fix: validate ArrivalOrder params and clarify ordering docs

- Add __post_init__ to ArrivalOrder raising ValueError if
  concurrent_streams < 1 or max_buffered_batches < 1. Previously
  max_buffered_batches=0 would silently create an unbounded queue.
- Split the ArrivalOrder row in the ordering semantics table to
  clarify that interleaving only occurs with concurrent_streams > 1;
  concurrent_streams=1 reads files sequentially.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: sumedhsakdeo

mkdocs/docs/api.md

@@ -378,7 +378,8 @@ for buf in tbl.scan().to_arrow_batch_reader(order=ArrivalOrder(concurrent_stream
 | Configuration | File ordering | Within-file ordering |
 |---|---|---|
 | `TaskOrder()` (default) | Batches grouped by file, in task submission order | Row order |
-| `ArrivalOrder()` | Interleaved across files (no grouping guarantee) | Row order within each file |
+| `ArrivalOrder(concurrent_streams=1)` | Sequential, one file at a time | Row order |
+| `ArrivalOrder(concurrent_streams>1)` | Interleaved across files (no grouping guarantee) | Row order within each file |
 
 The `limit` parameter is enforced correctly regardless of configuration.
 

pyiceberg/table/__init__.py

@@ -193,6 +193,13 @@ class ArrivalOrder(ScanOrder):
     batch_size: int | None = None
     max_buffered_batches: int = 16
 
+    def __post_init__(self) -> None:
+        """Validate ArrivalOrder parameters."""
+        if self.concurrent_streams < 1:
+            raise ValueError(f"concurrent_streams must be >= 1, got {self.concurrent_streams}")
+        if self.max_buffered_batches < 1:
+            raise ValueError(f"max_buffered_batches must be >= 1, got {self.max_buffered_batches}")
+
 
 @dataclass()
 class UpsertResult: