@@ -15,88 +15,9 @@
 // specific language governing permissions and limitations
 // under the License.
 
-//! Physical optimizer traits
+//! [`PhysicalOptimizer`] for optimizing [`ExecutionPlan`]s
 //!
-//! # Physical Optimizer Contract
-//!
-//! This section explains the contract for extending or replacing the default
-//! list of optimizer rules.
-//!
-//! [`PhysicalOptimizer::new`] defines the default rule sequence:
-//!
-//! ```text
-//! // Default rules
-//! let rules = vec![
-//!     rule1,
-//!     rule2,
-//!     rule3,
-//!     rule4,
-//!     // ...
-//! ];
-//! ```
-//!
-//! It's recommended to keep the default rule order and using supported configuration
-//! options to disable optimizations. These variations preserve correctness. For
-//! example, `SET datafusion.optimizer.enable_distinct_aggregation_soft_limit = false`
-//! disables the distinct aggregation soft-limit optimization. Custom pipelines
-//! require more care, as described below.
-//!
-//! ## Custom Optimizer Pipelines
-//!
-//! The following extension pipeline can expect built-in optimizer rules to preserve
-//! plan validity, but not to provide complete optimization coverage.
-//!
-//! ```text
-//! // Custom rules
-//! let rules = vec![
-//!     rule3,
-//!     extension_rule_1,
-//!     rule1,
-//! ];
-//! ```
-//!
-//! - **Plan Validity:** Applying `rule1` after `rule3` should preserve query
-//!   semantics and return a valid plan without internal errors or invalid
-//!   plan shapes.
-//!
-//!   The pipeline must still satisfy requirements needed for correctness. For
-//!   example, [`EnsureRequirements`] enforces input distribution and ordering.
-//!   Some constraints remain implicit or are documented only in individual rules.
-//!
-//! - **Optimization Coverage:** A non-default rule order may expose rules to
-//!   plan shapes they do not recognize, causing them to miss optimizations
-//!   that would apply in the default pipeline.
-//!
-//!   For example, [`LimitedDistinctAggregation`] runs before [`EnsureRequirements`]
-//!   and [`CombinePartialFinalAggregate`], so it only targets the canonical shape. To keep
-//!   its implementation simple, it does not guarantee optimization coverage for
-//!   non-canonical shapes produced by extension pipelines.
-//!
-//!   ```txt
-//!   -- Canonical (default pipeline):
-//!   -- Built-in rule recognize and optimize this shape
-//!   Limit
-//!     Aggregate(Final)
-//!       Aggregate(Partial)
-//!
-//!   -- Non-canonical (repartitioning inserted first):
-//!   -- Built-in rule skip the optimization
-//!   Limit
-//!     Aggregate(Final)
-//!       Repartition
-//!         Aggregate(Partial)
-//!   ```
-//!
-//! For custom optimizer pipelines:
-//!
-//! - Reordering optimizer rules must still result in a valid plan, subject to the
-//!   correctness requirements above. Downstream projects may add unit tests for
-//!   built-in rules to guard against correctness regressions.
-//! - Extending built-in rules to match plan shapes that the default rule order
-//!   cannot produce is discouraged. Prefer adding a custom optimizer rule that
-//!   transforms the plan into a standard shape recognized by built-in rules.
-//!   If extending a built-in rule is still necessary, please open a DataFusion
-//!   issue to discuss it.
+//! [`ExecutionPlan`]: datafusion_physical_plan::ExecutionPlan
 
 use std::fmt::Debug;
 use std::sync::Arc;
@@ -162,7 +83,96 @@ impl PhysicalOptimizerContext for ConfigOnlyContext<'_> {
 
 /// A rule-based physical optimizer.
 ///
-/// Applies its rule list in order in a single pass.
+/// Applies a *Pipeline* (an ordered list) of [`PhysicalOptimizerRule`]s in a single pass.
+///
+/// # Physical Optimizer Contract
+///
+/// [`PhysicalOptimizer::new`] defines the default sequence of
+/// [`PhysicalOptimizerRule`]s. The optimizer applies them in order, in a single
+/// pass. This section describes the contract between the optimizer rules, both
+/// for projects that extend or reorder the default rule list and for
+/// contributors adding new built-in rules.
+///
+/// ## Invariants
+///
+/// The following properties hold for all rules (built-in and custom):
+///
+/// 1. **Correctness.** The returned plan must a) be valid (it can be executed
+///    without internal errors) and b) produce the same results as the input
+///    plan. A rule may change the operators in the plan, such as changing
+///    which operator implements a join, but it may never change the query's
+///    semantics.
+///
+/// 2. **Reorderable.** Because each rule preserves correctness, running the
+///    rules in a different order must still yield a valid plan that produces
+///    the same results.
+///
+/// ### Exceptions
+///
+/// Some built-in rules do not yet fully satisfy the invariants above because
+/// they are responsible for making an initial plan *executable* rather than for
+/// optimizing an existing plan:
+///
+/// - [`EnsureRequirements`] inserts the repartitioning and sorting needed to
+///   satisfy the distribution and ordering requirements.
+/// - [`OutputRequirements`] records output requirements.
+/// - [`SanityCheckPlan`] rejects plans whose requirements are not satisfied.
+///   It should run last.
+///
+/// Custom pipelines must keep these rules in a compatible relative order. We
+/// are working to remove these exceptions, so that all rules can be reordered
+/// freely.
+///
+/// ## Optimization Coverage Is Not Guaranteed
+///
+/// The invariants above guarantee *correctness*, not that every optimization is
+/// applied. Built-in rules often match specific plan shapes that may only occur
+/// at a certain point in the default pipeline. Adding, removing, or reordering
+/// rules can change plan shapes, so a built-in rule may silently miss an
+/// optimization that would apply in the default order. To keep their
+/// implementations simple, built-in rules typically only recognize shapes that
+/// the default pipeline produces.
+///
+/// For example, [`CombinePartialFinalAggregate`] runs after
+/// [`EnsureRequirements`] and only merges a `Partial` aggregate that is the
+/// direct child of a `Final` aggregate.
+///
+/// ```text
+/// -- Canonical shape (default pipeline):
+/// -- built-in rules recognize and optimize this
+/// Limit
+///   Aggregate(Final)
+///     Aggregate(Partial)
+///
+/// -- Non-canonical shape (repartitioning inserted first):
+/// -- built-in rules skip the optimization
+/// Limit
+///   Aggregate(Final)
+///     Repartition
+///       Aggregate(Partial)
+/// ```
+///
+/// ## Guidance for Custom Pipelines
+///
+/// We recommend keeping the default rule order and using the supported
+/// configuration options to disable individual optimizations. For example, `SET
+/// datafusion.optimizer.enable_distinct_aggregation_soft_limit = false`
+/// disables the distinct aggregation soft-limit optimization. These variations
+/// are tested and preserve both correctness and optimization coverage.
+///
+/// If you do build a custom pipeline:
+///
+/// - **Reordering must still yield a valid plan.** Downstream projects are
+///   encouraged to add tests that run their pipeline end to end and check
+///   results, as DataFusion's own tests only cover the default order.
+/// - **Test for reduced optimization coverage,** as described above, and verify
+///   the plans you care about with `EXPLAIN`.
+/// - **Prefer adding a rule over extending a built-in one.** We discourage
+///   extending a built-in rule to match plan shapes it will not encounter in
+///   the default pipeline, because such extensions are difficult to test and
+///   maintain. Instead, add a custom rule that rewrites your plan into the
+///   canonical shape recognized by the built-in rules. If extending a built-in
+///   rule still seems necessary, please open a DataFusion issue to discuss it.
 #[derive(Clone, Debug)]
 pub struct PhysicalOptimizer {
     /// All rules to apply
@@ -291,8 +301,8 @@ impl PhysicalOptimizer {
 
     /// Create a new optimizer with the given rules
     ///
-    /// See the [module documentation](self) for the contract governing non-default
-    /// optimizer pipelines.
+    /// See the [`PhysicalOptimizer`](Self) documentation for the contract
+    /// governing non-default optimizer pipelines.
     pub fn with_rules(rules: Vec<Arc<dyn PhysicalOptimizerRule + Send + Sync>>) -> Self {
         Self { rules }
     }
 
@@ -120,10 +120,14 @@ where
 /// `PhysicalOptimizerRule` transforms one [`ExecutionPlan`] into another which
 /// computes the same results, but in a potentially more efficient way.
 ///
-/// Use [`SessionState::add_physical_optimizer_rule`] to register additional
+/// The returned plan must be valid and produce the same results as the input
+/// plan. See [`PhysicalOptimizer`] for more details.
+///
+/// Use [`SessionStateBuilder::with_physical_optimizer_rule`] to register additional
 /// `PhysicalOptimizerRule`s.
 ///
-/// [`SessionState::add_physical_optimizer_rule`]: https://docs.rs/datafusion/latest/datafusion/execution/session_state/struct.SessionState.html#method.add_physical_optimizer_rule
+/// [`PhysicalOptimizer`]: https://docs.rs/datafusion-physical-optimizer/latest/datafusion_physical_optimizer/optimizer/struct.PhysicalOptimizer.html
+/// [`SessionStateBuilder::with_physical_optimizer_rule`]: https://docs.rs/datafusion/latest/datafusion/execution/session_state/struct.SessionStateBuilder.html#method.with_physical_optimizer_rule
 pub trait PhysicalOptimizerRule: Debug + std::any::Any {
     /// Rewrite `plan` to an optimized form.
     ///