import { RecallTierExplain, RecallDisclosure } from './types.js';
import './index-1qIcnbG1.js';

/**
 * Recall X-ray snapshot schema (issue #570, PR 1).
 *
 * The X-ray surface is the unified, per-result attribution document that
 * merges the tier that served each memory, its score decomposition, any
 * graph path, an audit entry id, and the exact filter/eligibility ladder
 * that either admitted or rejected each candidate.  This file defines the
 * schema and an in-memory builder + builder-state helper.
 *
 * Scope for PR 1 (this slice):
 *   - Types only + pure builder functions (no IO, no rendering).
 *   - Orchestrator plumbing captures a snapshot when the caller passes
 *     `xrayCapture: true`.  No behavior change when the flag is absent.
 *   - NO new public surfaces here — CLI/HTTP/MCP land in later slices.
 *
 * The shared renderer lands in PR 2 at `recall-xray-renderer.ts`.  Do not
 * fork formatting logic into other surfaces; extend the renderer.
 */

/**
 * Estimate token cost of a payload at the rough ~4 chars/token English
 * heuristic.  Non-negative integer; returns 0 for empty / null input.
 * Used by recall surfaces to attach `estimatedTokens` to X-ray results
 * (issue #677 PR 3/4).  Identical to the private heuristic in
 * `chunking.ts`; kept self-contained here so X-ray callers don't pull
 * in chunking internals.
 */
declare function estimateRecallTokens(text: string | null | undefined): number;
/**
 * Aggregated per-disclosure token spend summary, computed by the
 * renderer from a snapshot's results.  Non-negative integers.
 */
interface RecallXrayDisclosureSummary {
    chunk: {
        count: number;
        estimatedTokens: number;
    };
    section: {
        count: number;
        estimatedTokens: number;
    };
    raw: {
        count: number;
        estimatedTokens: number;
    };
    /** Number of results without a recorded disclosure level. */
    unspecified: {
        count: number;
        estimatedTokens: number;
    };
}
/**
 * Which retrieval source produced a given result.  This is the X-ray
 * tier ladder called out in issue #570 and is *distinct* from the
 * `RetrievalTier` enum (which describes issue #518's tier-explain
 * block).  Keeping the sets separate lets the two observability
 * surfaces evolve without conflating their vocabularies:
 *
 *   - `RetrievalTier`     — direct-answer eligibility ladder.
 *   - `RecallXrayServedBy` — which source materialized each result.
 */
type RecallXrayServedBy = "direct-answer" | "hybrid" | "graph" | "recent-scan" | "procedural" | "review-context" | "lcm-file-parts" | "lcm-tool-parts";
declare const RECALL_XRAY_SERVED_BY_VALUES: readonly RecallXrayServedBy[];
declare function isRecallXrayServedBy(value: unknown): value is RecallXrayServedBy;
/**
 * Score decomposition for a single X-ray result.
 *
 * All fields are optional because different tiers populate different
 * terms: `hybrid` reports vector + bm25 + mmr penalty, `direct-answer`
 * reports importance + tier prior, etc.  The only guaranteed field is
 * `final`, which is the post-combination score used for ordering.
 */
interface RecallXrayScoreDecomposition {
    vector?: number;
    bm25?: number;
    importance?: number;
    mmrPenalty?: number;
    tierPrior?: number;
    /** Additive boost from `reinforcement_count` frontmatter (issue #687 PR 3/4). */
    reinforcementBoost?: number;
    final: number;
}
/**
 * Per-result breakdown inside an X-ray snapshot.
 */
interface RecallXrayResult {
    memoryId: string;
    path: string;
    servedBy: RecallXrayServedBy;
    scoreDecomposition: RecallXrayScoreDecomposition;
    graphPath?: string[];
    /**
     * Issue #681 PR 3/3 — per-edge confidence values aligned with
     * `graphPath`. When present, `graphEdgeConfidences[i]` is the
     * confidence of the edge between `graphPath[i]` and `graphPath[i+1]`,
     * so the array length is one less than `graphPath`. Legacy edges
     * without a recorded confidence render as `1.0`. Operators use this
     * to attribute floor-pruning and PageRank ranking decisions back to
     * specific edges. The renderer drops the line when the array is
     * empty or absent so legacy snapshots round-trip cleanly.
     */
    graphEdgeConfidences?: number[];
    auditEntryId?: string;
    /** Human-readable list of filters the candidate *passed*. */
    admittedBy: string[];
    /**
     * First filter that *would have* rejected the candidate, or undefined
     * when the candidate was admitted without a rejection trace.  When
     * present, `admittedBy` may still contain filters the candidate passed
     * before the rejecting gate; consumers should render both.
     */
    rejectedBy?: string;
    /**
     * Disclosure depth used to render this result's payload (issue #677
     * PR 3/4).  Mirrors the per-result disclosure already exposed in the
     * recall response so X-ray consumers can attribute token spend to
     * the depth that produced it.
     */
    disclosure?: RecallDisclosure;
    /**
     * Estimated token cost of the rendered payload at the chosen
     * disclosure depth.  Non-negative integer.  Computed by callers via
     * `estimateRecallTokens(text)`; the renderer aggregates these into
     * a per-disclosure summary so operators can see where their budget
     * went.
     */
    estimatedTokens?: number;
    /**
     * Free-form tags from the memory's YAML frontmatter (issue #689 PR 3/3).
     * Populated by the X-ray capture path when the caller passes a `tags`
     * filter so per-result tags are available alongside the filter trace
     * in `snapshot.filters`.  Also populated without a filter when the
     * orchestrator decorates results via `xrayCapture: true` so all X-ray
     * consumers can inspect memory labels without a separate storage read.
     * Absent (not `[]`) when the frontmatter has no tags or the memory
     * could not be read.
     */
    tags?: string[];
}
/**
 * Trace entry for a filter the orchestrator evaluated during recall.
 * Captures the name of the filter, how many candidates it saw, and how
 * many it let through.  Used by X-ray consumers to render the filter
 * ladder above the per-result breakdown.
 */
interface RecallFilterTrace {
    name: string;
    considered: number;
    admitted: number;
    /** Optional human-readable reason for any rejections. */
    reason?: string;
}
/**
 * Peer-profile injection annotation (issue #679 completion).
 *
 * When `peerProfileRecallEnabled` is true and a peer is registered for
 * the session, the orchestrator injects a `## Peer Profile` section into
 * the recall context. This annotation records which peer was injected and
 * how many profile fields were included so operators can correlate
 * retrieval quality with peer-context enrichment.
 *
 * `null` means no peer profile was injected (peer not registered, feature
 * disabled, or peer has no profile fields).
 */
interface RecallXrayPeerProfileInjection {
    /** The peer id whose profile was injected. */
    peerId: string;
    /**
     * Number of profile fields included after the `peerProfileRecallMaxFields`
     * cap was applied.  Zero means the profile existed but had no fields.
     */
    fieldsInjected: number;
}
/**
 * The unified X-ray snapshot.  CLI, HTTP, and MCP surfaces all render
 * this same shape through the shared renderer (CLAUDE.md rule 22).
 */
interface RecallXraySnapshot {
    /** Stable v1 tag so downstream consumers can version-gate their parsers. */
    schemaVersion: "1";
    query: string;
    /** UUID minted per capture; unique across snapshots within a process. */
    snapshotId: string;
    /** Epoch milliseconds the snapshot was captured. */
    capturedAt: number;
    /**
     * Tier-explain block from issue #518, carried verbatim when present.
     * `null` means direct-answer tier did not run (disabled, or another
     * tier served the query).
     */
    tierExplain: RecallTierExplain | null;
    results: RecallXrayResult[];
    filters: RecallFilterTrace[];
    /**
     * Character budget accounting for the final assembled recall payload.
     * `used` is the rendered-context length; `chars` is the cap.  Both are
     * non-negative integers in `[0, 2**31)`.
     */
    budget: {
        chars: number;
        used: number;
    };
    /** Optional session-scope fields carried for downstream filtering. */
    sessionKey?: string;
    namespace?: string;
    traceId?: string;
    /**
     * Peer-profile injection metadata (issue #679 completion).
     * Non-null when `peerProfileRecallEnabled` is true and a peer profile
     * was successfully injected into this recall's context. `null` (or
     * absent) means no peer profile was injected.
     */
    peerProfileInjection?: RecallXrayPeerProfileInjection | null;
}
interface BuildXraySnapshotInput {
    query: string;
    tierExplain?: RecallTierExplain | null;
    results?: RecallXrayResult[];
    filters?: RecallFilterTrace[];
    budget?: {
        chars?: number;
        used?: number;
    };
    sessionKey?: string;
    namespace?: string;
    traceId?: string;
    /** Peer-profile injection metadata (issue #679 completion). */
    peerProfileInjection?: RecallXrayPeerProfileInjection | null;
    /** Optional injected timestamp for deterministic tests. */
    now?: () => number;
    /** Optional injected id generator for deterministic tests. */
    snapshotIdGenerator?: () => string;
}
/**
 * Build a `RecallXraySnapshot` from explicit input fields.  Pure
 * function; safe to call from anywhere.  All array/object inputs are
 * shallow-copied so caller mutation after build cannot tear the
 * returned snapshot.
 */
declare function buildXraySnapshot(input: BuildXraySnapshotInput): RecallXraySnapshot;
/**
 * Mutable builder used by the orchestrator to accumulate X-ray fields
 * as recall progresses.  Call `build()` to get the finalized
 * immutable-ish snapshot.  All inputs are validated at insert time so
 * a malformed entry cannot poison the snapshot later.
 */
declare class RecallXrayBuilder {
    private readonly query;
    private readonly sessionKey;
    private namespace;
    private traceId;
    private tierExplain;
    private readonly results;
    private readonly filters;
    private budgetChars;
    private budgetUsed;
    private peerProfileInjection;
    constructor(opts: {
        query: string;
        sessionKey?: string;
        namespace?: string;
        traceId?: string;
    });
    setNamespace(namespace: string | undefined): void;
    setTraceId(traceId: string | undefined): void;
    setTierExplain(tierExplain: RecallTierExplain | null | undefined): void;
    setBudget(budget: {
        chars?: number;
        used?: number;
    }): void;
    /**
     * Record peer-profile injection metadata for this recall snapshot
     * (issue #679 completion). Pass `null` to explicitly record that no
     * injection happened (feature enabled but no peer / no profile fields).
     */
    setPeerProfileInjection(injection: RecallXrayPeerProfileInjection | null): void;
    recordResult(result: RecallXrayResult): void;
    recordFilter(filter: RecallFilterTrace): void;
    build(opts?: {
        now?: () => number;
        snapshotIdGenerator?: () => string;
    }): RecallXraySnapshot;
}
/**
 * Summarize per-disclosure token spend across an X-ray snapshot's
 * results.  Pure helper — used by the markdown renderer to print a
 * "per-disclosure token spend" line and exposed for tests / surfaces.
 */
declare function summarizeDisclosureTokens(results: ReadonlyArray<RecallXrayResult>): RecallXrayDisclosureSummary;

export { type BuildXraySnapshotInput, RECALL_XRAY_SERVED_BY_VALUES, type RecallFilterTrace, RecallXrayBuilder, type RecallXrayDisclosureSummary, type RecallXrayPeerProfileInjection, type RecallXrayResult, type RecallXrayScoreDecomposition, type RecallXrayServedBy, type RecallXraySnapshot, buildXraySnapshot, estimateRecallTokens, isRecallXrayServedBy, summarizeDisclosureTokens };
