/**
 * Superseded pointer resolution (#108).
 *
 * `custom.superseded_by` holds the successor's uuid, so resolving a pointer means a lookup
 * against a uuid index. Callers build the index once per command and reuse it — a library of
 * several thousand references makes a per-item linear scan quadratic.
 *
 * See spec/features/superseded.md.
 */
import type { CslItem } from "../../core/csl-json/types.js";
/** A superseded mark read off a reference. */
export interface SupersededMark {
    /** uuid of the successor. Never empty. */
    supersededBy: string;
    /** Free string from storage; falls back to "other" when absent. */
    reason: string;
    /** ISO 8601 timestamp, absent on hand-written marks. */
    at: string | undefined;
}
/** Result of following a single `superseded_by` pointer. */
export interface SuccessorResolution {
    /** The successor, or null when its uuid is absent from the library. */
    target: CslItem | null;
    /** True when the pointer names a uuid that is not in the library. */
    dangling: boolean;
}
/** Result of following a `superseded_by` chain to its end. */
export interface ChainResolution {
    /** Last record reached, or null when the very first hop dangled. */
    target: CslItem | null;
    /** True when the chain ended at a pointer whose uuid is absent from the library. */
    dangling: boolean;
    /** True when the chain revisited a record; `target` is the last one reached before that. */
    cycle: boolean;
    /** Number of pointers successfully followed. */
    hops: number;
}
/**
 * Read the superseded mark off a reference.
 *
 * The pointer alone constitutes a mark: `ref deprecate` always writes all three fields, but a
 * hand-edited or externally written record may carry only `superseded_by`, and dropping such a
 * pointer would silently lose the one piece of information that matters.
 *
 * @returns The mark, or null when the reference carries no usable pointer
 */
export declare function getSupersededMark(item: CslItem): SupersededMark | null;
/** Whether a reference carries a superseded pointer. */
export declare function isSuperseded(item: CslItem): boolean;
/**
 * Index references by uuid for pointer resolution.
 * References without a uuid cannot be pointed at and are skipped.
 */
export declare function buildUuidIndex(items: CslItem[]): Map<string, CslItem>;
/**
 * Follow one `superseded_by` pointer.
 *
 * @returns The resolution, or null when the reference is not superseded
 */
export declare function resolveSuccessor(item: CslItem, index: Map<string, CslItem>): SuccessorResolution | null;
/**
 * Follow a `superseded_by` chain to the last reachable record.
 *
 * `ref deprecate` rejects cycles, so a cycle here means the library was edited by hand or by
 * another tool. Detect and report it rather than looping.
 *
 * @returns The resolution, or null when the reference is not superseded
 */
export declare function resolveFinalSuccessor(item: CslItem, index: Map<string, CslItem>): ChainResolution | null;
//# sourceMappingURL=resolver.d.ts.map