react-native-nitro-storage 0.10.2 → 0.10.4

package/cpp/core/SqliteDiskStore.cpp

@@ -0,0 +1,416 @@
+#include "SqliteDiskStore.hpp"
+
+#include <sqlite3.h>
+
+#include <algorithm>
+#include <cstdlib>
+#include <filesystem>
+#include <memory>
+#include <stdexcept>
+
+namespace NitroStorage {
+namespace {
+
+std::unique_ptr<SqliteDiskStore>& sharedStore() {
+    static std::unique_ptr<SqliteDiskStore> store;
+    return store;
+}
+
+std::mutex& sharedMutex() {
+    static std::mutex mutex;
+    return mutex;
+}
+
+[[noreturn]] void throwSqlite(sqlite3* db, const char* operation, int code) {
+    const char* message = db != nullptr ? sqlite3_errmsg(db) : sqlite3_errstr(code);
+    throw std::runtime_error(
+        std::string("NitroStorage: Disk SQLite ") + operation + " failed: " +
+        (message != nullptr ? message : "unknown error")
+    );
+}
+
+void bindText(sqlite3_stmt* stmt, int index, const std::string& value) {
+    const int rc = sqlite3_bind_text(
+        stmt,
+        index,
+        value.data(),
+        static_cast<int>(value.size()),
+        SQLITE_TRANSIENT
+    );
+    if (rc != SQLITE_OK) {
+        throw std::runtime_error("NitroStorage: Disk SQLite bind failed");
+    }
+}
+
+std::string escapeLikePrefix(const std::string& prefix) {
+    std::string escaped;
+    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(character);
+    }
+    escaped.push_back('%');
+    return escaped;
+}
+
+} // namespace
+
+SqliteDiskStore::SqliteDiskStore(std::string path) : path_(std::move(path)) {
+    std::lock_guard<std::mutex> lock(mutex_);
+    openLocked();
+}
+
+SqliteDiskStore::~SqliteDiskStore() {
+    std::lock_guard<std::mutex> lock(mutex_);
+    closeLocked();
+}
+
+SqliteDiskStore& SqliteDiskStore::shared(const std::string& path) {
+    std::lock_guard<std::mutex> lock(sharedMutex());
+    auto& store = sharedStore();
+    if (!store || store->path() != path) {
+        store = std::make_unique<SqliteDiskStore>(path);
+    }
+    return *store;
+}
+
+void SqliteDiskStore::resetShared() {
+    std::lock_guard<std::mutex> lock(sharedMutex());
+    sharedStore().reset();
+}
+
+std::string SqliteDiskStore::defaultPath() {
+#ifdef __APPLE__
+    const char* home = std::getenv("HOME");
+    if (home == nullptr || home[0] == '\0') {
+        return "nitro-storage-disk.sqlite";
+    }
+    return std::string(home) + "/Library/Application Support/nitro-storage-disk.sqlite";
+#else
+    return "nitro-storage-disk.sqlite";
+#endif
+}
+
+void SqliteDiskStore::openLocked() {
+    const auto parent = std::filesystem::path(path_).parent_path();
+    if (!parent.empty()) {
+        std::filesystem::create_directories(parent);
+    }
+    sqlite3* db = nullptr;
+    const int flags = SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE | SQLITE_OPEN_FULLMUTEX;
+    const int openRc = sqlite3_open_v2(path_.c_str(), &db, flags, nullptr);
+    if (openRc != SQLITE_OK) {
+        const int code = openRc;
+        if (db != nullptr) {
+            sqlite3_close(db);
+        }
+        throwSqlite(nullptr, "open", code);
+    }
+    db_ = db;
+    sqlite3_busy_timeout(db_, 5000);
+    execLocked("PRAGMA journal_mode=WAL;");
+    execLocked("PRAGMA synchronous=NORMAL;");
+    execLocked("PRAGMA temp_store=MEMORY;");
+    execLocked(
+        "CREATE TABLE IF NOT EXISTS kv ("
+        "key TEXT PRIMARY KEY NOT NULL,"
+        "value 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;");
+    hasStmt_ = prepareLocked("SELECT 1 FROM kv WHERE key = ?1 LIMIT 1;");
+    keysStmt_ = prepareLocked("SELECT key FROM kv;");
+    prefixStmt_ = prepareLocked("SELECT key FROM kv WHERE key LIKE ?1 ESCAPE '\\';");
+    sizeStmt_ = prepareLocked("SELECT COUNT(*) FROM kv;");
+    clearStmt_ = prepareLocked("DELETE FROM kv;");
+    insertAbsentStmt_ = prepareLocked(
+        "INSERT OR IGNORE INTO kv(key, value) VALUES(?1, ?2);"
+    );
+}
+
+void SqliteDiskStore::closeLocked() {
+    auto finalize = [](sqlite3_stmt*& stmt) {
+        if (stmt != nullptr) {
+            sqlite3_finalize(stmt);
+            stmt = nullptr;
+        }
+    };
+    finalize(setStmt_);
+    finalize(getStmt_);
+    finalize(removeStmt_);
+    finalize(hasStmt_);
+    finalize(keysStmt_);
+    finalize(prefixStmt_);
+    finalize(sizeStmt_);
+    finalize(clearStmt_);
+    finalize(insertAbsentStmt_);
+    if (db_ != nullptr) {
+        sqlite3_close(db_);
+        db_ = nullptr;
+    }
+}
+
+void SqliteDiskStore::execLocked(const char* sql) {
+    char* error = nullptr;
+    const int rc = sqlite3_exec(db_, sql, nullptr, nullptr, &error);
+    if (rc != SQLITE_OK) {
+        const std::string message = error != nullptr ? error : "unknown error";
+        sqlite3_free(error);
+        throw std::runtime_error(
+            std::string("NitroStorage: Disk SQLite exec failed: ") + message
+        );
+    }
+}
+
+void SqliteDiskStore::beginLocked() {
+    execLocked("BEGIN IMMEDIATE;");
+}
+
+void SqliteDiskStore::commitLocked() {
+    execLocked("COMMIT;");
+}
+
+void SqliteDiskStore::rollbackLocked() {
+    sqlite3_exec(db_, "ROLLBACK;", nullptr, nullptr, nullptr);
+}
+
+sqlite3_stmt* SqliteDiskStore::prepareLocked(const char* sql) {
+    sqlite3_stmt* stmt = nullptr;
+    const int rc = sqlite3_prepare_v2(db_, sql, -1, &stmt, nullptr);
+    if (rc != SQLITE_OK) {
+        throwSqlite(db_, "prepare", rc);
+    }
+    return stmt;
+}
+
+void SqliteDiskStore::setLocked(const std::string& key, const std::string& value) {
+    sqlite3_reset(setStmt_);
+    sqlite3_clear_bindings(setStmt_);
+    bindText(setStmt_, 1, key);
+    bindText(setStmt_, 2, value);
+    const int rc = sqlite3_step(setStmt_);
+    sqlite3_reset(setStmt_);
+    if (rc != SQLITE_DONE) {
+        throwSqlite(db_, "set", rc);
+    }
+}
+
+std::optional<std::string> SqliteDiskStore::getLocked(const std::string& key) {
+    sqlite3_reset(getStmt_);
+    sqlite3_clear_bindings(getStmt_);
+    bindText(getStmt_, 1, key);
+    const int rc = sqlite3_step(getStmt_);
+    if (rc == SQLITE_DONE) {
+        sqlite3_reset(getStmt_);
+        return std::nullopt;
+    }
+    if (rc != SQLITE_ROW) {
+        sqlite3_reset(getStmt_);
+        throwSqlite(db_, "get", rc);
+    }
+    const unsigned char* text = sqlite3_column_text(getStmt_, 0);
+    const int bytes = sqlite3_column_bytes(getStmt_, 0);
+    std::string value(
+        text != nullptr ? reinterpret_cast<const char*>(text) : "",
+        static_cast<size_t>(bytes)
+    );
+    sqlite3_reset(getStmt_);
+    return value;
+}
+
+void SqliteDiskStore::removeLocked(const std::string& key) {
+    sqlite3_reset(removeStmt_);
+    sqlite3_clear_bindings(removeStmt_);
+    bindText(removeStmt_, 1, key);
+    const int rc = sqlite3_step(removeStmt_);
+    sqlite3_reset(removeStmt_);
+    if (rc != SQLITE_DONE) {
+        throwSqlite(db_, "remove", rc);
+    }
+}
+
+void SqliteDiskStore::set(const std::string& key, const std::string& value) {
+    std::lock_guard<std::mutex> lock(mutex_);
+    setLocked(key, value);
+}
+
+std::optional<std::string> SqliteDiskStore::get(const std::string& key) {
+    std::lock_guard<std::mutex> lock(mutex_);
+    return getLocked(key);
+}
+
+void SqliteDiskStore::remove(const std::string& key) {
+    std::lock_guard<std::mutex> lock(mutex_);
+    removeLocked(key);
+}
+
+bool SqliteDiskStore::has(const std::string& key) {
+    std::lock_guard<std::mutex> lock(mutex_);
+    sqlite3_reset(hasStmt_);
+    sqlite3_clear_bindings(hasStmt_);
+    bindText(hasStmt_, 1, key);
+    const int rc = sqlite3_step(hasStmt_);
+    sqlite3_reset(hasStmt_);
+    if (rc == SQLITE_ROW) {
+        return true;
+    }
+    if (rc == SQLITE_DONE) {
+        return false;
+    }
+    throwSqlite(db_, "has", rc);
+}
+
+void SqliteDiskStore::setBatch(
+    const std::vector<std::string>& keys,
+    const std::vector<std::string>& values
+) {
+    std::lock_guard<std::mutex> lock(mutex_);
+    beginLocked();
+    try {
+        const size_t count = std::min(keys.size(), values.size());
+        for (size_t index = 0; index < count; ++index) {
+            setLocked(keys[index], values[index]);
+        }
+        commitLocked();
+    } catch (...) {
+        rollbackLocked();
+        throw;
+    }
+}
+
+std::vector<std::optional<std::string>> SqliteDiskStore::getBatch(
+    const std::vector<std::string>& keys
+) {
+    std::lock_guard<std::mutex> lock(mutex_);
+    std::vector<std::optional<std::string>> results;
+    results.reserve(keys.size());
+    for (const auto& key : keys) {
+        results.push_back(getLocked(key));
+    }
+    return results;
+}
+
+void SqliteDiskStore::removeBatch(const std::vector<std::string>& keys) {
+    std::lock_guard<std::mutex> lock(mutex_);
+    beginLocked();
+    try {
+        for (const auto& key : keys) {
+            removeLocked(key);
+        }
+        commitLocked();
+    } catch (...) {
+        rollbackLocked();
+        throw;
+    }
+}
+
+std::vector<std::string> SqliteDiskStore::getAllKeys() {
+    std::lock_guard<std::mutex> lock(mutex_);
+    sqlite3_reset(keysStmt_);
+    std::vector<std::string> keys;
+    while (true) {
+        const int rc = sqlite3_step(keysStmt_);
+        if (rc == SQLITE_DONE) {
+            break;
+        }
+        if (rc != SQLITE_ROW) {
+            sqlite3_reset(keysStmt_);
+            throwSqlite(db_, "getAllKeys", rc);
+        }
+        const unsigned char* text = sqlite3_column_text(keysStmt_, 0);
+        const int bytes = sqlite3_column_bytes(keysStmt_, 0);
+        keys.emplace_back(
+            text != nullptr ? reinterpret_cast<const char*>(text) : "",
+            static_cast<size_t>(bytes)
+        );
+    }
+    sqlite3_reset(keysStmt_);
+    return keys;
+}
+
+std::vector<std::string> SqliteDiskStore::getKeysByPrefix(const std::string& prefix) {
+    std::lock_guard<std::mutex> lock(mutex_);
+    sqlite3_reset(prefixStmt_);
+    sqlite3_clear_bindings(prefixStmt_);
+    bindText(prefixStmt_, 1, escapeLikePrefix(prefix));
+    std::vector<std::string> keys;
+    while (true) {
+        const int rc = sqlite3_step(prefixStmt_);
+        if (rc == SQLITE_DONE) {
+            break;
+        }
+        if (rc != SQLITE_ROW) {
+            sqlite3_reset(prefixStmt_);
+            throwSqlite(db_, "getKeysByPrefix", rc);
+        }
+        const unsigned char* text = sqlite3_column_text(prefixStmt_, 0);
+        const int bytes = sqlite3_column_bytes(prefixStmt_, 0);
+        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;
+}
+
+size_t SqliteDiskStore::size() {
+    std::lock_guard<std::mutex> lock(mutex_);
+    sqlite3_reset(sizeStmt_);
+    const int rc = sqlite3_step(sizeStmt_);
+    if (rc != SQLITE_ROW) {
+        sqlite3_reset(sizeStmt_);
+        throwSqlite(db_, "size", rc);
+    }
+    const size_t count = static_cast<size_t>(sqlite3_column_int64(sizeStmt_, 0));
+    sqlite3_reset(sizeStmt_);
+    return count;
+}
+
+void SqliteDiskStore::clear() {
+    std::lock_guard<std::mutex> lock(mutex_);
+    sqlite3_reset(clearStmt_);
+    const int rc = sqlite3_step(clearStmt_);
+    sqlite3_reset(clearStmt_);
+    if (rc != SQLITE_DONE) {
+        throwSqlite(db_, "clear", rc);
+    }
+}
+
+void SqliteDiskStore::migrateIfAbsent(
+    const std::vector<std::pair<std::string, std::string>>& entries
+) {
+    if (entries.empty()) {
+        return;
+    }
+    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);
+            }
+        }
+        commitLocked();
+    } catch (...) {
+        rollbackLocked();
+        throw;
+    }
+}
+
+} // namespace NitroStorage

package/cpp/core/SqliteDiskStore.hpp

@@ -0,0 +1,69 @@
+#pragma once
+
+#include <mutex>
+#include <optional>
+#include <string>
+#include <utility>
+#include <vector>
+
+struct sqlite3;
+struct sqlite3_stmt;
+
+namespace NitroStorage {
+
+class SqliteDiskStore {
+public:
+    explicit SqliteDiskStore(std::string path);
+    SqliteDiskStore(const SqliteDiskStore&) = delete;
+    SqliteDiskStore& operator=(const SqliteDiskStore&) = delete;
+    ~SqliteDiskStore();
+
+    static SqliteDiskStore& shared(const std::string& path);
+    static void resetShared();
+    static std::string defaultPath();
+
+    const std::string& path() const { return path_; }
+
+    void set(const std::string& key, const std::string& value);
+    std::optional<std::string> get(const std::string& key);
+    void remove(const std::string& key);
+    bool has(const std::string& key);
+    void setBatch(
+        const std::vector<std::string>& keys,
+        const std::vector<std::string>& values
+    );
+    std::vector<std::optional<std::string>> getBatch(const std::vector<std::string>& keys);
+    void removeBatch(const std::vector<std::string>& keys);
+    std::vector<std::string> getAllKeys();
+    std::vector<std::string> getKeysByPrefix(const std::string& prefix);
+    size_t size();
+    void clear();
+    void migrateIfAbsent(const std::vector<std::pair<std::string, std::string>>& entries);
+
+private:
+    void openLocked();
+    void closeLocked();
+    void execLocked(const char* sql);
+    void beginLocked();
+    void commitLocked();
+    void rollbackLocked();
+    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);
+    sqlite3_stmt* prepareLocked(const char* sql);
+
+    std::string path_;
+    sqlite3* db_ = nullptr;
+    sqlite3_stmt* setStmt_ = nullptr;
+    sqlite3_stmt* getStmt_ = nullptr;
+    sqlite3_stmt* removeStmt_ = nullptr;
+    sqlite3_stmt* hasStmt_ = nullptr;
+    sqlite3_stmt* keysStmt_ = nullptr;
+    sqlite3_stmt* prefixStmt_ = nullptr;
+    sqlite3_stmt* sizeStmt_ = nullptr;
+    sqlite3_stmt* clearStmt_ = nullptr;
+    sqlite3_stmt* insertAbsentStmt_ = nullptr;
+    std::mutex mutex_;
+};
+
+} // namespace NitroStorage

package/docs/api-reference.md

@@ -342,7 +342,10 @@ Common public types:
 
 `getCapabilities().writeBuffering` describes real per-mode durability:
 
-- Native: Disk writes are buffered by the platform (`SharedPreferences.apply()` on Android, `NSUserDefaults` on iOS). Secure writes are buffered only when `setSecureWritesAsync(true)` is active on Android; iOS Keychain writes are synchronous.
+- Native: Disk writes commit in a SQLite WAL transaction. JavaScript can still
+  coalesce Disk writes until `flushDiskWrites()`. Secure writes are buffered
+  only when `setSecureWritesAsync(true)` is active on Android; iOS Keychain
+  writes are synchronous.
 - Web: buffering follows the configured backend; IndexedDB backends are buffered, localStorage backends are synchronous.
 
 `describeWebBackendCapabilities(backend)` reports a backend's `buffered`, `flushable`, `closable`, and `subscribable` capabilities from the same typed contract used by the built-in backends.

package/docs/benchmarks.md

@@ -44,3 +44,40 @@ bun run --cwd packages/react-native-nitro-storage check:pack
 ```
 
 Keep the dry-publish output in the release notes when validating a version locally.
+
+## 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/native-libraries.md

@@ -0,0 +1,30 @@
+# Native libraries
+
+Disk scope is a SQLite WAL key-value store. Secure scope stays on Keychain and
+EncryptedSharedPreferences. Web Disk stays on the configured web backend
+(IndexedDB or `localStorage`).
+
+## 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. |
+
+Existing UserDefaults suite keys and Android `NitroStorage` preferences are
+copied into SQLite on first open. Later Disk reads and writes use SQLite.
+
+## Evaluated and not shipped
+
+| Library           | Decision                                                                                                                               |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| MMKV              | Skipped. Disk still needs a first-party engine; MMKV remains a one-way migration source only.                                          |
+| LMDB              | Rejected. Extra vendored C, mmap file-handle limits on mobile, and no system copy on Android/iOS. SQLite is already on both platforms. |
+| RocksDB / LevelDB | Rejected. Heavy native footprint for small preference-sized values.                                                                    |
+| yyjson            | Rejected for Disk. Typed TTL/JSON envelopes stay in JavaScript.                                                                        |
+
+## Compatibility
+
+- Public Disk APIs (`get`/`set`/`setBatch`/`getKeysByPrefix`/`import`) are
+  unchanged.
+- iOS still runs the suite-domain legacy cutover before SQLite import.
+- Android still uses EncryptedSharedPreferences for Secure scope.

package/docs/secure-storage.md

@@ -213,6 +213,11 @@ values, and failed persistence therefore remain available for recovery. The
 migration is retryable on a later initialization; 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
+database. New Disk writes go to SQLite. The v1 suite marker is preserved so
+the UserDefaults cutover stays retryable. See
+[native-libraries.md](native-libraries.md).
+
 ## Web Secure Backend
 
 Browsers cannot provide iOS Keychain or Android Keystore guarantees. On web, Secure scope is only as strong as the backend you configure.