feat: add missing methods to SnapshotUpdate interface

Add DeleteWith() and ToBranch() methods to complete the SnapshotUpdate API
coverage from Java implementation. This brings the interface closer to
feature parity with Java Iceberg.

New methods:
- DeleteWith(): Set custom file deletion callback for tracking deleted files,
  implementing custom retention policies, or delegating deletion to external
  systems. Uses std::function<void(std::string_view)> for the callback.

- ToBranch(): Commit snapshot to a specific branch instead of main branch.
  Useful for Write-Audit-Publish (WAP) workflows, feature branch development,
  and testing changes before merging to main.

Method deferred:
- ScanManifestsWith(): Deferred until executor/thread pool infrastructure is
  available in the codebase. Documented in class comments for future addition.

Changes:
- Add DeleteWith() and ToBranch() methods with fluent API
- Add delete_func_ and target_branch_ protected members
- Add 3 new test cases: DeleteWith, ToBranch, MethodChainingWithAllMethods
- Update class documentation to list included and deferred methods
- Total test count increased from 10 to 13, all passing

Author: shangxinli

src/iceberg/snapshot_update.h

@@ -22,6 +22,8 @@
 /// \file iceberg/snapshot_update.h
 /// API for table updates that produce snapshots
 
+#include <functional>
+#include <optional>
 #include <string>
 #include <string_view>
 #include <unordered_map>
@@ -42,6 +44,16 @@ namespace iceberg {
 /// fluent API method chaining in derived classes, matching the Java pattern
 /// where SnapshotUpdate<ThisT> allows methods to return the actual derived type.
 ///
+/// Methods included from Java API:
+/// - Set(): Set summary properties
+/// - StageOnly(): Stage without updating current snapshot
+/// - DeleteWith(): Custom file deletion callback
+/// - ToBranch(): Commit to a specific branch
+///
+/// Methods deferred (will be added when infrastructure is available):
+/// - ScanManifestsWith(): Custom executor for parallel manifest scanning
+///   (requires executor/thread pool infrastructure)
+///
 /// \tparam Derived The actual implementation class (e.g., AppendFiles)
 template <typename Derived>
 class ICEBERG_EXPORT SnapshotUpdate : public PendingUpdateTyped<Snapshot> {
@@ -74,6 +86,36 @@ class ICEBERG_EXPORT SnapshotUpdate : public PendingUpdateTyped<Snapshot> {
     return static_cast<Derived&>(*this);
   }
 
+  /// \brief Set a custom file deletion callback
+  ///
+  /// By default, files are deleted using the table's FileIO implementation.
+  /// This method allows providing a custom deletion callback for use cases like:
+  /// - Tracking deleted files for auditing
+  /// - Implementing custom retention policies
+  /// - Delegating deletion to external systems
+  ///
+  /// \param delete_func Callback function that will be called for each file to delete
+  /// \return Reference to derived class for method chaining
+  Derived& DeleteWith(std::function<void(std::string_view)> delete_func) {
+    delete_func_ = std::move(delete_func);
+    return static_cast<Derived&>(*this);
+  }
+
+  /// \brief Commit the snapshot to a specific branch
+  ///
+  /// By default, snapshots are committed to the table's main branch.
+  /// This method allows committing to a named branch instead, which is useful for:
+  /// - Write-Audit-Publish (WAP) workflows
+  /// - Feature branch development
+  /// - Testing changes before merging to main
+  ///
+  /// \param branch The name of the branch to commit to
+  /// \return Reference to derived class for method chaining
+  Derived& ToBranch(std::string_view branch) {
+    target_branch_ = std::string(branch);
+    return static_cast<Derived&>(*this);
+  }
+
  protected:
   SnapshotUpdate() = default;
 
@@ -82,6 +124,12 @@ class ICEBERG_EXPORT SnapshotUpdate : public PendingUpdateTyped<Snapshot> {
 
   /// \brief Whether to stage only without updating current snapshot
   bool stage_only_ = false;
+
+  /// \brief Custom file deletion callback
+  std::optional<std::function<void(std::string_view)>> delete_func_;
+
+  /// \brief Target branch name for commit (nullopt means main branch)
+  std::optional<std::string> target_branch_;
 };
 
 }  // namespace iceberg

src/iceberg/test/snapshot_update_test.cc

@@ -68,6 +68,10 @@ class MockSnapshotUpdate : public SnapshotUpdate<MockSnapshotUpdate> {
     return summary_;
   }
   bool GetStageOnly() const { return stage_only_; }
+  const std::optional<std::function<void(std::string_view)>>& GetDeleteFunc() const {
+    return delete_func_;
+  }
+  const std::optional<std::string>& GetTargetBranch() const { return target_branch_; }
 
  private:
   bool should_fail_ = false;
@@ -100,6 +104,33 @@ TEST(SnapshotUpdateTest, StageOnly) {
   EXPECT_TRUE(update.GetStageOnly());
 }
 
+TEST(SnapshotUpdateTest, DeleteWith) {
+  MockSnapshotUpdate update;
+  std::vector<std::string> deleted_files;
+
+  update.DeleteWith([&deleted_files](std::string_view path) {
+    deleted_files.push_back(std::string(path));
+  });
+
+  EXPECT_TRUE(update.GetDeleteFunc().has_value());
+  // Test the callback works
+  if (update.GetDeleteFunc()) {
+    (*update.GetDeleteFunc())("s3://bucket/data/file1.parquet");
+    (*update.GetDeleteFunc())("s3://bucket/data/file2.parquet");
+  }
+  EXPECT_EQ(deleted_files.size(), 2);
+  EXPECT_EQ(deleted_files[0], "s3://bucket/data/file1.parquet");
+  EXPECT_EQ(deleted_files[1], "s3://bucket/data/file2.parquet");
+}
+
+TEST(SnapshotUpdateTest, ToBranch) {
+  MockSnapshotUpdate update;
+  update.ToBranch("feature-branch");
+
+  EXPECT_TRUE(update.GetTargetBranch().has_value());
+  EXPECT_EQ(*update.GetTargetBranch(), "feature-branch");
+}
+
 TEST(SnapshotUpdateTest, MethodChaining) {
   MockSnapshotUpdate update;
   update.Set("operation", "append")
@@ -114,6 +145,27 @@ TEST(SnapshotUpdateTest, MethodChaining) {
   EXPECT_TRUE(update.GetStageOnly());
 }
 
+TEST(SnapshotUpdateTest, MethodChainingWithAllMethods) {
+  MockSnapshotUpdate update;
+  std::vector<std::string> deleted_files;
+
+  update.Set("operation", "append")
+      .Set("added-files-count", "5")
+      .DeleteWith([&deleted_files](std::string_view path) {
+        deleted_files.push_back(std::string(path));
+      })
+      .ToBranch("wap-branch")
+      .StageOnly();
+
+  EXPECT_EQ(update.GetSummary().size(), 2);
+  EXPECT_EQ(update.GetSummary().at("operation"), "append");
+  EXPECT_EQ(update.GetSummary().at("added-files-count"), "5");
+  EXPECT_TRUE(update.GetDeleteFunc().has_value());
+  EXPECT_TRUE(update.GetTargetBranch().has_value());
+  EXPECT_EQ(*update.GetTargetBranch(), "wap-branch");
+  EXPECT_TRUE(update.GetStageOnly());
+}
+
 TEST(SnapshotUpdateTest, ApplySuccess) {
   MockSnapshotUpdate update;
   auto result = update.Apply();