feat(v4, kernel): ONE adaptive heartbeat -- it paces itself on the Stadium's resident heat; every VM ticks on it, in lockstep

Captain Bob, 2026-11-17: "The adaptive heartbeat is its own thing ... It has its own independent RWOT and slope
provider. Only one output from the entire stadium is used as a load measurement for heart rate pacing. ... ONE
AS IN THE NUMBER 1 heartbeat (the adaptive one) runs the entire system." Ruled one at a time: the kernel's
heartbeat; resident heat its one input; held in POST; the Stadium charged as before today
(docs/v4.0.0/plans/2026-11-17-one-adaptive-heartbeat.md, its first version kept as superseded).

- kernel/src/heartbeat.c, timer.h: heartbeat_pace_from(load) -- its own window of samples, its own slope
  provider (v4's inference arithmetic) every HEARTBEAT_PACE_EVERY samples, Loop #7 setting its own period
  (not stable 20% faster, stable 25% slower, 1/4..4x the 10 ms base). No source (v3's path): nothing runs.
- kernel/src/vm/stadium.c: stadium_resident_heat_total(), read only -- the one output it paces by.
- v4/system/mesh.c, mesh.h: the owner's clock read at every fabric step; each tick delivered, one by one, to
  every node present -- its heartbeat cycle run, active, idle or blocked alike. The tick by execution, the
  nodes' own Loop #7 and the heartrate callback are gone.
- kernel/src/v4/sk_v4.c: the clock gives the heartbeat's bottom half its turn; 0 until POST has ended.
- Tests first, each seen to fail (does not build): kernel/tests/test_heartbeat.c (11 checks),
  test_stadium_node.c (16), test_mesh_boot.c's lockstep checks. Seven Phase 7 checks that assumed the tick by
  execution now drive the test's heartbeat (ruled). POST 990/990 with v3's heat cases as written;
  mesh-boot 103, -on 112, -noop 100, san-mesh-boot 103, every v4 program at both widths, every kernel host
  test: 0 failures. The full `sanitize` target not run (it outlasts the foreground limit).

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:55:14 +00:00
parent 4a5c9bfd42
commit 00be537503
12 changed files with 462 additions and 88 deletions
@@ -1,4 +1,152 @@
# One adaptive heartbeat -- every node ticks in lockstep -- design, for ruling
# One adaptive heartbeat -- design, for ruling
## REVISED 2026-11-17 (Captain Bob): the heartbeat is its own thing
> "The adaptive heartbeat is its own thing. It has nothing to do with stadium with any interaction at all. Not
> words, not messages, not VMs. It has its own independent RWOT and slope provider. Only one output from the
> entire stadium is used as a load measurement for heart rate pacing. THATS IT! ONE AS IN THE NUMBER 1 heartbeat
> (the adaptive one) runs the entire system."
The first version, kept below under a "superseded" banner, got this wrong in three places. I built part of it,
and none of that was committed:
- it made the beat out of the fabric's steps, which ties it to the VMs' execution;
- it drove Loop #7 from Hera's word inference, which is a VM's RWOT and slope;
- it charged the Stadium on the beat.
**Ruled the same day, one at a time:**
1. **The one heartbeat is the kernel's,** `kernel/src/heartbeat.c`: the timer's ISR and its own rolling window.
Every VM's tick is its tick.
2. **Its one Stadium input is resident heat:** how much of the conserved 1.0 is resident on the floor rather
than in the reservoirs, summed over the Stadium. The heartbeat reads it and nothing else, and calls nothing
in the Stadium.
3. **It is held during POST,** as v3's boot runs POST before its timer starts (V3-PARITY 1a). v3's cases then
read as written, the same on every ISA. The VMs' ticks start after POST.
4. **The Stadium is charged as before today:** at the kernel's idle points and after each line, stamped with
the heartbeat's tick. "On the one beat" is withdrawn.
### The design
**A. The heartbeat's own RWOT and slope provider** (`kernel/src/heartbeat.c`):
- On each heartbeat tick, its bottom half (`heartbeat_service`) samples resident heat into a rolling window of
its own.
- Every `HEARTBEAT_INFERENCE_FREQUENCY` ticks, a slope provider of its own runs on that window: v4's inference
arithmetic, `v4/system/inference.c`, which is libc-free and already ported from v3 to the bit.
- Loop #7's rule then sets its own period, through `heartbeat_set_adaptive_period_ns`:
- stable (the inference exits early): 25% slower;
- otherwise: 20% faster;
- within a quarter to four times the 10 ms base.
- No VM, word or message is read, and nothing in the Stadium is called. One read-only accessor is added:
`stadium_resident_heat_total()`.
**B. Every VM ticks on it, in lockstep:**
- The kernel delivers each heartbeat tick to the mesh with `v4_mesh_tick(mesh, tick)`. Ticks missed between
service points are delivered one by one, so no tick is lost.
- On each delivered tick, every node present advances to that tick and runs its heartbeat cycle (decay, window
service, inference on its words, L8, snapshot), in place order, active, idle or blocked alike.
- Nothing in a VM paces the heartbeat. The nodes' own Loop #7 goes: a node adapts nothing of the clock.
**C. Held in POST:** the kernel delivers no ticks until POST has ended.
**D. What goes from the build:**
- the beat counted on fabric steps;
- `steps_per_beat`, `beat_base` and `HEARTBEAT_STEPS_PER_BEAT`;
- Loop #7 on Hera's word inference;
- the mesh's `beat` callback charging the Stadium;
- the per-node tick by execution (`check_counter`, `cycle_every`, `tokens_seen`).
**E. What stays from the build:** a node's tick is the one heartbeat's, the same on every node, and every node
present runs its cycle on each tick.
### Verification, named before anything is built
1. **Test first:**
- the mesh: after N delivered ticks, every node, active or idle, shows tick N, and each ran its cycle on
each;
- an idle node's words decay;
- no tick is delivered during POST;
- the heartbeat (`kernel/tests`, the host harness): resident heat is sampled each tick; the slope provider
runs; Loop #7 moves the period within its bounds; nothing in the Stadium is written by it.
Each test is seen to fail first.
2. **The rest of v4:**
- POST 990 of 990 with v3's heat cases as written, at both widths and under the sanitizers;
- every existing check;
- Phase 7 checks that assumed a tick by execution are brought to Captain Bob one at a time.
3. **The protocol** on a clean tree, three ISAs, one `dict_hash`.
### As built (2026-11-17)
- **The heartbeat paces itself** (`kernel/src/heartbeat.c`, `kernel/include/starkernel/timer.h`):
- `heartbeat_pace_from(load)` gives it its one load source;
- every serviced tick samples that source into the heartbeat's own window (`HEARTBEAT_PACE_WINDOW`,
1024 samples);
- every `HEARTBEAT_PACE_EVERY` (1000) samples its slope provider, `v4_inference_run`, runs on the window,
oldest first;
- Loop #7 then sets the period through `heartbeat_set_adaptive_period_ns`: not stable, 20% faster; stable,
25% slower; within a quarter to four times the 10 ms base.
- **With no source, nothing of this runs.** v3's path never gives one, so it is unchanged. The slope provider
is built under `STARFORTH_V4`.
- **The one input:** `stadium_resident_heat_total()` (`kernel/src/vm/stadium.c`) sums the heat of every
patron on the floor. It is read only.
- **Every VM on it** (`v4/system/mesh.c`, `v4/include/v4/mesh.h`):
- the owner's `clock` is read at every fabric step, and each tick not yet delivered is delivered, one by
one;
- on each tick, every node present whose physics is set up runs its heartbeat cycle, in place order,
active, idle or blocked: lockstep;
- a node's `tick` is the mesh's.
- **What went:**
- the tick by execution (`check_counter`, `cycle_every`, `tokens_seen`);
- the nodes' own Loop #7 (`tick_target_ns`);
- the `heartrate` callback.
- **The kernel** (`kernel/src/v4/sk_v4.c`):
- its `clock` gives the heartbeat's bottom half its turn and returns 0 until POST has ended (held), then the
heartbeat's ticks since;
- `heartbeat_pace_from(stadium_resident_heat_total)` is set before the mesh boots;
- the Stadium is charged as before today.
**Tests:**
| Test | Before | After |
|---|---|---|
| `kernel/tests/test_heartbeat.c` (new) | does not build | 11 checks, 0 failures |
| `kernel/tests/test_stadium_node.c` (added) | does not build | 16 checks, 0 failures |
| `v4/tests/test_mesh_boot.c` (added) | does not build | see below |
What the tests check:
- `test_heartbeat.c`: no source, no pacing; one sample per serviced tick; the slope provider every 1000;
faster when not stable, slower when stable; both bounds; the source taken away.
- `test_stadium_node.c`: resident heat over the Stadium.
- `test_mesh_boot.c`:
- held through the boot and POST;
- five ticks deliver five cycles to Hera and to an idle node alike;
- no tick lost between lines.
**Then:**
- **The mesh-boot builds:** POST 990 of 990, with v3's heat cases as written.
- `mesh-boot`: 103 checks;
- `mesh-boot-on`: 112 checks;
- `mesh-boot-noop`: 100 checks;
- `san-mesh-boot`: 103 checks under ASan and UBSan.
All with 0 failures.
- **Every v4 program at both widths:** 0 failures.
- **The kernel host tests:** all pass.
**Ruled along the way:**
- Seven Phase 7 checks assumed the tick by execution. They now drive the test's heartbeat clock by the ticks
they need (Captain Bob: "Drive the test's heartbeat"). The two Loop #7 checks on Hera went with Hera's
Loop #7.
**Noted, not changed:** v4's inference variance, which is v3's ported to the bit, saturates on very large
spreads. The heartbeat test keeps its fixture within that range.
**Not run here:** the full `sanitize` target, which outlasts the foreground limit. Only the mesh boot, where
the change is, ran under the sanitizers.
---
## SUPERSEDED 2026-11-17 -- the first version (wrong: see above). Kept as the record.
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