madden-fantasy-extractor 0.2.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "madden-fantasy-extractor",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Reads a Madden franchise save and produces a signed stat_import JSON payload for ingest.",
   "type": "module",
   "main": "src/index.js",

package/src/extract/franchise-news.js

@@ -0,0 +1,114 @@
+// Extracts franchise news: the `Story` and `Tweet` save tables, normalized into a
+// single row shape. Stories resolve to a team via a direct `Team` reference field;
+// Tweets resolve to a player by decoding `OverlayData`'s (TeamIndex, JerseyNum) pair
+// and looking it up against the already-extracted player roster.
+//
+// The (TeamIndex, JerseyNum) resolution below is not a heuristic invented for this
+// module -- it was empirically discovered and verified by decoding real Tweet.OverlayData
+// against three real Madden saves spanning a season, achieving a 100% hit rate for real
+// rostered players (TeamIndex 0-31). See docs/extraction-findings.md for the design
+// investigation this plan's spec was built from.
+
+import { createHash } from 'node:crypto';
+import { getTableByNameAndCapacity, liveRecords, resolveFieldRef } from '../lib/franchise-table.js';
+
+// TeamIndex 32 is the FA/practice-squad pool, not a real team (see games.js's own
+// TeamIndex-lookup pattern and db/schema.sql's sim_team comment). Tweet.OverlayData's
+// (TeamIndex, JerseyNum) pair only resolves to a specific player for REAL rostered
+// teams -- TeamIndex 32 rows use a jersey-number sentinel (observed as 10 across many
+// unrelated named players in every real save checked) for generic practice-squad-
+// flavor tweets that aren't actually tied to a resolvable individual. Emit
+// externalPlayerId: null for these rather than guessing; do not attempt name-based
+// disambiguation, which was tested against real saves and does not resolve them (the
+// candidate pool stays large and unrelated to the tweet's named player).
+const UNRESOLVABLE_TEAM_INDEX = 32;
+
+function parseOverlayData(value) {
+  const out = {};
+  for (const part of (value ?? '').split('|')) {
+    if (!part) continue;
+    const idx = part.indexOf(':');
+    if (idx === -1) continue;
+    out[part.slice(0, idx)] = part.slice(idx + 1);
+  }
+  return out;
+}
+
+export async function extractFranchiseNews(franchise, { indexTeamsByTeamIndex, indexPlayersByTeamAndJersey }) {
+  const stories = await extractStories(franchise, indexTeamsByTeamIndex);
+  const tweets = await extractTweets(franchise, indexPlayersByTeamAndJersey);
+  return [...stories, ...tweets];
+}
+
+async function extractStories(franchise, indexTeamsByTeamIndex) {
+  const table = await getTableByNameAndCapacity(franchise, 'Story');
+  const records = liveRecords(table).filter((r) => r.Header || r.Tag);
+
+  const rows = [];
+  for (const r of records) {
+    const teamRecord = await resolveFieldRef(franchise, r, 'Team');
+    const team = teamRecord ? indexTeamsByTeamIndex.get(teamRecord.TeamIndex) : null;
+
+    const row = {
+      type: 'story',
+      header: r.Header || null,
+      text: r.Tag || '',
+      externalPlayerId: null,
+      externalTeamId: team?.externalTeamId ?? null,
+      isBreaking: Boolean(r.IsBreaking),
+      seasonYear: r.SeasonYear,
+      seasonWeekIndex: r.SeasonWeek,
+    };
+    row.dedupeKey = computeDedupeKey(row);
+    rows.push(row);
+  }
+  return rows;
+}
+
+async function extractTweets(franchise, indexPlayersByTeamAndJersey) {
+  const table = await getTableByNameAndCapacity(franchise, 'Tweet');
+  const records = liveRecords(table).filter((r) => r.Tweet);
+
+  const rows = [];
+  for (const r of records) {
+    const overlay = parseOverlayData(r.OverlayData);
+    const teamIndex = overlay.ptlg != null ? Number(overlay.ptlg) : null;
+    const jerseyNum = overlay.pnum != null ? Number(overlay.pnum) : null;
+
+    let externalPlayerId = null;
+    if (teamIndex != null && teamIndex !== UNRESOLVABLE_TEAM_INDEX && jerseyNum != null) {
+      const candidates = indexPlayersByTeamAndJersey.get(`${teamIndex}|${jerseyNum}`) ?? [];
+      // A clean (TeamIndex, JerseyNum) hit is expected to be unique for real rosters
+      // (confirmed across 3 real saves) -- if more than one player somehow shares the
+      // key (a stale/retired duplicate), fall back to null rather than guess.
+      if (candidates.length === 1) externalPlayerId = candidates[0].externalPlayerId;
+    }
+
+    const row = {
+      type: 'tweet',
+      header: null,
+      text: r.Tweet,
+      externalPlayerId,
+      externalTeamId: null,
+      isBreaking: Boolean(r.IsBreaking),
+      seasonYear: r.SeasonYear,
+      seasonWeekIndex: r.SeasonWeek,
+    };
+    row.dedupeKey = computeDedupeKey(row);
+    rows.push(row);
+  }
+  return rows;
+}
+
+function computeDedupeKey(row) {
+  const parts = [
+    row.type,
+    row.header,
+    row.text,
+    row.externalPlayerId,
+    row.externalTeamId,
+    row.seasonYear,
+    row.seasonWeekIndex,
+  ];
+  return createHash('sha256').update(parts.join('|')).digest('hex');
+}

package/src/extract/league-awards.js

@@ -0,0 +1,137 @@
+import { getTableByNameAndCapacity, liveRecords, resolveFieldRef, resolveWrapperSlots } from '../lib/franchise-table.js';
+
+// League.Awards.WeeklyAwards -- confirmed live, real, per-franchise data (AFC/NFC
+// Offensive/Defensive Player of the Week) in every real save checked.
+//
+// League.Awards.AnnualAwards -- a 720-slot array mixing frozen real-world historical
+// placeholders (AwardScore always 0, PeriodIndex a real calendar year) with every
+// completed franchise season's real, live-computed values (AwardScore > 0). Confirmed
+// via real-save investigation (docs/superpowers/investigations/2026-07-25-league-
+// history-award-grouping-verification.md) that PeriodIndex grows forward
+// chronologically from a fixed anchor as more seasons complete -- PeriodIndex=0 is
+// only the FIRST season this array ever captured, not "the current season" forever.
+// Restricting to PeriodIndex===0 would silently miss every season after that first
+// one, so the real discriminator between "live season data" and "frozen historical
+// placeholder" is AwardScore > 0 alone. Confirmed empirically that a season's
+// PeriodIndex entries are ABSENT while that season is still in progress and only
+// appear once it fully closes -- this is expected, not a bug; a mid-season
+// extraction run correctly produces zero AnnualAwards rows for that season.
+//
+// A given AwardType can have MULTIPLE winners for the same PeriodIndex (confirmed:
+// AFC/NFC-style splits on most categories) -- do not assume or enforce one winner per
+// type per season.
+//
+// AllTimeAwards and LastSeasonWeeklyAwards were investigated and show the same
+// frozen/historical pattern as the debunked historical AnnualAwards entries in every
+// save checked -- deliberately not extracted.
+//
+// League.Awards has no Coach_of_Year slot at all -- that award is sourced from a
+// completely different, flat (non-wrapper) table, LeagueHistoryAward, resolved
+// directly off the franchise rather than through League.Awards. See
+// extractCoachOfYearAwards below.
+export async function extractLeagueAwards(franchise, { indexTeamsByTeamIndex }) {
+  const leagueTable = await getTableByNameAndCapacity(franchise, 'League');
+  const leagueRecord = liveRecords(leagueTable)[0];
+  if (!leagueRecord) return [];
+
+  const awardsRecord = await resolveFieldRef(franchise, leagueRecord, 'Awards');
+  if (!awardsRecord) return [];
+
+  const weekly = await extractAwardWrapper(franchise, awardsRecord, 'WeeklyAwards', indexTeamsByTeamIndex, { excludeHistoricalPlaceholders: false });
+  const annual = await extractAwardWrapper(franchise, awardsRecord, 'AnnualAwards', indexTeamsByTeamIndex, { excludeHistoricalPlaceholders: true });
+  const coachOfYear = await extractCoachOfYearAwards(franchise);
+  return [...weekly, ...annual, ...coachOfYear];
+}
+
+async function extractAwardWrapper(franchise, awardsRecord, fieldKey, indexTeamsByTeamIndex, { excludeHistoricalPlaceholders }) {
+  const wrapper = await resolveFieldRef(franchise, awardsRecord, fieldKey);
+  if (!wrapper) return [];
+
+  const awardRecords = await resolveWrapperSlots(franchise, wrapper, 'Award');
+  const rows = [];
+  for (const r of awardRecords) {
+    // AnnualAwards mixes frozen historical placeholders (real year, AwardScore 0)
+    // with every completed season's real values (AwardScore>0, whatever its
+    // PeriodIndex) -- only extract the latter for that array. WeeklyAwards has no
+    // equivalent historical pollution (confirmed in real saves), so this filter is a
+    // no-op there.
+    if (excludeHistoricalPlaceholders && !(r.AwardScore > 0)) continue;
+
+    const playerRecord = await resolveFieldRef(franchise, r, 'Player');
+    if (!playerRecord) continue; // unresolvable player ref -- skip, matching transactions.js's convention
+
+    const teamRecord = await resolveFieldRef(franchise, r, 'Team');
+    const team = teamRecord ? indexTeamsByTeamIndex.get(teamRecord.TeamIndex) : null;
+
+    rows.push({
+      awardType: r.AwardType,
+      period: r.Period,
+      periodIndex: r.PeriodIndex,
+      awardScore: r.AwardScore,
+      externalPlayerId: playerRecord.PresentationId,
+      externalTeamId: team?.externalTeamId ?? null,
+      conference: r.Conference ?? null,
+      coachName: null,
+    });
+  }
+  return rows;
+}
+
+// LeagueHistoryAward -- a flat (non-wrapper), un-marked table with no per-row
+// season/period field of its own. Confirmed via real-save investigation (see
+// docs/superpowers/investigations/2026-07-25-league-history-award-grouping-
+// verification.md against CAREER-2028) that its live records partition into clean,
+// consecutive 7-row blocks in chronological order (block 0 = oldest season), and
+// block N corresponds exactly to League.Awards.AnnualAwards' PeriodIndex=N (verified
+// via exact MVP-name cross-match across 3 blocks, including a repeated-winner case
+// that rules out coincidental matching).
+//
+// Every block's 7 AwardType values are pairwise distinct, and matched here by each
+// row's own AwardType field (not fixed sub-position within the block) -- more robust
+// to a future save where a block's internal order might differ.
+//
+// CRITICAL: every block's first row reads AwardType "INVALID" -- confirmed REAL,
+// populated per-season data (a genuine distinct player+position each season, e.g.
+// Josh Allen/QB, Keisean Nixon/CB, Trevor Lawrence/QB across 3 real blocks), not an
+// empty/placeholder row. It is NOT one of the 6 award types this project needs, and
+// is deliberately excluded here rather than surfaced or interpreted.
+//
+// Coach_of_Year rows have flat firstName/lastName/Position text fields and no
+// resolvable player/coach reference of any kind -- Position reads as the literal
+// string "Invalid_" for these rows (expected: a coach has no position, not an error).
+const LEAGUE_HISTORY_BLOCK_SIZE = 7; // confirmed via real-save investigation (see comment above)
+
+async function extractCoachOfYearAwards(franchise) {
+  const table = await getTableByNameAndCapacity(franchise, 'LeagueHistoryAward');
+  const records = liveRecords(table);
+
+  if (records.length % LEAGUE_HISTORY_BLOCK_SIZE !== 0) {
+    // Don't let an unproven assumption about ONE table's row count (confirmed only at
+    // n=1 real save so far -- see the block-grouping investigation) abort the entire
+    // payload. Skip just the Coach_of_Year awards for this run; everything else
+    // (weekly/annual awards, stats, games, transactions) still extracts normally.
+    console.error(
+      `LeagueHistoryAward has ${records.length} live records, not a multiple of ${LEAGUE_HISTORY_BLOCK_SIZE} -- ` +
+      'the block-size assumption (see the league-history-award-grouping-verification investigation) may no longer hold for this save. Skipping Coach_of_Year extraction for this run.',
+    );
+    return [];
+  }
+
+  const rows = [];
+  for (let block = 0; block < records.length / LEAGUE_HISTORY_BLOCK_SIZE; block++) {
+    const blockRecords = records.slice(block * LEAGUE_HISTORY_BLOCK_SIZE, (block + 1) * LEAGUE_HISTORY_BLOCK_SIZE);
+    const coachRecord = blockRecords.find((r) => r.AwardType === 'Coach_of_Year');
+    if (!coachRecord) continue; // defensive -- shouldn't happen per the investigation's findings, but don't crash if it does
+    rows.push({
+      awardType: 'Coach_of_Year',
+      period: 'Season',
+      periodIndex: block, // block index IS the PeriodIndex, per the investigation's confirmed correspondence
+      awardScore: 0, // LeagueHistoryAward has no AwardScore field -- not meaningful for this row shape
+      externalPlayerId: null,
+      externalTeamId: null,
+      conference: null,
+      coachName: `${coachRecord.firstName} ${coachRecord.lastName}`,
+    });
+  }
+  return rows;
+}

package/src/extract/payload.js

@@ -11,8 +11,8 @@
 // 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 { extractTeams, extractDivisionConferenceByTeam, indexTeamsByTeamIndex } from './teams.js';
+import { extractPlayers, indexPlayersByTeamAndJersey } from './players.js';
 import { extractGames, gameKey } from './games.js';
 import { extractPlayerGameStats } from './player-game-stats.js';
 import { extractTeamGameStats, indexPlayerGameStatsByGameAndTeam } from './team-game-stats.js';
@@ -20,13 +20,21 @@ 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 { extractFranchiseNews } from './franchise-news.js';
+import { extractLeagueAwards } from './league-awards.js';
 import { selectGamesToCapture, selectReadyGames, selectPendingGames, unionCapturedKeys } from '../lib/incremental.js';
 
-const PAYLOAD_SCHEMA_VERSION = '1.0.0';
+const PAYLOAD_SCHEMA_VERSION = '1.4.0';
 
 export async function buildPayload(franchise, { toolVersion, fullMode = false, capturedGameKeys = new Set() }) {
   const clock = await extractClock(franchise);
   const teams = await extractTeams(franchise);
+  const divisionConferenceByTeam = await extractDivisionConferenceByTeam(franchise);
+  for (const team of teams) {
+    const dc = divisionConferenceByTeam.get(team.externalTeamId);
+    team.divisionName = dc?.divisionName ?? null;
+    team.conferenceName = dc?.conferenceName ?? null;
+  }
   const teamIdx = indexTeamsByTeamIndex(teams);
 
   const allGames = await extractGames(franchise, { indexTeamsByTeamIndex: teamIdx });
@@ -39,6 +47,7 @@ export async function buildPayload(franchise, { toolVersion, fullMode = false, c
   const gamesByKey = new Map(gamesToCapture.map((g) => [gameKey(g), g]));
 
   const players = await extractPlayers(franchise, { currentSeasonYear: clock.calendarYear });
+  const playerIdx = indexPlayersByTeamAndJersey(players);
 
   const playerGameStats = await extractPlayerGameStats(franchise, {
     players,
@@ -66,6 +75,11 @@ export async function buildPayload(franchise, { toolVersion, fullMode = false, c
   const transactions = await extractTransactions(franchise, { indexTeamsByTeamIndex: teamIdx });
   const cumulativeStats = await extractCumulativeStats(franchise, { players });
   const depthChart = await extractDepthChart(franchise, { teams });
+  const franchiseNews = await extractFranchiseNews(franchise, {
+    indexTeamsByTeamIndex: teamIdx,
+    indexPlayersByTeamAndJersey: playerIdx,
+  });
+  const franchiseAwards = await extractLeagueAwards(franchise, { indexTeamsByTeamIndex: teamIdx });
 
   // Only games that ACTUALLY produced player-level stats this run get added to the
   // watermark (PreSeason excepted — see incremental.js's selectReadyGames) — "decided"
@@ -101,6 +115,8 @@ export async function buildPayload(franchise, { toolVersion, fullMode = false, c
     transactions,
     cumulativeStats,
     depthChart,
+    franchiseNews,
+    franchiseAwards,
   };
 
   const nextCapturedGameKeys = unionCapturedKeys(capturedGameKeys, readyGames, clock.seasonIndex);

package/src/extract/players.js

@@ -34,6 +34,7 @@ export async function extractPlayers(franchise, { currentSeasonYear }) {
       // 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,
+      jerseyNum: r.JerseyNum,
       contractStatus: r.ContractStatus,
 
       snapshot: extractSnapshot(r),
@@ -72,3 +73,18 @@ function extractRatings(r) {
   }
   return ratings;
 }
+
+// Groups already-extracted players by (teamIndex, jerseyNum), the key franchise-news
+// extraction (Task 8) uses to resolve a Story/Tweet's team+jersey reference back to a
+// specific player. Multiple players can share a key (e.g. TeamIndex 32 = free agents/
+// practice squad overflow, or a mid-season jersey number reuse) — callers must handle
+// arrays with more than one entry, not assume a unique match.
+export function indexPlayersByTeamAndJersey(players) {
+  const map = new Map();
+  for (const p of players) {
+    const key = `${p.teamIndex}|${p.jerseyNum}`;
+    if (!map.has(key)) map.set(key, []);
+    map.get(key).push(p);
+  }
+  return map;
+}

package/src/extract/teams.js

@@ -4,7 +4,7 @@
 // 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';
+import { getTableByNameAndCapacity, getAllLiveRecordsAcrossInstances, liveRecords, resolveFieldRef, resolveWrapperSlots } from '../lib/franchise-table.js';
 
 export async function extractTeams(franchise) {
   const table = await getTableByNameAndCapacity(franchise, 'Team');
@@ -35,6 +35,37 @@ export async function extractTeams(franchise) {
   }));
 }
 
+/**
+ * Division/conference membership is NOT a field on Team -- it's the reverse
+ * relationship (Conference -> Divisions -> Teams), confirmed via real-save
+ * investigation (see docs/superpowers/specs/2026-07-26-conference-division-standings-
+ * design.md in the madden-fantasy repo). Conference itself exists as TWO SEPARATE
+ * table instances in the save (one AFC, one NFC), which is why this reads via
+ * getAllLiveRecordsAcrossInstances rather than getTableByNameAndCapacity -- the
+ * latter would silently return only one conference.
+ *
+ * Returns a lookup from externalTeamId (Team.PresentationId) to
+ * { divisionName, conferenceName }.
+ */
+export async function extractDivisionConferenceByTeam(franchise) {
+  const conferences = await getAllLiveRecordsAcrossInstances(franchise, 'Conference');
+  const result = new Map();
+  for (const conf of conferences) {
+    const divWrapper = await resolveFieldRef(franchise, conf, 'Divisions');
+    if (!divWrapper) continue;
+    const divisions = await resolveWrapperSlots(franchise, divWrapper, 'Division');
+    for (const div of divisions) {
+      const teamWrapper = await resolveFieldRef(franchise, div, 'Teams');
+      if (!teamWrapper) continue;
+      const teams = await resolveWrapperSlots(franchise, teamWrapper, 'Team');
+      for (const team of teams) {
+        result.set(team.PresentationId, { divisionName: div.Name, conferenceName: conf.Name });
+      }
+    }
+  }
+  return result;
+}
+
 /** 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]));

package/src/lib/franchise-table.js

@@ -29,6 +29,25 @@ export async function getTableByNameAndCapacity(franchise, name, opts) {
   return table;
 }
 
+/**
+ * Some tables exist as multiple real (non-decoy) instances rather than one real
+ * instance plus decoys -- confirmed for `Conference` (two capacity-1 instances, one
+ * holding AFC, one holding NFC; see docs/superpowers/specs/2026-07-26-conference-
+ * division-standings-design.md in the madden-fantasy repo). Unlike
+ * getTableByNameAndCapacity, this reads and returns every instance's live records
+ * merged into one array, rather than picking a single "best" instance.
+ */
+export async function getAllLiveRecordsAcrossInstances(franchise, name) {
+  const matches = franchise.tables.filter((t) => t.name === name);
+  if (matches.length === 0) throw new Error(`No table named "${name}" in this save`);
+  const allRecords = [];
+  for (const table of matches) {
+    await table.readRecords();
+    allRecords.push(...liveRecords(table));
+  }
+  return allRecords;
+}
+
 /**
  * Resolve a reference field to its target record, reading the target table first if needed.
  *

package/test/franchise-news.test.js

@@ -0,0 +1,145 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { extractFranchiseNews } from '../src/extract/franchise-news.js';
+import { indexPlayersByTeamAndJersey } from '../src/extract/players.js';
+import { indexTeamsByTeamIndex } from '../src/extract/teams.js';
+import { fakeTable, fakeRecord, fakeFranchise } from './helpers/fake-franchise.js';
+
+test('extractFranchiseNews: resolves a Tweet with valid OverlayData to the correct player', async () => {
+  const teams = [{ teamIndex: 5, externalTeamId: 50 }];
+  const players = [{ teamIndex: 5, jerseyNum: 12, externalPlayerId: 500 }];
+
+  const tweetRecord = fakeRecord({
+    Tweet: 'Big performance from the star player.',
+    OverlayData: 'pnm:Test Player|ptlg:5|pnum:12|',
+    IsBreaking: true,
+    SeasonYear: 2026,
+    SeasonWeek: 3,
+  });
+  const tweetTable = fakeTable('Tweet', [tweetRecord]);
+  const storyTable = fakeTable('Story', []);
+  const franchise = fakeFranchise([tweetTable, storyTable]);
+
+  const rows = await extractFranchiseNews(franchise, {
+    indexTeamsByTeamIndex: new Map([[5, teams[0]]]),
+    indexPlayersByTeamAndJersey: indexPlayersByTeamAndJersey(players),
+  });
+
+  const tweetRows = rows.filter((r) => r.type === 'tweet');
+  assert.equal(tweetRows.length, 1);
+  assert.equal(tweetRows[0].externalPlayerId, 500);
+  assert.equal(tweetRows[0].text, 'Big performance from the star player.');
+  assert.equal(tweetRows[0].isBreaking, true);
+});
+
+test('extractFranchiseNews: a TeamIndex=32 Tweet resolves externalPlayerId to null, never guesses by name', async () => {
+  const players = [{ teamIndex: 10, jerseyNum: 10, externalPlayerId: 999 }]; // unrelated real player, same jersey number coincidentally
+
+  const tweetRecord = fakeRecord({
+    Tweet: 'Generic practice-squad tweet.',
+    OverlayData: 'pnm:Some Practice Player|ptlg:32|pnum:10|',
+    IsBreaking: false,
+    SeasonYear: 2026,
+    SeasonWeek: 3,
+  });
+  const tweetTable = fakeTable('Tweet', [tweetRecord]);
+  const storyTable = fakeTable('Story', []);
+  const franchise = fakeFranchise([tweetTable, storyTable]);
+
+  const rows = await extractFranchiseNews(franchise, {
+    indexTeamsByTeamIndex: new Map(),
+    indexPlayersByTeamAndJersey: indexPlayersByTeamAndJersey(players),
+  });
+
+  assert.equal(rows[0].externalPlayerId, null);
+});
+
+test('extractFranchiseNews: a (TeamIndex, JerseyNum) collision (2+ candidates) resolves to null, not a guess', async () => {
+  const players = [
+    { teamIndex: 5, jerseyNum: 12, externalPlayerId: 500 },
+    { teamIndex: 5, jerseyNum: 12, externalPlayerId: 501 }, // duplicate key, e.g. a stale entry
+  ];
+
+  const tweetRecord = fakeRecord({
+    Tweet: 'Ambiguous tweet.',
+    OverlayData: 'pnm:Test Player|ptlg:5|pnum:12|',
+    IsBreaking: false,
+    SeasonYear: 2026,
+    SeasonWeek: 3,
+  });
+  const tweetTable = fakeTable('Tweet', [tweetRecord]);
+  const storyTable = fakeTable('Story', []);
+  const franchise = fakeFranchise([tweetTable, storyTable]);
+
+  const rows = await extractFranchiseNews(franchise, {
+    indexTeamsByTeamIndex: new Map(),
+    indexPlayersByTeamAndJersey: indexPlayersByTeamAndJersey(players),
+  });
+
+  assert.equal(rows[0].externalPlayerId, null);
+});
+
+test('extractFranchiseNews: resolves a Story to its team, never a player', async () => {
+  const teamRecord = fakeRecord({ TeamIndex: 7 });
+  const teamTable = fakeTable('Team', [teamRecord]);
+
+  const storyRecord = fakeRecord(
+    { Header: 'Big Win', Tag: 'The team won big.', IsBreaking: true, SeasonYear: 2026, SeasonWeek: 4 },
+    { Team: { tableId: teamTable._id, rowNumber: 0 } },
+  );
+  const storyTable = fakeTable('Story', [storyRecord]);
+  const tweetTable = fakeTable('Tweet', []);
+  const franchise = fakeFranchise([storyTable, tweetTable, teamTable]);
+
+  const rows = await extractFranchiseNews(franchise, {
+    indexTeamsByTeamIndex: new Map([[7, { teamIndex: 7, externalTeamId: 70 }]]),
+    indexPlayersByTeamAndJersey: new Map(),
+  });
+
+  const storyRows = rows.filter((r) => r.type === 'story');
+  assert.equal(storyRows.length, 1);
+  assert.equal(storyRows[0].externalPlayerId, null);
+  assert.equal(storyRows[0].externalTeamId, 70);
+  assert.equal(storyRows[0].header, 'Big Win');
+  assert.equal(storyRows[0].text, 'The team won big.');
+});
+
+test('extractFranchiseNews: dedupeKey is stable for identical content and differs for different content', async () => {
+  const tweetRecordA = fakeRecord({ Tweet: 'Same text.', OverlayData: '', IsBreaking: false, SeasonYear: 2026, SeasonWeek: 1 });
+  const tweetRecordB = fakeRecord({ Tweet: 'Same text.', OverlayData: '', IsBreaking: false, SeasonYear: 2026, SeasonWeek: 1 });
+  const tweetRecordC = fakeRecord({ Tweet: 'Different text.', OverlayData: '', IsBreaking: false, SeasonYear: 2026, SeasonWeek: 1 });
+
+  async function run(record) {
+    const tweetTable = fakeTable('Tweet', [record]);
+    const storyTable = fakeTable('Story', []);
+    const franchise = fakeFranchise([tweetTable, storyTable]);
+    return extractFranchiseNews(franchise, { indexTeamsByTeamIndex: new Map(), indexPlayersByTeamAndJersey: new Map() });
+  }
+
+  const [rowsA] = [await run(tweetRecordA)];
+  const [rowsB] = [await run(tweetRecordB)];
+  const [rowsC] = [await run(tweetRecordC)];
+
+  assert.equal(rowsA[0].dedupeKey, rowsB[0].dedupeKey);
+  assert.notEqual(rowsA[0].dedupeKey, rowsC[0].dedupeKey);
+});
+
+test('extractFranchiseNews: dedupeKey differs for identical content in different weeks (prevents cross-week collisions)', async () => {
+  const tweetRecordWeek1 = fakeRecord({ Tweet: 'Same text.', OverlayData: '', IsBreaking: false, SeasonYear: 2026, SeasonWeek: 1 });
+  const tweetRecordWeek2 = fakeRecord({ Tweet: 'Same text.', OverlayData: '', IsBreaking: false, SeasonYear: 2026, SeasonWeek: 2 });
+  const tweetRecordYear2027 = fakeRecord({ Tweet: 'Same text.', OverlayData: '', IsBreaking: false, SeasonYear: 2027, SeasonWeek: 1 });
+
+  async function run(record) {
+    const tweetTable = fakeTable('Tweet', [record]);
+    const storyTable = fakeTable('Story', []);
+    const franchise = fakeFranchise([tweetTable, storyTable]);
+    return extractFranchiseNews(franchise, { indexTeamsByTeamIndex: new Map(), indexPlayersByTeamAndJersey: new Map() });
+  }
+
+  const rowsWeek1 = await run(tweetRecordWeek1);
+  const rowsWeek2 = await run(tweetRecordWeek2);
+  const rowsYear2027 = await run(tweetRecordYear2027);
+
+  assert.notEqual(rowsWeek1[0].dedupeKey, rowsWeek2[0].dedupeKey);
+  assert.notEqual(rowsWeek1[0].dedupeKey, rowsYear2027[0].dedupeKey);
+});

package/test/franchise-table.test.js

@@ -0,0 +1,37 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { getAllLiveRecordsAcrossInstances } from '../src/lib/franchise-table.js';
+import { fakeTable, fakeRecord, fakeFranchise } from './helpers/fake-franchise.js';
+
+test('getAllLiveRecordsAcrossInstances: merges live records across multiple instances of the same table name', async () => {
+  const afcRecord = fakeRecord({ Name: 'AFC' });
+  const afcTable = fakeTable('Conference', [afcRecord]);
+  const nfcRecord = fakeRecord({ Name: 'NFC' });
+  const nfcTable = fakeTable('Conference', [nfcRecord]);
+
+  const franchise = fakeFranchise([afcTable, nfcTable]);
+
+  const records = await getAllLiveRecordsAcrossInstances(franchise, 'Conference');
+  assert.equal(records.length, 2);
+  assert.deepEqual(records.map((r) => r.Name).sort(), ['AFC', 'NFC']);
+});
+
+test('getAllLiveRecordsAcrossInstances: skips empty records within each instance', async () => {
+  const liveRecord = fakeRecord({ Name: 'AFC' });
+  const emptyRecord = { ...fakeRecord({}), isEmpty: true };
+  const table = fakeTable('Conference', [liveRecord, emptyRecord]);
+
+  const franchise = fakeFranchise([table]);
+
+  const records = await getAllLiveRecordsAcrossInstances(franchise, 'Conference');
+  assert.equal(records.length, 1);
+  assert.equal(records[0].Name, 'AFC');
+});
+
+test('getAllLiveRecordsAcrossInstances: throws when no table with that name exists', async () => {
+  const franchise = fakeFranchise([]);
+  await assert.rejects(
+    () => getAllLiveRecordsAcrossInstances(franchise, 'Conference'),
+    /No table named "Conference"/,
+  );
+});

package/test/league-awards.test.js

@@ -0,0 +1,331 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { extractLeagueAwards } from '../src/extract/league-awards.js';
+import { fakeTable, fakeRecord, fakeFranchise } from './helpers/fake-franchise.js';
+
+// League.Awards resolves through TWO levels of reference: League -> Awards ->
+// WeeklyAwards/AnnualAwards (each a wrapper with numbered Award0/Award1/... slots,
+// same shape as GameStats[]) -> individual Award/PlayerAward records. Build the fake
+// table graph to match this real shape.
+//
+// LeagueHistoryAward (the Coach_of_Year source) is a separate, flat, non-wrapper
+// table resolved directly by name/capacity, not through League.Awards -- tests that
+// don't care about Coach_of_Year still need an empty LeagueHistoryAward table present
+// so extractCoachOfYearAwards's getTableByNameAndCapacity lookup doesn't throw.
+
+/** An empty LeagueHistoryAward table -- satisfies extractCoachOfYearAwards's lookup for tests that don't exercise it. */
+function emptyLeagueHistoryAwardTable() {
+  return fakeTable('LeagueHistoryAward', []);
+}
+
+test('extractLeagueAwards: extracts a WeeklyAwards entry with resolved player/team', async () => {
+  const player = fakeRecord({ PresentationId: 500, FirstName: 'Test', LastName: 'Player' });
+  const playerTable = fakeTable('Player', [player]);
+  const team = fakeRecord({ TeamIndex: 5 });
+  const teamTable = fakeTable('Team', [team]);
+
+  const awardRecord = fakeRecord(
+    { AwardType: 'AFC_Offensive_Player_of_Week', Period: 'Week', PeriodIndex: 1, AwardScore: 0 },
+    { Player: { tableId: playerTable._id, rowNumber: 0 }, Team: { tableId: teamTable._id, rowNumber: 0 } },
+  );
+  const awardTable = fakeTable('Award', [awardRecord]);
+  // Wrapper table: numbered slot fields pointing at the award record.
+  const weeklyWrapper = fakeRecord({}, { Award0: { tableId: awardTable._id, rowNumber: 0 } });
+  const weeklyWrapperTable = fakeTable('WeeklyAwardsWrapper', [weeklyWrapper]);
+
+  const annualWrapper = fakeRecord({}, {}); // empty AnnualAwards for this test
+  const annualWrapperTable = fakeTable('AnnualAwardsWrapper', [annualWrapper]);
+
+  const awardsRecord = fakeRecord(
+    {},
+    {
+      WeeklyAwards: { tableId: weeklyWrapperTable._id, rowNumber: 0 },
+      AnnualAwards: { tableId: annualWrapperTable._id, rowNumber: 0 },
+    },
+  );
+  const awardsTable = fakeTable('Awards', [awardsRecord]);
+
+  const leagueRecord = fakeRecord({}, { Awards: { tableId: awardsTable._id, rowNumber: 0 } });
+  const leagueTable = fakeTable('League', [leagueRecord]);
+
+  const franchise = fakeFranchise([playerTable, teamTable, awardTable, weeklyWrapperTable, annualWrapperTable, awardsTable, leagueTable, emptyLeagueHistoryAwardTable()]);
+
+  const rows = await extractLeagueAwards(franchise, { indexTeamsByTeamIndex: new Map([[5, { externalTeamId: 50, teamIndex: 5 }]]) });
+
+  assert.equal(rows.length, 1);
+  assert.equal(rows[0].awardType, 'AFC_Offensive_Player_of_Week');
+  assert.equal(rows[0].externalPlayerId, 500);
+  assert.equal(rows[0].externalTeamId, 50);
+  assert.equal(rows[0].periodIndex, 1);
+  assert.equal(rows[0].coachName, null);
+});
+
+test('extractLeagueAwards: captures every populated PeriodIndex in AnnualAwards, not just 0', async () => {
+  const player = fakeRecord({ PresentationId: 600 });
+  const playerTable = fakeTable('Player', [player]);
+
+  // PeriodIndex=0, real nonzero score -- MUST be extracted.
+  const season0Award = fakeRecord(
+    { AwardType: 'MVP', Period: 'Season', PeriodIndex: 0, AwardScore: 463 },
+    { Player: { tableId: playerTable._id, rowNumber: 0 } },
+  );
+  // PeriodIndex=1, real nonzero score -- MUST ALSO be extracted (this is the case the
+  // old PeriodIndex===0 restriction would have silently dropped).
+  const season1Award = fakeRecord(
+    { AwardType: 'MVP', Period: 'Season', PeriodIndex: 1, AwardScore: 513 },
+    { Player: { tableId: playerTable._id, rowNumber: 0 } },
+  );
+  // Historical placeholder entry: real (non-zero-index) PeriodIndex, AwardScore 0 --
+  // must NOT be extracted regardless of its PeriodIndex value.
+  const historicalPlaceholder = fakeRecord(
+    { AwardType: 'MVP', Period: 'Season', PeriodIndex: 2024, AwardScore: 0 },
+    { Player: { tableId: playerTable._id, rowNumber: 0 } },
+  );
+  const awardTable = fakeTable('Award', [season0Award, season1Award, historicalPlaceholder]);
+
+  const annualWrapper = fakeRecord(
+    {},
+    {
+      Award0: { tableId: awardTable._id, rowNumber: 0 },
+      Award1: { tableId: awardTable._id, rowNumber: 1 },
+      Award2: { tableId: awardTable._id, rowNumber: 2 },
+    },
+  );
+  const annualWrapperTable = fakeTable('AnnualAwardsWrapper', [annualWrapper]);
+  const weeklyWrapper = fakeRecord({}, {});
+  const weeklyWrapperTable = fakeTable('WeeklyAwardsWrapper', [weeklyWrapper]);
+
+  const awardsRecord = fakeRecord(
+    {},
+    { WeeklyAwards: { tableId: weeklyWrapperTable._id, rowNumber: 0 }, AnnualAwards: { tableId: annualWrapperTable._id, rowNumber: 0 } },
+  );
+  const awardsTable = fakeTable('Awards', [awardsRecord]);
+  const leagueRecord = fakeRecord({}, { Awards: { tableId: awardsTable._id, rowNumber: 0 } });
+  const leagueTable = fakeTable('League', [leagueRecord]);
+
+  const franchise = fakeFranchise([playerTable, awardTable, annualWrapperTable, weeklyWrapperTable, awardsTable, leagueTable, emptyLeagueHistoryAwardTable()]);
+
+  const rows = await extractLeagueAwards(franchise, { indexTeamsByTeamIndex: new Map() });
+
+  assert.equal(rows.length, 2);
+  assert.deepEqual(rows.map((r) => r.periodIndex).sort(), [0, 1]);
+  assert.deepEqual(rows.map((r) => r.awardScore).sort(), [463, 513]);
+});
+
+test('extractLeagueAwards: multiple current-season winners for the same AwardType are all extracted', async () => {
+  const player1 = fakeRecord({ PresentationId: 700 });
+  const player2 = fakeRecord({ PresentationId: 701 });
+  const playerTable = fakeTable('Player', [player1, player2]);
+
+  const award1 = fakeRecord(
+    { AwardType: 'Offensive_Player_of_Year', Period: 'Season', PeriodIndex: 0, AwardScore: 316, Conference: 'AFC' },
+    { Player: { tableId: playerTable._id, rowNumber: 0 } },
+  );
+  const award2 = fakeRecord(
+    { AwardType: 'Offensive_Player_of_Year', Period: 'Season', PeriodIndex: 0, AwardScore: 440, Conference: 'NFC' },
+    { Player: { tableId: playerTable._id, rowNumber: 1 } },
+  );
+  const awardTable = fakeTable('Award', [award1, award2]);
+
+  const annualWrapper = fakeRecord(
+    {},
+    { Award0: { tableId: awardTable._id, rowNumber: 0 }, Award1: { tableId: awardTable._id, rowNumber: 1 } },
+  );
+  const annualWrapperTable = fakeTable('AnnualAwardsWrapper', [annualWrapper]);
+  const weeklyWrapper = fakeRecord({}, {});
+  const weeklyWrapperTable = fakeTable('WeeklyAwardsWrapper', [weeklyWrapper]);
+  const awardsRecord = fakeRecord(
+    {},
+    { WeeklyAwards: { tableId: weeklyWrapperTable._id, rowNumber: 0 }, AnnualAwards: { tableId: annualWrapperTable._id, rowNumber: 0 } },
+  );
+  const awardsTable = fakeTable('Awards', [awardsRecord]);
+  const leagueRecord = fakeRecord({}, { Awards: { tableId: awardsTable._id, rowNumber: 0 } });
+  const leagueTable = fakeTable('League', [leagueRecord]);
+
+  const franchise = fakeFranchise([playerTable, awardTable, annualWrapperTable, weeklyWrapperTable, awardsTable, leagueTable, emptyLeagueHistoryAwardTable()]);
+
+  const rows = await extractLeagueAwards(franchise, { indexTeamsByTeamIndex: new Map() });
+
+  assert.equal(rows.length, 2);
+  assert.deepEqual(rows.map((r) => r.externalPlayerId).sort(), [700, 701]);
+});
+
+test('extractLeagueAwards: an award with an unresolvable Player ref is skipped, not thrown', async () => {
+  // Player ref with tableId 0 -- the documented "nothing here" sentinel (see
+  // franchise-table.js's resolveRef comment).
+  const award = fakeRecord(
+    { AwardType: 'MVP', Period: 'Season', PeriodIndex: 0, AwardScore: 100 },
+    { Player: { tableId: 0, rowNumber: 0 } },
+  );
+  const awardTable = fakeTable('Award', [award]);
+  const annualWrapper = fakeRecord({}, { Award0: { tableId: awardTable._id, rowNumber: 0 } });
+  const annualWrapperTable = fakeTable('AnnualAwardsWrapper', [annualWrapper]);
+  const weeklyWrapper = fakeRecord({}, {});
+  const weeklyWrapperTable = fakeTable('WeeklyAwardsWrapper', [weeklyWrapper]);
+  const awardsRecord = fakeRecord(
+    {},
+    { WeeklyAwards: { tableId: weeklyWrapperTable._id, rowNumber: 0 }, AnnualAwards: { tableId: annualWrapperTable._id, rowNumber: 0 } },
+  );
+  const awardsTable = fakeTable('Awards', [awardsRecord]);
+  const leagueRecord = fakeRecord({}, { Awards: { tableId: awardsTable._id, rowNumber: 0 } });
+  const leagueTable = fakeTable('League', [leagueRecord]);
+
+  const franchise = fakeFranchise([awardTable, annualWrapperTable, weeklyWrapperTable, awardsTable, leagueTable, emptyLeagueHistoryAwardTable()]);
+
+  const rows = await extractLeagueAwards(franchise, { indexTeamsByTeamIndex: new Map() });
+  assert.equal(rows.length, 0);
+});
+
+// LeagueHistoryAward is a flat, non-wrapper table with no League.Awards involvement
+// at all -- these tests still need an empty AnnualAwards/WeeklyAwards wrapper graph
+// wired up (extractLeagueAwards resolves both unconditionally), but supply real
+// LeagueHistoryAward rows to exercise extractCoachOfYearAwards.
+
+/** Wires an empty League/Awards/WeeklyAwards/AnnualAwards graph, for tests focused on LeagueHistoryAward. */
+function emptyAwardsGraph() {
+  const weeklyWrapper = fakeRecord({}, {});
+  const weeklyWrapperTable = fakeTable('WeeklyAwardsWrapper', [weeklyWrapper]);
+  const annualWrapper = fakeRecord({}, {});
+  const annualWrapperTable = fakeTable('AnnualAwardsWrapper', [annualWrapper]);
+  const awardsRecord = fakeRecord(
+    {},
+    { WeeklyAwards: { tableId: weeklyWrapperTable._id, rowNumber: 0 }, AnnualAwards: { tableId: annualWrapperTable._id, rowNumber: 0 } },
+  );
+  const awardsTable = fakeTable('Awards', [awardsRecord]);
+  const leagueRecord = fakeRecord({}, { Awards: { tableId: awardsTable._id, rowNumber: 0 } });
+  const leagueTable = fakeTable('League', [leagueRecord]);
+  return [weeklyWrapperTable, annualWrapperTable, awardsTable, leagueTable];
+}
+
+/** A LeagueHistoryAward row -- flat fields only, no reference fields (see the investigation doc). */
+function leagueHistoryAwardRow({ awardType, firstName, lastName, position = 'QB' }) {
+  return fakeRecord({ AwardType: awardType, firstName, lastName, Position: position, teamIdentity: '0' });
+}
+
+/** One real 7-row LeagueHistoryAward season block, in the confirmed real-save AwardType order. */
+function leagueHistoryAwardBlock({ invalidName, mvpName, opoyName, dpoyName, oroyName, droyName, coachName }) {
+  return [
+    leagueHistoryAwardRow({ awardType: 'INVALID', firstName: invalidName[0], lastName: invalidName[1] }),
+    leagueHistoryAwardRow({ awardType: 'MVP', firstName: mvpName[0], lastName: mvpName[1] }),
+    leagueHistoryAwardRow({ awardType: 'Offensive_Player_of_Year', firstName: opoyName[0], lastName: opoyName[1] }),
+    leagueHistoryAwardRow({ awardType: 'Defensive_Player_of_Year', firstName: dpoyName[0], lastName: dpoyName[1] }),
+    leagueHistoryAwardRow({ awardType: 'Offensive_Rookie_of_Year', firstName: oroyName[0], lastName: oroyName[1] }),
+    leagueHistoryAwardRow({ awardType: 'Defensive_Rookie_of_Year', firstName: droyName[0], lastName: droyName[1] }),
+    leagueHistoryAwardRow({ awardType: 'Coach_of_Year', firstName: coachName[0], lastName: coachName[1], position: 'Invalid_' }),
+  ];
+}
+
+test('extractLeagueAwards: extracts Coach_of_Year from LeagueHistoryAward with the correct season block', async () => {
+  const block0 = leagueHistoryAwardBlock({
+    invalidName: ['Josh', 'Allen'],
+    mvpName: ['Jalen', 'Hurts'],
+    opoyName: ['A', 'One'],
+    dpoyName: ['B', 'Two'],
+    oroyName: ['C', 'Three'],
+    droyName: ['D', 'Four'],
+    coachName: ['Brian', 'Daboll'],
+  });
+  const block1 = leagueHistoryAwardBlock({
+    invalidName: ['Keisean', 'Nixon'],
+    mvpName: ['Joe', 'Burrow'],
+    opoyName: ['E', 'Five'],
+    dpoyName: ['F', 'Six'],
+    oroyName: ['G', 'Seven'],
+    droyName: ['H', 'Eight'],
+    coachName: ['Liam', 'Coen'],
+  });
+
+  const leagueHistoryAwardTable = fakeTable('LeagueHistoryAward', [...block0, ...block1]);
+  const franchise = fakeFranchise([leagueHistoryAwardTable, ...emptyAwardsGraph()]);
+
+  const rows = await extractLeagueAwards(franchise, { indexTeamsByTeamIndex: new Map() });
+
+  const coachRows = rows.filter((r) => r.awardType === 'Coach_of_Year');
+  assert.equal(coachRows.length, 2);
+  assert.deepEqual(coachRows.map((r) => r.periodIndex).sort(), [0, 1]);
+
+  const block0Coach = coachRows.find((r) => r.periodIndex === 0);
+  const block1Coach = coachRows.find((r) => r.periodIndex === 1);
+  assert.equal(block0Coach.coachName, 'Brian Daboll');
+  assert.equal(block1Coach.coachName, 'Liam Coen');
+
+  // No player/team resolution attempted for coach rows -- there's no reference field to resolve.
+  for (const row of coachRows) {
+    assert.equal(row.externalPlayerId, null);
+    assert.equal(row.externalTeamId, null);
+  }
+
+  // The INVALID row in each block must never surface as an extracted award.
+  assert.ok(!rows.some((r) => r.awardType === 'INVALID'));
+});
+
+test('extractLeagueAwards: a LeagueHistoryAward count that is not a multiple of 7 skips Coach_of_Year, not the whole payload', async () => {
+  // 5 rows is not a multiple of LEAGUE_HISTORY_BLOCK_SIZE (7) -- the block-size
+  // assumption may not hold for this save. This must degrade to zero Coach_of_Year
+  // rows, not throw and abort the entire extraction.
+  const leagueHistoryAwardTable = fakeTable('LeagueHistoryAward', [
+    leagueHistoryAwardRow({ awardType: 'INVALID', firstName: 'A', lastName: 'One' }),
+    leagueHistoryAwardRow({ awardType: 'MVP', firstName: 'B', lastName: 'Two' }),
+    leagueHistoryAwardRow({ awardType: 'Offensive_Player_of_Year', firstName: 'C', lastName: 'Three' }),
+    leagueHistoryAwardRow({ awardType: 'Defensive_Player_of_Year', firstName: 'D', lastName: 'Four' }),
+    leagueHistoryAwardRow({ awardType: 'Offensive_Rookie_of_Year', firstName: 'E', lastName: 'Five' }),
+  ]);
+  const franchise = fakeFranchise([leagueHistoryAwardTable, ...emptyAwardsGraph()]);
+
+  const rows = await extractLeagueAwards(franchise, { indexTeamsByTeamIndex: new Map() });
+
+  assert.deepEqual(rows, []);
+});
+
+test('extractLeagueAwards: Coach_of_Year rows have coachName set; all other award types have coachName null', async () => {
+  // MVP comes from League.Awards.AnnualAwards (a real, resolved player), while
+  // Coach_of_Year comes from LeagueHistoryAward -- wire up both sources in one test
+  // so the coachName discriminator can be checked across row shapes from BOTH tables.
+  const player = fakeRecord({ PresentationId: 800 });
+  const playerTable = fakeTable('Player', [player]);
+  const mvpAward = fakeRecord(
+    { AwardType: 'MVP', Period: 'Season', PeriodIndex: 0, AwardScore: 463 },
+    { Player: { tableId: playerTable._id, rowNumber: 0 } },
+  );
+  const awardTable = fakeTable('Award', [mvpAward]);
+  const annualWrapper = fakeRecord({}, { Award0: { tableId: awardTable._id, rowNumber: 0 } });
+  const annualWrapperTable = fakeTable('AnnualAwardsWrapper', [annualWrapper]);
+  const weeklyWrapper = fakeRecord({}, {});
+  const weeklyWrapperTable = fakeTable('WeeklyAwardsWrapper', [weeklyWrapper]);
+  const awardsRecord = fakeRecord(
+    {},
+    { WeeklyAwards: { tableId: weeklyWrapperTable._id, rowNumber: 0 }, AnnualAwards: { tableId: annualWrapperTable._id, rowNumber: 0 } },
+  );
+  const awardsTable = fakeTable('Awards', [awardsRecord]);
+  const leagueRecord = fakeRecord({}, { Awards: { tableId: awardsTable._id, rowNumber: 0 } });
+  const leagueTable = fakeTable('League', [leagueRecord]);
+
+  const block0 = leagueHistoryAwardBlock({
+    invalidName: ['Trevor', 'Lawrence'],
+    mvpName: ['Joe', 'Burrow'], // LeagueHistoryAward's own MVP row is NOT extracted -- only Coach_of_Year is read from this table
+    opoyName: ['A', 'One'],
+    dpoyName: ['B', 'Two'],
+    oroyName: ['C', 'Three'],
+    droyName: ['D', 'Four'],
+    coachName: ['Tim', 'Stephens'],
+  });
+  const leagueHistoryAwardTable = fakeTable('LeagueHistoryAward', block0);
+
+  const franchise = fakeFranchise([
+    playerTable, awardTable, annualWrapperTable, weeklyWrapperTable, awardsTable, leagueTable, leagueHistoryAwardTable,
+  ]);
+
+  const rows = await extractLeagueAwards(franchise, { indexTeamsByTeamIndex: new Map() });
+
+  // One MVP row (from AnnualAwards) and one Coach_of_Year row (from LeagueHistoryAward).
+  assert.equal(rows.length, 2);
+
+  const coachRows = rows.filter((r) => r.awardType === 'Coach_of_Year');
+  const otherRows = rows.filter((r) => r.awardType !== 'Coach_of_Year');
+  assert.equal(coachRows.length, 1);
+  assert.equal(coachRows[0].coachName, 'Tim Stephens');
+  assert.ok(otherRows.length > 0);
+  for (const row of otherRows) {
+    assert.equal(row.coachName, null);
+  }
+});

package/test/players.test.js

@@ -0,0 +1,44 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { extractPlayers, indexPlayersByTeamAndJersey } from '../src/extract/players.js';
+import { fakeTable, fakeRecord, fakeFranchise } from './helpers/fake-franchise.js';
+
+test('extractPlayers includes jerseyNum on each returned player', async () => {
+  const player = fakeRecord({
+    PresentationId: 100,
+    FirstName: 'Test',
+    LastName: 'Player',
+    TeamIndex: 0,
+    JerseyNum: 12,
+    YearDrafted: 0,
+    ContractStatus: 'Signed',
+  });
+  const playerTable = fakeTable('Player', [player]);
+  const franchise = fakeFranchise([playerTable]);
+
+  const players = await extractPlayers(franchise, { currentSeasonYear: 2026 });
+  assert.equal(players.length, 1);
+  assert.equal(players[0].jerseyNum, 12);
+});
+
+test('indexPlayersByTeamAndJersey groups players by (teamIndex, jerseyNum) key', () => {
+  const players = [
+    { teamIndex: 0, jerseyNum: 12, externalPlayerId: 100 },
+    { teamIndex: 0, jerseyNum: 88, externalPlayerId: 101 },
+    { teamIndex: 1, jerseyNum: 12, externalPlayerId: 102 },
+  ];
+  const idx = indexPlayersByTeamAndJersey(players);
+
+  assert.deepEqual(idx.get('0|12'), [{ teamIndex: 0, jerseyNum: 12, externalPlayerId: 100 }]);
+  assert.deepEqual(idx.get('1|12'), [{ teamIndex: 1, jerseyNum: 12, externalPlayerId: 102 }]);
+  assert.equal(idx.get('99|99'), undefined);
+});
+
+test('indexPlayersByTeamAndJersey groups multiple players under the same key (collision case)', () => {
+  const players = [
+    { teamIndex: 32, jerseyNum: 10, externalPlayerId: 200 },
+    { teamIndex: 32, jerseyNum: 10, externalPlayerId: 201 },
+  ];
+  const idx = indexPlayersByTeamAndJersey(players);
+  assert.equal(idx.get('32|10').length, 2);
+});

package/test/teams.test.js

@@ -0,0 +1,79 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { extractTeams, extractDivisionConferenceByTeam } from '../src/extract/teams.js';
+import { fakeTable, fakeRecord, fakeFranchise } from './helpers/fake-franchise.js';
+
+// Builds a minimal two-conference, one-division-each save fragment: AFC -> AFC East -> 2 teams,
+// NFC -> NFC West -> 1 team. Enough to prove the two-instance Conference walk without needing
+// all 8 real divisions.
+function buildDivisionConferenceFixture() {
+  const dolphins = fakeRecord({ PresentationId: 12, DisplayName: 'Dolphins' });
+  const bills = fakeRecord({ PresentationId: 3, DisplayName: 'Bills' });
+  const teamTable = fakeTable('Team', [dolphins, bills]);
+
+  const afcEastTeamsWrapper = fakeRecord({}, {
+    Team0: { tableId: teamTable._id, rowNumber: 0 },
+    Team1: { tableId: teamTable._id, rowNumber: 1 },
+  });
+  const afcEastTeamsWrapperTable = fakeTable('DivisionTeamsWrapper', [afcEastTeamsWrapper]);
+  const afcEast = fakeRecord({ Name: 'AFC East' }, { Teams: { tableId: afcEastTeamsWrapperTable._id, rowNumber: 0 } });
+  const afcDivisionTable = fakeTable('Division', [afcEast]);
+
+  const afcDivisionsWrapper = fakeRecord({}, { Division0: { tableId: afcDivisionTable._id, rowNumber: 0 } });
+  const afcDivisionsWrapperTable = fakeTable('ConferenceDivisionsWrapper', [afcDivisionsWrapper]);
+  const afc = fakeRecord({ Name: 'AFC' }, { Divisions: { tableId: afcDivisionsWrapperTable._id, rowNumber: 0 } });
+  const afcConferenceTable = fakeTable('Conference', [afc]);
+
+  const rams = fakeRecord({ PresentationId: 20, DisplayName: 'Rams' });
+  const nfcTeamTable = fakeTable('Team', [rams]);
+  const nfcWestTeamsWrapper = fakeRecord({}, { Team0: { tableId: nfcTeamTable._id, rowNumber: 0 } });
+  const nfcWestTeamsWrapperTable = fakeTable('DivisionTeamsWrapper', [nfcWestTeamsWrapper]);
+  const nfcWest = fakeRecord({ Name: 'NFC West' }, { Teams: { tableId: nfcWestTeamsWrapperTable._id, rowNumber: 0 } });
+  const nfcDivisionTable = fakeTable('Division', [nfcWest]);
+
+  const nfcDivisionsWrapper = fakeRecord({}, { Division0: { tableId: nfcDivisionTable._id, rowNumber: 0 } });
+  const nfcDivisionsWrapperTable = fakeTable('ConferenceDivisionsWrapper', [nfcDivisionsWrapper]);
+  const nfc = fakeRecord({ Name: 'NFC' }, { Divisions: { tableId: nfcDivisionsWrapperTable._id, rowNumber: 0 } });
+  const nfcConferenceTable = fakeTable('Conference', [nfc]); // SEPARATE Conference table instance
+
+  return fakeFranchise([
+    teamTable, afcEastTeamsWrapperTable, afcDivisionTable, afcDivisionsWrapperTable, afcConferenceTable,
+    nfcTeamTable, nfcWestTeamsWrapperTable, nfcDivisionTable, nfcDivisionsWrapperTable, nfcConferenceTable,
+  ]);
+}
+
+test('extractDivisionConferenceByTeam: walks BOTH Conference table instances and merges results', async () => {
+  const franchise = buildDivisionConferenceFixture();
+  const result = await extractDivisionConferenceByTeam(franchise);
+
+  assert.equal(result.size, 3);
+  assert.deepEqual(result.get(12), { divisionName: 'AFC East', conferenceName: 'AFC' });
+  assert.deepEqual(result.get(3), { divisionName: 'AFC East', conferenceName: 'AFC' });
+  assert.deepEqual(result.get(20), { divisionName: 'NFC West', conferenceName: 'NFC' });
+});
+
+test('extractDivisionConferenceByTeam: a team not present in any division is simply absent from the map', async () => {
+  const franchise = buildDivisionConferenceFixture();
+  const result = await extractDivisionConferenceByTeam(franchise);
+  assert.equal(result.has(999), false);
+});
+
+test('extractTeams output can be merged with extractDivisionConferenceByTeam by externalTeamId', async () => {
+  // This proves the shape buildPayload's merge step (Step 12) relies on: extractTeams
+  // rows keyed by externalTeamId match extractDivisionConferenceByTeam's map keys.
+  const team = fakeRecord({
+    PresentationId: 12, TeamIndex: 0, TEAM_TYPE: 'Current',
+    DisplayName: 'Dolphins', NickName: 'Fins', ShortName: 'MIA',
+    HomeWin: 3, RoadWin: 2, HomeLoss: 1, RoadLoss: 1, HomeTie: 0, RoadTie: 0,
+    CurSeasonDivStanding: 1, CurSeasonConfStanding: 3, CurSeasonLeagStanding: 5,
+  });
+  const teamTable = fakeTable('Team', [team]);
+  const franchise = fakeFranchise([teamTable]);
+
+  const teams = await extractTeams(franchise);
+  assert.equal(teams.length, 1);
+  assert.equal(teams[0].externalTeamId, 12);
+  // divisionName/conferenceName are NOT set by extractTeams itself -- confirms the
+  // merge happens one level up, in buildPayload (Step 12), not inside this function.
+  assert.equal('divisionName' in teams[0], false);
+});