perf(physical-plan): fold PlanProperties fast-path into with_new_children_if_necessary (PR 1 of #22555) (#23332)

## Which issue does this PR close?

Part of #22555. This is **PR 1 of 2** — see the issue body for the full
plan. PR 2 will audit direct `with_new_children` callers and add a
clippy lint.

## Rationale for this change

Today the "skip work when children are unchanged" intent is split across
two layers:

- **caller-side** —
[`with_new_children_if_necessary`](https://github.com/apache/datafusion/blob/main/datafusion/physical-plan/src/execution_plan.rs)
short-circuits via `Arc::ptr_eq` on child pointers.
- **callee-side** — the `check_if_same_properties!` macro from #19792,
invoked inside each impl's `with_new_children`, short-circuits when
children's `PlanProperties` Arcs match (allowing the plan to reuse its
cached `PlanProperties` Arc instead of recomputing).

Having two independent layers means two places to maintain and two
places for future changes to drift apart. This PR consolidates the
fast-path into the single free-function helper so callers get both
short-circuits uniformly.

## What changes are included in this PR?

`with_new_children_if_necessary` now applies **three layers**, cheapest
first:

1. **Same child pointers** — every `children[i]` is `Arc::ptr_eq` to the
corresponding existing child → return the original plan unchanged, no
allocation.
2. **Same child properties** — children's `PlanProperties` Arcs match →
call the new [`ExecutionPlan::with_new_children_and_same_properties`](#)
trait method to reuse the plan's `PlanProperties` cache without
recomputing.
3. **Full recompute** — otherwise, delegate to
`ExecutionPlan::with_new_children`.

To make layer 2 dispatchable via `&dyn ExecutionPlan`,
`with_new_children_and_same_properties` is promoted from an ad-hoc
inherent method on each impl to a **trait method** with a safe default
that falls back to `with_new_children`. All 22 existing impls migrate
their inherent method to a trait override (mechanical change — signature
`&self → self: Arc<Self>`, return `Self → Result<Arc<dyn
ExecutionPlan>>`, body wrapped in `Ok(Arc::new(...))`).

The `check_if_same_properties!` macro and its call sites inside impls
are **kept**, so direct callers of `with_new_children` (which PR 2 will
audit + migrate) do not regress on this PR.

## Are these changes tested?

Yes — added `test_with_new_children_if_necessary_layers` in
`execution_plan.rs` that constructs test-local `WithChildrenTestLeaf` +
`WithChildrenTestParent` plans (the parent tracks recompute vs fast-path
calls via `AtomicUsize`) and asserts, for each of the three layers:

- **Layer 1**: `Arc::ptr_eq(result, parent)` returns true,
`recompute_calls == 0`, `fast_path_calls == 0`
- **Layer 2**: `Arc::ptr_eq(result.properties(), orig_props)` returns
true, `recompute_calls == 0`, `fast_path_calls == 1`
- **Layer 3**: `Arc::ptr_eq(result.properties(), orig_props)` returns
false, `recompute_calls == 1`, `fast_path_calls` unchanged

All 1523 `datafusion-physical-plan` unit tests pass. Full workspace
`cargo check` + `cargo clippy --all-targets --all-features -- -D
warnings` pass.

## Are there any user-facing changes?

Yes — `ExecutionPlan` gains a new default-implemented trait method
`with_new_children_and_same_properties`. Downstream impls that used to
override the ad-hoc inherent method with the same name will need to
re-implement as a trait override (mechanical signature change). Marking
as `api change`.

## Follow-up (PR 2, not in this PR)

- Audit the ~47 remaining direct callers of
`plan.with_new_children(children)` across the codebase and route them
through `with_new_children_if_necessary`.
- Add a `disallowed_methods` clippy lint (or custom lint) that forbids
direct `ExecutionPlan::with_new_children` outside of a small allow-list.
- Once all callers migrate, remove the `check_if_same_properties!` macro
and its impl-side invocations, making the helper the single source of
truth as described in the issue.

Author: zhuqi-lucas

datafusion/physical-plan/src/aggregates/mod.rs

@@ -1610,17 +1610,6 @@ impl AggregateExec {
             _ => Precision::Absent,
         }
     }
-
-    fn with_new_children_and_same_properties(
-        &self,
-        mut children: Vec<Arc<dyn ExecutionPlan>>,
-    ) -> Self {
-        Self {
-            input: children.swap_remove(0),
-            metrics: ExecutionPlanMetricsSet::new(),
-            ..Self::clone(self)
-        }
-    }
 }
 
 impl DisplayAs for AggregateExec {
@@ -1838,6 +1827,17 @@ impl ExecutionPlan for AggregateExec {
         Ok(Arc::new(me))
     }
 
+    fn with_new_children_and_same_properties(
+        self: Arc<Self>,
+        mut children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        Ok(Arc::new(Self {
+            input: children.swap_remove(0),
+            metrics: ExecutionPlanMetricsSet::new(),
+            ..Self::clone(&*self)
+        }))
+    }
+
     fn execute(
         &self,
         partition: usize,

datafusion/physical-plan/src/async_func.rs

@@ -113,17 +113,6 @@ impl AsyncFuncExec {
     pub fn input(&self) -> &Arc<dyn ExecutionPlan> {
         &self.input
     }
-
-    fn with_new_children_and_same_properties(
-        &self,
-        mut children: Vec<Arc<dyn ExecutionPlan>>,
-    ) -> Self {
-        Self {
-            input: children.swap_remove(0),
-            metrics: ExecutionPlanMetricsSet::new(),
-            ..Self::clone(self)
-        }
-    }
 }
 
 impl DisplayAs for AsyncFuncExec {
@@ -180,6 +169,17 @@ impl ExecutionPlan for AsyncFuncExec {
         )?))
     }
 
+    fn with_new_children_and_same_properties(
+        self: Arc<Self>,
+        mut children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        Ok(Arc::new(Self {
+            input: children.swap_remove(0),
+            metrics: ExecutionPlanMetricsSet::new(),
+            ..Self::clone(&*self)
+        }))
+    }
+
     fn execute(
         &self,
         partition: usize,

datafusion/physical-plan/src/buffer.rs

@@ -123,17 +123,6 @@ impl BufferExec {
     pub fn capacity(&self) -> usize {
         self.capacity
     }
-
-    fn with_new_children_and_same_properties(
-        &self,
-        mut children: Vec<Arc<dyn ExecutionPlan>>,
-    ) -> Self {
-        Self {
-            input: children.swap_remove(0),
-            metrics: ExecutionPlanMetricsSet::new(),
-            ..Self::clone(self)
-        }
-    }
 }
 
 impl DisplayAs for BufferExec {
@@ -181,6 +170,17 @@ impl ExecutionPlan for BufferExec {
         Ok(Arc::new(Self::new(children.swap_remove(0), self.capacity)))
     }
 
+    fn with_new_children_and_same_properties(
+        self: Arc<Self>,
+        mut children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        Ok(Arc::new(Self {
+            input: children.swap_remove(0),
+            metrics: ExecutionPlanMetricsSet::new(),
+            ..Self::clone(&*self)
+        }))
+    }
+
     fn execute(
         &self,
         partition: usize,

datafusion/physical-plan/src/coalesce_batches.rs

@@ -117,17 +117,6 @@ impl CoalesceBatchesExec {
             input.boundedness(),
         )
     }
-
-    fn with_new_children_and_same_properties(
-        &self,
-        mut children: Vec<Arc<dyn ExecutionPlan>>,
-    ) -> Self {
-        Self {
-            input: children.swap_remove(0),
-            metrics: ExecutionPlanMetricsSet::new(),
-            ..Self::clone(self)
-        }
-    }
 }
 
 #[expect(deprecated)]
@@ -195,6 +184,17 @@ impl ExecutionPlan for CoalesceBatchesExec {
         ))
     }
 
+    fn with_new_children_and_same_properties(
+        self: Arc<Self>,
+        mut children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        Ok(Arc::new(Self {
+            input: children.swap_remove(0),
+            metrics: ExecutionPlanMetricsSet::new(),
+            ..Self::clone(&*self)
+        }))
+    }
+
     fn execute(
         &self,
         partition: usize,

datafusion/physical-plan/src/coalesce_partitions.rs

@@ -100,17 +100,6 @@ impl CoalescePartitionsExec {
         .with_evaluation_type(drive)
         .with_scheduling_type(scheduling)
     }
-
-    fn with_new_children_and_same_properties(
-        &self,
-        mut children: Vec<Arc<dyn ExecutionPlan>>,
-    ) -> Self {
-        Self {
-            input: children.swap_remove(0),
-            metrics: ExecutionPlanMetricsSet::new(),
-            ..Self::clone(self)
-        }
-    }
 }
 
 impl DisplayAs for CoalescePartitionsExec {
@@ -164,6 +153,17 @@ impl ExecutionPlan for CoalescePartitionsExec {
         Ok(Arc::new(plan))
     }
 
+    fn with_new_children_and_same_properties(
+        self: Arc<Self>,
+        mut children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        Ok(Arc::new(Self {
+            input: children.swap_remove(0),
+            metrics: ExecutionPlanMetricsSet::new(),
+            ..Self::clone(&*self)
+        }))
+    }
+
     fn execute(
         &self,
         partition: usize,

datafusion/physical-plan/src/coop.rs

@@ -234,16 +234,6 @@ impl CooperativeExec {
     pub fn input(&self) -> &Arc<dyn ExecutionPlan> {
         &self.input
     }
-
-    fn with_new_children_and_same_properties(
-        &self,
-        mut children: Vec<Arc<dyn ExecutionPlan>>,
-    ) -> Self {
-        Self {
-            input: children.swap_remove(0),
-            ..Self::clone(self)
-        }
-    }
 }
 
 impl DisplayAs for CooperativeExec {
@@ -290,6 +280,16 @@ impl ExecutionPlan for CooperativeExec {
         Ok(Arc::new(CooperativeExec::new(children.swap_remove(0))))
     }
 
+    fn with_new_children_and_same_properties(
+        self: Arc<Self>,
+        mut children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        Ok(Arc::new(Self {
+            input: children.swap_remove(0),
+            ..Self::clone(&*self)
+        }))
+    }
+
     fn execute(
         &self,
         partition: usize,