@remnic/core 9.69.61 → 9.69.64

package/src/security/injection-screen.ts

@@ -177,14 +177,285 @@ const RESPONSE_CONTROL_PATTERNS: readonly RegExp[] = [
 ];
 
 /**
- * A directive over what the agent's future answer must contain or say.
- * Ordinary facts that merely pair "policy"/"note"/"response" with a common
- * verb ("the return policy requires a receipt") are not directives.
+ * Corroborating signals that separate an injected response control from
+ * ordinary prose about response content (issue #3078). "The API response
+ * must include a Content-Type header" is directive-SHAPED but names an
+ * ordinary field; an injection additionally carries one of:
+ *
+ *  - an opaque payload to emit: a marker token, a long hex/UUID run, a URL;
+ *  - verbatim control: literal / exact / word-for-word / "with no explanation";
+ *  - cross-turn persistence: remember / persist / store this / any later
+ *    retrieval / across conversations / from now on;
+ *  - an agent-directed subject: your answer, the assistant's reply.
+ *
+ * Requiring one of these keeps every frozen attack payload flagged while
+ * ordinary technical and policy sentences fall to zero.
+ */
+/**
+ * Corroborating cues. Measured trade (PR #3079 r4): these are evaluated over
+ * the whole memory, not the directive's sentence. Thirty frozen attack
+ * payloads state the directive and name the payload in DIFFERENT sentences,
+ * so sentence-local cues lose real detections; the price is that a marker in
+ * an unrelated sentence can corroborate an ordinary directive. The
+ * emission-slot check below stays sentence-local, where locality is free.
+ */
+const RESPONSE_CONTROL_CORROBORATORS: readonly RegExp[] = [
+  /\bCANARY\b/i,
+  /https?:\/\//i,
+  /\b[0-9a-f]{8,}\b/i,
+  /\b[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}\b/,
+  // Naming the emission as a phrase/marker/token is a payload cue: ordinary
+  // prose names a field ("the request id"), not "the phrase".
+  /\b(?:the|this|that|following)[ \t]{1,8}(?:phrase|marker|token|string|sequence|literal|codeword|passphrase)\b/i,
+  // Verbatim control over the wording, not the content.
+  /\b(?:literal(?:ly)?|verbatim|word[- ]for[- ]word|exactly[ \t]{1,8}(?:this|that|as)|character[- ]for[- ]character)\b/i,
+  /\bno[ \t]{1,8}(?:explanation|commentary|preamble|deviation|other[ \t]{1,8}text)\b/i,
+  /\b(?:only|nothing[ \t]{1,8}else|and[ \t]{1,8}nothing)\b[^\n]{0,30}\b(?:answers?|responses?|repl(?:y|ies)|output|say|said)\b/i,
+  // Persistence across turns: an ordinary fact does not legislate later turns.
+  /\b(?:remember|persist|store[ \t]{1,8}this|retain[ \t]{1,8}this)\b/i,
+  /\bany[ \t]{1,8}(?:later|future|subsequent)\b/i,
+  /\b(?:future|later|subsequent|following|upcoming)[ \t]{1,8}(?:answers?|responses?|repl(?:y|ies)|output|turns?|messages?|conversations?|sessions?)\b/i,
+  /\b(?:across|between)[ \t]{1,8}(?:conversations|sessions|chats)\b/i,
+  /\b(?:from[ \t]{1,8}now[ \t]{1,8}on|going[ \t]{1,8}forward|in[ \t]{1,8}(?:all|every)[ \t]{1,8}(?:future|later)[ \t]{1,8}(?:turns?|answers?|responses?))\b/i,
+  /\b(?:whenever|every[ \t]{1,8}time|each[ \t]{1,8}time|any[ \t]{1,8}time)\b[^\n]{0,60}\b(?:asked|discussed|mentioned|queried|retrieved|recalled)\b/i,
+  // The subject is the agent, not a system under discussion.
+  /\byour[ \t]{1,8}(?:answers?|responses?|repl(?:y|ies)|output|behaviou?r|memory)\b/i,
+  /\b(?:assistant|agent|model)(?:'s)?[ \t]{1,8}(?:answers?|responses?|repl(?:y|ies)|output|behaviou?r)\b/i,
+  // A hidden activation phrase is itself the second signal.
+  /\b(?:activation|trigger)[ \t]{1,8}(?:phrase|key|word|code)\b/i,
+  /\b(?:approved|required|correct|canonical)[ \t]{1,8}(?:response|answer|reply)\b/i,
+];
+
+
+/**
+ * Acronyms that appear as ordinary content in technical memories, so an
+ * all-caps token alone is not evidence of an injected marker.
+ */
+const ORDINARY_CAPS_TOKENS: ReadonlySet<string> = new Set([
+  "API", "HTTP", "HTTPS", "JSON", "XML", "HTML", "CSS", "CSV", "TSV", "YAML", "TOML",
+  "SQL", "URL", "URI", "UUID", "ID", "IDS", "UTC", "ISO", "PDF", "PNG", "JPEG", "SVG",
+  "TLS", "SSL", "SSH", "DNS", "TCP", "UDP", "IP", "CDN", "CORS", "CSRF", "JWT", "OAUTH",
+  "REST", "GRPC", "RPC", "SDK", "CLI", "GUI", "OK", "YES", "NO", "TODO", "FAQ", "PR",
+  "CI", "CD", "QA", "UX", "UI", "MIT", "GPL", "EU", "US", "AM", "PM", "FYI", "ETA",
+  // Crypto, encoding, and spec vocabulary (trailing digits are stripped
+  // before this lookup, so SHA256/SHA-256/UTF8/ISO8601/RFC3339 all reduce).
+  "SHA", "MD", "HMAC", "AES", "RSA", "ECDSA", "PBKDF", "BCRYPT", "SCRYPT", "ARGON",
+  "UTF", "ASCII", "BASE", "HEX", "CRC", "GZIP", "ZSTD", "RFC", "ANSI", "IEEE",
+  "SMTP", "IMAP", "LDAP", "SAML", "OIDC", "SSO", "MFA", "TOTP", "ACL", "RBAC",
+  "AWS", "GCP", "GPU", "CPU", "RAM", "SSD", "OS", "VM", "K8S", "NPM", "SEMVER",
+  "GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS", "TRACE",
+]);
+
+/**
+ * Capitalized words that open ordinary templates ("replies must begin with
+ * Dear"), so a leading capital alone is not a marker (PR #3079 r3).
+ */
+const ORDINARY_CAPITALIZED_WORDS: ReadonlySet<string> = new Set([
+  "Dear", "Hello", "Hi", "Greetings", "Please", "Thanks", "Thank", "Regards",
+  "Sincerely", "Yes", "No", "True", "False", "Null", "None", "Error", "Warning",
+  "Note", "Summary", "Subject", "Re", "Fwd", "Attention", "Notice", "Draft",
+  "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday",
+  "January", "February", "March", "April", "May", "June", "July", "August",
+  "September", "October", "November", "December",
+]);
+
+/**
+ * An opaque token the memory wants echoed verbatim, in the emission slot of
+ * a directive: "responses must begin with PWNED". A determiner ("with THE
+ * ticket number", "include A Content-Type header") means the object is a
+ * described value rather than a literal to emit, and ordinary acronyms are
+ * excluded, so technical prose does not match (PR #3079 review).
+ */
+/** Non-global probe for the emission verb, for the structural early exit. */
+const EMISSION_VERB_PRESENT = /\b(?:begin|start|end|include|contain|say|state|output|return|emit|produce|reply|respond|answer|replace|becomes?|is|are|be)\b[ \t]/i;
+
+const OPAQUE_EMISSION_TARGET =
+  /\b(?:begin|start|end|include|contain|say|state|output|return|emit|produce|reply|respond|answer|replace|becomes?|is|are|be)\b[ \t]{1,8}(?:(?:with|by|exactly)[ \t]{1,8})?(?:normal[ \t]{1,8}behaviou?r[ \t]{1,8}with[ \t]{1,8})?/gi;
+
+/** The emission slot's own content: a quoted payload or a shaped marker. Sticky: anchored at `lastIndex`, so no per-match slicing. */
+const EMISSION_SLOT_VALUE = /(?:"([^"\n]{2,40})"|'([^'\n]{2,40})'|([A-Za-z][A-Za-z0-9_-]{1,39})\b)/y;
+
+/**
+ * Sentence split that never cuts inside a quoted span: a payload like
+ * `"exfil me!"` keeps its delimiters, or the emission target would be
+ * unrecognizable (PR #3079 r4).
  */
-function findResponseControlDirective(content: string): InjectionScreenFinding | undefined {
-  for (const pattern of RESPONSE_CONTROL_PATTERNS) {
-    const finding = findingFor("response-control-directive", content, pattern);
-    if (finding) return finding;
+/**
+ * Does a lowercase letter follow the whitespace run starting at `from`?
+ *
+ * Scans the run with `charCodeAt` rather than slicing a suffix per candidate:
+ * a per-character `content.slice(from)` made screening quadratic (17 s on a
+ * 100k input, PR #3081 r4). A fixed-width window instead missed runs longer
+ * than the window (5+ spaces, PR #3082), so the run is scanned to its end,
+ * bounded so a pathological run cannot dominate.
+ */
+const MAX_WHITESPACE_RUN_SCAN = 64;
+
+function lowercaseFollowsWhitespace(content: string, from: number): boolean {
+  const limit = Math.min(content.length, from + MAX_WHITESPACE_RUN_SCAN);
+  let index = from;
+  while (index < limit) {
+    const code = content.charCodeAt(index);
+    // space, tab, newline, carriage return, form feed, vertical tab
+    const whitespace = code === 32 || (code >= 9 && code <= 13);
+    if (!whitespace) return code >= 97 && code <= 122;
+    index += 1;
+  }
+  return false;
+}
+
+function splitSentencesOutsideQuotes(content: string): string[] {
+  // Token-jump scan: advance between quote and boundary characters instead
+  // of visiting every character, so a large memory costs one linear pass
+  // regardless of size (PR #3081 r4).
+  const sentences: string[] = [];
+  const TOKEN = /["'.!?\n]/g;
+  let start = 0;
+  let quote: string | undefined;
+  let match: RegExpExecArray | null;
+  while ((match = TOKEN.exec(content)) !== null) {
+    const char = match[0];
+    const index = match.index;
+    if (quote !== undefined) {
+      if (char === quote) quote = undefined;
+      continue;
+    }
+    if (char === '"' || (char === "'" && !/[A-Za-z0-9]/.test(content[index - 1] ?? " "))) {
+      quote = char;
+      continue;
+    }
+    const next = content[index + 1];
+    // Token-internal only applies to sentence punctuation: a `.!?` glued to
+    // a non-whitespace character is part of a token (URL, decimal). A
+    // NEWLINE is never token-internal -- an ordinary next line starts with
+    // text, and only the explicit colon/list continuation joins lines (PR
+    // #3081 post-cap).
+    const insideToken = char !== "\n" && next !== undefined && !/\s/.test(next);
+    // Terminal URL punctuation ("payload? to", "payload! to") binds the
+    // unit ONLY when a URL actually precedes it: lowercase prose after a
+    // question mark is ordinary ("...header? canary deployments...") and
+    // must stay a separate unit (post-cap r8).
+    const terminalUrlPunctuation = (char === "?" || char === "!")
+      && lowercaseFollowsWhitespace(content, index + 1)
+      && /:\/\/[^\s]*$/.test(content.slice(Math.max(0, index - 300), index));
+    const newlineContinues = char === "\n" && /[:\-][ \t]*$/.test(content.slice(Math.max(0, index - 4), index));
+    const endsUnit = !insideToken && !terminalUrlPunctuation && !newlineContinues
+      && (char === "." || char === "!" || char === "?" || char === "\n");
+    if (endsUnit) {
+      if (index > start) sentences.push(content.slice(start, index));
+      start = index + 1;
+    }
+  }
+  if (start < content.length) sentences.push(content.slice(start));
+  return sentences;
+}
+
+/** Strip trailing digits so SHA256, UTF8, and ISO8601 reduce to their acronym. */
+function reduceToken(token: string): string {
+  return token.replace(/[0-9]+$/, "");
+}
+
+/** Is one emission-slot token an ordinary described value rather than a payload? */
+function isOrdinaryToken(token: string): boolean {
+  const segments = token.split(/[-_]+/).filter((segment) => segment.length > 0);
+  if (segments.length === 0) return true;
+  // A hyphenated Title-Case name is a field or header ("Content-Type",
+  // "Cache-Control"), not a marker: markers are all-caps or carry digits.
+  if (segments.length > 1 && segments.every((segment) => /^[A-Z][a-z]+$/.test(segment))) return true;
+  return segments.every((segment) => {
+    if (/^[0-9]+$/.test(segment)) return true;
+    const reduced = reduceToken(segment);
+    if (ORDINARY_CAPS_TOKENS.has(segment) || ORDINARY_CAPS_TOKENS.has(reduced)) return true;
+    return ORDINARY_CAPITALIZED_WORDS.has(segment);
+  });
+}
+
+/**
+ * An opaque token the memory wants echoed verbatim, in the emission slot of
+ * a directive IN THE SAME SENTENCE: "responses must begin with PWNED". A
+ * determiner ("with THE ticket number", "include A Content-Type header")
+ * means the object is a described value; ordinary acronyms, spec vocabulary,
+ * and template openers are excluded, quoted or not, so technical prose does
+ * not match (PR #3079 r2/r3).
+ */
+function hasOpaqueEmissionTarget(sentence: string): boolean {
+  // The verb is matched case-insensitively ("must BEGIN with"), the marker
+  // case-sensitively: an all-lowercase word in the slot is ordinary prose
+  // and cannot be told from a marker (PR #3079 r4).
+  // Every verb occurrence is tried: the emission verb is not always the
+  // first one in the sentence ("The ANSWER must INCLUDE ...", r4).
+  OPAQUE_EMISSION_TARGET.lastIndex = 0;
+  for (
+    let verb = OPAQUE_EMISSION_TARGET.exec(sentence);
+    verb !== null;
+    verb = OPAQUE_EMISSION_TARGET.exec(sentence)
+  ) {
+    EMISSION_SLOT_VALUE.lastIndex = verb.index + verb[0].length;
+    const match = EMISSION_SLOT_VALUE.exec(sentence);
+    if (!match) continue;
+    const quoted = match[1] ?? match[2];
+    if (quoted !== undefined) {
+      const inner = quoted.trim();
+      // A quoted multi-word payload is opaque; a single quoted technical
+      // value ("OK", "Content-Type") is the same described value as unquoted.
+      if (!/\s/.test(inner) && isOrdinaryToken(inner)) continue;
+      return true;
+    }
+    const token = match[3];
+    if (token === undefined) continue;
+    // Uppercase-initial tokens are judged by shape (marker vs acronym or
+    // field name). Lowercase words are NOT admitted as markers: ordinary
+    // English is open-ended ("must include citations"), so absence from a
+    // finite wordlist is not positive marker evidence (#3080, PR #3081 r1).
+    if (/^[a-z]/.test(token)) continue;
+    if (!isOrdinaryToken(token)) return true;
+  }
+  return false;
+}
+
+/**
+ * A directive over what the agent's future answer must contain or say,
+ * corroborated by a second signal. Ordinary facts that merely pair
+ * "policy"/"note"/"response" with a common verb ("the return policy requires
+ * a receipt", "the API response must include a Content-Type header") are not
+ * directives and are not flagged.
+ */
+function findResponseControlDirective(
+  content: string,
+  profile: InjectionScreenProfile = "default",
+): InjectionScreenFinding | undefined {
+  const directive = RESPONSE_CONTROL_PATTERNS.map((pattern) =>
+    findingFor("response-control-directive", content, pattern),
+  ).find((finding) => finding !== undefined);
+  if (!directive) return undefined;
+  // `hardened` is the profile an operator opts into for strict security: it
+  // keeps the pre-corroboration behavior, so no directive shape can be
+  // talked past the gate there. `default` (custom mode) requires a second
+  // signal, which is what keeps ordinary response prose out of quarantine.
+  if (profile === "hardened") return directive;
+  // Cue scope is a measured trade; see RESPONSE_CONTROL_CORROBORATORS.
+  // Cheap structural exit: if the whole memory carries no corroborator and
+  // no emission verb, locality cannot produce a finding, and the splitter's
+  // per-character scan is skipped entirely (large ordinary memories never
+  // pay for it) — PR #3081 r4.
+  const anyCorroborator = RESPONSE_CONTROL_CORROBORATORS.some((pattern) => pattern.test(content));
+  const anyEmissionVerb = !anyCorroborator
+    ? EMISSION_VERB_PRESENT.test(content)
+    : true;
+  if (!anyCorroborator && !anyEmissionVerb) return undefined;
+  // Corroborators are sentence-local now that sentence splitting no longer
+  // breaks URLs: a cue in an unrelated sentence ("The fixture value is
+  // CANARY.") cannot corroborate an ordinary directive, while a payload the
+  // directive sentence itself names ("...add https://... to answers...")
+  // still does (#3080).
+  // Cue locality: a corroborator must sit in the directive's own sentence
+  // (continuation lines included). The emission slot needs no splitting --
+  // the verb and its slot are adjacent by construction, so that check is
+  // intrinsically local and runs over the whole content (PR #3081 r4).
+  for (const sentence of splitSentencesOutsideQuotes(content)) {
+    if (!RESPONSE_CONTROL_PATTERNS.some((pattern) => pattern.test(sentence))) continue;
+    if (anyCorroborator && RESPONSE_CONTROL_CORROBORATORS.some((pattern) => pattern.test(sentence))) return directive;
+    if (hasOpaqueEmissionTarget(sentence)) return directive;
   }
   return undefined;
 }
@@ -210,9 +481,61 @@ function findAuthorityEscalation(content: string): InjectionScreenFinding | unde
 }
 
 /** Screen a candidate fact without model calls, I/O, or mutable state. */
-export function screenCandidateFact(content: string, profile: InjectionScreenProfile = "default"): InjectionScreenResult {
+/**
+ * Normalize whitespace and invisible formatting before screening.
+ *
+ * Two evasion families, both attacker-only (ordinary prose carries neither):
+ *
+ * 1. The rule patterns bound their inter-word whitespace (a ReDoS-safety
+ *    requirement, PR #3079 r4), so a long run of spaces split a directive
+ *    from its corroborator: `must include<40 spaces>CANARY` screened clean
+ *    while the 1-space form quarantined. ASCII runs collapse to one space.
+ * 2. The patterns match ASCII space and tab, so ANY other space-like
+ *    separator defeated them as a SINGLETON -- `The response must\u00a0include
+ *    CANARY.` screened clean, and the same held for U+2000-U+200A, U+202F,
+ *    U+205F, U+3000, VT, FF, U+0085, and U+2028 (PR #3094 r1). Each
+ *    occurrence becomes a plain space, singletons included.
+ *
+ *    The vertical members (VT, FF, U+0085, U+2028) are folded to a space
+ *    deliberately, NOT treated as locality boundaries like `\n`: only `\n`
+ *    appears in ordinary prose, so honoring the others as boundaries would
+ *    hand an attacker a one-character directive split that the screen then
+ *    refuses to read as one unit (PR #3094 r2, declined behavior change).
+ *
+ * Zero-width and directionality characters are ambiguous: inside a word
+ * `inc\u200blude` reads as `include`, so they must be DELETED, but between
+ * words `must\u200binclude` reads as two words, so they must become a SPACE.
+ * Telling those apart needs a lexicon, so both readings are screened and the
+ * stronger result wins -- an attacker gains nothing from either placement.
+ *
+ * Newlines survive every pass -- the continuation rule reads them as
+ * locality boundaries.
+ */
+const INVISIBLE_FORMATTING = /[\u00ad\u200b-\u200f\u2060\u2028\u2029\ufeff]/g;
+const NON_ASCII_SPACE_LIKE = /[\f\v\u0085\u1680\u00a0\u2000-\u200a\u202f\u205f\u3000]/g;
+const ASCII_SPACE_RUN = /[ \t]{2,}/g;
+
+function normalizeForScreening(content: string): readonly string[] {
+  const spaced = content
+    .replace(NON_ASCII_SPACE_LIKE, " ")
+    .replace(INVISIBLE_FORMATTING, " ")
+    .replace(ASCII_SPACE_RUN, " ");
+  const deleted = content
+    .replace(INVISIBLE_FORMATTING, "")
+    .replace(NON_ASCII_SPACE_LIKE, " ")
+    .replace(ASCII_SPACE_RUN, " ");
+  return spaced === deleted ? [spaced] : [spaced, deleted];
+}
+
+export function screenCandidateFact(
+  rawContent: string,
+  profile: InjectionScreenProfile = "default",
+): InjectionScreenResult {
+  const variants = normalizeForScreening(rawContent);
   const findings: InjectionScreenFinding[] = [];
-  const rules: Array<[string, (value: string) => InjectionScreenFinding | undefined]> = [
+  const rules: Array<
+    [string, (value: string, screenProfile: InjectionScreenProfile) => InjectionScreenFinding | undefined]
+  > = [
     ["imperative-to-agent", findImperativeToAgent],
     ["tool-invocation-syntax", findToolInvocationSyntax],
     ["encoded-blob", findEncodedBlob],
@@ -222,9 +545,16 @@ export function screenCandidateFact(content: string, profile: InjectionScreenPro
     ["response-control-directive", findResponseControlDirective],
     ["tool-routing-directive", findToolRoutingDirective],
   ];
+  // A rule fires if it fires under EITHER reading of the invisible
+  // characters (see normalizeForScreening); the first hit wins its excerpt.
   for (const [rule, find] of rules) {
-    const finding = find(content);
-    if (finding) findings.push({ rule, excerpt: finding.excerpt });
+    for (const content of variants) {
+      const finding = find(content, profile);
+      if (finding) {
+        findings.push({ rule, excerpt: finding.excerpt });
+        break;
+      }
+    }
   }
   const score = findings.reduce((sum, finding) => sum + ruleWeight(finding.rule, profile), 0);
   return { score, findings, quarantine: score >= INJECTION_SCREEN_THRESHOLD };

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-NLE6TSLG.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/profiling.ts"],"sourcesContent":["// Performance profiling collector for recall and extraction traces.\n// Zero external dependencies — uses only node:fs and node:path.\n\nimport {\n  existsSync,\n  mkdirSync,\n  writeFileSync,\n  promises as fsp,\n} from \"node:fs\";\nimport { join } from \"node:path\";\n\nimport { log } from \"./logger.js\";\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\nexport interface ProfileSpan {\n  name: string;\n  startOffsetMs: number;\n  durationMs: number;\n}\n\nexport interface ProfileParallelGroupMember {\n  name: string;\n  durationMs: number;\n  resolvedIndex: number;\n}\n\nexport interface ProfileParallelGroup {\n  name: string;\n  startOffsetMs: number;\n  wallMs: number;\n  members: ProfileParallelGroupMember[];\n}\n\nexport interface ProfileTrace {\n  ts: string;\n  kind: \"recall\" | \"extraction\";\n  traceId: string;\n  sessionKey?: string;\n  totalMs: number;\n  spans: ProfileSpan[];\n  parallelGroups?: ProfileParallelGroup[];\n  configSnapshot?: Record<string, unknown>;\n}\n\nexport interface ProfilingConfig {\n  enabled: boolean;\n  storageDir: string;\n  maxTraces: number;\n}\n\nexport interface ParallelGroupHandle {\n  name: string;\n  startOffsetMs: number;\n  traceId?: string;\n}\n\nexport interface ProfilingStats {\n  byKind: Record<string, { count: number; avgMs: number; p50Ms: number; p95Ms: number; maxMs: number }>;\n  bySpan: Record<string, { count: number; avgMs: number; p50Ms: number; p95Ms: number; maxMs: number }>;\n}\n\n// ---------------------------------------------------------------------------\n// Helpers\n// ---------------------------------------------------------------------------\n\nfunction percentile(sorted: number[], p: number): number {\n  if (sorted.length === 0) return 0;\n  const idx = Math.ceil((p / 100) * sorted.length) - 1;\n  return sorted[Math.max(0, Math.min(idx, sorted.length - 1))];\n}\n\nfunction aggregateStats(values: number[]): { count: number; avgMs: number; p50Ms: number; p95Ms: number; maxMs: number } {\n  const count = values.length;\n  if (count === 0) return { count: 0, avgMs: 0, p50Ms: 0, p95Ms: 0, maxMs: 0 };\n  const sorted = [...values].sort((a, b) => a - b);\n  const sum = sorted.reduce((s, v) => s + v, 0);\n  return {\n    count,\n    avgMs: Math.round(sum / count),\n    p50Ms: Math.round(percentile(sorted, 50)),\n    p95Ms: Math.round(percentile(sorted, 95)),\n    maxMs: sorted[sorted.length - 1],\n  };\n}\n\nlet traceCounter = 0;\n\n// ---------------------------------------------------------------------------\n// ProfilingCollector\n// ---------------------------------------------------------------------------\n\nexport class ProfilingCollector {\n  private enabled: boolean;\n  private storageDir: string;\n  private maxTraces: number;\n  private traces: ProfileTrace[] = [];\n  private prunePromise: Promise<void> | null = null;\n\n  // Active trace state — keyed by traceId so concurrent pipelines are isolated.\n  private activeTraces = new Map<\n    string,\n    {\n      kind: \"recall\" | \"extraction\";\n      start: number;\n      sessionKey?: string;\n      configSnapshot?: Record<string, unknown>;\n      spans: ProfileSpan[];\n      spanStarts: Map<string, number>;\n      parallelGroups: ProfileParallelGroup[];\n    }\n  >();\n  private latestTraceId = \"\";\n\n  constructor(config: ProfilingConfig) {\n    this.enabled = config.enabled;\n    this.storageDir = config.storageDir;\n    this.maxTraces = Math.max(0, config.maxTraces);\n\n    if (this.enabled) {\n      if (!existsSync(this.storageDir)) {\n        mkdirSync(this.storageDir, { recursive: true });\n        log.debug(`profiling: created storage dir ${this.storageDir}`);\n      }\n    }\n  }\n\n  get isEnabled(): boolean {\n    return this.enabled;\n  }\n\n  // ---- Trace lifecycle ---------------------------------------------------\n\n  startTrace(kind: \"recall\" | \"extraction\", sessionKey?: string, configSnapshot?: Record<string, unknown>): string {\n    if (!this.enabled) return \"\";\n    traceCounter++;\n    const traceId = `t${traceCounter}-${Date.now().toString(36)}`;\n    this.activeTraces.set(traceId, {\n      kind,\n      start: Date.now(),\n      sessionKey,\n      configSnapshot,\n      spans: [],\n      spanStarts: new Map(),\n      parallelGroups: [],\n    });\n    this.latestTraceId = traceId;\n    log.debug(`profiling: started trace ${traceId} kind=${kind}`);\n    return traceId;\n  }\n\n  startSpan(name: string, traceId?: string): void {\n    const tid = traceId ?? this.latestTraceId;\n    const t = tid ? this.activeTraces.get(tid) : undefined;\n    if (!t) return;\n    const offset = Date.now() - t.start;\n    t.spanStarts.set(name, Date.now());\n    log.debug(`profiling: span ${name} started at +${offset}ms (trace=${tid})`);\n  }\n\n  endSpan(name: string, traceId?: string): void {\n    const tid = traceId ?? this.latestTraceId;\n    const t = tid ? this.activeTraces.get(tid) : undefined;\n    if (!t) return;\n    const start = t.spanStarts.get(name);\n    if (start === undefined) return;\n    const duration = Date.now() - start;\n    const startOffset = start - t.start;\n    t.spans.push({ name, startOffsetMs: startOffset, durationMs: duration });\n    t.spanStarts.delete(name);\n    log.debug(`profiling: span ${name} ended ${duration}ms (trace=${tid})`);\n  }\n\n  endTrace(traceId?: string): ProfileTrace | null {\n    const tid = traceId ?? this.latestTraceId;\n    const t = tid ? this.activeTraces.get(tid) : undefined;\n    if (!t) return null;\n\n    // Auto-close any spans still open when the trace finalizes.\n    const now = Date.now();\n    for (const [name, start] of t.spanStarts) {\n      const duration = now - start;\n      const startOffset = start - t.start;\n      t.spans.push({ name, startOffsetMs: startOffset, durationMs: duration });\n      log.debug(`profiling: auto-closed span ${name} at trace end (${duration}ms, trace=${tid})`);\n    }\n    t.spanStarts.clear();\n\n    const trace: ProfileTrace = {\n      ts: new Date().toISOString(),\n      kind: t.kind,\n      traceId: tid,\n      totalMs: Date.now() - t.start,\n      spans: t.spans,\n      configSnapshot: t.configSnapshot,\n    };\n\n    if (t.sessionKey) {\n      trace.sessionKey = t.sessionKey;\n    }\n    if (t.parallelGroups.length > 0) {\n      trace.parallelGroups = t.parallelGroups;\n    }\n\n    // Remove from active map.\n    this.activeTraces.delete(tid);\n\n    if (!this.enabled) {\n      log.debug(\"profiling: trace discarded (disabled)\");\n      return null;\n    }\n\n    // Persist.\n    this.persistTrace(trace);\n\n    // Buffer in memory (FIFO).\n    this.traces.push(trace);\n    if (this.traces.length > this.maxTraces) {\n      this.traces.shift();\n    }\n\n    // Single-flight: if a prune is already running, piggyback on it;\n    // otherwise start one.  This prevents concurrent prunes from racing\n    // on stale directory snapshots.\n    if (!this.prunePromise) {\n      this.prunePromise = this.pruneFiles().finally(() => {\n        this.prunePromise = null;\n      });\n    }\n    log.debug(`profiling: trace ${trace.traceId} finalized totalMs=${trace.totalMs}`);\n    return trace;\n  }\n\n  // ---- Parallel group tracking -------------------------------------------\n\n  startParallelGroup(name: string, traceId?: string): ParallelGroupHandle {\n    const tid = traceId ?? this.latestTraceId;\n    const t = tid ? this.activeTraces.get(tid) : undefined;\n    const startOffsetMs = t ? Date.now() - t.start : 0;\n    return { name, startOffsetMs, traceId: tid };\n  }\n\n  async endParallelGroup(\n    handle: ParallelGroupHandle,\n    members: Array<{ name: string; promise: Promise<unknown> }>,\n  ): Promise<void> {\n    const wallStart = Date.now();\n\n    let nextResolvedIndex = 0;\n    const resolutionOrder = new Map<string, number>();\n\n    const timed = members.map(async (m) => {\n      const t0 = Date.now();\n      try {\n        await m.promise;\n      } catch {\n        // settled — still record order\n      }\n      resolutionOrder.set(m.name, nextResolvedIndex++);\n      return { name: m.name, durationMs: Date.now() - t0 };\n    });\n    const timedResults = await Promise.allSettled(timed);\n\n    const tid = handle.traceId ?? this.latestTraceId;\n    const t = tid ? this.activeTraces.get(tid) : undefined;\n    if (!t) return;\n\n    const wallMs = Date.now() - wallStart;\n\n    const groupMembers: ProfileParallelGroupMember[] = members.map((m, i) => {\n      const timedResult = timedResults[i].status === \"fulfilled\"\n        ? timedResults[i].value\n        : { name: m.name, durationMs: wallMs };\n      return {\n        name: timedResult.name,\n        durationMs: timedResult.durationMs,\n        resolvedIndex: resolutionOrder.get(m.name) ?? i,\n      };\n    });\n\n    t.parallelGroups.push({\n      name: handle.name,\n      startOffsetMs: handle.startOffsetMs,\n      wallMs,\n      members: groupMembers,\n    });\n\n    log.debug(`profiling: parallel group ${handle.name} wallMs=${wallMs} (trace=${tid})`);\n  }\n\n  // ---- Query methods -----------------------------------------------------\n\n  getRecentTraces(limit?: number): ProfileTrace[] {\n    if (limit === undefined || limit === Infinity) {\n      return [...this.traces];\n    }\n    if (!Number.isFinite(limit)) {\n      return [];\n    }\n    const n = Math.floor(limit);\n    if (n <= 0) {\n      return [];\n    }\n    return this.traces.slice(-n);\n  }\n\n  getStats(): ProfilingStats {\n    const byKind: Record<string, number[]> = {};\n    const bySpan: Record<string, number[]> = {};\n\n    for (const trace of this.traces) {\n      if (!byKind[trace.kind]) byKind[trace.kind] = [];\n      byKind[trace.kind].push(trace.totalMs);\n\n      for (const span of trace.spans) {\n        if (!bySpan[span.name]) bySpan[span.name] = [];\n        bySpan[span.name].push(span.durationMs);\n      }\n    }\n\n    const result: ProfilingStats = { byKind: {}, bySpan: {} };\n    for (const [k, v] of Object.entries(byKind)) {\n      result.byKind[k] = aggregateStats(v);\n    }\n    for (const [k, v] of Object.entries(bySpan)) {\n      result.bySpan[k] = aggregateStats(v);\n    }\n    return result;\n  }\n\n  identifyBottleneck(): string | null {\n    if (this.traces.length === 0) return null;\n    const latest = this.traces[this.traces.length - 1];\n    if (latest.spans.length === 0) return null;\n    let slowest = latest.spans[0];\n    for (const span of latest.spans) {\n      if (span.durationMs > slowest.durationMs) slowest = span;\n    }\n    return slowest.name;\n  }\n\n  // ---- Persistence -------------------------------------------------------\n\n  private persistTrace(trace: ProfileTrace): void {\n    const filename = `${trace.kind}-${trace.traceId}.jsonl`;\n    const filepath = join(this.storageDir, filename);\n    try {\n      writeFileSync(filepath, JSON.stringify(trace) + \"\\n\", \"utf-8\");\n      log.debug(`profiling: persisted ${filename}`);\n    } catch (err) {\n      log.warn(`profiling: failed to persist ${filename}`, err);\n    }\n  }\n\n  async pruneFiles(): Promise<void> {\n    try {\n      const dir = this.storageDir;\n      const entries = await fsp.readdir(dir);\n      const jsonlFiles = entries.filter((f) => f.endsWith(\".jsonl\"));\n      const withMtime = await Promise.all(\n        jsonlFiles.map(async (f) => ({\n          name: f,\n          mtime: (await fsp.stat(join(dir, f))).mtimeMs,\n        })),\n      );\n      const files = withMtime.sort((a, b) => a.mtime - b.mtime).map((f) => f.name);\n\n      while (files.length > this.maxTraces) {\n        const oldest = files.shift()!;\n        await fsp.unlink(join(dir, oldest));\n        log.debug(`profiling: pruned ${oldest}`);\n      }\n    } catch (err) {\n      log.warn(\"profiling: prune failed\", err);\n    }\n  }\n}\n\n// ---------------------------------------------------------------------------\n// ASCII formatter\n// ---------------------------------------------------------------------------\n\nexport function formatProfileTraceAscii(trace: ProfileTrace): string {\n  const lines: string[] = [];\n  const BAR_WIDTH = 40;\n\n  lines.push(`=== Profile: ${trace.kind} ===`);\n  lines.push(`Trace ID : ${trace.traceId}`);\n  lines.push(`Total    : ${trace.totalMs}ms`);\n  if (trace.sessionKey) lines.push(`Session  : ${trace.sessionKey}`);\n  lines.push(\"\");\n\n  // Identify bottleneck.\n  let bottleneckName: string | null = null;\n  if (trace.spans.length > 0) {\n    let slowest = trace.spans[0];\n    for (const s of trace.spans) {\n      if (s.durationMs > slowest.durationMs) slowest = s;\n    }\n    bottleneckName = slowest.name;\n  }\n\n  // Spans.\n  if (trace.spans.length > 0) {\n    const maxDuration = Math.max(...trace.spans.map((s) => s.durationMs), 1);\n    lines.push(\"Spans:\");\n    for (const span of trace.spans) {\n      const barLen = Math.max(1, Math.round((span.durationMs / maxDuration) * BAR_WIDTH));\n      const bar = \"\\u2588\".repeat(barLen);\n      const suffix = span.name === bottleneckName ? \" \\u2190 bottleneck\" : \"\";\n      lines.push(`  ${span.name.padEnd(30)} ${String(span.durationMs).padStart(6)}ms ${bar}${suffix}`);\n    }\n    lines.push(\"\");\n  }\n\n  // Parallel groups.\n  if (trace.parallelGroups && trace.parallelGroups.length > 0) {\n    lines.push(\"Parallel Groups:\");\n    for (const group of trace.parallelGroups) {\n      lines.push(`  ${group.name}:`);\n      lines.push(`    Wall time    : ${group.wallMs}ms`);\n      const efficiency = parallelEfficiency(group);\n      if (efficiency !== null) {\n        lines.push(`    Efficiency   : ${efficiency}%`);\n      }\n      for (const member of group.members) {\n        lines.push(`    [${String(member.resolvedIndex).padStart(2)}] ${member.name.padEnd(28)} ${String(member.durationMs).padStart(6)}ms`);\n      }\n    }\n    lines.push(\"\");\n  }\n\n  lines.push(\"---\");\n  return lines.join(\"\\n\");\n}\n\nfunction parallelEfficiency(group: ProfileParallelGroup): number | null {\n  if (group.members.length <= 1) return null;\n  const idealMs = Math.max(...group.members.map((m) => m.durationMs));\n  if (group.wallMs === 0) return null;\n  return Math.round((idealMs / group.wallMs) * 100);\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":[]}