@remnic/core 10.0.48 → 10.0.50

package/src/storage/entity-store.ts

@@ -10,11 +10,17 @@
  *   - fragmented-entity merge (consolidation)
  */
 
-import { lstat, readdir, realpath, unlink } from "node:fs/promises";
+import { lstat, readdir, unlink } from "node:fs/promises";
 import path from "node:path";
 import { checkCorpusReadAbort, type CorpusReadOptions } from "../corpus-read-cancellation.js";
 import { normalizeEntityStructuredSection, sortStructuredSectionsBySchema } from "../entity-schema.js";
 import { withEntityCanonicalMutationLock } from "./entity-canonical-id-lock.js";
+import { assertSafeEntityId } from "./entity-id-safety.js";
+import {
+  EntityMigrationCompletionCache,
+  isTrustedEntitiesRoot,
+  readEntityFileResolvingRename,
+} from "./entity-migration-completion-cache.js";
 import { isMalformedEntityRecord } from "../utils/malformed-entity-record.js";
 import { log } from "../logger.js";
 import {
@@ -33,7 +39,6 @@ import type {
   ScoredEntity,
 } from "../types.js";
 import { isErrnoCode } from "../utils/errno.js";
-import { pathIsInside } from "../utils/path-containment.js";
 import {
   reconcileIfJournalMovedSync,
   requestEntityCanonicalIdReconcileSync,
@@ -89,6 +94,7 @@ export interface EntityStoreDeps {
 export class EntityStore {
   /** Filename → file identity of the last indexable check. Unchanged files are not reread. */
   private readonly entityIndexableCache = new Map<string, { identity: string; ok: boolean }>();
+  private readonly migrationCompletion = new EntityMigrationCompletionCache();
 
   constructor(
     private readonly deps: EntityStoreDeps,
@@ -111,6 +117,7 @@ export class EntityStore {
     method: string,
     historicalIds: Readonly<Record<string, string>>,
   ): Promise<{ filePath: string; entity: EntityFile } | null> {
+    assertSafeEntityId(name);
     const canonical = resolveHistoricalEntityCanonicalId(name, historicalIds);
     for (const candidate of canonical === name ? [name] : [canonical, name]) {
       const filePath = path.join(this.deps.entitiesDir, `${candidate}.md`);
@@ -143,6 +150,7 @@ export class EntityStore {
     method: string,
     mutate: (entity: EntityFile, historicalIds: Readonly<Record<string, string>>) => boolean,
   ): Promise<boolean> {
+    await this.deps.ensureDirectories();
     const stateDir = path.join(this.deps.baseDir, "state");
     return withEntityCanonicalMutationLock(stateDir, async () => {
       for (let attempt = 0; attempt < 3; attempt += 1) {
@@ -375,83 +383,46 @@ export class EntityStore {
     return normalized;
   }
 
-  private async readEntityFileResolvingRename(firstPath: string, entityId: string) {
-    try {
-      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) {
+  async readEntity(name: string): Promise<string> {
+    const filePath = this.deps.resolveEntityFilePath(name);
+    if (filePath === null) return "";
+    // Physical hit wins. Miss skips rename/body-scan only when amortized
+    // completion attests live fingerprint inputs (not bare journal.complete).
+    const readDirect = async (): Promise<string | undefined> => {
       try {
-        return { id: candidate, content: await this.deps.readStorageSecureFile(
-          path.join(this.deps.entitiesDir, `${candidate}.md`),
-        ) };
+        return await this.deps.readStorageSecureFile(filePath);
       } 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;
+        if (isErrnoCode(err, "ENOENT") || isErrnoCode(err, "ELOOP")) return undefined;
         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()) {
+    };
+    const direct = await readDirect();
+    if (direct !== undefined) return direct;
+    if (await this.migrationCompletion.isCompleted(this.deps)) return "";
+    const renamed = await readEntityFileResolvingRename(this.deps, filePath, name);
+    if (renamed !== null) return renamed.content;
+    // Deferred / fingerprint-stale: match legacy filename by body id.
+    let legacy: string | undefined;
+    for (const file of await this.readEntityDirectoryNames()) {
+      if (!file.endsWith(".md") || !(await this.isContainedRegularEntityFile(file))) continue;
+      let content: string;
       try {
-        return await this.deps.readStorageSecureFile(filePath);
+        content = await this.deps.readStorageSecureFile(path.join(this.deps.entitiesDir, file));
       } 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 "";
+        if (isErrnoCode(err, "ENOENT") || isErrnoCode(err, "ELOOP")) continue;
         throw err;
       }
+      if (isMalformedEntityRecord(content)) continue;
+      const entity = parseEntityFile(content, this.deps.entitySchemas);
+      if (!entity.name.trim() || !entity.type.trim()) continue;
+      if (this.deps.normalizeEntityName(entity.name, entity.type) !== name) continue;
+      if (legacy !== undefined) throw new Error(`Ambiguous legacy entity id: ${name}`);
+      legacy = content;
     }
-    return (await this.readEntityFileResolvingRename(filePath, name))?.content ?? "";
-  }
-
-  /**
-   * True when `entities/` is a real directory inside this memory root.
-   * `realpath` on a symlinked root would treat the link target as trusted,
-   * so the check uses `lstat` first and refuses the scan when the root
-   * itself is a symlink.
-   */
-  private async isTrustedEntitiesRoot(): Promise<boolean> {
-    let rootStat;
-    try {
-      rootStat = await lstat(this.deps.entitiesDir);
-    } catch (err) {
-      if (isErrnoCode(err, "ENOENT")) return false;
-      throw err;
-    }
-    if (rootStat.isSymbolicLink() || !rootStat.isDirectory()) return false;
-    let memoryRoot: string;
-    let entitiesReal: string;
-    try {
-      memoryRoot = await realpath(this.deps.baseDir);
-      entitiesReal = await realpath(this.deps.entitiesDir);
-    } catch (err) {
-      if (isErrnoCode(err, "ENOENT")) return false;
-      throw err;
-    }
-    return pathIsInside(memoryRoot, entitiesReal);
+    // A peer may have renamed the legacy entry after the directory listing.
+    return (await readDirect()) ?? legacy ?? "";
   }
 
   /**
@@ -460,7 +431,7 @@ export class EntityStore {
    * A symlinked entities root yields an empty list and is not read.
    */
   private async readEntityDirectoryNames(): Promise<string[]> {
-    if (!(await this.isTrustedEntitiesRoot())) return [];
+    if (!(await isTrustedEntitiesRoot(this.deps.baseDir, this.deps.entitiesDir))) return [];
     const entries = await readdir(this.deps.entitiesDir);
     const { kept, ignored } = withoutMacOsReplicationJunk(entries, (name) => name);
     warnIgnoredMacOsReplicationJunk(this.deps.entitiesDir, ignored, (message) => {
@@ -595,6 +566,7 @@ export class EntityStore {
 
   /** Re-serialize every entity file into the compiled-truth timeline shape. */
   async migrateEntityFilesToCompiledTruthTimeline(): Promise<{ total: number; migrated: number }> {
+    await this.deps.ensureDirectories();
     const entityNames = await this.listEntityNames();
     const stateDir = path.join(this.deps.baseDir, "state");
     let migrated = 0;
@@ -605,14 +577,20 @@ export class EntityStore {
       // path bumps only the status version, which never re-triggers the
       // completed migration's reference scan.
       const wrote = await withEntityCanonicalMutationLock(stateDir, async () => {
-        const raw = await this.readEntity(entityName);
+        const filePath = this.deps.resolveEntityFilePath(entityName);
+        if (filePath === null) return false;
+        let raw: string;
+        try {
+          raw = await this.deps.readStorageSecureFile(filePath);
+        } catch (err) {
+          if (err instanceof SecureStoreLockedError || !isErrnoCode(err, "ENOENT")) throw err;
+          return false;
+        }
         if (!raw || isMalformedEntityRecord(raw)) return false;
         const parsed = parseEntityFile(raw, this.deps.entitySchemas);
         if (!parsed.name.trim() || !parsed.type.trim()) return false;
         const serialized = serializeEntityFile(parsed, this.deps.entitySchemas, this.deps.okfConformanceEnabled());
         if (raw.trimEnd() === serialized.trimEnd()) return false;
-        const filePath = this.deps.resolveEntityFilePath(entityName);
-        if (filePath === null) return false;
         await this.deps.writeStorageSecureFile(filePath, serialized);
         this.deps.bumpEntityMutationVersion();
         return true;
@@ -641,6 +619,7 @@ export class EntityStore {
       incrementVersion?: boolean;
     } = {},
   ): Promise<void> {
+    await this.deps.ensureDirectories();
     return withEntityCanonicalMutationLock(
       path.join(this.deps.baseDir, "state"),
       () => this.updateEntitySynthesisUnlocked(name, synthesis, options),
@@ -659,17 +638,9 @@ export class EntityStore {
       incrementVersion?: boolean;
     } = {},
   ): Promise<void> {
-    const filePath = path.join(this.deps.entitiesDir, `${name}.md`);
-    let entity: EntityFile;
-    try {
-      const content = await this.deps.readStorageSecureFile(filePath);
-      entity = parseEntityFile(content, this.deps.entitySchemas);
-    } catch (err) {
-      if (err instanceof SecureStoreLockedError) throw err;
-      if (!isErrnoCode(err, "ENOENT")) throw err;
-      log.debug(`updateEntitySynthesis: entity file ${name}.md not found`);
-      return;
-    }
+    const located = await this.readEntityForMutation(name, "updateEntitySynthesis", this.deps.currentHistoricalIds());
+    if (!located) return;
+    const { filePath, entity } = located;
 
     const updatedAt = options.updatedAt?.trim() || entity.synthesisUpdatedAt?.trim() || undefined;
     const entityUpdatedAt = options.entityUpdatedAt?.trim() || updatedAt || entity.updated || new Date().toISOString();
@@ -721,7 +692,7 @@ export class EntityStore {
       // #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 [];
+      if (!(await isTrustedEntitiesRoot(this.deps.baseDir, this.deps.entitiesDir))) return [];
       const listed = await readdir(this.deps.entitiesDir);
       const { kept: entries, ignored } = withoutMacOsReplicationJunk(listed, (name) => name);
       warnIgnoredMacOsReplicationJunk(this.deps.entitiesDir, ignored, (message) => {
@@ -753,11 +724,11 @@ export class EntityStore {
                 // 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 await readEntityFileResolvingRename(this.deps, entryPath, entityId);
                 }
                 return null;
               }
-              return await this.readEntityFileResolvingRename(entryPath, entityId);
+              return await readEntityFileResolvingRename(this.deps, entryPath, entityId);
             } catch (err) {
               // Lock and decrypt failures abort the corpus read (the store
               // is unusable or tampered); anything else isolates to this entry.
@@ -873,6 +844,7 @@ export class EntityStore {
    * Returns count of files merged.
    */
   async mergeFragmentedEntities(): Promise<number> {
+    await this.deps.ensureDirectories();
     return withEntityCanonicalMutationLock(
       path.join(this.deps.baseDir, "state"),
       () => this.mergeFragmentedEntitiesUnlocked(),

package/src/storage/memory-read-store.ts

@@ -41,7 +41,7 @@ export interface MemoryReadStoreDeps {
   readonly artifactsDir: string;
   readonly baseDir: string;
   readonly bufferSurpriseLedgerPath: string;
-  collectActiveMemoryPaths(): Promise<string[]>;
+  collectActiveMemoryPaths(options?: CorpusReadOptions): Promise<string[]>;
   readonly correctionsDir: string;
   ensureDirectories(): Promise<void>;
   readonly entitySchemas: PluginConfig["entitySchemas"] | undefined;
@@ -79,6 +79,7 @@ export interface MemoryReadStoreDeps {
     remainingSlots: number,
     remainingInspectionBudget: number,
     readBatchSize: number,
+    options?: CorpusReadOptions,
   ): Promise<{ memories: MemoryFile[]; filePaths: string[] }>;
   readonly reasoningTracesDir: string;
   resolveTierRootDir(tier: "hot" | "cold"): string;
@@ -408,8 +409,10 @@ export class MemoryReadStore {
     maxMemories?: number;
     batchSize?: number;
     updatedAfter?: Date;
+    abortSignal?: AbortSignal;
   } = {}): Promise<{ memories: MemoryFile[]; filePaths: string[] }> {
-    const allPaths = await this.deps.collectActiveMemoryPaths();
+    const readOptions: CorpusReadOptions = { abortSignal: options.abortSignal };
+    const allPaths = await this.deps.collectActiveMemoryPaths(readOptions);
     const sortedPaths = this.deps.orderWindowPaths(allPaths);
     const maxMemories =
       typeof options.maxMemories === "number" && Number.isFinite(options.maxMemories)
@@ -422,6 +425,8 @@ export class MemoryReadStore {
     const selectedPaths: string[] = [];
 
     for (let i = 0; i < sortedPaths.length; i += normalizedBatchSize) {
+      // Per batch: an abandoned caller must not keep the scan running (#3139).
+      checkCorpusReadAbort(readOptions);
       if (
         maxMemories !== undefined
         && (memories.length >= maxMemories || (maxCandidatePaths !== undefined && selectedPaths.length >= maxCandidatePaths))
@@ -436,7 +441,7 @@ export class MemoryReadStore {
       const remainingInspectionBudget = maxCandidatePaths === undefined ? undefined : Math.max(0, maxCandidatePaths - selectedPaths.length);
       const { memories: batchMemories, filePaths: parsedCandidatePaths } = remainingSlots === undefined
         ? {
-            memories: await this.deps.readParsedMemoriesFromPaths(candidateBatchPaths, normalizedBatchSize),
+            memories: await this.deps.readParsedMemoriesFromPaths(candidateBatchPaths, normalizedBatchSize, readOptions),
             filePaths: candidateBatchPaths,
           }
         : await this.deps.readWindowBoundedBatch(
@@ -444,6 +449,7 @@ export class MemoryReadStore {
             remainingSlots,
             remainingInspectionBudget ?? remainingSlots,
             normalizedBatchSize,
+            readOptions,
           );
       selectedPaths.push(...parsedCandidatePaths);
       for (const memory of batchMemories) {

package/src/storage/windowed-memory-read.ts

@@ -1,5 +1,6 @@
 import { stat } from "node:fs/promises";
 import path from "node:path";
+import { throwIfAborted } from "../abort-error.js";
 import { getCachedMemories } from "../memory-cache.js";
 import { readRawMemoryDocument } from "./memory-frontmatter-metadata.js";
 import type { MemoryFile } from "../types.js";
@@ -11,6 +12,12 @@ export interface WindowedMemoryReadOptions {
   updatedAfter?: Date;
   /** Require candidate paths so malformed files can be reported by governance. */
   includeMalformedPaths?: boolean;
+  /**
+   * Caller cancellation. The windowed scan stops at its next batch boundary
+   * when this aborts, so a cancelled read leaves no work running behind it
+   * (issue #3139).
+   */
+  abortSignal?: AbortSignal;
 }
 
 export interface WindowedMemoryReadResult {
@@ -62,6 +69,7 @@ export async function readWindowedMemories(
           })
         )
       ).filter((memory): memory is MemoryFile => memory !== null);
+      throwIfAborted(options.abortSignal, "windowed memory read aborted");
       const memories = orderWindowMemories(selected, hotCache.baseDir);
       return { memories: rememberMemorySnapshots(memories), filePaths: memories.map((memory) => memory.path) };
     }

package/src/storage-startup-nonblocking-migration.test.ts

@@ -0,0 +1,183 @@
+import assert from "node:assert/strict";
+import { existsSync } from "node:fs";
+import { mkdir, mkdtemp, readFile, readdir, rm, symlink, unlink, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { StorageManager } from "./storage.js";
+import { sleep } from "./utils/sleep.js";
+
+// Issue #3139 (Q2 briefing 60s ceiling): the CLI briefing path awaits
+// orchestrator.initialize(), which awaited storage.ensureDirectories(), which
+// awaited the entity canonical-id migration lock/replay (up to a 300s bounded
+// wait on a busy lock). Startup READ readiness must not sit behind that
+// migration; writes must. These tests pin the boundary with the real on-disk
+// migration lock and a real temp corpus — no orchestrator stubs. Every wait is
+// bounded so a regression fails fast instead of stalling the run.
+
+const MIGRATION_LOCK_FILE = path.join("state", "entity-canonical-id-migration.lock");
+const MIGRATION_JOURNAL_FILE = path.join("state", "entity-canonical-id-migration-v1.json");
+const READINESS_BUDGET_MS = 500;
+const BARRIER_PROBE_MS = 250;
+
+async function withMemoryDir(run: (dir: string) => Promise<void>): Promise<void> {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-startup-migration-"));
+  try {
+    await run(dir);
+  } finally {
+    StorageManager.clearAllStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Hold the migration's own cross-process lock (the exact file
+ * migrateLegacyEntityCanonicalIds acquires via withHeldFileLock: poll 50ms,
+ * stale 60s — a hold for the lifetime of one test). Returns the release.
+ */
+async function gateMigration(dir: string): Promise<() => Promise<void>> {
+  const lockPath = path.join(dir, MIGRATION_LOCK_FILE);
+  await mkdir(path.dirname(lockPath), { recursive: true });
+  await writeFile(lockPath, `${process.pid} startup-migration-test ${new Date().toISOString()}\n`);
+  return () => unlink(lockPath);
+}
+
+async function journalComplete(dir: string): Promise<boolean> {
+  try {
+    // SAFETY: the journal is written by this test fixture and carries an optional boolean `complete`.
+    const state = JSON.parse(await readFile(path.join(dir, MIGRATION_JOURNAL_FILE), "utf8")) as {
+      complete?: boolean;
+    };
+    return state.complete === true;
+  } catch {
+    return false;
+  }
+}
+
+test("startup read readiness can defer the entity canonical-id migration", async () => {
+  await withMemoryDir(async (dir) => {
+    const storage = new StorageManager(dir);
+    const releaseGate = await gateMigration(dir);
+    const readiness = storage.ensureDirectories({ waitForEntityMigration: false });
+    // Regression: on the awaited path this call sits behind the held lock and
+    // only surfaces after the 300s bounded wait. The startup option must
+    // settle while the lock is still held — asserted against a bounded race
+    // so main fails behaviorally in ~500ms instead of stalling the job.
+    let failure: unknown;
+    try {
+      const outcome = await Promise.race([readiness, sleep(READINESS_BUDGET_MS).then(() => "timeout")]);
+      assert.notEqual(outcome, "timeout", "startup read readiness must not wait for the gated migration");
+      assert.equal(existsSync(path.join(dir, "entities")), true);
+      assert.equal(
+        existsSync(path.join(dir, MIGRATION_LOCK_FILE)),
+        true,
+        "the deferred startup must not take the migration lock",
+      );
+      assert.equal(
+        existsSync(path.join(dir, MIGRATION_JOURNAL_FILE)),
+        false,
+        "the deferred startup must not run the migration",
+      );
+    } catch (err) {
+      failure = err;
+    } finally {
+      await releaseGate();
+    }
+    // The write-side ensure still runs the migration and awaits it.
+    await readiness;
+    await storage.ensureDirectories();
+    if (failure !== undefined) throw failure;
+    assert.equal(await journalComplete(dir), true);
+    // Normal entity writes still work after the deferred migration settles.
+    await storage.writeEntity("Alice", "person", ["Alice works on Remnic"]);
+  });
+});
+
+test("default ensureDirectories still waits behind a held migration lock", async () => {
+  await withMemoryDir(async (dir) => {
+    const storage = new StorageManager(dir);
+    const releaseGate = await gateMigration(dir);
+    let settled = false;
+    let setupError: Error | undefined;
+    const gatedSetup = storage.ensureDirectories().then(
+      () => {
+        settled = true;
+      },
+      (err: Error) => {
+        setupError = err;
+        settled = true;
+      },
+    );
+    let failure: unknown;
+    try {
+      await sleep(BARRIER_PROBE_MS);
+      assert.equal(settled, false, "default ensureDirectories must not resolve while the migration lock is held");
+    } catch (err) {
+      failure = err;
+    } finally {
+      await releaseGate();
+    }
+    await gatedSetup;
+    assert.equal(setupError, undefined);
+    if (failure !== undefined) throw failure;
+    assert.equal(await journalComplete(dir), true);
+  });
+});
+
+test("deferred startup still refuses unsafe entity entries before serving reads", async () => {
+  const outside = await mkdtemp(path.join(os.tmpdir(), "remnic-startup-migration-outside-"));
+  try {
+    await withMemoryDir(async (dir) => {
+      const storage = new StorageManager(dir);
+      await mkdir(path.join(dir, "entities"), { recursive: true });
+      await symlink(path.join(outside, "leaked.md"), path.join(dir, "entities", "leaked.md"));
+      await assert.rejects(
+        () => storage.ensureDirectories({ waitForEntityMigration: false }),
+        /Refusing entity canonical-id migration through symlink/,
+      );
+    });
+  } finally {
+    await rm(outside, { recursive: true, force: true });
+  }
+});
+
+test("entity writes queue behind the migration they trigger", async () => {
+  await withMemoryDir(async (dir) => {
+    const storage = new StorageManager(dir);
+    const releaseGate = await gateMigration(dir);
+    const readiness = storage.ensureDirectories({ waitForEntityMigration: false });
+    const { promise: written, resolve: writeSettled } = Promise.withResolvers<void>();
+    let writeError: Error | undefined;
+    let failure: unknown;
+    try {
+      const outcome = await Promise.race([readiness, sleep(READINESS_BUDGET_MS).then(() => "timeout")]);
+      assert.notEqual(outcome, "timeout", "startup read readiness must not wait for the gated migration");
+      // A real entity write must queue behind the migration it triggers — the
+      // deferred startup opens READ readiness only.
+      storage.writeEntity("Alice", "person", ["Alice works on Remnic"]).then(
+        () => writeSettled(),
+        (err: Error) => {
+          writeError = err;
+          writeSettled();
+        },
+      );
+      const writeProbe = await Promise.race([written, sleep(BARRIER_PROBE_MS).then(() => "pending")]);
+      assert.equal(writeProbe, "pending", "entity writes must queue behind the migration they trigger");
+    } catch (err) {
+      failure = err;
+    } finally {
+      await releaseGate();
+    }
+    await readiness;
+    await storage.ensureDirectories();
+    if (failure === undefined) {
+      const settled = await Promise.race([written, sleep(10_000).then(() => "deadline")]);
+      assert.notEqual(settled, "deadline", "entity write must complete once the gate releases");
+      assert.equal(writeError, undefined);
+      const entries = await readdir(path.join(dir, "entities"));
+      assert.equal(entries.some((name) => name.endsWith(".md")), true, "entity file must land after the migration settles");
+    }
+    if (failure !== undefined) throw failure;
+  });
+});

package/src/storage.ts

@@ -17,6 +17,7 @@ import { computeLegacyContentHash, normalizeContent } from "./content-hash.js";
 import { parseDriftProvenance, serializeDriftProvenance } from "./preferences/drift-types.js";
 import { isAbortError, raceAbort } from "./abort-error.js";
 import { checkCorpusReadAbort, type CorpusReadOptions } from "./corpus-read-cancellation.js";
+import { scopedCaptureWriteLockLimits } from "./capture-write-lock-scope.js";
 import { selectArtifactMatches, type ArtifactSearchOptions } from "./artifact-search.js";
 import path from "node:path";
 import { resolveSafeStoragePath } from "./storage-paths.js";
@@ -1922,6 +1923,8 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
   onCatalogWrite?: () => void;
   /** Post-write embedding hook (#2019). Installed by the orchestrator; fire-and-forget. */
   onMemoryWrite?: (filePath: string) => void;
+  /** Request search maintenance after a completed entity replay. */
+  onEntityMigrationComplete?: () => void;
   private notifyMemoryWrite(filePath: string): void {
     try {
       this.onMemoryWrite?.(filePath);
@@ -3241,7 +3244,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
    * resolves to the legacy short bounds instead of the converge deadline.
    */
   private captureLockLimitSource(): ContentHashIndexLockOptions | undefined {
-    const options = this.factHashIndexLockOptions;
+    const options = { ...this.factHashIndexLockOptions, ...scopedCaptureWriteLockLimits(this) };
     const keys = ["captureWriteLockInitialDelayMs", "captureWriteLockMaxDelayMs", "captureWriteLockDeadlineMs", "captureWriteLockSignal"] as const;
     return keys.some((key) => options[key] !== undefined) ? options : undefined;
   }
@@ -4833,13 +4836,16 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
     candidateBatchPaths: string[],
     remainingSlots: number,
     remainingInspectionBudget: number,
-    readBatchSize: number
+    readBatchSize: number,
+    options?: CorpusReadOptions
   ): Promise<{ memories: MemoryFile[]; filePaths: string[] }> {
     const memories: MemoryFile[] = [];
     const filePaths: string[] = [];
     const normalizedReadBatchSize = this.normalizeMemoryReadBatchSize(readBatchSize);
 
     for (let index = 0; index < candidateBatchPaths.length; ) {
+      // Per batch: an abandoned caller must not keep the scan running (#3139).
+      checkCorpusReadAbort(options);
       if (memories.length >= remainingSlots || filePaths.length >= remainingInspectionBudget) break;
       const availableSlots = remainingSlots - memories.length;
       const availableInspectionBudget = remainingInspectionBudget - filePaths.length;
@@ -4852,7 +4858,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
       index += candidatePaths.length;
       if (candidatePaths.length === 0) break;
       filePaths.push(...candidatePaths);
-      const parsedMemories = await this.readParsedMemoriesFromPaths(candidatePaths, candidatePaths.length);
+      const parsedMemories = await this.readParsedMemoriesFromPaths(candidatePaths, candidatePaths.length, options);
       if (parsedMemories.length === 0) continue;
       memories.push(...parsedMemories.slice(0, availableSlots));
     }

package/src/testing/subjects/entity-migration-completion-cache.test.ts

@@ -0,0 +1,90 @@
+/**
+ * Lifecycle matrix subject for the amortized entity migration-completion
+ * cache. Exercises the helper only through StorageManager.readEntity — never
+ * a direct cache test double.
+ */
+import assert from "node:assert/strict";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import { StorageManager } from "../../storage.js";
+import { type LifecycleSubject, type MatrixRow, runLifecycleMatrix } from "../lifecycle-matrix.js";
+import { mkTempMemoryDir } from "../orchestrator-lite.js";
+
+interface CompletionCacheState {
+  dir: string;
+  previousId: string;
+  reader: StorageManager;
+  warmMiss: string;
+  afterAlias?: string;
+  afterRestart?: string;
+  restarted?: StorageManager;
+}
+
+const subject: LifecycleSubject<CompletionCacheState> = {
+  async setup(row: MatrixRow): Promise<CompletionCacheState> {
+    const dir = await mkTempMemoryDir(`entity-mig-complete-${row.id}`);
+    try {
+      const seed = new StorageManager(dir);
+      const previousId = await seed.writeEntity("Café", "project", ["Synthetic legacy fact."]);
+      await seed.ensureDirectories();
+      const reader = new StorageManager(dir);
+      await reader.ensureDirectories({ waitForEntityMigration: false });
+      return { dir, previousId, reader, warmMiss: "" };
+    } catch (error) {
+      await rm(dir, { recursive: true, force: true });
+      throw error;
+    }
+  },
+
+  async exercise(state: CompletionCacheState, row: MatrixRow): Promise<void> {
+    // Warm the amortized completion verdict on a miss (key + fingerprint path).
+    state.warmMiss = await state.reader.readEntity("project-missing");
+
+    await mkdir(path.join(state.dir, "config"), { recursive: true });
+    await writeFile(path.join(state.dir, "config", "aliases.json"), JSON.stringify({ café: "coffee" }));
+    await state.reader.loadAliases();
+    const canonical = state.reader.normalizeEntityName("Café", "project");
+    assert.notEqual(canonical, state.previousId, `${row.id}: alias must move the canonical id`);
+    state.afterAlias = await state.reader.readEntity(canonical);
+
+    if (row.dimensions.restart) {
+      const restarted = new StorageManager(state.dir);
+      state.restarted = restarted;
+      await restarted.ensureDirectories({ waitForEntityMigration: false });
+      await restarted.loadAliases();
+      state.afterRestart = await restarted.readEntity(restarted.normalizeEntityName("Café", "project"));
+    }
+
+    if (row.dimensions.dedupeOrReplay) {
+      // Second miss with stable inputs must stay a cheap empty miss (no throw).
+      assert.equal(await state.reader.readEntity("project-missing-again"), "");
+    }
+  },
+
+  async invariants(state: CompletionCacheState, row: MatrixRow): Promise<void> {
+    assert.equal(state.warmMiss, "", `${row.id}: warm miss must return empty`);
+    assert.match(
+      state.afterAlias ?? "",
+      /Synthetic legacy fact/,
+      `${row.id}: alias drift must not hide the entity behind a stale completion cache`,
+    );
+    if (row.dimensions.restart) {
+      assert.match(
+        state.afterRestart ?? "",
+        /Synthetic legacy fact/,
+        `${row.id}: restarted reader must still resolve the alias-moved entity`,
+      );
+    }
+  },
+
+  async teardown(state: CompletionCacheState): Promise<void> {
+    // The deferred startup replay runs in the background; let it finish before the directory goes.
+    await state.reader.drainEntityCanonicalIdMigration();
+    await state.restarted?.drainEntityCanonicalIdMigration();
+    StorageManager.clearAllStaticCaches();
+    await rm(state.dir, { recursive: true, force: true });
+  },
+};
+
+runLifecycleMatrix("entity-migration-completion-cache", subject);