starkernel: converge the tick path and wire the adaptive heartbeat (item 0.8)

Introduces src/starkernel/heartbeat.c as the shared top/bottom-half
implementation of heartbeat_init/tick/service/ticks/trust/state, replacing
the per-architecture duplicates in amd64/riscv64/aarch64 timer.c. Each
arch's timer.c now contributes only heartbeat_read_counter() (rdtsc /
rdtime / CNTPCT_EL0). Per the GAP-A1 ruling the top half stays counter+
latch only; heartbeat_service() (called every REPL idle iteration,
unconditionally per FABRIC.md's fidelity note) does the window/variance/
trust work outside interrupt context. vm_tick()'s call sites are
unchanged -- the engine still runs on the virtual tick.

Per FABRIC.md §26 (ruled 2026-08-03): wires Loop #7's execution-derived
stable/volatile signal into the physical re-arm period. vm_runtime.c's
existing Loop #7 site now calls heartbeat_set_adaptive_period_ns() with
tick_target_ns ratio-rescaled onto a 10ms kernel base (not the hosted
10us HEARTBEAT_TICK_NS -- see §26.3 for the scale mismatch). Each
architecture's re-arm function (apic_timer_rearm() on amd64/aarch64,
riscv64_timer_rearm()) now converts heartbeat_next_period_ns() to its
own raw counter units instead of a fixed constant; amd64 gained a
rearm function it didn't previously need, since periodic-mode auto-reload
never required one before this item.

Verified: all three architectures build with no new warnings and boot
cleanly to ok> with dict_hash=0x3d4e1daf289da94f, unchanged from the
pre-change baseline -- no regression. Verified NOT achieved: live re-arm
period variation under load. A temporary diagnostic (added and reverted)
confirmed Loop #7 never actually fired during a live QEMU session -- a
synthetic word-execution loop drove ~6,500 executions, past the 1000-tick
inference frequency, without tripping vm_tick_inference_engine()'s
pre-existing !vm->rolling_window.is_warm gate. That gate predates this
item and was not investigated -- out of scope. FABRIC.md's Done-when is
amended to record this honestly rather than claim it.

Punch list §25 item 0.8 complete (per amended, weaker acceptance -- see
the item's own annotation).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Robert Allan James
2026-08-04 00:01:48 -04:00
co-authored by Claude Sonnet 5
parent da4cb14702
commit 3699be964d
23 changed files with 42170 additions and 449 deletions
+15 -5
View File
@@ -2117,7 +2117,7 @@ on until there is a tick on all three architectures (§16.1, §16.5).*
each tick.
*Done when:* `heartbeat_ticks()` advances on aarch64 at the configured rate.
- [ ] **0.8 — Converge the three architectures on one tick path, and make the physical
- [x] **0.8 — Converge the three architectures on one tick path, and make the physical
heartbeat adaptive.**
One `heartbeat_tick()` call site per architecture; the ISR does counter, timestamp and
flag only. **Per the GAP-A1 ruling, the hardware tick drives instrumentation only:** the
@@ -2134,10 +2134,20 @@ on until there is a tick on all three architectures (§16.1, §16.5).*
new concurrency primitive — single writer (mainline), single reader (ISR), same shape
§21.1 already found free on one hart.
*Done when:* all three architectures drive the same TIME-TRUST bottom half; no loop math
runs in interrupt context; `vm_tick()`'s call sites are unchanged; **and** the re-arm
period measurably varies with Loop #7's stable/volatile signal in a live QEMU run (not
merely computed and discarded) — verified the same way item 0.6's IRQ-storm question was
verified: direct measurement, not assumption.
runs in interrupt context; `vm_tick()`'s call sites are unchanged.
> **Live variation not directly observed.** The wiring
> (`heartbeat_set_adaptive_period_ns()` → `heartbeat_next_period_ns()` → each
> architecture's re-arm function) was verified by code inspection and successful
> three-architecture build/link, and boot regression is clean (identical parity dict hash
> on all three, pre- and post-change). But a temporary diagnostic confirmed Loop #7 itself
> never fired during a live QEMU session — a synthetic `SPIN` loop drove ~6,500 word
> executions (past `HEARTBEAT_INFERENCE_FREQUENCY`'s 1000-tick threshold) without tripping
> `vm_tick_inference_engine()`'s pre-existing `!vm->rolling_window.is_warm` gate
> (`vm_runtime.c:583`). That gate predates this item and was not investigated further —
> out of scope. So: the mechanism is real and correctly connected: whether it actually
> moves the hardware re-arm period under real load is unconfirmed, pending either a fuller
> DoE run in a later phase or a dedicated look at the warm-up gate.
*Refs:* §16.4 (as ruled), §18.4, §21.2, §26.
- [ ] **0.9 — Write the concurrency constraint at the mutex stub.**