feat(kernel): v4 boots in the kernel's boot -- the Stadium, its checks, the opcode patrons

#189, ENGINE step 4, Phase 1 (plan 2026-11-13-engine-step4-phase1), Tasks 1-4. Captain Bob, 2026-11-13: Q1 "A new node key", Q2 "Per heartbeat tick", Q3 "All of v3's", Q4 "In Phase 1" / "Full births now", who runs next "Hera by compudynamics now" (Task 5, to come). - stadium.c/.h: stadium_node_key(node) ("NODE" | number), stadium_boot_init_for(first), stadium_birth_node(key, name); stadium_boot_init() and stadium_birth_hera() are them for Hera's key, so v3's path is as it was (only an impossible panic's words changed). - kernel_main.c: the system is chosen and said first, then the Stadium, sessions, switch-signal and kernel-Hermes tables for both systems in v3's order; v4: Hera, node 10, patron zero under her node key, the word, block and opcode layers. The quota self-test and the heartbeat's line are functions now, called by both systems. - sk_v4.c/.h: sk_v4_run() goes -- sk_v4_boot() returns, the kernel's checks after POST (opcodes, words, conservation, quota, heartbeat), then sk_v4_prompt(). sk_v4_charge_opcodes() at the heartbeat's service points (the key wait, after each line) and once after POST. - stadium_ops.c/.h: a node's 32 opcodes as Stadium patrons (HEAT-OP's feed, "Both"): retirements charged as the word layer's dispatches, a quantum each, the reservoir's floor kept, shared by retirements when short; cooling per tick as words. ~0.5 us a charge on the host: kept. - qemu_session.py: a v4 acceptance boot fails without "Stadium: N cells", "Stadium conservation: CONSERVED" and the heartbeat's ticks (#189). Tests first (logs/20261113-122142): the physics check failed on the v4 boot; test_stadium_node, test_stadium_ops (and its share case, after a real boot showed ";" taking all the heat) failed before. Now: kernel host tests all pass; amd64 v4 boot passes, POST 539/539, dict_hash unchanged, "Stadium opcodes: 30 resident, hottest opcode 8", CONSERVED; a system=v3 boot prints its Stadium lines as on 2026-11-06. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-13 12:50:02 +00:00
parent 3f4988e19e
commit b1cac339c1
35 changed files with 959 additions and 85 deletions
@@ -10,13 +10,27 @@

 #include "uefi.h"   /* BootDisk */

-/* Start one StarForth v4 host node from the capsule image linked into the
- * kernel, with its console on the kernel's console, and run it.  Does not
- * return. */
-/* `chain` sets the kernel's block chain up.  It is called when the node has
- * booted and passed POST, before the prompt: as on the v3 path, POST runs
- * against block RAM of its own and the chain comes after it.  `boot_disk` is
- * the loader's: which disk it booted from (sk_v4_identity_boot()). */
-void sk_v4_run(void (*chain)(void), const BootDisk *boot_disk);
+/* Hera's node number: the first node the kernel brings up, as the hosted mesh numbers her
+ * (v4/tests/test_host_unit.c: "it is told it is 10"). The Stadium is keyed by it (#189). */
+#define SK_V4_HERA_NODE 10u
+
+/* Bring one StarForth v4 host node up from the capsule image linked into the
+ * kernel, with its console on the kernel's console: the node, POST, the
+ * blocks, the identity.  It returns; a node that does not start stops the
+ * machine.  `chain` sets the kernel's block chain up: it is called when the
+ * node has booted and passed POST, before the prompt -- as on the v3 path,
+ * POST runs against block RAM of its own and the chain comes after it.
+ * `boot_disk` is the loader's: which disk it booted from
+ * (sk_v4_identity_boot()). */
+void sk_v4_boot(void (*chain)(void), const BootDisk *boot_disk);
+
+/* The prompt: read a line, hand it to the node, say how it ended.  Does not
+ * return.  The kernel calls it after sk_v4_boot() and its own checks (#189,
+ * ENGINE.md step 4, Phase 1: sk_v4_run() went). */
+void sk_v4_prompt(void);
+
+/* Charge the node's opcode counts to its opcode patrons in the Stadium (#189; stadium_ops.h). The
+ * prompt does it as it waits and after each line; the kernel once after sk_v4_boot(). */
+void sk_v4_charge_opcodes(void);

 #endif /* STARKERNEL_V4_SK_V4_H */
@@ -1,7 +1,7 @@
 /* SPDX-License-Identifier: LicenseRef-Starship-1.0
 * Copyright (c) 2023-2026 Robert A. James
 */
-/* sk_v4_stop.h -- the v4 kernel's fatal stop (#177): what sk_v4_run does when the system cannot
+/* sk_v4_stop.h -- the v4 kernel's fatal stop (#177): what sk_v4_boot and sk_v4_prompt do when the system cannot
 * go on ("not started", "did not let go of POST's blocks", "stopped on a fault"). Never returns.
 */
 #ifndef STARKERNEL_V4_SK_V4_STOP_H
@@ -180,6 +180,21 @@ typedef char stadium_capacity_tick_configured_check[(STADIUM_CAPACITY_TICK > 0)
 */
 int stadium_boot_init(void);

+/*
+ * The Stadium keyed by a v4 node's number (#189; Captain Bob, 2026-11-13: "A new node key").
+ * stadium_node_key(node) -- a node's key: "NODE" in the high word, the node's number in the low; never
+ *   Hera's all-zero key or none's all-ones, and the same each time.
+ * stadium_boot_init_for(first) -- stadium_boot_init(), with `first`'s key in the first quota where
+ *   stadium_boot_init() puts Hera's (it is stadium_boot_init_for(vm_uuid_hera())).
+ * stadium_birth_node(key, name) -- stadium_birth_hera() for any key: the node is patron zero, on cell
+ *   0, its session registered under `name` and pinned. 0, or -1 as stadium_birth_hera().
+ * v3's path keeps vm_uuid_hera() and stadium_birth_hera() (docs/v4.0.0/MACHINE.md 7, item 3).
+ */
+#define STADIUM_NODE_KEY_HI 0x4E4F444500000000ULL     /* "NODE" */
+VMUuid stadium_node_key(uint32_t node);
+int    stadium_boot_init_for(VMUuid first);
+int    stadium_birth_node(VMUuid key, const char *name);
+
 /* stadium_is_initialized - Whether stadium_boot_init() has succeeded. */
 int stadium_is_initialized(void);

@@ -0,0 +1,48 @@
+/* SPDX-License-Identifier: LicenseRef-Starship-1.0
+ * Copyright (c) 2023-2026 Robert A. James
+ */
+/* stadium_ops.h -- a v4 node's opcodes as Stadium patrons (#189; plan
+ * 2026-11-13-engine-step4-phase1, Task 3).
+ *
+ * Captain Bob, 2026-11-12: "Add HEAT-OP. If it's a huge performance hit, we'll revert it" -- "Both":
+ * the registers (v4/include/v4/node.h) and the Stadium feed; 2026-11-13: "Per heartbeat tick".
+ * docs/v4.0.0/V3-PARITY.md 1c's reading -- "a VM's word patrons become its 32 opcode patrons" -- held
+ * since 1h left the opcodes unwired "for now"; this wires them, beside the word patrons, not instead.
+ *
+ * A node's 32 opcodes are patrons of its quota, behaviour COOL, each made resident on its first
+ * retirement as a word is on its first dispatch (stadium_words.c). At a charge, an opcode's
+ * retirements since the last charge are charged as that many of the word layer's dispatches -- the
+ * same quantum (STADIUM_WORD_HEAT_QUANTUM), the same floor left in the reservoir (a third); when
+ * they want more than there is, what there is is shared in proportion to the retirements, not taken
+ * by whichever opcode is charged first -- and a resident one first cools by the ticks since, as a
+ * word does
+ * (STADIUM_WORD_COOL_RATE_Q48). The kernel charges at its heartbeat's service points (sk_v4.c):
+ * where the node's host waits, and after each line. Conservation is the Stadium's: what is pulled is
+ * the node's own share.
+ */
+#ifndef STARKERNEL_VM_STADIUM_OPS_H
+#define STARKERNEL_VM_STADIUM_OPS_H
+
+#ifdef __STARKERNEL__
+
+#include <stdint.h>
+#include "starkernel/vm_uuid.h"
+
+#define STADIUM_OPS_COUNT 32u                          /* the F18 opcodes, 0 .. 31 */
+#define STADIUM_OPS_IDENTITY 0x4F50000000000000ULL     /* "OP" in a patron's identity, | the opcode */
+
+/* The per-quota tables; after stadium_boot_init_for(). Not re-entrant. */
+void stadium_ops_init(void);
+
+/* Charge the node `vm_id`'s opcodes: `counts` are its 32 running retirement counts (v4_heat.op),
+ * `tick` the heartbeat's count now. Nothing for a key with no quota. */
+void stadium_ops_charge(VMUuid vm_id, const uint64_t counts[STADIUM_OPS_COUNT], uint64_t tick);
+
+/* An opcode patron's heat now (Q48.16), or 0: not resident, or no quota. */
+uint64_t stadium_ops_heat(VMUuid vm_id, unsigned op);
+
+/* "Stadium opcodes: N resident, hottest opcode K" -- one line, at most 63 characters. */
+void stadium_ops_print_boot_diagnostics(VMUuid vm_id);
+
+#endif /* __STARKERNEL__ */
+#endif