docs/analysis/02-command-wire-protocol.md

# 02 — Command & Wire Protocol

**Status:** analysis complete, decisive. Primary input to `docs/adr/` (proposed
ADR-0002 *"Wire commands are id-based; `engine/commands.js` is wrapped, not
rewritten"*).

**Sources read:** `/home/user/alma92350/spaceexploration-rts` (read-only clone).
All `file.js:line` citations below refer to that tree unless prefixed with
`SpaceCities/`.

---

## 0. Decisions up front

| # | Decision | Where it lands |
|---|---|---|
| **D1** | **Wrap, do not rewrite.** `engine/commands.js` keeps its object-ref signatures. A new `net/commandCodec.js` owns id→object resolution, ownership, fog and rate limits. | §4 |
| **D2** | Exactly **one** signature change to the engine: `issueSetRally(building, …)` → `issueSetRally(state, buildingId, …)`. 3 call sites. Everything else is untouched. | §4.4 |
| **D3** | The wire envelope is **versioned, id-based, owner-stamped by the server (never by the client), and tick-scheduled**. The client's `ownerId` and `tick` fields are advisory/telemetry only. | §3.1 |
| **D4** | **Selection id arrays are ORDER-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 (`engine/commands.js:363`). | §3.3 |
| **D5** | Application order is `(applyTick, ownerIndex, clientSeq)` — `ownerIndex = state.owners.indexOf(owner)`, `engine/state.js:227`. Commands apply **immediately before `tick(state, dt)`**, never inside it. | §5 |
| **D6** | `state.selection` is UI-only. It moves to the client session. The field stays on `State` as a permanently-empty array (zero churn — `removeEntity` writes it, `engine/state.js:347`), guarded by a test that no server module *reads* it. | §6 |
| **D7** | A match is replayable from `{engineCommit, createGameStateOpts, dt, aiSeatConfigs, orderedCommandLog}` — **provided B1 below is fixed**. | §7 |
| **D8** | **Five engine defects block multiplayer** and must be fixed before the codec ships. The worst is a module-global entity-id counter that makes two concurrent matches in one Node process non-replayable. | §8 |

**Scope correction (important).** The brief states `engine/commands.js` is the
entire player-intent surface. It is the entire *unit-order* surface. It is **not**
the entire player-intent surface: `hudSelection.js:20-35` imports and calls
~20 further cost-bearing engine mutators directly (production, research, market,
diplomacy, colony, galaxy). See §1.6. The wire protocol must cover both, and the
second group is where the money is.

---

## 1. Signature audit — every export of `engine/commands.js`

22 exports, `engine/commands.js:231`–`:533`.

Legend for **Params**: `OBJ` = live object reference (unserialisable), `ID` =
string id, `SC` = scalar/plain-JSON, `STATE` = the whole `State`.

### 1.1 The table

| # | Function | Line | Exact signature | Param kinds | Owner check? | Afford check? | Mutates `players[x].resources`? | State written |
|---|---|---|---|---|---|---|---|---|
| 1 | `issueMove` | 231 | `(units, x, y, queue = false, formation)` | `units:OBJ[]`, `x,y,queue:SC`, `formation:SC` | **NO** | n/a | no | `u.order`, `u.orderQueue`, `u.hold`, `u.squadLeader`, `leader.squadFollowers`, `u.facing`, `order.speedCap` |
| 2 | `issueGather` | 237 | `(units, nodeId, queue = false)` | `units:OBJ[]`, `nodeId:ID`, `queue:SC` | **NO** | n/a | no | `u.order={type:"gather",nodeId}` (filtered by `canGatherType`) |
| 3 | `issueServiceBuilding` | 244 | `(units, buildingId, queue = false)` | `units:OBJ[]`, `buildingId:ID` | **NO** (neither unit nor building) | n/a | no | `u.order={type:"service",buildingId,phase:"plan",manual:true}` |
| 4 | `issueFerryFreighter` | 255 | `(units, freighterId, queue = false)` | `units:OBJ[]`, `freighterId:ID` | **NO** | n/a | no | `u.order={type:"ferry",…}` |
| 5 | `issueRepair` | 267 | `(units, targetId, queue = false)` | `units:OBJ[]`, `targetId:ID` | **NO** | n/a | no | `u.order={type:"repair",targetId,phase:"toSite",manual:true}` |
| 6 | `issueSetHomeBase` | 281 | `(units, ccId)` | `units:OBJ[]`, `ccId:ID` | **NO** | n/a | no | `u.homeCC` — `ccId` never validated as existing, as a building, as a CC, or as owned |
| 7 | `issueSetAILogistics` | 295 | `(units, on, state)` | `units:OBJ[]`, `on:SC`, `state:STATE` | **partial** — reads `state.players[u.owner].upgrades` (`:298`), so it is *correctly owner-scoped for the tech gate*, but does not check the caller owns the unit | n/a | no (upkeep is charged later, `haul.js payAIUpkeep`) | `u.aiLogistics`, `u.cargo` |
| 8 | `issueSetCollectPoint` | 310 | `(units, on)` | `units:OBJ[]`, `on:SC` | **NO** | n/a | no | `u.collectPoint`, `u.anchor` |
| 9 | `issueSetLogiPriority` | 330 | `(state, buildingId, priority)` | `state:STATE`, `buildingId:ID`, `priority:SC` | **NO** | n/a | no | `b.logiPriority` on **any** building in the world |
| 10 | `issueAttack` | 343 | `(units, targetId, queue = false)` | `units:OBJ[]`, `targetId:ID` | **NO** — and no hostility check either | n/a | no | `u.order={type:"attack",targetId}` (filtered to `def.attack \|\| role==="support"`) |
| 11 | `issueAttackMove` | 350 | `(units, x, y, queue = false, formation)` | as `issueMove` | **NO** | n/a | no | as `issueMove`, order type `attack-move` |
| 12 | `issueEscort` | 361 | `(units, targetId, queue = false)` | `units:OBJ[]`, `targetId:ID` | **NO** | n/a | no | `u.order={type:"escort",targetId,slot:i,slots:n}` — **no role filter at all** |
| 13 | `issueHoldFormation` | 375 | `(units, shape = "grid", leaderPos = "front")` | `units:OBJ[]`, `shape,leaderPos:SC` | **NO** | n/a | no | `hold-formation` orders + `u.hold` for `role==="combat"`; anchor is the **live centroid** of `units` |
| 14 | `issueBuild` | 390 | `(state, workerId, buildingType, x, y)` | `state:STATE`, `workerId:ID`, `buildingType,x,y:SC` | **NO** — derives `player` from `worker.owner` (`:393`) | **YES** `canAfford` `:404` | **YES — `payCost` `:407`** | mints a `constructing` building into `state.buildings`, sets `worker.order`; **returns the new building id** |
| 15 | `issueAssistBuild` | 420 | `(units, buildingId, buildingType, queue = false)` | `units:OBJ[]`, `buildingId,buildingType:ID/SC` | **NO** | n/a | no | `u.order={type:"build",buildingId}`; **`buildingType` is trusted from the caller** and only used to resolve the eligibility category (`:421`) |
| 16 | `issueStop` | 434 | `(units)` | `units:OBJ[]` | **NO** | n/a | no | clears `order`, `orderQueue`, `hold`, `recycling`, `squadLeader` |
| 17 | `issueRecycle` | 444 | `(entities)` | `entities:OBJ[]` (mixed `Unit`\|`Building`) | **NO** | n/a | **indirectly YES** — `beginRecycle` starts a timer that `recycle.js:136-138` later banks into `state.players[entity.owner].resources`, and `removeEntity`s the entity | `e.recycling`, `e.order`, `e.hold` |
| 18 | `issueCancelRecycle` | 454 | `(entities)` | `entities:OBJ[]` | **NO** | n/a | no | clears `e.recycling` |
| 19 | `issueHold` | 462 | `(units)` | `units:OBJ[]` | **NO** | n/a | no | `u.hold = true`, clears orders (combat role only) |
| 20 | `issuePatrol` | 480 | `(units, points)` | `units:OBJ[]`, `points:SC[]` | **NO** | n/a | no | a looping `attack-move … patrol:true` chain; **`points` length is unbounded** |
| 21 | `issueScout` | 509 | `(units)` | `units:OBJ[]` | **NO** | n/a | no | `u.order={type:"scout",speedCap?}` (scout role only) |
| 22 | `issueSetRally` | 531 | `(building, x, y, nodeId = null)` | `building:OBJ`, `x,y,nodeId:SC` | **NO** | n/a | no | `building.rally = {x,y,nodeId}` — **zero validation of anything** |

### 1.2 The central problem, confirmed

**20 of 22 take live object references.** Only `issueBuild` (`:390`) and
`issueSetLogiPriority` (`:330`) are fully id-based; `issueSetRally` (`:531`) is
the extreme case, taking a bare `Building` object with no `state` at all.

The object refs are not incidental — they are structural. `dispatchFormation`
(`:144`) *stores* references: `leader.squadFollowers = newFollowers`
(`:195`) and `dispatch(units[i], {type:"follow-leader", leader, …})` (`:204-207`)
puts a **live `Unit` object inside an order**. `setSquadLeader` (`:46`) maintains
a bidirectional object graph. That graph is explicitly non-serialisable and
`persist.js` already deals with it by *dropping* it — see the comment at
`engine/commands.js:43-45`: *"Transient, session-only state (never persisted — see
persist.js's serPlanet, which strips both fields and drops a live follow-leader
order entirely rather than trying to serialize the object reference it carries)."*

**Consequence for netcode:** the object graph is fine *inside* the authoritative
server sim (it never crosses a wire). What crosses the wire is only the *intent*.
So the id→object boundary belongs in an adapter, not in the engine. This is the
single most important architectural fact in this document, and it is what makes
D1 correct.

### 1.3 Hidden inputs that are not parameters

Three commands read state the wire schema must therefore also carry or recompute:

- `issueHoldFormation` (`:377-379`) computes the anchor from the **live centroid**
  of the passed units. The anchor is therefore a function of *when* the command
  applies. Two identical commands applied at different ticks produce different
  worlds. Scheduling must be authoritative and logged (§5).
- `issueMove`/`issueAttackMove` cap group speed from `UNITS[u.type].speed` of the
  live set (`groupSpeedCap`, `:66-69`) and re-derive `leader.squadFollowers`.
- `issueScout` (`:514-518`) reads and **prunes** `u.squadFollowers` by `hp > 0`.

### 1.4 The `owner === "player"` gate — a hard multiplayer blocker

`engine/commands.js:155`:

```js
if (leader.owner !== "player") {
  const spots = formationSlots(units, x, y, formation);
  units.forEach((u, i) => dispatch(u, makeLeaderOrder(spots[i]), queue));
  return;
}
```

The entire leader/follower squad mechanic — the thing that makes formations
*formations* rather than a one-shot grid spread — is gated on the literal owner
id `"player"`. In a 4-player match with owners `p1..p4`, **no seat gets
formations**. See §8/B2.

### 1.5 Silent-skip is the house style

Every role/capability filter in this file *silently skips* ineligible units
rather than failing the call (`canGatherType` `:238`, `canLogisticsType` `:246`,
`role === "combat"` `:464`, `canBuildCategory` `:422`). This is deliberate and
documented (`:293-294`, `:441-443`). **The codec must preserve it**: a mixed
selection must not be rejected wholesale because one unit is ineligible. Only
*ownership* violations are hard rejects (§2.6).

### 1.6 The second intent surface — `engine/commands.js` is not the whole story

`hudSelection.js:20-35` imports these directly, and they are all reachable from a
button click:

| Module | Exports the HUD calls | Cost-bearing? |
|---|---|---|
| `engine/production.js` | `queueProduction` `:118`, `cancelProduction` `:164`, `researchUpgrade` `:185` | **yes** — `payCost` at `:152`, `:205`; refund at `:173` |
| `engine/techtree.js` | `researchTech` `:190`, `cancelResearch` `:224` | **yes** |
| `engine/market.js` | `sell` `:164`, `buy` `:208` | **yes** |
| `engine/diplomacy.js` | `offerTribute` `:248`, `offerGift` `:271`, `fulfillRequest` `:290` | **yes** |
| `engine/colony.js` | `deployColonyShip` `:31`, `packCommandCenter` `:70` | **yes** (`PACK_COST`, `:86`) |
| `engine/colonyPolicy.js` | `setColonyPolicy` `:82` | no |
| `engine/bomb.js` | `lightFuse` `:249` | no (destructive) |
| `engine/galaxy.js` | `upgradeSpaceport`, `loadFreighter`, `unloadFreighter`, `createLane`, `deleteLane`, `assignShipToLane`, `upgradeToCapital`, `jumpVessel` | **yes** |

All three of `queueProduction`, `cancelProduction`, `researchUpgrade` derive the
paying player from `building.owner`, **not from a caller-supplied owner**:

```js
// engine/production.js:140
const player = state.players[building.owner];
if (!canAfford(player.resources, cost)) return false;
```

So they have exactly the same exposure class as `issueBuild` (§2.2). The wire
protocol below is designed as an open union so these fold in as additional
command types with the same envelope, resolver and ownership rule — see §3.6.
**Recommendation:** ship the unit-order commands (§3.4) in phase 1 and the
economy commands (§3.6) in phase 2, both through the same codec.

---

## 2. Ownership & validation gaps — the anti-cheat surface

**Baseline:** in single-player none of this matters, because the *only* callers
are `inputCommands.js` (which pre-filters to `owner === "player"`, e.g.
`inputCommands.js:99`, `:206`, `:211`) and the AI (which passes its own units).
Ownership enforcement lives entirely in the UI. Expose these over a socket
naively and every one of them becomes a cheat.

Ranked by severity.

### 2.1 CATASTROPHIC — destroy or disable another player's army

| Command | Attack |
|---|---|
| `issueRecycle(entities)` `:444` | Send the enemy's building/unit ids. `canRecycle` (`recycle.js:80`) only refuses a Command Center, a constructing building, or an already-recycling entity. Everything else starts a timer that ends in `removeEntity` (`recycle.js:149`, `:163`). **You can dismantle an opponent's entire base.** |
| `issueStop(units)` `:434` | Send every enemy unit id every tick. Clears `order`, `orderQueue`, `hold`, and `recycling`. The opposing army is permanently frozen — it can still auto-defend (`combat.js` re-acquires), but never moves, gathers, or builds again. |
| `issueAttack(units, targetId)` `:343` | Two attacks in one. (a) Send *your* units at a *friendly/allied* target: `combat.js:46` reads `unit.order.targetId` with **no owner filter**, and `performAttack` (`combat.js:85`) is reached without one — explicit orders are friendly-fire capable, unlike auto-acquisition which does filter (`combat.js:153`, `:243`, `:386`, `:411`). (b) Send *the enemy's* unit ids at *the enemy's own* buildings and they self-destruct. |
| `issueHold(units)` `:462` | Freeze the enemy's combat units in place (`u.hold = true`), then walk past them: `combat.js:83` refuses to chase while `unit.hold`. |

`recycle.js:87-89` carries a comment asserting the guard exists:

> *"Start recycling `entity` in place. Pure state mutation — engine/commands.js's
> issueRecycle checks ownership/canRecycle and handles the unit-order-dispatch
> side…"*

`issueRecycle` (`commands.js:444-450`) checks `canRecycle` and nothing else.
**The comment is wrong.** Fix the comment as part of the codec work so the next
reader is not misled into trusting a check that does not exist.

### 2.2 SEVERE — spend another player's resources

| Command | Attack |
|---|---|
| `issueBuild(state, workerId, …)` `:390` | `const player = state.players[worker.owner]` `:393`, then `payCost(player.resources, def.cost)` `:407`. Name an **enemy** worker id and you drain *their* treasury and hijack *their* worker's order (`:411`). You do not gain the building — but you can bankrupt them and pin their workers to construction sites at will. Placement, prereqs and affordability are all validated **against the victim**, so a well-chosen spam of expensive buildings is a total economic denial. |
| `queueProduction(state, buildingId, …)` `production.js:118` | Same shape: `state.players[building.owner]` `:140`, `payCost` `:152`. Fill the enemy's queues, drain their bank, and consume their supply cap (`:147`). |
| `cancelProduction(state, buildingId, i)` `production.js:164` | Delete an arbitrary index out of any building's queue (`:169`). Refunds to the owner, so it is pure griefing: cancel the enemy's army as fast as they queue it. |
| `researchUpgrade` / `researchTech` | Same derivation; burn the victim's bank on a doctrine they did not choose, and — because of the doctrine lock (`production.js:194-195`) — **permanently deny them the other doctrine.** This is the most damaging economic attack in the set. |

### 2.3 MODERATE — sabotage, waste, and free labour

| Command | Attack |
|---|---|
| `issueSetLogiPriority(state, buildingId, priority)` `:330` | No owner check anywhere. Set every enemy factory to `"low"` and their logistics chain starves (`haul.js priorityWeight`). |
| `issueSetRally(building, x, y, nodeId)` `:531` | Object-ref, zero validation. Once the codec resolves an id, an unguarded path re-points every enemy production building's rally into a corner of the map — or onto your own guns. |
| `issueSetHomeBase(units, ccId)` `:281` | `ccId` is never validated (not existence, not kind, not owner). Point the enemy's workers at *your* CC and their whole `zoneFirst` job search (`gather.js`) goes wrong. |
| `issueRepair(units, targetId)` `:267` | No owner check on either side. Order *your* workers to repair the *enemy's* CC. `repair.js:161`/`:172` gate the passive Mender scan on `owner`, but `updateRepairJob` runs off the explicit order. Mostly self-harm — but in a team game it is a way to launder resources/labour to a nominal opponent. |
| `issueAssistBuild(units, buildingId, buildingType)` `:420` | Two holes. (a) `buildingId` is unvalidated — send workers to accelerate an enemy site. (b) **`buildingType` is trusted from the caller** and is the only thing that resolves the eligibility category (`:421`). A client that lies about the type walks a combat unit onto a construction site the engine would otherwise refuse. The codec must read the type from the *resolved building*, never from the wire. |
| `issueSetAILogistics` `:295` / `issueSetCollectPoint` `:310` | Flip the enemy's freighters into/out of AI-logistics mode. The tech gate is correctly scoped to `u.owner` (`:298`) so you cannot grant them a mode they have not researched — but you can force one on, which burns their AI Cores (`haul.js payAIUpkeep`), or force one off mid-haul. |
| `issueServiceBuilding` `:244` / `issueFerryFreighter` `:255` | Same class: unvalidated target ids, cross-owner assignment. |

### 2.4 MAPHACK — fog is enforced only in the UI

`inputCommands.js` gates target picking on fog: `entityAt` skips non-player
entities that fail `isVisibleAt(state.fog, …)` (`inputCommands.js:58`, `:62`) and
`nodeAt` requires `isNodeDiscovered` (`:69`). **No engine function checks fog.**
A client that ignores its own renderer can:

- `issueAttack` a unit it has never seen (targeted alpha-strikes into fog),
- `issueGather` an undiscovered node — instant map knowledge of every deposit,
- `issueBuild` anywhere on the map: `canPlaceBuilding` (`colliders.js:26-47`)
  checks bounds, building overlap, node overlap and terrain — **never fog and
  never proximity to your own territory**. Wall in an enemy's expansion on turn
  one.

Fog enforcement is therefore a **new server-side rule** the codec must add; it
does not exist anywhere in the engine today.

### 2.5 DoS / resource-exhaustion

- `issuePatrol(units, points)` `:480-493` — `points` is unbounded and every point
  is pushed onto **every** unit's `orderQueue`. `|units| × |points|` allocations
  with no cap. 400 units × 100k points is a server OOM.
- Selection size is unbounded everywhere. `dispatchFormation` → `formationSlots`
  → `clusterUnits` (`formation.js:108`) is superlinear in group size.
- Command rate is unbounded. `issueStop` on 400 units at 20 Hz is cheap for the
  attacker and expensive for the server.

### 2.6 The rule that fixes 2.1–2.3 in one place

> **Every entity id on the wire resolves through the codec, and every resolution
> is scoped to the submitting owner.** A unit/building the submitter does not own
> is a *hard reject* of the whole command. A unit/building that has *ceased to
> exist* is a *silent drop* of that one id (it is a legitimate race between issue
> and apply, not a lie).

That distinction matters: rejecting on "not found" would make the protocol fail
constantly under normal packet latency, while dropping on "not yours" would let
an attacker probe the world for free.

Targets (the *object* of a command, not the *subject*) get a different rule —
see §3.5.

---

## 3. Wire schema

### 3.1 The envelope

One JSON object per command. Sent client→server over the WebSocket; the same
shape, once stamped, is what goes in the replay log.

```jsonc
{
  "v": 1,                     // PROTOCOL_VERSION — reject on mismatch, never coerce
  "seq": 417,                 // per-client monotonic counter, starts at 1
  "tick": 1183,               // ADVISORY: the tick the client believed it was on
  "cmd": { "t": "move", "ids": ["u12","u7"], "x": 900, "y": 412, "q": false,
           "f": { "s": "wedge", "l": "front", "hx": 1, "hy": 0 } }
}
```

Server-side, after admission, it becomes a **log record**:

```jsonc
{
  "v": 1,
  "seq": 417,
  "owner": "p2",              // AUTHORITATIVE — from the socket's session, never the client
  "applyTick": 1186,          // AUTHORITATIVE — stamped by the server at admission
  "cmd": { … },               // verbatim, post-validation
  "result": { "ok": true, "buildingId": "b41" }   // echo for build-like commands
}
```

**Deliberate design points.**

- **`owner` is never on the client→server wire.** It is stamped from the
  authenticated session. A field a client can set is a field a client will lie
  about. This is the single change that neutralises §2.1 and §2.2 by
  construction — an id-based protocol whose owner is client-supplied is *no
  safer* than passing object refs.
- **`tick` is advisory.** The server stamps `applyTick` itself (§5.2). The client
  value is kept only for latency telemetry and for detecting a client running
  ahead.
- **`seq` is the tie-break** and the replay/duplicate guard. `(owner, seq)` must
  be unique; a repeat is dropped idempotently.
- **Short keys** (`t`, `q`, `f`, `s`, `l`, `hx`) because these are the highest-rate
  messages in the protocol. Everything else in the game (chat, lobby, state
  snapshots) can afford long keys.

### 3.2 Batches

One right-click already fans out into several `issue*` calls —
`inputCommands.js:90-96` splits a selection into combatants (`issueAttackMove`)
and everyone else (`issueMove`), and `commandAt` (`:194-285`) picks one of eight
verbs. **Decision: the client resolves the gesture into primitive commands, and
ships them as an atomic batch.**

```jsonc
{ "v": 1, "seq": 418, "cmd": { "t": "batch", "c": [ {…}, {…} ] } }
```

A batch applies at one `applyTick`, in array order, all-or-nothing on validation
(if any member is rejected, the whole batch is rejected — the client's
disambiguation was built on a state it did not actually have). Max 16 members.

Rationale for client-side gesture resolution: `commandAt` is 92 lines of
UI-policy (`inputCommands.js:15-17` calls this out explicitly), it depends on
camera/pick-radius/touch-mode, and an MCP agent has no gesture at all — it wants
to say `attack`, not "right-click at (900,412)". Putting the verb on the wire
also makes the log human-readable, which matters enormously for replay debugging.
The cost is that a lying client can pick a verb the UI would not have offered —
which is exactly what §3.5's server-side re-validation is for.

### 3.3 How selections are expressed

```ts
/** Ordered, de-duplicated entity ids. ORDER IS LOAD-BEARING. */
type Ids = string[];   // 1..400
```

`ids[0]` is the **formation leader**: `dispatchFormation` takes
`const leader = units[0]` (`commands.js:145`), assigns
`leader.squadFollowers = units.slice(1)` (`:195`), and `rankSlotsByRange`
passes `spots[0]` through untouched because *"the leader is a documented player
choice … never re-picked by a stat"* (`:87-88`). `issueEscort` likewise derives
`slot: i, slots: n` from array position (`:363`).

**Therefore the codec must not sort, canonicalise or re-order `ids`.** It
de-duplicates preserving first occurrence, and drops dead ids in place. This is
also why the client's `state.selection` order is preserved through
`applyBoxSelection`'s promote-to-front behaviour (`inputCommands.js:152`) — that
ordering *is* game input and must be logged verbatim.

### 3.4 Command types — phase 1 (unit orders)

```ts
/** engine/formation.js:59-60 — the ONLY legal values. */
type Shape  = "grid" | "line" | "wedge" | "circle";
type LeadPos = "front" | "back" | "center";

/** Rides on move / attack-move. Maps to engine/commands.js's `formation` opts bag. */
interface WireFormation {
  s?: Shape;      // shape;     default "grid"
  l?: LeadPos;    // leaderPos; default "front"
  hx?: number;    // headingX — the right-click-DRAG vector; stamped as unit.facing (commands.js:218)
  hy?: number;    // headingY
}
// NOTE: originX/originY are NOT on the wire. issueHoldFormation derives them
// server-side from the live centroid (commands.js:377-380).

type WireCommand =
  // ---- movement -----------------------------------------------------------
  | { t: "move";        ids: Ids; x: number; y: number; q?: boolean; f?: WireFormation }
  | { t: "attackMove";  ids: Ids; x: number; y: number; q?: boolean; f?: WireFormation }
  | { t: "holdFormation"; ids: Ids; s?: Shape; l?: LeadPos }
  | { t: "patrol";      ids: Ids; pts: Array<{ x: number; y: number }> }   // 1..32
  | { t: "stop";        ids: Ids }
  | { t: "hold";        ids: Ids }
  | { t: "scout";       ids: Ids }

  // ---- targeted at another entity -----------------------------------------
  | { t: "attack";      ids: Ids; target: string; q?: boolean }
  | { t: "escort";      ids: Ids; target: string; q?: boolean }
  | { t: "repair";      ids: Ids; target: string; q?: boolean }
  | { t: "gather";      ids: Ids; node:   string; q?: boolean }
  | { t: "service";     ids: Ids; target: string; q?: boolean }   // building
  | { t: "ferry";       ids: Ids; target: string; q?: boolean }   // own freighter
  | { t: "setHomeBase"; ids: Ids; target: string }                // own command center
  | { t: "assistBuild"; ids: Ids; target: string; q?: boolean }   // NOTE: no buildingType — server reads it

  // ---- construction / teardown --------------------------------------------
  | { t: "build";       worker: string; b: string; x: number; y: number }
  | { t: "recycle";       ids: Ids }   // units AND buildings
  | { t: "cancelRecycle"; ids: Ids }

  // ---- toggles / properties ------------------------------------------------
  | { t: "setAILogistics";  ids: Ids; on: boolean }
  | { t: "setCollectPoint"; ids: Ids; on: boolean }
  | { t: "setLogiPriority"; building: string; p: "high" | "normal" | "low" }
  | { t: "setRally";        building: string; x: number; y: number; node?: string | null }

  // ---- envelope-level ------------------------------------------------------
  | { t: "batch"; c: WireCommand[] };   // 1..16, no nesting
```

**Mapping notes.**

- `q` is `queue` — the Ctrl-modifier. Pure boolean, rides on every command whose
  engine signature has a `queue` parameter. It is *not* meaningful for `stop`,
  `hold`, `scout`, `holdFormation`, `patrol`, `recycle` or the toggles, and is
  rejected as malformed there rather than ignored (silent ignore hides client
  bugs).
- `f` (formation) rides only on `move`/`attackMove`. `holdFormation` takes
  `s`/`l` directly because its engine signature is
  `(units, shape, leaderPos)` (`:375`), not an opts bag.
- **`assistBuild` deliberately drops `buildingType`.** The engine takes it
  (`:420`) but the codec supplies `site.type` from the resolved building — see
  §2.3. This is an example of the codec being *narrower* than the engine on
  purpose.
- `setRally.node` is a `nodeId` or `null` (`:531`); the codec validates it exists
  and is discovered.
- `escort` takes no role filter in the engine (`:361`) — the codec adds none
  either, matching current behaviour exactly, but it *does* reject
  `target ∈ ids` (`inputCommands.js:272` filters the target out client-side; the
  codec does it server-side so the engine cannot be handed a self-escort).

### 3.5 Server-side re-validation rules

For each command the codec applies, in order:

1. **Envelope** — `v === PROTOCOL_VERSION`, `seq` unseen for this owner, shape
   matches the union (unknown key ⇒ reject; JSON only, no prototypes).
2. **Subject resolution** — `ids`/`worker`/`building` resolve to live entities
   **owned by the stamped owner**. Foreign ⇒ hard reject `not-owner`. Missing ⇒
   silent drop of that id; empty result ⇒ reject `empty-selection`.
3. **Bounds** — every `x`/`y` inside `[0, map.width] × [0, map.height]`
   (`colliders.js:31` checks the footprint but the codec checks the raw point
   first, so an absurd coordinate never reaches formation math).
4. **Enum** — `s ∈ FORMATION_SHAPES`, `l ∈ LEADER_POSITIONS`
   (`formation.js:59-60`), `p ∈ LOGI_PRIORITIES` (`haul.js:102`),
   `b ∈ Object.keys(BUILDINGS)`.
5. **Limits** — `ids.length ≤ 400`, `pts.length ≤ 32`, `batch.c.length ≤ 16`,
   plus a per-owner token bucket (recommend 30 commands/sec sustained, burst 60 —
   comfortably above human APM and above the AI's own budgeted rate).
6. **Target visibility** (new rule, §2.4):
   - **own** entity ⇒ no fog check.
   - foreign **unit** ⇒ `isVisibleAt(state.fogs[owner], t.x, t.y)` (`fog.js:49`).
   - foreign **building** ⇒ `isExploredAt(…)` (`fog.js:55`) — remembered
     structures stay attackable, which is standard RTS and matches what the
     renderer already shows.
   - **node** ⇒ `isNodeDiscovered(state.fogs[owner], node)` (`fog.js:66`).
7. **Delegate** to `engine/commands.js`, unchanged. Affordability, prereqs,
   placement, doctrine locks and role filters stay **exactly where they are** —
   `issueBuild:404-407` re-runs `canAfford`/`prereqsMet`/`canPlaceBuilding`
   server-side for free, because the server *is* the authority and the codec
   calls the same function the local game calls.

That last point is the payoff of D1: **`issueBuild`'s placement validation is not
re-implemented in the codec at all.** The codec's only job is to prove the worker
belongs to the submitter; `canPlaceBuilding(state, buildingType, x, y)`
(`colliders.js:26`) then runs against the authoritative state at the scheduled
tick and returns `null` if the ground was taken in the meantime. The codec maps
that `null` to a `refused` result and echoes it to the client, which rolls back
its optimistic ghost. No duplicated collision logic, no drift between client
preview and server truth.

### 3.6 Phase 2 — the economy commands

Same envelope, same resolver, appended to the union:

```ts
type WireCommand2 =
  | { t: "queueProduction";  building: string; u: string; alt?: boolean }
  | { t: "cancelProduction"; building: string; i: number }
  | { t: "researchUpgrade";  building: string; up: string }
  | { t: "researchTech";     building: string; tech: string }
  | { t: "cancelResearch";   building: string; i: number }
  | { t: "deployColonyShip"; ship: string }
  | { t: "packCommandCenter"; building: string }
  | { t: "lightFuse";        unit: string }
  | { t: "marketSell" | "marketBuy"; com: string; qty: number }
  | { t: "setColonyPolicy";  planet: string; patch: object };
```

Every one of these resolves its `building`/`unit`/`ship` id through the same
owner-scoped resolver, which closes §2.2 wholesale. `marketSell`/`marketBuy` and
the diplomacy verbs take no entity id at all and are scoped by the stamped owner
directly — note `market.js:164 sell(galaxy, state, com, qty)` currently has **no
owner parameter**; it will need one (or a per-owner market), which is a genuine
Odyssey-scope design question and is out of scope for this document.

---

## 4. The adapter layer — `net/commandCodec.js`

### 4.1 Recommendation: **wrap, do not change `engine/commands.js`**

**Decision: D1. Keep object-ref signatures. Add `net/commandCodec.js`.**

Reasons, in order of weight:

1. **The object graph is not incidental.** `follow-leader` orders carry a live
   `Unit` (`commands.js:205`), `squadFollowers`/`squadLeader` are a bidirectional
   object graph (`:46-53`), and the file itself documents this as transient,
   deliberately non-serialisable state (`:43-45`). "Make it id-based" is not a
   signature change; it is a rewrite of the squad system plus every consumer in
   `movement.js` (`keepFollowingLeader`, `escortSlot`) — with a real perf cost
   (`test/perf-guard.test.js` exists) from re-doing `state.units.get()` in the
   hot loop.
2. **Blast radius.** **209 call sites** outside `engine/commands.js`, across 20 files:
   `test/commands.test.js` (58), `test/formation.test.js` (36),
   `test/ferry.test.js` (28), `test/recycle.test.js` (16), `inputCommands.js`
   (13), `engine/aiMilitary.js` (11), `input.js` (6), `test/sim.test.js` (6),
   `test/scout.test.js` (6), `test/escort.test.js` (6), `hudSelection.js` (5),
   plus 9 more files. Against 2519 tests and a
   determinism guard, that is a multi-day change with a real chance of a silent
   behavioural drift that only `test/determinism.test.js` would catch — and only
   if the drift happens to change a fingerprinted field.
3. **The AI already holds objects.** `aiMilitary.js`/`aiEconomy.js` iterate live
   units and pass them straight in. Forcing ids means map lookups the AI does not
   need, on the sim's hot path, for zero benefit — the AI never crosses a wire.
4. **A choke point is worth more than scattered guards.** One file to audit, one
   file to fuzz, one file to rate-limit, one file where "did we check ownership?"
   has a single answer. Scattering `owner` parameters into 22 engine functions
   would also mean every AI and test call site must now supply an owner —
   the *same* 209-site churn, plus a permanently wider engine API.
5. **The engine stays DOM-free and pure.** The codec is `net/`, not `engine/`, so
   `test/engine-purity.test.js` and the determinism guard keep their current
   boundary unchanged.

**What we give up:** the engine's public API stays "unsafe by default" — anyone
who calls `issueRecycle` directly can still recycle an enemy. Mitigation: a
guard test asserting that no file under `net/` or `server/` imports
`engine/commands.js` **except** `net/commandCodec.js`. Same idiom as the existing
`test/engine-purity.test.js` import walk (`engine-purity.test.js:35-52`).

### 4.2 The one exception — `issueSetRally` (D2)

`issueSetRally(building, x, y, nodeId)` (`:531`) is the only export taking a bare
entity object with no `state`. It is a 1-line function, has **3 call sites**
total, does no validation whatsoever, and is the only place where the codec would
otherwise have to hand a raw object across the boundary. Change it to match its
id-based sibling `issueSetLogiPriority(state, buildingId, priority)` (`:330`):

```js
export function issueSetRally(state, buildingId, x, y, nodeId = null) {
  const b = state.buildings.get(buildingId);
  if (!b) return;
  b.rally = { x, y, nodeId };
}
```

Cost: 3 call sites (`inputCommands.js:199` + 2 tests). Benefit: the codec's
entity-resolution rule becomes universal with no special case.

`issueSetAILogistics(units, on, state)` (`:295`) has an odd trailing `state`
parameter. **Leave it.** It is ugly, it is not a correctness problem, and
touching it buys nothing.

### 4.3 The codec

```js
/* ============================================================
   net/commandCodec.js — the ONLY bridge between the wire and engine/commands.js.

   Wire commands are id-based, owner-scoped and tick-scheduled. This file
   resolves ids to the live objects engine/commands.js wants, proves the
   submitting owner actually owns them, and delegates. It deliberately
   re-implements NO game rule: affordability, prereqs, placement, doctrine
   locks and role filters all stay in engine/, which the server calls exactly
   as the single-player client does.

   INVARIANT: no other module under net/ or server/ may import
   engine/commands.js. See test/net-boundary.test.js.
   ============================================================ */

"use strict";

import * as cmd from "../engine/commands.js";
import { BUILDINGS } from "../engine/entities.js";
import { FORMATION_SHAPES, LEADER_POSITIONS } from "../engine/formation.js";
import { LOGI_PRIORITIES } from "../engine/haul.js";
import { isVisibleAt, isExploredAt, isNodeDiscovered } from "../engine/fog.js";

export const PROTOCOL_VERSION = 1;

export const LIMITS = {
  ids: 400,          // per-command selection cap
  patrolPoints: 32,  // engine/commands.js:484 pushes |ids| x |pts| orders — must be bounded
  batch: 16,
};

export const REJECT = {
  BAD_VERSION:  "bad-version",
  UNKNOWN_TYPE: "unknown-type",
  MALFORMED:    "malformed",
  TOO_MANY:     "too-many",
  NOT_OWNER:    "not-owner",       // a LIE — the submitter does not own this entity
  NO_TARGET:    "no-target",       // the object of the command does not exist
  NOT_VISIBLE:  "not-visible",     // fog gate (a rule the engine does not have)
  EMPTY:        "empty-selection", // every id resolved to nothing (a legitimate race)
  OUT_OF_BOUNDS:"out-of-bounds",
  REFUSED:      "refused",         // the ENGINE said no (afford / prereq / placement)
};

/* ---------- primitives ---------- */

const isId  = v => typeof v === "string" && v.length > 0 && v.length <= 32;
const isNum = v => typeof v === "number" && Number.isFinite(v);
const bool  = v => v === undefined || typeof v === "boolean";

const ok   = (result = null) => ({ ok: true, result });
const err  = code => ({ ok: false, code });

function inBounds(state, x, y) {
  return isNum(x) && isNum(y) && x >= 0 && y >= 0 && x <= state.map.width && y <= state.map.height;
}

/* ---------- resolvers: id -> live object, scoped to `owner` ----------

   Two failure modes, deliberately different:
     - the entity is GONE      -> drop that id (a real race between issue and apply)
     - the entity is SOMEONE ELSE'S -> reject the whole command (a lie)
   Rejecting on "gone" would make the protocol fail under ordinary latency;
   dropping on "not yours" would let an attacker probe the world for free.

   ORDER IS PRESERVED. ids[0] is the formation leader (engine/commands.js:145,
   :195) and issueEscort derives ring slots from array index (:363). Never sort.
*/

function resolveOwn(state, owner, ids, pick) {
  if (!Array.isArray(ids) || ids.length === 0) return err(REJECT.EMPTY);
  if (ids.length > LIMITS.ids) return err(REJECT.TOO_MANY);
  const seen = new Set();
  const out = [];
  for (const id of ids) {
    if (!isId(id)) return err(REJECT.MALFORMED);
    if (seen.has(id)) continue;                 // dedupe, first occurrence wins
    seen.add(id);
    const e = pick(state, id);
    if (!e) continue;                           // died in flight — drop
    if (e.owner !== owner) return err(REJECT.NOT_OWNER);
    out.push(e);
  }
  return out.length ? ok(out) : err(REJECT.EMPTY);
}

const pickUnit     = (s, id) => s.units.get(id);
const pickBuilding = (s, id) => s.buildings.get(id);
const pickEntity   = (s, id) => s.units.get(id) || s.buildings.get(id);

const ownUnits      = (s, o, ids) => resolveOwn(s, o, ids, pickUnit);
const ownEntities   = (s, o, ids) => resolveOwn(s, o, ids, pickEntity);   // recycle takes both

function ownBuilding(state, owner, id) {
  if (!isId(id)) return err(REJECT.MALFORMED);
  const b = state.buildings.get(id);
  if (!b) return err(REJECT.NO_TARGET);
  if (b.owner !== owner) return err(REJECT.NOT_OWNER);
  return ok(b);
}

function ownUnit(state, owner, id) {
  if (!isId(id)) return err(REJECT.MALFORMED);
  const u = state.units.get(id);
  if (!u) return err(REJECT.NO_TARGET);
  if (u.owner !== owner) return err(REJECT.NOT_OWNER);
  return ok(u);
}

/* Any entity as the OBJECT of a command. Own entities need no fog check; a
   foreign unit must be currently visible, a foreign building merely explored
   (remembered structures stay targetable — standard RTS, and it is what the
   renderer already draws). This rule does not exist in the engine at all:
   inputCommands.js:58,:62 enforces it in the UI only, so a client that ignores
   its own renderer is a maphack today. */
function targetEntity(state, owner, id) {
  if (!isId(id)) return err(REJECT.MALFORMED);
  const e = pickEntity(state, id);
  if (!e) return err(REJECT.NO_TARGET);
  if (e.owner === owner) return ok(e);
  const fog = state.fogs[owner];
  const seen = e.kind === "building" ? isExploredAt(fog, e.x, e.y) : isVisibleAt(fog, e.x, e.y);
  return seen ? ok(e) : err(REJECT.NOT_VISIBLE);
}

function targetNode(state, owner, id) {
  if (!isId(id)) return err(REJECT.MALFORMED);
  const n = state.map.nodes.find(n => n.id === id);
  if (!n) return err(REJECT.NO_TARGET);
  return isNodeDiscovered(state.fogs[owner], n) ? ok(n) : err(REJECT.NOT_VISIBLE);
}

/* ---------- formation ---------- */

function decodeFormation(f) {
  if (f === undefined) return undefined;                 // engine default: flat grid spread
  if (f === null || typeof f !== "object") return null;  // null => malformed
  const { s = "grid", l = "front", hx, hy } = f;
  if (!FORMATION_SHAPES.includes(s)) return null;
  if (!LEADER_POSITIONS.includes(l)) return null;
  if (hx !== undefined && !isNum(hx)) return null;
  if (hy !== undefined && !isNum(hy)) return null;
  const out = { shape: s, leaderPos: l };
  if (hx !== undefined) out.headingX = hx;               // the right-click-DRAG facing (commands.js:218)
  if (hy !== undefined) out.headingY = hy;
  return out;
}

/* ---------- the schema table ----------
   One entry per wire type. `run` receives already-resolved, already-owned
   objects and does nothing but call engine/commands.js. Everything that could
   reject has already rejected. */

const SCHEMA = {

  /* ----- movement ----- */
  move: { run(state, owner, c) {
    if (!inBounds(state, c.x, c.y)) return err(REJECT.OUT_OF_BOUNDS);
    if (!bool(c.q)) return err(REJECT.MALFORMED);
    const f = decodeFormation(c.f); if (f === null) return err(REJECT.MALFORMED);
    const r = ownUnits(state, owner, c.ids); if (!r.ok) return r;
    cmd.issueMove(r.result, c.x, c.y, !!c.q, f);
    return ok();
  }},

  attackMove: { run(state, owner, c) {
    if (!inBounds(state, c.x, c.y)) return err(REJECT.OUT_OF_BOUNDS);
    if (!bool(c.q)) return err(REJECT.MALFORMED);
    const f = decodeFormation(c.f); if (f === null) return err(REJECT.MALFORMED);
    const r = ownUnits(state, owner, c.ids); if (!r.ok) return r;
    cmd.issueAttackMove(r.result, c.x, c.y, !!c.q, f);
    return ok();
  }},

  holdFormation: { run(state, owner, c) {
    const s = c.s ?? "grid", l = c.l ?? "front";
    if (!FORMATION_SHAPES.includes(s) || !LEADER_POSITIONS.includes(l)) return err(REJECT.MALFORMED);
    const r = ownUnits(state, owner, c.ids); if (!r.ok) return r;
    cmd.issueHoldFormation(r.result, s, l);   // anchor = live centroid, commands.js:377
    return ok();
  }},

  patrol: { run(state, owner, c) {
    if (!Array.isArray(c.pts) || !c.pts.length) return err(REJECT.MALFORMED);
    if (c.pts.length > LIMITS.patrolPoints) return err(REJECT.TOO_MANY);
    for (const p of c.pts) if (!p || !inBounds(state, p.x, p.y)) return err(REJECT.OUT_OF_BOUNDS);
    const r = ownUnits(state, owner, c.ids); if (!r.ok) return r;
    cmd.issuePatrol(r.result, c.pts.map(p => ({ x: p.x, y: p.y })));   // strip any extra keys
    return ok();
  }},

  stop:  { run: (s, o, c) => unitsOnly(s, o, c, us => cmd.issueStop(us)) },
  hold:  { run: (s, o, c) => unitsOnly(s, o, c, us => cmd.issueHold(us)) },
  scout: { run: (s, o, c) => unitsOnly(s, o, c, us => cmd.issueScout(us)) },

  /* ----- targeted ----- */
  attack: { run(state, owner, c) {
    if (!bool(c.q)) return err(REJECT.MALFORMED);
    const t = targetEntity(state, owner, c.target); if (!t.ok) return t;
    const r = ownUnits(state, owner, c.ids);        if (!r.ok) return r;
    cmd.issueAttack(r.result, t.result.id, !!c.q);
    return ok();
  }},

  escort: { run(state, owner, c) {
    if (!bool(c.q)) return err(REJECT.MALFORMED);
    const t = targetEntity(state, owner, c.target); if (!t.ok) return t;
    const r = ownUnits(state, owner, c.ids);        if (!r.ok) return r;
    // inputCommands.js:272 filters the target out of its own escort ring; do the
    // same here so the engine can never be handed a unit escorting itself.
    const units = r.result.filter(u => u.id !== t.result.id);
    if (!units.length) return err(REJECT.EMPTY);
    cmd.issueEscort(units, t.result.id, !!c.q);
    return ok();
  }},

  repair:  { run: (s, o, c) => targeted(s, o, c, (us, id, q) => cmd.issueRepair(us, id, q)) },
  service: { run: (s, o, c) => targeted(s, o, c, (us, id, q) => cmd.issueServiceBuilding(us, id, q)) },

  ferry: { run(state, owner, c) {
    if (!bool(c.q)) return err(REJECT.MALFORMED);
    const t = ownUnit(state, owner, c.target); if (!t.ok) return t;   // your OWN freighter only
    const r = ownUnits(state, owner, c.ids);   if (!r.ok) return r;
    cmd.issueFerryFreighter(r.result, t.result.id, !!c.q);
    return ok();
  }},

  setHomeBase: { run(state, owner, c) {
    const t = ownBuilding(state, owner, c.target); if (!t.ok) return t;
    // The engine never validates ccId is even a building (commands.js:281-287).
    if (t.result.type !== "command") return err(REJECT.MALFORMED);
    const r = ownUnits(state, owner, c.ids); if (!r.ok) return r;
    cmd.issueSetHomeBase(r.result, t.result.id);
    return ok();
  }},

  assistBuild: { run(state, owner, c) {
    if (!bool(c.q)) return err(REJECT.MALFORMED);
    const t = ownBuilding(state, owner, c.target); if (!t.ok) return t;
    if (!t.result.constructing) return err(REJECT.NO_TARGET);
    const r = ownUnits(state, owner, c.ids); if (!r.ok) return r;
    // buildingType comes from the RESOLVED SITE, never from the wire — it is the
    // only thing gating unit eligibility (commands.js:421) and a lying client
    // would otherwise walk a combat unit onto a site the engine refuses.
    cmd.issueAssistBuild(r.result, t.result.id, t.result.type, !!c.q);
    return ok();
  }},

  gather: { run(state, owner, c) {
    if (!bool(c.q)) return err(REJECT.MALFORMED);
    const n = targetNode(state, owner, c.node); if (!n.ok) return n;
    const r = ownUnits(state, owner, c.ids);    if (!r.ok) return r;
    cmd.issueGather(r.result, n.result.id, !!c.q);
    return ok();
  }},

  /* ----- construction ----- */
  build: { run(state, owner, c) {
    if (typeof c.b !== "string" || !BUILDINGS[c.b]) return err(REJECT.MALFORMED);
    if (!inBounds(state, c.x, c.y)) return err(REJECT.OUT_OF_BOUNDS);
    const w = ownUnit(state, owner, c.worker); if (!w.ok) return w;
    // EVERYTHING else — odysseyOnly, canBuildCategory, canAfford, prereqsMet,
    // canPlaceBuilding, payCost — is re-run by the engine against authoritative
    // state at THIS tick (commands.js:396-412). We re-implement none of it.
    const id = cmd.issueBuild(state, w.result.id, c.b, c.x, c.y);
    return id ? ok({ buildingId: id }) : err(REJECT.REFUSED);
  }},

  recycle:       { run: (s, o, c) => entitiesOnly(s, o, c, es => cmd.issueRecycle(es)) },
  cancelRecycle: { run: (s, o, c) => entitiesOnly(s, o, c, es => cmd.issueCancelRecycle(es)) },

  /* ----- toggles ----- */
  setAILogistics: { run(state, owner, c) {
    if (typeof c.on !== "boolean") return err(REJECT.MALFORMED);
    const r = ownUnits(state, owner, c.ids); if (!r.ok) return r;
    cmd.issueSetAILogistics(r.result, c.on, state);   // tech gate is owner-correct at commands.js:298
    return ok();
  }},

  setCollectPoint: { run(state, owner, c) {
    if (typeof c.on !== "boolean") return err(REJECT.MALFORMED);
    const r = ownUnits(state, owner, c.ids); if (!r.ok) return r;
    cmd.issueSetCollectPoint(r.result, c.on);
    return ok();
  }},

  setLogiPriority: { run(state, owner, c) {
    if (!LOGI_PRIORITIES.includes(c.p)) return err(REJECT.MALFORMED);
    const b = ownBuilding(state, owner, c.building); if (!b.ok) return b;
    cmd.issueSetLogiPriority(state, b.result.id, c.p);   // engine has NO owner check (commands.js:330)
    return ok();
  }},

  setRally: { run(state, owner, c) {
    if (!inBounds(state, c.x, c.y)) return err(REJECT.OUT_OF_BOUNDS);
    const b = ownBuilding(state, owner, c.building); if (!b.ok) return b;
    let nodeId = null;
    if (c.node !== undefined && c.node !== null) {
      const n = targetNode(state, owner, c.node); if (!n.ok) return n;
      nodeId = n.result.id;
    }
    cmd.issueSetRally(state, b.result.id, c.x, c.y, nodeId);   // see D2: signature changed
    return ok();
  }},
};

/* ---------- shared shapes ---------- */

function unitsOnly(state, owner, c, fn) {
  const r = ownUnits(state, owner, c.ids); if (!r.ok) return r;
  fn(r.result); return ok();
}
function entitiesOnly(state, owner, c, fn) {
  const r = ownEntities(state, owner, c.ids); if (!r.ok) return r;
  fn(r.result); return ok();
}
function targeted(state, owner, c, fn) {
  if (!bool(c.q)) return err(REJECT.MALFORMED);
  const t = targetEntity(state, owner, c.target); if (!t.ok) return t;
  const r = ownUnits(state, owner, c.ids);        if (!r.ok) return r;
  fn(r.result, t.result.id, !!c.q); return ok();
}

/* ============================================================
   PUBLIC API
   ============================================================ */

/** Client side: stamp an envelope around a WireCommand. No engine access. */
export function encode(command, seq, clientTick) {
  return { v: PROTOCOL_VERSION, seq, tick: clientTick, cmd: command };
}

/** Server side: envelope shape only. Does NOT touch game state — this runs on
 *  ARRIVAL, so a malformed packet is dropped before it can be scheduled. */
export function decode(envelope) {
  if (!envelope || typeof envelope !== "object") return err(REJECT.MALFORMED);
  if (envelope.v !== PROTOCOL_VERSION) return err(REJECT.BAD_VERSION);
  if (!Number.isInteger(envelope.seq) || envelope.seq < 0) return err(REJECT.MALFORMED);
  const c = envelope.cmd;
  if (!c || typeof c !== "object" || typeof c.t !== "string") return err(REJECT.MALFORMED);
  if (c.t === "batch") {
    if (!Array.isArray(c.c) || !c.c.length || c.c.length > LIMITS.batch) return err(REJECT.TOO_MANY);
    for (const sub of c.c) {
      if (!sub || typeof sub.t !== "string" || sub.t === "batch") return err(REJECT.MALFORMED);
      if (!SCHEMA[sub.t]) return err(REJECT.UNKNOWN_TYPE);
    }
    return ok(c);
  }
  if (!SCHEMA[c.t]) return err(REJECT.UNKNOWN_TYPE);
  return ok(c);
}

/** Server side: apply ONE validated command against live state, as `owner`.
 *  Runs at the scheduled tick, immediately before tick(state, dt). */
export function apply(state, owner, command) {
  if (command.t === "batch") {
    // Atomic on VALIDATION: a batch is one client gesture resolved against one
    // observed state (inputCommands.js:90-96 fans a right-click into two calls).
    // If any member is invalid the client's disambiguation was wrong, so none apply.
    const results = [];
    for (const sub of command.c) {
      const r = SCHEMA[sub.t].run(state, owner, sub);
      if (!r.ok) return r;
      results.push(r.result);
    }
    return ok(results);
  }
  const entry = SCHEMA[command.t];
  if (!entry) return err(REJECT.UNKNOWN_TYPE);
  return entry.run(state, owner, command);
}

export const COMMAND_TYPES = Object.keys(SCHEMA);
```

**Note the batch caveat.** A batch validates-then-applies member by member, so a
member that fails *after* an earlier one already mutated state is not rolled
back. That is acceptable for the only batch we actually generate
(`aggressiveMove`'s two disjoint sub-selections, `inputCommands.js:94-95`), where
member 2's validity does not depend on member 1. If a future batch needs true
atomicity, validate all members against a dry-run resolver first, then apply —
but do not build that until something needs it.

---

## 5. Determinism of application order

### 5.1 The ordering rule

Commands arrive out of order from N clients over N sockets. The authoritative
total order is:

```
sort key = (applyTick, ownerIndex, seq)

  applyTick   integer, stamped by the server at admission (§5.2)
  ownerIndex  state.owners.indexOf(owner)  -- engine/state.js:227,
              "the world's side ids, in canonical iteration order"
  seq         the client's per-connection monotonic counter
```

This is a **total** order: `(owner, seq)` is unique by construction (duplicates
are dropped idempotently at admission), so no two records ever tie.

**Why `ownerIndex` and not arrival time.** Arrival time is wall clock; the
engine-purity guard forbids wall clock in the sim
(`test/engine-purity.test.js:16` bans `Date.now`), and more importantly a replay
must not depend on network jitter. `state.owners` is a stable, seed-independent
array that already drives every other owner-generic loop in the engine
(`state.js:269-270`, `sim.js`, `victory.js`).

**Why `seq` and not a content hash.** `seq` preserves the *client's own* intent
order, which is load-bearing: a player who queues `move` then `attackMove` on the
same units in the same tick means something different from the reverse.

**Fairness note.** `ownerIndex` gives seat 0 a systematic advantage in the rare
case of two players issuing conflicting commands in the same tick (e.g. both
right-clicking the last unclaimed node). This is a known, accepted asymmetry in
every lockstep RTS and is far smaller than the network jitter it replaces. If it
ever matters, rotate the ownerIndex offset by `applyTick % owners.length` — but
do not do this speculatively; it makes replay logs harder to reason about.

### 5.2 Where the tick stamp comes from

**The server stamps it. The client's `tick` field is never trusted.**

```js
const INPUT_DELAY_TICKS = 3;   // 150ms at 20Hz — covers typical RTT + jitter
applyTick = state.tick + INPUT_DELAY_TICKS;
```

Because the architecture is **server-authoritative** (not peer lockstep), the
server does not need clients to agree on a future tick — it only needs the choice
to be *recorded*. The stamp depends on wall-clock arrival, which is
nondeterministic during the live match but is written into the log, so replay
from the log is exact (§7). This is strictly simpler and more robust than
honouring a client-proposed tick, which requires rejecting late commands and
opens a "schedule everything at tick+1000" griefing vector.

`INPUT_DELAY_TICKS` exists so a command is visible to every spectator/relay
before it lands, and so the server can batch a tick's worth of input into one
sorted list. Set it to 0 and the protocol still works; set it to 3 and the
spectator stream can stay a whole tick behind the sim without stuttering.

### 5.3 Where in the loop

```js
/* server/matchLoop.js — the ONLY place a wire command reaches the sim. */
import { tick } from "../engine/sim.js";
import { apply } from "../net/commandCodec.js";

function ownerIndex(state, owner) { return state.owners.indexOf(owner); }

/** Pull every command scheduled at or before `state.tick`, order it, apply it,
 *  append it to the log, THEN advance the sim by one fixed step. */
export function stepMatch(match, dt) {
  const { state, pending, log } = match;

  const due = pending.filter(r => r.applyTick <= state.tick);
  if (due.length) {
    // A command whose tick has already passed (a slow admission, a resumed
    // socket) still lands here rather than being dropped — but it sorts by its
    // ORIGINAL applyTick, so the log stays monotonic and the replay is exact.
    due.sort((a, b) =>
      a.applyTick - b.applyTick ||
      ownerIndex(state, a.owner) - ownerIndex(state, b.owner) ||
      a.seq - b.seq);
    for (const rec of due) {
      const res = apply(state, rec.owner, rec.cmd);
      rec.result = res.ok ? res.result : { rejected: res.code };
      rec.appliedAtTick = state.tick;   // == applyTick in the normal case
      log.push(rec);
      match.emitAck(rec);
    }
    match.pending = pending.filter(r => r.applyTick > state.tick);
  }

  tick(state, dt);          // <- the sim advances AFTER every command for this tick
}
```

**Why before `tick`, never inside it.** `tick(state, dt)` opens with
`runAI(state, dt)` (`engine/sim.js:39-40`), which issues its own orders through
the same `issue*` functions. In single-player, DOM input handlers fire between
`update()` calls (JS is single-threaded; `createLoop`'s `update(dtFixed)` at
`engine/loop.js:55` runs to completion). So "commands land between ticks, before
the AI thinks" is *exactly* the existing single-player ordering. Applying them
mid-tick — e.g. after `runAI` but before movement — would be a behavioural change
with no justification, and would break the ability to validate the netcode path
against `tools/selfplay.js`.

**Rejected commands are logged too.** A rejection is a fact about the match
(anti-cheat forensics, and a spectator needs to know why nothing happened). It
carries no state mutation, so it does not affect replay — but it must be
*present* in the log for the log to be auditable.

### 5.4 The fixed step

The server must pick one `dt` and never change it. `tools/selfplay.js:42-57`
documents in detail why: *"A fixed step IS the simulation… dt 0.1 ended 'ai' by
elimination at 1138 s, dt 0.05 ended 'player' by elimination at 1686 s — opposite
winners."*

**Recommendation: `dt = 0.05` (20 Hz), matching `createLoop`'s default
(`engine/loop.js:34`) and ordinary play.** `SELFPLAY_DT = 0.1` exists for
throughput on the AI bench, not for fidelity. Record the chosen `dt` in the match
header (§7) so a replay cannot be run at the wrong step.

---

## 6. `state.selection`

### 6.1 Who reads it — the grep

`state.selection` is declared at `engine/state.js:231` as
`selection: []  // unit/building ids currently selected by the human player`, and
typed at `engine/types.js:335`.

**Readers — all UI, none in the sim:**

| File | Lines |
|---|---|
| `inputCommands.js` | `103`, `147`, `150`, `152`, `154`, `157`, `177`, `195`, `196`, `206` |
| `renderEffects.js` | `544`, `561`, `562`, `598`, `635` |
| `hudSelection.js` | `76` (and the whole panel-signature system downstream) |
| `render.js` | `132` |
| `techChart.js` | `258` |
| `boot.js` | `223` |

**Writers inside `engine/`:**

| File | Line | What |
|---|---|---|
| `engine/state.js` | `347` | `removeEntity` prunes the dead id out of `state.selection` |
| `engine/galaxy.js` | `1422` | `from.selection = []; dest.selection = []` on an interplanetary jump |

**No file under `engine/` ever READS `state.selection`.** It is written
defensively (so the UI never holds a dangling id) and read only by the client.
The brief's premise is confirmed.

### 6.2 Where it must move — and what stays

**Decision (D6): selection is per-client UI state and moves to the client
session. The `State` field stays, permanently empty, on the server.**

- **Client** (browser): `client/session.js` grows `selection: string[]`, owned by
  the input layer. `inputCommands.js`'s `applyBoxSelection` / `selectedUnits` /
  `commandAt` read it from there instead of from `state`. Every one of those call
  sites is already local to the client — this is a find-and-replace, not a
  redesign.
- **MCP agent**: an agent has no pointer and no box-select. Its "selection" is
  whatever id array it puts in a command. The MCP server should expose a
  *convenience* selection in the agent session (so an agent can say "select all
  my Lancers, then attack-move") but it must be an MCP-server concept, never a
  sim concept, and it must be re-validated by the codec on every command anyway.
- **Server**: `state.selection` stays as `[]` forever. Do **not** delete the
  field. `removeEntity` (`state.js:345-348`) is on the hot path of every death in
  the game; making it conditional, or removing the line, means touching
  `engine/state.js`, `engine/galaxy.js:1422`, `engine/types.js:335`, the
  persistence layer and any test that asserts on selection pruning — for a
  saving of one array filter over an always-empty array. Not worth it.

**Guard test:** assert that no file under `server/` or `net/` contains
`state.selection`, using the same directory-walk idiom as
`test/engine-purity.test.js:35-52`. That converts D6 from a convention into an
enforced invariant.

**One subtlety that must be carried across:** selection *order* is game input
(§3.3). `applyBoxSelection`'s Ctrl-click promote-to-front
(`inputCommands.js:150-152`) is how a player picks a formation leader. When
selection moves client-side, that ordering must still be what the client puts in
`cmd.ids` — otherwise leaders silently change and formations break.

---

## 7. Replay & spectator

### 7.1 Can a seed + ordered command log replay the match exactly?

**Yes — after B1 in §8 is fixed. Not before.**

The engine is built for this. `engine/rng.js:5-6` states the sim uses *"NO other
randomness (a determinism-guard test enforces it), so 'same seed ⇒ same game'"*,
`test/engine-purity.test.js:16` bans `Math.random`/`Date.now`/`performance.now`
across `engine/`, and `test/determinism.test.js:22-29` proves 2500 ticks replay
byte-identically from one seed.

### 7.2 What a replay file must capture

```jsonc
{
  "replayVersion": 1,
  "engineCommit": "50ceb88",              // MUST match; balance changes invalidate a replay
  "protocolVersion": 1,

  "sim": {
    "dt": 0.05,                            // §5.4 — a different step is a DIFFERENT GAME
    "createGameState": {                   // every argument of engine/state.js:154
      "planetId": "ferros",
      "seed": 12345,                       // feeds mulberry32 (engine/rng.js:24)
      "sizeMult": 1, "resourceMult": 1, "swapAsym": false,
      "matchTimeLimit": null, "popCap": null, "endless": false,
      "difficulty": "medium", "aiArchetype": null,
      "playerFaction": "…", "aiFaction": "…"
    },
    "postCreate": [                        // mutations applied AFTER createGameState returns
      { "fn": "seedDifficultyEdge", "owner": "p1" },   // engine/state.js:299
      { "fn": "createAiController", "owner": "p3", "opts": { "apm": 120, "micro": true,
                                                             "strategy": "default",
                                                             "difficulty": "hard",
                                                             "archetype": "…" } }
    ]
  },

  "seats": [ { "owner": "p1", "kind": "human",  "label": "alma" },
             { "owner": "p2", "kind": "agent",  "label": "mcp:claude-1" },
             { "owner": "p3", "kind": "ai",     "label": "scripted" } ],

  "commands": [ /* log records from §3.1, already in (applyTick, ownerIndex, seq) order */ ],

  "checkpoints": [ { "tick": 200,  "fp": "…" },   // tools/selfplay.js:157 fingerprint()
                   { "tick": 400,  "fp": "…" } ],

  "outcome": { "tick": 18342, "winner": "p1", "winReason": "elimination" }
}
```

### 7.3 What is easy to forget — and fatal if forgotten

1. **`dt`.** Covered above. Put it in the header and refuse to replay without it.
2. **Every `createGameState` option, not just the seed.** `sizeMult`,
   `resourceMult` and `swapAsym` all feed `generateMap` (`state.js:161-165`) and
   change the world.
3. **Post-`createGameState` mutations.** `seedDifficultyEdge` (`state.js:299`)
   writes `players[owner].upgrades.hardEdge` *after* construction, and
   `state.playerAi` is *"populated after createGameState, never by it"*
   (`types.js:340-341`). A replay that only records constructor args reproduces a
   different world. `tools/selfplay.js:36` already imports all three functions for
   exactly this reason — copy that pattern.
4. **AI seat configuration.** `{apm, micro, strategy, difficulty, archetype}` per
   AI seat (`tools/selfplay.js:69-74`). The scripted AI is a *player* in a replay
   and its dials are inputs.
5. **The rejected commands.** Keep them; they are audit evidence and they cost
   nothing to replay (they no-op).
6. **The engine commit.** A balance tweak in `entities.js` silently invalidates
   every stored replay. Refuse to replay across a commit mismatch rather than
   producing a plausible lie.
7. **Periodic fingerprints.** Reuse `fingerprint(state)`
   (`tools/selfplay.js:157-169`) verbatim — it already covers units (id, type,
   owner, x, y, hp, order type), buildings, per-owner resources, fog totals, both
   AI controllers, `tick`, `time`, `over`, `winner`. Store one every N ticks. On
   replay, a mismatch localises the divergence to an N-tick window instead of
   "somewhere in 20 minutes". For live play, comparing the server fingerprint
   against a client's own prediction is the desync canary.
   *Note:* `test/determinism.test.js:9-15` warns that a *weaker* local snapshot
   once masked real drift, and `test/_helpers.js`'s `entitySnapshot` is the
   stronger one. For stored checkpoints, prefer `entitySnapshot`; `fingerprint`
   is the cheap live variant.

### 7.4 Spectator

A spectator is a replay consumer with a live tail: subscribe to the same ordered
command stream plus periodic `entitySnapshot` keyframes, and run the identical
`stepMatch` loop locally. That gives full-fidelity spectating at command
bandwidth (a few hundred bytes/sec) rather than state bandwidth.

**Fog is the catch.** A spectator running the real sim has the *whole* state,
including every player's fog. Client-side fog filtering is not a security
boundary. Two honest options:

- **Deferred spectating** (recommended for v1): spectators are N seconds behind
  and receive the *stream*, but the relay withholds commands whose subject is not
  yet visible to the spectator's chosen POV. Simple, and matches how most RTS
  observers work.
- **Server-rendered POV**: the server maintains one fog-filtered state view per
  spectator POV and ships deltas. Correct, but expensive and a much bigger build.

Do not ship "full state, hidden by the client" — in a competitive ladder that is
a maphack with extra steps.

---

## 8. Blockers found — fix before the codec ships

### B1 — `nextEntityId` is a module-global (**critical**)

`engine/state.js:23-24`:

```js
let nextEntityId = 1;
function newId(prefix) { return `${prefix}${nextEntityId++}`; }
```

reset at `createGameState` (`state.js:155`). The comment at `state.js:17-22`
reasons that *"IDs are only ever compared within one state's own Maps, so two
live games sharing id strings is harmless"* — **true for two games, false for two
games in one process.** A single Node server hosting concurrent matches will
interleave `newId` calls across matches, so match A's units are minted
`u57, u59, u62…` depending on what match B did. Entity ids feed the
deterministic tie-breaks in movement/separation/gather/`rankSlotsByRange`
(`commands.js:105` sorts by `a.id < b.id`), so **the same seed and the same
command log produce a different match** depending on what else the server was
hosting. Replay, spectating and any ladder rating built on them are all invalid.

Worse, `createGameState` *resets* the counter to 1 — so starting match B
mid-match A makes A start minting ids that collide with its own live entities.

**Fix (small, surgical):** move the counter onto the state. Either
`state.nextEntityId` with `makeUnit`/`makeBuilding` taking `state`, or a
per-match id-minter closure passed into `createGameState`. The existing
`peekEntityId`/`restoreEntityId` pair (`state.js:29-31`) shows persistence already
treats it as per-game state — this makes that real. Guard with a test that two
interleaved `createGameState` runs each replay identically.

**Until this is fixed, run one match per Node process (worker/child process per
match).** That is a legitimate v1 shipping posture on a Hugging Face Space and
sidesteps B1 entirely — but write it down as a constraint, not an accident.

### B2 — formations are gated on `owner === "player"` (**critical**)

`engine/commands.js:155` (§1.4). In a multi-seat match no owner is literally
`"player"`, so `dispatchFormation` takes the AI branch for everyone and the
leader/follower squad system silently disappears.

**Fix:** replace the literal test with a state-level predicate — e.g.
`state.seats[owner]?.kind !== "ai"`, or a `humanControlled` flag set at match
creation. The comment block at `:147-154` explains the intent precisely ("there's
no analogous 'the unit you built a selection around' concept for the scripted
AI"), so the predicate is *seat kind*, not owner name. Small change, but it
changes AI-vs-AI fingerprints if done carelessly — gate it so the existing
`"player"`/`"ai"` two-owner world behaves byte-identically.

### B3 — `tick` hardcodes two fog owners (**high**)

`engine/sim.js:70-71`:

```js
updateFog(state, state.fog, "player");
updateFog(state, state.fogAI, "ai");
```

`state.fogs` is already a per-owner map (`state.js:189`, `types.js:336`) and
`createGameState` iterates `owners` correctly (`state.js:269-270`) — but the tick
loop does not. Seats 3+ get no fog updates at all. Fix by iterating
`state.owners`. `test/ownerScaffold.test.js` exists and is the right place to
extend. (`engine/victory.js`, `engine/diplomacy.js` and `engine/galaxy.js` carry
similar two-owner assumptions — worth a dedicated audit, out of scope here.)

### B4 — `recycle.js`'s ownership comment is false (**doc bug, real risk**)

`engine/recycle.js:87-89` claims `issueRecycle` checks ownership. It does not
(`commands.js:444-450`). Fix the comment when the codec lands, or a future reader
will build on a guarantee that isn't there.

### B5 — explicit attack orders are friendly-fire capable (**medium**)

`engine/combat.js:46` takes `unit.order.targetId` with no owner filter and reaches
`performAttack` (`:85`) without one, while every *auto*-acquisition path does
filter (`:153`, `:243`, `:386`, `:411`). Harmless in single-player (the UI never
offers it, `inputCommands.js:247-251`). In multiplayer it is a team-griefing
vector and an own-goal footgun. Decide deliberately: either add the filter in the
codec (reject `attack` on a target whose owner is the submitter or an ally), or
in `combat.js`. **Recommend the codec** — keeping the engine byte-identical
protects the determinism baseline, and "can I shoot my ally" is a *rules* question
that belongs with the other rules the codec owns.

---

## 9. TDD hooks (the repo's house style)

The source repo is strict TDD with 2519 tests and a determinism guard. Land the
codec the same way:

| Test file | Asserts |
|---|---|
| `test/net-boundary.test.js` | Only `net/commandCodec.js` imports `engine/commands.js` from outside `engine/`. Directory-walk idiom from `engine-purity.test.js:35-52`. |
| `test/commandCodec-ownership.test.js` | For **every** entry in `COMMAND_TYPES`, a command naming another owner's entity returns `NOT_OWNER` and mutates nothing. Table-driven over `COMMAND_TYPES` so a new command type cannot be added without an ownership test. |
| `test/commandCodec-fog.test.js` | Foreign unit not visible ⇒ `NOT_VISIBLE`; foreign building explored-but-not-visible ⇒ allowed; undiscovered node ⇒ `NOT_VISIBLE`. |
| `test/commandCodec-schema.test.js` | Round-trip `encode`→`decode`; unknown type, bad version, oversized ids/pts/batch all rejected; **`ids` order is preserved** (the D4 guard). |
| `test/commandCodec-parity.test.js` | Driving a match through the codec produces the byte-identical `entitySnapshot` as driving the same orders through `issue*` directly. This is the proof that wrapping changed nothing. |
| `test/replay.test.js` | Seed + logged commands replay to an identical `entitySnapshot`; a one-tick shift in any `applyTick` diverges (proving the guard is real, mirroring `determinism.test.js:43-47`'s "different seeds diverge" check). |
| `test/matchLoop-order.test.js` | Commands submitted in scrambled arrival order apply in `(applyTick, ownerIndex, seq)` order; duplicate `(owner, seq)` is idempotent. |

---

## 10. Summary of recommendations

1. **Wrap `engine/commands.js` behind `net/commandCodec.js`.** Do not make the
   engine id-based. (§4.1)
2. **One engine signature change:** `issueSetRally(state, buildingId, x, y, nodeId)`. (§4.2)
3. **Server stamps `owner` and `applyTick`.** Never trust either from the client. (§3.1, §5.2)
4. **Order is `(applyTick, ownerIndex, seq)`; apply immediately before `tick(state, dt)`.** (§5)
5. **`ids` arrays are ordered input — never sort them.** (§3.3, D4)
6. **Add fog gating in the codec** — it exists nowhere in the engine. (§2.4, §3.5)
7. **`state.selection` moves to the client session; the field stays empty on the server.** (§6)
8. **Fix B1 (`nextEntityId`) before any concurrent hosting**, or run one match per
   process until it is fixed. (§8)
9. **Fix B2 (`owner === "player"` formation gate)** or multiplayer ships without
   formations. (§8)
10. **Cover both intent surfaces.** `engine/commands.js` is phase 1; the ~20
    cost-bearing mutators the HUD calls directly (`hudSelection.js:20-35`) are
    phase 2, through the same codec. (§1.6, §3.6)