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
227 lines
12 KiB
Markdown
227 lines
12 KiB
Markdown
# 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
|
|
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.
|