Preserve a ref's retention policy when its snapshot moves

[1fanwang]

Rationale for this change

Refs can be created with retention settings, but two move paths rebuild the ref without carrying those settings forward: branch writes and current-snapshot moves. This revives the stale-closed #3770. The next metadata update then clears max ref age, max snapshot age, and min snapshots to keep.

Fast-forward already preserves the policy. This makes branch writes, set-current-snapshot, and rollback do the same. Refs created without a policy still stay unset. This is separate from #3760, which covers expiring stale refs.

Are these changes tested?

Targeted unit regression tests fail on current main and pass with this branch. Branch write also passes against the REST catalog.

Raw logs

$ F=pyiceberg/table/update/snapshot.py
$ T=tests/table/test_manage_snapshots.py
$ git checkout origin/main -- "$F"
$ uv run pytest "$T" -k retention -q
..FFF...FFF...                                                           [100%]
E       assert None == 86400000
E       assert None == 99999
6 failed, 8 passed, 20 deselected in 4.99s

$ git checkout HEAD -- "$F"
$ uv run pytest "$T" -q
..................................                                       [100%]
34 passed in 1.20s

$ make test-integration-setup
$ I=tests/integration/test_writes/test_writes.py
$ uv run pytest "$I" -m integration -k retention -q
.                                                                        [100%]
1 passed, 123 deselected in 6.74s
$ make test-integration-cleanup

Are there any user-facing changes?

A ref keeps the retention policy it was created with when its snapshot moves. There is no API change.

AI Disclosure

AI disclosure: GitHub Copilot CLI (GPT-6 Astra) helped rebase the stale PR, resolve the current main conflict, refresh the PR description, and rerun the tests.

[Copilot]

Copilot review overview

🟢 Approval recommended

No unresolved issues were identified.

Review effort: Lite
Findings: None

What changed in this PR

Preserves ref retention policies when snapshots move through writes, current-snapshot changes, and rollbacks.

Changes:

• Carries retention fields through ref updates.
• Adds unit and integration regression coverage.

File	Description
tests/​table/​test_manage_snapshots.py	Adds unit coverage for retention behavior.
tests/​integration/​test_writes/​test_writes.py	Adds catalog integration coverage.
pyiceberg/​table/​update/​snapshot.py	Preserves retention metadata during snapshot moves.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.