feat: add core COW rewrite primitive

[u70b3]

Summary

• Add iceberg::cow_rewrite with candidate planning, batch rewriter trait, replacement writer, orchestration builder, result stats, public API snapshot, and docs.
• Reuse existing scan pruning/delete application while clearing the rewrite scan predicate so candidate files are read fully.
• Cover DELETE-style, UPDATE-style, no-op, full-file delete, no-match delete, writer edge cases, delete-file planning, and multi-file replacement path uniqueness.

Core Design

• Split COW into planning, batch rewriting, and replacement file writing so SQL planning and metadata commit can stay outside the primitive.
• Plan candidates through the existing scan path to keep manifest pruning and delete-file application consistent with normal reads, then clear only the row predicate for full-file rewrite input.
• Return removed, added, and unchanged DataFile sets plus stats; callers can pass these to a future overwrite/row-delta action.
• Write replacement files with unique COW prefixes and preserve the partition values of each source file; this primitive does not repartition rewritten rows.

Related Work Map

flowchart LR
    Read["#2367 / #2414 / #2532<br/>delete-read improvements"] --> Scan["existing scan/read path<br/>visible rows"]
    Scan --> ThisPR["#2752<br/>COW rewrite primitive<br/>plan + rewrite + write files"]
    ThisPR --> Files["removed DataFiles<br/>added DataFiles<br/>stats"]
    Files --> Overwrite["#2185<br/>OverwriteAction<br/>preferred COW commit path"]
    Files --> RowDelta["#2203 / #2678<br/>RowDelta / MoR path"]
    Validator["#2590<br/>SnapshotValidator"] -. future commit validation .-> Overwrite
    Validator -. future commit validation .-> RowDelta

Loading

Notes

• Part of [EPIC] Implement Missing Write Actions #2269.
• This PR is the core rewrite primitive only: it produces file sets and intentionally does not commit table metadata.
• The diff is larger than the usual small-PR preference because it adds a new public primitive, focused tests, docs, and the public API snapshot together; commit adapters are still left to follow-up PRs.
• feat(transaction): add OverwriteAction with CoW delete support #2185 (OverwriteAction) is the preferred follow-up commit path for COW; it can consume the removed/added DataFile sets returned here once available on the base branch.
• feat(transaction): add RowDelta transaction action for row-level modi… #2203 / feat(transaction): RowDelta merge-on-read deletion vectors (carries forward #2203) #2678 cover RowDelta/MoR-oriented transaction work; this PR stays independent and does not implement RowDelta, merge-on-read delete files, or deletion vectors.
• feat(iceberg): Enable delete files processing in snapshot producer #2367, feat(delete-vector): parse deletion-vector-v1 puffin blob - read support #2414, and Position delete read improvements #2532 are complementary delete-read/delete-file improvements. This PR reuses the scan path so those read-side capabilities remain centralized rather than duplicated here.
• feat(transaction): Add SnapshotValidator #2590 (SnapshotValidator) is complementary validation infrastructure for future commit adapters; no validator dependency is introduced in this primitive.

Test Plan

• cargo fmt --all -- --check
• make check
• cargo test -p iceberg cow_rewrite
• cargo test -p iceberg scan
• cargo test -p iceberg writer
• cargo test -p iceberg --doc cow_rewrite
• cargo public-api -p iceberg --all-features -ss | diff - crates/iceberg/public-api.txt