feat(writer): cascade Utf8 dict codes so they bitpack (#303)

encodeUtf8Cascade exposed the dict values pool as an open child (#299 Finding 2b)
but left the codes as a raw vortex.primitive leaf — paying the full U8/U16/U32
code width per row. The Rust reference bitpacks dict codes (fastlanes.bitpacked),
and the primitive dict path here already exposes its codes the same way; only the
Utf8 path was missing it.

Now both children are left open: codes (index 0) as a typed primitive array the
cascade bitpacks, and the values pool (index 1) for the FSST/VarBin competition.
No wire/reader change — the reader already decodes bitpacked dict codes (it reads
Rust files that use them).

nyc-311 re-encode: 1934.23 MB -> 1862.23 MB (1.10x -> 1.06x vortex-jni); the win
spans every per-chunk Utf8 dict column, not only the street columns that surfaced
it. Composes with #302 (they compress different children). Round-trip + 217
Java-writes-Rust-reads interop tests pass; full verify green.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: dfa1

writer/src/main/java/io/github/dfa1/vortex/writer/encode/DictEncodingEncoder.java

@@ -118,12 +118,11 @@ private static CascadeStep encodeUtf8Cascade(String[] strings, EncodeContext ctx
         }
         int dictSize = valueMap.size();
         PType codePType = codePType(dictSize);
-        int codeBytes = codePType.byteSize();
 
-        MemorySegment codesBuf = ctx.arena().allocate((long) n * codeBytes);
-        for (int i = 0; i < n; i++) {
-            writeCodeToSeg(codesBuf, codePType, i, valueMap.get(strings[i]));
-        }
+        // Codes as a typed array (U8->byte[], U16->short[], U32->int[]) so the cascade can bitpack
+        // them, rather than emitting a raw vortex.primitive leaf that pays the full U8/U16/U32 width
+        // per row (#303). The primitive dict path already exposes its codes this way.
+        Object codesArr = buildCodesArray(strings, valueMap, codePType);
 
         byte[] metaBytes = new ProtoDictMetadata(
                 dictSize,
@@ -132,23 +131,51 @@ private static CascadeStep encodeUtf8Cascade(String[] strings, EncodeContext ctx
                 null
         ).encode();
 
-        // Child order matches the terminal encodeUtf8: [codes, values]. Codes is a raw primitive
-        // leaf at buffer 0; values (index 1) is left null for the cascade to fill.
-        EncodeNode codesNode = EncodeNode.leaf(EncodingId.VORTEX_PRIMITIVE, 0);
+        // Child order matches the terminal encodeUtf8: [codes, values]. Both children are left open
+        // so the cascade bitpacks the codes and FSST/VarBin-competes the values pool.
         EncodeNode partialRoot = new EncodeNode(
                 EncodingId.VORTEX_DICT, MemorySegment.ofArray(metaBytes),
-                new EncodeNode[]{codesNode, null},
+                new EncodeNode[]{null, null},
                 new int[0]);
 
         String[] distinct = valueMap.keySet().toArray(new String[0]);
-        ChildSlot valuesSlot = new ChildSlot(DType.UTF8, distinct, 1);
 
         String minStr = valueMap.keySet().stream().min(String::compareTo).orElse(null);
         String maxStr = valueMap.keySet().stream().max(String::compareTo).orElse(null);
         byte[] statsMin = minStr != null ? ProtoScalarValue.ofStringValue(minStr).encode() : null;
         byte[] statsMax = maxStr != null ? ProtoScalarValue.ofStringValue(maxStr).encode() : null;
 
-        return new CascadeStep(partialRoot, List.of(codesBuf), List.of(valuesSlot), statsMin, statsMax, true);
+        return new CascadeStep(partialRoot, List.of(),
+                List.of(new ChildSlot(new DType.Primitive(codePType, false), codesArr, 0),
+                        new ChildSlot(DType.UTF8, distinct, 1)),
+                statsMin, statsMax, true);
+    }
+
+    private static Object buildCodesArray(String[] strings, java.util.Map<String, Integer> valueMap, PType codePType) {
+        int n = strings.length;
+        return switch (codePType) {
+            case U8 -> {
+                byte[] a = new byte[n];
+                for (int i = 0; i < n; i++) {
+                    a[i] = (byte) (int) valueMap.get(strings[i]);
+                }
+                yield a;
+            }
+            case U16 -> {
+                short[] a = new short[n];
+                for (int i = 0; i < n; i++) {
+                    a[i] = (short) (int) valueMap.get(strings[i]);
+                }
+                yield a;
+            }
+            default -> {
+                int[] a = new int[n];
+                for (int i = 0; i < n; i++) {
+                    a[i] = valueMap.get(strings[i]);
+                }
+                yield a;
+            }
+        };
     }
 
     private static EncodeResult encodeUtf8(String[] strings, EncodeContext ctx) {

writer/src/test/java/io/github/dfa1/vortex/writer/encode/DictEncodingEncoderTest.java

@@ -2,6 +2,7 @@
 
 import io.github.dfa1.vortex.reader.array.Array;
 import io.github.dfa1.vortex.reader.array.VarBinArray;
+import io.github.dfa1.vortex.core.model.DType;
 import io.github.dfa1.vortex.core.testing.DTypes;
 import io.github.dfa1.vortex.reader.decode.DecodeContext;
 
@@ -180,20 +181,23 @@ void encode_utf8_metadata_valuesLen_matchesUniqueCount() throws Exception {
     }
 
     @Test
-    void encodeCascade_utf8_exposesValuesPoolAsOpenChild() {
+    void encodeCascade_utf8_exposesCodesAndValuesAsOpenChildren() {
         // Given — a low-cardinality Utf8 column.
         String[] data = repeat(new String[]{"apple", "banana", "cherry"}, 100);
 
         // When
         CascadeStep result = ENCODER.encodeCascade(DTypes.UTF8, data, EncodeTestHelper.testCtx());
 
-        // Then — the distinct-values pool (child index 1) is left open for the cascade to compress
-        // (FSST/VarBin compete on it, #299), not hardcoded to a terminal raw-varbin node.
+        // Then — both children are left open for the cascade: codes (index 0) so they bitpack
+        // (#303), and the distinct-values pool (index 1) so FSST/VarBin compete on it (#299).
         assertThat(result.isTerminal()).isFalse();
-        assertThat(result.openChildren()).singleElement().satisfies(slot -> {
-            assertThat(slot.parentChildIdx()).isEqualTo(1);
-            assertThat(slot.childDtype()).isEqualTo(DTypes.UTF8);
-            assertThat((String[]) slot.childData()).containsExactly("apple", "banana", "cherry");
-        });
+        assertThat(result.openChildren()).extracting(ChildSlot::parentChildIdx).containsExactly(0, 1);
+        // Codes child: one primitive code per row.
+        ChildSlot codes = result.openChildren().get(0);
+        assertThat(codes.childDtype()).isInstanceOf(DType.Primitive.class);
+        // Values child: the distinct pool as Utf8.
+        ChildSlot values = result.openChildren().get(1);
+        assertThat(values.childDtype()).isEqualTo(DTypes.UTF8);
+        assertThat((String[]) values.childData()).containsExactly("apple", "banana", "cherry");
     }
 }