Skip to content

docs: outline how ASAPPlanner supports a new end-to-end use case - #684

Open
zzylol wants to merge 7 commits into
mainfrom
docs/asapplanner-e2e-use-case
Open

zzylol wants to merge 7 commits into
mainfrom
docs/asapplanner-e2e-use-case

Conversation

@zzylol

@zzylol zzylol commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

Why

planner-layering.md designs the planning stages, but there is no guide for bringing a new use case onto ASAPPlanner: how to describe its workloads, which ASAP Primitives fit, what to add when a primitive is missing, and how a deployment runtime integrates with the planner so the use case shows an end-to-end benefit.

What

Adds one file, docs/design_docs/proposals/asapplanner-e2e-use-case.md (111 lines). No other doc or code changes. It is an outline: each section holds key points marked "to be expanded".

  1. Defining the query and data workloads from recorded traces. The output is a PlanningWorkload: per query (text and language, accuracy target, latency, recurrence and predictability, time selection) and per source (schema, arrival and retention, cardinality and value distribution). It also covers the overlap analysis that makes ASAP worthwhile and declaring unmeasurable statistics as unknown.
  2. Query patterns → ASAP Primitives: a table from intent (count/sum, quantile, top-k, distinct count, frequency moments, high cardinality, overlapping windows, shared sub-expressions) to candidate primitives and the workload conditions each needs. It also states the eligible / valid / selected distinction.
  3. Adding a new ASAP Primitive: eight steps (capability declaration, Pass 1 offer, sizing and error bound, Stage 2 operator, Stage 3 pricing, executor kernel over the sketch library, sketch-bench measurements, tests). This extends planner-layering.md's "Adding a new summary family".
  4. Integrating with a deployment: a six-step workflow (collect → plan → validate and install → execute → observe and re-plan → compare with the exact baseline) and a table of interfaces between deployment and planner (e2e_plan, PlanningModels, capabilities, PhysicalASAPDAGDocument, the selection report, feedback).

How

Written as a design proposal next to planner-layering.md. It links that doc and asap-primitive-schema.md and keeps stage names and terms aligned with them.

Key code interfaces added / modified

None (documentation only)

Before this PR

The stage design existed, but no doc said how to go from a use case to a planned, deployed workload, or how to add a missing primitive end to end.

After this PR

There is one outline that covers that path, section by section, ready to be filled in.

Verification

  • Doc-only. Build, tests, screenshots and measurements: not applicable.
  • Links: planner-layering.md, its "Adding a new summary family" section, and asap-primitive-schema.md exist on main.

Limitations and follow-ups

Human review — do not complete with an agent

  • The MVP boundary is correct.
  • New conceptual layers or public interfaces are necessary.
  • The before/after description matches the intended product behavior.
  • Human reviewer:
  • Decision and rationale:

Problem Definition (motivation, numbered requirements), ASAPPlanner Design
(intuition, Assumptions 9-12, deployment/planner overview with an input-to-stage
table), Detailed Design per input with rules, outputs and handoff contract
(Algorithms 1-2), missing components, adding a summary family (Algorithm 3) and
workload/capability matching, two end-to-end examples, scenarios and open
questions. Factual content and status markings unchanged.
@zzylol zzylol added the documentation Improvements or additions to documentation label Oct 14, 2026
@zzylol zzylol changed the title docs: ASAPPlanner end-to-end use case — inputs, outputs, missing components, adding a summary family docs: outline how ASAPPlanner supports a new end-to-end use case Oct 14, 2026
@zzylol
zzylol force-pushed the docs/asapplanner-e2e-use-case branch from d8c9213 to d6dc11c Compare October 14, 2026 23:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant