@remnic/core 9.69.56 → 9.69.58

package/src/recall-why-renderer.ts

@@ -0,0 +1,142 @@
+/**
+ * Shared renderer for the recall-miss diagnosis (issue #3033).
+ *
+ * CLI, HTTP, and MCP all render the same {@link RecallWhyReport} through
+ * this module — never their own formatting (AGENTS.md rule 22, the same
+ * contract `recall-xray-renderer.ts` and `recall-explain-renderer.ts`
+ * hold).
+ */
+
+import type { RecallWhyReport } from "./recall-why.js";
+
+export type RecallWhyFormat = "json" | "markdown";
+
+export const RECALL_WHY_FORMATS: readonly RecallWhyFormat[] = ["json", "markdown"] as const;
+
+/**
+ * Validate and coerce a user-provided `--format` / `format` argument.
+ * Unknown values throw an error listing the valid options rather than
+ * silently defaulting (Review Prevention Checklist #1 / #39).
+ * `undefined` / `null` defaults to `"markdown"`.
+ */
+export function parseRecallWhyFormat(value: unknown): RecallWhyFormat {
+  if (value === undefined || value === null) return "markdown";
+  if (typeof value !== "string") {
+    throw new Error(`--format expects one of ${RECALL_WHY_FORMATS.join(", ")}; got ${typeof value}`);
+  }
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "json" || normalized === "markdown") return normalized;
+  throw new Error(`--format expects one of ${RECALL_WHY_FORMATS.join(", ")}; got ${JSON.stringify(value)}`);
+}
+
+export function renderRecallWhy(report: RecallWhyReport, format: RecallWhyFormat): string {
+  return format === "json" ? renderRecallWhyJson(report) : renderRecallWhyMarkdown(report);
+}
+
+/** Deterministic JSON encoding of the report. */
+export function renderRecallWhyJson(report: RecallWhyReport): string {
+  return JSON.stringify(report, null, 2);
+}
+
+export function renderRecallWhyMarkdown(report: RecallWhyReport): string {
+  const lines: string[] = ["# Recall diagnosis", ""];
+  lines.push(`- query: \`${report.query}\``);
+  lines.push(`- planner mode: \`${report.plannerMode}\``);
+  if (report.namespace !== undefined) lines.push(`- namespace: \`${report.namespace}\``);
+  lines.push(
+    `- recall namespaces: ${
+      report.recallNamespaces.length > 0 ? report.recallNamespaces.map((ns) => `\`${ns}\``).join(", ") : "_none_"
+    }`
+  );
+  lines.push(`- applied result limit: ${report.appliedResultLimit}`);
+  lines.push(
+    `- recalled: ${
+      report.recalledMemoryIds.length > 0 ? report.recalledMemoryIds.map((id) => `\`${id}\``).join(", ") : "_nothing_"
+    }`
+  );
+  lines.push("");
+
+  if (report.failure !== undefined) {
+    // An outage is never rendered as an empty pipeline (checklist #22).
+    lines.push("## Backend unavailable", "");
+    lines.push(`The diagnosis could not run: \`${report.failure.reason}\` — ${report.failure.detail}`);
+    lines.push("");
+    lines.push("This is a backend outage, not a zero-candidate recall.");
+    lines.push("");
+  }
+
+  lines.push("## Stages", "");
+  lines.push("| stage | considered | admitted | detail |");
+  lines.push("| --- | --- | --- | --- |");
+  for (const stage of report.stages) {
+    lines.push(`| ${stage.stage} | ${stage.considered} | ${stage.admitted} | ${escapeCell(stage.reason)} |`);
+  }
+  lines.push("");
+
+  const dropped = report.stages.filter((stage) => stage.drops.length > 0);
+  if (dropped.length > 0) {
+    lines.push("## Drops", "");
+    for (const stage of dropped) {
+      lines.push(`### ${stage.stage}`, "");
+      for (const drop of stage.drops) {
+        lines.push(`- \`${drop.memoryId}\` (${drop.path}) — ${drop.reason}: ${drop.detail}`);
+      }
+      lines.push("");
+    }
+  }
+
+  const expectation = report.expectation;
+  if (expectation !== undefined) {
+    lines.push("## Expected memory", "");
+    lines.push(`- expect: \`${expectation.expect}\``);
+    if (!expectation.matched) {
+      lines.push("- matched: **no stored memory matches**");
+    } else {
+      lines.push(`- memory id: \`${expectation.memoryId ?? "unknown"}\``);
+      lines.push(`- path: \`${expectation.path ?? "unknown"}\``);
+    }
+    lines.push("");
+    if (expectation.recalled) {
+      lines.push("**Recalled.** This memory survived every stage and was injected.");
+    } else {
+      lines.push(
+        `**Dropped at ${expectation.stage ?? "unknown"}: ${expectation.reason ?? "unknown"}** — ${
+          expectation.detail ?? "no detail recorded"
+        }`
+      );
+      if (expectation.remediation !== undefined) {
+        lines.push("");
+        lines.push(`Remediation: ${expectation.remediation}`);
+      }
+    }
+    lines.push("");
+  }
+
+  return `${lines.join("\n").trimEnd()}\n`;
+}
+
+/** One-line summary suited to a terminal or a chat reply. */
+export function summarizeRecallWhy(report: RecallWhyReport): string {
+  if (report.failure !== undefined) {
+    return `backend_unavailable: ${report.failure.detail}`;
+  }
+  const expectation = report.expectation;
+  if (expectation === undefined) {
+    return `recalled ${report.recalledMemoryIds.length} memories (planner mode ${report.plannerMode})`;
+  }
+  if (!expectation.matched) {
+    return `no stored memory matches ${JSON.stringify(expectation.expect)}`;
+  }
+  if (expectation.recalled) {
+    return `${expectation.memoryId ?? expectation.expect} was recalled`;
+  }
+  return `dropped at ${expectation.stage ?? "unknown"}: ${expectation.reason ?? "unknown"}${
+    expectation.detail !== undefined ? ` (${expectation.detail})` : ""
+  }`;
+}
+
+function escapeCell(value: string | undefined): string {
+  // A pipe inside a markdown table cell breaks the row; the filter ladder
+  // joins with "; " and can legitimately contain one.
+  return value === undefined ? "" : value.replace(/\\/g, "\\\\").replace(/\|/g, "\\|");
+}

package/src/recall-why-service.test.ts

@@ -0,0 +1,306 @@
+/**
+ * Service-binding tests for the recall-miss diagnosis (issue #3033).
+ *
+ * `recall-why.test.ts` covers the pure stage attribution. This file covers
+ * the orchestrator binding: the namespace ACL gate, the expected-memory
+ * lookup across readable namespaces, and — the reason the pipeline carries a
+ * `degradationSink` at all — that a backend which fails MID-recall is
+ * reported as `backend_unavailable` and never as an empty pipeline
+ * (Review Prevention Checklist #22).
+ *
+ * All fixture data is synthetic.
+ */
+
+import assert from "node:assert/strict";
+import { mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { parseConfig } from "./config.js";
+import type { Orchestrator } from "./orchestrator.js";
+import { runRecallWhy } from "./recall-why-service.js";
+import { buildXraySnapshot, type RecallXraySnapshot } from "./recall-xray.js";
+import type { SearchDegradation } from "./search/port.js";
+import type { MemoryFile, PluginConfig } from "./types.js";
+
+const QUERY = "what did we decide about the retention window?";
+
+function memoryFile(overrides: Partial<MemoryFile["frontmatter"]> & { id: string }): MemoryFile {
+  const { id, ...rest } = overrides;
+  return {
+    path: `facts/2026-01-02/${id}.md`,
+    frontmatter: {
+      id,
+      category: "fact",
+      created: "2026-01-02T00:00:00.000Z",
+      updated: "2026-01-02T00:00:00.000Z",
+      ...rest,
+    },
+    content: "Synthetic fixture content.",
+  } as MemoryFile;
+}
+
+function emptySnapshot(query: string): RecallXraySnapshot {
+  return buildXraySnapshot({
+    query,
+    results: [],
+    headroomResults: [],
+    appliedResults: [],
+    appliedResultLimit: 4,
+    budget: { chars: 4096, used: 0 },
+    now: () => 1_700_000_000_000,
+    snapshotIdGenerator: () => "00000000-0000-4000-8000-000000000000",
+  });
+}
+
+interface StubOptions {
+  config: PluginConfig;
+  memories?: MemoryFile[];
+  /** Degradations the stub pipeline pushes into the caller's sink. */
+  degradations?: SearchDegradation[];
+  qmdAvailable?: boolean;
+  /** Thrown by the stub recall, to exercise the fault path. */
+  recallError?: Error;
+}
+
+interface Stub {
+  orchestrator: Orchestrator;
+  /** Namespaces the expected-memory lookup actually read. */
+  readNamespaces: string[];
+  recallCalls: number;
+  /** True when the service handed the pipeline a degradation sink. */
+  sinkSupplied: boolean;
+}
+
+function makeStub(options: StubOptions): Stub {
+  const stub: Stub = {
+    readNamespaces: [],
+    recallCalls: 0,
+    sinkSupplied: false,
+    orchestrator: undefined as unknown as Orchestrator,
+  };
+  stub.orchestrator = {
+    config: options.config,
+    qmd: { isAvailable: () => options.qmdAvailable ?? true },
+    async recallWithXrayCapture(
+      prompt: string,
+      _sessionKey?: string,
+      invocation?: { degradationSink?: SearchDegradation[] }
+    ) {
+      stub.recallCalls += 1;
+      stub.sinkSupplied = Array.isArray(invocation?.degradationSink);
+      // Stand in for the real pipeline: it fills the SAME array it was
+      // handed, which is exactly what `options.degradationSink ?? []` in
+      // recall-internal.ts makes possible.
+      for (const degradation of options.degradations ?? []) {
+        invocation?.degradationSink?.push(degradation);
+      }
+      if (options.recallError !== undefined) throw options.recallError;
+      return { result: "", snapshot: emptySnapshot(prompt), recallStartedAt: 0 };
+    },
+    async getStorageForNamespace(namespace: string) {
+      stub.readNamespaces.push(namespace);
+      return {
+        async readAllMemories() {
+          return options.memories ?? [];
+        },
+      };
+    },
+  } as unknown as Orchestrator;
+  return stub;
+}
+
+async function withConfig<T>(raw: Record<string, unknown>, run: (config: PluginConfig) => Promise<T>): Promise<T> {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-why-svc-"));
+  try {
+    return await run(parseConfig({ memoryDir, ...raw }));
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+}
+
+const identityResolver = { resolveNamespace: (namespace?: string) => namespace ?? "default" };
+
+// ─── backend failure is an outage, never an empty pipeline (#22) ───────────
+
+test("a degradation raised mid-recall reports backend_unavailable, not zero candidates", async () => {
+  await withConfig({ qmdEnabled: true }, async (config) => {
+    const stub = makeStub({
+      config,
+      // The availability probe passes; the failure happens during the recall.
+      qmdAvailable: true,
+      degradations: [{ backend: "qmd", code: "daemon_timeout", detail: "no response in 5000ms" }],
+    });
+    const response = await runRecallWhy({ orchestrator: stub.orchestrator, ...identityResolver }, { query: QUERY });
+    assert.equal(stub.sinkSupplied, true, "the service must hand the pipeline a degradation sink");
+    assert.equal(response.reportFound, true);
+    assert.equal(response.report?.ok, false);
+    assert.equal(response.report?.failure?.reason, "backend_unavailable");
+    assert.match(response.report?.failure?.detail ?? "", /qmd:daemon_timeout/);
+    assert.match(response.report?.failure?.detail ?? "", /no response in 5000ms/);
+    // Only the retrieval stage is reported: no downstream stage ran, so none
+    // may claim it "considered 0".
+    assert.deepEqual(
+      response.report?.stages.map((s) => s.stage),
+      ["retrieval"]
+    );
+    assert.match(response.summary ?? "", /backend_unavailable/);
+  });
+});
+
+test("a partial vector-tier degradation is not an outage — lexical still answered", async () => {
+  await withConfig({ qmdEnabled: true }, async (config) => {
+    const stub = makeStub({
+      config,
+      degradations: [{ backend: "qmd", code: "vector_tier_unavailable" }],
+    });
+    const response = await runRecallWhy({ orchestrator: stub.orchestrator, ...identityResolver }, { query: QUERY });
+    assert.equal(response.report?.ok, true, "a degraded-but-real result set is not a failure");
+    assert.equal(response.report?.failure, undefined);
+  });
+});
+
+test("a recall that throws reports the fault as an outage, carrying what it observed", async () => {
+  await withConfig({ qmdEnabled: true }, async (config) => {
+    const stub = makeStub({
+      config,
+      degradations: [{ backend: "qmd", code: "subprocess_error" }],
+      recallError: new Error("search subprocess exited with code 1"),
+    });
+    const response = await runRecallWhy({ orchestrator: stub.orchestrator, ...identityResolver }, { query: QUERY });
+    assert.equal(response.report?.ok, false);
+    assert.match(response.report?.failure?.detail ?? "", /qmd:subprocess_error/);
+    assert.match(response.report?.failure?.detail ?? "", /subprocess exited with code 1/);
+  });
+});
+
+test("an unavailable backend is refused before the recall runs", async () => {
+  await withConfig({ qmdEnabled: true }, async (config) => {
+    const stub = makeStub({ config, qmdAvailable: false });
+    const response = await runRecallWhy({ orchestrator: stub.orchestrator, ...identityResolver }, { query: QUERY });
+    assert.equal(response.report?.ok, false);
+    assert.equal(response.report?.failure?.reason, "backend_unavailable");
+    assert.equal(stub.recallCalls, 0, "no point paying for a recall against a dead backend");
+  });
+});
+
+test("an honest empty recall stays ok:true", async () => {
+  await withConfig({ qmdEnabled: true }, async (config) => {
+    const stub = makeStub({ config });
+    const response = await runRecallWhy({ orchestrator: stub.orchestrator, ...identityResolver }, { query: QUERY });
+    assert.equal(response.report?.ok, true);
+    assert.equal(response.report?.failure, undefined);
+    assert.equal(stub.recallCalls, 1, "one diagnosis costs exactly one recall");
+  });
+});
+
+// ─── --expect resolution against the store ────────────────────────────────
+
+test("--expect resolves an exact id and reports the stage that dropped it", async () => {
+  await withConfig({ qmdEnabled: true }, async (config) => {
+    const stub = makeStub({
+      config,
+      memories: [memoryFile({ id: "fact-kept-0001" }), memoryFile({ id: "fact-gone-0002", status: "superseded" })],
+    });
+    const response = await runRecallWhy(
+      { orchestrator: stub.orchestrator, ...identityResolver },
+      { query: QUERY, expect: "fact-gone-0002" }
+    );
+    assert.equal(response.report?.expectation?.matched, true);
+    assert.equal(response.report?.expectation?.memoryId, "fact-gone-0002");
+    assert.equal(response.report?.expectation?.stage, "policy-filter");
+    assert.equal(response.report?.expectation?.reason, "status-filter");
+    assert.equal(response.report?.expectation?.detail, "status=superseded");
+  });
+});
+
+test("a memory with no frontmatter status is treated as active, not status-filtered", async () => {
+  await withConfig({ qmdEnabled: true }, async (config) => {
+    const stub = makeStub({ config, memories: [memoryFile({ id: "fact-untagged-0003" })] });
+    const response = await runRecallWhy(
+      { orchestrator: stub.orchestrator, ...identityResolver },
+      { query: QUERY, expect: "fact-untagged-0003" }
+    );
+    assert.equal(response.report?.expectation?.matched, true);
+    assert.notEqual(response.report?.expectation?.reason, "status-filter");
+    assert.equal(response.report?.expectation?.reason, "not-a-candidate");
+  });
+});
+
+test("an unmatched --expect says nothing matched rather than naming a stage falsely", async () => {
+  await withConfig({ qmdEnabled: true }, async (config) => {
+    const stub = makeStub({ config, memories: [memoryFile({ id: "fact-kept-0001" })] });
+    const response = await runRecallWhy(
+      { orchestrator: stub.orchestrator, ...identityResolver },
+      { query: QUERY, expect: "fact-absent-9999" }
+    );
+    assert.equal(response.report?.expectation?.matched, false);
+    assert.match(response.report?.expectation?.detail ?? "", /no stored memory matches/);
+  });
+});
+
+// ─── namespace scope (rule 42 / checklist #30) ─────────────────────────────
+
+test("a namespace the principal cannot read is refused without running a recall", async () => {
+  await withConfig(
+    {
+      namespacesEnabled: true,
+      namespacePolicies: [{ name: "team-beta", readPrincipals: ["beta-only"] }],
+    },
+    async (config) => {
+      const stub = makeStub({ config, memories: [memoryFile({ id: "fact-secret-0001" })] });
+      const response = await runRecallWhy(
+        { orchestrator: stub.orchestrator, ...identityResolver },
+        { query: QUERY, namespace: "team-beta", authenticatedPrincipal: "someone-else" }
+      );
+      assert.equal(response.reportFound, false, "an unreadable namespace yields no report");
+      assert.equal(response.report, undefined);
+      assert.equal(stub.recallCalls, 0);
+      assert.deepEqual(stub.readNamespaces, [], "and no store in it may be read");
+    }
+  );
+});
+
+test("with namespaces on and no identity supplied the diagnosis refuses", async () => {
+  await withConfig({ namespacesEnabled: true }, async (config) => {
+    const stub = makeStub({ config });
+    const response = await runRecallWhy({ orchestrator: stub.orchestrator, ...identityResolver }, { query: QUERY });
+    assert.equal(response.reportFound, false);
+    assert.equal(stub.recallCalls, 0);
+  });
+});
+
+test("the expected-memory lookup reads only the namespaces the recall is scoped to", async () => {
+  await withConfig({ qmdEnabled: true }, async (config) => {
+    const stub = makeStub({ config, memories: [memoryFile({ id: "fact-kept-0001" })] });
+    await runRecallWhy(
+      { orchestrator: stub.orchestrator, ...identityResolver },
+      // `expect` deliberately matches NOTHING: an early exact-id hit would
+      // stop the scan after the first namespace and hide a widened scope,
+      // so the lookup is forced to exhaust every namespace it is given.
+      { query: QUERY, namespace: "team-alpha", expect: "fact-absent-9999" }
+    );
+    assert.deepEqual(
+      stub.readNamespaces,
+      ["team-alpha"],
+      "an explicitly scoped request must not scan any other namespace"
+    );
+  });
+});
+
+// ─── input validation (#1 / #45) ───────────────────────────────────────────
+
+test("an empty or whitespace-only query is rejected before namespace resolution", async () => {
+  await withConfig({ qmdEnabled: true }, async (config) => {
+    const stub = makeStub({ config });
+    for (const bad of ["", "   ", "\t"]) {
+      await assert.rejects(
+        () => runRecallWhy({ orchestrator: stub.orchestrator, ...identityResolver }, { query: bad }),
+        /query is required and must be non-empty/,
+        `query ${JSON.stringify(bad)} must be rejected`
+      );
+    }
+    assert.equal(stub.recallCalls, 0);
+  });
+});

package/src/recall-why-service.ts

@@ -0,0 +1,218 @@
+/**
+ * Access-surface binding for the recall-miss diagnosis (issue #3033).
+ *
+ * `recall-why.ts` holds the stage logic and a port; this module binds that
+ * port to the live orchestrator. It lives beside `access-recall-surface.ts`
+ * rather than inside it because that file is at its file-size ratchet
+ * ceiling (AGENTS.md: extract the addition to a sibling module).
+ *
+ * Namespace scope is enforced BEFORE the recall fires and the expected-memory
+ * lookup is confined to namespaces the caller may read, so the diagnosis can
+ * never confirm the existence of a memory in a namespace the caller has no
+ * read access to. Read path and write path resolve through the same namespace
+ * layer (Review Prevention Checklist #30): the lookup consumes exactly the
+ * `recallNamespacesForPrincipal` set the recall itself is scoped by.
+ */
+
+import { resolveNamespaceCapabilities, resolveQmdCapabilities } from "./capabilities.js";
+import { planRecallMode } from "./intent.js";
+import { canReadNamespace, recallNamespacesForPrincipal, resolvePrincipal } from "./namespaces/principal.js";
+import { isGenericRecallExcludedPath } from "./orchestration/generic-recall-paths.js";
+import type { Orchestrator } from "./orchestrator.js";
+import {
+  explainRecallMiss,
+  RecallWhyInputError,
+  type RecallWhyDeps,
+  type RecallWhyMemoryRef,
+  type RecallWhyReport,
+} from "./recall-why.js";
+import { summarizeRecallWhy } from "./recall-why-renderer.js";
+import type { SearchDegradation } from "./search/port.js";
+import type { MemoryFile, MemoryStatus } from "./types.js";
+
+/**
+ * Degradation codes that mean the search backend could NOT answer, so an
+ * empty pipeline carries no information. `vector_tier_unavailable` is
+ * excluded on purpose: the lexical tier still answered, so the result set
+ * is degraded but real.
+ */
+const FATAL_DEGRADATION_CODES: Partial<Record<SearchDegradation["code"], true>> = {
+  backend_unavailable: true,
+  backend_error: true,
+  daemon_timeout: true,
+  daemon_loading: true,
+  subprocess_error: true,
+  deadline_exceeded: true,
+  remote_error: true,
+};
+
+function describeDegradations(degradations: readonly SearchDegradation[]): string {
+  return degradations.map((d) => `${d.backend}:${d.code}${d.detail !== undefined ? ` (${d.detail})` : ""}`).join("; ");
+}
+
+export interface RecallWhyRequest {
+  query: string;
+  /** Memory id or substring to trace through every stage. */
+  expect?: string;
+  sessionKey?: string;
+  namespace?: string;
+  authenticatedPrincipal?: string;
+  sourceConnector?: string;
+  abortSignal?: AbortSignal;
+}
+
+export interface RecallWhyResponse {
+  /** False when the namespace ACL denied the diagnosis. */
+  reportFound: boolean;
+  report?: RecallWhyReport;
+  /** One-line verdict, for agent callers that do not parse the full report. */
+  summary?: string;
+}
+
+export interface RecallWhyServiceDeps {
+  readonly orchestrator: Orchestrator;
+  /** The surface's shared namespace resolver. */
+  resolveNamespace(namespace?: string): string;
+}
+
+/**
+ * Run the recall-miss diagnosis for one request.
+ *
+ * Throws {@link RecallWhyInputError} for caller-input faults so surfaces can
+ * map them to a 400; backend faults are reported inside the report as
+ * `backend_unavailable` rather than thrown, because an outage is a diagnosis
+ * result, not a diagnosis failure.
+ */
+export async function runRecallWhy(deps: RecallWhyServiceDeps, request: RecallWhyRequest): Promise<RecallWhyResponse> {
+  const query = typeof request.query === "string" ? request.query : "";
+  if (query.trim().length === 0) {
+    throw new RecallWhyInputError("recallWhy: query is required and must be non-empty");
+  }
+  const orchestrator = deps.orchestrator;
+  const config = orchestrator.config;
+  const namespacesEnabled = resolveNamespaceCapabilities(config).namespaces;
+  const requestedNamespace = request.namespace?.trim() ? deps.resolveNamespace(request.namespace) : undefined;
+  const authenticatedPrincipal = request.authenticatedPrincipal?.trim();
+  const principal = authenticatedPrincipal || resolvePrincipal(request.sessionKey, config);
+
+  if (requestedNamespace !== undefined) {
+    if (!canReadNamespace(principal, requestedNamespace, config)) {
+      return { reportFound: false };
+    }
+  } else if (namespacesEnabled && !authenticatedPrincipal && !request.sessionKey?.trim()) {
+    // Namespaces on but no identity supplied: refuse rather than diagnose
+    // against the global namespace (least-privileged default).
+    return { reportFound: false };
+  }
+
+  const readableNamespaces =
+    requestedNamespace !== undefined ? [requestedNamespace] : [...recallNamespacesForPrincipal(principal, config)];
+  const recallSessionKey = request.sessionKey?.trim() || undefined;
+
+  const whyDeps: RecallWhyDeps = {
+    plannerMode: (prompt) => planRecallMode(prompt),
+    scopedNamespaces: readableNamespaces,
+    namespacesEnabled,
+    isExcludedPath: (memoryPath) => isGenericRecallExcludedPath(memoryPath, config),
+    runRecall: async (recallQuery, options) => {
+      // A configured-but-unreachable search backend is an OUTAGE, and must
+      // never render as "0 candidates" (Review Prevention Checklist #22).
+      // This is the same pair of expressions the pipeline emits as
+      // `qmdEnabled` / `qmdAvailable` on its recall_summary trace.
+      if (resolveQmdCapabilities(config).qmd && !orchestrator.qmd.isAvailable()) {
+        return {
+          ok: false,
+          reason: "backend_unavailable",
+          detail: "the search backend is enabled but reported itself unavailable",
+        };
+      }
+      // A backend that answers the availability probe can still fail
+      // mid-recall (daemon timeout, deadline exceeded, subprocess error).
+      // The pipeline already collects those; `degradationSink` hands us the
+      // same array it fills, so the outage is observed rather than inferred.
+      const degradations: SearchDegradation[] = [];
+      try {
+        const captured = await orchestrator.recallWithXrayCapture(recallQuery, options.sessionKey, {
+          ...(options.namespace !== undefined ? { namespace: options.namespace } : {}),
+          ...(authenticatedPrincipal ? { principalOverride: authenticatedPrincipal } : {}),
+          ...(request.sourceConnector ? { sourceConnector: request.sourceConnector } : {}),
+          ...(options.abortSignal !== undefined ? { abortSignal: options.abortSignal } : {}),
+          degradationSink: degradations,
+        });
+        const fatal = degradations.filter((d) => FATAL_DEGRADATION_CODES[d.code] === true);
+        if (fatal.length > 0) {
+          return { ok: false, reason: "backend_unavailable", detail: describeDegradations(fatal) };
+        }
+        return { ok: true, snapshot: captured.snapshot };
+      } catch (err) {
+        // Cancellation is the caller's decision, not a backend outage.
+        if (err instanceof Error && err.name === "AbortError") throw err;
+        const observed = degradations.length > 0 ? `${describeDegradations(degradations)}; ` : "";
+        return {
+          ok: false,
+          reason: "backend_unavailable",
+          detail: `${observed}${err instanceof Error ? err.message : "recall failed"}`,
+        };
+      }
+    },
+    findExpected: (expect) => findExpectedMemory(orchestrator, readableNamespaces, expect),
+  };
+
+  const report = await explainRecallMiss(query, {
+    deps: whyDeps,
+    ...(request.expect !== undefined ? { expect: request.expect } : {}),
+    ...(recallSessionKey !== undefined ? { sessionKey: recallSessionKey } : {}),
+    ...(requestedNamespace !== undefined ? { namespace: requestedNamespace } : {}),
+    ...(request.abortSignal !== undefined ? { abortSignal: request.abortSignal } : {}),
+  });
+
+  return { reportFound: true, report, summary: summarizeRecallWhy(report) };
+}
+
+/**
+ * Resolve `expect` to one stored memory, searching ONLY namespaces the
+ * caller may read. An exact id match wins over a substring match; among
+ * substring matches the lowest (memoryId, path) pair wins, so repeated runs
+ * report the same memory.
+ */
+async function findExpectedMemory(
+  orchestrator: Orchestrator,
+  namespaces: readonly string[],
+  expect: string
+): Promise<RecallWhyMemoryRef | null> {
+  const substringMatches: RecallWhyMemoryRef[] = [];
+  const seenNamespaces = new Set<string>();
+  for (const namespace of namespaces) {
+    if (seenNamespaces.has(namespace)) continue;
+    seenNamespaces.add(namespace);
+    let memories: MemoryFile[];
+    try {
+      const storage = await orchestrator.getStorageForNamespace(namespace);
+      memories = await storage.readAllMemories();
+    } catch {
+      // A namespace whose storage cannot be read contributes no candidates;
+      // the diagnosis still reports on the ones that could be read.
+      continue;
+    }
+    for (const memory of memories) {
+      const memoryId = typeof memory.frontmatter.id === "string" ? memory.frontmatter.id : "";
+      if (memoryId.length === 0) continue;
+      const ref: RecallWhyMemoryRef = {
+        memoryId,
+        path: memory.path,
+        status: (memory.frontmatter.status as MemoryStatus | undefined) ?? "active",
+        namespace,
+      };
+      if (memoryId === expect) return ref;
+      if (memoryId.includes(expect) || memory.path.includes(expect)) substringMatches.push(ref);
+    }
+  }
+  if (substringMatches.length === 0) return null;
+  // Total comparator: -1 / 0 / 1, and 0 for genuinely equal rows (#12).
+  substringMatches.sort((a, b) => {
+    if (a.memoryId !== b.memoryId) return a.memoryId < b.memoryId ? -1 : 1;
+    if (a.path !== b.path) return a.path < b.path ? -1 : 1;
+    return 0;
+  });
+  return substringMatches[0] ?? null;
+}