feat(fsst): rewire writer/reader adapters onto the fsst module

PR 5 of #287: reduce the two FSST production files to thin wire adapters
over the standalone vortex-fsst module. Only production code touched; no
test files changed (that is PR 6's scope). The wire format is unchanged.

Deleted (writer): the ~250-line inline SymbolTable/SymbolCandidate machinery
— training loop (trainSymbolTable), stratified sampling (sampleRowIndices),
the open-addressing longest-match index, candidate counting, and per-row
compress. All of that now lives in CompressorBuilder/Compressor/Matcher.

Deleted (reader): the byte-by-byte decompressString loop. Decoding now goes
through Decompressor (the unconditional 8-byte-store Algorithm 1).

Kept (both): all wire/metadata plumbing — UTF-8 conversion, ProtoFSSTMetadata
with narrowestUnsigned ptype selection, the EncodeNode/EncodeResult two-child
tree (uncompLens/codesOff), arena allocation of every output buffer, the
readUnsigned ptype dispatch, and the VarBinArray.OffsetMode result. The
TRAINING_SAMPLE_SEED reproducibility constant is retained and now feeds
CompressorBuilder.seed().

Wire-order code remapping (the subtle part — over-explained on purpose):
The Compressor numbers its codes in gain-descending order, but the vortex.fsst
wire format lays symbols out in length order (all multi-byte length-ascending,
then length-1 last; mirrors Rust FSSTData::validate_symbol_lengths). So the
writer must express BOTH the symbol table AND the code stream in wire codes.

  wireOrder = compressor.codesSortedByLength() — wireOrder[i] is the internal
    (gain-descending) code that belongs at wire position i.
  internalToWire[wireOrder[i]] = i — the inverse permutation, mapping every
    internal code the compressor emits to its wire position.

Symbol table buffers: at wire position i write packedSymbol(wireOrder[i]) and
symbolLength(wireOrder[i]) — the symbol living at wire slot i is internal
symbol wireOrder[i]. Code stream: compressor.compress emits internal codes;
each non-escape code byte c is rewritten to internalToWire[c]. The escape byte
0xFF and the single literal byte following it are copied through untouched —
the literal is raw data, not a code, and 0xFF never collides with a code since
codes are 0..254 (numSymbols <= 255). Reader side: it reads the wire symbol
table into code-indexed arrays and a code b in the stream indexes wire slot b
directly, so encoder position i and decoder index i refer to the same symbol —
the file is self-consistent and round-trips.

Verified: (1) writer,reader unit suite green with zero test changes (1713
tests); (2) checkstyle/javadoc gate green; (3) JavaWritesRustReadsIntegration
javaWriter_jniReader_fsstUtf8Column — the real Rust reference reader decodes
this encoder's output; (4) RustJavaReaderComparison fsst.vortex fixture (our
decoder reads a Rust-written FSST file) and FileSizeComparison
highCardinalityUtf8_javaVsJni (FSST still dispatch-selected) green; (5) full
reactor build green; plus a throwaway 11-row driver proving encode→remap→wire
symbol table→Decompressor reproduces every input byte-for-byte with the wire
table in valid length order.

Also fixed the empty-table read: with 0 trained symbols the writer floors the
symbol buffers to a 1-byte placeholder, so the decoder derives the symbol count
from symbolsBuf.byteSize()/8 (floors to 0) rather than symbolLensBuf.byteSize().

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

Author: dfa1

reader/pom.xml

@@ -20,6 +20,10 @@
 			<groupId>io.github.dfa1.vortex</groupId>
 			<artifactId>vortex-core</artifactId>
 		</dependency>
+		<dependency>
+			<groupId>io.github.dfa1.vortex</groupId>
+			<artifactId>vortex-fsst</artifactId>
+		</dependency>
 		<dependency>
 			<groupId>io.github.dfa1.zstd</groupId>
 			<artifactId>zstd</artifactId>

reader/src/main/java/io/github/dfa1/vortex/reader/decode/FsstEncodingDecoder.java

@@ -9,16 +9,20 @@
 import io.github.dfa1.vortex.core.io.VortexFormat;
 import io.github.dfa1.vortex.core.proto.ProtoFSSTMetadata;
 import io.github.dfa1.vortex.core.proto.ProtoPType;
+import io.github.dfa1.vortex.fsst.Decompressor;
 
 import java.io.IOException;
 import java.lang.foreign.MemorySegment;
 import java.lang.foreign.ValueLayout;
 
 /// Read-only decoder for `vortex.fsst`.
+///
+/// This class is a thin wire adapter over the standalone `vortex-fsst` module (issue #287): after
+/// parsing the `vortex.fsst` wire buffers (symbol table, per-row uncompressed lengths, code offsets,
+/// [ProtoFSSTMetadata]), it hands the symbol table and each row's code range to a [Decompressor],
+/// which runs the FSST paper's Algorithm 1 decode.
 public final class FsstEncodingDecoder implements EncodingDecoder {
 
-    private static final int ESCAPE = 0xFF;
-
     @Override
     public EncodingId encodingId() {
         return EncodingId.VORTEX_FSST;
@@ -63,44 +67,43 @@ public Array decode(DecodeContext ctx) {
         long uncompLensCap = SegmentBroadcast.capacity(uncompLensSeg, uncompLenPType.byteSize());
         long codesOffCap = SegmentBroadcast.capacity(codesOffsetsSeg, codesOffPType.byteSize());
 
+        // Read the wire symbol table into parallel code-indexed arrays once per chunk (there are at
+        // most 255 symbols), then hand them to the decompressor. symbolsBuf carries one LSB-first
+        // long per symbol, so its size divided by 8 is the symbol count: an empty table is written
+        // as a 1-byte placeholder buffer (allocations are floored at 1 byte), which floors to 0
+        // symbols here — an all-escape column decodes without touching the symbol table.
+        int numSymbols = (int) (symbolsBuf.byteSize() / 8);
+        long[] packedSymbols = new long[numSymbols];
+        int[] symbolLengths = new int[numSymbols];
+        for (int code = 0; code < numSymbols; code++) {
+            packedSymbols[code] = symbolsBuf.getAtIndex(VortexFormat.LE_LONG, code);
+            symbolLengths[code] = Byte.toUnsignedInt(symbolLensBuf.get(ValueLayout.JAVA_BYTE, code));
+        }
+        Decompressor decompressor = Decompressor.of(packedSymbols, symbolLengths);
+
         long totalUncompressed = 0L;
         for (long i = 0; i < n; i++) {
             totalUncompressed += readUnsigned(uncompLensSeg, i % uncompLensCap, uncompLenPType);
         }
 
-        MemorySegment outBytes = ctx.arena().allocate(totalUncompressed);
+        // Allocate 7 bytes of slack past the true logical length: the decompressor's unconditional
+        // 8-byte-store trick writes a full 8 bytes for the final symbol even when it contributes as
+        // few as 1 real byte. The slack is sliced off before the buffer is exposed, so callers still
+        // see an exactly-sized buffer.
+        MemorySegment outBytes = ctx.arena().allocate(totalUncompressed + 7);
         MemorySegment outOffsets = ctx.arena().allocate((n + 1) * 4L, 4);
         outOffsets.setAtIndex(VortexFormat.LE_INT, 0, 0);
 
         long outPos = 0L;
         for (long i = 0; i < n; i++) {
             long cStart = readUnsigned(codesOffsetsSeg, i % codesOffCap, codesOffPType);
             long cEnd = readUnsigned(codesOffsetsSeg, (i + 1) % codesOffCap, codesOffPType);
-            outPos = decompressString(compressedBytes, symbolsBuf, symbolLensBuf,
-                    cStart, cEnd, outBytes, outPos);
+            outPos = decompressor.decompress(compressedBytes, cStart, cEnd, outBytes, outPos);
             outOffsets.setAtIndex(VortexFormat.LE_INT, i + 1, (int) outPos);
         }
 
-        return new VarBinArray.OffsetMode(ctx.dtype(), n, outBytes.asReadOnly(), outOffsets.asReadOnly(), PType.I32);
-    }
-
-    private static long decompressString(
-            MemorySegment compressed, MemorySegment symbols, MemorySegment symLens,
-            long start, long end, MemorySegment out, long outPos
-    ) {
-        for (long j = start; j < end; j++) {
-            int b = Byte.toUnsignedInt(compressed.get(ValueLayout.JAVA_BYTE, j));
-            if (b == ESCAPE) {
-                out.set(ValueLayout.JAVA_BYTE, outPos++, compressed.get(ValueLayout.JAVA_BYTE, ++j));
-            } else {
-                int symLen = Byte.toUnsignedInt(symLens.get(ValueLayout.JAVA_BYTE, b));
-                long sym = symbols.getAtIndex(VortexFormat.LE_LONG, b);
-                for (int k = 0; k < symLen; k++) {
-                    out.set(ValueLayout.JAVA_BYTE, outPos++, (byte) (sym >>> (k * 8)));
-                }
-            }
-        }
-        return outPos;
+        return new VarBinArray.OffsetMode(ctx.dtype(), n,
+                outBytes.asSlice(0, totalUncompressed).asReadOnly(), outOffsets.asReadOnly(), PType.I32);
     }
 
     private static long readUnsigned(MemorySegment seg, long idx, PType ptype) {

writer/pom.xml

@@ -20,6 +20,10 @@
 			<groupId>io.github.dfa1.vortex</groupId>
 			<artifactId>vortex-core</artifactId>
 		</dependency>
+		<dependency>
+			<groupId>io.github.dfa1.vortex</groupId>
+			<artifactId>vortex-fsst</artifactId>
+		</dependency>
 		<dependency>
 			<groupId>io.github.dfa1.zstd</groupId>
 			<artifactId>zstd</artifactId>