LithosAnanake/docs/v4.0.0/plans/2026-10-26-engine-step4-identity-gate.md

ENGINE Step 4, ahead of Part A: the identity gate on v4 — Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:executing-plans (Captain Bob prefers native execution). Steps use checkbox (- [ ]) syntax for tracking.

Goal: On bare metal, v4 does what v3 does about identity before its prompt: with no identity drive the system is headless, with no prompt; when Zuse's minted thumbdrive is attached the kernel recognises it, and only then is there a console. Pulling the drive ends the session and the system goes headless again; putting it back brings the prompt back.

Why now (Captain Bob, 2026-10-26): "Gate first." Step 4's work goes ahead "only if zuse thumbdrive is attached so you have zuse. no identity thumb drive equals headless. when a thumb drive is inserted, only then is there an identity and a console" (2026-10-20, ENGINE.md §2). Today the v4 boot cannot meet that: sk_v4_run() (kernel_main.c:580) never returns, and it runs before USB bring-up (:823), the heartbeat (:915) and the headless wait (:1927), so a drive attached to a v4 boot is never read. The drive exists: disk/zuse-scratch/ (1f157e97), a minted Zuse pair.

Spec: ENGINE.md §2 (the rulings of 2026-10-20, the identity gate), MACHINE.md §5.1, the step 4 plan (2026-10-20-engine-step4-node-in-the-vms-place.md, "The identity gate"), V3-PARITY.md §1 rows 11 and 12.

What v3 does (read 2026-10-26, kernel_main.c, repl.c, capsule_zuse_boot.c)

1. After POST and the devices: pci_init, entropy, Artemis's virtio disk attached, and capsule_zuse_boot_load_root_pubkey() reads Zuse's public key from the genesis marker in the disk's metadata fence (blk_meta_zone_read(0)).
2. Every xHCI controller is found and brought up (xhci_find_and_map, xhci_bringup); a drive already in a port is enumerated by the bring-up's port scan.
3. The timer starts, interrupts are enabled ("Heartbeat running.").
4. sk_repl_headless_wait(): no banner, no prompt, no input. Every 100 ticks (sk_repl_idle): xhci_poll_events(); for each mass-storage device whose attach is pending, blkio_usb_open_msc(), then homeblocks_sig_check(); the device is given to the block subsystem (in v3 by a round trip through the Artemis VM and kernel-Hermes, ending in BLK-ATTACH-ACK on Hera); then capsule_zuse_boot_try_attach():
   • genesis marker present and the drive's identity record (magic, version, CRC-64) carries the marker's public key: "Zuse: identity confirmed from attached thumbdrive"; the cert is installed (one-way), and ACL-ZUSE-BOOT sets Hera's zuse_session;
   • no marker and a blank drive: genesis — Zuse is minted onto the drive and the marker written to the disk's fence;
   • anything else: nothing. The wait ends when sk_console_identity_present(): Zuse's session, or a WIREBIND user.
5. The banner, then sk_repl_run(), which re-checks identity before every prompt and while it waits for a line with nothing typed; when no one is attached it goes back to the headless wait. A drive pulled out: blk_subsys_detach_device(), capsule_zuse_boot_logout() ("Zuse: session ended -- reattach to re-authenticate").

What v4 does instead (Q1 ruled: Hera, Hermes, Artemis are kernel functions)

The same steps, done by the kernel for the v4 boot, with no v3 VM behind them:

• Artemis is the kernel's, so the kernel gives an attached drive to the block subsystem itself (blk_subsys_attach_device), with no VM round trip.
• Zuse's state is the kernel's, held for the first node, Hera: session, cert installed (one-way), root public key. Not in the node's memory and not in a v3 VM.
• The prompt loop in sk_v4_run() re-checks identity as sk_repl_run() does.

Decisions for Captain Bob

RULED 2026-10-26 (Captain Bob): D1 to D4 as recommended — split the file; recognise only; [zuse@Hera] ok> now; the minted pair the QEMU default.

D1. The identity check without a VM. capsule_zuse_boot_try_attach() takes Hera's VM * and ends in vm_interpret(mama_vm, "ACL-ZUSE-BOOT"); its readers (genesis_marker_read, read_devblock, the identity-record checks) are static. Recommend: split capsule_zuse_boot.c into a check that needs no VM — given the device and its signature result, it says "Zuse's drive", "genesis-eligible" or "not hers" and hands back her seed and public key — and v3's try_attach, which calls it and does the rest exactly as now. v4 calls the same check. One copy of code that handles Zuse's private key. Cost: it is a change to a file on v3's path (the plan's rule is "nothing in v3's own path changes"), with v3's behaviour unchanged; v3 is not part of acceptance, so that is shown by one system=v3 boot with the minted pair ("identity confirmed", [zuse@Hera] ok>). If not: a v4 copy of the check, beside v3's, until v3 leaves.

D2. Genesis on v4. v3 mints Zuse onto a blank drive when the disk has no marker. That writes the marker to Artemis's disk, and the v4 boot does not write the disk until the owner says it may (sk_v4_block_chain's comment; Phase 5). Recommend: the gate recognises a minted Zuse only. On v4 a blank pair stays headless, and says so once ("Zuse: no genesis on this disk -- the system stays headless"). Genesis on v4 comes with Artemis's writes (Phase 5).

D3. The prompt. v3's is [zuse@Hera] ok>: the console's line prefix, from the VM name and the user. Banner and prompt are row 12, Phase 6. Recommend: in this gate, the console's VM name is set to Hera and its user prefix says zuse while her session holds, so the prompt is [zuse@Hera] ok> as v3's, from the moment there is an identity. The banner stays Phase 6. Nothing before the first prompt changes. If not: ok> as today, and the prefix with row 12.

D4. Which disks QEMU boots with. The gate makes a bare make ARCH=<isa> clean qemu, with today's defaults (the blank disk/artemis.img and disk/thumbdrives/zuse-thumb-ident.img), stay headless, so no acceptance boot reaches ok>. Recommend: kernel/Makefile's defaults become the minted pair, disk/zuse-scratch/artemis.img and zuse-thumb-ident.img. The acceptance rule to put the disk images back as committed before each ISA then applies to them. .claude/CLAUDE.md says so. If not: every acceptance boot passes ARTDISK= and ZUSEDISK= copies, and .claude/CLAUDE.md says that instead.

Not in this gate: WIREBIND identities as a way in (Phase 6, with the user's VM born from the drive), EJECT, the banner, ACL-ZUSE-BOOT and god-mode (Phase 4, ACL on v4), Artemis's writes and genesis (Phase 5).

Global Constraints

As the step 4 plan's, and:

• No kernel unit tests; the tests are QEMU sessions typed to over the serial socket and driven over QMP (the serial and QMP sockets kernel/Makefile's qemu goal opens), each written before the change and seen to fail.
• The drives attached by QMP during a session are copies of disk/zuse-scratch/, in a scratch directory; the committed pair is never booted directly.

Tasks

Task G0: Record

• Step 1: This plan; in the step 4 plan, "The identity gate" points here and the Phases table puts the gate before Part A; ENGINE.md §2 one line saying the gate is built first.
• Step 2: Commit docs(v4): the identity gate before Part A.

Task G1: The check without a VM (D1)

Files: kernel/src/capsule/capsule_zuse_boot.c, kernel/include/starkernel/capsule_zuse_boot.h.

Interfaces: Produces zuse_drive_t capsule_zuse_boot_check(struct blkio_dev *dev, homeblocks_sig_result_t sig_rc, const homeblocks_sig_t *sig, uint8_t seed[32], uint8_t pubkey[32]); with ZUSE_DRIVE_HERS, ZUSE_DRIVE_GENESIS (no marker, blank drive), ZUSE_DRIVE_NOT_HERS; int capsule_zuse_boot_root_pubkey(uint8_t pubkey[32]); (0 = the marker read and checked). try_attach and load_root_pubkey call them; their behaviour and messages do not change.

• Step 1: Failing test: a system=v3 amd64 boot with copies of the minted pair, before the change: record "Zuse: identity confirmed from attached thumbdrive" and [zuse@Hera] ok> (the reference; this step is the yardstick, not a failure).
• Step 2: Split as above.
• Step 3: The same system=v3 boot after: the same lines. A blank copy pair: "Zuse: genesis minted onto attached thumbdrive", as before.
• Step 4: Commit with the two logs.

Task G2: The gate on the v4 boot

Files: kernel/src/v4/sk_v4.c, kernel/include/starkernel/v4/sk_v4.h, kernel/src/kernel_main.c (the v4 branch only: what sk_v4_run is given), a new kernel/src/v4/sk_v4_identity.c + kernel/include/starkernel/v4/sk_v4_identity.h (Zuse's state for Hera; the idle beat's USB servicing for the v4 boot).

Interfaces: Consumes G1. sk_v4_run(chain) keeps its signature; after chain() it: loads the root public key; brings up every xHCI controller; starts the timer and enables interrupts as v3 does ("Starting heartbeat...", "Heartbeat running."); waits headless; then the prompt loop.

• Step 1: Failing tests (amd64 sessions, before the change):
  • gate_headless: booted with no Zuse drive (ZUSEDISK=), the log has POST: PASSED and no ok> within 60 s of it. Today: FAIL (ok> appears).
  • gate_zuse: booted with copies of the minted pair: "Zuse: identity confirmed from attached thumbdrive", then [zuse@Hera] ok> (D3), and 3 4 + . answers 7 ok. Today: FAIL.
  • gate_hotplug: booted with no Zuse drive; QMP blockdev-add + device_add usb-storage of a copy of the minted Zuse drive → identity confirmed → prompt; a line typed; device_del → "Zuse: session ended -- reattach to re-authenticate", no further ok> for 30 s; added again → prompt. Today: FAIL.
• Step 2: Build the gate.
• Step 3: The three sessions pass; the v4 suite passes (make -C v4 test test-32 sanitize hosted-check, unchanged: nothing in v4/ changes).
• Step 4: D4 as ruled (kernel/Makefile defaults and .claude/CLAUDE.md, or the command line).
• Step 5: Full acceptance: three clean qemu boots with the minted pair, to [zuse@Hera] ok>, PARITY:V4_POST ... fail=0, POST: PASSED, dict_hash unchanged and equal (0xfec8c47cfc6f437f, word_count 317: nothing on the node changes); gate_hotplug on aarch64 and riscv64 too; make -C v4 test-32, 0 failures. Commit feat(v4): no identity drive, headless; Zuse's drive, a console, then the logs.

Review Focus

1. A drive pulled mid-line: the line in hand finishes; the next prompt is not shown.
2. A drive that is not Zuse's (another identity, a blank one, a foreign one): no prompt, no message beyond v3's.
3. Zuse's seed is read into kernel memory only, never into a node's memory, and the cert is installed once (one-way, as vm_zuse_cert_install).
4. The idle beat while the node runs a line: USB servicing happens only at the prompt or in the headless wait, never while the node is mid-line (v3's g_mama_interpreting reason).
5. All three ISAs: hot attach and detach on aarch64 and riscv64, not only amd64.