Add ManageSnapshots.fast_forward_branch

[Ferdinanddb]

Adds ManageSnapshots.fast_forward_branch, following Java's ManageSnapshots.fastForwardBranch and Spark's system.fast_forward procedure.

with table.manage_snapshots() as ms:
    ms.fast_forward_branch("main", "audit")

• the ref to fast-forward to can be a branch or a tag and is left untouched
• a branch that does not exist yet is created at that snapshot with default retention properties, an existing branch keeps its retention properties
• fast-forwarding to the snapshot the branch already points to is a no-op, a branch that is not an ancestor raises ValueError
• operations chained in one manage_snapshots() see each other, and a ref set twice in a chain results in a single set-snapshot-ref update

Supersedes #3649 by @JeroenSchmidt, which has been conflicting since August. It keeps the same API and intra-chain behaviour and addresses the open review comments from @rambleraptor (refs injected directly in the tests, default retention of a created branch documented, tag target and no-op covered, shorter docs). Differences: plain ValueError instead of new exception classes, the pending refs come from update_table_metadata instead of a separate overlay, and chained updates on the same ref are collapsed.

The second commit is separable: it adds the gt=0 bounds that SnapshotRef already has to SetSnapshotRefUpdate, so an invalid retention value fails when it is passed instead of at apply time, like SnapshotRef.Builder in Java. Happy to split it out if preferred.

[rambleraptor]

We already went through reviews, so this looks good to me. Thanks for doing this!

[Fokko]

I'm tempted to also call this table_metadata, similar to Transaction:

iceberg-python/pyiceberg/table/__init__.py

Lines 259 to 261 in 9299bdb

	@property
	def table_metadata(self) -> TableMetadata:
	return update_table_metadata(self._table.metadata, self._updates)

[Fokko]

This is outside of the scope of this PR, but I was a bit surprised by this. Based on the method name, I expected it to perform an actual commit, but after reading the code, it turns out it stages the commit within the transaction.

[Ferdinanddb]

Thanks a lot for the review @Fokko !

Before I push anything: @JeroenSchmidt pushed the pending changes to #3649 this morning, so the original PR is alive again. I had opened this one because his had been untouched since August, but he is back on it, so I am happy to let him finish and close this once #3649 lands. That said, it is your call which implementation fits best.

Since the two diverged, here is what actually differs. Your comments here are on code that only exists in this PR: #3649 reads the pending refs through a hand-rolled _effective_refs() that rebuilds SnapshotRef objects from the staged SetSnapshotRefUpdates rather than going through update_table_metadata, and it does not touch _commit_if_ref_updates_exist.

Only in this PR:

• gt=0 on the three retention fields of SetSnapshotRefUpdate, so an invalid value fails when it is passed rather than at apply time (always separable, happy to raise it on its own)
• repeated updates on the same ref within one chain are collapsed into a single set-snapshot-ref and a single AssertRefSnapshotId
• _commit_if_ref_updates_exist() on rollback_to_snapshot / rollback_to_timestamp
• a guard for a ref pointing at a snapshot id that is not in the metadata

Only in #3649: three new public exception types (NoSuchSnapshotRefError, SnapshotRefTypeError, NotAncestorError) instead of plain ValueError. That is the one that is hard to walk back after merge, so it would be good to have your opinion on it either way.

[rambleraptor]

Thanks for your work on this @Ferdinanddb

I'm slightly inclined to use #3649 since it's approved. If we can't get the CI passing on that PR soon, let's move forward with yours.