feat: implement DType.Map and the vortex.map encoding

- New sealed DType.Map(keyType, valueType, keysSorted, nullable) variant.
  Non-nullable key enforced by the compact constructor (VortexException,
  same reasoning as Extension's metadata bound). entriesDtype() returns the
  non-nullable {key, value} struct backing a map's physical storage.
- Wire format: dtype.fbs/dtype.proto gain a Map table/message at union tag
  13, matching upstream vortex-data/vortex field-for-field. Wired through
  PostscriptParser (decode) and VortexWriter (encode).
- vortex.map array encoding: one `entries` child (a bare vortex.listview of
  {key, value} structs), no buffers, no metadata. MapEncodingDecoder rejects
  anything other than a bare vortex.listview entries child (matching Rust's
  validate_entries); MapEncodingEncoder delegates straight to
  ListViewEncodingEncoder, since a map's entries literally are a
  ListView<Struct>.
- vortex.listview gains a real validity slot: a nullable list-view now
  carries validity in its own optional fourth child instead of always going
  through a vortex.masked wrapper. This was needed because vortex.map's
  entries child must stay a bare listview. Fixes a data-loss bug on read:
  a 4-child listview previously decoded to a bare ListViewArray with its
  validity silently dropped. A 4th child under a declared-non-nullable
  dtype is now rejected outright (contradiction between decoded and
  declared dtype otherwise). BREAKING: adding DType.Map to the sealed
  interface's permits clause breaks any downstream exhaustive
  switch (dtype) with no default arm.
- ListViewEncodingEncoder's FALLBACK gains StructEncodingEncoder, enabling
  ListView<Struct> columns generally (map's entries shape specifically).
- Editions.CORE_2026_08_0's vortex.map member flips from the placeholder
  EncodingId.Custom("vortex.map") to the real EncodingId.VORTEX_MAP.
- Fixes the performance module, left broken by the earlier vortex-jni
  0.84.0 bump (dev.vortex.api.VortexWriter.create(...) was replaced by
  builder(...).build() upstream).
- Cross-language round-trip verified against the real vortex-jni 0.84.0
  native library (MapEncodingInteropIntegrationTest): Java-writes/Rust-reads
  and Rust-writes/Java-reads, both nullable and non-nullable maps, plus
  keys_sorted survives the postscript round-trip.

Closes #351.

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

Author: dfa1

CHANGELOG.md

@@ -7,13 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- `DType.Map` logical type and the `vortex.map` encoding, read and write: a map column stores one `entries` child, a listview of non-nullable `{key, value}` structs (nullable map rows carry their validity in that listview's own validity slot), decoding to the new `MapArray`. Adding `Map` to the sealed `DType`'s `permits` clause is **breaking** for downstream exhaustive `switch` statements over `DType`. ([#351](https://github.com/dfa1/vortex-java/issues/351))
+
 ### Changed
 
 - A `fastlanes.rle` column reads its run values and per-row index table in place instead of copying them onto the heap; `LazyRle{Long,Int,Short,Byte,Double,Float,Bool}Array` now take `MemorySegment` values/indices plus a `wideIndices` flag, **breaking** for code constructing them directly. ([#342](https://github.com/dfa1/vortex-java/issues/342))
-- `WriteOptions` now defaults to the `core2026.08.0` edition, tracking upstream's new frozen edition (adds `vortex.map`, which vortex-java doesn't implement yet, so this changes no default write's output). ([#351](https://github.com/dfa1/vortex-java/issues/351))
+- `WriteOptions` now defaults to the `core2026.08.0` edition, tracking upstream's new frozen edition. ([#351](https://github.com/dfa1/vortex-java/issues/351))
 
 ### Fixed
 
+- A `vortex.listview` column no longer silently drops its validity bitmap on decode, and a validity child under a dtype the file declares non-nullable now fails as `VortexException` instead of decoding to an array that contradicts its own column dtype. ([#351](https://github.com/dfa1/vortex-java/issues/351))
+- The JMH benchmarks in `performance` compile again against vortex-jni 0.84.0, which replaced `VortexWriter.create(…)` with a builder. ([#351](https://github.com/dfa1/vortex-java/issues/351))
 - A malformed `fastlanes.rle` column now fails as `VortexException` where an absurd declared length, an empty or undersized child segment, or an out-of-range chunk offset previously escaped as `OutOfMemoryError`, `NegativeArraySizeException`, `ArithmeticException`, or `IndexOutOfBoundsException`. ([#342](https://github.com/dfa1/vortex-java/issues/342))
 - A `vortex.dict` layout over a StringView or `vortex.constant` values pool no longer expands every row into a fresh buffer, and no longer silently drops that pool's validity. ([#341](https://github.com/dfa1/vortex-java/issues/341))
 - A `vortex.dict` layout whose values pool declares more entries than it stores — a `vortex.constant` pool can claim any length in a few hundred bytes — no longer allocates against that claim; codes are bounded against the pool first, and an out-of-pool code fails as `VortexException`. ([#341](https://github.com/dfa1/vortex-java/issues/341))

cli/src/main/java/io/github/dfa1/vortex/cli/SchemaCommand.java

@@ -82,6 +82,11 @@ static String formatDType(DType dtype) {
             case DType.List(var elem, var nullable) -> "list<" + formatDType(elem) + ">" + (nullable ? "?" : "");
             case DType.FixedSizeList(var elem, var size, var nullable) ->
                     "list<" + formatDType(elem) + ">[" + size + "]" + (nullable ? "?" : "");
+            // keys_sorted is part of a map's identity — two schemas differing only in it are
+            // different types, so it is rendered rather than dropped (Rust prints it the same way).
+            case DType.Map(var key, var value, var keysSorted, var nullable) ->
+                    "map<" + formatDType(key) + ", " + formatDType(value)
+                            + ", keys_sorted=" + keysSorted + ">" + (nullable ? "?" : "");
             case DType.Extension(var id, var _, var _, var nullable) ->
                     "ext<" + id + ">" + (nullable ? "?" : "");
             case DType.Variant(var nullable) -> "variant" + (nullable ? "?" : "");

cli/src/test/java/io/github/dfa1/vortex/cli/SchemaCommandTest.java

@@ -82,6 +82,13 @@ static Stream<Arguments> dtypeCases() {
                 arguments(new DType.List(i64, true), "list<I64>?"),
                 arguments(new DType.FixedSizeList(i64, 4, false), "list<I64>[4]"),
                 arguments(new DType.FixedSizeList(i64, 4, true), "list<I64>[4]?"),
+                arguments(new DType.Map(DType.UTF8, i64, false, false), "map<utf8, I64, keys_sorted=false>"),
+                arguments(new DType.Map(DType.UTF8, i64, false, true), "map<utf8, I64, keys_sorted=false>?"),
+                // keys_sorted is part of a map's identity, so two maps differing only in it must
+                // not render identically
+                arguments(new DType.Map(DType.UTF8, i64, true, false), "map<utf8, I64, keys_sorted=true>"),
+                arguments(new DType.Map(DType.UTF8, new DType.Primitive(PType.I64, true), false, false),
+                        "map<utf8, I64?, keys_sorted=false>"),
                 arguments(new DType.Extension("vortex.uuid", i64, null, false), "ext<vortex.uuid>"),
                 arguments(new DType.Extension("vortex.uuid", i64, null, true), "ext<vortex.uuid>?"),
                 arguments(DType.VARIANT, "variant"),

core/src/main/fbs/dtype.fbs

@@ -73,6 +73,13 @@ table Union {
     nullable: bool;
 }
 
+table Map {
+    key_type: DType;
+    value_type: DType;
+    keys_sorted: bool;
+    nullable: bool;
+}
+
 union Type {
     Null = 1,
     Bool = 2,
@@ -86,6 +93,7 @@ union Type {
     FixedSizeList = 10, // This is after `Extension` for backwards compatibility.
     Variant = 11,
     Union = 12,
+    Map = 13,
 }
 
 table DType {

core/src/main/java/io/github/dfa1/vortex/core/fbs/FbsMap.java

@@ -0,0 +1,115 @@
+// Generated by vortex-fbs-gen. Do not edit.
+
+package io.github.dfa1.vortex.core.fbs;
+
+import java.lang.foreign.MemorySegment;
+import javax.annotation.processing.Generated;
+
+/// Reader and builder for the `Map` FlatBuffers table.
+@Generated("io.github.dfa1.vortex.fbsgen.CodeGen")
+public final class FbsMap extends FbsTable {
+
+    /// Positions a reader at the root table of a finished buffer.
+    /// @param seg the buffer
+    /// @return a reader positioned at the root
+    public static FbsMap getRootAsFbsMap(MemorySegment seg) {
+        return new FbsMap().assign(seg, FbsTable.rootPosition(seg, 0));
+    }
+
+    /// Positions this reader at a table.
+    /// @param seg the buffer
+    /// @param position the table position
+    /// @return this
+    public FbsMap assign(MemorySegment seg, long position) {
+        init(seg, position);
+        return this;
+    }
+
+    /// @return the `keyType` child, or null if absent
+    public FbsDType keyType() {
+        int o = fieldOffset(4);
+        return o != 0 ? new FbsDType().assign(seg, indirect(pos + o)) : null;
+    }
+
+    /// @return the `valueType` child, or null if absent
+    public FbsDType valueType() {
+        int o = fieldOffset(6);
+        return o != 0 ? new FbsDType().assign(seg, indirect(pos + o)) : null;
+    }
+
+    /// @return the `keysSorted` field
+    public boolean keysSorted() {
+        int o = fieldOffset(8);
+        return o != 0 ? readByte(pos + o) != 0 : false;
+    }
+
+    /// @return the `nullable` field
+    public boolean nullable() {
+        int o = fieldOffset(10);
+        return o != 0 ? readByte(pos + o) != 0 : false;
+    }
+
+    /// Sets the `keyType` offset field.
+    /// @param b the builder
+    /// @param offset the referenced offset
+    public static void addKeyType(FbsBuilder b, int offset) {
+        b.addOffset(0, offset, 0);
+    }
+
+    /// Sets the `valueType` offset field.
+    /// @param b the builder
+    /// @param offset the referenced offset
+    public static void addValueType(FbsBuilder b, int offset) {
+        b.addOffset(1, offset, 0);
+    }
+
+    /// Sets the `keysSorted` field.
+    /// @param b the builder
+    /// @param keysSorted value
+    public static void addKeysSorted(FbsBuilder b, boolean keysSorted) {
+        b.addBoolean(2, keysSorted, false);
+    }
+
+    /// Sets the `nullable` field.
+    /// @param b the builder
+    /// @param nullable value
+    public static void addNullable(FbsBuilder b, boolean nullable) {
+        b.addBoolean(3, nullable, false);
+    }
+
+    /// Builds a `FbsMap` table.
+    /// @param b the builder
+    /// @param keyTypeOffset field value
+    /// @param valueTypeOffset field value
+    /// @param keysSorted field value
+    /// @param nullable field value
+    /// @return the table offset
+    public static int createFbsMap(FbsBuilder b, int keyTypeOffset, int valueTypeOffset, boolean keysSorted, boolean nullable) {
+        b.startTable(4);
+        b.addOffset(1, valueTypeOffset, 0);
+        b.addOffset(0, keyTypeOffset, 0);
+        b.addBoolean(3, nullable, false);
+        b.addBoolean(2, keysSorted, false);
+        return b.endTable();
+    }
+
+    /// Begins a `FbsMap` table.
+    /// @param b the builder
+    public static void startFbsMap(FbsBuilder b) {
+        b.startTable(4);
+    }
+
+    /// Finishes a `FbsMap` table.
+    /// @param b the builder
+    /// @return the table offset
+    public static int endFbsMap(FbsBuilder b) {
+        return b.endTable();
+    }
+
+    /// Finishes the buffer with a `FbsMap` root.
+    /// @param b the builder
+    /// @param offset the root table offset
+    public static void finishFbsMapBuffer(FbsBuilder b, int offset) {
+        b.finish(offset);
+    }
+}

core/src/main/java/io/github/dfa1/vortex/core/fbs/FbsType.java

@@ -49,4 +49,7 @@ private FbsType() {
 
     /// Member `Union` = 12
     public static final byte FbsUnion = (byte) 12;
+
+    /// Member `Map` = 13
+    public static final byte FbsMap = (byte) 13;
 }

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

@@ -5,6 +5,7 @@
 import java.lang.foreign.MemorySegment;
 import java.util.ArrayList;
 import java.util.LinkedHashMap;
+import java.util.Objects;
 
 /// Vortex logical data type. Strictly logical — defines value domain, not physical storage.
 ///
@@ -19,7 +20,7 @@
 public sealed interface DType
         permits DType.Null, DType.Bool, DType.Primitive, DType.Decimal,
                         DType.Utf8, DType.Binary, DType.Struct,
-                        DType.List, DType.FixedSizeList, DType.Extension, DType.Variant {
+                        DType.List, DType.FixedSizeList, DType.Map, DType.Extension, DType.Variant {
 
     /// Returns whether this type allows null values.
     ///
@@ -36,7 +37,7 @@ default boolean isUnsigned() {
         return switch (this) {
             case Primitive(var pt, _) -> pt.isUnsigned();
             case Null _, Bool _, Decimal _, Utf8 _, Binary _, Struct _, List _,
-                 FixedSizeList _, Extension _, Variant _ -> false;
+                 FixedSizeList _, Map _, Extension _, Variant _ -> false;
         };
     }
 
@@ -64,6 +65,7 @@ default DType withNullable(boolean nullable) {
             case Struct(var names, var types, _) -> new Struct(names, types, nullable);
             case List(var elem, _) -> new List(elem, nullable);
             case FixedSizeList(var elem, var size, _) -> new FixedSizeList(elem, size, nullable);
+            case Map(var key, var value, var keysSorted, _) -> new Map(key, value, keysSorted, nullable);
             case Extension(var id, var storage, var meta, _) -> new Extension(id, storage, meta, nullable);
             case Variant _ -> new Variant(nullable);
         };
@@ -310,6 +312,44 @@ record List(DType elementType, boolean nullable) implements DType {
     record FixedSizeList(DType elementType, int fixedSize, boolean nullable) implements DType {
     }
 
+    /// Map logical type: an unordered collection of key/value entries per row.
+    ///
+    /// Physically a list of non-nullable `{key, value}` structs — see [#entriesDtype()]. The key
+    /// type must be non-nullable; the value type may be nullable.
+    ///
+    /// @param keyType    logical type of each entry key; must be non-nullable
+    /// @param valueType  logical type of each entry value
+    /// @param keysSorted producer assertion that every row's keys are sorted ascending; never
+    ///                   validated against the data, by either this implementation or the Rust
+    ///                   reference
+    /// @param nullable   whether null values are permitted
+    record Map(DType keyType, DType valueType, boolean keysSorted, boolean nullable) implements DType {
+
+        /// Rejects a nullable key type. Runs both on programmatic construction and while parsing
+        /// an untrusted file's DType blob, so it raises [VortexException] rather than
+        /// [IllegalArgumentException] — same reasoning as [Extension]'s metadata bound.
+        ///
+        /// @throws NullPointerException if `keyType` is `null`
+        /// @throws VortexException      if `keyType` is nullable
+        public Map {
+            Objects.requireNonNull(keyType, "keyType");
+            if (keyType.nullable()) {
+                throw new VortexException("map key dtype must be non-nullable: " + keyType);
+            }
+        }
+
+        /// Returns the dtype of a single map entry: a non-nullable [Struct] of `key` and `value`.
+        /// This is the element type of the list that physically backs a map column.
+        ///
+        /// @return the non-nullable `{key, value}` [Struct] dtype
+        public Struct entriesDtype() {
+            return new Struct(
+                    java.util.List.of(ColumnName.of("key"), ColumnName.of("value")),
+                    java.util.List.of(keyType, valueType),
+                    false);
+        }
+    }
+
     /// Extension logical type with user-defined semantics layered over a storage type.
     ///
     /// @param extensionId  unique string identifier for the extension type (e.g. `"vortex.timestamp"`)

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

@@ -18,11 +18,10 @@
 /// the union of everything it and every earlier edition of the same family added; see
 /// [#cumulativeMembers(Edition)].
 ///
-/// vortex-java implements every `core`-family encoding through `core2026.07.0`, referenced below
-/// by their [EncodingId.WellKnown] constants. `core2026.08.0` adds `vortex.map`, the canonical
-/// encoding for a `Map` dtype vortex-java does not model yet ([DType] has no `Map` variant), so it
-/// is named as [EncodingId.Custom] like the unimplemented `unstable` ids below. Of `unstable`, it
-/// implements only `fastlanes.delta` and `vortex.patched` — the remaining ids
+/// vortex-java implements every `core`-family encoding through `core2026.08.0`, referenced below
+/// by their [EncodingId.WellKnown] constants — including `vortex.map`, the canonical encoding for
+/// the [DType.Map] logical type. Of `unstable`, it implements only `fastlanes.delta` and
+/// `vortex.patched` — the remaining ids
 /// (`vortex.zstd_buffers`, `vortex.parquet.variant`, the `vortex.tensor.*` family, `vortex.onpair`)
 /// have no `WellKnown` constant yet, so they are named as [EncodingId.Custom] instead; the catalog
 /// stores both uniformly and mirrors upstream faithfully rather than being truncated to what is
@@ -62,7 +61,7 @@ public final class Editions {
     /// The `core` edition adding the canonical Map encoding, released through August 2026.
     public static final Edition CORE_2026_08_0 = new Edition(
             new EditionId(EditionFamily.CORE, YearMonth.of(2026, 8), 0),
-            Set.of(new EncodingId.Custom("vortex.map")));
+            Set.of(EncodingId.VORTEX_MAP));
 
     /// The May 2025 draft edition of the `unstable` family.
     public static final Edition UNSTABLE_2025_05_0 = new Edition(

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

@@ -86,6 +86,8 @@ enum WellKnown implements EncodingId {
         VORTEX_LISTVIEW("vortex.listview"),
         /// ALP-RD (ALP with remainder dictionary) encoding (`vortex.alprd`).
         VORTEX_ALPRD("vortex.alprd"),
+        /// Map encoding (`vortex.map`): a list-view of `{key, value}` entry structs.
+        VORTEX_MAP("vortex.map"),
 
         // Layout encoding IDs included so parser/registry can represent them safely
         /// Chunked layout encoding (`vortex.chunked`).
@@ -227,6 +229,8 @@ public String toString() {
     WellKnown VORTEX_LISTVIEW = WellKnown.VORTEX_LISTVIEW;
     /// Well-known `vortex.alprd` id.
     WellKnown VORTEX_ALPRD = WellKnown.VORTEX_ALPRD;
+    /// Well-known `vortex.map` id.
+    WellKnown VORTEX_MAP = WellKnown.VORTEX_MAP;
     /// Well-known `vortex.chunked` id.
     WellKnown VORTEX_CHUNKED = WellKnown.VORTEX_CHUNKED;
     /// Well-known `vortex.struct` id.