export interface ValuePerTokenCandidate<T> {
    /** Stable identity for dedup + reporting. */
    id: string;
    /** The underlying payload returned to the caller in `selected`. */
    payload: T;
    /** Caller-computed relevance score; the only constraint is that higher
     *  values mean MORE relevant. Normalized internally. */
    score: number;
    /** Estimated token cost of including the payload in the final pack.
     *  Must be > 0; zero-cost items are pinned (always included). */
    token_cost: number;
}
export interface ValuePerTokenResult<T> {
    /** Selected candidates in selection order (density-descending). */
    selected: ValuePerTokenCandidate<T>[];
    /** Token cost of the selected set. */
    total_cost: number;
    /** Token cost remaining under the budget. */
    remaining_budget: number;
    /** Per-candidate breakdown — useful for diagnostics and replay. */
    ranking: Array<{
        id: string;
        score: number;
        token_cost: number;
        density: number;
        rank: number;
        included: boolean;
    }>;
}
export interface ValuePerTokenOptions {
    /** Maximum total token cost the selection may consume. Items already
     *  costing more than the budget on their own are skipped — they
     *  cannot fit by definition. */
    budget: number;
    /** When true, items with `token_cost === 0` are unconditionally
     *  included regardless of budget. Useful for cost-free metadata that
     *  carries information density bonuses (anchors, claims). Default true. */
    pinZeroCost?: boolean;
}
/** Select a subset of candidates that maximises Σ score subject to
 *  Σ token_cost ≤ budget, using the greedy density heuristic. Returns
 *  selection plus per-candidate rank info. Deterministic — ties resolved
 *  by score desc, then token_cost asc, then id asc. */
export declare function selectByValuePerToken<T>(candidates: ReadonlyArray<ValuePerTokenCandidate<T>>, options: ValuePerTokenOptions): ValuePerTokenResult<T>;