docs(planner): describe cost-free Stage 1 candidate generation

Update the developer docs and the `CostModel` trait doc: strategies take no
cost model, sketch sizing is analytical, extension intents stay
pass-through, and the cost model is consulted only at selection.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: zzylol

crates/asap-aware-mapping/src/cost_model.rs

@@ -362,15 +362,14 @@ pub fn default_cse_shared_maintenance_cost(family: &FieldDataType) -> Cost {
     Cost(weight * UNIT)
 }
 
-/// Ranks the candidate sketch algorithms for one [`AggIntent`], best choice
-/// first.
+/// Selection-time preferences and costs over the candidates Stage 1
+/// generates.
 ///
 /// [`replacement::summary_candidates`] returns every algorithm that *can* answer an
 /// intent, in an arbitrary static preference order (issue #98's "one home"
-/// for the candidate set). A `CostModel` re-orders that list under real,
-/// deployment-specific cost knowledge this crate has no way to know about —
-/// `replacement::realizations_for_intent` constructs every candidate in the
-/// resulting order.
+/// for the candidate set), and candidate generation keeps that order. A
+/// `CostModel` re-orders the candidates when they are selected, under real,
+/// deployment-specific cost knowledge this crate has no way to know about.
 pub trait CostModel {
     /// Whether [`Self::candidate_cost`] prices a complete physical
     /// alternative, including its raw baseline, rather than a local

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

@@ -42,7 +42,9 @@ A strategy should answer:
 
 A cost model should answer:
 
-> Given valid choices, which choices are preferable, and how should they be parameterized?
+> Given valid choices, which choices are preferable?
+
+It is consulted only at selection time; sketch parameters come from the analytical estimators.
 
 Do not put cost-based pruning into a `ReplacementStrategy`. A strategy must enumerate every valid alternative, even when the default cost model clearly prefers one. See [Rule 2](extend-asap-aware-mapping.md#rule-2-enumerate-do-not-rank).
 
@@ -98,8 +100,6 @@ flowchart TB
     STRATEGY["ReplacementStrategy<br/>when a target matches, enumerate every legal replacement;<br/>implementations generate but do not choose"]:::generate
     CAND["ReplacementSubDAG candidates<br/>each contains a Subtree (summary or logical rewrite) or ExactComposition<br/>plus typed provenance and rationale;<br/>no alternative is removed solely on cost"]:::store
     TARGET -->|"try every registered strategy"| STRATEGY --> CAND
-    CM(["CostModel<br/>orders candidates and supplies<br/>deployment-specific parameters"]):::choose
-    CM -. "rank and parameterize; accuracy checks remain required" .-> STRATEGY
   end
 
   subgraph SEARCHSPACE[3. Store the workload-wide search space]
@@ -108,7 +108,9 @@ flowchart TB
   end
 
   subgraph RANKING[Optional ranked view]
+    CM(["CostModel<br/>selection-time preferences and costs"]):::choose
     SORT["CandidateLogicalASAPDAGs::cost_sorted<br/>use the CostModel to order each candidate set<br/>and cost every candidate"]:::choose
+    CM -.-> SORT
     RANKED["RankedTargetSubDAGCandidates<br/>the same candidates in preferred order,<br/>with costs aligned by index"]:::choose
     SPACE --> SORT -->|"reorder only; preserve every candidate"| RANKED
   end
@@ -193,9 +195,8 @@ capability and accuracy checks; supported algorithm applicability alone is not
 a result certificate.
 
 The complete `replacements()` result is the candidate set produced by one
-strategy for one target. A strategy may order or parameterize candidates with
-help from a `CostModel`, but it must not remove a valid candidate because of
-cost.
+strategy for one target. Strategies take no `CostModel` and must not remove a
+valid candidate because of cost; ranking happens at selection time.
 
 ### 3.3 Current concrete strategies
 
@@ -204,9 +205,9 @@ The default context-free registry contains five `ReplacementStrategy` implementa
 - `ASAPStrategies` matches supported aggregate and binary shapes. Its
   `replacements(target)` method constructs every legal post-ASAP summary sub-DAG,
   including applicable sketch, exact-accumulator, and pass-through
-  realizations. Candidates are sized and ordered for the target's accuracy
-  requirement; candidates without a sufficient guarantee are rejected before
-  costing.
+  realizations. Candidates are sized analytically for the target's accuracy
+  requirement and listed in `summary_candidates` order; candidates without a
+  sufficient guarantee are rejected before costing.
 - `SharedSubDAGStrategy` uses `consumer_count` to identify shared targets. It
   emits both build-once-and-share and recompute-independently rewrites when a
   target has multiple consumers.
@@ -215,8 +216,8 @@ The default context-free registry contains five `ReplacementStrategy` implementa
 - `ExactCompositionStrategy` preserves child-target references for compatible
   composition selection.
 
-`default_strategies_with` uses `SemanticEquivalentRewriteStrategy` in its rewrite
-slot. The evidence-aware registry supplies the accuracy evidence provider to
+`default_strategies` uses `SemanticEquivalentRewriteStrategy` (via its
+`AvgToSumOverCountStrategy` alias) in its rewrite slot. The evidence-aware registry supplies the accuracy evidence provider to
 summary and Hydra construction. Search derives `RollupStrategy` after CSE from
 the actual sibling set. See the
 [registry definitions](../../crates/asap-aware-mapping/src/replacement.rs).
@@ -251,8 +252,9 @@ matter.
 
 A single-target inspection caller may take the first
 candidate with `.into_iter().next()` and handle the empty case according to its
-execution policy. Constructing all candidates before taking the first costs
-more than constructing only the preferred candidate, but it keeps the strategy
+execution policy; the first candidate is in `summary_candidates` order, not cost
+order. Constructing all candidates before taking the first costs more than
+constructing only one, but it keeps the strategy
 contract consistent and preserves the full choice set for other callers.
 
 `CandidateLogicalASAPDAGs::global_selection` optionally coordinates cross-target sharing and

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

@@ -147,9 +147,9 @@ Search calls `propose`, so rejected candidates remain available for explanation.
 
 > What are all semantically valid alternatives for this target?
 
-`replacements` must be **exhaustive and not cost-filtered**. When its output has
-a preferred order, that ordering must come from the supplied `CostModel`; the
-strategy must still return every supported legal candidate. Required accuracy,
+`replacements` must be **exhaustive and not cost-filtered**. Strategies take no
+`CostModel`; output order carries no cost preference, and ranking happens at
+selection time. The strategy must return every supported legal candidate. Required accuracy,
 schema and capability checks can reject an otherwise applicable algorithm;
 exhaustiveness is not a promise of all theoretically possible plans.
 
@@ -164,7 +164,9 @@ accumulator, or a pass-through that keeps the original operation instead of
 building a summary. `realizations_for_intent` enumerates these concrete
 realizations; `ASAPStrategies::replacements()` constructs each one as
 a `ReplacementSubDAG`. It returns all
-candidates in preferred order without selecting a winner. At workload scale,
+candidates in `summary_candidates` order, sized by the analytical estimators,
+without selecting a winner; `AggIntent::Extension` intents stay
+`Realization::PassThrough`. At workload scale,
 `search_workload`/`search_workload_with` preserve all supported legal alternatives
 across every `TargetSubDAG`. Optional planner APIs coordinate compatible semantic selections; physical
 commitment and placement remain downstream deployment decisions.
@@ -201,17 +203,14 @@ see [code architecture §3](asap-aware-mapping-architecture.md#3-how-the-current
 
 ### `CostModel`
 
-`CostModel` covers every deployment-specific numeric or configuration decision—not only which candidate is cheapest. For example, sketch sizing trades memory and update cost for accuracy, so it belongs here too.
+`CostModel` covers deployment-specific preference and cost decisions. It is consulted only at selection time (`cost_sorted`, `global_selection` and their `_with_recurrence` variants), never during candidate generation: sketch parameters come from the analytical estimators (`accuracy::estimators::size_params`), and extension intents stay pass-through.
 
 The crate cannot hardcode real deployment costs: `asap-aware-mapping` uses `asap-types` and pinned `asap_sketchlib` mapping
 bounds, but does not execute workloads or own deployment measurements. Most hooks therefore provide the crate's built-in static behavior as a default. Override only the decisions your deployment needs to change.
 
 | Hook | Use it to | Default? |
 |---|---|---|
 | `rank_candidates` | Order valid sketch algorithms | No |
-| `size_params` | Convert an accuracy target into sketch parameters | Yes |
-| `realize_extension` | Map a custom intent to a realization | Yes |
-| `evaluation_extension` | Query a custom extension summary | Panics until paired with a custom realization |
 | `cse_recompute_cost` | Estimate independent recomputation | Yes |
 | `cse_shared_maintenance_cost` | Estimate shared maintenance | Yes |
 | `cse_share_decision` | Choose sharing or recomputation | Yes |
@@ -223,41 +222,6 @@ bounds, but does not execute workloads or own deployment measurements. Most hook
   fn rank_candidates(&self, intent: &AggIntent, candidates: &[SketchAlgorithm]) -> Vec<SketchAlgorithm>;
   ```
 
-- **`size_params`** — choose parameters, such as sketch capacity, for an already-selected `SketchAlgorithm` and accuracy target `(eps, delta)`, where `eps` is the tolerated error and `delta` is the tolerated probability of exceeding that error. It is separate from ranking so a deployment can customize sizing without changing algorithm preference. The trait provides a default implementation.
-
-  ```rust
-  fn size_params(&self, kind: SketchAlgorithm, intent: &AggIntent, eps: f64, delta: f64) -> SketchParams;
-  ```
-
-- **`realize_extension`** — map a deployment-defined `AggIntent::Extension` to a post-ASAP `Realization`. The default is `Realization::PassThrough`.
-
-  Use `AggIntent::Extension { ext_kind, payload }` for intent shapes that only your deployment needs. Core treats both fields as opaque. For example, a deployment can tag an approximate-frequency intent with `ext_kind: "frequency"` and recognize it in `realize_extension`:
-
-  ```rust
-  fn realize_extension(&self, ext_kind: &str, _payload: &serde_json::Value) -> Realization {
-      if ext_kind == "frequency" {
-          Realization::Sketch(SketchKind::new(
-              SketchAlgorithm::CountSketch,
-              SketchParams::CountSketch { width: 1024, depth: 5 },
-          ))
-      } else {
-          Realization::PassThrough  // fall back to the default for anything else
-      }
-  }
-  ```
-
-  Return `Realization::PassThrough` for unrecognized extension kinds. Do not panic.
-
-  ```rust
-  fn realize_extension(&self, ext_kind: &str, payload: &serde_json::Value) -> Realization;
-  ```
-
-- **`evaluation_extension`** — define how queries read an extension summary that `realize_extension` mapped to a `Sketch`. The two hooks are a pair: realization defines what is maintained; evaluation defines how it is queried. Override both for the same `ext_kind`. The default evaluation panics to prevent a silent wrong answer.
-
-  ```rust
-  fn evaluation_extension(&self, ext_kind: &str, payload: &serde_json::Value, col: &ColumnRef) -> SketchStatistic;
-  ```
-
 - **`cse_recompute_cost`** — estimate the one-time cost of recomputing a CSE candidate's sub-DAG independently at a single consumer. Default: `default_cse_recompute_cost`, a structural-size proxy.
 
   ```rust
@@ -297,7 +261,8 @@ A custom cost model does not necessarily need to override every hook. The curren
 `ReplacementStrategy` answers "what are the candidates for this one target?" `CandidateLogicalASAPDAGs` answers the same question for every target in a whole workload at once, without enumerating `2^N` fully-copied plans for `N` independently-choosable sites.
 
 ```rust
-// replacement.rs
+// replacement.rs (TargetSubDAGCandidates) and
+// plan_selection/candidate_selection.rs (RankedTargetSubDAGCandidates)
 
 // One TargetSubDAGCandidates per distinct TargetSubDAG in the whole workload —
 // never a flat list of fully assembled plans.
@@ -345,7 +310,7 @@ to the selected algorithm and classifies the pair into its category. The public
 `.category()`, `.algorithm()`, and `.params()` accessors expose the committed
 values without permitting an invalid combination.
 
-Where this matters in practice: `CostModel::rank_candidates`, `CostModel::size_params`, and `ASAPStrategies::replacements` operate at the **algorithm** level. `summary_candidates(intent)` returns a list of `SketchAlgorithm`s (`[Kll, DDSketch]` for a `Quantile` intent), never a bare `SketchKind` with nothing chosen underneath it. `SketchKind` appears after an algorithm has been selected and sized—on `Realization::Sketch(SketchKind)` and `FieldDataType::Sketch(SketchKind, GroupingStrategy)`.
+Where this matters in practice: `CostModel::rank_candidates` and `ASAPStrategies::replacements` operate at the **algorithm** level. `summary_candidates(intent)` returns a list of `SketchAlgorithm`s (`[Kll, DDSketch]` for a `Quantile` intent), never a bare `SketchKind` with nothing chosen underneath it. `SketchKind` appears after an algorithm has been selected and sized—on `Realization::Sketch(SketchKind)` and `FieldDataType::Sketch(SketchKind, GroupingStrategy)`.
 
 `Sample`, `Wavelet`, and `StatModel` each use a flat `(Kind, Params)` pair. `Sketch` needs the additional algorithm level because multiple algorithms can serve the same purpose—for example, KLL and DDSketch both answer quantile queries.
 
@@ -395,7 +360,7 @@ Each `ReplacementExplanation::reason` is copied verbatim from the matching candi
 
 ### Why there is no `ExplanationRule` trait
 
-Explanations are derived from candidates already present in `CandidateLogicalASAPDAGs`. A new candidate kind therefore requires an `impl ReplacementStrategy` wired into `default_strategies`/`default_strategies_with`; a second explanation-specific trait would duplicate registration and could drift from the actual search space. Custom callers supply strategies through `explain_replacements_with`, using the same extension point exposed by `search_workload_with`.
+Explanations are derived from candidates already present in `CandidateLogicalASAPDAGs`. A new candidate kind therefore requires an `impl ReplacementStrategy` wired into `default_strategies`; a second explanation-specific trait would duplicate registration and could drift from the actual search space. Custom callers supply strategies through `explain_replacements_with`, using the same extension point exposed by `search_workload_with`.
 
 ### How it derives `location` text
 

docs/develop_docs/end-to-end-accuracy-guarantees.md

@@ -43,7 +43,7 @@ The main implementation locations are:
 | Guarantee and error vocabulary | `asap_types::ir::properties::guarantee` |
 | Accuracy model and built-in propagation | `asap_aware_mapping::accuracy` |
 | Candidate construction and legality filtering | `asap_aware_mapping::replacement` |
-| Parameter sizing hooks | `asap_aware_mapping::cost_model` |
+| Parameter sizing | `asap_aware_mapping::accuracy::estimators` |
 | Guarantee and rejection export | `asap_types::dag_export` and the `dag_export` devtool |
 
 Read the sections below when changing one of those contracts.