docs(v4): one adaptive heartbeat -- every node ticks in lockstep on the fabric's beat; the design, its four points ruled

Captain Bob, 2026-11-17: "ONE ADAPTIVE HEARTBEAT. EVERY VM USES THAT ONE CLOCK ... THEY ADVANCE ONE TICK!"
Ruled: the beat is the fabric's steps; HEARTBEAT_CHECK_FREQUENCY steps a beat; the Stadium charged on it;
Loop #7 adapts the beat only; the heartbeat first, then mechanism A. Nothing built yet.

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-17 20:01:21 +00:00
parent e5cfe1d7d7
commit 4a5c9bfd42
@@ -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.