@remnic/core 9.54.4 → 9.54.6

package/dist/{chunk-K4QS7LXU.js → chunk-K2UGPTYY.js}

@@ -12,10 +12,13 @@ import {
 } from "./chunk-CX5SW2EW.js";
 import {
   markProjectedMemoryPathInvalid
-} from "./chunk-3CSX3ETE.js";
+} from "./chunk-2LWQSV6A.js";
 import {
   withHeldFileLock
 } from "./chunk-FFAZ2XFU.js";
+import {
+  resolveSafeStoragePath
+} from "./chunk-FF4KLI5W.js";
 import {
   readMaybeEncryptedFileFromChunks,
   writeMaybeEncryptedFileFromChunks
@@ -30,11 +33,427 @@ import {
   log
 } from "./chunk-3WCASNQZ.js";
 
+// src/storage/deletion-revision-store.ts
+import { createHash, randomUUID } from "crypto";
+import { lstat, mkdir, open, readFile, rename, unlink } from "fs/promises";
+import path from "path";
+var DELETION_REVISION_MAX_MTIME_MS = 864e13;
+var DELETION_REVISION_LOCK_STALE_MS = 6e4;
+var DELETION_REVISION_LOCK_MAX_WAIT_MS = 12e4;
+var INVALIDATION_COMMIT_MAX_TIMESTAMP_MS = 864e13;
+var INVALIDATION_PROOF_QUARANTINE_MAX_IDS = 1024;
+function canonicalizeInvalidationEvidence(value) {
+  if (Array.isArray(value)) return value.map((item) => canonicalizeInvalidationEvidence(item));
+  if (value && typeof value === "object") {
+    const result = {};
+    for (const key of Object.keys(value).sort()) {
+      result[key] = canonicalizeInvalidationEvidence(value[key]);
+    }
+    return result;
+  }
+  return value;
+}
+function invalidationCommitFingerprint(memory) {
+  const frontmatter = { ...memory.frontmatter };
+  delete frontmatter.accessCount;
+  delete frontmatter.lastAccessed;
+  return createHash("sha256").update(
+    JSON.stringify(
+      canonicalizeInvalidationEvidence({
+        content: memory.content,
+        frontmatter
+      })
+    )
+  ).digest("hex");
+}
+function isValidInvalidationCommitTimestamp(value) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= INVALIDATION_COMMIT_MAX_TIMESTAMP_MS;
+}
+function isValidInvalidationCommitFingerprint(value) {
+  return typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
+}
+function isValidMemoryId(value) {
+  return typeof value === "string" && value.length > 0 && !value.includes("\0");
+}
+function isValidDeletionRevisionPath(value) {
+  return typeof value === "string" && value.length > 0 && !value.includes("\\") && !value.includes("\0") && !path.posix.isAbsolute(value) && path.posix.normalize(value) === value && value !== "." && value !== ".." && !value.startsWith("../");
+}
+function deletionRevisionPathIdentity(value) {
+  return value.normalize("NFC").toUpperCase().toLowerCase();
+}
+var DeletionRevisionStore = class {
+  options;
+  invalidationProofQuarantine = /* @__PURE__ */ new Set();
+  invalidationProofQuarantineFull = false;
+  invalidationProofQuarantineFullAt = null;
+  constructor(options) {
+    this.options = options;
+  }
+  quarantineInvalidationProof(memoryId) {
+    if (this.invalidationProofQuarantineFull) {
+      const nextBoundary = Date.now() + 1;
+      this.invalidationProofQuarantineFullAt = Math.max(
+        this.invalidationProofQuarantineFullAt ?? 0,
+        nextBoundary
+      );
+      return;
+    }
+    if (this.invalidationProofQuarantine.has(memoryId)) return;
+    if (this.invalidationProofQuarantine.size >= INVALIDATION_PROOF_QUARANTINE_MAX_IDS) {
+      this.invalidationProofQuarantineFull = true;
+      this.invalidationProofQuarantineFullAt = Date.now() + 1;
+      return;
+    }
+    this.invalidationProofQuarantine.add(memoryId);
+  }
+  async resolveConfiguredStoragePath(targetPath) {
+    const baseDir = path.resolve(this.options.baseDir);
+    const relativePath = path.relative(baseDir, path.resolve(targetPath));
+    return resolveSafeStoragePath(baseDir, relativePath);
+  }
+  async resolveManagedStoragePath(filePath, method) {
+    const assertedPath = this.options.assertManagedStoragePath(filePath, method);
+    const target = await this.resolveConfiguredStoragePath(assertedPath);
+    const relativePath = path.relative(path.resolve(this.options.baseDir), target).split(path.sep).join("/");
+    return { target, relativePath };
+  }
+  parseDeletionRevisionMetadata(raw) {
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      throw new Error("Deletion revision metadata is invalid.");
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new Error("Deletion revision metadata is invalid.");
+    }
+    const root = parsed;
+    if (Object.keys(root).sort().join(",") !== "deletions,version" || root.version !== 1 || !Array.isArray(root.deletions)) {
+      throw new Error("Deletion revision metadata is invalid.");
+    }
+    const revisions = /* @__PURE__ */ new Map();
+    const pathByIdentity = /* @__PURE__ */ new Map();
+    for (const rawEntry of root.deletions) {
+      if (!rawEntry || typeof rawEntry !== "object" || Array.isArray(rawEntry)) {
+        throw new Error("Deletion revision metadata is invalid.");
+      }
+      const entry = rawEntry;
+      if (Object.keys(entry).sort().join(",") !== "mtimeMs,path" || !isValidDeletionRevisionPath(entry.path) || typeof entry.mtimeMs !== "number" || !Number.isFinite(entry.mtimeMs) || entry.mtimeMs < 0 || entry.mtimeMs > DELETION_REVISION_MAX_MTIME_MS || revisions.has(entry.path)) {
+        throw new Error("Deletion revision metadata is invalid.");
+      }
+      const identity = deletionRevisionPathIdentity(entry.path);
+      if (pathByIdentity.has(identity)) {
+        throw new Error("Deletion revision metadata is invalid.");
+      }
+      pathByIdentity.set(identity, entry.path);
+      revisions.set(entry.path, entry.mtimeMs);
+    }
+    return new Map([...revisions.entries()].sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0));
+  }
+  async readDeletionRevisionMetadata() {
+    const metadataPath = await this.resolveConfiguredStoragePath(this.options.deletionRevisionMetadataPath);
+    let raw;
+    try {
+      raw = await readFile(metadataPath, "utf8");
+    } catch (error) {
+      if (isErrnoCode(error, "ENOENT")) return /* @__PURE__ */ new Map();
+      throw new Error("Deletion revision metadata is unavailable.");
+    }
+    return this.parseDeletionRevisionMetadata(raw);
+  }
+  async writeDeletionRevisionMetadata(revisions, lock) {
+    const metadataPath = await this.resolveConfiguredStoragePath(this.options.deletionRevisionMetadataPath);
+    const deletions = [...revisions.entries()].sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0).map(([entryPath, mtimeMs]) => ({ path: entryPath, mtimeMs }));
+    const metadata = { version: 1, deletions };
+    const temporaryPath = await this.resolveConfiguredStoragePath(
+      `${metadataPath}.${process.pid}.${randomUUID()}.tmp`
+    );
+    let handle = null;
+    try {
+      handle = await open(temporaryPath, "wx", 384);
+      await handle.writeFile(`${JSON.stringify(metadata)}
+`, "utf8");
+      await handle.sync();
+      await handle.close();
+      handle = null;
+      if (!await lock.refresh()) {
+        throw new Error("Deletion revision metadata lock was lost.");
+      }
+      const renameTarget = await this.resolveConfiguredStoragePath(this.options.deletionRevisionMetadataPath);
+      await rename(temporaryPath, renameTarget);
+    } finally {
+      if (handle !== null) {
+        await handle.close().catch((error) => {
+          log.warn("failed to close deletion revision metadata temporary file", error);
+        });
+      }
+      const cleanupPath = await this.resolveConfiguredStoragePath(temporaryPath).catch((error) => {
+        log.warn("failed to resolve deletion revision metadata temporary file for cleanup", error);
+        return null;
+      });
+      if (cleanupPath !== null) {
+        await unlink(cleanupPath).catch((error) => {
+          if (!isErrnoCode(error, "ENOENT")) {
+            log.warn("failed to clean up deletion revision metadata temporary file", error);
+          }
+        });
+      }
+    }
+  }
+  async withDeletionRevisionLock(task) {
+    const lockPath = await this.resolveConfiguredStoragePath(this.options.deletionRevisionLockPath);
+    return withHeldFileLock(
+      lockPath,
+      {
+        staleMs: DELETION_REVISION_LOCK_STALE_MS,
+        maxWaitMs: DELETION_REVISION_LOCK_MAX_WAIT_MS
+      },
+      async (acquired, lock) => {
+        if (!acquired) throw new Error("Deletion revision metadata lock is unavailable.");
+        return task(lock);
+      }
+    );
+  }
+  async readDeletionRevisions() {
+    return this.withDeletionRevisionLock(async () => this.readDeletionRevisionMetadata());
+  }
+  parseInvalidationCommitMetadata(raw) {
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      throw new Error("Invalidation commit metadata is invalid.");
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new Error("Invalidation commit metadata is invalid.");
+    }
+    const root = parsed;
+    if (Object.keys(root).sort().join(",") !== "commits,version" || root.version !== 1 || !Array.isArray(root.commits)) {
+      throw new Error("Invalidation commit metadata is invalid.");
+    }
+    const commits = /* @__PURE__ */ new Map();
+    for (const rawEntry of root.commits) {
+      if (!rawEntry || typeof rawEntry !== "object" || Array.isArray(rawEntry)) {
+        throw new Error("Invalidation commit metadata is invalid.");
+      }
+      const entry = rawEntry;
+      if (Object.keys(entry).sort().join(",") !== "committedAt,fingerprint,memoryId" || !isValidMemoryId(entry.memoryId) || !isValidInvalidationCommitFingerprint(entry.fingerprint) || !isValidInvalidationCommitTimestamp(entry.committedAt) || commits.has(entry.memoryId)) {
+        throw new Error("Invalidation commit metadata is invalid.");
+      }
+      commits.set(entry.memoryId, {
+        fingerprint: entry.fingerprint,
+        committedAt: entry.committedAt
+      });
+    }
+    return commits;
+  }
+  async readInvalidationCommitMetadata() {
+    const metadataPath = await this.resolveConfiguredStoragePath(this.options.invalidationCommitMetadataPath);
+    let raw;
+    try {
+      raw = await readFile(metadataPath, "utf8");
+    } catch (error) {
+      if (isErrnoCode(error, "ENOENT")) return /* @__PURE__ */ new Map();
+      throw new Error("Invalidation commit metadata is unavailable.");
+    }
+    return this.parseInvalidationCommitMetadata(raw);
+  }
+  async writeInvalidationCommitMetadata(commits, lock) {
+    const metadataPath = await this.resolveConfiguredStoragePath(this.options.invalidationCommitMetadataPath);
+    const entries = [...commits.entries()].sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0).map(([memoryId, value]) => ({
+      memoryId,
+      fingerprint: value.fingerprint,
+      committedAt: value.committedAt
+    }));
+    const metadata = { version: 1, commits: entries };
+    const temporaryPath = await this.resolveConfiguredStoragePath(
+      `${metadataPath}.${process.pid}.${randomUUID()}.tmp`
+    );
+    const metadataDir = await this.resolveConfiguredStoragePath(path.dirname(metadataPath));
+    let handle = null;
+    let renamed = false;
+    try {
+      await mkdir(metadataDir, { recursive: true });
+      handle = await open(temporaryPath, "wx", 384);
+      await handle.writeFile(`${JSON.stringify(metadata)}
+`, "utf8");
+      await handle.sync();
+      await handle.close();
+      handle = null;
+      if (!await lock.refresh()) {
+        throw new Error("Invalidation commit metadata lock was lost.");
+      }
+      const renameTarget = await this.resolveConfiguredStoragePath(this.options.invalidationCommitMetadataPath);
+      await rename(temporaryPath, renameTarget);
+      renamed = true;
+    } finally {
+      if (handle !== null) {
+        await handle.close().catch((error) => {
+          log.warn("failed to close invalidation commit metadata temporary file", error);
+        });
+      }
+      const cleanupPath = await this.resolveConfiguredStoragePath(temporaryPath).catch((error) => {
+        log.warn("failed to resolve invalidation commit metadata temporary file for cleanup", error);
+        return null;
+      });
+      if (cleanupPath !== null) {
+        await unlink(cleanupPath).catch((error) => {
+          if (!isErrnoCode(error, "ENOENT")) {
+            log.warn(
+              `failed to clean up invalidation commit metadata temporary file after ${renamed ? "commit" : "failure"}`,
+              error
+            );
+          }
+        });
+      }
+    }
+  }
+  async hasCommittedInvalidation(memory) {
+    const memoryId = memory.frontmatter.id;
+    const fingerprint = invalidationCommitFingerprint(memory);
+    return this.withDeletionRevisionLock(async () => {
+      const entry = (await this.readInvalidationCommitMetadata()).get(memoryId);
+      if (entry?.fingerprint !== fingerprint) return false;
+      if (this.invalidationProofQuarantine.has(memoryId)) return false;
+      if (!this.invalidationProofQuarantineFull) return true;
+      const fullAt = this.invalidationProofQuarantineFullAt;
+      return fullAt !== null && entry.committedAt >= fullAt;
+    });
+  }
+  async recordCommittedInvalidation(memory) {
+    const fingerprint = invalidationCommitFingerprint(memory);
+    await this.withDeletionRevisionLock(async (lock) => {
+      const fullAt = this.invalidationProofQuarantineFullAt;
+      const committedAt = fullAt === null ? Date.now() : Math.max(Date.now(), fullAt + 1);
+      const commits = await this.readInvalidationCommitMetadata();
+      commits.set(memory.frontmatter.id, {
+        fingerprint,
+        committedAt
+      });
+      await this.writeInvalidationCommitMetadata(commits, lock);
+      this.invalidationProofQuarantine.delete(memory.frontmatter.id);
+    });
+  }
+  async clearCommittedInvalidation(memory) {
+    const memoryId = memory.frontmatter.id;
+    this.quarantineInvalidationProof(memoryId);
+    const fingerprint = invalidationCommitFingerprint(memory);
+    let cleared = false;
+    try {
+      await this.withDeletionRevisionLock(async (lock) => {
+        const commits = await this.readInvalidationCommitMetadata();
+        const current = commits.get(memoryId);
+        if (current?.fingerprint !== fingerprint) return;
+        commits.delete(memoryId);
+        await this.writeInvalidationCommitMetadata(commits, lock);
+      });
+      cleared = true;
+    } finally {
+      if (cleared) this.invalidationProofQuarantine.delete(memoryId);
+    }
+  }
+  async recordReplicatedDeletionRevision(filePath, mtimeMs) {
+    const { relativePath } = await this.resolveManagedStoragePath(
+      filePath,
+      "storage.recordReplicatedDeletionRevision"
+    );
+    if (typeof mtimeMs !== "number" || !Number.isFinite(mtimeMs) || mtimeMs < 0 || mtimeMs > DELETION_REVISION_MAX_MTIME_MS) {
+      throw new Error("Deletion revision timestamp is invalid.");
+    }
+    if (!isValidDeletionRevisionPath(relativePath)) {
+      throw new Error("Deletion revision path is invalid.");
+    }
+    await this.withDeletionRevisionLock(async (lock) => {
+      const revisions = await this.readDeletionRevisionMetadata();
+      const identity = deletionRevisionPathIdentity(relativePath);
+      let existingPath;
+      for (const candidatePath of revisions.keys()) {
+        if (deletionRevisionPathIdentity(candidatePath) === identity) {
+          existingPath = candidatePath;
+          break;
+        }
+      }
+      const existingMtimeMs = existingPath === void 0 ? void 0 : revisions.get(existingPath);
+      if (existingMtimeMs !== void 0 && existingMtimeMs >= mtimeMs) return;
+      const updated = new Map(revisions);
+      if (existingPath !== void 0) updated.delete(existingPath);
+      updated.set(relativePath, mtimeMs);
+      await this.writeDeletionRevisionMetadata(updated, lock);
+    });
+  }
+  async writeManagedStorageFile(filePath, write) {
+    const { relativePath } = await this.resolveManagedStoragePath(filePath, "storage.writeManagedStorageFile");
+    if (!isValidDeletionRevisionPath(relativePath)) {
+      throw new Error("Deletion revision path is invalid.");
+    }
+    await this.withDeletionRevisionLock(async (lock) => {
+      const before = await this.readDeletionRevisionMetadata();
+      const identity = deletionRevisionPathIdentity(relativePath);
+      const existingPath = [...before.keys()].find(
+        (candidatePath) => deletionRevisionPathIdentity(candidatePath) === identity
+      );
+      await write();
+      if (existingPath === void 0) return;
+      const updated = new Map(before);
+      updated.delete(existingPath);
+      await this.writeDeletionRevisionMetadata(updated, lock);
+    });
+  }
+  async deleteManagedStorageFile(filePath, deletionMtimeMs) {
+    const { target, relativePath } = await this.resolveManagedStoragePath(
+      filePath,
+      "storage.deleteManagedStorageFile"
+    );
+    if (deletionMtimeMs !== void 0 && deletionMtimeMs !== null && (typeof deletionMtimeMs !== "number" || !Number.isFinite(deletionMtimeMs) || deletionMtimeMs < 0 || deletionMtimeMs > DELETION_REVISION_MAX_MTIME_MS)) {
+      throw new Error("Deletion revision timestamp is invalid.");
+    }
+    return this.withDeletionRevisionLock(async (lock) => {
+      const safeTarget = await this.resolveConfiguredStoragePath(target);
+      try {
+        await lstat(safeTarget);
+      } catch (error) {
+        if (isErrnoCode(error, "ENOENT")) return false;
+        throw error;
+      }
+      if (!isValidDeletionRevisionPath(relativePath)) {
+        throw new Error("Deletion revision path is invalid.");
+      }
+      const revision = deletionMtimeMs === null ? void 0 : deletionMtimeMs ?? Date.now();
+      const before = await this.readDeletionRevisionMetadata();
+      const identity = deletionRevisionPathIdentity(relativePath);
+      let existingPath;
+      for (const candidatePath of before.keys()) {
+        if (deletionRevisionPathIdentity(candidatePath) === identity) {
+          existingPath = candidatePath;
+          break;
+        }
+      }
+      const existing = existingPath === void 0 ? void 0 : before.get(existingPath);
+      const changed = existingPath !== void 0 && existingPath !== relativePath || (revision === void 0 ? existing !== void 0 : existing !== revision);
+      if (changed) {
+        const updated = new Map(before);
+        if (existingPath !== void 0) updated.delete(existingPath);
+        if (revision !== void 0) updated.set(relativePath, revision);
+        await this.writeDeletionRevisionMetadata(updated, lock);
+      }
+      try {
+        const unlinkTarget = await this.resolveConfiguredStoragePath(target);
+        await unlink(unlinkTarget);
+        return true;
+      } catch (error) {
+        if (changed) await this.writeDeletionRevisionMetadata(before, lock);
+        if (isErrnoCode(error, "ENOENT")) return false;
+        throw error;
+      }
+    });
+  }
+};
+
 // src/storage/tombstone-blocked-capture-mutation.ts
 import { AsyncLocalStorage } from "async_hooks";
-import { createHash } from "crypto";
-import { mkdir } from "fs/promises";
-import path from "path";
+import { createHash as createHash2 } from "crypto";
+import { mkdir as mkdir2 } from "fs/promises";
+import path2 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;
@@ -57,7 +476,7 @@ function buildCapturePathLockIdentity(pathname) {
   return `path ${pathname.length} ${pathname}`;
 }
 function captureIdentityHash(memory) {
-  return createHash("sha256").update(
+  return createHash2("sha256").update(
     buildExplicitCaptureDedupKey(memory.content, memory.frontmatter.category, memory.frontmatter.sourceConnector)
   ).digest("hex");
 }
@@ -69,10 +488,10 @@ var TombstoneBlockedCaptureWriteLock = class {
   context = new AsyncLocalStorage();
   captureWriteLockPathForHash(identityHash) {
     const filename = identityHash.length === 0 ? "explicit-capture-write.lock" : `explicit-capture-write-${identityHash}.lock`;
-    return path.join(this.options.stateDir, "tombstone-blocked-capture", filename);
+    return path2.join(this.options.stateDir, "tombstone-blocked-capture", filename);
   }
   async withSingleCaptureWriteLock(lockPath, task) {
-    await mkdir(path.dirname(lockPath), { recursive: true });
+    await mkdir2(path2.dirname(lockPath), { recursive: true });
     const retry = /* @__PURE__ */ Symbol("retry");
     const permanentFailure = /* @__PURE__ */ Symbol("permanent-failure");
     const runWithHeldFileLock = this.options.withHeldFileLock ?? withHeldFileLock;
@@ -121,8 +540,8 @@ var TombstoneBlockedCaptureWriteLock = class {
   }
   async withCaptureWriteLocks(task, identities, identityHashes) {
     const current = this.context.getStore();
-    const hashToken = (key) => `\0${key.length === 0 ? "" : createHash("sha256").update(key).digest("hex")}`;
-    const identityHash = (key) => key.length === 0 ? "" : createHash("sha256").update(key).digest("hex");
+    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 identityKeys = [...new Set(identities)];
     const hashes = [...new Set(identityHashes)];
     const requested = [
@@ -217,16 +636,16 @@ function isQueuedReviewMemory(memory) {
 }
 
 // src/storage/tombstone-blocked-capture-sync.ts
-import { createHash as createHash2, randomUUID as randomUUID2 } from "crypto";
-import { unlink as unlink2 } from "fs/promises";
-import path3 from "path";
+import { createHash as createHash3, randomUUID as randomUUID3 } from "crypto";
+import { unlink as unlink3 } from "fs/promises";
+import path4 from "path";
 import { isDeepStrictEqual } from "util";
 
 // src/storage/tombstone-blocked-capture-index.ts
 import { execFile } from "child_process";
-import { randomUUID } from "crypto";
-import { mkdir as mkdir2, readFile, readdir, rename, stat, unlink, writeFile } from "fs/promises";
-import path2 from "path";
+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 { promisify } from "util";
 var REBUILD_MAX_ATTEMPTS = 3;
 var execFileAsync = promisify(execFile);
@@ -248,7 +667,7 @@ var TombstoneBlockedCaptureIndex = class {
   }
   createIndex() {
     return new ContentHashIndex(
-      path2.join(this.options.stateDir, "tombstone-blocked-capture"),
+      path3.join(this.options.stateDir, "tombstone-blocked-capture"),
       this.options.secureStoreKeyProvider,
       this.options.secureStoreWriteKeyProvider,
       this.options.memoryDir,
@@ -256,19 +675,19 @@ var TombstoneBlockedCaptureIndex = class {
     );
   }
   indexPath() {
-    return path2.join(this.options.stateDir, "tombstone-blocked-capture", "fact-hashes.txt");
+    return path3.join(this.options.stateDir, "tombstone-blocked-capture", "fact-hashes.txt");
   }
   rebuildMarkerPath() {
-    return path2.join(this.options.stateDir, "tombstone-blocked-capture", "rebuild-required");
+    return path3.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 = path2.join(this.rebuildMarkerPath(), entry);
+          const markerPath = path3.join(this.rebuildMarkerPath(), entry);
           try {
-            const raw = (await readFile(markerPath, "utf8")).trim();
+            const raw = (await readFile2(markerPath, "utf8")).trim();
             if (raw === "committed") return { path: markerPath, committed: true };
             let value;
             let malformed = false;
@@ -289,7 +708,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 : path2.basename(markerPath);
+            const ownerId = typeof value.ownerId === "string" && value.ownerId.length > 0 ? value.ownerId : path3.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 {
@@ -369,21 +788,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}-${randomUUID()}`;
+    const temporaryPath = `${markerPath}.tmp-${process.pid}-${randomUUID2()}`;
     try {
       await writeFile(temporaryPath, payload, "utf8");
-      await rename(temporaryPath, markerPath);
+      await rename2(temporaryPath, markerPath);
     } finally {
-      await unlink(temporaryPath).catch((err) => {
+      await unlink2(temporaryPath).catch((err) => {
         if (!isErrnoCode(err, "ENOENT")) throw err;
       });
     }
   }
   async markRebuildRequired(committed = false) {
     const markerDir = this.rebuildMarkerPath();
-    await mkdir2(markerDir, { recursive: true });
-    const ownerId = randomUUID();
-    const markerPath = path2.join(markerDir, ownerId);
+    await mkdir3(markerDir, { recursive: true });
+    const ownerId = randomUUID2();
+    const markerPath = path3.join(markerDir, ownerId);
     await this.writeMarkerAtomically(
       markerPath,
       `${JSON.stringify({
@@ -403,7 +822,7 @@ var TombstoneBlockedCaptureIndex = class {
       `${JSON.stringify({
         state: "committed",
         pid: process.pid,
-        ownerId: path2.basename(markerPath),
+        ownerId: path3.basename(markerPath),
         createdAt: Date.now(),
         processStartedAtMs: MARKER_PROCESS_STARTED_AT_MS
       })}
@@ -414,7 +833,7 @@ var TombstoneBlockedCaptureIndex = class {
     await Promise.all(
       markerPaths.map(async (markerPath) => {
         try {
-          await unlink(markerPath);
+          await unlink2(markerPath);
         } catch (err) {
           if (!isErrnoCode(err, "ENOENT")) throw err;
         }
@@ -644,8 +1063,8 @@ var TombstoneBlockedCaptureIndex = class {
     await this.failOpen("writeMemoryFrontmatter", () => this.sync(before, { ...before, frontmatter }, rebuildMarker));
   }
   shouldRebuildAfterInvalidationForPath(filePath) {
-    const relative = path2.relative(path2.resolve(this.options.memoryDir), path2.resolve(filePath));
-    const category = relative.split(path2.sep)[0];
+    const relative = path3.relative(path3.resolve(this.options.memoryDir), path3.resolve(filePath));
+    const category = relative.split(path3.sep)[0];
     return category === "cold" || RECALL_FALLBACK_DIRS.includes(category);
   }
 };
@@ -793,6 +1212,26 @@ var TombstoneBlockedCaptureIndexHost = class {
   async withTombstoneBlockedCaptureWriteLock(task, identity) {
     return await this.getTombstoneBlockedCaptureIndex().withCaptureWriteLock(task, identity);
   }
+  /** Read selected memories while their mutation locks remain held. */
+  async readMemorySnapshotsIfUnchanged(expected) {
+    return await this.withMemorySnapshotsIfUnchanged(expected, async (memories) => memories);
+  }
+  async withMemorySnapshotsIfUnchanged(expected, task) {
+    if (expected.length === 0) return await task([]);
+    const pathnames = [...new Set(expected.map((memory) => memory.path))];
+    if (pathnames.length !== expected.length) return null;
+    return await this.withTombstoneBlockedCaptureWriteLock(async () => {
+      const current = await Promise.all(pathnames.map((pathname) => this.readMemoryByPath(pathname)));
+      for (let index = 0; index < expected.length; index += 1) {
+        const actual = current[index];
+        const snapshot = expected[index];
+        if (!actual || !snapshot || actual.frontmatter.id !== snapshot.frontmatter.id || invalidationCommitFingerprint(actual) !== invalidationCommitFingerprint(snapshot)) {
+          return null;
+        }
+      }
+      return await task(current);
+    }, pathnames.map(buildCapturePathLockIdentity));
+  }
   async withTombstoneBlockedCaptureWriteLockAndHashes(task, identity, identityHashes) {
     return await this.getTombstoneBlockedCaptureIndex().withCaptureWriteLockAndHashes(task, identity, identityHashes);
   }
@@ -955,11 +1394,11 @@ var TombstoneBlockedCaptureIndexHost = class {
     this.invalidateAllMemoriesCache();
     this.invalidateKnowledgeIndexCache();
     this.markFactHashIndexNotAuthoritative();
-    if (filePath.includes(`${path3.sep}cold${path3.sep}`)) {
+    if (filePath.includes(`${path4.sep}cold${path4.sep}`)) {
       this.invalidateColdMemoriesCache();
     }
     await this.rebuildTombstoneBlockedCaptureAfterInvalidationForPath(filePath, ownedMarker);
-    if (filePath.includes(`${path3.sep}artifacts${path3.sep}`)) {
+    if (filePath.includes(`${path4.sep}artifacts${path4.sep}`)) {
       this.bumpArtifactWriteVersion();
     }
     const memoryDir = this.tombstoneBlockedCaptureIndexOptions().memoryDir;
@@ -1054,7 +1493,7 @@ var TombstoneBlockedCaptureIndexHost = class {
         bumpArchiveMutationForPath(memoryDir, true, current.path);
         markProjectedMemoryPathInvalid(memoryDir, current.frontmatter.id);
         this.invalidateAllMemoriesCache();
-        if (current.path.includes(`${path3.sep}cold${path3.sep}`)) {
+        if (current.path.includes(`${path4.sep}cold${path4.sep}`)) {
           this.invalidateColdMemoriesCache();
         }
         await this.rebuildTombstoneBlockedCaptureAfterInvalidation(rebuildMarker);
@@ -1132,7 +1571,7 @@ var TombstoneBlockedCaptureIndexHost = class {
   async writeTombstoneBlockedOfflineSyncFile(target, content) {
     const options = this.tombstoneBlockedCaptureIndexOptions();
     const after = options.parseMemory?.(target, content) ?? null;
-    await withRawEntityPageMutation(path3.dirname(options.stateDir), target, async () => {
+    await withRawEntityPageMutation(path4.dirname(options.stateDir), target, async () => {
       await this.runTombstoneBlockedOfflineSyncMutation(
         target,
         after,
@@ -1171,11 +1610,11 @@ var TombstoneBlockedCaptureIndexHost = class {
       return { after, chunks: replay };
     }
     const options = this.tombstoneBlockedCaptureIndexOptions();
-    const stagePath = path3.join(
+    const stagePath = path4.join(
       options.stateDir,
       "tombstone-blocked-capture",
       "offline-sync-staging",
-      `${randomUUID2()}.stage`
+      `${randomUUID3()}.stage`
     );
     const stagedChunks = (async function* () {
       for (const chunk of buffered) yield chunk;
@@ -1196,7 +1635,7 @@ var TombstoneBlockedCaptureIndexHost = class {
       );
       return await this.describeStagedOfflineSyncChunks(target, stagePath, parseMemory);
     } catch (err) {
-      await unlink2(stagePath).catch(() => {
+      await unlink3(stagePath).catch(() => {
       });
       throw err;
     }
@@ -1250,7 +1689,7 @@ var TombstoneBlockedCaptureIndexHost = class {
       encode("connector", connector),
       `content ${normalizedLength} `
     ].join(" ");
-    let identityHash = createHash2("sha256");
+    let identityHash = createHash3("sha256");
     let normalSigmaIdentityHash;
     identityHash.update(identityPrefix);
     const identityNormalizer = createExplicitContentNormalizer({
@@ -1296,7 +1735,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 = path3.dirname(this.tombstoneBlockedCaptureIndexOptions().stateDir);
+    const baseDir = path4.dirname(this.tombstoneBlockedCaptureIndexOptions().stateDir);
     try {
       await withRawEntityPageMutation(baseDir, target, async () => {
         await this.runTombstoneBlockedOfflineSyncMutation(
@@ -1308,7 +1747,7 @@ var TombstoneBlockedCaptureIndexHost = class {
         );
       });
     } finally {
-      if (prepared.stagePath !== void 0) await unlink2(prepared.stagePath).catch(() => {
+      if (prepared.stagePath !== void 0) await unlink3(prepared.stagePath).catch(() => {
       });
     }
   }
@@ -1328,7 +1767,7 @@ var TombstoneBlockedCaptureIndexHost = class {
    */
   async requestSyncReconcileIfMigrationPath(target) {
     const stateDir = this.tombstoneBlockedCaptureIndexOptions().stateDir;
-    if (!pathMayCarryEntityRefs(path3.dirname(stateDir), target)) return;
+    if (!pathMayCarryEntityRefs(path4.dirname(stateDir), target)) return;
     await requestEntityCanonicalIdReconcile(stateDir);
   }
   async deleteOfflineSyncFile(filePath, deletionMtimeMs) {
@@ -1338,7 +1777,7 @@ var TombstoneBlockedCaptureIndexHost = class {
   }
   async deleteTombstoneBlockedOfflineSyncFile(target, deletionMtimeMs) {
     const stateDir = this.tombstoneBlockedCaptureIndexOptions().stateDir;
-    await withRawEntityPageMutation(path3.dirname(stateDir), target, async () => {
+    await withRawEntityPageMutation(path4.dirname(stateDir), target, async () => {
       await this.runTombstoneBlockedOfflineSyncMutation(target, null, async () => {
         return await this.deleteManagedStorageFile(target, deletionMtimeMs);
       });
@@ -1365,6 +1804,8 @@ var TombstoneBlockedCaptureIndexHost = class {
 };
 
 export {
+  invalidationCommitFingerprint,
+  DeletionRevisionStore,
   isTombstoneBlockedCaptureWriteLockBusy,
   normalizeExplicitCaptureContent,
   buildExplicitCaptureDedupKey,
@@ -1374,4 +1815,4 @@ export {
   parseTombstoneBlockedOfflineSyncMemory,
   TombstoneBlockedCaptureIndexHost
 };
-//# sourceMappingURL=chunk-K4QS7LXU.js.map
+//# sourceMappingURL=chunk-K2UGPTYY.js.map