@@ -24,9 +24,11 @@ matched to the actual size of the problem.
    `jextract`/`cbindgen` out of habit).
 5. **`.claude/knowledge/jdk-toolchain-facts.md`** — which JDK path to
    use for which purpose. Getting this wrong (e.g. using `/usr/bin/java`
-   instead of `/opt/jdks/jdk-26.0.2`) produces confusing preview-flag
+   instead of `/opt/jdks/jdk-28+16`) produces confusing preview-flag
    errors that look like a design problem but are a toolchain-selection
-   mistake.
+   mistake. On JDK 28 the production build carries `--release 28
+   --enable-preview` for the Valhalla value types — FFM itself needs no
+   preview flag.
 6. **`.claude/knowledge/agent-cargo-hygiene.md`** — operator directive:
    spawned agents do NOT run `cargo` in any form (build/check/test/
    clippy), ever. Only the orchestrating main thread compiles. This
 
@@ -63,9 +63,12 @@ on both sides.
    Java side actually implements its half.
 7. **`--enable-native-access` is required and documented** in
    `java/README.md`'s exact command lines — verify the commands there
-   actually run against `/opt/jdks/jdk-26.0.2` (see
-   `.claude/knowledge/jdk-toolchain-facts.md`) without additional flags
-   beyond that one.
+   actually run against `/opt/jdks/jdk-28+16` (see
+   `.claude/knowledge/jdk-toolchain-facts.md`). **Two flags, two owners:**
+   `--enable-native-access=ALL-UNNAMED` is FFM's and the only one Panama
+   needs; `--enable-preview` is VALHALLA's, required because the production
+   vocabulary types are `value record`s. Never attribute the preview flag to
+   FFM — on JDK 28 FFM is final.
 
 ## What you are not
 
 
@@ -1,3 +1,107 @@
+## E-PANAMA-TIMES-VALHALLA-IS-ONE-MEMBRANE-AND-THE-LAB-FINALLY-HAS-ONE-VARIABLE-1 (2026-09-19)
+
+**Operator reframing, and it is the correct one:** this was never a JDK 26→28
+migration. It is **Panama-only production + Valhalla-lab arm → one production
+Panama × Valhalla membrane.** JDK 28 is the enabling toolchain, not the point.
+Panama answers *where are the bytes and how does Java reach them without
+copying*; Valhalla answers *how does Java name and carry semantic values over
+those bytes without identity-heavy heap objects*. lance-graph / T0 remains the
+only owner of canonical storage.
+
+### Measured on JDK 28 (`/opt/jdks/jdk-28+16`), production value-shaped
+
+| gate | result |
+|---|---|
+| native `lgj-abi` | **183 tests** green (182 + the new Range falsifier) |
+| Java `AllTests`, production as `value record` | **ALL PASSED (409 checks)** — identical to the unflipped baseline on the same JDK |
+| all six vocabulary types | `isValue() == true`; substitutability holds |
+
+### The flattening cliff is UNCHANGED on JDK 28 — and it bites one of our six
+
+Measured by the lab, both arms on one JDK:
+
+| type | payload | array |
+|---|---|---|
+| `LaneId` (1 int) | 4 B | **FLAT** |
+| `Ordinal` (1 int) | 4 B | **FLAT** |
+| `MaskId` (1 long) | 8 B | **FLAT** |
+| `RowRange` (2 long) | 16 B | **NOT-FLAT** |
+| `Row` (1 long + 2 int) | 16 B | **NOT-FLAT** |
+
+The ≤8-byte cliff measured on the 27-jep401ea3 build **reproduces on JDK 28**.
+So `value semantics` and `flattening` remain two different claims, and
+**`RowRange` is a real production type on the wrong side of the cliff.** No
+performance claim may be made for it from `isValue() == true`.
+
+### Allocation deltas, record arm → value arm (1M ops, same JDK)
+
+| measurement | record | value | delta |
+|---|---|---|---|
+| construct N `LaneId` into an array | 15.26 MiB | **1.87 MiB** | **8.2× less** (16 B → 1.96 B each) |
+| allocate+fill `LaneId[N]` | 19.07 MiB | **5.65 MiB** | 3.4× less |
+| construct N `Descriptor` (2 wrappers) | 45.78 MiB | **27.89 MiB** | 1.6× less |
+| construct N `LaneId`, never escaping | 4.73 MiB | **5.75 MiB** | ⊘ **value arm allocates MORE** — escape analysis already erased the record case |
+| hydrate 65,536 `Row` | 1.50 MiB | **2.00 MiB** | ⊘ **worse** — `Row` is 16 B, NOT-FLAT |
+
+**Two of the five went the wrong way, and both are honest.** Where EA already
+won, value classes add nothing; where the shape does not flatten, hydration
+costs more. Production does not hydrate rows, so the second is a warning about
+a path we do not take — not a regression we shipped.
+
+### The Panama path is byte-identical across the object model
+
+| FFM measurement | record arm | value arm |
+|---|---|---|
+| Java bytes allocated per query (warm) | 712 B | **712 B** |
+| Java objects per row | 0 | **0** |
+| native lane bytes / mask bytes | 1.00 MiB / 8.0 KiB | **identical** |
+
+**That is the integration's central invariant, measured rather than asserted:**
+Valhalla changes what the *vocabulary* costs; it does not touch the membrane.
+No second graph representation appeared, and no row hydration was introduced
+to "use Valhalla".
+
+### The lab's re-scope removed a confound it had carried since it was built
+
+The old A/B was `(record, JDK 26)` vs `(value record, JDK 27 EA)` — **two
+variables**. Both arms now run on JDK 28, so the object model is the only
+difference and the diff is attributable. The lab stops being
+present-vs-future and becomes a VM/representation probe suite over the real
+production vocabulary.
+
+Two things the re-scope forced, both real:
+- **Preview marking is transitive.** Production classfiles are preview-marked,
+  so the `record` arm *also* runs `--enable-preview`. It is a record arm on a
+  preview-enabled JVM, not a preview-free arm; the "stable" label survives only
+  as a path.
+- **A JDK 28 internal-API change.** `jdk.internal.value.ValueClass.isFlatArray`
+  narrowed from `Object` to `Object[]` since 27-jep401ea3; the flattening probe
+  was adapted (a non-`Object[]` argument answers `NOT-FLAT` without reaching
+  the internal API).
+
+### The `RangeOutOfBounds` fix is compatibility plumbing, with a falsifier
+
+`mask_risc::ExecError` gained `RangeOutOfBounds` with lance-graph's
+`Pred::Range` work and `exec_error_to_status` matches exhaustively, so
+`lgj-abi` **did not compile against lance-graph `main`**. Mapped into the
+documented *"bug in THIS file"* family — no new public status, no ABI bump —
+and backed by `plan_lower::range_falsifier::no_opcode_lowers_to_pred_range`,
+which sweeps every opcode through the real `lower_plan` and reads every
+emitted predicate. **Disable-verified red-then-green:** pointing `LGJ_OP_EQ_U32`
+at `Pred::Range` fails it with the intended message; restoring passes. When LGJ
+gains a Range lowering this goes red and forces a deliberate caller-visible
+mapping instead of inheriting `LGJ_ERR_ALLOCATION_FAILED`, which would then be
+a lie.
+
+### What could not be measured here, stated rather than implied
+
+`bench/` cannot run in this container — `bench/lib` does not exist, so the JMH
+jars are absent. The crossing-count and per-call allocation figures in
+`bench/RESULTS.md` are **historical JDK 26 measurements, correct when taken**,
+and are deliberately left untouched; they have NOT been re-taken on JDK 28.
+`gate-run.sh` carries the new pin and flags so the re-run is one command once
+the jars are present.
+
 ## E-THE-VALHALLA-FLIP-COST-ONE-WORD-SIX-TIMES-AND-THE-GATES-DID-NOT-MOVE-1 (2026-09-19)
 
 **Finding, measured end to end today.** The P0 mandate (JDK 28 + Valhalla +
 
@@ -70,11 +70,13 @@ no `cbindgen`, no `jextract`, no JNI. See `docs/abi.md` §1 and
 ## Toolchains
 
 - Rust: **1.97.1** stable, matching `ndarray`/`lance-graph`'s pin.
-- Production JDK: a GA build with `java.lang.foreign` final (no preview
-  flag needed) — verified against JDK 26 GA.
-- Valhalla lab JDK: the official JEP 401 early-access binary from
-  `jdk.java.net/valhalla/` — a value-classes preview build, kept physically
-  separate from the production path.
+- Production JDK: **JDK 28** (`/opt/jdks/jdk-28+16`). Panama FFM is final
+  there and needs no flag; Valhalla (JEP 401) is preview-gated and production
+  uses it, so `--enable-preview` is required — for the value classes, never
+  for FFM.
+- There is no separate "Valhalla JDK" any more. Production **is** the Valhalla
+  arm; `valhalla-lab/` is now a VM/representation probe suite over the real
+  production vocabulary rather than a parallel future-vs-present A/B.
 
 See `.claude/knowledge/jdk-toolchain-facts.md` for exact verified paths and
 flags in the reference development environment.
 
@@ -10,7 +10,7 @@ set -euo pipefail
 
 BENCH="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 ROOT="$(cd "$BENCH/.." && pwd)"
-JDK="${JDK:-/opt/jdks/jdk-26.0.2}"
+JDK="${JDK:-/opt/jdks/jdk-28+16}"   # P0: JDK 28 + Valhalla (JEP 401, preview) + Panama FFM
 LIB_DIR="${LIB_DIR:-$ROOT/target/release}"
 OUT="$BENCH/out-gate"
 CP_LIBS="$(find "$BENCH/lib" -name '*.jar' | sort | tr '\n' ':')"
@@ -27,10 +27,10 @@ cmp -s "$PROBE" "$VARIANT" && { echo "FAIL: variant is identical to the shipped
 rm -rf "$OUT"; mkdir -p "$OUT/before" "$OUT/after" "$OUT/bench" "$BENCH/results"
 
 echo "== build BEFORE: java/src/main as shipped"
-"$JDK/bin/javac" -d "$OUT/before" $(find "$API" -name '*.java')
+"$JDK/bin/javac" --release 28 --enable-preview -d "$OUT/before" $(find "$API" -name '*.java')
 
 echo "== build AFTER: same tree, LaneProbe.java swapped for bench/variants/probed"
-"$JDK/bin/javac" -d "$OUT/after" $(find "$API" -name '*.java' ! -path "$PROBE") "$VARIANT"
+"$JDK/bin/javac" --release 28 --enable-preview -d "$OUT/after" $(find "$API" -name '*.java' ! -path "$PROBE") "$VARIANT"
 
 # One compiled bench, run against each API build (the bench class is identical by construction).
 echo "== build the bench once"
@@ -41,6 +41,7 @@ run_arm() {
   local arm="$1"
   echo "== run $arm"
   ( cd "$BENCH" && JAVA_TOOL_OPTIONS= "$JDK/bin/java" \
+      --enable-preview \
       --enable-native-access=ALL-UNNAMED --add-modules jdk.incubator.vector \
       -Dstdout.encoding=UTF-8 -Dlgj.library="$LIB_DIR/liblgj_abi.so" \
       -Dlgj.bench.result="results/gate-$arm.csv" \
 
@@ -70,11 +70,17 @@ correctly (`bench/README.md` rule 4). Measured: a bare downcall costs
 ~22 ns over a plain Java call (`bench/RESULTS.md`, Component A) — the
 floor every native-side operation in this project sits on top of.
 
-## `--enable-preview` never reaches the shipped path
-
-The production Java tree (`java/`) targets `/opt/jdks/jdk-26.0.2`, where
-FFM is **final** — the only flag needed anywhere is
-`--enable-native-access=ALL-UNNAMED`. The Valhalla lab
+## `--enable-preview` is Valhalla's flag, never FFM's
+
+⊘ This section formerly read *"`--enable-preview` never reaches the shipped
+path"*, which was true only while production and Valhalla were split arms.
+The production Java tree (`java/`) now targets `/opt/jdks/jdk-28+16`, where
+**FFM is final and still needs no flag** — `--enable-native-access=ALL-UNNAMED`
+remains the only thing Panama asks for. What changed is that production
+deliberately uses Valhalla value classes (JEP 401, preview on this build), so
+`--release 28 --enable-preview` is now part of the shipped build contract.
+Read every "no preview" claim below as scoped to FFM: **Panama needs no
+preview; the vocabulary types do.** The Valhalla lab
 (`valhalla-lab/src/valhalla`) is compiled *separately*, with its own
 `-source 27 --enable-preview`, into its own output directory
 (`results/valhalla-lab/`), and is never on the classpath the production
 
@@ -27,17 +27,20 @@ become one native lane set, one packed mask, a few tiny schema descriptors, and
 There is no Maven, no Gradle, no downloaded dependency, and no C toolchain. `javac` and `java` are
 the entire Java toolchain, exactly as `cargo` is the entire Rust one.
 
-- **JDK 26** (`/opt/jdks/jdk-26.0.2`). FFM is **final** in JDK 26, so `--enable-preview` is neither
-  needed nor accepted. Do **not** use a JDK 21 `java` on the path — there FFM is preview-gated and
-  these commands will not work.
+- **JDK 28** (`/opt/jdks/jdk-28+16`). Two features, two reasons: **Panama FFM is final** here, so
+  it needs no flag; **Valhalla (JEP 401) is preview-gated**, and production deliberately uses it —
+  the six vocabulary types (`LaneId`, `MaskId`, `Ordinal`, `FacetId`, `RowRange`, `WideFieldMask`)
+  are `value record`s. So `--release 28 --enable-preview` is required to COMPILE and `--enable-preview`
+  to RUN. The flag is Valhalla's, never FFM's. Do **not** use a JDK 21 `java` on the path — there FFM
+  is preview-gated too and these commands will not work.
 - No JNI, no `jextract`, no `cbindgen`, no `.h` file anywhere in the project. See `../docs/abi.md`
   §0 for why those are absent by construction rather than by preference.
 
 ## Build
 
 ```sh
 cd java
-/opt/jdks/jdk-26.0.2/bin/javac -d out $(find src/main/java src/test/java -name '*.java')
+/opt/jdks/jdk-28+16/bin/javac --release 28 --enable-preview -d out $(find src/main/java src/test/java -name '*.java')
 ```
 
 Compilation emits **seven** `[restricted]` warnings with `-Xlint:all`: six in
@@ -56,11 +59,11 @@ exercise the restriction itself.
 
 ```sh
 # everything
-/opt/jdks/jdk-26.0.2/bin/java --enable-native-access=ALL-UNNAMED -cp out \
+/opt/jdks/jdk-28+16/bin/java --enable-preview --enable-native-access=ALL-UNNAMED -cp out \
     com.adaworldapi.lancegraph.AllTests
 
 # or one suite at a time — each has its own main
-/opt/jdks/jdk-26.0.2/bin/java --enable-native-access=ALL-UNNAMED -cp out \
+/opt/jdks/jdk-28+16/bin/java --enable-preview --enable-native-access=ALL-UNNAMED -cp out \
     com.adaworldapi.lancegraph.SmokeTest
 ```
 
@@ -69,7 +72,7 @@ exercise the restriction itself.
 | Flag | Needed? | Why |
 |---|---|---|
 | `--enable-native-access=ALL-UNNAMED` | **yes** | FFM's restricted methods (`libraryLookup`, `downcallHandle`, `reinterpret`) refuse to run without it. Omitting it does not fail the build — it fails at load, which is worse. |
-| `--enable-preview` | **no** | FFM is final in JDK 26. Passing it is an error. |
+| `--enable-preview` | **yes** | NOT for FFM — FFM is final on JDK 28. It is required because the production vocabulary types are Valhalla `value record`s (JEP 401, preview on this build). |
 | `-Djava.library.path=…` | **no** | Not used. That is the JNI mechanism; this project resolves the artifact itself (below). |
 
 ### Where the native library is found
 
@@ -158,3 +158,62 @@ fn pred_of(op: &LgjOpDesc) -> Option<Pred> {
         _ => return None,
     })
 }
+
+#[cfg(test)]
+mod range_falsifier {
+    use super::*;
+    use crate::abi::LGJ_COMBINE_OR;
+
+    /// **The falsifier behind `exec_error_to_status`'s `RangeOutOfBounds` arm.**
+    ///
+    /// That arm maps a `mask_risc` error into the documented *"would be a bug
+    /// in THIS file, not in a caller's plan"* family, and the justification is
+    /// one sentence: **this lowering emits no `Pred::Range`**, exactly as it
+    /// emits no sum terminal and no blend. A sentence is not a fence, so this
+    /// sweeps every opcode a caller can put in an `LgjOpDesc` — the nine
+    /// defined ones and a band of undefined ones either side — through the
+    /// real `lower_plan` and reads every emitted predicate.
+    ///
+    /// **When LGJ gains a Range lowering this test goes RED**, and that is its
+    /// whole purpose: it forces the author to decide, deliberately and
+    /// visibly, what a caller should see when a range leaves the lane — rather
+    /// than inheriting `LGJ_ERR_ALLOCATION_FAILED`, which would then be a lie.
+    #[test]
+    fn no_opcode_lowers_to_pred_range() {
+        let mut lowered_count = 0usize;
+        for op in 0u32..=32 {
+            for combine in [LGJ_COMBINE_AND, LGJ_COMBINE_OR] {
+                let desc = LgjOpDesc {
+                    op,
+                    lane_id: 0,
+                    operand: -1,
+                    combine,
+                    _reserved: 0,
+                };
+                let Some(lowered) = lower_plan(&[desc]) else {
+                    continue;
+                };
+                let Lowered::Program(program) = lowered else {
+                    continue; // AllRows: no predicate at all.
+                };
+                lowered_count += 1;
+                for mask_op in &program.ops {
+                    if let MaskOp::Pred { pred, .. } = mask_op {
+                        assert!(
+                            !matches!(pred, Pred::Range { .. }),
+                            "opcode {op} lowered to Pred::Range — `exec_error_to_status` maps \
+                             `RangeOutOfBounds` as an internal bug, which is now false: give it \
+                             a caller-visible status before shipping the Range lowering"
+                        );
+                    }
+                }
+            }
+        }
+        // Anti-vacuity: a sweep that lowers nothing proves nothing. Nine
+        // opcodes are defined and each lowers under `LGJ_COMBINE_AND`.
+        assert!(
+            lowered_count >= 9,
+            "the sweep lowered only {lowered_count} programs — it is not exercising the lowering"
+        );
+    }
+}