docs: add an Interface section to each L1-L5 doc

[zzylol]

Summary

Fixes #168.

PR #157 rewrote design.md + the per-layer docs to be pure principle/design-level, deliberately stripped of code-level detail. This adds the promised follow-up (per the note on #157: "please just review design.md for overall convergence for now... before we flesh out the API/interface details per layer") — a concrete Rust API surface per layer, added as a new ## Interface section at the end of each doc, on top of the existing principle-level content (which is untouched).

Every signature was verified against current main source before being written down — nothing here is carried over from an old draft or assumed from memory.

Per-layer notes

• L1: no shared trait exists today — each front end exposes its own free functions (lower_promql*, lower_sql*), converging on the same QueryExpr return type. This section is intentionally thin; that's the honest current shape, not an oversight.
• L2: SchemaCatalog (the pluggable schema-source trait Binder is generic over) + Binder + convert_root.
• L3: QueryExpr's shape (a representative slice — it's a ~24-variant enum, not reproduced in full), Reduction + GroupKeys in full (small, and central to this doc's own design principles), a representative AggIntent slice, and Schema.
• L4: SummaryExpr/L4Node, the binding entry points (implement_tree/implement_tree_with) + Implementation, the CostModel extension point (all its default-having methods shown so a reader sees what's actually mandatory to implement), and SummaryExecutor in full — the real, load-bearing serving-time interface just resolved via SummaryExecutor::find_candidates: empty by is ambiguous between "no grouping concept" and "explicit full reduction" #163/fix(sketch): SummaryAgg carries L3's Reduction directly, resolving the empty-by ambiguity #164/Design proposal: separate "what kind of computation" from "which dimensions to group by" in the intent algebra (dbt-style measure/dimension split) #165.
• L5: speculative — no asap-physical crate exists yet. Recovered the PhysicalPlanner/TopologyDescriptor/StageAllocator sketch an earlier draft of this doc had (before PR docs: split design.md into per-layer docs (L1-L5) + a slim index #157's final principle-level rewrite trimmed it out), updated to current summary-bound-IR naming (L4Node, SummaryKind instead of the old SketchExpr/SketchKind), and kept the same explicit "target to design against, not an API to depend on" framing this doc already uses, so it can't be mistaken for shipped code.

Test plan

• Every signature cross-checked against crates/frontend-promql, crates/frontend-sql, crates/l2, crates/ir, crates/sketch, crates/plan on current main.
• Markdown code-fence balance checked for all 5 files.
• Docs-only change — no code touched.

🤖 Generated with Claude Code

[zzylol]

Pushed 464241d addressing all 10 review comments from the pending review.

Doc-only fixes (done)

• L3 — reduction/Reduction/GroupKeys clarified as plain data on Aggregate itself, not tree nodes; AggIntent expanded from a representative slice to the full ~30-variant vocabulary (including Extension).
• L4 — added an explanation of what "Implementation" means (the per-intent binding decision's own result type: sketch vs. exact accumulator vs. pass-through).
• L5 — folded "what does edge mean", "StageId values are deployment-owned, not ASAPController's", and "this is interface-only in ASAPController" into one clarification at the top of the Interface section, and reworded StageId's inline comment so the example stage names don't read as a fixed vocabulary.

Two real code-change proposals (not done — flagged in the doc, not silently executed)

Two comments were actually about the code, not the docs, so I didn't just reword prose to match — I left the doc accurate to what's really shipped today and wrote the proposal inline instead:

1. Rename sketch/sketch_input → summary/summary_input on SummaryExpr::SummaryAgg/SummaryDelete/SummaryEstimate (crates/sketch/src/expr.rs). Agree with the reasoning — these names predate the summary/sketch terminology split this doc itself uses. Holding off on executing it in this PR because it's a breaking rename of fields every SummaryExecutor implementer pattern-matches on, and there are two ASAPQuery-backend PRs (feat(sql): support date types and calendar interval expressions #419/feat(sql): lower corr to a two-column extension intent #420) actively being updated against the current field names right now — landing the rename mid-flight would just make both moving targets. Worth its own follow-up PR once those settle.
2. Merge Implementation::Sketch{..} / Implementation::ExactAccumulator{..} into one Summary{..} variant (crates/plan/src/boundary.rs). Feasible, but only if SummaryKind grows something like is_exact() so bind_summary_agg can still tell the two apart (today the variant tag is that signal — it decides whether a SummaryEstimate readout gets wrapped on afterward). Suggest doing this together with proposal 1 rather than as two separate breaking changes to the same call sites, for the same reason as above.

Let me know if you'd like me to go ahead and implement either of these now, or file them as a follow-up issue instead.

🤖 Generated with Claude Code

[milindsrivastava1997]

@zzylol L1 and L2 lgtm. Haven't read through the rest. Do you just want me to do a high-level pass or do you want detailed comments?

[zzylol]

@zzylol L1 and L2 lgtm. Haven't read through the rest. Do you just want me to do a high-level pass or do you want detailed comments?

High-level pass is okay. If you have time, detailed comments are appreciated as well.

[zzylol]

I will merge it for now. The doc cleaning and interface definitions are done. We can refine them with future PRs.