@giveitsmaller/contracts 0.73.0 → 0.78.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.213.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:
@@ -1740,17 +1782,32 @@ paths:
               more operations / mime_groups / options gated by a higher
               subscription tier than the caller has. Each violation is
               listed in `violations[]` with `required_tier` populated.
+            - `anonymous_operation_not_allowed`: an ANONYMOUS caller (no
+              credential) requested an operation outside the anonymous
+              allow-list. `operation` names the first such operation.
+              A register-wall: signing in is the remedy, not upgrading.
+            - `anonymous_quota_exhausted`: an anonymous caller has used
+              its per-IP workflow allowance for the rolling 24 hours.
+              Also a register-wall.
+
+            Both anonymous walls are checked BEFORE the workflow is
+            built, and neither consumes the caller's anonymous
+            allowance. An authenticated caller never receives either.
           content:
             application/json:
               schema:
                 oneOf:
                   - $ref: '#/components/schemas/TierRestrictionResponse'
                   - $ref: '#/components/schemas/FeatureTierRestrictedResponse'
+                  - $ref: '#/components/schemas/AnonymousOperationNotAllowedResponse'
+                  - $ref: '#/components/schemas/AnonymousQuotaExhaustedResponse'
                 discriminator:
                   propertyName: error_type
                   mapping:
                     tier_restriction: '#/components/schemas/TierRestrictionResponse'
                     feature_tier_restricted: '#/components/schemas/FeatureTierRestrictedResponse'
+                    anonymous_operation_not_allowed: '#/components/schemas/AnonymousOperationNotAllowedResponse'
+                    anonymous_quota_exhausted: '#/components/schemas/AnonymousQuotaExhaustedResponse'
               examples:
                 feature_tier_restricted:
                   summary: Free tier referencing a Pro-tier operation
@@ -1763,6 +1820,25 @@ paths:
                         availability: "stable"
                         required_tier: "pro"
                         documentation_url: "https://docs.giveitsmaller.com/operations/image_watermark"
+                anonymous_operation_not_allowed:
+                  summary: Anonymous caller requesting an operation outside the allow-list
+                  value:
+                    success: false
+                    error: "ANONYMOUS_OPERATION_NOT_ALLOWED"
+                    error_type: "anonymous_operation_not_allowed"
+                    message: "Sign up to use the 'text_watermark' operation."
+                    message_key: "error.anonymous_operation_not_allowed"
+                    locale: "en-GB"
+                    operation: "text_watermark"
+                anonymous_quota_exhausted:
+                  summary: Anonymous caller past its rolling-24h allowance
+                  value:
+                    success: false
+                    error: "ANONYMOUS_QUOTA_EXHAUSTED"
+                    error_type: "anonymous_quota_exhausted"
+                    message: "Sign up to keep compressing."
+                    message_key: "error.anonymous_quota_exhausted"
+                    locale: "en-GB"
         '402':
           description: |
             Credit reservation failed (per ticket
@@ -1897,6 +1973,37 @@ paths:
               Caller resolves by switching to `re_encode_mode: auto`
               or `always`. The compatibility-probe algorithm is
               server-side and deliberately opaque per plan v5 §F8.2.
+            - Inputs not concat-uniform (ticket `MjzzPCWt`). Returned for a
+              job that routes to a processing class declaring
+              `input_uniformity` (today `merge.video.long_form_re_encode`)
+              when its inputs differ in stream layout or in a listed
+              attribute. `ValidationErrorEnvelope` with `error:
+              "INPUTS_NOT_CONCAT_UNIFORM"`; `details[]` entries are shaped
+              `{operation: "merge", field: "inputs[i].<attribute> vs
+              inputs[j].<attribute>", message: "..."}`, one per difference.
+              **Coverage rule:** the API refuses every difference its upload
+              probe can see WITH THE WORKER GATE'S SEMANTICS (audio present
+              on one input and not another; video codec, resolution; audio
+              codec, layout, channels, sample rate). NOT frame rate: the
+              probe's `fps` is the AVERAGE rate, which legitimately drifts
+              between concat-uniform clips, while the worker compares
+              `r_frame_rate`, so comparing `fps` would refuse valid merges.
+              Differences the probe does not carry with the worker's
+              semantics yet (frame rate as `r_frame_rate`, stream counts
+              beyond one video / one audio, stream order, pix_fmt, SAR,
+              timebase, codec_tag, profile, sample_fmt) are
+              refused by the worker after acceptance until the upload prober
+              emits them; the probe schema declares them
+              (`UploadProbeMediaMetadata`, card `lGeDDi4V`), and once a probe
+              carries one, the API refuses that difference at create too. **An input whose probe has not
+              completed is ADMITTED**, and the worker gate is its only
+              check, the same as **an input that is an upstream job's
+              output** (which has no upload probe). It does NOT get the
+              `probe_pending` branch: a probe that never lands cannot be
+              told apart from one still running, so refusing until it
+              lands could make a create that never succeeds (ruled
+              2026-09-24 on api's `nmYdwHAH`, matching api's disabled
+              single-operation probe gate).
 
             **Branch dispatch via the `error_type` discriminator** (per
             [ADR-0018](../docs/decisions/0018-universal-422-error-type-discriminator.md)).
@@ -1905,7 +2012,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 +2067,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:
@@ -2044,6 +2151,16 @@ paths:
                         actual: 54000
                         ceiling: 43200
                         required_tier: "enterprise"
+                inputs_not_concat_uniform:
+                  summary: merge.video long_form_re_encode with one input lacking audio (MjzzPCWt)
+                  value:
+                    success: false
+                    error_type: "validation_error"
+                    error: "INPUTS_NOT_CONCAT_UNIFORM"
+                    details:
+                      - operation: "merge"
+                        field: "inputs[0].audio vs inputs[1].audio"
+                        message: "Input 1 has no audio track and input 0 has one; long-form merge needs every input to share the same streams."
                 requires_reencode:
                   summary: merge.video re_encode_mode=never with incompatible inputs (I16-CONS)
                   value:
@@ -3033,10 +3150,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 +3189,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 +3199,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 +3213,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 +3225,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 +3294,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
@@ -3249,7 +3398,9 @@ paths:
         Per ticket [I24 `e50uXLcl`](https://trello.com/c/e50uXLcl).
 
         Resume succeeds only when the caller's `available_credits`
-        cover the next reservation the server would attempt. If the
+        cover the reservation the server re-takes for the workflow's
+        remaining work (the same estimate `WorkflowPausedDetail`'s
+        `required_action: resume` is computed from). If the
         balance is still insufficient, the response is 402
         `BalanceExhaustedResponse` (mirroring the workflow-create
         flow per ticket I23) and the workflow remains
@@ -5053,6 +5204,33 @@ paths:
                           type: object
                       billing:
                         type: object
+                        properties:
+                          checkout_sessions:
+                            type: array
+                            description: |
+                              Every checkout session the account started that
+                              the API recorded (ticket `JHrV4MUg`). Sessions
+                              created before that record existed are absent.
+                            items:
+                              type: object
+                              required: [session_id, mode, created_at, fulfilled_at]
+                              properties:
+                                session_id:
+                                  type: string
+                                mode:
+                                  type: string
+                                  description: The checkout mode (`payment` for a credit pack, `subscription`).
+                                  # OPEN: the provider's checkout mode, recorded as created; a
+                                  # new mode is informational in an export, not a decision input.
+                                  x-enum-openness: open
+                                  enum: [payment, subscription]
+                                created_at:
+                                  type: string
+                                  format: date-time
+                                fulfilled_at:
+                                  type: ['string', 'null']
+                                  format: date-time
+                                  description: When the purchase was applied; `null` while it has not been.
         '401':
           description: No authenticated principal.
           content:
@@ -5824,9 +6002,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 +6028,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 +6051,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 +6212,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 +6286,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 +6301,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 +6318,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 +6328,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 +6469,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 +6543,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 +6705,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
@@ -6561,20 +6731,24 @@ paths:
             headers.
           headers:
             X-RateLimit-Limit:
-              required: false
+              required: true
               description: Requests permitted in the current window.
               schema:
                 type: integer
                 minimum: 0
             X-RateLimit-Remaining:
-              required: false
+              required: true
               description: Requests remaining in the current window.
               schema:
                 type: integer
                 minimum: 0
             X-RateLimit-Reset:
-              required: false
-              description: Unix epoch seconds when the current window resets.
+              required: true
+              description: |
+                SECONDS UNTIL the current window resets (a delay, not a
+                timestamp). This said "Unix epoch seconds" until 2026-09-25;
+                api has always sent the delay, and both SDKs parse it as one
+                (card `KqPDtD9J`).
               schema:
                 type: integer
                 minimum: 0
@@ -6601,6 +6775,160 @@ 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 still linked to the caller's billing account (see below) |
+        | `pending` | the session is recorded as created BY THE CALLER and its purchase has not been applied yet — **not a failure** |
+        | `unknown` | anything else, including a session created before this endpoint shipped (nothing recorded it) |
+
+        **Subscription `paid` means LINKED, not IN GOOD STANDING** (ruled
+        2026-09-25 on api's `JHrV4MUg`). It holds while the subscription the
+        session started is still linked to the caller's billing account; a
+        `past_due` or `incomplete` subscription that is still linked reads
+        `paid`. It becomes `unknown` once the provider reports the
+        subscription deleted. A stricter meaning needs the subscription's
+        status recorded, which the API does not do today.
+
+        🔴 **`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, for any session id the router
+            accepts** — `unknown` is the answer for anything not provably the
+            caller's (see the collapse rationale above). An id the router
+            cannot route (for example invalid UTF-8 such as `cs_%FF`) is a
+            `404` before this endpoint runs; that answer is the same for
+            every caller and every session, so it reveals nothing. 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'
+        '404':
+          description: |
+            The ROUTER could not route the path (for example a session id
+            with invalid UTF-8). Returned before this endpoint runs, the same
+            for every caller and every session id, so it says nothing about
+            any session.
+          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'
+        '429':
+          description: |
+            Rate limit exceeded. This endpoint is limited as a STATUS POLL
+            (the same family as the other polling reads), independently of
+            `POST /api/billing/checkout`, so polling a pending session never
+            spends the caller's checkout-creation budget. `error:
+            TOO_MANY_REQUESTS`. No `Retry-After`; back off by
+            `X-RateLimit-Reset`.
+          headers:
+            X-RateLimit-Limit:
+              required: true
+              description: Requests permitted in the most constrained window.
+              schema:
+                type: integer
+                minimum: 0
+            X-RateLimit-Remaining:
+              required: true
+              description: Requests remaining in that window.
+              schema:
+                type: integer
+                minimum: 0
+            X-RateLimit-Reset:
+              required: true
+              description: |
+                SECONDS UNTIL that window resets (a delay, not a
+                timestamp) — what api's limiter sends
+                (`TieredRateLimiterService`: retry-after timestamp minus now).
+              schema:
+                type: integer
+                minimum: 0
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+
   # ============================================
   # CONTACT ENDPOINT
   # ============================================
@@ -6828,12 +7156,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 +7292,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 +7425,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 /
@@ -7118,12 +7469,23 @@ components:
     ReEncodeDecision:
       type: string
       description: |
-        Path chosen for `merge.video` when `re_encode_mode=auto`.
-        Server reports the actual path so callers can see why
-        `auto` took the slow path. Absent for non-`merge.video`
-        operations and for `merge.video` when `re_encode_mode` is
-        `always` or `never` (path was caller-fixed). Per ticket
-        I16-CONS (Trello 7nCZXEru).
+        Path the worker actually took for a SUCCESSFUL `merge.video`,
+        reported in EVERY `re_encode_mode`: `always` reports `re_encode`;
+        `never` reports `stream_copy`; `auto` reports whichever path it
+        chose. Absent for non-`merge.video` operations and on any failed
+        operation, even one that carries other metrics such as sizes or
+        cost figures (for example a `never`
+        request whose inputs need a re-encode, or a long-form merge the
+        uniformity gate refuses before the path is decided). Per ticket I16-CONS (Trello
+        7nCZXEru).
+
+        ⚠️ An earlier revision said the field was ABSENT under `always` /
+        `never`. The worker never behaved that way (it reports the path
+        in every mode), and the same contract listed an `always`-mode
+        reason as an example, so the text contradicted itself. The
+        worker's behaviour is the canonical one (ruled 2026-09-24 on
+        compression_e2e's report); a consumer MUST NOT assert absence
+        on a successful merge under a caller-fixed mode.
 
         Mirrors the AsyncAPI `ReEncodeDecision` (and
         `OperationMetrics.re_encode_decision`); exposed on the REST
@@ -7987,6 +8349,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 +8435,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 +8512,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 +8544,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 +8617,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 +8631,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 +8698,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 +9010,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
@@ -8791,15 +9217,28 @@ components:
 
     WorkflowPauseRequiredAction:
       type: string
+      x-enum-openness: open
       description: |
-        Action the caller must take to resume a paused workflow.
-        Same enum as `BalanceExhaustedResponse.required_action` —
-        the pause cause is always insufficient credits, so the
-        resolution affordances align.
+        Action the caller must take to resume a paused workflow. The
+        first three match `BalanceExhaustedResponse.required_action`.
+        `resume` (ticket `xNatWWpO`, api #747): the account can afford
+        the resume NOW, so the only action is to resume: call the
+        `resumeWorkflow` operation (`POST /api/workflows/{id}/resume`).
+        `links.resume`, when present, is a UI deep link, not the API
+        call. The
+        API emits it when the balance, plus this month's pending grant
+        for the base tier, covers the same cost estimate the resume
+        handler reserves — so `/status` and resume agree. A UI must not
+        offer a top-up, upgrade or pack for it.
+        **Open enum:** handle an unknown value as the generic case.
+        ⚠️ Rollout order, because a strict SDK deserialiser throws on an
+        unknown value: SDKs tolerate unknown values and are published
+        first, and only then does the API emit `resume`.
       enum:
         - add_credits
         - upgrade_plan
         - wait_for_renewal
+        - resume
 
     # ============================================
     # WORKFLOW ADVISORY WARNINGS (per ticket I25)
@@ -8950,9 +9389,10 @@ components:
 
         SDK + frontend gate UI on `required_action` to render the
         appropriate "Top up to resume" / "Upgrade plan to resume" /
-        "Wait for renewal" affordance, with `links.resume` enabling
-        a one-click POST to `/api/workflows/{id}/resume` once the
-        balance is sufficient.
+        "Wait for renewal" affordance — or, for `resume`, only the
+        resume action. The resume itself is the `resumeWorkflow`
+        operation (`POST /api/workflows/{id}/resume`); `links.resume` is
+        the frontend page where a user can do it, not that API call.
       required:
         - paused_at
         - expires_at
@@ -9000,9 +9440,11 @@ components:
               type: string
               format: uri
               description: |
-                Deep link to the resume action — typically
-                `POST /api/workflows/{id}/resume` exposed via the
-                frontend's "resume" UI.
+                URL of the frontend page for this workflow (e.g.
+                `{frontend}/{locale}/profile/workflows/{id}`), where the
+                user can resume it. **NOT the API call:** a client resumes
+                with the `resumeWorkflow` operation
+                (`POST /api/workflows/{id}/resume`).
             top_up:
               type: string
               format: uri
@@ -9263,6 +9705,67 @@ components:
     # FEATURE AVAILABILITY ENVELOPES
     # ============================================
 
+    AnonymousOperationNotAllowedResponse:
+      description: |
+        403 from `POST /api/workflows` when an ANONYMOUS caller (no
+        credential) requests an operation outside the anonymous
+        allow-list. A register-wall: the frontend renders a sign-up
+        prompt, since no tier upgrade applies to a caller without an
+        account.
+
+        Mirrors `compression_api`'s `WorkflowController` register-wall
+        (`JobsErrorCode::AnonymousOperationNotAllowed`), which checks
+        every operation in the body and names the FIRST disallowed one.
+
+        ⚠️ **The allow-list itself is NOT yet declared in this contract**
+        (ticket [`UQ7zROTr`](https://trello.com/c/UQ7zROTr)), so a client
+        can parse this refusal but cannot yet predict it. Do not hard-code
+        the list from this description: it deliberately names none.
+      allOf:
+        - $ref: '#/components/schemas/ErrorEnvelope'
+        - type: object
+          required:
+            - error_type
+            - operation
+          properties:
+            error:
+              enum:
+                - ANONYMOUS_OPERATION_NOT_ALLOWED
+            error_type:
+              description: Discriminator for the 403 oneOf. Always `anonymous_operation_not_allowed` for this envelope.
+              type: string
+              enum:
+                - anonymous_operation_not_allowed
+            operation:
+              description: |
+                The first operation in the request body that an anonymous
+                caller may not run.
+              $ref: '#/components/schemas/OperationType'
+    AnonymousQuotaExhaustedResponse:
+      description: |
+        403 from `POST /api/workflows` when an ANONYMOUS caller (no
+        credential) has used its per-IP workflow allowance for the
+        rolling 24 hours. A register-wall, distinct from the generic
+        `429`: the remedy is signing in, not waiting.
+
+        Mirrors `compression_api`'s `WorkflowController` register-wall
+        (`JobsErrorCode::AnonymousQuotaExhausted`). The allowance is only
+        consumed by a workflow that is actually created, so a refused
+        request does not use it up.
+      allOf:
+        - $ref: '#/components/schemas/ErrorEnvelope'
+        - type: object
+          required:
+            - error_type
+          properties:
+            error:
+              enum:
+                - ANONYMOUS_QUOTA_EXHAUSTED
+            error_type:
+              description: Discriminator for the 403 oneOf. Always `anonymous_quota_exhausted` for this envelope.
+              type: string
+              enum:
+                - anonymous_quota_exhausted
     FeatureViolation:
       type: object
       description: |
@@ -9506,6 +10009,13 @@ components:
           description: |
             The class whose ceiling was exceeded — typically `long_form`
             or `long_form_re_encode`.
+        resolution_band:
+          $ref: '#/components/schemas/ResolutionBand'
+          description: |
+            The band whose ceiling `ceiling` is, when the class declares
+            `resolution_bands`; omitted otherwise. `unknown` means the
+            resolution could not be determined — a different customer
+            action from a known-resolution overflow.
         actual:
           type: integer
           minimum: 0
@@ -9759,9 +10269,14 @@ components:
         - `failed`: All jobs finished, at least one failed, none succeeded.
         - `partially_failed`: Some jobs succeeded, some failed.
         - `paused_insufficient_credits`: Workflow paused at a job/
-          stage boundary because the next reservation exceeded the
-          caller's available credits. Pause occurs at boundaries
-          only — never mid-stream within a running operation.
+          stage boundary because it no longer holds a credit
+          reservation. The API reserves the FULL estimated cost at
+          create (a 402 there if the balance is short), so a normal run
+          never pauses; this is a defence for a workflow whose
+          reservation was released mid-flight (e.g. by an orphan
+          clean-up). There is no per-stage reservation (ticket
+          `mNA2uv3y`). Pause occurs at boundaries only — never
+          mid-stream within a running operation.
           Resumable via `POST /api/workflows/{id}/resume` once the
           caller tops up; expires after a 7-day TTL by default.
         - `cancelled`: Caller-initiated termination via
@@ -9837,6 +10352,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 +10383,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 +11275,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 +11433,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 +11980,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 +12272,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
@@ -11769,6 +12289,15 @@ components:
           $ref: '#/components/schemas/EstimateQuality'
         reason:
           $ref: '#/components/schemas/ProcessingClassReason'
+        resolution_band:
+          $ref: '#/components/schemas/ResolutionBand'
+          description: |
+            The resolution band whose ceiling the class decision was taken
+            against, when the operation's classes declare
+            `resolution_bands`; omitted otherwise. `unknown` says the
+            resolution could not be determined, so `reason` (which names the
+            AXIS, e.g. `input_duration_exceeds_short_form`) was judged against
+            the `unknown` band's ceiling.
         dropped_options:
           type: array
           description: |
@@ -12016,6 +12545,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 +12568,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 +12697,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
@@ -12307,6 +12836,84 @@ components:
             contract on the OpenAPI side; the prober reports the
             page-1 horizontal DPI when the document declares it,
             otherwise omits the field.
+        # STREAM TOPOLOGY + CONCAT ATTRIBUTES (lGeDDi4V, for MjzzPCWt): what the
+        # API needs to refuse a non-concat-uniform long-form merge at create.
+        # Defined with the SAME semantics as compression_lambdas' merge gate
+        # (re_encode.rs TopologyCounts / classify_non_uniform), or the
+        # create-time refusal and the worker gate would disagree. All OPTIONAL:
+        # a prober that has not emitted them yet simply omits them.
+        video_stream_count:
+          type: integer
+          minimum: 0
+          description: Streams whose ffprobe `codec_type` is `video`.
+        audio_stream_count:
+          type: integer
+          minimum: 0
+          description: Streams whose ffprobe `codec_type` is `audio`.
+        other_stream_count:
+          type: integer
+          minimum: 0
+          description: |
+            Every other stream: `codec_type` subtitle, data, attachment,
+            or unknown — the worker gate's `other` bucket.
+        stream_order:
+          type: array
+          items:
+            type: string
+            enum: [video, audio, other]
+          description: |
+            Per stream index, in container order, its kind (`other` as
+            above). Two inputs are order-compatible iff these are equal.
+        r_frame_rate:
+          type: string
+          pattern: '^[0-9]+/[0-9]+$'
+          description: |
+            ffprobe `r_frame_rate` of the video stream, raw (`30000/1001`;
+            ffprobe's `0/0` is carried as-is and means UNUSABLE). NOT the
+            average rate in `fps`, which drifts between concat-uniform
+            clips. **The worker's frame-rate rule, which a create-time
+            comparison must reproduce exactly:** (1) `r_frame_rate` and
+            `avg_frame_rate` must each be present on all inputs or absent
+            on all (else `input_metadata_inconsistent`); (2) if every
+            input has a usable `r_frame_rate`, compare those as parsed
+            rationals; (3) otherwise compare `avg_frame_rate` as parsed
+            rationals. Both comparisons are by VALUE (`60/2` equals `30/1`),
+            never by string.
+        avg_frame_rate:
+          type: string
+          pattern: '^[0-9]+/[0-9]+$'
+          description: |
+            ffprobe `avg_frame_rate` of the video stream, raw rational.
+            Presence-checked always; compared only as the fallback in the
+            `r_frame_rate` rule. `fps` is its lossy numeric form.
+        pix_fmt:
+          type: string
+          x-string-vocabulary: none
+          description: ffprobe `pix_fmt` of the video stream (e.g. `yuv420p`).
+        sar:
+          type: string
+          pattern: '^[0-9]+:[0-9]+$'
+          description: Sample aspect ratio of the video stream (`1:1`).
+        video_time_base:
+          type: string
+          pattern: '^[0-9]+/[0-9]+$'
+          description: ffprobe `time_base` of the video stream (`1/30000`).
+        audio_time_base:
+          type: string
+          pattern: '^[0-9]+/[0-9]+$'
+          description: ffprobe `time_base` of the audio stream (`1/48000`).
+        codec_tag:
+          type: string
+          x-string-vocabulary: none
+          description: ffprobe `codec_tag_string` of the video stream (e.g. `avc1`).
+        profile:
+          type: string
+          x-string-vocabulary: none
+          description: ffprobe `profile` of the video stream (e.g. `High`).
+        sample_fmt:
+          type: string
+          x-string-vocabulary: none
+          description: ffprobe `sample_fmt` of the audio stream (e.g. `fltp`).
         probed_at:
           type: string
           format: date-time
@@ -12750,7 +13357,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 +13594,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 +14007,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 +14020,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 +14064,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 +14085,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 +14201,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,10 +14218,11 @@ 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`,
-                `input_codec_mismatch`, `input_framerate_mismatch`).
+                `compatible_inputs`, `always_mode_forces_re_encode`,
+                `input_video_codec_mismatch`, `long_form_stream_copy`).
                 Free-form string — not an enum — so the Lambda can emit
                 human-readable diagnostics that evolve without contract
                 changes. Mirrors `OperationMetrics.re_encode_reason`.
@@ -13837,6 +14513,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
@@ -13857,6 +14534,10 @@ components:
             is gapless ONLY for a full conversion, not for a sparse selection.
             NOT the download `filename` suffix (that is a 0-based array
             position — see `OperationDownload.filename`). Mutually exclusive with `position`.
+            For a `split` of a PDF with `mode: page_groups`, each output holds
+            a GROUP of pages and `page_index` is the group's FIRST source
+            page; the group covers `page_index` .. `page_index + page_groups
+            - 1`, and the last group ends at the document's last page.
             Normative semantics: ADR-0009 §D2.
             Absent on non-indexed (single-output) downloads. Mirrors
             `OperationResultOutputEntry.page_index`. Per ADR-0009 §D2.
@@ -13885,6 +14566,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 +14950,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]
@@ -14300,6 +14983,10 @@ components:
             is gapless ONLY for a full conversion, not for a sparse selection.
             NOT the download `filename` suffix (that is a 0-based array
             position — see `OperationDownload.filename`). Mutually exclusive with `position`.
+            For a `split` of a PDF with `mode: page_groups`, each output holds
+            a GROUP of pages and `page_index` is the group's FIRST source
+            page; the group covers `page_index` .. `page_index + page_groups
+            - 1`, and the last group ends at the document's last page.
             Normative semantics: ADR-0009 §D2.
             Absent on non-indexed outputs. Mirrors
             `OperationResultOutputEntry.page_index`. Per ADR-0009 §D2.
@@ -14346,6 +15033,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 +15097,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 +15936,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 +16101,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 +16124,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 +16327,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 +16338,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: |
@@ -15641,7 +16383,10 @@ components:
             on the optimiser path (e.g. JPEG `progressive`); `[format_change]`
             only on the transcoder path (e.g. `background` alpha-flatten to JPEG).
             ABSENT ≡ honored on every route the option's `depends_on` already
-            admits (back-compat — existing options need no tag). Orthogonal to
+            admits (back-compat — existing options need no tag). An EMPTY
+            list `[]` ≡ ACCEPTED BUT INERT: the option is still accepted on
+            the wire but no route honours it, so it is never visible and
+            never in `honored_options` (card `Nqd3TdC6`). Orthogonal to
             `availability`: a `planned` option still declares the route it WILL
             be honoured on. Consumers derive option visibility from
             `honored_on` ∩ active-route ∩ (availability != planned) ∩ depends_on.
@@ -15735,6 +16480,69 @@ components:
             Baseline caps for the lowest tier this class's
             `required_tier` permits. Overlaid per-caller by
             `per_tier_constraints` (see below).
+        input_uniformity:
+          type: object
+          additionalProperties: false
+          description: |
+            Present on a class that CONCATENATES inputs without normalising
+            them (today `merge.video.long_form_re_encode`, ticket `MjzzPCWt`):
+            every input must share its stream layout (`structural`, a
+            permanent requirement) and its stream attributes (`attributes`,
+            until the heterogeneous re-encode ships). The names are the
+            worker gate's reason vocabulary. A request that breaks it is
+            refused at create with the `refusal` code where the API's upload
+            probe can see the difference; the worker gate refuses the rest.
+          required: [refusal, structural, attributes]
+          properties:
+            refusal:
+              type: string
+              enum: [INPUTS_NOT_CONCAT_UNIFORM]
+              description: The `ErrorEnvelope.error` code of the create-time refusal.
+            structural:
+              type: array
+              items: {type: string}
+              description: Permanent stream-layout requirements (worker gate reason names).
+            attributes:
+              type: object
+              additionalProperties:
+                type: array
+                items: {type: string}
+              description: |
+                Per stream kind (`video`, `audio`), the attributes every input
+                must share until the heterogeneous re-encode ships; plus
+                `field_presence`: a video/audio stream field present on one
+                input and absent on another.
+        resolution_bands:
+          type: object
+          description: |
+            Optional per-resolution ceilings for this class (ticket
+            [`GxQPL4IY`](https://trello.com/c/GxQPL4IY)). Keys are EVERY
+            `ResolutionBand` value — each band in
+            `schemas/resolution-bands.yaml` plus `unknown` — so when the
+            block is present a consumer never has to invent a ceiling.
+            An input is placed in a band by its probe's frame pixels
+            (width x height); `unknown` applies when the probe has no
+            width or height. A band only TIGHTENS `constraints` (after
+            the `per_tier_constraints` overlay): the effective ceiling on
+            an axis is the smaller of the two, and an axis the band omits
+            falls through to the class. An input over its band's ceiling
+            exceeds this class, exactly as one over `constraints` does.
+            Absent = no resolution axis; `constraints` binds at every
+            resolution. CI-checked by `scripts/check-resolution-bands.py`.
+            See `schemas/FORMAT.md` §`resolution_bands`.
+          # Every band is REQUIRED: a consumer must never invent a ceiling. The
+          # property names are the `ResolutionBand` enum, held equal by a test.
+          additionalProperties: false
+          required: [le_720p, p1080, gt_1080p, unknown]
+          properties:
+            le_720p:
+              $ref: '#/components/schemas/ResolutionBandCeiling'
+            p1080:
+              $ref: '#/components/schemas/ResolutionBandCeiling'
+            gt_1080p:
+              $ref: '#/components/schemas/ResolutionBandCeiling'
+            unknown:
+              $ref: '#/components/schemas/ResolutionBandCeiling'
         per_tier_constraints:
           type: object
           description: |
@@ -15753,6 +16561,108 @@ components:
           additionalProperties:
             $ref: '#/components/schemas/ProcessingClassConstraints'
 
+    ResolutionBand:
+      type: string
+      description: |
+        A resolution band (ticket [`GxQPL4IY`](https://trello.com/c/GxQPL4IY)).
+        The band names and their frame-pixel bounds are declared ONCE in
+        `schemas/resolution-bands.yaml`; this enum is those names plus the
+        `unknown` band, held equal by a test.
+
+        - `le_720p`, `p1080`, `gt_1080p`: ascending frame-pixel bands
+          (width x height). Their bounds are `max_frame_pixels` in
+          `schemas/resolution-bands.yaml` and are deliberately not
+          restated here.
+        - `unknown`: the upload probe reported no width or no height, so the
+          resolution could not be determined. A refusal or escalation under
+          this band means "we could not tell this file's resolution", which
+          calls for a different action (re-upload, wait for the probe,
+          contact us) than "your file is too long".
+
+        Pixels, not height: a portrait clip lands in the same band as its
+        landscape twin.
+      # CLOSED. The band a consumer computes decides which ceiling it enforces;
+      # an unrecognised band cannot be mapped to a ceiling safely in either
+      # direction, so a new band is a contract event consumers must learn.
+      x-enum-openness: closed
+      enum:
+        - le_720p
+        - p1080
+        - gt_1080p
+        - unknown
+
+    ResolutionBandCeiling:
+      type: object
+      additionalProperties: false
+      description: |
+        One band's ceiling within `ProcessingClassEntry.resolution_bands`.
+        `basis` is REQUIRED so no consumer inherits a default for a band
+        nobody measured. `not_served` carries neither `constraints` nor
+        `derivation`; `measured` carries both; `ruled` carries
+        `constraints` only.
+      required:
+        - basis
+      allOf:
+        - if:
+            properties: {basis: {const: not_served}}
+          then:
+            not:
+              anyOf:
+                - required: [constraints]
+                - required: [derivation]
+          else:
+            required: [constraints]
+        - if:
+            properties: {basis: {const: measured}}
+          then:
+            required: [derivation]
+          else:
+            not:
+              required: [derivation]
+      properties:
+        basis:
+          type: string
+          description: |
+            - `measured`: the ceiling is derived from measured encode time;
+              `derivation` carries the line it was solved from.
+            - `ruled`: a policy value, not a measurement (today: the
+              `unknown` band, which takes the `le_720p` ceiling).
+            - `not_served`: this class does not serve inputs in this band.
+              No `constraints`; an input in this band exceeds the class
+              (for `short_form`: it escalates to `long_form`, or is refused
+              where `long_form` is not available).
+          # CLOSED: each value changes what a consumer enforces.
+          x-enum-openness: closed
+          enum: [measured, ruled, not_served]
+        constraints:
+          type: object
+          additionalProperties: false
+          description: Present unless `basis` is `not_served`.
+          minProperties: 1
+          properties:
+            max_input_duration:
+              type: string
+              description: ISO-8601 duration; the band's input duration ceiling.
+              example: "PT4M35S"
+        derivation:
+          type: object
+          additionalProperties: false
+          description: |
+            Present only when `basis` is `measured`. Encode time was measured
+            as a line, `slope_s_per_s x duration + intercept_s`; the ceiling is
+            that line solved for `cap_s` and FLOORED, so it never promises a
+            duration that crosses the cap. CI recomputes the ceiling from these.
+          required: [slope_s_per_s, intercept_s, cap_s]
+          properties:
+            slope_s_per_s:
+              type: number
+              exclusiveMinimum: 0
+            intercept_s:
+              type: number
+            cap_s:
+              type: number
+              exclusiveMinimum: 0
+
     # ============================================
     # RETRY SCHEMAS
     # ============================================
@@ -15810,15 +16720,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