feat(dag-viewer): redesign the viewer around the stage pipeline

[zzylol]

Stack: #574 → #620 → #618 → #621 → #627 → #625 → #628 → #632 → #634 → #616 → #617 → #622 → #624 → #629 → #630 → #631 → #633 → #635 → #636 → #637
Stack: #605 → #607 → #608 → #609 → #610 → #612 → #613 → this PR

Rebased on main d4869a7 (DF 54). At this head fmt, clippy -D warnings and cargo test --workspace pass (1668 passed, 0 failed, 21 ignored).

Why

With #509's stages and #572's crates, there are no pre-ASAP and post-ASAP DAGs any more. What the planner produces is one asap-stage-pipeline/v1 document per workload:

• Stage 0: the logical DAG.
• Stage 1: the logical ASAP candidates.
• Stage 2: the physical candidates.
• Stage 3: costs, rejections and the selection.

The viewer is redesigned around that document, using the layout of the published Stage Viewer.

The page

• Example tabs for the six docs: propose workload-wide planning, summary sharing, and materialization #509 examples (1, 2, 3a, 3b, 4a, 4b). Each has a short explanation of the workload and why its plan wins, and #example4b in the URL opens that example.

• Workload queries with their accuracy, latency and recurrence.

• Deployment inputs (Show deployment inputs in the stage document and viewers #610):

  • the exact aggregates;
  • each sketch with the estimates it can be read for;
  • ingestion-time maintenance;
  • the memory budget;
  • raw-data retention;
  • the cost model with its calibration constants;
  • the accuracy model.

• Stage 3 · plans by cost: every plan, cheapest first, marked selected, valid but costlier, or invalid with the reason. When a document carries only the cheapest plans (devtools: stage_pipeline examples planner-layering-2 and 4b #613's shown_of), the list says "showing 64 of 486 plans, cheapest first; Stage 3 priced 486 and selected among all of them".

• Three DAG lanes, one cytoscape instance each:

  • Stage 0;
  • the chosen Stage 1 candidate;
  • the chosen Stage 2 candidate, with each node's timing and Stage 3 cost.

  Summary builds print their configuration (for example CmsWithHeap · depth 7 · heap 100 · width 272) and whether there is one instance per group, one per series, or one shared instance.

• Details for a clicked node (operator, output schema, coverage, guarantee, cost) or edge (schema, data state).

• Open stage document…, drag and drop, or ?doc=<path> to load other documents.

• Query editor: plans PromQL queries, with an optional ε and δ and the sample interval, through /api/plan, which now runs stage_pipeline. SQL needs a catalog and is left for later.

Changes

• index.html and app.js replace viewer.js.

  • stages.js (validation, ranking, lane elements, labels) is reused as is.
  • node-style.js keeps only KIND_CATEGORY_JSON, which viewer_contract.rs checks, plus the three node groups (data source, relational, summary).

• examples.json lists the examples. server.py builds stage_pipeline, writes any missing documents into the git-ignored out/ directory (--regenerate rewrites them), and serves /api/plan.

• Removed:

  • the Pre/Post-ASAP view and WorkloadDAG loading;
  • render.py's standalone HTML;
  • planner-ui.js;
  • the dag_export sample and the post-ASAP fixture;
  • the screenshots.

  The dag_export binary itself stays for a later cleanup PR.

• README.md, RUNNING.md and the user guide describe the Stage Viewer.

• test_viewer.py replaces test_render.py. It has:

  • the stage-document tests;
  • checks that the page's scripts and element ids line up;
  • the example manifest against stage_pipeline's examples;
  • the server's request checks;
  • app.js loading documents against a stub DOM in V8.

Test plan

• python3 -m unittest test_viewer in tools/dag-viewer, with py-mini-racer==0.6.0: 24 tests, OK (without it, 17 JS tests are skipped).
• cargo test -p asap-devtools: 45 passed, including viewer_contract and the Example 1 fixture check.
• server.py serves the page and all six example documents. /api/plan with a top-k query at ε=0.01, δ=0.001 returns a valid document; δ without ε returns 400.
• All six example documents load through app.js, selecting P82, P86, P365, P2, P365 and P4-m1.
• Not checked in a real browser in CI. The published Stage Viewer artifact runs the same page code.

🤖 Generated with Claude Code