Thread ctx through v3 envelope, add CtxCopy helper, and detach pebble finalize

[arreyder]

Summary

Stacked on #891. Merge that one first.

WriteEnvelope previously held no context: a caller cancellation during the payload tar/zstd walk had to wait for filepath.Walk to drain the entire Pebble checkpoint before the function returned. Big-tenant checkpoints are GBs; that wait is the gap during which the io.Pipe upload pattern can end up with clean-EOF semantics instead of CloseWithError.

WriteEnvelope now takes ctx as its first parameter. The walk callbacks check ctx.Err() per entry, and each regular-file copy is routed through a new iox.CtxCopy: chunked io.CopyBuffer (4 MiB poll granularity, 32 KiB working buffer held across iterations — one allocation per call, not one per chunk).

registeredStore.save (the Pebble equivalent of C1File.finalize) now runs the Checkpoint + WriteEnvelope + rename sequence on a context detached from the caller via dotc1z.FinalizeTimeout(), inside a uotel.StartWithLink new-root span — same pattern as PR #891's C1File.finalize. This protects the Pebble write path even when the caller is a direct C1ZStore consumer that didn't already detach.

Changes

• pkg/dotc1z/iox/copy.go (new, new package) — CtxCopy helper. Lives in a leaf subpackage of dotc1z so sibling subpackages (format/v3, engine/pebble, future manager/s3 / synccompactor callers) can import it without circular risk and without pulling in the rest of dotc1z.
• pkg/dotc1z/format/v3/envelope.go — WriteEnvelope(ctx, w, m, payloadDir) signature. Walk callbacks check ctx.Err() per entry and wrap with the in-flight tar entry name (c1z v3: tar_zstd walk canceled at "entry-X": ...) so operators triaging "context canceled" in logs can see exactly which Pebble checkpoint file was being visited. Godoc tightened to say magic+length+manifest bytes are written before the first ctx check, so io.Pipe callers must propagate ctx.Err() via CloseWithError on cancellation.
• pkg/dotc1z/engine/pebble/register.go — registeredStore.save adopts the detach + new-root pattern. Honors the propagated parent ctx-err label from PR Detach ctx for c1z finalize so caller cancel cannot truncate the artifact #891 so the inner finalize span reports the real caller cancel state.
• pkg/dotc1z/engine/pebble/adapter_clone_sync.go — passes ctx through to WriteEnvelope.
• pkg/dotc1z/iox/copy_test.go (new) — 7 unit tests: happy, empty source, cancel-before-start, cancel-mid-stream (with read counter to prove the source is not over-consumed), source-error, dst-error, short-write.
• pkg/dotc1z/format/v3/envelope_test.go — adds TestWriteEnvelopeCanceledMidWalk (tee-writer fires cancel after the first header bytes hit the writer; asserts wrapped error names the in-flight entry) and TestWriteEnvelopeEmptyPayloadDir.
• pkg/dotc1z/engine/pebble/registered_store_save_cancel_test.go (new) — pebble symmetry with PR Detach ctx for c1z finalize so caller cancel cannot truncate the artifact #891's TestC1FileCloseSurvivesCanceledCtx. A regression that replaces finalizeCtx with the caller ctx in save() would fail this test.

Deferred to follow-up

writeZstdTar still allocates a fresh zstd.Encoder per save instead of using pkg/dotc1z/pool.go's existing encoder pool. Using the pool from format/v3 requires either moving the pool to a shared subpackage or threading an encoder via a new option — out of scope for this PR.

Test plan

• go test ./... clean
• make lint clean on the touched files
• Mid-walk cancel test asserts wrapped error contains the in-flight tar entry name
• Pebble cancel-survival test mirrors the SQLite-engine test from PR Detach ctx for c1z finalize so caller cancel cannot truncate the artifact #891

🤖 Generated with Claude Code

[linear-code]

FDE-244

[github-actions]

🟡 Suggestion: io.CopyBuffer never returns io.EOF from a source-side EOF — it swallows it and returns (n, nil). The only way this check triggers is if dst.Write() returns io.EOF as a write error, in which case this would incorrectly treat it as successful completion. The check is effectively dead code today (the n < ctxCopyChunkSize branch at line 59 handles normal source exhaustion), but if you want to keep a defensive guard, consider checking err == io.EOF (identity, not wrapped) to avoid swallowing a wrapped writer error.

[github-actions]

General PR Review: Thread ctx through v3 envelope, add CtxCopy helper, and detach pebble finalize

Blocking Issues: 0 | Suggestions: 1 | Threads Resolved: 0
Review mode: full
View review run

Review Summary

This PR threads context.Context through WriteEnvelope and its tar-walk internals so that caller cancellation surfaces as an error mid-walk rather than silently producing a truncated envelope. The new iox.CtxCopy helper provides chunked context-aware copying, and registeredStore.save now detaches from the caller's context with FinalizeTimeout() — mirroring the C1File pattern from PR #891. The implementation is clean, all callers are updated, and test coverage is thorough (cancel-before, cancel-mid, empty payload, and the Pebble save-survives-cancel regression test).

Security Issues

None found.

Correctness Issues

None found.

Suggestions

• pkg/dotc1z/iox/copy.go:48-50: The errors.Is(err, io.EOF) check is dead code under normal io.CopyBuffer behavior (it swallows source EOF). Could mask a hypothetical dst.Write() returning io.EOF.

Prompt for AI agents

Verify each finding against the current code and only fix it if needed.

## Suggestions

In `pkg/dotc1z/iox/copy.go`:
- Around line 48-50: The `errors.Is(err, io.EOF)` guard after `io.CopyBuffer` is dead code for
  normal source EOF (io.CopyBuffer swallows it and returns nil). The only trigger is if
  `dst.Write()` returns `io.EOF` as a write error, which this code would incorrectly treat as
  success. Either remove the check entirely (the `n < ctxCopyChunkSize` branch at line 59
  already handles normal source exhaustion) or narrow it to identity comparison `err == io.EOF`
  to avoid masking a wrapped writer error.

[github-actions]

No blocking issues found.