@remnic/core 10.0.51 → 10.0.53

package/src/orchestrator.ts

@@ -865,6 +865,7 @@ export class Orchestrator {
         invalidateGraphEdgeCache: (storage) => this.graphIndexFor(storage).invalidateEdgeCache(),
         updateTemporalTagIndexes: (storage, persistedIds) =>
           this.updateTemporalTagIndexes(storage, persistedIds),
+        requestQmdMaintenance: () => this.requestQmdMaintenance(),
       });
     }
     return this._extractionPersistCoordinator;
@@ -1511,7 +1512,14 @@ export class Orchestrator {
       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(); };
+      storage.onEntityMigrationComplete = () => {
+        if (!this.acceptingEntityMigrationMaintenance) return false;
+        // Settles once a QMD pass covering this request ran; the migration keeps its pending marker until then.
+        const served = this.maintenanceScheduler.requestQmdMaintenanceCompletion();
+        // Same side effects as before: projection rebuild and ledger-compaction checks, independent of QMD.
+        this.requestQmdMaintenance();
+        return served;
+      };
       if (this.prioritizedEmbedding) storage.onMemoryWrite = (filePath) => this.prioritizedEmbedding?.enqueue(filePath, namespace);
     };
     bindStorage(this.storage, this.config.defaultNamespace);

package/src/search/lancedb-backend.ts

@@ -139,23 +139,38 @@ export class LanceDbBackend implements SearchBackend {
   }
 
   async updateCollectionFromDir(collection: string, memoryDir: string, execution?: SearchExecutionOptions): Promise<void> {
-    if (isSearchAborted(execution)) return;
+    await this.refreshCollection(collection, memoryDir, execution);
+  }
+
+  async updateCompleted(execution?: SearchExecutionOptions): Promise<boolean> {
+    try {
+      return await this.refreshCollection(this.collection, this.memoryDir, execution);
+    } catch (err) {
+      log.debug(`LanceDbBackend update did not complete: ${err}`);
+      return false;
+    }
+  }
+
+  /** Brings the collection up to date; true only when it ran to completion (false: aborted, unavailable, skipped or failed). */
+  private async refreshCollection(collection: string, memoryDir: string, execution?: SearchExecutionOptions): Promise<boolean> {
+    if (isSearchAborted(execution)) return false;
     let table = await this.ensureTableForCollection(collection);
-    if (isSearchAborted(execution)) return;
-    if (!table) return;
+    if (isSearchAborted(execution)) return false;
+    if (!table) return false;
 
     const docs = await scanMemoryDir(memoryDir);
-    if (isSearchAborted(execution)) return;
+    if (isSearchAborted(execution)) return false;
     if (docs.length === 0) {
       // Clear stale data when no docs remain
       try {
         const db = await this.ensureDb();
         await db.dropTable(collection).catch(() => {});
         if (collection === this.collection) this.table = null;
+        return true;
       } catch {
         // Best-effort cleanup
       }
-      return;
+      return false;
     }
 
     const embeddingProviderIdentity = this.embedHelper.getProviderIdentity();
@@ -166,13 +181,13 @@ export class LanceDbBackend implements SearchBackend {
     const vectorProviderColumnState = await this.tableVectorProviderColumnState(table);
     if (vectorProviderColumnState === "missing") {
       table = await this.recreateTableForCollection(collection);
-      if (isSearchAborted(execution)) return;
-      if (!table) return;
+      if (isSearchAborted(execution)) return false;
+      if (!table) return false;
     } else if (vectorProviderColumnState === "present") {
       try {
         const existingRows = await table.query().select(["docid", "vector", "vectorProvider"]).toArray();
         for (const row of existingRows ?? []) {
-          if (isSearchAborted(execution)) return;
+          if (isSearchAborted(execution)) return false;
           const docid = row.docid;
           if (typeof docid !== "string") continue;
           const vector = row.vector;
@@ -184,11 +199,11 @@ export class LanceDbBackend implements SearchBackend {
         }
       } catch {
         log.debug("LanceDbBackend skipped refresh after vector preservation failed");
-        return;
+        return false;
       }
     } else {
       log.debug("LanceDbBackend skipped vector preservation after vectorProvider probe failed");
-      return;
+      return false;
     }
 
     const rows = docs.map((d) => {
@@ -213,19 +228,21 @@ export class LanceDbBackend implements SearchBackend {
     });
 
     try {
-      if (isSearchAborted(execution)) return;
+      if (isSearchAborted(execution)) return false;
       await table.add(rows, { mode: "overwrite" });
       this.rememberVectorProviderCompatibility(
         table,
         embeddingProviderIdentity,
         rows.length > 0 && rows.every((row) => row.vectorProvider === embeddingProviderIdentity),
       );
-      if (isSearchAborted(execution)) return;
+      if (isSearchAborted(execution)) return false;
       // FTS index on the content column.
       await this.createFtsIndex(table);
       if (collection === this.collection) this.table = table;
+      return true;
     } catch (err) {
       log.debug(`LanceDbBackend update failed: ${err}`);
+      return false;
     }
   }
 

package/src/search/meilisearch-backend.test.ts

@@ -0,0 +1,148 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { MeilisearchBackend } from "./meilisearch-backend.js";
+
+// Issue #3286: update() is fail-open on every backend, so the entity-migration
+// pending marker asks updateCompleted() whether the re-index actually ran.
+test("Meilisearch updateCompleted is false whenever an enabled refresh returned early", async () => {
+  const base = { host: "http://127.0.0.1:1", collection: "openclaw-engram", memoryDir: "/nonexistent" };
+  assert.equal(await new MeilisearchBackend({ ...base, autoIndex: true }).updateCompleted(), false, "never probed: unavailable");
+  assert.equal(await new MeilisearchBackend({ host: base.host, collection: base.collection, autoIndex: true }).updateCompleted(), false, "no memory dir");
+});
+
+test("Meilisearch updateCompleted is true when autoIndex is off: nothing is pushed by configuration (issue #3286)", async () => {
+  // autoIndex defaults to off (the server is managed outside Remnic). Reporting false would
+  // make every strict namespace update fail and leave the pending marker stuck.
+  const base = { host: "http://127.0.0.1:1", collection: "openclaw-engram", memoryDir: "/nonexistent" };
+  assert.equal(await new MeilisearchBackend({ ...base, autoIndex: false }).updateCompleted(), true);
+  assert.equal(await new MeilisearchBackend({ host: base.host, collection: base.collection }).updateCompleted(), true, "default config, no memory dir, never probed");
+});
+
+/** A Meilisearch client double: waitForTask resolves with the task status, as the real 0.46 SDK does. */
+function stubClient(status: string) {
+  return {
+    async health() {},
+    async getIndex() {},
+    index: () => ({
+      async addDocuments() {
+        return { taskUid: 1 };
+      },
+      async getDocuments() {
+        return { results: [] };
+      },
+      async deleteDocuments() {
+        return { taskUid: 2 };
+      },
+    }),
+    // Resolves for failed and canceled tasks too; only a timeout rejects.
+    async waitForTask() {
+      return { status };
+    },
+  };
+}
+
+function reachableBackend(memoryDir: string, status: string): MeilisearchBackend {
+  const backend = new MeilisearchBackend({ host: "http://127.0.0.1:1", collection: "openclaw-engram", autoIndex: true, memoryDir });
+  Object.defineProperty(backend, "available", { value: true });
+  Object.defineProperty(backend, "client", { value: stubClient(status) });
+  return backend;
+}
+
+test("Meilisearch updateCompleted is true only when the add task succeeded (issue #3286)", async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "remnic-meili-completed-"));
+  try {
+    await mkdir(path.join(root, "facts"), { recursive: true });
+    await writeFile(path.join(root, "facts", "fact.md"), "---\nid: mem-meili\n---\nA fact to index.");
+    assert.equal(await reachableBackend(root, "succeeded").updateCompleted(), true);
+    for (const status of ["failed", "canceled", "enqueued", "processing"]) {
+      assert.equal(await reachableBackend(root, status).updateCompleted(), false, `a ${status} task did not index anything`);
+    }
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("Meilisearch updateCompleted is false for a reachable backend with no memory dir to index (issue #3286)", async () => {
+  const backend = new MeilisearchBackend({ host: "http://127.0.0.1:1", collection: "openclaw-engram", autoIndex: true });
+  Object.defineProperty(backend, "available", { value: true });
+  Object.defineProperty(backend, "client", { value: stubClient("succeeded") });
+  assert.equal(await backend.updateCompleted(), false);
+});
+
+test("Meilisearch updateCompleted is false when a stale-document deletion fails (issue #3286)", async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "remnic-meili-deletion-"));
+  try {
+    await mkdir(path.join(root, "facts"), { recursive: true });
+    // One live fact plus one stale server-side doc: the add succeeds, the deletion must too.
+    await writeFile(path.join(root, "facts", "fact.md"), "---\nid: mem-meili\n---\nA fact to index.");
+    const backend = new MeilisearchBackend({ host: "http://127.0.0.1:1", collection: "openclaw-engram", autoIndex: true, memoryDir: root });
+    Object.defineProperty(backend, "available", { value: true });
+    let waitForTaskCalls = 0;
+    Object.defineProperty(backend, "client", {
+      value: {
+        async health() {},
+        async getIndex() {},
+        index: () => ({
+          async addDocuments() {
+            return { taskUid: 1 };
+          },
+          async getDocuments() {
+            return { results: [{ id: "mem-meili" }, { id: "mem-stale" }] };
+          },
+          async deleteDocuments() {
+            return { taskUid: 2 };
+          },
+        }),
+        // First wait is the add (succeeded); second is the stale-doc deletion.
+        async waitForTask() {
+          waitForTaskCalls += 1;
+          return { status: waitForTaskCalls === 1 ? "succeeded" : "failed" };
+        },
+      },
+    });
+    assert.equal(await backend.updateCompleted(), false, "a failed deletion leaves a stale document searchable");
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("Meilisearch updateCompleted is false when waiting on the stale-document deletion throws (issue #3286)", async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "remnic-meili-deletion-throw-"));
+  try {
+    await mkdir(path.join(root, "facts"), { recursive: true });
+    await writeFile(path.join(root, "facts", "fact.md"), "---\nid: mem-meili\n---\nA fact to index.");
+    const backend = new MeilisearchBackend({ host: "http://127.0.0.1:1", collection: "openclaw-engram", autoIndex: true, memoryDir: root });
+    Object.defineProperty(backend, "available", { value: true });
+    let waitForTaskCalls = 0;
+    Object.defineProperty(backend, "client", {
+      value: {
+        async health() {},
+        async getIndex() {},
+        index: () => ({
+          async addDocuments() {
+            return { taskUid: 1 };
+          },
+          async getDocuments() {
+            return { results: [{ id: "mem-meili" }, { id: "mem-stale" }] };
+          },
+          async deleteDocuments() {
+            return { taskUid: 2 };
+          },
+        }),
+        // The add succeeds; waiting on the deletion rejects (a timeout in the real SDK).
+        async waitForTask() {
+          waitForTaskCalls += 1;
+          if (waitForTaskCalls > 1) throw new Error("timed out waiting for the deletion task");
+          return { status: "succeeded" };
+        },
+      },
+    });
+    assert.equal(await backend.updateCompleted(), false);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});

package/src/search/meilisearch-backend.ts

@@ -136,17 +136,30 @@ export class MeilisearchBackend implements SearchBackend {
   }
 
   async updateCollectionFromDir(collection: string, memoryDir: string, execution?: SearchExecutionOptions): Promise<void> {
-    if (!this.autoIndex) return;
-    if (!this.available) return;
-    if (isSearchAborted(execution)) return;
+    await this.refreshCollection(collection, memoryDir, execution);
+  }
+
+  async updateCompleted(execution?: SearchExecutionOptions): Promise<boolean> {
+    // autoIndex is off by default: the Meilisearch server is managed outside Remnic and
+    // nothing is pushed by configuration, so there is no re-index that could be left incomplete.
+    if (!this.autoIndex) return true;
+    if (!this.memoryDir) return false;
+    return this.refreshCollection(this.collection, this.memoryDir, execution);
+  }
+
+  /** Brings the collection up to date; true only when it ran to completion (false: aborted, unavailable, skipped or failed). */
+  private async refreshCollection(collection: string, memoryDir: string, execution?: SearchExecutionOptions): Promise<boolean> {
+    if (!this.autoIndex) return false;
+    if (!this.available) return false;
+    if (isSearchAborted(execution)) return false;
 
     try {
       const ensured = await this.ensureCollection(memoryDir, collection, execution);
-      if (ensured === "skipped" || ensured === "missing") return;
+      if (ensured === "skipped" || ensured === "missing") return false;
       const client = await this.ensureClient();
-      if (isSearchAborted(execution)) return;
+      if (isSearchAborted(execution)) return false;
       const docs = await scanMemoryDir(memoryDir);
-      if (isSearchAborted(execution)) return;
+      if (isSearchAborted(execution)) return false;
       const index = client.index(collection);
 
       const meilDocs = docs.map((d) => ({
@@ -157,10 +170,15 @@ export class MeilisearchBackend implements SearchBackend {
       }));
 
       // Upsert current docs and wait for the task to complete
-      if (isSearchAborted(execution)) return;
+      if (isSearchAborted(execution)) return false;
       const addTask = await index.addDocuments(meilDocs, { primaryKey: "id" });
-      await client.waitForTask(addTask.taskUid, { timeOutMs: this.timeoutMs });
-      if (isSearchAborted(execution)) return;
+      // waitForTask resolves with a failed or canceled task and rejects only on timeout.
+      const added = await client.waitForTask(addTask.taskUid, { timeOutMs: this.timeoutMs });
+      if (added.status !== "succeeded") {
+        log.debug(`MeilisearchBackend add task finished with status ${added.status}`);
+        return false;
+      }
+      if (isSearchAborted(execution)) return false;
 
       // Remove docs that no longer exist on disk (paginated to handle large indexes)
       const currentIds = new Set(docs.map((d) => d.docid));
@@ -170,7 +188,7 @@ export class MeilisearchBackend implements SearchBackend {
         let staleIds: string[] = [];
         let hasMore = true;
         while (hasMore) {
-          if (isSearchAborted(execution)) return;
+          if (isSearchAborted(execution)) return false;
           const page = await index.getDocuments({ limit: PAGE_SIZE, offset, fields: ["id"] });
           const results = page.results ?? [];
           for (const doc of results) {
@@ -181,15 +199,24 @@ export class MeilisearchBackend implements SearchBackend {
           hasMore = results.length === PAGE_SIZE;
         }
         if (staleIds.length > 0) {
-          if (isSearchAborted(execution)) return;
+          if (isSearchAborted(execution)) return false;
           const delTask = await index.deleteDocuments(staleIds);
-          await client.waitForTask(delTask.taskUid, { timeOutMs: this.timeoutMs });
+          // The deletion is part of completion: a stale document left searchable is not an
+          // up-to-date index, and waitForTask resolves failed/canceled tasks without throwing.
+          const deleted = await client.waitForTask(delTask.taskUid, { timeOutMs: this.timeoutMs });
+          if (deleted.status !== "succeeded") {
+            log.debug(`MeilisearchBackend stale-document deletion finished with status ${deleted.status}`);
+            return false;
+          }
         }
-      } catch {
-        // Deletion cleanup is best-effort
+      } catch (err) {
+        log.debug(`MeilisearchBackend stale-document deletion failed: ${err}`);
+        return false;
       }
+      return true;
     } catch (err) {
       log.debug(`MeilisearchBackend update failed: ${err}`);
+      return false;
     }
   }
 

package/src/search/orama-backend.test.ts

@@ -1,5 +1,5 @@
 import assert from "node:assert/strict";
-import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+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";
@@ -232,3 +232,77 @@ test("Orama rebuild gate inspects every indexed string field, not only content (
     await rm(root, { recursive: true, force: true });
   }
 });
+
+test("Orama updateCompleted reports a finished refresh, and false for an aborted one (issue #3286)", async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "remnic-orama-completed-"));
+  try {
+    await writeMemoryFact(root, "fact.md", "---\nid: mem-completed\n---\nAn indexed fact about completion.");
+    const backend = await createBackend(root, path.join(root, "orama-db"), undefined, { update: false });
+
+    assert.equal(await backend.updateCompleted({ signal: AbortSignal.abort() }), false, "an aborted refresh did not finish");
+    assert.equal((await backend.bm25Search("completion")).length, 0, "precondition: nothing was indexed");
+
+    assert.equal(await backend.updateCompleted(), true);
+    assert.equal((await backend.bm25Search("completion")).some((r) => r.docid === "mem-completed"), true);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+/** A signal that reports aborted from its Nth read on: lets a test abort a refresh at each of its checkpoints. */
+function abortingFromRead(read: number): AbortSignal {
+  const signal = new AbortController().signal;
+  let reads = 0;
+  Object.defineProperty(signal, "aborted", { get: () => ++reads >= read });
+  return signal;
+}
+
+test("Orama updateCompleted is false for a refresh aborted at any checkpoint, and true only once it persisted (issue #3286)", async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "remnic-orama-abort-sweep-"));
+  try {
+    await writeMemoryFact(root, "kept.md", "---\nid: mem-kept\n---\nA fact that stays indexed.");
+    await writeMemoryFact(root, "second.md", "---\nid: mem-second\n---\nA second fact so the diff loops iterate.");
+    const dbPath = path.join(root, "orama-db");
+    // An existing, persisted index makes the refresh walk the stored hits as well as the corpus.
+    await createBackend(root, dbPath);
+    const persistedFile = resolveOramaCollectionDbFilePath(dbPath, "openclaw-engram");
+    const before = await readFile(persistedFile);
+    await rm(path.join(root, "facts", "second.md"));
+
+    // Every abort checkpoint must report false and leave the persisted index alone;
+    // the first run that reports true must be the one that persisted the change.
+    let completedAt = 0;
+    for (let read = 1; read < 200 && completedAt === 0; read += 1) {
+      // A fresh backend per attempt: an aborted refresh leaves its in-memory edits behind,
+      // which would shift the checkpoints of the next attempt.
+      const backend = await createBackend(root, dbPath, undefined, { update: false });
+      const completed = await backend.updateCompleted({ signal: abortingFromRead(read) });
+      const persisted = await readFile(persistedFile);
+      if (completed) {
+        completedAt = read;
+        assert.notDeepEqual(persisted, before, "a refresh reporting completion persisted the index");
+      } else {
+        assert.deepEqual(persisted, before, `aborted at read ${read}: nothing may be persisted`);
+      }
+    }
+    assert.ok(completedAt > 4, `the refresh checks for abort at several points (completed only at read ${completedAt})`);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("Orama updateCompleted reports false, not a rejection, when the refresh throws (issue #3286)", async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "remnic-orama-throws-"));
+  try {
+    await writeMemoryFact(root, "fact.md", "---\nid: mem-throws\n---\nA fact.");
+    const backend = await createBackend(root, path.join(root, "orama-db"), undefined, { update: false });
+    Object.defineProperty(backend, "persistDbForCollection", {
+      value: async () => {
+        throw new Error("disk full");
+      },
+    });
+    assert.equal(await backend.updateCompleted(), false);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});

package/src/search/orama-backend.ts

@@ -178,14 +178,28 @@ export class OramaBackend implements SearchBackend {
   }
 
   async updateCollectionFromDir(collection: string, memoryDir: string, execution?: SearchExecutionOptions): Promise<void> {
-    if (isSearchAborted(execution)) return;
+    await this.refreshCollection(collection, memoryDir, execution);
+  }
+
+  async updateCompleted(execution?: SearchExecutionOptions): Promise<boolean> {
+    try {
+      return await this.refreshCollection(this.collection, this.memoryDir, execution);
+    } catch (err) {
+      log.debug(`OramaBackend update did not complete: ${err}`);
+      return false;
+    }
+  }
+
+  /** Brings the collection up to date; true only when it ran to completion (false: aborted, unavailable, skipped or failed). */
+  private async refreshCollection(collection: string, memoryDir: string, execution?: SearchExecutionOptions): Promise<boolean> {
+    if (isSearchAborted(execution)) return false;
     const db = await this.ensureDbForCollection(collection);
-    if (isSearchAborted(execution)) return;
-    if (!db) return;
+    if (isSearchAborted(execution)) return false;
+    if (!db) return false;
     const { search: oramaSearch, insert, remove, count, getByID } = this.oramaModule;
 
     const docs = await scanMemoryDir(memoryDir);
-    if (isSearchAborted(execution)) return;
+    if (isSearchAborted(execution)) return false;
     const docMap = new Map(docs.map((d) => [d.docid, d]));
     const { update: oramaUpdate } = this.oramaModule;
 
@@ -204,7 +218,7 @@ export class OramaBackend implements SearchBackend {
         limit: existingCount + 100,
       });
       for (const hit of allHits.hits) {
-        if (isSearchAborted(execution)) return;
+        if (isSearchAborted(execution)) return false;
         const storedDocument =
           typeof getByID === "function"
             ? await getByID(db, hit.id)
@@ -227,7 +241,7 @@ export class OramaBackend implements SearchBackend {
 
     // Insert new docs, update existing ones (preserving vectors since update is remove+insert)
     for (const doc of docs) {
-      if (isSearchAborted(execution)) return;
+      if (isSearchAborted(execution)) return false;
       const existing = existingDocs.get(doc.docid);
       if (existing) {
         const payload: Record<string, unknown> = {
@@ -281,13 +295,14 @@ export class OramaBackend implements SearchBackend {
       }
     }
 
-    if (isSearchAborted(execution)) return;
+    if (isSearchAborted(execution)) return false;
     await this.persistDbForCollection(db, collection);
     this.rememberVectorProviderCompatibility(
       db,
       embeddingProviderIdentity,
       allRowsCompatible,
     );
+    return true;
   }
 
   async embed(): Promise<void> {

package/src/search/port.ts

@@ -182,6 +182,13 @@ export interface SearchBackend {
    * calls remain fail-open for migration/maintenance resilience.
    */
   updateStrict?(execution?: SearchExecutionOptions): Promise<void>;
+  /**
+   * Fail-open like update(), but reports whether the index was actually brought
+   * up to date: false when it returned early (aborted, unavailable, suppressed
+   * or skipped) or failed. It never rejects for an update failure. For backends with no strict variant, so a caller
+   * that must not lose a re-index (the entity-migration pending marker) can tell.
+   */
+  updateCompleted?(execution?: SearchExecutionOptions): Promise<boolean>;
   updateCollection(collection: string, execution?: SearchExecutionOptions): Promise<void>;
   updateCollectionFromDir?(collection: string, memoryDir: string, execution?: SearchExecutionOptions): Promise<void>;
   /**

package/src/search/remote-backend.ts

@@ -84,6 +84,10 @@ export class RemoteSearchBackend implements SearchBackend {
   }
 
   async update(_execution?: SearchExecutionOptions): Promise<void> {}
+  /** The remote service owns its own indexing, so there is no local re-index that could be left incomplete. */
+  async updateCompleted(_execution?: SearchExecutionOptions): Promise<boolean> {
+    return true;
+  }
   async updateCollection(_collection: string, _execution?: SearchExecutionOptions): Promise<void> {}
   async embed(): Promise<void> {}
   async embedCollection(_collection: string): Promise<void> {}

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

@@ -10,6 +10,12 @@ import {
   rewriteProjectedEntityReferences,
   rewriteProjectedMemoryEntityReference,
 } from "../memory-projection-mutations.js";
+import {
+  listMaintenancePending,
+  settleMaintenancePending,
+  trackMaintenanceSettlement,
+  writeMaintenancePending,
+} from "./entity-migration-maintenance-pending.js";
 
 export interface EntityCanonicalIdMigrationHost {
   readonly baseDir: string;
@@ -31,7 +37,13 @@ export interface EntityCanonicalIdMigrationHost {
   invalidateColdMemoriesCache(): void;
   bumpMemoryStatusVersion(): void;
   getEntityMutationVersion(): number;
-  onEntityMigrationComplete?: () => void;
+  /**
+   * Ask search maintenance to re-index. `false` means the request was refused
+   * (e.g. the host is shutting down) and a promise settling to `false` means no
+   * pass served it: the pending markers stay so the next start retries. A
+   * promise is awaited off the startup path; `true` or nothing clears them.
+   */
+  onEntityMigrationComplete?: () => boolean | Promise<boolean> | void;
 }
 
 export async function runLegacyEntityCanonicalIdMigration(
@@ -43,15 +55,26 @@ export async function runLegacyEntityCanonicalIdMigration(
   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.
+  // references; a no-op replay must not ask search maintenance to run unless a
+  // previous run died owing it (issue #3286 pending marker).
   let rewroteReferences = false;
+  // Markers an earlier run left behind: this run owes (and may clear) exactly
+  // these plus its own, never a marker a concurrent run arms meanwhile.
+  const owed = await listMaintenancePending(host.stateDir);
+  // Arm the marker before this run rewrites anything, so a crash between the
+  // rewrite and the hook leaves it behind. Idempotent per run.
+  let armed: Promise<string> | undefined;
+  const armPending = (): Promise<string> => (armed ??= writeMaintenancePending(host.stateDir));
   const completionFingerprint = await migrateLegacyEntityCanonicalIds({
     stateDir: host.stateDir,
     entitiesDir: host.entitiesDir,
     normalizeEntityName: host.normalizeEntityName.bind(host),
     resolveEntityFilePath: host.resolveEntityFilePath.bind(host),
     readStorageSecureFile: host.readStorageSecureFile.bind(host),
-    writeStorageSecureFile: host.writeStorageSecureFile.bind(host),
+    writeStorageSecureFile: async (filePath, content, forceEncrypt) => {
+      await armPending();
+      return host.writeStorageSecureFile(filePath, content, forceEncrypt);
+    },
     isEncryptedStorageFile: host.isEncryptedFileHeader.bind(host),
     snapshotBeforeWrite: host.snapshotBeforeWrite.bind(host),
     parseEntityFile,
@@ -63,10 +86,14 @@ export async function runLegacyEntityCanonicalIdMigration(
     readArchivedMemories: host.readArchivedMemories.bind(host),
     validateMemoryScanRoots: () =>
       validateRoots(host.baseDir, host.entitiesDir, host.stateDir, host.archiveDir),
-    rewriteProjectedEntityReferences: (mappings) =>
-      rewriteProjectedEntityReferences(host.baseDir, mappings),
-    rewriteProjectedMemoryEntityReference: (memoryId, previousEntityRef, nextEntityRef) =>
-      rewriteProjectedMemoryEntityReference(host.baseDir, memoryId, previousEntityRef, nextEntityRef),
+    rewriteProjectedEntityReferences: async (mappings) => {
+      await armPending();
+      return rewriteProjectedEntityReferences(host.baseDir, mappings);
+    },
+    rewriteProjectedMemoryEntityReference: async (memoryId, previousEntityRef, nextEntityRef) => {
+      await armPending();
+      return rewriteProjectedMemoryEntityReference(host.baseDir, memoryId, previousEntityRef, nextEntityRef);
+    },
     invalidateKnowledgeIndexCache: host.invalidateKnowledgeIndexCache.bind(host),
     invalidateAllMemoriesCache: host.invalidateAllMemoriesCache.bind(host),
     invalidateColdMemoriesCache: host.invalidateColdMemoriesCache.bind(host),
@@ -76,9 +103,17 @@ export async function runLegacyEntityCanonicalIdMigration(
     },
     readMigrationFingerprint,
   } satisfies EntityCanonicalIdMigrationDependencies);
-  if (completionFingerprint !== undefined && rewroteReferences) {
+  if (completionFingerprint !== undefined && (rewroteReferences || owed.length > 0) && host.onEntityMigrationComplete) {
+    // No hook wired (e.g. a CLI-only process) skips this block, keeping the markers too.
+    const held = armed ? [...owed, await armed] : owed;
     try {
-      host.onEntityMigrationComplete?.();
+      const outcome = host.onEntityMigrationComplete();
+      const settling = settleMaintenancePending(host.stateDir, held, outcome).catch(() => {
+        log.warn("entity migration: search maintenance scheduling failed");
+      });
+      // An async hook is served after a debounce: never hold startup for it.
+      if (outcome instanceof Promise) trackMaintenanceSettlement(host.stateDir, settling);
+      else await settling;
     } catch {
       log.warn("entity migration: search maintenance scheduling failed");
     }