perf(#30): zero-copy stream parsing + test/coverage/mutation safeguards

[joeldsouzax]

P1.3 · Zero-copy stream parsing (#30)

Makes the stream/ group parser slice a shared bytes::Bytes instead of Bytes::copy_from_slice, cutting heap allocations per multi-group message from ~N to 1 (0 on the codec path). Public API is unchanged (non-breaking).

Read this first — honest framing. This is not a throughput win. It trades a little per-parse CPU (Arc refcounting + indirection) for fewer allocations. CodSpeed measures that CPU as a ~22–28 % parse regression on small streams (see below). Merging is a deliberate choice: fewer allocations (allocator pressure / fragmentation / no_std) is the goal, and the fixed overhead amortizes toward parity as streams grow. If you want raw parse speed at CESR sizes, main is faster.

Research → design → plan are on the issue and in docs/superpowers/. Decision (5-track research sweep): keep the hand-rolled parser (no winnow/nom), use Bytes + .slice() (no lifetime leaks into the public API), defer borrowed Matter<'a>.

What changed

• All ~18 group parsers take &Bytes and return (T, Bytes) via .slice() — skip_* loops byte-for-byte unchanged; only copy→slice + signature differ. Dispatch rebuilt on Bytes (all 44 code→variant mappings verified identical).
• Codec (decode_v1/v2): non-quadlet path parses zero-copy on success; the NeedBytes restore reclaims the buffer in place (fixed a dead try_into_mut that always copied). Banned saturating_mul/unwrap_or → checked_mul.
• unwrap_generic_group and Groups/GroupsV2 slice a once-copied region instead of re-copying.
• QuadletGroup::to_bytes() — O(1) shared-buffer accessor (additive).

Performance — measured, honestly

• Allocations (the win): iterating an N-group message allocates a count invariant to N — proven by tests/allocation.rs; a per-group-copy regression makes it scale (8 groups: 2 → 18 allocs; 760 → 4264 bytes).
• Parse CPU (the cost): CodSpeed on this PR — controller_idx_sigs_1sig −27.7 %, multi_group_controller_witness −21.7 % (aggregate ≈ −24.7 %). Confirmed by a local origin/main-vs-branch run (single-group +58 % at N=1). The Arc/indirection overhead is per-parse; it amortizes — per-group cost is ~equal to main by N≥16 groups (both are O(N); main was never O(N²)).
• Not claimed: any throughput improvement. This echoes the P1.2 · Base64 fast path (CESR inner loop) #29 finding — at CESR sizes the parse is overhead-bound, so copy-vs-slice doesn't move wall-clock; the benefit is allocation count, which single-threaded benchmarks don't reward.

Test / coverage / mutation safeguards (the bulk of this PR)

Behavioral tests can't see "correct-but-copying" regressions, so this adds property-level guards:

• Aliasing tests — every parser shape asserts its output points inside the parent buffer; each mutation-proven.
• Allocation-count test — thread-local counting allocator; asserts allocs invariant to group count. Runner-robust (cargo test / --test-threads=1 / nextest).
• cargo-mutants (dev shell, on-demand): swept the core stream logic — 161 mutants, 100 % of non-equivalent mutants killed (2 full sweeps). Found and closed a real gap: the entire V2 dispatch table + codec quadlet mapping was untested (~35 arms deletable with everything green).
• Coverage — on-demand nix build .#coverage (llvm-cov) + post-merge workflow (mirrors bombay). Not gating.
• GroupsV2 — previously zero coverage; now covered.

Bug fixes included (valuable independent of the perf tradeoff)

• Banned saturating_mul/unwrap_or arithmetic → checked_mul (quadlet_group, codec).
• Codec NeedBytes/Err restore now actually reclaims in place (was silently copying).

Constraints held

no_std + alloc and wasm32 green; no new deps; no unwrap/expect/panic/as in production; strict clippy clean; nix flake check green.

Note: the CodSpeed check is red by design — it's the accepted allocation-for-CPU tradeoff, not a mistake. Acknowledge/annotate on CodSpeed before merge.

Closes #30.

🤖 Generated with Claude Code

[codspeed-hq]

Merging this PR will degrade performance by 24.74%

❌ 2 (👁 2) regressed benchmarks
✅ 15 untouched benchmarks
🆕 4 new benchmarks

Performance Changes

	Benchmark	BASE	HEAD	Efficiency
🆕	stream_parse_scaling[1]	N/A	4.7 µs	N/A
🆕	stream_parse_scaling[16]	N/A	15.1 µs	N/A
🆕	stream_parse_scaling[256]	N/A	178.2 µs	N/A
🆕	stream_parse_scaling[64]	N/A	50.8 µs	N/A
👁	controller_idx_sigs_1sig	3 µs	4.1 µs	-27.68%
👁	multi_group_controller_witness	4.3 µs	5.5 µs	-21.67%

---

_{Comparing perf/30-zerocopy-stream-parsing (3170320) with main (856f6be)}