From 8ef909e97083c086ad291ceb05d021c006c0b740 Mon Sep 17 00:00:00 2001
From: Antiheld86 <4201585+Antiheld86@users.noreply.github.com>
Date: Wed, 2 Sep 2026 09:31:22 +0000
Subject: [PATCH] Regenerate the API contract for the token ceiling

The mint endpoint's description and its new 409 landed in the OpenAPI source
without the generated spec following, which CI's drift check would have
caught. No behaviour change; the two hunks are the reworded limits sentence
and the ceiling response block.
---
 docs/api/openapi.yaml | 15 +++++++++++++--
 1 file changed, 13 insertions(+), 2 deletions(-)

diff --git a/docs/api/openapi.yaml b/docs/api/openapi.yaml
index 45b5b777f..0eb45ec0c 100644
--- a/docs/api/openapi.yaml
+++ b/docs/api/openapi.yaml
@@ -2782,8 +2782,8 @@ paths:
         not because a wildcard lacks the reach, but because of the lifetimes involved: a native access token lives a day
         and what it could mint here lives a year, so admitting one would let a short-lived compromise leave behind a
         credential that outlives revoking it. Gated by the operator's instance-wide API switch. Body capped at 16 KiB;
-        10 mints per user per minute. Tokens appear in `GET /api/tokens` and are revoked at `DELETE /api/tokens/{id}`
-        like any other.
+        10 mints per user per minute, and at most 10 live tokens held at once. Tokens appear in `GET /api/tokens` and
+        are revoked at `DELETE /api/tokens/{id}` like any other — revoking frees a slot against the ceiling.
       requestBody:
         required: true
         content:
@@ -2811,6 +2811,17 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorEnvelope"
+        "409":
+          description: "The account already holds 10 live measurement tokens (`meta.errorCode` =
+            `tokens.measurements.ceiling_reached`). Nothing was minted. Distinct from the 429 above: that one is a rate
+            and clears by waiting, this one is a conflict with the account's current state and clears by revoking a
+            token at `DELETE /api/tokens/{id}`. Only LIVE tokens count — revoked and expired rows do not occupy a slot —
+            and only those carrying `measurements:write`, so the wildcard tokens a sign-in mints never consume the
+            budget."
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorEnvelope"
         "413":
           description: Body exceeds 16 KiB.
           content: