ADR 0003: Per-viewer views and JSON Patch sync
| Status | Accepted, 2026-11-14 |
| Related | RFC 0001 sections 4 (invariants), 5.2, 6, 7, 13; audit findings 3, 4, 12 |
Context
Section titled “Context”0.x syncs by broadcasting the full table state whenever a key from a hard-coded list
changes (findings 3, 12). Keys outside the list never sync. Hidden information is only
card isVisible; all player attributes reach everyone (finding 4). A poker game cannot
keep a hole card or a balance private.
RFC 0001 makes two invariants: clients receive only view() output, and applying a
viewer's patches in revision order reproduces the server's view exactly.
Decision
Section titled “Decision”Views are the only thing sent. After every commit, the engine computes the view for each distinct viewer at the table and sends that viewer a diff against the view it last sent. Raw state never leaves the server, not even to the seat that "owns" it.
type Viewer = | { kind: 'seat'; seat: number; seats: readonly number[]; playerId: string } // seat = first held seat | { kind: 'spectator'; seat: null; seats: readonly []; playerId: null }; // no player id, by design
interface TablePatch { t: 'table.patch'; table: string; from: number; rev: number; ops: JsonPatchOp[];}interface TableSnapshot { t: 'table.snapshot'; table: string; rev: number; doc: TableDocument; // { view, meta, seats, spectators, you }: see the protocol spec}- Viewer keys. Each seated player is one viewer (keyed by player id, so a player
holding several seats gets one view that knows all of them). All spectators share one
viewer (
spectator), soview()runs once for all of them, and they all receive the same serialized patch bytes. Spectators deliberately get noplayerId, which guarantees the sharing. A player who is seated sees the seat view, never the spectator one. Ifviewis omitted, every viewer shares one key and sees the state. - Revisions. Each table has one
rev, an integer that starts at 0 on creation and increases by 1 on every commit. It never resets, including across restarts (it is in the snapshot, ADR 0009). - Patches.
opsis RFC 6902 JSON Patch using onlyadd,removeandreplace. The diff is structural: objects by key, arrays by index (nomovedetection), with a===short-circuit so subtrees shared through Mutative's structural sharing cost nothing. A viewer whose view did not change gets no message for that commit. fromfield. Because unchanged viewers are skipped,table.patchcarriesfrom(the rev of the last document sent to this viewer, which the patch applies on top of) as well asrev. The protocol spec records it. The client applies a patch only if its current rev equalsfrom.- Snapshots. The server sends
table.snapshotontable.join, after a client reports a gap, and when it skipped patches for a slow connection. A client that seesfromnot equal to its rev resyncs by sendingtable.sync, which answers with a fresh snapshot. (table.joinis also idempotent, buttable.syncmakes the intent explicit in logs and devtools and never changes the viewer's role.) - Backpressure. If a connection's send buffer passes 1 MiB, the server stops sending it patches and marks it stale. When the buffer drains, it gets one snapshot. Other viewers are unaffected.
- Ordering per commit: patches for the commit, then that commit's
table.eventmessages, then theackfor the action that caused it. A client that receives its ack can rely on its view already reflecting the action. act.rev(optional) lets a client say "only if the table is still at rev N". If the table rev differs, the action rejects withSTALE_REVISIONwithout running.- JSON only. Views must be JSON values: no
undefinedin arrays, noMap,Set,Date, class instances, functions or non-finite numbers. In dev the engine checks every view and throws a descriptive error naming the path. In production the check is skipped. - Leak checks. Games may mark fields with the
secrethelper. In dev the engine warns when all viewer views are identical although secrets are declared (RFC 0001 section 5.2), andshoehive/testingships a property test helper asserting no secret value appears in any other seat's or the spectator view.
Multiple connections for one player (tabs) share the viewer for that seat. Each
connection tracks its own last acknowledged rev, so a lagging tab resyncs alone.
Lobby sync (lobby.snapshot / lobby.patch) uses the same diff and from / rev
scheme with one lobby-wide rev.
Status in v1 (Phase 7 review)
Section titled “Status in v1 (Phase 7 review)”Rule 10's secret helper, the dev warning and the leak-assertion helper were not built.
v1 covers the same ground with shoehive/cards view helpers (seatView, faceDown,
revealTo, hideCard) and with a per-game leak invariant in the property tests (see the
blackjack check in packages/shoehive/test/properties/invariants.test.ts, and the
Hold'em random-play test). A player may hold more than one seat (seats.perPlayer,
default 1); views then show all of that player's seats.
Consequences
Section titled “Consequences”Positive
Section titled “Positive”- Hidden information is a pure function the author can unit test, not a filter list.
- Bandwidth is proportional to what changed for that viewer.
- Spectator count costs one
view()call and one serialization per commit, not one per spectator. - Patch apply is about 50 lines in the client and can be property-tested against a full view (RFC 0001 section 10 test pyramid).
Negative
Section titled “Negative”- CPU per commit grows with seats: one
view()and one diff per seat. Twelve seats is our largest example; the Phase 1 benchmark (RFC 0001 section 13) checks it against the RFC 0001 section 12 Phase 8 target of p95 action-to-patch under 20 ms. - Index-based array diffs are verbose when a game removes from the front of a long array. Authors can key such data by id. We accept this over move detection's cost and ambiguity.
- The server holds the last sent view per viewer per table in memory.
Alternatives considered
Section titled “Alternatives considered”Full-state broadcast (0.x)
Section titled “Full-state broadcast (0.x)”Simple, but it sends raw state (leaks secrets by construction) and costs bandwidth proportional to state size times connections. Rejected; it caused findings 3, 4 and 12.
Colyseus schema binary deltas
Section titled “Colyseus schema binary deltas”Very compact, but it requires decorated schema classes or codegen, couples the wire format to the state shape, and hides fields with per-field filters instead of a view function. JSON Patch is debuggable in the browser and in devtools. A MessagePack codec can shrink JSON later (RFC 0001 section 13 roadmap) without changing this model.
Immer or Mutative patches of raw state
Section titled “Immer or Mutative patches of raw state”The drafting library can emit patches for free. Rejected because those patches
describe raw state: a patch saying hands/1/0 changed leaks that seat 1 drew a card and
its value. Patches must describe each viewer's view, so we diff views, not state.
Send full views every commit, per viewer
Section titled “Send full views every commit, per viewer”No leaks, but still bandwidth heavy and no cheaper to compute than a diff once views are cached. Rejected.
