From 833aebd97395605228da219666a1329e7da5c76d Mon Sep 17 00:00:00 2001
From: Yongting You <2010youy01@gmail.com>
Date: Wed, 7 Oct 2026 16:55:52 +0800
Subject: [PATCH 1/3] doc: Document the physical optimizer contract

---
 .../physical-optimizer/src/optimizer.rs       | 58 ++++++++++++++++++-
 1 file changed, 57 insertions(+), 1 deletion(-)

diff --git a/datafusion/physical-optimizer/src/optimizer.rs b/datafusion/physical-optimizer/src/optimizer.rs
index aed25546cd09b..118f33228d963 100644
--- a/datafusion/physical-optimizer/src/optimizer.rs
+++ b/datafusion/physical-optimizer/src/optimizer.rs
@@ -15,7 +15,63 @@
 // specific language governing permissions and limitations
 // under the License.
 
-//! Physical optimizer traits
+//! Physical optimizer rule ordering and customization.
+//!
+//! # Physical Optimizer Contract
+//!
+//! This section explains the contract for extending the default list of
+//! optimizer rules.
+//!
+//! [`PhysicalOptimizer::new`] defines the default rule sequence:
+//!
+//! ```text
+//! // Default rules
+//! let rules = vec![
+//!     rule1,
+//!     rule2,
+//!     rule3,
+//!     rule4,
+//!     // ...
+//! ];
+//! ```
+//!
+//! 1. **Keep the default order.** Rules may rely on properties established by
+//!    earlier rules. Correctness is only guaranteed in the default order.
+//!
+//! 2. **Use configuration to disable optimizations.** Configuration options
+//!    provide supported variations of the default pipeline that preserve
+//!    correctness. For example,
+//!    `SET datafusion.optimizer.enable_distinct_aggregation_soft_limit = false`
+//!    disables the distinct aggregation soft-limit optimization. Removing rules
+//!    directly from the pipeline may produce invalid plans.
+//!
+//! 3. **Adding optimizer rules.**
+//!
+//!    1. Rules added within DataFusion or downstream must respect the
+//!       assumptions of the surrounding rules. Many of these are implicit or
+//!       documented only in individual rules. Changes to the default pipeline
+//!       may require updates to rules that rely on them.
+//!
+//!    2. DataFusion aims to make these assumptions easier to understand and
+//!       verify.
+//!
+//!    3. DataFusion does not aim to support arbitrary downstream pipelines
+//!       such as:
+//!
+//!       ```text
+//!       // Potential downstream usage:
+//!       //
+//!       // Reordered default rules mixed with extension rules
+//!       let rules = vec![
+//!           rule3,
+//!           extension_rule1,
+//!           rule1,
+//!           // ...
+//!       ];
+//!       ```
+//!
+//!       Do not change built-in rules or add unit tests within DataFusion
+//!       solely to support such downstream pipelines.
 
 use std::fmt::Debug;
 use std::sync::Arc;

From c3a2009d1354e907fffeaccfd56149da144cbdbc Mon Sep 17 00:00:00 2001
From: Yongting You <2010youy01@gmail.com>
Date: Thu, 8 Oct 2026 10:37:31 +0800
Subject: [PATCH 2/3] improve wording

---
 datafusion/physical-optimizer/src/optimizer.rs | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/datafusion/physical-optimizer/src/optimizer.rs b/datafusion/physical-optimizer/src/optimizer.rs
index 118f33228d963..48da769db09a6 100644
--- a/datafusion/physical-optimizer/src/optimizer.rs
+++ b/datafusion/physical-optimizer/src/optimizer.rs
@@ -55,8 +55,9 @@
 //!    2. DataFusion aims to make these assumptions easier to understand and
 //!       verify.
 //!
-//!    3. DataFusion does not aim to support arbitrary downstream pipelines
-//!       such as:
+//!    3. Extension rules should adapt to the built-in rules, not the other
+//!       way around. DataFusion does not aim to support arbitrary downstream
+//!       pipelines such as:
 //!
 //!       ```text
 //!       // Potential downstream usage:
@@ -70,7 +71,7 @@
 //!       ];
 //!       ```
 //!
-//!       Do not change built-in rules or add unit tests within DataFusion
+//!       Do not extend built-in rules or add unit tests within DataFusion
 //!       solely to support such downstream pipelines.
 
 use std::fmt::Debug;

From 10924ce14dea076a68e94f75a292380674ff8b3d Mon Sep 17 00:00:00 2001
From: Yongting You <2010youy01@gmail.com>
Date: Thu, 8 Oct 2026 10:39:45 +0800
Subject: [PATCH 3/3] improve wording

---
 datafusion/physical-optimizer/src/optimizer.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/datafusion/physical-optimizer/src/optimizer.rs b/datafusion/physical-optimizer/src/optimizer.rs
index 48da769db09a6..0c798742808c3 100644
--- a/datafusion/physical-optimizer/src/optimizer.rs
+++ b/datafusion/physical-optimizer/src/optimizer.rs
@@ -15,7 +15,7 @@
 // specific language governing permissions and limitations
 // under the License.
 
-//! Physical optimizer rule ordering and customization.
+//! Physical optimizer traits
 //!
 //! # Physical Optimizer Contract
 //!