brackt/docs/superpowers/specs/2026-05-01-canonical-tournament-layer-design.md

Canonical Tournament & Participant Layer

Date: 2026-05-01 Status: Proposed

Overview

Qualifying-points sports (golf, tennis, CS2) use a four-event "season" that can roll across calendar boundaries (e.g., a June 2026 tennis window needs Wimbledon 2026, US Open 2026, Australian Open 2027, French Open 2027). Today the data model ties events and participants to a single sportsSeasons row, which means two overlapping windows must each have their own copy of Wimbledon 2026, their own Djokovic, their own surface Elo. Any change — results, corrections, Elo adjustments — must be applied to every copy.

This design introduces a canonical layer above the existing per-window layer:

• Canonical tables own real-world identity (tournaments, participants, final results, surface Elo).
• Per-window tables keep their role: which tournaments a window uses, which participants its draft pool contains, and window-specific derived data (EV, QP totals, QP config).

Results entered once on the canonical tournament fan out to every window that contains it. Surface Elo edited on a canonical participant propagates automatically. Creating a new rolling window is a point-and-click composition over the canonical data.

Per-window data that is inherently window-specific (expected value under a particular 4-event set, QP running totals, QP point configuration) stays per-window — because the math depends on which 4 events you're summing over.

Scope

• In scope: All scoringPattern='qualifying_points' sports — golf, tennis, CS2. The model is sport-agnostic, but migration covers these three.
• Out of scope: Team sports (NHL, MLB, NBA, WNBA, UCL, NCAAM/W), single-event sports (darts and snooker use only the World Championship — no rolling window problem). These keep their existing model.
• Out of scope: Historical fully-completed windows. No league currently has a completed qualifying-points sportsSeason, so there's nothing to backfill for reporting.

Architecture

Canonical tables (new)

tournaments
  id            uuid pk
  sport_id      fk → sports
  name          varchar           -- "Wimbledon"
  year          integer
  starts_at     timestamp
  ends_at       timestamp
  surface       varchar nullable  -- tennis only: hard | clay | grass
  location      varchar nullable
  status        enum              -- scheduled | in_progress | completed
  external_key  varchar nullable  -- reserved for future ATP/PGA/HLTV IDs
  created_at, updated_at
  UNIQUE (sport_id, name, year)

participants            -- RENAMED; see migration section
  id            uuid pk
  sport_id      fk → sports
  name          varchar
  external_key  varchar nullable
  metadata      jsonb
  created_at, updated_at
  UNIQUE (sport_id, name)

tournament_results
  id            uuid pk
  tournament_id fk → tournaments
  participant_id fk → participants
  placement     integer
  raw_score     decimal nullable
  created_at, updated_at
  UNIQUE (tournament_id, participant_id)

participant_surface_elos       -- tennis-specific; replaces the existing per-window table of the same name
  id            uuid pk
  participant_id fk → participants  (canonical)
  world_ranking integer nullable
  elo_hard      integer nullable
  elo_clay      integer nullable
  elo_grass     integer nullable
  updated_at
  UNIQUE (participant_id)

Shape note: Kept wide format (elo_hard/elo_clay/elo_grass) to match the existing per-window participant_surface_elos table, minimizing simulator read-path churn. world_ranking moves here because it's a real-world attribute of the participant, not a per-window value.

Name collision handling: The existing per-window participant_surface_elos table is renamed to season_participant_surface_elos in Phase 1 before the new canonical table of the same name is created.

Per-window tables (renamed / extended)

The existing participants table is renamed to season_participants. Related tables follow the same renaming pattern for clarity:

Old name	New name
participants	season_participants
participant_expected_values	season_participant_expected_values
participant_qualifying_totals	season_participant_qualifying_totals
participant_results	season_participant_results
event_results.participant_id	event_results.season_participant_id
participant_surface_elos (existing per-window)	season_participant_surface_elos (renamed in Phase 1); removed entirely in Phase 4 after canonical values verified

FK additions (nullable at Phase 1, NOT NULL after Phase 2 backfill):

• scoring_events.tournament_id → tournaments.id
• season_participants.participant_id → participants.id

Unchanged: sports_seasons, season_sports, qualifying_point_config, draft_picks, teams, draft_slots, watchlist, scoring calculation code in app/models/scoring-calculator.ts, simulators' Monte Carlo logic.

Source of truth

Concept	Table
Tournament existence & final placements	tournament_results (canonical)
Window → tournament mapping	scoring_events via tournament_id
Canonical participant identity	participants
Window's draftable roster	season_participants
Per-window derived scoring (QP awarded, totals, EV)	season_participant_*, event_results
Surface Elo & world ranking	participant_surface_elos (canonical)

Data Flow

Creating a new window

Admin flow has two new steps during sports_seasons creation for qualifying-points sports:

1. Pick tournaments — multi-select from tournaments filtered by sport_id. Inline create if missing. Writes scoring_events rows with tournament_id set.
2. Pick roster — multi-select from participants filtered by sport_id. Writes season_participants rows with participant_id set. Inline-create canonical participants if missing.

Downstream (EV upload, QP config edit, draft) is unchanged.

Entering results (enter-once flow)

New admin route: /admin/tournaments/:id.

1. Admin enters placements for a canonical tournament. UI supports the same paste-and-parse flow as the existing 2026-04-12-batch-qualifying-results design, but targets the canonical tournament.
2. Save writes tournament_results rows (upsert on (tournament_id, participant_id)).
3. syncTournamentResults(tournamentId) fans out:
   • For each scoring_events row with tournament_id = tournamentId:
     • For each participant in tournament_results whose canonical participant_id also appears in that window's season_participants: upsert a matching event_results row with placement and raw_score.
     • Apply existing "fill 0-QP for non-scoring season participants" behavior per the batch qualifying results design.
     • Run the existing processQualifyingEvent (idempotent — replaces QP, doesn't add) against that window's scoring event.
     • Update season_participant_qualifying_totals per the existing path.
   • Each window's fan-out is its own transaction. Failures are logged per-window with a retry action in the admin UI.
4. Tournament status auto-advances to completed on first result insert.

Corrections

Edit tournament_results → re-run syncTournamentResults. Idempotent updates to every affected window. No stale data unless sync fails (surfaced in UI).

Surface Elo

Read path: app/models/surface-elo.ts's getSurfaceEloMap(sportsSeasonId) joins season_participants → participants → participant_surface_elos (canonical). Admin UI for surface Elo edits canonical participant_surface_elos directly, keyed on canonical participant. Edit affects all current and future windows containing that participant.

Migration Plan

Four phases. Each is reversible until the next begins.

Phase 1 — Schema (data untouched)

Two sequential Drizzle migrations, in order, to avoid name collisions between the old per-window tables and the new canonical tables:

Phase 1a — Renames of existing tables (no new tables yet):

• participants → season_participants
• participant_expected_values → season_participant_expected_values
• participant_qualifying_totals → season_participant_qualifying_totals
• participant_results → season_participant_results
• participant_surface_elos → season_participant_surface_elos
• event_results.participant_id → event_results.season_participant_id

Update every code reference, Drizzle relations, model file names, and type imports. Existing app/models/participant.ts is renamed to app/models/season-participant.ts. npm run typecheck and npm run test:run must pass before proceeding to Phase 1b.

Phase 1b — New canonical tables:

• Create tournaments, participants (canonical), tournament_results, participant_surface_elos (canonical).
• Add nullable FKs: scoring_events.tournament_id, season_participants.participant_id.
• A new app/models/participant.ts is created for the canonical table (the old model file was renamed in 1a, freeing the name).

No logic paths read from canonical tables yet.

Reversible: run migrations in reverse (drop canonical tables first, then reverse the renames).

Phase 2 — Backfill

One-off script scripts/backfill-canonical-layer.ts with --dry-run and --sport=<id> flags.

For each sports_seasons where scoring_pattern='qualifying_points':

1. Upsert tournaments rows by (sport_id, name, year) from the window's scoring_events. Set scoring_events.tournament_id.
2. Upsert participants rows by (sport_id, name) from the window's season_participants. Set season_participants.participant_id.
3. For each event_results row with qualifying_points_awarded IS NOT NULL (i.e., already-scored events like Masters 2026): upsert a tournament_results row with placement and raw_score. Do not copy qualifying_points_awarded — QP stays on event_results because it's window-specific.
4. For each row in season_participant_surface_elos (the renamed per-window table): upsert into canonical participant_surface_elos keyed by canonical participant_id, copying elo_hard, elo_clay, elo_grass, world_ranking. Abort if two windows disagree on a canonical participant's values (not expected today — fail loud if encountered).

Dry-run writes nothing; emits a CSV + summary to stdout.

Go/no-go: dry-run reviewed by maintainer, real run matches dry-run counts exactly, spot-check Masters 2026 tournament_results row matches its event_results row.

Reversible: truncate canonical tables, null out FK columns. Old code paths still functional.

Phase 3 — Cutover

• ALTER scoring_events.tournament_id and season_participants.participant_id to NOT NULL.
• Implement app/models/tournament.ts, app/models/participant.ts (canonical), app/models/tournament-result.ts.
• Implement app/services/sync-tournament-results.ts.
• Add admin route app/routes/admin.tournaments.$id.tsx with paste-and-parse result entry.
• Add admin "create window" flow additions for tournament + roster picking.
• Switch surface Elo admin UI and getSurfaceEloMap to canonical read/write.
• Switch tennis simulator's surface Elo source to canonical.
• Existing per-window "Add Result" / batch entry routes become thin wrappers that write canonical + call sync. (They are removed in Phase 4.)

Feature-flag the new admin entry route; cut over during a no-draft window.

Go/no-go: new window created end-to-end in staging via canonical flow; all pre-Phase-1 baselines match post-Phase-3 values.

Phase 4 — Cleanup

• Remove per-window result entry wrappers.
• Drop season_participant_surface_elos table via migration after verifying canonical participant_surface_elos is fully populated and all code paths read from canonical.
• Remove any compatibility shims.

Testing Matrix

Required types: U unit, M model integration (real DB), E end-to-end (Cypress).

Baselines to capture before Phase 1

1. Monte Carlo simulator output JSON for each in-flight qualifying-points window, committed as a test fixture.
2. Snapshot of participant_qualifying_totals (pre-rename; post-Phase-1a this is season_participant_qualifying_totals) per window.
3. Snapshot of each window's event_results for completed events (Masters 2026, any completed CS2 majors).

These are used to verify no scoring drift across phases.

Phase 1 — Schema

What	Where	Type	Scenarios
Drizzle migration applies cleanly	staging run + npm run db:migrate	—	Forward run; re-run db:generate and confirm no drift
Renames propagate in code	npm run typecheck, npm run test:run	—	Pass
Relations load	existing model tests (updated for renames)	M	All pass

Phase 2 — Backfill script

What	Where	Type	Scenarios
Backfill dry-run	scripts/__tests__/backfill-canonical-layer.test.ts (new)	M	(a) Empty DB → no-op. (b) One in-flight golf window with 4 events incl. Masters 2026 → 4 tournaments, N canonical participants, N tournament_results rows. (c) Two tennis windows with overlapping participants → one canonical participant per (sport, name). (d) Conflicting canonical rows pre-existing → script aborts with clear error. (e) Dry-run writes nothing; real run matches dry-run CSV exactly.
Surface Elo backfill	same test file	M	All existing surface Elo rows translate to participant_surface_elos (canonical); counts match; conflicts abort.
Masters 2026 round-trip	same test file	M	Post-backfill: tournament_results for Masters 2026 matches event_results placement/raw_score; qualifying_points_awarded untouched on event_results; season_participant_qualifying_totals untouched.
Baseline verification	scripts/__tests__/verify-baselines.test.ts (new)	M	season_participant_qualifying_totals post-backfill matches pre-Phase-1 baseline snapshot of participant_qualifying_totals (they should be identical — backfill doesn't touch QP).

Phase 3 — New code paths

What	Where	Type	Scenarios
app/models/tournament.ts	app/models/__tests__/tournament.test.ts	M	CRUD, unique (sport_id, name, year), findBySport, status auto-advance.
app/models/participant.ts (canonical)	app/models/__tests__/participant.test.ts	M	CRUD, unique (sport_id, name), find-or-create.
app/models/tournament-result.ts	app/models/__tests__/tournament-result.test.ts	M	Upsert semantics, placement updates, idempotency.
app/services/sync-tournament-results.ts	app/services/__tests__/sync-tournament-results.test.ts	M	(a) Single window, roster matches all result participants → event_results created, QP processed. (b) Two windows share a tournament with overlapping but different rosters → only matching participants get event_results in each window; QP processed independently per window. (c) Participant in roster but not in tournament_results → 0-QP row (matches existing batch finalize). (d) Re-run with same data → idempotent, no duplicates. (e) Re-run after placement correction → all windows updated, QP re-processed. (f) One window's sync fails → others still succeed; failure logged and retryable.
Admin /admin/tournaments/:id route	app/routes/__tests__/admin.tournaments.$id.test.tsx (new)	M	Loader returns tournament + results; action upserts + triggers sync; non-admin → 403.
Admin create-window flow	cypress/e2e/admin-create-qualifying-window.cy.ts (new)	E	Admin picks 4 tournaments + roster → window created with FKs populated; draft room loads.
Result entry fan-out	cypress/e2e/enter-tournament-result.cy.ts (new)	E	Two windows share Wimbledon 2026; admin enters Wimbledon results once; both windows' QP standings update.
Surface Elo canonical	app/models/__tests__/surface-elo.test.ts (update)	M	Reads and writes go to canonical participant_surface_elos; tennis simulator receives correct values; world_ranking reads correctly.
Tennis simulator surface Elo	app/services/simulations/__tests__/tennis-simulator.test.ts (update)	U	Fed canonical surface Elo; Monte Carlo output matches baseline fixture within tolerance.
Back-compat wrappers for old per-window routes	existing route tests (update)	M	Writes via old routes still succeed and produce identical event_results.
Masters 2026 regression	scripts/__tests__/verify-baselines.test.ts	M	Post-Phase-3 QP standings for existing golf window match pre-Phase-1 baseline exactly.

Phase 4 — Cleanup

What	Where	Type	Scenarios
Old result-entry routes removed	removed test files	—	Routes return 404.
Drop season_participant_surface_elos	staging verification	—	Canonical participant_surface_elos fully populated; season_participant_surface_elos no longer read by any code path; drop migration applies cleanly.
Full regression	npm run test:all	—	Green.

Cross-cutting smoke tests (after every phase)

1. Load an in-flight golf draft room → Masters 2026 results render, QP standings match baseline.
2. Run tennis simulator for an in-flight window → Monte Carlo output matches baseline fixture within tolerance.
3. Create a fresh draft for an existing window → draft picks save (no NULL FK errors).

Risks & Mitigations

R1. Name collision for canonical participants. UNIQUE (sport_id, name) is correct for today's roster sizes. external_key reserved for future disambiguation via ATP/PGA/HLTV IDs.

R2. CS2 team-name churn. Rebranded team is a new canonical participant. Intentional — matches current fantasy semantics.

R3. Masters 2026 double-scoring. processQualifyingEvent is already idempotent (replaces QP). Explicit test in Phase 2 + Phase 3 matrix.

R4. Sync fan-out partial failure. Per-window transactions. Each window logs success/failure independently. Admin UI shows "synced to X of N windows" with per-window retry.

R5. Simulator output drift. Baseline Monte Carlo output captured before Phase 1 and compared after each subsequent phase.

R6. Draft-in-progress during cutover. Phase 3 deployed behind a feature flag, enabled during a no-draft window.

R7. Admin muscle memory. Old routes stay as wrappers through Phase 3; removed in Phase 4. Release notes accompany Phase 3 cutover.

Out of Scope / Flagged for Later

• Backfill of fully-completed historical windows: no such windows exist today.
• Automated import of tournament results from external feeds (ATP/PGA APIs). external_key column reserves space for this.
• Cross-sport disambiguation for identical names (extremely rare; punted until real).
• Merge tool for canonical participants if a duplicate is created accidentally (can be added later; not a v1 blocker given admin-only data entry).