review: narrow gap catch, guard untrusted pool codes, harden hydrate script

Applied from the PR review: assertStillFails now catches only
VortexException plus (narrowly, tied to #215) IndexOutOfBoundsException
instead of blanket RuntimeException; pool-validity lookups guard
out-of-range codes with VortexException per the untrusted-input rule;
the hydrate script rejects a valueless --max-mb, misplaced flags, and
an empty slug list (bash 3.2 + set -u would otherwise die cryptically);
oracle-abort asymmetry documented on oracleLines.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: dfa1

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

@@ -6,6 +6,7 @@
 import dev.hardwood.reader.ParquetFileReader;
 import dev.hardwood.reader.RowReader;
 import dev.hardwood.schema.ColumnSchema;
+import io.github.dfa1.vortex.core.error.VortexException;
 import io.github.dfa1.vortex.csv.CsvExporter;
 import io.github.dfa1.vortex.csv.ExportOptions;
 import org.junit.jupiter.api.DynamicTest;
@@ -108,14 +109,16 @@ private static void reportUntriaged(Path vortex, Path parquet) {
     }
 
     private static void assertStillFails(Path vortex, Path parquet, String status) {
-        // Given / When — a decode gap still reproduces when the export itself throws; any
-        // RuntimeException counts (a gap may surface as IndexOutOfBoundsException before its
-        // decoder gains proper VortexException bounds guards, e.g. #215). No oracle needed
+        // Given / When — a decode gap still reproduces when the export itself throws.
+        // Only VortexException (the contractual untrusted-input failure) and, narrowly,
+        // IndexOutOfBoundsException count: the latter is itself a bounds-guard bug (#215
+        // throws it today) and this arm dies with that fix — a blanket RuntimeException
+        // catch would green unrelated regressions (NPEs, ...). No oracle needed here
         // (the oracle may not even read this parquet, e.g. nested columns).
         List<String> result;
         try {
             result = exportVortex(vortex);
-        } catch (RuntimeException e) {
+        } catch (VortexException | IndexOutOfBoundsException e) {
             return;
         } catch (IOException e) {
             throw new UncheckedIOException(e);
@@ -145,7 +148,9 @@ private static List<String> exportVortex(Path vortex) throws IOException {
 
     /// Reads the parquet sibling through hardwood; an oracle-side failure (nested
     /// columns, unsupported physical type) aborts the slug rather than failing it —
-    /// it says nothing about vortex-java.
+    /// it says nothing about vortex-java. Deliberate asymmetry: an `ok` slug whose
+    /// parquet the oracle cannot read stops being verified (visibly, as skipped) —
+    /// widen the oracle rather than let unverifiable entries fail the build.
     private static List<String> oracleLines(Path parquet) {
         StringWriter out = new StringWriter();
         try {

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

@@ -164,15 +164,15 @@ private static BoolArray rowValidity(DecodeContext ctx, MemorySegment codesBuf,
         if (codesCap >= rowCount) {
             for (long i = 0; i < rowCount; i++) {
                 boolean valid = (codesValidity == null || codesValidity.getBoolean(i))
-                        && poolValidity.getBoolean(readCode(codesBuf, i, codePType));
+                        && poolValid(poolValidity, readCode(codesBuf, i, codePType));
                 if (valid) {
                     setBit(bits, i);
                 }
             }
         } else {
             for (long i = 0; i < rowCount; i++) {
                 boolean valid = (codesValidity == null || codesValidity.getBoolean(i))
-                        && poolValidity.getBoolean(readCode(codesBuf, i % codesCap, codePType));
+                        && poolValid(poolValidity, readCode(codesBuf, i % codesCap, codePType));
                 if (valid) {
                     setBit(bits, i);
                 }
@@ -181,6 +181,17 @@ private static BoolArray rowValidity(DecodeContext ctx, MemorySegment codesBuf,
         return new MaterializedBoolArray(DType.BOOL, rowCount, bits.asReadOnly());
     }
 
+    /// Untrusted-input guard: a malformed file may carry codes outside the pool, and the
+    /// validity bitmap lookup must fail as [VortexException], never as a raw JDK
+    /// IndexOutOfBoundsException.
+    private static boolean poolValid(BoolArray poolValidity, long code) {
+        if (code >= poolValidity.length()) {
+            throw new VortexException(EncodingId.VORTEX_DICT,
+                    "code " + code + " out of range for pool validity of length " + poolValidity.length());
+        }
+        return poolValidity.getBoolean(code);
+    }
+
     private static long readCode(MemorySegment codes, long i, PType codePType) {
         return switch (codePType) {
             case U8 -> Byte.toUnsignedLong(codes.get(ValueLayout.JAVA_BYTE, i));

reader/src/main/java/io/github/dfa1/vortex/reader/layout/DictLayoutDecoder.java

@@ -185,6 +185,13 @@ private static BoolArray gatherRowValidity(Array codes, BoolArray codesValidity,
                 default -> throw new VortexException(EncodingId.VORTEX_DICT,
                         "layout: invalid codes type: " + codes.getClass().getSimpleName());
             };
+            // Untrusted-input guard: codes outside the pool must fail as VortexException,
+            // never as a raw JDK IndexOutOfBoundsException.
+            if (code >= poolValidity.length()) {
+                throw new VortexException(EncodingId.VORTEX_DICT,
+                        "layout: code " + code + " out of range for pool validity of length "
+                                + poolValidity.length());
+            }
             boolean valid = (codesValidity == null || codesValidity.getBoolean(i))
                     && poolValidity.getBoolean(code);
             if (valid) {

scripts/hydrate-raincloud-corpus.sh

@@ -29,9 +29,20 @@ MATRIX="$REPO_ROOT/integration/src/test/resources/raincloud/expected-status.csv"
 
 MAX_MB=200
 if [[ "${1:-}" == "--max-mb" ]]; then
+    if [[ -z "${2:-}" ]]; then
+        echo "error: --max-mb needs a value" >&2
+        exit 2
+    fi
     MAX_MB="$2"
     shift 2
 fi
+# after the flag: any remaining --max-mb is misplaced, not a slug
+for arg in "$@"; do
+    if [[ "$arg" == --* ]]; then
+        echo "error: flags must come before slugs: $arg" >&2
+        exit 2
+    fi
+done
 
 if [[ ! -d "$VENV" ]]; then
     echo "creating venv for raincloud@$RAINCLOUD_TAG"
@@ -49,6 +60,12 @@ else
     done < <(grep -v '^#' "$MATRIX" | cut -d, -f1)
 fi
 
+# bash 3.2 + set -u: expanding an empty array is an unbound-variable error
+if [ ${#SLUGS[@]} -eq 0 ]; then
+    echo "error: no slugs to hydrate (empty matrix?)" >&2
+    exit 2
+fi
+
 mkdir -p "$(dirname "$MANIFEST")"
 printf '%s\n' "${SLUGS[@]}" | MAX_MB="$MAX_MB" MANIFEST="$MANIFEST" "$VENV/bin/python" - <<'PY'
 import json