perf(fibre): decrease encoding memory usage by 8x

[Wondertan]

Important

Please read the summary carefully to understand the motivation behind such a change

Summary

Fibre's Reed-Solomon encoding is memory-hungry by nature: every in-flight encode keeps roughly 8× the blob size resident: one copy of the original data, three copies for parity rows, and four copies of FFT scratch space. With 128 MiB blobs and a dozen concurrent uploads(throughput agentic payments targets), that's more than ten gigabytes of large, short-lived buffers churning through the heap. On modestly-sized validator nodes, this is genuinely hard to fit.

The first attempt (#7069) assumed Go's sync.Pool would absorb the churn. It doesn't. sync.Pool is tied to the garbage collector, and buffers this large trigger collections frequently enough that the pool never actually retains anything. Every encode ends up allocating fresh, and freed pages linger long enough that resident memory grows to several times the live working set. Meanwhile, the GC's heap-doubling behavior stacks successive allocations on top of each other, pushing memory-constrained nodes into OOMs before the pool has a chance to help. Essentially, the Go runtime is not suitable for this type of encoding workflow, especially if the encoding fibre client is intended to be embedded by other processes.

However, the workload is a good fit for explicit memory management (and I would argue even requires it): allocations are large, predictable, and bound to a clear lifecycle event (the end of a blob's upload) rather than to GC timing. That's an unusual shape for a Go program, but it's the same shape embedded databases like pebble and badger deal with, and they reach for the same solution. This PR introduces a small slab allocator that owns fibre's encoding buffers directly, grows only when real demand appears, hands regions back to the OS when they stop being used, and is otherwise invisible to the GC.

The encoder retrieves these buffers via the new WorkAllocator interface added upstream in klauspost/reedsolomon#331, enabling full control over allocations for the work buffers during the encoding.

The allocator, its tradeoffs, and the reasoning behind each design choice are documented in fibre/internal/slab/DESIGN.md. It felt necessary to make a design document, given the complexity this may bring to the codebase.

Commits

The total number of changes is rather large, so they are split into two commits, and those commits should be reviewed independently. Most of those changes are auxiliary, like tests, benchmarks, and fuzzing, so hopefully the actual code review won't be that big of an issue. If changes are perceived as large, I can spend time sharding them further.

1. perf(fibre): slab-backed pool allocator for RS work + parity buffers — the allocator itself, with tests, benchmarks, a fuzzer, and the design doc.
2. feat(fibre): add RowAssembler for zero-allocation blob encoding — integration through RowAssembler / Assembly, which owns pooled storage across an encode and releases it incrementally as validators finish.

Result

On a 16 GiB node, memory usage sits at the theoretical floor: around 1.4 GiB for a single in-flight encode, and roughly 13–15 GiB for ten concurrent ones, comfortably within the box. Steady-state slab churn drops to a few MiB per minute as both pools warm up to the concurrency high-water mark and stay there.

Most of the stress testing focused on the largest blob size because that's where memory pressure actually shows up. However, the allocator is size-agnostic by design, and slabs grow to whatever deficit a request leaves behind and pack smaller rows into the same space, so small and medium blobs should benefit from the same retention and reuse properties without any special-casing. That said, the mixed-size path has seen less direct measurement than the homogeneous large-blob case, and fragmentation behavior under varied workloads is noted as a known area to keep an eye on in the design doc.

Closes #7085

[claude]

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review to trigger a review and subscribe this PR to future pushes, or @claude review once for a one-time review.

_{Tip: disable this comment in your organization's Code Review settings.}

[devin-ai-integration]

Devin Review found 1 potential issue.

View 6 additional findings in Devin Review.

[Wondertan]

Superseeded by #7159