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

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

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

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

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