Avoid duplicate internal-page materialization in leaf-pack publication

[snissn]

Follow-up to #3666 and PR #3709; descendant of the completed maintenance graph #3630.

Goal

Remove duplicate internal-page materialization from leaf-generation pack publication.

Done means the pack path prepares an immutable relocation plan before acquiring writeMu, exact basis revalidation still occurs before publication, the exclusive path binds committed page IDs and writes each internal page once without recursively decoding and rebuilding staged pages, and the paired performance and correctness gates below pass.

This is a single-node continuation of the #3666 workstream. It does not reopen #3630 or #3666.

Current Evidence

PR #3709 reduced the fixed leaf-pack apply cost on its accepted paired benchmark:

Metric	Before	After	Delta
pack apply	81.18 ms/op	47.59 ms/op	-41.38%, p=0.002
private copy	39.07 ms/op	19.50 ms/op	-50.1%
publish hold	40.87 ms/op	27.02 ms/op	-33.9%
PL-01 p95 / p99	baseline contract	1.05x / 0.97x	within the <=2x gate

The current implementation on origin/main at d1b2d909e still performs two representations of rewritten internal pages:

1. Private rewrite builds staged internal pages in a pager.NewOverlay.
2. After taking writeMu and revalidating the exact basis, cloneLeafGenerationPackStagedNode recursively calls staged Get, verifies checksums, parses internal entries, allocates committed pages, rewrites child references, and rebuilds nodes with node.Builder.

This second recursive decode/build is inside the exclusive publication window and is specific to leaf-pack relocation. Existing structured stage counters expose TreeRewriteTimeNanos, RelocationTimeNanos, page sync, registration, finalization, and related stages, but BenchmarkCompactStorageLeafPackMultiPass currently reports only coarse apply/copy/publish metrics.

Root-Cause Classification Gate

Before selecting or retaining the implementation, report all relevant ApplyStages fields in the existing multi-pass benchmark and collect a current pinned-CPU baseline.

Classification	Evidence	Required action
duplicate staged parse/build	TreeRewrite + Relocation dominate local CPU/wall and recursive staged-node cloning is exercised	implement prepared relocation templates as specified below
private rewrite dominates	TreeRewrite dominates while relocation is minor	optimize only a directly profiled duplicate materialization cost; retain the same gates
relocation is noise	relocation is too small to support the required gates	stop implementation, publish evidence, and keep this issue open for a newly profiled local fix
durability syscall/wait dominates	page/directory/meta sync dominates	treat it as an excluded adjacent lane; do not weaken or batch barriers in this issue

Instrumentation-only benchmark changes are allowed before the red test. The optimization itself must start from a deterministic failing test.

Required Fix

• During private rewrite, prepare an immutable relocation plan for every reachable staged internal page. The plan must preserve page type, entry ordering, keys, values, flags, and child-reference positions without assigning committed page IDs.
• Deduplicate shared staged pages by staged page ID. User root, system/collection root, and shared descendants must resolve through one plan entry and one final committed page.
• After acquiring writeMu, preserve the existing exact basis revalidation and retry/abort behavior. A failed revalidation must discard the entire plan; no committed page IDs or retired IDs from an aborted attempt may be reused.
• Only after successful revalidation, allocate committed IDs, resolve child references, set final page IDs/checksums, and write each prepared page once. The locked publication path must not recursively decode and rebuild staged internal nodes.
• Preserve existing page sync, directory sync, registration, collection-root publication, metadata finalization, source-generation pinning, poisoning, and cleanup ordering.
• Preserve the public stats/JSON surface. Add benchmark reporting for detailed stage fields without renaming or removing existing metrics.

An equivalent implementation is acceptable only if it proves the same no-recursive-rematerialization property and passes every gate below.

Test-Driven Development

• Add a deterministic red test or test-only counter/hook proving the current locked publication path recursively materializes staged internal pages, then assert the replacement path performs zero recursive staged internal-page rebuilds.
• Verify prepared and published pages are semantically equivalent for user roots, system/collection roots, multi-level trees, and shared child references.
• Verify each staged internal page maps to exactly one committed page and all rewritten child references target the mapped committed IDs.
• Verify checksum corruption in staged input still fails closed before publication.
• Verify a concurrent foreground commit causes a full abort/retry and the discarded plan contributes no stale page IDs, retired IDs, or root publication.
• Keep promotion, directory-sync, registration, metadata-write, metadata-sync, cleanup, and poisoning failure seams green.
• Keep checkpoint/close/reopen, leaf-generation GC, and persistent value-log pointer tests green.
• Keep detailed stage accounting non-negative, bounded by apply/publish wall, retry-separated, and JSON compatible.

Focused minimum validation:

GOWORK=off GOMEMLIMIT=4GiB GOMAXPROCS=2 go test -p 1 ./TreeDB/db \
  -run 'TestLeafGenerationPack|TestCompactStorage.*LeafPack' -count=1
GOWORK=off GOMEMLIMIT=4GiB GOMAXPROCS=2 go test -race -p 1 ./TreeDB/db \
  -run 'TestLeafGenerationPack_(Retry|Copy|Changed|Private|Source|SyncFalse)' -count=3
GOWORK=off GOMEMLIMIT=4GiB GOMAXPROCS=2 go test -p 1 ./TreeDB/pager -count=1

Run broader affected-package tests on the exact PR head. Any failure in durability, reopen, GC, retry, or race coverage blocks merge.

Performance Gates

Use the current origin/main baseline, not PR #3709's historical numbers, as the authoritative comparison. Keep benchmark source and fixture byte-identical, pin the same isolated CPU, set the same GOMAXPROCS and memory limit, and run at least six interleaved base/head pairs. Publish raw outputs, source hash, exact SHAs, command, CPU/hardware context, medians, and benchstat.

Gate	Target	Failure action
TreeRewrite + Relocation	>=20% lower	continue profiling/implementation; do not close
pack apply wall	>=10% lower	continue profiling/implementation; do not close
publish hold	no regression beyond 5%	block merge
allocations and bytes	each no regression beyond 5%	optimize or explain host noise with repeat evidence; otherwise block
total CompactStorage wall	directional improvement and no material regression	block or isolate demonstrated host noise
PL-01 foreground-write p95/p99	each <=2x idle baseline	block merge
durability/correctness	all focused, race, reopen, GC, and exact-head CI pass	block merge

The historical #3709 apply result implies an indicative target below about 42.8 ms/op, but only the newly measured current baseline controls acceptance.

Non-Goals

• No changes to WAL, page/directory/meta durability barriers, or sync semantics.
• No changes to the pager range-allocation cutoff, batch size, or retuning introduced by perf(treedb): reduce sparse leaf-pack apply cost #3709.
• No on-disk format, public API, leaf-log, or persistent value-log semantic changes.
• No leaf-pack admission-policy or pass-count changes to make the benchmark cheaper.
• No reopening of PL-09 reachability caching, PL-14 scanner consolidation, Land TreeDB tx-index checkpoint coordination and small durable WriteSync optimization #3652, or unrelated active PR work.

Branch, Review, And Merge Gates

• Use a topic branch from the recorded origin/main base in an isolated worktree.
• Keep benchmark instrumentation separable from the optimization so the paired binaries can use byte-identical benchmark source.
• PR body must include the root-cause table, red/green test evidence, exact benchmark commands and artifacts, base/head SHAs, benchmark source hash, before/after table, and regression assessment.
• Request Codex and repository review only after the code, tests, and paired evidence are mature.
• Require latest-head CI, an exact-head AI review artifact, zero unresolved material review threads, and a clean merge state before merge.
• If a gate fails, keep the issue in fix-needed state and iterate. Do not close it as insufficient without an explicit maintainer waiver.

[snissn]

Executor State

Field	Value
State	Running
Selected graph	#3715 only
Dependency order	Single node; no predecessors
Base snapshot	origin/main@d1b2d909ee6a1fd409d63ef895245c04b0f1376f
Implementation branch	codex/3715-prepared-leaf-pack-relocation
Implementation worktree	/mnt/fast4tb/gomap-3715-prepared-relocation
Benchmark baseline worktree	/mnt/fast4tb/gomap-3715-baseline
Delegation	One gpt-5.6-terra worker, medium reasoning; no speculative fan-out
Merge authority	Authorized for the selected issue after all gates pass

Contract

• Owns prepared internal-page relocation and detailed benchmark attribution only.
• Preserves exact revalidation, full abort/retry, durability ordering, source pinning, poisoning, reopen, GC, and persistent value-log semantics.
• Excludes WAL/meta/directory/page barrier changes, pager cutoff retuning, on-disk formats, admission policy, Land TreeDB tx-index checkpoint coordination and small durable WriteSync optimization #3652, and unrelated active PRs.
• Existing PR treedb: retain more leaf-ref build pages #3568 touches TreeDB/zipper leaf-ref build-page retention and is not an implementation overlap.

Required Route

1. Add benchmark attribution and a deterministic red test.
2. Implement prepared relocation outside writeMu.
3. Run focused, race, pager, reopen/GC, and paired pinned-CPU performance gates.
4. Open a mature PR only after local gates pass.
5. Require latest-head CI, exact-head AI review, clean merge state, and zero unresolved material threads before merge.

Failure of a performance or correctness gate returns this node to fix-needed; it is not waived or silently closed.

[snissn]

Root-Cause Gate Result

State: fix-needed; proposed production optimization stopped

The instrumentation commit 38211ae0e reports every existing ApplyStages field from BenchmarkCompactStorageLeafPackMultiPass. Benchmark source SHA-256 is 95bc5f1c4a6778583fb9a52b6d4cb4e7f7e04030a78ef24d8ea9f1a0cfe9f63a.

Baseline code is d1b2d909ee6a1fd409d63ef895245c04b0f1376f plus the benchmark-only instrumentation commit. Six samples used the same binary, fixture, CPU, and environment:

taskset -c 2 env GOWORK=off GOMEMLIMIT=4GiB GOMAXPROCS=1 \
  ./db-detailed.test -test.run '^$' \
  -test.bench '^BenchmarkCompactStorageLeafPackMultiPass$' \
  -test.benchtime=3x -test.count=6 -test.benchmem

Median classification:

Metric	Median	Share / finding
pack apply	82.90 ms/op	reference
tree rewrite	0.944 ms/op	local CPU work
relocation	0.058 ms/op	recursive staged rebuild is measurable but minor
tree rewrite + relocation	1.002 ms/op	only about 1.2% of apply
leaf sync	29.82 ms/op	durability dominated
page sync	37.17 ms/op	durability dominated
finalize	14.52 ms/op	durability dominated

The worker independently reproduced relocation at 52 us/op against leaf sync 43.20 ms/op, page sync 44.04 ms/op, and finalize 17.38 ms/op.

The deterministic red test proved the current recursive materialization exists:

--- FAIL: TestLeafGenerationPack_PreparedRelocationAvoidsLockedStagedMaterialization
locked publication recursively materialized 1 staged internal pages

However, eliminating the entire measured TreeRewrite + Relocation budget cannot satisfy the required >=10% pack-apply gate. Continuing would violate this issue's relocation-noise stop rule. The implementation and red test were therefore discarded; no production behavior changed.

Validation of the retained instrumentation:

GOWORK=off GOMEMLIMIT=4GiB GOMAXPROCS=2 go test -p 1 ./TreeDB/db \
  -run 'TestLeafGenerationPack|TestCompactStorage.*LeafPack' -count=1
ok github.com/snissn/gomap/TreeDB/db 9.333s

The durability-dominated stages are explicitly excluded from this issue and overlap the separately owned durability workstream, so this executor will not broaden scope into them.

[snissn]

Executor Outcome

State: fix-needed; measurement landed, production optimization not merged

• PR bench(treedb): report detailed leaf-pack apply stages #3716 merged at b4579a8f2f21307b74a4fa07fbb5cbf4e11ac245.
• Merged head 38211ae0eb89c0baf0e42e94a16ee6de27ac3f0a adds detailed ApplyStages reporting only; production behavior is unchanged.
• All latest-head CI checks passed, including both race shards and all TreeDB Windows shards.
• CodeRabbit passed; exact-head Codex review found no major issues on 38211ae0eb; review threads: 0 total / 0 unresolved.
• Local focused leaf-pack tests passed.

The production optimization is intentionally not merged. Six samples put median TreeRewrite + Relocation at about 1.002 ms/op against 82.90 ms/op pack apply, so even eliminating the entire local budget cannot satisfy the >=10% apply gate. Leaf sync, page sync, and finalize dominate, and those durability stages are explicitly excluded here and separately owned.

Issue #3715 remains open rather than being closed with an unsupported performance claim. A future implementation must first identify a non-overlapping local cost with enough measured headroom, or be explicitly superseded by the separately owned durability workstream.

[snissn]

Superseded by the post-durability CompactStorage efficiency graph in #3732.

The current-main diagnostic profile at b51a8671bc1f09a2191902f292bc3952a1b08c81 does not support this issue's implementation premise:

• end-to-end stress fixture: 91.76 ms/op;
• leaf-pack apply: 42.29 ms/op;
• tree rewrite plus relocation planning: 0.858 ms/op;
• rewrite plus relocation share: 2.0% of apply and 0.94% of total wall;
• traced wall time was dominated by stable-storage syscall blocking.

Even eliminating the measured rewrite/relocation cost completely cannot satisfy this issue's >=10% apply-time gate. Implementing the proposed materialization cache would therefore add invalidation and lifetime complexity without a supported end-to-end payoff.

All remaining obligations are mapped rather than discarded:

• canonical post-[DUR-06] Atomically activate safe root publication and exact API boundaries #3680/[DUR-08] Fence destructive maintenance on the complete recoverable-root set #3681 phase, syscall, allocation, and write-latency evidence: M0: Stabilize post-durability CompactStorage phase and barrier evidence #3733;
• exact durable-root coverage across immediate post-pack checkpoint work: M1: Reuse exact durable-root coverage across leaf-pack checkpoints #3734;
• low-debt Full index-vacuum gating, only if evidence activates it: M2: Debt-gate Full-mode index vacuum without weakening exhaustive compaction #3735;
• residual profile-selected allocation work, only if evidence activates it: M3: Reduce residual leaf-pack staging allocations after I/O fixes #3736;
• final paired current-main certification and residual attribution: M4: Validate post-durability CompactStorage latency and residual attribution #3737;
• authoritative parent graph, north-star gates, and dispositions: Land post-durability CompactStorage phase efficiency #3732.

This issue remains useful as profiling history, but no longer owns implementation. Closing as not planned in favor of the measured successor graph. If a post-durability profile later shows duplicate internal-page materialization above a material activation threshold, it should be opened as a new measured child with a fresh baseline rather than reviving this stale gate.