Close FABRIC.md, open FABRIC-2.md as the living document

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>
This commit is contained in:
Robert Allan James
2026-08-12 18:45:13 -04:00
co-authored by Claude Sonnet 5
parent b6872d28ae
commit aba0b01a08
7 changed files with 8887 additions and 74 deletions
+54 -42
View File
@@ -1,14 +1,32 @@
# FABRIC.md — the Stadium
**Status:** Living working document. Started 3 August 2026 and appended to as work proceeds.
Sections are marked **DECIDED**, **LEANING**, or **OPEN** so they can be argued with rather
than inherited.
**Status: CLOSED, 2026-08-12.** This document is archival. It is not edited further and no
new work is added to it — everything still open as of the closure date was carried forward
into **`FABRIC-2.md`**, which is now the living document. Read `FABRIC-2.md` first for
current status; come back here only for the historical design argument and decision record
behind it.
**How to read it.** §115 are the original design argument, written before any code was
examined. §16 onward are findings and decisions made against the actual tree, in the order
they happened. **Where the two disagree, the later section wins** — earlier text is left
standing, with a pointer, because §19.4 and §19.5 quote it directly and because retracing
the reasoning matters more than a tidy read.
**Why it's closed, not just superseded.** §124 (the theory) and §25 (the punch list) did
their job — the design argument is settled, and every implementation item through 4.5 and
4.4ac either landed or was explicitly deferred with a reason. Closing a finished document
rather than continuing to append to a 7,500+-line file keeps the still-open work findable;
the alternative was letting it stay buried among hundreds of resolved items.
**The 2026-08-12 closure audit.** Before closing, the entire document was read end to end
(not sampled) looking for anything not yet resolved — punch-list checkboxes, the nine
"### N.N Open" architectural subsections in §124, the §25.7 "reported, not scheduled" gap
list, and any other "not yet"/"deferred"/"still open" language anywhere in the text. Four
places were found where something had actually been resolved by later work but the
document's own note was never updated (§19.6 #3, §21.5 #4, the §25.7 `stadium_owner[idx]`
bullet, and item 4.5's own parent checkbox) — those four are fixed in place below, since
they were bookkeeping errors, not open work. Everything else genuinely still open is in
`FABRIC-2.md`.
**How to read what remains.** §115 are the original design argument, written before any
code was examined. §16 onward are findings and decisions made against the actual tree, in
the order they happened. **Where the two disagree, the later section wins** — earlier text
is left standing, with a pointer, because §19.4 and §19.5 quote it directly and because
retracing the reasoning matters more than a tidy read.
**On the name.** The thing described here is the **Stadium**. "The arena" was the working
name until it collided with `src/starkernel/vm/arena.c` — the PMM-backed VM page allocator,
@@ -16,25 +34,8 @@ an unrelated structure. The document has been swept; "arena" now survives only i
quotes that reproduce an earlier section verbatim, and in §12's preserved question list,
which several sections quote.
**§25 is the punch list.** It is the authoritative statement of what is done and what is
not. Read its instructions before doing any work against this document.
**On `docs/lithosananke/ROADMAP.md`.** As of 2026-08-11, Captain Bob has stated this
document supersedes ROADMAP.md **entirely, not just the M8 section already marked
obsolete inside it.** Do not consult ROADMAP.md for status, scope, or design — not for M8,
not for anything else in it. Where this document and ROADMAP.md would disagree, this
document wins by default, full stop; there is no need to cross-check. FABRIC.md is the
living document now.
**NEXT SESSION — FIRST TASK, before any 4.4-series work:** Captain Bob flagged 2026-08-11
night that punch-list items are scattered throughout this document (interleaved with
narrative/design reasoning) rather than collected in one place, and the document is getting
cluttered as a result. **Refactor so all punch-list items live together at the end of the
document**, reorganizing what exists today rather than just changing the rule for new
entries — a full pass, not a partial one. Do this *before* resuming 4.4w or anything else in
the punch list, per Bob's explicit instruction that it's the first thing to do. Preserve
every item's content (including its `> Done`/blockquote history) exactly — this is a
structural move, not a rewrite, and must not lose or alter any decision already recorded.
**On `docs/lithosananke/ROADMAP.md`.** As of 2026-08-11, Captain Bob stated this document
superseded ROADMAP.md entirely. That still holds, transitively, through `FABRIC-2.md` now.
---
@@ -1557,11 +1558,11 @@ noun was overloaded.
2. ~~**Is mass constant for a patron's lifetime?**~~ **RESOLVED by §24.3** — mass changes
only through an arbitrated transfer, never through traffic, so density is stable between
transfers and §13 gets a mass function that changes at enumerable points. (D2)
3. **How does traffic transfer heat between patrons, concretely?** `vm_physics_touch()`
does this today for VMs, but it scales the transfer by wall-clock elapsed time
(`capsule_vm_physics.c:272`), which §18.5 forbids for anything influencing patron state.
**The transfer rule must be restated on tick count before L0 can use it.** This is the
single most concrete piece of work this section implies.
3. ~~**How does traffic transfer heat between patrons, concretely?**~~ **RESOLVED by item
2.1** — `vm_physics_touch()` was restated on the virtual tick (no `now_ns` parameter at
all), closing exactly the gap this point raised. This item's own cross-reference (*Refs:*
§19.6 #3) points back here; this note closes the loop the other direction. Never annotated
here at the time (found during the 2026-08-12 FABRIC-2.md audit).
---
@@ -1879,9 +1880,11 @@ level it was born on.
3. **§12 Q4 / §7 / §17.6(c) elasticity becomes the live question.** Nesting is what makes
capacity transfer between VMs meaningful, so the hard-versus-elastic decision can no
longer be deferred as an abstraction — it is the next real fork.
4. **§20.5 #4 remains open.** Nesting is two levels here. Whether a patron may itself
contain a Stadium — a tree rather than two tiers — is still deliberately unruled.
Nothing requires it; it should be excluded on purpose rather than by omission.
4. ~~**§20.5 #4 remains open.**~~ **RESOLVED by item 1.7 (§25.2), 2026-08-04** — this
section (§21.5) was written before that ruling and never updated to point to it. Bounded
by a Kconfig-tunable cap, default 2, enforced at VM-birth time. See §20.5 #4 for the full
resolution. Stale cross-reference, not new work (found during the 2026-08-12 FABRIC-2.md
audit).
---
@@ -6179,7 +6182,7 @@ document and committing that amendment as its own item.*
> scrolled-back view"
> case 4.4q's own comment block already calls out as known and out of scope.
- [ ] **4.5 — URGENT, flagged by Captain Bob 2026-08-11: the kernel build has never used any
- [x] **4.5 — URGENT, flagged by Captain Bob 2026-08-11: the kernel build has never used any
compiler optimization.** **Blocking priority, set by Captain Bob 2026-08-11: no other
punch-list item is worked until 4.5a4.5f are done**, ahead of whatever would otherwise
come next in sequence. Found while investigating why moving `console_fb_init()` earlier
@@ -6241,6 +6244,14 @@ document and committing that amendment as its own item.*
scoping only, per Captain Bob's explicit instruction 2026-08-11.
*Refs:* discovered via 4.4g; independent of Console work.
> **Parent closed 2026-08-12.** All six sub-items (4.5a4.5f) below are `[x]` done; 4.5f's
> own done-when is satisfied by 4.4g's real landing, not a separate pass. This checkbox was
> never flipped at the time — pure bookkeeping, not new work (found during the FABRIC-2.md
> audit). One real loose end surfaced by 4.5f's own text, not closed by any of this: the
> ACL-RWT DoE campaign's overhead numbers (CLAUDE.md, "+0.0054%+0.0088%") were all measured
> at `-O0`, before this item enabled real optimization — nobody has re-measured or even
> asked whether they're still comparable. Carried forward to FABRIC-2.md.
- [x] **4.5a — Full ISR/interrupt-context global-state audit, all three architectures.**
Investigation only, no code change. For each architecture, enumerate every vector actually
wired to a handler (amd64: IDT/APIC vectors in `arch/amd64/interrupts.c`; aarch64: GIC
@@ -6766,12 +6777,13 @@ so.*
ever been verified via its `Makefile.starkernel` `kconfig_int`/`kconfig_bool` default. Nobody
has run `make -f Makefile.starkernel menuconfig`, changed a value, and confirmed it actually
flows through to a build. Flagged by Captain Bob 2026-08-05.
- **`stadium_admit()` never writes `stadium_owner[idx]`**, on either the free-list-pop or the
eviction-fallback path (found during item 4.1's design pass, 2026-08-05). Harmless today
every cell's owner byte is `0` (Hera) from `stadium_boot_init()`, and Hera is the only VM
with a quota — but once item 4.2 restores Hermes, a resident's evict-credit (item 4.1's
reservoir accounting in `stadium_evict()`) would flow to the wrong VM's reservoir unless
this is fixed first.
- ~~**`stadium_admit()` never writes `stadium_owner[idx]`**~~, on either the free-list-pop or
the eviction-fallback path (found during item 4.1's design pass, 2026-08-05). **RESOLVED
folded into item 4.2's scope by explicit Captain Bob ruling**, fixed and verified: a
resident cell's evict-credit lands in the correct VM's reservoir with two VMs holding
quotas (Hera + Hermes), not just asserted from reading the code. This bullet was never
struck through at the time; stale, not new work (found during the 2026-08-12 FABRIC-2.md
audit). See item 4.2's *Done when* list and its 2026-08-05 addendum.
- **Taxonomy and lexicon.** Raised by Captain Bob 2026-08-04, mid-item-3.1. This document's
physics-flavored vocabulary (heat, mass, density, patron, Stadium, and the rest) needs a
glossary that is explicit these are named analogies, not physical claims — and that also