@remnic/core 1.1.11 → 1.1.13

package/dist/chunk-EHRTFRWW.js

@@ -0,0 +1,89 @@
+import {
+  normalizeReplayContent,
+  normalizeReplayRole,
+  normalizeReplayTimestamp
+} from "./chunk-TZOLIGIG.js";
+
+// src/replay/normalizers/claude.ts
+function gatherConversations(input) {
+  if (Array.isArray(input)) return input.filter((item) => !!item && typeof item === "object");
+  if (!input || typeof input !== "object") return [];
+  const obj = input;
+  if (Array.isArray(obj.conversations)) {
+    return obj.conversations.filter((item) => !!item && typeof item === "object");
+  }
+  if (Array.isArray(obj.chat_messages) || Array.isArray(obj.messages)) {
+    return [obj];
+  }
+  return [];
+}
+var claudeReplayNormalizer = {
+  source: "claude",
+  parse(input, options = {}) {
+    let parsedInput = input;
+    if (typeof input === "string") {
+      try {
+        parsedInput = JSON.parse(input);
+      } catch {
+        parsedInput = [];
+      }
+    }
+    const warnings = [];
+    const turns = [];
+    const conversations = gatherConversations(parsedInput);
+    for (let i = 0; i < conversations.length; i += 1) {
+      const conversation = conversations[i];
+      const convoIdRaw = conversation.uuid ?? conversation.id ?? conversation.conversation_id;
+      const hasSourceConversationId = typeof convoIdRaw === "string" && convoIdRaw.trim().length > 0;
+      const convoId = hasSourceConversationId ? convoIdRaw.trim() : `conv-${i + 1}`;
+      const sessionKey = `replay:claude:${convoId}`;
+      const fallbackSessionKey = options.defaultSessionKey?.trim() || sessionKey;
+      const messagesRaw = Array.isArray(conversation.chat_messages) ? conversation.chat_messages : Array.isArray(conversation.messages) ? conversation.messages : [];
+      for (let j = 0; j < messagesRaw.length; j += 1) {
+        const msg = messagesRaw[j];
+        if (!msg || typeof msg !== "object") {
+          warnings.push({
+            code: "replay.claude.message.invalid",
+            message: `Skipping malformed Claude message at conversation ${i + 1}, index ${j}.`,
+            index: j
+          });
+          continue;
+        }
+        const row = msg;
+        const role = normalizeReplayRole(
+          row.sender ?? row.role ?? row.author?.role
+        );
+        const content = normalizeReplayContent(row.text ?? row.content ?? row.message);
+        const timestamp = normalizeReplayTimestamp(
+          row.created_at ?? row.createdAt ?? row.updated_at ?? row.updatedAt ?? row.timestamp
+        );
+        if (!role || !content || !timestamp) {
+          const message = `Skipping invalid Claude replay message at conversation ${i + 1}, index ${j}.`;
+          if (options.strict) throw new Error(message);
+          warnings.push({ code: "replay.claude.message.invalid", message, index: j });
+          continue;
+        }
+        const externalIdRaw = row.uuid ?? row.id;
+        turns.push({
+          source: "claude",
+          sessionKey: hasSourceConversationId ? sessionKey : fallbackSessionKey,
+          role,
+          content,
+          timestamp,
+          sourceValidAt: timestamp,
+          externalId: typeof externalIdRaw === "string" ? externalIdRaw : void 0,
+          metadata: {
+            conversationId: convoId,
+            conversationName: typeof conversation.name === "string" ? conversation.name : void 0
+          }
+        });
+      }
+    }
+    return { turns, warnings };
+  }
+};
+
+export {
+  claudeReplayNormalizer
+};
+//# sourceMappingURL=chunk-EHRTFRWW.js.map

package/dist/chunk-EHRTFRWW.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/replay/normalizers/claude.ts"],"sourcesContent":["import {\n  type ReplayNormalizer,\n  type ReplayParseOptions,\n  type ReplayParseResult,\n  type ReplayTurn,\n} from \"../types.js\";\nimport { normalizeReplayContent, normalizeReplayRole, normalizeReplayTimestamp } from \"./shared.js\";\n\nfunction gatherConversations(input: unknown): Array<Record<string, unknown>> {\n  if (Array.isArray(input)) return input.filter((item): item is Record<string, unknown> => !!item && typeof item === \"object\");\n  if (!input || typeof input !== \"object\") return [];\n\n  const obj = input as Record<string, unknown>;\n  if (Array.isArray(obj.conversations)) {\n    return obj.conversations.filter((item): item is Record<string, unknown> => !!item && typeof item === \"object\");\n  }\n\n  if (Array.isArray(obj.chat_messages) || Array.isArray(obj.messages)) {\n    return [obj];\n  }\n\n  return [];\n}\n\nexport const claudeReplayNormalizer: ReplayNormalizer = {\n  source: \"claude\",\n  parse(input: unknown, options: ReplayParseOptions = {}): ReplayParseResult {\n    let parsedInput = input;\n    if (typeof input === \"string\") {\n      try {\n        parsedInput = JSON.parse(input);\n      } catch {\n        parsedInput = [];\n      }\n    }\n\n    const warnings: ReplayParseResult[\"warnings\"] = [];\n    const turns: ReplayTurn[] = [];\n    const conversations = gatherConversations(parsedInput);\n\n    for (let i = 0; i < conversations.length; i += 1) {\n      const conversation = conversations[i];\n      const convoIdRaw = conversation.uuid ?? conversation.id ?? conversation.conversation_id;\n      const hasSourceConversationId = typeof convoIdRaw === \"string\" && convoIdRaw.trim().length > 0;\n      const convoId = hasSourceConversationId ? convoIdRaw.trim() : `conv-${i + 1}`;\n      const sessionKey = `replay:claude:${convoId}`;\n      const fallbackSessionKey = options.defaultSessionKey?.trim() || sessionKey;\n\n      const messagesRaw = Array.isArray(conversation.chat_messages)\n        ? conversation.chat_messages\n        : Array.isArray(conversation.messages)\n          ? conversation.messages\n          : [];\n\n      for (let j = 0; j < messagesRaw.length; j += 1) {\n        const msg = messagesRaw[j];\n        if (!msg || typeof msg !== \"object\") {\n          warnings.push({\n            code: \"replay.claude.message.invalid\",\n            message: `Skipping malformed Claude message at conversation ${i + 1}, index ${j}.`,\n            index: j,\n          });\n          continue;\n        }\n\n        const row = msg as Record<string, unknown>;\n        const role = normalizeReplayRole(\n          row.sender ?? row.role ?? (row.author as Record<string, unknown> | undefined)?.role,\n        );\n        const content = normalizeReplayContent(row.text ?? row.content ?? row.message);\n        const timestamp = normalizeReplayTimestamp(\n          row.created_at ?? row.createdAt ?? row.updated_at ?? row.updatedAt ?? row.timestamp,\n        );\n\n        if (!role || !content || !timestamp) {\n          const message = `Skipping invalid Claude replay message at conversation ${i + 1}, index ${j}.`;\n          if (options.strict) throw new Error(message);\n          warnings.push({ code: \"replay.claude.message.invalid\", message, index: j });\n          continue;\n        }\n\n        const externalIdRaw = row.uuid ?? row.id;\n\n        turns.push({\n          source: \"claude\",\n          sessionKey: hasSourceConversationId ? sessionKey : fallbackSessionKey,\n          role,\n          content,\n          timestamp,\n          sourceValidAt: timestamp,\n          externalId: typeof externalIdRaw === \"string\" ? externalIdRaw : undefined,\n          metadata: {\n            conversationId: convoId,\n            conversationName: typeof conversation.name === \"string\" ? conversation.name : undefined,\n          },\n        });\n      }\n    }\n\n    return { turns, warnings };\n  },\n};\n"],"mappings":"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","names":[]}

package/dist/chunk-FAJ7FZYM.js

@@ -0,0 +1,11 @@
+// src/adapters/types.ts
+function headerValue(headers, key) {
+  const raw = headers[key];
+  const value = Array.isArray(raw) ? raw[0] : raw;
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : void 0;
+}
+
+export {
+  headerValue
+};
+//# sourceMappingURL=chunk-FAJ7FZYM.js.map

package/dist/chunk-FAJ7FZYM.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/adapters/types.ts"],"sourcesContent":["/**\n * Adapter interface for external system identity resolution.\n *\n * Each adapter maps an external system's session/identity conventions\n * to Engram's namespace + principal model. Adapters are stateless and\n * lightweight — they don't manage lifecycles or load plugins.\n */\n\nexport interface AdapterContext {\n  /** Raw HTTP headers from the incoming request */\n  headers: Record<string, string | string[] | undefined>;\n  /** MCP client info (from initialize handshake, if available) */\n  clientInfo?: { name: string; version?: string };\n  /** Explicit session key from request args */\n  sessionKey?: string;\n}\n\nexport interface ResolvedIdentity {\n  /** Engram namespace (scopes memory access) */\n  namespace: string;\n  /** Engram principal (authorization subject) */\n  principal: string;\n  /** Session key for continuity tracking */\n  sessionKey?: string;\n  /** Which adapter resolved this identity */\n  adapterId: string;\n}\n\nexport interface EngramAdapter {\n  /** Adapter identifier (e.g., \"claude-code\", \"codex\", \"hermes\", \"replit\") */\n  readonly id: string;\n\n  /** Whether this adapter recognizes the given request context */\n  matches(context: AdapterContext): boolean;\n\n  /** Map external session/identity to Engram namespace + principal */\n  resolveIdentity(context: AdapterContext): ResolvedIdentity;\n}\n\n/**\n * Extract and trim a single header value from a headers record.\n * Returns undefined if the header is missing, empty, or all whitespace.\n */\nexport function headerValue(\n  headers: Record<string, string | string[] | undefined>,\n  key: string,\n): string | undefined {\n  const raw = headers[key];\n  const value = Array.isArray(raw) ? raw[0] : raw;\n  return typeof value === \"string\" && value.trim().length > 0 ? value.trim() : undefined;\n}\n"],"mappings":";AA2CO,SAAS,YACd,SACA,KACoB;AACpB,QAAM,MAAM,QAAQ,GAAG;AACvB,QAAM,QAAQ,MAAM,QAAQ,GAAG,IAAI,IAAI,CAAC,IAAI;AAC5C,SAAO,OAAO,UAAU,YAAY,MAAM,KAAK,EAAE,SAAS,IAAI,MAAM,KAAK,IAAI;AAC/E;","names":[]}

package/dist/chunk-FBYESMQ2.js

@@ -0,0 +1,570 @@
+import {
+  isRetrievalTier
+} from "./chunk-SOBJ6NEY.js";
+import {
+  summarizeDisclosureTokens
+} from "./chunk-MGKYQQYF.js";
+import {
+  summarizeRetrievedMemoryProvenance
+} from "./chunk-AC5LO7IU.js";
+
+// src/recall-explain-renderer.ts
+function sanitizeString(v) {
+  return typeof v === "string" && v.length > 0 ? v : null;
+}
+function sanitizeFiniteNumber(v) {
+  return typeof v === "number" && Number.isFinite(v) ? v : null;
+}
+function normalizeTierExplain(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const raw = value;
+  const filteredBy = Array.isArray(raw.filteredBy) ? raw.filteredBy.filter((x) => typeof x === "string") : [];
+  const sourceAnchors = Array.isArray(raw.sourceAnchors) ? raw.sourceAnchors.filter(
+    (a) => !!a && typeof a === "object" && typeof a.path === "string"
+  ).map((a) => {
+    const lr = a.lineRange;
+    const lineRange = Array.isArray(lr) && lr.length === 2 && Number.isFinite(lr[0]) && Number.isFinite(lr[1]) ? [lr[0], lr[1]] : void 0;
+    return lineRange ? { path: a.path, lineRange } : { path: a.path };
+  }) : void 0;
+  return {
+    tier: isRetrievalTier(raw.tier) ? raw.tier : "hybrid",
+    tierReason: typeof raw.tierReason === "string" ? raw.tierReason : "",
+    filteredBy,
+    candidatesConsidered: sanitizeFiniteNumber(raw.candidatesConsidered) ?? 0,
+    latencyMs: sanitizeFiniteNumber(raw.latencyMs) ?? 0,
+    ...sourceAnchors !== void 0 ? { sourceAnchors } : {}
+  };
+}
+function toRecallExplainJson(snapshot) {
+  if (!snapshot) {
+    return {
+      hasExplain: false,
+      snapshotFound: false,
+      sessionKey: null,
+      recordedAt: null,
+      namespace: null,
+      memoryIds: [],
+      source: null,
+      sourcesUsed: null,
+      latencyMs: null,
+      tierExplain: null
+    };
+  }
+  const normalizedExplain = normalizeTierExplain(snapshot.tierExplain);
+  return {
+    hasExplain: normalizedExplain !== null,
+    snapshotFound: true,
+    sessionKey: sanitizeString(snapshot.sessionKey),
+    recordedAt: sanitizeString(snapshot.recordedAt),
+    namespace: sanitizeString(snapshot.namespace),
+    memoryIds: Array.isArray(snapshot.memoryIds) ? snapshot.memoryIds.filter((x) => typeof x === "string") : [],
+    source: sanitizeString(snapshot.source),
+    sourcesUsed: Array.isArray(snapshot.sourcesUsed) ? snapshot.sourcesUsed.filter((x) => typeof x === "string") : null,
+    latencyMs: sanitizeFiniteNumber(snapshot.latencyMs),
+    tierExplain: normalizedExplain
+  };
+}
+function renderTierExplainTextLines(tierExplain) {
+  const lines = [];
+  if (!tierExplain) {
+    lines.push(
+      "(not populated \u2014 direct-answer tier disabled or did not fire)"
+    );
+    return lines;
+  }
+  lines.push(`tier: ${tierExplain.tier}`);
+  lines.push(`reason: ${tierExplain.tierReason}`);
+  lines.push(`candidates-considered: ${tierExplain.candidatesConsidered}`);
+  lines.push(`latency-ms: ${tierExplain.latencyMs}`);
+  if (tierExplain.filteredBy.length > 0) {
+    lines.push(`filtered-by: ${tierExplain.filteredBy.join(", ")}`);
+  } else {
+    lines.push("filtered-by: (none)");
+  }
+  if (tierExplain.sourceAnchors && tierExplain.sourceAnchors.length > 0) {
+    lines.push("source-anchors:");
+    for (const anchor of tierExplain.sourceAnchors) {
+      const range = anchor.lineRange ? `:${anchor.lineRange[0]}-${anchor.lineRange[1]}` : "";
+      lines.push(`  - ${anchor.path}${range}`);
+    }
+  }
+  return lines;
+}
+function toRecallExplainText(snapshot) {
+  const lines = ["=== Recall Explain ==="];
+  if (!snapshot) {
+    lines.push("No recall snapshot recorded yet.");
+    return lines.join("\n");
+  }
+  const sessionKey = sanitizeString(snapshot.sessionKey);
+  const recordedAt = sanitizeString(snapshot.recordedAt);
+  const namespace = sanitizeString(snapshot.namespace);
+  const source = sanitizeString(snapshot.source);
+  lines.push(`session: ${sessionKey ?? "(unknown)"}`);
+  lines.push(`recorded: ${recordedAt ?? "(unknown)"}`);
+  if (namespace) lines.push(`namespace: ${namespace}`);
+  if (source) lines.push(`source: ${source}`);
+  const sourcesUsed = Array.isArray(snapshot.sourcesUsed) ? snapshot.sourcesUsed.filter((x) => typeof x === "string") : [];
+  if (sourcesUsed.length > 0) {
+    lines.push(`sources-used: ${sourcesUsed.join(", ")}`);
+  }
+  const latencyMs = sanitizeFiniteNumber(snapshot.latencyMs);
+  if (latencyMs !== null) {
+    lines.push(`latency-ms: ${latencyMs}`);
+  }
+  const memoryIds = Array.isArray(snapshot.memoryIds) ? snapshot.memoryIds.filter((x) => typeof x === "string") : [];
+  if (memoryIds.length > 0) {
+    lines.push(`memories: ${memoryIds.join(", ")}`);
+  }
+  const ex = normalizeTierExplain(snapshot.tierExplain);
+  if (!ex) {
+    lines.push("");
+    lines.push(
+      "tier-explain: (not populated \u2014 direct-answer tier disabled or did not fire)"
+    );
+    return lines.join("\n");
+  }
+  lines.push("");
+  lines.push("--- tier explain ---");
+  for (const line of renderTierExplainTextLines(ex)) {
+    lines.push(line);
+  }
+  return lines.join("\n");
+}
+function sanitizeForMarkdownInline(value) {
+  if (typeof value !== "string") return "";
+  return value.replace(/[`|\r\n]/g, " ").trim();
+}
+function mapLegacySourceToServedBy(source) {
+  if (source === "recent_scan") return "recent-scan";
+  return "hybrid";
+}
+function toRecallXraySnapshotFromLegacy(snapshot) {
+  if (!snapshot) return null;
+  const capturedAt = (() => {
+    if (typeof snapshot.recordedAt !== "string") return 0;
+    const ms = Date.parse(snapshot.recordedAt);
+    return Number.isFinite(ms) && ms >= 0 ? ms : 0;
+  })();
+  const memoryIds = Array.isArray(snapshot.memoryIds) ? snapshot.memoryIds.filter((x) => typeof x === "string") : [];
+  const servedBy = mapLegacySourceToServedBy(snapshot.source);
+  const results = memoryIds.map((memoryId) => ({
+    memoryId,
+    path: "",
+    servedBy,
+    scoreDecomposition: { final: 0 },
+    admittedBy: []
+  }));
+  const filters = [];
+  return {
+    schemaVersion: "1",
+    // `LastRecallSnapshot` does not preserve the original query text;
+    // synthesize a placeholder so the renderer has a non-empty
+    // string to print.  `queryHash` + `queryLen` stay in the JSON
+    // payload via `toRecallExplainJson` for callers that need them.
+    query: snapshot.queryHash ? `(legacy explain; queryHash=${snapshot.queryHash})` : "(legacy explain)",
+    // `snapshotId` is synthesized here; `sessionKey` is already
+    // sanitized before it reaches the ID because we re-use the
+    // sanitized string below.
+    snapshotId: `legacy-${sanitizeForMarkdownInline(snapshot.sessionKey ?? "unknown") || "unknown"}-${capturedAt}`,
+    capturedAt,
+    // Run the raw on-disk value through the same normalizer the text
+    // and JSON paths use so the markdown adapter cannot render
+    // unvalidated tier-explain payloads (cursor / codex review on
+    // #605).  A malformed tierExplain is dropped to null, matching the
+    // behavior of the non-markdown surfaces.
+    tierExplain: normalizeTierExplain(snapshot.tierExplain) ?? null,
+    results,
+    filters,
+    budget: { chars: 0, used: 0 },
+    // Sanitize legacy session metadata at the adapter boundary so a
+    // malformed on-disk value (containing backticks, pipes, or
+    // newlines) cannot break the enclosing markdown table when
+    // `renderXrayMarkdown` prints it in a raw code-span cell (codex P2
+    // review on #605).
+    ...snapshot.sessionKey ? (() => {
+      const clean = sanitizeForMarkdownInline(snapshot.sessionKey);
+      return clean ? { sessionKey: clean } : {};
+    })() : {},
+    ...snapshot.namespace ? (() => {
+      const clean = sanitizeForMarkdownInline(snapshot.namespace);
+      return clean ? { namespace: clean } : {};
+    })() : {}
+  };
+}
+function renderRecallExplain(snapshot, format) {
+  if (format === "json") {
+    return JSON.stringify(toRecallExplainJson(snapshot), null, 2);
+  }
+  if (format === "markdown") {
+    return renderXrayMarkdown(toRecallXraySnapshotFromLegacy(snapshot));
+  }
+  return toRecallExplainText(snapshot);
+}
+function parseRecallExplainFormat(value) {
+  if (value === void 0 || value === null) return "text";
+  if (typeof value !== "string") {
+    throw new Error(
+      `--format expects "text", "json", or "markdown", got ${typeof value}`
+    );
+  }
+  const v = value.trim().toLowerCase();
+  if (v === "text" || v === "json" || v === "markdown") return v;
+  throw new Error(
+    `--format expects "text", "json", or "markdown", got ${JSON.stringify(value)}`
+  );
+}
+
+// src/recall-xray-renderer.ts
+var RECALL_XRAY_FORMATS = [
+  "json",
+  "text",
+  "markdown"
+];
+function parseXrayFormat(value) {
+  if (value === void 0 || value === null) return "text";
+  if (typeof value !== "string") {
+    throw new Error(
+      `--format expects one of ${RECALL_XRAY_FORMATS.join(", ")}; got ${typeof value}`
+    );
+  }
+  const v = value.trim().toLowerCase();
+  if (v === "json" || v === "text" || v === "markdown") return v;
+  throw new Error(
+    `--format expects one of ${RECALL_XRAY_FORMATS.join(", ")}; got ${JSON.stringify(value)}`
+  );
+}
+function renderXray(snapshot, format) {
+  if (format === "json") return renderXrayJson(snapshot);
+  if (format === "markdown") return renderXrayMarkdown(snapshot);
+  return renderXrayText(snapshot);
+}
+function renderXrayJson(snapshot) {
+  if (!snapshot) {
+    return JSON.stringify(
+      { schemaVersion: "1", snapshotFound: false },
+      null,
+      2
+    );
+  }
+  return JSON.stringify(
+    { snapshotFound: true, ...snapshot },
+    null,
+    2
+  );
+}
+function renderXrayText(snapshot) {
+  const lines = ["=== Recall X-ray ==="];
+  if (!snapshot) {
+    lines.push("No X-ray snapshot captured.");
+    return lines.join("\n");
+  }
+  lines.push(`query: ${snapshot.query}`);
+  lines.push(`snapshot-id: ${snapshot.snapshotId}`);
+  lines.push(`captured-at: ${formatCapturedAt(snapshot.capturedAt)}`);
+  if (snapshot.sessionKey) lines.push(`session: ${snapshot.sessionKey}`);
+  if (snapshot.namespace) lines.push(`namespace: ${snapshot.namespace}`);
+  if (snapshot.traceId) lines.push(`trace-id: ${snapshot.traceId}`);
+  lines.push(
+    `budget: ${snapshot.budget.used} / ${snapshot.budget.chars} chars`
+  );
+  lines.push("");
+  lines.push("--- filters ---");
+  if (snapshot.filters.length === 0) {
+    lines.push("(no filter traces recorded)");
+  } else {
+    for (const f of snapshot.filters) {
+      lines.push(renderFilterTextLine(f));
+    }
+  }
+  lines.push("");
+  lines.push("--- results ---");
+  if (snapshot.results.length === 0) {
+    lines.push("(no results admitted)");
+  } else {
+    snapshot.results.forEach((result, idx) => {
+      for (const line of renderResultTextLines(result, idx + 1)) {
+        lines.push(line);
+      }
+    });
+  }
+  lines.push("");
+  lines.push("--- tier explain ---");
+  for (const line of renderTierExplainTextLines(snapshot.tierExplain ?? null)) {
+    lines.push(line);
+  }
+  return lines.join("\n");
+}
+function renderFilterTextLine(f) {
+  const base = `- ${f.name}: ${f.admitted}/${f.considered} admitted`;
+  return f.reason ? `${base} (${f.reason})` : base;
+}
+function renderResultTextLines(result, rank) {
+  const lines = [];
+  lines.push(`[${rank}] ${result.memoryId} \u2014 ${servedByLabel(result.servedBy)}`);
+  if (result.path) lines.push(`    path: ${result.path}`);
+  lines.push(`    score: ${renderScoreDecomposition(result)}`);
+  if (result.provenance) {
+    lines.push(
+      `    provenance: ${summarizeRetrievedMemoryProvenance(result.provenance)}`
+    );
+    lines.push(`    retrieval-reason: ${result.provenance.retrievalReason}`);
+    if (result.provenance.userContextScopes.length > 0) {
+      lines.push(
+        `    context-scopes: ${result.provenance.userContextScopes.join(", ")}`
+      );
+    }
+    if (result.provenance.safety !== "safe" || result.provenance.safetyReasons.length > 0) {
+      const reasonSuffix = result.provenance.safetyReasons.length > 0 ? ` (${result.provenance.safetyReasons.join(", ")})` : "";
+      lines.push(`    safety: ${result.provenance.safety}${reasonSuffix}`);
+    }
+  }
+  if (result.admittedBy.length > 0) {
+    lines.push(`    admitted-by: ${result.admittedBy.join(", ")}`);
+  }
+  if (result.rejectedBy) {
+    lines.push(`    rejected-by: ${result.rejectedBy}`);
+  }
+  if (result.graphPath && result.graphPath.length > 0) {
+    lines.push(`    graph-path: ${result.graphPath.join(" -> ")}`);
+    if (result.graphEdgeConfidences && result.graphEdgeConfidences.length > 0) {
+      lines.push(
+        `    edge-confidences: ${result.graphEdgeConfidences.map((c) => c.toFixed(2)).join(", ")}`
+      );
+    }
+  }
+  if (result.auditEntryId) {
+    lines.push(`    audit-entry: ${result.auditEntryId}`);
+  }
+  return lines;
+}
+function renderXrayMarkdown(snapshot) {
+  const lines = ["# Recall X-ray"];
+  if (!snapshot) {
+    lines.push("");
+    lines.push("_No X-ray snapshot captured._");
+    return lines.join("\n");
+  }
+  lines.push("");
+  lines.push(`**Query:** ${mdInlineCode(snapshot.query)}`);
+  lines.push("");
+  lines.push("| Field | Value |");
+  lines.push("| --- | --- |");
+  lines.push(`| Snapshot ID | \`${snapshot.snapshotId}\` |`);
+  lines.push(`| Captured at | ${formatCapturedAt(snapshot.capturedAt)} |`);
+  if (snapshot.sessionKey) {
+    lines.push(`| Session | \`${snapshot.sessionKey}\` |`);
+  }
+  if (snapshot.namespace) {
+    lines.push(`| Namespace | \`${snapshot.namespace}\` |`);
+  }
+  if (snapshot.traceId) {
+    lines.push(`| Trace ID | \`${snapshot.traceId}\` |`);
+  }
+  lines.push(
+    `| Budget | ${snapshot.budget.used} / ${snapshot.budget.chars} chars |`
+  );
+  lines.push("");
+  lines.push("## Filters");
+  if (snapshot.filters.length === 0) {
+    lines.push("");
+    lines.push("_No filter traces recorded._");
+  } else {
+    lines.push("");
+    lines.push("| Filter | Considered | Admitted | Reason |");
+    lines.push("| --- | ---: | ---: | --- |");
+    for (const f of snapshot.filters) {
+      const reason = f.reason ? mdEscape(f.reason) : "";
+      lines.push(`| ${mdEscape(f.name)} | ${f.considered} | ${f.admitted} | ${reason} |`);
+    }
+  }
+  lines.push("");
+  lines.push("## Results");
+  if (snapshot.results.length === 0) {
+    lines.push("");
+    lines.push("_No results admitted._");
+  } else {
+    snapshot.results.forEach((result, idx) => {
+      for (const line of renderResultMarkdownLines(result, idx + 1)) {
+        lines.push(line);
+      }
+    });
+    const summary = summarizeDisclosureTokens(snapshot.results);
+    const hasAnyDisclosure = summary.chunk.count + summary.section.count + summary.raw.count > 0;
+    if (hasAnyDisclosure) {
+      lines.push("");
+      lines.push("### Token spend by disclosure");
+      lines.push("");
+      lines.push("| Disclosure | Results | Estimated tokens |");
+      lines.push("| --- | ---: | ---: |");
+      lines.push(
+        `| chunk | ${summary.chunk.count} | ${summary.chunk.estimatedTokens} |`
+      );
+      lines.push(
+        `| section | ${summary.section.count} | ${summary.section.estimatedTokens} |`
+      );
+      lines.push(
+        `| raw | ${summary.raw.count} | ${summary.raw.estimatedTokens} |`
+      );
+      if (summary.unspecified.count > 0) {
+        lines.push(
+          `| _(unspecified)_ | ${summary.unspecified.count} | ${summary.unspecified.estimatedTokens} |`
+        );
+      }
+    }
+  }
+  lines.push("");
+  lines.push("## Tier Explain");
+  if (!snapshot.tierExplain) {
+    lines.push("");
+    lines.push(
+      "_Not populated \u2014 direct-answer tier disabled or did not fire._"
+    );
+  } else {
+    const te = snapshot.tierExplain;
+    lines.push("");
+    lines.push("| Field | Value |");
+    lines.push("| --- | --- |");
+    lines.push(`| Tier | \`${te.tier}\` |`);
+    lines.push(`| Reason | ${mdEscape(te.tierReason)} |`);
+    lines.push(`| Candidates considered | ${te.candidatesConsidered} |`);
+    lines.push(`| Latency (ms) | ${te.latencyMs} |`);
+    lines.push(
+      `| Filtered by | ${te.filteredBy.length > 0 ? te.filteredBy.map(mdInlineCode).join(", ") : "_(none)_"} |`
+    );
+    if (te.sourceAnchors && te.sourceAnchors.length > 0) {
+      lines.push("");
+      lines.push("**Source anchors:**");
+      for (const anchor of te.sourceAnchors) {
+        const range = anchor.lineRange ? `:${anchor.lineRange[0]}-${anchor.lineRange[1]}` : "";
+        lines.push(`- \`${anchor.path}${range}\``);
+      }
+    }
+  }
+  return lines.join("\n");
+}
+function renderResultMarkdownLines(result, rank) {
+  const lines = [];
+  lines.push("");
+  lines.push(
+    `### ${rank}. \`${result.memoryId}\` \u2014 ${servedByLabel(result.servedBy)}`
+  );
+  if (result.path) {
+    lines.push("");
+    lines.push(`- **Path:** \`${result.path}\``);
+  } else {
+    lines.push("");
+  }
+  lines.push(`- **Score:** ${renderScoreDecomposition(result)}`);
+  if (result.provenance) {
+    lines.push(
+      `- **Provenance:** ${mdEscape(summarizeRetrievedMemoryProvenance(result.provenance))}`
+    );
+    lines.push(
+      `- **Retrieval reason:** ${mdInlineCode(result.provenance.retrievalReason)}`
+    );
+    if (result.provenance.userContextScopes.length > 0) {
+      lines.push(
+        `- **Context scopes:** ${result.provenance.userContextScopes.map(mdInlineCode).join(", ")}`
+      );
+    }
+    if (result.provenance.safety !== "safe" || result.provenance.safetyReasons.length > 0) {
+      const reasonSuffix = result.provenance.safetyReasons.length > 0 ? ` (${result.provenance.safetyReasons.map(mdInlineCode).join(", ")})` : "";
+      lines.push(
+        `- **Safety:** ${mdInlineCode(result.provenance.safety)}${reasonSuffix}`
+      );
+    }
+  }
+  if (result.admittedBy.length > 0) {
+    lines.push(
+      `- **Admitted by:** ${result.admittedBy.map(mdInlineCode).join(", ")}`
+    );
+  }
+  if (result.rejectedBy) {
+    lines.push(`- **Rejected by:** ${mdInlineCode(result.rejectedBy)}`);
+  }
+  if (result.graphPath && result.graphPath.length > 0) {
+    lines.push(
+      `- **Graph path:** ${result.graphPath.map(mdInlineCode).join(" \u2192 ")}`
+    );
+    if (result.graphEdgeConfidences && result.graphEdgeConfidences.length > 0) {
+      lines.push(
+        `- **Edge confidences:** ${result.graphEdgeConfidences.map((c) => mdInlineCode(c.toFixed(2))).join(", ")}`
+      );
+    }
+  }
+  if (result.auditEntryId) {
+    lines.push(`- **Audit entry:** \`${result.auditEntryId}\``);
+  }
+  if (result.disclosure !== void 0) {
+    const tokenLine = typeof result.estimatedTokens === "number" ? ` (~${result.estimatedTokens} tokens)` : "";
+    lines.push(`- **Disclosure:** \`${result.disclosure}\`${tokenLine}`);
+  } else if (typeof result.estimatedTokens === "number") {
+    lines.push(`- **Estimated tokens:** ${result.estimatedTokens}`);
+  }
+  return lines;
+}
+function servedByLabel(servedBy) {
+  return `served-by=${servedBy}`;
+}
+function renderScoreDecomposition(result) {
+  const parts = [`final=${formatScore(result.scoreDecomposition.final)}`];
+  const s = result.scoreDecomposition;
+  if (s.vector !== void 0) parts.push(`vector=${formatScore(s.vector)}`);
+  if (s.bm25 !== void 0) parts.push(`bm25=${formatScore(s.bm25)}`);
+  if (s.importance !== void 0) {
+    parts.push(`importance=${formatScore(s.importance)}`);
+  }
+  if (s.mmrPenalty !== void 0) {
+    parts.push(`mmr_penalty=${formatScore(s.mmrPenalty)}`);
+  }
+  if (s.tierPrior !== void 0) {
+    parts.push(`tier_prior=${formatScore(s.tierPrior)}`);
+  }
+  if (s.reinforcementBoost !== void 0 && s.reinforcementBoost > 0) {
+    parts.push(`reinforcement_boost=${formatScore(s.reinforcementBoost)}`);
+  }
+  return parts.join(" ");
+}
+function formatScore(value) {
+  if (!Number.isFinite(value)) return "0.0000";
+  return value.toFixed(4);
+}
+function formatCapturedAt(ts) {
+  if (!Number.isFinite(ts) || ts < 0) return "(unknown)";
+  try {
+    return new Date(ts).toISOString();
+  } catch {
+    return "(unknown)";
+  }
+}
+function mdEscape(value) {
+  return value.replace(/\\/g, "\\\\").replace(/\|/g, "\\|");
+}
+function mdInlineCode(value) {
+  if (value.length === 0) return "``";
+  const longestRun = /`+/g;
+  let maxLen = 0;
+  for (const match of value.matchAll(longestRun)) {
+    if (match[0].length > maxLen) maxLen = match[0].length;
+  }
+  const fence = "`".repeat(maxLen + 1);
+  const pad = value.startsWith("`") || value.endsWith("`") ? " " : "";
+  return `${fence}${pad}${value}${pad}${fence}`;
+}
+
+export {
+  RECALL_XRAY_FORMATS,
+  parseXrayFormat,
+  renderXray,
+  renderXrayJson,
+  renderXrayText,
+  renderXrayMarkdown,
+  toRecallExplainJson,
+  renderTierExplainTextLines,
+  toRecallExplainText,
+  toRecallXraySnapshotFromLegacy,
+  renderRecallExplain,
+  parseRecallExplainFormat
+};
+//# sourceMappingURL=chunk-FBYESMQ2.js.map