Class Heart

java.lang.Object
ai.redouble.nucleo.harness.AbstractStoppable
ai.redouble.nucleo.harness.Heart
All Implemented Interfaces:
JobObserver<HeartbeatEvent>, Stoppable
public final class Heart extends AbstractStoppable implements JobObserver<HeartbeatEvent>
The heartbeat engine: consumes framework-minted Heartbeats off the bus into the HeartbeatStore, and fires due entries as ordinary job submissions under the authority captured at schedule time. Two virtual threads by design - the bus's per-subscriber queue thread does only fast in-memory store work, and the dispatch thread parks until the next due instant (LockSupport.parkUntil), unparked by the store's change notification. Spurious wakes cost one peek and a re-park.

Catch-up semantics: slots are fixed from the original anchor, so after a pause (GC, laptop sleep, suspended container) every overdue slot fires back-to-back. The burst is deliberate - a silently skipped slot would be behavior an operator has to reverse-engineer; the burst is self-explanatory in the HeartbeatFired timestamps.

Fires go through the REAL submission door: the captured ScopeGuard plays the caller-guard role in the same judgment-and-merge every live submission passes, so a fired flow cannot hold wider scope than its scheduler. A fire failure publishes HeartbeatFireFailed and, for recurring entries, still enqueues the next instance - one bad fire never kills a cadence. A Heart that is stopping drops every request and cancellation it is handed, with a warning naming the message: the store is closing and a late schedule would outlive it.

Since:
0.1 (2026-08-29)
Author:
Andrey Santrosyan