@remnic/core 9.3.715 → 9.3.716

package/dist/transfer/types.d.ts

@@ -313,13 +313,13 @@ declare const CapsuleBlockSchema: z.ZodObject<{
         peerProfiles: boolean;
     }>;
 }, "strip", z.ZodTypeAny, {
-    schemaVersion: string;
     includes: {
         procedural: boolean;
         taxonomy: boolean;
         identityAnchors: boolean;
         peerProfiles: boolean;
     };
+    schemaVersion: string;
     id: string;
     version: string;
     description: string;
@@ -334,13 +334,13 @@ declare const CapsuleBlockSchema: z.ZodObject<{
         directAnswerEnabled: boolean;
     };
 }, {
-    schemaVersion: string;
     includes: {
         procedural: boolean;
         taxonomy: boolean;
         identityAnchors: boolean;
         peerProfiles: boolean;
     };
+    schemaVersion: string;
     id: string;
     version: string;
     description: string;
@@ -464,13 +464,13 @@ declare const ExportManifestV2Schema: z.ZodObject<{
             peerProfiles: boolean;
         }>;
     }, "strip", z.ZodTypeAny, {
-        schemaVersion: string;
         includes: {
             procedural: boolean;
             taxonomy: boolean;
             identityAnchors: boolean;
             peerProfiles: boolean;
         };
+        schemaVersion: string;
         id: string;
         version: string;
         description: string;
@@ -485,13 +485,13 @@ declare const ExportManifestV2Schema: z.ZodObject<{
             directAnswerEnabled: boolean;
         };
     }, {
-        schemaVersion: string;
         includes: {
             procedural: boolean;
             taxonomy: boolean;
             identityAnchors: boolean;
             peerProfiles: boolean;
         };
+        schemaVersion: string;
         id: string;
         version: string;
         description: string;
@@ -518,13 +518,13 @@ declare const ExportManifestV2Schema: z.ZodObject<{
     pluginVersion: string;
     includesTranscripts: boolean;
     capsule: {
-        schemaVersion: string;
         includes: {
             procedural: boolean;
             taxonomy: boolean;
             identityAnchors: boolean;
             peerProfiles: boolean;
         };
+        schemaVersion: string;
         id: string;
         version: string;
         description: string;
@@ -551,13 +551,13 @@ declare const ExportManifestV2Schema: z.ZodObject<{
     pluginVersion: string;
     includesTranscripts: boolean;
     capsule: {
-        schemaVersion: string;
         includes: {
             procedural: boolean;
             taxonomy: boolean;
             identityAnchors: boolean;
             peerProfiles: boolean;
         };
+        schemaVersion: string;
         id: string;
         version: string;
         description: string;
@@ -683,13 +683,13 @@ declare const ExportBundleV2Schema: z.ZodObject<{
                 peerProfiles: boolean;
             }>;
         }, "strip", z.ZodTypeAny, {
-            schemaVersion: string;
             includes: {
                 procedural: boolean;
                 taxonomy: boolean;
                 identityAnchors: boolean;
                 peerProfiles: boolean;
             };
+            schemaVersion: string;
             id: string;
             version: string;
             description: string;
@@ -704,13 +704,13 @@ declare const ExportBundleV2Schema: z.ZodObject<{
                 directAnswerEnabled: boolean;
             };
         }, {
-            schemaVersion: string;
             includes: {
                 procedural: boolean;
                 taxonomy: boolean;
                 identityAnchors: boolean;
                 peerProfiles: boolean;
             };
+            schemaVersion: string;
             id: string;
             version: string;
             description: string;
@@ -737,13 +737,13 @@ declare const ExportBundleV2Schema: z.ZodObject<{
         pluginVersion: string;
         includesTranscripts: boolean;
         capsule: {
-            schemaVersion: string;
             includes: {
                 procedural: boolean;
                 taxonomy: boolean;
                 identityAnchors: boolean;
                 peerProfiles: boolean;
             };
+            schemaVersion: string;
             id: string;
             version: string;
             description: string;
@@ -770,13 +770,13 @@ declare const ExportBundleV2Schema: z.ZodObject<{
         pluginVersion: string;
         includesTranscripts: boolean;
         capsule: {
-            schemaVersion: string;
             includes: {
                 procedural: boolean;
                 taxonomy: boolean;
                 identityAnchors: boolean;
                 peerProfiles: boolean;
             };
+            schemaVersion: string;
             id: string;
             version: string;
             description: string;
@@ -819,13 +819,13 @@ declare const ExportBundleV2Schema: z.ZodObject<{
         pluginVersion: string;
         includesTranscripts: boolean;
         capsule: {
-            schemaVersion: string;
             includes: {
                 procedural: boolean;
                 taxonomy: boolean;
                 identityAnchors: boolean;
                 peerProfiles: boolean;
             };
+            schemaVersion: string;
             id: string;
             version: string;
             description: string;
@@ -858,13 +858,13 @@ declare const ExportBundleV2Schema: z.ZodObject<{
         pluginVersion: string;
         includesTranscripts: boolean;
         capsule: {
-            schemaVersion: string;
             includes: {
                 procedural: boolean;
                 taxonomy: boolean;
                 identityAnchors: boolean;
                 peerProfiles: boolean;
             };
+            schemaVersion: string;
             id: string;
             version: string;
             description: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remnic/core",
-  "version": "9.3.715",
+  "version": "9.3.716",
   "description": "Framework-agnostic Remnic memory engine — orchestrator, storage, extraction, search, trust zones",
   "type": "module",
   "main": "dist/index.js",
@@ -2966,7 +2966,7 @@
     "core"
   ],
   "peerDependencies": {
-    "@remnic/coding-graph": "^9.3.715"
+    "@remnic/coding-graph": "^9.3.716"
   },
   "peerDependenciesMeta": {
     "@remnic/coding-graph": {

package/src/capabilities.test.ts

@@ -96,6 +96,34 @@ test("resolveCapabilities returns a frozen object", () => {
   assert.equal(Object.isFrozen(caps), true, "CapabilitySet must be frozen");
 });
 
+test("resolveCapabilities is deterministic — same config always yields identical gate values (one-resolution-per-op #1523)", () => {
+  // The one-resolution-per-op contract (issue #1523): resolve ONCE at the
+  // operation entry, thread the frozen result down. This test proves the
+  // resolution is deterministic — calling it twice with the same config
+  // produces identical values for every gate, so there is never a reason to
+  // re-resolve mid-operation.
+  const config = parseConfig({
+    rerankCacheEnabled: true,
+    recallDirectAnswerEnabled: false,
+    recallMmrEnabled: true,
+    recallPlannerLlmEnabled: true,
+    graphRecallEnabled: true,
+  });
+  const first = resolveCapabilities(config);
+  const second = resolveCapabilities(config);
+  for (const field of FIELDS) {
+    assert.equal(
+      first[field],
+      second[field],
+      `field ${field} must be deterministic across resolutions`,
+    );
+  }
+  // Both must be frozen — a mid-operation mutation would break the contract.
+  assert.equal(Object.isFrozen(first), true);
+  assert.equal(Object.isFrozen(second), true);
+});
+
+
 // ---------------------------------------------------------------------------
 // GraphConstructionCapabilitySet — gate-parity tests (issue #1566 Cluster A).
 //

package/src/direct-answer-wiring.test.ts

@@ -13,7 +13,6 @@ import type { TrustZoneName } from "./trust-zones.js";
 type WiringConfig = DirectAnswerWiringInput["config"];
 
 const BASE_CONFIG: WiringConfig = {
-  recallDirectAnswerEnabled: true,
   recallDirectAnswerTokenOverlapFloor: 0.5,
   recallDirectAnswerImportanceFloor: 0.7,
   recallDirectAnswerAmbiguityMargin: 0.15,
@@ -105,17 +104,24 @@ test("tryDirectAnswer disabled-path does not call any source accessor", async ()
   assert.deepEqual(sources.calls.importance, []);
 });
 
-// ── Backward-compat (#1523): omit top-level `enabled`, fall back to config ──
+// ── One-resolution-per-op (#1523): `enabled` is the sole gate ──────────────
 
-test("tryDirectAnswer falls back to config.recallDirectAnswerEnabled when `enabled` is omitted (disabled)", async () => {
-  // Old input shape: config carries recallDirectAnswerEnabled: false and no
-  // top-level `enabled`. Must short-circuit as "disabled" (identical to the
-  // pre-#1523 behavior) rather than treating undefined as enabled.
-  const sources = makeMockSources({ memories: [makeMemory()] });
+test("tryDirectAnswer disabled when `enabled: false` even with matching candidates (caps wins over any config-derived value)", async () => {
+  // Issue #1523 contract: the resolved capability is the sole gate.
+  // `enabled` comes from `resolveCapabilities(config).recallDirectAnswer`,
+  // resolved ONCE at the recall entry. This test proves the gate value is
+  // authoritative — when it says disabled, the function short-circuits
+  // regardless of candidate quality.
+  const sources = makeMockSources({
+    memories: [makeMemory({ tags: ["pnpm"], content: "remnic uses pnpm" })],
+    trustZones: { m1: "trusted" },
+    importance: { m1: 0.9 },
+  });
   const result = await tryDirectAnswer({
-    query: "does not matter",
+    query: "package manager remnic",
     namespace: "default",
-    config: { ...BASE_CONFIG, recallDirectAnswerEnabled: false },
+    config: BASE_CONFIG,
+    enabled: false,
     sources,
   });
   assert.equal(result.eligible, false);
@@ -123,9 +129,9 @@ test("tryDirectAnswer falls back to config.recallDirectAnswerEnabled when `enabl
   assert.equal(sources.calls.listCandidates, 0);
 });
 
-test("tryDirectAnswer falls back to config.recallDirectAnswerEnabled when `enabled` is omitted (enabled)", async () => {
-  // Old input shape with recallDirectAnswerEnabled: true and no `enabled` must
-  // NOT short-circuit — it proceeds to materialize candidates.
+test("tryDirectAnswer proceeds when `enabled: true` and candidates match", async () => {
+  // Same contract, positive case: when the resolved capability says enabled,
+  // the function proceeds to materialize candidates.
   const sources = makeMockSources({
     memories: [makeMemory({ tags: ["pnpm"], content: "remnic uses pnpm" })],
     trustZones: { m1: "trusted" },
@@ -134,7 +140,8 @@ test("tryDirectAnswer falls back to config.recallDirectAnswerEnabled when `enabl
   const result = await tryDirectAnswer({
     query: "package manager remnic",
     namespace: "default",
-    config: BASE_CONFIG, // recallDirectAnswerEnabled: true
+    config: BASE_CONFIG,
+    enabled: true,
     sources,
   });
   assert.notEqual(result.reason, "disabled");

package/src/direct-answer-wiring.ts

@@ -14,8 +14,9 @@
  *
  * Short-circuit contract:
  *
- * - When the resolved gate (`input.enabled` if supplied, else
- *   `config.recallDirectAnswerEnabled`) is `false`, the function returns the
+ * - When the resolved gate (`input.enabled`, projected from
+ *   `caps.recallDirectAnswer` at the recall-operation entry) is `false`, the
+ *   function returns the
  *   eligibility verdict with reason `"disabled"` without touching any source
  *   accessor.  This is the documented default.
  * - When enabled, the wiring cheaply drops non-trusted-zone memories
@@ -74,7 +75,6 @@ export interface DirectAnswerWiringInput {
   namespace: string;
   config: Pick<
     PluginConfig,
-    | "recallDirectAnswerEnabled"
     | "recallDirectAnswerTokenOverlapFloor"
     | "recallDirectAnswerImportanceFloor"
     | "recallDirectAnswerAmbiguityMargin"
@@ -82,13 +82,12 @@ export interface DirectAnswerWiringInput {
   >;
   /**
    * Direct-answer capability gate, resolved once at the recall-operation entry
-   * (issue #1523: `caps.recallDirectAnswer`). OPTIONAL and additive: when the
-   * caller supplies it, this module and the orchestrator agree on a single
-   * resolved gate value for the whole operation. When omitted, we fall back to
-   * `config.recallDirectAnswerEnabled` so existing callers on the old input
-   * shape keep identical behavior.
+   * via `resolveCapabilities(config).recallDirectAnswer` (issue #1523). This
+   * is the sole gate — the function no longer reads the config flag directly.
+   * Callers MUST pass the resolved capability so the whole operation agrees on
+   * a single gate value.
    */
-  enabled?: boolean;
+  enabled: boolean;
   sources: DirectAnswerSources;
   queryEntityRefs?: string[];
   abortSignal?: AbortSignal;
@@ -105,10 +104,7 @@ export async function tryDirectAnswer(
   const { query, namespace, config, enabled, sources, queryEntityRefs, abortSignal } = input;
 
   const eligibilityConfig: DirectAnswerConfig = {
-    // Prefer the resolved capability when supplied; fall back to the config
-    // flag so callers on the old input shape (config-only, no `enabled`) get
-    // identical gating (issue #1523 backward-compat).
-    enabled: enabled ?? config.recallDirectAnswerEnabled,
+    enabled,
     tokenOverlapFloor: config.recallDirectAnswerTokenOverlapFloor,
     importanceFloor: config.recallDirectAnswerImportanceFloor,
     ambiguityMargin: config.recallDirectAnswerAmbiguityMargin,

package/src/orchestrator.ts

@@ -1396,12 +1396,11 @@ export async function resolveRecallModeDecisionAsync(
   options: RecallModeGraphOptions & {
     config: PluginConfig;
     /**
-     * Recall-operation capability gates (issue #1523). OPTIONAL and additive:
-     * the recall orchestrator passes a resolved set, but existing callers that
-     * only pass `config` + planner flags stay backward-compatible — the LLM
-     * planner gate falls back to `config.recallPlannerLlmEnabled` when omitted.
+     * Recall-operation capability gates (issue #1523). REQUIRED: the recall
+     * orchestrator always passes a resolved set — the LLM planner gate reads
+     * `caps.recallPlannerLlm`, never re-derives from config.
      */
-    caps?: CapabilitySet;
+    caps: CapabilitySet;
     hints?: string[];
     llm?: FallbackLlmClient;
     signal?: AbortSignal;
@@ -1410,10 +1409,8 @@ export async function resolveRecallModeDecisionAsync(
   const heuristicDecision = resolveRecallModeDecision(options);
 
   // Planner globally off, or LLM planning not opted into → heuristic only.
-  // Prefer the resolved capability when supplied; otherwise fall back to the
-  // config flag so callers on the old option shape get identical gating.
-  const plannerLlmEnabled =
-    options.caps?.recallPlannerLlm ?? options.config.recallPlannerLlmEnabled;
+  // Read the resolved capability (issue #1523) — never re-derive from config.
+  const plannerLlmEnabled = options.caps.recallPlannerLlm;
   if (!options.plannerEnabled || !plannerLlmEnabled) {
     return heuristicDecision;
   }
@@ -1423,9 +1420,9 @@ export async function resolveRecallModeDecisionAsync(
     options.prompt,
     options.hints,
     options.config,
+    options.caps,
     options.llm,
     options.signal,
-    options.caps,
   );
 
   // Shadow mode: record what the LLM would have chosen but keep the heuristic

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

@@ -41,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, undefined, resolveCapabilities(config));
+  const result = await planRecallModeLLM("what did we decide about auth?", undefined, config, resolveCapabilities(config), llm, undefined);
 
   assert.equal(captured.length, 0, "LLM must not be contacted when disabled");
   assert.equal(result.source, "heuristic");
@@ -55,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, undefined, resolveCapabilities(config));
+  const result = await planRecallModeLLM("restart the gateway", undefined, config, resolveCapabilities(config), llm, undefined);
 
   assert.equal(result.source, "llm");
   assert.equal(result.mode, "graph_mode");
@@ -75,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, undefined, resolveCapabilities(config));
+  await planRecallModeLLM("check status", undefined, config, resolveCapabilities(config), llm, undefined);
 
   assert.equal(captured.length, 1);
   // recallPlannerModel is tried first (prepended), taskModelChain is the fallback chain.
@@ -98,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, undefined, resolveCapabilities(config));
+  await planRecallModeLLM("summarize the project", undefined, config, resolveCapabilities(config), llm, undefined);
 
   assert.equal(captured.length, 1);
   assert.equal(captured[0]?.model, "openai/gpt-5.5");
@@ -110,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, undefined, resolveCapabilities(config));
+  const result = await planRecallModeLLM("what happened during the outage?", undefined, config, resolveCapabilities(config), llm, undefined);
 
   assert.equal(result.source, "heuristic-fallback");
   assert.equal(result.fallbackUsed, true);
@@ -124,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, undefined, resolveCapabilities(config));
+  const result = await planRecallModeLLM("how did we get here?", undefined, config, resolveCapabilities(config), llm, undefined);
 
   assert.equal(result.source, "heuristic-fallback");
   assert.equal(result.fallbackUsed, true);
@@ -140,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, undefined, resolveCapabilities(config));
+  const result = await planRecallModeLLM("anything", undefined, config, resolveCapabilities(config), llm, undefined);
 
   assert.equal(captured.length, 0, "no network attempt when nothing is routable");
   assert.equal(result.source, "heuristic-fallback");
@@ -156,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, undefined, resolveCapabilities(config));
+  const result = await planRecallModeLLM("anything", undefined, config, resolveCapabilities(config), llm, undefined);
 
   assert.equal(captured.length, 1, "qualified model override → still attempt the call");
   assert.equal(captured[0]?.model, "openai/gpt-5.5");
@@ -171,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, resolveCapabilities(config));
+  const result = await planRecallModeLLM("what did we decide?", undefined, config, resolveCapabilities(config), llm, ac.signal);
 
   assert.equal(captured.length, 0, "no LLM call when the recall is already aborted");
   assert.equal(result.source, "heuristic-fallback");
@@ -185,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, resolveCapabilities(config));
+  await planRecallModeLLM("check status", undefined, config, resolveCapabilities(config), llm, ac.signal);
 
   assert.equal(captured.length, 1);
   assert.equal(captured[0]?.signal, ac.signal, "recall abort signal must reach FallbackLlmClient");
@@ -196,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, undefined, resolveCapabilities(config));
+  const result = await planRecallModeLLM("   ", undefined, config, resolveCapabilities(config), llm, undefined);
 
   assert.equal(captured.length, 0);
   assert.equal(result.mode, "no_recall"); // heuristic returns no_recall for empty
@@ -223,3 +223,22 @@ test("resolveRecallPlannerLlmOptions drops bare model names but keeps provider-q
   );
   assert.equal(qualified.model, "anthropic/claude-haiku-4-5");
 });
+
+test("caps.recallPlannerLlm is authoritative — disabled caps wins over enabled config flag (one-resolution-per-op #1523)", async () => {
+  // Issue #1523 contract: the capability resolved at the operation entry is
+  // THE gate. Construct a deliberate mismatch: config says enabled, but the
+  // resolved CapabilitySet says disabled. The function must NOT call the LLM.
+  const config = parseConfig({ recallPlannerLlmEnabled: true });
+  const captured: Array<Record<string, unknown>> = [];
+  const llm = stubLlm({ capturedOptions: captured, result: { mode: "full" } });
+
+  // Manually construct caps with recallPlannerLlm: false (simulating a
+  // resolution that disagrees with the raw config — e.g. session toggle off).
+  const caps = { ...resolveCapabilities(config), recallPlannerLlm: false } as any;
+
+  const result = await planRecallModeLLM("what did we decide?", undefined, config, caps, llm, undefined);
+
+  assert.equal(captured.length, 0, "LLM must not be contacted when caps says disabled, even if config says enabled");
+  assert.equal(result.source, "heuristic");
+  assert.equal(result.reason, "llm-disabled");
+});

package/src/recall-planner-llm.ts

@@ -188,16 +188,15 @@ export async function planRecallModeLLM(
   prompt: string,
   hints: string[] | undefined,
   config: PluginConfig,
+  caps: CapabilitySet,
   llm?: FallbackLlmClient,
   signal?: AbortSignal,
-  caps?: CapabilitySet,
 ): Promise<RecallPlannerLlmResult> {
   const heuristicMode = planRecallMode(prompt);
 
-  // `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;
+  // The recall-operation entry resolved this gate once (issue #1523); read the
+  // capability, never re-derive it from raw config here.
+  const plannerLlmEnabled = caps.recallPlannerLlm;
   if (!plannerLlmEnabled) {
     return heuristicResult(heuristicMode, "heuristic", "llm-disabled", 0, false);
   }

package/dist/chunk-OQH5XUH3.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 the resolved gate (`input.enabled` if supplied, else\n *   `config.recallDirectAnswerEnabled`) is `false`, the function returns the\n *   eligibility verdict with reason `\"disabled\"` without touching any source\n *   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  /**\n   * Direct-answer capability gate, resolved once at the recall-operation entry\n   * (issue #1523: `caps.recallDirectAnswer`). OPTIONAL and additive: when the\n   * caller supplies it, this module and the orchestrator agree on a single\n   * resolved gate value for the whole operation. When omitted, we fall back to\n   * `config.recallDirectAnswerEnabled` so existing callers on the old input\n   * shape keep identical behavior.\n   */\n  enabled?: boolean;\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, enabled, sources, queryEntityRefs, abortSignal } = input;\n\n  const eligibilityConfig: DirectAnswerConfig = {\n    // Prefer the resolved capability when supplied; fall back to the config\n    // flag so callers on the old input shape (config-only, no `enabled`) get\n    // identical gating (issue #1523 backward-compat).\n    enabled: 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"]}