Skip to content

feat(types, stage2, stage3): deployment exclusions: one Stage 2 filter for a target's capabilities and the caller's exclusions - #1374

Open
zzylol wants to merge 5 commits into
mainfrom
test/deployment-exclusions
Open

zzylol wants to merge 5 commits into
mainfrom
test/deployment-exclusions

Conversation

@zzylol

@zzylol zzylol commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Summary

  • Problem: a deployment could only say which sketches it builds and whether it keeps raw data or query-time results, and those were applied in two places (Pass 1, and two Stage 2 rules). It could not say "no rate state merged across windows", "no counter extrapolation", or "never select a query-time scan". So rate(c[5m]) was planned as stored Rate windows on a target that cannot merge them, and the benchmark harness patched an environment-variable hook into Stage 3.
  • Change: DeploymentCapabilities is the one place a target's restrictions live. DeploymentCapabilities::exclusions() expands every capability a target lacks, and each candidate the caller excludes, into CandidateExclusions. Stage 2 applies them as one filter (PruneReason::ExcludedByDeployment(source)). Stage 3 reports no plan left as RejectionCause::ExcludedByDeployment.
  • Effect: for rate(c[5m]) every 60 s over 1,000 counter series, a target without mergeable rate state gets query-time SummaryAgg(Rate) → FinalizeExactAccumulator at 0.367671 per second, instead of stored windows at 0.279284. A target without counter extrapolation gets no plan, and the rejection names counter_not_extrapolated (7 candidates). The default capabilities select the same plans as before.

Part of #1370. This is harness PR P1 of #1317's design, with CandidateExclusion unified with the deployment capability table as #1370 asks. The Stage 2 placement and the tests were approved before implementation.

Review guide

  • Base: main at 1760a69f5; head ceb78acf4. Not stacked. Five commits:
    1. the approved tests, rebased (one conflict, resolved as described below);
    2. the implementation;
    3. the viewer and its fixture;
    4. a Stage 3 fix: the default deployment's own exclusion does not turn Infeasible into ExcludedByDeployment;
    5. review fixes: Pass 1 skips summaries excluded outright, the rejection keeps the costing failures, validate refuses self-contradicting exclusions, and smaller cleanups (see "Review fixes" below).
  • Read first (needs careful review):
    • crates/types/src/deployment_capabilities/mod.rs: exclusions() and validate.
    • crates/types/src/deployment_capabilities/exclusion.rs: CandidateExclusion::matches, invalid_reason, family_excluded_outright.
    • crates/stage1-pass1-per-computation-candidates/src/computation_targets.rs: without_excluded_families.
    • crates/stage2-physical-optimization/src/candidate.rs: the one filter in offered_physical_properties.
    • crates/stage3-plan-selection/src/report.rs: excluded_by_deployment, and its two call sites in lib.rs.
  • Mechanical:
    • pass1_memo(memo, None) → pass1_memo(memo, &[]) in tests; the facade and the devtools stage runner pass &capabilities.exclusions().
    • asap-cost's private measure_name became AggIntent::kind_name in asap-types.
    • tools/dag-viewer/test-fixtures/p90-kll.json was regenerated with the README command (see Verification).
  • Rebase conflict: main (refactor: tools and snapshots over the #1207 memo, edges and contexts (#1207 PR 9) #1239) removed the viewer's REJECTION_CAUSES list, and with it the rejection-cause half of viewer_contract.rs (the test is now viewer_knows_every_view_refresh). The tests commit's addition to that half is dropped, since no viewer list is left to check. assert_excluded_by_deployment in deployment_exclusions.rs still asserts that the cause is not a failed check.

Behavior: before → after

The user's input: a workload with one counter query, planned for a target that cannot keep rate state across windows.

// workload.json
{"query_workload": {"language": "promql", "repeating_queries": [
   {"query": "rate(c[5m])", "demand": {"fixed_interval_at": {"interval": 60000, "evaluation_phase": 0}},
    "requirements": {}, "predictability": {"predictable": {"known_at": null}}}]},
 "data_workload": {"arrival": {"ingesting": {"rows_per_second": 1000.0}},
   "sources": {"c": {"series_count": 1000, "metric_type": "counter", "sample_interval": 1000}}}}
// capabilities.json (asap_planner --deployment-capabilities)
{"state_not_mergeable_across_windows": [{"exact": "Rate"}, {"exact": "Increase"}]}
Before (main) After (this PR)
capabilities state_not_mergeable_across_windows is an unknown field, so the file is refused accepted
plan ingestion Scan → ingestion SummaryTumblingWindowChain(Rate) → TimeRange → SummaryMerge → FinalizeExactAccumulator, 0.279284 per second query-time Scan → TimeRange → SummaryAgg(Rate) → FinalizeExactAccumulator, 0.367671 per second
Stage 2 report — 3 alternatives pruned with ExcludedByDeployment(StateNotMergeableAcrossWindows)
{"counter_semantics": {"extrapolation": false}} unknown field no plan: NoValidCandidate([Rejection { cause: ExcludedByDeployment, reason: "… counter_not_extrapolated (7 candidates) … may be infeasible without …" }])
{"excluded_candidates": [{"timing": "query_time", "operator": "Scan"}, …]} (the sweep's "stored" arm) needs ASAP_SB_FORBID patched into Stage 3 sum_over_time(m[5m]) reads an ingestion-time chain of exact sums, at 0.113237 instead of 0.060534 per second

Rejection cause under MVP capabilities ({"raw_data_retained": false, "query_time_results_retained": false}, which plan_installable defaults to): 5 of the 77 sketch-heavy workloads have no plan. main reports them as Infeasible; this PR reports them as ExcludedByDeployment with the reason query 0 has no candidate left to answer it; excluded by the deployment: raw_data_not_retained (4 candidates); the workload may be infeasible without these exclusions too (for repeat-rate-and-l2…, the MILP form: no plan is left (the selection MILP is infeasible); …). The 5 are promql-entropy__r4-10hz-24h…, sql-entropy-client-ip…, sql-l2-client-ip…, control-l2-16-resolvers… and repeat-rate-and-l2…. When some execution could not be costed, the reason ends with the same ; executions left out because they could not be costed: … that Infeasible gives (none of these 5 has one).

This serves the measurement harness, whose sweep arms and target profiles need typed restrictions. It also serves #1370's capability-limited targets.

Interfaces

Every declaration below is in this PR, bodies elided.

crates/types/src/deployment_capabilities/mod.rs (was deployment_capabilities.rs)

 /// What the deployment's executor can run and keep. Planning reads it in
-/// Stage 1 (`supported_summaries`), Stage 2 (`query_time_results_retained`)
-/// and Stage 3 (`raw_data_retained`).
+/// Stage 2, as the exclusions it expands into.
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
 #[serde(default, deny_unknown_fields)]
 pub struct DeploymentCapabilities {
     pub supported_summaries: Option<Vec<SupportedSummary>>,
     pub raw_data_retained: bool,
     pub query_time_results_retained: bool,
+    /// What the executor's counter functions do; default: they handle
+    /// resets and extrapolate, as PromQL's do.
+    pub counter_semantics: CounterSemanticsSupport,
+    /// State families the executor builds and finalizes within one
+    /// evaluation only, e.g. `[{"exact": "Rate"}]`; default none.
+    pub state_not_mergeable_across_windows: Vec<SummaryFamily>,
+    /// Candidates the caller rules out directly, e.g. a benchmark arm with
+    /// no query-time scan; default none.
+    pub excluded_candidates: Vec<CandidateExclusion>,
 }
+/// What a deployment's counter functions do. JSON: an object; an omitted field is `true`.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(default, deny_unknown_fields)]
+pub struct CounterSemanticsSupport {
+    /// A drop in a counter is a reset and is added back (rate, increase, irate, resets).
+    pub reset_handling: bool,
+    /// The increase is extrapolated to the range's ends (rate, increase, delta).
+    pub extrapolation: bool,
+}
+/// Which capability an exclusion comes from; Stage 2's prune reason names it.
+/// JSON: snake_case, e.g. `"raw_data_not_retained"`.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ExclusionSource {
+    SummaryNotSupported,
+    ReadoutNotSupported,
+    RawDataNotRetained,
+    QueryTimeResultsNotRetained,
+    CounterResetsNotHandled,
+    CounterNotExtrapolated,
+    StateNotMergeableAcrossWindows,
+    /// The caller's `excluded_candidates[index]`.
+    ExcludedCandidate { index: usize },
+}
+/// One exclusion a deployment's capabilities expand into, with its source.
+#[derive(Debug, Clone, PartialEq)]
+pub struct DeploymentExclusion {
+    pub source: ExclusionSource,
+    pub exclusion: CandidateExclusion,
+}
 impl DeploymentCapabilities {
+    /// The exclusions these capabilities expand into, in the order: supported
+    /// summaries, raw data, query-time results, counter resets, counter
+    /// extrapolation, unmergeable state, then `excluded_candidates`. The default's
+    /// only one is `{timing: query_time, kept_across_evaluations: true}`.
+    pub fn exclusions(&self) -> Vec<DeploymentExclusion>;
-    pub fn supports(&self, summary_type: &SketchAlgorithm, readout: StatisticKind) -> bool;
     /// … also refuses an exclusion of `excluded_candidates` that cannot be applied.
     pub fn validate(&self, data: &DataWorkload) -> Result<(), DeploymentCapabilitiesError>;
 }
 }
-pub fn summary_supported(
-    supported_summaries: Option<&[SupportedSummary]>,
-    summary_type: &SketchAlgorithm,
-    readout: StatisticKind,
-) -> bool;
 pub enum DeploymentCapabilitiesError {
     StoredDataNotRetained { arrival: DataArrival },
+    /// Bad input: `excluded_candidates[index]` sets no field, has an empty
+    /// range or an α outside (0, 1), contradicts itself, or names no measure.
+    #[error("deployment capabilities, excluded candidate {index}: {reason}")]
+    InvalidExclusion { index: usize, reason: String },
 }

crates/types/src/deployment_capabilities/exclusion.rs (new)

+/// Physical candidates whose description matches every field that is set
+/// (AND; an unset field matches anything). JSON: an object; an unknown field is refused.
+#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
+#[serde(default, deny_unknown_fields)]
+pub struct CandidateExclusion {
+    pub timing: Option<ExecutionTiming>,
+    /// Lifetime `AcrossEvaluations` (`Some(true)`) or not.
+    pub kept_across_evaluations: Option<bool>,
+    pub operator: Option<OperatorKind>,
+    /// An operator with a `Reduction`: per entity (`Some(true)`) or grouped.
+    pub per_entity_reduction: Option<bool>,
+    /// An `Aggregate` one of whose measures has this `AggIntent` kind, e.g. `"rate"`.
+    pub aggregate_measure: Option<String>,
+    /// A counter function or counter state that needs this semantics.
+    pub counter_semantics: Option<CounterSemantics>,
+    /// A state build (`SummaryAgg`, chain) of this family.
+    pub summary_family: Option<SummaryFamily>,
+    /// A state build whose θ is in this range.
+    pub sketch_parameters: Option<SketchParameterRange>,
+    /// A state build merged across windows (a chain, or kept across
+    /// evaluations: `Some(true)`) or built and finalized in one evaluation.
+    pub merged_across_windows: Option<bool>,
+    /// A `SummaryEstimate` of this statistic from this sketch's state.
+    pub readout: Option<SketchReadout>,
+}
+/// What a counter function may need beyond reading samples. JSON: snake_case.
+pub enum CounterSemantics { ResetHandling, Extrapolation }
+/// A statistic read from a sketch's state, e.g. `{"summary_type": "Kll", "statistic": "Total"}`.
+pub struct SketchReadout { pub summary_type: SketchAlgorithm, pub statistic: StatisticKind }
+/// One physical candidate (or plan node) as an exclusion matches it. `C` is
+/// how the operator names its inputs: memo groups in Stage 2, plan node ids
+/// in a selected plan (the integration tests match plan nodes).
+pub struct CandidateDescription<'a, C> {
+    pub operator: &'a Operator<C>,
+    pub parameters: Option<&'a SketchParams>,
+    pub physical_properties: PhysicalProperties,
+    /// For a `SummaryEstimate`: the summary type of the state it reads.
+    pub read_summary_type: Option<&'a FieldDataType>,
+}
+impl CandidateExclusion {
+    pub fn matches<C>(&self, candidate: &CandidateDescription<'_, C>) -> bool;
+    /// The family this exclusion rules out outright: it sets `summary_family`
+    /// and no other field (as `supported_summaries` does for an algorithm it
+    /// does not list). Pass 1 skips such a sketch algorithm.
+    pub fn family_excluded_outright(&self) -> Option<SummaryFamily>;
+    /// Why `validate` refuses it (sets no field, two fields that match no
+    /// operator in common, invalid range, range of another algorithm than its
+    /// family, unknown measure), or `None`.
+    pub fn invalid_reason(&self) -> Option<String>;
+}

crates/types/src/summary_type/family.rs (new) and parameters.rs

+/// A summary state's family without θ. JSON: `{"sketch": "Kll"}`, `{"exact": "Sum"}`.
+#[serde(rename_all = "snake_case")]
+pub enum SummaryFamily { Sketch(SketchAlgorithm), Exact(ExactKind) }
+impl SummaryFamily { pub fn of(summary_type: &FieldDataType) -> Option<Self>; }
+/// An inclusive range of one sketch parameter. JSON: `{"kll_k": {"at_most": 1403}}`.
+#[serde(rename_all = "snake_case", deny_unknown_fields)]
+pub enum SketchParameterRange {
+    KllK { at_least: Option<u32>, at_most: Option<u32> },
+    KmvK { at_least: Option<u32>, at_most: Option<u32> },
+    #[serde(rename = "ddsketch_alpha")]
+    DDSketchAlpha { at_least: Option<f64>, at_most: Option<f64> },
+}
+impl SketchParameterRange {
+    pub fn algorithm(&self) -> SketchAlgorithm;
+    pub fn contains(&self, parameters: &SketchParams) -> bool;
+    /// Why the range is bad input: `at_least` above `at_most`, or an α
+    /// outside (0, 1); `None` when valid.
+    pub fn invalid_reason(&self) -> Option<String>;
+}

crates/types/src/ir/operator/kind.rs (moved from crates/cost/src/measured.rs, which re-exports it)

-pub fn of(payload: &Payload) -> Self;
+pub fn of<C>(operator: &Operator<C>) -> Self;

crates/types/src/stages/pruning.rs and crates/stage3-plan-selection/src/report.rs

 pub enum PruneReason {
     NoIngestionPipeline,
-    RawDataNotRetained,
-    QueryTimeResultsNotRetained,
     InputHasNoBuildableProducer,
     ReachesNoQueryOutput,
     CountMinWeightsNotProvenNonNegative,
+    /// Stage 2: the deployment's exclusions match it; names their source.
+    ExcludedByDeployment(ExclusionSource),
     DominatedBy(PhysicalCandidateId),
     UsageNotCostable,
 }
 pub enum RejectionCause {
     AccuracyTargetMissed,
     NoAccuracyGuarantee,
     LatencyBoundExceeded,
     LatencyOverRepeatInterval,
     OverClusterCapacity,
     CostNotRepresentable,
     Costlier,
     Slower,
     MoreMemory,
     TiedLostOnEnumerationOrder,
     Infeasible,
+    /// No plan is left without the deployment's exclusions. The reason names the
+    /// query or the infeasible MILP, then each source with its pruned count, e.g.
+    /// `counter_not_extrapolated (7 candidates)`, and says the workload may be
+    /// infeasible without them too. Not a failed check.
+    ExcludedByDeployment,
 }

crates/planner/src/lib.rs: re-exports CandidateExclusion, CounterSemantics, CounterSemanticsSupport, ExclusionSource, SketchReadout, SketchParameterRange, SummaryFamily.

crates/types/src/ir/operator/agg_intent.rs, crates/types/src/ir/schema/mod.rs and crates/stage1-pass1-per-computation-candidates/src/lib.rs

 impl AggIntent<ColumnId> {
+    /// The measure's JSON `kind`, e.g. `"rate"`; moved from `asap-cost`'s
+    /// private `measure_name`, which keys measured operation costs by it.
+    pub fn kind_name(&self) -> String;
+    /// Whether `name` is some measure's kind (`"rate"` yes, `"rte"` no).
+    pub fn is_kind_name(name: &str) -> bool;
 }
 impl Schema {
+    /// The summary state type this schema carries (its first non-plain
+    /// field), e.g. `Sketch(Kll)`; Stage 2 reads it for a readout's state.
+    pub fn summary_state_type(&self) -> Option<&FieldDataType>;
 }
-pub fn pass1_memo(
-    memo: Memo,
-    supported_summaries: Option<&[SupportedSummary]>,
-) -> Result<Memo, PerComputationCandidateError>;
+/// Pass 1 skips a summary whose sketch algorithm one of `exclusions` rules
+/// out outright (`family_excluded_outright`); Stage 2 prunes everything else
+/// the deployment cannot run.
+pub fn pass1_memo(
+    mut memo: Memo,
+    exclusions: &[DeploymentExclusion],
+) -> Result<Memo, PerComputationCandidateError>;

Removed by this PR (the - lines above):

  • PruneReason::RawDataNotRetained and PruneReason::QueryTimeResultsNotRetained. They are now ExcludedByDeployment(ExclusionSource::RawDataNotRetained) and ExcludedByDeployment(ExclusionSource::QueryTimeResultsNotRetained).
  • The Pass 1 summary filter without_unsupported_summaries and the supported_summaries parameter of pass1_memo and computation_targets. Pass 1 now reads the same exclusions() list (without_excluded_families), and only to skip sketch algorithms excluded outright; Stage 2 prunes unsupported readouts (ReadoutNotSupported) and everything narrower.
  • DeploymentCapabilities::supports and the free function summary_supported. Their only callers were the Pass 1 filter and one installable test, which now reads supported_summaries directly.
  • asap-cost's private measure_name, moved to AggIntent::kind_name.
  • The Pass 1 test tests::targets::unsupported_summaries_are_not_offered, which tested the deleted filter. exact_only_capabilities_offer_no_summary replaces it for the new Pass 1 skip; Stage 2's unsupported_summaries_and_readouts_are_pruned covers the Stage 2 side.

Wire change: a Stage 2 pruned candidate's reason for these capabilities is now {"excluded_by_deployment": "raw_data_not_retained"} (or {"excluded_by_deployment": {"excluded_candidate": {"index": 0}}}) instead of "raw_data_not_retained". The viewer shows it as "excluded by the deployment: raw data not retained".

Usage (what the integration tests run):

// The deployment: no rate or increase state kept across windows.
let capabilities = DeploymentCapabilities {
    state_not_mergeable_across_windows: vec![
        SummaryFamily::Exact(ExactKind::Rate),
        SummaryFamily::Exact(ExactKind::Increase),
    ],
    ..Default::default()
};
// The facade passes them to Stage 2, which prunes every alternative that
// `capabilities.exclusions()` matches.
let models = PlanningModels::builtin().with_deployment_capabilities(&capabilities);
// `rate(c[5m])` every 60 s over 1,000 counter series, lowered and planned.
let run = run_planning_stages_over(roots, &entries, &data, models)?.run;
// The plan: query-time Scan → TimeRange → SummaryAgg(Rate) → Finalize, 0.367671 per second.
let (plan, selection) = run.selection.as_ref().unwrap();

Design scope

New item Scope Why it is general
deployment_capabilities/exclusion.rs: CandidateExclusion, CounterSemantics, SketchReadout, CandidateDescription deployment input (asap-types), read by Stage 2 It describes physical candidates by operator, timing, lifetime, θ, measure and state use, which is the physical vocabulary every stage already has. It is not tied to one engine or one sweep arm.
DeploymentCapabilities::{counter_semantics, state_not_mergeable_across_windows, excluded_candidates}, CounterSemanticsSupport, ExclusionSource, DeploymentExclusion, exclusions() deployment input They hold a target's capabilities and how they expand. The sweep's exclusions and an engine's profile are both lists of the same type, as #1370 asks.
summary_type/family.rs: SummaryFamily; SketchParameterRange summary types (θ vocabulary) They are a family without θ and a range of θ, next to SketchParams. A calibration filter can reuse them.
ir/operator/kind.rs: OperatorKind (moved) IR It names an operator without its arguments. It is not cost-specific, and asap-types needs it.
PruneReason::ExcludedByDeployment, RejectionCause::ExcludedByDeployment stage reports They use the existing report shapes, with one reason per filter.
AggIntent::{kind_name, is_kind_name} (moved from asap-cost's private measure_name) IR The measure's JSON kind, shared by measured operation costs and exclusions.
CandidateExclusion::family_excluded_outright deployment input Says when an exclusion rules out a whole family, which is what lets Pass 1 skip it without a second filter.
Schema::summary_state_type IR schema The state type a schema carries; Stage 2 reads it for the state a readout reads, and plan-node matching does too.

Why the names changed from the approved plan:

  • SelectionOptions and select_plan_with are gone. The exclusions are a deployment input, and PlanningModels::deployment_capabilities already reaches Stage 2.
  • PlanningModels::selection_options is not needed.
  • The causes are ExcludedByDeployment, not ExcludedBySelectionOptions, because one cause now covers both capabilities and caller exclusions.

Algorithm changes

Problem: the restrictions were applied in three places with three mechanisms: Pass 1 for summaries, and two separate Stage 2 rules for retention. Nothing could express counter semantics, state mergeability, measures or θ ranges.

Before:

  1. Pass 1 dropped unsupported summaries (without_unsupported_summaries).
  2. Stage 2 pruned raw-data and query-time-result alternatives, each with its own reason.
  3. Stage 3 reported an empty plan space as Infeasible.

After:

  1. DeploymentCapabilities::exclusions() expands everything into one list, in this order:
    • supported summaries: a family exclusion for each sketch algorithm not listed, and a readout exclusion for each statistic a listed algorithm answers but the deployment does not;
    • raw data: {query_time, Scan} and {Scan, kept_across_evaluations};
    • query-time results: {query_time, kept_across_evaluations};
    • counter reset handling, then counter extrapolation;
    • unmergeable state families: {family, merged_across_windows: true};
    • excluded_candidates[i].
  2. Pass 1 (without_excluded_families, run last in computation_targets) drops each Summary(algorithm) way, a fused computation's included, whose Sketch(algorithm) family one exclusion of the same list rules out outright (summary_family set and nothing else). Stage 2 would prune every build of it, so this only saves work. Exact accumulators and every narrower exclusion (readouts, mergeability, θ ranges) are left to Stage 2.
  3. Stage 2 (offered_physical_properties) describes each offered (τ, ℓ) as a CandidateDescription: its operator, θ and physical properties, and for a SummaryEstimate the state type of the group it reads. After the Count-Min and no-ingestion rules, it records the first matching exclusion as ExcludedByDeployment(source). The existing propagation (InputHasNoBuildableProducer, ReachesNoQueryOutput) removes whatever depended on it.
  4. Stage 3 handles two cases: a query with no answering execution, and an infeasible MILP. In both, it returns one ExcludedByDeployment rejection when Stage 2 pruned some alternative for a source the default deployment does not have, with a count per source. Otherwise it returns today's Infeasible.

Correctness:

  • The expansions of the two old retention rules match them exactly:

    • raw data: (query_time ∨ across) ∧ Scan ∧ ¬raw_data_retained;
    • query-time results: query_time ∧ across ∧ ¬query_time_results_retained.

    The Stage 2 tests of these prunes pass with only the reason renamed.

  • The default's only exclusion is the query-time-results one, so planning with the defaults prunes what it pruned before. Stage 3 does not count that exclusion, so the default reports Infeasible as before (only_exclusions_beyond_the_default_deployments_make_the_rejection). an_exclusion_matching_nothing_changes_nothing and the unchanged pass/fail sets of every existing suite (see Verification) check this.

  • A matched candidate never reaches Stage 3, so it is never selected: some_node_matches is false on every selected plan in deployment_exclusions.rs.

  • The Pass 1 skip keeps the selected plans: across 101 workloads × 5 capability sets (see Verification), all 505 plans, costs, MILP objectives, MILP sizes and Stage 2 physical-candidate counts are identical to the previous head d9ecc8bd9, which skipped nothing in Pass 1.

Complexity: O(alternatives × exclusions) matches in Stage 2, each at most O(measures). The supported-summaries expansion has at most SketchAlgorithm::ALL.len() entries plus the readouts of the listed algorithms.

Limits:

  • Family, θ and mergeability match state builds (SummaryAgg, SummaryTumblingWindowChain) only. Merges, estimates and finalizations over an excluded build lose their producer.
  • Pass 1 skips only what an exclusion rules out as a whole family. A deployment that lists KLL without its quantile readout, or excludes KLL only when merged across windows, still has its KLL builds planned through Pass 1 and Pass 2, and pruned in Stage 2. The planning-time numbers are in Verification.
  • When exclusions matched and no plan is left, the rejection does not say whether the workload would be infeasible without them, because that needs a second solve. Its reason says so.

Decisions and open questions

Decided (by the user, before implementation):

  • The filter runs in Stage 2, and Pass 1 stops filtering supported_summaries. After review, Pass 1 reads the same exclusions() list to skip sketch algorithms excluded outright (one source of truth, no second filter), which restores main's planning time for restricted deployments.
  • Q-P1-1: the exclusions travel in PlanningModels::deployment_capabilities.
  • Q-P1-2: ExcludedByDeployment is not a failed check.
  • Q-P1-3: one cause, whose message says the workload may also be infeasible without the exclusions.
  • The tests of this PR, as written.

Needs reviewer decision:

  1. aggregate_measure is a string: the AggIntent JSON kind, e.g. "rate", as OperatorCost::measure already is. validate refuses a name that is no measure's kind; AggIntent::is_kind_name asks serde whether the tag is a known variant. A typed enum would duplicate the 40 intent kinds.
  2. Reset handling also covers irate and resets, and extrapolation also covers delta, following PromQL's definitions.
  3. aggregate_measure validation (review L3, not done): is_kind_name still relies on serde's unknown variant error text. A validating newtype AggregateMeasureKind would still need a way to list the measure kinds, which today only that error gives, so it was not small enough for this PR.
  4. Plan for a target's deployment capabilities #1370's names: this PR uses exclusions(), because the items are CandidateExclusions, and the existing NoValidCandidate with RejectionCause::ExcludedByDeployment. Plan for a target's deployment capabilities #1370 proposes restrictions() and NoDeployablePlan.
  5. Defaults in the rejection: the default deployment's own exclusion is left out of the ExcludedByDeployment rejection and its counts, which keeps Q-P1-3's "no exclusion matched → Infeasible" for default planning. The other way is to list it too, but then every infeasible workload under the defaults would be reported as excluded by the deployment.

Verification

Built with the shared build environment. cargo fmt --all --check and cargo clippy --all-targets on the changed crates are clean. The changed crates' suites ran at this head and were compared by name with main 1760a69f5 (main has not moved). No test fails here that passes on main.

Scope Command Result at this head Newly failing vs main Notes
types, Stage 1 Pass 1, Stage 2, Stage 3, planner, integration, devtools cargo test --no-fail-fast -p asap-types -p asap-stage1-pass1-per-computation-candidates -p asap-stage2-physical-optimization -p asap-stage3-plan-selection -p asap-planner -p asap-integration-tests -p asap-devtools 752 pass, 10 fail 0 the 10 also fail on main: planner summary_sharing::identical_ungrouped_queries_share_their_producers; integration joint_search_equivalence ×2, materialized_views, plan_sharing ×2, promql_to_post_asap; devtools planner_fuzz ×3. 47 tests are new; the only main tests gone are the renamed defaults test and unsupported_summaries_are_not_offered
viewer JS node --test tools/dag-viewer/ with asap_planner built 30 of 30 0

Plans unchanged by the Pass 1 skip, and planning time. Both release binaries (d9ecc8bd9, which plans every summary in Pass 1, and this head) ran asap_planner --run-until stage3 over 101 workloads: 24 showcase (21 single-query and joint workloads at 1 Hz/10 s and 10 Hz/60 s, plus viewer examples 1, 3a and 3b) and the 77 sketch-heavy workloads, each under 5 capability sets: CLI default {}, exact-only {"supported_summaries": []}, HLL-only, KLL-only, and MVP. All 505 plans, costs, MILP objectives, MILP sizes, physical-candidate counts and rejection texts are identical. Times are the median of 3 runs, each pinned to one core, --format text:

Set Capabilities Pass 1 candidates Logical candidates after Pass 2 Planning time, whole set Per workload
Sketch-heavy (77) exact-only 22,630 → 530 26,351 → 683 6.30 s → 2.47 s (×0.39) median ×0.76, best ×0.14
Sketch-heavy HLL-only 22,630 → 632 26,351 → 785 6.30 s → 2.53 s (×0.40) median ×0.77
Sketch-heavy KLL-only 22,630 → 539 26,351 → 711 6.34 s → 2.50 s (×0.39) median ×0.76
Showcase (24) exact-only / HLL-only / KLL-only 1,354 → 238 / 238 / 406 1,590 → 298 / 298 / 498 ×0.88 / ×0.88 / ×0.91
Both CLI default, MVP unchanged unchanged ×1.00–1.01

The restricted counts are back to main's (683 and 711 logical candidates on the sketch-heavy set under exact-only and KLL-only). No planning-time regression test was added: wall-clock tests are not reliable here, and exact_only_capabilities_offer_no_summary pins the candidate count that causes the time instead.

End to end, with the CLI (asap_planner --run-until stage3 --format json, on the rate workload of "Behavior"):

  • On main, both capability files are refused: unknown field `state_not_mergeable_across_windows` and unknown field `counter_semantics` .
  • At this head, {"state_not_mergeable_across_windows": [...]} selects query-time Scan → TimeRange → SummaryAgg → FinalizeExactAccumulator at 0.367671 per second.
  • At this head, {"counter_semantics": {"extrapolation": false}} gives: no valid candidate: [Rejection { id: "workload", cause: ExcludedByDeployment, reason: "query 0 has no candidate left to answer it; excluded by the deployment: counter_not_extrapolated (7 candidates); the workload may be infeasible without these exclusions too" }].

Expected values: every cost and count in the tests commit holds at this head unchanged:

  • costs: 0.060946, 0.061518, 0.062491, 0.072584, 0.060534, 0.113237, 0.279284, 0.367671, 1.490206, 3.953715 and 0.447669 per second;
  • pruned counts: 5, 10, 8, 3, 7, 4 and 2. (Pass 1 skips sketch algorithms only, so the 5 excluded Rate states are still pruned in Stage 2.)

Existing tests whose expected values change, and why:

  • devtools/tests/asap_planner.rs::deployment_capabilities_flag_sets_the_capabilities_and_shows_them: the echoed deployment_capabilities also lists the three new fields with their defaults. "Pass 1 offers no DDSketch candidate" under KLL-only capabilities holds again, as on main.
  • tools/dag-viewer/test-fixtures/p90-kll.json, regenerated with the README command: the memo and stage3_plan_selection are as on main; Stage 2's 36 pruned alternatives carry the new reason encoding, and deployment_capabilities lists the new fields.
  • memo.test.mjs: a Stage 2 line reads "excluded by the deployment: query time results not retained". Everything else is as on main.

Review fixes (independent review of d9ecc8bd9)

  • M1: Pass 1 skips a Summary(algorithm) way when a summary_family-only exclusion from the same exclusions() list matches it (numbers above). Tests written first and seen failing: exact_only_capabilities_offer_no_summary, a_partial_exclusion_keeps_the_summary, an_excluded_exact_family_is_left_to_stage_2, a_family_is_excluded_outright_only_by_a_family_only_exclusion.
  • M2: costing_failures is shared by infeasible and excluded_by_deployment, so the rejection keeps ; executions left out because they could not be costed: … (the_exclusion_rejection_keeps_the_costing_failures). The MVP cause change is listed under "Behavior".
  • L1: validate refuses an exclusion two of whose fields match no operator in common: family, θ or merged_across_windows with an operator other than a state build; aggregate_measure with one other than Aggregate; readout with one other than SummaryEstimate or with a build-only field; per_entity_reduction with an operator without a reduction (self_contradicting_exclusions_are_rejected, written first).
  • L2: CandidateDescription::of_plan_node moved into the integration test as description_of_plan_node. The C generic stays, because that test still describes plan nodes, whose operators name inputs by NodeId.
  • L3: not done; see "Needs reviewer decision" 3.
  • L4–L7: ASAPOp::produced_state calls Schema::summary_state_type; DeploymentExclusion::candidates is now exclusion; the viewer's deployment line reads summary_type (it showed undefined (Quantile)); the moved OperatorKind comment no longer names a PR.

New tests, by purpose:

  • Stage 1 Pass 1: exact-only capabilities offer no summary; a readout-only or merge-only exclusion keeps the summary; an excluded exact family is left to Stage 2.
  • types:
    • self-contradicting exclusions are refused, and family_excluded_outright holds only for a family-only exclusion;
    • matching on timing + operator, unset fields, lifetime and per-entity reduction;
    • family and θ match builds only;
    • aggregate_measure, merged_across_windows, counter semantics and readout;
    • the default expansion, each capability's expansion and the supported-summaries expansion;
    • invalid exclusions, by index;
    • JSON of the sweep's stored arm and of the new fields;
    • SummaryFamily::of and θ range bounds.
  • Stage 2:
    • a caller exclusion prunes like a capability;
    • a capability is named before a caller exclusion;
    • unsupported summaries and readouts are pruned.
  • Stage 3: only exclusions beyond the default deployment's make the rejection, its reason counts them, and it keeps the costing failures.
  • integration:
    • an exclusion matching nothing changes nothing;
    • the KLL k range moves the state from 547 to 1,404, then 2,863;
    • excluding every KLL size gives the exact quantile;
    • the stored arm;
    • excluding the only feasible candidate gives ExcludedByDeployment;
    • Stage 2 counts per index;
    • an empty exclusion is refused;
    • no mergeable rate or increase state;
    • excluding the rate state alone gives Aggregate[rate], until the measure is excluded too;
    • without extrapolation there is no rate plan and irate is unchanged; without reset handling, neither is planned.
  • planner: exclusions reach Stage 2 through plan_installable and e2e_plan.
  • crate_graph: no planning crate reads environment variables. This guard passes on main too.
  • viewer: the deployment line names each capability left out and each supported summary by summary_type, and the new reason reads as words.

Follow-ups

  • Not covered (Plan for a target's deployment capabilities #1370): per-family guarantee kind; window forms; and capability-level allow-lists of operators, measures and θ ranges. Today these can be expressed only as excluded_candidates.
  • CLI: asap_planner --deployment-capabilities reads the new fields, but the stage text does not list the exclusions yet.

@zzylol zzylol added optimizer Workload optimization and plan selection testing Corpus, regression, differential, or benchmark tests labels Nov 16, 2026
…clusion with the capability table (tests only)

Tests for harness PR P1, reworked so that a target's capabilities and the
caller's own exclusions expand into one list of CandidateExclusions that
Stage 2 applies as one filter. Adds the dimensions an external target
needs: a query-time aggregate's measure, state merged across windows
versus built within one evaluation, and counter reset handling and
extrapolation.

Stubs only, so the tests compile: every new function body is todo!(),
validate does not check excluded_candidates, Stage 2 and Stage 3 do not
read the new fields. OperatorKind moves unchanged from asap-cost to
asap-types (re-exported by asap-cost) so exclusions can name operators.
…clusions apply as one Stage 2 filter

DeploymentCapabilities::exclusions expands every capability a deployment
lacks, and the caller's excluded_candidates, into CandidateExclusions with
their source. Stage 2 prunes each matched alternative as
ExcludedByDeployment(source); Stage 3 reports no plan left as
RejectionCause::ExcludedByDeployment. Deletes PruneReason::RawDataNotRetained,
QueryTimeResultsNotRetained, the Pass 1 supported-summaries filter,
DeploymentCapabilities::supports and summary_supported.
…te the p90 KLL fixture

Pass 1 now offers every summary the planner builds, so the KLL-only
fixture's memo also holds the DDSketch readout and states that Pass 2
prunes; Stage 2's reasons for capabilities read as
{"excluded_by_deployment": source}. The viewer renders that reason, and
the capabilities echo lists the new defaulted fields.
@zzylol
zzylol force-pushed the test/deployment-exclusions branch from 94e966e to aa17a02 Compare November 16, 2026 23:49
…ble workload reported as Infeasible

Only exclusion sources the default deployment does not have make the
rejection ExcludedByDeployment, so planning with the defaults reports what
it reported before; a source that pruned one candidate reads "(1 candidate)".
@zzylol zzylol changed the title test(types, stage2, planner): deployment exclusions: one filter for a target's capabilities and the caller's exclusions (tests only) feat(types, stage2, stage3): deployment exclusions: one Stage 2 filter for a target's capabilities and the caller's exclusions Nov 16, 2026
@zzylol
zzylol marked this pull request as ready for review November 16, 2026 23:56
@zzylol zzylol added dag-viewer DAG export and visualization tooling enhancement New feature or request labels Nov 16, 2026
…sions

- Pass 1 skips a summary whose sketch algorithm a summary_family-only
  exclusion from DeploymentCapabilities::exclusions() rules out outright
  (CandidateExclusion::family_excluded_outright), so restricted
  deployments no longer plan every summary; plans are unchanged.
- The ExcludedByDeployment rejection keeps the costing-failure suffix,
  through a helper shared with infeasible.
- validate refuses exclusions whose fields match no operator in common.
- CandidateDescription::of_plan_node moves to the integration test.
- Schema::summary_state_type replaces a duplicate lookup;
  DeploymentExclusion::candidates is renamed exclusion; the viewer reads
  summary_type; a PR number is dropped from a comment.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

dag-viewer DAG export and visualization tooling enhancement New feature or request optimizer Workload optimization and plan selection testing Corpus, regression, differential, or benchmark tests

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant