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

package/docs/api.md

@@ -0,0 +1,901 @@
+---
+title: "API reference"
+description: "Every public export of @smthrs/run-store: the RunStore and AttemptStore services and their outcomes, ownership arbitration, the heartbeat constants, the fencing metrics, the migration set, and the test layer."
+---
+
+`@smthrs/run-store` exports five namespaces from its root entry point, and each
+is also importable from `@smthrs/run-store/<Module>`:
+
+```ts
+import { AttemptStore, Migrations, Ownership, RunStore, RunStoreMetrics } from "@smthrs/run-store"
+// or
+import * as RunStore from "@smthrs/run-store/RunStore"
+```
+
+Two subpaths are not namespaces of the root barrel:
+`@smthrs/run-store/Heartbeat`, the lease-constant leaf, and
+`@smthrs/run-store/test/TestRunStore`, which binds a Node database.
+`@smthrs/run-store/package.json` is exported. `internal/*`, `migrations/*`, and
+nested `*/index` are blocked in the export map and are not public API.
+
+Services and tags are Effect constructs: a `Layer` provides a service, and an
+effect reads it from context. `RunStore.layer` and `AttemptStore.layer` each
+require a `SqlClient` and a `DurableWriter` from
+[`@smthrs/database`](/api/database).
+
+## Example
+
+```ts
+import { RunStore } from "@smthrs/run-store"
+const owner = { hostId: "worker-1", pid: process.pid, nonce: "9c31-af02" }
+const program = Effect.gen(function*() {
+  const runs = yield* RunStore.RunStore
+  yield* runs.create("build-42", JSON.stringify({ step: "checkout" }))
+  const taken = yield* runs.claimAndOwn(
+    "build-42",
+    { status: "pending", owner: null, heartbeatAtMs: null },
+    owner,
+    Date.now()
+  )
+  if (taken._tag === "Activated") yield* runs.transitionOwned("build-42", owner, "completed")
+})
+```
+
+## Entry points
+
+| Import                                | Source                                                                                                                                  | Platform |
+| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | -------- |
+| `@smthrs/run-store`                   | [src/index.ts](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/run-store/src/index.ts)                         | any      |
+| `@smthrs/run-store/Heartbeat`         | [src/Heartbeat.ts](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/run-store/src/Heartbeat.ts)                 | any      |
+| `@smthrs/run-store/test/TestRunStore` | [src/test/TestRunStore.ts](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/run-store/src/test/TestRunStore.ts) | Node     |
+
+The root is driver-neutral and browser-bundleable: nothing under it imports a
+`node:` built-in.
+
+## RunStore
+
+One row per durable run: its status, its owner, its heartbeat, its cancellation
+intent, and the executable state a resume re-enters.
+
+### RunStore.RunStore
+
+```ts
+class RunStore extends Context.Service<RunStore, Service>()("@smthrs/run-store/RunStore")
+```
+
+The service tag. The identity string equals the defining module path.
+
+### RunStore.Service
+
+Fourteen operations. Every one validates its input first and fails with
+`RunStoreError` on a defect; competition is reported as a success value.
+
+#### create
+
+```ts
+const create: (runId: string, stateJson: string, options?: CreateOptions) => Effect<void, RunStoreError>
+```
+
+Inserts a `pending` row. `stateJson` is JSON text: it is parsed, bounded, and
+stored as the caller's own bytes. `created_at_ms` is stamped from the Effect
+`Clock`. A `runId` that begins with the journal's `companionPrefix` names a
+companion stream and fails `invalid_run`.
+
+#### get
+
+```ts
+const get: (runId: string) => Effect<RunRow, RunStoreError>
+```
+
+Reads one row and re-validates it. Fails with `not_found_row` when there is no
+such run, and with `decode_failed` when the row breaks the durable invariants.
+`latestRound` also reports a missing row as a failure.
+
+#### lineage and latestRound
+
+```ts
+const lineage: (runId: string) => Effect<ReadonlyArray<RunRow>, RunStoreError>
+const latestRound: (runId: string) => Effect<RunRow, RunStoreError>
+```
+
+Resolve trampoline membership from any existing round. `lineage` returns all
+rounds in ordinal order, or an empty array for an unknown ID. `latestRound`
+returns the highest ordinal using the lineage index, or `not_found_row`.
+Pre-lineage roots with null lineage columns are included as round zero. A run
+whose own ID equals the lineage ID joins only when its lineage columns are
+null or it explicitly names that lineage, so a same-named run in an
+independent lineage is excluded.
+Fork ancestry in `parentRunId` does not join otherwise independent lineages.
+These are individual snapshot reads; compose several reads with the owning
+database transaction when they must describe one coherent state.
+
+#### requestCancelLineage
+
+```ts
+const requestCancelLineage: (runId: string, nowMs: number) => Effect<RequestCancelOutcome, RunStoreError>
+```
+
+Records cancellation for every nonterminal round of the named logical run in
+one write transaction: one guarded UPDATE over the lineage members, and on a
+miss one read of their status and request columns. Cost follows the number of
+rounds and never their state payloads, so a long settled history adds nothing.
+A completed predecessor does not hide its live handoff successor. Existing
+request times and completed-round history are unchanged.
+Outcome precedence: `CancelRequested` if any round gets a new request;
+otherwise `AlreadyRequested` with the latest live round's earlier request;
+otherwise, with every round settled, `Terminal` with the latest round's status;
+`NotFound` when no round exists. A live round without a request that the
+UPDATE did not reach fails with `persistence_failed`, since the writer
+serializes the transaction and no peer can clear the column mid-call.
+This method does not traverse child ownership edges or interrupt local fibers;
+the engine coordinates those operations.
+
+#### requestCancel
+
+```ts
+const requestCancel: (runId: string, nowMs: number) => Effect<RequestCancelOutcome, RunStoreError>
+```
+
+Records unfenced cancellation intent for exactly one round that a later guarded transition observes.
+Any observer may call it, and it is first-writer-wins, so a repeat reports the
+original time. A settled run records nothing. The call is one guarded UPDATE
+and, on a miss, one read of the status and request columns; it never retries,
+because the durable writer serializes the whole call. `nowMs` is request data rather than
+a lease predicate, so it is checked as a non-negative safe integer and not bound
+by the skew allowance.
+
+#### acknowledgeCancel
+
+```ts
+const acknowledgeCancel: (runId: string, owner: OwnerId, nowMs: number) => Effect<boolean, RunStoreError>
+```
+
+Records the first owner observation of cancellation intent under the running
+owner fence. Returns false when the run is missing, not running, has no intent,
+or belongs to another owner. Repeated acknowledgements preserve the original
+owner and timestamp. This does not make the run terminal or prove cleanup ended.
+Engine snapshots expose the record separately from request and finish.
+
+#### claim
+
+```ts
+const claim: (
+  runId: string,
+  expected: RunSnapshot,
+  claimant: OwnerId,
+  nowMs: number
+) => Effect<ClaimOutcome, RunStoreError>
+```
+
+Reserves an exact `pending` or `suspended` snapshot for a later `activate`.
+`nowMs` becomes `claimed_at_ms` and is the token `activate` compares against.
+
+#### claimAndOwn
+
+```ts
+const claimAndOwn: (
+  runId: string,
+  expected: RunSnapshot,
+  owner: OwnerId,
+  nowMs: number,
+  evidence?: LivenessEvidence
+) => Effect<ClaimAndOwnOutcome, RunStoreError>
+```
+
+Claims and activates in one compare-and-swap. It admits `pending`, `suspended`,
+and `running` rows; replacing a different running owner additionally requires
+matching evidence, whose `checkedAtMs` must equal `nowMs` exactly. `nowMs` is the
+lease cutoff and the first heartbeat.
+
+#### activate
+
+```ts
+const activate: (
+  runId: string,
+  claimant: OwnerId,
+  claimedAtMs: number,
+  expected: RunSnapshot
+) => Effect<ActivateOutcome, RunStoreError>
+```
+
+Trades a held claim for ownership: sets `status = 'running'`, writes the owner
+columns and the first heartbeat from the Effect `Clock`, stamps `started_at_ms`
+if it is not already set, and clears the claim. `claimedAtMs` is the fence token
+`claim` or `steal` returned.
+
+#### abandonClaim
+
+```ts
+const abandonClaim: (
+  runId: string,
+  claimant: OwnerId,
+  claimedAtMs: number
+) => Effect<AbandonClaimOutcome, RunStoreError>
+```
+
+Releases a claim you hold, so a failed activation does not block the next
+claimant until the claim goes stale.
+
+#### recoverClaim
+
+```ts
+const recoverClaim: (
+  runId: string,
+  staleClaimant: OwnerId,
+  claimedAtMs: number,
+  observer: OwnerId,
+  nowMs: number,
+  evidence: LivenessEvidence
+) => Effect<RecoverClaimOutcome, RunStoreError>
+```
+
+Clears an exact stale claim after matching its claimant and liveness evidence.
+The claim must be older than `heartbeatStaleAfter` relative to `nowMs`.
+`claimedAtMs` is compared against the row and is not bound by the skew allowance,
+because the store issued it.
+
+#### heartbeat
+
+```ts
+const heartbeat: (runId: string, owner: OwnerId, nowMs: number) => Effect<HeartbeatOutcome, RunStoreError>
+const reconfirm: (runId: string, owner: OwnerId, nowMs: number) => Effect<HeartbeatOutcome, RunStoreError>
+```
+
+Renews the owner's lease. The write is `MAX(heartbeat_at_ms, nowMs)`, so a
+reading behind the persisted stamp still reports `Updated` without moving the
+lease backwards.
+
+#### transitionOwned
+
+```ts
+const transitionOwned: (
+  runId: string,
+  owner: OwnerId,
+  toStatus: RunStatus,
+  stateJson?: string,
+  guard?: TransitionGuard
+) => Effect<TransitionOutcome, RunStoreError>
+```
+
+The only way to move a run you own. `running` keeps the owner and rewrites only
+the state. `suspended` clears the owner, the heartbeat, and the claim and leaves
+`finished_at_ms` null. `completed`, `failed`, and `cancelled` clear the same
+columns and stamp `finished_at_ms`. `pending` fails with `invalid_run`. An
+omitted `stateJson` leaves the column as recorded; a supplied one replaces it
+whole. The guard is compiled into the same `UPDATE` as the ownership fence.
+
+#### steal
+
+```ts
+const steal: (
+  runId: string,
+  expected: RunSnapshot,
+  claimant: OwnerId,
+  nowMs: number,
+  evidence: LivenessEvidence
+) => Effect<StealOutcome, RunStoreError>
+```
+
+Writes the claim columns of a stale `running` row after verifying evidence,
+leaving status, owner, and heartbeat untouched so the same `expected` snapshot
+activates. The write refuses any row whose `heartbeat_at_ms` is within
+`heartbeatStaleAfter` of `nowMs`, and any row that already carries a claim.
+
+### RunStore models
+
+#### RunStatus
+
+```ts
+const RunStatus: Schema.Literals<["pending", "running", "suspended", "completed", "failed", "cancelled"]>
+type RunStatus = "pending" | "running" | "suspended" | "completed" | "failed" | "cancelled"
+```
+
+#### TerminalRunStatus and isTerminalRunStatus
+
+```ts
+const TerminalRunStatus: Schema.Literals<["completed", "failed", "cancelled"]>
+type TerminalRunStatus = "completed" | "failed" | "cancelled"
+const isTerminalRunStatus: (status: RunStatus) => status is TerminalRunStatus
+```
+
+The states a run never leaves. A settled run refuses new cancellation intent and
+is never claimed, activated, or swept.
+
+#### RunSnapshot
+
+```ts
+interface RunSnapshot {
+  readonly status: RunStatus
+  readonly owner: OwnerId | null
+  readonly heartbeatAtMs: number | null
+}
+```
+
+The triple every claim guards. `running` requires both an owner and a
+heartbeat; every other status requires neither. Admission is structural: the
+store reads only these three fields as own enumerable data properties and
+copies them, so a `RunRow` from `get` passes directly as `expected`. Other own
+data fields are ignored. A non-plain prototype, an enumerable accessor on any
+key, or a missing or inherited required field is refused as invalid input.
+
+#### RunRow
+
+```ts
+interface RunRow extends RunSnapshot {
+  readonly runId: string
+  readonly createdAtMs: number
+  readonly startedAtMs: number | null
+  readonly finishedAtMs: number | null
+  readonly claim: OwnerId | null
+  readonly claimedAtMs: number | null
+  readonly parentRunId: string | null
+  readonly cancelRequestedAtMs: number | null
+  readonly lineageId?: string | null | undefined
+  readonly roundOrdinal?: number | null | undefined
+  readonly stateJson: string
+}
+```
+
+A decoded `flows_runs` row, frozen. `lineageId` and `roundOrdinal` are optional
+on the interface because they arrived in an append-only migration, so a
+hand-built row still compiles.
+
+#### CreateOptions
+
+```ts
+interface CreateOptions {
+  readonly parentRunId?: string | undefined
+  readonly lineageId?: string | undefined
+  readonly roundOrdinal?: number | undefined
+}
+```
+
+`parentRunId` is the ancestry edge a fork, rewind, child, or trampoline round
+carries. It is a column rather than a state field because ancestry is walked in
+SQL, and it is a foreign key, so the parent must exist. `lineageId` and
+`roundOrdinal` name the trampoline lineage; both absent reads back as round 0 of
+a lineage of one.
+
+#### TransitionGuard
+
+```ts
+const TransitionGuard: Schema.Struct<{ cancelRequested: Schema.optional<Schema.Literals<["absent", "present"]>> }>
+type TransitionGuard = { readonly cancelRequested?: "absent" | "present" }
+```
+
+An extra compare-and-swap predicate over first-class run metadata, compiled into
+the transition's own `UPDATE`.
+
+### RunStore outcomes
+
+Every tag below is a success value. Union members carrying data are noted.
+
+| Type                   | Tags                                                                                                         |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `RequestCancelOutcome` | `CancelRequested { requestedAtMs }`, `AlreadyRequested { requestedAtMs }`, `NotFound`, `Terminal { status }` |
+| `ClaimOutcome`         | `Claimed { claimedAtMs }`, `NotFound`, `AlreadyClaimed`, `HeartbeatFresh`, `SnapshotChanged`                 |
+| `StealOutcome`         | `ClaimOutcome` plus `LivenessUnconfirmed`                                                                    |
+| `ClaimAndOwnOutcome`   | `Activated`, `NotFound`, `AlreadyClaimed`, `HeartbeatFresh`, `SnapshotChanged`, `EvidenceRequired`           |
+| `ActivateOutcome`      | `Activated`, `ClaimLost`, `SnapshotChanged`                                                                  |
+| `AbandonClaimOutcome`  | `Abandoned`, `ClaimLost`                                                                                     |
+| `RecoverClaimOutcome`  | `Recovered`, `NotFound`, `ClaimFresh`, `ClaimChanged`, `LivenessUnconfirmed`                                 |
+| `HeartbeatOutcome`     | `Updated`, `FenceLost`, `NotFound`                                                                           |
+| `TransitionOutcome`    | `Transitioned`, `FenceLost`, `NotFound`, `GuardFailed`                                                       |
+
+`LivenessUnconfirmed` means the evidence did not match, so no compare-and-swap
+ran. `SnapshotChanged` is reserved for matching evidence whose comparison lost to
+a row that moved. `EvidenceRequired` means the snapshot is current, its different
+owner is stale, and no evidence was supplied: retrying cannot help.
+`GuardFailed` means you own the run and the guard refused the write. What to do
+about each is in [Troubleshooting](./troubleshooting.md).
+
+### RunStore errors
+
+```ts
+const RunStoreErrorCode: Schema.Literals<
+  ["invalid_run", "not_found_row", "constraint", "decode_failed", "persistence_failed"]
+>
+
+class RunStoreError extends Schema.TaggedError<RunStoreError>()("@smthrs/run-store/RunStoreError", {
+  code: RunStoreErrorCode
+  method: Schema.String
+  message: Schema.String
+  cause: Schema.Unknown
+})
+```
+
+`message` is prefixed with the code and the method, as in
+`invalid_run: RunStore.claim: run input is invalid`. `cause` carries field names,
+lengths, and validity flags, never the value that failed.
+
+### RunStore constants
+
+| Constant              | Value   | Bounds                |
+| --------------------- | ------- | --------------------- |
+| `maximumRunJsonDepth` | 128     | Executable run state. |
+| `maximumRunJsonNodes` | 100,000 | Executable run state. |
+
+Run state has no byte ceiling by design: it is what a resume re-enters, so a
+large state has to persist.
+
+### Ownership transitions
+
+```ts
+const OwnershipTransition: Schema<"claimed" | "activated" | "released" | "stolen" | "expired">
+const ownershipEventType: (transition: OwnershipTransition) => string // "flows.consensus.<transition>"
+const companionStream: string // "run-store"
+```
+
+Every transition the consensus strategy grants is appended as a
+`flows.consensus.<transition>` fact, with payload `{ runId, owner,
+grantedAtMs }`, to the run's companion stream
+`JournalEvent.companionRunId(companionStream, runId)`, in the transaction that
+made it. `claim` records `claimed`; `activate` records `activated`, or
+`released` when the snapshot moved on; `claimAndOwn` records `claimed` or
+`stolen` and then `activated`, with a `released` first when an owner re-owns
+its own stale run; `steal` records `stolen`; `abandonClaim` and an owner's
+non-running `transitionOwned` record `released`; `recoverClaim` records
+`expired`. A refused operation and a heartbeat record nothing, and a
+rolled-back transaction leaves no fact.
+
+The facts sit beside the run's own stream, so a consumer that reads that stream
+by position never sees one. They are recorded when the caller runs with a
+`Journal` in its context, which the ordinary composition
+(`Layer.mergeAll(SqlJournal.layer(...), RunStore.layer)`) provides.
+
+### RunStore constructors and layers
+
+```ts
+const make: Effect<Service, never, DurableWriter | SqlClient.SqlClient>
+const makeNoop: (overrides?: Partial<Service>) => Service
+const layer: Layer<RunStore, never, DurableWriter | SqlClient.SqlClient>
+const layerNoop: (overrides?: Partial<Service>) => Layer<RunStore>
+```
+
+`makeNoop` is an explicit absence: `create` and `get` fail with
+`persistence_failed`, and every compare-and-swap reports a loss, `NotFound` or
+`ClaimLost` for `activate` and `abandonClaim`.
+
+## AttemptStore
+
+One row per step attempt, addressed by `(runId, stepKeyDigest, attempt)`. Every
+write is fenced on the run being `running` under the caller's owner; there is no
+unfenced write surface.
+
+### AttemptStore.AttemptStore
+
+```ts
+class AttemptStore extends Context.Service<AttemptStore, Service>()("@smthrs/run-store/AttemptStore")
+```
+
+### AttemptStore.Service
+
+#### put
+
+```ts
+const put: (attempt: Attempt, owner: OwnerId) => Effect<PutResult, AttemptStoreError>
+```
+
+Inserts the attempt row. `PutResult` is `Inserted`, `Upserted`, `ExistingSame`,
+`Conflict`, `FenceLost`, or `RunNotFound`. `ExistingSame` is a byte-equivalent
+replay, which makes a repeated `put` safe; object key order is ignored in that
+comparison and array order is not. `Upserted` occurs only under
+`putMode: "upsert"` and only while the existing row is still in progress.
+
+#### get
+
+```ts
+const get: (id: AttemptId) => Effect<Option<Attempt>, AttemptStoreError>
+```
+
+The one unfenced operation. Absent optional columns come back as absent keys
+rather than nulls, and every value is re-validated on the way out.
+
+Every `AttemptId` parameter (`get`, `patch`) is admitted structurally: the store
+reads only `runId`, `stepKeyDigest`, and `attempt` as own enumerable data
+properties and ignores other own data fields, so an `Attempt` from `put` or
+`get` passes directly as the id. A non-plain prototype, an enumerable accessor
+on any key, or a missing or inherited id field is refused with
+`invalid_attempt`.
+
+#### heartbeat
+
+```ts
+const heartbeat: (
+  runId: string,
+  stepKeyDigest: string,
+  attempt: number,
+  owner: OwnerId,
+  nowMs: number,
+  checkpoint?: JsonValue
+) => Effect<HeartbeatResult, AttemptStoreError>
+```
+
+Proves the attempt is still moving and optionally saves the value it would resume
+from. The checkpoint column is written with `COALESCE`, so omitting the argument
+leaves the stored checkpoint alone. The stamp is monotonic. `HeartbeatResult` is
+`Updated`, `FenceLost`, `NotFound`, or `StateChanged`, where `StateChanged` means
+you own the run but the attempt is no longer in `inProgressStates`.
+
+#### finish
+
+```ts
+const finish: (attempt: FinishAttempt, owner: OwnerId) => Effect<FinishResult, AttemptStoreError>
+```
+
+Moves the attempt to a terminal state. The target state must not be one of
+`inProgressStates`. `FinishResult` is `Finished`, `FenceLost`, `NotFound`, or
+`StateChanged`, so a second `finish` never overwrites the winning row.
+
+#### patch
+
+```ts
+const patch: (id: AttemptId, patch: AttemptPatch, owner: OwnerId) => Effect<PatchResult, AttemptStoreError>
+```
+
+Rewrites the opaque fields without touching the lifecycle, on running and
+terminal rows alike. `PatchResult` is `Patched`, `NotFound`, or `FenceLost`. It
+is still fenced on run ownership, so a patch after the run settles reports
+`FenceLost`.
+
+### AttemptStore models
+
+#### AttemptId, Attempt, FinishAttempt, AttemptPatch
+
+Each is a `Schema.Struct` exported under its own name, with a `type` alias of the
+same name for the decoded value:
+
+```ts
+interface AttemptId {
+  readonly runId: string
+  readonly stepKeyDigest: string
+  readonly attempt: number
+}
+
+interface Attempt extends AttemptId {
+  readonly state: string
+  readonly startedAtMs: number
+  readonly finishedAtMs?: number
+  readonly heartbeatAtMs?: number
+  readonly checkpoint?: JsonValue
+  readonly error?: JsonValue
+  readonly outcome?: JsonValue
+  readonly meta: JsonValue
+}
+
+interface FinishAttempt extends AttemptId {
+  readonly state: string
+  readonly finishedAtMs: number
+  readonly error?: JsonValue
+  readonly outcome?: JsonValue
+  readonly meta?: JsonValue
+}
+
+interface AttemptPatch {
+  readonly checkpoint?: JsonValue
+  readonly error?: JsonValue
+  readonly outcome?: JsonValue
+  readonly meta?: JsonValue
+}
+```
+
+`runId`, `stepKeyDigest`, and `state` are durable text: non-empty, at most 1,024
+UTF-16 units, no NUL, no lone surrogate. `attempt` and every timestamp are
+non-negative safe integers, range-checked independently and never against each
+other, so an attempt whose `finishedAtMs` precedes its `startedAtMs` persists as
+written.
+
+`meta` is required on `Attempt` and opaque: its shape belongs to the step
+executor, and the store carries it unchanged. On `FinishAttempt` and
+`AttemptPatch` an omitted field is left as recorded rather than cleared, so a
+terminal transition never erases a value written mid-flight. `AttemptPatch` never
+moves `state`, `startedAtMs`, or `finishedAtMs`.
+
+#### JsonValue
+
+```ts
+const JsonValue: Schema.declare<Json>
+```
+
+The strict JSON value accepted as durable attempt data: plain objects and arrays
+of finite numbers, well-formed strings, booleans, and null. Accessors, `toJSON`,
+non-plain prototypes, cycles, sparse arrays, enumerable symbols, and ill-formed
+text are refused. The store still takes an inert snapshot at effect start; this
+schema is the declaration contract the other schemas share.
+
+#### Options
+
+```ts
+interface Options {
+  readonly inProgressStates?: ReadonlyArray<string> | undefined
+  readonly maxCheckpointBytes?: number | undefined
+  readonly putMode?: "insert" | "upsert" | undefined
+}
+```
+
+| Field                | Default       | Meaning                                                                                           |
+| -------------------- | ------------- | ------------------------------------------------------------------------------------------------- |
+| `inProgressStates`   | `["running"]` | The states meaning "still moving". `heartbeat` and `finish` fence on membership.                  |
+| `maxCheckpointBytes` | 1 MiB         | Largest encoded checkpoint. Must be between 1 and `maximumCheckpointBytes`.                       |
+| `putMode`            | `"insert"`    | `"insert"` is first-writer-wins. `"upsert"` overwrites an in-progress row and reports `Upserted`. |
+
+All three are validated, detached, and frozen when the store is built, so an
+invalid policy fails at composition time.
+
+### AttemptStore errors
+
+```ts
+const AttemptStoreErrorCode: Schema.Literals<
+  ["invalid_attempt", "constraint", "decode_failed", "persistence_failed", "unknown"]
+>
+
+class AttemptStoreError extends Schema.TaggedError<AttemptStoreError>()(
+  "@smthrs/run-store/AttemptStoreError",
+  { code: AttemptStoreErrorCode; method: Schema.String; message: Schema.String; cause?: Schema.Unknown }
+)
+```
+
+`unknown` is what `layerNoop` reports.
+
+### AttemptStore constants
+
+| Constant                 | Value   | Bounds                                                   |
+| ------------------------ | ------- | -------------------------------------------------------- |
+| `maximumCheckpointBytes` | 16 MiB  | The ceiling `Options.maxCheckpointBytes` may not exceed. |
+| `maximumJsonDepth`       | 128     | Every attempt value.                                     |
+| `maximumJsonNodes`       | 100,000 | Every attempt value.                                     |
+
+Metadata, errors, and outcomes have no byte ceiling. Only the checkpoint does,
+because a step that cannot checkpoint still runs.
+
+### AttemptStore constructors and layers
+
+```ts
+const makeWith: (options?: Options) => Effect<Service, AttemptStoreError, DurableWriter | SqlClient.SqlClient>
+const make: Effect<Service, never, DurableWriter | SqlClient.SqlClient>
+const makeNoop: (overrides?: Partial<Service>) => Service
+const layer: Layer<AttemptStore, never, DurableWriter | SqlClient.SqlClient>
+const layerWith: (options: Options) => Layer<AttemptStore, AttemptStoreError, DurableWriter | SqlClient.SqlClient>
+const layerNoop: (overrides?: Partial<Service>) => Layer<AttemptStore>
+```
+
+`make` is `makeWith()` with the defaults, whose validation cannot fail.
+
+## Ownership
+
+Liveness evidence, the checks that produce it, and the heartbeat supervision loop.
+
+### OwnerId
+
+```ts
+interface OwnerId {
+  readonly hostId: string
+  readonly pid: number
+  readonly nonce: string
+}
+```
+
+Defined by [`@smthrs/journal`](/api/journal), because it is the same token the
+journal accepts on durable appends, and re-exported here so ownership callers
+read one vocabulary. All three fields are compared in the same SQL statement as
+every owned mutation.
+
+### LivenessEvidence
+
+```ts
+const LivenessEvidence: Schema.Struct<{
+  expectedOwner: OwnerId
+  checkedAtMs: Schema.Number
+  kind: Schema.Literals<["same-host-pid-dead", "cross-host-unreachable-stale", "lease-expired"]>
+}>
+```
+
+| Kind                           | Accepted when                                                                      |
+| ------------------------------ | ---------------------------------------------------------------------------------- |
+| `same-host-pid-dead`           | The observer and the recorded owner share a `hostId`.                              |
+| `cross-host-unreachable-stale` | The hosts differ.                                                                  |
+| `lease-expired`                | Any host. The strategy verifies this claim itself against the persisted heartbeat. |
+
+Defined by [`@smthrs/journal`](/api/journal)'s `Consensus`, because steal
+requires staleness plus liveness evidence in every strategy, and re-exported
+here. `checkedAtMs` must equal the consuming call's `nowMs` exactly, so a probe
+cannot be replayed into a later decision.
+
+### LivenessProbe, LivenessContext, LivenessCheck
+
+```ts
+type LivenessProbe<E = never, R = never> = (
+  expectedOwner: OwnerId,
+  claimant: OwnerId,
+  checkedAtMs: number
+) => Effect<LivenessEvidence | undefined, E, R>
+
+interface LivenessContext {
+  readonly claimant: OwnerId
+  readonly heartbeatAtMs: number | null
+  readonly nowMs: number
+}
+
+type LivenessCheck = (expectedOwner: OwnerId, context: LivenessContext) => Effect<boolean>
+```
+
+A `LivenessCheck` answers "is the recorded owner still working?", and answering
+`true` refuses the takeover. A `LivenessProbe` is the evidence factory the store's
+evidence-taking operations consume.
+
+### sameHostIncarnation
+
+```ts
+const sameHostIncarnation: (expectedOwner: OwnerId, claimant: OwnerId) => boolean
+```
+
+Whether two identities are incarnations on the same host. The predicate a probe
+applies before it inspects a pid.
+
+### leaseLiveness
+
+```ts
+const leaseLiveness: (staleAfter?: Duration.Input) => LivenessCheck
+```
+
+The default check and the honest floor: an owner is alive while its persisted
+heartbeat is younger than `staleAfter`, which defaults to `heartbeatStaleAfter`.
+An owner with no recorded heartbeat is reported gone. Browser compositions keep
+it, because a tab has no process table to ask.
+
+### sameHostPidProbe
+
+```ts
+const sameHostPidProbe: LivenessCheck
+```
+
+Asks this machine's process table with `process.kill(pid, 0)`, which sends no
+signal. Only `ESRCH` is read as death; `EPERM`, any other error, and a pid that
+is not a positive safe integer are read as life. A recorded owner on another host
+is never probed and answers `false`, so the expired lease decides instead of
+stranding that host's runs forever. Node hosts only.
+
+### heartbeatLoop
+
+```ts
+const heartbeatLoop: (
+  runId: string,
+  owner: OwnerId,
+  options?: HeartbeatLoopOptions
+) => Effect<never, never, RunStore>
+```
+
+Pulses every `heartbeatInterval` on the injected `Clock`, each pulse renewing
+the `Consensus` strategy's lease through `RunStore.heartbeat`, and interrupts
+itself when the fence is gone, so race it against the owned work with
+`Effect.raceFirst`. A heartbeat outcome other than `Updated` is durable evidence
+and interrupts immediately. An independent deadline bounds failing or stalled
+writes by `heartbeatWriteTolerance`. At expiry it tries `RunStore.reconfirm`
+for at most one `heartbeatInterval`: the same owner with no pending claim renews
+the lease. Its `onReconfirm` receipt must finish within the remaining renewed
+`heartbeatWriteTolerance` budget, measured from the timestamp sent to the store;
+loss, error, or timeout interrupts.
+Successful pulses re-arm that deadline from the timestamp supplied to the store,
+not their completion time.
+
+`RunStore.reconfirm` uses `Consensus.reconfirm` and mirrors the heartbeat
+transactionally, with the same input validation and outcome type as `heartbeat`.
+`options.onReconfirm(unconfirmedMs)` records each successful reconfirmation;
+it leaves the owner and generation unchanged.
+
+`options.onLapse(unconfirmedMs)` runs once when the lease lapses, before the
+self-interrupt, with how long the lease went unconfirmed. A lost fence does not
+call it. The engine's run driver uses it to record a `lease-lapsed` release cause.
+
+### The heartbeat constants
+
+`heartbeatInterval`, `heartbeatStaleAfter`, `heartbeatSkewAllowance`, and
+`heartbeatWriteTolerance` are re-exported from `Ownership`. See
+[Heartbeat](#heartbeat).
+
+## RunStoreMetrics
+
+Metric handles only; `RunStore` updates them as it decides each outcome, and the
+counters appear in whatever registry the composition provides.
+
+```ts
+const claims: Metric.Metric<number, Metric.CounterState<number>> // "flows_run_claims"
+const transitions: Metric.Metric<number, Metric.CounterState<number>> // "flows_run_transitions"
+const heartbeats: Metric.Metric<number, Metric.CounterState<number>> // "flows_run_heartbeats"
+```
+
+Eight records map an outcome `_tag` to an attributed view of its counter, so an
+update or a read is a lookup rather than a branch:
+
+| Record         | Counter       | Keys                                                                                                |
+| -------------- | ------------- | --------------------------------------------------------------------------------------------------- |
+| `claim`        | `claims`      | `Claimed`, `NotFound`, `AlreadyClaimed`, `HeartbeatFresh`, `SnapshotChanged`                        |
+| `claimAndOwn`  | `claims`      | the above with `Activated` for `Claimed`, plus `EvidenceRequired`                                   |
+| `activate`     | `claims`      | `Activated`, `ClaimLost`, `SnapshotChanged`                                                         |
+| `abandonClaim` | `claims`      | `Abandoned`, `ClaimLost`                                                                            |
+| `recoverClaim` | `claims`      | `Recovered`, `NotFound`, `ClaimFresh`, `ClaimChanged`, `LivenessUnconfirmed`                        |
+| `steal`        | `claims`      | `Claimed`, `NotFound`, `AlreadyClaimed`, `HeartbeatFresh`, `SnapshotChanged`, `LivenessUnconfirmed` |
+| `heartbeat`    | `heartbeats`  | `Updated`, `FenceLost`, `NotFound`                                                                  |
+| `transition`   | `transitions` | `Transitioned`, `FenceLost`, `NotFound`, `GuardFailed`                                              |
+
+Each view carries `outcome` in snake case, and the `claims` views also carry `op`
+(`claim`, `claim_and_own`, `activate`, `abandon_claim`, `recover_claim`,
+`steal`). `RunStore` adds the `to` attribute to a transition at the update site,
+because the target status is call input. A terminal transition also advances
+`runThroughput` from [`@smthrs/observability`](/api/observability). See
+[Observe store outcomes](./guides/observe-outcomes.md).
+
+## Migrations
+
+```ts
+const set: DatabaseMigrations.MigrationSet
+const run: Effect<ReadonlyArray<readonly [id: number, name: string]>, MigrationError | SqlError, SqlClient.SqlClient>
+const layer: Layer<never, MigrationError | SqlError, SqlClient.SqlClient>
+```
+
+`set` owns `flows_runs`, `flows_attempts`, `flows_run_source`, and
+`flows_run_changes` under the namespace `run-store` and
+reserves migration id block 1000, so its ids can never collide with another
+package's. `run` and `layer` install [`@smthrs/journal`](/api/journal)'s set
+ahead of it, because the SQL `RunStore` arbitrates ownership through the
+journal's `SqlConsensus` and its `flows_consensus_leases` table. Compose `set`
+with the other storage packages' sets and run them in one pass rather than
+layering several migrators; [`@smthrs/engine-store`](/api/engine-store)
+already does.
+
+The schema enforces the ownership invariants as SQL `CHECK` constraints, so no
+writer, including one issuing raw SQL, can leave a half-owned row behind.
+
+Migration 1003 adds a per-database source identity, monotonic revision triggers,
+and cancellation acknowledgement. Every run-row mutation advances the revision
+in its transaction. Existing rows receive baseline revisions; earlier mutation
+order and acknowledgement are unknown. Deleted run IDs remain permanent
+tombstones. See [Execution revisions](./concepts/execution-revisions.md).
+
+Migration 1004 (`0004_waiting_request`) adds nullable `flows_runs.waiting_request`
+as JSON text, enforced by `json_valid`. Existing rows read as having no declared
+request. The durable engine writes and clears it with the other waiting fields;
+human tasks use it to publish the prompt, answer kind, and attempt budget.
+
+## Heartbeat
+
+`@smthrs/run-store/Heartbeat` is a leaf module re-exporting the four lease
+durations from [`@smthrs/journal`](/api/journal)'s `Consensus`, where every
+strategy judges staleness against them. `RunStore` needs the staleness cutoff
+and `Ownership` needs all four, and `Ownership` imports `RunStore`, so neither
+could own them without the other restating them.
+
+| Constant                  | Value      | What it governs                                                                     |
+| ------------------------- | ---------- | ----------------------------------------------------------------------------------- |
+| `heartbeatInterval`       | 1 second   | How often the supervision loop pulses.                                              |
+| `heartbeatStaleAfter`     | 30 seconds | How old a persisted heartbeat must be before a peer may steal the run.              |
+| `heartbeatSkewAllowance`  | 10 seconds | How far the owner's wall clock may lag a peer's before the reasoning stops holding. |
+| `heartbeatWriteTolerance` | 19 seconds | How long an owner may keep working through failing heartbeat writes.                |
+
+All four are `Duration.Duration`. The last is derived rather than chosen:
+`heartbeatStaleAfter - heartbeatSkewAllowance - heartbeatInterval`, so an owner
+interrupts itself before a peer may steal the run. See
+[The heartbeat lease](./concepts/leases.md).
+
+## TestRunStore
+
+The module exports one layer, which provides both services at once:
+
+```ts
+import * as TestRunStore from "@smthrs/run-store/test/TestRunStore"
+import * as Effect from "effect/Effect"
+
+const tested = program.pipe(Effect.provide(TestRunStore.layer), Effect.scoped)
+```
+
+`@smthrs/run-store/test/TestRunStore` provides the production run and attempt
+stores over a fresh in-memory SQLite database, with the migrations applied before
+either service is exposed. Node only, and scoped: the database closes with the
+scope. See [Test against the real stores](./guides/testing.md).
+
+## Related reading
+
+- [Fencing and ownership](./concepts/fencing.md) for why competition is a value.
+- [Durable values](./concepts/durable-values.md) for the admission boundary.
+- [`@smthrs/journal`](/api/journal) for the history half of durability, and
+  [`@smthrs/engine-store`](/api/engine-store) for the composed storage ladder.