import type { Embedder, MarginCandidate, MarginResult } from './types.js';
export interface ScoreMarginArgs {
    /** The offered candidates (e.g. the tool catalog on `llm_start`). */
    readonly candidates: readonly MarginCandidate[];
    /** The choice context — the text the chooser ranked against. */
    readonly contextText: string;
    /** Names of the chosen candidate(s). Must exist in `candidates`. */
    readonly chosen: readonly string[];
    /**
     * Injected embedder. Wrap in an `EmbeddingCache` so descriptions
     * embed once across calls (RFC-002 §3 — the same cache the catalog
     * lint already filled).
     */
    readonly embedder: Embedder;
    /** Margins below this flag `narrow`. Default 0.05 (RFC-002 §4). */
    readonly marginThreshold?: number;
    /** Abort signal threaded to the embedder (network backends). */
    readonly signal?: AbortSignal;
}
/**
 * Rank candidates by cosine similarity to the choice context and
 * measure how decisively the chosen one(s) won.
 *
 * Returns ranked `scores` (descending; ties keep candidate input
 * order), the `topScored` name, the `margin` (undefined when every
 * candidate was chosen — no competition to measure; `narrow` is false
 * in that case), and the two flags.
 *
 * Fail-loud validation: empty candidates/chosen, duplicate candidate
 * names, or a chosen name missing from the candidates throw — those
 * are wiring bugs in the caller, not runtime conditions.
 */
export declare function scoreMargin(args: ScoreMarginArgs): Promise<MarginResult>;