@remnic/core 9.69.102 → 9.69.104

package/src/memory-corpus-version.ts

@@ -1,5 +1,6 @@
 import { appendFileSync, mkdirSync } from "node:fs";
 import path from "node:path";
+import { entityMentionEpoch } from "./entity-mention-epoch.js";
 import { deleteInFlightReadsForDir } from "./in-flight-reads.js";
 import { invalidateDerivedAndGlobalForDir } from "./memory-cache.js";
 
@@ -17,10 +18,16 @@ export const MEMORY_CORPUS_VERSION_SENTINEL = ".memory-corpus-version.log";
  * — review approval, governance restore, migration. Appends one byte to the
  * on-disk sentinel so any process's version-keyed hot-memories cache rescans
  * on its next read (StorageManager.readSharedVersion reads the file size, so
- * the growth is observed immediately). Fail-open: a bump failure must never
- * crash the caller — a stale-cache window self-heals on the next real write.
+ * the growth is observed immediately). The same call moves the entity-mention
+ * epoch, unless the caller passes `{ indexedText: false }` for a metadata
+ * stamp that cannot change snippet text, entityRef, or origin. Fail-open: a
+ * bump failure must never crash the caller — a stale-cache window self-heals
+ * on the next real write.
  */
-export function bumpMemoryCorpusVersionForDir(memoryDir: string): void {
+export function bumpMemoryCorpusVersionForDir(
+  memoryDir: string,
+  options?: { indexedText?: boolean },
+): void {
   try {
     const stateDir = path.join(memoryDir, "state");
     mkdirSync(stateDir, { recursive: true });
@@ -28,6 +35,9 @@ export function bumpMemoryCorpusVersionForDir(memoryDir: string): void {
   } catch {
     /* fail-open: never let a cache-coherence bump crash the primary operation */
   }
+  if (options?.indexedText !== false && !entityMentionEpoch.suppressed()) {
+    entityMentionEpoch.bump(memoryDir);
+  }
   // Drop any in-flight readAllMemories scan for this dir (Cursor Medium, #1902):
   // after the sentinel advances, a concurrent read that missed the version-keyed
   // hot entry must not attach to a scan that began BEFORE this out-of-band write

package/src/offline-sync-exclude-globs.ts

@@ -67,12 +67,35 @@ export const DEFAULT_OFFLINE_SYNC_EXCLUDE_GLOBS: readonly string[] = [
   "**/namespaces/*/state/embeddings.pre-replace.tmp/**",
   "**/namespaces/*/state/embeddings.staging.tmp-*/**",
   "**/namespaces/*/state/embeddings.json.pre-migration.tmp-*",
+  // The warm-cache generation marker (PR #3176) is node-local coherence
+  // state: a synced copy — worse, a captured `in-flight` value — would make
+  // the receiving node's stamp probes unique forever and force a full index
+  // reload on every search. Exclude on both sides: never snapshotted, and
+  // an incoming (old or hostile) marker never overwrites or deletes the
+  // local one.
+  "**/state/embeddings.generation",
+  "**/namespaces/*/state/embeddings.generation",
 ];
 
 
 const DEFAULT_OFFLINE_SYNC_EXCLUDE_REGEXPS: readonly RegExp[] =
   DEFAULT_OFFLINE_SYNC_EXCLUDE_GLOBS.map((glob) => globToRegExp(glob));
 
+/**
+ * The warm-cache generation marker is the one default-excluded path that
+ * must ALSO be refused on apply (push-side default excludes like the live
+ * LCM sqlite are deliberately apply-accepted for first-sync bootstrapping).
+ * Node-local on both sides: never snapshotted, never overwritten by an
+ * incoming old or hostile copy.
+ */
+export function isEmbeddingGenerationMarkerPath(relPosix: string): boolean {
+  const normalized = relPosix.includes("\\") ? relPosix.replaceAll("\\", "/") : relPosix;
+  // Case-insensitive: on APFS/NTFS a differently cased path resolves to the
+  // same file, so `state/Embeddings.Generation` must be refused like the
+  // canonical spelling.
+  return /(?:^|\/)state\/embeddings\.generation$/i.test(normalized);
+}
+
 /**
  * Precompiled-once default-exclude check for the snapshot enumeration hot
  * path (Kilo review, PR #1793). Moved here from offline-sync.ts with the

package/src/offline-sync.test.ts

@@ -26,7 +26,15 @@ import {
   summarizeOfflineSyncPendingFiles,
 } from "./offline-sync.js";
 import { isEncryptedFile } from "./secure-store/secure-fs.js";
+import { isEmbeddingGenerationMarkerPath } from "./offline-sync-exclude-globs.js";
 import { StorageManager } from "./storage.js";
+import { parseConfig } from "./config.js";
+import { EmbeddingFallback } from "./embedding-fallback.js";
+import {
+  clearHostEmbeddingProvidersForTest,
+  registerHostEmbeddingProvider,
+} from "./host-embedding-provider.js";
+import type { EmbeddingIndexStoreIo } from "./embedding-index-storage.js";
 
 async function tempDir(name: string): Promise<string> {
   return mkdtemp(path.join(os.tmpdir(), `${name}-`));
@@ -551,6 +559,21 @@ test("offline sync push-side default excludes live LCM sqlite but apply-side sti
     assert.equal(await readUtf8(root, "state/lcm.sqlite-shm"), "live shm");
     assert.equal(await readUtf8(root, "state/lcm.sqlite-wal"), "live wal");
 
+    // The apply-side acceptance is real, not vacuous: a node with NO local
+    // sqlite must bootstrap it from the incoming snapshot.
+    const freshRoot = await tempDir("remnic-offline-lcm-sqlite-bootstrap");
+    try {
+      const bootstrap = await applyOfflineSyncSnapshot({
+        root: freshRoot,
+        snapshot: remoteSnapshot,
+        baseFiles: [],
+      });
+      assert.equal(await readUtf8(freshRoot, "state/lcm.sqlite"), "live db", "first sync bootstraps the LCM DB from the incoming snapshot");
+      assert.equal(bootstrap.upserted, 1);
+    } finally {
+      await rm(freshRoot, { recursive: true, force: true });
+    }
+
     // The push-side changeset excludes lcm.sqlite and friends so the
     // local node never pushes the live sqlite state up.
     const changeset = await buildOfflineSyncChangeset({
@@ -569,6 +592,308 @@ test("offline sync push-side default excludes live LCM sqlite but apply-side sti
   }
 });
 
+test("offline sync excludes the node-local embedding generation marker", async () => {
+  const root = await tempDir("remnic-offline-emb3176-marker");
+  try {
+    await write(root, "facts/a.md", "alpha");
+    await write(root, "state/embeddings.generation", "in-flight");
+    await write(root, "namespaces/team/state/embeddings.generation", "gen-team-uuid");
+
+    const snapshot = await buildOfflineSyncSnapshot({
+      root,
+      sourceId: "remote",
+      includeContent: true,
+    });
+    assert.deepEqual(snapshot.files.map((file) => file.path), ["facts/a.md"]);
+
+    const changeset = await buildOfflineSyncChangeset({
+      root,
+      sourceId: "laptop",
+      baseFiles: [{
+        path: "facts/a.md",
+        sha256: createHash("sha256").update("alpha").digest("hex"),
+        bytes: Buffer.byteLength("alpha"),
+        mtimeMs: 0,
+      }],
+    });
+    assert.deepEqual(changeset.changes.map((change) => change.path), []);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("offline sync apply never lets an incoming marker overwrite the local one", async () => {
+  const root = await tempDir("remnic-offline-emb3176-marker-apply");
+  try {
+    const localMarker = "0d9d2c11-5f6e-4a0e-8f1a-2b3c4d5e6f70";
+    await write(root, "facts/a.md", "alpha");
+    await write(root, "state/embeddings.generation", localMarker);
+
+    // A hostile or pre-exclusion remote snapshot carries the marker as an
+    // ordinary file; the pinned-`in-flight` payload would make every local
+    // stamp probe unique and force a full reload on every search.
+    const hostile = "in-flight";
+    const snapshot = {
+      format: OFFLINE_SYNC_SNAPSHOT_FORMAT,
+      schemaVersion: 1 as const,
+      createdAt: new Date().toISOString(),
+      sourceId: "remote",
+      includeTranscripts: true,
+      files: [
+        {
+          path: "facts/b.md",
+          sha256: createHash("sha256").update("beta").digest("hex"),
+          bytes: Buffer.byteLength("beta"),
+          mtimeMs: 0,
+          contentBase64: Buffer.from("beta").toString("base64"),
+        },
+        {
+          path: "state/embeddings.generation",
+          sha256: createHash("sha256").update(hostile).digest("hex"),
+          bytes: Buffer.byteLength(hostile),
+          mtimeMs: 0,
+          contentBase64: Buffer.from(hostile).toString("base64"),
+        },
+      ],
+    };
+    const result = await applyOfflineSyncSnapshot({ root, snapshot, baseFiles: [] });
+
+    assert.equal(await readUtf8(root, "state/embeddings.generation"), localMarker, "the local marker is node-local: an incoming marker must never overwrite it");
+    assert.equal(await readUtf8(root, "facts/b.md"), "beta", "unrelated incoming files still apply");
+    assert.equal(result.deleted, 0);
+    assert.deepEqual(result.conflicts, [], "an incoming marker must be skipped node-local, not turned into a conflict");
+
+    // A stale base entry for the marker plus its absence from the incoming
+    // snapshot is NOT a delete instruction either.
+    const staleBase = [{
+      path: "state/embeddings.generation",
+      sha256: createHash("sha256").update("stale").digest("hex"),
+      bytes: Buffer.byteLength("stale"),
+      mtimeMs: 0,
+    }];
+    const deletionProbe = await applyOfflineSyncSnapshot({
+      root,
+      snapshot: {
+        ...snapshot,
+        files: snapshot.files.filter((file) => file.path !== "state/embeddings.generation"),
+      },
+      baseFiles: staleBase,
+    });
+    assert.equal(await exists(root, "state/embeddings.generation"), true);
+    assert.equal(await readUtf8(root, "state/embeddings.generation"), localMarker);
+    assert.equal(deletionProbe.deleted, 0);
+    assert.deepEqual(deletionProbe.conflicts, [], "a marker absence is node-local, never a delete instruction or conflict");
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("offline sync apply refuses differently cased marker paths on case-insensitive filesystems", async () => {
+  const root = await tempDir("remnic-offline-emb3176-marker-case");
+  try {
+    const localMarker = "0d9d2c11-5f6e-4a0e-8f1a-2b3c4d5e6f70";
+    await write(root, "facts/a.md", "alpha");
+    await write(root, "state/embeddings.generation", localMarker);
+
+    assert.equal(isEmbeddingGenerationMarkerPath("state/embeddings.generation"), true);
+    assert.equal(isEmbeddingGenerationMarkerPath("state/Embeddings.Generation"), true, "APFS/NTFS resolve this to the same file");
+    assert.equal(isEmbeddingGenerationMarkerPath("State/Embeddings.Generation"), true);
+    assert.equal(isEmbeddingGenerationMarkerPath("state/embeddings.json"), false);
+
+    const hostile = "in-flight";
+    const markerEntry = (relPath: string) => ({
+      path: relPath,
+      sha256: createHash("sha256").update(hostile).digest("hex"),
+      bytes: Buffer.byteLength(hostile),
+      mtimeMs: 0,
+      contentBase64: Buffer.from(hostile).toString("base64"),
+    });
+    const result = await applyOfflineSyncSnapshot({
+      root,
+      snapshot: {
+        format: OFFLINE_SYNC_SNAPSHOT_FORMAT,
+        schemaVersion: 1 as const,
+        createdAt: new Date().toISOString(),
+        sourceId: "remote",
+        includeTranscripts: true,
+        files: [
+          {
+            path: "facts/b.md",
+            sha256: createHash("sha256").update("beta").digest("hex"),
+            bytes: Buffer.byteLength("beta"),
+            mtimeMs: 0,
+            contentBase64: Buffer.from("beta").toString("base64"),
+          },
+          markerEntry("state/Embeddings.Generation"),
+        ],
+      },
+      baseFiles: [],
+    });
+    assert.equal(await readUtf8(root, "state/embeddings.generation"), localMarker, "the canonical local marker survives a cased incoming copy");
+    assert.equal(await exists(root, "state/Embeddings.Generation"), false, "a cased marker path is refused node-local, never written");
+    assert.equal(await exists(root, "facts/b.md"), true, "unrelated incoming files still apply");
+    assert.deepEqual(result.conflicts, []);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("a hostile incoming marker leaves the local warm embedding cache untouched", async () => {
+  const root = await tempDir("remnic-offline-emb3176-marker-warm");
+  try {
+    const vectorFor = (text: string): number[] => {
+      const vec = [0, 0, 0, 0];
+      for (let i = 0; i < text.length; i++) vec[i % 4] += text.charCodeAt(i) % 13;
+      return vec;
+    };
+    const unregister = registerHostEmbeddingProvider(root, {
+      id: "host-model-a",
+      model: "host-model-a",
+      embed: async (text: string) => vectorFor(text),
+    });
+    let reads = 0;
+    const countingIo: EmbeddingIndexStoreIo = {
+      readUtf8: async (filePath) => {
+        reads += 1;
+        return readFile(filePath, "utf-8");
+      },
+      writeUtf8: async (filePath, contents) => {
+        await mkdir(path.dirname(filePath), { recursive: true });
+        await writeFile(filePath, contents, "utf-8");
+      },
+    };
+    const fallback = new EmbeddingFallback(
+      parseConfig({
+        memoryDir: root,
+        embeddingFallbackEnabled: true,
+        embeddingFallbackProvider: "openai",
+        openaiApiKey: false,
+      }),
+      countingIo,
+    );
+    try {
+      await fallback.indexFile("mem-a", "parent fact about database indexes", "facts/a.md");
+      assert.equal((await fallback.search("parent fact about database indexes", 5))[0]?.id, "mem-a");
+      const readsBeforeApply = reads;
+
+      const hostile = "in-flight";
+      await applyOfflineSyncSnapshot({
+        root,
+        snapshot: {
+          format: OFFLINE_SYNC_SNAPSHOT_FORMAT,
+          schemaVersion: 1 as const,
+          createdAt: new Date().toISOString(),
+          sourceId: "remote",
+          includeTranscripts: true,
+          files: [{
+            path: "state/embeddings.generation",
+            sha256: createHash("sha256").update(hostile).digest("hex"),
+            bytes: Buffer.byteLength(hostile),
+            mtimeMs: 0,
+            contentBase64: Buffer.from(hostile).toString("base64"),
+          }],
+        },
+        baseFiles: [],
+      });
+
+      const warm = await fallback.search("parent fact about database indexes", 5);
+      assert.equal(warm[0]?.id, "mem-a", "the local generation is still served");
+      assert.equal(
+        reads,
+        readsBeforeApply,
+        "the local marker survived the apply: the warm cache keeps its stable stamp and performs no index reads",
+      );
+    } finally {
+      unregister();
+    }
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("offline sync changeset apply refuses marker upserts and deletes, continues ordinary changes", async () => {
+  const root = await tempDir("remnic-offline-emb3176-marker-changeset");
+  try {
+    const localMarker = "7f6c1e64-9b2a-4c7d-8e0f-1a2b3c4d5e6f";
+    const hostile = "in-flight";
+    const sha = (value: string) => createHash("sha256").update(value).digest("hex");
+    await write(root, "facts/a.md", "alpha");
+    await write(root, "state/embeddings.generation", localMarker);
+
+    const result = await applyOfflineSyncChangeset({
+      root,
+      currentFiles: [
+        { path: "facts/a.md", sha256: sha("alpha"), bytes: 5, mtimeMs: 0 },
+        { path: "state/embeddings.generation", sha256: sha(localMarker), bytes: localMarker.length, mtimeMs: 0 },
+      ],
+      changeset: {
+        format: "remnic.offline-sync.changeset.v1",
+        schemaVersion: 1,
+        createdAt: new Date().toISOString(),
+        sourceId: "peer",
+        includeTranscripts: false,
+        changes: [
+          { type: "upsert", path: "facts/b.md", file: { path: "facts/b.md", sha256: sha("beta"), bytes: 4, mtimeMs: 0, contentBase64: Buffer.from("beta").toString("base64") } },
+          { type: "upsert", path: "state/embeddings.generation", file: { path: "state/embeddings.generation", sha256: sha(hostile), bytes: hostile.length, mtimeMs: 0, contentBase64: Buffer.from(hostile).toString("base64") } },
+        ],
+      } as never,
+    });
+    const deletionResult = await applyOfflineSyncChangeset({
+      root,
+      currentFiles: [
+        { path: "facts/a.md", sha256: sha("alpha"), bytes: 5, mtimeMs: 0 },
+        { path: "facts/b.md", sha256: sha("beta"), bytes: 4, mtimeMs: 0 },
+        { path: "state/embeddings.generation", sha256: sha(localMarker), bytes: localMarker.length, mtimeMs: 0 },
+      ],
+      changeset: {
+        format: "remnic.offline-sync.changeset.v1",
+        schemaVersion: 1,
+        createdAt: new Date().toISOString(),
+        sourceId: "peer",
+        includeTranscripts: false,
+        changes: [
+          { type: "delete", path: "facts/a.md", baseSha256: sha("alpha"), mtimeMs: 0 },
+          { type: "delete", path: "state/embeddings.generation", baseSha256: sha(localMarker), mtimeMs: 0 },
+        ],
+      } as never,
+    });
+
+    assert.equal(await readUtf8(root, "state/embeddings.generation"), localMarker, "node-local marker: neither an incoming upsert nor a delete may touch it");
+    assert.equal(await exists(root, "state/embeddings.generation"), true);
+    assert.equal(await readUtf8(root, "facts/b.md"), "beta", "ordinary upserts continue");
+    assert.equal(await exists(root, "facts/a.md"), false, "ordinary deletes continue");
+    assert.equal(deletionResult.appliedDeletes, 1);
+    assert.deepEqual(result.conflicts, [], "a marker upsert must be skipped node-local, not turned into a conflict");
+    assert.deepEqual(deletionResult.conflicts, [], "a marker delete must be skipped node-local, not turned into a conflict");
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("offline sync file content chunks refuse the generation marker", async () => {
+  const root = await tempDir("remnic-offline-emb3176-marker-chunk");
+  try {
+    await write(root, "state/embeddings.generation", "local-uuid");
+    const content = Buffer.from("in-flight");
+    await assert.rejects(
+      () =>
+        applyOfflineSyncFileContentChunk({
+          root,
+          sourceId: "peer",
+          path: "state/embeddings.generation",
+          sha256: createHash("sha256").update(content).digest("hex"),
+          bytes: content.length,
+          mtimeMs: 0,
+          content,
+        }),
+      /node-local/,
+    );
+    assert.equal(await readUtf8(root, "state/embeddings.generation"), "local-uuid", "the chunked hostile payload never lands");
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
 test("offline sync includes durable runtime state and excludes only transient sync temp files", async () => {
   const root = await tempDir("remnic-offline-runtime-state");
   try {

package/src/offline-sync.ts

@@ -25,7 +25,7 @@ import {
 } from "./transfer/fs-utils.js";
 import { parseFlexibleIsoTimestamp } from "./utils/iso-timestamp.js";
 import { EmbeddingIndexStorageError } from "./embedding-index-storage.js";
-import { matchesOfflineSyncDefaultExclude } from "./offline-sync-exclude-globs.js";
+import { isEmbeddingGenerationMarkerPath, matchesOfflineSyncDefaultExclude } from "./offline-sync-exclude-globs.js";
 import {
   applyIncomingEmbeddingGenerations,
   assertEmbeddingGenerationStillIncluded,
@@ -1696,6 +1696,15 @@ export async function applyOfflineSyncSnapshot(options: {
     }
 
     if (incoming) {
+      // The generation marker (PR #3176) is node-local on BOTH sides: an
+      // incoming copy — old or hostile — never overwrites the local file
+      // and never enters the base set. Other default excludes stay
+      // apply-accepted (#1786: first-sync LCM sqlite bootstrapping).
+      if (isEmbeddingGenerationMarkerPath(relPath)) {
+        nextBase.delete(relPath);
+        skipped += 1;
+        continue;
+      }
       if (currentEntry?.sha256 === incoming.sha256) {
         if (await setSafeFileMtime(root, relPath, incoming.mtimeMs)) {
           nextBase.set(relPath, toFileState(incoming));
@@ -1933,6 +1942,10 @@ export async function applyOfflineSyncChangeset(options: {
   for (const change of changeset.changes) {
     if (generationRouting.conflictedPaths.has(change.path)) continue;
     if (generationRouting.transactionHandled.has(change.path)) continue;
+    if (isEmbeddingGenerationMarkerPath(change.path)) {
+      skipped += 1;
+      continue;
+    }
     const currentEntry = currentMap.get(change.path);
     if (change.type === "upsert") {
       if (currentEntry?.sha256 === change.file.sha256) {
@@ -2225,6 +2238,9 @@ export async function applyOfflineSyncFileContentChunk(options: {
   if (shouldExcludeRelPath(relPath, includeTranscripts)) {
     throw new Error(`offline sync file content path is excluded: ${relPath}`);
   }
+  if (isEmbeddingGenerationMarkerPath(relPath)) {
+    throw new Error(`offline sync file content path is node-local: ${relPath}`);
+  }
   const sha256 = assertSha256(options.sha256, "sha256");
   const bytes = assertNonNegativeInteger(options.bytes, "bytes");
   const mtimeMs = assertOfflineSyncMtimeMs(options.mtimeMs, "mtimeMs");

package/src/preferences/preference-drift.ts

@@ -558,8 +558,10 @@ export async function runPreferenceDriftScan(
     // shared corpus version out of band — otherwise hot recall caches keep
     // serving pre-stamp frontmatter and the damping stage never sees the new
     // `driftState` (§25/§31).
-    bumpMemoryCorpusVersionForDir(storage.dir);
-    if (storage.dir !== deps.memoryDir) bumpMemoryCorpusVersionForDir(deps.memoryDir);
+    bumpMemoryCorpusVersionForDir(storage.dir, { indexedText: false });
+    if (storage.dir !== deps.memoryDir) {
+      bumpMemoryCorpusVersionForDir(deps.memoryDir, { indexedText: false });
+    }
   }
   try {
     await writeJsonFileAtomic(driftMarkerPath(deps.memoryDir), {
@@ -640,7 +642,7 @@ export async function resolvePreferenceDrift(
       { lastCorroborated: nowIso, driftState: undefined, updated: nowIso },
       { at: now, actor: DRIFT_ACTOR, reasonCode: "drift_kept", ruleVersion: DRIFT_RULE_VERSION },
     );
-    bumpMemoryCorpusVersionForDir(storage.dir);
+    bumpMemoryCorpusVersionForDir(storage.dir, { indexedText: false });
     touched();
     return { affectedIds: [preferenceId], message: `Preference ${preferenceId} confirmed still current` };
   }

package/src/procedural/library-maintenance.ts

@@ -526,9 +526,10 @@ export async function runProcedureLibraryMaintenance(options: {
   report.appliedCount = report.applied.length;
 
   if (writes > 0) {
-    // Out-of-band corpus bump + marker so hot caches and the stats surface
-    // observe the pass (§25/§31 — direct writes must not leave stale views).
-    bumpMemoryCorpusVersionForDir(options.memoryDir);
+    // Corpus bump so hot caches observe the pass. Archive already moved the
+    // mention epoch when it removed the live file. Merge-supersede and repair
+    // stamps are metadata-only, so this bump must not move the epoch.
+    bumpMemoryCorpusVersionForDir(options.memoryDir, { indexedText: false });
   }
   try {
     await writeJsonFileAtomic(maintenanceMarkerPath(options.memoryDir), {

package/src/semantic-rule-promotion.ts

@@ -610,7 +610,7 @@ export async function promoteSemanticRuleFromMemory(options: {
   };
 
   return withPromotionLock(options.memoryDir, ruleKey, async (lock) => {
-    storage.invalidateAllMemoriesCacheForDir();
+    storage.invalidateAllMemoriesCacheForDir({ indexedText: false });
     const existingRule = (await storage.readAllMemories()).find(
       (memory) =>
         memory.frontmatter.category === "rule" &&

package/src/storage/entity-mention-frontmatter-hold.ts

@@ -0,0 +1,44 @@
+import { entityMentionEpoch } from "../entity-mention-epoch.js";
+import type { MemoryFile, MemoryFrontmatter } from "../types.js";
+import {
+  buildCapturePathLockIdentity,
+  buildExplicitCaptureDedupKey,
+} from "./tombstone-blocked-capture-mutation.js";
+
+type MentionHoldStorage = {
+  withTombstoneBlockedCaptureWriteLock<T>(
+    task: () => Promise<T>,
+    identity?: readonly string[],
+  ): Promise<T>;
+  readMemoryByPath(pathname: string): Promise<MemoryFile | null>;
+};
+
+/**
+ * Metadata frontmatter writes may suppress the mention epoch only when the
+ * file still has the same body, entityRef, and origin while the path lock is
+ * held. The write runs in that same lock so a concurrent body or entityRef
+ * change cannot be overwritten under suppression.
+ */
+export async function holdMentionNeutralFrontmatter<T>(
+  storage: MentionHoldStorage,
+  memory: MemoryFile,
+  updated: MemoryFrontmatter,
+  write: () => Promise<T>,
+): Promise<T | undefined> {
+  const identities = [
+    buildCapturePathLockIdentity(memory.path),
+    buildExplicitCaptureDedupKey(memory.content, memory.frontmatter.category, memory.frontmatter.sourceConnector),
+    buildExplicitCaptureDedupKey(memory.content, updated.category, updated.sourceConnector),
+  ];
+  return storage.withTombstoneBlockedCaptureWriteLock(async () => {
+    const persisted = await storage.readMemoryByPath(memory.path);
+    if (
+      !persisted ||
+      persisted.content !== memory.content ||
+      !entityMentionEpoch.neutral(persisted.frontmatter, updated)
+    ) {
+      return undefined;
+    }
+    return write();
+  }, identities);
+}