@remnic/core 1.1.12 → 1.1.13

package/dist/chunk-MC26UJIM.js

@@ -0,0 +1,118 @@
+import {
+  StorageManager
+} from "./chunk-7AAT6G4Q.js";
+import {
+  getCachedRuleMemories,
+  setCachedRuleMemories
+} from "./chunk-PFV5C235.js";
+import {
+  countRecallTokenOverlap,
+  normalizeRecallTokens
+} from "./chunk-DT5TVLJE.js";
+
+// src/semantic-rule-verifier.ts
+var DEFAULT_MIN_EFFECTIVE_CONFIDENCE = 0.45;
+function verificationConfidenceMultiplier(status) {
+  switch (status) {
+    case "verified":
+      return 1;
+    case "source-memory-not-episode":
+      return 0.45;
+    case "source-memory-archived":
+      return 0.4;
+    case "source-memory-forgotten":
+      return 0.3;
+    case "source-memory-missing":
+      return 0.35;
+    default:
+      return 0.35;
+  }
+}
+function resolveVerificationStatus(sourceMemory) {
+  if (!sourceMemory) return "source-memory-missing";
+  if (sourceMemory.frontmatter.status === "archived") {
+    return "source-memory-archived";
+  }
+  if (sourceMemory.frontmatter.status === "forgotten") return "source-memory-forgotten";
+  if (sourceMemory.frontmatter.memoryKind !== "episode") return "source-memory-not-episode";
+  return "verified";
+}
+function resolveEffectiveConfidence(rule, sourceMemory) {
+  const status = resolveVerificationStatus(sourceMemory);
+  const ruleConfidence = Number.isFinite(rule.frontmatter.confidence) ? rule.frontmatter.confidence : 0.8;
+  const sourceConfidence = Number.isFinite(sourceMemory?.frontmatter.confidence) ? sourceMemory.frontmatter.confidence : ruleConfidence;
+  const anchoredConfidence = Math.min(ruleConfidence, sourceConfidence);
+  const effectiveConfidence = Math.max(
+    0,
+    Math.min(1, anchoredConfidence * verificationConfidenceMultiplier(status))
+  );
+  return { status, effectiveConfidence };
+}
+function scoreVerifiedSemanticRuleCandidate(rule, sourceMemory, queryTokens, effectiveConfidence) {
+  const matchedFields = /* @__PURE__ */ new Set();
+  let score = 0;
+  const ruleContentMatches = countRecallTokenOverlap(queryTokens, rule.content);
+  if (ruleContentMatches > 0) {
+    score += ruleContentMatches * 5;
+    matchedFields.add("ruleContent");
+  }
+  const tagMatches = countRecallTokenOverlap(queryTokens, rule.frontmatter.tags?.join(" "));
+  if (tagMatches > 0) {
+    score += tagMatches * 2;
+    matchedFields.add("tags");
+  }
+  const sourceContentMatches = countRecallTokenOverlap(queryTokens, sourceMemory?.content);
+  if (sourceContentMatches > 0) {
+    score += sourceContentMatches * 2;
+    matchedFields.add("sourceContent");
+  }
+  if (score > 0) {
+    score += effectiveConfidence;
+  }
+  return { score, matchedFields };
+}
+async function searchVerifiedSemanticRules(options) {
+  const queryTokens = new Set(normalizeRecallTokens(options.query, ["what", "which"]));
+  if (queryTokens.size === 0 || options.maxResults <= 0) return [];
+  const storage = new StorageManager(options.memoryDir);
+  const version = storage.getMemoryStatusVersion();
+  let cachedRules = getCachedRuleMemories(storage.dir, version);
+  if (!cachedRules) {
+    const allMems = await storage.readAllMemories();
+    cachedRules = setCachedRuleMemories(storage.dir, allMems, version);
+  }
+  const { all: ruleMemories, byId: memoryById } = cachedRules;
+  const minEffectiveConfidence = options.minEffectiveConfidence ?? DEFAULT_MIN_EFFECTIVE_CONFIDENCE;
+  const candidates = [];
+  for (const memory of ruleMemories) {
+    if (memory.frontmatter.source !== "semantic-rule-promotion") continue;
+    const sourceMemoryId = memory.frontmatter.sourceMemoryId;
+    if (!sourceMemoryId) continue;
+    const sourceMemory = memoryById.get(sourceMemoryId);
+    const { status, effectiveConfidence } = resolveEffectiveConfidence(memory, sourceMemory);
+    if (effectiveConfidence < minEffectiveConfidence) continue;
+    const { score, matchedFields } = scoreVerifiedSemanticRuleCandidate(
+      memory,
+      sourceMemory,
+      queryTokens,
+      effectiveConfidence
+    );
+    if (score <= 0) continue;
+    candidates.push({
+      rule: memory,
+      score,
+      sourceMemoryId,
+      verificationStatus: status,
+      effectiveConfidence,
+      matchedFields: [...matchedFields].sort()
+    });
+  }
+  return candidates.sort(
+    (left, right) => right.score - left.score || right.effectiveConfidence - left.effectiveConfidence || right.rule.frontmatter.updated.localeCompare(left.rule.frontmatter.updated)
+  ).slice(0, options.maxResults);
+}
+
+export {
+  searchVerifiedSemanticRules
+};
+//# sourceMappingURL=chunk-MC26UJIM.js.map

package/dist/chunk-ME6ESPZU.js

@@ -0,0 +1,119 @@
+import {
+  hasCodexMaterializeSentinel,
+  materializeForNamespace
+} from "./chunk-RHY3HH7P.js";
+import {
+  resolveNamespaceChildRoot
+} from "./chunk-3UXOZBHV.js";
+import {
+  isSafeRouteNamespace
+} from "./chunk-U3PN77QT.js";
+import {
+  StorageManager
+} from "./chunk-7AAT6G4Q.js";
+import {
+  log
+} from "./chunk-2ODBA7MQ.js";
+
+// src/connectors/codex-materialize-runner.ts
+import { existsSync } from "fs";
+async function runCodexMaterialize(options) {
+  const cfg = options.config;
+  if (!cfg.codexMaterializeMemories) {
+    log.debug(`[codex-materialize] skipped \u2014 codexMaterializeMemories=false`);
+    return null;
+  }
+  if (options.reason === "session_end" && cfg.codexMaterializeOnSessionEnd === false) {
+    log.debug(
+      `[codex-materialize] skipped \u2014 session-end disabled via codexMaterializeOnSessionEnd=false`
+    );
+    return null;
+  }
+  const namespace = resolveNamespace(options.namespace, cfg);
+  const memoryDir = options.memoryDir ?? cfg.memoryDir;
+  if (!memoryDir) {
+    log.warn(`[codex-materialize] skipped \u2014 no memoryDir available`);
+    return null;
+  }
+  let memories;
+  if (options.memories) {
+    memories = options.memories;
+  } else {
+    if (!hasCodexMaterializeSentinel(options.codexHome)) {
+      return materializeForNamespace(namespace, {
+        memories: [],
+        codexHome: options.codexHome,
+        maxSummaryTokens: cfg.codexMaterializeMaxSummaryTokens,
+        rolloutRetentionDays: cfg.codexMaterializeRolloutRetentionDays,
+        rolloutSummaries: options.rolloutSummaries,
+        now: options.now
+      });
+    }
+    const nsDir = resolveNamespaceDir(memoryDir, namespace, cfg);
+    const storage = new StorageManager(nsDir);
+    memories = await storage.readAllMemories();
+  }
+  const result = materializeForNamespace(namespace, {
+    memories,
+    codexHome: options.codexHome,
+    maxSummaryTokens: cfg.codexMaterializeMaxSummaryTokens,
+    rolloutRetentionDays: cfg.codexMaterializeRolloutRetentionDays,
+    rolloutSummaries: options.rolloutSummaries,
+    now: options.now
+  });
+  if (options.reason) {
+    log.debug(
+      `[codex-materialize] ran reason=${options.reason} wrote=${result.wrote} files=${result.filesWritten.length}`
+    );
+  }
+  return result;
+}
+async function runPostConsolidationMaterialize(logPrefix, options) {
+  if (!options.config.codexMaterializeMemories) return null;
+  if (!options.config.codexMaterializeOnConsolidation) return null;
+  try {
+    return await runCodexMaterialize({
+      config: options.config,
+      namespace: options.namespace,
+      memories: options.memories,
+      memoryDir: options.memoryDir,
+      codexHome: options.codexHome,
+      rolloutSummaries: options.rolloutSummaries,
+      now: options.now,
+      reason: "consolidation"
+    });
+  } catch (error) {
+    log.warn(
+      `${logPrefix} Codex materialize post-hook failed (non-fatal): ${error instanceof Error ? error.message : String(error)}`
+    );
+    return null;
+  }
+}
+function resolveNamespace(override, cfg) {
+  const requested = (override ?? cfg.codexMaterializeNamespace ?? "auto").trim();
+  const defaultNamespace = (cfg.defaultNamespace ?? "").trim();
+  const namespace = requested.length === 0 || requested === "auto" ? defaultNamespace.length > 0 ? defaultNamespace : "default" : requested;
+  if (!isSafeRouteNamespace(namespace)) {
+    throw new Error(`invalid materialize namespace: ${namespace}`);
+  }
+  return namespace;
+}
+function resolveNamespaceDir(memoryDir, namespace, cfg) {
+  if (!cfg.namespacesEnabled) return memoryDir;
+  const defaultNamespace = (cfg.defaultNamespace ?? "").trim();
+  const ns = (namespace || defaultNamespace || "default").trim();
+  if (!isSafeRouteNamespace(ns)) {
+    throw new Error(`invalid materialize namespace: ${ns}`);
+  }
+  const namespacedRoot = resolveNamespaceChildRoot(memoryDir, ns, "materialize namespace path");
+  if (ns === defaultNamespace) {
+    return existsSync(namespacedRoot) ? namespacedRoot : memoryDir;
+  }
+  return namespacedRoot;
+}
+
+export {
+  runCodexMaterialize,
+  runPostConsolidationMaterialize
+};
+//# sourceMappingURL=chunk-ME6ESPZU.js.map

package/dist/chunk-ME6ESPZU.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/connectors/codex-materialize-runner.ts"],"sourcesContent":["/**\n * codex-materialize-runner.ts — Thin I/O bridge for the Codex materializer.\n *\n * The pure rendering logic lives in {@link ./codex-materialize.js}. This file\n * is the place callers (consolidation hooks, CLI, session-end hook) go when\n * they want the whole \"load memories from storage → render → write\" flow.\n *\n * Kept deliberately small so #378 never has to reach into orchestrator.ts /\n * importance.ts — the two files Wave 1 agents are editing concurrently.\n */\n\nimport { existsSync } from \"node:fs\";\n\nimport { log } from \"../logger.js\";\nimport { resolveNamespaceChildRoot } from \"../namespaces/path.js\";\nimport { isSafeRouteNamespace } from \"../routing/engine.js\";\nimport { StorageManager } from \"../storage.js\";\nimport type { PluginConfig, MemoryFile } from \"../types.js\";\nimport {\n  hasCodexMaterializeSentinel,\n  materializeForNamespace,\n  type MaterializeResult,\n  type RolloutSummaryInput,\n} from \"./codex-materialize.js\";\n\n/** Options accepted by the shared post-consolidation materialize helper. */\nexport interface PostConsolidationMaterializeOptions {\n  config: PluginConfig;\n  namespace?: string;\n  memories?: MemoryFile[];\n  memoryDir?: string;\n  codexHome?: string;\n  rolloutSummaries?: RolloutSummaryInput[];\n  now?: Date;\n}\n\n/** Options accepted by the runner. */\nexport interface RunMaterializeOptions {\n  /** Remnic config — we only read the `codexMaterialize*` fields. */\n  config: PluginConfig;\n  /** Namespace to materialize. Overrides the config's `codexMaterializeNamespace`. */\n  namespace?: string;\n  /** Override the memory directory (defaults to `config.memoryDir`). */\n  memoryDir?: string;\n  /** Override `<codex_home>` (useful for tests). */\n  codexHome?: string;\n  /** Optional pre-loaded memories (bypasses disk read — used in tests). */\n  memories?: MemoryFile[];\n  /** Optional rollout summaries supplied by the caller. */\n  rolloutSummaries?: RolloutSummaryInput[];\n  /** Current time injection for deterministic runs. */\n  now?: Date;\n  /** Reason string — logged for observability. */\n  reason?: \"consolidation\" | \"session_end\" | \"manual\" | \"cli\";\n}\n\n/**\n * Run the Codex materialization end-to-end. Returns `null` when the feature\n * is disabled in config or when the user hasn't opted in via the sentinel.\n * Never throws for \"expected\" skips; only throws on schema validation or I/O\n * errors that callers actually need to surface.\n */\nexport async function runCodexMaterialize(\n  options: RunMaterializeOptions,\n): Promise<MaterializeResult | null> {\n  const cfg = options.config;\n  if (!cfg.codexMaterializeMemories) {\n    log.debug(`[codex-materialize] skipped — codexMaterializeMemories=false`);\n    return null;\n  }\n\n  // Per-trigger gate: session-end runs must honor codexMaterializeOnSessionEnd.\n  // session-end.sh passes reason=\"session_end\"; when the user has turned off the\n  // session-end trigger we short-circuit here without touching disk.\n  if (options.reason === \"session_end\" && cfg.codexMaterializeOnSessionEnd === false) {\n    log.debug(\n      `[codex-materialize] skipped — session-end disabled via codexMaterializeOnSessionEnd=false`,\n    );\n    return null;\n  }\n\n  const namespace = resolveNamespace(options.namespace, cfg);\n  const memoryDir = options.memoryDir ?? cfg.memoryDir;\n  if (!memoryDir) {\n    log.warn(`[codex-materialize] skipped — no memoryDir available`);\n    return null;\n  }\n\n  let memories: MemoryFile[];\n  if (options.memories) {\n    memories = options.memories;\n  } else {\n    if (!hasCodexMaterializeSentinel(options.codexHome)) {\n      return materializeForNamespace(namespace, {\n        memories: [],\n        codexHome: options.codexHome,\n        maxSummaryTokens: cfg.codexMaterializeMaxSummaryTokens,\n        rolloutRetentionDays: cfg.codexMaterializeRolloutRetentionDays,\n        rolloutSummaries: options.rolloutSummaries,\n        now: options.now,\n      });\n    }\n    const nsDir = resolveNamespaceDir(memoryDir, namespace, cfg);\n    const storage = new StorageManager(nsDir);\n    memories = await storage.readAllMemories();\n  }\n\n  // Intentionally NOT catching here: per the JSDoc contract above,\n  // schema-validation and I/O errors from `materializeForNamespace` must\n  // surface to callers so they can exit non-zero (CLI) or log + recover\n  // (consolidation post-hook, which has its own narrower try/catch).\n  // Catching everything would make a broken MEMORY.md render look like a\n  // successful skip, and invisible failures are strictly worse than loud\n  // ones for a feature that writes to `~/.codex/memories`.\n  const result = materializeForNamespace(namespace, {\n    memories,\n    codexHome: options.codexHome,\n    maxSummaryTokens: cfg.codexMaterializeMaxSummaryTokens,\n    rolloutRetentionDays: cfg.codexMaterializeRolloutRetentionDays,\n    rolloutSummaries: options.rolloutSummaries,\n    now: options.now,\n  });\n  if (options.reason) {\n    log.debug(\n      `[codex-materialize] ran reason=${options.reason} wrote=${result.wrote} files=${result.filesWritten.length}`,\n    );\n  }\n  return result;\n}\n\n/**\n * Shared helper for post-consolidation materialize hooks.\n *\n * `materializeAfterSemanticConsolidation` and `materializeAfterCausalConsolidation`\n * used to be two nearly-identical copies of this logic; keeping the actual\n * body here means any future guard/logging change happens in one place.\n *\n * The only per-caller knob is `logPrefix`, which is used to tag the\n * non-fatal warning emitted when the materializer throws.\n */\nexport async function runPostConsolidationMaterialize(\n  logPrefix: string,\n  options: PostConsolidationMaterializeOptions,\n): Promise<MaterializeResult | null> {\n  if (!options.config.codexMaterializeMemories) return null;\n  if (!options.config.codexMaterializeOnConsolidation) return null;\n  try {\n    return await runCodexMaterialize({\n      config: options.config,\n      namespace: options.namespace,\n      memories: options.memories,\n      memoryDir: options.memoryDir,\n      codexHome: options.codexHome,\n      rolloutSummaries: options.rolloutSummaries,\n      now: options.now,\n      reason: \"consolidation\",\n    });\n  } catch (error) {\n    log.warn(\n      `${logPrefix} Codex materialize post-hook failed (non-fatal): ${\n        error instanceof Error ? error.message : String(error)\n      }`,\n    );\n    return null;\n  }\n}\n\nfunction resolveNamespace(override: string | undefined, cfg: PluginConfig): string {\n  const requested = (override ?? cfg.codexMaterializeNamespace ?? \"auto\").trim();\n  const defaultNamespace = (cfg.defaultNamespace ?? \"\").trim();\n  const namespace =\n    requested.length === 0 || requested === \"auto\"\n      ? (defaultNamespace.length > 0 ? defaultNamespace : \"default\")\n      : requested;\n  if (!isSafeRouteNamespace(namespace)) {\n    throw new Error(`invalid materialize namespace: ${namespace}`);\n  }\n  return namespace;\n}\n\n/**\n * Resolve the on-disk storage root for a namespace, matching\n * `NamespaceStorageRouter` in `packages/remnic-core/src/namespaces/storage.ts`.\n *\n * Contract:\n *  - When namespaces are disabled, every namespace maps to `memoryDir` itself.\n *  - When namespaces are enabled, non-default namespaces always live under\n *    `memoryDir/namespaces/<namespace>`.\n *  - The default namespace prefers `memoryDir/namespaces/<defaultNamespace>`\n *    when that directory already exists (migrated install); otherwise it\n *    falls back to the legacy `memoryDir` root so materialization does not\n *    silently switch directories out from under an existing install.\n */\nfunction resolveNamespaceDir(\n  memoryDir: string,\n  namespace: string,\n  cfg: PluginConfig,\n): string {\n  if (!cfg.namespacesEnabled) return memoryDir;\n\n  const defaultNamespace = (cfg.defaultNamespace ?? \"\").trim();\n  const ns = (namespace || defaultNamespace || \"default\").trim();\n  if (!isSafeRouteNamespace(ns)) {\n    throw new Error(`invalid materialize namespace: ${ns}`);\n  }\n  const namespacedRoot = resolveNamespaceChildRoot(memoryDir, ns, \"materialize namespace path\");\n\n  if (ns === defaultNamespace) {\n    return existsSync(namespacedRoot) ? namespacedRoot : memoryDir;\n  }\n  return namespacedRoot;\n}\n"],"mappings":"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","names":[]}

package/dist/chunk-MGKYQQYF.js

@@ -0,0 +1,272 @@
+import {
+  isRecallDisclosure
+} from "./chunk-Q7P4WJDP.js";
+import {
+  normalizeRetrievedMemoryProvenance
+} from "./chunk-AC5LO7IU.js";
+
+// src/recall-xray.ts
+import { randomUUID } from "crypto";
+function estimateRecallTokens(text) {
+  if (typeof text !== "string" || text.length === 0) return 0;
+  return Math.ceil(text.length / 4);
+}
+var RECALL_XRAY_SERVED_BY_VALUES = [
+  "direct-answer",
+  "hybrid",
+  "graph",
+  "recent-scan",
+  "procedural",
+  "review-context",
+  "lcm-file-parts",
+  "lcm-tool-parts"
+];
+function isRecallXrayServedBy(value) {
+  return typeof value === "string" && RECALL_XRAY_SERVED_BY_VALUES.includes(value);
+}
+function buildXraySnapshot(input) {
+  const now = input.now ?? Date.now;
+  const snapshotIdGenerator = input.snapshotIdGenerator ?? randomUUID;
+  const results = Array.isArray(input.results) ? input.results.map(cloneResult) : [];
+  const filters = Array.isArray(input.filters) ? input.filters.map(cloneFilter) : [];
+  const budgetChars = nonNegativeInt(input.budget?.chars);
+  const budgetUsed = nonNegativeInt(input.budget?.used);
+  const tierExplain = input.tierExplain && typeof input.tierExplain === "object" ? cloneTierExplain(input.tierExplain) : null;
+  let peerProfileInjection;
+  if (input.peerProfileInjection && typeof input.peerProfileInjection === "object") {
+    const raw = input.peerProfileInjection;
+    const peerId = nonEmptyString(raw.peerId);
+    if (peerId !== void 0) {
+      peerProfileInjection = {
+        peerId,
+        fieldsInjected: nonNegativeInt(raw.fieldsInjected)
+      };
+    }
+  } else if (input.peerProfileInjection === null) {
+    peerProfileInjection = null;
+  }
+  const out = {
+    schemaVersion: "1",
+    query: typeof input.query === "string" ? input.query : "",
+    snapshotId: snapshotIdGenerator(),
+    capturedAt: now(),
+    tierExplain,
+    results,
+    filters,
+    budget: { chars: budgetChars, used: budgetUsed },
+    sessionKey: nonEmptyString(input.sessionKey),
+    namespace: nonEmptyString(input.namespace),
+    traceId: nonEmptyString(input.traceId)
+  };
+  if (peerProfileInjection !== void 0) {
+    out.peerProfileInjection = peerProfileInjection;
+  }
+  return out;
+}
+var RecallXrayBuilder = class {
+  query;
+  sessionKey;
+  namespace;
+  traceId;
+  tierExplain = null;
+  results = [];
+  filters = [];
+  budgetChars = 0;
+  budgetUsed = 0;
+  peerProfileInjection;
+  constructor(opts) {
+    this.query = typeof opts.query === "string" ? opts.query : "";
+    this.sessionKey = nonEmptyString(opts.sessionKey);
+    this.namespace = nonEmptyString(opts.namespace);
+    this.traceId = nonEmptyString(opts.traceId);
+  }
+  setNamespace(namespace) {
+    this.namespace = nonEmptyString(namespace);
+  }
+  setTraceId(traceId) {
+    this.traceId = nonEmptyString(traceId);
+  }
+  setTierExplain(tierExplain) {
+    this.tierExplain = tierExplain && typeof tierExplain === "object" ? cloneTierExplain(tierExplain) : null;
+  }
+  setBudget(budget) {
+    this.budgetChars = nonNegativeInt(budget.chars);
+    this.budgetUsed = nonNegativeInt(budget.used);
+  }
+  /**
+   * Record peer-profile injection metadata for this recall snapshot
+   * (issue #679 completion). Pass `null` to explicitly record that no
+   * injection happened (feature enabled but no peer / no profile fields).
+   */
+  setPeerProfileInjection(injection) {
+    this.peerProfileInjection = injection;
+  }
+  recordResult(result) {
+    this.results.push(cloneResult(result));
+  }
+  recordFilter(filter) {
+    this.filters.push(cloneFilter(filter));
+  }
+  build(opts = {}) {
+    return buildXraySnapshot({
+      query: this.query,
+      tierExplain: this.tierExplain,
+      results: this.results,
+      filters: this.filters,
+      budget: { chars: this.budgetChars, used: this.budgetUsed },
+      sessionKey: this.sessionKey,
+      namespace: this.namespace,
+      traceId: this.traceId,
+      peerProfileInjection: this.peerProfileInjection,
+      now: opts.now,
+      snapshotIdGenerator: opts.snapshotIdGenerator
+    });
+  }
+};
+function cloneResult(result) {
+  if (!result || typeof result !== "object") {
+    throw new TypeError("RecallXrayResult must be an object");
+  }
+  if (!isRecallXrayServedBy(result.servedBy)) {
+    throw new TypeError(
+      `RecallXrayResult.servedBy must be one of ${RECALL_XRAY_SERVED_BY_VALUES.join(
+        ", "
+      )}; got ${JSON.stringify(result.servedBy)}`
+    );
+  }
+  const memoryId = typeof result.memoryId === "string" ? result.memoryId : "";
+  const path = typeof result.path === "string" ? result.path : "";
+  const admittedBy = Array.isArray(result.admittedBy) ? result.admittedBy.filter((x) => typeof x === "string") : [];
+  const graphPath = Array.isArray(result.graphPath) ? result.graphPath.filter((x) => typeof x === "string") : void 0;
+  let graphEdgeConfidences;
+  if (Array.isArray(result.graphEdgeConfidences) && graphPath && graphPath.length > 1) {
+    const expected = graphPath.length - 1;
+    const raw = result.graphEdgeConfidences;
+    if (raw.length === expected) {
+      const cleaned = [];
+      let allFinite = true;
+      for (const value of raw) {
+        if (typeof value !== "number" || !Number.isFinite(value)) {
+          allFinite = false;
+          break;
+        }
+        cleaned.push(Math.min(1, Math.max(0, value)));
+      }
+      if (allFinite) {
+        graphEdgeConfidences = cleaned;
+      }
+    }
+  }
+  const auditEntryId = nonEmptyString(result.auditEntryId);
+  const rejectedBy = nonEmptyString(result.rejectedBy);
+  const scoreDecomposition = cloneScoreDecomposition(result.scoreDecomposition);
+  const out = {
+    memoryId,
+    path,
+    servedBy: result.servedBy,
+    scoreDecomposition,
+    admittedBy
+  };
+  if (graphPath !== void 0) out.graphPath = graphPath;
+  if (graphEdgeConfidences !== void 0) {
+    out.graphEdgeConfidences = graphEdgeConfidences;
+  }
+  if (auditEntryId !== void 0) out.auditEntryId = auditEntryId;
+  if (rejectedBy !== void 0) out.rejectedBy = rejectedBy;
+  if (isRecallDisclosure(result.disclosure)) {
+    out.disclosure = result.disclosure;
+  }
+  if (typeof result.estimatedTokens === "number" && Number.isFinite(result.estimatedTokens) && result.estimatedTokens >= 0) {
+    out.estimatedTokens = Math.floor(result.estimatedTokens);
+  }
+  if (Array.isArray(result.tags)) {
+    const cleanedTags = result.tags.filter((t) => typeof t === "string").map((t) => t.trim()).filter((t) => t.length > 0);
+    if (cleanedTags.length > 0) {
+      out.tags = cleanedTags;
+    }
+  }
+  const provenance = normalizeRetrievedMemoryProvenance(result.provenance);
+  if (provenance !== void 0) {
+    out.provenance = provenance;
+  }
+  return out;
+}
+function summarizeDisclosureTokens(results) {
+  const summary = {
+    chunk: { count: 0, estimatedTokens: 0 },
+    section: { count: 0, estimatedTokens: 0 },
+    raw: { count: 0, estimatedTokens: 0 },
+    unspecified: { count: 0, estimatedTokens: 0 }
+  };
+  for (const result of results) {
+    const tokens = typeof result.estimatedTokens === "number" && Number.isFinite(result.estimatedTokens) && result.estimatedTokens >= 0 ? Math.floor(result.estimatedTokens) : 0;
+    const bucket = isRecallDisclosure(result.disclosure) ? result.disclosure : "unspecified";
+    summary[bucket].count += 1;
+    summary[bucket].estimatedTokens += tokens;
+  }
+  return summary;
+}
+function cloneFilter(filter) {
+  if (!filter || typeof filter !== "object") {
+    throw new TypeError("RecallFilterTrace must be an object");
+  }
+  const out = {
+    name: typeof filter.name === "string" ? filter.name : "",
+    considered: nonNegativeInt(filter.considered),
+    admitted: nonNegativeInt(filter.admitted)
+  };
+  const reason = nonEmptyString(filter.reason);
+  if (reason !== void 0) out.reason = reason;
+  return out;
+}
+function cloneScoreDecomposition(value) {
+  if (!value || typeof value !== "object") {
+    return { final: 0 };
+  }
+  const out = {
+    final: finiteNumber(value.final) ?? 0
+  };
+  const vector = finiteNumber(value.vector);
+  if (vector !== void 0) out.vector = vector;
+  const bm25 = finiteNumber(value.bm25);
+  if (bm25 !== void 0) out.bm25 = bm25;
+  const importance = finiteNumber(value.importance);
+  if (importance !== void 0) out.importance = importance;
+  const mmrPenalty = finiteNumber(value.mmrPenalty);
+  if (mmrPenalty !== void 0) out.mmrPenalty = mmrPenalty;
+  const tierPrior = finiteNumber(value.tierPrior);
+  if (tierPrior !== void 0) out.tierPrior = tierPrior;
+  const reinforcementBoost = finiteNumber(value.reinforcementBoost);
+  if (reinforcementBoost !== void 0 && reinforcementBoost > 0) {
+    out.reinforcementBoost = reinforcementBoost;
+  }
+  return out;
+}
+function cloneTierExplain(tierExplain) {
+  return structuredClone(tierExplain);
+}
+function nonNegativeInt(value) {
+  if (typeof value !== "number" || !Number.isFinite(value)) return 0;
+  if (value <= 0) return 0;
+  return Math.floor(value);
+}
+function finiteNumber(value) {
+  if (typeof value !== "number" || !Number.isFinite(value)) return void 0;
+  return value;
+}
+function nonEmptyString(value) {
+  if (typeof value !== "string") return void 0;
+  const trimmed = value.trim();
+  if (trimmed.length === 0) return void 0;
+  return trimmed;
+}
+
+export {
+  estimateRecallTokens,
+  RECALL_XRAY_SERVED_BY_VALUES,
+  isRecallXrayServedBy,
+  buildXraySnapshot,
+  RecallXrayBuilder,
+  summarizeDisclosureTokens
+};
+//# sourceMappingURL=chunk-MGKYQQYF.js.map

package/dist/chunk-MJFNCJXV.js

@@ -0,0 +1,66 @@
+// src/search/document-scanner.ts
+import path from "path";
+import { readdir, readFile } from "fs/promises";
+function parseFrontmatter(raw) {
+  const normalized = raw.replace(/\r\n/g, "\n");
+  const match = normalized.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+  if (!match) return null;
+  const fmBlock = match[1];
+  const body = (match[2] ?? "").trim();
+  const data = {};
+  for (const line of fmBlock.split("\n")) {
+    const colonIdx = line.indexOf(":");
+    if (colonIdx === -1) continue;
+    const key = line.slice(0, colonIdx).trim();
+    const value = line.slice(colonIdx + 1).trim();
+    data[key] = value;
+  }
+  return { data, body };
+}
+async function scanDir(dir) {
+  const docs = [];
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        const sub = await scanDir(fullPath);
+        docs.push(...sub);
+      } else if (entry.name.endsWith(".md")) {
+        try {
+          const raw = await readFile(fullPath, "utf-8");
+          const parsed = parseFrontmatter(raw);
+          const body = parsed ? parsed.body : raw.trim();
+          const docid = parsed?.data.id || path.basename(entry.name, ".md");
+          docs.push({
+            docid,
+            path: fullPath,
+            content: body,
+            snippet: body.slice(0, 200)
+          });
+        } catch {
+        }
+      }
+    }
+  } catch {
+  }
+  return docs;
+}
+async function scanMemoryDir(memoryDir) {
+  const factsDir = path.join(memoryDir, "facts");
+  const correctionsDir = path.join(memoryDir, "corrections");
+  const proceduresDir = path.join(memoryDir, "procedures");
+  const reasoningTracesDir = path.join(memoryDir, "reasoning-traces");
+  const [facts, corrections, procedures, reasoningTraces] = await Promise.all([
+    scanDir(factsDir),
+    scanDir(correctionsDir),
+    scanDir(proceduresDir),
+    scanDir(reasoningTracesDir)
+  ]);
+  return [...facts, ...corrections, ...procedures, ...reasoningTraces];
+}
+
+export {
+  scanMemoryDir
+};
+//# sourceMappingURL=chunk-MJFNCJXV.js.map

package/dist/chunk-MJFNCJXV.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/search/document-scanner.ts"],"sourcesContent":["import path from \"node:path\";\nimport { readdir, readFile } from \"node:fs/promises\";\n\nexport interface IndexableDocument {\n  /** Memory ID from frontmatter or filename stem */\n  docid: string;\n  /** Absolute file path */\n  path: string;\n  /** Markdown body (no YAML frontmatter) */\n  content: string;\n  /** First ~200 chars for display */\n  snippet: string;\n}\n\n/**\n * Parse YAML frontmatter from a markdown string.\n * Returns the frontmatter key-value pairs and body, or null if no frontmatter block.\n */\nfunction parseFrontmatter(raw: string): { data: Record<string, string>; body: string } | null {\n  // Support both LF and CRLF line endings\n  const normalized = raw.replace(/\\r\\n/g, \"\\n\");\n  const match = normalized.match(/^---\\n([\\s\\S]*?)\\n---\\n?([\\s\\S]*)$/);\n  if (!match) return null;\n\n  const fmBlock = match[1];\n  const body = (match[2] ?? \"\").trim();\n  const data: Record<string, string> = {};\n\n  for (const line of fmBlock.split(\"\\n\")) {\n    const colonIdx = line.indexOf(\":\");\n    if (colonIdx === -1) continue;\n    const key = line.slice(0, colonIdx).trim();\n    const value = line.slice(colonIdx + 1).trim();\n    data[key] = value;\n  }\n\n  return { data, body };\n}\n\n/**\n * Recursively scan a directory for `.md` files and return IndexableDocuments.\n */\nasync function scanDir(dir: string): Promise<IndexableDocument[]> {\n  const docs: IndexableDocument[] = [];\n  try {\n    const entries = await readdir(dir, { withFileTypes: true });\n    for (const entry of entries) {\n      const fullPath = path.join(dir, entry.name);\n      if (entry.isDirectory()) {\n        const sub = await scanDir(fullPath);\n        docs.push(...sub);\n      } else if (entry.name.endsWith(\".md\")) {\n        try {\n          const raw = await readFile(fullPath, \"utf-8\");\n          const parsed = parseFrontmatter(raw);\n          const body = parsed ? parsed.body : raw.trim();\n          const docid = parsed?.data.id || path.basename(entry.name, \".md\");\n          docs.push({\n            docid,\n            path: fullPath,\n            content: body,\n            snippet: body.slice(0, 200),\n          });\n        } catch {\n          // Skip unreadable files\n        }\n      }\n    }\n  } catch {\n    // Directory doesn't exist yet — not an error\n  }\n  return docs;\n}\n\n/**\n * Scan `facts/`, `corrections/`, `procedures/`, and `reasoning-traces/`\n * subdirs of memoryDir for indexable markdown documents.\n *\n * Note: reasoning-traces live under their own subtree (issue #564 PR 3).\n * Non-QMD backends (Orama / Meilisearch / LanceDB) build their index\n * through this helper, so any new category subtree must be listed here\n * or those backends silently stop seeing the new memories.\n */\nexport async function scanMemoryDir(memoryDir: string): Promise<IndexableDocument[]> {\n  const factsDir = path.join(memoryDir, \"facts\");\n  const correctionsDir = path.join(memoryDir, \"corrections\");\n  const proceduresDir = path.join(memoryDir, \"procedures\");\n  const reasoningTracesDir = path.join(memoryDir, \"reasoning-traces\");\n  const [facts, corrections, procedures, reasoningTraces] = await Promise.all([\n    scanDir(factsDir),\n    scanDir(correctionsDir),\n    scanDir(proceduresDir),\n    scanDir(reasoningTracesDir),\n  ]);\n  return [...facts, ...corrections, ...procedures, ...reasoningTraces];\n}\n"],"mappings":";AAAA,OAAO,UAAU;AACjB,SAAS,SAAS,gBAAgB;AAiBlC,SAAS,iBAAiB,KAAoE;AAE5F,QAAM,aAAa,IAAI,QAAQ,SAAS,IAAI;AAC5C,QAAM,QAAQ,WAAW,MAAM,oCAAoC;AACnE,MAAI,CAAC,MAAO,QAAO;AAEnB,QAAM,UAAU,MAAM,CAAC;AACvB,QAAM,QAAQ,MAAM,CAAC,KAAK,IAAI,KAAK;AACnC,QAAM,OAA+B,CAAC;AAEtC,aAAW,QAAQ,QAAQ,MAAM,IAAI,GAAG;AACtC,UAAM,WAAW,KAAK,QAAQ,GAAG;AACjC,QAAI,aAAa,GAAI;AACrB,UAAM,MAAM,KAAK,MAAM,GAAG,QAAQ,EAAE,KAAK;AACzC,UAAM,QAAQ,KAAK,MAAM,WAAW,CAAC,EAAE,KAAK;AAC5C,SAAK,GAAG,IAAI;AAAA,EACd;AAEA,SAAO,EAAE,MAAM,KAAK;AACtB;AAKA,eAAe,QAAQ,KAA2C;AAChE,QAAM,OAA4B,CAAC;AACnC,MAAI;AACF,UAAM,UAAU,MAAM,QAAQ,KAAK,EAAE,eAAe,KAAK,CAAC;AAC1D,eAAW,SAAS,SAAS;AAC3B,YAAM,WAAW,KAAK,KAAK,KAAK,MAAM,IAAI;AAC1C,UAAI,MAAM,YAAY,GAAG;AACvB,cAAM,MAAM,MAAM,QAAQ,QAAQ;AAClC,aAAK,KAAK,GAAG,GAAG;AAAA,MAClB,WAAW,MAAM,KAAK,SAAS,KAAK,GAAG;AACrC,YAAI;AACF,gBAAM,MAAM,MAAM,SAAS,UAAU,OAAO;AAC5C,gBAAM,SAAS,iBAAiB,GAAG;AACnC,gBAAM,OAAO,SAAS,OAAO,OAAO,IAAI,KAAK;AAC7C,gBAAM,QAAQ,QAAQ,KAAK,MAAM,KAAK,SAAS,MAAM,MAAM,KAAK;AAChE,eAAK,KAAK;AAAA,YACR;AAAA,YACA,MAAM;AAAA,YACN,SAAS;AAAA,YACT,SAAS,KAAK,MAAM,GAAG,GAAG;AAAA,UAC5B,CAAC;AAAA,QACH,QAAQ;AAAA,QAER;AAAA,MACF;AAAA,IACF;AAAA,EACF,QAAQ;AAAA,EAER;AACA,SAAO;AACT;AAWA,eAAsB,cAAc,WAAiD;AACnF,QAAM,WAAW,KAAK,KAAK,WAAW,OAAO;AAC7C,QAAM,iBAAiB,KAAK,KAAK,WAAW,aAAa;AACzD,QAAM,gBAAgB,KAAK,KAAK,WAAW,YAAY;AACvD,QAAM,qBAAqB,KAAK,KAAK,WAAW,kBAAkB;AAClE,QAAM,CAAC,OAAO,aAAa,YAAY,eAAe,IAAI,MAAM,QAAQ,IAAI;AAAA,IAC1E,QAAQ,QAAQ;AAAA,IAChB,QAAQ,cAAc;AAAA,IACtB,QAAQ,aAAa;AAAA,IACrB,QAAQ,kBAAkB;AAAA,EAC5B,CAAC;AACD,SAAO,CAAC,GAAG,OAAO,GAAG,aAAa,GAAG,YAAY,GAAG,eAAe;AACrE;","names":[]}