station-master/src/engine/events.ts

/**
 * Events — protocol.md §3.
 *
 * An event is a FACT: ordered, append-only, and standalone. Events NARRATE the game — they drive the
 * log, the sounds and the replay's captions.
 *
 * THEY DO NOT RECONSTRUCT IT. This header claimed `state = fold(events)` until v0.4.0 and it was
 * never true. `applyIntent` does go through `reduce`, but the phase driver in `advance.ts` mutates
 * state and THEN emits a descriptive event, so fourteen of the forty-six types below are never
 * reduced — the clock, and the whole Mainline phase, which is every train movement in the game.
 *
 * The canonical record is `{ seed, history: Intent[] }`, replayed by `fromSave`. That is what save,
 * restore, undo, restart recovery and post-game replay all run on. See
 * `docs/architecture/protocol.md` §3, and `test/events.test.ts`, which pins the unreduced set so
 * that closing the gap is a deliberate act rather than a surprise.
 *
 * DESIGN RULE (overview.md, post-game replay): events must render STANDALONE. Carry the from/to,
 * not just an id the renderer has to resolve against live state — otherwise a replay viewer has to
 * reconstruct the whole board to draw one frame.
 */

import type { CarType, OfficeTier } from './content.ts';
import type { LocalOpsOption } from './intents.ts';
import type { CardId, GridCoord, PlayerIndex, RollingStock, TrayId } from './state.ts';

export type GameEvent =
  // -- clock
  | { type: 'stageBegan'; day: number; stage: number }
  | { type: 'phaseBegan'; phase: string }
  | { type: 'actorChanged'; player: PlayerIndex | null }
  // -- local operations
  | { type: 'localOpsOptionChosen'; player: PlayerIndex; option: LocalOpsOption }
  | { type: 'trayMoved'; trayId: TrayId; from: GridCoord; to: GridCoord; movesRemaining: number; facing?: 'n' | 's' | 'e' | 'w' }
  | {
      type: 'carsCoupled';
      trayId: TrayId;
      at: GridCoord;
      stock: RollingStock[];
      /** The cards the cars were lifted from — the ones the crew actually ran over. */
      from: GridCoord[];
      /**
       * Coupled onto the ENGINE'S NOSE rather than behind the train (§A.3). True when the crew was
       * running forward: the engine meets the cars head-on and takes them on the front.
       */
      toNose: boolean;
    }
  | { type: 'carsDropped'; trayId: TrayId; at: GridCoord; stock: RollingStock[]; fromNose?: boolean }
  | { type: 'consistSorted'; trayId: TrayId; at: GridCoord; before: RollingStock[]; after: RollingStock[] }
  | { type: 'cardDrawn'; player: PlayerIndex; source: 'homeOffice' | 'department'; slot?: number; cardId: CardId }
  /**
   * §6.2 — the Home Office deck ran out, so the Salvage Yard and all three Department decks were
   * collected, reshuffled, and dealt back out as a fresh deck plus three face-up Departments.
   *
   * The full shuffled `order` rides the event rather than being recomputed from `rngState`. A save
   * is a seed plus the intents, so events are never serialised and the size costs nothing — and an
   * event that states the outcome outright cannot drift from the reducer the way a re-derivation
   * can. `rngState` still rides along so the next roll follows on.
   */
  | { type: 'deckReshuffled'; order: CardId[]; rngState: number }
  /** `variant` is the chosen orientation (Gap 11); it must be replayable, so it rides the event. */
  | { type: 'cardPlayed'; player: PlayerIndex; cardId: CardId; placement?: GridCoord; variant?: number }
  | { type: 'mainlineModified'; player: PlayerIndex; cardId: CardId; node: number; key: string; became?: string }
  | { type: 'redFlagsSet'; player: PlayerIndex; cardId: CardId; trayId: TrayId; node: number }
  | {
      type: 'trainsDestroyed';
      player: PlayerIndex;
      trains: { label: string; consist: RollingStock[] }[];
      reason: string;
      where: string;
    }
  | { type: 'flyingSwitch'; player: PlayerIndex; cardId: CardId; trayId: TrayId; to: GridCoord; stock: RollingStock[] }
  | { type: 'officeUpgraded'; player: PlayerIndex; from: OfficeTier; to: OfficeTier }
  | { type: 'cardDiscarded'; player: PlayerIndex; cardId: CardId; toSlot: number }
  | { type: 'departmentRefilled'; slot: number; cardId: CardId }
  // -- freight agent
  | { type: 'stockToOutbound'; player: PlayerIndex; at: GridCoord; stock: RollingStock }
  | { type: 'inboundCleared'; player: PlayerIndex; at: GridCoord; stock: RollingStock }
  | { type: 'facilityUnjammed'; player: PlayerIndex; at: GridCoord; from: string; stock: RollingStock }
  // -- trains
  /**
   * §7 — a Timetabled Train card played from hand is scheduled by a 1D12 roll. `rngState` carries
   * the advanced RNG so that folding events reproduces the draw exactly.
   */
  | { type: 'trainScheduled'; player: PlayerIndex; trainNumber: number; roll: number; slot: number; rngState: number }
  /**
   * Train lifecycle. These were originally squeezed into `phaseBegan` with a free-text label,
   * which made the replay say "New Train" and nothing else. A train being made up, departing,
   * arriving or finishing its run are four distinct facts and deserve four event types.
   */
  /**
   * `at` is a square in the Office Area; `node` is a Division node, for an Enhancement that goes on
   * a Mainline card. Exactly one is set — see `card.play` in intents.ts for why they are not one
   * field wearing a sentinel.
   */
  | { type: 'enhancementPlaced'; player: PlayerIndex; key: string; at?: GridCoord; node?: number }
  | { type: 'extraQueued'; player: PlayerIndex; trainNumber: number }
  | { type: 'secondSectionOrdered'; player: PlayerIndex; trainNumber: number }
  | { type: 'trainMadeUp'; trainNumber: number; isExtra: boolean; at: string; direction: string }
  | { type: 'trainHeld'; trainNumber: number; reason: string }
  /** A train whose card pays for standing still (X18 Circus) collected on it. */
  | { type: 'trainStoodStill'; trainNumber: number; where: string }
  | { type: 'trainHighballed'; trainNumber: number; from: string; to: string }
  /**
   * `expedited` because it changes what the player must do RIGHT NOW. Q3 — an expedited train
   * departs the same Stage it arrives, so there is no Local Operations turn in which to work it;
   * every other train stands until the next Mainline Phase and can be switched in between.
   */
  | { type: 'trainArrived'; trainNumber: number; consist: RollingStock[]; office: string; expedited: boolean }
  | { type: 'trainDiverted'; trainNumber: number; to: string; reason: string }
  /**
   * The train ran the length of the Division and left it. `side` is the Division Point it left by,
   * which is what the announcement needs — and every player scores 1 for it, so this event is
   * always followed by one `revenueChanged` per player.
   */
  | { type: 'trainCompleted'; trainNumber: number; isExtra: boolean; side: 'east' | 'west'; consist: RollingStock[] }
  | { type: 'carPlacedOnTrain'; player: PlayerIndex; trayId: TrayId; stock: RollingStock }
  | { type: 'carPassed'; player: PlayerIndex; trayId: TrayId }
  | { type: 'dispatchBonusUsed'; key: string; bonus: number; trainNumber: number; againstTrain: number }
  | { type: 'clearanceRequested'; trainId: TrayId; occupiedBy: TrayId }
  | { type: 'clearanceGiven'; trainId: TrayId; allow: boolean }
  // -- load / unload
  | { type: 'passengersBoarded'; player: PlayerIndex; at: GridCoord }
  | { type: 'passengersDetrained'; player: PlayerIndex; at: GridCoord }
  | { type: 'loadStarted'; player: PlayerIndex; at: GridCoord; carType: CarType }
  | { type: 'loadAdvanced'; player: PlayerIndex; at: GridCoord; fromBox: number; toBox: number }
  | { type: 'unloadCompleted'; player: PlayerIndex; at: GridCoord; carType: CarType }
  | { type: 'loadCompleted'; player: PlayerIndex; at: GridCoord; carType: CarType }
  | { type: 'unloadBegan'; player: PlayerIndex; at: GridCoord; carType: CarType }
  // -- consequences
  | { type: 'revenueChanged'; player: PlayerIndex; delta: number; total: number; reason: string }
  | { type: 'phaseEnded'; player: PlayerIndex; phase: string };

export type EventType = GameEvent['type'];