import { RecallFilterTrace } from './recall-xray.js';
import './types.js';

type TagMatchMode = "any" | "all";
/**
 * Coerce a caller-supplied `tagMatch` value to the allowed enum.
 *
 * - `undefined` / `null` → `undefined` (caller didn't ask).
 * - Valid string → narrowed `TagMatchMode`.
 * - Invalid string → throws (CLAUDE.md rule 51 — never silently default).
 */
declare function parseTagMatch(value: unknown): TagMatchMode | undefined;
/**
 * Coerce a caller-supplied `tags` value into a clean string[].
 *
 * Accepts `string[]` and discards non-string / empty entries. Returns
 * `undefined` when no usable tags remain so downstream callers can treat
 * "no filter" and "empty filter" identically.
 */
declare function normalizeTags(value: unknown): string[] | undefined;
interface TagFilterInput {
    tags: string[] | undefined;
    tagMatch: TagMatchMode | undefined;
}
interface TagFilterDecision {
    /** Whether the candidate's tags satisfy the filter. */
    admitted: boolean;
}
/**
 * Decide whether a single result's tags satisfy the filter.
 *
 * `any` (default) admits when the result has at least one of the filter
 * tags. `all` admits only when every filter tag is present on the result.
 * Returns `admitted: true` whenever no filter tags are configured.
 */
declare function evaluateTagFilter(candidateTags: string[] | undefined, filter: TagFilterInput): TagFilterDecision;
interface TaggedResult {
    tags: string[];
}
/**
 * Apply the tag filter to an array of recall results.
 *
 * Returns `{results, trace}`:
 *  - `results` is the filtered array (or the original when no filter).
 *  - `trace` is a `RecallFilterTrace` capturing how many candidates were
 *    seen vs admitted, suitable for surfacing in X-ray output.
 *
 * `trace` is `null` when no filter tags were configured so callers can
 * skip emitting an empty trace entry.
 */
declare function applyTagFilter<T extends TaggedResult>(results: T[], filter: TagFilterInput): {
    results: T[];
    trace: RecallFilterTrace | null;
};

export { type TagFilterDecision, type TagFilterInput, type TagMatchMode, type TaggedResult, applyTagFilter, evaluateTagFilter, normalizeTags, parseTagMatch };
