@giveitsmaller/contracts 0.7.0 → 0.9.0

package/openapi/api.yaml

@@ -42,13 +42,27 @@ info:
     `message_key`. Machine-readable fields (`error`, enum values, status
     codes) stay canonical English.
 
+    - **Currently committed locales:** `en-GB` only (per ticket
+      [`4GKyuYo6`](https://trello.com/c/4GKyuYo6)). The I26 carrier
+      shape (`Accept-Language` + `Content-Language` + `Vary` headers +
+      `locale` envelope field + `message_key` + `message_params`) is
+      stable and exercised; the **catalog** of translated `message`
+      strings is en-GB-only at runtime today. Additional locales (e.g.
+      `pt-PT`) will be advertised by name when their catalogs ship —
+      the request/response carrier shape does NOT change when a new
+      locale lands. Treat unrequested locales as "machine-code +
+      `message_key` path is committed; localised `message` prose is
+      not" until this prose enumerates them by name.
     - **Request:** `Accept-Language` header per RFC 9110 §12.5.4 (q-value
       negotiation supported). The server selects the best-match locale
-      from its supported list; falls back to `en-GB` when no match.
+      from its supported list; falls back to `en-GB` when no match —
+      which, until additional catalogs land, is every non-`en-GB`
+      `Accept-Language`.
     - **Response:** `Content-Language: <locale>` echo on every localised
       response; `Vary: Accept-Language` on every response (CDN/cache
       correctness — different `Accept-Language` requests produce
-      different responses).
+      different responses). `Vary` is emitted unconditionally so the
+      header contract does not flip when a second locale ships.
     - **Fallback locale:** `en-GB` (also the canonical locale for
       `message_key` translations and English `message` prose).
     - **SDK guidance:** switch on `error` (machine code) for typed
@@ -75,7 +89,7 @@ info:
     of truth instead of hardcoding magic numbers. A runtime
     `GET /api/uploads/limits` endpoint for dynamic discovery
     (per-tier / per-environment overrides) is a deferred follow-up.
-  version: 2.17.0
+  version: 2.31.0
   contact:
     name: API Support
 
@@ -1132,10 +1146,12 @@ paths:
           discriminated union with 4 leaves: `upload` /
           `external_import` / `connection` / `job_output`).
         - **Multi-input jobs** (merge, archive, image_watermark,
-          custom_luma, audio_overlay): provide `inputs[]` with
+          custom_luma, audio_overlay, audio_to_video, video_watermark):
+          provide `inputs[]` with
           `JobInputV2` entries. Each entry has its own `source`
           (same `WorkflowSource` union), plus optional `role`
-          (image_watermark, custom_luma, audio_overlay) and
+          (image_watermark, custom_luma, audio_overlay, audio_to_video,
+          video_watermark) and
           `per_input_options`.
 
         Exactly one of `source` or `inputs` is required per job.
@@ -1170,8 +1186,9 @@ paths:
 
         **Multi-input constraint:** multi-input jobs (`inputs[]`) must
         have exactly one operation, which must be a multi-input type
-        (`merge`, `archive`, `image_watermark`, `custom_luma`, or
-        `audio_overlay`). Chaining after a multi-input operation is
+        (`merge`, `archive`, `image_watermark`, `custom_luma`,
+        `audio_overlay`, `audio_to_video`, or `video_watermark`).
+        Chaining after a multi-input operation is
         not valid — create a downstream `job_output`-sourced job
         instead.
 
@@ -1379,11 +1396,59 @@ paths:
                           max_parallel_long_form_jobs: 2
                       warnings: []
         '400':
-          description: Validation failed (malformed request body)
+          description: |
+            Bad request — malformed request body, or a workflow-DAG
+            structural violation caught before semantic validation. The
+            `ErrorEnvelope.error` field carries a specific machine code (per
+            [`g8PPkbNu`](https://trello.com/c/g8PPkbNu) — narrower
+            DAG-validation codes; HTTP statuses unchanged, only the code
+            narrows). Conformance-safe: `error` is a free string (no enum).
+            - `WORKFLOW_EDGE_REFERENCES_UNKNOWN_JOB` — a `workflow_edges`
+              entry, a job-level `source`, or an `inputs[].source` references
+              a job `ref`/`id` not present in the request (one code across
+              all unknown-job-reference sites).
+            - `CYCLIC_JOB_OUTPUT_SOURCE_GRAPH` — an implicit cycle in the
+              `job_output` source graph, detected during effective-input-MIME
+              resolution (distinct from explicit `workflow_edges` cycles,
+              which are 422 `CYCLIC_WORKFLOW_EDGES`).
+            - `RESERVED_JOB_ID_PATTERN` — a user-supplied job `id` matches the
+              reserved `^job_\d+$` pattern **and is the SOLE validation
+              failure**; mixed-violation requests keep the aggregated generic
+              `BAD_REQUEST`.
+            - `BAD_REQUEST` — malformed JSON / generic body validation, or any
+              mixed/aggregated violation set.
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorEnvelope'
+              examples:
+                edge_references_unknown_job:
+                  summary: A workflow reference points at a job that does not exist
+                  value:
+                    success: false
+                    error: "WORKFLOW_EDGE_REFERENCES_UNKNOWN_JOB"
+                    message: "A workflow reference points at a job that does not exist."
+                    message_key: "error.workflow_edge_references_unknown_job"
+                reserved_job_id_pattern:
+                  summary: Sole violation — a job id uses the reserved pattern
+                  value:
+                    success: false
+                    error: "RESERVED_JOB_ID_PATTERN"
+                    message: "Job id must not use the reserved pattern (job_<number>)."
+                    message_key: "error.reserved_job_id_pattern"
+                cyclic_job_output_source_graph:
+                  summary: Implicit cycle in the job_output source graph
+                  value:
+                    success: false
+                    error: "CYCLIC_JOB_OUTPUT_SOURCE_GRAPH"
+                    message: "Job output sources form a cycle."
+                    message_key: "error.cyclic_job_output_source_graph"
+                bad_request_malformed:
+                  summary: Malformed JSON / generic or mixed-violation body
+                  value:
+                    success: false
+                    error: "BAD_REQUEST"
+                    message: "Invalid workflow request"
         '403':
           description: |
             Forbidden — tier-quota or feature-tier restriction. Discriminated
@@ -1482,10 +1547,19 @@ paths:
             Semantically invalid request. One of:
 
             - Generic validation error (unknown operation type, invalid
-              option combinations, cyclic dependency in workflow_edges,
-              multi-input job with multiple operations, source ref
-              pointing to a non-existent job) — returned as
-              `ValidationErrorEnvelope`. No `error_type` field.
+              option combinations, multi-input job with multiple
+              operations) — returned as `ValidationErrorEnvelope`
+              (`error_type: "validation_error"`, per ADR-0018).
+            - Cyclic explicit `workflow_edges` (a cycle or self-edge in the
+              edge DAG) — returned as a `ValidationErrorEnvelope` with
+              `error_type: "validation_error"`, `error:
+              "CYCLIC_WORKFLOW_EDGES"`, `message_key:
+              "error.cyclic_workflow_edges"`, and a `details[0].field =
+              "workflow_edges"` entry (per
+              [`g8PPkbNu`](https://trello.com/c/g8PPkbNu)). Implicit
+              `job_output` source-graph cycles and unknown-job references are
+              narrower **400** codes (`CYCLIC_JOB_OUTPUT_SOURCE_GRAPH` /
+              `WORKFLOW_EDGE_REFERENCES_UNKNOWN_JOB`) — see the 400 response.
             - Feature-availability violation (workflow references one or
               more `planned` / `experimental` / non-enabled-`beta`
               features) — returned as `FeatureNotAvailableResponse`
@@ -1523,29 +1597,34 @@ paths:
               or `always`. The compatibility-probe algorithm is
               server-side and deliberately opaque per plan v5 §F8.2.
 
-            Backward-compatibility note: the prior 422 shape
-            (`ValidationErrorEnvelope`) is preserved unchanged — its
-            `details[]` array is the structural signature consumers
-            duck-type against. `FeatureNotAvailableResponse` carries
-            `error_type: feature_not_available` + `violations[]`;
-            `ProcessingClassExceedsBandResponse` carries `error_type:
-            processing_class_exceeds_band` + `violations[]`.
-            `ProbePendingResponse` carries `error_type: probe_pending`
-            + `job_ref` (and NO `violations[]` / `details[]`), emitted
-            when the probe-pending gate is on and a job's upload has
-            not yet been probed. The `REQUIRES_REENCODE` flavour reuses
-            `ValidationErrorEnvelope`
-            (a user-fixable validation error in the same family as
-            `INVALID_OPTIONS`) and is distinguished by the stable
-            `error: "REQUIRES_REENCODE"` string code rather than a new
-            `error_type` enum value. Branches are distinguishable by
-            required-field shape (`details` vs `error_type` value), so
-            plain `oneOf` matches without a discriminator object — see
-            `openapi/api.yaml` §"FEATURE AVAILABILITY ENVELOPES"
-            commentary for the convention rationale (no discriminator
-            here because `ValidationErrorEnvelope` has no `error_type`
-            field; OpenAPI 3.1 discriminators require the property to
-            be present on every branch).
+            **Branch dispatch via the `error_type` discriminator** (per
+            [ADR-0018](../docs/decisions/0018-universal-422-error-type-discriminator.md)).
+            All four branches carry a required `error_type` enum, so the
+            `oneOf` declares an explicit `discriminator`
+            (`propertyName: error_type`):
+            - `validation_error` → `ValidationErrorEnvelope` (carries
+              `details[]`; the specific failure is in the `error` machine
+              code — `INVALID_OPTIONS`, `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.
+            - `feature_not_available` → `FeatureNotAvailableResponse`
+              (`violations[]`).
+            - `processing_class_exceeds_band` →
+              `ProcessingClassExceedsBandResponse` (`violations[]`).
+            - `probe_pending` → `ProbePendingResponse` (`job_ref`, no
+              `violations[]`/`details[]`), emitted when the probe-pending
+              gate is on and a job's upload has not yet been probed.
+
+            The prior 422 shape is otherwise preserved unchanged — the
+            `details[]` / `violations[]` / `job_ref` required-field shapes
+            still hold, so structural duck-typing keeps working; the
+            discriminator simply lets generated SDK clients dispatch on a
+            single property instead of mis-firing `instanceOf` guards
+            (camelCase-vs-snake_case). `error_type: validation_error` is a
+            **new required field** on `ValidationErrorEnvelope` — the
+            server populates it at every emission site (rollout coordinated
+            with the API per ADR-0018).
           headers:
             Retry-After:
               required: false
@@ -1569,11 +1648,19 @@ paths:
                   - $ref: '#/components/schemas/FeatureNotAvailableResponse'
                   - $ref: '#/components/schemas/ProcessingClassExceedsBandResponse'
                   - $ref: '#/components/schemas/ProbePendingResponse'
+                discriminator:
+                  propertyName: error_type
+                  mapping:
+                    validation_error: '#/components/schemas/ValidationErrorEnvelope'
+                    feature_not_available: '#/components/schemas/FeatureNotAvailableResponse'
+                    processing_class_exceeds_band: '#/components/schemas/ProcessingClassExceedsBandResponse'
+                    probe_pending: '#/components/schemas/ProbePendingResponse'
               examples:
                 validation_error:
                   summary: Generic validation error (legacy shape)
                   value:
                     success: false
+                    error_type: "validation_error"
                     error: "INVALID_OPTIONS"
                     details:
                       - operation: "compress"
@@ -1582,6 +1669,17 @@ paths:
                       - operation: "thumbnail"
                         option: "width"
                         message: "Required field"
+                cyclic_workflow_edges:
+                  summary: Cyclic or self-referential explicit workflow_edges (g8PPkbNu)
+                  value:
+                    success: false
+                    error_type: "validation_error"
+                    error: "CYCLIC_WORKFLOW_EDGES"
+                    message: "Workflow edges form a cycle."
+                    message_key: "error.cyclic_workflow_edges"
+                    details:
+                      - field: "workflow_edges"
+                        message: "Workflow edges form a cycle."
                 feature_not_available:
                   summary: Workflow references planned features
                   value:
@@ -1649,6 +1747,7 @@ paths:
                   summary: merge.video re_encode_mode=never with incompatible inputs (I16-CONS)
                   value:
                     success: false
+                    error_type: "validation_error"
                     error: "REQUIRES_REENCODE"
                     details:
                       - operation: "merge"
@@ -2185,7 +2284,7 @@ paths:
             still fresh. Strong-ETag comparison.
           schema:
             type: string
-          example: '"v2-pro-47"'
+          example: '"v2-pro-49"'
         - name: If-Modified-Since
           in: header
           required: false
@@ -2218,7 +2317,7 @@ paths:
                 Strong entity tag. Clients send `If-None-Match: <etag>`
                 on subsequent requests to revalidate; the server returns
                 `304 Not Modified` when the response is still fresh.
-              example: '"v2-pro-47"'
+              example: '"v2-pro-49"'
             Last-Modified:
               schema:
                 type: string
@@ -2236,7 +2335,7 @@ paths:
                   summary: Full schema (truncated for brevity)
                   value:
                     schema_version: "2.0.0"
-                    capabilities_version: 47
+                    capabilities_version: 49
                     generated_at: "2026-04-26T09:00:00Z"
                     user_tier: "pro"
                     operations:
@@ -2299,7 +2398,7 @@ paths:
             ETag:
               schema:
                 type: string
-              example: '"v2-pro-47"'
+              example: '"v2-pro-49"'
             Last-Modified:
               schema:
                 type: string
@@ -2779,6 +2878,11 @@ paths:
                 oneOf:
                   - $ref: '#/components/schemas/ValidationErrorEnvelope'
                   - $ref: '#/components/schemas/FeatureNotAvailableResponse'
+                discriminator:
+                  propertyName: error_type
+                  mapping:
+                    validation_error: '#/components/schemas/ValidationErrorEnvelope'
+                    feature_not_available: '#/components/schemas/FeatureNotAvailableResponse'
         '429':
           description: Rate limit exceeded
           content:
@@ -2891,6 +2995,11 @@ paths:
                 oneOf:
                   - $ref: '#/components/schemas/ValidationErrorEnvelope'
                   - $ref: '#/components/schemas/FeatureNotAvailableResponse'
+                discriminator:
+                  propertyName: error_type
+                  mapping:
+                    validation_error: '#/components/schemas/ValidationErrorEnvelope'
+                    feature_not_available: '#/components/schemas/FeatureNotAvailableResponse'
         '429':
           description: |
             Rate limit exceeded for decode requests. Decode
@@ -3017,7 +3126,10 @@ paths:
         - name: limit
           in: query
           required: false
-          description: Page size. Server may reject larger values with 400.
+          description: |
+            Page size. Server may reject invalid `limit` / `offset`
+            with `422 VALIDATION_FAILED` (per project-wide query-param
+            validation convention).
           schema:
             type: integer
             minimum: 1
@@ -3026,7 +3138,9 @@ paths:
         - name: offset
           in: query
           required: false
-          description: Page offset (zero-based).
+          description: |
+            Page offset (zero-based). Server may reject invalid
+            `limit` / `offset` with `422 VALIDATION_FAILED`.
           schema:
             type: integer
             minimum: 0
@@ -3149,21 +3263,34 @@ paths:
                       total: 47
                       limit: 20
                       offset: 0
-        '400':
-          description: Invalid pagination parameters (limit out of range, offset negative).
+        '401':
+          description: Authentication required.
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorEnvelope'
-              example:
-                success: false
-                error: "limit must be between 1 and 100"
-        '401':
-          description: Authentication required.
+        '422':
+          description: |
+            Invalid pagination parameters (`limit` out of range,
+            `offset` negative). Per the project-wide query-param
+            validation convention: the API runtime translates parameter
+            constraint violations into `ValidationErrorEnvelope` with
+            `error: "VALIDATION_FAILED"` and structured `details[]`
+            describing each rejected parameter. Replaces the prior
+            `400 ErrorEnvelope` shape — wire change landed via
+            [`gCfdFhdo`](https://trello.com/c/gCfdFhdo) on the API side
+            (contracts caught up via [`d4rJzTcU`](https://trello.com/c/d4rJzTcU)).
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ErrorEnvelope'
+                $ref: '#/components/schemas/ValidationErrorEnvelope'
+              example:
+                success: false
+                error_type: "validation_error"
+                error: "VALIDATION_FAILED"
+                details:
+                  - field: "limit"
+                    message: "limit must be between 1 and 100"
         '429':
           description: Rate limit exceeded
           content:
@@ -3420,10 +3547,13 @@ components:
           type: string
           description: |
             BCP 47 locale tag echoing the resolved `Content-Language`
-            response header value (e.g. `en-GB`, `pt-BR`, `ja-JP`).
-            Lets the SDK confirm which locale the server selected
-            when the request used q-value negotiation across multiple
-            `Accept-Language` values.
+            response header value. Currently always `en-GB` (the only
+            committed locale per `info.description` Localisation block
+            + ticket [`4GKyuYo6`](https://trello.com/c/4GKyuYo6));
+            additional values will appear here when their catalogs
+            ship. Lets the SDK confirm which locale the server
+            selected when the request used q-value negotiation across
+            multiple `Accept-Language` values.
           example: "en-GB"
         message_params:
           type: object
@@ -3455,11 +3585,30 @@ components:
       required:
         - success
         - error
+        - error_type
         - details
       properties:
         success:
           type: boolean
           enum: [false]
+        error_type:
+          type: string
+          enum:
+            - validation_error
+          description: |
+            Discriminator for the multi-branch 422 `oneOf` (per
+            [ADR-0018](../docs/decisions/0018-universal-422-error-type-discriminator.md)).
+            Always `validation_error` on this envelope. Added so the four
+            422 branches (`ValidationErrorEnvelope`,
+            `FeatureNotAvailableResponse`,
+            `ProcessingClassExceedsBandResponse`, `ProbePendingResponse`)
+            share a single discriminator property — generated SDK clients
+            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`,
+            `REQUIRES_REENCODE`, `CYCLIC_WORKFLOW_EDGES`, …) while
+            `error_type` only names the envelope shape.
         error:
           type: string
           description: |
@@ -3467,7 +3616,11 @@ components:
             (generic option/value validation failure), `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`).
+            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`).
             SDKs duck-type on this field for typed error-branch helpers.
         message:
           type: string
@@ -3538,6 +3691,26 @@ components:
                   `ErrorEnvelope.message_params`. Excludes cost
                   numbers.
 
+    ReEncodeDecision:
+      type: string
+      description: |
+        Path chosen for `merge.video` when `re_encode_mode=auto`.
+        Server reports the actual path so callers can see why
+        `auto` took the slow path. Absent for non-`merge.video`
+        operations and for `merge.video` when `re_encode_mode` is
+        `always` or `never` (path was caller-fixed). Per ticket
+        I16-CONS (Trello 7nCZXEru).
+
+        Mirrors the AsyncAPI `ReEncodeDecision` (and
+        `OperationMetrics.re_encode_decision`); exposed on the REST
+        `OperationResult.metrics` per ticket zS4e9CI2 so the SDK
+        customer path carries the same signal as the SSE/message
+        surface. Cross-spec enum parity is verified by
+        `tests/test_asyncapi_named_schemas.py`.
+      enum:
+        - stream_copy
+        - re_encode
+
     # ============================================
     # AVAILABILITY METADATA (decorative)
     # ============================================
@@ -4931,13 +5104,12 @@ components:
         with a generic schema error. This envelope is the structured
         rejection.
 
-        The 422 response is delivered alongside `ValidationErrorEnvelope`
-        and `ProcessingClassExceedsBandResponse` via a naked `oneOf`
-        (duck-typed on required-field shape — `details` vs `error_type`
-        value: `feature_not_available` vs `processing_class_exceeds_band`).
-        No discriminator object is used because `ValidationErrorEnvelope`
-        has no `error_type` field. See the 422 response on
-        `POST /api/workflows`.
+        The 422 response is delivered alongside `ValidationErrorEnvelope`,
+        `ProcessingClassExceedsBandResponse`, and `ProbePendingResponse`
+        via a `oneOf` with an explicit `error_type` discriminator (per
+        [ADR-0018](../docs/decisions/0018-universal-422-error-type-discriminator.md));
+        this branch's discriminator value is `feature_not_available`. See
+        the 422 response on `POST /api/workflows`.
       allOf:
         - $ref: '#/components/schemas/ErrorEnvelope'
         - type: object
@@ -4980,12 +5152,13 @@ components:
 
         Delivered alongside `ValidationErrorEnvelope`,
         `FeatureNotAvailableResponse`, and
-        `ProcessingClassExceedsBandResponse` via the naked `oneOf` on
-        the 422 response — duck-typed on required-field shape: this
-        branch is the only one carrying `error_type: probe_pending`
-        and it has neither `details` (ValidationErrorEnvelope) nor
-        `violations` (the other two typed envelopes), so it matches
-        exactly one branch.
+        `ProcessingClassExceedsBandResponse` via the discriminated
+        `oneOf` on the 422 response (per
+        [ADR-0018](../docs/decisions/0018-universal-422-error-type-discriminator.md)) —
+        this branch's `error_type` discriminator value is `probe_pending`;
+        it also remains the only branch carrying `job_ref` and neither
+        `details` (`ValidationErrorEnvelope`) nor `violations` (the other
+        two typed envelopes).
       allOf:
         - $ref: '#/components/schemas/ErrorEnvelope'
         - type: object
@@ -5181,10 +5354,12 @@ components:
         envelope is 422, not an extension of `TierRestrictionResponse`
         on 403).
 
-        Delivered on `POST /api/workflows` 422 in a naked `oneOf`
-        alongside `ValidationErrorEnvelope` and
-        `FeatureNotAvailableResponse` — branches distinguished by
-        required-field shape (`details` vs `error_type` value).
+        Delivered on `POST /api/workflows` 422 in a discriminated `oneOf`
+        alongside `ValidationErrorEnvelope`, `FeatureNotAvailableResponse`,
+        and `ProbePendingResponse` (per
+        [ADR-0018](../docs/decisions/0018-universal-422-error-type-discriminator.md)) —
+        this branch's `error_type` discriminator value is
+        `processing_class_exceeds_band`.
       allOf:
         - $ref: '#/components/schemas/ErrorEnvelope'
         - type: object
@@ -5405,19 +5580,21 @@ components:
         Available operation types:
         - compress: Reduce file size (images, audio, video, documents)
         - thumbnail: Legacy thumbnail value. Generates a preview image
-          for any media type via a single Lambda. Currently the only
-          thumbnail value the compression_api publisher emits; retirement
-          is planned after the publisher adopts the four sub-type values
-          below in a follow-up API PR.
+          for any media type via a single Lambda. Retained as a valid
+          routing target during the migration window, but the
+          compression_api publisher no longer emits it — it now resolves
+          the per-media sub-type value below on the SNS `operation_type`
+          attribute. The payload `operation_type` field stays `thumbnail`.
         - thumbnail_image: Image thumbnail sub-type. Backed by a dedicated
-          Rust image Lambda. Not yet emitted by the publisher.
+          Rust image Lambda. Emitted by the publisher for image inputs.
         - thumbnail_video: Video thumbnail sub-type. Backed by a dedicated
-          FFmpeg Lambda. Not yet emitted.
+          FFmpeg Lambda. Emitted by the publisher for video inputs.
         - thumbnail_document: PDF/EPUB thumbnail sub-type. Backed by a
-          dedicated Ghostscript Lambda. Not yet emitted.
+          dedicated Ghostscript Lambda. Emitted by the publisher for
+          PDF/EPUB inputs.
         - thumbnail_office: Office document (DOCX/XLSX/PPTX/ODT/ODS/ODP)
           thumbnail sub-type. Backed by a dedicated LibreOffice Lambda.
-          Not yet emitted.
+          Emitted by the publisher for office-document inputs.
         - image_watermark: Image overlay (file or external_source) onto a base IMAGE asset. Multi-input (Path B with role: base + overlay). Stable for static-image bases (jpeg/png/webp); animated GIF is advertised as `planned` via the `image_gif` mime_group — dispatch returns `feature_not_available` (422) until Lambda support ships. Video bases are NOT supported by image_watermark — use the dedicated `video_watermark` operation per ADR-0013. Per ADR-0004 + I4-CONS + I5 (Trello AKZiOXnd).
         - text_watermark: Text overlay rendered onto an image (Liberation Sans). Single-input. Per ADR-0004 + I4-CONS.
         - 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.
@@ -5426,10 +5603,10 @@ components:
         - 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).
         - 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_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`; dispatch returns `feature_not_available` (422) until Lambda ships. 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`; dispatch returns `feature_not_available` (422) until Lambda ships. Per ticket [`4NrRPCgh`](https://trello.com/c/4NrRPCgh) + ADR-0013.
+        - 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: beta` (Wave A — Lambda backend live; opt-in, MUST NOT return `feature_not_available`; may change with notice). 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: beta` (Wave A — Lambda backend live; opt-in, MUST NOT 422; `short_form` is beta, `long_form` stays `planned` — no live Fargate worker; `multi_overlay_stack` stays `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`; dispatch returns `feature_not_available` (422) until Lambda ships. 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: planned`; dispatch returns `feature_not_available` (422) until Lambda ships. 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` mime_group (worker live on staging — shape-stable + opt-in, MUST NOT 422); the `image_gif`, `document_pdf`, and `video` 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.
 
         Both the legacy `thumbnail` value and the four sub-type values
         are valid routing targets today during the thumbnail migration
@@ -6350,9 +6527,11 @@ components:
           text_watermark, convert).
         - `inputs[]` (multi-input): array of `JobInputV2` entries. Each entry
           carries its own `source` plus an optional `role`
-          (image_watermark, custom_luma, audio_overlay) and
+          (image_watermark, custom_luma, audio_overlay, audio_to_video,
+          video_watermark) and
           `per_input_options`. Used by multi-input operations (merge,
-          archive, image_watermark, custom_luma, audio_overlay).
+          archive, image_watermark, custom_luma, audio_overlay,
+          audio_to_video, video_watermark).
 
         Exactly one of `source` or `inputs` is required.
 
@@ -6415,7 +6594,8 @@ components:
           type: array
           description: |
             Multi-input list for `merge`, `archive`, `image_watermark`,
-            `custom_luma`, `audio_overlay`, and `audio_to_video`. Each
+            `custom_luma`, `audio_overlay`, `audio_to_video`, and
+            `video_watermark`. Each
             entry is a `JobInputV2` with its own `WorkflowSource`.
             Mutually exclusive with `source` — the V2 shape boundary
             stays `source` (single-input) XOR `inputs[]` (multi-input
@@ -6442,7 +6622,7 @@ components:
             Multi-input jobs (with `inputs[]`) must have exactly one
             operation, and it must be a multi-input type (`merge`,
             `archive`, `image_watermark`, `custom_luma`,
-            `audio_overlay`, or `audio_to_video`).
+            `audio_overlay`, `audio_to_video`, or `video_watermark`).
           items:
             $ref: '#/components/schemas/OperationDefinition'
         deliver:
@@ -6483,10 +6663,12 @@ components:
               `custom_luma` (joined via ticket
               [I29](https://trello.com/c/EPUE5Vs1) — `availability:
               planned` so workflow-create returns 422 until Lambda
-              ships), and `audio_overlay` (joined via ticket
+              ships), `audio_overlay` (joined via ticket
               [I19](https://trello.com/c/Xr3Z4GBF) — same `planned`
-              gating). The multi-input shape is contract-defined for
-              all entries.
+              gating), and `audio_to_video` + `video_watermark` (joined
+              via Wave A [`c3uthIP4`](https://trello.com/c/c3uthIP4) —
+              `availability: beta`, backends live). The multi-input
+              shape is contract-defined for all entries.
 
     JobInputV2:
       type: object
@@ -6631,8 +6813,19 @@ components:
             - explicit
           per_value_availability:
             terminal:    { availability: stable }
-            all_outputs: { availability: beta }
-            explicit:    { availability: beta }
+            all_outputs: { availability: planned }
+            explicit:    { availability: planned }
+          # Availability flipped beta → planned per ticket
+          # [`co0CERtJ`](https://trello.com/c/co0CERtJ) — the API
+          # runtime currently 422s every non-default `selection.type`
+          # with `feature_not_available`, which per the
+          # `info.description` availability taxonomy IS the `planned`
+          # behaviour (`stable`/`beta` MUST NOT 422). When the API
+          # threads the request-level `delivery.selection` shape, this
+          # flips back. Terminal stays `stable` because the runtime
+          # honours it as the implicit default (`DeliveryPlanComputer`
+          # computes terminal selection regardless of whether the
+          # caller supplied a `delivery` block).
         refs:
           type: array
           description: |
@@ -6659,7 +6852,20 @@ components:
       properties:
         mode:
           type: string
-          description: Delivery mode.
+          description: |
+            Delivery mode. `individual` is the only committed value
+            today (per ticket [`co0CERtJ`](https://trello.com/c/co0CERtJ)).
+            `bundle` and `both` are `planned`: the API runtime returns
+            `422 feature_not_available` for any non-`individual` value,
+            which per the `info.description` availability taxonomy is
+            the `planned` behaviour (`stable`/`beta` MUST NOT 422).
+
+            For workflows that need a packaged output today, compose
+            a terminal `archive` job whose `sources` are
+            `JobOutputSource` refs to the upstream jobs — `archive` is
+            the canonical output-bundler per ADR-0017. `delivery.mode:
+            bundle` is the deferred post-launch ergonomic sugar that
+            will reuse the same `archive` runtime under the hood.
           enum:
             - individual
             - bundle
@@ -6667,8 +6873,8 @@ components:
           default: individual
           per_value_availability:
             individual: { availability: stable }
-            bundle:     { availability: stable }
-            both:       { availability: beta }
+            bundle:     { availability: planned }
+            both:       { availability: planned }
         bundle_format:
           type: string
           enum:
@@ -6699,6 +6905,11 @@ components:
           description: |
             How to pick outputs. Default `terminal` (leaves only).
       example:
+        # Spec example uses `bundle` to document the deferred (planned)
+        # shape end-to-end — see Delivery.mode per_value_availability
+        # for the runtime state. For workflows that need packaged
+        # output today, compose a terminal `archive` job whose
+        # `sources` are `JobOutputSource` refs (ADR-0017).
         mode: bundle
         bundle_format: zip
         bundle_filename: "compressed-photos"
@@ -7068,12 +7279,22 @@ components:
           description: Container-reported duration (audio + video).
         width:
           type: integer
+          format: int64
           minimum: 1
-          description: Pixel width (image + video; best-effort document).
+          description: |
+            Pixel width (image + video; best-effort document). Declared
+            `int64` so Rust SDK generators emit `i64` instead of the
+            default `i32`; `i32` is fine for everything ffmpeg/libcaesium
+            handles today but the format hint keeps the door open for
+            scientific / RAW imagery without future SDK churn (per
+            ticket [`0sTmbUsc`](https://trello.com/c/0sTmbUsc)).
         height:
           type: integer
+          format: int64
           minimum: 1
-          description: Pixel height (image + video; best-effort document).
+          description: |
+            Pixel height (image + video; best-effort document). See
+            `width` for the `format: int64` rationale.
         codec:
           type: string
           description: |
@@ -7108,12 +7329,16 @@ components:
             `29.97`, `23.976`).
         bitrate_bps:
           type: integer
+          format: int64
           minimum: 0
           description: |
             Overall stream bitrate, **bits per second**. Units in
             the field name, mirroring `duration_seconds`, so SDKs
             avoid the kbps-vs-bps guessing trap. Container-reported
-            for video + audio.
+            for video + audio. Declared `int64` so Rust SDK
+            generators emit `i64` instead of `i32`; `i32` caps at
+            ~2.1 Gbps which is tight for future 4K/8K/RAW workloads
+            (per ticket [`0sTmbUsc`](https://trello.com/c/0sTmbUsc)).
         audio_layout:
           type: string
           description: |
@@ -7497,6 +7722,24 @@ components:
           $ref: '#/components/schemas/UuidV7'
         status:
           $ref: '#/components/schemas/JobStatus'
+        processing_class:
+          $ref: '#/components/schemas/ProcessingClass'
+          description: |
+            The logical processing class the server resolved this job to.
+            The status-poll echo of `WorkflowCreateResponse.processing_plan`
+            `.jobs[].processing_class` (`ProcessingPlanJob`) — same enum, same
+            per-job granularity — so consumers can observe the resolved
+            routing decision (`short_form` vs `long_form`, plus the merge-only
+            `*_concat` / `*_re_encode` aliases) after create, not just at
+            create time. The server always knows a job's class once the
+            workflow is resolved and populates this on every status response
+            (mirrors the `ProcessingPlanJob` invariant); it is left
+            schema-OPTIONAL rather than `required` only because `JobResponse`
+            is also embedded in the `WebhookPayload.workflow` callback payload,
+            where a required addition would be a breaking request-contract
+            change for existing webhook consumers. Per ticket
+            [F3dL0UKz](https://trello.com/c/F3dL0UKz); consumed by api
+            [D3yN1SGm](https://trello.com/c/D3yN1SGm).
         depends_on:
           type: array
           description: List of upstream job refs this job depends on
@@ -7574,6 +7817,21 @@ components:
             duration_ms:
               type: integer
               description: Processing time in milliseconds
+            re_encode_decision:
+              # Mirrors AsyncAPI OperationMetrics.re_encode_decision so the
+              # REST result surface (SDK customer path) carries the same
+              # merge.video stream-copy-vs-re-encode signal as the SSE/message
+              # channel. Per ticket zS4e9CI2 (unblocks e2e aDFI1FgT).
+              $ref: '#/components/schemas/ReEncodeDecision'
+            re_encode_reason:
+              type: string
+              description: |
+                Advisory explanation for `re_encode_decision` (e.g.
+                `all_inputs_compatible`, `explicit_always_mode`,
+                `input_codec_mismatch`, `input_framerate_mismatch`).
+                Free-form string — not an enum — so the Lambda can emit
+                human-readable diagnostics that evolve without contract
+                changes. Mirrors `OperationMetrics.re_encode_reason`.
 
     # ============================================
     # WORKFLOW DOWNLOAD SCHEMAS
@@ -7777,7 +8035,8 @@ components:
             Total number of inputs expected in this phase. Pairs with
             `phase_input_index`. For single-input operations this is
             `1` during the relevant phase; for multi-input merge /
-            archive / image_watermark / custom_luma / audio_overlay,
+            archive / image_watermark / custom_luma / audio_overlay /
+            audio_to_video / video_watermark,
             it matches the inputs[] count. Per ticket I27.
 
     SseOperationCompletedData:
@@ -8309,6 +8568,48 @@ components:
             either source.
           additionalProperties:
             $ref: '#/components/schemas/EndpointProjection'
+        workflow_features:
+          type: object
+          description: |
+            Workflow-level option availability projection (ticket
+            [`1ZQjSm0j`](https://trello.com/c/1ZQjSm0j)). Surfaces
+            `per_value_availability` for workflow-level options that live in
+            OpenAPI **component** schemas (not the per-operation
+            `schemas/operations/*.yaml` that drive the `operations` map),
+            keyed by REQUEST-shape path:
+            - `delivery.mode.per_value_availability` (from the `Delivery.mode`
+              schema)
+            - `delivery.selection.type.per_value_availability` (from the
+              `DeliverySelection.type` schema)
+
+            Closes the co0CERtJ (v2.19.0) authority-hierarchy gap: those
+            `planned` downgrades lived only in the (decorative per ADR-0001
+            §1.5) openapi component tags; this surfaces them in the
+            authoritative sidecar.
+
+            **Optional in the wire envelope** (same incremental-mirroring
+            stance as `endpoints`): the committed sidecar emits this block
+            authoritatively; the runtime `GET /api/operations/schema` MAY
+            mirror it once the API generator catches up. Consumers MUST
+            tolerate its absence from the runtime endpoint (read the sidecar)
+            and its presence from either source.
+          properties:
+            delivery:
+              type: object
+              properties:
+                mode:
+                  type: object
+                  properties:
+                    per_value_availability:
+                      $ref: '#/components/schemas/PerValueAvailability'
+                selection:
+                  type: object
+                  properties:
+                    type:
+                      type: object
+                      properties:
+                        per_value_availability:
+                          $ref: '#/components/schemas/PerValueAvailability'
 
     EndpointProjection:
       type: object
@@ -8584,6 +8885,22 @@ components:
             by `make check-per-value-availability` (CI guard, ticket
             [I17 `0gwtwCav`](https://trello.com/c/0gwtwCav)). Runtime
             emission lands with I3.
+        per_value_depends_on:
+          type: object
+          description: |
+            Per-enum-value cross-field constraint map, only meaningful
+            when `type: enum`. Keys MUST be a subset of `values[]`;
+            each entry value is a `depends_on`-shaped condition mapping
+            that the named enum value REQUIRES. Distinct from
+            option-level `depends_on` (which gates applicability with
+            silent-ignore semantics); `per_value_depends_on` rejects
+            the request with `invalid_options` when the named value is
+            chosen and the condition is not met. Verified by
+            `make check-per-value-depends-on` (CI guard, ticket
+            [`bsV3FWM5`](https://trello.com/c/bsV3FWM5)). Runtime
+            emission ships verbatim alongside other availability
+            metadata. See `schemas/FORMAT.md` §per_value_depends_on.
+          additionalProperties: true
         min:
           type: number
           description: Minimum value (for integer/float types)