docs(platform-wallet-storage): document V007 and pin the materialised release

Two review follow-ups.

`SCHEMA.md` described `spent_in_txid` but not the three objects V007
creates, so the reference no longer matched the database:
`core_utxos.winner_mined_height`, `core_sync_state.chainlock_height`, and
the partial `idx_core_utxos_unmaterialized` covering exactly the
unmaterialised rows. All three are now in the diagrams and the prose,
including what the stamp decides (a placeholder's lifetime, never its
existence) and why the funding upsert clears it.

The second was raised as a missing release path for a materialised
claim. The path exists — `apply` splits on `height IS NULL`, deleting an
unmaterialised placeholder outright and freeing a materialised row in
place — but nothing pinned that half: every other release test exercises
the placeholder, so a release that silently skipped materialised rows
would have left a live coin spent forever with nothing else able to free
it, the collector being deliberately unable to take such a row.

`a_release_frees_a_materialised_claim_in_place` closes that: seed a
stamped tombstone, materialise it through the funding upsert, then have
the winner itself swept with the coin released, and assert the row comes
back unspent in place — keeping its funding data — and stays so across a
restart.

Author: jeanpierreroma

packages/rs-platform-wallet-storage/SCHEMA.md

@@ -94,6 +94,7 @@ erDiagram
         INTEGER account_index
         INTEGER spent "0 | 1"
         BLOB spent_in_txid "set by apply_sweep for an unresolved held input; else NULL"
+        INTEGER winner_mined_height "V007: sweep winner's mined height; NULL when unstamped or materialised"
     }
 
     CORE_INSTANT_LOCKS {
@@ -115,6 +116,7 @@ erDiagram
         BLOB wallet_id PK "one row per wallet"
         INTEGER last_processed_height "NULL until first block processed"
         INTEGER synced_height "NULL until first sync"
+        INTEGER chainlock_height "V007: monotonic-max applied chainlock height; NULL until one is applied"
     }
 ```
 
@@ -392,9 +394,26 @@ referenced `core_transactions` row is deleted (instead of a native
 `ON DELETE SET NULL`, which would also null the NOT NULL `wallet_id`
 column) — and by a later sweep that releases the same outpoint.
 
+`winner_mined_height` (V007) stamps that claim with the mined height of the
+winner named in `spent_in_txid`, and decides the placeholder's lifetime
+rather than its existence. A block-context sweep stamps the winner's own
+height and `collect_finalized_tombstones` evicts the row once
+`min(chainlock_height, synced_height)` reaches it — upstream's
+`prune_finalized_observed_spends` boundary verbatim. An InstantSend-locked
+winner that is not yet mined leaves it NULL: the lock alone settles the
+input, but it carries no height to key a lifetime on, so the row resolves
+only through proof (the funding upsert materialising it, a later
+block-context sweep re-stamping it, or a release). The funding upsert
+clears the stamp, because a materialised row is the wallet's own coin held
+spent and is permanently outside the collector's reach.
+
 - PK: `(wallet_id, outpoint)`.
 - FK: `wallet_id → wallet_metadata(wallet_id) ON DELETE CASCADE`.
 - Index: `idx_core_utxos_spent(wallet_id, spent)`.
+- Index: `idx_core_utxos_unmaterialized(wallet_id, winner_mined_height)
+  WHERE height IS NULL` (V007) — covers exactly the unmaterialised rows, so
+  the collector's per-round scan touches tombstones rather than the
+  wallet's full spent history.
 
 ### `core_instant_locks`
 
@@ -419,6 +438,13 @@ One row per wallet, holding monotonically-advancing SPV sync watermarks.
 `last_processed_height` and `synced_height` are NULL until the first
 block is processed.
 
+`chainlock_height` (V007) mirrors `CoreChangeSet::last_applied_chain_lock`
+as a monotonic max — the height alone, which this store previously dropped.
+It is one half of the finality boundary
+`collect_finalized_tombstones` collects sweep tombstones against, so a
+tombstone is never collected before a chainlock has been persisted,
+matching upstream's "no-op until a chainlock has been applied".
+
 - PK: `wallet_id` (single-row-per-wallet).
 - FK: `wallet_id → wallet_metadata(wallet_id) ON DELETE CASCADE`.
 

packages/rs-platform-wallet-storage/tests/sqlite_transaction_sweeps.rs

@@ -2962,6 +2962,96 @@ fn a_materialised_claim_is_never_collected() {
     );
 }
 
+/// A MATERIALISED claim is releasable, and release is the only thing that
+/// frees it.
+///
+/// The collector deliberately never takes such a row
+/// (`a_materialised_claim_is_never_collected`): once the funding output has
+/// classified, the row carries real funding data and is the wallet's own coin
+/// held spent, so no finality boundary may reclaim it. That leaves exactly one
+/// way back — a later sweep naming the outpoint in `released_outpoints`, which
+/// the unmaterialised path handles by DELETE and this one by an in-place
+/// `spent = 0, spent_in_txid = NULL`.
+///
+/// Pinned because the two paths diverge on `height IS NULL` and every other
+/// release test exercises the placeholder half; without this one, a release
+/// that silently skipped materialised rows would leave a live coin spent
+/// forever with nothing else able to free it.
+#[test]
+fn a_release_frees_a_materialised_claim_in_place() {
+    let (persister, _tmp, path) = fresh_persister();
+    let w: WalletId = wid(0xF7);
+    ensure_wallet_meta(&persister, &w);
+
+    let addr = p2pkh(0x62);
+    let funding_txid = Txid::from_byte_array([0x71; 32]);
+    let p = OutPoint::new(funding_txid, 0);
+    let loser = Txid::from_byte_array([0x72; 32]);
+    let winner = Txid::from_byte_array([0x73; 32]);
+    let final_winner = Txid::from_byte_array([0x74; 32]);
+
+    let mut conn = persister.lock_conn_for_test();
+    derive_address(&conn, &w, 0, &addr);
+    apply_heights(&mut conn, &w, 100);
+    seed_tombstone(&mut conn, &w, p, loser, winner, Some(WINNER_HEIGHT));
+
+    // The funding output classifies: real data, stamp cleared, still spent.
+    {
+        let tx = conn.transaction().unwrap();
+        let cs = CoreChangeSet {
+            new_utxos: vec![make_utxo(&addr, funding_txid, 0, 50_000)],
+            ..Default::default()
+        };
+        core_state::apply(&tx, &w, &cs).unwrap();
+        tx.commit().unwrap();
+    }
+    assert_eq!(
+        utxo_row_state(&conn, &w, &p),
+        Some((true, Some(10), None)),
+        "sanity: materialised — real height, stamp cleared, still spent"
+    );
+    assert!(
+        !unspent(&conn, &w).contains(&p),
+        "sanity: a held coin is not spendable"
+    );
+
+    // The winner is itself swept, and this time the coin comes back free.
+    {
+        let tx = conn.transaction().unwrap();
+        let cs = CoreChangeSet {
+            sweeps: vec![SweepBatch {
+                txids: vec![winner],
+                superseded_by: final_winner,
+                winner_mined_height: Some(WINNER_HEIGHT),
+                released_outpoints: vec![p],
+            }],
+            ..Default::default()
+        };
+        core_state::apply(&tx, &w, &cs).unwrap();
+        tx.commit().unwrap();
+    }
+
+    assert_eq!(
+        utxo_row_state(&conn, &w, &p),
+        Some((false, Some(10), None)),
+        "a released materialised claim is freed in place, keeping its funding data"
+    );
+    assert!(
+        unspent(&conn, &w).contains(&p),
+        "and the coin is spendable again"
+    );
+
+    // Durable: the in-place release is not a memory-only flip.
+    drop(conn);
+    drop(persister);
+    let persister = SqlitePersister::open(SqlitePersisterConfig::new(&path)).unwrap();
+    let conn = persister.lock_conn_for_test();
+    assert!(
+        unspent(&conn, &w).contains(&p),
+        "the release must hold across a restart"
+    );
+}
+
 /// A held, unmaterialised row with a NULL winner height is never
 /// collected. The mempool-context sweep path writes exactly this shape
 /// (an IS-locked, unmined winner has no finality horizon to stamp), and