AdaWorldAPI
diff --git a/‎.claude/board/EPIPHANIES.md‎
Lines changed: 41 additions & 0 deletions b/‎.claude/board/EPIPHANIES.md‎
Lines changed: 41 additions & 0 deletions
diff --git a/‎.claude/board/LATEST_STATE.md‎
Lines changed: 31 additions & 0 deletions b/‎.claude/board/LATEST_STATE.md‎
Lines changed: 31 additions & 0 deletions
diff --git a/‎.claude/board/PR_ARC_INVENTORY.md‎
Lines changed: 21 additions & 0 deletions b/‎.claude/board/PR_ARC_INVENTORY.md‎
Lines changed: 21 additions & 0 deletions
diff --git a/‎.claude/board/STATUS_BOARD.md‎
Lines changed: 1 addition & 1 deletion b/‎.claude/board/STATUS_BOARD.md‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎.claude/plans/lgj-soa-substrate-v1.md‎
Lines changed: 2 additions & 1 deletion b/‎.claude/plans/lgj-soa-substrate-v1.md‎
Lines changed: 2 additions & 1 deletion
diff --git a/‎java/src/main/java/com/adaworldapi/lancegraph/FacetId.java‎
Lines changed: 37 additions & 0 deletions b/‎java/src/main/java/com/adaworldapi/lancegraph/FacetId.java‎
Lines changed: 37 additions & 0 deletions
diff --git a/‎java/src/main/java/com/adaworldapi/lancegraph/FacetMatchView.java‎
Lines changed: 97 additions & 0 deletions b/‎java/src/main/java/com/adaworldapi/lancegraph/FacetMatchView.java‎
Lines changed: 97 additions & 0 deletions
diff --git a/‎java/src/main/java/com/adaworldapi/lancegraph/Mask.java‎
Lines changed: 4 additions & 4 deletions b/‎java/src/main/java/com/adaworldapi/lancegraph/Mask.java‎
Lines changed: 4 additions & 4 deletions
diff --git a/‎java/src/main/java/com/adaworldapi/lancegraph/NativePattern.java‎
Lines changed: 1 addition & 1 deletion b/‎java/src/main/java/com/adaworldapi/lancegraph/NativePattern.java‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎java/src/main/java/com/adaworldapi/lancegraph/NativeResource.java‎
Lines changed: 22 additions & 0 deletions b/‎java/src/main/java/com/adaworldapi/lancegraph/NativeResource.java‎
Lines changed: 22 additions & 0 deletions
@@ -4,6 +4,47 @@
 > `**Status:**`/`**Confidence:**` line. A correction gets its own new,
 > dated entry that references the one it corrects — the storno rule.
 
+## 2026-08-17 — E-LGJ-WAVE-DISPATCH-VALIDATED-1
+
+**Status:** FINDING (first real dispatch of the wave system). **Confidence:**
+High — measured, not asserted.
+
+The wave map (`E-LGJ-CALCIFY-THEN-DISPATCH-1`) was written to be
+"dispatchable as-is by a session with zero shared context." First test: W3,
+three Sonnet workers on disjoint file scopes, zero coordination between
+them beyond the frozen signatures the orchestrator's briefs specified. All
+three landed clean, mutually consistent (same `RowStore.open(long,long)`
+signature, same `FacetId.index()` accessor — nobody guessed differently),
+and the disjoint-scope rule held with zero merge conflicts.
+
+Two things the gate sequence actually caught, worth recording precisely
+because they're the mechanism, not the anecdote:
+
+1. **A real defect, caught by the tests the wave mandated.**
+   `FacetMatchView.rowCount()` was missing the same closed-store guard
+   `matchesOf`/`cardinality` both carried — one accessor out of three,
+   asymmetric, exactly the kind of gap a reviewer skims past and a
+   two-sided lifetime test does not. `RowStoreLifetimeTest` (itself
+   AI-written, by a different worker than the one who wrote the class
+   under test) caught it on the first real run. This is the payoff of
+   "workers never run the gate themselves" — the orchestrator's fresh,
+   independent test run is what a self-reported "looks right" cannot be.
+2. **A false alarm from the ORCHESTRATOR's own environment, not the
+   code.** The first two `AllTests` invocations failed with every
+   pre-existing suite red — before touching a single line of worker
+   output. Root cause: I used an invented env var name (`LGJ_NATIVE_LIB`)
+   instead of the real one (`LGJ_LIBRARY`, defined in `Abi.java`), so the
+   runtime silently fell back to a stale `.so` from an unrelated default
+   search path. The fix was to READ THE CODE (`Abi.java`'s
+   `ENV_LIBRARY` constant) rather than guess a plausible-sounding name.
+   Lesson for future orchestrator runs: verify the discovery mechanism
+   from source before trusting a gate result — a wrong environment can
+   look exactly like a real regression.
+
+Both disable-runs (version-gate inflation; generator draw-order swap) ran
+red-then-green with the EXACT expected suite-level blast radius — no
+overreach, no under-reach — closing the loop the wave file promised.
+
 ## 2026-08-17 — E-LGJ-CALCIFY-THEN-DISPATCH-1
 
 **Status:** DOCTRINE (operator-ruled: "don't execute the consumer plans yet,
 
@@ -1,3 +1,34 @@
+## 2026-08-17 (dispatch 1) — W3 shipped: the Java `RowStore` facade, from the calcified wave map
+
+First real dispatch of the wave system: `wave-substrate-w3-w4.md` Dispatch 1
+executed exactly as mapped — 3 Sonnet workers on disjoint file scopes (FFM
+membrane extension / public facade / tests), Opus orchestrator integrated,
+gated, and fixed centrally. Confirms the calcify-then-dispatch rhythm works
+end to end, not just as a documentation exercise.
+
+- **New public surface:** `RowStore` (`open`/`rowCount`/`isOpen`/
+  `maskOfFacetClass`/`facetMatches`/`close`), `FacetMatchView`
+  (`rowCount`/`matchesOf`/`cardinality`), `FacetId` (a 0..31-checked record).
+  Zero `java.lang.foreign` types in any public signature — `ApiSurfaceTest`
+  passed unmodified.
+- **`Mask` generalized**: `source()` retypes `NativePattern → NativeResource`
+  (new minimal interface), so a mask can parent onto EITHER a pattern or a
+  row store with the existing algebra unchanged. Verified zero call-site
+  breakage before the retype.
+- **One real bug found by the suite itself and fixed**:
+  `FacetMatchView.rowCount()` was missing the closed-store guard its sibling
+  accessors both had — a caller could read a stale row count off a dead
+  view. Caught by `RowStoreLifetimeTest`, fixed, re-verified 185/185.
+- **Both disable-runs green-red-green**, confirming the version gate and the
+  generator-transcription parity are load-bearing, not decorative (full
+  detail on `STATUS_BOARD.md` D-LGJ-W3).
+- Gate: `javac -Xlint:all` clean (7 pre-existing `[restricted]` warnings,
+  0 new); `AllTests` 132→185 (+53); native `.so` unchanged this dispatch
+  (Rust side untouched — pure Java consumer work).
+
+**Next:** W4 (bench Component F, Vector API vs the crossing on the real
+row-store layout) — the second half of the same wave file.
+
 ## 2026-08-17 (latest) — waves calcified, Ghidra plan grounded, NOTHING dispatched
 
 Operator ruling: consumer plans are **calcified, not executed** — insights
 
@@ -8,6 +8,27 @@
 > anti-pattern the imported board rules name. Backfilled below in one
 > pass rather than left stale; PR #4 onward gets its entry at merge time.
 
+## PR #7 — waves calcified: dispatch maps for every plan (merged 2026-08-17, squash `68f7add`)
+
+- **Added:** `.claude/waves/` — README (standing rules + verbatim worker
+  preamble) + six dispatchable maps (substrate W3+W4 READY; three
+  consumer waves DO-NOT-DISPATCH; Ghidra G1+G2 shelved; OGAR-Machine
+  P-M1 BLOCKED behind a 4-condition gate incl. explicit operator go);
+  `.claude/plans/ghidra-integration-v1.md` (G0 archaeology from the real
+  clone: 74 P-code opcodes, `PcodeEmulator` as reference oracle, Toy as
+  minimal lift target).
+- **Locked:** the calcify-then-dispatch rhythm + the eight
+  muscle-memory rules (`E-LGJ-CALCIFY-THEN-DISPATCH-1`); the op-set
+  halt-loudly discipline; the D1a/D1b hop fork with ruling guidance.
+- **Deferred:** ALL execution, by operator ruling — nothing dispatched,
+  no code changed.
+- **Docs:** the PR is docs; mapping-time catches recorded (graph
+  consumer needs an edge-bearing generator arm — substrate change,
+  flagged before it could burn a dispatch).
+- **Confidence:** High for the maps (grounded in shipped code + real
+  clone archaeology); execution confidence deliberately unclaimed until
+  the waves run. Bot reviewers at usage limits, did not run.
+
 ## PR #6 — layout-bridge assessment, OGAR Machine plan, hydrate note (merged 2026-08-17, squash `8954e53`)
 
 - **Added:** `.claude/knowledge/prior-art-and-the-layout-bridge-claim.md`
 
@@ -38,6 +38,6 @@ layout wired end to end. Doctrine: `E-LGJ-THE-MIDDLE-TIER-IS-DELETED-NOT-WRAPPED
 |---|---|---|
 | D-LGJ-W1 | ndarray: `MultiLaneColumn::iter_u32x16`/`len_u32x16` + `eq_u32_strided_to_mask` (W1a contract) | **DONE 2026-08-17** — ndarray PR #279; `simd_int_ops` 46/46 (5 new strided tests incl. two `should_panic` bounds/overflow arms + stride-4 parity against the contiguous primitive), `simd_soa` 15/15, full `simd` 263/263, doctests, clippy `-D warnings` + fmt clean |
 | D-LGJ-W2 | lgj-abi row store: `rowstore.rs`, `LGJ_RESOURCE_ROWSTORE`, `lgj_rowstore_open`, strided facet lanes through the unchanged `LgjLaneDesc`, `lgj_op_eq_classid`, `lgj_row_facet_match`, ABI minor 1→2, `docs/abi.md` §11 | **DONE 2026-08-17** — `cargo test` **84/84**, clippy/fmt clean, release build exports **18/18** symbols (`nm -D`). Parity: both kernels vs independent scalar references over 10 row counts × 2 seeds × 4 facets × 4 needles, cross-checked a THIRD way against `RowStore::classid_at`. Two-sided payload-vs-classid falsifier. End-to-end membrane test covers describe → predicate → mask algebra → count → facet-match → lifecycle |
-| D-LGJ-W3 | Java `RowStore` facade: structured `MemoryLayout`, minor-≥2 gate, `FacetMatchView`, parity test transcribing the generator | **NEXT** |
+| D-LGJ-W3 | Java `RowStore` facade: structured `MemoryLayout`, minor-≥2 gate, `FacetMatchView`, parity test transcribing the generator | **DONE 2026-08-17** — dispatched per `.claude/waves/wave-substrate-w3-w4.md` (3 Sonnet workers, disjoint scopes: FFM membrane extension / public facade / tests), orchestrator-integrated. `javac -Xlint:all` clean (same 7 pre-existing `[restricted]` warnings, zero new). `AllTests` **185/185** (was 132; +53 new checks: 29 parity + 24 lifetime). **One real bug caught by the suite and fixed**: `FacetMatchView.rowCount()` was missing the closed-store guard `matchesOf`/`cardinality` both had — a stale row count was readable after the owning store closed. Fixed, re-verified. Both mandated disable-runs ran red-then-green: (1) `Abi.requireMinor` inflated by 1 → exactly `RowStoreParityTest`+`RowStoreLifetimeTest` failed, all 8 other suites stayed green; (2) the pure-Java generator's a/b draw order swapped in `RowStoreParityTest` → exactly that suite broke (17/29), `RowStoreLifetimeTest` (generator-independent) stayed green — confirming the parity test is a real falsifier, not decorative. `Mask.source()` retyped `NativePattern → NativeResource` (new interface) so a `Mask` can parent onto either a `NativePattern` or a `RowStore` — zero call-site breakage (verified: no existing caller bound the narrower type) |
 | D-LGJ-W4 | Bench Component F: Vector API facet scan vs the crossing, on the REAL layout | Queued |
 | D-LGJ-W5 | Three consumer examples (trades / bricks / graph) — one plan file each | Planned, gated on W3 |
@@ -43,7 +43,8 @@ disable-verified, every measured claim lands with its reproduction command.
 SoA→S3→volume→Lance hydration pattern (four-state lifecycle,
 hydrate-aside/publish-by-rename, warm markers, dirty detection), minted in
 lance-graph *specifically so consumers inherit it as a path/git dependency
-rather than re-implement*. **#958** (open, another session's PR) is its 5+3
+rather than re-implement*. **#958** (merged 2026-08-17, another session's
+PR) was its 5+3
 council hardening fast-follow. Consequence here: when this substrate's
 persistence slice arrives (the "Seal & Persist (Lance)" column of the
 formula, and `ogar-machine-v1.md`'s time-machine storage), the hydration
 
@@ -0,0 +1,37 @@
+package com.adaworldapi.lancegraph;
+
+/**
+ * Which of a {@link RowStore} row's 32 facet lanes to read.
+ *
+ * <p><strong>Not a lane id.</strong> abi.md §11 is explicit that {@code lgj_op_eq_classid} takes a
+ * facet index, not a lane id — lane {@code 0} is the raw buffer and facet {@code f}'s lane id is
+ * {@code 1 + f}. Mixing the two up is exactly the bug the end-to-end test pins (facet {@code 32}
+ * is invalid while lane {@code 32} is valid). A distinct type is what stops that confusion at the
+ * call site instead of relying on a comment.
+ *
+ * <h2>Valhalla A/B candidate</h2>
+ *
+ * <p>Same rules as {@link LaneId} and {@link Ordinal}: final, immutable, identity-free, so the
+ * same source compiles as a {@code value record} under JEP 401. It wraps a single {@code int}
+ * purely so a facet index cannot be confused with a lane id, a classid, or a row number, and under
+ * Valhalla that type-safety is expected to cost nothing at all.
+ *
+ * @param index zero-based facet index, {@code 0..32} exclusive (a row has exactly 32 facets)
+ */
+public record FacetId(int index) {
+
+    public FacetId {
+        if (index < 0 || index > 31) {
+            throw new IllegalArgumentException("facet index must be in 0..31, was " + index);
+        }
+    }
+
+    public static FacetId of(int index) {
+        return new FacetId(index);
+    }
+
+    @Override
+    public String toString() {
+        return "facet#" + index;
+    }
+}
@@ -0,0 +1,97 @@
+package com.adaworldapi.lancegraph;
+
+import java.lang.foreign.MemorySegment;
+import java.lang.foreign.ValueLayout;
+
+/**
+ * For every row of the {@link RowStore} it was taken from, which of its 32 facets carry the
+ * queried classid — one {@code int} bitset per row, bit {@code f} set exactly when facet
+ * {@code f}'s classid equals the value {@link RowStore#facetMatches} was called with.
+ *
+ * <p>Backed by a Java-owned segment a single native crossing wrote into ({@code
+ * lgj_row_facet_match}, abi.md §11). Every read below — {@link #matchesOf} and
+ * {@link #cardinality} — is an in-process access of that already-fetched segment; no further
+ * crossing occurs.
+ *
+ * <h2>Lifetime</h2>
+ *
+ * <p>A view is a child of the {@link RowStore} it was taken from: the segment it wraps is
+ * allocated from that store's own arena. It may outlive its parent as an object, but reading from
+ * it after the parent closes throws {@link ClosedResourceException} — the segment's backing arena
+ * dies with the store, so there is no arrangement of closes that lets a view read freed memory.
+ */
+public final class FacetMatchView {
+
+    private final RowStore owner;
+    private final MemorySegment data;
+    private final long rowCount;
+
+    FacetMatchView(RowStore owner, MemorySegment data, long rowCount) {
+        this.owner = owner;
+        this.data = data;
+        this.rowCount = rowCount;
+    }
+
+    /**
+     * How many rows this view covers.
+     *
+     * <p>Reads no segment bytes, but is guarded exactly like {@link #matchesOf} and
+     * {@link #cardinality} for the reason the class doc states: once the store closes, this view is
+     * no longer usable at all, not merely unsafe to read the segment through — a caller that checks
+     * {@code rowCount()} before deciding whether to call {@link #matchesOf} must not be able to
+     * observe a stale, disconnected-from-reality number from a dead view.
+     */
+    public long rowCount() {
+        requireUsable("rowCount()");
+        return rowCount;
+    }
+
+    /**
+     * The 32-bit facet-match bitset for {@code row}: bit {@code f} set means facet {@code f}'s
+     * classid equals the value queried.
+     *
+     * <p>An in-process segment read. No membrane crossing occurs.
+     *
+     * @throws IndexOutOfBoundsException if {@code row} is not in {@code [0, rowCount())}
+     */
+    public int matchesOf(long row) {
+        requireUsable("matchesOf()");
+        if (row < 0 || row >= rowCount) {
+            throw new IndexOutOfBoundsException(
+                    "row " + row + " is out of range [0, " + rowCount + ")");
+        }
+        return data.getAtIndex(ValueLayout.JAVA_INT, row);
+    }
+
+    /**
+     * The total number of set bits across every row's bitset.
+     *
+     * <p>Deliberately Java-side: this is a bulk reduction over a result that already crossed the
+     * membrane once (the single {@code lgj_row_facet_match} call behind
+     * {@link RowStore#facetMatches}), so a second crossing just to reduce it would undo the point
+     * of having fetched the whole thing in bulk.
+     */
+    public long cardinality() {
+        requireUsable("cardinality()");
+        long total = 0;
+        for (long row = 0; row < rowCount; row++) {
+            total += Integer.bitCount(data.getAtIndex(ValueLayout.JAVA_INT, row));
+        }
+        return total;
+    }
+
+    private void requireUsable(String what) {
+        // Checked before any segment access, on purpose: the segment's backing arena is the
+        // owning store's, so once the store is closed the segment must not be touched at all.
+        if (!owner.isOpen()) {
+            throw new ClosedResourceException(
+                    what + " was called on a facet-match view whose store is closed. The segment's"
+                            + " backing arena dies with the store, so it can never be read again.");
+        }
+    }
+
+    @Override
+    public String toString() {
+        return "FacetMatchView[" + rowCount + " rows]";
+    }
+}
@@ -21,11 +21,11 @@
  */
 public final class Mask implements AutoCloseable {
 
-    private final NativePattern parent;
+    private final NativeResource parent;
     private final long handle;
     private boolean closed;
 
-    Mask(NativePattern parent, long handle) {
+    Mask(NativeResource parent, long handle) {
         this.parent = parent;
         this.handle = handle;
     }
@@ -41,8 +41,8 @@ public MaskId id() {
         return new MaskId(handle);
     }
 
-    /** The resource whose rows this selects. */
-    public NativePattern source() {
+    /** The resource whose rows this selects — a {@link NativePattern} or a {@link RowStore}. */
+    public NativeResource source() {
         return parent;
     }
 
 
@@ -35,7 +35,7 @@
  * <p>Terminal operations reuse one internal scratch selection, so they are serialised on this
  * instance. Distinct resources do not contend with each other.
  */
-public final class NativePattern implements AutoCloseable {
+public final class NativePattern implements NativeResource, AutoCloseable {
 
     /**
      * The seed used by {@link #open(long)}.
 
@@ -0,0 +1,22 @@
+package com.adaworldapi.lancegraph;
+
+/**
+ * The common face of row-shaped native resources a {@link Mask} can select over.
+ *
+ * <p>Both {@link NativePattern} and {@link RowStore} hold rows natively and let a {@link Mask}
+ * parent onto them — abi.md §11 states this directly: "masks may parent onto a pattern OR a row
+ * store — both are read-only, row-shaped resources." This interface names that shared shape so
+ * {@link Mask} does not need to know, or care, which kind of resource it selects over.
+ *
+ * <p>Deliberately small: just enough for {@link Mask} to report a count and to check liveness
+ * before every operation. Anything specific to how a resource's rows are laid out or generated
+ * belongs on the concrete type, not here.
+ */
+public interface NativeResource {
+
+    /** How many rows this resource holds. */
+    long rowCount();
+
+    /** False once the resource has been closed. */
+    boolean isOpen();
+}