ENGINE step 4 Phase 2 (plan docs/v4.0.0/plans/2026-11-13-engine-step4-phase2-word-accounts.md). Rulings, Captain Bob 2026-11-13: "ID field in the header"; "Per heartbeat tick"; the ACL "All of it in Phase 4". - The word ID, at xt-4 before the flags (ENGINE.md 3b). The system's words are numbered as they are assembled, by a new directive, #id, (and #ids, the count), in the C assembler (text.c) and in the machine ROM's (capsules/v4/rom), which counts in the system's own (NEXT-ID). (HEADER) numbers later words; FORGET gives back the IDs it frees, always the newest; COLD resets to (BOOT-ID); (SEAL) records it. All 313 system headers carry the cell. - The kernel's records (v4/mesh.h): (TELL-DEFINED) and (TELL-FORGOTTEN), requests -19/-20 on port 0, which the kernel puts in (WORD-DEFINED)/(WORD-FORGOTTEN) when it seals a node, and reads the system's own words once. A bit per address marks a word's xt (calls into the ROM or headerless code are not words); at call, the bit test and a count. v4_mesh_charge hands the owner the calls since. - The Stadium: stadium_words_charge -- N calls as N of stadium_word_dispatch's dispatches, shared by calls when the reservoir is short; sk_v4.c charges every node's words at the tick beside its opcodes, and stadium_word_forget before an ID is used again. - Tests first: test_text.c, test_host_dict.c, test_host_quit.c (numbering, FORGET, COLD), test_mesh_boot.c (44 checks), kernel/tests/test_stadium_words.c; qemu_session.py: Hera's words admitted after POST. - amd64: Stadium words: promotions=141 after POST, CONSERVED; POST 539/539; word_count=377; dict_hash 0xa854ba15b437d288 (the new cell); the boot 142 s against Phase 1's 153 s. - v4 test, test-32: all pass; v4-checks: 80 programs under the sanitizers, 0 failures; the hosted builds alike. docs/reference/v4-dictionary.tsv: the two new words; FABRIC-3 XLVIII.24. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
8.2 KiB
ENGINE Step 4, Phase 2: word accounts at call -- Plan
For agentic workers: steps use checkbox (
- [ ]) syntax. One QEMU at a time, in the foreground, every boot undertimeout 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): the kernel keeps a record for each word on each node, joined to the word by the word
ID in its header (ENGINE.md 3b, ruled 2026-10-05: "A is good"). Each call to a word counts on its
record (execution_heat), and the Stadium's word layer is fed from the records, so that the Stadium
holds a node's words as it holds v3's (V3-PARITY.md §1 row 3, in part).
Parent plan: 2026-10-20-engine-step4-node-in-the-vms-place.md, Phase 2; after Phase 1
(2026-11-13-engine-step4-phase1-v4-in-the-kernels-boot.md, accepted 2026-11-13, protocol PASS on
046ce0be). Q4 (RULED 2026-10-20, as recommended): the kernel keeps, per node and word ID, a record with
DictEntry's account fields; stadium_word_dispatch takes a VM ID and a word ID.
Rulings (Captain Bob, 2026-11-13)
- The word ID is a field in the header -- not a kernel table keyed by address, and not every call target. (Matches 3b: "its word ID in its header".)
- Charged per heartbeat tick, as the opcodes are (Phase 1, Q2): a call only counts; once a tick the words called since are charged to the Stadium.
- The ACL is all Phase 4: no ACL fields or countdown in Phase 2.
The design
An entry gains one cell, its word ID, before its flags. Today (dict.f18):
name | xt-3 flags | xt-2 the name's address | xt-1 the link | xt the code
becomes
name | xt-4 word ID | xt-3 flags | xt-2 the name's address | xt-1 the link | xt the code
Every offset from the xt stays as it is; only the name moves one cell further from the code (NAME>,
TRAVERSE, (NEED): 12 bytes become 16).
Who numbers the words.
- The system's words are numbered by the assembler, in the order they are assembled, from 0, with a
new directive
#id,: it lays down the next number and counts on. The 313 assembled headers (... #, 0 #, HDR-NFA #, HDR-LINK ...) gain#id,before their flags. The count is stored in a new variable,(NEXT-ID). - A word defined later is numbered by
(HEADER), from(NEXT-ID). - FORGET takes away the newest entries, so the IDs it frees are the highest: it sets
(NEXT-ID)back to the first gone entry's ID, and they are used again, as v3 recycles its word IDs. COLD sets it back to the system's count. - The same numbering on every node and at either cell width; no kernel needed (the hosted product
numbers alike).
dict_hashchanges once, for the new cell;word_countdoes not.
How the kernel knows a called address is a word. Many calls are to ROM routines and headerless
code (189 of the system's definitions have no header), whose cell at xt-4 is not an ID. So the kernel
keeps, per node, one bit for each address of its memory: set for a word's xt. Its records are kept by
word ID. Both come from what the node tells it (3b, already in the system and unwired):
(WORD-DEFINED) (dict.f18), at (HEADER), gives the xt; (WORD-FORGOTTEN), at FORGET and COLD,
gives the word address from which entries went. The kernel attaches them with requests on port 0
(kernel_take). The system's own words, already in a node when it is sealed, are read once by
walking the dictionary from LATEST.
At call (Part A's hook, v4_exec_state.on_call): if the target's bit is set, the record of the
ID at target-4 counts one: execution_heat, and its calls since the last charge. A bit test and an
increment: nothing else at call.
At the heartbeat tick (where the opcodes are charged, sk_v4_charge_opcodes): for each node, the
words called since are charged to the Stadium under the node's key -- new
stadium_words_charge(vm, word_id, calls, tick), which is stadium_word_dispatch for that many calls
at once: cooling by the ticks since, a quantum a call, the reservoir's third left, and when the calls
want more than there is, a share in proportion to the calls (as stadium_ops_charge, #189).
When words go: FORGET and COLD drop the records and bits of the entries gone, and
stadium_word_forget each (v3's coherence on recycling). A kill already evicts every resident of the
node's quota (stadium_return_quota); the records go with the node.
Tasks
Task 1: #id, in the assembler
- Test first (
v4/tests/test_text.c):#id,lays down 0, 1, 2 in order; a symbol gives the count. v4/src/text.c: the directive and the counter (reset per text).
Task 2: the header's word-ID cell
- Tests first: the host dictionary tests (
test_host_dict.c): a word's ID at xt-4; a word defined at the prompt gets the next ID; FORGET gives its IDs back; COLD resets;NAME>andTRAVERSEacross the new cell. capsules/v4/sys/*.f18:#id,in the 313 headers;dict.f18:(NEED),(HEADER),NAME>,TRAVERSE,(NEXT-ID);system.f18: FORGET and COLD;map-32.f18/map-64.f18andmkmap.c:(NEXT-ID)'s address.make -C v4 test test-32; the POST expectations and the hosted products updated for the newdict_hash(word_count 375 unchanged).
Task 3: the kernel's records
- Test first (
v4/tests/test_mesh_boot.c, and a kernel host test): after the boot every system word has a record and a bit;: SQ DUP * ;makes one more;3 SQcounts SQ once; FORGET SQ drops it; a call to a headerless routine counts nothing. v4/system/mesh.c: the requests behind(WORD-DEFINED)/(WORD-FORGOTTEN), the walk at seal, the bits and records per place, the hook atcall. Records sized by(NEXT-ID), in the owner's memory.
Task 4: the Stadium charge per tick
- Test first (
kernel/tests/test_stadium_words.c):stadium_words_chargefor N calls equals N dispatches when there is enough; shares by calls when there is not; conservation. kernel/src/vm/stadium_words.c:stadium_words_charge;kernel/src/v4/sk_v4.c: charge every node's words at the tick, beside its opcodes;stadium_word_forgeton FORGET.scripts/qemu_session.py: after POST, "Stadium words: N resident" with N > 0, and conservation CONSERVED; a word defined at the prompt and called becomes resident.
Task 5: acceptance
- The boot's time before and after (Review focus 3), in the commit message.
- The full protocol;
docs/v4.0.0/ENGINE.md, this plan,FABRIC-3.mdXLVIII.24.
As built (2026-11-13)
- Tasks 1-4 done, test first:
test_text.c(#id,,#ids, the header's ID),test_host_dict.candtest_host_quit.c(the layout, numbering, FORGET giving IDs back, COLD),test_mesh_boot.c(44 checks: records, calls at the prompt, in definitions and throughEXECUTE, the charge, FORGET, every word on Hera kept, a born node's own),kernel/tests/test_stadium_words.c(the charge equal to that many dispatches; cooling; the floor; conservation). - The ROM's assembler counts in the system's
(NEXT-ID), zero when the machine starts, so no ROM variable was added. - The telling words are
(TELL-DEFINED)and(TELL-FORGOTTEN), requests −19 and −20; the kernel puts them in the hook variables when it seals a node, so the hosted product, which keeps no records, never tells. - amd64:
Stadium words: promotions=141after POST, CONSERVED;word_count=377; the boot 142 s (Phase 1: 153 s).
Review focus
- A headerless call is not a word: only an xt the node told of has its bit.
- Recycling: an ID freed by FORGET and used again starts from nothing in the Stadium
(
stadium_word_forgetbefore the reuse). - Cost at
call: a bit test and an increment; the boot's time under TCG recorded before and after. - The 32-bit build: the same IDs and the same counts at 32-bit cells.
- The Stadium's bound: its word layer holds word IDs below
DICTIONARY_SIZE(1024); the system has 375 words. An ID above it is counted on its record but not admitted; reported if reached.
What this phase does not do
The ACL (Phase 4, ruled). Decay, the rolling window, pipelining, inference, L8 on the records (Phase 7). The transition metrics (Phase 7, with the loops that read them).