v0.3.0 — playtest fixes, two new rules, and §7 enforced

src/engine/advance.ts

@@ -39,7 +39,7 @@ import type { GameEvent } from './events.ts';
 import { areaOf, trainNeedingCars } from './apply.ts';
 import { legalActions } from './legal.ts';
 import type { CrewTray, DivisionNode, GameState, PlayerIndex, RollingStock, TrayId } from './state.ts';
-import { coordKey, freshTurn, totalRevenue } from './state.ts';
+import { coordKey, freshTurn, subdivisions, totalRevenue } from './state.ts';
 
 export type AdvanceResult = {
   events: GameEvent[];
@@ -457,8 +457,19 @@ function spendDispatchBonus(
 }
 
 /** Q3 — an expedited train does not spend a Stage standing at the Office. */
+/**
+ * Does this train leave in the same Stage it arrives (§7)?
+ *
+ * Two ways to earn it. `expedite` is printed and permanent. `stopThenExpedite` is the X17 Campaign
+ * Train — "one turn at station (speeches) then expedite": its FIRST arrival is an ordinary stop while
+ * the speeches are made, and every arrival after that is expedited. `speechMade` is set on that first
+ * stop, so the train is slow once and fast thereafter.
+ */
 function isExpedited(tray: CrewTray): boolean {
-  return trainProfile(tray.trainNumber ?? 0, tray.trainIsExtra)?.rules.expedite === true;
+  const rules = trainProfile(tray.trainNumber ?? 0, tray.trainIsExtra)?.rules;
+  if (!rules) return false;
+  if (rules.expedite) return true;
+  return rules.stopThenExpedite === true && tray.speechMade === true;
 }
 
 function moveTrain(
@@ -540,11 +551,22 @@ function moveTrain(
         from: 'the Office',
         to: 'the Mainline',
       });
+      awardDeparture(s, owner, tray, events);
       return 'moved';
     }
 
+    /**
+     * CURRENTLY UNREACHABLE, and kept correct rather than deleted.
+     *
+     * `buildDivision` always lays `DP · Mainline · Office · Mainline · … · DP`, so an Office is never
+     * adjacent to a Division Point and this branch cannot be entered at any player count. It is left
+     * in — with the departure paid, so it would behave — because the layout is a setup decision that
+     * could reasonably change, and a branch that silently failed to score would be hard to spot.
+     * `setup.test.ts` asserts the flanking invariant that makes this dead.
+     */
     if (node.kind === 'divisionPoint') {
       area.adOccupancy = area.adOccupancy.filter((t) => t !== id);
+      awardDeparture(s, owner, tray, events);
       retireTrain(s, id, tray, events);
       return 'moved';
     }
@@ -668,11 +690,32 @@ function evaluateClearance(
   const profile = MAINLINE_PROFILES.find((m) => m.kind === node.card);
   if (profile?.trainsMayPass) return 'clear';
 
-  for (const t of node.transits) {
-    const other = t.tray;
-    if (!other || other === id) continue;
+  /**
+   * §8.1 asks about the next SUBDIVISION, not the next card.
+   *
+   * "If there is a train in the next Subdivision moving towards the considered train, the considered
+   * train will not depart" — and the same for a following train. This used to inspect only
+   * `node.transits`, the one card being entered, so a train ran headlong into a Subdivision an
+   * opposing train was two cards deep in and was stopped only on the Stage they met. `subdivisions()`
+   * had existed for this the whole time and was called by nothing outside a test.
+   *
+   * It bites hardest early: every Office starts as a Whistle Post, so the entire railroad is ONE
+   * Subdivision until someone upgrades, which is exactly why §8 describes early traffic as
+   * constrained. Each Office upgrade to a Control Point splits one in two and buys capacity.
+   */
+  const subdivision = subdivisions(s).find((group) => group.includes(targetIndex)) ?? [targetIndex];
+  const occupants: { tray: TrayId; onCard: number }[] = [];
+  for (const i of subdivision) {
+    const n = s.division.nodes[i];
+    if (!n || n.kind !== 'mainline') continue;
+    for (const t of n.transits) if (t.tray) occupants.push({ tray: t.tray, onCard: i });
+  }
+
+  for (const { tray: other, onCard } of occupants) {
+    if (other === id) continue;
     const otherTray = s.trays.get(other);
     if (!otherTray) continue;
+    const onNode = s.division.nodes[onCard];
 
     if (otherTray.direction !== tray.direction) {
       // §8.1 — a train moving TOWARDS the considered train is an absolute bar. That stands.
@@ -688,12 +731,16 @@ function evaluateClearance(
     // Red Flags — "a stopped train is prevented from being hit; the approaching train is prevented
     // from moving". Flagging is per-train rather than per-card, so it protects one specific train
     // where ABS Signals protects everything on the card.
-    if ((node.redFlagged ?? []).includes(other)) return 'blocked';
+    //
+    // Both of these now read the card the OTHER train is standing on rather than the card being
+    // entered. They were the same card while this only looked one card ahead; across a Subdivision
+    // they are not, and the protection belongs where the train it protects actually is.
+    if (onNode?.kind === 'mainline' && (onNode.redFlagged ?? []).includes(other)) return 'blocked';
 
     // ABS Signals — "trains on this card will not rear-end each other; they stop short of a
     // collision". With signals in place a following train simply holds, and the Superintendent has
     // no judgment call to make. This is the amendment to Gap 2's unconditional collisions.
-    if (node.absSignals) return 'blocked';
+    if (onNode?.kind === 'mainline' && onNode.absSignals) return 'blocked';
 
     // Same direction — the Superintendent must rule (§8.1, fourth condition).
     s.clock.pendingDecision = { train: id, occupiedBy: other };
@@ -786,6 +833,14 @@ function arriveAtOffice(
   // Q3 — an expedited train departs in the same Stage it arrived, so it is NOT added to
   // movedThisPhase and gets a second chance to move before the phase ends.
   if (isExpedited(tray)) return 'expedited';
+  /**
+   * X17 Campaign Train — the speeches happen at the first Office it reaches. Recorded AFTER the
+   * expedite test above, so this arrival is the ordinary stop the card pays for and every later one
+   * runs expedited.
+   */
+  if (trainProfile(tray.trainNumber ?? 0, tray.trainIsExtra)?.rules.stopThenExpedite) {
+    tray.speechMade = true;
+  }
   return 'moved';
 }
 
@@ -839,6 +894,42 @@ function collide(
 }
 
 /** A completed run frees the crew; Extras go to the Salvage Yard (§2.3, Gap 2c). */
+/**
+ * ONE REVENUE FOR EVERY TRAIN THAT GETS OUT OF YOUR SECTION.
+ *
+ * Jesse's rule. Unlike freight and passengers it pays for traffic the player does not have to work —
+ * which is the point: keeping the line clear is the Superintendent's job, and until now nothing paid
+ * for doing it well. It rewards splitting a Subdivision with a Control Point, holding a following
+ * train rather than gambling on it, and building the A/D capacity to turn arrivals around.
+ *
+ * Paid on DEPARTURE from the Office, once per train. Not paid again when the train later runs off
+ * the end of the Division and retires: it left YOUR section when it cleared your Office, and the far
+ * Division Point belongs to whoever is seated there.
+ *
+ * A crew with no train number is a local switching move and not a departure, so it earns nothing.
+ *
+ * PROVISIONAL, and worth watching: measured, this is roughly +5 Revenue a game against a mean of
+ * 2.7, so it more than doubles the score on its own. Flagged in `TODO.md`.
+ */
+function awardDeparture(
+  s: GameState,
+  owner: PlayerIndex,
+  tray: CrewTray,
+  events: GameEvent[],
+): void {
+  if (tray.trainNumber === null) return;
+  const p = s.players[owner];
+  if (!p) return;
+  p.revenue += 1;
+  events.push({
+    type: 'revenueChanged',
+    player: owner,
+    delta: 1,
+    total: p.revenue,
+    reason: 'a train cleared your section',
+  });
+}
+
 function retireTrain(s: GameState, id: TrayId, tray: CrewTray, events: GameEvent[]): void {
   for (const car of tray.consist) {
     if (car.type === 'caboose') s.yards.divisionYard.push(car);

src/engine/apply.ts

@@ -30,7 +30,7 @@ import {
   officeProfile,
   trainProfile,
 } from './content.ts';
-import type { CarType, FreightKind, Hand, MainlineKind, ModifierKind, TrackGeometry } from './content.ts';
+import type { CarType, FreightKind, Hand, MainlineKind, ModifierKind, ModifierProfile, TrackGeometry, TrainRules } from './content.ts';
 import type { GameEvent } from './events.ts';
 import type { Intent, RejectionCode } from './intents.ts';
 import type {
@@ -39,11 +39,14 @@ import type {
   Facility,
   GameState,
   GridCoord,
+  Load,
   OfficeArea,
   PlayerIndex,
   RollingStock,
+  TrackArc,
   TrackCard,
   TrayId,
+  TurnoutOrientation,
 } from './state.ts';
 import { createRng } from './rng.ts';
 import { carsOn, coordKey, isOperationalRail, spaceOn } from './state.ts';
@@ -138,7 +141,7 @@ export function hasFreightAgentOption(s: GameState, player: PlayerIndex): boolea
     if (!f) continue;
     if (f.allows.outbound && f.outboundBox.length < f.capacity.outbound) return true;
     if (f.inboundBox.length > 0) return true;
-    if (f.menAtWork.some((l) => l !== null)) return true;
+    if (f.menAtWork?.some((l) => l !== null)) return true;
     if (f.outboundBox.length > 0) return true;
   }
   return false;
@@ -196,6 +199,9 @@ export function portersLeft(f: Facility): number {
  * `loadAdvanced` never fired in 200 games because the outbound pipeline had no entry point.
  */
 export function canAdvanceLoad(f: Facility, box: number): boolean {
+  // A Passenger Facility has no pipeline at all (§9.2 is porters, not MEN | AT | WORK), so freight
+  // work is refused here on the shape of the facility rather than on it happening to have 0 Laborers.
+  if (!f.menAtWork) return false;
   if (box < 0 || box >= f.menAtWork.length) return false;
   const load = f.menAtWork[box];
   if (!load) return false;
@@ -215,7 +221,71 @@ export function canAdvanceLoad(f: Facility, box: number): boolean {
 }
 
 /** §9.3 — the first Laborer step of an outbound load: Green Loading Slot onto MEN. */
+/**
+ * A turnout's diverging leg, as an arc.
+ *
+ * The stem is always an east or west edge and the leg always leaves north or south, so the arc is
+ * just the two named together — `{stem:'w', diverge:'s'}` is `sw`. Naming the leg this way is what
+ * lets the upgrade rule below be stated in GEOMETRY rather than in hands, so it is unaffected by
+ * which printed row we call left.
+ */
+function divergingArc(t: TurnoutOrientation): TrackArc {
+  return `${t.diverge}${t.stem}` as TrackArc;
+}
+
+/**
+ * May this turnout be laid ON TOP of the card already on this square?
+ *
+ * Reported from playtesting: a district can only ever hang off a turnout, so a player who has laid
+ * a straight along the main and then wants to branch there had no move at all — the piece had to
+ * have been a turnout when it went down. A turnout may therefore UPGRADE:
+ *
+ *   - a **straight**, at any of its orientations, because a turnout is a straight plus a leg; or
+ *   - a **curve of the same arc** as the turnout's own diverging leg, which is the same road with a
+ *     through track added beside it.
+ *
+ * Both are strict port SUPERSETS of what they replace — `{e,w}` for a straight, one arc for a curve
+ * — so an upgrade can never sever a join a neighbour already relies on, and needs no connection test
+ * of its own. The new leg is allowed to reach nothing at all; opening a direction is the point.
+ *
+ * Two things block it, and both are about the card being in use rather than about its shape: you
+ * cannot swap the track out from under a standing car, and an Interlocking or Telegraph built on the
+ * card would have to be lifted with it. The replaced card leaves play — board cards are never
+ * salvaged (see the `cardPlayed` reducer), so a lifted one is simply gone, as it would be at a table.
+ */
+function checkTurnoutUpgrade(existing: TrackCard, proto: TrackCard): RejectionCode | null {
+  const t = proto.geometry.kind === 'track' ? proto.geometry.turnout : undefined;
+  if (!t) return 'NOT_UPGRADEABLE_TRACK';
+
+  const g = existing.geometry;
+  if (g.kind !== 'track') return 'NOT_UPGRADEABLE_TRACK';
+  if (g.geometry === 'curved' || g.geometry === 'sharpCurved') {
+    // The ARC, not merely the diagonal: a `sw` curve and an `ne` one share a slope but leave by
+    // opposite edges, so replacing one with the other would move the leg off its neighbour.
+    if (g.arc !== divergingArc(t)) return 'NOT_UPGRADEABLE_TRACK';
+  } else if (g.geometry !== 'straight') {
+    return 'NOT_UPGRADEABLE_TRACK';
+  }
+
+  if (existing.standing.length > 0) return 'UPGRADE_OCCUPIED';
+  if (existing.enhancements.length > 0) return 'UPGRADE_ENHANCED';
+  return null;
+}
+
+/**
+ * The MEN | AT | WORK pipeline of a Freight Facility.
+ *
+ * `execute` and `reduce` run only after `check` has passed, and every freight-work check refuses a
+ * Passenger Facility — so reaching here with one is a broken invariant, not a case to handle. Throwing
+ * says that, where a `!` would quietly write into nothing and leave the fault to surface later.
+ */
+function workTrack(f: Facility): [Load | null, Load | null, Load | null] {
+  if (!f.menAtWork) throw new Error('freight work attempted on a Passenger Facility');
+  return f.menAtWork;
+}
+
 export function canStartLoad(f: Facility): boolean {
+  if (!f.menAtWork) return false;
   if (laborersLeft(f) < 1) return false;
   if (f.outboundBox.length === 0) return false;
   return f.menAtWork[0] === null;
@@ -226,7 +296,13 @@ export function canBoard(s: GameState, player: PlayerIndex, at: GridCoord): bool
   const f = facilityAt(s, player, at);
   if (!f || f.kind !== 'passenger' || portersLeft(f) < 1) return false;
   if (!f.outboundBox.some((c) => c.type === 'coach' && c.loaded)) return false;
-  return trainAtOfficeWith(s, player, (c) => c.type === 'coach' && !c.loaded);
+  // §7 — a train whose card refuses passenger work, or which is not booked to stop here, is not a
+  // train these passengers can board however many empty coaches it is carrying.
+  return trainAtOfficeWith(
+    s, player,
+    (c) => c.type === 'coach' && !c.loaded,
+    (t) => !refusesPassengers(t) && !refusesThisOffice(s, player, t),
+  );
 }
 
 /**
@@ -246,16 +322,127 @@ export function canDetrain(s: GameState, player: PlayerIndex, at: GridCoord): bo
   if (!f || f.kind !== 'passenger' || portersLeft(f) < 1) return false;
   if (f.inboundBox.length >= f.capacity.inbound) return false;
   if (!s.yards.divisionYard.some((c) => c.type === 'coach' && !c.loaded)) return false;
-  return trainAtOfficeWith(s, player, (c) => c.type === 'coach' && c.loaded);
+  return trainAtOfficeWith(
+    s, player,
+    (c) => c.type === 'coach' && c.loaded,
+    (t) => !refusesPassengers(t) && !refusesThisOffice(s, player, t),
+  );
 }
 
 function trainAtOfficeWith(
   s: GameState,
   player: PlayerIndex,
   pred: (c: RollingStock) => boolean,
+  trayOk: (t: CrewTray) => boolean = () => true,
 ): boolean {
   const area = areaOf(s, player);
-  return area.adOccupancy.some((id) => s.trays.get(id)?.consist.some(pred) ?? false);
+  return area.adOccupancy.some((id) => {
+    const t = s.trays.get(id);
+    return !!t && trayOk(t) && t.consist.some(pred);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// §7 — the operating rules printed on a train's own card
+// ---------------------------------------------------------------------------
+
+/**
+ * What this tray's train card prints, or nothing at all.
+ *
+ * A local crew has no train number and therefore no printed rules — it is the player's own switcher
+ * and may do anything the general rules allow. Every restriction below is keyed off the CARD, so a
+ * crew is unaffected by all of them.
+ */
+function rulesOf(tray: CrewTray): TrainRules {
+  if (tray.trainNumber === null) return {};
+  return trainProfile(tray.trainNumber, tray.trainIsExtra)?.rules ?? {};
+}
+
+/** Freight cars this train has already exchanged on this square this turn (trains 3/4). */
+function freightWorkedKey(trayId: TrayId, at: GridCoord): string {
+  return `${trayId}@${coordKey(at)}`;
+}
+
+const isFreight = (c: RollingStock): boolean => c.type !== 'coach' && c.type !== 'caboose';
+
+/**
+ * May this train work these freight cars on this square?
+ *
+ * Trains 3/4 Express print "may drop or pick up one freight car at EVERY location", so the budget is
+ * per square rather than per turn — it may work a car here, move on, and work another there. Both
+ * setting out and picking up spend from the same one, because the card says "drop OR pick up".
+ */
+function freightBudgetLeft(
+  s: GameState,
+  tray: CrewTray,
+  at: GridCoord,
+  wanted: number,
+): boolean {
+  if (!rulesOf(tray).oneFreightPerLocation) return true;
+  const already = s.turn.freightWorked[freightWorkedKey(tray.id, at)] ?? 0;
+  return already + wanted <= 1;
+}
+
+/**
+ * Whether a train may do switching work at all (§7).
+ *
+ * Six cards print "no switching" — the two expresses, the Light Engine, the Campaign, Circus and
+ * Military trains. They run the Division; they do not shunt. This covers moving, setting out and
+ * sorting alike, because all three are switching.
+ */
+function switchingRefusal(tray: CrewTray): RejectionCode | null {
+  return rulesOf(tray).noSwitching ? 'NO_SWITCHING' : null;
+}
+
+/**
+ * Charge freight cars against this train's per-location budget (trains 3/4).
+ *
+ * Called from BOTH the coupling and the setting-out reducers, because the card says "drop OR pick up
+ * one" — the two share a budget rather than getting one each. Only recorded for trains the rule
+ * applies to, so the map stays empty for everything else.
+ */
+function spendFreightBudget(
+  s: GameState,
+  tray: CrewTray,
+  at: GridCoord,
+  stock: readonly RollingStock[],
+): void {
+  if (!rulesOf(tray).oneFreightPerLocation) return;
+  const n = stock.filter(isFreight).length;
+  if (n === 0) return;
+  const key = freightWorkedKey(tray.id, at);
+  s.turn.freightWorked[key] = (s.turn.freightWorked[key] ?? 0) + n;
+}
+
+/** Trains that may not be worked by Porters at all (§7): the Military train and the Director's car. */
+function refusesPassengers(tray: CrewTray): boolean {
+  return rulesOf(tray).noPassengerWork === true;
+}
+
+/**
+ * Trains 1/2 Crack Limited — "stop at Terminals only". It runs into every Office and takes an A/D
+ * track like anything else, but Porters only work it where it is booked to stop, so passengers can
+ * neither board nor alight anywhere but a Terminal.
+ */
+function refusesThisOffice(s: GameState, player: PlayerIndex, tray: CrewTray): boolean {
+  if (!rulesOf(tray).terminalsOnly) return false;
+  const area = s.officeAreas.get(player);
+  return !area || area.tier !== 'terminal';
+}
+
+/**
+ * WHY passenger work was refused — the printed rule if one is to blame, otherwise the general one.
+ *
+ * `canBoard`/`canDetrain` answer a single yes/no over every train at the Office, so when they say no
+ * this works out whether a card is the reason. Without it a Military train standing at the platform
+ * reported "no train at the Office", which is both wrong and unhelpful.
+ */
+function passengerRefusal(s: GameState, player: PlayerIndex): RejectionCode {
+  const area = areaOf(s, player);
+  const trains = area.adOccupancy.map((id) => s.trays.get(id)).filter((t): t is CrewTray => !!t);
+  if (trains.length > 0 && trains.every((t) => refusesThisOffice(s, player, t))) return 'NOT_A_TERMINAL';
+  if (trains.length > 0 && trains.every(refusesPassengers)) return 'NO_PASSENGER_WORK';
+  return 'NO_TRAIN_AT_OFFICE';
 }
 
 // ---------------------------------------------------------------------------
@@ -291,12 +478,27 @@ export function check(s: GameState, player: PlayerIndex, i: Intent): RejectionCo
       if (s.turn.movesRemaining < 1) return 'NO_MOVES_REMAINING';
       const tray = s.trays.get(i.trayId);
       if (!tray) return 'NO_SUCH_TRAY';
+      const noSwitch = switchingRefusal(tray);
+      if (noSwitch) return noSwitch;
       const from = trayCoord(s, i.trayId);
       if (!from) return 'ILLEGAL_MOVE';
       const dests = destinationsFor(s, player, i.trayId, from, i.reverse);
-      return dests.some((d) => d.coord.row === i.to.row && d.coord.col === i.to.col)
-        ? null
-        : 'ILLEGAL_MOVE';
+      const dest = dests.find((d) => d.coord.row === i.to.row && d.coord.col === i.to.col);
+      if (!dest) return 'ILLEGAL_MOVE';
+
+      /**
+       * COUPLING IS MANDATORY (§A.4), so a train forbidden to pick something up may not make the
+       * MOVE that would pick it up. There is no "move but leave them"; the restriction has to bite
+       * on the move or it cannot bite at all.
+       */
+      const rules = rulesOf(tray);
+      if (dest.couples.length > 0) {
+        if (rules.dropOnly) return 'PICKUP_NOT_ALLOWED';
+        if (rules.pickUpEmptiesOnly && dest.couples.some((c) => c.loaded)) return 'EMPTIES_ONLY';
+        const freight = dest.couples.filter(isFreight).length;
+        if (freight > 0 && !freightBudgetLeft(s, tray, i.to, freight)) return 'FREIGHT_WORKED_HERE';
+      }
+      return null;
     }
 
     case 'switch.dropCars': {
@@ -304,6 +506,8 @@ export function check(s: GameState, player: PlayerIndex, i: Intent): RejectionCo
       if (s.turn.option !== 'switch') return 'OPTION_NOT_CHOSEN';
       const tray = s.trays.get(i.trayId);
       if (!tray) return 'NO_SUCH_TRAY';
+      const noSwitch = switchingRefusal(tray);
+      if (noSwitch) return noSwitch;
       if (i.count < 1 || i.count > tray.consist.length) return 'CONSIST_EMPTY';
       const here = trayCoord(s, i.trayId);
       if (!here) return 'CANNOT_DROP_HERE';
@@ -319,6 +523,30 @@ export function check(s: GameState, player: PlayerIndex, i: Intent): RejectionCo
       const ahead = tray.engineAt;
       const behind = tray.consist.length - tray.engineAt;
       if (i.fromNose ? i.count > ahead : i.count > behind) return 'CONSIST_EMPTY';
+
+      // The cut that would come off, so the printed rules can be asked about its contents.
+      const cut = i.fromNose
+        ? tray.consist.slice(0, i.count)
+        : tray.consist.slice(tray.consist.length - i.count);
+      const dropRules = rulesOf(tray);
+      /**
+       * Trains 7/8 Local — "coach must remain on station track if switching", i.e. the coach is
+       * never set out during switching at all.
+       *
+       * The intended reading was "set out only at the Office", but §A.4 makes that unimplementable:
+       * `canDropCarsAt` refuses the Office square outright — "the Office track is Operational Rail,
+       * but Rolling Stock may not be left there" — so "only at the Office" and "nowhere" are the same
+       * rule. What is left is the effect that matters: the Local may shunt its freight car around the
+       * district, and may not abandon its coach at an industry or on a siding while it does.
+       * Flagged in `TODO.md` in case the station track is meant to become a real place to leave one.
+       */
+      if (dropRules.coachStaysOnStationTrack && cut.some((c) => c.type === 'coach')) {
+        return 'COACH_MUST_STAY';
+      }
+      const droppedFreight = cut.filter(isFreight).length;
+      if (droppedFreight > 0 && !freightBudgetLeft(s, tray, here, droppedFreight)) {
+        return 'FREIGHT_WORKED_HERE';
+      }
       return canDropCarsAt(areaOf(s, player), here, i.count) ? null : 'CANNOT_DROP_HERE';
     }
 
@@ -328,6 +556,8 @@ export function check(s: GameState, player: PlayerIndex, i: Intent): RejectionCo
       if (s.turn.movesRemaining < 1) return 'NO_MOVES_REMAINING';
       const tray = s.trays.get(i.trayId);
       if (!tray) return 'NO_SUCH_TRAY';
+      const noSwitch = switchingRefusal(tray);
+      if (noSwitch) return noSwitch;
       const here = trayCoord(s, i.trayId);
       if (!here) return 'ILLEGAL_MOVE';
       // Only on a card carrying a Small Yard, and it costs the Move it "spends in the yard".
@@ -493,7 +723,7 @@ export function check(s: GameState, player: PlayerIndex, i: Intent): RejectionCo
       if (s.turn.freightAgentUsed) return 'OPTION_ALREADY_CHOSEN';
       const f = facilityAt(s, player, i.at);
       if (!f) return 'NO_SUCH_FACILITY';
-      if (i.from === 'menAtWork') return f.menAtWork[i.index] ? null : 'BOX_EMPTY';
+      if (i.from === 'menAtWork') return f.menAtWork?.[i.index] ? null : 'BOX_EMPTY';
       const box = i.from === 'outbound' ? f.outboundBox : f.inboundBox;
       return box[i.index] ? null : 'BOX_EMPTY';
     }
@@ -544,13 +774,13 @@ export function check(s: GameState, player: PlayerIndex, i: Intent): RejectionCo
       if (!inPhase(s, 'loadUnload')) return 'WRONG_PHASE';
       if (!facilityAt(s, player, i.at)) return 'NO_SUCH_FACILITY';
       if (portersLeft(facilityAt(s, player, i.at)!) < 1) return 'RESOURCE_SPENT';
-      return canBoard(s, player, i.at) ? null : 'NO_TRAIN_AT_OFFICE';
+      return canBoard(s, player, i.at) ? null : passengerRefusal(s, player);
 
     case 'porter.detrain':
       if (!inPhase(s, 'loadUnload')) return 'WRONG_PHASE';
       if (!facilityAt(s, player, i.at)) return 'NO_SUCH_FACILITY';
       if (portersLeft(facilityAt(s, player, i.at)!) < 1) return 'RESOURCE_SPENT';
-      return canDetrain(s, player, i.at) ? null : 'NO_TRAIN_AT_OFFICE';
+      return canDetrain(s, player, i.at) ? null : passengerRefusal(s, player);
 
     case 'laborer.startLoad': {
       if (!inPhase(s, 'loadUnload')) return 'WRONG_PHASE';
@@ -584,7 +814,9 @@ export function check(s: GameState, player: PlayerIndex, i: Intent): RejectionCo
        * taking it, so every unload minted one. Unloading is meant to consume supply.
        */
       if (!s.yards.divisionYard.some((c) => c.type === car.type && !c.loaded)) return 'NO_SUITABLE_CAR';
-      // The load is placed on WORK, the last box, so that box must be free.
+      // The load is placed on WORK, the last box, so that box must be free — and a Passenger
+      // Facility has no such box, so there is nothing to unload into.
+      if (!f.menAtWork) return 'NO_SUCH_FACILITY';
       return f.menAtWork[f.menAtWork.length - 1] === null ? null : 'BOX_FULL';
     }
 
@@ -629,6 +861,21 @@ function checkPlay(
       {
         const proto = protoCard(card.kind, variant);
         if (!proto) return 'NO_PLACEMENT';
+
+        /**
+         * AN OCCUPIED SQUARE IS AN UPGRADE, not a placement.
+         *
+         * A turnout may be laid on top of a card already down — see `checkTurnoutUpgrade`. The one
+         * occupied square that is NOT an upgrade is a Limits sign on the Running Track: that is the
+         * growth point, and `canPlaceAt` moves it outward rather than building over it.
+         */
+        const existing = area.grid.get(coordKey(placement));
+        const isMovableSign =
+          existing?.geometry.kind === 'limits' &&
+          placement.row === area.runningRow &&
+          existing.standing.length === 0;
+        if (existing && !isMovableSign) return checkTurnoutUpgrade(existing, proto);
+
         // Said separately from NOT_CONNECTED because it is a different mistake: the card would join
         // perfectly well, and would still leave the Running Track stopping dead at it.
         if (placement.row === area.runningRow && !carriesThroughTrack(proto)) {
@@ -662,6 +909,8 @@ function checkPlay(
     case 'modifier': {
       if (!placement) return 'NO_PLACEMENT';
       if (area.grid.has(coordKey(placement))) return 'NOT_CONNECTED';
+      // One of a kind per Office Area, as with industries (Q4) — no district gets two Ice Houses.
+      if (hasModifierInArea(area, card.kind.modifier)) return 'FACILITY_LOCKED';
       // §9 — a Modifier is not track. It must sit adjacent to a Facility THAT CAN HOST IT (one of
       // the nine nearby spots) or it does nothing at all, so anywhere else is not a legal play.
       return adjacentFacilityCoord(area, placement, card.kind.modifier) ? null : 'NOT_CONNECTED';
@@ -1010,7 +1259,7 @@ function execute(s: GameState, player: PlayerIndex, i: Intent): GameEvent[] {
       const f = facilityAt(s, player, i.at)!;
       const stock: RollingStock =
         i.from === 'menAtWork'
-          ? { type: f.menAtWork[i.index]!.type, loaded: true }
+          ? { type: workTrack(f)[i.index]!.type, loaded: true }
           : (i.from === 'outbound' ? f.outboundBox : f.inboundBox)[i.index]!;
       return [{ type: 'facilityUnjammed', player, at: i.at, from: i.from, stock }];
     }
@@ -1059,10 +1308,10 @@ function execute(s: GameState, player: PlayerIndex, i: Intent): GameEvent[] {
 
     case 'laborer.advanceLoad': {
       const f = facilityAt(s, player, i.at)!;
-      const load = f.menAtWork[i.box]!;
+      const load = workTrack(f)[i.box]!;
       const next = load.dir === 'out' ? i.box + 1 : i.box - 1;
 
-      if (next >= f.menAtWork.length) {
+      if (next >= workTrack(f).length) {
         // Outbound complete: the load goes onto the spotted car (§9.3).
         return [
           { type: 'loadCompleted', player, at: i.at, carType: load.type },
@@ -1158,6 +1407,7 @@ export function reduce(s: GameState, e: GameEvent): void {
         card.standing = [];
         if (card.facility) card.facility.industryTrack.cars = [];
       }
+      spendFreightBudget(s, tray, e.at, e.stock);
       break;
     }
 
@@ -1187,6 +1437,7 @@ export function reduce(s: GameState, e: GameEvent): void {
       const card = area.grid.get(coordKey(e.at));
       // On a Facility card the industry track is where cars stand (§9.3).
       if (card) carsOn(card).push(...e.stock);
+      spendFreightBudget(s, tray, e.at, e.stock);
       break;
     }
 
@@ -1353,8 +1604,8 @@ export function reduce(s: GameState, e: GameEvent): void {
     case 'facilityUnjammed': {
       const f = facilityAt(s, e.player, e.at)!;
       if (e.from === 'menAtWork') {
-        const idx = f.menAtWork.findIndex((l) => l !== null);
-        if (idx >= 0) f.menAtWork[idx] = null;
+        const idx = workTrack(f).findIndex((l) => l !== null);
+        if (idx >= 0) workTrack(f)[idx] = null;
       } else {
         const box = e.from === 'outbound' ? f.outboundBox : f.inboundBox;
         const idx = box.findIndex((c) => c.type === e.stock.type);
@@ -1445,22 +1696,22 @@ export function reduce(s: GameState, e: GameEvent): void {
       const f = facilityAt(s, e.player, e.at)!;
       const idx = f.outboundBox.findIndex((c) => c.type === e.carType);
       if (idx >= 0) f.outboundBox.splice(idx, 1);
-      f.menAtWork[0] = { type: e.carType, dir: 'out' };
+      workTrack(f)[0] = { type: e.carType, dir: 'out' };
       f.usedThisStage.laborers += 1;
       break;
     }
 
     case 'loadAdvanced': {
       const f = facilityAt(s, e.player, e.at)!;
-      f.menAtWork[e.toBox] = f.menAtWork[e.fromBox]!;
-      f.menAtWork[e.fromBox] = null;
+      workTrack(f)[e.toBox] = workTrack(f)[e.fromBox]!;
+      workTrack(f)[e.fromBox] = null;
       f.usedThisStage.laborers += 1;
       break;
     }
 
     case 'unloadCompleted': {
       const f = facilityAt(s, e.player, e.at)!;
-      f.menAtWork[0] = null;
+      workTrack(f)[0] = null;
       f.inboundBox.push({ type: e.carType, loaded: true });
       f.usedThisStage.laborers += 1;
       break;
@@ -1468,7 +1719,7 @@ export function reduce(s: GameState, e: GameEvent): void {
 
     case 'loadCompleted': {
       const f = facilityAt(s, e.player, e.at)!;
-      f.menAtWork[f.menAtWork.length - 1] = null;
+      workTrack(f)[workTrack(f).length - 1] = null;
       const ci = f.industryTrack.cars.findIndex((c) => !c.loaded && c.type === e.carType);
       if (ci >= 0) {
         s.yards.classificationYard.push(f.industryTrack.cars[ci]!);
@@ -1489,7 +1740,7 @@ export function reduce(s: GameState, e: GameEvent): void {
         refillDivisionYardIfEmpty(s);
         f.industryTrack.cars[ci] = empty;
       }
-      f.menAtWork[f.menAtWork.length - 1] = { type: e.carType, dir: 'in' };
+      workTrack(f)[workTrack(f).length - 1] = { type: e.carType, dir: 'in' };
       f.usedThisStage.laborers += 1;
       break;
     }
@@ -1697,14 +1948,29 @@ export function checkEnhancementPlacement(
   }
 
   const onRunning = placement.row === area.runningRow;
-  const isStraight =
-    card.geometry.kind === 'track' && card.geometry.geometry === 'straight';
+  /**
+   * A STRAIGHT-PLACED ENHANCEMENT REPLACES THE STRAIGHT, so it cannot be stacked.
+   *
+   * The printed placement is "any Running Track Straight": the card goes down IN PLACE OF the
+   * straight, and what stands there afterwards is an Interlocking, not a straight carrying one. A
+   * second such card has no straight left to replace. This was unchecked — an enhancement only adds
+   * a string to `enhancements[]` and leaves the geometry alone, so a single straight could take
+   * Interlocking and Telegraph and a Water Column all at once.
+   *
+   * The `onCard` chain is untouched and is NOT an exception to this: Telephone prints "on Telegraph"
+   * and Radio "on Telephone", so those target a named card rather than a straight, which is exactly
+   * why they still stack. `requiresOnSameCard` above is what enforces it.
+   */
+  const isBareStraight =
+    card.geometry.kind === 'track' &&
+    card.geometry.geometry === 'straight' &&
+    card.enhancements.length === 0;
 
   switch (rule.placement) {
     case 'runningTrackStraight':
-      return onRunning && isStraight ? null : 'NOT_CONNECTED';
+      return onRunning && isBareStraight ? null : 'NOT_CONNECTED';
     case 'secondaryTrackStraight':
-      return !onRunning && isStraight ? null : 'NOT_CONNECTED';
+      return !onRunning && isBareStraight ? null : 'NOT_CONNECTED';
     case 'onCard':
       return null;
     default:
@@ -1778,18 +2044,85 @@ export function isLockedOut(area: OfficeArea, kind: FreightKind): boolean {
   return false;
 }
 
+/**
+ * Is a Modifier of this kind already standing in the district?
+ *
+ * Reported from playtesting: two Ice Houses could be built in one Office Area. Industries have been
+ * barred from doubling up since Q4 (`isLockedOut` above), but a Modifier is a different card kind
+ * and had no such check — every square adjacent to an eligible host was legal, however many copies
+ * you held. One of a kind per Office Area, the same rule the industries follow.
+ *
+ * Enhancements are deliberately NOT covered. An Interlocking is a plant at one junction, so a second
+ * on another straight is a different installation, and the Telegraph → Telephone → Radio chain is
+ * already gated per card by `checkEnhancementPlacement`.
+ *
+ * Consequence worth expecting: modifiers printed in more than one copy (Truck Dock 2, Ice House 2,
+ * Waiting Area 3) go partly dead in solitaire, where there is only one Office Area. That is correct
+ * — the spare copies exist for other players' districts.
+ */
+function hasModifierInArea(area: OfficeArea, kind: ModifierKind): boolean {
+  for (const card of area.grid.values()) {
+    if (card.geometry.kind === 'modifier' && card.geometry.modifier === kind) return true;
+  }
+  return false;
+}
+
+/**
+ * How much of a Modifier's printed capacity its host can actually use.
+ *
+ * AN INDUSTRY'S PRINTED FLOW IS ABSOLUTE. A Grocer's Warehouse is `flow: 'inbound'`, so it has no
+ * green boxes and `freightAgent.stockOutbound` refuses it — yet an Ice House beside it prints "+1
+ * outbound" and the capacity was being raised anyway, on a direction that can never be drawn or
+ * stocked. Reported from playtesting as "the Ice House added the laborer but not the outbound slot":
+ * the laborer landed because Laborers have no direction, and the slot did not because there was
+ * nowhere for it to go. No modifier turns a receiver into a shipper, so the grant is dropped.
+ *
+ * It is not one card's quirk. The same trap catches **Truck Dock** and **Forklifts**, which also
+ * print `addOut` and also list `grocersWarehouse` among their hosts, and **Waiting Area**,
+ * **Restaurant** and **Hotel**, whose `hosts: ['office']` includes a Whistle Post — not a Passenger
+ * Facility, so `allows.outbound` is false there too.
+ *
+ * The industry track grows by what was actually applied, not by what was printed: a slot that does
+ * not exist must not lengthen the siding that would have served it.
+ */
+function usableGrant(f: Facility, m: ModifierProfile): { out: number; in: number } {
+  return {
+    out: f.allows.outbound ? m.addOut : 0,
+    in: f.allows.inbound ? m.addIn : 0,
+  };
+}
+
 /** Applies a Modifier's printed effect to the Facility it was placed beside (content.ts). */
 function applyModifier(area: OfficeArea, coord: GridCoord, modifier: ModifierKind): void {
   const target = adjacentFacilityCoord(area, coord, modifier);
   if (!target) return;
-  const f = area.grid.get(coordKey(target))?.facility;
-  if (!f) return;
+  const host = area.grid.get(coordKey(target));
+  const f = host?.facility;
+  if (!host || !f) return;
   const m = modifierProfile(modifier);
-  f.capacity.outbound += m.addOut;
-  f.capacity.inbound += m.addIn;
+  /**
+   * Record WHICH facility this Modifier served.
+   *
+   * `TrackCard.modifiers` was initialised everywhere and appended nowhere, so the panel row listing
+   * "Modifier cards standing beside this industry" was permanently empty — and, more to the point,
+   * nothing downstream could tell which card had granted what. It is needed now to explain a grant
+   * that the host's flow discards (see `usableGrant`).
+   */
+  host.modifiers.push(modifier);
+  const use = usableGrant(f, m);
+  f.capacity.outbound += use.out;
+  f.capacity.inbound += use.in;
   f.laborers += m.addLoaders;
   f.porters += m.addPorters;
-  if (m.addOut > 0 || m.addIn > 0) f.industryTrack.length += m.addOut + m.addIn;
+  /**
+   * The siding grows only where there IS one. A Passenger Facility has no industry track — passengers
+   * board off the platform — so a Waiting Area, whose "+1" is a passenger slot rather than a car,
+   * must not give the Office somewhere to spot a car. It did, and the board then drew the Depot a
+   * siding square: the same phantom siding the renderer was just fixed for, arriving by another door.
+   */
+  if (f.kind === 'freight' && (use.out > 0 || use.in > 0)) {
+    f.industryTrack.length += use.out + use.in;
+  }
 }
 
 /** §2.1, Gap 4a — extending the Running Track pushes the Limits sign outward. */

src/engine/content.ts

@@ -72,15 +72,34 @@ export type TrackProfile = {
  * hand-of-three is the real constraint on how fast a railroad grows.
  *
  * Handedness is PRINTED, not chosen on placement: it is the diagonal the 45° leg lies on.
+ *
+ * DO NOT REORDER THESE ROWS to put left before right. `setup.ts` builds the deck by walking this
+ * array, so a row's POSITION decides which physical card a given seed deals — and the replays in
+ * `public/replays/` are saved as a seed plus a list of intents, replayed through this deck. When
+ * playtesting found the hands inverted (see `track.ts`, Orientation), the fix flipped each pair's
+ * `hand` label in place and left the order alone, so slot 32 still holds an `nw_se` curve and every
+ * published replay still plays. Reordering to look tidy would silently re-deal every saved game.
  */
 export const TRACK_CARDS: readonly TrackProfile[] = [
   { geometry: 'straight', hand: 'none', name: 'Straight track', copiesInDeck: 32, isOperationalRail: true, moveCost: 1 },
-  { geometry: 'curved', hand: 'left', name: 'Curved track (left)', copiesInDeck: 16, isOperationalRail: true, moveCost: 1 },
   { geometry: 'curved', hand: 'right', name: 'Curved track (right)', copiesInDeck: 16, isOperationalRail: true, moveCost: 1 },
-  { geometry: 'sharpCurved', hand: 'left', name: 'Sharp Curved Track (left)', copiesInDeck: 4, isOperationalRail: true, moveCost: 2 },
-  { geometry: 'sharpCurved', hand: 'right', name: 'Sharp Curved Track (right)', copiesInDeck: 4, isOperationalRail: true, moveCost: 2 },
-  { geometry: 'turnout', hand: 'left', name: 'Turnout (left)', copiesInDeck: 16, isOperationalRail: false, moveCost: 1 },
+  { geometry: 'curved', hand: 'left', name: 'Curved track (left)', copiesInDeck: 16, isOperationalRail: true, moveCost: 1 },
+  /**
+   * SHARP CURVES ARE DEALT ZERO COPIES — Jesse's call, and the same treatment as Poling.
+   *
+   * The only thing that made them different from an ordinary curve was `moveCost: 2`, and nothing
+   * ever charged it: every switching move costs exactly 1, hard-coded. So the 8 cards in the deck
+   * were geometric duplicates of the curves, taking 8 draws from a deck the rebalance already thinks
+   * is too diluted. They come out rather than having the Move cost built, because a per-card movement
+   * cost is a change to the Move model and the rebalance can wait.
+   *
+   * The rows stay in the catalogue at zero, exactly as Poling does, so the design is still visible
+   * and the geometry still works if they are ever dealt again.
+   */
+  { geometry: 'sharpCurved', hand: 'right', name: 'Sharp Curved Track (right)', copiesInDeck: 0, isOperationalRail: true, moveCost: 2 },
+  { geometry: 'sharpCurved', hand: 'left', name: 'Sharp Curved Track (left)', copiesInDeck: 0, isOperationalRail: true, moveCost: 2 },
   { geometry: 'turnout', hand: 'right', name: 'Turnout (right)', copiesInDeck: 16, isOperationalRail: false, moveCost: 1 },
+  { geometry: 'turnout', hand: 'left', name: 'Turnout (left)', copiesInDeck: 16, isOperationalRail: false, moveCost: 1 },
 ];
 
 /** 104 — the sheet's "Total track". */
@@ -321,8 +340,14 @@ export type TrainRules = {
   /** X17 Campaign, X18 Circus: a scheduled stop that does something. */
   stopEarnsPoint?: boolean;
   stopThenExpedite?: boolean;
-  /** The Second Section card copies the next scheduled train. */
-  copiesNextScheduled?: boolean;
+  /**
+   * `copiesNextScheduled` was here and is DELETED. No train card ever carried it: a Second Section
+   * is a Maneuver card played on a train that is due out, and it has its own intent
+   * (`newTrain.secondSection`, `SECOND_SECTION` below) which has been implemented all along. The
+   * flag was a second, unreachable way to describe a mechanic that already worked — it appeared in
+   * the "nine rules read by nothing" count while being the one entry that needed removing rather
+   * than building.
+   */
   note?: string;
 };
 
@@ -567,21 +592,72 @@ export type EnhancementRule = {
   requiresInDistrict?: EnhancementKey;
   /** Bonus added to an opposing train's number when resolving a meet, once a Day. */
   dispatchBonus?: number;
+  /**
+   * WHETHER THE PRINTED EFFECT ACTUALLY DOES ANYTHING, so the card can say so.
+   *
+   *   - `live`        — resolves in a solitaire game.
+   *   - `dormantSolo` — implemented and read at the point of attack, but the attack is an
+   *                     opponent-directed card that a solitaire deck does not contain (Q6).
+   *   - `unbuilt`     — nothing reads it at all. The effect is recorded here and not yet written.
+   *
+   * Seven of the ten are live. Each row below cites the file that reads it, because the first
+   * attempt at this table got FIVE of the ten wrong: it was filled in by grepping for four helper
+   * function names and reading "no match" as "no implementation", when Interlocking, Yard Office,
+   * Small Yard and ABS Signals are all read directly by key — and all four are covered by tests in
+   * `enhancements.test.ts` that were passing the whole time. The result was a tooltip telling players
+   * that four working cards did nothing, which is worse than the bare label it replaced.
+   *
+   * KEEP THIS HONEST, AND CHECK THE CITATION. Implementing one of these means changing its value in
+   * the same commit; otherwise the card goes on apologising for something it now does. It is data
+   * rather than something derived because "is this key read anywhere" is not a question the type
+   * system can answer — but a claim here without a file reference beside it is a claim nobody checked.
+   */
+  effect: 'live' | 'dormantSolo' | 'unbuilt';
 };
 
 export const ENHANCEMENT_RULES: readonly EnhancementRule[] = [
-  { key: 'interlocking', placement: 'runningTrackStraight' },
-  { key: 'facingPointLocks', placement: 'onCard', requiresInDistrict: 'interlocking' },
-  { key: 'yardOffice', placement: 'secondaryTrackStraight' },
-  { key: 'smallYard', placement: 'secondaryTrackStraight' },
-  { key: 'waterColumn', placement: 'runningTrackStraight' },
-  { key: 'overpass', placement: 'onCard' },
-  { key: 'telegraph', placement: 'runningTrackStraight', dispatchBonus: 4 },
-  { key: 'telephone', placement: 'onCard', requiresOnSameCard: 'telegraph', dispatchBonus: 8 },
-  { key: 'radio', placement: 'onCard', requiresOnSameCard: 'telephone', dispatchBonus: 12 },
-  { key: 'absSignals', placement: 'mainlineCard' },
+  // Holds an arrival at the Limits instead of colliding when the Office is full — advance.ts:770.
+  { key: 'interlocking', placement: 'runningTrackStraight', effect: 'live' },
+  // Wired at apply.ts:1738, but it answers Derail, an Action card the solitaire deck omits (Q6).
+  { key: 'facingPointLocks', placement: 'onCard', requiresInDistrict: 'interlocking', effect: 'dormantSolo' },
+  // Diverts a coachless arrival away from the Train Order Office — advance.ts:750.
+  { key: 'yardOffice', placement: 'secondaryTrackStraight', effect: 'live' },
+  // Lets a consist be re-ordered for one Move — apply.ts:405.
+  { key: 'smallYard', placement: 'secondaryTrackStraight', effect: 'live' },
+  // Wired at apply.ts:1743, but it removes a Watertower, a Space-use card the solo deck omits.
+  { key: 'waterColumn', placement: 'runningTrackStraight', effect: 'dormantSolo' },
+  // The only one with NO code path at all: nothing anywhere reads `overpass`.
+  { key: 'overpass', placement: 'onCard', effect: 'unbuilt' },
+  { key: 'telegraph', placement: 'runningTrackStraight', dispatchBonus: 4, effect: 'live' },
+  { key: 'telephone', placement: 'onCard', requiresOnSameCard: 'telegraph', dispatchBonus: 8, effect: 'live' },
+  { key: 'radio', placement: 'onCard', requiresOnSameCard: 'telephone', dispatchBonus: 12, effect: 'live' },
+  // Stored on the Mainline node rather than in `enhancements[]` — apply.ts:1461, read at
+  // advance.ts:599 (no rear-ending) and advance.ts:721 (the follower holds instead of being ruled on).
+  { key: 'absSignals', placement: 'mainlineCard', effect: 'live' },
 ];
 
+/**
+ * What an Enhancement's card does, and whether it does it yet — one line, ready for a tooltip.
+ *
+ * Reported from playtesting: an Interlocking on the board is a bare label with no hover text at all.
+ * Saying only the printed effect would be worse than silence for the four that are `unbuilt` — a
+ * player who builds one to hold a train at the Limit watches it not happen with no way to tell a
+ * misread card from a bug. Same discipline as `checkPlay`'s NOT_IMPLEMENTED: never let a card look
+ * like it is doing something it is not.
+ */
+export function enhancementText(key: string): string | null {
+  const card = ENHANCEMENT_CARDS.find((c) => c.key === key);
+  if (!card) return null;
+  const rule = enhancementRule(key);
+  const note =
+    rule?.effect === 'unbuilt'
+      ? ' — NOT YET IMPLEMENTED: this card has no effect in play.'
+      : rule?.effect === 'dormantSolo'
+        ? ' — it answers an opponent-directed card, which a solitaire deck does not contain, so it never fires in this game.'
+        : '';
+  return `${card.name}: ${card.effect}${note}`;
+}
+
 export function enhancementRule(key: string): EnhancementRule | null {
   return ENHANCEMENT_RULES.find((r) => r.key === key) ?? null;
 }
@@ -677,6 +753,15 @@ export const REGIONS_PER_MAINLINE_CARD = 2; // provisional, pending §10 Q2
 export const STAGES_PER_DAY = 12;
 export const STAGES_PER_SHIFT = 3;
 export const HAND_LIMIT = 3;
+
+/**
+ * The opening deal: 3 track cards and 3 others, from two separately shuffled piles (`setup.ts`).
+ *
+ * Six against a limit of three on purpose — the first turn is spent choosing which district you can
+ * afford to build. PROVISIONAL, and flagged in `TODO.md` for review after play.
+ */
+export const OPENING_TRACK = 3;
+export const OPENING_OTHER = 3;
 export const MAX_CONSIST = 4;
 export const MOVES_PER_LOCAL_OPS = 6;
 export const MOVES_PER_LOCAL_OPS_NIGHT = 5;

src/engine/intents.ts

@@ -136,6 +136,26 @@ export type RejectionCode =
   | 'ON_RUNNING_TRACK'
   /** A card with no east-west road would dead-end the Running Track it was laid in. */
   | 'BREAKS_RUNNING_TRACK'
+  /**
+   * A turnout may be laid on top of a straight, or of a curve on the same arc as its diverging leg
+   * — but only those, and only while the square is idle. See `checkTurnoutUpgrade`.
+   */
+  | 'NOT_UPGRADEABLE_TRACK'
+  /** You cannot swap the track out from under a standing car. */
+  | 'UPGRADE_OCCUPIED'
+  /** An Interlocking or Telegraph is built on that card; the upgrade would have to lift it. */
+  | 'UPGRADE_ENHANCED'
+  /**
+   * §7 — the operating rules printed on a train's own card. Each names the restriction it broke, so
+   * the UI can say which card is refusing rather than "illegal move".
+   */
+  | 'NO_SWITCHING'
+  | 'NOT_A_TERMINAL'
+  | 'COACH_MUST_STAY'
+  | 'FREIGHT_WORKED_HERE'
+  | 'NO_PASSENGER_WORK'
+  | 'PICKUP_NOT_ALLOWED'
+  | 'EMPTIES_ONLY'
   | 'NOT_IMPLEMENTED'
   | 'WRONG_INTENT'
   | 'NOT_A_GRADE'

src/engine/legal.ts

@@ -156,7 +156,22 @@ function localOpsCandidates(s: GameState, player: PlayerIndex): Intent[] {
         out.push({ type: 'card.play', cardId, node });
       }
     }
-    const targets = onMainline ? [] : kind?.kind === 'enhancement' ? attachments : placements;
+    /**
+     * A TURNOUT MAY ALSO UPGRADE A CARD ALREADY DOWN, so it is offered the occupied cells as well as
+     * the empty ones — `check` decides which of them it can actually be laid over. Without this the
+     * upgrade rule exists in the engine and is never once presented, which is precisely how the 18
+     * Enhancement cards came to be permanently dead.
+     *
+     * Deduplicated because the two lists overlap: `placements` already contains the Limits signs.
+     */
+    const isTurnout = kind?.kind === 'track' && kind.geometry === 'turnout';
+    const targets = onMainline
+      ? []
+      : kind?.kind === 'enhancement'
+        ? attachments
+        : isTurnout
+          ? dedupe([...placements, ...attachments])
+          : placements;
     // Orientation is chosen on placement, and a printed card turns but never flips, so the widest
     // variant set is TWO. Anything that is not track has a single orientation and needs one entry.
     const rotations = kind?.kind === 'track' ? variantsFor(kind.geometry, kind.hand).length : 1;
@@ -226,7 +241,8 @@ function loadUnloadCandidates(s: GameState, player: PlayerIndex): Intent[] {
     const f = area.grid.get(`${coord.row},${coord.col}`)?.facility;
     if (f) {
       out.push({ type: 'laborer.startLoad', at: coord });
-      for (let box = 0; box < f.menAtWork.length; box++) {
+      // A Passenger Facility has no MEN | AT | WORK boxes to advance a load along.
+      for (let box = 0; box < (f.menAtWork?.length ?? 0); box++) {
         out.push({ type: 'laborer.advanceLoad', at: coord, box });
       }
       for (let ci = 0; ci < f.industryTrack.cars.length; ci++) {
@@ -248,6 +264,16 @@ function facilityCoords(s: GameState, player: PlayerIndex): GridCoord[] {
   return out;
 }
 
+function dedupe(coords: GridCoord[]): GridCoord[] {
+  const seen = new Set<string>();
+  return coords.filter((c) => {
+    const k = `${c.row},${c.col}`;
+    if (seen.has(k)) return false;
+    seen.add(k);
+    return true;
+  });
+}
+
 /** Empty cells adjacent to occupied ones — `check` decides which actually connect. */
 function placementCandidates(s: GameState, player: PlayerIndex): GridCoord[] {
   const area = areaOf(s, player);

src/engine/setup.ts

@@ -16,6 +16,8 @@ import {
   MOVES_PER_LOCAL_OPS,
   MODIFIER_PROFILES,
   OFFICE_PROFILES,
+  OPENING_OTHER,
+  OPENING_TRACK,
   MAINLINE_PROFILES,
   mainlineProfile,
   TRACK_CARDS,
@@ -173,7 +175,10 @@ function buildPassengerFacility(tier: Parameters<typeof officeProfile>[0]): NonN
     outboundBox: [],
     inboundBox: [],
     capacity: { outbound: p.passengerOut, inbound: p.passengerIn },
-    menAtWork: [null, null, null],
+    // No freight pipeline: a Depot, Station and Terminal work passengers only, and the MEN | AT |
+    // WORK sign is printed "For Freight Facilities" (rules-v0.2.md:452). This was a three-slot array
+    // of nulls, which read as "three empty boxes" to every renderer that looked.
+    menAtWork: null,
     industryTrack: { length: 0, cars: [] },
     laborers: 0,
     porters: p.porters,
@@ -244,21 +249,56 @@ export function createGame(opts: SetupOptions): GameState {
   const superintendent = argmax(superRolls);
   void divisionRolls; // seating is fixed by array order; the roll is recorded for the event log
 
-  // §4.6-4.7 - shuffle, deal three each, then turn three face-up as the Department slots.
+  /**
+   * §4.6-4.7 — THE OPENING DEAL, dealt from two piles rather than one.
+   *
+   * Track is shuffled SEPARATELY from everything else and each player is dealt **3 track cards and 3
+   * other cards**; the track left over is then shuffled back in and the game runs off one deck as
+   * before. The player opens holding six against a limit of three, so the first turn is spent
+   * choosing what to keep — draw as usual, then play or discard down to three (§6.2, enforced on
+   * `draw.end`, which needs no special case for this).
+   *
+   * WHY. A run-around needs five specific pieces in a usable order, and the bot held a turnout and a
+   * matching-hand curve together on **0.2% of turns** — about once every eight games. Measured five
+   * ways, that is a SUPPLY problem and not a bot weakness: 91 run-arounds per 100 games when track
+   * was a private 26-piece supply the player chose from, 29 per 100 once it was drawn, 4 per 60 with
+   * track in the deck. Dealing the opening district as track restores something close to the
+   * prototype's private supply without reintroducing an unbounded one, and makes the opening a
+   * decision rather than a wait.
+   *
+   * PROVISIONAL — flagged for review once it has been played. See `TODO.md`.
+   */
   const deck = buildDeck(config.mode);
   const cards = new Map<CardId, Card>();
   for (const c of deck) cards.set(c.id, c);
 
-  const shuffled = rng.shuffle(deck.map((c) => c.id));
+  const isTrack = (id: CardId): boolean => cards.get(id)?.kind.kind === 'track';
+  const ids = deck.map((c) => c.id);
+  // Shuffled in a fixed order — track first — so the RNG stream is deterministic for a given seed.
+  const trackPile = rng.shuffle(ids.filter(isTrack));
+  const otherPile = rng.shuffle(ids.filter((id) => !isTrack(id)));
+
   const hands = new Map<PlayerIndex, CardId[]>();
-  let cursor = 0;
+  let trackCursor = 0;
+  let otherCursor = 0;
   for (let i = 0; i < playerCount; i++) {
     const p = (superintendent + i) % playerCount;
-    hands.set(p, shuffled.slice(cursor, cursor + 3));
-    cursor += 3;
+    hands.set(p, [
+      ...trackPile.slice(trackCursor, trackCursor + OPENING_TRACK),
+      ...otherPile.slice(otherCursor, otherCursor + OPENING_OTHER),
+    ]);
+    trackCursor += OPENING_TRACK;
+    otherCursor += OPENING_OTHER;
   }
+
+  // The remainder goes back into ONE deck for the rest of the game — the split is an opening-deal
+  // device only, so track competes for the draw exactly as before from the first draw onward.
+  const shuffled = rng.shuffle([...trackPile.slice(trackCursor), ...otherPile.slice(otherCursor)]);
+
   // §4.6-4.7 — three cards turned face up beside the deck. Each is the bottom of a Department pile
-  // that grows as players discard onto it.
+  // that grows as players discard onto it. Taken after the recombination, so a Department slot can
+  // show track like any other card.
+  let cursor = 0;
   const departments: CardId[][] = [[], [], []];
   for (const pile of departments) {
     const card = shuffled[cursor++];

src/engine/state.ts

@@ -150,8 +150,17 @@ export type Facility = {
   outboundBox: RollingStock[];
   inboundBox: RollingStock[];
   capacity: { outbound: number; inbound: number };
-  /** Freight only. One load per box; three boxes, so it is a pipeline (§9.1). */
-  menAtWork: [Load | null, Load | null, Load | null];
+  /**
+   * FREIGHT ONLY — `null` on a Passenger Facility, which is what makes that unrepresentable rather
+   * than merely unused.
+   *
+   * One load per box; three boxes, so it is a pipeline (§9.1). §9.2's passenger work is porters
+   * boarding and detraining with no pipeline at all, and the sign is printed "For Freight
+   * Facilities" (rules-v0.2.md:452). Every Office got a three-slot array anyway, and because it was
+   * an array the renderers happily drew three boxes on a Depot that has no Laborer to work them —
+   * reported from playtesting. Typing it away means a fourth renderer cannot reintroduce the bug.
+   */
+  menAtWork: [Load | null, Load | null, Load | null] | null;
   /** Where cars are spotted for loading and unloading. */
   industryTrack: { length: number; cars: RollingStock[] };
   laborers: number;
@@ -203,7 +212,8 @@ export function isOperationalRail(card: TrackCard): boolean {
  * `isOperationalRail` for exactly that reason.
  */
 export function isLockedByWork(card: TrackCard): boolean {
-  return !!card.facility && card.facility.menAtWork.some((slot) => slot !== null);
+  // A Passenger Facility has no pipeline, so it is never locked by freight work.
+  return !!card.facility?.menAtWork?.some((slot) => slot !== null);
 }
 
 // ---------------------------------------------------------------------------
@@ -263,6 +273,15 @@ export type CrewTray = {
    * runs once and is gone; there is no second visit to claim it on.
    */
   stopPointClaimed?: boolean;
+  /**
+   * X17 Campaign Train — "one turn at station (speeches) then expedite".
+   *
+   * It makes its speech at the first Office it reaches: that arrival is an ordinary stop, and from
+   * then on the train runs expedited, departing every Office in the Stage it arrives. Recorded on the
+   * tray for the same reason as `stopPointClaimed` — it is the TRAIN that stops, and an Extra runs
+   * once, so there is no later visit to hang it on.
+   */
+  speechMade?: boolean;
 };
 
 // ---------------------------------------------------------------------------
@@ -450,6 +469,15 @@ export type TurnState = {
   movesRemaining: number;
   drawnThisTurn: boolean;
   freightAgentUsed: boolean;
+  /**
+   * Trains 3/4 Express — "may drop or pick up ONE freight car at every location".
+   *
+   * Keyed `trayId@row,col`, counting freight cars that train has exchanged on that square this turn.
+   * Per LOCATION rather than per turn, so the Express can work its way along a district a car at a
+   * time — which is what makes it an Express rather than a train that may move one car a Stage.
+   * Cleared with the rest of the turn.
+   */
+  freightWorked: Record<string, number>;
   /** Set when the actor finishes; the phase driver then moves to the next player. */
   done: boolean;
 };
@@ -460,6 +488,7 @@ export function freshTurn(moves: number): TurnState {
     movesRemaining: moves,
     drawnThisTurn: false,
     freightAgentUsed: false,
+    freightWorked: {},
     done: false,
   };
 }

src/engine/track.ts

@@ -123,7 +123,7 @@ export function connectionsFor(card: TrackCard): readonly PortPair[] {
          */
         case 'curved':
         case 'sharpCurved': {
-          const arc = card.geometry.arc ?? (card.geometry.hand === 'right' ? 'se' : 'sw');
+          const arc = card.geometry.arc ?? (card.geometry.hand === 'right' ? 'sw' : 'se');
           return [[arc[0] as Port, arc[1] as Port]];
         }
       }
@@ -131,8 +131,12 @@ export function connectionsFor(card: TrackCard): readonly PortPair[] {
 }
 
 /**
- * A turnout with no stated orientation takes this one — the left-hand card at 0°, i.e. the
+ * A turnout with no stated orientation takes this one — the right-hand card at 0°, i.e. the
  * `ne_sw` slope. Only hand-less fixtures reach it; `variantsFor` always states an orientation.
+ *
+ * The ORIENTATION here is unchanged by the handedness fix; only the word for it moved, because
+ * `ne_sw` is now the right hand. Fixtures that lay a bare turnout get the same physical card as
+ * before, which is what keeps existing tests and saves describing the same board.
  */
 export const DEFAULT_TURNOUT: TurnoutOrientation = { stem: 'w', through: 'e', diverge: 's' };
 
@@ -197,9 +201,24 @@ export function joins(a: TrackCard, p: Port, b: TrackCard): boolean {
  * and south, but never between diagonals.
  *
  * So handedness is not decoration and not merely a supply label: it is the slope, and a siding
- * needs one card of each hand (a left turnout to drop off the main, a right curve to climb back).
- * Which printed row we call "left" is the one arbitrary bit, and it lives entirely in the two
- * tables below.
+ * needs one card of each hand (a right turnout to drop off the main, a left curve to climb back).
+ * Which printed row we call "left" is fixed by the prototype and lives entirely in the two tables
+ * below.
+ *
+ * WHICH ROW IS WHICH. A turnout is named for the side the diverging route leaves toward, seen by a
+ * train entering at the points. Take `{stem:'e', through:'w', diverge:'s'}`: the train enters at the
+ * east edge heading west, and facing west its left hand points south — so a leg going south is a
+ * LEFT-hand turnout. Turn the card 180° and it enters heading east with the leg going north, which
+ * is left again; that invariance under rotation is exactly why the hand can be a property of the
+ * card. Both orientations lie on `nw_se`, so LEFT IS `nw_se`.
+ *
+ * A curve has no points of its own, so it takes its hand from the turnout whose leg it continues —
+ * which is what makes "a run-around needs one card of each hand" true. Both tables therefore put
+ * left on the SAME diagonal: a left turnout's leg lands on `nw_se` and only a left curve can carry
+ * it onward.
+ *
+ * Both tables were inverted until playtesting caught it, so every label named the mirror card. The
+ * geometry was never wrong — the board draws from `connectionsFor` — only the words.
  *
  * §A.1's constraint is preserved: a turnout's two legs still never join each other.
  */
@@ -209,26 +228,27 @@ export type TrackVariant = {
   bypass?: Port;
 };
 
-/** Left-hand cards lie on `ne_sw`, right-hand on `nw_se`; 0° sends the leg south, 180° north. */
+/** Left-hand curves lie on `nw_se`, right-hand on `ne_sw`; 0° sends the leg south, 180° north. */
 const CURVE_VARIANTS: Record<Hand, readonly TrackArc[]> = {
-  left: ['sw', 'ne'],
-  right: ['se', 'nw'],
-  none: ['sw', 'ne'],
+  left: ['se', 'nw'],
+  right: ['sw', 'ne'],
+  none: ['se', 'nw'],
 };
 
+/** Left-hand turnouts lie on `nw_se`, right-hand on `ne_sw` — the same diagonals as the curves. */
 const TURNOUT_VARIANTS: Record<Hand, readonly TurnoutOrientation[]> = {
   left: [
-    { stem: 'w', through: 'e', diverge: 's' },
-    { stem: 'e', through: 'w', diverge: 'n' },
-  ],
-  right: [
     { stem: 'e', through: 'w', diverge: 's' },
     { stem: 'w', through: 'e', diverge: 'n' },
   ],
-  none: [
+  right: [
     { stem: 'w', through: 'e', diverge: 's' },
     { stem: 'e', through: 'w', diverge: 'n' },
   ],
+  none: [
+    { stem: 'e', through: 'w', diverge: 's' },
+    { stem: 'w', through: 'e', diverge: 'n' },
+  ],
 };
 
 export function variantsFor(geometry: TrackGeometry, hand: Hand = 'none'): TrackVariant[] {