One planner CLI: run stages up to a chosen point, print as JSON or text

Goal

One planner binary that runs the stages up to a chosen point and prints their output:

asap-planner explain --workload w.json \
  --until stage0|pass1|pass2|stage2|stage3 \
  --format json|text [--view]

--until: stop after that stage.
--format json: the Stage Viewer document. --format text: the text from feat(devtools): stage_pipeline --text prints every planner stage's output as text #1159.
--view: open the Stage Viewer on the result.

This replaces stage_pipeline and show_logical_dag. The corpus tools could become subcommands later.

Problem

Too many entry points. Inspecting the planner today takes several devtool binaries, and the names (stage_pipeline) don't say what they do.
No way to stop early. Every run goes through the Stage 3 MILP, even to see only the memo. That is slow, and on larger workloads it uses a lot of memory.
The printed memo is not the full memo. Pass 2 and Stage 2 run once per pane-width round inside Stage 3's search, and the document shows only the round that was selected. So you can't see the complete memo. --until pass2|stage2 would run once with all pane widths (PaneWidthDomain::Complete) and print that.

Agreed scope

Command

No subcommand:

asap_planner --workload <file>... --run-until stage0|pass1|pass2|stage2|stage3
  [--format text|json] [--out <file>] [--sql-catalog-table <json>]...
  [--cost-inputs <file>] [--deployment-capabilities <file>] [--ignore-accuracy-guarantees]

--run-until is required. It prints every stage up to and including the one named. pass2 prints both snapshots: after local window composition, and LogicalASAPMemoCandidates (Stage 2's input).
--format defaults to text (the feat(devtools): stage_pipeline --text prints every planner stage's output as text #1159 printer). json is the viewer document; stages that were not run are null, and the format name stays asap-stage-pipeline/v1.
--out defaults to stdout.
Accuracy guarantees are enforced by default, as in the planner library. --ignore-accuracy-guarantees turns that off.
The flags map onto UserInput: --workload → PlanningWorkload, --sql-catalog-table → FrontendInput::Sql, --cost-inputs → CostInputs, --deployment-capabilities → DeploymentCapabilities.

Global view across pane widths

Pass 2 runs once with PaneWidthDomain::Complete and no deadline. Its memo contains every pane width any round would add. Stage 2 and Stage 3 run on that same memo, so ids match across sections. Stage 3 runs until the solver finishes; --run-until stage2 skips it.

To stop early, the CLI calls the stages itself and does not change run_planning, because the pane-width round removal will rewrite run.rs later. #1169 moves the stop point into run_planning after that.

Removed flags

--example (its workloads become workloads/planner-layering-*.json), --promql, --sql, --name, --max-error, --failure-probability, --accuracy-metric, --sample-interval-ms, --series-count, --rows-per-second, --rows-held, --cost-model, --cluster-*, --measured-operation-costs, --enforce-accuracy-guarantees (now the default), --exhaustive, --max-combinations, --price-enumerated, --milp-time-limit-s, --max-displayed, --no-memo, --max-memo-candidates, --memo-enumeration-limit, --max-enumerated, and #1159's --text and --enumerated. Memo enumeration is removed.

Repo changes

asap_planner is a [[bin]] in crates/devtools and replaces stage_pipeline.
show_logical_dag is deleted; --run-until stage0 covers it.
feat(devtools): stage_pipeline --text prints every planner stage's output as text #1159's text printer (planning_stages_text.rs, the node_label move) is brought into this branch, and feat(devtools): stage_pipeline --text prints every planner stage's output as text #1159 is closed.
Every stage_pipeline caller moves to asap_planner: tools/dag-viewer/server.py (the query box writes a temporary workload JSON; the examples use the committed workload files; no E<n> lists), test_server.py, test_viewer.py, tools/validate_joint_workloads.py, CI, and the docs.

Acceptance tests

For each --run-until value, the text output contains exactly the sections up to that stage.
For a 5m quantile query every 60s, --run-until pass2 lists pane candidates for every width that divides 60s, not only the seed width.
With --run-until stage3, every candidate id in Stage 3's selection appears in the Stage 2 section.
--format json --run-until pass2 has Stage 2 and Stage 3 as null; the stage3 document passes test_viewer.py.
A missing --run-until, or a removed flag, exits with status 2 and prints the usage text.
test_server.py drives asap_planner with the new arguments.

Follow-ups

asap_planner --view: open the Stage Viewer on the result #1168: --view, which opens the Stage Viewer on the result.
Move asap_planner's stop-after-stage into run_planning #1169: move the stop-after-stage logic into run_planning once the pane-width rounds are removed.

feat(devtools): asap_planner runs the stages up to --run-until and pr…

feat(dag-viewer): plan through asap_planner; drop committed documents…

docs: asap_planner user guide; rename stage_pipeline across the docs (#…

feat(devtools): asap_planner — one planner CLI that runs the stages u…

Navigation Menu

Repository navigation

One planner CLI: run stages up to a chosen point, print as JSON or text #1161

Goal

Problem

Agreed scope

Command

Global view across pane widths

Removed flags

Repo changes

Acceptance tests

Follow-ups

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

One planner CLI: run stages up to a chosen point, print as JSON or text #1161

Description

Goal

Problem

Activity

milindsrivastava1997 commented on Nov 2, 2026

Agreed scope

Command

Global view across pane widths

Removed flags

Repo changes

Acceptance tests

Follow-ups

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions