feat: Iceberg WAP branch read via VERSION_REF time travel

[sfc-gh-igarish]

Summary

• Adds version_ref and branch to TimeTravelConfig for Iceberg WAP branch reads
• Maps Spark Iceberg branch, tag, and version_ref reader options
• Emits Snowflake AT(VERSION_REF => '<name>') for tag/branch named-ref reads (unifies prior VERSION_TAG SQL)
• Builds on merged tag support (SNOW-3473261: Add Iceberg tag time travel via version_tag #4211)

Test plan

• Unit tests for TimeTravelConfig and _extract_time_travel_from_options
• Manual: branch read on managed Iceberg table with WAP branch

1. Which Jira issue is this PR addressing? Make sure that there is an accompanying issue to your PR.

   Fixes SNOW-3674169

2. Fill out the following pre-review checklist:

   • I am adding a new automated test(s) to verify correctness of my new code
   • I am adding new logging messages
   • I am adding a new telemetry message
   • I am adding new credentials
   • I am adding a new dependency
   • If this is a new feature/behavior, I'm adding the Local Testing parity changes.
   • I acknowledge that I have ensured my changes to be thread-safe. Follow the link for more information: Thread-safe Developer Guidelines
   • If adding any arguments to public Snowpark APIs or creating new public Snowpark APIs, I acknowledge that I have ensured my changes include AST support. Follow the link for more information: AST Support Guidelines

3. Please describe how your code change solves the related issue.

   Extends TimeTravelConfig with version_ref and branch, maps Spark Iceberg reader options (branch, tag, version_ref, existing tag aliases), and emits Snowflake AT (VERSION_REF => '<name>') for named-ref reads. Tag reads keep the same customer-facing behavior while using the unified VERSION_REF SQL form.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.52%. Comparing base (c9b9303) to head (263b01d).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4267      +/-   ##
==========================================
- Coverage   95.52%   95.52%   -0.01%     
==========================================
  Files         171      171              
  Lines       44358    44396      +38     
  Branches     7577     7585       +8     
==========================================
+ Hits        42375    42411      +36     
- Misses       1221     1222       +1     
- Partials      762      763       +1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[sfc-gh-aling]

there are some failing tests, please fix them and also improve the test coverage. thanks!

[sfc-gh-yuwang]

Looks like this is changing a public class, should we add changelog for it?

[sfc-gh-igarish]

Thanks — working on this. Current failures look tied to missing CHANGELOG / AST / thread-safety checklist items plus unit-test gaps around the new version_ref / branch fields and the VERSION_TAG → VERSION_REF SQL change. Next push will add the changelog entry, extend unit coverage for the new paths, and fix the failing checks.

[sfc-gh-igarish]

Yes — TimeTravelConfig gains public version_ref and branch parameters, so I will add a CHANGELOG entry documenting Iceberg WAP branch / named-ref time travel via VERSION_REF.

[sfc-gh-igarish]

Addressed in b5cd211 — added CHANGELOG entry, fixed/extended unit tests (VERSION_REF message alignment + version_ref/branch validation coverage), and updated the PR description with the thread-safety / AST checklist items.

[sfc-gh-igarish]

Added CHANGELOG entry under 1.53.0 New Features in b5cd211.

[sfc-gh-igarish]

Removed the CHANGELOG entry in 263b01d — same rationale as #4262: the version_ref / branch time-travel surface is wired through Snowpark Connect (SAS) only, not as a standalone public Snowpark Python API, so it should not appear in the release notes. Branch is rebased onto latest main.