ADR 0004: Standard Schema validation for inputs and options
| Status | Accepted, 2026-11-14 |
| Related | RFC 0001 sections 5.1, 6, 7 (Dependencies); audit findings 10, 11; ADRs 0001, 0006 |
Context
Section titled “Context”0.x has no input validation: seatIndex as number is trusted straight off the socket
(finding 11), and inputs have no schemas (finding 10). Game authors already have a
favourite validator (zod, valibot, arktype), and forcing one on them would add a
dependency and a learning cost. The Standard Schema spec (~standard property, with
validate() and type-level InferInput / InferOutput) is implemented by all three,
so we can accept any of them without depending on any.
Decision
Section titled “Decision”-
Where schemas appear.
ActionDef.inputvalidates action input.defineGame'soptionsvalidates table options attable.createandshoehive.tables.create. Both accept any value with a valid~standardproperty, version 1. -
Zero dependencies. We copy the Standard Schema v1 type definitions into
src/core/standard-schema.ts, as the spec explicitly allows.@standard-schema/specis not a dependency. No validator is a dependency, dev dependency of the published package, or peer. -
Validation runs before game code, in this order for an
actmessage:- Message size cap and per-connection rate limit (RFC 0001 section 6).
- Protocol schema check of the envelope (
t,id,table,name,input). - Action lookup by name in the current phase (ADR 0001). Unknown or not in this phase:
ACTION_NOT_ALLOWED. inputschemavalidate(). Failure:INVALID_INPUTwith the Standard Schemaissues.- Enqueue. Inside the queue: phase recheck,
onceand turn rules, thenrun.
Steps 1 to 4 run outside the table's serial queue, so a flood of bad input cannot block a table. Step 3 runs again inside the queue because the phase may have changed.
-
Output is what runs.
runreceives the validator's output value, so transforms and defaults work (z.coerce, valibottransform). The log records the output, not the raw input (ADR 0006). Replay and recovery never re-run validators, so upgrading a validator cannot change a replay. -
Async schemas.
validate()may return a Promise. The engine awaits it with a 1 second limit; exceeding it isBAD_REQUESTwithdetails.reason: 'timeout'. Docs recommend synchronous schemas. -
No
inputmeans the action takes no input. A message whoseinputis anything other than absent ornullisINVALID_INPUT. -
Error shape. Validation failures map to the closed enum code
INVALID_INPUTwith issues normalised from the spec:
interface ValidationErrorDetails { issues: Array<{ path: Array<string | number>; message: string }>;}// ack: { ok: false, error: { code: 'INVALID_INPUT', message: 'Invalid input for "place"', details } }Path segments that are objects in the spec ({ key }) are flattened to their key.
At most 20 issues are sent.
- Types. The client's
act(name, input)usesInferInputof the schema.runusesInferOutput. Type tests (expectTypeOf) cover zod and valibot. - No client-side validation in v1. The client imports game definitions as types only (ADR 0002), so it has no schema objects at runtime. The server is the authority. An app that wants instant form feedback can import its schema separately.
- Internal actions (
internal: true, called by timers) are validated too when they declareinput, and their schemas must be synchronous. A timer scheduled with invalid input throws atctx.timers.aftertime, inside the scheduling entry, so the bug rolls back where it was introduced.
Consequences
Section titled “Consequences”Positive
Section titled “Positive”- Authors keep their validator. Switching from zod to valibot changes imports only.
- Bad input never reaches
run, which is where 0.x crashed or misbehaved. - Recorded outputs make replay independent of validator versions.
- Structured issues give clients usable error messages.
Negative
Section titled “Negative”- We maintain a copy of the spec's types. It is small and versioned (v1); a v2 would need a new ADR.
- Validator error message quality varies by library, and we pass it through.
- Validation outside the queue means validators must be pure. A validator that reads table state is not supported (and could not get it anyway).
Alternatives considered
Section titled “Alternatives considered”Bundle zod as the one validator
Section titled “Bundle zod as the one validator”Simplest docs. Rejected: it forces a dependency and a bundle size cost on everyone (RFC 0001 section 7 keeps core free of dependencies besides Mutative) and excludes valibot users who chose it for size.
Our own mini schema DSL
Section titled “Our own mini schema DSL”Full control and zero deps. Rejected: every author would learn yet another validator, and we would own a validator's bug surface forever.
JSON Schema
Section titled “JSON Schema”Language-neutral and serializable. Rejected for v1: TypeScript inference from JSON
Schema is weak without codegen or heavy type gymnastics, contradicting "types inferred
from defineGame, no codegen". Standard Schema libraries that emit JSON Schema remain
usable for docs generation.
Validate inside the queue only
Section titled “Validate inside the queue only”One code path. Rejected because invalid floods would hold the table queue.
