simd masking ops: address-only vocabulary, survival conditions, key-run distinct fold

The five data-indexed primitives no longer describe themselves in
foreign-key / join / table terms: parameters are `index` and `table`,
docs speak of addresses and populations. `mask_gather_u32` and
`mask_scatter_or_u32` carry their survival conditions — a gather reads
only resident state into a tile-local output; a scatter writes only the
demanded sink or the accumulator of the fold whose scalar leaves.

New: `masked_key_run_count_u32` + `KeyRunCarry` — on a key-clustered
lane, the distinct count over selected elements as a run fold with a
two-word carry and no population-sized set. Documented as over-counting
on an unclustered lane; parity 0xD50 threads the carry across uneven
tiles against a seen-set reference.

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

Author: claude

.claude/blackboard.md

@@ -3276,3 +3276,5 @@ Loose ends: the general strided path still gathers scalar (correct — at row
 strides ≥ a cache line a hardware gather buys nothing, per the doc); a
 `stride_bytes == 8` twin for `u64` lanes does not exist yet because no caller
 compares `u64` lanes.
+
+2026-09-21 (materialisation ruling): the five data-indexed primitives are re-documented in ADDRESS terms only — `index`/`table` parameters, no foreign-key / join / semijoin / table-name vocabulary; `mask_gather_u32` and `mask_scatter_or_u32` now carry their SURVIVAL CONDITIONS (gather: source must be resident state, output tile-local; scatter: destination must be the demanded sink or the accumulator of the fold whose scalar leaves). Sixth arm of the 0xDxx group: `masked_key_run_count_u32(keys, mask_words, &mut KeyRunCarry)` — on a key-clustered lane the distinct count over selected elements as a two-word-carry run fold, no population-sized set; parity `0xD50` threads the carry across uneven tiles against a seen-set reference. Not exact on an unclustered lane by construction (documented; unit test pins the over-count).

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

@@ -25,8 +25,8 @@
 //! permutation/scatter family (`mask_gather_u32`/`mask_scatter_or_u32`/
 //! `masked_group_sum_i32`/`masked_group_sum_i32_via`, for
 //! lance-graph-mask-risc's Gather/ScatterOr/GroupSum verbs); `0xD3x` the
-//! fk-indirected `masked_group_sum_i32_via` (two-hop zero-fallback); `0xD4x`
-//! `eq_u32_via_to_mask` (the same fk lane, packed as a predicate rather than
+//! index-addressed `masked_group_sum_i32_via` (two-hop zero-fallback); `0xD4x`
+//! `eq_u32_via_to_mask` (the same index lane, packed as a predicate rather than
 //! folded into a sum). `main.rs` (native / qemu) and
 //! `selfcheck()` (the wasm cdylib export, driven by `run.mjs`) both call
 //! [`run`].
@@ -39,10 +39,10 @@ use ndarray::simd::{
     lt_u8_to_mask, mask_all, mask_and, mask_and_assign, mask_andnot, mask_andnot_assign, mask_any, mask_gather_u32,
     mask_not, mask_not_assign, mask_or, mask_or_assign, mask_scatter_or_u32, mask_set_range, mask_shift_morton,
     mask_ternlog, mask_ternlog_assign, mask_xor, mask_xor_assign, masked_group_sum_i32, masked_group_sum_i32_via,
-    masked_max_i32, masked_min_i32, masked_strided_group_sum, masked_sum_i32, ne_i32_to_mask, ne_i32_to_mask_under,
-    ne_u32_to_mask, ne_u32_to_mask_under, ne_u64_to_mask, ne_u8_to_mask, ternary_match_strided_to_mask,
-    ternary_match_u32_to_mask, ternary_match_u32_to_mask_under, ternary_match_u64_to_mask,
-    ternary_match_u64_to_mask_under, ternlog, I32x16, MortonDir, U32x16, U64x8,
+    masked_key_run_count_u32, masked_max_i32, masked_min_i32, masked_strided_group_sum, masked_sum_i32, ne_i32_to_mask,
+    ne_i32_to_mask_under, ne_u32_to_mask, ne_u32_to_mask_under, ne_u64_to_mask, ne_u8_to_mask,
+    ternary_match_strided_to_mask, ternary_match_u32_to_mask, ternary_match_u32_to_mask_under,
+    ternary_match_u64_to_mask, ternary_match_u64_to_mask_under, ternlog, I32x16, KeyRunCarry, MortonDir, U32x16, U64x8,
 };
 
 /// Number of check groups [`run`] executes (for the log line only).
@@ -1335,7 +1335,7 @@ fn check_gather_scatter_group() -> Result<(), u32> {
         }
 
         // ── eq_u32_via_to_mask ────────────────────────────────────────────
-        // A predicate evaluated through the same fk lane `masked_group_sum_i32_via`
+        // A predicate evaluated through the same index lane `masked_group_sum_i32_via`
         // uses for its key, but packed into a bitmask rather than folded into a
         // sum: `fk[i] < foreign.len() && foreign[fk[i]] == v`.
         let foreign_len = 9usize;
@@ -1360,6 +1360,37 @@ fn check_gather_scatter_group() -> Result<(), u32> {
         if via_mask != want_via_mask {
             return Err(0xD40);
         }
+
+        // ── masked_key_run_count_u32 ─────────────────────────────────────
+        // A key-clustered lane (sorted with repeats), folded in uneven tiles
+        // with the carry threaded through; the reference is a plain
+        // seen-set over the selected elements — the population-sized state
+        // the fold replaces on a clustered lane.
+        let mut keys: Vec<u32> = (0..n).map(|_| (rng.next() % 23) as u32).collect();
+        keys.sort_unstable();
+        let sel: Vec<bool> = (0..n).map(|_| rng.next().is_multiple_of(3)).collect();
+        let sel_bits = reference_mask(n, nw, |i| sel[i]);
+        let mut carry = KeyRunCarry::default();
+        let mut got = 0usize;
+        let mut start = 0usize;
+        let tile = 37usize;
+        while start < n {
+            let end = (start + tile).min(n);
+            let mut tile_bits = vec![0u64; (end - start).div_ceil(64).max(1)];
+            for i in start..end {
+                if sel[i] {
+                    tile_bits[(i - start) / 64] |= 1 << ((i - start) % 64);
+                }
+            }
+            got += masked_key_run_count_u32(&keys[start..end], &tile_bits, &mut carry);
+            start = end;
+        }
+        got += carry.finish();
+        let want: std::collections::BTreeSet<u32> = (0..n).filter(|&i| sel[i]).map(|i| keys[i]).collect();
+        if got != want.len() {
+            return Err(0xD50);
+        }
+        let _ = sel_bits;
     }
     Ok(())
 }

src/simd.rs

@@ -828,6 +828,7 @@ pub use crate::simd_masking_ops::{
     mask_xor_assign,
     masked_group_sum_i32,
     masked_group_sum_i32_via,
+    masked_key_run_count_u32,
     masked_max_i32,
     masked_min_i32,
     masked_strided_group_sum,
@@ -843,6 +844,7 @@ pub use crate::simd_masking_ops::{
     ternary_match_u32_to_mask_under,
     ternary_match_u64_to_mask,
     ternary_match_u64_to_mask_under,
+    KeyRunCarry,
     MortonDir,
 };
 // The popcount that closes the loop on the masks above: `mask_count` in ABI