Skip to content

docs: clarify Planner window ownership - #586

Merged
zzylol merged 1 commit into
mainfrom
docs/clarify-planner-window-boundary
Sep 3, 2026
Merged

zzylol merged 1 commit into
mainfrom
docs/clarify-planner-window-boundary

Conversation

@zzylol

@zzylol zzylol commented Sep 3, 2026

Copy link
Copy Markdown
Contributor

Why

The existing planner-integration and physical-planning pages describe parts of
the boundary, but do not give one canonical, executable contract for turning
ASAPPlanner candidates into coordinated runtime plans. The boundary must also
distinguish an abstract primitive choice from its concrete runtime
implementation.

After this PR

One architecture page defines the feedback and compilation boundary:

ASAPPlanner abstract candidates and selection
        -> ASAPQuery-backend implementation enumeration
        -> DataWorkload-specific cost evidence back to ASAPPlanner
        -> SDK startup artifact + CollectorPlan + BackendPlan

ASAPPlanner owns abstract summary primitives, including the sketch algorithm,
summary-window framework, and maintenance-lifecycle candidates. Window
frameworks include tumbling, sliding, exponential histogram, and extensible
future alternatives. Incremental maintenance and window framework are
orthogonal: one describes update behavior and the other temporal state
organization.

ASAPQuery-backend enumerates concrete runtime implementations and
configurations for every Planner candidate. It owns physical identities, pane
sizing, state layout, placement, sharding, storage, transmission, and executor
capability checks. It feeds measured or estimated CPU, memory, network,
storage, and scan behavior under the same DataWorkload back into Planner's
cost model. ASAPCollector validates and executes the resulting compiled
physical plan; it does not redo planning.

TransmissionPlan is a shared typed section; backend precompute and query
routing are BackendPlan sections. The document also defines:

  • error composition in one query-output metric, with explicit
    failure-probability allocation;
  • family-specific threshold domains and a delivery-aware drift bound;
  • one-in-flight/one-pending backpressure behavior;
  • patched-OTLP FrameAck semantics and atomic backend sequence application;
  • Collector WAL and same-epoch restart replay requirements;
  • static MVP SDKPlan delivery and semantic activation evidence;
  • versioned cross-repository golden artifacts;
  • deterministic and statistical SDK sampling acceptance tests; and
  • an implementation-status table separating existing partial components from
    remaining MVP work.

Validation

  • git diff --check
  • verified balanced display-math delimiters
  • verified unsupported operatorname/environment macros are absent
  • verified the three boundary documents use the same window-ownership model
  • MVP collector CI runs on the pushed commit

Scope

Documentation only. No runtime types, planner adapter, wire schema, or
deployment behavior changes in this PR.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant