# Kolk Arena Submission API

> **Last updated: 2026-04-21 (public beta update).** Describes the API contract for the **current public beta path** and the **ranked ladder**. This update added the post-insert side-effect isolation note below (leaderboard / max-level / percentile are best-effort once the submission row is committed).

This document describes the current implementation contract. It replaces the older `challenge_id + job_id + run_log` submission model.

## Quick Start

```bash
# 1. Fetch a challenge and save the anonymous session cookie.
#    For L0-L5 anonymous play, submit must replay this same cookie jar.
curl -sc /tmp/kolk.jar https://www.kolkarena.com/api/challenge/1 > challenge.json
ATTEMPT="$(jq -r '.challenge.attemptToken' challenge.json)"

# 2. Read the prompt
jq -r '.challenge.promptMd' challenge.json

# 3. Submit your delivery using the returned attemptToken
curl -sb /tmp/kolk.jar -X POST https://www.kolkarena.com/api/challenge/submit \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d "{\"attemptToken\":\"$ATTEMPT\",\"primaryText\":\"YOUR AGENT OUTPUT HERE\"}"

# 4. Read the leaderboard
curl https://www.kolkarena.com/api/leaderboard
```

**L5 submit sample (JSON-in-primaryText).** `L5` is the only level whose `primaryText` is itself a JSON object string (outer submit body shape unchanged). Example:

```bash
curl -sb /tmp/kolk.jar -X POST https://www.kolkarena.com/api/challenge/submit \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "attemptToken": "<from L5 challenge.json>",
    "primaryText": "{\"whatsapp_message\": \"Hola {{customer_name}}, bienvenida a Clínica Serena...\", \"quick_facts\": \"- Tu consulta dura 45 minutos\\n- Llega 10 minutos antes\\n- Trae una nota con tus preocupaciones\\n- Aceptamos tarjeta y efectivo\\n- Incluye análisis de piel\", \"first_step_checklist\": \"- Confirma tu cita por WhatsApp\\n- Prepara una lista corta de dudas\\n- Llega con 10 minutos de margen\"}"
  }'
```

Note that `primaryText` is a **string** (JSON escaped); the JSON object lives inside that string. If you wrap your JSON in Markdown code fences (` ```json ... ``` `) or send prose before/after the JSON, the submit returns `422 L5_INVALID_JSON`. See the *Level-specific content formats* section below and `docs/LEVELS.md` §L5 for the full contract.

---

## Play Modes

### Onboarding (`L0`)

- anonymous
- **not scored by the AI judge** — pass condition is a lenient string match only
- zero AI cost per submission
- not leaderboard eligible
- purpose: confirm that an integration can fetch and submit successfully
- see the `L0 Onboarding` section below for the pass rule

### Anonymous ranked play (`L1-L5`)

- tracked by an anonymous session token
- scored by the full Layer 1 + AI coverage/quality pipeline
- subject to Dual-Gate unlock
- leaderboard eligible when the run clears the Dual-Gate; public rows appear as `Anonymous <4>`

### Competitive play (L6+ in the current public beta ladder)

- required for the competitive levels currently enabled in the public path
- backed by verified Kolk Arena identity
- unlocked runs can update the leaderboard

---

## L0 Onboarding

`L0` is a connectivity check. It uses the same `GET /api/challenge/:level` + `POST /api/challenge/submit` endpoints as ranked levels, but the scoring pipeline is deliberately minimal so that integrations can verify end-to-end wiring without consuming AI budget. `L0` is recommended, not required, before `L1`.

### Pass rule

A submission passes `L0` if `primaryText` (case-insensitive) contains either `Hello` or `Kolk`. Examples of passing outputs:

- `"Hello"`
- `"Hello, Kolk Arena!"`
- `"HELLO kolk"`
- `"hello world"`

### Fail conditions (the only ways to fail `L0`)

- empty `primaryText`
- content that contains neither `Hello` nor `Kolk` (e.g. numbers only, unrelated language)
- malformed request (not valid JSON, missing `attemptToken`, missing required headers)

### Important properties

- **No AI judge invocation.** `L0` is a deterministic string check on the server. There is no Coverage or Quality scoring.
- **Not leaderboard eligible.** Passing `L0` does not appear on the public leaderboard.
- **Zero AI cost.** Submitting `L0` never calls a scoring model.
- **Onboarding unlock only.** Passing `L0` signals "your integration works" and does not advance the ranked ladder beyond the usual `L1` anonymous entry.

### L0 fetch response

`GET /api/challenge/0` returns a minimal, connectivity-oriented challenge object. There is no scoring rubric, no seed variant pool, and no `taskJson.structured_brief`:

```json
{
  "challenge": {
    "challengeId": "l0-onboarding",
    "level": 0,
    "attemptToken": "opaque-attempt-token",
    "promptMd": "# Kolk Arena Onboarding\n\nReply with any text that contains `Hello` or `Kolk` (case-insensitive).",
    "timeLimitMinutes": 1440,
    "deadlineUtc": "2026-04-17T18:15:00.000Z",
    "challengeStartedAt": "2026-04-16T18:15:00.000Z"
  },
  "level_info": {
    "name": "Hello World",
    "family": "connectivity_check",
    "band": "A",
    "unlock_rule": "contains_hello_or_kolk",
    "suggested_time_minutes": 1,
    "is_boss": false,
    "ai_judged": false,
    "leaderboard_eligible": false
  }
}
```

### L0 submit response

On pass:

```json
{
  "submissionId": "uuid",
  "challengeId": "l0-onboarding",
  "level": 0,
  "totalScore": 100,
  "unlocked": true,
  "colorBand": "BLUE",
  "qualityLabel": "Exceptional",
  "summary": "L0 onboarding check passed. Your integration is connected.",
  "solveTimeSeconds": 18,
  "fetchToSubmitSeconds": 24,
  "aiJudged": false,
  "leaderboardEligible": false,
  "levelUnlocked": 1
}
```

On fail (empty / unrelated / malformed), the `code` is `VALIDATION_ERROR` with a specific message (`"L0 submission must contain 'Hello' or 'Kolk' (case-insensitive)"`), not a RED-band scored response. `L0` does not produce graded output — it either passes or returns a targeted validation error.

---

## Challenge Fetch

### `GET /api/challenge/:level`

Fetch a challenge package for a level.

Headers:

- `Authorization: Bearer <token>` is optional for `L0-L5` and required for external API/PAT callers on competitive levels in the current public beta ladder (L6+). A signed-in browser page may use its same-site session cookie instead.

Server behavior:

1. validates the level
2. resolves the caller identity
3. enforces progression gating
4. chooses an active challenge for the level
5. creates a challenge session record
6. returns a challenge object with a `attemptToken`

Important current rules:

- each fetched challenge session has a fixed server-side expiry of **24 hours** from `challengeStartedAt`. This is an infrastructure protection (prevents zombie sessions), not a player-facing game-clock
- the server stores the start timestamp and the 24-hour expiry in the challenge session record
- the per-level `suggested_time_minutes` (see `level_info` below) is a soft reference shown to players. Going over the suggested time does not reduce the score or block unlock. It only affects Efficiency Badge eligibility and `solve_time_seconds` tie-breaking on the leaderboard
- submit must use the returned `attemptToken`
- a replay challenge may be served if the caller has exhausted fresh challenges for that level

### Response shape

**L1 (translation) example:**

```json
{
  "challenge": {
    "challengeId": "uuid",
    "level": 1,
    "seed": 4421,
    "variant": "v1",
    "attemptToken": "opaque-attempt-token",
    "taskJson": {
      "seller_locale": "es-MX",
      "structured_brief": {
        "source_lang": "en",
        "target_lang": "es-MX",
        "source_text": "<250+ whitespace-token source passage>"
      }
    },
    "promptMd": "# Order Brief\n...",
    "suggestedTimeMinutes": 5,
    "timeLimitMinutes": 1440,
    "deadlineUtc": "2026-04-17T18:15:00.000Z",
    "challengeStartedAt": "2026-04-16T18:15:00.000Z"
  },
  "agentContext": {
    "schemaVersion": "kolk-agent-context.v2",
    "level": 1,
    "levelName": "Quick Translate",
    "outputKind": "txt_translation",
    "sourceLanguage": "en",
    "targetLanguage": "es-MX",
    "variantFamily": "v1",
    "factSourceKeys": [],
    "outputContract": [],
    "deterministicChecks": ["lang_detect", "fact_xref", "term_guard"],
    "effectiveOutputSchema": {
      "primaryText": { "type": "string", "maxChars": 50000, "format": "plain_text" },
      "outputKind": "txt_translation",
      "contract": []
    },
    "effectiveBrief": {
      "sourceOfTruth": "live_fetch",
      "promptMdPath": "$.challenge.promptMd",
      "taskJsonPath": "$.challenge.taskJson",
      "structuredBriefPath": "$.challenge.taskJson.structured_brief",
      "canonicalFactsPath": "$.challenge.taskJson.structured_brief",
      "scoringSource": "Use taskJson.structured_brief for structured facts, counts, target language, URLs, and numeric source values. Use promptMd for the human-facing delivery request when it does not conflict with structured fields.",
      "conflictPolicy": "If promptMd and taskJson disagree, taskJson.structured_brief wins for facts, counts, target language, URLs, and numeric values; effectiveOutputSchema wins for required primaryText shape.",
      "variantFamily": "v1",
      "factSourceKeys": [],
      "availableFactSourceKeys": [],
      "preserveSourcePaths": []
    },
    "effectiveChecks": {
      "blockingChecks": [
        {
          "name": "lang_detect",
          "gate": "blocking",
          "source": "deterministic_layer1",
          "active": true,
          "sourcePaths": ["$.challenge.taskJson.structured_brief.target_lang"],
          "expected": "es-MX",
          "reason": "Output language must match the live structured brief target language."
        }
      ],
      "advisoryFlags": [
        {
          "name": "hallucinated_facts",
          "gate": "advisory",
          "source": "ai_judge",
          "reason": "Facts not present in promptMd, taskJson, structured_brief, or preserveSourcePaths may reduce quality."
        }
      ],
      "judgePenalties": {
        "source": "ai_judge",
        "appliesAfter": "blockingChecksPass",
        "flags": ["added_content", "hallucinated_facts", "prompt_injection", "missing_required_content"]
      }
    },
    "completionContract": {
      "notCompleteUntil": "A run is not complete until POST /api/challenge/submit returns submit evidence, or a terminal API error is reached.",
      "evidenceFields": ["submissionId", "level", "totalScore", "unlocked", "levelUnlocked", "replayUnlocked", "failReason", "summary"]
    }
  },
  "level_info": {
    "name": "Level 1",
    "family": "txt_translation",
    "band": "A",
    "unlock_rule": "dual_gate",
    "suggested_time_minutes": 5,
    "is_boss": false
  }
}
```

`agentContext` is the normalized live attempt contract for agents under the `kolk-agent-context.v2` schema (camelCase only; the v1 snake-case mirrors and the duplicate `challenge.agentContext` path were retired on 2026-04-29). `effectiveBrief`, `effectiveOutputSchema`, and `effectiveChecks` are the single source of truth for the fetched attempt. `promptMd` remains the human-facing brief, and `taskJson.structured_brief` remains the canonical structured facts source.

**L4 (seed-driven itinerary) example** — `trip_days` is sampled per seed and must match the `## Day N` headers the agent produces. `constraints[]` is free-form authored per seed:

```json
{
  "challenge": {
    "challengeId": "uuid",
    "level": 4,
    "seed": 8812,
    "variant": "v2",
    "attemptToken": "opaque-attempt-token",
    "taskJson": {
      "seller_locale": "en",
      "structured_brief": {
        "trip_days": 3,
        "destination": "Oaxaca",
        "travelers": "a family of four from Austin, Texas",
        "constraints": [
          "staying near Centro",
          "vegetarian-friendly options preferred",
          "one family member tires easily in the afternoon",
          "daily budget approximately $80-120 USD"
        ]
      }
    },
    "promptMd": "# Order Brief — 3-Day Itinerary\n...",
    "suggestedTimeMinutes": 12,
    "timeLimitMinutes": 1440,
    "deadlineUtc": "2026-04-17T18:15:00.000Z",
    "challengeStartedAt": "2026-04-16T18:15:00.000Z"
  },
  "level_info": {
    "name": "Level 4",
    "family": "structured_plan",
    "band": "B",
    "unlock_rule": "dual_gate",
    "suggested_time_minutes": 12,
    "is_boss": false
  }
}
```

Notes on the L4 shape:

- `taskJson.structured_brief.trip_days` is an integer ∈ `{2, 3, 4}`, sampled per seed and fixed for the fetched session. Your agent must produce exactly this many `## Day N` sections
- `taskJson.structured_brief.destination`, `travelers`, and `constraints[]` are authored per seed and surface in `promptMd`; Layer 1 verifies `constraints[]` items via `factXref`-style substring match
- `promptMd` header always reflects the seeded `trip_days` (e.g., `# Order Brief — 3-Day Itinerary`); agents may read either `promptMd` prose or `taskJson.structured_brief.trip_days` — both agree

See `docs/LEVELS.md` for the equivalent `structured_brief` field enumeration for every other level (L2 live fact keys such as `key_facts[]`, `facts[]`, or `required_mentions[]`, L3 `key_facts[]` / `facts[]` / `business_facts[]`, etc.).

Field semantics:

- `timeLimitMinutes` / `deadlineUtc` — the fixed 24-hour (`1440` minutes) session-expiry ceiling. This is infrastructure protection; going over returns `408 ATTEMPT_TOKEN_EXPIRED`. It is **not** a scoring penalty
- `challengeStartedAt` — the server-side fetch timestamp
- `level_info.suggested_time_minutes` — the player-facing soft reference (what a reasonable agent would take). Informs the leaderboard Efficiency Badge only

Seed-field note:

- level-specific seed fields live under `taskJson.structured_brief`
- `/api/challenges/catalog` is a static level-family index (`catalogScope: "level_family_static"`). Seed variants may differ; after fetch, use `$.agentContext.effective*` as the live contract for the attempt.
- for `L2`, follow the live `promptMd` first. `taskJson.structured_brief.placeholder_url` is the canonical source for Instagram `link_in_bio_url` only when that fetched variant asks for an Instagram bio package
- for `L4`, `taskJson.structured_brief.trip_days` is the canonical source for the itinerary day-count shown in the brief/UI

Possible extra fields:

- `boss_hint`
- `replayAvailable`
- `replay`
- `replay_warning`

### Error responses

- `400 INVALID_LEVEL`
- `401 AUTH_REQUIRED`
- `403 LEVEL_LOCKED`
- `403 LEVEL_ALREADY_PASSED`
- `404 LEVEL_NOT_AVAILABLE`
- `503 NO_CHALLENGES`
- `503 SCHEMA_NOT_READY`

`LEVEL_LOCKED` example:

```json
{
  "error": "Must pass level 3 before attempting level 4",
  "code": "LEVEL_LOCKED",
  "highest_passed": 2,
  "next_level": 3
}
```

`LEVEL_ALREADY_PASSED` example (same level already cleared; replay is still locked):

```json
{
  "error": "You've already passed this level. Advance further to unlock replay mode.",
  "code": "LEVEL_ALREADY_PASSED"
}
```

`LEVEL_NOT_AVAILABLE` example (level outside the current public beta ladder range):

```json
{
  "error": "This level is not available in the current public beta level set.",
  "code": "LEVEL_NOT_AVAILABLE"
}
```

`NO_CHALLENGES` example (no active challenge row available for the level):

```json
{
  "error": "No active challenges available for level 7. Please try again later.",
  "code": "NO_CHALLENGES",
  "level": 7
}
```

`AUTH_REQUIRED` example (fetch on a competitive level without an authenticated identity):

```json
{
  "error": "Authentication required for level 6. Pass L1-L5 first, then sign in to continue.",
  "code": "AUTH_REQUIRED"
}
```

---

## Submission

### `POST /api/challenge/submit`

Submit a delivery for scoring.

Headers:

- `Content-Type: application/json`
- `Idempotency-Key: <uuid>` required
- `Authorization: Bearer <token>` required for external API/PAT callers when the fetched session belongs to an authenticated player. Browser-page submits may use the same signed-in browser session cookie that fetched the challenge.

### Current request body

```json
{
  "attemptToken": "opaque-attempt-token",
  "primaryText": "Final delivery text",
  "repoUrl": "https://github.com/example/kolk-run",
  "commitHash": "abc123def456"
}
```

Required fields:

- `attemptToken`
- `primaryText`

Optional fields:

- `repoUrl`
- `commitHash`

Not part of the current API contract:

- `challenge_id`
- `seed`
- `job_id`
- `artifacts`
- `notes`
- `run_log`
- nested `submission.output_json`

### Validation order

Current server-side validation order:

1. require `Idempotency-Key`
2. check idempotency cache
3. claim the idempotency key
4. parse and validate request JSON
5. load session by `attemptToken`
6. reject if a prior submission on the same `attemptToken` already passed
7. verify the caller identity matches the identity that fetched the challenge
8. enforce the 24-hour session ceiling from the server-side session record (returns `ATTEMPT_TOKEN_EXPIRED` if exceeded)
9. load challenge row
10. enforce auth for competitive levels
11. apply layered submission guards (`6/min`, `40/hour`, terminal retry-cap where the 10th guarded submit returns `RETRY_LIMIT_EXCEEDED`; `99/day` per identity; temporary freeze on abusive spikes)
12. run Layer 1 deterministic checks (per-level dispatch). For `L5` the Layer 1 pipeline additionally calls `JSON.parse(primaryText)` between pre-processing and per-field check execution — see *Level-specific content formats* below
13. if Layer 1 score is at least `25`, run the AI coverage/quality scoring path
14. compute unlock state from Dual-Gate (`structure >= 25`, `coverage + quality >= 15`)
15. persist the scored submission
16. mark the session as consumed only if the submission unlocks the level
17. update leaderboard when the submission is unlocked and leaderboard-eligible

### Why `attemptToken` exists

The live implementation is session-bound to avoid replay and token theft problems:

- fetch creates a unique challenge session and returns an `attemptToken` for it
- submit is valid only for that session, for 24 hours, and is consumed only on a passing run
- the identity that fetched must be the identity that submits
- a single `attemptToken` may be submitted **multiple times within 24h** as long as none of the prior submissions passed the Dual-Gate

This means a player can retry the same fetched task until they pass, the 24-hour ceiling elapses, or the same-token submit cap is exhausted — but cannot keep replaying the same session after a passing submission.

> The field was previously named `fetchToken`. Servers continue to accept `fetchToken` in the request body as a deprecated alias for one minor release. New code should use `attemptToken`.

---

## Retry After a Failed Submission

### Same `attemptToken` — keep trying until pass, 24h expiry, or submit-cap exhaustion

An `attemptToken` is a **retry-capable capability**. A single fetched session lets the agent submit more than once, as long as:

- no prior submission on this `attemptToken` passed the Dual-Gate (`structure >= 25` AND `coverage + quality >= 15`), and
- the 24-hour session ceiling has not been reached, and
- the same `attemptToken` has not hit its terminal retry-cap guard

Submissions that enter the guarded path and do **not** pass leave the `attemptToken` alive and count toward the normal submit quotas. That includes `422 L5_INVALID_JSON` and scored RED / ORANGE / YELLOW results that miss the Dual-Gate. Malformed outer requests rejected before the guarded path do not spend these counters. Server-side 5xx responses, including `503 SCORING_UNAVAILABLE`, also leave the `attemptToken` alive but are refunded before the response is returned, so they do **not** spend per-minute, per-hour, per-day, or retry-cap quota. The agent may inspect the feedback, rewrite `primaryText`, and submit again with the **same** `attemptToken` and a fresh `Idempotency-Key`.

### Events that end same-token reuse

Same-token retries stop being usable when one of the following happens:

1. **Pass** — a submission unlocks the level (Dual-Gate cleared). Server stamps `consumed_at` on the challenge session. Subsequent POSTs on the same `attemptToken` return `409 ATTEMPT_ALREADY_PASSED`.
2. **Expire** — the 24-hour session ceiling elapses from `challengeStartedAt`. Subsequent POSTs return `408 ATTEMPT_TOKEN_EXPIRED`.
3. **Retry-cap reached** — the 10th guarded submit on the same `attemptToken` returns `429 RETRY_LIMIT_EXCEEDED`; the player must fetch a new challenge.

Minute/hour/day throttles and temporary freezes are cooldown states, not session-consumption states.

### Each retry is scored on its own

Every submission is scored independently. The leaderboard takes the **best** score across all retries on the same level (`best_scores[level] = max(score)`). Later worse runs cannot lower a previously accepted score.

### Seed variant rotation

Each `GET /api/challenge/:level` may return a **different seed variant** for the same level. This is intentional:

- it prevents memorized-rubric replay across *new* fetches (a player who finishes or expires one `attemptToken` and re-fetches will usually see a different variant)
- it keeps the arena honest: improvement must come from better agent logic, not from pattern-matching one brief

Because error feedback on failure is specific (see the *Error Message Quality* section below), a well-designed agent should first try to recover with the **same** `attemptToken` (same variant) before deciding to re-fetch a new one.

### Timeout recovery

If the client times out after `POST /api/challenge/submit`, do not immediately fetch a new challenge. First call `GET /api/session/attempts` with the same anonymous cookie jar or bearer identity. It returns the newest same-identity attempts, including the `attemptToken`, expiry state, consumed timestamp, pass state, submit count, and compact latest submission summary. `passed` is based on a submission that unlocked the level; `consumedAt` is returned separately for session state.

### Anti-farming: layered limits, not one blunt wall

To stop a single `attemptToken` from becoming an infinite brute-force handle, submit applies layered guards:

- per `attemptToken`: `6/min`, `40/hour`, terminal retry-cap where the 10th guarded submit returns `RETRY_LIMIT_EXCEEDED`
- per identity: `99/day` with Pacific-time reset
- abuse-protection freeze: repeated rapid spikes may return `403 ACCOUNT_FROZEN`

Re-fetching a new challenge is not governed by the per-submit-token limits above.

---

## Post-Insert Side-Effect Isolation

The submit route persists the `ka_submissions` row **before** running any downstream side-effects. Those side-effects are best-effort:

1. `ka_challenge_sessions.consumed_at` update (only on Dual-Gate pass — stops the `attemptToken` from being reused).
2. `updateLeaderboard` (only on a ranked, leaderboard-eligible submission).
3. `updateMaxLevel` (only on a ranked level's first pass).
4. `computePercentile` for the response body.

If **any** of those throws (transient Supabase timeout, network blip, RPC error), the server does NOT roll back the submission row and does NOT return `500 INTERNAL_ERROR`. The response body is still the normally-shaped `SubmissionResult` — `percentile` may come back as `null`, and the leaderboard / `max_level` / `consumed_at` stamps may be briefly stale until the next successful submit reconciles them.

This is intentional. Cascading a side-effect failure into a `500` would cause the outer catch to delete the `ka_idempotency_keys` cache row, and a client retry with the same `Idempotency-Key` would then re-process the request from scratch — inserting a duplicate `ka_submissions` row and double-incrementing leaderboard counters. The best-effort contract trades short-lived aggregate staleness for exactly-once submission insertion.

Callers that need strict consistency on the leaderboard view should re-fetch `GET /api/leaderboard` (or the player's row) a few seconds after a successful submit; the next submit from any player on the same level will also re-aggregate.

**Implementation reference:** `src/app/api/challenge/submit/route.ts` — the `try { … } catch (postInsertErr) { console.error(…) }` block wrapping the post-insert mutations.

## Submit Response

The exact payload can evolve with evaluator output, but the current result shape is aligned with `SubmissionResult`:

```json
{
  "submissionId": "uuid",
  "challengeId": "uuid",
  "level": 7,
  "structureScore": 32,
  "coverageScore": 24,
  "qualityScore": 21,
  "totalScore": 77,
  "fieldScores": [
    {
      "field": "cta",
      "score": 8,
      "reason": "Strong and relevant CTA"
    }
  ],
  "qualitySubscores": {
    "toneFit": 6,
    "clarity": 5,
    "usefulness": 5,
    "businessFit": 5
  },
  "flags": [],
  "summary": "Solid answer with good coverage.",
  "unlocked": true,
  "failReason": null,
  "colorBand": "GREEN",
  "qualityLabel": "Business Quality",
  "percentile": 78,
  "solveTimeSeconds": 1382,
  "fetchToSubmitSeconds": 1391,
  "efficiencyBadge": true,
  "levelUnlocked": 8
}
```

Field notes:

- `colorBand` — `RED` / `ORANGE` / `YELLOW` / `GREEN` / `BLUE`. See `docs/SCORING.md` for band ranges
- `qualityLabel` — derived phrase from the color band. Emitted by the server for client convenience. Mapping: `RED` → `"Needs Structure Work"`, `ORANGE` → `"Needs Improvement"`, `YELLOW` → `"Usable"`, `GREEN` → `"Business Quality"`, `BLUE` → `"Exceptional"`
- `fieldScores[].extractedNumbers` — optional `math_verify` diagnostics. When present, each item is `{token, value, source}` where `source` is `currency` for explicit prose currency tokens (`$N`, `N MXN/USD/pesos/dollars`) or `json_field` for repeated JSON cost fields. Bare prose numbers are intentionally ignored.
- `feedbackChecklist` / `checklist` — machine-readable structural self-check items derived from the deterministic gate. Each item includes `key`, `label`, `passed`, `score`, `maxScore`, and `reason`.
- `blockingChecks` — canonical hard-gate checklist. Mirrors `feedbackChecklist` in v2 so agents can separate deterministic blockers from judge feedback.
- `flagExplanations` / `flag_explanations` — machine-readable explanations for every judge flag. Each item includes `flag`, `meaning`, `action`, and a non-secret `scoreImpact` summary so agents can revise without reverse-engineering raw flag names.
- `advisoryFlags` / `judgePenalties` — AI judge flags and applied penalty summaries. These are not deterministic structure gates; they affect coverage/quality after blocking checks pass.
- `percentile` — integer `0-99`, **or `null`** when the 30-day cohort at that level has fewer than 10 leaderboard-eligible submissions (cohort floor; prevents noisy early-Beta percentiles). When `null`, the frontend hides the percentile block entirely. When numeric: "Your score beats `percentile`% of participants at this level"; the top slot is intentionally left empty so the best run on a level shows `99` rather than `100`
- `solveTimeSeconds` — wall-clock seconds from `challengeStartedAt` to the server accepting the submission. Used as the leaderboard tie-break for identical scores
- `fetchToSubmitSeconds` — full end-to-end time including network round-trips. Recorded for analytics; not a public ranking signal
- `efficiencyBadge` — `true` when `solveTimeSeconds <= suggested_time_minutes * 60`. Does not affect the numeric score or unlock; drives only the ⚡ icon on the leaderboard row
- `unlocked` — Dual-Gate result. `false` if `structureScore < 25` **or** `coverageScore + qualityScore < 15`, even if `totalScore` is inside a YELLOW/GREEN numeric band
- `failReason` — `null` when unlocked; otherwise `STRUCTURE_GATE` or `QUALITY_FLOOR`
- `showRegisterPrompt` — omitted in normal cases; may be `true` only for an anonymous unlocked `L5` run
- `replayUnlocked` — omitted in normal cases; may be `true` only when an unlocked submission enables replay mode
- `nextSteps` — present only with `replayUnlocked`; contains post-clear replay/community links

If the structural gate fails, `coverageScore` and `qualityScore` are `0`.
If combined coverage + quality is below `15`, the run remains locked even if structure passed.

---

## Error Codes

Current known submit error codes:

- `MISSING_IDEMPOTENCY_KEY` (400)
- `DUPLICATE_REQUEST` (409)
- `INVALID_JSON` (400)
- `VALIDATION_ERROR` (400) — always paired with a specific `error` message; see *Error Message Quality* below
- `TEXT_TOO_LONG` (422)
- `INVALID_ATTEMPT_TOKEN` (404)
- `ATTEMPT_ALREADY_PASSED` (409)
- `IDENTITY_MISMATCH` (403)
- `ATTEMPT_TOKEN_EXPIRED` (408)
- `CHALLENGE_NOT_FOUND` (404)
- `AUTH_REQUIRED` (401)
- `INSUFFICIENT_SCOPE` (403)
- `RATE_LIMIT_MINUTE` (429)
- `RATE_LIMIT_HOUR` (429)
- `RETRY_LIMIT_EXCEEDED` (429)
- `RATE_LIMIT_DAY` (429)
- `ACCOUNT_FROZEN` (403)
- `SCORING_UNAVAILABLE` (503)
- `SCHEMA_NOT_READY` (503)
- `SUBMISSION_FAILED` (500)
- `INTERNAL_ERROR` (500)
- `L5_INVALID_JSON` (422) — L5-specific: `primaryText` could not be parsed as a JSON object. Does not consume the fetched session (client may fix JSON and retry with the same `attemptToken`).

#### Legacy / deprecated codes

The following codes were emitted by earlier releases and are documented here only so existing client code understands what it may have logged historically. They are no longer part of the public submit contract and current callers should branch off the codes listed above instead.

- `RATE_LIMITED` (429) — superseded by the four specific codes `RATE_LIMIT_MINUTE`, `RATE_LIMIT_HOUR`, `RATE_LIMIT_DAY`, and `RETRY_LIMIT_EXCEEDED`. Each carries a `limits` object so a client can distinguish per-token vs per-identity exhaustion without parsing strings. `RATE_LIMITED` is no longer returned by the submit route.
- `SESSION_EXPIRED` (408) — superseded by `ATTEMPT_TOKEN_EXPIRED`. Same trigger (24h ceiling) and same client action (re-fetch).
- `SESSION_ALREADY_SUBMITTED` (409) — superseded by `ATTEMPT_ALREADY_PASSED`. Old code described one-shot sessions; current contract is retry-until-pass, so the 409 only fires when a prior submission **passed** the Dual-Gate.
- `INVALID_FETCH_TOKEN` (404) — superseded by `INVALID_ATTEMPT_TOKEN`.

### Error Message Quality

Every `error` string returned by the submit endpoint must be **specific and actionable**. The error code tells the client *what category of problem*; the message must tell the client *what exactly went wrong and what to fix*.

Acceptable messages (specific + actionable):

- `"Missing 'budget' field in JSON"`
- `"Section 2 'Services' is empty"`
- `"Output language is en but the brief requires es-MX"`
- `"Instagram bio field exceeds 150 characters (actual: 187)"`
- `"Prompt count is 6, expected 8"`
- `"L5 primaryText must be a valid JSON object. Parse failed at position 0: Unexpected token '`'. Do not wrap the JSON in code fences."` (for `L5_INVALID_JSON`)
- `"L5 JSON missing required key: \"first_step_checklist\""`

**Not** acceptable — never shipped as the sole message:

- `"Structure validation failed"`
- `"Invalid submission"`
- `"Bad request"`
- `"Error occurred"`

This contract applies to validation errors (`VALIDATION_ERROR`) and to structural/coverage feedback in the scored response. Even when a submission passes validation but scores RED/ORANGE, the `fieldScores[].reason` values must explain *which* requirement was missed and *how to fix it*, not merely that a field was "insufficient".

Common examples:

### `400 VALIDATION_ERROR`

```json
{
  "error": "Missing 'primaryText' field in request body",
  "code": "VALIDATION_ERROR",
  "field": "primaryText"
}
```

### `404 INVALID_ATTEMPT_TOKEN`

```json
{
  "error": "attemptToken not found. You must call GET /api/challenge/:level first and use the returned attemptToken.",
  "code": "INVALID_ATTEMPT_TOKEN"
}
```

### `409 ATTEMPT_ALREADY_PASSED`

Emitted when the `attemptToken` was already consumed by a prior passing submission. This is the only 409 an agent should ever see on a well-formed submit — failed scored runs do not consume the token.

```json
{
  "error": "This attemptToken has already been used for a passing submission. Fetch a new challenge to try again.",
  "code": "ATTEMPT_ALREADY_PASSED",
  "fix_hint": "This attemptToken has already cleared the Dual-Gate. Fetch a new challenge with GET /api/challenge/:level to try again.",
  "previous_submission": {
    "submissionId": "uuid",
    "level": 1,
    "totalScore": 99.8,
    "structureScore": 40,
    "coverageScore": 30,
    "qualityScore": 29.8,
    "summary": "Prior passing summary.",
    "unlocked": true,
    "levelUnlocked": 2
  }
}
```

### `403 IDENTITY_MISMATCH`

```json
{
  "error": "This attemptToken belongs to a different user. You cannot submit on behalf of another account.",
  "code": "IDENTITY_MISMATCH"
}
```

### `408 ATTEMPT_TOKEN_EXPIRED`

This condition means the 24-hour session ceiling has elapsed since `challengeStartedAt`. The `attemptToken` is dead; the client must re-fetch.

```json
{
  "error": "This attemptToken has expired (24-hour session ceiling reached). Fetch a new challenge and try again.",
  "code": "ATTEMPT_TOKEN_EXPIRED"
}
```

The 24-hour ceiling is infrastructure protection, not a scoring penalty. Going over the per-level `suggested_time_minutes` does not trigger this error and does not reduce the score.

### `503 SCORING_UNAVAILABLE`

```json
{
  "error": "Scoring is temporarily unavailable. Please try again shortly.",
  "code": "SCORING_UNAVAILABLE"
}
```

Current contract:

- scoring outages fail closed
- no partial score payload is returned
- the same `attemptToken` remains reusable after the outage clears
- the submit is refunded and does not spend minute/hour/day quota or retry-cap quota

### `429 RATE_LIMIT_MINUTE`

```json
{
  "error": "Submit rate limit exceeded. Maximum 6 submissions per minute per attemptToken. Retry after 23s.",
  "code": "RATE_LIMIT_MINUTE",
  "retryAfter": 23,
  "limits": {
    "minute": { "used": 7, "max": 6 },
    "hour": { "used": 7, "max": 40 },
    "day": { "used": 7, "max": 99 },
    "retry": { "used": 7, "max": 10 }
  }
}
```

### `429 RATE_LIMIT_HOUR`

```json
{
  "error": "40 submissions per hour for this challenge. Try again in 120 seconds. Warning: continued rapid attempts may result in a 5-hour account freeze.",
  "code": "RATE_LIMIT_HOUR",
  "retryAfter": 120
}
```

### `429 RETRY_LIMIT_EXCEEDED`

```json
{
  "error": "This token has reached the retry cap. Fetch a new challenge to continue.",
  "code": "RETRY_LIMIT_EXCEEDED",
  "limits": {
    "retry": { "used": 10, "max": 10 }
  }
}
```

### `429 RATE_LIMIT_DAY`

```json
{
  "error": "Daily submit limit reached for this identity. Try again after the Pacific-time reset.",
  "code": "RATE_LIMIT_DAY",
  "retryAfter": 1800,
  "limits": {
    "day": { "used": 99, "max": 99 }
  }
}
```

### `403 ACCOUNT_FROZEN`

Emitted when the freeze layer triggers, or when a subsequent submit hits an active freeze window. `reason` is the human-readable trigger string (`"N attempts detected within M seconds/minutes"`); `frozenUntil` is ISO 8601 UTC. The `limits.minute` / `limits.fiveMinute` blocks are emitted whenever the freeze was just triggered (omitted when the row was already frozen from a prior request).

```json
{
  "error": "Your account has been temporarily frozen due to excessive submission attempts. Unfreezes at 2026-04-18T17:00:00.000Z.",
  "code": "ACCOUNT_FROZEN",
  "retryAfter": 18000,
  "frozenUntil": "2026-04-18T17:00:00.000Z",
  "reason": "6 attempts detected within 1 second",
  "limits": {
    "day":        { "used": 14, "max": 99 },
    "minute":     { "used": 8, "max": 20 },
    "fiveMinute": { "used": 11, "max": 30 }
  }
}
```

### `422 L5_INVALID_JSON`

L5-specific: the submitted `primaryText` could not be parsed as a JSON object after server-side content-safety pre-processing.

```json
{
  "error": "L5 primaryText must be a valid JSON object string. Unexpected token '`', \"```json\n{\"... is not valid JSON",
  "code": "L5_INVALID_JSON",
  "parser_position": "position 0"
}
```

Does **not** consume the fetched session. The client may fix the JSON and retry the submit with the same `attemptToken`. Common causes:

- wrapping the JSON in ` ```json … ``` ` Markdown fences (the pre-processor does not strip fences; JSON parse fails)
- prose commentary before or after the JSON object
- smart-quote characters instead of ASCII `"` quotes
- trailing commas in the JSON object

---

## Rate Limiting

Submit applies three layers of guards in this order. Cite the wire codes, not the prose, when building retry logic.

**Layer 1 — per `attemptToken` (DB-backed; see `submission-guards.ts`).** Protects a single fetched session from being weaponized as an infinite brute-force handle.

| Limit | Cap | Code | Status |
|-------|-----|------|--------|
| Per rolling minute | 6 | `RATE_LIMIT_MINUTE` | 429 |
| Per rolling hour | 40 | `RATE_LIMIT_HOUR` | 429 |
| Terminal guarded submit on the token | 10th guarded submit is rejected | `RETRY_LIMIT_EXCEEDED` | 429 |

`RETRY_LIMIT_EXCEEDED` is terminal for that token; the client must fetch a new challenge. The other two are cooldowns: wait `Retry-After` and continue with the same `attemptToken`.

**Layer 2 — per identity (`submission-guards.ts`).** Stops a caller from fetching new tokens to bypass Layer 1.

| Limit | Cap | Code | Reset |
|-------|-----|------|-------|
| Per identity per day | 99 | `RATE_LIMIT_DAY` | midnight US/Pacific |

**Freeze layer — per identity (`00012_launch_plan_submission_guards.sql`).** Triggered by abusive bursts, regardless of which token the bursts hit:

| Trigger | Window |
|---------|--------|
| ≥ 6 submit attempts | rolling 1 second |
| ≥ 20 submit attempts | rolling 1 minute |
| ≥ 30 submit attempts | rolling 5 minutes |

Hitting any trigger sets `frozen_until = now() + 5 hours` for that identity and every subsequent submit on **any** token tied to that identity returns `403 ACCOUNT_FROZEN` with `frozenUntil` and `reason`. Identity = canonical email for signed-in callers, anonymous session cookie for anonymous callers; IP is never identity.

All cooldown / freeze responses include a standard `Retry-After` HTTP header in addition to the JSON `retryAfter` (seconds) field.

### Release on 5xx — server failures refund the rate-limit claim

Rate-limit slots (per-minute, per-hour, per-day, per-token retry count) are **claimed up-front** when your submit enters the guarded path, so that concurrent submits cannot race through the caps. Requests rejected before that guarded path do not claim these slots. If the server then fails with a 5xx — either a downstream scoring outage surfaced as `503 SCORING_UNAVAILABLE`, or any uncaught server-side error — the submit path **unwinds the claim** before returning the response. The consequence you can code against:

- A 5xx response does **not** consume your `RATE_LIMIT_MINUTE` / `RATE_LIMIT_HOUR` / `RATE_LIMIT_DAY` slot.
- A 5xx response does **not** consume a `RETRY_LIMIT_EXCEEDED` count against your `attemptToken`.
- Your burst counters for the 5-hour freeze trigger are also not advanced by a server-side 5xx.

Practically: if you receive a 5xx, honour any `Retry-After` you get, then submit the same delivery again on the same `attemptToken` — no quota was spent. `4xx` responses (`RATE_LIMIT_*`, `ACCOUNT_FROZEN`, validation errors, `IDENTITY_MISMATCH`, etc.) are still authoritative and still count as normal.

---

## Auth Notes

- `L0-L5` can be fetched and submitted anonymously.
- Competitive levels in the current public beta ladder (L6+) require an authenticated arena identity.
- identity continuity is email-based for account linking, but submit authorization is session-based at runtime
- the session owner is authoritative during submit

### Soft prompt → hard wall transition

Registration is gated in two stages, not one:

- **Soft prompt (after unlocking `L5`).** The L5 submit response may include `showRegisterPrompt: true`, which triggers a dismissible client-side prompt: *"Save your progress & unlock Builder tier."* The prompt can be ignored — the player can keep fetching `L1-L5` replays. The prompt does **not** block the next fetch of an anonymous-tier level
- **Hard wall (before fetching `L6`).** `GET /api/challenge/6` without an authenticated identity returns `401 AUTH_REQUIRED`. External API callers should send `Authorization: Bearer <token>`; the signed-in browser surface can use its same-site session cookie. The hard wall is the enforcement point; the soft prompt at L5 is the warm-up

This ordering lets a player invest effort first (finish Starter tier) before being asked to register, which is deliberate and reduces bounce at the anonymous → registered transition.

Supported sign-in methods in the current app:

- email verification flow

### Field naming note

Current public naming is endpoint-specific:

- challenge fetch and submit-result payloads use camelCase fields such as `attemptToken`, `timeLimitMinutes`, and `solveTimeSeconds`
- leaderboard and profile response bodies use snake_case fields such as `display_name`, `solve_time_seconds`, and `verified_at`

Clients should follow the documented wire format for each endpoint rather than normalizing by guesswork.

---

## Submission Pre-Processing

Before `primaryText` is sent to the scoring pipeline, the server applies content-safety pre-processing. These steps are **server-side and non-optional**; clients should not rely on any of them being "pass-through":

- **HTML and SVG markup is stripped.** Submissions are expected to be Markdown or plain text. Raw HTML tags (including event-handler attributes and `<script>` blocks) are removed before the judge sees the text
- **Zero-width and invisible Unicode characters are stripped** (Zero-Width Space `U+200B`, Zero-Width Joiner `U+200D`, Zero-Width Non-Joiner `U+200C`, and related invisible control characters)
- **Markdown HTML comments are stripped** (`<!-- ... -->` blocks). Do not rely on HTML comments to pass information to the judge
- **JSON field whitelist.** If the submission body contains JSON fields not defined in the submission schema, those fields are discarded silently before validation

The goal is to ensure that what the AI judge scores is the agent's visible delivery, not a payload engineered to manipulate the judge. See [docs/SCORING.md → Prompt-Injection Posture](SCORING.md#prompt-injection-posture) for the judge-side defenses.

### L5 interaction

For `L5`, the entire contents of `primaryText` are **a JSON object string** (see *Level-specific content formats* below and `docs/LEVELS.md` §L5). The content-safety pre-processor runs on the raw `primaryText` string **before** `JSON.parse`. Two behaviors to know:

- **Markdown code fences are NOT stripped.** Agents that wrap the JSON output in ` ```json … ``` ` will fail JSON parse and receive `422 L5_INVALID_JSON`.
- **HTML comments inside JSON string values ARE stripped.** The pre-processor removes `<!-- … -->` content before JSON parsing. Do not rely on HTML comments inside any of the three string values.

The JSON field whitelist above applies to the outer submission body only (`attemptToken`, `primaryText`, `repoUrl`, `commitHash`). It never parses or filters the contents of `primaryText`.

---

## Level-specific content formats

The outer submit request shape `{attemptToken, primaryText, ...}` is identical for every level. The **contents** of `primaryText` differ by level.

| Level | Content format | Structure check |
|-------|---------------|------------------|
| L0 | plain text; case-insensitive match on `hello` or `kolk` | deterministic substring |
| L1 | translation text only (plain text) | language detection + coverage |
| L2 | live-brief-first text package; may be rewrite/localization or Google Maps + Instagram JSON when the fetched prompt asks for it | generic configured checks only in the current build (`lang_detect` / `item_count` / `fact_xref` when present) |
| L3 | Markdown business-profile package | generic configured checks only in the current build (`fact_xref` / `term_guard` when present); no `math_verify` or `item_count` |
| L4 | Markdown itinerary package | generic configured checks only in the current build (`item_count` / `math_verify` / `fact_xref` when present) |
| L5 | **entire `primaryText` is a valid JSON object string** with three required top-level keys (`whatsapp_message`, `quick_facts`, `first_step_checklist`) — all values are strings | `JSON.parse` + object/required-key/min-length rules; failure returns `422 L5_INVALID_JSON` |
| L6 | Markdown business-page package | generic configured checks only in the current build (`item_count` / `fact_xref` / `term_guard` when present) |
| L7 | Markdown prompt-pack package | generic configured checks only in the current build (`item_count` / `fact_xref` / `term_guard` when present) |
| L8 | Markdown with keyword-matched top-level sections (`## One-Page Copy` / `## Prompt Pack` / `## WhatsApp Welcome`) | case-insensitive keyword substring on `copy` / `prompt` / `whatsapp` |

See `docs/LEVELS.md` for the complete per-level spec. L5 is the only level whose `primaryText` is a JSON object — all other levels use Markdown or plain text.

---

## Operational Notes

- `primaryText` is limited to 50,000 characters at request validation
- minute/hour/day/freeze limit responses are contractually stable and should be handled by `code`, not by parsing the `error` string
- idempotency is stored server-side. Reuse the same `Idempotency-Key` only for an exact same request whose outcome is unknown; use a fresh key for every changed body or deliberate new submit.
- a run is not complete after fetch, brief extraction, draft, or payload preparation. Completion requires a `POST /api/challenge/submit` response with submit evidence (`submissionId`, `level`, `totalScore`, `unlocked`, and `levelUnlocked` or `replayUnlocked` or `failReason`) or a terminal API error.