logical

type AggCallProvenance struct {
	// AggColIdx is the index of the producing column; -1 for the synthesized
	// COUNT(*), which has no parsed column and no operand to resolve.
	AggColIdx int
	// Operand is that column's operand text as rendered BEFORE strip.
	Operand string
}

type AggregateCall struct {
	Func     string // upper-case aggregate function name (COUNT/SUM/MIN/MAX/AVG)
	Operand  string // canonical operand text; "*" for COUNT(*)
	Star     bool   // COUNT(*) (or COUNT(<non-null const>) collapsed to it)
	Distinct bool
	// IgnoreNulls and Limit are ARRAY_AGG's options (values.ArrayAggNoLimit
	// when uncapped).
	IgnoreNulls bool
	Limit       int
	// BareColumn: the operand is a single column reference PER THE PARSE
	// TREE — a lazy FieldValue read of Operand is well-defined without
	// catalog resolution. False for computed/expression operands, which
	// require a resolved Value.
	BareColumn bool
	// Qualified: a BareColumn operand carried a table qualifier PER THE
	// PARSE TREE (FullId segment count > 1) — never a dot scan of the
	// rendered name, which a delimited identifier containing a literal dot
	// would false-positive. Always false for computed operands; consumers
	// gating on qualification fall back to a conservative canonical-text
	// scan there (a dot inside a computed rendering only ever comes from a
	// real qualified reference or a quoted literal, and the gate is
	// optimization-only).
	Qualified bool
	// Bare/Qualifier are the SEGMENTS behind Operand for a BareColumn — the
	// last segment and the leading one(s). Qualified already said whether a
	// qualifier exists; these say what it IS, which is what a consumer needs to
	// resolve the operand WITHOUT slicing the rendered text apart at its first
	// dot. Empty for computed operands and for producers that have not been
	// taught to carry them; read them only through Ref().
	Bare      string
	Qualifier string
}

type AggregateOutputSlot struct {
	SelectOrdinal int
	NativeOrdinal int
}

type Assignment struct {
	// Column is the SET column's identifier for display, its segments joined
	// by '.' as Java prints an Identifier (`Ambiguous reference X.X.F`). It is
	// never parsed back: a quoted segment holding a dot would split wrong, so
	// every reader of the path reads Segments or the resolved FieldOrdinals.
	// Its readers are the refusals' messages and Explain.
	Column string
	// Segments is the SET column's identifier, one normalized segment per
	// part (a quoted part keeps its case and any '.').
	Segments []string
	Expr     string // canonical text
	Value    values.Value
	// FieldOrdinals and FieldNames are the target field the identifier
	// resolved to, set by the catalog-aware builder and read by everything
	// after it (nil until then): the column's position in the target
	// descriptor, then each struct field's position in the struct before it,
	// and the fields' names (user identifiers) along the way.
	FieldOrdinals []int
	FieldNames    []string
}

type BoundJoinPredicate struct {
	Predicate       predicates.QueryPredicate
	Exists          []ExistsSubquery
	VisibleBindings []values.CorrelationIdentifier
}

type CTEIdentity struct {
	// contains filtered or unexported fields
}

type CTEOption struct {
	// contains filtered or unexported fields
}

type CTEProducer struct {
	// contains filtered or unexported fields
}

type CTERegistry struct {
	// contains filtered or unexported fields
}

type ColumnRef struct {
	Present   bool
	Bare      string // last segment
	Qualifier string // leading segment(s); "" when unqualified
	Qualified bool   // parse-tree segment count > 1
}

type CorrelatedScalarSubquery struct {
	Alias      values.CorrelationIdentifier
	InnerPlan  LogicalOperator
	InnerAlias string
	ScalarCol  string // output column name from the inner aggregate
	// StrictSingle is true when the source can produce multiple post-pagination
	// rows, so SQL standard at-most-one-row semantics apply: a second inner row
	// per outer row is a cardinality violation (21000), not silent truncation.
	// It is false when exact pagination caps a multi-row-capable source to 0/1,
	// or when the source is intrinsically <=1 (for example a non-grouped real
	// aggregate, for which even LIMIT >1 remains safe). Data-dependent LIMIT >1
	// is rejected before this IR until post-pagination scalar collapse exists.
	StrictSingle bool
}

type ExistsConstraint uint8

type ExistsConsumer uint8

type ExistsInput struct {
	// contains filtered or unexported fields
}

type ExistsSubquery struct {
	Alias values.CorrelationIdentifier
	// FlowedType is the exact whole-row type of Plan. It is captured when the
	// subquery is built so every ExistsValue and existential Quantifier use one
	// stable type authority rather than re-deriving a placeholder type.
	FlowedType values.Type
	// Input owns the lowered producer and its scalar edges. Plan retains the
	// bound logical source/placement information; it is not rebuilt to type or
	// translate an attachment that already owns Input.
	Input         *ExistsInput
	Plan          LogicalOperator
	JoinPredicate predicates.QueryPredicate
	// KnownTruth is non-nil when the front-end can prove the EXISTS result from
	// relational cardinality alone. A non-grouped aggregate produces exactly one
	// row before pagination; applying a literal LIMIT/OFFSET therefore makes the
	// result statically TRUE (the row survives) or FALSE (the row is skipped).
	// LIMIT 0 is likewise empty for every supported inner shape. The translator
	// substitutes the constant in positive and negated WHERE consumers instead
	// of building a correlated semi-join. Nil means the result is data-dependent.
	KnownTruth predicates.TriBool
	// Constraint is an admission requirement, independent of dependency and
	// predicate placement. Only the completed owning clause can discharge it.
	Constraint ExistsConstraint
	// contains filtered or unexported fields
}

type GroupKey struct {
	Display   string
	Bare      string // last segment of a bare column ref; "" for expression keys
	Qualifier string // leading segment(s) when qualified; "" otherwise
	Qualified bool   // parse-tree segment count > 1
	// Segs is the FULL ordered segment list of a bare column reference
	// (`r.v.z` -> [R V Z]); nil for expression keys. Qualifier joins the
	// leading segments into one string and so cannot say where one segment
	// ends and the next begins — `R.V` reads as a source alias, which is why
	// a grouping key that descends INTO a struct column could only be
	// resolved once the segments travelled with it. Resolution consumes Segs;
	// Qualifier/Display remain renderings.
	Segs  []string
	Value values.Value
}

type JoinKind int

type LogicalAggregate struct {
	Input     LogicalOperator
	GroupKeys []GroupKey
	// Calls is the SOLE aggregate-call representation. Builders populate it
	// from the parse tree; the translator requires it (RFC-180 F-3 retired
	// the parallel display-text slice).
	Calls                []AggregateCall
	Aliases              []string       // parallel to Calls
	AggregateOperands    []values.Value // resolved operand Values (parallel to Calls); nil slot = use text
	HasDistinctAggregate bool           // true when any aggregate uses DISTINCT (e.g. COUNT(DISTINCT x))
	// HasHaving: the query carried a HAVING clause. Presence SENTINEL only
	// (RFC-180 F-3 — the former canonical-text field was never re-parsed):
	// the translator declines when HasHaving is set but HavingPredicate is
	// nil, so an unstructured HAVING can never be silently dropped.
	HasHaving              bool
	HavingPredicate        predicates.QueryPredicate
	HavingExistsSubqueries []ExistsSubquery // EXISTS subquery plans inside HAVING
	HavingScalarSubqueries []ScalarSubquery // scalar subquery plans inside HAVING
	// OutputSlots is the visible SQL SELECT contract in SELECT-list order.
	// NativeOrdinal addresses the aggregate's physical output row
	// [GroupKeys..., Calls...]; -1 marks a computed post-aggregate item.
	// The aggregate keeps producing its native row until the legal projection
	// boundary above ORDER BY, where this contract is materialized. Public
	// labels live exclusively on that Project and are not producer identity.
	OutputSlots []AggregateOutputSlot
	// CallProvenance maps each Calls entry to the parsed aggregate column that
	// produced it, and CallProvenanceCols records how many such columns the
	// producer walked. HasCallProvenance says whether a producer recorded any —
	// distinct from the slice being nil, which is also what CONSUMED looks like.
	//
	// It exists because the operand-resolution pass used to RECONSTRUCT this
	// correspondence by case-folding the operand's rendered text. That text
	// carries identifiers AND string literals, and a fold cannot tell them
	// apart, so two aggregates differing only in a literal's case matched each
	// other and the second write clobbered the first — a silent wrong answer
	// (RFC-241). The producer already knew the correspondence; this carries it
	// instead of having it guessed.
	//
	// PARSER PROVENANCE, NOT PLAN STRUCTURE. Two obligations follow, and both
	// are load-bearing rather than tidiness:
	//   - the operand-resolution pass NILS both on every exit, so nothing
	//     downstream can read parse-time positions off a logical node;
	//   - neither may reach memo identity, or two structurally identical
	//     GroupByExpressions differing only in provenance would land in
	//     different groups. That holds by construction today: this type never
	//     enters the cascades package, it is translated into
	//     expressions.GroupByExpression first.
	CallProvenance     []AggCallProvenance
	CallProvenanceCols int
	HasCallProvenance  bool
	// OuterCorrelations is Java's outerCorrelations as
	// LogicalOperator.generateGroupBy receives them: the runtime correlations
	// of the enclosing query blocks. They are constant for every row the
	// aggregate consumes, so a post-aggregate value correlated only to them is
	// composable from the aggregate output (SemanticAnalyzer.isComposableFrom's
	// constantCorrelations arm) and pulls up unchanged (Expressions.pullUp's
	// constantAliases). Nil for a block with no enclosing sources.
	OuterCorrelations map[values.CorrelationIdentifier]struct{}
}

type LogicalCTE struct {
	*CTEProducer
	// Alias retains a derived source's SQL qualifier independently of its
	// private CTE registration Name (empty = Name is also the qualifier).
	Alias string
	Main  LogicalOperator
	// PreserveMainSource marks a scope-only envelope: Name registers Body for
	// scans in Main, but the envelope does not replace Main's outward source
	// identity. Derived-table alias carriers leave it false because their
	// binding is the outward source identity.
	PreserveMainSource bool
	// Binding is the derived/CTE leg's binding correlation name when its
	// FROM alias duplicates an earlier leg's ("" = Name binds). See
	// LogicalScan.Binding.
	Binding string
}

type LogicalDDL struct {
	Kind string
	Text string
}

type LogicalDelete struct {
	Target string
	// TargetPath is the target's identifier segments (LogicalInsert.TablePath).
	TargetPath []string
	Input      LogicalOperator
}

type LogicalDistinct struct {
	Input LogicalOperator
}

type LogicalFilter struct {
	// HasQualify preserves the owning block's clause provenance when QUALIFY
	// is combined with WHERE. Correlated EXISTS admission must not infer that
	// provenance from a predicate that may already have folded to a constant.
	HasQualify                 bool
	Input                      LogicalOperator
	Predicate                  predicates.QueryPredicate  // preferred when non-nil
	PredicateText              string                     // source-text fallback
	ExistsSubqueries           []ExistsSubquery           // subquery plans for EXISTS predicates
	ScalarSubqueries           []ScalarSubquery           // uncorrelated scalar plans (pre-evaluated)
	CorrelatedScalarSubqueries []CorrelatedScalarSubquery // correlated scalar plans (per-row LEFT scalar join)
}

type LogicalInlineValues struct {
	Alias   string
	Binding string
	// contains filtered or unexported fields
}

type LogicalInsert struct {
	Table string
	// TablePath preserves the target's normalized identifier segments from
	// the SQL parse, as LogicalScan.TablePath does: a quoted dotted name is
	// one segment, not a template qualifier. Nil denotes legacy programmatic
	// input, resolved from Table by splitting.
	TablePath   []string
	Columns     []string
	Source      LogicalOperator
	ValuesArray values.Value
}

type LogicalJoin struct {
	BoundOn     *BoundJoinPredicate
	Left        LogicalOperator
	Right       LogicalOperator
	Kind        JoinKind
	OnText      string
	OnPredicate any // predicates.QueryPredicate when set
	// OnExistsSubqueries carries EXISTS subqueries lifted from the ON clause
	// (RFC-154 §5) BETWEEN two builder steps only: upgradeJoinOnPredicates
	// parks them here and the block's last step, foldInnerOnExistsIntoWhere,
	// moves them into the block's WHERE filter (an inner join's ON is a WHERE
	// conjunct — Java's QueryVisitor folds it there). A join reaching the
	// translator never carries one; the translator asserts that. Only ever
	// populated for INNER joins (OUTER EXISTS-in-ON is rejected — RFC-154
	// §5.2b).
	OnExistsSubqueries []ExistsSubquery
}

type LogicalLimit struct {
	Input      LogicalOperator
	Limit      int64
	Offset     int64
	LimitValue values.Value
}

type LogicalOperator interface {
	// Children returns the immediate child operators. Returning an
	// empty slice (not nil) for leaf nodes keeps caller code free
	// of nil checks.
	Children() []LogicalOperator

	// Explain returns an indented textual rendering of this node
	// and its subtree. The indent argument is prefixed to this
	// node's first line; children receive indent + "  ".
	//
	// This is the stable surface Plan.Explain() exposes to
	// frontend callers. Cascades physical plans will Explain()
	// through their own impl; logical plans use this.
	Explain(indent string) string
}

type LogicalProject struct {
	Input           LogicalOperator
	Projections     []string
	Aliases         []string       // parallel to Projections; "" means no alias
	ProjectedValues []values.Value // parallel to Projections; nil slot = walker declined
	IsComputed      []bool         // parallel to Projections; true = expression, not plain column ref
	// SQLNames preserves semantic name presence independently of physical
	// aliases: an empty slot is unnamed, even when its emitted field is _N.
	// nil means names derive from the projection's authored references/aliases.
	SQLNames []string
	// AliasMinted is parallel to Aliases: true = the alias in that slot was
	// written by the MACHINERY, not by the user's `AS`. It is the provenance of
	// the name, carried, because the name's SHAPE cannot carry it: the
	// duplicated-bare-leaf dedup pins a projected reference's QUALIFIED
	// spelling ("A.K") as the alias so two same-named datum keys stay
	// distinguishable in the executor's row map, and a user is equally free to
	// write `AS "A.K"`. A consumer that decides between them by inspecting the
	// string gets the user's alias wrong, which is how `SELECT u.name AS
	// "U.NAME"` came to report the label NAME.
	//
	// Java needs no such marker because its internal column for a duplicate is
	// ANONYMOUS (Expressions.java:268-287) while the label is untouched; where
	// it genuinely needs two names for one column it carries a SEPARATE
	// construction-time field (Type.Record.Field.fieldStorageNameOptional,
	// Type.java:2826-2827,2897-2899) rather than recovering provenance from a
	// spelling later. Go's executor keys its row map by name, so the qualified
	// key must stay — deleting it returns ONE column for `SELECT a.k, b.k` —
	// and the provenance rides beside it instead.
	//
	// nil (or a short slice) reads as "user alias" for every slot it does not
	// cover: a machinery mint is the exceptional case and states itself.
	AliasMinted []bool
	// AliasSources is parallel to AliasMinted. A present entry is the
	// STRUCTURED authored source identity captured at the instant the machinery
	// minted that slot's alias. It is not the later physical Value owner: a
	// projection Value can be reanchored onto `_current` while the alias remains
	// the datum key minted from source A. A short/nil vector means the source was
	// not captured; consumers must never reconstruct it from alias text.
	AliasSources []values.ProjectionAliasSource
	// SQLNameAuthored is parallel to Projections: true = the SQL name the slot
	// publishes was written by the statement — an explicit `AS`, or an
	// un-aliased reference to a column whose own name was (an unnest's AS/AT
	// alias, a derived table's or CTE's authored label). Aliases cannot say
	// this: the builder fills an un-aliased reference's slot with the selected
	// attribute's inherited name. A derived table or CTE over this projection
	// publishes an authored slot as semantic.Column.SQLAuthored, which
	// resolution compares exactly. nil (or a short slice) reads as NOT
	// authored — the descriptor-name reading, which keeps the relaxed pass.
	SQLNameAuthored []bool
	// AggregateOutputOrdinals is the exact native [group keys..., aggregate
	// calls...] input slot for each post-aggregate projection item. A negative
	// entry marks a computed item whose Value tree is bound separately. nil
	// means this is not the SQL aggregate-output boundary. Keeping this
	// identity separate from Projections/Aliases prevents a group key and an
	// aggregate alias with the same spelling from being rebound by name.
	AggregateOutputOrdinals []int
	// InputOrdinals is a complete positional projection contract for machinery
	// boundaries that are created before their input quantifier exists (for
	// example a CTE column-list rename). The logical node deliberately leaves
	// the corresponding ProjectedValues nil; cascades translation resolves each
	// slot against the real input quantifier's exact flowed object value. nil
	// means no such positional boundary.
	InputOrdinals []int
	// AggregateSlots is parallel to Projections; true = the slot's value tree
	// CONTAINS an aggregate. Captured pre-rewrite, where the *AggregateValue
	// node is still present (rewriteAggregateValuesInTree destructively replaces
	// it with a typed FieldValue). Read once by the INSERT…SELECT promotion guard
	// to identify reliably-typed aggregate-result columns — plain columns are
	// concrete-typed too (ResolveIdentifier), so type-presence cannot
	// discriminate. A bridge until the Java end-state (PromoteValue projection
	// nodes), which dissolves this marker.
	AggregateSlots             []bool
	ScalarSubqueries           []ScalarSubquery           // uncorrelated scalar subquery plans (pre-evaluated)
	CorrelatedScalarSubqueries []CorrelatedScalarSubquery // correlated scalar subquery plans (re-evaluated per outer row via FlatMap)
	// ProjectionRefs is parallel to Projections and carries the parse-tree
	// SEGMENTS of a plain column item — the same triple SortKey and GroupKey
	// already carry, for the same reason (RFC-197: qualification is FullId
	// SEGMENT COUNT, never a scan of the rendered name).
	//
	// Projections is a RENDERING. `A.B` written as a qualified reference and
	// `"A.B"` written as one quoted identifier are the same bytes, so a consumer
	// that recovers the qualifier by slicing at the first dot cannot tell a
	// reference to source A from a column literally so named — it manufactures a
	// qualifier out of a name and resolves against the wrong row. The segments
	// are what the parser actually saw, so they decide it.
	//
	// A zero entry means "no segments": a computed item, a sentinel slot, or a
	// producer that has not been taught to capture them. Consumers must treat
	// that as "unknown", never as "not qualified" — the ONLY safe reading of an
	// absent segment triple is to fall back to whatever the rendered name
	// supported before.
	ProjectionRefs []ColumnRef
}

type LogicalScan struct {
	Source ScanSource
	Table  string
	Alias  string
	// TablePath preserves normalized identifier segments from the SQL parse
	// boundary. A quoted dotted name is one segment, not a template qualifier.
	// Nil denotes legacy programmatic input; non-nil empty is malformed.
	TablePath []string
	// Binding is the scan's binding correlation name when its FROM alias
	// DUPLICATES an earlier leg's at the same level ("" = the alias binds —
	// every non-duplicate leg). Carried from the
	// parser's single mint authority (assignFromLegBindingIDs); consumers
	// read it via sourceBinding and never re-derive binding identity from
	// the alias. The SQL alias stays the DISPLAY qualifier (sourceAlias).
	Binding string
}

type LogicalSingleton struct{}

type LogicalSort struct {
	Input LogicalOperator
	Keys  []SortKey
}

type LogicalUnion struct {
	Inputs   []LogicalOperator
	Distinct bool
}

type LogicalUnnest struct {
	// Segments is the un-flattened dotted name of the array source
	// (`["T1","ARR1"]` for `T1.arr1`). Segment 0 names the in-scope outer
	// source; the remaining segments name the array field on it. Kept
	// un-flattened (no re-split of a joined string) so the translator
	// resolves segment-by-segment against the scope.
	Segments []string
	// Binding carries the comma source's duplicate-alias binding id
	// (see LogicalScan.Binding) so the
	// TABLE-FIRST demotion (demoteQualifiedTableUnnest) can restore it on
	// the demoted LogicalScan. A genuine unnest consumes the same identity;
	// repeated SQL labels do not replace it or collapse element/ordinal
	// slots (RFC-256).
	Binding string
	// Alias is the AS alias (`x` in `... AS x`) bound to each unnested
	// element. Empty when the AS alias is omitted (AT-only form).
	Alias string
	// AtAlias is the AT ordinal alias (`ord` in `... AT ord`), empty when
	// absent. Its presence makes the Explode WITH ORDINALITY.
	AtAlias string
	// CorrelatedCollection is the already-resolved array Value over the outer
	// correlation. A lateral FROM leg binds it against its preceding FROM
	// prefix; a correlated primary source in EXISTS binds it against its outer
	// scope. Carrying the value preserves the owner, exact type and ordinal
	// path instead of resolving the syntax again during translation.
	CorrelatedCollection values.Value
	// EnclosingOwner records that a lateral FROM leg's collection resolved to a
	// source of an ENCLOSING query, not of this FROM (`EXISTS (SELECT 1 FROM h,
	// w.arr AS v)` over an outer w; Java's resolveCorrelatedIdentifier reads
	// the operators including the outer ones). The binder sets it from the
	// resolution; the translator explodes such a collection as it is, correlated
	// to the outer query, and declines a collection its FROM's left side does
	// not own unless this is set.
	EnclosingOwner bool
}

type LogicalUpdate struct {
	Target string
	// TargetPath is the target's identifier segments (LogicalInsert.TablePath).
	TargetPath []string
	Sets       []Assignment
	Input      LogicalOperator // the scan + filter producing target rows
}

type ScalarSubquery struct {
	Alias values.CorrelationIdentifier
	Plan  LogicalOperator
}

type ScanSource struct {
	// contains filtered or unexported fields
}

type SortDir int

type SortKey struct {
	Expr       string // canonical text
	Dir        SortDir
	NullsFirst bool
	Value      values.Value // resolved Value expression (nil = use text as FieldValue)
	// Pos is a selected output's 1-based position; 0 means no slot selected.
	// ORDER BY <n>, a resolved SELECT alias, and a resolved UNION output name
	// use the same slot-binding mechanism. Authored numeric syntax remains in
	// the parser's orderByClause, independently of this semantic address.
	// The translator bakes a surviving Pos directly to the output slot, without
	// reinterpreting its rendered spelling as another alias or expression.
	Pos int
	// AggregateOutputOrdinal is an exact address into the grouped input's
	// native [keys..., calls...] row. The bool distinguishes native slot zero
	// from an unset field. It is used when the visible aggregate Project is
	// deliberately above ORDER BY.
	AggregateOutputOrdinal    int
	HasAggregateOutputOrdinal bool
	// AggregateOutputValueExact marks Value as a validated structural draft
	// over the aggregate's grouping keys and calls. The translator binds that
	// draft to its real aggregate-row owner; generic sort rebasing must not
	// overwrite it by name.
	AggregateOutputValueExact bool
	// Bare/Qualifier/Qualified: parse-tree segments of a plain column
	// reference key; zero values for positional and expression keys (their
	// Expr is a rendering only). Qualification is FullId SEGMENT COUNT.
	Bare      string
	Qualifier string
	Qualified bool
	// Segs is the FULL ordered segment list of the reference (`a.n.sk` ->
	// [A N SK]). Resolution consumes Segs; Qualifier is a rendering that
	// cannot say where one segment ends and the next begins, so a deeper
	// reference resolved through it looks for a source named "A.N".
	Segs []string
	// BareRef marks a key whose source text is a plain ONE-segment column
	// reference — the only shape SQL binds to an output alias. False for
	// qualified references (`ORDER BY d.x`), aggregates and computed
	// expressions: their canonical renderings ("X" after qualifier
	// stripping, "SUM(S.SCORE)") are indistinguishable from a delimited
	// alias's spelling, so alias-binding passes REQUIRE BareRef instead of
	// inspecting Expr text.
	BareRef bool
}

type TraversalOrder int