FABRIC-2.md Sections U/W/X: renumber milestones to match actual
execution order, physically reordered in the file Previously kept stable IDs with a separate "read this note for the real order" translation layer. Renumbered so the milestone numbers themselves read top-to-bottom in execution order and physically reordered the ### Milestone blocks in Section X to match -- no translation needed anymore. New order: 1=QEMU monitor/QMP socket, 2=USB hardware stack, 3=block subsystem extensions, 4=drive/credential security, 5=console/VM key-match binding, 6=PKI signing chain, 7=contributor capsules/trust tiers, 8=bare-metal USB boot (still second-to-last, not first -- QEMU-first per Captain Bob's explicit reinforcement), 9=networking (unchanged, still last). All cross- references between milestones (including Milestone 2's internal sub-item labels 2a-2h) updated to match throughout Sections U, W, and X. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Robert Allan James
co-authored by
Claude Sonnet 5
Claude Sonnet 5
parent
ef83ba46c8
commit
0008f19bbb
+83
-79
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user