import type { DocumentViewNode } from './document_view-types.js';
/**
 * Deterministic locator primitive over a `DocumentView`.
 *
 * A locator resolves a SINGLE span (raw-text offsets within one node) and never
 * heals, scores, or guesses. Ambiguity — zero matches or more than one — is a
 * drift signal reported as `unresolved`, so a caller updates the selector rather
 * than silently filling the wrong place. Redundant `assertions` corroborate the
 * `primary` match the moment an upstream change makes them disagree.
 *
 * Patterns are authored against the stable, normalized `clean_text`; resolved
 * spans are returned as RAW offsets (`getParagraphText` / `replaceTextAtRange`
 * coordinates) via {@link buildCleanToRawOffsetMap}.
 */
export type LocatorStep = {
    kind: 'section';
    /** Exact match against the node's derived heading text. */
    headingText?: string;
    /** Regex (un-anchored) tested against the node's derived heading text. */
    headingRegex?: string;
    /** Exact match against the paragraph's Word style id. */
    headingStyleId?: string;
    /**
     * Outline level at which the region ends: the region runs from the matched
     * heading until the next heading whose level is `<= untilLevel`. Defaults
     * to the matched heading's own level (so the region ends at the next
     * sibling-or-higher heading); when the matched heading has no level and no
     * `untilLevel` is given, the region runs to the end of the current scope.
     */
    untilLevel?: number;
} | {
    kind: 'regex';
    pattern: string;
    flags?: string;
    group?: number;
} | {
    kind: 'contextual';
    contextPattern: string;
    targetPattern: string;
    rowLabelPattern?: string;
} | {
    kind: 'fingerprint';
    contentFingerprint: string;
};
export interface Locator {
    /** Ordered `section` steps narrowing to a region (Scrapy-style nesting). */
    scope?: LocatorStep[];
    /** The deterministic single-span resolver. Must be regex | contextual | fingerprint. */
    primary: LocatorStep;
    /** Corroborators that never select. Must be regex | contextual | fingerprint. */
    assertions?: LocatorStep[];
}
export interface LocatorAssertionResult {
    ok: boolean;
    kind: string;
    detail?: string;
}
export interface LocatorResolution {
    /** RAW-offset span, or null when the primary did not resolve to exactly one span. */
    match: {
        nodeId: string;
        start: number;
        end: number;
    } | null;
    /** True when the primary matched zero or more than one span (a drift signal). */
    unresolved: boolean;
    /** Per-assertion corroboration results (empty when `unresolved`). */
    assertionResults: LocatorAssertionResult[];
}
/**
 * Resolve a {@link Locator} against a document view. Deterministic: the same
 * `(view, locator)` always yields the same result, with no randomness, scoring,
 * or tie-breaking.
 */
export declare function resolveLocator(view: DocumentViewNode[], locator: Locator): LocatorResolution;
//# sourceMappingURL=locator.d.ts.map