refactor(reader): typed columns from ScanIterator down

Chunk's two parallel string-keyed maps (columns + columnDtypes)
collapse into one SequencedMap<ColumnName, Chunk.Column> — the
Array and its DType travel together in the Column carrier, so
desync is unrepresentable, and schema order is now part of the
contract (previously Map.of gave no order guarantee for 1-2
column chunks).

ColumnName originates in ScanIterator.initialize(), parsed once
from the file's DType.Struct (the parse edge has already policy-
certified every name); ChunkSpec, layout lookups, zone-stat caches
and the column-map builders are typed end to end. Public rims keep
String sugar converted exactly once: chunk.column(String),
RowFilter references, columnZoneStats. A policy-invalid query name
fails fast with the policy message — it could never match a
certified column; valid-but-absent names keep the exact previous
behavior and messages.

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

Author: dfa1

cli/src/main/java/io/github/dfa1/vortex/cli/tui/VortexInspectorTui.java

@@ -3,6 +3,7 @@
 import io.github.dfa1.vortex.reader.layout.Layout;
 import io.github.dfa1.vortex.reader.SegmentSpec;
 import io.github.dfa1.vortex.core.model.DType;
+import io.github.dfa1.vortex.core.model.ColumnName;
 import io.github.dfa1.vortex.reader.array.Array;
 import io.github.dfa1.vortex.cli.tui.term.Ansi;
 import io.github.dfa1.vortex.cli.tui.term.Key;
@@ -766,11 +767,12 @@ private void runDataLoad(String columnName) {
                         return;
                     }
                     try (Chunk chunk = it.next()) {
-                        Array array = chunk.columns().get(columnName);
-                        if (array == null) {
+                        Chunk.Column column = chunk.columns().get(ColumnName.of(columnName));
+                        if (column == null) {
                             dataCache.put(columnName, new DataState.Loaded(List.of()));
                             return;
                         }
+                        Array array = column.array();
                         int n = (int) Math.min(array.length(), DATA_PREVIEW_ROWS);
                         List<String> out = new ArrayList<>(n);
                         for (int i = 0; i < n; i++) {

integration/src/test/java/io/github/dfa1/vortex/integration/AllowUnknownIntegrationTest.java

@@ -5,7 +5,7 @@
 import dev.vortex.arrow.ArrowAllocation;
 import dev.vortex.jni.NativeLoader;
 import io.github.dfa1.vortex.core.error.VortexException;
-import io.github.dfa1.vortex.reader.array.Array;
+import io.github.dfa1.vortex.reader.Chunk;
 import io.github.dfa1.vortex.reader.array.UnknownArray;
 import io.github.dfa1.vortex.reader.ReadRegistry;
 import io.github.dfa1.vortex.reader.VortexReader;
@@ -87,8 +87,8 @@ void allowUnknown_emptyRegistry_allColumnsReturnUnknownArray(@TempDir Path tmp)
             iter.forEachRemaining(c -> {
                 totalRows.addAndGet(c.rowCount());
                 chunkCount.incrementAndGet();
-                for (Array col : c.columns().values()) {
-                    if (!(col instanceof UnknownArray)) {
+                for (Chunk.Column col : c.columns().values()) {
+                    if (!(col.array() instanceof UnknownArray)) {
                         allUnknown.set(false);
                     }
                 }
@@ -130,8 +130,8 @@ void allowUnknown_loadAllRegistry_noUnknownArrayForSupportedEncodings(@TempDir P
              var iter = vf.scan(io.github.dfa1.vortex.reader.ScanOptions.all())) {
             iter.forEachRemaining(c -> {
                 chunkCount.incrementAndGet();
-                for (Array col : c.columns().values()) {
-                    if (col instanceof UnknownArray) {
+                for (Chunk.Column col : c.columns().values()) {
+                    if (col.array() instanceof UnknownArray) {
                         anyUnknown.set(true);
                     }
                 }

integration/src/test/java/io/github/dfa1/vortex/integration/JavaRoundTripIntegrationTest.java

@@ -65,7 +65,7 @@ private static int[] readIntColumn(Path file, String column) throws IOException
              var iter = vf.scan(ScanOptions.columns(column))) {
             var ints = new ArrayList<Integer>();
             iter.forEachRemaining(c -> {
-                IntArray arr = (IntArray) c.columns().get(column);
+                IntArray arr = c.column(column);
                 for (long i = 0; i < arr.length(); i++) {
                     ints.add(arr.getInt(i));
                 }

integration/src/test/java/io/github/dfa1/vortex/integration/RustJavaReaderComparisonIntegrationTest.java

@@ -21,6 +21,7 @@
 import io.github.dfa1.vortex.reader.ReadRegistry;
 import io.github.dfa1.vortex.inspect.VortexInspector;
 import io.github.dfa1.vortex.reader.VortexReader;
+import io.github.dfa1.vortex.core.model.ColumnName;
 import io.github.dfa1.vortex.reader.Chunk;
 import org.apache.arrow.memory.BufferAllocator;
 import org.apache.arrow.vector.BigIntVector;
@@ -229,18 +230,19 @@ private static Stats javaStats(Path file) throws Exception {
             while (iter.hasNext()) {
                 try (Chunk chunk = iter.next()) {
                     rowCount += chunk.rowCount();
-                    for (Map.Entry<String, Array> e : chunk.columns().entrySet()) {
-                        if (extensionCols.contains(e.getKey())) {
+                    for (Map.Entry<ColumnName, Chunk.Column> e : chunk.columns().entrySet()) {
+                        String name = e.getKey().value();
+                        if (extensionCols.contains(name)) {
                             continue;
                         }
-                        Array arr = e.getValue();
+                        Array arr = e.getValue().array();
                         Double numSum = numericSum(arr);
                         if (numSum != null) {
-                            numSums.merge(e.getKey(), numSum, Double::sum);
+                            numSums.merge(name, numSum, Double::sum);
                         }
                         Long strLen = stringByteLength(arr);
                         if (strLen != null && strLen > 0) {
-                            strLenSums.merge(e.getKey(), strLen, Long::sum);
+                            strLenSums.merge(name, strLen, Long::sum);
                         }
                     }
                 }

integration/src/test/java/io/github/dfa1/vortex/integration/RustWritesJavaReadsIntegrationTest.java

@@ -125,7 +125,7 @@ private static List<JavaChunk> scanAll(VortexReader vf,
             iter.forEachRemaining(c -> {
                 var mat = new LinkedHashMap<String, Object>(c.columns().size());
                 for (var e : c.columns().entrySet()) {
-                    mat.put(e.getKey(), snapshotArray(e.getValue()));
+                    mat.put(e.getKey().value(), snapshotArray(e.getValue().array()));
                 }
                 results.add(new JavaChunk(c.rowCount(), mat));
             });
@@ -212,7 +212,7 @@ private static long[] readJavaLongColumn(Path file, String column) throws IOExce
              var iter = vf.scan(io.github.dfa1.vortex.reader.ScanOptions.columns(column))) {
             var longs = new ArrayList<Long>();
             iter.forEachRemaining(c -> {
-                LongArray arr = (LongArray) c.columns().get(column);
+                LongArray arr = c.column(column);
                 for (long i = 0; i < arr.length(); i++) {
                     longs.add(arr.getLong(i));
                 }

performance/src/main/java/io/github/dfa1/vortex/performance/JniWritesJavaReadsBigFileBenchmark.java

@@ -179,7 +179,7 @@ private long scanJava() throws IOException {
              var iter = vf.scan(io.github.dfa1.vortex.reader.ScanOptions.columns("c0"))) {
             while (iter.hasNext()) {
                 try (Chunk c = iter.next()) {
-                    Array arr = c.columns().get("c0");
+                    Array arr = c.column("c0");
                     MemorySegment buf = arr.materialize(Arena.ofAuto());
                     long count = buf.byteSize() / Long.BYTES;
                     for (long i = 0; i < count; i++) {

reader/src/main/java/io/github/dfa1/vortex/reader/Chunk.java

@@ -1,5 +1,6 @@
 package io.github.dfa1.vortex.reader;
 
+import io.github.dfa1.vortex.core.model.ColumnName;
 import io.github.dfa1.vortex.core.model.DType;
 import io.github.dfa1.vortex.core.error.VortexException;
 import io.github.dfa1.vortex.reader.array.Array;
@@ -14,8 +15,8 @@
 import java.time.LocalDate;
 import java.time.LocalTime;
 import java.util.List;
-import java.util.Map;
 import java.util.Objects;
+import java.util.SequencedMap;
 import java.util.UUID;
 import java.util.function.Consumer;
 
@@ -26,6 +27,11 @@
 /// references into that arena (or into the underlying mmap region), valid only
 /// while this `Chunk` is open.
 ///
+/// Columns are keyed by [ColumnName] — the validated name domain the file parser
+/// certifies at the read boundary, so every key here is policy-valid and unique.
+/// [#column(String)] keeps a string-sugar overload for callers that hold a raw
+/// name; it wraps the string in a [ColumnName] before looking it up.
+///
 /// **Lifecycle.** `Chunk` is [AutoCloseable]. Always wrap consumption in
 /// try-with-resources:
 ///
@@ -43,50 +49,80 @@
 public final class Chunk implements AutoCloseable {
 
     private final long rowCount;
-    private final Map<String, Array> columns;
-    private final Map<String, DType> columnDtypes;
+    private final SequencedMap<ColumnName, Column> columns;
     private final Arena arena;
     private final Consumer<Chunk> onClose;
     private boolean closed;
 
-    Chunk(long rowCount, Map<String, Array> columns, Map<String, DType> columnDtypes,
+    Chunk(long rowCount, SequencedMap<ColumnName, Column> columns,
             Arena arena, Consumer<Chunk> onClose) {
         this.rowCount = rowCount;
         this.columns = Objects.requireNonNull(columns);
-        this.columnDtypes = Objects.requireNonNull(columnDtypes);
         this.arena = Objects.requireNonNull(arena);
         this.onClose = Objects.requireNonNull(onClose);
     }
 
+    /// One decoded column: its zero-copy [Array] view and the [DType] it was declared with in the
+    /// file's schema. The dtype travels with the array so extension decoding (see [#as(String, Class)])
+    /// and dtype-aware tooling need no second lookup.
+    ///
+    /// @param array the decoded column values, valid only while the owning [Chunk] is open
+    /// @param dtype the column's declared type from the file schema
+    public record Column(Array array, DType dtype) {
+
+        /// Binds a decoded array to its declared type.
+        ///
+        /// @param array the decoded column values
+        /// @param dtype the column's declared type
+        public Column {
+            Objects.requireNonNull(array, "array");
+            Objects.requireNonNull(dtype, "dtype");
+        }
+    }
+
     /// Number of logical rows in this chunk (after any limit truncation).
     ///
     /// @return row count of this chunk
     public long rowCount() {
         return rowCount;
     }
 
-    /// Returns the decoded columns by name. The map is unmodifiable; values are
-    /// valid only while this `Chunk` is open.
+    /// Returns the decoded columns in schema (projection) order. The map is unmodifiable and
+    /// preserves encounter order; each [Column] value is valid only while this `Chunk` is open.
     ///
-    /// @return projected columns keyed by name
-    public Map<String, Array> columns() {
+    /// @return projected columns keyed by [ColumnName], in schema order
+    public SequencedMap<ColumnName, Column> columns() {
         return columns;
     }
 
-    /// Looks up a column by name with a checked cast to the caller's expected
-    /// [Array] subtype.
+    /// Looks up a column by its raw string name with a checked cast to the caller's expected
+    /// [Array] subtype. The name is validated through [ColumnName#of(String)] first, so a
+    /// policy-invalid query name fails fast with the policy's [IllegalArgumentException] — it
+    /// could never match a certified column anyway.
     ///
     /// @param name column name as declared in the file's [io.github.dfa1.vortex.core.model.DType] schema
     /// @param <T>  expected concrete [Array] subtype
     /// @return the column array
+    /// @throws IllegalArgumentException if `name` violates the column-name policy
+    /// @throws VortexException          if no column with the given name is present in this chunk
+    public <T extends Array> T column(String name) {
+        return column(ColumnName.of(name));
+    }
+
+    /// Looks up a column by its validated [ColumnName] with a checked cast to the caller's
+    /// expected [Array] subtype.
+    ///
+    /// @param name validated column name as declared in the file's schema
+    /// @param <T>  expected concrete [Array] subtype
+    /// @return the column array
     /// @throws VortexException if no column with the given name is present in this chunk
     @SuppressWarnings("unchecked")
-    public <T extends Array> T column(String name) {
-        Array arr = columns.get(name);
-        if (arr == null) {
+    public <T extends Array> T column(ColumnName name) {
+        Column col = columns.get(name);
+        if (col == null) {
             throw new VortexException("unknown column: " + name);
         }
-        return (T) arr;
+        return (T) col.array();
     }
 
     /// Decodes an extension column into a typed `List<T>` of domain values.
@@ -110,16 +146,16 @@ public <T extends Array> T column(String name) {
     ///         or the requested `domainType` doesn't match the column's extension id
     @SuppressWarnings("unchecked")
     public <T> List<T> as(String name, Class<T> domainType) {
-        DType colDtype = columnDtypes.get(name);
-        if (colDtype == null) {
+        Column col = columns.get(ColumnName.of(name));
+        if (col == null) {
             throw new VortexException("unknown column: " + name);
         }
-        if (!(colDtype instanceof DType.Extension ext)) {
+        if (!(col.dtype() instanceof DType.Extension ext)) {
             throw new VortexException("not an extension column: " + name);
         }
         ExtensionId id = ExtensionId.parse(ext.extensionId())
                 .orElseThrow(() -> new VortexException("not a spec extension id: " + ext.extensionId()));
-        Array storage = column(name);
+        Array storage = col.array();
         Object result = switch (id) {
             case VORTEX_DATE -> {
                 requireDomainType(name, domainType, LocalDate.class);