diff --git a/.claude/memory/reading-2026-11-17.md b/.claude/memory/reading-2026-11-17.md new file mode 100644 index 00000000..a668c6d6 --- /dev/null +++ b/.claude/memory/reading-2026-11-17.md @@ -0,0 +1,954 @@ +# 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
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 , )" 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<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. diff --git a/.claude/memory/rules.md b/.claude/memory/rules.md index 5a5ed100..2018bf27 100644 --- a/.claude/memory/rules.md +++ b/.claude/memory/rules.md @@ -145,3 +145,11 @@ him -> the tag, on his word. head. During #189 Phase 7, commit locally and hold; push once, behind a passing protocol, at the Phase 7 boundary -- "End of phase 7" (2026-11-13): when Phase 7 is accepted, v3's whole POST passing on v4, not at the end of the loops. Before then, only on his word. + +## Ruled 2026-11-17 (Captain Bob) -- standing +- **Every discrepancy, ONE AT A TIME.** Wherever I find a discrepancy (doc vs code, v3 vs v4, rule vs practice, + directive vs record), present it to Captain Bob by itself, and let him decide, before the next. Never batch them, + never decide one myself. +- **POST is as v3's works.** Not reproducing v3's tests AS WRITTEN, or a parity mismatch, is THE failure. +- Order given: inspect the debug (EMERGENCY) build first, then write the design for the failure-triggered + diagnostic build -- for his ruling, before building.