feat(v4): Phase 7 Task 2b -- pipelining and the hot-words cache, built, off as v3 (#189)

Rulings, Captain Bob 2026-11-13: "Build a hot-words cache"; then, v3 being found to have both off
(ENABLE_PIPELINING, ENABLE_HOTWORDS_CACHE: n in Kconfig.physics and kernel/Makefile), "Built, off as v3".

- The kernel, at every call (mesh.c): v3's hit check, the transition, the likeliest next word (kept as each
  count rises; v3 scans 1024 a call -- the same word but in a tie v3's Q48.16 rounding makes), speculation
  at v3's thresholds into the node's cache; a word past heat 50 promoted at its call (v3 promotes at a
  lookup; v4's heat is the kernel's). Counters from the owner's heap, given back when a word goes.
- The node (dict.f18): (LOOKUP) tries (HOT)'s xts first, in F18, calling only C@; the kernel keeps it true
  (entries that go, or whose name is defined again, taken out). Empty unless the build has the cache.
- Tests: test_mesh_boot.c as built (57 checks) and with both on (mesh-boot-on, 65). v4 test: all pass.
- Reported, v3's own: when full, its promote takes the next slot without looking for the word there (a few
  hot words churn all 32 slots); its prefetch misses are never counted. Both reproduced.
- amd64 boots, RESULT: PASS, but 174 s and 181 s against 2a's 146 s, while on the host the mesh boot is no
  slower: being measured. Not pushed (held to the Phase 7 boundary).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
This commit is contained in:
Claude
2026-11-13 21:52:01 +00:00
parent b880a6eaed
commit 3a70e824a2
19 changed files with 473 additions and 145 deletions
@@ -98,6 +98,24 @@ Phase 4).
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.
- **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)
### 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