feat(table): add Transaction.AssertRefSnapshotID (Java UpdateRequirements parity)

[ryanworl]

Adds Transaction.AssertRefSnapshotID(branch): the same assert-ref-snapshot-id requirement Java's UpdateRequirements builds for a changed ref, exposed so metadata-only commits can use it too. A transaction that only sets properties (e.g. exactly-once bookkeeping that records ingestion offsets) can require that the branch is unchanged from the state it read; if another writer committed in between, the commit fails with ErrCommitFailed instead of being silently replayed onto the new head.

Two commits:

1. Align ref requirement accumulation with Java. UpdateRequirements accumulates one assertion per ref, built from the base table state. Our producers built theirs from the staged metadata's current snapshot instead — an id the catalog has never seen when a transaction carries multiple operations. Producers, RollbackToSnapshot, and ExpireSnapshots now assert the base state, and two same-ref assertions requiring different snapshot ids are rejected at apply time rather than one being silently dropped.

2. Expose the requirement on Transaction. Matches Java semantics: an explicit requirement and a producer-built one for the same branch collapse to one. The one Go-specific wrinkle is the commit retry loop, which rewrites ref assertions to the fresh head between retries; explicitly registered assertions are exempt, since rewriting would void the compare-and-swap the caller asked for.

Without this, Go writers have to commit an empty AddFiles append per metadata-only write to serialize through a producer's requirement (an included test documents that workaround, which also matches Java's zero-file newFastAppend().commit() behavior).

Made with Cursor

[zeroshade]

This lands the Java UpdateRequirements contract properly: ref assertions built from the base state the writer actually read (with the staged-ref exemption reasoned correctly at both RollbackToSnapshot and ExpireSnapshots), same-ref/different-id pairs rejected at apply time instead of one silently dropping, and the dedup-validation reorder that makes base-state re-assertion possible at all. The pin-before-visibility mutex discipline on AssertRefSnapshotID — so a concurrent commit's retry-rewrite can't void the CAS the caller just asked for — is the kind of detail that's easy to miss and wasn't. Documenting the empty-append workaround as a test is a nice touch for anyone migrating.

Heads-up only: #1637 (open) touches the same requirement-building paths, so whichever merges second will want a careful rebase.

---

This review was drafted with an AI-assisted tool and may contain mistakes; an Apache Iceberg Go maintainer has reviewed and confirmed the submission. See the contributing docs for what the project considers a maintainer review.

[zeroshade]

@ryanworl Approved — today's merges (#1784 in particular) touched the same transaction.go/table.go regions, so this now conflicts with main. After a rebase and green CI it can merge right away.

_{Posted by an AI-assisted tool on behalf of maintainer zeroshade.}