Skip to content

Verify CI on final head 44bafa0 - #149

Closed
nathan-probert wants to merge 172 commits into
mainfrom
feat/final-clean
Closed

nathan-probert wants to merge 172 commits into
mainfrom
feat/final-clean

Conversation

@nathan-probert

Copy link
Copy Markdown
Owner

Verification-only PR to run CI on feat/final-clean tip 44bafa0. Do not merge.

Player-Snapshots-{ENV} stores one row per player per date, captured live as the
pipeline runs. That capture has two properties that limit it:

* Sparse. Rows exist only for pick-relevant dates, not every game a player
  played, so it cannot answer "what were this player's stats entering game X"
  for an arbitrary X.
* Lossy on early rows. Rows captured in the first weeks of a season store rates
  at 2 decimal places (0.31) where later rows carry 6 (0.320755). The rounding
  is baked in at capture time.

This adds a pipeline that rebuilds those stats from the NHL's per-game box
scores, walking each season forward and accumulating.

Player-Snapshots-backtrack-{ENV} mirrors the live archive's 30 columns exactly,
so it is a drop-in replacement. Today date/player_id/name/team_name/home/gpg are
populated; the rest are declared and documented as not-yet-reconstructed, with
the reason per column (3-year windows for hgpg/hppg, no definition found for
tgpg/otga/otshga, and fields absent from the game-log feed for the goalie,
lineup and injury columns).

Player discovery comes from the box scores, not from the existing table. The
point is to replace the archive rather than supplement it, so the player set
must not be defined by who the old table happened to record - a player picked
for the first time appears because he played a game.

The raw per-game layer is data/dumps/*.sql.gz (1.8 MB per season), a gzipped SQL
text dump. Text so it diffs line by line in review; gzipped because the 32 MB
SQLite working copy compresses to 1.8 MB and would otherwise duplicate every
row. `make backtrack-load` rebuilds the database from it, so a fresh clone can
query the data without re-crawling.

Verified against Player-Snapshots-prod on 2023-24: 46,297 rows, 880 players,
and gpg agreeing on 15,640 of 15,667 comparable rows (99.83%), where the
remainder are archive rows rounded to 2dp and the reconstructed values are the
more precise of the two.

Refs the #113 archive work.
Second feature on top of gpg, computed as a rolling window over the raw
per-game rows rather than by re-crawling - `local_store.py --derive
20232024` then `--publish`, about 15 seconds end to end.

five_gpg is goals over the player's last 5 games. The window resets per season,
which falls out of the existing window partition (season, player_id), so the
denominator ramps 1, 2, 3, 4 and then pins at 5. A player's debut game is NULL
rather than 0, keeping "has not played yet" distinct from "played and scored
none" the same way gpg does.

THE DIVISOR IS DELIBERATELY DIFFERENT FROM THE ARCHIVE

smartscore_info_client's get_five_gpg divides by a hardcoded 5 regardless of how
many games the player has played. Sidney Crosby's first two games of 2023-24 are
2 goals in 2 games, which is a hot start; that function reports 0.2 and 0.2. The
archive's own values confirm the shape of the problem - 11 distinct values, all
multiples of 0.2, which is what a constant divisor produces, and it collapses a
rookie scoring on debut into the same value as a cold player with no goals in five.

Here the divisor is the number of games in the window, so that debut reads 1.0.
716 rows (1.39%) change, all early-season; distinct values go from 11 to 21 and
the maximum from 2.0 to 4.0.

Consequence, measured: agreement with Player-Snapshots-prod on five_gpg moves from
99.70% to 99.45%, with the 87 mismatches spread across 27 dates in
2024-02-17..2024-04-18. That is expected. This table exists to replace the
archive, and reproducing a division bug is not fidelity.

Verified against prod before and after: 47,221 published rows with goalies
excluded, gpg unchanged at 15,640/15,707. The dump round-trip was re-checked
with the new column and comes back identical, so `make backtrack-load` still
rebuilds the store exactly.
The archive carries three team-level features that are not player stats: every
player on a club holds the same value for a given date. From
smartscore_info_client's models/team.py:

    tgpg  - the team's own goals FOR per game, season to date
    otga  - the OPPONENT's goals AGAINST per game, i.e. how many goals this team
            scores on that specific opponent
    otshga- the opponent's shorthanded goals against per game

They live in Team-Stats-backtrack-{ENV} keyed on (season, team_abbrev, game_id)
rather than being denormalised onto player rows, where the archive repeats one
number across ~21 rows per team-date.

TEAM GOALS MUST COME FROM team_goals_for, NOT FROM SUMMING PLAYERS

Two goal types count toward a team's total but appear in no skater's box score
row, so summing player goals undercounts:

  * shootout game-winning goals - on the scoreboard and in the team total, but
    the play-by-play carries only a shootout-complete marker and the box score has
    no shootout play at all. Confirmed: PIT at MTL on 2023-12-13 (2023020442),
    official 4, skater sum 3, and PIT won the shootout.
  * goalie empty-net goals - officially credited to the goalie, omitted from his
    `goals` field. PIT at TBL on 2023-11-30 (2023020345): official 4, skater sum 3.

The archive's own totals include both, per the NHL glossary note that standings
GF/GA count shootout winners while the stats pages do not. The fix is the box
score's own awayTeam.score / homeTeam.score, which we were already fetching and
discarding. PIT 2023-12-13's official scores are 4 and 3, so the field was
complete all along; summing player rows was simply the wrong source.

otga additionally needed restructuring. It is the opponent's conceded rate, so
each team first carries its own goals-against (the sum of what its opponents
scored), and otga is then read off the *other* team's row for the same game. The
previous version accumulated the opponent's goals scored over our own games, which
is our scoring rate against them - related, but not the same number.

A NULL, not a 0, on a team's season debut: a zero claims a team averages no goals
per game, which the archive emits (Winnipeg, Anaheim, Dallas and Carolina all
show tgpg = 0 early in the current season).

A team's game with no opponent is refused rather than written with a silently
wrong otga.

VALIDATION

validate.py joins in Python on team_abbrev, never team_name. Three SQL joins were
tried first and all were wrong for the same reason: the archive's team_name is a
PLACE name, and NYI and NYR both render as "New York", so any join through it
matches whichever club's row the planner returns first. That surfaced as ~560
"wrong" team-stat rows which were really Rangers/Islanders values swapped. It cost
real time to diagnose and the module docstring records it.

  gpg      15,656 / 15,707 comparable  99.68%
  five_gpg 15,620 / 15,707            99.45%

15,707 archive rows compared with none missing a local match. The gpg residue is
2024-02-24, the stale-capture date, where our values are the more precise of the
two. The five_gpg residue is the intended divided-by-5 divergence.

Team features are counted but not compared: the archive has no team key at all
outside a six-day window, so there is nothing unambiguous to join against. That
needs 2026-27 crawled, where team_name is actually populated.

otshga remains NULL and documented - it needs
api.nhle.com/stats/rest/en/team/penaltykilltime, and cannot be derived from
per-player goals.
DEBUT ROWS ARE 0, NOT NULL

Empirically checked against Player-Snapshots-prod: 40 archive rows sit on
players' first-of-season dates and every one stores gpg 0 - including a player
who scored in his debut that night (8481462, 2024-02-19). The row is entering
the game, so 0 is the archive's pre-debut convention, not a missing value.
reconstruct_player normalises _rate's None and compute_derived's window SQL
gates on prev_gp = 0, so neither table ever carries a null gpg.

SCOPE: GAME DATES ONLY, REGULAR SEASON ONLY

Coverage diff against the local store (52,468 player_games rows): all 17,105
regular-season archive rows land on game dates - the archive has no rows on
non-game dates at all, so --all-dates was scanning 10x the dates to reproduce
nothing and is removed. The one real gap is playoff dates: 1,398 archive rows
(8.2%) fall after 2024-04-18 while this rebuild is regular-season scope. That
is documented in the module docstring and the player migration rather than
papered over.

DEAD CODE AND STALE DOCS

get_players, get_archive_dates, _opponent_for, and validate.py's compare() are
removed - unreachable after earlier refactors. main()'s target discovery
collapses into one if/elif/else: the old structure could fall through an
unmatched branch with appearances unbound, and a --player dry run did crash
that way; the fixed path has a regression test. team_map now says NYI/NYR share
"New York" (both New York clubs) and covers ARI through 2023-24 alongside UTA
from 2024-25. The team migration described otga/otshga as the team's own goals
against; they are the OPPONENT's - the old reading matched 107 of 16,301 rows.
The player migration's "every date is present" claim is replaced with the
measured coverage above.

Makefile: backtrack-publish is now derive + publish + publish-team (it used to
publish a table compute_derived may never have touched), with new
backtrack-derive and backtrack-validate targets.

TESTS

21 tests under tests/unit/test_backtrack_*: team_map place names, aliases and
the NYI/NYR collision; reconstruct_player's strictly-before gpg, debut-zero,
box-score context override and name fallback, plus a main() smoke test;
_literal's SQL rendering including the new None -> NULL; compute_derived's
window SQL (debut 0, strictly-before counts, idempotent replacement);
compute_derived_team's otga semantics and the no-opponent refusal. pyproject's
pytest pythonpath gains smartscore/scripts/backtrack.

Also adds .gitattributes so data/dumps/*.sql.gz diffs opt into gunzip textconv,
and runs ruff-format over the 7 files failing CI's lint job.

Verified: ruff check and format clean, 249/250 unit tests pass (the failure is
test_utility_schedule_run expecting -{ENV} -dev against a local ENV=prod .env),
and reconstruct.py --player 8476967 --season 20232024 --dry-run agrees with
prod on 29 of 30 compared rows. The one difference is the archive's
stale-capture 2024-02-24 row, which missed the 02-23 game (2/53 vs the correct
2/54); both sides agree again on 02-26 and 02-28.
The live archive was missing two columns the product depends on for 2023/24:
tims (challenge pick groups) and lineup/PP units. Live scrapes only answer
for today, so both are rebuilt from history instead:

- tims_client.py: api.hockeychallengehelper.com/api/history?datetime= serves
  the same playerLists shape back to 2023-10-10; cached per date, 404s (the
  offseason) cached as empty. tims_map joins player->group per game date.
- lineup_reconstruct.py: shiftcharts from the legacy stats API are swept per
  period into constant on-ice sets, strength-classified, and clustered into
  F1-F4 / D1-D3 / PP1-PP2 by shared TOI. Goalie shifts are filtered first
  (they span the whole time in net and would glue lines together and break
  the 5v4 read), and merges are size-capped at 3F/2D/5PP - without the cap,
  greedy sum-linkage collapses one mega-cluster once its cross-edges
  out-sum any real line pair.
- local_store: player_lineups table + --lineups CLI; publish now ships
  tims (0 = unlisted), lineup_unit, lineup_position_group, pp_unit, and
  lineup_status = ACTUAL (the live product stored PROJECTED).
- run_background: lineups and publish commands so multi-minute runs stay
  detached.

Published to Player-Snapshots-backtrack-dev: 50,389 rows, 22,182 tims
entries across 232 dates. Spot-checked McDavid 2023-10-14 (tims=1, F2, PP1)
and Oilers playoff pairs. 271 tests pass, ruff clean.
The archive missed opp_goalie_* for 2023/24 the same way it missed tims:
the live pipeline only scrapes today's slate. Rotowire's
projected-goalies.php takes a date parameter that serves history (verified
back to 2023-10-10 and into the 2024 playoffs), answering the same game
shape the live get_starting_goalies parses - so the backtrack reads the
table the product already trusts rather than inventing a new source.

- goalie_client.py: fetch + per-date cache (goalies-{date}.json), team
  abbreviations normalized MON->MTL / LAS->VGK like the live pipeline.
  Offseason dates are empty lists; a non-list payload raises instead of
  caching a shape change that would poison every later publish.
- publish joins each skater's opponent to that date's starter and ships
  opp_goalie_name/team/status/confirmed with the live denormalization
  semantics: upper-cased status, separate confirmed boolean, and
  UNKNOWN/False when the table lists no starter for the team.
- The stat columns (gaa, save_pct, record, shutouts, games_played) stay
  NULL: live filled them from same-day club-stats, which is
  current-season-only, so season-end totals standing in for an October
  game's as-of-date view would be a lie the archive itself never told.

Published to Player-Snapshots-backtrack-dev: 2,800 team entries across
232 dates, all 50,389 rows now carry the opponent starter. Spot-checked
DeSmith/VAN on 2023-10-14 and Talbot/LAK on 2024-04-22. 275 tests pass.
scored was the last unwritten column the 20261008 migration called out.
It is derivable from the game itself - did this skater score in it - so
the publish reads the box score's goals column: ground truth, and it
covers every published row rather than only the challenge's listed
skaters. The helper API's own graded flag agrees with it on every listed
skater checked (159/159 on 2023-10-14), so no second source is needed.
The column was already declared by the migration; no schema change.

Adding pg.goals to the SELECT, though, broke the query plan: the column
made the covering index unusable, SQLite flipped the join order, and the
DISTINCT skaters subquery - an ephemeral co-routine - got re-scanned for
every outer row. Half a million row-comparisons per second of nothing;
the publish hung indefinitely on a query that used to take 0.4s.

The fix removes the subquery: drive the join from player_games with the
goalie filter inline (pg.position <> 'G'), which is the same row set
(50,389) in 0.74s and one fewer CTE for the planner to mis-order.

Published to Player-Snapshots-backtrack-dev: 7,579 scored=1 / 42,810
scored=0 / 0 null across the season - the scorer-instance count a
5.4 goals/game pace predicts. Spot-checked McDavid and Draisaitl, both
goals, on 2023-10-14.
get_hgpg(years=3)/get_hppg(years=3) sum goals (power play goals) and games
over the season and the two before it, then divide once. compute_historic
mirrors that: prior two seasons complete, current season strictly before the
row's own game - the frame gpg was validated on. Both priors must exist in
the store or the columns stay NULL rather than divide by a partial window,
so 20212022/20222023 wait on 20192020/20202021 being crawled.

Re-derived all four seasons; 20232024/20242025 re-published to dev.
Validated against Player-Snapshots-dev: hgpg 99.83%, hppg 99.98% at 2dp.
The dumps predate compute_historic, so a restored store would need a
--derive pass before the 3-year windows were queryable. 20212022/20222023
carry the columns with NULL values pending the 20192020/20202021 crawls.
The archive's opp_goalie_gaa/save_pct/record/shutouts/games_played were NULL for history: live read them from club-stats/{team}/now, which has no date parameter and only answers for the in-progress season. Rebuild them from the game logs --build already caches instead: compute_goalie_features walks each goalie's appearances strictly before the row's own game, partitioned on (player_id, team_abbrev) like club-stats' own team-scoped totals, NULL on a club debut where live left the keys unset, and publish matches the goalie by NHL id to each opponent row.

save_pct sums official per-game saves (round(savePctg * shots_against)) rather than shots - goals: club-stats' season saves exceed sa - ga by a save or two and its savePercentage is saves/shots, so a new saves column stores them and --gamelogs re-merges the log layer alone after schema changes. A post-debut 0-shot window reads 0.0, the value club-stats pairs with shotsAgainst 0.

validate.py --goalies compares season-end totals against club-stats for all four seasons - regular season only, GAA with a sub-second toi tolerance (their published GAA uses unrounded ice time), SV% rounded half-up like the API: 450/450 goalie-team totals match. Re-derived and re-published all four seasons to dev; regenerated the dumps with the saves column.
…eup columns

The WHAT IS AND IS NOT RECONSTRUCTED section predates compute_goalie_features: it claimed opp_goalie_*, lineup_* and pp_unit stay null against the live archive, but local_store.publish now writes all three to the same backtrack table (cached game logs and goalie feeds for the stats, shift charts for the lineup block). Only injury_* still has no reconstructed source, so the null-means-not-reconstructed guarantee now names just that family.
nathan-probert and others added 27 commits October 27, 2026 21:35
…) + one-time top-up; publishing carries them forward
… per-game columns + daily gap-filler backfill; stage-1 attach demoted to fallback

Lands stage 2 of exact-features on feat/final-clean, reconciling the
parallel stage-2 branch (feat/stage2-exact, 92188b6) with stage-1's
raw-column top-up (ca1f44e):

- run_daily_picks: today's 14 shot/TOI features are recomputed VERBATIM
  (model.shot_features_from_games) over the PUBLISHED per-game record
  (game_goals/game_shots/game_points/game_toi_min on
  Player-Snapshots-backtrack-{env}); full-history month-windowed fetch;
  exact career sums; rows lacking count facts drop to a partial-prefix
  recompute with a LOUD warning; the stage-1 carry-forward attach survives
  only as carry_forward_shot_block, the clearly-marked last-resort fallback
- backfill_missing_days: the daily gap-fill (first task of the day) -
  FINAL-state-only schedule checks, FRESH boxscore GETs (the cached-LIVE
  hazard is overridden by deleting stale cache files; nhl_client untouched),
  two-lane upserts (raw-only top-up vs identity+raw minimal-row creation),
  500-batch with the 3-try backoff envelope, per-date marker rows
  (Player-Game-Raw-Markers-{env}) making the first-run-of-day work happen
  once and every re-run a zero-write skip, progress logs per 5k
- wiring: run() invokes the gap-fill FIRST (not dry); dry passes are
  read-only end to end and only list missing game days; a partial backfill
  failure is LOUD but never fatal
- season_label: the COVID-era post-seasons (Jul-Sep 2020 -> 20192020,
  Jul 2021 -> 20202021) now key exactly like the raw store (verified: zero
  disagreements across the store's full date range)
- train_export: coerce empty-string rate columns from the live API download
  (object dtype refused by lightgbm; the CSV round-trip used to mask it)
- tests: 59 in the picks/backfill/shot-cols set incl. the 1e-9 parity
  anchor vs a real sqlite store and the train/run parity on synthetic
  history; dry zero-writes; marker idempotency; no-overwrite of the 16
  precomputed columns

Co-authored-by: feat/stage2-exact <worker@smartscore.local>
…xture

CI's full-suite run (a436b8c, run #481) failed
test_handler_first_step_backfill_invoked_once_when_not_dry: the STAGE B
gap-fill was invoked with ('dev', '2026-06-13') instead of prod.
run_daily_picks captures `from config import ENV` at import time; on CI
there is no gitignored .env, so config.ENV defaults to 'dev' and the
fixture's monkeypatch.setenv("ENV", "prod") cannot rebind the already-
imported module global. Locally the .env supplies prod, which is why the
141-test battery passed. The fixture now also patches the module global
(monkeypatch-restored) so the test is deterministic in both environments.
…s straight to SaveToDb

PR #134 (7d093fd) made normal_run archive via SaveToDb, leaving
first_run and normal_run with the same Next; PR #136 (ee69d53) moved
last_run's exit to CheckLastRun, so all three reachable branches of
CheckInitialRun went to the same SaveToDb. Drop the dead Choice and
route GetTims -> SaveToDb directly; CheckSaveHistory still branches on
$.status, so status propagation is untouched.
…ost-SavePlayers ASL ordering (kick fires from the state machine; fresh tims guaranteed)
…is + owner paths) and make topup-raw-game-cols
…04 fix) + record stage-2 raw top-up complete

(orchestrator's draft title suggested default-raise/resume work, but the
actual uncommitted diff from the timed-out worker is the season-key
removal; message reflects the real content)
…se wiring) - cold-start safe

The relay's Handler lives in the shared event_handler module chain
(event_handler.py:9 -> player_archive.py:38 -> config.py), and config.py
builds BOTH Supabase clients at import time (config.py:19/:23). With only
GITHUB_DISPATCH_TOKEN wired, the deployed MLPicksKick-{env} died on cold
start with 'SupabaseException: supabase_url is required' before the handler
ran (PR #146 owner escalation).

Option A (matches the shared-module pattern): wire SUPABASE_URL /
SUPABASE_API_KEY / SUPABASE_SERVICE_ROLE_KEY into MLPicksKickFunction from
the SAME CloudFormation params the other 15 functions use
(SupabaseUrl/SupabaseApiKey/SupabaseServiceRoleKey) - no new secrets, no
runtime change (the relay still never touches Supabase; the wiring is for
the import). ENV/PostHog stay unwired: the import chain defaults ENV
(config.py:12) and consults PostHog lazily only.

Tests:
- new tests/unit/test_ml_picks_import_chain.py imports the REAL chain in a
  deploy-zip-shaped subprocess sandbox (units/conftest.py's global
  supabase.create_client mock masked this class of failure until now):
  no-supabase-env -> cold-start crash; URL-only / URL+anon -> crash on the
  service-role client; full trio -> clean import; the relay module alone
  still imports configless (proving the requirement is the shared chain).
- test_template_env_vars.py: the relay exemption reduced to the optional
  vars (ENV/POSTHOG); a new test asserts the relay carries the import trio
  from the shared Supabase* params.

Verified: battery green (ml_picks_kick, template_env_vars, pipeline_schedule,
import_chain, event_handler, utility_schedule_run, utility: 115 passed;
full unit suite 523 passed), pre-commit (ruff lint/format, asl-lint) green,
cfn-lint clean. deploy.sh change needed: NONE - the Supabase params are
already in both create-stack/update-stack parameter lists; the same
deploy.yml flow redeploys it (dev: 'deploy' label on this PR; prod: merge).
docs/ml-picks-runbook.md section 9 documents the wiring.
…cksKick errors

The deployed MLPicksKick-{env} relay raises 'GitHub repository_dispatch
failed (status=403)' and nothing more - the urllib HTTPError body was
discarded, so a token-scope rejection was undiagnosable from the logs.

- _post_dispatch now returns the GitHub response body; relay_game_kick
  includes it verbatim in the retry warning and the raised RuntimeError.
- 403 gets a fingerprint + hint: e.g. 'Resource not accessible by
  integration' = token reached GitHub but lacks permission - fine-grained
  PATs need BOTH Actions: Read & write AND Contents: Read & write (the
  runbook's old 'Actions: write only' guidance produced exactly this);
  a classic PAT with the repo scope is the simpler alternative.
- Corrected the GithubDispatchToken CFN parameter description and the
  runbook PAT-setup section (both carried the under-scoped guidance).
- New tests: 403 body + hint surfaced, retry log carries the body.

diag context: the endpoint/URL/headers/body are verified correct - the
same POST returns 204 with a classic repo-scoped token (2/2 runs + the
flattened-layout relay path), so the deployed 403 is the token itself.
…od; dispatch override default prod; step-level ENV on backfill+inference; no silent default into wrong tables)
…r-Snapshots-backtrack-prod regardless of picks env; dev-shell false routing removed

- backfill_missing_days: player_table/marker_table resolve the SHARED ledger
  (Player-Snapshots-backtrack-prod / Player-Game-Raw-Markers-prod)
  independent of --env (verified: the helper never reads the LIVE table, so
  --env is now vestigial for the table resolution and kept for CLI/
  workflow compatibility only). The ONE remaining fail-loud gate is the
  shared ledger being truly empty - new bootstrap message
  ('run the publish/bootstrap chain once (make backtrack-publish
  ENV=prod) - the helper never bootstraps'), never the deleted
  -dev-shell routing / publish-era 'run the publish/backfill chain first'
  wall that hit the owner's dev-mode run.
- run_daily_picks: history_rows/history_team_rows/history_goalie_rows and
  the carry-forward fallback read the -prod backtrack ledgers regardless of
  picks env (dev backtrack tables deleted, docs/backtrack_dev_deleted.md);
  strict date < before_date and missing-day semantics unchanged; only
  today_live_rows (Player-Snapshots-{env}) stays env-resolved.
- docs/runbook: data-flow section + the §51/53 env tables corrected; new
  section 10 'ONE SHARED HISTORY LEDGER' with the owner note that dev-mode
  runs are self-healing against the shared ledger (viable kick again).
- tests: dev-run-backfill-targets-shared-ledger (no RuntimeError, no
  -dev resolution), prod unchanged (existing suite), history_rows reads
  the shared ledger on a dev run (incl. full wiring: teams/goalies/live
  split), fail-loud bootstrap gate kept + re-pointed to the new message.
- verified: file batteries green, full unit suite 530 passed / 3 failed
  (all 3 pre-existing at 223e253: test_rust::test_predict + 2
  test_utility_schedule_run), ruff check + format clean.
…creates them; DROP SQL + docs for the owner

The three dev backtracking tables were row-deleted 2026-10-24 and their
empty shells were verified 0 rows again on 2026-11-03 (prod verified
superseding on the same read: Player 624,253 planned / exact rows through
2026-10-29; Team 34,636; Goalie 37,044). PostgREST cannot DDL, so the
final DROP stays owner-side - but the standing migrate job could have
revived the -dev shells on the next main-push run because every backtrack
migration scoped table names through __ENV__ (ENV=dev on PR deploys).

* supabase/migrations: all six backtrack migration files hard-pin the
  table names to the '-prod' literal suffix, each headed with the
  BACKTRACK-PROD-PINNED marker + deletion rationale (dev backtracking
  RETIRED Oct 2026). No __ENV__ remains in any migration (placeholder
  scan clean for ENV=prod AND ENV=dev substitution; files parse as
  Postgres SQL under both substitutions via sqlglot).
* deploy.yml 'Guard migration files': files carrying the marker may
  hardcode '-prod'; any '-dev' literal, any backtrack table scoped
  through __ENV__, and any non-marker '-prod' literal fail the run.
* deleted_env_tables guard: docstring/message updated (shell dropped
  Oct 2026; name-based, fires whether or not the table exists).
  fidelity_tracker's dev daily-build path now resolves through the
  guard (--env dev / both fails loud with the prod pointer).
* tests: guard tests extended (name-based semantics, migration scans,
  prod-pin marker coverage); new fail-loud publish test
  (ENV=dev publish_team raises before any Supabase call); skip-path
  test re-pointed to prod.
* docs: ml-picks-runbook.md section 11 'Deleting the -dev backtrack
  table shells' - owner DROP SQL (verbatim, PostgREST cannot DDL),
  VACUUM/size notes, backup/restore paths (r-deldev worktree
  data/backups/MANIFEST.md); backtrack_dev_deleted.md + the shared
  ledger section cite the deletion date and point at section 11.
  The DROPs are intentionally NOT in supabase/migrations/ - the migrate
  job re-applies every file there every run.
…r's rule: prod is the source of truth for feature reads; explicit source=dev remains as the legacy override)
…egacy wipe mode demoted behind --write-mode; top-3 becomes the summary output

OWNER-CORRECTED CONTRACT (2026-11-03): Picks-{ENV} is the FULL PLAYER
SLATE the site's own pipeline publishes (SaveToDb -> handle_publish_db ->
publish_public_db -> utility.save_to_db). The ML pass's DEFAULT write
mode is now stat_update:

* stat_update_picks_db (new): read today's Picks-{ENV} slate rows
  (picks_slate_rows), compute a prediction for EVERY player of the
  frame, and PATCH ONLY the stat column on the existing rows -
  update({'stat': v}).eq('id', row_id), one PATCH per row (cites the
  helper conventions of _picks_table_rows/save_picks_db). A PostgREST
  PATCH scoped to an existing id can never insert and never touches
  another column, so the row count, ids and all other columns are
  identical pre/post BY CONSTRUCTION (test-pinned). NO delete anywhere.
* A missing slate (the run fires before the site's SaveToDb publish) is
  a WARN + CLEAN SKIP - never our own minimal rows; stat PATCHes are
  read-modify-write, so later kicks re-fill the CURRENT slate
  (idempotent; the site's re-publishes re-clear stat and we re-fill
  AFTER, ordering already serialized by the ASL's PublishToDb ->
  KickMLPicks edge).
* Call-ups without history: WARN by name, stat left untouched. Frame
  players absent from the slate: WARN, no write.
* Top-3 challenge picks (one per tims group, ranked within (date,tims)
  as before) become an OUTPUT: the SMARTSCORE_ML_PICKS log carries a
  'picks' array + write_mode + stat_column fill counts, and the job
  summary lists the picks table - never a Picks-table mutation.
* The legacy wipe-then-publish-the-3-picks REPLACE survives behind
  --write-mode legacy (event write_mode -> WRITE_MODE env var ->
  stat_update default; whitelisted, fail-closed). Evidence for the
  demotion: handle_save_historic_db derives the calendar picks via
  choose_picks from its OWN state payload, and NotifyUsers' handle_emails
  derives the email picks via choose_picks from the PUBLISHED FULL slate
  rows - the 3-row wipe publication replaced the slate both derive from.
* stat_value factored out of pick_rows_to_picks_db so both modes share
  the stat convention (rank-pct*100, 1 decimal, None on non-finite).
* ml-picks.yml (workflow): picks step gains the explicit
  --write-mode (dispatch input write_mode, default stat_update) and
  corrected comments; runbook docs the corrected contract + timing.
* smoke (live, dev sandbox): Picks-dev seeded id-for-id with the
  site's 2026-11-03 full slate (495 rows, Picks-prod's own rows, no
  dev/prod column differences) -> stat_update filled 495/495 with the
  artifact artifact_2026-10-29; pre/post FULL-ROW diff: 495/495 stat
  values changed (Rust 0-1 -> ML percent), 0 non-stat column diffs, row
  count + ids unchanged.
… 26 cross-file failures)

tests/unit/test_predict_picks.py and tests/unit/test_picks_db_nan_behaviors.py
both exec'd run_daily_picks under the same sys.modules key; whichever file
imported second replaced the entry and the OTHER file's name-keyed fixture
patches ("run_daily_picks.SUPABASE_ADMIN_CLIENT" / ENV) landed on the wrong
module object -> 26 failures whenever the two files shared a pytest session
(each file passing alone). Both bootstraps now reuse the already-loaded
module when its __file__ matches, so one shared per-session module carries
both files' monkeypatch wiring (each test still wires/patches per-test and
monkeypatch restores). Verified: the full required command
142 passed (uv run pytest, 6 files) + pre-commit run -a all green.
… only write mode; source=prod and the shared history ledger hard-pinned
@nathan-probert

Copy link
Copy Markdown
Owner Author

not sure why this was reopened.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants