feat(decision): add strict public API and streamed Tetris races

Signed-off-by: Xunzhuo <Xunzhuo@users.noreply.huggingface.co>

.dockerignore

@@ -7,6 +7,7 @@
 !engine.py
 !relay.py
 !model_registry.py
+!tetris_arena.py
 !examples.json
 !static/
 !static/**

.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+*.py[cod]
+.ruff_cache/
+.pytest_cache/

DEPLOYMENT.md

@@ -1,8 +1,8 @@
 # Gateway and resident workers
 
-The Docker Space is a CPU-only gateway: no weights or tokenization. One gateway process maintains up to four independent bounded queues, selected by an explicit model ID and pinned manifest. Keep one replica because queue state is in memory.
+The Docker Space is a CPU-only gateway: no weights or tokenization. One gateway process maintains up to six independent bounded queues, selected by an explicit model ID and pinned manifest. Keep one replica because queue state is in memory.
 
-Kai retains `decision-nano-preview`; the other wire IDs are `decision-lex`, `decision-sol` and `decision-nox`. `/v1/models` exposes actual sizes, complete-input limits and per-model examples. `/api/status?model=…` reports the selected queue. Omitting `model` selects Kai.
+Internal queues retain short wire IDs such as `decision-nano-preview` for Kai. `/v1/models` exposes canonical Hugging Face repository IDs, actual sizes, complete-input limits, and per-model examples; `wire_id` is supplied for the Studio editor. `/api/status?model=…` reports the selected queue. Public `/v1/systemone` and `/v1/decision/batches` calls must select a canonical model explicitly.
 
 Configure `DECISION_BACKEND=pull_queue`, the private `DECISION_WORKER_TOKEN` secret, and `DECISION_MODEL_REGISTRY_V2`. Each registry item includes `id`, `label`, `version`, `manifest_sha256`, `complete_input_tokens` and optional presentation/example metadata. The old `DECISION_MODEL_REGISTRY` remains a fallback for legacy two-model deployments. The newer variable allows existing code to ignore it safely during a coordinated upgrade.
 
@@ -14,8 +14,22 @@ For upgrades, verify idle queues and preserve exact previous sources and registr
 
 ## Shared-question context batches
 
-The gateway accepts both the legacy `state` request and the new mutually exclusive `states` request. Batch support is negotiated by authenticated worker heartbeat (`context_batch_v1`); `/api/status` exposes `context_batch`. A legacy worker continues serving single-context requests and is never given a batch it cannot handle.
+The public `/v1/systemone` endpoint accepts one `state`; `/v1/decision/batches` accepts ordered `states` with shared questions. Batch support is negotiated by authenticated worker heartbeat (`context_batch_v1`); `/api/status` exposes `context_batch`. A legacy worker continues serving single-context requests and is never given a batch it cannot handle.
 
 Deploy a compatible gateway first. Upgrade one idle worker at a time, retaining its exact released manifest and runtime. Stop the old process explicitly and let its heartbeat expire before the replacement claims that model. Keep decoder workers under their existing shared GPU lock. Enable the new batch interface after each registered model reports the capability. A model mismatch, expired lease or missing result is an error, never a trigger for fallback inference or automatic replay.
 
-User request bodies remain bounded at 256 KiB. Worker result messages have an 8 MiB bound for repeated labels and legends; other internal messages retain their prior bound. Credentials remain exclusively in the existing private worker secret mount and Space secret. No model weights are shipped in this Space.
+Public single-state request bodies remain bounded at 256 KiB; public batch bodies are bounded at 2 MiB, with at most 1,024 state/question decisions. Worker result messages have an 8 MiB bound for repeated labels and legends; other internal messages retain their prior bound. Credentials remain exclusively in the existing private worker secret mount and Space secret. No model weights are shipped in this Space.
+
+## Tetris Race
+
+`/tetris/` is a passive SSE client for server-authoritative races. Starting a race creates two independent asynchronous runners immediately; connecting, reconnecting, or slowing the event stream does not pause either model. A disconnect starts a bounded reconnection lease, after which an abandoned race is cancelled. Only the seeded tetromino sequence is shared. The server retains separate board snapshots, request states, model actions, and traces at `/api/tetris/races/{id}/trace`. An illegal model choice ends that side and is never replaced by a heuristic choice or another model.
+
+All endpoints and credentials are server-only Space variables or secrets. Configure the shared Decision gateway with `TETRIS_LOCAL_API_URL` pointing to its `/v1/systemone` route, or configure resident `drun` endpoints independently with `TETRIS_LOCAL_LUX_API_URL`, `TETRIS_LOCAL_NOX_API_URL`, `TETRIS_LOCAL_SOL_API_URL`, `TETRIS_LOCAL_EOS_API_URL`, `TETRIS_LOCAL_KAI_API_URL`, and `TETRIS_LOCAL_LEX_API_URL`. Optional local bearer secrets use the corresponding `_API_KEY` name or the shared `TETRIS_LOCAL_API_KEY`. A Decision response must return the exact Hugging Face canonical model ID selected by the player, such as `llm-semantic-router/Decision-1.0-Lux-9B`; a different or missing identity ends that side instead of being displayed under the wrong model name. This strict response identity is a deployment prerequisite. Legacy wire IDs such as `decision-lux` are not compatibility aliases here and deliberately fail closed during integration with an outdated Gateway.
+
+Configure Jev Cloud with `TETRIS_JEV_API_URL`, the `TETRIS_JEV_API_KEY` secret, and optional `TETRIS_JEV_MODEL`. Configure the alternate SystemOne provider with `TETRIS_SYSTEMONE_API_URL`, the `TETRIS_SYSTEMONE_API_KEY` secret, and optional `TETRIS_SYSTEMONE_MODEL`. Existing `JEV_API_*`, `JEV_MIRROR_API_*`, and `LOCAL_API_URL` variables remain accepted while the deployment migrates. The `jev-latest` alias accepts only itself or a versioned `jev-x.y.z` response; an explicitly pinned Jev model must match exactly. `/api/tetris/config` exposes only readiness and display metadata; it never returns endpoint URLs or credentials.
+
+Step races accept 1 through `TETRIS_MAX_STEPS` pieces. The default server limit is 120, and the configured limit can be raised to 2,000; `/api/tetris/config` supplies the active limit to the browser. `first_failure` has no user-visible step target and stops after the first game-over or model failure. Its operational guard defaults to the configured step limit and can be lowered with `TETRIS_FIRST_FAILURE_GUARD`. Each race reserves at most two provider calls per allowed step. `TETRIS_CLIENT_CALLS_PER_WINDOW` defaults to at least one full configured race (4,000 calls at the 2,000-step limit), and a lower explicit value is rejected. Retained events and traces are bounded by that race limit; completed races expire or are evicted from the in-memory cache, while quota records shed their trace references after completion.
+
+`TETRIS_RACE_TIMEOUT_SECONDS` sets a 1–3,600 second whole-race deadline (default 900); raise it deliberately for slow long runs. `TETRIS_STREAM_GRACE_SECONDS` sets the 1–300 second reconnection lease after the last event stream disconnects (default 30); reconnecting resumes retained SSE events, and the browser can recover the latest board and terminal result from the race snapshot. An abandoned race is cancelled. `TETRIS_COMPLETED_TTL_SECONDS` controls completed-race retention from 30–3,600 seconds (default 300). Shutdown cancels and awaits every active race before closing the provider transport. A failed, timed-out, or otherwise incomplete race does not award a score winner. The speed percentage is available only when both sides complete the same step target; it compares the sums of server-measured request-to-response times for both providers. Local `inference_ms`, when returned, is retained per turn in the trace for diagnosis and never enters that comparison. Whole-run durations remain in the race summary as diagnostics.
+
+`TETRIS_REQUEST_TIMEOUT_SECONDS` bounds each server-to-provider call to 0.1–300 seconds (default 45). The adapter sends optional bearer credentials only from server configuration, rejects redirects, ignores ambient proxy settings, bounds response bytes, and never returns provider URLs or credentials to the browser. Validate each configured endpoint with its selected canonical model and expected response identity before enabling that competitor; publishing a Space commit rebuilds the live Space.

Dockerfile

@@ -6,7 +6,7 @@ RUN useradd --create-home --uid 1000 studio
 WORKDIR /app
 COPY requirements.txt /app/requirements.txt
 RUN pip install -r /app/requirements.txt
-COPY --chown=studio:studio app.py systemone_api.py contract.py engine.py relay.py model_registry.py examples.json LICENSE /app/
+COPY --chown=studio:studio app.py systemone_api.py contract.py engine.py relay.py model_registry.py tetris_arena.py examples.json LICENSE /app/
 COPY --chown=studio:studio static /app/static
 USER studio
 EXPOSE 7860

README.md

@@ -17,6 +17,12 @@ license: mit
 
 [Decision collection](https://huggingface.co/collections/llm-semantic-router/decision-10-6ab12177bd0002394d8409f9)
 
+The Space also includes a server-authoritative [Tetris Race](https://decision.vllm-sr.ai/tetris/) playground. It can compare any two configured Decision models, Jev Cloud, or a SystemOne upstream without exposing provider credentials to the browser. Both runners receive the same seeded piece sequence but keep independent boards, requests, actions, timing, and traces.
+
+The race length follows the server's configured limit (120 steps by default, up to 2,000 when enabled). A provider failure or incomplete run has no score winner. For equal completed step races, the speed percentage compares server-measured request-to-response time on both sides; a provider's local inference time is only diagnostic.
+
+Tetris local endpoints must run the strict Decision API and echo the selected Hugging Face repository ID exactly (for example, `llm-semantic-router/Decision-1.0-Lux-9B`) in the response `model` field. Legacy wire aliases such as `decision-lux` are intentionally rejected; this makes an outdated or misrouted Gateway fail closed instead of attributing one model's play to another.
+
 | Model | Focus | Model size | Complete input per question |
 |---|---|---:|---:|
 | [Kai](https://huggingface.co/llm-semantic-router/Decision-1.0-Kai-0.6B) | Multilingual encoder | 0.6B | 1K |

SYSTEMONE_API.md

@@ -4,6 +4,7 @@ Call Lux, Nox, Sol, Eos, Kai, and Lex from your computer using the same `state /
 
 **Base URL:** `https://decision.vllm-sr.ai`  
 **Inference:** `POST /v1/systemone`  
+**Shared-question batches:** `POST /v1/decision/batches`
 **Models:** `GET /v1/models`
 
 This is a public demo endpoint backed by the released models on AMD GPUs. It requires no API key. Inference runs on the connected server; your computer sends the request. It is a shared, bounded service rather than a dedicated production deployment. Responses are real model outputs; there is no chat-completion endpoint.
@@ -13,7 +14,7 @@ This is a public demo endpoint backed by the released models on AMD GPUs. It req
 ```bash
 curl --fail-with-body https://decision.vllm-sr.ai/v1/systemone \
   -H 'Content-Type: application/json' \
-  -d '{"model":"Lux","state":"My subscription was charged twice. Please refund the duplicate charge.","questions":{"billing":{"type":"noul","instructions":"Does the customer report a billing problem?"},"team":{"type":"choice","instructions":"Which team should handle this message?","criteria":{"Billing":"Charges, invoices, and refunds","Accounts":"Login, passwords, and account access"}}}}'
+  -d '{"model":"llm-semantic-router/Decision-1.0-Lux-9B","state":"My subscription was charged twice. Please refund the duplicate charge.","questions":{"billing":{"type":"noul","instructions":"Does the customer report a billing problem?"},"team":{"type":"choice","instructions":"Which team should handle this message?","criteria":{"Billing":"Charges, invoices, and refunds","Accounts":"Login, passwords, and account access"}}}}'
 ```
 
 Ask multiple named questions in one call. The same state is used for every question and the worker processes the admitted decisions in GPU batches. This does not imply shared-state encoder caching.
@@ -32,7 +33,7 @@ from typesafe_sdk import Choice, Noul, TypeSafeClient, RetryPolicy
 with TypeSafeClient(
     base_url="https://decision.vllm-sr.ai",
     api_key="decision-public",  # SDK-required placeholder, not a credential
-    model="Lux",
+    model="llm-semantic-router/Decision-1.0-Lux-9B",
     timeout=60,
     retry=RetryPolicy(max_retries=0),
 ) as client:
@@ -52,7 +53,7 @@ with TypeSafeClient(
     print(result.choices["team"].choice)
 ```
 
-Change `model` to `Nox`, `Sol`, `Eos`, `Kai`, or `Lex`. Short names are case-insensitive; full Hugging Face repository names and existing wire IDs also work. The returned `model` identifies the actual worker. SDK calls explicitly select a model; raw HTTP requests that omit it use Lux. A standalone single-model Kai deployment still defaults to Kai.
+Select any exact Hugging Face repository ID returned as `id` by `/v1/models`. The model is required on public inference requests; short names, wire aliases, and case variants are rejected. The response repeats the selected canonical ID. The Studio editor uses separate same-origin endpoints for its internal queue and diagnostics.
 
 | Model | Parameters | Complete input per question |
 |---|---:|---:|
@@ -68,10 +69,10 @@ Change `model` to `Nox`, `Sol`, `Eos`, `Kai`, or `Lex`. Short names are case-ins
 ## Responses and limits
 
 - Noul returns P(true); Choice returns its winning label and probabilities; Score returns the expected ordinal level and its distribution.
-- Choice/Score `confidence` is **max(probabilities)**, the native peak probability. It is not a calibrated probability of correctness, and no equivalence to TypeSafe's proprietary confidence calculation is claimed. Raw distributions and predictions are unchanged. The response describes this definition in `profile`.
+- Choice/Score `confidence` is **max(probabilities)**, the native peak probability. It is not a calibrated probability of correctness, and no equivalence to TypeSafe's proprietary confidence calculation is claimed. Raw distributions and predictions are unchanged. Public responses contain only `model`, `answers`, and `usage`.
 - The hosted endpoint accepts one or more named questions without a fixed question-count cap. GPU execution uses microbatches of up to eight decisions. Choice accepts 2–255 options, Score accepts 2–10 ordered levels, and JSON requests are limited to 256 KiB. Expanded state/question input is limited to 16 MiB so large Cartesian workloads stay bounded. Provide explicit nonempty instructions. State plus question plus all candidates must fit the model limit; overflowing requests are rejected without truncation.
 - Synchronous requests have a 45-second server wait. Each model admits up to eight queued/running requests. A busy or timed-out service may return 429/503/504. Completed requests do not consume admission capacity. Do not treat transport errors as predictions. SDK example retries are disabled to avoid duplicate inference.
-- Studio additionally supports `states: [{id, state}, ...]`, with shared questions, without fixed context or decision-count caps; the same byte and complete-input budgets apply. This is a documented Decision extension; it is not the standard SDK response shape. With the standard SDK, call `system_one` separately for each state.
+- `POST /v1/decision/batches` applies one shared `questions` map to ordered `states: [{id, state}, ...]`. It requires the same explicit canonical `model`, unique state IDs, at most 1,024 states, questions, and total decisions, a 2 MiB JSON body, and the same 16 MiB expanded-input and per-question token budgets. Its atomic response contains `model`, ordered `results: [{id, answers, usage}, ...]`, and aggregate `usage`. This Decision extension is separate from the SDK's single-state method. There is no `/v1/systemone/batch` alias.
 
 See [SYSTEM_ONE_MAPPING.md](SYSTEM_ONE_MAPPING.md) for the complete adapter contract. The standard single-state call, all three answer types, and model discovery are validated with the official SDK.
 

SYSTEM_ONE_MAPPING.md

@@ -7,18 +7,18 @@ Studio exposes a **SystemOne-format Decision service** with official Python SDK
 | Input | Exact local mapping |
 |---|---|
 | `state` text/object/array | Native `state_text`; structured content serializes as UTF-8 JSON with sorted object keys and compact separators. No truncation. |
-| `states: [{id, state}, ...]` | Decision Studio extension for shared-question context batches; mutually exclusive with `state`. IDs are unique output keys and never added to model text. |
+| `states: [{id, state}, ...]` | `POST /v1/decision/batches` extension for shared-question context batches. IDs are unique output keys and never added to model text. |
 | Question map key | Native question ID and returned answer key. Never added to model text. |
 | `instructions` text/object/array | Native question text, with the same deterministic JSON rule. |
 | Choice `criteria` map | Each option name is semantic: null description → name; otherwise name + `: ` + full description. Object insertion order is retained. External native candidate IDs equal the names, but the names reach the model only through this explicit semantic text. |
 | Score `criteria` array | Ordered native levels with IDs and values 0…K−1. Returned score is the probability-weighted level index. |
 | Noul `criteria.false/true` | Native false/true descriptions. If absent, the original native default no/yes descriptions are used. |
 
-The adapter has no fixed question/context-count caps. It accepts 2–255 Choice options, 2–10 Score levels, a 256 KiB JSON request, and up to 16 MiB of expanded context/question input. Records execute in GPU microbatches of up to eight. The complete-input limit is 1,024 tokens for Kai/Lex and 16,384 for Eos/Sol/Nox/Lux **per question**, including state and all candidate descriptions. The selected model’s published loader and numerical engine are retained. Unsupported fields and models are rejected. This is an intentional bounded subset of the upstream interface.
+The public single-state endpoint requires exactly `model`, `state`, and `questions`, with a 256 KiB JSON body. The separate batch endpoint requires exactly `model`, `states`, and `questions`, with a 2 MiB JSON body and at most 1,024 states, questions, and total decisions. Both accept 2–255 Choice options, 2–10 Score levels, and up to 16 MiB of expanded context/question input. Records execute in GPU microbatches of up to eight. The complete-input limit is 1,024 tokens for Kai/Lex and 16,384 for Eos/Sol/Nox/Lux **per question**, including state and all candidate descriptions. The selected model’s published loader and numerical engine are retained. Unsupported fields and models are rejected.
 
-Single-context responses preserve named `answers`, Choice `choice/probabilities`, Score `score/legend/probabilities`, and Noul `noul`. `usage.output_tokens=0` because these models do not generate text. Studio adds actual timing/profile/source fields.
+Single-context responses preserve named `answers`, Choice `choice/probabilities`, Score `score/legend/probabilities`, and Noul `noul`. `usage.output_tokens=0` because these models do not generate text. The public inference envelopes contain only `model`, answers or results, and usage. Studio's internal endpoints additionally retain timing/profile/source fields.
 
-The synchronous `/v1/systemone` response supplies the SDK-required `confidence` as **max(probabilities)**, matching the native peak-probability convention. This is explicitly recorded in `profile.confidence_definition`; it is not calibrated correctness or a claim of equivalence to TypeSafe’s unspecified confidence formula. `top_probability` remains available and the original distribution is unchanged. Noul returns its original probability of yes. Internal worker and asynchronous Studio envelopes retain their existing fields.
+The public inference responses supply the SDK-required `confidence` as **max(probabilities)**, matching the native peak-probability convention. It is not calibrated correctness or a claim of equivalence to TypeSafe’s unspecified confidence formula. Noul returns its original probability of yes. Internal worker and Studio envelopes retain diagnostic fields, including `top_probability` and timing.
 
 This mapping is independently testable with small metadata fixtures. It does not change the model's packing, native graph, weights, scoring arithmetic, or export format.
 
@@ -28,7 +28,7 @@ Sol and Nox use their published `question_row` and `predict_rows` path, the same
 
 ```json
 {
-  "model": "decision-nano-preview",
+  "model": "llm-semantic-router/Decision-1.0-Kai-0.6B",
   "states": [
     {"id": "T-101", "state": "My subscription was charged twice. Please refund the duplicate payment."},
     {"id": "T-102", "state": "I forgot my password and need help signing in."}
@@ -46,6 +46,6 @@ Sol and Nox use their published `question_row` and `predict_rows` path, the same
 }
 ```
 
-Batch responses replace top-level `answers` with ordered `results: [{id, answers, usage}, ...]`. Context order and shared-question order are retained. Top-level `usage` sums all pairs; `timing` also reports `contexts`, `questions` and `decisions`. A row can expand to show the original probabilities. Score is an expected ordinal index; Noul is P(Yes), not an independent confidence estimate.
+Submit this payload to `POST /v1/decision/batches`. Batch responses replace top-level `answers` with ordered `results: [{id, answers, usage}, ...]`. Context order and shared-question order are retained. Top-level `usage` sums all pairs. Studio's internal response also reports `contexts`, `questions`, and `decisions` in `timing`. A row can expand to show the original probabilities. Score is an expected ordinal index; Noul is P(Yes), not an independent confidence estimate.
 
 The worker admits every complete context/question input before its first forward. Any overflow rejects the whole request: no truncation or partial result. Admitted pairs are flattened into one predictor call with physical batches of up to eight. This is actual GPU batching, not browser-side request fanout or shared-state caching. The native numerical engine, weights, candidate order and published temperatures remain unchanged.

app.py

@@ -1,23 +1,76 @@
 """Same-origin Studio: local native mode or an outbound-worker CPU gateway."""
 import asyncio
+import ipaddress
 import json
 import logging
 import os
 import time
+from contextlib import asynccontextmanager
 from pathlib import Path
+
 from fastapi import FastAPI, HTTPException, Request
-from fastapi.responses import JSONResponse
+from fastapi.responses import JSONResponse, StreamingResponse
 from fastapi.staticfiles import StaticFiles
 from starlette.concurrency import run_in_threadpool
+
 from contract import MODEL, to_records
-from engine import DEFAULT_MANIFEST, Engine, Unavailable, Busy
+from engine import Busy, Engine, Unavailable
 from relay import Relay, RelayError
-from systemone_api import arrange_models, public_models, resolve_model, sdk_response
+from systemone_api import (
+    arrange_models,
+    public_models,
+    resolve_canonical_model,
+    resolve_model,
+    public_response,
+    sdk_response,
+)
+from tetris_arena import (
+    ArenaQuotaError,
+    ArenaValidationError,
+    HTTPDecisionAdapter,
+    RaceManager,
+    encode_sse,
+)
 
 ROOT = Path(__file__).resolve().parent
 logger = logging.getLogger("decision.studio")
 
 
+def trusted_proxy_networks(value: str):
+    if not value.strip():
+        return ()
+    try:
+        return tuple(
+            ipaddress.ip_network(part.strip(), strict=False)
+            for part in value.split(",")
+        )
+    except ValueError as exc:
+        raise ValueError("TETRIS_TRUSTED_PROXY_CIDRS must contain IP CIDRs") from exc
+
+
+def client_identity(request: Request, trusted_proxies=()) -> str:
+    """Use X-Forwarded-For only when every traversed hop is trusted."""
+    peer = request.client.host if request.client else ""
+    try:
+        current = ipaddress.ip_address(peer)
+    except ValueError:
+        return "unknown"
+    header = request.headers.get("x-forwarded-for", "")
+    if not header or len(header) > 1024 or not trusted_proxies:
+        return str(current)
+    try:
+        hops = [ipaddress.ip_address(part.strip()) for part in header.split(",")]
+    except ValueError:
+        return str(current)
+    if not 1 <= len(hops) <= 16:
+        return str(current)
+    for hop in reversed(hops):
+        if not any(current in network for network in trusted_proxies):
+            break
+        current = hop
+    return str(current)
+
+
 def unique_object(pairs):
     result = {}
     for key, value in pairs:
@@ -51,7 +104,16 @@ async def read_input(request):
     return payload, records
 
 
-def create_app(mode=None, *, native_engine=None, relay=None, registry=None, relays=None):
+def create_app(
+    mode=None,
+    *,
+    native_engine=None,
+    relay=None,
+    registry=None,
+    relays=None,
+    tetris_adapter=None,
+    tetris_manager=None,
+):
     mode = mode or os.getenv("DECISION_BACKEND", "native")
     if mode not in {"native", "pull_queue"}:
         raise ValueError("DECISION_BACKEND must be native or pull_queue")
@@ -60,7 +122,32 @@ def create_app(mode=None, *, native_engine=None, relay=None, registry=None, rela
         registry = [{'id': MODEL, 'label': 'Kai', 'version': '1.0', 'manifest_sha256': relay.manifest}]
     registry = arrange_models(model_registry(registry))
     default_model = next(iter(registry))
-    api = FastAPI(title="Decision Studio", version="0.6.0", docs_url="/api/docs", redoc_url=None)
+    trusted_proxies = trusted_proxy_networks(
+        os.getenv("TETRIS_TRUSTED_PROXY_CIDRS", "")
+    )
+    owns_tetris_manager = tetris_manager is None
+    owns_tetris_adapter = owns_tetris_manager and tetris_adapter is None
+    if tetris_manager is None:
+        tetris_adapter = tetris_adapter or HTTPDecisionAdapter.from_environment()
+        tetris_manager = RaceManager.from_environment(tetris_adapter)
+
+    @asynccontextmanager
+    async def lifespan(_api):
+        yield
+        if owns_tetris_manager:
+            try:
+                await tetris_manager.aclose()
+            finally:
+                if owns_tetris_adapter:
+                    await tetris_adapter.close()
+
+    api = FastAPI(
+        title="Decision Studio",
+        version="0.6.0",
+        docs_url="/api/docs",
+        redoc_url=None,
+        lifespan=lifespan,
+    )
     api.state.engine = native_engine or Engine()
     if mode == "native" and (len(registry) != 1 or api.state.engine.model != MODEL
             or api.state.engine.manifest != registry[MODEL]['manifest_sha256']):
@@ -79,14 +166,27 @@ def create_app(mode=None, *, native_engine=None, relay=None, registry=None, rela
     api.state.relay = relays.get(MODEL)  # backward-compatible default for local tooling
     api.state.registry = registry
 
+    api.state.tetris = tetris_manager
+
     def select(model):
         if not isinstance(model, str) or model not in registry:
             raise HTTPException(422, "This model is not available in this Studio")
         return relays.get(model)
 
-    async def input_for(request):
-        payload = await read_json(request)
-        model = resolve_model(payload.get('model', default_model) if isinstance(payload, dict) else default_model, registry)
+    async def input_for(request, *, public_contract=None):
+        payload = await read_json(
+            request, limit=2 * 1024 * 1024 if public_contract == 'batch' else 256 * 1024
+        )
+        if public_contract is not None:
+            expected = {'model', 'questions', 'states' if public_contract == 'batch' else 'state'}
+            if not isinstance(payload, dict) or set(payload) != expected:
+                raise HTTPException(422, f"Provide exactly {', '.join(sorted(expected))}.")
+        requested_model = payload.get('model') if isinstance(payload, dict) else None
+        model = (
+            resolve_canonical_model(requested_model, registry)
+            if public_contract is not None
+            else resolve_model(requested_model or default_model, registry)
+        )
         selected = select(model)
         if isinstance(payload, dict):
             payload = dict(payload, model=model)
@@ -94,7 +194,7 @@ def create_app(mode=None, *, native_engine=None, relay=None, registry=None, rela
             records = to_records(payload, model=model)
         except (ValueError, TypeError, UnicodeError, RecursionError) as exc:
             raise HTTPException(422, str(exc)) from None
-        return payload, records, selected
+        return payload, records, selected, registry[model]['repo_id']
 
     @api.exception_handler(RelayError)
     async def relay_error(request, exc):
@@ -110,14 +210,100 @@ def create_app(mode=None, *, native_engine=None, relay=None, registry=None, rela
     def examples():
         return json.loads((ROOT / "examples.json").read_text())
 
+    @api.get("/api/tetris/config")
+    def tetris_config():
+        # Credentials and upstream URLs intentionally never enter this response.
+        return api.state.tetris.public_config()
+
+    @api.post("/api/tetris/races", status_code=201)
+    async def create_tetris_race(request: Request):
+        payload = await read_json(request)
+        try:
+            race = await api.state.tetris.create(
+                payload,
+                client_id=client_identity(request, trusted_proxies),
+            )
+        except ArenaValidationError as exc:
+            headers = (
+                {"Retry-After": str(exc.retry_after)}
+                if isinstance(exc, ArenaQuotaError)
+                else None
+            )
+            raise HTTPException(exc.status_code, str(exc), headers=headers) from None
+        return {
+            "id": race.id,
+            "status": race.status,
+            "events_url": f"/api/tetris/races/{race.id}/events",
+            "result_url": f"/api/tetris/races/{race.id}",
+        }
+
+    def get_tetris_race(race_id):
+        try:
+            return api.state.tetris.get(race_id)
+        except KeyError:
+            raise HTTPException(404, "Race not found") from None
+
+    @api.get("/api/tetris/races/{race_id}")
+    async def tetris_race(race_id: str):
+        return get_tetris_race(race_id).snapshot()
+
+    @api.get("/api/tetris/races/{race_id}/trace")
+    async def tetris_race_trace(race_id: str):
+        return get_tetris_race(race_id).snapshot(include_traces=True)
+
+    @api.get("/api/tetris/races/{race_id}/events")
+    async def tetris_race_events(race_id: str, request: Request, after: int = 0):
+        race = get_tetris_race(race_id)
+        header_cursor = request.headers.get("last-event-id")
+        if header_cursor:
+            try:
+                after = max(after, int(header_cursor))
+            except ValueError:
+                raise HTTPException(400, "Last-Event-ID must be an integer") from None
+        if after < 0:
+            raise HTTPException(400, "after must not be negative")
+
+        async def stream():
+            async for event in race.iter_events(after):
+                yield encode_sse(event)
+
+        return StreamingResponse(
+            stream(),
+            media_type="text/event-stream",
+            headers={
+                "Cache-Control": "no-store",
+                "Connection": "keep-alive",
+                "X-Accel-Buffering": "no",
+            },
+        )
+
+    @api.delete("/api/tetris/races/{race_id}", status_code=204)
+    async def cancel_tetris_race(race_id: str):
+        try:
+            await api.state.tetris.cancel(race_id)
+        except KeyError:
+            raise HTTPException(404, "Race not found") from None
+
     @api.get("/v1/models")
     def models():
-        return {"default": default_model, "models": public_models(registry), "limits": {"request_bytes": 256 * 1024, "expanded_input_bytes": 16 * 1024 * 1024, "questions": None, "contexts": None, "active_requests_per_model": 8, "gpu_microbatch": 8, "synchronous_wait_seconds": 45}}
+        return {"default": registry[default_model]['repo_id'], "models": public_models(registry), "limits": {"request_bytes": 256 * 1024, "expanded_input_bytes": 16 * 1024 * 1024, "questions": None, "contexts": None, "active_requests_per_model": 8, "gpu_microbatch": 8, "synchronous_wait_seconds": 45}}
 
     @api.post("/v1/systemone")
+    async def evaluate_systemone(request: Request):
+        return await evaluate(request, public_contract='single')
+
+    @api.post("/v1/decision/batches")
+    async def evaluate_decision_batches(request: Request):
+        return await evaluate(request, public_contract='batch')
+
     @api.post("/api/evaluate")
-    async def evaluate(request: Request):
-        payload, records, selected = await input_for(request)
+    async def evaluate_studio(request: Request):
+        return await evaluate(request, public_contract=None)
+
+    async def evaluate(request: Request, *, public_contract: str | None):
+        payload, records, selected, public_model = await input_for(
+            request, public_contract=public_contract
+        )
         if selected:
             job = await selected.submit(payload, keep_until_read=True)
             deadline = time.monotonic() + 45
@@ -126,7 +312,10 @@ def create_app(mode=None, *, native_engine=None, relay=None, registry=None, rela
                     remaining = deadline - time.monotonic()
                     current = await selected.wait(job["id"], max(0.0, min(0.25, remaining)))
                     if current["status"] == "succeeded":
-                        return sdk_response(current["result"])
+                        if public_contract is not None:
+                            return public_response(current['result'], public_model=public_model,
+                                                   batch=public_contract == 'batch')
+                        return sdk_response(current['result'])
                     if current["status"] not in Relay.ACTIVE:
                         raise HTTPException(503, current.get("detail", "The request did not finish"))
                     if await request.is_disconnected():
@@ -135,7 +324,11 @@ def create_app(mode=None, *, native_engine=None, relay=None, registry=None, rela
             finally:
                 await selected.release(job["id"])
         try:
-            return sdk_response(await run_in_threadpool(api.state.engine.evaluate, payload, records))
+            result = await run_in_threadpool(api.state.engine.evaluate, payload, records)
+            if public_contract is not None:
+                return public_response(result, public_model=public_model,
+                                       batch=public_contract == 'batch')
+            return sdk_response(result)
         except Unavailable as exc:
             raise HTTPException(503, str(exc)) from None
         except Busy as exc:
@@ -152,7 +345,7 @@ def create_app(mode=None, *, native_engine=None, relay=None, registry=None, rela
     if relays:
         @api.post("/api/jobs", status_code=202)
         async def submit(request: Request):
-            payload, _, selected = await input_for(request)
+            payload, _, selected, _ = await input_for(request)
             return await selected.submit(payload)
 
         @api.get("/api/jobs/{job_id}")

contract.py

@@ -5,6 +5,8 @@ import math
 MODEL = "decision-nano-preview"
 MAX_EXPANDED_INPUT_BYTES = 16 * 1024 * 1024
 MAX_REQUEST_BYTES = 256 * 1024
+MAX_BATCH_REQUEST_BYTES = 2 * 1024 * 1024
+MAX_BATCH_DECISIONS = 1024
 
 
 def content(value, label):
@@ -107,8 +109,9 @@ def contexts(body, *, model=MODEL):
         raise ValueError("Provide exactly one of state or states")
     if body.get("model", MODEL) != model:
         raise ValueError("Request model does not match the selected model")
-    if len(json.dumps(body, ensure_ascii=False, separators=(",", ":"), allow_nan=False).encode("utf-8")) > MAX_REQUEST_BYTES:
-        raise ValueError("Request exceeds 256 KiB; no field is truncated")
+    limit = MAX_BATCH_REQUEST_BYTES if "states" in body else MAX_REQUEST_BYTES
+    if len(json.dumps(body, ensure_ascii=False, separators=(",", ":"), allow_nan=False).encode("utf-8")) > limit:
+        raise ValueError("Request exceeds the endpoint byte limit; no field is truncated")
     questions = body.get("questions")
     if not isinstance(questions, dict) or not questions:
         raise ValueError("Provide at least one named question")
@@ -119,6 +122,8 @@ def contexts(body, *, model=MODEL):
     states = body["states"]
     if not isinstance(states, list) or not states:
         raise ValueError("Provide at least one context")
+    if len(states) > MAX_BATCH_DECISIONS or len(questions) > MAX_BATCH_DECISIONS or len(states) * len(questions) > MAX_BATCH_DECISIONS:
+        raise ValueError("A batch may contain at most 1024 states, questions, and decisions")
     result, seen = [], set()
     for item in states:
         if not isinstance(item, dict) or set(item) != {"id", "state"}:

model_registry.py

@@ -53,7 +53,13 @@ def model_registry(value=None):
                     or any(not isinstance(x, str) or not 1 <= len(x) <= 128 for x in ids)
                     or len(set(ids)) != len(ids) or item['default_example_id'] not in ids):
                 raise ValueError('Invalid example allowlist/default')
-        result[item['id']] = dict(item, complete_input_tokens=cap)
+        # The queue uses the short ID internally, but public SystemOne traffic
+        # is identified exclusively by the immutable Hub repository ID.
+        result[item['id']] = dict(
+            item,
+            repo_id=profile['repo_id'],
+            complete_input_tokens=cap,
+        )
     if MODEL not in result:
         raise ValueError('Retain the existing Kai wire alias as the default')
     return result

requirements.txt

@@ -1,2 +1,3 @@
 fastapi==0.115.12
+httpx==0.28.1
 uvicorn==0.34.2

static/app.js

@@ -109,7 +109,9 @@ async function refreshMenuStatuses() {
 }
 async function loadModels() {
   const result=validateRegistry(await requestJSON('/v1/models',{cache:'no-store'}));
-  models=result.models;selectedModel=result.default;
+  const selected=result.models.find(model=>model.id===result.default);
+  models=result.models.map(model=>({...model,id:model.wire_id,repo_id:model.id}));
+  selectedModel=selected.wire_id;
   modelMenu.identity(modelInfo(),{enabled:false});
 }
 function saveWorkspace() {
@@ -249,7 +251,7 @@ async function requestJSON(url, options = {}) {
   return body;
 }
 async function nativePrediction(payload, current) {
-  return requestJSON('/v1/systemone', {method:'POST', headers:{'Content-Type':'application/json'}, body:JSON.stringify(payload), signal:current.signal});
+  return requestJSON('/api/evaluate', {method:'POST', headers:{'Content-Type':'application/json'}, body:JSON.stringify(payload), signal:current.signal});
 }
 function pollPause(signal) {
   return new Promise((resolve, reject) => {

static/model-menu.js

@@ -3,10 +3,10 @@ const esc = value => String(value).replace(/[&<>"']/g,x=>({'&':'&amp;','<':'&lt;
 export function validateRegistry(result) {
   if(!Array.isArray(result?.models)||!result.models.length||!result.models.some(m=>m.id===result.default))throw Error('Invalid model registry.');
   const text=(v,max)=>typeof v==='string'&&v.trim()&&v.length<=max;
-  const ids=new Set();
+  const ids=new Set(),wireIds=new Set();
   for(const m of result.models){
-    if(!text(m.id,128)||ids.has(m.id)||!text(m.label,64)||!text(m.version,32)||!/^[0-9a-f]{64}$/.test(m.manifest_sha256)||!Number.isInteger(m.complete_input_tokens)||m.complete_input_tokens<1)throw Error('Invalid model identity.');
-    ids.add(m.id);
+    if(!text(m.id,128)||!text(m.wire_id,128)||ids.has(m.id)||wireIds.has(m.wire_id)||!text(m.label,64)||!text(m.version,32)||!/^[0-9a-f]{64}$/.test(m.manifest_sha256)||!Number.isInteger(m.complete_input_tokens)||m.complete_input_tokens<1)throw Error('Invalid model identity.');
+    ids.add(m.id);wireIds.add(m.wire_id);
     if(m.description!==undefined&&!text(m.description,240)||m.parameter_label!==undefined&&!text(m.parameter_label,32))throw Error('Invalid model description.');
     if(m.example_ids!==undefined&&(!Array.isArray(m.example_ids)||!m.example_ids.length||m.example_ids.some(x=>!text(x,128))||new Set(m.example_ids).size!==m.example_ids.length))throw Error('Invalid model examples.');
     if(m.default_example_id!==undefined&&!text(m.default_example_id,128))throw Error('Invalid default example.');

static/tetris/app.js

@@ -0,0 +1,460 @@
+const elements = {
+  leftModel: document.querySelector('#left-model'),
+  rightModel: document.querySelector('#right-model'),
+  raceMode: document.querySelector('#race-mode'),
+  customWrap: document.querySelector('#custom-wrap'),
+  customSteps: document.querySelector('#custom-steps'),
+  seed: document.querySelector('#seed'),
+  start: document.querySelector('#start'),
+  status: document.querySelector('#status'),
+  summary: document.querySelector('#pk-summary'),
+  summaryLabel: document.querySelector('#summary-label'),
+  summaryLeft: document.querySelector('#summary-left'),
+  summaryRight: document.querySelector('#summary-right'),
+  summarySpeed: document.querySelector('#summary-speed'),
+  summaryScore: document.querySelector('#summary-score'),
+  closeSummary: document.querySelector('#close-summary'),
+}
+
+const views = Object.fromEntries(
+  ['left', 'right'].map((side) => {
+    const root = document.querySelector(`[data-side="${side}"]`)
+    const board = root.querySelector('[data-board]')
+    const cells = Array.from({ length: 200 }, () => {
+      const cell = document.createElement('span')
+      cell.className = 'cell'
+      cell.dataset.piece = '.'
+      board.append(cell)
+      return cell
+    })
+    return [side, {
+      root,
+      name: root.querySelector('[data-name]'),
+      board,
+      cells,
+      latency: root.querySelector('[data-latency]'),
+      score: root.querySelector('[data-score]'),
+      lines: root.querySelector('[data-lines]'),
+      pieces: root.querySelector('[data-pieces]'),
+      finish: root.querySelector('[data-finish]'),
+      resultScore: root.querySelector('[data-result-score]'),
+      resultLines: root.querySelector('[data-result-lines]'),
+      resultPieces: root.querySelector('[data-result-pieces]'),
+    }]
+  }),
+)
+
+let config = null
+let raceId = null
+let events = null
+let rendering = false
+let lifecycle = 'idle'
+let operation = 0
+let createController = null
+const latest = { left: null, right: null }
+const seenSteps = { left: 0, right: 0 }
+
+function setStatus(message) {
+  elements.status.textContent = message
+}
+
+function addOption(select, competitor) {
+  const option = document.createElement('option')
+  option.value = competitor.id
+  option.textContent = competitor.option_label
+  select.append(option)
+}
+
+function selectedCompetitor(side) {
+  const value = side === 'left' ? elements.leftModel.value : elements.rightModel.value
+  return config?.competitors.find((competitor) => competitor.id === value) ?? null
+}
+
+function updateNames() {
+  for (const side of ['left', 'right']) {
+    views[side].name.textContent = selectedCompetitor(side)?.display_name ?? 'Unavailable'
+  }
+}
+
+function renderControls() {
+  const locked = lifecycle !== 'idle'
+  for (const control of [
+    elements.leftModel,
+    elements.rightModel,
+    elements.raceMode,
+    elements.customSteps,
+    elements.seed,
+  ]) control.disabled = locked
+  const hasCompetitor = Boolean(config?.competitors.some((item) => item.ready))
+  elements.start.disabled = !hasCompetitor || lifecycle === 'starting' || lifecycle === 'stopping'
+  elements.start.textContent = {
+    idle: 'Start race',
+    starting: 'Starting…',
+    running: 'Stop',
+    stopping: 'Stopping…',
+  }[lifecycle]
+}
+
+function setLifecycle(next) {
+  lifecycle = next
+  renderControls()
+}
+
+function clearBoard(side) {
+  for (const cell of views[side].cells) cell.dataset.piece = '.'
+}
+
+function resetView() {
+  latest.left = null
+  latest.right = null
+  seenSteps.left = 0
+  seenSteps.right = 0
+  for (const side of ['left', 'right']) {
+    clearBoard(side)
+    views[side].latency.textContent = '— ms'
+    views[side].score.textContent = '0'
+    views[side].lines.textContent = '0'
+    views[side].pieces.textContent = '0'
+    views[side].finish.hidden = true
+  }
+  elements.summary.hidden = true
+  updateNames()
+}
+
+function paint(side, step) {
+  const view = views[side]
+  const game = step.game
+  game.board.forEach((row, y) => {
+    Array.from(row).forEach((piece, x) => {
+      view.cells[(y * 10) + x].dataset.piece = piece
+    })
+  })
+  view.score.textContent = String(game.score)
+  view.lines.textContent = String(game.lines)
+  view.pieces.textContent = String(game.pieces)
+  if (Number.isFinite(step.request_ms)) {
+    view.latency.textContent = `${Math.round(step.request_ms)} ms`
+  }
+  if (step.cleared_rows?.length) {
+    view.board.classList.remove('is-clearing')
+    requestAnimationFrame(() => {
+      view.board.classList.add('is-clearing')
+      setTimeout(() => view.board.classList.remove('is-clearing'), 140)
+    })
+  }
+}
+
+function scheduleRender() {
+  if (rendering) return
+  rendering = true
+  requestAnimationFrame(() => {
+    rendering = false
+    for (const side of ['left', 'right']) {
+      if (latest[side]) paint(side, latest[side])
+      latest[side] = null
+    }
+  })
+}
+
+function showSideResult(side, result) {
+  const view = views[side]
+  view.finish.querySelector('[data-result-status]').textContent = {
+    finished: 'Finished',
+    game_over: 'Game over',
+    guard_reached: 'Limit reached',
+    error: 'Failed',
+    stopped: 'Stopped',
+  }[result.status] ?? 'Incomplete'
+  view.resultScore.textContent = String(result.score)
+  view.resultLines.textContent = String(result.lines)
+  view.resultPieces.textContent = String(result.pieces)
+  view.finish.hidden = false
+}
+
+function winnerName(winner, summary) {
+  if (winner === 'left') return summary.left.display_name
+  if (winner === 'right') return summary.right.display_name
+  return 'Tie'
+}
+
+function comparisonText(comparison, summary, label) {
+  if (comparison.winner === 'unavailable') return 'Not comparable'
+  if (comparison.winner === 'tie') return 'Tie'
+  const name = winnerName(comparison.winner, summary)
+  if (comparison.unbounded || comparison.percent == null) return `${name} wins ${label}`
+  const suffix = label === 'speed' ? 'faster' : 'higher'
+  return `${name} · ${comparison.percent.toFixed(1)}% ${suffix}`
+}
+
+function showSummary(summary) {
+  elements.summaryLabel.textContent = summary.status === 'finished'
+    ? 'Final result'
+    : 'Race incomplete'
+  elements.summaryLeft.textContent = summary.left.display_name
+  elements.summaryRight.textContent = summary.right.display_name
+  elements.summarySpeed.textContent = comparisonText(summary.speed, summary, 'speed')
+  elements.summaryScore.textContent = comparisonText(summary.score, summary, 'score')
+  elements.summary.hidden = false
+}
+
+function parseEvent(event) {
+  try {
+    return JSON.parse(event.data)
+  } catch {
+    return null
+  }
+}
+
+function raceStatus(status) {
+  return {
+    finished: 'Race complete.',
+    incomplete: 'Race incomplete. One or both models did not complete.',
+    timed_out: 'Race timed out before both models completed.',
+    cancelled: 'Race stopped before completion.',
+    error: 'The race server could not complete this race.',
+  }[status] ?? 'Race ended before completion.'
+}
+
+function finishRace(status, summary, stream) {
+  stream.close()
+  if (events === stream) events = null
+  raceId = null
+  setLifecycle('idle')
+  setStatus(raceStatus(status))
+  if (summary) {
+    for (const side of ['left', 'right']) {
+      if (summary[side]) showSideResult(side, summary[side])
+    }
+    showSummary(summary)
+  }
+}
+
+function applySnapshot(snapshot) {
+  for (const side of ['left', 'right']) {
+    const state = snapshot.states?.[side]
+    if (state?.game && state.step >= seenSteps[side]) {
+      seenSteps[side] = state.step
+      latest[side] = state
+      scheduleRender()
+    }
+    const result = snapshot.results?.[side]
+    if (result) showSideResult(side, result)
+  }
+}
+
+function connectEventStream(url, resultUrl, expectedOperation, expectedRaceId) {
+  events?.close()
+  const stream = new EventSource(url)
+  events = stream
+  let recovering = false
+  const current = () => expectedOperation === operation && expectedRaceId === raceId
+  async function recoverSnapshot() {
+    if (!current() || recovering) return
+    recovering = true
+    try {
+      const response = await fetch(resultUrl, { headers: { Accept: 'application/json' } })
+      if (!current()) return
+      if (response.status === 404) {
+        finishRace('error', null, stream)
+        setStatus('The race result is no longer available. Start a new race.')
+        return
+      }
+      if (!response.ok) return
+      const snapshot = await response.json()
+      if (!current() || snapshot.id !== expectedRaceId) return
+      applySnapshot(snapshot)
+      if (!['created', 'running'].includes(snapshot.status)) {
+        finishRace(snapshot.status, snapshot.summary, stream)
+      }
+    } catch {
+      // EventSource keeps retrying transient failures within the server lease.
+    } finally {
+      recovering = false
+    }
+  }
+  stream.addEventListener('side.step', (event) => {
+    if (!current()) return
+    const data = parseEvent(event)
+    if (!data || !views[data.side] || data.step <= seenSteps[data.side]) return
+    seenSteps[data.side] = data.step
+    latest[data.side] = data
+    scheduleRender()
+  })
+  stream.addEventListener('side.finished', (event) => {
+    if (!current()) return
+    const data = parseEvent(event)
+    if (data && views[data.side]) showSideResult(data.side, data.result)
+  })
+  stream.addEventListener('side.error', (event) => {
+    if (!current()) return
+    const data = parseEvent(event)
+    if (data) setStatus(`${data.side === 'left' ? 'Left' : 'Right'}: ${data.message}`)
+  })
+  stream.addEventListener('race.finished', (event) => {
+    if (!current()) return
+    const summary = parseEvent(event)
+    if (summary) finishRace(summary.status, summary, stream)
+    else void recoverSnapshot()
+  })
+  stream.addEventListener('open', () => {
+    if (current()) void recoverSnapshot()
+  })
+  stream.addEventListener('error', () => {
+    if (current() && lifecycle === 'running') {
+      setStatus('Reconnecting to the live race…')
+      void recoverSnapshot()
+    }
+  })
+}
+
+function raceSettings() {
+  const selected = elements.raceMode.value
+  if (selected === 'first_failure') {
+    return { mode: 'first_failure', max_steps: null }
+  }
+  const raw = selected === 'custom' ? elements.customSteps.value : selected
+  const maximum = config?.limits.max_steps ?? 120
+  const maxSteps = Math.min(maximum, Math.max(1, Number.parseInt(raw, 10) || 40))
+  if (selected === 'custom') elements.customSteps.value = String(maxSteps)
+  return { mode: 'steps', max_steps: maxSteps }
+}
+
+async function startRace() {
+  if (lifecycle !== 'idle') return
+  const expectedOperation = ++operation
+  createController = new AbortController()
+  resetView()
+  setLifecycle('starting')
+  setStatus('Starting both model runners…')
+  const settings = raceSettings()
+  let response
+  try {
+    response = await fetch('/api/tetris/races', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      signal: createController.signal,
+      body: JSON.stringify({
+        left: elements.leftModel.value,
+        right: elements.rightModel.value,
+        seed: elements.seed.value || '42',
+        ...settings,
+      }),
+    })
+  } catch (error) {
+    if (expectedOperation !== operation) return
+    createController = null
+    setLifecycle('idle')
+    if (error?.name === 'AbortError') return
+    setStatus('The race server is unavailable.')
+    return
+  }
+  createController = null
+  if (!response.ok) {
+    const detail = await response.json().catch(() => ({}))
+    if (expectedOperation !== operation) return
+    setLifecycle('idle')
+    setStatus(detail.detail || 'The race could not start.')
+    return
+  }
+  const race = await response.json().catch(() => null)
+  if (!race?.id || !race?.events_url || !race?.result_url) {
+    if (expectedOperation !== operation) return
+    setLifecycle('idle')
+    setStatus('The race server returned an invalid response.')
+    return
+  }
+  if (expectedOperation !== operation) {
+    await fetch(`/api/tetris/races/${encodeURIComponent(race.id)}`, {
+      method: 'DELETE',
+      keepalive: true,
+    }).catch(() => {})
+    return
+  }
+  raceId = race.id
+  setLifecycle('running')
+  setStatus('Race in progress. Each side is running independently.')
+  connectEventStream(race.events_url, race.result_url, expectedOperation, race.id)
+}
+
+async function stopRace() {
+  if (lifecycle !== 'running' || !raceId) return
+  const expectedOperation = ++operation
+  const current = raceId
+  raceId = null
+  events?.close()
+  events = null
+  setLifecycle('stopping')
+  await fetch(`/api/tetris/races/${encodeURIComponent(current)}`, {
+    method: 'DELETE',
+  }).catch(() => {})
+  if (expectedOperation !== operation) return
+  setLifecycle('idle')
+  setStatus('Race stopped.')
+}
+
+async function loadConfig() {
+  try {
+    const response = await fetch('/api/tetris/config', { headers: { Accept: 'application/json' } })
+    if (!response.ok) throw new Error('config unavailable')
+    config = await response.json()
+  } catch {
+    setStatus('The arena configuration is unavailable.')
+    return
+  }
+  const competitors = config.competitors.filter((competitor) => competitor.ready)
+  const maximum = config.limits.max_steps
+  elements.customSteps.max = String(maximum)
+  for (const option of elements.raceMode.options) {
+    if (/^\d+$/.test(option.value)) option.disabled = Number(option.value) > maximum
+  }
+  const defaultSteps = Math.min(config.defaults.max_steps, maximum)
+  if ([...elements.raceMode.options].some((option) => option.value === String(defaultSteps))) {
+    elements.raceMode.value = String(defaultSteps)
+  } else {
+    elements.raceMode.value = 'custom'
+    elements.customSteps.value = String(defaultSteps)
+    elements.customWrap.hidden = false
+  }
+  for (const competitor of competitors) {
+    addOption(elements.leftModel, competitor)
+    addOption(elements.rightModel, competitor)
+  }
+  const cloud = competitors.find((item) => item.id === 'jev-cloud')
+  const lux = competitors.find((item) => item.id === 'lux')
+  elements.leftModel.value = cloud?.id ?? competitors[0]?.id ?? ''
+  elements.rightModel.value = lux?.id ?? competitors[1]?.id ?? competitors[0]?.id ?? ''
+  renderControls()
+  setStatus(
+    competitors.length > 0
+      ? 'Choose any two configured models.'
+      : 'No Tetris model endpoints are configured on this server.',
+  )
+  resetView()
+}
+
+elements.raceMode.addEventListener('change', () => {
+  elements.customWrap.hidden = elements.raceMode.value !== 'custom'
+})
+elements.leftModel.addEventListener('change', updateNames)
+elements.rightModel.addEventListener('change', updateNames)
+elements.start.addEventListener('click', () => {
+  if (lifecycle === 'running') void stopRace()
+  else if (lifecycle === 'idle') void startRace()
+})
+elements.closeSummary.addEventListener('click', () => { elements.summary.hidden = true })
+elements.summary.addEventListener('click', (event) => {
+  if (event.target === elements.summary) elements.summary.hidden = true
+})
+window.addEventListener('beforeunload', () => {
+  operation += 1
+  createController?.abort()
+  events?.close()
+  if (raceId) {
+    void fetch(`/api/tetris/races/${encodeURIComponent(raceId)}`, {
+      method: 'DELETE',
+      keepalive: true,
+    }).catch(() => {})
+  }
+})
+
+void loadConfig()

static/tetris/index.html

@@ -0,0 +1,138 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta
+      name="description"
+      content="A server-authoritative head-to-head Tetris race for Decision 1.0 models."
+    />
+    <title>Decision 1.0 · Tetris Race</title>
+    <link rel="stylesheet" href="styles.css" />
+  </head>
+  <body>
+    <main class="page">
+      <header class="toolbar">
+        <a class="wordmark" href="/tetris/" aria-label="Decision 1.0 Tetris Race">
+          <span class="wordmark__eyebrow">Decision 1.0 playground</span>
+          <strong>Tetris Race</strong>
+        </a>
+
+        <div class="controls" aria-label="Race controls">
+          <label class="control control--model">
+            <span>Left model</span>
+            <select id="left-model" aria-label="Left model"></select>
+          </label>
+          <span class="versus" aria-hidden="true">VS</span>
+          <label class="control control--model">
+            <span>Right model</span>
+            <select id="right-model" aria-label="Right model"></select>
+          </label>
+          <label class="control control--steps">
+            <span>Steps</span>
+            <select id="race-mode" aria-label="Race length">
+              <option value="20">20</option>
+              <option value="40" selected>40</option>
+              <option value="80">80</option>
+              <option value="120">120</option>
+              <option value="custom">Custom</option>
+              <option value="first_failure">Until first failure</option>
+            </select>
+          </label>
+          <label class="control control--custom" id="custom-wrap" hidden>
+            <span>Custom</span>
+            <input id="custom-steps" type="number" min="1" max="120" value="40" />
+          </label>
+          <label class="control control--seed">
+            <span>Seed</span>
+            <input id="seed" value="42" maxlength="128" />
+          </label>
+          <button id="start" class="start" type="button" disabled>Start race</button>
+        </div>
+      </header>
+
+      <section class="arena" aria-live="polite">
+        <article class="player" data-side="left">
+          <header class="player__header">
+            <h2 data-name>Left model</h2>
+            <output data-latency>— ms</output>
+          </header>
+          <div class="board-shell">
+            <div class="board" data-board aria-label="Left Tetris board"></div>
+            <div class="finish-card" data-finish hidden>
+              <span data-result-status>Result</span>
+              <strong data-result-score>0</strong>
+              <small class="finish-card__score-label">Score</small>
+              <div class="finish-card__metrics">
+                <p><b data-result-lines>0</b><small>Lines</small></p>
+                <p><b data-result-pieces>0</b><small>Pieces</small></p>
+              </div>
+            </div>
+          </div>
+          <div class="metrics">
+            <p><span>Score</span><strong data-score>0</strong></p>
+            <p><span>Lines</span><strong data-lines>0</strong></p>
+            <p><span>Pieces</span><strong data-pieces>0</strong></p>
+          </div>
+        </article>
+
+        <div class="arena__divider" aria-hidden="true"><span>PK</span></div>
+
+        <article class="player" data-side="right">
+          <header class="player__header">
+            <h2 data-name>Right model</h2>
+            <output data-latency>— ms</output>
+          </header>
+          <div class="board-shell">
+            <div class="board" data-board aria-label="Right Tetris board"></div>
+            <div class="finish-card" data-finish hidden>
+              <span data-result-status>Result</span>
+              <strong data-result-score>0</strong>
+              <small class="finish-card__score-label">Score</small>
+              <div class="finish-card__metrics">
+                <p><b data-result-lines>0</b><small>Lines</small></p>
+                <p><b data-result-pieces>0</b><small>Pieces</small></p>
+              </div>
+            </div>
+          </div>
+          <div class="metrics">
+            <p><span>Score</span><strong data-score>0</strong></p>
+            <p><span>Lines</span><strong data-lines>0</strong></p>
+            <p><span>Pieces</span><strong data-pieces>0</strong></p>
+          </div>
+        </article>
+
+        <section class="pk-summary" id="pk-summary" hidden aria-labelledby="pk-title">
+          <div class="pk-summary__card">
+            <button id="close-summary" class="summary-close" aria-label="Close result">×</button>
+            <span class="pk-summary__label" id="summary-label">Final result</span>
+            <h2 id="pk-title">PK</h2>
+            <div class="pk-summary__models">
+              <strong id="summary-left">Left</strong>
+              <span>vs</span>
+              <strong id="summary-right">Right</strong>
+            </div>
+            <div class="pk-summary__comparisons">
+              <p><span>Speed</span><strong id="summary-speed">—</strong></p>
+              <p><span>Score</span><strong id="summary-score">—</strong></p>
+            </div>
+          </div>
+        </section>
+      </section>
+
+      <p class="status" id="status" role="status">Configure two models to begin.</p>
+
+      <footer class="footer">
+        <a
+          href="https://huggingface.co/collections/llm-semantic-router/decision-10"
+          target="_blank"
+          rel="noopener noreferrer"
+        >
+          <img src="huggingface-logo.svg" width="62" height="58" alt="Hugging Face" />
+          <span><strong>Decision 1.0</strong>Open Decision Foundation Models</span>
+        </a>
+      </footer>
+    </main>
+    <script type="module" src="app.js"></script>
+  </body>
+</html>

static/tetris/styles.css

@@ -0,0 +1,486 @@
+:root {
+  color-scheme: dark;
+  --page: #05070b;
+  --surface: rgba(15, 19, 27, 0.88);
+  --line: rgba(255, 255, 255, 0.11);
+  --muted: #8993a3;
+  --ink: #f7f9fc;
+  --accent: #63c5ff;
+  --board-width: clamp(250px, min(23vw, 36vh), 360px);
+  font-family: Inter, ui-sans-serif, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+}
+
+* { box-sizing: border-box; }
+
+html,
+body { min-width: 320px; min-height: 100%; }
+
+body {
+  margin: 0;
+  color: var(--ink);
+  background:
+    radial-gradient(circle at 18% 12%, rgba(35, 132, 255, 0.12), transparent 32rem),
+    radial-gradient(circle at 82% 14%, rgba(194, 78, 255, 0.09), transparent 30rem),
+    linear-gradient(rgba(255, 255, 255, 0.016) 1px, transparent 1px),
+    linear-gradient(90deg, rgba(255, 255, 255, 0.016) 1px, transparent 1px),
+    #05070b;
+  background-size: auto, auto, 36px 36px, 36px 36px, auto;
+  -webkit-font-smoothing: antialiased;
+}
+
+button,
+input,
+select { font: inherit; }
+
+[hidden] { display: none !important; }
+
+.page {
+  display: grid;
+  min-height: 100dvh;
+  grid-template-rows: auto minmax(0, 1fr) auto auto;
+  gap: clamp(0.75rem, 1.6vh, 1.35rem);
+  width: min(1320px, 100%);
+  margin: 0 auto;
+  padding: clamp(0.8rem, 1.7vw, 1.5rem) clamp(1rem, 3vw, 2.8rem) 1.25rem;
+}
+
+.toolbar {
+  position: relative;
+  z-index: 10;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 1.5rem;
+  min-height: 78px;
+  padding: 0.8rem 0.95rem 0.8rem 1.25rem;
+  border: 1px solid var(--line);
+  border-radius: 18px;
+  background: rgba(12, 16, 23, 0.78);
+  box-shadow: 0 20px 70px rgba(0, 0, 0, 0.32), inset 0 1px rgba(255, 255, 255, 0.045);
+  backdrop-filter: blur(22px);
+}
+
+.wordmark {
+  min-width: 175px;
+  color: inherit;
+  text-decoration: none;
+}
+
+.wordmark__eyebrow {
+  display: block;
+  margin-bottom: 0.24rem;
+  color: #7f8a9b;
+  font-size: 0.61rem;
+  font-weight: 750;
+  letter-spacing: 0.14em;
+  text-transform: uppercase;
+}
+
+.wordmark strong {
+  display: block;
+  font-size: clamp(1.45rem, 2.2vw, 1.9rem);
+  letter-spacing: -0.055em;
+  line-height: 1;
+}
+
+.controls {
+  display: flex;
+  min-width: 0;
+  align-items: end;
+  justify-content: flex-end;
+  gap: 0.42rem;
+}
+
+.control {
+  display: grid;
+  min-width: 0;
+  gap: 0.27rem;
+}
+
+.control > span {
+  padding-left: 0.22rem;
+  color: var(--muted);
+  font-size: 0.55rem;
+  font-weight: 760;
+  letter-spacing: 0.1em;
+  text-transform: uppercase;
+}
+
+.control--model { width: 10.5rem; }
+.control--steps { width: 8.2rem; }
+.control--custom { width: 5rem; }
+.control--seed { width: 4.5rem; }
+
+.control input,
+.control select,
+.start {
+  height: 39px;
+  border-radius: 10px;
+}
+
+.control input,
+.control select {
+  width: 100%;
+  min-width: 0;
+  border: 1px solid rgba(255, 255, 255, 0.13);
+  outline: none;
+  color: #111720;
+  background-color: #f7f9fc;
+  font-size: 0.73rem;
+  font-weight: 650;
+  transition: border-color 150ms ease, box-shadow 150ms ease;
+}
+
+.control select {
+  appearance: none;
+  padding: 0 1.9rem 0 0.68rem;
+  background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='12' height='8' viewBox='0 0 12 8'%3E%3Cpath d='m1.5 1.5 4.5 4.5 4.5-4.5' fill='none' stroke='%23323a46' stroke-width='1.5' stroke-linecap='round' stroke-linejoin='round'/%3E%3C/svg%3E");
+  background-position: right 0.7rem center;
+  background-repeat: no-repeat;
+}
+
+.control input { padding: 0 0.62rem; }
+
+.control input:focus,
+.control select:focus {
+  border-color: var(--accent);
+  box-shadow: 0 0 0 3px rgba(99, 197, 255, 0.16);
+}
+
+.versus {
+  display: grid;
+  height: 39px;
+  place-items: center;
+  padding-inline: 0.15rem;
+  color: #687282;
+  font-size: 0.56rem;
+  font-weight: 850;
+}
+
+.start {
+  min-width: 88px;
+  padding: 0 0.85rem;
+  border: 0;
+  color: #04121c;
+  background: linear-gradient(145deg, #9cdbff, #48b9fa 55%, #258ed0);
+  box-shadow: 0 10px 26px rgba(48, 166, 235, 0.22);
+  font-size: 0.73rem;
+  font-weight: 800;
+  cursor: pointer;
+  transition: transform 150ms ease, opacity 150ms ease;
+}
+
+.start:hover:not(:disabled) { transform: translateY(-1px); }
+.start:active:not(:disabled) { transform: translateY(0) scale(0.98); }
+.start:disabled { cursor: not-allowed; opacity: 0.38; }
+
+.arena {
+  position: relative;
+  display: grid;
+  grid-template-columns: var(--board-width) clamp(42px, 6vw, 78px) var(--board-width);
+  align-items: center;
+  justify-content: center;
+  gap: clamp(0.75rem, 2vw, 1.75rem);
+  min-height: 0;
+}
+
+.player {
+  width: var(--board-width);
+  min-width: 0;
+}
+
+.player__header {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) auto;
+  align-items: baseline;
+  gap: 0.75rem;
+  min-height: 39px;
+  padding: 0 0.18rem 0.58rem;
+}
+
+.player__header h2 {
+  overflow: hidden;
+  margin: 0;
+  font-size: clamp(1.17rem, 2vw, 1.65rem);
+  font-weight: 720;
+  letter-spacing: -0.045em;
+  line-height: 1;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.player__header output {
+  color: #a7b1bf;
+  font-size: 0.75rem;
+  font-variant-numeric: tabular-nums;
+  font-weight: 700;
+}
+
+.board-shell {
+  position: relative;
+  padding: 9px;
+  overflow: hidden;
+  border: 1px solid rgba(255, 255, 255, 0.14);
+  border-radius: 14px;
+  background: linear-gradient(145deg, #252c38, #0e1219 42%, #282e38);
+  box-shadow:
+    0 24px 70px rgba(0, 0, 0, 0.45),
+    inset 0 1px rgba(255, 255, 255, 0.12),
+    inset 0 -1px rgba(0, 0, 0, 0.8);
+}
+
+.board-shell::before {
+  position: absolute;
+  z-index: 3;
+  inset: 4px;
+  border: 1px solid rgba(255, 255, 255, 0.07);
+  border-radius: 10px;
+  content: "";
+  pointer-events: none;
+}
+
+.board {
+  display: grid;
+  width: 100%;
+  aspect-ratio: 1 / 2;
+  grid-template-columns: repeat(10, 1fr);
+  grid-template-rows: repeat(20, 1fr);
+  overflow: hidden;
+  border: 1px solid rgba(0, 0, 0, 0.92);
+  background:
+    linear-gradient(rgba(255, 255, 255, 0.027) 1px, transparent 1px),
+    linear-gradient(90deg, rgba(255, 255, 255, 0.027) 1px, transparent 1px),
+    radial-gradient(circle at 50% 8%, #111927, #05070b 62%);
+  background-size: 10% 5%, 10% 5%, auto;
+  box-shadow: inset 0 0 38px rgba(0, 0, 0, 0.66);
+}
+
+.cell {
+  position: relative;
+  min-width: 0;
+  min-height: 0;
+  transition: background-color 80ms linear, box-shadow 80ms linear;
+}
+
+.cell[data-piece]:not([data-piece="."]) {
+  border: 1px solid rgba(0, 0, 0, 0.32);
+  border-radius: 18%;
+  box-shadow:
+    inset 2px 2px 0 rgba(255, 255, 255, 0.38),
+    inset -3px -3px 0 rgba(0, 0, 0, 0.24),
+    0 0 9px color-mix(in srgb, var(--piece-color) 42%, transparent);
+  background:
+    linear-gradient(145deg, rgba(255, 255, 255, 0.25), transparent 35%),
+    linear-gradient(320deg, rgba(0, 0, 0, 0.21), transparent 45%),
+    var(--piece-color);
+}
+
+.cell[data-piece="I"] { --piece-color: #28cce9; }
+.cell[data-piece="O"] { --piece-color: #ffca32; }
+.cell[data-piece="T"] { --piece-color: #a970ff; }
+.cell[data-piece="S"] { --piece-color: #44d79f; }
+.cell[data-piece="Z"] { --piece-color: #ff6070; }
+.cell[data-piece="J"] { --piece-color: #4f82ff; }
+.cell[data-piece="L"] { --piece-color: #ff964d; }
+
+.board.is-clearing { filter: brightness(1.38); }
+
+.metrics {
+  display: grid;
+  grid-template-columns: repeat(3, 1fr);
+  gap: 0.42rem;
+  margin-top: 0.52rem;
+}
+
+.metrics p {
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+  gap: 0.35rem;
+  margin: 0;
+  padding: 0.48rem 0.58rem;
+  border: 1px solid rgba(255, 255, 255, 0.075);
+  border-radius: 9px;
+  background: rgba(255, 255, 255, 0.025);
+}
+
+.metrics span { color: var(--muted); font-size: 0.58rem; text-transform: uppercase; }
+.metrics strong { font-size: 0.78rem; font-variant-numeric: tabular-nums; }
+
+.arena__divider {
+  display: grid;
+  align-self: center;
+  place-items: center;
+  height: 100%;
+}
+
+.arena__divider::before {
+  width: 1px;
+  height: 34%;
+  background: linear-gradient(transparent, rgba(255, 255, 255, 0.14), transparent);
+  content: "";
+}
+
+.arena__divider span {
+  display: grid;
+  width: 42px;
+  height: 42px;
+  place-items: center;
+  margin-block: 0.65rem;
+  border: 1px solid rgba(255, 255, 255, 0.12);
+  border-radius: 50%;
+  color: #b7c0cd;
+  background: #0b0e14;
+  box-shadow: 0 10px 28px rgba(0, 0, 0, 0.4);
+  font-size: 0.67rem;
+  font-weight: 850;
+}
+
+.finish-card {
+  position: absolute;
+  z-index: 4;
+  inset: 9px;
+  display: grid;
+  place-content: center;
+  justify-items: center;
+  background: rgba(4, 7, 11, 0.88);
+  backdrop-filter: blur(11px);
+  animation: finish-in 280ms cubic-bezier(0.2, 0.9, 0.2, 1) both;
+}
+
+.finish-card > span {
+  margin-bottom: 0.28rem;
+  color: #9ca7b7;
+  font-size: 0.68rem;
+  font-weight: 800;
+  letter-spacing: 0.15em;
+  text-transform: uppercase;
+}
+
+.finish-card > strong {
+  font-size: clamp(2.8rem, 6vw, 4.6rem);
+  letter-spacing: -0.08em;
+  line-height: 1;
+}
+
+.finish-card__score-label {
+  margin-top: 0.2rem;
+  color: var(--muted);
+  font-size: 0.6rem;
+  letter-spacing: 0.11em;
+  text-transform: uppercase;
+}
+
+.finish-card__metrics { display: flex; gap: 2rem; margin-top: 1.1rem; }
+.finish-card__metrics p { display: grid; justify-items: center; gap: 0.12rem; margin: 0; }
+.finish-card__metrics b { font-size: 1.25rem; }
+.finish-card__metrics small { color: var(--muted); font-size: 0.63rem; text-transform: uppercase; }
+
+.pk-summary {
+  position: fixed;
+  z-index: 30;
+  inset: 0;
+  display: grid;
+  place-items: center;
+  padding: 1rem;
+  background: rgba(2, 4, 8, 0.72);
+  backdrop-filter: blur(13px);
+}
+
+.pk-summary__card {
+  position: relative;
+  width: min(620px, 94vw);
+  padding: clamp(1.5rem, 4vw, 2.7rem);
+  border: 1px solid rgba(255, 255, 255, 0.15);
+  border-radius: 24px;
+  background:
+    radial-gradient(circle at 50% 0, rgba(84, 184, 255, 0.16), transparent 55%),
+    #0d1119;
+  box-shadow: 0 36px 100px rgba(0, 0, 0, 0.65), inset 0 1px rgba(255, 255, 255, 0.06);
+  text-align: center;
+  animation: summary-in 320ms cubic-bezier(0.18, 0.9, 0.2, 1) both;
+}
+
+.pk-summary__label { color: var(--muted); font-size: 0.66rem; font-weight: 800; letter-spacing: 0.16em; text-transform: uppercase; }
+.pk-summary h2 { margin: 0.35rem 0 0.75rem; font-size: 2.4rem; letter-spacing: -0.08em; }
+.pk-summary__models { display: grid; grid-template-columns: 1fr auto 1fr; align-items: center; gap: 0.8rem; }
+.pk-summary__models strong { overflow: hidden; font-size: clamp(1.1rem, 3vw, 1.55rem); text-overflow: ellipsis; white-space: nowrap; }
+.pk-summary__models span { color: #667182; font-size: 0.7rem; font-weight: 800; text-transform: uppercase; }
+.pk-summary__comparisons { display: grid; grid-template-columns: 1fr 1fr; gap: 0.8rem; margin-top: 1.4rem; }
+.pk-summary__comparisons p { margin: 0; padding: 1rem; border: 1px solid var(--line); border-radius: 14px; background: rgba(255, 255, 255, 0.025); }
+.pk-summary__comparisons span { display: block; margin-bottom: 0.32rem; color: var(--muted); font-size: 0.62rem; font-weight: 800; letter-spacing: 0.12em; text-transform: uppercase; }
+.pk-summary__comparisons strong { display: block; font-size: clamp(1.05rem, 2.6vw, 1.5rem); line-height: 1.15; }
+
+.summary-close {
+  position: absolute;
+  top: 0.8rem;
+  right: 0.9rem;
+  width: 34px;
+  height: 34px;
+  border: 0;
+  border-radius: 50%;
+  color: #b6bfcb;
+  background: rgba(255, 255, 255, 0.06);
+  font-size: 1.25rem;
+  cursor: pointer;
+}
+
+.status { min-height: 1em; margin: 0; color: #747f90; font-size: 0.68rem; text-align: center; }
+
+.footer {
+  display: grid;
+  min-height: clamp(74px, 10vh, 112px);
+  place-items: end center;
+  padding-top: 0.7rem;
+}
+
+.footer a {
+  display: flex;
+  align-items: center;
+  gap: 0.85rem;
+  color: inherit;
+  text-decoration: none;
+}
+
+.footer img { width: 48px; height: auto; filter: drop-shadow(0 8px 18px rgba(255, 183, 0, 0.13)); }
+.footer span { display: grid; gap: 0.14rem; color: #8a95a5; font-size: 0.72rem; }
+.footer strong { color: #eff3f8; font-size: 1.05rem; letter-spacing: -0.025em; }
+
+@keyframes finish-in {
+  from { opacity: 0; transform: scale(0.96); }
+  to { opacity: 1; transform: scale(1); }
+}
+
+@keyframes summary-in {
+  from { opacity: 0; transform: translateY(18px) scale(0.965); }
+  to { opacity: 1; transform: translateY(0) scale(1); }
+}
+
+@media (max-width: 980px) {
+  .toolbar { align-items: flex-start; flex-direction: column; }
+  .controls { width: 100%; flex-wrap: wrap; justify-content: flex-start; }
+  .control--model { flex: 1 1 10rem; }
+  .arena { grid-template-columns: var(--board-width) 35px var(--board-width); gap: 0.5rem; }
+}
+
+@media (max-width: 680px) {
+  :root { --board-width: min(78vw, 330px); }
+  .page { display: block; }
+  .toolbar { margin-bottom: 1.25rem; }
+  .controls { display: grid; grid-template-columns: 1fr 1fr; }
+  .versus { display: none; }
+  .control--model,
+  .control--steps,
+  .control--custom,
+  .control--seed { width: auto; }
+  .start { align-self: end; }
+  .arena { grid-template-columns: 1fr; gap: 1.4rem; }
+  .player { margin-inline: auto; }
+  .arena__divider { display: none; }
+  .status { margin: 1rem 0; }
+  .footer { padding-block: 1.5rem; }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after { scroll-behavior: auto !important; animation-duration: 1ms !important; transition-duration: 1ms !important; }
+}

systemone_api.py

@@ -25,15 +25,30 @@ def resolve_model(value, registry):
     raise HTTPException(422, "This model is not available in this Studio")
 
 
+def resolve_canonical_model(value, registry):
+    """Resolve the public SystemOne identifier without accepting wire aliases."""
+    if not isinstance(value, str) or not value.strip():
+        raise HTTPException(422, "Specify an available canonical Decision model")
+    for key, item in registry.items():
+        if value == item['repo_id']:
+            return key
+    raise HTTPException(
+        422,
+        "Use the exact Hugging Face repository ID for an available Decision model.",
+    )
+
+
 def public_models(registry):
-    return [dict(item, name=item['label'],
+    return [dict(item, id=item['repo_id'], wire_id=key, name=item['label'],
                  description=item.get('description', 'Decision foundation model'),
                  release_date=RELEASE_DATES[key]) for key, item in registry.items()]
 
 
-def sdk_response(result):
+def sdk_response(result, *, public_model=None):
     """Add the SDK's required distribution statistic without altering native outputs."""
     result = deepcopy(result)
+    if public_model is not None:
+        result['model'] = public_model
     groups = [result['answers']] if 'answers' in result else [r['answers'] for r in result['results']]
     for answers in groups:
         for answer in answers.values():
@@ -42,3 +57,34 @@ def sdk_response(result):
                 answer['confidence'] = max(probabilities)
     result['profile'] = dict(result.get('profile', {}), confidence_definition=CONFIDENCE_DEFINITION)
     return result
+
+
+def public_response(result, *, public_model, batch):
+    """Project native diagnostics onto the strict public Decision envelope."""
+    prepared = sdk_response(result, public_model=public_model)
+
+    def answers_only(answers):
+        fields = {
+            'noul': ('type', 'noul'),
+            'choice': ('type', 'choice', 'confidence', 'probabilities'),
+            'score': ('type', 'score', 'confidence', 'legend', 'probabilities'),
+        }
+        return {
+            key: {field: answer[field] for field in fields[answer['type']]}
+            for key, answer in answers.items()
+        }
+
+    if batch:
+        return {
+            'model': public_model,
+            'results': [
+                {'id': row['id'], 'answers': answers_only(row['answers']), 'usage': row['usage']}
+                for row in prepared['results']
+            ],
+            'usage': prepared['usage'],
+        }
+    return {
+        'model': public_model,
+        'answers': answers_only(prepared['answers']),
+        'usage': prepared['usage'],
+    }

tests/test_public_api_contract.py

@@ -0,0 +1,104 @@
+"""Public Decision endpoints keep canonical IDs separate from Studio wire IDs."""
+
+import unittest
+
+from fastapi.testclient import TestClient
+
+from app import create_app
+from contract import MODEL, to_response
+from engine import DEFAULT_MANIFEST
+from model_registry import PROFILES
+
+CANONICAL = PROFILES[MODEL]["repo_id"]
+
+
+class FakeEngine:
+    model = MODEL
+    manifest = DEFAULT_MANIFEST
+
+    def evaluate(self, payload, records):
+        predictions = []
+        for row in records:
+            predictions.append({
+                "id": row["id"],
+                "question_id": row["question"]["id"],
+                "type": "noul",
+                "candidate_ids": ["no", "yes"],
+                "probabilities": [0.25, 0.75],
+                "input_tokens": 8,
+                "state_tokens_original": 0,
+                "state_tokens_kept": 0,
+            })
+        result = to_response(payload, records, predictions, model=MODEL)
+        result["source"] = "live_native"
+        result["timing"] = {
+            "model_load_ms": 0,
+            "inference_ms": 1,
+            "server_ms": 2,
+            "cold_start": False,
+        }
+        return result
+
+
+def questions():
+    return {"check": {"type": "noul", "instructions": "Is this a request?"}}
+
+
+class PublicAPIContractTests(unittest.TestCase):
+    def setUp(self):
+        self.app_context = TestClient(create_app(
+            mode="native",
+            native_engine=FakeEngine(),
+            registry=[{
+                "id": MODEL,
+                "label": "Kai",
+                "version": "1.0",
+                "manifest_sha256": DEFAULT_MANIFEST,
+            }],
+        ))
+        self.client = self.app_context.__enter__()
+
+    def tearDown(self):
+        self.app_context.__exit__(None, None, None)
+
+    def test_single_requires_explicit_canonical_model_and_strict_envelope(self):
+        payload = {"model": CANONICAL, "state": "Please help", "questions": questions()}
+        result = self.client.post("/v1/systemone", json=payload)
+        self.assertEqual(result.status_code, 200)
+        body = result.json()
+        self.assertEqual(set(body), {"model", "answers", "usage"})
+        self.assertEqual(body["model"], CANONICAL)
+        self.assertEqual(set(body["answers"]["check"]), {"type", "noul"})
+
+        for invalid in (dict(payload, model=MODEL), dict(payload, model="Kai"),
+                        {key: value for key, value in payload.items() if key != "model"},
+                        dict(payload, states=[{"id": "one", "state": "extra"}])):
+            self.assertEqual(self.client.post("/v1/systemone", json=invalid).status_code, 422)
+
+    def test_batch_preserves_state_order_and_rejects_invalid_shapes(self):
+        payload = {
+            "model": CANONICAL,
+            "states": [
+                {"id": "second", "state": "Please help"},
+                {"id": "first", "state": "Thank you"},
+            ],
+            "questions": questions(),
+        }
+        result = self.client.post("/v1/decision/batches", json=payload)
+        self.assertEqual(result.status_code, 200)
+        body = result.json()
+        self.assertEqual(set(body), {"model", "results", "usage"})
+        self.assertEqual(body["model"], CANONICAL)
+        self.assertEqual([row["id"] for row in body["results"]], ["second", "first"])
+        self.assertEqual(body["usage"]["input_tokens"], 16)
+        self.assertTrue(all(set(row) == {"id", "answers", "usage"} for row in body["results"]))
+
+        duplicate = dict(payload, states=[payload["states"][0]] * 2)
+        self.assertEqual(self.client.post("/v1/decision/batches", json=duplicate).status_code, 422)
+        self.assertEqual(self.client.post("/v1/decision/batches", json=dict(payload, state="extra")).status_code, 422)
+        self.assertEqual(self.client.post("/v1/decision/batches", json=dict(payload, model=MODEL)).status_code, 422)
+        self.assertEqual(self.client.post("/v1/systemone/batch", json=payload).status_code, 404)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_tetris_arena.py

@@ -0,0 +1,747 @@
+import asyncio
+import json
+import unittest
+
+from tetris_arena import (
+    LOCAL_MODELS,
+    ArenaUpstreamError,
+    ArenaQuotaError,
+    ArenaValidationError,
+    Competitor,
+    DecisionOutcome,
+    Endpoint,
+    HTTPDecisionAdapter,
+    MAX_UPSTREAM_BYTES,
+    RaceManager,
+    create_piece_sequence,
+)
+
+LEFT = Competitor("left-model", "Left", "test", "left-wire", "Left")
+RIGHT = Competitor("right-model", "Right", "test", "right-wire", "Right")
+
+
+class RecordingAdapter:
+    def __init__(
+        self, *, delay=0, invalid_for=None, invalid_at=None,
+        request_ms=None, inference_ms=None,
+    ):
+        self.delay = delay
+        self.invalid_for = invalid_for
+        self.invalid_at = invalid_at
+        self.request_ms = request_ms
+        self.inference_ms = inference_ms
+        self.calls = []
+
+    def catalog(self):
+        return (LEFT, RIGHT)
+
+    async def decide(self, competitor, payload, legal_choices):
+        criteria = tuple(payload["questions"]["placement"]["criteria"])
+        self.calls.append(
+            {
+                "competitor": competitor.id,
+                "state": payload["state"],
+                "model": payload.get("model"),
+                "criteria": criteria,
+            }
+        )
+        delay = (
+            self.delay.get(competitor.id, 0)
+            if isinstance(self.delay, dict)
+            else self.delay
+        )
+        if delay:
+            await asyncio.sleep(delay)
+        side_calls = sum(
+            call["competitor"] == competitor.id for call in self.calls
+        )
+        if competitor.id == self.invalid_for or (
+            competitor.id == LEFT.id and side_calls == self.invalid_at
+        ):
+            choice = "not-a-legal-placement"
+        else:
+            choice = criteria[0] if competitor.id == LEFT.id else criteria[-1]
+        request_ms = (
+            self.request_ms.get(competitor.id, delay * 1_000)
+            if isinstance(self.request_ms, dict)
+            else delay * 1_000
+        )
+        inference_ms = (
+            self.inference_ms.get(competitor.id)
+            if isinstance(self.inference_ms, dict)
+            else self.inference_ms
+        )
+        return DecisionOutcome(
+            choice=choice, request_ms=request_ms, inference_ms=inference_ms
+        )
+
+
+class FakeResponse:
+    def __init__(
+        self, model, choice="r0-x0", *, chunks=None, encoding="identity",
+        inference_ms=None,
+    ):
+        self.is_redirect = False
+        self.status_code = 200
+        self.headers = {"content-encoding": encoding}
+        self.closed = False
+        self._document = {
+            "model": model,
+            "answers": {"placement": {"choice": choice}},
+        }
+        if inference_ms is not None:
+            self._document["timing"] = {"inference_ms": inference_ms}
+        self.chunks = chunks
+        self.yielded = 0
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *_args):
+        self.closed = True
+
+    async def aiter_raw(self, *, chunk_size):
+        for chunk in self.chunks or (json.dumps(self._document).encode(),):
+            self.yielded += 1
+            yield chunk
+
+
+class FakeHTTPClient:
+    def __init__(self, model, *, chunks=None, encoding="identity", inference_ms=None):
+        self.model = model
+        self.chunks = chunks
+        self.encoding = encoding
+        self.inference_ms = inference_ms
+        self.response = None
+
+    def stream(self, *args, **kwargs):
+        self.response = FakeResponse(
+            self.model, chunks=self.chunks, encoding=self.encoding,
+            inference_ms=self.inference_ms,
+        )
+        return self.response
+
+
+class BlockingAdapter(RecordingAdapter):
+    def __init__(self):
+        super().__init__()
+        self.entered = asyncio.Event()
+
+    async def decide(self, competitor, payload, legal_choices):
+        self.entered.set()
+        await asyncio.sleep(60)
+        return DecisionOutcome(choice=next(iter(legal_choices)), request_ms=60_000)
+
+
+class TetrisArenaTests(unittest.IsolatedAsyncioTestCase):
+    async def asyncSetUp(self):
+        self.managers = []
+
+    async def asyncTearDown(self):
+        await asyncio.gather(
+            *(manager.aclose() for manager in self.managers),
+            return_exceptions=True,
+        )
+
+    def manager(self, adapter, **kwargs):
+        manager = RaceManager(adapter, **kwargs)
+        self.managers.append(manager)
+        return manager
+
+    async def test_independent_requests_boards_actions_and_traces(self):
+        adapter = RecordingAdapter()
+        manager = self.manager(adapter)
+        race = await manager.create(
+            {
+                "left": LEFT.id,
+                "right": RIGHT.id,
+                "seed": 42,
+                "mode": "steps",
+                "max_steps": 6,
+            }
+        )
+
+        result = await asyncio.wait_for(race.wait(), 1)
+
+        self.assertEqual(result["results"]["left"]["pieces"], 6)
+        self.assertEqual(result["results"]["right"]["pieces"], 6)
+        self.assertTrue(result["summary"]["speed"]["comparable"])
+        self.assertEqual(result["states"]["left"]["step"], 6)
+        self.assertEqual(
+            result["states"]["left"]["game"]["board"],
+            race.traces["left"][-1]["board_after"],
+        )
+        left_calls = [call for call in adapter.calls if call["competitor"] == LEFT.id]
+        right_calls = [call for call in adapter.calls if call["competitor"] == RIGHT.id]
+        self.assertEqual(len(left_calls), 6)
+        self.assertEqual(len(right_calls), 6)
+        self.assertEqual(left_calls[0]["state"], right_calls[0]["state"])
+        self.assertNotEqual(left_calls[1]["state"], right_calls[1]["state"])
+        self.assertEqual(left_calls[0]["model"], "left-wire")
+        self.assertEqual(right_calls[0]["model"], "right-wire")
+
+        left_trace = race.traces["left"]
+        right_trace = race.traces["right"]
+        self.assertEqual(
+            [step["piece"] for step in left_trace],
+            [step["piece"] for step in right_trace],
+            "only the immutable piece sequence should be shared",
+        )
+        self.assertNotEqual(
+            [step["action"] for step in left_trace],
+            [step["action"] for step in right_trace],
+        )
+        self.assertNotEqual(left_trace[0]["board_after"], right_trace[0]["board_after"])
+        self.assertIsNot(left_trace, right_trace)
+        self.assertIsNone(race._orphan_task)
+
+    async def test_slow_renderer_does_not_gate_model_scheduling(self):
+        adapter = RecordingAdapter(delay=0.001)
+        manager = self.manager(adapter)
+        race = await manager.create(
+            {
+                "left": LEFT.id,
+                "right": RIGHT.id,
+                "seed": "render-independent",
+                "mode": "steps",
+                "max_steps": 8,
+            }
+        )
+
+        async def deliberately_slow_consumer():
+            async for event in race.iter_events():
+                if event is not None:
+                    await asyncio.sleep(0.05)
+
+        consumer = asyncio.create_task(deliberately_slow_consumer())
+        try:
+            result = await asyncio.wait_for(race.wait(), 0.25)
+        finally:
+            consumer.cancel()
+            await asyncio.gather(consumer, return_exceptions=True)
+
+        self.assertEqual(len(adapter.calls), 16)
+        self.assertEqual(result["status"], "finished")
+        self.assertEqual(result["results"]["left"]["pieces"], 8)
+        self.assertEqual(result["results"]["right"]["pieces"], 8)
+
+    async def test_invalid_model_choice_is_not_rewritten_or_retried(self):
+        adapter = RecordingAdapter(invalid_for=LEFT.id)
+        manager = self.manager(adapter)
+        race = await manager.create(
+            {
+                "left": LEFT.id,
+                "right": RIGHT.id,
+                "seed": 7,
+                "mode": "steps",
+                "max_steps": 3,
+            }
+        )
+
+        result = await asyncio.wait_for(race.wait(), 1)
+
+        self.assertEqual(result["status"], "incomplete")
+        self.assertEqual(result["results"]["left"]["status"], "error")
+        self.assertEqual(result["results"]["left"]["reason"], "invalid_choice")
+        self.assertEqual(result["results"]["left"]["pieces"], 0)
+        self.assertEqual(race.traces["left"][0]["action"], "not-a-legal-placement")
+        self.assertEqual(
+            len([call for call in adapter.calls if call["competitor"] == LEFT.id]),
+            1,
+            "an invalid choice must not trigger a hidden fallback request",
+        )
+        self.assertEqual(result["results"]["right"]["pieces"], 3)
+        self.assertEqual(result["summary"]["score"]["winner"], "unavailable")
+        self.assertFalse(result["summary"]["score"]["comparable"])
+        self.assertEqual(result["summary"]["speed"]["winner"], "unavailable")
+
+    async def test_partial_provider_failure_never_awards_a_score_winner(self):
+        race = await self.manager(RecordingAdapter(invalid_at=2)).create(
+            {
+                "left": LEFT.id,
+                "right": RIGHT.id,
+                "mode": "steps",
+                "max_steps": 3,
+            }
+        )
+
+        result = await asyncio.wait_for(race.wait(), 1)
+
+        self.assertEqual(result["status"], "incomplete")
+        self.assertEqual(result["results"]["left"]["pieces"], 1)
+        self.assertEqual(result["results"]["left"]["status"], "error")
+        self.assertEqual(result["results"]["right"]["status"], "finished")
+        self.assertEqual(result["summary"]["score"]["winner"], "unavailable")
+        self.assertEqual(result["summary"]["speed"]["winner"], "unavailable")
+        self.assertEqual(
+            [event["data"]["result"]["status"] for event in race.events
+             if event["type"] == "side.finished" and event["data"]["side"] == "left"],
+            ["error"],
+        )
+
+    async def test_first_failure_stops_a_pending_opponent(self):
+        adapter = RecordingAdapter(
+            delay={RIGHT.id: 60},
+            invalid_for=LEFT.id,
+        )
+        manager = self.manager(adapter, stream_grace_seconds=1)
+        race = await manager.create(
+            {
+                "left": LEFT.id,
+                "right": RIGHT.id,
+                "seed": 7,
+                "mode": "first_failure",
+                "max_steps": None,
+            }
+        )
+
+        result = await asyncio.wait_for(race.wait(), 1)
+
+        self.assertEqual(result["status"], "incomplete")
+        self.assertEqual(result["results"]["left"]["reason"], "invalid_choice")
+        self.assertEqual(
+            result["results"]["right"]["reason"],
+            "opponent_finished",
+        )
+        self.assertEqual(result["summary"]["score"]["winner"], "unavailable")
+
+    async def test_first_failure_guard_is_bounded_and_not_scored_as_a_win(self):
+        manager = self.manager(
+            RecordingAdapter(), max_steps_limit=2, first_failure_guard=2
+        )
+        race = await manager.create(
+            {"left": LEFT.id, "right": RIGHT.id, "mode": "first_failure"}
+        )
+
+        result = await asyncio.wait_for(race.wait(), 1)
+
+        self.assertEqual(result["status"], "incomplete")
+        self.assertEqual(
+            {side["reason"] for side in result["results"].values()},
+            {"operational_guard"},
+        )
+        self.assertEqual(race.provider_calls, 4)
+        self.assertEqual(result["summary"]["score"]["winner"], "unavailable")
+
+    async def test_speed_compares_server_request_e2e_even_when_runner_wall_time_differs(self):
+        adapter = RecordingAdapter(
+            delay={LEFT.id: 0.015, RIGHT.id: 0.001},
+            request_ms={LEFT.id: 2, RIGHT.id: 20},
+            inference_ms={LEFT.id: 100, RIGHT.id: 1},
+        )
+        race = await self.manager(adapter).create(
+            {
+                "left": LEFT.id,
+                "right": RIGHT.id,
+                "seed": 42,
+                "mode": "steps",
+                "max_steps": 4,
+            }
+        )
+
+        result = await asyncio.wait_for(race.wait(), 1)
+
+        self.assertEqual(result["summary"]["speed"]["winner"], "left")
+        self.assertEqual(result["summary"]["speed"]["percent"], 900.0)
+        self.assertEqual(
+            result["summary"]["speed"]["basis"],
+            "server_observed_request_to_response_e2e_total",
+        )
+        self.assertEqual(result["results"]["left"]["total_request_ms"], 8)
+        self.assertEqual(result["results"]["right"]["total_request_ms"], 80)
+        self.assertEqual(race.traces["left"][0]["provider_inference_ms"], 100)
+        self.assertGreater(
+            result["results"]["left"]["duration_ms"],
+            result["results"]["right"]["duration_ms"],
+        )
+
+    async def test_piece_sequence_is_seeded_bags(self):
+        first = create_piece_sequence("shared", 21)
+        second = create_piece_sequence("shared", 21)
+        different = create_piece_sequence("different", 21)
+        self.assertEqual(first, second)
+        self.assertNotEqual(first, different)
+        for offset in range(0, 21, 7):
+            self.assertEqual(set(first[offset : offset + 7]), set("IOTSZJL"))
+
+    async def test_local_catalog_contains_all_exact_models_with_short_display_names(
+        self,
+    ):
+        self.assertEqual(
+            [model.id for model in LOCAL_MODELS],
+            ["lux", "nox", "sol", "eos", "kai", "lex"],
+        )
+        self.assertTrue(
+            all(
+                model.request_model.startswith("llm-semantic-router/Decision-1.0-")
+                for model in LOCAL_MODELS
+            )
+        )
+        self.assertTrue(
+            all("Decision-1.0-" not in model.display_name for model in LOCAL_MODELS)
+        )
+
+    async def test_public_config_never_exposes_server_endpoints_or_credentials(self):
+        secret = "server-secret-canary"
+        private_url = "https://private-upstream.example.test/v1/systemone"
+        adapter = HTTPDecisionAdapter.from_environment(
+            {
+                "TETRIS_LOCAL_API_URL": private_url,
+                "TETRIS_JEV_API_URL": "https://jev.example.test/v1/systemone",
+                "TETRIS_JEV_API_KEY": secret,
+                "TETRIS_SYSTEMONE_API_URL": "https://systemone.example.test/api/v1/decide",
+                "TETRIS_SYSTEMONE_API_KEY": f"{secret}-mirror",
+            }
+        )
+        config = self.manager(adapter).public_config()
+        encoded = repr(config)
+
+        self.assertEqual(adapter._timeout_seconds, 45.0)
+        self.assertNotIn(secret, encoded)
+        self.assertNotIn(private_url, encoded)
+        self.assertTrue(all(item["ready"] for item in config["competitors"]))
+        self.assertEqual(len(config["competitors"]), 8)
+        by_id = {item["id"]: item for item in config["competitors"]}
+        self.assertEqual(by_id["jev-cloud-mirror"]["option_label"], "Jev Cloud")
+        self.assertEqual(by_id["jev-cloud-mirror"]["display_name"], "Jev Cloud")
+
+    async def test_decision_response_requires_exact_canonical_model_identity(self):
+        canonical = "llm-semantic-router/Decision-1.0-Lux-9B"
+        competitor = next(model for model in LOCAL_MODELS if model.id == "lux")
+        payload = {"state": "state", "questions": {}}
+        endpoint = Endpoint("https://local.example.test/v1/systemone", "", canonical)
+
+        accepted = HTTPDecisionAdapter(
+            endpoints={"lux": endpoint},
+            client=FakeHTTPClient(canonical),
+        )
+        outcome = await accepted.decide(competitor, payload, frozenset({"r0-x0"}))
+        self.assertEqual(outcome.provider_model, canonical)
+
+        mismatched = HTTPDecisionAdapter(
+            endpoints={"lux": endpoint},
+            client=FakeHTTPClient("llm-semantic-router/Decision-1.0-Kai-0.6B"),
+        )
+        with self.assertRaisesRegex(ArenaUpstreamError, "different model identity"):
+            await mismatched.decide(competitor, payload, frozenset({"r0-x0"}))
+
+        legacy_alias = HTTPDecisionAdapter(
+            endpoints={"lux": endpoint},
+            client=FakeHTTPClient("decision-lux"),
+        )
+        with self.assertRaisesRegex(ArenaUpstreamError, "different model identity"):
+            await legacy_alias.decide(competitor, payload, frozenset({"r0-x0"}))
+
+    async def test_request_latency_uses_server_clock_not_provider_inference_metric(self):
+        competitor = LOCAL_MODELS[0]
+        clock_ticks = iter((10.0, 10.037))
+        adapter = HTTPDecisionAdapter(
+            endpoints={
+                competitor.id: Endpoint(
+                    "https://local.example.test/v1/systemone", "", competitor.request_model
+                )
+            },
+            client=FakeHTTPClient(competitor.request_model, inference_ms=1),
+            clock=lambda: next(clock_ticks),
+        )
+
+        outcome = await adapter.decide(
+            competitor, {"state": "state"}, frozenset({"r0-x0"})
+        )
+
+        self.assertAlmostEqual(outcome.request_ms, 37.0)
+        self.assertEqual(outcome.inference_ms, 1)
+
+    async def test_jev_latest_accepts_versioned_identity_but_not_another_family(self):
+        competitor = Competitor(
+            "jev-cloud", "Jev Cloud", "cloud", "jev-latest", "Jev Cloud"
+        )
+        endpoint = Endpoint(
+            "https://api.typesafe.ai/v1/systemone",
+            "secret",
+            "jev-latest",
+            "jev_alias_or_version",
+        )
+        payload = {"state": "state", "questions": {}}
+        accepted = HTTPDecisionAdapter(
+            endpoints={"jev-cloud": endpoint},
+            client=FakeHTTPClient("jev-1.13.0"),
+        )
+        outcome = await accepted.decide(competitor, payload, frozenset({"r0-x0"}))
+        self.assertEqual(outcome.provider_model, "jev-1.13.0")
+
+        rejected = HTTPDecisionAdapter(
+            endpoints={"jev-cloud": endpoint},
+            client=FakeHTTPClient("unrelated-1.0.0"),
+        )
+        with self.assertRaisesRegex(ArenaUpstreamError, "unsupported model identity"):
+            await rejected.decide(competitor, payload, frozenset({"r0-x0"}))
+
+        pinned_endpoint = Endpoint(
+            "https://api.typesafe.ai/v1/systemone",
+            "secret",
+            "jev-1.12.0",
+            "jev_alias_or_version",
+        )
+        pinned = HTTPDecisionAdapter(
+            endpoints={"jev-cloud": pinned_endpoint},
+            client=FakeHTTPClient("jev-1.13.0"),
+        )
+        with self.assertRaisesRegex(ArenaUpstreamError, "different pinned model"):
+            await pinned.decide(competitor, payload, frozenset({"r0-x0"}))
+
+    async def test_upstream_stream_stops_at_byte_limit_and_closes(self):
+        canonical = LOCAL_MODELS[0].request_model
+        chunks = [b"x" * (64 * 1024)] * (MAX_UPSTREAM_BYTES // (64 * 1024) + 2)
+        client = FakeHTTPClient(canonical, chunks=chunks)
+        adapter = HTTPDecisionAdapter(
+            endpoints={"lux": Endpoint("https://local.example.test/v1/systemone", "", canonical)},
+            client=client,
+        )
+        with self.assertRaisesRegex(ArenaUpstreamError, "oversized response"):
+            await adapter.decide(LOCAL_MODELS[0], {"state": "state"}, frozenset({"r0-x0"}))
+        self.assertTrue(client.response.closed)
+        self.assertEqual(client.response.yielded, MAX_UPSTREAM_BYTES // (64 * 1024) + 1)
+
+    async def test_client_active_rate_and_provider_call_budgets(self):
+        adapter = BlockingAdapter()
+        manager = self.manager(
+            adapter,
+            client_races_per_minute=2,
+            client_calls_per_window=240,
+            stream_grace_seconds=1,
+        )
+        payload = {"left": LEFT.id, "right": RIGHT.id, "mode": "steps", "max_steps": 120}
+        first = await manager.create(payload, client_id="client-a")
+        await adapter.entered.wait()
+        with self.assertRaisesRegex(ArenaQuotaError, "already active"):
+            await manager.create(payload, client_id="client-a")
+        await first.cancel()
+        self.assertEqual(first.provider_calls, 2)
+        with self.assertRaisesRegex(ArenaQuotaError, "Provider call budget"):
+            await manager.create(payload, client_id="client-a")
+        second = await manager.create(
+            {**payload, "max_steps": 119}, client_id="client-a"
+        )
+        with self.assertRaisesRegex(ArenaQuotaError, "rate limit"):
+            await manager.create({**payload, "max_steps": 1}, client_id="client-a")
+        other = await manager.create(
+            {**payload, "max_steps": 1}, client_id="client-b"
+        )
+        await asyncio.gather(second.cancel(), other.cancel())
+
+    async def test_configured_long_run_limit_scales_call_budget_and_releases_history(self):
+        adapter = BlockingAdapter()
+        manager = RaceManager.from_environment(
+            adapter,
+            {
+                "TETRIS_MAX_STEPS": "2000",
+                "TETRIS_FIRST_FAILURE_GUARD": "1800",
+            },
+        )
+        self.managers.append(manager)
+
+        self.assertEqual(manager.public_config()["limits"], {
+            "max_steps": 2000,
+            "first_failure_guard": 1800,
+        })
+        self.assertEqual(manager.client_calls_per_window, 4000)
+        race = await manager.create(
+            {"left": LEFT.id, "right": RIGHT.id, "mode": "steps", "max_steps": 2000},
+            client_id="long-run",
+        )
+        await adapter.entered.wait()
+        self.assertEqual(race.call_budget, 4000)
+        self.assertEqual(race.history_limit, 4008)
+        await race.cancel()
+        manager._prune_admissions_locked()
+        admission = manager._client_history["long-run"][0]
+        self.assertIsNone(admission.session)
+        self.assertGreaterEqual(admission.provider_calls, 1)
+        self.assertLessEqual(admission.provider_calls, 2)
+
+        with self.assertRaisesRegex(ArenaValidationError, "between 1 and 2000"):
+            await manager.create(
+                {"left": LEFT.id, "right": RIGHT.id, "mode": "steps", "max_steps": 2001}
+            )
+        with self.assertRaisesRegex(ValueError, "TETRIS_CLIENT_CALLS_PER_WINDOW"):
+            RaceManager.from_environment(
+                RecordingAdapter(),
+                {"TETRIS_MAX_STEPS": "2000", "TETRIS_CLIENT_CALLS_PER_WINDOW": "3999"},
+            )
+
+    async def test_immediate_cancel_finalizes_a_not_yet_started_race(self):
+        manager = self.manager(RecordingAdapter())
+        race = await manager.create(
+            {
+                "left": LEFT.id,
+                "right": RIGHT.id,
+                "mode": "steps",
+                "max_steps": 3,
+            }
+        )
+
+        await race.cancel("user_cancelled")
+
+        self.assertTrue(race._done.is_set())
+        self.assertEqual(race.status, "cancelled")
+        self.assertIsNotNone(race.completed_at)
+        self.assertEqual((await race.wait())["status"], "cancelled")
+
+    async def test_race_deadline_stops_both_model_runners(self):
+        adapter = BlockingAdapter()
+        manager = self.manager(
+            adapter,
+            race_timeout_seconds=0.02,
+            stream_grace_seconds=1,
+        )
+        race = await manager.create(
+            {
+                "left": LEFT.id,
+                "right": RIGHT.id,
+                "mode": "steps",
+                "max_steps": 20,
+            }
+        )
+
+        result = await asyncio.wait_for(race.wait(), 1)
+
+        self.assertEqual(result["status"], "timed_out")
+        self.assertEqual(result["summary"]["status"], "timed_out")
+        self.assertEqual(result["summary"]["score"]["winner"], "unavailable")
+        self.assertEqual(
+            {item["reason"] for item in result["results"].values()},
+            {"race_timeout"},
+        )
+
+    async def test_stream_grace_cancels_an_abandoned_race(self):
+        adapter = BlockingAdapter()
+        manager = self.manager(
+            adapter,
+            race_timeout_seconds=1,
+            stream_grace_seconds=0.02,
+        )
+        race = await manager.create(
+            {
+                "left": LEFT.id,
+                "right": RIGHT.id,
+                "mode": "steps",
+                "max_steps": 20,
+            }
+        )
+
+        result = await asyncio.wait_for(race.wait(), 1)
+
+        self.assertEqual(result["status"], "cancelled")
+        self.assertEqual(
+            {item["reason"] for item in result["results"].values()},
+            {"stream_disconnected"},
+        )
+
+    async def test_connected_event_stream_holds_the_orphan_lease(self):
+        adapter = BlockingAdapter()
+        manager = self.manager(
+            adapter,
+            race_timeout_seconds=1,
+            stream_grace_seconds=0.02,
+        )
+        race = await manager.create(
+            {
+                "left": LEFT.id,
+                "right": RIGHT.id,
+                "mode": "steps",
+                "max_steps": 20,
+            }
+        )
+        stream = race.iter_events()
+        await anext(stream)
+
+        await asyncio.sleep(0.05)
+        self.assertFalse(race._done.is_set())
+
+        await stream.aclose()
+        result = await asyncio.wait_for(race.wait(), 1)
+        self.assertEqual(result["status"], "cancelled")
+
+    async def test_manager_close_cancels_and_awaits_active_sessions(self):
+        adapter = BlockingAdapter()
+        manager = self.manager(adapter, stream_grace_seconds=1)
+        race = await manager.create(
+            {
+                "left": LEFT.id,
+                "right": RIGHT.id,
+                "mode": "steps",
+                "max_steps": 20,
+            }
+        )
+        await adapter.entered.wait()
+
+        await manager.aclose()
+
+        self.assertEqual(race.status, "cancelled")
+        self.assertTrue(race._done.is_set())
+
+    async def test_concurrent_manager_close_waits_for_the_same_shutdown(self):
+        adapter = BlockingAdapter()
+        manager = self.manager(adapter, stream_grace_seconds=1)
+        race = await manager.create(
+            {
+                "left": LEFT.id,
+                "right": RIGHT.id,
+                "mode": "steps",
+                "max_steps": 20,
+            }
+        )
+        await adapter.entered.wait()
+
+        first = asyncio.create_task(manager.aclose())
+        second = asyncio.create_task(manager.aclose())
+        await asyncio.gather(first, second)
+
+        self.assertTrue(race._done.is_set())
+        self.assertEqual(race.status, "cancelled")
+        self.assertEqual(manager.sessions, {})
+
+    async def test_completed_sessions_expire_on_access(self):
+        manager = self.manager(
+            RecordingAdapter(),
+            completed_ttl_seconds=0.01,
+        )
+        race = await manager.create(
+            {
+                "left": LEFT.id,
+                "right": RIGHT.id,
+                "mode": "steps",
+                "max_steps": 1,
+            }
+        )
+        await race.wait()
+        await asyncio.sleep(0.02)
+
+        with self.assertRaises(KeyError):
+            manager.get(race.id)
+
+    async def test_race_lifecycle_limits_are_explicit_environment_settings(self):
+        manager = RaceManager.from_environment(
+            RecordingAdapter(),
+            {
+                "TETRIS_RACE_TIMEOUT_SECONDS": "120",
+                "TETRIS_STREAM_GRACE_SECONDS": "12",
+                "TETRIS_COMPLETED_TTL_SECONDS": "60",
+            },
+        )
+        self.managers.append(manager)
+
+        self.assertEqual(manager.race_timeout_seconds, 120)
+        self.assertEqual(manager.stream_grace_seconds, 12)
+        self.assertEqual(manager.completed_ttl_seconds, 60)
+
+        with self.assertRaisesRegex(ValueError, "TETRIS_RACE_TIMEOUT_SECONDS"):
+            RaceManager.from_environment(
+                RecordingAdapter(),
+                {"TETRIS_RACE_TIMEOUT_SECONDS": "unbounded"},
+            )
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_tetris_assets.py

@@ -0,0 +1,42 @@
+import unittest
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+class TetrisAssetTests(unittest.TestCase):
+    def test_docker_context_contains_tetris_server_module(self):
+        dockerignore = (ROOT / ".dockerignore").read_text().splitlines()
+        dockerfile = (ROOT / "Dockerfile").read_text()
+
+        self.assertIn("!tetris_arena.py", dockerignore)
+        self.assertIn("tetris_arena.py", dockerfile)
+
+    def test_frontend_has_a_single_flight_race_lifecycle(self):
+        source = (ROOT / "static" / "tetris" / "app.js").read_text()
+
+        for state in ("idle", "starting", "running", "stopping"):
+            self.assertIn(state, source)
+        self.assertIn("if (lifecycle !== 'idle') return", source)
+        self.assertIn("lifecycle === 'starting' || lifecycle === 'stopping'", source)
+        self.assertIn("expectedOperation !== operation", source)
+        self.assertIn("createController.signal", source)
+
+    def test_frontend_uses_server_limit_and_recovers_terminal_snapshots(self):
+        source = (ROOT / "static" / "tetris" / "app.js").read_text()
+        page = (ROOT / "static" / "tetris" / "index.html").read_text()
+
+        self.assertIn('elements.customSteps.max = String(maximum)', source)
+        self.assertIn('option.disabled = Number(option.value) > maximum', source)
+        self.assertIn('connectEventStream(race.events_url, race.result_url', source)
+        self.assertIn("async function recoverSnapshot()", source)
+        self.assertIn("applySnapshot(snapshot)", source)
+        self.assertIn("data.step <= seenSteps[data.side]", source)
+        self.assertIn("finishRace(snapshot.status, snapshot.summary, stream)", source)
+        self.assertIn("error: 'Failed'", source)
+        self.assertIn('max="120"', page)
+        self.assertEqual(page.count('data-result-status'), 2)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_tetris_routes.py

@@ -0,0 +1,138 @@
+import asyncio
+import json
+import unittest
+
+from fastapi.testclient import TestClient
+
+from app import create_app
+from tetris_arena import Competitor, DecisionOutcome, RaceManager
+
+LEFT = Competitor("route-left", "Route Left", "test", "left-wire", "Route Left")
+RIGHT = Competitor("route-right", "Route Right", "test", "right-wire", "Route Right")
+
+
+class RouteAdapter:
+    def catalog(self):
+        return (LEFT, RIGHT)
+
+    async def decide(self, competitor, payload, legal_choices):
+        choices = tuple(payload["questions"]["placement"]["criteria"])
+        choice = choices[0] if competitor.id == LEFT.id else choices[-1]
+        return DecisionOutcome(choice, 1.25, competitor.request_model)
+
+
+class SlowRouteAdapter(RouteAdapter):
+    async def decide(self, competitor, payload, legal_choices):
+        await asyncio.sleep(60)
+        return DecisionOutcome(
+            next(iter(legal_choices)), 60_000, competitor.request_model
+        )
+
+
+class TetrisRouteTests(unittest.TestCase):
+    def setUp(self):
+        self.manager = RaceManager(RouteAdapter())
+        self.client_context = TestClient(create_app(tetris_manager=self.manager))
+        self.client = self.client_context.__enter__()
+
+    def tearDown(self):
+        self.client_context.portal.call(self.manager.aclose)
+        self.client_context.__exit__(None, None, None)
+
+    def test_static_page_config_sse_and_trace_are_integrated(self):
+        page = self.client.get("/tetris/")
+        self.assertEqual(page.status_code, 200)
+        self.assertIn("Decision 1.0 · Tetris Race", page.text)
+
+        config = self.client.get("/api/tetris/config")
+        self.assertEqual(config.status_code, 200)
+        self.assertEqual(
+            [item["id"] for item in config.json()["competitors"]],
+            [LEFT.id, RIGHT.id],
+        )
+
+        created = self.client.post(
+            "/api/tetris/races",
+            json={
+                "left": LEFT.id,
+                "right": RIGHT.id,
+                "seed": 42,
+                "mode": "steps",
+                "max_steps": 3,
+            },
+        )
+        self.assertEqual(created.status_code, 201)
+        document = created.json()
+        with self.client.stream("GET", document["events_url"]) as response:
+            self.assertEqual(response.status_code, 200)
+            stream = "".join(response.iter_text())
+        self.assertIn("event: side.step", stream)
+        self.assertIn("event: race.finished", stream)
+        event_ids = [
+            int(line.removeprefix("id: "))
+            for line in stream.splitlines()
+            if line.startswith("id: ")
+        ]
+        resumed = self.client.get(
+            document["events_url"],
+            headers={"Last-Event-ID": str(event_ids[-2])},
+        )
+        self.assertEqual(resumed.status_code, 200)
+        self.assertEqual(
+            [line for line in resumed.text.splitlines() if line.startswith("id: ")],
+            [f"id: {event_ids[-1]}"],
+        )
+
+        trace = self.client.get(f"/api/tetris/races/{document['id']}/trace")
+        self.assertEqual(trace.status_code, 200)
+        payload = trace.json()
+        self.assertEqual(payload["status"], "finished")
+        self.assertEqual(len(payload["traces"]["left"]), 3)
+        self.assertEqual(len(payload["traces"]["right"]), 3)
+        self.assertEqual(payload["states"]["left"]["step"], 3)
+        self.assertEqual(
+            payload["states"]["left"]["game"]["board"],
+            payload["traces"]["left"][-1]["board_after"],
+        )
+        self.assertEqual(payload["summary"]["status"], "finished")
+        self.assertNotEqual(
+            payload["traces"]["left"][0]["action"],
+            payload["traces"]["right"][0]["action"],
+        )
+        self.assertNotIn("Authorization", json.dumps(payload))
+
+    def test_unconfigured_or_invalid_race_is_rejected(self):
+        response = self.client.post(
+            "/api/tetris/races",
+            json={
+                "left": "missing",
+                "right": RIGHT.id,
+                "mode": "steps",
+                "max_steps": 3,
+            },
+        )
+        self.assertEqual(response.status_code, 422)
+
+    def test_app_shutdown_closes_its_manager_and_active_races(self):
+        api = create_app(tetris_adapter=SlowRouteAdapter())
+        with TestClient(api) as client:
+            created = client.post(
+                "/api/tetris/races",
+                json={
+                    "left": LEFT.id,
+                    "right": RIGHT.id,
+                    "mode": "steps",
+                    "max_steps": 20,
+                },
+            )
+            self.assertEqual(created.status_code, 201)
+            race = api.state.tetris.get(created.json()["id"])
+
+        self.assertTrue(api.state.tetris._closing)
+        self.assertTrue(race._done.is_set())
+        self.assertEqual(race.status, "cancelled")
+        self.assertEqual(api.state.tetris.sessions, {})
+
+
+if __name__ == "__main__":
+    unittest.main()

tetris_arena.py

@@ -0,0 +1,1673 @@
+"""Server-authoritative Decision 1.0 Tetris races.
+
+The browser is deliberately a passive renderer.  Each competitor owns an
+independent game, request loop, and trace.  The only shared race input is the
+immutable tetromino sequence generated from the requested seed.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import copy
+import hashlib
+import json
+import math
+import os
+import random
+import re
+import secrets
+import time
+from collections import deque
+from collections.abc import AsyncIterator, Mapping
+from dataclasses import dataclass, field
+from typing import Any
+from urllib.parse import urlsplit
+
+BOARD_WIDTH = 10
+BOARD_HEIGHT = 20
+DEFAULT_MAX_STEPS = 40
+DEFAULT_MAX_CONFIGURED_STEPS = 120
+MAX_CONFIGURED_STEPS = 2_000
+MAX_PROVIDER_CALLS_PER_RACE = 2 * MAX_CONFIGURED_STEPS
+MAX_CONCURRENT_RACES = 4
+DEFAULT_CLIENT_ACTIVE_RACES = 1
+DEFAULT_CLIENT_RACES_PER_MINUTE = 6
+MAX_CLIENT_RACES_PER_MINUTE = 30
+DEFAULT_CLIENT_WINDOW_SECONDS = 60
+DEFAULT_CLIENT_CALLS_PER_WINDOW = 480
+DEFAULT_CLIENT_CALL_WINDOW_SECONDS = 10 * 60
+MAX_ADMISSION_HISTORY = 4096
+MAX_RACE_HISTORY = MAX_PROVIDER_CALLS_PER_RACE + 8
+MAX_UPSTREAM_BYTES = 1_048_576
+MAX_RETAINED_RACES = 16
+DEFAULT_RACE_TIMEOUT_SECONDS = 15 * 60
+DEFAULT_STREAM_GRACE_SECONDS = 30
+DEFAULT_COMPLETED_TTL_SECONDS = 5 * 60
+
+_JEV_VERSION = re.compile(r"jev-\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?")
+
+PIECE_NAMES = ("I", "O", "T", "S", "Z", "J", "L")
+PIECES: dict[str, tuple[tuple[tuple[int, int], ...], ...]] = {
+    "I": (
+        ((0, 1), (1, 1), (2, 1), (3, 1)),
+        ((2, 0), (2, 1), (2, 2), (2, 3)),
+        ((0, 2), (1, 2), (2, 2), (3, 2)),
+        ((1, 0), (1, 1), (1, 2), (1, 3)),
+    ),
+    "O": (((1, 0), (2, 0), (1, 1), (2, 1)),),
+    "T": (
+        ((1, 0), (0, 1), (1, 1), (2, 1)),
+        ((1, 0), (1, 1), (2, 1), (1, 2)),
+        ((0, 1), (1, 1), (2, 1), (1, 2)),
+        ((1, 0), (0, 1), (1, 1), (1, 2)),
+    ),
+    "S": (
+        ((1, 0), (2, 0), (0, 1), (1, 1)),
+        ((1, 0), (1, 1), (2, 1), (2, 2)),
+        ((1, 1), (2, 1), (0, 2), (1, 2)),
+        ((0, 0), (0, 1), (1, 1), (1, 2)),
+    ),
+    "Z": (
+        ((0, 0), (1, 0), (1, 1), (2, 1)),
+        ((2, 0), (1, 1), (2, 1), (1, 2)),
+        ((0, 1), (1, 1), (1, 2), (2, 2)),
+        ((1, 0), (0, 1), (1, 1), (0, 2)),
+    ),
+    "J": (
+        ((0, 0), (0, 1), (1, 1), (2, 1)),
+        ((1, 0), (2, 0), (1, 1), (1, 2)),
+        ((0, 1), (1, 1), (2, 1), (2, 2)),
+        ((1, 0), (1, 1), (0, 2), (1, 2)),
+    ),
+    "L": (
+        ((2, 0), (0, 1), (1, 1), (2, 1)),
+        ((1, 0), (1, 1), (1, 2), (2, 2)),
+        ((0, 1), (1, 1), (2, 1), (0, 2)),
+        ((0, 0), (1, 0), (1, 1), (1, 2)),
+    ),
+}
+LINE_SCORES = (0, 100, 300, 500, 800)
+
+
+@dataclass(frozen=True)
+class Competitor:
+    id: str
+    display_name: str
+    family: str
+    request_model: str | None
+    option_label: str
+    ready: bool = True
+
+    def public(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "display_name": self.display_name,
+            "option_label": self.option_label,
+            "family": self.family,
+            "ready": self.ready,
+        }
+
+
+LOCAL_MODELS: tuple[Competitor, ...] = (
+    Competitor(
+        "lux",
+        "Lux-9B",
+        "decision",
+        "llm-semantic-router/Decision-1.0-Lux-9B",
+        "Lux-9B",
+    ),
+    Competitor(
+        "nox",
+        "Nox-4B",
+        "decision",
+        "llm-semantic-router/Decision-1.0-Nox-4B",
+        "Nox-4B",
+    ),
+    Competitor(
+        "sol",
+        "Sol-2B",
+        "decision",
+        "llm-semantic-router/Decision-1.0-Sol-2B",
+        "Sol-2B",
+    ),
+    Competitor(
+        "eos",
+        "Eos-0.8B",
+        "decision",
+        "llm-semantic-router/Decision-1.0-Eos-0.8B",
+        "Eos-0.8B",
+    ),
+    Competitor(
+        "kai",
+        "Kai-0.6B",
+        "decision",
+        "llm-semantic-router/Decision-1.0-Kai-0.6B",
+        "Kai-0.6B",
+    ),
+    Competitor(
+        "lex",
+        "Lex-0.6B",
+        "decision",
+        "llm-semantic-router/Decision-1.0-Lex-0.6B",
+        "Lex-0.6B",
+    ),
+)
+
+
+class ArenaValidationError(ValueError):
+    """A user-visible race request error."""
+
+    status_code = 422
+    retry_after: int | None = None
+
+
+class ArenaQuotaError(ArenaValidationError):
+    """A bounded public-demo admission limit was reached."""
+
+    status_code = 429
+
+    def __init__(self, message: str, *, retry_after: int):
+        super().__init__(message)
+        self.retry_after = retry_after
+
+
+class ArenaUpstreamError(RuntimeError):
+    """A sanitized decision-provider error."""
+
+
+@dataclass(frozen=True)
+class Placement:
+    id: str
+    piece: str
+    rotation: int
+    x: int
+    y: int
+    cells: tuple[tuple[int, int], ...]
+    board: tuple[str, ...]
+    cleared_rows: tuple[int, ...]
+    top_out: bool
+    holes: int
+    max_height: int
+
+
+@dataclass
+class Game:
+    board: list[list[str | None]] = field(
+        default_factory=lambda: [
+            [None for _ in range(BOARD_WIDTH)] for _ in range(BOARD_HEIGHT)
+        ]
+    )
+    score: int = 0
+    lines: int = 0
+    pieces: int = 0
+    game_over: bool = False
+
+    def rows(self) -> list[str]:
+        return ["".join(cell or "." for cell in row) for row in self.board]
+
+    def public(self) -> dict[str, Any]:
+        return {
+            "board": self.rows(),
+            "score": self.score,
+            "lines": self.lines,
+            "pieces": self.pieces,
+            "game_over": self.game_over,
+        }
+
+
+@dataclass(frozen=True)
+class DecisionOutcome:
+    choice: str
+    request_ms: float
+    provider_model: str | None = None
+    inference_ms: float | None = None
+
+
+@dataclass(frozen=True)
+class Endpoint:
+    url: str
+    api_key: str = field(repr=False)
+    model: str | None = None
+    identity_policy: str = "exact"
+
+
+def _seed_number(seed: str | int) -> int:
+    if isinstance(seed, int) and not isinstance(seed, bool):
+        return seed
+    digest = hashlib.sha256(str(seed).encode("utf-8")).digest()
+    return int.from_bytes(digest[:8], "big")
+
+
+def create_piece_sequence(seed: str | int, count: int) -> tuple[str, ...]:
+    """Create deterministic shuffled seven-piece bags."""
+    if not isinstance(count, int) or isinstance(count, bool) or count < 0:
+        raise ValueError("count must be a non-negative integer")
+    generator = random.Random(_seed_number(seed))
+    result: list[str] = []
+    while len(result) < count:
+        bag = list(PIECE_NAMES)
+        generator.shuffle(bag)
+        result.extend(bag)
+    return tuple(result[:count])
+
+
+def _can_place(
+    board: list[list[str | None]],
+    shape: tuple[tuple[int, int], ...],
+    x: int,
+    y: int,
+) -> bool:
+    for cell_x, cell_y in shape:
+        absolute_x = x + cell_x
+        absolute_y = y + cell_y
+        if absolute_x < 0 or absolute_x >= BOARD_WIDTH or absolute_y >= BOARD_HEIGHT:
+            return False
+        if absolute_y >= 0 and board[absolute_y][absolute_x] is not None:
+            return False
+    return True
+
+
+def _board_stats(board: list[list[str | None]]) -> tuple[int, int]:
+    holes = 0
+    heights: list[int] = []
+    for x in range(BOARD_WIDTH):
+        first = next((y for y in range(BOARD_HEIGHT) if board[y][x] is not None), None)
+        if first is None:
+            heights.append(0)
+            continue
+        heights.append(BOARD_HEIGHT - first)
+        holes += sum(1 for y in range(first + 1, BOARD_HEIGHT) if board[y][x] is None)
+    return holes, max(heights, default=0)
+
+
+def _preview_placement(
+    game: Game,
+    piece: str,
+    rotation: int,
+    x: int,
+    y: int,
+) -> Placement:
+    shape = PIECES[piece][rotation]
+    cells = tuple(sorted((x + cell_x, y + cell_y) for cell_x, cell_y in shape))
+    board = [row[:] for row in game.board]
+    top_out = any(cell_y < 0 for _, cell_y in cells)
+    for cell_x, cell_y in cells:
+        if cell_y >= 0:
+            board[cell_y][cell_x] = piece
+    cleared_rows = tuple(
+        row_index
+        for row_index, row in enumerate(board)
+        if all(cell is not None for cell in row)
+    )
+    if cleared_rows:
+        kept = [row for index, row in enumerate(board) if index not in cleared_rows]
+        board = [[None] * BOARD_WIDTH for _ in cleared_rows] + kept
+    holes, max_height = _board_stats(board)
+    return Placement(
+        id=f"r{rotation}-x{x}",
+        piece=piece,
+        rotation=rotation,
+        x=x,
+        y=y,
+        cells=cells,
+        board=tuple("".join(cell or "." for cell in row) for row in board),
+        cleared_rows=cleared_rows,
+        top_out=top_out,
+        holes=holes,
+        max_height=max_height,
+    )
+
+
+def enumerate_placements(game: Game, piece: str) -> tuple[Placement, ...]:
+    if piece not in PIECES:
+        raise ValueError("unknown tetromino")
+    placements: list[Placement] = []
+    seen: set[tuple[tuple[int, int], ...]] = set()
+    for rotation, shape in enumerate(PIECES[piece]):
+        minimum_x = min(x for x, _ in shape)
+        maximum_x = max(x for x, _ in shape)
+        for x in range(-minimum_x, BOARD_WIDTH - maximum_x):
+            y = -4
+            while _can_place(game.board, shape, x, y + 1):
+                y += 1
+            if not _can_place(game.board, shape, x, y):
+                continue
+            absolute_cells = tuple(
+                sorted((x + cell_x, y + cell_y) for cell_x, cell_y in shape)
+            )
+            if absolute_cells in seen:
+                continue
+            seen.add(absolute_cells)
+            placements.append(_preview_placement(game, piece, rotation, x, y))
+    return tuple(placements)
+
+
+def apply_placement(game: Game, placement: Placement) -> Game:
+    board = [[None if cell == "." else cell for cell in row] for row in placement.board]
+    cleared = len(placement.cleared_rows)
+    return Game(
+        board=board,
+        score=game.score + LINE_SCORES[min(cleared, 4)],
+        lines=game.lines + cleared,
+        pieces=game.pieces + 1,
+        game_over=placement.top_out,
+    )
+
+
+def build_decision_request(
+    game: Game,
+    piece: str,
+    next_piece: str | None,
+    placements: tuple[Placement, ...],
+    model: str | None,
+) -> tuple[dict[str, Any], str]:
+    rows = game.rows()
+    state = "\n".join(
+        (
+            (
+                f"piece={piece}; next={next_piece or 'none'}; score={game.score}; "
+                f"lines={game.lines}; pieces={game.pieces}"
+            ),
+            "board (top to bottom, .=empty):",
+            *rows,
+        )
+    )
+    criteria = {
+        placement.id: (
+            f"rotation {placement.rotation}, column {placement.x}; "
+            f"clears {len(placement.cleared_rows)}; holes {placement.holes}; "
+            f"height {placement.max_height}; top-out {'yes' if placement.top_out else 'no'}"
+        )
+        for placement in placements
+    }
+    payload: dict[str, Any] = {
+        "state": state,
+        "questions": {
+            "placement": {
+                "type": "choice",
+                "instructions": (
+                    "Play Tetris to maximize long-term survival and score. Choose exactly "
+                    "one listed legal placement for the current tetromino. Prefer line "
+                    "clears, fewer holes, and a lower stack; avoid top-out. Return its "
+                    "choice id."
+                ),
+                "criteria": criteria,
+            }
+        },
+    }
+    if model:
+        payload["model"] = model
+    return payload, state
+
+
+def _valid_url(value: str, name: str) -> str:
+    try:
+        parsed = urlsplit(value.strip())
+    except ValueError as exc:
+        raise ValueError(f"{name} must be a valid HTTP or HTTPS URL") from exc
+    if (
+        parsed.scheme not in {"http", "https"}
+        or not parsed.netloc
+        or parsed.username
+        or parsed.password
+        or parsed.query
+        or parsed.fragment
+    ):
+        raise ValueError(
+            f"{name} must be an HTTP or HTTPS URL without credentials, query, or fragment"
+        )
+    return value.strip()
+
+
+def _first_environment(env: Mapping[str, str], *names: str) -> str:
+    for name in names:
+        value = env.get(name, "").strip()
+        if value:
+            return value
+    return ""
+
+
+def _environment_float(
+    env: Mapping[str, str],
+    name: str,
+    default: float,
+    *,
+    minimum: float,
+    maximum: float,
+) -> float:
+    raw = env.get(name, "").strip()
+    if not raw:
+        return float(default)
+    try:
+        value = float(raw)
+    except ValueError as exc:
+        raise ValueError(f"{name} must be numeric") from exc
+    if not math.isfinite(value) or not minimum <= value <= maximum:
+        raise ValueError(f"{name} must be between {minimum:g} and {maximum:g}")
+    return value
+
+
+def _environment_int(
+    env: Mapping[str, str],
+    name: str,
+    default: int,
+    *,
+    minimum: int,
+    maximum: int,
+) -> int:
+    raw = env.get(name, "").strip()
+    if not raw:
+        return default
+    try:
+        value = int(raw)
+    except ValueError as exc:
+        raise ValueError(f"{name} must be an integer") from exc
+    if not minimum <= value <= maximum:
+        raise ValueError(f"{name} must be between {minimum} and {maximum}")
+    return value
+
+
+class HTTPDecisionAdapter:
+    """Server-only adapters for local Decision, Jev Cloud, and SystemOne upstream."""
+
+    def __init__(
+        self,
+        *,
+        endpoints: Mapping[str, Endpoint],
+        timeout_seconds: float = 45.0,
+        client: Any = None,
+        clock=time.perf_counter,
+    ):
+        self._endpoints = dict(endpoints)
+        self._timeout_seconds = timeout_seconds
+        self._client = client
+        self._owns_client = client is None
+        self._clock = clock
+
+    @classmethod
+    def from_environment(
+        cls, env: Mapping[str, str] | None = None
+    ) -> HTTPDecisionAdapter:
+        env = os.environ if env is None else env
+        shared_local_key = _first_environment(env, "TETRIS_LOCAL_API_KEY")
+        endpoints: dict[str, Endpoint] = {}
+        for competitor in LOCAL_MODELS:
+            model_key = competitor.id.upper()
+            raw_url = _first_environment(
+                env,
+                f"TETRIS_LOCAL_{model_key}_API_URL",
+                "TETRIS_LOCAL_API_URL",
+                "LOCAL_API_URL",
+            )
+            if raw_url:
+                endpoints[competitor.id] = Endpoint(
+                    _valid_url(raw_url, f"TETRIS_LOCAL_{model_key}_API_URL"),
+                    _first_environment(env, f"TETRIS_LOCAL_{model_key}_API_KEY")
+                    or shared_local_key,
+                    competitor.request_model,
+                )
+
+        jev_url = _first_environment(env, "TETRIS_JEV_API_URL", "JEV_API_URL")
+        jev_key = _first_environment(env, "TETRIS_JEV_API_KEY", "JEV_API_KEY")
+        if jev_url and jev_key:
+            endpoints["jev-cloud"] = Endpoint(
+                _valid_url(jev_url, "TETRIS_JEV_API_URL"),
+                jev_key,
+                _first_environment(env, "TETRIS_JEV_MODEL") or "jev-latest",
+                "jev_alias_or_version",
+            )
+
+        systemone_url = _first_environment(
+            env, "TETRIS_SYSTEMONE_API_URL", "JEV_MIRROR_API_URL"
+        )
+        systemone_key = _first_environment(
+            env, "TETRIS_SYSTEMONE_API_KEY", "JEV_MIRROR_API_KEY"
+        )
+        if systemone_url and systemone_key:
+            endpoints["jev-cloud-mirror"] = Endpoint(
+                _valid_url(systemone_url, "TETRIS_SYSTEMONE_API_URL"),
+                systemone_key,
+                _first_environment(env, "TETRIS_SYSTEMONE_MODEL") or None,
+                "jev_alias_or_version",
+            )
+
+        timeout_raw = _first_environment(env, "TETRIS_REQUEST_TIMEOUT_SECONDS") or "45"
+        try:
+            timeout = float(timeout_raw)
+        except ValueError as exc:
+            raise ValueError("TETRIS_REQUEST_TIMEOUT_SECONDS must be numeric") from exc
+        if not math.isfinite(timeout) or not 0.1 <= timeout <= 300:
+            raise ValueError(
+                "TETRIS_REQUEST_TIMEOUT_SECONDS must be between 0.1 and 300"
+            )
+        return cls(endpoints=endpoints, timeout_seconds=timeout)
+
+    def catalog(self) -> tuple[Competitor, ...]:
+        cloud = (
+            Competitor(
+                "jev-cloud",
+                "Jev Cloud",
+                "cloud",
+                self._endpoints.get("jev-cloud", Endpoint("", "")).model,
+                "Jev Cloud",
+                "jev-cloud" in self._endpoints,
+            ),
+            Competitor(
+                "jev-cloud-mirror",
+                "Jev Cloud",
+                "cloud",
+                self._endpoints.get("jev-cloud-mirror", Endpoint("", "")).model,
+                "Jev Cloud",
+                "jev-cloud-mirror" in self._endpoints,
+            ),
+        )
+        return cloud + tuple(
+            Competitor(
+                model.id,
+                model.display_name,
+                model.family,
+                model.request_model,
+                model.option_label,
+                model.id in self._endpoints,
+            )
+            for model in LOCAL_MODELS
+        )
+
+    async def close(self) -> None:
+        if self._owns_client and self._client is not None:
+            await self._client.aclose()
+            self._client = None
+
+    async def decide(
+        self,
+        competitor: Competitor,
+        payload: Mapping[str, Any],
+        legal_choices: frozenset[str],
+    ) -> DecisionOutcome:
+        try:
+            import httpx
+        except ModuleNotFoundError as exc:
+            raise ArenaUpstreamError(
+                "The decision transport is not installed."
+            ) from exc
+        endpoint = self._endpoints.get(competitor.id)
+        if endpoint is None:
+            raise ArenaUpstreamError(
+                "The selected model is not configured on this server."
+            )
+        if self._client is None:
+            self._client = httpx.AsyncClient(
+                follow_redirects=False,
+                timeout=self._timeout_seconds,
+                trust_env=False,
+            )
+
+        upstream_payload = copy.deepcopy(dict(payload))
+        if endpoint.model:
+            upstream_payload["model"] = endpoint.model
+        else:
+            upstream_payload.pop("model", None)
+        headers = {
+            "Accept": "application/json",
+            "Accept-Encoding": "identity",
+            "Content-Type": "application/json",
+        }
+        if endpoint.api_key:
+            headers["Authorization"] = f"Bearer {endpoint.api_key}"
+
+        started = self._clock()
+        try:
+            async with self._client.stream(
+                "POST",
+                endpoint.url,
+                headers=headers,
+                json=upstream_payload,
+            ) as response:
+                if response.is_redirect:
+                    raise ArenaUpstreamError(
+                        "The selected model returned an unsupported redirect."
+                    )
+                if response.status_code >= 400:
+                    raise ArenaUpstreamError(
+                        "The selected model could not complete this turn."
+                    )
+                if response.headers.get("content-encoding", "identity").lower() != "identity":
+                    raise ArenaUpstreamError(
+                        "The selected model returned an unsupported encoding."
+                    )
+                body = await self._read_response_body(response)
+        except httpx.HTTPError as exc:
+            # httpx exceptions are intentionally not reflected to the browser;
+            # messages can contain upstream topology.
+            raise ArenaUpstreamError(
+                "The selected model did not respond in time."
+            ) from exc
+        request_ms = max(0.0, (self._clock() - started) * 1_000)
+        try:
+            document = json.loads(body)
+        except (TypeError, ValueError, UnicodeError) as exc:
+            raise ArenaUpstreamError(
+                "The selected model returned invalid JSON."
+            ) from exc
+        if not isinstance(document, dict):
+            raise ArenaUpstreamError(
+                "The selected model returned an invalid response envelope."
+            )
+        answers = document.get("answers")
+        placement = answers.get("placement") if isinstance(answers, dict) else None
+        choice = placement.get("choice") if isinstance(placement, dict) else None
+        if not isinstance(choice, str) or choice not in legal_choices:
+            raise ArenaUpstreamError(
+                "The selected model did not return a legal placement."
+            )
+        provider_model = document.get("model")
+        self._validate_provider_model(endpoint, provider_model)
+        timing = document.get("timing")
+        inference_ms = timing.get("inference_ms") if isinstance(timing, dict) else None
+        if (
+            competitor.family != "decision"
+            or isinstance(inference_ms, bool)
+            or not isinstance(inference_ms, (int, float))
+            or not math.isfinite(inference_ms)
+            or inference_ms < 0
+        ):
+            inference_ms = None
+        return DecisionOutcome(
+            choice=choice,
+            request_ms=request_ms,
+            provider_model=provider_model,
+            inference_ms=float(inference_ms) if inference_ms is not None else None,
+        )
+
+    @staticmethod
+    async def _read_response_body(response: Any) -> bytes:
+        body = bytearray()
+        async for chunk in response.aiter_raw(chunk_size=64 * 1024):
+            body.extend(chunk)
+            if len(body) > MAX_UPSTREAM_BYTES:
+                raise ArenaUpstreamError(
+                    "The selected model returned an oversized response."
+                )
+        return bytes(body)
+
+    @staticmethod
+    def _validate_provider_model(endpoint: Endpoint, provider_model: Any) -> None:
+        if not isinstance(provider_model, str) or not provider_model:
+            raise ArenaUpstreamError("The selected model returned no model identity.")
+        if endpoint.identity_policy == "exact":
+            if endpoint.model is None or provider_model != endpoint.model:
+                raise ArenaUpstreamError(
+                    "The selected endpoint returned a different model identity."
+                )
+            return
+        if endpoint.identity_policy == "jev_alias_or_version":
+            requested = endpoint.model
+            if requested not in {None, "jev-latest"}:
+                if provider_model != requested:
+                    raise ArenaUpstreamError(
+                        "Jev returned a different pinned model identity."
+                    )
+                return
+            if provider_model == "jev-latest" or _JEV_VERSION.fullmatch(provider_model):
+                return
+            raise ArenaUpstreamError("Jev returned an unsupported model identity.")
+        raise RuntimeError("unknown endpoint identity policy")
+
+
+@dataclass
+class SideResult:
+    side: str
+    competitor_id: str
+    display_name: str
+    status: str
+    reason: str
+    score: int
+    lines: int
+    pieces: int
+    duration_ms: float
+    total_request_ms: float
+
+    def public(self, *, include_duration: bool = True) -> dict[str, Any]:
+        result = {
+            "side": self.side,
+            "competitor_id": self.competitor_id,
+            "display_name": self.display_name,
+            "status": self.status,
+            "reason": self.reason,
+            "score": self.score,
+            "lines": self.lines,
+            "pieces": self.pieces,
+        }
+        if include_duration:
+            result["duration_ms"] = round(self.duration_ms, 3)
+            result["total_request_ms"] = round(self.total_request_ms, 3)
+        return result
+
+
+def _advantage(
+    left: float,
+    right: float,
+    *,
+    lower_wins: bool,
+) -> dict[str, Any]:
+    if math.isclose(left, right, rel_tol=1e-9, abs_tol=1e-9):
+        return {"winner": "tie", "percent": 0.0, "unbounded": False}
+    if lower_wins:
+        winner = "left" if left < right else "right"
+        better, worse = sorted((left, right))
+        percent = None if better <= 0 else ((worse / better) - 1) * 100
+    else:
+        winner = "left" if left > right else "right"
+        worse, better = sorted((left, right))
+        percent = None if worse <= 0 else ((better / worse) - 1) * 100
+    return {
+        "winner": winner,
+        "percent": None if percent is None else round(percent, 1),
+        "unbounded": percent is None,
+    }
+
+
+class RaceSession:
+    def __init__(
+        self,
+        *,
+        race_id: str,
+        adapter: Any,
+        left: Competitor,
+        right: Competitor,
+        client_id: str,
+        seed: str | int,
+        mode: str,
+        max_steps: int | None,
+        first_failure_guard: int,
+        race_timeout_seconds: float = DEFAULT_RACE_TIMEOUT_SECONDS,
+        stream_grace_seconds: float = DEFAULT_STREAM_GRACE_SECONDS,
+        clock=time.perf_counter,
+    ):
+        self.id = race_id
+        self.adapter = adapter
+        self.competitors = {"left": left, "right": right}
+        self.client_id = client_id
+        self.seed = seed
+        self.mode = mode
+        self.max_steps = max_steps
+        self.call_budget = 2 * (max_steps or first_failure_guard)
+        self.history_limit = min(MAX_RACE_HISTORY, self.call_budget + 8)
+        self.provider_calls = 0
+        self.first_failure_guard = first_failure_guard
+        self.race_timeout_seconds = race_timeout_seconds
+        self.stream_grace_seconds = stream_grace_seconds
+        sequence_length = (max_steps or first_failure_guard) + 1
+        self.sequence = create_piece_sequence(seed, sequence_length)
+        self.clock = clock
+        self.created_at = self.clock()
+        self.completed_at: float | None = None
+        self.status = "created"
+        self.events: list[dict[str, Any]] = []
+        self.states: dict[str, dict[str, Any]] = {
+            side: {"side": side, "step": 0, "request_ms": None, "game": Game().public()}
+            for side in ("left", "right")
+        }
+        self.traces: dict[str, list[dict[str, Any]]] = {"left": [], "right": []}
+        self.results: dict[str, SideResult] = {}
+        self.summary: dict[str, Any] | None = None
+        self._condition = asyncio.Condition()
+        self._done = asyncio.Event()
+        self._task: asyncio.Task[None] | None = None
+        self._orphan_task: asyncio.Task[None] | None = None
+        self._subscribers = 0
+        self._stop_reason = "cancelled"
+
+    def start(self) -> None:
+        if self._task is not None:
+            raise RuntimeError("race already started")
+        self._task = asyncio.create_task(self._run(), name=f"tetris-race-{self.id}")
+        self._schedule_orphan_watch()
+
+    async def cancel(self, reason: str = "cancelled") -> None:
+        self._stop_reason = reason
+        current = asyncio.current_task()
+        orphan_to_wait: asyncio.Task[None] | None = None
+        if self._orphan_task is not None and self._orphan_task is not current:
+            orphan_to_wait = self._orphan_task
+            self._orphan_task = None
+            orphan_to_wait.cancel()
+        if self._task is not None and not self._task.done():
+            self._task.cancel()
+            try:
+                await self._task
+            except asyncio.CancelledError:
+                pass
+        if orphan_to_wait is not None:
+            await asyncio.gather(orphan_to_wait, return_exceptions=True)
+        # A task cancelled before its coroutine first runs never reaches _run's
+        # finally block. Finalize it here so waiters and capacity accounting do
+        # not retain a permanently "created" race.
+        if not self._done.is_set():
+            self.status = "cancelled"
+            self.completed_at = self.clock()
+            self._done.set()
+            async with self._condition:
+                self._condition.notify_all()
+
+    async def wait(self) -> dict[str, Any]:
+        await self._done.wait()
+        return self.snapshot()
+
+    async def _publish(self, event_type: str, data: Mapping[str, Any]) -> None:
+        event = {
+            "id": len(self.events) + 1,
+            "type": event_type,
+            "data": copy.deepcopy(dict(data)),
+        }
+        async with self._condition:
+            if len(self.events) >= self.history_limit:
+                raise RuntimeError("race event history limit exceeded")
+            self.events.append(event)
+            self._condition.notify_all()
+
+    def _schedule_orphan_watch(self) -> None:
+        if self._done.is_set() or self._subscribers or self.stream_grace_seconds <= 0:
+            return
+        if self._orphan_task is not None and not self._orphan_task.done():
+            return
+        self._orphan_task = asyncio.create_task(
+            self._cancel_if_orphaned(),
+            name=f"tetris-orphan-{self.id}",
+        )
+
+    async def _cancel_if_orphaned(self) -> None:
+        try:
+            await asyncio.sleep(self.stream_grace_seconds)
+            async with self._condition:
+                should_cancel = (
+                    self._subscribers == 0
+                    and not self._done.is_set()
+                    and self.status in {"created", "running"}
+                )
+            if should_cancel:
+                await self.cancel("stream_disconnected")
+        except asyncio.CancelledError:
+            return
+        finally:
+            if self._orphan_task is asyncio.current_task():
+                self._orphan_task = None
+
+    async def iter_events(self, after: int = 0) -> AsyncIterator[dict[str, Any] | None]:
+        cursor = max(0, after)
+        async with self._condition:
+            self._subscribers += 1
+            orphan_task = self._orphan_task
+            self._orphan_task = None
+        if orphan_task is not None:
+            orphan_task.cancel()
+            await asyncio.gather(orphan_task, return_exceptions=True)
+        try:
+            while True:
+                heartbeat = False
+                async with self._condition:
+                    if cursor < len(self.events):
+                        pending = copy.deepcopy(self.events[cursor:])
+                    elif self._done.is_set():
+                        return
+                    else:
+                        try:
+                            await asyncio.wait_for(self._condition.wait(), timeout=10)
+                        except asyncio.TimeoutError:
+                            heartbeat = True
+                        pending = []
+                if heartbeat:
+                    # Yield outside the condition lock: a stalled renderer must never
+                    # prevent either model loop from publishing or scheduling work.
+                    yield None
+                if not pending:
+                    continue
+                for event in pending:
+                    cursor = event["id"]
+                    yield event
+        finally:
+            async with self._condition:
+                self._subscribers = max(0, self._subscribers - 1)
+            self._schedule_orphan_watch()
+
+    def snapshot(self, *, include_traces: bool = False) -> dict[str, Any]:
+        result: dict[str, Any] = {
+            "id": self.id,
+            "status": self.status,
+            "seed": self.seed,
+            "mode": self.mode,
+            "max_steps": self.max_steps,
+            "competitors": {
+                side: competitor.public()
+                for side, competitor in self.competitors.items()
+            },
+            "results": {
+                side: side_result.public() for side, side_result in self.results.items()
+            },
+            "states": copy.deepcopy(self.states),
+            "summary": copy.deepcopy(self.summary),
+        }
+        if include_traces:
+            result["traces"] = copy.deepcopy(self.traces)
+        return result
+
+    async def _run(self) -> None:
+        tasks: dict[str, asyncio.Task[SideResult]] = {}
+        try:
+            self.status = "running"
+            await self._publish(
+                "race.started",
+                {
+                    "race_id": self.id,
+                    "seed": self.seed,
+                    "mode": self.mode,
+                    "max_steps": self.max_steps,
+                    "competitors": {
+                        side: competitor.public()
+                        for side, competitor in self.competitors.items()
+                    },
+                },
+            )
+            tasks = {
+                side: asyncio.create_task(
+                    self._run_side(side, competitor),
+                    name=f"tetris-{self.id}-{side}",
+                )
+                for side, competitor in self.competitors.items()
+            }
+            # asyncio.timeout cancels the awaited child tasks before control
+            # reaches the TimeoutError handler, so publish the intended stop
+            # reason before entering the deadline scope.
+            self._stop_reason = "race_timeout"
+            try:
+                async with asyncio.timeout(self.race_timeout_seconds):
+                    await self._finish_competitors(tasks)
+            except TimeoutError:
+                self._stop_reason = "race_timeout"
+                await self._stop_tasks(tasks)
+                self.status = "timed_out"
+            else:
+                self.status = (
+                    "incomplete"
+                    if any(
+                        result.status in {"error", "guard_reached"}
+                        or (
+                            result.status == "stopped"
+                            and result.reason != "opponent_finished"
+                        )
+                        for result in self.results.values()
+                    )
+                    else "finished"
+                )
+            self.summary = self._build_summary()
+            await self._publish("race.finished", self.summary)
+        except asyncio.CancelledError:
+            await self._stop_tasks(tasks)
+            self.status = "cancelled"
+            raise
+        except Exception:  # noqa: BLE001 - fail closed and terminate both runners
+            self._stop_reason = "internal_error"
+            await self._stop_tasks(tasks)
+            self.status = "error"
+            if len(self.results) == 2:
+                self.summary = self._build_summary()
+                await self._publish("race.finished", self.summary)
+        finally:
+            # A fast race can finish before the browser opens its event stream.
+            # Reclaim the initial reconnect-grace sleeper as soon as the race is
+            # terminal. If that sleeper initiated cancellation, let it unwind
+            # naturally instead of making the two tasks cancel each other.
+            if self.status != "cancelled":
+                orphan_task = self._orphan_task
+                self._orphan_task = None
+                if orphan_task is not None:
+                    orphan_task.cancel()
+                    await asyncio.gather(orphan_task, return_exceptions=True)
+            self.completed_at = self.clock()
+            self._done.set()
+            async with self._condition:
+                self._condition.notify_all()
+
+    async def _finish_competitors(
+        self, tasks: Mapping[str, asyncio.Task[SideResult]]
+    ) -> None:
+        if self.mode == "first_failure":
+            pending = set(tasks.values())
+            while pending:
+                done, pending = await asyncio.wait(
+                    pending, return_when=asyncio.FIRST_COMPLETED
+                )
+                results = [task.result() for task in done]
+                self._record_results(results)
+                if any(result.status in {"game_over", "error"} for result in results):
+                    self._stop_reason = "opponent_finished"
+                    await self._stop_tasks(tasks)
+                    break
+            return
+        self._record_results(await asyncio.gather(*tasks.values()))
+
+    def _record_results(self, values: Any) -> None:
+        for result in values:
+            if isinstance(result, SideResult):
+                self.results[result.side] = result
+
+    async def _stop_tasks(self, tasks: Mapping[str, asyncio.Task[SideResult]]) -> None:
+        for task in tasks.values():
+            if not task.done():
+                task.cancel()
+        completed = await asyncio.gather(*tasks.values(), return_exceptions=True)
+        self._record_results(completed)
+        for side, competitor in self.competitors.items():
+            if side not in self.results and tasks:
+                self.results[side] = SideResult(
+                    side=side,
+                    competitor_id=competitor.id,
+                    display_name=competitor.display_name,
+                    status="stopped",
+                    reason=self._stop_reason,
+                    score=0,
+                    lines=0,
+                    pieces=0,
+                    duration_ms=0,
+                    total_request_ms=0,
+                )
+
+    async def _run_side(self, side: str, competitor: Competitor) -> SideResult:
+        game = Game()
+        started = self.clock()
+        status = "finished"
+        reason = "step_limit"
+        total_request_ms = 0.0
+        limit = self.max_steps if self.mode == "steps" else self.first_failure_guard
+        try:
+            await self._publish(
+                "side.started",
+                {
+                    "side": side,
+                    "competitor": competitor.public(),
+                    "game": game.public(),
+                },
+            )
+            for step in range(limit or 0):
+                piece = self.sequence[step]
+                next_piece = self.sequence[step + 1]
+                placements = enumerate_placements(game, piece)
+                if not placements:
+                    game.game_over = True
+                    status = "game_over"
+                    reason = "no_legal_placement"
+                    break
+                request, state = build_decision_request(
+                    game,
+                    piece,
+                    next_piece,
+                    placements,
+                    competitor.request_model,
+                )
+                before = game.public()
+                legal_choices = frozenset(placement.id for placement in placements)
+                try:
+                    self.provider_calls += 1
+                    outcome = await self.adapter.decide(
+                        competitor,
+                        request,
+                        legal_choices,
+                    )
+                except ArenaUpstreamError as exc:
+                    status = "error"
+                    reason = "provider_error"
+                    trace = {
+                        "step": step + 1,
+                        "piece": piece,
+                        "state": state,
+                        "board_before": before["board"],
+                        "action": None,
+                        "error": str(exc),
+                    }
+                    self.traces[side].append(trace)
+                    await self._publish(
+                        "side.error",
+                        {"side": side, "step": step + 1, "message": str(exc)},
+                    )
+                    break
+                if not isinstance(outcome, DecisionOutcome):
+                    raise TypeError("decision adapter returned an invalid outcome")
+                if not math.isfinite(outcome.request_ms) or outcome.request_ms < 0:
+                    raise TypeError("decision adapter returned an invalid request duration")
+                total_request_ms += outcome.request_ms
+                chosen = next(
+                    (
+                        placement
+                        for placement in placements
+                        if placement.id == outcome.choice
+                    ),
+                    None,
+                )
+                if chosen is None:
+                    # Never replace a model's invalid choice with a heuristic choice.
+                    status = "error"
+                    reason = "invalid_choice"
+                    self.traces[side].append(
+                        {
+                            "step": step + 1,
+                            "piece": piece,
+                            "state": state,
+                            "board_before": before["board"],
+                            "action": outcome.choice,
+                            "error": "invalid_choice",
+                        }
+                    )
+                    await self._publish(
+                        "side.error",
+                        {
+                            "side": side,
+                            "step": step + 1,
+                            "message": "The model returned an invalid placement.",
+                        },
+                    )
+                    break
+                game = apply_placement(game, chosen)
+                after = game.public()
+                trace = {
+                    "step": step + 1,
+                    "piece": piece,
+                    "next_piece": next_piece,
+                    "state": state,
+                    "board_before": before["board"],
+                    "action": chosen.id,
+                    "board_after": after["board"],
+                    "score": game.score,
+                    "lines": game.lines,
+                    "pieces": game.pieces,
+                    "request_ms": round(outcome.request_ms, 3),
+                    "provider_model": outcome.provider_model,
+                }
+                if outcome.inference_ms is not None:
+                    trace["provider_inference_ms"] = round(outcome.inference_ms, 3)
+                self.traces[side].append(trace)
+                step_event = {
+                    "side": side,
+                    "step": step + 1,
+                    "piece": piece,
+                    "next_piece": next_piece,
+                    "choice": chosen.id,
+                    "request_ms": round(outcome.request_ms, 3),
+                    "cleared_rows": list(chosen.cleared_rows),
+                    "game": after,
+                }
+                self.states[side] = step_event
+                await self._publish("side.step", step_event)
+                if game.game_over:
+                    status = "game_over"
+                    reason = "top_out"
+                    break
+            else:
+                if self.mode == "first_failure":
+                    status = "guard_reached"
+                    reason = "operational_guard"
+        except asyncio.CancelledError:
+            status = "stopped"
+            reason = self._stop_reason
+        except Exception:  # noqa: BLE001 - isolate one runner without exposing internals
+            status = "error"
+            reason = "internal_error"
+            await self._publish(
+                "side.error",
+                {
+                    "side": side,
+                    "message": "The server could not complete this model's turn.",
+                },
+            )
+
+        result = SideResult(
+            side=side,
+            competitor_id=competitor.id,
+            display_name=competitor.display_name,
+            status=status,
+            reason=reason,
+            score=game.score,
+            lines=game.lines,
+            pieces=game.pieces,
+            duration_ms=max(0.0, (self.clock() - started) * 1_000),
+            total_request_ms=total_request_ms,
+        )
+        await self._publish(
+            "side.finished",
+            {
+                "side": side,
+                # The in-board card intentionally contains game results only.
+                "result": result.public(include_duration=False),
+            },
+        )
+        return result
+
+    def _build_summary(self) -> dict[str, Any]:
+        left = self.results["left"]
+        right = self.results["right"]
+        comparable_speed = (
+            self.status == "finished"
+            and self.mode == "steps"
+            and left.reason == "step_limit"
+            and right.reason == "step_limit"
+            and left.pieces == right.pieces == self.max_steps
+        )
+        speed = (
+            _advantage(left.total_request_ms, right.total_request_ms, lower_wins=True)
+            if comparable_speed
+            else {"winner": "unavailable", "percent": None, "unbounded": False}
+        )
+        comparable_score = (
+            self.status == "finished"
+            and left.status in {"finished", "game_over"}
+            and right.status in {"finished", "game_over"}
+        )
+        return {
+            "race_id": self.id,
+            "status": self.status,
+            "mode": self.mode,
+            "left": left.public(),
+            "right": right.public(),
+            "speed": {
+                **speed,
+                "basis": "server_observed_request_to_response_e2e_total",
+                "comparable": comparable_speed,
+            },
+            "score": {
+                **(
+                    _advantage(float(left.score), float(right.score), lower_wins=False)
+                    if comparable_score
+                    else {"winner": "unavailable", "percent": None, "unbounded": False}
+                ),
+                "basis": "final_game_score",
+                "comparable": comparable_score,
+            },
+        }
+
+
+@dataclass
+class Admission:
+    """Keep quota accounting without retaining a completed race's traces."""
+
+    session: RaceSession | None
+    created_at: float
+    call_budget: int
+    completed_at: float | None = None
+    provider_calls: int = 0
+
+    def refresh(self) -> None:
+        if self.session is not None and self.session.completed_at is not None:
+            self.completed_at = self.session.completed_at
+            self.provider_calls = self.session.provider_calls
+            self.session = None
+
+    def active(self) -> bool:
+        return self.session is not None and self.session.status in {"created", "running"}
+
+    def charged_calls(self) -> int:
+        if self.session is not None:
+            if self.session.completed_at is None:
+                return self.call_budget
+            return self.session.provider_calls
+        return self.provider_calls
+
+
+class RaceManager:
+    def __init__(
+        self,
+        adapter: Any,
+        *,
+        max_concurrent_races: int = MAX_CONCURRENT_RACES,
+        client_active_races: int = DEFAULT_CLIENT_ACTIVE_RACES,
+        client_races_per_minute: int = DEFAULT_CLIENT_RACES_PER_MINUTE,
+        client_calls_per_window: int | None = None,
+        client_call_window_seconds: float = DEFAULT_CLIENT_CALL_WINDOW_SECONDS,
+        max_steps_limit: int = DEFAULT_MAX_CONFIGURED_STEPS,
+        first_failure_guard: int | None = None,
+        race_timeout_seconds: float = DEFAULT_RACE_TIMEOUT_SECONDS,
+        stream_grace_seconds: float = DEFAULT_STREAM_GRACE_SECONDS,
+        completed_ttl_seconds: float = DEFAULT_COMPLETED_TTL_SECONDS,
+        clock=time.perf_counter,
+    ):
+        if not 1 <= max_steps_limit <= MAX_CONFIGURED_STEPS:
+            raise ValueError("max_steps_limit is out of range")
+        if first_failure_guard is None:
+            first_failure_guard = max_steps_limit
+        if client_calls_per_window is None:
+            client_calls_per_window = max(
+                DEFAULT_CLIENT_CALLS_PER_WINDOW, 2 * max_steps_limit
+            )
+        if max_concurrent_races < 1:
+            raise ValueError("max_concurrent_races must be positive")
+        if client_active_races < 1 or client_active_races > max_concurrent_races:
+            raise ValueError("client_active_races must fit global capacity")
+        if not 1 <= client_races_per_minute <= MAX_CLIENT_RACES_PER_MINUTE:
+            raise ValueError("client_races_per_minute is out of range")
+        if client_calls_per_window < 2 * max_steps_limit:
+            raise ValueError("client_calls_per_window must permit one full race")
+        if client_call_window_seconds <= 0:
+            raise ValueError("client_call_window_seconds must be positive")
+        if not 1 <= first_failure_guard <= max_steps_limit:
+            raise ValueError("first_failure_guard is out of range")
+        if race_timeout_seconds <= 0:
+            raise ValueError("race_timeout_seconds must be positive")
+        if stream_grace_seconds <= 0:
+            raise ValueError("stream_grace_seconds must be positive")
+        if completed_ttl_seconds <= 0:
+            raise ValueError("completed_ttl_seconds must be positive")
+        self.adapter = adapter
+        self.max_concurrent_races = max_concurrent_races
+        self.client_active_races = client_active_races
+        self.client_races_per_minute = client_races_per_minute
+        self.client_calls_per_window = client_calls_per_window
+        self.client_call_window_seconds = client_call_window_seconds
+        self.max_steps_limit = max_steps_limit
+        self.first_failure_guard = first_failure_guard
+        self.race_timeout_seconds = race_timeout_seconds
+        self.stream_grace_seconds = stream_grace_seconds
+        self.completed_ttl_seconds = completed_ttl_seconds
+        self.clock = clock
+        self.sessions: dict[str, RaceSession] = {}
+        self._client_history: dict[str, deque[Admission]] = {}
+        self._lock = asyncio.Lock()
+        self._closing = False
+        self._closed = asyncio.Event()
+        self._reaper_task: asyncio.Task[None] | None = None
+
+    @classmethod
+    def from_environment(
+        cls,
+        adapter: Any,
+        env: Mapping[str, str] | None = None,
+    ) -> RaceManager:
+        env = os.environ if env is None else env
+        max_steps_limit = _environment_int(
+            env, "TETRIS_MAX_STEPS", DEFAULT_MAX_CONFIGURED_STEPS,
+            minimum=1, maximum=MAX_CONFIGURED_STEPS,
+        )
+        return cls(
+            adapter,
+            max_steps_limit=max_steps_limit,
+            first_failure_guard=_environment_int(
+                env, "TETRIS_FIRST_FAILURE_GUARD", max_steps_limit,
+                minimum=1, maximum=max_steps_limit,
+            ),
+            client_active_races=_environment_int(
+                env, "TETRIS_CLIENT_ACTIVE_RACES", DEFAULT_CLIENT_ACTIVE_RACES,
+                minimum=1, maximum=MAX_CONCURRENT_RACES,
+            ),
+            client_races_per_minute=_environment_int(
+                env, "TETRIS_CLIENT_RACES_PER_MINUTE", DEFAULT_CLIENT_RACES_PER_MINUTE,
+                minimum=1, maximum=MAX_CLIENT_RACES_PER_MINUTE,
+            ),
+            client_calls_per_window=_environment_int(
+                env, "TETRIS_CLIENT_CALLS_PER_WINDOW",
+                max(DEFAULT_CLIENT_CALLS_PER_WINDOW, 2 * max_steps_limit),
+                minimum=2 * max_steps_limit, maximum=10_000,
+            ),
+            race_timeout_seconds=_environment_float(
+                env,
+                "TETRIS_RACE_TIMEOUT_SECONDS",
+                DEFAULT_RACE_TIMEOUT_SECONDS,
+                minimum=1,
+                maximum=3_600,
+            ),
+            stream_grace_seconds=_environment_float(
+                env,
+                "TETRIS_STREAM_GRACE_SECONDS",
+                DEFAULT_STREAM_GRACE_SECONDS,
+                minimum=1,
+                maximum=300,
+            ),
+            completed_ttl_seconds=_environment_float(
+                env,
+                "TETRIS_COMPLETED_TTL_SECONDS",
+                DEFAULT_COMPLETED_TTL_SECONDS,
+                minimum=30,
+                maximum=3_600,
+            ),
+        )
+
+    def catalog(self) -> tuple[Competitor, ...]:
+        return tuple(self.adapter.catalog())
+
+    def public_config(self) -> dict[str, Any]:
+        return {
+            "competitors": [competitor.public() for competitor in self.catalog()],
+            "defaults": {
+                "max_steps": min(DEFAULT_MAX_STEPS, self.max_steps_limit),
+                "seed": 42,
+            },
+            "limits": {
+                "max_steps": self.max_steps_limit,
+                "first_failure_guard": self.first_failure_guard,
+            },
+            "modes": ["steps", "first_failure"],
+        }
+
+    async def create(self, value: Any, *, client_id: str = "unknown") -> RaceSession:
+        request = self._validate(value)
+        if not isinstance(client_id, str) or not 1 <= len(client_id) <= 128:
+            raise ArenaValidationError("Invalid client identity.")
+        async with self._lock:
+            if self._closing:
+                raise ArenaValidationError("The arena is shutting down.")
+            self._prune_locked()
+            self._ensure_reaper_locked()
+            self._prune_admissions_locked()
+            active = sum(
+                session.status in {"created", "running"}
+                for session in self.sessions.values()
+            )
+            if active >= self.max_concurrent_races:
+                raise ArenaQuotaError("The arena is busy. Try again shortly.", retry_after=2)
+            history = self._client_history.get(client_id, deque())
+            active_for_client = sum(admission.active() for admission in history)
+            if active_for_client >= self.client_active_races:
+                raise ArenaQuotaError("A race is already active for this client.", retry_after=2)
+            now = self.clock()
+            recent = [
+                admission for admission in history
+                if now - admission.created_at < DEFAULT_CLIENT_WINDOW_SECONDS
+            ]
+            if len(recent) >= self.client_races_per_minute:
+                retry = max(
+                    1,
+                    math.ceil(
+                        DEFAULT_CLIENT_WINDOW_SECONDS - (now - recent[0].created_at)
+                    ),
+                )
+                raise ArenaQuotaError("Race start rate limit reached.", retry_after=retry)
+            cost = 2 * (request["max_steps"] or self.first_failure_guard)
+            used = sum(admission.charged_calls() for admission in history)
+            if used + cost > self.client_calls_per_window:
+                raise ArenaQuotaError("Provider call budget reached.", retry_after=60)
+            if sum(map(len, self._client_history.values())) >= MAX_ADMISSION_HISTORY:
+                raise ArenaQuotaError("The arena is busy. Try again shortly.", retry_after=60)
+            race_id = secrets.token_urlsafe(18)
+            session = RaceSession(
+                race_id=race_id,
+                adapter=self.adapter,
+                left=request["left"],
+                right=request["right"],
+                client_id=client_id,
+                seed=request["seed"],
+                mode=request["mode"],
+                max_steps=request["max_steps"],
+                first_failure_guard=self.first_failure_guard,
+                race_timeout_seconds=self.race_timeout_seconds,
+                stream_grace_seconds=self.stream_grace_seconds,
+                clock=self.clock,
+            )
+            self.sessions[race_id] = session
+            self._client_history.setdefault(client_id, deque()).append(
+                Admission(session, session.created_at, session.call_budget)
+            )
+            session.start()
+            return session
+
+    def get(self, race_id: str) -> RaceSession:
+        self._prune_locked()
+        session = self.sessions.get(race_id)
+        if session is None:
+            raise KeyError(race_id)
+        return session
+
+    async def aclose(self) -> None:
+        async with self._lock:
+            if self._closing:
+                wait_for_close = True
+                reaper = None
+                sessions = ()
+            else:
+                wait_for_close = False
+                self._closing = True
+                reaper = self._reaper_task
+                self._reaper_task = None
+                sessions = tuple(self.sessions.values())
+        if wait_for_close:
+            await self._closed.wait()
+            return
+        try:
+            if reaper is not None:
+                reaper.cancel()
+                await asyncio.gather(reaper, return_exceptions=True)
+            await asyncio.gather(
+                *(session.cancel("shutdown") for session in sessions),
+                return_exceptions=True,
+            )
+            async with self._lock:
+                self.sessions.clear()
+                self._client_history.clear()
+        finally:
+            self._closed.set()
+
+    def _ensure_reaper_locked(self) -> None:
+        if self._reaper_task is None or self._reaper_task.done():
+            self._reaper_task = asyncio.create_task(
+                self._reap_loop(),
+                name="tetris-race-reaper",
+            )
+
+    async def _reap_loop(self) -> None:
+        interval = min(30.0, max(0.1, self.completed_ttl_seconds / 2))
+        try:
+            while True:
+                await asyncio.sleep(interval)
+                async with self._lock:
+                    self._prune_locked()
+                    self._prune_admissions_locked()
+        except asyncio.CancelledError:
+            return
+
+    def _prune_locked(self) -> None:
+        now = self.clock()
+        for race_id, session in tuple(self.sessions.items()):
+            if (
+                session.completed_at is not None
+                and now - session.completed_at >= self.completed_ttl_seconds
+            ):
+                self.sessions.pop(race_id, None)
+        if len(self.sessions) < MAX_RETAINED_RACES:
+            return
+        completed = sorted(
+            (
+                session
+                for session in self.sessions.values()
+                if session.completed_at is not None
+            ),
+            key=lambda session: session.completed_at or session.created_at,
+        )
+        for session in completed[: len(self.sessions) - MAX_RETAINED_RACES + 1]:
+            self.sessions.pop(session.id, None)
+
+    def _prune_admissions_locked(self) -> None:
+        now = self.clock()
+        for client_id, history in tuple(self._client_history.items()):
+            for admission in history:
+                admission.refresh()
+            retained = deque(
+                admission for admission in history
+                if admission.completed_at is None or now - max(
+                    admission.created_at, admission.completed_at
+                ) < max(DEFAULT_CLIENT_WINDOW_SECONDS, self.client_call_window_seconds)
+            )
+            if retained:
+                self._client_history[client_id] = retained
+            else:
+                self._client_history.pop(client_id, None)
+
+    async def cancel(self, race_id: str, *, reason: str = "user_cancelled") -> None:
+        async with self._lock:
+            session = self.sessions.pop(race_id, None)
+        if session is None:
+            raise KeyError(race_id)
+        await session.cancel(reason)
+
+    def _validate(self, value: Any) -> dict[str, Any]:
+        if not isinstance(value, dict):
+            raise ArenaValidationError("Race request must be a JSON object.")
+        allowed = {"left", "right", "seed", "mode", "max_steps"}
+        if set(value) - allowed:
+            raise ArenaValidationError("Race request contains unsupported fields.")
+        by_id = {competitor.id: competitor for competitor in self.catalog()}
+        selected: dict[str, Competitor] = {}
+        for side in ("left", "right"):
+            competitor_id = value.get(side)
+            competitor = by_id.get(competitor_id)
+            if competitor is None or not competitor.ready:
+                raise ArenaValidationError(
+                    f"{side} must select a configured competitor."
+                )
+            selected[side] = competitor
+        seed = value.get("seed", 42)
+        if isinstance(seed, bool) or not isinstance(seed, (str, int)):
+            raise ArenaValidationError("seed must be a string or integer.")
+        if isinstance(seed, str) and (not seed or len(seed) > 128):
+            raise ArenaValidationError("seed must contain 1 to 128 characters.")
+        if isinstance(seed, int) and not -(2**63) <= seed < 2**63:
+            raise ArenaValidationError("integer seed must fit in 64 bits.")
+        mode = value.get("mode", "steps")
+        if mode not in {"steps", "first_failure"}:
+            raise ArenaValidationError("mode must be steps or first_failure.")
+        max_steps = value.get("max_steps", min(DEFAULT_MAX_STEPS, self.max_steps_limit))
+        if mode == "steps":
+            if (
+                isinstance(max_steps, bool)
+                or not isinstance(max_steps, int)
+                or not 1 <= max_steps <= self.max_steps_limit
+            ):
+                raise ArenaValidationError(
+                    f"max_steps must be between 1 and {self.max_steps_limit}."
+                )
+        else:
+            if "max_steps" in value and value["max_steps"] is not None:
+                raise ArenaValidationError(
+                    "max_steps must be null in first_failure mode."
+                )
+            max_steps = None
+        return {**selected, "seed": seed, "mode": mode, "max_steps": max_steps}
+
+
+def encode_sse(event: dict[str, Any] | None) -> bytes:
+    if event is None:
+        return b": keep-alive\n\n"
+    data = json.dumps(event["data"], ensure_ascii=False, separators=(",", ":"))
+    return f"id: {event['id']}\nevent: {event['type']}\ndata: {data}\n\n".encode()
+
+
+__all__ = [
+    "LOCAL_MODELS",
+    "ArenaUpstreamError",
+    "ArenaValidationError",
+    "Competitor",
+    "DecisionOutcome",
+    "Game",
+    "HTTPDecisionAdapter",
+    "RaceManager",
+    "RaceSession",
+    "apply_placement",
+    "build_decision_request",
+    "create_piece_sequence",
+    "encode_sse",
+    "enumerate_placements",
+]