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.

  DIAGNOSTIC 2026-08-13 — toolchain replaced, build attempted, one root-cause file found broken; not yet fixed. The installed Isabelle at /home/rajames/CLionProjects/Isabelle2011-1 was genuinely Isabelle2011-1 (14+ years old, from the directory's own timestamps) — essentially guaranteed stale against proof/'s 23 .thy files. Replaced with Isabelle2025-2 (current stable, Jan 2026) at the same path, old install preserved alongside as Isabelle2011-1.old rather than deleted. isabelle build -v -D proof/ run for real (not a dry run): the Pure/HOL base heaps loaded fine, HOL-Library built clean from scratch in ~5 minutes, but the StarForth session failed.

  One root cause, not sixteen. proof/StarForth_Q48_16.thy — the base theory every other theory in the session transitively depends on — fails to load with three distinct real problems, all consequences of 14 years of HOL-Library changes since 2011:

  1. Line 75 — unat_push_bit is now an undefined fact; that lemma name from the old Word library appears renamed or removed.
  2. Lines 63 and 122 — two by (simp add: drop_bit_push_bit word_size) proofs (drop_bit 16 (push_bit 16 n) = n round-trip lemmas) no longer close, likely the same underlying Word-library lemma-set drift as #1.
  3. Line 144 — a genuine name collision, not proof drift: q48_accuracy's total parameter now shadow-fails against a same-named HOL-Library constant (the order-theory "total relation" predicate, type ('a×'a) set ⇒ bool) that didn't exist or wasn't in scope under the 2011 library — Isabelle now resolves the identifier to that constant instead of binding it as a fresh parameter, producing a real type error at the definition.

  Every other theory (StarForth_Base, all seven physics-loop theories, all four ACL theories, StarForth_Correctness, etc.) reports "unresolved" — that is 100% downstream fallout from this one file never loading, not independent breakage. Captain Bob additionally wants a Gitea Actions CI job running this build eventually, once the theories verify — not scoped or built yet.

  StarForth_Q48_16.thy FIXED 2026-08-13 — verifies 100%, all lemmas true. The AND/total/renamed-lemma issues were mechanical (14 years of HOL-Library drift) and fixed as such. Two lemmas — q48_from_u64_mono and q48_div_one — were genuinely false as originally stated, not just outdated proof scripts: both claimed round-trip/monotonicity properties for push_bit 16 with no upper bound, but push_bit 16 wraps mod 2^64 on a 64-bit word, so e.g. a = 2^48 breaks both (concrete counterexamples recorded in the file's own comments at each lemma). Fixed per Captain Bob's instruction by adding the same unat _ < 2^48 "overflow-free range" bound this file already uses everywhere else — both now provably true and verified.

  StarForth_Base.thy's vm_state circularity FIXED 2026-08-13 — properly, not patched around. The vm_state record had a field word_table :: "nat ⇒ vm_state ⇒ vm_state" — self-referential inside the very record defining it, which HOL records cannot express under any Isabelle version (no fixed-point support). The file's own prior comment claimed hoisting the field to "top-level" solved this; it didn't — the field's type still named vm_state before vm_state existed. Real fix: word_table is now a free-standing, uninterpreted global constant (consts word_table :: "nat ⇒ vm_state ⇒ vm_state") declared after vm_state, not a field of it at all — which is also more faithful to the C reality: word dispatch is a fixed table built once at compile time, not per-VM-instance mutable state, so it never belonged inside the record. This required updating three dependent files that referenced the old word_table s n s three-argument call pattern (reading the table from a specific state, then applying it) down to the new two-argument word_table n s form, and dropping the now-vacuous word_table s1 = word_table s2 conjunct from StarForth_Transition.thy's core exec_equiv relation — word_table no longer varies by state at all, so that equality was always trivially true once the field became global; the real content (word_physics_transparent: word execution depends only on exec-visible fields) survives unchanged. StarForth_Base.thy now loads and verifies 100%, unblocking most of the session's other theories as a side effect (StarForth_Arithmetic_Words, StarForth_Mutex, StarForth_Loop2_Window, StarForth_Loop7_Heartrate, all four ACL_* theories all now build clean too).

  Three more independent issues surfaced once StarForth_Base unblocked everything downstream of it — not yet fixed, same "apparently never actually compiled before" pattern:

  • StarForth_Loop2_Window.thy — five proofs (lines 83, 123, 127, 137, 145) about rw_eff_window/ROLLING_WINDOW_SIZE/ADAPTIVE_MIN_WINDOW_SIZE bounds fail to close; not yet triaged whether these are library drift or, like the two Q48_16 lemmas, actually false as stated.
  • StarForth_Loop5_WinInf.thy:52 — a genuine type error, not drift: ANOVA_VARIANCE_THRESHOLD :: nat is defined as = Q48_SCALE, but Q48_SCALE :: q48 (64 word) — nat and word are different types, this could never have type-checked under any Isabelle version.
  • StarForth_Memory_Words.thy:157 — same AND bundle issue already fixed in StarForth_Q48_16.thy (needs its own unbundle bit_operations_syntax), not yet applied here.

  ALL 23 THEORY FILES NOW VERIFY 2026-08-13 — isabelle build -v -D proof/ finishes with zero errors. Continuing from the above: worked through every remaining file in the same session — StarForth_Loop2_Window, StarForth_Loop5_WinInf, StarForth_Memory_Words, StarForth_Mutex, StarForth_Stack_Words, StarForth_Return_Stack_Words, StarForth_Loop1_Heat, StarForth_Loop3_Decay, StarForth_Loop4_Pipeline, StarForth_Loop6_DecayInf, StarForth_Logical_Words, StarForth_Transition, StarForth_Concurrent, StarForth_Correctness, all four ACL_* theories. Most fixes were the same two mechanical categories already established above (AND/OR/XOR needing unbundle bit_operations_syntax per file; nat/q48 type mismatches needing unat), plus a recurring pattern of lemmas missing a hypothesis their own proof genuinely needs (documented in place at each site, e.g. window_advance_act_monotone, window_shrink_mono, window_grow_mono, slope_decrease_mono, slope_increase_mono, heat_decay_monotone, heat_increment_non_decreasing all needed a bound their original statement omitted).

  One more foundational finding, fixed properly. StarForth_Transition.thy's axiom word_physics_transparent — one of only 2 axioms the entire correctness framework rests on — originally concluded full state equality (word_table n s1 = word_table n s2) from mere \<simeq> exec-equivalence of the inputs. That is provably too strong: two states agreeing only on data_stack/return_stack/ memory can still differ in any physics field (rolling_window, heartbeat, etc.), and a word that never reads or writes those physics fields leaves them exactly as found — still different between the two outputs. This surfaced as StarForth_Concurrent.thy's foldl_word_table_eq failing at the empty-list base case, which reduced to needing s1 = s2 from s1 \<simeq> s2 alone — genuinely unprovable, not a tactic problem. Fixed by weakening the axiom's conclusion to \<simeq> (congruence, not equality) — exactly what the file's own audit protocol ("word body only reads the three exec_equiv fields") actually justifies, and exactly what every downstream consumer (heartbeat_noninterference, heartbeat_trace_noninterference, etc.) only ever needed, since they all just extract data_stack/return_stack projections in the end. Propagated through StarForth_Transition.thy, StarForth_Concurrent.thy, StarForth_Correctness.thy. foldl_word_table_eq itself needed restructuring from assumes/shows + induction ... arbitrary: s1 s2 to an explicit object-level \<forall>s1 s2. ... \<longrightarrow> ... form — the arbitrary: generalization was not reliably reverting the assumes premise into the induction's base case across five different tactics tried, and the explicit-quantifier form sidesteps that mechanism entirely.

  Two genuine, non-tactical bugs found and deliberately left oops-flagged rather than fixed, each documented in place with a full explanation:

  • StarForth_Stack_Words.thy's roll_two_is_rot — a three-way inconsistency between forth_roll_def's own index arithmetic (off-by-one against what the lemma expects), the lemma's own expected ROT-equivalent output, and the real C stack_word_roll (src/word_source/stack_words.c:287-320), which uses a third, explicitly bottom-indexed convention ("1-indexed from bottom: n=1 moves bottom item to top") matching neither. Not a proof-script issue — a genuine open question about what ROLL is supposed to do, needing a decision before it can be closed either direction.
  • StarForth_Loop4_Pipeline.thy's pm_record_hit_preserves_wf/ pm_record_miss_preserves_wf — pm_wf only requires pm_last_accuracy_den > 0 when pm_prefetch_attempts > 0; both operations increment attempts from 0 to 1 without ever having required den > 0 beforehand, so the postcondition needs something the precondition never guaranteed. A genuine invariant-maintenance gap in pm_wf's own definition, not fixed here.

  Toolchain: /home/rajames/CLionProjects/Isabelle2011-1 now genuinely runs Isabelle2025-2 (old 2011 install preserved as Isabelle2011-1.old). Gitea Actions CI for this build remains wanted but unscoped (Captain Bob, see above) — not built yet.

  PROCESS CORRECTION 2026-08-14/15 — the word-source coverage sweep below should have been tracked here from the start and was not; recorded now, retroactively, per §25.0's own rule that new findings/decisions land in this document. Across several sessions (2026-08-14 through 2026-08-15) the proof suite was extended file-by-file to cover every file in src/word_source/*.c (34 files; q48_16_words.c deliberately excluded, it's the underlying math library, not a FORTH words file) — this was a different goal from 5.2's original "one datatype, one index space, one conservation theorem" framing (a Stadium-cell-model proof), and got tracked only in session memory instead of here. That memory is project_isabelle_hol_proof_suite.md in this machine's Claude memory store, if the full blow-by-blow is ever needed; the summary below is what matters for this document.

  Sweep complete, commit 346c793: all of src/word_source/*.c covered, 53 theories green. Two deliverables followed, proof/FINDINGS.md (commit 3426d6a) and proof/COVERAGE.md (same commit) — an aggregated cross-cutting-findings write-up and a coverage/purpose index, both requested by Captain Bob once the sweep was far enough along.

  Repair pass, commit dfdabcc — low-risk defects only, per Captain Bob's explicit scope call. DECAY-RATE@ (physics_freeze_words.c) had a genuine missing stack-overflow guard (raw push, no ds_full check, unlike its neighbors in the same file) — fixed. Removed dictionary_manipulation_words.c's dead, permanently-shadowed [/]/STATE and defining_words.c's dead, permanently-shadowed DEFER/IS/ DEFER@ (plus the now-orphaned defining_runtime_defer helper, which would have triggered an unused-static-function warning under -Wall -Werror if left behind) — both confirmed unreachable via word_registry.c's registration order and FORTH's newest-first dictionary lookup, zero behavior change. Correction caught mid-pass and worth recording: ~14 of the sweep's ~15 "missing overflow guard" findings turned out to be false positives — vm_push()/VM_PUSH already bounds-check internally in every build this repo currently ships (STARFORTH_PERFORMANCE, the one flag that would disable that check, is never defined by any Makefile/Kconfig target here) — the proof model just hadn't credited that. Corrected in the .thy files and FINDINGS.md, not silently left overstated. Three-architecture QEMU acceptance: all three booted clean to ok> with an identical dict_hash=0x24b4279f0670aa3a and identical 1003/965/0/0 self-test totals — logs/20260814-195128/amd64, logs/20260814-201210/aarch64, logs/20260814-202224/riscv64.

  Coverage-sweep continuation into structural gaps, commits cc46cf8/1aca77d/ d3d66fb/d59a913 — proof-only, no C changes, no QEMU boot needed for these. Dictionary insertion (vm_create_word) had never been modelled anywhere in the suite — every prior file only ever read the abstract dictionary table. dict_insert_entry now models the word_id-assignment/table/latest_id/ word_id_next-counter mechanism, reusing a word_id_next field that had been declared in StarForth_Base.thy since early in the sweep but never once written. Separately, input_buffer/input_length/input_pos (the TIB) turned out to be plain per-VM array/scalar fields, not host pointers as assumed everywhere else in the sweep, and vm_parse_word a pure scan — modelled as forth_parse_word. Composed together (plus a new de_df :: cell field on dict_entry and dict_write_df for the data-field write, and current_executing_word_id on vm_state), CREATE, VARIABLE, and CONSTANT are now the first three fully-modelled words in StarForth_Defining_Words.thy — guard through parse through insertion through the data-field write, matching the real C exactly, nothing left unmodelled per word except the pin-shadow name-scan guard (sidestepped via an explicit bool parameter, the same technique already used for the XT-pop gap elsewhere in this suite). : and DEFER are closed to the same point minus one remaining per-word gap each (: needs a vm->compiling_word-tracking field that doesn't exist yet; DEFER's own runtime is a structurally different DF usage — dispatch reassignment via a stored pointer, not a plain value). Full suite: 54 theories, green. Not yet done: IS/DEFER@ (need the FIND-family name-resolution gap first), the vocabulary-chain mechanics, the block-window cache, the hot-words cache — each flagged as its own project, 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.

  Pending edit fixed 2026-08-13; the item's larger scope (actually shrinking the four documents) remains open. TRIPOD.md's "Immediate Goal" section corrected: it now states plainly that Hera boots alone by design (confirmed live — capsules/init.4th births no other VM), that Hermes/Artemis-as-VM-patron births are on-demand via test tooling today (not automatic boot behavior), and separately notes that Artemis's block-storage device does auto-attach at the C level at boot (kernel_main.c's M7.pre step) — distinct from, and not to be confused with, an Artemis VM patron birth. The acceptance criteria were reworded from "Hera spawns X" to "Hera can spawn X" to stop asserting automatic behavior that doesn't exist. This closes only the one stale claim this document already flagged — ARTEMIS.md, HERMES.md, CONSOLE.md were not read for similar staleness, and none of the four documents' actual line-count reduction (the item's real ask) has been attempted.

  AUDIT of the other three, 2026-08-13. Read each in full. One got the same well-scoped fix as TRIPOD.md; the other two turned up staleness too large to silently correct — reported here for a call, not fixed.

  ARTEMIS.md — fixed, same pattern as TRIPOD.md. Its Build Status section claimed Artemis "boots live in the Tripod fleet (announces ready to Hermes) on every amd64/aarch64/riscv64 kernel boot." Same conflation as TRIPOD.md had: confirmed capsules/init.4th births no VM but Hera (item 0.1), so Artemis-as-VM-patron capsule birth is not automatic — but Artemis's block-storage device (the virtio-blk disk) genuinely does auto-attach at the C level at boot (kernel_main.c M7.pre), which is real and unchanged. Corrected in place; rest of the document (Build Status detail, Storage Design future material) read as accurate and current, not touched further.

  CONSOLE.md — not fixed, staleness is structural, needs Captain Bob's call on how to handle it. This document is dated 2026-08-02 and states outright "nothing described here is implemented yet... there is no Console code in the tree yet." That is no longer true in two different ways:

  1. Its central premise was superseded by a later, DECIDED ruling. CONSOLE.md says Console is "the fleet's fourth leg — Quadrupod, not Tripod. A real StarForth VM, spawned by Hera, participating in fleet K≡1.0." FABRIC.md §17.5 later ruled the opposite, explicitly and by name: the framebuffer is not a patron, it is a utility — "closer to the power company... Not the Stadium. Not the basement of the Stadium. A third thing." Confirmed no Console VM exists anywhere in the tree (grepped stadium.h, vm_uuid.c, the fleet machinery — zero hits for a Console VM kind). CONSOLE.md's entire "What Console Is" section describes a design that was designed away from, not toward.

  2. Its "explicitly out of scope" list is now false. CONSOLE.md lists keyboard input as out of scope, stating flatly "there is no keyboard driver anywhere in this codebase yet." Confirmed false: src/starkernel/arch/amd64/i8042.c (PS/2, exactly the driver CONSOLE.md itself predicted as "the pragmatic first target") and src/starkernel/virtio/virtio_input.c (USB HID, which the doc predicted "should come later, if at all") both exist, and a keyboard-to-REPL bridge is live (FABRIC.md item 4.4v, src/word_source/keyboard_words.c, src/starkernel/repl.c's sk_kbd_getc()).

     Some of the document's technical content did land as described and is not stale: the bottom-left-origin/Y-up Cartesian coordinate flip is real (framebuffer.c:225's comment confirms the pre-flip/post-flip distinction), and stroke-font glyph capsules plus a later TrueType adjunct did ship (FABRIC.md §27.6/§27.7). The font/pen layer and heat-driven-redraw sections were not independently re-verified line-by-line here — flagged as unverified, not claimed accurate or inaccurate.

     Given the console/framebuffer work that actually shipped went a different architectural direction than this document's core design (utility, not a 4th Tripod VM; direct C/StarForth console code, not Hermes-routed VM messages), a minimal correction paragraph the way TRIPOD.md/ARTEMIS.md got would understate the gap. This needs either a full rewrite against FABRIC.md §17.5/§27 as the design-of-record, or an explicit "superseded, kept for history" header — Captain Bob's call, not made here.

  HERMES.md — not fixed, one concrete verified discrepancy plus a stale block map, needs Captain Bob's call. HERMES.md's own "Message node — 8 cells" layout table (offsets 0–7: type, sender, recipient, payload addr, payload len, heat, seq, channel) contradicts the capsule's own 9 CONSTANT MSG-CELLS (capsules/hermes/init.4th, confirmed twice already this session — once in this document's §23.4 #2 closure, once independently here). The real 9-cell layout item 4.2 shipped stores a Stadium cell index at offset 5, not a raw heat value directly, and adds an ORIG-TYPE field at offset 8 that HERMES.md doesn't mention at all. Separately, HERMES.md's "v1 Block Map — LOCKED" lists only blocks 4100–4128; the actual capsule (grep '^Block ' capsules/hermes/init.4th) also has blocks 4142, 4144–4159, 4175, 4176 — a substantial amount of item 4.2's Stadium-integration content (VM-name routing, StadiumBehaviour tags, the admission-heat math) isn't in the documented map at all, and it's not verified here whether 4122–4128 as HERMES.md numbers them still hold the same content. HERMES.md closes with "This document is authoritative. If it conflicts with something in the codebase, the codebase is wrong" — that claim does not hold for the cell count, which is a deliberate, intentional change (the capsule's own comments say "item 4.2 -- heat/capacity via Stadium"), not a drift bug. Reported, not fixed — reconciling the full block map is real work, not a one-line correction.

---

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

• 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.

• 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

• 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() — TODO, not accidental dead code. Declared (arch.h:73) and defined on all three architectures (amd64/arch.c:246, aarch64/arch.c:169, riscv64/arch.c:179) but never called anywhere — confirmed by repo-wide grep, 2026-08-13. Each definition is a real doc-commented no-op stub ("paging will be wired up in later milestones" / "MMU bring-up deferred" / "Sv39/Sv48 bring-up deferred"), and each comment describes it as satisfying "the common arch_mmu_init() call site shared across all three ISAs" — a call site that does not exist anywhere in the tree today. vmm.c (M3) handles page-table management independently and does not need this hook to function. Captain Bob's call, 2026-08-13: leave the three stubs in place as scaffolding for a future per-arch MMU milestone rather than deleting or wiring in a no-op call site now — ruling recorded, closed as investigated/not-a-bug rather than left open. 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. (FABRIC.md §27.6) Investigated 2026-08-13, scope turned out wider than the field itself: blk_get_meta()/blk_set_meta() (src/block_subsystem.c:881,903) are the only public API for the whole blk_meta_t struct and have zero callers anywhere in the tree — not just encoding but content_type, content_length, owner_id, permissions, acl_block, signature, entropy, hash, the chain fields, and app_data[15] are all unused. The struct is a real fixed on-disk byte layout (packed 341 bytes/block into META_REGION_OFFSET, src/block_subsystem.c:69-71), serialized via meta_to_slice()/meta_from_slice() during cache writeback/load — so it isn't free-standing dead code to delete, removing a field would shift every subsequent field's on-disk offset. Ruling (Captain Bob, 2026-08-13): flag and leave as-is — this metadata subsystem is scaffolding expected to get consumed once Artemis's design (content-typed/owned/ACL'd blocks) is completed, not a bug to fix now.

• tools/README.md documents a fbtest.c example that does not actually exist in tools/ — stale-doc discrepancy. Confirmed 2026-08-13, and the discrepancy is two-sided: git log --all shows fbtest.c was never added to the repo at any point — the table entry describes a tool that was documented but never built. Meanwhile tools/ttftest.c (added 5f6cc05, item 4.3.7, TrueType parser core test) is a real tool that exists on disk but has no README table entry at all. Left unfixed pending explicit instruction (README edit would be a fix, not just an investigation).

• hotwords_cache_promote() has a NULL-write bug on a full cache. Confirmed 2026-08-13: the full-cache branch (src/physics_hotwords_cache.c:362-371) writes word into cache->cache[cache->lru_index] unconditionally once cache->cache_count >= HOTWORDS_CACHE_SIZE — it does not check word for NULL on that path, unlike the slot-available branch below it, which does. A NULL word would silently evict a live cache entry and replace it with NULL. Confirmed unreachable in practice: all four call sites (physics_hotwords_cache.c:284, physics_execution_hooks.c:140, rolling_window_of_truth.c:787, src/starkernel/vm/vm_core.c:731) only call hotwords_cache_promote() after a DictEntry* NULL check has already passed. Ruling: flag and leave as-is, matching the arch_mmu_init()/block_subsystem precedent — real defect, no live trigger, not fixed without explicit instruction.

• heartbeat_trust() has zero callers — dead code. Stale claim, corrected 2026-08-13: heartbeat_trust() (src/starkernel/heartbeat.c:205) is called from src/starkernel/kernel_main.c:913, printed as the trust=0x... field of the M5 heartbeat boot-milestone diagnostic line, alongside tick count and variance. Not dead code — closed as investigated/not-a-bug.

• m5_time_trust/m5_variance are declared and never used. Confirmed 2026-08-13: repo-wide grep for both names turns up only their own declarations (include/vm.h:315-316) — no reader, no writer, anywhere. Genuinely dead struct fields. Ruling: flag and leave as-is, same precedent as the other Section C dead-code items — not removed without explicit instruction.

• 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.

  DONE 2026-08-13. The vendored tools/kconfig build had never actually succeeded on this machine — bison/flex were missing, installed with Captain Bob's go-ahead. mconf needs an interactive TTY this environment doesn't have, so the exercise used conf directly (same underlying engine menuconfig calls) rather than the ncurses frontend itself. make -f Makefile.starkernel ARCH=amd64 kernel_amd64_defconfig generated build/amd64/.config correctly (CONFIG_SK_PARITY_DEBUG unset, matching Kconfig's default n). Hand-editing that line to CONFIG_SK_PARITY_DEBUG=y and re-running the kernel build showed the real compile line for src/starkernel/vm/parity.c gained -DSK_PARITY_DEBUG=1 (was =0), and the object compiled clean with it; reverting the line back to unset flipped the flag back to =0. Confirms the mk/Kconfig.mk bridge and kconfig_bool macro genuinely wire a .config change through to -D flags in both directions — this had never been verified before. One caveat found in passing, not itself a bug: invoking tools/kconfig/conf directly (bypassing the Makefile) writes a stray .config + include/config//include/generated/ at the repo root instead of under build/, since it doesn't pick up the KCONFIG_CONFIG/etc. env vars mk/Kconfig.mk exports — only matters if invoking conf by hand outside the Makefile targets, as done here; cleaned up before committing. No .config/build/ artifacts committed — both are gitignored working state.

---

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.

  ANALYSIS DONE 2026-08-13 — found a real violation of §22.4's required ordering, left open pending Captain Bob's call on how to handle it. Traced every loop's actual firing cadence from source (src/starkernel/vm/vm_core.c, vm_runtime.c, capsule_vm_physics.c), in execution counts, not the nominal per-loop constant names:

  • Cadence 1 execution: Loop #1 (heat), Loop #2 (rolling-window record), Loop #4 (pipelining) — every word dispatch.
  • Cadence HEARTBEAT_CHECK_FREQUENCY = 256 executions: Loop #3 (background decay, batched), rolling_window_service(), dict_adaptive_optimization_pass(), L8 Jacquard vote, fleet-capacity-counter increment — all five in the same vm_heartbeat_run_cycle() call, zero separation between them.
  • Cadence HEARTBEAT_INFERENCE_FREQUENCY ticks × 256 = 256,000 executions: Loop #5 (window width) + Loop #6 (decay slope) + Loop #7 (adaptive heartrate) — all three merged into one vm_tick_inference_engine() call, zero separation between them.

  Two real findings, not just tidiness:

  1. The fleet-capacity loop can fire faster than a VM's own heat loop, not slower — the opposite of §22.4's "capacity must be the slower loop." §22.4 cites vm_physics_heartbeat_tick() (capsule_vm_physics.c:454-459) by name as the existing precedent for the required 1000:1 separation. But that function is called from every live VM's own vm_heartbeat_run_cycle() (vm_runtime.c:502), incrementing one shared global fleet_heartbeat_tick_count, and fires vm_physics_tick() once that shared counter — fed by all VMs at once — reaches HEARTBEAT_INFERENCE_FREQUENCY (1000). A lone VM needs 1000 of its own 256-execution cycles to trip its own inference gate; with STADIUM_MAX_VM_COUNT's real default of 4 (Hera + 2×Hermes + Artemis, Tripod's actual topology), the shared fleet counter can reach the same threshold up to ~4× sooner in wall-clock terms. So in a live multi-VM fleet, capacity arbitration can run more often in real time than any individual VM's own heat-inference loop, not less — exactly the ordering §22.4 calls "required, not preferred" because getting it backwards "produces a system that thrashes while every individual rule looks correct."
  2. The fix §22.4 already specified was never actually built. §22.4's own resolution text says the capacity-tick should get "its own named constant rather than literally sharing HEARTBEAT_INFERENCE_FREQUENCY... named and made a Kconfig symbol at implementation time (item 3.1)." STADIUM_CAPACITY_TICK exists in Kconfig.kernel exactly as promised, default 1000 matching the cited precedent — but repo-wide grep confirms it is never read by any code path. Its only other appearance is a compile-time static assertion in include/starkernel/vm/stadium.h:118 checking it's > 0, which gates nothing at runtime. vm_physics_heartbeat_tick() still literally shares HEARTBEAT_INFERENCE_FREQUENCY, i.e. the code is still in the pre-implementation state §22.4 described as its starting precedent, not the resolved design it specified.

  Also found in passing, minor and not a correctness issue: vm_tick()'s own header comment (vm_runtime.c:104, "Aggregates all periodic optimization tasks (Loop #3 and Loop #5) into one place") is stale — Loop #3 is not called inside vm_tick(), it's called separately from vm_heartbeat_run_cycle() on the faster 256-execution cadence, not the 256,000-execution one vm_tick() itself gates.

  Where this leaves Q5: within a single cadence tier (the 256-execution cluster, or the 256,000-execution cluster), several nominally-distinct loops share one gate with zero separation between them — apparently intentional unification (Phase 2's "Unified Inference Engine" merged #5/#6, L8 explicitly reads #1–#7's latest outputs each vote), not obviously a bug. Between tiers, separation is comfortably past the order-of-magnitude minimum (256:1 and 1000:1). The one place separation is required by name and is not actually present is the heat/capacity pair finding #1 above — that's the concrete, verified answer to "the risk is interference." Left open, not fixed, per this document's discipline — whether to wire STADIUM_CAPACITY_TICK in for real (giving Hera her own slower cadence independent of per-VM tick counts) or something else is Captain Bob's call, not made here.

• §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.

  CHECKED 2026-08-13, still correctly not ripe — precondition refined, item left open. The actual FABRIC.md text (end of §17.5, not really §17.4 — that section number is a loose reference to the same "OPEN, deferred" paragraph) is explicit: "What those dynamics are is a question for when the framebuffer work actually happens... it should not be designed speculatively now." The console/framebuffer work (item 4.3/4.4 series) has since substantially shipped and is live, which looks at first glance like that precondition is now met. It isn't: grepped src/starkernel/hal/framebuffer.c, vt100.c, console.c (1,800 lines total) for heat/decay/dirty — zero hits. Every write is immediate-mode (fb_scroll_rows(), fb_scroll_rect(), direct glyph blits at the point of writing); there is no damage list, no dirty-region tracking, nothing a per-region heat/decay scheme would even attach to yet. That's consistent with Section A's item 1.11 (dirty-event granularity) still being unstarted — this item's true prerequisite is 1.11, not "the framebuffer work" in general as originally framed here. Designing framebuffer-internal physics before the dirty-event mechanism they'd govern exists would be exactly the speculative work FABRIC.md warns against. Left open, framing corrected: blocked on item 1.11, not merely deferred.

• §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.

  SETTLED 2026-08-13, but not as originally framed. Read Hermes v1's real message struct (capsules/hermes/init.4th, blocks 4100/4105/4143, item 4.2): MSG-CELLS is 9 cells — TYPE, FROM, TO, PADDR, PLEN, STADIUM-CELL, SEQ, CH, ORIG-TYPE — at 8 bytes/cell (cell_t is int64_t/long, include/vm.h:71-75), i.e. 72 bytes, already over §23.3's whole proposed 64-byte cell before any payload. And the payload itself is not inline at all: MSG-SEND (:208-213) takes a caller-supplied paddr plen — wherever the caller already put the bytes (a string literal via S", a block buffer) — and stores only the pointer and length in the struct. There is no fixed-size inline payload field to check a message against. So §23.4 #2's literal question ("does a typical message fit in the 32-byte inline payload") is moot, not answered: the shipped design didn't adopt §23.3's speculative 64-byte-cell/32-byte-inline-payload scheme for messages at all, it used a larger fixed control block plus out-of-line pointer/length indirection instead. Closing as settled-by-divergence — the real implementation went a different direction than the design question assumed, which is itself the answer; §23.3's cell-size numbers were never made load-bearing for Hermes messages and nothing here depends on reconciling them.

---

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."

  DONE 2026-08-13. ONTOLOGY.md already existed and already did exactly this job for the original heat/decay/inference vocabulary (Section III's lexicon, Section 3.2's "avoid/deprecated terms" table) — it just predated the Stadium work entirely (confirmed: zero mentions of "Stadium," "patron," "mass," or "density" before this edit) and was never extended to cover it. Added new §IX "Stadium/Fabric Vocabulary" in the same format as the existing lexicon: a metaphor-mapping table, alphabetical definitions for Cell, Code field, Density, K, Mass, Mass-vs-heat-conservation, Patron, Reap, Stadium, Warehouse, and Utility (all cited back to their FABRIC.md DECIDED sections, not invented), plus a Kconfig-knob-to-concept table with verified, not assumed wiring status for every STADIUM_* symbol — including flagging STADIUM_CAPACITY_TICK as dead, the same finding this document's own §12 Q5 closure made independently, now cross-referenced from the glossary too. Bumped ONTOLOGY.md to v1.1 with a version- history entry. No FABRIC.md/FABRIC-2.md content moved — this is a new, additive section in the document that already owned this job.

• 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.