@remnic/core 9.69.61 → 9.69.64

package/src/model-registry.ts

@@ -5,7 +5,7 @@
 
 import { log } from "./logger.js";
 import fs from "node:fs";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 
 export interface ModelCapabilities {
   modelId: string;
@@ -116,11 +116,7 @@ export class ModelRegistry {
   private readonly CACHE_TTL_DAYS = 7;
 
   constructor(memoryDir: string) {
-    const registryDir = join(memoryDir, ".registry");
-    if (!fs.existsSync(registryDir)) {
-      fs.mkdirSync(registryDir, { recursive: true });
-    }
-    this.registryPath = join(registryDir, "model-capabilities.json");
+    this.registryPath = join(memoryDir, ".registry", "model-capabilities.json");
     this.data = this.loadRegistry();
   }
 
@@ -140,6 +136,11 @@ export class ModelRegistry {
 
   private saveRegistry(): void {
     try {
+      // Created on first save, never at construction: building a registry
+      // happens on every plugin registration, including read-only discovery
+      // passes, and must not touch the operator's memory dir.
+      const registryDir = dirname(this.registryPath);
+      if (!fs.existsSync(registryDir)) fs.mkdirSync(registryDir, { recursive: true });
       fs.writeFileSync(this.registryPath, JSON.stringify(this.data, null, 2));
     } catch (err) {
       log.warn(`ModelRegistry: failed to save registry: ${err}`);

package/src/orchestration/recall-internal.ts

@@ -130,11 +130,9 @@ export class RecallInternalCoordinator {
     lifecycleCaps: MemoryLifecycleCapabilitySet = resolveMemoryLifecycleCapabilities(this.deps.config),
   ): Promise<string> {
     const recallStart = Date.now();
-    // Backend degradations observed by this recall's QMD searches (#1536):
-    // collected via the execution-options observer and attached to the
-    // LastRecallSnapshot after it is recorded, so surfaces can distinguish
-    // "no matches" from "backend could not answer" (CLAUDE.md rule 34).
-    const backendDegradations: SearchDegradation[] = options.degradationSink ?? [];
+    // Per-recall QMD degradations (#1536/#3082). Local array so overlapping
+    // recalls that share a sink cannot mark each other failed.
+    const backendDegradations: SearchDegradation[] = [];
     // Issue #680 — historical recall.  Parse `options.asOf` once at the
     // top of the recall so each boost-pass uses identical filter logic.
     // Invalid values are rejected at input boundaries (CLI / HTTP / MCP)
@@ -4964,7 +4962,12 @@ export class RecallInternalCoordinator {
         compactContext: compactRecallContextFromBuckets(sectionBuckets),
         footer: curiosityFooter,
         maxChars: recallBudgetChars,
+        backendDegradations,
+        qmdExpected: this.deps.config.searchBackend !== "noop" && (this.deps.config.searchBackend !== "qmd" || resolveQmdCapabilities(this.deps.config).qmd),
       });
+    if (options.degradationSink) {
+      for (const d of backendDegradations) options.degradationSink.push(d);
+    }
     notifyContextComposition(options.onContextComposition, composition, (err) => {
       log.warn("recall: context composition observer failed open", err);
     });

package/src/profiling.test.ts

@@ -1,5 +1,5 @@
 import assert from "node:assert/strict";
-import { mkdtempSync, readdirSync, rmSync } from "node:fs";
+import { existsSync, mkdtempSync, readdirSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import test, { describe } from "node:test";
@@ -283,4 +283,23 @@ describe("ProfilingCollector", () => {
       cleanup(dir);
     }
   });
+
+  test("construction never creates the storage dir; the first persist does", () => {
+    const dir = tempDir();
+    const storageDir = join(dir, "profiling");
+    try {
+      const collector = new ProfilingCollector({ enabled: true, storageDir, maxTraces: 10 });
+      // Constructing a collector happens on every plugin registration, including
+      // read-only discovery passes, so it must not touch the memory dir.
+      assert.equal(existsSync(storageDir), false, "no dir before a trace is written");
+      collector.startTrace("recall", "test-session");
+      collector.startSpan("qmd-search");
+      collector.endSpan("qmd-search");
+      collector.endTrace();
+      assert.equal(existsSync(storageDir), true, "the first persisted trace creates it");
+      assert.equal(readdirSync(storageDir).length, 1);
+    } finally {
+      cleanup(dir);
+    }
+  });
 });

package/src/profiling.ts

@@ -118,13 +118,6 @@ export class ProfilingCollector {
     this.enabled = config.enabled;
     this.storageDir = config.storageDir;
     this.maxTraces = Math.max(0, config.maxTraces);
-
-    if (this.enabled) {
-      if (!existsSync(this.storageDir)) {
-        mkdirSync(this.storageDir, { recursive: true });
-        log.debug(`profiling: created storage dir ${this.storageDir}`);
-      }
-    }
   }
 
   get isEnabled(): boolean {
@@ -347,6 +340,13 @@ export class ProfilingCollector {
     const filename = `${trace.kind}-${trace.traceId}.jsonl`;
     const filepath = join(this.storageDir, filename);
     try {
+      // Created on first persist, never at construction: constructing a
+      // collector (plugin registration, a discovery pass, CLI metadata) must
+      // not touch the operator's memory dir when no trace is ever written.
+      if (!existsSync(this.storageDir)) {
+        mkdirSync(this.storageDir, { recursive: true });
+        log.debug(`profiling: created storage dir ${this.storageDir}`);
+      }
       writeFileSync(filepath, JSON.stringify(trace) + "\n", "utf-8");
       log.debug(`profiling: persisted ${filename}`);
     } catch (err) {

package/src/recall-composition-decision.test.ts

@@ -30,6 +30,81 @@ test("#2972 empty recall stays marker-free", () => {
   assert.equal("degradation" in composition, false);
 });
 
+test("#3082 empty context plus daemon_timeout is missing, not a genuine empty", () => {
+  const { composition, context } = decideRecallContextComposition({
+    context: "",
+    maxChars: 512,
+    backendDegradations: [{ backend: "qmd", code: "daemon_timeout", detail: "no response in 8000ms" }],
+  });
+
+  assert.equal(composition.degradation?.state, "missing");
+  assert.equal(composition.degradation?.reason, "backend-unavailable");
+  assert.match(composition.degradation?.detail ?? "", /qmd:daemon_timeout/);
+  assert.match(context, /memory context unavailable/i);
+});
+
+test("#3082 vector_tier_unavailable on empty context is not an outage", () => {
+  const { composition, context } = decideRecallContextComposition({
+    context: "",
+    maxChars: 512,
+    backendDegradations: [{ backend: "qmd", code: "vector_tier_unavailable" }],
+  });
+
+  assert.equal(context, "");
+  assert.equal("degradation" in composition, false);
+});
+
+test("#3082 daemon_timeout with recalled context keeps results and marks degraded", () => {
+  const { composition, truncated } = decideRecallContextComposition({
+    context: "A remembered deployment decision.",
+    maxChars: 512,
+    backendDegradations: [{ backend: "qmd", code: "daemon_timeout", detail: "cold-tier timed out" }],
+  });
+
+  assert.equal(composition.context, "A remembered deployment decision.");
+  assert.equal(composition.degradation?.state, "degraded");
+  assert.equal(composition.degradation?.reason, "backend-unavailable");
+  assert.equal(truncated, false);
+});
+
+test("#3082 QMD-disabled backend_unavailable is not an outage", () => {
+  const { composition, context } = decideRecallContextComposition({
+    context: "",
+    maxChars: 512,
+    qmdExpected: false,
+    backendDegradations: [{ backend: "qmd", code: "backend_unavailable", detail: "qmd disabled" }],
+  });
+
+  assert.equal(context, "");
+  assert.equal("degradation" in composition, false);
+});
+
+test("#3082 non-QMD backend_unavailable is still an outage when QMD is off", () => {
+  const { composition, context } = decideRecallContextComposition({
+    context: "",
+    maxChars: 512,
+    qmdExpected: false,
+    backendDegradations: [{ backend: "remote", code: "backend_unavailable" }],
+  });
+
+  assert.equal(composition.degradation?.state, "missing");
+  assert.equal(composition.degradation?.reason, "backend-unavailable");
+  assert.match(context, /memory context unavailable/i);
+});
+test("#3082 timeout plus budget clip still reports backend-unavailable", () => {
+  const longContext = "A remembered deployment decision. ".repeat(40).trim();
+  const { composition, truncated } = decideRecallContextComposition({
+    context: longContext,
+    maxChars: 80,
+    backendDegradations: [{ backend: "qmd", code: "daemon_timeout", detail: "no response in 8000ms" }],
+  });
+
+  assert.equal(composition.degradation?.reason, "backend-unavailable");
+  assert.match(composition.degradation?.detail ?? "", /qmd:daemon_timeout/);
+  assert.ok(composition.degradation?.budget, "budget accounting stays on the overlay");
+  assert.equal(truncated, true);
+});
+
 test("#2972 compact form from section buckets is preferred over clipping", () => {
   const longOne = "full-form entry one with a long body ".repeat(6).trim();
   const longTwo = "full-form entry two with a long body ".repeat(6).trim();

package/src/recall-composition-decision.ts

@@ -15,6 +15,11 @@ import {
   RECALL_CONTEXT_SEPARATOR,
   type RecallContextComposition,
 } from "./recall-context-composition.js";
+import {
+  describeSearchDegradations,
+  fatalSearchDegradations,
+  type SearchDegradation,
+} from "./search/port.js";
 
 export type RecallCompositionChunk = string | { readonly content: string };
 
@@ -23,6 +28,14 @@ export interface DecideRecallContextCompositionInput {
   compactContext?: string;
   footer?: string;
   maxChars: number;
+  /** Mid-recall backend degradations (#3082). Absent on the healthy path. */
+  backendDegradations?: readonly SearchDegradation[];
+  /**
+   * When false, `{ backend: "qmd", code: "backend_unavailable" }` is the
+   * QMD-disabled/noop skip marker, not an outage. Other backends still count.
+   * Default true so unit tests that pass degradations stay honest.
+   */
+  qmdExpected?: boolean;
 }
 
 export interface DecidedRecallContextComposition {
@@ -65,18 +78,54 @@ export function compactRecallContextFromBuckets(
 export function decideRecallContextComposition(
   input: DecideRecallContextCompositionInput,
 ): DecidedRecallContextComposition {
-  const composition = boundRecallContextComposition({
+  const observed = input.backendDegradations ?? [];
+  const qmdExpected = input.qmdExpected !== false;
+  const fatal = fatalSearchDegradations(observed).filter(
+    (d) => qmdExpected || d.backend !== "qmd" || d.code !== "backend_unavailable",
+  );
+  if (fatal.length > 0 && input.context.trim().length === 0) {
+    const missing = composeMissingMemoryContext({
+      detail: describeSearchDegradations(fatal),
+    });
+    const composition = input.footer
+      ? { ...missing, footer: input.footer }
+      : missing;
+    return {
+      composition,
+      context: composeRecallContext(composition),
+      truncated: false,
+    };
+  }
+  const bounded = boundRecallContextComposition({
     context: input.context,
     footer: input.footer,
     maxChars: input.maxChars,
     compactContext: input.compactContext,
   });
+  if (fatal.length === 0) {
+    return {
+      composition: bounded,
+      context: composeRecallContext(bounded),
+      truncated:
+        bounded.degradation?.reason === "budget-clipped" ||
+        bounded.degradation?.reason === "budget-compacted",
+    };
+  }
+  const composition = {
+    ...bounded,
+    degradation: {
+      state: "degraded" as const,
+      reason: "backend-unavailable" as const,
+      detail: describeSearchDegradations(fatal),
+      ...(bounded.degradation?.budget ? { budget: bounded.degradation.budget } : {}),
+    },
+  };
   return {
     composition,
     context: composeRecallContext(composition),
     truncated:
-      composition.degradation?.reason === "budget-clipped" ||
-      composition.degradation?.reason === "budget-compacted",
+      bounded.degradation?.reason === "budget-clipped" ||
+      bounded.degradation?.reason === "budget-compacted",
   };
 }
 

package/src/recall-retrieval-failure.test.ts

@@ -0,0 +1,245 @@
+/**
+ * #3082: recall must distinguish a QMD daemon timeout from a genuine
+ * empty retrieval. Internally the pipeline already collected the
+ * degradation; this file asserts it is no longer flattened away by
+ * the time it reaches orchestrator.recall / EngramAccessService.recall
+ * / the MCP tool payload.
+ *
+ * Fixture data is synthetic and the store is an empty temp directory.
+ */
+
+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 { EngramMcpServer } from "./access-mcp.js";
+import { EngramAccessService } from "./access-service.js";
+import type { EngramAccessRecallRequest, EngramAccessRecallResponse } from "./access-service.js";
+import { parseConfig } from "./config.js";
+import { Orchestrator } from "./orchestrator.js";
+import {
+  MEMORY_CONTEXT_UNAVAILABLE_NOTE,
+  type RecallContextComposition,
+} from "./recall-context-composition.js";
+import type { SearchBackend, SearchDegradation, SearchExecutionOptions } from "./search/port.js";
+import { DEFAULT_RECALL_DISCLOSURE } from "./types.js";
+
+const TIMEOUT_DEGRADATION: SearchDegradation = {
+  backend: "qmd",
+  code: "daemon_timeout",
+  detail: "no response within the deadline",
+};
+
+const QUERY = "what writing rules apply here?";
+
+function searchBackend(observed: { calls: number }, degrade: boolean): SearchBackend {
+  const search = (execution?: SearchExecutionOptions) => {
+    observed.calls += 1;
+    if (degrade) execution?.onDegradation?.(TIMEOUT_DEGRADATION);
+    return [];
+  };
+  const backend: Partial<SearchBackend> = {
+    async probe() {
+      return true;
+    },
+    isAvailable() {
+      return true;
+    },
+    debugStatus() {
+      return degrade ? "backend=timeout-stub" : "backend=empty-stub";
+    },
+    async search(_query, _collection, _maxResults, _options, execution) {
+      return search(execution);
+    },
+    async searchGlobal(_query, _maxResults, execution) {
+      return search(execution);
+    },
+    async bm25Search(_query, _collection, _maxResults, execution) {
+      return search(execution);
+    },
+    async vectorSearch(_query, _collection, _maxResults, execution) {
+      return search(execution);
+    },
+    async hybridSearch(_query, _collection, _maxResults, execution) {
+      return search(execution);
+    },
+    async update() {},
+    async updateCollection() {},
+    async embed() {},
+    async embedCollection() {},
+    async ensureCollection() {
+      return "skipped";
+    },
+  };
+  return backend as SearchBackend;
+}
+
+async function withOrchestrator(
+  prefix: string,
+  degrade: boolean,
+  run: (orchestrator: Orchestrator, observed: { calls: number }) => Promise<void>,
+): Promise<void> {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), prefix));
+  const orchestrator = new Orchestrator(
+    parseConfig({
+      memoryDir,
+      workspaceDir: memoryDir,
+      qmdEnabled: true,
+      embeddingFallbackEnabled: false,
+    }),
+  );
+  const observed = { calls: 0 };
+  // Unchecked cast with reason: `qmd` is assigned post-construction because the
+  // backend is built by the search factory, which would reach for a real daemon.
+  const withBackend = orchestrator as unknown as { qmd: SearchBackend };
+  withBackend.qmd = searchBackend(observed, degrade);
+  try {
+    await orchestrator.initialize();
+    await orchestrator.deferredReady;
+    await run(orchestrator, observed);
+  } finally {
+    await orchestrator.destroy();
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+}
+
+test("QMD daemon_timeout mid-recall is distinguishable from genuine empty at the orchestrator", async () => {
+  await withOrchestrator("remnic-recall-timeout-", true, async (orchestrator, observed) => {
+    let composition: RecallContextComposition | undefined;
+    const context = await orchestrator.recall(QUERY, "timeout-session", {
+      onContextComposition: (value) => {
+        composition = value;
+      },
+    });
+
+    assert.ok(observed.calls > 0, "recall must consult the backend");
+    assert.equal(composition?.degradation?.state, "missing");
+    assert.equal(composition?.degradation?.reason, "backend-unavailable");
+    assert.match(composition?.degradation?.detail ?? "", /qmd:daemon_timeout/);
+    assert.equal(context, MEMORY_CONTEXT_UNAVAILABLE_NOTE);
+  });
+});
+
+test("genuine empty retrieval stays marker-free at the orchestrator", async () => {
+  await withOrchestrator("remnic-recall-empty-", false, async (orchestrator, observed) => {
+    let composition: RecallContextComposition | undefined;
+    const context = await orchestrator.recall(QUERY, "empty-session", {
+      onContextComposition: (value) => {
+        composition = value;
+      },
+    });
+
+    assert.ok(observed.calls > 0, "recall must consult the backend");
+    assert.equal(composition?.degradation, undefined);
+    assert.equal(context.includes("Memory context unavailable"), false);
+  });
+});
+
+test("access recall surfaces retrievalFailure on daemon timeout and omits it on genuine empty", async () => {
+  await withOrchestrator("remnic-recall-access-timeout-", true, async (timedOut, observed) => {
+    const failed = await new EngramAccessService(timedOut).recall({
+      query: QUERY,
+      sessionKey: "access-timeout",
+    });
+    assert.ok(observed.calls > 0, "timeout recall must consult the backend");
+    assert.equal(failed.retrievalFailure?.reason, "backend_unavailable");
+    assert.match(failed.retrievalFailure?.detail ?? "", /qmd:daemon_timeout/);
+    assert.equal(failed.contextComposition?.degradation?.state, "missing");
+    assert.match(failed.context, /memory context unavailable/i);
+  });
+
+  await withOrchestrator("remnic-recall-access-empty-", false, async (empty, observed) => {
+    const okEmpty = await new EngramAccessService(empty).recall({
+      query: QUERY,
+      sessionKey: "access-empty",
+    });
+    assert.ok(observed.calls > 0, "empty recall must consult the backend");
+    assert.equal(okEmpty.retrievalFailure, undefined);
+    assert.equal(okEmpty.contextComposition?.degradation, undefined);
+    assert.equal(okEmpty.context.includes("Memory context unavailable"), false);
+  });
+});
+
+test("a reused degradationSink cannot mark a later healthy empty recall as failed", async () => {
+  await withOrchestrator("remnic-recall-reused-sink-", true, async (orchestrator, observed) => {
+    const sink: SearchDegradation[] = [];
+    await orchestrator.recall(QUERY, "first-timeout", { degradationSink: sink });
+    assert.ok(sink.length > 0, "the first recall must record the timeout");
+
+    const withBackend = orchestrator as unknown as { qmd: SearchBackend };
+    withBackend.qmd = searchBackend(observed, false);
+    let composition: RecallContextComposition | undefined;
+    await orchestrator.recall(QUERY, "second-empty", {
+      degradationSink: sink,
+      onContextComposition: (value) => {
+        composition = value;
+      },
+    });
+    assert.equal(composition?.degradation, undefined);
+  });
+});
+
+test("MCP recall payload keeps retrievalFailure so a tool caller can branch on it", async () => {
+  const timeoutResponse: EngramAccessRecallResponse = {
+    query: QUERY,
+    namespace: "default",
+    context: MEMORY_CONTEXT_UNAVAILABLE_NOTE,
+    count: 0,
+    memoryIds: [],
+    results: [],
+    fallbackUsed: false,
+    sourcesUsed: [],
+    disclosure: DEFAULT_RECALL_DISCLOSURE,
+    retrievalFailure: {
+      reason: "backend_unavailable",
+      detail: "qmd:daemon_timeout (no response within the deadline)",
+    },
+  };
+  const emptyResponse: EngramAccessRecallResponse = {
+    query: QUERY,
+    namespace: "default",
+    context: "",
+    count: 0,
+    memoryIds: [],
+    results: [],
+    fallbackUsed: false,
+    sourcesUsed: [],
+    disclosure: DEFAULT_RECALL_DISCLOSURE,
+  };
+
+  async function callRecall(response: EngramAccessRecallResponse): Promise<EngramAccessRecallResponse> {
+    const service = {
+      briefingEnabled: false,
+      recall: (_req: EngramAccessRecallRequest) => Promise.resolve(response),
+    } as unknown as EngramAccessService;
+    const server = new EngramMcpServer(service);
+    // Unchecked cast with reason: handleRequest is a JSON-RPC envelope; this
+    // test owns both the spy recall result and the tool name, so the payload
+    // shape is the MCP recall structuredContent, not untrusted input.
+    const rpc = (await server.handleRequest({
+      jsonrpc: "2.0",
+      id: 1,
+      method: "tools/call",
+      params: { name: "engram.recall", arguments: { query: QUERY } },
+    })) as {
+      result?: { structuredContent?: EngramAccessRecallResponse; content?: Array<{ text?: string }> };
+    };
+    const structured = rpc.result?.structuredContent;
+    assert.ok(structured, "MCP recall must return structuredContent");
+    const text = rpc.result?.content?.[0]?.text ?? "{}";
+    const parsed: unknown = JSON.parse(text);
+    assert.ok(parsed && typeof parsed === "object");
+    const parsedFailure = "retrievalFailure" in parsed ? parsed.retrievalFailure : undefined;
+    assert.deepEqual(parsedFailure, structured.retrievalFailure);
+    return structured;
+  }
+
+  const timedOut = await callRecall(timeoutResponse);
+  const genuineEmpty = await callRecall(emptyResponse);
+  assert.equal(timedOut.count, genuineEmpty.count);
+  assert.deepEqual(timedOut.results, genuineEmpty.results);
+  assert.equal(timedOut.retrievalFailure?.reason, "backend_unavailable");
+  assert.equal(genuineEmpty.retrievalFailure, undefined);
+});

package/src/recall-why-service.ts

@@ -27,29 +27,13 @@ import {
   type RecallWhyReport,
 } from "./recall-why.js";
 import { summarizeRecallWhy } from "./recall-why-renderer.js";
-import type { SearchDegradation } from "./search/port.js";
+import {
+  describeSearchDegradations,
+  fatalSearchDegradations,
+  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. */
@@ -139,15 +123,15 @@ export async function runRecallWhy(deps: RecallWhyServiceDeps, request: RecallWh
           ...(options.abortSignal !== undefined ? { abortSignal: options.abortSignal } : {}),
           degradationSink: degradations,
         });
-        const fatal = degradations.filter((d) => FATAL_DEGRADATION_CODES[d.code] === true);
+        const fatal = fatalSearchDegradations(degradations);
         if (fatal.length > 0) {
-          return { ok: false, reason: "backend_unavailable", detail: describeDegradations(fatal) };
+          return { ok: false, reason: "backend_unavailable", detail: describeSearchDegradations(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)}; ` : "";
+        const observed = degradations.length > 0 ? `${describeSearchDegradations(degradations)}; ` : "";
         return {
           ok: false,
           reason: "backend_unavailable",

package/src/search/port.ts

@@ -55,6 +55,38 @@ export function reportSearchDegradation(
   }
 }
 
+/**
+ * Codes that mean the search backend could NOT answer, so an empty
+ * result set carries no information (issue #3082 / recall_why #3033).
+ * `vector_tier_unavailable` is excluded on purpose: the lexical tier
+ * still answered, so the result set is degraded but real.
+ */
+export const FATAL_SEARCH_DEGRADATION_CODES: Readonly<
+  Partial<Record<SearchDegradation["code"], true>>
+> = Object.freeze({
+  backend_unavailable: true,
+  backend_error: true,
+  daemon_timeout: true,
+  daemon_loading: true,
+  subprocess_error: true,
+  deadline_exceeded: true,
+  remote_error: true,
+});
+
+export function fatalSearchDegradations(
+  degradations: readonly SearchDegradation[],
+): SearchDegradation[] {
+  return degradations.filter((d) => FATAL_SEARCH_DEGRADATION_CODES[d.code] === true);
+}
+
+export function describeSearchDegradations(
+  degradations: readonly SearchDegradation[],
+): string {
+  return degradations
+    .map((d) => `${d.backend}:${d.code}${d.detail !== undefined ? ` (${d.detail})` : ""}`)
+    .join("; ");
+}
+
 export function resolveEnsureCollectionArgs(
   collectionOrExecution?: string | SearchExecutionOptions,
   execution?: SearchExecutionOptions