typescript-api-legacy-bridge-roster-events

Answer

Root cause (MAF-GAP-013): the legacy engine wrote games straight to the event store without ever emitting a ROLES_ASSIGNED event. The read-model adapter's ROLES_ASSIGNED branch (first-write-wins, fills only UNASSIGNED gaps) was correct but never fired for legacy games, so GET /api/v1/games/:id only had heuristic inference — plain villagers stayed UNASSIGNED. Separately, ?limit was parsed but applied only to the DB rows before legacy rows were merged, so merged games overflowed the requested page size.

1. Bridge: synthesize one ROLES_ASSIGNED at game end

// src/legacy/bridge.ts
import type { LegacyGameEndEvent } from "./legacy-events";
import type { RolesAssignedEvent, EventStore } from "../events";

export class LegacyBridge {
  constructor(
    private readonly legacyBus: LegacyEventBus,
    private readonly store: EventStore,
  ) {}

  start(): void {
    this.legacyBus.on("game.end", this.onGameEnd.bind(this));
  }

  private onGameEnd(legacy: LegacyGameEndEvent): void {
    // Full roster from game.players — fall back p.role -> p.persona.gameRole.
    const roster = legacy.game.players.map((p) => ({
      playerId: p.id,
      role: p.role ?? p.persona?.gameRole ?? "UNASSIGNED",
    }));

    const event: RolesAssignedEvent = {
      type: "ROLES_ASSIGNED",
      gameId: legacy.game.id,
      occurredAt: legacy.endedAt ?? legacy.timestamp,
      roster,
    };

    // Dedupe so replays / duplicate game.end notifications append exactly once.
    this.store.append(event, { dedupeKey: `legacy:${legacy.game.id}:roles` });
  }
}

2. Adapter (pre-existing, shown for contract): first-write-wins

The synthetic event is consumed by the existing branch — it must only fill UNASSIGNED gaps so real assignments (or an earlier roster) are never clobbered:

// src/events/projection.ts
function applyRolesAssigned(state: GameState, evt: RolesAssignedEvent): GameState {
  const players = new Map(state.players.map((p) => [p.playerId, { ...p }]));
  for (const { playerId, role } of evt.roster) {
    const p = players.get(playerId);
    if (!p || p.role !== "UNASSIGNED") continue; // first write wins
    p.role = role; // fill only UNASSIGNED gaps
  }
  return { ...state, players: [...players.values()] };
}

3. Route: apply ?limit after the merge

// src/routes/games.ts
router.get("/api/v1/games/:id", async (req, res) => {
  const limit = parseLimit(req.query.limit); // clamp to 1..100; null if absent

  const dbRows = await gamesRepo.fetchAllRows(req.params.id);   // no limit here
  const legacyRows = await legacyRepo.fetchMerged(req.params.id);
  const merged = dedupeById([...dbRows, ...legacyRows]);

  const page = limit ? merged.slice(0, limit) : merged; // route-level slice AFTER merge
  res.json({ game: projectGame(page) });
});

4. Docs / scripts alignment

• QUICK_START.md / SYSTEM_STATUS.md: examples now list the real routes (GET /api/v1/games, GET /api/v1/games/:id, POST /api/v1/games) and the actual ?limit semantics (applies to merged result).
• package.json — SYSTEM_STATUS exec form corrected (tsx -- → dev --):

// before
"system:status": "tsx -- src/scripts/system-status.ts"
// after
"system:status": "dev -- src/scripts/system-status.ts"