LithosAnanke/.claude/memory/docs-notes.md

Document notes, in the order read

Dates are the documents' own. "Bob" = Captain Bob (R. A. James). Rulings are quoted where short.

Top level and .claude/

• .claude/CLAUDE.md — authoritative. Summarised in rules.md. Status it states: M7.1; v4 default build since 2026-10-14; v3 "being retired", not part of acceptance; kernel 4.0.0-alpha.4, engine 3.2.0; v4 parity word_count=318 hash 0x8c92508f748f99cf (2026-11-10, on the working branch only, PR 164).
• .claude/README.md — STALE: still calls TRIPOD/HERMES/ARTEMIS "binding constraints"; CLAUDE.md says they are frozen history (superseded 2026-08-15, archived as-is 2026-09-22).
• README.md — v4.0.0-alpha.4. Three products: Hosted StarForth F18, FPGA StarForth F18, StarshipOS. Says v4 POST 538 tests, word_count=317 dict_hash=0xfec8c47cfc6f437f; v3 1052 tests, 526 words. (CLAUDE.md on the branch says 318 / 0x8c92... — see discrepancies.)
• CONTRIBUTING.md — STALE, StarForth-era: make test, "780+ tests", feature branches, hal_* interfaces, docs/02-experiments/. Contradicts CLAUDE.md on every one of these.
• docs/README.md — the map and the authority order. docs/CLAUDE.md — docs triage rules (two tiers: formal/ press-ready LaTeX, working/ living; INDEX.md hand-maintained; never delete without Bob).
• docs/DEAD-AND-REVISED.md — register of dead ideas (L4Re, hal_* contract, ACL-RECHECK-RW, the Hermes VM, elevation words, PIN/passphrase, cloned-drive defence, 2^6 factorial DoE) and revised claims (ACL overhead is +0.0603%; block rule is ≥2048 and 64×16; v4 boots by default).

docs/v4.0.0/ — StarForth v4 (the F18-derived engine)

Authority inside the set, newest wins: MACHINE.md (2026-10-15, amended 10-20) > ENGINE.md (10-05, §2 withdrawn 10-20) > NUCLEUS.md (10-05; §6 POST stands) > DECOMPOSITION.md (the word-by-word spec). DATASHEET-F18.md is the machine as built. STICK.md is the PC stick. V3-PARITY.md is the gap record.

JUSTIFICATION.md

• Why: v3 has 300+ C primitives, 64-bit cells, 5 MB per VM, software Hermes; fine for an OS, wrong for silicon.
• v4 = 32-opcode core ISA from Moore's F18 (5-bit opcodes, six slots in a 32-bit instruction word); everything else is capsule code; a mesh of small nodes with blocking ports; Hermes becomes the network; compudynamics as a side effect of instruction retirement; RWT governor controls timing only.
• Cell width is a build parameter (32/64). Heat and K arithmetic stay 64-bit.
• Physics split: virtual heat (deterministic) decides WHAT runs; physical power (XADC) decides WHEN.
• Path: hosted golden model → hosted mesh → Verilator co-sim → FPGA (2×2 on PZ7020) → ASIC (Tiny Tapeout, IHP SG13G2).
• §14 definition of done; §15 three products (ruled 2026-10-03); §16 acceptance: v4 equivalent to v3 at any point; every ISA hosted and bare metal reaches ok. make -C v4 test is a development check only.

ENGINE.md

• Rule (2026-10-05): v4 is exactly like v3 functionally up to the first prompt. "Nothing is stubbed, simulated or stood in for."
• §2 AMENDED 2026-10-20: "MACHINE.md stands; v3 goes after parity; Hera, Hermes, Artemis are now all kernel." Hera = process management (v4/src/manage.c), Hermes = wires (v4/src/wire.c, message.c), Artemis = block serving (v4/system/blocks.c), Hestia = the kernel's console. No capsule for any of them. The first node keeps the name Hera. No identity drive = headless; console only once a drive is in. 2026-10-26: "Gate first" (identity gate before the rest of step 4).
• Interface a node must answer (§3): interpret a line; char out; ask the kernel (blocking port write, KERNEL-WORD); stacks/dictionary from the kernel side; the hook at call; error; tick; dict hash.
• §3b ruling "A": word code lives on the node, its accounts live in a kernel record, joined by word ID.
• §3a: multiuser, multitasking, hybrid preemptive/cooperative. A node can stop between any two instruction words (v4_exec_step_word). Hera decides which nodes exist and are awake, not whose turn it is.
• §3d: nodes born empty, first thing received is a capsule of F18 code. First geometry "2x2 + 1 central", centre = Hera; ports are a parameter (6 discussed, default 8 in code); geometry is data; units join centre-to-centre.
• Steps: 1 done, 2 carrier done, 3 hook at call, 4 node as kernel interpreter, 6 Hera, 7 fleet, 8 identity. Open: who runs next (step 7), PAD 42 OVER ! byte address to ! (issue #12).

NUCLEUS.md

• Nucleus = what must stay in assembler (opcodes/registers, what reads a capsule, code generator words).
• §5.2 block rule: ≥2048, no ceiling. §5.3 loading: find, hash, signature (invalid stops, missing warns), feed lines; a failed line stops the boot (no v3-style retry).
• §6 POST (stands): cases in v4/system/post_cases.c, generated by v4/tools/mkpost.py from v3's test modules with expected values from hosted v3; runner v4/system/post.c; every case compares stack and output; seal before, COLD after, nothing left. Exceptions in v4/tools/post79_rules.py → POST79.md.
• §7 parity lines: PARITY:V4_NUCLEUS, V4_CAPSULE, V4_POST tests= pass= fail=, V4_SYSTEM word_count= dict_hash=, PARITY:OK, POST: PASSED. v4 dict hash = FNV-1a over node memory code..HERE plus LATEST.
• Lesson recorded in §6.3: a ruling was once made on a false reading of v3 (run_single_test vs run_test_suite). Read the whole of the thing before telling Bob what v3 does.

MACHINE.md (governs)

• Capsule = semi-truck: engine (32 opcodes), ROM = "the VM" (prebuilt F18 binary that assembles .f18), trailer = source blobs (.f18 assembler, .4th FORTH).
• ROM: host ROM 2372 words (entries 0–18), mesh ROM 277 words (entries 0–5: UM*, UM/MOD, D+, DNEGATE, Q.*, Q./). Entry table at ROM base; read-only (store = address fault). Built by v4/tools/mkrom.c; mkmap.c gives constants.
• Boot: engine reset → ROM assembles system .f18 (capsules/v4/sys) → forth79.4th, starforth.4th, other system capsules → POST → init.4th → ok>.
• §5.1 v3 leaves every build once v4 is at parity (ruled 10-15, confirmed 10-20). Issue #156 tracks it.
• §6 order: 1 ROM (done), 2 trailer (done), 3 init.4th after POST, 4 Hera streams the ROM, 5 FORTH-79 out of .f18 into forth79.4th, 6 v3 out. Steps 3–6 not built (issue #83).
• §7 rulings: VM is a machine; .f18 plain text; v3 deleted only after parity; all system capsules load before POST; forth79.4th names all 130 Required words; init.4th is the system's init.

DATASHEET-F18.md (machine as built, 2026-10-15)

• Registers P A B T S R (+I hidden). Stacks counted and guarded (D-16): mesh 10/9 deep, host 32/32.
• Word-addressed (D-1). RAM V4_NODE_WORDS (1024 mesh, 16384 host). V4_PORTS default 8.
• Instruction word 32 bits at every cell width (D-9). Branch reach by slot: 27/22/17/12 bits; slots 4,5 outside spec.
• 32 opcodes 00–1F: ; ex jump call unext next if -if @p @+ @b @ !p !+ !b ! +* 2* 2/ inv + and xor drop dup pop over a nop push b! a!.
• Faults: address 0, data over/under 1/2, return over/under 3/4, raised 5 (store to NODE-ERROR).
• MMIO: CONSOLE-TX/RX/STATUS, DSTACK/RSTACK-DEPTH, ports (k, any, which, writers, readers, Wire, A, B, Do, How, Have).
• §13 "not yet as intended": per-call-target heat is a 4096-entry stand-in; device addresses not fixed (D-4, issue #9); stale comment in stack.h; branches in slots 4/5 not trapped.

STICK.md (the x86_64 StarshipOS stick; 2026-10-26, amended 10-29)

• Goal: one USB stick is the whole OS, plug and play: boot → [zuse@Hera] ok>, nothing to set up. v4 only.
• GPT, three partitions: ESP (FAT32, BOOTX64.EFI, starforth.cfg), StarshipOS identity (500 MiB), StarshipOS Artemis (grows to fill the stick at first boot, cap 256 GiB, metadata-only writes). Image as built 2 GiB; minimum stick 8 GB.
• First boot mints the stick's proxy Zuse (full Zuse until a real one is minted). MINT-ZUSE puts the real Zuse on a second stick; after that the proxy only shows a fixed screen offering R = mint a replacement (the old stick "dies for good"). Genesis marker version 2 holds both keys.
• system=v3 is refused on a stick. Standing rule: "QEMU and bare metal ALWAYS hold parity."
• Every clean qemu boot attaches a fresh GPT data stick over xHCI, so every acceptance run is a first boot.
• §11 increments: 1–5a done (5a done 2026-11-10, #92); 6 pull/replug + flush (#93), 7 splash + progress bar (#94), 8 acceptance moves to the stick boot (#95) — open.
• Known and accepted: the system stick stays a master key (fallback can mint a new Zuse).

V3-PARITY.md (gap record, started 2026-10-05)

• Two rulings: v4 = v3 up to the first prompt; "I would never stub, simulate or develop outside of functional, as-intended code. Piecemeal is how errors and intent get hidden."
• §1a correction by Bob: "You haven't looked at the codebase ... Don't look at pieces until you see how they fit." The v3 boot order in kernel_main_deep: fleet tables → sk_vm_bootstrap_parity() → devices → capsule_birth_mama() runs init.4th → timer → self-tests, Hestia/Artemis born, Zuse, banner, REPL.
• Stadium frame (§1c, §1g): everything is a patron (word, VM, block, message), 64-byte cell of nine wires; each patron kind has its own accounting layer (stadium_words.c, stadium_blocks.c, capsule_vm_physics.c, kernel_hermes.c). K = conservation of heat (shares of 1.0).
• ACL word card stays per word, checked at run time at the call hook; TTL adaptive = heat/4 + 256, capped. In-line words >R R> R@ I J LEAVE cannot be called: checked at compile time.
• Opcode heat: counted, left unwired for now (§1h). Word accounts: ruling "A" (kernel record per word ID).
• §3 lists self-declared stand-ins in v4 (per-call heat, ACL-HEAT@ = 0, console, memory map, CA key placeholders).

DECOMPOSITION.md (the specification: every v3 C primitive's fate)

• Fates: OP (opcode), IN (in-line macro), CAP (core capsule colon def), CC (compiler capsule, host node only), DEV (device service), HERA (Hera service), MM (memory-mapped register), RET (retired).
• Decisions D-1..D-19 (ruled 2026-10-01 to 10-05). The ones that bite:
  • D-1 word addressing; byte address = 4×word + 0..3; CELLS is a no-op; C@/C! are CAP.
  • D-3 plain F18 +* (carry out of T not kept); UM* written for it, exact, proven on the golden model.
  • D-4 memory map DEFERRED; D-6 heat structures DEFERRED (answered per-opcode in V3-PARITY §2.7).
  • D-7 PICK/ROLL count from one (FORTH-79); v3 counts from zero.
  • D-8 Q48.16 signed; D-10 a Q value is two cells at every width; D-11 Q./ saturates and flags, by zero sets NODE-ERROR.
  • D-9 instruction word 32 bits at every cell width.
  • D-14 address fault; D-15 division by zero guarded; D-16 stacks counted and guarded (revises D-2); D-17 host node 32/32 deep, mesh node 10/9; D-18 "guard all errors": error codes 1–16 (+17 Storage refused, 18 No one on that port, 19 Message refused, 20 Node gone, 21 Interrupted added by MESH).
  • D-19 block registers REPLACED 2026-10-07 by kernel requests on port 0.
• Standing ruling: where v3 departs from FORTH-79, FORTH-79 wins and the departure is reported (LEAVE, MOVE, .R, ', WORD, NUMBER, LATEST, COMPILE, ABORT", FORGET, vocabularies). Several v3 bugs are "reported, not fixed" here (v3 LATEST pushes HERE; v3 COMPILE broken; v3 ABORT" segfaults in a compiled word; v3 FORGET DUP succeeds).
• Entry layout: xt-3 flags (1 immediate, 2 hidden, 4 data; ACL: bit5 denied, bit6 pinned, bits 8–15 mode, 16–31 TTL), xt-2 name address, xt-1 link, xt code. Names ≤31 chars.
• §5.20: v4's word ACL is weaker than v3's: checked when interpreted and when compiled, not at each run of a compiled call. Closing it needs the check at call (issue #6).
• §6 ports: originally four (UP/DOWN/LEFT/RIGHT), withdrawn; V4_PORTS is a parameter, wiring is a table.
• File paths in this document are the OLD ones (v4/capsule/*.v4); since MACHINE.md they are .f18 blobs under capsules/v4/sys/.

MESH.md ("Talking nodes", 2026-10-06 onward; long, with its own history)

• Rulings: ports are the transport, the Hermes message is what travels; geometry is data; first geometry 2×2 + centre, units join centre to centre; scales at run time; Hera decides which nodes exist/are awake; a node is born empty; built hosted first, then bare metal.
• §4 engine ports: base+k port k; then any, which, writers, readers, Wire, A, B, Do, How, Have.
• §5 a capsule of F18 code is just the words a neighbour writes to the port (@p a! @p push / @p !+ unext).
• §6 message: 7 words (to, from, type+channel, heat+TTL, ACL tag, sequence, length) + text, 4 chars/word. Types: 1 text, 2 output, 3 done, 4 NACK, 5 GONE. At most 16 hops.
• History worth remembering:
  • §7a (looking before writing, lower-number rule, 400-cell ring) — a RECORD since step 6e.
  • §7c "the wait" (step 6d) — built 2026-10-08, two reviews found it unsound, BACKED OUT the same day. Root causes (§7c.7): EMIT ran past the output buffer; a message's first word moved before room for the rest was known. Stack size was never the cause.
  • §7d "messages on the wire" (step 6e, built/reviewed/mended 2026-10-13): the fabric moves WHOLE messages; each wire has a queue each way of V4_WIRE_CELLS = 1024; put/take are all-or-nothing; ten operations (look, take, move, drop, put, first, next, sleep, sleep-for-room, room). Only printing waits for room. The kernel's port has no queue.
• §8 storage (ruled 2026-10-07, "v3's way in full"): every node asks the kernel for a block by number on port 0 (requests -1..-5: BLOCK BUFFER UPDATE SAVE-BUFFERS EMPTY-BUFFERS); the kernel keeps the node's window of four 256-cell slots (v4/system/blocks.c over v3/src/block_subsystem.c). §8.6/8.7 list what was WITHDRAWN (disk as a port device, nodes without storage, per-node drives, device identity in header). Not yet: who may have which block (needs identity).
• §9/§9a births follow v3 (2026-10-16): any node may birth, parent = the asker; KILL/PAUSE/RESUME are Hera's alone, by number; the kernel keeps the registry (v4/src/manage.c), requests -6..-18 (NODE-ME, NODE-BORN, NODE-WIRE, NODE-UNWIRE, NODE-SLEEP, NODE-WAKE, NODE-KILL, NODE-PARITY, CAPSULE-OPEN, CAPSULE-CELL, CAPSULE-LINE, NODE-CHILD, NODE-PLACE). The KERNEL tells a node's going (GONE), no node hands it on (amended 2026-10-20). Capsules capsules/v4/centre.4th (blocks 8100+) and hera.4th (8000+).
• §10 steps: 1–7 done (7 in the fabric under test only). Steps 8 and 9 NOT done: the hosted product and bare metal are still ONE node each (issue #85). Step 3 leftover: KEY/EXPECT/QUERY still read console registers, not messages (issue #84).
• Recurring method in this file: design → plan → build test-first → independent review "told to break it" → Bob rules "fix them all, test first" → verify on six systems with log dirs cited. "No bad code is ever released."
• dict_hash history (word_count 317/318): 0x220ab283a504a3b3 (10-07, 314 words) → ... → 0xe5a57f3eb72ff94a (10-13) → 0x248b4edc47f4357e (10-16, 318) → 0xfec8c47cfc6f437f (10-20, 317).

docs/v4.0.0/plans/ — step plans (all executed; format: Goal, Rulings, Global Constraints, Review Focus, Tasks with failing test first)

• Every plan repeats the working contract: branch StarForth-v4.0.0; strict C99 -Werror; v3 behaviour unchanged; QEMU/bare-metal parity; "no fix outside the plan; report it"; each task = failing test written and SEEN to fail → implement → pass → regressions → full acceptance → commit with the logs. No kernel unit tests: kernel tests are QEMU sessions driven by scripts/qemu_session.py over serial + QMP. Every new console/log message ≤ 63 chars (LOG_LINE_MAX 64 truncates; known defect, awaiting ruling).
• Plans say: commit with the LFS filter OFF (git -c filter.lfs.process= -c filter.lfs.clean=cat -c filter.lfs.smudge=cat -c filter.lfs.required=false) and push with GitKraken's git-lfs on PATH. That is how logs end up committed as plain text against .gitattributes — see discrepancies.md.
• 2026-10-20 engine-step4 (node in the VM's place), revised under MACHINE.md: Q1–Q5 ruled as recommended. Phases: Gate (done) → A (hook at call; every word but >R R> R@ I J LEAVE called) → 1 v4 in the kernel's boot → 2 word accounts at call → 3 init.4th/starforth.4th → 4 ACL → 5 Artemis writes → 6 identity/prompt → 7 physics on word records (v3's whole POST passes = parity) → 8 v3 leaves the build. Only Part A is written out; later phases get their own plan when the previous is accepted. v3 has 526 words before its prompt, a node has 317/318: the gap is the parity work (#4).
• 2026-10-26 identity gate (done): D1 split capsule_zuse_boot_check out (no VM); D2 recognise only (genesis later — later lifted by stick-5); D3 prompt [zuse@Hera] ok>; D4 minted pair the QEMU default (later replaced by the fresh data stick). New files kernel/src/v4/sk_v4_identity.c/.h.
• 2026-10-27 stick-4 (one disk): loader passes BootDisk {gpt, is_stick, disk_guid} in BootInfo; partition type GUIDs: identity 23BEBFE1-4817-4CF3-A537-9069BF159788, Artemis BCD7B586-1C8E-4EEF-86A3-273A8D8EE624; chain on v4 = fast RAM, ramdrive, stick's Artemis, its identity; detach tail-first; amd64 QEMU gets RDRAND; screen=boot keeps the console on screen until login (for the SER5, which has no serial port).
• 2026-10-29 stick-5 (proxy Zuse, growth, real Zuse; Tasks 1–5 all accepted, #92 done 2026-11-10): marker v2 {magic, version, proxy_pubkey[32], real_pubkey[32], has_real, crc}; sk_v4_marker.c, sk_v4_grow.c, sk_v4_mint.c, gpt.c writer (gpt_grow_last, gpt_write_one); R1 cap 256 GiB because the block map costs 2 bytes of kernel heap per 1 KiB block and the heap is 2 GiB; MINT-ZUSE is kernel word request 2 in sk_v4_words[] (BYE is 1) → word_count 318, dict_hash 0x8c92508f748f99cf. Bob, 2026-11-08: "work in small increments and memorize frequently" — hence the Progress section kept at the foot of the plan, one line per increment.
• 2026-11-10 alpha4-documents: #138 Book of Fabric (docs/book/fabric.tex, make fabric, 722 pages), #157 dictionary (docs/reference/v4-dictionary.tsv, v4/tools/mkdictionary.py check, make dictionary), #126 Downloads/Documents pages (site/com/build.py --release TAG --sums SHA256SUMS, install.sh is Bob's).
• NOT YET READ in full: 2026-10-06 step6-storage, 10-07 step6b/6c/6d, 10-08 step6e, 10-15 machine-step1-rom, 10-15 mesh-rom, 10-16 mesh-step7, 10-26 stick-1, stick-2, 10-27 stick-3 (all executed; MESH.md and STICK.md already carry their outcomes).

docs/fabric/FABRIC-3.md — the LIVING record ("bare metal boot", opened 2026-09-04; 6,515 lines)

House style of every FABRIC entry: write the decision and reasoning BEFORE building; "investigated, not assumed"; findings are report-only unless Bob names them; close each item with a dated note citing real evidence (log dirs, commit ids); never silently drop a stale claim — correct it in place with the date. Paths in early sections are pre-reorganisation (src/starkernel/…, Makefile.starkernel); today they are kernel/src/…, kernel/Makefile.

• §I.1–I.2 (09-04): v2.0.1 fast-forwarded into master; version rolled back to 2.0.0 (2.0.1 names the SER5 hardware line and claimed unverified progress); tag v2.0.0 moved; branch v2.0.1 deleted. Versioning is SEMANTIC, not sequential (roadmap table in kernel/Makefile).
• §II three hardware scopes: amd64 = ANY x86_64 UEFI PC (Beelink SER5 is only the reference; anything SER5-specific is a bug); aarch64 = Raspberry Pi 5 only; riscv64 = Milk-V Mars only.
• §III amd64 audit (report-only, still open unless later closed): HPET base hardcoded 0xFED00000 (no ACPI "HPET" lookup); LAPIC base hardcoded 0xFEE00000 (MADT type 5 not parsed); i8042 and 8259 PIC poked with no FADT presence check; arch_cold_reset() uses the i8042 pulse instead of the ACPI Reset Register (live via BYE). Clean: COM1 probed before use; ACPI 2.0 then 1.0; GetMemoryMap/ExitBootServices golden path; APIC timer calibrated at run time; IOAPIC from MADT; PM timer port from FADT.
• §IV Pi 5: NATIVE boot (not UEFI — rpi5-uefi is archived). config.txt: kernel=kernel_2712.img, os_check=0, device_tree=bcm2712-rpi-5-b.dtb, enable_uart=1. Entry x0 = 32-bit DTB pointer. New files (aarch64): native_rpi5_entry.S, rpi5_native_boot.c (DTB → existing BootInfo, then the unmodified kernel_main()), rpi5_mailbox.c (VideoCore mailbox framebuffer), rpi5_dtb.c (UART/mailbox bases, soc ranges offset 0x10_0000_0000), hal/fdt.c extensions. GIC bases and PSCI conduit now come from the DTB with QEMU constants as fallback. RP1 sits behind Broadcom's INDIRECT PCIe config window (brcm,bcm2712-pcie), a third config mechanism — not implemented (no QEMU model; needs hardware). Pi 5 RNG: no known register; not a boot blocker. No non-amd64 ISA turns its MMU on (VA == PA).
• §V Mars: U-Boot + OpenSBI + DTB, entry a0 = hart id, a1 = DTB. PLIC base from DTB (sifive,plic-1.0.0) with QEMU fallback; satp cleared only if not already Bare. JH7110 display and PCIe unresearched. riscv64's SBI timer and SBI SRST reset are the most portable of the three.
• §VI hardware reference (SER5 = some Ryzen 7; Pi 5 = BCM2712 4×A76; Mars = JH7110 4×U74; Zynq PZ7020 for the FPGA milestone; BeagleBone Black noted only).
• §VII xHCI/BOT went multi-device (closed 09-05): per-slot xhci_msc_slot_t registry sized off dev->max_slots; pending connect/disconnect queue; boot scan no longer stops at the first port. Bob's rule quoted: "we REALLY need to not paint ourselves into ANY scale issues by taking an easier way out." A worse bug found only by live two-device testing: transfer_purpose/next_action were shared scalars.
• §VIII (09-05) headless-until-login: EMERGENCY_CONSOLE_ENABLED default n — no banner, no prompt until an identity drive logs in; a runtime VM error halts (no recovery REPL) in production builds. "There should be nothing special about zuse as a user except zuse has no acl's." KILL now detaches the console if it kills the USEd VM.
• §IX (09-06) four bugs found by actually minting the 8 identity thumbdrives; IX.1: detach of an unrelated drive ended Zuse's/WIREBIND's session — both now compare the departing device.
• §IX.2–IX.5 (09-06): vm_cleanup() never freed DictEntry allocations (leak → PANIC after 8–9 birth/kill cycles); sf_free() was a deliberate no-op bump allocator → real free list; headless gate re-engages after a mid-boot logout ("we should never see an unauthorized, no session forth prompt"), via live sk_console_identity_present(); MINT verifies its own write (MINT_ERR_VERIFY_FAILED).
• §X (09-06/07): "4th device fails" was QEMU's xHCI having only 4 real ports (auto-inserted hub) → XHCI_PORTS Make variable (default 16), explicit port=; real driver bug: Configure Endpoint submitted unconditionally with several outstanding → single-in-flight. Heap: identity = 2 VM births = exactly 457,392 bytes; the 4 MiB alloc_kernel.c arena was the wall → sf_malloc/sf_free now delegate to kmalloc_aligned/kfree (the kernel's real heap: 2 GiB default floor, --heap=, splits and coalesces). Orphaned console VM on a failed WIREBIND birth now killed. Open lever: per-VM dictionary size. Flagged not fixed: printf '$(KERNEL_ARGS)\n' breaks when args start with --.
• §XI (09-07/09): MINT restricted personality (capsules/acl-std79.4th, ACL-LOCKDOWN-STD79, allowlist of ~200 FORTH-79/83 words; -1 MINT); storage attach goes Hera → Artemis by message (HERA-BLK-ATTACH-REQ / BLK-ATTACH-ACK); "identity attach never completes without Zuse" was TWO bugs: (1) blk_migration_idle_check() scanning ~16,000 devblocks every idle tick (fixed: has_ever_claimed, resume cursor, budget 256) — found by a fresh reader of the code after hours of live forensics; (2) cert verification gated on Zuse's live session instead of her persisted PUBLIC key (zuse_genesis_marker_t → zuse_root_pubkey). Bob: "zuse is zuse, [each identity] is [itself]". A guest's ACL denial used to halt the whole machine → only Hera's own session fails closed; a guest session prints "VM fault -- session recovered, resuming". xHCI now drives Port Reset on port reuse; WIREBIND teardown kills the console VM too. All 9 thumbdrives minted; 8 non-Zuse ones carry the restricted personality. Lesson recorded: check for a leaked qemu-system-* process before believing a slow/odd result.
• §XII.1 (09-10): EXEC no longer clears the capsule's blocks afterwards, so a locked-down identity can LOAD them (standard word) — capsule_exec_init() in capsule_loader.c.
• §XII.3 (09-10): use-after-free — sk_repl_run() captured active before a blocking read; a detach of A then attach of B never showed in the generic "anyone attached" boolean. Fix: re-read g_repl_active_vm after the read. Rule recorded: compare IDENTITY, not a boolean guard. The .elf is not the running binary for the monolithic build — use console probes compiled into the image, not GDB symbols.
• §XII.4 (09-11) 27-leg campaign (9 identities × 3 ISAs), cross-identity parity perfect. Bugs fixed on request: M* treated a double as 32-bit halves → __int128 multiply; M/MOD same class → hand-rolled 128÷64 restoring division (no __udivti3 in a freestanding build); D+, D-, DNEGATE, d_compare used bare unsigned long, which is 32-BIT ON THE aarch64 CROSS TARGET (64 on amd64/riscv64) → ucell_t. Lesson: cell_t width ≠ C long width; never use long for cell arithmetic.
• §XIII (09-10) heap corruption on the 3rd WIREBIND cycle = same stale-pointer class: sk_console_readline() kept calling sk_repl_idle(active_vm) on a freed VM, and blk_vm_flush_all() wrote into kmalloc's free list. Fix: re-resolve the live VM on every idle tick. kmalloc_debug_census() kept as permanent tooling; all other probes reverted ("write, run once, capture, revert").
• §XIV concurrent attach gap (only some of 8 simultaneous drives detected) — never fixed directly; no longer reproduces 2026-10-14 on all three ISAs (5/5), probably the xHCI pending-events queue. Note in that entry: every image under disk/thumbdrives/ and disk/artemis.img is ALL ZEROS since e56974e0 (bleached).
• §XV (09-11) std79 DoE: 3 arch × 9 identity × 3 rep, randomized (Fisher-Yates, seed 12345), all in FORTH (experiments/std79-doe/std79-doe.fth), driven by VM-EXEC. 81/81 correct. Rule: "any defect repair requires rerunning the DoE from the top."
• §XVI: aarch64 stall = stadium_admit() eviction fallback scanned all stadium_ncells (335,544 on a 4 GiB guest vs 83,886 on 1 GiB) instead of the VM's own residents → per-quota resident list. Stadium sizing: 1% of heap for cells, 50% of the rest for VM slots. §XVII: grant from stadium_best_donor() (most free cells), not always Hera; free_count O(1).
• §XVIII (09-12): per-tick CSV gained fleet_k_q48, fleet_conserved; K = 1.0 (Q48.16 65536) on all 775 ticks, sd 0. Report: experiments/std79-doe/report-20260912/report/std79_doe_report.pdf.
• §XIX: honest caveat — execution was strictly SERIAL (VM-EXEC is a synchronous C call; idle VMs accrue zero ticks), so K's result checks sequential accounting, not concurrency. Direction agreed: no scheduler; a compudynamic turn-attractor (coolest live VM goes next) in capsule_vm_physics.c. VM-HEAT word added.
• §XX (09-12): Hera could not message because 8 STADIUM-* primitives were registered for child VMs but not for her; an undefined word during compilation SILENTLY DROPS the definition. Fixed "by symmetry, not special-cased". 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." (All of §XX–§XXIII describes v3's FORTH messaging; the Hermes VM and messaging.4th were removed 09-22.)
• §XXI turn-attractor on messaging: priority = (heat gained this campaign) / reps remaining; sender pays; one message per rep (27 sends, not 648) because MSG-SEND silently no-ops when the reservoir is dry.
• §XXII riscv64 "stall" at 9 VMs = the idle pump dispatched MSG-TICK into EVERY live VM every beat (O(N)); fixed with round-robin batching (SK_MSG_PUMP_BATCH 4). Bob: "we really will be giving birth to potentially hundreds of VMs." Method lesson: three premature kills on "no output" — sample the qemu process's /proc/<pid>/stat utime to tell slow from stuck; run_doe_batch.sh now writes host-sample-*.csv.
• §XXIII: N-REPS > 3 loses data (reservoir refills ~6.8 units/s); left at 3 (this is issue #51, blocked). capsules/init-0..9.4th renamed workload-0..9.4th.
• §XXIV: a Block N collision is a silent PERSISTENT disk overwrite (capsule blocks land in Artemis's range, LBN 3072+). mkcapsule --resolve (interactive renumber), tools/capsule-claims.txt (derived, ignored), tools/capsule-reserved.txt (human, tracked), tools/patches/. "mkcapsule is our secret sauce linker." mkcapsule.c (1600+ lines) is due an ETL-shaped decomposition (not done).
• §XXV: governing principle in Bob's words: "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, born per trial and reaped. BIRTH/CAPSULE-BIRTH registered for every VM and carved into ACL-STD79-LIST (block 4048) as the one deliberate non-standard exception.
• §XXVI (09-13) CORRECTION: the "lockdown never engages" finding of §XXV was wrong — the wrong VM was tested. WIREBIND births TWO VMs per identity: console proxy <user> (not locked) and <user>~user (locked). Lesson: confirm which VM a name resolves to before concluding anything. Console prefix unified to [user@VMName]. Flagged: the messaging DoE had been driving the console proxies, not the ~user VMs.
• §XXVII: disk-backed log ring on Artemis (kernel/src/log_region.c, devblocks 65–96 from top; eligibility list 1–63 (now reserved/unused), artemis_sig_t 64); LOG-APPEND attributes the source VM itself (no caller-supplied source) and is pinned. Banner: "StarForth CLI", no em dash (font cannot draw it).
• §XXVIII (09-13/14) preemptive switching between v3 VMs, staged with go/no-go gates, one commit + full 3-arch acceptance per stage. Discovery: every VM ran as recursive C on ONE shared kernel stack. Stage 0 full trap frames (amd64 gained FXSAVE/FXRSTOR — a real pre-existing FP gap; aarch64 +v8–v15; riscv64 +s0–s11, fs0–fs11). Stage 1 a guarded 2 MiB native stack per VM (sk_vm_native_stack_alloc). Stage 2 sk_vm_switch_to/prime in per-arch switch.S, vm/switch.c, VM_STATE_SWITCHED_OUT; KILL refuses a switched-out VM. Stage 3 timer sets a flag only; the switch happens at a per-word checkpoint on the mainline (word granularity ruled "fine grained enough"); readiness signal in capsule_vm_switch_signal.c. XXVIII.1: "Stage 3 CLOSED" had overclaimed — a quiet log looks the same for a healthy idle REPL and a livelock. Real defect: checkpoint fired inside nested VM-EXEC on a borrowed stack → only at the OUTERMOST vm_interpret() (g_vm_interpret_depth). XXVIII.2: has_work eligibility (SWITCH-MARK-WORK); "who is current" tracked in switch.c, not by log attribution. XXVIII.3: off-by-one dsp < 2 (dsp is an INDEX, -1 = empty) set vm->error on every MSG-SEND. Verification rule: prove liveness by typing over QMP send-key and seeing a computed answer, not by log growth.
• §XXIX/§XXX Stage 4: WIREBIND user VMs are switch participants; per-device live table (13 slots); tombstone pending_reap + capsule_vm_force_reap() at the switcher's safe point. Found, pre-existing: interactive USE <identity> on a fresh WIREBIND identity halted the kernel.
• §XXXI DoE rerun after Stage 4: 81/81; harness bug (waited for ANY attach line, not the named one) had reproduced §XIV — check VM-EXEC: VM not found count is zero before trusting a run.
• §XXXII (09-15) new initiative scoped: human vs unattended identity, the USE halt root cause, a primitive error-handling audit, logging cleanup. All FABRIC files were read before planning it.
• §XXXII.1: any unknown word typed at Zuse's console used to HALT the kernel (Zuse's session runs on Hera's own VM; Hera's session failed closed). Now both sk_repl_step() and sk_repl_run() recover unconditionally ("VM fault -- session recovered, resuming"); sk_fault_handler() removed. Verify at ZUSE'S console.
• §XXXII.2 (ratified 09-16): unattended identities = cert + personality, NEVER a seed; minted at run time against a RAM scratch device (MINT-SCRATCH, MINT-SCRATCH-EMIT), hand-transcribed into a .4th capsule, born with UNATTENDED-BIRTH; CONSOLE-ATTACH pairs a console later. Invariant: an unattended birth must never touch the console-pairing global (would open a prompt with no human present). No C capability bit — ACL policy belongs in ACL.4th.
• §XXXII.3–.6 error-handling audit of the kernel-only words (v3): 105 vm->error = 1 sites triaged, 75 silent ones given diagnostics in 7 batches. Rules that came out of it: an interactive command's direct reply goes to the console; everything else goes through log_message(); in a function, match the convention its other guards already use; defer_words.c is the model (report, then fault). SWITCH-MARK-WORK and VM-HEAT must never error (hot path). Found two real NULL-deref guards in vm_compile_call/vm_exit_compile_mode. The vendored word_source/ files (e.g. memory_words.c pre-checks in @/!) were left for FABRIC-4.
• §XXXII.4 log ring eviction is level-aware (ERROR/WARN protected); log_region_append() returns 0 / 1 (dropped by design) / -1. LOG-FLUSH built later (10-14, §XXXVIII).
• §XXXIII (09-16) multiuser/multitasking DoE design (issue #58, deferred past bare metal): factors concurrency 2/4/8 × workload uniform/heterogeneous; "rule of 3's" in every DoE. New words WORKER-BIRTH (no identity), VM-ERROR?; every birth caller must itself call capsule_vm_registry_set_name() and vm_physics_init() — capsule_birth_baby() does neither. Heat only moves from a VM's SECOND touch. Per-tick CSV = doe_log.c (HB-ON/HB-OFF, off by default), columns vm_name, vm_id_hex first. Capsule format rule found: a : … ; definition and any control structure in it must fit inside ONE 16-line block (the loader keeps no control-flow state across Block headers). workload-5 = ~2.4 trillion word executions per call, workload-1 ~875M at birth → -lite variants. One physical terminal = one foreground session by construction (multi-seat is a deferred idea).
• §XXXIV: THRU/LOAD swallowed the rest of their line (fixed 10-14: vm_interpret() saves/restores the outer text). A second Claude session killed a live campaign by assuming a running QEMU was an orphan — NEVER assume a live qemu is an orphan; check its command line and log first. 30 reps/cell would have been ~10.3 days → ratified: per-ISA, one seed per ISA, 6 cells × 3 reps = 18 trials/ISA, ~24.8 h/ISA. Stop a campaign with SIGTERM to the qemu process (not the wrapper) so the Makefile's cleanup and scripts/extract_doe.sh still run.
• §XXXV.1–2 (09-17): block-backed DoE persistence design (issue #60): bare metal has no host to scrape serial; disk/artemis.img was 30 MiB, raw per-tick data ~64 MB/trial; the metadata fence is addressed BACKWARD from the end of the device, so a naive resize moves every fence consumer.
• §XXXV (09-17, design only): persist ONE binary record per trial in a new fence region (97+ from top), host reads it back after; prefer N=2 reps/cell; §XXXV.6 ratified a fresh 1 GiB disk/artemis.img and a full re-mint (never done for the committed images; they were bleached — see §XIV note).
• §XXXVI (10-14) one delivery path: a VM takes its own kernel-Hermes messages on its own turn, on its own native stack; Hera's idle beat runs only her own. Found: amd64 first-entry frame left rsp misaligned (#GP on an aligned SSE store) → 64-byte frame.
• §XXXVII (10-14) security: KH-ELEVATE-SEND and KH-BLK-ATTACH-SEND let ANY identity run text as Zuse on Hera — elevation removed entirely (ruled not needed: "privilege comes from the drive"); KH-BLK-ATTACH-SEND only from Artemis, BLK-ATTACH-ACK only by Hera; a message could run twice (drain now pops before running). v3 baseline became 523 words / 0xb73b58052d591638, then (§XXXVIII, LOG-FLUSH/LOG-SHOW) 526 / 0x82f4ae7cb2e2d424. The freestanding snprintf has no %lld, no %016llx, no %f.
• §XXXVIII LOG-FLUSH (every VM) / LOG-SHOW (Hera only): per-VM 900-byte buffer; flush = one kernel-Hermes message type 10 to Artemis; flushed on demand, when full, and at once on ERROR; ring-growth bug fixed.
• §XXXIX Pi 5 native path: MMU + caches on in the entry stub (identity map), bounded mailbox waits, framebuffer address via dma-ranges. Rehearsal target: make -f kernel/Makefile ARCH=aarch64 RPI5_NATIVE_BASE=0x40080000 rpi5-rehearsal (QEMU virt at EL2). It found: PL011 register shift, GIC address through ranges (fdt_reg_address()), no IRQ at EL2 without HCR_EL2.IMO/FMO/AMO.
• §XL xHCI found by PCI class 0C/03/30 from any vendor, real BAR size, BIOS handoff, 64-byte contexts (handoff and 64-byte contexts unproven until the SER5). §XLII every controller (up to 8), per-controller slots.
• §XLI USB HID boot keyboard (kernel/src/usb/usb_kbd.c), Caps/Num Lock, keypad; serviced every timer tick while waiting for a key. S3: a PC with no PS/2 controller hung in i8042_init() (0x64 reads 0xFF) — fixed. "Keyboard VMs" noted as a concept only.
• §XLIII system=v3|v4 boot argument; then (same day) v4 the default everywhere; acceptance = three ISAs as built (v4) + make -C v4 test-32; "i don't care about v3".
• §XLIV (10-29) first SER5 boot faulted in the loader: ~9,000 32-bit absolute relocations break when firmware loads the image above 2 GiB (QEMU q35 always loads low). Ruled: -fpie + everything hidden (kernel/include/starkernel/pie_hidden.h, #pragma GCC visibility push(hidden)), link refuses R_X86_64_32/32S/GOT relocations (AMD64_RELOC_FORBIDDEN), and qemu-stick-high (pc machine, 3 GiB) joined acceptance. The SER5 itself: new stick not yet booted at that entry.
• §XLV.1–2 (11-06) "the Captain Bob method" ruled; static review of v4 (11-02) fixed three bugs in fd208825 (hosted over-long line, bare-metal line cut at 255, a refused store still moved A/P); logs + DoE CSVs renormalised into LFS (027b144e, 1,003 files); make ARCH=… init installs the toolchain; scripts/nightly.sh stages: accept <isa|stick-high>, test-32, proofs, images, publish, docs, publish-docs.
• §XLV.4–8 (11-06): workflows nightly.yml 03:00 UTC, nightly-docs.yml 04:00 UTC, release.yml on tag v<LITHOS_VERSION> (a tag naming another version is refused), acceptance.yml on every PR into master, build.yml on every push. Nexus coordinates org.starship:kernelImage (classifiers pc, pc-stick, raspi5, milkv, logs) and org.starship:documentation (book, vol1..3, api, fabric, dictionary); classifier = the BOARD, not the ISA. Runner container pinned (gitea/runner-images:ubuntu-24.04-v26.11.03, later the project's own lithosananke-runner). Branch protection on master: no push by anyone, merge needs Acceptance / Acceptance (pull_request), PR must be up to date, admin override blocked. StarForth repo archived as tag archive/starforth-2026-09-17 and deleted. Repo renamed LithosAnanake → LithosAnanke (redirect kept). Gitea: wiki off; labels kind/ priority/ (exclusive), area/, board/, status/; the project board has no API. The .org XWiki is the project's entry point, the .com its public face.
• §XLVI (11-07) StarshipOS CA: Root CA (Ed25519, 20 y, key only on the CI box in /var/lib/starshipos-ca) and "StarshipOS Capsule Signing" intermediate (10 y) in the tree as capsules/pki/starshipos-intermediate.der; ci/pki/make-ca.sh; signing key = repo secret CAPSULE_SIGN_KEY; SIGN_KEY has no default, so local builds are UNSIGNED and log signature: missing (unsigned) — a warning by design. mkcapsule refuses a key that does not match the certificate. NOT done: the kernel does not check the intermediate against a root, and an unsigned capsule only warns (issue #139).
• §XLVII alpha releases: kernel LITHOS_VERSION 2.1.0 → 4.0.0-alpha.1; engine VERSION stays 3.2.0. 4.x is a working line (even major); LTS takes the next odd major. alpha.1 and alpha.2 were tagged but never published (the server has 3.8 GiB RAM: HOL-Library is prebuilt as a registry package, Isabelle capped to one thread / Java 512 MiB / Poly/ML 900 MiB); alpha.3 was the first published; "the tag stays where it is" — a failed release gets a new number, tags are never moved.
• §XLVIII (11-07 → 11-10): the ranked issue list after alpha.3 (milestone alpha.4, index #147); developer protocol #135 (scripts/nightly.sh protocol → PROTOCOL.md, checked by CI — not built); alpha.5 = the SDK (capsule repository in blocks #149, K under network latency #150); demo (try.starshipos-f18.com: ttyd behind Apache, guests 384 MiB, DEMO_MAX_GUESTS 2, "busy" message); #151 idle loop now arch_halt() (hlt/wfi) — QEMU 100% → 1% of a core; #131 was QEMU's serial capture doubling a byte under load, not the kernel; #155 BAM flush touches only the pages in use (1.1 s vs 5–6 s); licence headers: "Starship License, Version 1.0 (SL-1.0)" / SPDX-License-Identifier: LicenseRef-Starship-1.0 (patent/formal docs keep the old wording by ruling; capsules and proofs await a ruling); #156 retire v3 = its own milestone (what v4 takes from v3: the block layer, blkio, log, platform time, the VM * type in two headers; proof/'s 52 theories are all of the v3 VM); #158 a DoE per release; #92 done 2026-11-10 (Tasks 1–5). "Fabric is all about steady state" — the Book of Fabric is published.

What FABRIC-3 teaches about method (the nearest thing in the tree to a "Bulldozer" description)

1. Decide on paper first; Bob rules, usually from a short written trade-off with a recommendation.
2. Test first and SEE it fail; say so in the record ("Tested first, seen to fail"). Say when it was not.
3. Small increments, each with full three-ISA acceptance and its logs committed; no bundling.
4. Any defect repair invalidates earlier results: rerun from the top.
5. Root-cause, never patch a symptom; "no bad code is ever released"; "fix them all, test first".
6. Never trade scale for convenience; fix by symmetry, not by special case.
7. Record slips and corrections in place, dated; never quietly edit history.
8. Report what was NOT verified, and what was found but not fixed, every time.
9. Probes: write, run once, capture, revert. Check for leaked QEMU processes. One QEMU at a time.
10. An independent reviewer "told to break it" reads each finished step.

boards/BRINGUP.md (written 2026-10-13, amended through 11-10) — NOTHING here has run on hardware except the

SER5's first failed stick boot (10-29)

• Boards: PC (amd64, any UEFI PC; bench unit Beelink SER5), RASPI (Pi 5), MILKV (Mars), ZYNQ7020 (no ARMv7 port).
• Blocker table (IDs used across the repo and issues): A1 xHCI by class — fixed; A2 headless without login (bring-up builds set EMERGENCY_CONSOLE_ENABLED=1); A3 USB keyboard — fixed; A4 only disk driver is virtio (v3) — n/a on v4 (Artemis from the stick over USB); A5 entropy: RDRAND on amd64 only, virtio-rng elsewhere → Pi 5/Mars cannot mint; A6 both systems per image — fixed. PC: S1 HPET address fixed, S2 LAPIC address fixed, S3 i8042 half fixed (PIC unchecked), S4 BYE via i8042, S5 serial header unknown. Pi 5: R1 UART from DT — fixed, R2 MMU/caches — fixed, R3 mailbox partly fixed, R4 RP1 PCIe driver not written (no USB on the Pi 5), R5 no entropy. Mars: M1 UART layout — fixed, M2 framebuffer depends on U-Boot, M3 PCIe unknown, M4 image is the UEFI loader run by bootefi, M5 Zkr unknown.
• Order on the bench: SER5, Mars, Pi 5. Secure Boot stays OFF (unsigned loader, no shim; ruled 10-28).
• §4.2 the SER5 bench script for plug and play: first boot, second boot, MINT-ZUSE, system stick alone (fixed screen), both sticks at power-on — each rehearsed in QEMU by a named qemu_session.py mode.
• §5 pass levels 1–6 (level 4 = same parity as QEMU; 6 = hardware entropy + mint + re-attach).
• "Do not change two things between attempts." Logs/photos/firmware versions are kept and committed.
• STALE inside it: §5 still compares PARITY:M7.1a (v3) and says "once A6 is built"; §8 lists pre-alpha admin items (release number, CHANGELOG gap, SBOM, the old merge) that have since moved.

v4/README.md

• Five parts: engine v4/src; ROM capsules/v4/rom/*.f18 (built by v4/tools/mkrom.c); system source capsules/v4/sys/*.f18; capsules capsules/v4/*.4th; boot v4/system/boot.c.
• Products: hosted (make -C v4 hosted → v4/build/starforth4-{amd64,aarch64,riscv64}, static, 64-bit cells) and bare metal (kernel/src/v4/sk_v4.c).
• Targets: make -C v4 test (both widths), sanitize (ASan+UBSan), hosted-check (three ISAs, identical output, also a deliberately failing POST), post, post79 (regenerate cases; needs hosted v3), test-32.
• POST: 538 cases, 126 of the 130 Required words; 431 are v3's cases. Not tested: KEY EXPECT QUERY QUIT.
• Open: PAD 42 OVER ! (#12). "The Required Word Set list in tools/mkpost.py was written from memory of the standard and has not been checked against the document."
• STALE (issue #24): the opening still says "There is no POST and no K measurement yet", "circular stacks", "per-call-target heat", shows PARITY:V4_NUCLEUS lines, says forth79.4th holds two definitions and that the node starts "before the fleet tables"; "BYE is the one kernel word so far" (now also MINT-ZUSE).

docs/reference/ROADMAP.md ("roadmap and the ratified versioning policy")

• Versioning policy (ratified 2026-09-19, FABRIC-3.5 §XXX): ODD major = LTS (fixes only), EVEN major = working line (breaking changes); minor = release in the line; patch = working builds. Kernel LITHOS_VERSION and engine VERSION are independent. Engine bumps: major = FORTH-79-visible semantics change, minor = words added/removed, patch = build only.
• Five LTS criteria: real-hardware boot on the amd64 reference board with logs; no known reproducible silent-failure defect; ACL Phase 8 closed; proof/ boundary restated and not contracted; a soak of one release cycle.
• Three-product split (2026-08-29) and IP framing: Patent 1 + mark StarForth; Patent 2 + marks StarshipOS, LithosAnanke; Patent 3 + mark Compudynamics. The Dec-2025 provisional's conversion window is ~Dec 2026 ("#1 is on a hard clock"); "full StarshipOS is the December deliverable". Open points are for counsel.
• STALE throughout below the policy: "Current: M7.1", the ladder stops at v2.x/"v3.0.0 first LTS" (the kernel is 4.0.0-alpha.4; FABRIC-3 §XLVII says v3.0.0 is no longer the next LTS number), board gates v2.2/2.4/2.5, "POST 1012/0/0", M8 "OBSOLETE"/M9 "PLANNED" bars (README says both done in QEMU), validation commands use clean-kernel, examples show 295 words and LithosAnanke v0.3.0.

docs/reference/ (continued)

• word-acl/DESIGN.md (v3 word ACL): four DictEntry fields (acl_ttl, acl_allow, acl_mode, acl_pinned); hot path = one decrement + branch, cold path calls FORTH ACL-RECHECK; ACL-PIN one-way; birth copies mode, clears pin, resets TTL/decision; policy all in ACL.4th; Phases 1–7 done; 5 ACL_*.thy proofs. STALE: says EMERGENCY_CONSOLE_ENABLED default 1 (now n), "Phase 8 FUTURE/current open item" (closed 10-14), "ACL.4th opt-in commented out", CA key placeholder in Block 2066, src/... paths, "800/800" POST, "challenge-response" (ruled out). v3-only; goes with v3 (#156).
• kernel-args/DESIGN.md: says "Branch: lithosananke / Design complete — awaiting implementation" but it IS implemented (kernel/src/boot/cmdline.c, --heap=, --log-level=, --doe, plus later system=, screen=boot). REBOOT word design (NVRAM one-shot, max 3 tries) — implementation status unverified.
• hosted-acceptance-test/README.md: hosted v3 three-ISA test via qemu-user (make rpi4-cross, make riscv64-clang — riscv64 must use clang). Paths are pre-reorg (src/). v3-only.

experiments/bare_metal/README.md (MANDATORY before touching any .4th) + its CLAUDE.md

• Capsule format rules: first line of each block Block NNNN; numbers unique, ≥ 2048, no upper bound; ≤ 16 content lines × ≤ 64 chars per block; ( ... ) comments; : NAME ... ;; check with mkcapsule --lint capsules/. Shared namespace: 2048–2099 init.4th, 2100–2199 doe.4th, 3000–3999 workloads, 4000+ user capsules. (Plus FABRIC-3 §XXXIII.6: a definition and its control structures must fit in one block.)
• Only the exact filename init.4th is the MAMA_INIT capsule; workload-N.4th are alternate personalities.
• STALE: "the DoE runs automatically because init.4th calls it" (it does not; no DoE since 2026-09-16), Makefile.starkernel, logs2/, 15-column CSV (now 28+ with vm_name/vm_id_hex/K/switch columns).
• experiments/bare_metal/CLAUDE.md: the ACL-RWT campaign (+0.0054–0.0088%) is superseded; use +0.0603% ACL-TTL overhead, CV 0.000% (FABRIC-1 §T).

disk/README.md

• Committed QEMU fixtures; convention: every test disk image lives in disk/ and is committed.
• disk/zuse-scratch/{artemis.img, zuse-thumb-ident.img} = the minted Zuse pair (2026-10-26): a PAIR (marker on the Artemis fence names the drive's key). Boot COPIES; put back with git checkout -- disk/zuse-scratch. Since 2026-11-08 used only by tests that ask for it and by system=v3.
• disk/artemis.img rebuilt blank at 1 GiB 2026-09-17, never re-minted; artemis-30mb-pre-1gib-backup.img kept; artemis-unrecognized-test.img must stay byte-identical across a boot (regression fixture); artemis-debug-roundtrip.img must stay passing. artemis.img gains a mounted_time on every boot: revert it before committing.
• The stick and data stick are BUILD OUTPUT, not here (build/boards/pc/lithos-pc.img, build/<arch>/kernel/datastick.img), checked by scripts/check_images.sh.
• STALE: Makefile.starkernel, src/ paths, zuse.img (deleted per FABRIC-3 §X.1).

proof/COVERAGE.md (Isabelle/HOL, 52 theories, isabelle build -D proof/)

• Goal (Bob): not a green build but "identify precisely what cannot be proven and why". Companion proof/FINDINGS.md (file-scope statics standing in for per-VM state, missing overflow guards, duplicate registration, an unchecked pointer cast in EXECUTE).
• Covers v3's word_source/*.c word by word, the 7 physics loops, 5 ACL theories, Q48.16. Structurally not provable without big modelling: block-window cache, parts of TIB input, stdio, raw-pointer dictionary navigation, vocabulary statics, hot-words cache.
• ALL of it is about v3 (#156 proposes archiving under a tag). There are NO v4 proofs (issue #11).
• STALE: reproduce path is Bob's home directory; "generated 2026-08-14".

docs/fabric/FABRIC-4.md (ideas caught early, not scoped)

1. A Stadium-level "wheel": a second clock (Q48.16 phase accumulator, rate fixed first, adaptive only after a measured baseline) fed by fleet-wide rolling-window/inference output; a gate for a future "sieve stack". Purpose deliberately not stated yet ("we'll talk about why later").
2. A pinned GPIO VM per board (Pi 5 yes; Mars undecided). (Pre-dates "Hera/Hermes/Artemis are kernel".)
3. "Information state over information moment" (10-16): Bob's theory of information; H0/H1 written: delivering facts as persistent state vs as instantaneous events (signals/interrupts); measures loss, corruption under pressure, variance, cost. Bob's question to answer, not scoped.

• Note: FABRIC-3 §XXXII.3 says the vendored word_source sweep was "spun off as its own future FABRIC-4.md"; that content is NOT in FABRIC-4.md.

CHANGELOG.md — milestone-level entries; alpha.1–alpha.4 (11-07 → 11-10), 11-06 gate, then a gap back to

10-09 and 08-18. Its footer flags master's INPUT_BUFFER_SIZE 256 — that was the old StarForth repo's master, no longer relevant here (check v3/include/vm.h in the code review).

Board READMEs, capsules/README.md, kernel/src/hal/README.md

• boards/README.md: TARGET → dir/ISA/boot path/image; board.mk vars BOARD_DESC/ARCH/BOOT/IMAGE; scripts/mkdiskimage.sh (no root, no loop devices); default image 128 MiB (the PC stick is 2 GiB).
• STALE: boards/pc/README.md says one FAT32 partition (it is the three-partition stick since 10-27); boards/raspi/README.md says the EL2/MMU-off difference "has not been exercised" (FABRIC-3 §XXXIX rehearsed it); capsules/README.md lists hermes/init.4th (gone), says "1024 bytes, verify with wc -c" (wrong rule), EXEC-DOE; kernel/src/hal/README.md header path src/starkernel/hal/, no mention of fdt*, rpi5_*.
• Zynq: board is a Puzhi PZ-StarLite (Zynq-7020): FT232HL JTAG (no AMD tools — ruled; openFPGALoader/ OpenOCD), CH340E serial; trial Cortex-A9 compile built 147/151 sources (fails: fe25519.c, scalar25519.c, hal.c, mixed_arithmetic_words.c — __int128). Vendor files are on Bob's machine, not in the repo.

docs/v4.0.0/POST79.md (generated by v4/tools/mkpost.py from post79_rules.py — do not edit by hand)

• 538 cases = 431 v3 cases (v3 binary's results as expected) + 59 rewritten for FORTH-79 + 20 address-dependent (count of values checked, not values) + 28 hand-written (words v3 has no case for), with 39 v3 cases left out.
• Rewrites encode the standing ruling "FORTH-79 wins": PICK/ROLL from 1, >R R> R@ only inside a definition, <# # #S #> on doubles, MOVE moves cells, LEAVE ends at the next LOOP, FIND leaves 0, vocabularies separate, >IN is an offset.
• OPEN: 12 C!/C@/FILL/COUNT/CMOVE/TYPE cases out because HERE is a cell address and those take byte addresses (they wrote into the nucleus's code), and PAD.usable (#12).
• Not tested: KEY EXPECT QUERY QUIT. 6 cases where v3 contradicted its own table.

proof/FINDINGS.md (v3 sweep, 2026-08-14)

• File-scope statics standing in for per-VM state: #1 control-flow compile state and #5 vocabulary subsystem FIXED 09-05 (vm->cf, vm->vocab); still open: WORD scratch, system_running/79-STANDARD flags, g_prng_state (shared RNG across VMs), TTF ready flag, INTERPRET's dead state_variable.
• VM_PUSH is unchecked only under STARFORTH_PERFORMANCE, which no build defines. DECAY-RATE@ fixed.
• Dead duplicate registrations removed ([ ] STATE, DEFER IS DEFER@); starforth_words.c double registration untouched.
• One-offs: EXECUTE pointer cast, ?/DUMP, TYPE overflow, DECIMAL/HEX/OCTAL fixed 09-05; still open: LATEST == HERE in v3; INFER-* errors AND pushes; three different L8 selector representations.

docs/fabric/FABRIC-3.7.md — CLOSED 10-14 (elevation not needed, removed; see FABRIC-3 §XXXVII)

• Its own correction: §2's "raw cross-VM address" claim was wrong (the caller copied text); recorded struck, not deleted. Lessons kept: read how the caller builds a message before diagnosing the callee.
• Ruled 09-23: no knowledge factor, ever — "There's only the drive." A byte-for-byte drive clone made OUTSIDE StarshipOS is accepted by design; cloning from WITHIN (MOVE/CMOVE/CMOVE>/RELOCATE-BLOCK across devices) is refused (Phase 8 v3). Plans referenced in Bob's ~/.claude/plans/ (not in the repo).

docs/reference/M7.1.md (capsule architecture, v3; "shipped and live")

• The Immutable Law: exactly ONE production (p) INIT defines a baby VM; no shared/base INIT. DOMAIN is Mama-only (construction/selection), PERSONALITY is the baby's only truth. "Names lie. Hashes don't."
• CapsuleDesc 64 bytes (magic 'CAPS'|ver|hashAlg, capsule_id == content_hash xxHash64, offset, length, flags, owner_vm, birth_count, created_ns); flags ACTIVE/REVOKED/DEPRECATED/PINNED, mode PRODUCTION xor EXPERIMENT; REVOKED overrides ACTIVE; (e) capsules never touch babies. Parity lines PARITY:BIRTH, PARITY:RUN, PARITY:BIRTH_FAILED; VM states EMBRYO/LIVE/DEAD/STILLBORN.
• STALE: implementation checklist all unticked though built; src/starkernel/ paths. Superseded for v4 by MACHINE.md (capsule = ROM + .f18/.4th trailer).

docs/INDEX.md — 547-row catalogue of every document with a status (CURRENT/WORKING/HISTORICAL/SUPERSEDED/

DEAD/RECORD/FORMAL/LEGAL HOLD); last edited 2026-10-14, so it lags (README listed as "v2.1.0", CONTRIBUTING as CURRENT). Hand-maintained (docs/CLAUDE.md). Skimmed, not read row by row.

docs/fabric/FABRIC-3.5.md (design of the Tripod/kernel reshuffle; CLOSED at v2.1.0, 2026-09-22) — structure

read fully, key sections read in full (§XV, §XXII, §XXXV); the rest by heading

• Outcome: Hermes VM → kernel-Hermes (C); Tripod = Hera/Artemis/Hestia; BIRTH general; one failure ladder; SOS message type 10; Hestia = the console's VM face (HAL must never know a VM exists); versioning policy (§XXX); kernel-Hermes sinks when its own heat ledger stops adding up, epsilon zero (§XXXVI–XL).
• §XV the authority rulings — the philosophy in Bob's words: "Any VM can birth another VM that is almost a clone of itself with its own ACL DNA"; "Nobody declares a VM dead, it died a compudynamic death"; "Nobody owns the turn order. The turn order is compudynamic"; and what survives a death: "nothing survives except K". Three of four questions answered by rejecting the premise: no owner, no supervisor, no scheduler — authority flows only down the birth graph, everything else is physics. Flag: SK_SWITCH_READINESS_THRESHOLD = 50u is a hardcoded seam.
• §XXII execution method (Bob): strip the anticipated-dead code FIRST, then code; more dead code "falls out" as code/test iterate. Category A (dead today) stripped first in its own commit + boot; Category B (dead on arrival of the replacement) only once the replacement runs. Reachability is NEVER established by grep alone (capsules are born by runtime-built names; DoE capsules are invisible to a boot). Treat experiment/DoE capsules as live by default.
• §XXXV pre-mortem (Bob asked for it before the build): "Things here fail without saying anything" — silent failure is this codebase's dominant failure mode; name in advance, per stage, the observation that proves it worked ("not 'it booted'"); SK_SWITCH_MAX_SLOTS 16 was a future wall; the most repeated failure is "declared done, and it wasn't".
• §XXXI gap sweep: FABRIC-2's close overclaimed; FABRIC-0 had seven open items.

docs/fabric/FABRIC-3.6.md (execution log of the reshuffle; CLOSED at v2.1.0) — handoff, standing rules and

findings log read in full; phase task lists by heading

• Its "five traps" for a fresh session (still true in spirit):
  1. silent failure dominates — a green boot is weak evidence; name the proving observation BEFORE running;
  2. grep cannot establish capsule reachability; 3. fleet_conserved cannot see Stadium heat (two decoupled accountings); 4. dict_hash CHANGING is expected, DIVERGING across ISAs is the stop condition — never "fix" a changed hash; 5. docs drift — trust the code, and record the drift.
• Standing rules: one task one commit; three-ISA boot is acceptance; lint clean; no task without authorization; report, don't fix in passing. Checkbox convention restored ([x] only when the check ran; [~] started) so "is anything open" stays answerable by grep.
• Task 0.0: capture a three-ISA BASELINE before changing anything, so the first red boot is interpretable. Shared disk/artemis.img confounded dict_hash across ISAs — reset disks before each ISA.
• Findings: a FORTH address popped in a C word must go through vm_ptr()/VM_ADDR() (raw cast silently read zeros); kernel-Hermes messages now COPY their payload (payload_buf) — pointer aliasing lost a second identity's attach; an unexplained 40-minute freeze (logs/20260922-092154) never reproduced, kept open; sk_console_readline() submitted CRLF as two lines (doubled ok) — fixed by peeking for the pair; noise: Stadium: dispatch lines were ungated console_puts → log_message(LOG_DEBUG).
• Prompt rule: [zuse@Hera] at top level; [rajames@rajames] once USE'd into an identity's console VM ("R.A. James is also a VM"). An over-ambitious first design was reverted, not patched forward.
• Out of scope carried: should a Stadium reservoir replenish (item 43); FABRIC-2 §17.4 re-home; .c.bak.

docs/fabric/FABRIC-0.md "the Stadium" (CLOSED 2026-08-12, 7,622 lines) — §1–15 design argument read in full,

§16–27 by heading

• The claim: four subsystems (Artemis blocks, Hermes messages, Console, ACLs) implement one physics; lift the dictionary one level and each becomes an instance. Five patron kinds: block, message, VM, word, ACL (the console's patron is the dirty EVENT, not the cell).
• The Stadium: one bounded region outside any VM holding what is LIVE (not everything that exists); allocated at boot before any VM. One entry shape (64-byte cell): identity, heat, TTL, pin, link (index, not pointer), code field (closed enumeration of behaviours, fixed at build time — "the code field is the entire type system"; a type field means the design has gone wrong), mass, payload, contains. A cell is a header or a continuation cell (side bitmap).
• Heat is conferred by traffic; conserved share of 1.0 (K); density = heat ÷ mass; "ranking is read, not decided — there is no scheduler because there is no policy". Departure: TTL, cooling, or never (pin).
• Storage is BENEATH (warehouse: Artemis, dictionary), devices BESIDE (utility: framebuffer), patrons ON the floor.
• Boot order: kernel opens the hall, Hera walks in first "and cannot be asked to leave".
• Admission test before any code: what does heat mean for this thing, and what is its reap event?
• Debt rules: never two live mechanisms at once (dual paths); no speculative generality; decide the exception early. Formal payoff: one datatype, no pointers, finite state, one conservation theorem.
• §14: K is 1.0 by construction (a correctness check, not a diagnostic); ENTROPY of the heat distribution is the real instrument; the system is a driven dissipative system ("Prigogine, not Carnot").
• "Phenomenon first, then mathematics."
• §16–27 (history): substrate findings, patrons, L0 engine, mass/density/K, VMs as patrons, nesting, elastic quota over one pool, 25.x punch list (phases 0–5), §26 the hardware heartbeat must itself be adaptive (RULED 08-03), §27 console as drawing fabric.

docs/fabric/FABRIC-1.md (CLOSED 08-25) and FABRIC-2.md (CLOSED 09-04) — read by structure and headers

• FABRIC-1: open items A–E carried from FABRIC-0; Stadium VM bound made RAM-derived (§G); quota-grant ordering bug (§H); aarch64 BYE SMC→HVC (§I); SDK v1.9.0 scoping (§K); Fisher-Yates SWAP-MTX never shuffled (§N); ACL-TTL overhead campaign → final +0.0603% (§P–T); Artemis thumbdrive / home-blocks / PKI design (§U–X).
• FABRIC-2: §B Stadium unification; §C standing rule: "I've never allowed stubs before." — no stub, no TODO-and-move-on, ever; small honest increments are fine, each a complete real slice; a stub found nearby gets flagged and resolved, not built on; §D Tripod final shape; §E the pile as a graph; §F scoped plans; §G release plan; §H session = VM, identity/ACL "card" model; §I consolidated punch list.
• Carry-forward discipline: when a FABRIC doc closes, every - [ ] is extracted mechanically into the successor, none dropped (FABRIC-3 broke the checkbox habit; FABRIC-3.6 restored it).

Archive trees — SURVEYED, not read file by file (be honest about this if asked)

• docs/working/ (253 docs; 128 under archive/): architecture notes, DoE designs/data, papers (claim tables, ANTI_CLAIMS, null hypothesis, SSRN companion), scratch (incl. old docs/src/ dev reference), legal (HOLD). Its README is the 2026-06-16 reorg note.
• docs/formal/ (255 docs; 210 scraps/): press-ready LaTeX — vol1 VM physics, vol2 kernel, vol3 research, dev/user guides, cookbook, standalone experiments/proofs/ssrn/patent. Rules in docs/formal/CLAUDE.md (draft 06-16): scraps mirror docs/working/ paths with a %% SCRAP/SOURCE/STATUS/FITS/EDITORIAL header, every claim checked against ANTI_CLAIMS.md, %% TODO(bob): for dictation, %% PATENT: flags. Note the tension with "no TODOs ever" — %% TODO(bob) is the sanctioned doc-tier marker.
• docs/patent/ (43 docs): provisional patent (SSM), claim map, USPTO cover letter. LEGAL HOLD — read-only, ask Bob before touching anything there or in formal/patent/, formal/scraps/legal/, working/legal/.
• experiments/ (49 docs): bare_metal analysis/reports (L8 DoE, ACL-TTL), std79-doe and its reports, std79-exerciser, artemis_stress.
• .claude/TRIPOD.md, HERMES.md, ARTEMIS.md, CONSOLE.md: each still opens "This document constrains Claude Code behavior. Read it completely before touching ..." — but line 7 (21 in CONSOLE) says SUPERSEDED 2026-08-15. Frozen; do not use for design authority. Not read in full.
• capsules/MANIFEST.md (551 lines, block ownership justifications; FABRIC-3.6 trap 5 says it is stale about blocks 4055 and 2049), BLOCK_MAP.md / MANIFEST_AUTO.md (generated) — not read in full.