refactor(reader): ScanOptions projections carry ColumnName

ScanOptions.columns becomes List<ColumnName>: the ergonomic
columns(String...) / withColumns(String...) factories still take
strings at the API boundary but validate them into ColumnName on
construction, so a blank or control-character projection fails fast
instead of silently matching nothing. ScanIterator's projection
membership test is now ColumnName-vs-ColumnName. Completes the
typed-id arc for the scan API — strings at the boundary, types
inside.

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

Author: dfa1

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

@@ -113,7 +113,7 @@ private static void walkLayout(VortexReader reader, Layout layout, Footer footer
                 return;
             }
             MemorySegment seg = reader.rawSegment(spec);
-            dumpFlatRoot(seg, footer.arraySpecs(), indent + "  ");
+            dumpFlatRoot(seg, footer.arraySpecs().stream().map(EncodingId::id).toList(), indent + "  ");
         } else {
             System.out.println(header);
         }

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

@@ -542,16 +542,16 @@ private void initialize() {
         Map<ColumnName, DType> columnDtypes = new LinkedHashMap<>();
 
         if (rootLayout.isStruct() && rootDtype instanceof DType.Struct structDtype) {
-            List<String> projection = options.columns();
+            List<ColumnName> projection = options.columns();
             for (int i = 0; i < rootLayout.children().size(); i++) {
                 String rawName = structDtype.fieldNames().get(i);
                 DType colDtype = structDtype.fieldTypes().get(i);
-                if (!projection.isEmpty() && !projection.contains(rawName)) {
-                    continue;
-                }
                 // File-schema names are already policy-certified by PostscriptParser, so this
                 // ColumnName construction never throws — it just types the certified key.
                 ColumnName colName = ColumnName.of(rawName);
+                if (!projection.isEmpty() && !projection.contains(colName)) {
+                    continue;
+                }
                 Layout colTop = rootLayout.children().get(i);
                 var flats = new ArrayList<Layout>();
                 collectFlats(colTop, flats);

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

@@ -1,51 +1,93 @@
 package io.github.dfa1.vortex.reader;
 
+import io.github.dfa1.vortex.core.model.ColumnName;
+
+import java.util.Arrays;
 import java.util.List;
 
 /// Options controlling a file scan.
 ///
 /// Empty `columns` = read all columns.
 /// Null `rowFilter` = no zone-map pruning.
+///
+/// Projection names are supplied as strings at the API boundary and validated into
+/// [ColumnName] on construction, so a blank or control-character projection name fails fast
+/// rather than silently matching nothing.
+///
+/// @param columns   projected column names; empty means all columns
+/// @param rowFilter zone-map pruning filter, or `null` for none
+/// @param limit     row limit, or [#NO_LIMIT]
 public record ScanOptions(
-        List<String> columns,
+        List<ColumnName> columns,
         RowFilter rowFilter,
         long limit
 ) {
+    /// Sentinel limit meaning "no row limit".
     public static final long NO_LIMIT = Long.MAX_VALUE;
 
+    /// Scans every column with no filter or limit.
+    ///
+    /// @return options selecting all columns
     public static ScanOptions all() {
         return new ScanOptions(List.of(), null, NO_LIMIT);
     }
 
+    /// Projects the named columns.
+    ///
+    /// @param names column names to project
+    /// @return options projecting `names`
     public static ScanOptions columns(String... names) {
-        return new ScanOptions(List.of(names), null, NO_LIMIT);
+        return new ScanOptions(toColumnNames(names), null, NO_LIMIT);
     }
 
+    /// Scans every column, capped at `limit` rows.
+    ///
+    /// @param limit maximum rows to read
+    /// @return options with the given row limit
     public static ScanOptions limit(long limit) {
         return new ScanOptions(List.of(), null, limit);
     }
 
+    /// Returns a copy projecting the named columns.
+    ///
+    /// @param names column names to project
+    /// @return a copy with `names` projected
     public ScanOptions withColumns(String... names) {
-        return new ScanOptions(List.of(names), rowFilter, limit);
+        return new ScanOptions(toColumnNames(names), rowFilter, limit);
     }
 
+    /// Returns a copy with the given row limit.
+    ///
+    /// @param limit maximum rows to read
+    /// @return a copy with the given limit
     public ScanOptions withLimit(long limit) {
         return new ScanOptions(columns, rowFilter, limit);
     }
 
+    /// Returns a copy with the given zone-map filter.
+    ///
+    /// @param filter the row filter, or `null` for none
+    /// @return a copy with the given filter
     public ScanOptions withFilter(RowFilter filter) {
         return new ScanOptions(columns, filter, limit);
     }
 
+    /// @return `true` if a column projection is set
     public boolean hasProjection() {
         return !columns.isEmpty();
     }
 
+    /// @return `true` if a zone-map filter is set
     public boolean hasFilter() {
         return rowFilter != null;
     }
 
+    /// @return `true` if a row limit is set
     public boolean hasLimit() {
         return limit != NO_LIMIT;
     }
+
+    private static List<ColumnName> toColumnNames(String... names) {
+        return Arrays.stream(names).map(ColumnName::of).toList();
+    }
 }

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

@@ -220,7 +220,7 @@ public Chunk decodeChunk(int chunkIndex, List<String> columns) {
         validateColumns(requested);
         ScanOptions options = requested.isEmpty()
                 ? ScanOptions.all()
-                : new ScanOptions(requested, null, ScanOptions.NO_LIMIT);
+                : ScanOptions.columns(requested.toArray(new String[0]));
         try (ScanIterator iter = new ScanIterator(this, options)) {
             return iter.decodeChunkAt(chunkIndex);
         }

reader/src/test/java/io/github/dfa1/vortex/reader/ScanOptionsTest.java

@@ -1,5 +1,6 @@
 package io.github.dfa1.vortex.reader;
 
+import io.github.dfa1.vortex.core.model.ColumnName;
 import org.junit.jupiter.api.Test;
 
 import static org.assertj.core.api.Assertions.assertThat;
@@ -24,7 +25,7 @@ void withColumns_setsProjection() {
         ScanOptions sut = ScanOptions.all().withColumns("price", "qty");
 
         // Then
-        assertThat(sut.columns()).containsExactly("price", "qty");
+        assertThat(sut.columns()).containsExactly(ColumnName.of("price"), ColumnName.of("qty"));
         assertThat(sut.hasProjection()).isTrue();
         assertThat(sut.limit()).isEqualTo(ScanOptions.NO_LIMIT);
     }
@@ -51,7 +52,7 @@ void fluent_chainingPreservesAllFields() {
                                   .withFilter(RowFilter.gte("price", 50));
 
         // Then
-        assertThat(sut.columns()).containsExactly("price", "qty");
+        assertThat(sut.columns()).containsExactly(ColumnName.of("price"), ColumnName.of("qty"));
         assertThat(sut.limit()).isEqualTo(10);
         assertThat(sut.hasFilter()).isTrue();
     }