[Refactor] Crate organization by stage: per-crate functionality, cross-stage code into asap-accuracy / asap-cost / asap-types, enforced crate boundaries, public vs private #1054

Example

Run stage_pipeline on one query, quantile_over_time(0.9, latency[5m]), evaluated every minute with max_error 0.01. On main (cef05d2), the crate that should only select a plan (asap-plan-selection, Stage 3) runs every other stage itself:

The other crates have the same problem:

• asap-types holds algorithms used by one stage only.
• asap-physical-asap-optimization (Stage 2) depends on the Stage 1 crate for one field and one re-export.
• Almost every module of asap-logical-asap-optimization is pub.

What should happen instead:

• Each stage crate does only its stage.
• Stage crates never depend on each other.
• Shared models (accuracy, cost) and shared types live in non-stage crates.
• Each crate makes public only what other crates use.

Status (2026-10-31)

• code: decided 2026-10-31, Pass 1 sizes each approximate input for δ even when the query's root composes no guarantee (e.g. a ratio of quantiles under avg, or topk … or quantile). This follows the sizing table literally; such plans are rejected anyway when guarantees are enforced.

Done on refactor/stage-boundaries, apart from the open items below. Each stage crate depends only on asap-types, asap-accuracy and asap-cost. asap-plan-selection has no edge to logical or physical, and physical has none to logical. A CI test reads cargo metadata and checks the graph (integration-tests/tests/crate_graph.rs, #1132). The test allows two exceptions:

• logical → frontend-promql, optional, enabled only by test-support;
• planner → executor, which Deployment interface review: InstallablePlan, materialized views, DataStore and the executor #1016 decides.

Where the code differs from the text decided on 2026-10-29, the text below says so with "code:". Stage 3 internals are out of scope: the #1095 redesign was removed in #1133, so the old engine is Stage 3's only engine behind the frozen select_plan interface (#1047).

Open (Stages 0–2):

• Memo layout across crates ([Refactor] One named type per stage boundary: PerComputationLogicalMemoCandidates → LogicalASAPMemoCandidates → PhysicalASAPMemoCandidates #1047 D1). MemoCandidates is a public struct with public fields, and it is the public memo field of the Pass 1 and Pass 2 outputs.
• Low-value visibility leftovers in asap-types:
  • validate_at_ingestion and planned_data_state are pub, but only integration-tests use them.
  • Some IR compilation types (PhysicalASAPNodeIdentityMap, PhysicalASAPDAGCompilation, ProducerStorageMetrics, …) have only test users outside the crate. Check each one against the public signatures before narrowing it.
• Naming leftover: Stage 0's hash-consing lives under the logical crate's pass2/ module (pass2/cse.rs, pass2/memo.rs). Optional.

Open, allowed but not needed yet (no work planned):

• asap-cost lower and upper cost bounds over all materializations, for early pruning in Stages 1–2. With them, cost-dominance pruning in Stages 1–2 would follow the pruning rule below.

Outside this issue: planner → executor and the deployment items in asap-types (#1016).

Concrete maintenance problem

Current crate graph ([dependencies], not dev-dependencies)

flowchart TD
  planner["asap-planner<br/>(facade)"]
  fsql["frontend-sql"]; fpromql["frontend-promql"]; fmql["frontend-metricsql"]; fcommon["frontend-common"]
  ps["asap-plan-selection<br/>(Stage 3, plus S1/S2/facade code)"]
  phys["asap-physical-asap-optimization<br/>(Stage 2)"]
  logical["asap-logical-asap-optimization<br/>(S0 hash-cons, Pass 1, Pass 2, accuracy)"]
  exec["asap-executor"]
  types["asap-types<br/>(IR, workload, plus single-stage algorithms)"]
  planner --> fsql & fpromql & fmql
  planner --> ps
  planner --> logical
  planner -- "✗ #1016" --> exec
  fsql & fpromql & fmql --> fcommon
  fcommon --> types
  ps -- "✗ X1, X3: calls Stage 2" --> phys
  ps -- "✗ X2, X4: runs Pass 1/2, accuracy" --> logical
  phys -- "✗ one field + one re-export" --> logical
  logical --> types
  phys --> types
  ps --> types
  exec --> types
  classDef stage fill:#e8f0fe,stroke:#4a6fa5
  classDef bad fill:#fdecea,stroke:#c0392b
  class fsql,fpromql,fmql,fcommon,logical,phys stage
  class ps bad

Edges marked ✗ are the ones this issue removes or redirects. Not drawn: devtools and integration-tests (they depend on almost everything); dev-dependencies (executor → logical, plan-selection); the optional logical → frontend-promql under test-support; external crates (asap_sketchlib, highs, parsers).

The graph has no cycles. The problem is which edges exist and what each crate holds:

What each crate holds today (production lines)

Data structures and functions used across stages

Visibility

• asap-logical-asap-optimization: pub mod accuracy / pass1 / pass2 and every submodule are public. About 40 pub items of asap_aware_cse are used outside the crate only by devtools.
• asap-plan-selection:
  • PlanSelector and its methods, CalibrationFit, cost::analytical and cost::operator_statistics (~20 types), and six cost constants are pub with no user outside the crate.
  • pub use search as pass; (lib.rs:297) gives one module two public paths.
• asap-types: single-stage functions are public crate-wide.

Before and after structure

Decided 2026-10-29.

Target crate graph

flowchart TD
  planner["asap-planner (facade)<br/>runs: frontends → S0 → P1 → per round: P2 → S2 → S3 → build plan → InstallablePlan<br/>splits deployment inputs; injects the Stage 2 realizer into Stage 3"]
  fe["asap-frontend-*<br/>(Stage 0 lowering)"]
  logical["asap-logical-asap-optimization<br/>(S0 hash-cons, Pass 1 incl. all sizing, Pass 2)"]
  phys["asap-physical-asap-optimization<br/>(Stage 2, realizer)"]
  ps["asap-plan-selection<br/>(Stage 3 only)"]
  acc["asap-accuracy (new)<br/>guarantees, estimators, sizing, AccuracyModel"]
  cost["asap-cost (new)<br/>resource usage, cost models 1/2/3, CostInputs"]
  types["asap-types<br/>IR, workload, workload-derived bounds,<br/>stage-boundary types (asap_types::stages)"]
  planner --> fe & logical & phys & ps
  fe --> types
  logical --> acc
  logical -.->|early pruning| cost
  phys -.-> acc
  phys -.->|early pruning| cost
  ps --> acc
  ps --> cost
  logical & phys & ps --> types
  acc --> types
  cost --> types
  classDef stage fill:#e8f0fe,stroke:#4a6fa5
  classDef shared fill:#e9f7ef,stroke:#2e8b57
  class fe,logical,phys,ps stage
  class acc,cost shared

Blue boxes are stage crates; there is no edge between any two of them. Green boxes are shared models; any stage may depend on them, and dashed edges are allowed but not needed yet. planner also depends on asap-accuracy, asap-cost and asap-types to assemble deployment inputs (not drawn).

Rules:

1. Stage crates never depend on each other. The stage crates are frontend-*, logical, physical and plan-selection. A stage reads the previous stage's output type from asap-types and calls no other stage. Any stage may use asap-accuracy and asap-cost.
2. asap-accuracy and asap-cost depend only on asap-types. Neither depends on the other: the workload-derived bounds both need live in asap-types.
3. The facade is the only crate that depends on every stage. devtools and integration-tests are unrestricted.
4. CI checks the graph. A test reads cargo metadata and fails on any [dependencies] edge outside the allowed list.

Per-crate functionality after the change

Deployment items in asap-types (materialized_view.rs, SupportedSummary, the executor kernel list) and the planner → executor edge are decided in #1016.

Resolving the four cross-stage calls

Sizing: every size is decided in Stage 1, Stage 3 only checks

Sizes are decided in four places today:

1. Pass 1 per budget share (groups.rs:204-215 → compose_alone → sized).
2. add_scoped_candidates in plan-selection.
3. Pass 2 shared sizes (size_for_all_readers, shared_size, state groups).
4. Stage 3 δ resizing (lib.rs:2243).

After the change:

Docs to fix (done: #1098 and the final docs pass #1148): planner-layering.md ("Summary nodes are created unsized") and per_computation_candidates.rs:22 should say that Pass 1 creates sized candidates, one per accuracy-budget split. Smaller sketches per pane are out of scope; they need a sketchlib bound that depends on the number of merges.

Pruning

#1047's rule becomes: a stage removes only what its own knowledge proves invalid, or what is provably dominated under the shared cost model. Each stage records PrunedCandidate<C> with one PruneReason enum (asap_types::stages). Cost-dominance pruning in Stages 1–2 is allowed but not implemented yet.

• Dominated means the pruned candidate's cost lower bound is ≥ the kept candidate's upper bound, for the same output, a guarantee at least as strong, and the same sharing.
• This is the memo design's "keep the cheapest per sharing signature".

Visibility rules

• Public: a crate's entry functions, its boundary and IR types, and what the facade and devtools use.
• pub(crate): used by other modules of the same crate.
• Private: used only in its own module.
• #[cfg(test)] or a test-support feature: used only by tests.
• No pub mod that leaks internals, and no second public path to the same item.

Dead and test-only public code found by this review is listed in #1046.

Why the proposed structure is minimally complex

There are two new crates, each shared by several stages:

• asap-accuracy: Pass 1, Pass 2, Stage 3.
• asap-cost: Stage 3 now; earlier stages for cost-based pruning later.

Everything else is moving code to the crate whose stage uses it, and narrowing visibility. Removing the edges between stage crates turns the "no calls across stages" rule (#1047) from a review convention into a compile error.

Existing unit and end-to-end protection

• Planner snapshots in devtools/tests/corpus_snapshots/ must stay unchanged in every PR.
• cargo test --workspace.
• The new cargo metadata graph test.

Compatibility or migration impact

• Import paths change with no compatibility aliases (Reorganize by stage: one memo-based Pass 2, Stage 1 finishes the memo, deployment inputs split by stage, asap-planner as the only entry point #958 decision 5). Externally, ASAPQuery-backend uses only asap_planner (InstallablePlan, PlanningWorkload, StoredOutputBuild, PlanError), checked in its origin/main.
• PlanSelectionSettings becomes CostInputs, including the stage_pipeline --plan-selection-settings file. code: the flag is --cost-inputs <file> and the planner field PlanningModels.cost_inputs (with_cost_inputs), with no alias (refactor: rename --plan-selection-settings to --cost-inputs and PlanningModels.plan_selection to cost_inputs (#1054) #1141).

Suggested order (one concern per PR; move PRs only move code):

• 1. Create asap-accuracy; move the accuracy model (removes X4). refactor: create asap-accuracy with the accuracy model (#1054, part 1) #1077, refactor: move guarantee propagation and sizing into asap-accuracy (#1054, part 2) #1085
• 2. Create asap-cost; move resource-usage estimation and the cost models. refactor: create asap-cost with resource-usage estimation and cost models (#1054) #1061, refactor: move Stage 3's cost formulas into asap-cost; PlanCost (#1095 C2) #1102
• 3. Move the single-stage algorithms out of asap-types, and the workload-derived bounds into it. refactor: move single-stage algorithms out of asap-types (#1054) #1060, refactor: move data-workload bounds into asap-types (#1054) #1083, refactor(logical): narrow Stage 1's public API to what other crates use; split_shared_by_timing moves to Stage 2 (#1054) #1145 (split_shared_by_timing); refactor(accuracy): sized_for_failure_probability is private (#1054) #1131 made the dead sized_for_failure_probability private
• 4. Move the boundary types into asap_types::stages ([Refactor] One named type per stage boundary: PerComputationLogicalMemoCandidates → LogicalASAPMemoCandidates → PhysicalASAPMemoCandidates #1047 P3–P5). The last two, DagOfLogicalMemoGroups and PerComputationLogicalMemoCandidates, moved in refactor: Stage 0 and Pass 1 boundary types in asap_types::stages (#1054) #1146. The memo layout itself ([Refactor] One named type per stage boundary: PerComputationLogicalMemoCandidates → LogicalASAPMemoCandidates → PhysicalASAPMemoCandidates #1047 D1) is still open
• 5. Move the Stage 2 catalog into physical ([Refactor] One named type per stage boundary: PerComputationLogicalMemoCandidates → LogicalASAPMemoCandidates → PhysicalASAPMemoCandidates #1047 P5); fix X3. Drop physical → logical. refactor: move the Stage 2 catalog into asap-physical-asap-optimization (#1047 P5b) #1090, refactor: Stage 2 records whether a pane chain may be kept; pricing reads it (#1054 X3) #1079, refactor: each stage reads only its deployment capability; physical no longer depends on logical (#958) #1075
• 6. Move all sizing into Pass 1 (removes X2), then the realizer trait (removes X1). refactor: decide every sketch size in Pass 1; Stage 3 only checks (#1054 X2) #1098, refactor: AssignmentRealizer trait in asap_types::stages, implemented by Stage 2 (#1054 X1) #1097. X1 is done in its short-term form; the long-term "realizer goes away" option stays under consideration
• 7. Move orchestration and the public API to the planner (Reorganize by stage: one memo-based Pass 2, Stage 1 finishes the memo, deployment inputs split by stage, asap-planner as the only entry point #958 step 6, [Refactor] One named type per stage boundary: PerComputationLogicalMemoCandidates → LogicalASAPMemoCandidates → PhysicalASAPMemoCandidates #1047 P7). Drop plan-selection → logical / physical. refactor: facade runs the stages; Stage 3's frozen select_plan interface (#1047 P7) #1107
• 8. Visibility pass per crate, then the CI graph test. types/frontends refactor: narrow physical, cost, accuracy and types visibility (#1054 step 8b) #1094, refactor: narrow asap-types test-only fields and frontend visibility (#1054 step 8b, part 2) #1099, fix: lower_metricsql and lower_metricsql_query stay public (CI external-consumer check) #1114; physical refactor(physical): one public path per Stage 2 item; reference pricer behind a feature (#1054) #1135; cost refactor(cost): narrow asap-cost's public API to what other crates use #1136; logical refactor(logical): narrow Stage 1's public API to what other crates use; split_shared_by_timing moves to Stage 2 (#1054) #1145; graph test test(integration): CI checks the workspace crate graph (#1054) #1132. Low-value leftovers in asap-types: see Status

Related

• Reorganize by stage: one memo-based Pass 2, Stage 1 finishes the memo, deployment inputs split by stage, asap-planner as the only entry point #958: Stage 1 crate reorganization; its decisions 3–4 are extended here.
• [Refactor] One named type per stage boundary: PerComputationLogicalMemoCandidates → LogicalASAPMemoCandidates → PhysicalASAPMemoCandidates #1047: stage-boundary types; [Refactor] Pane-width rounds without cross-stage calls: rerun Pass 2 per round, or pass an incremental Pass 2 state #1048: pane-width rounds.
• [Refactor] Rename memo-named caches and the memo types by stage #1050: memo and cache renames.
• Remove dead and test-only code: row-reference oracle, old_docs, test-only demand model, batch bridge, memo snapshot #1046: dead code.
• Deployment interface review: InstallablePlan, materialized views, DataStore and the executor #1016: deployment items and the executor dependency.
• Stage 1 Pass 2 review: ASAP-aware CSE rules over memo groups and summary-state groups #1013: Pass 2 window rules.
• memo-milp: size summaries once (final config per reader set and summary count; Stage 3 never resizes) #929: sizing once per reader set.
• Tracking: stage-by-stage review of ASAPPlanner — functionality, concepts, abstractions, interfaces #1010: stage-by-stage review.