@remnic/core 9.3.727 → 9.3.729

package/src/orchestrator.ts

@@ -99,6 +99,7 @@ import {
 } from "./fallback-llm.js";
 import { MaintenanceScheduler } from "./orchestration/maintenance.js";
 import { TierMigrationCoordinator } from "./orchestration/tier-migration-coordinator.js";
+import { ExtractionQueueCoordinator } from "./orchestration/extraction-queue-coordinator.js";
 import {
   runLiveConnectorsOnce,
   type LiveConnectorsRunSummary,
@@ -171,7 +172,6 @@ import {
 import { SessionObserverState } from "./session-observer-state.js";
 import {
   abortError as sharedAbortError,
-  isAbortError,
   throwIfAborted as sharedThrowIfAborted,
 } from "./abort-error.js";
 import { CODEX_THREAD_KEY_PREFIX } from "./thread-key.js";
@@ -269,8 +269,10 @@ import { tryDirectAnswer, type DirectAnswerSources } from "./direct-answer-wirin
 import {
   resolveCapabilities,
   resolveGraphConstructionCapabilities,
+  resolveMemoryLifecycleCapabilities,
   type CapabilitySet,
   type GraphConstructionCapabilitySet,
+  type MemoryLifecycleCapabilitySet,
 } from "./capabilities.js";
 import { DEFAULT_TAXONOMY } from "./taxonomy/index.js";
 import {
@@ -2019,10 +2021,14 @@ export class Orchestrator {
     suppressedReasonCounts: Record<string, number>;
   } = { detected: 0, queued: 0, autoApplied: 0, suppressedReasonCounts: {} };
 
-  // Background serial queue for extractions (agent_end optimization)
-  // Queue stores promises that resolve when extraction should run
-  private extractionQueue: Array<() => Promise<void>> = [];
-  private queueProcessing = false;
+  /**
+   * Background serial extraction queue coordinator (issue #1526 — moved
+   * from inline `extractionQueue`/`queueProcessing` fields). Owns queue
+   * state + scheduling + the serial drain + failure classification; the
+   * orchestrator builds each task closure in `queueBufferedExtraction` and
+   * hands it to `enqueue`.
+   */
+  readonly extractionQueueCoordinator: ExtractionQueueCoordinator;
   private heartbeatObserverChains = new Map<string, Promise<void>>();
   private recentExtractionFingerprints = new Map<string, number>();
   private readonly consolidationObservers = new Set<
@@ -2989,6 +2995,8 @@ export class Orchestrator {
       namespaceSearchRouter: this.namespaceSearchRouter,
       namespaceCatalog: this.namespaceCatalog,
     });
+    // Issue #1526: background extraction queue lives on its own coordinator.
+    this.extractionQueueCoordinator = new ExtractionQueueCoordinator();
     const conversationIndexRuntime = createConversationIndexRuntime(config, {
       getQmd: () => this.conversationQmd,
       getFaiss: () => this.conversationFaiss,
@@ -3094,9 +3102,10 @@ export class Orchestrator {
     );
     // BoxBuilders are created per-namespace on first use in runExtraction().
 
+    const lifecycleCaps = resolveMemoryLifecycleCapabilities(config);
     // Temporal Memory Tree (v8.2) — lazy build during consolidation
     this.tmtBuilder = new TmtBuilder(config.memoryDir, {
-      temporalMemoryTreeEnabled: config.temporalMemoryTreeEnabled,
+      temporalMemoryTreeEnabled: lifecycleCaps.temporalMemoryTree,
       tmtHourlyMinMemories: config.tmtHourlyMinMemories,
       tmtSummaryMaxTokens: config.tmtSummaryMaxTokens,
     });
@@ -3654,6 +3663,7 @@ export class Orchestrator {
   }
 
   private async deferredInitialize(signal: AbortSignal): Promise<void> {
+    const lifecycleCaps = resolveMemoryLifecycleCapabilities(this.config);
 
     // Sync QMD index with current disk state so recall finds recently-written
     // facts. Without this, the index stays stale from the last extraction-
@@ -3707,7 +3717,7 @@ export class Orchestrator {
           }),
       );
     }
-    if (this.config.embeddingFallbackEnabled) {
+    if (resolveMemoryLifecycleCapabilities(this.config).embeddingFallback) {
       warmupPromises.push(
         this.embeddingFallback
           .isAvailable()
@@ -3792,7 +3802,7 @@ export class Orchestrator {
     // sweep (capped at 50 demotions) so the hot tier isn't flooded on the
     // first real cron pass. Non-fatal — a failure here must not break init.
     if (signal.aborted) return;
-    if (this.config.lifecyclePolicyEnabled && this.config.qmdTierMigrationEnabled) {
+    if (lifecycleCaps.lifecyclePolicy && this.config.qmdTierMigrationEnabled) {
       try {
         const { runFirstStartMigration } = await import(
           "./maintenance/first-start-migration.js"
@@ -4117,6 +4127,7 @@ export class Orchestrator {
    * default storage.
    */
   async runLifecyclePolicyFanout(): Promise<NamespaceMaintenanceSummary> {
+    const lifecycleCaps = resolveMemoryLifecycleCapabilities(this.config);
     return this.runNamespaceMaintenanceFanoutForJob(
       "lifecycle",
       async (ctx) => {
@@ -4125,7 +4136,7 @@ export class Orchestrator {
         const assessed = await this.runLifecyclePolicyPass(corpus, storage);
         return { itemCount: assessed };
       },
-      { enabled: this.config.lifecyclePolicyEnabled },
+      { enabled: lifecycleCaps.lifecyclePolicy },
     );
   }
 
@@ -4715,15 +4726,8 @@ export class Orchestrator {
   }
 
   async waitForExtractionIdle(timeoutMs: number = 60_000): Promise<boolean> {
-    const started = Date.now();
-    while (this.queueProcessing || this.extractionQueue.length > 0) {
-      if (Date.now() - started > timeoutMs) {
-        log.warn(`waitForExtractionIdle timed out after ${timeoutMs}ms`);
-        return false;
-      }
-      await new Promise((resolve) => setTimeout(resolve, 50));
-    }
-    return true;
+    // Issue #1526: queue state + idle wait moved to ExtractionQueueCoordinator.
+    return this.extractionQueueCoordinator.waitForIdle(timeoutMs);
   }
 
   async waitForConsolidationIdle(timeoutMs: number = 60_000): Promise<boolean> {
@@ -7438,6 +7442,7 @@ export class Orchestrator {
     options: RecallInvocationOptions = {},
     caps: CapabilitySet = resolveCapabilities(this.config),
     graphCaps: GraphConstructionCapabilitySet = resolveGraphConstructionCapabilities(this.config),
+    lifecycleCaps: MemoryLifecycleCapabilitySet = resolveMemoryLifecycleCapabilities(this.config),
   ): Promise<string> {
     const recallStart = Date.now();
     // Backend degradations observed by this recall's QMD searches (#1536):
@@ -10845,9 +10850,9 @@ export class Orchestrator {
     if (
       this.isRecallSectionEnabled(
         "temporal-memory-tree",
-        this.config.temporalMemoryTreeEnabled === true,
+        lifecycleCaps.temporalMemoryTree,
       ) &&
-      this.config.temporalMemoryTreeEnabled &&
+      lifecycleCaps.temporalMemoryTree &&
       recallMode !== "minimal" &&
       (recallMode as RecallPlanMode) !== "no_recall"
     ) {
@@ -11707,7 +11712,7 @@ export class Orchestrator {
           // Using the shared gate fixes both Finding 2 and Finding 3 from
           // PR #402 (round 6).
           const supersessionOptions = {
-            enabled: this.config.temporalSupersessionEnabled,
+            enabled: lifecycleCaps.temporalSupersession,
             includeInRecall: this.config.temporalSupersessionIncludeInRecall,
           };
           // Cursor Medium on PR #713: when `as_of` is active, the
@@ -13159,7 +13164,7 @@ export class Orchestrator {
       }, remainingMs);
     }
 
-    this.extractionQueue.push(async () => {
+    this.extractionQueueCoordinator.enqueue(async () => {
       if (settled) return;
       if (
         typeof extractionDeadlineMs === "number" &&
@@ -13190,13 +13195,6 @@ export class Orchestrator {
       }
     });
 
-    if (!this.queueProcessing) {
-      this.queueProcessing = true;
-      this.processQueue().catch((err) => {
-        this.logExtractionQueueFailure(err, "processor");
-        this.queueProcessing = false;
-      });
-    }
     log.debug(`queued extraction from ${reason}`);
   }
 
@@ -13231,7 +13229,8 @@ export class Orchestrator {
     turns: BufferTurn[],
     options: { commit?: boolean; bufferKey?: string } = {},
   ): boolean {
-    if (!this.config.extractionDedupeEnabled) return true;
+    const lifecycleCaps = resolveMemoryLifecycleCapabilities(this.config);
+    if (!lifecycleCaps.extractionDedupe) return true;
     if (!Array.isArray(turns) || turns.length === 0) return false;
 
     const bufferKey = options.bufferKey ?? turns[0]?.sessionKey ?? "default";
@@ -13263,62 +13262,6 @@ export class Orchestrator {
     return true;
   }
 
-  /**
-   * Background serial queue processor.
-   * Processes extractions one at a time to avoid race conditions.
-   * Called automatically when items are queued.
-   */
-  private async processQueue(): Promise<void> {
-    while (this.extractionQueue.length > 0) {
-      const task = this.extractionQueue.shift();
-      if (task) {
-        try {
-          await task();
-        } catch (err) {
-          this.logExtractionQueueFailure(err, "task");
-        }
-      }
-    }
-
-    this.queueProcessing = false;
-  }
-
-  /**
-   * Classify + log a failure from either the per-task catch inside
-   * `processQueue()` or the outer `processQueue().catch(...)` in
-   * `queueBufferedExtraction()`.  Issue #549: `throwIfRecallAborted`
-   * (used throughout `runExtraction`) raises an Error whose `name` is
-   * `"AbortError"`.  That path fires when `before_reset` aborts a
-   * queued task to avoid duplicate extraction — it is intentional
-   * cancellation, not a failure.  Downgrading the log to debug
-   * prevents spurious `error`-level lines that routinely appear
-   * right next to a successful `persisted: N facts, M entities` log
-   * and that confuse operators into thinking extraction is broken.
-   * Genuine extraction failures (network, parse, I/O) still log at
-   * `error`.
-   *
-   * Source differentiates the two call sites so the log message
-   * names the right layer (`task` vs `processor`).
-   */
-  private logExtractionQueueFailure(
-    err: unknown,
-    source: "task" | "processor",
-  ): void {
-    const aborted =
-      source === "task"
-        ? "background extraction task aborted (session transition)"
-        : "background extraction queue processor aborted (session transition)";
-    const failed =
-      source === "task"
-        ? "background extraction task failed"
-        : "background extraction queue processor failed";
-    if (isAbortError(err)) {
-      log.debug(aborted);
-    } else {
-      log.error(failed, err);
-    }
-  }
-
   /**
    * Passive correction capture (issue #1581) — detects corrections expressed
    * passively in conversation turns and routes them to the Correction Contract
@@ -14090,6 +14033,7 @@ export class Orchestrator {
     /** Verbatim source turn text the facts were extracted from (faithfulness gate #1576). */
     sourceText?: string,
     graphCaps: GraphConstructionCapabilitySet = resolveGraphConstructionCapabilities(this.config),
+    lifecycleCaps: MemoryLifecycleCapabilitySet = resolveMemoryLifecycleCapabilities(this.config),
   ): Promise<string[]> {
     // Inline source attribution (issue #369). When enabled, every extracted
     // fact is rewritten to carry a compact provenance tag inside its body so
@@ -14388,7 +14332,7 @@ export class Orchestrator {
             },
           );
           if (
-            this.config.temporalSupersessionEnabled &&
+            lifecycleCaps.temporalSupersession &&
             options.category === "fact" &&
             options.entityRef &&
             options.structuredAttributes &&
@@ -14552,7 +14496,7 @@ export class Orchestrator {
           // would have run post-writeMemory.  This is a best-effort / fail-open
           // step — if the lookup fails we skip silently (same as the normal path).
           if (
-            this.config.temporalSupersessionEnabled &&
+            lifecycleCaps.temporalSupersession &&
             options.entityRef &&
             options.structuredAttributes &&
             Object.keys(options.structuredAttributes).length > 0
@@ -14714,7 +14658,7 @@ export class Orchestrator {
         // shared recall continues returning the stale state.  Reuses the same
         // applyTemporalSupersession helper — no logic duplication.
         if (
-          this.config.temporalSupersessionEnabled &&
+          lifecycleCaps.temporalSupersession &&
           options.entityRef &&
           options.structuredAttributes &&
           Object.keys(options.structuredAttributes).length > 0
@@ -15024,7 +14968,7 @@ export class Orchestrator {
     // persistExtraction call so stale state from a prior call cannot leak
     // into the caller's buffer-retention decision.
     this.lastPersistExtractionDeferredCount = 0;
-    if (this.config.extractionJudgeEnabled) {
+    if (lifecycleCaps.extractionJudge) {
       // #1669 P1: pre-filter redacted facts from judge candidates so never-store
       // content is not persisted as judge training data.
       let preJudgeRedactionRules: CompiledRedactionRule[] = [];
@@ -15090,7 +15034,7 @@ export class Orchestrator {
         // off; the combined callback itself is undefined when both are
         // disabled so there is zero overhead in the default configuration.
         const judgeTelemetryOpts = {
-          enabled: this.config.extractionJudgeTelemetryEnabled === true,
+          enabled: lifecycleCaps.extractionJudgeTelemetry,
           memoryDir: this.config.memoryDir,
         };
         const judgeTrainingOpts = {
@@ -15301,7 +15245,7 @@ export class Orchestrator {
       // do not block scope routing). Rule 30: gated by
       // extractionScopeClassificationEnabled.
       if (
-        this.config.extractionScopeClassificationEnabled &&
+        lifecycleCaps.extractionScopeClassification &&
         this.config.namespacesEnabled &&
         fact.scope === "global" &&
         !routedNamespaceExplicit
@@ -15954,7 +15898,7 @@ export class Orchestrator {
                 // #1578 r3: an extracted end-only bound (validFrom absent) is
                 // historical, not a new authoritative state — never let it
                 // supersede a later active fact (codex P1 on :15534).
-                enabled: this.config.temporalSupersessionEnabled &&
+                enabled: lifecycleCaps.temporalSupersession &&
                   !(biTemporal && !biTemporal.validFrom),
               });
             } catch (err) {
@@ -16190,7 +16134,7 @@ export class Orchestrator {
             entityRef: supersessionEntityRef,
             structuredAttributes: fact.structuredAttributes,
             createdAt: supersessionOrderingAt(biTemporal?.validFrom ?? sourceContext?.validAt),
-            enabled: this.config.temporalSupersessionEnabled &&
+            enabled: lifecycleCaps.temporalSupersession &&
               !(biTemporal && !biTemporal.validFrom),
           });
         } catch (err) {
@@ -16557,7 +16501,7 @@ export class Orchestrator {
     storage: StorageManager,
     memoryId: string,
   ): Promise<void> {
-    if (!this.config.embeddingFallbackEnabled) return;
+    if (!resolveMemoryLifecycleCapabilities(this.config).embeddingFallback) return;
     if (!(await this.embeddingFallback.isAvailable())) return;
     const memory = await storage.getMemoryById(memoryId);
     if (!memory) return;
@@ -16749,6 +16693,7 @@ export class Orchestrator {
     merged: number;
     invalidated: number;
   }> {
+    const lifecycleCaps = resolveMemoryLifecycleCapabilities(this.config);
     log.info("running consolidation pass");
     let merged = 0;
     let invalidated = 0;
@@ -16985,7 +16930,7 @@ export class Orchestrator {
     }
 
     // v8.3 Lifecycle policy pass — deterministic promotion/decay metadata
-    if (this.config.lifecyclePolicyEnabled) {
+    if (lifecycleCaps.lifecyclePolicy) {
       try {
         const lightSleepStartedAt = new Date().toISOString();
         const lifecycleCorpus = await this.storage.readAllMemories();
@@ -17173,7 +17118,7 @@ export class Orchestrator {
     await this.storage.saveMeta(meta);
 
     // Temporal Memory Tree (v8.2) — rebuild nodes from all memories, fail-open
-    if (this.config.temporalMemoryTreeEnabled) {
+    if (lifecycleCaps.temporalMemoryTree) {
       try {
         const tmtEntries = allMemories
           .filter(
@@ -17715,6 +17660,7 @@ export class Orchestrator {
     let updatedCount = 0;
     let disputedCount = 0;
     let evaluatedCount = 0;
+    const lifecycleCaps = resolveMemoryLifecycleCapabilities(this.config);
 
     const thresholds = this.effectiveLifecycleThresholds();
     const policy = {
@@ -17780,7 +17726,7 @@ export class Orchestrator {
 
     // Report how many memories had frontmatter rewritten so callers can record a
     // catalog write touch for lifecycle-only passes (codex NR-tS).
-    if (!this.config.lifecycleMetricsEnabled) return updatedCount;
+    if (!lifecycleCaps.lifecycleMetrics) return updatedCount;
 
     const total = evaluatedCount;
     const metrics = {
@@ -19226,7 +19172,7 @@ export class Orchestrator {
     //   • search() throws                 → re-throw (network/provider error).
     //   • search() returns []             → return [] (empty index, not a
     //     backend failure; decideSemanticDedup reports no_candidates).
-    if (!this.config.embeddingFallbackEnabled) {
+    if (!resolveMemoryLifecycleCapabilities(this.config).embeddingFallback) {
       throw new Error("semantic dedup: embedding backend not configured");
     }
     if (!(await this.embeddingFallback.isAvailable())) {
@@ -19300,7 +19246,7 @@ export class Orchestrator {
     query: string,
     limit: number,
   ): Promise<QmdSearchResult[]> {
-    if (!this.config.embeddingFallbackEnabled) return [];
+    if (!resolveMemoryLifecycleCapabilities(this.config).embeddingFallback) return [];
     if (!(await this.embeddingFallback.isAvailable())) return [];
     const hits = await this.embeddingFallback.search(query, limit);
     if (hits.length === 0) return [];
@@ -20010,6 +19956,7 @@ export class Orchestrator {
       blockedPaths?: Set<string>;
     },
   ): QmdSearchResult[] {
+    const lifecycleCaps = resolveMemoryLifecycleCapabilities(this.config);
     let lifecycleFilteredCount = 0;
     let temporalSupersededFilteredCount = 0;
     let biTemporalExpiredFilteredCount = 0;
@@ -20043,9 +19990,9 @@ export class Orchestrator {
         if (
           options?.allowLifecycleFiltered !== true &&
           shouldFilterLifecycleRecallCandidate(memory.frontmatter, {
-            lifecyclePolicyEnabled: this.config.lifecyclePolicyEnabled,
+            lifecyclePolicyEnabled: lifecycleCaps.lifecyclePolicy,
             lifecycleFilterStaleEnabled:
-              this.config.lifecycleFilterStaleEnabled,
+              lifecycleCaps.lifecycleFilterStale,
           })
         ) {
           lifecycleFilteredCount += 1;
@@ -20079,7 +20026,7 @@ export class Orchestrator {
           // half-open `[valid_at, invalid_at)` evaluation in isValidAsOf
           // is the authoritative gate for historical recall.
           shouldFilterSupersededFromRecall(memory.frontmatter, {
-            enabled: this.config.temporalSupersessionEnabled,
+            enabled: lifecycleCaps.temporalSupersession,
             includeInRecall: this.config.temporalSupersessionIncludeInRecall,
           })
         ) {
@@ -20223,6 +20170,7 @@ export class Orchestrator {
       asOfMs?: number;
     },
   ): Promise<QmdSearchResult[]> {
+    const lifecycleCaps = resolveMemoryLifecycleCapabilities(this.config);
     if (results.length === 0) return results;
 
     const safety = await this.filterSearchResultsForRecall(
@@ -20397,7 +20345,7 @@ export class Orchestrator {
         const lifecycleDelta = lifecycleRecallScoreAdjustment(
           memory.frontmatter,
           {
-            lifecyclePolicyEnabled: this.config.lifecyclePolicyEnabled,
+            lifecyclePolicyEnabled: lifecycleCaps.lifecyclePolicy,
           },
         );
         score += applyUtilityRankingRuntimeDelta(

package/src/search/embed-helper.ts

@@ -1,4 +1,5 @@
 import { log } from "../logger.js";
+import { resolveMemoryLifecycleCapabilities } from "../capabilities.js";
 import type { PluginConfig } from "../types.js";
 import { isAbortError } from "../abort-error.js";
 import { withTimeoutSignal } from "./abort.js";
@@ -209,7 +210,7 @@ export class EmbedHelper {
   }
 
   private resolveProvider(options: { includeHost?: boolean } = {}): ProviderConfig | null {
-    if (!this.config.embeddingFallbackEnabled) return null;
+    if (!resolveMemoryLifecycleCapabilities(this.config).embeddingFallback) return null;
 
     if (
       options.includeHost !== false &&
@@ -244,7 +245,7 @@ export class EmbedHelper {
   }
 
   private resolveFallbackProviderForIdentity(identity: EmbedProviderIdentity): ProviderConfig | null {
-    if (!this.config.embeddingFallbackEnabled) return null;
+    if (!resolveMemoryLifecycleCapabilities(this.config).embeddingFallback) return null;
     const separator = identity.indexOf(":");
     if (separator <= 0 || separator === identity.length - 1) return null;
     const type = identity.slice(0, separator);