P1.3 follow-up: reproducibly measure zero-copy stream parsing's allocation payoff (concurrent-parse benchmark)

[joeldsouzax]

Follow-up to #30 (zero-copy stream parsing). Everything here must be reproducible — a committed benchmark + a documented command + pasted numbers, not a belief.

Why

#30 traded ~25% parse CPU (CodSpeed: controller_idx_sigs_1sig −27.7%, multi_group_controller_witness −21.7%) for fewer heap allocations (~N → 1 per multi-group message). The allocation reduction is proven (tests/allocation.rs, mutation-verified). But the payoff is unproven: no benchmark yet shows fewer allocations translating into a throughput or latency win anywhere. Single-threaded benches show a net regression (correct-but-slower). So "was #30 worth it?" is currently a belief, not a measured result — which violates the reproducibility bar.

Goal

Make "does the zero-copy allocation reduction actually pay off?" a reproducible measurement.

The measurement (the one place it should win)

Add a committed, deterministic benchmark that parses many small streams concurrently across N threads, comparing:

• branch (copy-once: 1 alloc/stream), vs
• origin/main behavior (per-group copy: N allocs/stream).

Under multi-thread allocator contention, N-allocs-per-stream should hit the global allocator lock far more than 1-alloc-per-stream — this is the scenario where fewer allocations converts to throughput. Measure wall-clock throughput and allocation counts at increasing thread counts (1, 2, 4, 8…).

Acceptance criteria (reproducible)

• A committed benchmark (criterion/CodSpeed-compatible) + a single documented command anyone can run.
• Before/after numbers pasted (branch vs origin/main behavior) across thread counts.
• A clear, re-runnable verdict:
  • Wins under concurrency → P1.3 · Zero-copy stream parsing #30 is vindicated as a concurrency/memory-pressure improvement; keep it, update the CHANGELOG with the measured win.
  • Shows nothing → P1.3 · Zero-copy stream parsing #30's lasting value is the safeguards + bug fixes, not the zero-copy; open a decision to revert the sync-path zero-copy (keep codec + safeguards).
• Consider also measuring no_std/constrained-allocator behavior if feasible.

Pointers

• tests/allocation.rs (alloc-count harness, thread-local counting allocator — reuse it).
• benches/stream.rs (stream_parse_scaling), CodSpeed on PR perf(#30): zero-copy stream parsing + test/coverage/mutation safeguards #63.

[joeldsouzax]

Verdict: VINDICATED — copy-once decisively beats the pre-#30 per-group copy, and the gap widens under concurrency.

Reproducible harness committed at examples/concurrent_parse.rs. One command:

cargo run --release --example concurrent_parse --features stream

What it measures

Two real, public, production arms parse the same 16-group ControllerIdxSigs stream — the only variable is the allocation pattern, no git checkout, no reimplemented parse logic:

• copy-once (this branch): groups() — copies the input into a shared Bytes once, then O(1)-slices every group. 2 allocs/stream.
• per-group (origin/main behavior): a parse_group() loop — parse_group_inner still does Bytes::copy_from_slice on every call, re-copying the shrinking remainder each step. This faithfully reproduces pre-P1.3 · Zero-copy stream parsing #30 Groups::next(): 32 allocs/stream + O(N²) total bytes copied.

A single-threaded armed counting allocator self-checks the 1-vs-N invariant (copy-once invariant to group count; per-group scales) before any timing runs. Timed passes run disarmed so the counter never perturbs wall-clock — without that gate, per-group's extra allocs would pay extra counter overhead and inflate copy-once's apparent win.

Numbers (14-core Apple M-series, release: lto, opt-level=3, codegen-units=1)

strategy     threads     streams/s   allocs/stream
copy-once          1       1984209               2
per-group          1        788426              32
copy-once          2       1979179               2
per-group          2       1054886              32
copy-once          4       5821357               2
per-group          4       1791295              32
copy-once          8      12695306               2
per-group          8       3272855              32

copy-once / per-group throughput ratio — 1t: 2.52× · 2t: 1.88× · 4t: 3.25× · 8t: 3.88×

copy-once wins at every thread count, and the advantage widens under contention: per-group throughput scales only ~4.2× across an 8× thread increase (788k → 3.27M streams/s) — the allocator-contention signature — while copy-once scales ~6.4× (1.98M → 12.7M).

Honesty notes

• The win has two sources here (fewer allocations and avoiding O(N²) remainder re-copying), and that is faithful to origin/main, which genuinely paid both.
• The 1-thread win (2.52×) does not contradict P1.3 · Zero-copy stream parsing #30's single-thread CodSpeed regression. That used a 2-group fixture, where O(N²) ≈ O(N) so the copy savings vanish and copy-once's refcount/get_or_insert overhead made it marginally slower. At K=16 the quadratic copying dominates and copy-once wins outright. The concurrency effect layers on top.
• These are wall-clock, machine-dependent numbers. The harness is a reproducible run-and-read measurement, not a CI regression gate (CodSpeed's single-core instruction-count simulator structurally cannot observe allocator contention — the exact effect under test).

Acceptance criteria

• Committed benchmark + single documented command anyone can run.
• Before/after numbers pasted (branch vs origin/main behavior) across thread counts.
• Clear, re-runnable verdict → VINDICATED; CHANGELOG updated with the measured win.
• no_std / constrained-allocator: deferred (threads require std; a constrained-allocator model needs a separate custom allocator — noted as follow-up).

Conclusion: #30's zero-copy stream parsing is vindicated as a concurrency / memory-pressure improvement. Keep it.

Design + plan: docs/superpowers/specs/2026-07-03-64-concurrent-parse-alloc-payoff-design.md, docs/superpowers/plans/2026-07-03-64-concurrent-parse-alloc-payoff.md.