Add server-side scrim endpoint (POST /api/v1/scrim) with atomic volume budget

[razam-sherwani]

Dependency: READY — unblocked 2026-08-18. The former #169 blocker was closed as not planned: #168's default now applies to every new ladder, so a scrim ladder stood up today inherits maxQueuedPerTeam = 10 and no backfill is needed. Closes #112 when it lands. See the turnstile correction in the comments before implementing.

Summary

Add POST /api/v1/scrim { taBotSlug, count } so students can run rate-limited practice matches against TA bots server-side instead of relying entirely on the locally-shipped obfuscated binary. See OBFUSCATION_PITCH.md §6 for full design rationale (Option E / J-centric recommendation).

Requirements:

• Resolve the TA-bot team server-side (TA-bot UUIDs never appear in the request/response).
• Enforce an atomic, windowed volume budget — one SQL statement, not read-then-write:

  INSERT INTO scrim_usage (team_id, ladder, window_start, count) VALUES (..., 1)
  ON CONFLICT (team_id, ladder, window_start)
  DO UPDATE SET count = scrim_usage.count + 1 WHERE scrim_usage.count < :cap
  RETURNING count;

• Concurrency check must include created/scheduling states, not just waiting/in_progress (the current Set.of(waiting, in_progress) in GameMatchService.countTeamQueuedMatchesByLadder is a hole a team can sit in).
• Return Retry-After on rejection.
• Write an audit row (this table doubles as attribution evidence and as the only telemetry available today — there's no actuator, and Prometheus only scrapes postgres_exporter).
• Carries @RequireTurnstile.

Closes #112

This is the same fix needed for the existing check-then-act race described in #112 ("I introduced a check-then-act race in the scrimmage rate limiter... we should fix this in the future"). Implement the atomic upsert pattern for both the new scrim budget and the existing rate limiter, and close #112 when this merges.

Suggested starting budget

~20/day, 60/week, burst 2 — then tune from the scrim_usage table rather than debating the number up front.

[razam-sherwani]

Two design points settled since this was filed, plus one correction to the original body.

1. This endpoint stays in Java, here. A separate Go microservice for the delivery side was floated on 2026-08-14 and is deferred behind an explicit trigger. Worth separating the two endpoints that discussion kept conflating: this one — the scrim/grading endpoint — is core webserver logic (ladders, Glicko, the RabbitMQ publish, the atomic budget SQL above) and was never really the thing in question. The debatable one is the delivery endpoint that gates pre-built TA-bot artifacts, and the conclusion there was also Java-in-this-repo for now, because every piece it needs already exists (LocalStorageService.getDownloadLink, HmacService, FileRecord + its persisted sha256) and the compilation can't move to either language regardless — Nuitka can't cross-compile, so building artifacts stays in CI. Revisit Go only if a shared Go tooling tier materialises independently.

2. @RequireTurnstile — correct the requirement above. The original body lists it as a requirement, which conflicts with #157 (merged 2026-07-24), where turnstile was removed from PrivateGameMatchController — the closest sibling endpoint, and for the same student-facing match-creation action. The annotation still exists and SubmissionController still uses it, so it remains implementable, but adding it back on a new match endpoint would quietly reverse a recent decision. Treat it as an open question for whoever picks this up, not a requirement, and follow whatever the current position on turnstile is.

3. Ordering. #159 is fixed and merged (#168), so the blocking prerequisite is cleared — but only for ladders created from here on. #169 tracks the sweep of existing rows still at maxQueuedPerTeam = 0; a scrim ladder created before that sweep will 429 on the first match and look broken on arrival. #170 tracks the missing test coverage on the endpoint this one extends.

Everything else in the body still stands: atomic upsert rather than read-then-write, TA-bot resolution server-side, created/scheduling included in the concurrency check, Retry-After on rejection, and the audit row doubling as the only telemetry available today.

[razam-sherwani]

Design decisions locked 2026-08-15 — this issue is confirmed as specced.

1. Student-initiated, as written. The alternative considered was auto-triggering a graded run on submission (a second scheduleMatch alongside the validation match at SubmissionController.java:144). Rejected: it makes the benchmark something that happens to a team rather than something they can aim at, and it inherits an unbounded trigger while Limit team submission count and implement submission deletion #96 is open. The endpoint stays as specced above.
2. No turnstile. Removing this from the requirements — Remove turnstile #157 took @RequireTurnstile off PrivateGameMatchController, the closest sibling endpoint, and a new endpoint shouldn't quietly reverse that. The atomic budget is the abuse control, and unlike a challenge it also bounds legitimate volume, which is the actual objective.
3. Capacity expectation, so this doesn't get mistaken for a practice loop. At 3 replicas × prefetch=1 this supports roughly 14 matches per team across a 48-hour crunch — a graded checkpoint, not a practice loop. The contract does not change when NUM_REPLICAS rises; only the quota does. Worth saying in the student-facing copy so expectations match reality.
4. Java here, not a separate Go service. Confirmed. Note the premise is still pending though: the "private webserver provides the secret boundary" argument assumes a private repo, and this repo is still public today.

Still open by design: the quota numbers (start 20/day, 60/week, burst 2 and tune from scrim_usage).

[razam-sherwani]

Three-tier reframe, 2026-08-16 — this issue is the T3 (server-side graded) tier.

Delivery is now three tiers (OBFUSCATION_PITCH.md §9 decisions 13–16):

• T1 — freely-shipped local sparring bundle (as today).
• T2 — streamed, metered, deterrence-only delivery → #171 (the "obfuscation-delivery endpoint" this issue's body says it is not; it now exists separately, so the two are no longer conflated).
• T3 — this issue. The graded benchmark that runs on our runners and never ships.

Nothing here changes — the rescope is only that T3 is now explicitly the protection tier while #171 handles metered delivery. Still blocked by #169 (existing-ladder sweep). The atomic-upsert budget pattern specced here is reused by both #171's fetch budget and #173's validation cap.