logical

type AggExpr struct {
	Func      string // sum, count, min, max, avg
	InputCol  string
	OutputCol string
	Distinct  bool         // COUNT(DISTINCT col)
	InputExpr plansql.Node // AST for aggregate argument (nil for simple column refs)
	// InputCol2, Separator and Percentile hold the arguments after the
	// first, for the functions that take more than one: the second column
	// of CORR/COVAR_SAMP/COVAR_POP and the ordering column of
	// MIN_BY/MAX_BY, STRING_AGG's separator literal, and
	// PERCENTILE_CONT/PERCENTILE_DISC's fraction. See parseAggExtraArgs.
	//
	// InputCol stays a single column name throughout: column pruning and
	// requiredColumns read it as one, and InputCol2 is registered beside
	// it rather than packed into the same string.
	InputCol2  string
	Separator  string
	Percentile float64
}

type ColumnPolicy struct {
	Column   string
	Denied   bool   // true = column excluded from results
	MaskExpr string // non-empty = column replaced with this value (e.g., "'***'", "0")
}

type DecimalMeta struct {
	Precision int
	Scale     int
}

type DecorrelatedKey struct {
	Outer string
	Op    string
	Inner InnerKeyRef
}

type GroupingCall struct {
	Args      []string
	OutputCol string
}

type HistogramStats interface {
	SelectivityLE(v any) float64
	SelectivityLT(v any) float64
	SelectivityRange(lo, hi any) float64
	SelectivityEQ(v any) float64
}

type InnerKeyRef struct {
	Qualifier string // relation alias, or table name when unaliased; "" = unqualified
	Column    string // source column, unqualified
	Text      string // the spelling the rewrite wrote, and the repair's fallback
}

type MergeInfo struct {
	GroupBy  []string
	AggExprs []AggExpr
	OrderBy  []OrderExpr
	// Limit is the top-level LIMIT value; meaningful only when HasLimit is
	// true. HasLimit is false both when the statement has no LIMIT at all
	// and when it has only an OFFSET (NoLimit) — a companion bool rather
	// than folding NoLimit into Limit itself, because the many test
	// literals that construct a MergeInfo{} directly (never touching
	// Limit) must keep meaning "unbounded" by leaving both fields at their
	// zero value. Before HasLimit existed, `Limit > 0` doubled as that
	// same test, so a probe-split merge for `... LIMIT 0` silently kept
	// every row instead of zero (#481) — test HasLimit, never `Limit > 0`.
	Limit    int
	HasLimit bool
	// Offset is the top-level OFFSET. Rows to keep are [Offset, Offset+Limit)
	// — a merge that truncates to Limit before skipping Offset returns the
	// first page for every page (#337).
	Offset       int
	HasAggregate bool
	HasDistinct  bool // DISTINCT requires deduplication across partials
}

type Node struct {
	Type     NodeType
	Children []*Node

	// Scan
	TableName  string
	TableAlias string
	// DerivedAliases are the DERIVED TABLE aliases whose scope this scan sits
	// inside, outermost last — `x` for the supplier scan in `(SELECT
	// s_suppkey AS k FROM supplier s1) x`. They are recorded ALONGSIDE
	// TableAlias rather than in it because the two answer different
	// questions: TableAlias is which relation the scan IS, and the derived
	// alias is which derived table's scope it is IN.
	//
	// Collapsing them cost a wrong answer. setSubtreeAlias used to overwrite
	// TableAlias, so `(SELECT n1.n_name AS a, n2.n_name AS b FROM nation n1
	// JOIN nation n2 ON …) u` planned as two scans BOTH aliased `u`, the join
	// could no longer tell its two sides apart by name, and `a` and `b` came
	// back as the same column — 25 groups where PostgreSQL 17 answers 5
	// (#489). The scope question still has to be answerable, because that is
	// what lets `u.a` drop its qualifier inside this subtree and nowhere else
	// (physical.derivedScopeBareName), so it is recorded rather than dropped.
	DerivedAliases  []string
	ScanColumns     []string                   // column names available from this scan (populated by physical planner)
	RequiredColumns []string                   // columns actually needed from this scan (set by optimizer column pruning)
	PartitionFilter map[string]string          // extracted partition key filters (year, month, day, hour)
	ScanPredicates  []Predicate                // pushed-down filter predicates for row group pruning
	ScanRowEstimate int64                      // estimated row count from manifest (0 = unknown)
	ScanColStats    map[string]ScanColumnStats // aggregated column stats from catalog (nil = unavailable)
	// ScanColTypes maps this scan's lower-cased column names to their
	// catalog types (populated by physical.AnnotateScanColumns alongside
	// ScanColumns). It is what lets the planner declare a MIN/MAX output
	// type, which follows the input column rather than the function.
	ScanColTypes map[string]parquet.TypeID
	// ScanColDecimal maps this scan's lower-cased column names to their
	// DECIMAL precision/scale — entries exist only for TypeDecimal columns.
	// Populated by physical.AnnotateScanColumns alongside ScanColTypes. It is
	// what lets a zero-row DECIMAL result declare the same PostgreSQL typmod
	// a non-empty one does: ScanColTypes alone carries the bare TypeID, which
	// left every declared-schema DECIMAL column at Precision=0 (typmod -1,
	// "unconstrained") even when the underlying column had a real (p,s)
	// (#458).
	ScanColDecimal map[string]DecimalMeta
	// ScanColFields maps this scan's lower-cased ROW column names to their
	// declared FIELDS. It is what types a field PATH (`rw.c`): `c` is not a
	// column of anything, so ScanColTypes cannot carry it and every lookup
	// keyed by column name misses. Without it a field path is declared
	// STRING — `SELECT rw.n` over an INT64 field returned string("9"),
	// `ORDER BY rw.c` sorted a CIDR field by its stored text, and the wire
	// reported OID 25 for both (#568). Populated by
	// physical.AnnotateScanColumns alongside ScanColTypes.
	ScanColFields     map[string][]parquet.Column
	FilterOnlyColumns []string // columns needed ONLY by the filter directly above this scan (candidates for scan-level filter evaluation without materialization)
	ShapeOnlyColumns  []string // byte-array columns whose EVERY use in the plan reads shape, not contents (LENGTH/IS NULL/= ”/COUNT) — the scan decodes them as lengths, see shape_only_columns.go
	SampleMethod      string   // TABLESAMPLE method: BERNOULLI, SYSTEM
	SamplePercent     float64  // percentage for TABLESAMPLE (0-100)

	// Table Function (e.g., read_json, read_csv, unnest)
	IsTableFunc    bool              // true if this scan reads from a table function
	FuncName       string            // function name (e.g., "read_json")
	FuncArgs       []string          // positional arguments (e.g., URL/path)
	FuncNamedArgs  map[string]string // named arguments (e.g., delimiter="|")
	WithOrdinality bool              // UNNEST(...) WITH ORDINALITY
	FuncColAliases []string          // AS alias(col1, col2, ...)

	// Filter
	Predicates []Predicate
	// PolicyFilter marks a Filter injected by row-level security
	// (InjectRowFilter) rather than written by the client. It is the
	// counterpart of SecurityBarrier below: together they are how a caller
	// asks "does this plan carry enforcement I must not throw away"
	// (PlanCarriesPolicyEnforcement).
	PolicyFilter bool

	// Project
	Projections []Projection
	// SecurityBarrier marks a projection injected by ABAC column-policy
	// enforcement (InjectColumnPolicies): masked columns replaced with
	// literal expressions, denied columns absent. The physical planner
	// must APPLY it at the scan (distributed walkStages treats ordinary
	// Projects as passthrough — a dropped barrier would leak raw values).
	SecurityBarrier bool

	// Aggregate
	// PreservesAggOutputs marks a synthetic Project inserted by a rewrite
	// directly above an Aggregate that passes every aggregate output
	// through under its original name (possibly adding finalizations,
	// e.g. the two-level AVG division). The physical builder's
	// aggregate-ancestor resolution walks through such projections so
	// SELECT-list aggregate references still resolve by output name.
	PreservesAggOutputs bool
	// ScanStrictIntCols marks scan columns whose vectors are plain
	// Int64/Int32 at runtime — exactly the set expr.BinOpNumeric resolves
	// to integer arithmetic. Planner-side int typing must stay a subset
	// of the runtime rule (a declared-int column over a float-mode expr
	// would read as NULL through the typed getter), so this is
	// deliberately narrower than ScanIntCols' int-class set.
	ScanStrictIntCols map[string]bool
	// ScanIntCols marks scan columns whose types land on the typed
	// integer aggregation paths (set by physical.AnnotateScanColumns;
	// consumed by the two-level distinct rewrite's cost gate).
	ScanIntCols map[string]bool

	GroupBy      []string
	GroupByExprs []plansql.Node // AST for GROUP BY expressions (may be nil)
	// InnerGroupRefs parallels GroupBy on an Aggregate the IN decorrelation
	// built inside a subquery's plan: what each group term MEANS, for
	// repairDecorrelatedSpelling to spell once the inner join order is
	// final. An aggregate's output column IS its group key's text, so a key
	// named from write order moves the #526 mismatch one node up rather
	// than removing it. Nil elsewhere, and nil again after the repair.
	InnerGroupRefs   []InnerKeyRef
	AggExprs         []AggExpr
	GroupingSetNulls []string   // columns that should be NULL in this grouping set (legacy, per-node)
	GroupingSets     [][]string // single-pass grouping sets: each entry lists the columns in that set
	// GroupingCalls is one entry per distinct GROUPING(...) call at this
	// query level — SELECT list, HAVING, or nested inside either — in the
	// order the slots were allocated.
	//
	// Set whenever the query has a GROUP BY, sets or not: a plain GROUP BY
	// answers 0 for every call (every key is grouped in every row) but takes
	// the SAME hidden slot rather than a constant fold of its own, so a call
	// nested in a larger expression has one substitution to make on either
	// shape. See builder.go's allocGroupingSlot (#804).
	GroupingCalls []GroupingCall

	// Sort
	OrderBy []OrderExpr

	// Limit
	LimitVal  int
	OffsetVal int

	// Join
	JoinType      string // inner, left, right, full, cross, semi, anti
	JoinCond      string
	JoinFilter    string // non-equality join conditions for semi/anti join
	LeftKeys      []string
	RightKeys     []string
	NeededColumns []string // columns the parent needs from this join's output (set by optimizer)

	// InnerKeys and InnerFilterKeys record what a semi/anti join produced by
	// the IN / EXISTS decorrelations MEANS by its build-side references —
	// the relation qualifier and source column the subquery wrote — for
	// repairDecorrelatedSpelling to turn back into JoinCond / JoinFilter
	// text once reorderJoins has settled which relation's columns the inner
	// join emits bare. Nil on every other join, and nil again after the
	// repair has run. See inner_key_spelling.go (#526, #527).
	InnerKeys       []DecorrelatedKey
	InnerFilterKeys []DecorrelatedKey

	// NullAwareAnti marks an anti join the NOT IN rewrite produced, which
	// must answer NOT IN's three-valued rule rather than the two-valued
	// question an anti join asks on its own: a NULL probe key, or a NULL
	// anywhere in the subquery's result, is UNKNOWN and not TRUE (#507).
	// Set only for an UNCORRELATED NOT IN — with a correlation the "the list
	// held a NULL" fact is per correlation group, which a single flag on the
	// operator cannot express, so that shape is left alone. NOT EXISTS is a
	// different predicate with its own (already correct) semantics and never
	// carries this. Consumed by exec.HashJoin.NullAwareAnti.
	NullAwareAnti bool

	// Window
	WindowExprs []WindowExpr

	// Union
	UnionAll bool // true = UNION ALL, false = UNION (dedup)

	// CTEs — stored on the root node so the physical planner can resolve
	// CTE references inside scalar subqueries (e.g., Q15's HAVING/WHERE
	// subquery that references a CTE defined in the outer WITH clause).
	CTEs []plansql.CTEDef

	// CTEName — set on the root of a CTE sub-plan so the physical planner
	// can detect and materialize multi-referenced CTEs. It is also the
	// SCOPE NAME the enclosing query qualifies this subtree's output columns
	// by — the CTE's answer to a derived table's alias, which
	// physical.subtreeNamesRelation reads so `c.gk` resolves to the SELECT
	// item `gk` names (#653).
	CTEName string

	// CTERefAlias is the name ONE reference gives that scope — `x` in
	// `FROM c AS x`, which PostgreSQL makes the only spelling the enclosing
	// query may use. It sits beside CTEName rather than replacing it because
	// the CTE cache is keyed on the definition's name and every reference
	// shares it.
	CTERefAlias string

	// DerivedAlias is a DERIVED table's own name, on the root of its
	// sub-plan: `q` in `FROM (SELECT …) q`. It is the derived spelling of
	// CTEName, and it is recorded on the SUBTREE ROOT for the same reason —
	// setSubtreeAlias stamps the alias onto the SCANS below, so a subtree
	// with more than one scan (an arm that is itself a JOIN) and a subtree
	// with a derived table INSIDE it (which stamps its own alias first, and
	// setSubtreeAlias then declines to overwrite) both leave the scans
	// answering to a name the enclosing query never wrote. `joinArmAlias`
	// reads it so a join qualifies an arm's duplicate columns by the name
	// the QUERY calls that arm (#751, #773).
	DerivedAlias string

	// ScalarDecorrelated marks a LEFT join produced by
	// decorrelateScalarSubqueries (children[1] is the grouped aggregate
	// materializing the subquery result). reduceDecorrelatedScalarAggs
	// uses it after predicate pushdown to semijoin-reduce the aggregate's
	// input by the outer plan's key-source branch.
	ScalarDecorrelated bool

	// BuildSideDedup marks a Distinct the PLANNER inserted, not one the
	// user wrote. Two passes create them: dedupSemiAntiBuildSide bounds a
	// semi/anti join's build hashtable by NDV, and scalar_agg_semijoin
	// builds a decorrelated semijoin's key source. Neither carries
	// user-visible semantics — a semi/anti join's result does not depend
	// on whether its build side has duplicates — and the physical planner
	// has dedicated handling for the shape (estimateDistinctKeyBytes sizes
	// Distinct(Project) subtrees by key count; the distinct-pair semi/anti
	// build fast path matches on it).
	//
	// rewriteDistinctAsGroupBy therefore leaves a marked Distinct alone and
	// rewrites every UNMARKED one — those are user SELECT DISTINCTs, and
	// each is an answer the engine has to actually compute (#466).
	BuildSideDedup bool
}

type NodeType int

type OrderExpr struct {
	Column     string
	Desc       bool
	NullsFirst *bool // nil = default, true = NULLS FIRST, false = NULLS LAST
	// Position is a select-list ordinal the parser could not count, because
	// the list carries a `*` at or before it and a star's width is a catalog
	// question (#810). Non-zero means Column is not yet a name;
	// ResolveOrdinalSortKeys fills it in after ExpandStarProjections and
	// clears this. A key that reaches the physical planner still carrying one
	// is refused loudly rather than sorted on the constant, which would be a
	// silent no-op.
	Position int
	// SlotPos is the 1-based select-list POSITION this key was written as,
	// kept even after Column has been resolved to a name. Unlike Position it
	// is not a "not yet resolved" marker: it is the ADDRESS, for the case
	// where the name is not one because two output columns share it (#557).
	SlotPos int
}

type PolicyLookup func(table string) (cols []ColumnPolicy, rowFilter string, err error)

type PreComputedAggregate struct {
	InputTable     string
	GroupByCols    []string
	AggOutputCols  []string // OutputCol names from each AggSpec, in order
	SyntheticAlias string   // unique scan alias to substitute
}

type Predicate struct {
	Column string
	Op     string // =, !=, <, <=, >, >=, is_null, is_not_null, in, between
	Value  any
	// ValueText is a numeric Value's exact source text. Value is boxed for
	// arithmetic and a float64 cannot hold a DECIMAL past ~15-16 significant
	// digits, so the text is what the scan's prune and the row-at-a-time
	// filter convert at the column's own scale (#452). Empty when Value did
	// not come from a numeric literal.
	ValueText string
	Raw       string       // raw SQL expression
	ASTExpr   plansql.Node // compiled AST expression node
	// PruneOnly marks predicates attached solely for storage-level pruning
	// (row-group stats / dictionary probes). The cardinality estimator
	// ignores them: attaching AST-decomposed conjuncts must not shift
	// distributed plan choices (Q08's orders join flipped shuffle →
	// broadcast off a 0.33^n selectivity guess the moment they appeared).
	// Estimate-visible attachment is a separate, SF100-validated change.
	PruneOnly bool
	// FromPolicy marks a predicate the POLICY itself put there — a column
	// policy's row filter, which reads the row AS STORED by design (ADR-0033
	// decision 6). It is the one predicate allowed to sit on a policed scan
	// below the security projection, and CheckPolicyPlanOrder refuses every
	// other one: a scan predicate feeds row-group PRUNING against the stored
	// column's statistics, so a user predicate that reaches the scan answers
	// "is there a row whose STORED value satisfies this" however the plan
	// above it is ordered.
	FromPolicy bool
}

type Projection struct {
	Column  string // column reference
	Alias   string // output name
	Expr    string // raw expression
	IsAgg   bool
	ASTExpr plansql.Node // compiled AST expression node (nil for aggregates)
	// SlotSource names the planner's HIDDEN SLOT this projection reads, and
	// is empty for every projection that reads a real column. It exists
	// because the two are otherwise indistinguishable: a query over a table
	// that already stores a `__win_0` column has a projection reading THAT and
	// a projection reading the window's slot of the same name, and the pass
	// that renumbers the slot past the stored column (physical.
	// renameCollidingSlots) must move exactly one of them.
	SlotSource string
	// PublishedName is the name the CLIENT is told this column has, where
	// that differs from Alias — PostgreSQL's `FigureColname`
	// (plansql.OutputColumnName, #732). `SELECT g + 1` publishes `?column?`,
	// `SELECT COUNT(*)` publishes `count`, `SELECT CAST(g AS bigint)`
	// publishes `g`.
	//
	// It is a SECOND name and not a rewrite of Alias, for the reason ADR-0026
	// §2 gives group keys a pair: an aggregate's `OutputCol` IS its Alias and
	// every consumer inside the planner — GROUP BY, HAVING, ORDER BY, the
	// stage's rename source — resolves against it, while two unaliased
	// aggregates legally publish ONE name (`SELECT COUNT(*), COUNT(g)` is two
	// columns called `count`). Collapsing the two would make the resolution
	// spelling ambiguous to fix a name.
	//
	// Empty means "the same as Alias", which is every projection the planner
	// itself mints. Only the OUTPUT projection's copy is consumed: it names
	// what leaves the engine, and a nested block's names are what the block
	// above resolves against.
	PublishedName string
	// Hidden marks a projection the planner added for its own use rather
	// than one the user selected: the materialized value of an ORDER BY term
	// the SELECT list does not carry (#320). It computes and sorts like any
	// other projection, and is dropped before the rows reach the client —
	// extractOutputRenames leaves it out of the DAG's output schema, and
	// hiddenSortTrimOp drops it on the single-process pipeline.
	Hidden bool
}

type RelStats struct {
	Rows   float64
	ColNDV map[string]float64 // lowercase unqualified column name → estimated NDV
	// ColHist carries opaque histogram pointers (*catalog.Histogram) for
	// columns that have one in the catalog. Used by estimatePredSelectivity
	// to compute range/equality selectivity from real data distributions.
	// Stored as any to keep the logical package free of catalog imports.
	ColHist map[string]any
}

type ScanColumnStats struct {
	MinValue  any
	MaxValue  any
	NullCount int64
	TotalRows int64
	// NDV is the catalog's merged HyperLogLog estimate of distinct values
	// across all files of this column. Zero means HLL wasn't collected
	// (legacy files / pre-ANALYZE state); planner falls back to the
	// min/max-range heuristic. When >0 it's preferred — orders of
	// magnitude more accurate for sparse-int / string columns where the
	// range overstates true cardinality.
	NDV int64
	// Histogram is the catalog's equi-depth histogram for this column,
	// merged across files from reservoir samples. Nil when not collected.
	// Used by estimatePredSelectivity to compute range/equality
	// selectivity from real value distributions instead of hardcoded
	// fractions (0.33 for <, 0.1 for =). The opaque any allows the
	// logical package to receive *catalog.Histogram without importing
	// the catalog package (avoids circular import).
	Histogram any
}

type TablePolicies map[string][]ColumnPolicy

type WindowBound struct {
	Type   string // "unbounded_preceding", "preceding", "current_row", "following", "unbounded_following"
	Offset int
}

type WindowExpr struct {
	Func        string // row_number, rank, dense_rank, sum, count, avg, min, max
	InputCol    string // the argument list, verbatim — see InputColumn
	OutputCol   string
	PartitionBy []string
	OrderBy     []OrderExpr
	Frame       *WindowFrameSpec
}

type WindowFrameSpec struct {
	Mode  string // "rows" or "range"
	Start WindowBound
	End   WindowBound
}