madden-fantasy-extractor 0.2.0

package/src/extract/transactions.js

@@ -0,0 +1,105 @@
+// Extracts sim_transaction from PlayerTransactionHistoryEntry — findings.md §7: this
+// table gives the REASON for every move directly, strictly better than diffing two
+// saves. Classification follows the transition table documented there, PLUS ps_sign
+// (added after real-save validation — see db/schema.sql's comment on classified_type):
+//
+//   Trade     | OldTeam != NewTeam (both real), Signed->Signed
+//   Sign (FA) | null -> real team, FreeAgent->Signed
+//   Cut       | real team -> null, Signed->FreeAgent
+//   PS demote | same team, Signed->PracticeSquad
+//   PS poach  | diff team, PracticeSquad->Signed
+//   PS sign   | null -> real team, FreeAgent->PracticeSquad  (NOT in findings.md's
+//             | original table — turned out to be the SINGLE MOST COMMON transaction
+//             | type, ~41% of all rows in a sampled save: a street free agent signed
+//             | straight to the practice squad, distinct from ps_demote which moves an
+//             | already-Signed player down within the same team)
+//
+// Capacity is finite (742, findings §7) — a rolling window, not full history. Every
+// import must archive what it sees; dedupe_key (built from content, since
+// TransactionId is only unique WITHIN one save's current window, not stable across
+// saves/re-imports) is what makes repeated archiving idempotent.
+//
+// CAVEAT (schema.sql): SeasonStage here is PlayerTransactionHistoryEntry's own enum
+// (PreSeason/NFLSeason) — a DIFFERENT vocabulary from SeasonGame.SeasonWeekType
+// (RegularSeason/WildcardPlayoff/...). Never cross-compare the two; both are carried
+// through unchanged below rather than coerced into franchise_week's week_type.
+
+import { getTableByNameAndCapacity, liveRecords, resolveFieldRef } from '../lib/franchise-table.js';
+import { createHash } from 'node:crypto';
+
+export async function extractTransactions(franchise, { indexTeamsByTeamIndex }) {
+  const table = await getTableByNameAndCapacity(franchise, 'PlayerTransactionHistoryEntry');
+  const records = liveRecords(table);
+
+  const rows = [];
+  for (const r of records) {
+    const playerRecord = await resolveFieldRef(franchise, r, 'Player');
+    if (!playerRecord) continue; // unresolvable player ref — skip rather than emit a dangling transaction
+
+    const oldTeamRecord = await resolveFieldRef(franchise, r, 'OldTeam');
+    const newTeamRecord = await resolveFieldRef(franchise, r, 'NewTeam');
+    const oldTeam = oldTeamRecord ? indexTeamsByTeamIndex.get(oldTeamRecord.TeamIndex) : null;
+    const newTeam = newTeamRecord ? indexTeamsByTeamIndex.get(newTeamRecord.TeamIndex) : null;
+
+    const classifiedType = classify({
+      oldExternalTeamId: oldTeam?.externalTeamId ?? null,
+      newExternalTeamId: newTeam?.externalTeamId ?? null,
+      oldContractStatus: r.OldContractStatus,
+      newContractStatus: r.ContractStatus,
+    });
+
+    const row = {
+      externalPlayerId: playerRecord.PresentationId,
+      oldExternalTeamId: oldTeam?.externalTeamId ?? null,
+      newExternalTeamId: newTeam?.externalTeamId ?? null,
+      oldContractStatus: r.OldContractStatus,
+      newContractStatus: r.ContractStatus,
+      seasonYear: r.SeasonYear,
+      // PlayerTransactionHistoryEntry's own stage enum — do not compare against
+      // sim_game's SeasonWeekType (see module header caveat).
+      seasonStage: r.SeasonStage,
+      seasonWeekIndex: r.SeasonWeek,
+      classifiedType,
+      contract: {
+        length: r.ContractLength,
+        totalSalary: r.ContractTotalSalary,
+        bonus: r.ContractBonus,
+        salary: r.ContractSalary,
+        capSavingsThisYear: r.CapSavingsThisYear,
+        fifthYearOptionCapHit: r.FifthYearOptionCapHit,
+      },
+    };
+    row.dedupeKey = computeDedupeKey(row);
+    rows.push(row);
+  }
+  return rows;
+}
+
+function classify({ oldExternalTeamId, newExternalTeamId, oldContractStatus, newContractStatus }) {
+  const hadTeam = oldExternalTeamId !== null;
+  const hasTeam = newExternalTeamId !== null;
+  const sameTeam = hadTeam && hasTeam && oldExternalTeamId === newExternalTeamId;
+  const diffTeam = hadTeam && hasTeam && oldExternalTeamId !== newExternalTeamId;
+
+  if (diffTeam && oldContractStatus === 'Signed' && newContractStatus === 'Signed') return 'trade';
+  if (!hadTeam && hasTeam && oldContractStatus === 'FreeAgent' && newContractStatus === 'Signed') return 'signing';
+  if (hadTeam && !hasTeam && oldContractStatus === 'Signed' && newContractStatus === 'FreeAgent') return 'cut';
+  if (sameTeam && oldContractStatus === 'Signed' && newContractStatus === 'PracticeSquad') return 'ps_demote';
+  if (diffTeam && oldContractStatus === 'PracticeSquad' && newContractStatus === 'Signed') return 'ps_poach';
+  if (!hadTeam && hasTeam && oldContractStatus === 'FreeAgent' && newContractStatus === 'PracticeSquad') return 'ps_sign';
+  return 'other';
+}
+
+function computeDedupeKey(row) {
+  const parts = [
+    row.externalPlayerId,
+    row.oldExternalTeamId,
+    row.newExternalTeamId,
+    row.oldContractStatus,
+    row.newContractStatus,
+    row.seasonYear,
+    row.seasonStage,
+    row.seasonWeekIndex,
+  ];
+  return createHash('sha256').update(parts.join('|')).digest('hex');
+}

package/src/index.js

@@ -0,0 +1,4 @@
+// Library entry point. Re-exports the extraction API for consumers that already
+// have an opened madden-franchise Franchise instance and want to run extraction
+// themselves, without going through this repo's CLI (src/cli.js).
+export { buildPayload } from './extract/payload.js';

package/src/lib/franchise-table.js

@@ -0,0 +1,88 @@
+// Thin helpers over the madden-franchise table/record API.
+//
+// Core primitive confirmed against a real save (Madden NFL 26, PC):
+// a reference field's `referenceData` is `{ tableId, rowNumber }`, resolved via
+// `franchise.getTableById(tableId).records[rowNumber]`. Every relationship in the
+// save (Player.GameStats, GameOffensiveStats.SeasonGame, SeasonGame.HomeTeam, ...)
+// goes through this same shape.
+
+/** Non-empty records only — tables have fixed capacity with scattered empty slots. */
+export function liveRecords(table) {
+  return table.records.filter((r) => !r.isEmpty);
+}
+
+/** Table instances can be duplicated (decoys, differing capacity). Pick by highest capacity. */
+export function pickByCapacity(tables, { largest = true } = {}) {
+  const sorted = [...tables].sort((a, b) => {
+    const ac = a.header?.recordCapacity ?? 0;
+    const bc = b.header?.recordCapacity ?? 0;
+    return largest ? bc - ac : ac - bc;
+  });
+  return sorted[0];
+}
+
+export async function getTableByNameAndCapacity(franchise, name, opts) {
+  const matches = franchise.tables.filter((t) => t.name === name);
+  if (matches.length === 0) throw new Error(`No table named "${name}" in this save`);
+  const table = pickByCapacity(matches, opts);
+  await table.readRecords();
+  return table;
+}
+
+/**
+ * Resolve a reference field to its target record, reading the target table first if needed.
+ *
+ * An unfilled slot in a wrapper table (e.g. a bye week in GameStats[]) reads back as a
+ * reference with tableId 0 — not a missing/null field, still `isReference: true`. tableId 0
+ * is never a real table, so it's the reliable "nothing here" signal; treat it as absent.
+ */
+export async function resolveRef(franchise, field) {
+  if (!field || !field.isReference) return null;
+  const { tableId, rowNumber } = field.referenceData;
+  if (!tableId) return null;
+  const table = franchise.getTableById(tableId);
+  if (!table) return null;
+  if (table.records.length === 0) {
+    await table.readRecords();
+  }
+  const record = table.records[rowNumber];
+  if (!record || record.isEmpty) return null;
+  return record;
+}
+
+/** Resolve a named field on a record to its target record (see resolveRef). */
+export async function resolveFieldRef(franchise, record, fieldKey) {
+  const field = record.fieldsArray.find((f) => f.key === fieldKey);
+  return resolveRef(franchise, field);
+}
+
+/**
+ * Wrapper tables like `GameStats[]` expose a dynamic, non-fixed set of numbered
+ * slot fields (GameStats0, GameStats1, ...) each a reference to a real row.
+ * Findings: the nominal slot count is NOT a ceiling (confirmed 20+ filled slots
+ * through a Super Bowl run) — iterate whatever fields are actually present,
+ * never assume indices 0..17.
+ */
+export async function resolveWrapperSlots(franchise, wrapperRecord, slotPrefix) {
+  const slotFields = wrapperRecord.fieldsArray
+    .filter((f) => f.key.startsWith(slotPrefix) && /^\d+$/.test(f.key.slice(slotPrefix.length)))
+    .sort((a, b) => Number(a.key.slice(slotPrefix.length)) - Number(b.key.slice(slotPrefix.length)));
+
+  const resolved = [];
+  for (const field of slotFields) {
+    const record = await resolveRef(franchise, field);
+    if (record) resolved.push(record);
+  }
+  return resolved;
+}
+
+/**
+ * Player.GameStats / SeasonStats / CareerStats all point at a `*[]` wrapper row,
+ * not directly at a stat row. This resolves player -> wrapper -> every non-null
+ * per-game stat row in one call.
+ */
+export async function resolveGameStatRows(franchise, playerRecord) {
+  const wrapper = await resolveFieldRef(franchise, playerRecord, 'GameStats');
+  if (!wrapper) return [];
+  return resolveWrapperSlots(franchise, wrapper, 'GameStats');
+}

package/src/lib/identity.js

@@ -0,0 +1,58 @@
+// Player identity: decode-then-hash. See docs/extraction-findings.md §1, §11 and the
+// comment block on the `player` table in db/schema.sql — this is the linchpin of the
+// whole model and the one place a subtle bug silently corrupts a franchise's history.
+
+import { createHash } from 'node:crypto';
+
+// Sentinel round/pick pair for undrafted players (confirmed against a real save:
+// round=63, pick=511 for every UDFA sampled, including Signed/FreeAgent/PracticeSquad).
+const UDFA_ROUND = 63;
+const UDFA_PICK = 511;
+
+/**
+ * Player.YearDrafted is RELATIVE to the save's current calendar year, not absolute.
+ * realDraftYear = CurrentSeasonYear + YearDrafted + 1
+ * Verified against 5 real players' known draft years (findings §11). The raw value
+ * shifts by one at every season roll — decode BEFORE hashing, always, or identity_key
+ * rotates annually and orphans the franchise's history.
+ */
+export function decodeDraftYear(yearDraftedRaw, currentSeasonYear) {
+  return currentSeasonYear + yearDraftedRaw + 1;
+}
+
+function isUdfa(draftRound, draftPick) {
+  return draftRound === UDFA_ROUND && draftPick === UDFA_PICK;
+}
+
+/**
+ * Deterministic hash of the identity bundle. Bundle composition depends on how the
+ * player entered the league:
+ *   drafted -> (draft_year, draft_round, draft_pick) is globally unique alone; name is
+ *              belt-and-braces. Bulletproof (findings §1).
+ *   udfa    -> round/pick are sentinels, so the bundle degrades to name + draft_year.
+ *              Two generated UDFAs sharing a name in one class could collide — rare,
+ *              tracked via identity_basis for monitoring (schema.sql migration note 6).
+ */
+export function computeIdentityKey({ firstName, lastName, draftYear, draftRound, draftPick }) {
+  const basis = isUdfa(draftRound, draftPick) ? 'udfa' : 'drafted';
+  const parts =
+    basis === 'drafted'
+      ? [firstName, lastName, draftYear, draftRound, draftPick]
+      : [firstName, lastName, draftYear];
+
+  const hash = createHash('sha256').update(parts.join('|')).digest('hex');
+  return { identityKey: hash, identityBasis: basis };
+}
+
+/**
+ * Statuses that are real, ingestible player rows. Everything else (Deleted, Retired,
+ * None, Created) is tombstone/template junk — findings §1 caveat A: every raw
+ * PresentationId collision in the save pairs a Deleted/Retired tombstone with a real
+ * player, all parked at TeamIndex 32. Confirmed 'None'/'Created' are blank-name
+ * template rows at TeamIndex 32 too. Drop all four at ingest (schema.sql §12 rule 1).
+ */
+const INGESTIBLE_CONTRACT_STATUSES = new Set(['Signed', 'PracticeSquad', 'FreeAgent', 'Draft']);
+
+export function isIngestiblePlayer(record) {
+  return INGESTIBLE_CONTRACT_STATUSES.has(record.ContractStatus);
+}

package/src/lib/incremental.js

@@ -0,0 +1,90 @@
+// Pure logic for incremental (weekly) capture: which games belong in THIS run's
+// output, and which games get recorded as "confirmed captured" afterward.
+//
+// Two different questions, two different gates — do not collapse them:
+//
+//   selectGamesToCapture: is this game DECIDED and not already in the watermark?
+//     Drives what's included in games / fed into playerGameStats+teamGameStats
+//     extraction this run.
+//
+//   unionCapturedKeys: did this game actually produce player-level stats THIS run?
+//     Drives what gets ADDED to the persisted watermark.
+//
+// These must stay separate. Verified directly against a real save (CAREER-WEEK18):
+// SeasonGame shows a final score AND TeamStats is already fully resolved for every
+// week-17 game (14 of 14), a full week before any player's GameStats[] wrapper gains
+// a slot for that same week (docs/extraction-findings.md §3.5 — the clock/stats lag).
+// So "decided" (used for selection) and "player stats actually landed" (required
+// before marking captured) are genuinely different moments. If a freshly-decided
+// game were marked captured immediately, its player_game_stat rows would be
+// permanently skipped once they do land — selectGamesToCapture never re-examines a
+// game once its key is in the watermark. Team-level stats have no such lag (per the
+// same check), so gating on player-stat presence is a strict superset check: by the
+// time player stats exist, team stats are already guaranteed to.
+//
+// gameKey() (games.js) is deliberately season-agnostic ("RegularSeason:0:3:25") —
+// sufficient within a single extraction run, but persisted indefinitely in a state
+// file it can collide: the same two teams can play the same week-type/index matchup
+// in two different franchise seasons. seasonCaptureKey() prefixes clock.seasonIndex
+// to disambiguate — internal to state tracking only; the payload's own gameKey
+// format is untouched.
+
+import { gameKey, isDecidedGame } from '../extract/games.js';
+
+export function seasonCaptureKey(seasonIndex, game) {
+  return `${seasonIndex}:${gameKey(game)}`;
+}
+
+/**
+ * fullMode=true  -> every game the save reports (current/legacy behavior, unfiltered;
+ *                   used for first run, --full/--backfill, and recovering a missed week).
+ * fullMode=false -> only DECIDED games not already in alreadyCapturedKeys.
+ */
+export function selectGamesToCapture(games, { fullMode, seasonIndex, alreadyCapturedKeys }) {
+  if (fullMode) return games;
+  return games.filter(
+    (g) => isDecidedGame(g) && !alreadyCapturedKeys.has(seasonCaptureKey(seasonIndex, g)),
+  );
+}
+
+/** New watermark set to persist after a successful run: previous keys plus every
+ * game in `readyGames` (the subset of this run's included games that actually
+ * produced at least one player_game_stat row — see module header). */
+export function unionCapturedKeys(alreadyCapturedKeys, readyGames, seasonIndex) {
+  const next = new Set(alreadyCapturedKeys);
+  for (const g of readyGames) next.add(seasonCaptureKey(seasonIndex, g));
+  return next;
+}
+
+/**
+ * Of the games included this run, which ones are safe to add to the watermark.
+ *
+ * Normally that's "produced at least one player_game_stat row this run" (see module
+ * header on the player-stat lag). PreSeason is a carve-out: confirmed exhaustively
+ * against a real save (1,644 players, 17,755 GameStats rows walked) that ZERO are
+ * linked to a PreSeason game — preseason box scores structurally never populate
+ * player-level GameStats in this data model, only the schedule/score. Gating a
+ * PreSeason game's watermark on "produced a player_game_stat row" would mean it can
+ * NEVER satisfy the condition, so it would be re-selected by selectGamesToCapture on
+ * every single incremental run forever. For PreSeason specifically, "decided" is
+ * both the correct and the only available readiness signal.
+ */
+export function selectReadyGames(gamesToCapture, playerGameStats) {
+  const producedGameKeys = new Set(playerGameStats.map((row) => row.gameKey));
+  return gamesToCapture.filter((g) =>
+    g.seasonWeekType === 'PreSeason' ? isDecidedGame(g) : producedGameKeys.has(gameKey(g)),
+  );
+}
+
+/**
+ * The complement of selectReadyGames: games included in this run's output that have
+ * NOT yet produced player stats — still sitting in the retry queue (TeamStats/schedule
+ * resolved, player_game_stat not yet). Exposed in the payload (payload.js) as
+ * pendingPlayerStatGameKeys so a consumer — or a human eyeballing the output — can see
+ * directly which games, if any, are still outstanding, rather than having to infer it
+ * by diffing games against playerGameStats themselves.
+ */
+export function selectPendingGames(gamesToCapture, playerGameStats) {
+  const readyKeys = new Set(selectReadyGames(gamesToCapture, playerGameStats).map((g) => gameKey(g)));
+  return gamesToCapture.filter((g) => !readyKeys.has(gameKey(g)));
+}

package/src/lib/signing.js

@@ -0,0 +1,48 @@
+// Ed25519 signing for the extractor's identity. franchise.signing_public_key (see
+// db/schema.sql) is what an ingest server checks stat_import.signature against — it's
+// what lets a stranger trust data pushed for a public franchise (README "Design
+// principles"). Node's built-in crypto supports Ed25519 directly; no dependency needed.
+
+import { generateKeyPairSync, sign, verify, createPublicKey } from 'node:crypto';
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+export function generateKeypair() {
+  const { publicKey, privateKey } = generateKeyPairSync('ed25519');
+  return {
+    publicKeyPem: publicKey.export({ type: 'spki', format: 'pem' }).toString(),
+    privateKeyPem: privateKey.export({ type: 'pkcs8', format: 'pem' }).toString(),
+  };
+}
+
+export function saveKeypair(keyPath, { publicKeyPem, privateKeyPem }) {
+  mkdirSync(dirname(keyPath), { recursive: true });
+  writeFileSync(`${keyPath}.private.pem`, privateKeyPem, { mode: 0o600 });
+  writeFileSync(`${keyPath}.public.pem`, publicKeyPem, { mode: 0o644 });
+}
+
+export function loadOrCreateKeypair(keyPath) {
+  const privatePath = `${keyPath}.private.pem`;
+  const publicPath = `${keyPath}.public.pem`;
+
+  if (existsSync(privatePath) && existsSync(publicPath)) {
+    return {
+      privateKeyPem: readFileSync(privatePath, 'utf8'),
+      publicKeyPem: readFileSync(publicPath, 'utf8'),
+    };
+  }
+
+  const keypair = generateKeypair();
+  saveKeypair(keyPath, keypair);
+  return keypair;
+}
+
+export function signPayload(payloadBytes, privateKeyPem) {
+  const signature = sign(null, payloadBytes, privateKeyPem);
+  return signature.toString('base64');
+}
+
+export function verifySignature(payloadBytes, signatureBase64, publicKeyPem) {
+  const publicKey = createPublicKey(publicKeyPem);
+  return verify(null, payloadBytes, publicKey, Buffer.from(signatureBase64, 'base64'));
+}

package/src/lib/stat-categories.js

@@ -0,0 +1,68 @@
+// Mirrors the stat_category seed data in db/schema.sql exactly (source_field values
+// are the confirmed Madden 26 fields from docs/extraction-findings.md §2/§8). This is
+// the single source of truth mapping a raw Madden stat field to a stat_category.key —
+// keep it in sync with the seed INSERT if either changes.
+
+// player-scope categories, keyed by the raw field name as it appears on
+// GameOffensiveStats / GameDefensiveStats / GameKickingStats / Game*KPReturnStats.
+export const PLAYER_STAT_FIELD_MAP = {
+  // Passing
+  PASSCOMPLETED: 'pass_completions',
+  PASSATTEMPTS: 'pass_attempts',
+  PASSYARDS: 'pass_yards',
+  PASSTDS: 'pass_tds',
+  PASSINTS: 'pass_ints',
+  PASSSACKED: 'pass_sacked',
+  // Rushing
+  RUSHATTEMPTS: 'rush_attempts',
+  RUSHYARDS: 'rush_yards',
+  RUSHTDS: 'rush_tds',
+  RUSHFUMBLES: 'fumbles_total',
+  // Receiving
+  RECEIVECATCHES: 'rec_catches',
+  RECEIVEYARDS: 'rec_yards',
+  RECEIVETDS: 'rec_tds',
+  RECEIVEDROPS: 'rec_drops',
+  // Kicking (targets excluded — derived_diff, handled by the cumulative-stat extractor)
+  KICKEPMADE: 'xp_made',
+  KICKEPATTEMPTS: 'xp_attempts',
+  KICKFGMADE29ORLESS: 'fg_made_0_29',
+  KICKFGMADE30TO39: 'fg_made_30_39',
+  KICKFGMADE40TO49: 'fg_made_40_49',
+  KICKFGMADE50ORMORE: 'fg_made_50_plus',
+  KICKFGATTEMPTS: 'fg_attempts',
+  // Punting
+  PUNTATTEMPTS: 'punts',
+  PUNTYARDS: 'punt_yards',
+  PUNTIN20: 'punt_in_20',
+  // Individual defense
+  DEFTACKLES: 'def_tackles',
+  ASSDEFTACKLES: 'def_assists',
+  DLINESACKS: 'def_sacks',
+  DEFTACKLESFORLOSS: 'def_tfl',
+  DSECINTS: 'def_ints',
+  DSECINTTDS: 'def_int_tds',
+  DEFPASSDEFLECTIONS: 'def_pass_deflections',
+  DLINEFORCEDFUMBLES: 'def_forced_fumbles',
+  DLINEFUMBLERECOVERIES: 'def_fumble_recoveries',
+  DLINEFUMBLETDS: 'def_fumble_tds',
+  DLINESAFETIES: 'def_safeties',
+  // Returns
+  KRETYARDS: 'kick_return_yards',
+  KRETTDS: 'kick_return_tds',
+  PRETYARDS: 'punt_return_yards',
+  PRETTDS: 'punt_return_tds',
+};
+
+// team-scope categories, keyed by TeamStats raw field name.
+export const TEAM_STAT_FIELD_MAP = {
+  SACKS: 'dst_sacks',
+  TAKEAWAYS: 'dst_takeaways',
+  TWOPOINTCONVMADE: 'two_point_conversions',
+};
+
+// Every stat_category.key this extractor can produce, in insertion order matching
+// the schema seed — used to validate the extractor's output covers what the schema
+// declares scoring-relevant.
+export const ALL_PLAYER_STAT_KEYS = Object.values(PLAYER_STAT_FIELD_MAP);
+export const ALL_TEAM_STAT_KEYS = Object.values(TEAM_STAT_FIELD_MAP);

package/src/lib/state.js

@@ -0,0 +1,30 @@
+// Local, gitignored state tracking which games have already been captured (and
+// presumably uploaded), so a normal run only emits what's new since last time.
+// See src/lib/incremental.js for the selection/watermark logic that consumes this.
+//
+// "Confirmed uploaded" currently means "the CLI successfully wrote its output file" —
+// there's no ingest/upload endpoint yet (see extractor/README.md). Once one exists,
+// this is the natural place to instead gate the state update on a real upload
+// acknowledgment rather than a successful local write.
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+export function loadState(statePath) {
+  if (!existsSync(statePath)) return null;
+  const raw = JSON.parse(readFileSync(statePath, 'utf8'));
+  return {
+    capturedGameKeys: new Set(raw.capturedGameKeys ?? []),
+  };
+}
+
+export function saveState(statePath, { capturedGameKeys, toolVersion, savePath }) {
+  mkdirSync(dirname(statePath), { recursive: true });
+  const serialized = {
+    capturedGameKeys: [...capturedGameKeys].sort(),
+    updatedAt: new Date().toISOString(),
+    lastToolVersion: toolVersion,
+    lastSavePath: savePath,
+  };
+  writeFileSync(statePath, JSON.stringify(serialized, null, 2));
+}

package/test/helpers/fake-franchise.js

@@ -0,0 +1,36 @@
+// Minimal fakes matching the madden-franchise API surface this extractor actually
+// uses (table.records, table.readRecords(), record.fieldsArray, field.referenceData,
+// franchise.getTableById). Exercises the REAL resolveRef/resolveFieldRef code path
+// rather than reimplementing it, since that resolution logic is where this
+// extractor's correctness lives.
+
+let nextTableId = 1;
+
+export function fakeTable(name, records) {
+  return {
+    name,
+    _id: nextTableId++,
+    header: { recordCapacity: records.length },
+    records,
+    async readRecords() {},
+  };
+}
+
+/** A record with plain fields plus reference fields (key -> {tableId, rowNumber}). */
+export function fakeRecord(fields, refs = {}) {
+  const fieldsArray = [
+    ...Object.keys(fields).map((key) => ({ key })),
+    ...Object.keys(refs).map((key) => ({ key, isReference: true, referenceData: refs[key] })),
+  ];
+  return { ...fields, isEmpty: false, fieldsArray };
+}
+
+/** Wires a list of fakeTable() instances into a minimal franchise-shaped object. */
+export function fakeFranchise(tables) {
+  return {
+    tables,
+    getTableById(id) {
+      return tables.find((t) => t._id === id);
+    },
+  };
+}

package/test/identity.test.js

@@ -0,0 +1,61 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { decodeDraftYear, computeIdentityKey, isIngestiblePlayer } from '../src/lib/identity.js';
+
+test('decodeDraftYear matches the 5 verified players from extraction-findings.md §11', () => {
+  // realDraftYear = CurrentSeasonYear + YearDrafted + 1, CurrentSeasonYear=2025
+  assert.equal(decodeDraftYear(-8, 2025), 2018); // Josh Allen
+  assert.equal(decodeDraftYear(-9, 2025), 2017); // Patrick Mahomes
+  assert.equal(decodeDraftYear(-8, 2025), 2018); // Lamar Jackson
+  assert.equal(decodeDraftYear(-6, 2025), 2020); // Joe Burrow / Justin Herbert
+  assert.equal(decodeDraftYear(-3, 2025), 2023); // C.J. Stroud
+});
+
+test('decodeDraftYear shifts correctly across a season roll', () => {
+  // findings.md: "the raw value shifts by one at every season roll" — same player,
+  // decoded year must stay identical even though YearDrafted itself changes.
+  const decodedIn2025 = decodeDraftYear(-8, 2025);
+  const decodedIn2026 = decodeDraftYear(-9, 2026);
+  assert.equal(decodedIn2025, decodedIn2026);
+});
+
+test('computeIdentityKey is deterministic and stable for the same inputs', () => {
+  const input = { firstName: 'Josh', lastName: 'Allen', draftYear: 2018, draftRound: 1, draftPick: 7 };
+  const a = computeIdentityKey(input);
+  const b = computeIdentityKey({ ...input });
+  assert.equal(a.identityKey, b.identityKey);
+  assert.equal(a.identityBasis, 'drafted');
+});
+
+test('computeIdentityKey classifies the UDFA sentinel (round=63, pick=511) as udfa basis', () => {
+  const { identityBasis } = computeIdentityKey({
+    firstName: 'Some', lastName: 'Player', draftYear: 2022, draftRound: 63, draftPick: 511,
+  });
+  assert.equal(identityBasis, 'udfa');
+});
+
+test('computeIdentityKey produces different keys for different players', () => {
+  const a = computeIdentityKey({ firstName: 'Josh', lastName: 'Allen', draftYear: 2018, draftRound: 1, draftPick: 7 });
+  const b = computeIdentityKey({ firstName: 'Lamar', lastName: 'Jackson', draftYear: 2018, draftRound: 1, draftPick: 32 });
+  assert.notEqual(a.identityKey, b.identityKey);
+});
+
+test('computeIdentityKey UDFA bundle ignores round/pick (both are sentinels)', () => {
+  // Two UDFAs with the same name+draftYear collide by design (schema.sql migration
+  // note 6) — this documents that behavior rather than treating it as a bug.
+  const a = computeIdentityKey({ firstName: 'John', lastName: 'Doe', draftYear: 2024, draftRound: 63, draftPick: 511 });
+  const b = computeIdentityKey({ firstName: 'John', lastName: 'Doe', draftYear: 2024, draftRound: 63, draftPick: 511 });
+  assert.equal(a.identityKey, b.identityKey);
+});
+
+test('isIngestiblePlayer accepts real roster statuses', () => {
+  for (const status of ['Signed', 'PracticeSquad', 'FreeAgent', 'Draft']) {
+    assert.equal(isIngestiblePlayer({ ContractStatus: status }), true, status);
+  }
+});
+
+test('isIngestiblePlayer rejects tombstone/template statuses', () => {
+  for (const status of ['Deleted', 'Retired', 'None', 'Created']) {
+    assert.equal(isIngestiblePlayer({ ContractStatus: status }), false, status);
+  }
+});