diff --git a/docs/v4.0.0/POST-PARITY.md b/docs/v4.0.0/POST-PARITY.md new file mode 100644 index 00000000..2c3d6bf5 --- /dev/null +++ b/docs/v4.0.0/POST-PARITY.md @@ -0,0 +1,73 @@ +# v3's whole POST on v4 -- the inventory + +Started 2026-11-13, Task 0 of `plans/2026-11-13-engine-step4-phase7-the-loops-and-parity.md` (#189). +Captain Bob, 2026-11-13: Phase 7 is accepted on **"v3's whole POST"**. This counts every case of v3's +POST against v4 as it is on e8e7ec8b (377 live words), with `v4/tools/mkpost.py`'s own reader of +`v3/src/test_runner/modules/`. It proposes; it decides nothing. + +## 1. The 17 modules `mkpost.py` reads today + +v4's POST keeps only their cases for the FORTH-79 Required Word Set (550 read, 539 after what +`mkpost.py` leaves out: the keyboard, words that forget or damage the system, lines too long). + +| Module | Cases | Required (on v4's POST) | Other words v4 has | Words v4 lacks | +|---|---|---|---|---| +| stack_words_test.c | 55 | 50 | 5 | 0 | +| return_stack_words_test.c | 11 | 11 | 0 | 0 | +| memory_words_test.c | 53 | 38 | 15 | 0 | +| arithmetic_words_test.c | 104 | 92 | 12 | 0 | +| logical_words_test.c | 103 | 64 | 39 | 0 | +| mixed_arithmetic_words_test.c | 40 | 18 | 22 | 0 | +| double_words_test.c | 125 | 21 | 104 | 0 | +| format_words_test.c | 31 | 25 | 6 | 0 | +| string_words_test.c | 49 | 15 | 34 | 0 | +| io_words_test.c | 73 | 61 | 3 | 9 (`BASE_OUTPUT`, `FORMAT_COMBO`: groups, not words) | +| block_words_test.c | 51 | 30 | 21 | 0 | +| dictionary_words_test.c | 49 | 22 | 15 | 12 (`SP!`, `SP@`; `COMPILATION`, `STACK_MGMT`: groups) | +| dictionary_manipulation_words_test.c | 29 | 16 | 13 | 0 | +| vocabulary_words_test.c | 22 | 19 | 3 | 0 | +| system_words_test.c | 7 | 4 | 3 | 0 | +| defining_words_tests.c | 32 | 22 | 10 | 0 | +| control_words_test.c | 54 | 42 | 12 | 0 | +| **Total** | **888** | **550** | **317** | **21** | + +The 317 test words v4 already has; they are left out only because `mkpost.py` keeps the Required set. + +## 2. The nine modules `mkpost.py` does not read + +| Module | Cases | Words v4 lacks | Kind | +|---|---|---|---| +| q48_words_test.c | 28 | none | FORTH lines; every word is on v4 | +| starforth_words_test.c | 29 | `ENTROPY!` `ENTROPY@` `RESET-ENTROPY` `TOP-WORDS` `WORD-ENTROPY` `(-` | FORTH lines; the entropy and top-words words read the physics | +| physics_freeze_words_test.c | 7 | `FREEZE-WORD` `UNFREEZE-WORD` `FROZEN?` `HEAT@` `HEAT!` `DECAY-RATE@` | FORTH lines; the loops' words | +| inference_words_test.c | 9 | `INFER-RUN` `INFER-DECAY-SLOPE` `INFER-DECAY@` `INFER-EARLY-EXIT@` `INFER-FIT@` `INFER-VARIANCE@` `INFER-WINDOW-WIDTH` `INFER-WINDOW@` `Q.VARIANCE` | FORTH lines; the inference engine's words | +| stress_tests.c | 45 | none (14 group names) | FORTH lines | +| integration_tests.c | 8 | none (3 group names) | FORTH lines | +| mama_forth_words_test.c | 20 | `CAPSULE-BIRTH` `CAPSULE-RUN` `CAPSULE-TEST` `CAPSULE-COUNT` `CAPSULE@` `CAPSULE-FLAGS@` `CAPSULE-HASH@` `CAPSULE-LEN@` `MAMA-VM-ID` `VM-COUNT` | FORTH lines about v3's VMs and capsule directory | +| acl_words_test.c | 11 | -- | **C**, against v3's VM's fields (`vm->...`), not FORTH lines | +| break_me_tests.c | 1 | -- | **C**, one routine against v3's VM | + +## 3. For ruling + +1. **Mama** (20 cases): the words are v3's: a VM ID, a VM count, v3's capsule directory. v4 has nodes, + births (`BIRTH`, `NODE-ME`) and its own capsules. Written as v4 words with v3's names and meaning, + mapped to v4's equivalents, or out of parity? +2. **The C modules** (ACL, break_me): they read v3's VM's fields directly. Rewritten as tests of the + same behaviour against v4 (FORTH lines where they can be, host tests in C where they cannot), or + out? +3. **The group names** (`STACK_BOUNDARY`, `COMPILATION`, ...): v3 files cases under a group, not a word. + They are cases like any other, run as they are; nothing to rule unless a case fails. + +**Ruled (Captain Bob, 2026-11-13):** +1. **Mama:** v4 words with v3's names and meaning, mapped to v4's equivalents -- "but do not compose + words in C99, use F18 and StarForth". The words are written in the system's F18 or in StarForth; + where only the kernel can answer (the registry, the capsules it holds), the word asks it by a + request on port 0, as `KERNEL-WORD` words do. The 20 cases run as they are. +2. **The C modules:** rewritten for v4, the same behaviour shown case by case -- as FORTH lines in POST + where they can be, as host tests in C where they need internals. + +## 4. What parity needs, in count + +About 1,050 cases: 888 in section 1, 146 FORTH-line cases in section 2's modules, and the C modules' 12 tests -- 1,046. v4 has 539 today. +The loops' own words (physics freeze, inference, entropy, top words) are 22 cases; the ACL and Mama +modules wait on section 3. diff --git a/docs/v4.0.0/plans/2026-11-13-engine-step4-phase7-the-loops-and-parity.md b/docs/v4.0.0/plans/2026-11-13-engine-step4-phase7-the-loops-and-parity.md new file mode 100644 index 00000000..8e3d01af --- /dev/null +++ b/docs/v4.0.0/plans/2026-11-13-engine-step4-phase7-the-loops-and-parity.md @@ -0,0 +1,97 @@ +# 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`. + +## 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 +### Task 2: the per-call loops at `call` (decay on touch, window, transitions) -- measured +### Task 3: the per-tick loops (tuner, slope, background decay, L8, inference, 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.