@remnic/core 1.1.12 → 1.1.13

package/src/recall-disclosure-escalation.ts

@@ -0,0 +1,158 @@
+/**
+ * Recall disclosure auto-escalation policy (issue #677 PR 4/4).
+ *
+ * Pure helper that decides the *effective* disclosure depth for a recall
+ * given the configured policy and the observed top-K confidence.  Lives
+ * outside `access-service.ts` so the decision logic can be unit-tested
+ * exhaustively without booting an orchestrator.
+ *
+ * Policy summary:
+ *
+ *   manual (default):
+ *     The caller's `disclosure` is honored verbatim.  Auto-escalation
+ *     does not run.
+ *
+ *   auto:
+ *     If the caller did NOT explicitly specify a disclosure (i.e. the
+ *     value in use is the system default) AND the recall's top-K
+ *     confidence falls below the configured threshold, escalate from
+ *     `chunk` to `section`.  `raw` is never auto-selected — it requires
+ *     an explicit caller request because of its higher cost and the
+ *     LCM-archive read paths it activates.  If the caller explicitly
+ *     passed a disclosure (even `chunk`), the policy respects that
+ *     choice and does not escalate.
+ *
+ * The threshold compares against `final` from the top result's score
+ * decomposition.  When the snapshot has no results or no scores, no
+ * escalation fires (`undefined` confidence is treated as "skip" rather
+ * than "always escalate").
+ */
+
+import type { RecallDisclosure } from "./types.js";
+
+export type DisclosureEscalationMode = "manual" | "auto";
+
+export const DISCLOSURE_ESCALATION_MODES: readonly DisclosureEscalationMode[] = [
+  "manual",
+  "auto",
+] as const;
+
+export function isDisclosureEscalationMode(
+  value: unknown,
+): value is DisclosureEscalationMode {
+  return (
+    typeof value === "string" &&
+    (DISCLOSURE_ESCALATION_MODES as readonly string[]).includes(value)
+  );
+}
+
+/**
+ * Threshold defaults — applied when config-side coercion produces an
+ * out-of-range or missing value.  0.5 is a deliberate midpoint:
+ * confidently-served recalls (top-K >= 0.5) stay on the cheap chunk
+ * tier; ambiguous recalls escalate to section.
+ */
+export const DEFAULT_DISCLOSURE_ESCALATION_THRESHOLD = 0.5;
+
+export interface DisclosureEscalationDecision {
+  /** The disclosure depth the caller should use to shape the response. */
+  effective: RecallDisclosure;
+  /**
+   * `true` when the policy escalated from the original disclosure;
+   * `false` when the original was kept (either by manual mode, by
+   * caller explicit choice, or because confidence stayed above the
+   * threshold).
+   */
+  escalated: boolean;
+  /**
+   * Human-readable reason for the decision.  Always populated; surfaces
+   * in operator-facing telemetry / debug paths.
+   */
+  reason: string;
+}
+
+export interface DecideDisclosureEscalationInput {
+  /** The mode from config (`manual` | `auto`). */
+  mode: DisclosureEscalationMode;
+  /** Threshold in [0, 1]; values outside this range fall back to the default. */
+  threshold: number;
+  /** Disclosure resolved at request time (after default-fill). */
+  originalDisclosure: RecallDisclosure;
+  /**
+   * Whether the caller explicitly specified a disclosure value.  Auto
+   * mode only acts when the caller did NOT specify, so explicit
+   * `chunk` requests are not silently upgraded.
+   */
+  callerProvidedDisclosure: boolean;
+  /**
+   * Top-K confidence (`final` score from the highest-ranked result),
+   * or `undefined` when the snapshot has no scored results.
+   */
+  topKConfidence: number | undefined;
+}
+
+/**
+ * Decide whether to escalate disclosure depth based on policy + signals.
+ * Pure function — no IO, no state.
+ */
+export function decideDisclosureEscalation(
+  input: DecideDisclosureEscalationInput,
+): DisclosureEscalationDecision {
+  if (input.mode === "manual") {
+    return {
+      effective: input.originalDisclosure,
+      escalated: false,
+      reason: "escalation-mode=manual",
+    };
+  }
+
+  if (input.callerProvidedDisclosure) {
+    return {
+      effective: input.originalDisclosure,
+      escalated: false,
+      reason: "caller-explicit-disclosure",
+    };
+  }
+
+  // Only chunk → section auto-escalation is allowed.  Section and raw
+  // are never demoted; raw is never auto-selected.
+  if (input.originalDisclosure !== "chunk") {
+    return {
+      effective: input.originalDisclosure,
+      escalated: false,
+      reason: `original-disclosure=${input.originalDisclosure}-not-eligible-for-auto`,
+    };
+  }
+
+  if (
+    input.topKConfidence === undefined ||
+    !Number.isFinite(input.topKConfidence)
+  ) {
+    return {
+      effective: input.originalDisclosure,
+      escalated: false,
+      reason: "no-top-k-confidence",
+    };
+  }
+
+  const threshold =
+    Number.isFinite(input.threshold) &&
+    input.threshold >= 0 &&
+    input.threshold <= 1
+      ? input.threshold
+      : DEFAULT_DISCLOSURE_ESCALATION_THRESHOLD;
+
+  if (input.topKConfidence < threshold) {
+    return {
+      effective: "section",
+      escalated: true,
+      reason: `top-k-confidence=${input.topKConfidence.toFixed(3)}<${threshold}`,
+    };
+  }
+
+  return {
+    effective: input.originalDisclosure,
+    escalated: false,
+    reason: `top-k-confidence=${input.topKConfidence.toFixed(3)}>=${threshold}`,
+  };
+}

package/src/recall-disclosure-shaping.test.ts

@@ -0,0 +1,146 @@
+/**
+ * Tests for the recall-disclosure payload-shaping wired in PR 2/4 of
+ * issue #677 — covers the new `content` and `rawExcerpts` fields on
+ * `EngramAccessMemorySummary`, the CLI flag-validation surface, and the
+ * HTTP `?disclosure=` query-parameter fallback.
+ *
+ * Pure-helper coverage runs against the exported `shapeMemorySummary()`
+ * so we can exercise every disclosure level without booting an
+ * orchestrator or a network surface.  All fixtures are synthetic — no
+ * real conversation data.
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { shapeMemorySummary } from "./access-service.js";
+import type { MemoryFile } from "./types.js";
+import { isRecallDisclosure, RECALL_DISCLOSURE_LEVELS } from "./types.js";
+
+function buildMemoryFixture(content: string): MemoryFile {
+  // Synthesized — no real user data per the public-repo policy.
+  return {
+    path: "/tmp/mem/abcd1234.md",
+    content,
+    frontmatter: {
+      id: "abcd1234",
+      category: "preference",
+      created: "2026-04-25T00:00:00Z",
+      updated: "2026-04-25T00:00:00Z",
+      source: "test",
+      confidence: 0.9,
+      confidenceTier: "explicit",
+      tags: ["fixture", "shape-test"],
+    },
+  };
+}
+
+// ──────────────────────────────────────────────────────────────────────
+// shapeMemorySummary() pure-helper coverage.
+// ──────────────────────────────────────────────────────────────────────
+
+test("shapeMemorySummary: chunk emits preview only — no content / rawExcerpts", () => {
+  const memory = buildMemoryFixture("Synthetic full body text for chunk test.");
+  const out = shapeMemorySummary(memory, "/tmp/mem", "chunk");
+  assert.strictEqual(out.disclosure, "chunk");
+  assert.ok(out.preview.length > 0);
+  assert.strictEqual(out.content, undefined);
+  assert.strictEqual(out.rawExcerpts, undefined);
+});
+
+test("shapeMemorySummary: section attaches the full memory body as `content`", () => {
+  const body = "Section disclosure must surface the entire markdown body.";
+  const memory = buildMemoryFixture(body);
+  const out = shapeMemorySummary(memory, "/tmp/mem", "section");
+  assert.strictEqual(out.disclosure, "section");
+  assert.strictEqual(out.content, body);
+  // No raw excerpts at section depth — rawExcerpts is reserved for raw.
+  assert.strictEqual(out.rawExcerpts, undefined);
+});
+
+test("shapeMemorySummary: raw attaches both full content and the supplied raw excerpts", () => {
+  const body = "Raw disclosure exposes content + transcript excerpts.";
+  const memory = buildMemoryFixture(body);
+  const excerpts = [
+    { turnIndex: 0, role: "user", content: "synthetic-q", sessionId: "s-1" },
+    { turnIndex: 1, role: "assistant", content: "synthetic-a", sessionId: "s-1" },
+  ];
+  const out = shapeMemorySummary(memory, "/tmp/mem", "raw", excerpts);
+  assert.strictEqual(out.disclosure, "raw");
+  assert.strictEqual(out.content, body);
+  assert.deepStrictEqual(out.rawExcerpts, excerpts);
+});
+
+test("shapeMemorySummary: raw with empty excerpts attaches an empty array (LCM disabled)", () => {
+  const memory = buildMemoryFixture("body");
+  const out = shapeMemorySummary(memory, "/tmp/mem", "raw", []);
+  assert.strictEqual(out.disclosure, "raw");
+  assert.strictEqual(out.content, "body");
+  assert.deepStrictEqual(out.rawExcerpts, []);
+});
+
+test("shapeMemorySummary: undefined disclosure (browse path) omits all three new fields", () => {
+  const memory = buildMemoryFixture("browse projection");
+  const out = shapeMemorySummary(memory, "/tmp/mem");
+  assert.strictEqual(out.disclosure, undefined);
+  assert.strictEqual(out.content, undefined);
+  assert.strictEqual(out.rawExcerpts, undefined);
+  // preview always populated — regardless of disclosure.
+  assert.ok(out.preview.length > 0);
+});
+
+test("shapeMemorySummary: section depth ignores rawExcerpts even when supplied", () => {
+  // Defensive: the recall path should never pass rawExcerpts at section
+  // depth, but a regression that did so must not leak excerpts onto the
+  // section-shaped payload.
+  const memory = buildMemoryFixture("body");
+  const out = shapeMemorySummary(memory, "/tmp/mem", "section", [
+    { turnIndex: 0, role: "user", content: "x", sessionId: "s" },
+  ]);
+  assert.strictEqual(out.rawExcerpts, undefined);
+});
+
+// ──────────────────────────────────────────────────────────────────────
+// CLI `--disclosure` flag validation parity check.
+//
+// The CLI path uses the same `isRecallDisclosure` guard as the service
+// layer; this test pins the contract so a future regression that loosens
+// validation in one path but not the other is caught.
+// ──────────────────────────────────────────────────────────────────────
+
+test("CLI parity: isRecallDisclosure() rejects values the CLI must reject", () => {
+  // Common typos / casing variants the CLI must throw on so operators
+  // notice their flag misuse instead of silently getting `chunk`.
+  for (const bad of ["", "Chunk", "CHUNK", "full", "raw_excerpt", "tier", "section "]) {
+    assert.strictEqual(isRecallDisclosure(bad), false, `bad=${JSON.stringify(bad)}`);
+  }
+});
+
+test("CLI parity: every documented disclosure level is accepted", () => {
+  for (const level of RECALL_DISCLOSURE_LEVELS) {
+    assert.strictEqual(isRecallDisclosure(level), true);
+  }
+});
+
+// ──────────────────────────────────────────────────────────────────────
+// HTTP `?disclosure=` query-param fallback contract.
+//
+// The HTTP route delegates parsing to `isRecallDisclosure` after reading
+// the query parameter.  We verify the contract here so a refactor that
+// stops calling the guard in `access-http.ts` would surface in CI.
+// ──────────────────────────────────────────────────────────────────────
+
+test("HTTP query-param parity: known levels round-trip through isRecallDisclosure", () => {
+  const url = new URL("http://localhost/engram/v1/recall?disclosure=section");
+  const value = url.searchParams.get("disclosure");
+  assert.ok(value !== null);
+  assert.strictEqual(isRecallDisclosure(value), true);
+  assert.strictEqual(value, "section");
+});
+
+test("HTTP query-param parity: unknown level fails the guard so callers get a 4xx", () => {
+  const url = new URL("http://localhost/engram/v1/recall?disclosure=full");
+  const value = url.searchParams.get("disclosure");
+  assert.ok(value !== null);
+  assert.strictEqual(isRecallDisclosure(value), false);
+});

package/src/recall-disclosure.test.ts

@@ -0,0 +1,214 @@
+/**
+ * Tests for the recall disclosure-depth plumbing introduced in PR 1/4 of
+ * issue #677.  Covers:
+ *
+ *  - Type-level constants (`DEFAULT_RECALL_DISCLOSURE`,
+ *    `RECALL_DISCLOSURE_LEVELS`).
+ *  - The `isRecallDisclosure()` type guard.
+ *  - The zod `recallRequestSchema` accept/reject behavior for the new
+ *    `disclosure` field.
+ *  - The MCP `engram.recall` handler forwards `disclosure` to the service
+ *    layer instead of silently dropping it (regression for the
+ *    cursor[bot] / codex review feedback on PR #694).
+ *
+ * Full surface integration tests (HTTP path, CLI flag) ship with their
+ * respective surface work in PR 2/4.  Auto-escalation tests ship in
+ * PR 4/4.  All fixtures are synthetic — no real user data.
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  DEFAULT_RECALL_DISCLOSURE,
+  RECALL_DISCLOSURE_LEVELS,
+  isRecallDisclosure,
+} from "./types.js";
+import { recallRequestSchema, validateRequest } from "./access-schema.js";
+import { EngramMcpServer } from "./access-mcp.js";
+import type { EngramAccessRecallRequest, EngramAccessService } from "./access-service.js";
+
+test("RECALL_DISCLOSURE_LEVELS is ordered chunk -> section -> raw", () => {
+  // Order matters for future escalation policy comparisons (PR 4/4).  The
+  // ladder must be stable; freezing here so a refactor that flips order is
+  // caught immediately.
+  assert.deepStrictEqual(
+    [...RECALL_DISCLOSURE_LEVELS],
+    ["chunk", "section", "raw"],
+  );
+});
+
+test("DEFAULT_RECALL_DISCLOSURE is 'chunk' (preserves pre-#677 behavior)", () => {
+  assert.strictEqual(DEFAULT_RECALL_DISCLOSURE, "chunk");
+});
+
+test("isRecallDisclosure() accepts the three valid levels", () => {
+  for (const level of RECALL_DISCLOSURE_LEVELS) {
+    assert.strictEqual(isRecallDisclosure(level), true, `level=${level}`);
+  }
+});
+
+test("isRecallDisclosure() rejects unknown strings, casing variants, and non-strings", () => {
+  for (const bad of ["", "Chunk", "CHUNK", "section ", "full", "raw_excerpt", "tier"]) {
+    assert.strictEqual(isRecallDisclosure(bad), false, `bad=${JSON.stringify(bad)}`);
+  }
+  for (const bad of [null, undefined, 0, 1, true, false, {}, []]) {
+    assert.strictEqual(isRecallDisclosure(bad as unknown), false);
+  }
+});
+
+test("recallRequestSchema: omitting disclosure is valid (default applied at service layer)", () => {
+  const result = recallRequestSchema.safeParse({ query: "hello" });
+  assert.strictEqual(result.success, true);
+  if (result.success) {
+    assert.strictEqual(result.data.disclosure, undefined);
+  }
+});
+
+test("recallRequestSchema: each documented disclosure level is accepted", () => {
+  for (const level of RECALL_DISCLOSURE_LEVELS) {
+    const result = recallRequestSchema.safeParse({ query: "hello", disclosure: level });
+    assert.strictEqual(result.success, true, `level=${level}`);
+    if (result.success) {
+      assert.strictEqual(result.data.disclosure, level);
+    }
+  }
+});
+
+test("recallRequestSchema: invalid disclosure is rejected with field-level error", () => {
+  const result = recallRequestSchema.safeParse({ query: "hello", disclosure: "full" });
+  assert.strictEqual(result.success, false);
+});
+
+test("validateRequest('recall') surfaces disclosure validation errors with structured detail", () => {
+  const outcome = validateRequest("recall", { query: "hello", disclosure: "verbose" });
+  assert.strictEqual(outcome.success, false);
+  if (!outcome.success) {
+    assert.strictEqual(outcome.error.code, "validation_error");
+    const fields = outcome.error.details.map((d) => d.field);
+    assert.ok(fields.includes("disclosure"), `expected disclosure field error, got ${JSON.stringify(fields)}`);
+  }
+});
+
+// ──────────────────────────────────────────────────────────────────────────
+// MCP handler must forward `disclosure` to the service layer.
+//
+// Regression coverage for the review feedback on PR #694: schema-level
+// validation alone is not enough — the handler must actually pass the
+// validated field through, otherwise callers see a silent default.
+// ──────────────────────────────────────────────────────────────────────────
+
+function makeMcpRecallSpyService(): {
+  service: EngramAccessService;
+  calls: EngramAccessRecallRequest[];
+} {
+  const calls: EngramAccessRecallRequest[] = [];
+  const service = {
+    briefingEnabled: false,
+    recall: (req: EngramAccessRecallRequest) => {
+      calls.push(req);
+      return Promise.resolve({
+        query: req.query,
+        sessionKey: req.sessionKey,
+        namespace: "default",
+        context: "",
+        count: 0,
+        memoryIds: [],
+        results: [],
+        fallbackUsed: false,
+        sourcesUsed: [],
+        disclosure: req.disclosure ?? DEFAULT_RECALL_DISCLOSURE,
+      });
+    },
+  } as unknown as EngramAccessService;
+  return { service, calls };
+}
+
+test("MCP engram.recall handler forwards explicit `disclosure` to the service", async () => {
+  const { service, calls } = makeMcpRecallSpyService();
+  const server = new EngramMcpServer(service);
+  await server.handleRequest({
+    jsonrpc: "2.0",
+    id: 1,
+    method: "tools/call",
+    params: {
+      name: "engram.recall",
+      arguments: { query: "hello", disclosure: "raw" },
+    },
+  });
+  assert.strictEqual(calls.length, 1);
+  assert.strictEqual(calls[0]?.disclosure, "raw");
+});
+
+test("MCP engram.recall handler omits `disclosure` when caller does not supply it", async () => {
+  // The service layer owns default-application; the handler should pass
+  // `undefined` (not `"chunk"`) when the caller did not provide a value
+  // so the single source of truth stays in `EngramAccessService.recall()`.
+  const { service, calls } = makeMcpRecallSpyService();
+  const server = new EngramMcpServer(service);
+  await server.handleRequest({
+    jsonrpc: "2.0",
+    id: 2,
+    method: "tools/call",
+    params: { name: "engram.recall", arguments: { query: "hello" } },
+  });
+  assert.strictEqual(calls.length, 1);
+  assert.strictEqual(calls[0]?.disclosure, undefined);
+});
+
+test("MCP engram.recall rejects non-string disclosure with a structured error", async () => {
+  // Codex review on PR #694: a number (e.g. `1`) used to be coerced to
+  // `undefined`, masking malformed input and silently applying the
+  // chunk default.  The handler now distinguishes "absent" from
+  // "present-but-wrong-type" and throws a structured error for the
+  // latter.  The MCP transport surfaces tool errors as `isError: true`.
+  const { service, calls } = makeMcpRecallSpyService();
+  const server = new EngramMcpServer(service);
+  const response = await server.handleRequest({
+    jsonrpc: "2.0",
+    id: 3,
+    method: "tools/call",
+    params: {
+      name: "engram.recall",
+      arguments: { query: "hello", disclosure: 1 as unknown as string },
+    },
+  });
+  assert.strictEqual(calls.length, 0, "service.recall must not be called for invalid input");
+  const result = (response as { result?: { isError?: boolean; content?: Array<{ text?: string }> } } | undefined)?.result;
+  assert.strictEqual(result?.isError, true);
+  const text = result?.content?.[0]?.text ?? "";
+  assert.match(text, /disclosure must be a string/i);
+});
+
+test("MCP engram.recall treats explicit `null` disclosure as absent (service applies default)", async () => {
+  // JSON-RPC clients sometimes serialize an unset field as `null`.
+  // Treat `null` like absence so the service-layer default path runs
+  // — matches `EngramAccessService.recall()`'s own null-tolerance.
+  const { service, calls } = makeMcpRecallSpyService();
+  const server = new EngramMcpServer(service);
+  await server.handleRequest({
+    jsonrpc: "2.0",
+    id: 4,
+    method: "tools/call",
+    params: {
+      name: "engram.recall",
+      arguments: { query: "hello", disclosure: null as unknown as string },
+    },
+  });
+  assert.strictEqual(calls.length, 1);
+  assert.strictEqual(calls[0]?.disclosure, undefined);
+});
+
+test("MCP engram.recall inputSchema advertises the `disclosure` enum", () => {
+  // MCP clients with strict validation reject unknown fields; the
+  // tool-list schema must declare `disclosure` so legitimate clients
+  // can use it.
+  const { service } = makeMcpRecallSpyService();
+  const server = new EngramMcpServer(service);
+  const tools = (server as unknown as { tools: Array<{ name: string; inputSchema: { properties?: Record<string, unknown> } }> }).tools;
+  const recallTool = tools.find((t) => t.name === "engram.recall");
+  assert.ok(recallTool, "engram.recall tool should be registered");
+  const props = recallTool?.inputSchema?.properties as Record<string, { type?: string; enum?: string[] }> | undefined;
+  assert.ok(props && "disclosure" in props, "engram.recall inputSchema must declare 'disclosure'");
+  assert.deepStrictEqual(props?.disclosure?.enum, ["chunk", "section", "raw"]);
+});

package/src/recall-explain-renderer.test.ts

@@ -0,0 +1,140 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import type { LastRecallSnapshot } from "./recall-state.js";
+import {
+  parseRecallExplainFormat,
+  renderRecallExplain,
+  toRecallXraySnapshotFromLegacy,
+} from "./recall-explain-renderer.js";
+
+function legacySnapshot(
+  overrides: Partial<LastRecallSnapshot> = {},
+): LastRecallSnapshot {
+  return {
+    sessionKey: "sess-42",
+    recordedAt: "2023-11-14T22:13:20.000Z",
+    queryHash: "deadbeef",
+    queryLen: 21,
+    memoryIds: ["mem-1", "mem-2"],
+    source: "hot_qmd",
+    sourcesUsed: ["hot_qmd", "memories"],
+    namespace: "workspace-a",
+    latencyMs: 42,
+    ...overrides,
+  };
+}
+
+// ─── parseRecallExplainFormat ────────────────────────────────────────────
+
+test("parseRecallExplainFormat accepts the original text+json formats", () => {
+  assert.equal(parseRecallExplainFormat("text"), "text");
+  assert.equal(parseRecallExplainFormat("json"), "json");
+});
+
+test("parseRecallExplainFormat accepts the new markdown format", () => {
+  assert.equal(parseRecallExplainFormat("markdown"), "markdown");
+  assert.equal(parseRecallExplainFormat("  MARKDOWN  "), "markdown");
+});
+
+test("parseRecallExplainFormat rejects unknown formats with a listed-options error", () => {
+  assert.throws(
+    () => parseRecallExplainFormat("xml"),
+    /--format expects "text", "json", or "markdown"/,
+  );
+});
+
+test("parseRecallExplainFormat defaults to text when absent", () => {
+  assert.equal(parseRecallExplainFormat(undefined), "text");
+  assert.equal(parseRecallExplainFormat(null), "text");
+});
+
+// ─── backward compatibility: text + json unchanged ───────────────────────
+
+test("renderRecallExplain text output is unchanged from pre-#570 behavior", () => {
+  const out = renderRecallExplain(legacySnapshot(), "text");
+  assert.ok(out.startsWith("=== Recall Explain ==="));
+  assert.ok(out.includes("session: sess-42"));
+  assert.ok(out.includes("source: hot_qmd"));
+  assert.ok(out.includes("memories: mem-1, mem-2"));
+  // The tier-explain section is absent because legacy snapshot has
+  // no tierExplain field populated.
+  assert.ok(out.includes("tier-explain: (not populated"));
+});
+
+test("renderRecallExplain json output is unchanged JSON shape", () => {
+  const out = renderRecallExplain(legacySnapshot(), "json");
+  const parsed = JSON.parse(out);
+  assert.equal(parsed.hasExplain, false);
+  assert.equal(parsed.snapshotFound, true);
+  assert.equal(parsed.sessionKey, "sess-42");
+  assert.deepEqual(parsed.memoryIds, ["mem-1", "mem-2"]);
+});
+
+// ─── markdown delegation ─────────────────────────────────────────────────
+
+test("renderRecallExplain markdown delegates to the shared X-ray renderer", () => {
+  const out = renderRecallExplain(legacySnapshot(), "markdown");
+  // X-ray markdown always opens with an H1.
+  assert.ok(out.startsWith("# Recall X-ray"));
+  // Session + namespace from the legacy snapshot round-trip into the
+  // markdown table.
+  assert.ok(out.includes("| Session | `sess-42` |"));
+  assert.ok(out.includes("| Namespace | `workspace-a` |"));
+  // Memory ids become H3 result sections.
+  assert.ok(out.includes("### 1. `mem-1` — served-by=hybrid"));
+  assert.ok(out.includes("### 2. `mem-2` — served-by=hybrid"));
+});
+
+test("renderRecallExplain markdown handles null snapshot via the renderer's placeholder", () => {
+  const out = renderRecallExplain(null, "markdown");
+  assert.equal(out, "# Recall X-ray\n\n_No X-ray snapshot captured._");
+});
+
+// ─── toRecallXraySnapshotFromLegacy adapter ──────────────────────────────
+
+test("toRecallXraySnapshotFromLegacy returns null for a null input", () => {
+  assert.equal(toRecallXraySnapshotFromLegacy(null), null);
+});
+
+test("toRecallXraySnapshotFromLegacy translates recordedAt to capturedAt epoch ms", () => {
+  const xray = toRecallXraySnapshotFromLegacy(legacySnapshot());
+  assert.ok(xray);
+  assert.equal(xray?.capturedAt, 1_700_000_000_000);
+});
+
+test("toRecallXraySnapshotFromLegacy preserves session / namespace / memory ids", () => {
+  const xray = toRecallXraySnapshotFromLegacy(legacySnapshot());
+  assert.equal(xray?.sessionKey, "sess-42");
+  assert.equal(xray?.namespace, "workspace-a");
+  assert.equal(xray?.results.length, 2);
+  assert.equal(xray?.results[0]?.memoryId, "mem-1");
+});
+
+test("toRecallXraySnapshotFromLegacy copes with malformed recordedAt", () => {
+  const xray = toRecallXraySnapshotFromLegacy(
+    legacySnapshot({ recordedAt: "not-a-date" }),
+  );
+  assert.equal(xray?.capturedAt, 0);
+});
+
+test("toRecallXraySnapshotFromLegacy propagates snapshot.source to servedBy", () => {
+  // Codex P2 + Cursor Medium on #605: every converted result used to
+  // be stamped with `servedBy: "hybrid"`, misattributing legacy
+  // snapshots from a non-hybrid source (notably `recent_scan`).
+  const recent = toRecallXraySnapshotFromLegacy(
+    legacySnapshot({ source: "recent_scan" }),
+  );
+  assert.equal(recent?.results[0]?.servedBy, "recent-scan");
+  assert.equal(recent?.results[1]?.servedBy, "recent-scan");
+
+  for (const source of ["hot_qmd", "hot_embedding", "cold_fallback", "none"]) {
+    const xray = toRecallXraySnapshotFromLegacy(legacySnapshot({ source }));
+    assert.equal(xray?.results[0]?.servedBy, "hybrid", `source=${source}`);
+  }
+  const unknown = toRecallXraySnapshotFromLegacy(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    legacySnapshot({ source: "future_tier" as any }),
+  );
+  assert.equal(unknown?.results[0]?.servedBy, "hybrid");
+});