@remnic/core 9.69.44 → 9.69.46

package/dist/{chunk-SHEHQBCG.js → chunk-DUJYRVUD.js}

@@ -475,11 +475,586 @@ var DeletionRevisionStore = class {
   }
 };
 
+// src/storage/cas-revision-store.ts
+import { createHash as createHash2, randomUUID as randomUUID2 } from "crypto";
+import { mkdir as mkdir2, open as open2, readFile as readFile2, rename as rename2, unlink as unlink2 } from "fs/promises";
+import path2 from "path";
+var ACCESS_TELEMETRY_FRONTMATTER_KEY = /^(?:accessCount|lastAccessed):/;
+function canonicalSemanticFileText(raw) {
+  const lines = raw.split("\n");
+  if (lines[0] !== "---") return raw;
+  const closing = lines.indexOf("---", 1);
+  if (closing === -1) return raw;
+  const frontmatter = lines.slice(1, closing).filter((line) => !ACCESS_TELEMETRY_FRONTMATTER_KEY.test(line));
+  return [...lines.slice(0, 1), ...frontmatter, ...lines.slice(closing)].join("\n");
+}
+var CAS_REVISION_LOCK_STALE_MS = 6e4;
+var CAS_REVISION_LOCK_MAX_WAIT_MS = 12e4;
+var SHA256_HEX = /^[0-9a-f]{64}$/;
+function isDigestOrNullOrUndefined(value) {
+  if (value === void 0 || value === null) return true;
+  return typeof value === "string" && SHA256_HEX.test(value);
+}
+function pendingWriteHasLanded(view) {
+  if (view.writeLanded === true) return true;
+  if (view.writeLanded === false) return false;
+  return view.expectedDigest !== void 0;
+}
+var CasRevisionStore = class {
+  baseDir;
+  legacyMetadataPath;
+  constructor(baseDir) {
+    this.baseDir = baseDir;
+    this.legacyMetadataPath = path2.join(baseDir, ".offline-sync", "cas-revisions.v1.json");
+  }
+  parseCasRevisionMetadata(raw) {
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      throw new Error("CAS revision metadata is invalid.");
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new Error("CAS revision metadata is invalid.");
+    }
+    const root = parsed;
+    if (Object.keys(root).sort().join(",") !== "revisions,version" || root.version !== 1 || !Array.isArray(root.revisions)) {
+      throw new Error("CAS revision metadata is invalid.");
+    }
+    const revisions = /* @__PURE__ */ new Map();
+    for (const rawEntry of root.revisions) {
+      if (!rawEntry || typeof rawEntry !== "object" || Array.isArray(rawEntry)) {
+        throw new Error("CAS revision metadata is invalid.");
+      }
+      const entry = rawEntry;
+      if (Object.keys(entry).sort().join(",") !== "path,revision" || typeof entry.path !== "string" || !isValidManagedStoragePath(entry.path) || typeof entry.revision !== "string" || entry.revision.length === 0 || revisions.has(entry.path)) {
+        throw new Error("CAS revision metadata is invalid.");
+      }
+      revisions.set(entry.path, entry.revision);
+    }
+    return revisions;
+  }
+  async readLegacyMetadata() {
+    const baseDir = path2.resolve(this.baseDir);
+    const legacyPath = await resolveSafeStoragePath(baseDir, path2.relative(baseDir, this.legacyMetadataPath));
+    let raw;
+    try {
+      raw = await readFile2(legacyPath, "utf8");
+    } catch (error) {
+      if (isErrnoCode(error, "ENOENT")) return /* @__PURE__ */ new Map();
+      throw new Error("CAS revision metadata is unavailable.");
+    }
+    return this.parseCasRevisionMetadata(raw);
+  }
+  /** #2813 (P1 A): every sidecar path is resolved (and symlink-audited)
+   * inside the memory root before it is used for a lock, read, rename, or
+   * unlink. A symlinked `.offline-sync`, `.offline-sync/cas-revisions`, or
+   * shard file makes this throw, so no sidecar traffic can follow a link
+   * out of the root. */
+  async getSafeShardInfo(relativePath) {
+    const baseDir = path2.resolve(this.baseDir);
+    const hash = createHash2("sha256").update(relativePath).digest("hex");
+    const shardPath = await resolveSafeStoragePath(baseDir, ".offline-sync", "cas-revisions", `${hash}.json`);
+    const lockPath = await resolveSafeStoragePath(baseDir, ".offline-sync", "cas-revisions", `${hash}.json.lock`);
+    return { shardPath, lockPath };
+  }
+  async readShardView(shardPath, relativePath) {
+    let raw;
+    try {
+      raw = await readFile2(shardPath, "utf8");
+    } catch (error) {
+      if (isErrnoCode(error, "ENOENT")) return { kind: "missing" };
+      throw error;
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      throw new Error("CAS revision shard is unreadable.");
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return { kind: "foreign" };
+    }
+    const root = parsed;
+    if (root.state !== void 0) {
+      if (root.version !== 1 || typeof root.path !== "string" || typeof root.revision !== "string" || root.revision.length === 0 || root.state !== "pending" && root.state !== "committed" || root.previous !== void 0 && (typeof root.previous !== "string" || root.previous.length === 0) || !isDigestOrNullOrUndefined(root.baselineDigest) || !isDigestOrNullOrUndefined(root.expectedDigest) || root.writeLanded !== void 0 && typeof root.writeLanded !== "boolean") {
+        throw new Error("CAS revision shard is unreadable.");
+      }
+      const foreign = root.path !== relativePath;
+      const committedDigest = typeof root.committedDigest === "string" ? root.committedDigest : void 0;
+      const committedSemanticFingerprint = typeof root.committedSemanticFingerprint === "string" ? root.committedSemanticFingerprint : void 0;
+      return root.state === "pending" ? {
+        kind: "pending",
+        revision: root.revision,
+        previous: root.previous,
+        foreign,
+        baselineDigest: root.baselineDigest,
+        expectedDigest: root.expectedDigest,
+        ...typeof root.writeLanded === "boolean" ? { writeLanded: root.writeLanded } : {}
+      } : {
+        kind: "committed",
+        revision: root.revision,
+        committedDigest,
+        committedSemanticFingerprint,
+        foreign
+      };
+    }
+    if (root.version === 1 && root.path === relativePath && typeof root.revision === "string" && root.revision.length > 0) {
+      const committedDigest = typeof root.committedDigest === "string" ? root.committedDigest : void 0;
+      const committedSemanticFingerprint = typeof root.committedSemanticFingerprint === "string" ? root.committedSemanticFingerprint : void 0;
+      return {
+        kind: "committed",
+        revision: root.revision,
+        committedDigest,
+        committedSemanticFingerprint,
+        foreign: false
+      };
+    }
+    return { kind: "foreign" };
+  }
+  async readStandingRevision(relativePath) {
+    try {
+      return await this.readStandingRevisionStrict(relativePath);
+    } catch (error) {
+      log.warn(`CasRevisionStore failed to read standing revision for ${relativePath}: ${error}`);
+      return void 0;
+    }
+  }
+  /** #2813 (P1 A): strict core of {@link readStandingRevision}. Returns
+   * undefined ONLY when no receipt exists for the target — the shard is
+   * absent (or names another target) and the legacy metadata holds no
+   * entry. THROWS when the standing receipt cannot be determined: an
+   * unreadable or corrupt shard, a PENDING reservation awaiting
+   * finalization or recovery, or unreadable or invalid legacy metadata.
+   * Fail-open callers collapse the throw into undefined; truthful callers
+   * ({@link readRevisionStatus}) report `unavailable` so a transaction can
+   * refuse instead of mistaking the failure for absence. */
+  async readStandingRevisionStrict(relativePath) {
+    const { shardPath } = await this.getSafeShardInfo(relativePath);
+    const view = await this.readShardView(shardPath, relativePath);
+    if (view.kind === "pending") {
+      throw new Error(
+        `CAS revision receipt for ${relativePath} is pending finalization (recovery needed).`
+      );
+    }
+    if (view.kind === "committed" && !view.foreign) {
+      return {
+        revision: view.revision,
+        committedDigest: view.committedDigest,
+        committedSemanticFingerprint: view.committedSemanticFingerprint
+      };
+    }
+    const legacyMap = await this.readLegacyMetadata();
+    const legacyRev = legacyMap.get(relativePath);
+    return legacyRev === void 0 ? void 0 : { revision: legacyRev };
+  }
+  async writeShard(shardPath, relativePath, revision, lock, state, previous, evidence) {
+    let payload;
+    if (state === "committed") {
+      payload = { version: 1, path: relativePath, revision, state };
+      if (evidence?.committedDigest !== void 0) {
+        payload.committedDigest = evidence.committedDigest;
+      }
+      if (evidence?.committedSemanticFingerprint !== void 0) {
+        payload.committedSemanticFingerprint = evidence.committedSemanticFingerprint;
+      }
+    } else {
+      payload = { version: 1, path: relativePath, revision, state };
+      if (previous !== void 0) payload.previous = previous;
+      if (evidence !== void 0) {
+        if (evidence.baselineDigest !== void 0) payload.baselineDigest = evidence.baselineDigest;
+        if (evidence.expectedDigest !== void 0) payload.expectedDigest = evidence.expectedDigest;
+        if (evidence.writeLanded !== void 0) payload.writeLanded = evidence.writeLanded;
+      }
+    }
+    const baseDir = path2.resolve(this.baseDir);
+    const temporaryPath = await resolveSafeStoragePath(
+      baseDir,
+      path2.relative(baseDir, `${shardPath}.${process.pid}.${randomUUID2()}.tmp`)
+    );
+    let handle = null;
+    try {
+      await mkdir2(path2.dirname(shardPath), { recursive: true });
+      handle = await open2(temporaryPath, "wx", 384);
+      await handle.writeFile(`${JSON.stringify(payload)}
+`, "utf8");
+      await handle.sync();
+      await handle.close();
+      handle = null;
+      if (!await lock.refresh()) {
+        throw new Error("CAS revision shard lock was lost.");
+      }
+      await rename2(temporaryPath, shardPath);
+    } finally {
+      if (handle !== null) {
+        await handle.close().catch((error) => {
+          log.warn("failed to close CAS revision shard temporary file", error);
+        });
+      }
+      await unlink2(temporaryPath).catch((error) => {
+        if (!isErrnoCode(error, "ENOENT")) {
+          log.warn("failed to clean up CAS revision shard temporary file", error);
+        }
+      });
+    }
+  }
+  async resolveRelativePath(filePath) {
+    const baseDir = path2.resolve(this.baseDir);
+    const target = await resolveSafeStoragePath(baseDir, path2.relative(baseDir, path2.resolve(baseDir, filePath)));
+    return path2.relative(baseDir, target).split(path2.sep).join("/");
+  }
+  async withShardLock(relativePath, task) {
+    const { lockPath } = await this.getSafeShardInfo(relativePath);
+    return await withHeldFileLock(
+      lockPath,
+      { staleMs: CAS_REVISION_LOCK_STALE_MS, maxWaitMs: CAS_REVISION_LOCK_MAX_WAIT_MS },
+      async (acquired, lock) => {
+        if (!acquired) throw new Error("CAS revision lock is unavailable.");
+        return await task(lock);
+      }
+    );
+  }
+  /** The target's standing revision token, or undefined when no receipt was
+   * ever minted for it. Fail-open on storage/read errors. */
+  async readRevision(filePath) {
+    try {
+      const relativePath = await this.resolveRelativePath(filePath);
+      return (await this.readStandingRevision(relativePath))?.revision;
+    } catch (error) {
+      log.warn(`CasRevisionStore.readRevision failed for ${filePath}: ${error}`);
+      return void 0;
+    }
+  }
+  /** #2813 (P1 A): the truthful standing-receipt read. `absent` means no
+   * receipt was ever minted for the target — undefined semantics stay
+   * correct for those records. `unavailable` means the sidecar could not
+   * be read OR a reservation is pending finalization; callers that
+   * transact on receipt identity MUST refuse rather than treat the
+   * failure as absence. */
+  async readRevisionStatus(filePath) {
+    try {
+      const relativePath = await this.resolveRelativePath(filePath);
+      const standing = await this.readStandingRevisionStrict(relativePath);
+      return standing === void 0 ? { status: "absent" } : {
+        status: "present",
+        revision: standing.revision,
+        ...standing.committedDigest !== void 0 ? { committedDigest: standing.committedDigest } : {},
+        ...standing.committedSemanticFingerprint !== void 0 ? { committedSemanticFingerprint: standing.committedSemanticFingerprint } : {}
+      };
+    } catch (error) {
+      return { status: "unavailable", reason: error instanceof Error ? error.message : String(error) };
+    }
+  }
+  /** #2813 (P1 C): reserve the NEXT revision token as a durable PENDING
+   * marker under the target's shard lock — the write-ahead record of a
+   * receipt transaction. The token is strictly greater than the standing
+   * token (max(clock, prev + 1ms)), so two commits can never share a
+   * receipt — not within one millisecond, not across a backward clock
+   * step. Refuses while another reservation is pending (recovery needed)
+   * or the standing receipt cannot be determined. The caller MUST either
+   * `commit` after its durable write lands or `abort` when it fails.
+   * #2807: the marker records the reserve-time fingerprint (`baselineDigest`)
+   * and optional expected post-write fingerprint (`expectedDigest`) with
+   * `writeLanded: false`. {@link recoverPendingRevision} decides crashes
+   * before or after the memory write from that evidence. */
+  async beginRevisionTransaction(filePath, expectedContent) {
+    const relativePath = await this.resolveRelativePath(filePath);
+    return await this.withShardLock(relativePath, async (lock) => {
+      const standingInfo = await this.readStandingRevisionStrict(relativePath);
+      const standing = standingInfo?.revision;
+      const next = nextCasRevisionIso(standing);
+      const baselineDigest = await this.digestDurableFile(relativePath);
+      const expectedDigest = expectedContent != null ? this.digestContent(expectedContent) : void 0;
+      const { shardPath } = await this.getSafeShardInfo(relativePath);
+      await this.writeShard(shardPath, relativePath, next, lock, "pending", standing, {
+        baselineDigest,
+        ...expectedDigest !== void 0 ? { expectedDigest } : {},
+        writeLanded: false
+      });
+      return {
+        pendingRevision: next,
+        writeLanded: () => this.recordPendingWriteLanded(relativePath, next),
+        commit: () => this.finalizeRevisionTransaction(relativePath, next, "commit"),
+        abort: () => this.finalizeRevisionTransaction(relativePath, next, "abort")
+      };
+    });
+  }
+  digestContent(content) {
+    const bytes = typeof content === "string" ? Buffer.from(content, "utf8") : content;
+    return createHash2("sha256").update(bytes).digest("hex");
+  }
+  async digestDurableFile(filePath) {
+    const bytes = await this.readDurableBytes(filePath);
+    return bytes === null ? null : createHash2("sha256").update(bytes).digest("hex");
+  }
+  /** #2870: canonical SEMANTIC fingerprint of the durable file — its text
+   * with the access-telemetry frontmatter keys stripped
+   * ({@link canonicalSemanticFileText}), hashed. Null means the file was
+   * absent. A fingerprint, never memory content. */
+  async semanticFingerprintDurableFile(filePath) {
+    const bytes = await this.readDurableBytes(filePath);
+    return bytes === null ? null : createHash2("sha256").update(canonicalSemanticFileText(bytes.toString("utf8"))).digest("hex");
+  }
+  async readDurableBytes(filePath) {
+    const relativePath = await this.resolveRelativePath(filePath);
+    const baseDir = path2.resolve(this.baseDir);
+    const target = await resolveSafeStoragePath(baseDir, relativePath);
+    try {
+      return await readFile2(target);
+    } catch (error) {
+      if (isErrnoCode(error, "ENOENT")) return null;
+      throw new Error(
+        `CAS revision evidence: durable memory file ${relativePath} is unreadable: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+  /** #2807: mark the reserved write as landed. Verifies a pre-recorded
+   * expected digest against the durable file, or records the file digest
+   * when none was reserved. Sets `writeLanded: true`. Idempotent. */
+  async recordPendingWriteLanded(relativePath, token) {
+    await this.withShardLock(relativePath, async (lock) => {
+      const { shardPath } = await this.getSafeShardInfo(relativePath);
+      const view = await this.readShardView(shardPath, relativePath);
+      if (view.kind !== "pending" || view.foreign || view.revision !== token) {
+        throw new Error(
+          `CAS revision evidence recording refused for ${relativePath}: the pending marker does not match the reserved token.`
+        );
+      }
+      if (pendingWriteHasLanded(view) && view.writeLanded !== false) return;
+      const currentDigest = await this.digestDurableFile(relativePath);
+      if (view.expectedDigest !== void 0 && currentDigest !== view.expectedDigest) {
+        throw new Error(
+          `CAS revision evidence recording refused for ${relativePath}: the durable file does not match the reserved expected digest.`
+        );
+      }
+      await this.writeShard(shardPath, relativePath, token, lock, "pending", view.previous, {
+        baselineDigest: view.baselineDigest === void 0 ? null : view.baselineDigest,
+        expectedDigest: view.expectedDigest !== void 0 ? view.expectedDigest : currentDigest,
+        writeLanded: true
+      });
+    });
+  }
+  async finalizeRevisionTransaction(relativePath, token, outcome) {
+    await this.withShardLock(relativePath, async (lock) => {
+      const { shardPath } = await this.getSafeShardInfo(relativePath);
+      const view = await this.readShardView(shardPath, relativePath);
+      if (view.kind === "pending" && !view.foreign && view.revision === token) {
+        if (outcome === "commit") {
+          const committedDigest = view.expectedDigest ?? await this.digestDurableFile(relativePath);
+          const committedSemanticFingerprint = await this.semanticFingerprintDurableFile(relativePath);
+          await this.writeShard(shardPath, relativePath, token, lock, "committed", void 0, {
+            committedDigest,
+            committedSemanticFingerprint
+          });
+        } else if (view.previous !== void 0) {
+          await this.writeShard(shardPath, relativePath, view.previous, lock, "committed");
+        } else {
+          await unlink2(shardPath);
+        }
+        return;
+      }
+      if (outcome === "commit" && view.kind === "committed" && !view.foreign && view.revision === token) {
+        return;
+      }
+      if (outcome === "abort" && view.kind === "missing") {
+        return;
+      }
+      throw new Error(
+        `CAS revision transaction ${outcome} refused for ${relativePath}: the pending marker does not match the reserved token.`
+      );
+    });
+  }
+  /** #2837: remove the target's receipt shard once its durable memory file
+   * has been deleted, so orphan shards cannot accumulate. Under the shard
+   * lock: a PENDING marker is crash-recovery evidence for
+   * {@link recoverPendingRevision} and is KEPT ("pending"); a shard naming
+   * another target is KEPT ("foreign") — never destroy a receipt you cannot
+   * attribute. Never touches the durable memory file or the legacy global
+   * metadata: a stale legacy entry keeps per-path monotonicity if the path
+   * is ever reused. */
+  async removeRevisionShard(filePath) {
+    const relativePath = await this.resolveRelativePath(filePath);
+    return await this.withShardLock(relativePath, async () => {
+      const { shardPath } = await this.getSafeShardInfo(relativePath);
+      const view = await this.readShardView(shardPath, relativePath);
+      if (view.kind === "missing") return "absent";
+      if (view.kind === "pending") return view.foreign ? "foreign" : "pending";
+      if (view.kind === "foreign" || view.foreign) return "foreign";
+      await unlink2(shardPath);
+      return "removed";
+    });
+  }
+  /** #2813 (P1 C): recovery for a reservation left PENDING by a crash or a
+   * failed publication. The caller supplies the KNOWN outcome of the
+   * durable memory write: `fileWriteLanded` publishes the pending token as
+   * the COMMITTED receipt; otherwise the reservation is discarded and the
+   * previous standing token restored. Idempotent — an already-committed or
+   * absent shard is reported, not mutated. */
+  async reconcilePendingRevision(filePath, fileWriteLanded) {
+    const relativePath = await this.resolveRelativePath(filePath);
+    return await this.withShardLock(relativePath, async (lock) => {
+      const { shardPath } = await this.getSafeShardInfo(relativePath);
+      const view = await this.readShardView(shardPath, relativePath);
+      if (view.kind === "committed") return "committed";
+      if (view.kind !== "pending") return "absent";
+      if (view.foreign) {
+        throw new Error(
+          `CAS revision pending marker for ${relativePath} names another target; manual recovery is required.`
+        );
+      }
+      if (fileWriteLanded) {
+        const committedDigest = view.expectedDigest ?? await this.digestDurableFile(relativePath);
+        const committedSemanticFingerprint = await this.semanticFingerprintDurableFile(relativePath);
+        await this.writeShard(shardPath, relativePath, view.revision, lock, "committed", void 0, {
+          committedDigest,
+          committedSemanticFingerprint
+        });
+      } else if (view.previous !== void 0) {
+        await this.writeShard(shardPath, relativePath, view.previous, lock, "committed");
+      } else {
+        await unlink2(shardPath);
+      }
+      return "reconciled";
+    });
+  }
+  /** #2807 (P1): evidence-based recovery for a reservation left PENDING by
+   * a crash between reserve and finalize. Under the shard lock, the durable
+   * file's current fingerprint is compared against the marker:
+   * - matches `expectedDigest` → publish the pending token as COMMITTED;
+   * - matches `baselineDigest` (including both absent) → abort and restore;
+   * - anything else THROWS. Recovery never guesses.
+   *
+   * `onlyWithWriteEvidence` is the unlocked read path. A marker whose write
+   * has not landed (`writeLanded` false, or legacy with no expectedDigest)
+   * may belong to a live writer, so it returns `reserved`. A landed marker
+   * whose file no longer matches `expectedDigest` throws ambiguity. */
+  async recoverPendingRevision(filePath, options) {
+    const relativePath = await this.resolveRelativePath(filePath);
+    return await this.withShardLock(relativePath, async (lock) => {
+      const { shardPath } = await this.getSafeShardInfo(relativePath);
+      const view = await this.readShardView(shardPath, relativePath);
+      if (view.kind === "missing" || view.kind === "foreign") return "absent";
+      if (view.kind === "committed") return view.foreign ? "absent" : "committed";
+      if (view.foreign) {
+        throw new Error(
+          `CAS revision pending marker for ${relativePath} names another target; manual recovery is required.`
+        );
+      }
+      const currentDigest = await this.digestDurableFile(relativePath);
+      const landed = pendingWriteHasLanded(view);
+      if (options?.onlyWithWriteEvidence && !landed) {
+        return "reserved";
+      }
+      if (view.expectedDigest !== void 0 && currentDigest === view.expectedDigest) {
+        await this.writeShard(shardPath, relativePath, view.revision, lock, "committed", void 0, {
+          committedDigest: view.expectedDigest,
+          committedSemanticFingerprint: await this.semanticFingerprintDurableFile(relativePath)
+        });
+        return "committed";
+      }
+      if (options?.onlyWithWriteEvidence) {
+        const evidence2 = view.expectedDigest === void 0 ? "the pending marker carries no crash evidence (written by an older version)" : "the durable file matches neither the expected commit fingerprint nor the reserve-time baseline";
+        throw new Error(
+          `CAS revision recovery for ${relativePath} is ambiguous: ${evidence2} (pending token ${view.revision}${view.previous !== void 0 ? `, previous ${view.previous}` : ""}). Inspect the durable file and the shard at ${shardPath}, then run reconcilePendingRevision with the known write outcome. Refusing to guess.`
+        );
+      }
+      if (view.baselineDigest !== void 0 && currentDigest === view.baselineDigest) {
+        if (view.previous !== void 0) {
+          await this.writeShard(shardPath, relativePath, view.previous, lock, "committed");
+        } else {
+          await unlink2(shardPath);
+        }
+        return "aborted";
+      }
+      const evidence = view.baselineDigest === void 0 && view.expectedDigest === void 0 ? "the pending marker carries no crash evidence (written by an older version)" : "the durable file matches neither the expected commit fingerprint nor the reserve-time baseline";
+      throw new Error(
+        `CAS revision recovery for ${relativePath} is ambiguous: ${evidence} (pending token ${view.revision}${view.previous !== void 0 ? `, previous ${view.previous}` : ""}). Inspect the durable file and the shard at ${shardPath}, then run reconcilePendingRevision with the known write outcome. Refusing to guess.`
+      );
+    });
+  }
+};
+
+// src/storage/cas-revision-host.ts
+var CasRevisionHost = class extends CasRevisionStore {
+  /** Standing CAS revision token — receipt identity, never public `updated` (#2807). Fail-open on read errors. */
+  async readCasRevision(filePath) {
+    try {
+      return await this.readRevision(filePath);
+    } catch (err) {
+      log.warn(`storage.readCasRevision failed for ${filePath}: ${err}`);
+      return void 0;
+    }
+  }
+  /** #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) {
+    const status = await this.readRevisionStatus(filePath);
+    if (status.status !== "unavailable" || !/pending/i.test(status.reason)) return status;
+    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) {
+    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, expectedContent) {
+    await this.recoverPendingRevision(pathname);
+    return await this.beginRevisionTransaction(pathname, expectedContent);
+  }
+  /** #2837: best-effort post-deletion sweep of the target's receipt shard.
+   * The durable memory file is already gone, so a failed sweep must never
+   * fail the deletion itself — it logs instead. A PENDING shard (crash
+   * recovery evidence) and a foreign shard (another target's receipt) are
+   * kept, with a warning naming the recovery path. */
+  async sweepShardAfterDeletion(filePath) {
+    try {
+      const outcome = await this.removeRevisionShard(filePath);
+      if (outcome === "pending") {
+        log.warn(
+          `CAS revision shard for ${filePath} kept after memory deletion: a pending reservation stands \u2014 run recovery before the path is reused`
+        );
+      } else if (outcome === "foreign") {
+        log.warn(
+          `CAS revision shard for ${filePath} kept after memory deletion: the shard names another target`
+        );
+      }
+    } catch (err) {
+      log.warn(`failed to sweep CAS revision shard for deleted memory ${filePath}: ${err}`);
+    }
+  }
+};
+
 // src/storage/tombstone-blocked-capture-mutation.ts
 import { AsyncLocalStorage } from "async_hooks";
-import { createHash as createHash2 } from "crypto";
-import { mkdir as mkdir2 } from "fs/promises";
-import path2 from "path";
+import { createHash as createHash3 } from "crypto";
+import { mkdir as mkdir3 } from "fs/promises";
+import path3 from "path";
 var TOMBSTONE_CAPTURE_WRITE_LOCK_STALE_MS = 6e4;
 var CAPTURE_WRITE_LOCK_MAX_ATTEMPTS = 3;
 var CAPTURE_WRITE_LOCK_RETRY_BASE_MS = 25;
@@ -502,7 +1077,7 @@ function buildCapturePathLockIdentity(pathname) {
   return `path ${pathname.length} ${pathname}`;
 }
 function captureIdentityHash(memory) {
-  return createHash2("sha256").update(
+  return createHash3("sha256").update(
     buildExplicitCaptureDedupKey(memory.content, memory.frontmatter.category, memory.frontmatter.sourceConnector)
   ).digest("hex");
 }
@@ -514,10 +1089,10 @@ var TombstoneBlockedCaptureWriteLock = class {
   context = new AsyncLocalStorage();
   captureWriteLockPathForHash(identityHash) {
     const filename = identityHash.length === 0 ? "explicit-capture-write.lock" : `explicit-capture-write-${identityHash}.lock`;
-    return path2.join(this.options.stateDir, "tombstone-blocked-capture", filename);
+    return path3.join(this.options.stateDir, "tombstone-blocked-capture", filename);
   }
   async withSingleCaptureWriteLock(lockPath, task) {
-    await mkdir2(path2.dirname(lockPath), { recursive: true });
+    await mkdir3(path3.dirname(lockPath), { recursive: true });
     const retry = /* @__PURE__ */ Symbol("retry");
     const permanentFailure = /* @__PURE__ */ Symbol("permanent-failure");
     const runWithHeldFileLock = this.options.withHeldFileLock ?? withHeldFileLock;
@@ -566,8 +1141,8 @@ var TombstoneBlockedCaptureWriteLock = class {
   }
   async withCaptureWriteLocks(task, identities, identityHashes) {
     const current = this.context.getStore();
-    const hashToken = (key) => `\0${key.length === 0 ? "" : createHash2("sha256").update(key).digest("hex")}`;
-    const identityHash = (key) => key.length === 0 ? "" : createHash2("sha256").update(key).digest("hex");
+    const hashToken = (key) => `\0${key.length === 0 ? "" : createHash3("sha256").update(key).digest("hex")}`;
+    const identityHash = (key) => key.length === 0 ? "" : createHash3("sha256").update(key).digest("hex");
     const identityKeys = [...new Set(identities)];
     const hashes = [...new Set(identityHashes)];
     const requested = [
@@ -695,16 +1270,16 @@ function isQueuedReviewMemory(memory) {
 }
 
 // src/storage/tombstone-blocked-capture-sync.ts
-import { createHash as createHash3, randomUUID as randomUUID3 } from "crypto";
-import { unlink as unlink3 } from "fs/promises";
-import path4 from "path";
+import { createHash as createHash4, randomUUID as randomUUID4 } from "crypto";
+import { unlink as unlink4 } from "fs/promises";
+import path5 from "path";
 import { isDeepStrictEqual } from "util";
 
 // src/storage/tombstone-blocked-capture-index.ts
 import { execFile } from "child_process";
-import { randomUUID as randomUUID2 } from "crypto";
-import { mkdir as mkdir3, readFile as readFile2, readdir, rename as rename2, stat, unlink as unlink2, writeFile } from "fs/promises";
-import path3 from "path";
+import { randomUUID as randomUUID3 } from "crypto";
+import { mkdir as mkdir4, readFile as readFile3, readdir, rename as rename3, stat, unlink as unlink3, writeFile } from "fs/promises";
+import path4 from "path";
 import { promisify } from "util";
 var REBUILD_MAX_ATTEMPTS = 3;
 var execFileAsync = promisify(execFile);
@@ -726,7 +1301,7 @@ var TombstoneBlockedCaptureIndex = class {
   }
   createIndex() {
     return new ContentHashIndex(
-      path3.join(this.options.stateDir, "tombstone-blocked-capture"),
+      path4.join(this.options.stateDir, "tombstone-blocked-capture"),
       this.options.secureStoreKeyProvider,
       this.options.secureStoreWriteKeyProvider,
       this.options.memoryDir,
@@ -734,19 +1309,19 @@ var TombstoneBlockedCaptureIndex = class {
     );
   }
   indexPath() {
-    return path3.join(this.options.stateDir, "tombstone-blocked-capture", "fact-hashes.txt");
+    return path4.join(this.options.stateDir, "tombstone-blocked-capture", "fact-hashes.txt");
   }
   rebuildMarkerPath() {
-    return path3.join(this.options.stateDir, "tombstone-blocked-capture", "rebuild-required");
+    return path4.join(this.options.stateDir, "tombstone-blocked-capture", "rebuild-required");
   }
   async readRebuildMarkers() {
     try {
       const entries = (await readdir(this.rebuildMarkerPath())).filter((entry) => !entry.startsWith("."));
       return (await Promise.all(
         entries.map(async (entry) => {
-          const markerPath = path3.join(this.rebuildMarkerPath(), entry);
+          const markerPath = path4.join(this.rebuildMarkerPath(), entry);
           try {
-            const raw = (await readFile2(markerPath, "utf8")).trim();
+            const raw = (await readFile3(markerPath, "utf8")).trim();
             if (raw === "committed") return { path: markerPath, committed: true };
             let value;
             let malformed = false;
@@ -767,7 +1342,7 @@ var TombstoneBlockedCaptureIndex = class {
             const markerStat = await stat(markerPath).catch(() => null);
             const createdAt = typeof value.createdAt === "number" && Number.isFinite(value.createdAt) ? value.createdAt : markerStat?.mtimeMs;
             if (typeof value.pid !== "number" || !Number.isInteger(value.pid)) malformed = true;
-            const ownerId = typeof value.ownerId === "string" && value.ownerId.length > 0 ? value.ownerId : path3.basename(markerPath);
+            const ownerId = typeof value.ownerId === "string" && value.ownerId.length > 0 ? value.ownerId : path4.basename(markerPath);
             if (typeof value.ownerId !== "string" || value.ownerId.length === 0) malformed = true;
             const processStartedAtMs = typeof value.processStartedAtMs === "number" && Number.isFinite(value.processStartedAtMs) && value.processStartedAtMs > 0 ? value.processStartedAtMs : void 0;
             return {
@@ -847,21 +1422,21 @@ var TombstoneBlockedCaptureIndex = class {
   }
   // A pending marker protects the pre-commit gap; only committed markers are safe for another writer to clear.
   async writeMarkerAtomically(markerPath, payload) {
-    const temporaryPath = `${markerPath}.tmp-${process.pid}-${randomUUID2()}`;
+    const temporaryPath = `${markerPath}.tmp-${process.pid}-${randomUUID3()}`;
     try {
       await writeFile(temporaryPath, payload, "utf8");
-      await rename2(temporaryPath, markerPath);
+      await rename3(temporaryPath, markerPath);
     } finally {
-      await unlink2(temporaryPath).catch((err) => {
+      await unlink3(temporaryPath).catch((err) => {
         if (!isErrnoCode(err, "ENOENT")) throw err;
       });
     }
   }
   async markRebuildRequired(committed = false) {
     const markerDir = this.rebuildMarkerPath();
-    await mkdir3(markerDir, { recursive: true });
-    const ownerId = randomUUID2();
-    const markerPath = path3.join(markerDir, ownerId);
+    await mkdir4(markerDir, { recursive: true });
+    const ownerId = randomUUID3();
+    const markerPath = path4.join(markerDir, ownerId);
     await this.writeMarkerAtomically(
       markerPath,
       `${JSON.stringify({
@@ -881,7 +1456,7 @@ var TombstoneBlockedCaptureIndex = class {
       `${JSON.stringify({
         state: "committed",
         pid: process.pid,
-        ownerId: path3.basename(markerPath),
+        ownerId: path4.basename(markerPath),
         createdAt: Date.now(),
         processStartedAtMs: MARKER_PROCESS_STARTED_AT_MS
       })}
@@ -892,7 +1467,7 @@ var TombstoneBlockedCaptureIndex = class {
     await Promise.all(
       markerPaths.map(async (markerPath) => {
         try {
-          await unlink2(markerPath);
+          await unlink3(markerPath);
         } catch (err) {
           if (!isErrnoCode(err, "ENOENT")) throw err;
         }
@@ -1133,8 +1708,8 @@ var TombstoneBlockedCaptureIndex = class {
     await this.failOpen("writeMemoryFrontmatter", () => this.sync(before, { ...before, frontmatter }, rebuildMarker));
   }
   shouldRebuildAfterInvalidationForPath(filePath) {
-    const relative = path3.relative(path3.resolve(this.options.memoryDir), path3.resolve(filePath));
-    const category = relative.split(path3.sep)[0];
+    const relative = path4.relative(path4.resolve(this.options.memoryDir), path4.resolve(filePath));
+    const category = relative.split(path4.sep)[0];
     return category === "cold" || RECALL_FALLBACK_DIRS.includes(category);
   }
 };
@@ -1271,6 +1846,24 @@ var TombstoneBlockedCaptureIndexHost = class {
   async beginDurableMemoryRevision(_pathname, _expectedContent) {
     return void 0;
   }
+  /** #2837 (shard cleanup): after a managed memory file is durably deleted,
+   * sweep its per-target CAS receipt shard so orphan shards cannot grow
+   * forever. The sweep runs under the shard's own lock and is best-effort —
+   * the memory file is already gone, so a sweep failure logs and never
+   * fails the delete. The sweeper is a second CasRevisionHost over the same
+   * memory dir; the host is stateless and every mutation serializes through
+   * the sidecar's file locks, so it shares the same shard files
+   * StorageManager's own host operates on. */
+  deletedMemoryShardSweeper = null;
+  async deleteManagedStorageFile(filePath, deletionMtimeMs) {
+    const deleted = await this.deleteManagedStorageFileDurable(filePath, deletionMtimeMs);
+    if (!deleted) return false;
+    if (this.deletedMemoryShardSweeper === null) {
+      this.deletedMemoryShardSweeper = new CasRevisionHost(this.tombstoneBlockedCaptureIndexOptions().memoryDir);
+    }
+    await this.deletedMemoryShardSweeper.sweepShardAfterDeletion(filePath);
+    return true;
+  }
   async writeStorageSecureFileChunks(filePath, chunks) {
     const options = this.tombstoneBlockedCaptureIndexOptions();
     await writeMaybeEncryptedFileFromChunks(
@@ -1477,7 +2070,7 @@ var TombstoneBlockedCaptureIndexHost = class {
     this.invalidateAllMemoriesCache();
     this.invalidateKnowledgeIndexCache();
     this.markFactHashIndexNotAuthoritative();
-    if (filePath.includes(`${path4.sep}cold${path4.sep}`)) {
+    if (filePath.includes(`${path5.sep}cold${path5.sep}`)) {
       this.invalidateColdMemoriesCache();
     }
     if (blockedKeySetMayHaveChanged) {
@@ -1490,7 +2083,7 @@ var TombstoneBlockedCaptureIndexHost = class {
         log.warn(`storage.offlineSyncFile committed write succeeded; marker cleanup failed: ${err}`);
       }
     }
-    if (filePath.includes(`${path4.sep}artifacts${path4.sep}`)) {
+    if (filePath.includes(`${path5.sep}artifacts${path5.sep}`)) {
       this.bumpArtifactWriteVersion();
     }
     const memoryDir = this.tombstoneBlockedCaptureIndexOptions().memoryDir;
@@ -1585,7 +2178,7 @@ var TombstoneBlockedCaptureIndexHost = class {
         bumpArchiveMutationForPath(memoryDir, true, current.path);
         markProjectedMemoryPathInvalid(memoryDir, current.frontmatter.id);
         this.invalidateAllMemoriesCache();
-        if (current.path.includes(`${path4.sep}cold${path4.sep}`)) {
+        if (current.path.includes(`${path5.sep}cold${path5.sep}`)) {
           this.invalidateColdMemoriesCache();
         }
         await this.rebuildTombstoneBlockedCaptureAfterInvalidation(rebuildMarker);
@@ -1668,7 +2261,7 @@ var TombstoneBlockedCaptureIndexHost = class {
   async writeTombstoneBlockedOfflineSyncFile(target, content) {
     const options = this.tombstoneBlockedCaptureIndexOptions();
     const after = options.parseMemory?.(target, content) ?? null;
-    await withRawEntityPageMutation(path4.dirname(options.stateDir), target, async () => {
+    await withRawEntityPageMutation(path5.dirname(options.stateDir), target, async () => {
       await this.runTombstoneBlockedOfflineSyncMutation(
         target,
         after,
@@ -1707,11 +2300,11 @@ var TombstoneBlockedCaptureIndexHost = class {
       return { after, chunks: replay };
     }
     const options = this.tombstoneBlockedCaptureIndexOptions();
-    const stagePath = path4.join(
+    const stagePath = path5.join(
       options.stateDir,
       "tombstone-blocked-capture",
       "offline-sync-staging",
-      `${randomUUID3()}.stage`
+      `${randomUUID4()}.stage`
     );
     const stagedChunks = (async function* () {
       for (const chunk of buffered) yield chunk;
@@ -1732,7 +2325,7 @@ var TombstoneBlockedCaptureIndexHost = class {
       );
       return await this.describeStagedOfflineSyncChunks(target, stagePath, parseMemory);
     } catch (err) {
-      await unlink3(stagePath).catch(() => {
+      await unlink4(stagePath).catch(() => {
       });
       throw err;
     }
@@ -1786,7 +2379,7 @@ var TombstoneBlockedCaptureIndexHost = class {
       encode("connector", connector),
       `content ${normalizedLength} `
     ].join(" ");
-    let identityHash = createHash3("sha256");
+    let identityHash = createHash4("sha256");
     let normalSigmaIdentityHash;
     identityHash.update(identityPrefix);
     const identityNormalizer = createExplicitContentNormalizer({
@@ -1832,7 +2425,7 @@ var TombstoneBlockedCaptureIndexHost = class {
     const coordinate = this.getTombstoneBlockedCaptureIndex().shouldRebuildAfterInvalidationForPath(target);
     const prepared = coordinate ? await this.prepareTombstoneBlockedOfflineSyncChunks(target, chunks) : { after: null, chunks };
     const streamedIdentity = prepared.streamedIdentity;
-    const baseDir = path4.dirname(this.tombstoneBlockedCaptureIndexOptions().stateDir);
+    const baseDir = path5.dirname(this.tombstoneBlockedCaptureIndexOptions().stateDir);
     try {
       await withRawEntityPageMutation(baseDir, target, async () => {
         await this.runTombstoneBlockedOfflineSyncMutation(
@@ -1844,7 +2437,7 @@ var TombstoneBlockedCaptureIndexHost = class {
         );
       });
     } finally {
-      if (prepared.stagePath !== void 0) await unlink3(prepared.stagePath).catch(() => {
+      if (prepared.stagePath !== void 0) await unlink4(prepared.stagePath).catch(() => {
       });
     }
   }
@@ -1864,7 +2457,7 @@ var TombstoneBlockedCaptureIndexHost = class {
    */
   async requestSyncReconcileIfMigrationPath(target) {
     const stateDir = this.tombstoneBlockedCaptureIndexOptions().stateDir;
-    if (!pathMayCarryEntityRefs(path4.dirname(stateDir), target)) return;
+    if (!pathMayCarryEntityRefs(path5.dirname(stateDir), target)) return;
     await requestEntityCanonicalIdReconcile(stateDir);
   }
   async deleteOfflineSyncFile(filePath, deletionMtimeMs) {
@@ -1874,7 +2467,7 @@ var TombstoneBlockedCaptureIndexHost = class {
   }
   async deleteTombstoneBlockedOfflineSyncFile(target, deletionMtimeMs) {
     const stateDir = this.tombstoneBlockedCaptureIndexOptions().stateDir;
-    await withRawEntityPageMutation(path4.dirname(stateDir), target, async () => {
+    await withRawEntityPageMutation(path5.dirname(stateDir), target, async () => {
       await this.runTombstoneBlockedOfflineSyncMutation(target, null, async () => {
         return await this.deleteManagedStorageFile(target, deletionMtimeMs);
       });
@@ -1903,10 +2496,10 @@ var TombstoneBlockedCaptureIndexHost = class {
 export {
   invalidationCommitFingerprint,
   casCommittedRevisionOf,
-  nextCasRevisionIso,
   withCasCommitReceipt,
-  isValidManagedStoragePath,
   DeletionRevisionStore,
+  canonicalSemanticFileText,
+  CasRevisionHost,
   isTombstoneBlockedCaptureWriteLockBusy,
   normalizeExplicitCaptureContent,
   buildExplicitCaptureDedupKey,
@@ -1916,4 +2509,4 @@ export {
   parseTombstoneBlockedOfflineSyncMemory,
   TombstoneBlockedCaptureIndexHost
 };
-//# sourceMappingURL=chunk-SHEHQBCG.js.map
+//# sourceMappingURL=chunk-DUJYRVUD.js.map