diff --git a/FABRIC-3.md b/FABRIC-3.md index 1af54d0..28ed9bf 100644 --- a/FABRIC-3.md +++ b/FABRIC-3.md @@ -3918,3 +3918,82 @@ as historical record (each item already carries its own closure annotation inlin **Remaining genuinely open design question, after this pass**: none — every design-level question from this list is now closed. What's left is implementation (items 4–9) and intentional deferrals (10–11). + +### H.12 — Implementation punch list (2026-09-03) + +One coding task per item, not a concept per item — each followed by the mandatory +amd64/aarch64/riscv64 boot acceptance test (this document's only valid acceptance criterion, +see the top-level CLAUDE.md). Grounded against live code, not the earlier design captures' +assumptions — two corrections surfaced while building this list, both noted inline below. + +**Correction 1**: `stadium_birth_hermes()`/`_artemis()` (§H.11 item 4) don't need writing from +scratch. `capsule_birth.c`'s generic admission path (~lines 574–602, used for every VM birth +today) already admits every born VM as a Stadium patron — it's just hardcoded to admit them +**unpinned** (`vm_patron.flags = 0`, with a comment explicitly noting "unpinned... unlike +Hera"). The real task is making that existing path pin Hera/Hermes/Artemis specifically, +leaving ordinary/user VMs unpinned as they already correctly are. + +**Correction 2**: `VMIdentity` (`include/starkernel/vm_identity.h`) already exists, fully +built — `owner_pubkey[32]` + `installed` + `acl_caps` (capability bitmask), the VM-card shape +from H.4, plus more. `Session.identity` should be a `VMIdentity`, not a new type. Its own doc +comment confirms Hera/Hermes/Artemis have no installed identity yet ("before D.5's per-VM- +identity work lands") — wiring real identities into them is part of this refactor's remaining +work, not new invention. + +**Phase 1 — Session struct + pin-authority choke point** +1. `include/starkernel/session.h`: `Session{vm_id (VMUuid), pinned (int), parent (VMUuid), + name (fixed buffer), identity (VMIdentity, embedded)}`. Type only, no logic. +2. `src/starkernel/vm/session.c`: fixed-size global session-slot array + + `session_find(VMUuid)`/`session_register(...)` skeleton. No callers yet. +3. `session_set_pinned()`/`session_is_pinned()` — the pin-authority choke point (H.2/H.10): + writes/reads `Session.pinned`, syncs `STADIUM_FLAG_PIN` on that VM's patron cell. +4. Rewire `stadium_birth_hera()` to register through `session_register()`/ + `session_set_pinned()` instead of setting `STADIUM_FLAG_PIN` directly — Hera becomes + session zero. + +**Phase 2 — Pin Hermes/Artemis (Correction 1 above)** +5. In `capsule_birth.c`'s existing generic admission block, add a name check ("Hera"/ + "Hermes"/"Artemis" → pinned, everything else → unpinned) routed through + `session_register()`/`session_set_pinned()`. +6. Confirm (boot-log/diagnostic) Hermes and Artemis now admit pinned; ordinary births still + admit unpinned. + +**Phase 3 — Session fields wired at birth** +7. Populate `Session.parent` from the birthing VM's `stadium_vm_id`. +8. Populate `Session.name` from the capsule's own name string (already available at this + point in `capsule_birth.c`). +9. Confirm `Session.identity` defaults to `installed=0` correctly (no behavior change + expected yet). + +**Phase 4 — Creator-ceiling enforcement (H.3, birth-time snapshot)** +10. `dictionary_snapshot_acl_from_parent(child, parent)`: for each word also present in the + parent's dictionary, copy `acl_allow`/`acl_mode`/`acl_pinned`/`acl_ttl` into the child's + matching entry. +11. Call it once, right after a child's dictionary finishes loading in `capsule_birth.c`. + +**Phase 5 — `BMAPFMT` (§F.4/§H.6, independent, can run any time)** +12. Edit `blk_meta_t` in `include/block_subsystem.h`: replace the old 4 ownership fields with + `owner_fp[8]`/`acl_allow`/`acl_ttl` (u32)/`acl_reserved[3]`/`reserved_future`. Verify + size/offsets with `offsetof`/`sizeof`, not by hand (see the `blk_volume_meta_t` padding-bug + lesson, [[project_phase8_milestone6_complete]]). +13. Define the three `flags` bit constants (`CLAIMED`=0/`MIGRATING`=1/`STALE`=2). +14. Add C get/set accessors for the new fields in `block_subsystem.c`. +15. Add FORTH wrappers (`BLK-ACL-ALLOW@`/`!`, `BLK-ACL-TTL@`/`!`, `BLK-OWNER@`). +16. Add a new policy capsule (mirroring `ACL.4th`) with a real fast-deny check on top — no + stub, per this project's standing "no stubs or TODOs, ever" rule (§C). + +**Phase 6 — Zuse eligibility list (H.5)** +17. Extend the metadata-fence record format with a new growable `owner_pubkey[32]`-list + record type. +18. Implement read/add/membership-check functions in C. +19. Add a Zuse-only FORTH word to add an entry, gated by `zuse_session`. + +**Phase 7 — Message card gate + `ELEVATE-REQUEST` (H.8)** +20. Add the initiator-only ACL gate at `CH-REQUEST`'s entry point (default-permissive + baseline, real hook point established). +21. Define `ELEVATE-REQUEST` and a minimal real handler checking the eligibility list, + granting via `ACL-ALLOW!`/`ACL-TTL!` on match. +22. Add the FORTH entrypoint a session actually calls to send one. + +**Excluded, per H.11's deferred items 10–11**: VM card multi-owner support, live-console +`sudo`-style elevation, pre-signed capability tickets.