feat: Add error collection pattern to PendingUpdate

Implement error vector collection pattern in PendingUpdateTyped
to allow builder methods to accumulate validation errors instead
of failing fast. This enables users to see all validation issues
at once rather than fixing them one by one.

Changes:
- Add protected error collection methods (AddError, CheckErrors,
  HasErrors, ClearErrors) to PendingUpdateTyped base class
- Add std::vector<Error> errors_ member to collect validation errors
- Update PendingUpdate documentation with usage examples
- Add 6 comprehensive unit tests demonstrating error collection

Pattern follows TableMetadataBuilder implementation.

All tests pass (11/11).

Author: shangxinli

src/iceberg/pending_update.h

@@ -22,6 +22,9 @@
 /// \file iceberg/pending_update.h
 /// API for table changes using builder pattern
 
+#include <string>
+#include <vector>
+
 #include "iceberg/iceberg_export.h"
 #include "iceberg/result.h"
 #include "iceberg/type_fwd.h"
@@ -72,6 +75,30 @@ class ICEBERG_EXPORT PendingUpdate {
 /// Apply() can be used to validate and inspect the uncommitted changes before
 /// committing. Commit() applies the changes and commits them to the table.
 ///
+/// Error Collection Pattern:
+/// Builder methods in subclasses should use AddError() to collect validation
+/// errors instead of returning immediately. The accumulated errors will be
+/// returned by Apply() or Commit() when they are called. This allows users
+/// to see all validation errors at once rather than fixing them one by one.
+///
+/// Example usage in a subclass:
+/// \code
+///   MyUpdate& SetProperty(std::string_view key, std::string_view value) {
+///     if (key.empty()) {
+///       AddError(ErrorKind::kInvalidArgument, "Property key cannot be empty");
+///       return *this;
+///     }
+///     // ... continue with normal logic
+///     return *this;
+///   }
+///
+///   Result<T> Apply() override {
+///     // Check for accumulated errors first
+///     ICEBERG_RETURN_IF_ERROR(CheckErrors());
+///     // ... proceed with apply logic
+///   }
+/// \endcode
+///
 /// \tparam T The type of result returned by Apply()
 template <typename T>
 class ICEBERG_EXPORT PendingUpdateTyped : public PendingUpdate {
@@ -89,6 +116,51 @@ class ICEBERG_EXPORT PendingUpdateTyped : public PendingUpdate {
 
  protected:
   PendingUpdateTyped() = default;
+
+  /// \brief Add a validation error to be returned later
+  ///
+  /// Errors are accumulated and will be returned by Apply() or Commit().
+  /// This allows builder methods to continue and collect all errors rather
+  /// than failing fast on the first error.
+  ///
+  /// \param kind The kind of error
+  /// \param message The error message
+  void AddError(ErrorKind kind, std::string message) {
+    errors_.emplace_back(kind, std::move(message));
+  }
+
+  /// \brief Check if any errors have been collected
+  ///
+  /// \return true if there are accumulated errors
+  bool HasErrors() const { return !errors_.empty(); }
+
+  /// \brief Check for accumulated errors and return them if any exist
+  ///
+  /// This should be called at the beginning of Apply() or Commit() to
+  /// return all accumulated validation errors.
+  ///
+  /// \return Status::OK if no errors, or a ValidationFailed error with
+  ///         all accumulated error messages
+  Status CheckErrors() const {
+    if (!errors_.empty()) {
+      std::string error_msg = "Validation failed due to the following errors:\n";
+      for (const auto& [kind, message] : errors_) {
+        error_msg += "  - " + message + "\n";
+      }
+      return ValidationFailed("{}", error_msg);
+    }
+    return {};
+  }
+
+  /// \brief Clear all accumulated errors
+  ///
+  /// This can be useful for resetting the error state in tests or
+  /// when reusing a builder instance.
+  void ClearErrors() { errors_.clear(); }
+
+ private:
+  // Error collection (since builder methods return *this and cannot throw)
+  std::vector<Error> errors_;
 };
 
 }  // namespace iceberg

src/iceberg/test/pending_update_test.cc

@@ -27,21 +27,61 @@
 namespace iceberg {
 
 // Mock implementation for testing the interface
-class MockSnapshot {};
+class MockSnapshot {
+ public:
+  std::string name;
+};
 
 class MockPendingUpdate : public PendingUpdateTyped<MockSnapshot> {
  public:
   MockPendingUpdate() = default;
 
+  // Builder-style methods that use error collection
+  MockPendingUpdate& SetName(std::string_view name) {
+    if (name.empty()) {
+      AddError(ErrorKind::kInvalidArgument, "Name cannot be empty");
+      return *this;
+    }
+    if (name.length() > 100) {
+      AddError(ErrorKind::kInvalidArgument, "Name cannot exceed 100 characters");
+      return *this;
+    }
+    name_ = name;
+    return *this;
+  }
+
+  MockPendingUpdate& SetId(int64_t id) {
+    if (id < 0) {
+      AddError(ErrorKind::kInvalidArgument, "ID must be non-negative");
+      return *this;
+    }
+    id_ = id;
+    return *this;
+  }
+
   Result<MockSnapshot> Apply() override {
+    // Check for accumulated errors first
+    auto error_status = CheckErrors();
+    if (!error_status.has_value()) {
+      return std::unexpected(error_status.error());
+    }
+
     if (should_fail_) {
       return ValidationFailed("Mock validation failed");
     }
     apply_called_ = true;
-    return MockSnapshot{};
+    MockSnapshot snapshot;
+    snapshot.name = name_;
+    return snapshot;
   }
 
   Status Commit() override {
+    // Check for accumulated errors first
+    auto error_status = CheckErrors();
+    if (!error_status.has_value()) {
+      return error_status;
+    }
+
     if (should_fail_commit_) {
       return CommitFailed("Mock commit failed");
     }
@@ -55,6 +95,8 @@ class MockPendingUpdate : public PendingUpdateTyped<MockSnapshot> {
   bool CommitCalled() const { return commit_called_; }
 
  private:
+  std::string name_;
+  int64_t id_ = 0;
   bool should_fail_ = false;
   bool should_fail_commit_ = false;
   bool apply_called_ = false;
@@ -96,4 +138,67 @@ TEST(PendingUpdateTest, BaseClassPolymorphism) {
   EXPECT_THAT(status, IsOk());
 }
 
+// Error collection tests
+TEST(PendingUpdateTest, ErrorCollectionSingleError) {
+  MockPendingUpdate update;
+  update.SetName("");  // This should add an error
+
+  auto result = update.Apply();
+  EXPECT_THAT(result, IsError(ErrorKind::kValidationFailed));
+  EXPECT_THAT(result, HasErrorMessage("Name cannot be empty"));
+}
+
+TEST(PendingUpdateTest, ErrorCollectionMultipleErrors) {
+  MockPendingUpdate update;
+  update.SetName("");  // Error: empty name
+  update.SetId(-5);    // Error: negative ID
+
+  auto result = update.Apply();
+  EXPECT_THAT(result, IsError(ErrorKind::kValidationFailed));
+  // Should contain both error messages
+  EXPECT_THAT(result, HasErrorMessage("Name cannot be empty"));
+  EXPECT_THAT(result, HasErrorMessage("ID must be non-negative"));
+}
+
+TEST(PendingUpdateTest, ErrorCollectionInCommit) {
+  MockPendingUpdate update;
+  update.SetName("");  // This should add an error
+
+  auto status = update.Commit();
+  EXPECT_THAT(status, IsError(ErrorKind::kValidationFailed));
+  EXPECT_THAT(status, HasErrorMessage("Name cannot be empty"));
+}
+
+TEST(PendingUpdateTest, ErrorCollectionValidInputNoErrors) {
+  MockPendingUpdate update;
+  update.SetName("valid_name");
+  update.SetId(42);
+
+  auto result = update.Apply();
+  EXPECT_THAT(result, IsOk());
+  EXPECT_EQ(result->name, "valid_name");
+}
+
+TEST(PendingUpdateTest, ErrorCollectionBuilderChaining) {
+  MockPendingUpdate update;
+  // Test that builder methods can be chained even when errors occur
+  update.SetName("").SetId(-1);
+
+  auto result = update.Apply();
+  EXPECT_THAT(result, IsError(ErrorKind::kValidationFailed));
+  // Should contain both errors
+  EXPECT_THAT(result, HasErrorMessage("Name cannot be empty"));
+  EXPECT_THAT(result, HasErrorMessage("ID must be non-negative"));
+}
+
+TEST(PendingUpdateTest, ErrorCollectionPartialValidation) {
+  MockPendingUpdate update;
+  update.SetName("valid_name");  // Valid
+  update.SetId(-1);              // Error
+
+  auto result = update.Apply();
+  EXPECT_THAT(result, IsError(ErrorKind::kValidationFailed));
+  EXPECT_THAT(result, HasErrorMessage("ID must be non-negative"));
+}
+
 }  // namespace iceberg