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 HistogramStats interface {
	SelectivityLE(v any) float64
	SelectivityLT(v any) float64
	SelectivityRange(lo, hi any) float64
	SelectivityEQ(v any) float64
}

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
	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
	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

	// 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)
	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

	// 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)

	// 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.
	CTEName 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
}

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
}

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)
	// 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 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
}