/**
 * @file Parse Failure Tracking
 * @description Types and utilities for tracking partial match failures
 *              to provide better error messages (Phase 1.2 of parser recommendations)
 */
import type { ParseErrorCode } from '@sharpee/world-model';
/**
 * Reason why a pattern match failed
 */
export type MatchFailureReason = 'NO_TOKENS' | 'VERB_MISMATCH' | 'LITERAL_MISMATCH' | 'SLOT_FAILED' | 'LEFTOVER_TOKENS' | 'NOT_ENOUGH_TOKENS';
/**
 * Detailed slot failure information
 */
export interface SlotFailure {
    /** Slot name (e.g., 'target', 'container') */
    slotName: string;
    /** Tokens that were tried for this slot */
    attemptedText: string;
    /** Why the slot failed */
    reason: 'NO_MATCH' | 'SCOPE_VIOLATION' | 'AMBIGUOUS';
    /** For NO_MATCH: the word(s) that couldn't be resolved */
    unknownWord?: string;
    /** For SCOPE_VIOLATION: entities found but out of scope */
    outOfScopeEntities?: string[];
    /** For AMBIGUOUS: multiple matches found */
    candidates?: string[];
}
/**
 * Information about a partial pattern match failure
 */
export interface PartialMatchFailure {
    /** The pattern that was attempted */
    pattern: string;
    /** The action this pattern maps to */
    action: string;
    /** How far into the pattern we got (0-1, higher = more matched) */
    progress: number;
    /** Number of tokens consumed before failure */
    tokensConsumed: number;
    /** Why the match failed */
    reason: MatchFailureReason;
    /** If verb was recognized, what was it */
    matchedVerb?: string;
    /** If a slot failed, details about that failure */
    slotFailure?: SlotFailure;
    /** The token that caused the mismatch (if applicable) */
    failedAtToken?: string;
    /** What was expected at the failure point */
    expected?: string;
}
/**
 * Analyze partial match failures to determine the best error to report
 */
export declare function analyzeBestFailure(failures: PartialMatchFailure[], input: string, hasVerb: boolean): {
    code: ParseErrorCode;
    messageId: string;
    context: Record<string, any>;
};
//# sourceMappingURL=parse-failure.d.ts.map