treedb: pool append-only key arena chunks

[snissn]

Objective

Pool append-only key arena chunks so copied non-inline keys do not repeatedly allocate fresh arena backing across append-only memtable reset/reuse cycles.

Refs #3558.

Scope

Includes:

• TreeDB/internal/memtable/append_only.go key-arena pool internals, lifecycle, stats.
• TreeDB/internal/memtable/append_only_pool_test.go key-arena pool/lifecycle/cap tests.
• Minimal TreeDB/caching stats/drop wiring and tests so the pool is observable and discarded during pressure/cold append-only transitions.

Excludes:

• TreeDB caching batch helper code.
• TreeDB zipper code.
• Durable/value-log semantics and on-disk formats.

Design

• Adds bounded strong-bin pooling for append-only key arena chunks, power-of-two classes from 2 KiB through 1 MiB.
• Caps package-level retained key-arena chunks at 64 MiB.
• Keeps the cold make([]byte, chunkCap) inside appendOnlyKeyArena.alloc, so profile attribution still shows real fresh allocation misses in the target function.
• Returns chunks to the pool on warm reset/reuse paths.
• Drops key-arena chunks on cold ReleaseDropEntries / ResetDropEntries paths.
• Drops the new key-arena pool along with existing append-only pools under memory pressure and cold memtable-mode transitions.
• Exposes cache/process stats for retained bytes, gets, puts, drops, drop bytes, and admission drops.

Correctness

Tests run locally:

GOWORK=off go test ./TreeDB/internal/memtable -run 'AppendOnly|Arena|Iterator' -count=1
# ok   github.com/snissn/gomap/TreeDB/internal/memtable  1.073s

GOWORK=off go test ./TreeDB/caching -run 'AppendOnly|MemoryStats|Dataset|Checkpoint' -count=1
# ok   github.com/snissn/gomap/TreeDB/caching  21.481s

New/updated coverage:

• key arena size-class selection;
• bounded pool retention/accounting;
• strong-bin retention across GC;
• reuse after hard reset;
• cold release/drop path avoiding retained key chunks;
• admission drops when the retain budget is full;
• caching stats mirror coverage;
• memory-pressure and cold-mode pool drops.

Performance Gate Status

The required 10M durable paired gate is deferred to the main orchestrator by request. Do not use local 10M artifacts from this branch for merge decisions.

Reason: another worker launched concurrent 10M unified-bench gates on the same machine while local paired gates were running. I stopped the in-progress #3558 gate and am treating the partial artifact roots as contaminated/aborted:

• /tmp/gomap_3558_key_arena_gate_20260706_063601
• /tmp/gomap_3558_key_arena_gate_20260706_064234
• /tmp/gomap_3558_key_arena_gate_20260706_064521

Required deferred command shape for the orchestrator:

GOWORK=off GOMAXPROCS=8 TMPDIR="$out/tmp" ./bin/unified-bench \
  -profile durable \
  -dbs treedb \
  -keys 10000000 \
  -valsize 128 \
  -batchsize 8000 \
  -test dataset_write_random,dataset_write_sorted \
  -checkpoint-between-tests \
  -treedb-journal-lanes=1 \
  -progress=false \
  -profile-dir "$out/profiles" \
  -path-label native-fastpath \
  -format markdown
GOWORK=off ./bin/benchprof -profiles-dir "$out/profiles"

Acceptance remains: materially reduce appendOnlyKeyArena.alloc flat allocation objects/space, target >=50% allocation-object reduction if feasible, with no >5% throughput regression in either dataset-write workload on a clean sequential paired gate against current origin/main.

Status

Draft / not merge-ready until the main orchestrator provides clean sequential paired benchmark evidence and the PR body is updated with those results.

AI reviews are not requested yet because the PR is intentionally waiting on the deferred performance gate.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 63e7b037-48b2-4fd8-b141-79e81bc11d61

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/3558-key-arena-pool

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[snissn]

Clean sequential coordinator gate for #3558 / #3569:

Artifact root: /tmp/gomap_3558_key_arena_clean_gate_20260706_070335
Baseline: origin/main 6f2d94def23551ccb1c6bdb35514bc72733d88e0
Candidate: 4178d916c2a2e61e7380f2e1c051e8ef890df31e
Command shape: durable 10M TreeDB, -test dataset_write_random,dataset_write_sorted, -checkpoint-between-tests, -treedb-journal-lanes=1, -profile-dir, then benchprof.

Throughput was not a blocker in this noisy run:

test	main ops/sec	PR ops/sec	delta
dataset_write_random	40,627	67,473	+66.0%
dataset_write_sorted	139,606	144,277	+3.3%

Total allocation-profile size also moved in a favorable direction:

test	main alloc space / objects	PR alloc space / objects	delta
dataset_write_random	14,302 MiB / 596,258	13,603 MiB / 528,223	-699 MiB / -68,035
dataset_write_sorted	10,591 MiB / 644,456	10,535 MiB / 373,238	-56 MiB / -271,218

However, the specific issue gate does not pass. Direct pprof focus on appendOnlyKeyArena shows the target function is not reduced by >=50% in this clean focused gate:

alloc_objects focus=appendOnlyKeyArena

dataset_write_random main: 1,282 objects in (*appendOnlyKeyArena).alloc
dataset_write_random PR:   1,795 objects in (*appendOnlyKeyArena).alloc
dataset_write_sorted main: no matching samples
dataset_write_sorted PR:   no matching samples

So I am leaving this PR draft / gate-blocked for now rather than promoting or merging it. The next useful action is either to revise the benchmark/issue target if the earlier full-suite attribution was sampling/order-sensitive, or revise this branch against a command shape that reproduces and materially reduces appendOnlyKeyArena.alloc on current origin/main.