Audience: developers adding planner behavior. Read the architecture and the contracts first. Each recipe lists the files to change and the tests to add; keep each change inside the stage that owns the decision.
A new sketch that Pass 1 can offer for an intent.
- Type.
SketchAlgorithmisasap_sketchlib's algorithm enum, so the algorithm must exist in the library first; its summary type isFieldDataType::Sketch(algorithm). Add its parameters toSketchParams(crates/types/src/summary_type/parameters.rs) and its predefined list toparameter_list. - Capability. Its row, which inputs it can merge and which statistics
it answers with the merged error, is the library's family-capability
table (
SketchAlgorithm::capability), read unchanged bySummaryTypeCapability::of(crates/types/src/summary_type/capability.rs). Pass 2's sharing, tumbling window and rollup rules read only this table. Which readouts the executor evaluates is its own declaration,EVALUATED_READOUTS(crates/executor/src/capability.rs); add the family's readouts there once the executor answers them. - Offer and size. Place it in
summary_realization::ALGORITHM_PREFERENCE(crates/stage1-pass1-per-computation-candidates):summary_candidatesoffers it, in that order, for every intent whose statistic its capability row answers. To size it, add its list incrates/types/src/summary_type/parameter_lists.rs(parameter_list). - Accuracy. Add its error model under
crates/accuracy/src/guarantee/and return it fromtheoretical_guarantee, evaluated at the required failure probability. Without a guarantee, every candidate that uses it is rejected. - Cost. Give it a state size (the library's
estimated_memory_bytesfor the type the executor builds; KLL keeps the planner's own formula) insketch_state_bytes(crates/cost/src/node/state_bytes/mod.rs), its per-row and per-merge CPU incrates/cost/src/node/operations_per_unit.rs(update_terms_per_row,counters_updated_per_row,merge_terms_per_state), and accept its parameters incrates/cost/src/measured.rsif deployments measure it. A new per-unit constant there also needs aCostConstantvariant of the same name incrates/cost/src/node/cost_terms.rsand its arm inCostConstant::operations_per_unit, sonode_cost_termscan name it; thecost_termstests fail until it has one. - Executor. Wrap the
asap_sketchlibimplementation incrates/executor/src/summary_kernels/and register it infactory.rsandcapability.rs. Gaps in the library are fixed upstream, not with a local copy. - Labels. Name it in
asap_devtools::candidate_labels.
Tests: a Pass 1 test in crates/stage1-pass1-per-computation-candidates/src/tests.rs
that the intent gets the new candidate (and that a deployment without it
is not offered it); an estimator test beside the
estimator; an execution test in crates/integration-tests/tests/ such as
frequency_execution.rs or kll_tumbling_window_execution.rs.
A new way for computations of one Pass 1 candidate to share, split or reuse work.
- Add a memo rule under
crates/stage1-pass2-reuse-candidates/src/rules/(for examplerollup/ortopk.rs): it adds candidates (and, when it needs them, groups) to the memo groups it implements, keeping every existing candidate. Read summary families only throughSummaryTypeCapability. The helpers rules add candidates with live inrules/candidates.rs. - Declare it in
rules/mod.rsand call it fromgenerate_logical_asap_memo_candidates(stage1-pass2-reuse-candidates/src/lib.rs), after the existing rules. - Add its row to the Pass 2 rule table of the design.
A rule must keep every Pass 1 candidate, must not add a family or a readout, and must keep the composed DAG's meaning. Stage 3 decides whether it pays off.
Tests: unit tests beside the rule in pass2/memo/rules/ for when it applies
and when it must not; an end-to-end test like
crates/integration-tests/tests/reuse_rules.rs that the planned workload
contains the candidate and that Stage 3 prices it.
- Add the
Lifetimevariant or the valid (timing, lifetime) pair (crates/types/src/stages/physical/properties/mod.rs,PhysicalProperties::newandreadable_at) and its placement incrates/types/src/ir/properties/timing.rs, with its data-state edge rules. - Offer it in
crates/stage2-physical-optimization/src/candidate.rs(LIFETIMES,offered_physical_properties; a per-group offer ingroup.rs), and gate it on the deployment input that allows it with aPruneReason. - Cost it in
crates/cost/src/node/usage/mod.rs(asap_cost::node_resource_usage_and_cost): what it keeps in memory or on disk, and what each evaluation rebuilds.
Tests: Stage 2 unit tests for when the option is offered;
crates/integration-tests/tests/physical_properties_e2e.rs and the Example 4
tests in planner_layering_example4.rs.
- A new validity check goes in
select_planand rejects a candidate with aRejection { cause, reason }whosecauseis a new failed-checkRejectionCausevariant (listed inRejectionCause::failed_a_check); it never fails the whole selection unless the input itself is bad (a newErrorSelectingPlanvariant, documented as bad input). - A new pricing input goes in
CostInputs(validated in itsvalidate); a new statement about the executor goes inDeploymentCapabilities. Both reach the stages throughPlanningModels. A new deployment capability is three pieces: its field inDeploymentCapabilities(with a default that changes no plan), its expansion intoCandidateExclusions inDeploymentCapabilities::exclusions, and theExclusionSourcevariant those exclusions carry. The facade expands the exclusions once and hands the list to Pass 1 and Stage 2; no stage reads the struct itself. When noCandidateExclusionfield can say what the capability rules out, add the field toCandidateExclusion(with itsmatchestest and the operators it applies to ininvalid_reason). - Expose it in
asap_plannerand in the Plan Viewer guide.
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.
Lower the construct in its frontend (crates/frontend-promql/src/promql.rs,
crates/frontend-sql/src/sql/, crates/frontend-metricsql/src/) into
existing NonASAPOp nodes and AggIntents. If it needs a new intent, add
it in asap-types and offer its candidates in Pass 1 (recipe 1). A construct
that cannot be represented is rejected with the frontend's
unsupported-feature error, never lowered approximately.
Tests: frontend tests for the lowering and its rejection cases; the corpus
tests (analyze_corpora, variant_coverage) show the coverage change.
- The decision is made in the stage that owns it (contracts §6).
- Every new public type, field and variant has a doc comment.
- Unit tests beside the code and one end-to-end test through the stages.
- The design document's examples still plan the same, or the change is
explained: run the
planner_layering_example*tests andasap_planner --workload tools/dag-viewer/workloads/planner-layering/example1.json --run-until stage3(andexample2.json, with--sql-catalog-tablefor each table intables.json,example3a.jsonandexample3b.json). - The design, developer and user docs that name what changed are updated.