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:
co-authored by
Claude Sonnet 5
parent
b6872d28ae
commit
aba0b01a08
@@ -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.** §1–15 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.** §1–24 (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 §1–24, 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.** §1–15 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.5a–4.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.5a–4.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
|
||||
|
||||
Reference in New Issue
Block a user