Robert Allan JamesandClaude Sonnet 5
aba0b01a08
FABRIC.md did its job: §1-24's design argument is settled and every implementation item through 4.5/4.4ac either landed or was explicitly deferred with a reason. At 7,595 lines it was no longer a good place to find what's actually still open, so it's now archival -- header rewritten to say so, pointing to FABRIC-2.md. Before closing it, read the entire document end to end (not sampled) looking for anything unresolved: punch-list checkboxes, the nine "### N.N Open" architectural subsections in §1-24, the §25.7 "reported, not scheduled" list, and any other "not yet"/"deferred" language. Found and fixed four stale bookkeeping spots where later work had actually resolved something but the note was never updated: §19.6 #3 (resolved by item 2.1), §21.5 #4 (resolved by §20.5 #4), the §25.7 stadium_owner[idx] bullet (resolved by item 4.2), and item 4.5's own parent checkbox (all six sub-items 4.5a-4.5f were already [x]). FABRIC-2.md carries forward everything genuinely still open: the blocked/scoped punch-list items (1.11, 4.3, 4.4s, 4.6, 5.1-5.3, plus a specific pending TRIPOD.md edit found within 5.3), two regressions that were invisible with Tripod pruned to Hera-alone and are now live since item 4.2 restored Hermes (the fleet heat leak in vm_physics_touch(), and multi-VM heartbeat ownership), nine dead-code/ cruft reports, three open design questions (§12 Q5, §17.4, §23.4 #2), and two documentation-debt items (the taxonomy/glossary Captain Bob flagged 2026-08-04, and re-measuring ACL-RWT DoE overhead now that real compiler optimization is enabled). Also includes BLOCK_MAP.md/artemis.img/amd64.csv regenerated by builds during this session, and a qemu boot log/DoE run that weren't from any command in this session -- kept per repo convention, logs are audit artifacts, not deleted. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
123 lines
6.8 KiB
Markdown
123 lines
6.8 KiB
Markdown
# 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
|
||
|
||
- [ ] **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.
|
||
|
||
- [ ] **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.
|
||
|
||
---
|
||
|
||
## C. Reported bugs and dead code, not yet fixed
|
||
|
||
- [ ] `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.
|