LithosAnanake/FABRIC-2.md

# FABRIC-2.md — the Stadium, continued

**Status:** Living working document, opened 2026-08-12 as the successor to `FABRIC.md`
(now closed/archival — see its own header). This document does not repeat `FABRIC.md`'s
design argument or history; it restates only outcomes, with pointers back to the section
that derived them. Read `FABRIC.md` for the "why," this document for the "what's left."

**Provenance.** Everything below came from a full, non-sampled read of the entire 7,595-line
`FABRIC.md` on 2026-08-12, looking for anything not yet resolved: unchecked punch-list
items, the architectural "### N.N Open" subsections in §1–24, the §25.7 "reported, not
scheduled" list, and any other "not yet"/"deferred"/"still open" language in the document.
Item numbers below are carried forward unchanged from `FABRIC.md` where one already existed,
for traceability — this is not a renumbering.

**How to use this document going forward.** New findings, new punch-list items, and new
decisions get added here, not to `FABRIC.md`. Follow the same discipline `FABRIC.md` §25.0
established (read it there — it isn't repeated here) for how work gets picked up, closed,
and recorded.

---

## A. Blocked or scoped, not started

- [ ] **1.11 — Dirty-event granularity.** Leaning region-based. Blocked on item 4.3 — settled
  as part of the console migration, not speculatively before it. *Refs (FABRIC.md):* §17.5,
  §23.2, §23.4 #1.

- [ ] **4.3 — Console.** Umbrella item; settles 1.11 as part of the work. Nearly everything
  under it (4.3.1–4.3.7f, 4.4–4.4ac) is done — the parent stays open only because 4.4s below
  is still blocked and nothing has formally closed the umbrella. *Refs (FABRIC.md):* §17.5,
  §27.

- [ ] **4.4s — `(user)` prompt segment.** Scoped, blocked, not started. Extends 4.4's prompt
  format. *Refs (FABRIC.md):* §27.8, 4.4.

- [ ] **4.6 — Artemis last.** It works today; it is the thing that cannot be broken. Not
  started.

- [ ] **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.

- [ ] **5.2 — Isabelle/HOL.** One datatype, one index space, one conservation theorem. Not
  started.

- [ ] **5.3 — Shrink the subsystem documents.** `ARTEMIS.md`, `HERMES.md`, `CONSOLE.md`,
  `TRIPOD.md` need trimming now that `FABRIC-2.md` (via `FABRIC.md`) is the design-of-record.
  Not started. **Specific pending edit found within this item:** `TRIPOD.md`'s own Immediate
  Goal section still describes Hera spawning Hermes and Artemis automatically at boot — item
  0.1 undid that behavior, and the doc was never updated to match.

---

## B. Live and unmeasured — deferred while Tripod was pruned to Hera-alone, now genuinely live since item 4.2 restored Hermes

- [x] **Fleet heat leak.** Integer-truncation drift in `vm_physics_touch()` (FABRIC.md §20.2)
  was explicitly noted as invisible with only Hera resident, and "becoming measurable the
  moment Phase 4 restores Hermes/Artemis." Phase 4 has now restored Hermes (item 4.2). This
  is the single most concrete open item carried into this document — real, live, and
  unmeasured.

  > **INVESTIGATED 2026-08-13 — §20.2's truncation claim does not hold; no live drift risk
  > exists today.** Full read of `capsule_vm_physics.c`: every write to
  > `execution_heat_q48` goes through exactly one of `vm_physics_init()` (birth),
  > `vm_physics_transfer()` (`:176-183`), or `vm_physics_retire()`'s zero-out after transfer
  > (`:277`) — confirmed via a repo-wide grep, nothing else touches the field.
  > `vm_physics_transfer()` moves an identical amount off `from` and onto `to` in the same
  > call (`from -= moved; to += moved`), unconditionally. The touch() fan-out (`:334`,
  > `share = (moved_total * heat) / others_total`) truncates per-VM, so `sum(shares) <
  > moved_total` — but each `share`, truncated or not, is what actually leaves its VM *and*
  > what actually arrives at the touched VM, via the same `vm_physics_transfer()` call. A
  > worked example: others_total=10 (A=5, B=5), moved_total=7 → share_A=share_B=3, sum is 6
  > not 7. Fleet sum before = 10+target; after = (2+2)+(target+6) = 10+target. Identical. The
  > truncation is a rate-fidelity shortfall (the touched VM pulls in less than the physics
  > model intended) — it cannot move the fleet-wide sum, because nothing is ever subtracted
  > from one place without the identical amount landing at exactly one other. This matches
  > the header's own contemporaneous claim (`capsule_vm_physics.h:31-33`): conservation is
  > "held by construction: every state change is a balanced transfer." Git history rules out
  > a since-fixed bug: `vm_physics_transfer()` and the touch() loop are unchanged since the
  > file's creation (`a5ed8c3`, 2026-08-01), predating §20.2's correction (`055e944`,
  > 2026-08-03) — the claim was made about the exact code read here, not an earlier version
  > of it.
  >
  > **The one path that can genuinely drop heat** is `vm_physics_retire()`'s guarded
  > "no valid root" case (`:271-275`) — the dying VM's remainder has nowhere
  > conservation-preserving to go if it IS the root, or its parent chain is broken. Both are
  > structurally excluded today: `capsule_vm_kill` refuses to kill Hera, and
  > `parent_vm_id` is set once at birth and never rewritten, so a well-formed chain can't
  > corrupt itself. Real in principle, unreachable under current invariants — tracked
  > separately in §C below rather than as a live measurement task.
  >
  > FABRIC.md §20.2 itself should eventually be corrected to match (currently still asserts
  > the truncation causes monotonic drift); not done here to keep this document's discipline
  > of not editing `FABRIC.md` further.

- [x] **Multi-VM heartbeat ownership.** Whose `tick_target_ns` drives the one physical timer
  (FABRIC.md §26.5) has only one answer while Hera is the only VM; explicitly "not resolved
  for when Hermes/Artemis return." Hermes has returned (item 4.2). Same situation as the
  fleet heat leak above — a deferral whose triggering condition has since become true.
  **Ruled:** there is exactly one physical timer, so exactly one VM may write its re-arm
  period — never whichever VM's `vm_tick()` happened to run last. Hera is the fixed point
  everywhere else in this design (patron zero, sole capacity arbiter, sole birther/killer of
  VMs — see FABRIC.md §20.2, §26), so she is the sole owner here too. Every other VM's Loop
  #7 (`vm_tick_inference_engine()`) still adapts its own `vm->heartbeat.tick_target_ns`
  exactly as before — that per-VM bookkeeping is correct and untouched — it simply never
  reaches the shared physical re-arm; only Hera's does.
  *Done when:* `vm_tick_inference_engine()` gates the physical-timer re-arm behind
  `vm_uuid_is_hera(vm->stadium_vm_id)`, and a three-arch QEMU boot with Hermes live (item
  4.2) is clean.
  *Refs (FABRIC.md):* §20.2, §26.5.

  > **DONE 2026-08-13.** `vm_tick_inference_engine()`
  > (`src/starkernel/vm/vm_runtime.c:766`) now wraps the kernel-base re-arm block in
  > `if (vm_uuid_is_hera(vm->stadium_vm_id))`, using the existing
  > `vm_uuid_is_hera()` (`src/starkernel/capsule/vm_uuid.c:51`) already used the same way at
  > the birth/kill call sites in `capsule_birth.c` and `capsule_vm_physics.c`. Three-arch
  > acceptance boot, all clean to `ok>`, Hermes live and self-testing in every log:
  > `logs/20260813-075940/amd64`, `logs/20260813-080125/aarch64`,
  > `logs/20260813-080257/riscv64`. Committed `bcc72d0`.

---

## C. Reported bugs and dead code, not yet fixed

- [x] **`vm_physics_retire()`'s dropped-remainder case.** (`capsule_vm_physics.c:271-275`)
  If the dying VM is itself the fleet root, or its parent chain is broken, its remaining
  heat has nowhere conservation-preserving to go and is zeroed instead of transferred — a
  genuine, if narrow, violation of the `sum(execution_heat) == Q48_ONE` invariant. Found
  while investigating the "Fleet heat leak" item above, 2026-08-13.

  > **CORRECTION, same day:** the "structurally excluded" framing this item originally had
  > was wrong — the Hera case *was* reachable. `mama_word_kill()`
  > (`mama_forth_words.c:520-530`) called `vm_physics_retire(entry.vm_id)` for any live-state
  > VM found by name, with no Hera check, *before* `capsule_vm_kill()`'s own Hera guard
  > (`capsule_birth.c:313-316`) ever ran. `S" Hera" KILL` therefore hit
  > `vm_physics_retire()` with Hera's own id; her self-referential `parent_vm_id` made
  > `vm_physics_find_root_id()` return her own id immediately, `root` came back `NULL`, and
  > the fleet's entire `execution_heat_q48` sum was silently zeroed — with only the
  > harmless-looking "cannot kill Hera" message as visible output, since that guard runs
  > second. The broken-parent-chain half of this item remains genuinely unreachable
  > (`parent_vm_id` is set once at birth and never rewritten); only the Hera half was live.
  >
  > **DONE 2026-08-13.** Fixed by excluding Hera from the retire call at the one call site,
  > mirroring `capsule_vm_kill()`'s existing guard: `mama_forth_words.c`'s
  > `capsule_vm_find_by_name_nocase(...) && entry.state == VM_STATE_LIVE` condition gained
  > `&& !vm_uuid_is_hera(entry.vm_id)`. No change to `vm_physics_retire()` or
  > `capsule_vm_kill()` itself. Three-arch acceptance boot, all clean to `ok>`:
  > `logs/20260813-083429/amd64`, `logs/20260813-083551/aarch64`,
  > `logs/20260813-083738/riscv64`. Committed `db66406`.
- [ ] `arch_mmu_init()` is declared and defined on all three architectures but never called
  anywhere — dead code. Found during item 4.3.5a.
- [ ] `include/block_subsystem.h:168`'s `encoding` field (ASCII/UTF-8/binary) is dead
  metadata — nothing reads or writes it. A ruling on wiring it up vs. removing it is still
  open. (FABRIC.md §27.6)
- [ ] `tools/README.md` documents a `fbtest.c` example that does not actually exist in
  `tools/` — stale-doc discrepancy.
- [ ] `hotwords_cache_promote()` has a NULL-write bug on a full cache. Unreachable under
  today's workloads, not fixed.
- [ ] `heartbeat_trust()` has zero callers — dead code.
- [ ] `m5_time_trust`/`m5_variance` are declared and never used.
- [ ] `src/*.c.bak` files (`vm.c.bak`, `doe_metrics.c.bak`, `inference_engine.c.bak`) remain
  tracked in git at `src/` top level. Repo hygiene debt, not intentional (also noted in
  `.claude/CLAUDE.md`).
- [ ] `bump-z`/`bump-y` Makefile targets reference `STARFORTH_VERSION_MAJOR`/`MINOR`/`PATCH`/
  `STARFORTH_VERSION_STRING` fields that don't exist in the actual generated
  `include/version.h` (also noted in `.claude/CLAUDE.md`).
- [ ] **Kconfig/`menuconfig` has never been exercised end-to-end.** Every knob added so far
  (including item 4.1's `STADIUM_WORD_HEAT_QUANTUM`/`STADIUM_WORD_COOL_RATE_Q48`) has only
  ever been verified via its `Makefile.starkernel` default. Nobody has run
  `make -f Makefile.starkernel menuconfig`, changed a value, and confirmed it flows through
  to a build. Flagged by Captain Bob 2026-08-05.

---

## D. Design questions still genuinely open

- [ ] **§12 Q5 — the full eight-loop interference analysis has not been done.** Its stated
  blocker ("no real time base on all three ISAs") is gone — Phase 0 completed that — so this
  is now unblocked and simply never picked back up.
- [ ] **§17.4 — the framebuffer utility's internal heat/decay dynamics are undesigned.**
  Explicitly "Open, deferred": not a Stadium patron, but what physics (if any) governs it
  internally was never designed. Not blocking anything.
- [ ] **§23.4 #2 — cell-size validation against a real message shape.** "Check that a typical
  message still fits in one cell" was never done — item 3.1's own done-note confirmed no
  message-patron struct existed yet at the time. This is now checkable: item 4.2 built
  Hermes's actual message/channel structures on the Stadium, so the 32-byte inline payload
  can finally be validated against something real instead of a hypothetical.

---

## E. Documentation debt

- [ ] **Taxonomy / glossary.** Captain Bob's own flag, 2026-08-04: the physics vocabulary
  (heat, mass, density, patron, Stadium, and Kconfig knob names built on it) needs an
  explicit glossary stating these are named analogies, so code, Kconfig, and documentation
  terminology don't drift apart over time. Never scoped into any phase. Real, acknowledged
  debt: "I guess that we didn't finish out FABRIC.md quite as much as we thought."
- [ ] **ACL-RWT DoE overhead re-measurement.** The measured overhead numbers in
  `.claude/CLAUDE.md` ("+0.0054%–+0.0088%") were all captured at `-O0`, before item 4.5
  enabled real compiler optimization. Nobody has re-measured, or even confirmed the old and
  new numbers are comparable at all. Flagged in passing during item 4.5f, never formally
  scoped.