madden-fantasy-extractor 0.2.0

package/src/extract/payload.js

@@ -0,0 +1,125 @@
+// Assembles the full stat_import payload by running every extractor against one
+// opened franchise save. Mirrors db/schema.sql's table shapes closely enough that
+// ingest can map each array 1:1 onto an INSERT, but stays in "extracted" shape
+// (external_*_id, not surrogate ids — those don't exist until ingest mints them).
+//
+// Incremental capture: `games` (and the playerGameStats/teamGameStats keyed off it)
+// are restricted, by default, to games newly decided since the last successful run —
+// see src/lib/incremental.js for why that's a different set than "every decided game
+// in the save," and why player_week_status deliberately does NOT go through the same
+// filter (it needs the full schedule for bye detection and to resolve the completed
+// week, independent of which games' stats have already been captured).
+
+import { extractClock } from './clock.js';
+import { extractTeams, indexTeamsByTeamIndex } from './teams.js';
+import { extractPlayers } from './players.js';
+import { extractGames, gameKey } from './games.js';
+import { extractPlayerGameStats } from './player-game-stats.js';
+import { extractTeamGameStats, indexPlayerGameStatsByGameAndTeam } from './team-game-stats.js';
+import { extractPlayerWeekStatus } from './player-week-status.js';
+import { extractTransactions } from './transactions.js';
+import { extractCumulativeStats } from './cumulative-stats.js';
+import { extractDepthChart } from './depth-chart.js';
+import { selectGamesToCapture, selectReadyGames, selectPendingGames, unionCapturedKeys } from '../lib/incremental.js';
+
+const PAYLOAD_SCHEMA_VERSION = '1.0.0';
+
+export async function buildPayload(franchise, { toolVersion, fullMode = false, capturedGameKeys = new Set() }) {
+  const clock = await extractClock(franchise);
+  const teams = await extractTeams(franchise);
+  const teamIdx = indexTeamsByTeamIndex(teams);
+
+  const allGames = await extractGames(franchise, { indexTeamsByTeamIndex: teamIdx });
+
+  const gamesToCapture = selectGamesToCapture(allGames, {
+    fullMode,
+    seasonIndex: clock.seasonIndex,
+    alreadyCapturedKeys: capturedGameKeys,
+  });
+  const gamesByKey = new Map(gamesToCapture.map((g) => [gameKey(g), g]));
+
+  const players = await extractPlayers(franchise, { currentSeasonYear: clock.calendarYear });
+
+  const playerGameStats = await extractPlayerGameStats(franchise, {
+    players,
+    gamesByKey,
+    indexTeamsByTeamIndex: teamIdx,
+  });
+
+  const pgsIndex = indexPlayerGameStatsByGameAndTeam(playerGameStats, players, teamIdx);
+  const teamGameStats = await extractTeamGameStats(franchise, {
+    games: gamesToCapture,
+    playerGameStatsByGameAndTeam: pgsIndex,
+    indexTeamsByTeamIndex: teamIdx,
+  });
+
+  // Deliberately allGames, not gamesToCapture: bye detection and resolving "the most
+  // recently completed week" both need the full schedule regardless of the
+  // incremental watermark — see this module's header and player-week-status.js's own.
+  const playerWeekStatus = await extractPlayerWeekStatus(franchise, {
+    players,
+    games: allGames,
+    clock,
+    indexTeamsByTeamIndex: teamIdx,
+  });
+
+  const transactions = await extractTransactions(franchise, { indexTeamsByTeamIndex: teamIdx });
+  const cumulativeStats = await extractCumulativeStats(franchise, { players });
+  const depthChart = await extractDepthChart(franchise, { teams });
+
+  // Only games that ACTUALLY produced player-level stats this run get added to the
+  // watermark (PreSeason excepted — see incremental.js's selectReadyGames) — "decided"
+  // (schedule/TeamStats) is not a safe readiness signal for player_game_stat. Anything
+  // else included this run is still sitting in the retry queue; surfaced below as
+  // pendingPlayerStatGameKeys so it doesn't take a diff against playerGameStats to see.
+  const readyGames = selectReadyGames(gamesToCapture, playerGameStats);
+  const pendingGames = selectPendingGames(gamesToCapture, playerGameStats);
+  const pendingPlayerStatGameKeys = pendingGames.map((g) => gameKey(g));
+
+  const payload = {
+    payloadSchemaVersion: PAYLOAD_SCHEMA_VERSION,
+    toolVersion,
+    gameSchemaVersion: formatGameSchemaVersion(franchise),
+    capturedAt: new Date().toISOString(),
+    // A hint for ingest's stat_import.status, not authoritative — ingest still owns
+    // that column and may reject or otherwise override this. 'partial' means: every
+    // game below is real and safe to upsert, but pendingPlayerStatGameKeys lists ones
+    // whose player_game_stat rows aren't in THIS payload yet and will arrive in a
+    // later import once the lag resolves (see docs/extraction-findings.md §3.5/§3.6).
+    suggestedStatus: pendingPlayerStatGameKeys.length > 0 ? 'partial' : 'accepted',
+
+    clock,
+
+    teams: teams.map(stripRecord),
+    players: players.map(({ _record, ...rest }) => rest),
+    games: gamesToCapture.map(({ _record, ...rest }) => ({ ...rest, gameKey: gameKey(rest) })),
+
+    playerGameStats,
+    teamGameStats,
+    pendingPlayerStatGameKeys,
+    playerWeekStatus,
+    transactions,
+    cumulativeStats,
+    depthChart,
+  };
+
+  const nextCapturedGameKeys = unionCapturedKeys(capturedGameKeys, readyGames, clock.seasonIndex);
+
+  return {
+    payload,
+    nextCapturedGameKeys,
+    gamesIncludedCount: gamesToCapture.length,
+    gamesTotalCount: allGames.length,
+    pendingCount: pendingGames.length,
+  };
+}
+
+function stripRecord({ _record, ...rest }) {
+  return rest;
+}
+
+function formatGameSchemaVersion(franchise) {
+  const v = franchise.expectedSchemaVersion;
+  if (!v) return null;
+  return `madden${franchise.gameYear}-${v.major}.${v.minor}`;
+}

package/src/extract/player-game-stats.js

@@ -0,0 +1,86 @@
+// Extracts player_game_stat: one row per (player, game, stat_category).
+//
+// Player.GameStats -> GameStats[] wrapper -> N slots, each a reference into ONE of six
+// position-bucketed tables (GameOffensiveStats, GameDefensiveStats, GameKickingStats,
+// GameOLineStats, GameOffensiveKPReturnStats, GameDefensiveKPReturnStats). The wrapper
+// doesn't say which table a slot resolves to — resolveWrapperSlots just returns the
+// record, so we key the field map lookup off the field names actually present.
+//
+// findings.md §2: a row exists iff the player played; GameStats[]'s nominal slot count
+// is not a ceiling (confirmed 20+ filled through a Super Bowl run) — iterate whatever's
+// there. Some rows have a null SeasonGame ref (preseason/template) — dropped below.
+
+import { resolveGameStatRows, resolveFieldRef } from '../lib/franchise-table.js';
+import { PLAYER_STAT_FIELD_MAP } from '../lib/stat-categories.js';
+import { gameKey } from './games.js';
+
+export async function extractPlayerGameStats(franchise, { players, gamesByKey, indexTeamsByTeamIndex }) {
+  const rows = [];
+  // A game's ~46 rostered players all resolve the same SeasonGame record instance
+  // (the underlying table caches records[]) — memoize the team-ref resolution per
+  // record rather than repeating two more reference lookups per player.
+  const keyCache = new WeakMap();
+
+  for (const player of players) {
+    const statRecords = await resolveGameStatRows(franchise, player._record);
+
+    for (const statRecord of statRecords) {
+      const seasonGame = await resolveFieldRef(franchise, statRecord, 'SeasonGame');
+      if (!seasonGame) continue; // null SeasonGame ref — template/preseason junk row
+
+      let key = keyCache.get(seasonGame);
+      if (key === undefined) {
+        key = await seasonGameKeyFromRecord(franchise, seasonGame, indexTeamsByTeamIndex);
+        keyCache.set(seasonGame, key);
+      }
+      if (!key) continue; // unresolvable team refs on this SeasonGame row
+      const game = gamesByKey.get(key);
+      if (!game) continue; // e.g. dropped Unscheduled/Invalid_ game
+
+      for (const field of statRecord.fieldsArray) {
+        const categoryKey = PLAYER_STAT_FIELD_MAP[field.key];
+        if (!categoryKey) continue;
+        const value = statRecord[field.key];
+        // Zero-skip is safe here: v_player_game_points (the only player-level scoring
+        // view — db/schema.sql) only ever joins rule_type='linear' rules, where
+        // points = value * points_per_unit. SUM over zero matching rows and SUM over
+        // one row worth 0 points are identical, so an all-zero category (e.g. a QB's
+        // rec_yards) costs storage for no scoring difference. There is no tiered
+        // player-level scoring path in this schema — tiered is a team/D-ST-only
+        // concept (see the exception carved out in team-game-stats.js) — so this
+        // check can be unconditional here, unlike the team-stat extractor.
+        if (!value) continue; // undefined, null, or 0
+
+        rows.push({
+          externalPlayerId: player.externalPlayerId,
+          gameKey: key,
+          statCategoryKey: categoryKey,
+          value,
+          source: 'native',
+        });
+      }
+    }
+  }
+
+  return rows;
+}
+
+// Same natural key as games.gameKey, but derived directly from a stat row's own
+// SeasonGame ref (not an already-extracted game object) — this is how a
+// player_game_stat row finds its sim_game without a second player_id-shaped join.
+async function seasonGameKeyFromRecord(franchise, seasonGameRecord, indexTeamsByTeamIndex) {
+  const homeTeamRecord = await resolveFieldRef(franchise, seasonGameRecord, 'HomeTeam');
+  const awayTeamRecord = await resolveFieldRef(franchise, seasonGameRecord, 'AwayTeam');
+  if (!homeTeamRecord || !awayTeamRecord) return null;
+
+  const homeTeam = indexTeamsByTeamIndex.get(homeTeamRecord.TeamIndex);
+  const awayTeam = indexTeamsByTeamIndex.get(awayTeamRecord.TeamIndex);
+  if (!homeTeam || !awayTeam) return null;
+
+  return gameKey({
+    seasonWeekType: seasonGameRecord.SeasonWeekType,
+    seasonWeek: seasonGameRecord.SeasonWeek,
+    homeExternalTeamId: homeTeam.externalTeamId,
+    awayExternalTeamId: awayTeam.externalTeamId,
+  });
+}

package/src/extract/player-week-status.js

@@ -0,0 +1,189 @@
+// Extracts player_week_status for TWO weeks every run, not one — a forward-looking
+// row for the week about to be played, and a backward-looking row for the most
+// recently COMPLETED week. They answer different questions and neither can stand in
+// for the other:
+//
+//   predictive (week = clock.weekType/weekIndex, i.e. "now"):
+//     "Is this player available for THIS week's lineup decisions?" InjuryStatus,
+//     ContractStatus, and the schedule are all live Player/SeasonGame fields with NO
+//     GameStats-style lag — confirmed directly against real saves (a slow-simmed
+//     game's newly-injured player appeared in the very next save, zero delay; see
+//     docs/extraction-findings.md §3.7). So injured/bye/free_agent are exactly as
+//     fresh as the save itself. What's NOT knowable yet is whether a healthy,
+//     rostered player will actually take the field (a late healthy scratch) — that's
+//     inherently a post-game fact. This mode therefore never reports 'inactive';
+//     healthy + rostered + team-has-a-game-this-week reads as 'active' by default,
+//     same spirit as the schema's "fantasy points computed live, frozen only at
+//     finalize" philosophy (db/schema.sql invariant on matchup.*_points_final) — this
+//     row is provisional until the retrospective pass for the SAME week (below,
+//     emitted once this week becomes the completed one) upserts over it with
+//     confirmed data. UNIQUE(player_id, franchise_week_id) makes that upsert automatic.
+//
+//   retrospective (week = clock.weekIndex - 1, i.e. "last week, confirmed"):
+//     "Did this player actually play last week?" This is the ONLY mode that can
+//     distinguish a genuine healthy scratch ('inactive') from a player who simply
+//     hasn't had their stats attributed yet, which matters because of the OTHER
+//     discovery below: SeasonInfo.CurrentWeek identifies the week about to be played,
+//     not the last one finished, and a player's GameStats[] wrapper only gains a slot
+//     once that week is fully processed — confirmed with a consistent 1-week lag
+//     across 5 saves spanning a full season (worse for instant-CPU-simmed games
+//     specifically; see docs/extraction-findings.md §3.5/§3.6). By the time a save
+//     reports CurrentWeek=N, the schedule for week N may already show decided scores,
+//     but per-player GameStats rows only go up to week N-1. This mode reports status
+//     as of clock.weekIndex - 1 accordingly, and derives that week's actual weekType
+//     from the schedule rather than assuming it matches the current week's type —
+//     necessary because SeasonGame.SeasonWeek resets to 0 independently at the start
+//     of RegularSeason and at each playoff round (WildcardPlayoff starts at index 18
+//     while index 17 is still RegularSeason).
+//
+// All non-derived fields live directly on Player (findings.md §5).
+//
+// status derivation (schema.sql comment on player_week_status):
+//   injured  = InjuryStatus='Injured'
+//   bye      = team had no SeasonGame this week
+//   inactive = healthy, no GameStats row for the week (healthy scratch) — RETROSPECTIVE ONLY
+//   active   = played (retrospective) / expected to play, nothing known against it (predictive)
+//   free_agent = ContractStatus='FreeAgent' (TeamIndex=32 pool)
+
+import { resolveFieldRef, resolveGameStatRows } from '../lib/franchise-table.js';
+
+export async function extractPlayerWeekStatus(franchise, { players, games, clock, indexTeamsByTeamIndex }) {
+  if (clock.stage !== 'NFLSeason') return []; // schema.sql: no meaningful "played this week" for OffSeason rows
+
+  const rows = [];
+
+  // Predictive: the week about to be played. No ambiguity in resolving it (unlike
+  // completedWeek below) — clock.weekType/weekIndex ARE SeasonInfo.CurrentWeekType/
+  // CurrentWeek directly, nothing to derive. Also computable at weekIndex 0, unlike
+  // the retrospective pass, since it has no "prior week" dependency.
+  const currentWeek = { weekType: clock.weekType, weekIndex: clock.weekIndex };
+  for (const player of players) {
+    rows.push(buildPredictiveRow(player, games, currentWeek, indexTeamsByTeamIndex));
+  }
+
+  // Retrospective: the most recently completed week, only resolvable once one exists.
+  if (clock.weekIndex > 0) {
+    const completedWeek = findCompletedWeek(games, clock);
+    if (completedWeek) {
+      for (const player of players) {
+        rows.push(await buildRetrospectiveRow(franchise, player, games, completedWeek, indexTeamsByTeamIndex));
+      }
+    }
+  }
+
+  return rows;
+}
+
+function teamsPlayingWeek(games, week) {
+  const teams = new Set();
+  for (const g of games) {
+    if (g.seasonWeekType !== week.weekType || g.seasonWeek !== week.weekIndex) continue;
+    teams.add(g.homeExternalTeamId);
+    teams.add(g.awayExternalTeamId);
+  }
+  return teams;
+}
+
+function buildPredictiveRow(player, games, week, indexTeamsByTeamIndex) {
+  const r = player._record;
+  const isFreeAgent = r.ContractStatus === 'FreeAgent';
+  const isInjured = r.InjuryStatus === 'Injured';
+  const team = indexTeamsByTeamIndex.get(player.teamIndex);
+
+  let status;
+  if (isFreeAgent) {
+    status = 'free_agent';
+  } else if (isInjured) {
+    status = 'injured';
+  } else if (!team || !teamsPlayingWeek(games, week).has(team.externalTeamId)) {
+    status = 'bye';
+  } else {
+    // Can't know "played" ahead of kickoff — a late healthy scratch is a post-game
+    // fact. Healthy + rostered + scheduled reads as active; see module header.
+    status = 'active';
+  }
+
+  return statusRow(player, week, status, isInjured, r);
+}
+
+async function buildRetrospectiveRow(franchise, player, games, week, indexTeamsByTeamIndex) {
+  const r = player._record;
+  const isFreeAgent = r.ContractStatus === 'FreeAgent';
+  const isInjured = r.InjuryStatus === 'Injured';
+  const team = indexTeamsByTeamIndex.get(player.teamIndex);
+
+  let status;
+  if (isFreeAgent) {
+    status = 'free_agent';
+  } else if (isInjured) {
+    status = 'injured';
+  } else if (!team || !teamsPlayingWeek(games, week).has(team.externalTeamId)) {
+    status = 'bye';
+  } else {
+    status = (await hasStatRowForWeek(franchise, r, week)) ? 'active' : 'inactive';
+  }
+
+  return statusRow(player, week, status, isInjured, r);
+}
+
+function statusRow(player, week, status, isInjured, r) {
+  return {
+    externalPlayerId: player.externalPlayerId,
+    weekType: week.weekType,
+    weekIndex: week.weekIndex,
+    status,
+    injuryType: isInjured ? r.InjuryType : null,
+    injurySeverity: isInjured ? r.InjurySeverity : null,
+    // Min can go negative in the save — clamp at 0 (schema.sql comment).
+    minWeeksOut: isInjured ? Math.max(0, r.MinInjuryDuration) : null,
+    maxWeeksOut: isInjured ? Math.max(0, r.MaxInjuryDuration) : null,
+    isInjuredReserve: Boolean(r.IsInjuredReserve),
+    // 30 is the sentinel for "not season-ending" — but it's also the DEFAULT value
+    // on players who were never injured at all, so gate on isInjured first or every
+    // healthy player's stale 0 reads as a season-ender.
+    isSeasonEnding: isInjured && r.CurrentYearSeasonEndingInjuryWeek !== 30,
+  };
+}
+
+// clock.weekIndex is monotonic from RegularSeason through the playoffs (confirmed:
+// RegularSeason runs 0..17, WildcardPlayoff starts at 18 and continues the SAME
+// counter rather than resetting — findings.md §3). But it is NOT safely monotonic
+// across the PreSeason -> RegularSeason boundary: both stages independently index
+// SeasonGame.SeasonWeek from 0 (confirmed directly: a save's PreSeason games occupy
+// SeasonWeek 0-2 while RegularSeason ALSO occupies 0-17 in the same save), so
+// "index - 1" is genuinely ambiguous exactly at RegularSeason week 0 — it could mean
+// PreSeason's last week or nothing at all, and this repo has no save evidence of
+// CurrentWeek's behavior during the PreSeason stage to disambiguate it.
+//
+// Strategy: prefer a game at (currentWeekType, targetIndex) — the common case, and
+// also what correctly resolves the RegularSeason -> WildcardPlayoff transition
+// (targetIndex won't exist under WildcardPlayoff, forcing the fallback below to find
+// the true RegularSeason week 17). Only fall back to a same-index search across
+// OTHER types when the current type has no such week.
+//
+// The one confirmed-ambiguous case — RegularSeason week 0 rolling back into
+// PreSeason — never reaches this function: extractPlayerWeekStatus only calls it
+// when clock.weekIndex > 0.
+function findCompletedWeek(games, clock) {
+  const targetIndex = clock.weekIndex - 1;
+
+  const sameType = games.find((g) => g.seasonWeekType === clock.weekType && g.seasonWeek === targetIndex);
+  if (sameType) return { weekType: clock.weekType, weekIndex: targetIndex };
+
+  const otherType = games.find((g) => g.seasonWeekType !== clock.weekType && g.seasonWeek === targetIndex);
+  if (otherType) return { weekType: otherType.seasonWeekType, weekIndex: targetIndex };
+
+  return null;
+}
+
+async function hasStatRowForWeek(franchise, playerRecord, week) {
+  const statRecords = await resolveGameStatRows(franchise, playerRecord);
+  for (const statRecord of statRecords) {
+    const seasonGame = await resolveFieldRef(franchise, statRecord, 'SeasonGame');
+    if (!seasonGame) continue;
+    if (seasonGame.SeasonWeekType === week.weekType && seasonGame.SeasonWeek === week.weekIndex) {
+      return true;
+    }
+  }
+  return false;
+}

package/src/extract/players.js

@@ -0,0 +1,74 @@
+// Extracts `player` (immutable identity) and `player_season_snapshot` (mutable
+// per-season attributes) rows. See docs/extraction-findings.md §1, §9 and
+// src/lib/identity.js for the identity_key decode-then-hash design.
+
+import { getTableByNameAndCapacity, liveRecords } from '../lib/franchise-table.js';
+import { decodeDraftYear, computeIdentityKey, isIngestiblePlayer } from '../lib/identity.js';
+
+export async function extractPlayers(franchise, { currentSeasonYear }) {
+  const table = await getTableByNameAndCapacity(franchise, 'Player');
+  const records = liveRecords(table).filter(isIngestiblePlayer);
+
+  const players = [];
+  for (const r of records) {
+    const draftYear = decodeDraftYear(r.YearDrafted, currentSeasonYear);
+    const { identityKey, identityBasis } = computeIdentityKey({
+      firstName: r.FirstName,
+      lastName: r.LastName,
+      draftYear,
+      draftRound: r.PLYR_DRAFTROUND,
+      draftPick: r.PLYR_DRAFTPICK,
+    });
+
+    players.push({
+      externalPlayerId: r.PresentationId,
+      identityKey,
+      identityBasis,
+      firstName: r.FirstName,
+      lastName: r.LastName,
+      draftYear,
+      draftRound: r.PLYR_DRAFTROUND,
+      draftPick: r.PLYR_DRAFTPICK,
+      assetName: r.PLYR_ASSETNAME || null,
+
+      // carried through for downstream extraction (team membership, snapshot, stats)
+      // without re-scanning the Player table — not part of the `player` table shape.
+      teamIndex: r.TeamIndex,
+      contractStatus: r.ContractStatus,
+
+      snapshot: extractSnapshot(r),
+
+      // raw record kept for other extractors (stats, injuries, transactions) that
+      // need to walk this same player's reference fields (GameStats, etc.) without
+      // re-reading the Player table.
+      _record: r,
+    });
+  }
+  return players;
+}
+
+function extractSnapshot(r) {
+  return {
+    position: r.Position,
+    overallRating: r.OverallRating,
+    age: r.Age,
+    yearsPro: r.YearsPro,
+    devTrait: r.TraitDevelopment,
+    careerPhase: r.PLYR_CAREERPHASE,
+    isLegend: Boolean(r.IsLegend),
+    ratingsJson: extractRatings(r),
+  };
+}
+
+// Current ratings only (excludes OriginalXRating baseline fields — those are the
+// player's rating before this season's progression, not needed for a snapshot of
+// "what they are right now").
+function extractRatings(r) {
+  const ratings = {};
+  for (const field of r.fieldsArray) {
+    if (field.key.endsWith('Rating') && !field.key.startsWith('Original')) {
+      ratings[field.key] = r[field.key];
+    }
+  }
+  return ratings;
+}

package/src/extract/team-game-stats.js

@@ -0,0 +1,153 @@
+// Extracts team_game_stat: one row per (team, game, stat_category), covering D/ST
+// scoring inputs. findings.md §8: reach per-game TeamStats rows via
+// SeasonGame.Home/AwayTeamStatCache — never scan TeamStats blind (it mixes
+// per-game and aggregate/all-time rows).
+//
+// Native categories (dst_sacks, dst_takeaways, two_point_conversions) come straight
+// off TeamStats. The derived_calc categories in the schema seed (dst_points_allowed,
+// dst_yards_allowed, dst_tds, dst_safeties) are computed here rather than deferred to
+// ingest, because the extractor already has every input in hand and a self-contained
+// payload is more useful to ingest than a partial one:
+//   - dst_points_allowed / dst_yards_allowed: read straight off the opponent's side
+//     of the same SeasonGame / TeamStats rows already resolved for this game.
+//   - dst_tds / dst_safeties: a defense's TDs/safeties are scored BY that team's own
+//     players on defense/special teams, so this sums def_int_tds + def_fumble_tds +
+//     kick_return_tds + punt_return_tds (+ def_safeties) across every player who
+//     fielded a stat row in this game AND belongs to that team.
+//     CAVEAT: attribution uses each player's CURRENT roster TeamIndex (as of this
+//     save read), not their team at the time that historical game was played — the
+//     save carries no per-game roster snapshot, only Player.TeamIndex "as of now"
+//     (see docs/extraction-findings.md §7). A player traded mid-season will have
+//     their pre-trade defensive TDs attributed to their POST-trade team once this
+//     runs against a later save. This only affects backfilled history for players
+//     who changed teams; weekly imports captured before a trade are unaffected
+//     because the player's TeamIndex was still correct at that read. Acceptable
+//     given how rare defensive-player trades with return/INT TDs are, but a known
+//     gap — fixing it needs sim_transaction-based team-at-time-of-game resolution,
+//     which is a fantasy_league_season/ingest-side concern, not this extractor's.
+
+import { resolveFieldRef } from '../lib/franchise-table.js';
+import { TEAM_STAT_FIELD_MAP } from '../lib/stat-categories.js';
+
+const DEFENSIVE_TD_KEYS = new Set(['def_int_tds', 'def_fumble_tds', 'kick_return_tds', 'punt_return_tds']);
+
+export async function extractTeamGameStats(franchise, { games, playerGameStatsByGameAndTeam, indexTeamsByTeamIndex }) {
+  const rows = [];
+
+  for (const game of games) {
+    const homeTeamRecord = await resolveFieldRef(franchise, game._record, 'HomeTeam');
+    const awayTeamRecord = await resolveFieldRef(franchise, game._record, 'AwayTeam');
+    if (!homeTeamRecord || !awayTeamRecord) continue;
+
+    const home = indexTeamsByTeamIndex.get(homeTeamRecord.TeamIndex);
+    const away = indexTeamsByTeamIndex.get(awayTeamRecord.TeamIndex);
+    if (!home || !away) continue;
+
+    const homeStatCache = await resolveFieldRef(franchise, game._record, 'HomeTeamStatCache');
+    const awayStatCache = await resolveFieldRef(franchise, game._record, 'AwayTeamStatCache');
+    const key = gameKeyOf(game);
+
+    if (homeStatCache) {
+      rows.push(
+        ...buildTeamRows({
+          team: home,
+          key,
+          ownStatCache: homeStatCache,
+          opponentScore: game.awayScore,
+          playerStats: playerGameStatsByGameAndTeam.get(`${key}:${home.externalTeamId}`) ?? [],
+        }),
+      );
+    }
+    if (awayStatCache) {
+      rows.push(
+        ...buildTeamRows({
+          team: away,
+          key,
+          ownStatCache: awayStatCache,
+          opponentScore: game.homeScore,
+          playerStats: playerGameStatsByGameAndTeam.get(`${key}:${away.externalTeamId}`) ?? [],
+        }),
+      );
+    }
+  }
+
+  return rows;
+}
+
+function buildTeamRows({ team, key, ownStatCache, opponentScore, playerStats }) {
+  const out = [];
+
+  // TEAM_STAT_FIELD_MAP (dst_sacks, dst_takeaways, two_point_conversions) are counting
+  // stats scored LINEAR in the seed ruleset (value * points_per_unit) — same
+  // zero-skip-is-safe reasoning as player-game-stats.js: a missing row and a
+  // value=0 row sum to the same points.
+  for (const [field, categoryKey] of Object.entries(TEAM_STAT_FIELD_MAP)) {
+    const value = ownStatCache[field];
+    if (!value) continue; // undefined, null, or 0
+    out.push(teamRow(team, key, categoryKey, value, 'native'));
+  }
+
+  // dst_yards_allowed / dst_points_allowed are NOT safe to zero-skip. The schema seed
+  // documents both as "almost always TIERED, not linear" (db/schema.sql) — tiered
+  // scoring (v_team_game_tier_points) is a bucket lookup via an INNER JOIN on
+  // scoring_rule_tier, not a multiply, and 0 is typically the BEST bucket (the seed
+  // ruleset's own points-allowed table pays a 10 pt bonus for the 0-0 band — a
+  // shutout). Skipping the row on a shutout would mean v_fantasy_slot_points's
+  // COALESCE(...,0) fallback silently scores it as 0 instead of the correct bonus.
+  // These two are therefore always emitted whenever the underlying value is present,
+  // regardless of whether that value is zero.
+  if (ownStatCache.DEFPASSYARDS != null && ownStatCache.DEFRUSHYARDS != null) {
+    out.push(
+      teamRow(team, key, 'dst_yards_allowed', ownStatCache.DEFPASSYARDS + ownStatCache.DEFRUSHYARDS, 'derived_calc'),
+    );
+  }
+
+  if (opponentScore != null) {
+    out.push(teamRow(team, key, 'dst_points_allowed', opponentScore, 'derived_calc'));
+  }
+
+  // dst_tds / dst_safeties are summed counts, scored LINEAR in the seed ruleset —
+  // safe to zero-skip same as the native categories above.
+  let tds = 0;
+  let safeties = 0;
+  for (const stat of playerStats) {
+    if (DEFENSIVE_TD_KEYS.has(stat.statCategoryKey)) tds += stat.value;
+    if (stat.statCategoryKey === 'def_safeties') safeties += stat.value;
+  }
+  if (tds) out.push(teamRow(team, key, 'dst_tds', tds, 'derived_calc'));
+  if (safeties) out.push(teamRow(team, key, 'dst_safeties', safeties, 'derived_calc'));
+
+  return out;
+}
+
+function teamRow(team, gameKey, statCategoryKey, value, source) {
+  return { externalTeamId: team.externalTeamId, gameKey, statCategoryKey, value, source };
+}
+
+function gameKeyOf(game) {
+  return `${game.seasonWeekType}:${game.seasonWeek}:${game.homeExternalTeamId}:${game.awayExternalTeamId}`;
+}
+
+/**
+ * Groups already-extracted player_game_stat rows by (gameKey, externalTeamId) so
+ * extractTeamGameStats can sum defensive TDs/safeties without re-walking every
+ * player's GameStats[] wrapper a second time. Built from the same players list
+ * extractPlayerGameStats consumed, keyed by each player's CURRENT roster TeamIndex
+ * (see the module-level caveat on why this is the only attribution available).
+ */
+export function indexPlayerGameStatsByGameAndTeam(playerGameStats, players, indexTeamsByTeamIndex) {
+  const teamByExternalPlayerId = new Map(
+    players.map((p) => [p.externalPlayerId, indexTeamsByTeamIndex.get(p.teamIndex)]),
+  );
+  const index = new Map();
+
+  for (const stat of playerGameStats) {
+    const team = teamByExternalPlayerId.get(stat.externalPlayerId);
+    if (!team) continue;
+    const mapKey = `${stat.gameKey}:${team.externalTeamId}`;
+    if (!index.has(mapKey)) index.set(mapKey, []);
+    index.get(mapKey).push(stat);
+  }
+
+  return index;
+}

package/src/extract/teams.js

@@ -0,0 +1,41 @@
+// Extracts sim_team (stable identity) and sim_team_season (per-season naming/standings).
+//
+// findings.md §6: getTableByName('Team') can return a 1-row decoy (Practice team) —
+// the real 32 teams live in the capacity-37 instance, filtered to TEAM_TYPE='Current'.
+// TeamIndex 32 is not a team, it's the FA/practice pool; we never create a row for it.
+
+import { getTableByNameAndCapacity, liveRecords } from '../lib/franchise-table.js';
+
+export async function extractTeams(franchise) {
+  const table = await getTableByNameAndCapacity(franchise, 'Team');
+  const teams = liveRecords(table).filter((r) => r.TEAM_TYPE === 'Current');
+
+  return teams.map((t) => ({
+    // sim_team — stable across weeks and season boundaries (findings §6).
+    externalTeamId: t.PresentationId,
+    teamIndex: t.TeamIndex, // 0..31, what Player.TeamIndex points at. Non-alphabetical, fixed.
+
+    // sim_team_season — season-scoped because relocation/rebrand renames teams mid-franchise.
+    // IsRelocated is unreliable (findings §6: Vikings ship with it true) — not read here;
+    // rebrand detection is a diff-across-imports concern for the ingest side, not extraction.
+    displayName: t.DisplayName,
+    nickName: t.NickName,
+    shortName: t.ShortName,
+
+    wins: (t.HomeWin ?? 0) + (t.RoadWin ?? 0),
+    losses: (t.HomeLoss ?? 0) + (t.RoadLoss ?? 0),
+    ties: (t.HomeTie ?? 0) + (t.RoadTie ?? 0),
+    divStanding: t.CurSeasonDivStanding,
+    confStanding: t.CurSeasonConfStanding,
+    leagueStanding: t.CurSeasonLeagStanding,
+
+    // raw record kept for other extractors (depth chart) that need to walk this
+    // same team's reference fields without re-reading/re-filtering the Team table.
+    _record: t,
+  }));
+}
+
+/** TeamIndex (0..31) -> extracted team row, for resolving Player.TeamIndex and SeasonGame refs. */
+export function indexTeamsByTeamIndex(teams) {
+  return new Map(teams.map((t) => [t.teamIndex, t]));
+}