Extract heartbeat lease primitive into star-lease #32

Merged

lost-rob0t merged 13 commits from extract/heartbeat-lease-core into main

2026-08-15 14:41:52 +00:00

lost-rob0t commented

2026-08-15 14:39:35 +00:00

(Migrated from github.com)

Scope

Continue the research-ordered one-authority extraction after PR #31 by moving the reusable heartbeat/liveness lease primitive out of prototype/domain-remoting-lease-prototype.lisp into final star-lease.

This is deliberately not presented as the complete durable lease/fencing subsystem from the design research.

Final authority in this slice

star-lease now owns:

monotonic/default heartbeat clock abstraction
positive heartbeat timeout validation
per-key last-seen state
heartbeat observation/renewal
timeout-boundary expiry semantics (>= timeout)
reusable expiry checks against an explicit sampled time
typed lease failures

The explicit sampled-time API preserves the prototype's deterministic behavior: a gateway expiration sweep reads the clock once and applies the same now to every node.

Prototype/domain authority retained

prototype/domain-remoting-lease-prototype.lisp still owns domain-remoting orchestration:

gateway → heartbeat-lease association
node registry iteration
mutation of remote-domain-node-alive-p
sorted expired-node reporting
registration/heartbeat hook composition
expiring nodes before routing
lexical deterministic failover through the existing domain router

Those behaviors are not duplicated in star-lease.

Not implemented / not claimed

The full research lease design still remains future work. This slice does not add:

durable lease claims
lease IDs or scopes
lease generations
fencing tokens
stale-fence result rejection
renewal records
distributed ownership transfer
journal-backed lease recovery
concurrency/rate-window/circuit-breaker policy

Extraction metrics

CI on final head 03fa1cf06807fb87409776f3803ec612d4083e0d reports:

aggregate prototype/**/*.lisp: 19,550 → 19,545 LOC (-5)
prototype/domain-remoting-lease-prototype.lisp: +34 / -39, net -5 lines
final reusable heartbeat lease implementation: 66 LOC

The modest prototype LOC reduction is intentional: gateway mutation and routing remain domain-owned rather than being shoved into the generic lease package.

Validation

GitHub Actions is green on the final head:

independent target-system loading ✅
asdf:test-system :star-actor-protocol ✅
asdf:test-system :star-canonical-json ✅
asdf:test-system :star-journal ✅
asdf:test-system :star-lease ✅ in a fresh process without the prototype package
asdf:test-system :star-mailbox ✅
asdf:test-system :star-sento-compat ✅
asdf:test-system :starlang-runtime ✅
HTTP/scrape final-system tests ✅
asdf:test-system :starlang-prototype ✅ — existing standalone prototype suite, including heartbeat lease and deterministic failover integration
generated interchange validation ✅
frozen canonical fixture/hash verification ✅
nix flake check --print-build-logs ✅

Next dependency-correct slice

Inspect and extract the runtime-directory discovery/resolution boundary using the already-final STAR URI and ActorRef protocol types. Preserve STAR-LANG-004's distinctions between missing, unavailable, and duplicate service registrations; do not create a second registry or move deterministic dispatcher behavior in the same slice.

## Scope Continue the research-ordered one-authority extraction after PR #31 by moving the reusable heartbeat/liveness lease primitive out of `prototype/domain-remoting-lease-prototype.lisp` into final `star-lease`. This is deliberately **not** presented as the complete durable lease/fencing subsystem from the design research. ## Final authority in this slice `star-lease` now owns: - monotonic/default heartbeat clock abstraction - positive heartbeat timeout validation - per-key last-seen state - heartbeat observation/renewal - timeout-boundary expiry semantics (`>= timeout`) - reusable expiry checks against an explicit sampled time - typed lease failures The explicit sampled-time API preserves the prototype's deterministic behavior: a gateway expiration sweep reads the clock once and applies the same `now` to every node. ## Prototype/domain authority retained `prototype/domain-remoting-lease-prototype.lisp` still owns domain-remoting orchestration: - gateway → heartbeat-lease association - node registry iteration - mutation of `remote-domain-node-alive-p` - sorted expired-node reporting - registration/heartbeat hook composition - expiring nodes before routing - lexical deterministic failover through the existing domain router Those behaviors are not duplicated in `star-lease`. ## Not implemented / not claimed The full research lease design still remains future work. This slice does **not** add: - durable lease claims - lease IDs or scopes - lease generations - fencing tokens - stale-fence result rejection - renewal records - distributed ownership transfer - journal-backed lease recovery - concurrency/rate-window/circuit-breaker policy ## Extraction metrics CI on final head `03fa1cf06807fb87409776f3803ec612d4083e0d` reports: - aggregate `prototype/**/*.lisp`: **19,550 → 19,545 LOC (-5)** - `prototype/domain-remoting-lease-prototype.lisp`: **+34 / -39**, net **-5 lines** - final reusable heartbeat lease implementation: **66 LOC** The modest prototype LOC reduction is intentional: gateway mutation and routing remain domain-owned rather than being shoved into the generic lease package. ## Validation GitHub Actions is green on the final head: - independent target-system loading ✅ - `asdf:test-system :star-actor-protocol` ✅ - `asdf:test-system :star-canonical-json` ✅ - `asdf:test-system :star-journal` ✅ - `asdf:test-system :star-lease` ✅ in a fresh process without the prototype package - `asdf:test-system :star-mailbox` ✅ - `asdf:test-system :star-sento-compat` ✅ - `asdf:test-system :starlang-runtime` ✅ - HTTP/scrape final-system tests ✅ - `asdf:test-system :starlang-prototype` ✅ — existing standalone prototype suite, including heartbeat lease and deterministic failover integration - generated interchange validation ✅ - frozen canonical fixture/hash verification ✅ - `nix flake check --print-build-logs` ✅ ## Next dependency-correct slice Inspect and extract the runtime-directory discovery/resolution boundary using the already-final STAR URI and ActorRef protocol types. Preserve STAR-LANG-004's distinctions between missing, unavailable, and duplicate service registrations; do not create a second registry or move deterministic dispatcher behavior in the same slice.