Support `retainLast` and `setMinSnapshotsToKeep` Snapshot Retention Policies

[ForeverAngry]

Feature Request / Improvement

Overview

Add richer snapshot expiration retention capabilities:

• retain_last_n(n): keep N most recent snapshots regardless of age.
• older_than_with_retention(...): combine max age filter with retain_last_n and a minimum snapshots floor.
• with_retention_policy(...): unified API that also consumes table property defaults:
  • history.expire.max-snapshot-age-ms
  • history.expire.min-snapshots-to-keep
  • history.expire.max-ref-age-ms (plumbed for future ref expiration logic)
    Internal helpers:
• _get_expiration_properties: parses table properties.
• _get_snapshots_to_expire_with_retention: core selection logic factoring protected refs (branches/tags), age, recency, and minimum keep guardrail.
  Motivation: safer, configurable space reclamation while preventing accidental over‑expiration.

Related to #2369

[ForeverAngry]

@greenlaw take a look, let me know if missed anything you were looking for, i added the enhancements outlined above to: #2369

[ForeverAngry]

@kevinjqliu or @sungwy could either of you assign me to this?

[greenlaw]

@greenlaw take a look, let me know if missed anything you were looking for, i added the enhancements outlined above to: #2143

Hey @ForeverAngry Sorry for delayed response on this.

Yes, this covers the cases I'm most interested in. Really appreciate your efforts 🙏 .

I do think the Java API also supports branch expiration (setMaxRefAgeMs) as well, but I think what you've added is most important, as we can always manually delete branches ourselves.

[ForeverAngry]

The draft pr for this is #2369, we pulled it out to make it easier to review some of the changes that needed to be made to the expire snapshots api. I plan on pushing the actual pr, this weekend.