From 403f53d0569587046d473921ad7c91f9c0583df1 Mon Sep 17 00:00:00 2001 From: Robert Allan James Date: Thu, 3 Sep 2026 13:34:29 -0400 Subject: [PATCH] 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 Claude-Session: https://claude.ai/code/session_01QgooKd5hJNtTYqB6CyK5f9 --- FABRIC-3.md | 98 +++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 76 insertions(+), 22 deletions(-) diff --git a/FABRIC-3.md b/FABRIC-3.md index 46d61c8..bcb7feb 100644 --- a/FABRIC-3.md +++ b/FABRIC-3.md @@ -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 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 - determinism holds under the Stadium migration — needs its own campaign. Not started. +- [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. **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 @@ -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 (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 (`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 @@ -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. 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. + **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 -- [ ] 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 (`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 - 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 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 -- [ ] 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 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 - they're compared). +- [x] Design the key/lock data shape (what the console presents, what the VM carries, how + 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) 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 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 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, 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 (`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 -- [ ] Generate (offline, outside the kernel/repo entirely) the real root CA keypair — "stays - unrevocable," never embedded, never loaded by any kernel code. +- [x] Generate (offline, outside the kernel/repo entirely) the real root CA keypair — "stays + 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 — - "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 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, - 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 - produces a signature alongside each capsule's existing xxHash64. +- [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. **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 - 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 primitive, also usable for Milestone 4's foreign-drive check.