@remnic/core 10.0.49 → 10.0.51

package/src/offline-sync.ts

@@ -70,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";
@@ -793,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) {
@@ -816,6 +830,7 @@ function assertSnapshotVanishIsSafe(relPath: string, base: ReadonlyMap<string, u
   }
 }
 
+
 async function readPresentOfflineSyncFileRecord(
   options: OfflineSyncFileRecordOptions,
 ): Promise<OfflineSyncFileRecord> {
@@ -923,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,
@@ -932,8 +947,7 @@ export async function* iterateOfflineSyncSnapshotFileRecords(options: {
         readFileDigest: options.readFileDigest,
         signal: options.signal,
       });
-      if (record) yield record;
-      else assertSnapshotVanishIsSafe(relPosix, undefined);
+
     }
   }
 
@@ -1094,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;
@@ -1112,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,
@@ -1120,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);
+      }));
     }
   }
 
@@ -1208,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,
@@ -1216,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);
 
@@ -1414,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[]")),
@@ -1453,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",
@@ -1467,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",
@@ -1808,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;

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

package/src/storage/entity-canonical-id-migration-adapter.ts

@@ -1,3 +1,4 @@
+import { log } from "../logger.js";
 import type { EntityFile, MemoryFile } from "../types.js";
 import {
   getFingerprint,
@@ -30,6 +31,7 @@ export interface EntityCanonicalIdMigrationHost {
   invalidateColdMemoriesCache(): void;
   bumpMemoryStatusVersion(): void;
   getEntityMutationVersion(): number;
+  onEntityMigrationComplete?: () => void;
 }
 
 export async function runLegacyEntityCanonicalIdMigration(
@@ -40,6 +42,9 @@ export async function runLegacyEntityCanonicalIdMigration(
 ): Promise<string | undefined> {
   const readMigrationFingerprint = () =>
     getFingerprint(host.baseDir, host.entitiesDir, () => String(host.getEntityMutationVersion()));
+  // The migration bumps the status version only after a pass that rewrote
+  // references; a no-op replay must not ask search maintenance to run.
+  let rewroteReferences = false;
   const completionFingerprint = await migrateLegacyEntityCanonicalIds({
     stateDir: host.stateDir,
     entitiesDir: host.entitiesDir,
@@ -65,9 +70,19 @@ export async function runLegacyEntityCanonicalIdMigration(
     invalidateKnowledgeIndexCache: host.invalidateKnowledgeIndexCache.bind(host),
     invalidateAllMemoriesCache: host.invalidateAllMemoriesCache.bind(host),
     invalidateColdMemoriesCache: host.invalidateColdMemoriesCache.bind(host),
-    bumpMemoryStatusVersion: host.bumpMemoryStatusVersion.bind(host),
+    bumpMemoryStatusVersion: () => {
+      rewroteReferences = true;
+      host.bumpMemoryStatusVersion();
+    },
     readMigrationFingerprint,
   } satisfies EntityCanonicalIdMigrationDependencies);
+  if (completionFingerprint !== undefined && rewroteReferences) {
+    try {
+      host.onEntityMigrationComplete?.();
+    } catch {
+      log.warn("entity migration: search maintenance scheduling failed");
+    }
+  }
   // An undefined completion fingerprint is a deliberate signal (issue #2213):
   // a reconcile marker landed while the run scanned, and recomputing the
   // fingerprint here would seal that pending request into the runner's

package/src/storage/entity-canonical-id-migration.ts

@@ -46,7 +46,8 @@ const ENTITY_MAPPING_RESCAN_MAX_PASSES = 3;
 const EntityCanonicalIdMigrationStateSchema = z.object({
   version: z.literal(ENTITY_CANONICAL_ID_MIGRATION_VERSION),
   complete: z.boolean(),
-  mappings: z.record(z.string().min(1)),
+  mappings: z.record(z.string(), z.string().min(1)),
+  completionFingerprint: z.string().optional(),
   /**
    * Pairs the migration refused to resolve, PARKED rather than dropped.
    * Deleting the record would strand the collision: once an operator removes
@@ -54,7 +55,7 @@ const EntityCanonicalIdMigrationStateSchema = z.object({
    * still naming the legacy id would never be rewritten. Optional so a journal
    * written by an older build still parses.
    */
-  blocked: z.record(z.string().min(1)).optional(),
+  blocked: z.record(z.string(), z.string().min(1)).optional(),
 });
 
 type EntityCanonicalIdMigrationState = z.infer<typeof EntityCanonicalIdMigrationStateSchema>;
@@ -370,6 +371,13 @@ async function assertEntityContentUnchanged(
   }
 }
 
+/**
+ * Fail-closed entity-entry validation for the startup path: refuses a
+ * symlinked or non-directory entities root and any symlinked entry, without
+ * taking the migration lock. Exported so `ensureDirectories()` can run it
+ * before deferring the migration (#3139) — the same check
+ * `migrateLegacyEntityCanonicalIds` performs under the lock.
+ */
 export async function readSafeEntityEntries(entitiesDir: string): Promise<string[]> {
   const rootStat = await lstat(entitiesDir);
   if (rootStat.isSymbolicLink() || !rootStat.isDirectory()) {
@@ -887,14 +895,11 @@ export async function migrateLegacyEntityCanonicalIds(
           if (!isErrnoCode(error, "ENOENT")) throw error;
         }
       }
-      let state = await readState(deps);
-      if (!state) {
-        state = {
-          version: ENTITY_CANONICAL_ID_MIGRATION_VERSION,
-          complete: false,
-          mappings: {},
-        };
-      }
+      let state: EntityCanonicalIdMigrationState = await readState(deps) ?? {
+        version: ENTITY_CANONICAL_ID_MIGRATION_VERSION,
+        complete: false,
+        mappings: {},
+      };
       const blocked: BlockedEntityPairs = new Map();
       const scanNotes: EntityScanNotes = { junk: new Set(), malformed: new Set() };
       // Parks for pairs whose files are GONE, tracked separately from
@@ -951,6 +956,10 @@ export async function migrateLegacyEntityCanonicalIds(
         // fingerprint could SEAL a marker the check never saw.
         const completionFingerprint = await deps.readMigrationFingerprint?.();
         if (await fileExists(reconcileMarkerPath)) return undefined;
+        if (completionFingerprint !== undefined && state.completionFingerprint !== completionFingerprint) {
+          state = { ...state, complete: true, completionFingerprint };
+          await publishState(deps, state);
+        }
         return completionFingerprint;
       };
       /**

package/src/storage/entity-canonical-id-references.ts

@@ -16,6 +16,7 @@ import { statSync } from "node:fs";
  *   reconciliation pass instead ({@link requestEntityCanonicalIdReconcile}).
  */
 import path from "node:path";
+import { z } from "zod";
 import {
   closeSync,
   constants,
@@ -112,6 +113,29 @@ function readJournalFileNoFollow(statePath: string): JournalRead {
   }
 }
 
+/** The journal fields completion attestation needs; extra journal fields are ignored. */
+const CompletedJournalAttestationSchema = z.object({
+  version: z.literal(1),
+  complete: z.literal(true),
+  completionFingerprint: z.string(),
+});
+
+/** Skip compatibility scans only when journal completion attests to the live inputs. */
+export async function entityCanonicalIdMigrationCompleted(
+  stateDir: string,
+  readFingerprint: () => Promise<string>,
+): Promise<boolean> {
+  const result = readJournalFileNoFollow(path.join(stateDir, ENTITY_CANONICAL_ID_MIGRATION_FILE));
+  if (result.kind !== "ok") return false;
+  try {
+    const parsed = CompletedJournalAttestationSchema.safeParse(JSON.parse(result.raw));
+    if (!parsed.success) return false;
+    return parsed.data.completionFingerprint === await readFingerprint();
+  } catch {
+    return false;
+  }
+}
+
 export function loadHistoricalEntityCanonicalIds(stateDir: string): Readonly<Record<string, string>> {
   const result = readJournalFileNoFollow(path.join(stateDir, ENTITY_CANONICAL_ID_MIGRATION_FILE));
   if (result.kind !== "ok") return {};

package/src/storage/entity-migration-completion-cache.nofollow.test.ts

@@ -0,0 +1,223 @@
+/**
+ * Regression: amortized completion must refuse a symlinked entities root
+ * before getFingerprint → fingerprintEntityEntries readdir.
+ *
+ * inputSig already labels the root "L", but isCompleted still runs the full
+ * fingerprint (external tree walk) before any isTrustedEntitiesRoot-style
+ * guard. A planted complete journal makes that path reachable after a
+ * missing-id ENOENT.
+ *
+ * Instrumentation (deterministic): spawn a plain child (not nested --test —
+ * node skips recursive test runs) with --experimental-test-module-mocks that
+ * wraps node:fs/promises.readdir via mock.module, dynamic-imports the real
+ * EntityMigrationCompletionCache, and records every readdir whose realpath is
+ * the external canary (or whose path is the entities symlink). Assert
+ * externalCount === 0 — not merely completed === false. chmod/EACCES is not
+ * used (false-green on this host).
+ *
+ * Dynamic import in the probe is intentional: mock.module must install before
+ * the cache module loads fs.promises (module-loading boundary).
+ *
+ * Temp roots only. Expected today: RED (externalCount >= 1).
+ * After root nofollow guard: externalCount === 0 and completed === false.
+ */
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import {
+  lstat,
+  mkdir,
+  mkdtemp,
+  readFile,
+  realpath,
+  rm,
+  symlink,
+  writeFile,
+} from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+
+import { ENTITY_CANONICAL_ID_MIGRATION_FILE } from "./entity-canonical-id-references.js";
+
+function findRepoRoot(startDir: string): string {
+  let dir = startDir;
+  for (;;) {
+    if (existsSync(path.join(dir, "packages", "remnic-core", "package.json"))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) {
+      throw new Error(`remnic repo root not found from ${startDir}`);
+    }
+    dir = parent;
+  }
+}
+
+const REPO_ROOT = findRepoRoot(path.dirname(fileURLToPath(import.meta.url)));
+const CACHE_MODULE = path.join(
+  REPO_ROOT,
+  "packages",
+  "remnic-core",
+  "src",
+  "storage",
+  "entity-migration-completion-cache.ts",
+);
+
+type ProbeResult = {
+  completed: boolean | null;
+  err: string | null;
+  externalCount: number;
+  seen: Array<{ raw: string; real: string }>;
+  canaryReal: string;
+};
+
+test("isCompleted must not readdir through a symlinked entities root", async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "remnic-entities-root-nofollow-"));
+  const memoryDir = path.join(root, "memory");
+  const canaryDir = path.join(root, "canary-external");
+  const entitiesDir = path.join(memoryDir, "entities");
+  const stateDir = path.join(memoryDir, "state");
+  const probeFile = path.join(root, "completion-cache-nofollow.probe.mts");
+  const resultFile = path.join(root, "probe-result.json");
+
+  try {
+    await mkdir(stateDir, { recursive: true });
+    await mkdir(path.join(memoryDir, "config"), { recursive: true });
+    await mkdir(canaryDir, { recursive: true });
+    await writeFile(path.join(canaryDir, "outside-only.md"), "canary external entity body\n");
+
+    await symlink(canaryDir, entitiesDir);
+    assert.equal(
+      (await lstat(entitiesDir)).isSymbolicLink(),
+      true,
+      "fixture: entities/ must be a symlink to the external canary directory",
+    );
+    const canaryReal = await realpath(canaryDir);
+
+    // Regular complete journal — completionFingerprint compare invokes getFingerprint.
+    await writeFile(
+      path.join(stateDir, ENTITY_CANONICAL_ID_MIGRATION_FILE),
+      JSON.stringify({
+        version: 1,
+        complete: true,
+        mappings: {},
+        completionFingerprint: "planted-complete-journal-for-symlink-root-regression",
+      }),
+    );
+
+    // Plain probe script (no nested --test: parent already runs under the test
+    // runner, and node skips recursive test-file execution).
+    // Dynamic import loads cache after mock.module wraps readdir.
+    await writeFile(
+      probeFile,
+      `import { mock } from "node:test";
+import path from "node:path";
+import { writeFile } from "node:fs/promises";
+import { readdir as realReaddir, realpath } from "node:fs/promises";
+
+const canaryReal = ${JSON.stringify(canaryReal)};
+const memoryDir = ${JSON.stringify(memoryDir)};
+const entitiesDir = ${JSON.stringify(entitiesDir)};
+const cacheModule = ${JSON.stringify(CACHE_MODULE)};
+const resultFile = ${JSON.stringify(resultFile)};
+const seen = [];
+
+const fsp = await import("node:fs/promises");
+mock.module("node:fs/promises", {
+  namedExports: {
+    ...fsp,
+    readdir: async (p, ...a) => {
+      const raw = path.resolve(String(p));
+      let real = raw;
+      try { real = await realpath(raw); } catch { /* keep raw */ }
+      seen.push({ raw, real });
+      return realReaddir(p, ...a);
+    },
+  },
+});
+
+// Dynamic import: mock.module must wrap fs.promises before the cache loads it.
+const { EntityMigrationCompletionCache } = await import(cacheModule);
+const cache = new EntityMigrationCompletionCache();
+let completed = null;
+let err = null;
+try {
+  completed = await cache.isCompleted({
+    baseDir: memoryDir,
+    entitiesDir,
+    getEntityMutationVersion: () => 0,
+  });
+} catch (e) {
+  err = e && typeof e === "object" && "code" in e ? String(e.code) : String(e);
+}
+const entitiesResolved = path.resolve(entitiesDir);
+const external = seen.filter((s) => s.real === canaryReal || s.raw === entitiesResolved);
+const payload = {
+  completed,
+  err,
+  seen,
+  externalCount: external.length,
+  canaryReal,
+};
+await writeFile(resultFile, JSON.stringify(payload), "utf8");
+console.log(JSON.stringify(payload));
+mock.reset();
+`,
+    );
+
+    const probe = spawnSync(
+      process.execPath,
+      [
+        "--experimental-test-module-mocks",
+        "--import",
+        "tsx",
+        "--conditions=remnic-source",
+        probeFile,
+      ],
+      {
+        encoding: "utf8",
+        cwd: REPO_ROOT,
+        env: {
+          ...process.env,
+          NODE_PATH: path.join(REPO_ROOT, "node_modules"),
+        },
+        timeout: 60_000,
+      },
+    );
+
+    if (probe.error) {
+      assert.fail(`probe failed to start: ${probe.error.message}`);
+    }
+
+    let result: ProbeResult;
+    try {
+      // SAFETY: the child probe in this file writes `resultFile` as a ProbeResult before exiting.
+      result = JSON.parse(await readFile(resultFile, "utf8")) as ProbeResult;
+    } catch {
+      assert.fail(
+        [
+          "probe did not write result file",
+          `status=${String(probe.status)} signal=${String(probe.signal)}`,
+          `stdout:\n${probe.stdout ?? ""}`,
+          `stderr:\n${probe.stderr ?? ""}`,
+        ].join("\n"),
+      );
+      return;
+    }
+
+    assert.equal(
+      result.externalCount,
+      0,
+      [
+        "isCompleted must not readdir a symlinked entities root (external canary).",
+        `externalCount=${result.externalCount} canaryReal=${result.canaryReal}`,
+        `seen=${JSON.stringify(result.seen)}`,
+        result.err ? `isCompleted err=${result.err}` : `completed=${String(result.completed)}`,
+      ].join(" "),
+    );
+    assert.equal(result.err, null, "untrusted root must fail closed without throwing through external IO");
+    assert.equal(result.completed, false, "untrusted entities root must not report migration complete");
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});