@remnic/core 1.1.10 → 1.1.12

package/dist/chunk-6AUUAZEX.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, pick the one with the lowest priority\n *    number (highest precedence). Apply keyword heuristics from\n *    filing rules as a secondary signal.\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 contentLower = content.toLowerCase();\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: computeKeywordScore(contentLower, 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 best = scored[0]!;\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      : `Priority tie-break: \"${best.cat.name}\" has lowest priority number (${best.cat.priority})`;\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 computeKeywordScore(contentLower: string, cat: TaxonomyCategory): number {\n  let score = 0;\n  const ruleText = [...cat.filingRules, cat.description]\n    .join(\" \")\n    .toLowerCase();\n\n  // Extract meaningful words (3+ chars) from the rule text\n  const keywords = ruleText\n    .split(/[^a-z0-9]+/)\n    .filter((w) => w.length >= 3);\n\n  for (const kw of keywords) {\n    if (contentLower.includes(kw)) {\n      score += 1;\n    }\n  }\n  return score;\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"]}