/**
 * Read de-duplication primitives.
 *
 * Two mechanisms share this module:
 *
 * - The post-hoc context GC (`context-gc.ts`), which stubs out a `read` result
 *   once a later overlapping read or an edit/write has superseded it.
 * - The at-call-time guard in the `read` tool, which short-circuits a read whose
 *   requested range is *already fully covered* by an earlier, still-live read in
 *   the current session, returning a pointer instead of re-fetching the file.
 *
 * Both reason about half-open line ranges `[start, end)` (end exclusive), so the
 * range math lives here and cannot drift between them. The guard additionally
 * needs to (a) recognise its own pointer results so they are never treated as
 * content-bearing reads, and (b) walk the session branch to find a covering
 * read — both of which are defined here to keep the tool file lean.
 */
/** Half-open line interval `[start, end)` a read call covers; end is exclusive. */
export interface ReadRange {
    start: number;
    end: number;
}
/** A read with no offset/limit covers the whole file (open-ended). */
export declare const WHOLE_FILE_RANGE: ReadRange;
/**
 * Derive the line range a read call covers from its `offset`/`limit` args.
 * Missing offset means "from line 1"; missing limit means "to end of file"
 * (open-ended, so it overlaps any later read of the same file).
 */
export declare function readRangeFromArgs(args: Record<string, unknown> | undefined): ReadRange;
/** Whether two half-open line ranges intersect. */
export declare function rangesOverlap(a: ReadRange, b: ReadRange): boolean;
/**
 * Marker prefix for the at-call dedup pointer. Kept stable so the context GC can
 * recognise a pointer result and exclude it from supersession bookkeeping (a
 * pointer fetched no content, so it must not stub the read it points at).
 */
export declare const DEDUP_POINTER_PREFIX = "[Already in context:";
/** Whether a tool-result text is an at-call dedup pointer. */
export declare function isDedupPointerText(text: string): boolean;
/** Remember the stamp of the file a read delivered. */
export declare function recordReadStamp(callId: string, stamp: string): void;
/**
 * Whether the file a read delivered still stamps the same. False when no stamp
 * was recorded, so an unprovable case re-reads rather than asserting freshness.
 */
export declare function readStampMatches(callId: string, stamp: string): boolean;
/** Test seam: drop all recorded stamps. */
export declare function clearReadStamps(): void;
/** A covering earlier read, described for the pointer message. */
export interface CoveringRead {
    /** Tool call id of the read being pointed at, used to check its stamp. */
    callId: string;
    /** The path as the earlier read spelled it (for a friendly pointer). */
    display: string;
    /** Delivered range start (1-indexed line). */
    start: number;
    /** Delivered range end (exclusive; Infinity for a whole-file read). */
    end: number;
}
export interface FindCoveringReadOptions {
    /** Resolved absolute path of the current read. */
    resolvedPath: string;
    /** Range the current read is asking for. */
    requestedRange: ReadRange;
    /** Tool call id of the current read, excluded from candidate/supersession sets. */
    currentCallId: string;
    /** Resolve a raw read-arg path the same way the current read resolved its path. */
    resolvePath: (rawPath: string) => string;
}
/**
 * Find the latest earlier read that (a) is for the same resolved path, (b)
 * actually delivered a range containing the requested range, and (c) is still
 * live in the outgoing context — i.e. the post-hoc GC will not have stubbed it,
 * because no later edit/write and no later overlapping content read supersede
 * it. Returns that read's delivered range for the pointer, or null when the
 * current read must actually run.
 *
 * Deliberately conservative: a truncated earlier read only covers what it
 * delivered, a whole-file read must have been delivered untruncated to count as
 * covering, and any pointer results (which fetched nothing) are ignored on both
 * the candidate and the supersession side.
 */
export declare function findCoveringRead(entries: readonly unknown[], opts: FindCoveringReadOptions): CoveringRead | null;
/** The parts of a covering read the pointer message renders. */
export type CoveringReadDisplay = Pick<CoveringRead, "display" | "start" | "end">;
/** Build the pointer text returned in place of a re-fetch. */
export declare function buildDedupPointerText(covering: CoveringReadDisplay): string;
//# sourceMappingURL=read-dedup.d.ts.map