@giveitsmaller/contracts 0.63.0 → 0.67.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.192.0
+  version: 2.196.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)."
@@ -2369,6 +2384,252 @@ paths:
   /api/workflows/{id}/events:
     get:
       summary: Stream workflow events (SSE)
+      # THE STREAM DOES NOT LIVE ON THE API HOST. THAT IS A CONTRACT FACT,
+      # DECLARED PER-OPERATION, AND DELIBERATELY NOT A CONVENTION.
+      #
+      # ⚠️ RULING (hub, 2026-08-14, on sdks' recommendation with api agreeing):
+      # SPLIT HOSTS, DECLARED PER-OPERATION. Not string surgery on `api.*`, not
+      # a per-client rule. The reason is not aesthetic — IT IS THAT A CONVENTION
+      # CAN ONLY FAIL SILENTLY. The frontend carried `VITE_SSE_BASE_URL`
+      # (created 2026-06-17) and preferred it when set; PROD NEVER SET IT, so
+      # prod silently fell back to the gateway path and inherited an entry point
+      # that cannot stream — for weeks, while everyone believed SSE worked. A
+      # declared per-operation server cannot fail that way.
+      #
+      # 🔴 WHAT THIS DECLARATION DOES **NOT** DO, STATED BECAUSE IT IS THE
+      # DIFFERENCE BETWEEN DECLARED AND IN EFFECT: it does not repoint any
+      # existing client. Both shipped SDKs resolve EVERY url from a single
+      # configured base — PHP `GislClient::streamEvents()` builds from the same
+      # base URL as everything else, and TypeScript does likewise — and the
+      # generators emit models and supporting files rather than per-operation
+      # server handling. **A CLIENT CONFIGURED FOR `api.*` KEEPS SENDING SSE TO
+      # `api.*` AFTER THIS LANDS.**
+      #
+      # ⇒ This block makes the routing a CONTRACT FACT that a client can
+      # consume. Consuming it is a change to endpoint RESOLUTION in two
+      # languages (sdks' `VUozk5Bc`), and it is theirs. Writing "a generated
+      # client picks the host up from the contract" would be the same
+      # declared-equals-working error this comment exists to warn about.
+      #
+      # THE RULE, STATED SO NOBODY DERIVES A DIFFERENT ONE: this is the ONLY
+      # operation with its own `servers`. Every other endpoint uses the
+      # root-level `servers:`. The stream API happens to proxy `ANY /{proxy+}`
+      # — the whole API — so "route SSE at the stream host" could have meant
+      # "move everything"; IT DOES NOT. Split per-endpoint, and the split is
+      # expressed here rather than in three consumers' READMEs.
+      #
+      # WHY THE API HOST CANNOT DO THIS — mechanism, not a workaround (api,
+      # 2026-08-13, relayed via the hub; contracts has not measured it):
+      # `api.*` is an API Gateway **HTTP API** with `integration_timeout_ms`
+      # 29000 against a **30s hard AWS ceiling with no quota path**, and
+      # `responseTransferMode: STREAM` is **REST-only**. `stream.*` is a REST
+      # API with a 900000ms timeout and STREAM set. Raising a number fixes
+      # nothing.
+      #
+      # THE REVERT CONDITION IS MET. This block was reverted on 2026-08-12
+      # (27d606c) with a named gate: "re-lands when the path is PROVEN".
+      # e2e then measured `stream.staging` streaming — `:ok` at 0.0s, frames
+      # over 165s, ~16s heartbeats — while `api.staging` 503s at 29.35s, which
+      # is the integration timeout firing to the millisecond. Measured AND
+      # mechanistically explained, which is what the gate asked for.
+      #
+      # 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
+          # infer the mapping from ordering or hostname shape — which is a
+          # per-client rule, i.e. the exact thing declaring the split was meant
+          # to remove. A client matches its CONFIGURED base against
+          # `x-replaces` exactly and takes `url`; no convention, no ordering
+          # dependency, and an unmatched base is an honest "no override for the
+          # host you are pointed at" rather than a guess.
+          x-replaces: http://localhost:8080
+          description: |
+            Local development. Same origin as the rest of the API — local runs
+            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: |
+            Staging stream host. A SEPARATE PUBLIC ENTRY POINT from
+            `api.staging.giveitsmaller.com`, which is why it is declared here
+            rather than inherited: the API host fronts an integration with no
+            response-streaming mode, and this is the only endpoint that needs
+            streaming.
+
+            ⚠️ **THIS HOST ALLOWS EXACTLY ONE CORS ORIGIN, AND IT IS A
+            DIFFERENT POLICY FROM THE API HOST.** The stream stack sets
+            `cors_allow_origin` (**singular**) to the frontend host alone, in
+            **both** environments. The API host sets `cors_allow_origins`
+            (**plural**) — and **the list differs BY ENVIRONMENT**:
+
+                staging api host   localhost:5173, localhost:3000, www.staging…
+                prod    api host   www.giveitsmaller.com   ← NO localhost, never had
+                both    stream     the frontend host only  (singular)
+
+            ⇒ **A BROWSER ON localhost CAN CALL THE STAGING API HOST AND
+            CANNOT CALL EITHER STREAM HOST.** The break is **conditional on a
+            local build choosing this host**: the frontend's local build leaves
+            `VITE_SSE_BASE_URL` unset and falls back to the API host, so nothing
+            breaks today (measured by `compression_frontend`, 2026-08-14). **A
+            client that DOES point a localhost browser here is blocked, and the
+            failure arrives as a CORS error that reads as a configuration
+            mistake in their own app.**
+
+            **This is a local-development concern only; prod never permitted
+            localhost on any host** (measured by `compression_terraform`,
+            2026-08-14 — an earlier version of this note gave the staging list
+            without saying it was staging's, which would have read as universal
+            and turned a dev-experience issue into an apparent launch one).
+
+            ⚠️ **"Just add another origin" is not a CONFIG CHANGE here, and
+            the reason is our implementation rather than an AWS limit.** An API
+            Gateway **HTTP** API has a native, declarative CORS configuration
+            that takes a LIST and echoes whichever origin matches. A **REST**
+            API has no equivalent declarative feature — the value is whatever
+            the preflight MOCK integration and the backend return — so
+            multi-origin support is possible but must be **built**
+            (validate-the-Origin-then-echo), which is a change with its own
+            correctness risk rather than an extra list entry.
+
+            *(An earlier version of this note said a REST API simply cannot do
+            it. That is wrong: AWS documents that for proxy integrations the
+            BACKEND returns `Access-Control-Allow-Origin`, so per-origin
+            responses are available to anyone willing to implement them.
+            Stating a platform prohibition where an implementation choice
+            exists closes a door that is open.)*
+
+            The credentialed case does foreclose the other escape: with
+            `Allow-Credentials: true` the origin header cannot be `*`.
+
+            The same applies to embedded and third-party consumers, and to any
+            **browser build of a published SDK**: `@giveitsmaller/sdk` ships a
+            browser entry point whose client carries `streamEvents`, so this is
+            a published-surface limit rather than an internal one.
+
+            A server-side caller is unaffected. **The origin list is a property
+            of the deployed stack, not of this contract** — it is stated here
+            because a client author reading only the URL cannot discover it, and
+            it changes only in `compression_terraform`.
+
+            ⚠️ **AUTH ON THIS HOST IS CROSS-ORIGIN, AND `sessionAuth` IS THE
+            ONE THAT MAY NOT SURVIVE IT.** This operation advertises
+            `bearerAuth`, `sessionAuth` and anonymous access — but the security
+            list describes what the ENDPOINT accepts, not what a browser can
+            deliver to a different origin.
+
+            **Cookie domain scope is necessary and NOT sufficient.** A
+            credentialed cross-origin request additionally requires the client
+            to opt in (`EventSource { withCredentials: true }`, or `fetch`
+            with `credentials: 'include'`) **and** the server to answer with
+            `Access-Control-Allow-Credentials` and a non-wildcard origin. Bearer
+            and capability headers likewise need the header to be permitted by
+            the preflight response.
+
+            **None of that is verified by this contract, and contracts has not
+            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.
@@ -2426,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:
@@ -5594,7 +5933,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:
@@ -5609,7 +5954,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:
@@ -5699,7 +6048,7 @@ paths:
                   type: subscription
                   key: pro
               credit_pack:
-                summary: Buy a 25-credit pack
+                summary: Buy the £25 credit pack
                 value:
                   type: pack
                   key: pack_25
@@ -7118,6 +7467,17 @@ components:
         - `type: subscription` → `key` ∈ { `pro`, `max` }
         - `type: pack` → `key` ∈ { `pack_10`, `pack_25`, `pack_50` }
 
+        ⚠️ **The number in a pack SKU is the PRICE IN POUNDS, not a credit
+        count** — `pack_25` is the £25 pack, and the credits it grants are a
+        different number entirely, roughly two orders of magnitude larger.
+        **How many** is server-side (api's versioned Stripe catalog) and is
+        deliberately not restated here, because a credit grant that lives in
+        two places drifts — and the copy a customer reads before paying is the
+        one that must not be stale. Clients that need to show it read it from
+        the server; they never infer it from the SKU. *An example on this very
+        endpoint read the SKU as a quantity until 2026-08-12, so the axis is
+        named here rather than assumed obvious.*
+
         The `type` ↔ `key` pairing is validated **server-side**, not by this
         schema (the `key` enum lists all values across both types). A
         mismatched or unprovisioned pair returns `422` `UNPROCESSABLE_ENTITY`;
@@ -7220,15 +7580,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
@@ -7256,133 +7624,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
@@ -8255,48 +8496,138 @@ components:
         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 IN PLACE AND
+        WILL BE REMOVED** (ticket [`nD8fCPDy`](https://trello.com/c/nD8fCPDy)).
+        Owner decision 2026-08-19: **you can buy credits into the base tier, so
+        calling it "free" is false.** Both values are accepted through the
+        transition and **occupy the same ordinal position** — they are one tier
+        under two names, never two tiers.
+
+        ⚠️ **A CONSUMER MUST TREAT THEM AS EQUAL.** Anything that compares,
+        sorts or gates on tier must accept either and rank them identically;
+        a `match`/`switch` that handles `free` and not `basic` will silently
+        take a different branch the day the producer switches.
+
+        🔴 **PRODUCERS: DO NOT EMIT `basic` YET. THE FIRST WRITE IS AN
+        OUTAGE, NOT A COMPILE ERROR.** This change makes the value *legal*, not
+        *live*. **Schema-additive and safe-to-send are different claims**, and
+        the gap between them is measured rather than theoretical:
+
+        - **api (2026-08-20, from its own mapping):** `UserRecord` declares the
+          column `enumType: UserTier::class`. Doctrine hydrates such a column
+          through `EnumPropertyAccessor::setValue()`, which calls
+          `$enumType::from($value)` — **and that THROWS on a value it does not
+          know**, with no extension point. **A row persisted as `basic` makes
+          every running api task 500 while hydrating that user.**
+        - **And the rollout overlaps by design:** ECS runs
+          `minimumHealthyPercent: 100` / `maximumPercent: 200`, so the NEW task
+          starts before the OLD one drains. **The moment a new task writes a
+          value the old one has never heard of, the old task 500s on that row
+          for the rest of the rollout.**
+        - **SDKs fail earlier and more kindly:** a generated Rust or PHP enum
+          gains a variant and an exhaustive match stops compiling.
+
+        ⭐ **AN ADDED ENUM VALUE IS A CONTRACT CHANGE WEARING A SCHEMA CHANGE'S
+        CLOTHES.** A new COLUMN is invisible to old code's `SELECT` list; a new
+        enum VALUE is **not** invisible to old code's hydration. *That asymmetry
+        is why expand → migrate → contract fails to get applied to enums — the
+        trigger does not look like the category.* (api's own note, written
+        during an earlier enum sweep and reached independently of this one.)
+        Emission is gated on the tolerance evidence table
+        ([`tkRA9Bim`](https://trello.com/c/tkRA9Bim)), which requires an
+        artefact from each of api, both SDK packages, frontend and e2e.
+
+        🔴 **`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`/`free` < `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:**
+
+        - it asserted *"`free`: image MIMEs only … video/audio are MIME-gated
+          away from Free"* — a per-tier media restriction this contract does not
+          own and cannot keep true;
+        - and the parallel table on `AccountLimits` listed tier byte defaults
+          for `free` / `pro` / `enterprise` and **silently omitted `max`**, a
+          tier this very enum declares. **That one was already wrong before any
+          of it was reviewed.**
+
+        **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 —
+        not the old restriction, and not its replacement.** 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. The
+        category axis as DATA, once, uniform across audiences. **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.
+          removal_gate: "consumer evidence table on nD8fCPDy"
 
     TierRestrictionKind:
       type: string
@@ -8305,10 +8636,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
@@ -13483,9 +13828,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: |
@@ -13519,11 +13882,6 @@ components:
             - 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'
         user_tier:
           description: |
             Tier of the calling user. Anonymous (unauthenticated) callers
@@ -13536,8 +13894,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'
@@ -13970,11 +14337,16 @@ components:
     EndpointProjection:
       type: object
       description: |
-        Per-endpoint projection entry per ADR-0016 §D4. Five fields;
-        `required_tier` and `availability` at endpoint level are
-        reserved/null today (operation-level `required_tier` continues
-        to flow via `operations.*.required_tier`; every shipped
-        endpoint is currently `availability: stable`).
+        Per-endpoint projection entry per ADR-0016 §D4. Five required
+        fields plus an OPTIONAL `servers`; `required_tier` at endpoint
+        level is reserved/null today (operation-level `required_tier`
+        continues to flow via `operations.*.required_tier`).
+
+        ⚠️ **`availability` is DERIVED from the operation's
+        `x-availability` and is no longer always `stable`** — an
+        earlier version of this description said every shipped endpoint
+        was `stable`, which was true only because the generator
+        hardcoded it.
       required:
         - auth
         - identity_scoped
@@ -13982,6 +14354,54 @@ components:
         - availability
         - operation_id
       properties:
+        servers:
+          type: array
+          minItems: 1
+          description: |
+            OPTIONAL. Present **only** when the operation overrides the
+            root host — today, the SSE stream endpoint alone.
+
+            **Absence means "inherits the root `servers`" and is not a
+            gap.** Emitting a copy of the root on every entry would put
+            one value on 43 rows, which conveys nothing and would invite
+            a consumer to read this projection as the routing source of
+            record for endpoints that have no override.
+
+            ⚠️ **This field exists because the declaration was
+            unreachable without it.** The routing split is declared on
+            the operation in `openapi/api.yaml`, but SDK consumers read
+            this sidecar rather than parsing the spec at runtime — so a
+            host declared only in the spec was in the same position as
+            the convention it replaced.
+          items:
+            type: object
+            additionalProperties: false
+            required: [url, replaces]
+            properties:
+              url:
+                type: string
+                format: uri
+                description: The host serving this operation.
+              replaces:
+                type: string
+                minLength: 1
+                description: |
+                  **The ROOT server URL this entry overrides.** A client
+                  matches its own configured base against this exactly
+                  and takes `url`.
+
+                  ⚠️ **Without it the mapping has to be inferred** from
+                  list ordering or hostname shape — which is a
+                  per-client rule, and therefore the precise thing that
+                  declaring the split was meant to remove. An
+                  unmatched base is an honest *"no override for the host
+                  you are pointed at"* rather than a guess.
+              description:
+                type: string
+                description: |
+                  Verbatim from the operation's server entry. Carries
+                  the caveats a URL cannot — CORS scope, whether the
+                  entry exercises the split-host topology at all.
         auth:
           type: string
           enum: [anonymous, optional, required]
@@ -14019,9 +14439,17 @@ components:
           type: string
           enum: [stable, beta, experimental, planned, deprecated]
           description: |
-            Endpoint-level availability tag. Currently always
-            `"stable"` for shipped endpoints. Reserved for future
-            `planned` / `deprecated` endpoint-level annotation.
+            Endpoint-level availability, **DERIVED from the operation's
+            `x-availability`** and defaulting to `stable` when the
+            operation declares none.
+
+            ⚠️ **It is NOT always `stable`.** This description used to
+            say it was, and the sidecar agreed with it — because the
+            generator HARDCODED the value. Four endpoints read `planned`
+            today, three of which (`probeUpload`,
+            `createExternalImport`, `decodeAudioWatermark`) had declared
+            `planned` in the spec all along and were silently
+            contradicted.
         operation_id:
           type: string
           description: |