@giveitsmaller/contracts 0.67.0 → 0.69.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.196.0
+  version: 2.199.0
   contact:
     name: API Support
 
@@ -454,10 +454,26 @@ paths:
                     feature_tier_restricted: '#/components/schemas/FeatureTierRestrictedResponse'
         '413':
           description: |
-            File exceeds the absolute maximum upload size (across all
-            tiers). For tier-specific size caps below this absolute
-            limit, the server returns 403 with
-            `error_type: tier_restriction, restriction_kind: file_size`.
+            Two rejection cases, discriminated by the `ErrorEnvelope.error`
+            code — the same pair as `POST /api/uploads`.
+
+            - **Byte size** — the file exceeds the absolute maximum upload size
+              (across all tiers). For tier-specific size caps below this
+              absolute limit, the server returns 403 with
+              `error_type: tier_restriction, restriction_kind: file_size`.
+            - **Pixel dimensions** (`error: IMAGE_DIMENSIONS_TOO_LARGE`) — as
+              declared on `POST /api/uploads`: a decodable raster image whose
+              `width x height` exceeds the configured pixel ceiling
+              (`UPLOAD_MAX_IMAGE_PIXELS`, default 16 MP), read from the file
+              **header** and rejected **before** decoding.
+
+            🔴 **THIS CASE WAS UNDECLARED HERE UNTIL 2026-08-28, AND THIS IS
+            THE PATH IT MATTERS MOST ON.** Multipart exists for LARGE uploads,
+            so a high-pixel image is *more* likely to arrive here than on the
+            single-shot endpoint where the ceiling was documented. A ceiling
+            declared on the small-file path and omitted from the large-file
+            path is worse than one declared nowhere: a consumer who reads the
+            contract concludes the rule does not apply here.
           content:
             application/json:
               schema:
@@ -1244,20 +1260,29 @@ paths:
         - name: archived
           in: query
           required: false
-          x-availability: planned
-          description: |
-            🔴 **NOT IMPLEMENTED — see the `planned` note below. A server
-            that does not support this parameter SILENTLY IGNORES IT and
-            returns the DEFAULT (non-archived) list.** That is the dangerous
-            half of this feature and the reason it is called out here rather
-            than only on the endpoints: `POST .../archive` would 404, which is
-            loud and teaches the caller immediately, whereas
-            **`archived=true` returns a 200 carrying the wrong rows.** A
-            consumer asking for their archive receives their NON-archived
-            workflows and is told nothing. **Silent wrong data beats a 404
-            every time for damage.**
-            Until the server implements it, a client MUST NOT present an
-            "archived" view built on this parameter.
+          x-availability: stable
+          description: |
+            ⚠️ **A SERVER THAT DOES NOT SUPPORT THIS PARAMETER SILENTLY
+            IGNORES IT and returns the DEFAULT (non-archived) list** — it
+            does not error. That asymmetry is why this is called out on the
+            parameter and not only on the endpoints: `POST .../archive`
+            would 404, which is loud and teaches the caller immediately,
+            whereas **`archived=true` returns a 200 carrying the wrong
+            rows** — a consumer asking for their archive receives their
+            NON-archived workflows and is told nothing. **Silent wrong data
+            beats a 404 every time for damage.**
+
+            ✅ **IMPLEMENTED. This was `planned` and carried a "clients MUST
+            NOT present an archived view" prohibition; both are struck.**
+            Verified on `compression_api` `origin/main` before the flip
+            rather than on report: the `ArchiveWorkflow` and
+            `RestoreWorkflow` command handlers exist, and
+            `WorkflowListReadPort` takes the `bool $archived` filter.
+            ⚠️ **What that establishes is that the code is MERGED, not that
+            a given environment is running it** — availability in this
+            contract has no environment axis, so read this as the shape
+            being committed, and confirm deployment from the environment
+            rather than from here.
 
             Archived-row filter (ticket
             [`j2s6T2qf`](https://trello.com/c/j2s6T2qf)). **Default `false`**:
@@ -2851,6 +2876,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:
@@ -5189,6 +5369,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: |
@@ -5608,7 +5852,29 @@ paths:
       summary: Get current credit balance
       description: |
         Returns a snapshot of the caller's credit position at request
-        time. Per ticket [I23 `DffjC3zm`](https://trello.com/c/DffjC3zm)
+        time.
+
+        🔴 **EVENTUALLY CONSISTENT WITH A COMPLETED CHECKOUT, AND THIS
+        RESPONSE CARRIES NO FRESHNESS SIGNAL.** A credit-pack purchase is
+        granted on an asynchronous server-to-server callback, so a
+        snapshot taken just after the Stripe redirect **may legitimately
+        predate the grant**. There is **no timestamp, no version, no
+        pending state and no session correlation** here — the fields
+        below are the whole of it — so **this endpoint cannot
+        distinguish "the grant has not landed yet" from "the payment did
+        not credit you".**
+
+        ⇒ **Do not treat an unchanged balance after checkout as a
+        failure.** Those two states need opposite handling — *wait*
+        versus *contact support* — and the way to tell them apart is
+        `GET /api/v2/credits/usage`, correlating on the checkout
+        `session_id`, not this endpoint. See
+        `POST /api/billing/checkout` for the full model, **including
+        that nothing detects a callback which never arrives.**
+
+        ⛔ **No interval is stated anywhere in this contract**, because
+        none has been measured end to end. Any client timeout is the
+        client's own choice and is not sanctioned here. Per ticket [I23 `DffjC3zm`](https://trello.com/c/DffjC3zm)
         + plan v5 §F9 round-13 narrowing — this endpoint is the
         canonical user-visible billing-state surface.
 
@@ -6013,6 +6279,43 @@ paths:
         frontend can hide/disable the upgrade affordance without
         hard-coding the rollout state.
 
+        🔴 **THE CREDIT GRANT IS ASYNCHRONOUS. THE BALANCE WILL NOT
+        REFLECT IT WHEN STRIPE REDIRECTS THE USER BACK.** Credits are
+        granted on the server-to-server callback, which arrives
+        independently of the browser redirect. A client reading
+        `GET /api/v2/credits/balance` immediately on return **may
+        legitimately see the pre-purchase value, and that is not an
+        error.**
+
+        **How to observe the grant:** poll `GET /api/v2/credits/usage`
+        for a transaction whose `reference_id` equals the `session_id`
+        returned here. That is the only client-observable correlation
+        between a checkout and its credits. ⚠️ See
+        `CreditTransaction.reference_id` — **the pack-purchase path does
+        not populate it yet**, so today there is nothing to match on.
+
+        ⛔ **NO TIMING IS STATED, DELIBERATELY.** The interval is
+        dominated by the provider's callback delivery latency, which
+        **this system does not measure**. Production has processed
+        **zero** such events; staging exactly one, a synthetic rehearsal
+        purchase — n=1, idle box, caller not a browser. **No bound is
+        derivable from that**, and a client MUST NOT build a timeout
+        from any figure in this contract, because there is none.
+
+        ⇒ **Show a pending state rather than a failure.** Absence of
+        credits after checkout is **indeterminate, not negative**.
+
+        🔴 **AND THE BRANCH A CLIENT MUST NOT BE PROMISED AWAY FROM:
+        NOTHING DETECTS A CALLBACK THAT NEVER ARRIVES.** Recovery relies
+        on the provider's own retries. There is **no server-side
+        reconciliation** comparing completed checkouts against granted
+        credits, and an event already marked terminal **cannot be
+        reopened**. **No customer-visible recovery route exists and no
+        automated one** — the manual path is an operator action. ⇒ A
+        client that has waited past any interval it considers reasonable
+        should **direct the user to support with the `session_id`**,
+        which is the only handle both sides share.
+
         The Stripe **webhook** (`POST /api/webhooks/stripe`) is a
         server-to-server, signature-authenticated callback and is
         deliberately **not** part of this client contract.
@@ -6726,6 +7029,10 @@ components:
         customer path carries the same signal as the SSE/message
         surface. Cross-spec enum parity is verified by
         `tests/test_asyncapi_named_schemas.py`.
+      # OPEN. Purely diagnostic — it reports which path `auto` took so a caller can
+      # see why. An unrecognised path does not change any decision a consumer makes,
+      # so a new one is safely ignorable and additive.
+      x-enum-openness: open
       enum:
         - stream_copy
         - re_encode
@@ -6752,6 +7059,12 @@ components:
         See `schemas/FORMAT.md` §Availability Taxonomy and
         `docs/decisions/0001-contract-first-availability.md` for the full
         rules, vocabulary rationale, and parser obligations.
+      # CLOSED. A consumer uses this to decide whether to EXPOSE a feature, so an
+      # unrecognised level cannot be handled safely in either direction — hiding a
+      # live capability or surfacing one that is not. ADR-0001 §1.3 defines exactly
+      # these five; a sixth is a contract event that consumers must be updated for,
+      # and failing loudly is the correct way to require that.
+      x-enum-openness: closed
       enum:
         - stable
         - beta
@@ -7654,8 +7967,23 @@ components:
         overridden:
           type: boolean
           description: |
-            True iff a per-account override is active (i.e. `effective`
-            comes from an override rather than the tier default).
+            Whether `effective` came from a per-account override rather than
+            the tier default.
+
+            🔴 **RESERVED, AND STRUCTURALLY `false` TODAY — DO NOT BRANCH ON
+            IT.** No per-account override store exists, and the API's resolver
+            is called with no override for either limit, so **every response
+            carries `false`, and will until an override store ships.**
+            Measured by `compression_api` on 2026-08-28.
+
+            ⚠️ It is declared **required**, so a consumer must handle a field
+            that currently takes exactly one value. It is kept rather than
+            removed because this is the shape an environment-overridable limit
+            needs, and removing it would be a breaking change to re-make later.
+
+            📌 **A test asserting `overridden === false` would be a decoration
+            — no input makes it fail.** When an override store exists, assert
+            against that, not against this field now.
 
     CreditTransaction:
       type: object
@@ -7782,10 +8110,31 @@ components:
           type: string
           description: |
             Identifier of the referenced entity. Typically a UUID v7
-            for `workflow` references, but other reference types
-            (`top_up` carrying a Stripe payment intent ID,
-            `cycle_grant` carrying a cycle date, etc.) may use
-            non-UUID identifiers. NOT constrained to `UuidV7`.
+            for `workflow` references; other reference types may use
+            non-UUID identifiers and this is NOT constrained to
+            `UuidV7`.
+
+            🔴 **FOR A `top_up` FROM CHECKOUT THIS IS THE CHECKOUT
+            SESSION ID (`cs_...`) — THE IDENTIFIER THE CLIENT ACTUALLY
+            HOLDS.** It is returned as
+            `BillingCheckoutSession.session_id` when the session is
+            created, and it is the handle that makes the asynchronous
+            credit grant observable. See `POST /api/billing/checkout`.
+
+            ⚠️ **This description previously named a Stripe PAYMENT
+            INTENT id.** A client never receives one — checkout returns
+            `checkout_url` and `session_id` and nothing else — so the
+            only correlator this contract named was one the caller
+            could not obtain.
+
+            🔴 **NOT YET POPULATED ON THE PACK-PURCHASE PATH.**
+            `compression_api` measured 2026-08-28: the pack grant writes
+            a free-text description naming the SKU and leaves
+            `reference_type` / `reference_id` empty, so **two purchases
+            of the same pack are indistinguishable**. Reservations do
+            populate them. Until the session id is wired through, a
+            `top_up` row carries no correlator and the polling strategy
+            described on checkout has nothing to match on.
         created_at:
           type: string
           format: date-time
@@ -8309,6 +8658,9 @@ components:
           rule when product/Lambda confirms detection logic.)
 
         Per ticket [I25 `i5yCuSZc`](https://trello.com/c/i5yCuSZc).
+      # `WarningType` carries the NORMATIVE statement of the additive convention
+      # ("SDKs MUST treat the enum as additive"), so it is open by its own declaration.
+      x-enum-openness: open
       enum:
         - redundant_pre_encode_before_reencode_merge
 
@@ -8490,52 +8842,72 @@ 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.
 
-        🔴 **`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.
+        `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
@@ -8545,7 +8917,7 @@ components:
         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
+        Ordering is `basic` < `pro` < `max` < `enterprise` (the
         upgrade-resolver / `isHigherThan` ordinal in `UserTier.php`).
         **The ordering is the part this contract owns** — it is what
         `TierRestrictionResponse.current_tier` / `.required_tier` and
@@ -8556,28 +8928,22 @@ components:
         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.**
+        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 —
-        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.
+        ⚠️ **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:**
@@ -8606,6 +8972,14 @@ components:
         429 response). **The per-tier numbers are deliberately not restated
         here** — read them from the source above.
 
+      # CLOSED, AND DELIBERATELY SO. The values are an ORDERED ladder driving upgrade
+      # prompts and tier comparisons — an unknown tier cannot be RANKED, so a consumer
+      # that silently accepted one would place it arbitrarily in that ordering.
+      # Failing on an unknown tier is the correct behaviour.
+      # SURVEY TRAP: this schema's description mentions "typed-open", but that
+      # sentence is about `AccountLimits.limits`, NOT about this enum. A keyword
+      # sweep reads it as open. It is not.
+      x-enum-openness: closed
       enum:
         - basic
         - free
@@ -8627,7 +9001,14 @@ components:
           # ⚠️ 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"
+          # ⚠️ 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
@@ -9219,6 +9600,9 @@ components:
           server. Equivalent to `cancelled` for downstream
           accounting; distinct status so dashboards can surface the
           natural-expiry vs caller-initiated distinction.
+      # Declared "additive widening; V1 clients ignoring unknown enum values
+      # continue to function".
+      x-enum-openness: open
       enum:
         - pending
         - in_progress
@@ -9246,6 +9630,8 @@ components:
         - `in_progress`: At least one operation is running.
         - `completed`: All operations completed successfully.
         - `failed`: Job failed (at least one operation failed).
+      # Declared "additive widening".
+      x-enum-openness: open
       enum:
         - pending
         - waiting
@@ -9319,6 +9705,13 @@ components:
         V1 `watermark` operation removed at V2 cutover (I4-CONS) —
         replaced by `image_watermark` + `text_watermark` per ADR-0004
         §"Greenfield V2.0 cutover".
+      # CLOSED on BOTH sides, and the two sides declare DIFFERENT VALUE SETS on
+      # purpose — see schemas/cross-document-enums.yaml. openapi types the CREATE
+      # SURFACE; asyncapi types the PAYLOAD FIELD, which stays coarse because the
+      # thumbnail sub-types travel on the SNS message ATTRIBUTE, not in the payload.
+      # Closed because an unrecognised operation type cannot be dispatched or
+      # rendered; guessing is never right.
+      x-enum-openness: closed
       enum:
         - compress
         - thumbnail
@@ -9428,10 +9821,31 @@ components:
             use the multipart flow
             (`POST /api/uploads/multipart/initiate` → chunk PUTs →
             `POST /api/uploads/multipart/complete`). 10 MB /
-            10,000,000 bytes — chosen to match the ALB-fronted
-            single-request body cap. Raising this requires
-            infrastructure work (ALB swap or rearchitect; out of
-            scope for this ticket).
+            10,000,000 bytes — matching the **API Gateway HTTP API
+            payload quota** that fronts `api.<domain>`.
+
+            🔴 **THIS CANNOT BE INCREASED.** AWS documents the HTTP API
+            payload limit as 10 MB, "Can be increased: No". It is a
+            platform quota, not a tunable setting, so there is no
+            configuration change or support request that raises it —
+            only a different ingress would.
+
+            ⚠️ **This line previously said the cap matched an
+            "ALB-fronted single-request body cap" and that raising it
+            required an "ALB swap".** There is no ALB in front of
+            `/api/uploads`; the ALB module is instantiated only for
+            `stream.<domain>`. `compression_api` measured this on
+            2026-08-28.
+
+            ⇒ **The NUMBER was right and the RECORDED REASON was wrong,
+            which is the more dangerous way round**: a correct value
+            never triggers a review, and the rationale is what the next
+            person acts on. **And the error pointed the permissive
+            way** — it named a load-balancer setting somebody could
+            raise, where the real constraint is a non-adjustable quota.
+            Anyone revisiting this would have gone looking for a load
+            balancer that is not there, concluded the cap was tunable,
+            and planned work that cannot succeed.
         multipart_chunk_size:
           type: integer
           format: int64
@@ -11092,6 +11506,10 @@ components:
         value is that sentence. Emit it in preference to a
         measurement-asserting value whenever the metrics were absent,
         even if the class ultimately chosen happens to be correct.
+      # OPEN BY CITED CONVENTION, AND IT SAID SO NOWHERE. `WarningType` names it in
+      # the precedent set and this declaration was silent — so a generator reading
+      # only this schema could not learn it. That is the gap this marker closes.
+      x-enum-openness: open
       enum:
         - within_short_form_limits
         - input_size_exceeds_short_form
@@ -11517,6 +11935,11 @@ components:
           could not extract enough metadata to make a routing
           decision. Caller may proceed at their own risk; the
           workflow-create routing fallback applies.
+      # OPEN. `ok` is the only proceed value and everything else is a reason not to,
+      # so a consumer branches on `ok` rather than enumerating failures. A new
+      # failure reason is additive and an old consumer treats it correctly as
+      # not-ok.
+      x-enum-openness: open
       enum:
         - ok
         - corrupt
@@ -11533,6 +11956,11 @@ components:
         the file (e.g. free-tier caller probing a long-form clip,
         or any caller probing a `corrupt` / `unsupported_codec`
         file).
+      # CLOSED. It GATES AN AFFORDANCE: `blocked` is a hard stop and the others
+      # predict routing. An unrecognised class cannot be safely treated as routable —
+      # a consumer guessing would offer an upload the server will refuse. A new
+      # class must reach consumers deliberately.
+      x-enum-openness: closed
       enum:
         - short_form
         - long_form
@@ -13874,14 +14302,136 @@ 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.
+
+            **AS MERGED ON THEIR `main` — api #662, merge commit `25801c8d`,
+            verified by ref 2026-08-28, not taken on report:**
+
+            - the read is **successor-preferred**: `capabilities_profile`
+              when provided, `environment` only as a fallback for a sidecar
+              predating the rename. `null` and `''` count as *not provided*
+              and fall back; a **present-but-wrong-type successor does NOT
+              fall back**, so a corrupt successor is never masked by the
+              predecessor's value.
+            - `DeprecatedEnvironmentKeyRemovalTriggerTest` fires on **four**
+              conditions — this contract **stops declaring** `environment`,
+              **loses `deprecated: true`**, **stops naming its successor**
+              via `x-superseded-by`, or **`availability.json` stops carrying
+              `environment`**. ⇒ **api goes red on the removal by itself**,
+              whichever artefact moves first.
+
+            🔴 **THE SIDECAR IS STILL A LEVER — ON THEIR BUILD, NOT ON THEIR
+            WIRE, AND THE TWO NOW POINT OPPOSITE WAYS.** api emits
+            `environment` as a **MIRROR of the resolved profile** rather than
+            as an independent read of the sidecar, so dropping it from
+            `availability.json` **no longer changes their wire output** — it
+            used to. It does now turn their **CI test suite** red, via
+            `testTheSidecarStillCarriesTheDeprecatedKeyItIsMirroredFrom`,
+            proved by mutation rather than by reading.
+            ⛔ **That is a PHPUnit alarm, NOT a build or deploy gate.** Their
+            production image installs without dev dependencies and neither
+            `ci-deploy.yml` nor `deploy-prod.yml` runs PHPUnit — `phpunit`
+            appears in `ci.yml` alone (verified against their `origin/main`).
+            ⇒ **An affected revision can BUILD AND DEPLOY, with the alarm
+            arriving separately.** The control gives detection, not
+            prevention, and the two must not be read as one.
+            ⚠️ **Under expand → migrate → contract the sidecar half fires
+            FIRST**, because the normal ordering drops the key there before
+            retiring the declaration here. ⇒ **Retiring the key quietly via
+            the sidecar ahead of this schema no longer half-works silently;
+            it fails loudly**, which is the outcome to want.
+            ⚠️ **That decoupling is the deliberate price of mirroring**, which
+            is what stops the successor drifting from the field it
+            supersedes; the four-condition control is what pays for it.
+            Recorded here rather than discovered later.
+
+            ⇒ **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"
+          example: "baseline"
         user_tier:
           description: |
             Tier of the calling user. Anonymous (unauthenticated) callers
@@ -14632,13 +15182,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