@remnic/core 9.3.728 → 9.3.729

package/dist/{chunk-QNEUZIAH.js → chunk-HEDZUSCS.js}

@@ -746,6 +746,130 @@ var TierMigrationCoordinator = class {
   }
 };
 
+// src/orchestration/extraction-queue-coordinator.ts
+var ExtractionQueueCoordinator = class {
+  /**
+   * Background serial queue for extractions (agent_end optimization).
+   * Queue stores tasks that resolve when extraction should run.
+   */
+  queue = [];
+  /** Whether the serial drain loop is currently running. */
+  processing = false;
+  /** Current queue depth (idle-wait + test seam). */
+  get length() {
+    return this.queue.length;
+  }
+  /** Whether the serial drain loop is currently running (idle-wait + test seam). */
+  get isProcessing() {
+    return this.processing;
+  }
+  /**
+   * Enqueue a task and start the serial processor if it is idle. This is
+   * the production entry point — the orchestrator's `queueBufferedExtraction`
+   * builds each task closure and hands it here.
+   */
+  enqueue(task) {
+    this.queue.push(task);
+    if (!this.processing) {
+      this.processing = true;
+      this.processQueue().catch((err) => {
+        this.logExtractionQueueFailure(err, "processor");
+        this.processing = false;
+      });
+    }
+  }
+  /**
+   * Background serial queue processor.
+   * Processes extractions one at a time to avoid race conditions.
+   * Called automatically when items are queued via `enqueue`; also exposed
+   * for the characterization tests that push raw tasks and assert drain
+   * semantics directly.
+   */
+  async processQueue() {
+    while (this.queue.length > 0) {
+      const task = this.queue.shift();
+      if (task) {
+        try {
+          await task();
+        } catch (err) {
+          this.logExtractionQueueFailure(err, "task");
+        }
+      }
+    }
+    this.processing = false;
+  }
+  /**
+   * Classify + log a failure from either the per-task catch inside
+   * `processQueue()` or the outer `processQueue().catch(...)` in
+   * `enqueue()`.  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`).
+   */
+  logExtractionQueueFailure(err, source) {
+    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);
+    }
+  }
+  /**
+   * Wait until the extraction queue is fully drained (no tasks queued, no
+   * drain in flight) or `timeoutMs` elapses. Used by bootstrap (after a
+   * dry-run import) and by tests that need to assert extraction settled.
+   * Returns false on timeout, true once idle.
+   */
+  async waitForIdle(timeoutMs = 6e4) {
+    const started = Date.now();
+    while (this.processing || this.queue.length > 0) {
+      if (Date.now() - started > timeoutMs) {
+        log.warn(`waitForExtractionIdle timed out after ${timeoutMs}ms`);
+        return false;
+      }
+      const { promise, resolve } = Promise.withResolvers();
+      setTimeout(resolve, 50);
+      await promise;
+    }
+    return true;
+  }
+  // ── Test seams ─────────────────────────────────────────────────────────
+  // Mirror the pre-extraction `orchestrator.extractionQueue` /
+  // `orchestrator.queueProcessing` direct-field access the characterization
+  // and flush deadline tests relied on. Each is a thin, well-named handle
+  // onto the coordinator's private state — no behavior change.
+  /**
+   * Push a raw task WITHOUT auto-starting the processor, matching the
+   * pre-extraction `this.extractionQueue.push(...)` used by the
+   * characterization tests that drive the drain manually via `processQueue`.
+   */
+  pushRaw(task) {
+    this.queue.push(task);
+  }
+  /** Remove + return the front task (test seam for the flush deadline tests). */
+  shift() {
+    return this.queue.shift();
+  }
+  /**
+   * Force the processor-busy flag so `enqueue` does not auto-start the
+   * drain — used by the flush deadline test to simulate a busy queue and
+   * assert a queued task's deadline expires while it waits.
+   */
+  setProcessingForTest(value) {
+    this.processing = value;
+  }
+};
+
 // src/maintenance/pattern-reinforcement.ts
 function patternReinforcementKey(content) {
   return content.trim().toLowerCase().replace(/\s+/g, " ").slice(0, 200);
@@ -2998,10 +3122,14 @@ var Orchestrator = class _Orchestrator {
   passiveCorrectionDedup = /* @__PURE__ */ new Set();
   _passiveCorrectionService = null;
   passiveCorrectionTelemetry = { detected: 0, queued: 0, autoApplied: 0, suppressedReasonCounts: {} };
-  // Background serial queue for extractions (agent_end optimization)
-  // Queue stores promises that resolve when extraction should run
-  extractionQueue = [];
-  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`.
+   */
+  extractionQueueCoordinator;
   heartbeatObserverChains = /* @__PURE__ */ new Map();
   recentExtractionFingerprints = /* @__PURE__ */ new Map();
   consolidationObservers = /* @__PURE__ */ new Set();
@@ -3706,6 +3834,7 @@ var Orchestrator = class _Orchestrator {
       namespaceSearchRouter: this.namespaceSearchRouter,
       namespaceCatalog: this.namespaceCatalog
     });
+    this.extractionQueueCoordinator = new ExtractionQueueCoordinator();
     const conversationIndexRuntime = createConversationIndexRuntime(config, {
       getQmd: () => this.conversationQmd,
       getFaiss: () => this.conversationFaiss
@@ -4928,15 +5057,7 @@ ${doc.content}` : doc.content,
     return result;
   }
   async waitForExtractionIdle(timeoutMs = 6e4) {
-    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;
+    return this.extractionQueueCoordinator.waitForIdle(timeoutMs);
   }
   async waitForConsolidationIdle(timeoutMs = 6e4) {
     const started = Date.now();
@@ -11161,7 +11282,7 @@ _Context: ${topQuestion.context}_`
         settleTask(new Error("replay extraction deadline exceeded (queue_wait)"));
       }, remainingMs);
     }
-    this.extractionQueue.push(async () => {
+    this.extractionQueueCoordinator.enqueue(async () => {
       if (settled) return;
       if (typeof extractionDeadlineMs === "number" && extractionDeadlineMs <= Date.now()) {
         settleTask(new Error("replay extraction deadline exceeded (queue_wait)"));
@@ -11187,13 +11308,6 @@ _Context: ${topQuestion.context}_`
         }
       }
     });
-    if (!this.queueProcessing) {
-      this.queueProcessing = true;
-      this.processQueue().catch((err) => {
-        this.logExtractionQueueFailure(err, "processor");
-        this.queueProcessing = false;
-      });
-    }
     log.debug(`queued extraction from ${reason}`);
   }
   normalizeExtractionFingerprintTurns(turns) {
@@ -11237,50 +11351,6 @@ ${normalized}`).digest("hex");
     }
     return true;
   }
-  /**
-   * Background serial queue processor.
-   * Processes extractions one at a time to avoid race conditions.
-   * Called automatically when items are queued.
-   */
-  async processQueue() {
-    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`).
-   */
-  logExtractionQueueFailure(err, source) {
-    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
@@ -16322,4 +16392,4 @@ export {
   resolvePersistedMemoryRelativePath,
   Orchestrator
 };
-//# sourceMappingURL=chunk-QNEUZIAH.js.map
+//# sourceMappingURL=chunk-HEDZUSCS.js.map