Skip to content

feat(plan): pluggable AggIntent::Extension realization + readout hook (closes #150) - #162

Merged
zzylol merged 1 commit into
mainfrom
feat/extension-realization-hook
Jul 25, 2026
Merged

zzylol merged 1 commit into
mainfrom
feat/extension-realization-hook

Conversation

@zzylol

@zzylol zzylol commented Jul 25, 2026

Copy link
Copy Markdown
Contributor

Summary

Closes #150: boundary::implementation_for_with mapped every AggIntent::Extension unconditionally to Implementation::PassThrough, with no way for a deployment to opt in to its own realization for a shape core doesn't know (e.g. control_plane's Extension{"frequency"} point-frequency intent — count(*) WHERE key = k).

Two new CostModel methods, both with safe defaults so every existing deployment is unaffected:

  • realize_extension(ext_kind, payload) -> Implementation — consulted by implementation_for_with's Extension arm instead of hardcoding PassThrough. Default: PassThrough (today's behavior).
  • readout_extension(ext_kind, payload, col) -> SketchQuery — consulted by bind::readout's new Extension arm. This half wasn't in boundary::implementation_for maps AggIntent::Extension to PassThrough unconditionally — no deployment-specific realization hook #150's literal ask, but turned out to be required for the feature to work end-to-end: readout() previously had other => unreachable!(...) for anything besides Quantile/Cardinality/TopK/Count — a CostModel that realizes an Extension as Sketch via realize_extension alone would panic the first time readout() actually fires for it. Default panics loudly with a clear message pointing at the missing override, rather than silently misinterpreting payload.

Also adds SketchQuery::PointCount.value: Option<String> — needed by readout_extension to carry a per-item filter value (e.g. count(cms_metric{item="checkout"})PointCount{key: Named("item"), value: Some("checkout")}). SketchQuery is a closed, exhaustively-matched enum with no room to grow this otherwise, and no SummaryExecutor implementation has any way to resolve a filter value on its own — readout()'s trait signature has no tree/QueryExpr access at all, only the already-decoded state + query.

This is prep work for ASAPQuery-backend's data_plane to close its own SketchQuery::PointCount named-key gap (companion to the SketchQuery::TopK gap closed in ASAPQuery-backend#412) — control_plane will implement both new methods for its Extension{"frequency"} intent in a follow-up PR once this merges.

Test plan

  • cargo test -p asap-plan -p asap-sketch — 39 tests, all passing, including 2 new: extension_intent_stays_logical_by_default (regression check — an Extension intent with no CostModel override still stays Logical, unchanged) and extension_intent_binds_via_custom_cost_model (a custom CostModel overriding both hooks binds a real SummaryAgg/SummaryEstimate with the expected SketchKind/SketchQuery::PointCount{key, value} instead of Logical/a panic).
  • cargo test --workspace — full workspace, 400+ tests across all crates, all passing.
  • cargo build --workspace — clean.
  • cargo clippy --workspace --all-targets — zero warnings.
  • rustfmt scoped to the touched files.

🤖 Generated with Claude Code

Closes the gap tracked in #150: boundary::implementation_for_with mapped
every AggIntent::Extension unconditionally to Implementation::PassThrough,
with no way for a deployment to opt in to its own realization for a
shape core doesn't know (e.g. control_plane's Extension{"frequency"}
point-frequency intent).

Adds two CostModel methods, both defaulting to today's behavior so no
existing deployment is affected:
- realize_extension(ext_kind, payload) -> Implementation, consulted by
  implementation_for_with's Extension arm instead of hardcoding
  PassThrough.
- readout_extension(ext_kind, payload, col) -> SketchQuery, consulted by
  bind::readout's new Extension arm. This half wasn't in #150's original
  ask, but is required for the feature to work end-to-end: readout()
  previously had `other => unreachable!()` for anything besides
  Quantile/Cardinality/TopK/Count, so a CostModel that realizes an
  Extension as Sketch without this would panic the first time it's read
  out.

Also adds SketchQuery::PointCount.value: Option<String>, needed by
readout_extension to carry a per-item filter value (e.g.
count(cms_metric{item="checkout"}) -> PointCount{key: Named("item"),
value: Some("checkout")}) -- SketchQuery is a closed, exhaustively-matched
enum with no room to grow this otherwise, and no SummaryExecutor
implementation has any way to resolve a filter value on its own (readout
gets no tree access).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@zzylol
zzylol merged commit 64df20d into main Jul 25, 2026
1 check passed
@zzylol
zzylol deleted the feat/extension-realization-hook branch July 25, 2026 19:38
zzylol added a commit that referenced this pull request Jul 28, 2026
Rebased onto main (now past #162/#164/#165/#166) after PR #157's original
37-commit history hit real conflicts with the intervening Reduction/L4
grouping-model work -- squashed to one commit here since the PR merges
as a squash anyway, so the intermediate history wasn't worth preserving
through a 37-way conflict resolution.

`docs/design.md` was a 1500+ line document mixing layer design, migration
planning, and crate-by-crate speculation, most of it already stale
relative to the shipped code. This does the same move `l4node-execution-
model.md` already made for L4 across the rest of the pipeline: each layer
gets its own doc, `design.md` becomes a thin index into them, and every
doc is cross-checked against current code rather than copied from old
drafts.

- New per-layer docs: `l1-query-language.md`, `l2-logical-plan.md`,
  `l3-intent-algebra.md`, `l5-physical-plan.md` (l4's already existed,
  renamed to `l4-summary-bound-ir.md` to match the shipped
  `SummaryExpr`/`SummaryKind`/`L4Node` naming instead of the older
  "sketch" framing). `l1-query-language.md` also absorbs the old
  standalone `promql-lowering.md` as a section.
- `design.md` cut to a slim index: one paragraph per L1-L5 linking to its
  doc, plus a trimmed Glossary.
- Deleted `docs/migration-plan.md` and `docs/intent-algebra-
  reconciliation.md` -- both were migration-era planning artifacts, the
  latter already self-annotated as a superseded historical snapshot.
- `crates/sketch/src/exec.rs`'s doc comments repointed at the renamed
  `l4-summary-bound-ir.md`.

Known gap carried over from the original PR (not introduced by this
rebase): README.md still links to `docs/migration-plan.md` and to
`docs/design.md`'s old §3/§6/§8/§9/§11/§12 section numbers, none of
which exist after this change -- worth a follow-up.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
zzylol added a commit that referenced this pull request Jul 28, 2026
Rebased onto main (now past #162/#164/#165/#166) after PR #157's original
37-commit history hit real conflicts with the intervening Reduction/L4
grouping-model work -- squashed to one commit here since the PR merges
as a squash anyway, so the intermediate history wasn't worth preserving
through a 37-way conflict resolution.

`docs/design.md` was a 1500+ line document mixing layer design, migration
planning, and crate-by-crate speculation, most of it already stale
relative to the shipped code. This does the same move `l4node-execution-
model.md` already made for L4 across the rest of the pipeline: each layer
gets its own doc, `design.md` becomes a thin index into them, and every
doc is cross-checked against current code rather than copied from old
drafts.

- New per-layer docs: `l1-query-language.md`, `l2-logical-plan.md`,
  `l3-intent-algebra.md`, `l5-physical-plan.md` (l4's already existed,
  renamed to `l4-summary-bound-ir.md` to match the shipped
  `SummaryExpr`/`SummaryKind`/`L4Node` naming instead of the older
  "sketch" framing). `l1-query-language.md` also absorbs the old
  standalone `promql-lowering.md` as a section.
- `design.md` cut to a slim index: one paragraph per L1-L5 linking to its
  doc, plus a trimmed Glossary.
- Deleted `docs/migration-plan.md` and `docs/intent-algebra-
  reconciliation.md` -- both were migration-era planning artifacts, the
  latter already self-annotated as a superseded historical snapshot.
- `crates/sketch/src/exec.rs`'s doc comments repointed at the renamed
  `l4-summary-bound-ir.md`.

Known gap carried over from the original PR (not introduced by this
rebase): README.md still links to `docs/migration-plan.md` and to
`docs/design.md`'s old §3/§6/§8/§9/§11/§12 section numbers, none of
which exist after this change -- worth a follow-up.

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
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.

boundary::implementation_for maps AggIntent::Extension to PassThrough unconditionally — no deployment-specific realization hook

1 participant