react-native-nitro-storage 0.10.3 → 0.11.0

package/cpp/core/SqliteDiskStore.cpp

@@ -44,12 +44,14 @@ void bindText(sqlite3_stmt* stmt, int index, const std::string& value) {
 
 std::string escapeLikePrefix(const std::string& prefix) {
     std::string escaped;
-    escaped.reserve(prefix.size());
-    for (const unsigned char character : prefix) {
+    escaped.reserve(prefix.size() + 1);
+    for (const char character : prefix) {
+        // SQLite LIKE stops at NUL; exact filtering below handles the full key.
+        if (character == '\0') break;
         if (character == '%' || character == '_' || character == '\\') {
             escaped.push_back('\\');
         }
-        escaped.push_back(static_cast<char>(character));
+        escaped.push_back(character);
     }
     escaped.push_back('%');
     return escaped;
@@ -59,7 +61,12 @@ std::string escapeLikePrefix(const std::string& prefix) {
 
 SqliteDiskStore::SqliteDiskStore(std::string path) : path_(std::move(path)) {
     std::lock_guard<std::mutex> lock(mutex_);
-    openLocked();
+    try {
+        openLocked();
+    } catch (...) {
+        closeLocked();
+        throw;
+    }
 }
 
 SqliteDiskStore::~SqliteDiskStore() {
@@ -119,6 +126,12 @@ void SqliteDiskStore::openLocked() {
         "value TEXT NOT NULL"
         ");"
     );
+    execLocked(
+        "CREATE TABLE IF NOT EXISTS meta ("
+        "k TEXT PRIMARY KEY NOT NULL,"
+        "v TEXT NOT NULL"
+        ");"
+    );
     setStmt_ = prepareLocked("INSERT OR REPLACE INTO kv(key, value) VALUES(?1, ?2);");
     getStmt_ = prepareLocked("SELECT value FROM kv WHERE key = ?1;");
     removeStmt_ = prepareLocked("DELETE FROM kv WHERE key = ?1;");
@@ -130,6 +143,8 @@ void SqliteDiskStore::openLocked() {
     insertAbsentStmt_ = prepareLocked(
         "INSERT OR IGNORE INTO kv(key, value) VALUES(?1, ?2);"
     );
+    getMetaStmt_ = prepareLocked("SELECT 1 FROM meta WHERE k = ?1 LIMIT 1;");
+    setMetaStmt_ = prepareLocked("INSERT OR REPLACE INTO meta(k, v) VALUES(?1, ?2);");
 }
 
 void SqliteDiskStore::closeLocked() {
@@ -148,6 +163,8 @@ void SqliteDiskStore::closeLocked() {
     finalize(sizeStmt_);
     finalize(clearStmt_);
     finalize(insertAbsentStmt_);
+    finalize(getMetaStmt_);
+    finalize(setMetaStmt_);
     if (db_ != nullptr) {
         sqlite3_close(db_);
         db_ = nullptr;
@@ -336,8 +353,7 @@ std::vector<std::string> SqliteDiskStore::getKeysByPrefix(const std::string& pre
     std::lock_guard<std::mutex> lock(mutex_);
     sqlite3_reset(prefixStmt_);
     sqlite3_clear_bindings(prefixStmt_);
-    const std::string pattern = escapeLikePrefix(prefix);
-    bindText(prefixStmt_, 1, pattern);
+    bindText(prefixStmt_, 1, escapeLikePrefix(prefix));
     std::vector<std::string> keys;
     while (true) {
         const int rc = sqlite3_step(prefixStmt_);
@@ -350,10 +366,13 @@ std::vector<std::string> SqliteDiskStore::getKeysByPrefix(const std::string& pre
         }
         const unsigned char* text = sqlite3_column_text(prefixStmt_, 0);
         const int bytes = sqlite3_column_bytes(prefixStmt_, 0);
-        keys.emplace_back(
+        std::string key(
             text != nullptr ? reinterpret_cast<const char*>(text) : "",
             static_cast<size_t>(bytes)
         );
+        if (key.compare(0, prefix.size(), prefix) == 0) {
+            keys.push_back(std::move(key));
+        }
     }
     sqlite3_reset(prefixStmt_);
     return keys;
@@ -382,6 +401,49 @@ void SqliteDiskStore::clear() {
     }
 }
 
+void SqliteDiskStore::insertAbsentLocked(
+    const std::vector<std::pair<std::string, std::string>>& entries
+) {
+    for (const auto& entry : entries) {
+        sqlite3_reset(insertAbsentStmt_);
+        sqlite3_clear_bindings(insertAbsentStmt_);
+        bindText(insertAbsentStmt_, 1, entry.first);
+        bindText(insertAbsentStmt_, 2, entry.second);
+        const int rc = sqlite3_step(insertAbsentStmt_);
+        sqlite3_reset(insertAbsentStmt_);
+        if (rc != SQLITE_DONE) {
+            throwSqlite(db_, "migrate", rc);
+        }
+    }
+}
+
+bool SqliteDiskStore::hasMigrationMarkerLocked(const std::string& name) {
+    sqlite3_reset(getMetaStmt_);
+    sqlite3_clear_bindings(getMetaStmt_);
+    bindText(getMetaStmt_, 1, name);
+    const int rc = sqlite3_step(getMetaStmt_);
+    sqlite3_reset(getMetaStmt_);
+    if (rc == SQLITE_ROW) {
+        return true;
+    }
+    if (rc == SQLITE_DONE) {
+        return false;
+    }
+    throwSqlite(db_, "hasMigrationMarker", rc);
+}
+
+void SqliteDiskStore::setMigrationMarkerLocked(const std::string& name) {
+    sqlite3_reset(setMetaStmt_);
+    sqlite3_clear_bindings(setMetaStmt_);
+    bindText(setMetaStmt_, 1, name);
+    bindText(setMetaStmt_, 2, "1");
+    const int rc = sqlite3_step(setMetaStmt_);
+    sqlite3_reset(setMetaStmt_);
+    if (rc != SQLITE_DONE) {
+        throwSqlite(db_, "setMigrationMarker", rc);
+    }
+}
+
 void SqliteDiskStore::migrateIfAbsent(
     const std::vector<std::pair<std::string, std::string>>& entries
 ) {
@@ -391,17 +453,32 @@ void SqliteDiskStore::migrateIfAbsent(
     std::lock_guard<std::mutex> lock(mutex_);
     beginLocked();
     try {
-        for (const auto& entry : entries) {
-            sqlite3_reset(insertAbsentStmt_);
-            sqlite3_clear_bindings(insertAbsentStmt_);
-            bindText(insertAbsentStmt_, 1, entry.first);
-            bindText(insertAbsentStmt_, 2, entry.second);
-            const int rc = sqlite3_step(insertAbsentStmt_);
-            sqlite3_reset(insertAbsentStmt_);
-            if (rc != SQLITE_DONE) {
-                throwSqlite(db_, "migrate", rc);
-            }
+        insertAbsentLocked(entries);
+        commitLocked();
+    } catch (...) {
+        rollbackLocked();
+        throw;
+    }
+}
+
+bool SqliteDiskStore::hasMigrationMarker(const std::string& name) {
+    std::lock_guard<std::mutex> lock(mutex_);
+    return hasMigrationMarkerLocked(name);
+}
+
+void SqliteDiskStore::migrateOnce(
+    const std::string& name,
+    const std::vector<std::pair<std::string, std::string>>& entries
+) {
+    std::lock_guard<std::mutex> lock(mutex_);
+    beginLocked();
+    try {
+        if (hasMigrationMarkerLocked(name)) {
+            commitLocked();
+            return;
         }
+        insertAbsentLocked(entries);
+        setMigrationMarkerLocked(name);
         commitLocked();
     } catch (...) {
         rollbackLocked();

package/cpp/core/SqliteDiskStore.hpp

@@ -39,6 +39,11 @@ public:
     size_t size();
     void clear();
     void migrateIfAbsent(const std::vector<std::pair<std::string, std::string>>& entries);
+    bool hasMigrationMarker(const std::string& name);
+    void migrateOnce(
+        const std::string& name,
+        const std::vector<std::pair<std::string, std::string>>& entries
+    );
 
 private:
     void openLocked();
@@ -50,6 +55,9 @@ private:
     void setLocked(const std::string& key, const std::string& value);
     std::optional<std::string> getLocked(const std::string& key);
     void removeLocked(const std::string& key);
+    void insertAbsentLocked(const std::vector<std::pair<std::string, std::string>>& entries);
+    bool hasMigrationMarkerLocked(const std::string& name);
+    void setMigrationMarkerLocked(const std::string& name);
     sqlite3_stmt* prepareLocked(const char* sql);
 
     std::string path_;
@@ -63,6 +71,8 @@ private:
     sqlite3_stmt* sizeStmt_ = nullptr;
     sqlite3_stmt* clearStmt_ = nullptr;
     sqlite3_stmt* insertAbsentStmt_ = nullptr;
+    sqlite3_stmt* getMetaStmt_ = nullptr;
+    sqlite3_stmt* setMetaStmt_ = nullptr;
     std::mutex mutex_;
 };
 

package/docs/api-reference.md

@@ -14,28 +14,28 @@ const item = createStorageItem<T>({
 
 `StorageItemConfig<T>`:
 
-| Field                        | Type                             | Purpose                                                             |
-| ---------------------------- | -------------------------------- | ------------------------------------------------------------------- |
-| `key`                        | `string`                         | Storage key. Combined with `namespace` when provided.               |
-| `scope`                      | `StorageScope`                   | Memory, Disk, or Secure.                                            |
-| `defaultValue`               | `T`                              | Value returned when no stored value exists.                         |
-| `serialize`                  | `(value: T) => string`           | Custom string encoder. Defaults to primitive/JSON serialization.    |
-| `deserialize`                | `(value: string) => T`           | Custom string decoder.                                              |
-| `validate`                   | `(value: unknown) => value is T` | Runtime guard for stored data.                                      |
-| `onValidationError`          | `(invalidValue: unknown) => T`   | Replacement value when validation fails.                            |
-| `expiration`                 | `{ ttlMs: number }`              | Time-to-live for the value.                                         |
-| `onExpired`                  | `(key: string) => void`          | Called when a read detects TTL expiry.                              |
-| `readCache`                  | `boolean`                        | Reuse raw cache entries for reads, including cached missing values. |
-| `coalesceDiskWrites`         | `boolean`                        | Buffer Disk writes until the next flush.                            |
-| `coalesceSecureWrites`       | `boolean`                        | Buffer Secure writes until the next flush.                          |
-| `namespace`                  | `string`                         | Prefix keys as `namespace:key`.                                     |
-| `biometric`                  | `boolean`                        | Store through biometric secure storage.                             |
-| `biometricLevel`             | `BiometricLevel`                 | Require biometric/passcode or biometric-only access.                |
-| `accessControl`              | `AccessControl`                  | Platform secure accessibility setting.                              |
-| `group`                      | `string`                         | Register the item for group cleanup and inspection.                 |
-| `renameFrom`                 | `string \| readonly string[]`    | Copy a legacy key on first read, then remove it.                    |
-| `fallbackToCacheOnReadError` | `boolean`                        | Return the last cached value when a backend read fails.             |
-| `onReadError`                | `(error: unknown) => void`       | Observe a backend read failure before fallback or rethrow.          |
+| Field                        | Type                             | Purpose                                                                                                                                                                               |
+| ---------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `key`                        | `string`                         | Storage key. Combined with `namespace` when provided. Must not be empty (`invalid_key`).                                                                                              |
+| `scope`                      | `StorageScope`                   | Memory, Disk, or Secure.                                                                                                                                                              |
+| `defaultValue`               | `T`                              | Value returned when no stored value exists.                                                                                                                                           |
+| `serialize`                  | `(value: T) => string`           | Custom string encoder. Defaults to primitive/JSON serialization.                                                                                                                      |
+| `deserialize`                | `(value: string) => T`           | Custom string decoder.                                                                                                                                                                |
+| `validate`                   | `(value: unknown) => value is T` | Runtime guard for stored data.                                                                                                                                                        |
+| `onValidationError`          | `(invalidValue: unknown) => T`   | Replacement value when validation fails.                                                                                                                                              |
+| `expiration`                 | `{ ttlMs: number }`              | Time-to-live for the value.                                                                                                                                                           |
+| `onExpired`                  | `(key: string) => void`          | Called when a read detects TTL expiry.                                                                                                                                                |
+| `readCache`                  | `boolean`                        | Reuse raw cache entries for reads, including cached missing values. Items without `readCache` or `fallbackToCacheOnReadError` do not fill the cache on read.                          |
+| `coalesceDiskWrites`         | `boolean`                        | Buffer Disk writes until the next flush.                                                                                                                                              |
+| `coalesceSecureWrites`       | `boolean`                        | Buffer Secure writes until the next flush.                                                                                                                                            |
+| `namespace`                  | `string`                         | Prefix keys as `namespace:key`.                                                                                                                                                       |
+| `biometric`                  | `boolean`                        | Store through biometric secure storage.                                                                                                                                               |
+| `biometricLevel`             | `BiometricLevel`                 | Require biometric/passcode or biometric-only access.                                                                                                                                  |
+| `accessControl`              | `AccessControl`                  | Platform secure accessibility setting.                                                                                                                                                |
+| `group`                      | `string`                         | Register the item for group cleanup and inspection.                                                                                                                                   |
+| `renameFrom`                 | `string \| readonly string[]`    | Copy a legacy key on first read, then remove it.                                                                                                                                      |
+| `fallbackToCacheOnReadError` | `boolean`                        | Return the last cached value when a backend read fails with `keychain_locked`. Other errors still throw. Only iOS reports `keychain_locked`, so this has no effect on Android or web. |
+| `onReadError`                | `(error: unknown) => void`       | Observe a backend read failure before fallback or rethrow.                                                                                                                            |
 
 `StorageItem<T>`:
 
@@ -65,6 +65,20 @@ const unsubscribe = profileItem.subscribeSelector(
 );
 ```
 
+## Scoped Item Factories
+
+`memoryItem(config)`, `diskItem(config)`, and `secureItem(config)` take the same
+config as `createStorageItem` without the `scope` field.
+
+```ts
+const draft = memoryItem<string>({ key: "draft", defaultValue: "" });
+const theme = diskItem<"light" | "dark">({
+  key: "theme",
+  defaultValue: "light",
+});
+const token = secureItem<string>({ key: "token", defaultValue: "" });
+```
+
 ## createSetItem
 
 ```ts
@@ -85,9 +99,11 @@ flags.getTyped();
 ## React Hooks
 
 ```ts
-const [value, setValue] = useStorage(item);
+const [value, setValue, actions] = useStorage(item);
 const [selected, setItem] = useStorageSelector(item, selector, isEqual);
 const setOnly = useSetStorage(item);
+const readOnly = useStorageValue(item);
+const writeOnly = useStorageActions(item);
 ```
 
 See [react-hooks.md](react-hooks.md).
@@ -128,7 +144,8 @@ See [react-hooks.md](react-hooks.md).
 | `getMetricsSnapshot()`                           | Read aggregated metrics.                                                                  |
 | `getScopedMetricsSnapshot()`                     | Read metrics grouped by storage scope.                                                    |
 | `resetMetrics()`                                 | Clear metrics counters.                                                                   |
-| `getCapabilities()`                              | Read runtime storage capabilities.                                                        |
+| `getCacheMetrics()`                              | Read raw-cache hits, misses, live entries, and estimated bytes.                           |
+| `getCapabilities()`                              | Read runtime storage capabilities. Native `backend.disk` is `"sqlite"`.                   |
 | `getSecurityCapabilities()`                      | Read secure backend capability metadata.                                                  |
 | `getSecureMetadata(key)`                         | Read secure metadata for one key without returning its value.                             |
 | `getAllSecureMetadata()`                         | Read secure metadata for all secure keys without values.                                  |
@@ -259,6 +276,21 @@ the native or web adapter. `isStorageError(error, code)` matches one exact code
 without parsing platform message text. See [secure-storage.md](secure-storage.md)
 for recovery semantics.
 
+| Code                          | Raised when                                                                                                             |
+| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `keychain_locked`             | The protected store is locked.                                                                                          |
+| `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, 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.                                                         |
+| `invalid_key`                 | A storage key is empty.                                                                                                 |
+
+`StorageCompositeError` and `StorageCompensationError` describe errors that
+carry a primary failure plus secondary failures from reconciliation or
+compensation steps.
+
 `isKeychainLockedError(error)` is deprecated. It remains available for
 compatibility and returns `true` for `keychain_locked`,
 `authentication_required`, and `key_invalidated`.
@@ -273,9 +305,10 @@ getWebSecureStorageBackend();
 await flushWebStorageBackends();
 ```
 
-The web entry also exports `describeWebBackendCapabilities(backend)` and
-`isIndexedDBWebBackend(backend)`. The native entry keeps the web backend
-setters, getters, and flush function as typed no-ops for shared code.
+Every entry, including native and `/testing`, exports
+`describeWebBackendCapabilities(backend)` and `isIndexedDBWebBackend(backend)`.
+The native and testing entries keep the web backend setters, getters, and flush
+function as typed no-ops for shared code.
 
 See [web-backends.md](web-backends.md).
 
@@ -339,6 +372,18 @@ Common public types:
 - `PlatformStorage`
 - `PlatformScope`
 - `WebBackendCapabilities`
+- `StorageCapabilities`
+- `StorageCacheMetrics`
+- `StorageExportOptions`
+- `StorageEventObserverOptions`
+- `StorageCompositeError`
+- `StorageCompensationError`
+- `SetStorageItem<T>`
+- `SetItemConfig<T>`
+- `StorageClearOptions`
+- `StorageKeyRef`
+- `StorageActions<T>`
+- `StorageSetter<T>`
 
 `getCapabilities().writeBuffering` describes real per-mode durability:
 
@@ -350,4 +395,4 @@ Common public types:
 
 `describeWebBackendCapabilities(backend)` reports a backend's `buffered`, `flushable`, `closable`, and `subscribable` capabilities from the same typed contract used by the built-in backends.
 
-The IndexedDB subpath exports `createIndexedDBBackend()` and `IndexedDBBackendOptions`.
+The IndexedDB subpath exports `createIndexedDBBackend()` and `IndexedDBBackendOptions`. The root export of `createIndexedDBBackend` is deprecated; import it from `react-native-nitro-storage/indexeddb-backend`.

package/docs/benchmarks.md

@@ -28,19 +28,48 @@ Native Disk/Secure baselines require a device or simulator run and are not part
 
 ## Release Checklist
 
-Before publishing:
+Before publishing, run the full release gate:
 
 ```sh
-bun run codegen:check
-bun run lint:check
-bun run format:check
-bun run typecheck
-bun run test:types
-bun run test
-bun run test:cpp
-bun run build
-bun run benchmark
-bun run --cwd packages/react-native-nitro-storage check:pack
+bun run release:preflight
 ```
 
-Keep the dry-publish output in the release notes when validating a version locally.
+It runs `check:ci` (including the benchmark), the example checks, the package
+audit, and the publish dry run.
+
+## 2026-09-27 Memory enumeration experiment
+
+Command: `bun run benchmark:enumeration`. The smoke form, `bun run benchmark:enumeration -- --smoke`, validates fixture execution only.
+
+Host: Apple M4 Pro, darwin 27.0.0, Bun 1.4.2. This uses the actual web Memory implementation, not native SQLite or JSI. Each run contains five batches of 30 warm samples per operation and size. Every output key/value is checked outside the timed interval.
+
+The comparison starts from the correctness-fixed implementation, not the original release, whose arbitrary-key behavior failed the fixture. It therefore does not establish an overall speedup over the published version.
+
+The accepted iteration change removes the repeated Map lookup in `getAll` and the intermediate prefix-key array. Two separate process runs produced these median changes versus the corrected baseline (negative is faster):
+
+| Keys    | Operation     | Run 1  | Run 2  |
+| ------- | ------------- | ------ | ------ |
+| 1,000   | `getAll`      | -10.6% | -14.2% |
+| 1,000   | `getByPrefix` | -8.4%  | -3.7%  |
+| 10,000  | `getAll`      | -10.4% | -7.4%  |
+| 10,000  | `getByPrefix` | -10.2% | -9.7%  |
+| 100,000 | `getAll`      | -47.5% | -47.8% |
+| 100,000 | `getByPrefix` | -12.2% | -6.9%  |
+
+Only the 100k-key `getAll` result clearly and repeatedly exceeds the proposed 10% target: median improved about 47%, with median batch p95 improving 43–48%. Smaller results vary and do not establish repeatable gains above the target.
+
+Peak process RSS was 318/339 MB for the corrected baseline and 400/340 MB for the candidate (decimal MB). This high-water metric was noisy and triggers review; source review found no added retained collection or cache. It does not prove equal allocation cost. Native/device performance and retained-memory profiling remain separate acceptance evidence.
+
+An earlier ordinary-property shortcut was reverted after a 10k-key regression. An entry-tuple iteration candidate was replaced after elevated peak RSS.
+
+Fixture SHA-256: `1ec2feb7ff55d5c61f33e4f70948336ca97d0a7746a77d9c295d7ae4417463f6`. Lockfile SHA-256: `1a6a54f48038afa313fb8a8316611f2091edf8a133bcc16173836599f1831492`. Corrected core SHA-256: `f7e8687b69d93a0fec8318877e6227b8b42ee617b68a257a17e33f83f4492b17`. Candidate core SHA-256: `e8b68c5bb3305b07eeaaff609381ec28ab564424a8fdbb53a8014f6460b6c86e`.
+
+Raw reports and environment: `/tmp/nitro-implementation.GbjgqhYj/storage-enumeration-v2-{corrected,candidate3}{,-repeat}.json` and `storage-enumeration-environment.json` on the execution host. These temporary receipts are not portable release artifacts; the table above preserves the selected results. No device or universal speed claim is made.
+
+### Original-release control and rejected prefix experiment
+
+The additional `--ordinary` mode omits the special prototype key so the original 0.10.3 source and the corrected source can produce identical valid output. Two quiet process comparisons against the archived original revision measured 100k-key `getAll` median improvement of about 42%, with batch p95 improving 43–45%. This is a host web-Memory result only. The correctness-fixed `getByPrefix` was 17–20% slower at 100k keys and 15–23% slower at 1k; no overall prefix speedup is claimed.
+
+A subsequent direct prefix scan preserved the observer path and passed independent source review, but was rejected: although 100k prefix medians improved 26–28% against the original, 1k medians regressed 66–67%. The final implementation retains the prior iteration change. The observer mutation/order regression test remains as coverage. Correctness and predictable small-workload behavior take priority over the large-workload result.
+
+Original-control receipts: `storage-ordinary-{original,final}{,-repeat}.json` in the evidence directory above (`final` denotes retained candidate3). Rejected-experiment receipts: `storage-ordinary-candidate4{,-repeat}.json`. The ordinary-mode harness extends the fixture; its hash differs from the default-only fixture recorded above. Neither these comparisons nor peak process RSS establish native latency, retained-memory equivalence, or a universal improvement.

package/docs/mmkv-migration.md

@@ -4,12 +4,14 @@ Use `migrateFromMMKV(mmkv, item, deleteAfterMigration?)` when an app already sto
 
 The helper reads in this order:
 
-1. `mmkv.getString(key)`
+1. `mmkv.getString(key)`, then `JSON.parse` on the string. If parsing succeeds, the parsed value is written; otherwise the raw string is written.
 2. `mmkv.getNumber(key)`
 3. `mmkv.getBoolean(key)`
 
 It writes through `item.set()`, so custom serialization, validation, TTL behavior, and listeners remain active.
 
+Because of the `JSON.parse` step, a string item can receive a non-string value: MMKV strings such as `"12345"`, `"true"`, or `"null"` are written as a number, a boolean, or `null`, while the item type still says `string`. For string items, add `validate` with an `onValidationError` fallback, or copy the raw value with `storage.setString(key, mmkv.getString(key), scope)` instead.
+
 ## Basic Migration
 
 ```ts

package/docs/native-libraries.md

@@ -6,12 +6,18 @@ EncryptedSharedPreferences. Web Disk stays on the configured web backend
 
 ## Kept
 
-| Library    | Where                                            | Why                                                                                                                                                                     |
-| ---------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| SQLite WAL | iOS `SqliteDiskStore`, Android `DiskSqliteStore` | Transactional batch writes, prefix queries without loading a plist/XML map, and crash-safe persistence. Closest Disk engine to a dedicated mmap KV without adding MMKV. |
+| Library    | Where                                            | Why                                                                                                                                                    |
+| ---------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| SQLite WAL | iOS `SqliteDiskStore`, Android `DiskSqliteStore` | Transactional batch writes, literal prefix queries in SQL, and crash-safe persistence. Closest Disk engine to a dedicated mmap KV without adding MMKV. |
 
 Existing UserDefaults suite keys and Android `NitroStorage` preferences are
-copied into SQLite on first open. Later Disk reads and writes use SQLite.
+copied into SQLite once, on first open. A marker in the SQLite `meta` table
+(`suite_v1` on iOS, `prefs_v1` on Android) records completion, so later launches
+skip the import. On iOS the suite domain is kept for downgrade safety, and Disk
+key enumeration still merges its keys. On Android the legacy `NitroStorage`
+preferences are kept after the import for downgrade safety, like the iOS suite;
+Disk deletes remove the key from them and `clear(Disk)` clears them, so a logout
+wipe leaves no pre-SQLite copy behind. Later Disk reads and writes use SQLite.
 
 ## Evaluated and not shipped
 

package/docs/secure-storage.md

@@ -47,7 +47,14 @@ export const recoveryCodeItem = createStorageItem<string>({
 
 `BiometricLevel.BiometryOnly` does not allow passcode fallback. Use `BiometricLevel.BiometryOrPasscode` when passcode fallback is acceptable.
 
-On Android 11 and newer, the two levels use separate Android Keystore keys with distinct allowed authenticators. Android 10 and older support `BiometryOrPasscode`; `BiometryOnly` reports `biometric_unavailable` because the older Keystore API cannot enforce that distinction safely for this storage backend. Android authorization remains valid for a 30-second window after successful authentication.
+On Android 11 and newer, the two levels use separate Android Keystore keys with distinct allowed authenticators. Android 10 and older support `BiometryOrPasscode`; `BiometryOnly` reports `biometric_unavailable` because the older Keystore API cannot enforce that distinction safely for this storage backend.
+
+### Platform prompt behaviour
+
+- **iOS:** reading a biometric item runs `SecItemCopyMatching` with user interaction allowed. The system shows the Face ID, Touch ID, or passcode sheet, and the synchronous JSI call blocks the JavaScript thread until the user answers. JavaScript timers, JavaScript-driven animations, and other JSI calls wait during that time. Read biometric items from a user action, not during render. Deleting a biometric item does not read it first unless an event listener or an unredacted event observer needs the previous value, so a delete does not show a prompt.
+- **Android errors:** if the default Secure master key or store cannot be created (for example a Keystore key that exists but is unusable), Secure calls throw `storage_corruption`. This is not a temporary state: do not retry in a loop. Secure scope stays unavailable until the app data is cleared or the app is reinstalled; Memory and Disk keep working.
+- **Android:** Nitro Storage never shows a prompt. Each biometric level is an `EncryptedSharedPreferences` file whose Tink keyset is wrapped by an Android Keystore key that requires user authentication within the last 30 seconds. That key is used only when the store is first opened in a process: `EncryptedSharedPreferences` decrypts the keyset once and keeps it in memory, and later reads and writes in the same process do not check authentication again. After the first successful open, biometric values stay readable without authentication until the process ends.
+- **What Android apps must do:** run `androidx.biometric.BiometricPrompt` in the app before every read that must be gated, and treat the storage check as a one-time guard per process. Enable the config plugin option `addBiometricPermissions` so the app can declare `USE_BIOMETRIC` and `USE_FINGERPRINT` for its own prompt. Reading a `BiometryOrPasscode` item opens only the `BiometryOrPasscode` store, so a device-credential authentication is enough for that level.
 
 ## Access Control
 
@@ -61,6 +68,8 @@ On Android 11 and newer, the two levels use separate Android Keystore keys with
 | `AccessControl.WhenUnlockedThisDeviceOnly`     | The secret should not migrate through backup/restore.             |
 | `AccessControl.AfterFirstUnlockThisDeviceOnly` | Background refresh is needed, but migration is not allowed.       |
 
+On iOS the level applies on every write, including updates of an item that already exists, so changing `accessControl` or `storage.setAccessControl()` moves existing items to the new level on their next write. On iOS, `item.has()` and `storage.has(key, StorageScope.Secure)` throw `keychain_locked` while the keychain is locked, and a Keychain status error for any other unexpected status, instead of returning `false`. A biometric item that the Keychain reports as needing authentication counts as present, so `has()` on a biometric item returns `true` without a prompt; while the device is locked the same status also returns `true`. Listing, counting, and prefix queries on Secure keys throw a Keychain status error for unexpected statuses instead of returning an empty result.
+
 ## Secure Auth Item Map
 
 `createSecureAuthStorage()` creates a namespaced map of secure string items.
@@ -172,13 +181,16 @@ Recovery depends on the exact stable code:
 
 `isKeychainLockedError()` remains available for compatibility but is
 deprecated. It groups all three codes and must not be used to select retry
-behavior. The package does not block the synchronous JSI call, sleep, or retry
-internally; the application owns lifecycle scheduling and cancellation.
+behavior. The package does not sleep or retry internally; the application owns
+lifecycle scheduling and cancellation. Biometric reads on iOS block the
+synchronous JSI call while the system prompt is visible.
 
-Do not enable `fallbackToCacheOnReadError` for access or refresh tokens unless
-the application explicitly accepts stale or revoked credentials. A cached
-value can hide the distinction between temporary unavailability and credential
-recovery.
+`fallbackToCacheOnReadError` returns the last value read in this process only
+when a read fails with `keychain_locked`. Every other error still throws. Only
+iOS reports `keychain_locked`; Android and web never do, so the fallback has no
+effect there. Do not
+enable it for access or refresh tokens unless the application explicitly
+accepts stale credentials while the device is locked.
 
 ## Android Secure Write Mode
 
@@ -204,13 +216,13 @@ entries, and surfaces native clear failures.
 ## iOS Legacy Disk Migration
 
 Older releases tracked observed Disk keys in `standardUserDefaults`. On iOS,
-adapter initialization copies a valid registry into the Nitro suite domain and
+the first Disk operation copies a valid registry into the Nitro suite domain and
 removes each legacy source only after a target readback and synchronization
 check. `NSUserDefaults` is not transactional, so the migration stops on any
 failed synchronization or readback without deleting the source or registry.
 Malformed registries, same-domain or fallback stores, conflicting target
 values, and failed persistence therefore remain available for recovery. The
-migration is retryable on a later initialization; do not delete the registry
+migration is retryable on a later launch; do not delete the registry
 manually while an upgrade is in progress.
 
 After that cutover, suite string keys are imported into the SQLite WAL Disk
@@ -237,10 +249,12 @@ See [web-backends.md](web-backends.md) for backend contracts and IndexedDB setup
 Before releasing secure-storage changes, run:
 
 ```sh
-bun run test -- --filter=react-native-nitro-storage
-bun run test:cpp -- --filter=react-native-nitro-storage
-(cd packages/react-native-nitro-storage && bun run check:pack)
+bun run test
+bun run test:cpp
+bun run audit:package
 ```
 
+`bun run release:preflight` runs these checks together with the full release gate.
+
 Also run the [physical-device Keychain lifecycle protocol](keychain-lifecycle-testing.md)
 when changing biometric, Keychain, or error-classification behavior.

package/docs/web-backends.md

@@ -4,6 +4,8 @@ Nitro Storage runs on web through synchronous backend contracts. Disk and Secure
 
 The default web backend is localStorage-style. Configure custom backends when you need IndexedDB persistence, tests with isolated storage, cross-tab sync, or a platform-specific secret wrapper.
 
+Register a separate backend instance for each scope. If one instance is registered for both scopes, Disk enumeration skips the `__secure_` and `__bio_` keys that Secure scope writes, and each scope's `clear()` removes only its own keys, but separate stores keep the scopes fully isolated.
+
 ## Backend Contract
 
 ```ts
@@ -102,7 +104,7 @@ The IndexedDB backend exposes `close()` and rejects later synchronous operations
 
 ### Persistence Lifecycle
 
-IndexedDB transactions cannot block a page unload, so in-flight writes may be aborted when the page closes. The backend mitigates this by starting a flush on `pagehide` and on `visibilitychange` (hidden), and `flush()` awaits every pending transaction. When persistence fails, `flush()` throws an error that names the affected keys, and `onError` receives each individual failure.
+IndexedDB transactions cannot block a page unload, so in-flight writes may be aborted when the page closes. The backend does not install `pagehide` or `visibilitychange` handlers, because there is no synchronous way to finish a pending transaction there. `flush()` awaits every pending transaction. When persistence fails, `flush()` throws an error that names the affected keys, and `onError` receives each individual failure.
 
 ```ts
 const backend = await createIndexedDBBackend("app-secure", "keyvalue", {
@@ -119,7 +121,9 @@ Treat IndexedDB persistence as best-effort under abrupt termination: keep a dura
 
 ## Cross-tab Updates
 
-The IndexedDB backend uses `BroadcastChannel` when available. Other tabs receive cache invalidation events and update their in-memory copy.
+The IndexedDB backend uses `BroadcastChannel` when available. Other tabs receive cache invalidation events and update their in-memory copy. Messages that arrive while a new backend is still loading its snapshot are applied after the snapshot, so they are not overwritten.
+
+The window `storage` event updates a scope only while that scope uses the default `localStorage` backend, and only for events from `localStorage`. Custom backends must sync through `subscribe(listener)`.
 
 If you provide your own backend, implement `subscribe(listener)` to keep Nitro Storage caches aligned with external writes.
 

package/indexeddb-backend/package.json

@@ -0,0 +1,6 @@
+{
+  "main": "../lib/commonjs/indexeddb-backend.js",
+  "module": "../lib/module/indexeddb-backend.js",
+  "types": "../lib/typescript/indexeddb-backend.d.ts",
+  "sideEffects": false
+}

package/ios/IOSStorageAdapterCpp.hpp

@@ -1,6 +1,7 @@
 #pragma once
 
 #include "../core/NativeStorageAdapter.hpp"
+#include <atomic>
 #include <mutex>
 #include <unordered_set>
 
@@ -55,7 +56,10 @@ private:
     std::unordered_set<std::string> secureKeysCache_;
     std::unordered_set<std::string> biometricKeysCache_;
     bool secureKeyCacheHydrated_{false};
+    std::mutex diskMigrationMutex_;
+    std::atomic<bool> diskMigrated_{false};
 
+    void ensureDiskMigrated();
     void ensureSecureKeyCacheHydrated();
     void markSecureKeySet(const std::string& key);
     void markSecureKeyRemoved(const std::string& key);