feat(serialize): opt-in bounded-memory zstd encoder profile (#79)

[oss-amikos]

Summary

Fixes #79.

Encode reuses one shared zstd encoder per compression mode, and each encoder keeps one worker per GOMAXPROCS. A level-15 worker holds about 36 MB of match tables, so a 16-CPU process retained about 560 MB after its first encode. Until now the only way to shrink that was a lower compression level.

This PR adds an opt-in bounded-memory encoder profile. It keeps a single worker at the same compression level, and the output bytes are identical.

Status: Verified ✓ (quick-260925-b7m, hold-out expectations E1–E11 all pass)

Changes

Encoder profile

• New EncoderProfile type: EncoderProfileDefault (today's behaviour) and EncoderProfileBoundedMemory.
• The bounded profile is WithEncoderConcurrency(1) + WithLowerEncoderMem(true). The window size is unchanged, so output is byte-identical to the default profile at every level.
• The shared encoder cache is keyed by (zstd mode, profile), so the two profiles never share an instance. It holds at most 4 × 2 entries.

Selecting it

• WithEncoderProfile(p) is a ConfigOption. Every encode path that reads the index config uses it: Encode, WriteSidecar, EncodeToMetadata, S3 sidecars.
• WithEncodeProfile(p) is an EncodeOption that overrides the config per call, including an explicit EncoderProfileDefault.
• The profile is runtime-only and never serialized. A decoded index reads EncoderProfileDefault. Wire format stays v11.
• Unknown profile values are rejected by the option, by config validation and by the encode call.

CLI

• gin-index build, extract and experiment gain -low-memory. extract passes the profile per call, because a decoded index always carries the default.

Benchmarks and docs

• BenchmarkEncoderProfile covers both profiles × levels 15 and 3 × small and high-cardinality fixtures × cold and repeated runs. It reports retained MB, allocations, time and compressed size.
• make bench-encoder-profile runs it at GOMAXPROCS 1, 4 and 16. Results are in docs/encoder-profile-benchmarks.md.
• README has a new "Encoder memory profile" subsection with the trade-off. CHANGELOG has an Unreleased entry, and CLAUDE.md is updated.

Retained heap after the first level-15 encode:

GOMAXPROCS	Default	Bounded
1	51 MB	42 MB
4	153 MB	42 MB
16	561 MB	42 MB

Review round

A high-effort self-review of the first commit found five issues; all are fixed in the second commit:

• The byte-identity test now covers a payload of more than 128 KB, so the multi-block path where low-memory buffers apply is tested.
• Forced GCs are out of the cold benchmark's timed region, and the cold timings were re-measured.
• -low-memory is added to extract and experiment -o.
• The cache-key and eviction helpers are deduplicated.
• The benchmark serializes each payload once.

Key files: serialize.go, gin.go, cmd/gin-index/main.go, cmd/gin-index/experiment.go, serialize_profile_test.go, serialize_concurrency_test.go, benchmark_test.go, Makefile, README.md, CHANGELOG.md, docs/encoder-profile-benchmarks.md

Requirements Addressed

• ISSUE-79: the bounded profile's level-15 output decodes to the same index, with decoder limits unchanged.
• ISSUE-79: mixed-profile and mixed-level concurrent encodes are race-free.
• ISSUE-79: benchmarks run at GOMAXPROCS 1, 4 and 16, cold and repeated, at levels 15 and 3, on small and high-cardinality fixtures.
• ISSUE-79: the memory, time and size trade-off is documented.

Verification

• go build ./... and go vet ./... pass
• make lint: 0 issues
• go test -race -short ./... passes in all packages
• Full suite via gotestsum (./... ./testdata/phase20): 1199 tests pass, 1 pre-existing skip (missing testdata/test.parquet)
• make bench-encoder-profile ran at GOMAXPROCS 1, 4 and 16
• Note: make test exits non-zero in the authoring container only because that Go toolchain lacks go tool covdata for -coverprofile. No tests failed. CI's runner has the tool.

Key Decisions

• The per-call option overrides the config option, mirroring WithEncodeSignals / WithSignals.
• The profile is a named enum, not a worker count. That keeps the cache bounded and keeps klauspost's pool model out of the public API.
• Bounded encoders are cached like default ones. About 42 MB is the level-15 floor, so it is paid once rather than per call.
• The default profile is unchanged. Capping default workers would silently reduce parallel-encode throughput on large hosts. It is logged as a deferred follow-up with these numbers.
• The window size is left alone, so byte-identical output holds as a tested invariant and the profile is purely a memory knob.

Review round 2 (local multi-agent review, 15 findings)

Summary

 WriteSidecar(path, idx)
 EncodeToMetadata(idx)
 RebuildWithIndex(path, idx)
 S3Client.WriteSidecar(ctx?, bucket, key, idx)
+  ...opts ...EncodeOption   // e.g. WithEncodeProfile; a decoded index always carries Default

• New TestEncoderProfileBoundedUsesSingleWorker reflects into the zstd encoder and asserts one worker and low-memory buffers. Before this, dropping both options passed every test.
• experiment -low-memory without -o now warns instead of doing nothing.
• Memory prose aligned with the benchmark tables: about 34 MB per additional worker, about 560 MB at 16 CPUs, about 42 MB bounded.
• Tautological wire-format check replaced with a byte-equality check across profiles. Mixed-profile concurrency test regained its decode-and-re-encode check.
• Doc comments, README cache-key and level-3 wording, CHANGELOG, and the klauspost pin in CLAUDE.md corrected.

Evidence

• Before: removing WithEncoderConcurrency(1) / WithLowerEncoderMem(true) from newZstdEncoder left the suite green.
  After: TestEncoderProfileBoundedUsesSingleWorker fails on channel capacity or lowMem.
• go test -race -short . ./cmd/... passes. make lint reports 0 issues (Go 1.25.5 toolchain).

Merge Danger

Door: two-way. Trailing variadic parameters are additive; wire format stays v11.

Blast Radius: small. Only callers that store these functions in a typed variable with the old signature would need a change.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Dh45hVm1GJoj9sTGDah84X

---

Generated by Claude Code