docs/adr/0006-command-wire-protocol.md

ADR-0006: Id-based, server-stamped, tick-scheduled command protocol

Status: Accepted Date: 2026-08-30 Serves: PRD FR-8, FR-10, FR-19, NFR-8 Evidence: docs/analysis/02-command-wire-protocol.md

Context

ADR-0003 makes the server authoritative, so player intent must cross a wire as data. Today it does not: engine/commands.js takes live object references — issueMove(units, x, y, …) is handed unit objects, not ids. Object references do not serialize.

The audit also corrected a scope assumption this port was carrying. engine/commands.js is the whole unit-order surface, but not the whole intent surface: hudSelection.js:20-35 imports and calls roughly 20 further cost-bearing engine mutators directly — production queueing, research, market trades, diplomacy, colony and galaxy actions. Those are where resources are actually spent, so the protocol must cover them too. A protocol built only around issue* would have shipped with the economy wide open.

The anti-cheat surface is concrete. Without server-side ownership checks a modified client can command another player's army, spend another player's resources, and recycle their buildings — issueRecycle in particular performs no ownership check at all, despite a comment in engine/recycle.js:87-89 claiming it does.

Options considered

A. Change engine/commands.js to take ids

Pros. One representation everywhere; no adapter. Cons. Touches ~22 exported functions and every call site across the client, the AI and the inherited tests — a very large diff through the most heavily tested code in the repo, against 2,519 tests and a determinism guard, for no behavioural gain. It also maximizes divergence from upstream, directly raising the cost of every future merge (ADR-0002).

B. Keep object signatures; wrap with a codec that resolves ids server-side

Pros. The engine is untouched, so the inherited suite keeps testing exactly what it tested before, and the upstream diff stays small. All the new, risky logic — resolution, ownership, validation, rate limits — lands in one new module that can be tested adversarially in isolation. Cons. Two representations coexist (wire ids, engine objects), and the boundary between them must be the only way in, or validation can be bypassed.

Decision

Option B: wrap, do not rewrite.

net/commandCodec.js owns encode/decode/validate/apply and is the sole path from wire to engine. Its rules:

1. Id-based envelope, versioned. Entities travel as id strings, resolved server-side.
2. The server stamps the owner. Always. A client's claimed ownerId is advisory telemetry and is never trusted; the seat is determined by the authenticated connection. This single rule closes the command-another-player's-army and spend-another-player's-resources classes at once.
3. Order of a selection is significant and must never be sorted. ids[0] is the formation leader (engine/commands.js:145, :195) and issueEscort derives ring slots from array index (:363). Canonicalizing the array — the obvious thing to do when de-duplicating input — would silently change formations.
4. Deterministic application order: (applyTick, ownerIndex, clientSeq), where ownerIndex = state.owners.indexOf(owner). Commands apply immediately before tick(state, dt), never inside it.
5. state.selection is UI-only and moves to the client session. The field remains on State as a permanently-empty array — removeEntity writes it (engine/state.js:347) — guarded by a test asserting no server module reads it.
6. The economy surface is in scope, not just issue*.

Exactly one engine signature changes: issueSetRally(building, …) → issueSetRally(state, buildingId, …), 3 call sites. It is the one command whose only handle on its target is an object reference with no id-based route, so wrapping it would mean inventing a lookup the engine already owns.

Consequences

Gains. The engine keeps its shape, so the inherited suite keeps its meaning and upstream merges stay cheap. Every new security-relevant decision lives in one file with one entry point. A match becomes replayable from {engineCommit, createGameStateOpts, dt, aiSeatConfigs, orderedCommandLog} (FR-19).

Costs. The codec is a chokepoint that must not be bypassed — any future code calling issue* directly on the server re-opens everything the codec closes. This needs a guard test in the style of test/engine-purity.test.js, which the repo already uses for exactly this kind of invariant.

Follow-on work. Fix the defects this audit surfaced before the codec ships — in particular issueRecycle's missing ownership check, the false comment documenting it, and friendly-fire on explicit attack orders (engine/combat.js:46). Fix the formation gate (see ADR-0008). Write the adversarial codec test suite: cross-seat commands, unaffordable commands, unknown ids, malformed envelopes, flooding.

Revisit if. The two-representation boundary proves leaky in practice — at which point option A becomes worth its cost, as a deliberate migration rather than a drift.