@remnic/core 1.1.2 → 1.1.3

package/dist/{chunk-C2EFFULQ.js → chunk-RK2Y4XOM.js}

@@ -1,6 +1,15 @@
+import {
+  readEdgeConfidence
+} from "./chunk-2LSZVONP.js";
+import {
+  emitGraphEvent
+} from "./chunk-WIICJPET.js";
+
 // src/graph.ts
 import { mkdir, appendFile, readFile } from "fs/promises";
 import * as path from "path";
+var DEFAULT_GRAPH_TRAVERSAL_CONFIDENCE_FLOOR = 0.2;
+var DEFAULT_GRAPH_TRAVERSAL_PAGERANK_ITERATIONS = 8;
 var CAUSAL_PHRASES = [
   "as a result",
   "led to",
@@ -18,29 +27,71 @@ function graphFilePath(memoryDir, type) {
 async function ensureGraphsDir(memoryDir) {
   await mkdir(graphsDir(memoryDir), { recursive: true });
 }
+var graphWriteLocks = /* @__PURE__ */ new Map();
+function withGraphWriteLock(filePath, fn) {
+  const prev = graphWriteLocks.get(filePath) ?? Promise.resolve();
+  const next = prev.then(fn, fn);
+  graphWriteLocks.set(
+    filePath,
+    next.then(
+      () => void 0,
+      () => void 0
+    )
+  );
+  return next;
+}
 async function appendEdge(memoryDir, edge) {
   await ensureGraphsDir(memoryDir);
+  const filePath = graphFilePath(memoryDir, edge.type);
   const line = JSON.stringify(edge) + "\n";
-  await appendFile(graphFilePath(memoryDir, edge.type), line, "utf8");
+  await withGraphWriteLock(filePath, async () => {
+    await appendFile(filePath, line, "utf8");
+  });
+  emitGraphEvent(memoryDir, "edge-added", {
+    source: edge.from,
+    target: edge.to,
+    kind: edge.type,
+    weight: edge.weight,
+    label: edge.label,
+    confidence: typeof edge.confidence === "number" ? edge.confidence : 1
+  });
+}
+function isNodeError(err) {
+  return typeof err === "object" && err !== null && "code" in err;
+}
+function parseEdgesJsonl(raw) {
+  const edges = [];
+  for (const line of raw.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      edges.push(JSON.parse(trimmed));
+    } catch {
+    }
+  }
+  return edges;
 }
 async function readEdges(memoryDir, type) {
   const filePath = graphFilePath(memoryDir, type);
   try {
     const raw = await readFile(filePath, "utf8");
-    const edges = [];
-    for (const line of raw.split("\n")) {
-      const trimmed = line.trim();
-      if (!trimmed) continue;
-      try {
-        edges.push(JSON.parse(trimmed));
-      } catch {
-      }
-    }
-    return edges;
+    return parseEdgesJsonl(raw);
   } catch {
     return [];
   }
 }
+async function readEdgesStrict(memoryDir, type) {
+  const filePath = graphFilePath(memoryDir, type);
+  try {
+    const raw = await readFile(filePath, "utf8");
+    return parseEdgesJsonl(raw);
+  } catch (err) {
+    if (isNodeError(err) && err.code === "ENOENT") {
+      return [];
+    }
+    throw err;
+  }
+}
 async function readAllEdges(memoryDir, config) {
   const parts = await Promise.all([
     config.entityGraphEnabled ? readEdges(memoryDir, "entity") : Promise.resolve([]),
@@ -238,21 +289,38 @@ var GraphIndex = class _GraphIndex {
    * Spreading activation BFS (SYNAPSE-inspired).
    *
    * Starting from `seeds`, traverse the combined graph for up to `maxSteps` hops.
-   * Each candidate gets an activation score = edge.weight × decay^hop.
-   * Returns top-N candidate paths sorted by descending activation score.
+   * Each candidate gets an activation score = edge.weight × edgeConfidence × decay^hop.
+   *
+   * Issue #681 PR 3/3 — confidence-aware traversal:
+   *   - Each edge's `weight` is multiplied by its `confidence` (legacy edges
+   *     missing `confidence` are treated as 1.0, preserving prior behavior).
+   *   - Edges with `confidence < graphTraversalConfidenceFloor` are pruned and
+   *     contribute neither activation nor downstream neighbors.
+   *   - When `graphTraversalPageRankIterations > 0`, an additional PageRank-
+   *     style refinement pass redistributes activation along confidence-weighted
+   *     edges, sharpening the ranking among multi-hop candidates.
+   *   - Per-result provenance includes the highest-confidence edge that landed
+   *     on each candidate, so the X-ray surface can attribute pruning and
+   *     ranking decisions back to specific edges.
    *
-   * @param seeds   - initial memory paths to expand from (e.g. QMD top results)
+   * @param seeds    - initial memory paths to expand from (e.g. QMD top results)
    * @param maxSteps - max BFS hops (from config: maxGraphTraversalSteps)
-   * @returns Array of {path, score} sorted descending, not including seed paths
+   * @returns Array of {path, score, edgeConfidence, ...} sorted descending, not including seed paths
    */
-  async spreadingActivation(seeds, maxSteps) {
+  async spreadingActivation(seeds, maxSteps, opts) {
     if (!this.cfg.multiGraphMemoryEnabled) return [];
     const steps = maxSteps ?? this.cfg.maxGraphTraversalSteps;
     const decay = this.cfg.graphActivationDecay;
+    const floor = opts?.includeLowConfidence === true ? 0 : clampConfidenceFloor(this.cfg.graphTraversalConfidenceFloor);
+    const iterations = clampPageRankIterations(
+      this.cfg.graphTraversalPageRankIterations
+    );
     try {
       const allEdges = await this.loadEdgesCached();
       const adj = /* @__PURE__ */ new Map();
       for (const edge of allEdges) {
+        const conf = readEdgeConfidence(edge);
+        if (conf < floor) continue;
         if (!adj.has(edge.from)) adj.set(edge.from, []);
         adj.get(edge.from).push(edge);
         if (edge.type !== "causal") {
@@ -271,7 +339,9 @@ var GraphIndex = class _GraphIndex {
         const edges = adj.get(node) ?? [];
         for (const edge of edges) {
           const neighbor = edge.to === node ? edge.from : edge.to;
-          const score = edge.weight * Math.pow(decay, hop + 1);
+          const conf = readEdgeConfidence(edge);
+          if (conf < floor) continue;
+          const score = edge.weight * conf * Math.pow(decay, hop + 1);
           if (!seedSet.has(neighbor)) {
             const existing = scores.get(neighbor) ?? 0;
             scores.set(neighbor, existing + score);
@@ -281,7 +351,8 @@ var GraphIndex = class _GraphIndex {
                 seed: sourceSeed,
                 hopDepth: hop + 1,
                 decayedWeight: score,
-                graphType: edge.type
+                graphType: edge.type,
+                edgeConfidence: conf
               });
             }
           }
@@ -291,6 +362,13 @@ var GraphIndex = class _GraphIndex {
           }
         }
       }
+      if (iterations > 0 && scores.size > 1) {
+        applyPageRankRefinement(scores, adj, {
+          iterations,
+          floor,
+          damping: 0.85
+        });
+      }
       if (this.cfg.graphLateralInhibitionEnabled && scores.size > 1) {
         const inhibited = applyLateralInhibition(scores, {
           beta: this.cfg.graphLateralInhibitionBeta,
@@ -306,7 +384,8 @@ var GraphIndex = class _GraphIndex {
         seed: provenance.get(p)?.seed ?? "",
         hopDepth: provenance.get(p)?.hopDepth ?? 0,
         decayedWeight: provenance.get(p)?.decayedWeight ?? 0,
-        graphType: provenance.get(p)?.graphType ?? "entity"
+        graphType: provenance.get(p)?.graphType ?? "entity",
+        edgeConfidence: provenance.get(p)?.edgeConfidence ?? 1
       })).sort((a, b) => b.score - a.score);
     } catch (err) {
       const { log } = await import("./logger.js");
@@ -315,6 +394,63 @@ var GraphIndex = class _GraphIndex {
     }
   }
 };
+function clampConfidenceFloor(raw) {
+  if (typeof raw !== "number" || !Number.isFinite(raw)) {
+    return DEFAULT_GRAPH_TRAVERSAL_CONFIDENCE_FLOOR;
+  }
+  if (raw < 0) return 0;
+  if (raw > 1) return 1;
+  return raw;
+}
+function clampPageRankIterations(raw) {
+  if (typeof raw !== "number" || !Number.isFinite(raw)) return 0;
+  if (raw <= 0) return 0;
+  return Math.floor(raw);
+}
+function applyPageRankRefinement(scores, adj, opts) {
+  const { iterations, floor, damping } = opts;
+  if (iterations <= 0 || scores.size === 0) return;
+  const safeDamping = Math.min(1, Math.max(0, damping));
+  const eligible = (edge, fromNode) => {
+    if (readEdgeConfidence(edge) < floor) return false;
+    const neighbor = edge.to === fromNode ? edge.from : edge.to;
+    return scores.has(neighbor);
+  };
+  const outboundTotal = /* @__PURE__ */ new Map();
+  for (const [node, edges] of adj.entries()) {
+    if (!scores.has(node)) continue;
+    let sum = 0;
+    for (const edge of edges) {
+      if (!eligible(edge, node)) continue;
+      sum += readEdgeConfidence(edge) * edge.weight;
+    }
+    if (sum > 0) outboundTotal.set(node, sum);
+  }
+  for (let i = 0; i < iterations; i += 1) {
+    const next = /* @__PURE__ */ new Map();
+    for (const [node, score] of scores) {
+      next.set(node, (1 - safeDamping) * score);
+    }
+    for (const [node, score] of scores) {
+      const outEdges = adj.get(node);
+      const total = outboundTotal.get(node);
+      if (!outEdges || outEdges.length === 0 || !total || total <= 0) {
+        next.set(node, (next.get(node) ?? 0) + safeDamping * score);
+        continue;
+      }
+      for (const edge of outEdges) {
+        if (!eligible(edge, node)) continue;
+        const conf = readEdgeConfidence(edge);
+        const neighbor = edge.to === node ? edge.from : edge.to;
+        const flow = safeDamping * score * (conf * edge.weight / total);
+        next.set(neighbor, (next.get(neighbor) ?? 0) + flow);
+      }
+    }
+    for (const [node, score] of next) {
+      scores.set(node, score);
+    }
+  }
+}
 function applyLateralInhibition(scores, opts) {
   const { beta, topM } = opts;
   if (beta === 0 || topM === 0) return new Map(scores);
@@ -334,16 +470,23 @@ function applyLateralInhibition(scores, opts) {
 }
 
 export {
+  DEFAULT_GRAPH_TRAVERSAL_CONFIDENCE_FLOOR,
+  DEFAULT_GRAPH_TRAVERSAL_PAGERANK_ITERATIONS,
   CAUSAL_PHRASES,
   graphsDir,
   graphFilePath,
   ensureGraphsDir,
+  withGraphWriteLock,
   appendEdge,
   readEdges,
+  readEdgesStrict,
   readAllEdges,
   analyzeGraphHealth,
   detectCausalPhrase,
   GraphIndex,
+  clampConfidenceFloor,
+  clampPageRankIterations,
+  applyPageRankRefinement,
   applyLateralInhibition
 };
-//# sourceMappingURL=chunk-C2EFFULQ.js.map
+//# sourceMappingURL=chunk-RK2Y4XOM.js.map

package/dist/chunk-RK2Y4XOM.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/graph.ts"],"sourcesContent":["/**\n * Multi-Graph Memory (MAGMA/SYNAPSE-inspired, v8.2)\n *\n * Maintains three typed edge graphs:\n *   entity.jsonl  — memories sharing a named entity (entityRef)\n *   time.jsonl    — consecutive memories in the same thread/session\n *   causal.jsonl  — memories linked by causal language heuristics\n *\n * Stored under `<memoryDir>/state/graphs/`.\n * All writes are fail-open: errors are caught/logged, never thrown.\n */\n\nimport { mkdir, appendFile, readFile } from \"node:fs/promises\";\nimport * as path from \"path\";\n\nimport { readEdgeConfidence } from \"./graph-edge-reinforcement.js\";\nimport { emitGraphEvent } from \"./graph-events.js\";\n\nexport type GraphType = \"entity\" | \"time\" | \"causal\";\n\nexport interface GraphEdge {\n  from: string; // relative memory path (e.g. \"facts/2026-02-22/abc.md\")\n  to: string; // relative memory path\n  type: GraphType;\n  weight: number; // 1.0 default, decay applied during traversal\n  label: string; // entity name, threadId, or matched causal phrase\n  ts: string; // ISO timestamp of edge creation\n\n  // Issue #681 — edge confidence + reinforcement (PR 1/3: schema + primitive only).\n  // Both fields are optional so existing edges without confidence still validate.\n  // Treat a missing `confidence` as 1.0 (legacy behavior) at read sites.\n  // PR 2/3 wires the maintenance decay job; PR 3/3 weights PageRank traversal by confidence.\n  confidence?: number; // [0, 1]; missing = 1.0\n  lastReinforcedAt?: string; // ISO timestamp of most recent reinforcement\n}\n\nexport interface GraphConfig {\n  multiGraphMemoryEnabled: boolean;\n  entityGraphEnabled: boolean;\n  timeGraphEnabled: boolean;\n  causalGraphEnabled: boolean;\n  maxGraphTraversalSteps: number;\n  graphActivationDecay: number;\n  maxEntityGraphEdgesPerMemory: number;\n  graphLateralInhibitionEnabled: boolean;\n  graphLateralInhibitionBeta: number;\n  graphLateralInhibitionTopM: number;\n  /**\n   * Issue #681 PR 3/3 — minimum edge confidence required for traversal.\n   * Edges with confidence below this floor are pruned. Legacy edges\n   * (no `confidence` field) are treated as 1.0 and always pass.\n   * Range `[0, 1]`. Default 0.2.\n   */\n  graphTraversalConfidenceFloor: number;\n  /**\n   * Issue #681 PR 3/3 — number of PageRank-style refinement iterations\n   * applied on top of BFS activation. Set to 0 to disable refinement\n   * and return raw BFS scores. Default 8.\n   */\n  graphTraversalPageRankIterations: number;\n}\n\n/** Default minimum edge confidence required for traversal (issue #681 PR 3/3). */\nexport const DEFAULT_GRAPH_TRAVERSAL_CONFIDENCE_FLOOR = 0.2;\n/** Default PageRank-style refinement iteration count (issue #681 PR 3/3). */\nexport const DEFAULT_GRAPH_TRAVERSAL_PAGERANK_ITERATIONS = 8;\n\n// Causal signal phrases — order matters (most specific first)\nexport const CAUSAL_PHRASES = [\n  \"as a result\",\n  \"led to\",\n  \"because of\",\n  \"therefore\",\n  \"caused\",\n  \"because\",\n];\n\nexport function graphsDir(memoryDir: string): string {\n  return path.join(memoryDir, \"state\", \"graphs\");\n}\n\nexport function graphFilePath(memoryDir: string, type: GraphType): string {\n  return path.join(graphsDir(memoryDir), `${type}.jsonl`);\n}\n\nexport async function ensureGraphsDir(memoryDir: string): Promise<void> {\n  await mkdir(graphsDir(memoryDir), { recursive: true });\n}\n\n// ---------------------------------------------------------------------------\n// Per-graph-file write lock (gotcha #40 promise-chain pattern).\n//\n// Both the append path (`appendEdge`) and the rewrite path used by the\n// decay maintenance job must serialize on the same lock keyed by the\n// JSONL file path. Without this, an extraction can append a new edge\n// between the decay job's read-snapshot and rewrite, silently dropping\n// the appended edge during active traffic (issue #729 / Codex P1).\n// ---------------------------------------------------------------------------\nconst graphWriteLocks = new Map<string, Promise<void>>();\n\n/**\n * Run `fn` while holding the write lock for the given graph JSONL file.\n *\n * The lock is keyed by absolute file path so concurrent writes to\n * different graph types proceed independently. The chain recovers from\n * rejection (gotcha #40) so a single I/O failure does not poison all\n * future writers, but the original error is still surfaced to the\n * caller of `withGraphWriteLock`.\n */\nexport function withGraphWriteLock<T>(filePath: string, fn: () => Promise<T>): Promise<T> {\n  const prev = graphWriteLocks.get(filePath) ?? Promise.resolve();\n  const next = prev.then(fn, fn);\n  graphWriteLocks.set(\n    filePath,\n    next.then(\n      () => undefined,\n      () => undefined,\n    ),\n  );\n  return next;\n}\n\nexport async function appendEdge(memoryDir: string, edge: GraphEdge): Promise<void> {\n  await ensureGraphsDir(memoryDir);\n  const filePath = graphFilePath(memoryDir, edge.type);\n  const line = JSON.stringify(edge) + \"\\n\";\n  await withGraphWriteLock(filePath, async () => {\n    await appendFile(filePath, line, \"utf8\");\n  });\n  // Emit edge-added event for SSE subscribers (issue #691 PR 5/5).\n  // Fail-open: emitGraphEvent catches listener errors so a bad SSE client\n  // can never surface into the extraction pipeline.\n  emitGraphEvent(memoryDir, \"edge-added\", {\n    source: edge.from,\n    target: edge.to,\n    kind: edge.type,\n    weight: edge.weight,\n    label: edge.label,\n    confidence: typeof edge.confidence === \"number\" ? edge.confidence : 1.0,\n  });\n}\n\nfunction isNodeError(err: unknown): err is NodeJS.ErrnoException {\n  return typeof err === \"object\" && err !== null && \"code\" in err;\n}\n\nfunction parseEdgesJsonl(raw: string): GraphEdge[] {\n  const edges: GraphEdge[] = [];\n  for (const line of raw.split(\"\\n\")) {\n    const trimmed = line.trim();\n    if (!trimmed) continue;\n    try {\n      edges.push(JSON.parse(trimmed) as GraphEdge);\n    } catch {\n      // skip corrupt lines — fail-open for partial JSONL recovery\n    }\n  }\n  return edges;\n}\n\n/**\n * Read all edges of a given type from the JSONL file.\n * Returns [] if the file doesn't exist or any read error occurs (fail-open).\n *\n * Production traversal callers (recall/PageRank) depend on this fail-open\n * posture so a temporarily missing or unreadable graph file never blocks\n * a recall. Maintenance jobs that need to distinguish ENOENT from real\n * I/O failures must use {@link readEdgesStrict} instead.\n */\nexport async function readEdges(memoryDir: string, type: GraphType): Promise<GraphEdge[]> {\n  const filePath = graphFilePath(memoryDir, type);\n  try {\n    const raw = await readFile(filePath, \"utf8\");\n    return parseEdgesJsonl(raw);\n  } catch {\n    return [];\n  }\n}\n\n/**\n * Same as {@link readEdges} but only swallows `ENOENT`; all other read\n * errors (`EACCES`, `EIO`, …) are propagated. Used by the graph-edge\n * decay maintenance job so I/O outages surface as a failed run instead\n * of being silently reported as \"no edges to decay\" (issue #729 /\n * Codex P1, line 120).\n */\nexport async function readEdgesStrict(memoryDir: string, type: GraphType): Promise<GraphEdge[]> {\n  const filePath = graphFilePath(memoryDir, type);\n  try {\n    const raw = await readFile(filePath, \"utf8\");\n    return parseEdgesJsonl(raw);\n  } catch (err) {\n    if (isNodeError(err) && err.code === \"ENOENT\") {\n      return [];\n    }\n    throw err;\n  }\n}\n\n/**\n * Read edges from all enabled graph types.\n */\nexport async function readAllEdges(\n  memoryDir: string,\n  config: Pick<GraphConfig, \"entityGraphEnabled\" | \"timeGraphEnabled\" | \"causalGraphEnabled\">,\n): Promise<GraphEdge[]> {\n  const parts: GraphEdge[][] = await Promise.all([\n    config.entityGraphEnabled ? readEdges(memoryDir, \"entity\") : Promise.resolve([]),\n    config.timeGraphEnabled ? readEdges(memoryDir, \"time\") : Promise.resolve([]),\n    config.causalGraphEnabled ? readEdges(memoryDir, \"causal\") : Promise.resolve([]),\n  ]);\n  return parts.flat();\n}\n\nexport interface GraphHealthFileStats {\n  type: GraphType;\n  filePath: string;\n  exists: boolean;\n  totalLines: number;\n  validEdges: number;\n  corruptLines: number;\n  uniqueNodes: number;\n}\n\nexport interface GraphHealthReport {\n  generatedAt: string;\n  enabledTypes: GraphType[];\n  totals: {\n    totalLines: number;\n    validEdges: number;\n    corruptLines: number;\n    uniqueNodes: number;\n  };\n  files: GraphHealthFileStats[];\n  repairGuidance?: string[];\n}\n\nfunction isValidGraphEdge(raw: unknown, expectedType: GraphType): raw is GraphEdge {\n  if (!raw || typeof raw !== \"object\") return false;\n  const edge = raw as Record<string, unknown>;\n  return (\n    edge.type === expectedType &&\n    typeof edge.from === \"string\" && edge.from.length > 0 &&\n    typeof edge.to === \"string\" && edge.to.length > 0 &&\n    typeof edge.weight === \"number\" && Number.isFinite(edge.weight) &&\n    typeof edge.label === \"string\" &&\n    typeof edge.ts === \"string\"\n  );\n}\n\nexport async function analyzeGraphHealth(\n  memoryDir: string,\n  options?: {\n    entityGraphEnabled?: boolean;\n    timeGraphEnabled?: boolean;\n    causalGraphEnabled?: boolean;\n    includeRepairGuidance?: boolean;\n  },\n): Promise<GraphHealthReport> {\n  const enabledTypes: GraphType[] = [];\n  if (options?.entityGraphEnabled !== false) enabledTypes.push(\"entity\");\n  if (options?.timeGraphEnabled !== false) enabledTypes.push(\"time\");\n  if (options?.causalGraphEnabled !== false) enabledTypes.push(\"causal\");\n\n  const files: GraphHealthFileStats[] = [];\n  const globalNodes = new Set<string>();\n\n  for (const type of enabledTypes) {\n    const filePath = graphFilePath(memoryDir, type);\n    let exists = true;\n    let totalLines = 0;\n    let validEdges = 0;\n    let corruptLines = 0;\n    const nodes = new Set<string>();\n\n    try {\n      const raw = await readFile(filePath, \"utf8\");\n      for (const line of raw.split(\"\\n\")) {\n        const trimmed = line.trim();\n        if (!trimmed) continue;\n        totalLines += 1;\n        try {\n          const parsed = JSON.parse(trimmed) as unknown;\n          if (!isValidGraphEdge(parsed, type)) {\n            corruptLines += 1;\n            continue;\n          }\n          validEdges += 1;\n          nodes.add(parsed.from);\n          nodes.add(parsed.to);\n          globalNodes.add(parsed.from);\n          globalNodes.add(parsed.to);\n        } catch {\n          corruptLines += 1;\n        }\n      }\n    } catch {\n      exists = false;\n    }\n\n    files.push({\n      type,\n      filePath,\n      exists,\n      totalLines,\n      validEdges,\n      corruptLines,\n      uniqueNodes: nodes.size,\n    });\n  }\n\n  const totals = files.reduce(\n    (acc, item) => {\n      acc.totalLines += item.totalLines;\n      acc.validEdges += item.validEdges;\n      acc.corruptLines += item.corruptLines;\n      return acc;\n    },\n    {\n      totalLines: 0,\n      validEdges: 0,\n      corruptLines: 0,\n      uniqueNodes: globalNodes.size,\n    },\n  );\n  totals.uniqueNodes = globalNodes.size;\n\n  const report: GraphHealthReport = {\n    generatedAt: new Date().toISOString(),\n    enabledTypes,\n    totals,\n    files,\n  };\n\n  if (options?.includeRepairGuidance === true) {\n    const guidance: string[] = [];\n    if (totals.corruptLines > 0) {\n      guidance.push(\"Corrupt graph lines detected: back up memory/state/graphs, then rebuild graphs from clean memory replay/extraction runs.\");\n    }\n    if (totals.validEdges === 0) {\n      guidance.push(\"No valid edges detected yet: run normal extraction traffic (or replay ingestion) to seed graph files.\");\n    }\n    if (guidance.length > 0) report.repairGuidance = guidance;\n  }\n\n  return report;\n}\n\n/**\n * Detect causal signal phrases in text. Returns the first matched phrase, or null.\n */\nexport function detectCausalPhrase(text: string): string | null {\n  const lower = text.toLowerCase();\n  for (const phrase of CAUSAL_PHRASES) {\n    if (lower.includes(phrase)) return phrase;\n  }\n  return null;\n}\n\n/**\n * GraphIndex — builds and updates the three memory graphs.\n *\n * Usage (orchestrator):\n *   this.graphIndex = new GraphIndex(config.memoryDir, config);\n *\n *   // After each memory write:\n *   await this.graphIndex.onMemoryWritten(memoryPath, frontmatter, threadId, recentInThread);\n */\nexport class GraphIndex {\n  private readonly memoryDir: string;\n  private readonly cfg: GraphConfig;\n\n  // Cache for readAllEdges() result.  With 30k+ entity edges (6 MB JSONL) the\n  // file read + JSON parse takes 2-4 s per call.  This instance-level cache\n  // eliminates that overhead on every spreadingActivation() call; it is\n  // invalidated (set to null) in onMemoryWritten() so new edges appear promptly.\n  private edgeCache: { allEdges: GraphEdge[]; loadedAt: number } | null = null;\n  private static readonly EDGE_CACHE_TTL_MS = 300_000; // 5 minutes\n\n  constructor(memoryDir: string, cfg: GraphConfig) {\n    this.memoryDir = memoryDir;\n    this.cfg = cfg;\n  }\n\n  /** Clear the edge cache so the next spreadingActivation() re-reads from disk.\n   *  Call after any code path that appends edges outside of onMemoryWritten(). */\n  invalidateEdgeCache(): void {\n    this.edgeCache = null;\n  }\n\n  private async loadEdgesCached(): Promise<GraphEdge[]> {\n    if (\n      this.edgeCache &&\n      Date.now() - this.edgeCache.loadedAt < GraphIndex.EDGE_CACHE_TTL_MS\n    ) {\n      return this.edgeCache.allEdges;\n    }\n    const allEdges = await readAllEdges(this.memoryDir, {\n      entityGraphEnabled: this.cfg.entityGraphEnabled,\n      timeGraphEnabled: this.cfg.timeGraphEnabled,\n      causalGraphEnabled: this.cfg.causalGraphEnabled,\n    });\n    this.edgeCache = { allEdges, loadedAt: Date.now() };\n    return allEdges;\n  }\n\n  /**\n   * Called after a memory is written to disk.\n   *\n   * @param memoryPath - relative path from memoryDir (e.g. \"facts/2026-02-22/abc.md\")\n   * @param entityRef  - entityRef frontmatter field (if any)\n   * @param content    - full memory text (for causal detection)\n   * @param created    - ISO timestamp of this memory\n   * @param threadId   - current thread ID (for time graph)\n   * @param recentInThread - paths of the N most-recent memories in this thread (for time graph)\n   * @param entitySiblings - paths of other memories that share the same entityRef (for entity graph)\n   */\n  async onMemoryWritten(opts: {\n    memoryPath: string;\n    entityRef?: string;\n    content: string;\n    created: string;\n    threadId?: string;\n    recentInThread?: string[];\n    entitySiblings?: string[];\n    causalPredecessor?: string;\n  }): Promise<void> {\n    if (!this.cfg.multiGraphMemoryEnabled) return;\n    const ts = new Date().toISOString();\n\n    try {\n      // Entity graph\n      if (this.cfg.entityGraphEnabled && opts.entityRef && opts.entitySiblings?.length) {\n        const siblings = opts.entitySiblings.slice(0, this.cfg.maxEntityGraphEdgesPerMemory);\n        for (const sibling of siblings) {\n          await appendEdge(this.memoryDir, {\n            from: opts.memoryPath,\n            to: sibling,\n            type: \"entity\",\n            weight: 1.0,\n            label: opts.entityRef,\n            ts,\n          });\n        }\n      }\n\n      // Time graph — link to most recent memory in same thread\n      if (this.cfg.timeGraphEnabled && opts.threadId && opts.recentInThread?.length) {\n        const predecessor = opts.recentInThread[opts.recentInThread.length - 1];\n        if (predecessor && predecessor !== opts.memoryPath) {\n          await appendEdge(this.memoryDir, {\n            from: predecessor,\n            to: opts.memoryPath,\n            type: \"time\",\n            weight: 1.0,\n            label: opts.threadId,\n            ts,\n          });\n        }\n      }\n\n      // Causal graph\n      if (this.cfg.causalGraphEnabled && opts.causalPredecessor) {\n        const phrase = detectCausalPhrase(opts.content);\n        if (phrase) {\n          await appendEdge(this.memoryDir, {\n            from: opts.causalPredecessor,\n            to: opts.memoryPath,\n            type: \"causal\",\n            weight: 1.0,\n            label: phrase,\n            ts,\n          });\n        }\n      }\n    } catch (err) {\n      // Fail-open: graph write errors must never surface to caller\n      const { log } = await import(\"./logger.js\");\n      log.warn(`[graph] onMemoryWritten error: ${err}`);\n    } finally {\n      // Invalidate edge cache so spreadingActivation() picks up new edges.\n      // In `finally` so the cache is cleared even on partial write failure.\n      this.edgeCache = null;\n    }\n  }\n\n  /**\n   * Spreading activation BFS (SYNAPSE-inspired).\n   *\n   * Starting from `seeds`, traverse the combined graph for up to `maxSteps` hops.\n   * Each candidate gets an activation score = edge.weight × edgeConfidence × decay^hop.\n   *\n   * Issue #681 PR 3/3 — confidence-aware traversal:\n   *   - Each edge's `weight` is multiplied by its `confidence` (legacy edges\n   *     missing `confidence` are treated as 1.0, preserving prior behavior).\n   *   - Edges with `confidence < graphTraversalConfidenceFloor` are pruned and\n   *     contribute neither activation nor downstream neighbors.\n   *   - When `graphTraversalPageRankIterations > 0`, an additional PageRank-\n   *     style refinement pass redistributes activation along confidence-weighted\n   *     edges, sharpening the ranking among multi-hop candidates.\n   *   - Per-result provenance includes the highest-confidence edge that landed\n   *     on each candidate, so the X-ray surface can attribute pruning and\n   *     ranking decisions back to specific edges.\n   *\n   * @param seeds    - initial memory paths to expand from (e.g. QMD top results)\n   * @param maxSteps - max BFS hops (from config: maxGraphTraversalSteps)\n   * @returns Array of {path, score, edgeConfidence, ...} sorted descending, not including seed paths\n   */\n  async spreadingActivation(\n    seeds: string[],\n    maxSteps?: number,\n    opts?: {\n      /**\n       * Issue #681 — when `true`, bypasses the configured\n       * `graphTraversalConfidenceFloor` and includes low-confidence\n       * edges in traversal.  Equivalent to forcing the floor to `0`.\n       * Default `false` (floor from config is applied).\n       */\n      includeLowConfidence?: boolean;\n    },\n  ): Promise<Array<{\n    path: string;\n    score: number;\n    seed: string;\n    hopDepth: number;\n    decayedWeight: number;\n    graphType: \"entity\" | \"time\" | \"causal\";\n    /**\n     * Confidence of the edge that produced this candidate's recorded\n     * provenance (the strongest edge along the chosen entry path).\n     * In `[0, 1]`. Legacy edges without `confidence` surface as 1.0.\n     */\n    edgeConfidence: number;\n  }>> {\n    if (!this.cfg.multiGraphMemoryEnabled) return [];\n    const steps = maxSteps ?? this.cfg.maxGraphTraversalSteps;\n    const decay = this.cfg.graphActivationDecay;\n    // When `includeLowConfidence` is set, use floor=0 so all edges\n    // participate in traversal regardless of their decay state.\n    // Otherwise clamp the configured floor into [0, 1] so misconfiguration\n    // cannot (a) admit edges with negative confidence or (b) reject every\n    // edge.\n    const floor = opts?.includeLowConfidence === true\n      ? 0\n      : clampConfidenceFloor(this.cfg.graphTraversalConfidenceFloor);\n    const iterations = clampPageRankIterations(\n      this.cfg.graphTraversalPageRankIterations,\n    );\n\n    try {\n      const allEdges = await this.loadEdgesCached();\n\n      // Build adjacency index: from → edges, to → edges (bidirectional for entity/time, directional for causal).\n      // Edges below the confidence floor are pruned at index time so neither\n      // direct activation nor downstream BFS expansion can re-introduce them.\n      const adj = new Map<string, GraphEdge[]>();\n      for (const edge of allEdges) {\n        const conf = readEdgeConfidence(edge);\n        if (conf < floor) continue;\n        if (!adj.has(edge.from)) adj.set(edge.from, []);\n        adj.get(edge.from)!.push(edge);\n        // Entity and time edges are bidirectional\n        if (edge.type !== \"causal\") {\n          if (!adj.has(edge.to)) adj.set(edge.to, []);\n          adj.get(edge.to)!.push({ ...edge, from: edge.to, to: edge.from });\n        }\n      }\n\n      const seedSet = new Set(seeds);\n      const scores = new Map<string, number>(); // candidate path → accumulated activation score\n      const provenance = new Map<\n        string,\n        {\n          seed: string;\n          hopDepth: number;\n          decayedWeight: number;\n          graphType: \"entity\" | \"time\" | \"causal\";\n          edgeConfidence: number;\n        }\n      >();\n      const visited = new Set<string>(seeds);\n\n      // BFS queue: [nodePath, hop, seedPath]\n      const queue: Array<[string, number, string]> = seeds.map((s) => [s, 0, s]);\n\n      while (queue.length > 0) {\n        const [node, hop, sourceSeed] = queue.shift()!;\n        if (hop >= steps) continue;\n\n        const edges = adj.get(node) ?? [];\n        for (const edge of edges) {\n          const neighbor = edge.to === node ? edge.from : edge.to;\n          const conf = readEdgeConfidence(edge);\n          // Defense in depth: the adjacency build already drops sub-floor\n          // edges, but if a synthesized reverse edge ever bypassed that\n          // path, this guard keeps spreading activation honest.\n          if (conf < floor) continue;\n          const score = edge.weight * conf * Math.pow(decay, hop + 1);\n\n          if (!seedSet.has(neighbor)) {\n            const existing = scores.get(neighbor) ?? 0;\n            scores.set(neighbor, existing + score);\n\n            const prev = provenance.get(neighbor);\n            if (\n              !prev ||\n              hop + 1 < prev.hopDepth ||\n              (hop + 1 === prev.hopDepth && score > prev.decayedWeight)\n            ) {\n              provenance.set(neighbor, {\n                seed: sourceSeed,\n                hopDepth: hop + 1,\n                decayedWeight: score,\n                graphType: edge.type,\n                edgeConfidence: conf,\n              });\n            }\n          }\n\n          if (!visited.has(neighbor)) {\n            visited.add(neighbor);\n            queue.push([neighbor, hop + 1, sourceSeed]);\n          }\n        }\n      }\n\n      // Issue #681 PR 3/3 — optional PageRank-style refinement.\n      // Redistributes a node's accumulated activation along its outgoing\n      // edges, weighted by edge confidence. Damping is fixed at the\n      // canonical 0.85 so the ranking stays comparable across queries;\n      // the `iterations` knob bounds compute, not behavior shape.\n      if (iterations > 0 && scores.size > 1) {\n        applyPageRankRefinement(scores, adj, {\n          iterations,\n          floor,\n          damping: 0.85,\n        });\n      }\n\n      // Apply lateral inhibition if enabled (Synapse-inspired competitive suppression)\n      if (this.cfg.graphLateralInhibitionEnabled && scores.size > 1) {\n        const inhibited = applyLateralInhibition(scores, {\n          beta: this.cfg.graphLateralInhibitionBeta,\n          topM: this.cfg.graphLateralInhibitionTopM,\n        });\n        for (const [k, v] of inhibited) {\n          scores.set(k, v);\n        }\n      }\n\n      return Array.from(scores.entries())\n        .map(([p, score]) => ({\n          path: p,\n          score,\n          seed: provenance.get(p)?.seed ?? \"\",\n          hopDepth: provenance.get(p)?.hopDepth ?? 0,\n          decayedWeight: provenance.get(p)?.decayedWeight ?? 0,\n          graphType: provenance.get(p)?.graphType ?? \"entity\",\n          edgeConfidence: provenance.get(p)?.edgeConfidence ?? 1,\n        }))\n        .sort((a, b) => b.score - a.score);\n    } catch (err) {\n      const { log } = await import(\"./logger.js\");\n      log.warn(`[graph] spreadingActivation error: ${err}`);\n      return [];\n    }\n  }\n}\n\n/**\n * Clamp `graphTraversalConfidenceFloor` into the legal range `[0, 1]`.\n * Non-finite or non-numeric values fall back to the documented default\n * so misconfiguration cannot silently disable the floor or reject every edge.\n *\n * Exported for tests; call sites in `spreadingActivation` use it to make\n * the contract explicit at every boundary.\n */\nexport function clampConfidenceFloor(raw: unknown): number {\n  if (typeof raw !== \"number\" || !Number.isFinite(raw)) {\n    return DEFAULT_GRAPH_TRAVERSAL_CONFIDENCE_FLOOR;\n  }\n  if (raw < 0) return 0;\n  if (raw > 1) return 1;\n  return raw;\n}\n\n/**\n * Clamp `graphTraversalPageRankIterations` into a non-negative integer.\n * Negative or non-finite values fall back to 0 (disable refinement) so\n * misconfiguration cannot stall recall in an unbounded loop.\n */\nexport function clampPageRankIterations(raw: unknown): number {\n  if (typeof raw !== \"number\" || !Number.isFinite(raw)) return 0;\n  if (raw <= 0) return 0;\n  return Math.floor(raw);\n}\n\n/**\n * PageRank-style refinement on top of the BFS activation map.\n *\n * Each iteration redistributes a fraction of every node's score along\n * its outgoing edges, scaled by edge confidence. Confidence below\n * `floor` is filtered out before redistribution, mirroring the BFS\n * pruning rule. Mutates `scores` in place.\n *\n * Exported for tests; in production, call sites pass the same adjacency\n * map already used by BFS so behavior stays consistent.\n */\nexport function applyPageRankRefinement(\n  scores: Map<string, number>,\n  adj: Map<string, GraphEdge[]>,\n  opts: { iterations: number; floor: number; damping: number },\n): void {\n  const { iterations, floor, damping } = opts;\n  if (iterations <= 0 || scores.size === 0) return;\n  const safeDamping = Math.min(1, Math.max(0, damping));\n\n  // Pre-compute confidence-weighted out-edge totals for normalization.\n  // Done once per refinement, not per iteration, since adjacency is\n  // immutable inside the loop.\n  //\n  // Codex P1 (#735): the denominator MUST be computed over the same\n  // eligible-neighbor set the iteration redistributes into — i.e.\n  // edges whose neighbor is in `scores`. Counting edges-to-seeds (or\n  // edges-to-unseen-nodes) in the denominator while dropping their\n  // flow during iteration leaks `safeDamping × score` every pass and\n  // collapses leaf candidates' scores instead of just re-ranking them.\n  const eligible = (edge: GraphEdge, fromNode: string): boolean => {\n    if (readEdgeConfidence(edge) < floor) return false;\n    const neighbor = edge.to === fromNode ? edge.from : edge.to;\n    return scores.has(neighbor);\n  };\n  const outboundTotal = new Map<string, number>();\n  for (const [node, edges] of adj.entries()) {\n    if (!scores.has(node)) continue; // only candidate nodes redistribute\n    let sum = 0;\n    for (const edge of edges) {\n      if (!eligible(edge, node)) continue;\n      sum += readEdgeConfidence(edge) * edge.weight;\n    }\n    if (sum > 0) outboundTotal.set(node, sum);\n  }\n\n  for (let i = 0; i < iterations; i += 1) {\n    const next = new Map<string, number>();\n    // Teleport / damping floor: every node retains `(1 - damping) * score`\n    // of its current activation so dangling nodes do not bleed to zero.\n    for (const [node, score] of scores) {\n      next.set(node, (1 - safeDamping) * score);\n    }\n    for (const [node, score] of scores) {\n      const outEdges = adj.get(node);\n      const total = outboundTotal.get(node);\n      // Dangling-node fallback: when a candidate has zero eligible\n      // outflow (no in-scores neighbors above the floor), the\n      // `safeDamping × score` portion would otherwise evaporate. Keep\n      // it on `node` so total mass is conserved and the score reflects\n      // the candidate's standing rather than its in-degree topology.\n      if (!outEdges || outEdges.length === 0 || !total || total <= 0) {\n        next.set(node, (next.get(node) ?? 0) + safeDamping * score);\n        continue;\n      }\n      for (const edge of outEdges) {\n        if (!eligible(edge, node)) continue;\n        const conf = readEdgeConfidence(edge);\n        const neighbor = edge.to === node ? edge.from : edge.to;\n        const flow = safeDamping * score * ((conf * edge.weight) / total);\n        next.set(neighbor, (next.get(neighbor) ?? 0) + flow);\n      }\n    }\n    for (const [node, score] of next) {\n      scores.set(node, score);\n    }\n  }\n}\n\n/**\n * Lateral inhibition (Synapse-inspired).\n *\n * For each node, the top-M higher-activation competitors exert inhibition\n * proportional to their activation difference. Output is clamped to [0, ∞).\n *\n * No sigmoid is applied here — downstream `normalizeGraphActivationScore`\n * already applies x/(1+x) soft squash, so adding a sigmoid would double-\n * normalize and cap graph influence at ~50%.\n *\n * Formula: u_hat_i = max(0, u_i - beta * sum_{k in top-M where u_k > u_i}(u_k - u_i))\n *\n * When beta=0 or topM=0, returns original scores unchanged (no-op).\n */\nexport function applyLateralInhibition(\n  scores: Map<string, number>,\n  opts: { beta: number; topM: number },\n): Map<string, number> {\n  const { beta, topM } = opts;\n  if (beta === 0 || topM === 0) return new Map(scores);\n\n  const sorted = Array.from(scores.entries()).sort((a, b) => b[1] - a[1]);\n  const topCompetitors = sorted.slice(0, topM);\n\n  const result = new Map<string, number>();\n  for (const [node, u] of scores) {\n    let inhibition = 0;\n    for (const [, uK] of topCompetitors) {\n      if (uK > u) {\n        inhibition += uK - u;\n      }\n    }\n    result.set(node, Math.max(0, u - beta * inhibition));\n  }\n\n  return result;\n}\n"],"mappings":"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","names":[]}

package/dist/{chunk-TP4FZJIZ.js → chunk-RULE4VG5.js}

@@ -28,6 +28,9 @@ function inferMemoryStatus(frontmatter, pathRel, fallbackStatus = "active") {
   if (frontmatter.status) return frontmatter.status;
   return fallbackStatus;
 }
+function isActiveMemoryStatus(status) {
+  return status === void 0 || status === "active";
+}
 function summarizeMemoryLifecycleState(memory) {
   return {
     category: memory.frontmatter.category,
@@ -85,9 +88,10 @@ export {
   toMemoryPathRel,
   isArchivedMemoryPath,
   inferMemoryStatus,
+  isActiveMemoryStatus,
   summarizeMemoryLifecycleState,
   makeRebuiltMemoryLifecycleEvent,
   buildLifecycleEventsForMemory,
   sortMemoryLifecycleEvents
 };
-//# sourceMappingURL=chunk-TP4FZJIZ.js.map
+//# sourceMappingURL=chunk-RULE4VG5.js.map

package/dist/chunk-RULE4VG5.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/memory-lifecycle-ledger-utils.ts"],"sourcesContent":["import path from \"node:path\";\nimport type {\n  MemoryFile,\n  MemoryLifecycleEvent,\n  MemoryLifecycleEventType,\n  MemoryLifecycleStateSummary,\n  MemoryFrontmatter,\n  MemoryStatus,\n} from \"./types.js\";\n\nexport const MEMORY_LIFECYCLE_RULE_VERSION = \"memory-lifecycle-ledger.v1\";\n\nexport const MEMORY_LIFECYCLE_EVENT_SORT_ORDER: Record<MemoryLifecycleEventType, number> = {\n  created: 0,\n  updated: 1,\n  promoted: 2,\n  explicit_capture_accepted: 3,\n  explicit_capture_queued: 4,\n  imported: 5,\n  merged: 6,\n  restored: 7,\n  superseded: 8,\n  rejected: 9,\n  archived: 10,\n};\n\nexport function toMemoryPathRel(baseDir: string, filePath: string): string {\n  if (!baseDir) return filePath.split(path.sep).join(\"/\");\n  return path.relative(baseDir, filePath).split(path.sep).join(\"/\");\n}\n\nexport function isArchivedMemoryPath(pathRel: string): boolean {\n  return pathRel === \"archive\" || pathRel.startsWith(\"archive/\");\n}\n\nexport function inferMemoryStatus(\n  frontmatter: MemoryFrontmatter,\n  pathRel: string,\n  fallbackStatus: MemoryStatus = \"active\",\n): MemoryStatus {\n  if (frontmatter.status && frontmatter.status !== \"active\") return frontmatter.status;\n  if (frontmatter.archivedAt) return \"archived\";\n  if (isArchivedMemoryPath(pathRel)) return \"archived\";\n  if (frontmatter.status) return frontmatter.status;\n  return fallbackStatus;\n}\n\nexport function isActiveMemoryStatus(status: MemoryStatus | string | undefined): boolean {\n  return status === undefined || status === \"active\";\n}\n\nexport function summarizeMemoryLifecycleState(memory: MemoryFile): MemoryLifecycleStateSummary {\n  return {\n    category: memory.frontmatter.category,\n    path: memory.path,\n    status: memory.frontmatter.status ?? \"active\",\n    lifecycleState: memory.frontmatter.lifecycleState,\n  };\n}\n\nexport function makeRebuiltMemoryLifecycleEvent(\n  memory: MemoryFile,\n  eventType: MemoryLifecycleEventType,\n  timestamp: string,\n): MemoryLifecycleEvent {\n  return {\n    eventId: `rebuild-${memory.frontmatter.id}-${eventType}-${timestamp}`,\n    memoryId: memory.frontmatter.id,\n    eventType,\n    timestamp,\n    actor: \"maintenance.rebuildMemoryLifecycleLedger\",\n    ruleVersion: MEMORY_LIFECYCLE_RULE_VERSION,\n    after: summarizeMemoryLifecycleState(memory),\n    relatedMemoryIds: [\n      ...(memory.frontmatter.supersededBy ? [memory.frontmatter.supersededBy] : []),\n      ...(memory.frontmatter.supersedes ? [memory.frontmatter.supersedes] : []),\n      ...((memory.frontmatter.lineage ?? []).filter(Boolean)),\n    ],\n  };\n}\n\nexport function buildLifecycleEventsForMemory(memory: MemoryFile): MemoryLifecycleEvent[] {\n  const events: MemoryLifecycleEvent[] = [];\n  const created = memory.frontmatter.created;\n  const updated = memory.frontmatter.updated;\n  const archivedAt = memory.frontmatter.archivedAt;\n  const supersededAt = memory.frontmatter.supersededAt;\n  const effectiveArchivedAt =\n    archivedAt ?? (memory.frontmatter.status === \"archived\" && updated ? updated : undefined);\n\n  events.push(makeRebuiltMemoryLifecycleEvent(memory, \"created\", created));\n  if (\n    updated &&\n    updated !== created &&\n    updated !== effectiveArchivedAt &&\n    updated !== supersededAt\n  ) {\n    events.push(makeRebuiltMemoryLifecycleEvent(memory, \"updated\", updated));\n  }\n  if (supersededAt) {\n    events.push(makeRebuiltMemoryLifecycleEvent(memory, \"superseded\", supersededAt));\n  }\n  if (effectiveArchivedAt) {\n    events.push(makeRebuiltMemoryLifecycleEvent(memory, \"archived\", effectiveArchivedAt));\n  }\n\n  return events;\n}\n\nexport function sortMemoryLifecycleEvents(events: MemoryLifecycleEvent[]): MemoryLifecycleEvent[] {\n  return [...events].sort((a, b) => {\n    if (a.memoryId !== b.memoryId) return a.memoryId.localeCompare(b.memoryId);\n    if (a.timestamp !== b.timestamp) return a.timestamp.localeCompare(b.timestamp);\n    return MEMORY_LIFECYCLE_EVENT_SORT_ORDER[a.eventType] - MEMORY_LIFECYCLE_EVENT_SORT_ORDER[b.eventType];\n  });\n}\n"],"mappings":";AAAA,OAAO,UAAU;AAUV,IAAM,gCAAgC;AAEtC,IAAM,oCAA8E;AAAA,EACzF,SAAS;AAAA,EACT,SAAS;AAAA,EACT,UAAU;AAAA,EACV,2BAA2B;AAAA,EAC3B,yBAAyB;AAAA,EACzB,UAAU;AAAA,EACV,QAAQ;AAAA,EACR,UAAU;AAAA,EACV,YAAY;AAAA,EACZ,UAAU;AAAA,EACV,UAAU;AACZ;AAEO,SAAS,gBAAgB,SAAiB,UAA0B;AACzE,MAAI,CAAC,QAAS,QAAO,SAAS,MAAM,KAAK,GAAG,EAAE,KAAK,GAAG;AACtD,SAAO,KAAK,SAAS,SAAS,QAAQ,EAAE,MAAM,KAAK,GAAG,EAAE,KAAK,GAAG;AAClE;AAEO,SAAS,qBAAqB,SAA0B;AAC7D,SAAO,YAAY,aAAa,QAAQ,WAAW,UAAU;AAC/D;AAEO,SAAS,kBACd,aACA,SACA,iBAA+B,UACjB;AACd,MAAI,YAAY,UAAU,YAAY,WAAW,SAAU,QAAO,YAAY;AAC9E,MAAI,YAAY,WAAY,QAAO;AACnC,MAAI,qBAAqB,OAAO,EAAG,QAAO;AAC1C,MAAI,YAAY,OAAQ,QAAO,YAAY;AAC3C,SAAO;AACT;AAEO,SAAS,qBAAqB,QAAoD;AACvF,SAAO,WAAW,UAAa,WAAW;AAC5C;AAEO,SAAS,8BAA8B,QAAiD;AAC7F,SAAO;AAAA,IACL,UAAU,OAAO,YAAY;AAAA,IAC7B,MAAM,OAAO;AAAA,IACb,QAAQ,OAAO,YAAY,UAAU;AAAA,IACrC,gBAAgB,OAAO,YAAY;AAAA,EACrC;AACF;AAEO,SAAS,gCACd,QACA,WACA,WACsB;AACtB,SAAO;AAAA,IACL,SAAS,WAAW,OAAO,YAAY,EAAE,IAAI,SAAS,IAAI,SAAS;AAAA,IACnE,UAAU,OAAO,YAAY;AAAA,IAC7B;AAAA,IACA;AAAA,IACA,OAAO;AAAA,IACP,aAAa;AAAA,IACb,OAAO,8BAA8B,MAAM;AAAA,IAC3C,kBAAkB;AAAA,MAChB,GAAI,OAAO,YAAY,eAAe,CAAC,OAAO,YAAY,YAAY,IAAI,CAAC;AAAA,MAC3E,GAAI,OAAO,YAAY,aAAa,CAAC,OAAO,YAAY,UAAU,IAAI,CAAC;AAAA,MACvE,IAAK,OAAO,YAAY,WAAW,CAAC,GAAG,OAAO,OAAO;AAAA,IACvD;AAAA,EACF;AACF;AAEO,SAAS,8BAA8B,QAA4C;AACxF,QAAM,SAAiC,CAAC;AACxC,QAAM,UAAU,OAAO,YAAY;AACnC,QAAM,UAAU,OAAO,YAAY;AACnC,QAAM,aAAa,OAAO,YAAY;AACtC,QAAM,eAAe,OAAO,YAAY;AACxC,QAAM,sBACJ,eAAe,OAAO,YAAY,WAAW,cAAc,UAAU,UAAU;AAEjF,SAAO,KAAK,gCAAgC,QAAQ,WAAW,OAAO,CAAC;AACvE,MACE,WACA,YAAY,WACZ,YAAY,uBACZ,YAAY,cACZ;AACA,WAAO,KAAK,gCAAgC,QAAQ,WAAW,OAAO,CAAC;AAAA,EACzE;AACA,MAAI,cAAc;AAChB,WAAO,KAAK,gCAAgC,QAAQ,cAAc,YAAY,CAAC;AAAA,EACjF;AACA,MAAI,qBAAqB;AACvB,WAAO,KAAK,gCAAgC,QAAQ,YAAY,mBAAmB,CAAC;AAAA,EACtF;AAEA,SAAO;AACT;AAEO,SAAS,0BAA0B,QAAwD;AAChG,SAAO,CAAC,GAAG,MAAM,EAAE,KAAK,CAAC,GAAG,MAAM;AAChC,QAAI,EAAE,aAAa,EAAE,SAAU,QAAO,EAAE,SAAS,cAAc,EAAE,QAAQ;AACzE,QAAI,EAAE,cAAc,EAAE,UAAW,QAAO,EAAE,UAAU,cAAc,EAAE,SAAS;AAC7E,WAAO,kCAAkC,EAAE,SAAS,IAAI,kCAAkC,EAAE,SAAS;AAAA,EACvG,CAAC;AACH;","names":[]}

package/dist/{chunk-PVPWZSSI.js → chunk-SMA4IMHV.js}

@@ -1,8 +1,21 @@
 import {
   parseXrayFormat
-} from "./chunk-ZAIM4TUE.js";
+} from "./chunk-LW2NMHDW.js";
+import {
+  RECALL_DISCLOSURE_LEVELS,
+  isRecallDisclosure
+} from "./chunk-43EKP2UK.js";
 
 // src/recall-xray-cli.ts
+function parseXrayDisclosureFlag(value) {
+  if (value === void 0 || value === null) return void 0;
+  if (typeof value !== "string" || !isRecallDisclosure(value)) {
+    throw new Error(
+      `--disclosure expects one of ${RECALL_DISCLOSURE_LEVELS.join(", ")}; got ${JSON.stringify(value)}`
+    );
+  }
+  return value;
+}
 function parseXrayBudgetFlag(value) {
   if (value === void 0 || value === null) return void 0;
   const parsed = typeof value === "number" ? value : Number(value);
@@ -21,17 +34,20 @@ function parseXrayCliOptions(rawQuery, options) {
   const budget = parseXrayBudgetFlag(options.budget);
   const namespace = typeof options.namespace === "string" && options.namespace.trim().length > 0 ? options.namespace.trim() : void 0;
   const outPath = typeof options.out === "string" && options.out.trim().length > 0 ? options.out.trim() : void 0;
+  const disclosure = parseXrayDisclosureFlag(options.disclosure);
   return {
     query: rawQuery,
     format,
     ...budget !== void 0 ? { budget } : {},
     ...namespace !== void 0 ? { namespace } : {},
-    ...outPath !== void 0 ? { outPath } : {}
+    ...outPath !== void 0 ? { outPath } : {},
+    ...disclosure !== void 0 ? { disclosure } : {}
   };
 }
 
 export {
+  parseXrayDisclosureFlag,
   parseXrayBudgetFlag,
   parseXrayCliOptions
 };
-//# sourceMappingURL=chunk-PVPWZSSI.js.map
+//# sourceMappingURL=chunk-SMA4IMHV.js.map

package/dist/chunk-SMA4IMHV.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/recall-xray-cli.ts"],"sourcesContent":["/**\n * Input-validation helpers for the `remnic xray` CLI command (issue\n * #570, PR 3).\n *\n * Pulled out of `cli.ts` so the validation paths can be unit-tested in\n * isolation — the full CLI handler is hard to exercise without booting\n * an orchestrator.  CLAUDE.md rules 14 + 51 require that `--format`,\n * `--budget`, `--namespace`, and `--out` reject missing-value /\n * unknown / non-positive arguments with a listed-options error, rather\n * than silently defaulting.\n */\n\nimport {\n  parseXrayFormat,\n  type RecallXrayFormat,\n} from \"./recall-xray-renderer.js\";\nimport {\n  isRecallDisclosure,\n  RECALL_DISCLOSURE_LEVELS,\n  type RecallDisclosure,\n} from \"./types.js\";\n\nexport interface ParsedXrayCliOptions {\n  format: RecallXrayFormat;\n  /** Positive integer override, or undefined when not specified. */\n  budget?: number;\n  /** Trimmed namespace, or undefined when not specified. */\n  namespace?: string;\n  /** Trimmed, tilde-unexpanded output path, or undefined when stdout. */\n  outPath?: string;\n  /** Disclosure depth for X-ray telemetry, or undefined when not specified. */\n  disclosure?: RecallDisclosure;\n}\n\n/**\n * Validate and coerce `--disclosure <level>`.  Must be one of the\n * canonical levels; throws a listed-options error otherwise.\n */\nexport function parseXrayDisclosureFlag(value: unknown): RecallDisclosure | undefined {\n  if (value === undefined || value === null) return undefined;\n  if (typeof value !== \"string\" || !isRecallDisclosure(value)) {\n    throw new Error(\n      `--disclosure expects one of ${RECALL_DISCLOSURE_LEVELS.join(\", \")}; got ${JSON.stringify(value)}`,\n    );\n  }\n  return value;\n}\n\n/**\n * Validate and coerce `--budget <chars>`.  Must be a positive integer;\n * throws a listed-options error otherwise.\n */\nexport function parseXrayBudgetFlag(value: unknown): number | undefined {\n  if (value === undefined || value === null) return undefined;\n  const parsed = typeof value === \"number\" ? value : Number(value);\n  if (\n    !Number.isFinite(parsed) ||\n    parsed <= 0 ||\n    !Number.isInteger(parsed)\n  ) {\n    throw new Error(\n      `--budget expects a positive integer; got ${JSON.stringify(value)}`,\n    );\n  }\n  return parsed;\n}\n\n/**\n * Parse and validate the full option bag for `remnic xray`.  Extracted\n * so the CLI handler in `cli.ts` can stay thin and the validation can\n * be unit-tested without booting an orchestrator.\n */\nexport function parseXrayCliOptions(\n  rawQuery: unknown,\n  options: Record<string, unknown>,\n): { query: string } & ParsedXrayCliOptions {\n  if (typeof rawQuery !== \"string\" || rawQuery.trim().length === 0) {\n    throw new Error(\"xray: <query> is required and must be non-empty\");\n  }\n  const format = parseXrayFormat(options.format);\n  const budget = parseXrayBudgetFlag(options.budget);\n  const namespace =\n    typeof options.namespace === \"string\" &&\n    options.namespace.trim().length > 0\n      ? options.namespace.trim()\n      : undefined;\n  const outPath =\n    typeof options.out === \"string\" && options.out.trim().length > 0\n      ? options.out.trim()\n      : undefined;\n  const disclosure = parseXrayDisclosureFlag(options.disclosure);\n  return {\n    query: rawQuery,\n    format,\n    ...(budget !== undefined ? { budget } : {}),\n    ...(namespace !== undefined ? { namespace } : {}),\n    ...(outPath !== undefined ? { outPath } : {}),\n    ...(disclosure !== undefined ? { disclosure } : {}),\n  };\n}\n"],"mappings":";;;;;;;;;AAsCO,SAAS,wBAAwB,OAA8C;AACpF,MAAI,UAAU,UAAa,UAAU,KAAM,QAAO;AAClD,MAAI,OAAO,UAAU,YAAY,CAAC,mBAAmB,KAAK,GAAG;AAC3D,UAAM,IAAI;AAAA,MACR,+BAA+B,yBAAyB,KAAK,IAAI,CAAC,SAAS,KAAK,UAAU,KAAK,CAAC;AAAA,IAClG;AAAA,EACF;AACA,SAAO;AACT;AAMO,SAAS,oBAAoB,OAAoC;AACtE,MAAI,UAAU,UAAa,UAAU,KAAM,QAAO;AAClD,QAAM,SAAS,OAAO,UAAU,WAAW,QAAQ,OAAO,KAAK;AAC/D,MACE,CAAC,OAAO,SAAS,MAAM,KACvB,UAAU,KACV,CAAC,OAAO,UAAU,MAAM,GACxB;AACA,UAAM,IAAI;AAAA,MACR,4CAA4C,KAAK,UAAU,KAAK,CAAC;AAAA,IACnE;AAAA,EACF;AACA,SAAO;AACT;AAOO,SAAS,oBACd,UACA,SAC0C;AAC1C,MAAI,OAAO,aAAa,YAAY,SAAS,KAAK,EAAE,WAAW,GAAG;AAChE,UAAM,IAAI,MAAM,iDAAiD;AAAA,EACnE;AACA,QAAM,SAAS,gBAAgB,QAAQ,MAAM;AAC7C,QAAM,SAAS,oBAAoB,QAAQ,MAAM;AACjD,QAAM,YACJ,OAAO,QAAQ,cAAc,YAC7B,QAAQ,UAAU,KAAK,EAAE,SAAS,IAC9B,QAAQ,UAAU,KAAK,IACvB;AACN,QAAM,UACJ,OAAO,QAAQ,QAAQ,YAAY,QAAQ,IAAI,KAAK,EAAE,SAAS,IAC3D,QAAQ,IAAI,KAAK,IACjB;AACN,QAAM,aAAa,wBAAwB,QAAQ,UAAU;AAC7D,SAAO;AAAA,IACL,OAAO;AAAA,IACP;AAAA,IACA,GAAI,WAAW,SAAY,EAAE,OAAO,IAAI,CAAC;AAAA,IACzC,GAAI,cAAc,SAAY,EAAE,UAAU,IAAI,CAAC;AAAA,IAC/C,GAAI,YAAY,SAAY,EAAE,QAAQ,IAAI,CAAC;AAAA,IAC3C,GAAI,eAAe,SAAY,EAAE,WAAW,IAAI,CAAC;AAAA,EACnD;AACF;","names":[]}

package/dist/{chunk-L7IXWRYE.js → chunk-SS253RXF.js}

@@ -1,6 +1,7 @@
 import {
-  StorageManager
-} from "./chunk-F5VP6YCB.js";
+  StorageManager,
+  normalizeEntityName
+} from "./chunk-DCE6SQLA.js";
 import {
   readEnvVar,
   resolveHomeDir
@@ -73,21 +74,29 @@ function parseBriefingFocus(token) {
   }
   return { type: "topic", value: trimmed };
 }
-function focusToEntityRefSlug(focus) {
-  const sluggedValue = focus.value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
-  return `${focus.type}-${sluggedValue}`;
-}
 function focusMatchesMemory(memory, focus) {
   const needle = focus.value.toLowerCase();
   const entityRef = (memory.frontmatter.entityRef ?? "").toLowerCase();
-  const rawHaystack = [
+  const rawHaystackParts = [
     memory.content,
-    entityRef,
     ...memory.frontmatter.tags ?? []
-  ].join(" ").toLowerCase();
+  ];
+  if (focus.type === "topic" && entityRef) {
+    rawHaystackParts.push(entityRef);
+  }
+  const rawHaystack = rawHaystackParts.join(" ").toLowerCase();
   if (rawHaystack.includes(needle)) return true;
-  const slug = focusToEntityRefSlug(focus);
-  return entityRef.includes(slug);
+  if (!entityRef) return false;
+  const focusCanonical = normalizeEntityName(focus.value, focus.type);
+  let refForNormalize = entityRef;
+  const typeDelimMatch = refForNormalize.match(
+    new RegExp(`^${focus.type}[^a-z0-9]+`, "i")
+  );
+  if (typeDelimMatch) {
+    refForNormalize = refForNormalize.slice(typeDelimMatch[0].length);
+  }
+  const refCanonical = normalizeEntityName(refForNormalize, focus.type);
+  return refCanonical === focusCanonical;
 }
 function focusMatchesEntity(entity, focus) {
   const needle = focus.value.toLowerCase();
@@ -527,7 +536,7 @@ function filterMemoriesByWindow(memories, window) {
   const toMs = window.to.getTime();
   return memories.filter((m) => {
     const status = m.frontmatter.status;
-    if (status === "superseded" || status === "archived" || status === "rejected" || status === "quarantined") {
+    if (status === "superseded" || status === "archived" || status === "rejected" || status === "quarantined" || status === "forgotten") {
       return false;
     }
     const ts = memoryTimestamp(m);
@@ -815,4 +824,4 @@ export {
   resolveBriefingSaveDir,
   briefingFilename
 };
-//# sourceMappingURL=chunk-L7IXWRYE.js.map
+//# sourceMappingURL=chunk-SS253RXF.js.map