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: 2 | Threads Resolved: 0
Review mode: full
View review run

Review Summary

This PR threads context.Context through WriteEnvelope and the tar walk/copy paths, adds a new iox.CtxCopy helper for context-aware chunked copying, and detaches the Pebble save() from caller cancellation using context.WithoutCancel bounded by FinalizeTimeout(). The implementation is clean and well-tested — the detach pattern, span linking, and per-entry/per-chunk ctx checks all look correct. Two minor suggestions below: an error-wrapping inconsistency in writeTar vs writeZstdTar, and a note on the exported WriteEnvelope signature change for downstream callers. The previously flagged errors.Is(err, io.EOF) dead-code concern in CtxCopy remains unchanged.

Security Issues

None found.

Correctness Issues

None found.

Suggestions

• pkg/dotc1z/format/v3/envelope.go:316: writeTar copy errors lack entry-name wrapping, unlike the parallel writeZstdTar path — makes TAR-path failures harder to diagnose.
• pkg/dotc1z/format/v3/envelope.go:80: WriteEnvelope is an exported function whose signature changed (added ctx context.Context). Downstream callers outside this repo will need a coordinated update.

Prompt for AI agents

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

## Suggestions

In `pkg/dotc1z/format/v3/envelope.go`:
- Around line 320: The `writeTar` function returns bare copy errors (`return err`) while the parallel `writeZstdTar` wraps them with the entry name (`fmt.Errorf("c1z v3: tar_zstd copy %q: %w", rel, err)`). Wrap the error on line 320 as `return fmt.Errorf("c1z v3: tar copy %q: %w", rel, err)` for diagnostic parity.

- Around line 80: `WriteEnvelope` is exported and its signature changed from `(io.Writer, *c1zv3.C1ZManifestV3, string) error` to `(context.Context, io.Writer, *c1zv3.C1ZManifestV3, string) error`. Ensure all downstream consumers outside this repo are updated. No code change needed here if downstream coordination is planned.

[github-actions]

No blocking issues found.

[github-actions]

🟡 Suggestion: Adding ctx context.Context as the first parameter changes the exported signature of WriteEnvelope. Any downstream caller outside this repo (e.g. connectors or tools importing pkg/dotc1z/format/v3) will fail to compile until updated. If external callers exist, consider coordinating the rollout or bumping the module version.

[github-actions]

🟡 Suggestion: In writeZstdTar, copy errors are wrapped with the entry name (fmt.Errorf("c1z v3: tar_zstd copy %q: %w", rel, err)), but the equivalent error path here in writeTar (line 320) returns the bare error. Consider wrapping for parity so operators can identify which file failed during a TAR-encoded write.

[github-actions]

No blocking issues found.