@remnic/core 1.1.0 → 1.1.1

package/dist/{port-C1GZFv8h.d.ts → port-BADbLZU5.d.ts}

@@ -31,8 +31,8 @@ interface SearchBackend {
     bm25Search(query: string, collection?: string, maxResults?: number, execution?: SearchExecutionOptions): Promise<SearchResult[]>;
     vectorSearch(query: string, collection?: string, maxResults?: number, execution?: SearchExecutionOptions): Promise<SearchResult[]>;
     hybridSearch(query: string, collection?: string, maxResults?: number, execution?: SearchExecutionOptions): Promise<SearchResult[]>;
-    update(): Promise<void>;
-    updateCollection(collection: string): Promise<void>;
+    update(execution?: SearchExecutionOptions): Promise<void>;
+    updateCollection(collection: string, execution?: SearchExecutionOptions): Promise<void>;
     embed(): Promise<void>;
     embedCollection(collection: string): Promise<void>;
     ensureCollection(memoryDir: string): Promise<"present" | "missing" | "unknown" | "skipped">;

package/dist/qmd-recall-cache.d.ts

@@ -1,5 +1,5 @@
 import { RecallPlanMode } from './types.js';
-import { a as SearchQueryOptions } from './port-C1GZFv8h.js';
+import { a as SearchQueryOptions } from './port-BADbLZU5.js';
 
 type QmdRecallCacheSource = "fresh" | "stale";
 interface QmdRecallCacheHit<T> {

package/dist/qmd.d.ts

@@ -1,5 +1,5 @@
 import { QmdSearchResult, QmdSearchExplain } from './types.js';
-import { S as SearchBackend, a as SearchQueryOptions, b as SearchExecutionOptions } from './port-C1GZFv8h.js';
+import { S as SearchBackend, a as SearchQueryOptions, b as SearchExecutionOptions } from './port-BADbLZU5.js';
 
 interface QmdClientOptions {
     slowLog?: {
@@ -32,6 +32,7 @@ declare class QmdClient implements SearchBackend {
     private lastCliProbeError;
     private daemonSession;
     private daemonAvailable;
+    private daemonSessionPath;
     private lastDaemonCheckAtMs;
     private readonly daemonEnabled;
     private readonly daemonRecheckIntervalMs;
@@ -50,6 +51,7 @@ declare class QmdClient implements SearchBackend {
     /** Debug string for troubleshooting availability issues. */
     debugStatus(): string;
     isDaemonMode(): boolean;
+    dispose(): void;
     /**
      * Record a daemon search success — resets the transient failure counter.
      */
@@ -97,8 +99,8 @@ declare class QmdClient implements SearchBackend {
     private bm25SearchViaSubprocess;
     private vsearchViaSubprocess;
     private searchGlobalViaSubprocess;
-    update(signal?: AbortSignal): Promise<void>;
-    updateCollection(collection: string): Promise<void>;
+    update(execution?: SearchExecutionOptions): Promise<void>;
+    updateCollection(collection: string, execution?: SearchExecutionOptions): Promise<void>;
     private runUpdateForCollection;
     embed(): Promise<void>;
     embedCollection(collection: string): Promise<void>;

package/dist/qmd.js

@@ -1,7 +1,7 @@
 import {
   QmdClient,
   parseQmdExplain
-} from "./chunk-BLKTA7MM.js";
+} from "./chunk-YNQKWQT4.js";
 import "./chunk-LK6SGL53.js";
 import "./chunk-PVGDJXVK.js";
 import "./chunk-MARWOCVP.js";

package/dist/reasoning-trace-recall.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Reasoning-trace recall boost (issue #564 PR 3).
+ *
+ * Pure helpers for:
+ * - detecting whether a user query looks like a problem-solving ask
+ *   ("how do I…", "step by step", etc.)
+ * - boosting stored reasoning_trace memories within a result list when that
+ *   condition matches.
+ *
+ * Callers gate these helpers behind the `recallReasoningTraceBoostEnabled`
+ * config flag (default false); the helpers themselves are also no-ops when
+ * `enabled` is false so they can be safely chained into the recall pipeline.
+ */
+/**
+ * Heuristic: does the incoming query read like the user wants a stored
+ * solution chain (reasoning trace)?
+ *
+ * Positive signals:
+ *  - starts with "how do I", "how can I", "how would I", "how to"
+ *  - contains "step by step", "walk me through", "work through"
+ *  - contains "reasoning", "think through", "figure out", "debug"
+ *  - explicitly mentions "trace" or "chain of thought"
+ *
+ * This is intentionally conservative — the boost is OFF by default, so false
+ * negatives are cheap, but false positives would shift retrieval for ordinary
+ * queries on an opt-in install.
+ */
+declare function looksLikeProblemSolvingQuery(query: string): boolean;
+/**
+ * Minimal shape the boost helper needs to read from a recall result. Matches
+ * QmdSearchResult as of issue #564 but kept structural so tests and future
+ * callers don't have to import orchestrator-level types.
+ */
+interface BoostableResult {
+    path: string;
+    score: number;
+    docid?: string;
+}
+/**
+ * Path-based marker for memories that live in the dedicated
+ * reasoning-traces/ subtree. Using a path segment keeps this cheap: no
+ * frontmatter parsing or extra I/O is needed.
+ */
+declare function isReasoningTracePath(candidatePath: string): boolean;
+/**
+ * Default additive boost applied to a reasoning_trace candidate when the
+ * current query looks like a problem-solving ask.
+ *
+ * Chosen to be roughly the same magnitude as the existing CATEGORY_BOOSTS
+ * entry for reasoning_trace (0.09 in importance scoring), keeping the signal
+ * visible but not overwhelming stronger lexical/vector matches.
+ */
+declare const DEFAULT_REASONING_TRACE_BOOST = 0.15;
+interface ApplyReasoningTraceBoostOptions {
+    enabled: boolean;
+    query: string;
+    boost?: number;
+}
+/**
+ * Apply a score boost to results whose path sits under reasoning-traces/
+ * when the query looks like a problem-solving ask. Returns a new array;
+ * the input array is not mutated.
+ *
+ * Ordering policy: the helper walks the results in order, boosts every
+ * matching reasoning trace in place, then promotes each boosted trace
+ * upward PAST any non-boosted neighbor whose score is strictly lower
+ * than the trace's boosted score. Non-matching results keep their
+ * incoming relative order — so reranker-driven path ordering and any
+ * other upstream nudges on non-trace items are preserved. We do NOT
+ * re-sort the full list, which would wipe out rerank priority on
+ * non-trace items (whose numeric scores may have been left stale by the
+ * rerank pass). This matters because MMR runs immediately after and
+ * truncates to a topN window — globally re-sorting would silently drop
+ * reranker-promoted items below the cutoff.
+ *
+ * No-ops (returns a copy of the input unchanged) when:
+ *  - `enabled` is false,
+ *  - `query` is empty / not a problem-solving ask,
+ *  - the result list contains no reasoning-trace paths.
+ *
+ * Note on legacy paths: this helper intentionally only matches paths
+ * under the dedicated `reasoning-traces/` subtree introduced by PR 3.
+ * Historical reasoning_trace memories (if any) written before that
+ * subtree existed were routed to `facts/<date>/` and are NOT
+ * boost-eligible. Operators upgrading across that boundary should run
+ * the migration CLI or rewrite old paths before enabling the boost.
+ */
+declare function applyReasoningTraceBoost<R extends BoostableResult>(results: readonly R[], options: ApplyReasoningTraceBoostOptions): R[];
+
+export { type ApplyReasoningTraceBoostOptions, type BoostableResult, DEFAULT_REASONING_TRACE_BOOST, applyReasoningTraceBoost, isReasoningTracePath, looksLikeProblemSolvingQuery };

package/dist/reasoning-trace-recall.js

@@ -0,0 +1,13 @@
+import {
+  DEFAULT_REASONING_TRACE_BOOST,
+  applyReasoningTraceBoost,
+  isReasoningTracePath,
+  looksLikeProblemSolvingQuery
+} from "./chunk-ZZTOURJI.js";
+export {
+  DEFAULT_REASONING_TRACE_BOOST,
+  applyReasoningTraceBoost,
+  isReasoningTracePath,
+  looksLikeProblemSolvingQuery
+};
+//# sourceMappingURL=reasoning-trace-recall.js.map

package/dist/reasoning-trace-recall.js.map

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

package/dist/reasoning-trace-types.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Reasoning-trace memory structural types (issue #564).
+ *
+ * Captures stored solution chains / chain-of-thought the user walked through
+ * to solve a problem. Traces have an ordered list of steps, a final answer,
+ * and an optional observed outcome.
+ */
+interface ReasoningTraceStep {
+    /** 1-based ordinal within the trace. */
+    order: number;
+    /** Human-readable description of what happened at this step. */
+    description: string;
+}
+interface ReasoningTraceStructuredData {
+    steps: ReasoningTraceStep[];
+    finalAnswer: string;
+    /** Optional confirmation of how the answer played out in practice. */
+    observedOutcome?: string;
+}
+/** Normalize loose extraction JSON into ReasoningTraceStep records. */
+declare function normalizeReasoningTraceSteps(raw: unknown): ReasoningTraceStep[];
+/**
+ * Normalize a loose reasoningTrace object (e.g. coming back from the LLM) to
+ * a strict ReasoningTraceStructuredData shape. Returns null when the data is
+ * clearly incomplete (no steps or no final answer).
+ */
+declare function normalizeReasoningTrace(raw: unknown): ReasoningTraceStructuredData | null;
+/**
+ * Serialize a normalized reasoning trace into a human-readable markdown body.
+ * Output shape mirrors the procedure body format: ## Step N sections followed
+ * by final answer and optional observed outcome.
+ */
+declare function buildReasoningTraceMarkdownBody(trace: ReasoningTraceStructuredData): string;
+/**
+ * Combine a short title with the structured trace body. The title becomes the
+ * one-line content of the stored memory, and the full body is appended below.
+ */
+declare function buildReasoningTracePersistBody(title: string, trace: ReasoningTraceStructuredData): string;
+/**
+ * Best-effort parse of a reasoning-trace markdown body back into structured
+ * data. Returns null when the document does not look like a reasoning trace.
+ */
+declare function parseReasoningTraceFromBody(content: string): ReasoningTraceStructuredData | null;
+/**
+ * Heuristic detector for whether a user message contains a chain-of-thought /
+ * solution trace that should be extracted. This is intentionally conservative:
+ * we require at least two explicitly-ordered steps and some form of final
+ * answer / resolution. Used by the extraction pipeline to decide whether to
+ * even consider emitting a reasoning_trace fact, so false positives are more
+ * costly than false negatives.
+ */
+declare function looksLikeReasoningTrace(message: string): boolean;
+
+export { type ReasoningTraceStep, type ReasoningTraceStructuredData, buildReasoningTraceMarkdownBody, buildReasoningTracePersistBody, looksLikeReasoningTrace, normalizeReasoningTrace, normalizeReasoningTraceSteps, parseReasoningTraceFromBody };

package/dist/reasoning-trace-types.js

@@ -0,0 +1,17 @@
+import {
+  buildReasoningTraceMarkdownBody,
+  buildReasoningTracePersistBody,
+  looksLikeReasoningTrace,
+  normalizeReasoningTrace,
+  normalizeReasoningTraceSteps,
+  parseReasoningTraceFromBody
+} from "./chunk-54V4BZWP.js";
+export {
+  buildReasoningTraceMarkdownBody,
+  buildReasoningTracePersistBody,
+  looksLikeReasoningTrace,
+  normalizeReasoningTrace,
+  normalizeReasoningTraceSteps,
+  parseReasoningTraceFromBody
+};
+//# sourceMappingURL=reasoning-trace-types.js.map

package/dist/reasoning-trace-types.js.map

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

package/dist/recall-audit-anomaly.d.ts

@@ -0,0 +1,112 @@
+import { RecallAuditEntry } from './recall-audit.js';
+
+/**
+ * Recall-audit anomaly detector (issue #565 PR 5/5).
+ *
+ * Given a sequence of `RecallAuditEntry` records for a single principal /
+ * session, classify the series and emit `AnomalyFlag`s for suspicious
+ * patterns. Intended to run on both:
+ *
+ * 1. The MCP / HTTP access layers — every `recall` / `memory_search` /
+ *    `memory_timeline` call appends an audit entry and the detector is
+ *    invoked against the tail of the series (streaming mode).
+ * 2. The existing Openclaw hook (already writes `transcripts/*.jsonl`) —
+ *    the detector can be invoked out-of-band over the same entries.
+ *
+ * See the threat model §5 (gap: recall-audit was only on the Openclaw
+ * hook) and §6.3 (anomaly signals) for the patterns below.
+ *
+ * The module is pure: no I/O, no clock. Callers pass the entries +
+ * configured thresholds; the detector returns a deterministic classification.
+ *
+ * Patterns detected:
+ *
+ * - `repeat-query` — the same normalized query text issued more than N
+ *   times in the window. Covers the ADAM "exploitation" phase where the
+ *   attacker re-queries a high-signal token until it plateaus.
+ * - `namespace-walk` — the same principal's queries visit more than N
+ *   distinct candidate memory namespaces in the window. Suggests the
+ *   attacker is enumerating the namespace tree for leaks.
+ * - `high-cardinality-return` — a single recall surfaced more than N
+ *   candidate memory IDs in one response. Covers the "one query, dump
+ *   everything" exfiltration path.
+ * - `rapid-fire` — more than N recalls in the window irrespective of
+ *   content. Blunt instrument; useful when nothing else fires.
+ *
+ * Each flag carries the entry indices that support it so an audit UI can
+ * highlight the underlying evidence.
+ */
+
+type AnomalyKind = "repeat-query" | "namespace-walk" | "high-cardinality-return" | "rapid-fire";
+type AnomalySeverity = "info" | "warn" | "alert";
+interface AnomalyFlag {
+    kind: AnomalyKind;
+    severity: AnomalySeverity;
+    /** Human-readable rationale, e.g. `"query 'alex' repeated 12 times in 60s"`. */
+    message: string;
+    /** Indices into the supplied `entries` array that triggered the flag. */
+    entryIndices: number[];
+    /**
+     * Optional extra signal the caller can use to key metrics. For
+     * `repeat-query` this is the normalized query text; for
+     * `namespace-walk` it is the namespace count; etc.
+     */
+    signal?: string | number;
+}
+interface AnomalyDetectorConfig {
+    /** Detector feature-flag. Defaults to false — ships disabled. */
+    enabled?: boolean;
+    /**
+     * Rolling window in ms. The detector only considers entries whose `ts`
+     * falls within `[now - windowMs, now]`. Default 5 minutes.
+     */
+    windowMs?: number;
+    /**
+     * Threshold for `repeat-query`: a normalized query repeated more than
+     * this many times in the window trips the flag. Default 5.
+     */
+    repeatQueryLimit?: number;
+    /**
+     * Threshold for `namespace-walk`: more than this many distinct
+     * candidate namespaces in the window trips the flag. Default 3.
+     */
+    namespaceWalkLimit?: number;
+    /**
+     * Threshold for `high-cardinality-return`: more than this many
+     * `candidateMemoryIds` in a single entry trips the flag. Default 50.
+     */
+    highCardinalityReturnLimit?: number;
+    /**
+     * Threshold for `rapid-fire`: more than this many entries in the
+     * window trips the flag. Default 30. (Matches the default
+     * `recallCrossNamespaceBudgetHardLimit` from PR 4.)
+     */
+    rapidFireLimit?: number;
+}
+declare const DEFAULT_ANOMALY_DETECTOR_CONFIG: Required<AnomalyDetectorConfig>;
+interface AnomalyDetectorInput {
+    entries: readonly RecallAuditEntry[];
+    /** Current time in epoch ms. Entries older than `now - windowMs` are ignored. */
+    now: number;
+    config?: AnomalyDetectorConfig;
+}
+interface AnomalyDetectorResult {
+    /** All flags ordered by descending severity then kind. */
+    flags: AnomalyFlag[];
+    /** Number of entries inside the active window (after filtering). */
+    windowEntryCount: number;
+    /** Window size actually used, in ms. */
+    windowMs: number;
+}
+/**
+ * Normalize query text so cosmetic variation doesn't defeat the
+ * repeat-query detector. Lowercase, collapse whitespace, trim.
+ */
+declare function normalizeQueryText(raw: string): string;
+/**
+ * Run the detector against a series of audit entries. Pure; no side
+ * effects.
+ */
+declare function detectRecallAnomalies(input: AnomalyDetectorInput): AnomalyDetectorResult;
+
+export { type AnomalyDetectorConfig, type AnomalyDetectorInput, type AnomalyDetectorResult, type AnomalyFlag, type AnomalyKind, type AnomalySeverity, DEFAULT_ANOMALY_DETECTOR_CONFIG, detectRecallAnomalies, normalizeQueryText };

package/dist/recall-audit-anomaly.js

@@ -0,0 +1,11 @@
+import {
+  DEFAULT_ANOMALY_DETECTOR_CONFIG,
+  detectRecallAnomalies,
+  normalizeQueryText
+} from "./chunk-RFYAYKTD.js";
+export {
+  DEFAULT_ANOMALY_DETECTOR_CONFIG,
+  detectRecallAnomalies,
+  normalizeQueryText
+};
+//# sourceMappingURL=recall-audit-anomaly.js.map

package/dist/recall-audit-anomaly.js.map

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

package/dist/recall-audit.js

@@ -1,47 +1,8 @@
-// src/recall-audit.ts
-import { appendFile, mkdir, readdir, rm } from "fs/promises";
-import path from "path";
-function formatIsoDate(ts) {
-  const normalized = new Date(ts);
-  if (Number.isNaN(normalized.getTime())) {
-    return (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
-  }
-  return normalized.toISOString().slice(0, 10);
-}
-function buildRecallAuditPath(rootDir, ts, sessionKey) {
-  const safeSessionKey = encodeURIComponent(sessionKey);
-  return path.join(rootDir, "transcripts", formatIsoDate(ts), `${safeSessionKey}.jsonl`);
-}
-async function appendRecallAuditEntry(rootDir, entry) {
-  const filePath = buildRecallAuditPath(rootDir, entry.ts, entry.sessionKey);
-  await mkdir(path.dirname(filePath), { recursive: true });
-  await appendFile(filePath, `${JSON.stringify(entry)}
-`, "utf8");
-  return filePath;
-}
-async function pruneRecallAuditEntries(rootDir, retentionDays, now = /* @__PURE__ */ new Date()) {
-  const transcriptsDir = path.join(rootDir, "transcripts");
-  const removed = [];
-  const cutoff = new Date(now);
-  cutoff.setUTCHours(0, 0, 0, 0);
-  cutoff.setUTCDate(cutoff.getUTCDate() - Math.max(1, Math.floor(retentionDays)));
-  let entries;
-  try {
-    entries = await readdir(transcriptsDir, { withFileTypes: true });
-  } catch {
-    return removed;
-  }
-  for (const entry of entries) {
-    if (!entry.isDirectory()) continue;
-    if (!/^\d{4}-\d{2}-\d{2}$/.test(entry.name)) continue;
-    const day = /* @__PURE__ */ new Date(`${entry.name}T00:00:00.000Z`);
-    if (Number.isNaN(day.getTime()) || day >= cutoff) continue;
-    const dirPath = path.join(transcriptsDir, entry.name);
-    await rm(dirPath, { recursive: true, force: true });
-    removed.push(dirPath);
-  }
-  return removed;
-}
+import {
+  appendRecallAuditEntry,
+  buildRecallAuditPath,
+  pruneRecallAuditEntries
+} from "./chunk-LBLXEFWK.js";
 export {
   appendRecallAuditEntry,
   buildRecallAuditPath,

package/dist/recall-audit.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/recall-audit.ts"],"sourcesContent":["import type { Dirent } from \"node:fs\";\nimport { appendFile, mkdir, readdir, rm } from \"node:fs/promises\";\nimport path from \"node:path\";\n\nexport interface RecallAuditEntry {\n  ts: string;\n  sessionKey: string;\n  agentId: string;\n  trigger: string;\n  queryText: string;\n  candidateMemoryIds: string[];\n  summary: string | null;\n  injectedChars: number;\n  toggleState: \"enabled\" | \"disabled-primary\" | \"disabled-secondary\";\n  latencyMs?: number;\n  plannerMode?: string;\n  requestedMode?: string;\n  fallbackUsed?: boolean;\n}\n\nfunction formatIsoDate(ts: string): string {\n  const normalized = new Date(ts);\n  if (Number.isNaN(normalized.getTime())) {\n    return new Date().toISOString().slice(0, 10);\n  }\n  return normalized.toISOString().slice(0, 10);\n}\n\nexport function buildRecallAuditPath(rootDir: string, ts: string, sessionKey: string): string {\n  const safeSessionKey = encodeURIComponent(sessionKey);\n  return path.join(rootDir, \"transcripts\", formatIsoDate(ts), `${safeSessionKey}.jsonl`);\n}\n\nexport async function appendRecallAuditEntry(\n  rootDir: string,\n  entry: RecallAuditEntry,\n): Promise<string> {\n  const filePath = buildRecallAuditPath(rootDir, entry.ts, entry.sessionKey);\n  await mkdir(path.dirname(filePath), { recursive: true });\n  await appendFile(filePath, `${JSON.stringify(entry)}\\n`, \"utf8\");\n  return filePath;\n}\n\nexport async function pruneRecallAuditEntries(\n  rootDir: string,\n  retentionDays: number,\n  now: Date = new Date(),\n): Promise<string[]> {\n  const transcriptsDir = path.join(rootDir, \"transcripts\");\n  const removed: string[] = [];\n  const cutoff = new Date(now);\n  cutoff.setUTCHours(0, 0, 0, 0);\n  cutoff.setUTCDate(cutoff.getUTCDate() - Math.max(1, Math.floor(retentionDays)));\n  let entries: Dirent[];\n  try {\n    entries = await readdir(transcriptsDir, { withFileTypes: true });\n  } catch {\n    return removed;\n  }\n\n  for (const entry of entries) {\n    if (!entry.isDirectory()) continue;\n    if (!/^\\d{4}-\\d{2}-\\d{2}$/.test(entry.name)) continue;\n    const day = new Date(`${entry.name}T00:00:00.000Z`);\n    if (Number.isNaN(day.getTime()) || day >= cutoff) continue;\n    const dirPath = path.join(transcriptsDir, entry.name);\n    await rm(dirPath, { recursive: true, force: true });\n    removed.push(dirPath);\n  }\n\n  return removed;\n}\n"],"mappings":";AACA,SAAS,YAAY,OAAO,SAAS,UAAU;AAC/C,OAAO,UAAU;AAkBjB,SAAS,cAAc,IAAoB;AACzC,QAAM,aAAa,IAAI,KAAK,EAAE;AAC9B,MAAI,OAAO,MAAM,WAAW,QAAQ,CAAC,GAAG;AACtC,YAAO,oBAAI,KAAK,GAAE,YAAY,EAAE,MAAM,GAAG,EAAE;AAAA,EAC7C;AACA,SAAO,WAAW,YAAY,EAAE,MAAM,GAAG,EAAE;AAC7C;AAEO,SAAS,qBAAqB,SAAiB,IAAY,YAA4B;AAC5F,QAAM,iBAAiB,mBAAmB,UAAU;AACpD,SAAO,KAAK,KAAK,SAAS,eAAe,cAAc,EAAE,GAAG,GAAG,cAAc,QAAQ;AACvF;AAEA,eAAsB,uBACpB,SACA,OACiB;AACjB,QAAM,WAAW,qBAAqB,SAAS,MAAM,IAAI,MAAM,UAAU;AACzE,QAAM,MAAM,KAAK,QAAQ,QAAQ,GAAG,EAAE,WAAW,KAAK,CAAC;AACvD,QAAM,WAAW,UAAU,GAAG,KAAK,UAAU,KAAK,CAAC;AAAA,GAAM,MAAM;AAC/D,SAAO;AACT;AAEA,eAAsB,wBACpB,SACA,eACA,MAAY,oBAAI,KAAK,GACF;AACnB,QAAM,iBAAiB,KAAK,KAAK,SAAS,aAAa;AACvD,QAAM,UAAoB,CAAC;AAC3B,QAAM,SAAS,IAAI,KAAK,GAAG;AAC3B,SAAO,YAAY,GAAG,GAAG,GAAG,CAAC;AAC7B,SAAO,WAAW,OAAO,WAAW,IAAI,KAAK,IAAI,GAAG,KAAK,MAAM,aAAa,CAAC,CAAC;AAC9E,MAAI;AACJ,MAAI;AACF,cAAU,MAAM,QAAQ,gBAAgB,EAAE,eAAe,KAAK,CAAC;AAAA,EACjE,QAAQ;AACN,WAAO;AAAA,EACT;AAEA,aAAW,SAAS,SAAS;AAC3B,QAAI,CAAC,MAAM,YAAY,EAAG;AAC1B,QAAI,CAAC,sBAAsB,KAAK,MAAM,IAAI,EAAG;AAC7C,UAAM,MAAM,oBAAI,KAAK,GAAG,MAAM,IAAI,gBAAgB;AAClD,QAAI,OAAO,MAAM,IAAI,QAAQ,CAAC,KAAK,OAAO,OAAQ;AAClD,UAAM,UAAU,KAAK,KAAK,gBAAgB,MAAM,IAAI;AACpD,UAAM,GAAG,SAAS,EAAE,WAAW,MAAM,OAAO,KAAK,CAAC;AAClD,YAAQ,KAAK,OAAO;AAAA,EACtB;AAEA,SAAO;AACT;","names":[]}
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/recall-explain-renderer.d.ts

@@ -0,0 +1,49 @@
+import { LastRecallSnapshot } from './recall-state.js';
+import { RecallTierExplain } from './types.js';
+import { RecallXraySnapshot } from './recall-xray.js';
+
+/**
+ * Renderers for RecallTierExplain (issue #518).
+ *
+ * Pure functions that format a `LastRecallSnapshot` and its
+ * optional `tierExplain` field for human text and machine JSON
+ * consumption.  CLI / HTTP / MCP surfaces consume these — they do
+ * not format explain output themselves, so rendering is tested in
+ * one place.
+ */
+
+/**
+ * `text` and `json` are the original formats (backwards-compatible
+ * since issue #518).  `markdown` was added in issue #570 PR 7 and
+ * delegates to the shared X-ray renderer so the three observability
+ * surfaces stay in lock-step (CLAUDE.md rule 22).
+ */
+type RecallExplainFormat = "text" | "json" | "markdown";
+interface RecallExplainJsonPayload {
+    hasExplain: boolean;
+    snapshotFound: boolean;
+    sessionKey: string | null;
+    recordedAt: string | null;
+    namespace: string | null;
+    memoryIds: string[];
+    source: string | null;
+    sourcesUsed: string[] | null;
+    latencyMs: number | null;
+    tierExplain: RecallTierExplain | null;
+}
+declare function toRecallExplainJson(snapshot: LastRecallSnapshot | null): RecallExplainJsonPayload;
+/**
+ * Render the shared "--- tier explain ---" text block used by both the
+ * recall-explain surface and the Recall X-ray surface.  Callers provide
+ * the normalized `RecallTierExplain` (or `null` for the
+ * not-populated/disabled case) so the block stays character-for-character
+ * identical across surfaces (CLAUDE.md rule 22).  The returned strings do
+ * NOT include leading blank lines or headers — callers own that framing.
+ */
+declare function renderTierExplainTextLines(tierExplain: RecallTierExplain | null): string[];
+declare function toRecallExplainText(snapshot: LastRecallSnapshot | null): string;
+declare function toRecallXraySnapshotFromLegacy(snapshot: LastRecallSnapshot | null): RecallXraySnapshot | null;
+declare function renderRecallExplain(snapshot: LastRecallSnapshot | null, format: RecallExplainFormat): string;
+declare function parseRecallExplainFormat(value: unknown): RecallExplainFormat;
+
+export { type RecallExplainFormat, type RecallExplainJsonPayload, parseRecallExplainFormat, renderRecallExplain, renderTierExplainTextLines, toRecallExplainJson, toRecallExplainText, toRecallXraySnapshotFromLegacy };

package/dist/recall-explain-renderer.js

@@ -0,0 +1,18 @@
+import {
+  parseRecallExplainFormat,
+  renderRecallExplain,
+  renderTierExplainTextLines,
+  toRecallExplainJson,
+  toRecallExplainText,
+  toRecallXraySnapshotFromLegacy
+} from "./chunk-ZAIM4TUE.js";
+import "./chunk-SOBJ6NEY.js";
+export {
+  parseRecallExplainFormat,
+  renderRecallExplain,
+  renderTierExplainTextLines,
+  toRecallExplainJson,
+  toRecallExplainText,
+  toRecallXraySnapshotFromLegacy
+};
+//# sourceMappingURL=recall-explain-renderer.js.map

package/dist/recall-explain-renderer.js.map

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

package/dist/recall-state.d.ts

@@ -32,6 +32,13 @@ interface LastRecallSnapshot {
     identityInjectionMode?: IdentityInjectionMode | "none";
     identityInjectedChars?: number;
     identityInjectionTruncated?: boolean;
+    /**
+     * Collision-safe write nonce.  Random UUID set on every `record()`
+     * call so the observation-mode direct-answer hook can detect stale
+     * snapshots and avoid annotating a snapshot that a subsequent recall
+     * already replaced (issue #518).
+     */
+    writeNonce?: string;
     /**
      * Optional tier-level explanation of how recall was served
      * (issue #518).  Populated by orchestrator call sites that can
@@ -126,7 +133,11 @@ declare class LastRecallStore {
      * No-op when no snapshot exists for the given session; callers do
      * not need to guard on existence.
      */
-    annotateTierExplain(sessionKey: string, tierExplain: RecallTierExplain): Promise<void>;
+    annotateTierExplain(sessionKey: string, tierExplain: RecallTierExplain, expected?: {
+        writeNonce?: string;
+        traceId?: string;
+        recordedAt?: string;
+    }): Promise<void>;
 }
 declare class TierMigrationStatusStore {
     private readonly statePath;

package/dist/recall-state.js

@@ -2,7 +2,7 @@ import {
   LastRecallStore,
   TierMigrationStatusStore,
   clampGraphRecallExpandedEntries
-} from "./chunk-47UU5PU2.js";
+} from "./chunk-VBVG2M5G.js";
 import "./chunk-2ODBA7MQ.js";
 export {
   LastRecallStore,

package/dist/recall-xray-cli.d.ts

@@ -0,0 +1,40 @@
+import { RecallXrayFormat } from './recall-xray-renderer.js';
+import './recall-xray.js';
+import './types.js';
+
+/**
+ * Input-validation helpers for the `remnic xray` CLI command (issue
+ * #570, PR 3).
+ *
+ * Pulled out of `cli.ts` so the validation paths can be unit-tested in
+ * isolation — the full CLI handler is hard to exercise without booting
+ * an orchestrator.  CLAUDE.md rules 14 + 51 require that `--format`,
+ * `--budget`, `--namespace`, and `--out` reject missing-value /
+ * unknown / non-positive arguments with a listed-options error, rather
+ * than silently defaulting.
+ */
+
+interface ParsedXrayCliOptions {
+    format: RecallXrayFormat;
+    /** Positive integer override, or undefined when not specified. */
+    budget?: number;
+    /** Trimmed namespace, or undefined when not specified. */
+    namespace?: string;
+    /** Trimmed, tilde-unexpanded output path, or undefined when stdout. */
+    outPath?: string;
+}
+/**
+ * Validate and coerce `--budget <chars>`.  Must be a positive integer;
+ * throws a listed-options error otherwise.
+ */
+declare function parseXrayBudgetFlag(value: unknown): number | undefined;
+/**
+ * Parse and validate the full option bag for `remnic xray`.  Extracted
+ * so the CLI handler in `cli.ts` can stay thin and the validation can
+ * be unit-tested without booting an orchestrator.
+ */
+declare function parseXrayCliOptions(rawQuery: unknown, options: Record<string, unknown>): {
+    query: string;
+} & ParsedXrayCliOptions;
+
+export { type ParsedXrayCliOptions, parseXrayBudgetFlag, parseXrayCliOptions };

package/dist/recall-xray-cli.js

@@ -0,0 +1,11 @@
+import {
+  parseXrayBudgetFlag,
+  parseXrayCliOptions
+} from "./chunk-PVPWZSSI.js";
+import "./chunk-ZAIM4TUE.js";
+import "./chunk-SOBJ6NEY.js";
+export {
+  parseXrayBudgetFlag,
+  parseXrayCliOptions
+};
+//# sourceMappingURL=recall-xray-cli.js.map

package/dist/recall-xray-cli.js.map

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

package/dist/recall-xray-renderer.d.ts

@@ -0,0 +1,44 @@
+import { RecallXraySnapshot } from './recall-xray.js';
+import './types.js';
+
+/**
+ * Unified Recall X-ray renderer (issue #570, PR 2).
+ *
+ * Pure functions that format a `RecallXraySnapshot` for human text,
+ * GitHub-flavored markdown, and machine JSON consumption.  CLI / HTTP
+ * / MCP surfaces all call into this module — they do NOT format X-ray
+ * output themselves, so rendering is tested in one place (CLAUDE.md
+ * rule 22).
+ *
+ * Scope for PR 2 (this slice):
+ *   - Pure rendering.  No IO, no transport, no capture.
+ *   - `renderXray(snapshot, format)` with format ∈
+ *     `{"json", "text", "markdown"}`.
+ *   - `parseXrayFormat(value)` — input validator that rejects unknown
+ *     formats with a listed-options error (CLAUDE.md rule 51).
+ *   - Golden-file-style tests in `recall-xray-renderer.test.ts`.
+ */
+
+type RecallXrayFormat = "json" | "text" | "markdown";
+declare const RECALL_XRAY_FORMATS: readonly RecallXrayFormat[];
+/**
+ * Validate and coerce a user-provided `--format` / `format` argument to
+ * `RecallXrayFormat`.  Unknown values throw an error listing valid
+ * options (CLAUDE.md rule 51).  `undefined`/`null` defaults to `"text"`.
+ */
+declare function parseXrayFormat(value: unknown): RecallXrayFormat;
+/**
+ * Top-level dispatcher.  CLI / HTTP / MCP callers should always route
+ * through this function so the three formats stay in lock-step.
+ */
+declare function renderXray(snapshot: RecallXraySnapshot | null, format: RecallXrayFormat): string;
+/**
+ * Deterministic JSON encoding of an X-ray snapshot.  Returns a stable
+ * v1 envelope when the snapshot is absent so consumers can pattern-match
+ * on `snapshotFound` rather than distinguishing `null` vs `{}`.
+ */
+declare function renderXrayJson(snapshot: RecallXraySnapshot | null): string;
+declare function renderXrayText(snapshot: RecallXraySnapshot | null): string;
+declare function renderXrayMarkdown(snapshot: RecallXraySnapshot | null): string;
+
+export { RECALL_XRAY_FORMATS, type RecallXrayFormat, parseXrayFormat, renderXray, renderXrayJson, renderXrayMarkdown, renderXrayText };