Actions, drafts and atomicity
An Action is the only way a table's state changes from outside. Shoehive treats each one as a transaction: it applies completely or it does not apply at all. This page explains how, and what that buys you. The full design is in ADR 0005 and the validation order in ADR 0004.
From socket to state
Section titled “From socket to state”An act message passes a series of gates. Only the last one runs your code.
message ─► size cap ─► rate limit ─► envelope check ─► action lookup ─► input schema │ (all of this runs outside the queue, so floods of bad input cannot block a table) ▼ serial queue for the table ─► draft ─► run() ─► commit or roll back- Limits and shape. Oversized messages, rate-limit overflow and malformed envelopes are refused first. See the security model.
- Lookup. The action must exist in the current phase (or at the top level). Otherwise:
ACTION_NOT_ALLOWED. - Validation. The
inputis checked against the action's Standard Schema (zod, valibot, arktype or anything that implements it). Failure isINVALID_INPUTwith the schema's issues. Yourrunreceives the validator's output, so defaults and transforms work, and it is typed from the schema. Noinputschema means the action takes no input. - The queue. Valid requests join the table's serial queue. The phase is checked again there, because it may have changed while the request waited.
The queue: one thing at a time
Section titled “The queue: one thing at a time”Each table has one serial queue. Actions, lifecycle hooks (onSit, onStand and the rest) and
timer firings all go through it, one entry at a time, in arrival order. There are no locks and
no races inside game code: when your run starts, nothing else is touching this table's state.
"Simultaneous" play in a round still means submissions arrive
one after another.
An async action holds the queue until it finishes. Only await things on ctx (such as the
wallet). Awaiting anything else breaks determinism.
Other tables are never affected.
The draft
Section titled “The draft”Each entry runs against a draft of the committed state, made with Mutative. You change it like a normal object. Shoehive keeps the real state untouched until your code finishes.
export const shop = defineGame({ id: 'shop', seats: { min: 1, max: 1 }, setup: () => ({ coins: 3, items: [] as string[] }), actions: { buy: { input: z.object({ item: z.string(), price: z.number().int().min(1) }), run({ state, input }) { state.items.push(input.item); // 1. a draft: mutate freely state.coins -= input.price; // 2. if (state.coins < 0) reject('NOT_ENOUGH_COINS'); // 3. everything above is undone }, }, },});Line 3 undoes lines 1 and 2. The proof:
export async function demo() { const table = await createTestTable(shop, { players: 1 });
await table.act(0, 'buy', { item: 'apple', price: 1 }); // commits: 2 coins left await table.act(0, 'buy', { item: 'castle', price: 99 }).catch(() => undefined); // rejected
// The castle never reached the state, and the revision did not move for it. return { coins: table.state.coins, items: table.state.items };}demo() returns 2 coins and ['apple']: the failed purchase left no trace, and it did not
move the revision.
Commit or roll back
Section titled “Commit or roll back”- Commit:
runreturns normally. The draft becomes the new, immutable state, the revision goes up by one, and the entry is appended to the log. - Roll back:
runcallsreject(code, details?)or throws. The draft is thrown away. The client getsack { ok: false }with your code (reject) orINTERNAL(any other error; the cause is logged, and the client message is generic in production). Nothing was applied, nothing was added to the log, and no patches go out.
Rollback covers more than your state. Everything the entry did through ctx is part of the
same transaction: phase changes, turn moves, timers you scheduled, random numbers you drew, and
events you emitted. ctx.phase.go('showdown') in an action that later rejects never happens.
Wallet commit, release and credit calls wait until the entry has committed and been
stored.
Follow-ups in the same entry
Section titled “Follow-ups in the same entry”Hooks triggered by an action run inside its transaction, on the same draft: the action body,
then onExit of the old phase, then onEnter of the new one, or onEnd after ctx.end(). If
any of them throws, the whole entry rolls back, including the action that started it.
Work the engine decides to do next becomes a new entry, queued after the current one: the
automatic start when enough seats fill, and closing a round when the last submission arrives.
So the last answer in a round commits and reaches clients first, and a bug in onClose rolls
back only the close.
Frozen committed state
Section titled “Frozen committed state”Committed state is plain data that is never mutated. In development it is frozen, so touching
it from view(), from a test, or through a draft you kept after run returned throws a
TypeError right where the mistake is. In production freezing is off for speed, so test with
the checks on (shoehive/testing always does).
State must be JSON: objects, arrays, strings, finite numbers, booleans and null. No Map,
Set, Date, class instances or undefined in arrays. In dev Shoehive checks the state after
every commit and names the offending path.
Acknowledgement
Section titled “Acknowledgement”The ack for an action is sent after its log entry is durably stored and after the patches for
that commit. An ok: true ack means the change is saved and the client's view already
includes it. See Views and sync.
Related: testing games, error codes.
