@giveitsmaller/contracts 0.73.0 → 0.76.0

package/openapi/api.yaml

@@ -35,6 +35,20 @@ info:
     (parser obligation: absent = stable; per-enum-value granularity is the
     `per_value_availability` primitive landed via ticket I17).
 
+    **Free-text string fields: `x-string-vocabulary` (ticket
+    [`Q79yjcFF`](https://trello.com/c/Q79yjcFF)).** A `type: string` field
+    with no `enum` that names example values says, as data, what a client
+    may do with them (the same marker is used in the AsyncAPI document):
+    - `open` — a vocabulary that grows. Each published value keeps its
+      meaning, the SET is not closed: switch on the values you know and
+      handle an unknown one as the generic case (e.g. `ErrorEnvelope.error`).
+    - `advisory` — explanatory text. Display or log it; **never switch on
+      it** (e.g. `SseWorkflowTerminalData.reason`).
+    - `none` — not a vocabulary at all (an expression or an identifier,
+      e.g. `OptionSchema.pattern`).
+    A field whose description hedges with "common values" or "free-form"
+    must carry the marker; a test enforces it.
+
     **Localisation (per ticket [I26](https://trello.com/c/rcnqwgI4)).**
 
     Error responses + paused/blocked workflow statuses carry a localised
@@ -89,7 +103,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.208.0
+  version: 2.211.0
   contact:
     name: API Support
 
@@ -250,8 +264,16 @@ paths:
               tier_restriction, restriction_kind: file_size` instead.
             - **Pixel dimensions** (`error: IMAGE_DIMENSIONS_TOO_LARGE`) — a
               decodable raster image whose `width × height` exceeds the
-              configured pixel ceiling (`UPLOAD_MAX_IMAGE_PIXELS`, default
-              16 MP). The server reads dimensions from the file **header** (no
+              SINGLE-SHOT pixel ceiling (`UPLOAD_MAX_IMAGE_PIXELS`, default
+              16 MP), sized for the API's inline decode on this endpoint.
+              Multipart uploads have their own, higher ceiling
+              (`limits.max_multipart_upload_image_pixels`). It is an
+              environment setting, so an **authenticated**
+              client should read the effective value from
+              `limits.max_upload_image_pixels` on `GET /api/v2/account/limits`
+              (once the API emits it) rather than hard-code a number. ⚠️ That
+              endpoint requires authentication, so an **anonymous** uploader has
+              no discovery surface for it yet and learns it from this 413. The server reads dimensions from the file **header** (no
               full-bitmap decode) and rejects **before** decoding, so a
               within-byte-limit but huge-dimension image (e.g. a few-KB 26 MP
               PNG that would decode to ~100 MB) is rejected up front rather than
@@ -276,17 +298,21 @@ paths:
         '415':
           description: |
             Unsupported file type at the contract level (no tier permits
-            this MIME). For tier-specific MIME restrictions where some
-            tier does permit the MIME, the server returns 403 with
-            `error_type: tier_restriction, restriction_kind: mime_type`
-            instead.
+            this MIME): `error: UNSUPPORTED_FILE_TYPE`, flat envelope, never
+            retryable and never an upgrade prompt. For tier-specific MIME
+            restrictions where some tier does permit the MIME, the server
+            returns 403 with `error_type: tier_restriction, restriction_kind:
+            mime_type` instead. The file-type check runs before the size
+            check, so an unsupported file that is also too large gets this
+            415.
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorEnvelope'
               example:
                 success: false
-                error: "Unsupported MIME type: application/x-msdownload"
+                error: "UNSUPPORTED_FILE_TYPE"
+                message: "This file type is not supported."
         '422':
           description: |
             Tier-relative cap exceeded for this upload per ticket
@@ -461,11 +487,22 @@ paths:
               (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.
+            - **Pixel dimensions** (`error: IMAGE_DIMENSIONS_TOO_LARGE`) — a
+              decodable raster image whose `width x height` exceeds the
+              MULTIPART pixel ceiling, read from the file **header** and
+              rejected **before** decoding. It is a SEPARATE, HIGHER ceiling
+              than single-shot's 16 MP (owner ruling 2026-09-24, card
+              [`ae4Q1yCb`](https://trello.com/c/ae4Q1yCb)): single-shot's is
+              sized for the API's inline decode, which multipart never does,
+              and multipart carries ordinary camera photos — **a 24 MP photo
+              must pass**. API setting `UPLOAD_MAX_MULTIPART_IMAGE_PIXELS`,
+              enforced at multipart initiate. Default 50 MP (hub ruling 2026-09-24, on lambdas'
+              recommendation: the image workers declare a 100 MP source cap,
+              but none has run a job that large, so it stays at half that
+              until a staging proof). It is an API setting, so authenticated
+              clients read the effective value from
+              `limits.max_multipart_upload_image_pixels`
+              (`GET /api/v2/account/limits`) once the API emits it.
 
             🔴 **THIS CASE WAS UNDECLARED HERE UNTIL 2026-08-28, AND THIS IS
             THE PATH IT MATTERS MOST ON.** Multipart exists for LARGE uploads,
@@ -480,9 +517,11 @@ paths:
                 $ref: '#/components/schemas/ErrorEnvelope'
         '415':
           description: |
-            Unsupported file type at the contract level. For tier-specific
-            MIME restrictions, the server returns 403 with
-            `error_type: tier_restriction, restriction_kind: mime_type`.
+            Unsupported file type at the contract level (no tier permits
+            this MIME): `error: UNSUPPORTED_FILE_TYPE`, as on
+            `POST /api/uploads`. For tier-specific MIME restrictions, the
+            server returns 403 with `error_type: tier_restriction,
+            restriction_kind: mime_type`.
           content:
             application/json:
               schema:
@@ -1032,9 +1071,13 @@ paths:
         bad ones before submit.
 
         Per ticket [I28 `KbVAnGCm`](https://trello.com/c/KbVAnGCm).
-        `availability: planned` until the cross-repo Lambda support
-        ships; the runtime returns `feature_not_available` (422)
-        until then. Per Tension 1 (ADR-0001 §1.3).
+        `availability: planned`. The upload-probe Lambda exists and runs
+        asynchronously when an upload is finalised; this endpoint returns
+        the cached result when one exists and `feature_not_available`
+        (422) when none does yet. It does not invoke the probe itself.
+        (A `planned` endpoint that answers 200 is inconsistent with the
+        availability taxonomy; the flip decision is tracked separately,
+        card `kAT0i5A6`.) Per Tension 1 (ADR-0001 §1.3).
 
         **SDK helper intent.** SDKs are expected to expose a
         `client.preflight_clips([file_ids])` helper that compiles to N
@@ -1045,11 +1088,10 @@ paths:
         **Tier scoping.** The probe respects the caller's tier — the
         `processing_class_pre_assignment` reflects the same logic
         F8.1 upload-side gating uses (per ticket I15-CONS), which
-        honours a class's `required_tier`. **Since 2026-09-23 no callable
-        video class carries one** (decision 26, `jLuZvlJe`; only the
-        `planned` `audio_watermark` keeps `enterprise`), so for every
-        callable class the pre-assignment depends on the file's duration
-        and size, not on the caller's tier.
+        honours a class's `required_tier`. **Since 2026-09-23 no class
+        carries one** (decision 26, `jLuZvlJe`, `UAQJcOi7`), so the
+        pre-assignment depends on the file's duration and size, not on
+        the caller's tier.
 
         **Idempotent.** Probing the same file_id twice returns the
         same `probed_at` timestamp + result (cached server-side per
@@ -1154,8 +1196,8 @@ paths:
                 $ref: '#/components/schemas/ErrorEnvelope'
         '422':
           description: |
-            The endpoint is `availability: planned` and the runtime
-            Lambda has not yet shipped — returned as
+            No probe result is cached for this upload yet (the probe runs
+            asynchronously after the upload is finalised) — returned as
             `FeatureNotAvailableResponse` with `error_type:
             feature_not_available`. Per Tension 1 (ADR-0001 §1.3).
           content:
@@ -1905,7 +1947,9 @@ paths:
             (`propertyName: error_type`):
             - `validation_error` → `ValidationErrorEnvelope` (carries
               `details[]`; the specific failure is in the `error` machine
-              code — `INVALID_OPTIONS`, `REQUIRES_REENCODE`,
+              code — `VALIDATION_FAILED` (an option or value failed
+              validation: unknown key, out of range, wrong type, enum),
+              `REQUIRES_REENCODE`,
               `CYCLIC_WORKFLOW_EDGES`, …). The `REQUIRES_REENCODE` flavour
               (per I16-CONS) reuses this same envelope/`error_type` and is
               distinguished only by its `error` code.
@@ -1958,18 +2002,16 @@ paths:
                     probe_pending: '#/components/schemas/ProbePendingResponse'
               examples:
                 validation_error:
-                  summary: Generic validation error (legacy shape)
+                  summary: An option failed validation (as the API emits it — VALIDATION_FAILED, details[] of {field, message})
                   value:
                     success: false
                     error_type: "validation_error"
-                    error: "INVALID_OPTIONS"
+                    error: "VALIDATION_FAILED"
                     details:
-                      - operation: "compress"
-                        option: "quality"
-                        message: "Must be between 1 and 100"
-                      - operation: "thumbnail"
-                        option: "width"
-                        message: "Required field"
+                      - field: "quality"
+                        message: "Option 'quality' must be at most 100."
+                      - field: "width"
+                        message: "Option 'width' is required."
                 cyclic_workflow_edges:
                   summary: Cyclic or self-referential explicit workflow_edges (g8PPkbNu)
                   value:
@@ -3033,10 +3075,34 @@ paths:
             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.
+            silently.**
+
+            - **Since 2026-09-23 (`compression_frontend` #485, `17bd8b6`,
+              ticket `nuipMybn` — built against this section's obligation):**
+              a `429` / `503` **carrying `Retry-After` or the API's error
+              envelope** is a deliberate refusal, not a transport error (`SseRefusedError`,
+              carrying the status, the `Retry-After` delay and the `error`
+              code). The reader keeps `/status` polling, reopens the stream
+              only after `Retry-After` has elapsed — a wait that applies to
+              **every** stream that browser tab opens, not only the refused
+              one (it is held in the page, so another tab of the same caller
+              does not share it) —
+              and **never reopens** a refusal that carried no `Retry-After`.
+              ⚠️ **Two edges it does not cover, stated so this is not read as
+              blanket compliance:** an UNSTRUCTURED `503` (a load balancer's,
+              with neither) still takes the transport path below; and a
+              `Retry-After` too large for the browser's timer keeps THAT run on
+              polling but does not set the caller-wide wait, so another stream
+              in the same tab may open before it elapses. This contract sets
+              no upper bound on `Retry-After`.
+            - **Before that (measured 2026-08-25):** a non-200 was raised as a
+              *transport error* and retried a bounded number of times on a
+              fixed delay. Any other non-200 status, and the unstructured `503`
+              above, still takes that transport path.
+
+            Either way the fallback is `/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
@@ -3048,8 +3114,9 @@ paths:
             🔴 **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**.
+            short poll is not a held connection — while that client's polls go
+            **up**. (Its stream re-attempts no longer do: since #485 they wait
+            out `Retry-After`.)
             ⚠️ **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
@@ -3057,9 +3124,10 @@ paths:
 
             ⚠️ **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
+            is **UNMEASURED** — refusals issued together with the same
+            `Retry-After` reopen together (the delay is the server's, with no
+            client jitter), 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.**
 
@@ -3070,10 +3138,11 @@ paths:
             before `Retry-After` elapses, never retried as a transport error,
             and `/status` polling permitted under that endpoint's own limits.
             ⚠️ **`Retry-After` governs the next STREAM request, not a poll
-            interval.** Falling back to polling is still load, merely cheaper,
-            and the measured behaviour above is what a client does TODAY; a
-            client that treats refusal as a transport error does not yet meet
-            the obligation.
+            interval.** Falling back to polling is still load, merely cheaper.
+            Our frontend meets the obligation since #485 for structured
+            refusals with a timer-sized `Retry-After` (the two edges above are
+            the exceptions); any reader that treats refusal as a transport
+            error does not.
 
             📌 **THE POPULATIONS SPLIT BY READER KIND, NOT BY
             BROWSER-VERSUS-NOT.** The WHATWG rule covers **native
@@ -3081,7 +3150,9 @@ paths:
             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.**
+            population, not exempt from it** — it is safe today because #485
+            made it so, and a regression in its code would not be visible
+            here.
 
             ✅ **For OUR SDKs that is measured, not assumed** (sdks,
             2026-08-22, driven through the BUILT client with a stubbed
@@ -3148,8 +3219,11 @@ paths:
         - `unspent_reservation_released`: the workflow was in
           `pending` / `in_progress` / `paused_insufficient_credits`,
           and the unspent portion of the original reservation has
-          been refunded to the caller's balance. The refund appears
-          as a separate `CreditTransaction` with `type: refund`.
+          been refunded to the caller's balance. The return appears
+          as a separate `CreditTransaction` with `type:
+          reservation_release` and `reference_type:
+          workflow_reservation_release` — there is no `type: refund`
+          (the API's ledger type is a closed set that has none).
         - `none`: no refund was issued (e.g. all reserved credits
           were already consumed by completed jobs at cancel time;
           or the workflow was already terminal in a previous cancel
@@ -5824,9 +5898,12 @@ paths:
         `schemas/operations/audio_watermark.yaml` — the operation
         embeds; this endpoint decodes.
 
-        **Tier-restricted.** This endpoint is `enterprise`-only. Free
-        and `pro` callers receive a 403 `feature_tier_restricted`.
-        Anonymous callers receive a 401.
+        **No tier gate** (since 2026-09-23, decision 26 — the paired
+        `audio_watermark` operation lost its `enterprise` gate the same
+        day; `X8m2vbvS`), and no 403 is declared: decode reads an
+        already-uploaded file, so no upload quota applies here. Any
+        authenticated caller may call it once it ships. Anonymous
+        callers receive a 401.
 
         **Scope: own watermarks only.** The decoder will refuse to
         extract from media the caller did not mark themselves
@@ -5847,7 +5924,7 @@ paths:
         `feature_not_available` (422) until the Lambda lands. Per
         Tension 1 (ADR-0001 §1.3).
       operationId: decodeAudioWatermark
-      security: [{bearerAuth: []}, {sessionAuth: []}]  # required (explicit 401 in response set; tier-gated runtime call)
+      security: [{bearerAuth: []}, {sessionAuth: []}]  # required (explicit 401 in response set; authenticated runtime call, no tier gate)
       tags:
         - AudioWatermark
       x-availability: planned
@@ -5870,22 +5947,6 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorEnvelope'
-        '403':
-          description: |
-            Tier insufficient (free / pro caller) — returned as
-            `FeatureTierRestrictedResponse` with
-            `error_type: feature_tier_restricted`. Per ADR-0001 §1.3.
-          content:
-            application/json:
-              schema:
-                oneOf:
-                  - $ref: '#/components/schemas/TierRestrictionResponse'
-                  - $ref: '#/components/schemas/FeatureTierRestrictedResponse'
-                discriminator:
-                  propertyName: error_type
-                  mapping:
-                    tier_restriction: '#/components/schemas/TierRestrictionResponse'
-                    feature_tier_restricted: '#/components/schemas/FeatureTierRestrictedResponse'
         '404':
           description: |
             No watermark detected in the supplied asset, OR the
@@ -6047,9 +6108,11 @@ paths:
         Per ticket [I23 `DffjC3zm`](https://trello.com/c/DffjC3zm).
 
         Each transaction is immutable once written. Workflow-create
-        reservations appear here as a single row; refunds appear as
-        separate rows referencing the original via `reference_id`
-        (and `reference_type: workflow`).
+        reservations appear here as a single row (`reference_type:
+        workflow_reservation`); credits returned appear as separate
+        rows carrying the workflow in `reference_id` and a
+        `reference_type` naming how they came back (see
+        `CreditTransaction.reference_type`).
 
         Default page is 20 transactions, ordered most-recent-first.
       operationId: getCreditsUsage
@@ -6119,7 +6182,7 @@ paths:
                           purchased_amount: null
                           pricing_version: "v3.2.0"
                           description: "Workflow reservation: compress.video short_form"
-                          reference_type: "workflow"
+                          reference_type: "workflow_reservation"
                           reference_id: "019539ac-2222-7000-8000-000000000001"
                           created_at: "2026-04-26T13:55:00Z"
                         - id: "019539ad-3333-7000-8000-aaaaaaaaaa02"
@@ -6134,14 +6197,14 @@ paths:
                           purchased_amount: -25
                           pricing_version: "v3.2.0"
                           description: "Workflow reservation: merge.video long_form_re_encode"
-                          reference_type: "workflow"
+                          reference_type: "workflow_reservation"
                           reference_id: "019539ac-2222-7000-8000-000000000002"
                           created_at: "2026-04-26T13:54:00Z"
                       total: 47
                       limit: 20
                       offset: 0
-                refund_followup:
-                  summary: Refund row referencing the prior workflow_001 reservation
+                reservation_release_followup:
+                  summary: Release row returning the prior workflow_001 reservation
                   value:
                     success: true
                     data:
@@ -6151,7 +6214,7 @@ paths:
                         # workflow_001.monthly_balance_after (955); after
                         # adds back 45 → 1000.
                         - id: "019539ad-3333-7000-8000-aaaaaaaaaa03"
-                          type: "refund"
+                          type: "reservation_release"
                           amount: 45
                           monthly_balance_before: 955
                           monthly_balance_after: 1000
@@ -6161,8 +6224,8 @@ paths:
                           monthly_amount: 45
                           purchased_amount: null
                           pricing_version: "v3.2.0"
-                          description: "Refund: terminal failure on operation-compression-video"
-                          reference_type: "workflow"
+                          description: "Reservation released: terminal failure on operation-compression-video"
+                          reference_type: "workflow_reservation_release"
                           reference_id: "019539ac-2222-7000-8000-000000000001"
                           created_at: "2026-04-26T13:56:00Z"
                       total: 47
@@ -6302,8 +6365,8 @@ paths:
                           tier_default: 10485760
                           overridden: false
                         max_total_input_size_bytes:
-                          effective: 1073741824
-                          tier_default: 1073741824
+                          effective: 5000000000
+                          tier_default: 5000000000
                           overridden: false
                 enterprise_with_upload_override:
                   summary: >-
@@ -6376,8 +6439,11 @@ paths:
         **How to observe the grant:** poll `GET /api/v2/credits/usage`
         for a transaction whose `reference_id` equals the `session_id`
         returned here, and whose `reference_type` is
-        `stripe_checkout_session`. That is the only client-observable
-        correlation between a checkout and its credits.
+        `stripe_checkout_session`. **Today that is the only
+        client-observable correlation** between a checkout and its credits.
+        `GET /api/billing/checkout/{sessionId}/status` is declared as the
+        second one, but it is `planned` (a `422 feature_not_available`)
+        until the API implements it.
 
         🔴 **MATCH ON `reference_type` + `reference_id`, AND DO NOT
         FILTER ON `type`.** The pack grant is written as an
@@ -6535,7 +6601,7 @@ paths:
                   value:
                     success: false
                     error_type: feature_not_available
-                    error: FEATURE_NOT_AVAILABLE
+                    error: UNPROCESSABLE_ENTITY
                     message: "Checkout is not yet available."
                     violations:
                       - feature: endpoint.billing.checkout
@@ -6601,6 +6667,105 @@ paths:
               schema:
                 $ref: '#/components/schemas/ErrorEnvelope'
 
+  /api/billing/checkout/{sessionId}/status:
+    get:
+      summary: Status of a checkout session the caller created
+      description: |
+        Whether the credits for a checkout the caller started have been
+        granted. Ticket [`7cSI8eIa`](https://trello.com/c/7cSI8eIa) — declared
+        BEFORE the API builds it (hub ruling, Option A, 2026-08-29); the API
+        half is [`JHrV4MUg`](https://trello.com/c/JHrV4MUg).
+
+        **Why it exists:** between "checkout created" and "the provider's
+        callback lands" nothing used to record that the session existed or
+        whose it was — so a post-checkout page, asked about the NORMAL
+        page-load state, had nothing to ask. The fix records the session at
+        creation; this endpoint reads that record and the credit ledger.
+
+        | `status` | meaning |
+        |---|---|
+        | `paid` | the purchase this session was for has been applied to the caller's account — for a credit **pack**, a credit transaction referencing this session exists; for a **subscription**, the subscription it started is active on the caller's account |
+        | `pending` | the session is recorded as created BY THE CALLER and its purchase has not been applied yet — **not a failure** |
+        | `unknown` | anything else |
+
+        🔴 **`unknown` DELIBERATELY COLLAPSES "not yours" WITH "never
+        existed". This is a decision, not missing detail.** Telling them
+        apart would make this endpoint an oracle for whether an arbitrary
+        session id is real — a probe confirming a stranger's purchase exists.
+        The requirement is *paid AND yours*; the honest refusal admits
+        neither. ⛔ **Do not "improve" the answer by distinguishing the two**
+        (a 403 or 404 for someone else's session is the same oracle).
+
+        ⛔ **No provider call on this read path.** It will be polled; a
+        third-party call would turn provider latency and outages into page
+        states and put the secret key on a read path.
+
+        ⛔ **No timing is stated here either** — the reason is the one given
+        on `POST /api/billing/checkout` (the delay is the provider's callback
+        latency, which this system does not measure). `pending` is a normal
+        state to keep polling on, not an error.
+      operationId: getCheckoutSessionStatus
+      security: [{bearerAuth: []}, {sessionAuth: []}]  # required; answers only about the caller's own sessions
+      x-identity-scoped: true  # a session belongs to the caller who created it
+      x-availability: planned
+      tags:
+        - Billing
+      parameters:
+        - name: sessionId
+          in: path
+          required: true
+          description: The `session_id` returned by `POST /api/billing/checkout`.
+          schema:
+            type: string
+            minLength: 1
+      responses:
+        '200':
+          description: |
+            The session's status for this caller. **Once implemented, always
+            200 for an authenticated caller**, whatever the session id —
+            `unknown` is the answer for anything not provably the caller's (see
+            the collapse rationale above). While the endpoint is `planned` it
+            answers `422 feature_not_available` instead.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CheckoutSessionStatusResponse'
+              examples:
+                paid:
+                  summary: Credits granted
+                  value:
+                    success: true
+                    data:
+                      session_id: cs_test_a1b2c3
+                      status: paid
+                pending:
+                  summary: Recorded for this caller, grant not landed yet
+                  value:
+                    success: true
+                    data:
+                      session_id: cs_test_a1b2c3
+                      status: pending
+                unknown:
+                  summary: Not provably this caller's — or never existed
+                  value:
+                    success: true
+                    data:
+                      session_id: cs_test_zzz
+                      status: unknown
+        '401':
+          description: Authentication required.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '422':
+          description: |
+            `feature_not_available` while this endpoint is `planned`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/FeatureNotAvailableResponse'
+
   # ============================================
   # CONTACT ENDPOINT
   # ============================================
@@ -6828,12 +6993,22 @@ components:
           enum: [false]
         error:
           type: string
+          x-string-vocabulary: open
           description: |
-            Stable, machine-readable error code (e.g.
-            `INVALID_OPTIONS`, `BALANCE_EXHAUSTED`,
+            Machine-readable error code. **Each published code is stable; the
+            SET is open** (`x-string-vocabulary: open`): handle an unknown code
+            as a generic error. E.g.
+            `VALIDATION_FAILED`, `BALANCE_EXHAUSTED`,
             `REQUIRES_REENCODE`). Canonical English; never localised.
             SDKs duck-type on this field for typed error-branch
-            helpers.
+            helpers — **except where an HTTP-status-shaped code
+            (`UNPROCESSABLE_ENTITY`, `BAD_REQUEST`, …) covers several
+            branches: there `error_type` is the discriminator.**
+            Example: `POST /api/billing/checkout` answers
+            `UNPROCESSABLE_ENTITY` both when checkout is switched off
+            (`error_type: feature_not_available`) and when a pack or
+            plan is not provisioned (no `error_type`); only
+            `error_type` tells them apart.
 
             Multipart-session resume codes (per ticket
             [`HxUmVr3Y`](https://trello.com/c/HxUmVr3Y), V2.10.0):
@@ -6954,21 +7129,33 @@ components:
             dispatch on `error_type` instead of structural `instanceOf`
             guards (which mis-fire on camelCase-vs-snake_case property
             names). Distinct from the `error` machine code below: `error`
-            carries the specific failure code (`INVALID_OPTIONS`,
+            carries the specific failure code (`VALIDATION_FAILED`,
             `REQUIRES_REENCODE`, `CYCLIC_WORKFLOW_EDGES`, …) while
             `error_type` only names the envelope shape.
         error:
           type: string
-          description: |
-            Stable error code. Common values: `INVALID_OPTIONS`
-            (generic option/value validation failure), `REQUIRES_REENCODE`
+          x-string-vocabulary: open
+          description: |
+            Error code. **Each published code is stable; the SET is open**
+            (`x-string-vocabulary: open`): handle an unknown code as a generic
+            validation error. Codes emitted today: `VALIDATION_FAILED`
+            (request, query-param **and workflow-create option/value**
+            validation failure — the API emits it for every create-time
+            option error: unknown key, out of range, wrong type, bad enum
+            value; `details[]` items carry `field` = the option key and
+            `message`), `REQUIRES_REENCODE`
             (per ticket I16-CONS — `merge.video` with
             `re_encode_mode: never` and incompatible inputs; caller
             resolves by switching to `re_encode_mode: auto` or `always`),
             `CYCLIC_WORKFLOW_EDGES` (cyclic/self explicit `workflow_edges`,
-            per `g8PPkbNu`), `VALIDATION_FAILED` (request/query-param
-            validation failure per the project-wide convention — e.g.
-            `GET /api/v2/credits/usage` invalid `limit`/`offset`).
+            per `g8PPkbNu`).
+            ⚠️ **`INVALID_OPTIONS` is NOT a create-time wire code**, though
+            earlier text here said it was and the example showed it: the
+            API has always sent `VALIDATION_FAILED` for option failures
+            (measured on prod by `compression_e2e`, 2026-09-23;
+            `WorkflowController` maps every `validation_error` to it).
+            `invalid_options` lives on the worker's
+            `OperationResult.error_code` (asyncapi), not on this envelope.
             SDKs duck-type on this field for typed error-branch helpers.
         message:
           type: string
@@ -7075,6 +7262,7 @@ components:
           enum: [false]
         error:
           type: string
+          x-string-vocabulary: open
           description: |
             Stable machine-readable failure code. `UNPROCESSABLE_ENTITY`
             for the generic auth domain rejections (register /
@@ -7987,6 +8175,32 @@ components:
         data:
           $ref: '#/components/schemas/AccountLimits'
 
+    CheckoutSessionStatusResponse:
+      type: object
+      # Envelope CLOSED, payload OPEN — the repo's success-envelope convention:
+      # top-level drift is detected, and new `data` fields stay additive.
+      additionalProperties: false
+      required: [success, data]
+      properties:
+        success:
+          type: boolean
+          enum: [true]
+        data:
+          type: object
+          required: [session_id, status]
+          properties:
+            session_id:
+              type: string
+              description: Echo of the path parameter.
+            status:
+              type: string
+              enum: [paid, pending, unknown]
+              x-enum-openness: closed
+              description: |
+                `paid` / `pending` / `unknown` — see
+                `GET /api/billing/checkout/{sessionId}/status`. `unknown`
+                collapses "not yours" and "never existed" on purpose.
+
     AccountLimits:
       type: object
       # Open payload (response data target stays open for additive evolution —
@@ -8047,6 +8261,29 @@ components:
               # api emits it. Unit is SECONDS — carried by the key name, per
               # AccountLimitEntry.
               $ref: '#/components/schemas/AccountLimitEntry'
+            max_upload_image_pixels:
+              # OPTIONAL in this expand step (ONxpaAlk); NOT required until api
+              # emits it. The upload gate's pixel ceiling for decodable rasters
+              # (width x height from the header) — the 413
+              # IMAGE_DIMENSIONS_TOO_LARGE threshold. It is an ENV KNOB on the
+              # API (UPLOAD_MAX_IMAGE_PIXELS), so the contract carries the
+              # SHAPE and the server serves the NUMBER; a number written here
+              # could drift from the running value by a task-definition edit.
+              # Not tier-varying today: `tier_default` equals `effective`.
+              # SINGLE-SHOT only (POST /api/uploads): sized for the API's inline
+              # decode. Multipart has its own key below (ae4Q1yCb).
+              $ref: '#/components/schemas/AccountLimitEntry'
+            max_multipart_upload_image_pixels:
+              # OPTIONAL in this expand step (ae4Q1yCb, owner ruling 2026-09-24);
+              # NOT required until api emits it. The MULTIPART upload pixel
+              # ceiling (width x height from the header) — the 413
+              # IMAGE_DIMENSIONS_TOO_LARGE threshold on the multipart path. A
+              # SEPARATE, HIGHER API setting than max_upload_image_pixels:
+              # default 50 MP (hub, 2026-09-24), about half the workers'
+              # declared 100 MP source cap, which is unproven end to end; it
+              # rises only after a 100 MP staging proof. It MUST admit a 24 MP
+              # photo. The server serves the number. Not tier-varying today.
+              $ref: '#/components/schemas/AccountLimitEntry'
 
     AccountLimitEntry:
       type: object
@@ -8101,9 +8338,10 @@ components:
       description: |
         Single ledger entry. Immutable once written. A workflow-create
         reservation appears here as a single row with `source_bucket`
-        indicating which pool(s) were debited; refunds appear as
-        separate rows referencing the original via `reference_id` and
-        `reference_type: workflow`.
+        indicating which pool(s) were debited; a returned reservation
+        appears as a separate `reservation_release` row referencing the
+        workflow via `reference_id` (see `reference_type` for the
+        values that distinguish a release from a settle refund).
 
         `type`, `pricing_version`, and `reference_type` are
         deliberately free-form strings — their value sets evolve with
@@ -8132,11 +8370,16 @@ components:
           $ref: '#/components/schemas/UuidV7'
         type:
           type: string
-          description: |
-            Ledger entry type — free-form string. Common values:
-            `reservation`, `refund`, `top_up`, `monthly_grant`,
-            `adjustment`. Not enumerated to avoid contract churn as
-            billing event taxonomy evolves.
+          x-string-vocabulary: open
+          description: |
+            Ledger entry type — free-form string. Values the API emits
+            today (its `CreditTransactionType`, a closed set): `grant`,
+            `deduction`, `adjustment`, `overdraft_repayment`,
+            `reservation`, `reservation_release`. **There is no
+            `refund`, `top_up` or `monthly_grant`** — earlier text listed
+            them, and a consumer filtering on one matched nothing. Not
+            enumerated in the schema to avoid contract churn as billing
+            event taxonomy evolves; SDKs duck-type.
         amount:
           type: integer
           description: |
@@ -8200,6 +8443,7 @@ components:
             applies symmetrically.
         pricing_version:
           type: string
+          x-string-vocabulary: none
           description: |
             Pricing-table version applied to this transaction.
             Free-form string (server emits a semver-shaped or
@@ -8213,10 +8457,16 @@ components:
           description: Human-readable description of the ledger entry.
         reference_type:
           type: string
-          description: |
-            What the transaction references. Common values:
-            `workflow`, `top_up`, `cycle_grant`, `adjustment`.
-            Free-form string.
+          x-string-vocabulary: open
+          description: |
+            What the transaction references. Free-form string. Values
+            the API emits for workflow credits: `workflow_reservation`
+            (the debit), `workflow_reservation_release`,
+            `workflow_pause_release`, `workflow_expiry_release` and
+            `workflow_settle_refund` (credits returned);
+            `stripe_checkout_session` for a credit-pack purchase. Match
+            on this field, not on `type`, to tell a release from a
+            settle refund.
         reference_id:
           type: string
           description: |
@@ -8274,6 +8524,7 @@ components:
         # additively from the API ahead of this contract.
         state:
           type: [string, "null"]
+          x-string-vocabulary: open
           description: |
             Reservation lifecycle state — free-form string (kept opaque like
             `type`/`reference_type` for churn-resistance; SDKs duck-type).
@@ -8585,10 +8836,11 @@ components:
         Effect of a workflow cancel on outstanding credit
         reservations.
         - `unspent_reservation_released`: caller refunded for the
-          unspent portion of the original reservation; refund
-          appears as a separate `CreditTransaction` (`type: refund`,
-          `reference_type: workflow`, `reference_id` matching the
-          cancelled workflow).
+          unspent portion of the original reservation; the return
+          appears as a separate `CreditTransaction` (`type:
+          reservation_release`, `reference_type:
+          workflow_reservation_release`, `reference_id` matching the
+          cancelled workflow). There is no `type: refund`.
         - `none`: no refund issued (all reserved credits already
           consumed by completed jobs at cancel time, OR the
           workflow was already terminal in a previous cancel — the
@@ -9837,6 +10089,12 @@ components:
     OperationType:
       type: string
       description: |
+        ⚠️ **HOMONYM:** `asyncapi/events.yaml` also declares an `OperationType` —
+        the narrower event PAYLOAD vocabulary. This one is the CREATE surface.
+        Same name, different membership; generated SDKs emit both, and the
+        import path is the only distinguisher (not renamed — breaking;
+        `bFy3zo5Y`). Relation asserted in `schemas/cross-document-enums.yaml`.
+
         Available operation types:
         - compress: Reduce file size (images, audio, video, documents)
         - thumbnail: Legacy thumbnail value. Generates a preview image
@@ -9862,11 +10120,11 @@ components:
         - convert: Change file format (all types)
         - custom_luma: Apply a caller-uploaded luma matte to a base video for a custom luma-matte transition effect. Multi-input (`role: base` + `role: transition_mask`). `availability: planned` (no tier gate); dispatch returns `feature_not_available` (422) until Lambda ships. Distinct from FFmpeg `xfade=custom` (which is an expression, not an operation). Per ticket I29 (Trello EPUE5Vs1).
         - audio_overlay: Mix a secondary audio asset over a primary audio or video base (DJ tags, podcast intros/outros, station IDs, jingles). Multi-input (`role: base` + `role: overlay`). `availability: planned`; dispatch returns `feature_not_available` (422) until Lambda ships. **NOT** the same as `audio_watermark` — that operation is steganographic (imperceptible identifier embedded for ownership tracking), tracked separately by I20. Per ticket I19 (Trello Xr3Z4GBF).
-        - audio_watermark: Embed a steganographic forensic watermark into an audio asset (or a video's audio track) — Cinavia / Resemble PerTh territory. Single-input. `availability: planned` + `required_tier: enterprise`; dispatch returns `feature_not_available` (422) until Lambda ships. Pairs with `POST /api/audio-watermark/decode` for own-watermarks-only extraction. Per ticket I20 (Trello omiCq7Vn).
+        - audio_watermark: Embed a steganographic forensic watermark into an audio asset (or a video's audio track) — Cinavia / Resemble PerTh territory. Single-input. `availability: planned` (no tier gate since 2026-09-23); dispatch returns `feature_not_available` (422) until Lambda ships. Pairs with `POST /api/audio-watermark/decode` for own-watermarks-only extraction. Per ticket I20 (Trello omiCq7Vn).
         - audio_to_video: Produce a video from an audio input plus an OPTIONAL still image overlay. Multi-input role-based with the first OPTIONAL role on the contract (`role: base` audio required, `role: overlay` image 0..1 — see `per_role_cardinality`). When overlay is omitted, the video uses a solid background colour. `availability: planned` — WITHDRAWN 2026-09-15: measured 0.300 s of encode per second of output PLUS A 7 s FIXED COST, so the advertised PT2H needs 2167 s against a 900 s platform maximum (0.300 x 7200 alone is 2160 — the intercept is what makes the figure 2167, and a consumer dividing 600 by 0.300 gets a 2000 s in-flight boundary where the real one is 1976 s). Returns `feature_not_available` (422) at workflow-create. An already-accepted workflow is not cancelled (availability is checked at create) and fails only when its output duration exceeds ~1976 s ON THE INPUT THE RATE WAS MEASURED WITH (a real photographic 1080p still plus looped real audio), where 0.300 s per second plus a 7 s fixed cost reaches the worker's 600 s cap — the 60 s and 120 s measured cells both COMPLETED. The driver is the STILL'S RESOLUTION, not duration alone: a 4K still is roughly 4x the rate (unmeasured), which would put the boundary near a quarter of that, and this schema places no constraint on the overlay's resolution. Per ticket [`SlluxMBN`](https://trello.com/c/SlluxMBN) + ADR-0015 (introduces `per_role_cardinality` vocab).
         - video_watermark: Apply an image overlay onto a base video via FFmpeg's `overlay` filter. Multi-input role-based (`role: base` video + `role: overlay` image, exactly one of each per `per_role_cardinality`). Re-encode required; audio stream-copy passthrough. Distinct from `image_watermark` (pure-Rust/image-only). `availability: planned` — WITHDRAWN 2026-09-15, operation AND `short_form`: a real 1080p source at the advertised PT5M / 500 MB was killed at 606 s by the worker's 600 s encode cap, no output. Returns `feature_not_available` (422) at workflow-create; an already-accepted workflow is not cancelled and fails only if it exceeds that cap; the 606 s kill is ONE measured point and nothing measured says where the boundary is. `long_form` and `multi_overlay_stack` were already `planned`. Per ticket [`4NrRPCgh`](https://trello.com/c/4NrRPCgh) + ADR-0013.
         - video_text_watermark: Render a text overlay onto a base video via FFmpeg's `drawtext` filter. Single-input — text and styling in options. Same `watermark_mode` (single/tiled), anchor + margin vocab as `text_watermark`. Re-encode required; audio stream-copy passthrough. `availability: planned` — WITHDRAWN 2026-09-15, operation AND `short_form`: a real 1080p source at the advertised PT5M was killed at 604 s by the worker's 600 s encode cap. Returns `feature_not_available` (422) at workflow-create. ⚠️ This entry previously read "until Lambda ships", which was wrong in a way that mattered: the worker SHIPPED and runs — it is the CEILING that cannot be served. Per ticket [`4NrRPCgh`](https://trello.com/c/4NrRPCgh) + ADR-0013.
-        - split: Fan one input file into N outputs across GIF / PDF / audio / video MIME families. Single-input per-mime-group catalog (mirrors merge/convert): GIF uses `frame_range` (REQUIRED) + `output_format`; PDF uses `page_range` OR `page_groups` (mutually exclusive); audio + video use a `mode` discriminator (interval/count/cut_points) + numeric-seconds wire format + `precision` flag (fast/exact). 200-output hard cap per ADR-0009 §D5 with per-mode preflight math; output naming `output-001..output-200`. Long-form video routes to a separate `split-video-fargate` worker via `processing_class`. `availability: beta` for the `audio` and `video` mime_groups (workers live on staging — shape-stable + opt-in, MUST NOT 422); video activates BOTH classes (`video.processing_class.short_form: beta` AND `long_form: beta` — `split-video-fargate` deployed + wired on staging but NOT yet proven end-to-end per [`rcwvUKhI`](https://trello.com/c/rcwvUKhI); the first customer-path soak has not completed, the 4GB+ speed-up is unmeasured, and the long-form fan-out is flag-gated dark). The `image_gif` and `document_pdf` mime_groups stay `availability: planned` and dispatch returns `feature_not_available` (422) until their workers ship. Per ticket [`vKI0CFDu`](https://trello.com/c/vKI0CFDu) + ADR-0014.
+        - split: Fan one input file into N outputs across GIF / PDF / audio / video MIME families. Single-input per-mime-group catalog (mirrors merge/convert): GIF uses `frame_range` (REQUIRED) + `output_format`; PDF uses `page_range` OR `page_groups` (mutually exclusive); audio + video use a `mode` discriminator (interval/count/cut_points) + numeric-seconds wire format + `precision` flag (fast/exact). 200-output hard cap per ADR-0009 §D5 with per-mode preflight math; output naming `output-001..output-200`. Long-form video routes to a separate `split-video-fargate` worker via `processing_class`. `availability: beta` for the `audio` and `video` mime_groups (workers live on staging — shape-stable + opt-in, MUST NOT 422); video activates BOTH classes (`video.processing_class.short_form: beta` AND `long_form: beta` — `split-video-fargate` deployed + wired on staging; it stays `beta` until a PRODUCTION `customer_path` run is recorded in `availability/prod-verification-log.yaml` per [`rcwvUKhI`](https://trello.com/c/rcwvUKhI)). The `image_gif` and `document_pdf` mime_groups stay `availability: planned` and dispatch returns `feature_not_available` (422) until their workers ship. Per ticket [`vKI0CFDu`](https://trello.com/c/vKI0CFDu) + ADR-0014.
         - passthrough: Inert lossless source operation. A single-input source job whose SOLE operation is `passthrough` emits its source bytes UNCHANGED — no compression, no Lambda. The API self-completes the job at publish (terminal output = the upload `{bucket, key}` unchanged). Its purpose is to feed an uploaded file into a multi-input operation LOSSLESSLY: because `JobInputV2.source` is narrowed to exclude upload-direct, an upload that must enter a `merge` / `archive` / `image_watermark` op enters via a `passthrough` source job referenced downstream by `{type: job_output, from: <id>}` — preserving billing / DAG / lineage. Distinct from `operations: []` (which keeps its implicit-compress meaning on a single-input upload job); `passthrough` is the EXPLICIT lossless path via the "non-empty `operations[]` without `compress` = compression opt-out" rule. Media-agnostic; no options. `availability: beta` — activated (the inputs[]-narrowing + passthrough self-complete mechanism is deployed API-side); workflow-create accepts `passthrough` source jobs and MUST NOT return `feature_not_available`. **Never published to SNS** — deliberately absent from the AsyncAPI routing enums (API self-completes; no `ops-passthrough` queue). Per ticket [`4som89Uh`](https://trello.com/c/4som89Uh) + ADR-0004 (planned→beta flip).
 
         - transform: Geometric/orientation transform — v1 = rotate (0/90/180/270) + flip (none/horizontal/vertical/both), ADR-0026. Single-input; `produces: same_as_input` (geometry preserves format/container). Chainable (NOT sole_op); canonical single-job chain order is `transform → convert → compress → thumbnail` (geometry before encode/derive so downstream width/height/fit refer to the final frame). Media groups: image (still jpeg/png/webp + animated `image_gif`), video (mp4/webm), document (PDF page-rotate only — no flip); audio not supported. ALL groups `availability: planned` (epic `fhiWebI0`) — workflow-create returns `feature_not_available` (422) until per-media Lambdas ship. A no-op transform (`rotate: 0` + `flip: none`) is rejected as `invalid_options`. The public operation type is `transform`; the API resolves an internal per-media SNS routing sub-type (`transform_image` / `transform_video` / `transform_document`) — those sub-types are routing-only and are NOT part of this public enum. Per ADR-0026.
@@ -10754,13 +11012,9 @@ components:
         The two forms are mutually exclusive (a request supplies exactly
         one — enforced by the `oneOf` below); they are NOT combined.
 
-        🔴 **THE FLAT FORM IS `planned`, AND THE SERVER DOES NOT ACCEPT IT
-        YET.** Send `jobs[]`. A flat request is rejected today, and the
-        rejection is currently a generic *"At least one job is required"*
-        rather than the `feature_not_available` (422) envelope this contract
-        requires for a `planned` shape — tracked against `compression_api`,
-        so do not read that generic message as a validation error in your
-        own payload.
+        🔴 **THE FLAT FORM IS `planned`.** Send `jobs[]`. A flat request is
+        rejected with the `feature_not_available` (422) envelope (feature
+        `workflow.request.flat_form`) until the API accepts the flat form.
 
         ⚠️ **The equivalence stated above is the DESIGN, not observed
         behaviour.** It describes what the server will do once the lowering
@@ -10916,11 +11170,12 @@ components:
           $ref: '#/components/schemas/NotifyConfig'
           description: |
             Optional per-job completion-notification config
-            (channel-agnostic). Currently exposes the `email` channel: the
-            API emails the configured recipients when the selected workflow
-            events occur, with a **server-composed** presigned `/downloads`
-            link to the results — the request carries recipients + event
-            selection only.
+            (channel-agnostic). Declares the `email` channel: once the
+            dispatch engine ships, the API emails the configured recipients
+            when the selected workflow events occur, with a
+            **server-composed** presigned `/downloads` link to the results —
+            the request carries recipients + event selection only. Nothing is
+            sent today (see `NotifyConfig`).
 
             **Advertised-ahead (contract-first, ticket
             [`IQtEwVET`](https://trello.com/c/IQtEwVET)):** the completion-
@@ -11462,6 +11717,7 @@ components:
             job that consumes this output.
         node_id:
           type: string
+          x-string-vocabulary: open
           description: |
             Symbolic composition `node_id` correlating this delivered output
             to its canonical node in `composition_plan` (e.g. `encode`,
@@ -11753,6 +12009,7 @@ components:
           $ref: '#/components/schemas/ProcessingClass'
         execution_pool:
           type: string
+          x-string-vocabulary: advisory
           description: |
             Logical pool name. **Opaque string** — not an enum — so
             future pool naming evolves without contract churn. Known
@@ -12016,6 +12273,7 @@ components:
       properties:
         node_id:
           type: string
+          x-string-vocabulary: open
           description: |
             Stable **symbolic** canonical node id (e.g. `original`,
             `processed_base`, `encode`, `thumbnail`). The correlation key
@@ -12038,6 +12296,7 @@ components:
             nodes `type` is the operation as submitted.
         chain_group:
           type: string
+          x-string-vocabulary: open
           description: |
             Which canonical stage this operation belongs to. **Open string,
             NOT a fixed enum** (mirrors `ProcessingPlanJob.execution_pool`) —
@@ -12166,10 +12425,8 @@ components:
         `blocked` is emitted when no tier-permitted pool exists for
         the file — any caller probing a `corrupt` /
         `unsupported_codec` file, or a caller below a class's
-        `required_tier`. Since 2026-09-23 (decision 26) the only
-        video classes still carrying one are `audio_watermark`'s
-        (`enterprise`, both `planned`), so the tier branch is
-        unreachable for every callable video class.
+        `required_tier`. Since 2026-09-23 (decision 26) no class
+        carries one, so the tier branch is currently unreachable.
       # 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
@@ -12750,7 +13007,9 @@ components:
           description: |
             OPTIONAL, drill-in-only "code for this run" / replay projection — the
             allowlisted, re-submittable shape of the original request (for an SDK
-            snippet / "run it again"). Absent until the API populates it. NOT a
+            snippet / "run it again"). Emitted on every workflow status
+            response by an API that implements the projector; OPTIONAL so a
+            consumer of an older API build tolerates its absence. NOT a
             dump of the persisted option bag; see `CodegenSource`. Per ticket
             `LO0R5gzk`.
 
@@ -12985,8 +13244,9 @@ components:
         EXCLUDES all of that plus runtime results.
 
         **Detail-only** — `WorkflowStatusResponse` only, NEVER `WorkflowSummary`
-        (payload + the list view doesn't need it). OPTIONAL: the projector ships
-        incrementally; the field is absent until the API populates it.
+        (payload + the list view doesn't need it). OPTIONAL in the schema so a
+        consumer of an older API build tolerates its absence; an API that
+        implements the projector emits it on every status response.
 
         **Scope: the reproducible JOB graph only.** Workflow-level request
         fields (`delivery` / `export` / `processing`) are deliberately NOT part
@@ -13397,6 +13657,9 @@ components:
             `never_started` (the operation was terminated without ever running
             because its job reached a terminal state first — an upstream failure
             OR a cancellation; API-derived, never worker-emitted),
+            `processing_limit_exceeded` (a processing tool was killed at a
+            budget set from this input — deterministic, non-retryable; a
+            transient deadline is `timeout`),
             `unknown` (unclassified),
             `out_of_memory` (retryable), `timeout` (retryable),
             `s3_download_failed` (retryable), `s3_upload_failed` (retryable).
@@ -13407,6 +13670,39 @@ components:
             Human-readable failure detail. Present when `status` is `failed`;
             absent otherwise. Mirrors `SseOperationFailedData.error_message`.
           example: "output_too_large: Output (12156489 bytes) is not smaller than input (6187609 bytes)"
+        message_key:
+          $ref: '#/components/schemas/OperationMessageKey'
+        message_params:
+          $ref: '#/components/schemas/OperationMessageParams'
+
+    OperationMessageKey:
+      type: string
+      x-string-vocabulary: open
+      pattern: '^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$'
+      description: |
+        Stable, never-localised key REFINING `error_code` on a failed
+        operation, so a client can show specific, localised copy (e.g.
+        `thumbnail.epub.no_cover`). OPTIONAL, failed only. Every value is
+        declared, with the codes it may accompany and its parameters, in
+        `schemas/operation-message-keys.yaml` (the one registry). Passed
+        through unchanged from the worker's OperationResult. A client
+        that does not know a key, or receives one whose registry
+        `error_codes` do not include this `error_code`, ignores the key and
+        falls back to the `error_code` headline;
+        retry is still decided from the code. Ticket U7GQhjhX.
+      example: "thumbnail.epub.no_cover"
+
+    OperationMessageParams:
+      type: object
+      additionalProperties:
+        type: [string, integer, number, boolean]
+      description: |
+        Interpolation values for `message_key`, named and typed in
+        `schemas/operation-message-keys.yaml`. JSON scalars only (string,
+        integer, number, boolean) — no nested objects. Absent when the key
+        declares no parameters (`params: {}`), and carries exactly the
+        registry's parameters otherwise. Never carries free-text
+        diagnostics; those stay in `error_message`.
 
     OperationResultMetadata:
       type: object
@@ -13418,9 +13714,15 @@ components:
         diagnostics never leak. New keys are **additive named cuts** (the
         `additionalProperties: false` closure is the point — an unmodelled
         key is a coordinated contract change, not a silent rollout). Twin of
-        the AsyncAPI `OperationResultMetadata` (wire ↔ read parity). Distinct
+        the AsyncAPI `OperationResultMetadata` (wire ↔ read parity), except
+        `already_optimal` / `estimated_saving_pct`, which the API projects
+        from the wire `OperationMetrics` where the worker emits them. Distinct
         from `OperationResult` (the deliverable output file): this carries
         small per-operation metadata, not the output. Per `EurbZLMH` (B1).
+      # The estimated_saving_pct => already_optimal:true relation is ENFORCED on
+      # the wire OperationMetrics this is projected from, not here: this schema
+      # also types the workflowCallback webhook payload, where oasdiff reads an
+      # added if/then as a breaking REQUEST change.
       properties:
         watermark_id:
           type: string
@@ -13433,6 +13735,28 @@ components:
             whitelist ship now (additive) so the result_metadata pipeline +
             read projection land without a later contract bump; absent in
             practice until B3 is live.
+        already_optimal:
+          type: boolean
+          description: |
+            `true` when the operation completed by returning the ORIGINAL file
+            unchanged, because compressing it would not have made it smaller
+            (or the source was already efficiently encoded). The operation is
+            a success, not a failure: `result` is the original. Show it as
+            "already optimised", not as "same size". On an ordinary result it
+            is absent or `false`; treat the two the same. Projected by the API from the wire
+            `OperationMetrics.already_optimal` (ticket `roNRMilt`).
+          example: true
+        estimated_saving_pct:
+          type: number
+          minimum: 0
+          maximum: 100
+          description: |
+            OPTIONAL, only with `already_optimal: true`: the worker's ESTIMATE
+            of how much smaller, as a percentage of the input size, a re-encode
+            would have made the file, when it declined before encoding. Absent
+            when no estimate was made. An estimate, not a guarantee. Projected
+            from the wire `OperationMetrics.estimated_saving_pct`.
+          example: 3.5
 
     OperationResult:
       type: object
@@ -13527,6 +13851,7 @@ components:
                 `OperationMetrics.measured_quality`.
             quality_metric:
               type: string
+              x-string-vocabulary: advisory
               description: |
                 The perceptual metric that produced `measured_quality` — a free-form
                 string (not an enum) so it can evolve without contract churn. Present
@@ -13543,6 +13868,7 @@ components:
               $ref: '#/components/schemas/ReEncodeDecision'
             re_encode_reason:
               type: string
+              x-string-vocabulary: advisory
               description: |
                 Advisory explanation for `re_encode_decision` (e.g.
                 `all_inputs_compatible`, `explicit_always_mode`,
@@ -13837,6 +14163,7 @@ components:
             Mirrors `OperationMetrics.measured_quality`.
         quality_metric:
           type: string
+          x-string-vocabulary: advisory
           description: |
             For an `auto_quality` encode: the perceptual metric that produced
             `measured_quality` — a free-form string (not an enum) so it can evolve
@@ -13885,6 +14212,7 @@ components:
           example: "thumb-2x"
         node_id:
           type: string
+          x-string-vocabulary: open
           description: |
             Symbolic composition `node_id` correlating this download to its
             canonical node in `WorkflowCreateResponse.composition_plan` (e.g.
@@ -14268,9 +14596,10 @@ components:
           not: { required: [page_index] }
         - title: Unindexed
           description: |
-            Output without an explicit indexing field. Reserved for future
-            operations that index by something other than page/position.
-            Schema-valid but not currently emitted by any operation.
+            Output without a page/position indexing field. Covers legacy
+            single-output entries AND `render_variants` variant outputs (still
+            `planned`, so not reachable through the API until that operation
+            is). Mirrors the AsyncAPI `OperationResultOutputEntry` branch.
           not:
             anyOf:
               - required: [page_index]
@@ -14346,6 +14675,10 @@ components:
             generic reason.
         error_message:
           type: string
+        message_key:
+          $ref: '#/components/schemas/OperationMessageKey'
+        message_params:
+          $ref: '#/components/schemas/OperationMessageParams'
 
     SseJobCompletedData:
       type: object
@@ -14406,6 +14739,7 @@ components:
             - partially_failed
         reason:
           type: string
+          x-string-vocabulary: advisory
           description: |
             Optional advisory reason for the terminal state. Free-form
             string; not an enum. Examples: "all jobs completed
@@ -15244,10 +15578,9 @@ components:
           description: |
             Operation-level availability tag. Optional — when absent, the
             operation is treated as `stable` (parser obligation per
-            ADR-0001 §1.4 / FORMAT.md §Availability Taxonomy). Runtime
-            emission lands with [I3 `eCWIpug8`](https://trello.com/c/eCWIpug8);
-            until then the contract declares the shape but the endpoint
-            does not yet surface the field.
+            ADR-0001 §1.4 / FORMAT.md §Availability Taxonomy). Echoed by
+            `GET /api/operations/schema` whenever the operation schema
+            declares it ([I3 `eCWIpug8`](https://trello.com/c/eCWIpug8)).
         required_tier:
           $ref: '#/components/schemas/UserTier'
           description: |
@@ -15410,7 +15743,7 @@ 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**, and
+            `max_output_pixels` (declared below). **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
@@ -15433,6 +15766,33 @@ components:
             `processing_class.<class>.constraints.max_input_size_bytes` instead —
             never both, so the input ceiling lives in exactly one place per group.
             CI-enforced by `scripts/check-per-tier-constraints.py`.
+        max_output_pixels:
+          type: integer
+          format: int64
+          minimum: 1
+          description: |
+            Optional mime-group-level OUTPUT area cap: a request is valid on
+            this axis iff `width × height <= max_output_pixels`, read from the
+            two option values. Declared here since 2026-09-23 (`gACSVjiK`): it
+            was named as a "sibling" of `max_input_size_bytes` while existing
+            only in the operation schemas and the availability sidecar, and a
+            consumer diffing the served schema reported it as a missing key.
+            ⚠️ **Optional, and not yet round-tripped by `GET
+            /api/operations/schema`** — the operation schemas under `schemas/`
+            and `availability/availability.json` carry it today. See
+            `schemas/FORMAT.md` §`max_output_pixels`.
+        input_size_bound:
+          type: string
+          enum: [processing_time]
+          x-enum-openness: closed
+          description: |
+            Declares that the group has **no byte ceiling on purpose**: the
+            worker is bounded by processing time instead. XOR with
+            `max_input_size_bytes` — exactly one is present when either is, so
+            an absent pair means "nothing declared", never "unlimited".
+            Declared here since 2026-09-23 (`gACSVjiK`) for the same reason as
+            `max_output_pixels`, with the same round-trip caveat. See
+            `schemas/FORMAT.md` §`input_size_bound`.
         max_input_duration:
           type: string
           description: |
@@ -15609,6 +15969,7 @@ components:
           description: Maximum value (for integer/float types)
         pattern:
           type: string
+          x-string-vocabulary: none
           description: |
             ECMA-262 regular expression a `type: string` value MUST match
             (the string analogue of `min`/`max`). Consumers pre-validate
@@ -15619,6 +15980,29 @@ components:
             `#RRGGBB`; a CSS named colour was silently dropped to white). Only
             meaningful for `type: string`. See `schemas/FORMAT.md`.
           example: "^#[0-9a-fA-F]{6}$"
+        items:
+          type: object
+          additionalProperties: true
+          description: |
+            `type: array` only. A JSON Schema 2020-12 OBJECT subschema every
+            element must satisfy (boolean schemas are not used in this DSL;
+            e.g. `{type: number, exclusiveMinimum: 0}` for
+            `split.cut_points`, or an object shape for
+            `image_watermark.overlays`). Named in JSON Schema's own camelCase,
+            like `pattern`, because these ARE JSON Schema keywords and the
+            published operation schemas already use them (fzrEO6GN).
+        minItems:
+          type: integer
+          minimum: 0
+          description: "`type: array` only. Fewest elements allowed."
+        maxItems:
+          type: integer
+          minimum: 0
+          description: "`type: array` only. Most elements allowed."
+        uniqueItems:
+          type: boolean
+          description: |
+            `type: array` only. `true`: elements must be pairwise distinct.
         depends_on:
           type: object
           description: |
@@ -15810,15 +16194,22 @@ components:
     NotifyConfig:
       type: object
       x-availability: planned
+      # CLOSED to the declared channels: the API refuses an undeclared channel
+      # key as validation_error, so the schema says so too (codex, #568).
+      additionalProperties: false
       description: |
         Channel-agnostic per-job completion-notification config (ticket
         [`IQtEwVET`](https://trello.com/c/IQtEwVET)). Currently the `email`
         channel only; `webhook` folds onto the same dispatch engine later
         (today webhook is configured via the top-level `callback_url` /
         `callback_events`). **Advertised-ahead** — the API returns
-        `feature_not_available` (422) for any `notify` use until the
-        dispatch engine ships. `x-availability` is decorative per
-        ADR-0001 §1.5; the API is the authority on the 422 gate.
+        `feature_not_available` (422) for any use of a declared channel
+        until the dispatch engine ships, with feature path
+        `workflow.notify.<channel>` (today `workflow.notify.email`), the
+        same dotted grammar as `workflow.request.flat_form`. An undeclared
+        channel key is a `validation_error` (422). `x-availability` is
+        decorative per ADR-0001 §1.5; the API is the authority on the 422
+        gate.
 
         An **empty `notify`** (object present but no channel set) is a
         no-op — the workflow runs normally with no notifications; it is