fix: accept blank column names on read and write (#255)

ColumnName now enforces a symmetric policy: non-null and free of
control characters. Blank names ("", " ", …) are wire-legal and
produced by the Rust reference (uci-electricityloaddiagrams20112014
has one at field index 0), so they are now accepted on both paths.
Control characters remain rejected on both paths; PostscriptParser
wraps the rejection as VortexException with field-index context.

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

Author: dfa1

CHANGELOG.md

@@ -13,6 +13,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- Blank column names are now accepted on both the read and write paths. The Rust reference legitimately produces them (e.g. `uci-electricityloaddiagrams20112014` has one at field index 0). `ColumnName` now enforces a symmetric policy: non-null and free of control characters (`\n`, `\t`, U+0000, …); blank names such as `""` or `" "` pass through on both paths. ([#255](https://github.com/dfa1/vortex-java/issues/255))
 - `VarBinArray.DictMode` reads dict-value offsets in a ptype-uniform loop: the I32 fast path eliminates the per-row `switch(dictValOffPType)` that blocked C2 vectorization (introduced by #215). ([#243](https://github.com/dfa1/vortex-java/issues/243))
 - `ConstantEncodingDecoder` now returns `NullArray` for null-scalar constants (proto `null_value` tag); previously decoded as `0`/`false`, silently corrupting nullable columns that the Rust writer encodes as an all-null constant. ([#246](https://github.com/dfa1/vortex-java/issues/246))
 - `ScanIterator.sliceArray` now handles `NullArray`; previously threw on Rust-written files where a null-typed column used a coarser chunk grid than the other columns. ([#247](https://github.com/dfa1/vortex-java/issues/247))

core/src/main/java/io/github/dfa1/vortex/core/model/ColumnName.java

@@ -3,28 +3,26 @@
 import java.util.Objects;
 import java.util.Optional;
 
-/// A column (struct field) name that satisfies vortex-java's name policy: non-blank and free
-/// of control characters.
+/// A non-null typed wrapper around a column (struct field) name, free of control characters.
 ///
-/// The wire format itself accepts almost any UTF-8 string — including `""`, whitespace-only
-/// names, and control characters — but those are footguns this implementation refuses on both
-/// sides of the file boundary (the writer never emits them, the reader rejects files carrying
-/// them). A `ColumnName` certifies at construction that a name passed that policy, so code
-/// holding one never re-validates. Printable names of any shape remain legal: `"$$$$$"`,
-/// names with interior spaces, and emoji all round-trip against the reference implementation.
+/// The wire format accepts almost any UTF-8 string — including `""`, whitespace-only names,
+/// and control characters. vortex-java accepts blank names on both the read and write paths
+/// (the Rust reference produces them and they are wire-legal), but still rejects control
+/// characters because they silently break CSV, JSON, SQL identifiers, and other downstream
+/// consumers. Printable names of any shape remain legal: `""`, `"$$$$$"`, names with interior
+/// spaces, and emoji all round-trip against the reference implementation.
 ///
-/// The policy checks live in [#violation(String)] — the single source of truth used by the
-/// schema builder, the writer, and the file parser (which wraps violations in its own
-/// file-context error).
+/// The policy check lives in [#violation(String)] — the single source of truth used by the
+/// schema builder, the writer, and the file parser.
 ///
-/// @param value the validated name; use it wherever a raw column-name string is required
+/// @param value the validated name; non-null and free of control characters
 public record ColumnName(String value) implements Comparable<ColumnName> {
 
-    /// Validates the name against the policy.
+    /// Validates the name against the policy (non-null, no control characters).
     ///
     /// @param value the column name
     /// @throws NullPointerException     if `value` is `null`
-    /// @throws IllegalArgumentException if the name violates the policy ([#violation(String)])
+    /// @throws IllegalArgumentException if the name contains a control character
     public ColumnName {
         Objects.requireNonNull(value, "value");
         Optional<String> violation = violation(value);
@@ -33,12 +31,12 @@ public record ColumnName(String value) implements Comparable<ColumnName> {
         }
     }
 
-    /// Creates a validated column name.
+    /// Creates a validated column name — identical to the compact constructor.
     ///
     /// @param value the column name
     /// @return the validated [ColumnName]
     /// @throws NullPointerException     if `value` is `null`
-    /// @throws IllegalArgumentException if the name violates the policy ([#violation(String)])
+    /// @throws IllegalArgumentException if the name contains a control character
     public static ColumnName of(String value) {
         return new ColumnName(value);
     }
@@ -51,9 +49,6 @@ public static ColumnName of(String value) {
     /// @param name the raw column name to check (must be non-`null`)
     /// @return the policy violation, or empty if `name` is a valid column name
     public static Optional<String> violation(String name) {
-        if (name.isBlank()) {
-            return Optional.of("blank field name (wire-legal, but a footgun vortex-java refuses to write)");
-        }
         for (int i = 0; i < name.length(); i++) {
             if (Character.isISOControl(name.charAt(i))) {
                 return Optional.of("field name contains control character U+%04X"

core/src/main/java/io/github/dfa1/vortex/core/model/DType.java

@@ -164,17 +164,15 @@ private StructBuilder() {
 
         /// Adds a named field to the struct under construction.
         ///
-        /// Field names follow the [ColumnName] policy, stricter than the wire format on
-        /// purpose: blank names and control characters are rejected as footguns, on both the
-        /// write and the read side — same spirit as a JSON library refusing a `""` key it
-        /// could technically parse.
+        /// Delegates to [ColumnName#of(String)], which enforces the policy: names must be
+        /// non-null and free of control characters. Blank names are wire-legal and accepted.
         ///
-        /// @param name the field name; non-`null`, non-blank, no control characters, not
-        ///             previously added
+        /// @param name the field name; non-`null`, no control characters, not previously added
         /// @param type the field type
         /// @return this builder
-        /// @throws IllegalArgumentException if `name` is blank, contains a control character,
-        ///         or duplicates a previously added field
+        /// @throws NullPointerException      if `name` is `null`
+        /// @throws IllegalArgumentException  if `name` contains a control character or duplicates
+        ///                                   a previously added field
         public StructBuilder field(String name, DType type) {
             return field(ColumnName.of(name), type);
         }

core/src/test/java/io/github/dfa1/vortex/core/model/ColumnNameTest.java

@@ -91,13 +91,24 @@ void builder_isNotReusable_afterMutation_byField() {
     }
 
     @org.junit.jupiter.params.ParameterizedTest
-    @org.junit.jupiter.params.provider.ValueSource(strings = {"", " ", "   ", "a\nb", "nul\u0000here"})
-    void field_footgunName_throwsIllegalArgumentException(String name) {
-        // Given the friendly path, which enforces the write-side name policy up front:
-        // blank and control-character names are wire-legal footguns vortex-java refuses to write
+    @org.junit.jupiter.params.provider.ValueSource(strings = {"a\nb", "nul\u0000here"})
+    void field_controlCharName_throwsIllegalArgumentException(String name) {
+        // Given — control characters are rejected; blank names are wire-legal and allowed
         var builder = DType.structBuilder();
         // When / Then
         org.assertj.core.api.Assertions.assertThatThrownBy(() -> builder.field(name, DType.I64))
                 .isInstanceOf(IllegalArgumentException.class);
     }
+
+    @org.junit.jupiter.params.ParameterizedTest
+    @org.junit.jupiter.params.provider.ValueSource(strings = {"", " ", "   "})
+    void field_blankName_succeeds(String name) {
+        // Given — blank names are wire-legal; the Rust reference produces them
+        // When
+        DType.Struct result = DType.structBuilder().field(name, DType.I64).build();
+
+        // Then
+        org.assertj.core.api.Assertions.assertThat(result.fieldNames())
+                .containsExactly(ColumnName.of(name));
+    }
 }

core/src/test/java/io/github/dfa1/vortex/core/model/DTypeStructBuilderTest.java

@@ -208,7 +208,7 @@ uci-default-of-credit-card-clients,ok
 uci-diabetes,ok
 uci-diabetes-130-us-hospitals,ok
 uci-dry-bean-dataset,ok
-uci-electricityloaddiagrams20112014,gap:255
+uci-electricityloaddiagrams20112014,ok
 uci-energy-efficiency,ok
 uci-estimation-of-obesity-levels,ok
 uci-forest-fires,ok

integration/src/test/resources/raincloud/expected-status.csv

@@ -278,18 +278,16 @@ private static DType convertDType(io.github.dfa1.vortex.core.fbs.FbsDType fbs, i
                         // file, and the name-keyed Chunk API would silently drop a column.
                         throw new VortexException("duplicate field name in file schema: " + name);
                     }
-                    // Same strict name policy as the write side (ColumnName is the single
-                    // source of truth): blank and control-character names are wire-legal but
-                    // almost certainly a bug in the producing pipeline — reject with a message
-                    // that says so rather than propagate unusable names into name-keyed APIs
-                    // and SQL identifiers.
+                    // Blank names are wire-legal and produced by the Rust reference (e.g. an
+                    // empty name at field index 0); ColumnName accepts them. Control characters
+                    // are rejected on both the read and write paths — wrap as VortexException
+                    // here so the caller sees file context rather than a raw IllegalArgumentException.
                     final int fieldIndex = i;
                     io.github.dfa1.vortex.core.model.ColumnName.violation(name).ifPresent(reason -> {
-                        throw new VortexException("invalid field name in file schema (field index "
-                                + fieldIndex + "): " + reason
-                                + " — likely a bug in the pipeline that produced this file");
+                        throw new io.github.dfa1.vortex.core.error.VortexException(
+                                "invalid field name at field index " + fieldIndex + " in file schema: " + reason);
                     });
-                    names.add(io.github.dfa1.vortex.core.model.ColumnName.of(name));
+                    names.add(new io.github.dfa1.vortex.core.model.ColumnName(name));
                 }
                 for (int i = 0; i < s.dtypesLength(); i++) {
                     types.add(convertDType(s.dtypes(i), depth + 1));

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

@@ -1,6 +1,8 @@
 package io.github.dfa1.vortex.reader;
 
 import io.github.dfa1.vortex.core.error.VortexException;
+import io.github.dfa1.vortex.core.model.ColumnName;
+import io.github.dfa1.vortex.core.model.DType;
 import io.github.dfa1.vortex.core.fbs.FbsArraySpec;
 import io.github.dfa1.vortex.core.fbs.FbsBuilder;
 import io.github.dfa1.vortex.core.fbs.FbsDType;
@@ -14,15 +16,19 @@
 
 import java.lang.foreign.MemorySegment;
 
+import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.assertThatThrownBy;
 
 /// Drives the struct-dtype guards in `PostscriptParser.convertDType` with crafted dtype
 /// FlatBuffers through the package-private [PostscriptParser#parseBlobs] — no file needed.
 ///
-/// Both inputs are files the reference writer refuses to produce ("StructLayout must have
-/// unique field names") or that no writer produces at all (names/dtypes arity desync), so they
-/// only arrive crafted or corrupt — and untrusted input must fail as [VortexException], never
-/// flow into the name-keyed Chunk maps where a duplicate silently drops a column.
+/// The duplicate-name and arity-desync inputs are files the reference writer refuses to produce
+/// ("StructLayout must have unique field names") or that no writer produces at all, so they only
+/// arrive crafted or corrupt — untrusted input must fail as [VortexException], never flow into
+/// the name-keyed Chunk maps where a duplicate silently drops a column. Blank names are
+/// wire-legal and accepted on both read and write paths. Control characters are rejected on
+/// both paths (they break CSV/JSON/SQL downstream); the read path wraps the error as a
+/// [VortexException] with field-index context rather than leaking a raw IllegalArgumentException.
 class PostscriptParserDTypeGuardsTest {
 
     @Test
@@ -53,32 +59,35 @@ void convertDType_structNamesDtypesArityMismatch_throwsVortexException() {
 
     @org.junit.jupiter.params.ParameterizedTest
     @org.junit.jupiter.params.provider.ValueSource(strings = {"", " ", "   "})
-    void convertDType_blankFieldName_throwsVortexException(String name) {
-        // Given — a file schema carrying a blank field name (wire-legal; the Rust writer can
-        // produce it) — rejected by policy with a message pointing at the producing pipeline
+    void convertDType_blankFieldName_isAccepted(String name) {
+        // Given — a file schema carrying a blank field name (wire-legal; the reference
+        // implementation produces it, e.g. an empty name at field index 0 in
+        // uci-electricityloaddiagrams20112014). The read path must not reject it (#255).
         MemorySegment dtype = structDType(new String[]{name}, 1);
 
-        // When / Then — footer/layout fixtures hoisted so only the subject call is in the lambda
+        // When
         MemorySegment footer = minimalFooter();
         MemorySegment layout = flatLayout();
-        assertThatThrownBy(() -> PostscriptParser.parseBlobs(footer, layout, dtype))
-                .isInstanceOf(VortexException.class)
-                .hasMessageContaining("invalid field name in file schema")
-                .hasMessageContaining("blank field name");
+        PostscriptParser.ParsedFile result = PostscriptParser.parseBlobs(footer, layout, dtype);
+
+        // Then — the blank name round-trips into the parsed struct dtype verbatim
+        assertThat(result.dtype()).isInstanceOfSatisfying(DType.Struct.class, struct ->
+                assertThat(struct.fieldNames()).containsExactly(new ColumnName(name)));
     }
 
     @Test
     void convertDType_controlCharacterFieldName_throwsVortexException() {
-        // Given — a newline inside a file schema's field name: wire-legal, but it poisons
-        // SQL/CSV/log renderings downstream, so the reader rejects it like the writer does
+        // Given — control characters in column names break downstream consumers (CSV/JSON/SQL);
+        // ColumnName rejects them on both the read and write paths. The read path wraps the
+        // rejection as VortexException with field-index context (#255).
         MemorySegment dtype = structDType(new String[]{"a\nb"}, 1);
 
         // When / Then — footer/layout fixtures hoisted so only the subject call is in the lambda
         MemorySegment footer = minimalFooter();
         MemorySegment layout = flatLayout();
         assertThatThrownBy(() -> PostscriptParser.parseBlobs(footer, layout, dtype))
                 .isInstanceOf(VortexException.class)
-                .hasMessageContaining("control character U+000A");
+                .hasMessageContaining("U+000A");
     }
 
     @Test

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

@@ -117,10 +117,10 @@ void schema_fieldNameWithNulByte_isUnbuildable() {
     }
 
     @org.junit.jupiter.params.ParameterizedTest
-    @org.junit.jupiter.params.provider.ValueSource(strings = {"", " ", "   ", "a\nb", "tab\there"})
-    void schema_footgunFieldName_isUnbuildable(String name) {
-        // Given a blank or control-character field name — wire-legal footguns. With ColumnName-
-        // typed fieldNames the schema can't hold one; the write-side strictness is now structural.
+    @org.junit.jupiter.params.provider.ValueSource(strings = {"a\nb", "tab\there"})
+    void schema_controlCharFieldName_isUnbuildable(String name) {
+        // Given a control-character field name — rejected by ColumnName on both read and write.
+        // Blank names are wire-legal and accepted; only control chars break downstream consumers.
         // When / Then
         assertThatThrownBy(() -> new DType.Struct(
                 List.of(ColumnName.of(name)),