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

package/dist/esm/RunStore.js

@@ -0,0 +1,1287 @@
+/**
+ * Fenced run persistence and ownership compare-and-swap operations.
+ *
+ * Operations that accept or verify `LivenessEvidence` (`claim`,
+ * `claimAndOwn`, `steal`, `heartbeat`, `requestCancel`, and `recoverClaim`)
+ * take the caller's `nowMs` and judge it literally, including the lease cutoff
+ * and exact `evidence.checkedAtMs === nowMs` rule. The lease operations
+ * (`claim`, `claimAndOwn`, `steal`, `heartbeat`, and `recoverClaim`) also
+ * refuse a `nowMs` that runs ahead of the injected Effect `Clock` by more than
+ * `heartbeatSkewAllowance`: no composition produces one honestly, because the
+ * caller and the store share a process, and such a reading is the one lever
+ * that steals a fresh owner or pins a lease past the cutoff. A reading behind
+ * the clock is admitted, since it only makes staleness judgments more
+ * conservative and the monotonic heartbeat absorbs it. `requestCancel` keeps
+ * the literal reading because its timestamp is request data, never a lease
+ * predicate. Lifecycle stamps use the Effect `Clock`: `create` writes
+ * `created_at_ms`, `activate` writes `started_at_ms` and `heartbeat_at_ms`,
+ * and `transitionOwned` writes `finished_at_ms`. A row can therefore carry
+ * readings from two clocks. Within the allowance the store trusts the caller's
+ * clock, which is right for an in-process library over local SQLite and must
+ * not cross a trust boundary.
+ *
+ * Arbitration itself — who holds the claim, who holds the lease, whether the
+ * fence still stands — is delegated to `@smthrs/journal`'s injected
+ * `Consensus` strategy. The run row mirrors the strategy's answer in the same
+ * write transaction, and every ownership transition the strategy grants is
+ * appended to the run's `run-store` companion journal stream in that
+ * transaction (see {@link OwnershipTransition}); heartbeats renew the lease
+ * and never enter the journal.
+ *
+ * @since 0.1.0
+ */
+import * as Dialect from "@smthrs/database/Dialect";
+import { afterCommit, DatabaseError, DurableWriter, fromSqlError } from "@smthrs/database/DurableWriter";
+import { Consensus, matchesEvidence, sameOwner } from "@smthrs/journal/Consensus";
+import { isCompanionRunId } from "@smthrs/journal/JournalEvent";
+import { OwnerId } from "@smthrs/journal/OwnerId";
+import * as SqlConsensus from "@smthrs/journal/SqlConsensus";
+import * as ObservabilityMetric from "@smthrs/observability/Metric";
+import { Clock, Context, Duration, Effect, Layer, Metric, Schema } from "effect";
+import * as SqlClient from "effect/unstable/sql/SqlClient";
+import { heartbeatSkewAllowance, heartbeatStaleAfter } from "./Heartbeat.js";
+import * as Boundary from "./internal/Boundary.js";
+import * as Companion from "./internal/Companion.js";
+import { observeExit, observeOutcome } from "./internal/SpanOutcome.js";
+import * as RunStoreMetrics from "./RunStoreMetrics.js";
+/** JSON text carrying an arbitrary decoded value. */
+const UnknownFromJsonString = Schema.fromJsonString(Schema.Unknown);
+/**
+ * A UTF-16 surrogate without its partner. The journal uses the same ES2022
+ * compatible check because `String.prototype.isWellFormed` needs ES2024.
+ */
+const loneSurrogate = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+/** A non-empty identifier whose UTF-16 encoding survives SQLite unchanged. */
+const wellFormedIdentifier = (value) => value.length > 0 && !loneSurrogate.test(value);
+const NonNegativeSafeInt = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0), Schema.isLessThanOrEqualTo(Number.MAX_SAFE_INTEGER));
+const durableIdentifier = Schema.NonEmptyString.check(Schema.isMaxLength(Boundary.maximumIdentifierLength), Schema.makeFilter((value) => wellFormedIdentifier(value) && Boundary.isDurableText(value), { title: "durableIdentifier" }));
+/**
+ * Maximum nesting admitted for executable run state.
+ *
+ * @since 1.0.0-rc.0
+ * @category constants
+ */
+export const maximumRunJsonDepth = 128;
+/**
+ * Maximum values and members admitted for executable run state.
+ *
+ * @since 1.0.0-rc.0
+ * @category constants
+ */
+export const maximumRunJsonNodes = 100_000;
+const runJsonLimits = {
+    maxDepth: maximumRunJsonDepth,
+    maxMembers: maximumRunJsonNodes,
+    maxNodes: maximumRunJsonNodes
+};
+/**
+ * Stable run states understood by the durability layer.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export const RunStatus = Schema.Literals([
+    "pending",
+    "running",
+    "suspended",
+    "completed",
+    "failed",
+    "cancelled"
+]);
+/**
+ * The run states a run never leaves.
+ *
+ * Named because two rules are written against exactly this set: a settled run
+ * refuses new cancellation intent ({@link RequestCancelOutcome}), and a
+ * settled row is never claimed, activated, or swept.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export const TerminalRunStatus = Schema.Literals(["completed", "failed", "cancelled"]);
+/**
+ * Whether a status is one a run never leaves.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export const isTerminalRunStatus = (status) => status === "completed" || status === "failed" || status === "cancelled";
+/**
+ * Stable failure codes surfaced by `RunStore`.
+ *
+ * @since 0.1.0
+ * @category errors
+ */
+export const RunStoreErrorCode = Schema.Literals([
+    "invalid_run",
+    "not_found_row",
+    "constraint",
+    "decode_failed",
+    "persistence_failed"
+]);
+/**
+ * A normalized run persistence failure.
+ *
+ * Compare-and-swap competition is represented by successful outcome values,
+ * never by this error channel.
+ *
+ * The identity string equals the defining module path, which is how every
+ * tagged identity in this package is named.
+ *
+ * @since 0.1.0
+ * @category errors
+ */
+export class RunStoreError extends Schema.TaggedError()("@smthrs/run-store/RunStoreError", {
+    code: RunStoreErrorCode,
+    method: Schema.String,
+    message: Schema.String,
+    cause: Schema.Unknown
+}) {
+}
+/**
+ * An extra compare-and-swap predicate over first-class run metadata.
+ *
+ * A guard is the seam for lifecycle rules a harness must enforce atomically —
+ * `{ cancelRequested: "absent" }` is the "do not finalize a run someone asked
+ * to cancel" rule, expressed as SQL rather than as a read-then-write race.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export const TransitionGuard = Schema.Struct({
+    cancelRequested: Schema.optional(Schema.Literals(["absent", "present"]))
+});
+/**
+ * An ownership transition the consensus strategy granted on a run.
+ *
+ * `claimed` and `stolen` reserve the run for a claimant, `activated` promotes
+ * a claim to ownership, `released` gives a claim or ownership back, and
+ * `expired` clears a dead claimant's stale claim. Each is appended as a
+ * `flows.consensus.<transition>` fact, with payload `{ runId, owner,
+ * grantedAtMs }`, to the run's companion stream
+ * `JournalEvent.companionRunId("run-store", runId)` in the transaction that
+ * made it; a rolled-back transition leaves no fact. Heartbeats are not
+ * transitions and never enter the journal.
+ *
+ * The facts live beside the run's own stream rather than in it, so a consumer
+ * that reads the run's stream by position never sees one, and a rewind or
+ * compaction of that stream never truncates one. They are recorded when the
+ * caller runs with a `Journal` in its context.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export const OwnershipTransition = Schema.Literals(["claimed", "activated", "released", "stolen", "expired"]);
+/**
+ * The name of the run store's journal companion stream: every fact the store
+ * records about a run goes to `JournalEvent.companionRunId(companionStream,
+ * runId)`.
+ *
+ * @since 1.0.0
+ * @category constants
+ */
+export const companionStream = Companion.stream;
+/**
+ * The journal event type an ownership transition is appended under.
+ *
+ * @since 1.0.0
+ * @category constants
+ */
+export const ownershipEventType = (transition) => `flows.consensus.${transition}`;
+/**
+ * Service tag for fenced run persistence.
+ *
+ * The identity string equals the defining module path, which is how every
+ * service in this package is named.
+ *
+ * @since 0.1.0
+ * @category services
+ */
+export class RunStore extends Context.Service()("@smthrs/run-store/RunStore") {
+}
+const claimed = (claimedAtMs) => ({ _tag: "Claimed", claimedAtMs });
+const notFound = { _tag: "NotFound" };
+const alreadyClaimed = { _tag: "AlreadyClaimed" };
+const heartbeatFresh = { _tag: "HeartbeatFresh" };
+const snapshotChanged = { _tag: "SnapshotChanged" };
+const evidenceRequired = { _tag: "EvidenceRequired" };
+const activated = { _tag: "Activated" };
+const claimLost = { _tag: "ClaimLost" };
+const abandoned = { _tag: "Abandoned" };
+const recovered = { _tag: "Recovered" };
+const claimFresh = { _tag: "ClaimFresh" };
+const claimChanged = { _tag: "ClaimChanged" };
+const livenessUnconfirmed = { _tag: "LivenessUnconfirmed" };
+const updated = { _tag: "Updated" };
+const fenceLost = { _tag: "FenceLost" };
+const transitioned = { _tag: "Transitioned" };
+const guardFailed = { _tag: "GuardFailed" };
+/**
+ * The staleness cutoff in milliseconds, derived from the one definition rather
+ * than restated. `Ownership` imports `RunStore`, so the shared constants live
+ * in the `Heartbeat` leaf both can reach.
+ */
+const heartbeatStaleAfterMs = Duration.toMillis(heartbeatStaleAfter);
+const heartbeatSkewAllowanceMs = Duration.toMillis(heartbeatSkewAllowance);
+const terminalStatuses = new Set(["completed", "failed", "cancelled"]);
+const DatabaseRunRow = Schema.Struct({
+    runId: durableIdentifier,
+    status: RunStatus,
+    createdAtMs: NonNegativeSafeInt,
+    startedAtMs: Schema.NullOr(NonNegativeSafeInt),
+    finishedAtMs: Schema.NullOr(NonNegativeSafeInt),
+    ownerHostId: Schema.NullOr(durableIdentifier),
+    ownerPid: Schema.NullOr(NonNegativeSafeInt),
+    ownerNonce: Schema.NullOr(durableIdentifier),
+    heartbeatAtMs: Schema.NullOr(NonNegativeSafeInt),
+    claimHostId: Schema.NullOr(durableIdentifier),
+    claimPid: Schema.NullOr(NonNegativeSafeInt),
+    claimNonce: Schema.NullOr(durableIdentifier),
+    claimedAtMs: Schema.NullOr(NonNegativeSafeInt),
+    parentRunId: Schema.NullOr(durableIdentifier),
+    cancelRequestedAtMs: Schema.NullOr(NonNegativeSafeInt),
+    lineageId: Schema.NullOr(durableIdentifier),
+    roundOrdinal: Schema.NullOr(NonNegativeSafeInt),
+    stateJson: Schema.String
+});
+const runStoreError = (method, code, message, cause) => new RunStoreError({
+    code,
+    method,
+    message: `${code}: RunStore.${method}: ${message}`,
+    cause
+});
+/**
+ * The normalized database failure behind a strategy or journal failure, found
+ * by following `cause` chains the way the durable writer's retry
+ * classification does. A wrapper that carries no database failure at all —
+ * a closed journal, say — has no category to report.
+ */
+const databaseFailure = (cause) => {
+    let current = cause;
+    for (let depth = 0; depth < 8 && typeof current === "object" && current !== null; depth++) {
+        if (current instanceof DatabaseError)
+            return current;
+        current = current.cause;
+    }
+    return undefined;
+};
+const persistenceError = (method, cause) => {
+    if (Schema.is(RunStoreError)(cause))
+        return cause;
+    const database = cause instanceof DatabaseError ? cause : databaseFailure(cause.cause);
+    const code = database?.code === "constraint"
+        ? "constraint"
+        : "persistence_failed";
+    return runStoreError(method, code, "database operation failed", {
+        category: code,
+        // Keep the classification for outer transaction retries, never driver
+        // causes that may contain executable state or bound SQL values.
+        cause: new DatabaseError({ code: database?.code ?? "unknown" })
+    });
+};
+const invalidRunError = (method, causeOrField, detail = "violates the durable contract") => runStoreError(method, "invalid_run", "run input is invalid", typeof causeOrField === "string" ? { field: causeOrField, detail } : causeOrField);
+const stateAdmission = (value) => Boundary.admitJsonText(value, runJsonLimits);
+const isJsonString = (value) => Schema.decodeUnknownResult(UnknownFromJsonString)(value)._tag === "Success";
+const validOwner = (value) => Schema.is(OwnerId)(value) &&
+    Boundary.isDurableText(value.hostId) &&
+    Boundary.isDurableText(value.nonce) &&
+    Number.isSafeInteger(value.pid) &&
+    value.pid >= 0;
+/** Caller timestamps are SQLite-safe, non-negative integer millisecond readings. */
+const validTimestamp = (value) => Number.isSafeInteger(value) && value >= 0;
+const inertRecord = (input, allowed) => {
+    if (typeof input !== "object" || input === null)
+        return undefined;
+    try {
+        const prototype = Object.getPrototypeOf(input);
+        if (prototype !== Object.prototype && prototype !== null)
+            return undefined;
+        const fields = Object.create(null);
+        for (const key of Reflect.ownKeys(input)) {
+            const descriptor = Object.getOwnPropertyDescriptor(input, key);
+            if (descriptor === undefined || !descriptor.enumerable)
+                continue;
+            if (!("value" in descriptor) || (allowed !== undefined && (typeof key !== "string" || !allowed.has(key)))) {
+                return undefined;
+            }
+            if (typeof key === "string")
+                fields[key] = descriptor.value;
+        }
+        return fields;
+    }
+    catch {
+        return undefined;
+    }
+};
+const snapshotOwner = (method, field, input) => Effect.suspend(() => {
+    const fields = inertRecord(input, new Set(["hostId", "pid", "nonce"]));
+    if (fields === undefined) {
+        return Effect.fail(invalidRunError(method, field, "must be an inert owner record"));
+    }
+    const owner = Object.freeze({
+        hostId: fields.hostId,
+        pid: fields.pid,
+        nonce: fields.nonce
+    });
+    return validOwner(owner)
+        ? Effect.succeed(owner)
+        : Effect.fail(invalidRunError(method, field, "must be a valid owner identity"));
+});
+const snapshotRunId = (method, input) => typeof input === "string" && wellFormedIdentifier(input) && Boundary.isDurableText(input)
+    ? Effect.succeed(input)
+    : Effect.fail(invalidRunError(method, "runId", "must be well-formed durable text"));
+const snapshotTimestamp = (method, field, input) => typeof input === "number" && validTimestamp(input)
+    ? Effect.succeed(input)
+    : Effect.fail(invalidRunError(method, field, "must be a non-negative safe integer"));
+/**
+ * Admits a caller's lease reading. Once admitted the reading is authoritative:
+ * it is the cutoff the lease predicate compares against and the stamp the row
+ * keeps. The store refuses only a reading that runs ahead of its own `Clock`
+ * by more than `heartbeatSkewAllowance`, because no composition produces one
+ * honestly (the caller and the store share a process) and it is the one lever
+ * that steals a fresh owner or pins a lease past the cutoff. A reading behind
+ * the clock is admitted: it makes every staleness judgment more conservative,
+ * and `heartbeat`'s monotonic write absorbs it.
+ */
+const snapshotLeaseReading = (method, field, input, cause) => Effect.gen(function* () {
+    const nowMs = yield* snapshotTimestamp(method, field, input);
+    const clockMs = yield* Clock.currentTimeMillis.pipe(Effect.map(Math.floor));
+    if (nowMs > clockMs + heartbeatSkewAllowanceMs) {
+        return yield* Effect.fail(invalidRunError(method, {
+            ...cause,
+            field,
+            nowMs,
+            clockMs,
+            detail: "runs ahead of the store clock by more than the heartbeat skew allowance"
+        }));
+    }
+    return nowMs;
+});
+const snapshotState = (method, input, cause) => {
+    const admitted = stateAdmission(input);
+    return admitted.ok
+        ? Effect.succeed(admitted.value)
+        : Effect.fail(invalidRunError(method, cause, admitted.complaint));
+};
+const snapshotCreateOptions = (input) => Effect.suspend(() => {
+    const value = input ?? {};
+    const fields = inertRecord(value, new Set(["parentRunId", "lineageId", "roundOrdinal"]));
+    if (fields === undefined) {
+        return Effect.fail(invalidRunError("create", "options", "must be an inert data record"));
+    }
+    const rawParent = fields.parentRunId;
+    const rawLineage = fields.lineageId;
+    const rawRound = fields.roundOrdinal;
+    const parentRunId = rawParent === undefined ? null : rawParent;
+    const lineageId = rawLineage === undefined ? null : rawLineage;
+    const roundOrdinal = rawRound === undefined ? null : rawRound;
+    if ((parentRunId !== null &&
+        (typeof parentRunId !== "string" ||
+            !wellFormedIdentifier(parentRunId) ||
+            !Boundary.isDurableText(parentRunId))) ||
+        (lineageId !== null &&
+            (typeof lineageId !== "string" ||
+                !wellFormedIdentifier(lineageId) ||
+                !Boundary.isDurableText(lineageId))) ||
+        (roundOrdinal !== null && (typeof roundOrdinal !== "number" || !validTimestamp(roundOrdinal))) ||
+        (lineageId === null) !== (roundOrdinal === null))
+        return Effect.fail(invalidRunError("create", "options", "contains invalid ancestry or lineage"));
+    return Effect.succeed(Object.freeze({ parentRunId, lineageId, roundOrdinal }));
+});
+/**
+ * Structural admission for a value typed as a required-field record. `RunRow`
+ * extends `RunSnapshot`, so a row from `get` must pass wherever an expected
+ * snapshot is typed: extra own data fields are ignored, while a non-plain
+ * prototype, any enumerable accessor, or a missing or inherited required field
+ * is still refused. The required fields come from one guarded own-descriptor snapshot.
+ */
+const inertFields = (input, required) => {
+    const fields = inertRecord(input);
+    return fields !== undefined && required.every((key) => Object.hasOwn(fields, key)) ? fields : undefined;
+};
+const snapshotExpected = (method, input) => Effect.gen(function* () {
+    const fields = inertFields(input, ["status", "owner", "heartbeatAtMs"]);
+    if (fields === undefined) {
+        return yield* Effect.fail(invalidRunError(method, "expected", "must be an inert snapshot record"));
+    }
+    const status = fields.status;
+    const rawOwner = fields.owner;
+    const heartbeatAtMs = fields.heartbeatAtMs;
+    if (!Schema.is(RunStatus)(status) ||
+        (heartbeatAtMs !== null && (typeof heartbeatAtMs !== "number" || !validTimestamp(heartbeatAtMs)))) {
+        return yield* Effect.fail(invalidRunError(method, "expected", "contains an invalid status or heartbeat"));
+    }
+    const owner = rawOwner === null ? null : yield* snapshotOwner(method, "expected.owner", rawOwner);
+    if (status === "running") {
+        if (owner === null || heartbeatAtMs === null) {
+            return yield* Effect.fail(invalidRunError(method, "expected", "violates ownership invariants"));
+        }
+        return Object.freeze({ status, owner, heartbeatAtMs });
+    }
+    else {
+        if (owner !== null || heartbeatAtMs !== null) {
+            return yield* Effect.fail(invalidRunError(method, "expected", "violates ownership invariants"));
+        }
+        return Object.freeze({ status, owner, heartbeatAtMs });
+    }
+});
+const snapshotEvidence = (method, input) => Effect.gen(function* () {
+    const fields = inertRecord(input, new Set(["expectedOwner", "checkedAtMs", "kind"]));
+    if (fields === undefined) {
+        return yield* Effect.fail(invalidRunError(method, "evidence", "must be an inert evidence record"));
+    }
+    const expectedOwner = yield* snapshotOwner(method, "evidence.expectedOwner", fields.expectedOwner);
+    const checkedAtMs = yield* snapshotTimestamp(method, "evidence.checkedAtMs", fields.checkedAtMs);
+    const kind = fields.kind;
+    if (kind !== "same-host-pid-dead" &&
+        kind !== "cross-host-unreachable-stale" &&
+        kind !== "lease-expired")
+        return yield* Effect.fail(invalidRunError(method, "evidence.kind"));
+    return Object.freeze({ expectedOwner, checkedAtMs, kind });
+});
+const snapshotGuard = (input) => Effect.suspend(() => {
+    if (input === undefined)
+        return Effect.succeed(undefined);
+    const fields = inertRecord(input, new Set(["cancelRequested"]));
+    if (fields === undefined) {
+        return Effect.fail(invalidRunError("transitionOwned", "guard", "must be an inert exact guard"));
+    }
+    const cancelRequested = fields.cancelRequested;
+    if (cancelRequested !== undefined && cancelRequested !== "absent" && cancelRequested !== "present") {
+        return Effect.fail(invalidRunError("transitionOwned", "guard.cancelRequested"));
+    }
+    return Effect.succeed(Object.freeze(cancelRequested === undefined ? {} : { cancelRequested }));
+});
+const ownerFromColumns = (hostId, pid, nonce) => {
+    if (hostId === null && pid === null && nonce === null)
+        return null;
+    if (hostId !== null && pid !== null && nonce !== null) {
+        // DatabaseRunRow already admitted all three columns through the stricter
+        // durable identifier and safe-integer schemas.
+        return Object.freeze({ hostId, pid, nonce });
+    }
+    return undefined;
+};
+const rowMatchesClaim = (row, claimant, claimedAtMs) => row.claimHostId === claimant.hostId &&
+    row.claimPid === claimant.pid &&
+    row.claimNonce === claimant.nonce &&
+    row.claimedAtMs === claimedAtMs;
+/**
+ * The exact predicate the ownership compare-and-swap used to compile into its
+ * UPDATE, evaluated in the serialized write transaction instead: the row must
+ * still match the caller's expected snapshot.
+ */
+const rowMatchesSnapshot = (row, expected) => row.status === expected.status &&
+    row.ownerHostId === (expected.owner?.hostId ?? null) &&
+    row.ownerPid === (expected.owner?.pid ?? null) &&
+    row.ownerNonce === (expected.owner?.nonce ?? null) &&
+    row.heartbeatAtMs === expected.heartbeatAtMs;
+const rowOwnedBy = (row, owner) => row.status === "running" &&
+    row.ownerHostId === owner.hostId &&
+    row.ownerPid === owner.pid &&
+    row.ownerNonce === owner.nonce;
+const claimColumnsFree = (row) => row.claimHostId === null && row.claimPid === null && row.claimNonce === null && row.claimedAtMs === null;
+const decodeRunRow = (method, runId, input) => Schema.decodeUnknownEffect(DatabaseRunRow)(input).pipe(Effect.mapError(() => runStoreError(method, "decode_failed", "could not decode flows_runs row", { runId, stage: "row-schema" })), Effect.flatMap((row) => {
+    const owner = ownerFromColumns(row.ownerHostId, row.ownerPid, row.ownerNonce);
+    const claim = ownerFromColumns(row.claimHostId, row.claimPid, row.claimNonce);
+    const admittedState = stateAdmission(row.stateJson);
+    const stateJsonValid = isJsonString(row.stateJson);
+    const invalidOwner = owner === undefined ||
+        (owner === null && row.heartbeatAtMs !== null) ||
+        (owner !== null && row.heartbeatAtMs === null) ||
+        (row.status === "running" ? owner === null : owner !== null);
+    const invalidClaim = claim === undefined ||
+        (claim === null && row.claimedAtMs !== null) ||
+        (claim !== null && row.claimedAtMs === null);
+    if (invalidOwner || invalidClaim || !admittedState.ok) {
+        // The cause is published to logs, spans, and telemetry. Executable
+        // state may carry credentials, so report only the invariants read here.
+        return Effect.fail(runStoreError(method, "decode_failed", "flows_runs row violates durable invariants", {
+            runId,
+            status: row.status,
+            heartbeatAtMs: row.heartbeatAtMs,
+            claimedAtMs: row.claimedAtMs,
+            hasClaimColumns: row.claimHostId !== null || row.claimPid !== null || row.claimNonce !== null,
+            hasOwnerColumns: row.ownerHostId !== null || row.ownerPid !== null || row.ownerNonce !== null,
+            stateJsonValid
+        }));
+    }
+    return Effect.succeed(Object.freeze({
+        runId: row.runId,
+        status: row.status,
+        createdAtMs: row.createdAtMs,
+        startedAtMs: row.startedAtMs,
+        finishedAtMs: row.finishedAtMs,
+        owner,
+        heartbeatAtMs: row.heartbeatAtMs,
+        claim,
+        claimedAtMs: row.claimedAtMs,
+        parentRunId: row.parentRunId,
+        cancelRequestedAtMs: row.cancelRequestedAtMs,
+        lineageId: row.lineageId,
+        roundOrdinal: row.roundOrdinal,
+        stateJson: row.stateJson
+    }));
+}));
+/**
+ * Rows that belong to the logical run containing `runId`: every round that
+ * names the resolved lineage, plus the root itself when its own lineage
+ * columns are null or name that lineage. A same-named run in an independent
+ * lineage is excluded. Shared by every lineage read and write so membership
+ * cannot drift between them.
+ */
+const lineageMembership = (sql, runId) => sql `(
+    lineage_id = (SELECT COALESCE(lineage_id, run_id) FROM flows_runs WHERE run_id = ${runId})
+    OR (
+      run_id = (SELECT COALESCE(lineage_id, run_id) FROM flows_runs WHERE run_id = ${runId})
+      AND (
+        lineage_id IS NULL
+        OR lineage_id = (SELECT COALESCE(lineage_id, run_id) FROM flows_runs WHERE run_id = ${runId})
+      )
+    )
+  )`;
+/**
+ * Names the outcome of a guarded cancellation UPDATE that matched nothing.
+ *
+ * `rows` are the lineage members in round order; an absent set is `NotFound`.
+ * Status is read before the request column, so a settled run reports how it
+ * ended even when its own closing request is still on the row. A live
+ * unrequested row cannot survive the UPDATE inside one serialized writer
+ * transaction, so it is a persistence invariant failure rather than a retry.
+ */
+const classifyCancellationMiss = (method, runId, rows) => Effect.gen(function* () {
+    let outcome = notFound;
+    for (const row of rows) {
+        const status = yield* Schema.decodeUnknownEffect(RunStatus)(row.status).pipe(Effect.mapError((cause) => runStoreError(method, "decode_failed", "could not decode flows_runs status", cause)));
+        if (isTerminalRunStatus(status)) {
+            // A terminal predecessor never hides a live round's request.
+            if (outcome._tag !== "AlreadyRequested")
+                outcome = { _tag: "Terminal", status };
+            continue;
+        }
+        if (row.requestedAtMs === null) {
+            return yield* Effect.fail(runStoreError(method, "persistence_failed", "guarded cancellation update missed a live unrequested row", {
+                runId,
+                stage: "write-invariant"
+            }));
+        }
+        outcome = { _tag: "AlreadyRequested", requestedAtMs: Number(row.requestedAtMs) };
+    }
+    return outcome;
+});
+const selectRun = (sql, runId, mode = "single") => sql `
+    SELECT
+      run_id AS "runId",
+      status AS "status",
+      created_at_ms AS "createdAtMs",
+      started_at_ms AS "startedAtMs",
+      finished_at_ms AS "finishedAtMs",
+      owner_host_id AS "ownerHostId",
+      owner_pid AS "ownerPid",
+      owner_nonce AS "ownerNonce",
+      heartbeat_at_ms AS "heartbeatAtMs",
+      claim_host_id AS "claimHostId",
+      claim_pid AS "claimPid",
+      claim_nonce AS "claimNonce",
+      claimed_at_ms AS "claimedAtMs",
+      parent_run_id AS "parentRunId",
+      cancel_requested_at_ms AS "cancelRequestedAtMs",
+      lineage_id AS "lineageId",
+      round_ordinal AS "roundOrdinal",
+      state_json AS "stateJson"
+    FROM flows_runs
+    WHERE ${mode === "latest"
+    ? sql `run_id = COALESCE(
+        (SELECT run_id FROM flows_runs
+         WHERE lineage_id = (SELECT COALESCE(lineage_id, run_id) FROM flows_runs WHERE run_id = ${runId})
+         ORDER BY round_ordinal DESC LIMIT 1),
+        (SELECT run_id FROM flows_runs WHERE run_id = ${runId})
+      )`
+    : mode === "lineage"
+        ? lineageMembership(sql, runId)
+        : sql `run_id = ${runId}`}
+    ORDER BY COALESCE(round_ordinal, 0), run_id
+  `;
+const classifyClaimLoss = (row, nowMs) => {
+    if (row === undefined)
+        return notFound;
+    if (row.claimHostId !== null)
+        return alreadyClaimed;
+    if (row.status === "running" &&
+        row.heartbeatAtMs !== null &&
+        row.heartbeatAtMs >= nowMs - heartbeatStaleAfterMs) {
+        return heartbeatFresh;
+    }
+    return snapshotChanged;
+};
+const evidenceMatches = (expected, claimant, checkedAtMs, evidence) => expected.status === "running" &&
+    expected.owner !== null &&
+    matchesEvidence(expected.owner, claimant, checkedAtMs, evidence);
+/**
+ * Constructs the production `RunStore` implementation.
+ *
+ * `state_json` is executable state: it is decoded and re-entered on every
+ * resume, so it is persisted and returned byte-for-byte. Nothing rewrites it
+ * on the way through — a redactor here would silently change what the flow
+ * re-reads (issue #72). `Schema.Redacted` hides inspection but allows schema
+ * JSON encoding by default. Use `Schema.Redacted(Schema.String, {
+ * disallowJsonEncode: true })` to refuse JSON encoding, or exclude credentials
+ * from the persistence schema and store a secret reference resolved from a
+ * secret provider on resume. Publication hygiene belongs on journal-event
+ * and export surfaces.
+ *
+ * `state_json` and `flows_attempts.outcome_json` therefore hold unredacted
+ * run inputs and results, so the run's SQLite file (`.flows/*.db`) must be
+ * handled as a secret store.
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export const make = Effect.gen(function* () {
+    const sql = yield* Effect.service(SqlClient.SqlClient);
+    const writer = yield* DurableWriter;
+    const consensus = yield* Consensus;
+    const write = (method, effect) => writer.write(effect).pipe(Effect.mapError((cause) => persistenceError(method, cause)));
+    /** Appends an ownership transition to the run's companion stream (see {@link OwnershipTransition}). */
+    const recordTransition = (runId, transition, owner, grantedAtMs) => Companion.append(runId, ownershipEventType(transition), {
+        owner: { hostId: owner.hostId, pid: owner.pid, nonce: owner.nonce },
+        grantedAtMs
+    });
+    // A bare SELECT needs no write transaction and no replay; only the error
+    // vocabulary stays shared with `write`.
+    const read = (method, effect) => effect.pipe(Effect.mapError((cause) => persistenceError(method, fromSqlError(cause))));
+    const create = Effect.fn("RunStore.create")((runIdInput, stateInput, optionsInput) => Effect.gen(function* () {
+        const runId = yield* snapshotRunId("create", runIdInput);
+        if (isCompanionRunId(runId)) {
+            return yield* Effect.fail(invalidRunError("create", "runId", "names a reserved journal companion stream"));
+        }
+        const { lineageId, parentRunId, roundOrdinal } = yield* snapshotCreateOptions(optionsInput);
+        // This cause is published to logs, spans, and telemetry. Executable
+        // state may carry credentials, so include its shape but never its text.
+        const stateJson = yield* snapshotState("create", stateInput, {
+            runId,
+            parentRunId,
+            lineageId,
+            roundOrdinal,
+            stateJsonLength: typeof stateInput === "string" ? stateInput.length : null,
+            stateJsonValid: isJsonString(stateInput)
+        });
+        yield* Effect.annotateCurrentSpan({ runId });
+        const createdAtMs = yield* Clock.currentTimeMillis.pipe(Effect.map(Math.floor));
+        yield* write("create", sql `
+            INSERT INTO flows_runs (
+              run_id,
+              status,
+              created_at_ms,
+              started_at_ms,
+              finished_at_ms,
+              owner_host_id,
+              owner_pid,
+              owner_nonce,
+              heartbeat_at_ms,
+              claim_host_id,
+              claim_pid,
+              claim_nonce,
+              claimed_at_ms,
+              parent_run_id,
+              lineage_id,
+              round_ordinal,
+              state_json
+            ) VALUES (
+              ${runId},
+              'pending',
+              ${createdAtMs},
+              NULL,
+              NULL,
+              NULL,
+              NULL,
+              NULL,
+              NULL,
+              NULL,
+              NULL,
+              NULL,
+              NULL,
+              ${parentRunId},
+              ${lineageId},
+              ${roundOrdinal},
+              ${stateJson}
+            )
+          `.pipe(Effect.asVoid));
+    }).pipe(observeExit));
+    const get = Effect.fn("RunStore.get")((runIdInput) => Effect.gen(function* () {
+        const runId = yield* snapshotRunId("get", runIdInput);
+        yield* Effect.annotateCurrentSpan({ runId });
+        const rows = yield* read("get", selectRun(sql, runId));
+        return rows[0] === undefined
+            ? yield* Effect.fail(runStoreError("get", "not_found_row", `run ${runId} was not found`, { runId }))
+            : yield* decodeRunRow("get", runId, rows[0]);
+    }).pipe(observeExit));
+    const lineage = Effect.fn("RunStore.lineage")((runIdInput) => Effect.gen(function* () {
+        const runId = yield* snapshotRunId("lineage", runIdInput);
+        yield* Effect.annotateCurrentSpan({ runId });
+        const rows = yield* read("lineage", selectRun(sql, runId, "lineage"));
+        return yield* Effect.forEach(rows, (row) => decodeRunRow("lineage", row.runId, row));
+    }).pipe(observeExit));
+    const latestRound = Effect.fn("RunStore.latestRound")((runIdInput) => Effect.gen(function* () {
+        const runId = yield* snapshotRunId("latestRound", runIdInput);
+        yield* Effect.annotateCurrentSpan({ runId });
+        const rows = yield* read("latestRound", selectRun(sql, runId, "latest"));
+        return rows[0] === undefined
+            ? yield* Effect.fail(runStoreError("latestRound", "not_found_row", `run ${runId} was not found`, { runId }))
+            : yield* decodeRunRow("latestRound", rows[0].runId, rows[0]);
+    }).pipe(observeExit));
+    const requestCancel = Effect.fn("RunStore.requestCancel")((runIdInput, nowMsInput) => Effect.gen(function* () {
+        const runId = yield* snapshotRunId("requestCancel", runIdInput);
+        const nowMs = yield* snapshotTimestamp("requestCancel", "nowMs", nowMsInput);
+        yield* Effect.annotateCurrentSpan({ runId });
+        return yield* write("requestCancel", Effect.gen(function* () {
+            // The status predicate is part of the compare-and-swap rather than
+            // a read-then-write check: a run that settles between a caller's
+            // read and this UPDATE must lose the write, not race it. The writer
+            // serializes the whole transaction, so a miss is classified by one
+            // read of the same columns and never retried.
+            const rows = yield* sql `
+          UPDATE flows_runs
+          SET cancel_requested_at_ms = ${nowMs}
+          WHERE run_id = ${runId}
+            AND cancel_requested_at_ms IS NULL
+            AND status NOT IN ('completed', 'failed', 'cancelled')
+          RETURNING cancel_requested_at_ms AS "requestedAtMs"
+        `;
+            if (rows[0] !== undefined) {
+                return { _tag: "CancelRequested", requestedAtMs: Number(rows[0].requestedAtMs) };
+            }
+            const current = yield* sql `
+          SELECT cancel_requested_at_ms AS "requestedAtMs", status AS "status"
+          FROM flows_runs WHERE run_id = ${runId}
+        `;
+            return yield* classifyCancellationMiss("requestCancel", runId, current);
+        }));
+    }).pipe(observeOutcome()));
+    const requestCancelLineage = Effect.fn("RunStore.requestCancelLineage")((runIdInput, nowMsInput) => Effect.gen(function* () {
+        const runId = yield* snapshotRunId("requestCancelLineage", runIdInput);
+        const nowMs = yield* snapshotTimestamp("requestCancelLineage", "nowMs", nowMsInput);
+        yield* Effect.annotateCurrentSpan({ runId });
+        return yield* write("requestCancelLineage", Effect.gen(function* () {
+            // One set-based guarded UPDATE over the lineage: cost follows the
+            // members' metadata, never their state payloads, and a settled
+            // history of any length adds no statements.
+            const rows = yield* sql `
+          UPDATE flows_runs
+          SET cancel_requested_at_ms = ${nowMs}
+          WHERE ${lineageMembership(sql, runId)}
+            AND cancel_requested_at_ms IS NULL
+            AND status NOT IN ('completed', 'failed', 'cancelled')
+          RETURNING cancel_requested_at_ms AS "requestedAtMs"
+        `;
+            if (rows[0] !== undefined) {
+                return { _tag: "CancelRequested", requestedAtMs: Number(rows[0].requestedAtMs) };
+            }
+            // A previous request on any live round dominates a terminal
+            // predecessor; otherwise the latest round's ending is reported.
+            const members = yield* sql `
+          SELECT cancel_requested_at_ms AS "requestedAtMs", status AS "status"
+          FROM flows_runs
+          WHERE ${lineageMembership(sql, runId)}
+          ORDER BY COALESCE(round_ordinal, 0), run_id
+        `;
+            return yield* classifyCancellationMiss("requestCancelLineage", runId, members);
+        }));
+    }).pipe(observeOutcome()));
+    const claim = Effect.fn("RunStore.claim")((runIdInput, expectedInput, claimantInput, nowMsInput) => Effect.gen(function* () {
+        const runId = yield* snapshotRunId("claim", runIdInput);
+        const expected = yield* snapshotExpected("claim", expectedInput);
+        const claimant = yield* snapshotOwner("claim", "claimant", claimantInput);
+        const nowMs = yield* snapshotLeaseReading("claim", "nowMs", nowMsInput, { runId });
+        yield* Effect.annotateCurrentSpan({ runId, claimantHostId: claimant.hostId });
+        return yield* write("claim", Effect.gen(function* () {
+            // `claim` never admits a running run, so it needs no staleness
+            // test: `pending` and `suspended` exclude it. `claimAndOwn` is the
+            // method that genuinely needs one, because it does admit `running`.
+            // The snapshot predicate is evaluated inside the serialized write
+            // transaction, so it is exactly the compare-and-swap it replaces.
+            const row = (yield* selectRun(sql, runId))[0];
+            const admissible = row !== undefined &&
+                (row.status === "pending" || row.status === "suspended") &&
+                rowMatchesSnapshot(row, expected) &&
+                claimColumnsFree(row);
+            if (!admissible)
+                return classifyClaimLoss(row, nowMs);
+            const grant = yield* consensus.claim(runId, claimant, nowMs);
+            if (grant._tag === "Rejected") {
+                // The strategy is authoritative: the row admitted what the lease
+                // refused, and the loss is classified from the row exactly as a
+                // failed compare-and-swap always was.
+                return classifyClaimLoss(row, nowMs);
+            }
+            yield* sql `
+          UPDATE flows_runs
+          SET
+            claim_host_id = ${claimant.hostId},
+            claim_pid = ${claimant.pid},
+            claim_nonce = ${claimant.nonce},
+            claimed_at_ms = ${grant.grantedAtMs}
+          WHERE run_id = ${runId}
+        `;
+            yield* recordTransition(runId, "claimed", claimant, grant.grantedAtMs);
+            return claimed(grant.grantedAtMs);
+        }));
+    }).pipe(observeOutcome((outcome) => RunStoreMetrics.claim[outcome._tag], Metric.withAttributes(RunStoreMetrics.claims, { op: "claim" }))));
+    const claimAndOwn = Effect.fn("RunStore.claimAndOwn")((runIdInput, expectedInput, ownerInput, nowMsInput, evidenceInput) => Effect.gen(function* () {
+        const runId = yield* snapshotRunId("claimAndOwn", runIdInput);
+        const expected = yield* snapshotExpected("claimAndOwn", expectedInput);
+        const owner = yield* snapshotOwner("claimAndOwn", "owner", ownerInput);
+        const nowMs = yield* snapshotLeaseReading("claimAndOwn", "nowMs", nowMsInput, { runId });
+        const evidence = evidenceInput === undefined
+            ? undefined
+            : yield* snapshotEvidence("claimAndOwn", evidenceInput);
+        yield* Effect.annotateCurrentSpan({ runId, ownerHostId: owner.hostId });
+        return yield* Effect.suspend(() => {
+            if (expected.status === "running" &&
+                !sameOwner(expected.owner, owner) &&
+                !(evidence !== undefined && evidenceMatches(expected, owner, nowMs, evidence))) {
+                return read("claimAndOwn", selectRun(sql, runId)).pipe(Effect.map((current) => {
+                    const row = current[0];
+                    // Classify the lease before upgrading an unchanged stale
+                    // snapshot. Evidence cannot displace a fresh heartbeat, so
+                    // naming evidence first would advise a retry the SQL must refuse.
+                    const loss = classifyClaimLoss(row, nowMs);
+                    return loss === snapshotChanged && row !== undefined && rowMatchesSnapshot(row, expected)
+                        ? evidenceRequired
+                        : loss;
+                }));
+            }
+            return write("claimAndOwn", Effect.gen(function* () {
+                const row = (yield* selectRun(sql, runId))[0];
+                const admissible = row !== undefined &&
+                    (row.status === "pending" || row.status === "suspended" || row.status === "running") &&
+                    rowMatchesSnapshot(row, expected) &&
+                    claimColumnsFree(row) &&
+                    (row.status !== "running" ||
+                        row.heartbeatAtMs === null ||
+                        row.heartbeatAtMs < nowMs - heartbeatStaleAfterMs);
+                if (!admissible)
+                    return classifyClaimLoss(row, nowMs);
+                const expectedOwner = expected.owner;
+                let grant;
+                let transition = "claimed";
+                if (expectedOwner === null) {
+                    grant = yield* consensus.claim(runId, owner, nowMs);
+                }
+                else if (sameOwner(expectedOwner, owner)) {
+                    // Re-owning one's own stale run: the stale lease is released
+                    // and re-granted under a fresh generation (R4).
+                    yield* consensus.release(runId, owner);
+                    yield* recordTransition(runId, "released", owner, null);
+                    grant = yield* consensus.claim(runId, owner, nowMs);
+                }
+                else {
+                    // Admission above proved the evidence matches, so the steal is
+                    // the strategy's evidence-gated claim.
+                    grant = yield* consensus.steal(runId, owner, nowMs, evidence);
+                    transition = "stolen";
+                }
+                if (grant._tag === "Rejected")
+                    return classifyClaimLoss(row, nowMs);
+                const activation = yield* consensus.activate(runId, owner, grant.grantedAtMs, nowMs);
+                if (activation._tag === "Lost") {
+                    // The strategy revoked the grant it just made — its lease moved
+                    // on under the transaction — so the fresh grant is released and
+                    // the loss classified from the row.
+                    yield* consensus.release(runId, owner);
+                    return classifyClaimLoss(row, nowMs);
+                }
+                yield* recordTransition(runId, transition, owner, grant.grantedAtMs);
+                yield* recordTransition(runId, "activated", owner, grant.grantedAtMs);
+                yield* sql `
+          UPDATE flows_runs
+          SET
+            status = 'running',
+            started_at_ms = COALESCE(started_at_ms, ${nowMs}),
+            finished_at_ms = NULL,
+            owner_host_id = ${owner.hostId},
+            owner_pid = ${owner.pid},
+            owner_nonce = ${owner.nonce},
+            heartbeat_at_ms = ${nowMs}
+          WHERE run_id = ${runId}
+        `;
+                return activated;
+            }));
+        });
+    }).pipe(observeOutcome((outcome) => RunStoreMetrics.claimAndOwn[outcome._tag], Metric.withAttributes(RunStoreMetrics.claims, { op: "claim_and_own" }))));
+    const activate = Effect.fn("RunStore.activate")((runIdInput, claimantInput, claimedAtMsInput, expectedInput) => Effect.gen(function* () {
+        const runId = yield* snapshotRunId("activate", runIdInput);
+        const claimant = yield* snapshotOwner("activate", "claimant", claimantInput);
+        const claimedAtMs = yield* snapshotTimestamp("activate", "claimedAtMs", claimedAtMsInput);
+        const expected = yield* snapshotExpected("activate", expectedInput);
+        yield* Effect.annotateCurrentSpan({ runId, claimantHostId: claimant.hostId });
+        const activatedAtMs = yield* Clock.currentTimeMillis.pipe(Effect.map(Math.floor));
+        return yield* write("activate", Effect.gen(function* () {
+            const row = (yield* selectRun(sql, runId))[0];
+            if (row === undefined || !rowMatchesClaim(row, claimant, claimedAtMs))
+                return claimLost;
+            const clearClaim = sql `
+              UPDATE flows_runs
+              SET
+                claim_host_id = NULL,
+                claim_pid = NULL,
+                claim_nonce = NULL,
+                claimed_at_ms = NULL
+              WHERE run_id = ${runId}
+                AND claim_host_id = ${claimant.hostId}
+                AND claim_pid = ${claimant.pid}
+                AND claim_nonce = ${claimant.nonce}
+                AND claimed_at_ms = ${claimedAtMs}
+            `;
+            if (!rowMatchesSnapshot(row, expected)) {
+                // The claim is intact but the guarded snapshot moved on: clear
+                // the claim, exactly as the compare-and-swap always did, and
+                // release the strategy's matching claim so the two stay aligned.
+                yield* consensus.release(runId, claimant);
+                yield* recordTransition(runId, "released", claimant, claimedAtMs);
+                yield* clearClaim;
+                return snapshotChanged;
+            }
+            const activation = yield* consensus.activate(runId, claimant, claimedAtMs, activatedAtMs);
+            if (activation._tag === "Lost") {
+                // The strategy no longer holds this claim though the row still
+                // shows it; the strategy is authoritative, so the stale claim
+                // columns are cleared and the claim reported lost.
+                yield* clearClaim;
+                return claimLost;
+            }
+            yield* sql `
+              UPDATE flows_runs
+              SET
+                status = 'running',
+                started_at_ms = COALESCE(started_at_ms, ${activatedAtMs}),
+                finished_at_ms = NULL,
+                owner_host_id = ${claimant.hostId},
+                owner_pid = ${claimant.pid},
+                owner_nonce = ${claimant.nonce},
+                heartbeat_at_ms = ${activatedAtMs},
+                claim_host_id = NULL,
+                claim_pid = NULL,
+                claim_nonce = NULL,
+                claimed_at_ms = NULL
+              WHERE run_id = ${runId}
+            `;
+            yield* recordTransition(runId, "activated", claimant, claimedAtMs);
+            return activated;
+        }));
+    }).pipe(observeOutcome((outcome) => RunStoreMetrics.activate[outcome._tag], Metric.withAttributes(RunStoreMetrics.claims, { op: "activate" }))));
+    const abandonClaim = Effect.fn("RunStore.abandonClaim")((runIdInput, claimantInput, claimedAtMsInput) => Effect.gen(function* () {
+        const runId = yield* snapshotRunId("abandonClaim", runIdInput);
+        const claimant = yield* snapshotOwner("abandonClaim", "claimant", claimantInput);
+        const claimedAtMs = yield* snapshotTimestamp("abandonClaim", "claimedAtMs", claimedAtMsInput);
+        yield* Effect.annotateCurrentSpan({ runId, claimantHostId: claimant.hostId });
+        return yield* write("abandonClaim", Effect.gen(function* () {
+            const rows = yield* sql `
+          UPDATE flows_runs
+          SET
+            claim_host_id = NULL,
+            claim_pid = NULL,
+            claim_nonce = NULL,
+            claimed_at_ms = NULL
+          WHERE run_id = ${runId}
+            AND claim_host_id = ${claimant.hostId}
+            AND claim_pid = ${claimant.pid}
+            AND claim_nonce = ${claimant.nonce}
+            AND claimed_at_ms = ${claimedAtMs}
+          RETURNING run_id AS "runId"
+        `;
+            if (rows.length === 0)
+                return claimLost;
+            yield* consensus.release(runId, claimant);
+            yield* recordTransition(runId, "released", claimant, claimedAtMs);
+            return abandoned;
+        }));
+    }).pipe(observeOutcome((outcome) => RunStoreMetrics.abandonClaim[outcome._tag], Metric.withAttributes(RunStoreMetrics.claims, { op: "abandon_claim" }))));
+    const recoverClaim = Effect.fn("RunStore.recoverClaim")((runIdInput, staleClaimantInput, claimedAtMsInput, observerInput, nowMsInput, evidenceInput) => Effect.gen(function* () {
+        const runId = yield* snapshotRunId("recoverClaim", runIdInput);
+        const staleClaimant = yield* snapshotOwner("recoverClaim", "staleClaimant", staleClaimantInput);
+        const claimedAtMs = yield* snapshotTimestamp("recoverClaim", "claimedAtMs", claimedAtMsInput);
+        const observer = yield* snapshotOwner("recoverClaim", "observer", observerInput);
+        const nowMs = yield* snapshotLeaseReading("recoverClaim", "nowMs", nowMsInput, { runId, claimedAtMs });
+        const evidence = yield* snapshotEvidence("recoverClaim", evidenceInput);
+        yield* Effect.annotateCurrentSpan({ runId, observerHostId: observer.hostId });
+        return yield* Effect.suspend(() => {
+            if (!matchesEvidence(staleClaimant, observer, nowMs, evidence)) {
+                return Effect.succeed(livenessUnconfirmed);
+            }
+            return write("recoverClaim", Effect.gen(function* () {
+                const row = (yield* selectRun(sql, runId))[0];
+                if (row === undefined)
+                    return notFound;
+                if (!rowMatchesClaim(row, staleClaimant, claimedAtMs))
+                    return claimChanged;
+                if (claimedAtMs >= nowMs - heartbeatStaleAfterMs)
+                    return claimFresh;
+                const outcome = yield* consensus.recover(runId, staleClaimant, claimedAtMs, observer, nowMs, evidence);
+                if (outcome._tag === "Rejected") {
+                    // The strategy refused what the row admitted: as the strategy
+                    // knows it, the claim has moved on.
+                    return claimChanged;
+                }
+                yield* sql `
+          UPDATE flows_runs
+          SET
+            claim_host_id = NULL,
+            claim_pid = NULL,
+            claim_nonce = NULL,
+            claimed_at_ms = NULL
+          WHERE run_id = ${runId}
+        `;
+                yield* recordTransition(runId, "expired", staleClaimant, claimedAtMs);
+                return recovered;
+            }));
+        });
+    }).pipe(observeOutcome((outcome) => RunStoreMetrics.recoverClaim[outcome._tag], Metric.withAttributes(RunStoreMetrics.claims, { op: "recover_claim" }))));
+    const renewLease = (method) => Effect.fn(`RunStore.${method}`)((runIdInput, ownerInput, nowMsInput) => Effect.gen(function* () {
+        const runId = yield* snapshotRunId(method, runIdInput);
+        const owner = yield* snapshotOwner(method, "owner", ownerInput);
+        const nowMs = yield* snapshotLeaseReading(method, "nowMs", nowMsInput, { runId });
+        yield* Effect.annotateCurrentSpan({ runId, ownerHostId: owner.hostId });
+        return yield* write(method, Effect.gen(function* () {
+            // The pulse drives the strategy's lease renewal; the row mirrors
+            // the stamp the strategy recorded. The lease timestamp is
+            // monotonic: a heartbeat that arrives late — delayed past a newer
+            // one from the same owner — never moves it backwards and never
+            // makes a live run look stale to `claimAndOwn`/`steal`'s cutoff. A
+            // late clock reading still reports `Updated`: the fence held, and
+            // the write proves liveness regardless of which caller clock
+            // reading it carried. Prior art: Temporal's shard `rangeID` only
+            // ever advances (`reference/temporal/service/history/shard/context_impl.go`,
+            // `renewRangeLocked`). Heartbeats never enter the journal.
+            const outcome = yield* consensus[method](runId, owner, nowMs);
+            if (outcome._tag === "Lost") {
+                const current = yield* selectRun(sql, runId);
+                return current.length === 0 ? notFound : fenceLost;
+            }
+            // The mirror write is verified: a renewed lease over a row this
+            // owner no longer holds is a lease/row disagreement, and a success
+            // that wrote nothing would hide it. RETURNING keeps the old row
+            // answer — `FenceLost` when the row moved on, `NotFound` when it
+            // is gone.
+            const rows = yield* sql `
+          UPDATE flows_runs
+          SET heartbeat_at_ms = ${Dialect.greatest(sql)}(heartbeat_at_ms, ${outcome.heartbeatAtMs})
+          WHERE run_id = ${runId}
+            AND status = 'running'
+            AND owner_host_id = ${owner.hostId}
+            AND owner_pid = ${owner.pid}
+            AND owner_nonce = ${owner.nonce}
+          RETURNING run_id AS "runId"
+        `;
+            if (rows.length > 0)
+                return updated;
+            const current = yield* selectRun(sql, runId);
+            return current.length === 0 ? notFound : fenceLost;
+        }));
+    }).pipe(observeOutcome((outcome) => RunStoreMetrics.heartbeat[outcome._tag], RunStoreMetrics.heartbeats)));
+    const heartbeat = renewLease("heartbeat");
+    const reconfirm = renewLease("reconfirm");
+    const transitionOwned = Effect.fn("RunStore.transitionOwned")((runIdInput, ownerInput, toStatusInput, stateInput, guardInput) => Effect.gen(function* () {
+        const runId = yield* snapshotRunId("transitionOwned", runIdInput);
+        const owner = yield* snapshotOwner("transitionOwned", "owner", ownerInput);
+        if (!Schema.is(RunStatus)(toStatusInput) || toStatusInput === "pending") {
+            return yield* Effect.fail(invalidRunError("transitionOwned", "toStatus"));
+        }
+        const toStatus = toStatusInput;
+        const state = stateInput === undefined
+            ? null
+            : yield* snapshotState("transitionOwned", stateInput, {
+                runId,
+                stateJsonLength: typeof stateInput === "string" ? stateInput.length : null,
+                stateJsonValid: isJsonString(stateInput)
+            });
+        const guard = yield* snapshotGuard(guardInput);
+        yield* Effect.annotateCurrentSpan({ runId, ownerHostId: owner.hostId, to: toStatus });
+        const transitionedAtMs = yield* Clock.currentTimeMillis.pipe(Effect.map(Math.floor));
+        const outcome = yield* write("transitionOwned", Effect.gen(function* () {
+            // The fence check is the strategy's guard (R3); the row check keeps
+            // the mirror honest. Both run in the serialized write transaction,
+            // so a concurrent cancellation request or reclaim can never slip
+            // between check and write.
+            const held = yield* consensus.guard(runId, owner).pipe(Effect.as(true), Effect.catch((cause) => cause.code === "fence_lost" ? Effect.succeed(false) : Effect.fail(cause)));
+            const row = (yield* selectRun(sql, runId))[0];
+            if (row === undefined)
+                return notFound;
+            if (!held || !rowOwnedBy(row, owner))
+                return fenceLost;
+            const guardBlocked = (guard?.cancelRequested === "absent" && row.cancelRequestedAtMs !== null) ||
+                (guard?.cancelRequested === "present" && row.cancelRequestedAtMs === null);
+            if (guardBlocked)
+                return guardFailed;
+            if (toStatus === "running") {
+                yield* sql `
+                UPDATE flows_runs
+                SET
+                  status = 'running',
+                  finished_at_ms = NULL,
+                  state_json = COALESCE(${state}, state_json)
+                WHERE run_id = ${runId}
+              `;
+                return transitioned;
+            }
+            yield* sql `
+                UPDATE flows_runs
+                SET
+                  status = ${toStatus},
+                  finished_at_ms = ${terminalStatuses.has(toStatus) ? transitionedAtMs : null},
+                  owner_host_id = NULL,
+                  owner_pid = NULL,
+                  owner_nonce = NULL,
+                  heartbeat_at_ms = NULL,
+                  claim_host_id = NULL,
+                  claim_pid = NULL,
+                  claim_nonce = NULL,
+                  claimed_at_ms = NULL,
+                  state_json = COALESCE(${state}, state_json)
+                WHERE run_id = ${runId}
+              `;
+            yield* consensus.release(runId, owner);
+            yield* recordTransition(runId, "released", owner, null);
+            if (terminalStatuses.has(toStatus)) {
+                yield* afterCommit(Metric.update(ObservabilityMetric.runThroughput, 1), sql);
+            }
+            return transitioned;
+        }));
+        return outcome;
+    }).pipe(observeOutcome((outcome) => Metric.withAttributes(RunStoreMetrics.transition[outcome._tag], {
+        to: toStatusInput
+    }), Metric.withAttributes(RunStoreMetrics.transitions, { to: toStatusInput }))));
+    const steal = Effect.fn("RunStore.steal")((runIdInput, expectedInput, claimantInput, nowMsInput, evidenceInput) => Effect.gen(function* () {
+        const runId = yield* snapshotRunId("steal", runIdInput);
+        const expected = yield* snapshotExpected("steal", expectedInput);
+        const claimant = yield* snapshotOwner("steal", "claimant", claimantInput);
+        const nowMs = yield* snapshotLeaseReading("steal", "nowMs", nowMsInput, { runId });
+        const evidence = yield* snapshotEvidence("steal", evidenceInput);
+        yield* Effect.annotateCurrentSpan({ runId, claimantHostId: claimant.hostId });
+        return yield* Effect.suspend(() => {
+            if (!evidenceMatches(expected, claimant, nowMs, evidence)) {
+                return Effect.succeed(livenessUnconfirmed);
+            }
+            return write("steal", Effect.gen(function* () {
+                const row = (yield* selectRun(sql, runId))[0];
+                const admissible = row !== undefined &&
+                    rowMatchesSnapshot(row, expected) &&
+                    claimColumnsFree(row) &&
+                    row.heartbeatAtMs !== null &&
+                    row.heartbeatAtMs < nowMs - heartbeatStaleAfterMs;
+                if (!admissible)
+                    return classifyClaimLoss(row, nowMs);
+                const grant = yield* consensus.steal(runId, claimant, nowMs, evidence);
+                if (grant._tag === "Rejected") {
+                    // The strategy refused what the row admitted — for example its
+                    // lease still records a fresh heartbeat — and is authoritative.
+                    return classifyClaimLoss(row, nowMs);
+                }
+                yield* sql `
+          UPDATE flows_runs
+          SET
+            claim_host_id = ${claimant.hostId},
+            claim_pid = ${claimant.pid},
+            claim_nonce = ${claimant.nonce},
+            claimed_at_ms = ${grant.grantedAtMs}
+          WHERE run_id = ${runId}
+        `;
+                yield* recordTransition(runId, "stolen", claimant, grant.grantedAtMs);
+                return claimed(grant.grantedAtMs);
+            }));
+        });
+    }).pipe(observeOutcome((outcome) => RunStoreMetrics.steal[outcome._tag], Metric.withAttributes(RunStoreMetrics.claims, { op: "steal" }))));
+    const acknowledgeCancel = Effect.fn("RunStore.acknowledgeCancel")((id, ownerInput, time) => Effect.gen(function* () {
+        const runId = yield* snapshotRunId("acknowledgeCancel", id);
+        const owner = yield* snapshotOwner("acknowledgeCancel", "owner", ownerInput);
+        const observedAtMs = yield* snapshotTimestamp("acknowledgeCancel", "nowMs", time);
+        yield* Effect.annotateCurrentSpan({ runId, ownerHostId: owner.hostId });
+        const acknowledgement = JSON.stringify({ observedAtMs, owner });
+        return yield* write("acknowledgeCancel", sql `
+        UPDATE flows_runs
+        SET cancel_acknowledgement_json = COALESCE(cancel_acknowledgement_json, ${acknowledgement})
+        WHERE run_id = ${runId} AND status = 'running' AND cancel_requested_at_ms IS NOT NULL
+          AND owner_host_id = ${owner.hostId} AND owner_pid = ${owner.pid} AND owner_nonce = ${owner.nonce}
+        RETURNING run_id
+      `.pipe(Effect.map((rows) => rows.length > 0)));
+    }).pipe(observeExit));
+    return RunStore.of({
+        create,
+        get,
+        lineage,
+        latestRound,
+        requestCancel,
+        acknowledgeCancel,
+        requestCancelLineage,
+        claim,
+        claimAndOwn,
+        activate,
+        abandonClaim,
+        recoverClaim,
+        heartbeat,
+        reconfirm,
+        transitionOwned,
+        steal
+    });
+});
+/**
+ * Constructs a stub `RunStore` whose direct operations fail and whose
+ * compare-and-swap operations report typed losses until overridden.
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export const makeNoop = (overrides = {}) => {
+    const unavailable = (method) => Effect.fail(runStoreError(method, "persistence_failed", "no run store in this environment", method));
+    return RunStore.of({
+        create: Effect.fn("RunStore.create")(() => unavailable("create")),
+        get: Effect.fn("RunStore.get")(() => unavailable("get")),
+        lineage: Effect.fn("RunStore.lineage")(() => unavailable("lineage")),
+        latestRound: Effect.fn("RunStore.latestRound")(() => unavailable("latestRound")),
+        requestCancel: Effect.fn("RunStore.requestCancel")(() => Effect.succeed(notFound)),
+        acknowledgeCancel: Effect.fn("RunStore.acknowledgeCancel")(() => Effect.succeed(false)),
+        requestCancelLineage: Effect.fn("RunStore.requestCancelLineage")(() => unavailable("requestCancelLineage")),
+        claim: Effect.fn("RunStore.claim")(() => Effect.succeed(notFound)),
+        claimAndOwn: Effect.fn("RunStore.claimAndOwn")(() => Effect.succeed(notFound)),
+        activate: Effect.fn("RunStore.activate")(() => Effect.succeed(claimLost)),
+        abandonClaim: Effect.fn("RunStore.abandonClaim")(() => Effect.succeed(claimLost)),
+        recoverClaim: Effect.fn("RunStore.recoverClaim")(() => Effect.succeed(notFound)),
+        heartbeat: Effect.fn("RunStore.heartbeat")(() => Effect.succeed(notFound)),
+        reconfirm: Effect.fn("RunStore.reconfirm")(() => Effect.succeed(notFound)),
+        transitionOwned: Effect.fn("RunStore.transitionOwned")(() => Effect.succeed(notFound)),
+        steal: Effect.fn("RunStore.steal")(() => Effect.succeed(notFound)),
+        ...overrides
+    });
+};
+/**
+ * Provides a stub `RunStore`.
+ *
+ * @since 0.1.0
+ * @category layers
+ */
+export const layerNoop = (overrides = {}) => Layer.succeed(RunStore)(makeNoop(overrides));
+/**
+ * Provides the database-backed `RunStore` over an explicitly injected
+ * consensus strategy.
+ *
+ * Arbitration — claims, activation, steals, heartbeats, and fence checks — is
+ * delegated to the `Consensus` service in context; the run row mirrors the
+ * outcome in the same transaction. Provide the SAME strategy instance the
+ * journal fences through (`SqlJournal.layerWith`), because
+ * `Consensus.layerLocal` keeps its leases per layer build.
+ *
+ * @since 1.0.0
+ * @category layers
+ */
+export const layerWith = Layer.effect(RunStore, make);
+/**
+ * Provides the database-backed `RunStore` arbitrated by the database-backed
+ * strategy, `SqlConsensus`, over the same client — the strategy
+ * `SqlJournal.layer` fences through. Use {@link layerWith} to inject a
+ * different strategy.
+ *
+ * @since 0.1.0
+ * @category layers
+ */
+export const layer = layerWith.pipe(Layer.provide(SqlConsensus.layer));
+//# sourceMappingURL=RunStore.js.map