import { type RunOptions, type RunResult, type Runnable } from './functional/run.ts';
export { GRAMMAR_COVERAGE_DEFINITIONS } from './grammar-metadata.ts';
import type { Combinator, ParseContext } from './types.ts';
import { type GrammarCoverageDefinition } from './compiler/grammar-coverage-ids.ts';
export type { GrammarCoverageDefinition } from './compiler/grammar-coverage-ids.ts';
export type GrammarCoverageSnapshot = {
    definitions: readonly GrammarCoverageDefinition[];
    hits: readonly string[];
    unhit: readonly string[];
    /**
     * Hit fraction, or `NaN` when there was NOTHING TO MEASURE.
     *
     * An empty definition set is not full coverage. This used to report `1` for it, so a
     * grammar whose definitions failed to load — the exact case
     * `'coverage-definitions-unavailable'` exists for — presented as 100% covered, and any
     * consumer gate of the shape `ratio >= threshold` passed on zero evidence. `NaN`
     * compares false against every threshold, so the gate now FAILS CLOSED by default
     * instead of passing by default. Read `measurable` to tell "nothing to measure" from a
     * genuine 0%.
     */
    ratio: number;
    /** False when the definition set was empty, i.e. `ratio` is not a measurement. */
    measurable: boolean;
};
export type GrammarCoverageCollector = {
    hit(id: string): void;
    snapshot(): GrammarCoverageSnapshot;
    reset(): void;
};
/** Metadata emitted only by a coverage-enabled macro grammar. It is attached to
 * the grammar map, rather than each rule function, so a caller chooses the
 * explicit public start rule before collecting results. */
export declare function compiledGrammarCoverageDefinitions(grammar: Record<string, unknown>): readonly GrammarCoverageDefinition[];
export type GrammarTracePhase = 'enter' | 'attempt' | 'selected' | 'success' | 'failure' | 'backtrack' | 'rollback';
export type GrammarTraceEvent = {
    id: string;
    phase: GrammarTracePhase;
    offset: number;
    end?: number;
};
export type GrammarTraceSnapshot = {
    events: readonly GrammarTraceEvent[];
    truncated: boolean;
    dropped: number;
};
export type GrammarTraceSink = {
    write(event: GrammarTraceEvent): void;
    snapshot(): GrammarTraceSnapshot;
};
/** Typed context for a coverage-enabled compiled or macro-generated parser. */
export type GrammarInstrumentationContext = ParseContext & {
    _grammarCoverage?: (id: string) => void;
    _grammarTrace?: GrammarTraceSink;
};
/** Create the opt-in context consumed by coverage-enabled compiled output. */
export declare function createGrammarInstrumentationContext(options?: {
    collector?: GrammarCoverageCollector;
    trace?: GrammarTraceSink;
    trackLines?: boolean;
    state?: unknown;
}): GrammarInstrumentationContext;
/** Bounded first-N trace sink. Exceptions and a false callback detach without
 * changing parser results; post-detach events count as dropped. */
export declare function createGrammarTraceSink(options: {
    capacity: number;
    write?: (event: GrammarTraceEvent) => boolean | void;
}): GrammarTraceSink;
export declare function createGrammarCoverageCollector(definitions: readonly GrammarCoverageDefinition[]): GrammarCoverageCollector;
export declare function grammarCoverageDefinitions(entry: Combinator<unknown>, winners?: Record<string, Combinator<unknown>>): readonly GrammarCoverageDefinition[];
/** Definitions for a runtime `compose()` result, normalized through its final
 * IR winner map. Opaque precompiled pieces intentionally fail rather than
 * reporting source-piece identities as though they were final grammar IDs. */
export declare function composedGrammarCoverageDefinitions(grammar: Record<string, unknown>, startRule: string): readonly GrammarCoverageDefinition[];
export declare function runWithGrammarCoverage(entry: Runnable, input: string, options?: RunOptions & {
    collector?: GrammarCoverageCollector;
    trace?: GrammarTraceSink;
}): {
    result: RunResult;
    coverage: GrammarCoverageSnapshot;
};
//# sourceMappingURL=coverage.d.ts.map