feat(core): ColumnName domain primitive carries the name policy

The strict field-name policy created the invariant the type was
waiting for: a ColumnName certifies at construction that a name is
non-blank and free of control characters — the exact contract both
file boundaries enforce. ColumnName.violation is the single source
of truth; StructBuilder, VortexWriter, and PostscriptParser all
delegate to it instead of triplicating the checks. StructBuilder
gains a field(ColumnName, DType) overload for callers that
validate early.

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

Author: dfa1

CHANGELOG.md

@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - `Compute.filteredSum(filterColumn, predicate, aggColumn)` fuses a filter and a sum into a single scan — a row folds into the total only when the predicate selects it (a null filter row is excluded) and the aggregate value is non-null — with no intermediate selection bitmap. It matches a hand-written fused loop and is ~1.5× faster than the two-pass `filter` + `sum`. ([57d2225b](https://github.com/dfa1/vortex-java/commit/57d2225b))
 - `Compute.filteredAggregate(chunk, filter, aggColumn)` fuses a whole multi-column `RowFilter` (an n-ary `AND` of column-bound predicate leaves) and folds the selected rows' `SUM`/`MIN`/`MAX`/non-null count over an aggregate column in a single pass — the multi-column counterpart of `filteredSum`, and the row-level kernel behind the Calcite boundary-chunk aggregate push-down. A `null` aggregate column counts selected rows only (`COUNT(*)`). ([2ba54888](https://github.com/dfa1/vortex-java/commit/2ba54888))
+- `core.model.ColumnName` — the validated column-name domain primitive: non-blank, no control characters (the policy the writer, schema builder, and file parser all enforce — `ColumnName.violation` is the single source of truth). Field names are now strict on BOTH sides of the file boundary: the writer refuses blank/control names (`IllegalArgumentException`; NUL additionally crashes the reference toolchain's Arrow FFI), and the reader rejects files carrying them or duplicate field names (`VortexException`) — wire-legal is a floor, not a policy. Printable names of any shape (`$$$$$`, interior spaces, emoji) remain legal and round-trip against the reference implementation. ([c993a355](https://github.com/dfa1/vortex-java/commit/c993a355), [dca815b9](https://github.com/dfa1/vortex-java/commit/dca815b9), [d3b5b251](https://github.com/dfa1/vortex-java/commit/d3b5b251))
 - `core.model.LayoutId` — typed layout identity with the same sealed shape as `EncodingId` (`WellKnown` constants plus `Custom`; layouts are runtime-pluggable in the reference implementation). The reader now recognizes `vortex.zoned`, the current canonical zone-map layout id in the Rust reference, alongside the legacy `vortex.stats` alias it keeps writing — files from current Rust writers scan and prune correctly. ([7df3a0db](https://github.com/dfa1/vortex-java/commit/7df3a0db))
 - Layout decode is pluggable: `LayoutDecoder` + `LayoutRegistry` (`reader.layout`) mirror the encoding registry — `LayoutRegistry.builder().registerDefaults().register(custom).build()` passed to the new `VortexReader.open(path, readRegistry, layoutRegistry)` / `VortexHttpReader` overloads dispatches every layout decode, container children included, through the registry. Programmatic registration only (no service file); unknown layouts fail loudly. Zone-map pruning and filtered scans recognize the built-in layouts only. ([fc488d04](https://github.com/dfa1/vortex-java/commit/fc488d04), [dd196f17](https://github.com/dfa1/vortex-java/commit/dd196f17))
 

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

@@ -0,0 +1,79 @@
+package io.github.dfa1.vortex.core.model;
+
+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.
+///
+/// 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 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).
+///
+/// @param value the validated name; use it wherever a raw column-name string is required
+public record ColumnName(String value) implements Comparable<ColumnName> {
+
+    /// Validates the name against the policy.
+    ///
+    /// @param value the column name
+    /// @throws NullPointerException     if `value` is `null`
+    /// @throws IllegalArgumentException if the name violates the policy ([#violation(String)])
+    public ColumnName {
+        Objects.requireNonNull(value, "value");
+        Optional<String> violation = violation(value);
+        if (violation.isPresent()) {
+            throw new IllegalArgumentException(violation.get());
+        }
+    }
+
+    /// Creates a validated column name.
+    ///
+    /// @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)])
+    public static ColumnName of(String value) {
+        return new ColumnName(value);
+    }
+
+    /// Checks a raw name against the policy without constructing anything — the shared
+    /// chokepoint for all boundary guards. Callers that need a domain-specific exception
+    /// (e.g. the file parser's `VortexException` with file context) format the returned
+    /// reason themselves.
+    ///
+    /// @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"
+                        .formatted((int) name.charAt(i)));
+            }
+        }
+        return Optional.empty();
+    }
+
+    /// Orders by the name string, so sorted collections of columns read naturally.
+    ///
+    /// @param other the name to compare against
+    /// @return negative, zero, or positive per [String#compareTo(String)] on the values
+    @Override
+    public int compareTo(ColumnName other) {
+        return value.compareTo(other.value);
+    }
+
+    @Override
+    public String toString() {
+        return value;
+    }
+}

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

@@ -164,10 +164,10 @@ private StructBuilder() {
 
         /// Adds a named field to the struct under construction.
         ///
-        /// Field names follow the write-side policy, stricter than the wire format on purpose:
-        /// blank names and control characters are rejected as footguns (a foreign file may
-        /// carry them and the reader tolerates it, but vortex-java refuses to produce them —
-        /// same spirit as a JSON library refusing to write a `""` key it would happily parse).
+        /// 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.
         ///
         /// @param name the field name; non-`null`, non-blank, no control characters, not
         ///             previously added
@@ -176,17 +176,17 @@ private StructBuilder() {
         /// @throws IllegalArgumentException if `name` is blank, contains a control character,
         ///         or duplicates a previously added field
         public StructBuilder field(String name, DType type) {
-            if (name.isBlank()) {
-                throw new IllegalArgumentException(
-                        "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))) {
-                    throw new IllegalArgumentException(
-                            "field name contains control character U+%04X".formatted((int) name.charAt(i)));
-                }
-            }
-            if (fields.putIfAbsent(name, type) != null) {
+            return field(ColumnName.of(name), type);
+        }
+
+        /// Adds a named field using an already-validated [ColumnName].
+        ///
+        /// @param name the validated field name; must not have been previously added
+        /// @param type the field type
+        /// @return this builder
+        /// @throws IllegalArgumentException if `name` duplicates a previously added field
+        public StructBuilder field(ColumnName name, DType type) {
+            if (fields.putIfAbsent(name.value(), type) != null) {
                 throw new IllegalArgumentException("duplicate field name: " + name);
             }
             return this;

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

@@ -0,0 +1,75 @@
+package io.github.dfa1.vortex.core.model;
+
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.ValueSource;
+
+import java.util.Optional;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+/// The [ColumnName] policy: names a holder certifies were validated once at construction.
+/// Printable weirdness is legal (measured against the reference implementation); blank and
+/// control-character names are the footguns the policy exists to refuse.
+class ColumnNameTest {
+
+    @ParameterizedTest
+    @ValueSource(strings = {"price", "$$$$$", "with space inside", "😀emoji", "UPPER_lower.dots-1"})
+    void of_printableName_constructsAndRoundTrips(String raw) {
+        // Given a printable name of arbitrary shape
+        // When
+        ColumnName result = ColumnName.of(raw);
+
+        // Then — value, toString, and equality all carry the exact string
+        assertThat(result.value()).isEqualTo(raw);
+        assertThat(result).hasToString(raw);
+        assertThat(result).isEqualTo(new ColumnName(raw));
+    }
+
+    @ParameterizedTest
+    @ValueSource(strings = {"", " ", "   ", "a\nb", "tab\there", "nul\u0000here"})
+    void of_footgunName_throwsIllegalArgumentException(String raw) {
+        // Given / When / Then — blank or control-character names violate the policy
+        assertThatThrownBy(() -> ColumnName.of(raw))
+                .isInstanceOf(IllegalArgumentException.class);
+    }
+
+    @Test
+    void of_nullName_throwsNullPointerException() {
+        // Given / When / Then
+        assertThatThrownBy(() -> ColumnName.of(null))
+                .isInstanceOf(NullPointerException.class);
+    }
+
+    @Test
+    void violation_validName_returnsEmpty() {
+        // Given a valid name
+        // When
+        Optional<String> result = ColumnName.violation("price");
+
+        // Then
+        assertThat(result).isEmpty();
+    }
+
+    @Test
+    void violation_controlCharacter_namesTheCodePoint() {
+        // Given a name with an embedded newline
+        // When
+        Optional<String> result = ColumnName.violation("a\nb");
+
+        // Then — the reason pins the exact code point so boundary errors stay actionable
+        assertThat(result).hasValueSatisfying(reason ->
+                assertThat(reason).contains("U+000A"));
+    }
+
+    @Test
+    void compareTo_ordersByValue() {
+        // Given two names
+        // When
+        int result = ColumnName.of("a").compareTo(ColumnName.of("b"));
+
+        // Then
+        assertThat(result).isNegative();
+    }
+}

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

@@ -69,7 +69,8 @@ void jniWritesEmptyColumnName_javaRejectsItByPolicy(@TempDir Path tmp) throws IO
         // into name-keyed APIs and SQL identifiers
         assertThat(result)
                 .isInstanceOf(VortexException.class)
-                .hasMessageContaining("blank field name in file schema");
+                .hasMessageContaining("invalid field name in file schema")
+                .hasMessageContaining("blank field name");
     }
 
     @Test

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

@@ -254,22 +254,17 @@ 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: 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.
-                    if (name.isBlank()) {
-                        throw new VortexException("blank field name in file schema (field index "
-                                + i + "): wire-legal, but rejected by policy — likely a bug in "
-                                + "the pipeline that produced this file");
-                    }
-                    for (int c = 0; c < name.length(); c++) {
-                        if (Character.isISOControl(name.charAt(c))) {
-                            throw new VortexException(
-                                    "field name in file schema contains control character U+%04X (field index %d)"
-                                            .formatted((int) name.charAt(c), i));
-                        }
-                    }
+                    // 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.
+                    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");
+                    });
                     names.add(name);
                 }
                 for (int i = 0; i < s.dtypesLength(); i++) {

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

@@ -57,7 +57,8 @@ void convertDType_blankFieldName_throwsVortexException(String name) {
         // When / Then
         assertThatThrownBy(() -> PostscriptParser.parseBlobs(minimalFooter(), flatLayout(), dtype))
                 .isInstanceOf(VortexException.class)
-                .hasMessageContaining("blank field name in file schema");
+                .hasMessageContaining("invalid field name in file schema")
+                .hasMessageContaining("blank field name");
     }
 
     @Test

writer/src/main/java/io/github/dfa1/vortex/writer/VortexWriter.java

@@ -144,18 +144,11 @@ private VortexWriter(
             if (!uniqueNames.add(name)) {
                 throw new IllegalArgumentException("duplicate field name: " + name);
             }
-            if (name.isBlank()) {
-                throw new IllegalArgumentException(
-                        "blank field name (wire-legal, but a footgun vortex-java refuses to write)");
-            }
-            for (int i = 0; i < name.length(); i++) {
-                // NUL aborts the reference toolchain's Arrow FFI export (SIGABRT in arrow-rs,
-                // measured 2026-07-04); other control characters poison SQL/CSV/log renderings.
-                if (Character.isISOControl(name.charAt(i))) {
-                    throw new IllegalArgumentException(
-                            "field name contains control character U+%04X".formatted((int) name.charAt(i)));
-                }
-            }
+            // Policy chokepoint: ColumnName.violation — NUL additionally aborts the reference
+            // toolchain's Arrow FFI export (SIGABRT in arrow-rs, measured 2026-07-04).
+            io.github.dfa1.vortex.core.model.ColumnName.violation(name).ifPresent(reason -> {
+                throw new IllegalArgumentException(reason);
+            });
         }
         this.channel = channel;
         this.schema = schema;