docs: Chunk typed-columns surface in reference + changelog

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: dfa1

CHANGELOG.md

@@ -17,6 +17,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- `Chunk.columns()` returns an order-preserving `SequencedMap<ColumnName, Chunk.Column>` — one map instead of two parallel string-keyed maps, with each column's `Array` and `DType` traveling together in the `Column` carrier. `column(String)` stays as boundary sugar (plus a `column(ColumnName)` overload); iteration order is the schema/projection order, now guaranteed even for 1–2 column chunks. Typed names originate in `ScanIterator` from the file's already-certified schema. ([f8ad15d1](https://github.com/dfa1/vortex-java/commit/f8ad15d1))
+
 - `Compute.filteredSum` over a dictionary-encoded filter column is ~20× faster (best runs ~30×): the predicate is resolved against the dictionary's value pool once and the raw `u8` codes are scanned directly from their backing segments, instead of decoding every row through the per-element accessor — a fused `SUM(measure) WHERE category = …` over 100M rows drops from ~760 ms to ~38 ms. ([85e251cc](https://github.com/dfa1/vortex-java/commit/85e251cc))
 - `Compute.filteredAggregate` takes the same dictionary code-scan lane (`COUNT(*)` included) — ~22× faster on the same workload (~980 ms → ~46 ms over 100M rows), which the Calcite `WHERE`-filtered aggregate push-down inherits on its boundary chunks. ([145791c7](https://github.com/dfa1/vortex-java/commit/145791c7), [6e6d7dd0](https://github.com/dfa1/vortex-java/commit/6e6d7dd0))
 - A multi-column `AND` filter no longer forfeits the dictionary lane: the dict-encoded leaf drives the code scan and the remaining predicates are evaluated only on its matches — `SUM(…) WHERE category = 7 AND price > 500` over 100M rows drops from ~2.3 s to ~200 ms (~11×). ([12e13501](https://github.com/dfa1/vortex-java/commit/12e13501))

docs/reference.md

@@ -183,13 +183,20 @@ columnar buffers; closing the chunk releases the arena. After `close()`, touchin
 any `Array` previously returned by `column(...)` or `columns()` raises FFM's scope
 check (`IllegalStateException`).
 
-| Method                                  | Notes                                                    |
-|-----------------------------------------|----------------------------------------------------------|
-| `rowCount()`                            | Rows in this chunk                                       |
-| `columns()`                             | All columns in this chunk                                |
-| `<T extends Array> column(String name)` | Typed column lookup; throws `VortexException` if unknown |
-| `isClosed()`                            | Whether `close()` has run                                |
-| `close()`                               | Releases the chunk's arena. Idempotent.                  |
+Columns are stored as one order-preserving map keyed by the validated [`ColumnName`]; each
+entry is a `Chunk.Column(Array array, DType dtype)` carrier, so a column's data and type can
+never desync. `column(String)` is boundary sugar: the name is wrapped in a `ColumnName` (a
+policy-invalid name fails fast — it could never match a certified column).
+
+| Method                                      | Notes                                                    |
+|---------------------------------------------|----------------------------------------------------------|
+| `rowCount()`                                | Rows in this chunk                                       |
+| `columns()`                                 | `SequencedMap<ColumnName, Chunk.Column>`, schema order, unmodifiable |
+| `<T extends Array> column(String name)`     | Typed column lookup; throws `VortexException` if absent  |
+| `<T extends Array> column(ColumnName name)` | Same, for callers that validated early                   |
+| `as(String name, Class<T> domainType)`      | Extension column → typed `List<T>`                       |
+| `isClosed()`                                | Whether `close()` has run                                |
+| `close()`                                   | Releases the chunk's arena. Idempotent.                  |
 
 ---