diff --git a/FABRIC-2.md b/FABRIC-2.md index fa25611..c8253b7 100644 --- a/FABRIC-2.md +++ b/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.