feat(update): add OverwriteFiles for overwrite snapshot commits (#741)

Summary:
Add a production OverwriteFiles builder that brings iceberg-cpp to
semantic parity with Java's BaseOverwriteFiles. It supports explicit
file replacement (DeleteFile + AddFile) and range-based replacement
(OverwriteByRowFilter + AddFile) with the same family of pre-commit
concurrency validations. The builder is a thin subclass of
MergingSnapshotUpdate and reuses the existing commit kernel
(Apply/summary/retry/cleanup) unchanged.

Changes:
- New OverwriteFiles class (src/iceberg/update/overwrite_files.{h,cc})
and Table::NewOverwrite() / Transaction::NewOverwrite() entry points.
- Builder surface: AddFile, DeleteFile, bulk DeleteFiles,
OverwriteByRowFilter, ValidateFromSnapshot, ConflictDetectionFilter,
ValidateNoConflictingData, ValidateNoConflictingDeletes,
ValidateAddedFilesMatchOverwriteFilter, WithCaseSensitivity.
- Validate(): conflict-filter resolution, concurrent add/delete conflict
checks, and strict added-file range validation (projection +
StrictMetricsEvaluator).
- Tests (overwrite_files_test.cc, 45 cases) and CMake/meson wiring.

Behavior alignment with Java:
- operation() returns append/delete/overwrite from builder content.
- Conflict-filter resolution mirrors BaseOverwriteFiles (explicit -> row
filter -> AlwaysTrue); replaced-file delete checks honor
ConflictDetectionFilter.
- Strict added-file validation uses a single DataSpec(), rejecting
multi-spec and empty added-file sets.
- Deviations: public WithCaseSensitivity (vs caseSensitive) to avoid a
protected-name clash; ValidateFromSnapshot rejects negative ids early.

---------

Co-authored-by: shuxu.li <shuxu.li@clickzetta.com>

Author: lishuxu

src/iceberg/CMakeLists.txt

@@ -105,6 +105,7 @@ set(ICEBERG_SOURCES
     update/fast_append.cc
     update/merge_append.cc
     update/merging_snapshot_update.cc
+    update/overwrite_files.cc
     update/pending_update.cc
     update/row_delta.cc
     update/set_snapshot.cc

src/iceberg/meson.build

@@ -130,6 +130,7 @@ iceberg_sources = files(
     'update/fast_append.cc',
     'update/merge_append.cc',
     'update/merging_snapshot_update.cc',
+    'update/overwrite_files.cc',
     'update/pending_update.cc',
     'update/row_delta.cc',
     'update/set_snapshot.cc',

src/iceberg/table.cc

@@ -35,6 +35,7 @@
 #include "iceberg/update/expire_snapshots.h"
 #include "iceberg/update/fast_append.h"
 #include "iceberg/update/merge_append.h"
+#include "iceberg/update/overwrite_files.h"
 #include "iceberg/update/row_delta.h"
 #include "iceberg/update/set_snapshot.h"
 #include "iceberg/update/snapshot_manager.h"
@@ -238,6 +239,12 @@ Result<std::shared_ptr<RowDelta>> Table::NewRowDelta() {
   return RowDelta::Make(name().name, std::move(ctx));
 }
 
+Result<std::shared_ptr<OverwriteFiles>> Table::NewOverwrite() {
+  ICEBERG_ASSIGN_OR_RAISE(
+      auto ctx, TransactionContext::Make(shared_from_this(), TransactionKind::kUpdate));
+  return OverwriteFiles::Make(name().name, std::move(ctx));
+}
+
 Result<std::shared_ptr<UpdateStatistics>> Table::NewUpdateStatistics() {
   ICEBERG_ASSIGN_OR_RAISE(
       auto ctx, TransactionContext::Make(shared_from_this(), TransactionKind::kUpdate));
@@ -349,6 +356,10 @@ Result<std::shared_ptr<RowDelta>> StaticTable::NewRowDelta() {
   return NotSupported("Cannot create a row delta for a static table");
 }
 
+Result<std::shared_ptr<OverwriteFiles>> StaticTable::NewOverwrite() {
+  return NotSupported("Cannot create an overwrite for a static table");
+}
+
 Result<std::shared_ptr<SnapshotManager>> StaticTable::NewSnapshotManager() {
   return NotSupported("Cannot create a snapshot manager for a static table");
 }

src/iceberg/table.h

@@ -185,6 +185,9 @@ class ICEBERG_EXPORT Table : public std::enable_shared_from_this<Table> {
   /// \brief Create a new RowDelta to add rows and row-level deletes.
   virtual Result<std::shared_ptr<RowDelta>> NewRowDelta();
 
+  /// \brief Create a new OverwriteFiles to overwrite data files and commit the changes.
+  virtual Result<std::shared_ptr<OverwriteFiles>> NewOverwrite();
+
   /// \brief Create a new SnapshotManager to manage snapshots and snapshot references.
   virtual Result<std::shared_ptr<SnapshotManager>> NewSnapshotManager();
 
@@ -258,6 +261,8 @@ class ICEBERG_EXPORT StaticTable : public Table {
 
   Result<std::shared_ptr<RowDelta>> NewRowDelta() override;
 
+  Result<std::shared_ptr<OverwriteFiles>> NewOverwrite() override;
+
   Result<std::shared_ptr<SnapshotManager>> NewSnapshotManager() override;
 
  private:

src/iceberg/test/CMakeLists.txt

@@ -239,7 +239,8 @@ if(ICEBERG_BUILD_BUNDLE)
                    update_properties_test.cc
                    update_schema_test.cc
                    update_sort_order_test.cc
-                   update_statistics_test.cc)
+                   update_statistics_test.cc
+                   overwrite_files_test.cc)
 
   add_iceberg_test(data_test
                    USE_BUNDLE