@remnic/core 9.69.103 → 9.69.104

package/src/embedding-index-storage.ts

@@ -14,6 +14,7 @@
  * caching or provider logic (that lives in `embedding-fallback.ts`).
  */
 import path from "node:path";
+import { randomUUID } from "node:crypto";
 import { constants as bufferConstants } from "node:buffer";
 import { lstat, mkdir, mkdtemp, realpath, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
 import { log } from "./logger.js";
@@ -165,6 +166,21 @@ function replacementBackupPath(shardDir: string): string {
   return path.join(path.dirname(shardDir), "embeddings.pre-replace.tmp");
 }
 
+/**
+ * Warm-cache generation marker (`<stateDir>/embeddings.generation`).
+ * Two-phase publication barrier: in-flight before a publication's first
+ * destructive write, fresh unique value after its last write. A stamp is
+ * therefore stable only for a completed generation — readers can never
+ * cache a stamp that stays stable while generation bytes change, and an
+ * in-flight stamp never repeats, so probes cached during a failed
+ * completion keep revalidating (PR #3176 codex P2). Plain fs like the
+ * status file.
+ */
+const GENERATION_MARKER_BASENAME = "embeddings.generation";
+
+/** Reserved in-flight marker value; never equals a completion marker. */
+const GENERATION_MARKER_IN_FLIGHT = "in-flight";
+
 /**
  * Stable FNV-1a shard assignment: an entry always hashes to the same shard,
  * so an update or removal never needs a manifest to find its file.
@@ -469,7 +485,9 @@ export class EmbeddingIndexFileStore {
    * the published position after an interrupted replacement. Returns true
    * when a rollback happened. Only fires in the actual rename gap
    * (published directory absent); callers must invalidate any cached index
-   * view when this returns true.
+   * view when this returns true. A successful rollback finalizes the
+   * generation marker strictly: a failed completion write fails the
+   * recovery instead of leaving every search reloading forever.
    */
   async recoverIfInterrupted(fence?: EmbeddingGenerationFence): Promise<boolean> {
     // Only the rename gap (published directory absent) is recoverable. When
@@ -492,6 +510,7 @@ export class EmbeddingIndexFileStore {
     // The rollback rename is destructive: reassert lock ownership first.
     await fence?.();
     await rename(backupPath, this.shardDir);
+    await this.writeGenerationMarker(randomUUID());
     log.warn(
       `embedding index: recovered interrupted replacement; former generation restored from ${backupPath}`,
     );
@@ -514,6 +533,97 @@ export class EmbeddingIndexFileStore {
     }
   }
 
+  /** Barrier first half: strict, so bytes can never change under a stable stamp. */
+  private async beginGenerationMarker(): Promise<void> {
+    await this.writeGenerationMarker(GENERATION_MARKER_IN_FLIGHT);
+  }
+
+  /**
+   * Barrier second half: written after the last content write. Best-effort:
+   * a failure leaves the in-flight marker, whose stamp identityStamp()
+   * never repeats, so cached probes revalidate on every search until a
+   * publication completes.
+   */
+  private async completeGenerationMarker(): Promise<void> {
+    await this.writeGenerationMarker(randomUUID()).catch((err) => {
+      log.warn(`embedding index: could not write generation completion marker: ${err instanceof Error ? err.message : String(err)}`);
+    });
+  }
+
+  private async writeGenerationMarker(value: string): Promise<void> {
+    await this.writeAtomicFile(
+      path.join(path.dirname(this.shardDir), GENERATION_MARKER_BASENAME),
+      value,
+      { bypassSecureIo: true },
+    );
+  }
+
+  /** Marker value, or null when absent/unreadable (pre-marker stores keep the stat stamp). */
+  private async readGenerationMarker(): Promise<string | null> {
+    try {
+      const raw = await readFile(
+        path.join(path.dirname(this.shardDir), GENERATION_MARKER_BASENAME),
+        "utf-8",
+      );
+      const value = raw.trim();
+      return value.length > 0 ? value : null;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Warm-cache stamp. A completed generation marker alone would freeze the
+   * stamp for a pre-marker writer in a rolling deployment (it publishes
+   * shard/index changes without updating the marker), so the marker is
+   * combined with the watched path's stat: the marker keeps consecutive
+   * publications distinct on coarse-tick filesystems, the stat keeps
+   * legacy writers visible. In-flight never repeats, forcing revalidation
+   * until a publication completes. Stores never published through this
+   * module keep the plain stat stamp — a directory stat alone aliases
+   * consecutive publications on coarse-tick filesystems and across inode
+   * reuse.
+   */
+  async identityStamp(): Promise<string> {
+    const layout = await this.detectLayout();
+    if (layout === "sharded") {
+      const info = await lstat(this.shardDir).catch((err) => {
+        // SAFETY: only the errno code is inspected; any other rejection shape rethrows uninterpreted.
+        if ((err as NodeJS.ErrnoException).code === "ENOENT") return null;
+        throw new EmbeddingIndexStorageError(
+          `cannot stat embedding index shard directory ${this.shardDir}: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      });
+      if (!info) return "rename-gap";
+      const marker = await this.readGenerationMarker();
+      // An in-flight marker must never produce a repeatable stamp: a probe
+      // that cached one (completion write failed) must revalidate on every
+      // later probe until a publication completes.
+      if (marker) {
+        if (marker === GENERATION_MARKER_IN_FLIGHT) return `gen:${randomUUID()}`;
+        return `gen:${marker}:${info.ino}:${info.mtimeMs}`;
+      }
+      return `shard:${info.ino}:${info.mtimeMs}`;
+    }
+    if (layout === "legacy") {
+      const info = await stat(this.indexPath).catch((err) => {
+        // SAFETY: only the errno code is inspected; any other rejection shape rethrows uninterpreted.
+        if ((err as NodeJS.ErrnoException).code === "ENOENT") return null;
+        throw new EmbeddingIndexStorageError(
+          `cannot stat embedding index file ${this.indexPath}: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      });
+      if (!info) return "rename-gap";
+      const marker = await this.readGenerationMarker();
+      if (marker) {
+        if (marker === GENERATION_MARKER_IN_FLIGHT) return `gen:${randomUUID()}`;
+        return `gen:${marker}:${info.ino}:${info.mtimeMs}`;
+      }
+      return `legacy:${info.ino}:${info.mtimeMs}`;
+    }
+    return "empty";
+  }
+
   /** Header identity of the authoritative generation, read leniently. */
   async identityFromDisk(): Promise<EmbeddingIndexIdentity | null> {
     const layout = await this.detectLayout();
@@ -751,6 +861,8 @@ export class EmbeddingIndexFileStore {
       // Serialization is done: reassert lock ownership immediately before
       // the destructive live-generation writes.
       await opts.fence?.();
+      await this.beginGenerationMarker();
+      await opts.fence?.();
       for (const payload of payloads) {
         await this.writeAtomicFile(
           path.join(this.shardDir, shardFileName(payload.shardIndex)),
@@ -764,6 +876,7 @@ export class EmbeddingIndexFileStore {
           await rm(path.join(this.shardDir, shardFileName(shardIndex)), { force: true });
         }
       }
+      await this.completeGenerationMarker();
       return;
     }
 
@@ -779,7 +892,10 @@ export class EmbeddingIndexFileStore {
       // Serialized above: reassert lock ownership immediately before the
       // destructive atomic write.
       await opts.fence?.();
+      await this.beginGenerationMarker();
+      await opts.fence?.();
       await this.writeAtomicFile(this.indexPath, whole);
+      await this.completeGenerationMarker();
       return;
     }
 
@@ -920,6 +1036,9 @@ export class EmbeddingIndexFileStore {
     // delay between the cleanup and the rename still allows a stale-break,
     // and publishing now would clobber the peer's write.
     await fence?.();
+    // Publication barrier: in-flight before the renames, final at commit.
+    await this.beginGenerationMarker();
+    await fence?.();
     let demoted = false;
     try {
       await stat(this.shardDir);
@@ -931,9 +1050,19 @@ export class EmbeddingIndexFileStore {
     try {
       await rename(stagingDir, this.shardDir);
     } catch (err) {
-      if (demoted) await rename(backupPath, this.shardDir).catch(() => undefined);
+      if (demoted) {
+        try {
+          await rename(backupPath, this.shardDir);
+          await this.completeGenerationMarker();
+        } catch (rollbackErr) {
+          log.warn(`embedding index: publication rollback did not restore the generation; marker stays in-flight: ${rollbackErr instanceof Error ? rollbackErr.message : String(rollbackErr)}`);
+        }
+      } else {
+        await this.completeGenerationMarker();
+      }
       throw err;
     }
+    await this.completeGenerationMarker();
     await rm(backupPath, { recursive: true, force: true }).catch((err) => {
       log.warn(`embedding index: could not remove replacement backup ${backupPath}: ${err}`);
     });

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");