docs: update chunk examples to ColumnName keys

Follow-up to the writeChunk(Map<ColumnName, Object>) retype (#201) and
the Chunk.put(ColumnName, ...) builder (#200): doc snippets still showed
String keys and would not compile. DocsConsistencyTest is blind to them
(the .put("x", ...) / writeChunk(Map<...>) forms have no dotted receiver
its regex can match), so this was caught in review, not CI.

- reference.md: writeChunk(Map<String, Object>) -> Map<ColumnName, Object>
- README / tutorial / compatibility: .put("x", ...) -> .put(ColumnName.of("x"), ...)
- tutorial: add the ColumnName import
- JdbcImporter.toChunkMap: drop a pointless ColumnName -> String -> ColumnName
  round-trip (List<ColumnName> names = schema.fieldNames())

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: dfa1

README.md

@@ -115,10 +115,10 @@ try (var ch = FileChannel.open(Path.of("data/example.vortex"),
                                StandardOpenOption.CREATE, StandardOpenOption.WRITE);
      var writer = VortexWriter.create(ch, schema, WriteOptions.cascading(3))) {
     writer.writeChunk(c -> c
-            .put("timestamp", new long[]   {1_700_000_000_000L, 1_700_000_001_000L})
-            .put("symbol",    new String[] {"AAPL", "AAPL"})
-            .put("price",     new double[] {189.95, 190.10})
-            .put("volume",    new Long[]   {100L, null}));  // null in nullable col
+            .put(ColumnName.of("timestamp"), new long[]   {1_700_000_000_000L, 1_700_000_001_000L})
+            .put(ColumnName.of("symbol"),    new String[] {"AAPL", "AAPL"})
+            .put(ColumnName.of("price"),     new double[] {189.95, 190.10})
+            .put(ColumnName.of("volume"),    new Long[]   {100L, null}));  // null in nullable col
 }
 ```
 

docs/compatibility.md

@@ -177,7 +177,7 @@ End-to-end round-trip — write a `List<LocalDate>`, read it back:
 var schema = DType.structBuilder()
         .field("birthdays", DateExtensionDecoder.INSTANCE.dtype(false))
         .build();
-writer.writeChunk(c -> c.put("birthdays", dates));              // Collection auto-routed
+writer.writeChunk(c -> c.put(ColumnName.of("birthdays"), dates));              // Collection auto-routed
 
 try (var iter = reader.scan(ScanOptions.all());
      Chunk chunk = iter.next()) {

docs/reference.md

@@ -98,7 +98,7 @@ Writes a Vortex file. Implements `Closeable`. The file is complete and readable
 | `static create(WritableByteChannel, DType.Struct, WriteOptions)`                 | Default codec set                                                                                                |
 | `static create(WritableByteChannel, DType.Struct, WriteOptions, List<Encoding>)` | Custom codec set                                                                                                 |
 | `writeChunk(Consumer<Chunk>)`                                                    | One batch of rows; typed builder validates column names + array types at each `.put`; missing columns throw `IllegalStateException` when the lambda returns. Preferred when columns are known at compile time. |
-| `writeChunk(Map<String, Object>)`                                                | One batch of rows by map. Validates that every schema column is present and that all columns share the same row count. Use when the column set is built dynamically (Parquet/JDBC importers, generic exporters). |
+| `writeChunk(Map<ColumnName, Object>)`                                                | One batch of rows by map. Validates that every schema column is present and that all columns share the same row count. Use when the column set is built dynamically (Parquet/JDBC importers, generic exporters). |
 | `close()`                                                                        | Finalizes file (footer, postscript, trailer)                                                                     |
 
 ### `Chunk` (`io.github.dfa1.vortex.writer.Chunk`)

docs/tutorial.md

@@ -46,6 +46,7 @@ A Vortex file is a typed struct — every column has a declared type before any
 
 ```java
 import io.github.dfa1.vortex.core.model.DType;
+import io.github.dfa1.vortex.core.model.ColumnName;
 
 DType.Struct schema = DType.structBuilder()
     .field("timestamp", DType.I64)                     // unix epoch millis
@@ -77,10 +78,10 @@ try (FileChannel ch = FileChannel.open(outPath, CREATE, WRITE, TRUNCATE_EXISTING
      VortexWriter writer = VortexWriter.create(ch, schema, WriteOptions.defaults())) {
 
     writer.writeChunk(c -> c
-        .put("timestamp", new long[]   {1_700_000_000_000L, 1_700_000_001_000L, 1_700_000_002_000L})
-        .put("symbol",    new String[] {"AAPL", "AAPL", "MSFT"})
-        .put("price",     new double[] {189.95, 190.10, 374.20})
-        .put("volume",    new Long[]   {100L, null, 175L}));   // boxed → nullable column
+        .put(ColumnName.of("timestamp"), new long[]   {1_700_000_000_000L, 1_700_000_001_000L, 1_700_000_002_000L})
+        .put(ColumnName.of("symbol"),    new String[] {"AAPL", "AAPL", "MSFT"})
+        .put(ColumnName.of("price"),     new double[] {189.95, 190.10, 374.20})
+        .put(ColumnName.of("volume"),    new Long[]   {100L, null, 175L}));   // boxed → nullable column
 }
 ```
 

jdbc/src/main/java/io/github/dfa1/vortex/jdbc/JdbcImporter.java

@@ -271,18 +271,18 @@ private static UUID toUuid(Object raw) {
 
     private static Map<ColumnName, Object> toChunkMap(DType.Struct schema, Object[] buffers,
             boolean[][] validity, boolean[] anyNull, int rows) {
-        List<String> names = schema.fieldNames().stream().map(ColumnName::value).toList();
+        List<ColumnName> names = schema.fieldNames();
         Map<ColumnName, Object> chunk = new LinkedHashMap<>();
         for (int c = 0; c < names.size(); c++) {
             Object trimmed = trimBuffer(buffers[c], rows);
             if (validity[c] != null && anyNull[c]) {
                 boolean[] trimmedValidity = rows == validity[c].length
                         ? validity[c]
                         : Arrays.copyOf(validity[c], rows);
-                chunk.put(ColumnName.of(names.get(c)),
+                chunk.put(names.get(c),
                         new io.github.dfa1.vortex.writer.encode.NullableData(trimmed, trimmedValidity));
             } else {
-                chunk.put(ColumnName.of(names.get(c)), trimmed);
+                chunk.put(names.get(c), trimmed);
             }
         }
         return chunk;