fix: keep a native hash join's streamed order when Spark drops the sort above it

docs/source/user-guide/latest/compatibility/operators.md

@@ -92,6 +92,12 @@ rows by the grouping keys only, and Spark and Comet can leave rows with equal ke
 orders, so a group with more than one candidate value can return a different value than Spark.
 Both results are valid under Spark's semantics for these functions.
 
+## Hash Join
+
+When Spark reports a hash join's output as ordered by its streamed side, Comet keeps that order.
+When DataFusion does not keep it, for example when it comes from a cached table or the join is a
+`NOT IN`, Comet sorts the native join output to restore it.
+
 ## Window Functions
 
 Comet runs `WindowExec` natively and it is enabled by default (`spark.comet.exec.window.enabled`). A broad set of

docs/source/user-guide/latest/operators.md

@@ -98,14 +98,15 @@ omitted from the tables below and may be reconsidered based on demand:
 
 | Operator                      | Status | Notes                                                                                                                                                                         |
 | ----------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `BroadcastHashJoinExec`       | ✅     |                                                                                                                                                                               |
-| `ShuffledHashJoinExec`        | ✅     |                                                                                                                                                                               |
+| `BroadcastHashJoinExec`       | ✅     | Falls back to Spark when an outer or `NOT IN` join reports an output ordering whose type or expression Comet cannot sort natively.                                            |
+| `ShuffledHashJoinExec`        | ✅     | Falls back to Spark when an outer join reports an output ordering whose type or expression Comet cannot sort natively.                                                        |
 | `SortMergeJoinExec`           | ✅     | Supports `BINARY` join keys. Nested-type (struct, array, map) and collated-string join keys fall back to Spark.                                                               |
 | `BroadcastNestedLoopJoinExec` | ✅     | Falls back to Spark when the preserved side is broadcast (for example LEFT OUTER with BROADCAST on the left) ([#4429](https://github.com/apache/datafusion-comet/pull/4429)). |
 
 `ExistenceJoin` (produced when `EXISTS` / `IN` is combined with another predicate via `OR`) runs
 natively on `BroadcastHashJoinExec` and `ShuffledHashJoinExec`. Existence sort-merge joins, residual
-(non-equi) join conditions, computed (non-column) join keys, and `NOT IN` fall back to Spark.
+(non-equi) join conditions, and computed (non-column) join keys fall back to Spark. So does `NOT IN`
+combined with `OR`, which Spark plans as an existence `BroadcastNestedLoopJoinExec`.
 
 ## Exchanges