@giveitsmaller/contracts 0.8.0 → 0.9.0

package/openapi/api.yaml

@@ -89,7 +89,7 @@ info:
     of truth instead of hardcoding magic numbers. A runtime
     `GET /api/uploads/limits` endpoint for dynamic discovery
     (per-tier / per-environment overrides) is a deferred follow-up.
-  version: 2.21.0
+  version: 2.31.0
   contact:
     name: API Support
 
@@ -1146,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.
@@ -1184,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.
 
@@ -1393,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
@@ -1496,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`
@@ -1537,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
@@ -1583,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"
@@ -1596,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:
@@ -1663,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"
@@ -2793,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:
@@ -2905,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
@@ -3191,6 +3286,7 @@ paths:
                 $ref: '#/components/schemas/ValidationErrorEnvelope'
               example:
                 success: false
+                error_type: "validation_error"
                 error: "VALIDATION_FAILED"
                 details:
                   - field: "limit"
@@ -3489,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: |
@@ -3502,9 +3617,10 @@ components:
             (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`),
-            `VALIDATION_FAILED` (request/query-param validation failure
-            per the project-wide convention — e.g. `GET /api/v2/credits/usage`
-            invalid `limit`/`offset`).
+            `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
@@ -4988,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
@@ -5037,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
@@ -5238,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
@@ -5462,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.
@@ -5483,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
@@ -6407,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.
 
@@ -6472,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
@@ -6499,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:
@@ -6540,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
@@ -7597,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
@@ -7892,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:
@@ -8424,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

package/operations/schemas/audio_to_video.yaml

@@ -2,7 +2,7 @@ schema_version: "2.0.0"
 
 operation:
   type: audio_to_video
-  availability: planned
+  availability: beta
   description: |
     Produce a video from an audio input plus an OPTIONAL still image
     overlay. Use cases: podcast → YouTube uploads, audio-only tracks
@@ -29,9 +29,11 @@ operation:
     tiny when the overlay is a still image (the common case).
 
     Per ticket [`SlluxMBN`](https://trello.com/c/SlluxMBN) +
-    ADR-0015. `availability: planned` until the cross-repo Lambda
-    support ships; the API rejects workflow-create with
-    `feature_not_available` (422) until then.
+    ADR-0015. Activated to `availability: beta` (Wave A, ticket
+    [`c3uthIP4`](https://trello.com/c/c3uthIP4)): the cross-repo
+    Lambda backend is live (API accepts + publishes), so this is
+    shape-stable + opt-in for callers and MUST NOT return
+    `feature_not_available` — it may still change with notice while beta.
 
   default: false
   input_model: multi

package/operations/schemas/custom_luma.yaml

@@ -12,10 +12,9 @@ operation:
 
     **NOT** related to FFmpeg's `xfade=custom` filter (which is an
     expression-mode parameter on the same `xfade` filter). The
-    `merge.transition.custom` value is tagged `planned` with
-    documentation_url pointing at this operation; once `custom_luma`
-    ships, the merge slot is repurposed to a "use the dedicated
-    `custom_luma` operation instead" advisory.
+    `merge.transition.custom` value is tagged `planned` as an advisory
+    that points callers at this dedicated operation for caller-uploaded
+    luma-matte transitions.
 
     Multi-input: exactly one input with `role: base` (the source
     video being transitioned) + exactly one input with

package/operations/schemas/merge.yaml

@@ -106,11 +106,11 @@ operation:
             # `custom` is `planned` indefinitely as an advisory — for
             # caller-uploaded luma-matte transitions, use the dedicated
             # `custom_luma` operation (multi-input with role: base +
-            # transition_mask) per ticket I29 (EPUE5Vs1). FFmpeg's
+            # transition_mask). FFmpeg's
             # xfade=custom is an expression-mode parameter, not the
             # shape callers want; the dedicated operation is the
             # supported path.
-            custom:       { availability: planned, documentation_url: "https://trello.com/c/EPUE5Vs1" }
+            custom:       { availability: planned }
             wipetl:       { availability: planned, eta: "2026-Q3" }
             wipetr:       { availability: planned, eta: "2026-Q3" }
             wipebl:       { availability: planned, eta: "2026-Q3" }
@@ -212,11 +212,11 @@ operation:
             # `custom` is `planned` indefinitely as an advisory — for
             # caller-uploaded luma-matte transitions, use the dedicated
             # `custom_luma` operation (multi-input with role: base +
-            # transition_mask) per ticket I29 (EPUE5Vs1). FFmpeg's
+            # transition_mask). FFmpeg's
             # xfade=custom is an expression-mode parameter, not the
             # shape callers want; the dedicated operation is the
             # supported path.
-            custom:       { availability: planned, documentation_url: "https://trello.com/c/EPUE5Vs1" }
+            custom:       { availability: planned }
             wipetl:       { availability: planned, eta: "2026-Q3" }
             wipetr:       { availability: planned, eta: "2026-Q3" }
             wipebl:       { availability: planned, eta: "2026-Q3" }
@@ -359,11 +359,11 @@ operation:
             # `custom` is `planned` indefinitely as an advisory — for
             # caller-uploaded luma-matte transitions, use the dedicated
             # `custom_luma` operation (multi-input with role: base +
-            # transition_mask) per ticket I29 (EPUE5Vs1). FFmpeg's
+            # transition_mask). FFmpeg's
             # xfade=custom is an expression-mode parameter, not the
             # shape callers want; the dedicated operation is the
             # supported path.
-            custom:       { availability: planned, documentation_url: "https://trello.com/c/EPUE5Vs1" }
+            custom:       { availability: planned }
             wipetl:       { availability: planned, eta: "2026-Q3" }
             wipetr:       { availability: planned, eta: "2026-Q3" }
             wipebl:       { availability: planned, eta: "2026-Q3" }