@smthrs/engine-store 1.0.0-rc.6 → 1.0.0-rc.8

package/docs/README.md

@@ -11,7 +11,9 @@ over.
 It is an [Effect](https://effect.website) library: every surface below is a
 `Layer` you compose or an `Effect` you run.
 
-Not on npm yet; see [Installation](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/flow/docs/installation.md#use-the-libraries).
+```bash
+npm install @smthrs/engine-store@next effect
+```
 
 ## What it solves
 

package/docs/api.md

@@ -369,16 +369,16 @@ interface Service {
 }
 ```
 
-| Export              | Signature                                                                                                | Meaning                                                                                                                       |
-| ------------------- | -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| `StepBoundary`      | `Context.Service<Service>`                                                                               | Service tag.                                                                                                                  |
-| `make`              | `(service: Service) => Service`                                                                          | Brands an implementation, so a wrong shape is reported where it is written.                                                   |
-| `makeFileSystem`    | `(fs: FileSystem, path: Path, artifacts: ArtifactStore.Service, options?: FileSystemOptions) => Service` | The production boundary.                                                                                                      |
-| `layer`             | `Layer<Service, never, FileSystem \| Path \| ArtifactStore>`                                             | Provides it, confining replay to the kernel `Workspace` root when one is in context. Resolves that root with the host `Path`. |
-| `layerTest`         | `(options?: TestOptions) => Layer<Service>`                                                              | Deterministic in-memory boundary.                                                                                             |
-| `exactReads`        | `(descriptor: FileBoundary) => ReadonlyArray<FileInput>`                                                 | Exact read inputs, ignoring declarations that still need expansion.                                                           |
-| `readSetMatches`    | `(prepared: PreparedBoundary) => boolean`                                                                | Whether the measured snapshot still matches the declaration.                                                                  |
-| `referencedDigests` | `(evidence: BoundaryEvidence) => ReadonlyArray<ArtifactStore.Digest>`                                    | The digests the evidence references rather than inlines. Evidence from a foreign implementation yields the empty list.        |
+| Export              | Signature                                                                                                | Meaning                                                                                                                                     |
+| ------------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `StepBoundary`      | `Context.Service<Service>`                                                                               | Service tag.                                                                                                                                |
+| `make`              | `(service: Service) => Service`                                                                          | Brands an implementation, so a wrong shape is reported where it is written.                                                                 |
+| `makeFileSystem`    | `(fs: FileSystem, path: Path, artifacts: ArtifactStore.Service, options?: FileSystemOptions) => Service` | The production boundary.                                                                                                                    |
+| `layer`             | `Layer<Service, never, FileSystem \| Path \| ArtifactStore>`                                             | Provides it, rooting measurement and replay at the kernel `Workspace` root when one is in context. Resolves that root with the host `Path`. |
+| `layerTest`         | `(options?: TestOptions) => Layer<Service>`                                                              | Deterministic in-memory boundary.                                                                                                           |
+| `exactReads`        | `(descriptor: FileBoundary) => ReadonlyArray<FileInput>`                                                 | Exact read inputs, ignoring declarations that still need expansion.                                                                         |
+| `readSetMatches`    | `(prepared: PreparedBoundary) => boolean`                                                                | Whether the measured snapshot still matches the declaration.                                                                                |
+| `referencedDigests` | `(evidence: BoundaryEvidence) => ReadonlyArray<ArtifactStore.Digest>`                                    | The digests the evidence references rather than inlines. Evidence from a foreign implementation yields the empty list.                      |
 
 ### Schemas
 
@@ -393,11 +393,11 @@ interface Service {
 
 ### FileSystemOptions
 
-| Field                 | Default | Meaning                                                                                                                      |
-| --------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- |
-| `maxInlineBytes`      | 1 MiB   | The largest single output inlined into the evidence. Anything larger is stored by digest reference.                          |
-| `maxTotalInlineBytes` | 8 MiB   | The largest aggregate inline payload one settle may fold in. Past it, an output is spilled even though it individually fits. |
-| `root`                | cwd     | The root replay confines writes and removals to. A filesystem already confined to a root keeps its own.                      |
+| Field                 | Default | Meaning                                                                                                                                                                                 |
+| --------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `maxInlineBytes`      | 1 MiB   | The largest single output inlined into the evidence. Anything larger is stored by digest reference.                                                                                     |
+| `maxTotalInlineBytes` | 8 MiB   | The largest aggregate inline payload one settle may fold in. Past it, an output is spilled even though it individually fits.                                                            |
+| `root`                | cwd     | The root declared paths resolve against: `prepare` and `settle` measure under it, and replay confines writes and removals to it. A filesystem already confined to a root keeps its own. |
 
 `replayOutputs` writes and deletes what the evidence names, so it confines its
 own mutations instead of trusting the composition. Every write, removal, probe,
@@ -406,7 +406,10 @@ one descriptor-relative, no-follow request per call against the pinned root. A
 symlink on a replayed path (a parent, the final component, or a member of a
 replayed tree) refuses with `UnsupportedBoundary`, and so does a host with no
 descriptor-relative executor or isolation attestation, before any host call.
-`prepare` and `settle` only read and keep the caller's filesystem.
+`prepare` and `settle` only read and keep the caller's filesystem, but hand a
+path-based host each declared path resolved against `root`, the root a step's
+own FileSystem resolves against. A same-named file in the process working
+directory therefore never answers the dirty check (issue #3911).
 
 ### TestOptions
 
@@ -892,7 +895,10 @@ durable fails and the shared entry is withheld.
 
 `hydrate(digests)` establishes that this host can resolve every referenced
 artifact and reports whether the replay is now worth retrying. It never fails a
-run: a shared tier that is down must not stop work that can simply be done.
+run: a shared tier that is down must not stop work that can simply be done. A
+downloaded blob counts only when this host's store files it under the requested
+digest, so a shared tier that serves the wrong bytes costs the replay, never
+its correctness.
 
 The two tiers cannot both be layers, because they inhabit the same tag and
 composing them would shadow one with the other.

package/docs/concepts/attempts-and-replay.md

@@ -30,15 +30,21 @@ question, answered in [Cache admission](./cache-admission.md).
 | ------------- | ------------------------------------------------------------------------------------------------------------------------------- |
 | `succeeded`   | Returns the recorded result, and calls `StepBoundary.replayOutputs` first so the workspace holds the outputs the step produced. |
 | `failed`      | Rethrows the persisted domain failure. It never re-admits the attempt.                                                          |
-| `running`     | Recovers under the run fence and shared admission permit, honoring any recorded effect crossing.                                |
+| `running`     | Asks the step cache first when the step is cache-eligible, then recovers under the run fence and admission permit.              |
 | `suspended`   | Continues the same attempt rather than burning a new one against the retry budget.                                              |
 
-An admitted attempt remains authoritative when a matching shared cache row
+A settled attempt remains authoritative when a matching shared cache row
 exists; another run's cached success cannot replace its result or failure.
 Failure values were schema-encoded before persistence, so a `_tag` survives
 the JSON round trip and a `RetryPolicy`'s non-retryable matching still applies
 on replay.
 
+A `running` attempt has no result of its own. When its step is cache-eligible
+(sealed, with a hard boundary), a verified row another run recorded under the
+same key answers it, and the row is closed as `succeeded` with that result. A
+recorded successful effect crossing still wins over the cache, because it
+carries this run's own result.
+
 ## Which columns are redacted
 
 Attempt and run rows share a database with the journal, so failure text meets
@@ -62,6 +68,13 @@ A permit covers one run and step key through admission, execution, and
 settlement. Concurrent same-key dispatches wait, then replay the settled
 attempt instead of executing another body. Interruption releases the permit.
 
+A cache-eligible dispatch also holds a permit for its cache address, which runs
+share. A second run that asks one engine for a step that engine is already
+computing waits, then takes the first run's cache row instead of running the
+body beside it. Engines in other processes are not excluded: two processes can
+still execute one key at once, and the second recording resolves as described
+in [Cache admission](./cache-admission.md).
+
 Holding the permit and the run fence permits recovery of a stranded `running`
 attempt. A recorded successful effect crossing supplies the result directly;
 an unresolved irreversible crossing requires an idempotency key before retry.

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

@@ -110,10 +110,16 @@ file (`store.sqlite3`), an `objects` directory, and a `restored.json` marker, an
 is a fresh store directory to compose `NodeDatabase.layer` and
 `ArtifactStore.layerFileSystem` over.
 
+A failed restore removes what it wrote, so nothing store-shaped is left in the
+target and you can retry into the same directory. A target that was not empty
+is refused with `not_empty` and left untouched.
+
 `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`.
+`FencedRestoredStore`. When fencing refuses, `restoreAndFence` also removes the
+restored files, so no engine can adopt a store that still carries pre-backup
+owners.
 
 ## What fencing does
 
@@ -149,8 +155,8 @@ its own fresh owner.
 | `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.                          |
+| `digest_mismatch`     | A backup file does not hash to its manifest digest.           |
+| `artifact_corruption` | A live blob does not hash to its address during a backup.     |
 | `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.    |

package/docs/guides/reclaim-runs-from-a-dead-host.md

@@ -93,6 +93,22 @@ at the staleness cutoff. A deferral is forgotten as soon as the row leaves the
 stale window, so a fresh stall under a new lease is probed on the first tick
 that sees it.
 
+## What a reclaimed run does with its unfinished step
+
+The step that was running when the owner died left an attempt row in state
+`running`. The re-drive reaches that attempt again, and what it does depends on
+the step:
+
+- A cache-eligible step (sealed, with a hard boundary) asks the step cache
+  first. When another run already recorded the same key, for example the run
+  you started to replace the killed one, the reclaimed attempt takes that
+  result and the body does not run again. When that run is still computing it
+  in the same process, the reclaimed attempt waits for it.
+- Any other step re-executes under its original attempt number. An
+  irreversible step whose effect was dispatched but never recorded as settled
+  needs an idempotency key to re-execute; without one the run fails with
+  `IrreversibleRetryRequiresIdempotencyKey`.
+
 ## Check a run's own view
 
 `DurableEngineState` answers directly, which is useful in a diagnostic tool:

package/docs/installation.md

@@ -7,7 +7,11 @@ sidebar:
 
 ## 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).
+```bash
+npm install @smthrs/engine-store@next effect
+```
+
+The `next` tag carries the 1.0 release candidates.
 
 The package requires Node.js 26.4.0 or later and ships as both ESM and
 CommonJS with TypeScript declarations. Its runtime dependencies, including

package/docs/quickstart.md

@@ -13,7 +13,11 @@ the whole point of the package.
 ## Prerequisites
 
 - Node.js 26.4.0 or later.
-- A package with the dependencies installed. Not on npm yet; see [Installation](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/flow/docs/installation.md#use-the-libraries).
+- A project with the packages installed:
+
+  ```bash
+  npm install @smthrs/engine-store@next @smthrs/artifacts@next @smthrs/database@next @smthrs/flow@next @smthrs/journal@next @smthrs/kernel@next @smthrs/platform-node@next @smthrs/run-store@next @smthrs/step-cache@next @effect/platform-node effect
+  ```
 
 ## Declare a sealed action and a flow
 
@@ -193,6 +197,10 @@ console.log(await Effect.runPromise(main("./.quickstart/.flows/engine.db", "./.q
 { first: '42', second: '42', executions: 1 }
 ```
 
+The assembled program is
+[`examples/quickstart.ts`](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/engine-store/examples/quickstart.ts);
+the package's test suite runs it on every change.
+
 ## What just happened
 
 The first run claimed `analyse-1`, opened an attempt row for the sealed step,

package/docs/troubleshooting.md

@@ -304,6 +304,9 @@ migrations omit or rename a historical entry recorded in the manifest. Forward
 additions within installed lower blocks are compatible; check historical IDs
 and names before fencing again.
 
+A failed backup, `restore`, or `restoreAndFence` removes the files it wrote, so
+fix the cause and retry into the same directory.
+
 ## The composition does not compile
 
 **What happened.** A required service is missing. A composition failure is an

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@smthrs/engine-store",
   "type": "module",
-  "version": "1.0.0-rc.6",
+  "version": "1.0.0-rc.8",
   "license": "MIT",
   "smthrs": {
     "group": "engine"
@@ -386,29 +386,29 @@
     "tag": "next"
   },
   "dependencies": {
-    "@smthrs/artifacts": "1.0.0-rc.6",
-    "@smthrs/canonical": "1.0.0-rc.6",
-    "@smthrs/crypto": "1.0.0-rc.6",
-    "@smthrs/database": "1.0.0-rc.6",
-    "@smthrs/engine": "1.0.0-rc.6",
-    "@smthrs/flow": "1.0.0-rc.6",
-    "@smthrs/journal": "1.0.0-rc.6",
-    "@smthrs/kernel": "1.0.0-rc.6",
-    "@smthrs/keys": "1.0.0-rc.6",
-    "@smthrs/plan": "1.0.0-rc.6",
-    "@smthrs/plan-store": "1.0.0-rc.6",
-    "@smthrs/run-store": "1.0.0-rc.6",
-    "@smthrs/step-cache": "1.0.0-rc.6",
-    "@smthrs/capability": "1.0.0-rc.6"
+    "@smthrs/artifacts": "1.0.0-rc.8",
+    "@smthrs/canonical": "1.0.0-rc.8",
+    "@smthrs/crypto": "1.0.0-rc.8",
+    "@smthrs/database": "1.0.0-rc.8",
+    "@smthrs/engine": "1.0.0-rc.8",
+    "@smthrs/flow": "1.0.0-rc.8",
+    "@smthrs/journal": "1.0.0-rc.8",
+    "@smthrs/kernel": "1.0.0-rc.8",
+    "@smthrs/keys": "1.0.0-rc.8",
+    "@smthrs/plan": "1.0.0-rc.8",
+    "@smthrs/plan-store": "1.0.0-rc.8",
+    "@smthrs/run-store": "1.0.0-rc.8",
+    "@smthrs/step-cache": "1.0.0-rc.8",
+    "@smthrs/capability": "1.0.0-rc.8"
   },
   "devDependencies": {
     "@effect/language-service": "0.87.2",
     "@effect/platform-node": "4.0.4",
     "@effect/vitest": "4.0.4",
     "@eslint/js": "9.39.5",
-    "@smthrs/core": "1.0.0-rc.6",
-    "@smthrs/patterns": "1.0.0-rc.6",
-    "@smthrs/platform-node": "1.0.0-rc.6",
+    "@smthrs/core": "1.0.0-rc.8",
+    "@smthrs/patterns": "1.0.0-rc.8",
+    "@smthrs/platform-node": "1.0.0-rc.8",
     "@types/node": "26.4.1",
     "@vitest/coverage-v8": "5.0.0",
     "dprint": "0.57.1",

package/src/ArtifactSync.ts

@@ -241,6 +241,13 @@ export const make = (options: {
         // them written into this workspace.
         const written = yield* remote.get(digest).pipe(
           Effect.flatMap((bytes) => local.put(bytes)),
+          // A custom tier may skip that verification; the address `put`
+          // returned is the proof the requested blob is now local.
+          Effect.flatMap((address) =>
+            address === digest ?
+              Effect.void :
+              Effect.fail({ message: `the shared tier served the bytes of ${address}` })
+          ),
           Effect.tapError(fallBack("the artifact could not be fetched", [digest])),
           Effect.option
         )

package/src/DisasterRecovery.ts

@@ -407,6 +407,23 @@ const ensureEmptyDirectory = (
     }
   })
 
+/**
+ * Removes every entry of a directory this module filled after admitting it
+ * empty, leaving the directory reusable for a retry. Cleanup is best effort;
+ * the caller reports the original failure.
+ */
+const discardEntries = (fs: FileSystem.FileSystem, directory: string): Effect.Effect<void> =>
+  fs.readDirectory(directory).pipe(
+    Effect.flatMap((entries) =>
+      Effect.forEach(
+        entries,
+        (entry) => fs.remove(`${directory}/${entry}`, { recursive: true, force: true }),
+        { discard: true }
+      )
+    ),
+    Effect.ignore
+  )
+
 /**
  * A relative blob path in the store's fanout layout: a two-hex directory
  * holding a 64-hex digest that begins with it. Anything else under the
@@ -660,18 +677,8 @@ export const backup = <R = never, E = never>(
     // The directory was empty when the capture began, so everything in it is
     // this capture's: the snapshot, any SQLite sidecar the inspection
     // connection left, and the copied blobs. A failed capture removes them and
-    // leaves the directory reusable for a retry. Cleanup is best effort; the
-    // original failure is the one reported.
-    const discardPartial = fs.readDirectory(options.directory).pipe(
-      Effect.flatMap((entries) =>
-        Effect.forEach(
-          entries,
-          (entry) => fs.remove(`${options.directory}/${entry}`, { recursive: true, force: true }),
-          { discard: true }
-        )
-      ),
-      Effect.ignore
-    )
+    // leaves the directory reusable for a retry.
+    const discardPartial = discardEntries(fs, options.directory)
 
     return yield* (options.objectsDirectory === undefined
       ? capture
@@ -719,6 +726,57 @@ export const verify = Effect.fn("DisasterRecovery.verify")(function*(
   return manifest
 })
 
+/** Copies a verified backup into an admitted empty target directory. */
+const writeRestoredStore = (
+  fs: FileSystem.FileSystem,
+  options: RestoreOptions,
+  manifest: BackupManifest,
+  maxFileSizeBytes: number
+): Effect.Effect<RestoredStore, DisasterRecoveryError, Crypto.Crypto> =>
+  Effect.gen(function*() {
+    const databaseBytes = yield* checkedFile(
+      fs,
+      "restore",
+      `${options.backupDirectory}/${manifest.database.file}`,
+      manifest.database.sha256,
+      maxFileSizeBytes
+    )
+    const databaseFile = `${options.targetDirectory}/${databaseFileName}`
+    yield* fs.writeFile(databaseFile, databaseBytes).pipe(
+      Effect.mapError(ioFailure("restore", `writing ${databaseFile}`))
+    )
+
+    const objectsDirectory = `${options.targetDirectory}/${objectsDirectoryName}`
+    for (const entry of manifest.artifacts) {
+      const bytes = yield* checkedFile(
+        fs,
+        "restore",
+        blobPath(`${options.backupDirectory}/${objectsDirectoryName}`, entry.digest),
+        entry.digest,
+        maxFileSizeBytes
+      )
+      yield* fs.makeDirectory(`${objectsDirectory}/${entry.digest.slice(0, 2)}`, { recursive: true }).pipe(
+        Effect.mapError(ioFailure("restore", `creating the objects directory for ${entry.digest}`))
+      )
+      yield* fs.writeFile(blobPath(objectsDirectory, entry.digest), bytes).pipe(
+        Effect.mapError(ioFailure("restore", `writing the blob for ${entry.digest}`))
+      )
+    }
+
+    const restoredAtMs = yield* Clock.currentTimeMillis.pipe(Effect.map(Math.floor))
+    const marker = {
+      formatVersion: 1,
+      restoredAtMs,
+      backupCreatedAtMs: manifest.createdAtMs,
+      databaseSha256: manifest.database.sha256
+    }
+    yield* fs.writeFileString(
+      `${options.targetDirectory}/${restoredMarkerFileName}`,
+      `${JSON.stringify(marker, null, 2)}\n`
+    ).pipe(Effect.mapError(ioFailure("restore", `writing ${restoredMarkerFileName}`)))
+    return { databaseFile, objectsDirectory, manifest } satisfies RestoredStore
+  })
+
 /**
  * Restores a verified backup into an empty target directory.
  *
@@ -728,7 +786,8 @@ export const verify = Effect.fn("DisasterRecovery.verify")(function*(
  * is a fresh store directory to compose `NodeDatabase.layer` and
  * `ArtifactStore.layerFileSystem` over. The database is restored with the
  * pre-backup owner fences still in place — run {@link fence} against it
- * before any engine adopts it.
+ * before any engine adopts it. A failed copy removes everything it wrote, so
+ * the target is left empty and reusable for a retry.
  *
  * @since 0.1.0
  * @category operations
@@ -741,47 +800,13 @@ export const restore = Effect.fn("DisasterRecovery.restore")(function*(options:
   const manifest = yield* readManifest(fs, "restore", options.backupDirectory, maxFileSizeBytes)
   yield* ensureEmptyDirectory(fs, "restore", options.targetDirectory)
 
-  const databaseBytes = yield* checkedFile(
-    fs,
-    "restore",
-    `${options.backupDirectory}/${manifest.database.file}`,
-    manifest.database.sha256,
-    maxFileSizeBytes
-  )
-  const databaseFile = `${options.targetDirectory}/${databaseFileName}`
-  yield* fs.writeFile(databaseFile, databaseBytes).pipe(
-    Effect.mapError(ioFailure("restore", `writing ${databaseFile}`))
+  // The target was empty when the copy began, so everything in it is this
+  // restore's. A refused blob or a failed write removes the partial store, so
+  // nothing store-shaped is left to compose over and a retry can reuse it.
+  return yield* Effect.onError(
+    writeRestoredStore(fs, options, manifest, maxFileSizeBytes),
+    () => discardEntries(fs, options.targetDirectory)
   )
-
-  const objectsDirectory = `${options.targetDirectory}/${objectsDirectoryName}`
-  for (const entry of manifest.artifacts) {
-    const bytes = yield* checkedFile(
-      fs,
-      "restore",
-      blobPath(`${options.backupDirectory}/${objectsDirectoryName}`, entry.digest),
-      entry.digest,
-      maxFileSizeBytes
-    )
-    yield* fs.makeDirectory(`${objectsDirectory}/${entry.digest.slice(0, 2)}`, { recursive: true }).pipe(
-      Effect.mapError(ioFailure("restore", `creating the objects directory for ${entry.digest}`))
-    )
-    yield* fs.writeFile(blobPath(objectsDirectory, entry.digest), bytes).pipe(
-      Effect.mapError(ioFailure("restore", `writing the blob for ${entry.digest}`))
-    )
-  }
-
-  const restoredAtMs = yield* Clock.currentTimeMillis.pipe(Effect.map(Math.floor))
-  const marker = {
-    formatVersion: 1,
-    restoredAtMs,
-    backupCreatedAtMs: manifest.createdAtMs,
-    databaseSha256: manifest.database.sha256
-  }
-  yield* fs.writeFileString(
-    `${options.targetDirectory}/${restoredMarkerFileName}`,
-    `${JSON.stringify(marker, null, 2)}\n`
-  ).pipe(Effect.mapError(ioFailure("restore", `writing ${restoredMarkerFileName}`)))
-  return { databaseFile, objectsDirectory, manifest } satisfies RestoredStore
 })
 
 /**
@@ -868,10 +893,12 @@ export const fence = Effect.fn("DisasterRecovery.fence")(function*(manifest: Bac
 /**
  * Restores a backup and immediately fences the restored database.
  *
- * This is the one-shot operator API for disaster recovery. The database
- * driver itself still arrives through a caller-supplied Layer so this module
- * remains host-neutral and browser-bundleable; the bundled Node script passes
- * `NodeDatabase.layer` for the restored file.
+ * This is the one-shot operator API for disaster recovery. When fencing
+ * refuses, the restored files are removed, so no engine can adopt a store that
+ * still carries pre-backup owners. The database driver itself still arrives
+ * through a caller-supplied Layer so this module remains host-neutral and
+ * browser-bundleable; the bundled Node script passes `NodeDatabase.layer` for
+ * the restored file.
  *
  * @since 0.1.0
  * @category operations
@@ -880,9 +907,14 @@ export const restoreAndFence = <R = never, E = never>(
   options: RestoreAndFenceOptions<R, E>
 ): Effect.Effect<FencedRestoredStore, DisasterRecoveryError | E, FileSystem.FileSystem | Crypto.Crypto | R> =>
   Effect.gen(function*() {
+    const fs = yield* FileSystem.FileSystem
     const restored = yield* restore(options)
+    // A refused fence leaves a database that still carries pre-backup owner
+    // fences beside a `restored.json` marker. Remove the whole restore so no
+    // engine can adopt it and the operator can retry into the same target.
     const summary = yield* fence(restored.manifest).pipe(
-      Effect.provide(options.databaseLayer(restored.databaseFile))
+      Effect.provide(options.databaseLayer(restored.databaseFile)),
+      Effect.onError(() => discardEntries(fs, options.targetDirectory))
     )
     return { ...restored, fence: summary } satisfies FencedRestoredStore
   })

package/src/StepBoundary.ts

@@ -496,12 +496,14 @@ export interface FileSystemOptions {
    */
   readonly maxTotalInlineBytes?: number | undefined
   /**
-   * The workspace root cache replay confines its writes, removals, and prune
-   * walk to. A filesystem already confined to a root (the kernel-guarded
-   * layer's service, or a `confined` view) keeps its own root and ignores
-   * this. Otherwise it defaults to the process working directory, the root a
-   * path-based host resolves `prepare` and `settle` against. {@link layer}
-   * passes the kernel `Workspace` root when one is in context.
+   * The workspace root every declared path resolves against: `prepare` and
+   * `settle` measure under it, and cache replay confines its writes, removals,
+   * and prune walk to it. A filesystem already confined to a root (the
+   * kernel-guarded layer's service, or a `confined` view) keeps its own root
+   * and ignores this. Otherwise it defaults to the process working directory,
+   * the root a path-based host resolves a relative path against. {@link layer}
+   * passes the kernel `Workspace` root when one is in context, which is the
+   * root a step's own FileSystem resolves against (issue #3911).
    */
   readonly root?: string | undefined
 }
@@ -573,7 +575,16 @@ export const makeFileSystem = (
     const digest = yield* Schema.decodeUnknownEffect(Sha256)(bytes).pipe(Effect.orDie)
     return { digest, bytes } satisfies MeasuredDigest
   })
-  const readDigest = (path: string) => readDigestFrom(fs, path)
+  // Declared paths are workspace-relative. A confined filesystem resolves them
+  // against its own root, but a path-based host resolves them against the
+  // process working directory, where a same-named file would answer the dirty
+  // check and let a stale declaration serve a cache hit (issue #3911). Such a
+  // host is handed each path resolved against the configured root; results
+  // stay keyed by the declared path.
+  const readRoot = KernelFileSystem.confinedRoot(fs) === undefined ? options.root : undefined
+  const hostPath = (path: string): string => readRoot === undefined ? path : platformPath.resolve(readRoot, path)
+  const enumeration: FileEnumeration.EnumerationOptions = readRoot === undefined ? {} : { resolve: hostPath }
+  const readDigest = (path: string) => readDigestFrom(fs, hostPath(path))
   const batch = KernelFileSystem.batch(fs)
   const measurements = Effect.fn("StepBoundary.measurements")(
     function*(paths: ReadonlyArray<string>, content: boolean) {
@@ -594,7 +605,7 @@ export const makeFileSystem = (
         const response = yield* batch.execute(
           paths.slice(offset, offset + batch.maxSize).map((path) => ({
             operation: "digest",
-            path,
+            path: hostPath(path),
             content
           }))
         ).pipe(Effect.mapError(hostFailure))
@@ -636,10 +647,14 @@ export const makeFileSystem = (
   // workspace-relative expansion and let a tree replay delete dotfiles the
   // producer wrote.
   const expandGlob = Effect.fn("StepBoundary.expandGlob")(function*(glob: FileSet.Glob) {
-    return yield* FileEnumeration.expandGlob(fs, glob).pipe(Effect.mapError(hostFailure))
+    return yield* FileEnumeration.expandGlob(fs, glob, enumeration).pipe(Effect.mapError(hostFailure))
   })
-  const treeEntries = Effect.fn("StepBoundary.treeEntries")(function*(host: FileSystem.FileSystem, path: string) {
-    return yield* FileEnumeration.entriesUnder(host, path).pipe(Effect.mapError(hostFailure))
+  const treeEntries = Effect.fn("StepBoundary.treeEntries")(function*(
+    host: FileSystem.FileSystem,
+    path: string,
+    resolution: FileEnumeration.EnumerationOptions
+  ) {
+    return yield* FileEnumeration.entriesUnder(host, path, resolution).pipe(Effect.mapError(hostFailure))
   })
   // Replay writes and deletes what evidence names, so the lexical check alone
   // is not a boundary: a symlink planted on a lexically valid path would carry
@@ -647,7 +662,7 @@ export const makeFileSystem = (
   // its prune walk go through a view pinned to the root, where each call is
   // one descriptor-relative, no-follow request and a symlink anywhere on the
   // path is refused rather than followed. `prepare` and `settle` only read,
-  // and keep the caller's filesystem.
+  // and keep the caller's filesystem, rooted through `hostPath`.
   const replayRoot = KernelFileSystem.confinedRoot(fs) ?? options.root ?? "."
   const replayHost: Effect.Effect<FileSystem.FileSystem, UnsupportedBoundary> = KernelFileSystem.isConfinable(fs)
     ? KernelFileSystem.confined(fs, replayRoot).pipe(
@@ -849,7 +864,7 @@ export const makeFileSystem = (
         if (typeof entry === "string") outputPaths.push(entry)
         else if (entry._tag === "Glob") outputPaths.push(...yield* expandGlob(entry))
         else {
-          const files = (yield* treeEntries(fs, entry.path)).files
+          const files = (yield* treeEntries(fs, entry.path, enumeration)).files
           outputPaths.push(...files)
           treeMembers.push({ path: entry.path, files })
         }
@@ -1007,7 +1022,7 @@ export const makeFileSystem = (
             .map((output) => output.path)
             .filter((path) => path.startsWith(prefix))
         )
-        const entries = yield* treeEntries(host, tree.path)
+        const entries = yield* treeEntries(host, tree.path, {})
         for (const path of entries.files) {
           if (!recorded.has(path)) yield* host.remove(path).pipe(Effect.mapError(hostFailure))
         }

package/src/index.ts

@@ -67,7 +67,21 @@ export * as RunChangeFeed from "./RunChangeFeed.ts"
  * @category services
  */
 export * as PlanInputStore from "./PlanInputStore.ts"
+
+/**
+ * Owner-fenced plan merge decisions, recorded before a merge is appended.
+ *
+ * @since 1.0.0
+ * @category services
+ */
 export * as PlanMergeStore from "./PlanMergeStore.ts"
+
+/**
+ * Drives a persisted plan: the node scheduler.
+ *
+ * @since 0.1.0
+ * @category services
+ */
 export * as PlanScheduler from "./PlanScheduler.ts"
 
 /**