@remnic/core 1.1.0 → 1.1.1

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-WBSAYXVI.js → chunk-INXV5JBT.js}

@@ -1,11 +1,14 @@
 import {
   promoteSemanticRuleFromMemory
-} from "./chunk-7ECD5ATE.js";
+} from "./chunk-VDX363PS.js";
 import {
   buildResumeBundleFromState,
   getResumeBundleStatus,
   recordResumeBundle
-} from "./chunk-6LX5ORAS.js";
+} from "./chunk-KUB6JU6H.js";
+import {
+  parseXrayCliOptions
+} from "./chunk-PVPWZSSI.js";
 import {
   listNamespaces,
   runBenchmarkRecall,
@@ -16,7 +19,7 @@ import {
   runOperatorRepair,
   runOperatorSetup,
   verifyNamespaces
-} from "./chunk-3QHL5ABG.js";
+} from "./chunk-B5WXLVDY.js";
 import {
   compareVersions
 } from "./chunk-HL4DB7TO.js";
@@ -25,16 +28,14 @@ import {
 } from "./chunk-ZPKBYX2F.js";
 import {
   RoutingRulesStore,
+  expandTildePath,
   isReplayRole,
   isReplaySource,
   normalizeReplaySessionKey,
   parseIsoOffsetTimestamp,
   parseIsoTimestamp,
   validateReplayTurn
-} from "./chunk-PAORGQRI.js";
-import {
-  searchVerifiedEpisodes
-} from "./chunk-6UJ47TVX.js";
+} from "./chunk-EPQJM2GC.js";
 import {
   getUtilityLearningStatus,
   learnUtilityPromotionWeights
@@ -43,12 +44,15 @@ import {
   getUtilityTelemetryStatus,
   recordUtilityTelemetryEvent
 } from "./chunk-3QKK7QOS.js";
+import {
+  searchVerifiedEpisodes
+} from "./chunk-CUPFXL3J.js";
 import {
   ThreadingManager
 } from "./chunk-JRNQ3RNA.js";
 import {
   searchVerifiedSemanticRules
-} from "./chunk-JIU55F3X.js";
+} from "./chunk-SPI27QT6.js";
 import {
   getWorkProductLedgerStatus,
   recordWorkProductLedgerEntry,
@@ -75,7 +79,7 @@ import {
 } from "./chunk-HMDCOMYU.js";
 import {
   rescoreMemoryImportance
-} from "./chunk-J4IYOZZ5.js";
+} from "./chunk-JXS5PDQ7.js";
 import {
   launchProcess
 } from "./chunk-LK6SGL53.js";
@@ -91,21 +95,21 @@ import {
   runEvalStoredBaselineCiGate,
   validateEvalBenchmarkPack
 } from "./chunk-K6WK37A6.js";
-import {
-  applyCommitmentLedgerLifecycle,
-  getCommitmentLedgerStatus,
-  recordCommitmentLedgerEntry,
-  transitionCommitmentLedgerEntryState
-} from "./chunk-FYIYMQ5N.js";
 import {
   parseConfig
-} from "./chunk-MBJHSA7F.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,23 +118,28 @@ import {
 } from "./chunk-NGAVDO7E.js";
 import {
   EngramAccessHttpServer
-} from "./chunk-37UIFYWO.js";
+} from "./chunk-DFTTJYSO.js";
 import {
   EngramMcpServer
-} from "./chunk-NQEVYWX6.js";
+} from "./chunk-HK3FGIEW.js";
 import {
   resolveHomeDir
 } from "./chunk-MARWOCVP.js";
 import {
   EngramAccessService,
   WorkStorage
-} from "./chunk-MVTHXUBX.js";
+} from "./chunk-GKFXUTJ2.js";
+import {
+  parseRecallExplainFormat,
+  renderRecallExplain,
+  renderXray
+} from "./chunk-ZAIM4TUE.js";
 import {
   listMemoryGovernanceRuns,
   readMemoryGovernanceRunArtifact,
   restoreMemoryGovernanceRun,
   runMemoryGovernance
-} from "./chunk-ITRLGI2T.js";
+} from "./chunk-3OGMS3PE.js";
 import {
   getTrustZoneStoreStatus,
   promoteTrustZoneRecord,
@@ -139,13 +148,20 @@ import {
 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-GV6NLQ4X.js";
+} from "./chunk-F5VP6YCB.js";
+import {
+  MEMORY_LIFECYCLE_EVENT_SORT_ORDER,
+  buildLifecycleEventsForMemory,
+  inferMemoryStatus,
+  sortMemoryLifecycleEvents,
+  toMemoryPathRel
+} from "./chunk-TP4FZJIZ.js";
 import {
   normalizeProjectionPreview,
   normalizeProjectionTags
@@ -162,13 +178,6 @@ import {
   readProjectedGovernanceRecord,
   readProjectedNativeKnowledgeChunks
 } from "./chunk-BOUYNNYD.js";
-import {
-  MEMORY_LIFECYCLE_EVENT_SORT_ORDER,
-  buildLifecycleEventsForMemory,
-  inferMemoryStatus,
-  sortMemoryLifecycleEvents,
-  toMemoryPathRel
-} from "./chunk-TP4FZJIZ.js";
 
 // src/cli.ts
 import path19 from "path";
@@ -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-5TIQBYZR.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;
@@ -7802,15 +7949,24 @@ Semantic consolidation complete. clusters=${result.clustersFound}, consolidated=
       });
       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-GR33PONM.js");
+        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,
-          embeddingLookup: void 0,
+          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: null,
+          fallbackLlm: orchestrator.fastGatewayLlm ?? null,
           namespace: options.namespace
         });
         console.log(`Scan complete in ${result.elapsedMs}ms:`);
@@ -7942,4 +8098,4 @@ export {
   resolveMemoryDirForNamespace,
   registerCli
 };
-//# sourceMappingURL=chunk-WBSAYXVI.js.map
+//# sourceMappingURL=chunk-INXV5JBT.js.map