@remnic/core 9.3.665 → 9.3.667

package/src/recall-planner-llm.test.ts

@@ -2,6 +2,7 @@ import assert from "node:assert/strict";
 import test from "node:test";
 
 import { parseConfig } from "./config.js";
+import { resolveCapabilities } from "./capabilities.js";
 import {
   planRecallModeLLM,
   resolveRecallPlannerLlmOptions,
@@ -40,7 +41,7 @@ test("returns heuristic without calling the LLM when recallPlannerLlmEnabled is
   const captured: Array<Record<string, unknown>> = [];
   const llm = stubLlm({ capturedOptions: captured, result: { mode: "no_recall" } });
 
-  const result = await planRecallModeLLM("what did we decide about auth?", undefined, config, llm);
+  const result = await planRecallModeLLM("what did we decide about auth?", undefined, config, llm, undefined, resolveCapabilities(config));
 
   assert.equal(captured.length, 0, "LLM must not be contacted when disabled");
   assert.equal(result.source, "heuristic");
@@ -54,7 +55,7 @@ test("uses the LLM classification when enabled", async () => {
   const config = parseConfig({ recallPlannerLlmEnabled: true });
   const llm = stubLlm({ result: { mode: "graph_mode", reason: "asks for root cause" }, modelUsed: "anthropic/claude" });
 
-  const result = await planRecallModeLLM("restart the gateway", undefined, config, llm);
+  const result = await planRecallModeLLM("restart the gateway", undefined, config, llm, undefined, resolveCapabilities(config));
 
   assert.equal(result.source, "llm");
   assert.equal(result.mode, "graph_mode");
@@ -74,7 +75,7 @@ test("forwards taskModelChain AND recallPlannerModel in gateway mode (provider-a
   const captured: Array<Record<string, unknown>> = [];
   const llm = stubLlm({ capturedOptions: captured, result: { mode: "minimal" } });
 
-  await planRecallModeLLM("check status", undefined, config, llm);
+  await planRecallModeLLM("check status", undefined, config, llm, undefined, resolveCapabilities(config));
 
   assert.equal(captured.length, 1);
   // recallPlannerModel is tried first (prepended), taskModelChain is the fallback chain.
@@ -97,7 +98,7 @@ test("plugin mode passes only the explicit model, no gateway chain", async () =>
   const captured: Array<Record<string, unknown>> = [];
   const llm = stubLlm({ capturedOptions: captured, result: { mode: "full" } });
 
-  await planRecallModeLLM("summarize the project", undefined, config, llm);
+  await planRecallModeLLM("summarize the project", undefined, config, llm, undefined, resolveCapabilities(config));
 
   assert.equal(captured.length, 1);
   assert.equal(captured[0]?.model, "openai/gpt-5.5");
@@ -109,7 +110,7 @@ test("falls back to heuristic when the LLM throws", async () => {
   const config = parseConfig({ recallPlannerLlmEnabled: true });
   const llm = stubLlm({ throwError: "boom" });
 
-  const result = await planRecallModeLLM("what happened during the outage?", undefined, config, llm);
+  const result = await planRecallModeLLM("what happened during the outage?", undefined, config, llm, undefined, resolveCapabilities(config));
 
   assert.equal(result.source, "heuristic-fallback");
   assert.equal(result.fallbackUsed, true);
@@ -123,7 +124,7 @@ test("falls back to heuristic when the LLM returns no parseable result", async (
   const config = parseConfig({ recallPlannerLlmEnabled: true });
   const llm = stubLlm({ result: null });
 
-  const result = await planRecallModeLLM("how did we get here?", undefined, config, llm);
+  const result = await planRecallModeLLM("how did we get here?", undefined, config, llm, undefined, resolveCapabilities(config));
 
   assert.equal(result.source, "heuristic-fallback");
   assert.equal(result.fallbackUsed, true);
@@ -139,7 +140,7 @@ test("falls back without a network attempt when the chain is empty and the model
   const captured: Array<Record<string, unknown>> = [];
   const llm = stubLlm({ available: false, capturedOptions: captured, result: { mode: "full" } });
 
-  const result = await planRecallModeLLM("anything", undefined, config, llm);
+  const result = await planRecallModeLLM("anything", undefined, config, llm, undefined, resolveCapabilities(config));
 
   assert.equal(captured.length, 0, "no network attempt when nothing is routable");
   assert.equal(result.source, "heuristic-fallback");
@@ -155,7 +156,7 @@ test("attempts the call (and falls back) when a provider-qualified model overrid
   const captured: Array<Record<string, unknown>> = [];
   const llm = stubLlm({ available: false, capturedOptions: captured, result: null });
 
-  const result = await planRecallModeLLM("anything", undefined, config, llm);
+  const result = await planRecallModeLLM("anything", undefined, config, llm, undefined, resolveCapabilities(config));
 
   assert.equal(captured.length, 1, "qualified model override → still attempt the call");
   assert.equal(captured[0]?.model, "openai/gpt-5.5");
@@ -170,7 +171,7 @@ test("an already-aborted recall short-circuits to the heuristic without an LLM c
   const ac = new AbortController();
   ac.abort();
 
-  const result = await planRecallModeLLM("what did we decide?", undefined, config, llm, ac.signal);
+  const result = await planRecallModeLLM("what did we decide?", undefined, config, llm, ac.signal, resolveCapabilities(config));
 
   assert.equal(captured.length, 0, "no LLM call when the recall is already aborted");
   assert.equal(result.source, "heuristic-fallback");
@@ -184,7 +185,7 @@ test("forwards the abort signal into the LLM call (cancellation contract)", asyn
   const llm = stubLlm({ capturedOptions: captured, result: { mode: "minimal" } });
   const ac = new AbortController();
 
-  await planRecallModeLLM("check status", undefined, config, llm, ac.signal);
+  await planRecallModeLLM("check status", undefined, config, llm, ac.signal, resolveCapabilities(config));
 
   assert.equal(captured.length, 1);
   assert.equal(captured[0]?.signal, ac.signal, "recall abort signal must reach FallbackLlmClient");
@@ -195,7 +196,7 @@ test("empty prompts skip the LLM entirely", async () => {
   const captured: Array<Record<string, unknown>> = [];
   const llm = stubLlm({ capturedOptions: captured, result: { mode: "full" } });
 
-  const result = await planRecallModeLLM("   ", undefined, config, llm);
+  const result = await planRecallModeLLM("   ", undefined, config, llm, undefined, resolveCapabilities(config));
 
   assert.equal(captured.length, 0);
   assert.equal(result.mode, "no_recall"); // heuristic returns no_recall for empty

package/src/recall-planner-llm.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 
 import type { PluginConfig, RecallPlanMode } from "./types.js";
+import type { CapabilitySet } from "./capabilities.js";
 import { planRecallMode } from "./intent.js";
 import {
   FallbackLlmClient,
@@ -189,10 +190,15 @@ export async function planRecallModeLLM(
   config: PluginConfig,
   llm?: FallbackLlmClient,
   signal?: AbortSignal,
+  caps?: CapabilitySet,
 ): Promise<RecallPlannerLlmResult> {
   const heuristicMode = planRecallMode(prompt);
 
-  if (!config.recallPlannerLlmEnabled) {
+  // `caps` is OPTIONAL and additive (issue #1523). Prefer the resolved
+  // capability when supplied; fall back to the config flag so existing callers
+  // that pass only `config` keep identical gating.
+  const plannerLlmEnabled = caps?.recallPlannerLlm ?? config.recallPlannerLlmEnabled;
+  if (!plannerLlmEnabled) {
     return heuristicResult(heuristicMode, "heuristic", "llm-disabled", 0, false);
   }
 

package/src/storage-fallback-category-dirs.test.ts

@@ -27,7 +27,7 @@
  */
 
 import assert from "node:assert/strict";
-import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { mkdir, mkdtemp, rm, symlink, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import test from "node:test";
@@ -356,6 +356,155 @@ test("question-queue items written by writeQuestion() do NOT leak into fallback
  * directly with a config object that explicitly disables QMD, proving the disk
  * scan a QMD-disabled deployment relies on returns every category.
  */
+/**
+ * Symlink containment (same walker-hardening class as PR #1563 / issue #1546).
+ *
+ * `collectActiveMemoryPaths()` walks the RECALL_FALLBACK_DIRS category dirs for
+ * the QMD-unavailable filesystem recall fallback. A category dir symlinked
+ * outside `memoryDir` (e.g. `decisions/` -> an external directory) must NOT be
+ * followed — otherwise out-of-store files leak into recall results. The walker
+ * now `lstat`s each dir (skipping symlinks/non-dirs), realpaths it, and asserts
+ * it stays inside the memory root; per entry it skips symlinks and asserts the
+ * file resolves inside the root before including it.
+ */
+test("category dir symlinked outside memoryDir does NOT leak files into fallback recall", async (t) => {
+  if (process.platform === "win32") {
+    t.skip("directory symlink setup is platform-specific");
+    return;
+  }
+  const baseDir = await mkdtemp(path.join(os.tmpdir(), "engram-1497-symlink-dir-"));
+  const outsideDir = await mkdtemp(path.join(os.tmpdir(), "engram-1497-symlink-out-"));
+  const storage = new StorageManager(baseDir);
+  StorageManager.clearAllStaticCaches();
+  storage.invalidateAllMemoriesCacheForDir();
+  try {
+    // A genuine in-store memory that MUST still be recalled.
+    await seedMemory(baseDir, "facts", "real-fact", "fact", "A genuine in-store fact.");
+
+    // An out-of-store memory reachable only via a symlinked category dir.
+    await writeFile(
+      path.join(outsideDir, "leaked.md"),
+      memoryFile("leaked-secret", "decision", "Out-of-store file must never be recalled."),
+      "utf-8",
+    );
+    // `decisions/` is a RECALL_FALLBACK_DIRS category dir; point it outside the store.
+    await symlink(outsideDir, path.join(baseDir, "decisions"), "dir");
+
+    storage.invalidateAllMemoriesCacheForDir();
+    const memories = await storage.readAllMemories();
+    const foundIds = new Set(memories.map((m) => m.frontmatter.id));
+
+    assert.ok(foundIds.has("real-fact"), "the genuine in-store fact must still be recalled");
+    assert.ok(
+      !foundIds.has("leaked-secret"),
+      "a symlinked-out category dir must not leak files into recall",
+    );
+    assert.equal(memories.length, 1, "only the in-store memory should be returned");
+  } finally {
+    StorageManager.clearAllStaticCaches();
+    await rm(baseDir, { recursive: true, force: true });
+    await rm(outsideDir, { recursive: true, force: true });
+  }
+});
+
+test("symlinked entry nested inside a category dir does NOT leak into fallback recall", async (t) => {
+  if (process.platform === "win32") {
+    t.skip("directory symlink setup is platform-specific");
+    return;
+  }
+  const baseDir = await mkdtemp(path.join(os.tmpdir(), "engram-1497-symlink-entry-"));
+  const outsideDir = await mkdtemp(path.join(os.tmpdir(), "engram-1497-symlink-entry-out-"));
+  const storage = new StorageManager(baseDir);
+  StorageManager.clearAllStaticCaches();
+  storage.invalidateAllMemoriesCacheForDir();
+  try {
+    // A genuine in-store memory in the same category dir that holds the symlink.
+    await seedMemory(baseDir, "facts", "real-fact", "fact", "A genuine in-store fact.");
+
+    await writeFile(
+      path.join(outsideDir, "leaked.md"),
+      memoryFile("nested-leak", "fact", "Out-of-store nested file must never be recalled."),
+      "utf-8",
+    );
+    // A symlinked *entry* inside facts/ that escapes the store.
+    await symlink(outsideDir, path.join(baseDir, "facts", "escape"), "dir");
+
+    storage.invalidateAllMemoriesCacheForDir();
+    const memories = await storage.readAllMemories();
+    const foundIds = new Set(memories.map((m) => m.frontmatter.id));
+
+    assert.ok(foundIds.has("real-fact"), "the genuine in-store fact must still be recalled");
+    assert.ok(
+      !foundIds.has("nested-leak"),
+      "a symlinked entry escaping the store must not leak files into recall",
+    );
+    assert.equal(memories.length, 1, "only the in-store memory should be returned");
+  } finally {
+    StorageManager.clearAllStaticCaches();
+    await rm(baseDir, { recursive: true, force: true });
+    await rm(outsideDir, { recursive: true, force: true });
+  }
+});
+
+/**
+ * Regression for Cursor Bugbot "Poisoned md skips sibling subdirs".
+ *
+ * Per-entry containment/realpath failures must be isolated so they cannot drop
+ * sibling `.md` files or, crucially, the nested-subdir recursion. This asserts
+ * that a category dir which also contains a symlinked-out entry still recurses
+ * into its real nested subdirectory and returns every in-store memory, while
+ * the out-of-store target stays excluded.
+ */
+test("a guarded/skipped sibling entry does NOT drop nested in-store memories", async (t) => {
+  if (process.platform === "win32") {
+    t.skip("directory symlink setup is platform-specific");
+    return;
+  }
+  const baseDir = await mkdtemp(path.join(os.tmpdir(), "engram-1497-sibling-"));
+  const outsideDir = await mkdtemp(path.join(os.tmpdir(), "engram-1497-sibling-out-"));
+  const storage = new StorageManager(baseDir);
+  StorageManager.clearAllStaticCaches();
+  storage.invalidateAllMemoriesCacheForDir();
+  try {
+    const factsDir = path.join(baseDir, "facts");
+    await mkdir(factsDir, { recursive: true });
+    // A top-level in-store memory and a nested in-store memory in the SAME
+    // category dir that also holds the symlinked-out sibling.
+    await writeFile(
+      path.join(factsDir, "top.md"),
+      memoryFile("top-fact", "fact", "Top-level in-store fact."),
+      "utf-8",
+    );
+    await seedMemory(baseDir, "facts", "deep-fact", "fact", "Deeply nested in-store fact.", {
+      nested: true,
+    });
+
+    await writeFile(
+      path.join(outsideDir, "leaked.md"),
+      memoryFile("leaked-secret", "fact", "Out-of-store file must never be recalled."),
+      "utf-8",
+    );
+    // A symlinked-out sibling entry alongside the real files/subdir.
+    await symlink(outsideDir, path.join(factsDir, "escape"), "dir");
+
+    storage.invalidateAllMemoriesCacheForDir();
+    const memories = await storage.readAllMemories();
+    const foundIds = new Set(memories.map((m) => m.frontmatter.id));
+
+    assert.ok(foundIds.has("top-fact"), "the top-level in-store fact must be recalled");
+    assert.ok(
+      foundIds.has("deep-fact"),
+      "the nested in-store fact must still be recalled past a skipped sibling",
+    );
+    assert.ok(!foundIds.has("leaked-secret"), "the symlinked-out file must not leak");
+    assert.equal(memories.length, 2, "exactly the two in-store memories should be returned");
+  } finally {
+    StorageManager.clearAllStaticCaches();
+    await rm(baseDir, { recursive: true, force: true });
+    await rm(outsideDir, { recursive: true, force: true });
+  }
+});
+
 test("QMD-disabled deployment: disk-scan collector returns all categories", async () => {
   const baseDir = await mkdtemp(path.join(os.tmpdir(), "engram-1497-qmd-off-"));
   // entitySchemas is the only other constructor arg; QMD is never constructed by

package/src/storage.ts

@@ -1,10 +1,11 @@
-import { access, readdir, readFile, stat, writeFile, mkdir, unlink, rename, appendFile, open } from "node:fs/promises";
-import { appendFileSync, createReadStream, mkdirSync, readFileSync, statSync } from "node:fs";
+import { access, lstat, readdir, readFile, realpath, stat, writeFile, mkdir, unlink, rename, appendFile, open } from "node:fs/promises";
+import { appendFileSync, createReadStream, mkdirSync, readFileSync, statSync, type Dirent } from "node:fs";
 import { createHash } from "node:crypto";
 import path from "node:path";
 import { log } from "./logger.js";
 import { isErrnoCode } from "./utils/errno.js";
 import { RECALL_FALLBACK_DIRS, getCategoryDir, categoryDirName } from "./utils/category-dir.js";
+import { assertPathInsideRoot } from "./utils/path-containment.js";
 import { getCachedEntities, invalidateAllForDir, setCachedEntities } from "./memory-cache.js";
 import { rotateMarkdownFileToArchive } from "./hygiene.js";
 import { sanitizeMemoryContent } from "./sanitize.js";
@@ -4082,23 +4083,59 @@ export class StorageManager {
   private async collectActiveMemoryPaths(): Promise<string[]> {
     const filePaths: string[] = [];
 
+    // Resolve the memory root once for containment checks below. A category dir
+    // symlinked outside memoryDir (e.g. decisions/ -> an external dir) must NOT
+    // pull out-of-store files into the QMD-unavailable recall fallback (info
+    // leak). Same walker-hardening pattern as document-scanner.ts / cli.ts /
+    // consolidation-provenance-check.ts; reuses the shared containment helper.
+    let memoryRootReal: string;
+    try {
+      memoryRootReal = await realpath(this.baseDir);
+    } catch {
+      return filePaths;
+    }
+
     const collectPaths = async (dir: string) => {
+      // Directory-level guard, isolated from per-entry handling: skip symlinked
+      // or non-directory category dirs and assert the resolved dir stays inside
+      // the memory root before reading. A failure here means the whole subtree
+      // does not exist or escaped the store — fail closed by skipping it.
+      let entries: Dirent[];
       try {
-        const entries = await readdir(dir, { withFileTypes: true });
-        const subdirs: string[] = [];
-        for (const entry of entries) {
-          const fullPath = path.join(dir, entry.name);
-          if (entry.isDirectory()) {
-            subdirs.push(fullPath);
-          } else if (entry.name.endsWith(".md")) {
+        const dirStat = await lstat(dir);
+        if (dirStat.isSymbolicLink() || !dirStat.isDirectory()) return;
+        assertPathInsideRoot(memoryRootReal, await realpath(dir), dir);
+        entries = await readdir(dir, { withFileTypes: true });
+      } catch {
+        return;
+      }
+
+      const subdirs: string[] = [];
+      for (const entry of entries) {
+        // Never follow symlinked entries out of the store.
+        if (entry.isSymbolicLink()) continue;
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+          subdirs.push(fullPath);
+        } else if (entry.name.endsWith(".md")) {
+          // Isolate per-entry failures in their own try/catch: a containment or
+          // realpath failure on ONE .md entry must not drop sibling files or,
+          // crucially, the deferred subdir recursion below (Cursor Bugbot:
+          // "Poisoned md skips sibling subdirs"). Mirrors the per-file try/catch
+          // in search/document-scanner.ts scanDir and
+          // consolidation-provenance-check.ts walkMarkdownFiles.
+          try {
+            assertPathInsideRoot(memoryRootReal, await realpath(fullPath), fullPath);
             filePaths.push(fullPath);
+          } catch {
+            // Skip just this entry (symlink/containment/realpath failure).
           }
         }
-        for (const subdir of subdirs) {
-          await collectPaths(subdir);
-        }
-      } catch {
-        // Directory does not exist yet.
+      }
+      // Recurse into real subdirectories regardless of any single poisoned entry
+      // above, so valid nested in-store memories are never dropped.
+      for (const subdir of subdirs) {
+        await collectPaths(subdir);
       }
     };
 

package/dist/chunk-SQZ42MKH.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/taxonomy/resolver.ts","../src/direct-answer-wiring.ts"],"sourcesContent":["/**\n * Resolver decision tree for the MECE taxonomy.\n *\n * Given extracted content and its MemoryCategory, determines which\n * taxonomy category the knowledge should be filed under.\n */\n\nimport type { MemoryCategory } from \"../types.js\";\nimport type { ResolverDecision, Taxonomy, TaxonomyCategory } from \"./types.js\";\n\nconst DEFAULT_CATEGORY_ID = \"facts\";\n\n/**\n * Resolve a piece of content to a taxonomy category.\n *\n * Algorithm:\n * 1. Find all taxonomy categories whose `memoryCategories` include\n *    the given `memoryCategory`.\n * 2. If exactly one match, return it with confidence 1.0.\n * 3. If multiple matches, prefer the strongest exact-token keyword\n *    overlap from filing rules. Use priority only as a tie-breaker.\n *    If no filing rules match, choose the explicit/default fallback\n *    category instead of letting low-priority generic terms win.\n * 4. If no match, fall back to the \"facts\" category (or first\n *    category if \"facts\" is absent) with low confidence.\n * 5. Always populate `alternatives` with other plausible categories.\n */\nexport function resolveCategory(\n  content: string,\n  memoryCategory: MemoryCategory,\n  taxonomy: Taxonomy,\n): ResolverDecision {\n  const contentTokens = tokenizeKeywordText(content);\n\n  // Step 1: find matching categories\n  const matches = taxonomy.categories.filter((cat) =>\n    cat.memoryCategories.includes(memoryCategory),\n  );\n\n  if (matches.length === 0) {\n    // No taxonomy category accepts this MemoryCategory — fall back\n    const fallback =\n      taxonomy.categories.find((c) => c.id === DEFAULT_CATEGORY_ID) ??\n      taxonomy.categories[0];\n    if (!fallback) {\n      return {\n        categoryId: DEFAULT_CATEGORY_ID,\n        confidence: 0,\n        reason: \"Taxonomy is empty; using default category\",\n        alternatives: [],\n      };\n    }\n    const alternatives = taxonomy.categories\n      .filter((c) => c.id !== fallback.id)\n      .map((c) => ({\n        categoryId: c.id,\n        reason: c.description,\n      }));\n    return {\n      categoryId: fallback.id,\n      confidence: 0.3,\n      reason: `No taxonomy category maps to MemoryCategory \"${memoryCategory}\"; falling back to \"${fallback.name}\"`,\n      alternatives,\n    };\n  }\n\n  if (matches.length === 1) {\n    const match = matches[0]!;\n    const alternatives = taxonomy.categories\n      .filter((c) => c.id !== match.id)\n      .map((c) => ({\n        categoryId: c.id,\n        reason: c.description,\n      }));\n    return {\n      categoryId: match.id,\n      confidence: 1.0,\n      reason: `Unique match: MemoryCategory \"${memoryCategory}\" maps to \"${match.name}\"`,\n      alternatives,\n    };\n  }\n\n  // Multiple matches — use filing rule keyword heuristics + priority\n  const scored = matches.map((cat) => ({\n    cat,\n    keywordScore: computeKeywordScoreForTokens(contentTokens, cat),\n  }));\n\n  // Sort by keyword score descending, then priority ascending (lower wins)\n  scored.sort((a, b) => {\n    if (b.keywordScore !== a.keywordScore) return b.keywordScore - a.keywordScore;\n    return a.cat.priority - b.cat.priority;\n  });\n\n  const topScored = scored[0]!;\n  const best = topScored.keywordScore > 0\n    ? topScored\n    : {\n        cat: selectFallbackCategory(matches) ?? topScored.cat,\n        keywordScore: 0,\n      };\n  const runnerUp = scored[1];\n\n  // Confidence is higher when keyword match clearly differentiates\n  const confidence =\n    best.keywordScore > 0 && (!runnerUp || best.keywordScore > runnerUp.keywordScore)\n      ? 0.9\n      : 0.7;\n\n  const alternatives = taxonomy.categories\n    .filter((c) => c.id !== best.cat.id)\n    .map((c) => ({\n      categoryId: c.id,\n      reason: c.description,\n    }));\n\n  const reason =\n    best.keywordScore > 0\n      ? `Filing rules for \"${best.cat.name}\" matched content keywords (priority ${best.cat.priority})`\n      : `No filing rules matched content keywords; using fallback category \"${best.cat.name}\"`;\n\n  return {\n    categoryId: best.cat.id,\n    confidence,\n    reason,\n    alternatives,\n  };\n}\n\n/**\n * Compute a simple keyword overlap score between content and\n * a category's filing rules + description.\n */\nfunction computeKeywordScoreForTokens(contentTokens: Set<string>, cat: TaxonomyCategory): number {\n  let score = 0;\n  const ruleText = [...cat.filingRules, cat.description]\n    .join(\" \")\n    .toLowerCase();\n\n  const keywords = tokenizeKeywordText(ruleText);\n\n  for (const kw of keywords) {\n    if (contentTokens.has(kw)) {\n      score += 1;\n    }\n  }\n  return score;\n}\n\nfunction tokenizeKeywordText(value: string): Set<string> {\n  return new Set(\n    value\n      .toLowerCase()\n      .split(/[^a-z0-9]+/)\n      .map((word) => word.trim())\n      .filter((word) => word.length >= 3 && !TAXONOMY_KEYWORD_STOPWORDS.has(word)),\n  );\n}\n\nfunction selectFallbackCategory(\n  categories: readonly TaxonomyCategory[],\n): TaxonomyCategory | undefined {\n  return categories.find((cat) => cat.id === DEFAULT_CATEGORY_ID) ??\n    categories.find((cat) => {\n      const text = `${cat.id} ${cat.name} ${cat.description} ${cat.filingRules.join(\" \")}`.toLowerCase();\n      return /\\b(general|fallback)\\b/.test(text);\n    });\n}\n\nconst TAXONOMY_KEYWORD_STOPWORDS = new Set([\n  \"about\",\n  \"all\",\n  \"and\",\n  \"are\",\n  \"for\",\n  \"from\",\n  \"has\",\n  \"into\",\n  \"not\",\n  \"the\",\n  \"this\",\n  \"was\",\n  \"with\",\n]);\n","/**\n * Direct-answer wiring (issue #518 slice 3).\n *\n * Binds the pure eligibility decision (`direct-answer.ts`) to the data\n * sources needed to build candidates: storage, trust-zones, taxonomy,\n * and importance scoring.  Kept as a separate module so that:\n *\n * - The eligibility layer stays pure and unit-testable without stores.\n * - Each caller injects its own source accessors.  The orchestrator\n *   binding is a follow-on slice; tests here use mock sources.\n * - The wiring is safe to ship alone — nothing calls `tryDirectAnswer`\n *   yet, so enabling this module's presence does not change recall\n *   behavior.  The next slice adds exactly one call site before QMD.\n *\n * Short-circuit contract:\n *\n * - When `config.recallDirectAnswerEnabled === false`, the function\n *   returns the eligibility verdict with reason `\"disabled\"` without\n *   touching any source accessor.  This is the documented default.\n * - When enabled, the wiring cheaply drops non-trusted-zone memories\n *   and ineligible taxonomy buckets before computing importance, so\n *   the eligibility module sees a pre-filtered candidate set.  The\n *   eligibility module still performs the same checks itself — this\n *   module is purely an I/O and prefiltering layer.\n */\n\nimport type { MemoryFile, PluginConfig } from \"./types.js\";\nimport type { TrustZoneName } from \"./trust-zones.js\";\nimport type { Taxonomy } from \"./taxonomy/types.js\";\nimport { resolveCategory } from \"./taxonomy/resolver.js\";\nimport { normalizeRecallTokens } from \"./recall-tokenization.js\";\nimport { throwIfAborted } from \"./abort-error.js\";\nimport {\n  isDirectAnswerEligible,\n  type DirectAnswerCandidate,\n  type DirectAnswerConfig,\n  type DirectAnswerResult,\n} from \"./direct-answer.js\";\n\n/**\n * Caller-provided accessors for candidate sourcing.  Decouples the\n * wiring from any specific storage / trust-zone / importance backend.\n */\nexport interface DirectAnswerSources {\n  /**\n   * List memories eligible to be considered for direct-answer.\n   * Callers are expected to return only active, non-superseded memories\n   * in the requested namespace; the wiring will cheaply re-filter on\n   * trust zone and taxonomy bucket and hand the rest to the eligibility\n   * module, which applies the full gate ladder.\n   */\n  listCandidateMemories(options: {\n    namespace: string;\n    abortSignal?: AbortSignal;\n  }): Promise<MemoryFile[]>;\n  /**\n   * Resolve the trust-zone record for a memory.  Returns `null` when\n   * the memory has no trust-zone record (treated as not trusted).\n   */\n  trustZoneFor(memoryId: string): Promise<TrustZoneName | null>;\n  /**\n   * Resolve a calibrated importance score in [0, 1] for a memory.\n   */\n  importanceFor(memory: MemoryFile): number;\n  /**\n   * Taxonomy used to classify memories into direct-answer buckets.\n   */\n  taxonomy: Taxonomy;\n}\n\nexport interface DirectAnswerWiringInput {\n  query: string;\n  namespace: string;\n  config: Pick<\n    PluginConfig,\n    | \"recallDirectAnswerEnabled\"\n    | \"recallDirectAnswerTokenOverlapFloor\"\n    | \"recallDirectAnswerImportanceFloor\"\n    | \"recallDirectAnswerAmbiguityMargin\"\n    | \"recallDirectAnswerEligibleTaxonomyBuckets\"\n  >;\n  sources: DirectAnswerSources;\n  queryEntityRefs?: string[];\n  abortSignal?: AbortSignal;\n}\n\n/**\n * Attempt direct-answer resolution.  Returns the eligibility verdict\n * produced by `isDirectAnswerEligible` with candidates materialized\n * from the caller-supplied sources.\n */\nexport async function tryDirectAnswer(\n  input: DirectAnswerWiringInput,\n): Promise<DirectAnswerResult> {\n  const { query, namespace, config, sources, queryEntityRefs, abortSignal } = input;\n\n  const eligibilityConfig: DirectAnswerConfig = {\n    enabled: config.recallDirectAnswerEnabled,\n    tokenOverlapFloor: config.recallDirectAnswerTokenOverlapFloor,\n    importanceFloor: config.recallDirectAnswerImportanceFloor,\n    ambiguityMargin: config.recallDirectAnswerAmbiguityMargin,\n    eligibleTaxonomyBuckets: config.recallDirectAnswerEligibleTaxonomyBuckets,\n  };\n\n  // Short-circuit disabled case before touching any I/O.\n  if (!eligibilityConfig.enabled) {\n    return isDirectAnswerEligible({\n      query,\n      candidates: [],\n      config: eligibilityConfig,\n      queryEntityRefs,\n    });\n  }\n\n  // Short-circuit empty-query case before any I/O.  isDirectAnswerEligible\n  // deterministically returns reason \"empty-query\" when the query\n  // normalizes to zero searchable tokens; there's no point materializing\n  // candidates just to reach the same verdict, and doing so would\n  // surface avoidable upstream errors for requests that should exit\n  // immediately.\n  if (normalizeRecallTokens(query).length === 0) {\n    return isDirectAnswerEligible({\n      query,\n      candidates: [],\n      config: eligibilityConfig,\n      queryEntityRefs,\n    });\n  }\n\n  throwIfAborted(abortSignal, \"direct-answer wiring aborted\");\n  const memories = await sources.listCandidateMemories({ namespace, abortSignal });\n  throwIfAborted(abortSignal, \"direct-answer wiring aborted\");\n  const candidates: DirectAnswerCandidate[] = [];\n\n  for (const memory of memories) {\n    // Throw rather than returning a partial verdict — a mid-loop abort\n    // that left competing candidates unprocessed could otherwise surface\n    // a spurious \"eligible\" result that the ambiguity gate never got a\n    // chance to reject.  The check repeats after every await so an\n    // abort that lands during the in-flight I/O on the final memory\n    // (after which no further iteration would exist) still stops us.\n    throwIfAborted(abortSignal, \"direct-answer wiring aborted\");\n\n    const trustZone = await sources.trustZoneFor(memory.frontmatter.id);\n    throwIfAborted(abortSignal, \"direct-answer wiring aborted\");\n\n    // Cheap pre-filter: non-trusted memories can't qualify, so skip\n    // taxonomy and importance resolution for them.\n    if (trustZone !== \"trusted\") continue;\n\n    const decision = resolveCategory(\n      memory.content,\n      memory.frontmatter.category,\n      sources.taxonomy,\n    );\n    const taxonomyBucket = decision.categoryId;\n    if (!eligibilityConfig.eligibleTaxonomyBuckets.includes(taxonomyBucket)) continue;\n\n    const importanceScore = sources.importanceFor(memory);\n\n    candidates.push({\n      memory,\n      trustZone,\n      taxonomyBucket,\n      importanceScore,\n    });\n  }\n\n  // Final check — if abort landed during the trust-zone await for the\n  // last memory, the loop condition no longer fires.  Guard before we\n  // hand candidates to the eligibility gate.\n  throwIfAborted(abortSignal, \"direct-answer wiring aborted\");\n\n  return isDirectAnswerEligible({\n    query,\n    candidates,\n    config: eligibilityConfig,\n    queryEntityRefs,\n  });\n}\n"],"mappings":"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","names":["alternatives"]}