docs: reconcile core::optimizer/core::plan with what's actually shipped - #145
Merged
zzylol merged 1 commit intoJul 21, 2026
Merged
Conversation
Flagged in #144's review: design.md's core::optimizer (L4 framework) and core::plan (shared cross-layer traits) sections described a general Cascades-style rule engine (OptimizerRule/RuleEngine, a shared rule library keyed by BindKllOnQuantile-style structs) that was never built. What actually shipped in crates/plan (asap-plan) is narrower: boundary::implementation_for (per-node choice), bind::implement_tree (whole-tree walk), cost_model::CostModel (the one pluggable ranking extension point, not a general rewrite interface), cse::dedupe_subtrees (workload CSE), and boundary::Matcher (the "does an available Implementation satisfy a required one" question, #144's "Match" row). core::optimizer now leads with what's real, cites the #144 terminology table for each piece, and explains what a deployment does beyond asap-plan's scope (implement_tree's conservative non-Aggregate stop, any rewriting past summary-candidate ranking) using ASAPQuery-backend's control_plane as the concrete downstream example. The original rule- engine sketch survives in a collapsed <details> block, explicitly labeled "never built", instead of silently disappearing -- readers who remember it (or find it in git blame) get a pointer to why it's gone rather than a mystery. core::physical (L5) and core::plan get a "Status: planned, not yet built" callout each -- confirmed via grep that no asap-physical crate or DeploymentModel/PhysicalPlanner/OptimizerRule/StageAllocator type exists anywhere in the workspace. core::plan additionally flags its own naming collision with the real asap-plan crate (a different thing entirely, landed under core::optimizer) since that's confusing on its own even setting the staleness aside. Also fixes §6.0's crate-map table: core::cost was listed "stub" but cost_model.rs is real, tested code (just deliberately narrow in scope, not incomplete). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
zzylol
deleted the
docs/reconcile-optimizer-plan-with-real-implementation
branch
July 21, 2026 21:30
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Follow-up to #144's review flag:
design.md'score::optimizer(L4 framework) andcore::plan(shared cross-layer traits) sections described a general Cascades-style rule engine (OptimizerRule/RuleEngine, a shared rule library) that was never built. What actually shipped incrates/plan(asap-plan) is narrower and different in shape.core::optimizernow leads with what's real:boundary::implementation_for(per-node choice),bind::implement_tree(whole-tree walk),cost_model::CostModel(the one pluggable ranking extension point -- not a general rewrite interface),cse::dedupe_subtrees(workload CSE),boundary::Matcher(the "does an availableImplementationsatisfy a required one" question -- docs: document bind/implementation/match terminology and their layers #144's "Match" terminology row). Cites docs: document bind/implementation/match terminology and their layers #144's terminology table throughout. Explains what a deployment does beyondasap-plan's scope (the conservative non-Aggregatestop inimplement_tree, any rewriting past summary-candidate ranking), using ASAPQuery-backend'scontrol_planeas the concrete downstream example.<details>block, explicitly labeled "never built" -- so it doesn't just silently vanish for anyone who remembers it or finds it in git blame.core::physical(L5) andcore::planeach get a "Status: planned, not yet built" callout -- confirmed via grep that noasap-physicalcrate, and noDeploymentModel/PhysicalPlanner/OptimizerRule/StageAllocatortype, exists anywhere in the workspace.core::planadditionally flags that its own name collides with the real, landedasap-plancrate (a completely different thing, documented undercore::optimizer) -- confusing even setting the staleness aside.core::costwas listed "stub" butcost_model.rsis real, tested code (deliberately narrow in scope, not incomplete).Test plan
<details>/code-fence balance (grep -csanity check) and read through the full diff in contextOptimizerRule/RuleEngine/PhysicalPlanner/DeploymentModel/StageAllocator/SketchCatalogdon't exist anywhere, before writing the "never built" framing🤖 Generated with Claude Code