feat(asap-aware-mapping): generalize summary/CSE selection into a ReplacementStrategy trait

[zzylol]

Closes #251, #252, #257, #266. Part of #33.

Why

The pre-ASAP → post-ASAP binding decision (which sketch, if any, realizes an AggIntent) used to commit to exactly one answer per node, ranked by a cost model — right for executing a query, but it throws away every alternative the cost model didn't pick. Nothing downstream (a future search, a reporting view, a human comparing options) could ever see what else was possible.

We need the opposite shape: every semantically valid alternative, at every relevant spot in the plan, kept — not collapsed early — with real costs attached, so a downstream consumer can make its own tradeoff instead of inheriting one this crate already baked in. That single requirement is what every feature below exists to satisfy, at three different scopes (one target, a whole workload, and a human trying to understand either).

What (features, and why each one)

1. Core replacement vocabulary — TargetSubDAG, Replacement, ReplacementSubDAG, ReplacementStrategy.
   Why: needs a name for "a candidate site" and "a candidate answer" that's exhaustive by contract, so any future optimization rule plugs into the same shape instead of inventing its own one-off return type.

2. Two concrete strategies — SketchAlgorithmStrategy (every valid summary realization for one AggIntent) and SharedSubtreeStrategy (build-once-and-share vs. build-independently, at a CSE-detected shared subtree).
   Why: the two decisions this crate actually has today — which sketch, and whether to share — need one real implementation each to prove the ReplacementStrategy contract is usable, not just designed on paper.

3. CostModel::estimate_cost — a new hook returning a real f64 per candidate.
   Why: the existing hooks (rank_candidates, cse_share_decision) only ever produce an order or a decision — enough to rank, not enough for a consumer that wants to show "candidate A ≈ 3.0, candidate B ≈ 1.0" next to each other.

4. PlanSpace / MemoGroup / RankedGroup / search_workload — the same "generate, never prune" contract extended from one target to a whole workload, without enumerating 2^N fully-copied plans for N independently-choosable sites.
   Why: a caller with one TargetSubDAG already in hand can use ReplacementStrategy directly, but nothing discovered candidate sites across a whole workload, or represented their combined space compactly. Without this, extending "keep every candidate" to workload scale would mean either literally enumerating 2^N copied plans (infeasible past a handful of sites) or quietly dropping candidates to keep it tractable — the same trap that made a premature-commitment bind.rs tempting in the first place.

5. Sketch type restructuring — SketchKind split into family → kind → algorithm (SketchKind::Quantile(SketchAlgorithm, SketchParams), etc.), SketchFamilyStrategy → SketchAlgorithmStrategy.
   Why: the old flat SketchKind conflated two different questions — "what kind of summary is this" (quantile, cardinality, frequency, top-k) and "which concrete algorithm realizes it" (Kll, DDSketch, Hll, …) — into one enum. That's fine as long as nothing ever needs to reason about one axis without the other, but (4) does: ranking algorithms within an already-fixed kind, or asking "does this target's kind match a required one" regardless of algorithm, both need the two questions answered separately. A flat enum can't express "same kind, different algorithm" as a first-class fact; the nested type can.

6. explanation.rs — explain_replacements/explain_replacements_with, returning ReplacementExplanation { kind, location, reason, node_hash } for anything in a PlanSpace beyond the trivial realization.
   Why: a PlanSpace is shaped for ranking — raw Rc pointers, every candidate's full construction detail — not for a human or a UI to read. Something has to translate "this MemoGroup has a non-trivial candidate" into a sentence, without re-deriving why that candidate is valid (a strategy already said so, in its rationale) or inventing a second, competing explanation. It isn't answering "is X applicable, yes or no" — every target already has some answer, trivial or not — it's explaining why a non-trivial replacement exists where one does.

7. dag_export / tools/dag-viewer integration — the devtools export binary now calls explain_replacements and attaches matching explanations to graph nodes by node_hash; the viewer badges and displays them.
   Why: (6) needed a real consumer to prove it's actually useful, not just correctly shaped — this is that consumer, and it's the concrete case that motivated cutting scope in (8) below.

8. Scope cut: no workload-level materialization — bind.rs (the old "keep the first candidate, memoize by Rc identity across a workload" step) is deleted, not kept alongside PlanSpace.
   Why: building (7) surfaced the actual question — does this crate ever need to commit to one final, physically-shared answer? Picking one still requires knowing where it'll be placed, which only a downstream deployment can see. Keeping bind.rs around with no real caller of that specific commitment was speculative scope, not an MVP need.

How (design per component)

Core vocabulary — generate/choose, never mixed. ReplacementStrategy::replacements() must return every valid candidate; a CostModel may only reorder or attach a number, never remove one. This is enforced by convention plus tests (e.g. an exact AccuracyTarget correctly yields exactly one candidate — because a sketch is never valid there, not because a cost model filtered it out). Everything else in this PR is this rule applied at different scopes.

SketchAlgorithmStrategy looks up every summary candidate an AggIntent's own type allows (a static table, not a search — e.g. quantile → {Kll, DDSketch}), sizes each one via CostModel::size_params/rank_candidates, and constructs its SummaryNode directly in the same pass — deciding and constructing were always one step, so there's no separate bridge function between them (an earlier implementation.rs module that was that bridge is merged in here). Child nodes are bound independently via a small internal helper, so a choice at one target never leaks into a nested aggregate's own choice.

SharedSubtreeStrategy has zero cost logic in it — it always returns both the share and recompute-independently candidates for any target with consumer_count >= 2. Whether sharing is worth it is answered later, only by CostModel::cse_share_decision, kept as one comparison rather than a second competing implementation.

PlanSpace is a Cascades/Volcano-style MEMO: one MemoGroup per distinct TargetSubDAG (keyed by Rc pointer identity), never a flat plan list.

// One MemoGroup per distinct TargetSubDAG in the whole workload —
// never a flat list of fully-materialized plans (that's 2^N for N sites).
pub struct MemoGroup {
    pub target: Rc<QueryExpr>,
    pub consumer_count: usize,
    pub candidates: Vec<ReplacementSubDAG>,  // every alternative, unranked
}

pub struct RankedGroup<'a> {
    pub target: &'a Rc<QueryExpr>,
    pub consumer_count: usize,
    pub candidates: Vec<&'a ReplacementSubDAG>,  // same candidates, ranked
    pub costs: Vec<f64>,                         // costs[i] <-> candidates[i]
}

search_workload_with runs the pre-ASAP CSE pass once, discovers every target across every root's whole DAG (a shared node three levels under an unshared Filter is exactly as real a site as a shared root — root-level-only discovery would miss it), then asks every registered strategy to a fixpoint (a documented iteration cap catches a hypothetically ill-behaved future strategy; both shipped strategies converge in one round). PlanSpace::cost_sorted dispatches each group by candidate shape — an all-Rewrite pair goes to cse_share_decision, an all-Summary sketch group goes to rank_candidates, everything also gets estimate_cost — rather than inventing one comparison that tries to cover every shape at once, and returns RankedGroups: same candidate count in as out, just ranked and costed.

explanation.rs does no new decision-making at all: for each MemoGroup with something beyond the trivial candidate, it emits one ReplacementExplanation whose reason is literally the matching candidate's own rationale string. node_hash is structural_hash on the target — the same function dag_export::DagNode::hash already computes for the identical subtree — so a downstream consumer can attach the two by exact match instead of guessing from text.

dag_export stays a strictly lower crate than asap-aware-mapping (asap_types::dag_export::DagNode gained a generic notes: Vec<DagNote> field it never populates itself); the devtools binary, which already depends on both, does the actual correlation after the fact. This keeps the layering invariant (dependencies point one way) intact while still letting a higher layer annotate a lower layer's export.

Architecture

flowchart TB
  classDef gen fill:#2b6f6a,color:#fff,stroke:none
  classDef choose fill:#ad7127,color:#fff,stroke:none
  classDef report fill:#5b6b78,color:#fff,stroke:none
  classDef store stroke-dasharray: 3 3

  TSD["TargetSubDAG"]:::gen --> RS{{"ReplacementStrategy"}}:::gen
  RS --> SAS["SketchAlgorithmStrategy"]:::gen
  RS --> SSS["SharedSubtreeStrategy\n(no cost logic at all)"]:::gen

  CM(["CostModel\nrank_candidates / size_params / estimate_cost / cse_share_decision"]):::choose
  CM -. sizes + orders while generating .-> SAS

  SAS --> CAND["ReplacementSubDAG candidates\n(unranked, nothing pruned)"]
  SSS --> CAND
  CAND --> PS["PlanSpace / MemoGroup\none group per TargetSubDAG, whole workload"]:::store

  PS --> DISPATCH{"cost_sorted\ndispatch by candidate shape"}:::choose
  DISPATCH -- "all Rewrite" --> CM
  DISPATCH -- "all Summary" --> CM
  DISPATCH -- "every candidate" --> CM
  DISPATCH --> RANKED["RankedGroup\nranked + real cost per candidate"]:::choose

  RANKED --> EXP["explanation.rs\nexplain_replacements"]:::report
  EXP --> DAGEXP["dag_export\n(node_hash match)"]:::report
  DAGEXP --> VIEWER(["tools/dag-viewer\nbadge + click-to-explain"]):::report

Loading

Deliberately absent from this diagram: any node that commits to one final, physically-shared answer for a whole workload. That step — bind::implement_workload in an earlier version of this crate — is removed; picking a candidate and placing it is a downstream deployment's call this crate has no visibility into.

Output

A real, captured run (not illustrative numbers) — two independently-built, structurally identical Sum by (job) queries and one Quantile(0.99) by (job) query on a different metric, through search_workload + DefaultCostModel:

--- shared target: consumer_count=2, candidates=3 ---
  [0] cost=3.000  exact Sum accumulator
  [1] cost=1.000  build once and share            <- ranks first
  [2] cost=4.000  build independently

--- p99 target: consumer_count=1, candidates=2 ---
  [0] cost=3.000  Kll sketch
  [1] cost=3.000  DDSketch sketch

explain_replacements:
  CommonSubexpressionReuse @ root "dash_a", root "dash_b"
  SketchApproximation      @ root "p99"

And real dag_export JSON, showing an explain_replacements finding attached to a graph node by hash:

"notes": [
  {
    "kind": "SketchApproximation",
    "reason": "count realizes as a Cms sketch — one of summary_candidates' alternatives for this intent (...); count realizes as a CountSketch sketch — one of summary_candidates' alternatives for this intent (...)"
  }
]

A fuller architecture map + this same worked example, interactive: https://claude.ai/code/artifact/f16b39a4-9d50-4e33-b1dc-54238ae766ae

Known limitation — accuracy is per-target only, not reconciled across the workload

Candidate sizing (accuracy_target/accuracy_budget/default_size_params) always comes from the one AggIntent a TargetSubDAG wraps — correct at single-target granularity. But AggIntent derives PartialEq over every field, including accuracy, so pre-ASAP CSE only ever merges two subtrees onto one shared Rc when their AccuracyTargets match exactly. Two otherwise-identical aggregates that differ only in accuracy (e.g. quantile(0.99, x) at epsilon=0.01 vs. the same query at epsilon=0.05) are simply never recognized as shareable — SharedSubtreeStrategy never even sees them as one target, so this crate never proposes "build once at the tighter bound, serve both." Tracked as future work: #273.

Checks

cargo build --workspace --all-targets, cargo test --workspace, cargo fmt --all -- --check, and cargo clippy --workspace --all-targets --all-features -- -D warnings all pass clean. tools/dag-viewer's test_render.py (12/12) also passes.

🤖 Generated with Claude Code

[milindsrivastava1997]

@zzylol Can you create dev docs for this? This is going to be a critical piece of code since anyone contributing to ASAPPlanner probably needs to understand the data structures and traits here.

[milindsrivastava1997]

@zzylol Can you create dev docs for this? This is going to be a critical piece of code since anyone contributing to ASAPPlanner probably needs to understand the data structures and traits here.

[zzylol]

@milindsrivastava1997 Added a dev guide: docs/ASAP-aware-mapping-developer-guide.md

Covers how to actually extend this code: the ReplacementStrategy/CostModel/Matcher contracts, worked examples (SketchFamilyStrategy, SharedSubtreeStrategy, ForceSketchKind), common mistakes, a testing checklist, and an extension-point lookup table.

🤖 Generated with Claude Code

[milindsrivastava1997]

High-level comments.

• Remove section 19. "If there is one rule to keep in mind when extending this layer" is applicable for human attention, not agent(?)
• Sec 16-18 is awesome and very helpful. We should do this for other efforts too.
• Glossary would help. Idk what boundary and binder/binding mean.

See more detailed comments inline