@giveitsmaller/contracts 0.72.0 → 0.76.0

package/openapi/api.yaml

@@ -35,6 +35,20 @@ info:
     (parser obligation: absent = stable; per-enum-value granularity is the
     `per_value_availability` primitive landed via ticket I17).
 
+    **Free-text string fields: `x-string-vocabulary` (ticket
+    [`Q79yjcFF`](https://trello.com/c/Q79yjcFF)).** A `type: string` field
+    with no `enum` that names example values says, as data, what a client
+    may do with them (the same marker is used in the AsyncAPI document):
+    - `open` — a vocabulary that grows. Each published value keeps its
+      meaning, the SET is not closed: switch on the values you know and
+      handle an unknown one as the generic case (e.g. `ErrorEnvelope.error`).
+    - `advisory` — explanatory text. Display or log it; **never switch on
+      it** (e.g. `SseWorkflowTerminalData.reason`).
+    - `none` — not a vocabulary at all (an expression or an identifier,
+      e.g. `OptionSchema.pattern`).
+    A field whose description hedges with "common values" or "free-form"
+    must carry the marker; a test enforces it.
+
     **Localisation (per ticket [I26](https://trello.com/c/rcnqwgI4)).**
 
     Error responses + paused/blocked workflow statuses carry a localised
@@ -89,7 +103,7 @@ info:
     of truth instead of hardcoding magic numbers. A runtime
     `GET /api/uploads/limits` endpoint for dynamic discovery
     (per-tier / per-environment overrides) is a deferred follow-up.
-  version: 2.203.0
+  version: 2.211.0
   contact:
     name: API Support
 
@@ -250,8 +264,16 @@ paths:
               tier_restriction, restriction_kind: file_size` instead.
             - **Pixel dimensions** (`error: IMAGE_DIMENSIONS_TOO_LARGE`) — a
               decodable raster image whose `width × height` exceeds the
-              configured pixel ceiling (`UPLOAD_MAX_IMAGE_PIXELS`, default
-              16 MP). The server reads dimensions from the file **header** (no
+              SINGLE-SHOT pixel ceiling (`UPLOAD_MAX_IMAGE_PIXELS`, default
+              16 MP), sized for the API's inline decode on this endpoint.
+              Multipart uploads have their own, higher ceiling
+              (`limits.max_multipart_upload_image_pixels`). It is an
+              environment setting, so an **authenticated**
+              client should read the effective value from
+              `limits.max_upload_image_pixels` on `GET /api/v2/account/limits`
+              (once the API emits it) rather than hard-code a number. ⚠️ That
+              endpoint requires authentication, so an **anonymous** uploader has
+              no discovery surface for it yet and learns it from this 413. The server reads dimensions from the file **header** (no
               full-bitmap decode) and rejects **before** decoding, so a
               within-byte-limit but huge-dimension image (e.g. a few-KB 26 MP
               PNG that would decode to ~100 MB) is rejected up front rather than
@@ -276,17 +298,21 @@ paths:
         '415':
           description: |
             Unsupported file type at the contract level (no tier permits
-            this MIME). For tier-specific MIME restrictions where some
-            tier does permit the MIME, the server returns 403 with
-            `error_type: tier_restriction, restriction_kind: mime_type`
-            instead.
+            this MIME): `error: UNSUPPORTED_FILE_TYPE`, flat envelope, never
+            retryable and never an upgrade prompt. For tier-specific MIME
+            restrictions where some tier does permit the MIME, the server
+            returns 403 with `error_type: tier_restriction, restriction_kind:
+            mime_type` instead. The file-type check runs before the size
+            check, so an unsupported file that is also too large gets this
+            415.
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorEnvelope'
               example:
                 success: false
-                error: "Unsupported MIME type: application/x-msdownload"
+                error: "UNSUPPORTED_FILE_TYPE"
+                message: "This file type is not supported."
         '422':
           description: |
             Tier-relative cap exceeded for this upload per ticket
@@ -461,11 +487,22 @@ paths:
               (across all tiers). For tier-specific size caps below this
               absolute limit, the server returns 403 with
               `error_type: tier_restriction, restriction_kind: file_size`.
-            - **Pixel dimensions** (`error: IMAGE_DIMENSIONS_TOO_LARGE`) — as
-              declared on `POST /api/uploads`: a decodable raster image whose
-              `width x height` exceeds the configured pixel ceiling
-              (`UPLOAD_MAX_IMAGE_PIXELS`, default 16 MP), read from the file
-              **header** and rejected **before** decoding.
+            - **Pixel dimensions** (`error: IMAGE_DIMENSIONS_TOO_LARGE`) — a
+              decodable raster image whose `width x height` exceeds the
+              MULTIPART pixel ceiling, read from the file **header** and
+              rejected **before** decoding. It is a SEPARATE, HIGHER ceiling
+              than single-shot's 16 MP (owner ruling 2026-09-24, card
+              [`ae4Q1yCb`](https://trello.com/c/ae4Q1yCb)): single-shot's is
+              sized for the API's inline decode, which multipart never does,
+              and multipart carries ordinary camera photos — **a 24 MP photo
+              must pass**. API setting `UPLOAD_MAX_MULTIPART_IMAGE_PIXELS`,
+              enforced at multipart initiate. Default 50 MP (hub ruling 2026-09-24, on lambdas'
+              recommendation: the image workers declare a 100 MP source cap,
+              but none has run a job that large, so it stays at half that
+              until a staging proof). It is an API setting, so authenticated
+              clients read the effective value from
+              `limits.max_multipart_upload_image_pixels`
+              (`GET /api/v2/account/limits`) once the API emits it.
 
             🔴 **THIS CASE WAS UNDECLARED HERE UNTIL 2026-08-28, AND THIS IS
             THE PATH IT MATTERS MOST ON.** Multipart exists for LARGE uploads,
@@ -480,9 +517,11 @@ paths:
                 $ref: '#/components/schemas/ErrorEnvelope'
         '415':
           description: |
-            Unsupported file type at the contract level. For tier-specific
-            MIME restrictions, the server returns 403 with
-            `error_type: tier_restriction, restriction_kind: mime_type`.
+            Unsupported file type at the contract level (no tier permits
+            this MIME): `error: UNSUPPORTED_FILE_TYPE`, as on
+            `POST /api/uploads`. For tier-specific MIME restrictions, the
+            server returns 403 with `error_type: tier_restriction,
+            restriction_kind: mime_type`.
           content:
             application/json:
               schema:
@@ -1032,9 +1071,13 @@ paths:
         bad ones before submit.
 
         Per ticket [I28 `KbVAnGCm`](https://trello.com/c/KbVAnGCm).
-        `availability: planned` until the cross-repo Lambda support
-        ships; the runtime returns `feature_not_available` (422)
-        until then. Per Tension 1 (ADR-0001 §1.3).
+        `availability: planned`. The upload-probe Lambda exists and runs
+        asynchronously when an upload is finalised; this endpoint returns
+        the cached result when one exists and `feature_not_available`
+        (422) when none does yet. It does not invoke the probe itself.
+        (A `planned` endpoint that answers 200 is inconsistent with the
+        availability taxonomy; the flip decision is tracked separately,
+        card `kAT0i5A6`.) Per Tension 1 (ADR-0001 §1.3).
 
         **SDK helper intent.** SDKs are expected to expose a
         `client.preflight_clips([file_ids])` helper that compiles to N
@@ -1044,10 +1087,11 @@ 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), so a
-        free-tier caller probing a 30-minute video sees
-        `blocked` rather than the long-form pre-assignment a
-        pro-tier caller would see.
+        F8.1 upload-side gating uses (per ticket I15-CONS), which
+        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
@@ -1138,22 +1182,6 @@ paths:
                         container: "mov"
                         probed_at: "2026-04-26T13:50:00Z"
                       processing_class_pre_assignment: "blocked"
-                blocked_by_tier:
-                  summary: Free-tier caller probes a long-form clip
-                  value:
-                    success: true
-                    data:
-                      file_id: "019539ab-1111-7000-8000-000000000005"
-                      probe_status: "ok"
-                      media_metadata:
-                        duration_seconds: 5400
-                        width: 1920
-                        height: 1080
-                        codec: "h264"
-                        container: "mp4"
-                        audio_layout: "stereo"
-                        probed_at: "2026-04-26T13:50:00Z"
-                      processing_class_pre_assignment: "blocked"
         '401':
           description: Authentication required.
           content:
@@ -1168,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:
@@ -1810,8 +1838,8 @@ paths:
                     required_action: "add_credits"
                     links:
                       top_up: "https://giveitsmaller.com/account/billing/top-up"
-                upgrade_plan_free_long_form:
-                  summary: Free tier; long-form requires pro upgrade
+                upgrade_plan_free_tier:
+                  summary: Free tier; the API judged the tier allowance too small for this workload (a balance outcome, not a capability gate)
                   value:
                     success: false
                     error: "Workflow requires more credits than the free tier provides."
@@ -1919,7 +1947,9 @@ paths:
             (`propertyName: error_type`):
             - `validation_error` → `ValidationErrorEnvelope` (carries
               `details[]`; the specific failure is in the `error` machine
-              code — `INVALID_OPTIONS`, `REQUIRES_REENCODE`,
+              code — `VALIDATION_FAILED` (an option or value failed
+              validation: unknown key, out of range, wrong type, enum),
+              `REQUIRES_REENCODE`,
               `CYCLIC_WORKFLOW_EDGES`, …). The `REQUIRES_REENCODE` flavour
               (per I16-CONS) reuses this same envelope/`error_type` and is
               distinguished only by its `error` code.
@@ -1972,18 +2002,16 @@ paths:
                     probe_pending: '#/components/schemas/ProbePendingResponse'
               examples:
                 validation_error:
-                  summary: Generic validation error (legacy shape)
+                  summary: An option failed validation (as the API emits it — VALIDATION_FAILED, details[] of {field, message})
                   value:
                     success: false
                     error_type: "validation_error"
-                    error: "INVALID_OPTIONS"
+                    error: "VALIDATION_FAILED"
                     details:
-                      - operation: "compress"
-                        option: "quality"
-                        message: "Must be between 1 and 100"
-                      - operation: "thumbnail"
-                        option: "width"
-                        message: "Required field"
+                      - field: "quality"
+                        message: "Option 'quality' must be at most 100."
+                      - field: "width"
+                        message: "Option 'width' is required."
                 cyclic_workflow_edges:
                   summary: Cyclic or self-referential explicit workflow_edges (g8PPkbNu)
                   value:
@@ -2080,8 +2108,10 @@ paths:
 
             1. **Long-form concurrency cap** — the caller already holds the
                maximum number of concurrent in-flight long-form (Fargate)
-               workflows their tier permits (Pro 2 / Max 5; Enterprise +
-               Free uncapped). Body is `LongFormConcurrencyLimitResponse`:
+               workflows their tier permits (per-tier values are the API's
+               `UserTier.maxConcurrentLongFormJobs` and are not restated
+               here — the restated copy said Free was uncapped while the
+               API capped it). Body is `LongFormConcurrencyLimitResponse`:
                `error: LONG_FORM_CONCURRENCY_LIMIT_EXCEEDED`, `message_key:
                job.long_form_concurrency_exceeded`, a `links.upgrade` CTA,
                and **no `Retry-After`** — the limit clears when an in-flight
@@ -2889,19 +2919,105 @@ paths:
             went too fast; a caller who has opened nothing and is refused
             because the pool is full has not, and sending them to a slow-down
             remedy is a lie. That case is `503`.
+
+            🔴 **THE LIMIT: 5 OPEN STREAMS PER CALLER** (owner ruling
+            2026-09-23, tickets [`2nZAmfxH`](https://trello.com/c/2nZAmfxH) /
+            [`rLCBjojv`](https://trello.com/c/rLCBjojv)).
+
+            - **Who "the caller" is.** An authenticated user — every stream
+              that user holds counts, across sessions and API keys. An
+              anonymous caller is counted per anonymous session.
+              ⛔ **The anonymous key MUST be server-derived, never from
+              client-supplied state** (a cookie or header the reader can drop
+              or rotate) — otherwise a capability-only reader mints fresh
+              slots per connection and the limit does not exist for anonymous
+              callers.
+              ⚠️ **What that key is TODAY: the verified capability, i.e. per
+              anonymous WORKFLOW.** An anonymous workflow persists only its
+              capability-token hash, not the session that created it, so "per
+              anonymous session" cannot yet be derived server-side. An
+              anonymous caller with several workflows therefore holds up to
+              the limit on EACH; the start-rate limiter and the global `503`
+              still bound the total. The key widens to the anonymous session
+              when the API persists an anonymous principal at create — that is
+              an API change, not a contract one.
+            - **What counts.** A stream occupies a slot from the moment it is
+              accepted (`200`) until it closes, for any reason. Streams are
+              counted, not starts — this is the limit `events_stream`'s start
+              RATE cannot express (see `503`).
+            - **Admission is an ATOMIC check-and-reserve, before the `200`.**
+              Checking the count and incrementing it as separate steps lets a
+              burst of concurrent requests all observe free capacity and open
+              more than the limit. A reservation whose stream then fails to
+              start MUST be released.
+            - **What is refused.** The request that would open the sixth
+              stream. **A held stream is never evicted to make room** — the
+              caller's existing streams are unaffected.
+            - **A crash cannot lock a caller out.** Slots are held in a shared
+              counter whose entries EXPIRE: a slot whose stream died without
+              closing cleanly is released at the latest when its entry
+              expires. The expiry is the server's to choose; it is the
+              longest a caller can be refused for streams that no longer
+              exist.
+            - ⛔ **An entry MUST NOT expire while its stream is still open.**
+              Either the expiry is at least the stream's maximum lifetime (the
+              server's stream deadline), or the holder refreshes the entry
+              while it streams. Otherwise a caller holding streams past the
+              expiry regains slots it is still using, and the limit silently
+              becomes "5 per expiry window" instead of "5 open".
+
+            ⚠️ **Refusal ends the ATTEMPT, never the workflow.** The workflow
+            keeps running and `/status` keeps answering; a caller refused a
+            stream loses only the push channel, not the result.
+
+            📌 **TWO `429`s SHARE THIS STATUS, discriminated by `error`:**
+            `SSE_CONNECTION_LIMIT_EXCEEDED` (the open-stream limit above,
+            carrying `open_streams` / `max_streams`) and the generic
+            `TOO_MANY_REQUESTS` from the `events_stream` start-RATE limiter — a
+            plain `ErrorEnvelope`, which validates against the same schema
+            because the two count fields are required only on the first. Both
+            carry `Retry-After` and the same obligation below.
+
+            🔴 **A BROWSER CANNOT READ `Retry-After` UNLESS IT IS EXPOSED.**
+            It is not a CORS-safelisted response header (Fetch Standard,
+            §CORS-safelisted response-header name), and the stream hosts are
+            cross-origin to the frontend. ⇒ **Every refusal on this endpoint
+            (`429` and `503`), as delivered to a browser, MUST carry the same
+            CORS headers as a `200` from that host AND
+            `Access-Control-Expose-Headers: Retry-After`.** Without the first
+            the browser cannot read the status; without the second it reads
+            the status and not the delay — and the consumer obligation below
+            becomes impossible to meet. The obligation is on whatever layer
+            sets CORS for the stream host, not only on the application.
           headers:
             Retry-After:
-              description: Seconds to wait. Delta-seconds, not an HTTP-date.
+              required: true
+              description: |
+                Seconds to wait. Delta-seconds, not an HTTP-date. **Always
+                sent on this status**, and exposed to browsers (see
+                `Access-Control-Expose-Headers` above).
+
+                **CONSUMER OBLIGATION** ([`rLCBjojv`](https://trello.com/c/rLCBjojv)):
+                a client receiving this status **MUST NOT** request another
+                stream for this caller before `Retry-After` has elapsed, and
+                **MUST NOT** treat it as a transport error to be retried on
+                its own schedule — it is a deliberate refusal. The client
+                **MAY** follow the workflow over `/status` meanwhile; that
+                endpoint's own rate limits govern it, and `Retry-After` here
+                governs only the next stream request.
               schema:
                 type: integer
+                minimum: 0
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ErrorEnvelope'
+                $ref: '#/components/schemas/SseConnectionLimitResponse'
               example:
                 success: false
                 error: SSE_CONNECTION_LIMIT_EXCEEDED
                 message: Too many open event streams for this caller.
+                open_streams: 5
+                max_streams: 5
         '503':
           description: |
             **Global stream capacity is exhausted — nothing about this caller.**
@@ -2959,10 +3075,34 @@ paths:
             Its refusal behaviour, **as a SHAPE — the counts and intervals are
             configurable defaults in that repo and are deliberately not
             restated here, because a number copied across a repo boundary rots
-            silently**: a non-200 is raised as a *transport error*, retried a
-            bounded number of times on a delay, and then falls through to
-            `/status` polling with **adaptive backoff** — the interval GROWS
-            while the server reports no movement.
+            silently.**
+
+            - **Since 2026-09-23 (`compression_frontend` #485, `17bd8b6`,
+              ticket `nuipMybn` — built against this section's obligation):**
+              a `429` / `503` **carrying `Retry-After` or the API's error
+              envelope** is a deliberate refusal, not a transport error (`SseRefusedError`,
+              carrying the status, the `Retry-After` delay and the `error`
+              code). The reader keeps `/status` polling, reopens the stream
+              only after `Retry-After` has elapsed — a wait that applies to
+              **every** stream that browser tab opens, not only the refused
+              one (it is held in the page, so another tab of the same caller
+              does not share it) —
+              and **never reopens** a refusal that carried no `Retry-After`.
+              ⚠️ **Two edges it does not cover, stated so this is not read as
+              blanket compliance:** an UNSTRUCTURED `503` (a load balancer's,
+              with neither) still takes the transport path below; and a
+              `Retry-After` too large for the browser's timer keeps THAT run on
+              polling but does not set the caller-wide wait, so another stream
+              in the same tab may open before it elapses. This contract sets
+              no upper bound on `Retry-After`.
+            - **Before that (measured 2026-08-25):** a non-200 was raised as a
+              *transport error* and retried a bounded number of times on a
+              fixed delay. Any other non-200 status, and the unstructured `503`
+              above, still takes that transport path.
+
+            Either way the fallback is `/status` polling with **adaptive
+            backoff** — the interval GROWS while the server reports no
+            movement.
 
             ⚠️ **And the `/status` poll is NOT started by the fallback.** It
             runs **in parallel from the outset**, as resilience against a
@@ -2974,8 +3114,9 @@ paths:
             🔴 **SO REFUSAL TRADES CONTINUOUS WORKER OCCUPANCY FOR A HIGHER
             REQUEST RATE.** Both halves matter: a held stream pins one PHP-FPM
             worker for its whole life and refusal genuinely sheds that — a
-            short poll is not a held connection — while that client's
-            connection attempts and polls go **up**.
+            short poll is not a held connection — while that client's polls go
+            **up**. (Its stream re-attempts no longer do: since #485 they wait
+            out `Retry-After`.)
             ⚠️ **Do not read either half alone.** "Refusal sheds load" invites
             a cap whose success metric moves the wrong way; "refusal increases
             load" argues against having a cap at all, and the occupancy it
@@ -2983,19 +3124,25 @@ 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.**
 
-            📌 **WHAT A REFUSED `fetch` CLIENT SHOULD DO INSTEAD IS NOT YET
-            SPECIFIED** — including whether `Retry-After` governs a fallback
-            poll interval and not only a reconnect. Falling back to polling
-            is also load, merely cheaper. Open on
-            [`rLCBjojv`](https://trello.com/c/rLCBjojv); **this block states the
-            measured behaviour and deliberately does not invent the
-            obligation.**
+            📌 **WHAT A REFUSED CLIENT MUST DO IS NOW SPECIFIED** — on the
+            `Retry-After` header of this status and of `429`
+            ([`rLCBjojv`](https://trello.com/c/rLCBjojv), decided with the
+            owner's stream-cap ruling of 2026-09-23): no further stream request
+            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.
+            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
@@ -3003,7 +3150,9 @@ paths:
             safe only by its own code, inside a browser or outside one** — and
             a retry loop treating `429`/`503` as retryable on a fixed interval
             is where a storm is reachable. ⚠️ **Our own frontend is in that
-            population, not exempt from it.**
+            population, not exempt from it** — it is safe today because #485
+            made it so, and a regression in its code would not be visible
+            here.
 
             ✅ **For OUR SDKs that is measured, not assumed** (sdks,
             2026-08-22, driven through the BUILT client with a stubbed
@@ -3018,11 +3167,19 @@ paths:
             endpoint would not notice.
           headers:
             Retry-After:
+              required: true
               description: |
                 Seconds to wait before retrying. Delta-seconds, not an
-                HTTP-date. **Also unreadable by `EventSource`** — see above.
+                HTTP-date. **Always sent on this status. Also unreadable by a native `EventSource`** — see
+                above; a `fetch`-based reader can read it.
+
+                **CONSUMER OBLIGATION** — the same as on `429`: no further
+                stream request before `Retry-After` has elapsed, never retried
+                as a transport error; `/status` polling permitted under that
+                endpoint's own limits.
               schema:
                 type: integer
+                minimum: 0
           content:
             application/json:
               schema:
@@ -3062,8 +3219,11 @@ paths:
         - `unspent_reservation_released`: the workflow was in
           `pending` / `in_progress` / `paused_insufficient_credits`,
           and the unspent portion of the original reservation has
-          been refunded to the caller's balance. The refund appears
-          as a separate `CreditTransaction` with `type: refund`.
+          been refunded to the caller's balance. The return appears
+          as a separate `CreditTransaction` with `type:
+          reservation_release` and `reference_type:
+          workflow_reservation_release` — there is no `type: refund`
+          (the API's ledger type is a closed set that has none).
         - `none`: no refund was issued (e.g. all reserved credits
           were already consumed by completed jobs at cancel time;
           or the workflow was already terminal in a previous cancel
@@ -5738,9 +5898,12 @@ paths:
         `schemas/operations/audio_watermark.yaml` — the operation
         embeds; this endpoint decodes.
 
-        **Tier-restricted.** This endpoint is `enterprise`-only. Free
-        and `pro` callers receive a 403 `feature_tier_restricted`.
-        Anonymous callers receive a 401.
+        **No tier gate** (since 2026-09-23, decision 26 — the paired
+        `audio_watermark` operation lost its `enterprise` gate the same
+        day; `X8m2vbvS`), and no 403 is declared: decode reads an
+        already-uploaded file, so no upload quota applies here. Any
+        authenticated caller may call it once it ships. Anonymous
+        callers receive a 401.
 
         **Scope: own watermarks only.** The decoder will refuse to
         extract from media the caller did not mark themselves
@@ -5761,7 +5924,7 @@ paths:
         `feature_not_available` (422) until the Lambda lands. Per
         Tension 1 (ADR-0001 §1.3).
       operationId: decodeAudioWatermark
-      security: [{bearerAuth: []}, {sessionAuth: []}]  # required (explicit 401 in response set; tier-gated runtime call)
+      security: [{bearerAuth: []}, {sessionAuth: []}]  # required (explicit 401 in response set; authenticated runtime call, no tier gate)
       tags:
         - AudioWatermark
       x-availability: planned
@@ -5784,22 +5947,6 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorEnvelope'
-        '403':
-          description: |
-            Tier insufficient (free / pro caller) — returned as
-            `FeatureTierRestrictedResponse` with
-            `error_type: feature_tier_restricted`. Per ADR-0001 §1.3.
-          content:
-            application/json:
-              schema:
-                oneOf:
-                  - $ref: '#/components/schemas/TierRestrictionResponse'
-                  - $ref: '#/components/schemas/FeatureTierRestrictedResponse'
-                discriminator:
-                  propertyName: error_type
-                  mapping:
-                    tier_restriction: '#/components/schemas/TierRestrictionResponse'
-                    feature_tier_restricted: '#/components/schemas/FeatureTierRestrictedResponse'
         '404':
           description: |
             No watermark detected in the supplied asset, OR the
@@ -5961,9 +6108,11 @@ paths:
         Per ticket [I23 `DffjC3zm`](https://trello.com/c/DffjC3zm).
 
         Each transaction is immutable once written. Workflow-create
-        reservations appear here as a single row; refunds appear as
-        separate rows referencing the original via `reference_id`
-        (and `reference_type: workflow`).
+        reservations appear here as a single row (`reference_type:
+        workflow_reservation`); credits returned appear as separate
+        rows carrying the workflow in `reference_id` and a
+        `reference_type` naming how they came back (see
+        `CreditTransaction.reference_type`).
 
         Default page is 20 transactions, ordered most-recent-first.
       operationId: getCreditsUsage
@@ -6033,7 +6182,7 @@ paths:
                           purchased_amount: null
                           pricing_version: "v3.2.0"
                           description: "Workflow reservation: compress.video short_form"
-                          reference_type: "workflow"
+                          reference_type: "workflow_reservation"
                           reference_id: "019539ac-2222-7000-8000-000000000001"
                           created_at: "2026-04-26T13:55:00Z"
                         - id: "019539ad-3333-7000-8000-aaaaaaaaaa02"
@@ -6048,14 +6197,14 @@ paths:
                           purchased_amount: -25
                           pricing_version: "v3.2.0"
                           description: "Workflow reservation: merge.video long_form_re_encode"
-                          reference_type: "workflow"
+                          reference_type: "workflow_reservation"
                           reference_id: "019539ac-2222-7000-8000-000000000002"
                           created_at: "2026-04-26T13:54:00Z"
                       total: 47
                       limit: 20
                       offset: 0
-                refund_followup:
-                  summary: Refund row referencing the prior workflow_001 reservation
+                reservation_release_followup:
+                  summary: Release row returning the prior workflow_001 reservation
                   value:
                     success: true
                     data:
@@ -6065,7 +6214,7 @@ paths:
                         # workflow_001.monthly_balance_after (955); after
                         # adds back 45 → 1000.
                         - id: "019539ad-3333-7000-8000-aaaaaaaaaa03"
-                          type: "refund"
+                          type: "reservation_release"
                           amount: 45
                           monthly_balance_before: 955
                           monthly_balance_after: 1000
@@ -6075,8 +6224,8 @@ paths:
                           monthly_amount: 45
                           purchased_amount: null
                           pricing_version: "v3.2.0"
-                          description: "Refund: terminal failure on operation-compression-video"
-                          reference_type: "workflow"
+                          description: "Reservation released: terminal failure on operation-compression-video"
+                          reference_type: "workflow_reservation_release"
                           reference_id: "019539ac-2222-7000-8000-000000000001"
                           created_at: "2026-04-26T13:56:00Z"
                       total: 47
@@ -6216,8 +6365,8 @@ paths:
                           tier_default: 10485760
                           overridden: false
                         max_total_input_size_bytes:
-                          effective: 1073741824
-                          tier_default: 1073741824
+                          effective: 5000000000
+                          tier_default: 5000000000
                           overridden: false
                 enterprise_with_upload_override:
                   summary: >-
@@ -6290,8 +6439,11 @@ paths:
         **How to observe the grant:** poll `GET /api/v2/credits/usage`
         for a transaction whose `reference_id` equals the `session_id`
         returned here, and whose `reference_type` is
-        `stripe_checkout_session`. That is the only client-observable
-        correlation between a checkout and its credits.
+        `stripe_checkout_session`. **Today that is the only
+        client-observable correlation** between a checkout and its credits.
+        `GET /api/billing/checkout/{sessionId}/status` is declared as the
+        second one, but it is `planned` (a `422 feature_not_available`)
+        until the API implements it.
 
         🔴 **MATCH ON `reference_type` + `reference_id`, AND DO NOT
         FILTER ON `type`.** The pack grant is written as an
@@ -6449,7 +6601,7 @@ paths:
                   value:
                     success: false
                     error_type: feature_not_available
-                    error: FEATURE_NOT_AVAILABLE
+                    error: UNPROCESSABLE_ENTITY
                     message: "Checkout is not yet available."
                     violations:
                       - feature: endpoint.billing.checkout
@@ -6515,6 +6667,105 @@ paths:
               schema:
                 $ref: '#/components/schemas/ErrorEnvelope'
 
+  /api/billing/checkout/{sessionId}/status:
+    get:
+      summary: Status of a checkout session the caller created
+      description: |
+        Whether the credits for a checkout the caller started have been
+        granted. Ticket [`7cSI8eIa`](https://trello.com/c/7cSI8eIa) — declared
+        BEFORE the API builds it (hub ruling, Option A, 2026-08-29); the API
+        half is [`JHrV4MUg`](https://trello.com/c/JHrV4MUg).
+
+        **Why it exists:** between "checkout created" and "the provider's
+        callback lands" nothing used to record that the session existed or
+        whose it was — so a post-checkout page, asked about the NORMAL
+        page-load state, had nothing to ask. The fix records the session at
+        creation; this endpoint reads that record and the credit ledger.
+
+        | `status` | meaning |
+        |---|---|
+        | `paid` | the purchase this session was for has been applied to the caller's account — for a credit **pack**, a credit transaction referencing this session exists; for a **subscription**, the subscription it started is active on the caller's account |
+        | `pending` | the session is recorded as created BY THE CALLER and its purchase has not been applied yet — **not a failure** |
+        | `unknown` | anything else |
+
+        🔴 **`unknown` DELIBERATELY COLLAPSES "not yours" WITH "never
+        existed". This is a decision, not missing detail.** Telling them
+        apart would make this endpoint an oracle for whether an arbitrary
+        session id is real — a probe confirming a stranger's purchase exists.
+        The requirement is *paid AND yours*; the honest refusal admits
+        neither. ⛔ **Do not "improve" the answer by distinguishing the two**
+        (a 403 or 404 for someone else's session is the same oracle).
+
+        ⛔ **No provider call on this read path.** It will be polled; a
+        third-party call would turn provider latency and outages into page
+        states and put the secret key on a read path.
+
+        ⛔ **No timing is stated here either** — the reason is the one given
+        on `POST /api/billing/checkout` (the delay is the provider's callback
+        latency, which this system does not measure). `pending` is a normal
+        state to keep polling on, not an error.
+      operationId: getCheckoutSessionStatus
+      security: [{bearerAuth: []}, {sessionAuth: []}]  # required; answers only about the caller's own sessions
+      x-identity-scoped: true  # a session belongs to the caller who created it
+      x-availability: planned
+      tags:
+        - Billing
+      parameters:
+        - name: sessionId
+          in: path
+          required: true
+          description: The `session_id` returned by `POST /api/billing/checkout`.
+          schema:
+            type: string
+            minLength: 1
+      responses:
+        '200':
+          description: |
+            The session's status for this caller. **Once implemented, always
+            200 for an authenticated caller**, whatever the session id —
+            `unknown` is the answer for anything not provably the caller's (see
+            the collapse rationale above). While the endpoint is `planned` it
+            answers `422 feature_not_available` instead.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CheckoutSessionStatusResponse'
+              examples:
+                paid:
+                  summary: Credits granted
+                  value:
+                    success: true
+                    data:
+                      session_id: cs_test_a1b2c3
+                      status: paid
+                pending:
+                  summary: Recorded for this caller, grant not landed yet
+                  value:
+                    success: true
+                    data:
+                      session_id: cs_test_a1b2c3
+                      status: pending
+                unknown:
+                  summary: Not provably this caller's — or never existed
+                  value:
+                    success: true
+                    data:
+                      session_id: cs_test_zzz
+                      status: unknown
+        '401':
+          description: Authentication required.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '422':
+          description: |
+            `feature_not_available` while this endpoint is `planned`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/FeatureNotAvailableResponse'
+
   # ============================================
   # CONTACT ENDPOINT
   # ============================================
@@ -6742,12 +6993,22 @@ components:
           enum: [false]
         error:
           type: string
+          x-string-vocabulary: open
           description: |
-            Stable, machine-readable error code (e.g.
-            `INVALID_OPTIONS`, `BALANCE_EXHAUSTED`,
+            Machine-readable error code. **Each published code is stable; the
+            SET is open** (`x-string-vocabulary: open`): handle an unknown code
+            as a generic error. E.g.
+            `VALIDATION_FAILED`, `BALANCE_EXHAUSTED`,
             `REQUIRES_REENCODE`). Canonical English; never localised.
             SDKs duck-type on this field for typed error-branch
-            helpers.
+            helpers — **except where an HTTP-status-shaped code
+            (`UNPROCESSABLE_ENTITY`, `BAD_REQUEST`, …) covers several
+            branches: there `error_type` is the discriminator.**
+            Example: `POST /api/billing/checkout` answers
+            `UNPROCESSABLE_ENTITY` both when checkout is switched off
+            (`error_type: feature_not_available`) and when a pack or
+            plan is not provisioned (no `error_type`); only
+            `error_type` tells them apart.
 
             Multipart-session resume codes (per ticket
             [`HxUmVr3Y`](https://trello.com/c/HxUmVr3Y), V2.10.0):
@@ -6780,7 +7041,8 @@ components:
               404 response + ADR-0016 Amendment.
             - `LONG_FORM_CONCURRENCY_LIMIT_EXCEEDED` (429) — caller already
               holds the maximum concurrent in-flight long-form workflows
-              their tier permits (Pro 2 / Max 5; Enterprise uncapped).
+              their tier permits (values: the API's
+              `UserTier.maxConcurrentLongFormJobs`, not restated here).
               DISTINCT from an infra rate-limit 429: carries no
               `Retry-After` (it clears on workflow completion) and adds a
               `links.upgrade` CTA. `message_key:
@@ -6867,21 +7129,33 @@ components:
             dispatch on `error_type` instead of structural `instanceOf`
             guards (which mis-fire on camelCase-vs-snake_case property
             names). Distinct from the `error` machine code below: `error`
-            carries the specific failure code (`INVALID_OPTIONS`,
+            carries the specific failure code (`VALIDATION_FAILED`,
             `REQUIRES_REENCODE`, `CYCLIC_WORKFLOW_EDGES`, …) while
             `error_type` only names the envelope shape.
         error:
           type: string
-          description: |
-            Stable error code. Common values: `INVALID_OPTIONS`
-            (generic option/value validation failure), `REQUIRES_REENCODE`
+          x-string-vocabulary: open
+          description: |
+            Error code. **Each published code is stable; the SET is open**
+            (`x-string-vocabulary: open`): handle an unknown code as a generic
+            validation error. Codes emitted today: `VALIDATION_FAILED`
+            (request, query-param **and workflow-create option/value**
+            validation failure — the API emits it for every create-time
+            option error: unknown key, out of range, wrong type, bad enum
+            value; `details[]` items carry `field` = the option key and
+            `message`), `REQUIRES_REENCODE`
             (per ticket I16-CONS — `merge.video` with
             `re_encode_mode: never` and incompatible inputs; caller
             resolves by switching to `re_encode_mode: auto` or `always`),
             `CYCLIC_WORKFLOW_EDGES` (cyclic/self explicit `workflow_edges`,
-            per `g8PPkbNu`), `VALIDATION_FAILED` (request/query-param
-            validation failure per the project-wide convention — e.g.
-            `GET /api/v2/credits/usage` invalid `limit`/`offset`).
+            per `g8PPkbNu`).
+            ⚠️ **`INVALID_OPTIONS` is NOT a create-time wire code**, though
+            earlier text here said it was and the example showed it: the
+            API has always sent `VALIDATION_FAILED` for option failures
+            (measured on prod by `compression_e2e`, 2026-09-23;
+            `WorkflowController` maps every `validation_error` to it).
+            `invalid_options` lives on the worker's
+            `OperationResult.error_code` (asyncapi), not on this envelope.
             SDKs duck-type on this field for typed error-branch helpers.
         message:
           type: string
@@ -6988,6 +7262,7 @@ components:
           enum: [false]
         error:
           type: string
+          x-string-vocabulary: open
           description: |
             Stable machine-readable failure code. `UNPROCESSABLE_ENTITY`
             for the generic auth domain rejections (register /
@@ -7221,6 +7496,14 @@ components:
     PerMimeAvailability:
       type: object
       description: |
+        **CLOSED TO NEW DECLARATIONS since 2026-09-18** ([`DquOfy7f`](https://trello.com/c/DquOfy7f)).
+        Retained for compatibility only: no cell declares it, and
+        `scripts/check-per-mime-availability.py` fails on any
+        declaration. The API does not enforce it and the SDKs do not
+        gate on it, so a differentiated MIME MUST use a parallel
+        mime_group instead. The description below records what the
+        field meant when it was open.
+
         Map of MIME-type → `PerValueAvailabilityEntry`. Attached to a
         mime_group's `per_mime_availability` field when individual
         MIMEs within the same `mimes:` list ship at different
@@ -7240,8 +7523,9 @@ components:
         remains the right tool when the differentiated subset has
         materially different option shape (animated GIF
         watermarking, video-base watermarking, etc.). This
-        primitive is for pure availability differentiation within
-        an otherwise-homogeneous mime list.
+        primitive WAS for pure availability differentiation within
+        an otherwise-homogeneous mime list; since the closure above,
+        that case uses a parallel mime_group too.
       additionalProperties:
         $ref: '#/components/schemas/PerValueAvailabilityEntry'
 
@@ -7891,6 +8175,32 @@ components:
         data:
           $ref: '#/components/schemas/AccountLimits'
 
+    CheckoutSessionStatusResponse:
+      type: object
+      # Envelope CLOSED, payload OPEN — the repo's success-envelope convention:
+      # top-level drift is detected, and new `data` fields stay additive.
+      additionalProperties: false
+      required: [success, data]
+      properties:
+        success:
+          type: boolean
+          enum: [true]
+        data:
+          type: object
+          required: [session_id, status]
+          properties:
+            session_id:
+              type: string
+              description: Echo of the path parameter.
+            status:
+              type: string
+              enum: [paid, pending, unknown]
+              x-enum-openness: closed
+              description: |
+                `paid` / `pending` / `unknown` — see
+                `GET /api/billing/checkout/{sessionId}/status`. `unknown`
+                collapses "not yours" and "never existed" on purpose.
+
     AccountLimits:
       type: object
       # Open payload (response data target stays open for additive evolution —
@@ -7951,6 +8261,29 @@ components:
               # api emits it. Unit is SECONDS — carried by the key name, per
               # AccountLimitEntry.
               $ref: '#/components/schemas/AccountLimitEntry'
+            max_upload_image_pixels:
+              # OPTIONAL in this expand step (ONxpaAlk); NOT required until api
+              # emits it. The upload gate's pixel ceiling for decodable rasters
+              # (width x height from the header) — the 413
+              # IMAGE_DIMENSIONS_TOO_LARGE threshold. It is an ENV KNOB on the
+              # API (UPLOAD_MAX_IMAGE_PIXELS), so the contract carries the
+              # SHAPE and the server serves the NUMBER; a number written here
+              # could drift from the running value by a task-definition edit.
+              # Not tier-varying today: `tier_default` equals `effective`.
+              # SINGLE-SHOT only (POST /api/uploads): sized for the API's inline
+              # decode. Multipart has its own key below (ae4Q1yCb).
+              $ref: '#/components/schemas/AccountLimitEntry'
+            max_multipart_upload_image_pixels:
+              # OPTIONAL in this expand step (ae4Q1yCb, owner ruling 2026-09-24);
+              # NOT required until api emits it. The MULTIPART upload pixel
+              # ceiling (width x height from the header) — the 413
+              # IMAGE_DIMENSIONS_TOO_LARGE threshold on the multipart path. A
+              # SEPARATE, HIGHER API setting than max_upload_image_pixels:
+              # default 50 MP (hub, 2026-09-24), about half the workers'
+              # declared 100 MP source cap, which is unproven end to end; it
+              # rises only after a 100 MP staging proof. It MUST admit a 24 MP
+              # photo. The server serves the number. Not tier-varying today.
+              $ref: '#/components/schemas/AccountLimitEntry'
 
     AccountLimitEntry:
       type: object
@@ -8005,9 +8338,10 @@ components:
       description: |
         Single ledger entry. Immutable once written. A workflow-create
         reservation appears here as a single row with `source_bucket`
-        indicating which pool(s) were debited; refunds appear as
-        separate rows referencing the original via `reference_id` and
-        `reference_type: workflow`.
+        indicating which pool(s) were debited; a returned reservation
+        appears as a separate `reservation_release` row referencing the
+        workflow via `reference_id` (see `reference_type` for the
+        values that distinguish a release from a settle refund).
 
         `type`, `pricing_version`, and `reference_type` are
         deliberately free-form strings — their value sets evolve with
@@ -8036,11 +8370,16 @@ components:
           $ref: '#/components/schemas/UuidV7'
         type:
           type: string
-          description: |
-            Ledger entry type — free-form string. Common values:
-            `reservation`, `refund`, `top_up`, `monthly_grant`,
-            `adjustment`. Not enumerated to avoid contract churn as
-            billing event taxonomy evolves.
+          x-string-vocabulary: open
+          description: |
+            Ledger entry type — free-form string. Values the API emits
+            today (its `CreditTransactionType`, a closed set): `grant`,
+            `deduction`, `adjustment`, `overdraft_repayment`,
+            `reservation`, `reservation_release`. **There is no
+            `refund`, `top_up` or `monthly_grant`** — earlier text listed
+            them, and a consumer filtering on one matched nothing. Not
+            enumerated in the schema to avoid contract churn as billing
+            event taxonomy evolves; SDKs duck-type.
         amount:
           type: integer
           description: |
@@ -8104,6 +8443,7 @@ components:
             applies symmetrically.
         pricing_version:
           type: string
+          x-string-vocabulary: none
           description: |
             Pricing-table version applied to this transaction.
             Free-form string (server emits a semver-shaped or
@@ -8117,10 +8457,16 @@ components:
           description: Human-readable description of the ledger entry.
         reference_type:
           type: string
-          description: |
-            What the transaction references. Common values:
-            `workflow`, `top_up`, `cycle_grant`, `adjustment`.
-            Free-form string.
+          x-string-vocabulary: open
+          description: |
+            What the transaction references. Free-form string. Values
+            the API emits for workflow credits: `workflow_reservation`
+            (the debit), `workflow_reservation_release`,
+            `workflow_pause_release`, `workflow_expiry_release` and
+            `workflow_settle_refund` (credits returned);
+            `stripe_checkout_session` for a credit-pack purchase. Match
+            on this field, not on `type`, to tell a release from a
+            settle refund.
         reference_id:
           type: string
           description: |
@@ -8178,6 +8524,7 @@ components:
         # additively from the API ahead of this contract.
         state:
           type: [string, "null"]
+          x-string-vocabulary: open
           description: |
             Reservation lifecycle state — free-form string (kept opaque like
             `type`/`reference_type` for churn-resistance; SDKs duck-type).
@@ -8378,14 +8725,64 @@ components:
                   format: uri
                   description: Top-up deep link.
 
+    SseConnectionLimitResponse:
+      type: object
+      description: |
+        `429` body for `GET /api/workflows/{id}/events` when the caller already
+        holds the maximum number of open event streams
+        (`SSE_CONNECTION_LIMIT_EXCEEDED`). The limit, who counts as the caller,
+        and the consumer obligation are on that response. Carries the two
+        counts the SDK taxonomy's `metadataSchema` names (`openStreams` /
+        `maxStreams` after camelCase lowering), so a client can say "5 of 5
+        streams open" without restating the limit.
+
+        **Both count fields are REQUIRED when `error` is
+        `SSE_CONNECTION_LIMIT_EXCEEDED` and absent otherwise**, enforced by the
+        `if`/`then`/`else` branch below rather than a plain `required` list,
+        because the endpoint's other `429` — `TOO_MANY_REQUESTS` from the
+        start-rate limiter — is the plain `ErrorEnvelope` subset of this shape
+        and must validate against it too.
+      allOf:
+        - $ref: '#/components/schemas/ErrorEnvelope'
+        - type: object
+          properties:
+            open_streams:
+              type: integer
+              minimum: 0
+              description: Streams this caller holds open at the moment of refusal.
+            max_streams:
+              type: integer
+              minimum: 1
+              description: |
+                The caller's open-stream limit. **Read the limit from here,
+                not from prose** — it is the server's value at refusal time.
+        # The two 429 branches, machine-enforced (codex, #515 round 4): the
+        # counts are REQUIRED on the stream-limit refusal and FORBIDDEN on any
+        # other code (the start-rate limiter's plain TOO_MANY_REQUESTS).
+        - if:
+            required: [error]
+            properties:
+              error:
+                const: SSE_CONNECTION_LIMIT_EXCEEDED
+          then:
+            required: [open_streams, max_streams]
+          else:
+            not:
+              anyOf:
+                - required: [open_streams]
+                - required: [max_streams]
+
     LongFormConcurrencyLimitResponse:
       type: object
       description: |
         `429` response body for `POST /api/workflows` when the caller
         already holds the maximum number of concurrent in-flight
         long-form (Fargate) workflows their tier permits
-        (`UserTier.maxConcurrentLongFormJobs`: Pro 2 / Max 5; Enterprise
-        + Free uncapped — Free has no long-form access at all). Carried
+        (`UserTier.maxConcurrentLongFormJobs`, owned by the API and not
+        restated here: an earlier copy said Free was uncapped and had no
+        long-form access, while the API capped Free at a value of its own
+        — and since 2026-09-23 every tier reaches long-form, decision 26,
+        `jLuZvlJe`). Carried
         on a `429` but DISTINCT from an infrastructure rate-limit `429`:
 
         - `error` is the stable code `LONG_FORM_CONCURRENCY_LIMIT_EXCEEDED`
@@ -8439,10 +8836,11 @@ components:
         Effect of a workflow cancel on outstanding credit
         reservations.
         - `unspent_reservation_released`: caller refunded for the
-          unspent portion of the original reservation; refund
-          appears as a separate `CreditTransaction` (`type: refund`,
-          `reference_type: workflow`, `reference_id` matching the
-          cancelled workflow).
+          unspent portion of the original reservation; the return
+          appears as a separate `CreditTransaction` (`type:
+          reservation_release`, `reference_type:
+          workflow_reservation_release`, `reference_id` matching the
+          cancelled workflow). There is no `type: refund`.
         - `none`: no refund issued (all reserved credits already
           consumed by completed jobs at cancel time, OR the
           workflow was already terminal in a previous cancel — the
@@ -9691,6 +10089,12 @@ components:
     OperationType:
       type: string
       description: |
+        ⚠️ **HOMONYM:** `asyncapi/events.yaml` also declares an `OperationType` —
+        the narrower event PAYLOAD vocabulary. This one is the CREATE surface.
+        Same name, different membership; generated SDKs emit both, and the
+        import path is the only distinguisher (not renamed — breaking;
+        `bFy3zo5Y`). Relation asserted in `schemas/cross-document-enums.yaml`.
+
         Available operation types:
         - compress: Reduce file size (images, audio, video, documents)
         - thumbnail: Legacy thumbnail value. Generates a preview image
@@ -9714,13 +10118,13 @@ components:
         - merge: Concatenate/combine multiple files into one (images, video, audio). Multi-input. Image inputs merge into animated GIF or slideshow video; image collage/grid and PDF concatenation are not supported by the V1 Lambda.
         - archive: Bundle files into ZIP/tar.gz (all types). Multi-input.
         - 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` + `required_tier: pro`; 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).
+        - 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.
@@ -10608,13 +11012,9 @@ components:
         The two forms are mutually exclusive (a request supplies exactly
         one — enforced by the `oneOf` below); they are NOT combined.
 
-        🔴 **THE FLAT FORM IS `planned`, AND THE SERVER DOES NOT ACCEPT IT
-        YET.** Send `jobs[]`. A flat request is rejected today, and the
-        rejection is currently a generic *"At least one job is required"*
-        rather than the `feature_not_available` (422) envelope this contract
-        requires for a `planned` shape — tracked against `compression_api`,
-        so do not read that generic message as a validation error in your
-        own payload.
+        🔴 **THE FLAT FORM IS `planned`.** Send `jobs[]`. A flat request is
+        rejected with the `feature_not_available` (422) envelope (feature
+        `workflow.request.flat_form`) until the API accepts the flat form.
 
         ⚠️ **The equivalence stated above is the DESIGN, not observed
         behaviour.** It describes what the server will do once the lowering
@@ -10770,11 +11170,12 @@ components:
           $ref: '#/components/schemas/NotifyConfig'
           description: |
             Optional per-job completion-notification config
-            (channel-agnostic). Currently exposes the `email` channel: the
-            API emails the configured recipients when the selected workflow
-            events occur, with a **server-composed** presigned `/downloads`
-            link to the results — the request carries recipients + event
-            selection only.
+            (channel-agnostic). Declares the `email` channel: once the
+            dispatch engine ships, the API emails the configured recipients
+            when the selected workflow events occur, with a
+            **server-composed** presigned `/downloads` link to the results —
+            the request carries recipients + event selection only. Nothing is
+            sent today (see `NotifyConfig`).
 
             **Advertised-ahead (contract-first, ticket
             [`IQtEwVET`](https://trello.com/c/IQtEwVET)):** the completion-
@@ -11316,6 +11717,7 @@ components:
             job that consumes this output.
         node_id:
           type: string
+          x-string-vocabulary: open
           description: |
             Symbolic composition `node_id` correlating this delivered output
             to its canonical node in `composition_plan` (e.g. `encode`,
@@ -11607,6 +12009,7 @@ components:
           $ref: '#/components/schemas/ProcessingClass'
         execution_pool:
           type: string
+          x-string-vocabulary: advisory
           description: |
             Logical pool name. **Opaque string** — not an enum — so
             future pool naming evolves without contract churn. Known
@@ -11870,6 +12273,7 @@ components:
       properties:
         node_id:
           type: string
+          x-string-vocabulary: open
           description: |
             Stable **symbolic** canonical node id (e.g. `original`,
             `processed_base`, `encode`, `thumbnail`). The correlation key
@@ -11892,6 +12296,7 @@ components:
             nodes `type` is the operation as submitted.
         chain_group:
           type: string
+          x-string-vocabulary: open
           description: |
             Which canonical stage this operation belongs to. **Open string,
             NOT a fixed enum** (mirrors `ProcessingPlanJob.execution_pool`) —
@@ -12018,9 +12423,10 @@ components:
         gating (per ticket I15-CONS) — reflects what the server
         would route this file to under the caller's current tier.
         `blocked` is emitted when no tier-permitted pool exists for
-        the file (e.g. free-tier caller probing a long-form clip,
-        or any caller probing a `corrupt` / `unsupported_codec`
-        file).
+        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) 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
@@ -12601,7 +13007,9 @@ components:
           description: |
             OPTIONAL, drill-in-only "code for this run" / replay projection — the
             allowlisted, re-submittable shape of the original request (for an SDK
-            snippet / "run it again"). Absent until the API populates it. NOT a
+            snippet / "run it again"). Emitted on every workflow status
+            response by an API that implements the projector; OPTIONAL so a
+            consumer of an older API build tolerates its absence. NOT a
             dump of the persisted option bag; see `CodegenSource`. Per ticket
             `LO0R5gzk`.
 
@@ -12836,8 +13244,9 @@ components:
         EXCLUDES all of that plus runtime results.
 
         **Detail-only** — `WorkflowStatusResponse` only, NEVER `WorkflowSummary`
-        (payload + the list view doesn't need it). OPTIONAL: the projector ships
-        incrementally; the field is absent until the API populates it.
+        (payload + the list view doesn't need it). OPTIONAL in the schema so a
+        consumer of an older API build tolerates its absence; an API that
+        implements the projector emits it on every status response.
 
         **Scope: the reproducible JOB graph only.** Workflow-level request
         fields (`delivery` / `export` / `processing`) are deliberately NOT part
@@ -13248,6 +13657,9 @@ components:
             `never_started` (the operation was terminated without ever running
             because its job reached a terminal state first — an upstream failure
             OR a cancellation; API-derived, never worker-emitted),
+            `processing_limit_exceeded` (a processing tool was killed at a
+            budget set from this input — deterministic, non-retryable; a
+            transient deadline is `timeout`),
             `unknown` (unclassified),
             `out_of_memory` (retryable), `timeout` (retryable),
             `s3_download_failed` (retryable), `s3_upload_failed` (retryable).
@@ -13258,6 +13670,39 @@ components:
             Human-readable failure detail. Present when `status` is `failed`;
             absent otherwise. Mirrors `SseOperationFailedData.error_message`.
           example: "output_too_large: Output (12156489 bytes) is not smaller than input (6187609 bytes)"
+        message_key:
+          $ref: '#/components/schemas/OperationMessageKey'
+        message_params:
+          $ref: '#/components/schemas/OperationMessageParams'
+
+    OperationMessageKey:
+      type: string
+      x-string-vocabulary: open
+      pattern: '^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$'
+      description: |
+        Stable, never-localised key REFINING `error_code` on a failed
+        operation, so a client can show specific, localised copy (e.g.
+        `thumbnail.epub.no_cover`). OPTIONAL, failed only. Every value is
+        declared, with the codes it may accompany and its parameters, in
+        `schemas/operation-message-keys.yaml` (the one registry). Passed
+        through unchanged from the worker's OperationResult. A client
+        that does not know a key, or receives one whose registry
+        `error_codes` do not include this `error_code`, ignores the key and
+        falls back to the `error_code` headline;
+        retry is still decided from the code. Ticket U7GQhjhX.
+      example: "thumbnail.epub.no_cover"
+
+    OperationMessageParams:
+      type: object
+      additionalProperties:
+        type: [string, integer, number, boolean]
+      description: |
+        Interpolation values for `message_key`, named and typed in
+        `schemas/operation-message-keys.yaml`. JSON scalars only (string,
+        integer, number, boolean) — no nested objects. Absent when the key
+        declares no parameters (`params: {}`), and carries exactly the
+        registry's parameters otherwise. Never carries free-text
+        diagnostics; those stay in `error_message`.
 
     OperationResultMetadata:
       type: object
@@ -13269,9 +13714,15 @@ components:
         diagnostics never leak. New keys are **additive named cuts** (the
         `additionalProperties: false` closure is the point — an unmodelled
         key is a coordinated contract change, not a silent rollout). Twin of
-        the AsyncAPI `OperationResultMetadata` (wire ↔ read parity). Distinct
+        the AsyncAPI `OperationResultMetadata` (wire ↔ read parity), except
+        `already_optimal` / `estimated_saving_pct`, which the API projects
+        from the wire `OperationMetrics` where the worker emits them. Distinct
         from `OperationResult` (the deliverable output file): this carries
         small per-operation metadata, not the output. Per `EurbZLMH` (B1).
+      # The estimated_saving_pct => already_optimal:true relation is ENFORCED on
+      # the wire OperationMetrics this is projected from, not here: this schema
+      # also types the workflowCallback webhook payload, where oasdiff reads an
+      # added if/then as a breaking REQUEST change.
       properties:
         watermark_id:
           type: string
@@ -13284,6 +13735,28 @@ components:
             whitelist ship now (additive) so the result_metadata pipeline +
             read projection land without a later contract bump; absent in
             practice until B3 is live.
+        already_optimal:
+          type: boolean
+          description: |
+            `true` when the operation completed by returning the ORIGINAL file
+            unchanged, because compressing it would not have made it smaller
+            (or the source was already efficiently encoded). The operation is
+            a success, not a failure: `result` is the original. Show it as
+            "already optimised", not as "same size". On an ordinary result it
+            is absent or `false`; treat the two the same. Projected by the API from the wire
+            `OperationMetrics.already_optimal` (ticket `roNRMilt`).
+          example: true
+        estimated_saving_pct:
+          type: number
+          minimum: 0
+          maximum: 100
+          description: |
+            OPTIONAL, only with `already_optimal: true`: the worker's ESTIMATE
+            of how much smaller, as a percentage of the input size, a re-encode
+            would have made the file, when it declined before encoding. Absent
+            when no estimate was made. An estimate, not a guarantee. Projected
+            from the wire `OperationMetrics.estimated_saving_pct`.
+          example: 3.5
 
     OperationResult:
       type: object
@@ -13378,6 +13851,7 @@ components:
                 `OperationMetrics.measured_quality`.
             quality_metric:
               type: string
+              x-string-vocabulary: advisory
               description: |
                 The perceptual metric that produced `measured_quality` — a free-form
                 string (not an enum) so it can evolve without contract churn. Present
@@ -13394,6 +13868,7 @@ components:
               $ref: '#/components/schemas/ReEncodeDecision'
             re_encode_reason:
               type: string
+              x-string-vocabulary: advisory
               description: |
                 Advisory explanation for `re_encode_decision` (e.g.
                 `all_inputs_compatible`, `explicit_always_mode`,
@@ -13688,6 +14163,7 @@ components:
             Mirrors `OperationMetrics.measured_quality`.
         quality_metric:
           type: string
+          x-string-vocabulary: advisory
           description: |
             For an `auto_quality` encode: the perceptual metric that produced
             `measured_quality` — a free-form string (not an enum) so it can evolve
@@ -13736,6 +14212,7 @@ components:
           example: "thumb-2x"
         node_id:
           type: string
+          x-string-vocabulary: open
           description: |
             Symbolic composition `node_id` correlating this download to its
             canonical node in `WorkflowCreateResponse.composition_plan` (e.g.
@@ -14119,9 +14596,10 @@ components:
           not: { required: [page_index] }
         - title: Unindexed
           description: |
-            Output without an explicit indexing field. Reserved for future
-            operations that index by something other than page/position.
-            Schema-valid but not currently emitted by any operation.
+            Output without a page/position indexing field. Covers legacy
+            single-output entries AND `render_variants` variant outputs (still
+            `planned`, so not reachable through the API until that operation
+            is). Mirrors the AsyncAPI `OperationResultOutputEntry` branch.
           not:
             anyOf:
               - required: [page_index]
@@ -14197,6 +14675,10 @@ components:
             generic reason.
         error_message:
           type: string
+        message_key:
+          $ref: '#/components/schemas/OperationMessageKey'
+        message_params:
+          $ref: '#/components/schemas/OperationMessageParams'
 
     SseJobCompletedData:
       type: object
@@ -14257,6 +14739,7 @@ components:
             - partially_failed
         reason:
           type: string
+          x-string-vocabulary: advisory
           description: |
             Optional advisory reason for the terminal state. Free-form
             string; not an enum. Examples: "all jobs completed
@@ -15095,19 +15578,19 @@ 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: |
             Operation-level minimum subscription tier. Optional — when
             absent, the operation is available to all callers regardless
             of tier. Per ADR-0001 §1.3 (tier and availability are
-            orthogonal axes). First operation-level consumer is
+            orthogonal axes). First operation-level consumer was
             `custom_luma` (`required_tier: pro`) per
-            [I29 `EPUE5Vs1`](https://trello.com/c/EPUE5Vs1). SDK + frontend
+            [I29 `EPUE5Vs1`](https://trello.com/c/EPUE5Vs1); that gate was
+            dropped 2026-09-23 under decision 26 (owner ruling, `jLuZvlJe`). SDK + frontend
             consumers gate UI on this value alongside `availability` to
             hide higher-tier features for lower-tier callers; the
             runtime returns `feature_tier_restricted` (403) on
@@ -15228,18 +15711,31 @@ components:
         per_mime_availability:
           $ref: '#/components/schemas/PerMimeAvailability'
           description: |
-            Optional per-MIME availability map per ticket
-            [`YXYOo6gg`](https://trello.com/c/YXYOo6gg). Keys MUST be
-            a subset of `mimes[]` (CI-checked by
-            `scripts/check-per-mime-availability.py`); absent keys
-            default to `availability: stable`. Use this when
-            individual MIMEs within an otherwise-homogeneous mime
-            list ship at different availability levels (e.g.
-            `image/avif: beta, image/heic: planned` alongside
-            `image/jpeg: stable`). Runtime emission lands with
-            [I3](https://trello.com/c/eCWIpug8); until then the
-            contract advertises the field shape but the endpoint
-            does not yet surface the field.
+            CLOSED TO NEW DECLARATIONS since 2026-09-18, ticket
+            [`DquOfy7f`](https://trello.com/c/DquOfy7f). No mime_group
+            declares this field and none may:
+            `scripts/check-per-mime-availability.py` REFUSES any
+            declaration, anywhere, at any depth. Expect this map to be
+            absent or empty on every group.
+
+            USE A PARALLEL `mime_group` INSTEAD. A group-level
+            `planned` is enforced at create by the API's 422 gate;
+            this map is NOT enforced anywhere. `compression_api`
+            round-trips it raw; the SDK generators parse and publish
+            it but nothing gates on it (`sdk_exposure` composes
+            op/group/option/value and has no per-MIME level); only the
+            frontend UI resolves it. So a declared value would be
+            served by the API, published to SDK consumers as metadata
+            their own gating ignores, and honoured only in one UI.
+
+            The field itself is RETAINED, not removed: the shape is
+            already published and deleting it would break the four
+            consuming repos. Keys, if any were ever present, MUST be a
+            subset of `mimes[]`, and absent keys mean
+            `availability: stable`. Runtime emission was to land with
+            [I3](https://trello.com/c/eCWIpug8); that roadmap is
+            closed. See `schemas/FORMAT.md`
+            §`per_mime_availability`.
         max_input_size_bytes:
           type: integer
           format: int64
@@ -15247,7 +15743,7 @@ components:
           description: |
             Optional mime-group-level INPUT-file size ceiling in BYTES
             (ticket [`uKsFzORi`](https://trello.com/c/uKsFzORi)). Sibling of
-            `max_output_pixels`. **Applies to the enclosing operation's input**, and
+            `max_output_pixels` (declared below). **Applies to the enclosing operation's input**, and
             a consumer MUST scope it to the operation whose schema carries it —
             **the same MIME can carry different ceilings under different
             operations, because different workers process it.** ⚠️ This line
@@ -15270,6 +15766,33 @@ components:
             `processing_class.<class>.constraints.max_input_size_bytes` instead —
             never both, so the input ceiling lives in exactly one place per group.
             CI-enforced by `scripts/check-per-tier-constraints.py`.
+        max_output_pixels:
+          type: integer
+          format: int64
+          minimum: 1
+          description: |
+            Optional mime-group-level OUTPUT area cap: a request is valid on
+            this axis iff `width × height <= max_output_pixels`, read from the
+            two option values. Declared here since 2026-09-23 (`gACSVjiK`): it
+            was named as a "sibling" of `max_input_size_bytes` while existing
+            only in the operation schemas and the availability sidecar, and a
+            consumer diffing the served schema reported it as a missing key.
+            ⚠️ **Optional, and not yet round-tripped by `GET
+            /api/operations/schema`** — the operation schemas under `schemas/`
+            and `availability/availability.json` carry it today. See
+            `schemas/FORMAT.md` §`max_output_pixels`.
+        input_size_bound:
+          type: string
+          enum: [processing_time]
+          x-enum-openness: closed
+          description: |
+            Declares that the group has **no byte ceiling on purpose**: the
+            worker is bounded by processing time instead. XOR with
+            `max_input_size_bytes` — exactly one is present when either is, so
+            an absent pair means "nothing declared", never "unlimited".
+            Declared here since 2026-09-23 (`gACSVjiK`) for the same reason as
+            `max_output_pixels`, with the same round-trip caveat. See
+            `schemas/FORMAT.md` §`input_size_bound`.
         max_input_duration:
           type: string
           description: |
@@ -15446,6 +15969,7 @@ components:
           description: Maximum value (for integer/float types)
         pattern:
           type: string
+          x-string-vocabulary: none
           description: |
             ECMA-262 regular expression a `type: string` value MUST match
             (the string analogue of `min`/`max`). Consumers pre-validate
@@ -15456,6 +15980,29 @@ components:
             `#RRGGBB`; a CSS named colour was silently dropped to white). Only
             meaningful for `type: string`. See `schemas/FORMAT.md`.
           example: "^#[0-9a-fA-F]{6}$"
+        items:
+          type: object
+          additionalProperties: true
+          description: |
+            `type: array` only. A JSON Schema 2020-12 OBJECT subschema every
+            element must satisfy (boolean schemas are not used in this DSL;
+            e.g. `{type: number, exclusiveMinimum: 0}` for
+            `split.cut_points`, or an object shape for
+            `image_watermark.overlays`). Named in JSON Schema's own camelCase,
+            like `pattern`, because these ARE JSON Schema keywords and the
+            published operation schemas already use them (fzrEO6GN).
+        minItems:
+          type: integer
+          minimum: 0
+          description: "`type: array` only. Fewest elements allowed."
+        maxItems:
+          type: integer
+          minimum: 0
+          description: "`type: array` only. Most elements allowed."
+        uniqueItems:
+          type: boolean
+          description: |
+            `type: array` only. `true`: elements must be pairwise distinct.
         depends_on:
           type: object
           description: |
@@ -15647,15 +16194,22 @@ components:
     NotifyConfig:
       type: object
       x-availability: planned
+      # CLOSED to the declared channels: the API refuses an undeclared channel
+      # key as validation_error, so the schema says so too (codex, #568).
+      additionalProperties: false
       description: |
         Channel-agnostic per-job completion-notification config (ticket
         [`IQtEwVET`](https://trello.com/c/IQtEwVET)). Currently the `email`
         channel only; `webhook` folds onto the same dispatch engine later
         (today webhook is configured via the top-level `callback_url` /
         `callback_events`). **Advertised-ahead** — the API returns
-        `feature_not_available` (422) for any `notify` use until the
-        dispatch engine ships. `x-availability` is decorative per
-        ADR-0001 §1.5; the API is the authority on the 422 gate.
+        `feature_not_available` (422) for any use of a declared channel
+        until the dispatch engine ships, with feature path
+        `workflow.notify.<channel>` (today `workflow.notify.email`), the
+        same dotted grammar as `workflow.request.flat_form`. An undeclared
+        channel key is a `validation_error` (422). `x-availability` is
+        decorative per ADR-0001 §1.5; the API is the authority on the 422
+        gate.
 
         An **empty `notify`** (object present but no channel set) is a
         no-op — the workflow runs normally with no notifications; it is