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

package/docs/concepts/workspace-transactions.md

@@ -0,0 +1,199 @@
+---
+title: "Workspace transactions"
+description: "The two-phase workspace sandbox: a body runs against an isolated tree and returns its writes, and a separate copy-back checks preconditions and applies them to the host."
+sidebar:
+  order: 4
+---
+
+`WorkspaceSandbox` is a functional transaction over a filesystem. A sealed
+action's body runs in an isolated workspace and returns its writes rather than
+performing them. Applying those writes to the host is a separate call that
+checks all preconditions before changing files and attempts in-process rollback
+on failure. Filesystem copy-back is not crash-atomic.
+
+```ts
+interface Service {
+  readonly execute: <Output, Error>(
+    execution: Execution<Output, Error>
+  ) => Effect<ExecutionResult<Output>, Error | WorkspaceError, Crypto>
+  readonly materialize: <Output>(
+    accepted: Accepted<Output>
+  ) => Effect<void, MaterializationConflict | WorkspaceError, Crypto>
+}
+```
+
+## execute never touches the host
+
+The transaction is seeded with exactly the declared read set. An undeclared
+file is simply not there, which is the strong enforcement tier: the body cannot
+read what it did not declare because the bytes were never copied in. The
+transaction is served through both the `Workspace` tag and a re-rooted Effect
+`FileSystem`, so a body written against either surface is isolated.
+
+At settlement the whole map is diffed. An execution whose observations
+contradict its declaration comes back `Invalidated`, and that shape deliberately
+carries provenance and violations only: there is no accessor for the candidate
+output, the files, or the queued effects. An accepted execution comes back as
+`Accepted`, carrying the `WorkflowResult`, the memo `CacheOutcome`, and, in
+expected mode, the violations the declaration did not predict.
+
+Seeding costs a copy of the declared reads. Re-rooting the body onto a bare
+host tree instead would leave every undeclared file readable and reduce
+enforcement to detection by diff after the fact, and the OS-level overlay that
+would fix that is not reachable through Effect's `FileSystem` tag, so it could
+not run in a browser. Bazel uses the same copy-in strategy for the same reason.
+
+## materialize is the only host write
+
+Copy-back is a compare-and-set on every `FileChange.beforeDigest`. If the base
+moved, the whole bundle is refused with `MaterializationConflict` and nothing
+lands. The engine answers that by retrying the attempt from a fresh base a bounded
+number of times.
+
+`beforeDigest` describes what is really on the host, not what was in the seed.
+The `Host.baseline` seam is what supplies it, because "absent from the seed" is
+emphatically not "absent from the host": a body writing a declared output it
+never declared as a read is the ordinary case, and that file usually already
+exists from a previous run. Treating the seed as the whole world made every such
+copy-back a conflict the engine could only rebase into the same refusal.
+
+Two more properties bind the write:
+
+- Every copy-back host call (the lock, the preflight reads, each write,
+  directory creation, and removal, and every rollback call) is one
+  descriptor-relative request against the workspace root pinned when the
+  commit starts. The host resolves each path component with `O_NOFOLLOW`
+  from that root, so there is no gap between a check and a write for another
+  process to swap a symlink into. A symlink anywhere on a change's path, a
+  hard-linked file, or a root replaced mid-commit fails `materialize` with
+  `path_escapes_workspace`. That includes a symlink that stays inside the
+  root: the body writes the referent path itself.
+- Digest checks and retained-byte resolution finish before any file change. The apply loop journals each target's pre-image before touching
+  it, including the target of a write that fails partway through. An apply
+  failure triggers an attempt to restore those files. Empty parent directories
+  can remain after rollback.
+
+The filesystem host serializes preflight, apply, and rollback with
+other cooperating commits. A semaphore is shared by workspace root in the
+process. A `.smithers-workspace-lock` lease file under the root coordinates
+separate processes, including callers using symlink aliases of the same root.
+This path is reserved: bundles cannot materialize it or its children. The `.flows` engine state directory is reserved the same way, so no
+write set, `**` glob, or `expected` boundary mode lets a step body replace the
+engine database, its `-wal` and `-shm` siblings, or artifact objects kept
+there. Add other state paths under the root with the `reservedPaths` option.
+A write or removal that targets a reserved path or lies beneath one fails
+`materialize` with `host_unavailable` before any file changes; a symlink alias
+of one is refused with `path_escapes_workspace` like any other symlink. Names
+match after NFKC normalization and case folding, so a spelling a
+case-insensitive volume equates with a reserved path, such as `.FLOWS`, is
+refused on every volume. An NTFS 8.3 short-name shape, such as `FLOWS~1`, is
+refused wherever a reserved segment stands, because an NTFS volume with short
+names on opens the long name through it.
+Filesystem hosts must support exclusive `wx` file creation, `stat` with an
+mtime, `utimes`, `rename`, and `remove`.
+
+The lock is `@smthrs/artifacts/FileLease`, the same lease the artifact store
+uses for its objects directory. The file holds a unique owner token, and the
+holder refreshes its mtime while the commit runs:
+
+| Bound                          | Value                          |
+| ------------------------------ | ------------------------------ |
+| Heartbeat interval             | 10 seconds                     |
+| Stale after                    | 60 seconds without a heartbeat |
+| Acquisition deadline           | 2 minutes                      |
+| Retry interval while contended | 25 milliseconds                |
+
+A killed or crashed holder stops heartbeating, and the next committer reclaims
+its lock a minute later. Reclaimers of one stale lock race for a `wx` claim
+file first, so the lock is moved away at most once and a fresh lock is never
+displaced. A committer that cannot take the lock within two minutes fails with
+`commit_lock_timeout` instead of waiting forever; the deadline ends before
+preflight starts, so it never interrupts an apply. A lock directory left by an
+rc.1 build is reclaimed on the same 60-second bound.
+
+The fence is bounded, not absolute. A holder whose host stalls past 60 seconds
+(a suspended machine, a stopped debugger) is reaped while it still runs; its
+heartbeat logs `Workspace commit lock was reclaimed while its holder was still
+running`, and its commit continues unfenced.
+
+Copy-back needs a host that can make those descriptor-relative requests. On
+Node and Bun that is `@smthrs/platform-node`'s `AtomicFileSystem.layer`, which
+`NodeHost` and `BunHost` already provide; an in-memory volume attests
+isolation with `@smthrs/kernel/FileSystem`'s `withIsolatedFileSystem`; the
+kernel-guarded `FileSystem.layer` rooted at the same workspace also qualifies.
+`WorkspaceSandbox.layerFileSystem` and `StepSandbox.layer` fail to build with
+`host_unavailable` over a plain path-based host such as
+`NodeFileSystem.layer`, because a path-based check cannot keep a concurrent
+symlink swap out of the write. Writers that ignore the advisory lock are not serialized.
+
+The undo journal exists only in memory. A process crash can leave partial file
+changes behind; the lock it held is reclaimed once stale. Rollback can also fail: the returned
+compound cause preserves the original apply failure and a `WorkspaceError`
+with code `host_unavailable` whose cause contains the rollback failure. Neither
+case guarantees restoration. The caller owns host reconciliation before
+resuming work: inspect affected paths and restore or accept their state.
+Waiting for the lock is interruptible, and an interrupted waiter never removes
+a lock it does not own.
+
+## Queued effects are dispatched after copy-back, never inside it
+
+A body that wants to send a message calls `Workspace.queueEffect`. The
+transaction records it and sends nothing. A speculative send has already reached
+the world when its execution turns out to be invalid, and reaches it twice when
+a copy-back loses a race.
+
+The optional `EffectDispatcher` stage runs after copy-back settles, deduplicated
+by `QueuedEffect.idempotencyKey`, the same key an irreversible action must carry
+before it may be retried at all. With no dispatcher provided the engine journals
+what a transaction queued and sends nothing. The journal records
+`diff-bundle-captured` and `copy-back-settled`.
+
+## One transaction, two hosts
+
+`makeHosted(host)` is the transaction. A `Host` supplies four things: `snapshot`
+(the base), `baseline` (the host's digest for a path the transaction never
+observed), `retain` (whether a produced file travels inline or by content
+address), and `commit` (the serialized, preconditions-first apply), plus a `root`.
+
+Two hosts ship:
+
+- `makeMemory(initialFiles)` is deterministic and browser-safe. It seeds the
+  whole tree rather than the declared read set, so an undeclared read is
+  observable, which is what makes it the conformance implementation.
+- `makeFileSystem(fs, path, artifacts, workspaceRoot, options)` and its layer
+  `layerFileSystem(options)` back the transaction with the kernel `FileSystem`,
+  the host `Path`, the kernel `Workspace` root, and the artifact store for products too large to
+  carry inline.
+
+Because both are `makeHosted` over one `Host`, the transaction, the diff, the
+violation check, and the provenance cannot drift between them.
+
+## It is a determinism boundary, not a security boundary
+
+A body that reaches the host through a service the transaction does not seed is
+outside the transaction. Denying that ambient access is the VM and
+`SandboxProvider` story in [`@smthrs/sandbox`](/api/sandbox). The transaction's
+`FileSystem` surface is deliberately partial. `readDirectory` lists immediate
+children and accepts `""`, `"."`, and the absolute workspace root as the root.
+`exists` recognizes the root, files, and directories implied by visible file
+paths. The root exists even when the transaction is empty; empty subdirectories
+are not retained, and `makeDirectory` is a no-op. File reads, writes, and removals
+require a non-root path. Paths containing `..` are refused. Directory probes
+trace the visible files that establish their results for declaration checks.
+A settled bundle is applied without a human diff-review gate, which is a known
+limitation.
+
+## StepSandbox is the scope-safe front door
+
+`StepSandbox.Service` has one member, `open`, which yields a
+`WorkspaceSandbox.Service` for one step or fails with `UnsupportedBoundary`.
+`StepSandbox.layer` is the filesystem-backed one, `layerTest(initialFiles)` is
+deterministic, and `layerNoop` fails closed for a host that cannot sandbox at
+all, such as a browser.
+
+## Related
+
+- [Step boundaries](./step-boundaries.md): the declaration the transaction is
+  validated against.
+- [Cache admission](./cache-admission.md): why the sandbox is what makes a
+  result shareable across runs.

package/docs/event-types.md

@@ -0,0 +1,14 @@
+---
+title: "Engine journal record names"
+description: "The shared persisted event types and child-spawn kind used by engine writers and time-travel readers."
+---
+
+[src/EventTypes.ts](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/engine-store/src/EventTypes.ts)
+
+Import `{ EventTypes }` from `@smthrs/engine-store/EventTypes` or the package
+entry point. The object supplies the persisted record names shared by engine
+writers and time-travel readers: `runDecision`, `attemptStarted`,
+`snapshotIdentified`, `planRecorded`, `subgraphAppended`, `deferredCompleted`,
+and `clockScheduled`. `childSpawnKind` identifies the effect inside a child-spawn
+boundary. It is an effect kind, not a journal event type. Changing these values
+requires migrating stored history.

package/docs/guides/back-up-and-restore.md

@@ -0,0 +1,164 @@
+---
+title: "Back up and restore the store"
+description: "Take a hot backup of a live engine database and its artifact blobs, verify it, restore it into a fresh directory, and fence the restored file so no pre-backup owner resurrects."
+sidebar:
+  order: 7
+---
+
+`DisasterRecovery` captures a live store without stopping it, verifies a capture
+against its own manifest, restores one into a fresh directory, and invalidates
+the ownership fences the restored file still carries.
+
+Back up the authoritative stores even when using the additive
+[typed event contracts](https://journal.smithers.sh/concepts/state-event-authority/).
+The demonstrated attempt projection rebuilds disclosed history, including from
+a retained snapshot and suffix. It does not recover arbitrary private results,
+all execution state, or live ownership fences. Current writers and retained
+history keep their existing bytes until an explicit writer cutover and migration.
+
+## Start from the reference script
+
+A reference command-line entry point,
+[`flows-backup.mjs`](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/engine-store/scripts/flows-backup.mjs),
+is the operator front end these three operations were designed against. It is
+not part of the published package, because the host layers are yours to choose:
+copy it into your own project, or read the sections that follow and compose the
+operations directly. It parses arguments and composes the Node host layers, and
+nothing else. Once copied, it takes three commands:
+
+```bash
+node flows-backup.mjs backup <database-file> <backup-directory> [objects-directory] [--max-file-size <bytes>]
+node flows-backup.mjs verify <backup-directory> [--max-file-size <bytes>]
+node flows-backup.mjs restore <backup-directory> <target-directory> [--max-file-size <bytes>]
+```
+
+`--max-file-size` sets `maxFileSizeBytes`, described below. Raise it when the
+database file or a blob is larger than 512 MiB.
+
+Its `restore` command calls `restoreAndFence`, so the restored file is fenced
+before the command returns.
+
+## Take a backup
+
+```ts
+import * as NodeDatabase from "@smthrs/database/node/NodeDatabase"
+import { DisasterRecovery } from "@smthrs/engine-store"
+
+const capture = DisasterRecovery.backup({
+  directory: "./backups/2026-09-03",
+  objectsDirectory: "./.flows/objects",
+  snapshotDatabaseLayer: (databaseFile) => NodeDatabase.layer({ filename: databaseFile })
+})
+```
+
+The database is snapshotted first with `VACUUM INTO`, a read transaction under
+WAL, so live writers are never blocked and the copy is one consistent point in
+time. The artifact walk runs after it, so every digest the snapshot references
+is captured, because publication always precedes reference. Blobs are
+digest-verified as they are copied: a blob whose bytes no longer hash to its
+address fails the backup loudly rather than capturing corruption. The manifest
+is written last, so a partial backup is detectable by its absence. A failed
+backup removes what it wrote, so you can retry into the same directory.
+
+`snapshotDatabaseLayer` opens the frozen file so the backup can enumerate
+artifact roots and migrations from that exact snapshot, independently of the
+live connection. Open it without applying migrations.
+
+**Pass `objectsDirectory` whenever the composition has a filesystem artifact
+tier.** With it, the whole capture holds the cross-process artifact backup
+lease, so a concurrent `ArtifactGc.gc` sweep cannot delete a blob between the
+database snapshot and its copy. Without it, no lease is taken, the backup
+carries no blobs, and a snapshot that references any artifact digest fails with
+`snapshot_incomplete` rather than reporting success. Pass the same directory you
+give `ArtifactStore.layerFileSystem`.
+
+`FileSizeOptions.maxFileSizeBytes` bounds what backup, verify, and restore may
+buffer for hashing or copying. It defaults to
+`DisasterRecovery.defaultMaxFileSizeBytes`, which is 512 MiB. An oversized file
+fails with the typed `io` code instead of reaching the host's allocation limit.
+Each file is read whole into memory, so set the limit above your largest
+database or blob and below the memory the host can spare.
+
+## Verify a backup without restoring it
+
+```ts
+const check = DisasterRecovery.verify("./backups/2026-09-03")
+```
+
+The manifest decodes, the database snapshot hashes to its recorded digest, and
+every listed artifact blob is present and hashes to its address. Run it on a
+schedule against your backup storage; a backup you have never read is a
+hypothesis.
+
+## Restore and fence
+
+```ts
+import { DurableWriter } from "@smthrs/database"
+import * as Layer from "effect/Layer"
+
+const restored = DisasterRecovery.restoreAndFence({
+  backupDirectory: "./backups/2026-09-03",
+  targetDirectory: "./.flows-restored",
+  databaseLayer: (databaseFile) =>
+    Layer.provideMerge(DurableWriter.layer(), NodeDatabase.layer({ filename: databaseFile }))
+})
+```
+
+Every byte is re-verified against the manifest as it is copied, so a backup that
+rotted in storage is refused rather than restored. The target holds the database
+file (`store.sqlite3`), an `objects` directory, and a `restored.json` marker, and
+is a fresh store directory to compose `NodeDatabase.layer` and
+`ArtifactStore.layerFileSystem` over.
+
+`restore` alone leaves the pre-backup owner fences in place. Run
+`DisasterRecovery.fence(manifest)` against the restored file before any engine
+adopts it, or use `restoreAndFence`, which does both and returns a
+`FencedRestoredStore`.
+
+## What fencing does
+
+The store's fence is `OwnerId` equality, so fence invalidation is the epoch
+bump. In one serialized write transaction, every pending claim is cleared and
+every run that was `running` at backup time is suspended with its owner and
+heartbeat cleared. A surviving pre-backup owner then fails every fenced
+operation against the restored store: `heartbeat` and `transitionOwned` report
+`FenceLost`, and fenced journal appends fail `fence_lost`. The suspended runs
+are claimable immediately, without waiting out the heartbeat staleness cutoff
+and without liveness evidence.
+
+`FenceSummary` reports `clearedClaims` and `suspendedRuns`.
+
+Fencing requires every migration recorded in the manifest to remain applied
+with the same ID and namespaced name. A missing or renamed historical entry
+fails with `schema_mismatch` before ownership is cleared. Forward additions in
+any installed block are compatible, including engine-store `3006` below an
+existing plan `4003`. The current database layer applies migrations on open;
+the manifest need not be a prefix of the globally ordered migration list.
+
+In-flight attempt rows are deliberately untouched: attempt writes are fenced on
+the run row's ownership, and the resuming engine adopts or retries them under
+its own fresh owner.
+
+## Failure codes
+
+`DisasterRecoveryError` carries a stable `code` and the `method` that raised it:
+
+| Code                  | Meaning                                                       |
+| --------------------- | ------------------------------------------------------------- |
+| `invalid_options`     | An option cannot be admitted safely.                          |
+| `not_empty`           | A target or backup directory exists and is not empty.         |
+| `invalid_manifest`    | The manifest is missing or does not decode.                   |
+| `missing_file`        | A file the manifest lists is absent.                          |
+| `digest_mismatch`     | The database snapshot does not hash to its recorded digest.   |
+| `artifact_corruption` | A blob does not hash to its address.                          |
+| `snapshot_incomplete` | The snapshot references artifacts the capture could not take. |
+| `schema_mismatch`     | A recorded migration is missing or has a different name.      |
+| `io`                  | A host read or write refused, including an oversized file.    |
+| `sql`                 | The database refused; the dialect here is SQLite.             |
+
+## Related
+
+- [Ownership and fencing](../concepts/ownership-and-fencing.md): why a restored
+  file needs a fence at all.
+- [Collect unreferenced artifacts](./collect-unreferenced-artifacts.md): the
+  sweep the backup lease fences against.

package/docs/guides/collect-unreferenced-artifacts.md

@@ -0,0 +1,128 @@
+---
+title: "Collect unreferenced artifacts"
+description: "Run an explicit mark and sweep over the artifact store: the live roots, the grace bound, pinned digests, and why the collection is fail-safe rather than best-effort."
+sidebar:
+  order: 6
+---
+
+Boundary evidence spills large outputs to the artifact store by digest. When
+the attempt rows and cache entries that referenced those blobs are deleted, the
+blobs stay. `ArtifactGc` is the explicit pass that removes them.
+
+Collection never runs automatically. `gc()` is a verb a caller invokes, and
+[`smthrs gc`](/cli/gc) invokes it after its retention pass.
+
+## Run a collection
+
+```ts
+import { ArtifactGc } from "@smthrs/engine-store"
+import * as Effect from "effect/Effect"
+
+const sweep = Effect.gen(function*() {
+  const gc = yield* ArtifactGc.ArtifactGc
+  return yield* gc.gc({ dryRun: true })
+})
+```
+
+`ArtifactGc.layer(options?)` provides the service and needs `SqlClient` and
+[`@smthrs/artifacts`](/api/artifacts)'s `ArtifactSweep`.
+`ArtifactGc.layerFileSystem(options?)` provides the filesystem sweep too and
+needs `SqlClient` and `FileSystem`; give it the same `directory` and
+`coordination` as the `ArtifactStore.layerFileSystem` it collects behind.
+`MakeOptions.pageSize` sets how many rows one mark-phase page holds; it defaults
+to 500.
+
+`GcOptions` takes `graceMs`, `pins`, and `dryRun`. A `GcReport` comes back with
+`scannedBlobs`, `liveDigests`, the `sweptDigests` list, `reclaimedBytes`,
+`keptByGrace`, and the `dryRun` flag.
+
+## Set the grace bound
+
+`graceMs` is how recently a blob must have been written or freshened to survive
+being unreferenced. It defaults to the installed policy's bound, then to
+`ArtifactGc.defaultGraceMs`, which is 14 days, git's `gc.pruneExpire` default.
+
+Each collection reads its start time before resolving policy pins or scanning
+roots. The cutoff is `startTimeMs - graceMs` and stays fixed through inventory
+and deletion. Only mtimes strictly before the cutoff are eligible; equality
+is retained, including publications in the starting millisecond with zero
+grace. The remove-side mtime fence uses the same cutoff, so a slow scan cannot
+age a concurrent publication into eligibility.
+
+The bound is deliberately far beyond any live attempt's duration. A blob spilled
+by a running step is unreferenced until its attempt row finishes, and the grace
+period is the only thing protecting it in that window.
+
+## Install a policy
+
+`ArtifactGcPolicy` carries the defaults a `gc()` call may omit. Explicit
+`GcOptions` override the policy, and the policy overrides the built-in
+defaults:
+
+```ts
+const policy = ArtifactGc.layerPolicy({
+  graceMs: 7 * 24 * 60 * 60 * 1000,
+  pins: Effect.succeed([pinnedExportDigest])
+})
+```
+
+`pins` is the seam for references this composition's tables cannot see: an
+external index, or an export a human wants kept. Each entry is a hex SHA-256
+content address. It is an effect, resolved fresh on every collection, and its
+digests are held live regardless of reachability.
+Installing a policy configures collection; it never schedules it.
+
+## What counts as a live root
+
+The mark phase reads this package's own tables directly, because the package
+composes every one of those migrations:
+
+- Every row of `flows_step_cache`, through its boundary evidence.
+- Every row of `flows_attempts`, through its boundary evidence and its
+  checkpoints. Digest-shaped strings in a checkpoint are retained
+  conservatively.
+- The pins.
+
+Every run present in `flows_runs` is a live root: there is no deleted state, and
+the attempt table's foreign key guarantees each attempt's run exists, so the
+scan is all attempt rows plus all cache entries, paged by primary key.
+
+## The mark is fail-safe, not best-effort
+
+A root row carrying boundary evidence this build cannot decode aborts the
+collection with `mark_failed` rather than contributing nothing. Silently reading
+such a row as "references no artifacts" is exactly how a live blob gets
+collected. A metadata shape with no `boundary` key at all is the ordinary
+foreign-evidence case, and yields the empty set.
+
+## Why concurrent work is safe
+
+The live set is computed before the inventory, so a root recorded during the
+sweep can only be missed, never half seen. The blob such a root references is
+protected anyway: a fresh publication carries a fresh mtime, a re-publication of
+existing bytes freshens the blob's mtime, and the sweep's deletion is fenced on
+that mtime. A crash mid-sweep deletes some garbage and no live blobs, and
+re-running converges.
+
+## Read the failures
+
+`ArtifactGcError` carries one of three codes:
+
+| Code              | Meaning                                                                                |
+| ----------------- | -------------------------------------------------------------------------------------- |
+| `invalid_options` | An option was outside its admissible range.                                            |
+| `mark_failed`     | A root could not be scanned or its evidence could not be decoded. Nothing was deleted. |
+| `sweep_failed`    | The inventory or a deletion refused.                                                   |
+
+## Order it after retention
+
+Deleting run history removes roots; collecting artifacts removes the blobs
+those roots kept alive. Run
+[retention](./delete-old-run-history.md) first, then this pass, or the blobs
+freed by retention wait for the next collection.
+
+A backup taken while a collection runs would race the sweep. `DisasterRecovery`
+takes the artifact backup lease for the whole capture when it is given an
+`objectsDirectory`, so a concurrent sweep cannot delete a blob between the
+database snapshot and its copy. See
+[Back up and restore the store](./back-up-and-restore.md).

package/docs/guides/compose-a-durable-engine.md

@@ -0,0 +1,146 @@
+---
+title: "Compose a durable engine"
+description: "Wire EngineStore.layer: the services it requires, the ones it resolves optionally, what each option changes, and how to give engine bookkeeping its own repository."
+sidebar:
+  order: 1
+---
+
+`EngineStore.layer(options)` provides `FlowRuntime` and
+`FlowEngine.SnapshotBoundary`. This guide covers what you have to provide
+underneath it, what you may provide, and what each choice changes.
+
+## Provide the required services
+
+A composition failure is an unmet requirement in the layer's type, so a
+composition that forgets one of these fails to compile. There is no run-time
+composition error to handle.
+
+| Service              | From                                    | Why                                                |
+| -------------------- | --------------------------------------- | -------------------------------------------------- |
+| `Journal`            | [`@smthrs/journal`](/api/journal)       | Every engine decision is written here.             |
+| `RunStore`           | [`@smthrs/run-store`](/api/run-store)   | Run rows, claims, leases, cancellation.            |
+| `AttemptStore`       | [`@smthrs/run-store`](/api/run-store)   | Attempt rows.                                      |
+| `CacheStore`         | [`@smthrs/step-cache`](/api/step-cache) | Recorded step results.                             |
+| `DurableEngineState` | this package                            | Deferreds, clocks, waiting rows, the run DAG.      |
+| `OwnerIdentity`      | this package                            | Mints the `OwnerId` this incarnation fences with.  |
+| `StepBoundary`       | this package                            | Measures each step's declared read and write sets. |
+| `Jj`                 | [`@smthrs/kernel`](/api/kernel)         | Compensable snapshots for the snapshot boundary.   |
+| `Crypto`             | `effect/Crypto`                         | Digests the step keys and mints the owner nonce.   |
+| `Scope`              | `effect`                                | Registrations and active fibers are scoped.        |
+
+The [Quickstart](../quickstart.md) builds all of them over one SQLite file.
+
+## Provide the optional services deliberately
+
+Both halves of the isolated-execution lane are optional and are resolved at
+composition time, because `actionExecute` runs on the engine's own fiber, which
+does not carry the store's layer context. Anything a dispatch needs has to be
+captured when the store is built and re-provided onto that fiber.
+
+| Optional service   | Absent                                                                                                                    | Present                                                                                                           |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `WorkspaceSandbox` | The body runs against the host directly; results stay run-local.                                                          | The body runs isolated, so evidence can claim the whole tree and results become shareable.                        |
+| `EffectDispatcher` | The engine journals what a transaction queued and sends nothing.                                                          | Queued effects are dispatched after copy-back, deduplicated by idempotency key.                                   |
+| `StepSandbox`      | No per-step isolated workspace is acquired.                                                                               | Each step opens its own scoped workspace.                                                                         |
+| `WakeBus`          | The composition builds a private bus.                                                                                     | Your own wake sources share one bus with the engine.                                                              |
+| `ArtifactSync`     | `makeLocal()`: publish is a no-op, hydrate reports nothing arrived.                                                       | Referenced blobs reach a shared tier before their cache entry does.                                               |
+| `CacheSync`        | `makeLocal()`: a recorded entry is already everywhere it will be.                                                         | Durable local entries are published to a shared step-result tier.                                                 |
+| `Inconsistency`    | Conflicts are journaled and fail the dispatch (the strict default); provide `layerTolerant(owner)` to continue past them. | Cache conflicts and corrupt evidence are journaled. `layerStrict(owner)` fails; `layerTolerant(owner)` continues. |
+| `Reconciliation`   | Deviations and conflicts have no reader.                                                                                  | `layerDefault` answers them deterministically.                                                                    |
+| `Selection`        | Everything is admitted.                                                                                                   | Sinks may be deferred to a guess-free pass.                                                                       |
+
+## Set the options
+
+```ts
+import { EngineStore } from "@smthrs/engine-store"
+import { Ownership } from "@smthrs/run-store"
+
+const engine = EngineStore.layer({
+  owner: { hostId: "worker-a" },
+  journalSource: "worker-a-engine",
+  isAlive: Ownership.sameHostPidProbe
+})
+```
+
+`owner.hostId` is this engine's stable identity. Which host a store speaks for
+is a composition decision, not a host fact, so the store asks you rather than
+guessing.
+
+`journalSource` is the source id every record this engine writes carries. Give
+two engines over one database two different source ids so their records are
+distinguishable.
+
+`isAlive` decides whether a run whose lease expired may be stolen. Omit it and
+the lease alone decides, which is enough to reclaim from a SIGKILL. Supply one
+to refuse a takeover for longer. See
+[Reclaim runs from a dead host](./reclaim-runs-from-a-dead-host.md).
+
+`clockFireRetryPolicy` is the redispatch `Schedule` for a durable clock whose
+fire failed. It defaults to exponential from 100ms capped at 30s, forever.
+
+## Build the service instead of the layer
+
+`EngineStore.make(options)` returns the `FlowRuntime` service itself, for a host
+that composes it by hand rather than through a layer:
+
+```ts
+import * as Effect from "effect/Effect"
+
+const runtime = Effect.gen(function*() {
+  const flowRuntime = yield* EngineStore.make({
+    owner: { hostId: "worker-a" },
+    journalSource: "worker-a-engine"
+  })
+  return flowRuntime
+})
+```
+
+`make` does not provide `FlowEngine.SnapshotBoundary`; `layer` does.
+
+## Give engine bookkeeping a private repository
+
+The engine uses `Jj` for two different purposes: the repository an action body
+may reach, and the bookkeeping the snapshot boundary performs. A host that
+guards action access wants those to be different services.
+
+`EngineStore.layerWithPrivilegedJj(options, privilegedJj)` takes a second `Jj`
+layer for engine bookkeeping and leaves the ambient `Jj` for action bodies:
+
+```ts
+const engine = EngineStore.layerWithPrivilegedJj(
+  { owner: { hostId: "worker-a" }, journalSource: "worker-a-engine" },
+  privilegedJjLayer
+)
+```
+
+Use `layer` when both roles may use the same repository access.
+
+## Install the schema underneath
+
+`Migrations.layer` runs journal, run store, step cache, this package's own
+tables, and the plan store, in that order. It must complete before any durable
+service is exposed, so provide it under the stores rather than beside them:
+
+```ts
+import { DurableWriter } from "@smthrs/database"
+import * as NodeDatabase from "@smthrs/database/node/NodeDatabase"
+import { Migrations } from "@smthrs/engine-store"
+import * as Layer from "effect/Layer"
+
+const database = (filename: string) =>
+  Layer.provideMerge(
+    Migrations.layer,
+    Layer.provideMerge(DurableWriter.layer(), NodeDatabase.layer({ filename }))
+  )
+```
+
+The plan store's set comes last because its id block is the highest, and the
+migrator decides what to run from a single high-water mark. See
+[`@smthrs/database`](/api/database) for how namespaced sets compose without
+colliding.
+
+## Related
+
+- [Quickstart](../quickstart.md): the whole composition, runnable.
+- [Test against a durable store](./testing.md): the same composition with
+  `test/TestStores` doing the wiring.