@remnic/core 10.0.48 → 10.0.50

package/src/offline-sync.test.ts

@@ -1,6 +1,6 @@
 import assert from "node:assert/strict";
 import { createHash } from "node:crypto";
-import { chmod, mkdir, mkdtemp, readdir, readFile, rm, stat, utimes, writeFile } from "node:fs/promises";
+import { chmod, mkdir, mkdtemp, readdir, readFile, rm, stat, symlink, utimes, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import test from "node:test";
@@ -3714,33 +3714,37 @@ test("applyOfflineSyncSnapshot consumes readIncomingFile for records without inl
   }
 });
 
-test("buildOfflineSyncSnapshot skips a file that vanishes during the walk", async () => {
+test("buildOfflineSyncSnapshot fails closed when a file vanishes during digest", async () => {
   const root = await tempDir("remnic-offline-vanish");
   try {
     await write(root, "facts/keep.md", "keep");
     await write(root, "facts/gone.md", "gone");
-    const snapshot = await buildOfflineSyncSnapshot({
-      root,
-      sourceId: "local",
-      includeContent: false,
-      readFileDigest: async ({ path: relPath, filePath }) => {
-        if (relPath.endsWith("gone.md")) {
-          await rm(filePath);
-          throw Object.assign(new Error("ENOENT: vanished"), { code: "ENOENT" });
-        }
-        const content = await readFile(filePath);
-        return {
-          sha256: createHash("sha256").update(content).digest("hex"),
-          bytes: content.length,
-        };
-      },
-    });
-    assert.deepEqual(snapshot.files.map((file) => file.path), ["facts/keep.md"]);
+    await assert.rejects(
+      () => buildOfflineSyncSnapshot({
+        root,
+        sourceId: "local",
+        includeContent: false,
+        readFileDigest: async ({ path: relPath, filePath }) => {
+          if (relPath.endsWith("gone.md")) {
+            await rm(filePath);
+            throw Object.assign(new Error("ENOENT: vanished"), { code: "ENOENT" });
+          }
+          const content = await readFile(filePath);
+          return {
+            sha256: createHash("sha256").update(content).digest("hex"),
+            bytes: content.length,
+          };
+        },
+      }),
+      /census race|vanished during digest|retry the snapshot/i,
+    );
+    assert.equal(await readUtf8(root, "facts/keep.md"), "keep");
   } finally {
     await rm(root, { recursive: true, force: true });
   }
 });
 
+
 test("base snapshot fails when a base-known file vanishes before the fast-base stat", async () => {
   const root = await tempDir("remnic-offline-base-vanish");
   try {
@@ -3770,7 +3774,7 @@ test("base snapshot fails when a base-known file vanishes before the fast-base s
   }
 });
 
-test("base snapshot omits a brand-new file that vanishes during the walk", async () => {
+test("base snapshot omits a brand-new file that vanishes before the fast-base stat", async () => {
   const root = await tempDir("remnic-offline-new-vanish");
   try {
     await write(root, "facts/keep.md", "keep");
@@ -3798,6 +3802,7 @@ test("base snapshot omits a brand-new file that vanishes during the walk", async
   }
 });
 
+
 test("snapshot fails when an embedding generation member vanishes during the walk", async () => {
   const root = await tempDir("remnic-offline-shard-vanish");
   try {
@@ -3822,3 +3827,291 @@ test("snapshot fails when an embedding generation member vanishes during the wal
     await rm(root, { recursive: true, force: true });
   }
 });
+
+test("a transient snapshot omission must not emit a delete for a shared-base file", async () => {
+  const root = await tempDir("remnic-offline-uncertain-delete");
+  try {
+    await write(root, "facts/keep.md", "keep");
+    await write(root, "facts/race.md", "race-v1");
+    const base = await buildOfflineSyncSnapshot({
+      root,
+      sourceId: "local",
+      includeContent: false,
+    });
+    // Live census fail-closes on digest ENOENT. A stale/incomplete currentFiles
+    // list is still possible from an older client cache — that path must not
+    // emit a confirmed delete when the file is back on disk.
+    const incompleteFiles = base.files.filter((file) => file.path !== "facts/race.md");
+    assert.deepEqual(
+      incompleteFiles.map((file) => file.path),
+      ["facts/keep.md"],
+      "fixture: the race path is absent from the incomplete currentFiles view",
+    );
+    await write(root, "facts/race.md", "race-v1");
+    const changeset = await buildOfflineSyncChangesetFromSnapshot({
+      root,
+      sourceId: "local",
+      currentFiles: incompleteFiles,
+      baseFiles: base.files,
+    });
+    assert.equal(
+      changeset.changes.filter((change) => change.path === "facts/race.md" && change.type === "delete").length,
+      0,
+      "an unreadable/recreated path must not become a confirmed delete against the shared base",
+    );
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("apply must not overwrite a recreated local file omitted from the local census", async () => {
+  const root = await tempDir("remnic-offline-uncertain-overwrite");
+  try {
+    const recreated = "recreated local bytes";
+    const incoming = "incoming remote bytes";
+    await write(root, "facts/race.md", recreated);
+    const incomingSha = createHash("sha256").update(incoming).digest("hex");
+    // Local census omitted the recreated path (stale/racy currentFiles).
+    // Incoming is base-less, so the apply path would treat it as a pure create.
+    const result = await applyOfflineSyncSnapshot({
+      root,
+      currentFiles: [],
+      baseFiles: [],
+      snapshot: {
+        format: OFFLINE_SYNC_SNAPSHOT_FORMAT,
+        schemaVersion: 1,
+        createdAt: new Date().toISOString(),
+        sourceId: "remote",
+        includeTranscripts: false,
+        files: [{
+          path: "facts/race.md",
+          sha256: incomingSha,
+          bytes: Buffer.byteLength(incoming),
+          mtimeMs: 2,
+          contentBase64: Buffer.from(incoming).toString("base64"),
+        }],
+      },
+    });
+    assert.equal(
+      await readUtf8(root, "facts/race.md"),
+      recreated,
+      "recreated local content must survive when the local census omitted it",
+    );
+    assert.equal(result.upserted, 0, "must not publish over an uncertain local path");
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("changeset apply must not overwrite a recreated local file omitted by controlled digest census", async () => {
+  // Public applyOfflineSyncChangeset builds local currentFiles via
+  // buildOfflineSyncSnapshotForPaths when currentFiles is omitted. A controlled
+  // digest that recreates local bytes then throws ENOENT must fail closed at
+  // the shared census boundary — never export confirmed absence and overwrite.
+  const root = await tempDir("remnic-offline-changeset-uncertain-overwrite");
+  try {
+    const recreated = "recreated local bytes";
+    const incoming = "incoming remote bytes";
+    const incomingSha = createHash("sha256").update(incoming).digest("hex");
+    await write(root, "facts/race.md", recreated);
+
+    await assert.rejects(
+      () => applyOfflineSyncChangeset({
+        root,
+        // No currentFiles: exercise the public snapshotForPaths census path.
+        returnCurrentFiles: false,
+        writeConflictCopies: false,
+        readFileDigest: async ({ path: relPath, filePath }) => {
+          if (relPath === "facts/race.md") {
+            await writeFile(filePath, recreated);
+            throw Object.assign(new Error("ENOENT: vanished during census"), { code: "ENOENT" });
+          }
+          const content = await readFile(filePath);
+          return {
+            sha256: createHash("sha256").update(content).digest("hex"),
+            bytes: content.length,
+          };
+        },
+        changeset: {
+          format: "remnic.offline-sync.changeset.v1",
+          schemaVersion: 1,
+          createdAt: new Date().toISOString(),
+          sourceId: "remote",
+          includeTranscripts: false,
+          changes: [{
+            type: "upsert",
+            path: "facts/race.md",
+            file: {
+              path: "facts/race.md",
+              sha256: incomingSha,
+              bytes: Buffer.byteLength(incoming),
+              mtimeMs: 2,
+              contentBase64: Buffer.from(incoming).toString("base64"),
+            },
+          }],
+        },
+      }),
+      /census race|vanished during digest|retry the snapshot/i,
+    );
+
+    assert.equal(
+      await readUtf8(root, "facts/race.md"),
+      recreated,
+      "recreated local content must survive a fail-closed public changeset census race",
+    );
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("sender snapshot omission from digest race must not delete receiver shared-base file", async () => {
+  // Root premise: sender digest race must not export an apparently-complete
+  // snapshot that omits the path. Fail closed at the shared census boundary so
+  // no consumer can assign confirmed absence. Sender and receiver bytes stay.
+  const senderRoot = await tempDir("remnic-offline-sender-uncertain-omit");
+  const receiverRoot = await tempDir("remnic-offline-receiver-shared-base");
+  try {
+    const good = "unchanged good fact bytes";
+    const keep = "keep peer";
+    await write(senderRoot, "facts/race.md", good);
+    await write(senderRoot, "facts/keep.md", keep);
+    await write(receiverRoot, "facts/race.md", good);
+    await write(receiverRoot, "facts/keep.md", keep);
+
+    const sharedBase = await buildOfflineSyncSnapshot({
+      root: receiverRoot,
+      sourceId: "shared",
+      includeContent: false,
+    });
+    assert.ok(
+      sharedBase.files.some((file) => file.path === "facts/race.md"),
+      "fixture: shared base includes the good race path",
+    );
+
+    await assert.rejects(
+      () => buildOfflineSyncSnapshot({
+        root: senderRoot,
+        sourceId: "sender",
+        includeContent: false,
+        readFileDigest: async ({ path: relPath, filePath }) => {
+          if (relPath === "facts/race.md") {
+            await writeFile(filePath, good);
+            throw Object.assign(new Error("ENOENT: vanished during sender census"), { code: "ENOENT" });
+          }
+          const content = await readFile(filePath);
+          return {
+            sha256: createHash("sha256").update(content).digest("hex"),
+            bytes: content.length,
+          };
+        },
+      }),
+      /census race|vanished during digest|retry the snapshot/i,
+    );
+
+    assert.equal(await readUtf8(senderRoot, "facts/race.md"), good, "sender bytes preserved");
+    assert.equal(await readUtf8(receiverRoot, "facts/race.md"), good, "receiver bytes preserved without a false snapshot");
+    assert.equal(await readUtf8(receiverRoot, "facts/keep.md"), keep);
+  } finally {
+    await rm(senderRoot, { recursive: true, force: true });
+    await rm(receiverRoot, { recursive: true, force: true });
+  }
+});
+
+
+test("a file vanishing during the changeset upsert read keeps the retryable changed-while-building message", async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "remnic-offline-changeset-vanish-"));
+  try {
+    const rel = "facts/volatile.md";
+    const bytes = Buffer.from("volatile bytes\n");
+    await mkdir(path.join(root, "facts"), { recursive: true });
+    await writeFile(path.join(root, rel), bytes);
+    const currentFile = {
+      path: rel,
+      sha256: createHash("sha256").update(bytes).digest("hex"),
+      bytes: bytes.byteLength,
+      mtimeMs: 1,
+    };
+    await assert.rejects(
+      buildOfflineSyncChangesetFromSnapshot({
+        root,
+        sourceId: "laptop",
+        baseFiles: [],
+        currentFiles: [currentFile],
+        readFile: async () => {
+          await rm(path.join(root, rel), { force: true });
+          throw Object.assign(new Error("ENOENT: file vanished"), { code: "ENOENT" });
+        },
+      }),
+      (error: Error) => {
+        // The CLI retry loop matches this exact prefix to defer the path and rebuild the census.
+        assert.equal(error.message, `offline sync file changed while building changeset: ${rel}`);
+        return true;
+      },
+    );
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("a tracked file replaced by a symlink is a local delete, not a push-blocking error", async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "remnic-offline-symlink-replaced-"));
+  const outside = await mkdtemp(path.join(os.tmpdir(), "remnic-offline-symlink-target-"));
+  try {
+    const rel = "facts/tracked.md";
+    const bytes = Buffer.from("tracked bytes\n");
+    await mkdir(path.join(root, "facts"), { recursive: true });
+    await writeFile(path.join(outside, "target.md"), "outside\n");
+    await symlink(path.join(outside, "target.md"), path.join(root, rel));
+    const baseFile = {
+      path: rel,
+      sha256: createHash("sha256").update(bytes).digest("hex"),
+      bytes: bytes.byteLength,
+      mtimeMs: 1,
+    };
+    const changeset = await buildOfflineSyncChangesetFromSnapshot({
+      root,
+      sourceId: "laptop",
+      baseFiles: [baseFile],
+      currentFiles: [],
+    });
+    assert.deepEqual(
+      changeset.changes.map((change) => [change.type, change.path]),
+      [["delete", rel]],
+      "a symlink is not a regular local file: it reads as a delete, as before the census change",
+    );
+  } finally {
+    await rm(root, { recursive: true, force: true });
+    await rm(outside, { recursive: true, force: true });
+  }
+});
+
+test("a tracked file under a directory replaced by an in-root symlink is a local delete", async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "remnic-offline-symlink-parent-"));
+  try {
+    const rel = "facts/tracked.md";
+    const bytes = Buffer.from("tracked bytes\n");
+    await mkdir(path.join(root, "elsewhere"), { recursive: true });
+    await writeFile(path.join(root, "elsewhere", "tracked.md"), bytes);
+    // The census skips a symlinked directory, so facts/tracked.md is not in it.
+    await symlink(path.join(root, "elsewhere"), path.join(root, "facts"));
+    const baseFile = {
+      path: rel,
+      sha256: createHash("sha256").update(bytes).digest("hex"),
+      bytes: bytes.byteLength,
+      mtimeMs: 1,
+    };
+    const changeset = await buildOfflineSyncChangesetFromSnapshot({
+      root,
+      sourceId: "laptop",
+      baseFiles: [baseFile],
+      currentFiles: [],
+    });
+    assert.deepEqual(
+      changeset.changes.map((change) => [change.type, change.path]),
+      [["delete", rel]],
+      "a path reached only through a symlinked parent is absent, as the census sees it",
+    );
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});

package/src/offline-sync.ts

@@ -32,6 +32,7 @@ import { isMacOsReplicationJunkBasename } from "./utils/macos-replication-junk.j
 import {
   applyIncomingEmbeddingGenerations,
   assertEmbeddingGenerationStillIncluded,
+  advanceEmbeddingGenerationMarker,
   computeOmittedEmbeddingGenerationPaths,
   divergedEmbeddingGenerationDeferrals,
   embeddingGenerationMembership,
@@ -69,6 +70,10 @@ import {
   setSafeFileMtime,
   assertNonNegativeFinite,
   assertOfflineSyncMtimeMs,
+  offlineSyncRegularFilePresent,
+  OfflineSyncCensusRaceError,
+  censusRaceAsChangedWhileBuilding,
+  changedWhileBuildingChangesetError,
   OFFLINE_SYNC_FAST_BASE_MTIME_TOLERANCE_MS,
 } from "./offline-sync-file-io.js";
 import { CENSUS_MAX_MTIME_MS, isSha256Hex } from "./census-validation.js";
@@ -792,19 +797,29 @@ async function canReuseFastBaseFileStateFromDisk(
 
 async function readOfflineSyncFileRecord(
   options: OfflineSyncFileRecordOptions,
-): Promise<OfflineSyncFileRecord | null> {
+): Promise<OfflineSyncFileRecord> {
   try {
     return await readPresentOfflineSyncFileRecord(options);
   } catch (error) {
-    // A file removed between readdir and stat/hash is a race, not a corrupt corpus.
-    if (isNotFoundError(error)) return null;
+    // Caller already observed the path (readdir/lstat). Digest ENOENT is an
+    // ambiguous race: exporting a silent omission assigns confirmed absence to
+    // every consumer (full snapshot apply + changeset apply). Fail closed.
+    if (isNotFoundError(error)) {
+      if (embeddingGenerationMembership(options.relPath) !== null) {
+        throw new Error(
+          `offline sync embedding generation member vanished during snapshot walk: ${options.relPath}`,
+        );
+      }
+      throw new OfflineSyncCensusRaceError(options.relPath, error);
+    }
     throw error;
   }
 }
 
-// A vanished path may only be omitted when nothing can misread the gap:
-// embedding generations travel and replace as one unit (issue #3148), and a
-// base-known file omitted here would fabricate a delete in
+
+// Pre-stat vanish (readdir then lstat/stat ENOENT) may omit only when nothing
+// can misread the gap: embedding generations travel as one unit (issue #3148),
+// and a base-known file omitted here would fabricate a delete in
 // buildOfflineSyncChangesetFromSnapshot.
 function assertSnapshotVanishIsSafe(relPath: string, base: ReadonlyMap<string, unknown> | undefined): void {
   if (embeddingGenerationMembership(relPath) !== null) {
@@ -815,6 +830,7 @@ function assertSnapshotVanishIsSafe(relPath: string, base: ReadonlyMap<string, u
   }
 }
 
+
 async function readPresentOfflineSyncFileRecord(
   options: OfflineSyncFileRecordOptions,
 ): Promise<OfflineSyncFileRecord> {
@@ -922,7 +938,7 @@ export async function* iterateOfflineSyncSnapshotFileRecords(options: {
         path: relPosix,
         filePath: abs,
       })) continue;
-      const record = await readOfflineSyncFileRecord({
+      yield await readOfflineSyncFileRecord({
         root,
         relPath: relPosix,
         filePath: abs,
@@ -931,8 +947,7 @@ export async function* iterateOfflineSyncSnapshotFileRecords(options: {
         readFileDigest: options.readFileDigest,
         signal: options.signal,
       });
-      if (record) yield record;
-      else assertSnapshotVanishIsSafe(relPosix, undefined);
+
     }
   }
 
@@ -1093,8 +1108,7 @@ export async function buildOfflineSyncSnapshotFromBase(options: {
       try {
         st = await stat(abs);
       } catch (error) {
-        // Same race readOfflineSyncFileRecord tolerates, unless omitting the
-        // path could fabricate a delete or downgrade a generation.
+        // Pre-stat vanish after readdir: omit only when assertSnapshotVanishIsSafe allows.
         if (isNotFoundError(error)) {
           assertSnapshotVanishIsSafe(relPosix, base);
           continue;
@@ -1111,7 +1125,7 @@ export async function buildOfflineSyncSnapshotFromBase(options: {
         files.push(baseEntry);
         continue;
       }
-      const record = await readOfflineSyncFileRecord({
+      files.push(await readOfflineSyncFileRecord({
         root,
         relPath: relPosix,
         filePath: abs,
@@ -1119,9 +1133,7 @@ export async function buildOfflineSyncSnapshotFromBase(options: {
         readFile: options.readFile,
         readFileDigest: options.readFileDigest,
         signal: options.signal,
-      });
-      if (record) files.push(record);
-      else assertSnapshotVanishIsSafe(relPosix, base);
+      }));
     }
   }
 
@@ -1207,7 +1219,7 @@ export async function buildOfflineSyncSnapshotForPaths(options: {
     })) {
       throw new Error(`offline sync snapshot path is excluded: ${relPath}`);
     }
-    const record = await readOfflineSyncFileRecord({
+    files.push(await readOfflineSyncFileRecord({
       root,
       relPath,
       filePath,
@@ -1215,9 +1227,7 @@ export async function buildOfflineSyncSnapshotForPaths(options: {
       readFile: options.readFile,
       readFileDigest: options.readFileDigest,
       signal: options.signal,
-    });
-    if (record) files.push(record);
-    else assertSnapshotVanishIsSafe(relPath, undefined);
+    }));
   }
   throwIfOfflineSyncAborted(options.signal);
 
@@ -1413,6 +1423,11 @@ export async function buildOfflineSyncChangesetFromSnapshot(options: {
   excludeNodeLocalState?: boolean;
   readFile?: (target: OfflineSyncFileTarget) => Promise<Buffer>;
 }): Promise<OfflineSyncChangeset> {
+  const root = await prepareSafeArchiveRoot(
+    path.resolve(options.root),
+    "buildOfflineSyncChangesetFromSnapshot",
+    "root",
+  );
   const includeTranscripts = options.includeTranscripts !== false;
   const excludedPaths = new Set(
     (options.excludePaths ?? []).map((relPath) => normalizeRelativePath(relPath, "excludePaths[]")),
@@ -1452,10 +1467,10 @@ export async function buildOfflineSyncChangesetFromSnapshot(options: {
         now: options.now,
         userExcludeRegexps: options.userExcludeRegexps,
         readFile: options.readFile,
-      });
+      }).catch(censusRaceAsChangedWhileBuilding(relPath));
       const record = file.files[0];
       if (!record || typeof record.contentBase64 !== "string" || record.sha256 !== currentEntry.sha256) {
-        throw new Error(`offline sync file changed while building changeset: ${relPath}`);
+        throw changedWhileBuildingChangesetError(relPath);
       }
       changes.push({
         type: "upsert",
@@ -1466,6 +1481,8 @@ export async function buildOfflineSyncChangesetFromSnapshot(options: {
       continue;
     }
     if (!currentEntry && baseEntry) {
+      // Census miss is not confirmed delete — recheck disk (transient ENOENT / recreate).
+      if (await offlineSyncRegularFilePresent(root, relPath)) continue;
       const mtimeMs = deletionMtimeByPath?.get(relPath);
       changes.push({
         type: "delete",
@@ -1807,6 +1824,12 @@ export async function applyOfflineSyncSnapshot(options: {
         continue;
       }
       if (!currentEntry && !base) {
+        // Census miss with on-disk file: uncertain local presence, do not overwrite.
+        if (await offlineSyncRegularFilePresent(root, relPath)) {
+          pendingLocal += 1;
+          skipped += 1;
+          continue;
+        }
         await writeSafeFile(root, relPath, requiredBuffer(incomingBuffers, relPath), options.writeFile, incoming.mtimeMs);
         nextBase.set(relPath, toFileState(incoming));
         upserted += 1;
@@ -2466,7 +2489,9 @@ export async function applyOfflineSyncFileContentChunk(options: {
       };
     }
 
-    await writeSafeFileFromUpload(root, relPath, upload, options.readFile, options.writeFileChunks, mtimeMs);
+    await advanceEmbeddingGenerationMarker(root.abs, embeddingGenerationMembership(relPath), () =>
+      writeSafeFileFromUpload(root, relPath, upload, options.readFile, options.writeFileChunks, mtimeMs),
+    );
     return {
       ...baseResult,
       applied: true,

package/src/orchestrator-init.test.ts

@@ -1,5 +1,6 @@
 import assert from "node:assert/strict";
-import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import test from "node:test";
@@ -1547,3 +1548,50 @@ test("startupSearchSync composes its caller abort into the QMD probe", async ()
     await rm(memoryDir, { recursive: true, force: true, maxRetries: 3, retryDelay: 50 });
   }
 });
+
+// Both startup call sites must open read readiness without migration replay.
+for (const namespace of ["default", "shared"]) {
+  test(`startup defers entity migration for ${namespace} storage`, async () => {
+    const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-init-migration-defer-"));
+    const orchestrator = new Orchestrator(
+      parseConfig({
+        memoryDir,
+        workspaceDir: path.join(memoryDir, "workspace"),
+        qmdEnabled: false,
+        namespacesEnabled: namespace === "shared",
+        namespaceCatalogEnabled: false,
+        defaultNamespace: "default",
+        sharedNamespace: "shared",
+        namespacePolicies: [],
+        embeddingFallbackEnabled: false,
+        identityContinuityEnabled: false,
+        transcriptEnabled: false,
+        hourlySummariesEnabled: false,
+        compoundingEnabled: false,
+        knowledgeIndexEnabled: false,
+      }),
+    );
+    const storage = await orchestrator.getStorage(namespace);
+    const lockPath = path.join(storage.dir, "state", "entity-canonical-id-migration.lock");
+    const journalPath = path.join(storage.dir, "state", "entity-canonical-id-migration-v1.json");
+    try {
+      await mkdir(path.dirname(lockPath), { recursive: true });
+      await writeFile(lockPath, `${process.pid} init-migration-test ${new Date().toISOString()}\n`);
+      const outcome = await withTestDeadline(
+        orchestrator.initialize().then(() => "settled" as const, () => "rejected" as const),
+      );
+      assert.equal(outcome, "settled", "startup must succeed while the migration lock is held");
+      assert.equal(existsSync(lockPath), true);
+      assert.equal(existsSync(journalPath), false, "startup must not run the migration");
+      await rm(lockPath);
+      await storage.ensureDirectories();
+      // SAFETY: the journal is written by the migration under test and carries an optional boolean `complete`.
+      const state = JSON.parse(await readFile(journalPath, "utf8")) as { complete?: boolean };
+      assert.equal(state.complete, true, "default setup must still run migration");
+    } finally {
+      await rm(lockPath, { force: true });
+      await orchestrator.destroy();
+      await rm(memoryDir, { recursive: true, force: true, maxRetries: 3, retryDelay: 50 });
+    }
+  });
+}

package/src/orchestrator.ts

@@ -746,6 +746,7 @@ export class Orchestrator {
   private _dependencyPropagationDelivery: DependencyPropagationDelivery | undefined;
   private _dependencyPropagationRecovery: Promise<void> | null = null;
   private destroyed = false;
+  private acceptingEntityMigrationMaintenance = true;
 
   private get dependencyPropagationDelivery(): DependencyPropagationDelivery {
     if (this.destroyed) throw new Error("orchestrator has been destroyed");
@@ -967,6 +968,7 @@ export class Orchestrator {
    * commands should call it before returning to let Node exit naturally.
    */
   async destroy(): Promise<void> {
+    this.acceptingEntityMigrationMaintenance = false;
     this._orchestratorInitCoordinator?.retireStartupEpoch();
     this.abortDeferredInit();
     this.extractionQueueCoordinator.stopAccepting();
@@ -1499,14 +1501,6 @@ export class Orchestrator {
         (namespace) => this.namespaceSearchRouter.backendForNamespace(namespace),
         (msg) => log.debug(msg),
       );
-      const defaultNs = this.config.defaultNamespace;
-      this.storage.onMemoryWrite = (filePath) => this.prioritizedEmbedding?.enqueue(filePath, defaultNs);
-      this.storageRouter.onStorageCreated = (storage, namespace) => {
-        storage.onMemoryWrite = (filePath) => this.prioritizedEmbedding?.enqueue(filePath, namespace);
-      };
-      this.storageRouter.forEachCachedStorage((storage, namespace) => {
-        storage.onMemoryWrite = (filePath) => this.prioritizedEmbedding?.enqueue(filePath, namespace);
-      });
     }
     this.maintenanceScheduler = new MaintenanceScheduler({
       config,
@@ -1516,6 +1510,13 @@ export class Orchestrator {
       getStorage: () => this.storage, storageForNamespace: (namespace) => this.storageRouter.storageFor(namespace),
       onActivitySynced: (summary) => { if (!this.config.meetings.enabled) return; void this.getMeetingsService().then((s) => s.requestBuildForActivitySync(summary.ranAt, this.config.activity.timezone, summary.touchedDates)).catch((err) => log.warn(`meetings: activity tail-step build failed to schedule: ${err instanceof Error ? err.message : String(err)}`)); },
     });
+    const bindStorage = (storage: StorageManager, namespace: string) => {
+      storage.onEntityMigrationComplete = () => { if (this.acceptingEntityMigrationMaintenance) this.requestQmdMaintenance(); };
+      if (this.prioritizedEmbedding) storage.onMemoryWrite = (filePath) => this.prioritizedEmbedding?.enqueue(filePath, namespace);
+    };
+    bindStorage(this.storage, this.config.defaultNamespace);
+    this.storageRouter.onStorageCreated = bindStorage;
+    this.storageRouter.forEachCachedStorage(bindStorage);
     // Issue #1526: background extraction queue lives on its own coordinator.
     this.extractionQueueCoordinator = new ExtractionQueueCoordinator();