Game surface contract (version 1)

The Game surface is a strategy laboratory owned by the native runtime. Its UI configures runs and submits proposed actions; neither React nor Node evaluates game rules. Existing declarative game blocks and typed game values retain their existing meanings.

Implementation status is tracked in the implementation ledger. This contract describes the registered implementation; product publication and packaged-product QA are separate operations.

Match identity and authority

A run retains its definition, seat strategies, seed, limits, source identity, initial state, accepted decisions with player observations, transition states and private strategy memories. Native built-in kernels implement matrix games, chess, Kuhn poker and heads-up no-limit hold’em. Custom bindings compile to an isolated, bounded compiled formula dependency closure. The closure and its compiled identity are retained with the match. Later model edits do not replace that program.

Every mutation has an attemptKey. Existing-match mutations also have id and revision. The owner reconciles the attempt before computing a transition outside shared locks; the durable transaction repeats reconciliation before committing. Reusing an attempt with different input fails. An obsolete revision cannot advance a match. A receipt and its successor state commit atomically in model.db; uncertain commits require reconciliation of the original request.

A running snapshot also exposes runRevision, the revision that admitted its current worker. Pause and Stop may carry that generation along with the displayed revision. The transaction accepts intervening decisions from that same worker, preserves their history, and rejects a later Resume generation. Act, Step, Resume and Fork always require an exact current revision. Duplicate control attempts return their original receipt, including after another run.

The selected tables are _grid_owner_games_matches and _grid_owner_games_commands, _grid_owner_games_tournaments, and the selected _grid_owner_games_processes intent/evidence table. Access is principal-scoped. Table creation happens on selected mutation, never ordinary model admission. Inspect does not create an absent database. Native documents use their authenticated physical document owner and existing table manager; they cannot fall back to a hosted model ID.

Explicit Run selects the existing bounded model executor. Paused, stopped or superseded revisions reject an older worker's publication. Runs without a live owner after host restart are inspected as interrupted and paused; continuing is explicit. Surface opening only inspects retained records.

Playable rules and decisions

The versioned contract has initialization, phase actors, observations, legal actions, transitions, rewards and terminal reasons. An action is a stable ID plus an optional bounded integer amount. Rules validate proposals in the owner. Simultaneous games retain individual submissions privately until all required actors have submitted. Each opponent receives its permitted pre-round observation. An explicit chance phase has no player actors and a bounded distribution of distinct actions with positive finite weights. The owner samples that distribution and retains the outcome. Replay consumes the retained action without sampling again.

Grid strategy bindings receive observation, legal actions, private memory and limits. They never receive the match seed, retained deck, another player's pending decision or the authoritative private state. Their output has action, memory and an optional explanation. Invalid output and exhausted budgets produce a recorded stop or truncation, never a replacement random move.

The selected Grid adapter admits only its named dependency closure. Unadmitted inputs, scheduled/stateful assignments, external references and effectful calls are refused. Its bounded pure-expression vocabulary follows the existing native pure-check admission mechanism. The formula evaluator remains compiled formula. Unique text-keyed compiled formula record rows are projected to JSON records. Grid row vectors at legal-action, actor and reward boundaries are marshalled to the contract's lists; arbitrary state and observation arrays keep their native shape. Integer action fields accept exactly representable integral values.

Process opponents must use the existing Process admission, PublishedReads, retained argument recipes, shared capacity and accounting. Public Start never accepts caller-overridden arguments. Durable pending intents precede dispatch; late results must reconcile the original attempt and revision before becoming accepted actions. Provider replay is prohibited. The selected adapter admits four arguments (observation, legal actions, memory, limits), profile responders and no tools, external agents, human responders or population effects. Limits include 1–64 calls per decision, 1,000–60,000 ms per decision and at most 10,000 reserved calls per seat per match. Reservations never refund an unknown call. Each decision bounds its native Process trace to 512 KiB, context to 128 KiB, raw response to 128 KiB and contribution to 64 KiB. The serialized parent evidence has a 1 MiB ceiling and shares the match's overall retention budget. Saved connection selections and credential-free identities are frozen; live credentials come from the configured Process ingress. Receipt reconciliation precedes connection lookup. An existing intent never authorizes another Start.

Terminal Process evidence is durably retained before its shared service slot is retired. Unknown Start outcomes pause for reconciliation. A suspended original Process must be reconciled through Process before Game can continue; Game does not silently create a new experiment. Stop/cancellation fences accepted actions, even when the original provider later produces an answer. The combined match and Process evidence must fit the match retention limit. Player views expose only their own Process evidence; replay excludes evidence after its checkpoint.

Game semantics

• Matrix games accept a complete finite payoff table and bounded round count. Payoffs accumulate over completed rounds only. Starters include Prisoner’s Dilemma and rock-paper-scissors.
• Chess uses canonical native move semantics, including promotions, castling and en passant. The laboratory adjudicates threefold repetition, the fifty-move condition and supported insufficient-material positions. Decision limits are truncations. Alpha-beta results are heuristic; a partial search cannot claim a completed depth or certified result.
• Kuhn uses two players, one-chip antes, three distinct cards, a single betting round and one-chip bets. Check/check and called bets show down; folds do not reveal the folded private card. The independent rules reference is OpenSpiel’s Kuhn implementation.
• Hold’em uses integer chips, blinds, four streets, full-raise thresholds, short all-ins, unmatched-chip returns and exact native five-of-seven ranking. Tied pots split evenly in heads-up matched contributions. Player observations exclude the undealt deck and unrevealed opposing cards. Equity estimates sample only from cards absent from the player's observation. See the published hold’em rules.

Replay and experiments

Replay evaluates only recorded decisions with the frozen rules. It makes no provider calls. Public action history remains visible from either seat; private explanations and Process references remain scoped to their owner or the researcher. The researcher can inspect full state.

Branch creates a new identity at an accepted checkpoint. It retains the prefix and policy memory but does not rewrite the original or carry a live provider session. Re-running an opponent is a new experiment.

Tournament schedules are bounded round-robin comparisons, with paired seeds and swapped competitors. Hold’em fixtures reset stacks for every independent hand. Completed, incomplete and failed results must remain separate. Uncertainty must account for paired observations, and unknown provider costs must remain unknown. Tournament matches are controlled by their comparison owner; a researcher branches a new independent match to experiment with a tournament position. Process recovery pauses the comparison while retaining its current fixture. Normal fixture completion advances sequentially on the selected host executor. A 60-second execution burst pauses with an explicit budget reason; continuing requires an explicit operation.

Presentation and extensions

GameSurfaceSpec version 1 binds the game, competitors, analysis symbols, seed and limits. useGame supplies the selected snapshot, legal actions, action submission and replay selection to an admitted React renderer. Existing JSX trust policy continues to apply. A renderer has no transition authority.

All new views require isolated before/after evidence and named-view approval. Their prior Game presentation is explicitly absent. Existing navigation stays active until its separate proposal is approved. No approval is inferred from successful tests, time or an unanswered review.