perf: reduce core-sim GC churn 42% and add GC-churn profiling to the perf harness (#4494)

## Summary

Reduces core-simulation GC churn by **42%** on a 20-game-minute Giant
World Map run, and extends the headless full-game perf harness so churn
is measurable and regressions are visible.

### 1. GC-churn measurement (`tests/perf/fullgame/GcProfiler.ts`)

`npm run perf:game` now reports:

- **GC pauses** by kind (minor/major/incremental) via a
`PerformanceObserver` on `'gc'` entries, bucketed into tick windows by
timestamp (V8 only delivers these entries on a timer task, so they're
flushed after the run)
- **Allocation rate** per `--window N` ticks (default 1000) from
used-heap deltas sampled every tick, so churn can be tracked across game
phases
- **Top allocating functions** from the V8 sampling heap profiler with
`includeObjectsCollectedBy{Major,Minor}GC` — i.e. actual churn including
short-lived garbage, not live memory — plus a `.heapprofile` loadable in
Chrome DevTools (Memory → Allocation sampling)

New flags: `--window N`, `--no-gc-profile`, `--no-alloc-profile`.

### 2. Allocation reductions in the hot paths it found

| Site | Change |
|---|---|
| `GameMap.bfs` | inline neighbor enumeration instead of an array per
visited tile |
| `GameMap`/`Game` | new `forEachNeighborNSWE` — allocation-free
iterator matching `neighbors()` N,S,W,E order for order-sensitive
callers (`forEachNeighbor` visits W,E,N,S, so substituting it would
change sim behavior) |
| `PlayerImpl.nearby` / `sharesBorderWith` / `shoreReachableNeighbors` |
no per-call neighbor arrays; no materialized shore-tile array |
| `PlayerImpl.units(types)` | gather into a reusable scratch buffer,
return one exact-size slice (still a fresh snapshot array per call) |
| `AiAttackBehavior.maybeAttack` | single pass over border neighbors
replacing the `flatMap`/`filter`/`map` chain over every border tile |
| `AiAttackBehavior.isBorderingNukedTerritory` | reusable `neighbors4`
buffer with early exit |
| `SharedWaterCache.build` | allocation-free neighbor iteration |
| `SpatialQuery.bfsNearest` | first-minimum scan instead of
collect-then-stable-sort (identical result incl. tie-breaking) |

### Results (Giant World Map, 400 bots, 12,000 ticks ≈ 20 game-minutes,
seed `perf-default`)

| Metric | Before | After |
|---|---|---|
| Sampled allocations (incl. collected) | 97.7 GB | **56.9 GB (−42%)** |
| GC count / total pause | 1,682 / 3,313 ms (1.8% of wall) | 1,058 /
2,087 ms (1.2%) |
| Ticks/sec | 66 | 70 |
| p99 / max tick | 49.9 ms / 988 ms | 43.5 ms / 689 ms |
| Ticks over 100 ms budget | 31 | 19 |

## Determinism

Every rewrite preserves exact iteration order (the new NSWE iterator
exists precisely for the order-sensitive sites). Verified by identical
final game-state hashes on three runs: Giant World Map 12,000 ticks
(`67286276735690560`), Giant World Map 2,000 ticks, and World 1,800
ticks.

## Test plan

- [x] Full suite green (1,896 tests)
- [x] New tests: `forEachNeighborNSWE` order contract vs `neighbors()`
over every tile; `units()` filtering semantics (insertion order,
fresh-array guarantee, duplicate types, Set path)
- [x] Final-hash equality on 3 seeded headless runs (2 maps)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

src/client/view/GameView.ts

@@ -1172,6 +1172,12 @@ export class GameView implements GameMap {
   forEachNeighbor(ref: TileRef, callback: (neighbor: TileRef) => void): void {
     this._map.forEachNeighbor(ref, callback);
   }
+  forEachNeighborNSWE(
+    ref: TileRef,
+    callback: (neighbor: TileRef) => void,
+  ): void {
+    this._map.forEachNeighborNSWE(ref, callback);
+  }
   neighbors4(ref: TileRef, out: TileRef[]): number {
     return this._map.neighbors4(ref, out);
   }

src/core/execution/nation/SharedWaterCache.ts

@@ -48,17 +48,20 @@ export class SharedWaterCache {
 
       let hasOcean = false;
       const lakes = new Set<number>();
+      // The lake set is only membership-tested, so neighbor visit order does
+      // not matter — use the allocation-free iterator.
+      const visit = (neighbor: number) => {
+        if (!game.isWater(neighbor)) return;
+        if (game.isOcean(neighbor)) {
+          hasOcean = true;
+          return;
+        }
+        const comp = game.getWaterComponent(neighbor);
+        if (comp !== null) lakes.add(comp);
+      };
       for (const tile of player.borderTiles()) {
         if (!game.isShore(tile)) continue;
-        for (const neighbor of game.neighbors(tile)) {
-          if (!game.isWater(neighbor)) continue;
-          if (game.isOcean(neighbor)) {
-            hasOcean = true;
-            continue;
-          }
-          const comp = game.getWaterComponent(neighbor);
-          if (comp !== null) lakes.add(comp);
-        }
+        game.forEachNeighbor(tile, visit);
       }
       playerToWater.set(player, { hasOcean, lakes });
 

src/core/execution/utils/AiAttackBehavior.ts

@@ -33,6 +33,9 @@ import {
 import { TransportShipExecution } from "../TransportShipExecution";
 import { closestTwoTiles } from "../Util";
 
+// Reusable neighbor buffer for hot loops; the simulation is single-threaded.
+const NEIGHBOR_SCRATCH: TileRef[] = [0, 0, 0, 0];
+
 export class AiAttackBehavior {
   private botAttackTroopsSent: number = 0;
 
@@ -52,20 +55,24 @@ export class AiAttackBehavior {
       throw new Error("not initialized");
     }
 
-    const border = Array.from(this.player.borderTiles())
-      .flatMap((t) => this.game.neighbors(t))
-      .filter(
-        (t) =>
-          this.game.isLand(t) &&
-          !this.game.isImpassable(t) &&
-          this.game.ownerID(t) !== this.player?.smallID(),
-      );
+    // Neighbor visit order matters here: the set's insertion order feeds the
+    // stable troop-count sort below, so ties keep border-discovery order.
+    const borderingPlayerSet = new Set<Player>();
+    let borderHasNonNukedTerraNullius = false;
+    const smallID = this.player.smallID();
+    const visit = (t: number) => {
+      if (!this.game.isLand(t) || this.game.isImpassable(t)) return;
+      if (this.game.ownerID(t) === smallID) return;
+      const owner = this.game.playerBySmallID(this.game.ownerID(t));
+      if (owner.isPlayer()) borderingPlayerSet.add(owner);
+      if (!this.game.hasOwner(t) && !this.game.hasFallout(t)) {
+        borderHasNonNukedTerraNullius = true;
+      }
+    };
+    for (const t of this.player.borderTiles()) {
+      this.game.forEachNeighborNSWE(t, visit);
+    }
     const playerNeighbors = this.player.nearby();
-    const borderingPlayerSet = new Set<Player>(
-      border
-        .map((t) => this.game.playerBySmallID(this.game.ownerID(t)))
-        .filter((o): o is Player => o.isPlayer()),
-    );
     for (const n of playerNeighbors) {
       if (n.isPlayer()) borderingPlayerSet.add(n);
     }
@@ -81,7 +88,7 @@ export class AiAttackBehavior {
 
     // Attack TerraNullius but not nuked territory (direct border or across a river)
     const hasNonNukedTerraNullius =
-      border.some((t) => !this.game.hasOwner(t) && !this.game.hasFallout(t)) ||
+      borderHasNonNukedTerraNullius ||
       playerNeighbors.some((n) => !n.isPlayer());
     if (hasNonNukedTerraNullius) {
       if (this.sendAttack(this.game.terraNullius())) return;
@@ -548,8 +555,13 @@ export class AiAttackBehavior {
       return false;
     }
 
+    // Boolean result, so neighbor order doesn't matter; a reused scratch
+    // buffer keeps this allocation-free and allows early exit.
+    const nbuf = NEIGHBOR_SCRATCH;
     for (const tile of this.player.borderTiles()) {
-      for (const neighbor of this.game.neighbors(tile)) {
+      const n = this.game.neighbors4(tile, nbuf);
+      for (let i = 0; i < n; i++) {
+        const neighbor = nbuf[i];
         if (
           this.game.isLand(neighbor) &&
           !this.game.hasOwner(neighbor) &&

src/core/game/Game.ts

@@ -705,6 +705,14 @@ export interface Game extends GameMap {
   forEachTile(fn: (tile: TileRef) => void): void;
   // Zero-allocation neighbor iteration (cardinal only) to avoid creating arrays
   forEachNeighbor(tile: TileRef, callback: (neighbor: TileRef) => void): void;
+  // Same, but in neighbors() N, S, W, E order — for order-sensitive code.
+  forEachNeighborNSWE(
+    tile: TileRef,
+    callback: (neighbor: TileRef) => void,
+  ): void;
+  // Writes the cardinal neighbors of ref into out (W, E, N, S order) and
+  // returns the count. Reuse out across calls to avoid allocation.
+  neighbors4(ref: TileRef, out: TileRef[]): number;
   // Zero-allocation neighbor iteration for performance-critical cluster calculation
   // Alternative to neighborsWithDiag() that returns arrays
   // Avoids creating intermediate arrays and uses a callback for better performance

src/core/game/GameImpl.ts

@@ -1134,6 +1134,12 @@ export class GameImpl implements Game {
   forEachNeighbor(tile: TileRef, callback: (neighbor: TileRef) => void): void {
     this._map.forEachNeighbor(tile, callback);
   }
+  forEachNeighborNSWE(
+    tile: TileRef,
+    callback: (neighbor: TileRef) => void,
+  ): void {
+    this._map.forEachNeighborNSWE(tile, callback);
+  }
   neighbors4(ref: TileRef, out: TileRef[]): number {
     return this._map.neighbors4(ref, out);
   }

src/core/game/GameMap.ts

@@ -39,6 +39,14 @@ export interface GameMap {
   neighbors(ref: TileRef): TileRef[];
   // Zero-allocation neighbor iteration (cardinal only), in W, E, N, S order.
   forEachNeighbor(ref: TileRef, callback: (neighbor: TileRef) => void): void;
+  // Zero-allocation neighbor iteration (cardinal only) in the same N, S, W, E
+  // order as neighbors(). Use this in order-sensitive code — anything feeding
+  // sets/arrays whose iteration order affects the simulation — where
+  // forEachNeighbor's W, E, N, S order would change behavior.
+  forEachNeighborNSWE(
+    ref: TileRef,
+    callback: (neighbor: TileRef) => void,
+  ): void;
   // Writes the cardinal neighbors of ref into out (W, E, N, S order) and
   // returns the count. out must have length >= 4; reuse it across calls to
   // avoid allocation in hot loops.
@@ -395,6 +403,19 @@ export class GameMapImpl implements GameMap {
     if (ref < (this.height_ - 1) * w) callback(ref + w);
   }
 
+  forEachNeighborNSWE(
+    ref: TileRef,
+    callback: (neighbor: TileRef) => void,
+  ): void {
+    const w = this.width_;
+    const x = this.refToX[ref];
+
+    if (ref >= w) callback(ref - w);
+    if (ref < (this.height_ - 1) * w) callback(ref + w);
+    if (x !== 0) callback(ref - 1);
+    if (x !== w - 1) callback(ref + 1);
+  }
+
   neighbors4(ref: TileRef, out: TileRef[]): number {
     const w = this.width_;
     const x = this.refToX[ref];
@@ -480,15 +501,24 @@ export class GameMapImpl implements GameMap {
       q.push(tile);
     }
 
+    // Neighbors are enumerated inline in the same order as neighbors() to
+    // avoid allocating an array per visited tile.
+    const w = this.width_;
+    const southLimit = (this.height_ - 1) * w;
+    const visit = (n: TileRef) => {
+      if (!seen.has(n) && filter(this, n)) {
+        seen.add(n);
+        q.push(n);
+      }
+    };
     while (q.length > 0) {
       const curr = q.pop();
       if (curr === undefined) continue;
-      for (const n of this.neighbors(curr)) {
-        if (!seen.has(n) && filter(this, n)) {
-          seen.add(n);
-          q.push(n);
-        }
-      }
+      const x = this.refToX[curr];
+      if (curr >= w) visit(curr - w);
+      if (curr < southLimit) visit(curr + w);
+      if (x !== 0) visit(curr - 1);
+      if (x !== w - 1) visit(curr + 1);
     }
     return seen;
   }

src/core/game/PlayerImpl.ts

@@ -84,6 +84,13 @@ const EMPTY_ATTACK_UPDATES: AttackUpdate[] = [];
 const EMPTY_ALLIANCE_VIEWS: AllianceView[] = [];
 const EMPTY_EMOJIS: EmojiMessage[] = [];
 const EMPTY_EMBARGOES = new Set<string>();
+// Reusable buffers for hot loops. The simulation is single-threaded and these
+// are fully consumed before any re-entrant call, so sharing is safe.
+const NEIGHBOR_SCRATCH: TileRef[] = [0, 0, 0, 0];
+const UNITS_SCRATCH: Unit[] = [];
+// N, S, W, E — the sampling directions used by shoreReachableNeighbors().
+const SHORE_DIRECTIONS_DX = [0, 0, -1, 1];
+const SHORE_DIRECTIONS_DY = [-1, 1, 0, 0];
 Object.freeze(EMPTY_NUMBER_ARRAY);
 Object.freeze(EMPTY_STRING_ARRAY);
 Object.freeze(EMPTY_ATTACK_UPDATES);
@@ -361,53 +368,41 @@ export class PlayerImpl implements Player {
       return this._units;
     }
 
+    // Hot path. Matches are gathered into a reusable scratch buffer and
+    // copied out with an exact-size slice, so each call allocates exactly
+    // one right-sized result array.
+    const scratch = UNITS_SCRATCH;
+    let n = 0;
+
     // Fast paths for common small arity calls to avoid Set allocation.
     if (len === 1) {
       const t0 = types[0]!;
-      const out: Unit[] = [];
       for (const u of this._units) {
-        if (u.type() === t0) out.push(u);
+        if (u.type() === t0) scratch[n++] = u;
       }
-      return out;
-    }
-
-    if (len === 2) {
+    } else if (len === 2) {
       const t0 = types[0]!;
       const t1 = types[1]!;
-      if (t0 === t1) {
-        const out: Unit[] = [];
-        for (const u of this._units) {
-          if (u.type() === t0) out.push(u);
-        }
-        return out;
-      }
-      const out: Unit[] = [];
       for (const u of this._units) {
         const t = u.type();
-        if (t === t0 || t === t1) out.push(u);
+        if (t === t0 || t === t1) scratch[n++] = u;
       }
-      return out;
-    }
-
-    if (len === 3) {
+    } else if (len === 3) {
       const t0 = types[0]!;
       const t1 = types[1]!;
       const t2 = types[2]!;
       // Keep semantics identical for duplicates in types by using direct comparisons.
-      const out: Unit[] = [];
       for (const u of this._units) {
         const t = u.type();
-        if (t === t0 || t === t1 || t === t2) out.push(u);
+        if (t === t0 || t === t1 || t === t2) scratch[n++] = u;
+      }
+    } else {
+      const ts = new Set(types);
+      for (const u of this._units) {
+        if (ts.has(u.type())) scratch[n++] = u;
       }
-      return out;
     }
-
-    const ts = new Set(types);
-    const out: Unit[] = [];
-    for (const u of this._units) {
-      if (ts.has(u.type())) out.push(u);
-    }
-    return out;
+    return scratch.slice(0, n);
   }
 
   private numUnitsConstructed: Partial<Record<UnitType, number>> = {};
@@ -454,9 +449,13 @@ export class PlayerImpl implements Player {
   }
 
   sharesBorderWith(other: Player | TerraNullius): boolean {
+    const map = this.mg.map();
+    const otherID = other.smallID();
+    const nbuf = NEIGHBOR_SCRATCH;
     for (const border of this._borderTiles) {
-      for (const neighbor of this.mg.map().neighbors(border)) {
-        if (this.mg.map().ownerID(neighbor) === other.smallID()) {
+      const n = map.neighbors4(border, nbuf);
+      for (let i = 0; i < n; i++) {
+        if (map.ownerID(nbuf[i]) === otherID) {
           return true;
         }
       }
@@ -478,26 +477,23 @@ export class PlayerImpl implements Player {
 
   nearby(): (Player | TerraNullius)[] {
     const ns: Set<Player | TerraNullius> = new Set();
-    for (const border of this.borderTiles()) {
-      for (const neighbor of this.mg.map().neighbors(border)) {
-        if (
-          this.mg.map().isLand(neighbor) &&
-          !this.mg.map().isImpassable(neighbor)
-        ) {
-          if (
-            !this.mg.map().hasOwner(neighbor) &&
-            this.mg.map().hasFallout(neighbor)
-          ) {
-            continue;
-          }
-          const owner = this.mg.map().ownerID(neighbor);
-          if (owner !== this.smallID()) {
-            ns.add(
-              this.mg.playerBySmallID(owner) satisfies Player | TerraNullius,
-            );
-          }
+    const map = this.mg.map();
+    const smallID = this.smallID();
+    const visit = (neighbor: TileRef) => {
+      if (map.isLand(neighbor) && !map.isImpassable(neighbor)) {
+        if (!map.hasOwner(neighbor) && map.hasFallout(neighbor)) {
+          return;
+        }
+        const owner = map.ownerID(neighbor);
+        if (owner !== smallID) {
+          ns.add(
+            this.mg.playerBySmallID(owner) satisfies Player | TerraNullius,
+          );
         }
       }
+    };
+    for (const border of this.borderTiles()) {
+      map.forEachNeighborNSWE(border, visit);
     }
     for (const n of this.shoreReachableNeighbors()) {
       ns.add(n);
@@ -511,21 +507,19 @@ export class PlayerImpl implements Player {
   private shoreReachableNeighbors(): Set<Player | TerraNullius> {
     const ns: Set<Player | TerraNullius> = new Set();
     const map = this.mg.map();
-    const shores = Array.from(this.borderTiles()).filter((t) => map.isShore(t));
-    const directions: [number, number][] = [
-      [0, -1],
-      [0, 1],
-      [-1, 0],
-      [1, 0],
-    ];
 
-    for (let i = 0; i < shores.length; i += 10) {
-      const border = shores[i];
+    let shoreIdx = 0;
+    for (const border of this.borderTiles()) {
+      if (!map.isShore(border)) continue;
+      // Visit every 10th shore tile.
+      if (shoreIdx++ % 10 !== 0) continue;
 
       const bx = map.x(border);
       const by = map.y(border);
 
-      for (const [dx, dy] of directions) {
+      for (let d = 0; d < 4; d++) {
+        const dx = SHORE_DIRECTIONS_DX[d];
+        const dy = SHORE_DIRECTIONS_DY[d];
         // Only follow directions that immediately enter water; land-adjacent
         // directions are already covered by the direct neighbors() loop.
         const x1 = bx + dx;

src/core/pathfinding/spatial/SpatialQuery.ts

@@ -32,25 +32,25 @@ export class SpatialQuery {
     predicate: (t: TileRef) => boolean,
   ): TileRef | null {
     const map = this.game.map();
-    const candidates: TileRef[] = [];
 
+    // Strict < keeps the first candidate on distance ties, so the winner
+    // depends only on the deterministic BFS visit order.
+    let best: TileRef | null = null;
+    let bestDist = Infinity;
     for (const tile of map.bfs(
       from,
       (_, t) => map.manhattanDist(from, t) <= maxDist,
     )) {
       if (predicate(tile)) {
-        candidates.push(tile);
+        const dist = map.manhattanDist(from, tile);
+        if (dist < bestDist) {
+          best = tile;
+          bestDist = dist;
+        }
       }
     }
 
-    if (candidates.length === 0) return null;
-
-    // Sort by Manhattan distance to find actual nearest
-    candidates.sort(
-      (a, b) => map.manhattanDist(from, a) - map.manhattanDist(from, b),
-    );
-
-    return candidates[0];
+    return best;
   }
 
   /**