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);