@remnic/core 9.7.15 → 9.9.0

package/src/qmd-status.ts

@@ -0,0 +1,186 @@
+/**
+ * QMD status parsing and backlog reporting helpers.
+ *
+ * Extracted from qmd.ts to keep that module under its structural ceiling.
+ * Issue #2019: expose embedding backlog metrics in health and CLI surfaces.
+ */
+
+export interface QmdStatusReport {
+  totalFiles: number | null;
+  embeddedFiles: number | null;
+  pendingEmbeddings: number | null;
+  /** Age in ms of the oldest file still pending embedding, or null if unavailable. */
+  oldestPendingAgeMs: number | null;
+  /** Raw text output from `qmd status` for debugging. */
+  raw: string;
+  /** Error message when the status command fails, if any. */
+  error?: string;
+}
+
+/** Minimal interface for backends that expose QMD status. */
+export interface QmdStatusCapable {
+  status(): Promise<QmdStatusReport>;
+}
+
+/**
+ * Parse `qmd status -c <collection>` text output into structured metrics.
+ * Handles formats like:
+ *   Total files: 200129
+ *   Embedded: 189091 (94.5%)
+ *   Pending embedding: 108186
+ * Returns null fields for unparseable or missing lines.
+ */
+function parseLeadingInt(s: string): number | null {
+  let digits = "";
+  for (const ch of s) {
+    if (ch >= "0" && ch <= "9") digits += ch;
+    else if (ch === "," && digits.length > 0) continue;
+    else break;
+  }
+  return digits.length > 0 ? Number.parseInt(digits, 10) : null;
+}
+
+function parseLeadingDurationMs(s: string): number | null {
+  let digits = "";
+  let i = 0;
+  for (; i < s.length; i++) {
+    if (s[i] >= "0" && s[i] <= "9") digits += s[i];
+    else break;
+  }
+  if (digits.length === 0) return null;
+  const val = Number.parseInt(digits, 10);
+  const unit = s.slice(i).trim();
+  if (unit === "ms") return val;
+  if (unit === "s") return val * 1000;
+  if (unit === "m") return val * 60_000;
+  if (unit === "h") return val * 3_600_000;
+  return null;
+}
+
+export function parseQmdStatusOutput(stdout: string): QmdStatusReport {
+  const raw = stdout;
+  let totalFiles: number | null = null;
+  let embeddedFiles: number | null = null;
+  let pendingEmbeddings: number | null = null;
+  let oldestPendingAgeMs: number | null = null;
+
+  for (const rawLine of stdout.split("\n")) {
+    const line = rawLine.trim().toLowerCase();
+    const colonIdx = line.indexOf(":");
+    if (colonIdx === -1) continue;
+    const key = line.slice(0, colonIdx).trim();
+    const value = line.slice(colonIdx + 1).trim();
+
+    if (key === "total" || key === "total files" || key === "total file") {
+      totalFiles = parseLeadingInt(value);
+    } else if (key === "vectors" || key === "embedded") {
+      embeddedFiles = parseLeadingInt(value);
+    } else if (key === "oldest pending") {
+      oldestPendingAgeMs = parseLeadingDurationMs(value);
+    } else if (key.startsWith("pending")) {
+      pendingEmbeddings = parseLeadingInt(value);
+    }
+  }
+
+  return { totalFiles, embeddedFiles, pendingEmbeddings, oldestPendingAgeMs, raw };
+}
+
+/** Empty status report returned when QMD is unavailable or the command fails. */
+export const EMPTY_QMD_STATUS: QmdStatusReport = {
+  totalFiles: null,
+  embeddedFiles: null,
+  pendingEmbeddings: null,
+  oldestPendingAgeMs: null,
+  raw: "",
+};
+
+/**
+ * Format backlog lines from a pre-resolved status report.
+ * Returns display strings for CLI output; empty array when unavailable.
+ */
+export function formatBacklogLinesFromReport(
+  report: QmdStatusReport | null | undefined,
+  threshold: number,
+): string[] {
+  if (!report) return [];
+  const lines: string[] = [];
+
+  if (report.pendingEmbeddings != null) {
+    lines.push(`  Pending embeddings: ${report.pendingEmbeddings}`);
+    if (threshold > 0 && report.pendingEmbeddings > threshold) {
+      lines.push(`  ⚠ Embedding backlog exceeds threshold (${threshold}) — degraded`);
+    }
+  }
+
+  if (report.oldestPendingAgeMs != null) {
+    const ageMin = Math.round(report.oldestPendingAgeMs / 60_000);
+    lines.push(`  Oldest pending: ${ageMin}m`);
+  }
+
+  return lines;
+}
+
+/**
+ * Fetch QMD status and format backlog lines for CLI output.
+ * Returns empty array when the backend lacks status() or the call fails.
+ */
+export async function renderQmdBacklogStatus(
+  qmd: unknown,
+  threshold: number,
+): Promise<string[]> {
+  const backend = qmd as Partial<QmdStatusCapable> | null;
+  if (!backend || typeof backend.status !== "function") return [];
+  try {
+    const report = await Promise.race([
+      backend.status(),
+      new Promise<null>((resolve) => setTimeout(() => resolve(null), 5_000).unref?.()),
+    ]);
+    if (!report) return [];
+    return formatBacklogLinesFromReport(report, threshold);
+  } catch {
+    return [];
+  }
+}
+
+export type QmdCommandRunner = (args: string[], timeoutMs: number) => Promise<{ stdout: string; stderr: string }>;
+
+/**
+ * Fetch QMD collection status via the `qmd status` command. Returns an
+ * unavailable report (with `error` set) when the command fails.
+ */
+export async function fetchQmdStatus(
+  runQmdCommand: QmdCommandRunner,
+  collection: string,
+  timeoutMs: number,
+): Promise<QmdStatusReport> {
+  try {
+    const { stdout } = await runQmdCommand(["status", "-c", collection], timeoutMs);
+    return parseQmdStatusOutput(stdout);
+  } catch (error) {
+    return { ...EMPTY_QMD_STATUS, error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+/**
+ * Trigger a collection-level embed run via `qmd embed -c <collection>`.
+ * The QMD CLI does not support per-file embed targeting; this triggers
+ * embedding for all pending files in the collection. The prioritized-embed
+ * module debounces and batches these triggers so fresh writes become
+ * searchable within minutes without hammering the CLI on every write.
+ * Returns `{ ok: false }` on failure so callers can reschedule without crashing.
+ */
+export async function embedQmdFiles(
+  runQmdCommand: QmdCommandRunner,
+  collection: string,
+  _filePaths: string[],
+  timeoutMs: number,
+  embedArgs?: string[],
+): Promise<{ ok: boolean; error?: string }> {
+  try {
+    await runQmdCommand(["update", "-c", collection], timeoutMs);
+    await runQmdCommand(embedArgs ?? ["embed", "-c", collection], timeoutMs);
+    return { ok: true };
+  } catch (error) {
+    return { ok: false, error: error instanceof Error ? error.message : String(error) };
+  }
+}

package/src/qmd.ts

@@ -33,6 +33,7 @@ import {
   versionAtLeast,
   type QmdProbeFailureKind,
 } from "./qmd-preflight.js";
+import { fetchQmdStatus, embedQmdFiles, EMPTY_QMD_STATUS, type QmdStatusReport } from "./qmd-status.js";
 // Re-export version-check / probe-preflight helpers (moved to qmd-preflight.ts,
 // issue #1841) so existing imports from "./qmd.js" keep resolving.
 export {
@@ -149,16 +150,13 @@ export interface QmdDoctorReport {
   error?: string;
 }
 
+export { parseQmdStatusOutput } from "./qmd-status.js";
+export type { QmdStatusReport } from "./qmd-status.js";
+
 const QMD_TIMEOUT_MS = 30_000;
-// Daemon timeout for individual search calls. Keep well under RECALL_TIMEOUT_MS (75s) so a
-// slow/loading daemon fails fast and the caller can return early rather than hanging.
-// After the daemon has loaded its index (~90s for 75K files), actual searches complete in <3s.
-// During the loading window, searches will timeout/return [] quickly — this is preferable to
-// blocking the full 75s on every recall request.
-// Note: keep this ≥ 5s to allow normal searches (post-load) to complete reliably.
-// This is the DEFAULT only — operators can override per-client via the
-// `qmdDaemonTimeoutMs` config knob (issue #1335), e.g. to give CPU-only HyDE
-// queries more headroom. The effective value lives in `this.daemonTimeoutMs`.
+// Daemon timeout for search calls. Keep under RECALL_TIMEOUT_MS (75s) so a slow
+// daemon fails fast. Default only — override via `qmdDaemonTimeoutMs` (#1335).
+// Keep ≥ 5s for normal post-load searches to complete reliably.
 const QMD_DAEMON_TIMEOUT_MS = 8_000;
 const QMD_UPDATE_BACKOFF_MS = 15 * 60 * 1000; // 15m
 const QMD_EMBED_BACKOFF_MS = 60 * 60 * 1000; // 60m
@@ -687,10 +685,7 @@ class QmdDaemonSession {
       return this.startPromise;
     }
     this.startPromise = (async () => {
-      // If the process is already running but not yet initialized (e.g. it is still
-      // loading its index after a previous handshake timeout), reuse it instead of
-      // killing and re-spawning. This prevents accumulating zombie qmd-mcp processes
-      // when the daemon takes >15s to load a large collection.
+      // Reuse already-running uninitialized process to avoid zombie accumulation.
       const processAlreadyRunning = this.child != null && !this.child.killed;
       if (!processAlreadyRunning) {
         if (this.child) {
@@ -715,10 +710,7 @@ class QmdDaemonSession {
             if (msg) log.debug(`QMD mcp stderr: ${stripControlChars(msg)}`);
           });
           child.stdin?.on("error", (err) => {
-            // Swallow EPIPE/ERR_STREAM_DESTROYED — these happen when the child
-            // process is killed (e.g. due to recall timeout) and a write arrives
-            // after the pipe is broken.  Without this handler Node.js would throw
-            // an uncaught exception and crash the process.
+            // Swallow EPIPE/ERR_STREAM_DESTROYED from killed child processes.
             log.debug(`QMD mcp stdin error (suppressed): ${err.message}`);
           });
           child.on("error", (err) => {
@@ -1328,12 +1320,8 @@ export class QmdClient implements SearchBackend {
       this.daemonSessionPath = daemonSessionPath;
     }
     try {
-      // Race start() against a short window: if the session is already initialized
-      // this returns instantly; if the process is still loading its index we fail
-      // fast and let the caller fall back gracefully. The underlying start() promise
-      // continues running in the background so the process is NOT killed. On the
-      // next recheck cycle (daemonRecheckIntervalMs=15s) start() returns true
-      // immediately once the handshake has completed.
+      // Race start() against a short window: fail fast if still loading; the
+      // underlying promise continues so the process is NOT killed.
       const PROBE_QUICK_TIMEOUT_MS = 3_000;
       const ok = await Promise.race([
         this.daemonSession.start(),
@@ -1422,10 +1410,7 @@ export class QmdClient implements SearchBackend {
 
     if (this.configuredQmdPath) {
       const configuredPath = this.configuredQmdPath;
-      // Retry only TRANSIENT (timeout/abort) probes of the configured path: a
-      // binary that resolved and ran before is more likely slow under load than
-      // gone. ENOENT/EACCES is a hard misconfiguration and must fail fast.
-      // Issue #1841.
+      // Retry only transient probes; ENOENT/EACCES is a hard misconfiguration (#1841).
       let failureKind: QmdProbeFailureKind = "other";
       let retries = 0;
       let callerCancelled = false;
@@ -1437,10 +1422,7 @@ export class QmdClient implements SearchBackend {
         } catch (err) {
           markProbeFailure(err);
           configuredProbeFailure = this.lastCliProbeError;
-          // Detect CALLER cancellation FIRST: an aborted signal / AbortError is
-          // non-actionable noise — the caller chose to stop. Other QMD paths
-          // treat it via `isCallerCancellation`; do the same here so a cancelled
-          // probe never reads as a transient host-load failure. Issue #1841.
+          // Detect caller cancellation first — non-actionable noise (#1841).
           if (isCallerCancellation(err, options.signal)) {
             callerCancelled = true;
             break;
@@ -1468,11 +1450,7 @@ export class QmdClient implements SearchBackend {
           break;
         }
       }
-      // Distinct operator-facing warnings so a slow binary is not mistaken for
-      // a misconfiguration (and vice versa). Do not hard-fail here: fall through
-      // to PATH/fallback probing so recall stays healthy when config is stale.
-      // Caller cancellation is silent noise (issue #1841): suppress all warnings
-      // for it exactly as the other QMD paths do.
+      // Distinct warnings for slow binary vs misconfiguration; suppress on caller cancellation (#1841).
       if (!callerCancelled) {
         if (failureKind === "transient") {
           this.logCliProbeWarning(
@@ -1736,6 +1714,21 @@ export class QmdClient implements SearchBackend {
     }
   }
 
+  /**
+   * Query QMD collection status for embedding backlog metrics.
+   * Runs `qmd status -c <collection>` and parses the text output.
+   * Returns null fields when the command fails or output is unparseable.
+   */
+  async status(): Promise<QmdStatusReport> {
+    if (!this.isAvailable()) {
+      return EMPTY_QMD_STATUS;
+    }
+    if (!this.qmdCapabilities.safeStatusDeviceProbe) {
+      return EMPTY_QMD_STATUS;
+    }
+    return fetchQmdStatus((args, timeoutMs) => this.runQmdCommand(args, timeoutMs), this.collection, QMD_TIMEOUT_MS);
+  }
+
   isDaemonMode(): boolean {
     return this.daemonAvailable;
   }
@@ -1947,23 +1940,14 @@ export class QmdClient implements SearchBackend {
     // repeated queries within the same recall cycle (e.g., primary + hybrid
     // top-up, or conversation recall using the same collection).
     const optionsFingerprint = searchOptions ? JSON.stringify(searchOptions) : "";
-    // The QMD search cache is a process-global keyed map (memory-cache.ts), so the
-    // key must capture every input that changes the result — including the daemon
-    // and subprocess strategies. Otherwise two QmdClient instances (or a reloaded
-    // config) with different strategies collide within the TTL and one plan serves
-    // another plan's cached results. Issue #1335 (codex review on #1422).
+    // Key must capture daemon/subprocess strategies to avoid cross-instance collisions (#1335).
     const strategyFingerprint = `${this.qmdSearchStrategy}:${this.qmdSubprocessStrategy}`;
     const cacheKey = createHash("sha256")
       .update(`${strategyFingerprint}:${col}:${n}:${optionsFingerprint}:${trimmed}`)
       .digest("hex");
     const cached = getCachedQmdSearch(cacheKey);
     if (cached) {
-      // No degradation fires on a cache hit BY DESIGN (#1536): only
-      // trustworthy results are ever cached (degraded empties are excluded
-      // at the write below), so a TTL hit is a healthy serve of a recently
-      // valid answer — the backend's live state is irrelevant because no
-      // live call is attempted. Reporting unavailability here would fabricate
-      // a degradation for a recall that was not degraded.
+      // No degradation on cache hit by design (#1536): only trustworthy results are cached.
       log.debug(`QMD search cache hit (${cached.length} results)`);
       return cached as QmdSearchResult[];
     }
@@ -2780,6 +2764,22 @@ export class QmdClient implements SearchBackend {
     await this.runEmbedForCollection(collection, { perCollectionThrottle: true, strict: true });
   }
 
+  /** Trigger a collection-level embed for fresh writes (debounced by prioritized-embed). */
+  async embedFiles(filePaths: string[]): Promise<boolean> {
+    if (this.available === false || filePaths.length === 0) {
+      return false;
+    }
+    const result = await embedQmdFiles(
+      (args, timeoutMs) => this.runQmdCommand(args, timeoutMs),
+      this.collection,
+      filePaths,
+      300_000,
+      this.buildEmbedArgs(this.collection),
+    );
+    if (result.ok) clearQmdResultCaches();
+    return result.ok;
+  }
+
   private async runEmbedForCollection(
     collection: string,
     options: { perCollectionThrottle: boolean; strict?: boolean },

package/src/recall-budget-config.test.ts

@@ -14,6 +14,36 @@ test("parseConfig applies recall timeout and qmd recall cache defaults", () => {
   assert.equal(config.qmdRecallCacheMaxEntries, 128);
 });
 
+test("parseConfig applies the default profile share cap", () => {
+  assert.equal(parseConfig({}).recallProfileMaxRatio, 0.3);
+});
+
+test("parseConfig accepts a configurable profile share cap", () => {
+  assert.equal(
+    parseConfig({ recallProfileMaxRatio: 0.5 }).recallProfileMaxRatio,
+    0.5,
+  );
+});
+
+test("parseConfig preserves profile share cap boundaries", () => {
+  assert.equal(parseConfig({ recallProfileMaxRatio: 0 }).recallProfileMaxRatio, 0);
+  assert.equal(parseConfig({ recallProfileMaxRatio: 1 }).recallProfileMaxRatio, 1);
+});
+
+test("parseConfig rejects an explicit null profile share cap", () => {
+  assert.throws(
+    () => parseConfig({ recallProfileMaxRatio: null }),
+    /recallProfileMaxRatio must be a finite number in \[0, 1\]/,
+  );
+});
+
+test("parseConfig rejects an invalid profile share cap", () => {
+  assert.throws(
+    () => parseConfig({ recallProfileMaxRatio: 1.1 }),
+    /recallProfileMaxRatio must be a finite number in \[0, 1\]/,
+  );
+});
+
 test("parseConfig respects explicit recall timeout and qmd recall cache settings", () => {
   const config = parseConfig({
     recallOuterTimeoutMs: 18_000,

package/src/recall-cold-deadline.test.ts

@@ -0,0 +1,149 @@
+/**
+ * recall-cold-deadline.test.ts — issue #1907.
+ *
+ * Pins the task-level cancellation contract of runColdStepWithinDeadline
+ * inside RecallSearchPipelineCoordinator.applyColdFallbackPipeline:
+ *   - when the per-step deadline wins, the losing cold task's INJECTED signal
+ *     is aborted (so an orphaned archive scan stops cooperatively) and the
+ *     step returns its fallback (fail-open);
+ *   - a task-level deadline must NOT abort the request-level signal;
+ *   - a task that completes normally (no deadline) never aborts the injected
+ *     step signal.
+ */
+
+import assert from "node:assert/strict";
+import os from "node:os";
+import path from "node:path";
+import { mkdtemp, rm } from "node:fs/promises";
+import test from "node:test";
+
+import { parseConfig } from "./config.js";
+import {
+  RecallSearchPipelineCoordinator,
+  type RecallSearchPipelineDeps,
+} from "./orchestration/recall-search-pipeline.js";
+import type { PluginConfig, QmdSearchResult, RecallPlanMode } from "./types.js";
+
+async function coldConfig() {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-1907-cold-"));
+  const config = parseConfig({
+    openaiApiKey: "sk-test",
+    memoryDir,
+    workspaceDir: path.join(memoryDir, "workspace"),
+    qmdEnabled: false,
+    namespacesEnabled: false,
+  });
+  return { memoryDir, config };
+}
+
+/**
+ * Minimal deps for the archive-scan branch. qmd.isAvailable() === false forces
+ * the cold-qmd block to be skipped, so control reaches the archive-scan step;
+ * an empty archive result returns [] before any namespace/storage-router work,
+ * keeping the stub surface tight. The cast is a deliberate test double.
+ */
+function coldDeps(
+  config: PluginConfig,
+  searchLongTermArchiveFallback: RecallSearchPipelineDeps["searchLongTermArchiveFallback"],
+): RecallSearchPipelineDeps {
+  return {
+    config,
+    qmd: { isAvailable: () => false },
+    namespaceFromPath: () => "default",
+    searchLongTermArchiveFallback,
+  } as unknown as RecallSearchPipelineDeps;
+}
+
+test("#1907: cold archive-scan deadline aborts the injected step signal, returns fallback, leaves the request signal intact", async () => {
+  const { memoryDir, config } = await coldConfig();
+  try {
+    const stuck = Promise.withResolvers<QmdSearchResult[]>();
+    let capturedStepSignal: AbortSignal | undefined;
+    // Observable side-effect channel. A cooperatively-cancelled worker sees
+    // stepSignal.aborted === true by the time it settles late and performs no
+    // write; if the deadline's abort wiring is removed the signal never aborts,
+    // so the late completion leaks "late" here and the assertion below fails.
+    const lateWrites: string[] = [];
+    const abandonedTaskSettled = Promise.withResolvers<void>();
+    const deps = coldDeps(config, async (_prompt, _ns, _limit, _prefilter, abortSignal) => {
+      capturedStepSignal = abortSignal;
+      const late = await stuck.promise; // does not settle before the deadline wins
+      if (!abortSignal?.aborted) {
+        for (const hit of late) lateWrites.push(hit.docid);
+      }
+      abandonedTaskSettled.resolve();
+      return late;
+    });
+    const coordinator = new RecallSearchPipelineCoordinator(deps);
+
+    const requestController = new AbortController();
+    const result = await coordinator.applyColdFallbackPipeline({
+      prompt: "long term recall",
+      recallNamespaces: ["default"],
+      recallResultLimit: 5,
+      recallMode: "full" as RecallPlanMode,
+      deadlineAtMs: Date.now() + 120,
+      abortSignal: requestController.signal,
+    });
+
+    assert.deepEqual(result, [], "the step returns its fallback when the deadline wins");
+    assert.ok(capturedStepSignal, "archive scan received an injected step signal");
+    assert.equal(
+      capturedStepSignal!.aborted,
+      true,
+      "the injected step signal is aborted on deadline so the losing task stops",
+    );
+    assert.equal(
+      requestController.signal.aborted,
+      false,
+      "a task-level deadline must NOT abort the request-level signal",
+    );
+
+    // The abandoned task's LATE completion has no observable side effect: a
+    // cooperative worker sees its injected signal aborted and performs no write.
+    // Deterministic — we await the abandoned task's own settlement, not a bare
+    // microtask flush.
+    stuck.resolve([{ docid: "late", path: "/facts/late.md", snippet: "late", score: 1 }]);
+    await abandonedTaskSettled.promise;
+    assert.deepEqual(
+      lateWrites,
+      [],
+      "the abandoned task observed its abort and performed no late write",
+    );
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("#1907: a cold step that completes before its deadline never aborts the injected step signal", async () => {
+  const { memoryDir, config } = await coldConfig();
+  try {
+    let capturedStepSignal: AbortSignal | undefined;
+    const deps = coldDeps(config, async (_prompt, _ns, _limit, _prefilter, abortSignal) => {
+      capturedStepSignal = abortSignal;
+      return []; // resolves immediately, well within the deadline
+    });
+    const coordinator = new RecallSearchPipelineCoordinator(deps);
+
+    const requestController = new AbortController();
+    const result = await coordinator.applyColdFallbackPipeline({
+      prompt: "long term recall",
+      recallNamespaces: ["default"],
+      recallResultLimit: 5,
+      recallMode: "full" as RecallPlanMode,
+      deadlineAtMs: Date.now() + 30_000,
+      abortSignal: requestController.signal,
+    });
+
+    assert.deepEqual(result, [], "empty archive returns []");
+    assert.ok(capturedStepSignal, "archive scan received an injected step signal");
+    assert.equal(
+      capturedStepSignal!.aborted,
+      false,
+      "normal completion must not abort the injected step signal",
+    );
+    assert.equal(requestController.signal.aborted, false, "request signal untouched");
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});

package/src/recall-concurrency-config.ts

@@ -0,0 +1,28 @@
+/**
+ * Recall concurrency config parsing (issue #1906), extracted from config.ts to
+ * keep that grandfathered file within its structural-ratchet ceiling (#1520/#1995).
+ * The parsed fields still live on {@link PluginConfig}; this only relocates the
+ * coercion/validation logic.
+ */
+import { coerceBool, coerceNumber } from "./connectors/coerce.js";
+import type { PluginConfig } from "./types.js";
+
+/**
+ * Parse the per-principal recall concurrency knobs from raw config.
+ *
+ * `recallMaxConcurrentPerPrincipal` accepts only finite integers >= 0 so `0`
+ * means "unlimited" deliberately. A fractional typo like `0.5` must NOT floor to
+ * `0` (which would silently disable the cap); it falls back to the default 4
+ * (AGENTS.md #1/#17).
+ */
+export function parseRecallConcurrencyConfig(
+  cfg: Record<string, unknown>,
+): Pick<PluginConfig, "recallMaxConcurrentPerPrincipal" | "recallSingleFlightEnabled"> {
+  return {
+    recallMaxConcurrentPerPrincipal: (() => {
+      const n = coerceNumber(cfg.recallMaxConcurrentPerPrincipal);
+      return n !== undefined && Number.isInteger(n) && n >= 0 ? n : 4;
+    })(),
+    recallSingleFlightEnabled: coerceBool(cfg.recallSingleFlightEnabled) ?? true,
+  };
+}

package/src/recall-memory-map.ts

@@ -0,0 +1,74 @@
+import type { MemoryFile, QmdSearchResult } from "./types.js";
+
+export function memoryMapKey(result: Pick<QmdSearchResult, "namespace" | "path">): string {
+  // No namespace -> bare path (backward-compatible with path-keyed lookups).
+  // Namespaced -> composite so the same relative path across namespaces stays distinct.
+  return result.namespace ? `${result.namespace}\0${result.path}` : result.path;
+}
+
+export function memoryForResult(
+  memoryByPath: ReadonlyMap<string, MemoryFile>,
+  result: Pick<QmdSearchResult, "namespace" | "path">,
+): MemoryFile | undefined {
+  return memoryByPath.get(memoryMapKey(result));
+}
+
+export function hasMemoryForResult(
+  memoryByPath: ReadonlyMap<string, MemoryFile>,
+  result: Pick<QmdSearchResult, "namespace" | "path">,
+): boolean {
+  return memoryByPath.has(memoryMapKey(result));
+}
+
+export function markResultKey(
+  keys: Set<string>,
+  result: Pick<QmdSearchResult, "namespace" | "path">,
+): void {
+  keys.add(memoryMapKey(result));
+}
+
+export function resultHasKey(
+  keys: ReadonlySet<string>,
+  result: Pick<QmdSearchResult, "namespace" | "path">,
+): boolean {
+  return keys.has(memoryMapKey(result));
+}
+
+/**
+ * Merge recall results from multiple producers, deduplicating by the composite
+ * (namespace, path) identity so the same memory found by a fanout hit and a
+ * seed/hybrid/archive hit collapses to ONE entry instead of being injected and
+ * access-tracked twice (#2020). The namespace is resolved the SAME way on every
+ * producer — carried when present, else derived from the path — and stamped on
+ * the surviving result. Highest score wins; a surviving result keeps its own
+ * snippet, falling back to the displaced entry's snippet when empty. Results are
+ * returned sorted by descending score and capped to `limit`.
+ */
+export function dedupeResultsByNamespace(
+  results: readonly QmdSearchResult[],
+  namespaceFromPath: (path: string) => string,
+  limit: number,
+  options?: {
+    transportFallback?: QmdSearchResult["transport"];
+    filter?: (result: QmdSearchResult) => boolean;
+  },
+): QmdSearchResult[] {
+  const merged = new Map<string, QmdSearchResult>();
+  for (const result of results) {
+    const namespace = result.namespace ?? namespaceFromPath(result.path);
+    const key = `${namespace}\0${result.path || result.docid}`;
+    const existing = merged.get(key);
+    if (existing && result.score <= existing.score) continue;
+    merged.set(key, {
+      ...result,
+      namespace,
+      ...(options?.transportFallback !== undefined
+        ? { transport: result.transport ?? options.transportFallback }
+        : {}),
+      snippet: result.snippet || existing?.snippet || "",
+    });
+  }
+  let out = [...merged.values()];
+  if (options?.filter) out = out.filter(options.filter);
+  return out.sort((a, b) => b.score - a.score).slice(0, limit);
+}