docs: add explicit error codes for commit failure categories

Add ValidationFailed error code and document specific error codes
returned by Apply() and Commit() methods:

- ValidationFailed: update cannot be applied to current metadata
- CommitFailed: update cannot be committed due to conflicts
- CommitStateUnknown: commit success state is unknown
- InvalidArgument: pending changes are conflicting

This allows callers to distinguish between different failure types,
matching the Java exception categories (ValidationException,
CommitFailedException, CommitStateUnknownException).

Addresses feedback from gty404 about defining explicit Status codes.

Author: shangxinli

src/iceberg/pending_update.h

@@ -46,8 +46,10 @@ class ICEBERG_EXPORT PendingUpdateBase {
   ///
   /// Once the commit is successful, the updated table will be refreshed.
   ///
-  /// \return Status::OK if the commit was successful, or an error status if
-  ///         validation failed or the commit encountered conflicts
+  /// \return Status::OK if the commit was successful, or an error:
+  ///         - ValidationFailed: if update cannot be applied to current metadata
+  ///         - CommitFailed: if update cannot be committed due to conflicts
+  ///         - CommitStateUnknown: if commit success state is unknown
   virtual Status Commit() = 0;
 
   // Non-copyable, movable
@@ -80,16 +82,19 @@ class ICEBERG_EXPORT PendingUpdate : public PendingUpdateBase {
   ///
   /// This does not result in a permanent update.
   ///
-  /// \return the uncommitted changes that would be committed, or an error if
-  ///         the pending changes cannot be applied to the current table metadata
+  /// \return the uncommitted changes that would be committed, or an error:
+  ///         - ValidationFailed: if pending changes cannot be applied
+  ///         - InvalidArgument: if pending changes are conflicting
   virtual Result<T> Apply() = 0;
 
   /// \brief Apply and commit the pending changes to the table
   ///
   /// Implements PendingUpdateBase::Commit().
   ///
-  /// \return Status::OK if the commit was successful, or an error status if
-  ///         validation failed or the commit encountered conflicts
+  /// \return Status::OK if the commit was successful, or an error:
+  ///         - ValidationFailed: if update cannot be applied to current metadata
+  ///         - CommitFailed: if update cannot be committed due to conflicts
+  ///         - CommitStateUnknown: if commit success state is unknown
   Status Commit() override = 0;
 
  protected:

src/iceberg/result.h

@@ -35,6 +35,7 @@ enum class ErrorKind {
   kDecompressError,
   kInvalid,  // For general invalid errors
   kInvalidArgument,
+  kValidationFailed,
   kInvalidArrowData,
   kInvalidExpression,
   kInvalidSchema,
@@ -84,6 +85,7 @@ DEFINE_ERROR_FUNCTION(CommitStateUnknown)
 DEFINE_ERROR_FUNCTION(DecompressError)
 DEFINE_ERROR_FUNCTION(Invalid)
 DEFINE_ERROR_FUNCTION(InvalidArgument)
+DEFINE_ERROR_FUNCTION(ValidationFailed)
 DEFINE_ERROR_FUNCTION(InvalidArrowData)
 DEFINE_ERROR_FUNCTION(InvalidExpression)
 DEFINE_ERROR_FUNCTION(InvalidSchema)