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

146 lines
10 KiB
Markdown

# 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
- [x] 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.
- [x] `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
- [x] 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).
- [x] `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
- [x] 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.
- [x] `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).
- [x] 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
- [x] 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.
- [x] 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.
- [x] 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`.
- [x] 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.
- [x] 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)
- [x] **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.