# ENGINE Step 4, Phase 1: v4 in the kernel's boot -- Plan > **For agentic workers:** steps use checkbox (`- [ ]`) syntax. One QEMU at a time, in the foreground > (`.claude/CLAUDE.md`); every log and CSV is committed. **Goal (#189):** on bare metal, v4 boots *in* the kernel's boot, not before it: the kernel's own order, as v3's -- hardware, the heartbeat, **the Stadium**, then the v4 system on the first node (Hera) with POST, then the devices, then the prompt -- and the Stadium holds Hera from the start, so that Phase 2 can feed it every word Hera calls. `sk_v4_run()`, which today takes the boot before the Stadium is made and never returns (`kernel_main.c:647`), goes. **Parent plan:** `2026-10-20-engine-step4-node-in-the-vms-place.md`, Phase 1 (rows 1, 2, 5, 6 and 9 of `V3-PARITY.md` section 1). Order ruled 2026-11-12 (Captain Bob, #189): Part A (done), Phase 1, Phase 2, then Phase 7. HEAT-OP's Stadium feed was ruled into this phase ("Both": the registers now -- built 2026-11-12 -- and the Stadium feed in Phase 1, measured, kept or reverted on the numbers). ## What a v4 boot does today, and what v3's does | | v3 (`system=v3`) | v4 today | |---|---|---| | Heartbeat | started (`kernel_main_deep`) | started -- the same code, before the choice | | The Stadium | `stadium_boot_init`, `session_boot_init`, `stadium_birth_hera`, `stadium_words_init`, `stadium_blocks_init` -- "Stadium: 83886 cells (5242 KB), 50 VM slots" | **never made**: `sk_v4_run()` is called before it and does not return | | The system | the v3 VM, POST | one node, POST (`v4_boot_run`) | | The checks after POST | "Stadium words: promotions=...", "Stadium conservation: ... CONSERVED", "Stadium quota grant self-test: OK", "Heartbeat: N ticks" | none | | Devices | PCI, the disk | the block chain, after POST (`sk_v4_block_chain`) | | The prompt | `sk_repl()` | `sk_v4_run()`'s own loop | ## Rulings (Captain Bob, 2026-11-13) - **Q1: "A new node key."** The Stadium is keyed by v4 node number now, ahead of the fleet -- not by `vm_uuid_hera()`. A node's key is made from its number (`stadium_node_key(node)`, a `VMUuid` that no v3 VM can have); the node the kernel brings up first, Hera -- node 10, as the hosted mesh numbers her (`test_host_unit.c`: "it is told it is 10") -- is patron zero under her key. v3's path keeps `vm_uuid_hera()` and `stadium_birth_hera()` unchanged (`MACHINE.md` 7 item 3); the v4 path gets `stadium_birth_node(key)`, the same birth for a key it is given. - **Q2: per heartbeat tick**, as recommended. - **Q3: "All of v3's."** A v4 boot runs every boot check v3's does that is not v3's VM itself: the Stadium, the session table, the switch-signal table, kernel-Hermes' channels and queues, Hera's birth, the word and block layers; and after POST the conservation check, the quota grant self-test and the heartbeat's tick line. - **Q4: "In Phase 1."** The registry (`v4/src/manage.c`) comes into the kernel build in this phase: Task 5 is in. Asked how much -- it needs a fabric of nodes, births that make them, and who runs next (`ENGINE.md` 6, open) -- **"Full births now."** - ~~**Who runs next (`ENGINE.md` 6): "Hera by compudynamics now."**~~ **Withdrawn 2026-11-13** -- the question was put wrongly, as a choice of scheduling policy. The design has no scheduler (`JUSTIFICATION.md` 4: "There is no scheduler to write"; `fabric.h`: "There is no choice of whose turn it is"; FABRIC-3's turn-attractor: "fix the gap without a scheduler"): every awake node steps together, and a node with nothing to do waits at a port. Captain Bob, asked "Scheduler? Have we regressed?", then: **"Build it to proper spec."** The withdrawn ruling, as it was written: ~~As v3's turn-attractor, agreed with Captain Bob (`FABRIC-3.md`, the turn-attractor: "the next turn to whichever live identity VM currently has the lowest `execution_heat_q48` ... No priority levels, no time slices, no preemption -- the same density comparison Stadium already uses"): the next instruction word goes to the **coolest awake node** that can run, by its resident heat in the Stadium -- its opcode patrons (Task 3) until Phase 2 adds its words. Switching only between instruction words (`ENGINE.md` 3a). A node asleep at its wires, or blocked, is not a candidate.~~ ## Questions (as they were put) **Q1. Hera's place in the Stadium.** *Recommend:* the v4 node is Hera, patron zero, under `vm_uuid_hera()`: `stadium_birth_hera()` as v3 has it, and its session. The Stadium's own code is the kernel's and unchanged (Q3 of 2026-10-20: "keyed by node number where they are keyed by VM today" -- with one node, Hera's UUID is that key until the fleet, Phase 5 onward). **Q2. The opcode patrons: how a count becomes heat.** The Stadium's heat is a conserved share of 1.0, not a count. *Recommend:* 32 opcode patrons for the node, one per opcode, admitted at boot as the word layer admits words (`stadium_words.c`), behaviour `COOL`; **at each heartbeat tick, not at each instruction**, each opcode's retirements since the last tick (`v4_heat.op[k]`'s delta) are charged as that many of the word layer's dispatches -- the same pull from the node's reservoir, the same cooling per tick -- in one step. Per instruction it would be a kernel call per instruction (the "huge performance hit" the ruling allows to be reverted); per tick it is 32 sums a tick. Measured either way (Task 3). *If not:* charged per instruction, at the hook in `v4/src/exec.c` -- then measured, and reverted if it is the hit. **Q3. Which of v3's boot checks a v4 boot runs.** *Recommend:* those of the Stadium and the heartbeat, which are the kernel's: the Stadium's allocation, Hera's birth, the word and block layers, and after POST the conservation check (`stadium_words_print_boot_diagnostics`), the quota grant self-test and the heartbeat's tick line. Not v3's switch-signal table, kernel-Hermes' channels and queues, or the v3 VM's own Stadium step lines: they are a v3 VM's (Q1 of 2026-10-20: Hermes is v4's wires, not `kernel_hermes.c`). **Q4. The registry (`v4/src/manage.c`, MESH step 9) in this phase or after alpha.5.** The parent plan puts it in Phase 1; the physics does not need it -- one node, Hera, is enough for Phases 2 and 7. *Recommend:* after alpha.5, with the fleet (Phase 5 onward), to keep #189's path short. *If not:* Task 5 below. ## Tasks ### Task 1: The Stadium before the system **Files:** `kernel/src/kernel_main.c`. Test: the amd64 boot (an acceptance check, Task 4). - [ ] **Step 1: Seen to fail first:** the acceptance check of Task 4, on today's build: a v4 boot has no "Stadium: ... cells" line. - [ ] **Step 2:** `stadium_boot_init`, `session_boot_init`, `sk_vm_switch_signal_boot_init`, `sk_hermes_channels_boot_init`, `sk_hermes_queues_boot_init` move above the choice of system -- the kernel's, for both systems, in v3's order (Q3). Then on v3's path `stadium_birth_hera()` as today; on v4's, `stadium_birth_node(stadium_node_key(10))` (Q1, a failing host test first: `kernel/tests/test_stadium_node.c` -- the key is no v3 VM's, the node lands on cell 0, its session is registered and pinned). Then `stadium_words_init` and `stadium_blocks_init`. v3's path is otherwise unchanged (`MACHINE.md` 7 item 3): the same calls, in the same order, before its VM. - [ ] **Step 3:** the three boots and the stick, v4: "Stadium: N cells (... KB), 50 VM slots" before the system starts; POST and `dict_hash` unchanged (the node is not touched). One `system=v3` boot, for v3's path: the same lines it printed before. ### Task 2: `sk_v4_run()` goes **Files:** `kernel/src/v4/sk_v4.c`, `kernel/include/starkernel/v4/sk_v4.h`, `kernel/src/kernel_main.c`. - [ ] **Step 1:** `sk_v4_run()` becomes two: `sk_v4_boot()` -- the node, POST, the blocks, the identity; it returns -- and `sk_v4_prompt()`, the prompt loop, which does not. The kernel calls them in its own order: the Stadium (Task 1), `sk_v4_boot()`, the checks after POST (Q3), then `sk_v4_prompt()`. - [ ] **Step 2:** the checks after POST on v4, under Hera's node key: "Stadium words: ...", "Stadium conservation: ... CONSERVED", "Stadium quota grant self-test: OK", the heartbeat's tick line (Q3). - [ ] **Step 3:** the three boots and the stick: those lines, then `[zuse@Hera] ok> `; POST and `dict_hash` unchanged. ### Task 3: The opcode patrons (HEAT-OP into the Stadium), measured **Files:** `kernel/src/vm/stadium_ops.c` (new), its header, `kernel/src/v4/sk_v4.c` (the tick). Test: `kernel/tests/test_stadium_ops.c` (the host harness, `make -C kernel/tests`), with the Stadium's own sources. - [ ] **Step 1: Failing test:** 32 patrons admitted for a node; N retirements of an opcode between two ticks heat its patron as N of the word layer's dispatches would; the sum of the node's resident heat and its reservoir stays 1.0 (`stadium_conserved`); no retirements, no heat; cooling per tick as words. - [ ] **Step 2:** `stadium_ops.c`, as ruled in Q2; the heartbeat's tick charges the deltas. - [ ] **Step 3:** a line after POST, "Stadium opcodes: ..." (the hottest opcodes), and conservation still CONSERVED with them in. - [ ] **Step 4: Measured:** the amd64 boot's time and POST's instruction count, with and without the feed, five boots each -- recorded in the commit. Kept, or reverted on the numbers (Captain Bob, 2026-11-12). ### Task 4: Acceptance asserts it **Files:** `scripts/qemu_session.py` (the v4 boot's checks), `scripts/nightly.sh` (the stages read them). - [ ] **Step 1:** a v4 acceptance boot must show "Stadium: ... cells", "Stadium conservation: ... CONSERVED" and the heartbeat's line before its prompt; one without them fails (#189 Done when, third item: "a boot without the physics fails"). Seen to fail on today's build (Task 1 Step 1). - [ ] **Step 2:** the protocol, all eight stages; then the push, on Captain Bob's word. ### Task 5: the registry and births, to spec **5a's "Hera as now, in a fabric" is superseded for births** (2026-11-13): with Hera booted by `v4_boot_run`, her messages to a child are answered "no one is there" (`boot.c` speaks only her console's wire) and nothing runs a child while the boot drives her. To spec -- `MESH.md` 9, `MACHINE.md` 3, and as `v4/tests/test_host_unit.c` already does on the host -- **Hera is born empty in the kernel's fabric, and every node steps together** (`v4_fabric_step`). No scheduler. - [x] **5a. The registry** (2026-11-13; `f10d2bc8`): Hera at place 0, entered as node 10; `centre.4th` and `hera.4th`; `NODE-ME`. Kept; its boot is replaced by 5b. - [x] **5b. The mesh boot** -- `v4/system/mesh.c` (new), the kernel's boot of the fabric, a host test first (`v4/tests/test_host_meshboot.c`, 64-bit cells, as `test_host_unit.c`): 1. the nucleus: the machine's ROM assembles the system on a node of its own (`boot.c`'s `load_system`, shared); written as a capsule of F18 cells (`v4_capsule_write`) -- "a node that is born is given assembled code, never the source" (Captain Bob, 2026-10-15); 2. Hera born empty at place 0 of the fabric: the kernel on her port 0 (it gives her the nucleus a cell at a time, and takes her requests -- blocks, the kernel's words, the registry), the console on her port 1 (whole messages); stepped until she sleeps at her wires; 3. told she is 10 and where the console is; entered in the registry; the kernel's words; `forth79.4th` a line at a time; sealed; POST (`v4_post_run`, its lines as messages); the kernel's capsules (`centre.4th`, `hera.4th`); sealed; 4. the same parity lines as `v4_boot_run` prints, so acceptance reads a mesh boot as it read the other; 5. a line from the console is a message to node 10; what any node prints comes back as messages; how it ended is said; `KEY` reads her console registers, fed by the host; 6. births: `NODE-BORN` makes a node in room the owner gives, carrying the mesh ROM, wired to the kernel on its port 0 for its blocks; `NODE-KILL` gives the room back. `CAPSULE-OPEN` of `v4:nucleus-64.f18` reads the nucleus a cell at a time. The test: the parity lines; POST passes; `NODE-ME .` 0; `KEY`; `11 2 2 BIRTH` -- node 11 takes in the nucleus and FORTH-79 and answers a line; `11 KILL`. - [x] **5c. The kernel boots by it** (`sk_v4.c`): the prompt's lines go to node 10 as messages; the identity gate, the block chain after POST, the heartbeat's service; a born node's room from the kernel's heap, its Stadium quota granted from Hera's under its node key (`stadium_node_key`), its opcode patrons charged with Hera's; its quota given back when it is killed. The hosted product keeps `v4_boot_run`; `boot.h`'s "differ only in where the text goes" is corrected. - [x] **5d. Acceptance:** a boot births a node from Hera, it answers a line, Hera kills it, the Stadium CONSERVED after; then the protocol. **Built (2026-11-13).** 5b: `v4/system/mesh.c`, `v4/include/v4/mesh.h`; `boot.c` shares `v4_boot_assemble` (which `v4_boot_run` now calls), `v4_boot_capsule` and its number printing; the image carries `(ME)`'s address. `v4/tests/test_mesh_boot.c` (in `make -C v4 test`): failed first (no `mesh.c`), then 16 checks -- POST 539/539, `NODE-ME` 0, `11 2 2 BIRTH`, node 11 answers directly and through Hera, `11 KILL`. 5c: `sk_v4.c` boots by it -- 16 places, a born node's room from the kernel's heap, its Stadium quota under its node key granted from Hera's on its first charge and given back when it is killed (`stadium_return_quota`, `stadium_ops_forget`: failed first, then `test_stadium_ops` 20 checks); every node's opcodes charged. A line that waits for an answer is broken by the next line, as a message (`MESH.md` 7b.6). 5d: `qemu_session.py births()`. The amd64 boot: 160 s (about 90 s before -- POST and the lines now go as messages); `dict_hash` changes (Hera is told she is 10). ## What this phase does not do Phase 2 (the word accounts at `call`: the kernel's record per word, `execution_heat`, `stadium_word_dispatch`, the ACL's countdown) and Phase 7 (decay, the rolling window, pipelining, inference, L8 on those records). After Phase 1 the Stadium holds Hera and her 32 opcode patrons, and nothing yet of her words. ## Review focus 1. **v3's path:** a `system=v3` boot prints what it printed before, in the same order. 2. **The 32-bit build and the stick:** the Stadium's allocation fits the stick loaded high as it does at 2 GiB. 3. **Conservation with the opcodes in:** K = 1.0 after POST, before the prompt. 4. **The tick's cost:** with the feed, the heartbeat still keeps its rate (its tick line's count against the boot's time).