Files
LithosAnanke/.claude/memory/reading-2026-11-17.md
T

955 lines
79 KiB
Markdown

# The full reading, 2026-11-17 (Captain Bob: "read EVERYTHING" -- after the regression)
Why: v4's boot slowed ~2.4x on aarch64 at 046ce0be (2026-11-13 17:00, "the mesh boot to spec ... every node
stepping together"): protocol stage times amd64 107->184 s, aarch64 209->499 s, riscv64 105->163 s (f10d2bc8 ->
046ce0be, same 539-case POST). The lock-step `v4_fabric_step` -- one instruction word per awake node per step,
round-robin, with ~10 passes over 16 places and their ports around each word -- is a scheduler, and it was put in
after Captain Bob asked "Scheduler? Have we regressed?" and was told no. Everything since (Phase 2, Phase 7, the
whole-POST work) sits on it. His instruction: find when, start over from there, after reading EVERYTHING; his
method -- incremental documentation, intent and verification stated, auditable data -- not mine.
Notes are per batch, in reading order. Where the record disagrees with the tree or with what I told him: marked
**DISAGREES**.
## FABRIC-0.md (the Stadium; CLOSED 2026-08-12)
### Lines 1-400 (§1-§10)
- Later sections win over earlier; earlier text left standing with pointers.
- §2 Stadium: one bounded region outside any VM, allocated at boot, not the heap; holds what is LIVE, not all
that exists. §3 one entry shape (+ continuation cells, side bitmap), code field is the whole type system.
- §4 Heat is conferred by traffic. **"Ranking is read, not decided. There is no scheduler because there is no
policy."** K constrains the total: "the defensible distinction from a scheduler".
- §6 Boot order: LithosAnanke establishes the Stadium and starts the engine; Hera is its first entry; Hera
births everything else.
- §8 containment (`contains`), not locks; a priority among blocked chains "is a scheduling question" -- deferred.
- §10 POST is the regression gate (every dictionary word).
### Lines 400-1800 (§11-§21)
- §11 debt: never two live mechanisms at once; no speculative generality; a special case is permanent.
- §16.1 (v3 era) no IRQ return path on aarch64/riscv64 then; §16.4 + GAP-A1 RULED 2026-08-03: **the engine's
tick is virtual -- a pure, deterministic function of the execution stream**; the hardware heartbeat is the
TIME-TRUST instrument and idle wake source and "the driver of nothing that feeds patron state".
- §17 patrons (blocks, words, ACLs, messages, VMs); three departures (TTL, heat decay, pin); reap = leaves the
floor. §17.3 hot words are the patrons, the dictionary the warehouse; the old cache's round-robin eviction is
"exactly a policy ... uninformed by the physics". §17.7 word heat conserved via a per-VM reservoir, O(1).
- §18 L0 the engine, ungated (as L8); dispatch on behaviour tags, not kinds. §18.5 **"Anything that influences
patron state advances on tick count. Wall-clock time ... must never be an input to a decision."**
- §19 K = conserved heat share (Σ = 1.0), mass = cells, density = heat ÷ mass; ranking reads density, admission
= denser than the least dense resident: "a comparison of two intrinsic numbers, not a policy".
- §20 VMs are patrons; Hera pinned, her eviction a panic; outer bound refuses births. TRIPOD: fleet K is
"lifecycle telemetry, not a dispatch mechanism ... never decides where work goes".
### Lines 1800-2700 (§21-§25.2)
- §21 nested Stadiums; §21.2 **"Nothing in interrupt context may mutate Stadium structure. Ever."** ISR = top
half (counter + flag), mainline = bottom half. §22 elastic quotas over one cell pool, per-VM free lists;
capacity moves 1000:1 slower than heat. §24 identity/mass stable while resident.
- **§25.0 -- HOW TO WORK (his method, read before every item):** one item at a time, lowest first; do not jump
ahead or reorder unasked; **do not increase scope** -- report, don't fix; **do not fabricate, confabulate or
conflate** ("A wrong answer stated confidently has cost this project git resets before"); when blocked, stop
and report; acceptance is the item's own *Done when*, observed; report failures honestly; one item, one
commit, with the document's checkbox; **"The design is not sacred ... stop, report what the code
demonstrated, and propose the amendment. Amend the relevant section of this document first, get agreement,
then continue."**
- Phase 0 (v3 substrate, done 2026-08-04): real IRQ return paths, timers on three ISAs, one tick path; the
hardware tick drives instrumentation only; acceptance included a double boot with identical dict_hash.
### Lines 2700-3400 (§25.2-§25.5 item 4.2 start)
- Every item's DONE note shows the method in practice: what was built, **what was verified and how** (logs by
path, dict_hash per arch), **honest limitations** ("unexercised at runtime, stated plainly rather than implied
by a passing boot"), bugs caught before shipping, scope additions only by explicit ruling, prerequisites found
mid-item inserted as new items (3.7, 3.8, 4.1a) rather than silently built.
- v3 Stadium built: cells, density, admission, Hera patron zero (panic on eviction), per-VM free lists, VMUuid
(deterministic splitmix64 from Mama's hash), hot words on the Stadium with the reservoir (4.1), quota grant
(4.1a: even split), Hermes native (4.2).
### Lines 3400-4050 (§25.5: 4.2 done, 4.3.x Console groundwork, keyboard/PLIC bring-up)
- 4.2: a design question spanning two items (word dispatch draining the shared reservoir) was **reported for a
ruling rather than patched** -- options listed "no ranking, not decided here"; ruled option 4 (floor).
The effort number was recorded (files, lines, session time) because §10 asked for it.
- The record's honesty pattern again: "a header nothing compiles proves nothing"; "conflating the two was an
error" (REPL/dict_hash parity vs framebuffer presence); amd64-only checks flagged as such.
- Debugging lessons kept: GDB unusable on this kernel; print bisection only; LOG_INFO below threshold.
- 4.3.5a: a prerequisite discovered mid-item was **stopped and scoped as its own item** (Bob: "decide the
approach in a future session with fresh context"), not decided inside the item that found it.
### Lines 4050-6600 (§25.5: 4.3.5c-4.4ac console/keyboard/TTF/REPL; 4.5-4.5d -O2 enablement)
- Each bring-up finding was root-caused before any fix, then the fix applied only on his word ("Not applied --
reporting only, per Captain Bob's Law"), the tree reverted to clean between diagnostic builds.
- -O2 findings: FORTIFY, putc/getc, muldiv64 RDX clobber (#DE), lidt "r" constraint -> dead-store-eliminated IDT
(#GP vector 32). Same bug class twice: inline-asm constraint weaker than what the asm touches. Fixed with "m".
- Verification per arch: boot to ok>, POST Failed: 0, dict-hash identical across all three, warning-count diff
against the -O0 baseline (and a -j interleave artefact ruled out by a serial rerun, not assumed).
### Lines 6600-7120 (4.5d-4.5f, 4.6, Phase 5, §25.7, §25.7.1, §26, §27 start)
- 4.5f: an informational experiment run, captured, and **reverted** because the decision (4.4g) was still open;
"What this answers and doesn't" stated separately. A real cost (~12x heartbeat ticks) recorded as new data.
- 5.1: "A green POST suite is not evidence that K holds; those are different claims."
- §25.7 Reported, not scheduled -- found while reading, "They become items only if Captain Bob says so".
- §25.7.1 second review pass: triage order; the GAP-A1 virtual-tick ruling's argument preserved as record.
- §26 adaptive heartbeat RULED: Loop #7's logic reused unmodified on the 10 ms base; **§26.4: "one is not
required, and adding one would need a preemptive scheduler this single-hart kernel does not have ... No
pthread, no kernel task, no scheduler."** Single-writer (mainline) / single-reader (ISR) shape.
- §26.5 deferred: multi-VM -- "whose tick_target_ns drives the one physical timer" -- not resolved for Tripod
return. **Relevant to the regression:** the record deferred the many-node question; it never ruled that
every node steps together in lock-step.
### Lines 7120-7622 (§27.5-§27.8: keyboard, PLIC/GIC derivations, glyphs, TTF, REPL) -- FABRIC-0 DONE
- "No polling, anywhere" carried as the hard constraint through every keyboard item; interrupts are the
substrate. Derivations done live from QEMU's own DTB, "derived live rather than assumed".
- §27.6.2: untested stack code is not presented as settled -- "exactly the kind of confidently-wrong mistake
§25.0 rule 4 warns against".
- §27.7 correction: a grep-shallow check produced a wrong "open question"; a full read of mkcapsule.c
superseded decision #3. **The lesson the record itself draws: read in full, don't grep-skim.**
- §27.8: "found by checking the tree per §25.0 rule 4, not by assumption"; things assumed live
(VT100-on-framebuffer) never were, because they were never screendump-verified.
## FABRIC-1.md (CLOSED 2026-08-25; carried 51 open items into FABRIC-2 §A)
### Lines 1-1500 (§A-§J)
- **§F.2 (2026-08-15), directly on point:** the first fix proposed for the capacity cadence ("threshold scaled by
live VM count") was **rejected by Captain Bob before implementation -- "reading VM count at the check site to
adjust a rate dynamically is the first brick of a scheduler, which is exactly the kind of machinery this
project has deliberately avoided building."** Fixed instead with one flat constant on the one clock.
- §G: "the clock is only the heartbeat, period" (his pushback, confirmed against FABRIC-0 §16.4/§17.1's
one-clock rule). VM population made RAM-derived at boot -- no fixed ceiling ("could be 4, could be 4000").
- §B: multi-VM heartbeat ownership RULED: one physical timer, Hera alone writes its period; every other VM's
Loop #7 adapts its own bookkeeping. No node takes turns -- each VM runs its own vm_tick on its own execution.
- §D §12 Q5: loop cadences are execution counts (1, 256, 256000); a shared fleet counter fed by all VMs
violated "capacity must be the slower loop" -- **shared, fleet-wide stepping state is where the trouble came
from.**
- §H/§I: method again -- before/after data on all three arches; a hypothesis he doubted ("introducing momentary
dishonesty") tested cheaply, refuted, **reverted**; a wrong conclusion corrected in place, not erased.
- §J: a "zero warnings" claim found false and corrected; a test-authoring bug "worth recording as the caught
mistake it is, not silently fixed".
### Lines 1500-3000 (§J-§V: POST coverage clusters, cookbook/SDK/FENCE, DoE campaigns, ACL-TTL, Artemis PKI)
- POST coverage added cluster by cluster, each: read the C, write tests in that file's style, boot, verify the
counts moved by exactly the number added. Two real production bugs found by tests (vm_ptr vs host pointer;
dsp off-by-one). Probe-capture-revert never lands in a commit.
- FENCE (2026-08-19) exposed the existing dict_fence; a FORGET use-after-free found and fixed, with a POST case
so it can't regress. **v3 FENCE semantics are a recorded design: one word, raise the fence to the top.**
- §M-§O: campaign discipline -- ISA-blocked order rejected by Bob ("confounds ISA with time/session-order");
discarded cells kept as audit artefacts, not deleted; randomized order; clean build per cell.
- §P-§T: **"the adaptive heartbeat tick counter is the one and only clock"** (`vm->heartbeat.tick_count`,
Loop #7), not host wall-clock; Section P invalidated in place (ACL never armed), Q corrected, R the real
fix, S/T the final figure (+0.0603%, CV 0.000%, arch-independent). Wrong sections stay, marked.
- §U-§V: Artemis/PKI design notes only, nothing implemented; gap analysis checked against the tree.
### Lines 3000-4420 (§W-§X Artemis milestones 1-9) -- FABRIC-1 DONE
- 2d: interrupt-driven xHCI was built, then **reverted** after a live check proved the routing formula wrong;
reframed to Bob's own spec ("interrupt-driven, coarse cadence, cheap early-exit") as a poll from
sk_repl_idle() -- the idle wake path, not a fleet step.
- A HEARTBEAT-TICKS@ "stall" was a false alarm: vm->heartbeat.tick_count is per-VM, advances only on that VM's
own execution. **Each VM's clock is its own execution stream -- there is no shared fleet step in v3.**
- Recurring self-caught errors recorded in place (stale log picked by `ls -t`; a glibc misattribution; a
hand-derived crypto claim) -- lesson recorded: "treat any hand-derived claim as unverified until checked
against an independent source". **The PID's command line is the ground truth for which log is mine.**
- §X.3: relocation primitive is mechanism only; "Policy is explicitly out of scope here, by design" -- ACL
decides when.
## FABRIC-2.md (CLOSED 2026-09-04)
### Lines 1-1044 (§A carried items; Phase 8 PKI: homeblocks sig, zuse cert, virtio-rng, Ed25519 sign, meta fence)
- **"No files, ever -- this OS's entire reason for being is anti-POSIX, anti-file."** (Bob, 2026-08-26.)
- **"No stubs or TODOs, ever"** (a §C standing rule, to come). "Don't build ahead of a real caller" -- the
refuse half was deferred until WRITE(10) existed.
- A risky enforcement landed WARN-only first, proven both directions on three arches, then flipped -- and
narrower than planned (INVALID only), because MISSING is normal off this machine.
- NVRAM persistence crashed; it was localized with one-boot debug markers, root-caused, and **reverted to
known-safe**, with "do not retry as designed" written down. A second design defect (an exposed seed) was
recorded independently of the crash.
- A hand-summed pad size was off by 4; caught by `_Static_assert` + offsetof, "never trust a hand-derived numeric
claim".
### Lines 1044-1744 (§B Stadium unification, §C no stubs, §D Tripod shape, §E the pile as a graph)
- §B: "words/VMs/blocks/messages ... all should be operated on by THE SAME ENGINE" -- the engine is
stadium_dispatch on departure (MIGRATE/DELIVER/COOL/EXPIRE); **the engine acts on patrons, it does not
schedule VMs.** VM-patron admission/COOL built; each VM's own words/blocks heat on its own execution.
- §B: a lib.4th shadow of the C primitives USE/RUN was reported first, then fixed on request.
- §C: **no stubs or TODOs, ever** ("I've never allowed stubs before").
- §D.2: **"a session IS a VM"**; VMs doing work are "players on the field"; "When Hera has no VM attached
beyond fleet-servicing strata, she idles, watching services" -- idle is a normal steady state.
- §D.1/D.2b: messaging-only end state -- "nothing is done until it's messaging" -- and the pentagon of five VMs
(Hera, Hermes, Artemis, user VM, Console), with Hermes as the medium.
- **DISAGREES with 046ce0be's premise?** Nothing here says VMs advance in lock-step. Each VM runs its own
execution; Hermes MSG-DELIVER runs VM-EXEC of a payload on the target. To check against FABRIC-3/3.5+.
### Lines 1744-2444 (§F.1-F.14, D.5: scoped Q&A per graph node)
- Method: "Traced against the live code before asking anything"; each node gets decisions recorded, plus "Not yet
scoped (deferred within this node)". Real gaps found mid-trace become new graph edges (WIREBIND <- CERTVERIFY,
RUNCAP), not silently absorbed.
- Bob's standing instruction (F.2): **don't grow struct VM feature by feature; real-shaped data gets its own
header, integrated as a field.**
- F.10: a pre-existing KILL dangling-pointer bug was "reported, not fixed".
- Nothing in this range about how VMs are stepped; each VM's work is driven by its own REPL/message.
### Lines 2444-3144 (§F.3-F.23: HOTPLUG, D.6/D.7, Phase C, RUNCAP, MINT, console pair, WIREBIND)
- **Phase C (2026-08-28), the v3 shape of "many VMs":** every VM gets its own messaging vocabulary and arena;
**"Idle-loop pump: sk_repl_idle(), ~1s cadence -- Hera walks every live registry entry except her own and
VM-EXECs MSG-TICK into it -- fully distributed, Hera pumps each VM's drain."** Other VMs run only when a
message or command is delivered to them (VM-EXEC on demand). There is no per-instruction interleaving of
all VMs.
- §F.15: "every VM is a Forth VM instance living inside one kernel address space, not a separate OS process" --
the reason to message is uniform heat tracking + audit, "not solving an isolation problem".
- §D.7: "Hera gives birth only by request ... no coupling outside of messages"; Artemis/Hermes stay born.
- §F.22: console->user VM relay is async MSG-SEND, delivered on the next idle tick ("~1s cadence is the console's
own round-trip latency ... acceptable for v1").
- Bugs found live were fixed at the source (console_set_vm_name stored a raw pointer); diagnostic words
(RUNCAP-TEST, PAIR-TEST) were flagged as scaffolding that must not survive.
### Lines 3144-3844 (§F.23-F.27, §G v2.0.0/v2.5.0 releases, §H.1-H.5 session refactor)
- F.25: Bob's pushback "i know this machine, it's never that slow" -> the slowness was root-caused (60 leaked
`tail -f` processes; 200s -> 26s), not explained away as "slow TCG". **Precedent: slowness gets root-caused,
not tolerated.**
- F.26: what looked like a hang was a correct silent decline plus the busy-poll idle loop; `LOG_INFO` is filtered
after the REPL starts ("don't trust LOG_INFO silence as not reached").
- §G: release policy -- X.0.0 is the QEMU release, X.5.0 is hardware; three products; patent clocks
(Dec 2026).
- §H.1: **"a process and a virtual machine are going to be exactly the same thing"**; a session is a Stadium
patron; Hermes/Artemis are pinned. §H.3: each VM has its own dictionary; ACL snapshot at birth.
### Lines 3844-4832 (§H.5-H.12 session refactor built, §I consolidated punch list) -- FABRIC-2 DONE
- **H.12 item 19, Bob: "NEVER, EVER do that"** -- a policy check written into a C primitive. Then: "there is
nothing special about zuse session, it's just a session", "full superpowers can be determined by the lack of
ACLs". **Policy lives in ACL.4th / FORTH, never in C; no bespoke gates.**
- H.12: each punch item -- one coding task -> 3-arch boot; corrections recorded inline ("Correction 1/2");
premises re-verified against live code before building, not trusted from the item text.
- H.12 item 11: a snapshot was deliberately placed after dict_hash so the hash stays a pure function of capsule
content -- **the determinism invariant is load-bearing.**
- I.9: a first-pass "not reproduced" was wrong -- the defect was in the logs and was misread; the record keeps
"SUPERSEDED, kept for the record because the misread itself is instructive". Root cause to specific lines,
"Not fixed -- reported per this project's identify, don't fix unless asked rule", then fixed on "Yes, fix it".
- §I.6: real hardware has never been booted (as of 2026-09-04).
## FABRIC-3.md (bare metal boot; living through 2026-11)
### Lines 1-700 (§I.1-I.2 merge/version, §II-IV aarch64 Pi 5 native, start of §V riscv64)
- Write-up before executing; the plan re-verifies its own precondition (`--ff-only`); acceptance on a
genuinely clean tree "not inferred from the fast-forward".
- Version labels got ahead of reality and were corrected: "claiming 2.0.1 implies hardware-track progress
that was never actually verified".
- Audit passes are report-only unless a finding is named by direct instruction; each fix exercises the guard
on QEMU and states that the success branch is unverified until hardware.
- §IV.3 item 5: a half-finished Broadcom PCIe mode was refused -- "compile and boot cleanly while silently
never working, exactly the half-finished implementation this project's own conventions rule out".
### Lines 700-1350 (§V riscv64 Mars, §VI hardware reference, §VII xHCI multi-device, §VIII headless console)
- §VII.1, Bob: "We MUST fix that! It was a deliberate choice at that time and is no longer true." §VII.4, Bob:
**"we REALLY need to not paint ourselves into ANY scale issues by taking an easier way out."** Size from the
hardware's own value (max_slots), not a chosen small N.
- §VII.3: separate the state that must become per-instance from the in-flight state that stays
single-outstanding -- "the difference between a bounded, scoped refactor and a full concurrent rewrite".
- §VII: halted before code, "pending Captain Bob's explicit okay"; then "okay, go ahead and implement it".
- §VIII.1: **"no thumbdrive, no prompt"**; headless until login, with the idle loop (`heartbeat_service()` +
sk_repl_idle()) still running. "there should be nothing special about zuse as a user except zuse has no
acl's".
### Lines 1350-2050 (§IX-§XI: 8 identities, leaks, allocator, ports, lockdown, Hera->Artemis messaging)
- IX.4, Bob: **"we should never see an unauthorized, no session forth prompt."**
- X.4, Bob: the number of concurrent VMs is "not knowable in advance"; the heap must use real memory, no
compile-time ceiling (sf_malloc moved onto kmalloc).
- XI.2: Hera's idle pump VM-EXECs `MSG-TICK` into every live VM each idle tick; Hera itself can't load
messaging.4th. The storage attach became a real Hera->Artemis->Hera message round trip.
- XI.3, method: "the single highest-leverage move" was a fresh subagent reading the code cold after hours of live
forensics hadn't converged; the record names the "framing trap" plainly instead of editing it out. **And a
self-inflicted unbounded scan in the idle tick blocked everything** -- fixed with a per-tick budget so idle
work stays "coarse cadence, cheap early-exit".
- XI.4: a guest's fault must not halt the machine; only Hera's own session halts.
### Lines 2050-2750 (§XII-§XIX: std79 exerciser, heap UAF, DoE 81/81, Stadium O(ncells) fix, K, VM-HEAT)
- XII.3/XIII: stale `active` VM pointer captured before a blocking read -> UAF -> heap free-list corruption;
fixed by re-resolving the live VM every idle tick. Kept debug census as permanent infrastructure; reverted every
other probe.
- XII.4: real slowdown "per-tick MSG-TICK pump cost grows" with more live VMs (the O(N) idle pump).
- XVI: **a doc comment said "scoped to that VM's own resident patrons" but the code scanned all ncells -- the doc
and the code had silently diverged** -> 90-minute stall on aarch64; fixed with a per-quota resident list.
"Any defect repair requires rerunning the DoE from the top."
- **XIX (2026-09-12), THE PRECEDENT FOR THIS REGRESSION:** in v3 "exactly one VM's FORTH code executes at any
instant"; dormant VMs accrue zero ticks. **"Design direction agreed with Captain Bob: fix the gap without a
scheduler. A fixed round-robin across identities would just be a different hardcoded policy -- not in the
spirit of a runtime whose whole design principle is finding its own attractors rather than being told what
to do."** The chosen direction: a turn-attractor -- the next turn goes to the live VM with the lowest
execution_heat (same judgment as stadium_admit's coolest-resident eviction). Read on: XX-XXXVI.
- **DISAGREES with 046ce0be:** `v4_fabric_step` steps every awake node one word, round-robin -- exactly the
"fixed round-robin ... hardcoded policy" XIX rejected.
### Lines 2750-3510 (§XIX-§XXVIII start: turn-attractor, Hera messages by symmetry, O(N) pump fix, --resolve)
- XIX/XXI: the turn-attractor -- "No priority levels, no time slices, no preemption -- the same density
comparison Stadium already uses, applied to who goes next." It lives in the fleet layer
(capsule_vm_physics.c), "not the floor". It was rebuilt on messaging: priority = heat gained this campaign
/ reps remaining, and the granularity is a **whole rep per message** (one turn = one message's worth of
work, not a word).
- XX: Bob: **"I don't want us to begin thinking of Hera as being different than any other VM... the only real
difference in Hera should be access to the kernel capsule repository."** Fixed by symmetry.
- XXII: the O(N)-per-tick idle pump hit a wall at 9 VMs on riscv64. Bob: **"we really will be giving birth
to potentially hundreds of VMs."** It was fixed by bounding the pump to K=4 VMs per beat with a cursor;
each VM drains every ceil(N/K) beats. Method: utime progress sampling, not "silence = hung"; three
premature kills were named as the mistake.
- XXV: Bob: **"the trick is to make system calls, schedulers and filesystems more or less go away and at the
same time introduce more automanagement and make that shit obsolete."** Workloads run as ephemeral child VMs.
- XXVI: a wrong conclusion (§XXV lockdown "broken") was corrected in place, not deleted: "always confirm which
specific VM a name resolves to".
- **XXVIII (2026-09-13): preemptive context switching between VMs -- timer-triggered, "driven by a new
Compudynamics-style physics signal purpose-built for who runs next ... explicitly not a classic
ready-queue/priority scheduler".** No per-VM native stack in v3; every VM runs as recursive C on the one
kernel stack. Reading on.
### Lines 3510-4210 (§XXVIII Stages 0-3, XXVIII.1-3, XXIX-XXXI Stage 4, XXXII start) -- THE v3 SWITCHING DESIGN
- v3's multitasking, as built and accepted (2026-09-13/15):
- Stage 0: complete trap frames. Stage 1: a per-VM native stack (2 MiB, guard pages). Stage 2: a cooperative
`sk_vm_context_switch(from,to)` saving only the callee-saved registers.
- Stage 3: **timer-driven, but the ISR only sets a flag.** The switch happens at a cooperative checkpoint on
the mainline -- the check "fires on literally every single word dispatch", so the latency is at most one
word. Bob confirmed "word-level granularity is fine grained enough" (Zynq: a word is a mnemonic).
- **The decision is a new physics signal** (capsule_vm_switch_signal.c): per-slot `readiness` accumulates on
timer ticks while a VM is not current; a switch is requested only when readiness >= threshold (50 ticks)
**and** `has_work` (set at MSG-SEND to that VM). It resets when the VM becomes current.
- The ISR is the single writer, the mainline the single reader (§21.1 amended once, explicitly, in writing).
- **So in v3 a VM runs a burst -- until another VM with work has waited ~50 ticks -- then switches. The per-word
cost is one flag check (take_pending), gated to the outermost interpret.** Idle VMs (no work) are never
switched to; a lone working VM never loses the CPU.
- XXVIII.1: "Stage 3 CLOSED overclaimed" -- a silent livelock and stack-ownership corruption, root-caused by
reading code; the fix was the outermost-frame gate, per Bob's decision.
- XXIX Bug 2: the MSG-TICK idle pump and the Stage 3 switcher were two owners of control, unreconciled
-> closed at §XXXVI ("one delivery path").
- **DISAGREES with 046ce0be:** v4's `v4_fabric_step` hands every awake node one word in turn, every step, with
per-step passes over every place and port. v3's design: a VM keeps the CPU until a readiness+has_work
signal crosses a threshold, and the per-word cost is O(1). v4 replaced a physics-signalled, threshold-gated
switch with a fixed round-robin.
### Lines 4210-4860 (§XXXII: USE halt, human vs unattended identity, the error-handling audit A-E)
- The options are named for Bob to pick ("not pre-decided"), with a recommendation; an option that amends a
ruling is "a gate decision for Bob, not an implementer's call". When live testing forced the bigger option,
it was "brought back for a decision rather than fixed unilaterally".
- The initiative was staged A-E, each stage its own commit with a 3-arch boot; triage came before fixing (105
sites classified, read in context, not sampled). Fix shapes follow the precedent of the same function.
- Policy: an interactive reply goes to the console; everything else goes to log_message.
### Lines 4860-5530 (§XXXIII multiuser DoE, §XXXIV THRU/collision/per-ISA pivot, §XXXV block-backed DoE)
- XXXIII.1: v3 has one physical console and one foreground session; **"Multitasking (many VMs alive and doing
real work concurrently) is real"**. The DoE stresses concurrency with VM-EXEC-driven workers.
- XXXIV.1: two false leads (host memory, pre-auth timing) were recorded so they are not re-chased; Bob: "you
should not have to edit anything". THRU swallowed the rest of its line -- fixed 2026-10-14 with POST cases.
- XXXIV.2: a peer session killed a live QEMU -> rule "never assume a live qemu is an orphan".
- XXXIV.3/4: the real cost was measured, not guessed, and the design was resized to a target (rule of 3s).
- XXXV.1: anything that must survive bare metal has to be written by the guest itself; host scraping is
QEMU-only.
- XXXVI begins: "one mover" (FABRIC-3.5 §XXXII); MSG-TICK pump gone (FABRIC-3.6 Stage E).
### Lines 5530-6130 (§XXXVI one delivery path, XXXVII-XLVII: elevation removed, LOG-FLUSH, Pi5, USB, both systems, PIE, process, CA, alpha)
- **XXXVI (2026-10-14), "one mover" (ruled in FABRIC-3.5 §XXXII):** a VM takes its own messages on its own
stack, on its own turn. sk_hermes_send_one marks the receiver has_work for the switch signal; the VM's
switch-entry loop drains, then yields; Hera's idle beat runs only her own messages and services the pending
switch. **The switch signal (readiness >= threshold AND has_work) is the one scheduler-free mover.**
- XXXVII: elevation removed -- privilege comes from the drive.
- XLIII (2026-10-14): v4 is the default build; "we are effectively trying to retire v3"; acceptance = the three
ISAs as built (v4) + `make -C v4 test-32`.
- XLV: "the Captain Bob method"; failures may not be merged to master; one process.
### Lines 6130-6671 (§XLVII-XLVIII alpha releases, idle halts, #92 the stick, #140, #168, #188, #189 A/1/2) -- FABRIC-3 DONE
- XLVIII.5 (#151): the idle loop halts (`arch_halt`, hlt/wfi) until the next interrupt -- 100% -> 1% of a core.
**v4 waits for an interrupt; it does not spin.**
- XLVIII.18, Bob: **"You are NOT to run acceptance tests in background EVER!"; "We track all logs and all
CSV's always as evidence"**; "tags are sacred".
- XLVIII.22 (#189 A): the hook at `call`; HEAT-OP ("If it's a huge performance hit, we'll revert it").
**Performance is measured at every step** (3.734 -> 3.731 s; A2 +2.4%).
- **XLVIII.23 (#189 Phase 1), the record of the regression, in our own words:** "Asked 'who runs next', I
offered choices of scheduling policy ... Captain Bob: 'Scheduler? Have we regressed?' The design has none
(JUSTIFICATION.md 4; fabric.h; this file's turn-attractor, 'without a scheduler'). The ruling was
withdrawn; 'Build it to proper spec.'" Then **"To spec (Task 5): the kernel boots the fabric (v4/mesh.h) ...
every node stepped together."** -- **DISAGREES:** "every node stepped together" is not the spec the record
cites. The spec it cites is the turn-attractor / switch signal: the next turn by physics (heat, readiness
plus has_work), no fixed policy, "no priority levels, no time slices"; one mover (XXXVI). Lock-step
round-robin is the fixed hardcoded policy §XIX rejected by name. The cost was never measured at this step
(unlike A1/A2/Phase 2): Phase 1's boot was 153 s.
- XLVIII.24 (Phase 2): "142 s against Phase 1's 153 s: no measurable cost" -- measured against Phase 1, which
was already on the lock-step fabric; never against f10d2bc8 (107 s).
## FABRIC-3.5.md (the Tripod/kernel reshuffle; CLOSED 2026-09-22 at v2.1.0)
### Lines 1-700 (§I-§XIII.1)
- "this is a reorganization, not an invention ... Any item that turns out to need a genuinely new algorithm is
by that fact out of scope and gets flagged, not quietly built." Provenance convention: "Traced" vs "Per §X"
vs "Open".
- Rulings: Hermes moves into the kernel (the arbiter, not a client); the Tripod = Hera/Artemis/Hestia; BIRTH is
general, with authority bounded by inheritance; one failure ladder; SOS; Hermes's sinking semaphore;
**"authority only ever flows down the birth graph"**.
- §I.8: the idle pump is already a kernel-resident clock for messaging.
- Superseded sections are kept with a banner ("Left in place, not rewritten").
### Lines 700-1400 (§XIII-§XVII: inventory, FORTH messaging legacy, scheduler firewall, authority rulings, shutdown, Hestia)
- **XIV.5 (raised):** "The fleet already has a scheduler: §XXVIII ... Message arrival is already a scheduling
input." This contradicts VM-PHYSICS-DYNAMIC-FLEET-DESIGN-20260705.md: "**Explicitly not wanted: a VM
scheduler. Nothing gets built that decides whose turn it is to execute.**" Proposed firewall: "switch.c
remains the sole owner of who runs next". "This codebase punishes duplicated authority with hangs."
- **XV.3 RULING (Bob, 2026-09-18): "Nobody owns the turn order. The turn order is compudynamic."** -> "Turn
order is an emergent output of the compudynamics, not a decision any component makes. Kernel-Hermes
publishes facts -- 'this VM has mail' -- and computes no ordering. Neither does anything else." Cites §XIX:
"a fixed round-robin across identities would just be a different hardcoded policy". The fixed threshold 50 is
flagged as "a real seam ... where a hardcoded policy could quietly start deciding turns".
- XV.2: "Nobody declares a VM dead, it died a compudynamic death." XV.5: "there is no owner to constrain ...
everything else -- death, turn order, conservation -- is physics rather than policy."
- XV.4: nothing survives but K. XVI: clean shutdown = flush + BYE; Hera = suicide (halt).
- XVII: Hestia is the existing drawing fabric given a VM face.
- **DISAGREES with 046ce0be:** `v4_fabric_step`'s "the next awake node in turn" IS a component that computes an
ordering (round-robin over places), every step. XV.3 says nothing computes an ordering.
### Lines 1400-2100 (§XVIII Hestia designed, §XIX name, §XX the bind records its target, §XXI SOS, §XXII strip method)
- XVIII.7: Hestia does not own turn order -- "Nothing owns it (§XV.3)".
- XX: "the bind records its target; nothing re-derives it" -- remove the derivation, don't widen it.
- XXI.2: SOS is message-driven, not polling: "a VM's own internal state (e.g. its message queue) determining
whether it does anything. No timer, no scan, no watch loop." Quoting VM-PHYSICS-DYNAMIC-FLEET-DESIGN-20260705.
- XXII, Bob: strip dead FORTH first, then code; "gaps reveal themselves as we code/test iterate". Separate
commits, a 3-arch boot each, and "reachability cannot be established by grep".
### Lines 2100-2800 (§XXIII sinking latch, §XXIV SCUTTLE, §XXV DoE/HOL, §XXVI close protocol, §XXVII empty floor, §XXVIII 2.1.0)
- XXIII.3: single-writer/many-reader one-way latch -- "the discipline this codebase has already sanctioned
twice" (heartbeat.c, the Stage 3 switch signal).
- **XXIII.4: "A VM cannot poll ... a VM only runs when dispatched ... On giving a VM its turn, the kernel
checks the latch."** In v3 a VM runs when it is given its turn by the switch, not by a per-step walk.
- XXV.3: the HOL deliverable is "a restated boundary, not a green build".
- XXVII.5: "The design got simpler each time it was checked against the tree rather than reasoned about in the
abstract. That is the single most useful habit to carry into the build."
- XXVIII.3: sweeps grep by exclusion; audit records (settings.local.json, ClaudeEXPORT) are never rewritten.
### Lines 2800-3500 (§XXIX-XXX versioning, §XXXI gap analysis, §XXXII one mover, §XXXIII sizing, §XXXIV transition)
- XXXI.1 admits its own coverage limit: "Not done: an end-to-end read ... it does not certify that every
claim in the set is accurate." **That is exactly what Bob has me doing now: the full read.**
- **XXXII RULING (item 22): retire the MSG-TICK pump; the switcher is the sole mover of control.
"Moving control is a mechanism. Deciding whose turn it is is a policy. The switcher is the mechanism.
The compudynamics remains the policy, and it is still owned by nobody."** Kernel-Hermes publishes
eligibility (has_work); it does not dispatch. XXXII.2: the pump's O(N) per beat was "a wall on every
architecture" at hundreds of VMs.
- **DISAGREES with 046ce0be:** `v4_fabric_step` is an O(N-places) walk on every step of every word -- the same
shape as the O(N) pump XXXII retired as a scaling wall, and worse, since it runs per word, not per second.
- XXXIII: the scope was counted before building (85 words -> ~9 protocol words + a heat-coupled allocator);
**"build and prove the hard part first" (K).**
- XXXIV.2: during a transition, one owner per message, never shared.
### Lines 3500-4150 (§XXXIV staging, §XXXV pre-mortem, §XXXVI-XXXIX the self-audit, decay, two accountings)
- XXXIV.3: a staged cutover (A: inert -> B: prove -> C: one type -> D -> E: strip), one commit each, "each
stage a revert of one commit". XXXIV.6: tripwires written down as stop conditions before starting.
- **XXXV.0: "Things here fail without saying anything"** -- the dominant failure mode. XXXV.6: "it was
declared done, and it wasn't". **Item 34: for each stage, name in advance the observation that would prove
it worked.**
- **XXXV.2: SK_SWITCH_MAX_SLOTS 16 -> "the §XXII pump story repeating one layer over: a bound invisible at
Tripod scale ... a wall later ... findable now, on paper".**
- XXXVII.4: "the mistake this reshuffle has now identified three times (the pump, SK_SWITCH_MAX_SLOTS, this)"
-- **no O(N) scans on the hot path; O(1) running counters; a scan only verifies the counters.**
- XXXVIII-XXXIX: one field carrying two meanings (age vs reservation) -> the leak; two accountings that share
vocabulary were conflated. "That shared vocabulary is what made them look like one system."
### Lines 4150-4761 (§XXXIX-XLVI: corrections, the build punch list, B1-B4) -- FABRIC-3.5 DONE
- XXXIX.4: "a check that passes while the thing it is supposed to guard is broken -- and I built one into the
plan" -- corrected in place.
- XL: the "leak" was a designed consumption economy (a comment at the reap site) -- "the framing was wrong";
the recommendation was withdrawn. The model was kept, and the sink is now ledgered.
- XLI: build phases 0-5; **"Standing rules for every task: one task per commit; three-architecture QEMU
acceptance before the next; logs committed; dict_hash identical across architectures."** **Phase 2 gate:
"if 2.7 fails, stop and re-plan".**
- XLII: work moves to FABRIC-3.6 with checkboxes restored; the design record stays authoritative; "If executing
a task proves a ruling wrong, FABRIC-3.6 records the finding and this document is amended -- never a silent
divergence."
- **XLIII RULING (B3): "Kernel-Hermes enqueues the payload onto the target's own pending queue and publishes
the fact. It dispatches nothing. The target drains its own queue, in its own context, at its own outermost
interpret checkpoint."** One message per checkpoint (XLVI 3.0(e)). "Starvation is possible and bounded": a
VM in a tight loop never drains; "preemption does not create a boundary".
- XLV.2 (B2): "SK_SWITCH_MAX_SLOTS (16) is not to be fixed and static; it becomes a dynamic component" --
RAM-derived at boot.
## FABRIC-3.6.md (execution log of the reshuffle; CLOSED 2026-09-22 at v2.1.0)
### Lines 1-650 (START HERE, standing rules, pre-flight 0.0, Phase 0, Phase 1, Phase 2.1-2.4)
- **The method, in executable form:** a 3-ISA baseline first (task 0.0, "a gate, not a formality ... Without a
known-good baseline captured first, the first red boot is ambiguous"); one task, one commit; a 3-arch boot
per task; logs committed; **"Never mark [x] on a task whose check did not actually run"**; the observation
that proves a task is named before running it (1.5: the storm signature checked directly, not "it booted").
- 1.6/1.7: a real dependency found -> asked Bob -> "best practices" -> merged, with the deviation documented.
The failed partial boot is kept as evidence.
- 2.3: a gap in the previous task's code was "Flagged to Captain Bob before proceeding; authorized to correct".
- **The regression I caused contradicts all of this: I measured the baseline (f10d2bc8 107 s) only after the
fact, and Phase 1's fabric step was never measured against it.**
### Lines 650-1813 (Phase 2.5-2.8, Phase 3 cutover, Phase 4 strip, Phase 5 close-out, findings) -- FABRIC-3.6 DONE
- 3.4 (finding): a drain at the outermost checkpoint is gated behind a system-wide pending counter -- "so the
common no-message-in-flight case costs one integer read per word dispatch ... flagged as a real hot-path
cost against this project's own +0.0603% measurement floor, not deferred." **The per-word hot path is held
to a measured cost floor: one integer read when nothing is happening.**
- 3.9 (finding): a passive receiver (an identity VM) is driven by nothing, so its queue never drains; fixed by
draining in the idle pump. (Later: §XXXVI's switch-entry loop.)
- Every task: limits stated ("the corruption proof exercises the predicate, not the wiring"); failed first
attempts kept as audit artifacts; out-of-scope items carried for visibility.
## FABRIC-3.7.md (217 lines) -- read in full
- CLOSED 2026-10-14: elevation removed, not built. "privilege comes from the drive"; a request-and-grant
channel only adds attack surface. KH-ELEVATE-SEND, type 8, the eligibility list removed.
- Method shown: §2's central claim was found WRONG before any code (written from a signature alone, without
reading the caller); the wrong §2/§3 are kept in a <details> block, struck, for traceability -- "this
series' own rule against silently rewriting a prior state". Lesson for me: read the actual source of the
caller before claiming what it does.
- Drive is the whole credential; no knowledge factor, ever (built, tested, reverted). Phase 8 v3 closed
in-console block cloning.
## FABRIC-4.md (169 lines) -- read in full
- Scratchpad of theory-stage ideas; graduates to the living doc only with a real scope.
- §1 the Stadium "wheel": Q48.16 phase accumulator off the heartbeat, fed by RWOT + inference engine.
`rate` starts FIXED (so DoE can measure it), graduates to adaptive only after a measured baseline.
Same graduation as L8's hardcoded constant -> VM Fleet Attractor. **Fixed baseline first, then adaptive,
measured.**
- §2 a pinned GPIO VM per board (Pi 5; Milk-V undecided).
- §3 "information state over information moment" (MESH step 7): the GONE made a state on the node's wire,
taken when the node can. H0/H1 with measures: loss, corruption under pressure, variance, cost.
**Bearing on the regression:** the design delivers as state, taken by the receiver on its own turn --
consistent with §XXXVI/§XLIII; nothing here calls for stepping every node together.
FABRIC record (0, 1, 2, 3, 3.5, 3.6, 3.7, 4) read in full. Next: task #9.
# Task #9 -- docs/v4.0.0
## JUSTIFICATION.md (257) -- read in full
- §4: the mesh "replaces time-sharing with space"; "Contention disappears as a scheduling problem. A blocking
port is flow control. There is no scheduler to write, which honours the existing design goal of avoiding one."
- §6: virtual heat (deterministic) chooses WHAT; physical power chooses WHEN (timing only, never results).
- §12 risk: "Capsule-level arithmetic is much slower than v3's C primitives on a hosted build. Accepted ... The
hosted build is a correctness oracle." **Some v4 slowness against v3 is an accepted, recorded risk** -- but
it is about the engine's arithmetic, not a fabric step; the regression measured is v4-against-v4
(f10d2bc8 vs 046ce0be, same engine), so §12 does not cover it.
- §16 acceptance: v4 equivalent to v3; every ISA reaches `ok`; `make -C v4 test` is a development check, NOT acceptance.
## ENGINE.md (477) -- read in full
- §3a (Bob 2026-10-05): "multiuser, multitasking, and a hybrid of preemptive and cooperative"; "Hera will be the
process manager via compudynamics per node." A node can be stopped between any two instruction words.
- **§3d RULED "A" (2026-10-05): "What Hera's process management decides: which nodes exist and are awake, not
whose turn it is. Every node that is not blocked runs; on one processor that is each in rotation, an
instruction word at a time, which is what 'all at once' is there and is not a policy." ... "an idle node does
not spin; it is blocked reading its ports and wakes when a neighbour writes".**
- §6 table: "Who decides which node runs next" struck, "Settled 2026-11-13 (#189; 'Build it to proper spec'):
no one decides -- there is no scheduler (JUSTIFICATION 4). Every awake node executes an instruction word at
each step of the fabric." -- 046ce0be cites THIS ruling.
- **DISAGREES with my earlier summary** (that 046ce0be's rotation contradicts the spec): ENGINE.md §3d is a
2026-10-05 ruling, by Bob, that rotation an instruction word at a time across unblocked nodes IS the v4
design and is not a policy. FABRIC-3 §XIX / 3.5 §XV.3 (threshold readiness, coolest VM) are v3's switcher,
which MACHINE.md §5.1 / ENGINE §2 amendment (2026-10-20) withdraw with v3. So the regression is NOT
"a scheduler was introduced against the spec". The question narrows to: the rotation is ruled; what does
each step COST, and does the step visit nodes that are blocked/idle (§3d: "an idle node does not spin")?
An O(N) walk per instruction word over every place, blocked or not, would contradict "does not spin" and
FABRIC-3.5's O(N) scaling-wall rulings. To be verified in the code (v4_fabric_step) before any write-up.
- §6 still open: "The node's safe moment for message delivery and switching" (Step 7).
## MACHINE.md (266) -- read in full
- Engine / ROM / trailer: the ROM is the only binary; assembles .f18 at boot; FORTH layers forth79 -> starforth
-> others, all before POST; POST; init.4th; ok>. No boot policy in C.
- §4 "A newborn node blocks on its ports and executes what arrives". §5.1 (2026-10-20): v3 leaves every build
after parity; Hera/Hermes/Artemis/Hestia are kernel functions. **So v3's switcher (FABRIC-3 §XIX/§XXVIII,
3.5 §XV.3) is v3's, withdrawn with v3 -- it is not v4's spec.** v4's is ENGINE §3d.
- §6: each step accepted by three ISAs + test-32.
## plans/2026-11-13-engine-step4-phase1-v4-in-the-kernels-boot.md (207) -- read in full
- Q4 "Full births now." The "who runs next: Hera by compudynamics now" ruling WITHDRAWN 2026-11-13 ("the question
was put wrongly, as a choice of scheduling policy"); "Build it to proper spec": every awake node steps
together, idle node waits at a port.
- Task 5b/5c/5d built 2026-11-13: mesh.c, Hera born empty at place 0, kernel on port 0, console port 1, births.
- **KEY LINE (the regression was seen and recorded at the time): "The amd64 boot: 160 s (about 90 s before --
POST and the lines now go as messages)".** An explanation was given ("lines now go as messages"); it was NOT
root-caused or measured against the cause. Task 3 Step 4 requires the opcode feed to be "Measured ... five
boots each -- recorded in the commit. Kept, or reverted on the numbers" -- check whether that measurement
exists. Bob's own standard: "i know this machine, it's never that slow" -> root-cause, don't explain away.
- Review focus 4: "The tick's cost: with the feed, the heartbeat still keeps its rate."
## plans/2026-10-20-engine-step4-node-in-the-vms-place.md (194) -- read in full
- Spec order: MACHINE.md governs; ENGINE §3/3a/3b/3d stand where not in conflict; V3-PARITY §1 the yardstick.
- Constraint: "A node may be stopped between any two instruction words (ENGINE 3a)."
- Review focus 5 **Speed**: "POST and the depth sweep must still finish under QEMU TCG in the time the acceptance
boots allow. Measured in A2 (boot time before and after recorded in the commit message)." A2 Step 5 (full
acceptance with boot times before/after) is UNCHECKED.
- Phase order ruled 2026-11-12: Part A, Phase 1, Phase 2, Phase 7.
## plans/...-phase2-word-accounts.md (137) -- read in full
- Word ID cell in the header; per-node bit per address; at call: a bit test and increment; charged per tick.
- "the boot 142 s (Phase 1: 153 s)" -- **measured against the already-regressed Phase 1**, not f10d2bc8 (~90-107 s).
- Task 5 full protocol box unchecked.
## plans/...-phase7-the-loops-and-parity.md (220) -- read in full
- Rulings: every-call loops (measured, kept/reverted on numbers); rewrite for v4; accepted on v3's WHOLE POST;
words in F18/StarForth not C; opcode physics (OPCODE_PHYSICS, default y, the revert switch).
- Tick by execution: every 256 word calls (v3's HEARTBEAT_CHECK_FREQUENCY), counted as v3 counts.
- **Timings recorded and explained away, never root-caused:** 2a 146 s vs 142 s (+3%); 2b "174 s and 181 s; 2a's
own commit booted again just after, 175 s (it was 146 s an hour before). The host slowed"; 3 inference 163 s,
L8 156 s; 3b "219 s on, 196 s off -- about +12% under TCG. Kept". Wide host variance (146 -> 175 for the
same commit) means single-boot numbers can't attribute small costs -- yet my f10d2bc8/046ce0be comparison
must be shown with repeats on one host, back to back, before it is called proof.
- Task 8: mkpost --all: 1020 cases, 849 pass, 171 fail; "v3's table, not v3's bugs". Unchecked: the 171 by kind,
then the whole table becomes v4's POST and its floor.
## MESH.md lines 1-400
- §2 ruling 7: "Hera decides which nodes exist and are awake, not whose turn it is. Every node that is not blocked
runs ... An idle node does not spin: it is blocked reading its ports." 2026-10-16: births follow v3 (any node).
- §3 acceptance 5: "An idle node executes nothing while it waits, which the anti-clock shows."
- **§4.3 The fabric, "A step. Every node that is awake and not blocked executes one instruction word. Then every
write that has a reader waiting on the other end of its wire is handed over ... there is no choice of whose
turn it is (ruling 7)."** -- the lock-step is THE DESIGN since 2026-10-06, built and accepted on the hosted
mesh long before 046ce0be. CONFIRMED: 046ce0be did not invent it; it brought the designed fabric into the
kernel's boot.
- So the regression question is ONLY cost: what a step costs per instruction word executed when one node (Hera)
is busy and the others blocked/asleep/empty (046ce0be's kernel fabric has 16 places). "Executes nothing" is
about the node; the step's own walk over places and wires is the fabric's overhead, and that is what the
profile (~40% self time in v4_fabric_step) points at. Verify in v4/src/fabric.c.
- §4.1: a port with nothing wired -> error 18 on a node that can take errors; bare node waits.
- §7a superseded by 7d (messages wait on wires). §7b refusals: NACK, GONE, 16 hops, Hera kills, console breaks a wait.
## MESH.md lines 400-850
- 7b.2-7b.7: NACK/GONE types; TTL hop limit 16; Hera's KILL sends GONE; console line breaks AWAIT (error 21).
- 7c: the wait, built, two reviews found unsound, BACKED OUT to dfabfa46, kept as record with what a second attempt
must settle first.
- **7c.7 -- the precedent for now:** "Captain Bob asked for the root cause before deciding whether to make the
stacks bigger ... Doubling moved the faults ... and removed none. **The size was never the cause.**" Two real
defects found (EMIT past the buffer; first word moved before room known). The analogue: raising the 570 s
timeout (which I proposed) is the "make the stacks bigger" move; the record's method is root cause first.
- depthsweep.py came from 7c.7 ("the test that was missing").
- 7d: messages on the wire, whole, in the fabric; a put/take is one step, all or none; wire 1024 cells each way;
stacks stay 32.
## MESH.md lines 850-1300
- 7d.3 wire ops 1-10; only sleep (8) and sleep-for-room (9) block; "A node blocked there executes nothing."
Sleep woken by a message COMING (event), not by one being there.
- 7d.4-7d.7 the nucleus keeps no messages; room for the answer kept; limits; acceptance incl. every stack depth.
- 7d.8 wires in system blocks: later, not built. 7d.9 ping: thought about, not ruled.
- §8 storage: v3's way in full; block words are kernel requests -1..-5 on port 0; window 4 x 256 cells.
- **8.5 / 8.7 method lesson:** a review's claim of "departure from v3" was reported to Bob before being checked
against v3, he ruled on it, then it was taken back. Step 6a's rulings were "given in answer to questions put
without first saying how v3 does it" and withdrawn. => Before putting any question, show how v3 / the record
already answers it. (Exactly Bob's "You're asking questions that the architecture answers.")
## MESH.md lines 1300-1750
- 8.6 withdrawn list (disk-as-port, nodes w/o storage, own drives, POST per birth): Bob "something is really off.
it sounds like a divergence from the os as designed" -> brought back to v3's way.
- §9 births follow v3 (2026-10-16): any node births; KILL Hera's alone; POST once, kernel's, on Hera.
- 9a step 7: second unit, centre.4th / hera.4th split, PAUSE/RESUME by number, kernel registry (manage.c),
requests -6..-18, the kernel tells GONE (no node hands one on -- the 7c.6 lesson).
- **9a.6 acceptance 2: "An idle node executes nothing: its anti-clock, read from C, does not move over thousands
of steps."** This proves the NODE spends nothing; it does not measure the FABRIC's per-step overhead of
visiting idle places. That is the gap the regression lives in -- the acceptance never had a cost criterion.
- §10 steps 1-6 done on the hosted fabric under test 2026-10-06/07 with 3-ISA logs per step. Step 5 note: "The
suite now takes about four minutes ... five POSTs" -- the mesh's cost was visible early in tests.
- Found on the way (step 4): POST was writing into the nucleus's code (HERE cell vs byte addresses); 12 cases left
out OPEN -> POST 538 not 550.
## MESH.md lines 1750-2162 -- MESH.md DONE
- Steps 6, 6b (POST the kernel's; "the judge can fail"; POST leaves nothing), 6c (refusals; review "did not keep its
rule" -> "fix them all; 16 hops"), 6d backed out, 6e (wires; 26,814 disturbances; final review by a fresh
reviewer "told to break it" -> "fix them all, test first"; "Not done: a second review, of the mends"), 7 (second
unit; ruling 7 amended in two increments each accepted on its own).
- Every step: 3-ISA boot logs named, POST 538/538, one dict_hash on all six. Reviews by fresh reviewers; each mend
with a test that failed first. Statements "that said too much" are reworded.
- **6e note on cost:** "a line is mostly the dictionary being searched, tens of thousands of steps in which no
message moves." -- at that time, in the TEST fabric. In the kernel since 046ce0be every one of those steps goes
through v4_fabric_step (all places, all wires), where f10d2bc8's v4_boot_run ran one node directly.
That is the concrete mechanism to verify in code.
- Steps 8 (hosted = five nodes) and 9 (bare metal) never marked done here; 046ce0be did the bare-metal part via
ENGINE step 4 Phase 1 Task 5.
## V3-PARITY.md lines 1-450
- Rulings: "v4 is exactly like v3 in functional requirements up to the first FORTH prompt"; "I would never stub,
simulate or develop outside of functional, as-intended code. Piecemeal is how errors and intent get hidden."
- **1a correction: "You haven't looked at the codebase. You're assuming missing pieces that are not missing and
ignoring the entire v3 architecture. Don't look at pieces until you see how they fit."** -- the same failure
he has called out in me now.
- 1b console: kernel hands a node a whole line; REPL and prompt are the kernel's.
- 1c the Stadium: compudynamics is the kernel's Stadium, not inside the engine; the engine reports what it executes.
- 1e messaging: Hermes delivers into no one; target drains at its outermost checkpoint; "the switcher reads the
same fact to choose which VM runs." **"Open. v3's safe moment is a per-word checkpoint in the inner loop ... A v4
node has no inner loop. What a node's safe moment is has to be defined; it is also where the switcher moves
control, so it decides how the fleet shares the processor."** -- still open in ENGINE.md §6 ("The node's safe
moment for message delivery and switching | Step 7"). 046ce0be did not settle it; it made every instruction
word a switch point across all places.
- 1f word card, ACL TTL adaptive (heat/4+256); hook at call; the six in-line residue.
- 1g every patron keeps its own accounts. 1h opcodes unwired (later wired by #189 ruling).
- 1i: "Yes, and Hera will be the process manager via compudynamics per node." Recorded, not designed.
- 1j: A -- code the node's, accounts the kernel's, joined by word ID.
## V3-PARITY.md lines 450-668 -- DONE
- 2.1 v3's seven per-word steps in the inner loop; per-tick loops in vm_runtime.c driven by the timer interrupt.
- 2.3 JUSTIFICATION: compudynamics "cost no instructions" -- on the fabric (hardware). In the C golden model every
per-call / per-retire hook is real CPU time; that cost is designed-in software cost, measured and kept by ruling
(HEAT-OP, opcode physics +12%). It is NOT the 046ce0be regression (that is between f10d2bc8 and 046ce0be, before
Phase 2/7 loops existed).
- 2.7 ruling: heat per opcode; "Before, a word was our smallest unit; now it is the opcode."; every loop runs.
- §3 stand-ins as found, none changed.
## NUCLEUS.md (362) -- read in full
- §6.1 POST is v3's own cases, ported (v3/src/test_runner/modules/*.c); only Required-set cases at first.
- §6.2 every case compares its result; expected values from the hosted v3 binary; FORTH-79 wins over v3's departures.
- **§6.3 "POST is the kernel's, as in v3." The kernel holds the cases (v4/system/post_cases.c, from mkpost.py) and
feeds them to the node; runner v4/system/post.c shared by hosted, kernel and tests; nothing of POST in the node;
POST leaves nothing (seal before, COLD after). A case the node does not come back from fails and ENDS POST, named.**
=> POST is a BOOT function of the runtime (as v3's POST at boot). This is what Bob means: v3's function-test
harness migrated into the runtime -- the runner and the cases, run at boot. NOT a unit test, NOT `make test`.
My putting POST into test_mesh_boot / make test was outside this design.
- 6.3 "How this came to be ruled twice": told Bob a false thing about v3 read from run_single_test without reading
run_test_suite. Same lesson again: read the whole of v3's code path before stating what v3 does.
- §6.5 rules: address-dependent, FORTH-79 wins, v4 address units, hand-written cases.
- §8 order: POST proven on today's words first ("This proves POST before it judges anything new").
- §9 acceptance: six boots of one commit (3 hosted, 3 bare). Later amended: hosted no longer required to match bare.
## POST.md (generated by mkpost.py --all; committed at 281972ab) -- read (committed version; working copy is my
uncommitted, rejected change)
- Committed: "POST runs 990 cases. 783 are v3's". Sections: 1 rewritten to the standard / v3's table (159);
2 address-dependent (20); 3 written by hand (28); 4 v3 cases left out (52, incl. OPEN D-1 cases, SP@ D-2 ruling);
5 KEY EXPECT QUERY QUIT untested; 6 v3 self-disagreements (14).
- Rule order (POST-PARITY): the standard first (FORTH-79, FORTH-83, ANS 1994), then v3's table, not v3's bugs.
- The committed state is that POST at boot is 990 cases (37469f6c). The boot-time cost of 990 cases on the mesh is
what pushed boots toward the 570 s limit -- the slowdown is the fabric, not the case count (f10d2bc8 ran 539 in
~107 s amd64).
## POST79.md -- read (generated; the Required-set table, 539 cases, 432 v3's; 59 rewritten to FORTH-79 ...)
## POST-PARITY.md (committed) -- read in full
- §1-4 inventory: 17 modules mkpost reads (888 cases), 9 it didn't (q48, starforth, physics_freeze, inference,
stress, integration, mama, acl (C), break_me (C)); parity ~1,050.
- §3 rulings: Mama in v4 words with v3's names "do not compose words in C99, use F18 and StarForth"; C modules
rewritten for v4 (FORTH lines in POST where they can be, host tests in C where they need internals).
- §5 rulings: "v3's table, not v3's bugs"; "The standard first" (79, 83, ANS, then v3); FORTH-83 double layout;
"Enlarge v4 to fit"; Q./ by zero = 0; D-2 for SP@; v3 for FENCE; SPAN fixed.
- §6 Result: 990 of 990 on Hera (mesh-boot); floor 990; node 32768 words, data stack 1024.
- **The boot's time: "at 990 cases the amd64 accept took 8 m 45 s (about 3 m 15 s at 539), and aarch64 ran out of
its 570 s in POST (STOPPED) ... Ruled (Captain Bob): 'Find the TCG cost first' -- profile POST under emulation
and bring 990 cases under 570 s on all three, before the push."** THIS is the standing order the regression
hunt answers. Note 3 m 15 s at 539 vs f10d2bc8's ~107 s at 539 (amd64): the regression was already in that
baseline; nobody compared against f10d2bc8.
- **My uncommitted addition to §6 ("Ruled: Whole POST in tests; boot runs less") is FALSE as a ruling** -- Bob
withdrew it ("No, no, no! ... unit tests are NOT part of the runtime"). It must not be committed. Left untouched
pending his word, with the rest of the rejected work.
## DECOMPOSITION.md (1116) -- read (ISA §1, conventions §2, decisions §3 D-1..D-19, foundation §4, fates §5 by
section -- skimmed the per-word tables -- §6 messaging, §7 registers)
- §1.4: "Execution itself drives the physics ... None of this costs an instruction" (hardware).
- D-2/D-16/D-17 stacks: counted, guarded; host node 32/32, then 1024 data / 32 return (2026-11-14 enlargement).
- D-14/D-16/D-18 faults and errors guarded; no silent corruption.
- §5.34 `SWITCH-MARK-WORK` RET: "Nodes run concurrently; there is no context switch to mark." On ONE processor,
"concurrently" = the fabric step (MESH 4.3). v4 has no switcher by design; the fabric step IS the sharing.
- §6: ports, GA144 blocking model; 6.1 packet proposal; router TTL/ACL later.
- §7 registers incl. HEAT-OP/ANTICLOCK (#189).
## STICK.md (384) -- read in full
- Plug and play; proxy Zuse minted at first boot per stick; real Zuse on a second stick; GPT; Artemis grows to
256 GiB; every acceptance run is a first boot (data stick); QEMU and bare metal ALWAYS hold parity.
- §7: the idle beat flushes the node's updated blocks ~1/s, "at the prompt or while headless, never mid-line".
- Anti-goals incl. "A path that works in QEMU and not on a PC, or the reverse."
## plans step6 (storage), 6b (POST the kernel's), 6c (refusals), 6d (the wait, backed out), 6e (wires) -- read
- Same content as MESH.md's step records. Global constraints of note: "v4 follows the OS as designed: before
building any mechanism, read how v3 does it, and report a departure instead of building it"; "No stubs, no
stand-ins. If something cannot be built as intended, stop and report"; 6e: "Compare the product with the commit
before on the same session" (build the commit before into scratch with git archive) -- **the method for a
before/after comparison that the 046ce0be change never had for speed.** Final review by a fresh reviewer "told to
break it".
## plans alpha4-documents, kernel-host-tests, capa-fmea-gate -- read in full
- kernel-host-tests: kernel/tests/, fakes not mocks; "Code is moved only to be testable, never changed in the
move"; "Not a substitute for acceptance."
- **capa-fmea-gate (nothing built; to rule):** CAPA = record per ESCAPED defect + a preventive control wired into a
stage; FMEA rows with RPN. "Silent failure is this project's dominant failure mode." CAPA-0003: "acceptance run in
the background; a rule nothing enforces." Detection = "name, before running, the observation that proves it worked".
**The 046ce0be slowdown is an escaped defect in exactly this sense**: no stage measures boot time against the
last good commit, so a 1.7-2.4x regression passed the protocol (it only failed later, at 990 cases, against 570 s).
For the write-up: name it as a CAPA candidate with a proposed preventive control -- not build it (to rule).
## plans machine-step1-rom (432) and mesh-rom (876) -- read headers, constraints, review focus, oracle, boot task
- "text.c stays as the oracle ... compare node memory word for word" -- every ROM routine tested against an oracle.
"It does not pre-write unrun F18 code. The test is what decides whether a routine is done."
- "No stubs, stand-ins or 'for now' code." Acceptance per task: three ISAs + test-32, logs committed.
- "If hera.4th's tests need more than that change, stop and report before going further."
## plan mesh-step7-second-unit (1212) -- read header, constraints, rulings-while-planning, review focus, task list
- "Rulings made while planning (for Captain Bob's review before execution)", each with reason and cost if wrong.
Task 1 writes the approved ones into the spec BEFORE code. Ruling 3 (GONE hook) later withdrawn (kernel tells).
## plans identity-gate, stick-1..5 -- read headers, goals, rulings, constraints, review focus (task bodies skimmed)
- Pattern: "What v3 does (read <date>, <files>)" written FIRST, then "What v4 does instead", then Decisions for
Captain Bob with recommendations, RULED before execution. Review focus pinned to named tests.
- Stick-5: Bob 2026-11-08: "work in small increments and memorize frequently".
- Constraint repeated everywhere: "QEMU and bare metal ALWAYS hold parity"; "Never apply a fix that is not in this
plan; report it."
docs/v4.0.0 and plans: DONE (DATASHEET-F18 next).
## DATASHEET-F18.md (353) -- read (summary, params, registers, control unit, faults, I/O, side effects, reset,
not-yet, not-in-machine; stacks/memory/opcodes sections skimmed -- same as DECOMPOSITION §1)
- §8 control unit: `v4_exec_step_word` -- "Stopped or blocked? ... nothing happens." Per-step cost for a blocked node
is the CALLER'S cost of asking it (the fabric's walk), not the node's.
- Note: the datasheet's §1/§11/§13 still mention per-call-target heat (removed by Part A1) and 16384 host words
(now 32768) -- stale statements. REPORT, don't fix.
## docs/reference -- HONEST SCOPE: headings of every file + targeted search (schedul/round-robin/turn/switch/
preempt/lockstep) -- NOT read line by line (DICTIONARY, STARFORTH_PRIMITIVES are v3 word tables; L8 table,
M7.1, ONTOLOGY, ROADMAP, kernel-args, word-acl, hosted-acceptance-test, standards). Say so if asked.
- ONTOLOGY "Density": "not computed by a separate scheduler -- it is read, not decided (FABRIC-0 §19.3)".
- ROADMAP M11 "Process Model: Forth tasks, Scheduling, IPC" -- a future milestone listing, pre-v4.
- DICTIONARY/PRIMITIVES: v3 `VM-STEP` "Gives one REPL turn ... to a named VM -- the Compudynamics context-switch
primitive."
## .claude/memory: MEMORY.md, rules.md, progress.md, discrepancies.md, code-review.md, .claude/README.md -- read in full
- rules.md is my own prior summary of Bob's Law; it already said "Name, BEFORE running, the observation that proves
a step worked", "Capture a three-ISA baseline before changing anything", "Read the whole of v3's code before
telling Bob what v3 does". I had these written down and did not apply them on 11-13/11-14 to the fabric change.
- Push point ruling: "Phase 7 boundary" -- commit locally, hold.
- alpha.5 closed to new work (2026-11-13).
- code-review.md (11-11) reviewed fabric.c but only for correctness (1u<<V4_PORTS+k, #20); no cost review of the
step. "Not yet reviewed": kernel_main.c, etc.
## boards/BRINGUP.md (331) -- scanned (headings, A/S tables, idle/time terms). Nothing run on hardware yet.
Not bearing on the regression. docs-notes.md: my own 11-11 notes, headings reviewed.
# CODE -- the fabric step (the decisive read)
## v4/src/fabric.c `v4_fabric_step` (423-490), fabric.h contract, mesh.c v4_mesh_step/v4_mesh_tell, sk_v4.c idle;
f10d2bc8 boot.c boot_exec -- read
- **f10d2bc8 (good):** `boot_exec` per instruction word = `v4_node_have` + `v4_exec_step_word` + a flag check. One
node, nothing else.
- **046ce0be (regressed):** every instruction word Hera executes goes through `v4_fabric_step` over
`f->capacity` = SK_V4_PLACES = 16 places, in TEN passes, each calling `awake()` per place:
(1) have-mask: for each awake node an 8-port loop over rx queues; (2) look_about for each non-blocked node: an
8-port loop; (3) exec one instruction word per awake node (blocked ones return at once, still a call each);
(4) have_fetched clear (8-port); (5)(6) two operate passes; (7) hand_over_write pass; (8) hand_over_read pass
(8-port device loop for a reading node -- Hera's console port device asked every step she reads); (9) gone-error
pass. Then `takes()` polls the console device queue. Then v4_mesh_tell's own checks (image_waiting, etc.).
=> per instruction word: ~160 place visits + several 8-port loops + device calls, vs. 1 call before. Cost
scales with CAPACITY (places that exist), not with nodes that run. With one node running, ~all of it is
overhead. Matches the profile (v4_fabric_step self ~40%) and the 1.5-2.4x stage times.
- **Against the record:** MESH §2 ruling 7 / ENGINE §3d "An idle node does not spin" -- the NODE does not, but the
fabric spins over it at every instruction word; FABRIC-3.5 §XXII/§XXXV.2: O(N) per-tick walks are scaling walls
("hundreds of VMs"); MESH 9a.6 tested only that an idle node's anti-clock stays still, never the step's cost;
046ce0be/Phase-2/Phase-7 timings were never compared to f10d2bc8, and drift was put down to "the host slowed".
- **What is NOT in question (ruled):** rotation one instruction word at a time among unblocked nodes, no scheduler,
no choice of whose turn (ENGINE §3d "A", MESH ruling 7, fabric.h). The fix must keep that semantics and remove
the per-step walk of places that cannot run -- i.e. the step's work proportional to what runs/moves, not to
capacity. HOW is a design question for Bob, with v3's answers shown first (FABRIC-3 §XXVIII flag-not-walk,
FABRIC-0 GAP-A1 virtual tick, 3.5 §XLIII the target takes its own on its turn). No code before his ruling.
- Still open in ENGINE §6: "The node's safe moment for message delivery and switching" -- 046ce0be's step makes
every instruction word that moment.
## The timing evidence -- provenance (auditable, committed logs)
- Stage time = start of that stage's QEMU log to start of the next stage's (each stage is `clean` build + boot +
session). f10d2bc8 protocol logs/20261113-142432: amd64 14:25:04 -> 14:26:51 = 107 s; aarch64 -> 14:30:20 =
209 s; riscv64 -> 14:32:05 = 105 s. 046ce0be protocol logs/20261113-170011: amd64 17:00:39 -> 17:03:43 = 184 s;
aarch64 -> 17:12:02 = 499 s; riscv64 -> 17:14:45 = 163 s. Same POST (539), both PASS.
- Limits: one run each; includes the clean build; host variance is real (Phase 7 2b: same commit 146 s then 175 s).
So these show the gap, but a back-to-back repeat on one host is the proof to propose (not run without his word).
- The gprof profile (v4_fabric_step ~40% self) and the 1M-loop figures (v3 hosted ~172 ms, Hera in the mesh
1362 ms) were measured in the previous session and are NOT committed evidence (v4/gmon.out untracked).
- History state: origin/StarForth-v4.0.0 = ee28530b (046ce0be and Phase 2 e8e7ec8b are PUSHED, in PR 164); 28 local
commits (Phase 7 + my five). "Start over from f10d2bc8" therefore touches pushed history -> his explicit word.
- Issues (Gitea) not re-read in this pass; issue numbers known from code-review.md (#168-#183, #20, #189-#196).
TASK #9 reading DONE (with the honest scopes noted above).
# Bob 2026-11-17: "Not JUST fabric too. Follow all the readmes and accomplishments" -- READMEs + CHANGELOG + log READMEs
(excluded: build/cache third-party Isabelle READMEs, build/sbom copies; docs/patent + docs/working/legal = legal hold)
## README.md (175) -- read in full
- v3 "What's live": kernel-Hermes -- "every VM takes its own messages on its own turn, under a cooperative switcher
that every VM takes part in." (v3's model). Word-ACL measured overhead +0.0603% -- the project measures overhead
and states it as an accomplishment.
- Stale vs tree (report, don't fix): POST 538 / word_count 317 / dict_hash 0xfec8...; "Tasks 1-3 of 5" for the
stick (done through 5a). The release is alpha.4.
## v4/README.md (227) -- read in full
- Largely stale: "This is still the lone node", "There is no POST and no K measurement yet", per-call-target heat,
nucleus-64 lines, "products ... become the five nodes at MESH steps 8 and 9". Not updated for 046ce0be (mesh
boot) or Phase 2/7. Report.
- "Nodes that talk ... The products below are still one node each" -- the cost of the multi-node fabric was never
the products' until 046ce0be put the boot into it.
## CHANGELOG.md (269) -- read in full (the accomplishments)
- The record of accomplishment is root cause, measured: 2026-07-24 amd64 dict_hash "Root-caused rather than dismissed";
2026-07-07 riscv64 divergence "mis-attributed to an architecture quirk" -> root cause (wall clock vs tick);
2026-08-18 Artemis 30/30 FAIL -> root cause (quota grant order); aarch64 BYE -> live gdb root cause;
2026-06-16 ACL overhead "+0.0054%-+0.0088%, CV = 0.000%" -- overhead MEASURED and stated, 3x3 Latin square.
- So the standard for a cost is a DoE measurement with CV, not a single boot, and a slowdown is root-caused, never
put down to "the host" or "messages". 046ce0be..Phase 7 broke that standard.
- alpha.1-4 (11-07..11-10): v4 default; acceptance gate; alpha.4 the stick. No entry for #189 yet.
## boards/* READMEs, capsules/* READMEs, configs, demo, lfs, logs, mk READMEs -- read in full
- **demo/README.md (tested 2026-11-06): "The saved machine: POST 538/538 ... `[zuse@Hera] ok>` after an 87 s boot"**
-- a third, independent pre-regression amd64 baseline (v4 lone node), consistent with f10d2bc8's 107 s stage
(which includes the clean build) and Phase 1's "about 90 s before". Cite in the write-up.
- The demo depends on boot time (snapshot made by one boot; sessions resume). A slower boot costs the demo too.
- capsules/README.md stale: names hermes/init.4th (gone), "1024 bytes ... wc -c" (the rule is 64x16 lint). Report.
## disk/, docs/README, docs/book, docs/pptx, experiments/, std79-doe, std79-exerciser READMEs -- read in full
- **std79-doe precedent (FABRIC-3 §XVI): aarch64 identity attach "stalled 90+ minutes" -> root cause an O(ncells)
scan in stadium.c -> fixed -> "~34s".** The same class as now: a per-step walk over every cell, aarch64 worst.
The record's answer was to remove the scan, not to wait longer. Discipline: "any Stadium defect repair reruns the
whole DoE from the top", same seed, one boot per arch; wall-clock recorded per run (amd64 ~151-165 s etc.).
- disk/README: fixtures are committed; regression fixtures kept in their state.
- docs/book "Rule for data": measured numbers are generated from the CSV at build, never typed by hand, with
\datasource. => the regression write-up's table must name its source logs (it does), and a committed measurement
should be a CSV, not prose.
- docs/README "What to believe": CLAUDE.md > FABRIC > v4.0.0 ... code wins over all.
## docs/formal/* and docs/working/* top READMEs -- read in full (756 lines)
- Experiment lifecycle (02-experiments): Design (hypothesis, factors, response) -> Protocol -> Execute -> Analyze
(ANOVA, Levene) -> Document. Claim discipline: ANTI_CLAIMS, NULL_HYPOTHESIS, NEGATIVE_RESULTS, REPRODUCIBILITY.
=> the regression measurement should be put as a hypothesis with a null, factors (commit), response (boot time),
replicates -- not a single comparison.
- scratch/ci-cd/FMEA_BLOCKING_GATES.adoc exists (older FMEA gate idea, pre-CAPA plan).
## kernel/*, proof, scripts, site/*, tools, tools/kconfig, v3/* READMEs -- read in full (851 lines)
- **v3/src/test_runner/README.md: "Test harness for the hosted VM's test suite, run via ./starforth --run-tests.
Organized in POST (Power-On Self Test) order: unit tests -> dictionary/word-category tests -> integration/stress/
adversarial tests." test_runner.c orchestrates modules in POST order; test_common.c; test_contracts.c (pre/post
contracts).** THIS is "v3's function-test harness" Bob means: its own harness (runner + common + contracts +
modules), in POST order, migrated into v4's runtime -- not my generated tables in make test.
- Many of these READMEs are stale (paths `src/starkernel/`, `Makefile.starkernel`, "24 theory files", hermes smoke
tools, kmalloc "16 MB heap", GIC/PLIC "stub"). Report, don't fix.
- kernel/src/README: "the only valid acceptance test is the three-arch QEMU boot ... never make test."
## docs/working/archive/* READMEs -- read in full (legacy, operations, quality, research, session-logs, historical
amd64-isr-fix, riscv64-stack-fix, birthing (+acceptance-logs), dead hal-target-contract, superseded tripod)
- **The fix write-up template of record (amd64 ISR fix, riscv64 stack fix):** Problem (with the evidence) ->
Investigation (the DEAD ENDS ruled out, each said) -> Root Cause (proved: disassembly / bisected checkpoints) ->
Fix -> Result (a Before/After table) -> Acceptance (commands, and the committed log paths). My write-up must
follow this form, and must list my dead ends honestly: case count, the lookup, TCG, the enlargement, raising the
timeout, "the scheduler", running in the background, POST into make test.
- riscv64 fix: "A crash whose location ... shift under unrelated code changes is the standard signature of stack
corruption" -- read the symptom's signature; "kernel_main.c documented the gap directly, once read closely".
- quality/README: "After Major Changes: Run regression detection framework; Compare DoE results with baseline".
hal contract success criteria: "No measurable performance regression".
- superseded TRIPOD: "no heat-based VM routing" -- consistent with v4's no-scheduler ruling.
## logs/*/README.* (all labelled evidence 11-12..11-17) -- read in full
- **THE ESTABLISHED COST METHOD (accomplished, ruled):** logs/20261113-005047/heat-op/timing.txt -- "the hosted
amd64 boot (POST 538), five runs each, alternating: OLD = 3c97534c, NEW = with HEAT-OP. Median 3.734 s / 3.731 s;
instructions 59145258 / 59302047 (+0.27%) ... No measurable cost: by Captain Bob's rule it stands."
logs/20261113-045122/a2/timing.txt -- same: five alternating, medians 2.917/2.987 s (+2.4%), instructions +0.4%.
Phase 1 bench_ops: "about 0.5 us a charge ... Not the 'huge performance hit': it stands".
=> Every cost was measured this way UNTIL 046ce0be. 046ce0be has no timing.txt, no alternating runs, no
instruction count. Phase 2 and Phase 7 used single bare-metal boots; 2b's slowness was "explained" by booting
b880a6ea once more (175 s) and concluding "the host had slowed, not the code" -- one boot each, no alternation.
- The proof (write-up §5) must use THIS method: OLD = f10d2bc8, NEW = 046ce0be, five runs each, alternating,
medians, plus instruction/step counts. The hosted product did not change at 046ce0be (it keeps v4_boot_run), so
the comparison is the kernel boot under QEMU (alternating, one at a time, foreground, timeout 570), or a host
harness running the same POST through v4_boot_run vs through the fabric (test_mesh_boot did not exist at f10d2bc8).
- aarch64 at 046ce0be-era: 460-473 s with 539 cases (logs/20261113-170343, -191606) vs f10d2bc8 209 s.
- 11-17 diagnostic: ~0.57 s/case aarch64 vs ~0.17 s amd64 under TCG.
- Stopped boots labelled STOPPED, development boots labelled "not acceptance evidence" -- every log labelled.
## READMEs done (campaign READMEs doe_2x7/shape/window/l8, PEER_REVIEW, std79 analysis/report: headings + method
sections only -- the v3 hosted DoE method: replicates, --shuffle randomized order, "Running with a Specific Git
Commit", mean/median/SD/CV). docs/patent/README_V3.md NOT read (legal hold).
# 2026-11-17 CI DIRECTIVE (Bob, after a worker restart) -- inspected, NOT changed; conflicts to rule
- POST = only: all .f18 assemble, all .4th compile; report; no runtime tests. CURRENT: v4/system/post.c runs 539
(990 committed) runtime cases at boot; post-count stage + POST_FLOOR enforce the count. CONFLICTS with Bob earlier
today ("POST is v3's function-test harness ... Functional tests exactly the analog of v3"), NUCLEUS §6, MACHINE §3.4,
POST-PARITY rulings, #173. Assembly/compile failure already fails the boot (ROM-FAILED; a capsule line not " ok"
-> PARITY:FAIL, POST: FAILED) -- so the two responsibilities exist in the loader today.
- Unit tests = kernel compile + ASan + UBSan only. CURRENT: build.yml runs `make -C v4 test` (v4 engine/host tests,
not the kernel); nightly v4-checks = v4 sanitize + hosted-check; kernel/tests (host tests of kernel C) has NO
sanitizers and is in NO pipeline; test-32 (v4 tests at 32 bits) is an acceptance stage by Bob's 2026-10-14 ruling.
- 3 ISAs sequential foreground: acceptance.yml/nightly.yml run accept amd64,aarch64,riscv64,stick-high as sequential
steps in one job, runner capacity 1 -- COMPLIANT. Failure fails the job -- compliant.
- EMERGENCY build param: exists (EMERGENCY_CONSOLE_ENABLED, Kconfig.heartbeat, default n); no --sos anywhere;
acceptance never uses the emergency modes -- compliant. MISSING: the failure-triggered EMERGENCY diagnostic build
(separate, diagnostic logging, artifacts kept, original failure authoritative). Unknown: what stack/backtrace
diagnostics the emergency/debug build has on v4 -- to inspect before designing.
- Failure categories: partly by step name; not the five categories asked.
- Performance out of scope => the 046ce0be fabric cost is not to be optimized now; the write-up records it only.