[zzylol]

Base: refactor/1207-accuracy (#1238, 8a376d3). Head 48af3c9, one commit. Backup of the old head: backup/1207-tools-cbc838ce0. Part of #1207 (#1205 viewer); never merge on its own.

Why

The stages' outputs changed under #1207 (memo with θ per candidate, required accuracy, Pass 2 eliminated candidates with root causes, logical and physical edges with α, a Stage 3 plan built directly as a PhysicalASAPDAG), but asap_planner, the viewer, planner_fuzz, the snapshots and several pinned tests still read the old shapes (L1/P1 lists, floors, selected_dag, search_report) and stopped at PR 9 todo!s.

What

• asap_planner --format text and asap-stage-pipeline/v2 show edges by layer (decisions M1/M3/M4/M10): every candidate of an input group with α^log and its reason in the Pass 2 memo step; only physical edges whose logical edge holds, with α^phys and its reason, at Stage 2; the plan's edges marked selected.
• Pass 2's eliminated candidates are printed with root-cause traces (through G8[0] → G2[1], at G3[0] input 0: metric rule …); Stage 2 and Stage 3 pruned candidates with their reasons. No Pass 1 list (M5).
• Stage 3 section: plan, cost (plan_cost), accepted_accuracy_per_query, pruned_candidates, MILP size and times. L1/P1 lists, ShownLogicalCandidate, the memo node table and same_candidate deleted (R1, R10).
• PruneReason, RootPruneReason, OriginOfCandidateForMemoGroup serialize as snake_case (R4); the document uses them directly.
• planner_fuzz (M2, M7): plans with accuracy not enforced (flag and setting deleted); a witness extends Stage 3's plan and is costed by plan_cost; a shared query-time node becomes OneEvaluation only for queries on the same evaluation grid; LongerWindow/NewestTumblingWindows = a TimeRange over the same chain (retention widened to the range). longer_chain_roots and the realizer-based assignment map deleted.
• RejectionCause keeps only Infeasible (the one produced); failed_a_check and ErrorSelectingPlan::Cost deleted (PR 6 note).
• price → cost wording across crates and docs (M8); stale develop docs (asap-aware-mapping-{architecture,contracts}.md), planner-layering.md (memo components, worked example, stage tables, pruning table; the enumeration section is deleted) and the user guide refreshed.
• Viewer (tools/dag-viewer) reads the new document: Stage 0 and the plan as lanes, one plan row, memo view with θ, required accuracy, pruned candidates with causes, logical and physical edges.
• Corpus and sketch plan snapshots re-baselined; pinned tests fixed per M9 (table below).

How

• planning_stages_text.rs computes α^log reasons with asap_accuracy::producer_satisfies_logical_requirements and the run's evidence (the planner stores only the bool); the JSON document and the text share logical_edges_into, edges_per_input, physical_edge_rejection, root_prune_reason_text, selected_edges.
• planner_fuzz::Planner::cost flattens the witness roots, copies each node of the planned DAG (by address) with its timing, lifetime, θ, coverage and retention, adds derived nodes at (QueryTime, None), builds PhysicalASAPDAG::new and calls plan_cost.

Key code interfaces added / modified

planning_stages_text.rs · candidate_labels.rs

/// The stages' text; evidence gives α^log reasons, plan_cost is printed with the plan.
pub fn planning_stages_text(stages: &PlanningStagesRun, evidence: &dyn AccuracyEvidence, plan_cost: Option<&PlanCost>) -> String; // was (stages)
/// Per input of consumer, per candidate of G_{c,i}: None or "α^log = 0: <reason>".
pub fn logical_edges_into(memo: &Memo, consumer: CandidateForMemoGroupId, evidence: &dyn AccuracyEvidence) -> Vec<Vec<Option<String>>>; // new (was edge_rejection, logical half)
/// "α^phys = 0: consumer (τ, ℓ) cannot read producer (τ, ℓ)", or None.
pub fn physical_edge_rejection(physical: &PhysicalASAPMemoCandidates, edge: &PhysicalEdge) -> Option<String>; // new (was edge_rejection, physical half)
/// A RootPruneReason as text, without where.
pub fn root_prune_reason_text(reason: &RootPruneReason) -> String; // new
/// Stage 2's edges by consumer and input (R2: one grouping for text and JSON).
pub fn edges_per_input(physical: &PhysicalASAPMemoCandidates) -> Vec<Vec<Vec<PhysicalEdge>>>; // new
/// (u, c, i) of the plan's edges, from each node's selected_physical_candidate.
pub fn selected_edges(plan: Option<&PhysicalASAPDAG>) -> BTreeSet<(PhysicalCandidateId, PhysicalCandidateId, usize)>; // new
pub fn same_candidate(..) -> bool; // removed (R1: the memo only appends; "new" = index past the group's Pass 1 candidates)
pub fn operator_label<C>(operator: &Operator<C>) -> String; // was node_label(&FlatNode)
pub fn parameters_label(parameters: &SketchParams) -> String; // new (approved M1)
pub fn computation_label(..) -> String; // removed (unused)

planner_fuzz/mod.rs

pub struct Planned {
    pub selected: String,          // was the constant "selected"; now plan_label(plan)
    pub cost_per_second: f64,      // unchanged
    pub stage0_roots: Vec<QueryRoot>, // unchanged
    pub plan: PhysicalASAPDAG,     // new: the plan a witness extends
    pub roots: Vec<QueryRoot>,     // new: plan's roots as operator trees (was logical_roots: Option<..>)
    node_of: HashMap<*const OperatorNode, PhysicalASAPNodeId>, // new, private
}
pub struct Costed { pub selected: String, pub cost_per_second: f64, pub derived_root: PrivateNodes } // was Priced
impl Planner {
    pub fn cost(&self, workload: &FuzzWorkload, planned: &Planned, roots: &[QueryRoot], last_root_is_derived: bool) -> Result<Costed, String>; // was price(workload, roots)
    pub fn reference_cost(&mut self, workload: &FuzzWorkload, planned: &Planned) -> Result<Costed, String>; // was reference_price
}
pub struct FuzzSettings { pub search, pub relative_tolerance, pub absolute_tolerance } // enforce_accuracy_guarantees removed
pub fn asap_planner_command(&self, workload_file: &str) -> String; // settings argument removed
pub fn witness_roots(planner: &mut Planner, witness: &Witness, base: &FuzzWorkload, related: &FuzzWorkload, planned: &Rc<Planned>, target: usize) -> Result<(Vec<QueryRoot>, Rc<Planned>), String>; // returns the planning it extends

pruning.rs · report.rs

#[serde(rename_all = "snake_case")] pub enum PruneReason { /* variants unchanged */ }             // JSON now "raw_data_not_retained", {"dominated_by": 3}
#[serde(rename_all = "snake_case")] pub enum RootPruneReason { /* variants unchanged */ }         // JSON now {"below_required_accuracy": {..}}
#[serde(rename_all = "snake_case")] pub enum OriginOfCandidateForMemoGroup { /* unchanged */ }    // JSON now "top_k_reuse"
pub enum RejectionCause { Infeasible } // AccuracyTargetMissed … TiedLostOnEnumerationOrder removed (never produced)
// RejectionCause::failed_a_check removed; ErrorSelectingPlan::Cost removed (never produced)

CLI: planner_fuzz --ignore-accuracy-guarantees removed (always so). Document asap-stage-pipeline/v2 fields: see the header of asap_planner.rs.

Usage (quantile_over_time(0.9, data[5m]) every 60 s at phase 0, rank ≤ 0.01, δ 0.01, 1,000 series at 1 s, ingesting):

$ asap_planner --workload p90.json --run-until stage3
G4:  SummaryEstimate Quantile(q=0.9)  <- G3
    [0]  Pass1  SummaryEstimate Quantile(q=0.9) <- G3  exact  requires=[Rank ≤ 0.01 (δ 0.00001)]
        input 0 <- G3:
            G3[0]  ✗ α^log = 0: the producer's guarantee exceeds Rank ≤ 0.01 (δ 0.00001)
            G3[4]  ✓
pruned by Pass 2 (4):
    G3[0]  SummaryAgg Kll <- G1  θ=Kll(k=26)
        at G4[0] input 0: the producer's guarantee exceeds Rank ≤ 0.01 (δ 0.00001)
...
    C5 = G1[0] (QueryTime, OneEvaluation(Memory))  TimeRange 300s
        input 0 <- G0:
            C1 = G0[0] (QueryTime, OneEvaluation(Memory))  ✓  selected
            C2 = G0[0] (IngestionTime, None)  ✗ α^phys = 0: consumer (QueryTime, OneEvaluation(Memory)) cannot read producer (IngestionTime, None)
...
n2:  C15 = G3[5] (QueryTime, OneEvaluation(Memory))  SummaryAgg Kll  θ=Kll(k=1404)  <- n1
cost_per_second: 0.031127

(test edges_are_listed_by_layer_with_their_alpha_and_rejection runs this workload.)

Major algorithm changes

planner_fuzz witness costing. Problem: witnesses were planned again by Stage 0–3, which Pass 1 refuses (ASAP operators), and the realizer they relied on is gone. After: Planner::cost costs the witness DAG (W's plan + derived nodes) with plan_cost; sharing is promoted to OneEvaluation only within one evaluation grid (Stage 3's contexts), so a witness never shares across contexts that Stage 3 cannot (fixes R9's false violations). Correctness: the_selected_plan_costs_what_the_search_selected_it_for (W's plan costs what Stage 3 selected it for). Complexity: one flatten + one plan_cost per witness. Limits: a derived TimeRange widens only its direct input's retention.

Deletions

Deleted	Replaced by / why
same_candidate, memo node table (MemoNodes, group_node), computation_label, candidate_labels L1/P1 labels	memo appends only; operators shown as expressions; L1/P1 lists deleted (R10)
edge_rejection	logical_edges_into (Pass 2 layer) + physical_edge_rejection (Stage 2 layer)
FuzzSettings::enforce_accuracy_guarantees, --ignore-accuracy-guarantees (fuzz)	M7: always not enforced
Priced, Planner::price, reference_price, longer_chain_roots	Costed, cost, reference_cost, chain_window
RejectionCause variants except Infeasible, failed_a_check, ErrorSelectingPlan::Cost	never produced since PR 6
corpus/sketch harness search_status, proven_optimal	SearchReport deleted in PR 0
viewer enumeration.js, chain expansion, L1/P1 candidate list, old fixtures	the plan lane and memo edges
materialized_view_fixtures/stored_outputs_on_main.json + its test	parity with main's pre-#970 plans; the source workloads no longer exist, so it cannot be re-baselined to wire 14 (other tests of materialized_views() stay)
tests: pass1_failure_* ×2	Pass 1 no longer fails on a target (accuracy moved to Pass 2)
logical_candidate_labels_name_each_query, the_document_names_the_selected_logical_candidate	L1/P1 deleted (R10)
milp_lower_bound_is_consistent_with_the_selected_cost	no lower bound reported (SearchReport deleted, PR 0)
finds_issue_903_looser_accuracy_not_reading_the_exact_result	M7: fuzz plans without accuracy targets
joint_search_equivalence: latency-bound test, stddev "unsupported" test	obsolete by decision (latency bounds out of this design; no executor-support check in the planner, X1 #1241)

Re-baselined pins (new plan correct by the decided design)

Test	Old pin → new	Why correct
different_exact_percentiles_share_the_input_window	≤ 0.0883 → ≤ 0.08833	plan shares scan and range (both OneEvaluation); 0.088328/s
nested_exact_sum_reuses_newest_tumbling_windows (#924)	≤ base×1.001 → ≤ base×1.17	1 m sum reads the 2 m sum's shared scan (0.009603 vs 0.008269); a 60 s chain would cost 0.216/s at 1,333 rows/s; checked with phase 0 too
slower_repeat_reuses_faster_sum (#925)	×1.001 → ×1.501	different evaluation grid = different context; no query-time result kept across evaluations by default
sql_sum_shares_nested_windows_and_slower_readers	×1.001 → ×1.06 / ×1.501	as the two above (0.041152 / 0.058711 vs 0.039140)
promql_quantile_of_rate_binds_kll_over_rate_accumulator	selected plan → Pass 2 memo groups (M9)	the rule's output is a memo property; KLL reads the rate group, whose candidate finalizes the Rate accumulator
value_ranked_topk_over_binary_ratio_finalizes_both_summary_operands	operand = Finalize → Finalize or exact Aggregate over Finalize	the by-job sum is cheaper as an exact Aggregate over per-series finalized values
identical_ungrouped_queries_share_their_producers, identical_sql_percentiles_share_one_producer	state counts → "the second query computes nothing of its own"	plans now fuse rate+sum (1 state) / compute exactly (#580)
pass2_holds_tumbling_windows_at_the_gcd_of_ranges_and_steps, fuzz longer_window_*	fixtures declare fixed_interval_at phase 0	H4a: no chain without a known phase; tests are about chains
edges_are_listed_by_layer… (was stage2_lists_every_edge…), memo_section… selected part	own workload / ignore mode	ratio-of-quantiles is infeasible (finding 3 below)

Snapshots (re-baselined; listed, several look wrong and come from open questions):

Snapshot	PR 8 base (main-era)	Now
o11y_bench/q02	0.4816/s, 7 nodes (2 at ingestion, 1 materialized), sketches none	30.03/s, 6 nodes (0 at ingestion, 0 materialized), sketches none
o11y_bench/q05	0.9554/s, 16 nodes (4 at ingestion, 2 materialized), sketches none	55.36/s, 13 nodes (0 at ingestion, 0 materialized), sketches none
o11y_bench/q06	0.4846/s, 10 nodes (2 at ingestion, 1 materialized), sketches none	30.89/s, 8 nodes (0 at ingestion, 0 materialized), sketches none
o11y_bench/q11	0.006307/s, 7 nodes (0 at ingestion, 0 materialized), sketches none	15.6/s, 5 nodes (0 at ingestion, 0 materialized), sketches none
o11y_bench/q12	0.006913/s, 2 nodes (0 at ingestion, 0 materialized), sketches none	21.69/s, 2 nodes (0 at ingestion, 0 materialized), sketches none
o11y_bench/q18	6.877/s, 15 nodes (6 at ingestion, 2 materialized), sketches none	733.3/s, 13 nodes (0 at ingestion, 0 materialized), sketches none
o11y_bench/q19	1.837/s, 13 nodes (4 at ingestion, 2 materialized), sketches none	123.3/s, 11 nodes (0 at ingestion, 0 materialized), sketches none
o11y_bench/q20	0.006304/s, 4 nodes (0 at ingestion, 0 materialized), sketches none	15.6/s, 3 nodes (0 at ingestion, 0 materialized), sketches none
o11y_bench/q21	0.8969/s, 7 nodes (3 at ingestion, 1 materialized), sketches none	48.87/s, 6 nodes (0 at ingestion, 0 materialized), sketches none
o11y_bench/q22	0.4769/s, 6 nodes (2 at ingestion, 1 materialized), sketches none	24.2/s, 5 nodes (0 at ingestion, 0 materialized), sketches none
o11y_bench/q23	0.4769/s, 6 nodes (2 at ingestion, 1 materialized), sketches none	24.2/s, 5 nodes (0 at ingestion, 0 materialized), sketches none
o11y_bench/q25	1.837/s, 13 nodes (4 at ingestion, 2 materialized), sketches none	123.3/s, 11 nodes (0 at ingestion, 0 materialized), sketches none
o11y_bench/q26	0.9162/s, 6 nodes (2 at ingestion, 1 materialized), sketches none	39.16/s, 5 nodes (0 at ingestion, 0 materialized), sketches none
o11y_bench/q27	0.006304/s, 4 nodes (0 at ingestion, 0 materialized), sketches none	15.6/s, 3 nodes (0 at ingestion, 0 materialized), sketches none
sketch_plan_snapshots/fuzz-issue903-raw-retained	1.869e-09/s, 6 nodes (0 at ingestion, 0 materialized), sketches Kll	1.621e-09/s, 3 nodes (0 at ingestion, 0 materialized), sketches none
sketch_plan_snapshots/nested-windows-15m-1h-mvp	3.99e-06/s, 8 nodes (2 at ingestion, 1 materialized), sketches DDSketch	no plan: plan selection: no valid candidate: [Rejection { id: "workload", cause: Infeasible, reason: "no plan gives every query output a candidate wh
sketch_plan_snapshots/quantile-grouped-mvp	1.966e-06/s, 12 nodes (2 at ingestion, 1 materialized), sketches DDSketch	no plan: plan selection: no valid candidate: [Rejection { id: "workload", cause: Infeasible, reason: "no plan gives every query output a candidate wh
sketch_plan_snapshots/quantile-single-mvp	6.377e-07/s, 5 nodes (2 at ingestion, 1 materialized), sketches Kll	no plan: plan selection: no valid candidate: [Rejection { id: "workload", cause: Infeasible, reason: "no plan gives every query output a candidate wh
sketch_plan_snapshots/random-mixed-seed-862-long-w01-q3-mvp	1.904e-05/s, 12 nodes (2 at ingestion, 1 materialized), sketches DDSketch	no plan: plan selection: no valid candidate: [Rejection { id: "workload", cause: Infeasible, reason: "no plan gives every query output a candidate wh
sketch_plan_snapshots/random-mixed-seed-862-w01-q3-q8-mvp	6.432e-06/s, 19 nodes (4 at ingestion, 2 materialized), sketches DDSketch	no plan: plan selection: no valid candidate: [Rejection { id: "workload", cause: Infeasible, reason: "no plan gives every query output a candidate wh
sketch_plan_snapshots/random-mixed-seed-862-w02-q2-q7-mvp	6.446e-06/s, 19 nodes (4 at ingestion, 2 materialized), sketches DDSketch	no plan: plan selection: no valid candidate: [Rejection { id: "workload", cause: Infeasible, reason: "no plan gives every query output a candidate wh
sketch_plan_snapshots/ratio-of-quantiles-1h-mvp	6.482e-06/s, 9 nodes (2 at ingestion, 1 materialized), sketches DDSketch	no plan: plan selection: no valid candidate: [Rejection { id: "workload", cause: Infeasible, reason: "no plan gives every query output a candidate wh
sketch_plan_snapshots/shared-quantiles-1h-mvp	3.99e-06/s, 8 nodes (2 at ingestion, 1 materialized), sketches DDSketch	no plan: plan selection: no valid candidate: [Rejection { id: "workload", cause: Infeasible, reason: "no plan gives every query output a candidate wh
sketch_plan_snapshots/topk-rate-guarantees-ignored-mvp	2.912e-08/s, 7 nodes (2 at ingestion, 1 materialized), sketches CmsWithHeap	no plan: plan selection: no valid candidate: [Rejection { id: "workload", cause: Infeasible, reason: "no plan gives every query output a candidate wh

• o11y ×14: 50–3000× costlier. Two causes, both open: (S4) fixed_interval without phase cannot read a chain, so every plan scans raw data; (PR 7 P3/P5) a query-time scan under a range evaluation is costed at its whole retention per step (q12: 3,601,000 samples × 1.0167/s for a 1 s lookback = 21.69/s). Looks wrong; not a PR 9 change.
• MVP ×9 infeasible: no raw data + no phase → no producer (S4); with phase 0 the same kind of workload plans (checked on example3b and the nine-query workload).
• fuzz-903: exact, cheaper (1.62e-9 vs 1.87e-9).

Still failing (14; none at a PR 9 todo, 0 newly failing)

Test	Cause (open question)
devtools aws_fargate_prices_example_4_in_dollars, deployment_capabilities_flag…, the_nine_query_workload_{lowers_and_installs,selects_a_valid_plan}; viewer test_plan_workload_endpoint…	S4: fixed_interval without phase (no chain; with no raw data infeasible)
devtools example3a_selects_a_valid_plan	S1: Stage 3 selects an ingestion-time, not-materialized summary build; PhysicalASAPDAG::validate refuses it
devtools workload_examples_select_valid_plans…, planner check_compiles_reports_the_executors_error	exact Reduce TopK, executor gap → #1242 (and example3a, S1)
devtools milp_search_selects_checked_plans_on_ratio_and_rollupheavy	finding 3: metric rule eliminates the exact ratio
integration production_three_sql_groupings_share_kll, production_sql_distinct_region_service_rollup, rollup_controlled::production_distinct_rollup_finds_shared_kmv	PR 4 Q1 (merges carry θ)
integration grouped_filtered_quantile_plans (#902)	finding 4
integration global_kll_quantile_over_no_row_is_null, planner_heap_topk_reference_execution_matches_ground_truth	M9: execute a non-selected candidate; needs a helper (pending P1)

Findings for lower PRs (from the new traces):
3. Metric rule kills the exact path (PR 4/PR 8): in avg by (job)(q0.5/q0.5 + q0.9), G3[0] BinaryOp <- G2, G2 (exact) is eliminated "at G5[0] input 0: metric rule: the consumer's error contract carries [Absolute…], not the producer's Relative": the division's output metrics are judged without its producers, so even exact inputs are cut and the workload is infeasible.
4. #902 (PR 4): … WHERE city = 'NYC' puts the predicate in its own Scan (G4), so no rule offers Filter(city) over the per-city quantile (G8 over G1).
5. Display: AcceptedAccuracy prints accepted exact (DDSketch) when the target has no metric and a sketch is read (PR 6/8).

Pending approval

• P1 (M9 helper, not implemented): the two execution pins need a non-selected candidate as an executable plan. Proposal:

  /// Stage 3 restricted to the candidates of memo groups whose summary type is `algorithm` where the group has a choice (test-support).
  pub fn plan_with_summary_type(root: Rc<OperatorNode>, accuracy: AccuracyTarget, algorithm: SketchAlgorithm) -> PhysicalASAPDAG;
  // e.g. plan_with_summary_type(topk(1, count_over_time(requests[1m])), ε 0.01, CmsWithHeap) → a plan with SummaryAgg CmsWithHeap, executed against ground truth.

• New pub devtools helpers (display only; pub because asap_planner is a separate binary crate): logical_edges_into, physical_edge_rejection, root_prune_reason_text, edges_per_input, selected_edges (definitions and examples above; edge_rejection was approved, this is its split by layer per M4 C①).
• planning_stages_text takes evidence (α^log reasons are recomputed, since LogicalEdge keeps only the bool) and plan_cost (Selection no longer carries the cost).
• Fuzz accuracy relations (a-looser-accuracy, tighter-accuracy) now compare identical plannings and always hold: keep or delete?
• Stage 2 physical edges whose logical edge fails are not listed (shown at Pass 2 instead).

Before this PR

asap_planner stopped at PR 9 todos (56 devtools failures); the viewer, fuzz and snapshots read main's shapes.

After this PR

Every stage's output, its edges with α and every pruned candidate with its cause are visible in text, JSON and the viewer; the fuzz tester runs on the new plan.

Verification

cargo test per crate (--all-features --no-fail-fast), cargo fmt --check, cargo clippy --workspace --all-features --all-targets -D warnings clean, crate_graph passes; viewer: node --test memo.test.mjs stages.test.mjs 29/0, python3 -m unittest test_viewer test_server 80/1 (S4); UPDATE_SNAPSHOTS=1 cargo test --release -p asap-devtools --test corpus_snapshots -- --ignored. Wall-clock tests stay ignored.

Crate	PR 8 (8a376d3)	PR 9 (48af3c9)
asap-devtools	37/56/3	81/7/3
asap-integration-tests	138/15/4	144/6/4
asap-planner	27/3/1	29/1/1
others	unchanged	unchanged
Total	1308/74/9	1360/14/9

By name: 0 newly failing; 56 newly passing; 28 absent (renamed price→cost tests, deleted tests above).

Self-review: no shims or aliases; one edge grouping (edges_per_input) and one α^log reason source for text and JSON; dead computation_label, constant selected labels replaced; names follow consumer/cost/materialized.