feat: reference-parity swap_or_not_shuffle API and JS binding

[nazarhussain]

Motivation

Stacked on #558. Ports the full @chainsafe/swap-or-not-shuffle API into lodestar-z so Lodestar can consume it from the zig bindings — the surface ChainSafe/lodestar#9263 uses. Zero behavioral divergence from the Rust package, with performance as the priority.

Description

Module (src/swap_or_not_shuffle) — line-faithful port of the reference lib.rs:

• innerShuffleList/shuffleList/unshuffleList with the reference's exact validation order (rounds==0 and len<=1 return before seed validation; seed errors take precedence over rounds errors) and error set; generic over element type so state_transition keeps using u64
• ComputeShuffledIndex with per-round pivot/source caching
• getCommitteeIndices, computeProposerIndex(Electra), computeSyncCommitteeIndices(Electra), ByteCount, SHUFFLE_ROUNDS_MAINNET/MINIMAL

Binding (bindings.shuffle) — identical names, argument order, return values, and error messages as the npm package:

• sync shuffleList/unshuffleList return a new Uint32Array without mutating the input
• asyncShuffleList/asyncUnshuffleList run on the libuv pool and resolve zero-copy via an external ArrayBuffer
• ComputeShuffledIndex class, the four committee-index functions, constants + ByteCount enum object
• Reference error strings verbatim (e.g. "Shuffling seed must be 32 bytes long") for sync throws and async rejections

Zero-divergence validation

• bindings/test/shuffle.test.ts ports the reference repo's own test suite, using an in-repo pure-TS reference implementation (bindings/test/shuffleReference.ts, deps inlined) as the oracle on random seeds — no dependency on the npm package. Out-of-range wrapping vectors are hardcoded from @chainsafe/swap-or-not-shuffle v1.2.1 output
• 2M indices × 90 rounds × 3 random seeds sweep (shuffle + unshuffle): zero divergence
• Zig unit tests carry the reference repo's fixed vectors (spec vector, proposer/sync-committee vectors)

Performance (darwin-arm64)

One-off comparison against the Rust npm package (v1.2.1) during development:

Benchmark	zig	rust
unshuffleList 100k	15.2 ms	19.9 ms
unshuffleList 2M	332 ms	318 ms (parity within noise; ReleaseFast: 301 vs 312 ms)
computeSyncCommitteeIndicesElectra 1M	5.4 ms	6.9 ms
computeProposerIndexElectra 1M	14.9 µs	24.9 µs

Note: pnpm prepare builds bindings with ReleaseSafe, which leaves the big-list shuffle ~4% behind the Rust package; ReleaseFast beats it. Left the project default untouched — worth a separate discussion.

Out of scope

computePtcIndices/computePtcIndicesForEpoch (the new functions ChainSafe/lodestar#9263 also needs) are still unmerged upstream (ChainSafe/swap-or-not-shuffle#24); they'll come as a follow-up once upstream settles, ported the same way.

🤖 Generated with Claude Code

[nazarhussain]

This will soon go away as we will support namepsace pub const and enum in the Zapi.