Files
LithosAnanke/docs/v4.0.0/plans/2026-11-13-engine-step4-phase7-the-loops-and-parity.md
T
Claude 5c79bddbbb feat(v4): Phase 7 Task 3, first step -- each node's tick by execution, as v3 (#189)
Captain Bob, 2026-11-13: "By execution, as v3". v3's kernel runs a VM's heartbeat cycle every 256 word
executions (HEARTBEAT_CHECK_FREQUENCY, vm_core.c:912 and :1210), and its tick_count is the count of cycles.
Task 2a had used the kernel's timer heartbeat as the decay clock: corrected. Each node counts its word
calls; every 256th runs its heartbeat cycle at the call; the cycle's loops follow. The kernel no longer
gives the mesh its timer. Test first: test_mesh_boot.c, 59 checks (67 with pipelining and the cache on).
Not pushed (held to the end of Phase 7).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-13 22:17:50 +00:00

10 KiB

ENGINE Step 4, Phase 7: the physics loops on the word records, and v3's whole POST -- Plan

For agentic workers: steps use checkbox (- [ ]) syntax. One QEMU at a time, in the foreground, every boot under timeout 570 (.claude/CLAUDE.md, .claude/memory/rules.md); every log and CSV is committed. Test first: each change starts with a failing test.

Goal (#189): every loop v3 runs before its prompt runs on v4, on the kernel's word records (Phase 2), on every node; and v3's whole POST passes on v4.

Parent plan: 2026-10-20-engine-step4-node-in-the-vms-place.md, Phase 7; after Phase 2 (2026-11-13-engine-step4-phase2-word-accounts.md, protocol PASS on e8e7ec8b).

Rulings (Captain Bob, 2026-11-13)

  1. Every call, as v3. The per-call loops (decay on touch, the rolling window, pipelining) run at every call, from the hook, as v3's run at every execution -- not replayed from a trace each tick. Measured, kept or reverted on the numbers (as HEAT-OP was).

  2. Rewrite for v4. The loops are written afresh for v4's records, with v3's code (v3/src/rolling_window_of_truth.c, physics_pipelining_metrics.c, inference_engine.c, physics_metadata.c, physics_execution_hooks.c, compudynamics.c, ssm_jacquard.c, and the kernel's vm_runtime.c tick) and v3's POST as the specification.

  3. Accepted on v3's whole POST. Not the loops' own modules alone: every module of v3's POST passes on v4.

  4. Words in F18 and StarForth, not C (2026-11-13, on the Mama module: "do not compose words in C99, use F18 and StarForth"). Every word this phase adds -- the loops' (FREEZE-WORD, HEAT@, the inference words, the entropy words), Mama's, the StarForth words -- is written in the system's F18 or in StarForth. What only the kernel holds (a word's record, the window, the registry) is asked for by a request on port 0, as KERNEL-WORD words do. The loops themselves run in the kernel, on its records (Q4).

  5. Mama's 20 cases run as they are, on v4 words with v3's names mapped to v4's equivalents; the C modules (ACL, break_me) are rewritten for v4. Inventory and rulings: docs/v4.0.0/POST-PARITY.md.

  6. Pipelining and the hot-words cache: "Built, off as v3" (2026-11-13). Asked first "Build a hot-words cache" (in front of FIND, in F18/StarForth, as v3 promotes into its own); then it was found that v3 as built has both off (ENABLE_PIPELINING, ENABLE_HOTWORDS_CACHE: n in Kconfig.physics and kernel/Makefile), so v3's boot records no transitions and uses no cache. Ruled: both written and tested, behind the same two build options, off by default as in v3.

What ruling 3 brings in

v3's POST is 26 modules (v3/src/test_runner/modules/, about 1,050 cases; v3's bare-metal boot says 1050). v4's POST is v3's cases for the FORTH-79 Required Word Set, 539 (v4/tools/mkpost.py). The rest need words v4 does not have yet, which the parent plan put in other phases:

v3's modules Needs Parent plan's phase
physics_freeze, inference the loops, and the words that read and set them (FREEZE-WORD, ...) 7
starforth, q48, format, double (beyond the Required set), string, system, vocabulary, ... the StarForth words: init.4th, starforth.4th 3
acl ACL.4th on v4; the word card (the four ACL fields) on the record; the countdown at call 4
block the blocks the kernel serves; writes 5 (in part)
mama_forth, integration, break_me, stress to be read case by case (Task 0): some name v3's VMs and fleet --

So, by ruling 3, Phase 7 is accepted only when Phases 3 and 4 (and the block cases of 5) are in. The ruled order (Part A, Phase 1, Phase 2, Phase 7) stands for the loops; the words of 3 and 4 come in under this plan, as tasks of it.

The design

The records grow v3's physics. A word's record (v4_mesh_account, Phase 2) gains what a DictEntry carries for the loops: temperature, the last decay tick, mass, the state flags (frozen, pinned), and its transition metrics (by next word ID). Per node: one rolling window, one pipelining context, one L8 mode, one inference state.

At every call (the hook; ruling 1), in v3's order (V3-PARITY.md 2.1): decay the word by the ticks since it was touched (Loop #3, unless frozen or L8 has it off); its heat +1 (Loop #1, done); the Stadium (Phase 2 charges per tick: kept); the rolling window records its ID (Loop #2); the transition from the word before is recorded and the likely next worked out (Loop #4); the ACL countdown (with Phase 4).

At every heartbeat tick, for every node: the window tuner (Loop #5), the slope validator (Loop #6), background decay, L8's mode update, the inference engine, the snapshot -- as vm_runtime.c does for v3's VM.

Tasks

Task 0: the inventory

  • Every case of v3's POST, by module, in v3's own order: kept as it is, kept with v4's address units (D-1), needs a word of Phase 3, 4, 5 or 7, or names v3's VMs (Mama, the fleet) -- the last listed for Captain Bob's ruling, case by case, before anything is written for them.
  • docs/v4.0.0/POST-PARITY.md: the table, and the count v4 must reach (about 1,050; 539 today). Mama and the C modules ruled (above).

Task 1: the records' physics fields, and the per-node state

  • Test first (test_mesh_boot.c): a new word's heat, temperature, last decay tick and state flags are 0; each node starts with v3's decay slope (21845, Q48.16) and Loop #3 on; a word's state flags as v3 derives them (IMMEDIATE read from its header).
  • v4_mesh_account gains heat (v3's execution_heat), last_decay_tick, temperature_q8, state_flags (the kernel's own: pinned, frozen); v4_mesh_physics per node (tick, decay slope, L8's Loop #3 gate); v4_mesh_state_flags. Immediate and hidden are read from the node's header when asked, so they are never stale. v3's mass_bytes is only ever set, never read, in v3: not kept until a word reads it.

Task 2a: the per-call loops at call -- decay on touch, heat, temperature, the rolling window -- measured

  • Test first (test_mesh_boot.c, 56 checks): heat +1 a call; decay by the ticks since at v3's slope and arithmetic (6 ticks: 1; 3 ticks: 0); none for a frozen word, none while L8 has Loop #3 off; the temperature; the window.
  • mesh.c's call hook, in v3's order; the kernel's heartbeat read at each call (ticks). Until Task 3 brings L8, Loop #2 and #3 are on (v3's boot sets both off and lets its card decide).
  • Measured: amd64 boot 146 s, against Phase 2's 142 s (about +3%).

Task 2b: pipelining (transitions, the likely next word, speculation) and the hot-words cache in front of FIND, behind ENABLE_PIPELINING and ENABLE_HOTWORDS_CACHE, off as v3

  • Test first: test_mesh_boot.c built twice -- as the build is (off: no transitions, an empty cache; 57 checks) and with both on (make -C v4 mesh-boot-on, 65 checks): PA's 12 transitions to PB, its likeliest next; speculation after 10 puts PB in the node's cache; hits; FIND through the cache; PB defined again is taken out; a word past heat 50 goes in; FORGET takes the rest out.
  • The kernel (mesh.c), at every call: v3's hit check, the transition, the likeliest next (kept as each count rises, not a scan of 1024 a call: the same word but in a tie v3's Q48.16 rounding makes, recorded in the code), speculation at v3's thresholds (1/2, 10 samples). Counters from the owner's heap on a word's first transition; given back when it goes.
  • The node (dict.f18, (LOOKUP)): (HOT)'s xts tried first, in F18, calling only C@ as before; the kernel fills it as v3's promote, and takes out entries that go or whose name is defined again. Empty unless the kernel's build has ENABLE_HOTWORDS_CACHE.
  • One departure, ruled by default (Captain Bob did not choose; recorded): v3 promotes a hot word when a lookup finds it in the dictionary; v4's heat is the kernel's, so it is promoted at the call where it is hot.
  • Measured: amd64 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; 2b costs nothing measurable, as the host mesh boot also shows.
  • Reported, not changed (v3's own): with the cache full, v3's promote takes the next slot in turn without looking for the word already there, so a few hot words churn through all 32 slots (hotwords_cache_promote, v3/src/physics_hotwords_cache.c). v4 does the same. And v3 never calls transition_metrics_record_prefetch_miss: its misses are always 0, as v4's.

Task 3: the per-tick loops (tuner, slope, background decay, L8, inference, snapshot)

  • The tick, by execution (Captain Bob, 2026-11-13: "By execution, as v3"). v3's kernel runs a VM's heartbeat cycle every 256 word executions (HEARTBEAT_CHECK_FREQUENCY, kernel/src/vm/vm_core.c:912 and :1210), and its tick is the count of cycles; the timer heartbeat is not the VM's tick. Task 2a had used the kernel's timer: corrected. Each node counts its word calls; every 256th runs its cycle at the call. Test first (test_mesh_boot.c, 59 and 67 checks).
  • The cycle's loops, in v3's order (vm_heartbeat_run_cycle): tick; inference every 1000 ticks; background decay; the window's service; L8's update; the snapshot.

Task 4: the words that read and set them (FREEZE-WORD, the inference words, ...), and their POST

Task 5: the StarForth words (Phase 3's: init.4th, starforth.4th), and their POST

Task 6: the ACL (Phase 4's: ACL.4th, the word card, the countdown), and its POST

Task 7: the block cases (Phase 5's part)

Task 8: mkpost.py beyond the Required set: v3's whole POST as v4's; the floor raised

Task 9: acceptance -- the full protocol; ENGINE.md, V3-PARITY.md, FABRIC-3

Each task gets its steps when the one before it is accepted, test first, as Phase 2's did.

Review focus

  1. Cost at call (ruling 1): the boot's time under TCG before and after each per-call loop.
  2. Order: the window and the transitions see calls in the order they happen, across nodes kept apart.
  3. Recycled IDs: a word ID FORGET gave back starts with no physics (decay, window, transitions).
  4. The 32-bit build: the same results at 32-bit cells.
  5. What names v3's VMs (Task 0): ruled, not guessed.