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

package/docs/guides/record-step-attempts.md

@@ -0,0 +1,170 @@
+---
+title: "Record a step attempt"
+description: "Start, checkpoint, finish, and annotate one execution of a step: the attempt identity, the run fence every write inherits, first-writer-wins versus upsert, and what patch is for."
+sidebar:
+  order: 3
+---
+
+An attempt is one execution of one content-addressed step inside a run. The
+store holds four operations that move it and one that reads it, and every write
+is fenced on the run you own.
+
+## The identity
+
+An attempt is addressed by three fields:
+
+```ts
+import type { AttemptId } from "@smthrs/run-store/AttemptStore"
+
+const id: AttemptId = { runId: "run-1", stepKeyDigest: "sha256-9f2c", attempt: 0 }
+```
+
+`stepKeyDigest` is the step's content address, so the same step in two runs
+shares no row, and a retry of the same step increments `attempt` rather than
+overwriting the previous try. All three are the table's primary key.
+
+## Start it
+
+`put` inserts the row, and the insert only lands while the run is `running` and
+owned by the caller:
+
+```ts
+import { AttemptStore } from "@smthrs/run-store"
+import type { OwnerId } from "@smthrs/run-store/Ownership"
+import * as Clock from "effect/Clock"
+import * as Effect from "effect/Effect"
+
+const start = (id: AttemptId, owner: OwnerId) =>
+  Effect.gen(function*() {
+    const attempts = yield* AttemptStore.AttemptStore
+    return yield* attempts.put({
+      ...id,
+      state: "running",
+      startedAtMs: yield* Clock.currentTimeMillis,
+      meta: { step: "fetch", cached: false }
+    }, owner)
+  })
+```
+
+`meta` is required and opaque: its shape belongs to the step executor, and the
+store carries it unchanged across every later state change. `state` is a name
+you choose, and the store only cares whether it is in `inProgressStates`.
+
+Five outcomes are possible, and only one is a defect:
+
+| Outcome        | Meaning                                                                                                                 |
+| -------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `Inserted`     | The row is new.                                                                                                         |
+| `Upserted`     | `putMode: "upsert"` replaced a row that was still in progress.                                                          |
+| `ExistingSame` | A row already exists and is byte-equivalent, so the write was a no-op. Object key order is ignored; array order is not. |
+| `Conflict`     | A row exists with different content, and the store is first-writer-wins.                                                |
+| `RunNotFound`  | The run row does not exist.                                                                                             |
+| `FenceLost`    | The run exists but is not `running` under your owner.                                                                   |
+
+`ExistingSame` is what makes a replayed `put` safe. `Conflict` means two
+writers disagree about what this attempt is, which is a bug in the caller.
+
+## Checkpoint it
+
+`heartbeat` proves the attempt is still moving and optionally saves the value it
+would resume from:
+
+```ts
+const beat = (id: AttemptId, owner: OwnerId, checkpoint: unknown) =>
+  Effect.gen(function*() {
+    const attempts = yield* AttemptStore.AttemptStore
+    return yield* attempts.heartbeat(
+      id.runId,
+      id.stepKeyDigest,
+      id.attempt,
+      owner,
+      yield* Clock.currentTimeMillis,
+      checkpoint as AttemptStore.JsonValue
+    )
+  })
+```
+
+The checkpoint argument is optional, and omitting it leaves the stored one
+alone: the column is written with `COALESCE`, never cleared. The heartbeat
+stamp is monotonic, so a delayed pulse cannot move it backwards.
+
+`heartbeat` fences on two things: the run must be `running` under your owner,
+and the attempt's `state` must still be one of the store's `inProgressStates`.
+Those two are reported separately. `FenceLost` means the run moved on;
+`StateChanged` means you still own the run but the attempt is no longer in
+progress, so something already finished it.
+
+## Finish it
+
+`finish` moves the attempt to a terminal state and records how it ended:
+
+```ts
+const succeed = (id: AttemptId, owner: OwnerId, outcome: AttemptStore.JsonValue) =>
+  Effect.gen(function*() {
+    const attempts = yield* AttemptStore.AttemptStore
+    return yield* attempts.finish({
+      ...id,
+      state: "completed",
+      finishedAtMs: yield* Clock.currentTimeMillis,
+      outcome
+    }, owner)
+  })
+```
+
+The target `state` must not be one of `inProgressStates`; passing one fails
+with `invalid_attempt`. `error`, `outcome`, and `meta` are all optional, and an
+omitted field is left as recorded rather than cleared, so a terminal transition
+never erases a value written mid-flight. Supplying one replaces it atomically
+with the terminal state, which is how an executor durably records what it
+learned while handling a failure.
+
+The outcomes match `heartbeat`: `Finished`, `NotFound`, `FenceLost`, or
+`StateChanged`. A second `finish` on an already-terminal attempt reports
+`StateChanged`, so repeated terminal transitions never overwrite the winning
+row.
+
+## Annotate it without touching its lifecycle
+
+`patch` rewrites the opaque fields and nothing else. It never moves `state`,
+`startedAtMs`, or `finishedAtMs`, so it works on running and terminal rows
+alike:
+
+```ts
+const annotate = (id: AttemptId, owner: OwnerId) =>
+  Effect.gen(function*() {
+    const attempts = yield* AttemptStore.AttemptStore
+    return yield* attempts.patch(id, { meta: { worktree: "/tmp/wt-1" } }, owner)
+  })
+```
+
+Use it for response text, worktree pointers, cache flags, and quarantined
+evidence: the things an executor discovers about an attempt after the fact.
+Omitted fields are left as recorded.
+
+`patch` is still fenced on run ownership, and that is the one surprising part.
+There is no unfenced write surface, so a delayed patch from an owner that lost
+the run reports `FenceLost` instead of rewriting the winning row. After the run
+reaches any terminal status its owner columns are cleared, so every patch on it
+reports `FenceLost` from then on. Patch before you settle the run.
+
+## Read it back
+
+```ts
+const read = (id: AttemptId) =>
+  Effect.gen(function*() {
+    const attempts = yield* AttemptStore.AttemptStore
+    return yield* attempts.get(id)
+  })
+```
+
+`get` is the one unfenced operation and returns `Option<Attempt>`. Absent
+optional columns come back as absent keys rather than nulls, and every stored
+value is re-validated on the way out, so a row corrupted outside these stores
+fails with `decode_failed` instead of being handed back as state.
+
+## Next steps
+
+- [Durable values](../concepts/durable-values.md): what the admission boundary
+  accepts, and the limits on checkpoints.
+- [Compose the stores into a host](./compose-the-stores.md): setting
+  `inProgressStates`, `putMode`, and the checkpoint ceiling.

package/docs/guides/recover-a-stalled-run.md

@@ -0,0 +1,173 @@
+---
+title: "Take over a stalled run"
+description: "Reclaim a run whose owner stopped: build liveness evidence at the instant you use it, steal the stale row, activate it, and recover a claim nobody ever activated."
+sidebar:
+  order: 5
+---
+
+A run stalls in two different places, and each has its own operation:
+
+- A **running owner stopped heartbeating.** The row is `running`, its
+  `heartbeat_at_ms` is older than `heartbeatStaleAfter`, and no other process
+  can write to it. `steal` takes it.
+- A **claim was never activated.** The row is still `pending` or `suspended`,
+  its claim columns are held by a claimant that died between `claim` and
+  `activate`, and `claim` reports `AlreadyClaimed` forever. `recoverClaim`
+  releases it.
+
+Both require two independent things: the SQL predicate that the row really is
+stale, and matching `LivenessEvidence` about the process that left it that way.
+Neither alone is enough.
+
+## Build evidence at the instant you spend it
+
+`evidence.checkedAtMs` must equal the `nowMs` of the call that consumes it,
+exactly, so evidence cannot be probed once and replayed later. Build it from a
+[`LivenessCheck`](../concepts/liveness-evidence.md) inside the same effect that
+uses it:
+
+```ts
+import { Ownership } from "@smthrs/run-store"
+import * as Effect from "effect/Effect"
+
+const probeFrom = (
+  check: Ownership.LivenessCheck,
+  heartbeatAtMs: number | null
+): Ownership.LivenessProbe =>
+(expectedOwner, claimant, checkedAtMs) =>
+  Effect.map(
+    check(expectedOwner, { claimant, heartbeatAtMs, nowMs: checkedAtMs }),
+    (alive) =>
+      alive ? undefined : {
+        expectedOwner,
+        checkedAtMs,
+        kind: Ownership.sameHostIncarnation(expectedOwner, claimant)
+          ? "same-host-pid-dead" as const
+          : "cross-host-unreachable-stale" as const
+      }
+  )
+```
+
+The `kind` has to match the host relation or the store refuses it: a pid probe
+means nothing across hosts, and an unreachability judgment means nothing on the
+owner's own machine. `Ownership.sameHostPidProbe` is the check to pass on a Node
+host; `Ownership.leaseLiveness()` is the floor every host can give.
+
+## Steal a stale running row, then activate it
+
+```ts
+import { RunStore } from "@smthrs/run-store"
+import type { OwnerId } from "@smthrs/run-store/Ownership"
+import * as Clock from "effect/Clock"
+
+const takeOver = (runId: string, claimant: OwnerId, check: Ownership.LivenessCheck) =>
+  Effect.gen(function*() {
+    const runs = yield* RunStore.RunStore
+    const row = yield* runs.get(runId)
+    if (row.status !== "running" || row.owner === null) return { _tag: "NotRunning" } as const
+
+    const expected = { status: row.status, owner: row.owner, heartbeatAtMs: row.heartbeatAtMs }
+    const nowMs = yield* Clock.currentTimeMillis
+    const evidence = yield* probeFrom(check, row.heartbeatAtMs)(row.owner, claimant, nowMs)
+    if (evidence === undefined) return { _tag: "OwnerAlive" } as const
+
+    const stolen = yield* runs.steal(runId, expected, claimant, nowMs, evidence)
+    if (stolen._tag !== "Claimed") return stolen
+    return yield* runs.activate(runId, claimant, stolen.claimedAtMs, expected)
+  })
+```
+
+A successful steal writes the claim columns and nothing else, so the row's
+status, owner, and heartbeat are still the ones you read. That is why the same
+`expected` snapshot satisfies the activation, and why the takeover path and the
+ordinary claim path converge on `activate`.
+
+| Steal outcome         | What it means                                                                             |
+| --------------------- | ----------------------------------------------------------------------------------------- |
+| `Claimed`             | The claim columns are yours. `claimedAtMs` is your activation token.                      |
+| `LivenessUnconfirmed` | The evidence did not match the owner, the host relation, or `nowMs`. No comparison ran.   |
+| `HeartbeatFresh`      | The persisted heartbeat is still inside the staleness window. The owner is not stale yet. |
+| `SnapshotChanged`     | The evidence matched, and the row moved between your read and your write.                 |
+| `AlreadyClaimed`      | Another process already holds the claim columns.                                          |
+| `NotFound`            | No such run row.                                                                          |
+
+`LivenessUnconfirmed` and `SnapshotChanged` are deliberately separate: the first
+says you were not allowed to try, the second says you tried and lost.
+
+## Recover a claim nobody activated
+
+`recoverClaim` clears an exact stale claim so the row becomes claimable again.
+It takes the claimant it is displacing, that claimant's `claimedAtMs` as a fence
+token, your own identity as the observer, and evidence about the dead claimant:
+
+```ts
+const releaseStaleClaim = (runId: string, observer: OwnerId, check: Ownership.LivenessCheck) =>
+  Effect.gen(function*() {
+    const runs = yield* RunStore.RunStore
+    const row = yield* runs.get(runId)
+    if (row.claim === null || row.claimedAtMs === null) return { _tag: "NoClaim" } as const
+
+    const nowMs = yield* Clock.currentTimeMillis
+    const evidence = yield* probeFrom(check, row.heartbeatAtMs)(row.claim, observer, nowMs)
+    if (evidence === undefined) return { _tag: "ClaimantAlive" } as const
+
+    return yield* runs.recoverClaim(runId, row.claim, row.claimedAtMs, observer, nowMs, evidence)
+  })
+```
+
+`Recovered` means the claim columns are clear. Claim the run normally after
+that; recovery does not hand you the run, it only unblocks it.
+
+| Recover outcome       | What it means                                                                      |
+| --------------------- | ---------------------------------------------------------------------------------- |
+| `Recovered`           | The stale claim is cleared. Any process may now claim the run.                     |
+| `ClaimFresh`          | The claim is younger than `heartbeatStaleAfter`. Wait, or leave it alone.          |
+| `ClaimChanged`        | The row no longer carries the claim you named, so someone else already handled it. |
+| `LivenessUnconfirmed` | The evidence did not match the claimant, the host relation, or `nowMs`.            |
+| `NotFound`            | No such run row.                                                                   |
+
+An owner that loses its own activation does not need any of this:
+`abandonClaim` releases a claim cooperatively, and it is what
+[Claim a run and finish it](./claim-and-finish-a-run.md) does when an activation
+loses. `recoverClaim` is for the claimant that will never come back.
+
+## The two cutoffs are the same number
+
+`steal` refuses any row whose `heartbeat_at_ms` is within `heartbeatStaleAfter`
+of your `nowMs`, and `recoverClaim` refuses any claim whose `claimed_at_ms` is
+within the same window. Both compare against the `nowMs` you passed, and both
+refuse a `nowMs` that runs more than `heartbeatSkewAllowance` ahead of the
+store's own clock with `invalid_run`, so no caller can shorten either window by
+reporting a later time.
+
+## Let the engine do it
+
+If you are running the Smithers engine, this sweep already exists. Its
+`NodeRuntime`, from [`@smthrs/flows`](/api/flows) rather than this package,
+requires an `isAlive` check precisely so it can run the sweep, and it takes no
+default: a check that answers "gone" without asking steals runs out of live
+processes.
+
+```ts
+import type * as NodeRuntime from "@smthrs/flows/NodeRuntime"
+import { Ownership } from "@smthrs/run-store"
+
+const options: NodeRuntime.Options = {
+  filename: ".smithers/smithers.db",
+  workspaceRoot: "/srv/workspace",
+  owner: { hostId: "host-a" },
+  isAlive: Ownership.sameHostPidProbe
+}
+```
+
+Write the sweep yourself only for a host, an adapter, or an operator tool that
+has to agree with the engine about who owns what.
+
+## Next steps
+
+- [Liveness evidence](../concepts/liveness-evidence.md): the three kinds, and
+  why every unknown probe answer is read as life.
+- [The heartbeat lease](../concepts/leases.md): what the staleness window can
+  and cannot promise.
+- [Observe store outcomes](./observe-outcomes.md): the counters that make a
+  takeover visible without reading logs.

package/docs/guides/testing.md

@@ -0,0 +1,141 @@
+---
+title: "Test against the real stores"
+description: "Test ownership and attempt code deterministically: the in-memory layer that runs the production stores, TestClock for every lease rule, the noop layers, and when a real file is the only honest test."
+sidebar:
+  order: 7
+---
+
+Nothing in these stores needs a mock. Every nondeterministic input is a service:
+the database is a `SqlClient`, the lease reasoning reads the Effect `Clock`, and
+the liveness answer is a `LivenessCheck` you pass in. A test swaps those and runs
+the production code.
+
+## Run the production stores in memory
+
+`@smthrs/run-store/test/TestRunStore` provides `RunStore` and `AttemptStore` over
+a fresh in-memory SQLite database with the migrations already applied. The stores
+are the real ones; only the file is gone.
+
+```ts
+import { AttemptStore, RunStore } from "@smthrs/run-store"
+import * as TestRunStore from "@smthrs/run-store/test/TestRunStore"
+import * as Effect from "effect/Effect"
+
+const withStores = <A, E>(
+  effect: Effect.Effect<A, E, RunStore.RunStore | AttemptStore.AttemptStore>
+) => effect.pipe(Effect.provide(TestRunStore.layer), Effect.scoped)
+```
+
+The layer is Node only, because it binds `node:sqlite`. Nothing else in the
+package is: the root entry point names no driver and bundles for the browser.
+
+Each provision gets its own database, so tests do not share rows. `Effect.scoped`
+is required: the database is a scoped resource and closes with the scope.
+
+## Drive every lease rule with TestClock
+
+The lease is the part most worth testing and the part you must never wait for in
+wall time. Both the store's own stamps and `Ownership.heartbeatLoop` read the
+injected `Clock`, so `TestClock` controls all of it:
+
+```ts
+import * as TestDatabase from "@smthrs/database/test/TestDatabase"
+import * as Migrations from "@smthrs/run-store/Migrations"
+import * as Duration from "effect/Duration"
+import { TestClock } from "effect/testing"
+
+const withTestClock = <A, E>(effect: Effect.Effect<A, E, RunStore.RunStore>) =>
+  effect.pipe(
+    Effect.provide(RunStore.layer),
+    Effect.provide(Migrations.layer),
+    Effect.provide(TestDatabase.layer),
+    Effect.provide(TestClock.layer())
+  )
+```
+
+`TestDatabase` comes from [`@smthrs/database`](/api/database), which this
+package depends on but does not re-export, so add it to your dev dependencies
+for that import to resolve.
+
+`TestClock.adjust(Duration.seconds(31))` walks a fresh lease past
+`heartbeatStaleAfter` in one statement, which is what makes a steal test a
+readable ten lines. Take `nowMs` from `Clock.currentTimeMillis` in the code under
+test, never `Date.now()`: a reading more than `heartbeatSkewAllowance` ahead of
+the store's clock fails with `invalid_run`, and a test that mixed the two would
+be failing on that rather than on what it meant to assert.
+
+To test the supervision loop, race it against work and assert on the exit:
+
+```ts
+import { Ownership } from "@smthrs/run-store"
+import type { OwnerId } from "@smthrs/run-store/Ownership"
+
+const supervised = (runId: string, owner: OwnerId) =>
+  Effect.raceFirst(Effect.never, Ownership.heartbeatLoop(runId, owner))
+```
+
+A pulse lands after each `TestClock.adjust(Ownership.heartbeatInterval)`. Once
+the fence is gone, the loop interrupts itself and takes the raced work with it,
+so the fiber's exit is an interrupt rather than a failure.
+
+## Assert on outcomes, not on rows
+
+Every operation answers with a tagged value, so the assertion is the contract:
+
+```ts
+const losesTheRace = Effect.gen(function*() {
+  const runs = yield* RunStore.RunStore
+  const outcome = yield* runs.claim("run-1", expected, ownerB, nowMs)
+  expect(outcome).toEqual({ _tag: "AlreadyClaimed" })
+})
+```
+
+Read the row back with `get` only for the fields the outcome does not carry:
+`heartbeatAtMs` after a pulse, `finishedAtMs` after a terminal transition, or
+`stateJson` to prove executable state round-tripped byte for byte. Counting
+outcomes proves the other half; see
+[Observe store outcomes](./observe-outcomes.md).
+
+## Use the noop layers for compositions that must not persist
+
+Both services ship an explicit absence, so a test that is not about persistence
+provides the smallest thing that type-checks:
+
+| Layer                      | Behavior                                                                                                                                                |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `RunStore.layerNoop()`     | `create` and `get` fail with `persistence_failed`. Every compare-and-swap reports a loss: `NotFound`, or `ClaimLost` for `activate` and `abandonClaim`. |
+| `AttemptStore.layerNoop()` | Every operation fails with the `unknown` code.                                                                                                          |
+
+Both take partial overrides, which is how a test forces one outcome without
+building a store:
+
+```ts
+const alwaysFenced = RunStore.layerNoop({
+  heartbeat: () => Effect.succeed({ _tag: "FenceLost" })
+})
+```
+
+Use an override to drive the caller's losing branch: a supervision test that
+needs `FenceLost` on the third pulse gets it here, with no second process and no
+clock arithmetic.
+
+## When a real file is the only honest test
+
+The in-memory database lives in one process, so it cannot prove anything about
+two processes contending for one run. Cross-process fencing needs a real SQLite
+file and two real Node processes, which is what
+[`test/RunStoreFileFence.integration.test.ts`](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/run-store/test/RunStoreFileFence.integration.test.ts)
+does: it spawns two children over one temporary database and steps them through a
+takeover from the parent.
+
+Write one of those only for a claim about concurrency across processes. Every
+other rule in this package, the fence, the guards, the admission boundary, the
+lease arithmetic, is fully decided inside one process.
+
+## Next steps
+
+- [Compose the stores into a host](./compose-the-stores.md): the production
+  layer order the test layer stands in for.
+- [Observe store outcomes](./observe-outcomes.md): asserting on counters.
+- [Troubleshooting](../troubleshooting.md): the failures a test is most likely to
+  hit first.

package/docs/installation.md

@@ -0,0 +1,109 @@
+---
+title: "Installation"
+description: "Install @smthrs/run-store, the SQL driver and durable writer it needs, its import forms, and the subpaths that are deliberately not public."
+sidebar:
+  order: 1
+---
+
+## Install the package
+
+Not on npm yet; see [Installation](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/flow/docs/installation.md#use-the-libraries).
+
+The package requires Node.js 26.4.0 or later and ships as both ESM and
+CommonJS with TypeScript declarations. Its dependencies install with it:
+[`@smthrs/database`](/api/database) for the durable write contract,
+[`@smthrs/journal`](/api/journal) for the `OwnerId` fencing token, and
+[`@smthrs/observability`](/api/observability) for the shared throughput metric.
+
+[`effect`](https://effect.website) is a peer dependency pinned at
+`4.0.0-rc.115`, so install exactly that version. Two copies of `effect` in one
+program are two sets of service tags, and a store layer built against one copy
+cannot be provided to a program holding the other: the mismatch surfaces as a
+missing service rather than as a version error.
+
+Installed is not the same as importable. A package manager that isolates
+transitive dependencies puts only `@smthrs/run-store` on your resolution path,
+so install any of those packages you import by name as a direct dependency too.
+`OwnerId` is the one you would otherwise reach for first: import it from
+`@smthrs/run-store/Ownership`, which re-exports the journal's token, rather
+than from `@smthrs/journal`.
+
+[`@smthrs/flows`](/api/flows) is not a dependency of this package at all. The
+snippets on these pages that type a `NodeRuntime.Options` value need it
+installed alongside.
+
+## What a working composition adds
+
+The stores are written against the driver-neutral `@smthrs/database` contract,
+so they carry no database of their own. A composition supplies two services:
+
+- `SqlClient.SqlClient` from `effect/unstable/sql/SqlClient`, which the SQL
+  driver provides. `@smthrs/database/node/NodeDatabase` opens a `node:sqlite`
+  database.
+- `DurableWriter` from `@smthrs/database`, which serializes and retries the
+  write transactions the stores run inside.
+
+The SQLite and PostgreSQL adapters share this package's migrations and
+statements. Both must satisfy the `DurableWriter` serialization contract.
+Use `PostgresDatabase` for schema-scoped advisory locking; a bare PostgreSQL
+READ COMMITTED client does not serialize writers.
+
+Using `NodeDatabase` or the in-memory `TestRunStore` helper selects the optional
+Node SQLite driver:
+
+```bash
+pnpm add @effect/sql-sqlite-node@4.0.0-rc.115
+```
+
+Both `RunStore.layer` and `AttemptStore.layer` require exactly those two, and
+`Migrations.layer` requires the `SqlClient` alone. The layer order that
+satisfies them is in [Compose the stores into a host](./guides/compose-the-stores.md).
+
+Most hosts do not wire this by hand. [`@smthrs/engine-store`](/api/engine-store)
+composes these stores with the journal, the step cache, and the durable engine
+state into one storage ladder, and `@smthrs/flows/NodeRuntime` builds that
+ladder over a single SQLite file.
+
+## Import forms
+
+The root entry point re-exports every module as a namespace:
+
+```ts
+import { AttemptStore, Migrations, Ownership, RunStore, RunStoreMetrics } from "@smthrs/run-store"
+```
+
+Each module is also importable from its own subpath, which is the form the API
+reference uses:
+
+```ts
+import * as AttemptStore from "@smthrs/run-store/AttemptStore"
+import * as RunStore from "@smthrs/run-store/RunStore"
+```
+
+Both forms reach the same modules. The root is driver-neutral and bundles for
+the browser: nothing under it imports a `node:` built-in.
+
+## The two subpaths that are not namespaces of the root
+
+| Import                                | Platform | What it holds                                                                                                                  |
+| ------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `@smthrs/run-store/Heartbeat`         | any      | The four lease durations: `heartbeatInterval`, `heartbeatStaleAfter`, `heartbeatSkewAllowance`, and `heartbeatWriteTolerance`. |
+| `@smthrs/run-store/test/TestRunStore` | Node     | `layer`, which provides migrated in-memory `RunStore` and `AttemptStore` services.                                             |
+
+`Ownership` re-exports all four durations, so the `Heartbeat` leaf exists for a
+consumer that wants the numbers and no store at all:
+
+```ts
+import * as Heartbeat from "@smthrs/run-store/Heartbeat"
+import * as TestRunStore from "@smthrs/run-store/test/TestRunStore"
+```
+
+`@smthrs/run-store/package.json` is exported. Three subpath families are
+blocked in the export map and are not public API: `internal/*`, `migrations/*`,
+and nested `*/index`. The migration implementations are blocked because the set
+is the contract; import `Migrations.set` rather than a numbered file.
+
+## Next step
+
+Run a full lifecycle against an in-memory database in the
+[Quickstart](./quickstart.md).