logical

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
	// 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 string
	Expr   string // canonical text
	Value  values.Value
}

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 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
	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
	// OuterOnlyJoinConjuncts marks a JoinPredicate carrying conjuncts with
	// NO inner-source reference that can FILTER (a nested-EXISTS middle
	// routes them here; the inside placement does not plan for that
	// composition; statically-TRUE tautologies are excluded - routing TRUE
	// is a no-op). The outer-routing validity matrix, enforced by
	// declineNegatedOuterOnlyEsq (predicate side) and
	// declineNegatedOuterOnlyEsqValue (value side) in the translator:
	//
	//	WHERE/ON + positive  -> VALID   (P AND EXISTS(Q) == EXISTS(P AND Q))
	//	WHERE/ON + negative  -> DECLINE (would compute P AND NOT-EXISTS(Q))
	//	projected + either   -> DECLINE (outer-routing filters the row
	//	                        stream; a projected boolean must not)
	//
	// HAVING is kept out of the surface by translateAggregate's blanket
	// rejection of HavingExistsSubqueries.
	OuterOnlyJoinConjuncts bool
}

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
}

type LogicalCTE struct {
	Name           string
	Body           LogicalOperator
	Main           LogicalOperator
	Recursive      bool
	ColumnAliases  []string // WITH c(a, b) AS (...) → renames body's output columns
	TraversalOrder TraversalOrder
	// PreserveMainSource marks a scope-only envelope: Name registers Body for
	// scans in Main, but the envelope does not replace Main's outward source
	// identity. Correlated EXISTS/Scalar plans use this when they copy enclosing
	// CTE definitions into a self-contained subplan. Derived-table alias carriers
	// leave it false because their CTE name deliberately IS the outward alias.
	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
	Input  LogicalOperator
}

type LogicalDistinct struct {
	Input LogicalOperator
}

type LogicalFilter struct {
	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
	Columns     []string
	Source      LogicalOperator
	ValuesArray values.Value
}

type LogicalJoin struct {
	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). The cascades translator turns each into an existential
	// quantifier on the join's SelectExpression, so the NLJ rule's
	// the existential peel path builds the semi-join. Only populated for
	// INNER joins (OUTER EXISTS-in-ON is deferred — 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
	// 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
	// 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 {
	Table string
	Alias 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 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 (demoteSchemaQualifiedUnnest) can restore it on
	// the demoted LogicalScan — a mis-classified schema-qualified TABLE leg
	// is a table leg for binding purposes. A GENUINE unnest never consumes
	// it: a duplicate unnest AS/AT alias is rejected outright (RFC-142).
	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 set only when this unnest is the primary source
	// of a correlated subquery (`EXISTS (SELECT ... FROM R.TAGS AS E)`). It is
	// the already-resolved array FieldValue over the outer correlation. A
	// regular lateral FROM leg gets that value from the LogicalJoin on its left
	// and leaves this nil. Carrying the resolved Value preserves minted outer
	// correlations and avoids resolving the owner a second time.
	CorrelatedCollection values.Value
}

type LogicalUpdate struct {
	Target string
	Sets   []Assignment
	Input  LogicalOperator // the scan + filter producing target rows
}

type LogicalValues struct {
	Rows    []string
	Aliases []string
}

type ScalarSubquery struct {
	Alias values.CorrelationIdentifier
	Plan  LogicalOperator
}

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 the 1-based SELECT-list position for a positional key
	// (`ORDER BY <n>`); 0 = not positional. A positional key IS an output
	// ordinal by SQL definition, so the translator bakes it directly to the
	// projection's output slot — no text-rendering round-trip, which
	// diverges for computed items whose canonical source text differs from the
	// baked output spelling.
	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 already structurally bound to
	// the native aggregate row (including a computed tree whose leaves are
	// native ordinals). 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