Skip to content

docs(design): model workload demand and summary lifecycle - #310

Open
zzylol wants to merge 1 commit into
mainfrom
design/workload-demand-lifecycle
Open

docs(design): model workload demand and summary lifecycle#310
zzylol wants to merge 1 commit into
mainfrom
design/workload-demand-lifecycle

Conversation

@zzylol

@zzylol zzylol commented Aug 28, 2026

Copy link
Copy Markdown
Contributor

Why

ASAPPlanner currently distinguishes one-shot consumers, fixed-interval repeating queries, and an ingest-rate proxy, but it does not model query predictability, queried time scope, data-at-rest versus continuous ingestion, demand uncertainty, or the lifecycle of summary state.

This matters because a summary operator is not inherently continuously maintained. The same exact or approximate summary may be built ephemerally for one invocation, prepared for a known future query, shared for a bounded period, or maintained incrementally.

What

Adds a design document that:

  • models ad-hoc/predictable, one-time/repeated, and real-time/longitudinal as independent query-workload axes;
  • separates query demand from data-workload arrival, volume, rate, cardinality, and distribution;
  • separates operator statefulness, evaluation schedule, output representation, and state lifecycle;
  • defines ephemeral, prepared, shared, and continuously maintained lifecycle alternatives;
  • extends the existing horizon-based recurrence cost model conceptually rather than introducing a second cost system;
  • defines conservative behavior for unknown or stale demand evidence;
  • reviews current ASAPPlanner coverage against the ProjectASAP glossary at pinned revision 03e1c70;
  • records acceptance cases, alternatives, rollout stages, and open architecture decisions.

The ASAP-aware mapping design index links the new document.

Before this PR

The design could describe a root as one-shot or fixed-interval repeating and could derive update/evaluation rates, but it had no authoritative answer to:

Should this SummaryAgg be built once, prepared, retained for sharing,
or continuously maintained?

Repeated query demand could also be confused with continuously ingesting data.

After this PR

The design treats those facts independently:

logical query
  + query demand (predictability, recurrence, time scope)
  + data workload (arrival, volume/rate, cardinality, distribution)
  + available state
      -> legal execution contracts and state lifecycles
      -> accuracy legality
      -> horizon-normalized cost
      -> selected plan and explicit state deployments

Identical query syntax can therefore receive different lifecycle alternatives under unpredictable one-time, scheduled one-time, repeated-at-rest, and repeated-continuous workloads.

Verification

  • git diff --check
  • verified local Markdown targets referenced by the new document
  • reviewed terminology and missing coverage against the pinned internal glossary revision
  • pre-commit was not available in the environment; this PR changes Markdown only

Scope and follow-up

This PR is design documentation only. It does not change public Rust types or planner behavior. The document leaves uncertain-demand objective policy, template equivalence, horizon ownership, runtime state ownership, time-scope classification, and empirical evidence freshness as explicit decisions requiring owners.

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