sqllens 0.1.0 → 1.0.0

package/dist/api.d.ts

@@ -1,5 +1,5 @@
 import type { ParserRuleContext } from "antlr4ng";
-import type { Expr, QueryExpr } from "./ir/ir.js";
+import type { Expr, Projection, QueryExpr } from "./ir/ir.js";
 import type { SyntaxDiagnostic } from "./parse-diagnostics.js";
 import { type Scope, type ScopeTree } from "./scope/scope.js";
 import { type Qualification } from "./qualify/qualify.js";
@@ -10,9 +10,8 @@ export type { Nullability } from "./infer/nullability.js";
 import { originsOf as exprOriginsOf, type ColumnLineage, type Origin } from "./lineage/lineage.js";
 import { type StarExpansion, type Sym } from "./symbols/symbols.js";
 import type { Token } from "./token/token.js";
-/** The dialects reachable through the unified surface. Each has its own grammar/CST and a
- *  parse+lower pair; everything after lower() runs unchanged on all seven. */
-export type Dialect = "databricks" | "tsql" | "snowflake" | "bigquery" | "redshift" | "postgres" | "duckdb" | "trino";
+import type { Dialect } from "./dialect.js";
+export type { Dialect } from "./dialect.js";
 /** Options carrying the dialect, needed only when a lift helper enters from a raw string. */
 export interface DialectOpts {
     dialect?: Dialect;
@@ -103,22 +102,25 @@ export declare class Lineage {
     /** Per output column: the base-table columns it derives from. */
     readonly all: readonly ColumnLineage[];
     private readonly byOutput;
+    private readonly byNode;
     constructor(columns: ColumnLineage[]);
     /** The base-table origins of a named output column, or [] if there is no such output. */
     originsOf(column: string): Origin[];
+    /** Origins keyed by the producing Projection node — unambiguous under duplicate output names. */
+    originsOfNode(projection: Projection): Origin[];
 }
 export { exprOriginsOf as originsOfExpr };
 export { lineageAt, lineageOf, type LineageHop, type ViaStep } from "./lineage/hops.js";
 export { tokenize } from "./token/tokenize.js";
 export type { Token, TokenRole } from "./token/token.js";
-export { SqlDocument, type DocumentAnalysis, type StatementCell } from "./document/document.js";
+export { SqlDocument, type DocumentAnalysis, type StatementCell, type DocumentVariant, type UnionCte, } from "./document/document.js";
 export { LineIndex } from "./document/line-index.js";
 export type { StatementCellSpan } from "./document/split.js";
-export { complete, type Completion } from "./completion/complete.js";
+export { complete, completeAt, type Completion } from "./completion/complete.js";
 export { signatureAt, type SignatureInfo } from "./signature/signature.js";
 export { FUNCTION_SIGNATURES, HARVESTED_SIGNATURES, lookupSignature, hasSignature, type FnSignature, type ParamSig, } from "./signature/signatures.js";
 export { referencesAt, type Occurrence, type Occurrences } from "./references/references.js";
 export { dialectSymbols, type DialectSymbols } from "./dialect-symbols.js";
 export { CallbackSchema, type SchemaProvider, type TableResolver } from "./qualify/schema-provider.js";
-export { ADAPTER_DIALECTS, adapterDialect } from "./adapters.js";
+export { DERIVED_DIALECTS, resolveDialect } from "./derived-dialects.js";
 export { foldIdentifier, displayName, type IdentKind } from "./ident/fold.js";

package/dist/api.js

@@ -157,16 +157,25 @@ export class Lineage {
     /** Per output column: the base-table columns it derives from. */
     all;
     byOutput;
+    byNode;
     constructor(columns) {
         this.all = columns;
         this.byOutput = new Map();
-        for (const c of columns)
+        this.byNode = new WeakMap();
+        for (const c of columns) {
             this.byOutput.set(c.output, c.origins);
+            if (c.projection)
+                this.byNode.set(c.projection, c.origins);
+        }
     }
     /** The base-table origins of a named output column, or [] if there is no such output. */
     originsOf(column) {
         return this.byOutput.get(column) ?? [];
     }
+    /** Origins keyed by the producing Projection node — unambiguous under duplicate output names. */
+    originsOfNode(projection) {
+        return this.byNode.get(projection) ?? [];
+    }
 }
 // Re-export the single-expression origin walk under its building-block name (distinct from the
 // Lineage wrapper) so consumers can trace one expression without a full query lineage.
@@ -185,11 +194,11 @@ export { tokenize } from "./token/tokenize.js";
 // It composes the surface above (parse/toScopes/qualify/deriveSymbols/TypeInfo); the import cycle
 // (api re-exports SqlDocument, document imports from api) is safe because document.ts only calls
 // these at call time, never at module-eval time.
-export { SqlDocument } from "./document/document.js";
+export { SqlDocument, } from "./document/document.js";
 export { LineIndex } from "./document/line-index.js";
 // Scope-aware completion over a SqlDocument — the broken-input editor feature (keywords + schema
 // tables/columns + function names at the caret). Total: never throws.
-export { complete } from "./completion/complete.js";
+export { complete, completeAt } from "./completion/complete.js";
 // Signature help over a SqlDocument — the broken-input editor feature that shows parameter hints
 // while typing inside a call's parens. Lookup order: curated (hand-verified) → harvested (doc-derived
 // long tail, from tools/harvest-signatures.mjs) → name-only fallback. A pure token scan; never throws.
@@ -207,9 +216,9 @@ export { dialectSymbols } from "./dialect-symbols.js";
 // lazy resolver whose prime() bumps a version to invalidate SqlDocument.analyze's memo) both
 // satisfy `SchemaProvider`; every analysis entry point accepts the interface.
 export { CallbackSchema } from "./qualify/schema-provider.js";
-// The dbt-adapter → dialect map: resolve a profiles.yml `type:` value (athena, glue, fabric,
-// spark, …) to the dialect that parses its SQL, so consumers don't re-derive the family knowledge.
-export { ADAPTER_DIALECTS, adapterDialect } from "./adapters.js";
+// The derived-dialect → dialect map: resolve an engine name (athena, glue, fabric, spark, …) to the
+// dialect that parses its SQL, so consumers don't re-derive the family knowledge.
+export { DERIVED_DIALECTS, resolveDialect } from "./derived-dialects.js";
 // The dialect-true identifier fold — the identity key for name comparison (unquote + case-fold per
 // the dialect's documented rules) and its display twin (unquote only). Exported so an embedding
 // consumer comparing names against IR/scope output folds the same way the pipeline does.

package/dist/bigquery/parse.d.ts

@@ -1,21 +1,8 @@
-import { type ParserRuleContext } from "antlr4ng";
-import { type SyntaxDiagnostic } from "../parse-diagnostics.js";
-import type { Token } from "../token/token.js";
-export interface ParseResult {
-    /** The CST rooted at `root` (`stmts EOF`). */
-    tree: ParserRuleContext;
-    /** Count of lexer + parser + escape + post-parse syntax errors; equals `diagnostics.length`. */
-    errors: number;
-    /** Positioned syntax diagnostics — lexer/parser (listener-captured) plus escape and post-parse
-     *  errors, all carrying a source span. `errors === diagnostics.length`. */
-    diagnostics: SyntaxDiagnostic[];
-    /** Every token the parser consumed (trivia included, EOF excluded), as neutral `Token`s. Built
-     *  from the dot-path-rewritten stream, so spans match the consumed source. */
-    tokens: Token[];
-    /** True when the fast SLL prediction pass bailed and the parse re-ran under full LL. Same result
-     *  either way — this just says which path produced it, for perf profiling (tools/profile-sll.ts). */
-    sllFallback: boolean;
-}
+import type { ParseResult } from "../parse-result.js";
+/** The CST rooted at `root` (`stmts EOF`); errors count lexer + parser + escape + post-parse
+ *  diagnostics (`errors === diagnostics.length`); tokens are built from the dot-path-rewritten
+ *  stream. See `ParseResult` for the full result shape. */
+export type { ParseResult } from "../parse-result.js";
 /**
  * Lex + parse BigQuery / GoogleSQL (one statement or a `;`-separated batch). Two-stage parsing:
  * try the fast SLL prediction mode first (bail on the first conflict), fall back to full LL

package/dist/bigquery/parse.js

@@ -1,4 +1,4 @@
-import { BailErrorStrategy, CharStream, CommonTokenStream, PredictionMode, } from "antlr4ng";
+import { BailErrorStrategy, CharStream, CommonTokenStream, PredictionMode } from "antlr4ng";
 import { GoogleSQLLexer } from "../generated/bigquery/GoogleSQLLexer.js";
 import { GoogleSQLParser } from "../generated/bigquery/GoogleSQLParser.js";
 import { dotPathTokenSource } from "./dot-path.js";

package/dist/completion/complete.d.ts

@@ -13,4 +13,6 @@ export interface Completion {
  * (table names + column types). NEVER throws: on broken / mid-edit input it still returns the
  * keyword candidates the walk can reach.
  */
-export declare function complete(doc: SqlDocument, offset: number, schema?: SchemaProvider): Completion[];
+export declare function completeAt(doc: SqlDocument, offset: number, schema?: SchemaProvider): Completion[];
+/** @deprecated Use completeAt — same function, uniform cursor-verb naming. */
+export declare const complete: typeof completeAt;

package/dist/completion/complete.js

@@ -1,5 +1,5 @@
 // ---------------------------------------------------------------------------
-// complete() — scope-aware completion over a SqlDocument.
+// completeAt() — scope-aware completion over a SqlDocument.
 //
 // The interactive editor feature that lives in the BROKEN-input world: the user
 // is mid-keystroke, so this runs its OWN error-tolerant lex+parse of the current
@@ -25,7 +25,7 @@ import { makeParser } from "./parser-factory.js";
  * (table names + column types). NEVER throws: on broken / mid-edit input it still returns the
  * keyword candidates the walk can reach.
  */
-export function complete(doc, offset, schema) {
+export function completeAt(doc, offset, schema) {
     try {
         return collect(doc, offset, schema);
     }
@@ -34,6 +34,8 @@ export function complete(doc, offset, schema) {
         return [];
     }
 }
+/** @deprecated Use completeAt — same function, uniform cursor-verb naming. */
+export const complete = completeAt;
 function collect(doc, offset, schema) {
     const dialect = doc.dialect;
     const cfg = COMPLETION_CONFIG[dialect];

package/dist/completion/config.d.ts

@@ -1,4 +1,4 @@
-import type { Dialect } from "../api.js";
+import type { Dialect } from "../dialect.js";
 /**
  * Per-dialect tuning for the ATN candidate walk (`collectCandidates`).
  *

package/dist/completion/parser-factory.d.ts

@@ -1,5 +1,5 @@
 import { CommonTokenStream, type Lexer, type Parser, type ParserRuleContext } from "antlr4ng";
-import type { Dialect } from "../api.js";
+import type { Dialect } from "../dialect.js";
 /**
  * A ready-to-walk parser for the completion engine: the lexer, the token stream, the entry
  * rule's index (for `atn.ruleToStartState[...]`), and a `runEntry()` that drives the parse far

package/dist/databricks/parse.d.ts

@@ -1,20 +1,7 @@
-import { type ParserRuleContext } from "antlr4ng";
-import { type SyntaxDiagnostic } from "../parse-diagnostics.js";
-import type { Token } from "../token/token.js";
-export interface ParseResult {
-    /** The CST rooted at `multiStatement` (a `;`-separated batch of statements and/or
-     *  BEGIN…END SQL-scripting compounds, + EOF). */
-    tree: ParserRuleContext;
-    /** Count of lexer + parser syntax errors. */
-    errors: number;
-    /** Positioned syntax diagnostics (message + line/column/offset/length), in report order. */
-    diagnostics: SyntaxDiagnostic[];
-    /** Every lexer token (trivia included, EOF excluded), as neutral `Token`s with exact spans. */
-    tokens: Token[];
-    /** True when the fast SLL prediction pass bailed and the parse re-ran under full LL. Same result
-     *  either way — this just says which path produced it, for perf profiling (tools/profile-sll.ts). */
-    sllFallback: boolean;
-}
+import type { ParseResult } from "../parse-result.js";
+/** The CST rooted at `multiStatement` (a `;`-separated batch of statements and/or
+ *  BEGIN…END SQL-scripting compounds, + EOF); see `ParseResult` for the full result shape. */
+export type { ParseResult } from "../parse-result.js";
 /**
  * Lex + parse one Databricks SQL statement. Two-stage parsing: try the fast SLL
  * prediction mode first (bail on the first conflict), and fall back to full LL only

package/dist/derived-dialects.d.ts

@@ -0,0 +1,8 @@
+import type { Dialect } from "./dialect.js";
+export declare const DERIVED_DIALECTS: Readonly<Record<string, Dialect>>;
+/**
+ * Resolve an engine / product name (or a dialect name) to the dialect that
+ * parses its SQL. Case-insensitive. Returns undefined for anything not
+ * genuinely served by a gated grammar — never guesses.
+ */
+export declare function resolveDialect(engineOrDialect: string): Dialect | undefined;

package/dist/derived-dialects.js

@@ -0,0 +1,50 @@
+// ---------------------------------------------------------------------------
+// Derived-dialect → dialect map. The eight grammars parse more than eight
+// engines: a *derived dialect* is an engine with no grammar of its own whose
+// SQL surface is a subset of — or identical to — one we already parse (Amazon
+// Athena's engine is Trino, AWS Glue runs Spark, Microsoft Fabric / Azure
+// Synapse / SQL Server speak T-SQL, …). A consumer that only knows an engine
+// name should not have to own that knowledge — this table does.
+//
+// Keys are engine / product names (plus our own dialect names, so both
+// vocabularies resolve). Only engines whose SQL surface our corpus gates
+// genuinely represent are mapped — an unlisted name resolves to undefined,
+// never to a guess.
+// ---------------------------------------------------------------------------
+export const DERIVED_DIALECTS = {
+    // identity — the engine name and the dialect name coincide
+    databricks: "databricks",
+    snowflake: "snowflake",
+    bigquery: "bigquery",
+    redshift: "redshift",
+    postgres: "postgres",
+    duckdb: "duckdb",
+    trino: "trino",
+    // our dialect name (not an engine name) — accepted so both vocabularies work
+    tsql: "tsql",
+    // Spark SQL family — Databricks SQL = Spark SQL; AWS Glue runs Spark
+    spark: "databricks",
+    glue: "databricks",
+    // T-SQL family — Microsoft Fabric and Azure Synapse (restricted T-SQL subsets)
+    // and SQL Server (the reference T-SQL)
+    fabric: "tsql",
+    synapse: "tsql",
+    sqlserver: "tsql",
+    // Trino family — Amazon Athena engine v3 routes queries/DML to Trino; Presto
+    // is Trino's predecessor
+    athena: "trino",
+    presto: "trino",
+    // Alternate spelling of the engine name (alias class, same as our own dialect
+    // names above). Admitted 2026-07-10 on the anvil channel's request; caveat noted
+    // there: no dbt adapter is attested to emit `postgresql` as its adapter_type —
+    // it is inherited consumer vocabulary, admitted as a cheap, honest alias.
+    postgresql: "postgres",
+};
+/**
+ * Resolve an engine / product name (or a dialect name) to the dialect that
+ * parses its SQL. Case-insensitive. Returns undefined for anything not
+ * genuinely served by a gated grammar — never guesses.
+ */
+export function resolveDialect(engineOrDialect) {
+    return DERIVED_DIALECTS[engineOrDialect.trim().toLowerCase()];
+}

package/dist/dialect-symbols.d.ts

@@ -1,4 +1,4 @@
-import type { Dialect } from "./api.js";
+import type { Dialect } from "./dialect.js";
 /** Per-dialect membership sets — canonical UPPERCASE names. See module header for sources
  *  and heuristic limits per set. */
 export interface DialectSymbols {

package/dist/dialect.d.ts

@@ -0,0 +1,3 @@
+/** The dialects reachable through the unified surface. Each has its own grammar/CST and a
+ *  parse+lower pair; everything after lower() runs unchanged on all eight. */
+export type Dialect = "databricks" | "tsql" | "snowflake" | "bigquery" | "redshift" | "postgres" | "duckdb" | "trino";

package/dist/dialect.js

@@ -0,0 +1 @@
+export {};

package/dist/document/document.d.ts

@@ -1,13 +1,18 @@
 import type { ParserRuleContext } from "antlr4ng";
-import { TypeInfo, type Dialect } from "../api.js";
-import type { QueryExpr } from "../ir/ir.js";
+import { TypeInfo } from "../api.js";
+import { type LineageHop } from "../lineage/hops.js";
+import { type Occurrences } from "../references/references.js";
+import type { Dialect } from "../dialect.js";
+import type { QueryExpr, PartSpan } from "../ir/ir.js";
 import type { StatementCategory } from "../ir/statement.js";
 import type { SyntaxDiagnostic } from "../parse-diagnostics.js";
 import type { ScopeTree } from "../scope/scope.js";
 import type { Qualification, Diagnostic } from "../qualify/qualify.js";
 import type { SchemaProvider } from "../qualify/schema-provider.js";
-import type { Sym } from "../symbols/symbols.js";
+import { type TemplateProvider } from "../qualify/template-provider.js";
+import type { Span, Sym } from "../symbols/symbols.js";
 import type { Token } from "../token/token.js";
+import type { TemplateEngine, TemplatedParseResult, TemplateVariant } from "../template/engine.js";
 import { LineIndex } from "./line-index.js";
 import { type NodeHit } from "./node-at.js";
 import { type StatementCellSpan } from "./split.js";
@@ -45,6 +50,39 @@ export interface DocumentAnalysis {
     /** Qualification's semantic diagnostics (unknown table/column/field). */
     diagnostics: Diagnostic[];
 }
+/** One coherent arm realization of a templated document. Lazy: nothing parses until doc() or
+ *  text() is first touched. A variant IS a document — everything a plain SqlDocument exposes
+ *  (ast/tokens/scopes/templated/analyze/cursor members) is available per arm through doc(). */
+export interface DocumentVariant {
+    /** The arm this variant activates (undefined = variant 0, all defaults). Mirrors
+     *  TemplateVariant.active, including the synthetic-empty marker from Task 1. */
+    readonly active?: TemplateVariant["active"];
+    /** The realized text: original text with inactive arms whitespace-blanked —
+     *  length- and newline-preserving (spans stay document-true). Memoized. */
+    text(): string;
+    /** The arm's own SqlDocument: same dialect, SAME engine, SAME provider, SHARING the parent's
+     *  content-addressed cell-cache family (an arm whose text an edit didn't change is a cache hit).
+     *  Memoized per variant. */
+    doc(): SqlDocument;
+}
+/** One CTE's identity + its output columns unioned across arms (`SqlDocument.unionCtes`). */
+export interface UnionCte {
+    /** Fold-normalized, quote-preserving identity form — `foldIdentifier(raw, dialect)`, the same
+     *  vocabulary the column entries below (and the rest of the resolved surface) speak. The exact
+     *  written form is recoverable by slicing the source at `declarationSpan`. */
+    name: string;
+    /** Declaration identity: the CTE name's own span (`CteDef.nameCst`, falling back to the whole
+     *  `CteDef.cst` when the name itself has no real token). Part of the key: two same-named CTEs
+     *  declared at different positions stay distinct entries. */
+    declarationSpan: PartSpan;
+    /** Output columns unioned by NAME across arms; each column's span is the FIRST LIVE ARM's (arm
+     *  iteration order = `SqlDocument.variants` order) — the representative-span rule pinned by the
+     *  variant-acceptance brief's A8a-c. Names are fold-normalized like `name` above. */
+    columns: {
+        name: string;
+        span: Span;
+    }[];
+}
 export declare class SqlDocument {
     readonly uri?: string;
     readonly version: number;
@@ -73,6 +111,10 @@ export declare class SqlDocument {
      *  facade's scopes (`statement: "compound"`); use `statements`/`cellAt` for per-statement scopes. */
     readonly scopes: ScopeTree;
     readonly lines: LineIndex;
+    /** The template artifacts when this document was built with a `templating` engine:
+     *  tags/regions/symbols/placeholder/degraded plus tagOf/nodeOf/diagnosticsOf.
+     *  Undefined on plain documents. */
+    readonly templated?: TemplatedParseResult;
     /** Schema-keyed memo of the MERGED analyze() result (concat + coordinate shift). Rebuilt per doc
      *  version — the merge must redo when an earlier statement's line count changes and shifts later
      *  cells' doc coordinates — while the per-CELL analysis (the expensive qualify/deriveSymbols) is
@@ -86,6 +128,19 @@ export declare class SqlDocument {
     /** The content-addressed cross-edit cell cache, carried to withText() children. Its contents stay
      *  mutable (a memo) even though the reference is frozen with the instance. */
     private readonly _cellCache;
+    /** The injected template engine + provider, carried to withText() children so an edit keeps
+     *  building through the same door its parent used. Undefined on a plain document. */
+    private readonly _templating?;
+    private readonly _provider?;
+    /** Memo box for the `variants` getter (frozen instance, mutable memo — the `_analysisCache`
+     *  precedent: the box reference is frozen with the instance, but its `.value` stays settable). */
+    private readonly _variantsMemo;
+    /** Schema-keyed memos for the four union views (`unionSymbols`/`unionDiagnostics`/`unionCtes`/
+     *  `unionOutputColumns`) — one WeakMap per view, same identity+version pattern as `_analysisCache`. */
+    private readonly _unionSymbolsCache;
+    private readonly _unionDiagnosticsCache;
+    private readonly _unionCtesCache;
+    private readonly _unionOutputColumnsCache;
     private constructor();
     /** Build one statement cell for `span`: reuse the cached cell-relative parse if its text is
      *  already known (content addressing), else parse+scope it and cache it; then shift tokens /
@@ -100,14 +155,29 @@ export declare class SqlDocument {
      *  NOT replace the cache entry: the first occurrence keeps its stable cross-edit identity (the
      *  common case), and only intra-doc duplicates — rare — pay a re-parse per build. */
     private buildCell;
+    /** Build the ONE cell for a TEMPLATED document: span [0, text.length) — the templated build path
+     *  bypasses `splitStatements` entirely (one cell, whole text), and its products come from a single
+     *  `engine.parse(text, dialect, { provider })` call rather than the plain per-dialect `parse()`.
+     *  `r.tokens`/`r.diagnostics` are ALREADY document coordinates (the cell always starts at 0), so —
+     *  unlike `buildCell` — nothing is shifted. Mirrors `buildCell`'s CachedCell/StatementCell shapes
+     *  so every downstream consumer (analyze(), cellAt(), nodeAt()…) sees the same structure whether
+     *  the document is plain or templated. Cached in the SAME cross-edit `_cellCache` as plain cells,
+     *  under a prefixed key so a templated cell can never collide with a plain one for the same text. */
+    private buildTemplatedCell;
     /** Build a document for `text` in `dialect`. Total: never throws, even on broken / mid-edit input.
-     *  Starts a FRESH cell cache — cross-edit reuse comes from withText(), not create(). */
+     *  Starts a FRESH cell cache — cross-edit reuse comes from withText(), not create(). Pass
+     *  `templating` to parse through an injected TemplateEngine (jinja-SQL etc.) instead of the plain
+     *  per-dialect parser — absent, this is the exact untouched plain-SQL path (never auto-detected).
+     *  `provider` feeds the engine's fills/markers and is ignored without `templating`. */
     static create(text: string, dialect: Dialect, opts?: {
         uri?: string;
         version?: number;
+        templating?: TemplateEngine;
+        provider?: TemplateProvider;
     }): SqlDocument;
     /** An edit: a NEW SqlDocument for the new text. This instance is untouched (immutable). The cell
-     *  cache is CARRIED forward, so statements whose text didn't change reuse their parsed cells. */
+     *  cache is CARRIED forward, so statements whose text didn't change reuse their parsed cells. The
+     *  injected templating engine + provider (if any) ride the instance to this child too. */
     withText(text: string, version: number): SqlDocument;
     /** The statement cell owning `offset` (binary search over the tiling cell spans), or undefined if
      *  there are no cells. An offset at end-of-document resolves to the last cell. */
@@ -122,6 +192,42 @@ export declare class SqlDocument {
      *  `expr.cst` carries CELL-relative spans; a caller turning it into a document Range shifts it by the
      *  owning cell's start (see `cellBaseAt` in src/lsp/ranges.ts). Single-cell: identical to today. */
     nodeAt(offset: number): NodeHit | undefined;
+    /** The declaration + every occurrence of the symbol at `offset` (the references engine,
+     *  cell-aware): resolved over the CELL owning the offset — its own scopes/ast, with a
+     *  cell-relative offset — then every returned span (occurrences + declaration) shifted from
+     *  cell-relative to DOCUMENT coordinates by the cell base. Absorbs the dance the LSP
+     *  references/documentHighlight/codeLens features hand-rolled. Single-cell documents: base
+     *  0/0/0, byte-identical to the free referencesAt over doc.scopes. Total: null off-symbol or
+     *  with no cells; never throws. */
+    referencesAt(offset: number, schema?: SchemaProvider): Occurrences | null;
+    /** The per-hop lineage spine anchored at `offset` (cell-aware): resolved over the CELL owning
+     *  the offset, with a cell-relative offset. NOTE: on a MULTI-statement document the returned
+     *  hop nodes' cst spans are CELL-relative — the spine references the frozen per-cell IR (hops
+     *  are references, not copies), so nothing is shifted here; use `cellAt(offset).span.start` as
+     *  the base to map them to document coordinates. Single-cell documents (every dbt model) are
+     *  identical either way. Total: undefined off-symbol or with no cells; never throws. */
+    lineageAt(offset: number, schema?: SchemaProvider): LineageHop | undefined;
+    /** The coherent per-arm variants of a templated document (engine.variants() consumed). `[]` on
+     *  plain documents and on templated documents with no control-flow regions. Lazy at every level:
+     *  enumeration on first read, realization+parse per variant on first doc()/text(). Memoized on
+     *  the instance (frozen instance, mutable memo box — see `_variantsMemo`). */
+    get variants(): readonly DocumentVariant[];
+    /** Compute (no memo) the variant list: absent `variants` hook, a plain document, or a templated
+     *  document with no control-flow regions all answer `[]`. Otherwise consults the engine, wrapped
+     *  defensively (degrade to `[]`, never throw — engine.variants may throw only on engine bugs, the
+     *  same posture parseTemplated's own catch uses). */
+    private buildVariants;
+    /** Wrap one engine-produced TemplateVariant as a DocumentVariant: `text()` delegates straight to
+     *  the engine variant's own memoized realization (never re-realized here); `doc()` builds — once,
+     *  memoized — the arm's own SqlDocument through the PRIVATE constructor, carrying this document's
+     *  `_cellCache` (the exact carry `withText` uses, NOT the public `create`'s fresh cache) plus the
+     *  same templating engine + provider, so an unchanged arm across an edit is a cache hit. */
+    private wrapVariant;
+    /** The variant whose realization has `offset` LIVE (its arm active): an offset inside a
+     *  non-default arm routes to that arm's variant; a default-arm or outside-all-regions offset
+     *  routes to variant 0. undefined on plain documents and no-region templated documents.
+     *  Never throws; out-of-range offsets answer variant 0 (the honest default). */
+    variantAt(offset: number): DocumentVariant | undefined;
     /** The schema-dependent tiers, over the cached per-cell scopes/ast (no re-parse). Memoized by
      *  schema IDENTITY + VERSION — a plain Schema (version 0) memoizes exactly as before; a
      *  CallbackSchema that has been prime()d bumps its version and so re-computes with the newly
@@ -139,4 +245,52 @@ export declare class SqlDocument {
      *  identity + version) so it survives edits that don't touch this cell, yet re-runs when a primed
      *  CallbackSchema bumps its version. */
     private cellAnalysis;
+    /** Symbols across ALL variants, deduped by span+identity+NAME (`start:end:kind:frame:name` —
+     *  NAME is load-bearing: schema-expanded star Syms share one zero-width span by design, see
+     *  symbols.ts's emitColumns). Computed over the VARIANT documents only — never the primary
+     *  parse, whose all-arms-live SQL can mis-read conflicting arms (e.g. `col_a col_b` reading as
+     *  an alias) into junk that must never leak into the union. Equals the plain `analyze(schema)`
+     *  symbols when there are no variants (a plain document, or a templated one with no
+     *  control-flow regions). Memoized per schema identity+version, like `analyze()`. */
+    unionSymbols(schema?: SchemaProvider): Sym[];
+    private buildUnionSymbols;
+    /** Diagnostics across all variants — syntax + semantic, like `session.diagnostics()` — deduped
+     *  by position+identity, NOT message text: two arms producing the SAME diagnostic at the SAME
+     *  position collapse to one entry, but the same message at TWO DIFFERENT positions stays two
+     *  entries (the exact case a message-keyed merge gets wrong). Same variant-only, memoized
+     *  semantics as `unionSymbols`. */
+    unionDiagnostics(schema?: SchemaProvider): (SyntaxDiagnostic | Diagnostic)[];
+    private buildUnionDiagnostics;
+    /** Per-CTE column unions across all variants, keyed by NAME + declaration span (two same-named
+     *  CTEs declared at different positions stay distinct entries; a CTE existing in only one arm
+     *  still appears). Columns union by NAME; a column's representative span is the FIRST LIVE ARM's
+     *  (arm iteration order = `this.variants` order) — the rule the variant-acceptance brief's A8a-c
+     *  pin. A CTE whose body is a set operation answers through the qualification (names per SQL
+     *  setop semantics, spans from the declaring branch); a PIPE-syntax body answers no columns — a
+     *  visible, ledgered gap, see `scopeOutputColumns`. Falls through to this document's own
+     *  (single-arm) answer when there are no variants — there is no pre-existing single-doc
+     *  equivalent to delegate to, unlike unionSymbols/unionDiagnostics, so the no-variant case is
+     *  just the one-arm instance of the same algorithm. Variant-only, memoized like `unionSymbols`.
+     *  KNOWN GAP (visible, ledgered — not silently narrowed): on a multi-statement document these
+     *  answer `[]` — the compound facade carries no CTEs/outputs; the per-cell merge is a tracked
+     *  follow-up; single-statement documents (every dbt model) are fully covered. */
+    unionCtes(schema?: SchemaProvider): UnionCte[];
+    private buildUnionCtes;
+    /** The document's final-SELECT (root scope) output columns unioned across arms — same NAME
+     *  keying and representative-span rule as `unionCtes`. A setop root (the dbt-incremental
+     *  `… UNION ALL …` arm shape) answers through the qualification — names per SQL setop semantics
+     *  (left branch positionally, BY NAME appends right-only), spans from the declaring branch. A
+     *  PIPE-syntax root answers `[]` — a visible, ledgered gap, see `scopeOutputColumns`. Falls
+     *  through to this document's own root outputs when there are no variants.
+     *  KNOWN GAP (visible, ledgered — not silently narrowed): on a multi-statement document these
+     *  answer `[]` — the compound facade carries no CTEs/outputs; the per-cell merge is a tracked
+     *  follow-up; single-statement documents (every dbt model) are fully covered. */
+    unionOutputColumns(schema?: SchemaProvider): {
+        name: string;
+        span: Span;
+    }[];
+    private buildUnionOutputColumns;
+    /** The per-arm documents `unionCtes`/`unionOutputColumns` aggregate over: the real variants when
+     *  they exist, else this document itself as the sole arm (see those methods' fall-through note). */
+    private arms;
 }