fix(platform-wallet): typed persister errors with caller-visible retry classification

packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/errors/DashSdkError.kt

@@ -3,6 +3,17 @@ package org.dashfoundation.dashsdk.errors
 import org.dashfoundation.dashsdk.ffi.DashSDKException
 import org.json.JSONObject
 
+// Display text for the persister failures, whose native message is a nested
+// Rust error chain (operation, backend classification, the store's own
+// phrasing) that no user can act on. One string per outcome a person can
+// distinguish; a failed read and a failed write must not describe each other.
+private const val PERSISTER_BUSY_USER_MESSAGE =
+    "The wallet database is busy. Try again in a moment."
+private const val PERSISTER_UNREADABLE_USER_MESSAGE =
+    "The wallet data could not be read and may need to be restored."
+private const val PERSISTER_UNSAVED_USER_MESSAGE =
+    "The wallet data could not be saved and may need to be restored."
+
 /**
  * Public error hierarchy of the Kotlin SDK — the Android analog of the
  * Swift SDK's `UserFacingError`/`SDKError` split, keyed off the native
@@ -19,6 +30,14 @@ sealed class DashSdkError(
     /** Whether retrying the same operation can plausibly succeed. */
     open val isRetryable: Boolean get() = false
 
+    /**
+     * Text fit to show a person. Defaults to [message] — most native
+     * messages read as a sentence — but types whose message is a nested
+     * error chain override it, so a UI can display this unconditionally
+     * while logs keep [message].
+     */
+    open val userMessage: String get() = message.orEmpty()
+
     class InvalidParameter(message: String, cause: Throwable? = null) :
         DashSdkError(message, cause)
 
@@ -478,6 +497,93 @@ sealed class DashSdkError(
             cause,
         )
 
+        /**
+         * `ErrorPersisterLoadTransient` (native code 49). Reading persisted
+         * wallet state failed on a store that reported the failure as
+         * retryable (`SQLITE_BUSY` and friends). Nothing was mutated — a
+         * load is a read — so this is retryable. The Android analog of
+         * Swift's `PlatformWalletError.persisterLoadTransient`. [message] is
+         * the diagnostic chain; display [userMessage].
+         */
+        class PersisterLoadTransient(message: String, cause: Throwable? = null) :
+            PlatformWallet(message, cause) {
+            override val isRetryable: Boolean get() = true
+            override val userMessage: String get() = PERSISTER_BUSY_USER_MESSAGE
+        }
+
+        /**
+         * `ErrorPersisterLoadFatal` (native code 50). Reading persisted
+         * wallet state failed permanently — a corrupt or unreadable store,
+         * or a decode that will fail identically next time. Do NOT retry;
+         * the store needs repair or re-provisioning. Constraint-class read
+         * failures fold in here: a read cannot violate one, and neither is
+         * retryable. [message] is the diagnostic chain; display
+         * [userMessage].
+         */
+        class PersisterLoadFatal(message: String, cause: Throwable? = null) :
+            PlatformWallet(message, cause) {
+            override val userMessage: String get() = PERSISTER_UNREADABLE_USER_MESSAGE
+        }
+
+        /**
+         * `ErrorPersisterStoreTransient` (native code 51). Writing wallet
+         * state failed on a busy or momentarily unavailable store.
+         *
+         * **Nothing was committed.** The native side only emits this when
+         * the persister guarantees the failed changeset round was rolled
+         * back whole, so re-issuing the operation cannot double-apply part
+         * of it — which is why this, uniquely among the store failures, is
+         * retryable. A wallet registration against a locked database
+         * produces it (dashpay/platform#4365); the retry decision is the
+         * host's, not the wallet's. [message] is the diagnostic chain;
+         * display [userMessage].
+         */
+        class PersisterStoreTransient(message: String, cause: Throwable? = null) :
+            PlatformWallet(message, cause) {
+            override val isRetryable: Boolean get() = true
+            override val userMessage: String get() = PERSISTER_BUSY_USER_MESSAGE
+        }
+
+        /**
+         * `ErrorPersisterStoreFatal` (native code 52). Writing wallet state
+         * failed permanently — a full disk, a corrupt schema, an I/O error
+         * outside the retryable class. Do NOT retry; the wallet rolled its
+         * in-memory state back, so the operation may be re-attempted once
+         * the underlying fault is fixed. [message] is the diagnostic chain;
+         * display [userMessage].
+         */
+        class PersisterStoreFatal(message: String, cause: Throwable? = null) :
+            PlatformWallet(message, cause) {
+            override val userMessage: String get() = PERSISTER_UNSAVED_USER_MESSAGE
+        }
+
+        /**
+         * `ErrorPersisterStoreConstraint` (native code 53). A write violated
+         * a constraint / foreign key / integrity rule. Deliberately distinct
+         * from [PersisterStoreFatal]: this is "the data is wrong" (a caller
+         * or schema-mapping bug) rather than "the storage engine is unhappy"
+         * (an operator problem), and the two route to different people. Do
+         * NOT retry unchanged. [message] is the diagnostic chain; display
+         * [userMessage].
+         */
+        class PersisterStoreConstraint(message: String, cause: Throwable? = null) :
+            PlatformWallet(message, cause) {
+            override val userMessage: String get() = PERSISTER_UNSAVED_USER_MESSAGE
+        }
+
+        /**
+         * `ErrorPersisterRestore` (native code 54). Rehydrating persisted
+         * platform-address state into a freshly registered wallet failed.
+         * One code rather than three: it wraps a wallet error, not a store
+         * error, so it carries no retry classification. The wrapped error's
+         * rendering is in [message], which is diagnostic — display
+         * [userMessage].
+         */
+        class PersisterRestore(message: String, cause: Throwable? = null) :
+            PlatformWallet(message, cause) {
+            override val userMessage: String get() = PERSISTER_UNREADABLE_USER_MESSAGE
+        }
+
         /**
          * Any other `PlatformWalletFFIResultCode` without a dedicated type.
          * Carries the platform-wallet [nativeCode] (already de-offset) and
@@ -657,6 +763,17 @@ sealed class DashSdkError(
             // the deferred-token trio sits at 34-36 above. See
             // PlatformWalletFFIResultCode for the authoritative map.)
             31 -> PlatformWallet.SigningKeyUnavailable(message, cause)
+            // Persister failures, operation x retry classification. These are
+            // exactly the "retry-semantics-bearing" codes this mapping exists
+            // for: only the two transients are retryable, and a constraint is
+            // kept apart from a fatal so hosts can route "your data is wrong"
+            // differently from "the storage engine is unhappy".
+            49 -> PlatformWallet.PersisterLoadTransient(message, cause)
+            50 -> PlatformWallet.PersisterLoadFatal(message, cause)
+            51 -> PlatformWallet.PersisterStoreTransient(message, cause)
+            52 -> PlatformWallet.PersisterStoreFatal(message, cause)
+            53 -> PlatformWallet.PersisterStoreConstraint(message, cause)
+            54 -> PlatformWallet.PersisterRestore(message, cause)
             else ->
                 // @Deprecated fallback — see the code-6 arm; code 31 is the
                 // real discriminator.

packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/ffi/NativePersistenceBridge.kt

@@ -32,9 +32,27 @@ package org.dashfoundation.dashsdk.ffi
  *   [onWalletChangesetAccountBegin] / [onWalletChangesetAccountEnd].
  * - Persist slots return `Int` (0 = ok, non-zero flips the round's
  *   success flag so [onChangesetEnd] delivers the rollback).
+ * - A plain non-zero return means "failed, do not retry". A handler that
+ *   can classify its own failure may instead return one of the two
+ *   sentinels `platform-wallet-ffi` defines — [PERSIST_RC_TRANSIENT] for
+ *   a retryable failure after which nothing was applied, or
+ *   [PERSIST_RC_CONSTRAINT] for an integrity violation. The native side
+ *   forwards the classification to its caller (surfacing as
+ *   `DashSdkError.PlatformWallet.PersisterStoreTransient` and friends) and
+ *   never retries on the handler's behalf. Returning the transient
+ *   sentinel from a ROUND callback additionally asserts that a failed
+ *   round is rolled back whole — see `PersistenceCallbacks` in
+ *   `rs-platform-wallet-ffi/src/persistence.rs` for the exact contract.
  * - Load slots return flattened representations (`Array<...>` / typed
  *   holder objects) that the trampoline re-packs into Rust-owned FFI
- *   structs; Kotlin never allocates native memory.
+ *   structs; Kotlin never allocates native memory. **Only the
+ *   `Int`-returning persist slots can carry a sentinel.** A load has no
+ *   `Int` to put one in, so every load failure — a thrown exception
+ *   included — reaches Rust as a fatal, unclassified error, and no load
+ *   on this binding can report itself as transient or constraint-class.
+ *   A subclass must therefore let a failed load THROW: returning an empty
+ *   array reports a successful restore of nothing, which Rust reads as a
+ *   fresh device, turning a store fault into apparent data loss.
  *
  * ## Threading
  *
@@ -50,17 +68,29 @@ package org.dashfoundation.dashsdk.ffi
  */
 abstract class NativePersistenceBridge {
 
-    /**
-     * Versioned semantic capability declaration consumed when JNI builds the
-     * native callback vtable. Defaults are deliberately zero: a no-op subclass
-     * must never gain capabilities merely because JNI supplies trampolines for
-     * every virtual method.
-     */
-    open fun persistenceCapabilitiesVersion(): Int = 0
+    companion object {
+        // Both values are the ABI defined by
+        // `packages/rs-platform-wallet-ffi/src/persistence.rs` and must
+        // change only together with it.
 
-    open fun persistenceCapabilitiesBits(): Long = 0L
+        /**
+         * A retryable failure after which nothing was applied. Returning it
+         * from a callback inside a changeset round also asserts that the
+         * failed round was rolled back whole.
+         *
+         * The round-end callback is the exception: failing it when the round
+         * had already failed means the rollback itself did not complete, so
+         * what reached the store is unknown. Rust classifies that as fatal and
+         * withholds the retry regardless of this value — re-issuing a
+         * changeset the store could neither apply nor undo risks merging it
+         * twice. This sentinel is honoured at round end only on a clean
+         * round, where the commit failed but the rollback succeeded.
+         */
+        const val PERSIST_RC_TRANSIENT: Int = -2
+
+        /** A constraint / integrity violation — the data is wrong, not the store. */
+        const val PERSIST_RC_CONSTRAINT: Int = -3
 
-    companion object {
         /**
          * `PersistenceCapabilities::CORE_SWEEP_REMOVAL` (bit 11, `0x800`).
          * The one Kotlin home of this bit: `PlatformWalletPersistenceHandler`
@@ -71,6 +101,16 @@ abstract class NativePersistenceBridge {
         const val CAPABILITY_CORE_SWEEP_REMOVAL: Long = 0x800
     }
 
+    /**
+     * Versioned semantic capability declaration consumed when JNI builds the
+     * native callback vtable. Defaults are deliberately zero: a no-op subclass
+     * must never gain capabilities merely because JNI supplies trampolines for
+     * every virtual method.
+     */
+    open fun persistenceCapabilitiesVersion(): Int = 0
+
+    open fun persistenceCapabilitiesBits(): Long = 0L
+
     // ── Transactional bracketing ──────────────────────────────────────
 
     /** `on_changeset_begin_fn` — descriptor `([B)I`. */
@@ -729,6 +769,10 @@ abstract class NativePersistenceBridge {
     ): Int = 0
 
     // ── Load callbacks ────────────────────────────────────────────────
+    //
+    // These return objects rather than `Int`, so [PERSIST_RC_TRANSIENT] and
+    // [PERSIST_RC_CONSTRAINT] cannot be expressed here: a failing load
+    // reaches Rust as a fatal, unclassified error however it fails.
 
     /**
      * `on_load_wallet_list_fn`. Returns the persisted wallet list as an