package gudusoft.gsqlparser.ir.semantic;

import gudusoft.gsqlparser.ir.semantic.joinanalysis.JoinAnalysisFacts;
import gudusoft.gsqlparser.ir.semantic.joinanalysis.JoinGraph;

import java.util.ArrayList;
import java.util.Collections;
import java.util.List;

/**
 * Semantic shape of one SQL statement. Currently covers SELECT.
 *
 * <p><b>API status:</b> read-only traversal of analyzer-produced instances,
 * including {@link #getJoinAnalysisFacts()}, {@link #getJoinGraph()}, and
 * {@link #getJoinColumnRefs()}, is part of Join Analysis Consumption Profile
 * v1. Public constructors, copying methods, and degrade factories are
 * producer-oriented and are not included in that consumption profile.
 *
 * <p>{@link #name} is non-null when this statement is the body of a named
 * CTE or a FROM-clause subquery. For top-level outer SELECTs it is null.
 *
 * <p>{@link #filterColumnRefs}, {@link #joinColumnRefs},
 * {@link #groupByColumnRefs}, {@link #havingColumnRefs}, and
 * {@link #orderByColumnRefs} are flat lists of column references that
 * appear in the WHERE, JOIN predicate (ON / USING), GROUP BY, HAVING,
 * and ORDER BY clauses respectively. For {@code JOIN ... USING (k)}
 * (slice 64) {@code joinColumnRefs} contains one ref per
 * (relation, key) pair on both sides — left side first via
 * catalog-aware narrowing, then the right side. The IR deliberately
 * does <i>not</i> model structured
 * {@code Filter}, {@code Join}, or {@code GroupBy} nodes with predicate
 * trees yet; later slices will add them. Listing the affected columns
 * is enough to answer the roadmap's questions about
 * filter/join/grouping/having/ordering influence.
 *
 * <p>{@link #groupingElements} (slice 128) is the structured companion to
 * the flat {@link #groupByColumnRefs}: one {@link GroupingElement} per
 * top-level {@code GROUP BY} item, preserving the {@code SIMPLE} /
 * {@code ROLLUP} / {@code CUBE} / {@code GROUPING SETS} structure the flat
 * list discards. See {@link #getGroupingElements()}.
 *
 * <p>{@link #orderByColumnRefs} only ever contains references to physical
 * (base or in-statement) columns. Ordinal references ({@code ORDER BY 1})
 * and bare-constant sort keys are rejected by the builder — emitting
 * {@code []} for them would lose the dependency information silently.
 *
 * <p>Slice 9 (single-SELECT) rejects projection-alias references like
 * {@code SELECT id AS x ... ORDER BY x}. Slice 21 (set-op outer)
 * <i>accepts</i> alias references positionally against branch[0]'s
 * outputs — the alias IS the set-op output schema. The two paths
 * diverge intentionally; see
 * {@code SemanticIRBuilder.buildOrderByColumnRefs} (slice 9) versus
 * {@code SemanticIRBuilder.buildSetOpOuterOrderByColumnRefs} (slice 21).
 */
public final class StatementGraph {

    private final String name;
    private final String kind;
    private final List<RelationSource> relations;
    private final List<OutputColumn> outputColumns;
    private final List<OutputColumn> returningColumns;
    private final List<ColumnRef> filterColumnRefs;
    private final List<ColumnRef> joinColumnRefs;
    private final List<ColumnRef> groupByColumnRefs;
    private final List<ColumnRef> havingColumnRefs;
    private final List<ColumnRef> orderByColumnRefs;
    private final List<ColumnRef> distinctOnColumnRefs;
    private final List<ColumnRef> qualifyColumnRefs;
    private final List<GroupingElement> groupingElements;
    private final List<ColumnRef> pivotColumnRefs;
    private final boolean distinct;
    private final SetOperator setOperator;
    private final RowLimit rowLimit;
    private final TargetRelation target;
    /**
     * Join-analysis facts (slice 167, GAP 1/2/4): the single optional
     * carrier holding the structured {@link JoinGraph}, the WHERE filter
     * predicates, and the query-block scope. Never null — defaults to
     * {@link JoinAnalysisFacts#EMPTY} for every legacy constructor.
     */
    private final JoinAnalysisFacts joinAnalysisFacts;
    /**
     * Optional block-level source span (slice 179, R5) covering this
     * statement's own text. Null when not set (e.g. DML / set-op paths that
     * do not thread the parse node). Read by {@code attachQueryBlockScopes}
     * to populate {@link QueryBlockScope#getSourceSpan()}.
     */
    private final SourceSpan sourceSpan;
    /**
     * Non-null only on a degrade placeholder (see {@link #KIND_UNANALYZED}):
     * the ERROR diagnostic explaining why this block could not be analyzed.
     */
    private final Diagnostic unanalyzedReason;

    /**
     * {@link #getKind() Kind} of a placeholder block emitted in place of a
     * nested block the builder could not analyze, when the caller opted in
     * via {@code SemanticIRBuildOptions.withDegradeUnsupportedNestedBlocks(true)}.
     *
     * <p>A placeholder carries no relations, no output columns and no clause
     * refs — <em>not</em> because the block had none, but because it was
     * never analyzed. Consumers that aggregate over
     * {@code SemanticProgram.getStatements()} MUST treat this kind as
     * "unknown", never as "empty": reading a placeholder as an ordinary
     * SELECT with zero joins turns a known gap into a silent false negative.
     * {@link #getUnanalyzedReason()} carries the cause and its source span.
     */
    public static final String KIND_UNANALYZED = "UNANALYZED";

    /**
     * Build the degrade placeholder for a nested block that could not be
     * analyzed. {@code name} is the synthetic block name the analyzed body
     * would have carried, so the block keeps its identity and its position
     * in {@code SemanticProgram.getStatements()}.
     *
     * @param name   synthetic block name (may be null)
     * @param reason non-null diagnostic explaining the rejection
     * @param span   optional span of the skipped block
     */
    public static StatementGraph unanalyzed(String name, Diagnostic reason, SourceSpan span) {
        if (reason == null) {
            throw new IllegalArgumentException("reason must be non-null");
        }
        return new StatementGraph(name, KIND_UNANALYZED,
                Collections.<RelationSource>emptyList(),
                Collections.<OutputColumn>emptyList(),
                Collections.<OutputColumn>emptyList(),
                Collections.<ColumnRef>emptyList(),
                Collections.<ColumnRef>emptyList(),
                Collections.<ColumnRef>emptyList(),
                Collections.<ColumnRef>emptyList(),
                Collections.<ColumnRef>emptyList(),
                Collections.<ColumnRef>emptyList(),
                Collections.<ColumnRef>emptyList(),
                Collections.<GroupingElement>emptyList(),
                Collections.<ColumnRef>emptyList(),
                /*distinct=*/ false, /*setOperator=*/ null, /*rowLimit=*/ null,
                /*target=*/ null, JoinAnalysisFacts.EMPTY, span, reason);
    }

    /**
     * Slice 129 primary constructor — adds the optional
     * {@code pivotColumnRefs} slot, the columns CONSUMED by a {@code PIVOT}
     * operator (the {@code FOR} / pivot column(s) followed by the
     * aggregation-function argument column(s)). The slot is always non-null
     * (use {@link Collections#emptyList()} when absent); non-empty only on a
     * SELECT whose FROM source is a {@code PIVOT}. All other slots are
     * unchanged. See {@link #getPivotColumnRefs()}.
     */
    public StatementGraph(String name,
                          String kind,
                          List<RelationSource> relations,
                          List<OutputColumn> outputColumns,
                          List<OutputColumn> returningColumns,
                          List<ColumnRef> filterColumnRefs,
                          List<ColumnRef> joinColumnRefs,
                          List<ColumnRef> groupByColumnRefs,
                          List<ColumnRef> havingColumnRefs,
                          List<ColumnRef> orderByColumnRefs,
                          List<ColumnRef> distinctOnColumnRefs,
                          List<ColumnRef> qualifyColumnRefs,
                          List<GroupingElement> groupingElements,
                          List<ColumnRef> pivotColumnRefs,
                          boolean distinct,
                          SetOperator setOperator,
                          RowLimit rowLimit,
                          TargetRelation target) {
        this(name, kind, relations, outputColumns, returningColumns,
                filterColumnRefs, joinColumnRefs, groupByColumnRefs,
                havingColumnRefs, orderByColumnRefs, distinctOnColumnRefs,
                qualifyColumnRefs, groupingElements, pivotColumnRefs,
                distinct, setOperator, rowLimit, target,
                JoinAnalysisFacts.EMPTY);
    }

    /**
     * Slice 167 primary constructor — adds the single optional
     * {@link JoinAnalysisFacts} carrier (GAP 1/2/4). Every prior
     * constructor delegates here with {@link JoinAnalysisFacts#EMPTY}, so
     * the additive slot does not grow the constructor surface per GAP. A
     * null {@code joinAnalysisFacts} coalesces to {@code EMPTY}.
     */
    public StatementGraph(String name,
                          String kind,
                          List<RelationSource> relations,
                          List<OutputColumn> outputColumns,
                          List<OutputColumn> returningColumns,
                          List<ColumnRef> filterColumnRefs,
                          List<ColumnRef> joinColumnRefs,
                          List<ColumnRef> groupByColumnRefs,
                          List<ColumnRef> havingColumnRefs,
                          List<ColumnRef> orderByColumnRefs,
                          List<ColumnRef> distinctOnColumnRefs,
                          List<ColumnRef> qualifyColumnRefs,
                          List<GroupingElement> groupingElements,
                          List<ColumnRef> pivotColumnRefs,
                          boolean distinct,
                          SetOperator setOperator,
                          RowLimit rowLimit,
                          TargetRelation target,
                          JoinAnalysisFacts joinAnalysisFacts) {
        this(name, kind, relations, outputColumns, returningColumns, filterColumnRefs,
                joinColumnRefs, groupByColumnRefs, havingColumnRefs, orderByColumnRefs,
                distinctOnColumnRefs, qualifyColumnRefs, groupingElements, pivotColumnRefs,
                distinct, setOperator, rowLimit, target, joinAnalysisFacts, /*sourceSpan=*/ null);
    }

    /**
     * Slice 179 (R5) primary constructor — adds the optional block-level
     * {@link SourceSpan} covering this statement's own source text. Every
     * prior constructor delegates here with a null span (additive). Set at
     * the SELECT construction site (where the parse node is in scope) and
     * read by {@code attachQueryBlockScopes} so each {@link QueryBlockScope}
     * carries an honest span.
     */
    public StatementGraph(String name,
                          String kind,
                          List<RelationSource> relations,
                          List<OutputColumn> outputColumns,
                          List<OutputColumn> returningColumns,
                          List<ColumnRef> filterColumnRefs,
                          List<ColumnRef> joinColumnRefs,
                          List<ColumnRef> groupByColumnRefs,
                          List<ColumnRef> havingColumnRefs,
                          List<ColumnRef> orderByColumnRefs,
                          List<ColumnRef> distinctOnColumnRefs,
                          List<ColumnRef> qualifyColumnRefs,
                          List<GroupingElement> groupingElements,
                          List<ColumnRef> pivotColumnRefs,
                          boolean distinct,
                          SetOperator setOperator,
                          RowLimit rowLimit,
                          TargetRelation target,
                          JoinAnalysisFacts joinAnalysisFacts,
                          SourceSpan sourceSpan) {
        this(name, kind, relations, outputColumns, returningColumns, filterColumnRefs,
                joinColumnRefs, groupByColumnRefs, havingColumnRefs, orderByColumnRefs,
                distinctOnColumnRefs, qualifyColumnRefs, groupingElements, pivotColumnRefs,
                distinct, setOperator, rowLimit, target, joinAnalysisFacts, sourceSpan,
                /*unanalyzedReason=*/ null);
    }

    /**
     * Full constructor — adds the optional {@code unanalyzedReason} slot
     * that marks a degrade placeholder. Private: placeholders are built
     * through {@link #unanalyzed(String, Diagnostic, SourceSpan)}, and every
     * public constructor delegates here with a null reason, so an ordinary
     * block can never be mistaken for a placeholder.
     */
    private StatementGraph(String name,
                          String kind,
                          List<RelationSource> relations,
                          List<OutputColumn> outputColumns,
                          List<OutputColumn> returningColumns,
                          List<ColumnRef> filterColumnRefs,
                          List<ColumnRef> joinColumnRefs,
                          List<ColumnRef> groupByColumnRefs,
                          List<ColumnRef> havingColumnRefs,
                          List<ColumnRef> orderByColumnRefs,
                          List<ColumnRef> distinctOnColumnRefs,
                          List<ColumnRef> qualifyColumnRefs,
                          List<GroupingElement> groupingElements,
                          List<ColumnRef> pivotColumnRefs,
                          boolean distinct,
                          SetOperator setOperator,
                          RowLimit rowLimit,
                          TargetRelation target,
                          JoinAnalysisFacts joinAnalysisFacts,
                          SourceSpan sourceSpan,
                          Diagnostic unanalyzedReason) {
        if (kind == null || kind.isEmpty()) {
            throw new IllegalArgumentException("kind must be non-empty");
        }
        // KIND_UNANALYZED and a non-null reason imply each other. Every public
        // constructor delegates here with a null reason, so a hand-built
        // statement cannot claim the reserved kind without its diagnostic —
        // that would make isUnanalyzed() false and silently walk past every
        // consumer safeguard (schema v4, projector / logical-builder refusal),
        // turning "unknown" into "empty". Placeholders are built only through
        // {@link #unanalyzed(String, Diagnostic, SourceSpan)}.
        if (KIND_UNANALYZED.equals(kind) != (unanalyzedReason != null)) {
            throw new IllegalArgumentException(KIND_UNANALYZED.equals(kind)
                    ? "kind " + KIND_UNANALYZED + " is reserved for degrade "
                            + "placeholders; use StatementGraph.unanalyzed(...)"
                    : "unanalyzedReason requires kind " + KIND_UNANALYZED);
        }
        if (relations == null || outputColumns == null
                || returningColumns == null
                || filterColumnRefs == null || joinColumnRefs == null
                || groupByColumnRefs == null || havingColumnRefs == null
                || orderByColumnRefs == null || distinctOnColumnRefs == null
                || qualifyColumnRefs == null || groupingElements == null
                || pivotColumnRefs == null) {
            throw new IllegalArgumentException(
                    "relations/outputColumns/returningColumns/filterColumnRefs/joinColumnRefs/"
                            + "groupByColumnRefs/havingColumnRefs/orderByColumnRefs/"
                            + "distinctOnColumnRefs/qualifyColumnRefs/groupingElements/"
                            + "pivotColumnRefs must not be null");
        }
        this.name = (name != null && name.isEmpty()) ? null : name;
        this.kind = kind;
        this.relations = Collections.unmodifiableList(new ArrayList<>(relations));
        this.outputColumns = Collections.unmodifiableList(new ArrayList<>(outputColumns));
        this.returningColumns = Collections.unmodifiableList(new ArrayList<>(returningColumns));
        this.filterColumnRefs = Collections.unmodifiableList(new ArrayList<>(filterColumnRefs));
        this.joinColumnRefs = Collections.unmodifiableList(new ArrayList<>(joinColumnRefs));
        this.groupByColumnRefs = Collections.unmodifiableList(new ArrayList<>(groupByColumnRefs));
        this.havingColumnRefs = Collections.unmodifiableList(new ArrayList<>(havingColumnRefs));
        this.orderByColumnRefs = Collections.unmodifiableList(new ArrayList<>(orderByColumnRefs));
        this.distinctOnColumnRefs = Collections.unmodifiableList(new ArrayList<>(distinctOnColumnRefs));
        this.qualifyColumnRefs = Collections.unmodifiableList(new ArrayList<>(qualifyColumnRefs));
        this.groupingElements = Collections.unmodifiableList(new ArrayList<>(groupingElements));
        this.pivotColumnRefs = Collections.unmodifiableList(new ArrayList<>(pivotColumnRefs));
        this.distinct = distinct;
        this.setOperator = setOperator;
        this.rowLimit = rowLimit;
        this.target = target;
        this.joinAnalysisFacts =
                joinAnalysisFacts == null ? JoinAnalysisFacts.EMPTY : joinAnalysisFacts;
        this.sourceSpan = sourceSpan;
        this.unanalyzedReason = unanalyzedReason;
    }

    /**
     * Return a copy of this statement with its {@link JoinAnalysisFacts}
     * replaced. Used by the builder (slices 167/168/169/170) to attach
     * join/predicate/scope facts after the flat graph is built, without
     * mutating this immutable value. Preserves the block {@link #sourceSpan}.
     */
    public StatementGraph withJoinAnalysisFacts(JoinAnalysisFacts facts) {
        return new StatementGraph(name, kind, relations, outputColumns, returningColumns,
                filterColumnRefs, joinColumnRefs, groupByColumnRefs, havingColumnRefs,
                orderByColumnRefs, distinctOnColumnRefs, qualifyColumnRefs, groupingElements,
                pivotColumnRefs, distinct, setOperator, rowLimit, target, facts, sourceSpan,
                unanalyzedReason);
    }

    /**
     * Return a copy of this statement with its block-level
     * {@link #sourceSpan} replaced (slice 179, R5). Preserves the
     * {@link JoinAnalysisFacts}.
     */
    public StatementGraph withSourceSpan(SourceSpan newSourceSpan) {
        return new StatementGraph(name, kind, relations, outputColumns, returningColumns,
                filterColumnRefs, joinColumnRefs, groupByColumnRefs, havingColumnRefs,
                orderByColumnRefs, distinctOnColumnRefs, qualifyColumnRefs, groupingElements,
                pivotColumnRefs, distinct, setOperator, rowLimit, target,
                joinAnalysisFacts, newSourceSpan, unanalyzedReason);
    }

    /**
     * Slice 128 primary constructor preserved — adds the optional
     * {@code groupingElements} slot, the structured per-top-level-element
     * view of the {@code GROUP BY} ({@code SIMPLE} / {@code ROLLUP} /
     * {@code CUBE} / {@code GROUPING SETS}; see {@link GroupingElement}).
     * Delegates to the slice-129 primary with empty {@code pivotColumnRefs}.
     */
    public StatementGraph(String name,
                          String kind,
                          List<RelationSource> relations,
                          List<OutputColumn> outputColumns,
                          List<OutputColumn> returningColumns,
                          List<ColumnRef> filterColumnRefs,
                          List<ColumnRef> joinColumnRefs,
                          List<ColumnRef> groupByColumnRefs,
                          List<ColumnRef> havingColumnRefs,
                          List<ColumnRef> orderByColumnRefs,
                          List<ColumnRef> distinctOnColumnRefs,
                          List<ColumnRef> qualifyColumnRefs,
                          List<GroupingElement> groupingElements,
                          boolean distinct,
                          SetOperator setOperator,
                          RowLimit rowLimit,
                          TargetRelation target) {
        this(name, kind, relations, outputColumns, returningColumns,
                filterColumnRefs, joinColumnRefs, groupByColumnRefs,
                havingColumnRefs, orderByColumnRefs,
                distinctOnColumnRefs, qualifyColumnRefs, groupingElements,
                Collections.<ColumnRef>emptyList(),
                distinct, setOperator, rowLimit, target);
    }

    /**
     * Slice 125 primary constructor preserved — adds the optional
     * {@code qualifyColumnRefs} slot for the {@code QUALIFY} clause
     * (Snowflake / BigQuery / Teradata). Delegates to the slice-128
     * primary constructor with empty {@code groupingElements}.
     */
    public StatementGraph(String name,
                          String kind,
                          List<RelationSource> relations,
                          List<OutputColumn> outputColumns,
                          List<OutputColumn> returningColumns,
                          List<ColumnRef> filterColumnRefs,
                          List<ColumnRef> joinColumnRefs,
                          List<ColumnRef> groupByColumnRefs,
                          List<ColumnRef> havingColumnRefs,
                          List<ColumnRef> orderByColumnRefs,
                          List<ColumnRef> distinctOnColumnRefs,
                          List<ColumnRef> qualifyColumnRefs,
                          boolean distinct,
                          SetOperator setOperator,
                          RowLimit rowLimit,
                          TargetRelation target) {
        this(name, kind, relations, outputColumns, returningColumns,
                filterColumnRefs, joinColumnRefs, groupByColumnRefs,
                havingColumnRefs, orderByColumnRefs,
                distinctOnColumnRefs, qualifyColumnRefs,
                Collections.<GroupingElement>emptyList(),
                distinct, setOperator, rowLimit, target);
    }

    /**
     * Slice 85 constructor preserved so production code that predates
     * slice 125 keeps compiling unchanged. Delegates to the slice-125
     * primary constructor with empty {@code qualifyColumnRefs}. QUALIFY
     * is a SELECT-only clause, so DML / predicate-body / set-op-outer
     * call sites correctly default to empty.
     */
    public StatementGraph(String name,
                          String kind,
                          List<RelationSource> relations,
                          List<OutputColumn> outputColumns,
                          List<OutputColumn> returningColumns,
                          List<ColumnRef> filterColumnRefs,
                          List<ColumnRef> joinColumnRefs,
                          List<ColumnRef> groupByColumnRefs,
                          List<ColumnRef> havingColumnRefs,
                          List<ColumnRef> orderByColumnRefs,
                          List<ColumnRef> distinctOnColumnRefs,
                          boolean distinct,
                          SetOperator setOperator,
                          RowLimit rowLimit,
                          TargetRelation target) {
        this(name, kind, relations, outputColumns, returningColumns,
                filterColumnRefs, joinColumnRefs, groupByColumnRefs,
                havingColumnRefs, orderByColumnRefs,
                distinctOnColumnRefs,
                Collections.<ColumnRef>emptyList(),
                distinct, setOperator, rowLimit, target);
    }

    /**
     * Slice 78 constructor preserved so production code that predates
     * slice 85 keeps compiling unchanged. Delegates to the slice-85
     * constructor with empty {@code returningColumns}.
     */
    public StatementGraph(String name,
                          String kind,
                          List<RelationSource> relations,
                          List<OutputColumn> outputColumns,
                          List<ColumnRef> filterColumnRefs,
                          List<ColumnRef> joinColumnRefs,
                          List<ColumnRef> groupByColumnRefs,
                          List<ColumnRef> havingColumnRefs,
                          List<ColumnRef> orderByColumnRefs,
                          List<ColumnRef> distinctOnColumnRefs,
                          boolean distinct,
                          SetOperator setOperator,
                          RowLimit rowLimit,
                          TargetRelation target) {
        this(name, kind, relations, outputColumns,
                Collections.<OutputColumn>emptyList(),
                filterColumnRefs, joinColumnRefs, groupByColumnRefs,
                havingColumnRefs, orderByColumnRefs,
                distinctOnColumnRefs,
                distinct, setOperator, rowLimit, target);
    }

    /**
     * Slice 73 constructor preserved so SELECT-kind production code that
     * predates slice 78 keeps compiling unchanged. Delegates to the
     * slice-78 constructor with {@code target=null}.
     */
    public StatementGraph(String name,
                          String kind,
                          List<RelationSource> relations,
                          List<OutputColumn> outputColumns,
                          List<ColumnRef> filterColumnRefs,
                          List<ColumnRef> joinColumnRefs,
                          List<ColumnRef> groupByColumnRefs,
                          List<ColumnRef> havingColumnRefs,
                          List<ColumnRef> orderByColumnRefs,
                          List<ColumnRef> distinctOnColumnRefs,
                          boolean distinct,
                          SetOperator setOperator,
                          RowLimit rowLimit) {
        this(name, kind, relations, outputColumns,
                filterColumnRefs, joinColumnRefs, groupByColumnRefs,
                havingColumnRefs, orderByColumnRefs,
                distinctOnColumnRefs,
                distinct, setOperator, rowLimit, /*target=*/ null);
    }

    /**
     * Slice 125 SELECT constructor — the slice-73 SELECT shape plus the
     * {@code qualifyColumnRefs} slot. Used by the shared SELECT builder
     * ({@code SemanticIRBuilder.buildSelectStatementImpl}) so a SELECT
     * carrying a QUALIFY clause can pass its resolved filter refs.
     * Delegates to the slice-125 primary constructor with empty
     * {@code returningColumns} and {@code target=null}. The parameter
     * list differs from the slice-78 14-arg constructor by type
     * (a {@code List} {@code qualifyColumnRefs} at position 11 vs a
     * {@code boolean distinct} there), so overload resolution is
     * unambiguous.
     */
    public StatementGraph(String name,
                          String kind,
                          List<RelationSource> relations,
                          List<OutputColumn> outputColumns,
                          List<ColumnRef> filterColumnRefs,
                          List<ColumnRef> joinColumnRefs,
                          List<ColumnRef> groupByColumnRefs,
                          List<ColumnRef> havingColumnRefs,
                          List<ColumnRef> orderByColumnRefs,
                          List<ColumnRef> distinctOnColumnRefs,
                          List<ColumnRef> qualifyColumnRefs,
                          boolean distinct,
                          SetOperator setOperator,
                          RowLimit rowLimit) {
        this(name, kind, relations, outputColumns,
                Collections.<OutputColumn>emptyList(),
                filterColumnRefs, joinColumnRefs, groupByColumnRefs,
                havingColumnRefs, orderByColumnRefs,
                distinctOnColumnRefs,
                qualifyColumnRefs,
                distinct, setOperator, rowLimit, /*target=*/ null);
    }

    /**
     * Slice 128 SELECT constructor — the slice-125 SELECT shape plus the
     * {@code groupingElements} slot, the structured GROUP BY view. Used by
     * the shared SELECT builder ({@code SemanticIRBuilder}) so a SELECT
     * with a GROUP BY can pass its structured grouping elements. Delegates
     * to the slice-128 primary with empty {@code returningColumns} and
     * {@code target=null}. The parameter list differs from the slice-125
     * 14-arg SELECT constructor by the extra {@code List groupingElements}
     * arg, so overload resolution is unambiguous.
     */
    public StatementGraph(String name,
                          String kind,
                          List<RelationSource> relations,
                          List<OutputColumn> outputColumns,
                          List<ColumnRef> filterColumnRefs,
                          List<ColumnRef> joinColumnRefs,
                          List<ColumnRef> groupByColumnRefs,
                          List<ColumnRef> havingColumnRefs,
                          List<ColumnRef> orderByColumnRefs,
                          List<ColumnRef> distinctOnColumnRefs,
                          List<ColumnRef> qualifyColumnRefs,
                          List<GroupingElement> groupingElements,
                          boolean distinct,
                          SetOperator setOperator,
                          RowLimit rowLimit) {
        this(name, kind, relations, outputColumns,
                Collections.<OutputColumn>emptyList(),
                filterColumnRefs, joinColumnRefs, groupByColumnRefs,
                havingColumnRefs, orderByColumnRefs,
                distinctOnColumnRefs,
                qualifyColumnRefs,
                groupingElements,
                distinct, setOperator, rowLimit, /*target=*/ null);
    }

    /**
     * Slice 129 PIVOT SELECT constructor — a {@code SELECT} whose FROM
     * source is a {@code PIVOT}. Carries {@code relations} (the underlying
     * pivot source), {@code outputColumns} (one per projected column), and
     * {@code pivotColumnRefs} (the consumed FOR + aggregation-arg columns).
     * Every other slot defaults empty / null: a slice-129 PIVOT skeleton has
     * no filter / join / group-by / having / order-by / distinct-on /
     * qualify / grouping / returning refs, is not {@code DISTINCT}, is not a
     * set-op, has no row-limit, and writes no target. The five-arg shape is
     * unambiguous against every other constructor.
     */
    public StatementGraph(String name,
                          String kind,
                          List<RelationSource> relations,
                          List<OutputColumn> outputColumns,
                          List<ColumnRef> pivotColumnRefs) {
        this(name, kind, relations, outputColumns,
                Collections.<OutputColumn>emptyList(),
                Collections.<ColumnRef>emptyList(),
                Collections.<ColumnRef>emptyList(),
                Collections.<ColumnRef>emptyList(),
                Collections.<ColumnRef>emptyList(),
                Collections.<ColumnRef>emptyList(),
                Collections.<ColumnRef>emptyList(),
                Collections.<ColumnRef>emptyList(),
                Collections.<GroupingElement>emptyList(),
                pivotColumnRefs,
                /*distinct=*/ false, /*setOperator=*/ null,
                /*rowLimit=*/ null, /*target=*/ null);
    }

    /**
     * Slice 156 PIVOT SELECT constructor — the slice-129 PIVOT shape plus a
     * {@code filterColumnRefs} slot for an admitted passthrough-only
     * {@code WHERE} clause over a PIVOT (every WHERE ref resolves to a provable
     * passthrough source column). All other clause slots default empty / null,
     * exactly as the five-arg PIVOT constructor — so an admitted PIVOT without a
     * WHERE (empty {@code filterColumnRefs}) is byte-identical to the five-arg
     * form. The six-arg shape (two {@code List<ColumnRef>} trailing args) is
     * unambiguous against every other constructor by arity.
     */
    public StatementGraph(String name,
                          String kind,
                          List<RelationSource> relations,
                          List<OutputColumn> outputColumns,
                          List<ColumnRef> filterColumnRefs,
                          List<ColumnRef> pivotColumnRefs) {
        this(name, kind, relations, outputColumns,
                Collections.<OutputColumn>emptyList(),
                filterColumnRefs,
                Collections.<ColumnRef>emptyList(),
                Collections.<ColumnRef>emptyList(),
                Collections.<ColumnRef>emptyList(),
                Collections.<ColumnRef>emptyList(),
                Collections.<ColumnRef>emptyList(),
                Collections.<ColumnRef>emptyList(),
                Collections.<GroupingElement>emptyList(),
                pivotColumnRefs,
                /*distinct=*/ false, /*setOperator=*/ null,
                /*rowLimit=*/ null, /*target=*/ null);
    }

    /**
     * Slice 158 PIVOT SELECT constructor — the slice-156 PIVOT shape plus a
     * {@code groupByColumnRefs} slot for an admitted passthrough-only
     * {@code GROUP BY} clause over a PIVOT/UNPIVOT (every GROUP BY ref resolves
     * to a provable passthrough source column). All other clause slots default
     * empty / null, exactly as the six-arg PIVOT constructor — so an admitted
     * PIVOT without a GROUP BY (empty {@code groupByColumnRefs}) is byte-identical
     * to the six-arg form. The seven-arg shape (three {@code List<ColumnRef>}
     * trailing args) is unambiguous against every other constructor by arity.
     */
    public StatementGraph(String name,
                          String kind,
                          List<RelationSource> relations,
                          List<OutputColumn> outputColumns,
                          List<ColumnRef> filterColumnRefs,
                          List<ColumnRef> groupByColumnRefs,
                          List<ColumnRef> pivotColumnRefs) {
        this(name, kind, relations, outputColumns,
                Collections.<OutputColumn>emptyList(),
                filterColumnRefs,
                Collections.<ColumnRef>emptyList(),
                groupByColumnRefs,
                Collections.<ColumnRef>emptyList(),
                Collections.<ColumnRef>emptyList(),
                Collections.<ColumnRef>emptyList(),
                Collections.<ColumnRef>emptyList(),
                Collections.<GroupingElement>emptyList(),
                pivotColumnRefs,
                /*distinct=*/ false, /*setOperator=*/ null,
                /*rowLimit=*/ null, /*target=*/ null);
    }

    /**
     * Slice 159 PIVOT SELECT constructor — the slice-158 PIVOT shape plus a
     * {@code qualifyColumnRefs} slot for an admitted passthrough-only
     * {@code QUALIFY} clause over a PIVOT/UNPIVOT (every QUALIFY ref resolves to a
     * provable passthrough source column). All other clause slots default empty /
     * null, exactly as the seven-arg PIVOT constructor — so an admitted PIVOT
     * without a QUALIFY (empty {@code qualifyColumnRefs}) is byte-identical to the
     * seven-arg form. The eight-arg shape (four {@code List<ColumnRef>} trailing
     * args) is unambiguous against every other constructor by arity.
     */
    public StatementGraph(String name,
                          String kind,
                          List<RelationSource> relations,
                          List<OutputColumn> outputColumns,
                          List<ColumnRef> filterColumnRefs,
                          List<ColumnRef> groupByColumnRefs,
                          List<ColumnRef> qualifyColumnRefs,
                          List<ColumnRef> pivotColumnRefs) {
        this(name, kind, relations, outputColumns,
                Collections.<OutputColumn>emptyList(),
                filterColumnRefs,
                Collections.<ColumnRef>emptyList(),
                groupByColumnRefs,
                Collections.<ColumnRef>emptyList(),
                Collections.<ColumnRef>emptyList(),
                Collections.<ColumnRef>emptyList(),
                qualifyColumnRefs,
                Collections.<GroupingElement>emptyList(),
                pivotColumnRefs,
                /*distinct=*/ false, /*setOperator=*/ null,
                /*rowLimit=*/ null, /*target=*/ null);
    }

    /**
     * Slice 160 PIVOT SELECT constructor — the slice-159 PIVOT shape plus a
     * {@code havingColumnRefs} slot for an admitted passthrough-only
     * {@code HAVING} clause over a PIVOT/UNPIVOT (every HAVING ref resolves to a
     * provable passthrough source column). All other clause slots default empty /
     * null, exactly as the eight-arg PIVOT constructor — so an admitted PIVOT
     * without a HAVING (empty {@code havingColumnRefs}) is byte-identical to the
     * eight-arg form. The nine-arg shape (five {@code List<ColumnRef>} trailing
     * args) is unambiguous against every other constructor by arity. The trailing
     * args follow the natural SQL clause order: filter (WHERE), groupBy, having,
     * qualify, then the consumed pivot refs.
     */
    public StatementGraph(String name,
                          String kind,
                          List<RelationSource> relations,
                          List<OutputColumn> outputColumns,
                          List<ColumnRef> filterColumnRefs,
                          List<ColumnRef> groupByColumnRefs,
                          List<ColumnRef> havingColumnRefs,
                          List<ColumnRef> qualifyColumnRefs,
                          List<ColumnRef> pivotColumnRefs) {
        this(name, kind, relations, outputColumns,
                Collections.<OutputColumn>emptyList(),
                filterColumnRefs,
                Collections.<ColumnRef>emptyList(),
                groupByColumnRefs,
                havingColumnRefs,
                Collections.<ColumnRef>emptyList(),
                Collections.<ColumnRef>emptyList(),
                qualifyColumnRefs,
                Collections.<GroupingElement>emptyList(),
                pivotColumnRefs,
                /*distinct=*/ false, /*setOperator=*/ null,
                /*rowLimit=*/ null, /*target=*/ null);
    }

    /**
     * Slice 161 PIVOT SELECT constructor — the slice-160 PIVOT shape plus an
     * {@code orderByColumnRefs} slot for a passthrough-only {@code ORDER BY}
     * clause over a PIVOT/UNPIVOT (every sort key resolves to a provable
     * passthrough source column). UNLIKE the WHERE/GROUP BY/HAVING/QUALIFY
     * slots, an ORDER BY over a pivot was already admitted (slice 142,
     * lineage-neutral), so this slot only refines the lineage and is empty when
     * no passthrough sort key can be proven. All other clause slots default
     * empty / null, exactly as the nine-arg PIVOT constructor — so an admitted
     * PIVOT without a passthrough ORDER BY (empty {@code orderByColumnRefs}) is
     * byte-identical to the nine-arg form. The ten-arg shape (six
     * {@code List<ColumnRef>} trailing args) is unambiguous against every other
     * constructor by arity. The trailing args follow the natural SQL clause
     * order: filter (WHERE), groupBy, having, qualify, orderBy, then the
     * consumed pivot refs.
     */
    public StatementGraph(String name,
                          String kind,
                          List<RelationSource> relations,
                          List<OutputColumn> outputColumns,
                          List<ColumnRef> filterColumnRefs,
                          List<ColumnRef> groupByColumnRefs,
                          List<ColumnRef> havingColumnRefs,
                          List<ColumnRef> qualifyColumnRefs,
                          List<ColumnRef> orderByColumnRefs,
                          List<ColumnRef> pivotColumnRefs) {
        this(name, kind, relations, outputColumns,
                Collections.<OutputColumn>emptyList(),
                filterColumnRefs,
                Collections.<ColumnRef>emptyList(),
                groupByColumnRefs,
                havingColumnRefs,
                orderByColumnRefs,
                Collections.<ColumnRef>emptyList(),
                qualifyColumnRefs,
                Collections.<GroupingElement>emptyList(),
                pivotColumnRefs,
                /*distinct=*/ false, /*setOperator=*/ null,
                /*rowLimit=*/ null, /*target=*/ null);
    }

    /**
     * Pre-slice-73 constructor preserved so hand-built test fixtures
     * (e.g. {@code SemanticIRProjectorBodyIndexesTest}) continue to
     * compile without touching every call site. Delegates to the
     * slice-73 constructor with an empty {@code distinctOnColumnRefs}
     * list. New production code should call the slice-78 primary
     * constructor directly.
     */
    public StatementGraph(String name,
                          String kind,
                          List<RelationSource> relations,
                          List<OutputColumn> outputColumns,
                          List<ColumnRef> filterColumnRefs,
                          List<ColumnRef> joinColumnRefs,
                          List<ColumnRef> groupByColumnRefs,
                          List<ColumnRef> havingColumnRefs,
                          List<ColumnRef> orderByColumnRefs,
                          boolean distinct,
                          SetOperator setOperator,
                          RowLimit rowLimit) {
        this(name, kind, relations, outputColumns,
                filterColumnRefs, joinColumnRefs, groupByColumnRefs,
                havingColumnRefs, orderByColumnRefs,
                Collections.<ColumnRef>emptyList(),
                distinct, setOperator, rowLimit);
    }

    /** Nullable: name for a CTE body or FROM-subquery alias, else null. */
    public String getName() {
        return name;
    }

    public String getKind() {
        return kind;
    }

    /**
     * @return the diagnostic explaining why this block was not analyzed, or
     *         {@code null} for an ordinary (fully analyzed) block. Non-null
     *         exactly when {@link #getKind()} is
     *         {@value #KIND_UNANALYZED}; see
     *         {@code SemanticIRBuildOptions.withDegradeUnsupportedNestedBlocks}.
     */
    public Diagnostic getUnanalyzedReason() {
        return unanalyzedReason;
    }

    /**
     * @return {@code true} when this entry is a degrade placeholder standing
     *         in for a nested block the builder could not analyze. Its empty
     *         relation / column lists mean "not analyzed", never "none
     *         present".
     */
    public boolean isUnanalyzed() {
        return unanalyzedReason != null;
    }

    public List<RelationSource> getRelations() {
        return relations;
    }

    public List<OutputColumn> getOutputColumns() {
        return outputColumns;
    }

    /**
     * Slice 85 — RETURNING / OUTPUT projection columns for INSERT / UPDATE /
     * DELETE statements. Empty list on every SELECT-kind statement (CTE
     * body / FROM-subquery / scalar / set-op branch / outer), on every
     * DML statement that did not supply a RETURNING (PG / Oracle) or
     * OUTPUT (SQL Server) clause, and on CTAS / CREATE VIEW statements.
     *
     * <p>For PG / Oracle RETURNING, each entry's
     * {@link OutputColumn#getName()} is the explicit alias when present,
     * else the verbatim bare column spelling.
     * {@link OutputColumn#getSources()} lists the underlying column refs;
     * the {@code relationAlias} resolves through the same provider used
     * for SET RHS / WHERE / JOIN ON, so a joined-UPDATE with
     * {@code RETURNING t.a, s.x} produces refs against both target and
     * FROM-side relations.
     *
     * <p>For SQL Server OUTPUT pseudo-table refs (INSERTED.col,
     * DELETED.col), the {@code relationAlias} is preserved as the
     * uppercase pseudo-table name ({@code "INSERTED"} or
     * {@code "DELETED"}) so consumers can distinguish post-write from
     * pre-write row state. Lineage edges still flow to
     * {@link LineageRef#tableColumn(String, String)} pointing at the
     * physical target table column — both INSERTED and DELETED ultimately
     * reference the same physical column; only the temporal phase differs.
     */
    public List<OutputColumn> getReturningColumns() {
        return returningColumns;
    }

    public List<ColumnRef> getFilterColumnRefs() {
        return filterColumnRefs;
    }

    public List<ColumnRef> getJoinColumnRefs() {
        return joinColumnRefs;
    }

    public List<ColumnRef> getGroupByColumnRefs() {
        return groupByColumnRefs;
    }

    /**
     * Column references that appear in the {@code HAVING} clause's
     * predicate. The list is per-statement and per-clause: a HAVING
     * predicate that names {@code d.id} contributes one entry; a HAVING
     * predicate inside an aggregate ({@code HAVING SUM(salary) > 1000})
     * contributes the underlying column ({@code salary}) — the same
     * convention used for projection-side aggregate arguments
     * (slice 6 OutputColumn.sources).
     *
     * <p>Subqueries in HAVING (scalar, EXISTS, IN-SELECT, ANY/ALL/SOME)
     * and window functions in HAVING are rejected by the builder rather
     * than silently captured, because the visitor would descend into
     * inner scopes and leak refs (mirrors the slice-9 ORDER BY guards).
     *
     * <p>HAVING is row-influence semantically (it filters out groups),
     * but it deliberately does <i>not</i> contribute to the canonical
     * lineage model (slice 7 / {@code CanonicalLineageEdge}). The
     * canonical model is a parity contract between IR and dlineage, and
     * dlineage exposes no per-clause HAVING field — it folds HAVING refs
     * into aggregate-function fdr/fdd edges. Including HAVING-derived
     * canonical edges only on the IR side would manufacture
     * divergence-by-design. The {@code havingColumnRefs} field remains
     * useful for downstream consumers (SQL Guard, lineage explainers)
     * that don't depend on the dlineage parity contract.
     */
    public List<ColumnRef> getHavingColumnRefs() {
        return havingColumnRefs;
    }

    /**
     * Column references that appear in the {@code ORDER BY} clause's sort
     * keys. Only physical column references are recorded — ordinal
     * ({@code ORDER BY 1}) and projection-alias ({@code ORDER BY x})
     * forms are rejected by the builder, not silently emitted as
     * {@code []}. Sort direction ({@code ASC}/{@code DESC}) and null
     * placement ({@code NULLS FIRST}/{@code NULLS LAST}) are presentation
     * metadata and are not modelled.
     *
     * <p>The flag is per-statement: in
     * {@code WITH x AS (... ORDER BY id) SELECT id FROM x} the inner
     * statement's {@code orderByColumnRefs} contains {@code id} while the
     * outer's is empty.
     */
    public List<ColumnRef> getOrderByColumnRefs() {
        return orderByColumnRefs;
    }

    /**
     * Whether the statement applies row-deduplication. True for
     * {@code SELECT DISTINCT}, Oracle's deprecated synonym
     * {@code SELECT UNIQUE}, AND PostgreSQL / Greenplum
     * {@code SELECT DISTINCT ON (cols)}; false for {@code SELECT},
     * {@code SELECT ALL}, and the absence of any row-filter clause.
     * The flag is per-statement, never per-output.
     *
     * <p>For {@code DISTINCT ON (cols)} the partition keys live on
     * {@link #getDistinctOnColumnRefs()}; the boolean here pins the
     * semantic invariant that the statement deduplicates rows
     * regardless of which key shape is used.
     */
    public boolean isDistinct() {
        return distinct;
    }

    /**
     * Column references in the {@code DISTINCT ON (cols)} partition list
     * (PostgreSQL / Greenplum). Empty for plain {@code SELECT DISTINCT},
     * {@code SELECT UNIQUE}, {@code SELECT ALL}, and the absence of any
     * row-filter clause.
     *
     * <p>Invariant: {@code !distinctOnColumnRefs.isEmpty()} implies
     * {@link #isDistinct()} == {@code true}. The reverse does not hold
     * (plain {@code DISTINCT} also returns {@code true}).
     *
     * <p>The list collects physical column refs the same way
     * {@code groupByColumnRefs} does: column refs inside compound
     * expressions ({@code a + b}, {@code CASE WHEN ...}) and aggregate
     * arguments ({@code COUNT(x)}) are descended into; subqueries and
     * window functions in {@code DISTINCT ON} are rejected by the
     * builder so they cannot leak inner-scope refs.
     *
     * <p>Oracle, MySQL, Redshift and other non-PG vendors silently
     * accept {@code DISTINCT ON (...)} as plain {@code DISTINCT} —
     * their parser drops the ON expression list, so this slot stays
     * empty for those vendors regardless of the surface SQL.
     */
    public List<ColumnRef> getDistinctOnColumnRefs() {
        return distinctOnColumnRefs;
    }

    /**
     * Column references that appear in the {@code QUALIFY} clause's
     * predicate (Snowflake / BigQuery / Teradata). QUALIFY filters rows on
     * window-function results; it is row-influence in the same family as
     * {@code WHERE} and {@code HAVING}.
     *
     * <p>Two surface forms reduce to the SAME set of influencing base
     * columns:
     * <ul>
     *   <li>Inline window form
     *       ({@code QUALIFY ROW_NUMBER() OVER (PARTITION BY a ORDER BY b) = 1})
     *       — the window's PARTITION BY / ORDER BY / argument refs are
     *       collected directly ({@code a}, {@code b}).</li>
     *   <li>Projection-alias form ({@code QUALIFY rn = 1} where
     *       {@code rn} aliases a window projection) — the alias resolves to
     *       the matching {@link OutputColumn}; its influencing columns are
     *       {@code getSources()} unioned with the
     *       {@link WindowSpec#getPartitionRefs()} and
     *       {@link WindowSpec#getOrderRefs()} of its window spec (a window
     *       {@link OutputColumn#getSources()} is empty on its own).</li>
     * </ul>
     *
     * <p>Subqueries in QUALIFY are rejected by the builder (they would
     * leak inner-scope refs); window functions are admitted (the whole
     * point of QUALIFY).
     *
     * <p>Like {@code havingColumnRefs}, this slot is row-influence
     * semantically but deliberately does <i>not</i> contribute to the
     * canonical lineage model (slice 7 / {@code CanonicalLineageEdge}).
     * The canonical model is a parity contract with dlineage, which
     * exposes no per-clause QUALIFY field; emitting QUALIFY-derived
     * canonical edges only on the IR side would manufacture
     * divergence-by-design.
     */
    public List<ColumnRef> getQualifyColumnRefs() {
        return qualifyColumnRefs;
    }

    /**
     * Structured per-top-level-element view of the {@code GROUP BY} (slice
     * 128): one {@link GroupingElement} per top-level grouping item in
     * document order, each tagged {@code SIMPLE} / {@code ROLLUP} /
     * {@code CUBE} / {@code GROUPING_SETS} with its flattened member
     * columns. Empty iff the statement has no {@code GROUP BY} items; a
     * plain {@code GROUP BY a, b} yields {@code [SIMPLE: a, SIMPLE: b]}.
     *
     * <p>This is additive to {@link #getGroupByColumnRefs()}, which still
     * returns the flat, deduplicated, document-order union of every
     * grouping column (slice 127) regardless of grouping structure.
     * {@code groupingElements} preserves the structure the flat list
     * discards — relevant for governance (a {@code ROLLUP}/{@code CUBE}
     * changes output cardinality and produces super-aggregate rows) and
     * for downstream OpenLineage / DataHub consumers.
     */
    public List<GroupingElement> getGroupingElements() {
        return groupingElements;
    }

    /**
     * Slice 129 — columns CONSUMED by a {@code PIVOT} operator, in document
     * order: the {@code FOR} / pivot column(s) first, then the
     * aggregation-function argument column(s). All resolve to the underlying
     * pivot source relation ({@link #getRelations()}). Empty on every
     * non-PIVOT statement.
     *
     * <p>These are the input columns a PIVOT reads; the IN-list values
     * become the new output column names (synthesised in a later sub-slice).
     * Function names, literals, and column-alias nodes (e.g. the Oracle
     * {@code SUM(quantity) AS q}) are not columns and do not appear here.
     *
     * <p>Slice 129 (sub-slice a) admits only a PIVOT over a base-table
     * source with an explicit (non-{@code *}) projection and no other query
     * clauses; broader shapes (UNPIVOT, subquery source, {@code SELECT *}
     * expansion, output-column lineage) are deferred to later sub-slices and
     * rejected with structured {@code PIVOT_*} diagnostics until then.
     */
    public List<ColumnRef> getPivotColumnRefs() {
        return pivotColumnRefs;
    }

    /**
     * Set-operation kind for the outer statement of a set-op program
     * (slice 12). Returns null on every regular SELECT statement and on
     * every CTE / FROM-subquery / scalar / set-op-branch body. The
     * {@code _ALL} variants encode {@code TSelectSqlStatement#isAll()};
     * {@code MINUS} (Oracle / Spark / Hive) and {@code EXCEPT}
     * (PostgreSQL / SQL Server / standard) are kept distinct because the
     * parser exposes them as separate
     * {@link gudusoft.gsqlparser.ESetOperatorType} values, even though
     * they are semantically equivalent.
     */
    public SetOperator getSetOperator() {
        return setOperator;
    }

    /**
     * Per-statement row-limit metadata (slice 70). Returns null when no
     * row-limit clause was present, or when the row-limit clause is in
     * slice-71 / 72 territory (TOP, standalone OFFSET, PG inline
     * {@code LIMIT N OFFSET M}, MySQL inline {@code LIMIT M, N},
     * set-op outer row-limit) — those surfaces continue to be rejected
     * by the builder with their existing diagnostic codes.
     *
     * <p>When non-null, the {@link RowLimit#getKind()} captures which
     * surface SQL form was used ({@code LIMIT} vs {@code FETCH FIRST})
     * and {@link RowLimit#getCount()} captures the verbatim count text.
     *
     * <p>Row-limit metadata does <i>not</i> change column lineage. The
     * canonical lineage model (slice 7 / {@code CanonicalLineageEdge})
     * deliberately ignores it: row-limit is presentation-time pruning,
     * not a column-flow influence. ORDER BY refs, output sources,
     * filter / join / group-by / having refs are all unaffected.
     */
    public RowLimit getRowLimit() {
        return rowLimit;
    }

    /**
     * Slice 78 — write-side target for INSERT statements. Non-null only on
     * {@code "INSERT"}-kind statements; null on every {@code "SELECT"}-kind
     * statement (whether the SELECT is an outer, CTE body, FROM-subquery
     * body, scalar-subquery body, or set-op branch).
     *
     * <p>When non-null, {@link TargetRelation#getBinding()} is the target
     * table (kind = {@link RelationKind#TABLE}) and
     * {@link TargetRelation#getColumns()} holds the verbatim SQL column-list
     * spellings (empty list when the SQL author omitted the column list).
     *
     * <p>Cross-statement {@link LineageEdge}s for INSERT use
     * {@link LineageRef#tableColumn(String, String)} as the {@code from}
     * endpoint (target_table, target_col) and
     * {@link LineageRef#statementOutput(int, String)} as the {@code to}
     * endpoint (source SELECT body statement index + output name).
     */
    public TargetRelation getTarget() {
        return target;
    }

    /**
     * Join-analysis facts for this query block (slice 167, GAP 1/2/4):
     * the structured {@link JoinGraph}, WHERE filter predicates, and
     * query-block scope. Never null ({@link JoinAnalysisFacts#EMPTY} when
     * not populated).
     */
    public JoinAnalysisFacts getJoinAnalysisFacts() {
        return joinAnalysisFacts;
    }

    /**
     * Convenience accessor for the structured {@link JoinGraph} (slice
     * 167). Never null ({@link JoinGraph#EMPTY} when this block has no
     * modelled joins).
     */
    public JoinGraph getJoinGraph() {
        return joinAnalysisFacts.getJoinGraph();
    }

    /**
     * Optional block-level source span (slice 179, R5) covering this
     * statement's own text, or {@code null} when not set. The same span is
     * surfaced on {@link QueryBlockScope#getSourceSpan()}.
     */
    public SourceSpan getSourceSpan() {
        return sourceSpan;
    }
}