@smthrs/run-store 0.0.0-stage → 1.0.0-rc.4

package/dist/esm/Ownership.d.ts

@@ -0,0 +1,275 @@
+/**
+ * Run ownership arbitration: liveness evidence, probes, and heartbeat
+ * supervision.
+ *
+ * The identity being arbitrated — {@link OwnerId} — is defined by
+ * `@smthrs/journal`, because it is the fencing token the journal accepts on
+ * durable appends. It is re-exported here so ownership callers keep reading it
+ * as one vocabulary.
+ *
+ * @since 0.1.0
+ */
+import { LivenessEvidence } from "@smthrs/journal/Consensus";
+import { OwnerId } from "@smthrs/journal/OwnerId";
+import { Duration, Effect } from "effect";
+import { RunStore } from "./RunStore.ts";
+export { 
+/**
+ * A process identity scoped to a host and a unique ownership nonce, defined
+ * by `@smthrs/journal` as the fence on durable appends.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+OwnerId };
+export { 
+/**
+ * Evidence that the owner in an exact run snapshot is no longer live.
+ *
+ * Defined by `@smthrs/journal`'s `Consensus`, because R5 — steal requires
+ * staleness plus liveness evidence — is a consensus rule every strategy
+ * validates. Two of the three kinds are collected outside the store:
+ * `same-host-pid-dead` is a local process probe, and
+ * `cross-host-unreachable-stale` is a reachability judgement the deployment
+ * makes. `lease-expired` is different — it asserts only that the persisted
+ * heartbeat is older than the staleness cutoff, which is the one claim the
+ * strategy can check for itself, and `steal` checks it: the takeover
+ * refuses any lease whose heartbeat is still inside the window. It is
+ * therefore accepted from a claimant on any host, while the other two stay
+ * bound to the host relation that makes them meaningful. The observation
+ * must carry the exact instant supplied to the consuming operation:
+ * `checkedAtMs` must equal that operation's `nowMs`. A caller that probes
+ * at T and calls at T+1 is refused and must build fresh evidence.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+LivenessEvidence };
+/**
+ * Evidence-factory signature a composition uses for ownership arbitration.
+ *
+ * A `LivenessProbe` returns `LivenessEvidence` or `undefined` for `steal`,
+ * `claimAndOwn`, and `recoverClaim` to verify. {@link LivenessCheck} is the
+ * separate alive-or-not question the engine asks before it decides to steal.
+ * `RunStore` validates supplied evidence and never probes a process or network
+ * itself.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export type LivenessProbe<E = never, R = never> = (expectedOwner: OwnerId, claimant: OwnerId, checkedAtMs: number) => Effect.Effect<LivenessEvidence | undefined, E, R>;
+/**
+ * What a liveness check knows about the run it is asked about, beyond the
+ * owner recorded on it.
+ *
+ * The lease is here because it is the only liveness signal every deployment
+ * has: `heartbeatAtMs` is the last heartbeat the owner persisted, `nowMs` is
+ * the reading the arbitration is made against, and `claimant` is the identity
+ * that would take the run over. A check that wants to probe a pid compares
+ * hosts with {@link sameHostIncarnation} first; a check that has nothing but
+ * the lease uses {@link leaseLiveness}.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface LivenessContext {
+    readonly claimant: OwnerId;
+    readonly heartbeatAtMs: number | null;
+    readonly nowMs: number;
+}
+/**
+ * The question ownership arbitration asks before it steals a run: is the
+ * recorded owner still working?
+ *
+ * Answering `true` refuses the takeover. The engine consults this only for a
+ * run whose lease has already expired, so a check that has no better evidence
+ * than the lease answers `false` there — which is exactly what
+ * {@link leaseLiveness} does.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export type LivenessCheck = (expectedOwner: OwnerId, context: LivenessContext) => Effect.Effect<boolean>;
+/**
+ * Whether two owner identities are incarnations on the same host.
+ *
+ * The predicate a probe applies before it inspects a pid: `owner.pid` names a
+ * process in the claimant's own process namespace only when the hosts match,
+ * so a cross-host probe that read it would be answering about an unrelated
+ * process. Exposed because the check that needs it — a
+ * `process.kill(pid, 0)` probe — belongs to a platform package rather than
+ * here.
+ *
+ * @since 0.1.0
+ * @category ownership
+ */
+export declare const sameHostIncarnation: (expectedOwner: OwnerId, claimant: OwnerId) => boolean;
+/**
+ * The default liveness check: the lease, and nothing else.
+ *
+ * An owner is treated as alive for as long as its persisted heartbeat is
+ * younger than `staleAfter`, and as gone once it is not. That is the weakest
+ * honest answer, and it is the one every host can give: a fresh process with
+ * no application code at all can reclaim a hard-killed owner's runs once the
+ * lease it stopped renewing has expired. A deployment that can say more — a
+ * pid probe on the owner's host, an orchestrator that reports pod liveness —
+ * supplies its own {@link LivenessCheck} and refuses the takeover for longer.
+ *
+ * An owner with no recorded heartbeat holds no lease and is reported gone; the
+ * steal it enables is still gated by the store's own snapshot compare-and-swap.
+ *
+ * @since 0.1.0
+ * @category ownership
+ */
+export declare const leaseLiveness: (staleAfter?: Duration.Input) => LivenessCheck;
+/**
+ * The Node hosts' liveness check: does the owner's process still exist?
+ *
+ * {@link leaseLiveness} is the honest floor — every host can read a persisted
+ * heartbeat — but it is only a timeout, so two engine processes over one
+ * database steal each other's running rows `heartbeatStaleAfter` after any
+ * heartbeat stall: a stop-the-world pause, a swapped-out process, a disk that
+ * blocked longer than the window. This answers the question the lease is
+ * standing in for, by asking the operating system whether the recorded pid is
+ * still there.
+ *
+ * `process.kill(pid, 0)` sends no signal; it performs only the delivery
+ * checks. Three answers matter:
+ *
+ * - It returns: the process exists and is signalable. The owner is alive.
+ * - It throws `ESRCH`: no such process exists. This is the sole death answer,
+ *   so the owner is gone.
+ * - It throws anything else, including `EPERM`, `EINVAL`, or an unrecognized
+ *   value: the owner is treated as alive because an unknown answer is not
+ *   death.
+ *
+ * This `ESRCH`-only death rule deliberately aligns with
+ * `@smthrs/platform-node`'s `HostLiveness`.
+ *
+ * A pid is only meaningful inside one process namespace, so a recorded owner
+ * on another host is never probed: the answer is `false` and the arbitration
+ * falls back to the evidence that does cross hosts — the expired lease, which
+ * `RunStore.steal` verifies for itself. The engine consults this check only
+ * for a run whose lease has ALREADY expired, so answering `false` here does
+ * not weaken anything; it declines to add evidence.
+ *
+ * Node hosts only. It is not part of the browser promise: this entry point
+ * bundles for the browser because it never imports a `node:` built-in, and a
+ * browser composition has no process table to ask, so it keeps
+ * {@link leaseLiveness}.
+ *
+ * `@smthrs/platform-node`'s `HostLiveness.isAlive` asks the same question of
+ * the same process table and differs in one deliberate place: it answers
+ * `true` for an owner on another host, which refuses the steal outright, while
+ * this check answers `false` and lets the expired lease decide. The difference
+ * matters after a host dies for good — under the refusing answer its runs are
+ * never reclaimed by anyone, because no other machine can ever produce
+ * evidence about its pids.
+ *
+ * Two limits are inherent to asking a pid, and they bound what reclaim can
+ * promise. Both are shared with `HostLiveness.isAlive`.
+ *
+ * - An owner recorded with the CLAIMANT'S OWN pid is always alive. A previous
+ *   incarnation of this process, or a second engine composed inside it, differs
+ *   from the claimant only by `nonce`, and the process it names is this one.
+ *   Such a row is never stolen while the process lives, so an embedded host
+ *   that re-creates its engine in place should keep {@link leaseLiveness},
+ *   whose timeout does expire. Reading same-pid-different-nonce as death is
+ *   not the alternative: it would let two engines in one process — the exact
+ *   shape this check exists to arbitrate — steal each other's live runs.
+ * - A pid the operating system has REUSED reports the unrelated process that
+ *   now holds it. The dead owner's row stays refused for as long as that
+ *   process lives, which delays reclaim rather than breaking it: the row is
+ *   still `running` under an expired lease, and the next probe after the pid
+ *   is free reclaims it.
+ *
+ * @since 0.1.0
+ * @category ownership
+ */
+export declare const sameHostPidProbe: LivenessCheck;
+export { 
+/**
+ * How often the supervision loop pulses to renew the owner's lease.
+ *
+ * @since 0.1.0
+ * @category constants
+ */
+heartbeatInterval, 
+/**
+ * How far the owner's wall clock may run behind a peer's before the lease
+ * reasoning stops holding.
+ *
+ * @since 0.1.0
+ * @category constants
+ */
+heartbeatSkewAllowance, 
+/**
+ * How old a persisted heartbeat must be before a peer may steal the run.
+ *
+ * @since 0.1.0
+ * @category constants
+ */
+heartbeatStaleAfter, 
+/**
+ * How long the owner may keep working through failing or stalled heartbeat writes.
+ *
+ * @since 0.1.0
+ * @category constants
+ */
+heartbeatWriteTolerance } from "./Heartbeat.ts";
+/**
+ * Hooks a {@link heartbeatLoop} caller may supply.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export interface HeartbeatLoopOptions {
+    /** Called after the same unclaimed owner reconfirms an expired heartbeat budget. */
+    readonly onReconfirm?: ((unconfirmedMs: number) => Effect.Effect<void>) | undefined;
+    /** Called with the unconfirmed milliseconds when the lease lapses, before the loop interrupts itself. */
+    readonly onLapse?: ((unconfirmedMs: number) => Effect.Effect<void>) | undefined;
+}
+/**
+ * Runs heartbeats until the persisted ownership fence is lost, then interrupts
+ * itself. Race this effect with owned work so structured concurrency
+ * interrupts the work when ownership disappears.
+ *
+ * Each pulse drives the injected `Consensus` strategy's `heartbeat` through
+ * `RunStore.heartbeat`, which renews the strategy's lease and mirrors the
+ * recorded stamp onto the run row in the same transaction. Heartbeats are
+ * lease evidence, never journal events.
+ *
+ * Pulses are delayed by `heartbeatInterval` and read the Effect `Clock`, so the
+ * loop is fully driveable with `TestClock`.
+ *
+ * A lost fence — any outcome other than `Updated` — is durable evidence and
+ * interrupts immediately. A failed heartbeat *write* is not: the persisted
+ * heartbeat is still there and no other process may steal the run until it is
+ * `heartbeatStaleAfter` old, so transient write errors are tolerated for
+ * `heartbeatWriteTolerance` — deliberately shorter than the steal cutoff by a
+ * pulse plus `heartbeatSkewAllowance`. The reserved pulse bounds a final
+ * reconfirmation; a pending claim or changed owner fails that check. Past that allowance
+ * the fence still protects durable writes but non-durable side effects may
+ * overlap; see {@link heartbeatWriteTolerance}.
+ *
+ * An independent deadline races the pulse loop. At expiry it reconfirms the
+ * same owner with no pending claim, bounded by one heartbeat interval. A
+ * renewed lease continues supervision; loss, error, or timeout interrupts
+ * even when an ordinary heartbeat write never returns. Each successful
+ * pulse re-arms the deadline from the timestamp sent to the store, not from
+ * its completion time. The deadline re-reads the clock after waking, so delayed
+ * writes cannot hide expiry behind a stale clock reading.
+ *
+ * `options.onReconfirm` records a successful reconfirmation after a gap. Its
+ * deadline is the remaining renewed lease budget, measured from the timestamp
+ * sent to the store. A blocked or failed receipt lapses the lease instead of
+ * stranding supervision; receipt completion never grants another lease budget.
+ * `options.onLapse` runs once, before the self-interrupt, when reconfirmation
+ * fails: it receives how long the lease went unconfirmed, so the caller can
+ * record why its work stopped. A lost fence does not call it.
+ *
+ * @since 0.1.0
+ * @category supervision
+ */
+export declare const heartbeatLoop: (runId: string, owner: OwnerId, options?: HeartbeatLoopOptions) => Effect.Effect<never, never, RunStore>;
+//# sourceMappingURL=Ownership.d.ts.map

package/dist/esm/Ownership.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Ownership.d.ts","sourceRoot":"","sources":["../../src/Ownership.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAA;AAC5D,OAAO,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAA;AACjD,OAAO,EAAgB,QAAQ,EAAE,MAAM,EAAa,MAAM,QAAQ,CAAA;AAElE,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAExC,OAAO;AACL;;;;;;GAMG;AACH,OAAO,EACR,CAAA;AAED,OAAO;AACL;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,gBAAgB,EACjB,CAAA;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,GAAG,KAAK,EAAE,CAAC,GAAG,KAAK,IAAI,CAChD,aAAa,EAAE,OAAO,EACtB,QAAQ,EAAE,OAAO,EACjB,WAAW,EAAE,MAAM,KAChB,MAAM,CAAC,MAAM,CAAC,gBAAgB,GAAG,SAAS,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA;AAEtD;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IACrC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,aAAa,GAAG,CAC1B,aAAa,EAAE,OAAO,EACtB,OAAO,EAAE,eAAe,KACrB,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;AAE3B;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,mBAAmB,GAC9B,eAAe,OAAO,EACtB,UAAU,OAAO,KAChB,OAAmD,CAAA;AAEtD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,aAAa,GACxB,aAAY,QAAQ,CAAC,KAA2B,KAC/C,aAOF,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,eAAO,MAAM,gBAAgB,EAAE,aAU3B,CAAA;AAEJ,OAAO;AACL;;;;;GAKG;AACH,iBAAiB;AACjB;;;;;;GAMG;AACH,sBAAsB;AACtB;;;;;GAKG;AACH,mBAAmB;AACnB;;;;;GAKG;AACH,uBAAuB,EACxB,MAAM,gBAAgB,CAAA;AAEvB;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,oFAAoF;IACpF,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,aAAa,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,GAAG,SAAS,CAAA;IACnF,yGAAyG;IACzG,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,aAAa,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,GAAG,SAAS,CAAA;CAChF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,eAAO,MAAM,aAAa,GACxB,OAAO,MAAM,EACb,OAAO,OAAO,EACd,UAAS,oBAAyB,KACjC,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAoFnC,CAAA"}

package/dist/esm/Ownership.js

@@ -0,0 +1,299 @@
+/**
+ * Run ownership arbitration: liveness evidence, probes, and heartbeat
+ * supervision.
+ *
+ * The identity being arbitrated — {@link OwnerId} — is defined by
+ * `@smthrs/journal`, because it is the fencing token the journal accepts on
+ * durable appends. It is re-exported here so ownership callers keep reading it
+ * as one vocabulary.
+ *
+ * @since 0.1.0
+ */
+import { LivenessEvidence } from "@smthrs/journal/Consensus";
+import { OwnerId } from "@smthrs/journal/OwnerId";
+import { Cause, Clock, Duration, Effect, Semaphore } from "effect";
+import { heartbeatInterval, heartbeatStaleAfter, heartbeatWriteTolerance } from "./Heartbeat.js";
+import { RunStore } from "./RunStore.js";
+export { 
+/**
+ * A process identity scoped to a host and a unique ownership nonce, defined
+ * by `@smthrs/journal` as the fence on durable appends.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+OwnerId };
+export { 
+/**
+ * Evidence that the owner in an exact run snapshot is no longer live.
+ *
+ * Defined by `@smthrs/journal`'s `Consensus`, because R5 — steal requires
+ * staleness plus liveness evidence — is a consensus rule every strategy
+ * validates. Two of the three kinds are collected outside the store:
+ * `same-host-pid-dead` is a local process probe, and
+ * `cross-host-unreachable-stale` is a reachability judgement the deployment
+ * makes. `lease-expired` is different — it asserts only that the persisted
+ * heartbeat is older than the staleness cutoff, which is the one claim the
+ * strategy can check for itself, and `steal` checks it: the takeover
+ * refuses any lease whose heartbeat is still inside the window. It is
+ * therefore accepted from a claimant on any host, while the other two stay
+ * bound to the host relation that makes them meaningful. The observation
+ * must carry the exact instant supplied to the consuming operation:
+ * `checkedAtMs` must equal that operation's `nowMs`. A caller that probes
+ * at T and calls at T+1 is refused and must build fresh evidence.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+LivenessEvidence };
+/**
+ * Whether two owner identities are incarnations on the same host.
+ *
+ * The predicate a probe applies before it inspects a pid: `owner.pid` names a
+ * process in the claimant's own process namespace only when the hosts match,
+ * so a cross-host probe that read it would be answering about an unrelated
+ * process. Exposed because the check that needs it — a
+ * `process.kill(pid, 0)` probe — belongs to a platform package rather than
+ * here.
+ *
+ * @since 0.1.0
+ * @category ownership
+ */
+export const sameHostIncarnation = (expectedOwner, claimant) => expectedOwner.hostId === claimant.hostId;
+/**
+ * The default liveness check: the lease, and nothing else.
+ *
+ * An owner is treated as alive for as long as its persisted heartbeat is
+ * younger than `staleAfter`, and as gone once it is not. That is the weakest
+ * honest answer, and it is the one every host can give: a fresh process with
+ * no application code at all can reclaim a hard-killed owner's runs once the
+ * lease it stopped renewing has expired. A deployment that can say more — a
+ * pid probe on the owner's host, an orchestrator that reports pod liveness —
+ * supplies its own {@link LivenessCheck} and refuses the takeover for longer.
+ *
+ * An owner with no recorded heartbeat holds no lease and is reported gone; the
+ * steal it enables is still gated by the store's own snapshot compare-and-swap.
+ *
+ * @since 0.1.0
+ * @category ownership
+ */
+export const leaseLiveness = (staleAfter = heartbeatStaleAfter) => {
+    const staleAfterMs = Duration.toMillis(staleAfter);
+    return (_expectedOwner, context) => Effect.succeed(context.heartbeatAtMs !== null &&
+        context.heartbeatAtMs >= context.nowMs - staleAfterMs);
+};
+/**
+ * The Node hosts' liveness check: does the owner's process still exist?
+ *
+ * {@link leaseLiveness} is the honest floor — every host can read a persisted
+ * heartbeat — but it is only a timeout, so two engine processes over one
+ * database steal each other's running rows `heartbeatStaleAfter` after any
+ * heartbeat stall: a stop-the-world pause, a swapped-out process, a disk that
+ * blocked longer than the window. This answers the question the lease is
+ * standing in for, by asking the operating system whether the recorded pid is
+ * still there.
+ *
+ * `process.kill(pid, 0)` sends no signal; it performs only the delivery
+ * checks. Three answers matter:
+ *
+ * - It returns: the process exists and is signalable. The owner is alive.
+ * - It throws `ESRCH`: no such process exists. This is the sole death answer,
+ *   so the owner is gone.
+ * - It throws anything else, including `EPERM`, `EINVAL`, or an unrecognized
+ *   value: the owner is treated as alive because an unknown answer is not
+ *   death.
+ *
+ * This `ESRCH`-only death rule deliberately aligns with
+ * `@smthrs/platform-node`'s `HostLiveness`.
+ *
+ * A pid is only meaningful inside one process namespace, so a recorded owner
+ * on another host is never probed: the answer is `false` and the arbitration
+ * falls back to the evidence that does cross hosts — the expired lease, which
+ * `RunStore.steal` verifies for itself. The engine consults this check only
+ * for a run whose lease has ALREADY expired, so answering `false` here does
+ * not weaken anything; it declines to add evidence.
+ *
+ * Node hosts only. It is not part of the browser promise: this entry point
+ * bundles for the browser because it never imports a `node:` built-in, and a
+ * browser composition has no process table to ask, so it keeps
+ * {@link leaseLiveness}.
+ *
+ * `@smthrs/platform-node`'s `HostLiveness.isAlive` asks the same question of
+ * the same process table and differs in one deliberate place: it answers
+ * `true` for an owner on another host, which refuses the steal outright, while
+ * this check answers `false` and lets the expired lease decide. The difference
+ * matters after a host dies for good — under the refusing answer its runs are
+ * never reclaimed by anyone, because no other machine can ever produce
+ * evidence about its pids.
+ *
+ * Two limits are inherent to asking a pid, and they bound what reclaim can
+ * promise. Both are shared with `HostLiveness.isAlive`.
+ *
+ * - An owner recorded with the CLAIMANT'S OWN pid is always alive. A previous
+ *   incarnation of this process, or a second engine composed inside it, differs
+ *   from the claimant only by `nonce`, and the process it names is this one.
+ *   Such a row is never stolen while the process lives, so an embedded host
+ *   that re-creates its engine in place should keep {@link leaseLiveness},
+ *   whose timeout does expire. Reading same-pid-different-nonce as death is
+ *   not the alternative: it would let two engines in one process — the exact
+ *   shape this check exists to arbitrate — steal each other's live runs.
+ * - A pid the operating system has REUSED reports the unrelated process that
+ *   now holds it. The dead owner's row stays refused for as long as that
+ *   process lives, which delays reclaim rather than breaking it: the row is
+ *   still `running` under an expired lease, and the next probe after the pid
+ *   is free reclaims it.
+ *
+ * @since 0.1.0
+ * @category ownership
+ */
+export const sameHostPidProbe = (expectedOwner, context) => Effect.sync(() => {
+    if (!sameHostIncarnation(expectedOwner, context.claimant))
+        return false;
+    if (!Number.isSafeInteger(expectedOwner.pid) || expectedOwner.pid <= 0)
+        return true;
+    try {
+        process.kill(expectedOwner.pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error?.code !== "ESRCH";
+    }
+});
+export { 
+/**
+ * How often the supervision loop pulses to renew the owner's lease.
+ *
+ * @since 0.1.0
+ * @category constants
+ */
+heartbeatInterval, 
+/**
+ * How far the owner's wall clock may run behind a peer's before the lease
+ * reasoning stops holding.
+ *
+ * @since 0.1.0
+ * @category constants
+ */
+heartbeatSkewAllowance, 
+/**
+ * How old a persisted heartbeat must be before a peer may steal the run.
+ *
+ * @since 0.1.0
+ * @category constants
+ */
+heartbeatStaleAfter, 
+/**
+ * How long the owner may keep working through failing or stalled heartbeat writes.
+ *
+ * @since 0.1.0
+ * @category constants
+ */
+heartbeatWriteTolerance } from "./Heartbeat.js";
+/**
+ * Runs heartbeats until the persisted ownership fence is lost, then interrupts
+ * itself. Race this effect with owned work so structured concurrency
+ * interrupts the work when ownership disappears.
+ *
+ * Each pulse drives the injected `Consensus` strategy's `heartbeat` through
+ * `RunStore.heartbeat`, which renews the strategy's lease and mirrors the
+ * recorded stamp onto the run row in the same transaction. Heartbeats are
+ * lease evidence, never journal events.
+ *
+ * Pulses are delayed by `heartbeatInterval` and read the Effect `Clock`, so the
+ * loop is fully driveable with `TestClock`.
+ *
+ * A lost fence — any outcome other than `Updated` — is durable evidence and
+ * interrupts immediately. A failed heartbeat *write* is not: the persisted
+ * heartbeat is still there and no other process may steal the run until it is
+ * `heartbeatStaleAfter` old, so transient write errors are tolerated for
+ * `heartbeatWriteTolerance` — deliberately shorter than the steal cutoff by a
+ * pulse plus `heartbeatSkewAllowance`. The reserved pulse bounds a final
+ * reconfirmation; a pending claim or changed owner fails that check. Past that allowance
+ * the fence still protects durable writes but non-durable side effects may
+ * overlap; see {@link heartbeatWriteTolerance}.
+ *
+ * An independent deadline races the pulse loop. At expiry it reconfirms the
+ * same owner with no pending claim, bounded by one heartbeat interval. A
+ * renewed lease continues supervision; loss, error, or timeout interrupts
+ * even when an ordinary heartbeat write never returns. Each successful
+ * pulse re-arms the deadline from the timestamp sent to the store, not from
+ * its completion time. The deadline re-reads the clock after waking, so delayed
+ * writes cannot hide expiry behind a stale clock reading.
+ *
+ * `options.onReconfirm` records a successful reconfirmation after a gap. Its
+ * deadline is the remaining renewed lease budget, measured from the timestamp
+ * sent to the store. A blocked or failed receipt lapses the lease instead of
+ * stranding supervision; receipt completion never grants another lease budget.
+ * `options.onLapse` runs once, before the self-interrupt, when reconfirmation
+ * fails: it receives how long the lease went unconfirmed, so the caller can
+ * record why its work stopped. A lost fence does not call it.
+ *
+ * @since 0.1.0
+ * @category supervision
+ */
+export const heartbeatLoop = (runId, owner, options = {}) => Effect.gen(function* () {
+    const runStore = yield* RunStore;
+    const toleranceMs = Duration.toMillis(heartbeatWriteTolerance);
+    const intervalMs = Duration.toMillis(heartbeatInterval);
+    let lastConfirmedPulseMs = yield* Clock.currentTimeMillis;
+    let failing = false;
+    // Both overdue timers may wake after a host stall. Serialize expiry and
+    // recheck the budget so they cannot reconfirm or journal the same gap twice.
+    const expiry = yield* Semaphore.make(1);
+    const expire = () => expiry.withPermit(Effect.gen(function* () {
+        // A competing expiry may have held the permit across a write. Take
+        // fresh evidence after acquisition, never the waiting timer's reading.
+        const nowMs = yield* Clock.currentTimeMillis;
+        if (nowMs - lastConfirmedPulseMs < toleranceMs)
+            return;
+        const unconfirmedMs = nowMs - lastConfirmedPulseMs;
+        const renewed = yield* runStore.reconfirm(runId, owner, Math.floor(nowMs)).pipe(
+        // Only the ownership check consumes the old lease's reserved pulse.
+        Effect.timeout(heartbeatInterval), Effect.flatMap((outcome) => Effect.gen(function* () {
+            if (outcome._tag !== "Updated")
+                return false;
+            lastConfirmedPulseMs = Math.max(lastConfirmedPulseMs, Math.floor(nowMs));
+            failing = false;
+            const confirmedAtMs = yield* Clock.currentTimeMillis;
+            const remainingMs = lastConfirmedPulseMs + toleranceMs - confirmedAtMs;
+            if (remainingMs <= 0)
+                return false;
+            // The receipt is still required and bounded, but ownership was
+            // already renewed. Spending only its old reserved pulse would
+            // interrupt live work despite a fresh, fenced persisted lease.
+            yield* (options.onReconfirm?.(unconfirmedMs) ?? Effect.void).pipe(Effect.timeout(remainingMs));
+            return true;
+        })), Effect.catchCause((cause) => Cause.hasInterruptsOnly(cause) ? Effect.failCause(cause) : Effect.succeed(false)));
+        if (renewed)
+            return;
+        yield* Effect.logWarning("run lease lapsed; interrupting owned work").pipe(Effect.annotateLogs({ runId, unconfirmedMs }), Effect.andThen(options.onLapse?.(unconfirmedMs) ?? Effect.void), Effect.andThen(Effect.interrupt));
+    }));
+    const deadline = Effect.gen(function* () {
+        while (true) {
+            const nowMs = yield* Clock.currentTimeMillis;
+            const remainingMs = lastConfirmedPulseMs + toleranceMs - nowMs;
+            if (remainingMs <= 0) {
+                yield* expire();
+                continue;
+            }
+            // Check alongside pulse intervals, with a shorter final wait when needed.
+            yield* Effect.sleep(Math.min(remainingMs, intervalMs));
+        }
+    });
+    const pulses = Effect.sleep(heartbeatInterval).pipe(Effect.andThen(Clock.currentTimeMillis.pipe(Effect.map(Math.floor))), Effect.flatMap((nowMs) => nowMs - lastConfirmedPulseMs >= toleranceMs ? expire() : runStore.heartbeat(runId, owner, nowMs).pipe(Effect.flatMap((outcome) => outcome._tag === "Updated"
+        ? Effect.sync(() => {
+            lastConfirmedPulseMs = Math.max(lastConfirmedPulseMs, nowMs);
+            failing = false;
+        })
+        : Effect.interrupt), 
+    // A failed write keeps the confirmed lease; the independent deadline
+    // supervises its expiry. Warn on the first failure of an outage.
+    Effect.catch((error) => {
+        if (failing)
+            return Effect.void;
+        failing = true;
+        return Effect.logWarning("run heartbeat write failed").pipe(Effect.annotateLogs({ runId, code: error.code }));
+    }))), Effect.forever);
+    return yield* Effect.raceFirst(pulses, deadline);
+});
+//# sourceMappingURL=Ownership.js.map

package/dist/esm/Ownership.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Ownership.js","sourceRoot":"","sources":["../../src/Ownership.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Run ownership arbitration: liveness evidence, probes, and heartbeat\n * supervision.\n *\n * The identity being arbitrated — {@link OwnerId} — is defined by\n * `@smthrs/journal`, because it is the fencing token the journal accepts on\n * durable appends. It is re-exported here so ownership callers keep reading it\n * as one vocabulary.\n *\n * @since 0.1.0\n */\n\nimport { LivenessEvidence } from \"@smthrs/journal/Consensus\"\nimport { OwnerId } from \"@smthrs/journal/OwnerId\"\nimport { Cause, Clock, Duration, Effect, Semaphore } from \"effect\"\nimport { heartbeatInterval, heartbeatStaleAfter, heartbeatWriteTolerance } from \"./Heartbeat.ts\"\nimport { RunStore } from \"./RunStore.ts\"\n\nexport {\n  /**\n   * A process identity scoped to a host and a unique ownership nonce, defined\n   * by `@smthrs/journal` as the fence on durable appends.\n   *\n   * @since 0.1.0\n   * @category models\n   */\n  OwnerId\n}\n\nexport {\n  /**\n   * Evidence that the owner in an exact run snapshot is no longer live.\n   *\n   * Defined by `@smthrs/journal`'s `Consensus`, because R5 — steal requires\n   * staleness plus liveness evidence — is a consensus rule every strategy\n   * validates. Two of the three kinds are collected outside the store:\n   * `same-host-pid-dead` is a local process probe, and\n   * `cross-host-unreachable-stale` is a reachability judgement the deployment\n   * makes. `lease-expired` is different — it asserts only that the persisted\n   * heartbeat is older than the staleness cutoff, which is the one claim the\n   * strategy can check for itself, and `steal` checks it: the takeover\n   * refuses any lease whose heartbeat is still inside the window. It is\n   * therefore accepted from a claimant on any host, while the other two stay\n   * bound to the host relation that makes them meaningful. The observation\n   * must carry the exact instant supplied to the consuming operation:\n   * `checkedAtMs` must equal that operation's `nowMs`. A caller that probes\n   * at T and calls at T+1 is refused and must build fresh evidence.\n   *\n   * @since 0.1.0\n   * @category models\n   */\n  LivenessEvidence\n}\n\n/**\n * Evidence-factory signature a composition uses for ownership arbitration.\n *\n * A `LivenessProbe` returns `LivenessEvidence` or `undefined` for `steal`,\n * `claimAndOwn`, and `recoverClaim` to verify. {@link LivenessCheck} is the\n * separate alive-or-not question the engine asks before it decides to steal.\n * `RunStore` validates supplied evidence and never probes a process or network\n * itself.\n *\n * @since 0.1.0\n * @category models\n */\nexport type LivenessProbe<E = never, R = never> = (\n  expectedOwner: OwnerId,\n  claimant: OwnerId,\n  checkedAtMs: number\n) => Effect.Effect<LivenessEvidence | undefined, E, R>\n\n/**\n * What a liveness check knows about the run it is asked about, beyond the\n * owner recorded on it.\n *\n * The lease is here because it is the only liveness signal every deployment\n * has: `heartbeatAtMs` is the last heartbeat the owner persisted, `nowMs` is\n * the reading the arbitration is made against, and `claimant` is the identity\n * that would take the run over. A check that wants to probe a pid compares\n * hosts with {@link sameHostIncarnation} first; a check that has nothing but\n * the lease uses {@link leaseLiveness}.\n *\n * @since 0.1.0\n * @category models\n */\nexport interface LivenessContext {\n  readonly claimant: OwnerId\n  readonly heartbeatAtMs: number | null\n  readonly nowMs: number\n}\n\n/**\n * The question ownership arbitration asks before it steals a run: is the\n * recorded owner still working?\n *\n * Answering `true` refuses the takeover. The engine consults this only for a\n * run whose lease has already expired, so a check that has no better evidence\n * than the lease answers `false` there — which is exactly what\n * {@link leaseLiveness} does.\n *\n * @since 0.1.0\n * @category models\n */\nexport type LivenessCheck = (\n  expectedOwner: OwnerId,\n  context: LivenessContext\n) => Effect.Effect<boolean>\n\n/**\n * Whether two owner identities are incarnations on the same host.\n *\n * The predicate a probe applies before it inspects a pid: `owner.pid` names a\n * process in the claimant's own process namespace only when the hosts match,\n * so a cross-host probe that read it would be answering about an unrelated\n * process. Exposed because the check that needs it — a\n * `process.kill(pid, 0)` probe — belongs to a platform package rather than\n * here.\n *\n * @since 0.1.0\n * @category ownership\n */\nexport const sameHostIncarnation = (\n  expectedOwner: OwnerId,\n  claimant: OwnerId\n): boolean => expectedOwner.hostId === claimant.hostId\n\n/**\n * The default liveness check: the lease, and nothing else.\n *\n * An owner is treated as alive for as long as its persisted heartbeat is\n * younger than `staleAfter`, and as gone once it is not. That is the weakest\n * honest answer, and it is the one every host can give: a fresh process with\n * no application code at all can reclaim a hard-killed owner's runs once the\n * lease it stopped renewing has expired. A deployment that can say more — a\n * pid probe on the owner's host, an orchestrator that reports pod liveness —\n * supplies its own {@link LivenessCheck} and refuses the takeover for longer.\n *\n * An owner with no recorded heartbeat holds no lease and is reported gone; the\n * steal it enables is still gated by the store's own snapshot compare-and-swap.\n *\n * @since 0.1.0\n * @category ownership\n */\nexport const leaseLiveness = (\n  staleAfter: Duration.Input = heartbeatStaleAfter\n): LivenessCheck => {\n  const staleAfterMs = Duration.toMillis(staleAfter)\n  return (_expectedOwner, context) =>\n    Effect.succeed(\n      context.heartbeatAtMs !== null &&\n        context.heartbeatAtMs >= context.nowMs - staleAfterMs\n    )\n}\n\n/**\n * The Node hosts' liveness check: does the owner's process still exist?\n *\n * {@link leaseLiveness} is the honest floor — every host can read a persisted\n * heartbeat — but it is only a timeout, so two engine processes over one\n * database steal each other's running rows `heartbeatStaleAfter` after any\n * heartbeat stall: a stop-the-world pause, a swapped-out process, a disk that\n * blocked longer than the window. This answers the question the lease is\n * standing in for, by asking the operating system whether the recorded pid is\n * still there.\n *\n * `process.kill(pid, 0)` sends no signal; it performs only the delivery\n * checks. Three answers matter:\n *\n * - It returns: the process exists and is signalable. The owner is alive.\n * - It throws `ESRCH`: no such process exists. This is the sole death answer,\n *   so the owner is gone.\n * - It throws anything else, including `EPERM`, `EINVAL`, or an unrecognized\n *   value: the owner is treated as alive because an unknown answer is not\n *   death.\n *\n * This `ESRCH`-only death rule deliberately aligns with\n * `@smthrs/platform-node`'s `HostLiveness`.\n *\n * A pid is only meaningful inside one process namespace, so a recorded owner\n * on another host is never probed: the answer is `false` and the arbitration\n * falls back to the evidence that does cross hosts — the expired lease, which\n * `RunStore.steal` verifies for itself. The engine consults this check only\n * for a run whose lease has ALREADY expired, so answering `false` here does\n * not weaken anything; it declines to add evidence.\n *\n * Node hosts only. It is not part of the browser promise: this entry point\n * bundles for the browser because it never imports a `node:` built-in, and a\n * browser composition has no process table to ask, so it keeps\n * {@link leaseLiveness}.\n *\n * `@smthrs/platform-node`'s `HostLiveness.isAlive` asks the same question of\n * the same process table and differs in one deliberate place: it answers\n * `true` for an owner on another host, which refuses the steal outright, while\n * this check answers `false` and lets the expired lease decide. The difference\n * matters after a host dies for good — under the refusing answer its runs are\n * never reclaimed by anyone, because no other machine can ever produce\n * evidence about its pids.\n *\n * Two limits are inherent to asking a pid, and they bound what reclaim can\n * promise. Both are shared with `HostLiveness.isAlive`.\n *\n * - An owner recorded with the CLAIMANT'S OWN pid is always alive. A previous\n *   incarnation of this process, or a second engine composed inside it, differs\n *   from the claimant only by `nonce`, and the process it names is this one.\n *   Such a row is never stolen while the process lives, so an embedded host\n *   that re-creates its engine in place should keep {@link leaseLiveness},\n *   whose timeout does expire. Reading same-pid-different-nonce as death is\n *   not the alternative: it would let two engines in one process — the exact\n *   shape this check exists to arbitrate — steal each other's live runs.\n * - A pid the operating system has REUSED reports the unrelated process that\n *   now holds it. The dead owner's row stays refused for as long as that\n *   process lives, which delays reclaim rather than breaking it: the row is\n *   still `running` under an expired lease, and the next probe after the pid\n *   is free reclaims it.\n *\n * @since 0.1.0\n * @category ownership\n */\nexport const sameHostPidProbe: LivenessCheck = (expectedOwner, context) =>\n  Effect.sync(() => {\n    if (!sameHostIncarnation(expectedOwner, context.claimant)) return false\n    if (!Number.isSafeInteger(expectedOwner.pid) || expectedOwner.pid <= 0) return true\n    try {\n      process.kill(expectedOwner.pid, 0)\n      return true\n    } catch (error) {\n      return (error as { readonly code?: string | undefined } | null)?.code !== \"ESRCH\"\n    }\n  })\n\nexport {\n  /**\n   * How often the supervision loop pulses to renew the owner's lease.\n   *\n   * @since 0.1.0\n   * @category constants\n   */\n  heartbeatInterval,\n  /**\n   * How far the owner's wall clock may run behind a peer's before the lease\n   * reasoning stops holding.\n   *\n   * @since 0.1.0\n   * @category constants\n   */\n  heartbeatSkewAllowance,\n  /**\n   * How old a persisted heartbeat must be before a peer may steal the run.\n   *\n   * @since 0.1.0\n   * @category constants\n   */\n  heartbeatStaleAfter,\n  /**\n   * How long the owner may keep working through failing or stalled heartbeat writes.\n   *\n   * @since 0.1.0\n   * @category constants\n   */\n  heartbeatWriteTolerance\n} from \"./Heartbeat.ts\"\n\n/**\n * Hooks a {@link heartbeatLoop} caller may supply.\n *\n * @since 1.0.0\n * @category models\n */\nexport interface HeartbeatLoopOptions {\n  /** Called after the same unclaimed owner reconfirms an expired heartbeat budget. */\n  readonly onReconfirm?: ((unconfirmedMs: number) => Effect.Effect<void>) | undefined\n  /** Called with the unconfirmed milliseconds when the lease lapses, before the loop interrupts itself. */\n  readonly onLapse?: ((unconfirmedMs: number) => Effect.Effect<void>) | undefined\n}\n\n/**\n * Runs heartbeats until the persisted ownership fence is lost, then interrupts\n * itself. Race this effect with owned work so structured concurrency\n * interrupts the work when ownership disappears.\n *\n * Each pulse drives the injected `Consensus` strategy's `heartbeat` through\n * `RunStore.heartbeat`, which renews the strategy's lease and mirrors the\n * recorded stamp onto the run row in the same transaction. Heartbeats are\n * lease evidence, never journal events.\n *\n * Pulses are delayed by `heartbeatInterval` and read the Effect `Clock`, so the\n * loop is fully driveable with `TestClock`.\n *\n * A lost fence — any outcome other than `Updated` — is durable evidence and\n * interrupts immediately. A failed heartbeat *write* is not: the persisted\n * heartbeat is still there and no other process may steal the run until it is\n * `heartbeatStaleAfter` old, so transient write errors are tolerated for\n * `heartbeatWriteTolerance` — deliberately shorter than the steal cutoff by a\n * pulse plus `heartbeatSkewAllowance`. The reserved pulse bounds a final\n * reconfirmation; a pending claim or changed owner fails that check. Past that allowance\n * the fence still protects durable writes but non-durable side effects may\n * overlap; see {@link heartbeatWriteTolerance}.\n *\n * An independent deadline races the pulse loop. At expiry it reconfirms the\n * same owner with no pending claim, bounded by one heartbeat interval. A\n * renewed lease continues supervision; loss, error, or timeout interrupts\n * even when an ordinary heartbeat write never returns. Each successful\n * pulse re-arms the deadline from the timestamp sent to the store, not from\n * its completion time. The deadline re-reads the clock after waking, so delayed\n * writes cannot hide expiry behind a stale clock reading.\n *\n * `options.onReconfirm` records a successful reconfirmation after a gap. Its\n * deadline is the remaining renewed lease budget, measured from the timestamp\n * sent to the store. A blocked or failed receipt lapses the lease instead of\n * stranding supervision; receipt completion never grants another lease budget.\n * `options.onLapse` runs once, before the self-interrupt, when reconfirmation\n * fails: it receives how long the lease went unconfirmed, so the caller can\n * record why its work stopped. A lost fence does not call it.\n *\n * @since 0.1.0\n * @category supervision\n */\nexport const heartbeatLoop = (\n  runId: string,\n  owner: OwnerId,\n  options: HeartbeatLoopOptions = {}\n): Effect.Effect<never, never, RunStore> =>\n  Effect.gen(function*() {\n    const runStore = yield* RunStore\n    const toleranceMs = Duration.toMillis(heartbeatWriteTolerance)\n    const intervalMs = Duration.toMillis(heartbeatInterval)\n    let lastConfirmedPulseMs = yield* Clock.currentTimeMillis\n    let failing = false\n    // Both overdue timers may wake after a host stall. Serialize expiry and\n    // recheck the budget so they cannot reconfirm or journal the same gap twice.\n    const expiry = yield* Semaphore.make(1)\n    const expire = () =>\n      expiry.withPermit(Effect.gen(function*() {\n        // A competing expiry may have held the permit across a write. Take\n        // fresh evidence after acquisition, never the waiting timer's reading.\n        const nowMs = yield* Clock.currentTimeMillis\n        if (nowMs - lastConfirmedPulseMs < toleranceMs) return\n        const unconfirmedMs = nowMs - lastConfirmedPulseMs\n        const renewed = yield* runStore.reconfirm(runId, owner, Math.floor(nowMs)).pipe(\n          // Only the ownership check consumes the old lease's reserved pulse.\n          Effect.timeout(heartbeatInterval),\n          Effect.flatMap((outcome) =>\n            Effect.gen(function*() {\n              if (outcome._tag !== \"Updated\") return false\n              lastConfirmedPulseMs = Math.max(lastConfirmedPulseMs, Math.floor(nowMs))\n              failing = false\n              const confirmedAtMs = yield* Clock.currentTimeMillis\n              const remainingMs = lastConfirmedPulseMs + toleranceMs - confirmedAtMs\n              if (remainingMs <= 0) return false\n              // The receipt is still required and bounded, but ownership was\n              // already renewed. Spending only its old reserved pulse would\n              // interrupt live work despite a fresh, fenced persisted lease.\n              yield* (options.onReconfirm?.(unconfirmedMs) ?? Effect.void).pipe(Effect.timeout(remainingMs))\n              return true\n            })\n          ),\n          Effect.catchCause((cause) =>\n            Cause.hasInterruptsOnly(cause) ? Effect.failCause(cause as Cause.Cause<never>) : Effect.succeed(false)\n          )\n        )\n        if (renewed) return\n        yield* Effect.logWarning(\"run lease lapsed; interrupting owned work\").pipe(\n          Effect.annotateLogs({ runId, unconfirmedMs }),\n          Effect.andThen(options.onLapse?.(unconfirmedMs) ?? Effect.void),\n          Effect.andThen(Effect.interrupt)\n        )\n      }))\n    const deadline = Effect.gen(function*() {\n      while (true) {\n        const nowMs = yield* Clock.currentTimeMillis\n        const remainingMs = lastConfirmedPulseMs + toleranceMs - nowMs\n        if (remainingMs <= 0) {\n          yield* expire()\n          continue\n        }\n        // Check alongside pulse intervals, with a shorter final wait when needed.\n        yield* Effect.sleep(Math.min(remainingMs, intervalMs))\n      }\n    })\n    const pulses = Effect.sleep(heartbeatInterval).pipe(\n      Effect.andThen(Clock.currentTimeMillis.pipe(Effect.map(Math.floor))),\n      Effect.flatMap((nowMs) =>\n        nowMs - lastConfirmedPulseMs >= toleranceMs ? expire() : runStore.heartbeat(runId, owner, nowMs).pipe(\n          Effect.flatMap((outcome) =>\n            outcome._tag === \"Updated\"\n              ? Effect.sync(() => {\n                lastConfirmedPulseMs = Math.max(lastConfirmedPulseMs, nowMs)\n                failing = false\n              })\n              : Effect.interrupt\n          ),\n          // A failed write keeps the confirmed lease; the independent deadline\n          // supervises its expiry. Warn on the first failure of an outage.\n          Effect.catch((error) => {\n            if (failing) return Effect.void\n            failing = true\n            return Effect.logWarning(\"run heartbeat write failed\").pipe(\n              Effect.annotateLogs({ runId, code: error.code })\n            )\n          })\n        )\n      ),\n      Effect.forever\n    )\n    return yield* Effect.raceFirst(pulses, deadline)\n  })\n"]}