Core: Clarify the atomicity of BasePersistence methods (#1274)

Author: flyrain

polaris-core/src/main/java/org/apache/polaris/core/persistence/BasePersistence.java

@@ -38,6 +38,10 @@
  * defining the internal data model for Polaris, and which defines the basis for the RBAC model
  * provided by Polaris.
  *
+ * <p>Each method in this interface must be atomic, meaning that write operations must either fully
+ * succeed with all changes applied, or fail entirely without partial updates. Read operations must
+ * provide a consistent view of the data as it existed at the start of the operation.
+ *
  * <p>Note that APIs to the actual persistence store are very basic, often point read or write to
  * the underlying data store. The goal is to make it really easy to back this using databases like
  * Postgres or simpler KV store.

polaris-core/src/main/java/org/apache/polaris/core/persistence/IntegrationPersistence.java

@@ -31,6 +31,10 @@
  * persistence entities but which typically involve additional separate external integrations
  * related to identity/auth, kms/secrets storage, etc.
  *
+ * <p>Each method in this interface must be atomic, meaning that write operations must either fully
+ * succeed with all changes applied, or fail entirely without partial updates. Read operations must
+ * provide a consistent view of the data as it existed at the start of the operation.
+ *
  * <p>Implementations should orchestrate any necessary multi-phase protocols such as leasing an
  * external resource before committing a reference to the external resource in the Polaris
  * persistence layer, etc.