import type { Expr, Projection } from "../ir/ir.js";
import type { SchemaProvider } from "../qualify/schema-provider.js";
import type { Scope, ScopeTree } from "../scope/scope.js";
import { type Origin } from "./lineage.js";
export interface LineageHop {
    /** The frame (CTE / subquery / leg / main) this hop lives in — a pre-existing Scope object. */
    scope: Scope;
    /** The projection that produced the column here — its `cst` + Task-5 `aliasCst` spans. Absent
     *  only when the hop anchors a raw column ref that has no producing projection (a WHERE/ON ref
     *  landing directly on a base table or a set-op fork); the spec forbids fabricating one. */
    projection?: Projection;
    /** The producing expression — its `cst` span (the panel slices the source text itself). */
    expr: Expr;
    /** The hops feeding this one, toward the base tables; `[]` at a terminal. Deduped by object
     *  identity — a producer reached twice is the SAME object appearing once (DAG). */
    downstream: LineageHop[];
    /** Base-table leaves this hop's expression reads DIRECTLY, or an honest dead end. Set to the
     *  Origin[] when the expression's refs land on base tables; `"unresolved"` when nothing could be
     *  bound (ambiguity, no schema, lateral/TVF, or a cycle-guarded recursive leg). A hop may carry
     *  BOTH `downstream` (derived refs) and a `terminal` Origin[] (base-table refs) — an honest
     *  mixed expression. Absent when every ref flows through `downstream`. */
    terminal?: Origin[] | "unresolved";
    /** ITEM 12/13 (flow view): the ordered scopes the walk COLLAPSED (pure-rename passthroughs) or
     *  DESCENDED (star / bare-source resolution) through while following this hop's refs to its
     *  `downstream`/`terminal` — consumer-side first, identity-deduped (by scope) in first-traversal
     *  order, ABSENT when nothing was collapsed. Each step is TAGGED with WHY it was traversed
     *  (ITEM 13): `"rename"` = an explicitly-written passthrough (fully trustworthy), `"expand"` =
     *  a `SELECT *` / bare-source descent (schema-inferred — trust equals schema trust). Metadata
     *  only: no fabricated hops; a terminal's trail is its carrying hop's `via`. Deferred flat-walk
     *  paths (lateral/pivot/pipe) record no trail — absent means "not recorded on this edge". */
    via?: readonly ViaStep[];
}
/** One step of a hop's `via` trail (ITEM 13). `kind` distinguishes a written rename-collapse from a
 *  schema-inferred star/bare-source descent — the panel's DIRECT-vs-INDIRECT trust distinction. */
export interface ViaStep {
    scope: Scope;
    kind: "rename" | "expand";
}
/** Cursor-anchored: the hop map for the column reference (or projection/alias) under `offset`,
 *  ANYWHERE in the tree. Returns undefined off a resolvable column/projection (a keyword, an
 *  operator, whitespace). Total: never throws. V1 domain — column refs, projections, aliases. */
export declare function lineageAt(scopes: ScopeTree, offset: number, schema?: SchemaProvider): LineageHop | undefined;
/** Programmatic: the hop map for any column-ref Expr or Projection node, evaluated in `scope`. */
export declare function lineageOf(node: Expr | Projection, scope: Scope, schema?: SchemaProvider): LineageHop;