From 75e8f1cd566a5aeedaf4ccfeabfcb50823a1b452 Mon Sep 17 00:00:00 2001 From: Milind Srivastava Date: Wed, 18 Nov 2026 11:39:13 -0500 Subject: [PATCH 01/27] docs(query-engine): design engine boundaries for ASAPPlanner plans Co-Authored-By: Claude Opus 5.5 --- .design_docs/asapplanner-engine-boundaries.md | 224 ++++++++++++++++++ 1 file changed, 224 insertions(+) create mode 100644 .design_docs/asapplanner-engine-boundaries.md diff --git a/.design_docs/asapplanner-engine-boundaries.md b/.design_docs/asapplanner-engine-boundaries.md new file mode 100644 index 00000000..deeb0297 --- /dev/null +++ b/.design_docs/asapplanner-engine-boundaries.md @@ -0,0 +1,224 @@ +# Engine boundaries for ASAPPlanner plans + +Status: in discussion. This document is the source of truth; update it as decisions change. + +## Context + +ASAPQuery (`asap-query-engine`) has two core engines. The precompute engine +builds sketches at ingest. `SimpleEngine` answers queries from them. Both are +driven by asap-planner-rs output (`StreamingConfig`, `InferenceConfig`). We are +replacing both engines with ones that execute plans from ASAPPlanner +(`../ASAPPlanner`). Those plans arrive as an `InstallablePlan`, which wraps a +`PhysicalASAPDAG` plus the query texts, one per DAG root. This lets us retire +asap-planner-rs. The protocol adapters, fallback clients and ingest decoders +stay. This doc defines the traits and boundaries around the new engines. It +does not cover how the engines are implemented. + +Terms: +- **Summary**: a stored, materialized node of the plan (ASAPPlanner calls it a + `MaterializedView`), identified by its `PhysicalASAPNodeId`. +- **Planned query**: a query whose text is in `InstallablePlan.query_texts`. +- **Capability-matched query**: a query that is not in the plan but can be + answered from the installed summaries. + +## Interfaces: before → after + +Kept unchanged: +- `QueryRequestAdapter`, `QueryResponseAdapter`: still parse requests and format + `QueryResult`. The request struct they return changes (see `QueryRequest`). +- `FallbackClient`: unchanged. +- Ingest decoders (Prometheus remote write, VictoriaMetrics, OTLP, CSV, JSON). + +Changed: +- `ParsedQueryRequest {query, time}` and + `ParsedRangeQueryRequest {query, start, end, step}` → one + `QueryRequest {language, query, eval: Instant{time} | Range{start, end, step}}`. + Times are `i64` ms; the adapters convert from protocol seconds. +- `QueryResult {Vector, Matrix}` → adds `Scalar` and `Table {columns, rows}`. + The SQL response adapters (ClickHouse, Elastic) format `Table`. Today they + flatten `Vector` into rows of label values plus one value, and return 501 for + `Matrix`. +- `HttpProtocolAdapter::handle_runtime_info(Arc)` → takes a + `RuntimeInfoSource` instead of the store. Contents are tabled (T4). +- `IngestSource`: its `IngestContext` holds old-engine routing state + (`SeriesRouter`, `AggregationConfig`-based routing configs). It is replaced by + a handle to `IngestEngine`. `OtlpReceiver`, which bypasses `IngestSource` + today, moves behind it. +- `QueryTracker` → `QueryWorkloadTracker`. It emits ASAPPlanner's + `PlanningWorkload`. +- `HttpServer` holds `Arc` instead of `Arc`. + +Replaced: +- `PlannerClient` (calls asap-planner-rs) → `PlanProvider` (returns an + ASAPPlanner `InstallablePlan`). +- `StreamingConfig` / `InferenceConfig` → `InstalledPlan`. +- `Store`, keyed by `(metric, aggregation_id, window)` with `AggregateCore` + values → `SummaryStore` + `RawDataStore`. +- `SimpleEngine` (a concrete struct) → `QueryEngine` trait. +- `PrecomputeEngine` (a concrete struct) → `IngestEngine` trait. + +Removed from the boundary (internal to the old engines): `AccumulatorUpdater`, +`AggregateCore` and the related aggregate traits, `OutputSink`, `WindowMerger`, +`QueryPlanRuntime`. + +## New interfaces + +Signatures are indicative. Method-level details are still open. + +```rust +struct InstalledPlan { // ASAPQuery's validated view of an InstallablePlan + id: PlanId, + plan: InstallablePlan, // + derived summaries, refresh groups, raw retention +} + +trait PlanProvider { // input: PlanningWorkload + DeploymentCapabilities + // → InstalledPlan, pushed to PlanInstaller. Implementations: from a plan file, + // or in-process ASAPPlanner. +} + +trait IngestEngine { + install(plan); ingest(SampleBatch); flush(); shutdown(); +} + +trait QueryEngine { // steps through range queries itself + install(plan); + execute(plan, &AnswerSource, &QueryRequest) -> Result; +} + +struct PlanInstaller { /* installs each new InstalledPlan into both engines */ } + +trait QueryResolver { // chained: planned resolver, then capability resolver + resolve(plan, &QueryRequest) -> Option; +} + +struct QueryDispatcher { resolvers, engine } // called by HttpServer for every query +// dispatch(&QueryRequest) -> QueryOutcome: +// no resolver matches → NotAnswerable(Unmatched) +// engine → NotReady → NotAnswerable(NotReady) +// engine → Err(e) → NotAnswerable(EngineError(e)) or Failed(e), per error policy +// engine → Ready → Ready + +enum AnswerSource { + Planned { root: RootRef }, // matched InstallablePlan.query_texts + CapabilityMatched { matched: CapabilityMatch }, // contents tabled (T2) +} + +enum EngineQueryResult { + Ready { labels: KeyByLabelNames, result: QueryResult }, + NotReady, // summaries don't yet cover the query → fallback +} + +enum QueryOutcome { + Ready { labels, result, source: AnswerSource }, + NotAnswerable(NotAnswerableReason), // → FallbackClient + Failed(QueryEngineError), // → error response +} +enum NotAnswerableReason { Unmatched, NotReady, EngineError(QueryEngineError) } + +trait SummaryStore { + put(SummaryKey, SummaryState); get(plan, summary, range); evict_before(plan, summary, ts); + earliest_timestamp_per_summary() -> Map; // was get_earliest_timestamp_per_aggregation_id +} +struct SummaryKey { plan: PlanId, summary: PhysicalASAPNodeId, window: (i64, i64) } +struct SummaryState { encoding: EncodingId, bytes: Bytes } // opaque to the store + +trait RawDataStore { append(Source, SampleBatch); read(Source, range); evict(retention, now); } + +enum SampleBatch { + TimeSeries { /* (ts, value, structured label set) rows */ }, // Source::TimeSeries + Table { schema, rows }, // Source::Table +} +``` + +Why `QueryDispatcher`: every query goes through the same three steps: resolve +it to an `AnswerSource`, execute it, and map the result to an answer, a fallback +or an error. Putting this in `HttpServer` would repeat it in every handler +(instant, range, RQE). Putting it in `QueryEngine` would repeat plan matching +and fallback policy in every engine implementation. The dispatcher does it once, +so engines only execute. + +## Decisions + +1. **The contract is ASAPPlanner's plan types, not its executor.** Only + ASAPPlanner's `asap-types` plan types (`InstallablePlan`, `PhysicalASAPDAG`, + `MaterializedView`, `Source`, …) cross ASAPQuery boundaries. The engine + traits must not depend on `asap_executor`, which may change or be retired. +2. **Two engine traits.** `IngestEngine` and `QueryEngine` are the only seams for + the engines. Adapters, fallback and decoders don't know which engine + implementation is behind them. +3. **Fallback.** A query falls back to the real backend when it is not in the + plan and not capability-matched, or when the engine returns `NotReady`. +4. **Answers record their source.** A query result records whether it came from + a planned root or from capability matching (`AnswerSource`). +5. **One place for engine-error policy.** How engine errors map to responses + (fallback or error) is decided in a single place: `QueryDispatcher`. +6. **Query language is on the request.** `QueryRequest` carries the language so + that one deployment can later serve several languages. +7. **Times.** Engines and stores see `i64` ms only. The adapters convert from + protocol times. +8. **Stores.** The deployment owns the stores and injects them into both + engines. They are in-memory only, with no durability: after a restart they + are empty and queries return `NotReady` (→ fallback). Summary keys include + `PlanId`. +9. **Capabilities.** The deployment declares one `DeploymentCapabilities`, which + `PlanProvider` passes to ASAPPlanner. +10. **Workload.** `QueryWorkloadTracker` emits ASAPPlanner's `PlanningWorkload`. +11. **Resolution is whole-query.** An `AnswerSource` covers a whole query; there + is no partial or sub-expression resolution for now. +12. **Raw data enters through `IngestSource`** (via `IngestEngine`; see 23). +13. **Ingest batches.** `SampleBatch` carries structured label sets instead of + today's `labels: String`. It is one enum with a `TimeSeries` variant and a + `Table` variant, matching the plan's two `Source` kinds. +14. **`QueryResult` gains `Scalar` and `Table`.** +15. **RQE endpoint.** It is kept for testing only and removed at the end of the + migration. +16. **`QueryDispatcher`.** It resolves each query, runs the engine and applies + the fallback and error policy. `HttpServer` calls it. +17. **One resolver trait.** `QueryResolver` implementations are chained: the + planned resolver first, then the capability resolver. Split it into + separate traits later if their inputs diverge. +18. **`PlanInstaller`.** One component installs each new plan into both engines. +19. **Range queries.** `QueryEngine` receives the whole range request and + decides how to step through it. +20. **Watermarks, lateness and backpressure.** `IngestEngine` owns them, + configured by deployment config (today's `LateDataPolicy` model). This is + the simplest option, chosen for now. The alternatives were per-source + watermarks, lateness stated in the plan, or a combination. +21. **Plan delivery is push, for now.** `PlanProvider` decides when a new plan + exists (for example, the workload changed or the plan file changed) and + hands it to `PlanInstaller`. +22. **`QueryLanguage` comes from ASAPPlanner.** We use + `asap_types::workload::QueryLanguage` (`PromQL`, `MetricsQL`, + `SQL(DataFusionSQL | ClickhouseSQL | ElasticSQL)`, `DataFusion`, + `ElasticDSL`), which covers ASAPQuery's current enum. +23. **`IngestSource` dependencies.** The deployment owns the engine and the + stores. An `IngestSource` gets only a shared `IngestEngine` handle, + `run(self, engine: Arc)`, and calls `ingest(batch)`. The + engine decides what goes into `RawDataStore`. Sources never write to stores: + otherwise every source would need the plan's raw-data retention, and raw data + the engine rejects as late would still be stored. A cleaner alternative is + for sources to be pure producers (`run(self) -> Stream`, or + sending into a channel) that the deployment forwards to the engine, so sources + know nothing about engines. It isn't chosen for now because it adds stream + or channel wiring. + +## Tabled + +- **T1. Plan swap semantics.** When a new plan is installed, do we drain and + rebuild, or run the old and new plans side by side until the new summaries + cover the needed lookback? This affects `install` versus building engines per + plan. +- **T2. How a capability match is computed.** Ideally this is an ASAPPlanner API + (plan a query against the installed summaries, with no new materialization). + It is not designed yet, so `CapabilityMatch` is a placeholder. +- **T3. Per-request query requirements.** The same query text with different + accuracy requirements collides today (issue #778). Should `QueryRequest` carry + requirements? +- **T4. `RuntimeInfoSource` contents.** + +## Open + +- **Q3. Error policy and `QueryEngineError` variants.** Does an engine error fall + back (`NotAnswerable(EngineError)`) or fail (`Failed`)? Today it fails with a + 500. Does the policy need to tell "plan not executable by this engine" apart + from "execution failed"? If not, a single error type is enough. From 4c875589846f349b7bb7b49913e7536513b00796 Mon Sep 17 00:00:00 2001 From: Milind Srivastava Date: Wed, 18 Nov 2026 14:46:03 -0500 Subject: [PATCH 02/27] docs(query-engine): add query-path pseudocode and record more boundary decisions Co-Authored-By: Claude Opus 5.5 --- .design_docs/asapplanner-engine-boundaries.md | 112 ++++++++++++++++-- 1 file changed, 100 insertions(+), 12 deletions(-) diff --git a/.design_docs/asapplanner-engine-boundaries.md b/.design_docs/asapplanner-engine-boundaries.md index deeb0297..3b0d022c 100644 --- a/.design_docs/asapplanner-engine-boundaries.md +++ b/.design_docs/asapplanner-engine-boundaries.md @@ -26,7 +26,7 @@ Terms: Kept unchanged: - `QueryRequestAdapter`, `QueryResponseAdapter`: still parse requests and format `QueryResult`. The request struct they return changes (see `QueryRequest`). -- `FallbackClient`: unchanged. +- `FallbackClient`: unchanged, except that it takes the merged `QueryRequest`. - Ingest decoders (Prometheus remote write, VictoriaMetrics, OTLP, CSV, JSON). Changed: @@ -37,13 +37,16 @@ Changed: - `QueryResult {Vector, Matrix}` → adds `Scalar` and `Table {columns, rows}`. The SQL response adapters (ClickHouse, Elastic) format `Table`. Today they flatten `Vector` into rows of label values plus one value, and return 501 for - `Matrix`. + `Matrix`. Each response adapter returns an error for result variants it + doesn't support. - `HttpProtocolAdapter::handle_runtime_info(Arc)` → takes a `RuntimeInfoSource` instead of the store. Contents are tabled (T4). - `IngestSource`: its `IngestContext` holds old-engine routing state (`SeriesRouter`, `AggregationConfig`-based routing configs). It is replaced by - a handle to `IngestEngine`. `OtlpReceiver`, which bypasses `IngestSource` - today, moves behind it. + a handle to `IngestEngine`. `OtlpReceiver` becomes an ordinary + `IngestSource`. Today it runs outside `IngestSource`, and the precompute + engine is skipped for OTLP: it decodes points and only logs them, so the + data is dropped. - `QueryTracker` → `QueryWorkloadTracker`. It emits ASAPPlanner's `PlanningWorkload`. - `HttpServer` holds `Arc` instead of `Arc`. @@ -88,7 +91,7 @@ trait QueryEngine { // steps through range queries itself struct PlanInstaller { /* installs each new InstalledPlan into both engines */ } trait QueryResolver { // chained: planned resolver, then capability resolver - resolve(plan, &QueryRequest) -> Option; + resolve(plan, &QueryRequest) -> Option; // None: can't answer it; never fails } struct QueryDispatcher { resolvers, engine } // called by HttpServer for every query @@ -99,7 +102,7 @@ struct QueryDispatcher { resolvers, engine } // called by HttpServer for every // engine → Ready → Ready enum AnswerSource { - Planned { root: RootRef }, // matched InstallablePlan.query_texts + Planned { root: PhysicalASAPNodeId }, // matched InstallablePlan.query_texts CapabilityMatched { matched: CapabilityMatch }, // contents tabled (T2) } @@ -130,12 +133,62 @@ enum SampleBatch { } ``` -Why `QueryDispatcher`: every query goes through the same three steps: resolve -it to an `AnswerSource`, execute it, and map the result to an answer, a fallback -or an error. Putting this in `HttpServer` would repeat it in every handler -(instant, range, RQE). Putting it in `QueryEngine` would repeat plan matching -and fallback policy in every engine implementation. The dispatcher does it once, -so engines only execute. +How these fit together: +- **`QueryResolver`** is one matching strategy. `None` means "this resolver + can't answer this query". +- **`QueryDispatcher`** orchestrates every query in the same three steps: + resolve it to an `AnswerSource`, execute it, and map the result to an answer, + a fallback or an error. Putting this in `HttpServer` would repeat it in every + handler (instant, range, RQE). Putting it in `QueryEngine` would repeat plan + matching and fallback policy in every engine implementation. The dispatcher + does it once, so engines only execute. `QueryResolver` is a trait only so + capability matching (T2) can be replaced without touching the dispatcher. +- **`AnswerSource`** is passed to `QueryEngine::execute` to tell the engine what + to run: a DAG root, or a capability match. The engine doesn't redo matching. +- **`EngineQueryResult`** is what the engine reports. **`QueryOutcome`** is the + dispatcher's final verdict to `HttpServer`, combining the resolver result, the + engine result and the error policy. + +## Query path (pseudocode) + +```rust +// HttpServer: one handler shape for instant and range queries. +async fn handle(http_req) -> Response { + let req: QueryRequest = match adapter.parse(http_req) { + Ok(r) => r, + Err(e) => return adapter.format_error(e), + }; + match dispatcher.dispatch(&req).await { + QueryOutcome::Ready { labels, result, .. } => + adapter.format_success(labels, result), // errors on unsupported result variants + QueryOutcome::NotAnswerable(_) => match fallback { + Some(f) => f.execute(&req).await, + None => adapter.format_unsupported(), + }, + QueryOutcome::Failed(e) => adapter.format_error(e), + } +} + +impl QueryDispatcher { + async fn dispatch(&self, req: &QueryRequest) -> QueryOutcome { + let plan = self.current_plan(); // set by PlanInstaller; one snapshot for the whole query + let Some(source) = self.resolvers.iter().find_map(|r| r.resolve(&plan, req)) else { + return QueryOutcome::NotAnswerable(Unmatched); + }; + match self.engine.execute(&plan, &source, req).await { + Ok(EngineQueryResult::Ready { labels, result }) => QueryOutcome::Ready { labels, result, source }, + Ok(EngineQueryResult::NotReady) => QueryOutcome::NotAnswerable(NotReady), + Err(e) => self.error_policy(e), // NotAnswerable(EngineError(e)) or Failed(e); see Q3 + } + } +} + +// Planned resolver: exact match against the plan's query texts. +fn resolve(plan: &InstalledPlan, req: &QueryRequest) -> Option { + let i = plan.query_texts().position(|q| q == req.query)?; + Some(AnswerSource::Planned { root: plan.dag().roots[i] }) +} +``` ## Decisions @@ -201,6 +254,18 @@ so engines only execute. sending into a channel) that the deployment forwards to the engine, so sources know nothing about engines. It isn't chosen for now because it adds stream or channel wiring. +24. **Resolvers can't fail.** `resolve` returns `None` when it can't answer a + query; it has no error case. +25. **A planned root is a `PhysicalASAPNodeId`.** +26. **`PlanInstaller` validates incoming plans.** If it rejects a plan, the + current plan stays installed. +27. **Install failure.** If installing a plan into either engine fails, the + current plan stays installed. +28. **`DeploymentCapabilities` is a constant** in the code. +29. **Response adapters return an error for result variants they don't + support** (for example, PromQL given `Table`, or SQL given `Matrix`). +30. **Engine implementations are selected by a command-line flag**, so old and + new engines can coexist during the migration. ## Tabled @@ -215,6 +280,12 @@ so engines only execute. accuracy requirements collides today (issue #778). Should `QueryRequest` carry requirements? - **T4. `RuntimeInfoSource` contents.** +- **T5. Store method signatures.** What `SummaryStore::get` returns, who + allocates `EncodingId`, who triggers eviction (at install time or + periodically), and whether `RawDataStore::read` takes predicates. +- **T6. Ingesting pre-built sketches.** OTLP can carry sketch payloads, which + today are decoded and only logged. Should `SampleBatch` accept pre-built + summaries? Out of scope for the MVP; to be done later. ## Open @@ -222,3 +293,20 @@ so engines only execute. back (`NotAnswerable(EngineError)`) or fail (`Failed`)? Today it fails with a 500. Does the policy need to tell "plan not executable by this engine" apart from "execution failed"? If not, a single error type is enough. +- **Q9. Call direction between `PlanProvider` and `PlanInstaller`.** Decision 21 + (push) means the provider calls the installer when a new plan exists. If the + installer calls the provider instead, the installer has to decide when to ask + (pull). +- **Q10. Engine method errors and backpressure.** What errors do `install`, + `ingest` and `flush` return? When the engine is overloaded, does `ingest` wait + until it can accept the batch, or return an error immediately (so a + remote-write source can return 503)? +- **Q11. Label names next to `QueryResult`.** Today output label names + (`KeyByLabelNames`) travel separately from `QueryResult` + (`QueryExecutionResult {query_output_labels, query_result}`). `Table` carries + its own column names, so should label names move into the `Vector`/`Matrix` + variants? +- **Q12. RQE path.** RQE requests are an expression tree (JSON), not a query + text, so they don't fit `QueryRequest` or the resolvers. Should the test-only + RQE endpoint keep calling the old `SimpleEngine` directly until it is removed, + instead of going through the dispatcher? From 79270da5a3dee886fa71029812f4420477ac3f90 Mon Sep 17 00:00:00 2001 From: Milind Srivastava Date: Wed, 18 Nov 2026 15:22:48 -0500 Subject: [PATCH 03/27] docs(query-engine): move label names into QueryResult; RQE bypasses dispatcher Co-Authored-By: Claude Opus 5.5 --- .design_docs/asapplanner-engine-boundaries.md | 42 ++++++++++--------- 1 file changed, 22 insertions(+), 20 deletions(-) diff --git a/.design_docs/asapplanner-engine-boundaries.md b/.design_docs/asapplanner-engine-boundaries.md index 3b0d022c..377a2b10 100644 --- a/.design_docs/asapplanner-engine-boundaries.md +++ b/.design_docs/asapplanner-engine-boundaries.md @@ -107,12 +107,12 @@ enum AnswerSource { } enum EngineQueryResult { - Ready { labels: KeyByLabelNames, result: QueryResult }, + Ready { result: QueryResult }, // label/column names live inside QueryResult NotReady, // summaries don't yet cover the query → fallback } enum QueryOutcome { - Ready { labels, result, source: AnswerSource }, + Ready { result: QueryResult, source: AnswerSource }, NotAnswerable(NotAnswerableReason), // → FallbackClient Failed(QueryEngineError), // → error response } @@ -139,7 +139,7 @@ How these fit together: - **`QueryDispatcher`** orchestrates every query in the same three steps: resolve it to an `AnswerSource`, execute it, and map the result to an answer, a fallback or an error. Putting this in `HttpServer` would repeat it in every - handler (instant, range, RQE). Putting it in `QueryEngine` would repeat plan + handler (instant, range). Putting it in `QueryEngine` would repeat plan matching and fallback policy in every engine implementation. The dispatcher does it once, so engines only execute. `QueryResolver` is a trait only so capability matching (T2) can be replaced without touching the dispatcher. @@ -159,8 +159,8 @@ async fn handle(http_req) -> Response { Err(e) => return adapter.format_error(e), }; match dispatcher.dispatch(&req).await { - QueryOutcome::Ready { labels, result, .. } => - adapter.format_success(labels, result), // errors on unsupported result variants + QueryOutcome::Ready { result, .. } => + adapter.format_success(result), // errors on unsupported result variants QueryOutcome::NotAnswerable(_) => match fallback { Some(f) => f.execute(&req).await, None => adapter.format_unsupported(), @@ -176,7 +176,7 @@ impl QueryDispatcher { return QueryOutcome::NotAnswerable(Unmatched); }; match self.engine.execute(&plan, &source, req).await { - Ok(EngineQueryResult::Ready { labels, result }) => QueryOutcome::Ready { labels, result, source }, + Ok(EngineQueryResult::Ready { result }) => QueryOutcome::Ready { result, source }, Ok(EngineQueryResult::NotReady) => QueryOutcome::NotAnswerable(NotReady), Err(e) => self.error_policy(e), // NotAnswerable(EngineError(e)) or Failed(e); see Q3 } @@ -266,6 +266,15 @@ fn resolve(plan: &InstalledPlan, req: &QueryRequest) -> Option { support** (for example, PromQL given `Table`, or SQL given `Matrix`). 30. **Engine implementations are selected by a command-line flag**, so old and new engines can coexist during the migration. +31. **Label names live inside `QueryResult`.** `Vector` and `Matrix` carry their + output label names, as `Table` carries its columns. This replaces today's + separate `KeyByLabelNames` next to the result + (`QueryExecutionResult {query_output_labels, query_result}`), so every + variant is self-describing. +32. **The RQE endpoint bypasses the dispatcher.** RQE requests are a JSON + expression tree, not a query text, so they don't fit `QueryRequest` or the + resolvers. The test-only endpoint keeps calling the old `SimpleEngine` + directly until it is removed (decision 15). ## Tabled @@ -293,20 +302,13 @@ fn resolve(plan: &InstalledPlan, req: &QueryRequest) -> Option { back (`NotAnswerable(EngineError)`) or fail (`Failed`)? Today it fails with a 500. Does the policy need to tell "plan not executable by this engine" apart from "execution failed"? If not, a single error type is enough. -- **Q9. Call direction between `PlanProvider` and `PlanInstaller`.** Decision 21 - (push) means the provider calls the installer when a new plan exists. If the - installer calls the provider instead, the installer has to decide when to ask - (pull). +- **Q9. Plan components.** Are `PlanProvider` and `PlanInstaller` separate + components, and which one decides when to replan? This may revise decision 21. - **Q10. Engine method errors and backpressure.** What errors do `install`, `ingest` and `flush` return? When the engine is overloaded, does `ingest` wait until it can accept the batch, or return an error immediately (so a - remote-write source can return 503)? -- **Q11. Label names next to `QueryResult`.** Today output label names - (`KeyByLabelNames`) travel separately from `QueryResult` - (`QueryExecutionResult {query_output_labels, query_result}`). `Table` carries - its own column names, so should label names move into the `Vector`/`Matrix` - variants? -- **Q12. RQE path.** RQE requests are an expression tree (JSON), not a query - text, so they don't fit `QueryRequest` or the resolvers. Should the test-only - RQE endpoint keep calling the old `SimpleEngine` directly until it is removed, - instead of going through the dispatcher? + remote-write source can return 503)? Today it waits: samples go to workers + over bounded channels (`channel_buffer_size`, default 10,000) and + `send().await` blocks when a channel is full, so the remote-write HTTP response + is delayed. An error happens only if a worker's channel is closed, and the + source then returns 500. A decode error returns 400. From 1f1e0420fa12f46b55ec480dc70a21ac4a61449b Mon Sep 17 00:00:00 2001 From: Milind Srivastava Date: Wed, 18 Nov 2026 15:28:15 -0500 Subject: [PATCH 04/27] docs(query-engine): drop PlanProvider; data plane triggers replans; ingest waits Co-Authored-By: Claude Opus 5.5 --- .design_docs/asapplanner-engine-boundaries.md | 43 ++++++++++--------- 1 file changed, 22 insertions(+), 21 deletions(-) diff --git a/.design_docs/asapplanner-engine-boundaries.md b/.design_docs/asapplanner-engine-boundaries.md index 377a2b10..bc783127 100644 --- a/.design_docs/asapplanner-engine-boundaries.md +++ b/.design_docs/asapplanner-engine-boundaries.md @@ -52,8 +52,9 @@ Changed: - `HttpServer` holds `Arc` instead of `Arc`. Replaced: -- `PlannerClient` (calls asap-planner-rs) → `PlanProvider` (returns an - ASAPPlanner `InstallablePlan`). +- `PlannerClient` (calls asap-planner-rs) → no trait. `QueryWorkloadTracker` + calls ASAPPlanner (`plan_installable`) directly and hands the result to + `PlanInstaller`. - `StreamingConfig` / `InferenceConfig` → `InstalledPlan`. - `Store`, keyed by `(metric, aggregation_id, window)` with `AggregateCore` values → `SummaryStore` + `RawDataStore`. @@ -74,10 +75,11 @@ struct InstalledPlan { // ASAPQuery's validated view of an Insta plan: InstallablePlan, // + derived summaries, refresh groups, raw retention } -trait PlanProvider { // input: PlanningWorkload + DeploymentCapabilities - // → InstalledPlan, pushed to PlanInstaller. Implementations: from a plan file, - // or in-process ASAPPlanner. +struct PlanInstaller { // validates and installs into both engines + dispatcher + install(InstallablePlan) -> Result<()>; // on any failure, the current plan stays } +// Callers: startup (plan file, if given) and QueryWorkloadTracker +// (plan_installable(workload, DeploymentCapabilities) when it decides to replan). trait IngestEngine { install(plan); ingest(SampleBatch); flush(); shutdown(); @@ -88,8 +90,6 @@ trait QueryEngine { // steps through range queries itself execute(plan, &AnswerSource, &QueryRequest) -> Result; } -struct PlanInstaller { /* installs each new InstalledPlan into both engines */ } - trait QueryResolver { // chained: planned resolver, then capability resolver resolve(plan, &QueryRequest) -> Option; // None: can't answer it; never fails } @@ -214,7 +214,7 @@ fn resolve(plan: &InstalledPlan, req: &QueryRequest) -> Option { are empty and queries return `NotReady` (→ fallback). Summary keys include `PlanId`. 9. **Capabilities.** The deployment declares one `DeploymentCapabilities`, which - `PlanProvider` passes to ASAPPlanner. + `QueryWorkloadTracker` passes to ASAPPlanner when it replans. 10. **Workload.** `QueryWorkloadTracker` emits ASAPPlanner's `PlanningWorkload`. 11. **Resolution is whole-query.** An `AnswerSource` covers a whole query; there is no partial or sub-expression resolution for now. @@ -237,9 +237,12 @@ fn resolve(plan: &InstalledPlan, req: &QueryRequest) -> Option { configured by deployment config (today's `LateDataPolicy` model). This is the simplest option, chosen for now. The alternatives were per-source watermarks, lateness stated in the plan, or a combination. -21. **Plan delivery is push, for now.** `PlanProvider` decides when a new plan - exists (for example, the workload changed or the plan file changed) and - hands it to `PlanInstaller`. +21. **Plan delivery: the data plane decides when to replan, with no plan + trait.** `QueryWorkloadTracker` decides when to replan, calls ASAPPlanner + directly and passes the plan to `PlanInstaller::install`. At startup, a plan + file (if given) is loaded and installed the same way. There is no + `PlanProvider` or plan-source trait: the plan's origin is simply whoever + calls `install`. 22. **`QueryLanguage` comes from ASAPPlanner.** We use `asap_types::workload::QueryLanguage` (`PromQL`, `MetricsQL`, `SQL(DataFusionSQL | ClickhouseSQL | ElasticSQL)`, `DataFusion`, @@ -275,6 +278,12 @@ fn resolve(plan: &InstalledPlan, req: &QueryRequest) -> Option { expression tree, not a query text, so they don't fit `QueryRequest` or the resolvers. The test-only endpoint keeps calling the old `SimpleEngine` directly until it is removed (decision 15). +33. **Ingest backpressure: `ingest` waits** until the engine can accept the + batch, as today. Today samples go to workers over bounded channels + (`channel_buffer_size`, default 10,000) and `send().await` blocks when a + channel is full, delaying the remote-write HTTP response. `ingest` returns an + error only if the engine is gone (today a closed worker channel, which leads + to a 500). ## Tabled @@ -302,13 +311,5 @@ fn resolve(plan: &InstalledPlan, req: &QueryRequest) -> Option { back (`NotAnswerable(EngineError)`) or fail (`Failed`)? Today it fails with a 500. Does the policy need to tell "plan not executable by this engine" apart from "execution failed"? If not, a single error type is enough. -- **Q9. Plan components.** Are `PlanProvider` and `PlanInstaller` separate - components, and which one decides when to replan? This may revise decision 21. -- **Q10. Engine method errors and backpressure.** What errors do `install`, - `ingest` and `flush` return? When the engine is overloaded, does `ingest` wait - until it can accept the batch, or return an error immediately (so a - remote-write source can return 503)? Today it waits: samples go to workers - over bounded channels (`channel_buffer_size`, default 10,000) and - `send().await` blocks when a channel is full, so the remote-write HTTP response - is delayed. An error happens only if a worker's channel is closed, and the - source then returns 500. A decode error returns 400. +- **Q10. Engine method error types.** What errors do `install` and `flush` + return? (Backpressure is decided: decision 33.) From 57cb8bb1775e79cac10a3a70ded8dc670a2eb72a Mon Sep 17 00:00:00 2001 From: Milind Srivastava Date: Wed, 18 Nov 2026 15:51:55 -0500 Subject: [PATCH 05/27] docs(query-engine): add startup/install/ingest pseudocode; record decisions 34-39 Co-Authored-By: Claude Opus 5.5 --- .design_docs/asapplanner-engine-boundaries.md | 108 ++++++++++++++++-- 1 file changed, 96 insertions(+), 12 deletions(-) diff --git a/.design_docs/asapplanner-engine-boundaries.md b/.design_docs/asapplanner-engine-boundaries.md index bc783127..33cf3f0a 100644 --- a/.design_docs/asapplanner-engine-boundaries.md +++ b/.design_docs/asapplanner-engine-boundaries.md @@ -49,7 +49,8 @@ Changed: data is dropped. - `QueryTracker` → `QueryWorkloadTracker`. It emits ASAPPlanner's `PlanningWorkload`. -- `HttpServer` holds `Arc` instead of `Arc`. +- `HttpServer` holds a `QueryDispatcher` (which holds `Arc`) + instead of `Arc`, except with the old engines (decision 34). Replaced: - `PlannerClient` (calls asap-planner-rs) → no trait. `QueryWorkloadTracker` @@ -71,7 +72,7 @@ Signatures are indicative. Method-level details are still open. ```rust struct InstalledPlan { // ASAPQuery's validated view of an InstallablePlan - id: PlanId, + id: PlanId, // counter, incremented per install plan: InstallablePlan, // + derived summaries, refresh groups, raw retention } @@ -85,9 +86,9 @@ trait IngestEngine { install(plan); ingest(SampleBatch); flush(); shutdown(); } -trait QueryEngine { // steps through range queries itself +trait QueryEngine { // holds its installed plan; steps through range queries itself install(plan); - execute(plan, &AnswerSource, &QueryRequest) -> Result; + execute(&AnswerSource, &QueryRequest) -> Result; } trait QueryResolver { // chained: planned resolver, then capability resolver @@ -102,17 +103,17 @@ struct QueryDispatcher { resolvers, engine } // called by HttpServer for every // engine → Ready → Ready enum AnswerSource { - Planned { root: PhysicalASAPNodeId }, // matched InstallablePlan.query_texts - CapabilityMatched { matched: CapabilityMatch }, // contents tabled (T2) + Planned { plan: PlanId, root: PhysicalASAPNodeId }, // matched InstallablePlan.query_texts + CapabilityMatched { plan: PlanId, matched: CapabilityMatch }, // contents tabled (T2) } enum EngineQueryResult { Ready { result: QueryResult }, // label/column names live inside QueryResult - NotReady, // summaries don't yet cover the query → fallback + NotReady, // summaries don't cover the whole query → fallback } enum QueryOutcome { - Ready { result: QueryResult, source: AnswerSource }, + Ready { result: QueryResult, source: AnswerSource }, // source: for logging NotAnswerable(NotAnswerableReason), // → FallbackClient Failed(QueryEngineError), // → error response } @@ -151,6 +152,9 @@ How these fit together: ## Query path (pseudocode) +New engines only. With the old engines (decision 34), `HttpServer` calls +`SimpleEngine` directly, as today. + ```rust // HttpServer: one handler shape for instant and range queries. async fn handle(http_req) -> Response { @@ -171,11 +175,13 @@ async fn handle(http_req) -> Response { impl QueryDispatcher { async fn dispatch(&self, req: &QueryRequest) -> QueryOutcome { - let plan = self.current_plan(); // set by PlanInstaller; one snapshot for the whole query - let Some(source) = self.resolvers.iter().find_map(|r| r.resolve(&plan, req)) else { + let plan = self.current_plan(); // set by PlanInstaller; None before the first install + let Some(source) = plan.and_then(|p| self.resolvers.iter().find_map(|r| r.resolve(&p, req))) else { return QueryOutcome::NotAnswerable(Unmatched); }; - match self.engine.execute(&plan, &source, req).await { + // The engine compares source's PlanId with its installed plan; a mismatch + // (a plan swap between resolve and execute) returns NotReady. + match self.engine.execute(&source, req).await { Ok(EngineQueryResult::Ready { result }) => QueryOutcome::Ready { result, source }, Ok(EngineQueryResult::NotReady) => QueryOutcome::NotAnswerable(NotReady), Err(e) => self.error_policy(e), // NotAnswerable(EngineError(e)) or Failed(e); see Q3 @@ -186,8 +192,59 @@ impl QueryDispatcher { // Planned resolver: exact match against the plan's query texts. fn resolve(plan: &InstalledPlan, req: &QueryRequest) -> Option { let i = plan.query_texts().position(|q| q == req.query)?; - Some(AnswerSource::Planned { root: plan.dag().roots[i] }) + Some(AnswerSource::Planned { plan: plan.id, root: plan.dag().roots[i] }) +} +``` + +## Startup, plan install and ingest path (pseudocode) + +New engines only. With the old engines (decision 34), wiring is as today. + +```rust +// main: the deployment owns the stores and injects them (decision 8). +let summaries = Arc::new(InMemorySummaryStore::new()); +let raw = Arc::new(InMemoryRawDataStore::new()); +let (ingest_engine, query_engine) = engines_for(cli.engine, summaries.clone(), raw.clone()); // decision 30 +let dispatcher = Arc::new(QueryDispatcher::new(resolvers, query_engine.clone())); +let installer = Arc::new(PlanInstaller::new(ingest_engine.clone(), query_engine.clone(), dispatcher.clone())); +if let Some(path) = cli.plan_file { + installer.install(InstallablePlan::from_json(&read(path))?); // failure → no plan; queries fall back +} +for source in ingest_sources { spawn(source.run(ingest_engine.clone())); } // decision 23 +spawn(QueryWorkloadTracker::new(installer.clone()).run()); +HttpServer::new(adapter, dispatcher, fallback).run().await; + +impl PlanInstaller { + fn install(&self, plan: InstallablePlan) -> Result<()> { + let plan = InstalledPlan::validate(plan, self.next_id())?; // reject → current plan stays (26) + // All-or-nothing across the three: if any step fails, the current plan stays (27). + self.ingest_engine.install(plan.clone())?; + self.query_engine.install(plan.clone())?; + self.dispatcher.set_plan(plan); + Ok(()) + } +} + +// QueryWorkloadTracker: the data plane decides when to replan (decision 21). +loop { + // records queries the HttpServer reports + if self.should_replan() { + let plan = asap_planner::plan_installable(self.workload(), DEPLOYMENT_CAPABILITIES)?; + let _ = self.installer.install(plan); + } } + +// An IngestSource, e.g. the remote-write handler. +async fn handle_remote_write(body: Bytes) -> StatusCode { + let Ok(batch) = decode(body) else { return StatusCode::BAD_REQUEST }; + match engine.ingest(batch).await { // waits under backpressure (decision 33) + Ok(()) => StatusCode::NO_CONTENT, + Err(_) => StatusCode::INTERNAL_SERVER_ERROR, // engine gone + } +} + +// IngestEngine::ingest, at the boundary: uses its installed plan to decide what +// to keep; writes RawDataStore and SummaryStore, keying summaries by its PlanId. ``` ## Decisions @@ -284,6 +341,24 @@ fn resolve(plan: &InstalledPlan, req: &QueryRequest) -> Option { channel is full, delaying the remote-write HTTP response. `ingest` returns an error only if the engine is gone (today a closed worker channel, which leads to a 500). +34. **The old engines bypass the new pipeline.** When the flag (decision 30) + selects the old engines, `HttpServer` calls `SimpleEngine` directly and + ingest uses `PrecomputeEngine`, both driven by asap-planner-rs as today. The + dispatcher, resolvers and `PlanInstaller` are used only with the new + engines. +35. **Engines hold their installed plan.** `QueryEngine::execute` takes only the + `AnswerSource` and the request, not the plan. `AnswerSource` carries the + `PlanId` it was resolved against. If the engine's installed plan differs (a + plan swap between resolve and execute), the engine returns `NotReady`, so the + query falls back. +36. **`NotReady` covers the whole query.** If the summaries don't cover the whole + query, the result is `NotReady`: for a range query, if any step isn't + covered; for an instant query, if its time is past what the summaries cover. + There are no partial answers. +37. **`AnswerSource` in `QueryOutcome::Ready` is for logging only.** +38. **`PlanId` is a counter**, incremented per install. +39. **Before the first plan is installed, queries fall back.** The dispatcher has + no plan, so every query is `Unmatched`. ## Tabled @@ -313,3 +388,12 @@ fn resolve(plan: &InstalledPlan, req: &QueryRequest) -> Option { from "execution failed"? If not, a single error type is enough. - **Q10. Engine method error types.** What errors do `install` and `flush` return? (Backpressure is decided: decision 33.) +- **Q13. Capabilities per engine implementation.** Decision 28 makes + `DeploymentCapabilities` a constant; decision 30 picks the engine by flag. Two + new-engine implementations may support different summaries. Should each engine + implementation define its own constant, selected together with the engine? +- **Q14. Ingest before the first plan.** Does `IngestEngine::ingest` drop + batches, or keep raw data, before any plan is installed? +- **Q15. `InstalledPlan` contents.** Does it add anything beyond + `InstallablePlan` + `PlanId` (for example, precomputed summaries, refresh + groups and raw retention), or is it just that pair? From d9d48c6247a616ea7485e84d55ca63df1b0d8fe2 Mon Sep 17 00:00:00 2001 From: Milind Srivastava Date: Wed, 18 Nov 2026 15:54:11 -0500 Subject: [PATCH 06/27] docs(query-engine): record capabilities, pre-plan ingest and InstalledPlan decisions Co-Authored-By: Claude Opus 5.5 --- .design_docs/asapplanner-engine-boundaries.md | 17 +++++++---------- 1 file changed, 7 insertions(+), 10 deletions(-) diff --git a/.design_docs/asapplanner-engine-boundaries.md b/.design_docs/asapplanner-engine-boundaries.md index 33cf3f0a..dd8f5489 100644 --- a/.design_docs/asapplanner-engine-boundaries.md +++ b/.design_docs/asapplanner-engine-boundaries.md @@ -73,7 +73,7 @@ Signatures are indicative. Method-level details are still open. ```rust struct InstalledPlan { // ASAPQuery's validated view of an InstallablePlan id: PlanId, // counter, incremented per install - plan: InstallablePlan, // + derived summaries, refresh groups, raw retention + plan: InstallablePlan, // nothing else; derived data is computed from it } struct PlanInstaller { // validates and installs into both engines + dispatcher @@ -359,6 +359,12 @@ async fn handle_remote_write(body: Bytes) -> StatusCode { 38. **`PlanId` is a counter**, incremented per install. 39. **Before the first plan is installed, queries fall back.** The dispatcher has no plan, so every query is `Unmatched`. +40. **One capabilities constant.** There is one old engine and one new engine, + and only the new engine uses ASAPPlanner, so a single + `DeploymentCapabilities` constant is enough (decision 28). +41. **Ingest before the first plan is dropped.** `IngestEngine::ingest` discards + batches until a plan is installed. +42. **`InstalledPlan` is just `InstallablePlan` + `PlanId`.** ## Tabled @@ -388,12 +394,3 @@ async fn handle_remote_write(body: Bytes) -> StatusCode { from "execution failed"? If not, a single error type is enough. - **Q10. Engine method error types.** What errors do `install` and `flush` return? (Backpressure is decided: decision 33.) -- **Q13. Capabilities per engine implementation.** Decision 28 makes - `DeploymentCapabilities` a constant; decision 30 picks the engine by flag. Two - new-engine implementations may support different summaries. Should each engine - implementation define its own constant, selected together with the engine? -- **Q14. Ingest before the first plan.** Does `IngestEngine::ingest` drop - batches, or keep raw data, before any plan is installed? -- **Q15. `InstalledPlan` contents.** Does it add anything beyond - `InstallablePlan` + `PlanId` (for example, precomputed summaries, refresh - groups and raw retention), or is it just that pair? From 54fe3e1396f4a93850f98f1442dbbd85e8e8f04f Mon Sep 17 00:00:00 2001 From: Milind Srivastava Date: Wed, 18 Nov 2026 15:57:06 -0500 Subject: [PATCH 07/27] docs(query-engine): replace resolver trait with dispatcher-private resolve functions Co-Authored-By: Claude Opus 5.5 --- .design_docs/asapplanner-engine-boundaries.md | 51 ++++++++++--------- 1 file changed, 27 insertions(+), 24 deletions(-) diff --git a/.design_docs/asapplanner-engine-boundaries.md b/.design_docs/asapplanner-engine-boundaries.md index dd8f5489..adec96f9 100644 --- a/.design_docs/asapplanner-engine-boundaries.md +++ b/.design_docs/asapplanner-engine-boundaries.md @@ -91,13 +91,9 @@ trait QueryEngine { // holds its installed plan; steps through execute(&AnswerSource, &QueryRequest) -> Result; } -trait QueryResolver { // chained: planned resolver, then capability resolver - resolve(plan, &QueryRequest) -> Option; // None: can't answer it; never fails -} - -struct QueryDispatcher { resolvers, engine } // called by HttpServer for every query +struct QueryDispatcher { engine } // called by HttpServer for every query // dispatch(&QueryRequest) -> QueryOutcome: -// no resolver matches → NotAnswerable(Unmatched) +// no match (planned, then capability) → NotAnswerable(Unmatched) // engine → NotReady → NotAnswerable(NotReady) // engine → Err(e) → NotAnswerable(EngineError(e)) or Failed(e), per error policy // engine → Ready → Ready @@ -135,19 +131,21 @@ enum SampleBatch { ``` How these fit together: -- **`QueryResolver`** is one matching strategy. `None` means "this resolver - can't answer this query". - **`QueryDispatcher`** orchestrates every query in the same three steps: resolve it to an `AnswerSource`, execute it, and map the result to an answer, a fallback or an error. Putting this in `HttpServer` would repeat it in every handler (instant, range). Putting it in `QueryEngine` would repeat plan matching and fallback policy in every engine implementation. The dispatcher - does it once, so engines only execute. `QueryResolver` is a trait only so - capability matching (T2) can be replaced without touching the dispatcher. + does it once, so engines only execute. +- **Resolving** is matching only: which plan root, or which capability match, + answers this query. It is two private functions of the dispatcher, + `resolve_planned` then `resolve_capability`; `None` means no match. It is not + a trait because there are only two fixed matchers and capability matching is + undesigned (T2). - **`AnswerSource`** is passed to `QueryEngine::execute` to tell the engine what to run: a DAG root, or a capability match. The engine doesn't redo matching. - **`EngineQueryResult`** is what the engine reports. **`QueryOutcome`** is the - dispatcher's final verdict to `HttpServer`, combining the resolver result, the + dispatcher's final verdict to `HttpServer`, combining the match result, the engine result and the error policy. ## Query path (pseudocode) @@ -175,8 +173,9 @@ async fn handle(http_req) -> Response { impl QueryDispatcher { async fn dispatch(&self, req: &QueryRequest) -> QueryOutcome { - let plan = self.current_plan(); // set by PlanInstaller; None before the first install - let Some(source) = plan.and_then(|p| self.resolvers.iter().find_map(|r| r.resolve(&p, req))) else { + // Set by PlanInstaller; None before the first install. + let Some(plan) = self.current_plan() else { return QueryOutcome::NotAnswerable(Unmatched) }; + let Some(source) = resolve_planned(&plan, req).or_else(|| resolve_capability(&plan, req)) else { return QueryOutcome::NotAnswerable(Unmatched); }; // The engine compares source's PlanId with its installed plan; a mismatch @@ -189,11 +188,15 @@ impl QueryDispatcher { } } -// Planned resolver: exact match against the plan's query texts. -fn resolve(plan: &InstalledPlan, req: &QueryRequest) -> Option { +// Exact match against the plan's query texts. +fn resolve_planned(plan: &InstalledPlan, req: &QueryRequest) -> Option { let i = plan.query_texts().position(|q| q == req.query)?; Some(AnswerSource::Planned { plan: plan.id, root: plan.dag().roots[i] }) } + +fn resolve_capability(plan: &InstalledPlan, req: &QueryRequest) -> Option { + None // until capability matching is designed (T2) +} ``` ## Startup, plan install and ingest path (pseudocode) @@ -205,7 +208,7 @@ New engines only. With the old engines (decision 34), wiring is as today. let summaries = Arc::new(InMemorySummaryStore::new()); let raw = Arc::new(InMemoryRawDataStore::new()); let (ingest_engine, query_engine) = engines_for(cli.engine, summaries.clone(), raw.clone()); // decision 30 -let dispatcher = Arc::new(QueryDispatcher::new(resolvers, query_engine.clone())); +let dispatcher = Arc::new(QueryDispatcher::new(query_engine.clone())); let installer = Arc::new(PlanInstaller::new(ingest_engine.clone(), query_engine.clone(), dispatcher.clone())); if let Some(path) = cli.plan_file { installer.install(InstallablePlan::from_json(&read(path))?); // failure → no plan; queries fall back @@ -284,9 +287,9 @@ async fn handle_remote_write(body: Bytes) -> StatusCode { migration. 16. **`QueryDispatcher`.** It resolves each query, runs the engine and applies the fallback and error policy. `HttpServer` calls it. -17. **One resolver trait.** `QueryResolver` implementations are chained: the - planned resolver first, then the capability resolver. Split it into - separate traits later if their inputs diverge. +17. **No resolver trait.** Resolving is two private dispatcher functions, tried + in order: `resolve_planned`, then `resolve_capability`. Add a trait only if + capability matching later needs to be swappable. 18. **`PlanInstaller`.** One component installs each new plan into both engines. 19. **Range queries.** `QueryEngine` receives the whole range request and decides how to step through it. @@ -314,8 +317,8 @@ async fn handle_remote_write(body: Bytes) -> StatusCode { sending into a channel) that the deployment forwards to the engine, so sources know nothing about engines. It isn't chosen for now because it adds stream or channel wiring. -24. **Resolvers can't fail.** `resolve` returns `None` when it can't answer a - query; it has no error case. +24. **Resolving can't fail.** The resolve functions return `None` when they + can't answer a query; they have no error case. 25. **A planned root is a `PhysicalASAPNodeId`.** 26. **`PlanInstaller` validates incoming plans.** If it rejects a plan, the current plan stays installed. @@ -332,8 +335,8 @@ async fn handle_remote_write(body: Bytes) -> StatusCode { (`QueryExecutionResult {query_output_labels, query_result}`), so every variant is self-describing. 32. **The RQE endpoint bypasses the dispatcher.** RQE requests are a JSON - expression tree, not a query text, so they don't fit `QueryRequest` or the - resolvers. The test-only endpoint keeps calling the old `SimpleEngine` + expression tree, not a query text, so they don't fit `QueryRequest` or + query-text matching. The test-only endpoint keeps calling the old `SimpleEngine` directly until it is removed (decision 15). 33. **Ingest backpressure: `ingest` waits** until the engine can accept the batch, as today. Today samples go to workers over bounded channels @@ -344,7 +347,7 @@ async fn handle_remote_write(body: Bytes) -> StatusCode { 34. **The old engines bypass the new pipeline.** When the flag (decision 30) selects the old engines, `HttpServer` calls `SimpleEngine` directly and ingest uses `PrecomputeEngine`, both driven by asap-planner-rs as today. The - dispatcher, resolvers and `PlanInstaller` are used only with the new + dispatcher and `PlanInstaller` are used only with the new engines. 35. **Engines hold their installed plan.** `QueryEngine::execute` takes only the `AnswerSource` and the request, not the plan. `AnswerSource` carries the From c985e5e53e429f5486b438f93ba0bf87e4b3aec1 Mon Sep 17 00:00:00 2001 From: Milind Srivastava Date: Wed, 18 Nov 2026 22:18:39 -0500 Subject: [PATCH 08/27] docs(query-engine): split SummaryId from window key; store medium behind traits; generic ingest handler Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_014qhwq4jq8TFcKGchhF7Hfb --- .design_docs/asapplanner-engine-boundaries.md | 23 +++++++++++-------- 1 file changed, 14 insertions(+), 9 deletions(-) diff --git a/.design_docs/asapplanner-engine-boundaries.md b/.design_docs/asapplanner-engine-boundaries.md index adec96f9..7b6e93c8 100644 --- a/.design_docs/asapplanner-engine-boundaries.md +++ b/.design_docs/asapplanner-engine-boundaries.md @@ -116,10 +116,11 @@ enum QueryOutcome { enum NotAnswerableReason { Unmatched, NotReady, EngineError(QueryEngineError) } trait SummaryStore { - put(SummaryKey, SummaryState); get(plan, summary, range); evict_before(plan, summary, ts); - earliest_timestamp_per_summary() -> Map; // was get_earliest_timestamp_per_aggregation_id + put(SummaryWindowKey, SummaryState); get(SummaryId, range); evict_before(SummaryId, ts); + earliest_timestamp_per_summary() -> Map; // was get_earliest_timestamp_per_aggregation_id } -struct SummaryKey { plan: PlanId, summary: PhysicalASAPNodeId, window: (i64, i64) } +struct SummaryId { plan: PlanId, node: PhysicalASAPNodeId } // one summary +struct SummaryWindowKey { summary: SummaryId, window: (i64, i64) } // one stored window of it struct SummaryState { encoding: EncodingId, bytes: Bytes } // opaque to the store trait RawDataStore { append(Source, SampleBatch); read(Source, range); evict(retention, now); } @@ -237,9 +238,9 @@ loop { } } -// An IngestSource, e.g. the remote-write handler. -async fn handle_remote_write(body: Bytes) -> StatusCode { - let Ok(batch) = decode(body) else { return StatusCode::BAD_REQUEST }; +// An IngestSource's HTTP handler; the protocol (e.g. Prometheus remote write) picks the decoder. +async fn handle_ingestion(protocol: IngestProtocol, body: Bytes) -> StatusCode { + let Ok(batch) = decoder_for(protocol).decode(body) else { return StatusCode::BAD_REQUEST }; match engine.ingest(batch).await { // waits under backpressure (decision 33) Ok(()) => StatusCode::NO_CONTENT, Err(_) => StatusCode::INTERNAL_SERVER_ERROR, // engine gone @@ -270,9 +271,13 @@ async fn handle_remote_write(body: Bytes) -> StatusCode { 7. **Times.** Engines and stores see `i64` ms only. The adapters convert from protocol times. 8. **Stores.** The deployment owns the stores and injects them into both - engines. They are in-memory only, with no durability: after a restart they - are empty and queries return `NotReady` (→ fallback). Summary keys include - `PlanId`. + engines. `SummaryStore` and `RawDataStore` are the boundary; whether an + implementation keeps data in memory, on disk or both is internal to it. The + first implementations are in-memory with no durability: after a restart they + are empty and queries return `NotReady` (→ fallback). Summaries are + identified by `SummaryId {PlanId, PhysicalASAPNodeId}`. A durable + implementation would need summary ids that survive a restart, which a + `PlanId` counter (decision 38) does not. 9. **Capabilities.** The deployment declares one `DeploymentCapabilities`, which `QueryWorkloadTracker` passes to ASAPPlanner when it replans. 10. **Workload.** `QueryWorkloadTracker` emits ASAPPlanner's `PlanningWorkload`. From a3fea1c0b6e2f2a97b32c96209fa25be966d224b Mon Sep 17 00:00:00 2001 From: Milind Srivastava Date: Wed, 18 Nov 2026 22:23:06 -0500 Subject: [PATCH 09/27] docs(query-engine): RawDataBatch, timestamp_range_per_summary, allow executor value types Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_014qhwq4jq8TFcKGchhF7Hfb --- .design_docs/asapplanner-engine-boundaries.md | 37 +++++++++++-------- 1 file changed, 22 insertions(+), 15 deletions(-) diff --git a/.design_docs/asapplanner-engine-boundaries.md b/.design_docs/asapplanner-engine-boundaries.md index 7b6e93c8..e4ff7308 100644 --- a/.design_docs/asapplanner-engine-boundaries.md +++ b/.design_docs/asapplanner-engine-boundaries.md @@ -83,7 +83,7 @@ struct PlanInstaller { // validates and installs into both engin // (plan_installable(workload, DeploymentCapabilities) when it decides to replan). trait IngestEngine { - install(plan); ingest(SampleBatch); flush(); shutdown(); + install(plan); ingest(RawDataBatch); flush(); shutdown(); } trait QueryEngine { // holds its installed plan; steps through range queries itself @@ -117,17 +117,17 @@ enum NotAnswerableReason { Unmatched, NotReady, EngineError(QueryEngineError) } trait SummaryStore { put(SummaryWindowKey, SummaryState); get(SummaryId, range); evict_before(SummaryId, ts); - earliest_timestamp_per_summary() -> Map; // was get_earliest_timestamp_per_aggregation_id + timestamp_range_per_summary() -> Map; // was get_earliest_timestamp_per_aggregation_id } struct SummaryId { plan: PlanId, node: PhysicalASAPNodeId } // one summary struct SummaryWindowKey { summary: SummaryId, window: (i64, i64) } // one stored window of it struct SummaryState { encoding: EncodingId, bytes: Bytes } // opaque to the store -trait RawDataStore { append(Source, SampleBatch); read(Source, range); evict(retention, now); } +trait RawDataStore { append(Source, RawDataBatch); read(Source, range); evict(retention, now); } -enum SampleBatch { - TimeSeries { /* (ts, value, structured label set) rows */ }, // Source::TimeSeries - Table { schema, rows }, // Source::Table +enum RawDataBatch { // raw input only; never data between operators + TimeSeries { series: Vec<(LabelSet, Vec<(i64, f64)>)> }, // Source::TimeSeries + Table(arrow::RecordBatch), // Source::Table } ``` @@ -253,10 +253,12 @@ async fn handle_ingestion(protocol: IngestProtocol, body: Bytes) -> StatusCode { ## Decisions -1. **The contract is ASAPPlanner's plan types, not its executor.** Only - ASAPPlanner's `asap-types` plan types (`InstallablePlan`, `PhysicalASAPDAG`, - `MaterializedView`, `Source`, …) cross ASAPQuery boundaries. The engine - traits must not depend on `asap_executor`, which may change or be retired. +1. **The contract is ASAPPlanner's plan types, not its executor.** ASAPPlanner's + `asap-types` plan types (`InstallablePlan`, `PhysicalASAPDAG`, + `MaterializedView`, `Source`, …) cross ASAPQuery boundaries. Executor value + types may appear where they fit, but the traits must not depend on the + executor's runtime (`compile`, `RunContext`, `DataStore`), which may change or + be retired. 2. **Two engine traits.** `IngestEngine` and `QueryEngine` are the only seams for the engines. Adapters, fallback and decoders don't know which engine implementation is behind them. @@ -284,9 +286,14 @@ async fn handle_ingestion(protocol: IngestProtocol, body: Bytes) -> StatusCode { 11. **Resolution is whole-query.** An `AnswerSource` covers a whole query; there is no partial or sub-expression resolution for now. 12. **Raw data enters through `IngestSource`** (via `IngestEngine`; see 23). -13. **Ingest batches.** `SampleBatch` carries structured label sets instead of - today's `labels: String`. It is one enum with a `TimeSeries` variant and a - `Table` variant, matching the plan's two `Source` kinds. +13. **Raw data batches.** `RawDataBatch` (named after ASAPPlanner's + `read_raw_data`) is raw input only: what `IngestSource` passes to + `IngestEngine::ingest` and what `RawDataStore` appends and returns. Data + between operators is internal to the engine. It is one enum matching the + plan's two `Source` kinds. `TimeSeries` holds per-series structured label + sets (instead of today's `labels: String`), since series in one batch have + different labels. `Table` is a plain Arrow `RecordBatch`, not the executor's + `Batch`, which needs one schema per batch and carries sketch-state columns. 14. **`QueryResult` gains `Scalar` and `Table`.** 15. **RQE endpoint.** It is kept for testing only and removed at the end of the migration. @@ -318,7 +325,7 @@ async fn handle_ingestion(protocol: IngestProtocol, body: Bytes) -> StatusCode { engine decides what goes into `RawDataStore`. Sources never write to stores: otherwise every source would need the plan's raw-data retention, and raw data the engine rejects as late would still be stored. A cleaner alternative is - for sources to be pure producers (`run(self) -> Stream`, or + for sources to be pure producers (`run(self) -> Stream`, or sending into a channel) that the deployment forwards to the engine, so sources know nothing about engines. It isn't chosen for now because it adds stream or channel wiring. @@ -391,7 +398,7 @@ async fn handle_ingestion(protocol: IngestProtocol, body: Bytes) -> StatusCode { allocates `EncodingId`, who triggers eviction (at install time or periodically), and whether `RawDataStore::read` takes predicates. - **T6. Ingesting pre-built sketches.** OTLP can carry sketch payloads, which - today are decoded and only logged. Should `SampleBatch` accept pre-built + today are decoded and only logged. Should `RawDataBatch` accept pre-built summaries? Out of scope for the MVP; to be done later. ## Open From c18058ff036b577ea1b4e5738e2abe53b7240b8b Mon Sep 17 00:00:00 2001 From: Milind Srivastava Date: Thu, 19 Nov 2026 09:58:35 -0500 Subject: [PATCH 10/27] docs(query-engine): implementation plan and decisions I1-I7 Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_014qhwq4jq8TFcKGchhF7Hfb --- .design_docs/asapplanner-engine-boundaries.md | 68 +++++++++++++++++-- 1 file changed, 64 insertions(+), 4 deletions(-) diff --git a/.design_docs/asapplanner-engine-boundaries.md b/.design_docs/asapplanner-engine-boundaries.md index e4ff7308..7cacc10a 100644 --- a/.design_docs/asapplanner-engine-boundaries.md +++ b/.design_docs/asapplanner-engine-boundaries.md @@ -121,7 +121,7 @@ trait SummaryStore { } struct SummaryId { plan: PlanId, node: PhysicalASAPNodeId } // one summary struct SummaryWindowKey { summary: SummaryId, window: (i64, i64) } // one stored window of it -struct SummaryState { encoding: EncodingId, bytes: Bytes } // opaque to the store +struct SummaryState(Arc); // the engine's native state, opaque to the store (I6) trait RawDataStore { append(Source, RawDataBatch); read(Source, range); evict(retention, now); } @@ -381,6 +381,66 @@ async fn handle_ingestion(protocol: IngestProtocol, body: Bytes) -> StatusCode { batches until a plan is installed. 42. **`InstalledPlan` is just `InstallablePlan` + `PlanId`.** +## Implementation plan + +Small single-purpose PRs; the repo stays runnable at every merge. + +- **Phase 0, dependency.** ASAPPlanner as a git dependency pinned to a commit + (`asap-types`, renamed to avoid clashing with ASAPQuery's `asap_types`, and + `asap-planner`). +- **Phase 1, boundary types with the old engines behind them** (no behavior + change): `QueryRequest`; `QueryResult` `Scalar`/`Table`; + `RuntimeInfoSource`; `OtlpReceiver` behind `IngestSource`, `handle_ingestion`. +- **Phase 2, new traits and plumbing, tested with fake engines:** the traits, + in-memory stores, `QueryDispatcher`, `PlanInstaller`. +- **Phase 3, new engine path:** `--engine` flag, first engines, `--plan-file`, + one PromQL instant query end to end; then ingest via `RawDataBatch`, range + queries, the remaining query types; then `QueryWorkloadTracker`. +- **Phase 4, retire:** pass the gate (I4), then delete `SimpleEngine`, + `PrecomputeEngine`, asap-planner-rs, `PlannerClient`, + `StreamingConfig`/`InferenceConfig` and the RQE endpoint, one PR each. + +Implementation decisions: + +- **I1. The first `QueryEngine` wraps `asap-executor`'s query path.** Its + `RunContext` is `!Send`, so it runs on a dedicated engine thread. Its + `read_materialized_view` serves states from `SummaryStore` by downcast (I6). + The traits let us replace it later (decision 1). +- **I7. The first `IngestEngine` is our own push-based streaming engine,** + modeled on today's precompute engine (route series, per-window updaters in + workers, seal into `SummaryStore` when the watermark passes a window's end + plus lateness). The executor's ingestion is pull-based: it refreshes each + tumbling window once, after it closes, by reading the window's raw rows, + so every sample would be buffered for a window even when the plan keeps no + raw data. What to build comes from the plan's ingestion subgraphs instead of + `AggregationConfig`. States are built with the executor's kernel factory + (`AccumulatorUpdater`), so they are the executor's `AggregateCore` and the + query engine reads them without conversion. It writes to `RawDataStore` only + what the plan's raw-data retention requires. +- **I2. Phase 1 before the new engine path**, so the dispatcher is built on + `QueryRequest` from the start and Phase 1 PRs are useful on their own. +- **I3. ASAPPlanner is a pinned git dependency.** +- **I4. Gate for deleting the old engines.** Old and new run different plans, + so their answers are not compared with each other. On a fixed set of + benchmark workloads: (1) coverage: every query the old engine answers without + fallback, the new engine answers too once its summaries cover it; (2) + accuracy: every new answer meets the `AccuracyTarget` its query was planned + with (ε, allowing δ failures), against the exact + answer from the backend (Prometheus or ClickHouse via the fallback client), + and exactly-answered queries match exactly. Performance and memory are not + part of the gate. +- **I5. One deployment-wide default `AccuracyTarget`** (config or CLI), which + `QueryWorkloadTracker` puts on every query it records. ASAPPlanner treats a + query without one as exact, so the planner would never choose sketches. A + plan file is planned with its own workload's targets; keep that workload with + it so I4 can check against them. +- **I6. `SummaryStore` holds the engine's native state**, as an opaque + `SummaryState(Arc)` the engine downcasts. Bytes would + cost a decode on every query read (the executor reads summaries as live + `AggregateCore` objects; today's `Store` holds them too). Executor types in + the trait would tie the store to the executor. A durable store would need an + engine encode method, added when durability is. + ## Tabled - **T1. Plan swap semantics.** When a new plan is installed, do we drain and @@ -394,9 +454,9 @@ async fn handle_ingestion(protocol: IngestProtocol, body: Bytes) -> StatusCode { accuracy requirements collides today (issue #778). Should `QueryRequest` carry requirements? - **T4. `RuntimeInfoSource` contents.** -- **T5. Store method signatures.** What `SummaryStore::get` returns, who - allocates `EncodingId`, who triggers eviction (at install time or - periodically), and whether `RawDataStore::read` takes predicates. +- **T5. Store method signatures.** Who triggers eviction (at install time or + periodically), and whether `RawDataStore::read` takes predicates. (What + `SummaryStore` holds is decided: I6.) - **T6. Ingesting pre-built sketches.** OTLP can carry sketch payloads, which today are decoded and only logged. Should `RawDataBatch` accept pre-built summaries? Out of scope for the MVP; to be done later. From 6405b66909d90e699a49dd83e0843fed5abe34ef Mon Sep 17 00:00:00 2001 From: Milind Srivastava Date: Thu, 19 Nov 2026 10:06:46 -0500 Subject: [PATCH 11/27] docs(query-engine): ingest operator subset (I8) and shared precompute pipeline (I9) Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_014qhwq4jq8TFcKGchhF7Hfb --- .design_docs/asapplanner-engine-boundaries.md | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/.design_docs/asapplanner-engine-boundaries.md b/.design_docs/asapplanner-engine-boundaries.md index 7cacc10a..f97a18e2 100644 --- a/.design_docs/asapplanner-engine-boundaries.md +++ b/.design_docs/asapplanner-engine-boundaries.md @@ -392,7 +392,8 @@ Small single-purpose PRs; the repo stays runnable at every merge. change): `QueryRequest`; `QueryResult` `Scalar`/`Table`; `RuntimeInfoSource`; `OtlpReceiver` behind `IngestSource`, `handle_ingestion`. - **Phase 2, new traits and plumbing, tested with fake engines:** the traits, - in-memory stores, `QueryDispatcher`, `PlanInstaller`. + in-memory stores, `QueryDispatcher`, `PlanInstaller`. Split + `PrecomputeEngine` into pipeline + build specification (I9). - **Phase 3, new engine path:** `--engine` flag, first engines, `--plan-file`, one PromQL instant query end to end; then ingest via `RawDataBatch`, range queries, the remaining query types; then `QueryWorkloadTracker`. @@ -417,6 +418,22 @@ Implementation decisions: (`AccumulatorUpdater`), so they are the executor's `AggregateCore` and the query engine reads them without conversion. It writes to `RawDataStore` only what the plan's raw-data retention requires. +- **I8. Ingest-time operators the push engine runs (v1):** `Scan` of one + `TimeSeries` source, `Filter`, `Project`, `Aggregate` (exact), and the + sketch builds `SummaryAgg` and `SummaryTumblingWindowChain`. `Table` + sources come later. The capabilities constant (decision 28) steers the + planner to this subset: `excluded_candidates` excludes every other + ingestion-time operator, and `supported_summaries` lists only the executor + kernel factory's sketch types. `PlanInstaller` validation (decision 26) + rejects a plan that still uses another ingestion-time operator; the current + plan stays. +- **I9. The push engine reuses today's precompute pipeline.** A + no-behavior-change PR first splits `PrecomputeEngine` into a generic pipeline + (series routing, workers, windows, watermark and late-data policy, + backpressure) and a build specification it is given (what to build per series + and where to write it). The old engine supplies an `AggregationConfig`-based + one and its tests must pass unchanged; the new `IngestEngine` supplies a + plan-based one (I8). Windowing and lateness logic then exists once. - **I2. Phase 1 before the new engine path**, so the dispatcher is built on `QueryRequest` from the start and Phase 1 PRs are useful on their own. - **I3. ASAPPlanner is a pinned git dependency.** From b6682e31ab0bb059c43b5ab7bab4a6ab3d36da85 Mon Sep 17 00:00:00 2001 From: Milind Srivastava Date: Thu, 19 Nov 2026 10:11:55 -0500 Subject: [PATCH 12/27] docs(query-engine): NotReady by running (I10), strict evaluation time (I11), T7 Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_014qhwq4jq8TFcKGchhF7Hfb --- .design_docs/asapplanner-engine-boundaries.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/.design_docs/asapplanner-engine-boundaries.md b/.design_docs/asapplanner-engine-boundaries.md index f97a18e2..ad36cd71 100644 --- a/.design_docs/asapplanner-engine-boundaries.md +++ b/.design_docs/asapplanner-engine-boundaries.md @@ -434,6 +434,17 @@ Implementation decisions: and where to write it). The old engine supplies an `AggregationConfig`-based one and its tests must pass unchanged; the new `IngestEngine` supplies a plan-based one (I8). Windowing and lateness logic then exists once. +- **I10. `NotReady` is detected by running, not by a pre-check.** The + executor reads only stored windows that exactly cover the requested range, + and requires an error for a missing one. Our `DataStore` adapter returns a + distinct missing-window error, which the engine maps to `NotReady`; other + executor errors are `Err` (Q3). A pre-check would duplicate the executor's + window arithmetic. In a range query, the first missing step makes the whole + query `NotReady` (decision 36). +- **I11. Strict evaluation time.** A query is answered at exactly its `T`, or + is `NotReady`. The engine never rounds `T` down to the newest sealed window + and never reads the ingest engine's open windows. Queries at "now" therefore + fall back until the newest window is sealed (T7). - **I2. Phase 1 before the new engine path**, so the dispatcher is built on `QueryRequest` from the start and Phase 1 PRs are useful on their own. - **I3. ASAPPlanner is a pinned git dependency.** @@ -478,6 +489,10 @@ Implementation decisions: today are decoded and only logged. Should `RawDataBatch` accept pre-built summaries? Out of scope for the MVP; to be done later. +- **T7. Freshness at "now".** If fallback for queries at "now" dominates in + benchmarks, allow a configured staleness tolerance (answer from the newest + sealed window) or read the open window's state from the ingest engine. + ## Open - **Q3. Error policy and `QueryEngineError` variants.** Does an engine error fall From 4aedfe30359a7f236d3f1479d171cc33c45e9d89 Mon Sep 17 00:00:00 2001 From: Milind Srivastava Date: Thu, 19 Nov 2026 10:13:00 -0500 Subject: [PATCH 13/27] docs(query-engine): engine errors fall back (I12), closes Q3 Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_014qhwq4jq8TFcKGchhF7Hfb --- .design_docs/asapplanner-engine-boundaries.md | 23 ++++++++++--------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/.design_docs/asapplanner-engine-boundaries.md b/.design_docs/asapplanner-engine-boundaries.md index ad36cd71..011a3ebd 100644 --- a/.design_docs/asapplanner-engine-boundaries.md +++ b/.design_docs/asapplanner-engine-boundaries.md @@ -95,7 +95,7 @@ struct QueryDispatcher { engine } // called by HttpServer for every query // dispatch(&QueryRequest) -> QueryOutcome: // no match (planned, then capability) → NotAnswerable(Unmatched) // engine → NotReady → NotAnswerable(NotReady) -// engine → Err(e) → NotAnswerable(EngineError(e)) or Failed(e), per error policy +// engine → Err(e) → NotAnswerable(EngineError(e)), logged and counted (I12) // engine → Ready → Ready enum AnswerSource { @@ -111,7 +111,6 @@ enum EngineQueryResult { enum QueryOutcome { Ready { result: QueryResult, source: AnswerSource }, // source: for logging NotAnswerable(NotAnswerableReason), // → FallbackClient - Failed(QueryEngineError), // → error response } enum NotAnswerableReason { Unmatched, NotReady, EngineError(QueryEngineError) } @@ -146,8 +145,9 @@ How these fit together: - **`AnswerSource`** is passed to `QueryEngine::execute` to tell the engine what to run: a DAG root, or a capability match. The engine doesn't redo matching. - **`EngineQueryResult`** is what the engine reports. **`QueryOutcome`** is the - dispatcher's final verdict to `HttpServer`, combining the match result, the - engine result and the error policy. + dispatcher's final verdict to `HttpServer`, combining the match result and + the engine result. Engine errors fall back (I12), so there is no failure + variant. ## Query path (pseudocode) @@ -168,7 +168,6 @@ async fn handle(http_req) -> Response { Some(f) => f.execute(&req).await, None => adapter.format_unsupported(), }, - QueryOutcome::Failed(e) => adapter.format_error(e), } } @@ -184,7 +183,7 @@ impl QueryDispatcher { match self.engine.execute(&source, req).await { Ok(EngineQueryResult::Ready { result }) => QueryOutcome::Ready { result, source }, Ok(EngineQueryResult::NotReady) => QueryOutcome::NotAnswerable(NotReady), - Err(e) => self.error_policy(e), // NotAnswerable(EngineError(e)) or Failed(e); see Q3 + Err(e) => { self.count_engine_error(&e); QueryOutcome::NotAnswerable(EngineError(e)) } // I12 } } } @@ -438,13 +437,19 @@ Implementation decisions: executor reads only stored windows that exactly cover the requested range, and requires an error for a missing one. Our `DataStore` adapter returns a distinct missing-window error, which the engine maps to `NotReady`; other - executor errors are `Err` (Q3). A pre-check would duplicate the executor's + executor errors are `Err` (I12). A pre-check would duplicate the executor's window arithmetic. In a range query, the first missing step makes the whole query `NotReady` (decision 36). - **I11. Strict evaluation time.** A query is answered at exactly its `T`, or is `NotReady`. The engine never rounds `T` down to the newest sealed window and never reads the ingest engine's open windows. Queries at "now" therefore fall back until the newest window is sealed (T7). +- **I12. Engine errors fall back** (`NotAnswerable(EngineError)`), and are + logged and counted so engine bugs stay visible (the counter is exposed via + `RuntimeInfoSource`, T4, or logs). Today they return a 500; falling back + still gives the user a correct answer. `QueryOutcome` has no failure variant; + only a failing fallback is an error response. The policy doesn't tell error + kinds apart, so `QueryEngineError` is a single type. - **I2. Phase 1 before the new engine path**, so the dispatcher is built on `QueryRequest` from the start and Phase 1 PRs are useful on their own. - **I3. ASAPPlanner is a pinned git dependency.** @@ -495,9 +500,5 @@ Implementation decisions: ## Open -- **Q3. Error policy and `QueryEngineError` variants.** Does an engine error fall - back (`NotAnswerable(EngineError)`) or fail (`Failed`)? Today it fails with a - 500. Does the policy need to tell "plan not executable by this engine" apart - from "execution failed"? If not, a single error type is enough. - **Q10. Engine method error types.** What errors do `install` and `flush` return? (Backpressure is decided: decision 33.) From 36af1bd8586a05ad07ff4a81396a8f6224717fc2 Mon Sep 17 00:00:00 2001 From: Milind Srivastava Date: Thu, 19 Nov 2026 10:17:55 -0500 Subject: [PATCH 14/27] docs(query-engine): drop flush, InstallError (I13), closes Q10 Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_014qhwq4jq8TFcKGchhF7Hfb --- .design_docs/asapplanner-engine-boundaries.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/.design_docs/asapplanner-engine-boundaries.md b/.design_docs/asapplanner-engine-boundaries.md index 011a3ebd..1773d983 100644 --- a/.design_docs/asapplanner-engine-boundaries.md +++ b/.design_docs/asapplanner-engine-boundaries.md @@ -83,11 +83,11 @@ struct PlanInstaller { // validates and installs into both engin // (plan_installable(workload, DeploymentCapabilities) when it decides to replan). trait IngestEngine { - install(plan); ingest(RawDataBatch); flush(); shutdown(); + install(plan) -> Result<(), InstallError>; ingest(RawDataBatch); shutdown(); // closes windows on its own timer } trait QueryEngine { // holds its installed plan; steps through range queries itself - install(plan); + install(plan) -> Result<(), InstallError>; execute(&AnswerSource, &QueryRequest) -> Result; } @@ -450,6 +450,13 @@ Implementation decisions: still gives the user a correct answer. `QueryOutcome` has no failure variant; only a failing fallback is an error response. The policy doesn't tell error kinds apart, so `QueryEngineError` is a single type. +- **I13. No `flush` on `IngestEngine`.** Closing idle windows stays inside the + engine on its own timer, as today's precompute engine does; nothing outside + calls it, and with no durability there is nothing to flush at shutdown. Tests + close windows by ingesting samples that advance the watermark. `install` + returns `Result<(), InstallError>`, a single type with a message: + `PlanInstaller` only needs failure (keep the current plan, decision 27) and a + reason to log. `shutdown` is best-effort and returns nothing. - **I2. Phase 1 before the new engine path**, so the dispatcher is built on `QueryRequest` from the start and Phase 1 PRs are useful on their own. - **I3. ASAPPlanner is a pinned git dependency.** @@ -500,5 +507,4 @@ Implementation decisions: ## Open -- **Q10. Engine method error types.** What errors do `install` and `flush` - return? (Backpressure is decided: decision 33.) +None currently. From ad6e4344b1953c28378701471d2ff705afcf2938 Mon Sep 17 00:00:00 2001 From: Milind Srivastava Date: Thu, 19 Nov 2026 10:23:48 -0500 Subject: [PATCH 15/27] docs(query-engine): v1 installs once (I14) Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_014qhwq4jq8TFcKGchhF7Hfb --- .design_docs/asapplanner-engine-boundaries.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/.design_docs/asapplanner-engine-boundaries.md b/.design_docs/asapplanner-engine-boundaries.md index 1773d983..9926f165 100644 --- a/.design_docs/asapplanner-engine-boundaries.md +++ b/.design_docs/asapplanner-engine-boundaries.md @@ -457,6 +457,11 @@ Implementation decisions: returns `Result<(), InstallError>`, a single type with a message: `PlanInstaller` only needs failure (keep the current plan, decision 27) and a reason to log. `shutdown` is best-effort and returns nothing. +- **I14. v1 installs once.** `PlanInstaller` accepts only the first plan; + `QueryWorkloadTracker` keeps replanning and logs later plans without + installing them, as today's `QueryTracker` does. Plan swap (T1) stays tabled; + `install`, `PlanId` in summary keys and `NotReady` on a `PlanId` mismatch + already leave room for it. - **I2. Phase 1 before the new engine path**, so the dispatcher is built on `QueryRequest` from the start and Phase 1 PRs are useful on their own. - **I3. ASAPPlanner is a pinned git dependency.** @@ -486,7 +491,7 @@ Implementation decisions: - **T1. Plan swap semantics.** When a new plan is installed, do we drain and rebuild, or run the old and new plans side by side until the new summaries cover the needed lookback? This affects `install` versus building engines per - plan. + plan. v1 sidesteps this (I14). - **T2. How a capability match is computed.** Ideally this is an ASAPPlanner API (plan a query against the installed summaries, with no new materialization). It is not designed yet, so `CapabilityMatch` is a placeholder. From ea0b537889393e087cd9955a5be7f1f42f5ebde4 Mon Sep 17 00:00:00 2001 From: Milind Srivastava Date: Thu, 19 Nov 2026 10:27:52 -0500 Subject: [PATCH 16/27] docs(query-engine): query engine thread pool (I15) Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_014qhwq4jq8TFcKGchhF7Hfb --- .design_docs/asapplanner-engine-boundaries.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/.design_docs/asapplanner-engine-boundaries.md b/.design_docs/asapplanner-engine-boundaries.md index 9926f165..2c875e58 100644 --- a/.design_docs/asapplanner-engine-boundaries.md +++ b/.design_docs/asapplanner-engine-boundaries.md @@ -462,6 +462,12 @@ Implementation decisions: installing them, as today's `QueryTracker` does. Plan swap (T1) stays tabled; `install`, `PlanId` in summary keys and `NotReady` on a `PlanId` mismatch already leave room for it. +- **I15. The executor-backed `QueryEngine` runs a pool of N engine threads** + (deployment config, default the CPU count). Each compiles the installed plan + itself and instantiates it against one shared `DataStore` adapter; queries are + dispatched round-robin over per-thread channels. One thread would serialize + every query, where today's `SimpleEngine` serves them concurrently. + Compiling per thread avoids relying on the compiled plan being `Send`. - **I2. Phase 1 before the new engine path**, so the dispatcher is built on `QueryRequest` from the start and Phase 1 PRs are useful on their own. - **I3. ASAPPlanner is a pinned git dependency.** From 3e3f9892a4296dbaf88bd45c9e1d4ea2054a5ed9 Mon Sep 17 00:00:00 2001 From: Milind Srivastava Date: Thu, 19 Nov 2026 10:29:15 -0500 Subject: [PATCH 17/27] docs(query-engine): late data Drop only (I16), T8 Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_014qhwq4jq8TFcKGchhF7Hfb --- .design_docs/asapplanner-engine-boundaries.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/.design_docs/asapplanner-engine-boundaries.md b/.design_docs/asapplanner-engine-boundaries.md index 2c875e58..404a3007 100644 --- a/.design_docs/asapplanner-engine-boundaries.md +++ b/.design_docs/asapplanner-engine-boundaries.md @@ -468,6 +468,11 @@ Implementation decisions: dispatched round-robin over per-thread channels. One thread would serialize every query, where today's `SimpleEngine` serves them concurrently. Compiling per thread avoids relying on the compiled plan being `Send`. +- **I16. Late data: only `Drop`.** Samples later than the allowed lateness are + dropped; a sealed window never changes. Every query run then reads a + consistent store state, and each window has exactly one state, as the + executor's `DataStore` contract requires, with no snapshots or locking. + `ForwardToStore` is tabled (T8). - **I2. Phase 1 before the new engine path**, so the dispatcher is built on `QueryRequest` from the start and Phase 1 PRs are useful on their own. - **I3. ASAPPlanner is a pinned git dependency.** @@ -515,6 +520,8 @@ Implementation decisions: - **T7. Freshness at "now".** If fallback for queries at "now" dominates in benchmarks, allow a configured staleness tolerance (answer from the newest sealed window) or read the open window's state from the ingest engine. +- **T8. `ForwardToStore` late data.** Merging late samples into sealed windows + needs merge-on-read (one state per window) and snapshot reads per query run. ## Open From 118e7e890c2ab8f3b3dee1d7260ae703c0ecf68b Mon Sep 17 00:00:00 2001 From: Milind Srivastava Date: Thu, 19 Nov 2026 10:40:36 -0500 Subject: [PATCH 18/27] docs(query-engine): query engine evicts by time (I17) Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_014qhwq4jq8TFcKGchhF7Hfb --- .design_docs/asapplanner-engine-boundaries.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/.design_docs/asapplanner-engine-boundaries.md b/.design_docs/asapplanner-engine-boundaries.md index 404a3007..ab889f02 100644 --- a/.design_docs/asapplanner-engine-boundaries.md +++ b/.design_docs/asapplanner-engine-boundaries.md @@ -473,6 +473,13 @@ Implementation decisions: consistent store state, and each window has exactly one state, as the executor's `DataStore` contract requires, with no snapshots or locking. `ForwardToStore` is tabled (T8). +- **I17. Only the query engine evicts, by time.** The ingest engine never + evicts. The query engine tracks the latest evaluation time it has served + (a range query's end) and, after each query, evicts each summary's windows + before `latest_T − retention_ms` and raw data past the plan's raw-data + retention. This uses the planner's retentions as given; today's read-count + policy (`ReadBased`) would need a read count the plan doesn't have. With no + queries nothing is evicted, as with `ReadBased` today. - **I2. Phase 1 before the new engine path**, so the dispatcher is built on `QueryRequest` from the start and Phase 1 PRs are useful on their own. - **I3. ASAPPlanner is a pinned git dependency.** @@ -510,9 +517,9 @@ Implementation decisions: accuracy requirements collides today (issue #778). Should `QueryRequest` carry requirements? - **T4. `RuntimeInfoSource` contents.** -- **T5. Store method signatures.** Who triggers eviction (at install time or - periodically), and whether `RawDataStore::read` takes predicates. (What - `SummaryStore` holds is decided: I6.) +- **T5. Store method signatures.** Whether `RawDataStore::read` takes + predicates (the executor re-applies them, so a store may ignore them). What + `SummaryStore` holds and who evicts are decided: I6, I17. - **T6. Ingesting pre-built sketches.** OTLP can carry sketch payloads, which today are decoded and only logged. Should `RawDataBatch` accept pre-built summaries? Out of scope for the MVP; to be done later. From 32ec4d82629a0694e78bb7037f29fe1c67f50c82 Mon Sep 17 00:00:00 2001 From: Milind Srivastava Date: Thu, 19 Nov 2026 12:55:15 -0500 Subject: [PATCH 19/27] docs(query-engine): exact-text planned matching (I18); glossary terms Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_014qhwq4jq8TFcKGchhF7Hfb --- .design_docs/asapplanner-engine-boundaries.md | 6 ++++- CONTEXT.md | 25 +++++++++++++++++++ 2 files changed, 30 insertions(+), 1 deletion(-) diff --git a/.design_docs/asapplanner-engine-boundaries.md b/.design_docs/asapplanner-engine-boundaries.md index ab889f02..9e2f3959 100644 --- a/.design_docs/asapplanner-engine-boundaries.md +++ b/.design_docs/asapplanner-engine-boundaries.md @@ -190,7 +190,7 @@ impl QueryDispatcher { // Exact match against the plan's query texts. fn resolve_planned(plan: &InstalledPlan, req: &QueryRequest) -> Option { - let i = plan.query_texts().position(|q| q == req.query)?; + let i = plan.query_texts().position(|q| q.trim() == req.query.trim())?; // I18 Some(AnswerSource::Planned { plan: plan.id, root: plan.dag().roots[i] }) } @@ -480,6 +480,10 @@ Implementation decisions: retention. This uses the planner's retentions as given; today's read-count policy (`ReadBased`) would need a read count the plan doesn't have. With no queries nothing is evicted, as with `ReadBased` today. +- **I18. Planned queries match by exact text**, after trimming surrounding + whitespace. The tracker plans the texts it saw in requests, so repeated + queries match; cosmetic variants fall back. Parsing and comparing queries + would need a parser per language. Capability matching (T2) is the general fix. - **I2. Phase 1 before the new engine path**, so the dispatcher is built on `QueryRequest` from the start and Phase 1 PRs are useful on their own. - **I3. ASAPPlanner is a pinned git dependency.** diff --git a/CONTEXT.md b/CONTEXT.md index a83c52ec..af3097b8 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -22,3 +22,28 @@ atomic-cost table for a sketch family and configuration. **Planner context**: Query- and deployment-specific structural inputs, such as label-group count and retained-window count, that scale atomic costs into a plan cost. + +**Summary**: +A stored, materialized node of an installed ASAPPlanner plan (ASAPPlanner's +materialized view), built at ingest and read at query time. +_Avoid_: aggregation, view, precomputed output + +**Summary window**: +One stored state of a summary, covering one time window. + +**Raw data**: +Ingested samples or rows as they arrive, before any summary is built. + +**Planned query**: +A query whose text is one of the installed plan's query texts. + +**Capability-matched query**: +A query not in the plan that can still be answered from installed summaries. + +**Not ready**: +A planned or capability-matched query whose summary windows don't yet cover +its whole evaluation range; it is answered by the fallback backend. + +**Fallback**: +Forwarding a query the engines don't answer to the real backend (Prometheus, +ClickHouse, Elastic). From 2291f095bd7d969f1dcb38c3213e2f6914f10c31 Mon Sep 17 00:00:00 2001 From: Milind Srivastava Date: Thu, 19 Nov 2026 12:57:01 -0500 Subject: [PATCH 20/27] docs(query-engine): PR stack for the implementation plan Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_014qhwq4jq8TFcKGchhF7Hfb --- .design_docs/asapplanner-engine-boundaries.md | 49 ++++++++++++------- 1 file changed, 32 insertions(+), 17 deletions(-) diff --git a/.design_docs/asapplanner-engine-boundaries.md b/.design_docs/asapplanner-engine-boundaries.md index 9e2f3959..c6cf3eee 100644 --- a/.design_docs/asapplanner-engine-boundaries.md +++ b/.design_docs/asapplanner-engine-boundaries.md @@ -382,23 +382,38 @@ async fn handle_ingestion(protocol: IngestProtocol, body: Bytes) -> StatusCode { ## Implementation plan -Small single-purpose PRs; the repo stays runnable at every merge. - -- **Phase 0, dependency.** ASAPPlanner as a git dependency pinned to a commit - (`asap-types`, renamed to avoid clashing with ASAPQuery's `asap_types`, and - `asap-planner`). -- **Phase 1, boundary types with the old engines behind them** (no behavior - change): `QueryRequest`; `QueryResult` `Scalar`/`Table`; - `RuntimeInfoSource`; `OtlpReceiver` behind `IngestSource`, `handle_ingestion`. -- **Phase 2, new traits and plumbing, tested with fake engines:** the traits, - in-memory stores, `QueryDispatcher`, `PlanInstaller`. Split - `PrecomputeEngine` into pipeline + build specification (I9). -- **Phase 3, new engine path:** `--engine` flag, first engines, `--plan-file`, - one PromQL instant query end to end; then ingest via `RawDataBatch`, range - queries, the remaining query types; then `QueryWorkloadTracker`. -- **Phase 4, retire:** pass the gate (I4), then delete `SimpleEngine`, - `PrecomputeEngine`, asap-planner-rs, `PlannerClient`, - `StreamingConfig`/`InferenceConfig` and the RQE endpoint, one PR each. +A stack of PRs, each on the previous one and each one logical step, so a +human can review them one at a time. The repo may be broken between PRs. + +1. **Dependency and interfaces only.** ASAPPlanner as a pinned git dependency + (`asap-types`, renamed to avoid clashing with ASAPQuery's `asap_types`, and + `asap-planner`). A new module with only the traits, structs and enums of + this doc, no implementations and no call-site changes. +2. **`QueryRequest` replaces `ParsedQueryRequest`/`ParsedRangeQueryRequest`** + in adapters, `HttpServer`, `FallbackClient` and `SimpleEngine`. Mechanical. +3. **`QueryResult` gains `Scalar` and `Table`**; adapters error on variants + they don't support. +4. **In-memory `SummaryStore` and `RawDataStore`**, with unit tests. +5. **`QueryDispatcher` and `PlanInstaller`**, tested with fake engines + (fallback rules, `NotReady`, no plan yet, install-once, error policy). +6. **Split `PrecomputeEngine` into pipeline + build specification (I9).** No + behavior change; old tests pass unchanged. +7. **Push `IngestEngine`**: plan → build specification (I8), executor kernels, + installer validation of supported operators. +8. **Executor-backed `QueryEngine`**: `DataStore` adapter, thread pool (I15), + missing window → `NotReady` (I10), eviction (I17). +9. **Wiring**: `--engine`, `--plan-file`, `IngestSource` → `IngestEngine`, + `OtlpReceiver` behind `IngestSource`, `handle_ingestion`; first end-to-end + test (one PromQL instant query). +10. **Range queries and the remaining query types.** +11. **`QueryWorkloadTracker`** emits `PlanningWorkload` with the default + `AccuracyTarget` (I5). +12. **I4 gate harness.** +13. **Deletions, one PR each:** `SimpleEngine`, `PrecomputeEngine`, + asap-planner-rs, `PlannerClient`, `StreamingConfig`/`InferenceConfig`, the + RQE endpoint. + +`RuntimeInfoSource` joins the stack once its contents are decided (T4). Implementation decisions: From f1ec819dc4688d3f078a8691293c7c5bb8de844d Mon Sep 17 00:00:00 2001 From: Milind Srivastava Date: Thu, 19 Nov 2026 12:58:20 -0500 Subject: [PATCH 21/27] docs(query-engine): stack base and interface module location Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_014qhwq4jq8TFcKGchhF7Hfb --- .design_docs/asapplanner-engine-boundaries.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/.design_docs/asapplanner-engine-boundaries.md b/.design_docs/asapplanner-engine-boundaries.md index c6cf3eee..cd0c532d 100644 --- a/.design_docs/asapplanner-engine-boundaries.md +++ b/.design_docs/asapplanner-engine-boundaries.md @@ -382,8 +382,11 @@ async fn handle_ingestion(protocol: IngestProtocol, body: Bytes) -> StatusCode { ## Implementation plan -A stack of PRs, each on the previous one and each one logical step, so a -human can review them one at a time. The repo may be broken between PRs. +A stack of PRs on top of the design-doc PR (#935), each on the previous one +and each one logical step, so a human can review them one at a time. The repo +may be broken between PRs. The interfaces live in a module of +`asap-query-engine` (`src/engine_api/`), not a separate crate: nothing outside +`asap-query-engine` uses them yet. 1. **Dependency and interfaces only.** ASAPPlanner as a pinned git dependency (`asap-types`, renamed to avoid clashing with ASAPQuery's `asap_types`, and From 286ea910378862a822058cecd0c757c3488db35a Mon Sep 17 00:00:00 2001 From: Milind Srivastava Date: Thu, 19 Nov 2026 13:09:36 -0500 Subject: [PATCH 22/27] docs(query-engine): drop glossary additions from this PR Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_014qhwq4jq8TFcKGchhF7Hfb --- CONTEXT.md | 25 ------------------------- 1 file changed, 25 deletions(-) diff --git a/CONTEXT.md b/CONTEXT.md index af3097b8..a83c52ec 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -22,28 +22,3 @@ atomic-cost table for a sketch family and configuration. **Planner context**: Query- and deployment-specific structural inputs, such as label-group count and retained-window count, that scale atomic costs into a plan cost. - -**Summary**: -A stored, materialized node of an installed ASAPPlanner plan (ASAPPlanner's -materialized view), built at ingest and read at query time. -_Avoid_: aggregation, view, precomputed output - -**Summary window**: -One stored state of a summary, covering one time window. - -**Raw data**: -Ingested samples or rows as they arrive, before any summary is built. - -**Planned query**: -A query whose text is one of the installed plan's query texts. - -**Capability-matched query**: -A query not in the plan that can still be answered from installed summaries. - -**Not ready**: -A planned or capability-matched query whose summary windows don't yet cover -its whole evaluation range; it is answered by the fallback backend. - -**Fallback**: -Forwarding a query the engines don't answer to the real backend (Prometheus, -ClickHouse, Elastic). From fc8b7487c6c7c829a59d9a4a1e8c0b0bdc215b78 Mon Sep 17 00:00:00 2001 From: Milind Srivastava Date: Thu, 19 Nov 2026 13:56:35 -0500 Subject: [PATCH 23/27] docs(query-engine): ViewStore model (definition, input data scope, instance); wait for ASAPPlanner physical view id Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_014qhwq4jq8TFcKGchhF7Hfb --- .design_docs/asapplanner-engine-boundaries.md | 148 ++++++++++++------ 1 file changed, 96 insertions(+), 52 deletions(-) diff --git a/.design_docs/asapplanner-engine-boundaries.md b/.design_docs/asapplanner-engine-boundaries.md index cd0c532d..2d7da871 100644 --- a/.design_docs/asapplanner-engine-boundaries.md +++ b/.design_docs/asapplanner-engine-boundaries.md @@ -15,11 +15,18 @@ stay. This doc defines the traits and boundaries around the new engines. It does not cover how the engines are implemented. Terms: -- **Summary**: a stored, materialized node of the plan (ASAPPlanner calls it a - `MaterializedView`), identified by its `PhysicalASAPNodeId`. +- **View**: a stored, materialized node of the plan (ASAPPlanner's + `MaterializedView`). Three concepts describe what is stored: + - **`ViewDefinitionId`**: the computation, physically: what the view computes, + its summary type, sketch parameters θ and pane width. Provided by + ASAPPlanner (decision 44). + - **`ViewInputDataScope`**: the concrete data that went in: the selection's + constraints (e.g. label matchers) and the exact pane start and end. + - **`ViewInstance`**: the stored state for one definition over one input data + scope, plus metadata. - **Planned query**: a query whose text is in `InstallablePlan.query_texts`. - **Capability-matched query**: a query that is not in the plan but can be - answered from the installed summaries. + answered from the stored views. ## Interfaces: before → after @@ -58,7 +65,7 @@ Replaced: `PlanInstaller`. - `StreamingConfig` / `InferenceConfig` → `InstalledPlan`. - `Store`, keyed by `(metric, aggregation_id, window)` with `AggregateCore` - values → `SummaryStore` + `RawDataStore`. + values → `ViewStore` + `RawDataStore`. - `SimpleEngine` (a concrete struct) → `QueryEngine` trait. - `PrecomputeEngine` (a concrete struct) → `IngestEngine` trait. @@ -72,7 +79,7 @@ Signatures are indicative. Method-level details are still open. ```rust struct InstalledPlan { // ASAPQuery's validated view of an InstallablePlan - id: PlanId, // counter, incremented per install + id: PlanId, // the plan's version for the workload: a counter, incremented per install plan: InstallablePlan, // nothing else; derived data is computed from it } @@ -105,7 +112,7 @@ enum AnswerSource { enum EngineQueryResult { Ready { result: QueryResult }, // label/column names live inside QueryResult - NotReady, // summaries don't cover the whole query → fallback + NotReady, // stored views don't cover the whole query → fallback } enum QueryOutcome { @@ -114,19 +121,27 @@ enum QueryOutcome { } enum NotAnswerableReason { Unmatched, NotReady, EngineError(QueryEngineError) } -trait SummaryStore { - put(SummaryWindowKey, SummaryState); get(SummaryId, range); evict_before(SummaryId, ts); - timestamp_range_per_summary() -> Map; // was get_earliest_timestamp_per_aggregation_id +struct ViewDefinitionId(..); // ASAPPlanner's physical view id (decision 44) +struct ViewInputDataScope { // the concrete data that went in + constraints: SelectionConstraints, // from the plan's selection, e.g. label matchers + interval: (i64, i64), // the exact pane (start, end] +} +struct ViewInstanceKey { definition: ViewDefinitionId, scope: ViewInputDataScope } +struct ViewInstance { state: ViewState, metadata: ViewInstanceMetadata } // metadata: open, e.g. size +struct ViewState(Arc); // the engine's native state, opaque to the store (I6) + +trait ViewStore { // in-memory or on disk; indexing is the implementation's (decision 8) + put(ViewInstanceKey, ViewInstance); // once; never rewritten (I16) + get(&ViewInstanceKey) -> Option; + instances(&ViewDefinitionId, &SelectionConstraints, interval) -> Vec<(ViewInputDataScope, ViewInstance)>; + evict_before(&ViewDefinitionId, ts); + timestamp_range_per_view() -> Map; // runtime info; was get_earliest_timestamp_per_aggregation_id } -struct SummaryId { plan: PlanId, node: PhysicalASAPNodeId } // one summary -struct SummaryWindowKey { summary: SummaryId, window: (i64, i64) } // one stored window of it -struct SummaryState(Arc); // the engine's native state, opaque to the store (I6) trait RawDataStore { append(Source, RawDataBatch); read(Source, range); evict(retention, now); } enum RawDataBatch { // raw input only; never data between operators - TimeSeries { series: Vec<(LabelSet, Vec<(i64, f64)>)> }, // Source::TimeSeries - Table(arrow::RecordBatch), // Source::Table + TimeSeries { series: Vec<(LabelSet, Vec<(i64, f64)>)> }, // Source::TimeSeries; Table later } ``` @@ -205,9 +220,9 @@ New engines only. With the old engines (decision 34), wiring is as today. ```rust // main: the deployment owns the stores and injects them (decision 8). -let summaries = Arc::new(InMemorySummaryStore::new()); +let views = Arc::new(InMemoryViewStore::new()); let raw = Arc::new(InMemoryRawDataStore::new()); -let (ingest_engine, query_engine) = engines_for(cli.engine, summaries.clone(), raw.clone()); // decision 30 +let (ingest_engine, query_engine) = engines_for(cli.engine, views.clone(), raw.clone()); // decision 30 let dispatcher = Arc::new(QueryDispatcher::new(query_engine.clone())); let installer = Arc::new(PlanInstaller::new(ingest_engine.clone(), query_engine.clone(), dispatcher.clone())); if let Some(path) = cli.plan_file { @@ -247,7 +262,7 @@ async fn handle_ingestion(protocol: IngestProtocol, body: Bytes) -> StatusCode { } // IngestEngine::ingest, at the boundary: uses its installed plan to decide what -// to keep; writes RawDataStore and SummaryStore, keying summaries by its PlanId. +// to keep; writes RawDataStore, and ViewStore keyed by (ViewDefinitionId, ViewInputDataScope). ``` ## Decisions @@ -272,13 +287,13 @@ async fn handle_ingestion(protocol: IngestProtocol, body: Bytes) -> StatusCode { 7. **Times.** Engines and stores see `i64` ms only. The adapters convert from protocol times. 8. **Stores.** The deployment owns the stores and injects them into both - engines. `SummaryStore` and `RawDataStore` are the boundary; whether an - implementation keeps data in memory, on disk or both is internal to it. The - first implementations are in-memory with no durability: after a restart they - are empty and queries return `NotReady` (→ fallback). Summaries are - identified by `SummaryId {PlanId, PhysicalASAPNodeId}`. A durable - implementation would need summary ids that survive a restart, which a - `PlanId` counter (decision 38) does not. + engines. `ViewStore` and `RawDataStore` are the boundary; an implementation + may keep data in memory, on disk or both, and chooses its own indexing. The + store never looks inside a view's state, so the state's structure can change + without changing the store. The first implementations are in-memory; after a + restart they are empty and queries return `NotReady` (→ fallback). Recovery + from a durable store is deferred; `ViewDefinitionId` is the same across + restarts, so it can key recovered instances. 9. **Capabilities.** The deployment declares one `DeploymentCapabilities`, which `QueryWorkloadTracker` passes to ASAPPlanner when it replans. 10. **Workload.** `QueryWorkloadTracker` emits ASAPPlanner's `PlanningWorkload`. @@ -288,11 +303,13 @@ async fn handle_ingestion(protocol: IngestProtocol, body: Bytes) -> StatusCode { 13. **Raw data batches.** `RawDataBatch` (named after ASAPPlanner's `read_raw_data`) is raw input only: what `IngestSource` passes to `IngestEngine::ingest` and what `RawDataStore` appends and returns. Data - between operators is internal to the engine. It is one enum matching the - plan's two `Source` kinds. `TimeSeries` holds per-series structured label - sets (instead of today's `labels: String`), since series in one batch have - different labels. `Table` is a plain Arrow `RecordBatch`, not the executor's - `Batch`, which needs one schema per batch and carries sketch-state columns. + between operators is internal to the engine. `TimeSeries` holds per-series + structured label sets (instead of today's `labels: String`), since series in + one batch have different labels. v1 has only `TimeSeries` (I8); a `Table` + variant comes with table sources. ASAPPlanner has no such type: the planner + handles no data, and the executor's `Batch` has one fixed schema per batch + (a time-series `Scan` gives one column per label), so the ingest engine + converts into it using the plan's `Scan` schema. 14. **`QueryResult` gains `Scalar` and `Table`.** 15. **RQE endpoint.** It is kept for testing only and removed at the end of the migration. @@ -365,12 +382,13 @@ async fn handle_ingestion(protocol: IngestProtocol, body: Bytes) -> StatusCode { `PlanId` it was resolved against. If the engine's installed plan differs (a plan swap between resolve and execute), the engine returns `NotReady`, so the query falls back. -36. **`NotReady` covers the whole query.** If the summaries don't cover the whole - query, the result is `NotReady`: for a range query, if any step isn't - covered; for an instant query, if its time is past what the summaries cover. +36. **`NotReady` covers the whole query.** If the stored views don't cover the + whole query, the result is `NotReady`: for a range query, if any step isn't + covered; for an instant query, if its time is past what the views cover. There are no partial answers. 37. **`AnswerSource` in `QueryOutcome::Ready` is for logging only.** -38. **`PlanId` is a counter**, incremented per install. +38. **`PlanId` is the plan's version for the workload**: a counter, + incremented per install. It is not part of view store keys. 39. **Before the first plan is installed, queries fall back.** The dispatcher has no plan, so every query is `Unmatched`. 40. **One capabilities constant.** There is one old engine and one new engine, @@ -379,6 +397,29 @@ async fn handle_ingestion(protocol: IngestProtocol, body: Bytes) -> StatusCode { 41. **Ingest before the first plan is dropped.** `IngestEngine::ingest` discards batches until a plan is installed. 42. **`InstalledPlan` is just `InstallablePlan` + `PlanId`.** +43. **View store model: definition, input data scope, instance.** A + `ViewInstance` (state + metadata) is keyed by + `(ViewDefinitionId, ViewInputDataScope)`: what was computed, and over which + data. The store is opaque to the state's structure (decision 8). This + matches the ASAPQuery-backend's store (`SummaryInstanceKey {definition, + selection}` over opaque states). +44. **`ViewDefinitionId` is a physical view id from ASAPPlanner; we wait for + it.** ASAPPlanner today has only a logical id + (`ViewCoverage::definition_id`: a hash of the view's sub-DAG down to its + `Scan`s, including the summary type), which omits θ (`node.parameters`) and + window geometry, so two plans can share it while storing states that are + not interchangeable. We ask ASAPPlanner for a physical view id that changes + exactly when stored states are not interchangeable: + - in: the logical definition (incl. summary type), θ, pane width; + - out: refresh mode (ingestion or first read) and retention, which change + how a state is built or kept, not what it is; the pane's exact start and + end, which are in `ViewInputDataScope`. + + We don't compose one ourselves, and our interfaces carry no logical id: + reuse across different θ is capability matching (T2), the planner's job. +45. **`timestamp_range_per_view` stays.** It feeds runtime info (today's + `earliest_timestamp_per_aggregation_id`), used to send queries aligned with + when views are computed. ## Implementation plan @@ -388,6 +429,8 @@ may be broken between PRs. The interfaces live in a module of `asap-query-engine` (`src/engine_api/`), not a separate crate: nothing outside `asap-query-engine` uses them yet. +0. **Blocked on ASAPPlanner adding a physical view id** (decision 44). The + stack starts after that lands upstream. 1. **Dependency and interfaces only.** ASAPPlanner as a pinned git dependency (`asap-types`, renamed to avoid clashing with ASAPQuery's `asap_types`, and `asap-planner`). A new module with only the traits, structs and enums of @@ -396,7 +439,7 @@ may be broken between PRs. The interfaces live in a module of in adapters, `HttpServer`, `FallbackClient` and `SimpleEngine`. Mechanical. 3. **`QueryResult` gains `Scalar` and `Table`**; adapters error on variants they don't support. -4. **In-memory `SummaryStore` and `RawDataStore`**, with unit tests. +4. **In-memory `ViewStore` and `RawDataStore`**, with unit tests. 5. **`QueryDispatcher` and `PlanInstaller`**, tested with fake engines (fallback rules, `NotReady`, no plan yet, install-once, error policy). 6. **Split `PrecomputeEngine` into pipeline + build specification (I9).** No @@ -404,7 +447,7 @@ may be broken between PRs. The interfaces live in a module of 7. **Push `IngestEngine`**: plan → build specification (I8), executor kernels, installer validation of supported operators. 8. **Executor-backed `QueryEngine`**: `DataStore` adapter, thread pool (I15), - missing window → `NotReady` (I10), eviction (I17). + missing view instance → `NotReady` (I10), eviction (I17). 9. **Wiring**: `--engine`, `--plan-file`, `IngestSource` → `IngestEngine`, `OtlpReceiver` behind `IngestSource`, `handle_ingestion`; first end-to-end test (one PromQL instant query). @@ -422,11 +465,11 @@ Implementation decisions: - **I1. The first `QueryEngine` wraps `asap-executor`'s query path.** Its `RunContext` is `!Send`, so it runs on a dedicated engine thread. Its - `read_materialized_view` serves states from `SummaryStore` by downcast (I6). + `read_materialized_view` serves states from `ViewStore` by downcast (I6). The traits let us replace it later (decision 1). - **I7. The first `IngestEngine` is our own push-based streaming engine,** modeled on today's precompute engine (route series, per-window updaters in - workers, seal into `SummaryStore` when the watermark passes a window's end + workers, seal into `ViewStore` when the watermark passes a window's end plus lateness). The executor's ingestion is pull-based: it refreshes each tumbling window once, after it closes, by reading the window's raw rows, so every sample would be buffered for a window even when the plan keeps no @@ -454,7 +497,7 @@ Implementation decisions: - **I10. `NotReady` is detected by running, not by a pre-check.** The executor reads only stored windows that exactly cover the requested range, and requires an error for a missing one. Our `DataStore` adapter returns a - distinct missing-window error, which the engine maps to `NotReady`; other + distinct missing-instance error, which the engine maps to `NotReady`; other executor errors are `Err` (I12). A pre-check would duplicate the executor's window arithmetic. In a range query, the first missing step makes the whole query `NotReady` (decision 36). @@ -478,8 +521,7 @@ Implementation decisions: - **I14. v1 installs once.** `PlanInstaller` accepts only the first plan; `QueryWorkloadTracker` keeps replanning and logs later plans without installing them, as today's `QueryTracker` does. Plan swap (T1) stays tabled; - `install`, `PlanId` in summary keys and `NotReady` on a `PlanId` mismatch - already leave room for it. + `install` and `NotReady` on a `PlanId` mismatch already leave room for it. - **I15. The executor-backed `QueryEngine` runs a pool of N engine threads** (deployment config, default the CPU count). Each compiles the installed plan itself and instantiates it against one shared `DataStore` adapter; queries are @@ -493,8 +535,9 @@ Implementation decisions: `ForwardToStore` is tabled (T8). - **I17. Only the query engine evicts, by time.** The ingest engine never evicts. The query engine tracks the latest evaluation time it has served - (a range query's end) and, after each query, evicts each summary's windows - before `latest_T − retention_ms` and raw data past the plan's raw-data + (a range query's end) and, after each query, calls + `evict_before(ViewDefinitionId, latest_T − retention_ms)` per view and + evicts raw data past the plan's raw-data retention. This uses the planner's retentions as given; today's read-count policy (`ReadBased`) would need a read count the plan doesn't have. With no queries nothing is evicted, as with `ReadBased` today. @@ -508,7 +551,7 @@ Implementation decisions: - **I4. Gate for deleting the old engines.** Old and new run different plans, so their answers are not compared with each other. On a fixed set of benchmark workloads: (1) coverage: every query the old engine answers without - fallback, the new engine answers too once its summaries cover it; (2) + fallback, the new engine answers too once its views cover it; (2) accuracy: every new answer meets the `AccuracyTarget` its query was planned with (ε, allowing δ failures), against the exact answer from the backend (Prometheus or ClickHouse via the fallback client), @@ -519,9 +562,9 @@ Implementation decisions: query without one as exact, so the planner would never choose sketches. A plan file is planned with its own workload's targets; keep that workload with it so I4 can check against them. -- **I6. `SummaryStore` holds the engine's native state**, as an opaque - `SummaryState(Arc)` the engine downcasts. Bytes would - cost a decode on every query read (the executor reads summaries as live +- **I6. A `ViewInstance` holds the engine's native state**, as an opaque + `ViewState(Arc)` the engine downcasts. Bytes would + cost a decode on every query read (the executor reads views as live `AggregateCore` objects; today's `Store` holds them too). Executor types in the trait would tie the store to the executor. A durable store would need an engine encode method, added when durability is. @@ -529,19 +572,20 @@ Implementation decisions: ## Tabled - **T1. Plan swap semantics.** When a new plan is installed, do we drain and - rebuild, or run the old and new plans side by side until the new summaries + rebuild, or run the old and new plans side by side until the new views cover the needed lookback? This affects `install` versus building engines per - plan. v1 sidesteps this (I14). + plan. v1 sidesteps this (I14). A physical `ViewDefinitionId` (decision 44) + lets a new plan reuse instances an old plan stored. - **T2. How a capability match is computed.** Ideally this is an ASAPPlanner API - (plan a query against the installed summaries, with no new materialization). + (plan a query against the stored views and raw data, with no new + materialization). Not in v1. It is not designed yet, so `CapabilityMatch` is a placeholder. - **T3. Per-request query requirements.** The same query text with different accuracy requirements collides today (issue #778). Should `QueryRequest` carry requirements? - **T4. `RuntimeInfoSource` contents.** -- **T5. Store method signatures.** Whether `RawDataStore::read` takes - predicates (the executor re-applies them, so a store may ignore them). What - `SummaryStore` holds and who evicts are decided: I6, I17. +- **T5. `RawDataStore::read` predicates.** Whether it takes predicates (the + executor re-applies them, so a store may ignore them). - **T6. Ingesting pre-built sketches.** OTLP can carry sketch payloads, which today are decoded and only logged. Should `RawDataBatch` accept pre-built summaries? Out of scope for the MVP; to be done later. From 438aefe4e28543861112bb63708bfe172ed8d6a6 Mon Sep 17 00:00:00 2001 From: Milind Srivastava Date: Thu, 19 Nov 2026 14:47:07 -0500 Subject: [PATCH 24/27] docs(query-engine): link ASAPPlanner issues for physical view id and capability matching Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_014qhwq4jq8TFcKGchhF7Hfb --- .design_docs/asapplanner-engine-boundaries.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.design_docs/asapplanner-engine-boundaries.md b/.design_docs/asapplanner-engine-boundaries.md index 2d7da871..c120a7b8 100644 --- a/.design_docs/asapplanner-engine-boundaries.md +++ b/.design_docs/asapplanner-engine-boundaries.md @@ -408,7 +408,7 @@ async fn handle_ingestion(protocol: IngestProtocol, body: Bytes) -> StatusCode { (`ViewCoverage::definition_id`: a hash of the view's sub-DAG down to its `Scan`s, including the summary type), which omits θ (`node.parameters`) and window geometry, so two plans can share it while storing states that are - not interchangeable. We ask ASAPPlanner for a physical view id that changes + not interchangeable. We ask ASAPPlanner (ProjectASAP/ASAPPlanner#1429) for a physical view id that changes exactly when stored states are not interchangeable: - in: the logical definition (incl. summary type), θ, pane width; - out: refresh mode (ingestion or first read) and retention, which change @@ -429,7 +429,7 @@ may be broken between PRs. The interfaces live in a module of `asap-query-engine` (`src/engine_api/`), not a separate crate: nothing outside `asap-query-engine` uses them yet. -0. **Blocked on ASAPPlanner adding a physical view id** (decision 44). The +0. **Blocked on ASAPPlanner adding a physical view id** (decision 44; ProjectASAP/ASAPPlanner#1429). The stack starts after that lands upstream. 1. **Dependency and interfaces only.** ASAPPlanner as a pinned git dependency (`asap-types`, renamed to avoid clashing with ASAPQuery's `asap_types`, and @@ -576,7 +576,7 @@ Implementation decisions: cover the needed lookback? This affects `install` versus building engines per plan. v1 sidesteps this (I14). A physical `ViewDefinitionId` (decision 44) lets a new plan reuse instances an old plan stored. -- **T2. How a capability match is computed.** Ideally this is an ASAPPlanner API +- **T2. How a capability match is computed.** Ideally this is an ASAPPlanner API (ProjectASAP/ASAPPlanner#1430) (plan a query against the stored views and raw data, with no new materialization). Not in v1. It is not designed yet, so `CapabilityMatch` is a placeholder. From 5b1c2fa299541052822a712373204fba36b05267 Mon Sep 17 00:00:00 2001 From: Milind Srivastava Date: Thu, 19 Nov 2026 20:16:59 -0500 Subject: [PATCH 25/27] docs(design): view definition id is logical id plus physical properties Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_014qhwq4jq8TFcKGchhF7Hfb --- .design_docs/asapplanner-engine-boundaries.md | 30 +++++++++++-------- 1 file changed, 18 insertions(+), 12 deletions(-) diff --git a/.design_docs/asapplanner-engine-boundaries.md b/.design_docs/asapplanner-engine-boundaries.md index c120a7b8..278dd7eb 100644 --- a/.design_docs/asapplanner-engine-boundaries.md +++ b/.design_docs/asapplanner-engine-boundaries.md @@ -17,9 +17,9 @@ does not cover how the engines are implemented. Terms: - **View**: a stored, materialized node of the plan (ASAPPlanner's `MaterializedView`). Three concepts describe what is stored: - - **`ViewDefinitionId`**: the computation, physically: what the view computes, - its summary type, sketch parameters θ and pane width. Provided by - ASAPPlanner (decision 44). + - **`ViewDefinitionId`**: the computation, physically: ASAPPlanner's logical + `definition_id` (what the view computes, incl. summary type) plus its + physical properties, sketch parameters θ and pane width (decision 44). - **`ViewInputDataScope`**: the concrete data that went in: the selection's constraints (e.g. label matchers) and the exact pane start and end. - **`ViewInstance`**: the stored state for one definition over one input data @@ -121,7 +121,10 @@ enum QueryOutcome { } enum NotAnswerableReason { Unmatched, NotReady, EngineError(QueryEngineError) } -struct ViewDefinitionId(..); // ASAPPlanner's physical view id (decision 44) +struct ViewDefinitionId { // decision 44 + definition_id: DefinitionId, // ASAPPlanner's logical id + physical: PhysicalProperties, // from ASAPPlanner: θ, pane width +} struct ViewInputDataScope { // the concrete data that went in constraints: SelectionConstraints, // from the plan's selection, e.g. label matchers interval: (i64, i64), // the exact pane (start, end] @@ -403,20 +406,23 @@ async fn handle_ingestion(protocol: IngestProtocol, body: Bytes) -> StatusCode { data. The store is opaque to the state's structure (decision 8). This matches the ASAPQuery-backend's store (`SummaryInstanceKey {definition, selection}` over opaque states). -44. **`ViewDefinitionId` is a physical view id from ASAPPlanner; we wait for - it.** ASAPPlanner today has only a logical id +44. **`ViewDefinitionId` is ASAPPlanner's logical id plus its physical + properties; we wait for them.** ASAPPlanner today has only a logical id (`ViewCoverage::definition_id`: a hash of the view's sub-DAG down to its `Scan`s, including the summary type), which omits θ (`node.parameters`) and window geometry, so two plans can share it while storing states that are - not interchangeable. We ask ASAPPlanner (ProjectASAP/ASAPPlanner#1429) for a physical view id that changes - exactly when stored states are not interchangeable: + not interchangeable. ASAPPlanner (ProjectASAP/ASAPPlanner#1429) keeps the + logical id and exposes the physical properties as separate fields on each + materialized view; together they change exactly when stored states are not + interchangeable: - in: the logical definition (incl. summary type), θ, pane width; - out: refresh mode (ingestion or first read) and retention, which change how a state is built or kept, not what it is; the pane's exact start and end, which are in `ViewInputDataScope`. - We don't compose one ourselves, and our interfaces carry no logical id: - reuse across different θ is capability matching (T2), the planner's job. + We take both from the plan and don't derive either ourselves. The logical + id alone is not a store key; it lets capability matching (T2) find a view + that answers a query at a different θ. 45. **`timestamp_range_per_view` stays.** It feeds runtime info (today's `earliest_timestamp_per_aggregation_id`), used to send queries aligned with when views are computed. @@ -429,7 +435,7 @@ may be broken between PRs. The interfaces live in a module of `asap-query-engine` (`src/engine_api/`), not a separate crate: nothing outside `asap-query-engine` uses them yet. -0. **Blocked on ASAPPlanner adding a physical view id** (decision 44; ProjectASAP/ASAPPlanner#1429). The +0. **Blocked on ASAPPlanner exposing physical view properties** (decision 44; ProjectASAP/ASAPPlanner#1429). The stack starts after that lands upstream. 1. **Dependency and interfaces only.** ASAPPlanner as a pinned git dependency (`asap-types`, renamed to avoid clashing with ASAPQuery's `asap_types`, and @@ -574,7 +580,7 @@ Implementation decisions: - **T1. Plan swap semantics.** When a new plan is installed, do we drain and rebuild, or run the old and new plans side by side until the new views cover the needed lookback? This affects `install` versus building engines per - plan. v1 sidesteps this (I14). A physical `ViewDefinitionId` (decision 44) + plan. v1 sidesteps this (I14). A `ViewDefinitionId` that includes physical properties (decision 44) lets a new plan reuse instances an old plan stored. - **T2. How a capability match is computed.** Ideally this is an ASAPPlanner API (ProjectASAP/ASAPPlanner#1430) (plan a query against the stored views and raw data, with no new From 521b9e0514850dcaac22f5ec2217f3a913429202 Mon Sep 17 00:00:00 2001 From: Milind Srivastava Date: Thu, 19 Nov 2026 21:13:38 -0500 Subject: [PATCH 26/27] docs(design): start the stack with steps that don't need ASAPPlanner Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_014qhwq4jq8TFcKGchhF7Hfb --- .design_docs/asapplanner-engine-boundaries.md | 27 ++++++++++--------- 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/.design_docs/asapplanner-engine-boundaries.md b/.design_docs/asapplanner-engine-boundaries.md index 278dd7eb..739ae138 100644 --- a/.design_docs/asapplanner-engine-boundaries.md +++ b/.design_docs/asapplanner-engine-boundaries.md @@ -435,21 +435,24 @@ may be broken between PRs. The interfaces live in a module of `asap-query-engine` (`src/engine_api/`), not a separate crate: nothing outside `asap-query-engine` uses them yet. -0. **Blocked on ASAPPlanner exposing physical view properties** (decision 44; ProjectASAP/ASAPPlanner#1429). The - stack starts after that lands upstream. -1. **Dependency and interfaces only.** ASAPPlanner as a pinned git dependency - (`asap-types`, renamed to avoid clashing with ASAPQuery's `asap_types`, and - `asap-planner`). A new module with only the traits, structs and enums of - this doc, no implementations and no call-site changes. -2. **`QueryRequest` replaces `ParsedQueryRequest`/`ParsedRangeQueryRequest`** +1. **`QueryRequest` replaces `ParsedQueryRequest`/`ParsedRangeQueryRequest`** in adapters, `HttpServer`, `FallbackClient` and `SimpleEngine`. Mechanical. -3. **`QueryResult` gains `Scalar` and `Table`**; adapters error on variants +2. **`QueryResult` gains `Scalar` and `Table`**; adapters error on variants they don't support. -4. **In-memory `ViewStore` and `RawDataStore`**, with unit tests. -5. **`QueryDispatcher` and `PlanInstaller`**, tested with fake engines - (fallback rules, `NotReady`, no plan yet, install-once, error policy). -6. **Split `PrecomputeEngine` into pipeline + build specification (I9).** No +3. **Split `PrecomputeEngine` into pipeline + build specification (I9).** No behavior change; old tests pass unchanged. + +Steps 1–3 don't use ASAPPlanner. The rest wait for ASAPPlanner to expose +physical view properties (decision 44; ProjectASAP/ASAPPlanner#1429). + +4. **Dependency and interfaces only.** ASAPPlanner as a git dependency pinned + to a commit that includes #1429 (`asap-types`, renamed to avoid clashing + with ASAPQuery's `asap_types`, and `asap-planner`). A new module with only + the traits, structs and enums of this doc, no implementations and no + call-site changes. +5. **In-memory `ViewStore` and `RawDataStore`**, with unit tests. +6. **`QueryDispatcher` and `PlanInstaller`**, tested with fake engines + (fallback rules, `NotReady`, no plan yet, install-once, error policy). 7. **Push `IngestEngine`**: plan → build specification (I8), executor kernels, installer validation of supported operators. 8. **Executor-backed `QueryEngine`**: `DataStore` adapter, thread pool (I15), From 86732ff76abad338e8380618c8fe9d6dbc3668dd Mon Sep 17 00:00:00 2001 From: Milind Srivastava Date: Fri, 20 Nov 2026 23:18:45 -0500 Subject: [PATCH 27/27] docs(design): adapters move to their own crate (decision 46) Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_014qhwq4jq8TFcKGchhF7Hfb --- .design_docs/asapplanner-engine-boundaries.md | 83 +++++++++++++++---- 1 file changed, 65 insertions(+), 18 deletions(-) diff --git a/.design_docs/asapplanner-engine-boundaries.md b/.design_docs/asapplanner-engine-boundaries.md index 739ae138..b9b430d7 100644 --- a/.design_docs/asapplanner-engine-boundaries.md +++ b/.design_docs/asapplanner-engine-boundaries.md @@ -11,7 +11,7 @@ replacing both engines with ones that execute plans from ASAPPlanner (`../ASAPPlanner`). Those plans arrive as an `InstallablePlan`, which wraps a `PhysicalASAPDAG` plus the query texts, one per DAG root. This lets us retire asap-planner-rs. The protocol adapters, fallback clients and ingest decoders -stay. This doc defines the traits and boundaries around the new engines. It +stay, in their own crate, `asap-adapters` (decision 46). This doc defines the traits and boundaries around the new engines. It does not cover how the engines are implemented. Terms: @@ -426,45 +426,92 @@ async fn handle_ingestion(protocol: IngestProtocol, body: Bytes) -> StatusCode { 45. **`timestamp_range_per_view` stays.** It feeds runtime info (today's `earliest_timestamp_per_aggregation_id`), used to send queries aligned with when views are computed. +46. **Adapters are a separate crate, `asap-adapters`, that depends on the + engine crate.** + - `asap-adapters` holds everything that talks to an outside system: + protocol adapters, `HttpServer`, fallback clients, ingest decoders and + `IngestSource` implementations, `QueryWorkloadTracker`, and every + binary. + - `asap-query-engine` becomes a library: the engines, stores, + `QueryDispatcher`, `PlanInstaller` and `engine_api`. `QueryDispatcher` + and `PlanInstaller` use only the engine traits; fallback is called from + `HttpServer` (decision 5). + - Dependencies point one way, adapters → engine, so the engine can't reach + HTTP, protocol code or a planner. + - The engine crate never depends on a planning algorithm. Today's + asap-planner-rs (deleted in the last step) and ASAPPlanner's + `asap-planner` (added with `QueryWorkloadTracker`) are used only from + `asap-adapters`. The engine crate depends only on ASAPPlanner's + `asap-types` plan types (decision 1). A new or remote planner changes + only `asap-adapters`. + - ASAPPlanner stays a pinned git dependency (I3), not copied in: planning + is control-plane logic, not protocol translation. + + Not solved: the engine still depends on ASAPPlanner's plan types (decision + 1). `asap-adapters` can see everything public in the engine crate; + visibility narrows this, and it is fully closed once the old engines are + deleted. `handle_runtime_info` still takes the old engine's + `Arc` until T4. There is no separate `engine_api` crate: + `HttpServer` calls `SimpleEngine` directly while the old engines are + selectable (decision 34), so `asap-adapters` depends on the engine crate + anyway. ## Implementation plan A stack of PRs on top of the design-doc PR (#935), each on the previous one and each one logical step, so a human can review them one at a time. The repo may be broken between PRs. The interfaces live in a module of -`asap-query-engine` (`src/engine_api/`), not a separate crate: nothing outside -`asap-query-engine` uses them yet. - -1. **`QueryRequest` replaces `ParsedQueryRequest`/`ParsedRangeQueryRequest`** +`asap-query-engine` (`src/engine_api/`), not a separate crate: their only +outside user is `asap-adapters`, which depends on the engine crate anyway. +Split it out only if a second engine crate appears. + +1. **Extract `asap-adapters` (decision 46) as a pure move.** `drivers/` + (query adapters, fallback, ingest), `query_tracker/`, `planner_client.rs` + with its asap-planner-rs dependency, `main.rs` and every binary in + `src/bin/` move to the new crate; all of them use `drivers`. The engine + crate becomes a library. `tests/sql_query_support.rs` and + `tests/e2e_precompute_equivalence.rs` move too, or keep asap-planner-rs as a + dev-dependency. The Dockerfiles (`asap-query-engine/Dockerfile`, + `asap-quickstart/Dockerfile.queryengine-local`) point at the new crate. + `precompute_engine/{csv_ingest,json_ingest,ingest_source}.rs` move too, + unless they pull in precompute internals; then they move with the + `IngestSource` rewiring (wiring step). No ASAPPlanner dependency is added + and there is no behavior change; every test passes unchanged. Imports and + `Cargo.toml` are the only changes, so later diffs to adapter signatures, + wiring and the tracker each land in one crate. Optional follow-up: + `pub(crate)` on engine internals, re-exporting only `engine_api` plus the + old engines, stores and precompute types the adapters need until the + deletions. +2. **`QueryRequest` replaces `ParsedQueryRequest`/`ParsedRangeQueryRequest`** in adapters, `HttpServer`, `FallbackClient` and `SimpleEngine`. Mechanical. -2. **`QueryResult` gains `Scalar` and `Table`**; adapters error on variants +3. **`QueryResult` gains `Scalar` and `Table`**; adapters error on variants they don't support. -3. **Split `PrecomputeEngine` into pipeline + build specification (I9).** No +4. **Split `PrecomputeEngine` into pipeline + build specification (I9).** No behavior change; old tests pass unchanged. -Steps 1–3 don't use ASAPPlanner. The rest wait for ASAPPlanner to expose +Steps 1–4 don't use ASAPPlanner. The rest wait for ASAPPlanner to expose physical view properties (decision 44; ProjectASAP/ASAPPlanner#1429). -4. **Dependency and interfaces only.** ASAPPlanner as a git dependency pinned +5. **Dependency and interfaces only.** ASAPPlanner as a git dependency pinned to a commit that includes #1429 (`asap-types`, renamed to avoid clashing with ASAPQuery's `asap_types`, and `asap-planner`). A new module with only the traits, structs and enums of this doc, no implementations and no call-site changes. -5. **In-memory `ViewStore` and `RawDataStore`**, with unit tests. -6. **`QueryDispatcher` and `PlanInstaller`**, tested with fake engines +6. **In-memory `ViewStore` and `RawDataStore`**, with unit tests. +7. **`QueryDispatcher` and `PlanInstaller`**, tested with fake engines (fallback rules, `NotReady`, no plan yet, install-once, error policy). -7. **Push `IngestEngine`**: plan → build specification (I8), executor kernels, +8. **Push `IngestEngine`**: plan → build specification (I8), executor kernels, installer validation of supported operators. -8. **Executor-backed `QueryEngine`**: `DataStore` adapter, thread pool (I15), +9. **Executor-backed `QueryEngine`**: `DataStore` adapter, thread pool (I15), missing view instance → `NotReady` (I10), eviction (I17). -9. **Wiring**: `--engine`, `--plan-file`, `IngestSource` → `IngestEngine`, +10. **Wiring**: `--engine`, `--plan-file`, `IngestSource` → `IngestEngine`, `OtlpReceiver` behind `IngestSource`, `handle_ingestion`; first end-to-end test (one PromQL instant query). -10. **Range queries and the remaining query types.** -11. **`QueryWorkloadTracker`** emits `PlanningWorkload` with the default +11. **Range queries and the remaining query types.** +12. **`QueryWorkloadTracker`** emits `PlanningWorkload` with the default `AccuracyTarget` (I5). -12. **I4 gate harness.** -13. **Deletions, one PR each:** `SimpleEngine`, `PrecomputeEngine`, +13. **I4 gate harness.** +14. **Deletions, one PR each:** `SimpleEngine`, `PrecomputeEngine`, asap-planner-rs, `PlannerClient`, `StreamingConfig`/`InferenceConfig`, the RQE endpoint.