simd: scatter-or and group-sum kernels accumulate into out, never zero it

A fold kernel adds or ORs into the caller's demanded sink; the caller
zeroes that sink once. Whole-buffer zeroing inside the kernel made every
call population-sized in writes and broke tiled execution, where the
same sink receives one call per tile. mask_gather_u32 is unchanged (its
destination is its own output tile).

Tests: 6 two-sided accumulation tests (each red with the zeroing
restored, verified); parity group 13 gains three from-nonzero checks.

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

Author: claude

.claude/blackboard.md

@@ -6,6 +6,7 @@ All three are deliberately scalar bit-walks — permutations/scatters indexed by
 Parity: `check_gather_scatter_group` (0xDxx) in `crates/simd-masking-parity`, against naive per-element references, disable-verified red-then-green.
 `masked_group_sum_i32_via(mask, index, remap, values, out)` — the same one-pass keyed sum with the key read through a foreign-key hop (`SUM(line.amount) GROUP BY partner.country`); the indirection is fused so no remapped key lane of N is ever materialised. Fourth arm of the same parity group (0xD3x).
 Consumer: lance-graph-mask-risc `Gather`/`ScatterOr`/`GroupSum` (landing next).
+⊘ CORRECTED (operator ruling, same day): `mask_scatter_or_u32`, `masked_group_sum_i32`, and `masked_group_sum_i32_via` no longer zero `out`/`out_words` on entry — a fold kernel accumulates into the caller's demanded sink, and the caller zeroes it once. `mask_gather_u32` is unaffected (its destination is its own output tile). Each function's doc comment now states "accumulates into `out`; the caller zeroes `out` once before the first call"; the surplus/unreferenced-slot assertions in the tail tests were reworded to "untouched, stays as the caller left it" rather than "cleared". Every unit test whose `out` buffer relied on the old zeroing was given an explicit zeroed prefill in its arrange step, and each of the three functions got two new two-sided tests (a preloaded slot/bit that survives untouched alongside the call's own contribution landing correctly; a second call with a different mask summing/unioning on top of the first) — disable-verified red-then-green by temporarily restoring the whole-buffer zero in each function in turn. The parity crate's `check_gather_scatter_group` (0xDxx) now zeroes `out`/`out2` explicitly before its from-zero reference checks and adds one accumulation check per function (0xD11/0xD22/0xD32) that preloads `out` and asserts the call adds on top.
 
 ## 2026-09-17 (19) — G8 named: a tree-depth column (`lzcnt(bswap(x)) >> 2`) is the missing primitive for basin-local ranking; popcount is only its tie-break
 

crates/simd-masking-parity/src/lib.rs

@@ -1163,6 +1163,10 @@ fn check_gather_scatter_group() -> Result<(), u32> {
         }
 
         // ── mask_scatter_or_u32 ──────────────────────────────────────────
+        // `out2` starts explicitly zeroed (the caller's job now, not the
+        // primitive's): the accumulate contract means a dirty prefill would
+        // stay dirty rather than being cleared, so parity against a
+        // from-zero reference needs a from-zero `out2`.
         let out_rows = 50usize;
         let out_words_count = words_for(out_rows);
         let src_bits: Vec<u64> = (0..nw).map(|_| rng.next()).collect();
@@ -1176,8 +1180,8 @@ fn check_gather_scatter_group() -> Result<(), u32> {
                 }
             })
             .collect();
-        let out_len2 = out_words_count + 1; // dirty, over-long
-        let mut out2 = vec![u64::MAX; out_len2];
+        let out_len2 = out_words_count + 1; // over-long, but zeroed not dirty
+        let mut out2 = vec![0u64; out_len2];
         mask_scatter_or_u32(&src_bits, &idx2, &mut out2, out_rows);
         let mut want2 = vec![false; out_rows];
         for i in 0..n {
@@ -1193,6 +1197,23 @@ fn check_gather_scatter_group() -> Result<(), u32> {
             return Err(0xD10);
         }
 
+        // Accumulation check: preload a bit, prove it survives the call
+        // unioned with the scatter result — the reference is the union
+        // regardless of whether the preloaded bit also happens to be a
+        // scatter target, which is exactly what accumulation must produce.
+        {
+            let preset_bit = out_rows - 1;
+            let mut out2_acc = vec![0u64; out_len2];
+            out2_acc[preset_bit / 64] |= 1u64 << (preset_bit % 64);
+            mask_scatter_or_u32(&src_bits, &idx2, &mut out2_acc, out_rows);
+            let mut want2_acc = want2.clone();
+            want2_acc[preset_bit] = true;
+            let want2_acc_words = reference_mask(out_rows, out_len2, |t| want2_acc[t]);
+            if out2_acc != want2_acc_words {
+                return Err(0xD11);
+            }
+        }
+
         // ── masked_group_sum_i32 ─────────────────────────────────────────
         let n_groups = 12usize;
         let mask_bits: Vec<u64> = (0..nw).map(|_| rng.next()).collect();
@@ -1207,7 +1228,9 @@ fn check_gather_scatter_group() -> Result<(), u32> {
             })
             .collect();
         let values = i32_values(n, &mut rng);
-        let mut group_out = vec![-1i64; n_groups + 1]; // garbage + one unreferenced slot
+        // `out` starts explicitly zeroed: the caller's job now, not the
+        // primitive's.
+        let mut group_out = vec![0i64; n_groups + 1]; // one unreferenced slot
         masked_group_sum_i32(&mask_bits, &keys, &values, &mut group_out);
         let mut want_group = vec![0i64; n_groups];
         for i in 0..n {
@@ -1221,10 +1244,26 @@ fn check_gather_scatter_group() -> Result<(), u32> {
         if group_out[..n_groups] != want_group[..] {
             return Err(0xD20);
         }
-        // The unreferenced slot must be zeroed, not left as garbage.
+        // The unreferenced slot must stay exactly as the caller left it
+        // (zero here), never touched.
         if group_out[n_groups] != 0 {
             return Err(0xD21);
         }
+        // Accumulation check: preload every group slot with a known value,
+        // prove the call adds its contribution on top rather than resetting.
+        {
+            let preload = 1_000_000i64;
+            let mut group_out_acc = vec![preload; n_groups + 1];
+            masked_group_sum_i32(&mask_bits, &keys, &values, &mut group_out_acc);
+            for k in 0..n_groups {
+                if group_out_acc[k] != preload.wrapping_add(want_group[k]) {
+                    return Err(0xD22);
+                }
+            }
+            if group_out_acc[n_groups] != preload {
+                return Err(0xD22);
+            }
+        }
 
         // ── masked_group_sum_i32_via ─────────────────────────────────────
         // Same n_groups/mask_bits/values as above, but the key is reached
@@ -1251,7 +1290,9 @@ fn check_gather_scatter_group() -> Result<(), u32> {
                 }
             })
             .collect();
-        let mut via_out = vec![-1i64; n_groups + 1]; // garbage + one unreferenced slot
+        // `out` starts explicitly zeroed: the caller's job now, not the
+        // primitive's.
+        let mut via_out = vec![0i64; n_groups + 1]; // one unreferenced slot
         masked_group_sum_i32_via(&mask_bits, &index, &remap, &values, &mut via_out);
         let mut want_via = vec![0i64; n_groups];
         for i in 0..n {
@@ -1270,9 +1311,26 @@ fn check_gather_scatter_group() -> Result<(), u32> {
         if via_out[..n_groups] != want_via[..] {
             return Err(0xD30);
         }
+        // The unreferenced slot must stay exactly as the caller left it
+        // (zero here), never touched.
         if via_out[n_groups] != 0 {
             return Err(0xD31);
         }
+        // Accumulation check: preload every group slot, prove the call adds
+        // its contribution on top rather than resetting.
+        {
+            let preload = 2_000_000i64;
+            let mut via_out_acc = vec![preload; n_groups + 1];
+            masked_group_sum_i32_via(&mask_bits, &index, &remap, &values, &mut via_out_acc);
+            for k in 0..n_groups {
+                if via_out_acc[k] != preload.wrapping_add(want_via[k]) {
+                    return Err(0xD32);
+                }
+            }
+            if via_out_acc[n_groups] != preload {
+                return Err(0xD32);
+            }
+        }
     }
     Ok(())
 }

src/simd_masking_ops.rs

@@ -935,11 +935,12 @@ pub fn mask_gather_u32(src: &[u64], src_rows: usize, index: &[u32], out_words: &
 /// (union), so repeats are harmless and order-independent — the same
 /// reason `vsa_bundle`-shaped accumulation is safe under reordering.
 ///
-/// `out_words[..out_rows.div_ceil(64)]` is **fully overwritten**, not
-/// OR-ed into an existing result: it is zeroed first, then every scattered
-/// bit is set. A caller composing this into an accumulating pipeline
-/// combines the *result* with `mask_or`/`mask_or_assign`, not by pre-seeding
-/// `out_words`.
+/// `out_words[..out_rows.div_ceil(64)]` is **accumulated into, not
+/// overwritten**: every scattered bit is OR-ed into whatever `out_words`
+/// already holds, and a bit set before the call that this call does not
+/// itself scatter to stays set. The caller zeroes `out_words` once before
+/// the first call in a sequence; repeated calls (e.g. one per source batch)
+/// compose as a running union without re-zeroing between them.
 ///
 /// **An out-of-range target (`index[i] >= out_rows`) is silently dropped**,
 /// not an error — the same zero-fallback contract as [`mask_gather_u32`]'s
@@ -993,11 +994,8 @@ pub fn mask_scatter_or_u32(src: &[u64], index: &[u32], out_words: &mut [u64], ou
         out_word_count
     );
 
-    // Zero first, whole buffer — same full-overwrite convention as every
-    // other writer in this module.
-    for w in out_words.iter_mut() {
-        *w = 0;
-    }
+    // Accumulate: OR scattered bits into whatever the caller already has in
+    // `out_words`. The caller zeroes once before the first call.
     for (w, &word) in src.iter().take(src_words).enumerate() {
         let base = w * 64;
         let mut bits = word;
@@ -1037,8 +1035,10 @@ pub fn mask_scatter_or_u32(src: &[u64], index: &[u32], out_words: &mut [u64], ou
 /// selected population and has no notion of a register. Same word
 /// "group", two unrelated shapes; do not conflate them.
 ///
-/// `out` is **fully overwritten**, not accumulated into an existing
-/// result: it is zeroed first. **A key at or past `out.len()` is dropped,
+/// `out` is **accumulated into, not overwritten**: contributions are
+/// added to whatever `out` already holds, so the caller zeroes `out` once
+/// before the first call in a sequence rather than this function doing it.
+/// **A key at or past `out.len()` is dropped,
 /// not an error** — the zero-fallback contract shared by
 /// [`mask_gather_u32`]/[`mask_scatter_or_u32`]: a key naming no group in
 /// `out` is not a group, the same way an unminted classid is not a class.
@@ -1100,9 +1100,8 @@ pub fn masked_group_sum_i32(mask_words: &[u64], keys: &[u32], values: &[i32], ou
         words
     );
 
-    for o in out.iter_mut() {
-        *o = 0;
-    }
+    // Accumulate: add into whatever `out` already holds. The caller zeroes
+    // once before the first call.
     for (w, &word) in mask_words.iter().take(words).enumerate() {
         let base = w * 64;
         let mut bits = word;
@@ -1145,9 +1144,10 @@ pub fn masked_group_sum_i32(mask_words: &[u64], keys: &[u32], values: &[i32], ou
 /// to avoid — one fused scan over the selected rows costs no more than the
 /// naive two-hop lookup per selected row, with no second array in between.
 ///
-/// `out` is fully overwritten (zeroed first); overflow wraps the same way
-/// as [`masked_group_sum_i32`] (widened to `i64`, `wrapping_add`), and the
-/// mask tail is clamped identically.
+/// `out` is accumulated into (not zeroed by this function) — the caller
+/// zeroes `out` once before the first call, same as [`masked_group_sum_i32`];
+/// overflow wraps the same way as [`masked_group_sum_i32`] (widened to
+/// `i64`, `wrapping_add`), and the mask tail is clamped identically.
 ///
 /// # Panics
 ///
@@ -1181,9 +1181,8 @@ pub fn masked_group_sum_i32_via(mask_words: &[u64], index: &[u32], remap: &[u32]
         words
     );
 
-    for o in out.iter_mut() {
-        *o = 0;
-    }
+    // Accumulate: add into whatever `out` already holds. The caller zeroes
+    // once before the first call.
     for (w, &word) in mask_words.iter().take(words).enumerate() {
         let base = w * 64;
         let mut bits = word;
@@ -4208,9 +4207,9 @@ mod tests {
     fn mask_scatter_or_u32_empty_index_writes_nothing() {
         let src: [u64; 0] = [];
         let index: [u32; 0] = [];
-        let mut out = [0xFFFF_FFFF_FFFF_FFFFu64; 1];
+        let mut out = [0u64; 1]; // caller zeroes before the first call
         mask_scatter_or_u32(&src, &index, &mut out, 10);
-        assert_eq!(out[0], 0, "no source rows selected ⇒ output cleared, nothing set");
+        assert_eq!(out[0], 0, "no source rows selected ⇒ output unchanged, nothing set");
     }
 
     #[test]
@@ -4232,10 +4231,12 @@ mod tests {
                 .collect();
             let want = bits_to_words(&naive_scatter(&src_bits, &index, out_rows));
             let out_words = out_rows.div_ceil(64);
-            let mut out = vec![0xFFFF_FFFF_FFFF_FFFFu64; out_words + 1]; // dirty, over-long
+            // Caller zeroes once before the first call; over-long by one word
+            // to prove the surplus word is left untouched, not cleared by us.
+            let mut out = vec![0u64; out_words + 1];
             mask_scatter_or_u32(&src, &index, &mut out, out_rows);
             assert_eq!(&out[..want.len()], &want[..], "scatter mismatch at n={n}");
-            assert_eq!(out[out_words], 0, "surplus word must be cleared at n={n}");
+            assert_eq!(out[out_words], 0, "surplus word is untouched (stays as the caller left it) at n={n}");
         }
     }
 
@@ -4266,6 +4267,26 @@ mod tests {
         assert_eq!(out[0], 1u64 << 3);
     }
 
+    #[test]
+    fn mask_scatter_or_u32_accumulates_into_a_preloaded_out_buffer() {
+        // A bit the call never scatters to must survive; the call's own
+        // contribution must land alongside it. This must FAIL if the old
+        // whole-buffer zeroing is restored (bit 7 would be cleared).
+        let src = [0b1u64]; // row 0 selected
+        let index = [3u32]; // scatters to bit 3
+        let mut out = [1u64 << 7]; // pre-set bit 7, not touched by this call
+        mask_scatter_or_u32(&src, &index, &mut out, 8);
+        assert_eq!(out[0], (1u64 << 3) | (1u64 << 7), "pre-existing bit 7 must survive alongside the new bit 3");
+    }
+
+    #[test]
+    fn mask_scatter_or_u32_a_second_call_with_a_different_mask_unions_on_top() {
+        let mut out = [0u64; 1];
+        mask_scatter_or_u32(&[0b1u64], &[2u32], &mut out, 8);
+        mask_scatter_or_u32(&[0b1u64], &[5u32], &mut out, 8);
+        assert_eq!(out[0], (1u64 << 2) | (1u64 << 5), "two calls union, the second does not erase the first");
+    }
+
     #[test]
     #[should_panic(expected = "out_words.len()")]
     fn mask_scatter_or_u32_rejects_short_out_buffer() {
@@ -4302,7 +4323,7 @@ mod tests {
         let mask: [u64; 0] = [];
         let keys: [u32; 0] = [];
         let values: [i32; 0] = [];
-        let mut out = [123i64; 4]; // garbage, must be cleared
+        let mut out = [0i64; 4]; // caller zeroes before the first call
         masked_group_sum_i32(&mask, &keys, &values, &mut out);
         assert_eq!(out, [0, 0, 0, 0]);
     }
@@ -4327,10 +4348,15 @@ mod tests {
             // Signed values spanning both sides of zero.
             let values: Vec<i32> = (0..n).map(|_| (splitmix(&mut seed) as i32) / 2).collect();
             let want = naive_group_sum(&mask_bits, &keys, &values, n_groups);
-            let mut out = vec![-999i64; n_groups + 1]; // garbage, and one extra slot no key ever hits
+            // Caller zeroes once before the first call; one extra slot no
+            // key ever hits, to prove it is left untouched, not cleared.
+            let mut out = vec![0i64; n_groups + 1];
             masked_group_sum_i32(&mask, &keys, &values, &mut out);
             assert_eq!(&out[..n_groups], &want[..], "group sum mismatch at n={n}");
-            assert_eq!(out[n_groups], 0, "an unreferenced group slot must be zero, not garbage, at n={n}");
+            assert_eq!(
+                out[n_groups], 0,
+                "an unreferenced group slot is untouched (stays as the caller left it) at n={n}"
+            );
         }
     }
 
@@ -4365,6 +4391,28 @@ mod tests {
         assert_eq!(out, [10, 20], "the out-of-range key contributes nothing");
     }
 
+    #[test]
+    fn masked_group_sum_i32_accumulates_into_a_preloaded_out_buffer() {
+        // Slot 1 starts pre-loaded and is never touched by this call; slot 0
+        // starts pre-loaded and IS the call's target. This must FAIL if the
+        // old whole-buffer zeroing is restored (both would reset to 0 first).
+        let mask = [0b1u64]; // row 0 selected
+        let keys = [0u32]; // routes to slot 0
+        let values = [7i32];
+        let mut out = [5i64, 42i64]; // slot 0 preloaded 5, slot 1 preloaded 42
+        masked_group_sum_i32(&mask, &keys, &values, &mut out);
+        assert_eq!(out[0], 12, "slot 0: preload 5 + contribution 7 = 12");
+        assert_eq!(out[1], 42, "slot 1 is untouched, must survive exactly as preloaded");
+    }
+
+    #[test]
+    fn masked_group_sum_i32_a_second_call_with_a_different_mask_sums_on_top() {
+        let mut out = [0i64; 2];
+        masked_group_sum_i32(&[0b1u64], &[0u32], &[10i32], &mut out);
+        masked_group_sum_i32(&[0b1u64], &[0u32], &[3i32], &mut out);
+        assert_eq!(out, [13, 0], "two calls sum, the second does not erase the first's contribution");
+    }
+
     #[test]
     #[should_panic(expected = "keys/values length mismatch")]
     fn masked_group_sum_i32_rejects_mismatched_keys_and_values() {
@@ -4408,7 +4456,7 @@ mod tests {
             let mut want = vec![0i64; n_groups];
             masked_group_sum_i32(&mask, &keys, &values, &mut want);
 
-            let mut got = vec![-1i64; n_groups];
+            let mut got = vec![0i64; n_groups]; // caller zeroes before the first call
             masked_group_sum_i32_via(&mask, &index, &remap, &values, &mut got);
             assert_eq!(got, want, "via mismatched the plain two-hop-materialised form at n={n}");
         }
@@ -4484,11 +4532,34 @@ mod tests {
                 want[k] = want[k].wrapping_add(values[i] as i64);
             }
         }
-        let mut got = vec![-1i64; n_groups];
+        let mut got = vec![0i64; n_groups]; // caller zeroes before the first call
         masked_group_sum_i32_via(&mask, &index, &remap, &values, &mut got);
         assert_eq!(got, want);
     }
 
+    #[test]
+    fn masked_group_sum_i32_via_accumulates_into_a_preloaded_out_buffer() {
+        // Slot 1 is preloaded and never targeted; slot 0 is preloaded and IS
+        // the resolved target. Must FAIL if whole-buffer zeroing returns.
+        let mask = [0b1u64]; // row 0 selected
+        let index = [0u32]; // partner 0
+        let remap = [0u32]; // partner 0 -> group 0
+        let values = [7i32];
+        let mut out = [5i64, 42i64];
+        masked_group_sum_i32_via(&mask, &index, &remap, &values, &mut out);
+        assert_eq!(out[0], 12, "group 0: preload 5 + contribution 7 = 12");
+        assert_eq!(out[1], 42, "group 1 is untouched, must survive exactly as preloaded");
+    }
+
+    #[test]
+    fn masked_group_sum_i32_via_a_second_call_with_a_different_mask_sums_on_top() {
+        let remap = [0u32];
+        let mut out = [0i64; 1];
+        masked_group_sum_i32_via(&[0b1u64], &[0u32], &remap, &[10i32], &mut out);
+        masked_group_sum_i32_via(&[0b1u64], &[0u32], &remap, &[3i32], &mut out);
+        assert_eq!(out, [13], "two calls sum, the second does not erase the first's contribution");
+    }
+
     #[test]
     #[should_panic(expected = "index/values length mismatch")]
     fn masked_group_sum_i32_via_rejects_mismatched_index_and_values() {