@remnic/core 10.0.66 → 10.0.67

package/src/orchestration/extraction-persist.ts

@@ -1,4 +1,5 @@
 import { classifyExtractionOrigin, type ExtractionSourceContext } from "./extraction-origin-context.js";
+import { confirmActiveFactDuplicate, persistUnderFactDedupWindow } from "./fact-dedup-window.js";
 import { evaluateInjectionScreen, screenEntityForIndex, screenPersistStrings } from "./extraction-injection-gate.js";
 /**
  * Extraction persistence coordinator (issue #1526, seam 16).
@@ -1663,148 +1664,123 @@ export class ExtractionPersistCoordinator {
         fact.tags,
       );
       let exactDuplicate = false;
-      let needsCorpusConfirm = false;
       try {
         exactDuplicate = await this.deps.hasContentHashDedup(targetStorage, contentHashDedupKey);
-        if (factDedupEnabled && !exactDuplicate) {
-          // Fact dedup disabled → skip the authority check AND (via the guarded
-          // corpus block below) corpus confirmation, so a disabled deployment
-          // never suppresses a write via dedup (PR #2016 thread SD-nH). Enabled:
-          // a MISS is trustworthy only against an AUTHORITATIVE index — re-check.
-          if (await targetStorage.isFactContentHashAuthoritative()) {
-            exactDuplicate = await this.deps.hasContentHashDedup(targetStorage, contentHashDedupKey);
-          } else {
-            needsCorpusConfirm = true;
-          }
-        }
       } catch (err) {
-        // Dedup lookup failed (e.g. the authoritative rebuild could not run). Do
-        // NOT fail-open into a possible duplicate — confirm against the corpus.
-        needsCorpusConfirm = true;
+        // Dedup lookup failed (e.g. the authoritative rebuild could not run).
+        // When dedup is enabled the confirm below still scans the corpus; when
+        // it is disabled, never suppress a write via dedup (PR #2016 SD-nH).
+        exactDuplicate = false;
         log.warn(
           `content-hash dedup lookup unavailable for storage ${targetStorage.dir}; confirming against corpus: ${err}`,
         );
       }
-      // Connector-aware dedup (QOjlB): if the hash says duplicate — or the index
-      // could not authoritatively confirm a miss — verify a same-content,
-      // same-connector active fact exists across the hot+cold tiers. Different
-      // connectors with the same content are NOT duplicates. Fail open (write) on
-      // scan failure so an unverifiable state cannot silently drop content.
-      if (factDedupEnabled && (exactDuplicate || needsCorpusConfirm)) {
-        try {
-          // #2016 cold-tier finding: the authoritative content-hash rebuild
-          // unions the HOT and COLD tiers, so a hash hit can name an active copy
-          // that was demoted to cold/. A hot-only confirmation scan misses it,
-          // flips exactDuplicate back to false, and writes a second active hot
-          // copy of the same content. Scan both tiers so a cold-only active copy
-          // still confirms the duplicate and suppresses the redundant hot write.
-          const [hotMems, coldMems] = await Promise.all([
-            targetStorage.readAllMemories(),
-            targetStorage.readAllColdMemories(),
-          ]);
-          const nc = sourceContext?.sourceConnector?.trim() || undefined;
-          const matchesActiveDuplicate = (m: MemoryFile): boolean => {
-            if (m.frontmatter.category !== writeCategory) return false;
-            if ((m.frontmatter.status ?? "active") !== "active") return false;
-            // Thread 5 (QPDE5): for procedures the hash is keyed on the full
-            // body (title + steps via buildProcedurePersistBody), so compare
-            // against contentHashDedupKey — not canonicalContentForHash which
-            // is the title only. Thread 3 (QO42V): facts with
-            // structuredAttributes get an appended [Attributes: ...] suffix in
-            // the stored body that the hash key lacks; strip it before
-            // comparing so same-connector enriched facts dedup correctly.
-            if (normalizeStoredHashSource(stripAttributesSuffix(m.content ?? "")) !==
-              ContentHashIndex.normalizeContent(contentHashDedupKey)) return false;
-            return (m.frontmatter.sourceConnector?.trim() || undefined) === nc;
-          };
-          exactDuplicate =
-            hotMems.some(matchesActiveDuplicate) || coldMems.some(matchesActiveDuplicate);
-        } catch (err) {
-          log.warn(
-            `connector-aware dedup scan failed for storage ${targetStorage.dir}; writing fail-open: ${err instanceof Error ? err.message : String(err)}`,
-          );
-          exactDuplicate = false;
-        }
+      // Shared confirm options for the persist-time check and the write-window
+      // race recheck below.
+      const raceDedupOpts = (key: string) => ({
+        category: writeCategory,
+        contentHashDedupKey: key,
+        connector: sourceContext?.sourceConnector?.trim() || undefined,
+        citationEnabled,
+        citationTemplate,
+      });
+      // Fact dedup disabled → skip the authority check AND the corpus
+      // confirmation, so a disabled deployment never suppresses a write via
+      // dedup (PR #2016 thread SD-nH).
+      if (factDedupEnabled) {
+        exactDuplicate = await confirmActiveFactDuplicate(
+          { hasContentHashDedup: (storage, key) => this.deps.hasContentHashDedup(storage, key) },
+          targetStorage,
+          raceDedupOpts(contentHashDedupKey),
+        );
       }
-      if (exactDuplicate && injectionScreenStatus !== "pending_review") {
-        // #1671 — before short-circuiting, backfill bi-temporal bounds
-        // onto the existing source-namespace copy if it lacks bounds the
-        // incoming fact now carries (re-extraction with a resolved invalidAt).
-        // Skip when the fact would be rejected/deferred/pending by downstream
-        // gates — a non-durable candidate must not expire an active fact
-        // (chatgpt-codex P1: faithfulness, requireSpans, extraction judge).
-        // #1671 + #1707: backfill bi-temporal bounds onto the existing
-        // source-namespace copy if it lacks bounds the incoming fact now
-        // carries (re-extraction with a resolved bound). #1707 thread 3:
-        // gate on writeCategory === "fact" — the helper only matches facts,
-        // so a non-fact duplicate must not reach the fact-only scan.
-        // #1707 thread 2: also fire when only a corrected start bound
-        // (validFrom) is present, not just an end bound (validUntil). The
-        // downstream-gate skip still applies — a non-durable candidate must
-        // not expire an active fact (chatgpt-codex P1).
+      // PR #2016/#3231: finalize committed writes before a fail-closed
+      // window throw propagates (PRRT_kwDORJXyws6zxG6H).
+      const finalizeOnWindowFailure = async (err: Error): Promise<never> => {
+        await finalizeCommittedWrites(true).catch((finalizeErr) =>
+          log.warn(`committed-write finalization after fact-dedup window failure failed: ${finalizeErr}`),
+        );
+        throw err;
+      };
+      const raceRecheck = (storage: StorageManager, key: string) => () => {
+        // Gates mirror the persist-time suppression gates (PR #2016 SD-nH; #1645 quarantine).
+        if (!factDedupEnabled || injectionScreenStatus === "pending_review") return Promise.resolve(false);
+        return confirmActiveFactDuplicate(
+          { hasContentHashDedup: (s, k) => this.deps.hasContentHashDedup(s, k) },
+          storage,
+          raceDedupOpts(key),
+        );
+      };
+      // #1671/#1707 — backfill bi-temporal bounds onto the surviving copy
+      // when a duplicate short-circuits: persist-time hit OR raced duplicate
+      // suppressed in the window (codex P2, PRRT_kwDORJXyws6zxlor). Facts
+      // only (#1707 t3); a corrected start bound counts (t2). Skipped when a
+      // downstream gate would reject the candidate — a non-durable candidate
+      // must not expire an active fact (faithfulness, requireSpans, judge,
+      // #372 importance).
+      const backfillDuplicateTemporalBounds = async () => {
+        if (!(biTemporal && writeCategory === "fact" && (biTemporal.validUntil || biTemporal.validFrom))) return;
+        const fr = faithfulnessResultsByFactIndex?.get(factLoopIndex);
+        const faithfulnessWouldPending =
+          faithfulnessMode === "enforce" &&
+          fr?.ok === true &&
+          (fr.verdict === "unsupported" || fr.verdict === "contradicted");
+        const requireSpansWouldPending =
+          this.deps.config.provenance?.requireSpans === true &&
+          fact.requireSpansPending === true;
+        const judgeVerdict = judgeVerdictsByFactIndex?.get(factLoopIndex);
+        const judgeWouldGate =
+          !this.deps.config.extractionJudgeShadow &&
+          judgeVerdict !== undefined &&
+          !judgeVerdict.durable;
+        // Importance gate (cursor PRRT_OvKnS): below-threshold duplicates
+        // would never persist (#372) and carry no judge verdict (the
+        // pre-filter skips them), so they must not expire an active fact.
         if (
-          biTemporal &&
-          writeCategory === "fact" &&
-          (biTemporal.validUntil || biTemporal.validFrom)
+          !isAboveImportanceThreshold(importance.level, this.deps.config.extractionMinImportanceLevel) ||
+          faithfulnessWouldPending ||
+          requireSpansWouldPending ||
+          judgeWouldGate
         ) {
-          const fr = faithfulnessResultsByFactIndex?.get(factLoopIndex);
-          const faithfulnessWouldPending =
-            faithfulnessMode === "enforce" &&
-            fr?.ok === true &&
-            (fr.verdict === "unsupported" || fr.verdict === "contradicted");
-          const requireSpansWouldPending =
-            this.deps.config.provenance?.requireSpans === true &&
-            fact.requireSpansPending === true;
-          const judgeVerdict = judgeVerdictsByFactIndex?.get(factLoopIndex);
-          const judgeWouldGate =
-            !this.deps.config.extractionJudgeShadow &&
-            judgeVerdict !== undefined &&
-            !judgeVerdict.durable;
-          // Importance gate (cursor PRRT_OvKnS): below-threshold duplicates
-          // would never persist (#372) and carry no judge verdict (the
-          // pre-filter skips them), so they must not expire an active fact.
-          if (
-            isAboveImportanceThreshold(importance.level, this.deps.config.extractionMinImportanceLevel) &&
-            !faithfulnessWouldPending &&
-            !requireSpansWouldPending &&
-            !judgeWouldGate
-          ) {
-            await this.deps.backfillTemporalBoundsOnDedupHit(
-              targetStorage,
-              contentHashDedupKey,
-              {
-                invalidAt: biTemporal.validUntil,
-                // #1707 thread 2 — carry the corrected start bound too.
-                validFrom: biTemporal.validFrom,
-                observedAt: biTemporal.observedAt,
-                eventTimeSource: biTemporal.eventTimeSource,
-              },
-              fact.entityRef,
-              sourceContext?.sourceConnector,
-            );
-            // #1707 thread 1 — the source branch short-circuits (`continue`
-            // below) before the promotion dedup paths run, so promoted
-            // shared/profile copies written before the source fact carried
-            // resolved bounds stay stale and cross-namespace recall surfaces
-            // an expired fact. Backfill the promotion targets too (fail-open,
-            // backfill-only — never writes a new promoted copy).
-            await backfillTemporalBoundsOnPromotionCopies({
-              sourceStorage: targetStorage,
-              content: fact.content,
-              category: writeCategory,
-              confidence: fact.confidence,
-              entityRef: fact.entityRef,
-              structuredAttributes: fact.structuredAttributes,
-              sourceConnector: sourceContext?.sourceConnector,
-              bounds: {
-                invalidAt: biTemporal.validUntil,
-                validFrom: biTemporal.validFrom,
-                observedAt: biTemporal.observedAt,
-                eventTimeSource: biTemporal.eventTimeSource,
-              },
-            });
-          }
+          return;
         }
+        await this.deps.backfillTemporalBoundsOnDedupHit(
+          targetStorage,
+          contentHashDedupKey,
+          {
+            invalidAt: biTemporal.validUntil,
+            // #1707 thread 2 — carry the corrected start bound too.
+            validFrom: biTemporal.validFrom,
+            observedAt: biTemporal.observedAt,
+            eventTimeSource: biTemporal.eventTimeSource,
+          },
+          fact.entityRef,
+          sourceContext?.sourceConnector,
+        );
+        // #1707 thread 1 — a short-circuited source branch never reaches the
+        // promotion dedup paths, so promoted shared/profile copies written
+        // before the source fact carried resolved bounds stay stale and
+        // cross-namespace recall surfaces an expired fact. Backfill the
+        // promotion targets too (fail-open, backfill-only — never writes a
+        // new promoted copy).
+        await backfillTemporalBoundsOnPromotionCopies({
+          sourceStorage: targetStorage,
+          content: fact.content,
+          category: writeCategory,
+          confidence: fact.confidence,
+          entityRef: fact.entityRef,
+          structuredAttributes: fact.structuredAttributes,
+          sourceConnector: sourceContext?.sourceConnector,
+          bounds: {
+            invalidAt: biTemporal.validUntil,
+            validFrom: biTemporal.validFrom,
+            observedAt: biTemporal.observedAt,
+            eventTimeSource: biTemporal.eventTimeSource,
+          },
+        });
+      };
+      if (exactDuplicate && injectionScreenStatus !== "pending_review") {
+        await backfillDuplicateTemporalBounds();
         log.debug(
           `dedup: skipping duplicate fact "${fact.content.slice(0, 60)}…" in storage ${targetStorage.dir}`,
         );
@@ -2198,7 +2174,11 @@ export class ExtractionPersistCoordinator {
             },
             { source: extractionWriteSource },
 );
-          const parentWrite = await targetStorage.writeSealedMemory(parentWriteEnvelope, {
+          const parentWriteOutcome = await persistUnderFactDedupWindow(
+            targetStorage.dir,
+            raceRecheck(targetStorage, contentHashDedupKey),
+            async () =>
+              targetStorage.writeSealedMemory(parentWriteEnvelope, {
             importance,
             supersedes,
             links: links.length > 0 ? links : undefined,
@@ -2218,7 +2198,16 @@ export class ExtractionPersistCoordinator {
             // durable parent .md; flush the hash now so a throw can't strand it (dup).
             deferHashIndexSave: false,
             ...(factToolScoped ? { toolScoped: true as const } : {}),
-          });
+              }),
+          ).catch(finalizeOnWindowFailure);
+          if (parentWriteOutcome.suppressed) {
+            // Codex P2: backfill bounds onto the winning copy first.
+            await backfillDuplicateTemporalBounds();
+            log.info(`dedup: raced duplicate suppressed in fact-dedup window (chunked parent) for storage ${targetStorage.dir}`);
+            dedupedCount++;
+            continue;
+          }
+          const parentWrite = parentWriteOutcome.result;
           const parentId = parentWrite.id;
           // #1645: surface the tombstone block and gate active post-write paths
           const tombstoneBlocked = parentWrite.tombstoneBlocked;
@@ -2589,7 +2578,11 @@ export class ExtractionPersistCoordinator {
         },
         { source: extractionWriteSource },
 );
-      const factWrite = await targetStorage.writeSealedMemory(factWriteEnvelope, {
+      const factWriteOutcome = await persistUnderFactDedupWindow(
+        targetStorage.dir,
+        raceRecheck(targetStorage, contentHashDedupKey),
+        async () =>
+          targetStorage.writeSealedMemory(factWriteEnvelope, {
         importance,
         supersedes,
         links: links.length > 0 ? links : undefined,
@@ -2607,11 +2600,21 @@ export class ExtractionPersistCoordinator {
         // through to frontmatter so they survive end-to-end.
         ...(fact.sources && fact.sources.length > 0 ? { sources: fact.sources } : {}),
         ...(fact.provenance ? { provenance: fact.provenance } : {}),
-        // #1909: defer the per-fact index flush to the batch save only when
-        // fact dedup is on (the batch saver is a no-op otherwise).
-        deferHashIndexSave: factDedupEnabled,
+        // PR #2016: never defer inside the commit window (chunked-path
+        // rule): a peer loading an authoritative index after the release
+        // must see this hash, or its recheck misses and duplicates it.
+        deferHashIndexSave: false,
         ...(factToolScoped ? { toolScoped: true as const } : {}),
-      });
+          }),
+      ).catch(finalizeOnWindowFailure);
+      if (factWriteOutcome.suppressed) {
+        // Codex P2: backfill bounds onto the window's winning copy first.
+        await backfillDuplicateTemporalBounds();
+        log.info(`dedup: raced duplicate suppressed in fact-dedup window for storage ${targetStorage.dir}`);
+        dedupedCount++;
+        continue;
+      }
+      const factWrite = factWriteOutcome.result;
       const memoryId = factWrite.id;
       // #1645: surface the tombstone block; gate active post-write paths like #1576
       // so a blocked fact creates no active shared copy / supersession / graph entry.

package/src/orchestration/extraction-queue-coordinator.ts

@@ -1,13 +1,15 @@
 /**
  * Extraction queue coordinator — extracted from the orchestrator (issue #1526).
  *
- * Owns the background serial queue that drains extraction tasks one at a
- * time to avoid races between concurrent flush/heartbeat/bulk-import
+ * Owns the background bounded-parallel queue that drains extraction tasks
+ * while avoiding races between concurrent flush/heartbeat/bulk-import
  * triggers:
- *   - queue state (`extractionQueue` + `queueProcessing`)
+ *   - queue state (`queue` + `processing` + per-task preempt slots)
  *   - the scheduling trigger (start the drain when the first task lands and
- *     the processor is idle)
- *   - the serial drain loop itself (`processQueue`)
+ *     capacity is free)
+ *   - the drain loop itself (`processQueue`): up to `concurrency` tasks run
+ *     at once; tasks sharing an entry `key` (a buffer/session) never run
+ *     concurrently, so the same buffer is never extracted twice in parallel
  *   - failure classification (`logExtractionQueueFailure`) — issue #549:
  *     AbortError from session transitions logs at debug, real failures at
  *     error
@@ -19,51 +21,102 @@
  * orchestrator builds each task closure and hands it to `enqueue`; the
  * coordinator owns only the queue mechanics.
  *
- * Behavior-preserving move from orchestrator.ts. No logic changes — the
- * orchestrator keeps a thin delegating `waitForExtractionIdle` and the
- * `queueBufferedExtraction` builder delegates push+scheduling here.
+ * Preemption is per task: each running task receives an
+ * `ExtractionPreemptHandle` at run time and registers its own abort, so two
+ * concurrent automatic extractions cannot clobber each other's registration
+ * (the previous single-slot `runningPreempt` could only hold one).
+ * `preemptRunning` aborts at most ONE armed task — the requested key's own
+ * running work when it is armed, else the most recently armed task — which
+ * is exactly the single-slot semantics generalized from one worker to N.
  */
 
 import { isAbortError, preemptedExtractionError } from "../abort-error.js";
 import { log } from "../logger.js";
 
+/** Preemption registration for ONE running task. Armed work can be aborted
+ *  by a fail-closed flush; disarmed work (past persist) cannot. */
+export interface ExtractionPreemptHandle {
+  /** Register the task's abort (replacing any previous registration). */
+  arm(abort: () => void): void;
+  /** Remove the task's registration (idempotent). */
+  disarm(): void;
+}
+
+/** A queued task; the coordinator passes the task's own preempt handle. */
+export type ExtractionQueueTask = (preempt?: ExtractionPreemptHandle) => Promise<void>;
+
+export interface ExtractionQueueEnqueueOptions {
+  /** Jump the queue and preempt the running automatic work (force flush). */
+  front?: boolean;
+  /** Buffer/session key. Tasks sharing a key never run concurrently. */
+  key?: string;
+}
+
+interface QueueEntry {
+  run: ExtractionQueueTask;
+  key?: string;
+}
+
+interface PreemptSlot {
+  key?: string;
+  armed?: { abort: () => void; seq: number };
+}
+
 /**
- * Coordinates the background serial extraction queue. Owns the in-flight
- * guard + queue array that previously lived as private orchestrator fields.
+ * Coordinates the background bounded-parallel extraction queue. Owns the
+ * queue array, the per-key in-flight guard, and the per-task preempt slots.
  */
 export class ExtractionQueueCoordinator {
+  /** Maximum tasks that run at the same time (config `extractionQueueConcurrency`). */
+  private readonly concurrency: number;
   /**
-   * Background serial queue for extractions (agent_end optimization).
-   * Queue stores tasks that resolve when extraction should run.
+   * Background queue for extractions (agent_end optimization). Queue stores
+   * tasks that resolve when extraction should run.
    */
-  private readonly queue: Array<() => Promise<void>> = [];
-  /** Whether the serial drain loop is currently running. */
+  private readonly queue: QueueEntry[] = [];
+  /** Whether the drain loop is currently running. */
   private processing = false;
   private accepting = true;
-  private runningPreempt: (() => void) | undefined;
+  /** Buffer keys with a task currently running (per-key exclusion). */
+  private readonly activeKeys = new Set<string>();
+  /** Preempt slots of the currently running tasks, keyed by slot identity. */
+  private readonly preemptSlots = new Map<object, PreemptSlot>();
+  private preemptSeq = 0;
+  /** Resolves the processor's park while a new task arrives mid-drain. */
+  private wake?: () => void;
+
+  constructor(concurrency = 1) {
+    this.concurrency = Number.isInteger(concurrency) && concurrency >= 1 ? concurrency : 1;
+  }
 
   /** Current queue depth (idle-wait + test seam). */
   get length(): number {
     return this.queue.length;
   }
 
-  /** Whether the serial drain loop is currently running (idle-wait + test seam). */
+  /** Whether the drain loop is currently running (idle-wait + test seam). */
   get isProcessing(): boolean {
     return this.processing;
   }
 
+  /** How many tasks may run at once (test seam + diagnostics). */
+  get maxConcurrency(): number {
+    return this.concurrency;
+  }
+
   /**
-   * Enqueue a task and start the serial processor if it is idle. This is
+   * Enqueue a task and start the processor when capacity is free. This is
    * the production entry point — the orchestrator's `queueBufferedExtraction`
-   * builds each task closure and hands it here.
+   * builds each task closure and hands it here with its buffer key.
    */
-  enqueue(task: () => Promise<void>, options?: { front?: boolean }): boolean {
+  enqueue(task: ExtractionQueueTask, options?: ExtractionQueueEnqueueOptions): boolean {
     if (!this.accepting) return false;
+    const entry: QueueEntry = { run: task, key: options?.key };
     if (options?.front) {
-      this.preemptRunning();
-      this.queue.unshift(task);
+      this.preemptRunning(options.key);
+      this.queue.unshift(entry);
     } else {
-      this.queue.push(task);
+      this.queue.push(entry);
     }
     if (!this.processing) {
       this.processing = true;
@@ -71,38 +124,43 @@ export class ExtractionQueueCoordinator {
         this.logExtractionQueueFailure(err, "processor");
         this.processing = false;
       });
+    } else {
+      // The processor may be parked waiting for an in-flight task while a
+      // slot is free; wake it so the new task starts instead of waiting
+      // behind work it could overlap with.
+      this.wake?.();
     }
     return true;
   }
 
-  /** Automatic extraction registers this so a fail-closed flush can abort it. */
-  beginPreemptable(abort: () => void): void {
-    this.runningPreempt = abort;
-  }
-
-  endPreemptable(): void {
-    this.runningPreempt = undefined;
-  }
-
-  preemptRunning(): void {
-    const abort = this.runningPreempt;
-    this.runningPreempt = undefined;
+  preemptRunning(preferredKey?: string): void {
+    const armed = Array.from(this.preemptSlots.values()).filter((slot) => slot.armed !== undefined);
+    if (armed.length === 0) return;
+    const preferred = preferredKey !== undefined ? armed.find((slot) => slot.key === preferredKey) : undefined;
+    const chosen =
+      preferred ??
+      armed.reduce((a, b) => ((b.armed?.seq ?? -1) > (a.armed?.seq ?? -1) ? b : a));
+    const abort = chosen.armed?.abort;
+    chosen.armed = undefined;
     abort?.();
   }
+
   runPreemptable<T>(
+    preempt: ExtractionPreemptHandle | undefined,
     preemptable: boolean,
     parent: AbortSignal | undefined,
     run: (signal: AbortSignal) => Promise<T>,
   ): Promise<T> {
-    const preempt = new AbortController();
-    if (preemptable) this.beginPreemptable(() => preempt.abort(preemptedExtractionError()));
-    const signal = parent ? AbortSignal.any([parent, preempt.signal]) : preempt.signal;
+    const preemptController = new AbortController();
+    if (preemptable && preempt) {
+      preempt.arm(() => preemptController.abort(preemptedExtractionError()));
+    }
+    const signal = parent ? AbortSignal.any([parent, preemptController.signal]) : preemptController.signal;
     return Promise.resolve(run(signal)).finally(() => {
-      if (preemptable) this.endPreemptable();
+      if (preemptable && preempt) preempt.disarm();
     });
   }
 
-
   /** Stop new producers from entering the queue. */
   stopAccepting(): void {
     this.accepting = false;
@@ -123,30 +181,82 @@ export class ExtractionQueueCoordinator {
   }
 
   /**
-   * 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.
+   * Background queue processor. Runs up to `concurrency` tasks at a time,
+   * never two tasks with the same entry key. 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(): Promise<void> {
-    while (this.queue.length > 0) {
-      const task = this.queue.shift();
-      if (task) {
+    const inFlight = new Set<Promise<void>>();
+    try {
+      while (this.queue.length > 0 || inFlight.size > 0) {
+        while (inFlight.size < this.concurrency) {
+          const entry = this.takeRunnable();
+          if (!entry) break;
+          const running = this.runEntry(entry).finally(() => {
+            inFlight.delete(running);
+          });
+          inFlight.add(running);
+        }
+        // Park until a task settles OR a new task is enqueued. A queued task
+        // whose key is still held always implies an in-flight task holding
+        // it, so inFlight is non-empty here whenever the loop must wait.
+        if (inFlight.size === 0) break;
+        const { promise: wakePromise, resolve: wake } = Promise.withResolvers<void>();
+        this.wake = wake;
         try {
-          await task();
-        } catch (err) {
-          this.logExtractionQueueFailure(err, "task");
+          await Promise.race([wakePromise, ...inFlight]);
+        } finally {
+          this.wake = undefined;
         }
       }
+    } finally {
+      this.processing = false;
     }
+  }
+
+  /** Take the next queue entry whose key is not already running (FIFO within a key). */
+  private takeRunnable(): QueueEntry | undefined {
+    for (let index = 0; index < this.queue.length; index += 1) {
+      const entry = this.queue[index];
+      if (entry.key !== undefined && this.activeKeys.has(entry.key)) continue;
+      this.queue.splice(index, 1);
+      if (entry.key !== undefined) this.activeKeys.add(entry.key);
+      return entry;
+    }
+    return undefined;
+  }
+
+  /** Run one entry with its own preempt slot; failures are classified + logged. */
+  private async runEntry(entry: QueueEntry): Promise<void> {
+    const slot: PreemptSlot = {};
+    this.preemptSlots.set(slot, { key: entry.key });
+    try {
+      await entry.run(this.createPreemptHandle(slot));
+    } catch (err) {
+      this.logExtractionQueueFailure(err, "task");
+    } finally {
+      this.preemptSlots.delete(slot);
+      if (entry.key !== undefined) this.activeKeys.delete(entry.key);
+    }
+  }
 
-    this.processing = false;
+  private createPreemptHandle(slot: PreemptSlot): ExtractionPreemptHandle {
+    return {
+      arm: (abort: () => void) => {
+        const state = this.preemptSlots.get(slot);
+        if (state) state.armed = { abort, seq: this.preemptSeq++ };
+      },
+      disarm: () => {
+        const state = this.preemptSlots.get(slot);
+        if (state) state.armed = undefined;
+      },
+    };
   }
 
   /**
    * Classify + log a failure from either the per-task catch inside
-   * `processQueue()` or the outer `processQueue().catch(...)` in
+   * `runEntry` 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
@@ -211,13 +321,14 @@ export class ExtractionQueueCoordinator {
    * pre-extraction `this.extractionQueue.push(...)` used by the
    * characterization tests that drive the drain manually via `processQueue`.
    */
-  pushRaw(task: () => Promise<void>): void {
-    this.queue.push(task);
+  pushRaw(task: ExtractionQueueTask, options?: { key?: string }): void {
+    this.queue.push({ run: task, key: options?.key });
+    this.wake?.();
   }
 
   /** Remove + return the front task (test seam for the flush deadline tests). */
-  shift(): (() => Promise<void>) | undefined {
-    return this.queue.shift();
+  shift(): ExtractionQueueTask | undefined {
+    return this.queue.shift()?.run;
   }
 
   /**