@remnic/core 10.0.28 → 10.0.30

package/src/orchestration/orchestrator-init.ts

@@ -114,6 +114,7 @@ export class OrchestratorInitCoordinator {
   private startupEpochAbort:
     | { epoch: number; controller: AbortController }
     | undefined;
+  private readonly startupStorageWrites = new Set<Promise<void>>();
 
   constructor(
     private readonly deps: OrchestratorInitDeps,
@@ -127,6 +128,25 @@ export class OrchestratorInitCoordinator {
     this.activeStartupEpoch = null;
   }
 
+  private async initializeStorage(storage: StorageManager): Promise<void> {
+    const write = storage.ensureDirectories({ waitForEntityMigration: false });
+    this.startupStorageWrites.add(write);
+    try {
+      await write;
+    } finally {
+      this.startupStorageWrites.delete(write);
+    }
+  }
+
+  async drainEntityMigrations(): Promise<void> {
+    await Promise.allSettled([...this.startupStorageWrites]);
+    const drains = [this.deps.storage.drainEntityCanonicalIdMigration()];
+    this.deps.storageRouter.forEachCachedStorage((storage) => {
+      drains.push(storage.drainEntityCanonicalIdMigration());
+    });
+    await Promise.all(drains);
+  }
+
   private beginStartupEpoch(): number {
     this.startupEpochAbort?.controller.abort();
     this.startupEpochAbort = undefined;
@@ -305,7 +325,8 @@ export class OrchestratorInitCoordinator {
         logger: (message) => log.info(message),
       });
       await this.deps.storage.loadAliases();
-      await this.deps.storage.ensureDirectories();
+      if (exitIfStale()) return;
+      await this.initializeStorage(this.deps.storage);
       await Promise.all(
         this.deps.config.externalWikis.map((wiki) =>
           assertExternalWikiRootOutsideMemoryDirCanonical(
@@ -323,7 +344,8 @@ export class OrchestratorInitCoordinator {
         for (const ns of namespaces) {
           const sm = await this.deps.storageRouter.storageFor(ns);
           await sm.loadAliases().catch(() => undefined);
-          await sm.ensureDirectories();
+          if (exitIfStale()) return;
+          await this.initializeStorage(sm);
         }
         // Explicitly seed the catalog with all configured namespaces at startup
         // (round 6, cursor Medium — NBLlR). The storageFor loop above fires the
@@ -564,7 +586,8 @@ export class OrchestratorInitCoordinator {
         .catch((err) => {
           log.error(`deferred initialization failed (non-fatal): ${err}`);
         })
-        .finally(() => {
+        .finally(async () => {
+          await this.drainEntityMigrations();
           settleOwnDeferredReady();
         });
     } catch (err) {

package/src/orchestrator.ts

@@ -969,6 +969,7 @@ export class Orchestrator {
     this._orchestratorInitCoordinator?.retireStartupEpoch();
     this.abortDeferredInit();
     this.extractionQueueCoordinator.stopAccepting();
+    await this._orchestratorInitCoordinator?.drainEntityMigrations();
     if (this.wearablesAutoSyncHandle) {
       await this.wearablesAutoSyncHandle.stop();
       this.wearablesAutoSyncHandle = null;

package/src/secure-store/entity-file-read.ts

@@ -0,0 +1,55 @@
+import { constants } from "node:fs";
+import { lstat, open, readFile, realpath } from "node:fs/promises";
+import path from "node:path";
+import { assertPathInsideRoot } from "../utils/path-containment.js";
+
+export async function readStoreFileBuffer(filePath: string, memoryDir: string): Promise<Buffer> {
+  const root = path.resolve(memoryDir);
+  const entities = path.join(root, "entities");
+  const target = path.resolve(filePath);
+  const relative = path.relative(entities, target);
+  if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    return readFile(filePath);
+  }
+  const handle = await open(target, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
+  try {
+    for (let parent = path.dirname(target); ; parent = path.dirname(parent)) {
+      const info = await lstat(parent);
+      if (info.isSymbolicLink() || !info.isDirectory()) {
+        throw new Error(`Refusing unsafe entity directory: ${parent}.`);
+      }
+      if (parent === root) break;
+    }
+    const [opened, entry, realRoot, realEntities, realTarget] = await Promise.all([
+      handle.stat(), lstat(target), realpath(root), realpath(entities), realpath(target),
+    ]);
+    if (!opened.isFile() || entry.isSymbolicLink() || !entry.isFile()
+      || opened.dev !== entry.dev || opened.ino !== entry.ino
+      || realEntities !== path.join(realRoot, "entities")) {
+      throw new Error(`Refusing unsafe entity file: ${filePath}.`);
+    }
+    assertPathInsideRoot(realEntities, realTarget, filePath);
+    return await handle.readFile();
+  } finally {
+    await handle.close();
+  }
+}
+
+
+/**
+ * Atomic-replacement-tolerant variant: entity writes ship as temp-file +
+ * rename, so an open/lstat identity mismatch during a concurrent write is an
+ * ordinary race, not tampering. Retry a bounded number of times with fresh
+ * containment checks before surfacing the mismatch as unsafe.
+ */
+export async function readStoreFileBufferTolerant(filePath: string, memoryDir: string, attempts = 3): Promise<Buffer> {
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      return await readStoreFileBuffer(filePath, memoryDir);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      const identityRace = /unsafe entity (?:file|directory)/.test(message);
+      if (!identityRace || attempt >= attempts - 1) throw err;
+    }
+  }
+}

package/src/secure-store/secure-fs.ts

@@ -61,6 +61,7 @@ import {
 } from "./cipher.js";
 import { RECALL_FALLBACK_DIRS } from "../utils/category-dir.js";
 import { isErrnoCode } from "../utils/errno.js";
+import { readStoreFileBufferTolerant as readStoreFileBuffer } from "./entity-file-read.js";
 
 // ---------------------------------------------------------------------------
 // Error classes
@@ -291,7 +292,7 @@ export async function readMaybeEncryptedFileBuffer(
   memoryDir?: string,
   opts?: { aadFilePath?: string }
 ): Promise<Buffer> {
-  const buf = await readFile(filePath);
+  const buf = memoryDir ? await readStoreFileBuffer(filePath, memoryDir) : await readFile(filePath);
   if (!isEncryptedFile(buf)) {
     // Plain file — legacy or unencrypted store.
     return buf;

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

@@ -10,6 +10,38 @@ export class EntityCanonicalIdMigrationRunner {
     private readonly readFingerprint: () => Promise<string> = async () => "static",
   ) {}
 
+  /**
+   * First half of deferred startup: when waiting, ensure the migration runs;
+   * when deferring, pre-read the entity entries the store serves instead and
+   * let the migration start later (finishBegin detaches it).
+   */
+  public async begin(wait: boolean, entitiesDir: string): Promise<void> {
+    if (wait) {
+      await this.ensure();
+      return;
+    }
+    const { readSafeEntityEntries } = await import("./entity-canonical-id-migration.js");
+    await readSafeEntityEntries(entitiesDir);
+  }
+
+  /**
+   * Second half: return the directory-initialized barrier when waiting, or
+   * detach it with a warning when the caller deferred the migration.
+   */
+  public finishBegin(wait: boolean): Promise<void> {
+    const barrier = this.markDirectoriesInitialized();
+    if (wait) return barrier;
+    // Thrown rejections are Error-or-primitive; the message extractor
+    // handles both without asserting a shape.
+    const describeDeferredFailure = (failure: Error | string): string =>
+      failure instanceof Error ? failure.message : failure;
+    void barrier.catch(describeDeferredFailureAndWarn);
+    function describeDeferredFailureAndWarn(failure: Error | string): void {
+      console.warn(`entity canonical-id migration deferred at startup failed: ${describeDeferredFailure(failure)}`);
+    }
+    return Promise.resolve();
+  }
+
   public async markDirectoriesInitialized(): Promise<void> {
     this.directoriesInitialized = true;
     await this.ensure();
@@ -32,6 +64,10 @@ export class EntityCanonicalIdMigrationRunner {
     return this.ensure();
   }
 
+  public async drain(): Promise<void> {
+    while (this.inFlight) await this.inFlight.catch(() => undefined);
+  }
+
   private async runOrReuse(): Promise<void> {
     let fingerprintAtStart = await this.readFingerprint();
     if (this.migrationComplete && fingerprintAtStart === this.completedFingerprint) return;

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

@@ -370,7 +370,7 @@ async function assertEntityContentUnchanged(
   }
 }
 
-async function readSafeEntityEntries(entitiesDir: string): Promise<string[]> {
+export async function readSafeEntityEntries(entitiesDir: string): Promise<string[]> {
   const rootStat = await lstat(entitiesDir);
   if (rootStat.isSymbolicLink() || !rootStat.isDirectory()) {
     throw new Error("Refusing entity canonical-id migration through a symlinked or non-directory entities root.");

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

@@ -1,3 +1,4 @@
+import { statSync } from "node:fs";
 /**
  * Write-boundary surface of the entity canonical-id migration (issue #2213).
  *
@@ -60,6 +61,13 @@ function parseJournalMappings(raw: string): Readonly<Record<string, string>> {
   return cleaned;
 }
 
+/** Whether the journal says its migration completed. Throws like the mapping parser. */
+function parseJournalComplete(raw: string): boolean {
+  // SAFETY: JSON.parse output is unknown; the shape is validated on access.
+  const parsed = JSON.parse(raw) as { complete?: unknown };
+  return parsed !== null && parsed.complete === true;
+}
+
 type JournalRead =
   | { kind: "ok"; raw: string; key: string }
   | { kind: "missing" }
@@ -183,13 +191,57 @@ export async function appendCanonicalizedTombstone(
  * identity, so the next lookup retries instead of caching an empty table
  * under a valid key.
  */
+
+/** Journal lookup result: mapping table plus its completion flag. */
+export type HistoricalEntityIdsEntry = {
+  mappings: Readonly<Record<string, string>>;
+  complete: boolean;
+};
+
+
+
+/**
+ * Memoized journal-completion view keyed on the journal file's stat identity.
+ * entityList consults completion once per listed entity; without this each
+ * consult re-opens and re-reads the journal (quadratic I/O on large corpora).
+ */
+export function memoizedJournalCompletion(
+  cache: HistoricalEntityCanonicalIdCache,
+  stateDir: () => string,
+): () => boolean {
+  let memo: { key: string; complete: boolean } | undefined;
+  return (): boolean => {
+    let key = "missing";
+    try {
+      const journalPath = path.join(stateDir(), ENTITY_CANONICAL_ID_MIGRATION_FILE);
+      const j = statSync(journalPath);
+      key = `${j.dev}:${j.ino}:${j.mtimeMs}:${j.ctimeMs}:${j.size}`;
+    } catch {
+      key = "missing";
+    }
+    if (memo && memo.key === key) return memo.complete;
+    const entry = cache.getEntry(stateDir());
+    memo = { key, complete: entry.complete };
+    return memo.complete;
+  };
+}
+
 export class HistoricalEntityCanonicalIdCache {
   private mappings: Readonly<Record<string, string>> = {};
+  private complete = false;
   private key: string | null = null;
   private stateDir: string | null = null;
 
   get(stateDir: string): Readonly<Record<string, string>> {
-    const lastKnown = this.stateDir === stateDir ? this.mappings : {};
+    return this.getEntry(stateDir).mappings;
+  }
+
+
+  /** Table plus the journal's completion flag, cached under one identity. */
+  getEntry(stateDir: string): HistoricalEntityIdsEntry {
+    const lastKnownMappings = this.stateDir === stateDir ? this.mappings : {};
+    const lastKnownComplete = this.stateDir === stateDir ? this.complete : false;
+    const lastKnown: HistoricalEntityIdsEntry = { mappings: lastKnownMappings, complete: lastKnownComplete };
     const result = readJournalFileNoFollow(path.join(stateDir, ENTITY_CANONICAL_ID_MIGRATION_FILE));
     if (result.kind === "refused") {
       // Symlinked/non-regular journal: never follow it, never adopt its
@@ -208,9 +260,11 @@ export class HistoricalEntityCanonicalIdCache {
     const key = result.kind === "missing" ? "missing" : result.key;
     if (key !== this.key || stateDir !== this.stateDir) {
       let table: Readonly<Record<string, string>> = {};
+      let complete = false;
       if (result.kind === "ok") {
         try {
           table = parseJournalMappings(result.raw);
+          complete = parseJournalComplete(result.raw);
         } catch {
           // Parse failed under a VALID identity: do not commit the key —
           // the next lookup retries instead of pinning an empty table.
@@ -218,10 +272,11 @@ export class HistoricalEntityCanonicalIdCache {
         }
       }
       this.mappings = table;
+      this.complete = complete;
       this.key = key;
       this.stateDir = stateDir;
     }
-    return this.mappings;
+    return { mappings: this.mappings, complete: this.complete };
   }
 }
 

package/src/storage/entity-store.ts

@@ -23,7 +23,7 @@ import {
 } from "../utils/macos-replication-junk.js";
 import { getCachedEntities, setCachedEntities } from "../memory-cache.js";
 import type { VersionTrigger } from "../page-versioning.js";
-import { SecureStoreLockedError } from "../secure-store/secure-fs.js";
+import { SecureStoreDecryptError, SecureStoreLockedError } from "../secure-store/secure-fs.js";
 import type {
   EntityActivityEntry,
   EntityFile,
@@ -67,6 +67,8 @@ export interface EntityStoreDeps {
   readonly entitiesDir: string;
   readonly entitySchemas: PluginConfig["entitySchemas"] | undefined;
   currentHistoricalIds(): Readonly<Record<string, string>>;
+  /** True when the entity canonical-id journal says migration completed. */
+  entityCanonicalMigrationComplete(): boolean;
   findMatchingEntity(proposedName: string, type: string): Promise<string | null>;
   getEntityCacheSecureStoreKey(): string;
   getEntityMutationVersion(): number;
@@ -373,18 +375,56 @@ export class EntityStore {
     return normalized;
   }
 
-  async readEntity(name: string): Promise<string> {
-    const filePath = this.deps.resolveEntityFilePath(name);
-    if (filePath === null) {
-      return "";
-    }
+  private async readEntityFileResolvingRename(firstPath: string, entityId: string) {
     try {
-      return await this.deps.readStorageSecureFile(filePath);
+      return { id: entityId, content: await this.deps.readStorageSecureFile(firstPath) };
     } catch (err) {
       if (err instanceof SecureStoreLockedError) throw err;
+      // ENOENT: renamed away (retry below). ELOOP: planted symlink — skip.
+      if (isErrnoCode(err, "ELOOP")) return null;
       if (!isErrnoCode(err, "ENOENT")) throw err;
+    }
+    const historicalIds = this.deps.currentHistoricalIds();
+    const canonical = resolveHistoricalEntityCanonicalId(entityId, historicalIds);
+    const candidates = new Set([canonical]);
+    for (const legacy of Object.keys(historicalIds)) {
+      if (resolveHistoricalEntityCanonicalId(legacy, historicalIds) === canonical) candidates.add(legacy);
+    }
+    candidates.delete(entityId);
+    for (const candidate of candidates) {
+      try {
+        return { id: candidate, content: await this.deps.readStorageSecureFile(
+          path.join(this.deps.entitiesDir, `${candidate}.md`),
+        ) };
+      } catch (err) {
+        if (err instanceof SecureStoreLockedError) throw err;
+        // ENOENT/ELOOP: gone or a planted symlink — try the next candidate.
+        if (isErrnoCode(err, "ENOENT") || isErrnoCode(err, "ELOOP")) continue;
+        throw err;
+      }
+    }
+    return null;
+  }
+
+  async readEntity(name: string): Promise<string> {
+    const filePath = this.deps.resolveEntityFilePath(name);
+    if (filePath === null) {
       return "";
     }
+    // Batch reads retry renames unconditionally (a listed file that ENOENTs
+    // is definitionally a race), but a DIRECT lookup of a legacy id must stop
+    // resolving once the journal says migration completed and its file is gone.
+    if (this.deps.entityCanonicalMigrationComplete()) {
+      try {
+        return await this.deps.readStorageSecureFile(filePath);
+      } catch (err) {
+        if (err instanceof SecureStoreLockedError) throw err;
+        // ENOENT: gone. ELOOP: a planted symlink the open refused to follow.
+        if (isErrnoCode(err, "ENOENT") || isErrnoCode(err, "ELOOP")) return "";
+        throw err;
+      }
+    }
+    return (await this.readEntityFileResolvingRename(filePath, name))?.content ?? "";
   }
 
   /**
@@ -434,6 +474,16 @@ export class EntityStore {
    * Symlinks, FIFOs, and devices are skipped before any read. The entities
    * root is refused separately, before the directory is listed.
    */
+  private async isMissingEntry(file: string): Promise<boolean> {
+    try {
+      await lstat(path.join(this.deps.entitiesDir, file));
+      return false;
+    } catch (err) {
+      if (isErrnoCode(err, "ENOENT")) return true;
+      throw err;
+    }
+  }
+
   private async isContainedRegularEntityFile(file: string): Promise<boolean> {
     const filePath = path.join(this.deps.entitiesDir, file);
     let entryStat;
@@ -491,23 +541,54 @@ export class EntityStore {
       const names: string[] = [];
       const batchSize = 100;
       for (let i = 0; i < mdFiles.length; i += batchSize) {
+        // Journal table snapshot once per call (per-entry reads are quadratic).
+        const historicalIds = this.deps.currentHistoricalIds();
+        const snapshotIds = new Set(mdFiles.map((file) => file.slice(0, -3)));
+        const journalComplete = this.deps.entityCanonicalMigrationComplete();
+        const resolveCanonical = (entityId: string): string => {
+          const canonical = resolveHistoricalEntityCanonicalId(entityId, historicalIds);
+          if (canonical === entityId) return entityId;
+          // Completed journal: the on-disk filename is authoritative; a
+          // late legacy file stays under its own readable name.
+          if (journalComplete) return entityId;
+          // Both claimants coexisting (copy-before-unlink) keep both names.
+          if (snapshotIds.has(canonical)) return entityId;
+          return canonical;
+        };
         const resolved = await Promise.all(mdFiles.slice(i, i + batchSize).map(async (file) => {
+          const entityId = file.slice(0, -3);
           try {
-            if (!(await this.isIndexableEntityMarkdown(file))) return null;
+            // Report the canonical id for every indexable file so legacy
+            // names surface as their canonical identity from the start.
+            if (await this.isIndexableEntityMarkdown(file)) {
+              return resolveCanonical(entityId);
+            }
           } catch (err) {
-            if (err instanceof SecureStoreLockedError) throw err;
-            return null;
+            // Lock and decrypt errors abort the listing; anything else
+            // (EACCES) fails only this entry — one unhealthy file must not
+            // empty it.
+            if (err instanceof SecureStoreLockedError || err instanceof SecureStoreDecryptError) throw err;
+          }
+          // Vanished listed entry: resolve through the journal (rename
+          // race); lstat failures stay within this entry.
+          try {
+            if (await this.isMissingEntry(file)) {
+              const canonical = resolveHistoricalEntityCanonicalId(entityId, this.deps.currentHistoricalIds());
+              if (canonical !== entityId) return canonical;
+            }
+          } catch (err) {
+            if (err instanceof SecureStoreLockedError || err instanceof SecureStoreDecryptError) throw err;
           }
-          return file.slice(0, -3);
+          return null;
         }));
-        for (const name of resolved) {
-          if (name) names.push(name);
-        }
+        names.push(...resolved.filter((name): name is string => name !== null));
       }
-      names.sort();
-      return names;
+      // The copy-before-unlink migration window can snapshot both the legacy
+      // and canonical names; the legacy fallback then resolves to the same
+      // canonical id. Deduplicate so the total stays correct.
+      return [...new Set(names)].sort();
     } catch (err) {
-      if (err instanceof SecureStoreLockedError) throw err;
+      if (err instanceof SecureStoreLockedError || err instanceof SecureStoreDecryptError) throw err;
       return [];
     }
   }
@@ -636,10 +717,22 @@ export class EntityStore {
     if (cached) return cached;
 
     try {
-      const entries = await this.readEntityDirectoryNames();
+      // A symlinked/replaced entities root has no readable entries (merged
+      // #3207 semantics): resolve empty rather than following it. Within a
+      // trusted root, readdir directly so planted entries reach the secure
+      // read instead of being swallowed by the listing guards.
+      if (!(await this.isTrustedEntitiesRoot())) return [];
+      const listed = await readdir(this.deps.entitiesDir);
+      const { kept: entries, ignored } = withoutMacOsReplicationJunk(listed, (name) => name);
+      warnIgnoredMacOsReplicationJunk(this.deps.entitiesDir, ignored, (message) => {
+        log.warn(`entity load ${message}`);
+      });
       const mdFiles = entries.filter((e) => e.endsWith(".md"));
       if (mdFiles.length === 0) return [];
 
+      const historicalIds = this.deps.currentHistoricalIds();
+      const seen = new Map<string, Set<string>>();
+
       // Read all entity files in parallel batches to avoid O(N) sequential I/O.
       // With 3000+ entity files, sequential reads can take 15-20s under load.
       // Batching at 100 keeps file-descriptor pressure manageable while staying fast.
@@ -652,19 +745,39 @@ export class EntityStore {
         const batch = mdFiles.slice(i, i + BATCH_SIZE);
         const results = await Promise.all(
           batch.map(async (entry) => {
+            const entityId = entry.slice(0, -".md".length);
+            const entryPath = path.join(this.deps.entitiesDir, entry);
             try {
-              if (!(await this.isContainedRegularEntityFile(entry))) return null;
-              return await this.deps.readStorageSecureFile(path.join(this.deps.entitiesDir, entry));
+              if (!(await this.isContainedRegularEntityFile(entry))) {
+                // A listed entry that vanished races a background migration
+                // rename: resolve through historical ids like a direct read.
+                // Still-present symlinks/dirs stay skipped.
+                if (await this.isMissingEntry(entry)) {
+                  return await this.readEntityFileResolvingRename(entryPath, entityId);
+                }
+                return null;
+              }
+              return await this.readEntityFileResolvingRename(entryPath, entityId);
             } catch (err) {
-              if (err instanceof SecureStoreLockedError) throw err;
-              if (!isErrnoCode(err, "ENOENT")) throw err;
+              // Lock and decrypt failures abort the corpus read (the store
+              // is unusable or tampered); anything else isolates to this entry.
+              if (err instanceof SecureStoreLockedError || err instanceof SecureStoreDecryptError) throw err;
+              log.warn(`entity read isolated failure for ${entry}: ${err instanceof Error ? err.message : String(err)}`);
               return null;
             }
           }),
         );
-        for (const content of results) {
-          if (content === null) continue;
-          const entity = parseEntityFile(content, this.deps.entitySchemas);
+        for (const result of results) {
+          if (result === null) continue;
+          const canonical = resolveHistoricalEntityCanonicalId(result.id, historicalIds);
+          let contents = seen.get(canonical);
+          if (contents?.has(result.content)) continue;
+          if (!contents) {
+            contents = new Set();
+            seen.set(canonical, contents);
+          }
+          contents.add(result.content);
+          const entity = parseEntityFile(result.content, this.deps.entitySchemas);
           if (!entity.name.trim() || !entity.type.trim()) continue;
           entities.push(entity);
         }

package/src/storage.ts

@@ -2323,10 +2323,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
   private _entityStore: EntityStore | undefined;
 
   private get entityStore(): EntityStore {
-    if (!this._entityStore) {
-      this._entityStore = new EntityStore(selfDeps<ConstructorParameters<typeof EntityStore>[0]>(this));
-    }
-    return this._entityStore;
+    return (this._entityStore ??= new EntityStore(selfDeps<ConstructorParameters<typeof EntityStore>[0]>(this)));
   }
 
   /** IdentityContinuityStore (storage.ts decomposition). Lazy; selfDeps live wiring. */
@@ -3537,6 +3534,16 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
   private currentHistoricalIds(): Readonly<Record<string, string>> {
     return this.historicalEntityCanonicalIds.get(this.stateDir);
   }
+
+  /** Journal completion for EntityStore's legacy-id retry gate (live view). */
+  entityCanonicalMigrationComplete = entityRefs.memoizedJournalCompletion(this.historicalEntityCanonicalIds, () => this.stateDir);
+
+  normalizeEntityName(raw: string, type: string): string {
+    return entityRefs.resolveHistoricalEntityCanonicalId(
+      this.entityStore.normalizeEntityName(raw, type),
+      this.currentHistoricalIds()
+    );
+  }
   /** Post-persist repair subsystem (issue #2213) — storage/entity-ref-repair.ts. */
   private _entityRefRepair: EntityRefRepair | undefined;
   private get entityRefRepair(): EntityRefRepair {
@@ -3561,12 +3568,6 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
     () => this.runLegacyEntityCanonicalIdMigration(),
     () => entityMigration.getFingerprint(this.baseDir, this.entitiesDir, () => String(this.getEntityMutationVersion()))
   );
-  normalizeEntityName(raw: string, type: string): string {
-    return entityRefs.resolveHistoricalEntityCanonicalId(
-      this.entityStore.normalizeEntityName(raw, type),
-      this.currentHistoricalIds()
-    );
-  }
 
   /**
    * Read-only view of this store's user alias table, for call sites that
@@ -3623,7 +3624,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
     return completionFingerprint;
   }
 
-  async ensureDirectories(): Promise<void> {
+  async ensureDirectories(options: { waitForEntityMigration?: boolean } = {}): Promise<void> {
     await mkdir(this.baseDir, { recursive: true });
     await entityMigration.validateRoots(this.baseDir, this.entitiesDir, this.stateDir, this.archiveDir);
     const today = new Date().toISOString().slice(0, 10);
@@ -3640,7 +3641,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
     await mkdir(this.identityAuditsWeeklyDir, { recursive: true });
     await mkdir(this.identityAuditsMonthlyDir, { recursive: true });
     await mkdir(path.join(this.baseDir, "config"), { recursive: true });
-    await this.entityCanonicalIdMigration.ensure();
+    await this.entityCanonicalIdMigration.begin(options.waitForEntityMigration !== false, this.entitiesDir);
     // Activate the corpus sentinel at setup (issue #1902, Cursor Medium): an
     // existing corpus predating this feature has a size-0/absent sentinel, which
     // getCachedMemories treats as a miss — so a read-heavy workload would never
@@ -3654,9 +3655,9 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
     if (this.hotMemoriesCacheEnabled && this.getMemoryCorpusVersion() === 0) {
       this.bumpMemoryCorpusVersion();
     }
-    await this.entityCanonicalIdMigration.markDirectoriesInitialized();
+    return this.entityCanonicalIdMigration.finishBegin(options.waitForEntityMigration !== false);
   }
-
+  drainEntityCanonicalIdMigration = (): Promise<void> => this.entityCanonicalIdMigration.drain();
   /**
    * Resolve the on-disk write path for a memory of the given category, creating
    * the target directory. Category routing goes through the shared
@@ -4079,7 +4080,6 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
     await this.addActiveFactContentHash(memory);
   }
 
-
   private async syncFactHashIndexAfterRewrite(before: MemoryFile, after: MemoryFile): Promise<void> {
     if (before.frontmatter.category !== "fact" && after.frontmatter.category !== "fact") return;