Pete/pete_games_plan.md

Pete Games — games.parodia.dev

A web casino/arcade on Pete, authenticated by Authentik, playing for gogobee euros. Blackjack, Texas Hold'em, UNO (normal + no-mercy), Hangman, Trivia.

Companion to gogobee_mischief_plan.md, which already established the web↔game seam. This plan reuses that seam wholesale and does not invent a second one.

---

0. Progress — last updated 2026-07-13

A multi-session build. This section is the handover; read it before anything else.

Decisions taken (these close §9's open questions)

• Chips are 1:1 with euros. No second denomination.
• Session buy-in cap: €10,000, enforced against chips held plus buy-ins still in flight, so it can't be cleared by firing several requests at once.
• A house rake, 5% in blackjack's DefaultRules, taken from winnings only — never the stake. A push returns the bet untouched; a loss is never charged a fee.
• The site must look like Pete. Same cute, bubbly interface: layout.html, Fredoka/Nunito, the CSS vars, rounded-3xl cards, shadow-pete. Not a separate-looking SPA bolted onto the same box.
• Dealing is animated. Cards visibly dealt and flipped, chips that move. This is a requirement, not polish to drop when the clock runs out.

Done

• Phase 0 — euro idempotency (gogobee). euro_transactions.external_id + a partial unique index, and CreditIdem/DebitIdem in internal/plugin/euro.go: balance mutation and transaction log in one tx, keyed by the escrow GUID. A replay reports success without moving money again; a rejection writes nothing, so the same GUID stays retryable once the player is good for it. Six tests, including eight goroutines racing one GUID. (gogobee ab2bcf0)

• pete/internal/games/cards — the shared deck gogobee never had. RNG is threaded, never the package global, so a hand is reproducible from its seed. (pete 8310b30)

• pete/internal/games/blackjack — pure reducer, ApplyMove(state, move) (state, []Event, error), where an error means the move was illegal and nothing else. State is a plain value: it serializes, so a hand survives a redeploy, and it replays. Six decks, 3:2, dealer hits soft 17, plus the rake. (pete 8310b30)

• pete/internal/storage/games.go — the euro/chip border. game_chips, game_escrow, game_hands. Chips appear only once gogobee confirms it took the euros; chips are destroyed the moment a cash-out opens (so they can't be bet while their euros are in flight) and come back if the credit fails. Table cap, 30-minute reaper, per-hand audit log with seeds. 17 tests. (pete f9a98f7)

• The wire protocol. Pete serves GET /api/games/escrow/pending, POST …/claim, POST …/settled (internal/web/games.go), bearer-authed on the adventure ingest token. gogobee polls every 3s (internal/plugin/pete_games.go), claims a row, calls DebitIdem/CreditIdem against the escrow GUID, and pushes the verdict back through pete_emit_queue — which grew a path column so escrow verdicts ride the same durable queue as adventure facts rather than getting a second one. peteclient.Flush sends the verdict immediately instead of waiting out the 15s sender tick, because a player is watching a spinner. A row re-offered after a gogobee crash replays as a no-op: 13 tests across both repos, including a fake Pete that offers the same row three times and a player who is charged once.

Next, in order

1. Identity. PreferredUsername into the OIDC claims struct and the signed cookie; cookie Domain: ".parodia.dev" so a news session travels to games. Add the games redirect URI to the pete app in Authentik.
2. Frontend. Host branching in the mux, lobby + blackjack table, animated dealing. Nothing yet opens an escrow row from a browser — RequestBuyIn/RequestCashOut have no HTTP surface, on purpose: they need a signed-in Matrix identity, which is step 1.
3. Then Phase 2 (trivia, hangman), 3 (UNO), 4 (hold'em) as below.

Notes for whoever picks this up

• SQLite runs at MaxOpenConns(1) in both repos. Any db.Get().Exec inside an open transaction deadlocks against itself. Do the pre-work before Begin.
• A buy-in can currently take a player into debt. DebitIdem inherits BLACKJACK_DEBT_LIMIT (default −1000), so someone with an empty wallet can buy €1,000 of chips, win, and cash out while still €1,000 down. That is exactly what gogobee's Matrix blackjack already allows, so it is consistent rather than a bug — but a web casino runs far more hands, and this is the knob to turn if the economy starts leaking. A buy-in-specific floor of 0 is a two-line change.
• gogobee's blackjack taxes 5% of the gross payout into a community pot (communityTax). Pete's rake takes 5% of the profit. Deliberately different, and gentler; don't "fix" one to match the other without deciding which is right.

---

1. The three constraints everything else follows from

gogobee owns the euros. The ledger is euro_balances / euro_transactions (gogobee internal/db/db.go:1316,1324), tied to the wider economy — adventure, shop, lottery, mischief. Pete does not get a second wallet. Pete never writes a balance.

gogobee has no inbound API and isn't getting one. The only listening socket in the whole repo is the Matrix appservice transaction endpoint (internal/bot/appservice.go:255). Pete's own source says it plainly (internal/web/roster.go:23):

Direction of travel is gogobee → Pete ... Pete has no route back into the game box's network and we are not opening one.

So gogobee stays the only initiator. It polls Pete for work and pushes results back through the existing durable queue. Same as mischief (gogobee_mischief_plan.md:191-197).

One binary. Games live in the Pete process. gogobee already runs ~50 plugins and six games in one process with in-memory table state and it's fine. Caddy points games.parodia.dev at the same port; the mux branches on Host.

---

2. Identity — free, no link codes

MAS imports the Authentik preferred_username as the Matrix localpart (gogobee_mischief_plan.md:176-186). So an Authentik session on Pete maps to a Matrix user deterministically:

OIDC preferred_username  ->  strings.ToLower(u)  ->  @<u>:parodia.dev

Pete's SessionUser (internal/web/auth.go) carries Sub/Name/Email today. Add PreferredUsername to the claims struct and the signed cookie payload. That is the whole identity story.

Note the existing precedent: email_nag.go:52 already asserts "Authentik usernames == Matrix localparts".

---

3. Money — session escrow, not per-hand settlement

Why not settle each hand

Mischief is fire-and-forget: place an order, gogobee claims it within 30s, nobody cares. A blackjack hand cannot work that way. If every bet round-trips through a poll loop you wait half a minute to be dealt, and again for the payout.

The model

Borrow the semantics hold'em already uses — euro.Debit(..., "holdem_buyin") (holdem.go:319), euro.Credit(..., "holdem_cashout") (holdem.go:371) — and apply it to the whole web casino:

1. Buy in. You convert euros to chips for a games session. One debit. Tolerates poll latency.
2. Play. Blackjack, UNO, hold'em, all at full speed against chips held in Pete's SQLite. Zero economy calls in the hot path.
3. Cash out. Chips convert back to euros. One credit. Tolerates the same latency.

Two economy touches per session instead of two per hand. Poll latency stops mattering.

The invariant

A euro is either in gogobee's euro_balances or in Pete's chip escrow. Never both. It moves between them only via a GUID-idempotent claim.

Pete's balance display is advisory only, sourced from the roster push and up to 2 minutes stale. The authoritative check is euro.Debit at claim time. This preserves gogobee_mischief_plan.md:198-202 — "Pete never writes a balance, so no double-spend surface."

The prerequisite: euro idempotency (BLOCKING)

euro_transactions (db.go:1324) has no external id and no unique constraint. Debit is an atomic conditional UPDATE, but calling it twice debits twice. That is safe today only because every caller is a Matrix message that arrives once. A retrying poll loop breaks that: a claim that succeeds but whose ack is lost on the wire gets retried, and the player pays twice.

Before any of this ships:

ALTER TABLE euro_transactions ADD COLUMN external_id TEXT;
CREATE UNIQUE INDEX idx_euro_tx_external ON euro_transactions(external_id)
  WHERE external_id IS NOT NULL;

plus CreditIdem(userID, amount, reason, externalID) / DebitIdem(...) in euro.go that do the balance mutation and the transaction insert in one tx, and treat a unique-violation on external_id as success-already-applied. Everything web-initiated goes through these.

---

4. The wire protocol

All new Pete endpoints are bearer-authed with the existing ingest token (internal/web/adventure.go:307 bearerOK). gogobee grows its first GET path in internal/peteclient/client.go — the poll loop the mischief plan already calls for.

Pete serves (gogobee polls, ~3s interval)

GET  /api/games/escrow/pending        -> [{guid, matrix_user, kind: buyin|cashout, amount}]
POST /api/games/escrow/claim          <- {guid}          idempotent, marks claimed

gogobee pushes (existing peteclient queue, guid-idempotent)

POST /api/games/escrow/settled        -> {guid, ok: bool, reason?: "insufficient_funds", balance_after}

Reuse pete_emit_queue (client.go:121-125, INSERT OR IGNORE on guid PK) — it already does durability, backoff and parking. Don't build a second queue.

State machine (Pete side, table game_escrow)

requested -> claimed -> funded     (buyin ok; chips become spendable)
                     -> rejected   (insufficient funds; nothing spendable)
requested -> claimed -> settled    (cashout ok; chips destroyed, euros credited)

Poll interval 3s, not 30s: a player waiting to be dealt is watching a spinner. 3s of "buying chips…" is acceptable; 30s is not.

The reaper

Chips left in an abandoned session are euros in limbo. Auto-cash-out any session idle for 30 minutes. A crashed Pete must reconcile on boot: any claimed escrow with no settled push gets re-polled by GUID.

---

5. Code reuse — copy, don't share

Separate modules, both mine, and the shells diverge (Matrix vs HTTP). Copy the pure cores into pete/internal/games/, let them drift, no shared module.

Verdict per game

Game	Copy	Rewrite	Notes
Hold'em	~2,700 LOC	the shell	The crown jewel. Take it all.
UNO	~1,400 LOC	the turn engine	Great primitives, unshippable engine.
Hangman	~250 LOC	loading/persistence	Clean rune-safe state machine.
Blackjack	~95 LOC	everything else	95 lines is the entire core.
Trivia	~80 LOC	everything else	No question bank exists.

Hold'em — take almost all of it

Already mautrix-free, verified by import check:

• holdem_cfr.go (1,285) — full CFR trainer + NPC policy runtime, info-set packing into a uint64, regret pruning, board-texture/SPR/equity bucketing. Plus the trained data/policy.gob (3.4 MB) and cmd/holdem-train, cmd/holdem-seed. This is the single highest-value asset in either repo.
• holdem_equity.go + holdem_equity_range.go (548) — Monte-Carlo equity, equity-vs-range, draw/out detection. 100% pure, well tested.
• holdem_betting.go (383) — side pots, min-raise, all-in, street completion. The fiddly poker rules you do not want to rewrite. Untested in gogobee — write tests as you port.
• holdem_game.go, holdem_eval.go, holdem_render.go.

Entanglements to break (mechanical):

1. id.UserID → PlayerID string (holdem_betting.go:283,314; holdem_eval.go winnings maps).
2. Delete RoomID/DMRoomID from HoldemGame — table identity belongs to the shell.
3. Hoist the four *time.Timer fields out of HoldemGame (holdem_game.go:92-95).
4. LoadPolicy(path) does os.Open → LoadPolicyFrom(io.Reader), so the policy can be embed.FS'd.

Hand evaluation is not homegrown — holdem_eval.go:12 wraps poker.Evaluate. Just take the github.com/chehsunliu/poker dependency.

UNO — lift the primitives, rewrite the engine

Copy verbatim (already unit-tested in uno_test.go):

• unoCard/unoColor/unoValue, canPlayOn, newUnoDeck, draw/reshuffle (uno.go:21-364)
• The bot AI as free functions: botPickCard, botPickNormal, botPickAggressive, botPickColor (uno.go:1465-1585)
• uno_nomercy.go is ~90% pure: scoring, stacking rules, no-mercy deck, second bot.

Rewrite the turn engine. In gogobee the engine is the message sender — executeMultiTurn, applyAndAnnounce, handlePlayerPlay mutate state and call p.SendReply(...) mid-turn, and their error returns mean "send failed", not "illegal move". There is no ApplyMove(game, move) (Result, error) seam anywhere. Disentangling that costs more than rewriting it against the (good) primitives. One near-seam worth keeping: applyCardEffects (uno_multi.go:1459) already returns a struct instead of sending.

Hangman — take the struct

hangmanGame + guessLetter/guessSolution/displayPhrase + the gallows [7]string ASCII art (hangman.go:26-274). Strip three fields (participants, solvedBy, threadID). Copy hangman_phrases.txt (237 lines) and embed it instead of os.Getenv("HANGMAN_PHRASE_FILE"). Drop the dreamclient translation path for v1.

Blackjack — retype it

handValue (correct soft-ace demotion), isBlackjack, and their tests. That's it — 95 lines. The rest is bjTable keyed by id.RoomID with timers embedded, and raw db.Exec SQL at blackjack.go:867.

Trivia — the question bank does not exist

trivia.go:288 fetches from OpenTDB live, one question per round:

apiURL := "https://opentdb.com/api.php?amount=1"

Reuse the category map (trivia.go:24-53) and calculateScore (time-decay, :536). For the web version, pre-fetch and cache a bank locally — a per-question HTTP call in a web game loop is a latency and rate-limit problem gogobee never had to care about at Matrix pace. Route outbound fetches through Pete's internal/safehttp (SSRF guard).

Trivia has no euro coupling today (points only). Keep it that way in v1 — it's the one game that can ship with zero escrow risk.

Two things that apply to every copied engine

Thread the RNG. Every card game uses the math/rand/v2 package global — blackjack.go:60, uno.go:186,277, holdem_game.go:102, and throughout the CFR/Monte-Carlo code. Nothing is seedable, which is why TestBotPickCard_* can only assert weak properties. The adventure half of gogobee already does this right (dnd_zone_combat.go:361 threads an explicit *rand.Rand via rand.NewPCG). The card games never adopted it. Threading rng *rand.Rand through the deck constructors is mandatory, not optional — ~20 call sites, and it's the difference between a testable engine and one you can only smoke-test. It also gives you a reproducible shuffle for dispute resolution.

Hoist the timers. bjTable.joinTimer/turnTimer/reminderTimers, unoGame.idleTimer/warningTimer, HoldemGame.actionTimer/warningTimer/idleTimer/idleWarningTimer — all live inside the game structs today. Timers are a shell concern. Game state must be a plain value you can serialize, which is also what makes restart-mid-hand survivable.

Build a cards package while you're at it

There is no shared cards package in gogobee — blackjack has its own deck (blackjack.go:32-75), UNO has its own (uno.go:130-189), hold'em uses the third-party lib. Consolidate into pete/internal/games/cards during the port rather than importing the duplication.

---

6. Architecture in Pete

internal/games/
  cards/        shared deck primitives (new; consolidates gogobee's duplicates)
  blackjack/    pure engine  — ApplyMove(state, move) (state, events, error)
  holdem/       pure engine  + cfr/ (copied) + policy.gob (embedded)
  uno/          pure engine  (rewritten) over copied primitives + bots
  hangman/      pure engine  (copied) + phrases.txt (embedded)
  trivia/       pure engine  (new) + cached question bank
  escrow/       chip ledger, the gogobee poll/push seam
  table/        session, seating, turn clocks, reconnect — the shell

Server-authoritative, always. The browser sends intents and never sees the deck. Any game with money attached cannot trust a client-reported result. This is why the engines have to be Go on Pete's side rather than ported to JS.

Every engine is a pure reducer: ApplyMove(state, move) (newState, []Event, error). Timers, sockets and persistence all live in table/. That's the seam gogobee never had, and it's what buys testability, replay, and surviving a redeploy.

Transport

• Blackjack, Hangman, Trivia, UNO-solo — request/response over fetch. No sockets.
• Hold'em, UNO-multi — WebSocket. Lobby, seating, presence, turn clocks, reconnect-mid-hand, spectators. This is the bulk of the total effort, and it is the only genuinely new infrastructure in the project.

Frontend

Pete has no SPA and no bundler today — server-rendered html/template + embed.FS, plain <script defer> tags, npm present only to run the Tailwind CLI. games.parodia.dev is the first real client-side app in the repo.

Precedent says this is survivable: weather-gl.js is 1,028 lines of hand-written WebGL2 with no build step. Do the same here — vanilla JS per game, no framework, no bundler, Tailwind for layout. Revisit only if it actually hurts.

Auth

Session cookie is host-only today — auth.go:151 sets Path but no Domain, so a news.parodia.dev session will not travel to games.parodia.dev. Set Domain: ".parodia.dev". Note this widens the cookie to every parodia.dev host including the landing site — a deliberate loosening, fine here, but not a freebie. Add the games.parodia.dev redirect URI to the pete app in Authentik.

Games require login. No anonymous play — there's money in it.

---

7. Ship order

Phase 0 — euro idempotency (gogobee). external_id column + unique index + CreditIdem/DebitIdem. Blocking; nothing else is safe without it.

Phase 1 — escrow + Blackjack. The full money loop against the simplest possible game (95 lines of logic). Buy in, play, cash out. This proves cross-subdomain auth, the identity mapping, the poll loop, the escrow state machine, the reaper, and the frontend shape — all against a game where the game cannot be what's broken.

Phase 2 — Trivia + Hangman. No escrow (trivia has no euro coupling; keep hangman's collaborative credit out of v1). Pure frontend and content work. Cheap wins, and they make the site feel like a place rather than a demo.

Phase 3 — UNO. Solo first (single-player vs bot, no sockets). Then multi, which is where the WebSocket infrastructure gets built. Forgiving latency, simple turn model — the right place to learn multiplayer.

Phase 4 — Hold'em. Last. It's the hardest engine (side pots, all-ins, split pots), the biggest port, and the one where collusion is a real threat rather than a theoretical one. Do it when the multiplayer plumbing has already survived contact with real players.

---

8. Risks

Economy inflation. A web casino runs orders of magnitude more hands per hour than Matrix-paced games ever did. Whatever the house edge is, it now compounds far faster in both directions. Before Phase 1 ships, decide: session buy-in caps, a daily net-win/loss ceiling, or a rake. This is the risk most likely to be discovered too late.

Restart mid-hand. Game state is in memory, so a Pete redeploy kills live tables — the same property gogobee has today, and it redeploys far less often than Pete does. Mitigate with serializable state (which the pure-reducer design gives for free) plus a drain-before-restart, not a second process.

Collusion in hold'em. Two browsers, one person, one table. Not solvable in v1; at minimum log seat/IP/session overlap so it's detectable after the fact.

The gogobee contract is cross-repo. roster_test.go already guards it: an unknown event_type is a 400 that makes gogobee's sender park the row. Add the same guard on the new escrow endpoints, and keep the payload structs in step across both repos by hand — that's the cost of copying instead of sharing, and it's the right trade here.

---

9. Open questions

• Chips 1:1 with euros, or a separate denomination? 1:1 is simpler and honest. A separate denomination gives you a knob for the inflation problem.
• Do web results feed the Matrix room? Pete already has a priority poster (adventure.go:151). "Reala just took a 12k pot" is a good bulletin, and this is nearly free.
• NPC opponents at the web tables? The CFR bot is right there and it's good. It also means a table never sits empty, which matters a lot for a small community.