fix CI: register SamplePushdown in docs and explain.slt; broken doc link

- optimizer_rule_reference.md: add SamplePushdown entry between
  PushdownSort and EnsureCooperative so the
  physical_rules_match_documented_order test matches the registered
  pipeline.
- explain.slt: add `physical_plan after SamplePushdown SAME TEXT AS
  ABOVE` line under each PushdownSort line so the verbose-explain
  snapshots stay in sync with the new rule.
- physical-plan/sample.rs: drop the intra-doc link to `Sample` from
  the SampleExec docstring; that node lives in datafusion-expr and
  the link can't resolve from physical-plan.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: adriangb

datafusion/core/src/optimizer_rule_reference.md

@@ -88,6 +88,7 @@ in multiple phases.
 | 17    | `TopKRepartition`              | -                       | Pushes TopK below hash repartition when the partition key is a prefix of the sort key.                       |
 | 18    | `ProjectionPushdown`           | late pass               | Runs projection pushdown again after limit and TopK rewrites expose new pruning opportunities.               |
 | 19    | `PushdownSort`                 | -                       | Pushes sort requirements into data sources that can already return sorted output.                            |
-| 20    | `EnsureCooperative`            | -                       | Wraps non-cooperative plan parts so long-running tasks yield fairly.                                         |
-| 21    | `FilterPushdown(Post)`         | post-optimization phase | Pushes dynamic filters at the end of optimization, after plan references stop moving.                        |
-| 22    | `SanityCheckPlan`              | -                       | Validates that the final physical plan meets ordering, distribution, and infinite-input safety requirements. |
+| 20    | `SamplePushdown`               | -                       | Pushes `TABLESAMPLE` into the source; errors at planning time if the sample can't be absorbed.               |
+| 21    | `EnsureCooperative`            | -                       | Wraps non-cooperative plan parts so long-running tasks yield fairly.                                         |
+| 22    | `FilterPushdown(Post)`         | post-optimization phase | Pushes dynamic filters at the end of optimization, after plan references stop moving.                        |
+| 23    | `SanityCheckPlan`              | -                       | Validates that the final physical plan meets ordering, distribution, and infinite-input safety requirements. |

datafusion/physical-plan/src/sample.rs

@@ -62,7 +62,7 @@ pub struct SampleExec {
 
 impl SampleExec {
     /// Construct a [`SampleExec`] over `input`. Caller is expected to
-    /// have validated `fraction` upstream (the logical [`Sample`] node
+    /// have validated `fraction` upstream (the logical `Sample` node
     /// does this in `try_new`).
     pub fn new(
         input: Arc<dyn ExecutionPlan>,

datafusion/sqllogictest/test_files/explain.slt

@@ -249,6 +249,7 @@ physical_plan after LimitPushdown SAME TEXT AS ABOVE
 physical_plan after TopKRepartition SAME TEXT AS ABOVE
 physical_plan after ProjectionPushdown SAME TEXT AS ABOVE
 physical_plan after PushdownSort SAME TEXT AS ABOVE
+physical_plan after SamplePushdown SAME TEXT AS ABOVE
 physical_plan after EnsureCooperative SAME TEXT AS ABOVE
 physical_plan after FilterPushdown(Post) SAME TEXT AS ABOVE
 physical_plan after SanityCheckPlan SAME TEXT AS ABOVE
@@ -332,6 +333,7 @@ physical_plan after LimitPushdown DataSourceExec: file_groups={1 group: [[WORKSP
 physical_plan after TopKRepartition SAME TEXT AS ABOVE
 physical_plan after ProjectionPushdown SAME TEXT AS ABOVE
 physical_plan after PushdownSort SAME TEXT AS ABOVE
+physical_plan after SamplePushdown SAME TEXT AS ABOVE
 physical_plan after EnsureCooperative SAME TEXT AS ABOVE
 physical_plan after FilterPushdown(Post) SAME TEXT AS ABOVE
 physical_plan after SanityCheckPlan SAME TEXT AS ABOVE
@@ -379,6 +381,7 @@ physical_plan after LimitPushdown DataSourceExec: file_groups={1 group: [[WORKSP
 physical_plan after TopKRepartition SAME TEXT AS ABOVE
 physical_plan after ProjectionPushdown SAME TEXT AS ABOVE
 physical_plan after PushdownSort SAME TEXT AS ABOVE
+physical_plan after SamplePushdown SAME TEXT AS ABOVE
 physical_plan after EnsureCooperative SAME TEXT AS ABOVE
 physical_plan after FilterPushdown(Post) SAME TEXT AS ABOVE
 physical_plan after SanityCheckPlan SAME TEXT AS ABOVE
@@ -624,6 +627,7 @@ physical_plan after LimitPushdown SAME TEXT AS ABOVE
 physical_plan after TopKRepartition SAME TEXT AS ABOVE
 physical_plan after ProjectionPushdown SAME TEXT AS ABOVE
 physical_plan after PushdownSort SAME TEXT AS ABOVE
+physical_plan after SamplePushdown SAME TEXT AS ABOVE
 physical_plan after EnsureCooperative SAME TEXT AS ABOVE
 physical_plan after FilterPushdown(Post) SAME TEXT AS ABOVE
 physical_plan after SanityCheckPlan SAME TEXT AS ABOVE