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

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 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        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)
	FilterOnlyColumns []string                   // columns needed ONLY by the filter directly above this scan (candidates for scan-level filter evaluation without materialization)
	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
}

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

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 // for aggregate window functions
	OutputCol   string
	PartitionBy []string
	OrderBy     []OrderExpr
	Frame       *WindowFrameSpec
}

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