@giveitsmaller/contracts 0.8.0 → 0.9.0

package/asyncapi/events.yaml

@@ -1,7 +1,7 @@
 asyncapi: 3.0.0
 info:
   title: GISL Compression Events
-  version: 3.3.0
+  version: 3.9.0
   description: |
     Asynchronous event contracts for the GISL (Give It Smaller) compression service.
 
@@ -21,16 +21,20 @@ info:
       video_watermark, video_text_watermark, split). Filter attribute:
       `operation_type`. Subscriptions: one queue per operation type,
       plus four thumbnail sub-type queues during the migration window.
-      `custom_luma`, `audio_overlay`, `audio_watermark`,
-      `audio_to_video`, `video_watermark`, `video_text_watermark`, and
-      `split` are `availability: planned` (per
-      [I29](https://trello.com/c/EPUE5Vs1) +
+      `custom_luma`, `audio_overlay`, `audio_watermark`, and
+      `video_text_watermark` are `availability: planned`
+      (per [I29](https://trello.com/c/EPUE5Vs1) +
       [I19](https://trello.com/c/Xr3Z4GBF) +
       [I20](https://trello.com/c/omiCq7Vn) +
-      [`SlluxMBN`](https://trello.com/c/SlluxMBN) +
-      [`4NrRPCgh`](https://trello.com/c/4NrRPCgh) +
-      [`vKI0CFDu`](https://trello.com/c/vKI0CFDu)) — their queues are
-      declared but receive no traffic until Lambda ships.
+      [`4NrRPCgh`](https://trello.com/c/4NrRPCgh)) — their queues are
+      declared but receive no traffic until Lambda ships. `split` is
+      `availability: beta` for its `audio` mime_group (worker live on
+      staging — [`vKI0CFDu`](https://trello.com/c/vKI0CFDu)); its
+      `image_gif`, `document_pdf`, and `video` mime_groups stay
+      `availability: planned`.
+      `audio_to_video` and `video_watermark` are `availability: beta`
+      (Wave A activation [`c3uthIP4`](https://trello.com/c/c3uthIP4) —
+      backends live; the API accepts + publishes, traffic flows).
       `audio_watermark` additionally requires `enterprise` tier.
 
     **Publisher branching rule** (implemented in `compression_api`'s
@@ -54,11 +58,13 @@ info:
     **Thumbnail migration window.** The terraform topology has both the
     legacy `ops-thumbnail` queue and four new sub-type queues
     (`ops-thumbnail-{image,video,document,office}`) live simultaneously.
-    The API publisher currently emits the legacy `operation_type=thumbnail`
-    only; adoption of the four sub-type values (`thumbnail_image`,
-    `thumbnail_video`, `thumbnail_document`, `thumbnail_office`) is a
-    follow-up API PR. Both routing targets are documented in this contract
-    because both are valid during the migration.
+    The API publisher emits the four sub-type values (`thumbnail_image`,
+    `thumbnail_video`, `thumbnail_document`, `thumbnail_office`) on the
+    SNS `operation_type` attribute, resolved from each operation's
+    effective input MIME; the legacy `operation_type=thumbnail` attribute
+    is retained as a valid routing target during the migration window but
+    is no longer emitted. Both routing targets are documented in this
+    contract because both remain valid during the migration.
 
     **Notifications (Lambda -> API).** Lambda functions publish progress
     and result notifications to the FIFO SNS topic
@@ -191,19 +197,23 @@ channels:
         [I19](https://trello.com/c/Xr3Z4GBF) — same `feature_not_
         available` 422 gating)
       - `operation_type = audio_to_video` -> `ops-audio-to-video` queue
-        (gated by `availability: planned` until Lambda ships per
-        [`SlluxMBN`](https://trello.com/c/SlluxMBN) — same
-        `feature_not_available` 422 gating)
+        (`availability: beta` — Wave A activated per
+        [`SlluxMBN`](https://trello.com/c/SlluxMBN) +
+        [`c3uthIP4`](https://trello.com/c/c3uthIP4); backend live, traffic
+        flows)
       - `operation_type = video_watermark` -> `ops-video-watermark`
-        queue (gated by `availability: planned` until Lambda ships per
-        [`4NrRPCgh`](https://trello.com/c/4NrRPCgh) — same gating)
+        queue (`availability: beta` — Wave A activated per
+        [`4NrRPCgh`](https://trello.com/c/4NrRPCgh) +
+        [`c3uthIP4`](https://trello.com/c/c3uthIP4); backend live)
       - `operation_type = video_text_watermark` ->
         `ops-video-text-watermark` queue (gated by
         `availability: planned` until Lambda ships per
         [`4NrRPCgh`](https://trello.com/c/4NrRPCgh) — same gating)
-      - `operation_type = split` -> `ops-split` queue (gated by
-        `availability: planned` until Lambda ships per
-        [`vKI0CFDu`](https://trello.com/c/vKI0CFDu) — same gating;
+      - `operation_type = split` -> `ops-split` queue (the `audio`
+        mime_group is `availability: beta` — audio split traffic
+        reaches this queue; `image_gif` / `document_pdf` / `video`
+        stay `availability: planned` until their Lambdas ship per
+        [`vKI0CFDu`](https://trello.com/c/vKI0CFDu);
         long-form video splits route via `processing_class` to the
         `split-video-fargate` worker, same OperationType, different
         worker)
@@ -223,9 +233,11 @@ channels:
 
       **Thumbnail migration window.** The legacy `ops-thumbnail` queue and
       the four sub-type queues are all live simultaneously. The API
-      publisher currently emits `operation_type=thumbnail` (legacy);
-      adoption of the four sub-type values is a follow-up API PR. Both
-      paths are valid routing targets today.
+      publisher emits the four sub-type values on the SNS `operation_type`
+      attribute (resolved from effective input MIME); the legacy
+      `operation_type=thumbnail` attribute is retained as a valid routing
+      target but is no longer emitted. Both paths are valid routing
+      targets today.
     parameters:
       env:
         description: Environment (local, stg, prod)
@@ -245,6 +257,12 @@ channels:
       SQS queue for image compression jobs.
       Subscribed to the `job-requests` SNS topic with filter
       `job_type = image`. Handles `compress` only for image inputs.
+    bindings:
+      sqs:
+        queue:
+          name: gisl-{env}-{region}-jobs-image
+          fifoQueue: false
+        bindingVersion: '0.2.0'
     parameters:
       env:
         description: Environment (local, stg, prod)
@@ -260,6 +278,12 @@ channels:
       SQS queue for video compression jobs.
       Subscribed to the `job-requests` SNS topic with filter
       `job_type = video`. Handles `compress` only for video inputs.
+    bindings:
+      sqs:
+        queue:
+          name: gisl-{env}-{region}-jobs-video
+          fifoQueue: false
+        bindingVersion: '0.2.0'
     parameters:
       env:
         description: Environment (local, stg, prod)
@@ -275,6 +299,12 @@ channels:
       SQS queue for audio compression jobs.
       Subscribed to the `job-requests` SNS topic with filter
       `job_type = audio`. Handles `compress` only for audio inputs.
+    bindings:
+      sqs:
+        queue:
+          name: gisl-{env}-{region}-jobs-audio
+          fifoQueue: false
+        bindingVersion: '0.2.0'
     parameters:
       env:
         description: Environment (local, stg, prod)
@@ -290,6 +320,12 @@ channels:
       SQS queue for document compression jobs.
       Subscribed to the `job-requests` SNS topic with filter
       `job_type = document`. Handles `compress` only for document inputs.
+    bindings:
+      sqs:
+        queue:
+          name: gisl-{env}-{region}-jobs-document
+          fifoQueue: false
+        bindingVersion: '0.2.0'
     parameters:
       env:
         description: Environment (local, stg, prod)
@@ -350,12 +386,14 @@ channels:
       Subscribed to the `operations` SNS topic with filter
       `operation_type = thumbnail`.
 
-      **Migration window**: This is the legacy routing target and is
-      currently the only one the API publisher emits for (via
-      `operation_type=thumbnail`). It handles thumbnail requests for all
-      media types. Retirement is planned after the API publisher adopts
-      the four sub-type values (`thumbnail_image`, `thumbnail_video`,
-      `thumbnail_document`, `thumbnail_office`) in a follow-up API PR.
+      **Migration window**: This is the legacy routing target. It is
+      retained as a valid routing target (via `operation_type=thumbnail`)
+      and handles thumbnail requests for all media types, but the API
+      publisher no longer emits it — the publisher now emits the four
+      sub-type values (`thumbnail_image`, `thumbnail_video`,
+      `thumbnail_document`, `thumbnail_office`), resolved from each
+      operation's effective input MIME. Retirement of this legacy queue
+      follows once no traffic remains.
     parameters:
       env:
         description: Environment (local, stg, prod)
@@ -373,9 +411,10 @@ channels:
       `operation_type = thumbnail_image`. Backed by the Rust image
       thumbnail Lambda (`operation-thumbnail-image`).
 
-      Not yet receiving traffic — the API publisher currently emits
-      `operation_type=thumbnail` (legacy) and will flip to
-      `thumbnail_image` after a follow-up API PR adds input-MIME dispatch.
+      Receives traffic for image inputs — the API publisher emits
+      `operation_type=thumbnail_image` on the SNS attribute (resolved from
+      the operation's effective input MIME); the payload `operation_type`
+      field stays `thumbnail`.
     parameters:
       env:
         description: Environment (local, stg, prod)
@@ -393,9 +432,10 @@ channels:
       `operation_type = thumbnail_video`. Backed by the FFmpeg video
       thumbnail Lambda (`operation-thumbnail-video`).
 
-      Not yet receiving traffic — the API publisher currently emits
-      `operation_type=thumbnail` (legacy) and will flip to
-      `thumbnail_video` after a follow-up API PR adds input-MIME dispatch.
+      Receives traffic for video inputs — the API publisher emits
+      `operation_type=thumbnail_video` on the SNS attribute (resolved from
+      the operation's effective input MIME); the payload `operation_type`
+      field stays `thumbnail`.
     parameters:
       env:
         description: Environment (local, stg, prod)
@@ -413,10 +453,10 @@ channels:
       `operation_type = thumbnail_document`. Backed by the Ghostscript
       document thumbnail Lambda (`operation-thumbnail-document`).
 
-      Not yet receiving traffic — the API publisher currently emits
-      `operation_type=thumbnail` (legacy) and will flip to
-      `thumbnail_document` after a follow-up API PR adds input-MIME
-      dispatch.
+      Receives traffic for PDF/EPUB inputs — the API publisher emits
+      `operation_type=thumbnail_document` on the SNS attribute (resolved
+      from the operation's effective input MIME); the payload
+      `operation_type` field stays `thumbnail`.
     parameters:
       env:
         description: Environment (local, stg, prod)
@@ -435,10 +475,10 @@ channels:
       `operation_type = thumbnail_office`. Backed by the LibreOffice
       thumbnail Lambda (`operation-thumbnail-office`).
 
-      Not yet receiving traffic — the API publisher currently emits
-      `operation_type=thumbnail` (legacy) and will flip to
-      `thumbnail_office` after a follow-up API PR adds input-MIME
-      dispatch.
+      Receives traffic for office-document inputs — the API publisher
+      emits `operation_type=thumbnail_office` on the SNS attribute
+      (resolved from the operation's effective input MIME); the payload
+      `operation_type` field stays `thumbnail`.
     parameters:
       env:
         description: Environment (local, stg, prod)
@@ -614,11 +654,11 @@ channels:
       `role: overlay` image OPTIONAL — see `per_role_cardinality`
       on the operation schema).
 
-      `availability: planned` per the operation schema; the API
-      rejects workflow-create with `feature_not_available` (422)
-      until the Lambda ships, so traffic does not reach this queue
-      today. Backed by the `operation-audio-to-video` Lambda
-      (cross-repo follow-up — lambdas pre-launch epic Wave A).
+      `availability: beta` per the operation schema (Wave A activated,
+      [`c3uthIP4`](https://trello.com/c/c3uthIP4)): the API accepts +
+      publishes, so traffic flows to this queue (MUST NOT 422). Backed
+      by the `operation-audio-to-video` Lambda (live; lambdas pre-launch
+      epic Wave A).
 
       Per ADR-0004 + ADR-0015
       ([`SlluxMBN`](https://trello.com/c/SlluxMBN)).
@@ -642,10 +682,12 @@ channels:
       (no operation-specific conditional needed in
       OperationRequestAttributes).
 
-      `availability: planned` per the operation schema; the API
-      rejects workflow-create with `feature_not_available` (422)
-      until the Lambda ships, so traffic does not reach this queue
-      today. Backed by the `operation-split` Lambda (cross-repo
+      `availability: beta` for the `audio` mime_group (worker live on
+      staging — audio split traffic reaches this queue); the
+      `image_gif`, `document_pdf`, and `video` mime_groups stay
+      `availability: planned`, and the API rejects their
+      workflow-create with `feature_not_available` (422) until those
+      Lambdas ship. Backed by the `operation-split` Lambda (cross-repo
       follow-up — lambdas pre-launch epic Wave A, ticket
       [DbpJpVtm-sibling-L1](https://trello.com/c/vKI0CFDu)
       [`vKI0CFDu`](https://trello.com/c/vKI0CFDu)).
@@ -678,11 +720,12 @@ channels:
       (Path B with `role: base` video + `role: overlay` image,
       exactly one of each per `per_role_cardinality`).
 
-      `availability: planned` per the operation schema; the API
-      rejects workflow-create with `feature_not_available` (422)
-      until the Lambda ships, so traffic does not reach this queue
-      today. Backed by the `operation-video-watermark` Lambda (cross-
-      repo follow-up — lambdas pre-launch epic Wave A, ticket
+      `availability: beta` per the operation schema (Wave A activated,
+      [`c3uthIP4`](https://trello.com/c/c3uthIP4)): the API accepts +
+      publishes, so traffic flows to this queue (MUST NOT 422). The
+      `short_form` processing class is beta; `long_form` stays planned
+      (no live Fargate worker). Backed by the `operation-video-watermark`
+      Lambda (live; lambdas pre-launch epic Wave A, ticket
       [DbpJpVtm](https://trello.com/c/DbpJpVtm)).
 
       Distinct from `image_watermark` (pure-Rust image-only) — see
@@ -900,9 +943,9 @@ channels:
     description: |
       DLQ for failed audio_to_video operations (per ticket
       [`SlluxMBN`](https://trello.com/c/SlluxMBN) / ADR-0015).
-      Messages land here after 5 failed processing attempts. No
-      traffic reaches this queue while audio_to_video is
-      `availability: planned`.
+      Messages land here after 5 failed processing attempts.
+      audio_to_video is `availability: beta` (Wave A activated) so
+      this queue now receives real failures.
     parameters:
       env:
         description: Environment (local, stg, prod)
@@ -914,9 +957,9 @@ channels:
     description: |
       DLQ for failed video_watermark operations (per ticket
       [`4NrRPCgh`](https://trello.com/c/4NrRPCgh) / ADR-0013).
-      Messages land here after 5 failed processing attempts. No
-      traffic reaches this queue while video_watermark is
-      `availability: planned`.
+      Messages land here after 5 failed processing attempts.
+      video_watermark is `availability: beta` (Wave A activated) so
+      this queue now receives real failures.
     parameters:
       env:
         description: Environment (local, stg, prod)
@@ -942,9 +985,10 @@ channels:
     description: |
       DLQ for failed split operations (per ticket
       [`vKI0CFDu`](https://trello.com/c/vKI0CFDu) / ADR-0014).
-      Messages land here after 5 failed processing attempts. No
-      traffic reaches this queue while split is `availability:
-      planned`.
+      Messages land here after 5 failed processing attempts. Live for
+      the `split` `audio` mime_group (now `availability: beta`); the
+      `image_gif`, `document_pdf`, and `video` groups stay
+      `availability: planned` and carry no traffic yet.
     parameters:
       env:
         description: Environment (local, stg, prod)
@@ -1308,9 +1352,10 @@ operations:
     description: |
       The legacy thumbnail Lambda consumes thumbnail requests routed
       by `operation_type=thumbnail`. Handles thumbnail generation for
-      all media types in a single Lambda. This is the current live
-      routing target for the API publisher; it will be retired after
-      the publisher adopts the four sub-type values.
+      all media types in a single Lambda. Retained as a valid routing
+      target during the migration window, but the API publisher no
+      longer emits `operation_type=thumbnail` (it emits the four
+      sub-type values); this queue is retired once no traffic remains.
     messages:
       - $ref: '#/channels/opsThumbnail/messages/operationRequest'
 
@@ -1322,7 +1367,7 @@ operations:
     description: |
       The image thumbnail Lambda consumes thumbnail requests routed by
       `operation_type=thumbnail_image`. Backed by a Rust image crate.
-      Not yet receiving traffic — see channel description.
+      Receives traffic for image inputs — see channel description.
     messages:
       - $ref: '#/channels/opsThumbnailImage/messages/operationRequest'
 
@@ -1333,8 +1378,8 @@ operations:
     summary: Process video thumbnail operation
     description: |
       The video thumbnail Lambda consumes thumbnail requests routed by
-      `operation_type=thumbnail_video`. Backed by FFmpeg. Not yet
-      receiving traffic — see channel description.
+      `operation_type=thumbnail_video`. Backed by FFmpeg. Receives
+      traffic for video inputs — see channel description.
     messages:
       - $ref: '#/channels/opsThumbnailVideo/messages/operationRequest'
 
@@ -1346,7 +1391,8 @@ operations:
     description: |
       The document (PDF/EPUB) thumbnail Lambda consumes thumbnail
       requests routed by `operation_type=thumbnail_document`. Backed by
-      Ghostscript. Not yet receiving traffic — see channel description.
+      Ghostscript. Receives traffic for PDF/EPUB inputs — see channel
+      description.
     messages:
       - $ref: '#/channels/opsThumbnailDocument/messages/operationRequest'
 
@@ -1358,8 +1404,8 @@ operations:
     description: |
       The office document (DOCX/XLSX/PPTX/ODT/ODS/ODP) thumbnail Lambda
       consumes thumbnail requests routed by
-      `operation_type=thumbnail_office`. Backed by LibreOffice. Not yet
-      receiving traffic — see channel description.
+      `operation_type=thumbnail_office`. Backed by LibreOffice. Receives
+      traffic for office-document inputs — see channel description.
     messages:
       - $ref: '#/channels/opsThumbnailOffice/messages/operationRequest'
 
@@ -1474,14 +1520,18 @@ operations:
       $ref: '#/channels/opsSplit'
     summary: Process split operation
     description: |
-      The `operation-split` Lambda (cross-repo follow-up — lambdas
-      pre-launch epic Wave A, not yet shipped) consumes split
-      requests routed by `operation_type=split`. Single-input —
+      The `operation-split` Lambda (lambdas pre-launch epic Wave A)
+      consumes split requests routed by `operation_type=split`. Its
+      `audio` path is live on staging (lambdas #161); the
+      `image_gif` / `document_pdf` / `video` workers remain a
+      cross-repo follow-up. Single-input —
       `media_group` derives from the input MIME prefix per the
-      existing single-input rule. `availability: planned`; the API
-      rejects workflow-create with `feature_not_available` (422)
-      until the Lambda ships, so traffic does not reach this channel
-      today. Long-form video splits route to a separate
+      existing single-input rule. `availability: beta` for the `audio`
+      mime_group (worker live on staging); the `image_gif`,
+      `document_pdf`, and `video` mime_groups stay `availability:
+      planned`, and the API rejects their workflow-create with
+      `feature_not_available` (422) until those Lambdas ship.
+      Long-form video splits route to a separate
       `split-video-fargate` worker via `processing_class`.
       Per ADR-0004 + ADR-0014
       ([`vKI0CFDu`](https://trello.com/c/vKI0CFDu)).
@@ -1495,14 +1545,14 @@ operations:
     summary: Process video_watermark operation
     description: |
       The `operation-video-watermark` Lambda (cross-repo follow-up —
-      lambdas pre-launch epic Wave A, not yet shipped) consumes
+      lambdas pre-launch epic Wave A, live) consumes
       video_watermark requests routed by
       `operation_type=video_watermark`. Multi-input role-based with
       `role: base` video + `role: overlay` image (exactly one of
-      each per `per_role_cardinality`). `availability: planned`; the
-      API rejects workflow-create with `feature_not_available` (422)
-      until the Lambda ships, so traffic does not reach this channel
-      today.
+      each per `per_role_cardinality`). `availability: beta` (Wave A
+      activated, [`c3uthIP4`](https://trello.com/c/c3uthIP4)): the API
+      accepts + publishes (MUST NOT 422), so traffic flows to this
+      channel. `short_form` is beta; `long_form` stays planned.
       Per ADR-0004 + ADR-0013
       ([`4NrRPCgh`](https://trello.com/c/4NrRPCgh)).
     messages:
@@ -1534,14 +1584,14 @@ operations:
     summary: Process audio_to_video operation
     description: |
       The `operation-audio-to-video` Lambda (cross-repo follow-up —
-      lambdas pre-launch epic Wave A, not yet shipped) consumes
+      lambdas pre-launch epic Wave A, live) consumes
       audio_to_video requests routed by
       `operation_type=audio_to_video`. Multi-input role-based with
       role asymmetry (Path B with `role: base` audio REQUIRED +
       `role: overlay` image OPTIONAL per `per_role_cardinality`).
-      `availability: planned`; the API rejects workflow-create with
-      `feature_not_available` (422) until the Lambda ships, so
-      traffic does not reach this channel today.
+      `availability: beta` (Wave A activated,
+      [`c3uthIP4`](https://trello.com/c/c3uthIP4)): the API accepts +
+      publishes (MUST NOT 422), so traffic flows to this channel.
       Per ADR-0004 + ADR-0015
       ([`SlluxMBN`](https://trello.com/c/SlluxMBN)).
     messages:
@@ -1820,7 +1870,7 @@ components:
         **non-compression** operation (thumbnail, image_watermark,
         text_watermark, merge, archive, convert, custom_luma,
         audio_overlay, audio_watermark, audio_to_video,
-        video_watermark, video_text_watermark). Published to the
+        video_watermark, video_text_watermark, split). Published to the
         `operations` SNS topic; routed by the single-attribute
         filter `operation_type` to one of the ops-family queues.
 
@@ -1830,8 +1880,8 @@ components:
           `thumbnail_office`, `image_watermark`, `text_watermark`,
           `merge`, `archive`, `convert`, `custom_luma`,
           `audio_overlay`, `audio_watermark`, `audio_to_video`,
-          `video_watermark`, `video_text_watermark`. Used by SNS as
-          the filter attribute on the `operations` topic.
+          `video_watermark`, `video_text_watermark`, `split`. Used by
+          SNS as the filter attribute on the `operations` topic.
         - `media_group`: informational metadata, present for every
           operation except `archive` (which is media-agnostic). Values:
           `image`, `video`, `audio`, `document`. **Not** used by SNS as
@@ -1840,7 +1890,8 @@ components:
 
         **Input models:**
         - Single-input operations (thumbnail, text_watermark, convert,
-          audio_watermark): use `source_bucket` + `source_key`.
+          audio_watermark, video_text_watermark, split): use
+          `source_bucket` + `source_key`.
           `file_type` required. For `thumbnail`, the SNS
           `operation_type` attribute is permitted to carry a per-media
           sub-type value for routing (see `OperationRequestAttributes`
@@ -1850,23 +1901,29 @@ components:
           `required_tier: enterprise` so workflow-create rejects with
           422 + 403 today.
         - Multi-input operations (merge, archive, image_watermark,
-          custom_luma, audio_overlay, audio_to_video): use `sources`
-          array. Merge additionally requires `output_type`.
-          image_watermark, custom_luma, audio_overlay, and
-          audio_to_video use `role` per `JobInputV2.role`.
+          custom_luma, audio_overlay, audio_to_video, video_watermark):
+          use `sources` array. Merge additionally requires `output_type`.
+          image_watermark, custom_luma, audio_overlay, audio_to_video,
+          and video_watermark use `role` per `JobInputV2.role`.
           audio_to_video has role asymmetry — REQUIRED `base` (audio)
           + OPTIONAL `overlay` (image 0..1) per
           `per_role_cardinality`; sum-of-role-minima drives the
           minimum `sources` count (1 for audio_to_video; 2 for all
-          other role-based ops today). custom_luma, audio_overlay,
-          and audio_to_video are `availability: planned` so
-          workflow-create rejects with 422 today.
+          other role-based ops today). custom_luma and audio_overlay
+          are `availability: planned` so workflow-create rejects with
+          422 today (audio_to_video and video_watermark are now `beta` —
+          Wave A activated).
 
         **Migration window note.** During the thumbnail sub-type
         migration, both `operation_type=thumbnail` (legacy) and
         `operation_type=thumbnail_{image,video,document,office}` (new)
-        are valid routing targets. The API publisher currently emits
-        the legacy value only; sub-type adoption is a follow-up API PR.
+        are valid routing targets. The API publisher emits the per-media
+        sub-type value on the SNS `operation_type` attribute (resolved
+        from the operation's effective input MIME); the payload
+        `operation_type` field always remains `thumbnail`. The legacy
+        bare `thumbnail` attribute value is retained as a valid routing
+        target during the migration window but is no longer emitted by
+        the publisher.
       contentType: application/json
       headers:
         $ref: '#/components/schemas/OperationRequestAttributes'
@@ -2623,9 +2680,10 @@ components:
           prefix per ADR-0015 — the operation is multi-input
           role-based with role asymmetry: required audio base +
           optional image overlay; routing follows the `base` role).
-          The operation is `availability: planned` per
-          [`SlluxMBN`](https://trello.com/c/SlluxMBN), so this
-          constraint is contract-defined but not exercised today.
+          The operation is `availability: beta` per
+          [`SlluxMBN`](https://trello.com/c/SlluxMBN) +
+          [`c3uthIP4`](https://trello.com/c/c3uthIP4) (Wave A activated),
+          so this constraint is exercised on live traffic.
         - For `operation_type = image_watermark`, `media_group` must
           equal `image` while only the stable `image` mime_group is
           dispatchable. The schema declares `image_gif` and `video`
@@ -2803,17 +2861,18 @@ components:
         API to SNS, consumed by Lambda from SQS.
 
         **Single-input operations** (compress, thumbnail, text_watermark,
-        convert): use `source_bucket` + `source_key` for the input file.
-        `file_type` is required.
+        convert, audio_watermark, video_text_watermark, split): use
+        `source_bucket` + `source_key` for the input file. `file_type` is
+        required.
 
         **Multi-input operations** (merge, archive, image_watermark,
-        custom_luma, audio_overlay, audio_to_video): use `sources`
-        array. Each entry has `bucket` + `key`. Merge entries may
-        include per-input overrides (e.g. transition type). Merge
-        also requires `output_type`. custom_luma, audio_overlay, and
-        audio_to_video are
-        `availability: planned` so workflow-create rejects with 422
-        today; the wire shape is contract-defined.
+        custom_luma, audio_overlay, audio_to_video, video_watermark):
+        use `sources` array. Each entry has `bucket` + `key`. Merge
+        entries may include per-input overrides (e.g. transition type).
+        Merge also requires `output_type`. custom_luma and audio_overlay
+        are `availability: planned` so workflow-create rejects with 422
+        today (audio_to_video + video_watermark are now `beta` — Wave A
+        activated, backends live); the wire shape is contract-defined.
 
         Note: `media_group` is **not** a field in this payload. It exists
         only as an SNS MessageAttribute on the non-compression branch; on
@@ -2911,12 +2970,13 @@ components:
           description: |
             Input files for multi-input operations (merge, archive,
             image_watermark, custom_luma, audio_overlay,
-            audio_to_video). Each entry specifies an S3 location.
-            Order matters for merge (concatenation order). Per-input
-            overrides (e.g. transition) can be inlined on each entry.
-            Role-based multi-input operations (image_watermark,
-            custom_luma, audio_overlay, audio_to_video) require a
-            `role` discriminator on each entry — see `SourceEntry.role`.
+            audio_to_video, video_watermark). Each entry specifies an
+            S3 location. Order matters for merge (concatenation order).
+            Per-input overrides (e.g. transition) can be inlined on each
+            entry. Role-based multi-input operations (image_watermark,
+            custom_luma, audio_overlay, audio_to_video, video_watermark)
+            require a `role` discriminator on each entry — see
+            `SourceEntry.role`.
 
             **Minimum source count = sum of role minima** declared in
             the operation's `per_role_cardinality` (per ticket
@@ -3036,30 +3096,16 @@ components:
           description: Unique operation identifier (UUID v7).
           example: "018f9c42-5d6b-7481-b3df-9fd0a0a5e200"
         operation_type:
-          type: string
-          enum:
-            - compress
-            - merge
-          description: |
-            Coarse operation verb for the long-form job. Deliberately a
-            call-site subset of `OperationType` — only the long-form classes
-            the API actually publishes today (`compress`, `merge`). NOT the
-            full `OperationType` enum (which would over-promise the wire).
+          $ref: '#/components/schemas/LongFormOperationType'
         processing_class:
-          type: string
-          const: long_form
-          description: |
-            Logical processing class — always the literal `long_form` on this
-            wire (never `short_form` / `blocked`; those exist only on the
-            upload-probe response and HTTP plan surfaces). The launcher forks
-            on this field; do not confuse it with the backend worker identity,
-            which stays off the wire per `schemas/FORMAT.md` §F8.
+          $ref: '#/components/schemas/LongFormProcessingClass'
 
     SourceEntry:
       type: object
       description: |
         A single source file for multi-input operations (merge,
-        archive, image_watermark, custom_luma, audio_overlay).
+        archive, image_watermark, custom_luma, audio_overlay,
+        audio_to_video, video_watermark).
         Provides the S3 location, optional per-input overrides, and
         the `role` discriminator for role-based multi-input
         operations.
@@ -3082,9 +3128,52 @@ components:
         transition:
           type: string
           description: |
-            Per-input transition override for video merge.
-            Overrides the global transition option for the join point before this input.
+            Per-input transition override for the join point before this
+            input. Applies to both video and audio merge — see the
+            per-media per-input transition catalogs in
+            `schemas/operations/merge.yaml`
+            (`merge.video.per_input_options` / `merge.audio.per_input_options`),
+            which the API validates against. Overrides the global
+            `options.transition` for this join point.
           example: "none"
+        crossfade_duration:
+          type: number
+          minimum: 0
+          maximum: 10.0
+          description: |
+            Per-input crossfade duration override, in seconds, for the
+            join point before this input. Overrides the global
+            `options.crossfade_duration` for this join point. Per the
+            `depends_on` on `merge.*.per_input_options.crossfade_duration`
+            (which resolves against the sibling per-input option, see
+            FORMAT.md), this takes effect only when this input's own
+            `transition` override is `crossfade` — pair it with
+            `transition: crossfade` on the same entry; it does NOT key off
+            the global `options.transition`. Mirrors
+            `merge.*.per_input_options.crossfade_duration` in
+            `schemas/operations/merge.yaml` — the API validates this
+            per-input value but, until this slot existed, dropped it at the
+            wire boundary (the slot lets the merge Lambda's audio path
+            honour it). The 0–10s bound here is a broad transport envelope;
+            the effective per-media limits (video crossfade `0.1`–`5.0`,
+            audio `0`–`10`) are enforced by the per-mime-group
+            operation-options schema in `merge.yaml`, which the API
+            validates against before publishing.
+          example: 1.0
+        gap_duration:
+          type: number
+          minimum: 0
+          maximum: 10.0
+          description: |
+            Per-input silence/gap duration override, in seconds, inserted
+            before this input at the join point. Overrides the global
+            `options.gap_duration` for this join point. Mirrors
+            `merge.audio.per_input_options.gap_duration` in
+            `schemas/operations/merge.yaml` (no transition dependency) —
+            added alongside `crossfade_duration` so the API does not
+            silently drop this sibling per-input audio override at the wire
+            boundary.
+          example: 0.5
 
     # ============================================
     # OPERATION PROGRESS SCHEMA
@@ -3151,8 +3240,9 @@ components:
             `phase_input_index`. For single-input operations (most
             ops) `phase_total_inputs: 1` and `phase_input_index: 1`
             during the relevant phase. For multi-input merge,
-            archive, image_watermark, custom_luma, and audio_overlay,
-            this matches the inputs[] count. Per ticket I27.
+            archive, image_watermark, custom_luma, audio_overlay,
+            audio_to_video, and video_watermark, this matches the
+            inputs[] count. Per ticket I27.
           example: 4
 
     # ============================================
@@ -4033,10 +4123,10 @@ components:
           the first OPTIONAL role on the contract — `role: base`
           audio required, `role: overlay` image 0..1 per
           `per_role_cardinality`). When overlay is omitted, the video
-          uses a solid background colour. `availability: planned` per
-          the operation schema; the API rejects workflow-create with
-          `feature_not_available` (422) until the Lambda ships, so
-          traffic does not reach SNS today. `media_group` is derived
+          uses a solid background colour. `availability: beta` (Wave A,
+          [`c3uthIP4`](https://trello.com/c/c3uthIP4)) — the Lambda
+          backend is live, so the API accepts + publishes (MUST NOT 422);
+          traffic flows to SNS. `media_group` is derived
           from the `base` role input MIME prefix per ADR-0015 (always
           `audio` for audio_to_video). Routes via
           `operation_type=audio_to_video` to `ops-audio-to-video`.
@@ -4047,7 +4137,9 @@ components:
           of each per `per_role_cardinality { base: 1/1, overlay:
           1/1 }`). Re-encode required; audio stream-copy passthrough.
           Distinct from `image_watermark` (pure-Rust/image-only —
-          see ADR-0013). `availability: planned`; routes via
+          see ADR-0013). `availability: beta` (Wave A, `c3uthIP4` —
+          Lambda backend live; `short_form` beta, `long_form` stays
+          `planned`); routes via
           `operation_type=video_watermark` to `ops-video-watermark`.
           Per ADR-0004 + ADR-0013
           ([`4NrRPCgh`](https://trello.com/c/4NrRPCgh)).
@@ -4069,8 +4161,10 @@ components:
           a separate `split-video-fargate` worker via
           `processing_class`. `media_group` derives from the input
           MIME prefix per the existing single-input rule (no
-          operation-specific conditional needed). `availability:
-          planned`; routes via `operation_type=split` to `ops-split`.
+          operation-specific conditional needed). `availability: beta`
+          for the `audio` mime_group (`image_gif` / `document_pdf` /
+          `video` stay `planned`); routes via `operation_type=split`
+          to `ops-split`.
           Per ADR-0004 + ADR-0014
           ([`vKI0CFDu`](https://trello.com/c/vKI0CFDu)).
       enum:
@@ -4208,6 +4302,47 @@ components:
         - stream_copy
         - re_encode
 
+    LongFormOperationType:
+      type: string
+      description: |
+        Coarse operation verb for the long-form claim-check job
+        (`LongFormJobMessage.operation_type`). Deliberately a call-site
+        **subset** of `OperationType` — only the long-form classes the API
+        actually publishes today (`compress`, `merge`). NOT the full
+        `OperationType` enum (which would over-promise the wire). Future
+        long-form publishers (e.g. `split` per
+        [`rcwvUKhI`](https://trello.com/c/rcwvUKhI)) widen this enum when
+        they ship.
+
+        Named-schema form lifted from inline at
+        `LongFormJobMessage.operation_type` per ticket
+        [`A3DyuYUd`](https://trello.com/c/A3DyuYUd) — generated SDK bindings
+        emit a stable typed name instead of an `AnonymousSchema_N`
+        placeholder.
+      enum:
+        - compress
+        - merge
+
+    LongFormProcessingClass:
+      type: string
+      description: |
+        Logical processing class on the long-form claim-check wire
+        (`LongFormJobMessage.processing_class`) — always the literal
+        `long_form` (never `short_form` / `blocked`; those exist only on the
+        upload-probe response and HTTP plan surfaces). The launcher forks on
+        this field; do not confuse it with the backend worker identity, which
+        stays off the wire per `schemas/FORMAT.md` §F8.
+
+        A single-value enum (not a JSON-Schema `const`): named + `enum` is the
+        repo's proven typed-codegen form (mirrors `JobInputRole` /
+        `ReEncodeDecision`), whereas `const` degraded to an unconstrained
+        `String` in SDK generators. Lifted from inline at
+        `LongFormJobMessage.processing_class` per ticket
+        [`A3DyuYUd`](https://trello.com/c/A3DyuYUd). Single-member enum
+        validates identically to the prior `const long_form`.
+      enum:
+        - long_form
+
     ProgressStatus:
       type: string
       description: |