FABRIC-2.md Section V: complete gap analysis of the Artemis home-

blocks/thumbdrive/PKI subsystem against the actual codebase

Systematic pass over every requirement gathered in Section U, each
verified directly against the tree rather than recalled. Organized by
area (physical block layout, USB hardware, drive/credential security,
console/VM binding, capsule signing/PKI, contributor trust tiers,
networking, dev workflow).

Found more than expected already exists and is reusable as-is: the
block address space and device-chain abstraction, sk_repl_idle()'s
empty trigger hook, capsule_birth_baby()'s on-demand VM spin-up,
acl_pinned's one-way-ratchet mechanism (a direct precedent for the
zuse one-way-burn requirement), arbitrary binary payload capsule
embedding (proven by the font capsule), the manifest's already-
documented Ed25519 anchor point, and the live-boot ISO pipeline.

Confirmed real, clearly-scoped gaps with nothing partially started:
identity-to-block-range derivation, the block migration state machine,
drive-map format, console/VM key binding, all signature/cert
verification code, magic-number content-type/foreign-drive detection,
the contributor trust-tier flag, QEMU monitor socket exposure, and the
install path.

Identifies the USB stack itself as the one hard, load-bearing
prerequisite gating almost every other gap from being testable at all,
even in QEMU -- the honest first-cut recommendation if a concrete next
milestone gets picked from this analysis.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

FABRIC-2.md

@@ -2737,3 +2737,168 @@ virtio-blk's build-out for comparison.
   refused unconditionally on a real bare-metal boot — i.e. signature enforcement could be
   QEMU-vs-real-hardware conditional rather than uniformly strict everywhere, which is plausibly
   *why* item 15's assumption was worth stating up front.
+
+---
+
+## V. Gap analysis — Artemis home-blocks/thumbdrive/PKI subsystem, 2026-08-22
+
+Systematic pass over everything gathered in Section U (plus the dev-workflow/networking/QEMU
+points from the same conversation), each checked directly against the current tree rather than
+recalled. Organized by area; each item states the requirement, its verified current status, the
+real gap, and any reusable precedent found along the way. **Nothing below is implemented.**
+This is a status snapshot to scope from, not a plan.
+
+### A. Physical block layout & logical/physical translation (Section U items 1-6)
+
+- **Block address space (RAM/RAMDRIVE/DISK tiers).** ✅ **Exists, real, working.**
+  `include/block_subsystem.h`: LBN 0-2047 FAST RAM, 2048-3071 RAMDRIVE (`KRD_MAX_BLOCKS`),
+  3072+ DISK IMG (virtio-blk). Already verified against the header during the original Section
+  U conversation.
+- **Chained-device attach mechanism (`blk_subsys_attach_device()`/
+  `blk_subsys_add_raw_device()`).** ✅ **Exists, real, working.** Each device gets a
+  `blk_dev_slot_t` node with its own heap-allocated BAM; this is the actual logical/physical
+  translation layer already asked about — LBN is already device-independent. "USB / future
+  devices (chained, including hot-attach/detach)" is in the header comment, unimplemented for
+  USB specifically but the chain mechanism itself doesn't need new design to accept a new
+  device type.
+- **Identity-derived (not attach-order-derived) block-range assignment.** ❌ **Absent.** No
+  code anywhere computes a block range from an identity/credential. The chain's current
+  behavior is pure attach-order. No derivation function exists even as a stub.
+- **Drive-carries-its-own-map.** ❌ **Absent.** No on-disk map format defined, nothing reads or
+  writes one.
+- **Bidirectional block migration between devices (the "state machine").** ❌ **Absent,
+  confirmed by direct search.** `grep`ed `block_subsystem.c`/`.h` for any move/migrate/promote/
+  demote-between-devices function — zero matches. A block, once assigned to a device's BAM
+  slot, has no code path to move to a different device's BAM slot. This is a real gap, not a
+  partially-built feature.
+- **`sk_repl_idle()` as the trigger hook.** ✅ **Confirmed empty and ready.** No-op placeholder,
+  called at `SK_IDLE_BEAT_INTERVAL` cadence, exactly as described when this was first raised
+  during the ACL-TTL investigation (Section R). Genuinely just needs a function body.
+
+### B. USB hardware (referenced throughout, the hard prerequisite)
+
+- ❌ **Zero USB code anywhere in the tree.** Repeated `grep -rli usb src/starkernel/` (and a
+  file-name search) both return nothing — no xHCI/EHCI/OHCI controller code, no USB core stack,
+  no mass-storage class driver, not even a stub. Only PCI enumeration
+  (`starkernel/pci/pci.c`) and virtio-blk (`starkernel/virtio/virtio_blk.c`) exist as device
+  drivers today. Every item in section A and C below that depends on a physical (or
+  QEMU-virtual) drive is inert without this. Sized, per earlier conversation, closer to the
+  virtio-blk build-out than a driver stub — this is the single largest gap in the whole
+  subsystem.
+- ❌ **No QEMU monitor/QMP socket exposed** in any of `Makefile.starkernel`'s QEMU
+  invocations (checked directly — no `-monitor`, no `-qmp` flag anywhere). Live hot-attach/
+  detach of a virtual thumb drive (the proposed dev-iteration workflow) isn't usable today;
+  needs one `-qmp unix:$SOCK,server=on,wait=off` line added, matching the existing serial
+  socket pattern (`-chardev socket,...,server=on,wait=off`). Small, not blocking, but real.
+
+### C. Drive/credential security (Section U items 7-8)
+
+- **Foreign-drive protection (magic-number signature check before write).** ❌ **No
+  drive-signature scheme exists**, but a real, working, directly-relevant precedent does:
+  `CAPSULE_MAGIC_PACK` (`tools/mkcapsule.c`) already identifies valid capsule containers by
+  magic number today. The *mechanism* (pack a magic + version into a fixed header field, check
+  it before trusting content) is proven in this codebase; it has just never been applied to a
+  block device's header.
+- **Zuse one-way burn.** ❌ **The credential-minting side is entirely unbuilt** —
+  `capsules/zuse.4th`'s `ZUSE-CERT-LO`/`ZUSE-CERT-HI` are literally `0 CONSTANT` placeholders,
+  not real key material (block's own comment: "FUTURE: Replace with thumbdrive Ed25519 PKI").
+  But the **one-way-ratchet mechanism itself already exists and is exactly the right shape**:
+  `acl_pinned` (`include/vm.h:346`, `src/word_source/acl_words.c`) is a genuine one-way flag —
+  "one-way ratchet: pinned is immutable," enforced in C (`if (e->acl_pinned) return;`
+  appears at every mutating ACL primitive), and FORTH code has no path to clear it once set.
+  This is a strong, direct precedent for "zuse minting is a one-way burn" — the exact
+  irreversibility semantics wanted already exist and are proven, just gating word-execution
+  permission today rather than credential minting.
+
+### D. Console/VM key-match binding (Section U item 9)
+
+- **On-demand VM spin-up (triggered by drive insertion, not just boot).** ✅ **Real,
+  callable mechanism exists.** `capsule_birth_baby()` (`src/starkernel/capsule/
+  capsule_birth.c`) is a genuine on-demand birth call, not a boot-only code path — it checks
+  `CAPSULE_BIRTH_ELIGIBLE` and can be invoked whenever, not only during the fixed boot
+  sequence. Spinning up a per-identity VM on USB insertion is a plausible new caller of an
+  existing mechanism, not a new VM-lifecycle subsystem.
+- **Console→VM key/lock attachment.** ❌ **No such binding exists.** `ACL-PIN`'s key-based
+  permission model (item 8's precedent, same mechanism) is structurally close but gates *word
+  execution*, not *console session ownership* — there's no concept anywhere in the console/REPL
+  code of a session being bound to one specific VM by credential match. `sk_repl_set_active_vm()`
+  exists (`starkernel/repl.c`) and lets the REPL target a specific VM, but nothing gates *which*
+  console is allowed to call it for *which* VM — it's a raw pointer-set, not an authenticated
+  bind. This is unbuilt and the "reuse ACL-PIN or build new" question from Section U item 9 is
+  still genuinely open.
+
+### E. Capsule signing / PKI (Section U items 10-14)
+
+- ❌ **No signature/certificate verification code exists anywhere** — confirmed, this was the
+  finding that opened this whole thread. `capsule birth`/`capsule_validate.c` verify the
+  XXHash64 content hash only (integrity, not authenticity).
+- ✅ **The manifest hook is real and was already the documented plan independent of this
+  conversation** — `tools/mkcapsule.c`'s own header: *"The xxHash64 column is the anchor for
+  future Ed25519 fingerprints (Phase 8)."* Nothing to build to make this true; it's a matter of
+  writing the Ed25519 verification code and a new manifest column, both net-new, but the
+  *anchor point* is already correct and doesn't need re-deciding.
+- ✅ **Arbitrary binary payload embedding (for the cert-as-capsule-blob idea) is proven,
+  working today** — the font capsule (`fonts:JetBrainsMono-Regular.ttf`) is live evidence, not
+  a hypothetical.
+- ❌ **Magic-number content-type detection.** Confirmed: content type is currently
+  extension-string-based only (`mkcapsule.c`: "file extension is preserved verbatim and is
+  meaningful only at load time"). No byte-sniffing exists. `CAPSULE_MAGIC_PACK` (see area C)
+  is the closest existing precedent for the *mechanism*, again not yet applied to this purpose.
+- **Per-capsule signing granularity.** Not a gap — this one follows for free once signing
+  exists, since it just needs to match the existing 1:1 hash-per-file granularity already in
+  `MANIFEST_AUTO.md`.
+
+### F. Contributor capsules / trust tiers (Section U items 15-18 + spitball)
+
+- ❌ **`capsules/contrib/` does not exist.** Confirmed — not in the current directory listing.
+- ❌ **No provenance/trust-tier flag exists.** Confirmed by direct search: no `FLAG_CONTRIB`
+  or equivalent anywhere in `mkcapsule.c`. Every non-Mama-init capsule today gets identical
+  `FLAG_PRODUCTION | FLAG_EXPERIMENT`, unconditionally, regardless of authorship.
+- All four spitballed directions (new flag bit, signature-authority tiers, block-namespace
+  sandboxing, QEMU-vs-real-hardware conditional enforcement) remain exactly that — spitballed,
+  none evaluated against the code, none chosen.
+
+### G. Networking / capsule distribution server (later in the same conversation)
+
+- ❌ **No network stack exists in any form** — no TCP/IP, no WiFi, nothing. Confirmed absent by
+  the same repo-wide search pattern used for USB (nothing under `src/starkernel/` matches).
+  Explicitly sequenced by Captain Bob as *after* the ACL/PKI/contrib work above, not concurrent
+  with it — this gap is expected and not being treated as a blocker for anything else in this
+  analysis.
+- The Nexus-style capsule server idea is pure concept at this point — no design has been
+  attempted yet beyond the name and its rough purpose (serve signed capsules, check against
+  the manifest metadata already discussed in area E).
+
+### H. Dev workflow (virtual thumb drives, live ISO)
+
+- **QEMU-virtual thumb drive for dev iteration (raw image file + `usb-storage`, hot-attach/
+  detach via monitor).** ❌ **Not set up.** No image file created, no launch-script changes
+  made, and per area B, the monitor socket needed to make attach/detach live-hot-pluggable
+  isn't exposed yet either. Directly blocked by area B's USB-stack gap regardless — the kernel
+  side has to exist before a virtual drive is useful for testing anything beyond QEMU-level
+  hotplug mechanics.
+- **Live-boot ISO ("try it").** ✅ **Already real and working** — `Makefile.starkernel`'s
+  `qemu` target builds a genuine bootable ISO (`xorriso`, El Torito) for amd64/aarch64 before
+  every launch; riscv64 builds a raw GPT/FAT32 disk image for the same purpose (no El Torito/
+  `-bios` support on riscv64 virt). CI already produces these as real artifacts
+  (`build-amd64-iso`, `build-aarch64-iso`, `build-riscv64-img`).
+- **Install path ("install it").** ❌ **Does not exist in any form.** No code writes the
+  kernel/OS itself to persistent storage; the one disk image currently in use
+  (`disk/artemis.img`) is content storage, never an install target.
+
+### Summary — what's real vs. what's still just direction
+
+**Solid, verified, reusable as-is:** block address space and device-chain abstraction (area A),
+`sk_repl_idle()` trigger hook (area A), `capsule_birth_baby()` on-demand VM spin-up (area D),
+`acl_pinned`'s one-way-ratchet mechanism (area C), arbitrary binary payload capsule embedding
+(area E), the manifest's Ed25519 anchor point (area E), the live-boot ISO pipeline (area H).
+
+**Real gaps, clearly scoped, nothing partially started:** identity→block-range derivation,
+block migration state machine, drive-map format, console/VM key binding, all signature/cert
+verification code, magic-number content-type/foreign-drive detection, contributor trust-tier
+flag, QEMU monitor socket exposure, install path.
+
+**The one hard, load-bearing prerequisite gating almost everything else from being testable
+at all, even in QEMU: the USB stack itself (area B).** Every other gap in areas A, C, D, and H
+either directly requires it or becomes untestable without it. This is the honest first-cut
+recommendation if a concrete next milestone gets picked from this analysis.