@giveitsmaller/contracts 0.65.0 → 0.68.0

package/openapi/api.yaml

@@ -89,7 +89,7 @@ info:
     of truth instead of hardcoding magic numbers. A runtime
     `GET /api/uploads/limits` endpoint for dynamic discovery
     (per-tier / per-environment overrides) is a deferred follow-up.
-  version: 2.194.0
+  version: 2.198.0
   contact:
     name: API Support
 
@@ -168,7 +168,14 @@ paths:
               $ref: '#/components/schemas/SingleUploadRequest'
       responses:
         '200':
-          description: File uploaded successfully
+          description: |
+            File uploaded successfully.
+
+            ⚠️ **SAMPLE VALUES BELOW ARE ILLUSTRATIVE AND NOT A LIMITS SOURCE.**
+            `constraints_applied` shows the SHAPE of what the server echoes; the
+            figures are not maintained against the API's tier enum and must not
+            be read as current caps. A caller's real, override-aware limits come
+            from `GET /api/v2/account/limits`.
           content:
             application/json:
               schema:
@@ -215,7 +222,7 @@ paths:
                     feature_tier_restricted: '#/components/schemas/FeatureTierRestrictedResponse'
               examples:
                 tier_restriction_mime:
-                  summary: Free tier uploading a video
+                  summary: A caller's tier does not permit the uploaded MIME type
                   value:
                     success: false
                     error: "Your tier does not permit this MIME type"
@@ -313,16 +320,24 @@ paths:
                     upload_duration_exceeds_tier: '#/components/schemas/UploadDurationExceedsTierResponse'
               examples:
                 size_exceeds_tier:
-                  summary: Free-tier caller uploads a 200MB file (cap is 10 MiB)
+                  summary: >-
+                    Envelope shape only — SAMPLE VALUES ARE ILLUSTRATIVE AND NOT
+                    A LIMITS SOURCE. The figures below are not maintained against
+                    the API's tier enum; a caller's real, override-aware limits
+                    come from GET /api/v2/account/limits.
                   value:
                     success: false
-                    error: "Upload exceeds size cap for free tier (max 10 MiB; pro permits up to 5 GiB)."
+                    error: "Upload exceeds the size cap for your tier."
                     error_type: "upload_size_exceeds_tier"
                     current_tier: "free"
-                    max_size_bytes: 10485760
+                    max_size_bytes: 1048576
                     required_tier: "pro"
                 duration_exceeds_tier:
-                  summary: Pro-tier caller uploads a 30-minute video (cap is 5min on short_form)
+                  summary: >-
+                    Envelope shape only — SAMPLE VALUES ARE ILLUSTRATIVE AND NOT
+                    A LIMITS SOURCE. The authoritative duration bands are
+                    generated into each operation schema's processing_class
+                    constraints.
                   value:
                     success: false
                     error: "Upload exceeds short_form duration cap (max 5 minutes; long_form permits up to 12 hours)."
@@ -2418,13 +2433,24 @@ paths:
       # is the integration timeout firing to the millisecond. Measured AND
       # mechanistically explained, which is what the gate asked for.
       #
-      # ⚠️ THERE IS STILL DELIBERATELY NO PRODUCTION ENTRY, and the reason is
-      # UNCHANGED by the staging proof: PROD HAS NEVER HAD A PROVEN STREAM.
-      # Declaring a prod host would be a contract fact pointing at something
-      # unproven, which is worse than the gap because it LOOKS resolved — the
-      # same error this block exists to prevent, committed in the opposite
-      # direction. The gate is the same one, applied to prod: a first-byte
-      # timestamp on a heartbeat from the prod stream host.
+      # HISTORY, kept because the reasoning is still live even though its
+      # conclusion is not: from 2026-08-14 to 2026-08-18 there was DELIBERATELY
+      # NO PRODUCTION ENTRY, on the rule that declaring a prod host would be a
+      # contract fact pointing at something unproven — worse than the gap
+      # because it LOOKS resolved.
+      #
+      # ⚠️ THAT RULE IS NOT REPEALED. What ended the withholding is that the gap
+      # was found to be ALREADY OCCUPIED: `compression_frontend`'s prod deploy
+      # hardcodes `VITE_SSE_BASE_URL` to the prod stream host, so the convention
+      # was live and undeclared, and silence was preventing consumers from
+      # KNOWING about a host they already depended on. The rule is now satisfied
+      # a different way — the prod entry states, in itself, which half is proven
+      # (ROUTING) and which is not (DURATION, the property the split host exists
+      # for). See its description.
+      #
+      # ⇒ Do NOT read the prod entry as "prod SSE is proven". If you are about
+      # to write that sentence, the discriminator is named in the entry and has
+      # not been run.
       servers:
         - url: http://localhost:8080
           # WHICH ROOT SERVER THIS ENTRY REPLACES. Without it a client has to
@@ -2440,6 +2466,79 @@ paths:
             do NOT reproduce the split-host topology, so a client that works
             locally has **not** exercised the cross-origin path. Treat a local
             pass as evidence about your code and not about the routing.
+        - url: https://stream.giveitsmaller.com
+          x-replaces: https://api.giveitsmaller.com
+          description: |
+            Production stream host. Declared 2026-08-18 after **routing** was
+            measured; see the two headings below for exactly what that does and
+            does not cover.
+
+            🔴 **THIS ENTRY WAS DELIBERATELY WITHHELD FROM 2026-08-14 TO
+            2026-08-18, AND THE REASON IT LANDED IS NOT THAT THE ORIGINAL GATE
+            WAS MET.** The gate was *"prod has never had a proven stream; a
+            declared host would be a contract fact pointing at nothing — worse
+            than the gap, because it looks resolved."* What changed is that **the
+            gap was found to be already occupied**:
+            `compression_frontend/.github/workflows/deploy-env.yml` hardcodes
+            `VITE_SSE_BASE_URL: https://stream.giveitsmaller.com` for prod, so
+            **the production frontend has been routing SSE to this host all
+            along, undeclared.** Contract silence was not preventing anyone from
+            depending on the host; it was preventing them from *knowing* about
+            it — which is the undeclared per-client convention this whole
+            declaration exists to end.
+
+            ### WHAT IS MEASURED (2026-08-18, prod, by `compression_e2e`)
+
+            - An **authenticated stream against a real prod workflow** returned
+              `200` with `content-type: text/event-stream`, replayed
+              `operation.progress` at 10 / 50 / 90, then `operation.completed`
+              carrying a real presigned S3 `download_url`, `size_bytes` 246217,
+              `compression_ratio` 0.3288 — then `job.completed` and
+              `workflow.completed`.
+            - An **unauthenticated** request returns the full localised error
+              envelope (`WORKFLOW_NOT_FOUND` with `message_key`,
+              `Content-Language: en-GB`, `Vary`, HSTS), byte-identical to
+              `api.giveitsmaller.com` — so this host reaches the **real
+              application**, not an edge stub or a parked custom domain.
+            - **CORS is correct on both hosts**: preflight `200`,
+              `Access-Control-Allow-Origin` exactly
+              `https://www.giveitsmaller.com`, `Allow-Credentials: true`,
+              `Authorization` among the allowed headers.
+
+            ### ⚠️ WHAT IS **NOT** MEASURED: DURATION — THE PROPERTY THIS HOST EXISTS FOR
+
+            **The split host exists because `api.*` is an API Gateway HTTP API
+            with a 30-second hard ceiling** (staging measured it `503`-ing at
+            **29.35s**, to the millisecond) and `responseTransferMode: STREAM` is
+            REST-only. **Nothing has yet shown that a stream on THIS host
+            survives past that ceiling.**
+
+            The attempt was made and could not answer: prod holds exactly one
+            workflow and it was already **terminal**, so the server correctly
+            replayed history and closed on the terminal frame — total elapsed
+            **0.355s**. ⇒ **A stream that closes at 0.4s because the job finished
+            says nothing about whether a stream that WANTED to stay open would
+            survive to 35s.** It is a non-answer, not a negative result.
+
+            **The discriminator, named so nobody re-derives it:** a
+            **NON-TERMINAL** prod job, streamed and held, reporting either the
+            last-byte timestamp or that the connection was still open at **35s+**.
+            One request; no browser needed. Until then, treat long-lived prod
+            streams as unproven on this host — and note that a client falling
+            back to `api.giveitsmaller.com` is *provably* subject to the 30s
+            ceiling, so this entry cannot be worse than the fallback.
+
+            ⚠️ **The BROWSER path is also unmeasured.** The evidence above is
+            HTTP-layer. The CORS preflight is correct, which is the part a
+            browser needs, but no browser client has been observed consuming this
+            stream in production.
+
+            **This entry declares ROUTING. It does not assert that prod SSE
+            works** — do not let it be quoted as though it did.
+
+            The CORS scope, auth and cross-origin caveats stated on the staging
+            entry above apply here too, with one difference already noted there:
+            **prod's API host has never permitted `localhost`.**
         - url: https://stream.staging.giveitsmaller.com
           x-replaces: https://api.staging.giveitsmaller.com
           description: |
@@ -2519,10 +2618,18 @@ paths:
             the preflight response.
 
             **None of that is verified by this contract, and contracts has not
-            measured it.** ⇒ **A browser client SHOULD prefer `bearerAuth` or
-            the anonymous capability header on this host**, and should treat
-            cookie-based session auth over it as unproven until somebody
-            measures a credentialed cross-origin stream.
+            measured it.**
+
+            🔴 **This passage used to conclude "a browser client SHOULD prefer
+            `bearerAuth` or the anonymous capability header on this host, and
+            should treat cookie-based session auth as unproven". DO NOT
+            REINSTATE IT.** For an **owned** stream the shipped browser client
+            has no bearer token on its runtime path at all, so that advice named
+            a credential the caller does not possess — leaving a logged-in user
+            with nothing to send. See **AUTH ON THE STREAM HOST** on the
+            operation below, which is the single place this question is
+            answered; the cross-origin caveats above remain true and are what
+            that section is qualified by.
       description: |
         Server-Sent Events endpoint for real-time workflow progress. The server pushes
         events as workflow, job, and operation statuses change.
@@ -2580,7 +2687,85 @@ paths:
         the `data:` JSON payload of each event. The SSE envelope framing itself
         (the `id:` and `event:` lines) is transport-level and intentionally
         **not** schema-described.
+
+        ### AUTH ON THE STREAM HOST: the CREDENTIAL decides, not the caller
+
+        **Two axes, and conflating them is what made two earlier versions of this
+        note wrong.** *Which credential is available to you* depends on the
+        workflow and your runtime. *What the browser then requires of the
+        request* depends only on **which credential you actually send**.
+
+        **Which credential you have:**
+
+        | workflow | caller | credential |
+        |---|---|---|
+        | null-owner | any runtime, server or browser | **`X-Workflow-Capability`** — bearer does NOT establish workflow ownership and is not a substitute |
+        | owned | server-side | **`bearerAuth`** (or `sessionAuth`) |
+        | owned | the shipped browser client | **the session cookie** — it carries no bearer token on its runtime path, so this is the only credential it possesses |
+
+        ⚠️ **The last row describes the SHIPPED CLIENT, not what the endpoint
+        supports.** The endpoint accepts `bearerAuth` for an owned workflow; a
+        browser build that obtains a bearer token can use it.
+
+        **What the credential then requires of the request:**
+
+        | credential sent | `credentials` mode | why |
+        |---|---|---|
+        | any **header** (bearer or capability) | **`omit`** | the header carries the auth; `include` would impose the credentialed-CORS requirement for nothing |
+        | the **session cookie** | **`include`** | the cookie *is* the credential, and the browser only sends it in this mode |
+
+        ⇒ **The mode follows the CREDENTIAL, not the ownership and not the
+        runtime.** An owned stream authenticated by bearer uses `omit`; only a
+        cookie-authenticated request needs `include`.
+
+        **Where a header credential is available it is already the right answer** —
+        headers are immune to `SameSite` and third-party-cookie policy and need no
+        `Access-Control-Allow-Credentials`. What is NOT yet available is a
+        **browser** bearer credential for an **owned** stream, and until one
+        exists that one cell of the matrix cannot act on the advice.
+
+        🔴 **Two earlier versions of this note stated a destination in the present
+        tense and would have caused harm.** One concluded *"a browser client
+        SHOULD prefer `bearerAuth` or the anonymous capability header on this
+        host"*; a later revision restated it as *"cookie session auth is NOT
+        supported on the stream host"*. **Both named a credential an owned browser
+        caller does not possess**, and an implementer following either would have
+        left every logged-in user with nothing to send. Verified in the shipped
+        client, not inferred. **DO NOT REINSTATE EITHER.**
+
+        ⚠️ **`sessionAuth` therefore stays in the `security` list, and so does the
+        anonymous `{}` alternative, pending the modelling fix noted below.**
+        OpenAPI has **no per-server `security`**: an operation-level `servers`
+        block does not scope it, so one list covers this operation on every host.
+
+        ⚠️ **`X-Workflow-Capability` is currently a HEADER PARAMETER, not a
+        security scheme**, so the machine-readable contract does not express that
+        a null-owner read requires it — the `{}` alternative advertises
+        credential-free access that a successful null-owner read does not
+        actually have. Promoting it to an `apiKey` scheme is available and is
+        tracked separately; naming it in prose is documentation, and treating
+        that as a declaration is the mistake this note exists to prevent.
+
+        ⚠️ **`credentials: 'include'` is a property of the REQUEST MODE, not of
+        the credential you meant to send.** A `fetch` issued with it makes the
+        browser require the response to carry `Access-Control-Allow-Credentials:
+        true` **and** a non-wildcard origin — **or it blocks the response, whether
+        or not a cookie was actually sent**. So a header-authenticated request
+        that keeps `include` is browser-blocked against a host that does not
+        return the header **while its authentication is perfectly fine** — a
+        failure that reads as an auth bug and is not one. The shipped browser
+        client already splits on exactly this.
       operationId: streamWorkflowEvents
+      # ⚠️ `sessionAuth` IS LOAD-BEARING — the session cookie is the SOLE
+      # credential for an OWNED stream on the shipped browser client, which
+      # carries no bearer token on its runtime path. Do not remove it on the
+      # strength of a "prefer headers" ruling; that ruling is a direction, and
+      # for owned streams there is currently nothing to point at.
+      # `{}` is the anonymous alternative and is currently OVER-PERMISSIVE: a
+      # successful null-owner read requires `X-Workflow-Capability`, which is a
+      # header PARAMETER rather than a security scheme, so the security list
+      # cannot yet say so. Tracked separately.
+      # See AUTH ON THE STREAM HOST in the description above.
       security: [{}, {bearerAuth: []}, {sessionAuth: []}]  # optional (anon-OK; identity-scoped to workflow owner)
       x-identity-scoped: true  # workflow-ownership-scoped per ADR-0016 D3
       tags:
@@ -2666,6 +2851,161 @@ paths:
                   Server-Sent Events stream. Each event has an `event` field (type)
                   and a `data` field (JSON payload). See endpoint description for
                   event types and payload shapes.
+        '429':
+          description: |
+            **The CALLER's own concurrent-stream allowance is exhausted.**
+
+            Consistent with `LONG_FORM_CONCURRENCY_LIMIT_EXCEEDED`, which this
+            contract already returns `429` for and describes as *"the caller's
+            tier concurrency allowance is exhausted"*. **Same semantics, same
+            code** — this caller is holding too many streams open.
+
+            ⚠️ **NOT for a global-capacity refusal.** `429` tells a caller they
+            went too fast; a caller who has opened nothing and is refused
+            because the pool is full has not, and sending them to a slow-down
+            remedy is a lie. That case is `503`.
+          headers:
+            Retry-After:
+              description: Seconds to wait. Delta-seconds, not an HTTP-date.
+              schema:
+                type: integer
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: SSE_CONNECTION_LIMIT_EXCEEDED
+                message: Too many open event streams for this caller.
+        '503':
+          description: |
+            **Global stream capacity is exhausted — nothing about this caller.**
+
+            🔴 **The cap this exists for is not a rate.** `events_stream` limits
+            how fast streams START, not how many are OPEN, and a stream holds
+            one PHP-FPM worker for its entire life. At 10 starts/min against a
+            570s deadline a single caller sustains roughly 95 concurrent streams
+            on a 50-worker pool **without exceeding any documented limit** —
+            uploads, `/status`, auth and the health probes queue behind it.
+            ⇒ **An ordinary client can exhaust the pool using a documented
+            feature within its documented limits.** No malice required.
+
+            🔴 **RECONNECT BEHAVIOUR DEPENDS ON THE CLIENT KIND, AND SAYING
+            SO IS THE WHOLE POINT OF THIS BLOCK.** A `text/event-stream`
+            endpoint is not necessarily consumed by an `EventSource`. The
+            WHATWG rules below are **user-agent behaviour of `EventSource`**
+            and hold for **nothing else** — a `fetch`-based reader supplies its
+            own policy, and the two behave oppositely under refusal.
+
+            **(a) A NATIVE `EventSource`.** From the WHATWG HTML spec,
+            Server-sent events (read 2026-08-22, api searched it and this repo
+            verified it independently rather than relaying):
+
+            - *"if res's status is not 200, or if res's `Content-Type` is not
+              `text/event-stream`, then fail the connection."*
+            - *"Once the user agent has failed the connection, it does not
+              attempt to reconnect."*
+            - *"…if res is not a network error, then reestablish the
+              connection."* — this is `processEventSourceEndOfBody`, i.e. a
+              **clean EOF on an already-established 200 stream.**
+
+            ⇒ For this client kind, refusing with a status does not storm, and
+            **accept-then-close-with-an-in-band-error IS the reconnect path** —
+            a clean EOF on an established stream is precisely what the spec
+            reestablishes. ⭐ **The shape that reads as the gentler option is
+            the one that amplifies**, and the intuition is backwards.
+
+            ⚠️ Its cost, which must not be sold as graceful degradation: a
+            refused stream **dead-ends**, permanently, with no retry of its
+            own. ⇒ **Such a UI must treat refusal as TERMINAL and offer an
+            explicit user-visible retry — never a spinner**, which would wait
+            forever on a connection that is never coming back. It also **cannot
+            read this status** (`EventSource` does not expose it to page
+            script), so it cannot tell `503` from `500`.
+
+            **(b) A `fetch`-BASED READER — WHICH IS WHAT OUR FRONTEND IS.**
+            Measured at `compression_frontend` `origin/main` on 2026-08-25 by
+            two independent parties: **zero `EventSource` references** across
+            its source tree (positive control on the same enumeration: several
+            files reference this endpoint), a plain `fetch()` whose own comment
+            says *"a direct fetch, not an SDK call"*. It reads
+            `response.status` fine.
+
+            Its refusal behaviour, **as a SHAPE — the counts and intervals are
+            configurable defaults in that repo and are deliberately not
+            restated here, because a number copied across a repo boundary rots
+            silently**: a non-200 is raised as a *transport error*, retried a
+            bounded number of times on a delay, and then falls through to
+            `/status` polling with **adaptive backoff** — the interval GROWS
+            while the server reports no movement.
+
+            ⚠️ **And the `/status` poll is NOT started by the fallback.** It
+            runs **in parallel from the outset**, as resilience against a
+            gateway that cannot proxy SSE, and **self-cancels on the stream's
+            first event.** A refused stream never delivers one — so **refusal
+            does not start a poll, it prevents an already-running poll from
+            being cancelled.**
+
+            🔴 **SO REFUSAL TRADES CONTINUOUS WORKER OCCUPANCY FOR A HIGHER
+            REQUEST RATE.** Both halves matter: a held stream pins one PHP-FPM
+            worker for its whole life and refusal genuinely sheds that — a
+            short poll is not a held connection — while that client's
+            connection attempts and polls go **up**.
+            ⚠️ **Do not read either half alone.** "Refusal sheds load" invites
+            a cap whose success metric moves the wrong way; "refusal increases
+            load" argues against having a cap at all, and the occupancy it
+            sheds is the resource this limit exists for.
+
+            ⚠️ **THAT IS PER-CLIENT AND MEASURED. THE AGGREGATE IS NEITHER.**
+            Whether refusing many clients at once produces a synchronised burst
+            is **UNMEASURED** — the retry delay is a fixed configured interval
+            with no jitter, so refusals issued together are retried together,
+            and nothing here has observed what that does in aggregate. **Do not
+            read "not a storm" out of this section; it says the per-client cost
+            is bounded and says nothing about the fleet.**
+
+            📌 **WHAT A REFUSED `fetch` CLIENT SHOULD DO INSTEAD IS NOT YET
+            SPECIFIED** — including whether `Retry-After` governs a fallback
+            poll interval and not only a reconnect. Falling back to polling
+            is also load, merely cheaper. Open on
+            [`rLCBjojv`](https://trello.com/c/rLCBjojv); **this block states the
+            measured behaviour and deliberately does not invent the
+            obligation.**
+
+            📌 **THE POPULATIONS SPLIT BY READER KIND, NOT BY
+            BROWSER-VERSUS-NOT.** The WHATWG rule covers **native
+            `EventSource` consumers** and nothing else. **A custom reader is
+            safe only by its own code, inside a browser or outside one** — and
+            a retry loop treating `429`/`503` as retryable on a fixed interval
+            is where a storm is reachable. ⚠️ **Our own frontend is in that
+            population, not exempt from it.**
+
+            ✅ **For OUR SDKs that is measured, not assumed** (sdks,
+            2026-08-22, driven through the BUILT client with a stubbed
+            transport and a positive control): `429`, `503` and a `429` with no
+            `Retry-After` each produce **exactly one request**; the control
+            `200` also produces one, proving the stub was reached.
+            `GislClient.request()` has no retry layer, `streamEvents` reaches
+            none of the upload/probe retry predicates, and there is no
+            Last-Event-ID reconnection in either language.
+            ⚠️ **That is a property of the current SDK, not of the contract** —
+            it can be undone by an ordinary change to a retry policy, and this
+            endpoint would not notice.
+          headers:
+            Retry-After:
+              description: |
+                Seconds to wait before retrying. Delta-seconds, not an
+                HTTP-date. **Also unreadable by `EventSource`** — see above.
+              schema:
+                type: integer
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: SSE_CAPACITY_EXHAUSTED
+                message: Event stream capacity is temporarily exhausted.
         '404':
           description: Workflow not found
           content:
@@ -5004,6 +5344,70 @@ paths:
                 $ref: '#/components/schemas/ErrorEnvelope'
 
   /api/auth/profile:
+    get:
+      summary: Get the authenticated identity (whoami)
+      description: |
+        Returns the caller's own identity. **This endpoint SHIPS and was
+        undocumented until 2026-08-22** — the contract described only `PATCH`
+        on this path, and three sessions independently concluded that no
+        whoami capability existed because they read the contract rather than
+        the API. **A contract that omits a shipped endpoint is exactly as
+        dangerous as one that documents a missing one.**
+
+        ⚠️ **Documented from the producer, not from a test.** The response
+        shape below is taken from `ProfileController::profile()` in
+        `compression_api`. An e2e test asserts only `data.user.id` and
+        `data.user.email`; writing the schema from it would have documented
+        two of eight fields and called the rest absent.
+
+        🔴 **`tier` is emitted through `UserTier::canonicalValue()`**, which
+        returns the WIRE spelling of the base tier — see `UserTier` for the
+        `basic`/`free` transition and why the two spellings are one tier.
+      operationId: getProfile
+      security:
+        - bearerAuth: []
+        - sessionAuth: []
+      x-identity-scoped: true
+      tags:
+        - Auth
+      responses:
+        '200':
+          description: The authenticated identity.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [success, data]
+                properties:
+                  success:
+                    type: boolean
+                    enum: [true]
+                  data:
+                    type: object
+                    required: [user]
+                    properties:
+                      user:
+                        $ref: '#/components/schemas/AuthenticatedIdentity'
+        '401':
+          description: No authenticated principal.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '404':
+          description: |
+            The authenticated principal no longer resolves to a stored user
+            (`error: USER_NOT_FOUND`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '500':
+          description: Internal server error.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
     patch:
       summary: Update the authenticated user's profile
       description: |
@@ -5748,7 +6152,13 @@ paths:
                 $ref: '#/components/schemas/AccountLimitsSuccessEnvelope'
               examples:
                 free_tier_defaults:
-                  summary: Free tier, no overrides (effective == tier_default)
+                  summary: >-
+                    Free tier, no overrides (effective == tier_default) — SAMPLE
+                    VALUES ARE ILLUSTRATIVE AND NOT A LIMITS SOURCE. The field is
+                    named tier_default, which makes a stale figure here read as
+                    authoritative; the numbers are not maintained against the
+                    API's tier enum. The response itself is the source, per
+                    caller.
                   value:
                     success: true
                     data:
@@ -5763,7 +6173,11 @@ paths:
                           tier_default: 1073741824
                           overridden: false
                 enterprise_with_upload_override:
-                  summary: Enterprise tier with a raised per-account upload override
+                  summary: >-
+                    Enterprise tier with a raised per-account upload override —
+                    SAMPLE VALUES ARE ILLUSTRATIVE AND NOT A LIMITS SOURCE. It
+                    demonstrates the override SHAPE (effective diverging from
+                    tier_default), not the current figures.
                   value:
                     success: true
                     data:
@@ -7385,15 +7799,23 @@ components:
           (`UserTier.maxFileSizeBytes` — the request-level tier quota the
           upload endpoints enforce). **Distinct** from the per-operation
           processing ceiling `max_input_size_bytes` in operation schemas
-          (different axis AND number). Tier defaults: free 10 MiB, pro 5 GiB,
-          enterprise 100 GiB.
+          (different axis AND number).
+          ⚠️ **The per-tier byte defaults are deliberately NOT restated here.**
+          This line used to list them for `free` / `pro` / `enterprise` and
+          **silently omitted `max`** — a tier the `UserTier` enum declares. The
+          response itself carries the answer per caller (`tier_default` beside
+          `effective`), which is override-aware in a way a static table can
+          never be.
         - `max_total_input_size_bytes`: the effective merge combined-input
           size cap (the summed-inputs ceiling). Same key as the
           operation-schema merge band; the band is processing-class +
-          tier dependent (`short_form_concat` baseline 1 GiB; the
-          `long_form_re_encode` band where the tier permits it — Pro 5 GB,
-          Enterprise 120 GB). The server resolves the effective value for
-          the caller.
+          tier dependent. **The server resolves the effective value for the
+          caller** and returns it here — that is the point of this endpoint.
+          ⚠️ **A THIRD restated per-tier table lived on this line** (it named
+          two tiers' band ceilings and, like the other two, omitted `max`). The
+          machine-readable source is `per_tier_constraints` on the operation
+          schema's `processing_class`; it is generated, so it cannot drift from
+          the schemas the way a sentence here does.
       required:
         - tier
         - limits
@@ -7421,133 +7843,6 @@ components:
               # AccountLimitEntry.
               $ref: '#/components/schemas/AccountLimitEntry'
 
-    MediaCategory:
-      type: string
-      enum: [image, video, audio, document]
-      description: |
-        Coarse input media family, as used by the tier-default surface.
-        **Not** a MIME type and **not** an operation `mime_group` — those are
-        finer-grained and live in the operation schemas. This vocabulary
-        exists so a client can filter a file picker without enumerating MIMEs.
-
-    TierDefaults:
-      type: object
-      additionalProperties: false
-      description: |
-        The **published default limits**, readable by an ANONYMOUS caller.
-
-        **Why this exists separately from `GET /api/v2/account/limits`:** that
-        endpoint is per-account and override-aware, so it requires auth and
-        returns `401` to an anonymous caller — **correctly**, because
-        `effective` / `tier_default` / `overridden` is meaningless without an
-        account. What a logged-out visitor needs is the **tier defaults**,
-        which are not per-account. This publishes AS DATA what the `UserTier`
-        description already publishes as prose.
-
-        **The server is authoritative for the values.** This contract declares
-        the SHAPE; the numbers are computed per environment and per tier
-        model, and a client MUST read them here rather than hard-coding a
-        table (the drift this field exists to end).
-      required:
-        - media_categories
-        - by_audience
-      properties:
-        media_categories:
-          type: array
-          minItems: 1
-          uniqueItems: true
-          items:
-            $ref: '#/components/schemas/MediaCategory'
-          description: |
-            The input media families available **to every audience,
-            including anonymous**. Declared ONCE, not per-tier, because it
-            does not vary — hub decision 25 made audio universal, and there
-            is now no tier boundary at which the category axis changes.
-
-            ⚠️ **Deliberately NOT a per-audience allow-list.** A structure
-            with one row per tier, every row identical, is a gate whose every
-            row is open — it reads as an entitlement mechanism while
-            encoding no entitlement, and the next reader maintains it as
-            though it did. If a future tier DOES restrict categories, this
-            field moves into `by_audience` in a deliberate change, and that
-            change is where the restriction gets argued.
-        by_audience:
-          type: object
-          additionalProperties: false
-          description: |
-            The limits that genuinely DO vary, keyed by audience. Contains
-            only axes with real variance; an axis that is uniform belongs
-            beside `media_categories`, not here.
-
-            **`anonymous` is a key here but deliberately NOT a `UserTier`
-            value.** `UserTier` is a subscription tier and anonymous is the
-            ABSENCE of one — putting it in that enum would place a
-            non-subscription value inside the ordering that drives upgrade
-            prompts (`free < pro < max < enterprise`), where it has no
-            position.
-            ⚠️ **And keeping them distinct is not pedantry — the conflation
-            has already shipped once.** This endpoint's `user_tier`
-            description used to say anonymous callers "receive the `free`
-            tier baseline view", which became false the moment the two were
-            allowed to differ. **A vocabulary that cannot express the
-            difference invites prose asserting they are the same.**
-          required:
-            - anonymous
-            - free
-            - pro
-            - max
-            - enterprise
-          properties:
-            anonymous:
-              $ref: '#/components/schemas/TierDefaultLimits'
-            free:
-              $ref: '#/components/schemas/TierDefaultLimits'
-            pro:
-              $ref: '#/components/schemas/TierDefaultLimits'
-            max:
-              $ref: '#/components/schemas/TierDefaultLimits'
-            enterprise:
-              $ref: '#/components/schemas/TierDefaultLimits'
-
-    TierDefaultLimits:
-      type: object
-      additionalProperties: false
-      description: |
-        One audience's default limits. **Defaults, not entitlements** — a
-        specific account may carry an override, which only
-        `GET /api/v2/account/limits` can report.
-      required:
-        - max_upload_size_bytes
-        - max_duration_seconds
-      properties:
-        max_upload_size_bytes:
-          type: integer
-          format: int64
-          minimum: 1
-          description: |
-            Per-FILE upload cap. Same axis as
-            `AccountLimits.limits.max_upload_size_bytes`.
-
-            ⚠️ **A client MUST NOT treat this as the only size bound.** The
-            per-operation processing ceilings (`max_input_size_bytes` in the
-            operation schemas) are a **different axis and a different
-            number**, and can be SMALLER than this cap — an upload that
-            succeeds may still be rejected at operation time. A picker that
-            shows one number without the other will let a user pick a file
-            the product cannot process.
-        max_duration_seconds:
-          type: [integer, "null"]
-          minimum: 0
-          description: |
-            Per-upload duration cap for time-based media. `null` where the
-            audience has no duration cap.
-
-            ⚠️ **DISTINCT from `processing_class.short_form.max_input_duration`
-            (`PT5M`) in the operation schemas, which it may numerically
-            equal.** That is the short-form/long-form PROCESSING boundary and
-            applies to every audience; this is an entitlement. Two concepts,
-            one integer — read this one for entitlement.
-
     AccountLimitEntry:
       type: object
       additionalProperties: false
@@ -8414,54 +8709,165 @@ components:
     # USER TIER + TIER RESTRICTION ENVELOPES
     # ============================================
 
+    AuthenticatedIdentity:
+      type: object
+      description: |
+        The caller's own identity, as returned by `GET /api/auth/profile`.
+
+        **Documented from `ProfileController::profile()` in `compression_api`,
+        2026-08-22, after the endpoint was found to ship undocumented.**
+        Nullability is taken from `UserRecord`'s constructor promotion, not
+        inferred from a sample response — a field that happens to be populated
+        in one response says nothing about whether it can be null.
+      required:
+        - id
+        - email
+        - tier
+        - email_verified
+        - created_at
+      properties:
+        id:
+          type: string
+          description: Stable identifier for the user.
+        email:
+          type: string
+          format: email
+        name:
+          type: string
+          nullable: true
+          description: Display name. Nullable — `UserRecord::$name` defaults to null.
+        tier:
+          allOf:
+            - $ref: '#/components/schemas/UserTier'
+          description: |
+            🔴 **Emitted through `UserTier::canonicalValue()`**, which returns the
+            WIRE spelling of the base tier. See `UserTier` for why `basic` and
+            `free` are one tier under two names and must rank identically.
+        email_verified:
+          type: boolean
+          description: |
+            Derived — true iff `UserRecord::$emailVerifiedAt` is set. The
+            timestamp itself is NOT exposed on this endpoint.
+        pending_email:
+          type: string
+          format: email
+          nullable: true
+          description: A requested email change awaiting confirmation, if any.
+        created_at:
+          type: string
+          format: date-time
+        delete_requested_at:
+          type: string
+          format: date-time
+          nullable: true
+          description: |
+            Set when the user has requested account deletion and not cancelled
+            it. Nullable in the normal case.
     UserTier:
       type: string
       description: |
         Subscription tier. Mirrors the API-side
         `App\Identity\Domain\Enums\UserTier` PHP enum.
 
-        Ordering is `free` < `pro` < `max` < `enterprise` (the
+        `basic` is the base tier. **`free` is DEPRECATED and will be removed**
+        ([`nD8fCPDy`](https://trello.com/c/nD8fCPDy)) — the two are one tier
+        under two names, never two tiers, and a consumer must rank them
+        identically. The dated record of the rename and of the rollout that
+        carried it is
+        [ADR-0028](../docs/decisions/0028-base-tier-rename-free-to-basic.md).
+
+        🔴 **`guest` IS NOT AND MUST NOT BECOME A MEMBER OF THIS ENUM.** It is
+        the *absence* of a subscription, not a tier. Putting it here places a
+        non-subscription value inside the ordering that drives upgrade prompts,
+        where it has no position — **that conflation already shipped once as a
+        bug and was deliberately removed.** The audience key lives on
+        the audience axis, which is NOT a `UserTier` value. Asserted by a
+        test, not left to prose.
+
+        Ordering is `basic` < `pro` < `max` < `enterprise` (the
         upgrade-resolver / `isHigherThan` ordinal in `UserTier.php`).
-        `max` is the top **self-serve** tier — Pro plus audio + larger
-        long-form bands; Enterprise remains the negotiated tier above it.
-
-        Tier capability summary (informational; canonical limits are
-        enforced server-side per `UserTier.php`):
-        - `free`: 10 MiB max upload; image MIMEs only; 50 monthly credits;
-          0 overdraft; 1× rate-limit baseline. No long-form access
-          (video/audio are MIME-gated away from Free).
-        - `pro`: 5 GiB max upload; image + video + document MIMEs; 1000
-          monthly credits; 200 overdraft; 5× rate-limit; up to 2 concurrent
-          in-flight long-form jobs.
-        - `max`: 50 GiB max upload; image + video + document + audio MIMEs;
-          7500 monthly credits; 2500 overdraft; 15× rate-limit; up to 5
-          concurrent in-flight long-form jobs.
-        - `enterprise`: 100 GiB max upload; image + video + document + audio
-          MIMEs; 10000 monthly credits; 5000 overdraft; 20× rate-limit;
-          uncapped concurrent long-form jobs.
-
-        **Concurrent long-form jobs** is a hard per-tier ceiling on the
-        number of in-flight long-form (Fargate) workflows a caller may
-        hold at once — exceeding it returns a typed `429`
+        **The ordering is the part this contract owns** — it is what
+        `TierRestrictionResponse.current_tier` / `.required_tier` and
+        `FeatureViolation.required_tier` are compared with.
+
+        🔴 **THIS SCHEMA DELIBERATELY DOES NOT ENUMERATE WHAT EACH TIER MAY
+        DO, IN EITHER DIRECTION.** It previously carried a per-tier capability
+        summary — upload caps, permitted MIME families, monthly credits,
+        overdraft, rate-limit multiples, concurrent long-form jobs. **That was a
+        restated SNAPSHOT of another repository's code, and it drifted, twice:**
+        once asserting a per-tier media restriction this contract does not own
+        and cannot keep true, and once listing tier byte defaults while
+        **silently omitting `max`**, a tier this very enum declares.
+
+        **A description ships to every SDK consumer as generated documentation**,
+        so a stale sentence here is not an internal note — it is an assertion
+        delivered to callers, and it outlives the code it describes. *Point at
+        the gate, not at a snapshot of it.*
+
+        ⚠️ **No claim is made HERE about which media categories a tier permits.**
+        That is a scoping statement about this description, **not a claim that
+        the contract is silent on the subject**: hub decision 25 made audio
+        universal, so there is no tier boundary at which the category axis
+        changes. **Prose that restates another repository's enforcement is the
+        defect; a single generated declaration is the fix**, and the two must
+        not both exist.
+
+        **Where the answers actually live — and they are DIFFERENT SURFACES,
+        which is why naming just one was wrong:**
+
+        - **Which media categories are available** — the capability
+          endpoint's `operations` map, per operation and mime_group
+          block. Declared **once, not per audience**, because the axis does not
+          vary. ⚠️ **`GET /api/v2/account/limits` cannot answer this**: it
+          carries numeric limit entries only and exposes no MIME entitlement
+          data at all.
+        - **A caller's own numeric limits** — override-aware, and the only
+          source reflecting account-level overrides:
+          `GET /api/v2/account/limits` (`AccountLimits`). Its `limits` map is
+          typed-open, so new limit keys arrive additively.
+        - **Enforcement of record**: the API's `UserTier` enum. A `403`
+          `tier_restriction` carries `TierRestrictionKind` — `mime_type` or
+          `file_size` — naming which quota refused the request.
+        - **Per-operation processing ceilings** (a different axis and a
+          different number from the per-file upload cap):
+          `processing_class.constraints` and `per_tier_constraints` in the
+          operation schemas.
+
+        **Concurrent long-form jobs** remain a hard per-tier ceiling enforced
+        server-side; exceeding it returns a typed `429`
         `LONG_FORM_CONCURRENCY_LIMIT_EXCEEDED` (see the `POST /api/workflows`
-        429 response). Pro's 2-job cap is enforced as of the Max-tier
-        launch.
-
-        The "max upload" figures are the per-file upload cap
-        (`UserTier.maxFileSizeBytes`) — the request-level tier quota,
-        surfaced override-aware via `GET /api/v2/account/limits`
-        (`max_upload_size_bytes`). They are DISTINCT from the per-operation
-        processing-class band caps (`processing_class.constraints` in the
-        operation schemas; e.g. the 120 GB Enterprise merge combined band).
-
-        Used by `TierRestrictionResponse.current_tier` /
-        `TierRestrictionResponse.required_tier` and by
-        `FeatureViolation.required_tier`.
+        429 response). **The per-tier numbers are deliberately not restated
+        here** — read them from the source above.
+
       enum:
+        - basic
         - free
         - pro
         - max
         - enterprise
+      # 🔴 MACHINE-READABLE, BECAUSE THE PROSE ABOVE IS NOT CHECKABLE.
+      # OpenAPI has no per-member enum metadata, so a deprecation stated only
+      # in `description` is a judgement call at removal time — and this repo
+      # has now watched prose fail to prevent the same conflation twice.
+      # Requested by `compression_api` so that removing `free` is a check
+      # rather than an opinion.
+      x-enum-deprecated:
+        free:
+          superseded_by: basic
+          # Owner decision 2026-08-19: you can buy credits into the base tier,
+          # so "free" is false. Same ordinal — one tier under two names.
+          removal_ticket: nD8fCPDy
+          # ⚠️ NOT A DATE. Removal is gated on every consumer having stopped
+          # EMITTING and REQUIRING the value, which is evidence rather than a
+          # calendar. A date here would be overtaken and then cited.
+          # ⚠️ NOT A DATE, and now TWO conditions. `compression_api` measured
+          # production on 2026-08-27: `users.tier` `column_default` is still
+          # `'free'::character varying`. The persisted-value constant governs
+          # what the application WRITES; the default is SCHEMA, baked into a
+          # migration, so moving the constant never touched it. ⇒ "there are no
+          # `free` rows" is a fact about today's CONTENTS, not a property of the
+          # system — an INSERT omitting the column still manufactures one.
+          removal_gate: "consumer evidence table on nD8fCPDy AND the users.tier column default migrated and drained"
 
     TierRestrictionKind:
       type: string
@@ -8470,10 +8876,24 @@ components:
         workflow-create endpoints. Mirrors the API-side
         `App\Identity\Domain\Enums\RestrictionKind` PHP enum.
 
-        - `mime_type`: caller's tier does not permit this MIME type
-          (e.g. free tier uploading a video).
-        - `file_size`: file exceeds caller's tier file-size cap
-          (e.g. pro tier uploading a 1 GB file).
+        - `mime_type`: the caller's tier does not permit this MIME type.
+        - `file_size`: the file exceeds the caller's tier file-size cap.
+
+        ⚠️ **Deliberately no worked example naming a tier and a media type.**
+        Both bullets previously carried one, and an illustration of the form
+        *"free tier uploading a video"* is a per-tier capability claim wearing an
+        example's clothes — it reaches generated documentation exactly as an
+        assertion would. **Which pairs are refused is api's to enforce**, not
+        this schema's to illustrate.
+
+        ⚠️ **The two kinds resolve against DIFFERENT surfaces**, and an earlier
+        version of this note named only the numeric one:
+        - `mime_type` → the capability endpoint's `operations` map, which
+          declares accepted MIMEs per operation. `GET /api/v2/account/limits`
+          **cannot** answer a media question — it carries numeric limit entries
+          and exposes no MIME entitlement data.
+        - `file_size` → `GET /api/v2/account/limits` (`AccountLimits`), which is
+          override-aware per caller.
       enum:
         - mime_type
         - file_size
@@ -13648,9 +14068,27 @@ components:
           description: |
             Monotonically-increasing capability matrix version. Bumps
             independently of `schema_version` whenever the underlying
-            availability matrix changes (Lambda capability flips, tier
-            policy updates, V2-planned op promotions). Used as part of the
-            cache key. Per ADR-0002.
+            **availability matrix** changes — Lambda capability flips,
+            V2-planned op promotions, an operation or mime_group changing
+            its `availability` value. Used as part of the cache key.
+            Per ADR-0002.
+
+            🔴 **NEITHER VERSION IS AN ENVIRONMENT-EQUALITY PROXY, AND
+            THAT IS MEASURED RATHER THAN THEORETICAL.** On 2026-08-20
+            staging and production both served `schema_version 2.195.0`
+            and `capabilities_version 182` **while enforcing different
+            free-tier upload caps** (measured by `compression_e2e`:
+            prod `10485760`, staging `157286400`). ⇒ **Two hosts
+            reporting identical versions can behave differently**, and
+            `capabilities_version` is an easy proxy to reach for.
+
+            ⚠️ **It bumps on AVAILABILITY, not on LIMITS.** A tier's caps,
+            quotas and entitlements can change with no bump here, because
+            they are not the availability matrix — *the gate is
+            implementation, not contract.* The earlier wording said
+            "tier policy updates", which reads as covering a cap change
+            and does not. **Read a caller's own numbers from
+            `GET /api/account/limits`, never from a version number.**
           example: 47
         generated_at:
           description: |
@@ -13676,19 +14114,104 @@ components:
           example: "c4d80fb"
         environment:
           description: |
-            Deployment environment identifier (`baseline` for the
-            committed sidecar; `staging` / `production` etc. when
-            substituted at deploy time per per-environment overlays —
-            future ticket).
+            🔴 **THIS FIELD IDENTIFIES NEITHER ENVIRONMENT TODAY, AND MUST NOT
+            BE USED TO DETERMINE WHICH HOST YOU REACHED.**
+
+            Measured by `compression_e2e` on 2026-08-22, both read in the same
+            moment, anonymously: **prod and staging BOTH return `baseline`.**
+            The per-environment overlay that would substitute a real value is
+            an unshipped ticket ([`befVmKN2`](https://trello.com/c/befVmKN2)),
+            so every host serves the committed sidecar's literal.
+
+            ⚠️ **A VALUE THAT IS CONSTANT ACROSS ENVIRONMENTS LOOKS EXACTLY
+            LIKE A VALUE THAT CONFIRMS ONE.** This field previously carried
+            `example: production` — an example of a value it has never
+            returned — which taught precisely the misreading it invites.
+
+            🔑 **`fetch` follows redirects by default and does not report where
+            it ended up**, so a production host redirecting to staging returns
+            staging's schema and **nothing in this body reveals it**. The
+            catastrophic outcome is not a failure; it is a green measured
+            against staging and reported as prod. ⇒ **Assert the FINAL HOST at
+            the transport layer** (`redirect: 'error'` plus an origin check).
+            **A payload cannot corroborate which origin you reached.**
+
+            🔑 **AND IT CANNOT BE FIXED IN PLACE, WHICH IS WHY IT IS BEING
+            RENAMED RATHER THAN CORRECTED.** api traced the value:
+            `OperationSchemaController` reads it from
+            `CapabilitiesSidecar`, which reads
+            `vendor/antoniocs/compression-contracts/availability/availability.json`
+            — **a file in a VENDORED PACKAGE.** The same package is vendored
+            everywhere, so the field is **constant BY CONSTRUCTION, not
+            because somebody forgot to set it per environment.**
+
+            ⚠️ **That also corrects an earlier reading of `befVmKN2` — mine.**
+            "Substituted at deploy time" describes a mechanism that does not
+            exist for this source: a per-environment value would require
+            shipping a DIFFERENT PACKAGE per environment, which is a far
+            larger thing than an overlay. ⭐ **A label that is an INPUT to the
+            build can never be evidence about the build's runtime behaviour**
+            (frontend's line, one layer up).
+
+            ⇒ **Superseded by `capabilities_profile`**, which names what the
+            value actually is. `environment` is **DEPRECATED and retained for
+            the transition**; both carry the same value. A server-supplied
+            ORIGIN field does not exist and is not what this becomes — if one
+            is ever added it must come from the deployment (task metadata or an
+            env var), never from a vendored file.
+          oneOf:
+            - type: string
+            - type: 'null'
+          # ⚠️ `baseline`, NOT `production`. An example is documentation, and an
+          # example of a value the field has never returned is a false one.
+          example: "baseline"
+          deprecated: true
+          # 🔴 MACHINE-READABLE SUCCESSOR, so the transition is checkable
+          # rather than described. `tests/test_deprecated_fields_have_a_
+          # reachable_successor.py` reads THIS, not the prose above: if the
+          # deprecated key is in the sidecar, the successor must be there too
+          # and carry the same value. Without it the successor was declared and
+          # emitted NOWHERE, and nothing on either side could see that — it is
+          # not `required` and the response sets no `additionalProperties`,
+          # so omitting it validates clean.
+          x-superseded-by: capabilities_profile
+        capabilities_profile:
+          description: |
+            **Which capability profile the vendored contracts package carries**
+            — the honest name for the value `environment` has always held.
+
+            Sourced from the committed sidecar, so it is a property of the
+            PACKAGE, not of the host. ⚠️ **It does not identify an environment
+            and never could**: the same package is vendored everywhere. To
+            establish which host you reached, assert the FINAL HOST at the
+            transport layer.
+
+            Carries the same value as the deprecated `environment` throughout
+            the transition; consumers should move and `environment` is removed
+            once no consumer reads it.
+
+            🔴 **KNOWN READER OF `environment`, RECORDED SO THE REMOVAL
+            CONDITION IS CHECKABLE RATHER THAN ASSUMED:**
+            `compression_api` reads it — `CapabilitiesSidecar::fromArray`
+            does `$raw['environment'] ?? null` and `OperationSchemaController`
+            emits it conditionally (reported by that session, 2026-08-25).
+
+            ⚠️ **THEIR ONLY TRIPWIRE IS A TEST THAT REMOVAL TURNS RED AND
+            DEPRECATION DOES NOT** — it asserts `environment === 'baseline'`
+            against the real vendored sidecar. So the null-coalesce means a
+            removal drops the field from `/api/operations/schema` **with no
+            error anywhere**, and the deprecation window generates no signal
+            they can act on.
+
+            ⇒ **REMOVAL IS A CO-LAND, NOT A CUT.** Tell every reader listed
+            here BEFORE the removal ships, and remove a name from this list
+            only when that session confirms it has stopped reading — never
+            because the field looks unused. *"No consumer reads it"* is a claim
+            about other repositories, and this contract cannot see them.
           oneOf:
             - type: string
             - type: 'null'
-          example: "production"
-        tier_defaults:
-          # Anonymous-readable. Declared here rather than on
-          # /api/v2/account/limits because that surface is per-account and
-          # override-aware, so it 401s an anonymous caller — correctly.
-          $ref: '#/components/schemas/TierDefaults'
+          example: "baseline"
         user_tier:
           description: |
             Tier of the calling user. Anonymous (unauthenticated) callers
@@ -13701,8 +14224,17 @@ components:
             free limits were allowed to differ (hub decisions 22 + 25 —
             anonymous carries a shorter duration entitlement than a
             signed-in free user). **Anonymous is the ABSENCE of a tier, not
-            the lowest one.** Read `tier_defaults.by_audience.anonymous`
-            for what an unauthenticated caller may actually do.
+            the lowest one.**
+
+            ⚠️ **AND THERE IS NOW NO DECLARED SURFACE CARRYING AN ANONYMOUS
+            LIMITS ROW.** `tier_defaults.by_audience` used to hold one and was
+            RETRACTED (`233A3CbV`, 2026-08-20) — it encoded per-audience SIZE
+            limits, which the committed pricing model abolishes in favour of
+            technical ceilings identical for everyone. It was never served, so
+            nothing lost a value it had been reading. **Hub decision 27 required
+            the anonymous/free distinction to be expressible; it is not
+            expressible today, deliberately, and re-expressing it belongs to
+            the pricing programme's tier-entitlement work.**
           oneOf:
             - $ref: '#/components/schemas/UserTier'
             - type: 'null'
@@ -14430,13 +14962,22 @@ components:
           description: |
             Optional mime-group-level INPUT-file size ceiling in BYTES
             (ticket [`uKsFzORi`](https://trello.com/c/uKsFzORi)). Sibling of
-            `max_output_pixels`. **Applies to the enclosing operation's input** —
-            currently authored on `compress` image/document groups (the API
-            enforces it on compress input only: AVIF 20 MiB, other images 500 MiB,
-            office/ODF/EPUB 100 MiB). A consumer MUST scope it to the operation
-            whose schema carries it and MUST NOT assume it applies to other
-            operations. An oversize input is rejected at create-time (ADR-0012
-            band-ceiling 422 family).
+            `max_output_pixels`. **Applies to the enclosing operation's input**, and
+            a consumer MUST scope it to the operation whose schema carries it —
+            **the same MIME can carry different ceilings under different
+            operations, because different workers process it.** ⚠️ This line
+            previously said the ceilings were authored on `compress` only; they
+            are not, and reading a `compress` number as the binding one for a
+            `[compress, thumbnail]` chain is what let a 128 MB EPUB upload
+            succeed and then be refused (`jLxWpQEZ`). **Do not enumerate the
+            values here** — a restated table is one nothing re-measures; read
+            them from the operation's own schema.
+
+            🔴 **A GROUP WITH NO `max_input_size_bytes` HAS NOT SAID THERE IS NO
+            LIMIT.** It has said nothing. A group whose worker imposes no byte
+            ceiling declares `input_size_bound: processing_time` instead, and
+            exactly one of the two keys is present when either is. An oversize
+            input is rejected at create-time (ADR-0012 band-ceiling 422 family).
 
             **XOR with `processing_class` caps (ADR-0011):** a group carries this
             group-level cap ONLY when it has NO `processing_class` band. Banded