@giveitsmaller/contracts 0.4.0 → 0.7.0

package/asyncapi/events.yaml

@@ -17,15 +17,21 @@ info:
       compression Lambda handles `compress` for exactly one media type.
     - **`gisl-{env}-{region}-operations`** — non-compression operations
       (thumbnail, image_watermark, text_watermark, merge, archive, convert,
-      custom_luma, audio_overlay, audio_watermark). Filter attribute:
-      `operation_type`. Subscriptions: one queue per operation type, plus four
-      thumbnail sub-type queues during the migration window. `custom_luma`,
-      `audio_overlay`, and `audio_watermark` are `availability: planned`
-      (per [I29](https://trello.com/c/EPUE5Vs1) +
+      custom_luma, audio_overlay, audio_watermark, audio_to_video,
+      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) +
       [I19](https://trello.com/c/Xr3Z4GBF) +
-      [I20](https://trello.com/c/omiCq7Vn)) — their queues are declared
-      but receive no traffic until Lambda ships. `audio_watermark`
-      additionally requires `enterprise` tier.
+      [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.
+      `audio_watermark` additionally requires `enterprise` tier.
 
     **Publisher branching rule** (implemented in `compression_api`'s
     `AwsSnsOperationPublisherAdapter` under Option A):
@@ -159,7 +165,7 @@ channels:
     address: gisl-{env}-{region}-operations
     description: |
       SNS topic where the API publishes **non-compression** operation
-      requests (thumbnail, image_watermark, text_watermark, merge, archive, convert, custom_luma, audio_overlay, audio_watermark). Filter
+      requests (thumbnail, image_watermark, text_watermark, merge, archive, convert, custom_luma, audio_overlay, audio_watermark, audio_to_video, video_watermark, video_text_watermark, split). Filter
       attribute: `operation_type` (single-attribute filter policy).
       Subscriptions fan out to per-operation-type queues, keyed by
       `operation_type` value.
@@ -184,6 +190,23 @@ channels:
         (gated by `availability: planned` until Lambda ships per
         [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)
+      - `operation_type = video_watermark` -> `ops-video-watermark`
+        queue (gated by `availability: planned` until Lambda ships per
+        [`4NrRPCgh`](https://trello.com/c/4NrRPCgh) — same gating)
+      - `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;
+        long-form video splits route via `processing_class` to the
+        `split-video-fargate` worker, same OperationType, different
+        worker)
       - `operation_type = audio_watermark` -> `ops-audio-watermark`
         queue (gated by `availability: planned` +
         `required_tier: enterprise` per
@@ -435,13 +458,15 @@ channels:
       (per JobInputV2.role). Backed by the operation-image-watermark
       Lambda (cross-repo X1 retirement target).
 
-      Stable today for image bases (jpeg/png/webp). Animated GIF and
-      video bases are advertised in `image_watermark.yaml` as `planned`
-      via parallel mime_groups (`image_gif`, `video` per I5 — Trello
-      AKZiOXnd); the publisher MAY route those `media_group` values to
-      this queue once Lambda support ships. Until then the API returns
-      `feature_not_available` (422) at workflow-create time and these
-      messages do not reach the queue. Per ADR-0004 + I4-CONS + I5.
+      Stable today for image bases (jpeg/png/webp). Animated GIF is
+      advertised in `image_watermark.yaml` as `planned` via the
+      `image_gif` mime_group (per I5 — Trello AKZiOXnd); the publisher
+      MAY route that `media_group` value to this queue once Lambda
+      support ships. Until then the API returns `feature_not_available`
+      (422) at workflow-create time and those messages do not reach the
+      queue. Video bases are NOT routed here — they go to
+      `ops-video-watermark` for the dedicated `video_watermark`
+      operation per ADR-0013. Per ADR-0004 + I4-CONS + I5 + ADR-0013.
     parameters:
       env:
         description: Environment (local, stg, prod)
@@ -578,6 +603,132 @@ channels:
       operationRequest:
         $ref: '#/components/messages/OperationRequestMessage'
 
+  opsAudioToVideo:
+    address: gisl-{env}-{region}-ops-audio-to-video
+    description: |
+      SQS queue for audio_to_video operations (produce video from an
+      audio input + optional still image overlay). Subscribed to the
+      `operations` SNS topic with filter
+      `operation_type = audio_to_video`. Multi-input role-based with
+      role asymmetry (Path B with `role: base` audio REQUIRED +
+      `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).
+
+      Per ADR-0004 + ADR-0015
+      ([`SlluxMBN`](https://trello.com/c/SlluxMBN)).
+    parameters:
+      env:
+        description: Environment (local, stg, prod)
+      region:
+        description: AWS region abbreviation (euw1, use1, etc.)
+    messages:
+      operationRequest:
+        $ref: '#/components/messages/OperationRequestMessage'
+
+  opsSplit:
+    address: gisl-{env}-{region}-ops-split
+    description: |
+      SQS queue for split operations (fan one input file into N
+      outputs across GIF / PDF / audio / video MIME families).
+      Subscribed to the `operations` SNS topic with filter
+      `operation_type = split`. Single-input — `media_group` derives
+      from the input MIME prefix per the existing single-input rule
+      (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
+      follow-up — lambdas pre-launch epic Wave A, ticket
+      [DbpJpVtm-sibling-L1](https://trello.com/c/vKI0CFDu)
+      [`vKI0CFDu`](https://trello.com/c/vKI0CFDu)).
+
+      **Long-form video splits** route to a separate
+      `split-video-fargate` worker via `processing_class` (same
+      OperationType, different worker — mirrors the
+      `compress` / `compress-video-fargate` topology). The schema
+      uses the standard processing_class short_form/long_form block
+      on the video mime_group; no schema-side discriminator beyond
+      MIME detection.
+
+      Per ADR-0004 + ADR-0014.
+    parameters:
+      env:
+        description: Environment (local, stg, prod)
+      region:
+        description: AWS region abbreviation (euw1, use1, etc.)
+    messages:
+      operationRequest:
+        $ref: '#/components/messages/OperationRequestMessage'
+
+  opsVideoWatermark:
+    address: gisl-{env}-{region}-ops-video-watermark
+    description: |
+      SQS queue for video_watermark operations (image overlay onto a
+      base video via FFmpeg's `overlay` filter). Subscribed to the
+      `operations` SNS topic with filter
+      `operation_type = video_watermark`. Multi-input role-based
+      (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
+      [DbpJpVtm](https://trello.com/c/DbpJpVtm)).
+
+      Distinct from `image_watermark` (pure-Rust image-only) — see
+      ADR-0013 for the split rationale. Audio stream-copy passthrough.
+
+      Per ADR-0004 + ADR-0013
+      ([`4NrRPCgh`](https://trello.com/c/4NrRPCgh)).
+    parameters:
+      env:
+        description: Environment (local, stg, prod)
+      region:
+        description: AWS region abbreviation (euw1, use1, etc.)
+    messages:
+      operationRequest:
+        $ref: '#/components/messages/OperationRequestMessage'
+
+  opsVideoTextWatermark:
+    address: gisl-{env}-{region}-ops-video-text-watermark
+    description: |
+      SQS queue for video_text_watermark operations (text overlay
+      onto a base video via FFmpeg's `drawtext` filter). Subscribed
+      to the `operations` SNS topic with filter
+      `operation_type = video_text_watermark`. Single-input — text
+      and styling come from options.
+
+      `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-text-watermark` Lambda
+      (cross-repo follow-up — lambdas pre-launch epic Wave A,
+      ticket [mQdunjv6](https://trello.com/c/mQdunjv6)).
+
+      Distinct from `text_watermark` (pure-Rust image drawtext) —
+      see ADR-0013. Audio stream-copy passthrough.
+
+      Per ADR-0004 + ADR-0013
+      ([`4NrRPCgh`](https://trello.com/c/4NrRPCgh)).
+    parameters:
+      env:
+        description: Environment (local, stg, prod)
+      region:
+        description: AWS region abbreviation (euw1, use1, etc.)
+    messages:
+      operationRequest:
+        $ref: '#/components/messages/OperationRequestMessage'
+
   opsAudioWatermark:
     address: gisl-{env}-{region}-ops-audio-watermark
     description: |
@@ -744,6 +895,62 @@ channels:
       region:
         description: AWS region abbreviation (euw1, use1, etc.)
 
+  opsAudioToVideoDlq:
+    address: gisl-{env}-{region}-ops-audio-to-video-dlq
+    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`.
+    parameters:
+      env:
+        description: Environment (local, stg, prod)
+      region:
+        description: AWS region abbreviation (euw1, use1, etc.)
+
+  opsVideoWatermarkDlq:
+    address: gisl-{env}-{region}-ops-video-watermark-dlq
+    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`.
+    parameters:
+      env:
+        description: Environment (local, stg, prod)
+      region:
+        description: AWS region abbreviation (euw1, use1, etc.)
+
+  opsVideoTextWatermarkDlq:
+    address: gisl-{env}-{region}-ops-video-text-watermark-dlq
+    description: |
+      DLQ for failed video_text_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_text_watermark is
+      `availability: planned`.
+    parameters:
+      env:
+        description: Environment (local, stg, prod)
+      region:
+        description: AWS region abbreviation (euw1, use1, etc.)
+
+  opsSplitDlq:
+    address: gisl-{env}-{region}-ops-split-dlq
+    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`.
+    parameters:
+      env:
+        description: Environment (local, stg, prod)
+      region:
+        description: AWS region abbreviation (euw1, use1, etc.)
+
   # ============================================
   # UPLOAD PROBE (per ticket vBlEurU7 + M2 Epic SrHwuvIl)
   # ============================================
@@ -944,7 +1151,8 @@ operations:
       operation where `operation_type != compress` — that is, thumbnail
       (including the four sub-type values during the migration window),
       image_watermark, text_watermark, merge, archive, convert,
-      custom_luma, audio_overlay, audio_watermark. The target SNS
+      custom_luma, audio_overlay, audio_watermark, audio_to_video,
+      video_watermark, video_text_watermark, split. The target SNS
       topic filters subscriptions on `operation_type` alone.
 
       **Message attributes set on this branch:** `{operation_type,
@@ -1187,6 +1395,85 @@ operations:
     messages:
       - $ref: '#/channels/opsAudioOverlay/messages/operationRequest'
 
+  consumeSplitOperation:
+    action: receive
+    channel:
+      $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 —
+      `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
+      `split-video-fargate` worker via `processing_class`.
+      Per ADR-0004 + ADR-0014
+      ([`vKI0CFDu`](https://trello.com/c/vKI0CFDu)).
+    messages:
+      - $ref: '#/channels/opsSplit/messages/operationRequest'
+
+  consumeVideoWatermarkOperation:
+    action: receive
+    channel:
+      $ref: '#/channels/opsVideoWatermark'
+    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
+      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.
+      Per ADR-0004 + ADR-0013
+      ([`4NrRPCgh`](https://trello.com/c/4NrRPCgh)).
+    messages:
+      - $ref: '#/channels/opsVideoWatermark/messages/operationRequest'
+
+  consumeVideoTextWatermarkOperation:
+    action: receive
+    channel:
+      $ref: '#/channels/opsVideoTextWatermark'
+    summary: Process video_text_watermark operation
+    description: |
+      The `operation-video-text-watermark` Lambda (cross-repo
+      follow-up — lambdas pre-launch epic Wave A, not yet shipped)
+      consumes video_text_watermark requests routed by
+      `operation_type=video_text_watermark`. Single-input — text
+      and styling come from options (no `role` field on the source
+      entry). `availability: planned`; the API rejects workflow-
+      create with `feature_not_available` (422) until the Lambda
+      ships, so traffic does not reach this channel today.
+      Per ADR-0004 + ADR-0013
+      ([`4NrRPCgh`](https://trello.com/c/4NrRPCgh)).
+    messages:
+      - $ref: '#/channels/opsVideoTextWatermark/messages/operationRequest'
+
+  consumeAudioToVideoOperation:
+    action: receive
+    channel:
+      $ref: '#/channels/opsAudioToVideo'
+    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
+      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.
+      Per ADR-0004 + ADR-0015
+      ([`SlluxMBN`](https://trello.com/c/SlluxMBN)).
+    messages:
+      - $ref: '#/channels/opsAudioToVideo/messages/operationRequest'
+
   consumeAudioWatermarkOperation:
     action: receive
     channel:
@@ -1401,17 +1688,19 @@ components:
         Message sent by the API to request processing of any
         **non-compression** operation (thumbnail, image_watermark,
         text_watermark, merge, archive, convert, custom_luma,
-        audio_overlay, audio_watermark). Published to the
-        `operations` SNS topic; routed by the single-attribute filter
-        `operation_type` to one of the ops-family queues.
+        audio_overlay, audio_watermark, audio_to_video,
+        video_watermark, video_text_watermark). Published to the
+        `operations` SNS topic; routed by the single-attribute
+        filter `operation_type` to one of the ops-family queues.
 
         **SNS Message Attributes:**
         - `operation_type`: always present. Values: `thumbnail`,
           `thumbnail_image`, `thumbnail_video`, `thumbnail_document`,
           `thumbnail_office`, `image_watermark`, `text_watermark`,
           `merge`, `archive`, `convert`, `custom_luma`,
-          `audio_overlay`, `audio_watermark`. Used by SNS as the
-          filter attribute on the `operations` topic.
+          `audio_overlay`, `audio_watermark`, `audio_to_video`,
+          `video_watermark`, `video_text_watermark`. 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
@@ -1430,12 +1719,17 @@ components:
           `required_tier: enterprise` so workflow-create rejects with
           422 + 403 today.
         - Multi-input operations (merge, archive, image_watermark,
-          custom_luma, audio_overlay): use `sources` array. Merge
-          additionally requires `output_type`. image_watermark,
-          custom_luma, and audio_overlay use `role` per
-          `JobInputV2.role`. custom_luma and audio_overlay are
-          `availability: planned` so workflow-create rejects with 422
-          today.
+          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`.
+          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.
 
         **Migration window note.** During the thumbnail sub-type
         migration, both `operation_type=thumbnail` (legacy) and
@@ -2151,6 +2445,14 @@ components:
           `required_tier: enterprise` per
           [I20](https://trello.com/c/omiCq7Vn), so this constraint is
           contract-defined but not exercised today.
+        - For `operation_type = audio_to_video`, `media_group` must
+          equal `audio` (derived from the `base` role input MIME
+          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.
         - 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`
@@ -2190,6 +2492,10 @@ components:
             - custom_luma
             - audio_overlay
             - audio_watermark
+            - audio_to_video
+            - video_watermark
+            - video_text_watermark
+            - split
         media_group:
           type: string
           description: |
@@ -2286,6 +2592,30 @@ components:
             properties:
               media_group:
                 const: document
+        - if:
+            properties:
+              operation_type:
+                const: audio_to_video
+          then:
+            properties:
+              media_group:
+                const: audio
+        - if:
+            properties:
+              operation_type:
+                const: video_watermark
+          then:
+            properties:
+              media_group:
+                const: video
+        - if:
+            properties:
+              operation_type:
+                const: video_text_watermark
+          then:
+            properties:
+              media_group:
+                const: video
 
     # ============================================
     # OPERATION REQUEST PAYLOAD SCHEMA (shared by both messages)
@@ -2304,10 +2634,11 @@ components:
         `file_type` is required.
 
         **Multi-input operations** (merge, archive, image_watermark,
-        custom_luma, audio_overlay): 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
+        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.
 
@@ -2331,6 +2662,8 @@ components:
                   - text_watermark
                   - convert
                   - audio_watermark
+                  - video_text_watermark
+                  - split
           then:
             required:
               - file_type
@@ -2339,7 +2672,7 @@ components:
         - if:
             properties:
               operation_type:
-                enum: [merge, archive, image_watermark, custom_luma, audio_overlay]
+                enum: [merge, archive, image_watermark, custom_luma, audio_overlay, audio_to_video, video_watermark]
           then:
             required:
               - sources
@@ -2404,16 +2737,24 @@ components:
           type: array
           description: |
             Input files for multi-input operations (merge, archive,
-            image_watermark, custom_luma, audio_overlay). Each entry
-            specifies an S3 location. Order matters for merge
-            (concatenation order). Per-input overrides (e.g.
-            transition) can be inlined on each entry.
+            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) require a `role` discriminator
-            on each entry — see `SourceEntry.role`.
+            custom_luma, audio_overlay, audio_to_video) 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
+            [`SlluxMBN`](https://trello.com/c/SlluxMBN) ADR-0015).
+            `audio_to_video` requires 1 source (`base` audio;
+            `overlay` optional, 0..1); all other role-based ops
+            require 2+ today. The schema floor here is `minItems: 1`
+            to admit the audio_to_video case.
           items:
             $ref: '#/components/schemas/SourceEntry'
-          minItems: 2
+          minItems: 1
 
         # Output
         output_bucket:
@@ -3413,6 +3754,51 @@ components:
           today. Pairs with `POST /api/audio-watermark/decode` for
           own-watermarks-only extraction. Per ADR-0004 + 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 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
+          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`.
+          Per ADR-0004 + ADR-0015 ([`SlluxMBN`](https://trello.com/c/SlluxMBN)).
+        - `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 { 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
+          `operation_type=video_watermark` to `ops-video-watermark`.
+          Per ADR-0004 + ADR-0013
+          ([`4NrRPCgh`](https://trello.com/c/4NrRPCgh)).
+        - `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.
+          Distinct from `text_watermark` (image-only drawtext path
+          — see ADR-0013). `availability: planned`; routes via
+          `operation_type=video_text_watermark` to
+          `ops-video-text-watermark`. Per ADR-0004 + ADR-0013.
+        - `split`: Fan one input file into N outputs across GIF /
+          PDF / audio / video MIME families. Single-input per-mime-
+          group catalog (mode discriminator for audio + video;
+          frame_range REQUIRED for GIF; page_range OR page_groups
+          for PDF). 200-output hard cap per ADR-0009 §D5; output
+          naming output-001..output-200. Long-form video routes to
+          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`.
+          Per ADR-0004 + ADR-0014
+          ([`vKI0CFDu`](https://trello.com/c/vKI0CFDu)).
       enum:
         - compress
         - thumbnail
@@ -3424,6 +3810,10 @@ components:
         - custom_luma
         - audio_overlay
         - audio_watermark
+        - audio_to_video
+        - video_watermark
+        - video_text_watermark
+        - split
 
     MediaGroup:
       type: string
@@ -3448,6 +3838,10 @@ components:
         - output_type=video -> video
         - output_type=audio -> audio
 
+        For multi-input role-based operations with role asymmetry
+        (audio_to_video), derived from the `base` role input MIME prefix
+        per ADR-0015 — audio_to_video always emits `media_group: audio`.
+
         Omitted from the SNS attributes for archive (media-agnostic). The
         four thumbnail sub-types map to media_group as follows:
         - thumbnail_image -> image
@@ -3489,6 +3883,22 @@ components:
         - `audio_overlay`: REQUIRED — exactly one `base` + one
           `overlay` per job (per ticket I19); reuses
           `image_watermark`'s role values.
+        - `audio_to_video`: REQUIRED `base` (audio source); OPTIONAL
+          `overlay` (still image, 0..1). FIRST role-based op with
+          an OPTIONAL role — see `per_role_cardinality` on the
+          operation schema for the machine-readable cardinality
+          declaration (per ticket
+          [`SlluxMBN`](https://trello.com/c/SlluxMBN) / ADR-0015).
+          Reuses `base` + `overlay` role values already declared
+          for `image_watermark` / `audio_overlay`.
+        - `video_watermark`: REQUIRED `base` (video source); REQUIRED
+          `overlay` (watermark image). Exactly one of each per
+          `per_role_cardinality { base: 1/1, overlay: 1/1 }`. First
+          non-introductory adoption of the `per_role_cardinality`
+          vocab (per ticket
+          [`4NrRPCgh`](https://trello.com/c/4NrRPCgh) / ADR-0013).
+          `video_text_watermark` is single-input (text in options;
+          no `role` field applies).
         - `merge` / `archive`: omit (all inputs share the same
           role). Future operations may widen this enum.
 
@@ -3496,7 +3906,11 @@ components:
         per ticket QokFw8VR. The OpenAPI side at `JobInputV2.role`
         remains an inline enum today — symmetric extraction tracked
         as a follow-up; value-set parity is verified by inspection
-        (both lists must remain identical).
+        (both lists must remain identical). The
+        `scripts/check-per-role-cardinality.py` anti-drift check
+        takes this AsyncAPI named enum as the authoritative source
+        for cardinality-key membership checks until the OpenAPI
+        side is extracted.
       enum:
         - base
         - overlay