FABRIC-3.md: retroactively check 11 stale-carried-forward items

Audited all 34 unchecked checklist lines against the actual codebase.
Checked off 11 that were already done -- most were completed in
FABRIC-2.md/FABRIC-3.md sections written after the item's own carry-
forward, never reconciled back to the original checkbox: the DoE
Stadium-substrate re-run (5.1), xHCI stall recovery (G.1), CERTVERIFY,
the whole BINDSTEP cluster (key/lock design, hotplug-to-birth wiring,
USE guard), and the Milestone 6 PKI generation/embedding/signing steps.
Each gets a RETROACTIVELY CHECKED annotation citing real file:line
evidence. One item (MANIFEST_AUTO.md signature column) investigated and
left unchecked on purpose -- the goal was met via a different file
(BLOCK_MAP.md's Signed column), not the one this item names.
The other 23 unchecked items were verified still genuinely open (several
require real hardware, not verifiable from code) and left untouched.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QgooKd5hJNtTYqB6CyK5f9
This commit is contained in:
Robert Allan James
2026-09-03 13:34:29 -04:00
co-authored by Claude Sonnet 5
parent 2b9fa02354
commit 403f53d056
+76 -22
View File
@@ -43,8 +43,15 @@ decisions get added here, not to `FABRIC-2.md`. Follow the same discipline `FABR
- [ ] **4.4s — `(user)` prompt segment.** Scoped, blocked, not started. Extends 4.4's prompt - [ ] **4.4s — `(user)` prompt segment.** Scoped, blocked, not started. Extends 4.4's prompt
format. *Refs (FABRIC.md):* §27.8, 4.4. format. *Refs (FABRIC.md):* §27.8, 4.4.
- [ ] **5.1 — Re-run the DoE on the new substrate.** A green POST suite is not evidence that - [x] **5.1 — Re-run the DoE on the new substrate.** A green POST suite is not evidence that
determinism holds under the Stadium migration — needs its own campaign. Not started. determinism holds under the Stadium migration — needs its own campaign. **RETROACTIVELY
CHECKED 2026-09-03: was already done before this document even opened.** `FABRIC-2.md` §M/§O
(2026-08-20) ran the stadium-relaunch campaign against the post-4.6 Stadium substrate — 9
cells (3 archs × 3 seeds), 4,320/4,320 rows captured, zero VM errors, zero `UNKNOWN WORD`
faults, raw logs and per-cell CSVs committed (`logs/20260820-*/`,
`experiments/bare_metal/runs/acl-rwt-20260820/`) — and its own text states directly: "this
satisfies item 5.1's own concern." A stale carry-forward into this document's Section A,
never reconciled against `FABRIC-2.md`'s own closure a few sections later.
### From FABRIC-2.md §D — Design questions still genuinely open ### From FABRIC-2.md §D — Design questions still genuinely open
@@ -127,7 +134,7 @@ decisions get added here, not to `FABRIC-2.md`. Follow the same discipline `FABR
same-session read. `blkio_usb.c` is read-write now; `read_only` flipped to `0`. Real hardware same-session read. `blkio_usb.c` is read-write now; `read_only` flipped to `0`. Real hardware
(Milestone 8) remains untested — QEMU-only so far. (Milestone 8) remains untested — QEMU-only so far.
- [ ] Implement basic error/stall recovery (CSW failure status, endpoint stall clear) — at - [x] Implement basic error/stall recovery (CSW failure status, endpoint stall clear) — at
minimum enough to not wedge the controller on a single bad transfer. **SCOPED 2026-08-27 minimum enough to not wedge the controller on a single bad transfer. **SCOPED 2026-08-27
(`FABRIC-3.md` §F.14)**: full BOT-spec recovery designed — new `STALL_ERROR` completion code, (`FABRIC-3.md` §F.14)**: full BOT-spec recovery designed — new `STALL_ERROR` completion code,
new xHCI Reset Endpoint + Set TR Dequeue Pointer commands, `CLEAR_FEATURE(ENDPOINT_HALT)` via new xHCI Reset Endpoint + Set TR Dequeue Pointer commands, `CLEAR_FEATURE(ENDPOINT_HALT)` via
@@ -135,14 +142,28 @@ decisions get added here, not to `FABRIC-2.md`. Follow the same discipline `FABR
second stall, bounded via a new retry counter mirroring `bot_tur_retries`'s own precedent. second stall, bounded via a new retry counter mirroring `bot_tur_retries`'s own precedent.
Real gap closed today: CSW status handling (PASS/FAILED/PHASE ERROR) already existed; nothing Real gap closed today: CSW status handling (PASS/FAILED/PHASE ERROR) already existed; nothing
distinguished a STALL specifically, and no recovery of any kind existed before this pass. distinguished a STALL specifically, and no recovery of any kind existed before this pass.
**RETROACTIVELY CHECKED 2026-09-03: built per this exact scope, see §G.1 below ("BUILT
2026-08-29").** `xhci.c` has the full path — `XHCI_COMPLETION_CODE_STALL_ERROR` handling,
`XHCI_CONN_AWAIT_RESET_ENDPOINT`/`AWAIT_SET_TR_DEQUEUE` states, `xhci_handle_bulk_stall()`,
`CLEAR_FEATURE(ENDPOINT_HALT)`, `XHCI_BOT_STALL_MAX_RECOVERIES` escalation — verified via a
clean QEMU boot regression on all three archs with the normal (non-stall) path byte-for-byte
unchanged. One honest residual gap, already flagged by §G.1 itself, not this checkbox's
concern: QEMU's `qemu-xhci` model cannot produce a real `STALL_ERROR`, so live
stall-injection-and-recover is unverifiable until real hardware (Milestone 8/v2.5.0) — a
physical-hardware limitation, not incomplete code.
### From FABRIC-2.md §X, Milestone 3 — Block subsystem extensions ### From FABRIC-2.md §X, Milestone 3 — Block subsystem extensions
- [ ] Implement the CA-signed-cert verification path (Milestone 6 dependency — the cert chain - [x] Implement the CA-signed-cert verification path (Milestone 6 dependency — the cert chain
validator doesn't exist yet either). **Now confirmed a hard prerequisite of `WIREBIND` too validator doesn't exist yet either). **Now confirmed a hard prerequisite of `WIREBIND` too
(`FABRIC-3.md` §F.5), not just an M3 item in isolation. SCOPED 2026-08-27 (§F.7)**: format (`FABRIC-3.md` §F.5), not just an M3 item in isolation. SCOPED 2026-08-27 (§F.7)**: format
and trust root decided (Zuse-signed X.509/DER cert, not the offline capsule-PKI chain); the and trust root decided (Zuse-signed X.509/DER cert, not the offline capsule-PKI chain); the
actual DER signature-extraction code is new work, not yet built. actual DER signature-extraction code is new work, not yet built. **RETROACTIVELY CHECKED
2026-09-03: built and wired.** `vm_identity_from_cert()` (`src/starkernel/capsule/
vm_identity.c:23`) calls `x509_verify_signature()` (`src/starkernel/crypto/
x509_ed25519.c:127`, a from-scratch DER walker), and is called live from
`capsule_wirebind_try_attach()` (`capsule_wirebind.c:72`), itself invoked from the real
hotplug path in `repl.c:240` — the full CERTVERIFY chain is real, not a stub.
- [ ] Implement the first-touch allocation function: given a verified identity pubkey and a - [ ] Implement the first-touch allocation function: given a verified identity pubkey and a
requested block count, either read an existing range from the drive's map or claim a new requested block count, either read an existing range from the drive's map or claim a new
@@ -695,27 +716,41 @@ decisions get added here, not to `FABRIC-2.md`. Follow the same discipline `FABR
### From FABRIC-2.md §X, Milestone 5 — Console/VM key-match binding ### From FABRIC-2.md §X, Milestone 5 — Console/VM key-match binding
- [ ] Settle the still-open question: reuse `ACL-PIN`/`acl_allow` directly, or build a - [x] Settle the still-open question: reuse `ACL-PIN`/`acl_allow` directly, or build a
separate key-matching primitive — `ACL-PIN` gates word execution specifically and nothing separate key-matching primitive — `ACL-PIN` gates word execution specifically and nothing
today gates console-session-to-VM ownership, so this decision needs to happen before any today gates console-session-to-VM ownership, so this decision needs to happen before any
code gets written here. code gets written here. **RETROACTIVELY CHECKED 2026-09-03: settled as "separate primitive,"
not `ACL-PIN` reuse** — `USE`'s BINDSTEP block does a live `VMIdentity` compare against the
currently-attached drive (`mama_forth_words.c:485-500`+), an entirely different mechanism
from word-level ACL, confirmed built (see the next item).
- [ ] Design the key/lock data shape (what the console presents, what the VM carries, how - [x] Design the key/lock data shape (what the console presents, what the VM carries, how
they're compared). they're compared). **RETROACTIVELY CHECKED 2026-09-03: `VMIdentity{owner_pubkey, installed}`
is the VM's lock (`include/starkernel/vm_identity.h`); the console's key is whatever's on
the currently-attached drive, read live via `homeblocks_sig_t` + `CERTVERIFY`
(`vm_identity_from_cert()`) and compared byte-for-byte in `mama_word_use()` — confirmed real,
not just designed.**
- [ ] Wire drive insertion (Milestone 2e's hotplug signal, post-identity-authentication) to a - [x] Wire drive insertion (Milestone 2e's hotplug signal, post-identity-authentication) to a
call into `capsule_birth_baby()` (confirmed a real, callable, on-demand birth path already) call into `capsule_birth_baby()` (confirmed a real, callable, on-demand birth path already)
to spin up or re-attach that identity's VM. **Traced 2026-08-27 (`FABRIC-3.md` §F.5): this to spin up or re-attach that identity's VM. **Traced 2026-08-27 (`FABRIC-3.md` §F.5): this
has no mechanism behind it yet — depends on both `CERTVERIFY` (identity-authentication) and has no mechanism behind it yet — depends on both `CERTVERIFY` (identity-authentication) and
a new `RUNCAP` mechanism (§F.6, scoped) for per-identity VM content, since a new `RUNCAP` mechanism (§F.6, scoped) for per-identity VM content, since
`capsule_birth_baby()` today only births fixed, build-time-baked capsules.** `capsule_birth_baby()` today only births fixed, build-time-baked capsules.** **RETROACTIVELY
CHECKED 2026-09-03: both dependencies are now built, and the wiring itself is real.**
`capsule_wirebind_try_attach()` (`capsule_wirebind.c:77`) runs on every drive attach
(`repl.c:240`), calls `CERTVERIFY` then `capsule_runcap_birth()`
(`capsule_runcap.c:22`) → `capsule_birth_baby()` — the full hotplug-to-birth chain, live.
- [ ] Implement the actual attach/bind step — extending `sk_repl_set_active_vm()` (confirmed - [x] Implement the actual attach/bind step — extending `sk_repl_set_active_vm()` (confirmed
to exist, currently an unguarded raw pointer-set) with the key-match check from above, so a to exist, currently an unguarded raw pointer-set) with the key-match check from above, so a
console can only bind to the one VM whose lock matches its key. **SCOPED 2026-08-27 console can only bind to the one VM whose lock matches its key. **SCOPED 2026-08-27
(`FABRIC-3.md` §F.9)**: real gate is `USE` (`mama_forth_words.c:430-480`), the live, (`FABRIC-3.md` §F.9)**: real gate is `USE` (`mama_forth_words.c:430-480`), the live,
already-working, currently-unguarded retarget word — check re-verifies the attached drive already-working, currently-unguarded retarget word — check re-verifies the attached drive
live on every call; `installed=0` VMs stay freely targetable. live on every call; `installed=0` VMs stay freely targetable. **RETROACTIVELY CHECKED
2026-09-03: confirmed built exactly as scoped** — `mama_word_use()`'s BINDSTEP block
(`mama_forth_words.c:485-500`+) does the live re-verify-and-compare, gated on
`((VM*)entry.vm_ptr)->identity.installed`.
- [ ] Implement detach behavior on console disconnect or VM teardown. **SCOPED 2026-08-27 - [ ] Implement detach behavior on console disconnect or VM teardown. **SCOPED 2026-08-27
(`FABRIC-3.md` §F.10)**: a new `EJECT` word — flush via the existing `blk_vm_flush_all()`, (`FABRIC-3.md` §F.10)**: a new `EJECT` word — flush via the existing `blk_vm_flush_all()`,
@@ -725,24 +760,43 @@ decisions get added here, not to `FABRIC-2.md`. Follow the same discipline `FABR
### From FABRIC-2.md §X, Milestone 6 — Kernel/capsule PKI signing chain ### From FABRIC-2.md §X, Milestone 6 — Kernel/capsule PKI signing chain
- [ ] Generate (offline, outside the kernel/repo entirely) the real root CA keypair — "stays - [x] Generate (offline, outside the kernel/repo entirely) the real root CA keypair — "stays
unrevocable," never embedded, never loaded by any kernel code. unrevocable," never embedded, never loaded by any kernel code. **RETROACTIVELY CHECKED
2026-09-03: never reconciled against its own later closure.** The checked bullet a few
paragraphs below ("Root CA + snakeoil intermediate generated 2026-08-26," one day after this
document opened) is this exact item's own completion — carried forward here as still-open
and never crossed off. Root CA lives at `/home/rajames/CLionProjects/lithosananke-ca/`,
outside this repo.
- [ ] Generate the "snakeoil" intermediate certificate, signed by that real root CA (this is - [x] Generate the "snakeoil" intermediate certificate, signed by that real root CA (this is
a real CA-signed intermediate, not a self-signed/untrusted cert despite the name — a real CA-signed intermediate, not a self-signed/untrusted cert despite the name —
"snakeoil" names its informal/private-project status). "snakeoil" names its informal/private-project status). **RETROACTIVELY CHECKED 2026-09-03:**
same closure as the item above — CA-signed, 10-year validity, `CA:TRUE, pathlen:0`, chain
verified via `openssl verify`.
- [ ] Embed the already-CA-signed snakeoil intermediate as a capsule blob at build time - [x] Embed the already-CA-signed snakeoil intermediate as a capsule blob at build time
(mechanically proven already via the font-capsule precedent — no new embedding (mechanically proven already via the font-capsule precedent — no new embedding
infrastructure needed, just a new payload). **Bootstrapping resolved: no kernel-boot-time infrastructure needed, just a new payload). **Bootstrapping resolved: no kernel-boot-time
verification of a hardcoded CA public key is needed at all** — trust is established once, verification of a hardcoded CA public key is needed at all** — trust is established once,
at build time, by whoever holds the real root CA and produces the build. at build time, by whoever holds the real root CA and produces the build. **RETROACTIVELY
CHECKED 2026-09-03:** `capsules/pki/snakeoil-intermediate.der` (418 bytes) exists, shows up
as capsule `pki:snakeoil-intermediate.der` in the generated capsule table.
- [ ] Add a signing step to the `mkcapsule` build tool (or a separate signing tool) that - [x] Add a signing step to the `mkcapsule` build tool (or a separate signing tool) that
produces a signature alongside each capsule's existing xxHash64. produces a signature alongside each capsule's existing xxHash64. **RETROACTIVELY CHECKED
2026-09-03:** confirmed live — `ed25519_verify()` wired into all three `capsule_validate()`
call sites in `capsule_birth.c` (lines 472, 551, 747), backed by `capsule_sig.c`. Every
capsule in `capsules/BLOCK_MAP.md`'s manifest shows `Signed: yes`.
- [ ] Extend `MANIFEST_AUTO.md`'s generation to add a signature-status column, matching the - [ ] Extend `MANIFEST_AUTO.md`'s generation to add a signature-status column, matching the
existing xxHash64 column's generation pattern. existing xxHash64 column's generation pattern. **INVESTIGATED 2026-09-03, left unchecked on
purpose — redirected, not done as literally worded.** This document's own later text (Phase
8 close-out) explicitly decided `MANIFEST_AUTO.md` is "stale/dead, not regenerated since
2026-07-05" and redirected this need to `capsules/BLOCK_MAP.md` instead, which now carries a
real `Signed` column (`| Capsule | Blocks claimed | xxHash64 | Signed |`, values `yes`/`no`
per capsule). The underlying goal is met; the specific file this item names deliberately
never was touched, so the box stays unchecked as a marker that this exact wording is now
moot rather than pretending the literal ask was fulfilled.
- [ ] Implement magic-number-based content-type detection (Section U item 14) — a shared - [ ] Implement magic-number-based content-type detection (Section U item 14) — a shared
primitive, also usable for Milestone 4's foreign-drive check. primitive, also usable for Milestone 4's foreign-drive check.