lgj-abi minor 12: the grouped sum that never builds a selection

`lgj_plan_group_sum_i32` lowers the fused plan and `GROUP BY key SUM(val)`
as ONE mask-risc program (`plan_lower::lower_group_sum`, the same prefix
rewrite and survivor skip as `plan_eval`, ending in `Terminal::GroupSumI32`
over the accumulator instead of `Keep`). The executor runs it tile by tile;
the only state sized by the answer is the caller's `i64` buffer, one per
group, and that is all that crosses back. Java's `View.sumByGroup` is
therefore one crossing for 16 groups at any row count, where the path it
replaces (plan_eval into a mask, then reduce per group) measured 32.

`via_res`/`via_lane` give the fk-keyed form: the group of a row is the
second table's `u32` lane read through this table's key lane, fused inside
`Terminal::GroupSumViaI32` — no partner-side mask, no remapped key lane.
`View.sumByGroupVia` is the Java spelling, still one crossing.

An empty plan is legal here (there is no destination mask a caller could
fill itself) and lowers to the whole-lane `Pred::Range { 0, n_rows }` — the
one Range this crate emits, pinned to be that range and nothing else so
`exec_error_to_status`'s RangeOutOfBounds arm stays an internal-bug mapping.

Native: 191 tests (8 new: two-crossing-path parity over the combine sweep
on single- and multi-tile populations, empty/all-OR plans against a hand
walk, n_groups as a sink bound, tiled executor vs scalar reference on both
key shapes, the fk-keyed form against a hand-walked join with zero-fallback
drops, every refusal leaving out_sums untouched, and a quack-lowering
convergence arm with Agg::GroupSumI32). Clippy -D warnings and fmt clean.

Java (JDK 28, --enable-preview): 612 checks (409 + GroupSumTest 203):
parity against per-group sumOf, one-crossing cost measured beside the
32-crossing path, the keyed form against an oracle that reads the second
resource's keys through the one named materialiser, argument checks before
any crossing. Minor12 lazy holder, requireMinor(12), an OldAbiCompatTest
gate, and the DoctrineFenceTest pin for the eighth named materialisation
site (Engine.groupSumI32's toArray, sized by groups, never rows).

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GXUahz73MZxtxWcfpHp9dG

Author: claude

java/src/main/java/com/adaworldapi/lancegraph/GroupTotals.java

@@ -0,0 +1,53 @@
+package com.adaworldapi.lancegraph;
+
+/**
+ * The answer to a grouped sum: one widened total per group, addressed by the group's key value.
+ *
+ * <p>This is what {@code SELECT key, SUM(value) … GROUP BY key} hands back — the same thing a
+ * {@code ResultSet} would, without the cursor. {@link #total(int)} is the row for key {@code g};
+ * {@link #groups()} is how many keys were asked for. A key no selected row carries has a total of
+ * {@code 0}, exactly as SQL would report it with an outer join onto the key domain.
+ *
+ * <p>Sized by the question, never by the data: a {@code GroupTotals} over 16 keys is 16 numbers
+ * whether the view spans a thousand rows or a billion. No row, no selection and no index list is
+ * behind it — the totals were folded natively in one pass and only the totals crossed.
+ *
+ * <p>Immutable. There is no accessor for the underlying storage; the totals are read one at a
+ * time by key, which is also the only way a caller ever needs them.
+ */
+public final class GroupTotals {
+
+    private final long[] totals;
+
+    GroupTotals(long[] totals) {
+        this.totals = totals;
+    }
+
+    /** How many groups this answer covers — the {@code groups} the caller asked for. */
+    public int groups() {
+        return totals.length;
+    }
+
+    /**
+     * The sum for key {@code group}, widened to 64 bits; {@code 0} when no selected row carried
+     * that key.
+     *
+     * @throws IndexOutOfBoundsException if {@code group} is not in {@code [0, groups())}
+     */
+    public long total(int group) {
+        java.util.Objects.checkIndex(group, totals.length);
+        return totals[group];
+    }
+
+    @Override
+    public String toString() {
+        StringBuilder sb = new StringBuilder("GroupTotals[");
+        for (int g = 0; g < totals.length; g++) {
+            if (g > 0) {
+                sb.append(", ");
+            }
+            sb.append(g).append('=').append(totals[g]);
+        }
+        return sb.append(']').toString();
+    }
+}

java/src/main/java/com/adaworldapi/lancegraph/NativePattern.java

@@ -226,6 +226,41 @@ OptionalLong maxOf(List<Predicate> predicates, I32Field field) {
         return reduceI32(predicates, field, Layouts.REDUCE_OP_MAX);
     }
 
+    /**
+     * {@code GROUP BY key SUM(value)} over the rows the plan selects, as ONE native program
+     * (docs/abi.md §20). No selection is built: the plan is not evaluated into a mask and then
+     * reduced per group, it is folded straight into the group totals tile by tile. An empty
+     * plan crosses as such — the ABI treats it as every row — rather than being routed through
+     * the cached all-rows selection {@link #sumOf} uses, because here there is nothing for a
+     * selection to be consumed by.
+     */
+    GroupTotals sumByGroup(List<Predicate> predicates, U32Field key, I32Field value, int groups) {
+        requireOpen("sumByGroup()");
+        synchronized (lock) {
+            requireOpen("sumByGroup()");
+            return new GroupTotals(Engine.groupSumI32(handle, plan(predicates),
+                    key.lane().index(), value.lane().index(), 0L, 0, groups));
+        }
+    }
+
+    /**
+     * The fk-keyed form of {@link #sumByGroup}: the group of a row is {@code viaKey} read on
+     * {@code via} at the row index this resource's {@code key} names — {@code SUM(line.amount)
+     * GROUP BY partner.country}, still one program and one crossing, with no selection on either
+     * resource. {@code via} may be this resource.
+     */
+    GroupTotals sumByGroupVia(List<Predicate> predicates, U32Field key, NativePattern via,
+            U32Field viaKey, I32Field value, int groups) {
+        requireOpen("sumByGroupVia()");
+        via.requireOpen("sumByGroupVia() via");
+        synchronized (lock) {
+            requireOpen("sumByGroupVia()");
+            return new GroupTotals(Engine.groupSumI32(handle, plan(predicates),
+                    key.lane().index(), value.lane().index(), via.handle(),
+                    viaKey.lane().index(), groups));
+        }
+    }
+
     /** Materialise a selection the caller owns and closes. */
     Mask selectInto(List<Predicate> predicates) {
         requireOpen("select()");

java/src/main/java/com/adaworldapi/lancegraph/View.java

@@ -114,6 +114,64 @@ public OptionalLong maxOf(I32Field field) {
         return owner.maxOf(predicates, field);
     }
 
+    /**
+     * {@code SELECT key, SUM(value) FROM … WHERE <this view> GROUP BY key}, for keys
+     * {@code 0..groups}.
+     *
+     * <p><strong>One crossing</strong>, whatever the number of conditions, groups or rows. The
+     * chain and the grouped sum are one fused native program; nothing is selected first and
+     * nothing per group is asked separately. Before this existed the same question cost two
+     * crossings per group — a {@code sumOf} over {@code where(key.eq(g))} for each {@code g} —
+     * which the {@code bricks} consumer measured at 32 for 16 groups; it is now 1 for any number.
+     *
+     * <p>A key no selected row carries totals {@code 0}. A selected row whose key is
+     * {@code >= groups} belongs to no requested group and is dropped, as a {@code WHERE key < n}
+     * would drop it; ask for more groups to see it.
+     *
+     * @param key an unsigned 32-bit column whose values are the group keys
+     * @param value the signed 32-bit column to sum, widened to 64 bits
+     * @param groups how many keys to answer for, {@code > 0}
+     * @throws AbiMismatchException if the loaded library reports ABI minor &lt; 12
+     */
+    public GroupTotals sumByGroup(U32Field key, I32Field value, int groups) {
+        java.util.Objects.requireNonNull(key, "key");
+        java.util.Objects.requireNonNull(value, "value");
+        requirePositiveGroups(groups);
+        return owner.sumByGroup(predicates, key, value, groups);
+    }
+
+    /**
+     * {@code SELECT via.viaKey, SUM(value) FROM this JOIN via ON via.row = this.key … GROUP BY
+     * via.viaKey} — the grouped sum keyed through a second resource, still <strong>one
+     * crossing</strong>.
+     *
+     * <p>{@code key} holds, for each row here, the row index in {@code via} it refers to; the
+     * group of that row is the {@code viaKey} value found there. The lookup is fused into the
+     * native fold — no selection on either resource, no remapped key column. A {@code key} that
+     * names no row of {@code via} drops the row, as an inner join would.
+     *
+     * @param via the resource whose {@code viaKey} column supplies the group; may be this view's
+     *     own resource
+     * @throws AbiMismatchException if the loaded library reports ABI minor &lt; 12
+     */
+    public GroupTotals sumByGroupVia(U32Field key, NativePattern via, U32Field viaKey,
+            I32Field value, int groups) {
+        java.util.Objects.requireNonNull(key, "key");
+        java.util.Objects.requireNonNull(via, "via");
+        java.util.Objects.requireNonNull(viaKey, "viaKey");
+        java.util.Objects.requireNonNull(value, "value");
+        requirePositiveGroups(groups);
+        return owner.sumByGroupVia(predicates, key, via, viaKey, value, groups);
+    }
+
+    private static void requirePositiveGroups(int groups) {
+        if (groups <= 0) {
+            throw new IllegalArgumentException(
+                    "groups must be positive (the number of key values to answer for), was "
+                            + groups);
+        }
+    }
+
     /**
      * A projection of one column through this view.
      *

java/src/main/java/com/adaworldapi/lancegraph/internal/ffm/Downcalls.java

@@ -491,6 +491,21 @@ private static final class Minor11 {
         private Minor11() {}
     }
 
+    /**
+     * ABI minor 12 symbol (docs/abi.md §20): the fused plan run straight into a grouped-sum
+     * terminal — one crossing returns one {@code i64} per group and no selection ever exists.
+     * Lazy per the minor-2..11 rule.
+     */
+    private static final class Minor12 {
+        static final MethodHandle PLAN_GROUP_SUM_I32 = mh("lgj_plan_group_sum_i32",
+                FunctionDescriptor.of(ValueLayout.JAVA_INT, ValueLayout.JAVA_LONG,
+                        ValueLayout.ADDRESS, ValueLayout.JAVA_INT, ValueLayout.JAVA_INT,
+                        ValueLayout.JAVA_INT, ValueLayout.JAVA_LONG, ValueLayout.JAVA_INT,
+                        ValueLayout.ADDRESS, ValueLayout.JAVA_LONG));
+
+        private Minor12() {}
+    }
+
     /**
      * Sum one facet's 12-byte register, under {@code carving}, over the rows a mask selects.
      *
@@ -639,6 +654,29 @@ public static long reduceI32(long res, int laneId, int reduceOp, long mask,
         return outValue.get(ValueLayout.JAVA_LONG, 0);
     }
 
+    /**
+     * {@code GROUP BY groupLane SUM(valLane)} over the rows the plan selects, in ONE crossing
+     * (docs/abi.md §20, minor 12). {@code outSums} receives {@code nGroups} widened totals; a
+     * selected row whose key is past {@code nGroups} is dropped, never an error. With
+     * {@code viaRes != 0} the key is read THROUGH {@code groupLane} into {@code viaRes}'s
+     * {@code viaLane} (the fk-keyed form). {@code nOps == 0} is legal and means every row.
+     *
+     * <p>Bulk in the §6 sense: one pass over the predicate lanes, one read of the key and value
+     * lanes for the selected rows, no per-row and no per-group crossing.
+     */
+    public static void planGroupSumI32(long res, MemorySegment ops, int nOps, int groupLane,
+            int valLane, long viaRes, int viaLane, MemorySegment outSums, long nGroups) {
+        crossed();
+        int st;
+        try {
+            st = (int) Minor12.PLAN_GROUP_SUM_I32.invokeExact(res, ops, nOps, groupLane, valLane,
+                    viaRes, viaLane, outSums, nGroups);
+        } catch (Throwable t) {
+            throw wrap("lgj_plan_group_sum_i32", t);
+        }
+        Status.check("lgj_plan_group_sum_i32", st);
+    }
+
     // ── row store (docs/abi.md §11, ABI minor 2) ─────────────────────────────────────────────
     //
     // Callers above this class are expected to have already checked Abi.requireMinor(2) — these

java/src/main/java/com/adaworldapi/lancegraph/internal/ffm/Engine.java

@@ -379,6 +379,37 @@ public static ReduceOutcome reduceI32(long resource, int laneId, int reduceOp, l
         return new ReduceOutcome(value, present);
     }
 
+    /**
+     * The grouped sum that never builds a selection (docs/abi.md §20, ABI minor 12):
+     * {@code GROUP BY groupLane SUM(valLane)} over the rows {@code plan} selects, evaluated as
+     * ONE native program and returned as one widened total per group. Unlike every reduce
+     * above, no mask handle is involved at any point — the plan is not evaluated INTO anything;
+     * the fold reads it tile by tile and lands only the group totals.
+     *
+     * <p>{@code viaResource != 0} selects the fk-keyed form: the group of a row is
+     * {@code viaLane[groupLane[row]]}, read on {@code viaResource}, with no partner-side
+     * selection and no remapped key lane (the indirection is fused inside the native terminal).
+     *
+     * <p>An empty {@code plan} is legal here and means every row — the ABI has no destination
+     * mask for Java to fill on its own, so the whole-lane case crosses as a plan of zero ops
+     * rather than being answered locally. Requires ABI minor &gt;= 12.
+     *
+     * <p>The returned array is sized by {@code groups} — the shape of the QUESTION the caller
+     * typed, never by the row count — which is what keeps it on the right side of the
+     * materialization rule (the eighth named site; see the repo's zero-copy section).
+     */
+    public static long[] groupSumI32(long resource, List<PlanOp> plan, int groupLane, int valLane,
+            long viaResource, int viaLane, int groups) {
+        Abi.requireMinor(12);
+        MemorySegment ops = plan.isEmpty() ? MemorySegment.NULL : marshal(plan);
+        try (Arena a = Arena.ofConfined()) {
+            MemorySegment out = a.allocate(ValueLayout.JAVA_LONG, groups);
+            Downcalls.planGroupSumI32(resource, ops, plan.size(), groupLane, valLane, viaResource,
+                    viaLane, out, groups);
+            return out.toArray(ValueLayout.JAVA_LONG);
+        }
+    }
+
     // ── mask complement + hop (docs/abi.md §13, ABI minor ≥ 4) ─────────────────────────────
     //
     // Same requireMinor-before-any-downcall discipline as the row store section above: a Java

java/src/test/java/com/adaworldapi/lancegraph/AllTests.java

@@ -34,6 +34,7 @@ public static void main(String[] args) {
         suites.put("CarvingTableTest", CarvingTableTest::run);
         suites.put("ColumnarStoreTest", ColumnarStoreTest::run);
         suites.put("MaskingOpCompletionTest", MaskingOpCompletionTest::run);
+        suites.put("GroupSumTest", GroupSumTest::run);
 
         if (!NativeRuntime.isAvailable()) {
             // ApiSurfaceTest and DoctrineFenceTest need no native library — the API's shape is a

java/src/test/java/com/adaworldapi/lancegraph/DoctrineFenceTest.java

@@ -100,6 +100,9 @@ private DoctrineFenceTest() {}
     // five named sites, mechanically:
     //   Mask.materializeRows()           → Arrays.copyOf ×2 + new long[ ×1   (the named terminal)
     //   Engine.rowLayoutProbe            → .toArray( ×1                       (≤32 B diagnostic)
+    //   Engine.groupSumI32               → .toArray( ×1                       (one i64 per GROUP —
+    //                                      sized by the question the caller typed, never by rows;
+    //                                      the eighth named site, minor 12)
     //   Engine.facetSumResolved          → new long[ ×1                       (fixed [2] pair)
     //   Abi manifest-name read (cString) → new byte[ ×1 + MemorySegment.copy ×1
     //   Abi.readCarvings                 → new int[ ×2                        (incl. empty arm)
@@ -108,7 +111,7 @@ private DoctrineFenceTest() {}
     static {
         MATERIALIZATION_PINS.put("Mask.java|Arrays.copyOf", 2);
         MATERIALIZATION_PINS.put("Mask.java|new long[", 1);
-        MATERIALIZATION_PINS.put("Engine.java|.toArray(", 1);
+        MATERIALIZATION_PINS.put("Engine.java|.toArray(", 2);
         MATERIALIZATION_PINS.put("Engine.java|new long[", 1);
         MATERIALIZATION_PINS.put("Abi.java|new int[", 2);
         MATERIALIZATION_PINS.put("Abi.java|new byte[", 1);