diff --git a/docs/v4.0.0/plans/2026-11-17-one-adaptive-heartbeat.md b/docs/v4.0.0/plans/2026-11-17-one-adaptive-heartbeat.md new file mode 100644 index 00000000..ddfb689e --- /dev/null +++ b/docs/v4.0.0/plans/2026-11-17-one-adaptive-heartbeat.md @@ -0,0 +1,78 @@ +# One adaptive heartbeat -- every node ticks in lockstep -- design, for ruling + +Written 2026-11-17. Captain Bob: **"ONE ADAPTIVE HEARTBEAT. EVERY VM USES THAT ONE CLOCK AND +REGARDLESS OF WHAT THEY'RE ALL DOING, ACTIVE OR NOT, THEY ADVANCE ONE TICK! PERIOD. ... Lots of +little soldiers marching lockstep."** His rulings the same day: +- replace the per-node ticks with the one heartbeat, every node ticking together; +- the beat is **the fabric's own steps**: deterministic, the same on every ISA and every run + (FABRIC-0 GAP-A1; v3's lessons of 07-07 and 07-24). + +**Nothing here is built.** The open points are put to Captain Bob one at a time. + +## 1. What is there now (code, read 2026-11-17) + +- **Many clocks.** Each node has its own `tick` (`ms->physics[place].tick`). It advances in that node's + `heartbeat_cycle` (`v4/system/mesh.c:657`), which runs from `on_call` (`:720`) every + `HEARTBEAT_CHECK_FREQUENCY` (256) of the node's own counted calls and tokens. This was Phase 7 + Task 3, from the ruling "By execution, as v3". +- **The result:** an idle node never ticks, a busy one ticks often, and no two nodes share a tick. +- **Loop #7** runs per node, in `inference_tick` (`:644`). Hera's re-arms the kernel's timer + (`sk_v4_heartrate` -> `heartbeat_set_adaptive_period_ns`). +- **The Stadium charge** runs on a second clock: the kernel's timer ticks + (`sk_v4_charge_opcodes`, `heartbeat_ticks()`, `kernel/src/v4/sk_v4.c:171`). + +## 2. The design + +**A. One clock, the fabric's.** +- The mesh counts its fabric steps. +- Every `steps_per_beat` steps is one beat. The mesh's one `tick` advances by one, and **every node + present runs its heartbeat cycle on that tick, in place order, active, idle or blocked alike**: the + soldiers march together. Every node's `tick` is that one tick. +- The fabric is stepped from `v4_mesh_step`, `v4_mesh_tell` and the boot's loop (`mesh.c:1145, 1166, + 1283`). All three go through one counting step, so no step goes uncounted. + +**B. What leaves `on_call`.** The count of calls and tokens that triggered a node's own cycle +(`check_counter`, `cycle_every`) goes. A word's per-call loops stay at its call, as ruled ("Every +call, as v3"): decay by the ticks since, heat, temperature, the window and pipelining. They now read +the one tick. + +**C. One Loop #7.** The heartrate adapts `steps_per_beat`: +- 25% slower when stable; +- 20% faster when not; +- within 1/4 to 4 times its starting value, as v3's rule. + +**D. Determinism.** The beat is a function of the fabric's steps alone, so it is the same on every ISA +and every run. POST and `dict_hash` are judged as they are today. + +## 3. How it is verified (named now) + +1. **Test first** (`test_mesh_boot.c`): + - nodes born and idle advance their tick on each beat exactly as Hera does; + - two nodes always show the same tick; + - a node that runs nothing still has its heartbeat cycle run, its words decaying; + - Loop #7 changes `steps_per_beat` within its bounds. + + Each check is seen to fail on today's code. +2. **Every existing test**, at both widths and under the sanitizers. Where today's expected heat or + tick values change because the clock changed, each change is listed and put to Captain Bob, one at + a time, before anything is rewritten. +3. **The same on all three ISAs:** POST 990 of 990, and one `dict_hash`. +4. **The protocol** on a clean tree. + +## 4. Open points, one at a time + +1. ~~The starting `steps_per_beat`.~~ **Ruled 2026-11-17: `HEARTBEAT_CHECK_FREQUENCY` steps**, the + existing Kconfig symbol (default 256), read as fabric steps. Ticks come more often than today's, so + every test value that changes is brought to Captain Bob one at a time. +2. ~~The Stadium charge?~~ **Ruled 2026-11-17: on the one beat.** Every beat, every node's opcodes and + words are charged with the one tick: one clock for everything. The charge now runs during POST and + lines as well. +3. ~~Loop #7 and the kernel's timer?~~ **Ruled 2026-11-17: Loop #7 adapts the beat only.** The kernel's + 100 Hz timer is left at its fixed rate. It is the kernel's housekeeping (the idle wait, the + keyboard, USB, the cursor, the block flush), not a VM clock. `sk_v4_heartrate` is no longer called + from Loop #7. +4. ~~The order against mechanism A?~~ **Ruled 2026-11-17: the heartbeat first, then A.** The heartbeat is + built and accepted with its own tests and its own protocol. Then A follows, measured against it by + five alternating runs. + +All four open points are settled.