Capsule: wire protocol

Use when adding, removing, or changing any field on a client↔server message, snapshot, or event.

Read first

server/crates/protocol/src/lib.rs — authoritative Rust wire DTOs and compact transport
server/crates/contract/src/lib.rs — shared semantic DTOs re-exported by protocol, including start/snapshot contract records and DEFAULT_FACTION_ID
server/src/protocol.rs — server-shell adapter for typed kind conversion and legacy imports
server/crates/sim/src/protocol.rs — sim-facing adapter for typed kind conversion
client/src/protocol.js — mirror; must agree on every tag, field name, and shape
server/src/lobby/mod.rs + client/src/config.js — PLAYER_PALETTE cross-surface mirror, guarded by node tests/protocol_parity.mjs

selectMap { map } is the host-only map selector command.
lobby carries map (selected stable map name) and maps[] ({name, description} catalog rows). Replay start metadata separately uses mapName.
Lab start payloads carry lab metadata with the public lab id, operator id, role, full-world vision mode, dirty flag, and operation count.
Start payloads carry recipient-scoped capabilities metadata for shared room-time, replay-vision, and gameplay-command affordances. The client parser must not infer these from replay/dev/lab mode names.
Start payloads carry recipient-scoped diagnostics metadata when projection policy enables movement-path overlays or observer analysis. Do not infer those affordances from room mode names.
LobbyPlayer carries teamId, factionId, aiProfileId?, and isSpectator; spectators are lobby members but not active match players.

Mirror. Every protocol change touches both files and docs/design/protocol.md in the same commit.
Parity. Run node tests/protocol_parity.mjs after protocol vocabulary, compact code/slot, prediction metadata, start/snapshot/replay DTO, default faction id, or lobby palette changes.
Fog is authoritative. Anything sent per-player (entity views, target_id tracers, death/ positional events) must be gated on visibility/ownership. Never send a player an entity or position they can’t see. See docs/design/protocol.md §2.4 and docs/design/hardening.md.
Clients are untrusted. Validate and bound everything inbound: dedupe + cap unit lists (MAX_UNITS_PER_COMMAND), size-limit frames, range/overflow-check placement coords. See deployment.md and docs/design/hardening.md.
rts-protocol depends only on rts-contract among workspace crates. Kind conversion that needs rules/sim vocabulary belongs in adapter modules.