diff --git a/FABRIC-2.md b/FABRIC-2.md index 1bed29f..70c4843 100644 --- a/FABRIC-2.md +++ b/FABRIC-2.md @@ -2738,7 +2738,7 @@ virtio-blk's build-out for comparison. QEMU-vs-real-hardware conditional rather than uniformly strict everywhere, which is plausibly *why* item 15's assumption was worth stating up front. -**Fourth addendum — user-role tiers, and the snakeoil-cert answer to Milestone 7's +**Fourth addendum — user-role tiers, and the snakeoil-cert answer to Milestone 6's bootstrapping question, 2026-08-22:** 19. **Three distinct user-role tiers, not just "core" vs. "contrib."** (a) Builder+dev — @@ -2754,7 +2754,7 @@ bootstrapping question, 2026-08-22:** Captain Bob's own real root CA (a real root he controls, "snakeoil" here naming its informal/private-project status, not that it's untrusted or self-signed), and *that* signed intermediate is what gets embedded into each build and does the actual per-blob/ - per-capsule signing. This resolves Milestone 7's bootstrapping question precisely, not + per-capsule signing. This resolves Milestone 6's bootstrapping question precisely, not just "for dev/test": the CA public key never needs to get into the kernel at boot at all, because the intermediate cert is already CA-signed and embedded at build time — trust is established once, at build time, by whoever controls the root CA and produces the build, @@ -2765,10 +2765,10 @@ bootstrapping question, 2026-08-22:** 21. **Two paths into a build, nothing else.** A capsule or named blob makes it into a build only by (a) being signed via the chain above (the embedded, CA-signed intermediate cert), or (b) going through code review and inclusion in either the build or the single source - repo. This substantially simplifies Milestone 8's still-open trust-tier decision (item + repo. This substantially simplifies Milestone 7's still-open trust-tier decision (item 17's spitballed directions) — "in the reviewed source repo" is itself the trust signal for production-track content, rather than needing a separate signature-authority-tier scheme - layered on top. Worth revisiting Milestone 8's punch-list items against this before + layered on top. Worth revisiting Milestone 7's punch-list items against this before picking one of the four originally-spitballed directions; at least one of them (signature-authority tiers) may now be redundant with "repo inclusion already is the review gate." @@ -2988,21 +2988,25 @@ Secure Boot variance — the exact caveats this section already listed as real, reason to defer rather than a footnote) and isn't worth attempting until there's something real to boot *into*, not just an empty kernel proving UEFI boot works at all. -1. **USB hardware stack (Milestone 3) and the rest of the Artemis subsystem (Milestones - 4-8), built and validated entirely in QEMU** — QEMU's own USB hotplug emulation - (`device_add`/`device_del` via the QMP socket, Milestone 2) is sufficient to build and test +1. **USB hardware stack (Milestone 2) and the rest of the Artemis subsystem (Milestones + 3-6 — block subsystem extensions, drive/credential security, console/VM binding, PKI + signing chain), built and validated entirely in QEMU** — QEMU's own USB hotplug emulation + (`device_add`/`device_del` via the QMP socket, Milestone 1) is sufficient to build and test all of it without touching real hardware at all. This is now the actual near-term work. -2. Contributor capsules/trust tiers, still explicitly sequenced after the ACL/PKI work closes. -3. Networking (capsule distribution server, WiFi), still sequenced after that. -4. **Bare-metal boot from a physical USB stick (demo/"try it" mode) — moved to last, not - first.** Still confirmed not *technically* gated on the USB-hardware-driver work (booting - *from* USB is UEFI's job, not the kernel's), but no longer worth doing until there's a - working Artemis subsystem to actually demonstrate. **Added scope constraint for whenever - this does happen: the boot path must be UEFI-only — no legacy BIOS/MBR support, no GRUB2 - or any other bootloader in the chain.** The existing `starkernel_loader.efi` is meant to be - the entire boot path, generic and minimal, not one stage in a longer chain. Two 64GB - SanDisk drives remain on hand and available whenever this gets picked back up; one - currently carries a Kubuntu 26.04-era live ISO, re-flashable without loss. +2. Contributor capsules/trust tiers (Milestone 7), still explicitly sequenced after the + ACL/PKI work closes. +3. **Bare-metal boot from a physical USB stick (Milestone 8, demo/"try it" mode) — moved to + second-to-last, not first.** Still confirmed not *technically* gated on the + USB-hardware-driver work (booting *from* USB is UEFI's job, not the kernel's), but no + longer worth doing until there's a working Artemis subsystem to actually demonstrate. + **Added scope constraint for whenever this does happen: the boot path must be UEFI-only — + no legacy BIOS/MBR support, no GRUB2 or any other bootloader in the chain.** The existing + `starkernel_loader.efi` is meant to be the entire boot path, generic and minimal, not one + stage in a longer chain. Two 64GB SanDisk drives remain on hand and available whenever this + gets picked back up; one currently carries a Kubuntu 26.04-era live ISO, re-flashable + without loss. +4. Networking (capsule distribution server, WiFi — Milestone 9), still sequenced last, after + everything above. Not started: no code, no capsule work, no hardware testing yet. This section exists so a future session (or Captain Bob re-reading cold) gets the whole shape in one read, rather than @@ -3017,54 +3021,18 @@ task breakdown only. Each milestone is independently checkable off; sub-items wi milestone are ordered (later items generally depend on earlier ones in the same milestone unless noted). `[ ]` = not started, matching this file's existing convention (Section F). Where a task genuinely needs spec research before it can even be scoped precisely (mostly in -Milestone 3, USB hardware), the research step is its own punch-list item rather than skipped. +Milestone 2, USB hardware), the research step is its own punch-list item rather than skipped. -**Execution order — corrected same day, see Section W's sequencing update.** Milestone -numbers below are stable IDs (kept as originally assigned so cross-references between -milestones stay valid), *not* execution order. Real-hardware boot (Milestone 1) moved to -**last** — build and validate Artemis entirely in QEMU first. Actual order to work through: -**2 → 3 → 4 → 5 → 6 → 7 → 8 → 1**, with Milestone 9 (networking) deferred past all of them per -its own section below. +**Renumbered to match execution order, 2026-08-22** (originally drafted in a different order, +then corrected same day, then renumbered so the milestone numbers themselves read top to +bottom in the order to actually work through — no more separate "read this note to know the +real order" translation needed). Real-hardware boot is Milestone 8, deliberately second to +last, not first — build and validate the whole Artemis subsystem in QEMU before touching real +hardware at all. Networking (Milestone 9) stays last, deferred past everything else. -### Milestone 1 — Bare-metal boot from physical USB (demo/"try it" mode) +### Milestone 1 — QEMU monitor/QMP socket (small, unblocks dev-iteration workflow) -**Deferred to last, not first — see the execution-order note above.** Technically not gated -on any milestone below (booting from USB is UEFI's job, not the kernel's), but deliberately -not attempted until Milestones 2-8 give it something real to demonstrate; real-hardware boot -is "difficult and lots of blind guesswork" and not worth the detour yet. **Scope constraint -for whenever this resumes: UEFI-only boot path, no legacy BIOS/MBR support, no GRUB2 or any -other bootloader in the chain** — `starkernel_loader.efi` is meant to be the entire boot path, -generic and minimal, not one stage in a longer one. - -- [ ] Confirm which physical machine will receive the first real-hardware boot test (CPU - arch — amd64 assumed given the SanDisk drives on hand, but confirm) -- [ ] Build a fresh `starkernel.iso` via `make -f Makefile.starkernel ARCH=amd64 clean` + - the ISO-build step (already runs as part of `qemu` target — confirm it can be invoked - standalone without also launching QEMU, or just let the `qemu` target build it and - Ctrl-C before the QEMU launch line) -- [ ] Identify the exact block device path for the target USB drive on the host doing the - flashing (`lsblk`/`dmesg` after insertion — care needed, wrong device = data loss on - the wrong disk) -- [ ] `dd if=build/amd64/kernel/starkernel.iso of=/dev/sdX bs=4M status=progress` (or - equivalent) — confirm `dd` is the right tool for an El Torito ISO vs. needing - `isohybrid` or similar preprocessing first (open question, not yet verified either - way) -- [ ] Physically boot the real machine from the flashed drive (BIOS/UEFI boot-order menu, - Secure Boot may need disabling — unknown until tried, per Section W's caveat) -- [ ] Capture what happens with no serial-socket log available (real hardware has no - `qemu-serial-*.sock` to `socat` into) — decide the observation method: onboard - framebuffer/console output only, or a real serial cable to another machine, or nothing - beyond "did it reach `ok>`" -- [ ] Confirm POST reaches the same 1012/0/0 result on real hardware as every QEMU - acceptance run this session -- [ ] Confirm `ok>` prompt is reachable and a basic command (e.g. `HEARTBEAT-TICKS@ .`) works - identically to QEMU -- [ ] Document the result (pass/fail, and if fail, what diverged from QEMU) — first real - external validation this project has ever had outside QEMU TCG emulation - -### Milestone 2 — QEMU monitor/QMP socket (small, unblocks dev-iteration workflow) - -Independent of Milestone 1; useful before Milestone 3's virtual-drive testing starts. +Independent of Milestone 8; useful before Milestone 2's virtual-drive testing starts. - [ ] Add `-qmp unix:$QMP_SOCK,server=on,wait=off` to each arch's QEMU invocation in `Makefile.starkernel`, matching the existing `-chardev socket,id=cserial,...` pattern @@ -3077,9 +3045,9 @@ Independent of Milestone 1; useful before Milestone 3's virtual-drive testing st HMP (`-monitor`) is simpler to drive by hand via `socat`, QMP is more scriptable but needs the capabilities handshake first) - [ ] Confirm `device_add`/`device_del` works against a trivial device (not USB yet — prove - the mechanism itself first with something simple) before relying on it for Milestone 3 + the mechanism itself first with something simple) before relying on it for Milestone 2 -### Milestone 3 — USB hardware stack (the hard prerequisite, most granular breakdown) +### Milestone 2 — USB hardware stack (the hard prerequisite, most granular breakdown) Nothing in Section U/V/W's home-blocks thread is testable past this point without it. Ordered roughly bottom-up: PCI discovery → controller bring-up → command/event rings → port/hotplug @@ -3168,15 +3136,15 @@ detection → device enumeration → mass-storage class → read/write. - [ ] Wire a working USB MSC device into `blk_subsys_attach_device()` (or `blk_subsys_add_raw_device()`, whichever fits — confirm which, since USB is persistent+removable, a hybrid of the two existing categories) — this is the point - where Milestone 3's work actually becomes visible to everything in Section U/V's + where Milestone 2's work actually becomes visible to everything in Section U/V's block-layout design - [ ] Confirm a plugged-in USB drive shows up in the LBN chain at the expected offset - (today: attach-order-based, per Section V area A — item below in Milestone 4 changes + (today: attach-order-based, per Section V area A — item below in Milestone 3 changes this to identity-derived) -### Milestone 4 — Block subsystem extensions (Section U items 3-6, Section V area A) +### Milestone 3 — Block subsystem extensions (Section U items 3-6, Section V area A) -Depends on Milestone 3 existing (needs a real device to test against, though the +Depends on Milestone 2 existing (needs a real device to test against, though the identity→range derivation logic itself could be unit-tested against the existing RAM/ RAMDRIVE/DISK devices first without waiting for USB). @@ -3198,12 +3166,12 @@ RAMDRIVE/DISK devices first without waiting for USB). between two attached devices) - [ ] Implement the `sk_repl_idle()` body — the cheap "anything dirty? no? done" check (Section V confirmed this hook is empty and ready right now, doesn't even need - Milestone 3 to be written, only to be *tested end to end*) + Milestone 2 to be written, only to be *tested end to end*) - [ ] Decide and implement unclean-removal handling (Section U's explicitly flagged open question — never answered) — at minimum, detect a mid-flush disconnect via - Milestone 3e's disconnect signal and decide what state that leaves affected blocks in + Milestone 2e's disconnect signal and decide what state that leaves affected blocks in -### Milestone 5 — Drive/credential security (Section U items 7-8, Section V area C) +### Milestone 4 — Drive/credential security (Section U items 7-8, Section V area C) - [ ] Design the home-blocks drive signature format (Section U item 7) — reusing `CAPSULE_MAGIC_PACK`'s pattern (magic + version in a fixed header field) as the @@ -3218,7 +3186,7 @@ RAMDRIVE/DISK devices first without waiting for USB). (the credential isn't a dictionary word, so the existing bit may not directly apply — open question, not yet resolved) -### Milestone 6 — Console/VM key-match binding (Section U item 9, Section V area D) +### Milestone 5 — Console/VM key-match binding (Section U item 9, Section V area D) - [ ] Settle the still-open question from Section U/V: reuse `ACL-PIN`/`acl_allow` directly, or build a separate key-matching primitive — Section V's finding was that `ACL-PIN` @@ -3226,7 +3194,7 @@ RAMDRIVE/DISK devices first without waiting for USB). ownership, so this decision needs to happen before any code gets written here - [ ] Design the key/lock data shape (what the console presents, what the VM carries, how they're compared) -- [ ] Wire drive insertion (Milestone 3e's hotplug signal, post-identity-authentication) to +- [ ] Wire drive insertion (Milestone 2e's hotplug signal, post-identity-authentication) to a call into `capsule_birth_baby()` (Section V confirmed this is a real, callable, on-demand birth path already) to spin up or re-attach that identity's VM - [ ] Implement the actual attach/bind step — extending `sk_repl_set_active_vm()` (confirmed @@ -3234,7 +3202,7 @@ RAMDRIVE/DISK devices first without waiting for USB). so a console can only bind to the one VM whose lock matches its key - [ ] Implement detach behavior on console disconnect or VM teardown -### Milestone 7 — Kernel/capsule PKI signing chain (Section U items 10-14, Section V area E) +### Milestone 6 — Kernel/capsule PKI signing chain (Section U items 10-14, Section V area E) - [ ] Generate (offline, outside the kernel/repo entirely) the real root CA keypair — "stays unrevocable," never embedded, never loaded by any kernel code @@ -3255,11 +3223,11 @@ RAMDRIVE/DISK devices first without waiting for USB). - [ ] Extend `MANIFEST_AUTO.md`'s generation to add a signature-status column, matching the existing xxHash64 column's generation pattern - [ ] Implement magic-number-based content-type detection (Section U item 14) — a shared - primitive, per Section V, also usable for Milestone 5's foreign-drive check + primitive, per Section V, also usable for Milestone 4's foreign-drive check -### Milestone 8 — Contributor capsules / trust tiers (Section U items 15-18, Section V area F) +### Milestone 7 — Contributor capsules / trust tiers (Section U items 15-18, Section V area F) -Explicitly sequenced after Milestone 7 closes. +Explicitly sequenced after Milestone 6 closes. - [ ] Create the `capsules/contrib/` directory (mechanically trivial, matches existing subdirectory convention — the directory itself is not the work, see below) @@ -3273,6 +3241,42 @@ Explicitly sequenced after Milestone 7 closes. detection logic to also reject a `contrib/`-path capsule claiming blocks outside its reserved range +### Milestone 8 — Bare-metal boot from physical USB (demo/"try it" mode) + +**Deferred to last, not first — see the execution-order note above.** Technically not gated +on any milestone below (booting from USB is UEFI's job, not the kernel's), but deliberately +not attempted until Milestones 2-8 give it something real to demonstrate; real-hardware boot +is "difficult and lots of blind guesswork" and not worth the detour yet. **Scope constraint +for whenever this resumes: UEFI-only boot path, no legacy BIOS/MBR support, no GRUB2 or any +other bootloader in the chain** — `starkernel_loader.efi` is meant to be the entire boot path, +generic and minimal, not one stage in a longer one. + +- [ ] Confirm which physical machine will receive the first real-hardware boot test (CPU + arch — amd64 assumed given the SanDisk drives on hand, but confirm) +- [ ] Build a fresh `starkernel.iso` via `make -f Makefile.starkernel ARCH=amd64 clean` + + the ISO-build step (already runs as part of `qemu` target — confirm it can be invoked + standalone without also launching QEMU, or just let the `qemu` target build it and + Ctrl-C before the QEMU launch line) +- [ ] Identify the exact block device path for the target USB drive on the host doing the + flashing (`lsblk`/`dmesg` after insertion — care needed, wrong device = data loss on + the wrong disk) +- [ ] `dd if=build/amd64/kernel/starkernel.iso of=/dev/sdX bs=4M status=progress` (or + equivalent) — confirm `dd` is the right tool for an El Torito ISO vs. needing + `isohybrid` or similar preprocessing first (open question, not yet verified either + way) +- [ ] Physically boot the real machine from the flashed drive (BIOS/UEFI boot-order menu, + Secure Boot may need disabling — unknown until tried, per Section W's caveat) +- [ ] Capture what happens with no serial-socket log available (real hardware has no + `qemu-serial-*.sock` to `socat` into) — decide the observation method: onboard + framebuffer/console output only, or a real serial cable to another machine, or nothing + beyond "did it reach `ok>`" +- [ ] Confirm POST reaches the same 1012/0/0 result on real hardware as every QEMU + acceptance run this session +- [ ] Confirm `ok>` prompt is reachable and a basic command (e.g. `HEARTBEAT-TICKS@ .`) works + identically to QEMU +- [ ] Document the result (pass/fail, and if fail, what diverged from QEMU) — first real + external validation this project has ever had outside QEMU TCG emulation + ### Milestone 9 — Networking / capsule distribution server Explicitly sequenced last, after everything above. Deliberately not broken down further here @@ -3280,4 +3284,4 @@ Explicitly sequenced last, after everything above. Deliberately not broken down the name and its rough purpose." Punch-listing this in real detail before Milestones 1-8 land would be premature relative to Captain Bob's own stated sequencing. -- [ ] (Deferred) Revisit and punch-list this milestone once Milestone 8 closes, not before +- [ ] (Deferred) Revisit and punch-list this milestone once Milestone 7 closes, not before