@remnic/core 1.0.3 → 1.1.1

package/dist/{chunk-AAI7JARD.js → chunk-HMDCOMYU.js}

@@ -2,6 +2,9 @@ import {
   resolveCueAnchorStoreDir,
   validateCueAnchor
 } from "./chunk-C6QPK5GG.js";
+import {
+  throwIfAborted
+} from "./chunk-PVGDJXVK.js";
 import {
   resolveAbstractionNodeStoreDir,
   validateAbstractionNode
@@ -96,13 +99,13 @@ async function readCueAnchors(options) {
   return anchors;
 }
 async function searchHarmonicRetrieval(options) {
-  throwIfAborted(options.abortSignal);
+  throwIfAborted(options.abortSignal, "harmonic retrieval aborted");
   const queryTokens = new Set(normalizeRecallTokens(options.query, ["what", "which"]));
   if (queryTokens.size === 0 || options.maxResults <= 0) return [];
   const nodes = await readAbstractionNodes(options);
   const candidates = /* @__PURE__ */ new Map();
   for (const node of nodes) {
-    throwIfAborted(options.abortSignal);
+    throwIfAborted(options.abortSignal, "harmonic retrieval aborted");
     const { score, matchedFields } = scoreNode(node, queryTokens);
     if (score <= 0) continue;
     candidates.set(node.nodeId, {
@@ -114,11 +117,11 @@ async function searchHarmonicRetrieval(options) {
     });
   }
   if (options.anchorsEnabled) {
-    throwIfAborted(options.abortSignal);
+    throwIfAborted(options.abortSignal, "harmonic retrieval aborted");
     const anchors = await readCueAnchors(options);
     const nodeIndex = new Map(nodes.map((node) => [node.nodeId, node]));
     for (const anchor of anchors) {
-      throwIfAborted(options.abortSignal);
+      throwIfAborted(options.abortSignal, "harmonic retrieval aborted");
       const { score, matchedFields } = scoreAnchor(anchor, queryTokens);
       if (score <= 0) continue;
       for (const nodeRef of anchor.nodeRefs) {
@@ -160,14 +163,8 @@ async function searchHarmonicRetrieval(options) {
     (left, right) => right.score - left.score || right.anchorScore - left.anchorScore || right.node.recordedAt.localeCompare(left.node.recordedAt)
   ).slice(0, options.maxResults);
 }
-function throwIfAborted(signal) {
-  if (!signal?.aborted) return;
-  const err = new Error("harmonic retrieval aborted");
-  Object.defineProperty(err, "name", { value: "AbortError" });
-  throw err;
-}
 
 export {
   searchHarmonicRetrieval
 };
-//# sourceMappingURL=chunk-AAI7JARD.js.map
+//# sourceMappingURL=chunk-HMDCOMYU.js.map

package/dist/chunk-HMDCOMYU.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/harmonic-retrieval.ts"],"sourcesContent":["import path from \"node:path\";\nimport { listJsonFiles, readJsonFile } from \"./json-store.js\";\nimport { throwIfAborted } from \"./abort-error.js\";\nimport {\n  resolveAbstractionNodeStoreDir,\n  validateAbstractionNode,\n  type AbstractionNode,\n} from \"./abstraction-nodes.js\";\nimport {\n  resolveCueAnchorStoreDir,\n  validateCueAnchor,\n  type CueAnchor,\n  type CueAnchorType,\n} from \"./cue-anchors.js\";\nimport { countRecallTokenOverlap, normalizeRecallTokens } from \"./recall-tokenization.js\";\n\nexport interface HarmonicMatchedAnchor {\n  anchorId: string;\n  anchorType: CueAnchorType;\n  anchorValue: string;\n}\n\nexport interface HarmonicRetrievalResult {\n  node: AbstractionNode;\n  score: number;\n  nodeScore: number;\n  anchorScore: number;\n  matchedFields: string[];\n  matchedAnchors: HarmonicMatchedAnchor[];\n}\n\ninterface HarmonicCandidate {\n  node: AbstractionNode;\n  nodeScore: number;\n  anchorScore: number;\n  matchedFields: Set<string>;\n  matchedAnchors: Map<string, HarmonicMatchedAnchor>;\n}\n\nfunction scoreNode(node: AbstractionNode, queryTokens: Set<string>): { score: number; matchedFields: string[] } {\n  const matchedFields: string[] = [];\n  let score = 0;\n\n  const titleMatches = countRecallTokenOverlap(queryTokens, node.title);\n  if (titleMatches > 0) {\n    score += titleMatches * 3;\n    matchedFields.push(\"title\");\n  }\n\n  const summaryMatches = countRecallTokenOverlap(queryTokens, node.summary);\n  if (summaryMatches > 0) {\n    score += summaryMatches * 3;\n    matchedFields.push(\"summary\");\n  }\n\n  const tagMatches = countRecallTokenOverlap(queryTokens, node.tags?.join(\" \"));\n  if (tagMatches > 0) {\n    score += tagMatches * 2;\n    matchedFields.push(\"tags\");\n  }\n\n  const entityMatches = countRecallTokenOverlap(queryTokens, node.entityRefs?.join(\" \"));\n  if (entityMatches > 0) {\n    score += entityMatches * 2;\n    matchedFields.push(\"entityRefs\");\n  }\n\n  const kindMatches = countRecallTokenOverlap(queryTokens, `${node.kind} ${node.abstractionLevel}`);\n  if (kindMatches > 0) {\n    score += kindMatches;\n    matchedFields.push(\"kind\");\n  }\n\n  return { score, matchedFields };\n}\n\nfunction scoreAnchor(anchor: CueAnchor, queryTokens: Set<string>): { score: number; matchedFields: string[] } {\n  const matchedFields: string[] = [];\n  let score = 0;\n\n  const valueMatches = countRecallTokenOverlap(queryTokens, anchor.anchorValue);\n  const normalizedMatches = countRecallTokenOverlap(queryTokens, anchor.normalizedCue);\n  const cueMatches = Math.max(valueMatches, normalizedMatches);\n  if (cueMatches > 0) {\n    score += cueMatches * 4;\n    if (valueMatches > 0) matchedFields.push(\"anchorValue\");\n    if (normalizedMatches > 0) matchedFields.push(\"anchor\");\n  }\n\n  const typeMatches = countRecallTokenOverlap(queryTokens, anchor.anchorType);\n  if (typeMatches > 0) {\n    score += typeMatches;\n    matchedFields.push(\"anchorType\");\n  }\n\n  const tagMatches = countRecallTokenOverlap(queryTokens, anchor.tags?.join(\" \"));\n  if (tagMatches > 0) {\n    score += tagMatches * 2;\n    matchedFields.push(\"anchorTags\");\n  }\n\n  return { score, matchedFields };\n}\n\nasync function readAbstractionNodes(options: {\n  memoryDir: string;\n  abstractionNodeStoreDir?: string;\n}): Promise<AbstractionNode[]> {\n  const rootDir = resolveAbstractionNodeStoreDir(options.memoryDir, options.abstractionNodeStoreDir);\n  const files = await listJsonFiles(path.join(rootDir, \"nodes\"));\n  const nodes: AbstractionNode[] = [];\n  for (const filePath of files) {\n    try {\n      nodes.push(validateAbstractionNode(await readJsonFile(filePath)));\n    } catch {\n      // fail-open: invalid artifacts stay visible via status tooling instead of recall\n    }\n  }\n  return nodes;\n}\n\nasync function readCueAnchors(options: {\n  memoryDir: string;\n  abstractionNodeStoreDir?: string;\n}): Promise<CueAnchor[]> {\n  const abstractionRoot = resolveAbstractionNodeStoreDir(options.memoryDir, options.abstractionNodeStoreDir);\n  const rootDir = resolveCueAnchorStoreDir(abstractionRoot);\n  const files = await listJsonFiles(rootDir);\n  const anchors: CueAnchor[] = [];\n  for (const filePath of files) {\n    try {\n      anchors.push(validateCueAnchor(await readJsonFile(filePath)));\n    } catch {\n      // fail-open: invalid artifacts stay visible via status tooling instead of recall\n    }\n  }\n  return anchors;\n}\n\nexport async function searchHarmonicRetrieval(options: {\n  memoryDir: string;\n  abstractionNodeStoreDir?: string;\n  query: string;\n  maxResults: number;\n  sessionKey?: string;\n  anchorsEnabled: boolean;\n  abortSignal?: AbortSignal;\n}): Promise<HarmonicRetrievalResult[]> {\n  throwIfAborted(options.abortSignal, \"harmonic retrieval aborted\");\n  const queryTokens = new Set(normalizeRecallTokens(options.query, [\"what\", \"which\"]));\n  if (queryTokens.size === 0 || options.maxResults <= 0) return [];\n\n  const nodes = await readAbstractionNodes(options);\n  const candidates = new Map<string, HarmonicCandidate>();\n\n  for (const node of nodes) {\n    throwIfAborted(options.abortSignal, \"harmonic retrieval aborted\");\n    const { score, matchedFields } = scoreNode(node, queryTokens);\n    if (score <= 0) continue;\n    candidates.set(node.nodeId, {\n      node,\n      nodeScore: score,\n      anchorScore: 0,\n      matchedFields: new Set(matchedFields),\n      matchedAnchors: new Map(),\n    });\n  }\n\n  if (options.anchorsEnabled) {\n    throwIfAborted(options.abortSignal, \"harmonic retrieval aborted\");\n    const anchors = await readCueAnchors(options);\n    const nodeIndex = new Map(nodes.map((node) => [node.nodeId, node]));\n    for (const anchor of anchors) {\n      throwIfAborted(options.abortSignal, \"harmonic retrieval aborted\");\n      const { score, matchedFields } = scoreAnchor(anchor, queryTokens);\n      if (score <= 0) continue;\n      for (const nodeRef of anchor.nodeRefs) {\n        const node = nodeIndex.get(nodeRef);\n        if (!node) continue;\n        const existing = candidates.get(nodeRef) ?? {\n          node,\n          nodeScore: 0,\n          anchorScore: 0,\n          matchedFields: new Set<string>(),\n          matchedAnchors: new Map<string, HarmonicMatchedAnchor>(),\n        };\n        existing.anchorScore += score;\n        existing.matchedFields.add(\"anchor\");\n        for (const field of matchedFields) existing.matchedFields.add(field);\n        existing.matchedAnchors.set(anchor.anchorId, {\n          anchorId: anchor.anchorId,\n          anchorType: anchor.anchorType,\n          anchorValue: anchor.anchorValue,\n        });\n        candidates.set(nodeRef, existing);\n      }\n    }\n  }\n\n  return [...candidates.values()]\n    .map((candidate) => {\n      let score = candidate.nodeScore + candidate.anchorScore;\n      if (options.sessionKey && candidate.node.sessionKey === options.sessionKey) score += 0.5;\n      return {\n        node: candidate.node,\n        score,\n        nodeScore: candidate.nodeScore,\n        anchorScore: candidate.anchorScore,\n        matchedFields: [...candidate.matchedFields].sort(),\n        matchedAnchors: [...candidate.matchedAnchors.values()].sort((left, right) =>\n          left.anchorType.localeCompare(right.anchorType) || left.anchorValue.localeCompare(right.anchorValue)\n        ),\n      };\n    })\n    .filter((result) => result.nodeScore > 0 || result.anchorScore > 0)\n    .sort(\n      (left, right) =>\n        right.score - left.score\n        || right.anchorScore - left.anchorScore\n        || right.node.recordedAt.localeCompare(left.node.recordedAt),\n    )\n    .slice(0, options.maxResults);\n}\n"],"mappings":"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","names":[]}

package/dist/chunk-IISBCCWR.js

@@ -0,0 +1,52 @@
+// src/memory-worth.ts
+var MAX_COUNTER = 1e12;
+function classifyCounter(value) {
+  if (value === void 0) return { ok: true, value: 0 };
+  if (typeof value !== "number") return { ok: false };
+  if (!Number.isFinite(value)) return { ok: false };
+  if (value < 0) return { ok: false };
+  if (!Number.isInteger(value)) return { ok: false };
+  if (value > MAX_COUNTER) return { ok: false };
+  return { ok: true, value };
+}
+function parseLastAccessedMs(lastAccessed) {
+  if (!lastAccessed) return null;
+  const parsed = Date.parse(lastAccessed);
+  if (!Number.isFinite(parsed)) return null;
+  return parsed;
+}
+function decayFactor(ageMs, halfLifeMs) {
+  if (typeof halfLifeMs !== "number") return 1;
+  if (!Number.isFinite(halfLifeMs)) return 1;
+  if (halfLifeMs <= 0) return 1;
+  if (ageMs <= 0) return 1;
+  return Math.pow(2, -ageMs / halfLifeMs);
+}
+function computeMemoryWorth(input) {
+  const sClass = classifyCounter(input.mw_success);
+  const fClass = classifyCounter(input.mw_fail);
+  if (!sClass.ok || !fClass.ok) {
+    return { score: 0.5, p_success: 0.5, confidence: 0 };
+  }
+  const rawS = sClass.value;
+  const rawF = fClass.value;
+  const lastAccessedMs = parseLastAccessedMs(input.lastAccessed);
+  const nowMs = input.now.getTime();
+  const nowUsable = Number.isFinite(nowMs);
+  const ageMs = !nowUsable || lastAccessedMs === null ? 0 : Math.max(0, nowMs - lastAccessedMs);
+  const factor = nowUsable ? decayFactor(ageMs, input.halfLifeMs) : 1;
+  const sEff = rawS * factor;
+  const fEff = rawF * factor;
+  const pSuccess = (sEff + 1) / (sEff + fEff + 2);
+  const clamped = Math.max(0, Math.min(1, pSuccess));
+  return {
+    score: clamped,
+    p_success: clamped,
+    confidence: sEff + fEff
+  };
+}
+
+export {
+  computeMemoryWorth
+};
+//# sourceMappingURL=chunk-IISBCCWR.js.map

package/dist/chunk-IISBCCWR.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/memory-worth.ts"],"sourcesContent":["/**\n * Issue #560 PR 2 — Memory Worth scoring (pure helper).\n *\n * Given per-memory outcome counters (`mw_success`, `mw_fail` — added to\n * frontmatter in PR 1), compute a scalar worth score plus interpretable\n * metadata. The score is a Laplace-smoothed success probability with an\n * optional recency decay, and is meant to be used as a multiplier on existing\n * recall scores (PR 4) to sink memories that consistently lead to failed\n * sessions and keep uninstrumented memories at a neutral baseline.\n *\n * Intentional properties:\n *   - Pure function. No I/O, no time-of-import side effects. Testable in\n *     isolation; callers pass `now` so tests don't depend on the wall clock.\n *   - Laplace-smoothed ratio `(s + 1) / (s + f + 2)` ensures a memory with\n *     zero observations scores exactly 0.5 — neither boosted nor penalized.\n *     A single failure on a new memory lands at 1/3, not 0, so one bad\n *     session doesn't permanently exile a fact.\n *   - Recency decay is optional. When a memory hasn't been touched in a long\n *     time, its `p_success` is pulled back toward 0.5 (the prior). Decay is\n *     exponential with an operator-configured half-life so old verdicts\n *     aren't treated as equally informative as fresh ones.\n *   - Corrupt / missing inputs fail safely to the prior. Callers upstream of\n *     this helper (see `storage.parseMemoryWorthCounterField` in PR 1) already\n *     strip negatives and non-integers, but the helper re-validates so it\n *     survives being called directly from tests / ad-hoc tooling.\n *   - Confidence is the effective number of observations (post-decay). PR 4\n *     and PR 5 use it to decide whether the Memory Worth multiplier should\n *     actually be applied vs. left at 1.0 (i.e., \"not enough signal yet\").\n *\n * Out of scope here:\n *   - Mutating frontmatter (PR 3).\n *   - Recall integration / feature flag (PR 4).\n *   - Benchmark & default-flip (PR 5).\n */\n\n/**\n * Input to `computeMemoryWorth`.\n *\n * All fields are optional so a legacy (pre-PR-1) memory can be passed through\n * without upstream guards — it will simply score to the neutral prior.\n */\nexport interface ComputeMemoryWorthInput {\n  /** Count of sessions where this memory was recalled and the outcome was success. */\n  mw_success?: number;\n  /** Count of sessions where this memory was recalled and the outcome was failure. */\n  mw_fail?: number;\n  /**\n   * ISO timestamp of the most recent outcome observation for this memory.\n   * When provided together with `halfLifeMs`, observations decay exponentially\n   * toward the uniform prior as they age. Absent / unparseable timestamp →\n   * decay is skipped and raw counters are used directly.\n   */\n  lastAccessed?: string | null;\n  /**\n   * Current wall-clock reference. Required in the signature (not defaulted to\n   * `Date.now()`) so the function stays pure and tests are deterministic.\n   */\n  now: Date;\n  /**\n   * Half-life for outcome decay, in milliseconds. When `undefined` or `<= 0`,\n   * no decay is applied (raw counts are used). When positive, counter weights\n   * are multiplied by `2^(-age / halfLifeMs)`.\n   */\n  halfLifeMs?: number;\n}\n\n/**\n * Output of `computeMemoryWorth`.\n *\n * `score` is the value recall callers multiply into their base score.\n * `p_success` is the same number pre-clamped — exposed separately so\n * observability surfaces can log the probability distinctly from the\n * multiplier. `confidence` is the effective observation count after decay,\n * useful for UIs that want to render \"strong signal\" vs. \"tentative\".\n */\nexport interface MemoryWorthResult {\n  /**\n   * The Laplace-smoothed success probability, post-decay, clamped to\n   * `[0, 1]`. This is the multiplier PR 4 applies to the base recall score.\n   */\n  score: number;\n  /**\n   * Same as `score` conceptually, surfaced separately so telemetry /\n   * xray surfaces can report probability independently of whatever final\n   * multiplier PR 4 chooses to apply.\n   */\n  p_success: number;\n  /**\n   * Effective observation count (`s_eff + f_eff`). With decay enabled this is\n   * fractional; without decay it equals `mw_success + mw_fail` exactly.\n   * Zero indicates no signal — callers should treat the score as a prior.\n   */\n  confidence: number;\n}\n\n/**\n * Treat fractional or negative counter inputs as zero. Upstream writers in\n * PR 1 already reject these, but this helper is also called from tests and\n * benchmark seeders that build inputs by hand, so we defend here too.\n */\n/**\n * Upper bound for a plausible counter. `Number.MAX_SAFE_INTEGER` would\n * be technically correct but still overflows the sum `sEff + fEff + 2`\n * when both counters are near the max. A more conservative cap also\n * doubles as a sanity check against clearly-corrupt frontmatter (no\n * single memory should have 10B recorded outcomes), and leaves plenty\n * of headroom for the sum.\n */\nconst MAX_COUNTER = 1e12;\n\n/**\n * Classify a counter into `{ok, value}` for the scorer:\n *   - `{ok: true, value}` means the input was absent or a valid non-negative\n *     integer within range. Treated as a normal signal.\n *   - `{ok: false}` means the caller supplied a value but it was corrupt\n *     (negative, NaN, Infinity, non-integer, or absurdly large). The scorer\n *     treats the record as corrupted and collapses BOTH counters to the\n *     prior — a partial-corruption record (e.g. `mw_success: 10` with\n *     `mw_fail: NaN`) must not be read as strong evidence.\n */\nfunction classifyCounter(value: number | undefined): { ok: true; value: number } | { ok: false } {\n  // Absent counter is a legitimate \"no data yet\" signal, not corruption.\n  if (value === undefined) return { ok: true, value: 0 };\n  if (typeof value !== \"number\") return { ok: false };\n  if (!Number.isFinite(value)) return { ok: false };\n  if (value < 0) return { ok: false };\n  // Non-integer counters are refused outright (not floored). Fractional\n  // counters can only arise from hand-edited frontmatter or a mis-seeded\n  // bench fixture — the PR 1 serializer rejects them on write. Treating\n  // `1.9` as `1` would give obviously-corrupt data non-zero confidence and\n  // shift the score away from the neutral prior.\n  if (!Number.isInteger(value)) return { ok: false };\n  // Overflow guard. `mw_success: 1e308` (or anything past `MAX_COUNTER`)\n  // would let `sEff + fEff + 2` overflow to `Infinity` and drive the\n  // computed score to 0 for symmetric counts — exactly the opposite of\n  // the neutral-prior fail-safe contract.\n  if (value > MAX_COUNTER) return { ok: false };\n  return { ok: true, value };\n}\n\n/**\n * Parse `lastAccessed` into a millisecond timestamp. Any parse failure\n * collapses to `null`, which disables decay rather than throwing.\n */\nfunction parseLastAccessedMs(lastAccessed: string | null | undefined): number | null {\n  if (!lastAccessed) return null;\n  const parsed = Date.parse(lastAccessed);\n  if (!Number.isFinite(parsed)) return null;\n  return parsed;\n}\n\n/**\n * Compute the decay multiplier for an observation of age `ageMs` given a\n * `halfLifeMs`. Returns `1` when decay is disabled or age is non-positive\n * (can happen if a test seeds `lastAccessed` slightly in the future).\n */\nfunction decayFactor(ageMs: number, halfLifeMs: number | undefined): number {\n  if (typeof halfLifeMs !== \"number\") return 1;\n  if (!Number.isFinite(halfLifeMs)) return 1;\n  if (halfLifeMs <= 0) return 1;\n  if (ageMs <= 0) return 1;\n  return Math.pow(2, -ageMs / halfLifeMs);\n}\n\n/**\n * Score a single memory's worth based on outcome history.\n *\n * Returns the neutral prior (`0.5`, `confidence=0`) for uninstrumented\n * memories so the caller can treat \"no data\" and \"data says 50/50\"\n * identically — neither should be penalized.\n */\nexport function computeMemoryWorth(input: ComputeMemoryWorthInput): MemoryWorthResult {\n  const sClass = classifyCounter(input.mw_success);\n  const fClass = classifyCounter(input.mw_fail);\n  // If EITHER counter is corrupt, fail the whole record to the prior. A\n  // partially-corrupt record (e.g. `mw_success: 10` with `mw_fail: NaN`)\n  // would otherwise read as strong positive evidence — the exact opposite\n  // of the documented \"corrupt inputs fail safely\" contract.\n  if (!sClass.ok || !fClass.ok) {\n    return { score: 0.5, p_success: 0.5, confidence: 0 };\n  }\n  const rawS = sClass.value;\n  const rawF = fClass.value;\n\n  const lastAccessedMs = parseLastAccessedMs(input.lastAccessed);\n  const nowMs = input.now.getTime();\n  // An invalid `now` Date (`new Date(\"bad\")`) would otherwise propagate\n  // NaN through `ageMs` → `decayFactor` → score and poison any downstream\n  // sort that treats NaN as \"less than everything\". Skip decay in that\n  // case — the raw counters are still well-defined.\n  const nowUsable = Number.isFinite(nowMs);\n  const ageMs =\n    !nowUsable || lastAccessedMs === null ? 0 : Math.max(0, nowMs - lastAccessedMs);\n  const factor = nowUsable ? decayFactor(ageMs, input.halfLifeMs) : 1;\n\n  const sEff = rawS * factor;\n  const fEff = rawF * factor;\n\n  // Laplace smoothing: Beta(1,1) prior ⇒ (s+1) / (s+f+2).\n  // This is equivalent to adding one imaginary success + one imaginary\n  // failure before computing the ratio, and guarantees a finite non-zero\n  // result even when both counters are 0.\n  const pSuccess = (sEff + 1) / (sEff + fEff + 2);\n\n  // Clamp defensively — floating-point noise can push (s+1)/(s+f+2) a hair\n  // outside [0, 1] when `factor` is very small, and the callers (recall\n  // score multiplication) expect a well-formed probability.\n  const clamped = Math.max(0, Math.min(1, pSuccess));\n\n  return {\n    score: clamped,\n    p_success: clamped,\n    confidence: sEff + fEff,\n  };\n}\n"],"mappings":";AA4GA,IAAM,cAAc;AAYpB,SAAS,gBAAgB,OAAwE;AAE/F,MAAI,UAAU,OAAW,QAAO,EAAE,IAAI,MAAM,OAAO,EAAE;AACrD,MAAI,OAAO,UAAU,SAAU,QAAO,EAAE,IAAI,MAAM;AAClD,MAAI,CAAC,OAAO,SAAS,KAAK,EAAG,QAAO,EAAE,IAAI,MAAM;AAChD,MAAI,QAAQ,EAAG,QAAO,EAAE,IAAI,MAAM;AAMlC,MAAI,CAAC,OAAO,UAAU,KAAK,EAAG,QAAO,EAAE,IAAI,MAAM;AAKjD,MAAI,QAAQ,YAAa,QAAO,EAAE,IAAI,MAAM;AAC5C,SAAO,EAAE,IAAI,MAAM,MAAM;AAC3B;AAMA,SAAS,oBAAoB,cAAwD;AACnF,MAAI,CAAC,aAAc,QAAO;AAC1B,QAAM,SAAS,KAAK,MAAM,YAAY;AACtC,MAAI,CAAC,OAAO,SAAS,MAAM,EAAG,QAAO;AACrC,SAAO;AACT;AAOA,SAAS,YAAY,OAAe,YAAwC;AAC1E,MAAI,OAAO,eAAe,SAAU,QAAO;AAC3C,MAAI,CAAC,OAAO,SAAS,UAAU,EAAG,QAAO;AACzC,MAAI,cAAc,EAAG,QAAO;AAC5B,MAAI,SAAS,EAAG,QAAO;AACvB,SAAO,KAAK,IAAI,GAAG,CAAC,QAAQ,UAAU;AACxC;AASO,SAAS,mBAAmB,OAAmD;AACpF,QAAM,SAAS,gBAAgB,MAAM,UAAU;AAC/C,QAAM,SAAS,gBAAgB,MAAM,OAAO;AAK5C,MAAI,CAAC,OAAO,MAAM,CAAC,OAAO,IAAI;AAC5B,WAAO,EAAE,OAAO,KAAK,WAAW,KAAK,YAAY,EAAE;AAAA,EACrD;AACA,QAAM,OAAO,OAAO;AACpB,QAAM,OAAO,OAAO;AAEpB,QAAM,iBAAiB,oBAAoB,MAAM,YAAY;AAC7D,QAAM,QAAQ,MAAM,IAAI,QAAQ;AAKhC,QAAM,YAAY,OAAO,SAAS,KAAK;AACvC,QAAM,QACJ,CAAC,aAAa,mBAAmB,OAAO,IAAI,KAAK,IAAI,GAAG,QAAQ,cAAc;AAChF,QAAM,SAAS,YAAY,YAAY,OAAO,MAAM,UAAU,IAAI;AAElE,QAAM,OAAO,OAAO;AACpB,QAAM,OAAO,OAAO;AAMpB,QAAM,YAAY,OAAO,MAAM,OAAO,OAAO;AAK7C,QAAM,UAAU,KAAK,IAAI,GAAG,KAAK,IAAI,GAAG,QAAQ,CAAC;AAEjD,SAAO;AAAA,IACL,OAAO;AAAA,IACP,WAAW;AAAA,IACX,YAAY,OAAO;AAAA,EACrB;AACF;","names":[]}

package/dist/{chunk-YFYL2SIJ.js → chunk-INXV5JBT.js}

@@ -1,11 +1,14 @@
 import {
   promoteSemanticRuleFromMemory
-} from "./chunk-KWP7T3DP.js";
+} from "./chunk-VDX363PS.js";
 import {
   buildResumeBundleFromState,
   getResumeBundleStatus,
   recordResumeBundle
-} from "./chunk-AYPYCLR7.js";
+} from "./chunk-KUB6JU6H.js";
+import {
+  parseXrayCliOptions
+} from "./chunk-PVPWZSSI.js";
 import {
   listNamespaces,
   runBenchmarkRecall,
@@ -16,7 +19,7 @@ import {
   runOperatorRepair,
   runOperatorSetup,
   verifyNamespaces
-} from "./chunk-X4WESCKA.js";
+} from "./chunk-B5WXLVDY.js";
 import {
   compareVersions
 } from "./chunk-HL4DB7TO.js";
@@ -25,13 +28,14 @@ import {
 } from "./chunk-ZPKBYX2F.js";
 import {
   RoutingRulesStore,
+  expandTildePath,
   isReplayRole,
   isReplaySource,
   normalizeReplaySessionKey,
   parseIsoOffsetTimestamp,
   parseIsoTimestamp,
   validateReplayTurn
-} from "./chunk-PAORGQRI.js";
+} from "./chunk-EPQJM2GC.js";
 import {
   getUtilityLearningStatus,
   learnUtilityPromotionWeights
@@ -42,25 +46,18 @@ import {
 } from "./chunk-3QKK7QOS.js";
 import {
   searchVerifiedEpisodes
-} from "./chunk-GJQPH5G3.js";
+} from "./chunk-CUPFXL3J.js";
 import {
   ThreadingManager
 } from "./chunk-JRNQ3RNA.js";
 import {
   searchVerifiedSemanticRules
-} from "./chunk-MYQWXITD.js";
+} from "./chunk-SPI27QT6.js";
 import {
   getWorkProductLedgerStatus,
   recordWorkProductLedgerEntry,
   searchWorkProductLedgerEntries
 } from "./chunk-CULXMQJH.js";
-import {
-  readRuntimePolicySnapshot,
-  sanitizeRuntimePolicyValues
-} from "./chunk-EABGC2TL.js";
-import {
-  getObjectiveStateStoreStatus
-} from "./chunk-LOBRX7VD.js";
 import {
   analyzeSessionIntegrity,
   applySessionRepair,
@@ -71,11 +68,21 @@ import {
   PLUGIN_ID
 } from "./chunk-U66YHYC7.js";
 import {
-  rescoreMemoryImportance
-} from "./chunk-J4IYOZZ5.js";
+  readRuntimePolicySnapshot,
+  sanitizeRuntimePolicyValues
+} from "./chunk-EABGC2TL.js";
+import {
+  getObjectiveStateStoreStatus
+} from "./chunk-LOBRX7VD.js";
 import {
   searchHarmonicRetrieval
-} from "./chunk-AAI7JARD.js";
+} from "./chunk-HMDCOMYU.js";
+import {
+  rescoreMemoryImportance
+} from "./chunk-JXS5PDQ7.js";
+import {
+  launchProcess
+} from "./chunk-LK6SGL53.js";
 import {
   loadPersistedNativeKnowledgeChunks
 } from "./chunk-7SEAZFFB.js";
@@ -88,24 +95,21 @@ import {
   runEvalStoredBaselineCiGate,
   validateEvalBenchmarkPack
 } from "./chunk-K6WK37A6.js";
-import {
-  launchProcess
-} from "./chunk-LK6SGL53.js";
-import {
-  applyCommitmentLedgerLifecycle,
-  getCommitmentLedgerStatus,
-  recordCommitmentLedgerEntry,
-  transitionCommitmentLedgerEntryState
-} from "./chunk-FYIYMQ5N.js";
 import {
   parseConfig
-} from "./chunk-OJFGVJS6.js";
+} from "./chunk-BK2EFTE2.js";
 import {
   getCueAnchorStoreStatus
 } from "./chunk-C6QPK5GG.js";
 import {
   analyzeGraphHealth
 } from "./chunk-C2EFFULQ.js";
+import {
+  applyCommitmentLedgerLifecycle,
+  getCommitmentLedgerStatus,
+  recordCommitmentLedgerEntry,
+  transitionCommitmentLedgerEntryState
+} from "./chunk-FYIYMQ5N.js";
 import {
   chunkContent
 } from "./chunk-4WMCPJWX.js";
@@ -114,38 +118,43 @@ import {
 } from "./chunk-NGAVDO7E.js";
 import {
   EngramAccessHttpServer
-} from "./chunk-PMB3WGDL.js";
+} from "./chunk-DFTTJYSO.js";
 import {
   EngramMcpServer
-} from "./chunk-NSB3WSYS.js";
+} from "./chunk-HK3FGIEW.js";
 import {
   resolveHomeDir
 } from "./chunk-MARWOCVP.js";
 import {
   EngramAccessService,
   WorkStorage
-} from "./chunk-V7XCAHIB.js";
+} from "./chunk-GKFXUTJ2.js";
 import {
-  getTrustZoneStoreStatus,
-  promoteTrustZoneRecord,
-  seedTrustZoneDemoDataset
-} from "./chunk-EQINRHYR.js";
+  parseRecallExplainFormat,
+  renderRecallExplain,
+  renderXray
+} from "./chunk-ZAIM4TUE.js";
 import {
   listMemoryGovernanceRuns,
   readMemoryGovernanceRunArtifact,
   restoreMemoryGovernanceRun,
   runMemoryGovernance
-} from "./chunk-POBPGDWI.js";
+} from "./chunk-3OGMS3PE.js";
+import {
+  getTrustZoneStoreStatus,
+  promoteTrustZoneRecord,
+  seedTrustZoneDemoDataset
+} from "./chunk-EQINRHYR.js";
 import {
   selectRouteRule,
   validateRouteTarget
-} from "./chunk-QNJMBKFK.js";
+} from "./chunk-2LGMW3DJ.js";
 import {
   getCausalTrajectoryStoreStatus
-} from "./chunk-4NRAJUDS.js";
+} from "./chunk-RBBWYEFJ.js";
 import {
   StorageManager
-} from "./chunk-POMSFKTB.js";
+} from "./chunk-F5VP6YCB.js";
 import {
   MEMORY_LIFECYCLE_EVENT_SORT_ORDER,
   buildLifecycleEventsForMemory,
@@ -3785,13 +3794,6 @@ function isWorkTaskPriority(value) {
 function isWorkProjectStatus(value) {
   return value === "active" || value === "on_hold" || value === "completed" || value === "archived";
 }
-function expandTildePath(p) {
-  if (p === "~") return resolveHomeDir();
-  if (p.startsWith("~/") || p.startsWith("~\\")) {
-    return path19.join(resolveHomeDir(), p.slice(2));
-  }
-  return p;
-}
 async function runTrainingExportCliCommand(opts) {
   const expandedMemoryDir = expandTildePath(opts.memoryDir);
   const expandedOutput = expandTildePath(opts.output);
@@ -4121,7 +4123,7 @@ async function runSemanticRulePromoteCliCommand(options) {
   });
 }
 async function runCompoundingPromoteCliCommand(options) {
-  const { CompoundingEngine } = await import("./engine-X7X3AAG3.js");
+  const { CompoundingEngine } = await import("./engine-F3GOXGE5.js");
   const config = parseConfig({
     memoryDir: options.memoryDir,
     qmdEnabled: false,
@@ -5531,6 +5533,68 @@ function registerCli(api, orchestrator) {
           }
         }
       });
+      cmd.command("judge-stats").description(
+        "Show extraction-judge verdict stats from the observation ledger"
+      ).option("--since <iso>", "Start timestamp (inclusive, ISO-8601)").option("--until <iso>", "End timestamp (exclusive, ISO-8601)").option("--json", "Emit machine-readable JSON only").action(async (...args) => {
+        const options = args[0] ?? {};
+        const sinceRaw = typeof options.since === "string" ? options.since : void 0;
+        const untilRaw = typeof options.until === "string" ? options.until : void 0;
+        const sinceMs = sinceRaw ? Date.parse(sinceRaw) : void 0;
+        const untilMs = untilRaw ? Date.parse(untilRaw) : void 0;
+        if (sinceRaw && !Number.isFinite(sinceMs)) {
+          throw new Error(
+            `Invalid --since value: ${sinceRaw}. Use ISO-8601, e.g. 2026-04-01T00:00:00Z`
+          );
+        }
+        if (untilRaw && !Number.isFinite(untilMs)) {
+          throw new Error(
+            `Invalid --until value: ${untilRaw}. Use ISO-8601, e.g. 2026-04-15T00:00:00Z`
+          );
+        }
+        const { readJudgeVerdictStats } = await import("./extraction-judge-telemetry.js");
+        const stats = await readJudgeVerdictStats(
+          orchestrator.config.memoryDir,
+          {
+            ...typeof sinceMs === "number" && Number.isFinite(sinceMs) ? { sinceMs } : {},
+            ...typeof untilMs === "number" && Number.isFinite(untilMs) ? { untilMs } : {}
+          }
+        );
+        if (options.json === true) {
+          console.log(JSON.stringify(stats, null, 2));
+          return;
+        }
+        console.log("=== Extraction Judge Verdict Stats ===\n");
+        console.log(`Total verdicts: ${stats.total}`);
+        if (stats.total === 0) {
+          if (!orchestrator.config.extractionJudgeTelemetryEnabled) {
+            console.log(
+              "\nNote: extractionJudgeTelemetryEnabled is OFF. Enable it in plugin config to collect verdict telemetry."
+            );
+          }
+          return;
+        }
+        console.log(
+          `  accept: ${stats.accept} (${(stats.accept / stats.total * 100).toFixed(1)}%)`
+        );
+        console.log(
+          `  reject: ${stats.reject} (${(stats.reject / stats.total * 100).toFixed(1)}%)`
+        );
+        console.log(
+          `  defer:  ${stats.defer} (${(stats.deferRate * 100).toFixed(1)}%)`
+        );
+        if (stats.deferCapTriggered > 0) {
+          console.log(
+            `    of which ${stats.deferCapTriggered} cap-rejected (defer \u2192 reject)`
+          );
+        }
+        console.log(`  mean elapsed: ${stats.meanElapsedMs.toFixed(1)} ms`);
+        if (stats.firstTs && stats.lastTs) {
+          console.log(`  window: ${stats.firstTs} \u2026 ${stats.lastTs}`);
+        }
+        if (stats.malformed > 0) {
+          console.log(`  malformed rows skipped: ${stats.malformed}`);
+        }
+      });
       cmd.command("setup").description("Validate config, scaffold directories, and print first-run next steps").option("--install-capture-instructions", "Create workspace MEMORY.md when explicit capture is enabled and missing").option("--preview-capture-instructions", "Print the managed explicit-capture instruction snippet without writing files").option("--remove-capture-instructions", "Remove the managed explicit-capture instruction snippet from MEMORY.md").option("--json", "Emit machine-readable JSON only").action(async (...args) => {
         const options = args[0] ?? {};
         const captureInstructionsMode = options.removeCaptureInstructions === true ? "remove" : options.previewCaptureInstructions === true ? "preview" : options.installCaptureInstructions === true ? "install" : void 0;
@@ -5950,6 +6014,59 @@ function registerCli(api, orchestrator) {
         }
         if (!reportHasMachineReadableOutput(options)) console.log("OK");
       });
+      cmd.command("recall-explain").description(
+        "Show tier explain for the most recent recall (or a specific session)"
+      ).option(
+        "--session <key>",
+        "Session key to look up; omit to use the most recent snapshot"
+      ).option("--format <fmt>", "Output format: text (default) or json", "text").action(async (...args) => {
+        const options = args[0] ?? {};
+        const format = parseRecallExplainFormat(options.format);
+        await orchestrator.lastRecall.load();
+        const sessionKey = typeof options.session === "string" && options.session.length > 0 ? options.session : void 0;
+        let snapshot = null;
+        try {
+          snapshot = sessionKey ? orchestrator.lastRecall.get(sessionKey) : orchestrator.lastRecall.getMostRecent();
+        } catch {
+          snapshot = null;
+        }
+        console.log(renderRecallExplain(snapshot, format));
+      });
+      cmd.command("xray").description(
+        "Run a recall with X-ray capture and print the unified snapshot (tier + audit + MMR + filters).  Part of #570."
+      ).argument("<query>", "Query to recall against").option(
+        "--format <fmt>",
+        "Output format: text (default), markdown, or json",
+        "text"
+      ).option(
+        "--budget <chars>",
+        "Override recall character budget for this call (positive integer)"
+      ).option(
+        "--namespace <ns>",
+        "Namespace to scope the recall to (defaults to configured namespace)"
+      ).option(
+        "--out <path>",
+        "Write the rendered snapshot to a file instead of stdout"
+      ).action(async (...args) => {
+        const parsed = parseXrayCliOptions(
+          args[0],
+          args[1] ?? {}
+        );
+        const xrayService = new EngramAccessService(orchestrator);
+        const response = await xrayService.recallXray({
+          query: parsed.query,
+          ...parsed.namespace ? { namespace: parsed.namespace } : {},
+          ...parsed.budget !== void 0 ? { budget: parsed.budget } : {}
+        });
+        const snapshot = response.snapshotFound ? response.snapshot ?? null : null;
+        const rendered = renderXray(snapshot, parsed.format);
+        if (parsed.outPath) {
+          const { writeFile: fsWriteFile } = await import("fs/promises");
+          await fsWriteFile(expandTildePath(parsed.outPath), rendered, "utf8");
+        } else {
+          console.log(rendered);
+        }
+      });
       cmd.command("benchmark-validate").description("Validate a benchmark manifest file or pack directory without importing it").argument("<path>", "Path to a benchmark manifest JSON file or a directory with manifest.json").action(async (...args) => {
         const inputPath = args[0];
         const summary = await runBenchmarkValidateCliCommand({
@@ -7336,6 +7453,36 @@ Clusters found: ${result.clustersFound}`);
 Semantic consolidation complete. clusters=${result.clustersFound}, consolidated=${result.memoriesConsolidated}, archived=${result.memoriesArchived}, errors=${result.errors}`
         );
       });
+      cmd.command("consolidate-undo <target>").description(
+        "Undo a consolidation: restore source memories from their derived_from snapshots and archive the target"
+      ).option("--dry-run", "Show the restore plan without modifying files").action(async (...args) => {
+        const rawTarget = typeof args[0] === "string" ? args[0] : "";
+        const options = args[1] ?? {};
+        const dryRun = options.dryRun === true;
+        if (!rawTarget) {
+          console.error("consolidate-undo: missing <target> argument");
+          process.exitCode = 1;
+          return;
+        }
+        const expandedTarget = expandTildePath(rawTarget);
+        const targetPath = path19.isAbsolute(expandedTarget) ? expandedTarget : path19.join(orchestrator.config.memoryDir, expandedTarget);
+        const { runConsolidationUndo, formatConsolidationUndoResult } = await import("./consolidation-undo.js");
+        const result = await runConsolidationUndo({
+          storage: orchestrator.storage,
+          memoryDir: orchestrator.config.memoryDir,
+          targetPath,
+          versioning: {
+            enabled: orchestrator.config.versioningEnabled,
+            maxVersionsPerPage: orchestrator.config.versioningMaxPerPage,
+            sidecarDir: orchestrator.config.versioningSidecarDir
+          },
+          dryRun
+        });
+        console.log(formatConsolidationUndoResult(result));
+        if (result.error) {
+          process.exitCode = 1;
+        }
+      });
       cmd.command("questions").description("List open questions from memory extraction").option("-a, --all", "Show all questions including resolved").action(async (...args) => {
         const options = args[0] ?? {};
         const showAll = options.all === true;
@@ -7732,6 +7879,103 @@ Semantic consolidation complete. clusters=${result.clustersFound}, consolidated=
         }
         console.log(orchestrator.summarizer.formatForRecall(summaries, summaries.length));
       });
+      const reviewCmd = cmd.command("review").description("Manage contradiction review queue");
+      reviewCmd.command("list").description("List contradiction review items").option("--filter <type>", "Filter: all, unresolved, contradicts, independent, duplicates, needs-user", "unresolved").option("--namespace <ns>", "Filter by namespace").option("--limit <n>", "Max items (default 50)", "50").action(async (...args) => {
+        const options = args[0] ?? {};
+        const filter = options.filter ?? "unresolved";
+        const validFilters = ["all", "unresolved", "contradicts", "independent", "duplicates", "needs-user"];
+        if (!validFilters.includes(filter)) {
+          console.error(`Invalid filter: ${filter}. Must be one of: ${validFilters.join(", ")}`);
+          process.exit(1);
+        }
+        const limit = parseInt(options.limit ?? "50", 10);
+        const { listPairs } = await import("./contradiction-review-WIUBAR52.js");
+        const result = listPairs(orchestrator.config.memoryDir, {
+          filter,
+          namespace: options.namespace,
+          limit: Number.isFinite(limit) ? limit : 50
+        });
+        if (result.pairs.length === 0) {
+          console.log("No review items found.");
+          return;
+        }
+        console.log(`Found ${result.total} item(s) (${result.durationMs}ms):
+`);
+        for (const pair of result.pairs) {
+          console.log(`  [${pair.verdict}] ${pair.pairId}`);
+          console.log(`    Memories: ${pair.memoryIds.join(", ")}`);
+          console.log(`    Rationale: ${pair.rationale}`);
+          console.log(`    Confidence: ${pair.confidence.toFixed(2)}`);
+          if (pair.resolution) console.log(`    Resolution: ${pair.resolution}`);
+          console.log();
+        }
+      });
+      reviewCmd.command("show <pairId>").description("Show details of a contradiction pair").action(async (...args) => {
+        const pairId = typeof args[0] === "string" ? args[0] : "";
+        if (!pairId) {
+          console.error("pairId is required");
+          process.exit(1);
+        }
+        const { readPair } = await import("./contradiction-review-WIUBAR52.js");
+        const pair = readPair(orchestrator.config.memoryDir, pairId);
+        if (!pair) {
+          console.error(`Pair ${pairId} not found.`);
+          process.exit(1);
+        }
+        console.log(JSON.stringify(pair, null, 2));
+      });
+      reviewCmd.command("resolve <pairId>").description("Resolve a contradiction pair").requiredOption("--verb <verb>", "Resolution verb: keep-a, keep-b, merge, both-valid, needs-more-context").action(async (...args) => {
+        const pairId = typeof args[0] === "string" ? args[0] : "";
+        const cmdOpts = args[1] ?? {};
+        if (!pairId) {
+          console.error("pairId is required");
+          process.exit(1);
+        }
+        const verb = cmdOpts.verb;
+        if (!verb) {
+          console.error("--verb is required. Must be one of: keep-a, keep-b, merge, both-valid, needs-more-context");
+          process.exit(1);
+        }
+        const { isValidResolutionVerb, executeResolution } = await import("./resolution-QBTDHTG7.js");
+        if (!isValidResolutionVerb(verb)) {
+          console.error(`Invalid verb: ${verb}. Must be one of: keep-a, keep-b, merge, both-valid, needs-more-context`);
+          process.exit(1);
+        }
+        const result = await executeResolution(orchestrator.config.memoryDir, orchestrator.storage, pairId, verb);
+        console.log(result.message);
+        if (result.affectedIds.length > 0) {
+          console.log(`Affected: ${result.affectedIds.join(", ")}`);
+        }
+      });
+      reviewCmd.command("scan").description("Run an on-demand contradiction scan").option("--namespace <ns>", "Namespace to scan").action(async (...args) => {
+        const options = args[0] ?? {};
+        const { runContradictionScan } = await import("./contradiction-scan-E3GJTI4F.js");
+        console.log("Running contradiction scan...");
+        const result = await runContradictionScan({
+          storage: orchestrator.storage,
+          config: orchestrator.config,
+          memoryDir: orchestrator.config.memoryDir,
+          embeddingLookupFactory: (storage) => {
+            if (!orchestrator.config.embeddingFallbackEnabled) return void 0;
+            return async (content, limit) => {
+              try {
+                return await orchestrator.semanticDedupLookup(content, limit, storage);
+              } catch {
+                return [];
+              }
+            };
+          },
+          localLlm: orchestrator.localLlm ?? null,
+          fallbackLlm: orchestrator.fastGatewayLlm ?? null,
+          namespace: options.namespace
+        });
+        console.log(`Scan complete in ${result.elapsedMs}ms:`);
+        console.log(`  Scanned: ${result.scanned} memories`);
+        console.log(`  Candidates: ${result.candidates} pairs`);
+        console.log(`  Judged: ${result.judged}`);
+        console.log(`  Queued: ${result.queued}`);
+        console.log(`  Cooled down: ${result.cooledDown}`);
+      });
     },
     { commands: ["engram"] }
   );
@@ -7854,4 +8098,4 @@ export {
   resolveMemoryDirForNamespace,
   registerCli
 };
-//# sourceMappingURL=chunk-YFYL2SIJ.js.map
+//# sourceMappingURL=chunk-INXV5JBT.js.map