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

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

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

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

1. Create asap-accuracy; move the accuracy model (removes X4).
2. Create asap-cost; move resource-usage estimation and the cost models.
3. Move the single-stage algorithms out of asap-types, and the workload-derived bounds into it.
4. Move the boundary types into asap_types::stages ([Refactor] One named type per stage boundary: PerComputationLogicalMemoCandidates → LogicalASAPMemoCandidates → PhysicalASAPMemoCandidates #1047 P3–P5).
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.
6. Move all sizing into Pass 1 (removes X2), then the realizer trait (removes X1).
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.
8. Visibility pass per crate, then the CI graph test.

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.