feat(dag-viewer): show planner cost and benefit annotations

crates/types/src/lib.rs

@@ -19,6 +19,7 @@
 //!   runtime's readout path can call directly — see that module's docs
 //!   for the planning-time/execution-time boundary and why it's unwired
 //!   today.
+pub mod cost;
 pub mod dag_export;
 pub mod post_asap;
 pub mod pre_asap;

tools/dag-viewer/README.md

@@ -13,6 +13,11 @@ The viewer has one visualization mode: **Pre/Post-ASAP**.
   target operation derives its output schema in the details panel.
 - The details panel shows the selected workload's bound table/metric schemas
   and can be resized by dragging its left edge.
+- A post-ASAP node whose winning decision carries a cost/benefit annotation
+  shows a concise `▼NN%`/`▲NN%` badge next to its label; the sidebar and the
+  workload-scope summary show the full baseline/selected/benefit breakdown,
+  with units and provenance, wherever the export provides one — see "Cost/
+  benefit annotations" below.
 
 There are no separate Single, Compare, or Union modes.
 
@@ -52,12 +57,20 @@ shell command.
 ```sh
 cargo run -p asap-devtools --bin dag_export -- \
   --post-asap --epsilon 0.01 \
+  --planner-cost-json "$PLANNER_PHYSICAL_EVIDENCE" \
   --sql "SELECT service, COUNT(*) FROM metrics GROUP BY service" --name q1 \
   > /tmp/dag.json
 ```
 
-Load the JSON with the page's file picker. A post-ASAP visualization requires
-`--post-asap`; ordinary exports intentionally omit `post_graph`.
+Load the JSON with the page's file picker. `--planner-cost-json` is a complete
+physical-evidence document: calibration plus target records containing the
+exact target `QueryExpr`, comparison scope, exact logical query nodes with
+`PhysicalNodeEvidence`, and exact exported replacement DAGs with their bound
+`PhysicalDag`. Matching uses full structural equality, never a hash or strategy
+name. Duplicate, conflicting, or missing records fail closed. Without this
+document, `--post-asap` exports the raw graph only. The old
+`--analytical-cost-json` spelling accepts the new document as an alias; its old
+compact aggregation payload is rejected with a migration error.
 
 The viewer also accepts the JSON produced by
 `export_summary_maintenance_plan`. It renders the materialized summary DAG as
@@ -90,8 +103,11 @@ a selected replacement directly contains:
     "strategy": "SketchAlgorithmStrategy",
     "rationale": "count realizes as a Cms sketch",
     "rank": 0,
-    "cost": 3.0,
-    "role": "replacement_root"
+    "cost": 5.64051088,
+    "role": "replacement_root",
+    "baseline_cost": { "value": 164.000000016, "unit": "CostUnits", "source": "Modeled", "model_version": "analytical-resource-v1+demo-calibration-v1" },
+    "selected_cost": { "value": 5.64051088, "unit": "CostUnits", "source": "Modeled", "baseline": {"kind": "PreAsapRecomputation"}, "delta": 158.359489136, "benefit_ratio": 0.965606640979 },
+    "benefit": { "value": 158.359489136, "unit": "CostUnits", "source": "Modeled", "baseline": {"kind": "PreAsapRecomputation"}, "benefit_ratio": 0.965606640979 }
   }
 }
 ```
@@ -106,6 +122,32 @@ filter predicates, projections, sources, summary families, and readout
 queries. Category icons are deliberately omitted so they cannot be confused
 with IR text.
 
+### Cost/benefit annotations (issue #286)
+
+`decision.baseline_cost` / `.selected_cost` / `.benefit` are structured
+[`CostAnnotation`](../../crates/types/src/cost.rs)s: `value` + `unit` +
+`source` (`Modeled` / `Measured` / `Unavailable`), optionally `baseline` +
+`delta` + `benefit_ratio`, and `model_version`/`benchmark_id`/`inputs` for
+provenance. A missing `value` (`source: "Unavailable"`) always renders as
+**Not estimated** — the viewer never fabricates a number. A complete physical
+planner export keeps CPU operations, peak memory, scan bytes, coefficients,
+and workload statistics in `inputs`. Without complete physical evidence, the
+annotation is `Unavailable`; structural node counts are never substituted.
+See the [analytical model design](../../docs/design_docs/asap-aware-mapping/analytical-resource-cost.md).
+
+The same three fields also appear on `TargetReplacement`
+(replacement-region baseline/selected/benefit), `NamedGraph.workload_cost` /
+`WorkloadGraph.workload_cost` (whole selected-workload cost/benefit, shared
+nodes counted once via `decision.id` dedup), and `DagGraph.edge_annotations`
+(materialization/read cost on an edge into a genuine DAG merge point — never
+a guessed multi-hop path cost). The sidebar shows the full breakdown
+(value, unit, provenance, baseline, ratio, inputs) on node/edge click and in
+the workload-scope summary; a post-ASAP node with a costed decision also
+gets a concise on-graph `▼NN%`/`▲NN%` badge next to its label.
+
+All of this is additive and optional: an export with none of these fields
+(anything produced before issue #286) renders exactly as before.
+
 ## Tests
 
 ```sh