fix(economy): BEGIN IMMEDIATE for write transactions (concurrency-safe)

Root cause of the fresh-DB multi-connection write failure: economy writes ran in
a DEFERRED transaction (pool.begin() = BEGIN) that read then wrote; SQLite returns
SQLITE_BUSY (code 5, 'database is locked') *immediately* when a deferred tx
upgrades to a write while another holds the write lock, bypassing busy_timeout to
avoid deadlock. Fix: open each write op with BEGIN IMMEDIATE on a dedicated pooled
connection (finish() commits/rolls back), taking the write lock up front so
busy_timeout serializes writers. Reproduction test: 100 fresh DBs x 8 concurrent
grant_reward — was 644/800 failures, now 800/800 succeed with correct final
balance (no lost update). Reads unchanged.

src/services/economy.rs

@@ -215,6 +215,25 @@ pub async fn list_unopened_entitlements(pool: &Pool, club_id: &str) -> AppResult
         .collect())
 }
 
+/// Commit on `Ok`, roll back on `Err`. Paired with a `BEGIN IMMEDIATE` opened on
+/// the same connection, so the write lock is held for the whole op and a
+/// concurrent writer waits (honoring `busy_timeout`) instead of failing: a
+/// DEFERRED `pool.begin()` upgrades to a write only at the first write, where
+/// SQLite returns SQLITE_BUSY *immediately* (bypassing the busy handler to avoid
+/// deadlock) — the fresh-DB multi-connection write failure.
+async fn finish<T>(conn: &mut SqliteConnection, result: AppResult<T>) -> AppResult<T> {
+    match result {
+        Ok(v) => {
+            sqlx::query("COMMIT").execute(&mut *conn).await?;
+            Ok(v)
+        }
+        Err(e) => {
+            let _ = sqlx::query("ROLLBACK").execute(&mut *conn).await;
+            Err(e)
+        }
+    }
+}
+
 /// Debit `cost` and grant one entitlement, atomically. Fail-closed: if the club
 /// cannot afford `cost`, nothing is debited and no entitlement is created.
 pub async fn purchase_entitlement(
@@ -223,14 +242,18 @@ pub async fn purchase_entitlement(
     cost: i64,
     definition_id: &str,
 ) -> AppResult<PurchaseReceipt> {
-    let mut tx = pool.begin().await?;
-    let balance = debit(&mut tx, club_id, cost).await?;
-    let entitlement_id = grant_entitlement(&mut tx, club_id, definition_id).await?;
-    tx.commit().await?;
-    Ok(PurchaseReceipt {
-        balance,
-        entitlement_id,
-    })
+    let mut conn = pool.acquire().await?;
+    sqlx::query("BEGIN IMMEDIATE").execute(&mut *conn).await?;
+    let result = async {
+        let balance = debit(&mut conn, club_id, cost).await?;
+        let entitlement_id = grant_entitlement(&mut conn, club_id, definition_id).await?;
+        Ok(PurchaseReceipt {
+            balance,
+            entitlement_id,
+        })
+    }
+    .await;
+    finish(&mut conn, result).await
 }
 
 /// Debit `cost` and mint one owned item, atomically. Fail-closed: if the club
@@ -245,11 +268,15 @@ pub async fn purchase_item(
     item_id: &str,
     card_id: &str,
 ) -> AppResult<i64> {
-    let mut tx = pool.begin().await?;
-    let balance = debit(&mut tx, club_id, cost).await?;
-    add_item(&mut tx, club_id, item_id, card_id).await?;
-    tx.commit().await?;
-    Ok(balance)
+    let mut conn = pool.acquire().await?;
+    sqlx::query("BEGIN IMMEDIATE").execute(&mut *conn).await?;
+    let result = async {
+        let balance = debit(&mut conn, club_id, cost).await?;
+        add_item(&mut conn, club_id, item_id, card_id).await?;
+        Ok(balance)
+    }
+    .await;
+    finish(&mut conn, result).await
 }
 
 /// Debit `cost` and mint several owned items, atomically. Fail-closed: if the
@@ -263,13 +290,17 @@ pub async fn purchase_items(
     cost: i64,
     items: &[GrantedItem],
 ) -> AppResult<i64> {
-    let mut tx = pool.begin().await?;
-    let balance = debit(&mut tx, club_id, cost).await?;
-    for item in items {
-        add_item(&mut tx, club_id, &item.item_id, &item.card_id).await?;
+    let mut conn = pool.acquire().await?;
+    sqlx::query("BEGIN IMMEDIATE").execute(&mut *conn).await?;
+    let result = async {
+        let balance = debit(&mut conn, club_id, cost).await?;
+        for item in items {
+            add_item(&mut conn, club_id, &item.item_id, &item.card_id).await?;
+        }
+        Ok(balance)
     }
-    tx.commit().await?;
-    Ok(balance)
+    .await;
+    finish(&mut conn, result).await
 }
 
 /// Consume an entitlement once and add its granted items, atomically. If any
@@ -281,31 +312,38 @@ pub async fn redeem_entitlement(
     entitlement_id: &str,
     items: &[GrantedItem],
 ) -> AppResult<String> {
-    let mut tx = pool.begin().await?;
-    let definition_id = consume_entitlement(&mut tx, club_id, entitlement_id).await?;
-    for item in items {
-        add_item(&mut tx, club_id, &item.item_id, &item.card_id).await?;
+    let mut conn = pool.acquire().await?;
+    sqlx::query("BEGIN IMMEDIATE").execute(&mut *conn).await?;
+    let result = async {
+        let definition_id = consume_entitlement(&mut conn, club_id, entitlement_id).await?;
+        for item in items {
+            add_item(&mut conn, club_id, &item.item_id, &item.card_id).await?;
+        }
+        Ok(definition_id)
     }
-    tx.commit().await?;
-    Ok(definition_id)
+    .await;
+    finish(&mut conn, result).await
 }
 
 /// Remove an owned item and credit `price`, atomically. Fail-closed: if the item
 /// is not owned by the club nothing is credited.
 pub async fn sell_item(pool: &Pool, club_id: &str, item_id: &str, price: i64) -> AppResult<i64> {
-    let mut tx = pool.begin().await?;
-    remove_item(&mut tx, club_id, item_id).await?;
-    let balance = credit(&mut tx, club_id, price).await?;
-    tx.commit().await?;
-    Ok(balance)
+    let mut conn = pool.acquire().await?;
+    sqlx::query("BEGIN IMMEDIATE").execute(&mut *conn).await?;
+    let result = async {
+        remove_item(&mut conn, club_id, item_id).await?;
+        credit(&mut conn, club_id, price).await
+    }
+    .await;
+    finish(&mut conn, result).await
 }
 
 /// Credit a reward to a club's balance atomically.
 pub async fn grant_reward(pool: &Pool, club_id: &str, amount: i64) -> AppResult<i64> {
-    let mut tx = pool.begin().await?;
-    let balance = credit(&mut tx, club_id, amount).await?;
-    tx.commit().await?;
-    Ok(balance)
+    let mut conn = pool.acquire().await?;
+    sqlx::query("BEGIN IMMEDIATE").execute(&mut *conn).await?;
+    let result = async { credit(&mut conn, club_id, amount).await }.await;
+    finish(&mut conn, result).await
 }
 
 #[cfg(test)]