import type { SessionEvidenceScope, SessionTextEvidenceSource } from '../store/evidence/types.js';
import type { PrepareStep, PrepareStepContext } from '../types/session/prepare-step.js';
/** @experimental An authenticated historical passage, never a current-state assertion. */
export interface EvidenceRecallCandidate {
    readonly scope: SessionEvidenceScope;
    readonly seq: number;
    /** Optional stored-event wall-clock Unix milliseconds, not fact time or causal order. */
    readonly recordedAt?: number;
    readonly part: number;
    readonly source: string;
    readonly toolName?: string;
    readonly isError?: boolean;
    readonly retained: 'full' | 'preview';
    readonly excerpt: string;
    /** Whole full-retained text part; false is partial/preview, absent is unknown. */
    readonly excerptComplete?: boolean;
    readonly byteOffset?: number;
}
/** @experimental The host enforces the read ceiling, ownership and source integrity. */
export interface EvidenceRecallRequest {
    /** The session the recall is for; the host binds retrieval to it. */
    readonly sessionId: string;
    /** The turn asking. */
    readonly turnId: string;
    /** Optional current writer; bound to this recall's cancellation and deadline. */
    readonly captureSessionEvidence?: (maxReadBytes?: number) => Promise<SessionTextEvidenceSource | undefined>;
    readonly terms: readonly string[];
    readonly maxReadBytes: number;
    readonly maxCandidates: number;
    readonly signal: AbortSignal;
}
/** @experimental Incomplete is not proof that unmatched evidence does not exist. */
export interface EvidenceRecallBatch {
    readonly candidates: readonly EvidenceRecallCandidate[];
    readonly scannedBytes: number;
    readonly incomplete: boolean;
    /** Successful tool-result visits excluded during this scan; not a count of unique facts. */
    readonly excludedToolResults?: number;
    /** Deliberately excluded derived-summary visits, not unique facts. */
    readonly excludedSummaries?: number;
    /** Optional host-mounted read-only calls continuing this incomplete scan. At most four. */
    readonly continuations?: readonly EvidenceRecallContinuation[];
}
/** @experimental Hints confer no authority; the host tool must revalidate ownership and source. */
export interface EvidenceRecallContinuation {
    readonly toolName: string;
    readonly input: Readonly<Record<string, string | number | boolean | null>>;
}
/** @experimental Local retrieval with optional turn-metered query resolution. */
export interface EvidenceRecallOptions {
    readonly scope: Omit<SessionEvidenceScope, 'turnId'>;
    readonly retrieve: (request: EvidenceRecallRequest) => Promise<EvidenceRecallBatch>;
    /** Entire added context, including labels. Default 6,000; maximum 12,000 UTF-16 units. */
    readonly maxChars?: number;
    /** Default 4; maximum 8 new passages plus visible quotes combined, from at most 24 candidates. */
    readonly maxPassages?: number;
    /** Default 1,000ms; maximum 10,000ms. Late results are discarded. */
    readonly timeoutMs?: number;
    /** Host fallback only when latestUserMessage is absent. */
    readonly query?: string;
    /** Resolve references through one turn-metered preparation call per operator input. Default false. */
    readonly resolveQuery?: boolean;
}
export type ScopedEvidenceRecallCandidate = Omit<EvidenceRecallCandidate, 'part'> & {
    readonly part?: number;
};
export interface ScopedEvidenceRecallBatch extends Omit<EvidenceRecallBatch, 'candidates'> {
    readonly candidates: readonly ScopedEvidenceRecallCandidate[];
}
interface ScopedEvidenceRecallOptions extends Omit<EvidenceRecallOptions, 'scope' | 'retrieve'> {
    readonly retrieve: (request: EvidenceRecallRequest) => Promise<ScopedEvidenceRecallBatch>;
}
interface EvidenceRecallBoundary {
    readonly kind: 'conversation' | 'resident';
    readonly validate: (candidate: ScopedEvidenceRecallCandidate) => void;
    readonly address: (candidate: ScopedEvidenceRecallCandidate) => Readonly<Record<string, unknown>>;
    readonly selectQuery?: (context: PrepareStepContext) => {
        readonly terms: readonly string[];
        readonly metadata: Readonly<Record<string, unknown>>;
    };
}
/**
 * @experimental Suggest a strict query subset not yet covered by bounded excerpts.
 * This is lexical coverage, not relevance or proof of absence from the archive.
 * Hosts may spend an existing page on it, retaining the original continuation.
 * Accepts 1–16 single-token terms (≤256 UTF-16 units) and ≤24 excerpts (≤512 each).
 * Returns undefined when no terms or all terms were observed; never performs I/O.
 */
export declare function refineEvidenceRecallTerms(terms: readonly string[], excerpts: readonly string[]): string[] | undefined;
/** Internal bounded literal selection shared by the two authority adapters. */
export declare function evidenceRecallQueryTokens(text: string): string[];
/**
 * Recall scoped evidence into ephemeral trailing request context. No historical
 * messages or system guidance are changed. Every step revalidates its source;
 * timeout/error reaches the runtime's diagnostic and bounded availability context,
 * never a cached fact or raw error body in model input.
 */
export declare function createEvidenceRecallStep(options: EvidenceRecallOptions): PrepareStep;
/** Internal shared selection engine; callers retain their own authority boundary. */
export declare function createScopedEvidenceRecallStep(options: ScopedEvidenceRecallOptions, boundary: EvidenceRecallBoundary): PrepareStep;
export {};
//# sourceMappingURL=evidence-recall.d.ts.map