Add Quantum Arcade design spec

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

docs/superpowers/specs/2026-08-05-quantum-arcade-design.md

@@ -0,0 +1,181 @@
+# Quantum Arcade — Design Spec
+
+**Date:** 2026-08-05
+**Status:** Approved for planning
+**Repo:** https://gitea.thetempleofdoom.com/drjones/casino.git
+
+## 1. Context and Scope
+
+Quantum Arcade is a private, LAN-hosted physics gaming platform for the host and
+their friends, including at parties of up to ~100 people on phones. It runs
+entirely on a single Linux box owned by the host.
+
+**In scope:** deterministic physics games (group and single-player), a
+provably-fair RNG, a double-entry ledger, Lightning deposits/withdrawals and
+peer-to-peer transfers, ephemeral chat, and a single-box Docker deployment.
+
+**Out of scope for this phase:** public internet deployment, KYC/identity
+verification, geo-gating, and licensed real-money operation. The architecture
+keeps these as additive modules rather than rewrites, but they are not built
+here and this system is not to be exposed publicly as-is.
+
+**Success criteria:**
+- A guest joins from a phone in under 5 seconds with no account creation.
+- 100 concurrent phones sustain a group round with no visible desync.
+- Any player can independently verify any round outcome on their own device.
+- End-of-night balances reconcile exactly, with a per-transaction explanation.
+
+## 2. Identity
+
+Identity is a keypair, not an account.
+
+On first visit the browser generates an ed25519 keypair stored in IndexedDB and
+prompts for a nickname. The public key is the player ID: it is what the ledger
+posts against and what signs bet intents. There is no email, password, reset
+flow, or KYC.
+
+Multi-device: a QR code exports the key from one device to another.
+Key loss means balance loss. This is accepted and stated plainly in the UI.
+
+Nicknames are display-only and non-unique; the pubkey prefix disambiguates.
+
+## 3. Architecture
+
+One Go binary with enforced internal module boundaries, plus PostgreSQL, Redis,
+LND, and Caddy. Nine separate services on one machine would add latency and
+operational burden with no benefit at this scale.
+
+```
+Caddy (TLS termination, static assets, WebSocket upgrade)
+  └── quantum-arcade (single Go binary)
+        ├── ledger/   double-entry postings, append-only
+        ├── rng/      commit-reveal seed lifecycle
+        ├── sim/      deterministic physics core
+        ├── room/     round lifecycle, tick broadcast
+        ├── wallet/   Lightning in/out, P2P transfers
+        └── chat/     ephemeral, in-memory only
+PostgreSQL  ledger, rounds, seeds, results
+Redis       live room state, presence, rate limits
+LND         Lightning node, isolated wallet
+```
+
+Modules communicate only through Go interfaces defined by the *consumer*. No
+module imports another's internal types. Extracting a module into its own
+process later is a transport change at the call site, not a rewrite.
+
+**Scaling posture:** 100 concurrent WebSocket clients is a small fraction of a
+single Go process's capacity. The genuine constraint is PostgreSQL write
+throughput at settlement, addressed by settling each round in exactly one
+transaction with batched postings.
+
+## 4. Deterministic Simulation Core
+
+The physics core is fixed-timestep and integer-seeded, using fixed-point
+arithmetic rather than floating point to guarantee bit-identical results across
+platforms. It is compiled twice from one source: natively for the authoritative
+server, and to WASM for the browser.
+
+Consequences:
+- The server broadcasts a seed, not a position stream. Bandwidth per additional
+  phone is negligible.
+- Any client can replay any historical round locally.
+- The public verifier is simply the sim run against published inputs.
+
+Determinism is a hard invariant, enforced by test (§9), not a convention.
+
+## 5. Provable Fairness
+
+Per round:
+
+1. **Commit.** Server generates `serverSeed`, publishes `SHA256(serverSeed)`
+   before the betting window opens.
+2. **Client seed.** Derived from the concatenated public keys of all
+   participants in the round, in join order. The host cannot know the outcome in
+   advance because the host does not control the inputs.
+3. **Outcome.** `HMAC-SHA256(serverSeed, clientSeed || nonce)` seeds the sim.
+   The crash point / result is a pure function of that seed.
+4. **Reveal.** After settlement the server publishes `serverSeed`. Clients
+   recompute the commitment hash, re-derive the seed, and re-run the WASM sim.
+
+Verification runs on-device in roughly 400ms and requires trusting no server
+response. Seeds, commitments, and participant sets are retained permanently.
+
+## 6. Games
+
+All games share the sim core and the fairness pipeline.
+
+**Group rounds** — a fixed ~5-minute cadence; all players watch the same
+simulation. Three crash variants rotate:
+- *Rocket vs. gravity* — multiplier is altitude; the craft visibly strains as
+  fuel depletes toward the seeded crash point.
+- *Orbital decay* — multiplier is orbits completed, each pass dipping lower.
+- *Stacking tower* — multiplier is height; wobble grows until collapse.
+
+Round lifecycle: `betting_open` → `locked` → `running` → `settled`. Cash-out
+intents are signed by the player key and accepted only while `running`.
+
+**Single-player** — always available between group rounds, ~10 seconds per play,
+one tap to start: gravity-slingshot targeting, physics drop, and a
+momentum/timing challenge. Same fairness proof, per-play nonce.
+
+## 7. Ledger and Money
+
+Double-entry, append-only. No row is ever updated or deleted; corrections are
+compensating entries.
+
+Every posting records: transaction ID, timestamp, player pubkey, account,
+amount, round ID, balance before, balance after. Each transaction's postings sum
+to zero. Player balances may never go negative.
+
+Accounts: per-player balances, house pot, and Lightning bridge accounts. The
+house pot balance is displayed in the UI to all players — the pool is never
+opaque.
+
+**Lightning:** deposit and withdraw via invoice/QR against the on-box LND node.
+The LND wallet is isolated from application state, with its own credentials and
+backup path.
+
+**Peer-to-peer transfers:** instant, purely internal ledger entries between two
+player accounts, signed by the sender's key. This is the primary way value moves
+between friends at a party.
+
+## 8. Interface and Feel
+
+Phone-first portrait layout; cash-out is thumb-reachable.
+
+Deep obsidian and indigo ground, with dense ornate filigree etched into the
+background. Vibrant cyan and magenta are reserved exclusively for the live
+multiplier, the player's balance, and the cash-out control — everything that
+matters is luminous, nothing else is.
+
+Ambient music is synthesized in WebAudio: endless, non-looping, and shipping
+with zero audio assets.
+
+Chat is a compact sidebar, in-memory only, discarded when the round ends.
+Nothing is written to disk.
+
+## 9. Testing
+
+- **Ledger:** property-based tests for the invariants in §7 — postings sum to
+  zero, balances never negative, no value created or destroyed across arbitrary
+  transaction sequences.
+- **Sim determinism:** identical seed produces identical output across 10,000
+  runs, and native output matches WASM output byte-for-byte.
+- **Fairness:** commitment always matches revealed seed; independent
+  reimplementation of the verifier agrees with the server on recorded rounds.
+- **Load:** harness simulating 150 concurrent phone clients through a complete
+  group round, asserting no desync and correct settlement.
+
+## 10. Deployment
+
+`docker compose up` on the single Linux box. Postgres and LND data on persistent
+volumes with scheduled backups. Caddy terminates TLS on the LAN. Prometheus and
+Grafana included for host and application metrics.
+
+## 11. Explicit Non-Goals
+
+- Not exposed to the public internet in this phase.
+- No engagement mechanics designed to extend play beyond a player's intent: no
+  loss-chasing prompts, no artificial near-miss tuning, no dark patterns on
+  cash-out. Game feel comes from the physics being genuinely good.
+- No mixing or obfuscation of fund provenance. The ledger is the product.