diff --git a/README.md b/README.md index 6ed0603c..cdea7c9d 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ cargo build cargo test --workspace ``` -No external setup required. See [`docs/user-guide.md`](docs/user-guide.md) for how to run a +No external setup required. See [`docs/user-guide/user-guide.md`](docs/user-guide/user-guide.md) for how to run a query through the pipeline. ## Glossary @@ -220,17 +220,17 @@ semantic information that matters downstream. - Change input from a single query string to `QueryWorkload` (tracked in [#194](https://github.com/ProjectASAP/ASAPPlanner/issues/194) - Remove legacy data structures and types (tracked in [#179](https://github.com/ProjectASAP/ASAPPlanner/issues/179), [#205](https://github.com/ProjectASAP/ASAPPlanner/issues/205) -- Implement the ASAP-aware mapping [logic and interfaces](docs/asap_aware_mapping.md) +- Implement the ASAP-aware mapping [logic and interfaces](docs/design_docs/asap_aware_mapping.md) - Connect output of ASAPPlanner to asap-fusion - Connect output of ASAPPlanner to ASAPCollector and ASAPQuery (see open question #1 below) # Next steps -- [Description of pre-ASAP IR](docs/pre-asap-ir.md) -- [Description of post-ASAP IR](docs/post-asap-ir.md) -- [Converting a QueryWorkload to a pre-ASAP plan](docs/parse_and_canonicalize.md) -- [Converting a pre-ASAP plan to a post-ASAP plan](docs/asap_aware_mapping.md) -- [Guide on how to use ASAPPlanner](docs/user-guide.md) +- [Description of pre-ASAP IR](docs/design_docs/pre-asap-ir.md) +- [Description of post-ASAP IR](docs/design_docs/post-asap-ir.md) +- [Converting a QueryWorkload to a pre-ASAP plan](docs/design_docs/parse_and_canonicalize.md) +- [Converting a pre-ASAP plan to a post-ASAP plan](docs/design_docs/asap_aware_mapping.md) +- [Guide on how to use ASAPPlanner](docs/user-guide/user-guide.md) # Open questions diff --git a/crates/asap-aware-mapping/src/bind.rs b/crates/asap-aware-mapping/src/bind.rs index 53d605e2..60a2508c 100644 --- a/crates/asap-aware-mapping/src/bind.rs +++ b/crates/asap-aware-mapping/src/bind.rs @@ -115,7 +115,7 @@ pub fn implement_tree_with( /// A first pass over `roots` counts each distinct `Rc` pointer's /// true `consumer_count` across the whole workload, so the /// [`CseCandidate`]/[`CostModel::cse_share_decision`] cost comparison (see -/// `docs/cse-cost-model-decision.md`) sees the real total, not a running +/// `docs/design_docs/cse-cost-model-decision.md`) sees the real total, not a running /// count that grows as roots are processed left to right. The decision is /// made once, the first time a shared pointer is bound, and cached alongside /// the bound `SummaryNode` so every later occurrence of that same `Rc` diff --git a/crates/asap-aware-mapping/src/cost_model.rs b/crates/asap-aware-mapping/src/cost_model.rs index c4944f96..89cddb98 100644 --- a/crates/asap-aware-mapping/src/cost_model.rs +++ b/crates/asap-aware-mapping/src/cost_model.rs @@ -39,7 +39,7 @@ //! ([`asap_types::pre_asap::cse::share_common_subtrees`], issue #223 stages //! 1-2, PR #235) is actually worth sharing, via a real Volcano/Cascades-style //! cost comparison rather than a fixed rule. See -//! `docs/cse-cost-model-decision.md` for the full design discussion (why +//! `docs/design_docs/cse-cost-model-decision.md` for the full design discussion (why //! cost-based, why not a full plan-search engine, the layering constraint //! that forces detection to stay cost-agnostic). [`bind::implement_workload_with`](crate::bind::implement_workload_with) //! is the caller. @@ -59,7 +59,7 @@ use crate::boundary::Implementation; /// the first time it binds a subtree that /// [`asap_types::pre_asap::cse::share_common_subtrees`] already collapsed /// onto one `Rc` for two or more workload roots. See -/// `docs/cse-cost-model-decision.md`. +/// `docs/design_docs/cse-cost-model-decision.md`. pub struct CseCandidate<'a> { /// The shared pre-ASAP subtree itself. pub subtree: &'a QueryExpr, @@ -211,7 +211,7 @@ pub trait CostModel { /// Estimate the one-time cost of recomputing `candidate.subtree` /// independently at a single use site. Default: /// [`default_cse_recompute_cost`] (a structural-size proxy). See - /// `docs/cse-cost-model-decision.md`. + /// `docs/design_docs/cse-cost-model-decision.md`. fn cse_recompute_cost(&self, candidate: &CseCandidate) -> f64 { default_cse_recompute_cost(candidate.subtree) } @@ -223,7 +223,7 @@ pub trait CostModel { /// `candidate.bound_summary`'s output schema actually carries summary /// state (falls back to the cheapest, `Plain`, weight if none does — /// e.g. `bound_summary` is a passthrough `Logical` node with nothing - /// summary-shaped to maintain). See `docs/cse-cost-model-decision.md`. + /// summary-shaped to maintain). See `docs/design_docs/cse-cost-model-decision.md`. fn cse_shared_maintenance_cost(&self, candidate: &CseCandidate) -> f64 { let family = candidate .bound_summary @@ -242,7 +242,7 @@ pub trait CostModel { /// Decide whether to reuse one shared `SummaryNode` across every /// consumer of `candidate`, or bind each occurrence independently — a /// Volcano/Cascades-style cost comparison (issue #237, #223 stage 4; see - /// `docs/cse-cost-model-decision.md`): share iff the estimated cost of + /// `docs/design_docs/cse-cost-model-decision.md`): share iff the estimated cost of /// maintaining one shared summary is no greater than the estimated total /// cost of recomputing it independently everywhere it's used. /// diff --git a/crates/types/src/pre_asap/cse.rs b/crates/types/src/pre_asap/cse.rs index 0ec319d9..f27cb6ee 100644 --- a/crates/types/src/pre_asap/cse.rs +++ b/crates/types/src/pre_asap/cse.rs @@ -4,7 +4,7 @@ //! //! CSE only runs on an already-bound, already-canonicalized tree — //! structural matching is meaningless before canonicalization has converged -//! semantically-equivalent queries onto one shape (`docs/pre-asap-ir.md` +//! semantically-equivalent queries onto one shape (`docs/design_docs/pre-asap-ir.md` //! design principle 3; `median(latency)` and `approx_percentile_cont(latency, //! 0.5)` already lower to an identical `AggIntent::Quantile` today, per //! `sql_lowering.rs`'s `median_is_the_same_intent_as_an_explicit_half_percentile` @@ -94,7 +94,7 @@ //! `asap_aware_mapping::cost_model::CostModel::cse_share_decision` and its //! caller, `asap_aware_mapping::bind::implement_workload_with` — a real, //! Volcano/Cascades-style cost comparison over what this module detects, not -//! a fixed rule. See `docs/cse-cost-model-decision.md`. This module's own +//! a fixed rule. See `docs/design_docs/cse-cost-model-decision.md`. This module's own //! unconditional "share whenever legal" behavior is unchanged: detection //! stays cost-agnostic by construction (this crate cannot depend on //! `asap-aware-mapping`'s `CostModel`), and the cost-aware decision is diff --git a/docs/asap_aware_mapping.md b/docs/design_docs/asap_aware_mapping.md similarity index 100% rename from docs/asap_aware_mapping.md rename to docs/design_docs/asap_aware_mapping.md diff --git a/docs/cse-cost-model-decision.md b/docs/design_docs/cse-cost-model-decision.md similarity index 100% rename from docs/cse-cost-model-decision.md rename to docs/design_docs/cse-cost-model-decision.md diff --git a/docs/parse_and_canonicalize.md b/docs/design_docs/parse_and_canonicalize.md similarity index 100% rename from docs/parse_and_canonicalize.md rename to docs/design_docs/parse_and_canonicalize.md diff --git a/docs/post-asap-ir.md b/docs/design_docs/post-asap-ir.md similarity index 100% rename from docs/post-asap-ir.md rename to docs/design_docs/post-asap-ir.md diff --git a/docs/pre-asap-ir.md b/docs/design_docs/pre-asap-ir.md similarity index 100% rename from docs/pre-asap-ir.md rename to docs/design_docs/pre-asap-ir.md diff --git a/docs/user-guide.md b/docs/user-guide/user-guide.md similarity index 95% rename from docs/user-guide.md rename to docs/user-guide/user-guide.md index 1cda23fc..301b9fa5 100644 --- a/docs/user-guide.md +++ b/docs/user-guide/user-guide.md @@ -116,6 +116,6 @@ Match on `post_asap.expr` (a `SummaryExpr`): - `SummaryEstimate { summary_input, query }` — wraps a sketch `SummaryAgg`; `query` is what to read out of it (`Quantile`, `Cardinality`, `TopK`, `PointCount`). -`docs/asap_aware_mapping.md` has the conceptual background (why this layer exists, what an -"implementation" is); `docs/pre-asap-ir.md` / `docs/post-asap-ir.md` are the node-by-node IR +`docs/design_docs/asap_aware_mapping.md` has the conceptual background (why this layer exists, what an +"implementation" is); `docs/design_docs/pre-asap-ir.md` / `docs/design_docs/post-asap-ir.md` are the node-by-node IR reference.