simd: group_walk as a (group,row) visitor; add PowerSums power-sum fold

[AdaWorldAPI]

What

• Walker: the private group_walk now yields (group, row) and never sees a sink (groups: usize, fold: FnMut(usize, usize)). Its i64 slot was an accident of the first folds. All 15 existing folds were migrated mechanically (|k, i| out[k] = …, passing out.len()). No public signature changes.
• New: #[repr(C)] PowerSums { n: u64, sum: i64, sum_sq: u128 }, the exact degree-0/1/2 power sums, plus masked_group_power_sums_i32 / _via / _pair sharing one fold, all re-exported from ndarray::simd. No statistical vocabulary at this layer: what the sums mean is decided upstream (jc).
• Compile-time layout pin: size 32, offsets 0/8/16, alignment equal to align_of::<u128>(). That is 16 on x86_64/aarch64 and 8 on some cross targets; size and offsets are the same everywhere. It also checks the documented Σx row bound, (2^32-1)·2^31 ≤ i64::MAX.

Why this shape (measured before the change)

Scratch benchmark over 72 cells: resident/via/pair keys × mask density 1/50/100 % × K 1…65 536 × realistic/extreme values; median of 15 reps, two runs.

Comparison	Median ratio
Existing sum, new walker vs old	0.994×
Slot-generic walker vs visitor with a record sink	identical instruction stream (79 instructions)
Three separate lanes (SoA) vs one record (AoS)	1.095× overall, 1.37× at K = 65 536, up to 2.5× on pair keys
Three separate passes vs one record pass	2.17×

The record wins because it touches one cache line per row instead of three, and its hot loop has 2 stack reloads instead of 6. One cell is unexplained: SoA beats AoS by ~35 % on dense resident/via keys at K = 16. It reproduced in both runs; it is recorded and not investigated, since the decision doesn't depend on it.

Evidence

• 9 new tests against an independent per-row i128/u128 oracle:
  • resident and via at 7 lengths × sparse/half/dense masks;
  • pair keys, with both drop paths present;
  • an unreached group stays zero, while a cancelling group has n = 2;
  • agreement with the existing count and sum folds;
  • repeated calls accumulate;
  • an extreme fixture whose exact Σx² exceeds u64::MAX, asserted from the oracle before the kernel is checked;
  • 2^20 × i32::MIN in one group, exact;
  • two panic tests.
• Disable run (Σx² truncated to u64 inside the fold): exit 101, the 4 exactness tests red, the other 5 green. The ordinary randomized fixture also overflows a u64 square sum, so the width matters on realistic data, not only adversarial data.
• The existing group-family tests pass after the walker change alone: 35/35.
• Full cargo test --lib: 2516 passed, 32 ignored. Group doctests: 17/17. clippy --lib -D warnings and fmt are clean.

Not in this PR

• No codegen witness has been run on the real crate's symbols yet. The no-regression figure comes from a verbatim scratch copy of the walker.
• Next: mask-risc GroupFold::PowerSumsI32 + Out::PowerSums, reusing Value::GroupReduced. The R2IL vocabulary gets its byte only after that parity is green.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Ho2JosrXCnZPbB7RFssrse

---

Generated by Claude Code

Summary by CodeRabbit

• New Features
  • Added grouped power-sum reductions that calculate each group’s count, sum, and sum of squared values in one operation.
  • The reductions support direct keys, indirect keys, and composite key pairs, with results available through the SIMD masking operations interface.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Essentials

Run ID: 00a17340-3973-4a16-af20-16d25fc8521b

📥 Commits

Reviewing files that changed from the base of the PR and between b9f8e4e and 8334bb7.

📒 Files selected for processing (3)

• .claude/blackboard.md
• src/simd.rs
• src/simd_masking_ops.rs

Included review availability: This review used your included allowance. 2 included reviews remain after this review. Your included PR review attempts over the past 7 days set your current allowance at 5 reviews per hour.

---

📝 Walkthrough

Walkthrough

The shared group_walk interface now passes group and row indices to fold closures. Three masked power-sum kernels and the public PowerSums type add per-group count, sum, and squared-sum accumulation.

Changes

Masked Grouped Reductions

Layer / File(s)	Summary
Index-based group walker and existing folds src/simd_masking_ops.rs	group_walk now passes valid group and row indices to its fold closure. Existing sum, symmetric-sum, count, min, and max operations update their captured output slots.
Power-sum type, kernels, and validation src/simd_masking_ops.rs, src/simd.rs, .claude/blackboard.md	Adds PowerSums and resident-key, VIA-key, and pair-key kernels. The SIMD facade re-exports the new API. Tests cover arithmetic, accumulation, and input validation. The blackboard records implementation details and validation results.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant masked_group_power_sums_i32_via
  participant group_walk
  participant PowerSums
  Caller->>masked_group_power_sums_i32_via: Provide mask, index, table, values, and output
  masked_group_power_sums_i32_via->>group_walk: Supply group count and fold
  group_walk->>PowerSums: Pass group and row indices to update count, sum, and squared sum

Loading

Suggested reviewers: claude

Merge Risk: ⚪ Minimal · up to 8334b

The change adds grouped power sums while preserving the existing reduction interfaces. No concrete merge-blocking issue is established; merge after normal checks.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes both primary changes: the private group_walk visitor refactor and the addition of the PowerSums power-sum fold.
Docstring Coverage	✅ Passed	Docstring coverage is 97.06% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 34 functions across 2 files. (1 skipped: 1 …
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.

---

_{I hop through rows beneath the mask
Three sums gather as kernels pass
Count and squares join the stream
Wide numbers fit the scheme
I nibble clover, pleased with the task}

_{Comment @coderabbitai help to get the list of available commands.}