NMAO Tournament

The competition engine of the NMAO suite — a monthly, video-based martial arts tournament. Competitors submit an event video each round; an automated engine sorts them into fair divisions and skill-based pods, routes videos to judges, scores them, updates ratings and standings, and ships collectible medals. A season runs 9 qualifying rounds → semi-finals → grand finale.

Backend is Supabase (Postgres + Auth + Edge Functions + Storage). The engine is a pure, DB-free, unit-tested core wrapped by idempotent edge functions keyed by (round_id, step) — the same core powers live runs and the operator preview.

Repo layout

README.md                                   This file
docs/
  NMAO-suite-handoff.md                     Master orientation for the whole 3-product suite
  engine-spec.md                            Full tournament engine spec (state machine, pipeline, overrides)
  scoring-and-rating.md                     Plain-language, auditable spec of scoring + the locked rating rule
  project-log.md                            Living log: locked decisions, parked ideas, open items
supabase/
  migrations/                               Ordered, reconciled set — apply in filename order
    20260804000000_base_reference_people.sql        1/3 reference + people/org (schools, competitors,
                                                    guardians/COPPA consents, judges[+school_id], staff)
    20260805120000_tournament_engine.sql            2/3 engine (seasons, division_schemes, rounds, divisions,
                                                    pods, entries, judge_assignments, results, step-runs, audit)
    20260806000000_ratings_finance_recognition.sql  3/3 skill_ratings (seed 50), rating_history, medals +
                                                    medal_shipments, payments, payouts, content_reports, season_results
    20260807000000_rls_policies.sql                 4/4 per-role Row-Level Security: competitor/guardian/judge/
                                                    staff scoping + public reference/structure; engine via service role
  functions/
    _shared/
      divisioning.ts                        Step 3 core: classify → collapse → formPods → runDivisioning
      assignments.ts                        Step 4: per-video judge assignment (1/3, own-school exclusion)
      rating.ts                             Step 4: resolve (score→placement) + LOCKED same-rank rating
      distribute.ts                         Step 4: medal ship list (one shipment per school)
      roundState.ts                         Step 4: round state machine + §4 guardrails
      engine.ts                             Step 4: idempotent orchestration over an EngineStore seam
      supabaseStore.ts                      Supabase (Deno) EngineStore adapter — not run by npm test
      *.test.ts                             93 assertions total across the cores
    round-controller/
      index.ts                              Edge entrypoint: run a step (or the tail) for a round
mission-control/
  index.html                                Operator dry-run console (seeded data, real engine) — open in a browser

Migrations reconciled (2026-08-06): the earlier forked 001 schema was split into the three ordered files above (base → engine → ratings/finance). The engine schema is the source of truth for competition structure; ratings/finance/recognition were repointed onto the engine's rounds/entries/divisions; judges.school_id and a medal_shipments table were added. Verified to apply clean in order against Postgres (PG16) with all foreign keys resolving.

Status

• Step 2 — data-model migration: done (engine schema applies clean against Postgres).
• Step 3 — divisioning core: done. Pure, DB-free, deterministic.
• Step 4 — round-state controller + remaining pipeline steps: done. Assign judges, resolve (straight-average scoring + tiebreak), update ratings (the locked same-rank rule), distribute (ship list), plus the round state machine and idempotent orchestration keyed by (round_id, step). The Supabase adapter + round-controller edge function wire the pure cores to the DB.
• Step 5 — mission-control UI + end-to-end dry run on seeded data: done (mission-control/index.html).

npm test runs 93 assertions, all passing (divisioning 24, rating 21, assignments 11, distribute + state machine 19, engine orchestration 18).

Open before a live DB run: confirm the identity→role model the RLS policies assume (auth users linked via auth_user_id; guardians act for their competitors; the school app has no school↔auth mapping yet, so school data is staff-only for now), stand up a Supabase project + env for the round-controller edge function, and design the video storage/moderation pipeline. Schema reconciliation, judges.school_id, medal_shipments, and per-role RLS policies are done (RLS row-isolation validated against Postgres with test users for each role).

See docs/engine-spec.md for the pipeline and docs/scoring-and-rating.md for exactly how every score and rating is produced.

Running the tests

Requires Node 18+ (uses tsx to run the TypeScript tests directly).

npm test

Expected: each suite prints N passed, 0 failed.

Mission Control (dry run)

Open mission-control/index.html in any browser — no build step. Seed competitors/schools/judges, edit the Division Scheme, simulate, then advance a round through the full state machine (classify → … → distribute) and watch pods, judge assignments, results, rating deltas, and the per-school medal ship list. Its embedded engine mirrors the locked cores.

Locked engine parameters (season 1)

Pod floor 6 · rank tiers beginner/intermediate/advanced · age brackets 7-9, 10-12, 13-15, 16-17, 18+ · pods cap 20, split at 22 · collapse merges nearest rank then age, never across events · judging 1 judge (beginner/intermediate) or 3 (advanced) · 3-judge score = straight average · tiebreak = highest single-judge score then earliest submission · incomplete pod = reopen to judge pool, never force-resolve.

Rating (locked): every competitor seeds at 50 on a 0–100 scale; rating moves on placement, measured only against same-rank podmates; K = 8 for a competitor's first 3 rounds then 4; clamped 0–100; used only to form pods within a rank bracket — it never crosses ranks (that's a real dojo promotion via declared_rank). Full formula + worked examples in docs/scoring-and-rating.md.