docs: align #509/#511/#573 docs with the decided vocabulary and Pass 1 candidates

[zzylol]

Why

The #509 / #511 / #573 design docs lagged behind decisions already made in code review: the vocabulary is "evaluation", not "readout"; Pass 1's targets were never defined; and Pass 1's exact accumulator option, which #561 generates, was missing from #509, so Example 1's candidate counts were wrong.

What

Documentation only.

• docs: define unified operators and SQL/PromQL scalar boundaries #511 / docs: ASAP primitive schema and summary coverage (definition + selection) #573 vocabulary (operator-sharing.md, asap-primitive-schema.md): ReadPopulation { readout } → EvaluatePopulation { evaluation } (the names in crates/types/src/ir/asap.rs), "readout" → "evaluation" where it names reading a summary, and SummaryAgg gains its filter field as in the code.
• docs: propose workload-wide planning, summary sharing, and materialization #509 eligible sub-DAG (planner-layering.md): defined at its first use. A sub-DAG is eligible when its root is an Aggregate whose intent has at least one realization (exact accumulator state or a summary family). Nested aggregations are separate targets.
• docs: propose workload-wide planning, summary sharing, and materialization #509 Pass 1 table and Example 1: each target gets one exact option. If its intent has an exact mergeable accumulator (Count, Sum, Min, Max, Rate, IRate, Increase; avg via sum and count) and the accumulator can be built, that option is exact accumulator state (SummaryAgg with an exact family → FinalizeExactAccumulator); otherwise it is the plain exact computation. With nested targets, Example 1 has four targets (Q1's per-series rate and per-job sum, Q2's per-series sum_over_time and top-k), and the totals stay 1 × 1 × 1 × 3 = 3, 54 and 156. The Algorithm 1 example and its diagram follow.

How

Minimal edits; no other wording changed. The coverage cache in #573 (§4.2.3, §6.1) is left as is: it is the decided design, not yet implemented (#651).

Before this PR

The docs said ReadPopulation / readout, used "eligible sub-DAG" without a definition, and counted Example 1 with one option for Q1 and no nested targets.

After this PR

The docs use the code's names, define Pass 1's targets, and Example 1's counts match what Pass 1 enumerates.

Evidence

The Example 1 targets were checked by running #561's enumerate_local_logical_candidates on Example 1's two queries with the doc's accuracy targets: it finds the same 4 targets. #561 is being updated to offer one exact option per target, which gives 1, 1, 1 and 3 options. (The code offers Count-Sketch + heap where the doc lists Hydra for top-k; TopK Hydra is being added in #605. That does not change the count.) Screenshots and measurements: not applicable.

Verification

• Documentation only; no code change. The edited mermaid diagram was not rendered locally.

Architectural decisions

• Every aggregation, including nested ones, is its own Pass 1 target, and target options multiply (decided in the feat(planner): Stage 1 Pass 1 per-computation candidate generation #561 review).
• One exact option per target (decided in this PR's review): the plain exact computation would duplicate "accumulator, not materialized", which is the raw plan for targets with an accumulator.
• MaintainedPopulation<N = QueryExpr> in docs: ASAP primitive schema and summary coverage (definition + selection) #573 is unchanged here: on main the code default is still QueryExpr; refactor(ir): remove the legacy QueryExpr and SummaryExpr IRs; move docs and DAG viewer to the unified IR #543 changes the code default to OperatorNode and updates the doc with it.

Limitations and follow-up

• Multi-measure aggregates are not described yet.

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:

🤖 Generated with Claude Code

https://claude.ai/code/session_01W7qG9aFyPij5uWsyAJCxDW