annotation.json

{
  "version": 1,
  "modules": {

    "Pelotero.Prelude": {
      "decisions": [
        {
          "name": "HandMaintainedVersionString",
          "what": "appVersion is a hand-edited Text constant rather than read from cabal-generated Paths_pelotero_engine.version",
          "why": [
            "Reading from Paths_* requires plumbing the autogen module into the import graph and pulls Data.Version handling into every site that logs the version.",
            "The risk is drift: bumping the .cabal version without bumping this constant produces a binary that lies about itself in the fetch log.",
            "Mitigation is process: a release checklist item, not a code-level guarantee."
          ],
          "affects": ["appVersion"]
        }
      ],
      "invariants": {
        "appName": [
          "compile-time constant; canonical application name used in logging and any place that needs to identify this binary as the producer of a record",
          "OverloadedStrings is enabled solely so the string literal types as Text without explicit pack"
        ],
        "appVersion": [
          "hand-maintained version string; not derived from cabal's PackageInfo_pelotero_engine, so it can drift from the .cabal file unless updated by hand",
          "intended to be embedded wherever the engine identifies itself (audit fields, fetch-log enrichment)"
        ]
      }
    },

    "Pelotero.Provider.ExternalId": {
      "decisions": [
        {
          "name": "SingleHelperEliminatesImplicitContract",
          "what": "All upstream-id <-> external_id Text encodings live in this one module; every site that crosses that boundary calls a typed helper rather than rolling its own T.pack . show",
          "why": [
            "The legacy pattern (T.pack . show . unTeamId scattered across Sync.Players, Sync.Schedule, Sync.Boxscores) was an implicit string contract; if anyone changed one site without changing the others, every game upsert silently skipped because resolveTeam returned Nothing for every team.",
            "Centralising the encoding makes the contract a function call: changing the encoding requires editing one module, and the type system enforces that callers go through the helper.",
            "The roundtrip property (externalIdToTeamId . externalIdFromTeamId === Just) is checked by Hedgehog so encoding drift between forward and reverse paths is caught at test time."
          ],
          "affects": [
            "externalIdFromTeamId",
            "externalIdFromPlayerId",
            "externalIdFromGameId",
            "externalIdToTeamId",
            "externalIdToPlayerId",
            "externalIdToGameId"
          ]
        },
        {
          "name": "PerIdTypePairsNotPolymorphic",
          "what": "Six concrete functions (one from + one to per id type) rather than a single class-based polymorphic encoder",
          "why": [
            "Three id types is below the threshold where typeclass machinery earns its keep; six monomorphic helpers are easier to grep, easier to test, and easier to read at call sites.",
            "If a fourth id type appears (e.g. ProviderInternal player ids using a different scheme), this is the place to revisit; until then, monomorphic wins."
          ],
          "affects": []
        }
      ],
      "invariants": {
        "externalIdFromTeamId": [
          "TeamId -> Text via T.pack . show . unTeamId",
          "stable byte-for-byte: this is the canonical wire encoding stored in team_external_id.external_id"
        ],
        "externalIdFromPlayerId": [
          "PlayerId -> Text via T.pack . show . unPlayerId",
          "consumed by Sync.Players.upsertAllPlayers and Sync.Boxscores.upsertEntries (forward) and Sync.Boxscores.syncOne (reverse via the roundtrip)"
        ],
        "externalIdFromGameId": [
          "GameId -> Text via T.pack . show . unGameId",
          "consumed by Sync.Schedule.upsertOneGame and Sync.Boxscores.syncOne"
        ],
        "externalIdToTeamId": [
          "Text -> Maybe TeamId; reads via Text.Read.readMaybe and wraps in TeamId",
          "returns Nothing on any non-integer or negative value; an empty Text returns Nothing"
        ],
        "externalIdToPlayerId": [
          "mirror of externalIdToTeamId"
        ],
        "externalIdToGameId": [
          "mirror of externalIdToTeamId"
        ]
      }
    },

    "Pelotero.Effects.Logging": {
      "decisions": [
        {
          "name": "KatipPatternLiftedFromCheeblr",
          "what": "Logging effect uses the Katip pattern: logFM, logItem, addNamespace, addContext; production interpreter writes structured JSON to stdout",
          "why": [
            "Cheeblr already runs this pattern in production with structured search-friendly JSON logs; reusing it means we get the same querying, the same tooling, and one less invented wheel.",
            "Structured logs make per-warning grepping (e.g. 'all UnknownPosition warnings in the last week') a one-line jq query rather than a regex over freeform text.",
            "Stdout-only at the application layer; the runtime (systemd / OCI runtime / k8s) handles persistence and rotation. We deliberately avoid in-process file rotation because it duplicates the runtime's job."
          ],
          "affects": ["logFM", "logItem", "addNamespace", "addContext", "runLoggingKatip", "runLoggingCapture", "runLoggingDiscard"]
        },
        {
          "name": "ReplacesConvertLogWarnings",
          "what": "Pelotero.MLB.Convert.logWarnings (direct stderr IO) is gone; warning emission goes through Logging.logFM with structured fields",
          "why": [
            "Convert.logWarnings wrote bare stderr lines with a 'convert: ' prefix; the prefix was the only structure log scrapers had to grab onto.",
            "Going through Logging means each ConvertWarning becomes a structured log item with its constructor name as a tag; downstream systems can filter on the tag, not on string-prefix scraping.",
            "The Handle-parameterised logWarningsTo indirection existed only to make logWarnings testable; with a capturing test interpreter (runLoggingCapture), that indirection disappears."
          ],
          "affects": ["logFM"]
        }
      ],
      "invariants": {
        "logFM": [
          "Logging send-only; structured log emission with severity + message",
          "production: writes a JSON line to stdout via Katip's stdout scribe",
          "test: appends to an IORef-backed [LogLine] under runLoggingCapture, or no-ops under runLoggingDiscard"
        ],
        "logItem": [
          "Logging send-only; logs a Katip-LogItem-encodable payload with a severity",
          "used for richer structured events (e.g. SyncResult summaries) where a plain text message loses the structure"
        ],
        "addNamespace": [
          "Logging operation; runs an inner Eff under a nested Katip namespace",
          "used to scope all logs from a syncRosters call under e.g. 'sync.rosters' so traces are easy to filter"
        ],
        "addContext": [
          "Logging operation; attaches structured key/value context to all logs emitted by the inner Eff",
          "carries through to JSON output as additional fields on each log line"
        ],
        "runLoggingKatip": {
          "intent": "Production interpreter; writes JSON-formatted log lines to stdout via Katip's stdout scribe",
          "effects": ["IOE"],
          "notes": [
            "scribes and namespace are wired once at startup",
            "stdout-only; the runtime is responsible for persistence/rotation"
          ]
        },
        "runLoggingCapture": {
          "intent": "Test interpreter that captures every emitted log into an IORef-backed [LogLine] returned alongside the inner action's result",
          "effects": ["IOE"],
          "notes": [
            "uses IOE because it needs an IORef; not pure",
            "captures the structured payload (severity, namespace, message), suitable for asserting 'these warnings were emitted in this order' in property tests"
          ]
        },
        "runLoggingDiscard": {
          "intent": "Test interpreter that silently drops every log; pure (no effects on the inner stack)",
          "notes": [
            "default for tests that don't care about logging output",
            "leaves the rest of the effect stack untouched so callers don't have to thread IOE just to silence logs"
          ]
        }
      }
    },
    "Pelotero.Draft": {
      "decisions": [
        {
          "name": "PureLogicNoEffects",
          "what": "Pelotero.Draft is the pure data layer for the draft state machine: the DraftState ADT, the DraftCommand / DraftEvent / DraftError sums, the DraftContext / DraftPickEntry / DraftSummary records, plus a handful of total query helpers (currentPicker, picksRemaining, isPlayerAvailable). No effect dependencies.",
          "why": [
            "Phase D.1a separated the transition logic from the persistence layer so the state machine is testable with hedgehog without any DB or in-memory effect runner.",
            "The transition logic itself lives in Pelotero.Draft.Machine as draftAction (and the existential-erasing wrapper runDraftCommand); the effectful handler in Pelotero.Draft.Run (Phase D.1c) wraps runDraftCommand with PlayerRanking / DraftPick / Players / Logging / Clock; that is where commands actually get persisted.",
            "Pelotero.Domain.Draft remains the upstream-id-keyed pre-compute layer (order generation from a strategy + team list); this module is DB-id-keyed because the state machine talks to the persistence layer."
          ],
          "affects": []
        },
        {
          "name": "AutoPickIsNotACommand",
          "what": "DraftCommand has only StartDraft, MakePick, EndDraft; auto-picking is a wrapper at the effect layer (D.1c) that consults PlayerRanking, intersects with dcAvailable, and issues MakePick with the chosen player",
          "why": [
            "Keeps the pure logic with one place-a-player path rather than two; the strategy logic for which player gets picked stays separate from the how of recording it.",
            "Means the state machine itself doesn't take a ranking source as input: the ranking lookup happens before MakePick is constructed.",
            "If a future strategy variant emerges (round-specific overrides, drop-and-replace), it lives at the effect layer alongside the existing auto-pick wrapper, not as a new state-machine command."
          ],
          "affects": []
        }
      ],
      "invariants": {
        "initialState": [
          "WaitingToStart; the empty start of any draft"
        ],
        "currentPicker": [
          "Whose pick is up? Nothing if the draft hasn't started or has finished.",
          "Used by Pelotero.Draft.Run's auto-pick wrapper (D.1c) to identify which team's ranking to consult."
        ],
        "picksRemaining": [
          "Length of dcRemaining inside Drafting; 0 outside Drafting."
        ],
        "isPlayerAvailable": [
          "Set membership in dcAvailable; False outside Drafting."
        ]
      }
    },
    "Pelotero.Draft.Machine": {
      "decisions": [
        {
          "name": "CremTopologyForCompileTimeLegalTransitions",
          "what": "DraftTopology is declared as a crem Topology with explicit allowed transitions per vertex (WaitingToStartV -> {self, DraftingV}; DraftingV -> {self, CompleteV}; CompleteV -> {self}); draftAction is checked at compile time against the topology, so an illegal transition is a type error rather than a runtime branch",
          "why": [
            "An invariant like 'you cannot go from Complete back to Drafting' wants to be enforced by the compiler, not by a runtime guard that future refactors might quietly remove.",
            "The self-edges on every vertex are deliberate: rejection cases (NotYourTurn, PlayerAlreadyDrafted, DraftAlreadyComplete) return the same vertex they entered with, so the topology must permit self-loops.",
            "Cost: the GADT DraftStateG plus the singletons machinery (SDraftVertex via singletons-th) is a chunk of type-level apparatus, and DraftAction's return type is verbose. Acceptable because the alternative (a flat DraftState sum + a runtime 'is this legal?' check inside applyCommand) is what we had before and is exactly what we're moving away from."
          ],
          "affects": ["draftAction"]
        },
        {
          "name": "ExistentialWrapperForCallerErgonomics",
          "what": "SomeDraftStateG hides the vertex index so callers can hold draft state without threading the singleton type through their signatures; runDraftCommand is the consumer-facing wrapper that takes a SomeDraftStateG and a command and returns the next SomeDraftStateG plus the result",
          "why": [
            "Pelotero.Draft.Run.applyAndPersist sees state as an opaque value, not as a vertex-indexed thing; the persistence loop doesn't care which vertex it's at except via the runtime tag (draftStateVertex).",
            "Hiding the index also keeps the public API expressible without type-level Haskell at every call site; downstream code reads as plain Haskell.",
            "fromDraftState / toDraftState exist as the bridge to and from the unindexed Pelotero.Draft.DraftState; useful when the caller has constructed state from raw data (e.g. recovery from DB) or wants to render state as the simpler sum type."
          ],
          "affects": ["runDraftCommand", "toSomeDraftStateG", "fromDraftState", "toDraftState"]
        },
        {
          "name": "LastPickEmitsTwoEvents",
          "what": "draftAction on MakePick for the last remaining pick emits both PickRecorded and DraftCompleted in that order; EndDraft from Drafting emits only DraftCompleted",
          "why": [
            "The handler in Pelotero.Draft.Run persists both events in order: insert the DraftPick row first, then log the completion. The league_config status update is the orchestrator's job, not the state-machine handler's, per Pelotero.Draft.Run's StatusUpdateNotInScope decision.",
            "Crash between events leaves the pick recorded with the in-memory machine state still consistent: the next run sees an empty dcRemaining and re-runs draftAction to get DraftCompleted again; idempotent on the in-memory side. DB-level idempotency on partial-draft retries is documented separately under NoCrashRecovery.",
            "Flipping the order would leave a 'completed' log line with the last pick missing from draft_pick: a worse partial state for anyone reading logs."
          ],
          "affects": ["draftAction"]
        },
        {
          "name": "PicksMadeListSnocAppend",
          "what": "DraftContext.dcPicksMade is appended to in pick order (oldest first) using snoc; total cost is O(n^2) across a full draft",
          "why": [
            "n is small: at most ~300 picks for a 25-team / 12-round league. 300^2 = 90,000 cons cells; not a perf concern.",
            "Oldest-first ordering means the DraftSummary doesn't need a final reverse step, and the audit trail reads naturally in chronological order without calling reverse on every read.",
            "If a much larger draft format appears (50-team dynasty with 30 rounds = 1500 picks), revisit; until then the simpler shape wins."
          ],
          "affects": ["draftAction"]
        }
      ],
      "invariants": {
        "initialMachineState": [
          "SomeDraftStateG SWaitingToStartV WaitingToStartG; the existential-wrapped starting state for every draft"
        ],
        "draftStateVertex": [
          "extracts the runtime DraftVertex tag from a SomeDraftStateG without unwrapping the GADT payload",
          "useful for the auto-draft loop which needs to know 'are we in Drafting?' as a value-level predicate"
        ],
        "fromDraftState": [
          "DraftState -> SomeDraftStateG; bridges from the unindexed sum (Pelotero.Draft) into the indexed GADT shape",
          "constructs the appropriate singleton tag per constructor"
        ],
        "toDraftState": [
          "DraftStateG v -> DraftState; the inverse of fromDraftState modulo vertex index erasure"
        ],
        "toSomeDraftStateG": [
          "DraftStateG v -> SomeDraftStateG; trivially wraps an indexed state under its singleton"
        ],
        "draftAction": {
          "intent": "Per-vertex transition: given a state indexed by vertex v and a DraftCommand, return an ActionResult under DraftTopology with either an event list or a DraftError plus the next (vertex-indexed) state",
          "notes": [
            "Pure inside Identity; same inputs -> same outputs.",
            "Rejection cases (NotYourTurn, PlayerAlreadyDrafted, DraftAlreadyComplete, DraftNotStarted, EmptyDraftPlan, DraftAlreadyStarted) emit Left and stay on the same vertex via the topology's self-loops.",
            "MakePick on the final dcRemaining entry transitions to CompleteV emitting [PickRecorded entry, DraftCompleted summary].",
            "EndDraft from Drafting transitions to CompleteV emitting [DraftCompleted summary] with whatever picks have been made so far; useful for early commissioner-driven termination.",
            "An empty DraftPlan (dpOrder == []) returns Left EmptyDraftPlan rather than transitioning to a degenerate Complete state."
          ]
        },
        "runDraftCommand": [
          "SomeDraftStateG -> DraftCommand -> (Either DraftError [DraftEvent], SomeDraftStateG)",
          "the existential-erasing wrapper around draftAction; consumed by Pelotero.Draft.Run.applyAndPersist",
          "runs the ActionResult under Identity to extract the pure value pair"
        ]
      }
    },
    "Pelotero.Score": {
      "decisions": [
        {
          "name": "PureKernelSplitFromEffects",
          "what": "scorePlayerPure / sumBattingPoints / sumPitchingPoints / rowToBattingStats / rowToPitchingStats are pure and exported separately from the effectful scoreLeague / scoreTeam",
          "why": [
            "The pure kernel is the part hedgehog tests can hit without spinning up Postgres.",
            "Splitting them lets us unit-test 'given these rows, the score is X' without an in-memory effect runner: just a record literal and a function call.",
            "The pure functions deliberately take and return DB row types (BattingRow / PitchingRow), not domain types, because the round-trip BattingRow -> BattingStats -> Points loses no information; storing-then-loading and direct-scoring agree by construction."
          ],
          "affects": ["scorePlayerPure", "sumBattingPoints", "sumPitchingPoints", "rowToBattingStats", "rowToPitchingStats"]
        },
        {
          "name": "MissingLeagueReturnsNothing",
          "what": "scoreLeague and scoreTeam both return Maybe; Nothing means the league config (or the team) wasn't in the DB",
          "why": [
            "Distinguishes 'this league doesn't exist' from 'this league has zero teams' (Just LeagueScore { lscTeams = [] }).",
            "An empty lineup still produces a TeamScore with zero points: dropping such teams would be a presentation choice the caller should make.",
            "Doesn't validate that the team belongs to the league in scoreTeam: caller's responsibility to check."
          ],
          "affects": ["scoreLeague", "scoreTeam"]
        },
        {
          "name": "PitOutsIsCanonicalNoTextRoundTrip",
          "what": "rowToPitchingStats passes pitOuts straight through from the DB row; pitInningsPitched no longer exists in PitchingStats",
          "why": [
            "Phase B.1 collapsed the redundant pitInningsPitched (Maybe Text) + pitOuts (Maybe Int) pair into pitOuts only. The wire-format string is parsed at convert time and discarded; the DB stores outs; readers see outs.",
            "Removes the parseInningsPitched . renderInningsPitched round-trip that previously lived in the score path. Saves one parse and one render per pitching row, more importantly removes a class of subtle bug (a future caller setting pitOuts only would have been silently zeroed by the round-trip).",
            "scorePitching now reads pitOuts directly without any parse step."
          ],
          "affects": ["rowToPitchingStats"]
        },
        {
          "name": "PeriodFromUtcStartEnd",
          "what": "scoreLeague derives lscPeriodStart / lscPeriodEnd by utctDay'ing lcScoringStart and lcScoringEnd from the league config",
          "why": [
            "league_config stores UTCTime instants because lineup-lock cutoffs are timezone-sensitive (see Pelotero.Domain.League decision ScoringPeriodAsUtcTime), but the DB game.game_date is Day, so the query needs Day bounds.",
            "Truncating UTCTime to Day in UTC is correct only because game_date is also stored in UTC at write time. A change to either column's timezone semantics would break this silently.",
            "The two utctDay calls happen once per scoreLeague invocation; not a perf concern."
          ],
          "affects": ["scoreLeague", "scoreTeam"]
        },
        {
          "name": "DateRangePlayerMapBuilds",
          "what": "buildPlayerMaps issues exactly two BoxscoreEntry effect calls (getBattingForDateRange and getPitchingForDateRange) for the entire scoring period; the SQL joins game_player_batting/pitching against game on game_id and filters by game.game_date in [startDay, endDay]",
          "why": [
            "Phase C.2 collapsed the per-game query loop. The previous shape did 2 * N transactions for an N-game period (~900 round-trips for a 30-day MLB period); the date-range version is exactly 2.",
            "Correctness preserved: the date-range query joins against gameSchema and filters by game_date, which is exactly the predicate Games.getGamesByDateRange uses, so the fetched row set is identical to what the per-game loop produced.",
            "The downstream per-game filter in scoreOnePlayerForGame is unchanged and load-bearing: each player's bucket now contains rows from every game in the period, and the filter narrows to just the game being scored. Removing the filter would silently score every player's full-period stats once per game."
          ],
          "affects": ["buildPlayerMaps"]
        },
        {
          "name": "ScoringReadsFromLineupSnapshots",
          "what": "scoreOneTeam reads from LineupSnapshot.getSnapshotsForDateRange (grouped in-memory by game_id), NOT from the team's current lineup_slot rows",
          "why": [
            "Phase B.3 fixed the correctness bug where scoring used the current lineup against historical games. Real fantasy leagues lock lineups daily; mid-period lineup edits used to retroactively change prior days' scores.",
            "The scoring loop is now per-game (which it should always have been): for each game in the period, read the snapshot for that team for that game, score that game's stats against that snapshot, sum.",
            "Re-running scoring at any point gives the same answer for the same (league, period, team) triple. This is the invariant owners were checking against and losing trust over.",
            "Implementation note (post Phase C.2): the snapshot fetch is also a single date-range query (LSnap.getSnapshotsForDateRange) grouped in-memory by game_id via Map.fromListWith, rather than N per-game fetches."
          ],
          "affects": ["scoreOneTeam", "scoreTeam"]
        }
      ],
      "invariants": {
        "rowToBattingStats": [
          "mechanical Int32 -> Int widening on every Maybe field; lossless"
        ],
        "rowToPitchingStats": [
          "Int32 -> Int widening on every Maybe field; lossless",
          "pitOuts is preserved straight from the row; no Text reconstruction (post Phase B.1)"
        ],
        "sumBattingPoints": [
          "sumPoints over (scoreBatting m . rowToBattingStats): a fold; empty list yields zeroPoints"
        ],
        "sumPitchingPoints": [
          "mirror of sumBattingPoints for pitching"
        ],
        "scorePlayerPure": [
          "produces a PlayerScore with batting + pitching subtotals and their sum",
          "pure: same inputs -> same output, no IO or randomness",
          "the canonical hedgehog target for scoring property tests"
        ],
        "scoreLeague": {
          "intent": "Score every team in a league across the league's configured scoring period using snapshotted lineups",
          "effects": ["LeagueConfig", "LeagueTeam", "LineupSnapshot", "BoxscoreEntry"],
          "notes": [
            "returns Nothing if the league config row is absent",
            "empty lineups produce zero-point TeamScores rather than being dropped",
            "uses LineupSnapshot.getSnapshotsForDateRange (grouped in-memory by game_id), NOT LineupSlot.getSlotsForTeam: see decision ScoringReadsFromLineupSnapshots",
            "deterministic across re-runs: same (league, period) inputs always yield the same scores"
          ]
        },
        "scoreTeam": [
          "scores a single team using the league's period",
          "returns Nothing if either the league config or the team is absent",
          "does NOT validate that the team belongs to the league"
        ],
        "buildPlayerMaps": [
          "takes (startDay, endDay) and issues exactly two date-range queries (Box.getBattingForDateRange and Box.getPitchingForDateRange)",
          "buckets results into Map DbPlayerId [BattingRow] and Map DbPlayerId [PitchingRow] via Map.fromListWith (++)",
          "exactly 2 database round trips per scoring invocation, independent of period length (post Phase C.2)"
        ],
        "scoreOneTeam": [
          "internal helper; not exported. Per-team aggregation: load all snapshot rows for the period via LSnap.getSnapshotsForDateRange, group them by game_id with Map.fromListWith, then for each (gameId, [playerIds]) pair call scoreOnePlayerForGame and aggregate per-player scores across games via Map.fromListWith mergePlayerScores",
          "signature subject to change"
        ],
        "scoreOnePlayerForGame": [
          "internal; given a player and a game id, filter the player's period-wide row buckets to only that game's rows, then call scorePlayerPure",
          "a player on the snapshot with no boxscore activity for that game gets zero points (filter yields empty lists)"
        ],
        "mergePlayerScores": [
          "internal; pointwise addition of two PlayerScores, used when aggregating per-game scores for the same player across multiple games"
        ]
      }
    },
    "Pelotero.Draft.Run": {
      "decisions": [
        {
          "name": "PerCommandPersistencePrimitive",
          "what": "applyAndPersist is the per-command primitive: takes one command, runs it through runDraftCommand, persists whichever events come out, returns the new state and the result. Both runAutoDraft and any future manual-pick UI handler go through it.",
          "why": [
            "Keeps the persistence logic in one place; manual UI picks and auto-picks share the same code path.",
            "Returns SomeDraftStateG so the caller threads state across calls explicitly — no IORef, no MVar, no state-holding effect. Makes the primitive fully testable with the existing in-memory effect interpreters.",
            "DraftError flows through the Either; AutoDraftError is a strict superset for the loop-specific failures (no candidate, stuck, etc.)."
          ],
          "affects": ["applyAndPersist", "runAutoDraft"]
        },
        {
          "name": "StatusUpdateNotInScope",
          "what": "applyAndPersist requires only DraftPick + Clock + Logging; the league_config status transition from 'draft' to 'active' is NOT done here",
          "why": [
            "Pelotero.Draft.Run's job is recording picks. League lifecycle is a separate concern that belongs to whatever orchestrator started the draft.",
            "Decoupling means a replay-pick CLI command can re-run picks without bumping league status, and league-status transitions are tested independently of draft picking.",
            "Reverses the implication in D.1a's LastPickEmitsTwoEvents decision that DraftCompleted becomes a league_config status update; that annotation is being narrowed accordingly."
          ],
          "affects": ["applyAndPersist", "persistEvent", "runAutoDraft"]
        },
        {
          "name": "AutoPickFallbackToLowestIdAvailable",
          "what": "autoPickCommand falls back to Set.lookupMin (dcAvailable ctx) when the team's ranking has no available candidates",
          "why": [
            "Deterministic — same draft plan + same DB state always picks the same player, so the loop is reproducible across runs.",
            "Position-aware fallback (e.g. fill the team's positional needs) is more sophisticated and is properly D.1d's concern when porting AutoDraft.hs from old_src/.",
            "WarningS log line on every fallback so operators can see when ranking coverage is poor — the metric to watch is fallback-rate-per-draft."
          ],
          "affects": ["autoPickCommand"]
        },
        {
          "name": "NoCrashRecovery",
          "what": "If the auto-draft loop crashes mid-draft, the partially-inserted DraftPick rows must be manually cleaned up before retry; recordPickT's Abort-on-conflict means a naive retry will fail at the first already-recorded pick",
          "why": [
            "State-from-DB recovery (read existing picks, reconstruct DraftContext, resume from where we left off) is genuinely useful but well beyond D.1c's scope.",
            "The Abort-on-conflict fail-fast is the correct default — silent retry of duplicate picks would mask real bugs (double-pick, race condition, stale state, draft-id reuse).",
            "Operators retrying a partial draft DELETE FROM draft_pick WHERE league_config_id = X and re-run runAutoDraft. Not elegant, but the failure is rare enough that the explicit cleanup is acceptable for now."
          ],
          "affects": ["runAutoDraft"]
        }
      ],
      "invariants": {
        "applyAndPersist": [
          "Takes (league, state, command); runs command through runDraftCommand; persists events for Right; logs at WarningS and returns Left for rejection.",
          "Rejection cases leave state unchanged (relies on the topology's self-loops in Pelotero.Draft.Machine).",
          "PickRecorded events become recordPick calls with picked_at = Clock.now; DraftStarted and DraftCompleted are log-only."
        ],
        "persistEvent": [
          "PickRecorded -> recordPick with server-stamped picked_at and the league_config id from the caller.",
          "DraftStarted -> InfoS log line with league id and team count.",
          "DraftCompleted -> InfoS log line with league id and pick count."
        ],
        "autoPickCommand": [
          "Reads PR.getRankingsForTeam for the team whose turn it is.",
          "Filters rankings to dcAvailable; picks the head if any remain.",
          "Falls back to Set.lookupMin (dcAvailable ctx) if the ranked-and-available list is empty; logs WarningS on fallback.",
          "Returns Left (AutoDraftNoCandidate team) only if dcAvailable is empty AND rankings are exhausted."
        ],
        "runAutoDraft": {
          "intent": "Drive a draft from initialMachineState to Complete via auto-picks; return the DraftSummary or an AutoDraftError.",
          "notes": [
            "Persists every pick as a DraftPickRow as it happens.",
            "Single-process invocation; state lives only in this Eff stack — no IORef, no DB-state recovery on restart.",
            "DraftPlan must be pre-built by the caller (Pelotero.Domain.Draft.generateDraftOrder + active player pool); this function does not construct the plan.",
            "Future CLI command 'pelotero draft run --league=X' will live above this and own the plan construction."
          ]
        }
      }
    },
    "Pelotero.Lineup.Snapshot": {
      "decisions": [
        {
          "name": "SnapshotPerGamePerTeamWithExistsCheck",
          "what": "snapshotLineupsForGame copies the current lineup_slot rows into lineup_snapshot keyed by (league_team_id, game_id); idempotency is enforced both by an explicit 'snapshot exists?' check at the orchestration level and by a UNIQUE constraint at the table level",
          "why": [
            "The (league_team_id, game_id) key gives us 'what was this team's lineup for this specific game'. Re-running scoring against a snapshot gives a deterministic answer.",
            "Once a snapshot exists for a (team, game) pair, it is treated as locked-in and is NOT overwritten by re-running. ON CONFLICT DO NOTHING in writeSnapshotsT plus the explicit pre-check together ensure 'first snapshot wins'. This deliberately prevents late-edit scenarios where an owner changes a lineup after the snapshot job ran.",
            "There is no game-start-time guard at the orchestration level; the schema only tracks game_date (Day), not a precise instant. Operators are responsible for scheduling snapshots before first pitch."
          ],
          "affects": ["snapshotLineupsForTeam", "snapshotLineupsForGame"]
        },
        {
          "name": "TypedResultNotUnit",
          "what": "snapshotLineupsForTeam returns PerTeamResult and snapshotLineupsForGame returns SnapshotResult; both are aggregates that surface counts (teams snapshotted vs already-done, rows inserted)",
          "why": [
            "An earlier sketch had snapshotLineupsForGame return (); operators couldn't tell whether anything happened.",
            "PerTeamResult has two constructors: TeamSnapshotted Int (n rows submitted to the snapshot table for this team — the number reflects rows attempted; under concurrent snapshot jobs ON CONFLICT DO NOTHING could silently drop duplicates so n may overstate actual inserts in that case) and TeamAlreadyHasSnapshot (snapshotExistsForTeamGame returned True; nothing was written).",
            "SnapshotResult is a record { snapTeamsSnapshotted, snapTeamsAlreadyDone, snapRowsInserted } with a Monoid instance: mempty is all zeros and (<>) is pointwise addition, so the per-league aggregation is just mconcat."
          ],
          "affects": ["snapshotLineupsForTeam", "snapshotLineupsForGame"]
        },
        {
          "name": "ModuleLivesInLineupNotEffects",
          "what": "snapshot orchestration lives at Pelotero.Lineup.Snapshot, not under Pelotero.Effects",
          "why": [
            "This module composes multiple effects (LineupSlot, LineupSnapshot, LeagueConfig, LeagueTeam, Logging) to do a piece of business logic; it is not itself an effect definition.",
            "Pelotero.Effects.LineupSnapshot is the dispatch interface; Pelotero.Lineup.Snapshot is the orchestration layer that uses it.",
            "Mirrors the layering between Pelotero.Sync.* (orchestration) and Pelotero.Effects.* (dispatch)."
          ],
          "affects": []
        },
        {
          "name": "EmptyLineupCornerCase",
          "what": "If a team has no lineup_slot rows at snapshot time, snapshotLineupsForTeam writes zero rows and returns TeamSnapshotted 0; the snapshotExistsForTeamGame query will subsequently return False (no rows), so a re-run with a non-empty lineup will write a fresh snapshot",
          "why": [
            "This is a deliberate quirk: empty-lineup snapshots and 'no snapshot taken' are indistinguishable at the storage level.",
            "In practice this is desirable — a team that joins late and has no lineup at the first snapshot should still get scored once they set one — but it does mean 'TeamSnapshotted 0' is operationally meaningful."
          ],
          "affects": ["snapshotLineupsForTeam"]
        }
      ],
      "invariants": {
        "snapshotLineupsForTeam": {
          "intent": "Snapshot one team's current lineup for one game; idempotent on (team, game)",
          "effects": ["LineupSlot", "LineupSnapshot", "Logging"],
          "notes": [
            "first calls LSnap.snapshotExistsForTeamGame; if True, returns TeamAlreadyHasSnapshot without touching lineup_slot",
            "if False, reads the team's lineup via LS.getSlotsForTeam, projects each slot row to a LineupSnapshotRow tagged with the game id, and writes via LSnap.writeSnapshots",
            "logs an InfoS event with team/game/row count on the success path"
          ]
        },
        "snapshotLineupsForGame": {
          "intent": "Snapshot every team in every active league for one game",
          "effects": ["LeagueConfig", "LeagueTeam", "LineupSlot", "LineupSnapshot", "Logging"],
          "notes": [
            "loads all LeagueConfig rows via LC.getAll, filters to those with lcStatus == \"active\"",
            "for each active league, fetches league teams via LT.getForLeague and snapshots each via snapshotLineupsForTeam",
            "aggregates per-team results into a SnapshotResult and logs an InfoS summary"
          ]
        },
        "toSnapshot": [
          "internal helper; projects (DbGameId, LineupSlotRow) into a LineupSnapshotRow"
        ]
      }
    },

    "Pelotero.Sync.Players": {
      "decisions": [
        {
          "name": "TeamsBeforePlayersOrdering",
          "what": "syncRosters upserts all teams first, builds a TeamId -> DbTeamId map, then upserts players using that map to resolve playerRowCurrentTeamId",
          "why": [
            "Players carry a foreign key to team via current_team_id; if the team doesn't exist in the DB at insert time, the FK either fails (with constraint enforcement) or installs a dangling reference (without).",
            "Building the map in memory between the two phases avoids a second round-trip per player to look up the DB team id.",
            "The two phases share one syncedAt timestamp from the Clock effect, so last_synced_at on team and player rows match exactly for a given sync run, useful when reasoning about staleness."
          ],
          "affects": ["syncRosters", "upsertAllTeams", "upsertAllPlayers"]
        },
        {
          "name": "ProviderAgnosticEntryPoint",
          "what": "syncRosters takes already-converted [Team] and [Player] domain values plus a precomputed SHA-256, never touches wire types or HTTP",
          "why": [
            "Keeps the sync pipeline testable in isolation: tests construct domain values directly and run against in-memory effect interpreters.",
            "Allows alternative providers (a future non-MLB feed, manual data import) to reuse this exact code path by doing their own wire->domain conversion upstream.",
            "The SHA is computed by the caller because only the caller has the raw bytes; passing it in here keeps this module from depending on Crypto.Hash."
          ],
          "affects": ["syncRosters"]
        },
        {
          "name": "ResourceLiteralActiveRosters",
          "what": "syncRosters writes fetchLogResource = 'active-rosters' as a literal rather than parameterising it",
          "why": [
            "The MLB roster endpoint queried (rosterUrl) filters to activeStatus=ACTIVE on the server side, so this resource name is the literal truth of what was fetched.",
            "If a future scope adds inactive/40-man/minor-league fetches, that becomes a new resource name passed in by the caller, not a flag here."
          ],
          "affects": ["syncRosters"]
        },
        {
          "name": "ExternalIdViaCentralisedHelper",
          "what": "upsertAllTeams and upsertAllPlayers call Pelotero.Provider.ExternalId.externalIdFromTeamId / externalIdFromPlayerId, never inline T.pack . show",
          "why": [
            "Phase A.1 collapsed the implicit cross-module string contract into a typed helper. The sync pipeline now goes through one canonical encoding for all upstream id -> Text conversions.",
            "The Hedgehog roundtrip property (externalIdToTeamId . externalIdFromTeamId === Just) catches any future encoding drift at test time.",
            "Sync.Schedule.resolveTeam uses the matching reverse function (externalIdToTeamId via the lookup); both sides go through the same module."
          ],
          "affects": ["upsertAllTeams", "upsertAllPlayers"]
        },
        {
          "name": "TotalHandCharFromDomain",
          "what": "upsertAllPlayers uses Pelotero.Domain.Player.handChar (total) instead of T.head . renderHandedness (partial)",
          "why": [
            "Phase A.6 introduced handChar :: Handedness -> Char as an exhaustive case-of in the domain layer. T.head's partiality is gone because the conversion is no longer a Text indexing operation.",
            "The total function lives next to the Handedness type so any new constructor forces an exhaustivity check at compile time, eliminating the legacy class of bug where a renderHandedness change could silently break this caller.",
            "DB column for bat_side / pitch_hand is still Text (CHAR(1) has padding gotchas in PostgreSQL), but the API path is now total end-to-end."
          ],
          "affects": ["upsertAllPlayers"]
        },
        {
          "name": "IdempotencyByPayloadSha",
          "what": "syncRosters short-circuits when the inbound payloadSha matches the most recent fetch-log row for ('provider', 'active-rosters', 'scope'); the no-op path returns SyncResult { syncTeamsUpserted = 0, syncPlayersUpserted = 0, syncFetchSha256 = payloadSha } and emits one InfoS log line",
          "why": [
            "Re-running with an unchanged payload should not re-upsert ~30 teams + ~700 players or write a new fetch-log row; that work is wasted writes and DB contention. The fetch-log already records payload_sha256 for exactly this purpose; the short-circuit reads at most one row before deciding whether to do anything.",
            "Ordering is load-bearing: the fetch-log INSERT is the LAST step in the non-skip path, AFTER both upserts complete. A crash mid-upsert leaves no log row, so the next run retries rather than silently skips a partial state. Inverting this ordering would mask partial writes — comments at the call site flag this for future maintainers.",
            "Phase C.1."
          ],
          "affects": ["syncRosters"]
        }
      ],
      "invariants": {
        "syncRosters": {
          "intent": "Provider-agnostic upsert pipeline: SHA-checked short-circuit, then (on miss) teams, players, and finally a fetch-log entry",
          "effects": ["Players", "Teams", "FetchLog", "Clock", "Logging"],
          "notes": [
            "single Clock.now call shared by both team and player upserts; both rows get identical last_synced_at",
            "fetchLogResource hardcoded to 'active-rosters'; scope is supplied by the caller (typically the season as Text)",
            "fetchLogRecordCount is the player count, NOT the team count; teams are bookkeeping",
            "fetchLogId and fetchLogFetchedAt are Nothing on the inbound row; the DB layer fills them via DEFAULT",
            "SHA short-circuit (Phase C.1): if payloadSha matches the most recent fetchLogRow.fetchLogPayloadSha256 for this (provider, 'active-rosters', scope), returns a zero-row SyncResult and emits exactly one InfoS log line. Both counts being zero is the canonical 'we skipped' signal — distinguishable from 'first call with empty inputs' by the syncFetchSha256 echoing the input",
            "the fetch-log INSERT is the last step in the non-skip path; reordering it before the upserts would let a crash at the wrong moment silently mask a partial-state on the next run"
          ],
          "consumes": [
            "CLI sync command (process startup or scheduled run)"
          ]
        },
        "upsertAllTeams": [
          "produces Map TeamId DbTeamId where the key is the upstream MLB id and the value is the surrogate DB id, in the order traverse visits the input list",
          "extId = externalIdFromTeamId team — single source of truth for the encoding",
          "teamRowId is Nothing on insert; the DB layer assigns the surrogate id"
        ],
        "upsertAllPlayers": [
          "uses the team map from upsertAllTeams to resolve playerRowCurrentTeamId; players whose upstream team isn't in the map (unknown / minor league call-up) get Nothing for current_team_id",
          "extId = externalIdFromPlayerId player — single source of truth",
          "discards the DbPlayerId returned by upsertPlayerByExternalId; the caller doesn't need it",
          "handedness conversion via handChar (total Domain function), not T.head of renderHandedness"
        ]
      }
    },

    "Pelotero.Sync.Schedule": {
      "decisions": [
        {
          "name": "SkipGamesWithUnknownTeams",
          "what": "syncSchedule resolves both away and home teams via lookupTeamByExternalId; if either is missing, the entire game is skipped and counted in schedGamesSkipped",
          "why": [
            "The schedule endpoint can include teams that haven't been ingested yet (spring training affiliates, all-star game rosters, exhibition opponents).",
            "Inserting a game with a NULL or fabricated team_id violates the foreign-key contract and silently corrupts later joins.",
            "Skipping is recoverable: re-run after a roster sync and the game shows up. Failing the whole batch on one missing reference is not.",
            "The skip count is surfaced in ScheduleSyncResult so operators can detect when this is happening at scale."
          ],
          "affects": ["syncSchedule", "upsertOneGame"]
        },
        {
          "name": "FetchLogResourceLiteralSchedule",
          "what": "syncSchedule writes fetchLogResource = 'schedule' as a literal rather than parameterising it",
          "why": [
            "Mirrors the convention in Pelotero.Sync.Players where 'active-rosters' is the literal resource name.",
            "If a future scope adds e.g. minor-league schedule fetches, that becomes a new resource string, not a flag here."
          ],
          "affects": ["syncSchedule"]
        },
        {
          "name": "ExternalIdViaCentralisedHelper",
          "what": "upsertOneGame and resolveTeam call Pelotero.Provider.ExternalId helpers; no inline encoding",
          "why": [
            "Phase A.1 made resolveTeam use externalIdFromTeamId on the lookup side and upsertOneGame use externalIdFromGameId for game external ids.",
            "The implicit cross-module contract that previously lived in source comments ('the show-of-Int convention here MUST match upsertAllTeams') is now a typed function call. Source comments don't need to assert what the type system enforces."
          ],
          "affects": ["upsertOneGame", "resolveTeam"]
        },
        {
          "name": "IdempotencyByPayloadSha",
          "what": "syncSchedule short-circuits when the inbound payloadSha matches the most recent fetch-log row for ('provider', 'schedule', 'scope'); the no-op path returns ScheduleSyncResult { schedGamesUpserted = 0, schedGamesSkipped = 0, schedFetchSha256 = payloadSha } and emits one InfoS log line",
          "why": [
            "Symmetric to the syncRosters short-circuit (Phase C.1). Re-running with an unchanged schedule payload should not re-upsert hundreds of games.",
            "Ordering matters here too: the fetch-log INSERT is the LAST step in the non-skip path. A crash mid-upsert leaves no log row, so retry is safe.",
            "Both counts (schedGamesUpserted and schedGamesSkipped) being zero is the unambiguous 'we skipped entirely' signal; distinguishable from a non-skip run with an empty input list because the input list of zero games is itself a degenerate non-skip case that still writes a fetch-log row.",
            "Phase C.1."
          ],
          "affects": ["syncSchedule"]
        }
      ],
      "invariants": {
        "syncSchedule": {
          "intent": "Provider-agnostic upsert pipeline for already-converted [Game] domain values: SHA-checked short-circuit, then (on miss) per-game upserts and a fetch-log entry",
          "effects": ["Games", "Teams", "FetchLog", "Clock", "Logging"],
          "notes": [
            "writes one fetch-log row per call (in the non-skip path) with resource = 'schedule', scope supplied by caller (typically a date-range string like '2025-04-01..2025-04-07')",
            "fetchLogRecordCount is the total games count, NOT just upserted games; matches the input list length so an operator can compare against schedGamesUpserted to detect skip-rate",
            "single Clock.now call shared across all game upserts in this run",
            "iteration order is the input list order",
            "SHA short-circuit (Phase C.1): if payloadSha matches the most recent fetchLogRow.fetchLogPayloadSha256 for this (provider, 'schedule', scope), returns a zero-row ScheduleSyncResult and emits exactly one InfoS log line. Both schedGamesUpserted and schedGamesSkipped are zero",
            "the fetch-log INSERT is the last step in the non-skip path, mirroring syncRosters; this is load-bearing for partial-failure recovery"
          ]
        },
        "upsertOneGame": [
          "returns True on successful upsert, False on skip (either team unresolved)",
          "extId = externalIdFromGameId game (post Phase A.1)",
          "discards the DbGameId returned by upsertGameByExternalId; downstream boxscore upserts re-resolve via lookupGameByExternalId at scoring time"
        ],
        "resolveTeam": [
          "wraps lookupTeamByExternalId, calling externalIdFromTeamId for the encoding",
          "the encoding is now type-checked at compile time via the Provider.ExternalId helper, not asserted via source comments"
        ]
      }
    },

    "Pelotero.Sync.Boxscores": {
      "decisions": [
        {
          "name": "PerGameFetchLogEntry",
          "what": "syncBoxscores writes one FetchLogRow per game (resource = 'boxscore', scope = the GameId as text), not one row per batch",
          "why": [
            "Catch-up runs ('which boxscores are new since last sync?') become a single getLastFetch query per gameId, which is the natural primitive for incremental work.",
            "A per-batch row would force the caller to remember which games it included, defeating the purpose of an external log.",
            "Cost: high write volume on a fresh-season backfill (~2400 rows for a full season). Acceptable; provider_fetch_log is append-only and not a query hot path.",
            "Phase C.1 reads from this same per-game row to make the SHA short-circuit possible."
          ],
          "affects": ["syncBoxscores", "syncOne"]
        },
        {
          "name": "MissingPlayerSilentSkip",
          "what": "If lookupPlayerByExternalId returns Nothing for a boxscore entry's playerId, the entry is silently skipped (no upsert, no warning, no error)",
          "why": [
            "Real cause: roster sync hasn't run for that player yet (mid-season callup, traded mid-game). Re-running after the next roster sync recovers the data.",
            "Failing the whole game would lose 25 known-good batting lines because of one unknown player.",
            "Trade-off: silently skipping means no operator visibility. A future improvement would be to count skipped entries in BoxscoreSyncResult so the operator can detect when this is happening at scale."
          ],
          "affects": ["upsertEntries"]
        },
        {
          "name": "MissingTeamSilentDegradation",
          "what": "If a boxscore entry has a TeamId that isn't in the local DB, the team_id field is set to NULL rather than skipping the entry",
          "why": [
            "The batting/pitching row is still useful without team attribution (player's stats are intact); team is a join convenience.",
            "MLB occasionally ships parentTeamId values for teams that haven't been ingested (international roster expansions, mid-season ownership swaps).",
            "Symmetrical to player handling above but lossier — at least the player would re-sync; an unknown team_id never gets backfilled. Worth flagging if it becomes common."
          ],
          "affects": ["upsertEntries"]
        },
        {
          "name": "InningsPitchedOutsAtConvertTime",
          "what": "Conversion to outs happens in Pelotero.MLB.Convert.convertPitching at the wire boundary; pitchingRowFor in this module just copies pitOuts straight through",
          "why": [
            "Phase B.1 moved the parse to convertPitching, where the wire string and the wire pitOuts are reconciled and a WireFieldDiscrepancy warning is emitted on disagreement. The sync layer no longer carries the redundancy; it sees a single Maybe Int.",
            "Previously inningsPitchedOuts here did the prefer-IP-string-then-fall-back-to-outs dance. That logic is gone; this module is now a mechanical Int -> Int32 narrowing per field."
          ],
          "affects": ["pitchingRowFor"]
        },
        {
          "name": "ExternalIdViaCentralisedHelper",
          "what": "syncOne uses externalIdFromGameId to resolve GameId -> DbGameId and externalIdFromPlayerId / externalIdFromTeamId for entry resolution",
          "why": [
            "Phase A.1 unified the encoding; this module is one of the consumer sites. Same compile-time enforcement applies.",
            "Phase C.1 also uses externalIdFromGameId as the fetch-log scope, so the SHA-lookup path goes through the same helper as the upsert path."
          ],
          "affects": ["syncOne", "upsertEntries"]
        },
        {
          "name": "BoxscoreOutcomeTypedSum",
          "what": "syncOne returns Either BoxscoreSyncError BoxscoreOutcome where BoxscoreOutcome = BoxUpserted Int Int [ConvertWarning] | BoxUnchanged",
          "why": [
            "Distinguishes 'fetched, parsed, upserted zero rows because the boxscore was genuinely empty' from 'short-circuited on SHA match because nothing changed since last run'. The two are operationally different and need different counters.",
            "Replaces the prior (Int, Int, [ConvertWarning]) tuple. The aggregator in syncBoxscores increments boxGamesProcessed for BoxUpserted and boxGamesUnchanged for BoxUnchanged.",
            "BoxUnchanged carries no warnings because no parse/convert ran; warnings are exclusively a parse/convert artefact."
          ],
          "affects": ["syncOne", "syncBoxscores"]
        },
        {
          "name": "IdempotencyByPayloadSha",
          "what": "syncOne computes sha256Hex of the fetched bytes, looks up the most recent fetch-log row for ('provider', 'boxscore', externalIdFromGameId gid), and returns BoxUnchanged if the SHA matches; in that case the parse, convert, upsert, and fetch-log INSERT are all skipped, and one InfoS log line is emitted",
          "why": [
            "Asymmetry vs. syncRosters/syncSchedule: those callers compute the SHA before invoking the sync, so the short-circuit precedes the HTTP work entirely. For boxscores, the bytes are fetched inside syncOne via MLBClient, so the HTTP cost is unavoidable.",
            "What the short-circuit saves is parse + convert + upsert + fetch-log INSERT — the bulk of the per-game DB work. For a fresh-season backfill where most games are already final (byte-identical on every refetch), this is one HTTP per game and zero DB work.",
            "Live games (mid-game boxscores still updating) will never short-circuit because their bytes change on every poll. That is correct behaviour: live data has to be re-ingested.",
            "Ordering remains load-bearing: the fetch-log INSERT is the LAST step of the non-skip path, so a crash mid-upsert leaves no log row and the next run retries.",
            "Phase C.1."
          ],
          "affects": ["syncOne", "syncBoxscores"]
        }
      ],
      "invariants": {
        "syncBoxscores": {
          "intent": "Process a list of upstream GameIds: resolve each to DbGameId, fetch raw boxscore bytes, decide via SHA whether the payload changed, then (on miss) decode, convert, and upsert per-player batting and pitching rows",
          "effects": ["BoxscoreEntry", "Games", "Players", "Teams", "MLBClient", "FetchLog", "Logging"],
          "notes": [
            "iterates input order; no concurrency at this layer",
            "accumulates per-game results into a BoxscoreSyncResult so partial failures don't abort the batch",
            "boxConvertWarnings is concatenated across all successfully-processed games (now includes any WireFieldDiscrepancy warnings from convertPitching); SHA-skipped games contribute no warnings",
            "boxGamesSeen == boxGamesProcessed + boxGamesUnchanged + length boxErrors as an identity (modulo any future per-game skip categories tracked by boxGamesSkipped)"
          ]
        },
        "syncOne": [
          "GameNotKnown: lookupGameByExternalId returned Nothing; caller must run schedule sync first",
          "FetchFailed: HTTP or transport-level failure from MLBClient",
          "ParseFailed: Aeson decode failure on the raw bytes",
          "writes FetchLog after a successful upsert pass, NOT before — a partial-write scenario doesn't get logged as a successful fetch",
          "C.1 short-circuit: after a successful fetch but before parse, computes sha256Hex of the bytes and reads getLastFetch for ('provider', 'boxscore', externalIdFromGameId gid). On SHA match returns BoxUnchanged; otherwise proceeds with the original parse / convert / upsert / record-fetch path"
        ],
        "upsertEntries": [
          "fold over [BoxscoreEntry] producing (battingCount, pitchingCount)",
          "missing player -> skip entry (counts unchanged); missing team -> degrade team_id to NULL",
          "boxBatting Nothing -> no batting row written; boxPitching Nothing -> no pitching row written"
        ],
        "battingRowFor": ["mechanical Maybe Int -> Maybe Int32 widening for every stat field"],
        "pitchingRowFor": ["same as battingRowFor; pitOuts is passed straight through (no IP string reconciliation here post Phase B.1)"],
        "i32": ["fmap fromIntegral; Int -> Int32 narrowing"],
        "sha256Hex": ["raw ByteString -> hex-encoded Text via SHA-256"]
      }
    },

    "Pelotero.MLB.Urls": {
      "decisions": [
        {
          "name": "UrlsIsolatedAsSwapPoint",
          "what": "All MLB Stats API URLs live in this single module with no other logic; the only way to talk to the upstream service is via this module's exports",
          "why": [
            "If MLB changes the API base or moves an endpoint, this is the only file that needs editing.",
            "If a future provider replaces MLB entirely, this module is the natural delete-and-rewrite boundary.",
            "Side effect: discourages ad-hoc URL construction scattered through fetch code."
          ],
          "affects": ["rosterUrl", "teamsUrl", "scheduleUrl", "scheduleDateUrl", "boxscoreUrl", "gameStatusUrl"]
        }
      ],
      "invariants": {
        "rosterUrl": [
          "pre-filters to activeStatus=ACTIVE on the server side; inactive players are not returned",
          "uses /sports/1/players (sport id 1 = MLB), not /people, because /people requires explicit ID lists"
        ],
        "teamsUrl": [
          "uses sportId=1 (MLB) only; minor-league teams are not returned"
        ],
        "scheduleUrl": [
          "language=en is hardcoded; the MLB API supports other locales but the engine doesn't model them",
          "startDate and endDate are passed as raw String; caller is responsible for the YYYY-MM-DD format MLB expects"
        ],
        "scheduleDateUrl": [
          "convenience wrapper for single-day queries; the MLB API does not have a separate per-day endpoint, so we issue a range query with start==end"
        ],
        "boxscoreUrl": [
          "v1 endpoint; returns the boxscore object whose shape is parsed by Pelotero.MLB.Wire.Boxscore"
        ],
        "gameStatusUrl": [
          "v1.1 endpoint (note the version difference from boxscoreUrl); /feed/live carries scheduled-vs-final status that the boxscore endpoint does not surface cleanly",
          "currently UNUSED in the sync pipeline; reserved for the future 'is this game final yet?' check before scoring"
        ]
      }
    },

    "Pelotero.MLB.Convert": {
      "decisions": [
        {
          "name": "WarningsBesideValuesNotInsteadOf",
          "what": "Conversion functions return ([ConvertWarning], Maybe a) or ([ConvertWarning], a) so warnings accumulate without halting the batch",
          "why": [
            "MLB ships partial records during spring training; halting on the first one means losing the other 700 valid players.",
            "Treating malformed records as exceptions would conflate parse errors (caught upstream by Aeson) with data-quality warnings (this layer's job).",
            "The caller decides whether to log warnings, ignore them, or fail loudly via Logging."
          ],
          "affects": [
            "convertPlayer", "convertPlayers",
            "convertSchedule", "convertDateEntry", "convertGame",
            "convertPosition", "convertHand",
            "convertPitching"
          ]
        },
        {
          "name": "MLBLooseDateFormat",
          "what": "parseDate uses '%Y-%-m-%-d' instead of '%Y-%m-%d'",
          "why": [
            "MLB's schedule endpoint occasionally returns dates without zero-padding ('2024-3-5' instead of '2024-03-05').",
            "The %-m / %-d directives accept both padded and unpadded forms.",
            "Strict %m/%d would silently drop ~5% of pre-season games."
          ],
          "affects": ["parseDate"]
        },
        {
          "name": "InvalidPlayerIdDropsRecord",
          "what": "convertPlayer drops players with id <= 0 entirely (returns Nothing) and emits an InvalidPlayerId warning",
          "why": [
            "An id of 0 or negative is structurally meaningless; the surrogate-key lookup would fail and the rest of the row would be junk anyway.",
            "Position and handedness warnings, in contrast, downgrade to Nothing for that field while keeping the rest of the player; the player is still useful as a name + team reference.",
            "An invalid id removes the only stable identity the record has, so there is nothing left worth keeping."
          ],
          "affects": ["convertPlayer"]
        },
        {
          "name": "BoxscoreEmitsDiscrepancyWarnings",
          "what": "convertBoxscore (specifically convertPitching) can now emit WireFieldDiscrepancy warnings when wire pitOuts disagrees with the parsed wire IP string",
          "why": [
            "Phase B.1 moved IP-string reconciliation here. We parse both wbpInningsPitched and wbpOuts, compare them, and emit WireFieldDiscrepancy if they disagree (rare; usually only during live-update windows).",
            "Output remains a single Maybe Int via parseInningsPitched ip <|> wbpOuts: parsed string is preferred (canonical), wire outs is a fallback, both Nothing is preserved.",
            "Boxscore conversion previously never emitted warnings (the BoxscoreNeverWarns decision); that decision is now narrowed to the batting path. Pitching can warn; batting still doesn't."
          ],
          "affects": ["convertBoxscore", "convertPitching"]
        },
        {
          "name": "DateParseFailureSilentlyDropsEntireDate",
          "what": "convertDateEntry returns ([], []) on date parse failure without emitting an InvalidGameDate warning",
          "why": [
            "InvalidGameDate is a defined ConvertWarning constructor but no current code path produces one — it exists for the rendering pass and as an extension point.",
            "Real MLB dates parse via the loose-padding format; failure here would indicate a structural feed change, not a data-quality issue worth surfacing per game.",
            "Known gap: a date corruption in one entry silently loses an entire day's games. Documented as a known limitation."
          ],
          "affects": ["convertDateEntry", "renderWarning"]
        }
      ],
      "invariants": {
        "renderWarning": [
          "renders each ConvertWarning constructor as a single line of stable text",
          "format is conventional: 'convert: <subject> <id> <verb> <detail>'; downstream log scrapers can rely on the leading 'convert: ' prefix",
          "tshow uses Show on the int id, so player ids appear without quotes",
          "WireFieldDiscrepancy renders as 'convert: pitching <playerId> wire field discrepancy: ip=<text> outs=<int>'"
        ],
        "convertPlayer": [
          "returns ([InvalidPlayerId], Nothing) for ids <= 0; the empty-warning case never produces Nothing here",
          "useName / useLastName / nameSlug all default to T.empty when absent (orEmpty); the DB schema requires NOT NULL, so empty is the safe default",
          "playerActive is non-optional in the wire shape; if MLB ever drops it, parsing breaks at Aeson level, not here",
          "currentTeam is decoded as Maybe; teamless players (free agents, just-released) get Nothing for playerTeamId"
        ],
        "convertPlayers": [
          "concats per-player warnings; the resulting list is in input order (well-defined because the envelope's player list is a list)",
          "uses mapMaybe to filter out the Nothing cases (invalid ids); does NOT preserve a placeholder for them"
        ],
        "convertPosition": {
          "notes": [
            "tries abbreviation first, then code; if both are present and one parses while the other is unknown, prefers the parsed one without warning",
            "if NEITHER parses but at least one is present, emits UnknownPosition with the abbreviation if available else the code",
            "if both are Nothing, returns ([], Nothing) silently — the position field is genuinely optional for some records"
          ]
        },
        "convertHand": [
          "WireHandRef wraps a Maybe Text; this function handles WireHandRef Nothing (silent), WireHandRef (Just code) parseable (silent), and WireHandRef (Just code) unknown (warning)",
          "no validation that batSide and pitchHand are consistent for switch-hitters; they are independent fields"
        ],
        "convertSchedule": [
          "folds over wseDates building (warnings, games) in date order",
          "produces GameSchedule wrapping a flat [Game]; the per-date grouping in the wire format is discarded",
          "off-days and missing date entries simply produce no games and no warnings"
        ],
        "convertDateEntry": [
          "if the date string fails parseDate the WHOLE date entry is dropped silently — see decision DateParseFailureSilentlyDropsEntireDate",
          "wdeGames Nothing means 'no games scheduled'; treated as []",
          "delegates per-game conversion to convertGame which then attaches its own warnings"
        ],
        "convertGame": [
          "extracts away/home team ids from the wire's nested teams.away.team.id and teams.home.team.id",
          "if either is missing, emits MissingTeamRef with the gamePk and returns Nothing for the game",
          "preserves the gameDate by carrying the parsed Day in from convertDateEntry"
        ],
        "parseDate": [
          "returns Nothing for any unparseable input; never throws",
          "uses %-m/%-d for MLB's loose padding"
        ],
        "convertBoxscore": [
          "returns ([WireFieldDiscrepancy], entries); the only warnings produced here come from convertPitching",
          "concatenates away-side then home-side entries; team identification on each entry uses wbpParentTeamId from the wire",
          "the GameId comes from the caller"
        ],
        "boxsideEntries": [
          "iterates Map.elems of the players map; the wire keys ('ID660271') are discarded",
          "missing batting or pitching stats default to emptyBatting / emptyPitching"
        ],
        "convertBatting": [
          "mechanical field-by-field copy from WireBoxBatting to BattingStats; no derivation, parsing, or fallback",
          "any divergence between the two record shapes is a compile error here"
        ],
        "convertPitching": {
          "intent": "Convert WireBoxPitching to PitchingStats, reconciling wire IP string against wire outs and emitting a WireFieldDiscrepancy if they disagree",
          "notes": [
            "parses wbpInningsPitched via parseInningsPitched; compares against wbpOuts when both are present",
            "on disagreement: emits WireFieldDiscrepancy and prefers the parsed IP string",
            "output pitOuts = parseInningsPitched ip <|> wbpOuts (parsed string preferred, wire outs fallback)",
            "every other field is a mechanical copy"
          ]
        },
        "orEmpty": [
          "Maybe Text -> Text helper, falling back to T.empty",
          "used to avoid scattering 'fromMaybe T.empty' through the conversion code"
        ],
        "tshow": [
          "Show -> Text helper, T.pack . show",
          "used in renderWarning to embed numeric ids in messages"
        ]
      }
    },

    "Pelotero.MLB.Fetch": {
      "decisions": [
        {
          "name": "WireToDomainTeamPrivate",
          "what": "wireToDomainTeam is not exported; it is duplicated by hand in Pelotero.Effects.MLBClient",
          "why": [
            "Exporting it would create a circular concern: Fetch shouldn't be a public utility module, it's the production HTTP path.",
            "The conversion is one record literal with four fields; duplicating it is cheaper than the import discipline of having both Fetch and MLBClient depend on a shared private module.",
            "If a third caller appears, this should move to a Convert-level helper."
          ],
          "affects": ["wireToDomainTeam"]
        },
        {
          "name": "PayloadShaIsTeamsBytesThenPlayersBytes",
          "what": "computeSha hashes the concatenation of teamsBody (raw bytes) followed by playersBody (raw bytes), in that order",
          "why": [
            "Order matters for stability: if a future fetch reorders the calls, a re-fetch with identical content would produce a different SHA, breaking change-detection.",
            "Using the lazy-then-strict transform inside fetchRosters is a one-place implementation detail and not part of the SHA's semantics.",
            "Teams-then-players matches the order they're parsed and converted in the same function."
          ],
          "affects": ["fetchRosters", "computeSha"]
        }
      ],
      "invariants": {
        "fetchRosters": {
          "intent": "Real-HTTP roster fetcher: pulls teams and players, parses both, converts to domain, returns FetchedRosters with payload SHA",
          "effects": ["IO (HTTP, network)"],
          "notes": [
            "two HTTP calls happen sequentially, not concurrently; latency is teams + players, not max(teams, players)",
            "if either fetch errors at HTTP level, returns Left with the URL in the message",
            "if either body fails to parse (Aeson), returns Left with 'Teams parse failure: ...' or 'Players parse failure: ...' prefix",
            "warnings from convertPlayers are surfaced in frWarnings; team conversion does not produce warnings",
            "frPayloadSha is over the concatenation of raw response bodies"
          ],
          "consumes": [
            "Pelotero.Effects.MLBClient.runMLBClientHTTP (production interpreter)"
          ]
        },
        "wireToDomainTeam": [
          "private; converts WireTeam to DTeam.Team",
          "wtLocationName is Maybe Text in the wire; defaults to T.empty because Team.teamLocationName is non-Maybe",
          "duplicated by hand in Pelotero.Effects.MLBClient.runMLBClientFixture"
        ],
        "fetchSchedule": {
          "intent": "Real-HTTP schedule fetcher for a date range",
          "effects": ["IO"],
          "notes": [
            "single HTTP call; parses through Pelotero.MLB.Wire.Schedule then converts via Convert.convertSchedule",
            "warnings are passed through as fsWarnings",
            "returns Left on HTTP error or parse failure"
          ]
        },
        "fetchBoxscoreRaw": [
          "returns the raw response body as ByteString without parsing",
          "the caller parses with Pelotero.MLB.Wire.Boxscore + Pelotero.MLB.Convert.convertBoxscore at the point of use",
          "asymmetry vs. fetchRosters/fetchSchedule is deliberate: boxscore fetches are sometimes archived raw before processing"
        ],
        "fetchUrl": [
          "private helper; one HTTP GET, returns the body or an HTTP error message",
          "non-2xx responses are returned as Left, not thrown"
        ],
        "computeSha": [
          "SHA-256 of the input bytes, hex-encoded as Text"
        ]
      }
    },

    "Pelotero.MLB.Wire.Boxscore": {
      "decisions": [
        {
          "name": "FlatRecordPerStatsCategory",
          "what": "The batting and pitching wire records list every Maybe Int field individually rather than using a Map Text Int",
          "why": [
            "Named fields make the conversion to BattingStats / PitchingStats a mechanical record-to-record copy that the compiler verifies.",
            "A Map-based representation would defer typo-detection to runtime.",
            "The cost is verbose Aeson FromJSON instances, but those are write-once."
          ],
          "affects": []
        },
        {
          "name": "InningsPitchedAsTextAtWireOnly",
          "what": "wbpInningsPitched is decoded as Maybe Text; wbpOuts is decoded as Maybe Int; both stay as wire-shape, with reconciliation in convertPitching",
          "why": [
            "MLB sends '6.2' meaning six and two-thirds innings; decoding as Double gives floating-point grief.",
            "Both fields persist all the way to convertPitching, where they are reconciled and a discrepancy warning is emitted on disagreement.",
            "After Phase B.1, the Domain.Stats type stores ONLY pitOuts. The Text representation is a wire-layer fact only."
          ],
          "affects": []
        }
      ]
    },

    "Pelotero.MLB.Wire.Team": {
      "decisions": [
        {
          "name": "WireTeamMinimalFields",
          "what": "WireTeam parses only id, name, abbreviation, and locationName; ignores division, league, venue, founded year, etc.",
          "why": [
            "The DB stores only what we display in lineup/box rendering; ignoring the rest is the simplest way to avoid schema bloat.",
            "If a future feature needs division or league info, we re-parse here without any data migration.",
            "Aeson silently ignores unknown JSON keys, so this is forward-compatible against MLB adding fields."
          ],
          "affects": []
        }
      ]
    },

    "Pelotero.MLB.Wire.Player": {},

    "Pelotero.MLB.Wire.Schedule": {
      "decisions": [
        {
          "name": "InlineWireGameTeamParser",
          "what": "WireGameTeam's FromJSON instance manually extracts team.id rather than reusing WireTeamRef from Wire.Player",
          "why": [
            "Schedule context only needs the id; pulling in WireTeamRef would either re-export it from Player.hs or duplicate the type.",
            "Inlining the parse keeps the Schedule wire module self-contained.",
            "If schedule entries ever need team names, this is the place to swap in WireTeamRef."
          ],
          "affects": []
        }
      ]
    },

    "Pelotero.DB.Provider": {
      "decisions": [
        {
          "name": "TolerantParseStrictRender",
          "what": "parseProviderName returns Maybe rather than failing; renderProviderName is total over the closed sum",
          "why": [
            "Reading: an unknown provider name in the database (e.g. an old row from a discontinued provider) shouldn't crash the whole query.",
            "Writing: the writer always uses the rendered constant from the sum, so writes are never typos.",
            "Adding a provider is a code change (new constructor + new parse case + new render case); no migration needed because the column is TEXT."
          ],
          "affects": ["parseProviderName", "renderProviderName"]
        },
        {
          "name": "WireFormatNamesAreStable",
          "what": "renderProviderName values ('mlb', 'pelotero-internal') are stable strings that can never change without a data migration",
          "why": [
            "The text is stored in DB rows (player_external_id, team_external_id, game_external_id, provider_fetch_log).",
            "Renaming a constructor without renaming the rendered string would silently invalidate every row of that provider."
          ],
          "affects": ["renderProviderName"]
        }
      ],
      "invariants": {
        "renderProviderName": [
          "exhaustive over the sum; adding a constructor without a render case is a -Wincomplete-patterns error",
          "produces lowercase, hyphen-separated names matching the SQL convention"
        ],
        "parseProviderName": [
          "returns Nothing for unknown names rather than failing",
          "case-sensitive: 'MLB' and 'mlb' are distinct, only the second matches"
        ]
      }
    },
    "Pelotero.DB.ProviderKeyed": {
      "decisions": [
        {
          "name": "ParametricExternalIdEntity",
          "what": "ExternalIdE i f is a single rel8able record parameterised by the surrogate id type, NOT three separate per-table records (PlayerExternalId, TeamExternalId, GameExternalId)",
          "why": [
            "All three external-id companion tables have identical column shape (entity_id, provider, external_id, fetched_at); the only difference is the type of entity_id. Sharing the record type forces that fact at compile time.",
            "Adding a fourth provider-keyed table is one TableSchema literal plus one ProviderKeyed instance; no new entity record needed.",
            "Cost: one Rel8able instance with a (DBType i, DBEq i) constraint, plus standalone-deriving ergonomics. Acceptable for the consolidation."
          ],
          "affects": []
        },
        {
          "name": "TypeclassOverRecordOfFunctions",
          "what": "ProviderKeyed is a typeclass with associated type families (RowEntity, RowId), not a record-of-functions value passed to free-standing helpers",
          "why": [
            "The associated type families let GHC propagate RowId row through to the surrogate-id type at every call site without manual threading.",
            "Type applications (linkExternalIdT @PlayerRow) at the few sites where row is otherwise ambiguous from the value-level args; explicit and greppable.",
            "A Proxy-based or record-of-functions variant would push that disambiguation to value-level boilerplate at every call site."
          ],
          "affects": []
        },
        {
          "name": "InsertAndUpdateAreInstanceMethods",
          "what": "insertRowT and updateRowByIdT are typeclass methods (each instance provides its own), NOT default methods derived from rowSchema and a generic rowToExpr",
          "why": [
            "The rel8 Insert and Update clauses need entity-specific knowledge: which field is the surrogate id (so it can be set to unsafeDefault on insert and to lit pid on update), and the per-field 'lit value' translation. Generalising this would require per-field traversals via Generic, which is more machinery than the three current callers justify.",
            "Each instance's insertRowT and updateRowByIdT are literally one-liners that point at the existing per-table insertXxxT and updateXxxT functions, so no real boilerplate is added.",
            "If a fourth provider-keyed table arrives, this design extends cleanly: write the per-table insert/update, declare the instance."
          ],
          "affects": []
        },
        {
          "name": "FacadesPreserveCallSites",
          "what": "Per-table modules (Pelotero.DB.Player / .Team / .Game) re-export the four external-id helpers and their Pool wrappers as one-line facades that call PK.foo @MyRow",
          "why": [
            "Zero call-site changes outside the DB layer. The effect interpreters (runPlayersDB etc.) and Sync code keep importing Pelotero.DB.Player.upsertByExternalIdT exactly as before.",
            "Cost: 4 × 2 = 8 trivial wrapper definitions per table. Worth it to keep the migration scope narrow.",
            "If we later decide call sites should go through PK directly, deleting the facades is a mechanical follow-up."
          ],
          "affects": []
        }
      ],
      "invariants": {
        "linkExternalIdT": [
          "INSERT into externalIdSchema with ON CONFLICT DO NOTHING; idempotent on re-runs",
          "_eidFetchedAt set via unsafeDefault — the DB column has DEFAULT NOW()"
        ],
        "lookupByExternalIdT": [
          "SELECT _eidEntityId WHERE provider AND external_id; returns the first row or Nothing",
          "Phase A.5: replaces the inline lookup that was duplicated across DB.Player / DB.Team / DB.Game"
        ],
        "getExternalIdT": [
          "Reverse lookup; SELECT _eidExternalId WHERE entity_id AND provider"
        ],
        "upsertByExternalIdT": [
          "Atomic within the caller's transaction: lookupByExternalIdT, then either updateRowByIdT (existing entity) or insertRowT + linkExternalIdT (new entity)",
          "Returns the surrogate id either way — caller doesn't need to distinguish insert vs. update"
        ],
        "linkExternalId": ["Pool-flavored wrapper around linkExternalIdT"],
        "lookupByExternalId": ["Pool-flavored wrapper around lookupByExternalIdT"],
        "getExternalId": ["Pool-flavored wrapper around getExternalIdT"],
        "upsertByExternalId": ["Pool-flavored wrapper around upsertByExternalIdT"]
      }
    },
    "Pelotero.DB.Pool": {
      "decisions": [
        {
          "name": "DefaultsAreLocalDevValues",
          "what": "defaultDBConfig points at localhost:5433 / pelotero-engine with empty user/password",
          "why": [
            "These are values for the local Nix dev shell; they fail loudly if used in production.",
            "Production setups must set PG* env vars; sops-nix handles this in real deploys.",
            "An alternative was to require all values explicitly, but that breaks 'cabal run' in a dev shell where defaults are convenient."
          ],
          "affects": ["defaultDBConfig", "loadDBConfig"]
        },
        {
          "name": "DbErrorIsTypedSum",
          "what": "PoolUsageError and MigrationError are constructors of a pure Haskell DBError; consumers can pattern-match rather than re-parse a rendered string",
          "why": [
            "Phase A.3 made DBError flow through the effect layer as a typed Error co-effect; callers in tests or in CLI commands that care about specific failure modes (pool exhaustion, migration drift) can match on the constructor.",
            "renderDBError is still the canonical user-facing rendering; the type is just no longer opaque-text-only.",
            "Adding a new error category remains a constructor + a renderDBError case."
          ],
          "affects": ["renderDBError"]
        }
      ],
      "invariants": {
        "defaultDBConfig": [
          "host=localhost, port=5433, db=pelotero-engine, empty user/password, pool=10, timeout=10s",
          "matches Nix dev shell launch script defaults"
        ],
        "loadDBConfig": {
          "intent": "Read DB config from libpq-conventional env vars + two pelotero-specific tunables",
          "effects": ["IO (env reads)"],
          "notes": [
            "PGHOST/PGPORT/PGDATABASE/PGUSER/PGPASSWORD: standard libpq names",
            "PELOTERO_DB_POOL_SIZE / PELOTERO_DB_ACQUIRE_TIMEOUT: app-specific tunables",
            "missing or unparseable env vars fall back to defaultDBConfig field-by-field"
          ]
        },
        "poolConfig": [
          "private; constructs PoolConfig.Config from a DBConfig",
          "uses staticConnectionSettings (single-host setup)"
        ],
        "acquire": [
          "non-blocking; returns immediately. Pool only opens connections lazily on first runSession.",
          "no validation that the database is reachable until first use"
        ],
        "release": [
          "drains the pool; safe to call on a partially-used pool",
          "does NOT abort in-flight transactions; finishes them then closes connections"
        ],
        "runSession": [
          "single-statement (or multi-statement) Session execution",
          "wraps Pool.use; converts hasql-pool errors to DBError",
          "preserves the Right value type a as-is"
        ],
        "runTransaction": [
          "convenience wrapper: ReadCommitted, Write, single Transaction",
          "atomicity: write commits on success, rolls back on Tx error or thrown exception"
        ],
        "renderDBError": [
          "converts to user-facing Text with a category prefix ('DB pool usage error: ', 'Migration error: ')",
          "exhaustive over the sum"
        ]
      }
    },

    "Pelotero.DB.Migration": {
      "decisions": [
        {
          "name": "OwnedMigrationRunner",
          "what": "Custom migration runner instead of hasql-migration",
          "why": [
            "hasql-migration is broken against current crypton (which we use for SHA-256) and is effectively unmaintained.",
            "Migrations are a couple hundred lines we can own outright; less cost than maintaining a fork.",
            "Owning the implementation also lets us encode our specific operational policy (immutable migrations, hash mismatch is a hard error) directly."
          ],
          "affects": ["runMigrations", "applyAll", "applyOne"]
        },
        {
          "name": "ImmutableMigrationsHashChecked",
          "what": "Each migration file is hashed (SHA-256) on first apply; subsequent runs verify the hash and abort with Mismatch if the file has changed",
          "why": [
            "Prevents accidental edits from silently de-syncing dev/prod schemas.",
            "Forces the convention 'create a new V0042__ file' rather than 'edit V0007__'.",
            "Whitespace-sensitive on purpose: any edit, even cosmetic, trips the alarm."
          ],
          "affects": ["applyOne", "loadScript"]
        },
        {
          "name": "PerMigrationTransaction",
          "what": "Each migration runs in its own transaction (not the whole batch)",
          "why": [
            "A failure rolls back exactly the offending migration, leaving the prior ones intact.",
            "Avoids the 'partially applied batch' state."
          ],
          "affects": ["applyAll", "applyOne"]
        },
        {
          "name": "FilenameOrderIsApplyOrder",
          "what": "Migration files are sorted lexicographically; apply order = filename order",
          "why": [
            "The convention V<NNNN>__<desc>.sql with zero-padded numbers makes lexicographic order match numeric order.",
            "Forgetting to zero-pad (V42__ before V9__) is caught by code review, not by the runner."
          ],
          "affects": ["runMigrations"]
        }
      ],
      "invariants": {
        "runMigrations": {
          "intent": "Apply all .sql files in dir that haven't been applied; verify checksums of those that have",
          "effects": ["IO (filesystem + DB)"],
          "notes": [
            "missing directory is a hard error (MigrationError 'Migration directory not found')",
            "SUCCESS path: returns Right MigrationOutcome with totals",
            "MISMATCH path: returns Left MigrationError with the filename",
            "ensures schema_migrations exists via a CREATE TABLE IF NOT EXISTS at the start of applyAll",
            "idempotent: safe to call on every process startup",
            "most recent migration: V0030__lineup_snapshot.sql (added in Phase B.3)"
          ]
        },
        "loadScript": [
          "private; reads a file's bytes and computes its SHA-256 hex string",
          "scriptName is the bare filename (Text), not the full path"
        ],
        "applyAll": [
          "first runs ensureMigrationsTable in its own transaction",
          "then folds over scripts; on the first Mismatch, stops and returns Left"
        ],
        "applyOne": [
          "looks up the prior checksum for this filename; if present and matching, returns Skipped",
          "if present and DIFFERENT, returns Mismatch (does NOT throw — the caller decides)",
          "if absent, runs the SQL via Tx.sql then inserts the (filename, checksum) pair, both in the same transaction"
        ],
        "ensureMigrationsTable": [
          "CREATE TABLE IF NOT EXISTS schema_migrations (filename TEXT PK, checksum TEXT NOT NULL, applied_at TIMESTAMPTZ DEFAULT NOW())"
        ],
        "selectChecksum": ["Statement Text -> Maybe Text; one row or none"],
        "insertApplied": ["Statement (Text, Text) -> ()"],
        "hexSha256": ["ByteString -> Text; SHA-256 then base16 then UTF-8 decode"]
      }
    },
    "Pelotero.DB.JsonB": {
      "decisions": [
        {
          "name": "WrappersOnlyAtTheDbBoundary",
          "what": "JSONB-going Domain types (LeagueScoring, RosterLimits, LineupLimits) are wrapped by newtypes (JsonbScoring, JsonbRosterLimits, JsonbLineupLimits) only at the rel8 Column boundary; the public LeagueConfigRow API still carries the unwrapped Domain types",
          "why": [
            "Phase A.4 made Domain Aeson-free by moving every ToJSON / FromJSON instance off Domain.Scoring and Domain.Roster onto wrappers in this module.",
            "Wrapping at the rel8 Column boundary localises the bridge to the persistence layer; callers who already hold a LeagueScoring keep getting one back from getById and friends, with the wrap/unwrap living entirely inside Pelotero.DB.LeagueConfig.",
            "Wire format is byte-equivalent to the pre-A.4 instances (same field names, same key order, same Map-keyed encoding for limits), so existing JSONB rows round-trip without a data migration."
          ],
          "affects": []
        },
        {
          "name": "InternalSubrecordWrappers",
          "what": "JsonbBattingMultipliers and JsonbPitchingMultipliers are private to this module and used only inside JsonbScoring's ToJSON / FromJSON",
          "why": [
            "Each sub-record gets its own field-by-field encoding, mirroring the original split per type at the Domain layer.",
            "Keeps the LeagueScoring wrapper instance short and locally readable: the inner records' encoding lives next to the inner records' wrappers.",
            "Not exported because nothing outside JsonB needs to talk about the multipliers in JSONB form independently."
          ],
          "affects": []
        },
        {
          "name": "WrapperContentRationale",
          "what": "JsonbScoring, JsonbRosterLimits, and JsonbLineupLimits are public newtypes around LeagueScoring, RosterLimits, and LineupLimits respectively; their DBType instances are derived via JSONBEncoded and the on-the-wire JSON is byte-equivalent to the pre-A.4 instances",
          "why": [
            "These three wrappers exist for one job: carry the Aeson instances at the DB boundary without leaking Aeson into Domain.",
            "On-the-wire JSON parity with pre-A.4 is load-bearing; any existing league_config row in the database is read back through these wrappers without a migration.",
            "Captured as a decision rather than per-newtype invariants because chase resolves top-level value bindings, not newtype constructors; the documentation belongs at module level."
          ],
          "affects": []
        }
      ]
    },
    "Pelotero.DB.Rel8Instances": {
      "decisions": [
        {
          "name": "OrphanInstancesAreDeliberate",
          "what": "DBType / DBEq / DBOrd instances for domain id types live here as orphans; the {-# OPTIONS_GHC -Wno-orphans #-} pragma is intentional",
          "why": [
            "Putting them in Pelotero.Domain.Id forces the domain layer to depend on rel8, which is the wrong direction.",
            "Putting them in each Pelotero.DB.* table module produces orphan-conflict warnings as soon as two table modules reference the same domain type.",
            "This module is the lowest place that already imports both the domain types and rel8.",
            "Importers use the empty-import idiom: 'import Pelotero.DB.Rel8Instances ()'."
          ],
          "affects": []
        },
        {
          "name": "JsonbInstancesLiveOnWrappers",
          "what": "ToJSON / FromJSON for LeagueScoring, RosterLimits, LineupLimits live on newtype wrappers in Pelotero.DB.JsonB; this module no longer carries any DBType deriving for those Domain types",
          "why": [
            "Phase A.4 moved Domain off Aeson. The Domain types no longer have ToJSON / FromJSON instances; the DBType-via-JSONBEncoded deriving therefore moved next to the wrappers in Pelotero.DB.JsonB, where it's non-orphan.",
            "This module remains the home for orphan rel8 instances on Domain id newtypes; the JsonB wrappers' DBType instances are non-orphans because the wrappers are defined alongside them."
          ],
          "affects": []
        },
        {
          "name": "ProviderNameTextEnumDb",
          "what": "ProviderName decodes via parseTypeInformation, with parseProviderName as the decoder; on unknown values it returns Left, which becomes a hasql query failure",
          "why": [
            "Unlike Pelotero.DB.FetchLog.fromResult (which decodes to Maybe and filters), this DBType instance is strict.",
            "Tables that use ProviderName directly must only contain known providers, OR the table must decode to Text and convert in code.",
            "This asymmetry is per-table by design: external-id tables are write-controlled; the fetch log is append-only and historical."
          ],
          "affects": []
        }
      ]
    },

    "Pelotero.DB.Player": {
      "decisions": [
        {
          "name": "TwoTablePlayerExternalIdSplit",
          "what": "player table holds the canonical row; player_external_id holds (player_id, provider, external_id) tuples",
          "why": [
            "A player can have ids from multiple providers without schema gymnastics on the player table.",
            "If a player gets re-identified, the player row stays put; only the external_id rows update.",
            "Cost: every upsert is two operations. Phase A.5 collapsed the link / lookup / getExternalId / upsert boilerplate into Pelotero.DB.ProviderKeyed; this module retains the per-table schema, row, and entity-specific reads, plus a one-line ProviderKeyed instance and four facades around the polymorphic helpers."
          ],
          "affects": []
        },
        {
          "name": "BatHandStoredAsText",
          "what": "DB column for bat_side / pitch_hand is Text; the API exposes Char",
          "why": [
            "PostgreSQL doesn't have a native single-character type smaller than TEXT (CHAR(1) exists but has fixed-length-padding gotchas).",
            "Char in Haskell is multi-byte (Unicode) so storing as Text is structurally correct.",
            "API uses Char because the only legal values are 'L', 'R', 'S' and a Char is the most precise way to encode 'exactly one character of these three'.",
            "Conversion API is now total at the Domain layer (handChar) post Phase A.6; this module only does the Text<->Char shuffle which remains structurally honest."
          ],
          "affects": ["charToText", "textToChar", "fromResult", "insertPlayerT", "updatePlayerT"]
        }
      ],
      "invariants": {
        "playerSchema": [
          "table 'player' with surrogate id, denormalised name, position, batting/pitching hand as text, active flag, FK to team, last-synced metadata",
          "playerCurrentTeamId is Maybe DbTeamId; a player without a team has NULL"
        ],
        "playerExternalIdSchema": [
          "table 'player_external_id' with (player_id, provider, external_id, fetched_at)"
        ],
        "charToText": ["Maybe Char -> Maybe Text via T.singleton; preserves None"],
        "textToChar": [
          "Maybe Text -> Maybe Char via T.uncons",
          "if the stored text has more than one character (data corruption), silently truncates"
        ],
        "fromResult": [
          "private; converts the rel8 Player Result row to the public PlayerRow"
        ],
        "insertPlayerT": [
          "INSERT ... RETURNING id; uses Abort on conflict",
          "the surrogate id is unsafeDefault (DB-assigned BIGSERIAL); all other fields come from the row"
        ],
        "updatePlayerT": [
          "WHERE id = pid; updates everything except id",
          "no-op if pid doesn't exist"
        ],
        "getByIdT": ["single-row select via WHERE; returns the first match or Nothing"],
        "getAllT": ["ORDER BY last_name, first_name; returns the entire table"],
        "getActiveT": ["ORDER BY last_name, first_name; WHERE active = TRUE"],
        "linkExternalIdT": [
          "INSERT ... ON CONFLICT DO NOTHING into player_external_id",
          "idempotent; safe to call repeatedly during re-syncs"
        ],
        "lookupByExternalIdT": [
          "SELECT player_id WHERE provider AND external_id; returns Maybe DbPlayerId"
        ],
        "getExternalIdT": [
          "reverse lookup: given a DbPlayerId and provider, returns Maybe Text"
        ],
        "upsertByExternalIdT": [
          "two-step: lookup via (provider, external_id); if found, update player; if not, insert and link",
          "atomic within the caller's transaction"
        ],
        "insertPlayer": ["Pool-flavored wrapper around insertPlayerT"],
        "updatePlayer": ["Pool-flavored wrapper around updatePlayerT"],
        "getById": ["Pool-flavored single-player read"],
        "getAll": ["Pool-flavored full table read"],
        "getActive": ["Pool-flavored active-only read"],
        "linkExternalId": ["Pool-flavored wrapper"],
        "lookupByExternalId": ["Pool-flavored wrapper"],
        "getExternalId": ["Pool-flavored wrapper"],
        "upsertByExternalId": ["Pool-flavored wrapper"]
      }
    },

    "Pelotero.DB.Team": {
      "decisions": [
        {
          "name": "MirrorsPlayerSchema",
          "what": "team and team_external_id mirror the shape of player and player_external_id",
          "why": [
            "Same provider-keyed pattern as Player. Phase A.5 collapsed the four external-id helpers (link / lookup / getExternalId / upsert, plus their Pool wrappers) into Pelotero.DB.ProviderKeyed; this module retains the per-table schema, row, and reads, plus a one-line ProviderKeyed instance and facades."
          ],
          "affects": []
        }
      ],
      "invariants": {
        "teamSchema": [
          "table 'team' with surrogate id, name, abbreviation, location_name (city), and last-synced metadata",
          "no FK out — teams are leaves in the FK graph"
        ],
        "teamExternalIdSchema": [
          "same shape as player_external_id: (team_id, provider, external_id, fetched_at)"
        ],
        "fromResult": ["private; rel8 Result -> public TeamRow"],
        "insertTeamT": ["INSERT ... RETURNING id; Abort on conflict"],
        "updateTeamT": ["WHERE id = tid; updates everything except id"],
        "getByIdT": ["single-row select via WHERE id"],
        "getAllT": ["ORDER BY name; no pagination; 30 MLB teams"],
        "linkExternalIdT": ["INSERT ... ON CONFLICT DO NOTHING into team_external_id"],
        "lookupByExternalIdT": ["SELECT team_id WHERE provider AND external_id"],
        "getExternalIdT": ["reverse lookup; (DbTeamId, ProviderName) -> Maybe Text"],
        "upsertByExternalIdT": ["lookup-then-update or insert-and-link"],
        "insertTeam": ["Pool-flavored wrapper"],
        "updateTeam": ["Pool-flavored wrapper"],
        "getById": ["Pool-flavored single-team read"],
        "getAll": ["Pool-flavored full table read"],
        "linkExternalId": ["Pool-flavored wrapper"],
        "lookupByExternalId": ["Pool-flavored wrapper"],
        "getExternalId": ["Pool-flavored wrapper"],
        "upsertByExternalId": ["Pool-flavored wrapper"]
      }
    },

    "Pelotero.DB.Game": {
      "decisions": [
        {
          "name": "GameDateAsDay",
          "what": "game.game_date stores Day (no time of day), not UTCTime",
          "why": [
            "Fantasy scoring periods are defined by date in the league's local timezone; game start times within a day are irrelevant for whether the game counts.",
            "Storing as TIMESTAMPTZ would force every query to deal with timezone offset for what is fundamentally a calendar question."
          ],
          "affects": ["gameSchema", "getByDateT"]
        },
        {
          "name": "MirrorsTeamSchema",
          "what": "game and game_external_id mirror the shape of team and team_external_id",
          "why": [
            "Same provider-keyed pattern as Player and Team. Phase A.5 collapsed the external-id boilerplate into Pelotero.DB.ProviderKeyed; this module is now a per-table schema + row + entity-specific reads (getByDateT, getByDateRangeT) plus a one-line ProviderKeyed instance and four facades."
          ],
          "affects": []
        }
      ],
      "invariants": {
        "gameSchema": [
          "table 'game' with surrogate id, game_date (Day), away/home team FKs to team.id, last-synced metadata"
        ],
        "gameExternalIdSchema": [
          "same shape as player_external_id and team_external_id"
        ],
        "getByDateRangeT": [
          "WHERE game_date BETWEEN startDay AND endDay (inclusive both ends)",
          "ORDER BY game_date ASC, id ASC for stable cross-day display",
          "consumed by Pelotero.Effects.Games.getGamesByDateRange and indirectly by Pelotero.Score.buildPlayerMaps via the date-range box queries"
        ],
        "getByDateRange": ["Pool-flavored wrapper; inclusive on both ends"],
        "fromResult": ["private; rel8 Result -> public GameRow"],
        "insertGameT": ["INSERT ... RETURNING id; Abort on conflict"],
        "updateGameT": ["WHERE id = gid; updates everything except id"],
        "getByIdT": ["single-row select via WHERE id"],
        "getByDateT": [
          "WHERE game_date = ? ORDER BY id"
        ],
        "linkExternalIdT": ["INSERT ... ON CONFLICT DO NOTHING into game_external_id"],
        "lookupByExternalIdT": ["SELECT game_id WHERE provider AND external_id"],
        "getExternalIdT": ["reverse lookup"],
        "upsertByExternalIdT": ["lookup-then-update or insert-and-link"],
        "insertGame": ["Pool-flavored wrapper"],
        "updateGame": ["Pool-flavored wrapper"],
        "getById": ["Pool-flavored single-game read"],
        "getByDate": ["Pool-flavored per-date read"],
        "linkExternalId": ["Pool-flavored wrapper"],
        "lookupByExternalId": ["Pool-flavored wrapper"],
        "getExternalId": ["Pool-flavored wrapper"],
        "upsertByExternalId": ["Pool-flavored wrapper"]
      }
    },

    "Pelotero.DB.FetchLog": {
      "decisions": [
        {
          "name": "ProviderColumnIsTextNotEnum",
          "what": "_flProvider is Column f Text, NOT Column f ProviderName",
          "why": [
            "The fetch log is append-only and historical; a row written by a provider that no longer exists must remain readable.",
            "If we used the ProviderName DBType (which fails on unknown values), a single legacy row would crash every fetch-log query.",
            "fromResult does the parse and returns Nothing for unparseable rows; getLastFetchT and getRecentFetchesT use mapMaybe to drop them silently."
          ],
          "affects": ["fetchLogSchema", "fromResult", "getLastFetchT", "getRecentFetchesT"]
        },
        {
          "name": "RecordCountAsInt32",
          "what": "fetchLogRecordCount is Int32, not Int64 or Int",
          "why": [
            "INTEGER (not BIGINT) in PostgreSQL; 2^31 ~= 2 billion records per fetch is plenty.",
            "Using Int (machine-word) would silently widen on 64-bit platforms, then narrow at the wire boundary."
          ],
          "affects": ["fetchLogSchema", "recordFetchT"]
        }
      ],
      "invariants": {
        "fetchLogSchema": [
          "table 'provider_fetch_log' with id (BIGSERIAL), provider (TEXT), resource, scope, fetched_at, payload_sha256, record_count (INTEGER)"
        ],
        "fromResult": [
          "private; rel8 Result -> Maybe FetchLogRow",
          "Returns Nothing if _flProvider doesn't parse as a known ProviderName"
        ],
        "recordFetchT": [
          "INSERT ... ON CONFLICT Abort; the fetch log is append-only"
        ],
        "getLastFetchT": [
          "ORDER BY fetched_at DESC, id DESC LIMIT 1; the id-DESC tiebreaker handles same-millisecond fetches"
        ],
        "getRecentFetchesT": [
          "same ORDER BY pattern, LIMIT lim; returns up to `lim` parseable rows"
        ],
        "recordFetch": ["Pool-flavored wrapper"],
        "getLastFetch": ["Pool-flavored last-fetch lookup"],
        "getRecentFetches": ["Pool-flavored recent-fetches lookup"]
      }
    },

    "Pelotero.DB.LeagueConfig": {
      "decisions": [
        {
          "name": "ScoringAndLimitsAsJsonbColumns",
          "what": "scoring_config (JSONB), roster_limits (JSONB), and lineup_limits (JSONB) are columns whose rel8 type is the Pelotero.DB.JsonB wrapper (JsonbScoring / JsonbRosterLimits / JsonbLineupLimits); the public LeagueConfigRow still carries the unwrapped Domain types",
          "why": [
            "JSONB lets us evolve the inner record shape without a schema migration on every existing row.",
            "Phase A.4 moved the Aeson instances off Domain onto the wrappers; this module wraps in insertLeagueConfigT / updateLeagueConfigT and unwraps in fromResult, keeping the public API in Domain types and Domain itself Aeson-free."
          ],
          "affects": ["leagueConfigSchema", "fromResult", "insertLeagueConfigT", "updateLeagueConfigT"]
        },
        {
          "name": "StatusAsTextNotEnum",
          "what": "_lcStatus is Column f Text, not the LeagueStatus domain sum",
          "why": [
            "Same rationale as ProviderName for the fetch log: tolerate legacy or unrecognised values without crashing reads.",
            "The layered domain type LeagueStatus exists as the canonical render/parse pair; this column being Text is the persistence-layer trade-off."
          ],
          "affects": ["leagueConfigSchema"]
        }
      ],
      "invariants": {
        "leagueConfigSchema": [
          "table 'league_config' with surrogate id, league_id (Text), commissioner, status, JSONB scoring/roster/lineup, draft params, scoring period bounds"
        ],
        "fromResult": [
          "private; rel8 Result -> public LeagueConfigRow"
        ],
        "insertLeagueConfigT": [
          "INSERT ... RETURNING id; Abort on conflict"
        ],
        "updateLeagueConfigT": [
          "WHERE id = lcid; updates everything except id"
        ],
        "getByIdT": ["single-row select via WHERE id"],
        "getByLeagueIdT": ["WHERE league_id = ?; the user-facing identifier"],
        "getAllT": ["ORDER BY league_id; full table"],
        "insertLeagueConfig": ["Pool-flavored wrapper"],
        "updateLeagueConfig": ["Pool-flavored wrapper"],
        "getById": ["Pool-flavored single-row read"],
        "getByLeagueId": ["Pool-flavored user-id read"],
        "getAll": ["Pool-flavored full read"]
      }
    },

    "Pelotero.DB.LeagueTeam": {
      "decisions": [
        {
          "name": "TeamKeySeparateFromName",
          "what": "league_team has both team_key (stable identifier within a league) and name (mutable display name)",
          "why": [
            "Owners change team names mid-season; references from elsewhere (rosters, lineups, picks) must remain stable.",
            "team_key is the join key; name is the rendered string.",
            "(league_config_id, team_key) is the natural compound key."
          ],
          "affects": ["leagueTeamSchema", "lookupByKeyT"]
        }
      ],
      "invariants": {
        "leagueTeamSchema": [
          "table 'league_team' with surrogate id, FK to league_config, team_key (stable), name, owner",
          "no last-synced metadata — league teams are user-managed, not externally synced"
        ],
        "fromResult": ["private; rel8 Result -> LeagueTeamRow"],
        "insertLeagueTeamT": ["INSERT ... RETURNING id; Abort on conflict"],
        "updateLeagueTeamT": ["WHERE id = ltid; updates everything except id"],
        "getByIdT": ["single-row select via WHERE id"],
        "lookupByKeyT": ["WHERE league_config_id AND team_key; returns the first match or Nothing"],
        "getForLeagueT": ["ORDER BY name; all teams in a league"],
        "deleteT": ["DELETE WHERE id; cascading deletes on dependent rows handled by FK ON DELETE"],
        "insertLeagueTeam": ["Pool-flavored wrapper"],
        "updateLeagueTeam": ["Pool-flavored wrapper"],
        "getById": ["Pool-flavored single-row read"],
        "lookupByKey": ["Pool-flavored compound-key lookup"],
        "getForLeague": ["Pool-flavored per-league listing"],
        "delete": ["Pool-flavored row deletion"]
      }
    },

    "Pelotero.DB.RosterSlot": {
      "decisions": [
        {
          "name": "UpsertOnPlayerNotSlot",
          "what": "addSlotT does ON CONFLICT (league_team_id, player_id) DO UPDATE SET slot, NOT (league_team_id, slot)",
          "why": [
            "The natural-feeling 'a slot can hold one player' is wrong for fantasy; multiple OF/UTIL slots per team is normal.",
            "The actual invariant is 'a player is in at most one slot per team'.",
            "Adding a player who's already on the roster moves them to the new slot rather than failing or duplicating."
          ],
          "affects": ["addSlotT"]
        }
      ],
      "invariants": {
        "rosterSlotSchema": [
          "table 'roster_slot' with surrogate id, FK to league_team, slot (Text), FK to player, created_at",
          "natural unique key: (league_team_id, player_id)",
          "no order_index column today; planned B.2 work adds it for batting-order positional persistence"
        ],
        "fromResult": [
          "private; drops the hidden surrogate id and created_at"
        ],
        "addSlotT": [
          "INSERT ... ON CONFLICT (league_team_id, player_id) DO UPDATE SET slot"
        ],
        "getSlotsForTeamT": [
          "WHERE league_team_id; ORDER BY slot, player_id"
        ],
        "removeSlotT": ["DELETE WHERE league_team_id AND player_id"],
        "removePlayerFromTeamT": ["alias for removeSlotT"],
        "clearTeamRosterT": ["DELETE WHERE league_team_id"],
        "replaceTeamRosterT": [
          "transaction-internal sequence: clearTeamRosterT then mapM_ addSlotT",
          "entirely within the caller's transaction"
        ],
        "countBySlotT": ["COUNT(*) WHERE league_team_id AND slot"],
        "getSlotsForTeam": ["Pool-flavored wrapper"],
        "addSlot": ["Pool-flavored upsert"],
        "removeSlot": ["Pool-flavored single removal"],
        "removePlayerFromTeam": ["Pool-flavored alias for removeSlot"],
        "clearTeamRoster": ["Pool-flavored full clear"],
        "replaceTeamRoster": ["Pool-flavored clear-then-fill"],
        "countBySlot": ["Pool-flavored count"]
      }
    },

    "Pelotero.DB.LineupSlot": {
      "decisions": [
        {
          "name": "MirrorsRosterSlotShape",
          "what": "lineup_slot is structurally identical to roster_slot",
          "why": [
            "Lineups and rosters are different concepts but the storage shape stays parallel.",
            "Same caveat as roster_slot: no order_index today; planned B.2 work adds it on both tables in one migration."
          ],
          "affects": ["lineupSlotSchema", "addSlotT"]
        }
      ],
      "invariants": {
        "lineupSlotSchema": [
          "table 'lineup_slot' with surrogate id, FK to league_team, slot (Text), FK to player, created_at",
          "structurally identical to roster_slot",
          "no order_index column today; see B.2 in RosterSlot"
        ],
        "fromResult": ["private; same omission of id and created_at as RosterSlot.fromResult"],
        "addSlotT": [
          "same upsert pattern as RosterSlot.addSlotT"
        ],
        "getSlotsForTeamT": ["WHERE league_team_id; ORDER BY slot, player_id"],
        "removeSlotT": ["DELETE WHERE league_team_id AND player_id"],
        "clearTeamLineupT": ["DELETE WHERE league_team_id"],
        "replaceTeamLineupT": ["clear-then-fill within the caller's transaction"],
        "getSlotsForTeam": ["Pool-flavored wrapper"],
        "addSlot": ["Pool-flavored upsert"],
        "removeSlot": ["Pool-flavored removal"],
        "clearTeamLineup": ["Pool-flavored clear"],
        "replaceTeamLineup": ["Pool-flavored replace"]
      }
    },

    "Pelotero.DB.LineupSnapshot": {
      "decisions": [
        {
          "name": "SnapshotKeyedByLeagueTeamAndGame",
          "what": "lineup_snapshot has UNIQUE (league_team_id, game_id, slot, player_id); a snapshot is the team's lineup-as-of-this-specific-game",
          "why": [
            "Phase B.3 introduced the table to fix the correctness bug where scoring used current lineups against historical games.",
            "(league_team_id, game_id) is the lookup key for scoring; slot + player_id complete the row's identity.",
            "snapshotted_at TIMESTAMPTZ DEFAULT NOW() records when the snapshot was actually taken; useful for debugging late-snapshot or out-of-order-snapshot scenarios.",
            "No order_index column today; if/when B.2 adds it to lineup_slot, the snapshot will need it too so that snapshots preserve the lineup ordering at snapshot time."
          ],
          "affects": ["lineupSnapshotSchema", "writeSnapshotsT"]
        },
        {
          "name": "ImmutableSnapshotsViaOnConflictDoNothing",
          "what": "writeSnapshotsT uses ON CONFLICT (league_team_id, game_id, slot, player_id) DO NOTHING; once a snapshot row exists, it is never overwritten",
          "why": [
            "Snapshots model 'the lineup at game start' and must be immutable after that.",
            "Combined with Lineup.Snapshot's pre-check via snapshotExistsForTeamGameT, this gives 'first snapshot wins' semantics for the (team, game) pair as a whole.",
            "Re-running snapshot jobs is therefore a safe operational primitive."
          ],
          "affects": ["writeSnapshotsT"]
        }
      ],
      "invariants": {
        "lineupSnapshotSchema": [
          "table 'lineup_snapshot' with id (BIGSERIAL), league_team_id (FK), game_id (FK), slot (Text), player_id (FK), snapshotted_at (TIMESTAMPTZ DEFAULT NOW())",
          "UNIQUE (league_team_id, game_id, slot, player_id)",
          "index lineup_snapshot_game on (game_id)",
          "index lineup_snapshot_team_game on (league_team_id, game_id)",
          "introduced by V0030__lineup_snapshot.sql (Phase B.3)"
        ],
        "fromResult": [
          "private; rel8 Result -> LineupSnapshotRow",
          "drops surrogate id and snapshotted_at from the public row type"
        ],
        "writeSnapshotsT": [
          "INSERT [LineupSnapshotRow] ... ON CONFLICT DO NOTHING; returns ()",
          "empty input returns immediately without hitting the database",
          "callers track the count of attempted rows via 'length' on the input; the function does not return a count today"
        ],
        "getSnapshotForTeamGameT": [
          "WHERE league_team_id AND game_id; no SQL-level ordering",
          "consumed by Pelotero.Lineup.Snapshot.snapshotLineupsForTeam for the 'is this snapshot already locked in?' guard; Pelotero.Score reads via the date-range variant (getSnapshotsForDateRangeT) and groups in-memory"
        ],
        "snapshotExistsForTeamGameT": [
          "SELECT ... LIMIT 1; returns True iff at least one row exists for the (team, game) pair",
          "used by Pelotero.Lineup.Snapshot.snapshotLineupsForTeam as the 'is this snapshot already locked in?' guard"
        ],
        "getSnapshotsForGameT": [
          "WHERE game_id; returns every snapshot row across all teams for one game",
          "useful for debugging or auditing; not on the scoring hot path"
        ],
        "writeSnapshots": ["Pool-flavored wrapper"],
        "getSnapshotForTeamGame": ["Pool-flavored wrapper"],
        "snapshotExistsForTeamGame": ["Pool-flavored wrapper"],
        "getSnapshotsForGame": ["Pool-flavored wrapper"]
      }
    },

    "Pelotero.DB.PlayerRanking": {
      "decisions": [
        {
          "name": "NoSurrogateIdNaturalKey",
          "what": "player_ranking has no surrogate id; (league_team_id, player_id) is the primary key",
          "why": [
            "Unlike roster_slot/lineup_slot where the (team, player) pair has a 'context' (the slot string), a ranking pair carries only its rank_slot integer.",
            "Fewer columns, simpler schema."
          ],
          "affects": ["playerRankingSchema", "insertOneT"]
        },
        {
          "name": "AbortOnConflictForRankings",
          "what": "insertOneT uses Abort, not Upsert; replaceRankingsT works by clear-then-fill",
          "why": [
            "Rankings are typically replaced wholesale rather than tweaked incrementally.",
            "Abort + clear-then-fill is conceptually simpler than upsert."
          ],
          "affects": ["insertOneT", "replaceRankingsT"]
        }
      ],
      "invariants": {
        "playerRankingSchema": [
          "table 'player_ranking' with FK to league_team, FK to player, rank_slot (Int32), updated_at",
          "PK is (league_team_id, player_id) — no surrogate id"
        ],
        "fromResult": ["private; rel8 Result -> PlayerRankingRow; drops updated_at"],
        "insertOneT": [
          "private; INSERT ... ON CONFLICT Abort"
        ],
        "getRankingsForTeamT": [
          "WHERE league_team_id; ORDER BY rank_slot",
          "intended consumer is the planned Pelotero.Draft state machine (D.1); no consumer in tree today"
        ],
        "clearRankingsT": ["DELETE WHERE league_team_id"],
        "replaceRankingsT": [
          "clearRankingsT then mapM_ insertOneT",
          "atomic within the caller's transaction"
        ],
        "getRankingCountT": ["COUNT(*) WHERE league_team_id"],
        "getRankingsForTeam": ["Pool-flavored wrapper"],
        "replaceRankings": ["Pool-flavored replace"],
        "clearRankings": ["Pool-flavored clear"],
        "getRankingCount": ["Pool-flavored count"]
      }
    },

    "Pelotero.DB.DraftPick": {
      "decisions": [
        {
          "name": "AppendOnlyDraftPicks",
          "what": "Only insert (recordPick) and read (getPicksForLeague, getPickCount) operations exist; no update or delete",
          "why": [
            "Picks are historical events; once made, they don't get edited or undone.",
            "If a wrong pick needs correction, the convention is to insert a new pick at the next pick_number rather than mutating the prior row.",
            "Audit trail integrity: a query at any point in time gives the actual sequence of picks made."
          ],
          "affects": ["recordPickT"]
        }
      ],
      "invariants": {
        "draftPickSchema": [
          "table 'draft_pick' with surrogate id, FK to league_config, pick_number (Int32 — 1-indexed), FK to league_team, FK to player, picked_at"
        ],
        "fromResult": [
          "private; rel8 Result -> DraftPickRow"
        ],
        "recordPickT": [
          "INSERT ... RETURNING id; Abort on conflict",
          "intended consumer is the planned Pelotero.Draft state machine (D.1); no consumer in tree today"
        ],
        "getPicksForLeagueT": [
          "WHERE league_config_id; ORDER BY pick_number"
        ],
        "getPickCountT": [
          "COUNT(*) WHERE league_config_id",
          "used to figure out 'whose pick is next?' as count + 1"
        ],
        "recordPick": ["Pool-flavored insert"],
        "getPicksForLeague": ["Pool-flavored full-league pick listing"],
        "getPickCount": ["Pool-flavored count"]
      }
    },

    "Pelotero.DB.BoxscoreEntry": {
      "decisions": [
        {
          "name": "TwoTablesNotOne",
          "what": "Batting and pitching are separate tables (game_player_batting and game_player_pitching), not one wide table",
          "why": [
            "Batting has ~25 stat columns, pitching has ~40. Combining gives a 65-column row that's mostly NULL for any given player.",
            "Querying 'all batting lines this week' becomes a clean SELECT from one table without WHERE filtering on column NULLness.",
            "A two-way player gets two rows, one per table — correct because both stat lines are independently meaningful."
          ],
          "affects": ["battingSchema", "pitchingSchema"]
        },
        {
          "name": "InningsPitchedAsOuts",
          "what": "The pitching table stores INTEGER outs, NOT the wire string '6.2'",
          "why": [
            "Storing as outs makes SUM, AVG, and arithmetic exact; a decimal column would lose precision.",
            "Conversion happens at convert time in Pelotero.MLB.Convert.convertPitching (Phase B.1); readers always see exact integer outs.",
            "Domain.Stats.PitchingStats now also has only pitOuts (Phase B.1 dropped pitInningsPitched), so the DB row, the domain row, and the scoring path all agree."
          ],
          "affects": ["pitchingSchema", "upsertPitchingT"]
        },
        {
          "name": "UpdatedAtFromSqlNow",
          "what": "Upsert sets updated_at = RT.now (a SQL-side NOW()), preserving created_at from the existing row",
          "why": [
            "RT.now is rel8's Expr-level NOW() — runs at DB transaction time, not at Haskell wall-clock time.",
            "Taking the timestamp client-side would risk skew between client and DB clocks."
          ],
          "affects": ["upsertBattingT", "upsertPitchingT"]
        }
      ],
      "invariants": {
        "battingSchema": [
          "table 'game_player_batting' with FK to game, FK to player, FK to team (nullable), 25 stat columns (all Maybe Int32), created_at, updated_at",
          "natural PK: (game_id, player_id)"
        ],
        "pitchingSchema": [
          "table 'game_player_pitching' with FK to game, FK to player, FK to team (nullable), 40+ stat columns, innings_pitched_outs as Int32, created_at, updated_at",
          "natural PK: (game_id, player_id)"
        ],
        "fromBattingResult": [
          "private; rel8 BattingE Result -> BattingRow; drops created_at and updated_at"
        ],
        "fromPitchingResult": [
          "private; rel8 PitchingE Result -> PitchingRow; drops created_at and updated_at"
        ],
        "battingRowToExpr": [
          "private; BattingRow -> BattingE Expr for use in INSERT VALUES clause",
          "created_at and updated_at are unsafeDefault — DB sets them on insert"
        ],
        "pitchingRowToExpr": [
          "private; mirror of battingRowToExpr"
        ],
        "upsertBattingT": [
          "INSERT ... ON CONFLICT (game_id, player_id) DO UPDATE",
          "set: keeps id-like columns from old, takes stats from new, preserves created_at, sets updated_at = NOW()",
          "updateWhere = lit True (always update on conflict)"
        ],
        "getBattingForGameT": [
          "WHERE game_id; ORDER BY player_id",
          "consumed by Pelotero.Score.buildPlayerMaps (one call per game id in the period)"
        ],
        "deleteBattingForGameT": [
          "DELETE WHERE game_id",
          "useful when re-ingesting a corrected boxscore"
        ],
        "upsertPitchingT": ["mirror of upsertBattingT for pitching"],
        "getPitchingForGameT": [
          "WHERE game_id; ORDER BY player_id",
          "consumed by Pelotero.Score.buildPlayerMaps"
        ],
        "deletePitchingForGameT": ["DELETE WHERE game_id"],
        "upsertBatting": ["Pool-flavored wrapper"],
        "upsertPitching": ["Pool-flavored wrapper"],
        "getBattingForGame": ["Pool-flavored read"],
        "getPitchingForGame": ["Pool-flavored read"],
        "deleteBattingForGame": ["Pool-flavored delete"],
        "deletePitchingForGame": ["Pool-flavored delete"]
      }
    },

    "Pelotero.Effects.Database": {
      "decisions": [
        {
          "name": "OneOperationOneTransaction",
          "what": "Database has a single operation, runTx, which acquires a connection and runs the transaction in isolation",
          "why": [
            "Each runTx is its own atomic unit; no need for callers to manage connection scope.",
            "Composing multiple runTx calls is NOT one transaction — they're independent. If you need a multi-step atomic operation, build a single Transaction and pass it to one runTx.",
            "This matches Pool.runTransaction's contract; the Database effect is a thin wrapper to make it dispatchable through the effectful machinery."
          ],
          "affects": ["runTx", "runDatabasePool"]
        },
        {
          "name": "DbErrorAsTypedCoEffect",
          "what": "runDatabasePool requires Logging and Error DBError co-effects; DBErrors flow through the effect system as typed errors and are also logged at ErrorS before throwing",
          "why": [
            "Phase A.3 replaced the runOrThrow pattern. Callers that don't care about typed handling do `runErrorNoCallStack @DBError` at the top of the program and either crash or log on Left; callers that want to handle pool exhaustion specifically can pattern-match on PoolUsageError.",
            "Removes the lossy `show` step that used to live in runOrThrow; structured error data now propagates intact.",
            "Logging the error before throwing means a silently-discarded Left still leaves a trace.",
            "Every effect runner consuming Database (Players, Teams, Games, BoxscoreEntry, FetchLog, LeagueConfig, LeagueTeam, RosterSlot, LineupSlot, LineupSnapshot, PlayerRanking, DraftPick) threads `Error DBError` through.",
            "Type signature: runDatabasePool :: (IOE :> es, Logging :> es, Error DBError :> es) => Pool -> Eff (Database : es) a -> Eff es a"
          ],
          "affects": ["runDatabasePool"]
        }
      ],
      "invariants": {
        "runTx": [
          "the only public operation; takes a Tx.Transaction a and returns Eff es a",
          "each call is one independent transaction; no nesting, no batching",
          "writes commit on success; on Tx error, throwError @DBError is invoked rather than throwing IO"
        ],
        "runDatabasePool": {
          "intent": "Production interpreter: runs each runTx via Pool.runTransaction; on Left DBError, logs at ErrorS then calls throwError into the Error DBError co-effect",
          "effects": ["IOE", "Logging", "Error DBError"],
          "notes": [
            "no longer throws userError; DBError flows through the effect system",
            "callers compose with `runErrorNoCallStack @DBError` at whatever boundary they want to handle errors",
            "the rationale shift from throw-IO to typed-Error is captured in DbErrorAsTypedCoEffect"
          ]
        }
      }
    },

    "Pelotero.Effects.Clock": {
      "decisions": [
        {
          "name": "FixedTimeForTests",
          "what": "runClockFixed is the test interpreter; every now call returns the same fixed UTCTime",
          "why": [
            "Sync code uses Clock.now to stamp synced_at on rows; tests need the same value to compare against.",
            "An incrementing-on-each-call interpreter would test more edge cases but adds complexity."
          ],
          "affects": ["runClockFixed"]
        }
      ],
      "invariants": {
        "now": ["the only operation; returns the current time per the active interpreter"],
        "runClockIO": ["IO interpreter; calls Data.Time.getCurrentTime per call"],
        "runClockFixed": [
          "fixed-time interpreter; every call returns the same UTCTime",
          "useful for deterministic tests"
        ]
      }
    },

    "Pelotero.Effects.MLBClient": {
      "decisions": [
        {
          "name": "TwoInterpretersHttpAndFixture",
          "what": "MLBClient has runMLBClientHTTP (production) and runMLBClientFixture (offline tests reading JSON files from disk)",
          "why": [
            "The fixture interpreter exercises the same wire-to-domain conversion path (Pelotero.MLB.Convert) as production, just with file reads instead of HTTP.",
            "Fixture tests don't depend on network, MLB API uptime, or rate limits.",
            "The fixture path manually computes the SHA over teams+players bytes (same order as fetchRosters), so test-mode SHAs match production semantics."
          ],
          "affects": ["runMLBClientHTTP", "runMLBClientFixture"]
        },
        {
          "name": "FixtureBoxscoresOverride",
          "what": "MLBFixture has fixtureBoxscores :: Map Int FilePath for per-game path overrides",
          "why": [
            "Most tests use the conventional path; the override exists for tests that need to point a specific gamePk at a corrupted/edge-case fixture file.",
            "Avoids forcing every test to lay out its own complete fixture directory."
          ],
          "affects": ["runMLBClientFixture", "defaultFixture"]
        },
        {
          "name": "WireToDomainTeamCopiedFromFetch",
          "what": "runMLBClientFixture inlines its own copy of wireToDomainTeam rather than importing from Pelotero.MLB.Fetch",
          "why": [
            "wireToDomainTeam is private to Fetch; exporting it for one test caller felt heavier than four lines of duplication.",
            "If a third caller appears, this should move to a shared Convert helper."
          ],
          "affects": ["runMLBClientFixture"]
        }
      ],
      "invariants": {
        "fetchRosters": ["MLBClient send-only API for rosters"],
        "fetchSchedule": ["MLBClient send-only API for schedule"],
        "fetchBoxscoreRaw": ["MLBClient send-only API for boxscore raw bytes"],
        "runMLBClientHTTP": {
          "intent": "Production interpreter; delegates each operation to Pelotero.MLB.Fetch via liftIO",
          "effects": ["IOE"],
          "notes": ["no caching, no retries, no rate limiting at this layer"]
        },
        "defaultFixture": [
          "constructs an MLBFixture with empty fixtureBoxscores"
        ],
        "runMLBClientFixture": {
          "intent": "Test interpreter; reads fixture files from disk and runs them through the same Convert pipeline as production",
          "effects": ["IOE"]
        }
      }
    },

    "Pelotero.Effects.FetchLog": {
      "decisions": [
        {
          "name": "InMemoryFetchLogIsList",
          "what": "runFetchLogInMemory uses an IORef [FetchLogRow] (cons-prepended), not a Map",
          "why": [
            "Tests typically write a few rows and read the most recent; a list is fine.",
            "Cons-prepending makes 'most recent first' free."
          ],
          "affects": ["runFetchLogInMemory"]
        }
      ],
      "invariants": {
        "recordFetch": ["FetchLog send-only; records a new fetch row"],
        "getLastFetch": [
          "FetchLog send-only; given (provider, resource, scope), returns the most recent fetch or Nothing"
        ],
        "runFetchLogDB": [
          "Database-backed interpreter; delegates to Pelotero.DB.FetchLog",
          "requires Error DBError in the effect stack (post Phase A.3)"
        ],
        "runFetchLogInMemory": [
          "IO-backed test interpreter using an IORef [FetchLogRow]"
        ]
      }
    },

    "Pelotero.Effects.Players": {
      "decisions": [
        {
          "name": "InMemoryAssignsAutoIncrementId",
          "what": "runPlayersInMemory's UpsertPlayerByExternalId uses an internal nextId counter (Int starting at 1)",
          "why": [
            "Mirrors the DB's BIGSERIAL behaviour without needing an actual sequence.",
            "Counter is per-IORef (per-runner-instance), so two concurrent test runs don't share ids."
          ],
          "affects": ["runPlayersInMemory", "emptyStore"]
        }
      ],
      "invariants": {
        "upsertPlayerByExternalId": ["Players send-only; same semantics as DB upsertByExternalId"],
        "lookupPlayerByExternalId": ["Players send-only; (provider, externalId) -> Maybe DbPlayerId"],
        "getPlayerById": ["Players send-only; DbPlayerId -> Maybe PlayerRow"],
        "getActivePlayers": ["Players send-only; all players where active=True"],
        "runPlayersDB": [
          "Database-backed interpreter; delegates to Pelotero.DB.Player",
          "requires Error DBError post Phase A.3"
        ],
        "emptyStore": ["private; PlayerStore Map.empty Map.empty 1"],
        "runPlayersInMemory": [
          "IORef-based test interpreter",
          "UpsertPlayerByExternalId: if (provider, externalId) found, update rowsByDb keeping the existing id; else assign nextId and insert into both maps",
          "GetActivePlayers iterates all rows and filters by playerRowActive"
        ]
      }
    },

    "Pelotero.Effects.Teams": {
      "decisions": [
        {
          "name": "MirrorsPlayersInMemoryShape",
          "what": "TeamStore has the same external-id-map + db-rows-map + nextId-counter shape as PlayerStore",
          "why": [
            "Same trade-offs as Players: per-runner counter mimicking BIGSERIAL, no FK enforcement.",
            "Code duplication is acceptable at two test interpreters."
          ],
          "affects": ["runTeamsInMemory", "emptyTeamStore"]
        }
      ],
      "invariants": {
        "upsertTeamByExternalId": ["Teams send-only"],
        "lookupTeamByExternalId": ["Teams send-only"],
        "getTeamById": ["Teams send-only"],
        "getAllTeams": ["Teams send-only"],
        "runTeamsDB": [
          "Database-backed interpreter; delegates to Pelotero.DB.Team",
          "requires Error DBError post Phase A.3"
        ],
        "emptyTeamStore": ["private; TeamStore Map.empty Map.empty 1"],
        "runTeamsInMemory": ["IORef-based test interpreter"]
      }
    },

    "Pelotero.Effects.Games": {
      "decisions": [
        {
          "name": "GameStoreHasReverseLookupMap",
          "what": "The in-memory game store maintains both an external-id->db-id map AND a db-id->external-id map",
          "why": [
            "GetGameExternalId requires reverse lookup; iterating the forward map with elem-on-value would be O(n) per call.",
            "Two maps cost twice the memory but make every lookup O(log n)."
          ],
          "affects": ["runGamesInMemory", "emptyGameStore"]
        }
      ],
      "invariants": {
        "upsertGameByExternalId": ["Games send-only"],
        "lookupGameByExternalId": ["Games send-only"],
        "getGameExternalId": ["Games send-only; reverse lookup"],
        "getGameById": ["Games send-only"],
        "getGamesByDate": ["Games send-only; per-date listing"],
        "getGamesByDateRange": [
          "Games send-only; range listing inclusive on both ends",
          "consumed by Pelotero.Lineup.Snapshot.snapshotLineupsForDate and Pelotero.Sync.Boxscores.syncBoxscoresForDateRange; Score uses the date-range box and snapshot queries directly rather than enumerating game ids"
        ],
        "runGamesDB": [
          "Database-backed interpreter; delegates to Pelotero.DB.Game",
          "requires Error DBError"
        ],
        "emptyGameStore": ["private; three empty Maps + nextId=1"],
        "runGamesInMemory": ["IORef-based test interpreter"]
      }
    },

    "Pelotero.Effects.LeagueConfig": {
      "invariants": {
        "insertLeagueConfig": ["LeagueConfig send-only"],
        "updateLeagueConfig": ["LeagueConfig send-only"],
        "getById": ["LeagueConfig send-only"],
        "getByLeagueId": ["LeagueConfig send-only"],
        "getAll": [
          "LeagueConfig send-only",
          "consumed by Pelotero.Lineup.Snapshot.snapshotLineupsForGame to enumerate active leagues"
        ],
        "runLeagueConfigDB": [
          "Database-backed interpreter; delegates to Pelotero.DB.LeagueConfig",
          "requires Error DBError post Phase A.3"
        ]
      }
    },

    "Pelotero.Effects.LeagueTeam": {
      "invariants": {
        "insertLeagueTeam": ["LeagueTeam send-only"],
        "updateLeagueTeam": ["LeagueTeam send-only"],
        "getById": ["LeagueTeam send-only"],
        "lookupByKey": ["LeagueTeam send-only; (league_config_id, team_key) lookup"],
        "getForLeague": ["LeagueTeam send-only; per-league listing"],
        "delete": ["LeagueTeam send-only"],
        "runLeagueTeamDB": ["Database-backed interpreter; requires Error DBError"]
      }
    },

    "Pelotero.Effects.RosterSlot": {
      "invariants": {
        "addSlot": ["RosterSlot send-only; semantically an upsert"],
        "removeSlot": ["RosterSlot send-only"],
        "clearTeamRoster": ["RosterSlot send-only"],
        "replaceTeamRoster": ["RosterSlot send-only"],
        "getSlotsForTeam": ["RosterSlot send-only"],
        "countBySlot": ["RosterSlot send-only"],
        "runRosterSlotDB": ["Database-backed interpreter; requires Error DBError"]
      }
    },

    "Pelotero.Effects.LineupSlot": {
      "invariants": {
        "addSlot": ["LineupSlot send-only; semantically an upsert"],
        "removeSlot": ["LineupSlot send-only"],
        "clearTeamLineup": ["LineupSlot send-only"],
        "replaceTeamLineup": ["LineupSlot send-only"],
        "getSlotsForTeam": ["LineupSlot send-only"],
        "runLineupSlotDB": ["Database-backed interpreter; requires Error DBError"]
      }
    },

    "Pelotero.Effects.LineupSnapshot": {
      "decisions": [
        {
          "name": "NewEffectForPhaseB3",
          "what": "LineupSnapshot is a separate effect from LineupSlot; the two have different lifecycles and different consumers",
          "why": [
            "LineupSlot is the live, mutable, owner-edited lineup. LineupSnapshot is the immutable per-game freeze. Different concerns, different effects.",
            "Pelotero.Score reads ONLY from LineupSnapshot; Pelotero.Lineup.Snapshot writes ONLY to LineupSnapshot. Pelotero.UI / lineup management reads/writes LineupSlot.",
            "Splitting the effects keeps the producer/consumer graph clean and avoids the temptation to read from the live lineup at scoring time (which was the original correctness bug)."
          ],
          "affects": []
        }
      ],
      "invariants": {
        "writeSnapshots": ["LineupSnapshot send-only; writes a list of LineupSnapshotRow with ON CONFLICT DO NOTHING; returns ()"],
        "getSnapshotsForDateRange": [
          "LineupSnapshot send-only; (Day, Day) -> [LineupSnapshotRow]",
          "consumed by Pelotero.Score.scoreOneTeam (Phase C.2): single query replaces the per-game getSnapshotForTeamGame loop"
        ],
        "getSnapshotForTeamGame": [
          "LineupSnapshot send-only; (DbLeagueTeamId, DbGameId) -> [LineupSnapshotRow]",
          "consumed by Pelotero.Lineup.Snapshot.snapshotLineupsForTeam"
        ],
        "snapshotExistsForTeamGame": [
          "LineupSnapshot send-only; (DbLeagueTeamId, DbGameId) -> Bool",
          "consumed by Pelotero.Lineup.Snapshot.snapshotLineupsForTeam"
        ],
        "getSnapshotsForGame": [
          "LineupSnapshot send-only; DbGameId -> [LineupSnapshotRow]",
          "audit/inspection use; not on the scoring path"
        ],
        "runLineupSnapshotDB": [
          "Database-backed interpreter; delegates to Pelotero.DB.LineupSnapshot",
          "requires Error DBError"
        ]
      }
    },

    "Pelotero.Effects.PlayerRanking": {
      "invariants": {
        "getRankingsForTeam": [
          "PlayerRanking send-only",
          "intended consumer is the planned Pelotero.Draft state machine (D.1); no consumer in tree today"
        ],
        "replaceRankings": ["PlayerRanking send-only"],
        "clearRankings": ["PlayerRanking send-only"],
        "getRankingCount": ["PlayerRanking send-only"],
        "runPlayerRankingDB": ["Database-backed interpreter; requires Error DBError"]
      }
    },

    "Pelotero.Effects.DraftPick": {
      "invariants": {
        "recordPick": [
          "DraftPick send-only",
          "intended consumer is the planned Pelotero.Draft state machine (D.1); no consumer in tree today"
        ],
        "getPicksForLeague": [
          "DraftPick send-only"
        ],
        "getPickCount": ["DraftPick send-only"],
        "runDraftPickDB": [
          "Database-backed interpreter; requires Error DBError",
          "no in-memory interpreter — draft picks are append-only and the in-memory equivalent would be a list"
        ]
      }
    },

    "Pelotero.Effects.BoxscoreEntry": {
      "invariants": {
        "upsertBatting": ["BoxscoreEntry send-only"],
        "upsertPitching": ["BoxscoreEntry send-only"],
        "getBattingForGame": [
          "BoxscoreEntry send-only",
          "consumed by Pelotero.Score.buildPlayerMaps (one call per game in the period)"
        ],
        "getPitchingForGame": [
          "BoxscoreEntry send-only",
          "consumed by Pelotero.Score.buildPlayerMaps"
        ],
        "deleteBattingForGame": ["BoxscoreEntry send-only"],
        "deletePitchingForGame": ["BoxscoreEntry send-only"],
        "runBoxscoreEntryDB": [
          "Database-backed interpreter; requires Error DBError"
        ],
        "runBoxscoreEntryNever": [
          "test interpreter that errors on every operation",
          "useful for tests that need BoxscoreEntry in the effect stack but exercise paths where no batting/pitching upsert should occur (e.g. C.1 SHA-skip tests with empty boxscore JSON)",
          "any actual invocation is the test's bug, not a real failure mode — the error message names the operation that was unexpectedly called"
        ]
      }
    },

    "Pelotero.Domain.Id": {
      "decisions": [
        {
          "name": "UpstreamAndSurrogateAreDistinctTypes",
          "what": "PlayerId / TeamId / GameId (upstream MLB ids) and DbPlayerId / DbTeamId / DbGameId (surrogate DB BIGSERIAL ids) are different newtypes",
          "why": [
            "Conflating them led to bugs: a function expecting an MLB id received a DB surrogate, the SQL succeeded with the wrong row, and nothing complained.",
            "Newtype distinctness forces the conversion to be explicit (a lookup against player_external_id) rather than a coerce.",
            "The cost is more wrappers; the win is the type system catching crossings of the layer boundary."
          ],
          "affects": []
        },
        {
          "name": "TextIdsForUserSpaces",
          "what": "LeagueId and FantasyTeamId wrap Text, not Int",
          "why": [
            "Leagues and fantasy teams have user-chosen identifiers (e.g. 'east-coast-2025', 'rocketeers'), not auto-incremented numbers.",
            "Database surrogate keys (DbLeagueConfigId, DbLeagueTeamId) are still Int64 for indexing efficiency; user-facing stays Text."
          ],
          "affects": []
        },
        {
          "name": "NoSmartConstructorsHere",
          "what": "All newtypes have public constructors and accessors; no smart-constructor validation",
          "why": [
            "Validation (rejecting nonsense like PlayerId 0) happens at the wire boundary in Pelotero.MLB.Convert.convertPlayer.",
            "The wire layer is the single source of truth for what counts as a valid id; this module is structural only.",
            "Pelotero.Provider.ExternalId provides the to/from Text encodings (Phase A.1) but does not validate id ranges."
          ],
          "affects": []
        }
      ]
    },

    "Pelotero.Domain.Position": {
      "decisions": [
        {
          "name": "ExhaustiveSumNoCatchAll",
          "what": "The Position type is an exhaustive sum of MLB's ten positions; parsePosition returns Nothing on anything else",
          "why": [
            "Positions are a small, stable set defined by MLB rules.",
            "An 'Other Text' fallback constructor would make the type infectious.",
            "Errors at the wire boundary surface as warnings, not silent fallbacks."
          ],
          "affects": ["parsePosition"]
        },
        {
          "name": "TwoWayPlayerNotModelled",
          "what": "MLB's 'TWP' (two-way player, e.g. Ohtani) is intentionally not parsed",
          "why": [
            "TWP requires a richer domain model (a player has multiple primary positions with separate stat lines).",
            "Out of scope for the current engine; would change scoring shape."
          ],
          "affects": ["parsePosition"]
        }
      ],
      "invariants": {
        "parsePosition": [
          "accepts BOTH MLB numeric codes ('1','2',...,'10') AND scorer abbreviations ('P','C','1B','2B','3B','SS','LF','CF','RF','DH')",
          "case-sensitive: '1b' would not match",
          "returns Nothing for 'TWP' (intentional)"
        ],
        "renderPosition": [
          "returns the scorer form",
          "exhaustive over the sum"
        ],
        "isPitcher": ["True for Pitcher only; False for everything else including DH"],
        "isInfielder": [
          "True for FirstBase, SecondBase, ThirdBase, Shortstop, AND Catcher",
          "Catcher being an infielder is conventional for fantasy classification"
        ],
        "isOutfielder": [
          "True for LeftField, CenterField, RightField",
          "DH is not an outfielder despite the position number 10 being adjacent"
        ]
      }
    },

    "Pelotero.Domain.Player": {
      "decisions": [
        {
          "name": "TotalHandChar",
          "what": "handChar :: Handedness -> Char is exhaustive case-of, total at the type level",
          "why": [
            "Phase A.6 introduced this to replace the partial T.head . renderHandedness path.",
            "Adding a new Handedness constructor is a -Wincomplete-patterns error here; the previous design (T.head over a Text) deferred totality to the renderHandedness exhaustivity, with a hidden coupling that wasn't enforced by anything visible at the call site.",
            "The DB column for bat_side / pitch_hand remains Text (PostgreSQL CHAR(1) padding gotchas), but the API is now total Char end-to-end."
          ],
          "affects": ["handChar"]
        }
      ],
      "invariants": {
        "parseHandedness": [
          "accepts only 'L', 'R', 'S' (case-sensitive)",
          "consumed by Pelotero.MLB.Convert.convertHand"
        ],
        "renderHandedness": [
          "exhaustive: LeftHanded -> 'L', RightHanded -> 'R', Switch -> 'S'",
          "kept for symmetry with parseHandedness; sync code now uses handChar instead"
        ],
        "handChar": [
          "exhaustive case-of: LeftHanded -> 'L', RightHanded -> 'R', Switch -> 'S'",
          "total; consumed by Pelotero.Sync.Players.upsertAllPlayers (replacing T.head . renderHandedness)"
        ]
      }
    },

    "Pelotero.Domain.Team": {},

    "Pelotero.Domain.Game": {},

    "Pelotero.Domain.Stats": {
      "decisions": [
        {
          "name": "MaybeIntPerField",
          "what": "Every stat field in the per-game stats records is Maybe Int rather than Int with a default of 0",
          "why": [
            "Distinguishes 'didn't bat' from 'batted, went 0-for-0'.",
            "A pitcher's batting line in the AL legitimately has Nothing for atBats, not 0.",
            "Scoring layer applies fromMaybe 0 at the point of multiplication; presence/absence info is preserved up to that point."
          ],
          "affects": ["emptyBatting", "emptyPitching"]
        },
        {
          "name": "PitOutsIsCanonicalNoTextField",
          "what": "PitchingStats has pitOuts :: Maybe Int and NO pitInningsPitched field; the wire-format string is parsed at Convert time and discarded",
          "why": [
            "Phase B.1 collapsed the redundancy. The wire ships both pitOuts (Maybe Int) and pitInningsPitched (Maybe Text); convertPitching reconciles the two and emits a WireFieldDiscrepancy warning if they disagree, then keeps only the Int.",
            "Outs are exact integers; the Text representation was only ever a wire-layer artifact. Domain code now never has to worry about the parse round-trip footgun.",
            "renderInningsPitched still exists for human-facing display (e.g. 'Roberts pitched 6.2 innings') but is no longer in the scoring/storage path."
          ],
          "affects": ["emptyPitching", "parseInningsPitched", "renderInningsPitched"]
        }
      ],
      "invariants": {
        "emptyBatting": [
          "all-Nothing default for every BattingStats field",
          "BattingStats has 25 Maybe Int fields; all wire-derived"
        ],
        "emptyPitching": [
          "mirror of emptyBatting for pitching",
          "PitchingStats has ~40 Maybe Int fields plus pitOuts as Maybe Int (NO pitInningsPitched, post Phase B.1)"
        ],
        "parseInningsPitched": [
          "input: '6.2' or '6' or '6.0'; output: outs (Int)",
          "'6.2' = 6 innings + 2 outs = 20 outs",
          "the fractional part must be 0, 1, or 2; '6.3' returns Nothing",
          "negative whole or fractional parts return Nothing",
          "non-numeric input returns Nothing",
          "consumed only by Pelotero.MLB.Convert.convertPitching at the wire boundary"
        ],
        "renderInningsPitched": [
          "inverse of parseInningsPitched; outs -> Text",
          "20 -> '6.2'",
          "negative input -> '0.0'",
          "kept for human-facing display only; not used in the scoring/storage path post Phase B.1"
        ]
      }
    },

    "Pelotero.Domain.Roster": {
      "decisions": [
        {
          "name": "SeqForOrderedSlotMembers",
          "what": "Roster and Lineup both use Map RosterSlot (Seq PlayerId) — Seq, not List or Set",
          "why": [
            "Order matters within a slot.",
            "Set would lose ordering; List has O(n) appends; Seq has O(log n).",
            "The slot order itself doesn't matter (Map handles that), but the order within a slot does. Persistence of within-slot order via order_index columns is planned B.2 work."
          ],
          "affects": ["addToRoster", "addToLineup"]
        },
        {
          "name": "ValidationProducesAllErrorsNotJustFirst",
          "what": "validateRoster and validateLineup return [RosterError] / [LineupError] — all problems, not just the first",
          "why": [
            "When showing errors in a UI, displaying 'too many at OF (3 vs 2)' AND 'duplicate player X' is more useful than 'too many at OF, retry'.",
            "Order is: all size problems then all duplicate problems."
          ],
          "affects": ["validateRoster", "validateLineup"]
        }
      ],
      "invariants": {
        "allRosterSlots": [
          "[minBound .. maxBound]; the canonical traversal order is the constructor order in RosterSlot"
        ],
        "parseRosterSlot": [
          "case-sensitive; accepts 'catcher', 'first', 'second', 'third', 'shortstop', 'outfield', 'utility', 's_pitcher', 'r_pitcher'",
          "the s_pitcher / r_pitcher names match legacy DB schema"
        ],
        "renderRosterSlot": [
          "exhaustive; produces the parse-target strings"
        ],
        "isPitcherSlot": ["True for SlotStartingPitcher and SlotReliefPitcher"],
        "isBatterSlot": ["= not . isPitcherSlot; SlotUtility is a batter slot"],
        "emptyRoster": ["every slot present with empty Seq"],
        "emptyLineup": ["mirror of emptyRoster"],
        "rosterAt": ["returns Seq.empty if the slot is somehow missing from the map"],
        "lineupAt": ["mirror of rosterAt"],
        "addToRoster": [
          "appends to the slot's Seq using Map.insertWith",
          "no validation against limits at this point"
        ],
        "addToLineup": ["mirror of addToRoster"],
        "removeFromRoster": [
          "removes the FIRST occurrence of pid from the slot's Seq",
          "does nothing if the slot or pid is absent"
        ],
        "removeFromLineup": ["mirror of removeFromRoster"],
        "seqRemoveFirst": ["private; uses Seq.breakl + Seq.viewl"],
        "rosterPlayers": ["concatMap toList over slot Seqs"],
        "lineupPlayers": ["mirror of rosterPlayers"],
        "rosterContains": ["linear scan via elem"],
        "lineupContains": ["mirror of rosterContains"],
        "countAt": ["Seq.length on the slot; O(1)"],
        "countAtLineup": ["mirror of countAt"],
        "rosterLimitFor": ["Map lookup; defaults to 0 if the slot has no entry"],
        "lineupLimitFor": ["mirror of rosterLimitFor"],
        "totalRosterSize": ["sum of all slot limits"],
        "totalLineupSize": ["mirror of totalRosterSize"],
        "validateRoster": [
          "produces all over-limit errors then all duplicate errors",
          "duplicates detected via group . sort, so the resulting list is in PlayerId order"
        ],
        "validateLineup": ["mirror of validateRoster but with LineupError variants"],
        "duplicates": ["private; group . sort then take first of each group of size >= 2"]
      }
    },

    "Pelotero.Domain.Scoring": {
      "decisions": [
        {
          "name": "PointsAsRationalNotDouble",
          "what": "The Points newtype wraps Rational, not Double",
          "why": [
            "Sums of fantasy points across many games accumulate; floating drift is observable when a season total visibly disagrees with the sum of game lines.",
            "Scaling by Rational multipliers (e.g. 1/3 for innings) stays exact end-to-end."
          ],
          "affects": ["scalePoints", "scoreBatting", "scorePitching"]
        },
        {
          "name": "MultiplierFieldsAsExplicitRecord",
          "what": "The batting and pitching multiplier records list every scored stat as a named field",
          "why": [
            "A Map String Rational would defer typo detection to runtime.",
            "Adding a stat is a structural change on purpose."
          ],
          "affects": ["scoreBatting", "scorePitching"]
        },
        {
          "name": "DerivedStatsInScoringNotData",
          "what": "Singles (batting) and quality starts (pitching) are derived inside scoreBatting / scorePitching, not stored as fields",
          "why": [
            "Singles = hits - (doubles + triples + homeRuns); the wire layer doesn't ship singles separately.",
            "Quality start = IP >= 6 AND ER <= 3; not a stat the boxscore reports."
          ],
          "affects": ["scoreBatting", "scorePitching"]
        },
        {
          "name": "ScorePitchingReadsPitOutsDirectly",
          "what": "scorePitching reads pitOuts straight from PitchingStats; no parseInningsPitched . pitInningsPitched step (post Phase B.1)",
          "why": [
            "The redundancy between pitInningsPitched (Maybe Text) and pitOuts (Maybe Int) is gone at the Domain level; PitchingStats now has only pitOuts.",
            "Removes a parse step from every scoring call. More importantly, removes a class of bug where a future caller could set pitOuts without setting pitInningsPitched (or vice versa) and silently get the wrong answer."
          ],
          "affects": ["scorePitching"]
        },
        {
          "name": "InningsPitchedExactRationalArithmetic",
          "what": "scorePitching computes 'pmInningPitched * (outs / 3)' as Rational, not as a Double or pre-rounded decimal",
          "why": [
            "Per-inning multipliers are typically integers or simple fractions; fractional outs need exact division.",
            "Pre-rounding loses ~0.05 points per fractional inning, compounding over 150 starts."
          ],
          "affects": ["scorePitching"]
        }
      ],
      "invariants": {
        "zeroPoints": ["Points 0; identity for addPoints"],
        "addPoints": ["pointwise Rational addition"],
        "subPoints": [
          "pointwise Rational subtraction; can produce negative Points",
          "currently has no in-tree caller; effectively dead code retained for symmetry"
        ],
        "scalePoints": [
          "multiplies Points by a Rational; preserves exactness"
        ],
        "sumPoints": [
          "left-fold over a Foldable; uses zeroPoints as the seed"
        ],
        "scoreBatting": [
          "sums per-stat contributions; each contribution is multiplier * count",
          "singles are derived: max 0 of (hits - doubles - triples - homeRuns)",
          "missing stats default to 0 via fromMaybe; an empty BattingStats produces zeroPoints"
        ],
        "scorePitching": [
          "outs read directly from pitOuts (post Phase B.1); no parseInningsPitched step",
          "qualityStarts is 1 if outs >= 18 (6 innings) AND earnedRuns <= 3, else 0",
          "innings-pitched contribution uses Rational (outs/3) for exactness"
        ],
        "rationalPts": [
          "private; Int -> Points via toRational"
        ]
      }
    },

    "Pelotero.Domain.Draft": {
      "decisions": [
        {
          "name": "PureOrderGenerator",
          "what": "generateDraftOrder is pure (no IO, no Random); randomness is supplied by the caller as the order of the input team list",
          "why": [
            "Pure functions are testable without any randomness effect.",
            "If the caller wants random ordering (a coin flip for first pick), they shuffle the team list outside this module and pass it in.",
            "Keeps this module free of effects."
          ],
          "affects": ["generateDraftOrder", "serpentine", "experimentalSnake"]
        },
        {
          "name": "TruncateTrailingPartialRound",
          "what": "If totalPicks is not a multiple of length teams, the trailing partial round is dropped, NOT half-completed",
          "why": [
            "A draft with N teams should always have a multiple-of-N pick count.",
            "Half-completing a round would create asymmetry; truncating preserves the 'teams are equal' invariant."
          ],
          "affects": ["generateDraftOrder"]
        },
        {
          "name": "PureModuleByDesign",
          "what": "This module stays pure; no effectful state machine lives here today, and a future Pelotero.Draft (planned D.1 work) will be the home of the live draft state machine when it lands",
          "why": [
            "generateDraftOrder is pre-computation pure logic. Running an actual draft requires database writes per pick, which means the live state machine has to live in a module with effect access.",
            "Splitting the modules keeps Pelotero.Domain.Draft testable without effects; Pelotero.Draft (when implemented) will be testable via the in-memory effect interpreters."
          ],
          "affects": []
        }
      ],
      "invariants": {
        "parseDraftOrderStrategy": [
          "case-sensitive; accepts 'serpentine' or 'experimental_snake'"
        ],
        "renderDraftOrderStrategy": [
          "exhaustive over the sum"
        ],
        "generateDraftOrder": {
          "intent": "Produce the full pick-by-pick order as (team, pickNumber)",
          "notes": [
            "empty teams returns []",
            "rounds = totalPicks `div` length teams; trailing partial round is truncated",
            "pick numbers are 1-indexed",
            "pure: no randomness, no IO"
          ]
        },
        "serpentine": [
          "private; rounds copies of [teams, reverse teams] alternating"
        ],
        "experimentalSnake": [
          "private; rounds copies of [teams, mid-shifted, reverse, mid-shifted-reverse] alternating",
          "reproduces the legacy 'experimental_snake' algorithm"
        ],
        "rankingPlayerIds": [
          "extracts just the PlayerIds from a Ranking, in rank order",
          "assumes Ranking.rankingEntries was constructed in rank order — does NOT sort"
        ],
        "extendRankingsWithUnranked": [
          "appends unranked players to the end of ranked, preserving universe order",
          "intended consumer is the planned Pelotero.Draft AutoPick handler when a team's ranking is shorter than the player pool; no consumer in tree today"
        ]
      }
    },

    "Pelotero.Domain.League": {
      "decisions": [
        {
          "name": "LeagueStatusOnlyMutableField",
          "what": "League's only field that changes after creation is leagueStatus; everything else is the immutable league definition",
          "why": [
            "Scoring rules, roster limits, and draft params shouldn't change mid-season.",
            "Status moves through draft -> active -> closed in the lifecycle."
          ],
          "affects": ["parseLeagueStatus", "renderLeagueStatus"]
        },
        {
          "name": "ScoringPeriodAsUtcTime",
          "what": "ScoringPeriod uses UTCTime, not Day",
          "why": [
            "Real leagues have lineup-lock cutoffs at specific game start times in specific timezones.",
            "Day would be ambiguous; UTCTime forces an explicit instant."
          ],
          "affects": []
        }
      ],
      "invariants": {
        "parseLeagueStatus": ["case-sensitive; accepts 'draft', 'active', 'closed'"],
        "renderLeagueStatus": ["exhaustive over the sum"]
      }
    }

  }
}