WIP: discord system — transactional token leases + desired-state streams (c2-core, unwired)

Paused by owner instruction; not wired into routers/mqtt yet, untested.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

drb-c2-core/app/internal/firestore.py

@@ -161,6 +161,26 @@ async def doc_delete(collection: str, doc_id: str) -> None:
     await asyncio.to_thread(ref.delete)
 
 
+def _run_transaction_sync(fn):
+    """Run ``fn(transaction)`` inside a Firestore transaction (retried on contention).
+
+    ``fn`` must do every read (``ref.get(transaction=txn)`` /
+    ``query.stream(transaction=txn)``) before any write (``txn.set/update``) —
+    Firestore's rule, and the reason this takes a function rather than being a
+    context manager: the SDK re-runs the whole function when a read document
+    changed underneath it. Bypasses the replay sandbox on purpose; nothing that
+    uses it touches calls/incidents.
+    """
+    txn = db.transaction()
+    return fs.transactional(fn)(txn)
+
+
+async def run_transaction(fn):
+    """Async wrapper for _run_transaction_sync. Tests patch this with an
+    in-memory fake (tests/fake_firestore.py)."""
+    return await asyncio.to_thread(_run_transaction_sync, fn)
+
+
 async def doc_get_cached(collection: str, doc_id: str, ttl: float = 300.0) -> Optional[dict]:
     """
     Like doc_get but backed by a short-lived in-memory TTL cache.