@remnic/core 9.69.63 → 9.69.65

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

package/dist/chunk-FM5HN7LL.js.map

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

package/dist/chunk-U2VDCFXW.js

@@ -1,19 +0,0 @@
-// src/search/port.ts
-function reportSearchDegradation(execution, degradation) {
-  try {
-    execution?.onDegradation?.(degradation);
-  } catch {
-  }
-}
-function resolveEnsureCollectionArgs(collectionOrExecution, execution) {
-  if (typeof collectionOrExecution === "string") {
-    return { collection: collectionOrExecution, execution };
-  }
-  return { collection: void 0, execution: collectionOrExecution ?? execution };
-}
-
-export {
-  reportSearchDegradation,
-  resolveEnsureCollectionArgs
-};
-//# sourceMappingURL=chunk-U2VDCFXW.js.map

package/dist/chunk-U2VDCFXW.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/search/port.ts"],"sourcesContent":["import type { QmdSearchResult } from \"../types.js\";\n\n/** Alias so consumers don't need to reference \"Qmd\" in a backend-agnostic context. */\nexport type SearchResult = QmdSearchResult;\n\nexport interface SearchQueryOptions {\n  intent?: string;\n  explain?: boolean;\n  candidateLimit?: number;\n  rerank?: boolean;\n  chunkStrategy?: \"auto\" | \"regex\";\n  structuredSearches?: Array<{ type: \"lex\" | \"vec\" | \"hyde\"; query: string }>;\n}\n\n/**\n * A search that returned empty (or partial) results because the backend was\n * unavailable, still loading, or timed out — cases that are otherwise\n * indistinguishable from a genuine \"no matches\" (issue #1536, CLAUDE.md\n * rule 34).\n */\nexport interface SearchDegradation {\n  backend: \"qmd\" | \"remote\" | \"meilisearch\" | \"orama\" | \"lancedb\";\n  code:\n    | \"backend_unavailable\"\n    | \"backend_error\"\n    | \"daemon_timeout\"\n    | \"daemon_loading\"\n    | \"subprocess_error\"\n    | \"deadline_exceeded\"\n    | \"remote_error\"\n    | \"vector_tier_unavailable\";\n  detail?: string;\n}\n\nexport interface SearchExecutionOptions {\n  signal?: AbortSignal;\n  /**\n   * Observer invoked when the backend degrades during this call (#1536).\n   * Callers that need to distinguish empty-because-degraded from\n   * empty-because-no-matches (recall x-ray, fallback decisions) pass a\n   * collector here. Observer failures are swallowed by the notifier —\n   * observability must never break search.\n   */\n  onDegradation?: (degradation: SearchDegradation) => void;\n}\n\nexport function reportSearchDegradation(\n  execution: SearchExecutionOptions | undefined,\n  degradation: SearchDegradation\n): void {\n  try {\n    execution?.onDegradation?.(degradation);\n  } catch {\n    // Observability must never break search.\n  }\n}\n\nexport function resolveEnsureCollectionArgs(\n  collectionOrExecution?: string | SearchExecutionOptions,\n  execution?: SearchExecutionOptions\n): { collection?: string; execution?: SearchExecutionOptions } {\n  if (typeof collectionOrExecution === \"string\") {\n    return { collection: collectionOrExecution, execution };\n  }\n  return { collection: undefined, execution: collectionOrExecution ?? execution };\n}\n\n/**\n * Optional status report for search backends that track embedding backlog.\n * Backends without embedding pipelines return null from status().\n */\nexport interface SearchBackendStatus {\n  pendingEmbeddings: number | null;\n  oldestPendingAgeMs: number | null;\n  totalFiles: number | null;\n  embeddedFiles: number | null;\n}\n\n/**\n * Abstract search backend interface.\n *\n * Implementations:\n * - QmdClient (default, local hybrid BM25+vector+reranking)\n * - OramaBackend (embedded, pure JS, hybrid FTS+vector)\n * - LanceDbBackend (embedded, native Arrow bindings, RRF reranking)\n * - MeilisearchBackend (server-based SDK, hybrid search)\n * - RemoteSearchBackend (HTTP REST adapter)\n * - NoopSearchBackend (graceful degradation)\n *\n * See docs/writing-a-search-backend.md for the implementation guide.\n */\nexport interface SearchBackend {\n  // ── Lifecycle ──\n  probe(execution?: SearchExecutionOptions): Promise<boolean>;\n  /**\n   * Optional non-mutating availability probe for health/readiness checks.\n   * Implementations must avoid auto-upgrades, collection creation, daemon\n   * startup, or any other runtime-modifying side effects.\n   */\n  checkAvailability?(execution?: SearchExecutionOptions): Promise<boolean>;\n  isAvailable(): boolean;\n  debugStatus(): string;\n  /** Optional embedding backlog status for health surfaces. */\n  status?(): Promise<SearchBackendStatus>;\n\n  // ── Search ──\n  search(\n    query: string,\n    collection?: string,\n    maxResults?: number,\n    options?: SearchQueryOptions,\n    execution?: SearchExecutionOptions\n  ): Promise<SearchResult[]>;\n  searchGlobal(query: string, maxResults?: number, execution?: SearchExecutionOptions): Promise<SearchResult[]>;\n  bm25Search(\n    query: string,\n    collection?: string,\n    maxResults?: number,\n    execution?: SearchExecutionOptions\n  ): Promise<SearchResult[]>;\n  vectorSearch(\n    query: string,\n    collection?: string,\n    maxResults?: number,\n    execution?: SearchExecutionOptions\n  ): Promise<SearchResult[]>;\n  hybridSearch(\n    query: string,\n    collection?: string,\n    maxResults?: number,\n    execution?: SearchExecutionOptions\n  ): Promise<SearchResult[]>;\n\n  // ── Maintenance ──\n  update(execution?: SearchExecutionOptions): Promise<void>;\n  /**\n   * Wall-clock ms of the most recent SUCCESSFUL index refresh, or null when the\n   * backend has never run one. Ordinary update() is fail-open: it returns\n   * silently (without throwing or advancing this timestamp) when the backend is\n   * unavailable or the call is suppressed by a min-interval / failure backoff.\n   * Callers that must know whether update() actually indexed — so they can\n   * invalidate dependent caches only on a real refresh — snapshot this before\n   * the call and treat the backend as refreshed iff the value advanced. Optional\n   * because not every backend tracks it; absent means \"assume refreshed\".\n   */\n  readonly lastUpdateRanAtMs?: number | null;\n  /**\n   * Optional strict refresh used by callers that must know whether the backend\n   * was actually refreshed before writing success markers. Ordinary update\n   * calls remain fail-open for migration/maintenance resilience.\n   */\n  updateStrict?(execution?: SearchExecutionOptions): Promise<void>;\n  updateCollection(collection: string, execution?: SearchExecutionOptions): Promise<void>;\n  updateCollectionFromDir?(collection: string, memoryDir: string, execution?: SearchExecutionOptions): Promise<void>;\n  /**\n   * True when update() refreshes every indexed collection, not just this\n   * backend's configured collection. Namespace routers use this to avoid\n   * repeating the same expensive global update once per namespace.\n   */\n  updatesAllCollections?(): boolean;\n  /**\n   * Optional strict refresh used by callers that must know whether a collection\n   * was actually refreshed before writing success markers. Ordinary update\n   * calls remain fail-open for migration/maintenance resilience.\n   */\n  updateCollectionStrict?(collection: string, execution?: SearchExecutionOptions): Promise<void>;\n  embed(): Promise<void>;\n  /**\n   * Optional strict embed used by callers that must know vectors were actually\n   * refreshed before writing success markers.\n   */\n  embedStrict?(): Promise<void>;\n  embedCollection(collection: string): Promise<void>;\n  /**\n   * Optional strict collection embed used by callers that must know vectors were\n   * actually refreshed before writing success markers.\n   */\n  embedCollectionStrict?(collection: string): Promise<void>;\n\n  // ── Collection management ──\n  /**\n   * True only when the backend can bind, isolate, search, and delete collections\n   * outside Remnic's primary memory roots.\n   */\n  supportsAdditionalCollections?(): boolean;\n  /**\n   * Prevent a collection from participating in unscoped/global searches.\n   * Dedicated corpora must call this immediately after collection creation.\n   */\n  excludeCollectionFromGlobalSearch?(collection: string, execution?: SearchExecutionOptions): Promise<void>;\n  /** Remove a non-primary collection and its backend-owned index state. */\n  deleteCollection?(collection: string, execution?: SearchExecutionOptions): Promise<boolean>;\n  /** Canonical source root currently bound to a named collection. */\n  collectionRoot?(collection: string, execution?: SearchExecutionOptions): Promise<string | null>;\n  /** Collection-scoped status for observability surfaces. */\n  collectionStatus?(collection: string): Promise<Pick<SearchBackendStatus, \"totalFiles\">>;\n  /**\n   * Optional non-mutating collection probe. Backends that can distinguish a\n   * missing collection from a transient probe failure should implement this so\n   * callers can avoid auto-creating collections in unsafe layouts.\n   */\n  checkCollection?(\n    collectionOrExecution?: string | SearchExecutionOptions,\n    execution?: SearchExecutionOptions\n  ): Promise<\"present\" | \"missing\" | \"unknown\" | \"skipped\">;\n  ensureCollection(\n    memoryDir: string,\n    execution?: SearchExecutionOptions\n  ): Promise<\"present\" | \"missing\" | \"unknown\" | \"skipped\">;\n  ensureCollection(\n    memoryDir: string,\n    collection?: string,\n    execution?: SearchExecutionOptions\n  ): Promise<\"present\" | \"missing\" | \"unknown\" | \"skipped\">;\n}\n"],"mappings":";AA8CO,SAAS,wBACd,WACA,aACM;AACN,MAAI;AACF,eAAW,gBAAgB,WAAW;AAAA,EACxC,QAAQ;AAAA,EAER;AACF;AAEO,SAAS,4BACd,uBACA,WAC6D;AAC7D,MAAI,OAAO,0BAA0B,UAAU;AAC7C,WAAO,EAAE,YAAY,uBAAuB,UAAU;AAAA,EACxD;AACA,SAAO,EAAE,YAAY,QAAW,WAAW,yBAAyB,UAAU;AAChF;","names":[]}