@remnic/core 9.69.32 → 9.69.34

package/src/reconcile/manifest.ts

@@ -1,8 +1,8 @@
 import { createHash } from "node:crypto";
 import { computeLegacyContentHash, normalizeLegacyContent } from "../content-hash.js";
 import { inferMemoryStatus } from "../memory-lifecycle-ledger-utils.js";
-import { ContentHashIndex, type ContentHashPathEntry } from "../storage/content-hash-index.js";
 import { DEFAULT_CITATION_FORMAT, stripCitationForTemplate } from "../source-attribution.js";
+import { ContentHashIndex, type ContentHashPathEntry } from "../storage/content-hash-index.js";
 import { storedContentIdentityCandidates } from "../structured-attributes.js";
 import type { MemoryFrontmatter, MemoryStatus } from "../types.js";
 import { RECALL_FALLBACK_DIRS } from "../utils/category-dir.js";
@@ -19,7 +19,7 @@ import {
 
 export const RECONCILE_MANIFEST_FORMAT = "remnic-reconcile-manifest";
 export const RECONCILE_MANIFEST_SCHEMA_VERSION = 1;
-const CONTENT_HASH_NORMALIZER_VERSION = 4;
+export const CONTENT_HASH_NORMALIZER_VERSION = 4;
 /**
  * Version of the identity-resolution LOGIC (alias recovery, candidate
  * ordering), independent of the content normalizer: a cached manifest entry
@@ -28,7 +28,7 @@ const CONTENT_HASH_NORMALIZER_VERSION = 4;
  * review round 2). Bump when parsedMemoryIdentity's output shape or
  * semantics change.
  */
-const IDENTITY_RESOLUTION_VERSION = 2;
+export const IDENTITY_RESOLUTION_VERSION = 2;
 
 export interface ReconcileMemoryIdentity {
   id: string;
@@ -49,6 +49,9 @@ export interface ReconcileMemoryIdentity {
 
 export interface ReconcileManifestFile extends ReconcileFileState {
   memory?: ReconcileMemoryIdentity;
+  /** Present on sha-only (negative) entries so an upgrade re-parses them. */
+  normalizerVersion?: number;
+  identityResolutionVersion?: number;
 }
 
 type ActiveFactManifestFile = ReconcileManifestFile & { memory: ReconcileMemoryIdentity };
@@ -132,6 +135,65 @@ function parsedMemoryIdentity(
   };
 }
 
+/**
+ * Stable fingerprint of the citation template that `parsedMemoryIdentity` uses
+ * to strip inline attribution before hashing. A persisted identity cache is
+ * only reusable while this matches: identical file content under a different
+ * template yields a different `contentHash`, which would silently change
+ * duplicate and conflict decisions on a warm plan.
+ */
+export function citationTemplateFingerprint(citationTemplate?: string): string {
+  return createHash("sha256")
+    .update(citationTemplate ?? DEFAULT_CITATION_FORMAT)
+    .digest("hex")
+    .slice(0, 16);
+}
+
+/**
+ * Structural guard for identities read back from an on-disk cache. A cache file
+ * is untrusted JSON: without this an entry carrying `memory: null` survives the
+ * loader's cast and then throws when the hit path dereferences
+ * `memory.normalizerVersion`, aborting a manifest build that should instead
+ * fall back to a cold parse.
+ */
+export function isReconcileMemoryIdentity(value: unknown): value is ReconcileMemoryIdentity {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const memory = value as Record<string, unknown>;
+  if (typeof memory.id !== "string") return false;
+  if (typeof memory.category !== "string") return false;
+  if (typeof memory.contentHash !== "string" || !SHA256_PATTERN.test(memory.contentHash)) return false;
+  if (typeof memory.status !== "string") return false;
+  if (memory.normalizerVersion !== undefined && typeof memory.normalizerVersion !== "number") return false;
+  if (memory.identityResolutionVersion !== undefined && typeof memory.identityResolutionVersion !== "number") {
+    return false;
+  }
+  if (
+    memory.contentHashAliases !== undefined &&
+    (!Array.isArray(memory.contentHashAliases) ||
+      memory.contentHashAliases.some((alias) => typeof alias !== "string" || !SHA256_PATTERN.test(alias)))
+  ) {
+    return false;
+  }
+  return true;
+}
+
+/** A cache hit is valid only when the entry was built by the current parser.
+ * Positive hits carry versions on `memory`; sha-only negatives stamp the same
+ * versions on the entry itself. Unversioned negatives are pre-upgrade leftovers
+ * and must miss so a newer parser can recognize an identity it previously skipped. */
+export function isCachedIdentityReusable(cached: ReconcileManifestFile): boolean {
+  if (cached.memory !== undefined) {
+    return (
+      cached.memory.normalizerVersion === CONTENT_HASH_NORMALIZER_VERSION &&
+      cached.memory.identityResolutionVersion === IDENTITY_RESOLUTION_VERSION
+    );
+  }
+  return (
+    cached.normalizerVersion === CONTENT_HASH_NORMALIZER_VERSION &&
+    cached.identityResolutionVersion === IDENTITY_RESOLUTION_VERSION
+  );
+}
+
 export async function buildReconcileManifestFile(
   file: ReconcileFileState,
   readFile: (file: ReconcileFileState) => Promise<Buffer | string | null>,
@@ -139,10 +201,12 @@ export async function buildReconcileManifestFile(
   citationTemplate = DEFAULT_CITATION_FORMAT
 ): Promise<ReconcileManifestFile> {
   let raw: Buffer | string | null = null;
+  let readFailed = false;
   if (isMemoryPath(file.path)) {
     try {
       raw = await readFile(file);
     } catch {
+      readFailed = true;
       raw = null;
     }
   }
@@ -150,7 +214,18 @@ export async function buildReconcileManifestFile(
     raw = null;
   }
   const memory = raw === null ? undefined : parsedMemoryIdentity(file.path, raw, parseMemory, citationTemplate);
-  return { ...file, ...(memory ? { memory } : {}) };
+  // A thrown read is not a negative identity. Stamping versions here would
+  // make the next warm cycle treat the failure as "this file has no id".
+  if (readFailed) return { ...file };
+  return {
+    ...file,
+    ...(memory
+      ? { memory }
+      : {
+          normalizerVersion: CONTENT_HASH_NORMALIZER_VERSION,
+          identityResolutionVersion: IDENTITY_RESOLUTION_VERSION,
+        }),
+  };
 }
 
 /** Read-batch size for manifest builds. Uncached files are independent (a
@@ -168,23 +243,33 @@ export async function buildReconcileManifest(options: BuildReconcileManifestOpti
     cachedByPath.set(cached.path, cached);
   }
 
-  const files: ReconcileManifestFile[] = [];
+  const allFiles = [...options.files];
+  // Every result — cache hit or rebuild — is stored at its own input index.
+  // Pushing hits onto a dense array while rebuilds are assigned by index
+  // silently drops entries whenever a miss precedes a hit: the rebuild lands
+  // on the slot the hit already occupied.
+  const files: ReconcileManifestFile[] = new Array(allFiles.length);
   // Cache hits stay on a synchronous fast path (no promise allocation, no
   // Promise.all — a fully-cached rebuild must not regress); only the uncached
-  // entries ride the bounded batches. Order is preserved by index.
+  // entries ride the bounded batches.
   const uncached: Array<{ index: number; file: ReconcileFileState }> = [];
-  const allFiles = [...options.files];
   for (let i = 0; i < allFiles.length; i += 1) {
     const file = allFiles[i]!;
     const cached = cachedByPath.get(file.path);
     if (
       cached !== undefined &&
       cached.sha256.toLowerCase() === file.sha256.toLowerCase() &&
-      (cached.memory === undefined ||
-        (cached.memory.normalizerVersion === CONTENT_HASH_NORMALIZER_VERSION &&
-          cached.memory.identityResolutionVersion === IDENTITY_RESOLUTION_VERSION))
+      isCachedIdentityReusable(cached)
     ) {
-      files.push({ ...file, ...(cached.memory ? { memory: cached.memory } : {}) });
+      files[i] = {
+        ...file,
+        ...(cached.memory
+          ? { memory: cached.memory }
+          : {
+              normalizerVersion: cached.normalizerVersion,
+              identityResolutionVersion: cached.identityResolutionVersion,
+            }),
+      };
     } else {
       uncached.push({ index: i, file });
     }

package/src/reconcile-identity-cache.test.ts

@@ -0,0 +1,378 @@
+import * as assert from "node:assert/strict";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import test from "node:test";
+
+import { createHash } from "node:crypto";
+import { type ServerIdentityCacheEntry, planServerIdentityCacheWrite } from "./access-offline-manifest.js";
+import { isInternalRemnicStatePath } from "./offline-sync.js";
+import { convergeIdentityCachePath } from "./reconcile/cursor.js";
+import {
+  buildReconcileManifest,
+  citationTemplateFingerprint,
+  isReconcileMemoryIdentity,
+} from "./reconcile/manifest.js";
+import { createPersistedSupportPassportPrivateFileExclusion } from "./support-passport/card-projection.js";
+import { parseFrontmatter } from "./storage.js";
+
+function memoryFile(id: string, body: string): string {
+  return [
+    "---",
+    `id: ${id}`,
+    "category: fact",
+    "created: 2026-01-01T00:00:00.000Z",
+    "updated: 2026-01-01T00:00:00.000Z",
+    "status: active",
+    "---",
+    body,
+  ].join("\n");
+}
+
+test("converge identity cache path lives beside cursors but in its own dir", () => {
+  const p = convergeIdentityCachePath("/tmp/mem", "http://peer", "default");
+  assert.ok(p.includes("converge-identity"));
+  assert.ok(!p.includes("converge-cursors"));
+  assert.ok(path.basename(p).startsWith("identity-"));
+});
+
+test("cachedFiles with matching sha skip the content read (warm manifest build)", async () => {
+  const dir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "identity-cache-"));
+  try {
+    const content = memoryFile("warm-1", "warm body");
+    const file = path.join(dir, "facts/warm-1.md");
+    await fs.promises.mkdir(path.dirname(file), { recursive: true });
+    await fs.promises.writeFile(file, content);
+
+    const contentSha = createHash("sha256").update(content).digest("hex");
+    // First (cold) build reads content and produces identities.
+    const cold = await buildReconcileManifest({
+      files: [{ path: "facts/warm-1.md", sha256: contentSha, mtimeMs: 1, bytes: content.length }],
+      parseMemory: parseFrontmatter,
+      readFile: async () => content,
+    });
+    assert.ok(cold.files[0]?.memory?.id === "warm-1");
+
+    // Warm build with cachedFiles: readFile must NEVER be called.
+    let readCalled = false;
+    const warm = await buildReconcileManifest({
+      files: [{ path: "facts/warm-1.md", sha256: contentSha, mtimeMs: 1, bytes: content.length }],
+      parseMemory: parseFrontmatter,
+      cachedFiles: cold.files,
+      readFile: async () => {
+        readCalled = true;
+        return content;
+      },
+    });
+    assert.equal(readCalled, false);
+    assert.deepEqual(warm.files[0]?.memory, cold.files[0]?.memory);
+  } finally {
+    await fs.promises.rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("a changed sha invalidates the cached identity (cold re-read)", async () => {
+  const dir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "identity-cache-"));
+  try {
+    const contentA = memoryFile("flip-1", "body a");
+    const contentB = memoryFile("flip-1", "body b");
+    const cold = await buildReconcileManifest({
+      files: [
+        {
+          path: "facts/flip-1.md",
+          sha256: createHash("sha256").update(contentA).digest("hex"),
+          mtimeMs: 1,
+          bytes: contentA.length,
+        },
+      ],
+      parseMemory: parseFrontmatter,
+      readFile: async () => contentA,
+    });
+    let readCalled = false;
+    const warm = await buildReconcileManifest({
+      files: [
+        {
+          path: "facts/flip-1.md",
+          sha256: createHash("sha256").update(contentB).digest("hex"),
+          mtimeMs: 2,
+          bytes: contentB.length,
+        },
+      ],
+      parseMemory: parseFrontmatter,
+      cachedFiles: cold.files,
+      readFile: async () => {
+        readCalled = true;
+        return contentB;
+      },
+    });
+    assert.equal(readCalled, true);
+    assert.ok(warm.files[0]?.memory);
+  } finally {
+    await fs.promises.rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("the server identity cache lives on a path snapshot enumeration excludes", () => {
+  // The cache is node-local: enumerating it would advertise it as a peer file
+  // and make convergence transfer the cache itself.
+  assert.equal(isInternalRemnicStatePath(".remnic/state/converge-identity-cache.json"), true);
+  assert.equal(isInternalRemnicStatePath("state/converge-identity-cache.json"), false);
+});
+
+test("the CLI identity cache path is excluded from enumeration too", () => {
+  const absolute = convergeIdentityCachePath("/tmp/mem", "http://peer", "default");
+  const relative = absolute.slice("/tmp/mem/".length);
+  assert.equal(isInternalRemnicStatePath(relative), true);
+});
+
+test("citation templates fingerprint distinctly and default consistently", () => {
+  const fallback = citationTemplateFingerprint(undefined);
+  assert.equal(
+    citationTemplateFingerprint("{{source}} — {{title}}"),
+    citationTemplateFingerprint("{{source}} — {{title}}")
+  );
+  assert.notEqual(citationTemplateFingerprint("{{source}}"), citationTemplateFingerprint("{{title}}"));
+  assert.notEqual(citationTemplateFingerprint("{{source}}"), fallback);
+  assert.match(fallback, /^[0-9a-f]{16}$/);
+});
+
+test("malformed cached identities are rejected instead of trusted", () => {
+  const hash = "a".repeat(64);
+  const otherHash = "b".repeat(64);
+  const valid = { id: "a", category: "fact", contentHash: hash, status: "active" };
+  assert.equal(isReconcileMemoryIdentity(valid), true);
+  assert.equal(isReconcileMemoryIdentity({ ...valid, contentHashAliases: [otherHash] }), true);
+  assert.equal(isReconcileMemoryIdentity(null), false);
+  assert.equal(isReconcileMemoryIdentity(undefined), false);
+  assert.equal(isReconcileMemoryIdentity([valid]), false);
+  assert.equal(isReconcileMemoryIdentity({ ...valid, id: 1 }), false);
+  assert.equal(isReconcileMemoryIdentity({ ...valid, status: undefined }), false);
+  assert.equal(isReconcileMemoryIdentity({ ...valid, normalizerVersion: "4" }), false);
+  assert.equal(isReconcileMemoryIdentity({ ...valid, contentHashAliases: [1] }), false);
+  // A well-typed but non-hash value would be reused without a parse and could
+  // shift duplicate decisions, so the guard enforces the producer's format.
+  assert.equal(isReconcileMemoryIdentity({ ...valid, contentHash: "not-a-hash" }), false);
+  assert.equal(isReconcileMemoryIdentity({ ...valid, contentHashAliases: ["not-a-hash"] }), false);
+});
+
+test("a cache miss before a cache hit does not overwrite the hit", async () => {
+  const changed = memoryFile("mixed-a", "edited body");
+  const unchanged = memoryFile("mixed-b", "stable body");
+  const changedSha = createHash("sha256").update(changed).digest("hex");
+  const unchangedSha = createHash("sha256").update(unchanged).digest("hex");
+  const byPath = new Map([
+    ["facts/mixed-a.md", changed],
+    ["facts/mixed-b.md", unchanged],
+  ]);
+  const files = [
+    { path: "facts/mixed-a.md", sha256: changedSha, mtimeMs: 2, bytes: changed.length },
+    { path: "facts/mixed-b.md", sha256: unchangedSha, mtimeMs: 1, bytes: unchanged.length },
+  ];
+
+  const cold = await buildReconcileManifest({
+    files,
+    parseMemory: parseFrontmatter,
+    readFile: async (file) => byPath.get(file.path) ?? null,
+  });
+
+  // Warm run where only the FIRST file changed: its rebuild is assigned by
+  // input index while the second file is a cache hit.
+  const staleSha = createHash("sha256").update("stale").digest("hex");
+  const warm = await buildReconcileManifest({
+    files,
+    parseMemory: parseFrontmatter,
+    cachedFiles: [
+      { path: "facts/mixed-a.md", sha256: staleSha, mtimeMs: 1, bytes: 1 },
+      cold.files.find((file) => file.path === "facts/mixed-b.md")!,
+    ],
+    readFile: async (file) => byPath.get(file.path) ?? null,
+  });
+
+  assert.equal(warm.files.length, 2);
+  assert.deepEqual(
+    warm.files.map((file) => file.path),
+    ["facts/mixed-a.md", "facts/mixed-b.md"]
+  );
+  assert.equal(
+    warm.files.every((file) => file !== undefined),
+    true
+  );
+  assert.equal(warm.files[0]?.memory?.id, "mixed-a");
+  assert.equal(warm.files[1]?.memory?.id, "mixed-b");
+});
+
+test("the server cache write persists removals and prunes only completed walks", () => {
+  const entry = (path: string): ServerIdentityCacheEntry => ({
+    path,
+    sha256: "c".repeat(64),
+    memory: {
+      id: path,
+      category: "fact",
+      contentHash: "d".repeat(64),
+      normalizerVersion: 4,
+      identityResolutionVersion: 2,
+      status: "active",
+    },
+  });
+  const persisted = new Map([
+    ["facts/kept.md", entry("facts/kept.md")],
+    ["facts/deleted.md", entry("facts/deleted.md")],
+  ]);
+
+  // A completed walk that only observed the surviving file must still write,
+  // or the deleted file's entry stays on disk forever.
+  const pruned = planServerIdentityCacheWrite({
+    persisted,
+    yieldedPaths: new Set(["facts/kept.md"]),
+    streamCompleted: true,
+    cacheDirty: false,
+  });
+  assert.equal(pruned.shouldWrite, true);
+  assert.deepEqual(
+    pruned.entries.map((e) => e.path),
+    ["facts/kept.md"]
+  );
+
+  // An entry dropped because its file lost its identity is a mutation even
+  // though nothing was rebuilt.
+  const lostIdentity = planServerIdentityCacheWrite({
+    persisted: new Map([["facts/kept.md", entry("facts/kept.md")]]),
+    yieldedPaths: new Set(["facts/kept.md", "facts/lost.md"]),
+    streamCompleted: true,
+    cacheDirty: true,
+  });
+  assert.equal(lostIdentity.shouldWrite, true);
+
+  // Nothing changed: no write.
+  const unchanged = planServerIdentityCacheWrite({
+    persisted,
+    yieldedPaths: new Set(["facts/kept.md", "facts/deleted.md"]),
+    streamCompleted: true,
+    cacheDirty: false,
+  });
+  assert.equal(unchanged.shouldWrite, false);
+
+  // An aborted walk never prunes, so it can only add.
+  const aborted = planServerIdentityCacheWrite({
+    persisted,
+    yieldedPaths: new Set(["facts/kept.md"]),
+    streamCompleted: false,
+    cacheDirty: false,
+  });
+  assert.equal(aborted.shouldWrite, false);
+  assert.equal(aborted.entries.length, 2);
+});
+
+test("a persisted classification with a matching stat identity skips the file read", async () => {
+  const dir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "persisted-exclusion-"));
+  try {
+    const target = path.join(dir, "facts", "warm.md");
+    await fs.promises.mkdir(path.dirname(target), { recursive: true });
+    await fs.promises.writeFile(target, memoryFile("warm-excl", "body"));
+    await fs.promises.utimes(target, new Date(1_700_000_000_000), new Date(1_700_000_000_000));
+
+    let reads = 0;
+    const storage = {
+      readMemoryByPath: async () => {
+        reads += 1;
+        return null;
+      },
+    };
+
+    const persisted = new Map<string, { statIdentity?: string; excluded?: boolean }>();
+    const updates = new Map<string, { statIdentity: string; excluded: boolean }>();
+    const exclude = createPersistedSupportPassportPrivateFileExclusion(storage, persisted, updates);
+
+    // Cold: no persisted classification -> reads once and records it.
+    assert.equal(await exclude({ root: dir, path: "facts/warm.md", filePath: target }), false);
+    assert.equal(reads, 1);
+    const recorded = updates.get("facts/warm.md");
+    assert.ok(recorded, "the cold classification must be recorded for persistence");
+    persisted.set("facts/warm.md", recorded);
+
+    // Warm: the stat identity matches -> no read.
+    updates.clear();
+    assert.equal(await exclude({ root: dir, path: "facts/warm.md", filePath: target }), false);
+    assert.equal(reads, 1, "a matching persisted classification must not re-read the file");
+
+    // A content change moves ctime -> the classification is recomputed.
+    await fs.promises.writeFile(target, memoryFile("warm-excl", "changed body"));
+    updates.clear();
+    assert.equal(await exclude({ root: dir, path: "facts/warm.md", filePath: target }), false);
+    assert.equal(reads, 2, "a changed stat identity must re-classify");
+    assert.ok(updates.has("facts/warm.md"));
+  } finally {
+    await fs.promises.rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("an unversioned sha-only cache entry is not reused", async () => {
+  const content = "not a memory file at all";
+  const sha = createHash("sha256").update(content).digest("hex");
+  let reads = 0;
+  await buildReconcileManifest({
+    files: [{ path: "facts/no-id.md", sha256: sha, mtimeMs: 1, bytes: content.length }],
+    parseMemory: parseFrontmatter,
+    cachedFiles: [{ path: "facts/no-id.md", sha256: sha, mtimeMs: 1, bytes: content.length }],
+    readFile: async () => {
+      reads += 1;
+      return content;
+    },
+  });
+  assert.equal(reads, 1, "a pre-upgrade sha-only entry must be reparsed");
+});
+
+test("a version-stamped sha-only cache entry is reused", async () => {
+  const content = "not a memory file at all";
+  const sha = createHash("sha256").update(content).digest("hex");
+  let reads = 0;
+  const warm = await buildReconcileManifest({
+    files: [{ path: "facts/no-id.md", sha256: sha, mtimeMs: 1, bytes: content.length }],
+    parseMemory: parseFrontmatter,
+    cachedFiles: [
+      {
+        path: "facts/no-id.md",
+        sha256: sha,
+        mtimeMs: 1,
+        bytes: content.length,
+        normalizerVersion: 4,
+        identityResolutionVersion: 2,
+      },
+    ],
+    readFile: async () => {
+      reads += 1;
+      return content;
+    },
+  });
+  assert.equal(reads, 0, "a current-version sha-only entry must skip the read");
+  assert.equal(warm.files[0]?.memory, undefined);
+  assert.equal(warm.files[0]?.normalizerVersion, 4);
+  assert.equal(warm.files[0]?.identityResolutionVersion, 2);
+});
+
+test("a thrown memory-file read is not cached as a reusable negative", async () => {
+  const sha = "a".repeat(64);
+  const first = await buildReconcileManifest({
+    files: [{ path: "facts/flaky.md", sha256: sha, mtimeMs: 1, bytes: 1 }],
+    parseMemory: parseFrontmatter,
+    readFile: async () => {
+      throw new Error("transient");
+    },
+  });
+  assert.equal(first.files[0]?.memory, undefined);
+  assert.equal(first.files[0]?.normalizerVersion, undefined);
+
+  let reads = 0;
+  await buildReconcileManifest({
+    files: [{ path: "facts/flaky.md", sha256: sha, mtimeMs: 1, bytes: 1 }],
+    parseMemory: parseFrontmatter,
+    cachedFiles: first.files,
+    readFile: async () => {
+      reads += 1;
+      return "---\nid: recovered\ncategory: fact\nstatus: active\n---\nbody\n";
+    },
+  });
+  assert.equal(reads, 1, "a failed read must not become a warm negative hit");
+});
+
+

package/src/runtime/child-process.ts

@@ -4,7 +4,7 @@ type ProcessOptions = Record<string, unknown>;
 type ProcessStream = {
   destroyed?: boolean;
   destroy: () => void;
-  end: () => void;
+  end: (chunk?: string | Buffer, callback?: (error?: Error | null) => void) => void;
   on: (event: string, listener: (...args: any[]) => void) => ProcessStream;
   once: (event: string, listener: (...args: any[]) => void) => ProcessStream;
   setEncoding: (encoding: BufferEncoding) => void;

package/src/storage/cas-revision-host.ts

@@ -0,0 +1,75 @@
+import { log } from "../logger.js";
+import {
+  CasRevisionStore,
+  type CasRevisionReadStatus,
+  type CasRevisionTransaction,
+} from "./cas-revision-store.js";
+
+/**
+ * StorageManager CAS receipt host (#2813 / #2807).
+ * Owns fail-open reads, lazy pending recovery, durable digest, and begin-revision.
+ * Tests patch the inherited CasRevisionStore seam on `casRevisions`.
+ */
+export class CasRevisionHost extends CasRevisionStore {
+  /** Standing CAS revision token — receipt identity, never public `updated` (#2807). Fail-open on read errors. */
+  async readCasRevision(filePath: string): Promise<string | undefined> {
+    try {
+      return await this.readRevision(filePath);
+    } catch (err) {
+      log.warn(`storage.readCasRevision failed for ${filePath}: ${err}`);
+      return undefined;
+    }
+  }
+
+  /** #2813 (P1 A): truthful CAS receipt probe — distinguishes a genuinely
+   * ABSENT receipt (target predates the sidecar; `undefined` semantics stay
+   * correct) from an UNAVAILABLE one (unreadable shard: receipt identity is
+   * unknown). Transactional callers that must refuse on unknown identity
+   * route here; `readCasRevision` stays fail-open for advisory reads.
+   * #2807 (P1): a PENDING marker left by a crash is lazily recovered on
+   * this first read when its evidence is decisive; a reserve-only marker
+   * may belong to a live writer and defers to the path-locked write path,
+   * and ambiguity stays `unavailable` with an actionable reason. */
+  async readCasRevisionStatus(filePath: string): Promise<CasRevisionReadStatus> {
+    const status = await this.readRevisionStatus(filePath);
+    if (status.status !== "unavailable" || !/pending/i.test(status.reason)) return status;
+    // #2807: an evidenced PENDING marker (its write already landed) is
+    // lazily recovered here. A reserve-only marker may belong to a LIVE
+    // transaction — this read holds no capture path lock — so it is left
+    // for the path-locked write path, which cannot race the owner.
+    try {
+      const outcome = await this.recoverPendingRevision(filePath, {
+        onlyWithWriteEvidence: true,
+      });
+      if (outcome === "reserved") return status;
+    } catch (error) {
+      return {
+        status: "unavailable",
+        reason: error instanceof Error ? error.message : String(error),
+      };
+    }
+    return await this.readRevisionStatus(filePath);
+  }
+
+  async readDurableFileDigest(filePath: string): Promise<string | null> {
+    try {
+      return await this.digestDurableFile(filePath);
+    } catch (err) {
+      log.warn(`storage.readDurableFileDigest failed for ${filePath}: ${err}`);
+      return null;
+    }
+  }
+
+  /** #2807 (P1): reconcile any crash-orphaned PENDING marker for this
+   * target BEFORE the next semantic mutation reserves a new token —
+   * otherwise a crashed reservation would make the memory permanently
+   * unwritable. Decisive evidence heals; ambiguity throws so the
+   * mutation fails closed with the actionable recovery error. */
+  async beginRevision(
+    pathname: string,
+    expectedContent?: string | Buffer | null,
+  ): Promise<CasRevisionTransaction> {
+    await this.recoverPendingRevision(pathname);
+    return await this.beginRevisionTransaction(pathname, expectedContent);
+  }
+}