@remnic/core 9.3.654 → 9.3.655

package/src/orchestrator.ts

@@ -299,13 +299,16 @@ import {
 } from "./conversation-index/backend.js";
 import {
   NamespaceStorageRouter,
-  resolveNamespaceStorageRoot,
 } from "./namespaces/storage.js";
 import {
   NamespaceCatalog,
-  hasMemoryData,
-  type NamespaceRecord,
 } from "./namespaces/catalog.js";
+import {
+  planNamespaceMaintenance,
+  runNamespaceMaintenanceBatchPlan,
+  type NamespaceMaintenancePlan,
+  type NamespaceMaintenanceSkipReason,
+} from "./maintenance/namespace-planner.js";
 import {
   namespaceIdentityFromToken,
   namespaceIdentityToken,
@@ -1767,6 +1770,13 @@ export function resolvePersistedMemoryRelativePath(options: {
   return path.join(subtree, `${options.memoryId}.md`);
 }
 
+function qmdMaintenanceSkipReasonForError(error: unknown): NamespaceMaintenanceSkipReason | null {
+  const message = error instanceof Error ? error.message : String(error);
+  return /^QMD (?:update|embed) skipped by .*min-interval gate$/.test(message)
+    ? "throttled"
+    : null;
+}
+
 export class Orchestrator {
   readonly storage: StorageManager;
   private readonly storageRouter: NamespaceStorageRouter;
@@ -1914,6 +1924,7 @@ export class Orchestrator {
   private qmdMaintenancePending = false;
   private qmdMaintenanceInFlight = false;
   private lastQmdEmbedAtMs = 0;
+  private lastQmdEmbedAtMsByNamespace = new Map<string, number>();
   private lastQmdReprobeAtMs = 0;
   private tierMigrationInFlight = false;
   private lastTierMigrationRunAtMs = 0;
@@ -2417,63 +2428,31 @@ export class Orchestrator {
   }
 
   /**
-   * Namespaces that QMD maintenance (update/embed) must cover: the CONFIGURED set
-   * PLUS every dynamic namespace recorded in the catalog (NGnei, codex P2). An
-   * extraction that writes to a coding-scoped/dynamic namespace (not in
-   * defaultNamespace/sharedNamespace/namespacePolicies) is only made discoverable
-   * via the catalog; if maintenance embeds only `configuredNamespaces()`, that
-   * namespace's QMD collection is never updated/embedded after writes and
-   * recall/search stays stale or empty until it is manually configured. We union in
-   * the catalog's namespaces so maintenance keeps dynamic namespaces fresh.
-   * `updateNamespaces`/`embedNamespaces` already trim, dedup, and skip
-   * unavailable/missing collections, so extra names are filtered safely. A catalog
-   * read failure must never break maintenance — fall back to the configured set.
+   * Shared namespace maintenance planner (issue #1500). This extends the
+   * #1499 catalog-union QMD helper into a reusable contract: configured
+   * namespaces are always considered, dynamic catalog namespaces are admitted
+   * only when their live router root still matches real memory data, and branch
+   * namespaces are opt-in. Recurring jobs use the per-cycle budget; startup and
+   * recovery discovery paths use the same safety filters without that cycle
+   * budget so every live namespace is ensured/synced.
    */
-  private async maintenanceNamespaces(): Promise<string[]> {
-    const configured = this.configuredNamespaces();
-    if (!this.namespaceCatalog.enabled) return configured;
-    const configuredSet = new Set(configured);
-    let cataloged: string[] = [];
-    try {
-      const records = await this.namespaceCatalog.listNamespaces();
-      const safeRecords = await Promise.all(
-        records.map(async (record) => {
-          const namespace = record.namespace.trim();
-          if (!namespace || configuredSet.has(namespace)) return null;
-          return (await this.isCatalogedMaintenanceRootLive(record))
-            ? namespace
-            : null;
-        }),
-      );
-      cataloged = safeRecords.filter(
-        (namespace): namespace is string => namespace !== null,
-      );
-    } catch {
-      // Best-effort: a catalog read failure must not break QMD maintenance.
-      cataloged = [];
-    }
-    return Array.from(
-      new Set(
-        [...configured, ...cataloged].map((value) => value.trim()).filter(Boolean),
-      ),
-    );
+  private async namespaceMaintenancePlan(jobName: string): Promise<NamespaceMaintenancePlan> {
+    return planNamespaceMaintenance(this.config, {
+      jobName,
+      catalog: this.namespaceCatalog,
+    });
   }
 
-  private async isCatalogedMaintenanceRootLive(
-    record: NamespaceRecord,
-  ): Promise<boolean> {
-    if (typeof record.storageDir !== "string" || record.storageDir.length === 0) {
-      return false;
-    }
-    try {
-      const liveRoot = await resolveNamespaceStorageRoot(this.config, record.namespace);
-      if (path.resolve(liveRoot) !== path.resolve(record.storageDir)) {
-        return false;
-      }
-      return hasMemoryData(liveRoot);
-    } catch {
-      return false;
-    }
+  private async maintenanceNamespaces(
+    jobName = "qmd",
+    budgetMode: "cycle" | "unbounded" = "unbounded",
+  ): Promise<string[]> {
+    const plan = await planNamespaceMaintenance(this.config, {
+      jobName,
+      catalog: this.namespaceCatalog,
+      budgetMode,
+    });
+    return plan.namespaces.map((candidate) => candidate.namespace);
   }
 
   private buildConfiguredQmdSearchOptions(
@@ -13337,17 +13316,69 @@ export class Orchestrator {
     try {
       if (this.config.namespacesEnabled) {
         // Include cataloged dynamic namespaces, not just the configured set
-        // (NGnei) — resolve once and reuse for both update and embed.
-        const maintenanceNamespaces = await this.maintenanceNamespaces();
-        await this.namespaceSearchRouter.updateNamespaces(maintenanceNamespaces);
+        // (NGnei), but run through the namespace-aware maintenance planner so
+        // each namespace is budgeted, lock-protected, and status-recorded
+        // independently (issue #1500).
+        const plan = await this.namespaceMaintenancePlan("qmd");
         const now = Date.now();
-        if (
-          this.config.qmdAutoEmbedEnabled &&
-          now - this.lastQmdEmbedAtMs >= this.config.qmdEmbedMinIntervalMs
-        ) {
-          await this.namespaceSearchRouter.embedNamespaces(maintenanceNamespaces);
+        const lastEmbedAtByNamespace =
+          this.lastQmdEmbedAtMsByNamespace ?? (this.lastQmdEmbedAtMsByNamespace = new Map());
+        const dueEmbedNamespaces = (namespaces: string[]): string[] => {
+          if (!this.config.qmdAutoEmbedEnabled) return [];
+          return namespaces.filter(
+            (namespace) =>
+              now - (lastEmbedAtByNamespace.get(namespace) ?? 0) >= this.config.qmdEmbedMinIntervalMs,
+          );
+        };
+        const markEmbedded = (namespaces: string[]): void => {
+          if (namespaces.length === 0) return;
+          for (const namespace of namespaces) {
+            lastEmbedAtByNamespace.set(namespace, now);
+          }
           this.lastQmdEmbedAtMs = now;
-        }
+        };
+        await runNamespaceMaintenanceBatchPlan(
+          this.config,
+          plan,
+          async (candidates) => {
+            const namespaces = candidates.map((candidate) => candidate.namespace);
+            const embedNamespaces = dueEmbedNamespaces(namespaces);
+            let result: Awaited<ReturnType<NamespaceSearchRouter["updateNamespacesDetailed"]>>;
+            try {
+              result = await this.namespaceSearchRouter.updateNamespacesDetailed(
+                namespaces,
+                undefined,
+                { strict: true },
+              );
+            } catch (error) {
+              if (
+                embedNamespaces.length > 0 &&
+                qmdMaintenanceSkipReasonForError(error) === "throttled"
+              ) {
+                await this.namespaceSearchRouter.embedNamespaces(embedNamespaces, { strict: true });
+                markEmbedded(embedNamespaces);
+              }
+              throw error;
+            }
+            if (result.backendCount <= 0) {
+              throw new Error("no eligible QMD backend for selected namespaces");
+            }
+            if (result.eligibleNamespaces.length !== namespaces.length) {
+              const eligible = new Set(result.eligibleNamespaces);
+              const missing = namespaces.filter((namespace) => !eligible.has(namespace));
+              throw new Error(`QMD backend ineligible for selected namespaces (${missing.length})`);
+            }
+            if (embedNamespaces.length > 0) {
+              await this.namespaceSearchRouter.embedNamespaces(embedNamespaces, { strict: true });
+              markEmbedded(embedNamespaces);
+            }
+            return { itemCount: result.backendCount };
+          },
+          this.namespaceCatalog,
+          {
+            skipReasonForError: qmdMaintenanceSkipReasonForError,
+          },
+        );
       } else {
         await this.qmd.update();
         const now = Date.now();

package/src/qmd-client.test.ts

@@ -70,6 +70,65 @@ function captureSubprocessArgs(client: QmdClient): string[][] {
   return calls;
 }
 
+test("updateStrict respects QMD update min-interval throttles", async () => {
+  const client = new QmdClient("memories", 3, { updateMinIntervalMs: 60_000 });
+  client.resetUpdateThrottles();
+  const calls = captureSubprocessArgs(client);
+
+  try {
+    await client.updateStrict();
+    await assert.rejects(
+      () => client.updateStrict(),
+      /QMD update skipped by min-interval gate|QMD update skipped by global min-interval gate/,
+    );
+  } finally {
+    client.resetUpdateThrottles();
+  }
+
+  assert.equal(calls.length, 1);
+});
+
+test("embedCollectionStrict rejects QMD embed subprocess failures", async () => {
+  const client = new QmdClient("memories", 3, { updateMinIntervalMs: 60_000 });
+  client.resetUpdateThrottles();
+  const internals = client as unknown as SubprocessInternals;
+  const calls: string[][] = [];
+  internals.available = true;
+  internals.runQmdCommand = async (args: string[]) => {
+    calls.push(args);
+    throw new Error("embed subprocess failed");
+  };
+
+  try {
+    await assert.rejects(
+      () => client.embedCollectionStrict("memories--project"),
+      /embed subprocess failed/,
+    );
+  } finally {
+    client.resetUpdateThrottles();
+  }
+
+  assert.deepEqual(calls, [["embed", "-c", "memories--project"]]);
+});
+
+test("embedCollectionStrict respects QMD embed min-interval throttles", async () => {
+  const client = new QmdClient("memories", 3, { updateMinIntervalMs: 60_000 });
+  client.resetUpdateThrottles();
+  const calls = captureSubprocessArgs(client);
+
+  try {
+    await client.embedCollectionStrict("memories--project");
+    await assert.rejects(
+      () => client.embedCollectionStrict("memories--project"),
+      /QMD embed skipped by per-collection min-interval gate/,
+    );
+  } finally {
+    client.resetUpdateThrottles();
+  }
+
+  assert.equal(calls.length, 1);
+});
+
 test("ensureCollection treats cancelled auto-create as unknown", async () => {
   const client = new QmdClient("memories", 3, {});
   const internals = client as unknown as SubprocessInternals & {

package/src/qmd.ts

@@ -1232,9 +1232,14 @@ export class QmdClient implements SearchBackend {
   resetUpdateThrottles(): void {
     this._lastUpdateFailAtMs = null;
     this.lastUpdateRunAtMs = null;
+    this.lastEmbedFailAtMs = null;
     const gs = getGlobalQmdState();
     gs.lastGlobalUpdateRunAtMs = null;
     gs.lastGlobalUpdateFailAtMs = null;
+    gs.lastGlobalEmbedRunAtMs = null;
+    gs.lastGlobalEmbedFailAtMs = null;
+    gs.lastEmbedByCollectionMs = {};
+    gs.lastEmbedFailByCollectionMs = {};
   }
 
   private readonly updateTimeoutMs: number;
@@ -2493,6 +2498,14 @@ export class QmdClient implements SearchBackend {
     );
   }
 
+  async updateStrict(execution?: SearchExecutionOptions): Promise<void> {
+    await this.runUpdateForCollection(
+      this.collection,
+      { perCollectionThrottle: false, strict: true },
+      execution?.signal,
+    );
+  }
+
   async updateCollection(
     collection: string,
     execution?: SearchExecutionOptions,
@@ -2510,7 +2523,7 @@ export class QmdClient implements SearchBackend {
   ): Promise<void> {
     await this.runUpdateForCollection(
       collection,
-      { perCollectionThrottle: true, strict: true },
+      { perCollectionThrottle: true, strict: true, force: true },
       execution?.signal,
     );
   }
@@ -2521,7 +2534,7 @@ export class QmdClient implements SearchBackend {
 
   private async runUpdateForCollection(
     collection: string,
-    options: { perCollectionThrottle: boolean; strict?: boolean },
+    options: { perCollectionThrottle: boolean; strict?: boolean; force?: boolean },
     signal?: AbortSignal,
   ): Promise<void> {
     if (this.available === false) {
@@ -2539,12 +2552,13 @@ export class QmdClient implements SearchBackend {
     }
     const globalState = getGlobalQmdState();
     const now = Date.now();
-    if (!options.strict && options.perCollectionThrottle) {
+    if (!options.force && options.perCollectionThrottle) {
       if (
         globalState.lastGlobalUpdateFailAtMs &&
         now - globalState.lastGlobalUpdateFailAtMs < QMD_UPDATE_BACKOFF_MS
       ) {
         log.debug("QMD update: suppressed by global failure backoff");
+        if (options.strict) throw new Error("QMD update skipped by global failure backoff");
         return;
       }
       const lastCollectionRun = globalState.lastUpdateByCollectionMs[name];
@@ -2553,6 +2567,7 @@ export class QmdClient implements SearchBackend {
         now - lastCollectionRun < this.updateMinIntervalMs
       ) {
         log.debug(`QMD update: suppressed by per-collection min-interval gate (${name})`);
+        if (options.strict) throw new Error("QMD update skipped by per-collection min-interval gate");
         return;
       }
       const lastCollectionFail = globalState.lastUpdateFailByCollectionMs[name];
@@ -2561,14 +2576,16 @@ export class QmdClient implements SearchBackend {
         now - lastCollectionFail < QMD_UPDATE_BACKOFF_MS
       ) {
         log.debug(`QMD update: suppressed by per-collection failure backoff (${name})`);
+        if (options.strict) throw new Error("QMD update skipped by per-collection failure backoff");
         return;
       }
-    } else if (!options.strict) {
+    } else if (!options.force) {
       if (
         this.lastUpdateRunAtMs &&
         now - this.lastUpdateRunAtMs < this.updateMinIntervalMs
       ) {
         log.debug("QMD update: suppressed due to min-interval gate");
+        if (options.strict) throw new Error("QMD update skipped by min-interval gate");
         return;
       }
       if (
@@ -2576,6 +2593,7 @@ export class QmdClient implements SearchBackend {
         now - this._lastUpdateFailAtMs < QMD_UPDATE_BACKOFF_MS
       ) {
         log.debug("QMD update: suppressed due to recent failures (backoff)");
+        if (options.strict) throw new Error("QMD update skipped by recent failure backoff");
         return;
       }
       if (
@@ -2583,6 +2601,7 @@ export class QmdClient implements SearchBackend {
         now - globalState.lastGlobalUpdateRunAtMs < this.updateMinIntervalMs
       ) {
         log.debug("QMD update: suppressed by global min-interval gate");
+        if (options.strict) throw new Error("QMD update skipped by global min-interval gate");
         return;
       }
       if (
@@ -2590,6 +2609,7 @@ export class QmdClient implements SearchBackend {
         now - globalState.lastGlobalUpdateFailAtMs < QMD_UPDATE_BACKOFF_MS
       ) {
         log.debug("QMD update: suppressed by global failure backoff");
+        if (options.strict) throw new Error("QMD update skipped by global failure backoff");
         return;
       }
     }
@@ -2633,117 +2653,137 @@ export class QmdClient implements SearchBackend {
   }
 
   async embed(): Promise<void> {
-    if (this.available === false) return;
-    const globalState = getGlobalQmdState();
-    if (
-      this.lastEmbedFailAtMs &&
-      Date.now() - this.lastEmbedFailAtMs < QMD_EMBED_BACKOFF_MS
-    ) {
-      log.debug("QMD embed: suppressed due to recent failures (backoff)");
+    await this.runEmbedForCollection(this.collection, { perCollectionThrottle: false });
+  }
+
+  async embedStrict(): Promise<void> {
+    await this.runEmbedForCollection(this.collection, { perCollectionThrottle: false, strict: true });
+  }
+
+  async embedCollection(collection: string): Promise<void> {
+    await this.runEmbedForCollection(collection, { perCollectionThrottle: true });
+  }
+
+  async embedCollectionStrict(collection: string): Promise<void> {
+    await this.runEmbedForCollection(collection, { perCollectionThrottle: true, strict: true });
+  }
+
+  private async runEmbedForCollection(
+    collection: string,
+    options: { perCollectionThrottle: boolean; strict?: boolean },
+  ): Promise<void> {
+    if (this.available === false) {
+      if (options.strict) throw new Error("QMD unavailable");
       return;
     }
-    if (
-      globalState.lastGlobalEmbedRunAtMs &&
-      Date.now() - globalState.lastGlobalEmbedRunAtMs < this.updateMinIntervalMs
-    ) {
-      log.debug("QMD embed: suppressed by global min-interval gate");
+    const name = collection.trim();
+    if (!name) {
+      if (options.strict) throw new Error("QMD collection name is required");
       return;
     }
-    if (
-      globalState.lastGlobalEmbedFailAtMs &&
-      Date.now() - globalState.lastGlobalEmbedFailAtMs < QMD_EMBED_BACKOFF_MS
-    ) {
-      log.debug("QMD embed: suppressed by global failure backoff");
-      return;
+    const globalState = getGlobalQmdState();
+    const now = Date.now();
+    if (options.perCollectionThrottle) {
+      if (
+        globalState.lastGlobalEmbedFailAtMs &&
+        now - globalState.lastGlobalEmbedFailAtMs < QMD_EMBED_BACKOFF_MS
+      ) {
+        log.debug(`QMD embed: suppressed by global failure backoff (${name})`);
+        if (options.strict) throw new Error("QMD embed skipped by global failure backoff");
+        return;
+      }
+      const lastCollectionRun = globalState.lastEmbedByCollectionMs[name];
+      if (
+        Number.isFinite(lastCollectionRun) &&
+        now - lastCollectionRun < this.updateMinIntervalMs
+      ) {
+        log.debug(`QMD embed: suppressed by per-collection min-interval gate (${name})`);
+        if (options.strict) throw new Error("QMD embed skipped by per-collection min-interval gate");
+        return;
+      }
+      const lastCollectionFail = globalState.lastEmbedFailByCollectionMs[name];
+      if (
+        Number.isFinite(lastCollectionFail) &&
+        now - lastCollectionFail < QMD_EMBED_BACKOFF_MS
+      ) {
+        log.debug(`QMD embed: suppressed by per-collection failure backoff (${name})`);
+        if (options.strict) throw new Error("QMD embed skipped by per-collection failure backoff");
+        return;
+      }
+    } else {
+      if (
+        this.lastEmbedFailAtMs &&
+        now - this.lastEmbedFailAtMs < QMD_EMBED_BACKOFF_MS
+      ) {
+        log.debug("QMD embed: suppressed due to recent failures (backoff)");
+        if (options.strict) throw new Error("QMD embed skipped by recent failure backoff");
+        return;
+      }
+      if (
+        globalState.lastGlobalEmbedRunAtMs &&
+        now - globalState.lastGlobalEmbedRunAtMs < this.updateMinIntervalMs
+      ) {
+        log.debug("QMD embed: suppressed by global min-interval gate");
+        if (options.strict) throw new Error("QMD embed skipped by global min-interval gate");
+        return;
+      }
+      if (
+        globalState.lastGlobalEmbedFailAtMs &&
+        now - globalState.lastGlobalEmbedFailAtMs < QMD_EMBED_BACKOFF_MS
+      ) {
+        log.debug("QMD embed: suppressed by global failure backoff");
+        if (options.strict) throw new Error("QMD embed skipped by global failure backoff");
+        return;
+      }
     }
     try {
       const startedAtMs = Date.now();
-      await this.runQmdCommand(this.buildEmbedArgs(this.collection), 300_000);
+      await this.runQmdCommand(this.buildEmbedArgs(name), 300_000);
       const durationMs = Date.now() - startedAtMs;
       if (this.slowLog?.enabled && durationMs >= this.slowLog.thresholdMs) {
         log.warn(`SLOW QMD embed: durationMs=${durationMs}`);
       }
-      globalState.lastGlobalEmbedRunAtMs = Date.now();
-      log.debug("QMD embed completed");
-    } catch (err) {
-      if (isVectorDimensionMismatchError(err)) {
-        try {
-          log.warn("QMD embed hit a vector dimension mismatch; retrying with force re-embed");
-          await this.runQmdCommand(this.buildEmbedArgs(this.collection, true), 300_000);
-          globalState.lastGlobalEmbedRunAtMs = Date.now();
-          this.lastEmbedFailAtMs = null;
-          globalState.lastGlobalEmbedFailAtMs = null;
-          log.warn("QMD embed recovered by forcing a full vector rebuild");
-          return;
-        } catch (retryErr) {
-          const retryMsg = retryErr instanceof Error ? retryErr.message : String(retryErr);
-          log.warn(`QMD force re-embed failed after dimension mismatch: ${retryMsg}`);
-        }
-      }
-      const now = Date.now();
-      this.lastEmbedFailAtMs = now;
-      globalState.lastGlobalEmbedFailAtMs = now;
-      const msg = err instanceof Error ? err.message : String(err);
-      log.warn(`QMD embed failed: ${msg}`);
-    }
-  }
-
-  async embedCollection(collection: string): Promise<void> {
-    if (this.available === false) return;
-    const name = collection.trim();
-    if (!name) return;
-    const globalState = getGlobalQmdState();
-    const now = Date.now();
-    if (
-      globalState.lastGlobalEmbedFailAtMs &&
-      now - globalState.lastGlobalEmbedFailAtMs < QMD_EMBED_BACKOFF_MS
-    ) {
-      log.debug(`QMD embed: suppressed by global failure backoff (${name})`);
-      return;
-    }
-    const lastCollectionRun = globalState.lastEmbedByCollectionMs[name];
-    if (
-      Number.isFinite(lastCollectionRun) &&
-      now - lastCollectionRun < this.updateMinIntervalMs
-    ) {
-      log.debug(`QMD embed: suppressed by per-collection min-interval gate (${name})`);
-      return;
-    }
-    const lastCollectionFail = globalState.lastEmbedFailByCollectionMs[name];
-    if (
-      Number.isFinite(lastCollectionFail) &&
-      now - lastCollectionFail < QMD_EMBED_BACKOFF_MS
-    ) {
-      log.debug(`QMD embed: suppressed by per-collection failure backoff (${name})`);
-      return;
-    }
-    try {
-      await this.runQmdCommand(this.buildEmbedArgs(name), 300_000);
       const at = Date.now();
-      globalState.lastEmbedByCollectionMs[name] = at;
+      if (options.perCollectionThrottle) {
+        globalState.lastEmbedByCollectionMs[name] = at;
+      }
       globalState.lastGlobalEmbedRunAtMs = at;
+      log.debug(`QMD embed completed for collection=${name}`);
     } catch (err) {
+      let failure: unknown = err;
       if (isVectorDimensionMismatchError(err)) {
         try {
           log.warn(`QMD embed for collection ${name} hit a vector dimension mismatch; retrying with force re-embed`);
           await this.runQmdCommand(this.buildEmbedArgs(name, true), 300_000);
           const recoveredAt = Date.now();
-          globalState.lastEmbedByCollectionMs[name] = recoveredAt;
+          if (options.perCollectionThrottle) {
+            globalState.lastEmbedByCollectionMs[name] = recoveredAt;
+            delete globalState.lastEmbedFailByCollectionMs[name];
+          } else {
+            this.lastEmbedFailAtMs = null;
+          }
           globalState.lastGlobalEmbedRunAtMs = recoveredAt;
-          delete globalState.lastEmbedFailByCollectionMs[name];
           globalState.lastGlobalEmbedFailAtMs = null;
           log.warn(`QMD embed for collection ${name} recovered by forcing a full vector rebuild`);
           return;
         } catch (retryErr) {
+          failure = retryErr;
           const retryMsg = retryErr instanceof Error ? retryErr.message : String(retryErr);
           log.warn(`QMD force re-embed failed for collection ${name}: ${retryMsg}`);
         }
       }
       const at = Date.now();
-      globalState.lastEmbedFailByCollectionMs[name] = at;
+      if (options.perCollectionThrottle) {
+        globalState.lastEmbedFailByCollectionMs[name] = at;
+      } else {
+        this.lastEmbedFailAtMs = at;
+      }
       globalState.lastGlobalEmbedFailAtMs = at;
-      const msg = err instanceof Error ? err.message : String(err);
+      const msg = failure instanceof Error ? failure.message : String(failure);
       log.warn(`QMD embed failed for collection ${name}: ${msg}`);
+      if (options.strict) {
+        throw failure;
+      }
     }
   }
 

package/src/search/port.ts

@@ -81,6 +81,12 @@ export interface SearchBackend {
 
   // ── Maintenance ──
   update(execution?: SearchExecutionOptions): Promise<void>;
+  /**
+   * Optional strict refresh used by callers that must know whether the backend
+   * was actually refreshed before writing success markers. Ordinary update
+   * calls remain fail-open for migration/maintenance resilience.
+   */
+  updateStrict?(execution?: SearchExecutionOptions): Promise<void>;
   updateCollection(collection: string, execution?: SearchExecutionOptions): Promise<void>;
   updateCollectionFromDir?(collection: string, memoryDir: string, execution?: SearchExecutionOptions): Promise<void>;
   /**
@@ -96,7 +102,17 @@ export interface SearchBackend {
    */
   updateCollectionStrict?(collection: string, execution?: SearchExecutionOptions): Promise<void>;
   embed(): Promise<void>;
+  /**
+   * Optional strict embed used by callers that must know vectors were actually
+   * refreshed before writing success markers.
+   */
+  embedStrict?(): Promise<void>;
   embedCollection(collection: string): Promise<void>;
+  /**
+   * Optional strict collection embed used by callers that must know vectors were
+   * actually refreshed before writing success markers.
+   */
+  embedCollectionStrict?(collection: string): Promise<void>;
 
   // ── Collection management ──
   /**

package/src/types.ts

@@ -1216,6 +1216,18 @@ export interface PluginConfig {
   // QMD maintenance (debounced singleflight)
   qmdMaintenanceEnabled: boolean;
   qmdMaintenanceDebounceMs: number;
+  /**
+   * Namespace-aware maintenance fanout (issue #1500). When namespaces are
+   * enabled, background maintenance jobs use the rebuildable namespace catalog
+   * to discover dynamic project/team namespaces rather than only processing the
+   * configured default/shared/policy set.
+   */
+  maintenanceNamespaceFanoutEnabled: boolean;
+  maintenanceMaxNamespacesPerCycle: number;
+  maintenanceIncludeProjectNamespaces: boolean;
+  maintenanceIncludeBranchNamespaces: boolean;
+  maintenanceIncludeTeamProjectNamespaces: boolean;
+  maintenanceNamespaceLockStaleMs: number;
   qmdAutoEmbedEnabled: boolean;
   qmdEmbedMinIntervalMs: number;
   qmdUpdateTimeoutMs: number;