[Refactor] Repo-wide naming survey: overloaded and misleading names #948

Example

PhysicalCandidate (plan-selection/src/search/candidates/graph.rs:18) is one operator node in the dependency graph. Before configuration it is neither physical nor a whole candidate. CandidateEvaluation, in the same module, evaluates a whole MILP assignment. PhysicalWorkloadPlan (physical-asap-optimization/src/lib.rs:133) documents itself as "One CandidatePhysicalASAPDAG". A reader meets the word "candidate" with six meanings, and the word "physical" with five, before reaching the selection code.

Similarly, PhysicalCandidate.local_cost is documented as "Local work and state only". In practice it is overwritten with lower bounds (costing/lower_bounds.rs:237), refinement weights (refinement/objectives.rs:132, refinement/search.rs:222) and zero placeholders. It is the MILP objective coefficient, not a cost.

Concrete maintenance problem

A repo-wide naming survey found that many central names don't say what the code does. They are overloaded across crates, have several synonyms, or survive from the old whole-workload planner after #933/#934. The findings are listed below. Paths are relative to crates/ unless noted.

1. Overloaded terms (highest impact)

2. Several names for one concept

• Summary state in memory: AggregateCore (trait), accumulator (*Accumulator, take_accumulator), kernel (summary_kernels), StateColumn, ScalarState (meaning "unkeyed"). There are also two builder types: AccumulatorUpdater and StateColumnUpdater.
• Reading a value out of a summary: SketchStatistic, SummaryEstimate.query, EvaluatePopulation.evaluation, "readout", StatisticKind, and executor Statistic. In the executor, Kind::KeyedEvaluation (really top-k) is displayed as "SummaryEstimate", while Kind::Evaluation, which implements IR SummaryEstimate, is displayed as "SummaryEvaluation".
• Which aggregate: AggIntent (types), AggSemantic (sql-function-catalog), Outer/InnerFunc (promql), executor Statistic/Reduction.
• Producer / consumer: also called supplier / reader. SupplierCandidates is stored in a field of type CompatibleProducers. Counts: producer 528, supplier 182, reader 670, consumer 222.
• Off-query-path computation: ingestion / precompute / maintenance. Scope::Ingestion { window_start_ms, window_end_ms } is really one pane.
• A series' label set: labels, $population, $promql_series_identity.
• The joint search: "memo" (dag-viewer DOM/JSON), --search candidate-connections (CLI), SearchAlgorithm::CandidateConnections (Rust), "Joint search" (UI), MILP. The viewer still maps the stale memo-milp / memo-brute-force names.
• The candidate set: catalog / inventory / archive. "Inventory" also names two different types: CandidateInventory (the lowered dependency graph) and CandidateSearchContext.inventory: &PerComputationCandidates (the Pass 1 targets).
• Query outputs: query root / output reference / output group / boundary (BoundaryConsumer).
• Identical-subexpression sharing: share_common_sub_dags, memo hash-consing, "identical-expression rule".
• Shared summary builds: summary-capability rule / CapabilitySharingCandidate / CandidateOrigin::SharedBuild / shared_builds. Windows have the same problem: window-composition rule / CandidateOrigin::Panes / PaneCandidate / window_candidates.rs / SharedPaneChain.
• The materialization cut: frontier / materialized_outputs / precompute "boundary" / InputContract.
• The materialization choice for one candidate: PhysicalWorkloadPlan.materialization (node → option map), .assignment (Vec<Materialization>), and MaterializationAssignment (a third, pointer-keyed form). The field named assignment is not of type MaterializationAssignment. MaterializationCandidate and is_materialization_point name the same concept.
• Recurrence: Repeated / Repeating / RepeatedDemand / RepetitionInterval / QueryRecurrence. The unit of execution is likewise called invocation / request / run / evaluation.

3. Names whose meaning no longer matches the code (legacy of #933/#934)

4. Other misleading names

types / planner / physical-asap-optimization / frontend-common

• types/src/ir/physical_export.rs:98 PhysicalASAPDAG / module physical_export: post-asap-ir.md says this DAG is logical. Suggested: TimedASAPDAG.
• types/src/ir/schema/sketch.rs SketchStatistic: covers every summary family, not only sketches. SummaryEstimate.query collides with workload Query (its doc has to warn about this). Suggested: SummaryStatistic, with one field name statistic.
• types/src/workload/parsed_workload.rs:32 ParsedWorkload.exprs: holds lowered and canonicalized IR roots. Suggested: LoweredWorkload.roots.
• physical-asap-optimization/src/lib.rs:353 MaterializationCandidate: a materialization point. Suggested: MaterializationPoint.
• summary_coverage.rs:162 Constraint: per-column value set. It is re-exported by the planner and collides with MILP constraints. Suggested: ColumnConstraint.
• non_asap.rs:43,159 NonASAPOp::TimeRange + TimeRangeKind::Instant: an instant selector modeled as a range. Suggested: SelectorWindow.
• planner/src/lib.rs:97 UserInput / frontend_specific: Suggested PlanRequest / frontend.
• frontend-common/src/schema_resolver.rs:39 SchemaResolver: derives a leaf schema from usage and binds nothing, while resolve.rs uses "resolve" for binding.
• IngestionPruneReason: also used as an eligibility result. Suggested: IngestionIneligibility.
• GuaranteeSource: a provenance step. AccuracySpec: vague.
• StatisticKind::Distinct vs SketchStatistic::Cardinality.

logical-asap-optimization / plan-selection

• ComputationCandidate: a realization method. Suggested: RealizationMethod; also rename summary_candidates() to summary_families_for_intent.
• SupplierCandidates, SupplierSetInterner: Suggested CompatibleProducers.
• CandidateMemo: documented as "the hash-consed workload". Suggested: GroupImplementations.
• NodeCost.multiplier, CandidateDemand.multiplier: Suggested computations_per_execution.
• EdgeStatistics describes a node's output. Suggested: OutputStatistics. PropagationStats should be PropagationEvidence.

executor (paths relative to executor/src/)

• operators/mod.rs:126 Kind::Window (displayed as "WindowAggregate"): also runs HistogramQuantile with window: None, and coordinate is sometimes the le bound.
• operators/mod.rs:69-111, VectorBinary/RangeWindow/HistogramQuantile vs SeriesBinary/SeriesWindow/SeriesHistogramQuantile: the real difference is label-map rows vs flattened series rows. SeriesLabels does label matching.
• statistic.rs:4 Statistic: exact-family readout. Only 6 of its variants are reachable. Suggested: ExactStatistic.
• physical_planner/candidates.rs:9 CompiledPhysicalPlan: a precompute/query split of a CompiledPhysicalDAG. Suggested: PrecomputeQuerySplit.
• summary_kernels/exact.rs:14 ScalarState (.scalar / .keyed): also used as the per-key value. Suggested: ExactRecord with unkeyed / by_key.
• key_by_label_values.rs:6 KeyByLabelValues.labels: holds values and is used for SQL item keys too. Suggested: ItemKey { values }.
• summary_kernels/increase.rs:7 IncreaseAccumulator: also backs Rate. Suggested: CounterAccumulator. Measurement is a bare f64 newtype.
• module query_time: unused CMS error-bound math. Suggested: sketch_error_estimation.
• samples.rs:214 TableRowSelector: called a "raw-data-sample window" although it handles SQL rows. Kind::Join is displayed as "RelationalJoin".

frontends / sql-function-catalog / devtools / dag-viewer

• frontend-promql/src/lib.rs:32,82 and frontend-metricsql/src/lib.rs:80,94: lower_promql_workload vs lower_promql_query_workload (and lower_metricsql vs lower_metricsql_query) differ only in whether scalar roots are allowed.
• frontend-promql/src/promql.rs:98-171 Outer / OuterIntent / Inner / InnerFunc: named by position, not meaning. Suggested: CrossSeriesAgg / SeriesSelection / RangeFunction. Its comments also mention an "Unresolved Window" node that no longer exists.
• sql-function-catalog/src/lib.rs:262,277 ClickHouseBuiltin / CLICKHOUSE_BUILTINS: the aggregate table, which includes asap_rate / asap_increase.
• frontend-sql/src/sql/mod.rs:1243 PlanningBridge: holds relation markers, but the module docs use "bridge" for asap_rate too.
• frontend-metricsql/src/lib.rs:40 canonical_metricsql: returns normalized query text.
• Import aliases: UnresolvedOp as Unresolved (promql/sql) vs as U (metricsql); UnresolvedScalar as Scalar; both frontend error types are imported as LoweringError. The lowerers are inconsistent: PromqlLowerer (a unit struct), SqlLowerer, and a bare Lowerer.
• devtools/src/planner_fuzz/mod.rs:371 Planner: collides with the product name. Suggested: FuzzPlanCache.
• devtools/src/planner_fuzz/relations.rs:201 Witness: already stored as derivation. Suggested: Derivation.
• devtools/src/planner_fuzz/mod.rs:352 Priced.derived_root: PrivateNodes: a node set, not a root.
• devtools/src/rqe_atomic_costs.rs: "RQE" is undefined. Suggested: sketch_bench_operation_costs.
• devtools/src/lib.rs:1, bin/variant_coverage.rs:1: docs say cargo run -p asap-lower, but the crate is asap-devtools.
• HistogramKind::RawDataSamples: the metric isn't a histogram. Suggested: HistogramSampleType.

5. Stale documentation

• docs/design_docs/architecture/asap-aware-plan-search.md and about 10 other docs still reference CandidateLogicalASAPDAGs, TargetSubDAGCandidates, RankedTargetSubDAGCandidates, global_selection and assemble_selected_dag. Apart from one mention in the logical-asap-optimization/src/lib.rs header, none of these exist in code.
• The glossary's definition of "Candidate" conflicts with proposals/joint-planning-search.md.
• executor/src/capability.rs:10 refers to a nonexistent binding module.
• FieldDataType::Sketch doc says SketchKind carries the grouping layout, but grouping is the second tuple field.
• QueryWorkload.repeating_queries doc says "fixed interval", but RepeatedDemand also allows Scheduled / EstimatedRate.

Behavior that must remain unchanged

Planner output, plan costs, executor results, CLI semantics, and dag-viewer behavior. Renames only, plus deletion of the always-empty legacy fields.

Before and after structure

Before: overlapping terms as listed above. After: each term in sections 1–2 has one meaning, recorded in docs/design_docs/concepts/glossary.md, and the code follows it. Proposed order:

1. Decide glossary meanings for candidate, physical, memo, state, population, sample, raw, and producer/consumer.
2. Delete the dead legacy fields (LogicalCandidate.choice, .pass2, combinations).
3. Rename names that say something false: PlanSelector, local_cost, --exhaustive / --max-combinations, show_logical_dag, SummaryFamilyType, milp_time_limit_ms.
4. Unify synonyms crate by crate, following the step-1 glossary.
5. Fix the stale docs.

Why the proposed structure is minimally complex

No new types or layers. Renames and deletions only.

Existing unit and end-to-end protection

Existing unit and integration tests (crates/integration-tests) cover the renamed types. Renames are compile-checked. The dag-viewer and JSON output field renames need the viewer and its consumers updated together.

Compatibility or migration impact

• Public API renames in asap-types, asap-planner and the frontends affect downstream callers.
• Devtools CLI flag renames (--exhaustive, --max-combinations) and binary names affect scripts and docs.
• Report/JSON field renames affect tools/dag-viewer and any saved outputs.

Found by an AI-assisted naming survey (four read-only sub-surveys). Each sub-survey says it read the definition and a few uses of everything it lists. Only a few of the larger claims were re-checked against the code.

🤖 Generated with Claude Code