react-native-nitro-storage 0.12.0 → 0.14.0

package/CHANGELOG.md

@@ -6,6 +6,53 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 Breaking changes are always listed first in each release section.
 
+## [0.14.0] - 2026-10-03
+
+### Breaking changes
+
+- Transaction and migration callbacks must finish synchronously. Promise and thenable results now throw `TypeError`, roll back writes made through the transaction context, and leave migration versions unchanged. Context methods reject calls after the callback ends. Migration: finish asynchronous work before entering the callback and keep all context access inside it. TypeScript now rejects direct async callbacks.
+
+### Added
+
+- `storage.setScheduledFlushErrorObserver()` reports scheduled Disk and Secure flush failures with their scope and backend adapter error. Failed writes stay queued for retry. Explicit flush calls still throw to their caller, and scheduled failures still propagate when no observer is installed.
+
+### Documentation
+
+- `flushSecureWrites()` drains the JavaScript queue; it is not an Android `apply()` durability barrier. Select synchronous secure-write mode before writes that need synchronous native persistence.
+- Biometric policy documentation now distinguishes iOS Keychain prompts from Android authentication when a protected store first opens and its cached keyset on later access.
+
+## [0.13.0] - 2026-10-01
+
+### Breaking changes
+
+- **Android no longer deletes a corrupt Disk database.** In 0.12.0, Android replaced a corrupt Disk database with an empty one when it opened. Now the file is kept and every Disk call fails with `storage_corruption`, as on iOS, until the app calls `storage.clear(StorageScope.Disk)` or `storage.clearAll()`. Migration: catch `storage_corruption` on Disk calls and call `storage.clear(StorageScope.Disk)` when the app can continue without the stored data.
+- **iOS reports undecodable Secure data as `storage_corruption`.** Reading a Secure or biometric item whose Keychain data is empty or is not UTF-8 text failed with an untagged `failed with status 0` error. It now fails with the `storage_corruption` code. The item can still be deleted or replaced. Migration: handle `storage_corruption` on Secure reads if you matched the old message.
+
+### Added
+
+- `storage.clear(StorageScope.Disk)` and `storage.clearAll()` recover a corrupt Disk database on iOS and Android: they delete the database and its journal files and create an empty store. `clear` with `except`, namespace clears, and `removeByPrefix` need to read keys and still fail on a corrupt database.
+- `storage.clear(StorageScope.Disk)` works on a full device. When the delete fails with `storage_full`, the database is deleted and created again, which frees its space.
+
+### Changed
+
+- Android Disk uses SQLite WAL. 0.12.0 documented WAL but did not enable it. An existing database converts on first open and keeps its rows. If the conversion cannot run, for example on a full device, the database opens without WAL so reads keep working, and the next launch tries again. With WAL and `synchronous=NORMAL`, a power loss can drop the most recent commits; an app kill cannot. This matches iOS.
+- `getKeysByPrefix` on Disk uses the key index instead of reading every key, on iOS and Android. On iOS, `size(StorageScope.Disk)` no longer builds the full key list. Results are unchanged.
+
+### Fixed
+
+- `storage.clear(StorageScope.Disk)` no longer fails before it reaches native storage when a Disk listener or event observer is registered and the stored values cannot be read, or when pending async Disk writes cannot be flushed. The pending writes are dropped and listeners receive a `clear` batch with no key changes.
+- Android: `setBatch`, `removeBatch`, and the first-launch import report a full Disk database with the `storage_full` code. They used to fail with an untagged `cannot rollback` error.
+- Android: Disk values larger than 2 MiB can be read. They could be written but not read.
+- Android: a Disk I/O error that occurs with less than 1 MiB of free space carries the `storage_full` code. Read errors do not.
+- iOS: Disk I/O errors caused by a full device or an exceeded quota carry the `storage_full` code, including while the database opens.
+- iOS: a Disk read of a legacy value that is not yet migrated no longer fails when the Disk database is full.
+- iOS: `clearSecureBiometric` reports an unavailable Keychain with the `keychain_locked` code.
+- iOS: the Disk WAL file is truncated after checkpoints on every SQLite build.
+- iOS: a Disk key that is not valid UTF-8 is rejected before anything is written or removed.
+- `removeByPrefix("", scope)` rejects an invalid scope.
+- Unknown native failures in `hasSecureBiometric`, `setSecureAccessControl`, `setSecureWritesAsync`, and `setKeychainAccessGroup` surface as a `NitroStorage: … failed (unknown error)` error.
+- The Android library declares its unit-test dependencies only inside the repository, so consumer builds do not resolve them.
+
 ## [0.12.0] - 2026-10-01
 
 ### Breaking changes

package/README.md

@@ -91,7 +91,7 @@ before installing this package, then rebuild the native app so the generated
 Nitro bindings and native runtime use the same major-minor version:
 
 ```sh
-bun add react-native-nitro-modules@0.37.1 react-native-nitro-storage@0.12.0
+bun add react-native-nitro-modules@0.37.1 react-native-nitro-storage@0.14.0
 bunx expo prebuild
 ```
 
@@ -491,9 +491,12 @@ explicitly opt into `{ includeSecureValues: true }`.
 
 Android secure writes default to synchronous `commit()` durability. Call
 `storage.setSecureWritesAsync(true)` only when asynchronous `apply()` writes are
-acceptable. After opting into async writes, call `storage.flushSecureWrites()`
-before a deterministic persistence boundary. A failed secure flush throws and
-keeps failed or unattempted queued writes available for retry.
+acceptable. `storage.flushSecureWrites()` drains the JavaScript write queue into
+the native backend; it does not wait for Android `apply()` to reach disk. Keep
+the default synchronous mode, or call `storage.setSecureWritesAsync(false)`
+before the writes that need synchronous native persistence. Changing the mode
+does not make earlier `apply()` calls durable retroactively. A failed explicit
+flush throws and keeps failed or unattempted queued writes available for retry.
 `storage.clearBiometric()`
 flushes pending Secure writes before clearing biometric entries and surfaces
 native clear failures.
@@ -538,6 +541,43 @@ Biometric behaviour differs by platform:
   before every read that must be gated. Reading a `BiometryOrPasscode` item
   opens only that store, so a device-credential authentication is enough.
 
+Scheduled Disk and Secure flush failures can be handled without losing the
+pending writes:
+
+```ts
+import {
+  storage,
+  type StorageScheduledFlushError,
+} from "react-native-nitro-storage";
+
+let lastFlushFailure: StorageScheduledFlushError | undefined;
+storage.setScheduledFlushErrorObserver((failure) => {
+  lastFlushFailure = failure;
+});
+
+// Call after resolving the failure, such as freeing space or unlocking storage.
+function retryPendingWrites() {
+  storage.flushDiskWrites();
+  storage.flushSecureWrites();
+  lastFlushFailure = undefined;
+}
+
+// Remove the observer when its owner is disposed.
+function stopObservingFlushErrors() {
+  storage.setScheduledFlushErrorObserver(undefined);
+}
+```
+
+The observer receives the failed scope and the error thrown by the backend
+adapter. Web adapters may wrap the underlying failure in an error with `cause`.
+It replaces
+the uncaught scheduled-flush error only while installed; without an observer,
+the error still propagates. Explicit flush calls always throw to their caller,
+and an observer that throws also propagates its error. Register one observer per
+storage instance and handle retry failures at the calling boundary. The observer
+reports the synchronous backend handoff; it cannot report a later Android
+`apply()` or IndexedDB persistence failure that the backend does not expose.
+
 ## Batch Operations
 
 `getBatch()` preserves tuple value types, so IDEs infer each result from the
@@ -666,10 +706,16 @@ migrateFromMMKV(mmkvInstance, themeItem);
 
 `runTransaction(scope, callback)` rolls back every write made through the `tx`
 context if the callback throws, then emits one typed `rollback` batch event.
+Callbacks must be synchronous. A Promise or thenable return throws a `TypeError`
+and rolls back changes made through the context. Every context method becomes
+unavailable when the callback ends, including for a continuation after `await`.
+Complete asynchronous work before calling `runTransaction()` or registering a
+migration; do not retain the context outside its callback.
 
 Each migration step runs in its own transaction with its version marker, so a
 failed step leaves the scope on the last completed version and rerunning
 `migrateToLatest()` retries deterministically.
+An asynchronous migration is rejected without advancing its version marker.
 
 ## Web Backends
 
@@ -752,17 +798,17 @@ Native and web adapters tag classified failures with stable error codes. Use
 Errors never swallow the underlying cause silently: the original platform
 message is preserved on the error for diagnostics.
 
-| Code                          | Meaning                                                                                                                                               |
-| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `keychain_locked`             | The protected store is locked. Retry after the device unlocks.                                                                                        |
-| `authentication_required`     | The item needs user authentication, or the user cancelled the prompt.                                                                                 |
-| `key_invalidated`             | The protecting key was invalidated, for example by a biometric enrolment change.                                                                      |
-| `biometric_unavailable`       | The requested biometric level is not available on this device or OS version.                                                                          |
-| `storage_corruption`          | Stored secure data could not be decrypted, the Disk database is corrupt, or (Android) the Secure master key or store cannot be created. Do not retry. |
-| `storage_compensation_failed` | A multi-step write failed and restoring the previous state also failed.                                                                               |
-| `unsupported`                 | The operation is not available on this platform or environment.                                                                                       |
-| `storage_full`                | The device or database is out of space, or the web storage quota is exceeded. Free space before retrying.                                             |
-| `invalid_key`                 | The storage key is empty. Keys must be non-empty strings.                                                                                             |
+| Code                          | Meaning                                                                                                                                             |
+| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `keychain_locked`             | The protected store is locked. Retry after the device unlocks.                                                                                      |
+| `authentication_required`     | The item needs user authentication, or the user cancelled the prompt.                                                                               |
+| `key_invalidated`             | The protecting key was invalidated, for example by a biometric enrolment change.                                                                    |
+| `biometric_unavailable`       | The requested biometric level is not available on this device or OS version.                                                                        |
+| `storage_corruption`          | Stored secure data could not be decoded, the Disk database is corrupt, or (Android) the Secure master key or store cannot be created. Do not retry. |
+| `storage_compensation_failed` | A multi-step write failed and restoring the previous state also failed.                                                                             |
+| `unsupported`                 | The operation is not available on this platform or environment.                                                                                     |
+| `storage_full`                | The device or database is out of space, or the web storage quota is exceeded. Free space before retrying.                                           |
+| `invalid_key`                 | The storage key is empty. Keys must be non-empty strings.                                                                                           |
 
 Invalid scopes and non-finite numeric levels are rejected with untagged errors
 before they reach native storage.
@@ -788,6 +834,44 @@ function saveDraft(draft: string): "saved" | "storage_full" {
 }
 ```
 
+A full device does not block cleanup. `storage.clear(StorageScope.Disk)`
+deletes and recreates the Disk database when a normal delete fails with
+`storage_full`, which frees the space the database used. `remove` and
+`removeBatch` can still fail with `storage_full`, because a delete also writes
+to the database log.
+
+A corrupt Disk database is never deleted automatically. Every Disk call fails
+with `storage_corruption` until the app clears Disk storage:
+
+```ts
+import {
+  isStorageError,
+  storage,
+  StorageScope,
+} from "react-native-nitro-storage";
+
+function readDraft(): string | undefined {
+  try {
+    return storage.getString("draft", StorageScope.Disk);
+  } catch (error) {
+    if (!isStorageError(error, "storage_corruption")) throw error;
+    storage.clear(StorageScope.Disk);
+    return undefined;
+  }
+}
+```
+
+`storage.clear(StorageScope.Disk)` and `storage.clearAll()` are the recovery
+calls. `clear` with `except`, namespace clears, and `removeByPrefix` read keys
+first and fail on a corrupt database. A `clear` batch event with an empty
+`changes` array means every key in that scope was removed and the previous
+values could not be read; treat all keys in the scope as deleted.
+
+On Android, Disk values above 512 KiB are read in 512 KiB chunks, and read
+time grows faster than value size (about 30 ms for 5 MiB and 265 ms for 20 MiB
+in a host measurement; devices are slower). Keep single Disk values below about
+5 MiB.
+
 ## Platform Support
 
 | Platform               | Status                                             |
@@ -812,6 +896,7 @@ function saveDraft(draft: string): "saved" | "storage_full" {
 | Native libraries                    | [docs/native-libraries.md](docs/native-libraries.md)                           |
 | Recipes                             | [docs/recipes.md](docs/recipes.md)                                             |
 | Benchmarks                          | [docs/benchmarks.md](docs/benchmarks.md)                                       |
+| Example replay coverage             | [docs/qa/agent-device-replay.md](docs/qa/agent-device-replay.md)               |
 | Security policy                     | [SECURITY.md](SECURITY.md)                                                     |
 
 ## Troubleshooting
@@ -849,6 +934,13 @@ Nitro, secure storage, or packaging files. GitHub CI does not build the Android
 or iOS example. The package release path also validates package contents and
 dry-run publish behavior.
 
+Run `bun run example:replay:check` to check that replay coverage matches package
+and example sources. After reviewing affected assertions, use
+`bun run example:replay:refresh` to update the source lock. Device execution uses
+`bun run example:replay --platform ios --udid <exact-target>` or
+`--platform android --serial <exact-target>`; see the
+[replay guide](docs/qa/agent-device-replay.md) for prerequisites and coverage limits.
+
 `bun run benchmark` measures only the built web entry with an isolated private
 localStorage implementation; it is not a native Disk or Secure benchmark. See
 [docs/benchmarks.md](docs/benchmarks.md) for sampling and interpretation limits.

package/SECURITY.md

@@ -6,8 +6,8 @@ Security fixes are shipped for the latest published `0.x` release line.
 
 | Version  | Supported |
 | -------- | --------- |
-| `0.11.x` | Yes       |
-| `< 0.11` | No        |
+| `0.13.x` | Yes       |
+| `< 0.13` | No        |
 
 ## Reporting a Vulnerability
 

package/android/build.gradle

@@ -83,4 +83,9 @@ dependencies {
   implementation "com.facebook.react:react-native:+"
   implementation "androidx.security:security-crypto:1.1.0"
   implementation project(":react-native-nitro-modules")
+
+  if (file("src/test").exists()) {
+    testImplementation "junit:junit:4.13.2"
+    testImplementation "org.robolectric:robolectric:4.13"
+  }
 }

package/android/src/main/cpp/AndroidStorageAdapterCpp.cpp

@@ -1,4 +1,5 @@
 #include "AndroidStorageAdapterCpp.hpp"
+#include "JniSize.hpp"
 
 #include <limits>
 #include <stdexcept>
@@ -13,11 +14,8 @@ namespace {
 local_ref<JString> toJavaString(const std::string& value) {
     // fbjni's std::string overload uses c_str(), which truncates embedded NUL.
     if (value.find('\0') == std::string::npos) return make_jstring(value);
-    if (value.size() > static_cast<size_t>(std::numeric_limits<jsize>::max())) {
-        throw std::length_error("Storage string exceeds the Java array limit");
-    }
-    const auto size = static_cast<jsize>(value.size());
-    auto bytes = JArrayByte::newArray(size);
+    const jsize size = toJniSize(value.size(), "Storage string exceeds the Java array limit");
+    auto bytes = JArrayByte::newArray(value.size());
     bytes->setRegion(0, size, reinterpret_cast<const jbyte*>(value.data()));
     static auto constructor = JString::javaClassStatic()->getConstructor<
         jstring(jbyteArray, jstring)>();
@@ -26,10 +24,11 @@ local_ref<JString> toJavaString(const std::string& value) {
 }
 
 local_ref<JavaStringArray> toJavaStringArray(const std::vector<std::string>& values) {
-    auto javaArray = JavaStringArray::newArray(static_cast<jsize>(values.size()));
+    toJniSize(values.size(), "Storage batch exceeds the Java array limit");
+    auto javaArray = JavaStringArray::newArray(values.size());
     for (size_t i = 0; i < values.size(); ++i) {
         auto javaValue = toJavaString(values[i]);
-        javaArray->setElement(static_cast<jsize>(i), javaValue.get());
+        javaArray->setElement(i, javaValue.get());
     }
     return javaArray;
 }
@@ -38,9 +37,9 @@ std::vector<std::optional<std::string>> fromNullableJavaStringArray(alias_ref<Ja
     std::vector<std::optional<std::string>> parsedValues;
     if (!values) return parsedValues;
 
-    const jsize size = static_cast<jsize>(values->size());
+    const size_t size = values->size();
     parsedValues.reserve(size);
-    for (jsize i = 0; i < size; ++i) {
+    for (size_t i = 0; i < size; ++i) {
         auto currentValue = values->getElement(i);
         if (!currentValue) {
             parsedValues.push_back(std::nullopt);
@@ -53,10 +52,10 @@ std::vector<std::optional<std::string>> fromNullableJavaStringArray(alias_ref<Ja
 
 std::vector<std::string> fromJavaStringArray(alias_ref<JavaStringArray> values) {
     if (!values) return {};
-    const jsize size = values->size();
+    const size_t size = values->size();
     std::vector<std::string> result;
     result.reserve(size);
-    for (jsize i = 0; i < size; ++i) {
+    for (size_t i = 0; i < size; ++i) {
         auto currentValue = values->getElement(i);
         // Null entries are dropped so a missing key can never surface as the
         // empty-string clear sentinel used by change listeners.
@@ -115,7 +114,7 @@ std::vector<std::string> AndroidStorageAdapterCpp::getKeysByPrefixDisk(const std
 
 size_t AndroidStorageAdapterCpp::sizeDisk() {
     static auto method = AndroidStorageAdapterJava::javaClassStatic()->getStaticMethod<jint()>("sizeDisk");
-    return static_cast<size_t>(method(AndroidStorageAdapterJava::javaClassStatic()));
+    return fromJniSize(method(AndroidStorageAdapterJava::javaClassStatic()));
 }
 
 void AndroidStorageAdapterCpp::setDiskBatch(
@@ -199,7 +198,7 @@ std::vector<std::string> AndroidStorageAdapterCpp::getKeysByPrefixSecure(const s
 
 size_t AndroidStorageAdapterCpp::sizeSecure() {
     static auto method = AndroidStorageAdapterJava::javaClassStatic()->getStaticMethod<jint()>("sizeSecure");
-    return static_cast<size_t>(method(AndroidStorageAdapterJava::javaClassStatic()));
+    return fromJniSize(method(AndroidStorageAdapterJava::javaClassStatic()));
 }
 
 void AndroidStorageAdapterCpp::setSecureBatch(

package/android/src/main/cpp/JniSize.hpp

@@ -0,0 +1,21 @@
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+#include <limits>
+#include <stdexcept>
+
+namespace NitroStorage {
+
+inline int32_t toJniSize(size_t size, const char* what) {
+    if (size > static_cast<size_t>(std::numeric_limits<int32_t>::max())) {
+        throw std::length_error(what);
+    }
+    return static_cast<int32_t>(size);
+}
+
+inline size_t fromJniSize(int32_t size) {
+    return size > 0 ? static_cast<size_t>(size) : 0;
+}
+
+} // namespace NitroStorage

package/android/src/main/java/com/nitrostorage/AndroidStorageAdapter.kt

@@ -4,9 +4,11 @@ package com.nitrostorage
 
 import android.content.Context
 import android.database.sqlite.SQLiteDatabaseCorruptException
+import android.database.sqlite.SQLiteDiskIOException
 import android.database.sqlite.SQLiteException
 import android.database.sqlite.SQLiteFullException
 import android.os.Build
+import android.os.StatFs
 import android.security.keystore.KeyGenParameterSpec
 import android.security.keystore.KeyPermanentlyInvalidatedException
 import android.security.keystore.KeyProperties
@@ -20,7 +22,7 @@ import java.security.KeyStore
 import java.security.KeyStoreException
 import javax.crypto.AEADBadTagException
 
-private fun Throwable.hasCause(type: Class<*>): Boolean {
+internal fun Throwable.hasCause(type: Class<*>): Boolean {
     var current: Throwable? = this
     while (current != null) {
         if (type.isInstance(current)) return true
@@ -29,7 +31,7 @@ private fun Throwable.hasCause(type: Class<*>): Boolean {
     return false
 }
 
-private fun Throwable.storageErrorCode(): String? {
+internal fun Throwable.storageErrorCode(): String? {
     val taggedCode = message
         ?.let { Regex("\\[nitro-error:([a-z_]+)]").find(it)?.groupValues?.get(1) }
     if (taggedCode == "storage_compensation_failed") {
@@ -47,7 +49,34 @@ private fun Throwable.storageErrorCode(): String? {
     }
 }
 
-private fun Throwable.wrapStorageException(
+internal const val OUT_OF_SPACE_USABLE_BYTES = 1L shl 20
+
+private val sqliteExtendedCodePattern = Regex("\\(code (\\d+)")
+private const val SQLITE_IOERR_READ = 266
+private const val SQLITE_IOERR_SHORT_READ = 522
+
+internal fun isOutOfSpaceFailure(error: Throwable, usableBytes: Long): Boolean {
+    var current: Throwable? = error
+    while (current != null && current !is SQLiteDiskIOException) {
+        current = current.cause
+    }
+    val ioError = current ?: return false
+    val extendedCode = ioError.message
+        ?.let { sqliteExtendedCodePattern.find(it)?.groupValues?.get(1)?.toIntOrNull() }
+        ?: return false
+    if (extendedCode == SQLITE_IOERR_READ || extendedCode == SQLITE_IOERR_SHORT_READ) {
+        return false
+    }
+    return usableBytes in 0 until OUT_OF_SPACE_USABLE_BYTES
+}
+
+internal fun isRecoverableByRecreate(error: Throwable): Boolean {
+    val message = error.message ?: return false
+    return message.startsWith("[nitro-error:storage_corruption] NitroStorage: Disk SQLite ") ||
+        message.startsWith("[nitro-error:storage_full] NitroStorage: Disk SQLite ")
+}
+
+internal fun Throwable.wrapStorageException(
     defaultMessage: String,
     defaultCode: String? = null,
 ): RuntimeException {
@@ -66,8 +95,34 @@ private fun Throwable.wrapStorageException(
 class AndroidStorageAdapter private constructor(private val context: Context) {
     private val sharedPreferences: SharedPreferences =
         context.getSharedPreferences("NitroStorage", Context.MODE_PRIVATE)
-    private val diskStore: DiskSqliteStore by lazy {
-        DiskSqliteStore(context, sharedPreferences)
+    private val diskStoreLock = Any()
+    private var openDiskStore: DiskSqliteStore? = null
+    private val diskStore: DiskSqliteStore
+        get() = synchronized(diskStoreLock) {
+            openDiskStore ?: DiskSqliteStore(context, sharedPreferences, diskDatabaseOpener)
+                .also { openDiskStore = it }
+        }
+
+    private fun recreateDiskStore() {
+        synchronized(diskStoreLock) {
+            openDiskStore?.let { store -> runCatching { store.close() } }
+            openDiskStore = null
+            DiskSqliteStore.deleteDatabaseFiles(context)
+            sharedPreferences.edit().clear().commit()
+            openDiskStore = DiskSqliteStore(context, sharedPreferences, diskDatabaseOpener)
+        }
+    }
+
+    private fun diskFullCodeFor(error: Throwable): String? {
+        if (!error.hasCause(SQLiteDiskIOException::class.java)) {
+            return null
+        }
+        val usableBytes = try {
+            StatFs(context.filesDir.path).availableBytes
+        } catch (statError: IllegalArgumentException) {
+            return null
+        }
+        return if (isOutOfSpaceFailure(error, usableBytes)) "storage_full" else null
     }
 
     private val masterKeyAlias = "${context.packageName}.nitro_storage.master_key"
@@ -549,6 +604,9 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
         @Volatile
         private var instance: AndroidStorageAdapter? = null
 
+        @Volatile
+        internal var diskDatabaseOpener: DiskDatabaseOpener = ::openDiskDatabase
+
         private fun getInstanceOrThrow(): AndroidStorageAdapter {
             return instance ?: throw IllegalStateException(
                 "NitroStorage not initialized. Call AndroidStorageAdapter.init(this) in your MainApplication.onCreate(), " +
@@ -585,8 +643,22 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
         ): T {
             val instance = getInstanceOrThrow()
             try {
-                return instance.diskStore.block()
+                val store = instance.diskStore
+                return try {
+                    store.block()
+                } catch (closed: IllegalStateException) {
+                    val current = instance.diskStore
+                    if (current === store) {
+                        throw closed
+                    }
+                    current.block()
+                }
             } catch (e: SQLiteException) {
+                throw e.wrapStorageException(
+                    "NitroStorage: Disk SQLite $operation failed: ${e.message}",
+                    instance.diskFullCodeFor(e),
+                )
+            } catch (e: IllegalStateException) {
                 throw e.wrapStorageException(
                     "NitroStorage: Disk SQLite $operation failed: ${e.message}",
                 )
@@ -645,7 +717,22 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
 
         @JvmStatic
         fun clearDisk() {
-            diskOperation("clear") { clear() }
+            try {
+                diskOperation("clear") { clear() }
+            } catch (e: RuntimeException) {
+                if (!isRecoverableByRecreate(e)) {
+                    throw e
+                }
+                val instance = getInstanceOrThrow()
+                try {
+                    instance.recreateDiskStore()
+                } catch (recreateError: SQLiteException) {
+                    throw recreateError.wrapStorageException(
+                        "NitroStorage: Disk SQLite clear failed: ${recreateError.message}",
+                        instance.diskFullCodeFor(recreateError),
+                    )
+                }
+            }
         }
 
         // --- Secure (async apply by default, sync commit when requested) ---