Decisions

Architectural Decision Records (ADRs) for the Numero platform. Listed roughly newest-first within thematic groups.

Hosted agents & inference

• Rake & Fees — house-as-player ledger, program-verified collections — the fee split is exact on both chains; Solana collections are receipt-verified + once-only on-chain; the conservation sweep keeps the pipeline live (2026-07-03)
• Bulletproof Hosted Agents — end-to-end rebuild of the agent path; restart-safe persistence; skill-based core/skills separation; audit ledger durability
• LiteLLM Integration — stateless gateway, per-agent model selection, two-axis cost+charge pricing, auto-fold safe-action path

Game lifecycle & state

• Table Kind × Mode Matrix — kind (open | human_only | agent | copilot) as the single audience axis through one assertSeatAllowed gate
• Player-Funds Lifecycle Audit — single transitionTableState() writer, participant end-of-life at settle, idle reaper, restart matrix
• SnG Tournaments — mode flag on poker, TournamentOrchestrator, two-axis chip semantics, multi-position settlement
• Sit=Deposit, Stand=Withdraw — atomic sit-with-permit, atomic stand-with-withdrawal, no floating table balance
• Room State Persistence — DB-backed participant state, table lifecycle, checkpoint recovery
• Table Lifecycle Unification — rooms → tables, single authoritative POST /api/tables, compat views during soak
• Chain of Custody — zero-decimal CTN, pooled tables, game-agnostic settlement
• Chain of Custody 4 — zero wallet awareness in game-server; admin-server is the only chain-talker

Funds, custody & betting

• Custody Layer — CustodyFacet holds per-user FREE/DISPUTED claims; escape/idle_kick hand the pool to custody as an internal ledger move; FREE claim is the verbatim cash-out

Engine & game logic

• Arena Generalization — GameEngine interface validated by two game types
• Game-Admin Alignment — game-server manages chips, admin-server manages money
• Rake Reconciliation — house as participant, lazy chain, claim-first DB write
• Poker OHH Integration — handHash = keccak256(canonical OHH JSON); chain anchor binds to gameplay

Discipline & infrastructure

• Infra Liveness Gate — .internal everywhere with mandatory always-on + alert coverage; an alert rule is live only when it has FIRED and ARRIVED (routing-aware parity, drills); HAS litellm heartbeat (2026-09-08)

• Bulletproof Persistence — turnstore hot tier (inter-turn state) + Postgres cold tier (post-boundary), versioned refuse-on-skew, cross-process reserve handshake

• Bulletproof State — events as truth, intent-outcome for crash recovery, Ponder as amplifier not bike

• Bulletproof State Machine (UI) — UI as conformant consumer of server intent state machines

• Bulletproof Pre-game UI — Tier 1/2/4 test discipline; useGameDispatcher as single instrumentation point

• Poker UI Foundation Rewrite — framework/shared/poker-leaf tree-shape with strict import directionality

• Bulletproof Observability — telemetry contracts per service, mock-exporter pattern, hand envelopes, observatory dashboard