chainlesschain 0.166.105 → 0.166.107

package/src/lib/cli-goal-source.js

@@ -0,0 +1,119 @@
+/** Bounded standalone file reads shared by explicit CLI snapshots. */
+import fs from "node:fs";
+import { createHash } from "node:crypto";
+import { createGoalFileAdapter } from "./goal-store.js";
+
+function fail(code) {
+  throw new Error(code);
+}
+function sameFile(a, b) {
+  return (
+    a.dev === b.dev &&
+    a.ino === b.ino &&
+    a.size === b.size &&
+    a.mtimeMs === b.mtimeMs &&
+    a.ctimeMs === b.ctimeMs
+  );
+}
+
+/** Pin the configured store, including directory identity, for this snapshot. */
+function sourceReader(root, onRead) {
+  const realRoot = fs.realpathSync(root);
+  const initialRoot = fs.statSync(root);
+  function checkRoot() {
+    const stat = fs.statSync(root);
+    if (
+      !stat.isDirectory() ||
+      fs.realpathSync(root) !== realRoot ||
+      stat.dev !== initialRoot.dev ||
+      stat.ino !== initialRoot.ino
+    )
+      fail("CLI_GOAL_STORE_CHANGED");
+  }
+  const readJson = (file) => {
+    checkRoot();
+    const entry = fs.lstatSync(file);
+    if (!entry.isFile() || entry.isSymbolicLink())
+      fail("CLI_GOAL_REGULAR_FILE_REQUIRED");
+    let fd;
+    try {
+      fd = fs.openSync(
+        file,
+        fs.constants.O_RDONLY |
+          (fs.constants.O_NOFOLLOW || 0) |
+          (fs.constants.O_NONBLOCK || 0),
+      );
+      const before = fs.fstatSync(fd);
+      if (!before.isFile() || !sameFile(entry, before))
+        fail("CLI_GOAL_SOURCE_CHANGED");
+      if (before.size > 64 * 1024) fail("CLI_GOAL_SOURCE_TOO_LARGE");
+      const buffer = Buffer.alloc(before.size + 1);
+      let count = 0;
+      while (count < buffer.length) {
+        const size = fs.readSync(
+          fd,
+          buffer,
+          count,
+          buffer.length - count,
+          count,
+        );
+        if (!size) break;
+        count += size;
+      }
+      checkRoot();
+      const after = fs.lstatSync(file);
+      if (
+        count !== before.size ||
+        !sameFile(before, fs.fstatSync(fd)) ||
+        !after.isFile() ||
+        after.isSymbolicLink() ||
+        !sameFile(before, after)
+      )
+        fail("CLI_GOAL_SOURCE_CHANGED");
+      const bytes = buffer.subarray(0, count);
+      const value = JSON.parse(
+        new TextDecoder("utf-8", { fatal: true }).decode(bytes),
+      );
+      onRead(createHash("sha256").update(bytes).digest("hex"));
+      return value;
+    } finally {
+      if (fd !== undefined) fs.closeSync(fd);
+    }
+  };
+  return { readJson, checkRoot };
+}
+
+export function createCliGoalSnapshotReader(root) {
+  let rawDigest;
+  const source = sourceReader(root, (value) => {
+    rawDigest = value;
+  });
+  const adapter = createGoalFileAdapter({ root, readJson: source.readJson });
+  function read(id) {
+    const goal = adapter.get(id);
+    if (!goal) fail("CLI_GOAL_NOT_FOUND");
+    return { goal, digest: rawDigest };
+  }
+  function revalidate(snapshot) {
+    let current;
+    try {
+      current = read(snapshot.goal.id);
+    } catch {
+      fail("CLI_GOAL_SOURCE_CHANGED");
+    }
+    if (
+      current.digest !== snapshot.digest ||
+      current.goal.storeId !== snapshot.goal.storeId ||
+      current.goal.revision !== snapshot.goal.revision ||
+      current.goal.controlGeneration !== snapshot.goal.controlGeneration
+    )
+      fail("CLI_GOAL_SOURCE_CHANGED");
+    return current.goal;
+  }
+  return {
+    storeId: adapter.storeId,
+    read,
+    revalidate,
+    checkRoot: source.checkRoot,
+  };
+}

package/src/lib/coding-task-guidance.js

@@ -1,10 +1,12 @@
 /** Shared correctness guidance for normal and file-only coding sessions. */
 export const CODING_TASK_QUALITY_GUIDANCE = `Coding task quality:
 - Read the actual implementation and its exported API before writing a caller or test. Check parameter order, return shapes, asynchronous lifecycle and fixture requirements against the source; an example in another directory can have different relative imports.
+- Keep progress explanations to one or two sentences. Once the relevant API and behavior are clear, make the next tool call; resolve a remaining uncertainty with a targeted read. Put implementation code directly in write/edit tool arguments instead of rehearsing the code or repeatedly analyzing the same source in ordinary assistant text.
 - Resolve each relative import from the destination file's directory. Read back the completed file and fix newDiagnostics from write/edit results before finishing. A successful write confirms persistence, not syntax, test execution or acceptance.
 - Regression tests need a working positive control and a negative control that exercises the requested behavior through the real production entry point. Assert observable effects; avoid mocks or alternate calls that bypass the behavior under test. Complete the current worker/request when testing cancellation and replacement.
+- For boundary regressions, derive expected defaults, computed values and rejection rules from the implementation or the explicit requested contract. Inject mismatched, tampered or stale input through the real entry point while keeping other prerequisites valid; verify that the fixture reaches the intended check rather than failing during setup. Compare observable results with independent expected values or authoritative state, not a helper that merely recomputes the same result.
 - Use available execution tools for a focused check when permitted. When execution tools are unavailable, inspect imports, API contracts and fixtures using the available file tools, and clearly say that tests were not run. Never describe a read-back or static check as a passing test or end-to-end verification.
-- Finish requested file changes before the final response. For large files, write a smaller complete section and extend it with bounded edits; do not spend the remaining output budget repeatedly rewriting the entire file. State what was delivered, what was checked and what remains unverified.`;
+- Finish requested file changes before the final response. Reserve output and remaining requests for writing, read-back and focused validation. For large files, aim for a few thousand characters of new content per call: write a small complete section, then extend it with edit_file using a unique existing anchor and a replacement containing that anchor plus the next complete section. Keep each tool call complete and wait for its result before extending the file again; do not repeatedly rewrite the growing file. State what was delivered, what was checked and what remains unverified.`;
 
 export const HERMETIC_CODING_SYSTEM_PROMPT = `You are a hermetic coding assistant. The exposed file tools are the complete tool surface. Inspect and mutate only the exact paths authorized by the user request. Do not invoke hidden tools, commands, language servers or other execution paths.
 

package/src/lib/config-schema.js

@@ -83,7 +83,7 @@ const DESCRIPTORS = [
       "Requested live service tier; model and endpoint support are checked before dispatch",
   }),
   descriptor("llm.visionModel", ["string", "null"], {
-    description: "Model used for image turns",
+    description: "Fallback for image turns when the main model lacks vision",
   }),
   descriptor("llm.fallbackModel", ["string", "null"], {
     deprecated: true,

package/src/lib/eval/stream-terminal.js

@@ -1,5 +1,5 @@
 /** Parse raw agent NDJSON. A declaration of success is never terminal evidence. */
-export function verifyAgentTerminal(output) {
+export function verifyAgentTerminal(output, { allowSessionEnd = false } = {}) {
   try {
     const events = output
       .split(/\r?\n/u)
@@ -7,6 +7,31 @@ export function verifyAgentTerminal(output) {
       .map((line) => JSON.parse(line));
     const results = events.filter((event) => event?.type === "result");
     const terminal = results[0];
+    const last = events.at(-1);
+    const init = events.find(
+      (event) => event?.type === "system" && event.subtype === "init",
+    );
+    const sessionEnded =
+      allowSessionEnd &&
+      events.at(-2) === terminal &&
+      last?.type === "system" &&
+      last.subtype === "end" &&
+      typeof terminal?.session_id === "string" &&
+      terminal.session_id.length > 0 &&
+      last.session_id === terminal.session_id &&
+      init?.session_id === terminal.session_id &&
+      typeof terminal.trace_id === "string" &&
+      terminal.trace_id.length > 0 &&
+      last.trace_id === terminal.trace_id &&
+      Number.isSafeInteger(terminal.seq) &&
+      terminal.seq > 0 &&
+      last.seq === terminal.seq + 1 &&
+      Number.isSafeInteger(terminal.turn) &&
+      terminal.turn > 0 &&
+      last.turns === terminal.turn &&
+      events.filter(
+        (event) => event?.type === "system" && event.subtype === "end",
+      ).length === 1;
     const usage = terminal?.usage;
     const normalizedUsage =
       usage &&
@@ -26,7 +51,7 @@ export function verifyAgentTerminal(output) {
     return {
       terminalVerified:
         results.length === 1 &&
-        events.at(-1) === terminal &&
+        (last === terminal || sessionEnded) &&
         terminal.subtype === "success" &&
         terminal.is_error === false &&
         !events.some((event) => event?.type === "error"),

package/src/lib/evolution/evolution-artifact-ports.js

@@ -23,6 +23,11 @@ import {
 } from "./evolution-ledger.js";
 
 const ARTIFACT_STORE_DIRECTORY_BOUNDARIES = new WeakMap();
+// Capture repository function identity before binding instance methods. Only
+// these exact defaults may skip legacy list/get I/O; overrides still execute
+// and must match the independently authenticated descriptor snapshots.
+const DEFAULT_STORE_LIST = ArtifactStore.prototype.list;
+const DEFAULT_STORE_GET = ArtifactStore.prototype.get;
 // Only the shared identity helper's directory opens use this adapter. A POSIX
 // directory/FIFO swap must fail before reaching a potentially blocking open.
 const INDEX_DIRECTORY_FS = Object.freeze({
@@ -1014,7 +1019,7 @@ function normalizeKeyId(value, label) {
   return value;
 }
 
-function captureMethod(port, method, label) {
+function captureDataMethod(port, method, label) {
   if (!port || (typeof port !== "object" && typeof port !== "function")) {
     throw new TypeError(`EvolutionArtifactPorts requires ${label}.${method}`);
   }
@@ -1029,13 +1034,17 @@ function captureMethod(port, method, label) {
           `EvolutionArtifactPorts requires ${label}.${method} as a data method`,
         );
       }
-      return Object.freeze(descriptor.value.bind(port));
+      return descriptor.value;
     }
     cursor = Object.getPrototypeOf(cursor);
   }
   throw new TypeError(`EvolutionArtifactPorts requires ${label}.${method}`);
 }
 
+function captureMethod(port, method, label) {
+  return Object.freeze(captureDataMethod(port, method, label).bind(port));
+}
+
 function captureArtifactStore(store) {
   rejectProxy(store, "artifactStore");
   if (!hasStablePrototype(store, ArtifactStore.prototype, "artifactStore")) {
@@ -1049,19 +1058,21 @@ function captureArtifactStore(store) {
   }
   const resolvedDir = path.resolve(dir);
   const layout = establishStoreLayout(resolvedDir);
+  const list = captureDataMethod(store, "list", "artifactStore");
+  const get = captureDataMethod(store, "get", "artifactStore");
   const captured = Object.freeze({
     dir: resolvedDir,
-    get: captureMethod(store, "get", "artifactStore"),
+    get: get === DEFAULT_STORE_GET ? null : Object.freeze(get.bind(store)),
     layout,
-    list: captureMethod(store, "list", "artifactStore"),
+    list: list === DEFAULT_STORE_LIST ? null : Object.freeze(list.bind(store)),
     publishDataOnce: captureMethod(store, "publishDataOnce", "artifactStore"),
     storedPath: captureMethod(store, "storedPath", "artifactStore"),
     verifyIntegrity: captureMethod(store, "verifyIntegrity", "artifactStore"),
   });
   // ArtifactStore methods consult public instance fields such as `dir` on
   // every call. Freeze the trusted instance after capturing its methods so a
-  // later collaborator cannot redirect a bound get/list/integrity call to a
-  // different store root.
+  // later collaborator cannot redirect a bound custom get/list/integrity call
+  // to a different store root. Null index methods select trusted snapshots.
   Object.freeze(store);
   return captured;
 }
@@ -2164,7 +2175,7 @@ export class EvolutionArtifactPorts {
     let entries;
     try {
       entries = rejectPromise(
-        this.#store.list(),
+        this.#store.list ? this.#store.list() : trustedBefore.entries,
         "ArtifactStore.list",
         EVOLUTION_ARTIFACT_STORE_FAILED_CODE,
       );
@@ -2187,9 +2198,9 @@ export class EvolutionArtifactPorts {
         "ArtifactStore.list did not return an array",
       );
     }
-    // ArtifactStore currently materializes its whole JSONL index before this
-    // adapter can enforce a limit. Reject immediately after return; this is an
-    // explicit scalability boundary, not a claim of bounded store-side query.
+    // Default entries already came from a bounded descriptor read. Custom
+    // list hooks retain their original execution and exact cross-check; their
+    // own I/O cannot be constrained by this adapter's snapshot byte limit.
     if (entries.length > EVOLUTION_ARTIFACT_MAX_INDEX_ENTRIES) {
       throw artifactError(
         EVOLUTION_ARTIFACT_STORE_FAILED_CODE,
@@ -2280,7 +2291,7 @@ export class EvolutionArtifactPorts {
     let current;
     try {
       current = rejectPromise(
-        this.#store.get(artifactId),
+        this.#store.get ? this.#store.get(artifactId) : listed[0],
         "ArtifactStore.get",
         EVOLUTION_ARTIFACT_STORE_FAILED_CODE,
       );

package/src/lib/evolution/evolution-file-witness.js

@@ -4,8 +4,7 @@ import path from "node:path";
 import { types } from "node:util";
 import { ensurePrivateDirectory, ensurePrivateFile } from "../secure-fs.js";
 import { withFileLock } from "../with-file-lock.js";
-import { readBoundedDescriptor } from "./bounded-descriptor-read.js";
-import { withEvolutionFileIdentity } from "./evolution-file-identity.js";
+import { createEvolutionPhysicalStateReader } from "./evolution-physical-state-reader.js";
 import {
   createEvolutionWitnessSegments,
   EVOLUTION_SEGMENTED_WITNESS_SCHEMA,
@@ -17,6 +16,8 @@ import {
 
 export const EVOLUTION_FILE_WITNESS_STORE_SCHEMA =
   "chainlesschain.evolution-file-witness-store/v1";
+export const EVOLUTION_WITNESS_STATE_READ_FAILED_CODE =
+  "CC_EVOLUTION_WITNESS_STATE_READ_FAILED";
 
 const WITNESS_DOMAIN = `${EVOLUTION_LEDGER_WITNESS_SCHEMA}\0`;
 const ANCESTRY_DOMAIN = `${EVOLUTION_LEDGER_WITNESS_ANCESTRY_SCHEMA}\0`;
@@ -247,6 +248,63 @@ export function createEvolutionFileWitness({
   }
   const secureOptions = { deps: { fs: fsImpl }, failIfUnavailable: true };
   ensurePrivateDirectory(directory, secureOptions);
+  const readerOptions = {
+    fsImpl,
+    maximumBytes,
+    minimumBytes: 2,
+    directoryMode: process.platform === "win32" ? null : 0o700n,
+    sizeError: "store size is invalid",
+    label: "witness",
+    errorCode: EVOLUTION_WITNESS_STATE_READ_FAILED_CODE,
+    readFailureMessage: "witness bounded read failed",
+  };
+  const rootReader = createEvolutionPhysicalStateReader({
+    ...readerOptions,
+    directoryPath: directory,
+  });
+  const segmentDirectory = `${target}.segments-v2`;
+  let segmentReader = null;
+  const captureSegments = () => {
+    rootReader.recheck();
+    segmentReader = createEvolutionPhysicalStateReader({
+      ...readerOptions,
+      label: "witness segment",
+      readFailureMessage: "witness segment bounded read failed",
+      directoryPath: segmentDirectory,
+    });
+    rootReader.recheck();
+    return segmentReader;
+  };
+  // A constructor may secure existing local storage. Read paths never create
+  // or repair a missing segment directory; first publication retains that job.
+  let existingSegments = false;
+  try {
+    fsImpl.lstatSync(segmentDirectory, { bigint: true });
+    existingSegments = true;
+  } catch (cause) {
+    if (cause?.code !== "ENOENT") throw cause;
+  }
+  if (existingSegments) {
+    ensurePrivateDirectory(segmentDirectory, secureOptions);
+    captureSegments();
+  }
+  const checkSegments = () => {
+    const reader = segmentReader ?? captureSegments();
+    rootReader.recheck();
+    reader.recheck();
+    return reader;
+  };
+  const prepareSegments = () => {
+    rootReader.recheck();
+    if (segmentReader !== null) return segmentReader.recheck();
+    ensurePrivateDirectory(segmentDirectory, secureOptions);
+    captureSegments();
+  };
+  const recheckStorage = () => {
+    rootReader.recheck();
+    segmentReader?.recheck();
+    rootReader.recheck();
+  };
   // Cache immutable encodings, never an authority decision. Keep the earliest
   // entries when full so full-history scans cannot churn the bounded cache.
   const recordEncodings = new Map();
@@ -587,67 +645,25 @@ export function createEvolutionFileWitness({
     return store;
   };
 
-  const readBytes = (file, byteLimit = maximumBytes) =>
-    withEvolutionFileIdentity(fsImpl, file, (samePathHandle) =>
-      readBytesWithIdentity(
-        file,
-        Math.min(maximumBytes, byteLimit),
-        samePathHandle,
-      ),
-    );
-
-  const readBytesWithIdentity = (file, byteLimit, samePathHandle) => {
-    ensurePrivateFile(file, secureOptions);
-    const stat = fsImpl.lstatSync(file);
-    if (
-      !stat.isFile() ||
-      stat.isSymbolicLink() ||
-      stat.nlink !== 1 ||
-      stat.size < 2 ||
-      stat.size > byteLimit
-    ) {
-      throw new Error("witness store size is invalid");
-    }
-    let descriptor;
-    const sameFile = (observed) =>
-      observed.isFile() &&
-      observed.nlink === 1 &&
-      observed.dev === stat.dev &&
-      observed.ino === stat.ino &&
-      observed.size === stat.size &&
-      observed.mtimeMs === stat.mtimeMs &&
-      observed.ctimeMs === stat.ctimeMs;
-    try {
-      descriptor = fsImpl.openSync(
-        file,
-        fsImpl.constants.O_RDONLY | (fsImpl.constants.O_NOFOLLOW || 0),
-      );
-      if (!samePathHandle(stat, fsImpl.fstatSync(descriptor))) {
-        throw new Error("witness store changed while opening");
-      }
-      const bytes = readBoundedDescriptor(
-        fsImpl,
-        descriptor,
-        stat.size,
-        byteLimit,
-      );
-      const afterPath = fsImpl.lstatSync(file);
-      if (
-        !samePathHandle(stat, fsImpl.fstatSync(descriptor)) ||
-        afterPath.isSymbolicLink() ||
-        !sameFile(afterPath)
-      ) {
-        throw new Error("witness store changed while reading");
-      }
-      return bytes;
-    } finally {
-      if (descriptor !== undefined) fsImpl.closeSync(descriptor);
-    }
+  const readBytes = (file, byteLimit = maximumBytes, allowAbsent = false) => {
+    recheckStorage();
+    const reader = file === target ? rootReader : checkSegments();
+    const bytes = reader.read(file, {
+      maximumBytes: byteLimit,
+      allowAbsent,
+      prepareFile: (name) => ensurePrivateFile(name, secureOptions),
+    });
+    recheckStorage();
+    return bytes;
   };
 
   const readStore = (options = {}) => {
-    if (!fsImpl.existsSync(target)) return emptyStore();
-    const bytes = readBytes(target, maximumHistoryBytes);
+    const bytes = readBytes(target, maximumHistoryBytes, true);
+    if (bytes === null) {
+      const store = emptyStore();
+      recheckStorage();
+      return store;
+    }
     const parsed = JSON.parse(
       new TextDecoder("utf-8", { fatal: true }).decode(bytes),
     );
@@ -660,7 +676,10 @@ export function createEvolutionFileWitness({
               headBytes: bytes.length,
             })
           : validateStore(parsed, trustEpoch);
-      if (trustEpoch === currentTrustEpoch()) return store;
+      if (trustEpoch === currentTrustEpoch()) {
+        recheckStorage();
+        return store;
+      }
     }
     throw new Error("witness verifier trust epoch changed while reading");
   };
@@ -716,6 +735,8 @@ export function createEvolutionFileWitness({
   const segments = createEvolutionWitnessSegments({
     filePath: target,
     fsImpl,
+    checkDirectory: checkSegments,
+    prepareDirectory: prepareSegments,
     readBytes,
     writeBytes,
     validateStore,
@@ -760,8 +781,10 @@ export function createEvolutionFileWitness({
     return store.current;
   };
 
-  const underLock = (operation) =>
-    lock(target, operation, { failIfUnavailable: true, _fs: fsImpl });
+  const underLock = (operation) => {
+    recheckStorage();
+    return lock(target, operation, { failIfUnavailable: true, _fs: fsImpl });
+  };
   const discarded = (store, snapshot) =>
     segments.isDiscarded(store, snapshot) ||
     store.discardedAnchors.some(

package/src/lib/evolution/evolution-ledger-file-backend.js

@@ -4,6 +4,7 @@ import { createEvolutionFileWitness } from "./evolution-file-witness.js";
 import {
   EvolutionLedger,
   captureEvolutionLedgerMigrationSource,
+  captureEvolutionLedgerDirectoryBoundary,
 } from "./evolution-ledger.js";
 import { createEvolutionLedgerV2JournalFromFactory } from "./evolution-ledger-v2-journal.js";
 
@@ -12,6 +13,7 @@ export const EVOLUTION_LEDGER_FILE_BACKEND_SCHEMA =
 
 const BACKENDS = new WeakSet();
 const BACKEND_BINDINGS = new WeakMap();
+const SOURCE_DIRECTORY_BOUNDARIES = new WeakMap();
 
 function requiredString(value, label) {
   if (typeof value !== "string" || value.trim() === "") {
@@ -205,7 +207,10 @@ export function createEvolutionLedgerFileBackend({
     ledger,
     witness,
   });
+  const sourceDirectoryBoundary =
+    captureEvolutionLedgerDirectoryBoundary(sourceLedger);
   BACKENDS.add(backend);
+  SOURCE_DIRECTORY_BOUNDARIES.set(backend, sourceDirectoryBoundary);
   BACKEND_BINDINGS.set(
     backend,
     Object.freeze({
@@ -234,3 +239,20 @@ export function captureEvolutionLedgerFileBackendBinding(value) {
     );
   return binding;
 }
+
+/** Captured private v1 source even when the public journal is a v2 wrapper. */
+export function captureEvolutionLedgerFileBackendSourceDirectoryBoundary(
+  value,
+) {
+  if (arguments.length !== 1)
+    throw new TypeError(
+      "source directory boundary capture takes exactly one original backend",
+    );
+  const boundary = SOURCE_DIRECTORY_BOUNDARIES.get(value);
+  if (!boundary)
+    throw new TypeError(
+      "a branded file backend source directory boundary is required",
+    );
+  boundary.recheck();
+  return boundary;
+}

package/src/lib/evolution/evolution-ledger-file-manifest-catalog.js

@@ -5,7 +5,10 @@ import { types as utilTypes } from "node:util";
 
 import { ensurePrivateDirectory, ensurePrivateFile } from "../secure-fs.js";
 import { withFileLock } from "../with-file-lock.js";
-import { readBoundedDescriptor } from "./bounded-descriptor-read.js";
+import {
+  createEvolutionManifestStateReader,
+  captureEvolutionManifestStateReaderDirectoryBoundary,
+} from "./evolution-manifest-state-reader.js";
 import { EVOLUTION_LEDGER_MANIFEST_CATALOG_APPEND_RESULT_SCHEMA } from "./evolution-ledger-manifest-catalog.js";
 
 export const EVOLUTION_LEDGER_FILE_MANIFEST_CATALOG_SCHEMA =
@@ -15,6 +18,7 @@ const STATE_SCHEMA =
   "chainlesschain.evolution-ledger-file-manifest-catalog-state/v2";
 const STATE_KEYS = new Set(["manifests", "schema"]);
 const DEFAULT_MAXIMUM_BYTES = 64 * 1024 * 1024;
+const DIRECTORY_BOUNDARIES = new WeakMap();
 
 function exactRecord(value, keys, label) {
   if (
@@ -75,39 +79,13 @@ export function createEvolutionLedgerFileManifestCatalogBackend({
   const secureOptions = { deps: { fs: fsImpl }, failIfUnavailable: true };
   ensurePrivateDirectory(directory, secureOptions);
 
-  const readBytes = () => {
-    if (!fsImpl.existsSync(file)) return null;
-    const stat = fsImpl.lstatSync(file);
-    if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1) {
-      throw new Error("manifest catalog file identity is invalid");
-    }
-    if (stat.size > maximumBytes)
-      throw new Error("manifest catalog exceeds maximumBytes");
-    let descriptor;
-    try {
-      descriptor = fsImpl.openSync(
-        file,
-        fsImpl.constants.O_RDONLY | (fsImpl.constants.O_NOFOLLOW || 0),
-      );
-      const opened = fsImpl.fstatSync(descriptor);
-      if (!opened.isFile() || opened.nlink !== 1 || opened.size !== stat.size) {
-        throw new Error("manifest catalog changed while opening");
-      }
-      const bytes = readBoundedDescriptor(
-        fsImpl,
-        descriptor,
-        stat.size,
-        maximumBytes,
-      );
-      const after = fsImpl.lstatSync(file);
-      if (after.isSymbolicLink() || after.size !== stat.size) {
-        throw new Error("manifest catalog changed while reading");
-      }
-      return bytes;
-    } finally {
-      if (descriptor !== undefined) fsImpl.closeSync(descriptor);
-    }
-  };
+  const stateReader = createEvolutionManifestStateReader({
+    file,
+    fsImpl,
+    maximumBytes,
+    label: "manifest catalog",
+  });
+  const readBytes = stateReader.read;
 
   const readState = () => {
     const bytes = readBytes();
@@ -173,13 +151,14 @@ export function createEvolutionLedgerFileManifestCatalogBackend({
     }
   };
 
-  return Object.freeze({
+  const backend = Object.freeze({
     descriptor: Object.freeze({
       file,
       localOnly: true,
       schema: EVOLUTION_LEDGER_FILE_MANIFEST_CATALOG_SCHEMA,
     }),
     compareAndAppend(request) {
+      stateReader.recheck();
       return lock(
         file,
         () => {
@@ -215,4 +194,24 @@ export function createEvolutionLedgerFileManifestCatalogBackend({
       return structuredClone(readState().manifests.at(-1) ?? null);
     },
   });
+  DIRECTORY_BOUNDARIES.set(
+    backend,
+    captureEvolutionManifestStateReaderDirectoryBoundary(stateReader),
+  );
+  return backend;
+}
+
+/** Original local catalog directory only; structural wrappers are not owners. */
+export function captureEvolutionLedgerFileManifestCatalogDirectoryBoundary(
+  backend,
+) {
+  if (arguments.length !== 1)
+    throw new TypeError("catalog directory capture takes one original backend");
+  const boundary = DIRECTORY_BOUNDARIES.get(backend);
+  if (!boundary)
+    throw new TypeError(
+      "an original file manifest catalog backend is required",
+    );
+  boundary.recheck();
+  return boundary;
 }