feat(ir): derive summary coverage as definition + selection

[zzylol]

Closes #570.

Why

A summary state's schema says what kind of state it is (KLL, k=200, by job), not what it summarizes. #560 (merged) makes SummaryMerge structurally valid, but structure cannot tell a KLL over latency from one over size, nor show that two inputs share no row. This PR derives what each summary state covers from its sub-DAG and uses it to decide whether a merge is valid. The design is in #573 (§4.2), based on Goldstein & Larson's view matching (SIGMOD 2001).

Before this PR (main + #560): coverage was declared by whoever built the node and never checked against the sub-DAG.

A = KLL(latency) over Filter(region = 'us', Scan t)   declared {region: eu}   ← wrong
B = KLL(latency) over Filter(region = 'us', Scan t)   declared {region: us}
SummaryMerge(A, B) → accepted; every US row counted twice

After this PR: nothing is declared. Both states derive selection {region ∈ {us}} over the same definition, so the merge fails with PossibleOverlap.

What

Coverage = definition (what the state computes) + selection (which output rows of that computation it took):

KLL(latency) by[job] over Filter(region = 'us' AND latency < 100, Scan t)
  definition: KLL(latency) by[job] over Scan t
  selection:  [{ region ∈ {us}, latency ∈ (−∞, 100) }]

KLL(value) over TimeRange(1m, range) over TimeShift(2m) over Scan m{job="api"}
  definition: KLL(value) over Scan m
  selection:  [{ job ∈ {api}, relative time (−3m, −2m] }]

• Selection: a predicate conjunct is lifted when it passes Filter, a range TimeRange, a TimeShift without @, and direct-column Project items up to the SummaryAgg (including SummaryAgg.filter and Scan.predicates), and it is a value set (=, !=, IN, NOT IN, OR of equalities) or an interval (<, <=, >, >=) on one column. Columns are identified by (table, name) as the SummaryAgg reads them, so shipping.region and billing.region stay distinct, and a Project renames (region AS r gives r ∈ {us}). A column whose (table, name) is not unique in the agg child (two items aliased k) is not lifted, and value sets compare literals by type, so 1 and 1.0 are never proven different. One range TimeRange(w) over TimeShift(s) gives the relative window (−(s+w), −s]; PromQL ranges are left-open.
• Definition: the SummaryAgg with what was lifted removed. Everything else (arithmetic, regex, rate, instant selectors, …) stays in it as a residual, so states that differ there do not merge.
• Merge: valid only when all inputs have structurally equal definitions (ignoring timing and guarantee, so ingestion-time and query-time panes can merge) and pairwise disjoint selections. Its coverage is the shared definition and the union of the selections; boxes that differ in one dimension join when the union is again one constraint (touching time windows, touching value ranges, value sets of one column), as in the paper's one range per column; gaps stay separate boxes. Merges nest.

Not in this PR (each follows when a caller needs it; see #573 §4.2.2 and §5.6): SummaryMerge { group_by } (rollup), family-specific overlap rules (HLL may overlap; #592), hash-partition constraints, lifting through Aggregate/window/rate partition columns, and SQL timestamp intervals (the IR has no timestamp literal yet).

Key code interfaces

summary_coverage.rs, node.rs

impl OperatorNode {
    /// `Some` for a SummaryAgg and a valid SummaryMerge; derived on first use.
    pub fn coverage(&self) -> Option<&SummaryCoverage>;
}

impl SummaryCoverage {
    /// The single entry point for every summary node.
    pub fn derive(node: &OperatorNode) -> Result<Self, CoverageError>;
}

pub struct SummaryCoverage {
    pub definition: Rc<OperatorNode>,
    pub selection: Vec<SelectionBox>,
}

pub struct SelectionBox {
    pub columns: BTreeMap<ColumnIdentity, Constraint>,
    pub relative_time: Option<(Bound<i64>, Bound<i64>)>,
}

pub enum Constraint {
    In(Vec<ScalarValue>),
    NotIn(Vec<ScalarValue>),
    Interval { lower: Bound<ScalarValue>, upper: Bound<ScalarValue> },
}

pub enum CoverageError { NotSummary, EmptyMerge, DefinitionMismatch, PossibleOverlap }

• OperatorNode::new and validate_structure reject an invalid SummaryMerge; the derived coverage is cached on the node, so it is not derived again.
• The node's coverage field is now a private cache: ignored by equality, skipped by serde, emptied on clone.
• Removed: with_coverage, requires_coverage, CoverageError::Missing, and the coverage fields of CSE keys and FlatNode.

Tests

crates/types/tests/summary_coverage.rs covers each rule: filters and scan predicates lifting, population and value-range merges, overlap rejection, different inputs and different scan schemas, qualified columns, time panes (join, gap, overlap), touching value ranges joining, residuals, instant selectors, nested merges, timing, a forged merge caught by validate_structure, and three regressions from an independent review (ambiguous column names, literals of different types, partly lifted scan predicates), each confirmed failing before the fix. design_doc_worked_example reproduces the SQL worked example of #573 §4.2.2 (renaming Project, Scan.predicates, residual on an expression, SummaryAgg.filter). Tests that start from SQL/PromQL query strings follow in #542, the first PR where the planner lowers a query into a SummaryAgg. Workspace tests, cargo fmt and workspace/all-targets Clippy with warnings denied pass.

---

Base: main · Next: #539 · Tracker: #528 · Design: #573

🤖 Generated with Claude Code