@remnic/core 1.1.0 → 1.1.1

package/dist/contradiction-scan-E3GJTI4F.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/contradiction/contradiction-judge.ts","../src/contradiction/contradiction-scan.ts"],"sourcesContent":["/**\n * Contradiction Judge — LLM-as-judge for semantic contradiction detection (issue #520).\n *\n * Pairs semantically-similar memories and classifies their relationship.\n * Reuses the extraction-judge adapter pattern but with a contradiction-specific\n * prompt and verdict taxonomy.\n *\n * Design constraints:\n *   - Default verdict on any failure is \"needs-user\" (rule 48: least-privileged default).\n *   - Never auto-resolve; all verdicts enter the review queue.\n *   - Content-hash caching avoids redundant LLM calls across runs.\n */\n\nimport { createHash } from \"node:crypto\";\nimport { log } from \"../logger.js\";\nimport type { PluginConfig } from \"../types.js\";\nimport type { LocalLlmClient } from \"../local-llm.js\";\nimport type { FallbackLlmClient } from \"../fallback-llm.js\";\nimport { extractJsonCandidates } from \"../json-extract.js\";\n\n// ── Types ──────────────────────────────────────────────────────────────────────\n\nexport type ContradictionVerdict =\n  | \"contradicts\"\n  | \"independent\"\n  | \"duplicates\"\n  | \"needs-user\";\n\nexport interface ContradictionJudgeInput {\n  /** Memory ID of the first fact. */\n  memoryIdA: string;\n  /** Memory ID of the second fact. */\n  memoryIdB: string;\n  /** Content text of the first fact. */\n  textA: string;\n  /** Content text of the second fact. */\n  textB: string;\n  /** Category of the first fact (optional context). */\n  categoryA?: string;\n  /** Category of the second fact (optional context). */\n  categoryB?: string;\n}\n\nexport interface ContradictionJudgeResult {\n  /** Memory IDs of the pair. */\n  memoryIdA: string;\n  memoryIdB: string;\n  /** Verdict from the judge. */\n  verdict: ContradictionVerdict;\n  /** Human-readable rationale. */\n  rationale: string;\n  /** Confidence in [0, 1]. */\n  confidence: number;\n}\n\nexport interface ContradictionJudgeBatchResult {\n  /** Results keyed by pair key (\"idA:idB\"). */\n  results: Map<string, ContradictionJudgeResult>;\n  /** Number served from cache. */\n  cached: number;\n  /** Number produced by LLM call. */\n  judged: number;\n  /** Total wall-clock time in ms. */\n  elapsed: number;\n}\n\n// ── Prompt ─────────────────────────────────────────────────────────────────────\n\nconst CONTRADICTION_JUDGE_PROMPT = `You are a memory contradiction classifier. You will receive pairs of stored memories and must classify their semantic relationship.\n\nFor each pair, respond with a JSON array where each element has:\n- \"pairKey\": the pairKey provided in the input\n- \"verdict\": one of \"contradicts\", \"independent\", \"duplicates\", \"needs-user\"\n- \"rationale\": one sentence explaining why\n- \"confidence\": number between 0 and 1\n\nVERDICT DEFINITIONS:\n- \"contradicts\": The two memories make claims that cannot both be true. One must be wrong or outdated.\n- \"duplicates\": The two memories convey essentially the same information (near-paraphrase).\n- \"independent\": The memories are topically similar but do not conflict or duplicate.\n- \"needs-user\": Cannot determine with sufficient confidence; requires human review.\n\nIMPORTANT:\n- Be conservative. When in doubt, prefer \"needs-user\" over a wrong classification.\n- Two memories about the same entity/topic are NOT necessarily contradictory.\n- Temporal changes (\"Joshua uses pnpm\" vs \"Joshua switched to npm\") ARE contradictions.\n- Different aspects of the same entity (\"Joshua uses pnpm\" vs \"Joshua works on Remnic\") are \"independent\".`;\n\n// ── Cache ──────────────────────────────────────────────────────────────────────\n\n/** Module-level fallback cache — only used when caller does not supply one. */\nlet defaultVerdictCache: Map<string, ContradictionJudgeResult> = new Map();\nconst CACHE_MAX = 10_000;\n\nfunction pairKey(idA: string, idB: string): string {\n  const sorted = [idA, idB].sort();\n  return `${sorted[0]}:${sorted[1]}`;\n}\n\nfunction contentHash(a: ContradictionJudgeInput): string {\n  // Sort each side pair to be order-independent (matching pairKey behavior)\n  const sides = [\n    [a.textA.trim(), (a.categoryA ?? \"\").trim()].join(\"|\"),\n    [a.textB.trim(), (a.categoryB ?? \"\").trim()].join(\"|\"),\n  ].sort();\n  const normalized = sides.join(\"|||\");\n  return createHash(\"sha256\").update(normalized).digest(\"hex\").slice(0, 16);\n}\n\nexport function createVerdictCache(): Map<string, ContradictionJudgeResult> {\n  return new Map();\n}\n\nexport function clearVerdictCache(): void {\n  defaultVerdictCache.clear();\n}\n\nexport function verdictCacheSize(): number {\n  return defaultVerdictCache.size;\n}\n\n// ── Public API ──────────────────────────────────────────────────────────────────\n\n/**\n * Judge a batch of memory pairs for contradiction.\n *\n * Uses content-hash caching to skip pairs already judged in a prior run.\n * On any LLM failure, all unresolved pairs default to \"needs-user\".\n */\nexport async function judgeContradictionPairs(\n  pairs: ContradictionJudgeInput[],\n  config: PluginConfig,\n  localLlm: LocalLlmClient | null,\n  fallbackLlm: FallbackLlmClient | null,\n  cache?: Map<string, ContradictionJudgeResult>,\n): Promise<ContradictionJudgeBatchResult> {\n  const startTime = Date.now();\n  const results = new Map<string, ContradictionJudgeResult>();\n  const activeCache = cache ?? defaultVerdictCache;\n  let cached = 0;\n  let judged = 0;\n\n  // Partition into cached vs needs-judging\n  const toJudge: ContradictionJudgeInput[] = [];\n  for (const pair of pairs) {\n    const key = pairKey(pair.memoryIdA, pair.memoryIdB);\n    const hash = contentHash(pair);\n    const cachedResult = activeCache.get(hash);\n    if (cachedResult) {\n      results.set(key, { ...cachedResult, memoryIdA: pair.memoryIdA, memoryIdB: pair.memoryIdB });\n      cached++;\n    } else {\n      toJudge.push(pair);\n    }\n  }\n\n  if (toJudge.length === 0) {\n    return { results, cached, judged, elapsed: Date.now() - startTime };\n  }\n\n  // Build the prompt with all pairs\n  const pairDescriptions = toJudge.map((p, i) => {\n    const pk = pairKey(p.memoryIdA, p.memoryIdB);\n    const catA = p.categoryA ? ` [${p.categoryA}]` : \"\";\n    const catB = p.categoryB ? ` [${p.categoryB}]` : \"\";\n    return `Pair ${i + 1} (pairKey: \"${pk}\"):${catA} \"${p.textA}\"${catB} \"${p.textB}\"`;\n  });\n\n  const userMessage = `Classify these ${toJudge.length} memory pair(s):\\n\\n${pairDescriptions.join(\"\\n\\n\")}`;\n\n  // Try LLM call\n  let llmResponse: string | null = null;\n\n  if (localLlm) {\n    try {\n      llmResponse = await callLlm(localLlm, config, userMessage);\n    } catch (err) {\n      log.warn(\"[contradiction-judge] local LLM call failed: %s\", err instanceof Error ? err.message : err);\n    }\n  }\n\n  if (!llmResponse && fallbackLlm) {\n    try {\n      llmResponse = await callLlm(fallbackLlm, config, userMessage);\n    } catch (err) {\n      log.warn(\"[contradiction-judge] fallback LLM call failed: %s\", err instanceof Error ? err.message : err);\n    }\n  }\n\n  // Parse response or default to needs-user\n  if (llmResponse) {\n    const candidates = extractJsonCandidates(llmResponse);\n    const parsed = parseJudgeResponse(candidates, toJudge);\n\n    for (const result of parsed) {\n      const key = pairKey(result.memoryIdA, result.memoryIdB);\n      results.set(key, result);\n\n      // Update cache\n      const input = toJudge.find(\n        (p) => pairKey(p.memoryIdA, p.memoryIdB) === key,\n      );\n      if (input) {\n        const hash = contentHash(input);\n        if (activeCache.size >= CACHE_MAX) {\n          const firstKey = activeCache.keys().next().value;\n          if (firstKey !== undefined) activeCache.delete(firstKey);\n        }\n        activeCache.set(hash, result);\n      }\n      judged++;\n    }\n  } else {\n    // All unresolved → needs-user (rule 48)\n    for (const pair of toJudge) {\n      const key = pairKey(pair.memoryIdA, pair.memoryIdB);\n      const result: ContradictionJudgeResult = {\n        memoryIdA: pair.memoryIdA,\n        memoryIdB: pair.memoryIdB,\n        verdict: \"needs-user\",\n        rationale: \"LLM call failed; requires manual review\",\n        confidence: 0,\n      };\n      results.set(key, result);\n      judged++;\n    }\n  }\n\n  return { results, cached, judged, elapsed: Date.now() - startTime };\n}\n\n// ── Internals ──────────────────────────────────────────────────────────────────\n\nasync function callLlm(\n  client: LocalLlmClient | FallbackLlmClient,\n  config: PluginConfig,\n  userMessage: string,\n): Promise<string> {\n  const messages: Array<{ role: \"user\" | \"assistant\" | \"system\"; content: string }> = [\n    { role: \"system\", content: CONTRADICTION_JUDGE_PROMPT },\n    { role: \"user\", content: userMessage },\n  ];\n  if (\"chatCompletion\" in client && typeof client.chatCompletion === \"function\") {\n    const result = await client.chatCompletion(messages, {\n      temperature: 0.1,\n      maxTokens: 4096,\n    });\n    return result?.content ?? \"\";\n  }\n  // FallbackLlmClient — try OpenAI-compatible chat completions\n  if (\"complete\" in client && typeof (client as Record<string, unknown>).complete === \"function\") {\n    const result = await (client as { complete: (msg: Array<{ role: string; content: string }>) => Promise<{ content: string }> }).complete(messages);\n    return result.content ?? \"\";\n  }\n  return \"\";\n}\n\nfunction parseJudgeResponse(\n  candidates: string[],\n  inputs: ContradictionJudgeInput[],\n): ContradictionJudgeResult[] {\n  const VALID_VERDICTS: ContradictionVerdict[] = [\"contradicts\", \"independent\", \"duplicates\", \"needs-user\"];\n\n  for (const candidate of candidates) {\n    try {\n      const parsed = JSON.parse(candidate);\n      const items = Array.isArray(parsed) ? parsed : [parsed];\n      const results: ContradictionJudgeResult[] = [];\n      const matchedKeys = new Set<string>();\n\n      for (const item of items) {\n        if (!item || typeof item !== \"object\") continue;\n\n        const verdict = typeof item.verdict === \"string\" && VALID_VERDICTS.includes(item.verdict as ContradictionVerdict)\n          ? (item.verdict as ContradictionVerdict)\n          : \"needs-user\";\n\n        const pairKeyVal = typeof item.pairKey === \"string\" ? item.pairKey : null;\n        const input = pairKeyVal\n          ? inputs.find((p) => pairKey(p.memoryIdA, p.memoryIdB) === pairKeyVal)\n          : null;\n\n        // If we can't match the pairKey, fall back to index-based matching\n        const fallbackInput = input ?? inputs[results.length] ?? inputs[0];\n        if (!fallbackInput) continue;\n\n        matchedKeys.add(pairKey(fallbackInput.memoryIdA, fallbackInput.memoryIdB));\n\n        const confidence = typeof item.confidence === \"number\"\n          ? Math.min(1, Math.max(0, item.confidence))\n          : 0.5;\n\n        results.push({\n          memoryIdA: fallbackInput.memoryIdA,\n          memoryIdB: fallbackInput.memoryIdB,\n          verdict,\n          rationale: typeof item.rationale === \"string\" ? item.rationale : \"No rationale provided\",\n          confidence,\n        });\n      }\n\n      // Backfill any inputs the LLM omitted with needs-user\n      for (const inp of inputs) {\n        const key = pairKey(inp.memoryIdA, inp.memoryIdB);\n        if (!matchedKeys.has(key)) {\n          results.push({\n            memoryIdA: inp.memoryIdA,\n            memoryIdB: inp.memoryIdB,\n            verdict: \"needs-user\",\n            rationale: \"LLM response omitted this pair\",\n            confidence: 0,\n          });\n        }\n      }\n\n      if (results.length > 0) return results;\n    } catch {\n      continue;\n    }\n  }\n\n  // All parse attempts failed → needs-user for every input\n  return inputs.map((p) => ({\n    memoryIdA: p.memoryIdA,\n    memoryIdB: p.memoryIdB,\n    verdict: \"needs-user\" as ContradictionVerdict,\n    rationale: \"Failed to parse judge response\",\n    confidence: 0,\n  }));\n}\n\nexport { pairKey as _pairKey, contentHash as _contentHash };\n","/**\n * Contradiction Scan — pair generator + scan driver (issue #520).\n *\n * Nightly cron that pairs semantically-similar active memories within\n * the same namespace, sends candidate pairs to the LLM-as-judge\n * contradiction classifier, and drops contradicting pairs into a\n * review queue for user resolution.\n *\n * Pair generation (cheap pre-filter):\n *   1. Find candidate peers via embedding cosine >= similarityFloor.\n *   2. Restrict to pairs sharing at least one entityRef OR overlapping\n *      topic tokens >= topicOverlapFloor.\n *   3. Skip pairs already judged independent/both-valid within cooldown.\n *   4. Cap per-run work at maxPairsPerRun.\n */\n\nimport type { StorageManager } from \"../storage.js\";\nimport type { PluginConfig, MemoryFile, MemoryStatus } from \"../types.js\";\nimport type { SemanticDedupLookup } from \"../dedup/semantic.js\";\nimport { log } from \"../logger.js\";\nimport { judgeContradictionPairs, type ContradictionJudgeInput } from \"./contradiction-judge.js\";\nimport {\n  writePairs,\n  listPairs,\n  isCoolingDown,\n  computePairId,\n  type ContradictionPair,\n} from \"./contradiction-review.js\";\nimport type { LocalLlmClient } from \"../local-llm.js\";\nimport type { FallbackLlmClient } from \"../fallback-llm.js\";\n\n// ── Types ──────────────────────────────────────────────────────────────────────\n\n/** The set of statuses that represent \"live\" memories eligible for scanning. */\nexport const ACTIVE_STATUSES: Set<MemoryStatus> = new Set([\"active\"]);\n\n/** High-value taxonomy buckets to scan. */\nconst SCAN_CATEGORIES = new Set([\n  \"decision\",\n  \"principle\",\n  \"rule\",\n  \"entity\",\n  \"fact\",\n  \"preference\",\n]);\n\nexport interface ScanResult {\n  /** Total active memories scanned. */\n  scanned: number;\n  /** Candidate pairs generated by the pre-filter. */\n  candidates: number;\n  /** Pairs sent to judge. */\n  judged: number;\n  /** Pairs written to review queue. */\n  queued: number;\n  /** Pairs skipped due to cooldown. */\n  cooledDown: number;\n  /** Total wall-clock time in ms. */\n  elapsedMs: number;\n}\n\nexport interface ScanDependencies {\n  storage: StorageManager;\n  config: PluginConfig;\n  memoryDir: string;\n  /** Pre-built embedding lookup. When provided, used as-is for Strategy 3. */\n  embeddingLookup?: SemanticDedupLookup;\n  /**\n   * Factory to build a namespace-scoped embedding lookup.\n   * When provided, takes precedence over `embeddingLookup`.\n   * The scan driver passes its own `storage` so the lookup queries the correct index.\n   */\n  embeddingLookupFactory?: (storage: StorageManager) => SemanticDedupLookup | undefined;\n  localLlm: LocalLlmClient | null;\n  fallbackLlm: FallbackLlmClient | null;\n  namespace?: string;\n}\n\n// ── Main scan driver ───────────────────────────────────────────────────────────\n\n/**\n * Run a contradiction scan over the memory corpus.\n *\n * This is the entry point called by the nightly cron and by the CLI.\n */\nexport async function runContradictionScan(deps: ScanDependencies): Promise<ScanResult> {\n  const startTime = Date.now();\n  const { storage, config, memoryDir, embeddingLookup, embeddingLookupFactory, localLlm, fallbackLlm, namespace } = deps;\n  const scanConfig = config.contradictionScan;\n\n  // Prefer the factory (which uses the scan's own storage for correct namespace scoping)\n  // over a pre-built lookup (which may use default-namespace storage).\n  const scopedEmbeddingLookup = embeddingLookupFactory\n    ? embeddingLookupFactory(storage)\n    : embeddingLookup;\n\n  if (!scanConfig.enabled) {\n    log.info(\"[contradiction-scan] disabled by config\");\n    return { scanned: 0, candidates: 0, judged: 0, queued: 0, cooledDown: 0, elapsedMs: 0 };\n  }\n\n  // 1. Load active memories in scan categories\n  const memories = await loadEligibleMemories(storage, namespace);\n  log.info(\"[contradiction-scan] loaded %d eligible memories\", memories.length);\n\n  if (memories.length < 2) {\n    return { scanned: memories.length, candidates: 0, judged: 0, queued: 0, cooledDown: 0, elapsedMs: Date.now() - startTime };\n  }\n\n  // 2. Load existing review pairs for cooldown checking\n  const existingPairs = listPairs(memoryDir, { filter: \"all\", namespace, limit: 10000 }).pairs;\n  const existingMap = new Map<string, ContradictionPair>();\n  for (const p of existingPairs) {\n    existingMap.set(p.pairId, p);\n  }\n\n  // 3. Generate candidate pairs\n  const candidates = await generatePairs(memories, existingMap, scanConfig, scopedEmbeddingLookup);\n  const cooledDown = candidates.skipped;\n  log.info(\"[contradiction-scan] generated %d candidates (%d cooled down)\", candidates.pairs.length, cooledDown);\n\n  if (candidates.pairs.length === 0) {\n    return {\n      scanned: memories.length,\n      candidates: 0,\n      judged: 0,\n      queued: 0,\n      cooledDown,\n      elapsedMs: Date.now() - startTime,\n    };\n  }\n\n  // 4. Cap at maxPairsPerRun (deterministic selection by pairId)\n  const capped = candidates.pairs\n    .sort((a, b) => computePairId(a.idA, a.idB).localeCompare(computePairId(b.idA, b.idB)))\n    .slice(0, scanConfig.maxPairsPerRun);\n\n  // 5. Build judge inputs\n  const judgeInputs: ContradictionJudgeInput[] = capped.map((pair) => ({\n    memoryIdA: pair.idA,\n    memoryIdB: pair.idB,\n    textA: pair.textA,\n    textB: pair.textB,\n    categoryA: pair.categoryA,\n    categoryB: pair.categoryB,\n  }));\n\n  // 6. Send to judge (per-scan cache avoids module-level singleton leak)\n  const scanCache = new Map<string, import(\"./contradiction-judge.js\").ContradictionJudgeResult>();\n  const judgeResult = await judgeContradictionPairs(judgeInputs, config, localLlm, fallbackLlm, scanCache);\n  log.info(\"[contradiction-scan] judge completed: %d judged, %d cached in %dms\", judgeResult.judged, judgeResult.cached, judgeResult.elapsed);\n\n  // 7. Write to review queue\n  const queueEntries: Array<Omit<ContradictionPair, \"pairId\"> & { memoryIds: [string, string] }> = [];\n  for (const [key, result] of judgeResult.results) {\n    queueEntries.push({\n      memoryIds: [result.memoryIdA, result.memoryIdB],\n      verdict: result.verdict,\n      rationale: result.rationale,\n      confidence: result.confidence,\n      detectedAt: new Date().toISOString(),\n      // Set lastReviewedAt for non-actionable verdicts so cooldown prevents re-judging\n      lastReviewedAt: result.verdict === \"independent\" ? new Date().toISOString() : undefined,\n      namespace,\n    });\n  }\n\n  const written = writePairs(memoryDir, queueEntries);\n  const elapsed = Date.now() - startTime;\n  log.info(\"[contradiction-scan] complete: %d queued in %dms\", written.length, elapsed);\n\n  return {\n    scanned: memories.length,\n    candidates: candidates.pairs.length,\n    judged: judgeResult.judged,\n    queued: written.length,\n    cooledDown,\n    elapsedMs: elapsed,\n  };\n}\n\n// ── Pair generation ────────────────────────────────────────────────────────────\n\ninterface CandidatePair {\n  idA: string;\n  idB: string;\n  textA: string;\n  textB: string;\n  categoryA?: string;\n  categoryB?: string;\n}\n\ninterface PairGenResult {\n  pairs: CandidatePair[];\n  skipped: number;\n}\n\nasync function generatePairs(\n  memories: MemoryFile[],\n  existingPairs: Map<string, ContradictionPair>,\n  scanConfig: PluginConfig[\"contradictionScan\"],\n  embeddingLookup?: SemanticDedupLookup,\n): Promise<PairGenResult> {\n  const pairs: CandidatePair[] = [];\n  const embeddingPairs: CandidatePair[] = [];\n  let skipped = 0;\n  const seen = new Set<string>();\n\n  // Build index by entityRef for fast lookup\n  const byEntity = new Map<string, MemoryFile[]>();\n  for (const mem of memories) {\n    const entity = mem.frontmatter.entityRef;\n    if (entity) {\n      const existing = byEntity.get(entity) ?? [];\n      existing.push(mem);\n      byEntity.set(entity, existing);\n    }\n  }\n\n  // Strategy 1: Entity-ref based pairing (high precision)\n  for (const [, group] of byEntity) {\n    if (group.length < 2) continue;\n    for (let i = 0; i < group.length; i++) {\n      for (let j = i + 1; j < group.length; j++) {\n        const a = group[i];\n        const b = group[j];\n        const pairId = computePairId(a.frontmatter.id!, b.frontmatter.id!);\n\n        if (seen.has(pairId)) continue;\n        seen.add(pairId);\n\n        // Check cooldown\n        const existing = existingPairs.get(pairId);\n        if (existing && isCoolingDown(existing, scanConfig.cooldownDays)) {\n          skipped++;\n          continue;\n        }\n\n        pairs.push({\n          idA: a.frontmatter.id!,\n          idB: b.frontmatter.id!,\n          textA: a.content,\n          textB: b.content,\n          categoryA: a.frontmatter.category as string | undefined,\n          categoryB: b.frontmatter.category as string | undefined,\n        });\n      }\n    }\n  }\n\n  // Strategy 2: Tag/topic overlap for memories without shared entityRef\n  const noEntity = memories.filter((m) => !m.frontmatter.entityRef);\n  for (let i = 0; i < noEntity.length; i++) {\n    for (let j = i + 1; j < noEntity.length; j++) {\n      const a = noEntity[i];\n      const b = noEntity[j];\n      const overlap = jaccardOverlap(\n        (a.frontmatter.tags as string[]) ?? [],\n        (b.frontmatter.tags as string[]) ?? [],\n      );\n\n      if (overlap < scanConfig.topicOverlapFloor) continue;\n\n      const pairId = computePairId(a.frontmatter.id!, b.frontmatter.id!);\n      if (seen.has(pairId)) continue;\n      seen.add(pairId);\n\n      const existing = existingPairs.get(pairId);\n      if (existing && isCoolingDown(existing, scanConfig.cooldownDays)) {\n        skipped++;\n        continue;\n      }\n\n      pairs.push({\n        idA: a.frontmatter.id!,\n        idB: b.frontmatter.id!,\n        textA: a.content,\n        textB: b.content,\n        categoryA: a.frontmatter.category as string | undefined,\n        categoryB: b.frontmatter.category as string | undefined,\n      });\n    }\n  }\n\n  // Strategy 3: Embedding cosine similarity (enforces similarityFloor config)\n  if (embeddingLookup) {\n    const memoryById = new Map(memories.map((m) => [m.frontmatter.id!, m]));\n    for (const mem of memories) {\n      const id = mem.frontmatter.id!;\n      try {\n        const hits = await embeddingLookup(mem.content, 20);\n        for (const hit of hits) {\n          if (hit.score < scanConfig.similarityFloor) continue;\n          if (hit.id === id) continue;\n          const peer = memoryById.get(hit.id);\n          if (!peer) continue;\n\n          const pairId = computePairId(id, hit.id);\n          if (seen.has(pairId)) continue;\n          seen.add(pairId);\n\n          const existing = existingPairs.get(pairId);\n          if (existing && isCoolingDown(existing, scanConfig.cooldownDays)) {\n            skipped++;\n            continue;\n          }\n\n          embeddingPairs.push({\n            idA: id,\n            idB: hit.id,\n            textA: mem.content,\n            textB: peer.content,\n            categoryA: mem.frontmatter.category as string | undefined,\n            categoryB: peer.frontmatter.category as string | undefined,\n          });\n        }\n      } catch {\n        // Embedding backend unavailable — skip, entity-ref/tag strategies already covered\n      }\n    }\n  }\n\n  // Append embedding pairs after high-precision entity/topic pairs so the\n  // downstream sort+slice(maxPairsPerRun) keeps precision-first ordering.\n  pairs.push(...embeddingPairs);\n\n  return { pairs, skipped };\n}\n\n// ── Helpers ────────────────────────────────────────────────────────────────────\n\nasync function loadEligibleMemories(storage: StorageManager, namespace?: string): Promise<MemoryFile[]> {\n  let all: MemoryFile[];\n  try {\n    all = await storage.readAllMemories();\n  } catch {\n    return [];\n  }\n\n  return all.filter((mem) => {\n    const fm = mem.frontmatter;\n    // Only active memories (rule 53: explicit ACTIVE_STATUSES set)\n    const status = (fm.status as MemoryStatus) ?? \"active\";\n    if (!ACTIVE_STATUSES.has(status)) return false;\n\n    // Only scan high-value categories\n    const category = fm.category as string | undefined;\n    if (category && !SCAN_CATEGORIES.has(category)) return false;\n\n    // Must have content\n    if (!mem.content || mem.content.trim().length === 0) return false;\n\n    // Must have an ID\n    if (!fm.id) return false;\n\n    // Namespace scoping is handled at the storage layer — memoryDir is\n    // already namespace-scoped, so readAllMemories() returns only memories\n    // within the requested namespace.\n\n    return true;\n  });\n}\n\nfunction jaccardOverlap(a: string[], b: string[]): number {\n  if (a.length === 0 && b.length === 0) return 0;\n  const setA = new Set(a.map((t) => t.toLowerCase()));\n  const setB = new Set(b.map((t) => t.toLowerCase()));\n  let intersection = 0;\n  for (const item of setA) {\n    if (setB.has(item)) intersection++;\n  }\n  const union = setA.size + setB.size - intersection;\n  return union === 0 ? 0 : intersection / union;\n}\n"],"mappings":"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","names":[]}

package/dist/cross-namespace-budget.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Per-principal cross-namespace query-budget limiter (issue #565 PR 4/5).
+ *
+ * Detects and throttles bursts of recall-type operations that a principal
+ * issues against namespaces *other than their own*. Thresholds come from the
+ * memory-extraction threat model (`docs/security/memory-extraction-threat-model.md`
+ * §6.2) and the ADAM baseline report (`docs/security/adam-baseline-2026-04.md`):
+ * a T2-class same-namespace attacker plateaus at 61 queries in the published
+ * baseline, so the default window is set well below that to force any
+ * adaptive loop to noticeably slow down.
+ *
+ * Shape:
+ * - Pure, in-process, per-principal sliding window. No persistence.
+ * - Only cross-namespace reads count: a principal hitting only their own
+ *   namespace is never throttled.
+ * - The limiter is behind the `recallCrossNamespaceBudgetEnabled` feature
+ *   flag (defaults to `false`) and is a no-op when disabled. This mirrors
+ *   the canonical "new filter/transform needs an enabled check" pattern
+ *   (see CLAUDE.md gotcha #30).
+ *
+ * The module has no side effects beyond incrementing its own counters, and
+ * it does NOT take a clock dependency — callers pass the current epoch ms
+ * (or let the default `Date.now()` do it) so tests can step time
+ * deterministically.
+ */
+interface CrossNamespaceBudgetConfig {
+    /** Feature flag. Defaults to false — a disabled limiter is always allow. */
+    enabled?: boolean;
+    /**
+     * Rolling window size in milliseconds. Counts decay out of the window
+     * as the clock advances. Default: 60_000 (1 minute).
+     */
+    windowMs?: number;
+    /**
+     * Soft cap. Once a principal has `softLimit` cross-namespace reads in the
+     * window, the limiter *records* a warning on the decision but still
+     * allows the call. Used by PR 5's anomaly detector to surface flags
+     * without blocking. Default: 10.
+     */
+    softLimit?: number;
+    /**
+     * Hard cap. Once `hardLimit` is reached, the limiter denies the call.
+     * Default: 30 — picked to be well below the T2 baseline of ~60 queries
+     * at half-plateau, so an ADAM-style adaptive loop is throttled before it
+     * meaningfully leaks.
+     */
+    hardLimit?: number;
+}
+declare const DEFAULT_CROSS_NAMESPACE_BUDGET: Required<CrossNamespaceBudgetConfig>;
+/**
+ * Why a call was denied / warned. Stable strings so callers can key log
+ * lines and metrics on them.
+ */
+type BudgetDecisionReason = "allowed-same-namespace" | "allowed-no-limit" | "allowed-under-soft" | "warn-over-soft" | "deny-over-hard";
+interface BudgetDecision {
+    allowed: boolean;
+    reason: BudgetDecisionReason;
+    /** Cross-namespace reads by this principal currently in the window. */
+    count: number;
+    /** Active config snapshot at decision time. */
+    limit: {
+        softLimit: number;
+        hardLimit: number;
+        windowMs: number;
+    };
+}
+/**
+ * In-process cross-namespace budget limiter. Instantiate once per
+ * orchestrator / access-service.
+ *
+ * Threadsafe-by-construction: Node.js is single-threaded per process for
+ * application code, and the limiter never awaits between read-modify-write
+ * operations on its internal state.
+ */
+declare class CrossNamespaceBudget {
+    private readonly config;
+    private readonly buckets;
+    constructor(config?: CrossNamespaceBudgetConfig);
+    /** Exposed for tests / audit surfaces. Never mutate the returned value. */
+    getConfig(): Required<CrossNamespaceBudgetConfig>;
+    /**
+     * Check whether `principal` is allowed to issue another cross-namespace
+     * read. Call site is expected to compare `principalNamespace` against
+     * `queryNamespace` and only pass through reads where they differ — the
+     * limiter treats every call as a cross-namespace event.
+     *
+     * @param principal Stable identifier for the calling principal (token
+     *   subject, session principal, etc.). Must be non-empty.
+     * @param now Epoch-ms clock read. Defaults to `Date.now()`; tests pass a
+     *   fixed value to step time deterministically.
+     */
+    record(principal: string, now?: number): BudgetDecision;
+    /**
+     * Read-only peek at whether a call would be allowed, WITHOUT recording a
+     * timestamp. Useful when the caller must inspect multiple namespaces before
+     * deciding to record a single event. The returned `count` reflects the
+     * current window state at call time.
+     */
+    peek(args: {
+        principal: string;
+        principalNamespace: string;
+        queryNamespace: string;
+        now?: number;
+    }): BudgetDecision;
+    /**
+     * Convenience guard that also skips the limiter when `principalNamespace`
+     * equals `queryNamespace` (same-namespace is never cross-namespace).
+     * Returns an `allowed-same-namespace` decision in that case.
+     */
+    check(args: {
+        principal: string;
+        principalNamespace: string;
+        queryNamespace: string;
+        now?: number;
+    }): BudgetDecision;
+    /**
+     * Clear all state. Intended for tests and for the orchestrator's
+     * lifecycle `before_reset` hook.
+     */
+    reset(): void;
+    /**
+     * Evict buckets whose entire timestamp list has slid out of the
+     * active window by `now`. Intended to be called periodically by a
+     * long-lived host process (e.g. from a maintenance cron) that sees
+     * many transient principals. Safe to call at any time; returns the
+     * number of buckets evicted.
+     */
+    gc(now?: number): number;
+    /** For tests: current number of live buckets. */
+    bucketCount(): number;
+}
+
+export { type BudgetDecision, type BudgetDecisionReason, CrossNamespaceBudget, type CrossNamespaceBudgetConfig, DEFAULT_CROSS_NAMESPACE_BUDGET };

package/dist/cross-namespace-budget.js

@@ -0,0 +1,9 @@
+import {
+  CrossNamespaceBudget,
+  DEFAULT_CROSS_NAMESPACE_BUDGET
+} from "./chunk-GDFS42HT.js";
+export {
+  CrossNamespaceBudget,
+  DEFAULT_CROSS_NAMESPACE_BUDGET
+};
+//# sourceMappingURL=cross-namespace-budget.js.map

package/dist/cross-namespace-budget.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/direct-answer-wiring.js

@@ -1,74 +1,9 @@
 import {
-  resolveCategory
-} from "./chunk-OIT5QGG4.js";
-import {
-  isDirectAnswerEligible
-} from "./chunk-Y4FHOFJ2.js";
-import {
-  throwIfAborted
-} from "./chunk-PVGDJXVK.js";
-import {
-  normalizeRecallTokens
-} from "./chunk-DT5TVLJE.js";
-
-// src/direct-answer-wiring.ts
-async function tryDirectAnswer(input) {
-  const { query, namespace, config, sources, queryEntityRefs, abortSignal } = input;
-  const eligibilityConfig = {
-    enabled: config.recallDirectAnswerEnabled,
-    tokenOverlapFloor: config.recallDirectAnswerTokenOverlapFloor,
-    importanceFloor: config.recallDirectAnswerImportanceFloor,
-    ambiguityMargin: config.recallDirectAnswerAmbiguityMargin,
-    eligibleTaxonomyBuckets: config.recallDirectAnswerEligibleTaxonomyBuckets
-  };
-  if (!eligibilityConfig.enabled) {
-    return isDirectAnswerEligible({
-      query,
-      candidates: [],
-      config: eligibilityConfig,
-      queryEntityRefs
-    });
-  }
-  if (normalizeRecallTokens(query).length === 0) {
-    return isDirectAnswerEligible({
-      query,
-      candidates: [],
-      config: eligibilityConfig,
-      queryEntityRefs
-    });
-  }
-  throwIfAborted(abortSignal, "direct-answer wiring aborted");
-  const memories = await sources.listCandidateMemories({ namespace, abortSignal });
-  throwIfAborted(abortSignal, "direct-answer wiring aborted");
-  const candidates = [];
-  for (const memory of memories) {
-    throwIfAborted(abortSignal, "direct-answer wiring aborted");
-    const trustZone = await sources.trustZoneFor(memory.frontmatter.id);
-    throwIfAborted(abortSignal, "direct-answer wiring aborted");
-    if (trustZone !== "trusted") continue;
-    const decision = resolveCategory(
-      memory.content,
-      memory.frontmatter.category,
-      sources.taxonomy
-    );
-    const taxonomyBucket = decision.categoryId;
-    if (!eligibilityConfig.eligibleTaxonomyBuckets.includes(taxonomyBucket)) continue;
-    const importanceScore = sources.importanceFor(memory);
-    candidates.push({
-      memory,
-      trustZone,
-      taxonomyBucket,
-      importanceScore
-    });
-  }
-  throwIfAborted(abortSignal, "direct-answer wiring aborted");
-  return isDirectAnswerEligible({
-    query,
-    candidates,
-    config: eligibilityConfig,
-    queryEntityRefs
-  });
-}
+  tryDirectAnswer
+} from "./chunk-6AUUAZEX.js";
+import "./chunk-Y4FHOFJ2.js";
+import "./chunk-PVGDJXVK.js";
+import "./chunk-DT5TVLJE.js";
 export {
   tryDirectAnswer
 };

package/dist/direct-answer-wiring.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/direct-answer-wiring.ts"],"sourcesContent":["/**\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":";;;;;;;;;;;;;;AA2FA,eAAsB,gBACpB,OAC6B;AAC7B,QAAM,EAAE,OAAO,WAAW,QAAQ,SAAS,iBAAiB,YAAY,IAAI;AAE5E,QAAM,oBAAwC;AAAA,IAC5C,SAAS,OAAO;AAAA,IAChB,mBAAmB,OAAO;AAAA,IAC1B,iBAAiB,OAAO;AAAA,IACxB,iBAAiB,OAAO;AAAA,IACxB,yBAAyB,OAAO;AAAA,EAClC;AAGA,MAAI,CAAC,kBAAkB,SAAS;AAC9B,WAAO,uBAAuB;AAAA,MAC5B;AAAA,MACA,YAAY,CAAC;AAAA,MACb,QAAQ;AAAA,MACR;AAAA,IACF,CAAC;AAAA,EACH;AAQA,MAAI,sBAAsB,KAAK,EAAE,WAAW,GAAG;AAC7C,WAAO,uBAAuB;AAAA,MAC5B;AAAA,MACA,YAAY,CAAC;AAAA,MACb,QAAQ;AAAA,MACR;AAAA,IACF,CAAC;AAAA,EACH;AAEA,iBAAe,aAAa,8BAA8B;AAC1D,QAAM,WAAW,MAAM,QAAQ,sBAAsB,EAAE,WAAW,YAAY,CAAC;AAC/E,iBAAe,aAAa,8BAA8B;AAC1D,QAAM,aAAsC,CAAC;AAE7C,aAAW,UAAU,UAAU;AAO7B,mBAAe,aAAa,8BAA8B;AAE1D,UAAM,YAAY,MAAM,QAAQ,aAAa,OAAO,YAAY,EAAE;AAClE,mBAAe,aAAa,8BAA8B;AAI1D,QAAI,cAAc,UAAW;AAE7B,UAAM,WAAW;AAAA,MACf,OAAO;AAAA,MACP,OAAO,YAAY;AAAA,MACnB,QAAQ;AAAA,IACV;AACA,UAAM,iBAAiB,SAAS;AAChC,QAAI,CAAC,kBAAkB,wBAAwB,SAAS,cAAc,EAAG;AAEzE,UAAM,kBAAkB,QAAQ,cAAc,MAAM;AAEpD,eAAW,KAAK;AAAA,MACd;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF,CAAC;AAAA,EACH;AAKA,iBAAe,aAAa,8BAA8B;AAE1D,SAAO,uBAAuB;AAAA,IAC5B;AAAA,IACA;AAAA,IACA,QAAQ;AAAA,IACR;AAAA,EACF,CAAC;AACH;","names":[]}
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/{engine-5TIQBYZR.js → engine-F3GOXGE5.js}

@@ -1,22 +1,23 @@
 import {
   CompoundingEngine,
   defaultTierMigrationCycleBudget
-} from "./chunk-DHHP2Z4X.js";
-import "./chunk-GV6NLQ4X.js";
-import "./chunk-3WHVNEN7.js";
+} from "./chunk-RGLL5SPU.js";
+import "./chunk-F5VP6YCB.js";
+import "./chunk-LTCGGW2D.js";
 import "./chunk-4KAN3GZ3.js";
-import "./chunk-6ZH4TU6I.js";
-import "./chunk-SCU65EZI.js";
-import "./chunk-BOUYNNYD.js";
 import "./chunk-6PFRXT4K.js";
 import "./chunk-TP4FZJIZ.js";
+import "./chunk-SCU65EZI.js";
+import "./chunk-BOUYNNYD.js";
 import "./chunk-DM2T26WE.js";
 import "./chunk-QSVPYQPG.js";
 import "./chunk-M62O4P4T.js";
 import "./chunk-4DJQYKMN.js";
+import "./chunk-X6GF3FX2.js";
+import "./chunk-FAAFWE4G.js";
 import "./chunk-2ODBA7MQ.js";
 export {
   CompoundingEngine,
   defaultTierMigrationCycleBudget
 };
-//# sourceMappingURL=engine-5TIQBYZR.js.map
+//# sourceMappingURL=engine-F3GOXGE5.js.map

package/dist/engine-F3GOXGE5.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/entity-retrieval.d.ts

@@ -1,6 +1,7 @@
 import { StorageManager } from './storage.js';
 import { PluginConfig, TranscriptEntry } from './types.js';
 import './page-versioning.js';
+import './consolidation-operator.js';
 import './memory-projection-store-DeSXPh1j.js';
 import 'better-sqlite3';
 

package/dist/entity-retrieval.js

@@ -3,20 +3,21 @@ import {
   entityIndexVersion,
   entityRecentTranscriptLookbackHours,
   readRecentEntityTranscriptEntries
-} from "./chunk-7WQ6SLIE.js";
+} from "./chunk-FVA6TGI3.js";
 import "./chunk-7SEAZFFB.js";
-import "./chunk-GV6NLQ4X.js";
-import "./chunk-3WHVNEN7.js";
+import "./chunk-F5VP6YCB.js";
+import "./chunk-LTCGGW2D.js";
 import "./chunk-4KAN3GZ3.js";
-import "./chunk-6ZH4TU6I.js";
-import "./chunk-SCU65EZI.js";
-import "./chunk-BOUYNNYD.js";
 import "./chunk-6PFRXT4K.js";
 import "./chunk-TP4FZJIZ.js";
+import "./chunk-SCU65EZI.js";
+import "./chunk-BOUYNNYD.js";
 import "./chunk-DM2T26WE.js";
 import "./chunk-QSVPYQPG.js";
 import "./chunk-M62O4P4T.js";
 import "./chunk-4DJQYKMN.js";
+import "./chunk-X6GF3FX2.js";
+import "./chunk-FAAFWE4G.js";
 import "./chunk-2ODBA7MQ.js";
 export {
   buildEntityRecallSection,

package/dist/explicit-capture.d.ts

@@ -1,22 +1,25 @@
-import { O as Orchestrator } from './orchestrator-DRYA6_lW.js';
+import { O as Orchestrator } from './orchestrator-CmJ-NTdJ.js';
 import { MemoryCategory, PluginConfig } from './types.js';
 import './buffer.js';
 import './storage.js';
 import './page-versioning.js';
+import './consolidation-operator.js';
 import './memory-projection-store-DeSXPh1j.js';
 import 'better-sqlite3';
-import './port-C1GZFv8h.js';
+import './port-BADbLZU5.js';
 import './transcript.js';
 import './session-integrity.js';
 import './summarizer.js';
 import './model-registry.js';
 import './local-llm.js';
+import './fallback-llm.js';
 import './relevance.js';
 import './negative.js';
 import './recall-state.js';
+import './recall-xray.js';
 import './session-observer-state.js';
 import './embedding-fallback.js';
-import './semantic-consolidation-DrvSYRdB.js';
+import './semantic-consolidation-CxJU6MJk.js';
 import './codex-materialize-CQlLTzke.js';
 import './logger.js';
 import 'zod';

package/dist/explicit-capture.js

@@ -7,8 +7,8 @@ import {
   shouldSkipImplicitExtraction,
   stripInlineExplicitCaptureNotes,
   validateExplicitCaptureInput
-} from "./chunk-QDYXG4CS.js";
-import "./chunk-QNJMBKFK.js";
+} from "./chunk-3FPTCC3Z.js";
+import "./chunk-2LGMW3DJ.js";
 import "./chunk-M62O4P4T.js";
 export {
   hasInlineExplicitCaptureMarkup,

package/dist/extraction-judge-telemetry.d.ts

@@ -0,0 +1,113 @@
+import { JudgeVerdictKind } from './extraction-judge.js';
+import './types.js';
+import './local-llm.js';
+import './model-registry.js';
+import './fallback-llm.js';
+
+/**
+ * Extraction Judge Telemetry (issue #562, PR 3).
+ *
+ * Appends one structured event per judge verdict to the observation ledger
+ * under a dedicated JSONL file. The ledger is the same directory used by
+ * the turn-count observation writer
+ * (`state/observation-ledger/rebuilt-observations.jsonl`) but judge events
+ * live in their own file so aggregation stays cheap and schemas do not
+ * collide.
+ *
+ * Emit path is best-effort and fail-open: a telemetry write must never
+ * block an extraction run.
+ */
+
+/**
+ * Observation-ledger category for judge verdict events. Callers that
+ * aggregate across event kinds can filter on this constant.
+ */
+declare const EXTRACTION_JUDGE_VERDICT_CATEGORY = "EXTRACTION_JUDGE_VERDICT";
+/**
+ * Structured event written for every judge verdict (including verdicts
+ * served from cache). The `version` field lets future readers upgrade the
+ * schema without breaking older rows.
+ */
+interface JudgeVerdictEvent {
+    version: 1;
+    category: typeof EXTRACTION_JUDGE_VERDICT_CATEGORY;
+    ts: string;
+    verdictKind: JudgeVerdictKind;
+    /** Short free-text reason from the judge / deterministic fallback. */
+    reason: string;
+    /**
+     * How many times this candidate's content hash had already been deferred
+     * before this verdict. 0 for the first defer, 1 for the second, etc.
+     * Not applicable for non-defer kinds — emitted as 0.
+     */
+    deferrals: number;
+    /**
+     * Milliseconds between batch start and batch return (the whole
+     * `judgeFactDurability` call, shared across all verdicts in a single
+     * batch).
+     */
+    elapsedMs: number;
+    /** Candidate metadata for coarse filtering. */
+    candidateCategory: string;
+    confidence?: number;
+    /** SHA-256 of the (text\0category) pair, same as the verdict-cache key. */
+    contentHash: string;
+    /** Whether the verdict came from the in-memory verdict cache. */
+    fromCache: boolean;
+    /**
+     * True when the judge forcibly converted a defer to reject because the
+     * defer cap was reached. Only set on cap-triggered rejects.
+     */
+    deferCapTriggered?: boolean;
+}
+/**
+ * Options to control emit behavior. `enabled` gates all writes; when
+ * false, `recordJudgeVerdict` is a no-op so callers can unconditionally
+ * invoke it.
+ */
+interface JudgeTelemetryOptions {
+    enabled: boolean;
+    memoryDir: string;
+}
+declare function judgeTelemetryPath(memoryDir: string): string;
+/**
+ * Append a single verdict event as a JSONL row. Fails open — if the write
+ * cannot be completed (directory missing, permissions, disk full), the
+ * error is logged at debug level and swallowed so extraction never fails
+ * because of telemetry.
+ */
+declare function recordJudgeVerdict(event: JudgeVerdictEvent, options: JudgeTelemetryOptions): Promise<void>;
+/**
+ * Aggregate statistics over the verdict ledger, optionally restricted to a
+ * time window. Returns zero-count stats when the ledger is missing or
+ * empty — callers do not need to special-case a cold install.
+ */
+interface JudgeVerdictStats {
+    total: number;
+    accept: number;
+    reject: number;
+    defer: number;
+    deferCapTriggered: number;
+    /** Mean elapsed milliseconds across all events in the window. */
+    meanElapsedMs: number;
+    /** Defer rate as `defer / total`, in `[0, 1]`. `0` when total is 0. */
+    deferRate: number;
+    /** First and last event timestamps observed in the window. */
+    firstTs?: string;
+    lastTs?: string;
+    /** Number of rows skipped because they were malformed or wrong shape. */
+    malformed: number;
+}
+/**
+ * Read and aggregate events from the verdict ledger.
+ *
+ * `sinceMs` / `untilMs` bound by `ts` parse — events with unparseable
+ * timestamps are counted toward `malformed`. The upper bound is exclusive
+ * (`ts < untilMs`), per CLAUDE.md gotcha 35.
+ */
+declare function readJudgeVerdictStats(memoryDir: string, opts?: {
+    sinceMs?: number;
+    untilMs?: number;
+}): Promise<JudgeVerdictStats>;
+
+export { EXTRACTION_JUDGE_VERDICT_CATEGORY, type JudgeTelemetryOptions, type JudgeVerdictEvent, type JudgeVerdictStats, judgeTelemetryPath, readJudgeVerdictStats, recordJudgeVerdict };

package/dist/extraction-judge-telemetry.js

@@ -0,0 +1,14 @@
+import {
+  EXTRACTION_JUDGE_VERDICT_CATEGORY,
+  judgeTelemetryPath,
+  readJudgeVerdictStats,
+  recordJudgeVerdict
+} from "./chunk-AJU4PJGY.js";
+import "./chunk-2ODBA7MQ.js";
+export {
+  EXTRACTION_JUDGE_VERDICT_CATEGORY,
+  judgeTelemetryPath,
+  readJudgeVerdictStats,
+  recordJudgeVerdict
+};
+//# sourceMappingURL=extraction-judge-telemetry.js.map

package/dist/extraction-judge-telemetry.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}