feat(platform-wallet-storage): snapshot readers + unified V002 schema migration

packages/rs-platform-wallet-storage/Cargo.toml

@@ -247,3 +247,9 @@ kv = ["sqlite"]
 __test-helpers = ["sqlite"]
 # e2e tests that drive the #3692 manager-apply path; enabled in the integrated stack (dash-evo-tool).
 rehydration-apply = []
+# Pass-through to `platform-wallet/shielded` so the feature-gated
+# `PlatformWalletChangeSet::shielded` field is visible to the exhaustive
+# `versions::touched_domains` destructure (the R8 forgotten-domain guard).
+# Storage persists no shielded state itself; this only aligns visibility so
+# an added always-on field stays a compile error.
+shielded = ["platform-wallet/shielded"]

packages/rs-platform-wallet-storage/migrations/V002__unified.rs

@@ -0,0 +1,80 @@
+//! Unified additive migration for `platform-wallet-storage` (#3968).
+//!
+//! Additive-only: V001 stays byte-identical so refinery's applied-migration
+//! checksum for version 1 never diverges on an existing store. V002 lifts
+//! `max_supported_version()` from 1 to 2 automatically (the value is derived
+//! from the embedded list) and lands three concerns in one migration event:
+//!
+//! - `core_address_pool` — per-index address-pool rows with a `used` flag,
+//!   the first-class row store that replaces `core_utxos` script-derivation
+//!   for the address-reuse guard. `account_type` and `pool_type` are both in
+//!   the primary key: `account_type` so two accounts that collapse to the same
+//!   `(account_index, key_class)` sentinel (e.g. `IdentityRegistration` and
+//!   `ProviderVotingKeys`, both `0, 0`) never overwrite each other, and
+//!   `pool_type` so an External (receive) and Internal (change) pool never
+//!   collide at the same `address_index`. `script` (the address'
+//!   `script_pubkey`) is stored so the reader returns used addresses verbatim
+//!   and the UTXO writer can attribute an outpoint to its owning account, both
+//!   without re-deriving.
+//! - `meta_data_versions` — per-`(wallet_id, domain)` monotonic `seq`
+//!   bumped inside the flush transaction, the cache-invalidation keystone.
+//!   No FK (a domain row may be written before its typed parent syncs,
+//!   mirroring the `meta_*` tables); a soft-cascade trigger reaps rows on
+//!   wallet delete.
+//! - `meta_store_generation` — a single-row store-generation token,
+//!   initialized with `randomblob(16)` so the rendered SQL stays deterministic (the
+//!   content fingerprint pins the text, the runtime value is unique per
+//!   store). Regenerated on restore.
+//!
+//! No MAC column ships here — manifest authentication is deferred out of
+//! this workstream (dev-plan §7).
+
+pub fn migration() -> String {
+    "\
+CREATE TABLE core_address_pool (
+    wallet_id BLOB NOT NULL,
+    account_type TEXT NOT NULL,
+    account_index INTEGER NOT NULL,
+    key_class INTEGER NOT NULL DEFAULT 0,
+    pool_type INTEGER NOT NULL CHECK (pool_type IN (0, 1, 2, 3)),
+    address_index INTEGER NOT NULL,
+    script BLOB NOT NULL,
+    used INTEGER NOT NULL DEFAULT 0 CHECK (used IN (0, 1)),
+    PRIMARY KEY (wallet_id, account_type, account_index, key_class, pool_type, address_index),
+    FOREIGN KEY (wallet_id) REFERENCES wallets(wallet_id) ON DELETE CASCADE
+);
+
+CREATE INDEX idx_core_address_pool_used
+    ON core_address_pool(wallet_id, used);
+
+-- The UTXO writer attributes an outpoint to its owning account by matching
+-- the outpoint's script against a pool row.
+CREATE INDEX idx_core_address_pool_script
+    ON core_address_pool(wallet_id, script);
+
+CREATE TABLE meta_data_versions (
+    wallet_id BLOB NOT NULL,
+    domain TEXT NOT NULL,
+    seq INTEGER NOT NULL DEFAULT 0,
+    PRIMARY KEY (wallet_id, domain)
+);
+
+-- Soft-cascade reap, matching the meta_* tables: no FK (a domain may be
+-- bumped before its typed parent exists), so a trigger clears rows when
+-- the owning wallet is deleted.
+CREATE TRIGGER cascade_meta_data_versions_on_wallet_delete
+AFTER DELETE ON wallets
+FOR EACH ROW
+BEGIN
+    DELETE FROM meta_data_versions WHERE wallet_id = OLD.wallet_id;
+END;
+
+CREATE TABLE meta_store_generation (
+    id INTEGER NOT NULL PRIMARY KEY CHECK (id = 0),
+    generation BLOB NOT NULL
+);
+
+INSERT INTO meta_store_generation (id, generation) VALUES (0, randomblob(16));
+"
+    .to_string()
+}

packages/rs-platform-wallet-storage/src/sqlite/backup.rs

@@ -132,14 +132,17 @@ pub fn run_to(src: &Connection, dest: &Path) -> Result<(), WalletStorageError> {
 ///
 /// Validation runs against the source and again against the STAGED bytes,
 /// under a SQLite-native `BEGIN EXCLUSIVE` on `dest_db_path` that blocks
-/// every other SQLite peer (which advisory flock could not). The staged
-/// temp is `persist`-ed as an atomic rename only after all gates pass, and
-/// that rename is the commit point: if it fails, the live DB and its WAL/SHM
-/// siblings are left untouched, so a failed restore never strands the old DB
-/// without its WAL-committed state. The now-stale WAL/SHM siblings are
-/// unlinked only AFTER the swap succeeds (so a leftover `-wal` can't shadow
-/// the restored DB); the parent dir is fsynced afterward. See the numbered
-/// steps in the body for the per-phase rationale.
+/// every other SQLite peer (which advisory flock could not). The
+/// store-generation token is rotated INTO the staged temp before the swap,
+/// so the single commit point brings in the restored bytes and the fresh
+/// token together — a peer never observes restored content carrying the
+/// source's stale token. The staged temp is `persist`-ed as an atomic rename
+/// only after all gates pass, and that rename is the commit point: if it
+/// fails, the live DB and its WAL/SHM siblings are left untouched, so a failed
+/// restore never strands the old DB without its WAL-committed state. The
+/// now-stale WAL/SHM siblings are unlinked only AFTER the swap succeeds (so a
+/// leftover `-wal` can't shadow the restored DB); the parent dir is fsynced
+/// afterward. See the numbered steps in the body for the per-phase rationale.
 ///
 /// # Lock-release-before-rename trade-off
 ///
@@ -224,7 +227,27 @@ pub fn restore_from(dest_db_path: &Path, src_backup: &Path) -> Result<(), Wallet
         crate::sqlite::migrations::assert_schema_history_well_formed(&staged)?;
     }
 
-    // 5. chmod 0o600 on the temp BEFORE persist so the destination
+    // 5. Regenerate the store-generation token INTO the staged temp, before
+    //    the atomic rename, so the single commit point (step 8) swaps in the
+    //    restored bytes and the rotated token together — there is no window
+    //    where restored content is observable with the source's stale token.
+    //    The staged DB is switched to DELETE journaling first so the UPDATE
+    //    lands in the main file with no `-wal` frames stranded outside the
+    //    rename; the reopened destination is forced back to its configured
+    //    journal mode on its next open. A pre-V002 backup has no generation
+    //    table; `regenerate_generation` is a no-op there and the token is
+    //    (re)seeded on its later migration to V002.
+    {
+        let conn =
+            crate::sqlite::conn::open_conn(tmp.path(), crate::sqlite::conn::Access::ReadWrite)?;
+        conn.pragma_update(None, "journal_mode", "DELETE")?;
+        crate::sqlite::schema::versions::regenerate_generation(&conn)?;
+        drop(conn);
+        // Durably flush the regenerated token before the rename commits it.
+        tmp.as_file().sync_all()?;
+    }
+
+    // 6. chmod 0o600 on the temp BEFORE persist so the destination
     //    inherits owner-only mode via the rename (post-persist chmod could
     //    fail with the new DB already live).
     #[cfg(unix)]
@@ -234,7 +257,7 @@ pub fn restore_from(dest_db_path: &Path, src_backup: &Path) -> Result<(), Wallet
             .set_permissions(std::fs::Permissions::from_mode(0o600))?;
     }
 
-    // 6. Release the EXCLUSIVE lock before the rename/unlinks: on Windows /
+    // 7. Release the EXCLUSIVE lock before the rename/unlinks: on Windows /
     //    some FUSE mounts `remove_file` on a still-open file returns
     //    `PermissionDenied`, and the rename window wants a clean close (see
     //    lock-release trade-off above).
@@ -243,18 +266,20 @@ pub fn restore_from(dest_db_path: &Path, src_backup: &Path) -> Result<(), Wallet
         drop(conn);
     }
 
-    // 7. Persist the staged DB atomically over the destination FIRST. The
-    //    atomic rename is the commit point: if it fails (disk full, EXDEV,
-    //    perms) the live DB and its WAL/SHM siblings are left untouched, so a
-    //    failed restore can never strand the old DB without its WAL-committed
-    //    state. Sibling cleanup (step 8) runs only once the swap has succeeded.
+    // 8. Persist the staged DB atomically over the destination. The atomic
+    //    rename is the single commit point: it swaps in both the restored
+    //    bytes and the rotated generation token together. If it fails (disk
+    //    full, EXDEV, perms) the live DB and its WAL/SHM siblings are left
+    //    untouched, so a failed restore can never strand the old DB without
+    //    its WAL-committed state. Sibling cleanup (step 9) runs only once the
+    //    swap has succeeded.
     tmp.persist(dest_db_path)
         .map_err(|e| WalletStorageError::Io(e.error))?;
 
-    // 8. Clear the now-stale WAL/SHM siblings AFTER the swap so a leftover
+    // 9. Clear the now-stale WAL/SHM siblings AFTER the swap so a leftover
     //    `-wal` can't shadow the restored DB on the next open. Sibling paths
     //    use `OsString::push` so non-UTF-8 bytes round-trip; `NotFound` is a
-    //    silent no-op. The lock conn was dropped in step 6 for cross-platform
+    //    silent no-op. The lock conn was dropped in step 7 for cross-platform
     //    unlink semantics.
     if let Some(file_name) = dest_db_path.file_name() {
         for ext in ["-wal", "-shm"] {
@@ -269,10 +294,10 @@ pub fn restore_from(dest_db_path: &Path, src_backup: &Path) -> Result<(), Wallet
         }
     }
 
-    // 9. Make the rename + unlink dentry updates durable.
+    // 10. Make the rename + unlink dentry updates durable.
     fsync_parent_dir(dest_db_path)?;
 
-    // 10. Re-tighten perms (idempotent; SQLite may re-materialise -wal/-shm).
+    // 11. Re-tighten perms (idempotent; SQLite may re-materialise -wal/-shm).
     apply_secure_permissions(dest_db_path)?;
     Ok(())
 }

packages/rs-platform-wallet-storage/src/sqlite/migrations.rs

@@ -175,6 +175,52 @@ pub fn embedded_migrations_fingerprint() -> [u8; 32] {
     hasher.finalize().into()
 }
 
+/// SHA-256 over `(version, name, rendered SQL)` of every embedded migration
+/// in version order. Unlike [`embedded_migrations_fingerprint`] this is
+/// content-level: it pins each migration's SQL body, so an in-place DDL edit
+/// (e.g. renaming a table inside a same-named file) breaks the golden test.
+/// This is the guard the D0 schema freeze relies on; the identity-only
+/// fingerprint cannot catch a same-name body edit.
+///
+/// The SQL *text* is deterministic even where a value is generated at run
+/// time (`randomblob(16)`): the literal string is hashed, not the runtime
+/// bytes.
+#[cfg(any(test, feature = "__test-helpers"))]
+pub fn embedded_migrations_sql_fingerprint() -> [u8; 32] {
+    use sha2::{Digest, Sha256};
+    let mut migrations = migrations::runner().get_migrations().clone();
+    migrations.sort_by_key(|m| m.version());
+    let mut hasher = Sha256::new();
+    for m in &migrations {
+        hasher.update((m.version() as u32).to_be_bytes());
+        hasher.update([0u8]);
+        hasher.update(m.name().as_bytes());
+        hasher.update([0u8]);
+        let sql = m
+            .sql()
+            .expect("embedded migrations always carry rendered SQL");
+        hasher.update(sql.as_bytes());
+        hasher.update([0u8]);
+    }
+    hasher.finalize().into()
+}
+
+/// Rendered SQL of every embedded migration, in version order. Used by the
+/// schema-freeze grep guard to scan for retired table names.
+#[cfg(any(test, feature = "__test-helpers"))]
+pub fn embedded_migrations_sql() -> Vec<String> {
+    let mut migrations = migrations::runner().get_migrations().clone();
+    migrations.sort_by_key(|m| m.version());
+    migrations
+        .iter()
+        .map(|m| {
+            m.sql()
+                .expect("embedded migrations always carry rendered SQL")
+                .to_string()
+        })
+        .collect()
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;

packages/rs-platform-wallet-storage/src/sqlite/persister.rs

@@ -7,7 +7,7 @@ use std::sync::{Arc, Mutex, MutexGuard, OnceLock};
 use rusqlite::{Connection, OptionalExtension};
 
 use platform_wallet::changeset::{
-    ClientStartState, Merge, PersistenceError, PlatformWalletChangeSet, PlatformWalletPersistence,
+    ClientStartState, PersistenceError, PlatformWalletChangeSet, PlatformWalletPersistence,
 };
 use platform_wallet::wallet::platform_wallet::WalletId;
 
@@ -940,20 +940,37 @@ impl PlatformWalletPersistence for SqlitePersister {
                 .map_err(PersistenceError::from)?;
             let identity_keys = schema::identity_keys::load_state(&conn, &wallet_id)
                 .map_err(PersistenceError::from)?;
-            // Every address that ever held a UTXO (spent + unspent) is "used":
-            // the address-reuse guard so a used-then-emptied address is never
-            // handed back as a fresh receive address. The in-band pool snapshot
-            // was retired, so we derive this from the full core_utxos set.
-            let used_core_addresses =
-                schema::core_state::load_used_addresses(&conn, &wallet_id, network)
+            // Used addresses drive the reuse guard: a used-then-emptied
+            // address must never be handed back as a fresh receive address.
+            // Union the verbatim `core_address_pool` used-set with the
+            // `core_utxos`-derived set (spent + unspent). The guard is
+            // monotonic, so a mixed store — historical UTXOs plus a later
+            // partial pool snapshot that never enumerates them — must surface
+            // both; neither source may shadow the other. Deduped by script.
+            let used_core_addresses = {
+                let mut seen = std::collections::HashSet::new();
+                let mut union = Vec::new();
+                let pool = schema::core_pool::load_used_addresses(&conn, &wallet_id, network)
                     .map_err(PersistenceError::from)?;
+                let utxo = schema::core_state::load_used_addresses(&conn, &wallet_id, network)
+                    .map_err(PersistenceError::from)?;
+                for addr in pool.into_iter().chain(utxo) {
+                    if seen.insert(addr.script_pubkey().to_bytes()) {
+                        union.push(addr);
+                    }
+                }
+                union
+            };
 
             state.wallets.insert(
                 wallet_id,
                 platform_wallet::changeset::ClientWalletStartState {
                     network,
                     birth_height,
                     account_manifest,
+                    // SQLite rehydration replays the keyless projection onto a
+                    // fresh skeleton; it mints no full snapshot.
+                    core_wallet_info: None,
                     core_state,
                     identity_manager,
                     unused_asset_locks,
@@ -994,25 +1011,9 @@ impl PlatformWalletPersistence for SqlitePersister {
 /// from the public fields so no storage-only helper leaks into the
 /// `rs-platform-wallet` API.
 fn populated_field_count(cs: &PlatformWalletChangeSet) -> usize {
-    [
-        cs.core.is_empty(),
-        cs.identities.is_empty(),
-        cs.identity_keys.is_empty(),
-        cs.contacts.is_empty(),
-        cs.platform_addresses.is_empty(),
-        cs.asset_locks.is_empty(),
-        cs.token_balances.is_empty(),
-        cs.dashpay_profiles.as_ref().is_none_or(|m| m.is_empty()),
-        cs.dashpay_payments_overlay
-            .as_ref()
-            .is_none_or(|m| m.is_empty()),
-        cs.wallet_metadata.is_none(),
-        cs.account_registrations.is_empty(),
-        cs.account_address_pools.is_empty(),
-    ]
-    .iter()
-    .filter(|empty| !**empty)
-    .count()
+    // Single source of truth with the version-domain mapping: each populated
+    // field is exactly one touched domain.
+    schema::versions::touched_domains(cs).len()
 }
 
 fn validate_config(config: &SqlitePersisterConfig) -> Result<(), WalletStorageError> {
@@ -1088,10 +1089,12 @@ fn apply_changeset_to_tx(
     if !cs.account_registrations.is_empty() {
         schema::accounts::apply_registrations(tx, wallet_id, &cs.account_registrations)?;
     }
-    // `account_address_pools` is intentionally NOT applied: UTXO attribution
-    // is hardcoded to the default account (index 0) in `core_state`, so the
-    // pool snapshot is no longer a storage input. The changeset field is kept
-    // for API stability and still feeds non-storage consumers.
+    // Pools land before core so the UTXO writer can attribute each outpoint
+    // to its owning account by matching the outpoint's script against a
+    // freshly-written `core_address_pool` row.
+    if !cs.account_address_pools.is_empty() {
+        schema::core_pool::apply_pools(tx, wallet_id, &cs.account_address_pools)?;
+    }
     if let Some(core) = cs.core.as_ref() {
         schema::core_state::apply(tx, wallet_id, core)?;
     }
@@ -1121,6 +1124,9 @@ fn apply_changeset_to_tx(
             cs.dashpay_payments_overlay.as_ref(),
         )?;
     }
+    // Bump each touched domain's version inside this same tx so a domain's
+    // cache-invalidation marker commits atomically with its data.
+    schema::versions::bump_touched_domains(tx, wallet_id, cs)?;
     Ok(())
 }