madden-fantasy-extractor 0.2.0

package/README.md

@@ -0,0 +1,255 @@
+# madden-fantasy-extractor
+
+Reads a Madden NFL franchise save and produces a signed `stat_import` JSON payload —
+the ingest-ready snapshot consumed by the [`madden-fantasy`](https://github.com/patches822/madden-fantasy)
+server monorepo. Schema and extraction-design context (`db/schema.sql`,
+`docs/extraction-findings.md`) live in that repo, not here — this repo is standalone
+and depends on it only through the payload/signing contract
+(`payloadSchemaVersion`), not a code or file dependency.
+
+## Usage
+
+```bash
+npm install
+
+# First run auto-generates a signing keypair under .keys/ (gitignored) and, since
+# there's no capture watermark yet, runs in full/backfill mode automatically.
+node src/cli.js "C:/Users/you/Documents/Madden NFL 26/saves/CAREER-WEEK1"
+
+# A normal weekly run only includes games newly decided since the last successful
+# run (tracked in .extractor-state.json, gitignored) — expect roughly one week's
+# worth of games, not the whole season.
+node src/cli.js "C:/Users/you/Documents/Madden NFL 26/saves/CAREER-WEEK2"
+
+# Force everything in the save regardless of the watermark — first run, recovering
+# from a missed week, or manual backfill:
+node src/cli.js <savePath> --full
+node src/cli.js <savePath> --backfill   # same thing, alternate spelling
+
+# Optional flags:
+node src/cli.js <savePath> --out payload.json --key .keys/myfranchise --state .extractor-state.json
+
+# Print a fresh public key + keyId to register as a franchise_signing_key row:
+node src/cli.js keygen
+```
+
+The output is a signed envelope:
+
+```jsonc
+{
+  "payload": { /* the stat_import shape — see below */ },
+  "payloadHash": "sha256 hex, matches stat_import.payload_hash",
+  "signature": "base64 Ed25519 signature over the payload bytes",
+  "signingPublicKey": "PEM — the public key this was signed with",
+  "keyId": "sha256 hex of signingPublicKey — matches franchise_signing_key.key_id"
+}
+```
+
+## Using this as a library
+
+`buildPayload` is also exported directly, for callers that already have an opened
+`madden-franchise` `Franchise` instance and want to run extraction themselves (e.g.
+madden-fantasy's server-side save-upload feature, which downloads a save file and opens
+it before calling this):
+
+```js
+import Franchise from 'madden-franchise';
+import { buildPayload } from 'madden-fantasy-extractor';
+
+const franchise = await Franchise.create(localSaveFilePath);
+const { payload, nextCapturedGameKeys, pendingCount } = await buildPayload(franchise, {
+  toolVersion: 'my-caller-version',
+  fullMode: false,
+  capturedGameKeys: new Set(), // or a previously-persisted set
+});
+```
+
+See `src/extract/payload.js` for `buildPayload`'s full return shape.
+
+## What it extracts
+
+One run reads the save's CURRENT clock position and produces:
+
+| Payload key | Schema table(s) | Source |
+| --- | --- | --- |
+| `clock` | `franchise_season` / `franchise_week` identity fields | `SeasonInfo` |
+| `teams` | `sim_team` + `sim_team_season` | `Team` (capacity-37 instance, `TEAM_TYPE='Current'`) |
+| `players` | `player` + `player_season_snapshot` | `Player` |
+| `games` | `sim_game` | `SeasonGame` |
+| `playerGameStats` | `player_game_stat` | `Player.GameStats[]` → `Game*Stats` |
+| `teamGameStats` | `team_game_stat` | `SeasonGame.*TeamStatCache` → `TeamStats` |
+| `playerWeekStatus` | `player_week_status` | `Player` injury/roster fields (live) + game presence (lagged) — TWO rows per player per run, see below |
+| `transactions` | `sim_transaction` | `PlayerTransactionHistoryEntry` |
+| `cumulativeStats` | `player_cumulative_stat` | `Player.CareerStats` (targets only) |
+| `depthChart` | `depth_chart_entry` | `Team.DepthChart` |
+| `pendingPlayerStatGameKeys` | — (extractor-only signal) | games included in `games` this run whose `player_game_stat` rows haven't landed yet — see "Incremental capture" below |
+| `suggestedStatus` | hint for `stat_import.status` | `'partial'` if `pendingPlayerStatGameKeys` is non-empty, else `'accepted'` — not authoritative, ingest still decides |
+
+`sequence` (the cross-regime week ordinal) is **not** assigned here — per
+`db/schema.sql`'s migration notes, that's an ingest-side responsibility requiring
+knowledge of previously observed weeks, which a single save read can't provide.
+
+`games`, `playerGameStats`, and `teamGameStats` are **incremental by default** — see
+"Incremental capture" below. `teams`, `players`, `playerWeekStatus`, `transactions`,
+`cumulativeStats`, and `depthChart` always reflect the save's current full state;
+incremental filtering only applies to the per-game historical arrays.
+
+## Key design points
+
+**Reference resolution.** Almost everything in a Madden save is a reference field
+(`{tableId, rowNumber}`) rather than an inline value. `src/lib/franchise-table.js`
+centralizes that resolution, including the two non-obvious cases:
+
+- `tableId: 0` means "nothing here" (an unfilled wrapper slot, e.g. a bye week in
+  `GameStats[]`), not a real table — `resolveRef` treats it as `null`.
+- Wrapper tables (`GameStats[]`, `Player[]` depth-chart slots) expose a dynamic set of
+  numbered fields whose count is **not** a hard ceiling — confirmed 20+ filled
+  `GameStats` slots through a Super Bowl run. Always iterate present fields, never
+  assume a fixed range.
+
+**Player identity.** `src/lib/identity.js` implements the decode-then-hash design
+from `docs/extraction-findings.md` §1/§11: `YearDrafted` is relative to the save's
+current calendar year and must be decoded (`CurrentSeasonYear + YearDrafted + 1`)
+*before* hashing into `identity_key`, or the key rotates every season and orphans a
+franchise's history. Verified stable across a season boundary and through a real
+trade (James Cook III / Emanuel Wilson) against real save data.
+
+**The week lag (discovered during this build, not in the original findings doc) — and
+that it's CPU-sim-only.** `SeasonInfo.CurrentWeek` identifies the week about to be
+played, not the last one finished — confirmed with a consistent 1-week lag across 5
+saves spanning a full season. A player's `GameStats[]` wrapper only gains a slot once
+a week is fully processed, even though that week's `SeasonGame` scores may already be
+posted. Resolving "the most recently completed week" (`findCompletedWeek` in
+`src/extract/player-week-status.js`) 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`).
+
+Follow-up finding: the lag only applies to instant-CPU-simmed games (`IsSimmed=true`),
+not to slow-simmed or manually-played ones. A save taken immediately after finishing a
+slow-simmed game — confirmed with the save's owner it was slow-simmed, not manually
+controller-played — showed nearly the entire roster on both sides (46/51 and 46/52
+players) with that exact week's `GameStats` already populated, in the same save where
+every other, instant-simmed game that week still had zero players with a stat row for
+it (`docs/extraction-findings.md` §3.6). `TeamStats`/`SeasonGame` scores are always
+immediate regardless of `IsSimmed`; only the player-level box score is deferred, and
+only for instant-simmed games. This means a franchise that slow-sims (or plays) every
+game rather than using instant/auto-sim should see no player-stat lag at all, though
+that's an inference from one confirmed game, not a full season — check
+`payload.pendingPlayerStatGameKeys` against real saves to confirm it holds for a given
+franchise's workflow. No code change was needed for any of this either way — the
+incremental watermark (below) already checks readiness empirically per game rather
+than assuming a fixed delay, so it naturally clears a non-lagged game's stats on the
+very next capture instead of waiting a full week like an instant-simmed one.
+
+**Injury/roster status has NONE of the GameStats lag — `player-week-status.js` emits
+two rows per player per run because of it.** `Player.InjuryStatus`/`InjuryType`/
+`Min`/`MaxInjuryDuration`/`ContractStatus`/`TeamIndex` are direct fields, not resolved
+through `GameStats[]` — confirmed directly (`docs/extraction-findings.md` §3.7): a
+player injured in a slow-simmed game showed up injured in the very next save, with
+zero other injury/roster changes anywhere else in the league in that same window.
+Because this is live, bundling it under the same lagged week-label as the "did they
+actually play" check (which genuinely can't be known before kickoff) would delay
+injury visibility by a full week for no reason. So each run now emits:
+
+- a **predictive** row for `clock.weekType`/`clock.weekIndex` (the week about to be
+  played) — injured/bye/free_agent read live and current; `active` here means
+  "nothing known against them," not "confirmed played" (a late healthy scratch is
+  unknowable ahead of time). This is what answers "which of my players are hurt or
+  not playing this week" for setting a lineup, with zero lag.
+- the original **retrospective** row for the most recently completed week — unchanged
+  from the lag discussion above, and still the only row type that can distinguish a
+  confirmed healthy scratch (`inactive`) from a player whose stats simply haven't
+  landed yet.
+
+Both target the same `UNIQUE(player_id, franchise_week_id)` once a week transitions
+from "current" to "completed" across runs, so the predictive row for a given week is
+naturally superseded by the retrospective one once it's captured — no explicit
+"is this confirmed" flag needed, same "live now, frozen later" pattern the schema
+already uses for fantasy scoring (`matchup.*_points_final`).
+
+**Transaction classification.** `src/extract/transactions.js` extends the 5-pattern
+table in `docs/extraction-findings.md` §7 with a 6th, `ps_sign` (`FreeAgent` →
+`PracticeSquad` with no prior team) — real-save validation showed it's actually the
+*single most common* transaction type (~41% of rows in a sampled save), not a rare
+edge case. `db/schema.sql`'s `sim_transaction.classified_type` CHECK was widened to
+match.
+
+**Incremental capture (`src/lib/incremental.js`, `src/lib/state.js`).** A save
+re-exposes the whole season's `GameStats` every time (they persist, per
+`docs/extraction-findings.md` §2), so a naive weekly run re-emits everything it's
+ever seen — 169k+ `playerGameStats` rows / ~43MB for a single week-14 capture of one
+real franchise. A local, gitignored watermark (`.extractor-state.json`) tracks which
+games have already been captured; a normal run only includes games newly decided
+since then. `--full`/`--backfill` bypasses the watermark for first-run/recovery.
+
+This is gated on **player-level readiness, not on the game being decided** — a game
+is only added to the watermark once it actually produced a `playerGameStats` row this
+run. That distinction matters because of the week lag above: verified directly
+against a real save (`CAREER-WEEK18`), `SeasonGame` shows a final score *and*
+`TeamStats` is already fully resolved for every game in the most recent week, a full
+week before any player's `GameStats[]` wrapper gains a slot for that same week.
+Marking a game captured as soon as it's merely decided would permanently skip its
+`player_game_stat` rows once they do land, since a captured game is never
+re-examined. `teamGameStats` has no such lag (same check), so gating on player-stat
+presence is a safe superset — by the time player stats exist, team stats already do.
+
+The watermark itself is not lag-length-dependent — it doesn't assume one week, or any
+fixed number of runs. A decided game with no player stats yet simply stays out of the
+watermark and gets re-selected by `selectGamesToCapture` on every subsequent run,
+however many, until it actually produces a `player_game_stat` row. Verified against a
+real three-save sequence (`CAREER-WEEK10` → `CAREER-WEEK10SIM` → `CAREER-WEEK11`): a
+week's 14 games went 13 decided/0 player-ready → all 14 decided/1 player-ready (the
+one the user played themselves) → the remaining 13 became player-ready a full save
+later, at which point they were captured with zero duplication of the one already
+captured earlier.
+
+Any game still sitting in that retry state when a run completes is surfaced in the
+payload as `pendingPlayerStatGameKeys`, so a consumer doesn't have to diff `games`
+against `playerGameStats` to find out — and `suggestedStatus` flips to `'partial'`
+whenever that list is non-empty, as a hint for what `stat_import.status` to assign at
+ingest.
+
+**Same risk applies on the ingest/finalize side — not fixed here, but flagged.**
+Whatever eventually marks a `franchise_week` as `'final'` (freezing
+`matchup.*_points_final` per `db/schema.sql`) needs to gate on the *same* signal this
+watermark uses — "every `sim_game` in the week has produced `player_game_stat` rows"
+— not on "every game in the week is decided." A week finalized the moment its games
+are scheduled/scored, before the lagged player stats for a CPU-simmed game land, would
+freeze that week's fantasy scores permanently wrong, with no error anywhere in the
+pipeline to catch it. This can't be enforced from the extractor side — it depends on
+logic that doesn't exist yet (the ingest/finalize service). `pendingPlayerStatGameKeys`
+is exactly the signal that future code should check before flipping a week to `final`.
+
+**Zero-value stat rows are skipped, except where zero is a real outcome.**
+`v_player_game_points` (the only player-level scoring view) is linear-only — `SUM`
+over zero matching rows and `SUM` over one row worth `0 × points_per_unit` are
+identical, so an empty category (e.g. a QB's `rec_yards`) is written for no scoring
+benefit. `src/extract/player-game-stats.js` skips these unconditionally. For
+`team_game_stat`, most categories are the same story, but `dst_points_allowed` and
+`dst_yards_allowed` are documented in the schema seed as "almost always tiered" —
+tiered scoring is a bucket lookup, not a multiply, and 0 is typically the *best*
+bucket (the seed ruleset pays a 10 pt shutout bonus for the 0-0 band). Dropping those
+two rows at zero would silently score a shutout as 0 instead of the correct bonus, so
+`src/extract/team-game-stats.js` always emits them regardless of value and only
+zero-skips the genuinely linear categories (`dst_sacks`, `dst_takeaways`,
+`two_point_conversions`, `dst_tds`, `dst_safeties`).
+
+## Testing
+
+```bash
+npm test
+```
+
+Unit tests (`test/*.test.js`) cover the pure-logic pieces — identity hashing, draft
+year decoding, transaction classification, the week-lag/boundary-crossing logic, the
+incremental watermark's selection and season-collision handling, the state file's
+load/save round-trip, and the zero-skip rules (including the tiered-category
+exception) — against fakes shaped like the real `madden-franchise` API
+(`test/helpers/fake-franchise.js`), so they exercise the actual reference-resolution
+code path rather than a reimplementation of it. There's no fixture-based save file in
+the repo (real saves are personal franchise data and gitignored); the extractor has
+been validated end-to-end against real Madden NFL 26 saves during development,
+cross-checked line-by-line against `docs/extraction-findings.md`'s verified box score
+and trade cases.

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "madden-fantasy-extractor",
+  "version": "0.2.0",
+  "description": "Reads a Madden franchise save and produces a signed stat_import JSON payload for ingest.",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": {
+      "default": "./src/index.js"
+    }
+  },
+  "bin": {
+    "madden-extract": "src/cli.js"
+  },
+  "scripts": {
+    "extract": "node src/cli.js",
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "madden-franchise": "^4.3.1"
+  }
+}

package/src/cli.js

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+// CLI entry point. Reads a Madden franchise save, builds a stat_import payload,
+// signs it, and writes the signed envelope to a JSON file — see README.md's
+// "Getting started" for the ingest side this feeds.
+//
+// Usage:
+//   node src/cli.js <savePath> [--out <file>] [--key <keyPathPrefix>] [--state <file>] [--full|--backfill]
+//   node src/cli.js keygen [--key <keyPathPrefix>]
+//
+// By default, a run only includes games newly decided since the last successful run
+// (tracked in a local, gitignored state file) — see src/lib/incremental.js. Pass
+// --full (or --backfill) to include everything in the save regardless of the
+// watermark; this is also the automatic behavior on a first run with no state file.
+
+import Franchise from 'madden-franchise';
+import { createHash } from 'node:crypto';
+import { writeFileSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { buildPayload } from './extract/payload.js';
+import { loadOrCreateKeypair, generateKeypair, saveKeypair, signPayload } from './lib/signing.js';
+import { loadState, saveState } from './lib/state.js';
+
+const DEFAULT_KEY_PATH = resolve(import.meta.dirname, '..', '.keys', 'extractor');
+const DEFAULT_STATE_PATH = resolve(import.meta.dirname, '..', '.extractor-state.json');
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args[0] === 'keygen') {
+    const keyPath = readFlag(args, '--key') ?? DEFAULT_KEY_PATH;
+    const keypair = generateKeypair();
+    saveKeypair(keyPath, keypair);
+    const keyId = createHash('sha256').update(keypair.publicKeyPem).digest('hex');
+    console.log(`New keypair written to ${keyPath}.private.pem / ${keyPath}.public.pem`);
+    console.log(`\nkeyId: ${keyId}`);
+    console.log('\nRegister this as a franchise_signing_key row (public_key + key_id):\n');
+    console.log(keypair.publicKeyPem);
+    return;
+  }
+
+  const savePath = args[0];
+  if (!savePath) {
+    console.error('Usage: node src/cli.js <savePath> [--out <file>] [--key <keyPathPrefix>] [--state <file>] [--full|--backfill]');
+    console.error('       node src/cli.js keygen [--key <keyPathPrefix>]');
+    process.exitCode = 1;
+    return;
+  }
+
+  const outPath = readFlag(args, '--out') ?? defaultOutPath(savePath);
+  const keyPath = readFlag(args, '--key') ?? DEFAULT_KEY_PATH;
+  const statePath = readFlag(args, '--state') ?? DEFAULT_STATE_PATH;
+  const toolVersion = readToolVersion();
+
+  const existingState = loadState(statePath);
+  const fullMode = args.includes('--full') || args.includes('--backfill') || existingState === null;
+  if (existingState === null) {
+    console.error(`No state file at ${statePath} — running full/backfill (expected on first run).`);
+  } else if (fullMode) {
+    console.error('Running --full: including every game in the save, ignoring the capture watermark.');
+  }
+
+  console.error(`Opening save: ${savePath}`);
+  const franchise = await Franchise.create(savePath);
+
+  console.error('Extracting...');
+  const { payload, nextCapturedGameKeys, gamesIncludedCount, gamesTotalCount, pendingCount } = await buildPayload(franchise, {
+    toolVersion,
+    fullMode,
+    capturedGameKeys: existingState?.capturedGameKeys ?? new Set(),
+  });
+
+  const canonicalBytes = Buffer.from(JSON.stringify(payload));
+  const payloadHash = createHash('sha256').update(canonicalBytes).digest('hex');
+
+  const { privateKeyPem, publicKeyPem } = loadOrCreateKeypair(keyPath);
+  const signature = signPayload(canonicalBytes, privateKeyPem);
+  const keyId = createHash('sha256').update(publicKeyPem).digest('hex');
+
+  const envelope = {
+    payload,
+    payloadHash,
+    signature,
+    signingPublicKey: publicKeyPem,
+    keyId,
+  };
+
+  writeFileSync(outPath, JSON.stringify(envelope, null, 2));
+  saveState(statePath, { capturedGameKeys: nextCapturedGameKeys, toolVersion, savePath });
+
+  console.error(`Wrote ${outPath}`);
+  console.error(`  keyId: ${keyId}`);
+  console.error(`  mode: ${fullMode ? 'full/backfill' : 'incremental'}`);
+  console.error(
+    `  clock: ${payload.clock.stage} / ${payload.clock.weekType} / week ${payload.clock.weekIndex}`,
+  );
+  console.error(`  teams: ${payload.teams.length}`);
+  console.error(`  players: ${payload.players.length}`);
+  console.error(`  games: ${gamesIncludedCount} included (of ${gamesTotalCount} in the save)`);
+  console.error(`  playerGameStats: ${payload.playerGameStats.length}`);
+  console.error(`  teamGameStats: ${payload.teamGameStats.length}`);
+  console.error(`  pendingPlayerStatGames: ${pendingCount} (suggestedStatus: ${payload.suggestedStatus})`);
+  console.error(`  playerWeekStatus: ${payload.playerWeekStatus.length}`);
+  console.error(`  transactions: ${payload.transactions.length}`);
+  console.error(`  cumulativeStats: ${payload.cumulativeStats.length}`);
+  console.error(`  depthChart: ${payload.depthChart.length}`);
+  console.error(`  state: ${statePath} (${nextCapturedGameKeys.size} games watermarked)`);
+}
+
+function readFlag(args, name) {
+  const i = args.indexOf(name);
+  return i === -1 ? undefined : args[i + 1];
+}
+
+function defaultOutPath(savePath) {
+  const base = savePath.replace(/[/\\]+$/, '').split(/[/\\]/).pop();
+  return resolve(process.cwd(), `${base}.stat_import.json`);
+}
+
+function readToolVersion() {
+  const pkgPath = resolve(import.meta.dirname, '..', 'package.json');
+  const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+  return pkg.version ?? '0.0.0';
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exitCode = 1;
+});

package/src/extract/clock.js

@@ -0,0 +1,75 @@
+// Decodes the franchise clock from SeasonInfo (the singleton table; capacity 1).
+//
+// Two regimes that behave nothing alike — see docs/extraction-findings.md §3 and the
+// comment block on franchise_week in db/schema.sql:
+//
+//   stage='NFLSeason' -> CurrentWeek is monotonic 0..22 straight through the playoffs,
+//                        disambiguated by CurrentWeekType. Trustworthy.
+//   stage='OffSeason' -> CurrentWeek resets to 0 and jumps non-uniformly. Decorative.
+//                        CurrentOffseasonStage (0..10) is authoritative instead.
+//
+// `sequence` (the only safe cross-regime sort key) is NOT assigned here — schema.sql
+// migration note 7 makes it explicit that sequence assignment is an ingest-side
+// responsibility requiring knowledge of previously observed weeks, which a single
+// stateless save read cannot provide. This module only decodes the clock as read.
+
+import { getTableByNameAndCapacity, liveRecords } from '../lib/franchise-table.js';
+
+const REGULAR_SEASON_WEEK_TYPES = new Set([
+  'PreSeason',
+  'RegularSeason',
+  'WildcardPlayoff',
+  'DivisionalPlayoff',
+  'ConferencePlayoff',
+  'ProBowl',
+  'SuperBowl',
+]);
+
+export async function extractClock(franchise) {
+  const table = await getTableByNameAndCapacity(franchise, 'SeasonInfo');
+  const info = liveRecords(table)[0];
+  if (!info) throw new Error('SeasonInfo table has no live record — cannot read the clock');
+
+  const stage = info.CurrentStage; // 'NFLSeason' | 'OffSeason'
+  const weekType = info.CurrentWeekType;
+  const weekIndex = info.CurrentWeek;
+  const offseasonStage = stage === 'OffSeason' ? info.CurrentOffseasonStage : null;
+
+  if (stage === 'NFLSeason' && !REGULAR_SEASON_WEEK_TYPES.has(weekType)) {
+    throw new Error(
+      `Unrecognized CurrentWeekType "${weekType}" during NFLSeason — widen ` +
+        'REGULAR_SEASON_WEEK_TYPES (and the matching franchise_week.week_type CHECK in ' +
+        'db/schema.sql) rather than coercing. A rejected import beats a silently wrong week.',
+    );
+  }
+
+  return {
+    // franchise_season identity
+    seasonIndex: info.CurrentYear, // 0-indexed franchise season number
+    calendarYear: info.CurrentSeasonYear, // NFL calendar year, e.g. 2025
+
+    // franchise_week identity
+    stage,
+    weekType: stage === 'OffSeason' ? 'OffSeason' : weekType,
+    weekIndex,
+    offseasonStage,
+    // Human-facing week: only meaningful for the regular season / preseason count-up.
+    // NULL in the offseason, where no meaningful week number exists (schema.sql comment).
+    displayWeek: stage === 'NFLSeason' ? weekIndex + 1 : null,
+
+    // Sub-phase booleans that drive the offseason lock calendar. Kept as a raw bag —
+    // franchise_week.phase_flags_json is deliberately JSON so EA can add phases without
+    // a migration.
+    phaseFlags: extractPhaseFlags(info),
+  };
+}
+
+function extractPhaseFlags(info) {
+  const flags = {};
+  for (const field of info.fieldsArray) {
+    if (field.key.startsWith('Is')) {
+      flags[field.key] = info[field.key];
+    }
+  }
+  return flags;
+}

package/src/extract/cumulative-stats.js

@@ -0,0 +1,35 @@
+// Extracts player_cumulative_stat: raw cumulative baselines, captured per import so
+// ingest can diff consecutive imports to recover categories the save only exposes as
+// a running total. Currently that's exactly one category — rec_targets — per the
+// schema seed (stat_category.default_source='derived_diff') and findings.md §2/§12
+// rule 6: targets exist ONLY on CareerOffensiveStats.TARGETS, never per-game or
+// per-season. This extractor stays scoped to that single verified case rather than
+// speculatively capturing all 86 CareerOffensiveStats fields "just in case" — nothing
+// else in the schema or findings calls for them, and CareerOffensiveStats is
+// real-career-inclusive (imported NFL history + sim), so surfacing an unused raw
+// field as if it meant something would be actively misleading (schema.sql comment).
+//
+// Player.CareerStats resolves DIRECTLY to one CareerOffensiveStats row (not a
+// per-season wrapper like SeasonStats/GameStats — career is inherently one row).
+// Only offensive-position players (WR/RB/TE/QB) have a meaningful CareerStats ref;
+// this silently skips anyone whose ref doesn't resolve (e.g. pure defensive players,
+// whose career stats live in a different position-bucketed table this doesn't need).
+
+import { resolveFieldRef } from '../lib/franchise-table.js';
+
+export async function extractCumulativeStats(franchise, { players }) {
+  const rows = [];
+  for (const player of players) {
+    const careerRow = await resolveFieldRef(franchise, player._record, 'CareerStats');
+    if (!careerRow) continue;
+    if (careerRow.TARGETS === undefined || careerRow.TARGETS === null) continue; // non-offensive bucket
+
+    rows.push({
+      externalPlayerId: player.externalPlayerId,
+      statCategoryKey: 'rec_targets',
+      scope: 'career',
+      value: careerRow.TARGETS,
+    });
+  }
+  return rows;
+}

package/src/extract/depth-chart.js

@@ -0,0 +1,56 @@
+// Extracts depth_chart_entry: Team.DepthChart -> position slot -> Player[] wrapper,
+// Player0=starter, Player1=backup, ... Not needed for scoring; drives "is my guy
+// starting?" on waiver/draft day (schema.sql comment on depth_chart_entry).
+//
+// Position slot keys (QB, WR, SLWR, KR, PR, ...) are Madden's own depth-chart
+// position taxonomy — finer-grained than Player.Position (e.g. WR splits into
+// WR/SLWR for outside vs. slot). Stored as-is; not reconciled against
+// player_season_snapshot.position, which is a separate, coarser field.
+
+import { resolveFieldRef } from '../lib/franchise-table.js';
+
+export async function extractDepthChart(franchise, { teams }) {
+  const rows = [];
+
+  for (const team of teams) {
+    const depthChart = await resolveFieldRef(franchise, team._record, 'DepthChart');
+    if (!depthChart) continue;
+
+    for (const field of depthChart.fieldsArray) {
+      if (field.key === 'LockedEntries') continue; // not a position slot
+      if (!field.isReference) continue;
+
+      const wrapper = await resolveFieldRef(franchise, depthChart, field.key);
+      if (!wrapper) continue;
+
+      const playerSlots = await resolveWrapperSlotsWithIndex(franchise, wrapper, 'Player');
+      for (const { record: playerRecord, depthOrder } of playerSlots) {
+        rows.push({
+          externalTeamId: team.externalTeamId,
+          positionSlot: field.key,
+          depthOrder,
+          externalPlayerId: playerRecord.PresentationId,
+        });
+      }
+    }
+  }
+
+  return rows;
+}
+
+// Like franchise-table.js's resolveWrapperSlots, but keeps each slot's numeric index
+// (0 = starter) rather than discarding it — depth_order is part of the schema's
+// UNIQUE constraint and the entire point of this table (schema.sql: depth_order
+// INTEGER NOT NULL, 0=starter), so it can't be thrown away like GameStats[] does.
+async function resolveWrapperSlotsWithIndex(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 resolveFieldRef(franchise, wrapperRecord, field.key);
+    if (record) resolved.push({ record, depthOrder: Number(field.key.slice(slotPrefix.length)) });
+  }
+  return resolved;
+}

package/src/extract/games.js

@@ -0,0 +1,78 @@
+// Extracts sim_game — the schedule + box score, and the anchor every stat row
+// hangs off (via each stat row's own SeasonGame ref, resolved elsewhere).
+//
+// No stable game ID exists in the save (findings.md §4), so downstream identity is
+// the natural key (season, week, home, away) per schema.sql's UNIQUE on sim_game.
+
+import { getTableByNameAndCapacity, liveRecords, resolveFieldRef } from '../lib/franchise-table.js';
+
+// db/schema.sql sim_game.game_status CHECK. The save also reports a template/junk
+// status 'Invalid_' on one permanently-unscheduled row per save (score 0-0, no
+// resolvable team refs, confirmed across multiple saves) — not a real game, dropped
+// below rather than widening the CHECK to accept it.
+const VALID_GAME_STATUSES = new Set(['Unscheduled', 'Unplayed', 'HomeWon', 'AwayWon', 'Tie']);
+const UNDECIDED_STATUSES = new Set(['Unscheduled', 'Unplayed']);
+
+export async function extractGames(franchise, { indexTeamsByTeamIndex }) {
+  const table = await getTableByNameAndCapacity(franchise, 'SeasonGame');
+  const records = liveRecords(table).filter((r) => VALID_GAME_STATUSES.has(r.GameStatus));
+
+  const games = [];
+  for (const r of records) {
+    const homeTeamRecord = await resolveFieldRef(franchise, r, 'HomeTeam');
+    const awayTeamRecord = await resolveFieldRef(franchise, r, 'AwayTeam');
+    // Unscheduled slots (playoff byes/TBD brackets) have no resolvable team refs yet.
+    if (!homeTeamRecord || !awayTeamRecord) continue;
+
+    const homeTeam = indexTeamsByTeamIndex.get(homeTeamRecord.TeamIndex);
+    const awayTeam = indexTeamsByTeamIndex.get(awayTeamRecord.TeamIndex);
+    if (!homeTeam || !awayTeam) continue;
+
+    const decided = !UNDECIDED_STATUSES.has(r.GameStatus);
+
+    games.push({
+      // natural key for sim_game.UNIQUE(franchise_season_id, franchise_week_id, home, away)
+      seasonWeek: r.SeasonWeek,
+      seasonWeekType: r.SeasonWeekType,
+      homeExternalTeamId: homeTeam.externalTeamId,
+      awayExternalTeamId: awayTeam.externalTeamId,
+
+      // Madden reports 0 for an unplayed game's score, not a null/absent value —
+      // normalize to NULL so "hasn't happened" is never confused with a real 0-0
+      // result once the game finalizes (schema.sql: home_score/away_score nullable).
+      homeScore: decided ? r.HomeScore : null,
+      awayScore: decided ? r.AwayScore : null,
+      gameStatus: r.GameStatus,
+      // IsSimmed=false => a human played it => footage exists (findings §4).
+      resultType: decided ? (r.IsSimmed ? 'cpu_simmed' : 'user_played') : null,
+
+      detail: {
+        homeScoreQuarter1: r.HomeScoreQuarter1,
+        homeScoreQuarter2: r.HomeScoreQuarter2,
+        homeScoreQuarter3: r.HomeScoreQuarter3,
+        homeScoreQuarter4: r.HomeScoreQuarter4,
+        homeScoreOT: r.HomeScoreOT,
+        awayScoreQuarter1: r.AwayScoreQuarter1,
+        awayScoreQuarter2: r.AwayScoreQuarter2,
+        awayScoreQuarter3: r.AwayScoreQuarter3,
+        awayScoreQuarter4: r.AwayScoreQuarter4,
+        awayScoreOT: r.AwayScoreOT,
+      },
+
+      // kept for the stats extractor to match Game*Stats rows back to this game via
+      // the identical (week, weekType, home, away) key, without re-resolving refs.
+      _record: r,
+    });
+  }
+  return games;
+}
+
+export function gameKey(g) {
+  return `${g.seasonWeekType}:${g.seasonWeek}:${g.homeExternalTeamId}:${g.awayExternalTeamId}`;
+}
+
+/** True once a game has a real result (not a future/unscheduled slot). Operates on
+ * the already-extracted game's own `gameStatus` field — no new payload field. */
+export function isDecidedGame(g) {
+  return !UNDECIDED_STATUSES.has(g.gameStatus);
+}