feat(dag-viewer): readable memo (drill-down, Stage 2 grid, plan-only and pruned filters), inputs/outputs layout, Plan Viewer rename (#1262)

README.md

@@ -6,7 +6,7 @@ ASAPPlanner turns SQL, PromQL, and MetricsQL query workloads into legal candidat
 
 - New to the repository? Read the [planner pipeline](docs/design_docs/concepts/planner-pipeline.md), then the [glossary](docs/design_docs/concepts/glossary.md).
 - Want to run a query? Follow [Run and inspect a query](docs/user_guide_docs/run-a-query.md).
-- Want to see how a workload is planned, stage by stage? Use the [Stage Viewer](docs/user_guide_docs/stage-viewer.md).
+- Want to see how a workload is planned, stage by stage? Use the [Plan Viewer](docs/user_guide_docs/plan-viewer.md).
 - Embedding Planner? Use the [library API guide](docs/develop_docs/library-api.md).
 - Extending Planner? Read the [planning stages design](docs/design_docs/proposals/planner-layering.md), then the [ASAP-aware mapping architecture](docs/develop_docs/asap-aware-mapping-architecture.md), which maps each stage to its code, then [extend ASAP-aware mapping](docs/develop_docs/extend-asap-aware-mapping.md).
 - Evaluating a design? Browse the [design documentation](docs/design_docs/README.md), [developer documentation](docs/develop_docs/README.md), and [user guides](docs/user_guide_docs/README.md).

crates/devtools/src/bin/asap_planner.rs

@@ -8,7 +8,7 @@
 // `--run-until` (`stage0`, `stage1_pass1`, `stage1_pass2`, `stage2` or
 // `stage3`) and writes each stage's output, as text (`--format text`, the default;
 // `asap_devtools::planning_stages_text`) or as an `asap-stage-pipeline/v2`
-// document for the Stage Viewer (`--format json`), to `--out` or standard
+// document for the Plan Viewer (`--format json`), to `--out` or standard
 // output. The text is terse by default (a legend per stage, folded θ
 // variants, producer ids per input, pruned counts per cause); `--verbose`
 // prints every candidate, edge with its reason, group's properties and

docs/README.md

@@ -11,7 +11,7 @@ Choose the path that matches what you need to do.
 
 ## Run or inspect a query
 
-Follow [Run and inspect a query](user_guide_docs/run-a-query.md). To see how the planner plans a workload stage by stage, and why it selects its plan, use [the Stage Viewer](user_guide_docs/stage-viewer.md).
+Follow [Run and inspect a query](user_guide_docs/run-a-query.md). To see how the planner plans a workload stage by stage, and why it selects its plan, use [the Plan Viewer](user_guide_docs/plan-viewer.md).
 
 ## Embed the library
 

docs/design_docs/architecture/README.md

@@ -51,7 +51,7 @@ target.
 | Plan selection | `stage3-plan-selection` | Stage 3: accuracy and latency checks, costing and selection; the planning models and the Stage 1 to Stage 3 driver |
 | Planner facade | `planner` | `e2e_plan`: Stage 0 followed by Stages 1–3 |
 | Executor | `executor` | Stage 4: runs a `PhysicalASAPDAG` over `asap_sketchlib` summaries; no stage crate depends on it |
-| Developer inspection | `devtools` | `asap_planner` and the Stage Viewer documents, corpus coverage tools |
+| Developer inspection | `devtools` | `asap_planner` and the Plan Viewer documents, corpus coverage tools |
 | End-to-end validation | `integration-tests` | Verify behavior across frontends, stages and execution |
 
 ## Inputs and outputs

docs/design_docs/architecture/input-output-workflow.md

@@ -304,7 +304,7 @@ PlanningWorkload + frontend dependencies + PlanningModels
 |---|---|---|
 | Plan a workload end to end | `asap_planner::e2e_plan` | `PlanOutput` |
 | Plan already-lowered roots and inspect every stage | `asap_planner::run_planning` | `PlanningRun`, whose `selection` is the `Selection` |
-| Inspect a workload's stages as a document | `asap_planner` (devtools) | The stage document the [Stage Viewer](../../user_guide_docs/stage-viewer.md) shows |
+| Inspect a workload's stages as a document | `asap_planner` (devtools) | The stage document the [Plan Viewer](../../user_guide_docs/plan-viewer.md) shows |
 
 The integration associates each lowered root, by its position, with its
 workload entry (accuracy target, latency bound, recurrence). See the

docs/design_docs/proposals/planner-layering-example2-acceptance.md

@@ -159,5 +159,5 @@ strictest size.
 is the `flows` table of `tools/dag-viewer/workloads/planner-layering/tables.json`,
 plans the SQL workload with the `flows(ts, src_ip)` catalog (with
 `--ignore-accuracy-guarantees`, none of the plans below is rejected for its
-guarantee). The stage viewer has no tab for it; open the
+guarantee). The plan viewer has no tab for it; open the
 document with **Open stage document…**.

docs/develop_docs/extend-asap-aware-mapping.md

@@ -105,7 +105,7 @@ tests in `planner_layering_example4.rs`.
   a stage function takes only the field it reads (Stage 2 takes
   `query_time_results_retained: bool`, not the whole struct).
 - Expose it in `asap_planner` and in the
-  [Stage Viewer guide](../user_guide_docs/stage-viewer.md).
+  [Plan Viewer guide](../user_guide_docs/plan-viewer.md).
 
 Tests: a Stage 3 unit test that the check rejects exactly the candidates it
 should, and a `crates/devtools/tests/asap_planner.rs` test for the flag.

docs/develop_docs/library-api.md

@@ -295,7 +295,7 @@ let models = PlanningModels::builtin().with_cost_inputs(&settings);
 
 The `asap_planner` devtool runs the same stages and writes every stage's
 output as text or, with `--format json`, as one JSON document; see the
-[Stage Viewer guide](../user_guide_docs/stage-viewer.md).
+[Plan Viewer guide](../user_guide_docs/plan-viewer.md).
 
 ## Workload inputs and defaults
 

docs/develop_docs/replacement-explanations.md

@@ -5,7 +5,7 @@
 > and why each candidate was pruned or rejected, is now in the stages'
 > output: Pass 1's pruned candidates with their `PruneReason`, Stage 2's
 > pruned candidates, and Stage 3's `Rejection` reasons, all written by
-> `asap_planner` (see the [Stage Viewer guide](../user_guide_docs/stage-viewer.md)).
+> `asap_planner` (see the [Plan Viewer guide](../user_guide_docs/plan-viewer.md)).
 
 ASAP-aware mapping should make its discovered opportunities visible to users and other components.
 

docs/user_guide_docs/README.md

@@ -5,4 +5,4 @@ result.
 
 - [Run and inspect a query](run-a-query.md)
 - [Plan a workload with asap_planner](asap-planner.md)
-- [See how ASAPPlanner plans a workload: the Stage Viewer](stage-viewer.md)
+- [See how ASAPPlanner plans a workload: the Plan Viewer](plan-viewer.md)

docs/user_guide_docs/asap-planner.md

@@ -2,7 +2,7 @@
 
 `asap_planner` runs the planner's stages on a workload, up to the stage you
 choose, and prints what each stage produced: as text, or as a JSON document
-for the [Stage Viewer](stage-viewer.md). It reports candidates, selection,
+for the [Plan Viewer](plan-viewer.md). It reports candidates, selection,
 modeled costs and accuracy checks; it does not deploy or execute the plan.
 
 ## Build and run
@@ -100,7 +100,7 @@ SQL examples. To try a single query, write a one-query workload file.
 ## Inspect the result
 
 With `--format json`, open the document in the
-[Stage Viewer](stage-viewer.md), or read Stage 3 directly:
+[Plan Viewer](plan-viewer.md), or read Stage 3 directly:
 
 ```sh
 cargo run --release -p asap-devtools --bin asap_planner -- \

docs/user_guide_docs/stage-viewer.md → docs/user_guide_docs/plan-viewer.md

@@ -1,6 +1,6 @@
-# See how ASAPPlanner plans a workload: the Stage Viewer
+# See how ASAPPlanner plans a workload: the Plan Viewer
 
-The Stage Viewer is a web page that shows what ASAPPlanner does with one
+The Plan Viewer is a web page that shows what ASAPPlanner does with one
 workload at each
 [planning stage](../design_docs/proposals/planner-layering.md#asapplanner-system-overview-planning-stages),
 and which plan it selects. It reads one JSON document per workload, written

docs/user_guide_docs/run-a-query.md

@@ -14,7 +14,7 @@ tool on first use.
 
 | Command (`cargo run -p asap-devtools --bin … -- …`) | Input / options | Result |
 | --- | --- | --- |
-| `asap_planner --workload <file> --run-until <stage>` | `PlanningWorkload` JSON files | Runs the planner's stages up to `<stage>` and prints each stage's output as text, or with `--format json` as the document the [Stage Viewer](stage-viewer.md) shows |
+| `asap_planner --workload <file> --run-until <stage>` | `PlanningWorkload` JSON files | Runs the planner's stages up to `<stage>` and prints each stage's output as text, or with `--format json` as the document the [Plan Viewer](plan-viewer.md) shows |
 | `convert_rqe_atomic_costs <rqe_atomic_costs.json> <out.json>` | sketch-bench's per-operation cost table | Writes a measured table to set as `measured_operation_costs` in an `asap_planner --cost-inputs` file; skipped rows are listed on stderr |
 | `analyze_corpora --corpora --sample-interval-ms 1000 --out-dir <dir>` | Repository PromQL corpora, output directory | Writes successful/error IR dumps and summary reports |
 | `analyze_corpora --sql-corpora --out-dir <dir>` | Repository SQL corpora, output directory | Writes SQL corpus reports |
@@ -49,7 +49,7 @@ the selected physical candidates, the plan's `cost_per_second` with each
 node's charge, each query's accepted accuracy, and the search status
 (`Optimal` when the plan is proven the cheapest). For this example the
 selected plan is exact for both queries. Add `--format json --out plan.json`
-and open the document in the [Stage Viewer](stage-viewer.md) to see every
+and open the document in the [Plan Viewer](plan-viewer.md) to see every
 stage.
 
 ## Inspect a query's logical DAG

tools/dag-viewer/README.md

@@ -1,4 +1,4 @@
-# ASAPPlanner Stage Viewer
+# ASAPPlanner Plan Viewer
 
 A browser view of what the planner does with one workload, read from an
 `asap-stage-pipeline/v2` document written by the `asap_planner` devtool
@@ -31,24 +31,27 @@ To run it, see [RUNNING.md](RUNNING.md).
   (deployment capabilities, cost model, accuracy guarantees). Without the
   server, the rows say they need it. `#workload-sets` in the URL opens the
   section.
-- **Query workload** with each query's accuracy, latency, recurrence,
-  predictability and range evaluation, and a line that counts the
-  candidates at each stage: the Pass 2 memo's logical candidates and how
+- **Planner inputs** (blue bar), what the planner was given:
+  - **Query workload** with each query's accuracy (`error metric not set` when
+    the workload names no error metric), latency, recurrence,
+    predictability and range evaluation;
+  - **Data workload**: the arrival and one row per declared source with
+    exactly the facts it declares (series count, metric type, non-negative
+    values, sample interval, stream norms, distinct bound, distinct values
+    per label, distinct values per label set) and the queries whose text
+    names it;
+  - **Deployment and planner settings**: the deployment capabilities (raw
+    data and query-time results retained or not, the summaries it
+    supports), whether accuracy guarantees were enforced or ignored, and
+    the cost model Stage 3 priced the plan with (`cost.source`).
+- **Planner output** (green bar), everything below: a line that counts the
+  candidates at each stage (the Pass 2 memo's logical candidates and how
   many Pass 2 pruned, the physical candidates and how many Stage 2 and
-  Stage 3 pruned, and whether a plan was selected.
-- **Data workload** beside it: the arrival and one row per declared source
-  with exactly the facts it declares (series count, metric type,
-  non-negative values, sample interval, stream norms, distinct bound,
-  distinct values per label, distinct values per label set) and the queries
-  whose text names it, plus the deployment capabilities the run planned
-  with.
-- **Stage 3 · plan selection**: one row, the selected plan with its cost
-  per second and the accuracy Stage 3 accepted per query, or why no plan
-  was selected. The header says why Stage 1 or Stage 2 failed when it did,
-  shows the selection's warnings, says whether accuracy guarantees were
-  enforced or ignored, and names the search with its MILP's size and times.
-- **Two lanes**, stacked top to bottom so each is as wide as the page:
-  Stage 0 and Stage 3's plan, with each plan node's timing (also its fill:
+  Stage 3 pruned) and a line with Stage 3's outcome (plan selected, or why
+  not), why Stage 1 or Stage 2 failed when it did, the selection's
+  warnings, and the search with its MILP's size and times.
+- **Two lanes**, each as wide as the page: **Input**, the queries as one
+  logical DAG (Stage 0's output, drawn with the inputs), and Stage 3's plan, with each plan node's timing (also its fill:
   green at ingestion time, orange at query time) and Stage 3 cost (`× n`
   when a node that is not materialized is computed once per consumer).
   Each lane is the whole workload's DAG, so a node shared by several queries
@@ -68,13 +71,27 @@ To run it, see [RUNNING.md](RUNNING.md).
   is not installable says why instead. Clicking a row selects its node in
   the plan lane.
 - **Memo**: the memo after each planner step, one tab per step (`Stage 0`,
-  `Stage 1, Pass 1`, `Stage 1, Pass 2`), opening on the last. Each memo
+  `Stage 1 · Pass 1`, `Stage 1 · Pass 2`), opening on the last. Each memo
   group is a box `G<id> · <label>` with its candidate count (and how many
   Pass 2 pruned) and the queries it is the root of; its candidates sit
   inside it, bordered by origin, marked `✚ new` when the step added them
-  and `✗ pruned` (dashed) when Pass 2 pruned them. A group with more than
-  12 candidates is drawn as one node per origin with its count; clicking a
-  count lists them. Each candidate box shows its parameters θ. On the last
+  and `✗ pruned` (dashed) when Pass 2 pruned them; those (and a group left
+  with none) are hidden until **show pruned candidates** is ticked; on the
+  last tab, **selected plan only** leaves just the candidates the plan uses
+  and their groups. A group with more than
+  12 candidates is split into counts by its first dimension that varies:
+  origin, sketch family, each θ field (e.g. `k`, `depth`, `width`), then
+  tumbling-window width. Clicking a count drills into it, splitting again
+  until at most 12 remain, which are then drawn one by one; the group's
+  label shows the path (`origin=Pass1 › depth=5`), clicking the group goes
+  back one level, and the group's details offer the other varying
+  dimensions to split by instead. An arrow goes from a candidate (or count) to
+  each group it reads, or once from the group when all its candidates read the
+  same groups; a line above the drawing says how to read it. Each candidate box shows its parameters θ and, on the Pass 2 tab with **show Stage 2 variants** ticked (the default), a grid of
+  its Stage 2 physical variants: rows by timing (ingest, query), columns by
+  lifetime (not kept, one run, across runs), filled green or orange when one
+  is there, crossed when Stage 2 pruned it, outlined dark when the plan uses
+  it; the candidate's details show the same grid with the `C<id>`s. On the last
   tab the selected plan's candidates are filled green with `✓ selected` (a
   group may have several, one per execution context). Clicking a group
   shows its operator, children, parents, queries, its candidates with θ,
@@ -89,6 +106,10 @@ To run it, see [RUNNING.md](RUNNING.md).
   physical edges per input (`✓ C<producer>`, or `✗ C<producer>: α^phys =
   0: …`; `selected` when the plan uses it), and the physical candidates of
   it Stage 2 and Stage 3 pruned.
+- **Theme**: light by default; **Dark theme** (top right) switches it and is remembered
+  in the browser.
+- **Zoom**: each graph has `+`, `−` and `⌂` (fit the whole graph) buttons
+  in its top right corner; a small graph is drawn at most at 1.3×.
 - **Details**: click a node for its operator, the queries reaching it,
   timing, lifetime, output schema, guarantee and Stage 3 cost; click
   an edge for its schema and data state.