Skip to content

docs(planner): document lifecycle-aware planning and costs #320

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
zzylol wants to merge 1 commit into
base: test/workload-lifecycle-e2e
Choose a base branch
from
Open

docs(planner): document lifecycle-aware planning and costs #320

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
207 changes: 207 additions & 0 deletions docs/design_docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,207 @@
# ASAPPlanner Design Overview

ASAPPlanner converts queries in supported source languages into a compact
space of plans that use exact summaries, sketches, samples, wavelets,
statistical models, sharing, and other ASAP-aware alternatives. It removes
illegal alternatives, expands each remaining plan with legal summary
maintenance lifecycles, costs the resulting combinations, and only then
materializes a final plan.

## Planner component flow

```mermaid
flowchart LR
subgraph FRONTEND[Query frontend]
Q[Original query-language input]
PARSE[Parse and normalize]
PRE[Pre-ASAP DAG]
Q --> PARSE --> PRE
end

subgraph WORKLOAD[Workload inputs and model]
QW[Query workload]
DW[Data workload]
H[Explicit planning horizon H]
W[Normalize workload and derive demand,<br/>time scope, recurrence, and data evidence]
QW --> W
DW --> W
H --> W
end

subgraph MAPPING[Semantic mapping DAG]
MAP[Build a compact space representing all<br/>Post-ASAP DAG candidates]
end

subgraph ACCURACY[Correctness and accuracy models]
LEGAL[Check semantic, schema,<br/>capability, and phase legality]
PROP[Propagate guarantees through nested summaries]
ACHECK[Keep candidates that satisfy each query's<br/>accuracy requirement; reject unknown guarantees]
LEGAL --> PROP --> ACHECK
end

subgraph COST[Lifecycle expansion, cost model, and global selection]
LIFE[Expand every candidate with legal summary-maintenance lifecycles:<br/>build once / prepared / shared / incremental / existing state]
EST[Estimate lifecycle-aware candidate cost over H:<br/>build + maintenance + reads + retention + retirement]
RANK[Select the lowest-cost compatible<br/>whole-plan and lifecycle combination]
LIFE --> EST --> RANK
end

subgraph OUTPUT[Materialization and explanation]
MAT[Materialize the selected Post-ASAP DAG<br/>with its selected summary-maintenance lifecycle]
EMIT[Emit final plan, deployment actions,<br/>guarantees, assumptions, and rejections]
MAT --> EMIT
end

PRE --> MAP
W --> MAP
MAP --> LEGAL
W --> PROP
ACHECK --> LIFE
W --> LIFE
RANK --> MAT
```

The optimizer's decision unit is a compatible whole-plan combination:

```text
Post-ASAP candidate plan × summary-maintenance lifecycle assignment
```

It is not sound to select a summary implementation first and attach a
lifecycle afterward. Workload and lifecycle can reverse the ranking: a
summary that is cheapest to build once may be more expensive than another
summary when maintained for a high-frequency dashboard.

## Terminology: summary maintenance lifecycle

This design uses **summary maintenance lifecycle** for the lifetime of planner-
selected summary state: build, prepare, share, incrementally maintain, read,
and retire. A final plan's promises about those actions are its **summary
maintenance lifecycle guarantees**.

This is narrower than the end-to-end **data lifecycle**, which covers data
collection, transmission, storage, and analytics. Unqualified names such as
"lifecycle guarantee" are avoided because they do not say which lifecycle is
being guaranteed.

## Major components

### Query frontend

The frontend parses an original query-language input, such as PromQL or SQL,
and normalizes it into a Pre-ASAP DAG. The Pre-ASAP DAG represents the query's
semantics without committing to an ASAP summary implementation.

Detailed designs:

- [Parsing and canonicalization](parse_and_canonicalize.md)
- [Pre-ASAP IR](pre-asap-ir.md)

### Workload inputs and model

The workload model keeps three inputs explicit and separate:

- the query workload describes one-time and repeated queries, predictability,
accuracy and latency requirements, and concrete time selections;
- the data workload describes data arrival, ingestion volume and rate, input
cardinality, and distribution evidence;
- the planning horizon `H` is the interval over which one-time costs and cost
rates can be compared.

Normalization derives demand, recurrence, time scope, and freshness-checked
data evidence. Repeated query demand does not imply continuously arriving
data, and a numeric lookback does not by itself determine whether a query is
real-time or longitudinal.

Detailed design:

- [Query workloads, data workloads, and summary lifecycle maintenance](asap-aware-mapping/workload-demand-and-summary-lifecycle.md)

### Semantic mapping DAG

Semantic mapping takes the Pre-ASAP DAG and constructs a compact candidate
space. Candidates may use different summary families, summary parameters,
semantic rewrites, sharing arrangements, roll-ups, and generic update- or
readout-phase value operations. Shared structure and local alternative groups
represent possible complete Post-ASAP DAGs without eagerly copying every full
DAG.

Semantic mapping enumerates possibilities; it does not select or deploy one.
Semantic equivalence, schema compatibility, summary capabilities, and phase
contracts remove illegal combinations before costing.

Detailed designs:

- [Post-ASAP IR](post-asap-ir.md)
- [ASAP-aware mapping overview](asap-aware-mapping/README.md)
- [Mapping key concepts](asap-aware-mapping/key_concepts.md)
- [Searching over candidate plans](asap-aware-mapping/searching_over_plans.md)
- [Mapping optimizations](asap-aware-mapping/optimizations.md)
- [Summary properties](asap-aware-mapping/summary_properties.md)

### Accuracy model

The accuracy model derives a machine-readable guarantee for each complete
candidate plan. It propagates guarantees through nested summaries and post-
processing rather than checking each summary independently. A candidate
remains eligible only when its end-to-end guarantee satisfies the
corresponding query requirement; missing evidence or unsupported propagation
rules fail closed.

Detailed design:

- [End-to-end accuracy guarantees](asap-aware-mapping/end-to-end-accuracy-guarantees.md)

### Cost model

Every eligible semantic candidate is expanded with its legal summary-
maintenance lifecycle alternatives. A summary may be built once for an
ephemeral query, prepared for predictable demand, shared for a bounded period,
maintained incrementally as data arrives, or read from compatible existing
state. Runtime, summary, and existing-state capabilities determine which
alternatives are legal.

The cost model estimates; it does not decide legality or silently remove an
alternative. For each legal whole-plan and lifecycle assignment, it combines
build, maintenance, read, retention, and retirement costs over the same
explicit horizon `H`. Unknown costs remain unknown.

The global optimizer then selects the lowest-cost compatible combination. It
accounts for shared state once, validates lifecycle compatibility across
nested summaries and consumers, and retains raw recomputation as an explicit
fallback. Lifecycle is therefore part of candidate cost and global selection,
not a separate decision made after semantic ranking.

Detailed designs:

- [Cost model](cost-model.md)

### Materialization and explanation

The final output contains the selected Post-ASAP DAG, deployment actions,
accuracy guarantees, and summary maintenance lifecycle guarantees. It also
records cost evidence, assumptions, and rejected alternatives.

Conceptually:

```text
FinalPlan {
post_asap_dag,
deployments,
accuracy_guarantees,
summary_maintenance_lifecycle_guarantees,
cost_estimates,
assumptions,
rejected_alternatives,
}
```

Materialization commits the summary implementation and its maintenance
lifecycle. For example, after a KLL summary is deployed for incremental
maintenance, the runtime cannot silently maintain DDSketch instead. A later
replan may select DDSketch, but the resulting deployment must explicitly
build or migrate state, cut over readers, and retire the KLL state.

Detailed design:

- [Explainability](asap-aware-mapping/explainability.md)
93 changes: 69 additions & 24 deletions docs/design_docs/asap-aware-mapping/workload-demand-and-summary-lifecycle.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,9 @@
This document is for ASAPPlanner designers, architects, researchers, and
developers working on workload-aware plan selection. It defines how the
planner should describe query workload, data workload, and the lifecycle of
summary state. It is a design contract, not a description of the current
public Rust API.
summary state. It is the design contract for the public Rust model and the
workload-to-lifecycle planning API; deployments still supply their own cost
statistics and runtime capabilities.

The terminology follows the ProjectASAP
[glossary](https://github.com/ProjectASAP/internal-docs/blob/03e1c70f5af3ae9221471898541067eee7f86338/glossary.md).
Expand All @@ -22,6 +23,16 @@ decides whether a candidate is correct enough. Workload demand and state
lifecycle decide whether building, maintaining, sharing, or recomputing that
candidate is worthwhile. Neither decision may override the other.

### Lifecycle terminology

This document uses **summary maintenance lifecycle** for the lifetime of
planner-selected summary state: build, prepare, share, incrementally maintain,
read, and retire. The final plan's promises about those actions are its
**summary maintenance lifecycle guarantees**. This term is intentionally
distinct from the broader **data lifecycle**, which covers data collection,
transmission, storage, and analytics. Unqualified "lifecycle guarantees" are
avoided.

## Problem and why now

A summary operator does not imply one execution lifecycle. The same exact or
Expand All @@ -36,18 +47,49 @@ Likewise, an exact stateless operator may run once over a batch, once per
update in an incremental pipeline, or once per readout. Operator statefulness,
execution schedule, and output representation are separate properties.

The phase contract is also independent of accuracy semantics. A value
operation may be exact, summary-derived, or approximate. The post-ASAP IR
therefore uses the generic phase nodes `UpdateTransform` (`UpdateValue ->
UpdateValue`) and `ReadoutPostProcess` (`ReadoutValue -> ReadoutValue`). Their
`ValueOperator` payload identifies the computation; the enclosing node carries
its output schema and accuracy guarantee. The exact-composition strategy emits
`ValueOperator::Exact` today, but it is only the first producer of these phase
nodes, not their definition.

The query expression alone cannot determine those properties. The same query
may arrive unexpectedly during exploration, run once at a scheduled time, or
repeat every ten seconds on a dashboard. Planning summary state from syntax
alone either misses reuse or invents reuse that the workload does not justify.

The current normalized workload distinguishes a one-shot `query_batch` from
fixed-interval `repeating_queries`, and the recurrence cost model distinguishes
one-shot consumers from evaluation and update rates. This is a useful base, but
it does not represent predictability, uncertain demand, real-time versus
longitudinal scope, at-rest versus continuously ingesting data, or summary-state
lifecycle. It also risks treating "repeating query" and "streaming data" as the
same fact even though the glossary defines them on different axes.
The normalized workload preserves `query_batch` and `repeating_queries` as
compatibility-shaped inputs, then exposes both through `QueryWorkload::entries`
as recurrence, predictability, requirements, and time-selection axes. Data
arrival and fresh ingestion evidence remain a separate `DataWorkload`; a
repeating query therefore never implies streaming data.

### Implementation map

- `asap_types::workload` defines the normalized query/data workload and
evidence freshness contract.
- `PlanSpace::recurrence_profiles_from_workload` derives per-target read and
update recurrence from an explicit root-to-workload-entry binding, without
treating missing evidence as zero or relying on container order.
- `WorkloadAccuracyEvidence` supplies fresh cardinality and distribution to
accuracy models.
- `plan_summary_maintenance_lifecycles` enumerates legal ephemeral, prepared, shared, and
continuously maintained alternatives for the entries explicitly associated
with the target, and compares their costs over the caller's explicit horizon.
- `global_selection_with_summary_maintenance_lifecycles` prices each semantic
summary candidate using its cheapest legal summary maintenance lifecycle
before global selection. Its recurrence profile includes repeated DAG paths,
while the workload binding separately preserves time-selection and
predictability facts.
- `materialize_with_summary_maintenance_lifecycles` materializes that phase-valid selection and
attaches the selected state deployments. Each deployment retains assumptions
and rejected alternatives for explanation.
- `UpdateTransform` and `ReadoutPostProcess` express availability boundaries
for any value operator. Exact, summary-derived, and approximate producers use
the same phase validation rather than defining accuracy-specific phase nodes.

## Inputs, outputs, and end-to-end behavior

Expand Down Expand Up @@ -84,19 +126,20 @@ preparing state in advance with building or recomputing at execution time. For
repeated queries, it may amortize build and maintenance cost across reads over
an explicit horizon.

### End-to-end decision order
### Target end-to-end decision order

```text
normalize query and data workloads
-> derive recurrence, time-scope, and data evidence
-> enumerate semantic plan alternatives
-> enumerate legal execution contracts and state lifecycles
-> validate summary capabilities and phase constraints
-> build a compact space of semantic plan alternatives
-> validate semantic, schema, summary-capability, and phase constraints
-> derive and check accuracy guarantees
-> expand every legal candidate with summary-maintenance lifecycles
-> normalize one-time and rate costs over an explicit horizon
-> rank legal alternatives and compare the selected summary deployment
with raw recomputation
-> emit plan, deployments, assumptions, and rejected alternatives
-> globally rank compatible plan-and-lifecycle combinations
-> emit plan, deployments, accuracy guarantees,
summary maintenance lifecycle guarantees, assumptions,
and rejected alternatives
```

## Goals and non-goals
Expand Down Expand Up @@ -439,10 +482,10 @@ not imply long-lived incremental maintenance. A stateless transform can run
`PerUpdate` before a downstream maintained summary. These types describe an
execution contract; they do not replace semantic operators in the post-ASAP IR.

### State lifecycle is a plan alternative
### Summary maintenance lifecycle is a plan alternative

```rust
enum StateLifecycle {
enum SummaryMaintenanceLifecycle {
Ephemeral,
Prepared {
activate_at: Timestamp,
Expand All @@ -466,7 +509,7 @@ The summary family and its properties constrain which lifecycles are legal.
For example, an append-only sketch may support continuous inserts but not a
sliding-window lifecycle requiring deletion. Lifecycle legality is checked
before cost ranking, like accuracy legality. Deployments provide these
per-summary properties through `summary_lifecycle_capabilities`; moving
per-summary properties through `summary_maintenance_capabilities`; moving
real-time windows require deletion support as well as incremental updates.

### Existing summaries are planning input
Expand Down Expand Up @@ -515,11 +558,13 @@ For repeated raw recomputation:
total(H) = reads(H) * raw_recompute_cost
```

The current lifecycle-aware materialization sums the selected summary
deployments and can replace that plan with raw recomputation when the raw cost
is lower or the summary lifecycle is uncostable. Jointly reconsidering every
sibling semantic candidate under lifecycle costs remains a later optimizer
integration; this document does not claim that broader search is implemented.
Before materialization, lifecycle-aware global selection computes the cheapest
legal summary maintenance lifecycle total for every semantic summary sibling
whose cost evidence is complete. Those totals can reorder summary families;
unknown totals remain conservative and cannot win as invented zeroes. After
selection, materialization sums each unique selected summary deployment once
and can replace the selected summary plan with raw recomputation when the raw
cost is lower or the summary maintenance lifecycle is uncostable.

For an ephemeral summary:

Expand Down
Loading