docs: describe the planning stages, devtools and types now on main

[zzylol]

Closes #677.

Why

The PRs that landed this week (Pass 2 reuse rules, Stage 2 materialization and the latency check, the AccuracyTarget builders, cost models 1–3, the Pass 2 *Candidate names, FusedComputation, and the DataWorkload reshape into arrival + sources) changed no Markdown, or only the lines that named their own API. The docs therefore still described types, fields and tools that no longer exist on main:

• run-a-query.md sent readers to show_pre_asap_ir, show_post_asap_ir and dag_export, none of which exists.
• stage-viewer.md described tabs (2, 4a, 4b), a deployment-inputs panel and --example planner-layering-4a/-4b that the viewer and stage_pipeline do not have, and its numbers predate materialization.
• Design and developer docs used input_cardinality, data_ingestion_interval, ingestion_rate, continuously_ingesting, Evidence<T> freshness, ResultGuarantee, AccuracyTarget::Exact / Epsilon / EpsilonDelta and EstimatorContract::ClassicHll.
• library-api.md examples no longer compiled, and it did not mention the stage pipeline at all.

What

Docs only. Each doc keeps its audience; the user's own prose is unchanged except where a name, field or behaviour is now wrong.

• User guides (docs/user_guide_docs/run-a-query.md, stage-viewer.md, tools/dag-viewer/README.md, root README.md, docs/README.md)
  • run-a-query.md lists the binaries that exist: stage_pipeline, show_logical_dag, analyze_corpora, variant_coverage, sketch_coverage, plus the two examples. Every command in it was run at this head.
  • stage-viewer.md: the tab table has the three tabs examples.json defines (1, 3a, 3b). Example 2 (now with its MatAtQuery plans) and Example 4 (Example 3b under cost models 1, 2 and 3) move to a "no tab, run from the command line" table. The editor section describes the real fields (input tables, SQL or PromQL, ε, metric; no δ, fixed 15 s interval). The option table lists every stage_pipeline flag, including --sql, --table, --name, --metric, --cost-model and the cluster flags. The stale "based on PR feat(dag-viewer): redesign the viewer around the stage pipeline #574" banner and the deployment-inputs panel section are removed.
  • The viewer README's document schema shows cost_per_second, usage, front and the P<n>-m<k> materialization ids.
• Deployment capabilities (landed with feat(asap-aware-mapping)!: deployment capabilities (supported summaries, raw-data and query-time retention) #730): stage-viewer.md documents --deployment-capabilities (supported_summaries, raw_data_retained, query_time_results_retained), the raw-data rejection and the pass1_pruned listing, and Example 4's row shows kept panes (P3-m2, 8,884.53 per second) and no raw data (P3-m1 selected). The viewer README's schema adds deployment_capabilities and pass1_pruned, and per_node holds only cost_per_second, multiplier and detail. library-api.md lists DeploymentCapabilities and with_deployment_capabilities. planner-layering.md's Stage 2 paragraph and the Example 4 acceptance doc describe MatAtQueryKeptAcrossEvaluations (B3) and the B3 tests that now pass.
• Measured operation costs and removed legacy cost models (main since ac8493a2): stage-viewer.md and run-a-query.md document stage_pipeline --measured-operation-costs and convert_rqe_atomic_costs; the viewer README's per_node gains price_source; library-api.md adds measured_operation_costs to PlanSelectionSettings and drops the deleted EmpiricalCostModel / PhysicalPlanCostModel rows and comparison; offline-sketch-evidence.md, storage-operation-costs.md and physical-handoff-costs.md say their planner consumer is gone. post-asap-ir.md uses split_shared_by_timing (the rename in chore!: accumulated review nits (column-metric and viewer fixes, timing names, lost tests, stale comments) #737).
• Developer docs (docs/develop_docs/)
  • library-api.md: dependency pins at a current revision (775e21ee) with asap-planner and tokio for the e2e_plan example, a new section "Plan a workload through the stages" (asap_planner::e2e_plan, run_stage1_to_stage3, PlanningModels, PlanSelectionSettings, CostModel 1–3, ResourceUsage, PlanOutput), the AccuracyTarget builder table, and the legacy search, ranking, strategy, cost-model and selection sections removed, since that code is deleted on main. The doc now reads lowering → planning through the stages → inputs and defaults → export.
  • asap-aware-mapping-architecture.md, asap-aware-mapping-contracts.md and extend-asap-aware-mapping.md are rewritten around the stage code: where each stage lives, the rules each stage's input and output follow, and recipes for adding a summary family, a Pass 2 rule, a Stage 2 option, a Stage 3 check or a frontend construct.
  • metrics-observability-corpora.md describes the Stage 1 measurement the corpus test runs; replacement-explanations.md, planner-vocabulary-migration.md and target-candidate-api-migration.md carry a historical note; develop_docs/README.md lists them under "Historical records".
  • end-to-end-accuracy-guarantees.md, pre-asap-ir.md, offline-sketch-evidence.md, physical-handoff-costs.md, storage-operation-costs.md, physical-compile-coverage.md, target-candidate-api-migration.md: AccuracyGuarantee, the builders, classic HLL's per-source distinct bound, and no dag_export.
• Design docs
  • planner-layering.md: the shared and Example 2 data tables (arrival, sources[...].series_count, sources[...].sample_interval), the approximate-target sentence, Mixed, the moved workload.rs link, Example 2's SQL recognition, one added paragraph each for what Stage 2 implements and for Stage 3's resource usage and cost models 1–3, and two new rows in the Pass 2 rule table (rollup rule, exact top-k reuse rule), so it lists all five rules. The Problem Definition section, the overview diagram's wording and the lookback / as_of columns keep the original text.
  • planner-layering-example{1,2,3,4}-acceptance.md: counts, costs and test statuses from stage_pipeline and the tests at this head. These include the three Example 1 corrections recorded on Update the docs after the G1–G11 consolidation groups land #677, and Example 3a, where no DDSketch plan is valid any more because the targets are rank errors.
  • analytical-resource-cost.md and planner-runtime-contract.md use the past tense for the removed physical-plan adapter and global_selection; the Example 4 acceptance doc no longer claims B2 ≥ B1, B3 under every model (cost model 1 makes B2 cheapest).
  • input-output-workflow.md, architecture/README.md, concepts/planner-pipeline.md, planner-runtime-contract.md and physical-planning-and-deployment.md describe Stages 0–3 and PlanOutput instead of CandidateLogicalASAPDAGs ranking and global_selection.
  • Docs about the removed search (asap-aware-mapping.md, asap-aware-plan-search.md, evidence-dependent-candidates.md, cse-cost-model.md, asapquery-rule-coverage.md, ddsketch-quantile-ratios.md) carry a historical note; updated_interface_with_pluggable_optimization.md, analytical-resource-cost.md and concat-unique-keys.md get updated status lines.
  • Historical and concept docs: ResultGuarantee → AccuracyGuarantee (the list recorded on Update the docs after the G1–G11 consolidation groups land #677), AccuracyTarget forms, the classic-HLL example in accuracy-models.md, and the old DataWorkload fields in analytical-resource-cost.md.

How

• I grepped every Markdown file for each identifier that feat(planner): Pass 2 reuse rules (rollup, exact top-k reuse) and nested sum merge in Pass 1 (#680) #716–refactor(planner)!: Pass 1 candidates are exact or a summary; fused computations become the outer target's FusedComputation #729 removed or renamed, and fixed each hit that describes current code. Hits that describe the legacy search, which is still on main, were left alone (see Limitations).
• Every number I changed comes from a stage_pipeline run at 0b4fb83a, or at 66533b36 for the deployment-capability runs (--deployment-capabilities with KLL only and query_time_results_retained, and with raw_data_retained: false) (--example planner-layering-1/-2/-3a/-3b, with --max-displayed 100000 for the totals, and Example 3b under --cost-model provisioned-capacity and cluster-capacity at 256 GB and 64 GB). None was written by hand.
• Every Rust example in library-api.md was compiled and run as a temporary test, which is not committed.

Key code interfaces added / modified

None (docs only).

Before this PR

cargo run -p asap-devtools --bin show_post_asap_ir -- --sample-interval-ms 1000 queries.txt
# error: no bin target named `show_post_asap_ir` in `asap-devtools` package

stage-viewer.md said that Example 2's 12 valid plans were the only valid ones and that a "4b" tab existed. library-api.md built targets with AccuracyTarget::Epsilon(0.01), which no longer compiles.

After this PR

cargo run -p asap-devtools --bin stage_pipeline -- \
    --promql "topk by (job) (10, sum_over_time(http_requests_total[1m]))" \
    --epsilon 0.01 --delta 0.001 --out plan.json
# selected P1 (exact); P2 CMS+heap rejected (weights not proven non-negative),
# P3 CountSketch+heap rejected (no guarantee)

The guides' commands run as written, and Example 2's row in stage-viewer.md reports what the planner does now: 184 physical plans, 20 valid, and P1 at 6.08 per second. The shared count accumulator costs 7.04 per second when it is built once at query time, against 7.44 when it is not materialized.

Verification

• Ran every command in run-a-query.md and stage-viewer.md at this head: the stage_pipeline examples and options, show_logical_dag (file and stdin), analyze_corpora --corpora and --sql-corpora, variant_coverage, sketch_coverage, and the topk_ir and canonical_examples examples.
• Started python3 tools/dag-viewer/server.py --skip-build. It wrote the three tab documents and printed its address, and POST /api/plan returned a selected plan.
• Compiled and ran the library-api.md Rust examples at 775e21ee (temporary test, not committed): the e2e_plan example prints selected P1 at Some(0.000313...) per second with P2 and P3 rejected.
• Checked the relative links in the changed docs.
• cargo fmt --all -- --check. No Rust or doc comment changed, so cargo test --doc was not needed.

Limitations and follow-ups

• Broken source links remain only in documents marked historical (for example cse-cost-model.md's links to cost_model.rs and replacement.rs).
• Names a parallel rename PR changes (AccuracyTarget.error, --epsilon/--delta/--metric, Rejection.valid) are left as they are on main.
• planner-layering.md's Problem Definition row ("volume, rate, cardinality and distribution") and its illustrative Example 1 narrative stay as written; the acceptance doc records the planner's numbers.
• asap-primitive-schema.md was changed only where a type name or field list was wrong (AccuracyGuarantee, its spec fields).