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 };
