From 8b3e46fa550e0b7c9a9174563fbbe98b32bdc8bc Mon Sep 17 00:00:00 2001 From: Robert Allan James Date: Thu, 27 Aug 2026 14:03:42 -0400 Subject: [PATCH] FABRIC-3.md: scope WIREBIND (breadcrumb) and RUNCAP, add missing graph edges MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit WIREBIND traced against live capsule_birth_baby()/dispatch_init_forth() and found to have no real mechanism behind it yet -- depends on CERTVERIFY (identity-authentication) and a new RUNCAP mechanism for per-identity VM content, neither shown in the §E graph before now. Followed the thread into RUNCAP: capsule_birth_baby() is already generic, so RUNCAP needs only a heap-built single-entry capsule directory, not new birth machinery. Repurposes homeblocks_sig_t's now-dead blockmap_offset/blockmap_devblocks fields (per BMAPFMT, §F.4) to point at the identity's init source instead. Also captures a user-pool scope clarification: a thumbdrive is a user's pool by default, uncontested; FIRSTTOUCH's claim logic applies only to system-device extension. --- FABRIC-3.md | 103 ++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 99 insertions(+), 4 deletions(-) diff --git a/FABRIC-3.md b/FABRIC-3.md index dff5c33..1d7f7bf 100644 --- a/FABRIC-3.md +++ b/FABRIC-3.md @@ -126,14 +126,19 @@ decisions get added here, not to `FABRIC-2.md`. Follow the same discipline `FABR ### From FABRIC-2.md §X, Milestone 3 — Block subsystem extensions - [ ] Implement the CA-signed-cert verification path (Milestone 6 dependency — the cert chain - validator doesn't exist yet either). + 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.** - [ ] 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 one at `g.total_user_lbn` and write it back. *(Single-block relocation itself — the mechanism this would allocate ranges for — is done: `blk_subsys_relocate_block()`/ `RELOCATE-BLOCK`, `FABRIC-2.md`, commit `36d832f`. This item is about the identity→range - allocation that decides what to relocate blocks* into*, still unbuilt.)* + allocation that decides what to relocate blocks* into*, still unbuilt.)* **Scope clarified + 2026-08-27 (`FABRIC-3.md` §F.6, decision 3): a user's pool is their entire thumbdrive by + default (never contested) plus any system-resident device blocks they additionally claim, + first-come-first-served — this function only governs that second, system-side extension, + not the drive itself.** - [x] **SCOPED 2026-08-27 (FABRIC-3.md §F.4).** Design the on-drive block-map format (Section U item 4). Resolved as: no separate table — repurpose the existing, fully-wired-but- @@ -668,7 +673,10 @@ decisions get added here, not to `FABRIC-2.md`. Follow the same discipline `FABR - [ ] 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. + 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.** - [ ] 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 @@ -1320,7 +1328,11 @@ can't"):** - **How does thumbdrive content actually become a capsule at runtime?** `mkcapsule` only ever builds capsules at build time, baked into `capsule_generated.c` — nothing today constructs a capsule from data read off a live-attached device. This is new mechanism, not - a variation on anything that exists. + a variation on anything that exists. **SCOPED 2026-08-27, `FABRIC-3.md` §F.6**: no new + birth machinery needed — `capsule_birth_baby()` is already generic; construct a + self-contained heap-allocated single-entry directory (mirroring `kernel_main.c`'s own + heap-copy of the compile-time directory) and feed it straight in. Source-location-on-drive + and read-path details still open. - **Exact ACL "bumps and holes" comparison semantics.** Which specific ACL fields, compared how, constitute a console-to-VM match? Direction is settled (reuse ACL), the actual comparison logic is not designed. @@ -1438,6 +1450,8 @@ graph TD RUNCAP --> MINT HOTPLUG --> WIREBIND + CERTVERIFY -->|"post-identity-authentication" per M5 wording, SCOPED 2026-08-27 §F.5| WIREBIND + RUNCAP -->|no per-identity VM content until this exists, SCOPED 2026-08-27 §F.5| WIREBIND ACLKEY --> BINDSTEP WIREBIND --> BINDSTEP BINDSTEP --> DETACH @@ -1483,6 +1497,11 @@ finished). Dashed arrows = softer "gates/informs" relationships. a parallel track. - **Only `SSDSCOPE`, `ROUNDTRIP`, `POLYBLOCK`, and `PROMPTBUG` are genuinely standalone** — everything else in the pile connects to at least one other node. +- **`WIREBIND` was missing two real incoming edges** (found scoping it, §F.5): `CERTVERIFY` + and `RUNCAP` both gate it, not just `HOTPLUG`. Without a verified identity there's nothing + to bind to, and without `RUNCAP` there's no per-identity VM content to birth — today's + `capsule_birth_baby()` only runs fixed, build-time-baked capsules by name, so "spin up that + identity's VM" had no real mechanism behind it at all until this pass traced it. **Not yet done:** an ordered plan (which node to attack first, given the graph). Per Captain Bob's own framing, that's the next pass — "start asking and answering questions iteratively @@ -1652,6 +1671,82 @@ or stay C-only like `zuse_cert_seed`'s "no FORTH access" precedent; the actual r edit to `block_subsystem.h`/`.c` itself (this pass produced the field design, not the code change). +### F.5 — `WIREBIND` (breadcrumb only — followed into `RUNCAP` instead, 2026-08-27) + +Traced against the live code before asking anything: `capsule_birth_baby()` +(`capsule_birth.c:473-614`) only ever births a fixed, build-time-baked `(p)` capsule looked up +by name — `BIRTH`'s own mapping is literally `S" Artemis" → "artemis:init.4th"` +(`mama_forth_words.c:216`). The PERSONALITY stage — where a baby would load *its own* +per-identity content — is a confirmed no-op today: `dispatch_init_forth(new_vm)` +(`capsule_birth.c:605`) does nothing, with its own comment stating "per-VM block storage is +M9 scope; no-op until then." + +**Finding: the M5 punch-list wording — "spin up or re-attach *that identity's VM*" — has no +mechanism behind it yet.** Two real prerequisites were missing from the §E graph and are now +added: +- **`CERTVERIFY`** — M5's own wording calls this step "post-identity-authentication"; there's + nothing to bind an identity to without a verified identity first. **Decision: required, not + optional** — matches the literal M5 wording and avoids birthing VMs for unauthenticated + drives before any lock/key concept (`ACLKEY`/`BINDSTEP`) exists to protect them. +- **`RUNCAP`** — without it, "that identity's VM" can only ever mean the one generic, + same-for-everyone capsule that happens to exist at build time. Real per-identity content is + blocked on `RUNCAP` (or M9's per-VM block storage, a larger and further-out mechanism). + +**Working assumption recorded for whenever this node is actually scoped:** a `WIREBIND`- +triggered birth always creates a fresh VM (matches `capsule_birth_baby()`'s existing shape). +Recognizing a *returning* identity and re-attaching to a prior VM/session is `ROUNDTRIP`'s +question, not `WIREBIND`'s — deliberately not folded in here. + +**Not scoped further — by design.** Rather than decide `WIREBIND`'s generic-capsule shape in +the abstract, the pass followed the real blocker down into `RUNCAP` itself (§F.6). Revisit +`WIREBIND` once `CERTVERIFY` and `RUNCAP` both exist. + +### F.6 — `RUNCAP` (runtime capsule construction from thumbdrive content) + +Traced against `capsule.h`/`capsule_birth.h` before assuming new birth machinery was needed. +Two things, read directly from the code, changed the shape of this node: + +1. **`capsule_birth_baby()` is already generic** — it takes `dir`/`descs`/`names`/`arena` as + plain parameters; it is not wired to the compile-time `capsule_descriptors[]` global in any + way. `mkcapsule` sets `.desc_capacity = capsule_count` always (`mkcapsule.c:955`) — despite + `capsule.h`'s own comment calling this "fixed at compile time for **Phase A**" (implying + headroom for a later phase), there is zero spare capacity reserved today, and no + runtime-append mechanism exists into the baked-in directory. Not a blocker, though — +2. **...because `RUNCAP` doesn't need to touch the baked-in directory at all.** It can + construct its own self-contained, heap-allocated `CapsuleDirHeader` + one `CapsuleDesc` + + one `CapsuleNameEntry` + a small arena — the exact same shape `kernel_main.c:729-750` + already builds when it heap-copies the compile-time directory before Mama's own birth, just + sized for a single entry instead of the whole set — fill the arena with raw FORTH source + text read off the thumbdrive, and hand that straight to the existing, unmodified + `capsule_birth_baby()`. No directory-merge logic, no changes to the birth path itself. + +**Decisions made 2026-08-27:** + +1. **Mechanism: heap-built single-entry capsule directory, not baked-in-directory extension.** + Confirmed safe and minimal per the trace above. +2. **Location of the source content on the drive.** `homeblocks_sig_t`'s `blockmap_offset`/ + `blockmap_devblocks` fields are already dead weight per `BMAPFMT`'s decision (§F.4) that + ownership/ACL/state travel with `blk_meta_t`, not a centralized on-drive table. **Repurpose + those two fields** (rename to `identity_src_offset`/`identity_src_devblocks`) to point at + this identity's raw FORTH init/personality source instead of adding new fields — reuses + already-reserved header space, keeps `homeblocks_sig_t`'s byte budget untouched. (Comment + update in `homeblocks_sig.h` still owed when this is actually built, same as `F.4` already + flagged.) +3. **Scope of a user's pool — clarified 2026-08-27, corrects the framing this node started + from:** a user's pool is **their entire thumbdrive by default**, plus any system-resident + device blocks they additionally claim, first-come-first-served, plus the required metadata. + The thumbdrive itself is never contested — it's already theirs, no claiming logic needed + there. `FIRSTTOUCH`'s "claim a new range at `g.total_user_lbn`" logic (M3) applies only to + the *system*-device extension, not the drive itself. This simplifies the personality-source + question in decision 2 above: no allocation contention to resolve, just a pointer into the + drive's own metadata partition. + +**Not yet scoped (deferred within this node):** the exact read path (which forth-blocks within +the metadata partition, how `identity_src_devblocks` bounds a variable-length FORTH source); +whether the source is plain FORTH text authored once at mint time or something a user can edit +and have re-read on next attach; the interaction with `CERTVERIFY` (does verification gate +reading this content, or only gate the resulting birth). + ### D.5 — Scope expansion (2026-08-27): identity is common to every VM, not just users Surfaced while scoping `ACLKEY`, stated directly: *"the whole object is to deliver a