@giveitsmaller/contracts 0.2.3 → 0.3.0

package/asyncapi/events.yaml

@@ -1,7 +1,7 @@
 asyncapi: 3.0.0
 info:
   title: GISL Compression Events
-  version: 3.0.0
+  version: 3.2.0
   description: |
     Asynchronous event contracts for the GISL (Give It Smaller) compression service.
 
@@ -16,9 +16,16 @@ info:
       (`jobs-image`, `jobs-video`, `jobs-audio`, `jobs-document`). Each
       compression Lambda handles `compress` for exactly one media type.
     - **`gisl-{env}-{region}-operations`** — non-compression operations
-      (thumbnail, watermark, merge, archive, convert). Filter attribute:
+      (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.
+      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) +
+      [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.
 
     **Publisher branching rule** (implemented in `compression_api`'s
     `AwsSnsOperationPublisherAdapter` under Option A):
@@ -64,8 +71,13 @@ info:
       `operation-thumbnail` (legacy, retiring after migration),
       `operation-thumbnail-image`, `operation-thumbnail-video`,
       `operation-thumbnail-document`, `operation-thumbnail-office`,
-      `operation-watermark`, `operation-merge`, `operation-archive`,
-      `operation-convert`.
+      `operation-image-watermark`, `operation-text-watermark`,
+      `operation-merge`, `operation-archive`,
+      `operation-convert`,
+      `operation-custom-luma` (planned per ticket I29 — not yet shipped),
+      `operation-audio-overlay` (planned per ticket I19 — not yet shipped),
+      `operation-audio-watermark` (planned per ticket I20 —
+      enterprise-tier; not yet shipped).
 
     **Message Types**
 
@@ -81,6 +93,22 @@ info:
     and `OperationRequestAttributes`) so each topic's required attributes can
     be enforced cleanly without conditional discriminators.
 
+    **Availability metadata.**
+
+    This spec uses the `x-availability` vendor extension as **decorative
+    documentation only**. Per [ADR-0001](../docs/decisions/0001-contract-first-availability.md)
+    §1.5, the runtime endpoint `GET /api/operations/schema` (ticket I3) is
+    the authoritative source; the sidecar `availability.json` (ticket I3b)
+    is the authoritative companion. SDKs MUST NOT depend on
+    `x-availability` reaching generated code — consumers read availability
+    from the runtime endpoint, not from the generated bindings.
+
+    The 5-value vocabulary (`stable | beta | experimental | planned |
+    deprecated`) is defined in the `AvailabilityValue` schema. See
+    `schemas/FORMAT.md` §Availability Taxonomy for operational rules
+    (parser obligation: absent = stable; per-enum-value granularity lands
+    via ticket I17 `per_value_availability` primitive).
+
 servers:
   local:
     host: localhost:4566
@@ -131,7 +159,7 @@ channels:
     address: gisl-{env}-{region}-operations
     description: |
       SNS topic where the API publishes **non-compression** operation
-      requests (thumbnail, watermark, merge, archive, convert). Filter
+      requests (thumbnail, image_watermark, text_watermark, merge, archive, convert, custom_luma, audio_overlay, audio_watermark). Filter
       attribute: `operation_type` (single-attribute filter policy).
       Subscriptions fan out to per-operation-type queues, keyed by
       `operation_type` value.
@@ -142,10 +170,25 @@ channels:
       - `operation_type = thumbnail_video` -> `ops-thumbnail-video` queue
       - `operation_type = thumbnail_document` -> `ops-thumbnail-document` queue
       - `operation_type = thumbnail_office` -> `ops-thumbnail-office` queue
-      - `operation_type = watermark` -> `ops-watermark` queue
+      - `operation_type = image_watermark` -> `ops-image-watermark` queue
+      - `operation_type = text_watermark` -> `ops-text-watermark` queue
       - `operation_type = merge` -> `ops-merge` queue
       - `operation_type = archive` -> `ops-archive` queue
       - `operation_type = convert` -> `ops-convert` queue
+      - `operation_type = custom_luma` -> `ops-custom-luma` queue (gated
+        by `availability: planned` until Lambda ships per
+        [I29](https://trello.com/c/EPUE5Vs1) — API rejects workflow-
+        create with `feature_not_available` (422) so no traffic reaches
+        the topic today)
+      - `operation_type = audio_overlay` -> `ops-audio-overlay` queue
+        (gated by `availability: planned` until Lambda ships per
+        [I19](https://trello.com/c/Xr3Z4GBF) — same `feature_not_
+        available` 422 gating)
+      - `operation_type = audio_watermark` -> `ops-audio-watermark`
+        queue (gated by `availability: planned` +
+        `required_tier: enterprise` per
+        [I20](https://trello.com/c/omiCq7Vn) — same 422 gating, plus
+        a 403 `feature_tier_restricted` for non-enterprise callers)
 
       The API's Option A publisher sets `operation_type` as the filter
       attribute and additionally sets `media_group` as an **informational**
@@ -382,14 +425,41 @@ channels:
       operationRequest:
         $ref: '#/components/messages/OperationRequestMessage'
 
-  opsWatermark:
-    address: gisl-{env}-{region}-ops-watermark
+  opsImageWatermark:
+    address: gisl-{env}-{region}-ops-image-watermark
+    description: |
+      SQS queue for image_watermark operations (multi-input).
+      Subscribed to the `operations` SNS topic with filter
+      `operation_type = image_watermark`. Handles image-overlay
+      watermarking with one `base` input + one `overlay` input
+      (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.
+    parameters:
+      env:
+        description: Environment (local, stg, prod)
+      region:
+        description: AWS region abbreviation (euw1, use1, etc.)
+    messages:
+      operationRequest:
+        $ref: '#/components/messages/OperationRequestMessage'
+
+  opsTextWatermark:
+    address: gisl-{env}-{region}-ops-text-watermark
     description: |
-      SQS queue for watermark operations (image-only).
+      SQS queue for text_watermark operations (single-input, image-only).
       Subscribed to the `operations` SNS topic with filter
-      `operation_type = watermark`. Handles image-overlay and text-overlay
-      watermark modes on image inputs. Backed by the watermark Lambda
-      (`operation-watermark`).
+      `operation_type = text_watermark`. Renders text overlays
+      (Liberation Sans) — supports `single` (one label at anchor) and
+      `tiled` (Cinavia-style angled fill) modes. Backed by the
+      operation-text-watermark Lambda. Per ADR-0004 + I4-CONS.
     parameters:
       env:
         description: Environment (local, stg, prod)
@@ -405,10 +475,10 @@ channels:
       SQS queue for merge operations.
       Subscribed to the `operations` SNS topic with filter
       `operation_type = merge`. A single `operation-merge` Lambda handles
-      all merge output types (image collage/grid, animated GIF, video
-      slideshow/concat, audio concat, PDF concat) — the `output_type`
-      field on the request determines the encoding path internally, not
-      the routing.
+      all merge output types (animated GIF, video slideshow/concat, audio
+      concat) — the `output_type` field on the request determines the
+      encoding path internally, not the routing. Image collage and PDF
+      concatenation are not supported by the V1 Lambda.
     parameters:
       env:
         description: Environment (local, stg, prod)
@@ -451,6 +521,97 @@ channels:
       operationRequest:
         $ref: '#/components/messages/OperationRequestMessage'
 
+  opsCustomLuma:
+    address: gisl-{env}-{region}-ops-custom-luma
+    description: |
+      SQS queue for custom_luma operations (caller-uploaded luma matte
+      transition; pro-tier paid feature). Subscribed to the
+      `operations` SNS topic with filter `operation_type = custom_luma`.
+      Multi-input (Path B with `role: base` + `role: transition_mask`
+      per `JobInputV2.role`).
+
+      `custom_luma` is `availability: planned` + `required_tier: pro`
+      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-custom-luma` Lambda (cross-repo follow-up; not yet
+      shipped).
+      Per ADR-0004 + I29 (Trello EPUE5Vs1).
+    parameters:
+      env:
+        description: Environment (local, stg, prod)
+      region:
+        description: AWS region abbreviation (euw1, use1, etc.)
+    messages:
+      operationRequest:
+        $ref: '#/components/messages/OperationRequestMessage'
+
+  opsAudioOverlay:
+    address: gisl-{env}-{region}-ops-audio-overlay
+    description: |
+      SQS queue for audio_overlay operations (mix a secondary audio
+      asset over a primary audio or video base — DJ tags, podcast
+      intros/outros, station IDs, jingles). Subscribed to the
+      `operations` SNS topic with filter
+      `operation_type = audio_overlay`. Multi-input (Path B with
+      `role: base` + `role: overlay` per `JobInputV2.role`).
+
+      Both mime_groups (`audio`, `video`) are `availability: planned`;
+      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-overlay` Lambda
+      (cross-repo follow-up; not yet shipped).
+
+      **NOT** the same as `audio_watermark` — that operation is
+      steganographic (imperceptible identifier embedded in audio for
+      ownership / forensic tracking) and is owned by ticket I20
+      (Trello omiCq7Vn). `audio_overlay` is industry "audio overlay"
+      / "audio branding".
+
+      Per ADR-0004 + I19 (Trello Xr3Z4GBF).
+    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: |
+      SQS queue for audio_watermark operations (steganographic
+      forensic watermarking — Cinavia / Resemble PerTh territory).
+      Subscribed to the `operations` SNS topic with filter
+      `operation_type = audio_watermark`. Single-input.
+
+      Both mime_groups (`audio`, `video` — embed in video's audio
+      track) are `availability: planned` + `required_tier:
+      enterprise` per the operation schema; the API rejects workflow-
+      create with `feature_not_available` (422) until the Lambda
+      ships, plus 403 `feature_tier_restricted` for non-enterprise
+      callers, so traffic does not reach this queue today. Backed
+      by the `operation-audio-watermark` Lambda (cross-repo follow-up;
+      not yet shipped).
+
+      **Industry naming.** This is *audio watermarking* (steganographic
+      ownership / forensic tracking), NOT *audio overlay* (audible
+      mixing). Audio overlay is owned by `audio_overlay` (I19).
+
+      Pairs with `POST /api/audio-watermark/decode` for
+      own-watermarks-only extraction (declared in `openapi/api.yaml`).
+
+      Per ADR-0004 + I20 (Trello omiCq7Vn).
+    parameters:
+      env:
+        description: Environment (local, stg, prod)
+      region:
+        description: AWS region abbreviation (euw1, use1, etc.)
+    messages:
+      operationRequest:
+        $ref: '#/components/messages/OperationRequestMessage'
+
   # ============================================
   # OPS FAMILY - DEAD LETTER QUEUES
   # ============================================
@@ -500,9 +661,18 @@ channels:
       region:
         description: AWS region abbreviation (euw1, use1, etc.)
 
-  opsWatermarkDlq:
-    address: gisl-{env}-{region}-ops-watermark-dlq
-    description: DLQ for failed watermark operations. Messages land here after 5 failed processing attempts.
+  opsImageWatermarkDlq:
+    address: gisl-{env}-{region}-ops-image-watermark-dlq
+    description: DLQ for failed image_watermark operations. Messages land here after 5 failed processing attempts.
+    parameters:
+      env:
+        description: Environment (local, stg, prod)
+      region:
+        description: AWS region abbreviation (euw1, use1, etc.)
+
+  opsTextWatermarkDlq:
+    address: gisl-{env}-{region}-ops-text-watermark-dlq
+    description: DLQ for failed text_watermark operations. Messages land here after 5 failed processing attempts.
     parameters:
       env:
         description: Environment (local, stg, prod)
@@ -536,6 +706,152 @@ channels:
       region:
         description: AWS region abbreviation (euw1, use1, etc.)
 
+  opsCustomLumaDlq:
+    address: gisl-{env}-{region}-ops-custom-luma-dlq
+    description: |
+      DLQ for failed custom_luma operations (per ticket I29).
+      Messages land here after 5 failed processing attempts. No traffic
+      reaches this queue while custom_luma is `availability: planned`.
+    parameters:
+      env:
+        description: Environment (local, stg, prod)
+      region:
+        description: AWS region abbreviation (euw1, use1, etc.)
+
+  opsAudioOverlayDlq:
+    address: gisl-{env}-{region}-ops-audio-overlay-dlq
+    description: |
+      DLQ for failed audio_overlay operations (per ticket I19).
+      Messages land here after 5 failed processing attempts. No
+      traffic reaches this queue while audio_overlay is
+      `availability: planned`.
+    parameters:
+      env:
+        description: Environment (local, stg, prod)
+      region:
+        description: AWS region abbreviation (euw1, use1, etc.)
+
+  opsAudioWatermarkDlq:
+    address: gisl-{env}-{region}-ops-audio-watermark-dlq
+    description: |
+      DLQ for failed audio_watermark operations (per ticket I20).
+      Messages land here after 5 failed processing attempts. No
+      traffic reaches this queue while audio_watermark is
+      `availability: planned` + `required_tier: enterprise`.
+    parameters:
+      env:
+        description: Environment (local, stg, prod)
+      region:
+        description: AWS region abbreviation (euw1, use1, etc.)
+
+  # ============================================
+  # UPLOAD PROBE (per ticket vBlEurU7 + M2 Epic SrHwuvIl)
+  # ============================================
+
+  uploadProbeRequestsTopic:
+    address: gisl-{env}-{region}-upload-probe-requests
+    description: |
+      SNS topic where the API publishes asynchronous upload-probe
+      requests for eager `rich_metadata` enrichment on upload finalize.
+      Per ticket [vBlEurU7](https://trello.com/c/vBlEurU7) +
+      M2 Epic re-scope ([SrHwuvIl](https://trello.com/c/SrHwuvIl)).
+
+      The probe Lambda ([rdBHmTfa](https://trello.com/c/rdBHmTfa))
+      can be invoked two ways with the same `UploadProbeRequest`
+      payload shape:
+
+      1. **Synchronous AWS Lambda Invoke** (RequestResponse mode) —
+         used to back `POST /api/uploads/{id}/probe`. Not modelled
+         as an AsyncAPI channel; the request payload + the response
+         payload (`UploadProbeResponse` from `openapi/api.yaml`) are
+         the contract for that path.
+      2. **Asynchronous SNS -> SQS -> Lambda** — used by the upload
+         finalize publisher. This topic is the entry point for that
+         async branch. The Lambda then publishes the result to the
+         `uploadProbeCompletionsQueue` for the API consumer to read.
+
+      No SNS message attribute filter is applied — the topic has a
+      single subscription (`uploadProbeQueue`) and the Lambda accepts
+      every probe request published here.
+    parameters:
+      env:
+        description: Environment (local, stg, prod)
+      region:
+        description: AWS region abbreviation (euw1, use1, etc.)
+    messages:
+      uploadProbeRequest:
+        $ref: '#/components/messages/UploadProbeRequestMessage'
+
+  uploadProbeQueue:
+    address: gisl-{env}-{region}-upload-probe
+    description: |
+      SQS queue subscribed to the `upload-probe-requests` SNS topic.
+      The upload-probe Lambda consumes from this queue.
+
+      Standard (non-FIFO) — each probe request is independent; no
+      ordering guarantees are required across uploads.
+    parameters:
+      env:
+        description: Environment (local, stg, prod)
+      region:
+        description: AWS region abbreviation (euw1, use1, etc.)
+    messages:
+      uploadProbeRequest:
+        $ref: '#/components/messages/UploadProbeRequestMessage'
+
+  uploadProbeDlq:
+    address: gisl-{env}-{region}-upload-probe-dlq
+    description: |
+      DLQ for failed upload-probe Lambda invocations from the async
+      branch. Messages land here after 5 failed processing attempts.
+      The sync `POST /api/uploads/{id}/probe` path does not flow
+      through this DLQ — sync errors are surfaced inline via the
+      Lambda RequestResponse return value.
+    parameters:
+      env:
+        description: Environment (local, stg, prod)
+      region:
+        description: AWS region abbreviation (euw1, use1, etc.)
+
+  uploadProbeCompletionsQueue:
+    address: gisl-{env}-{region}-upload-probe-completions
+    description: |
+      SQS queue where the upload-probe Lambda publishes
+      `UploadProbeCompletion` messages on the async branch. The API
+      consumer worker reads from this queue and persists
+      `rich_metadata` on the upload row.
+
+      Standard (non-FIFO) — completions are independent; no ordering
+      guarantees across uploads. Idempotency is handled by the
+      `idempotency_key` field on the message payload (echoed from the
+      original request) and by the API consumer's per-upload
+      "first-write-wins" persistence path.
+
+      The sync `POST /api/uploads/{id}/probe` path does not publish
+      here — sync results are returned inline via the Lambda
+      RequestResponse return value.
+    parameters:
+      env:
+        description: Environment (local, stg, prod)
+      region:
+        description: AWS region abbreviation (euw1, use1, etc.)
+    messages:
+      uploadProbeCompletion:
+        $ref: '#/components/messages/UploadProbeCompletionMessage'
+
+  uploadProbeCompletionsDlq:
+    address: gisl-{env}-{region}-upload-probe-completions-dlq
+    description: |
+      DLQ for failed completion-message processing by the API
+      consumer worker. Messages land here after 5 failed processing
+      attempts (e.g. database persistence failures, malformed
+      payloads).
+    parameters:
+      env:
+        description: Environment (local, stg, prod)
+      region:
+        description: AWS region abbreviation (euw1, use1, etc.)
+
   # ============================================
   # NOTIFICATIONS (Lambda -> API)
   # ============================================
@@ -627,8 +943,9 @@ operations:
       Non-compression-branch publisher path. Invoked by the API for any
       operation where `operation_type != compress` — that is, thumbnail
       (including the four sub-type values during the migration window),
-      watermark, merge, archive, convert. The target SNS topic filters
-      subscriptions on `operation_type` alone.
+      image_watermark, text_watermark, merge, archive, convert,
+      custom_luma, audio_overlay, audio_watermark. The target SNS
+      topic filters subscriptions on `operation_type` alone.
 
       **Message attributes set on this branch:** `{operation_type,
       media_group}`, with `media_group` omitted for `archive` (which is
@@ -653,8 +970,9 @@ operations:
     description: |
       The image compression Lambda consumes jobs for image inputs.
       Handles `compress` only. Non-compression image operations
-      (thumbnail, watermark, convert, merge) are routed to their
-      respective queues on the ops-family under the `operations` topic.
+      (thumbnail, image_watermark, text_watermark, convert, merge) are
+      routed to their respective queues on the ops-family under the
+      `operations` topic.
     messages:
       - $ref: '#/channels/jobsImage/messages/jobRequest'
 
@@ -764,17 +1082,36 @@ operations:
     messages:
       - $ref: '#/channels/opsThumbnailOffice/messages/operationRequest'
 
-  consumeWatermarkOperation:
+  consumeImageWatermarkOperation:
     action: receive
     channel:
-      $ref: '#/channels/opsWatermark'
-    summary: Process watermark operation
+      $ref: '#/channels/opsImageWatermark'
+    summary: Process image_watermark operation
     description: |
-      The watermark Lambda consumes watermark requests routed by
-      `operation_type=watermark`. Image-only — handles both
-      image-overlay and text-overlay modes.
+      The operation-image-watermark Lambda consumes image_watermark
+      requests routed by `operation_type=image_watermark`. Multi-input
+      (Path B with role: base + overlay per JobInputV2.role).
+
+      Stable for image bases today; animated GIF (`image_gif` group) and
+      video bases (`video` group) are advertised as `planned` in the
+      schema (I5 — Trello AKZiOXnd) and dispatch returns
+      `feature_not_available` (422) at the API edge until Lambda support
+      ships. Per ADR-0004 + I4-CONS + I5.
     messages:
-      - $ref: '#/channels/opsWatermark/messages/operationRequest'
+      - $ref: '#/channels/opsImageWatermark/messages/operationRequest'
+
+  consumeTextWatermarkOperation:
+    action: receive
+    channel:
+      $ref: '#/channels/opsTextWatermark'
+    summary: Process text_watermark operation
+    description: |
+      The operation-text-watermark Lambda consumes text_watermark
+      requests routed by `operation_type=text_watermark`. Single-input;
+      image-only. Renders text via bundled Liberation Sans (SIL OFL),
+      supports `single` and `tiled` watermark_mode. Per ADR-0004 + I4-CONS.
+    messages:
+      - $ref: '#/channels/opsTextWatermark/messages/operationRequest'
 
   consumeMergeOperation:
     action: receive
@@ -783,10 +1120,11 @@ operations:
     summary: Process merge operation
     description: |
       The merge Lambda consumes merge requests routed by
-      `operation_type=merge`. A single Lambda handles all merge output
-      types (image collage/grid, animated GIF, video slideshow/concat,
-      audio concat, PDF concat). The `output_type` field on the request
-      determines the encoding path internally.
+      `operation_type=merge`. A single Lambda handles the supported merge
+      output types (animated GIF, video slideshow/concat, audio concat).
+      The `output_type` field on the request determines the encoding
+      path internally. Image collage and PDF concatenation are not
+      supported by the V1 Lambda.
     messages:
       - $ref: '#/channels/opsMerge/messages/operationRequest'
 
@@ -814,6 +1152,59 @@ operations:
     messages:
       - $ref: '#/channels/opsConvert/messages/operationRequest'
 
+  consumeCustomLumaOperation:
+    action: receive
+    channel:
+      $ref: '#/channels/opsCustomLuma'
+    summary: Process custom_luma operation
+    description: |
+      The `operation-custom-luma` Lambda (cross-repo follow-up — not
+      yet shipped) consumes custom_luma requests routed by
+      `operation_type=custom_luma`. Multi-input (Path B with
+      `role: base` + `role: transition_mask` per `JobInputV2.role`).
+      `availability: planned` + `required_tier: pro`; 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 + I29 (Trello EPUE5Vs1).
+    messages:
+      - $ref: '#/channels/opsCustomLuma/messages/operationRequest'
+
+  consumeAudioOverlayOperation:
+    action: receive
+    channel:
+      $ref: '#/channels/opsAudioOverlay'
+    summary: Process audio_overlay operation
+    description: |
+      The `operation-audio-overlay` Lambda (cross-repo follow-up —
+      not yet shipped) consumes audio_overlay requests routed by
+      `operation_type=audio_overlay`. Multi-input (Path B with
+      `role: base` + `role: overlay` per `JobInputV2.role`).
+      Both mime_groups (`audio`, `video`) are `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 + I19 (Trello Xr3Z4GBF).
+    messages:
+      - $ref: '#/channels/opsAudioOverlay/messages/operationRequest'
+
+  consumeAudioWatermarkOperation:
+    action: receive
+    channel:
+      $ref: '#/channels/opsAudioWatermark'
+    summary: Process audio_watermark operation
+    description: |
+      The `operation-audio-watermark` Lambda (cross-repo follow-up —
+      not yet shipped) consumes audio_watermark requests routed by
+      `operation_type=audio_watermark`. Single-input. Both mime_groups
+      (`audio`, `video`) are `availability: planned` +
+      `required_tier: enterprise`; the API rejects workflow-create
+      with `feature_not_available` (422) until the Lambda ships, plus
+      403 `feature_tier_restricted` for non-enterprise callers, so
+      traffic does not reach this channel today.
+      Per ADR-0004 + I20 (Trello omiCq7Vn).
+    messages:
+      - $ref: '#/channels/opsAudioWatermark/messages/operationRequest'
+
   # ============================================
   # NOTIFICATION OPERATIONS
   # ============================================
@@ -853,6 +1244,81 @@ operations:
       - $ref: '#/channels/notificationsOperationsQueue/messages/operationProgress'
       - $ref: '#/channels/notificationsOperationsQueue/messages/operationResult'
 
+  # ============================================
+  # UPLOAD-PROBE OPERATIONS (per ticket vBlEurU7)
+  # ============================================
+
+  publishUploadProbeRequest:
+    action: send
+    channel:
+      $ref: '#/channels/uploadProbeRequestsTopic'
+    summary: Publish an async upload-probe request
+    description: |
+      The API publishes to this topic on the **async branch** —
+      typically from the upload-finalize publisher when eager
+      `rich_metadata` enrichment is configured for the caller's
+      tier / MIME group.
+
+      The `POST /api/uploads/{id}/probe` sync path does **not** use
+      this operation — it invokes the Lambda directly via the AWS
+      Lambda Invoke API (RequestResponse mode). The two paths share
+      the `UploadProbeRequest` payload schema so the Lambda accepts
+      a single request shape regardless of invocation source.
+    messages:
+      - $ref: '#/channels/uploadProbeRequestsTopic/messages/uploadProbeRequest'
+
+  consumeUploadProbeRequest:
+    action: receive
+    channel:
+      $ref: '#/channels/uploadProbeQueue'
+    summary: Consume an upload-probe request (async branch)
+    description: |
+      The upload-probe Lambda consumes from the SQS queue subscribed
+      to the `upload-probe-requests` topic. On success the Lambda
+      publishes an `UploadProbeCompletion` to the completions queue;
+      on failure the Lambda emits a completion with `error_code`
+      populated (so the API consumer can persist the failure mode)
+      before SQS retry / DLQ handling kicks in.
+
+      Sync invocations bypass this operation entirely.
+    messages:
+      - $ref: '#/channels/uploadProbeQueue/messages/uploadProbeRequest'
+
+  publishUploadProbeCompletion:
+    action: send
+    channel:
+      $ref: '#/channels/uploadProbeCompletionsQueue'
+    summary: Publish an upload-probe completion (async branch)
+    description: |
+      The upload-probe Lambda publishes the result of the async
+      branch to this queue. The payload shape is `UploadProbeCompletion`
+      and intentionally carries both the success fields
+      (`probe_status`, `media_metadata`, `processing_class_pre_assignment`)
+      and the failure fields (`error_code`, `error_message`) so the
+      API consumer worker handles both outcomes from a single
+      message shape.
+
+      The sync `POST /api/uploads/{id}/probe` path does not publish
+      here — sync results are returned inline via the Lambda
+      RequestResponse return value as `UploadProbeResponse`
+      (`openapi/api.yaml`).
+    messages:
+      - $ref: '#/channels/uploadProbeCompletionsQueue/messages/uploadProbeCompletion'
+
+  consumeUploadProbeCompletion:
+    action: receive
+    channel:
+      $ref: '#/channels/uploadProbeCompletionsQueue'
+    summary: Consume an upload-probe completion (async branch)
+    description: |
+      The API consumer worker reads completions from this queue and
+      persists `rich_metadata` (and any error state) on the upload
+      row. Idempotency is handled by the `idempotency_key` echoed in
+      the completion payload plus a per-upload "first-write-wins"
+      persistence path on the API side.
+    messages:
+      - $ref: '#/channels/uploadProbeCompletionsQueue/messages/uploadProbeCompletion'
+
 components:
   messages:
     # ============================================
@@ -933,16 +1399,19 @@ components:
       summary: Request to process a non-compression operation
       description: |
         Message sent by the API to request processing of any
-        **non-compression** operation (thumbnail, watermark, merge,
-        archive, convert). Published to the `operations` SNS topic;
-        routed by the single-attribute filter `operation_type` to one
-        of the nine ops-family queues.
+        **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.
 
         **SNS Message Attributes:**
         - `operation_type`: always present. Values: `thumbnail`,
           `thumbnail_image`, `thumbnail_video`, `thumbnail_document`,
-          `thumbnail_office`, `watermark`, `merge`, `archive`, `convert`.
-          Used by SNS as the filter attribute on the `operations` topic.
+          `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.
         - `media_group`: informational metadata, present for every
           operation except `archive` (which is media-agnostic). Values:
           `image`, `video`, `audio`, `document`. **Not** used by SNS as
@@ -950,12 +1419,23 @@ components:
           log correlation.
 
         **Input models:**
-        - Single-input operations (thumbnail, thumbnail_image,
-          thumbnail_video, thumbnail_document, thumbnail_office,
-          watermark, convert): use `source_bucket` + `source_key`.
-          `file_type` required.
-        - Multi-input operations (merge, archive): use `sources` array.
-          Merge additionally requires `output_type`.
+        - Single-input operations (thumbnail, text_watermark, convert,
+          audio_watermark): 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`
+          and the migration-window note below); the payload
+          `operation_type` field always remains `thumbnail`.
+          `audio_watermark` is `availability: planned` +
+          `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.
 
         **Migration window note.** During the thumbnail sub-type
         migration, both `operation_type=thumbnail` (legacy) and
@@ -988,14 +1468,14 @@ components:
               fit: "crop"
               format: "jpg"
         - name: Thumbnail Image (sub-type)
-          summary: Generate a thumbnail for an image using the new thumbnail_image sub-type routing target
+          summary: Generate a thumbnail for an image using the new thumbnail_image sub-type routing target. The SNS attribute `operation_type` carries the sub-type (drives routing); the payload `operation_type` carries the base value (`thumbnail`).
           headers:
             operation_type: "thumbnail_image"
             media_group: "image"
           payload:
             job_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e121"
             operation_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e221"
-            operation_type: "thumbnail_image"
+            operation_type: "thumbnail"
             file_type: "image/png"
             source_bucket: "gisl-stg-euw1-input"
             source_key: "uploads/018f9c42-kkll/screenshot.png"
@@ -1006,47 +1486,52 @@ components:
               height: 512
               fit: "max"
               format: "webp"
-        - name: Image Watermark (image overlay)
-          summary: Apply a PNG logo overlay to a JPEG image
+        - name: Image Watermark (file overlay)
+          summary: Apply a PNG logo overlay to a JPEG image (V2 multi-input Path B)
           headers:
-            operation_type: "watermark"
+            operation_type: "image_watermark"
             media_group: "image"
           payload:
             job_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e118"
             operation_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e210"
-            operation_type: "watermark"
+            operation_type: "image_watermark"
             file_type: "image/jpeg"
-            source_bucket: "gisl-stg-euw1-input"
-            source_key: "uploads/018f9c42-eeff/photo.jpg"
+            sources:
+              - role: "base"
+                source_bucket: "gisl-stg-euw1-input"
+                source_key: "uploads/018f9c42-eeff/photo.jpg"
+              - role: "overlay"
+                source_bucket: "gisl-stg-euw1-assets"
+                source_key: "brand/logo.png"
             output_bucket: "gisl-stg-euw1-output"
             output_key_prefix: "jobs/018f9c42-5d6b-7481-b3df-9fd0a0a5e118/018f9c42-5d6b-7481-b3df-9fd0a0a5e210/"
             options:
-              watermark_type: "image"
-              watermark_bucket: "gisl-stg-euw1-assets"
-              watermark_key: "brand/logo.png"
-              position: "bottom-right"
+              anchor: "bottom_right"
+              margin_x: "20px"
+              margin_y: "20px"
               opacity: 0.6
-        - name: Image Watermark (tiled text overlay)
-          summary: Render a rotated tiled text watermark across a PNG image
+              overlay_width: "200px"
+        - name: Text Watermark (tiled)
+          summary: Render a rotated tiled text watermark across a PNG image (V2 single-input)
           headers:
-            operation_type: "watermark"
+            operation_type: "text_watermark"
             media_group: "image"
           payload:
             job_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e119"
             operation_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e211"
-            operation_type: "watermark"
+            operation_type: "text_watermark"
             file_type: "image/png"
             source_bucket: "gisl-stg-euw1-input"
             source_key: "uploads/018f9c42-gghh/screenshot.png"
             output_bucket: "gisl-stg-euw1-output"
             output_key_prefix: "jobs/018f9c42-5d6b-7481-b3df-9fd0a0a5e119/018f9c42-5d6b-7481-b3df-9fd0a0a5e211/"
             options:
-              watermark_type: "text"
-              watermark_mode: "tiled"
               text: "CONFIDENTIAL"
               font_size: 64
               color: "#FF000080"
+              font_family: "liberation_sans"
               rotation: -45
+              watermark_mode: "tiled"
               tile_spacing: 120
               opacity: 0.4
         - name: Image Convert
@@ -1113,25 +1598,6 @@ components:
             options:
               frame_delay: 100
               loop: true
-        - name: PDF Merge
-          summary: Concatenate multiple PDFs into one
-          headers:
-            operation_type: "merge"
-            media_group: "document"
-          payload:
-            job_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e116"
-            operation_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e204"
-            operation_type: "merge"
-            file_type: "application/pdf"
-            output_type: "document"
-            sources:
-              - bucket: "gisl-stg-euw1-output"
-                key: "jobs/018f9c42-aaa1/018f9c42-bbb1/chapter1.pdf"
-              - bucket: "gisl-stg-euw1-output"
-                key: "jobs/018f9c42-aaa2/018f9c42-bbb2/chapter2.pdf"
-            output_bucket: "gisl-stg-euw1-output"
-            output_key_prefix: "jobs/018f9c42-5d6b-7481-b3df-9fd0a0a5e116/018f9c42-5d6b-7481-b3df-9fd0a0a5e204/"
-            options: {}
         - name: Archive
           summary: Bundle multiple files into a ZIP archive (no media_group attribute — archive is media-agnostic)
           headers:
@@ -1216,6 +1682,157 @@ components:
     # OPERATION RESULT MESSAGE
     # ============================================
 
+    # ============================================
+    # UPLOAD-PROBE MESSAGES (per ticket vBlEurU7)
+    # ============================================
+
+    UploadProbeRequestMessage:
+      name: UploadProbeRequest
+      title: Upload Probe Request
+      summary: Request for the upload-probe Lambda to analyse an uploaded file
+      description: |
+        Request published by the API to the upload-probe Lambda. The
+        same payload shape is also used as the Lambda invoke payload
+        on the synchronous `POST /api/uploads/{id}/probe` path.
+
+        **Invocation paths:**
+        - **Sync (Lambda RequestResponse)** — backs
+          `POST /api/uploads/{id}/probe`. The API Lambda invoker
+          serialises this payload into the Invoke event body and
+          returns the Lambda response (`UploadProbeResponse` from
+          `openapi/api.yaml`) inline.
+        - **Async (SNS -> SQS)** — published to the
+          `upload-probe-requests` topic on upload finalize for eager
+          `rich_metadata` enrichment. The Lambda consumes from the
+          subscribed queue and publishes a completion to the
+          `upload-probe-completions` queue.
+
+        The Lambda differentiates the two paths from the AWS event
+        source (Lambda RequestResponse vs SNS event) — no flag in
+        the payload distinguishes them.
+      contentType: application/json
+      payload:
+        $ref: '#/components/schemas/UploadProbeRequest'
+      examples:
+        - name: Async upload-finalize probe
+          summary: Eager enrichment for a long-form video upload
+          payload:
+            file_id: "019539ab-1111-7000-8000-000000000010"
+            source_bucket: "gisl-stg-euw1-input"
+            source_key: "uploads/019539ab-1111-7000-8000-000000000010/clip.mp4"
+            file_type: "video/mp4"
+            idempotency_key: "upload-finalize:019539ab-1111-7000-8000-000000000010"
+            requested_at: "2026-05-06T13:50:00Z"
+        - name: Sync preflight probe
+          summary: Caller-initiated preflight via POST /api/uploads/{id}/probe
+          payload:
+            file_id: "019539ab-1111-7000-8000-000000000011"
+            source_bucket: "gisl-stg-euw1-input"
+            source_key: "uploads/019539ab-1111-7000-8000-000000000011/clip.mp4"
+            file_type: "video/mp4"
+            idempotency_key: "019539ab-1111-7000-8000-000000000011"
+            requested_at: "2026-05-06T13:50:00Z"
+
+    UploadProbeCompletionMessage:
+      name: UploadProbeCompletion
+      title: Upload Probe Completion
+      summary: Completion notification from the upload-probe Lambda (async branch only)
+      description: |
+        Published by the upload-probe Lambda to the
+        `upload-probe-completions` queue when the async branch
+        finishes. The payload carries either a successful probe
+        result (parity with `UploadProbeResponse` from
+        `openapi/api.yaml`) or a failure envelope (`error_code` +
+        `error_message`).
+
+        **Idempotency.** `idempotency_key` is echoed from the
+        request so the API consumer can deduplicate against its
+        upload row's persisted probe state.
+
+        Sync invocations do not publish here — sync results are
+        returned inline as `UploadProbeResponse`.
+      contentType: application/json
+      payload:
+        $ref: '#/components/schemas/UploadProbeCompletion'
+      examples:
+        - name: Successful probe (long-form video with audio track)
+          summary: Lambda extracted full media metadata for a 4K H.265 video
+          payload:
+            file_id: "019539ab-1111-7000-8000-000000000010"
+            idempotency_key: "upload-finalize:019539ab-1111-7000-8000-000000000010"
+            probe_status: "ok"
+            processing_class_pre_assignment: "long_form"
+            media_metadata:
+              duration_seconds: 5400
+              width: 3840
+              height: 2160
+              codec: "h265"
+              audio_codec: "aac"
+              container: "mp4"
+              fps: 23.976
+              bitrate_bps: 18000000
+              audio_layout: "stereo"
+              channels: 2
+              sample_rate_hz: 48000
+              probed_at: "2026-05-06T13:50:01Z"
+            probed_at: "2026-05-06T13:50:01Z"
+            probe_version: "1.0.0"
+        - name: Successful probe (audio-only)
+          summary: MP3 podcast episode — codec under `codec`, no `audio_codec` field
+          payload:
+            file_id: "019539ab-1111-7000-8000-000000000020"
+            idempotency_key: "upload-finalize:019539ab-1111-7000-8000-000000000020"
+            probe_status: "ok"
+            processing_class_pre_assignment: "short_form"
+            media_metadata:
+              duration_seconds: 2700
+              codec: "mp3"
+              container: "mp3"
+              bitrate_bps: 192000
+              audio_layout: "stereo"
+              channels: 2
+              sample_rate_hz: 44100
+              probed_at: "2026-05-06T13:50:01Z"
+            probed_at: "2026-05-06T13:50:01Z"
+            probe_version: "1.0.0"
+        - name: Successful probe (document)
+          summary: PDF — `page_count` + `dpi` populated, video/audio fields omitted
+          payload:
+            file_id: "019539ab-1111-7000-8000-000000000021"
+            idempotency_key: "upload-finalize:019539ab-1111-7000-8000-000000000021"
+            probe_status: "ok"
+            processing_class_pre_assignment: "short_form"
+            media_metadata:
+              container: "pdf"
+              page_count: 42
+              dpi: 300
+              probed_at: "2026-05-06T13:50:01Z"
+            probed_at: "2026-05-06T13:50:01Z"
+            probe_version: "1.0.0"
+        - name: Probe surfaced unsupported codec
+          summary: Container readable; codec not in supported set
+          payload:
+            file_id: "019539ab-1111-7000-8000-000000000012"
+            idempotency_key: "upload-finalize:019539ab-1111-7000-8000-000000000012"
+            probe_status: "unsupported_codec"
+            processing_class_pre_assignment: "blocked"
+            media_metadata:
+              duration_seconds: 600
+              codec: "prores"
+              container: "mov"
+              probed_at: "2026-05-06T13:50:01Z"
+            probed_at: "2026-05-06T13:50:01Z"
+            probe_version: "1.0.0"
+        - name: Probe failed (Lambda-side error)
+          summary: S3 download failed; probe could not run
+          payload:
+            file_id: "019539ab-1111-7000-8000-000000000013"
+            idempotency_key: "upload-finalize:019539ab-1111-7000-8000-000000000013"
+            error_code: "s3_download_failed"
+            error_message: "Failed to download source file from S3"
+            probed_at: "2026-05-06T13:50:01Z"
+            probe_version: "1.0.0"
+
     OperationResultMessage:
       name: OperationResult
       title: Operation Result
@@ -1290,8 +1907,148 @@ components:
             error_message: "Failed to download source file from S3"
             is_retryable: true
             last_progress: 0
+        - name: Successful Multi-Output Convert (PDF to PNG, 3 pages)
+          summary: Convert PDF->image fan-out result per ADR-0009
+          payload:
+            job_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e115"
+            operation_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e203"
+            operation_type: "convert"
+            status: "completed"
+            output_bucket: "gisl-stg-euw1-output"
+            total_output_size_bytes: 786432
+            outputs:
+              - output_key: "jobs/018f9c42-5d6b/018f9c42-5d6b-e203/page-001.png"
+                output_size_bytes: 262144
+                page_index: 1
+              - output_key: "jobs/018f9c42-5d6b/018f9c42-5d6b-e203/page-002.png"
+                output_size_bytes: 262144
+                page_index: 2
+              - output_key: "jobs/018f9c42-5d6b/018f9c42-5d6b-e203/page-003.png"
+                output_size_bytes: 262144
+                page_index: 3
+            metrics:
+              input_count: 1
+              output_size_bytes: 786432
+              duration_ms: 2300
+        - name: Failed Multi-Output Convert (page 2 of 3 corrupted)
+          summary: |
+            Multi-output operation failed mid-stream per ADR-0009 §D3 (all-or-nothing
+            failure). Lambda short-circuited on page 2; page 1 was uploaded before
+            the failure, listed in outputs[] as informational data only — consumers
+            MUST NOT treat them as usable on failure.
+          payload:
+            job_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e115"
+            operation_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e203"
+            operation_type: "convert"
+            status: "failed"
+            error_code: "processing_failed"
+            error_message: "pdftocairo failed on page 2: invalid page tree node"
+            is_retryable: false
+            last_progress: 50
+            outputs:
+              - output_key: "jobs/018f9c42-5d6b/018f9c42-5d6b-e203/page-001.png"
+                output_size_bytes: 262144
+                page_index: 1
 
   schemas:
+    # ============================================
+    # AVAILABILITY METADATA (decorative)
+    # ============================================
+
+    AvailabilityValue:
+      type: string
+      description: |
+        Availability level for an operation, mime_group, option, or
+        per-enum-value entry per ADR-0001 §1.3. Mirrors the
+        `AvailabilityValue` schema in `openapi/api.yaml` so SDK
+        generators that consume both specs emit a single typed binding.
+
+        Used as the value of decorative `x-availability` extensions in
+        this spec, and as the typed schema future tickets (I17
+        `per_value_availability` primitive; I27 phased progress states)
+        reference for availability metadata on event payloads.
+
+        Per ADR-0001 §1.4: when `availability` is absent, the implicit
+        value is `stable` for consumers. `stable_pending_audit` is
+        internal CI accounting only and never surfaces.
+
+        See `schemas/FORMAT.md` §Availability Taxonomy for full rules.
+      enum:
+        - stable
+        - beta
+        - experimental
+        - planned
+        - deprecated
+
+    PerValueAvailabilityEntry:
+      type: object
+      description: |
+        Single per-enum-value availability entry. Mirrors
+        `PerValueAvailabilityEntry` in `openapi/api.yaml` so SDK
+        generators consuming both specs emit a single typed binding.
+
+        AsyncAPI consumers: this primitive is the canonical mechanism
+        for tagging individual enum values at different availability
+        levels — see `schemas/operations/merge.yaml` `transition`
+        (per ticket I16-CONS) and `audio_watermark.method` /
+        `audio_overlay.mode` for shipped consumers. The
+        `ProgressStatus` enum (probing / decoding / encoding values
+        landed via ticket I27) deliberately does NOT use
+        `per_value_availability` — those phase statuses are
+        long-form-operation conditional rather than caller-facing
+        feature gates, and their visibility is controlled by which
+        operations emit them rather than by per-value availability
+        tags.
+
+        See `schemas/FORMAT.md` §Availability Taxonomy for full rules.
+      required:
+        - availability
+      properties:
+        availability:
+          $ref: '#/components/schemas/AvailabilityValue'
+        required_tier:
+          description: Tier required to use this enum value. Optional.
+          type: string
+          enum:
+            - free
+            - pro
+            - enterprise
+        eta:
+          type: string
+          description: |
+            ISO-8601 date or quarter (`2026-Q3`) when this value is
+            expected to ship. Only meaningful for `availability: planned`.
+        documentation_url:
+          type: string
+          format: uri
+        sunset:
+          type: string
+          format: date
+
+    PerValueAvailability:
+      type: object
+      description: |
+        Map of enum-value → `PerValueAvailabilityEntry`. Mirrors the
+        OpenAPI version. Keys MUST be a subset of the option / status
+        enum's `values[]` (or AsyncAPI message field's `enum`) array.
+      additionalProperties:
+        $ref: '#/components/schemas/PerValueAvailabilityEntry'
+
+    PerMimeAvailability:
+      type: object
+      description: |
+        Map of MIME-type → `PerValueAvailabilityEntry`. Mirrors the
+        OpenAPI `PerMimeAvailability` schema so SDK generators
+        consuming both specs emit a single typed binding.
+
+        Keys MUST be a subset of the parent
+        `mime_groups.<group>.mimes` array (CI-checked by
+        `scripts/check-per-mime-availability.py`). Absent keys default
+        to `availability: stable` per ADR-0001 §1.4. Per ticket
+        [`YXYOo6gg`](https://trello.com/c/YXYOo6gg).
+      additionalProperties:
+        $ref: '#/components/schemas/PerValueAvailabilityEntry'
+
     # ============================================
     # FIFO MESSAGE HEADERS
     # ============================================
@@ -1374,8 +2131,35 @@ components:
         - `operation_type` is always present.
         - `media_group` is required iff `operation_type != archive`.
           Archive is explicitly omitted because it is media-agnostic.
-        - For `operation_type == watermark`, `media_group` must equal
-          `image` (watermark is image-only).
+        - For `operation_type = text_watermark`, `media_group` must
+          equal `image` (text_watermark is image-only).
+        - For `operation_type = custom_luma`, `media_group` must
+          equal `video` (custom_luma applies a luma matte to a video
+          base; the operation is `availability: planned` per
+          [I29](https://trello.com/c/EPUE5Vs1) so this constraint is
+          contract-defined but not exercised today).
+        - For `operation_type = audio_overlay`, `media_group` must
+          equal `audio` or `video` (audio_overlay supports both —
+          mixing into an audio track or into a video's audio track).
+          Both mime_groups are `availability: planned` per
+          [I19](https://trello.com/c/Xr3Z4GBF), so this constraint is
+          contract-defined but not exercised today.
+        - For `operation_type = audio_watermark`, `media_group` must
+          equal `audio` or `video` (audio_watermark supports both —
+          embedding into an audio asset or into a video's audio
+          track). Both mime_groups are `availability: planned` +
+          `required_tier: enterprise` per
+          [I20](https://trello.com/c/omiCq7Vn), 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`
+          mime_groups at `availability: planned` (I5 — Trello AKZiOXnd);
+          when those flip to `stable`, this constraint widens to
+          `{image, video}` (animated GIF carries `media_group=image`).
+          Until then the API rejects non-image bases at workflow-create
+          time with `feature_not_available` (422), so SNS-attribute
+          values stay constrained to `image`.
         - For the four thumbnail sub-types, `media_group` is constrained
           to the matching media:
           - `thumbnail_image` -> `image`
@@ -1398,10 +2182,14 @@ components:
             - thumbnail_video
             - thumbnail_document
             - thumbnail_office
-            - watermark
+            - image_watermark
+            - text_watermark
             - merge
             - archive
             - convert
+            - custom_luma
+            - audio_overlay
+            - audio_watermark
         media_group:
           type: string
           description: |
@@ -1429,11 +2217,43 @@ components:
         - if:
             properties:
               operation_type:
-                const: watermark
+                const: image_watermark
+          then:
+            properties:
+              media_group:
+                const: image
+        - if:
+            properties:
+              operation_type:
+                const: text_watermark
           then:
             properties:
               media_group:
                 const: image
+        - if:
+            properties:
+              operation_type:
+                const: custom_luma
+          then:
+            properties:
+              media_group:
+                const: video
+        - if:
+            properties:
+              operation_type:
+                const: audio_overlay
+          then:
+            properties:
+              media_group:
+                enum: [audio, video]
+        - if:
+            properties:
+              operation_type:
+                const: audio_watermark
+          then:
+            properties:
+              media_group:
+                enum: [audio, video]
         - if:
             properties:
               operation_type:
@@ -1479,15 +2299,17 @@ components:
         `OperationRequestMessage` (non-compression branch). Published by
         API to SNS, consumed by Lambda from SQS.
 
-        **Single-input operations** (compress, thumbnail, thumbnail_image,
-        thumbnail_video, thumbnail_document, thumbnail_office, watermark,
+        **Single-input operations** (compress, thumbnail, text_watermark,
         convert): use `source_bucket` + `source_key` for the input file.
         `file_type` is required.
 
-        **Multi-input operations** (merge, archive): use `sources` array.
-        Each entry has `bucket` + `key`. Merge entries may include
-        per-input overrides (e.g. transition type). Merge also requires
-        `output_type`.
+        **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
+        `availability: planned` so workflow-create rejects with 422
+        today; 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
@@ -1506,12 +2328,9 @@ components:
                 enum:
                   - compress
                   - thumbnail
-                  - thumbnail_image
-                  - thumbnail_video
-                  - thumbnail_document
-                  - thumbnail_office
-                  - watermark
+                  - text_watermark
                   - convert
+                  - audio_watermark
           then:
             required:
               - file_type
@@ -1520,7 +2339,7 @@ components:
         - if:
             properties:
               operation_type:
-                enum: [merge, archive]
+                enum: [merge, archive, image_watermark, custom_luma, audio_overlay]
           then:
             required:
               - sources
@@ -1584,9 +2403,14 @@ components:
         sources:
           type: array
           description: |
-            Input files for multi-input operations (merge, archive).
-            Each entry specifies an S3 location. Order matters for merge (concatenation order).
-            Per-input overrides (e.g. transition) can be inlined on each entry.
+            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.
+            Role-based multi-input operations (image_watermark,
+            custom_luma, audio_overlay) require a `role` discriminator
+            on each entry — see `SourceEntry.role`.
           items:
             $ref: '#/components/schemas/SourceEntry'
           minItems: 2
@@ -1633,8 +2457,11 @@ components:
     SourceEntry:
       type: object
       description: |
-        A single source file for multi-input operations (merge, archive).
-        Provides the S3 location and optional per-input overrides.
+        A single source file for multi-input operations (merge,
+        archive, image_watermark, custom_luma, audio_overlay).
+        Provides the S3 location, optional per-input overrides, and
+        the `role` discriminator for role-based multi-input
+        operations.
       required:
         - bucket
         - key
@@ -1647,18 +2474,16 @@ components:
           type: string
           description: S3 key of the source file
           example: "jobs/018f9c42-aaa1/018f9c42-bbb1/intro.mp4"
+        role:
+          # Named schema preserves the per-operation role rules in its
+          # description; lifted from inline per ticket QokFw8VR.
+          $ref: '#/components/schemas/JobInputRole'
         transition:
           type: string
           description: |
             Per-input transition override for video merge.
             Overrides the global transition option for the join point before this input.
           example: "none"
-        page_range:
-          type: string
-          description: |
-            Page range for PDF merge. Selects specific pages from this input.
-            Format: "1-5", "1,3,5-10". Omit for all pages.
-          example: "1-5"
 
     # ============================================
     # OPERATION PROGRESS SCHEMA
@@ -1704,6 +2529,30 @@ components:
           type: string
           description: Human-readable description of current processing stage
           example: "Compressing image"
+        phase_input_index:
+          type: integer
+          minimum: 1
+          description: |
+            1-based index of the input currently being processed in
+            this phase. Emitted only when `status` is `probing` or
+            `decoding` (and optionally `encoding` for multi-output
+            operations) to give callers visibility into long-form
+            jobs that internally process inputs sequentially.
+            Frontend renders "probing input 2/4" / "decoding input
+            3/4" without callers having to decompose into multiple
+            jobs. Per ticket I27 (Trello 1R3K3bsG) + plan v5 §F8.3.
+          example: 2
+        phase_total_inputs:
+          type: integer
+          minimum: 1
+          description: |
+            Total number of inputs expected in this phase. Pairs with
+            `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.
+          example: 4
 
     # ============================================
     # OPERATION RESULT SCHEMA
@@ -1717,25 +2566,81 @@ components:
 
         **Important**: This message MUST always be sent, whether the operation
         succeeds or fails. It is the definitive signal that processing is complete.
+
+        ## Single-output vs multi-output completion
+
+        Per [ADR-0009](../docs/decisions/0009-multi-output-result-envelope.md),
+        successful completion uses one of two mutually-exclusive shapes:
+
+        - **Single-output** (compress, watermark, merge, archive, convert
+          single-output, thumbnail): top-level `output_key` + `output_size_bytes`
+          are present; `outputs[]` is absent.
+        - **Multi-output** (convert PDF->image; future fan-out operations):
+          `outputs[]` + `total_output_size_bytes` are present; top-level
+          `output_key` / `output_size_bytes` are absent. Consumers MUST use
+          `outputs.length` (or its language equivalent) for the count; per
+          ADR-0009 §D4 a denormalised `output_count` field was deliberately
+          rejected.
+
+        `output_bucket` is shared across both shapes — all outputs in a
+        multi-output operation live in the same bucket.
+
+        Failure (`status: failed`) is unified across both shapes: one
+        `error_code` + `error_message` + `is_retryable` at the top level; no
+        per-output error array (all-or-nothing failure per ADR-0009 §D3).
+        `outputs[]` MAY be present on failure as informational data showing
+        which outputs completed before the failing one; consumers MUST NOT
+        treat them as usable.
       required:
         - job_id
         - operation_id
         - operation_type
         - status
-      if:
-        properties:
-          status:
-            const: completed
-      then:
-        required:
-          - output_bucket
-          - output_key
-          - output_size_bytes
-      else:
-        required:
-          - error_code
-          - error_message
-          - is_retryable
+      oneOf:
+        - title: SingleOutputCompletion
+          description: |
+            Legacy single-output completion. Used by compress, watermark,
+            merge, archive, convert single-output, and thumbnail operations.
+          properties:
+            status:
+              const: completed
+          required:
+            - output_bucket
+            - output_key
+            - output_size_bytes
+          not:
+            anyOf:
+              - required: [outputs]
+              - required: [output_count]
+              - required: [total_output_size_bytes]
+        - title: MultiOutputCompletion
+          description: |
+            Multi-output completion. Used by convert PDF->image and future
+            fan-out operations. Per ADR-0009.
+          properties:
+            status:
+              const: completed
+          required:
+            - output_bucket
+            - outputs
+            - total_output_size_bytes
+          not:
+            anyOf:
+              - required: [output_key]
+              - required: [output_size_bytes]
+        - title: Failure
+          description: |
+            Operation failed (single- or multi-output). One top-level error
+            envelope per ADR-0009 §D3 (all-or-nothing failure). `outputs[]`
+            MAY be present with partial results as informational data; do
+            not consume.
+          properties:
+            status:
+              const: failed
+          required:
+            - error_code
+            - error_message
+            - is_retryable
       properties:
         job_id:
           type: string
@@ -1752,20 +2657,75 @@ components:
         status:
           $ref: '#/components/schemas/ResultStatus'
 
-        # Success fields
+        # Shared success field (both single- and multi-output)
         output_bucket:
           type: string
-          description: S3 bucket where output file is stored (completed only)
+          description: |
+            S3 bucket where output file(s) are stored. Present on completion
+            for both single- and multi-output operations; all outputs in a
+            multi-output operation share this bucket. Absent on failure.
           example: "gisl-stg-euw1-output"
+
+        # Single-output success fields (legacy; per ADR-0009 SingleOutputCompletion)
         output_key:
           type: string
-          description: S3 key of the output file (completed only)
+          description: |
+            S3 key of the output file. Single-output completion only — mutually
+            exclusive with `outputs[]`. Absent for multi-output operations and
+            on failure.
           example: "jobs/018f9c42-5d6b/018f9c42-5d6b-e200/photo_compressed.png"
         output_size_bytes:
           type: integer
           format: int64
-          description: Output file size in bytes (completed only)
+          description: |
+            Output file size in bytes. Single-output completion only — mutually
+            exclusive with `outputs[]`. Absent for multi-output operations and
+            on failure.
           example: 2097152
+
+        # Multi-output success fields (per ADR-0009 MultiOutputCompletion)
+        outputs:
+          type: array
+          minItems: 1
+          maxItems: 200
+          description: |
+            Per-output details for multi-output operations (e.g. convert
+            PDF->image emits one entry per page). Mutually exclusive with
+            top-level `output_key` / `output_size_bytes` on completion. MAY
+            be present on failure as informational data showing partial
+            results; consumers MUST NOT treat those as usable. See ADR-0009.
+
+            **`maxItems: 200`** is a worst-case transport-layer defence
+            against SQS/SNS's 256 KiB payload cap. Worst-case per-entry size
+            is ~1080 bytes (1024-char `output_key` at the S3 hard limit + ~55
+            bytes JSON envelope per entry); 200 entries × 1080 bytes ≈ 216
+            KB, leaving ~40 KB headroom for the outer message envelope
+            (`job_id`, `operation_id`, `metrics`, `total_output_size_bytes`,
+            etc.). Typical Lambda-generated keys are ~110 chars so the
+            realistic per-message size stays well under the cap; this bound
+            defends against the worst case, not the typical case.
+
+            Operations that could theoretically exceed 200 outputs from one
+            logical operation (e.g. convert PDF->image on a >200-page PDF)
+            MUST enforce a corresponding upper bound on the input side
+            (per-operation page-range / count option in the operation's
+            `schemas/operations/*.yaml`); the transport bound is defence in
+            depth, not the primary user-facing limit. See ADR-0009 §D5.
+          items:
+            $ref: '#/components/schemas/OperationResultOutputEntry'
+        total_output_size_bytes:
+          type: integer
+          format: int64
+          minimum: 0
+          description: |
+            Aggregate size of all `outputs[]` in bytes. Equals
+            `sum(outputs[].output_size_bytes)`. Emitted only with multi-output
+            completion. Used for billing and aggregate observability. Per
+            ADR-0009 §D4, this is denormalised against the per-entry sum;
+            consumers SHOULD trust the per-entry sum if the two disagree (and
+            log a warning).
+          example: 786432
+
         metrics:
           $ref: '#/components/schemas/OperationMetrics'
 
@@ -1787,6 +2747,156 @@ components:
           description: Progress percentage when the operation failed (failed only)
           example: 10
 
+    OperationResultOutputEntry:
+      type: object
+      description: |
+        Single entry in the `OperationResult.outputs[]` array for multi-output
+        operations. Per ADR-0009.
+
+        Each entry represents one output file produced by the operation, with
+        its S3 key, size, and an indexing field (`page_index` for PDF-page
+        outputs, `position` for generic ordinals). Per ADR-0009 §D2, an
+        operation uses **one** indexing field consistently for all its
+        outputs; the two are mutually exclusive within an entry.
+      required:
+        - output_key
+        - output_size_bytes
+      oneOf:
+        - title: PageIndexed
+          description: PDF-page output (convert PDF->image).
+          required: [page_index]
+          not: { required: [position] }
+        - title: PositionIndexed
+          description: Generic ordinal output (frame strip, chapter split).
+          required: [position]
+          not: { required: [page_index] }
+        - title: Unindexed
+          description: |
+            Output without an explicit indexing field. Reserved for future
+            operations that index by something other than page/position.
+            Schema-valid but not currently emitted by any operation.
+          not:
+            anyOf:
+              - required: [page_index]
+              - required: [position]
+      properties:
+        output_key:
+          type: string
+          maxLength: 1024
+          description: |
+            S3 key of this individual output file. `maxLength: 1024` matches
+            the S3 object key hard limit; keys longer than this are rejected
+            by S3 itself, so this is a contract-level mirror of the upstream
+            constraint.
+          example: "jobs/018f9c42-5d6b/018f9c42-5d6b-e200/page-001.png"
+        output_size_bytes:
+          type: integer
+          format: int64
+          minimum: 0
+          description: Size of this individual output file in bytes.
+          example: 262144
+        page_index:
+          type: integer
+          minimum: 1
+          description: |
+            1-based page number for PDF-page outputs. Gapless within an
+            operation (an N-page conversion emits `page_index` 1..N). Mutually
+            exclusive with `position`. Per ADR-0009 §D2.
+          example: 1
+        position:
+          type: integer
+          minimum: 0
+          description: |
+            0-based ordinal for non-PDF multi-output operations (e.g. frame
+            strip, chapter split). Mutually exclusive with `page_index`.
+            Per ADR-0009 §D2.
+          example: 0
+
+    # ============================================
+    # WORKFLOW STATE CHANGED (per ticket I24)
+    # ============================================
+
+    WorkflowStateChanged:
+      type: object
+      description: |
+        Workflow-level state-transition event published by the API
+        when a workflow's `status` changes. Per ticket
+        [I24 `e50uXLcl`](https://trello.com/c/e50uXLcl) + plan v5
+        round 9.
+
+        Emitted on every transition (e.g. `pending → in_progress`,
+        `in_progress → paused_insufficient_credits`,
+        `paused_insufficient_credits → in_progress` after resume,
+        `in_progress → cancelled`, `paused_insufficient_credits →
+        expired`, the terminal `completed` / `failed` /
+        `partially_failed`). The SSE stream's
+        `workflow.completed` / `workflow.failed` /
+        `workflow.partially_failed` events are the frontend-facing
+        subset of these transitions; this event covers the full
+        lifecycle for backend consumers (audit log, dashboards,
+        webhook subscribers).
+
+        `reason` is a free-form string carrying advisory cause —
+        same opacity precedent as `OperationMetrics.re_encode_reason`
+        (per I16-CONS) and `SseWorkflowTerminalData.reason` (per
+        I27). `billing_effect` is present only on transitions to
+        `cancelled` or `expired` — both states release any unspent
+        reservation portion (see `WorkflowCancelBillingEffect` in
+        `openapi/api.yaml`).
+      required:
+        - workflow_id
+        - previous_status
+        - current_status
+        - changed_at
+      properties:
+        workflow_id:
+          type: string
+          format: uuid
+          description: UUID-v7 workflow identifier.
+        previous_status:
+          type: string
+          enum:
+            - pending
+            - in_progress
+            - completed
+            - failed
+            - partially_failed
+            - paused_insufficient_credits
+            - cancelled
+            - expired
+        current_status:
+          type: string
+          enum:
+            - pending
+            - in_progress
+            - completed
+            - failed
+            - partially_failed
+            - paused_insufficient_credits
+            - cancelled
+            - expired
+        changed_at:
+          type: string
+          format: date-time
+        reason:
+          type: string
+          description: |
+            Optional advisory reason. Free-form string; not enumerated.
+            Examples: `all jobs completed successfully`,
+            `next reservation exceeded available_credits` (when
+            transitioning to `paused_insufficient_credits`),
+            `caller requested cancel`, `paused_insufficient_credits
+            past expires_at`, `dispatch timeout`.
+        billing_effect:
+          type: string
+          enum:
+            - unspent_reservation_released
+            - none
+          description: |
+            Present on transitions to `cancelled` or `expired`.
+            Mirrors `WorkflowCancelBillingEffect` from
+            `openapi/api.yaml`. Absent on other transitions.
+
     # ============================================
     # METRICS
     # ============================================
@@ -1801,7 +2911,7 @@ components:
         original_size_bytes:
           type: integer
           format: int64
-          description: Original file size in bytes (compress, convert, thumbnail, watermark)
+          description: Original file size in bytes (compress, convert, thumbnail, image_watermark, text_watermark)
           example: 5242880
         output_size_bytes:
           type: integer
@@ -1835,6 +2945,381 @@ components:
           format: int64
           description: Sum of all input file sizes (merge, archive)
           example: 52428800
+        re_encode_decision:
+          # Named schema lifted from inline per ticket QokFw8VR.
+          $ref: '#/components/schemas/ReEncodeDecision'
+        re_encode_reason:
+          type: string
+          description: |
+            Advisory explanation for `re_encode_decision` (e.g.
+            `all_inputs_compatible`, `explicit_always_mode`,
+            `input_codec_mismatch`, `input_framerate_mismatch`).
+            Free-form string — not an enum — so the Lambda can emit
+            human-readable diagnostics that evolve without contract
+            churn (compatibility-probe algorithm stays opaque per
+            plan v5 §F8.2). Per ticket I16-CONS.
+          example: input_codec_mismatch
+
+    # ============================================
+    # UPLOAD PROBE PAYLOADS (per ticket vBlEurU7)
+    # ============================================
+
+    UploadProbeRequest:
+      type: object
+      description: |
+        Request payload for the upload-probe Lambda. Shared between
+        the synchronous Lambda RequestResponse path (backing
+        `POST /api/uploads/{id}/probe`) and the asynchronous
+        SNS->SQS->Lambda path (eager `rich_metadata` enrichment on
+        upload finalize). Per ticket
+        [vBlEurU7](https://trello.com/c/vBlEurU7) +
+        [rdBHmTfa](https://trello.com/c/rdBHmTfa).
+
+        The Lambda detects which path it is on from the AWS event
+        source structure — there is no flag in the payload that
+        distinguishes sync vs async. The shape is intentionally
+        small so SDK generators emit a single typed binding the API
+        layer can construct from either invocation path.
+      required:
+        - file_id
+        - source_bucket
+        - source_key
+        - file_type
+        - idempotency_key
+      properties:
+        file_id:
+          type: string
+          format: uuid
+          description: |
+            Upload file identifier (UUID v7). Mirrors the path
+            parameter on `POST /api/uploads/{id}/probe` for the sync
+            path and the upload row's primary key for the async path.
+          example: "019539ab-1111-7000-8000-000000000010"
+        source_bucket:
+          type: string
+          description: |
+            S3 bucket containing the uploaded file. Always the
+            tenant-scoped input bucket
+            (`gisl-{env}-{region}-input`).
+          example: "gisl-stg-euw1-input"
+        source_key:
+          type: string
+          description: |
+            S3 key of the uploaded file under `source_bucket`.
+          example: "uploads/019539ab-1111-7000-8000-000000000010/clip.mp4"
+        file_type:
+          type: string
+          description: |
+            MIME type of the uploaded file (e.g. `video/mp4`,
+            `audio/mpeg`, `application/pdf`) as recorded on the
+            upload row at finalize time. Field name follows the
+            AsyncAPI events.yaml convention (`OperationRequest.file_type`
+            and the rest of the message-payload schemas in this spec
+            consistently use `file_type` for MIME, even though
+            `openapi/api.yaml` uses `mime_type` for the same concept
+            on the REST surface). The probe uses this as a hint for
+            which extractor pipeline to run; mismatches against the
+            actual container surface as `format_mismatch` in the
+            completion's `error_code`.
+          example: "video/mp4"
+        idempotency_key:
+          type: string
+          minLength: 1
+          maxLength: 200
+          description: |
+            Caller-supplied idempotency token. Echoed back on the
+            `UploadProbeCompletion` (async branch) so the API
+            consumer can deduplicate against the upload row.
+
+            Conventions:
+            - Sync path: typically the `file_id` itself, since the
+              probe is cached server-side per upload (see
+              `UploadProbeMediaMetadata.probed_at` description in
+              `openapi/api.yaml`).
+            - Async path: the upload finalize event identifier
+              (e.g. `upload-finalize:{file_id}`) so retries of the
+              same finalize event collapse to a single completion.
+          example: "upload-finalize:019539ab-1111-7000-8000-000000000010"
+        requested_at:
+          type: string
+          format: date-time
+          description: |
+            ISO-8601 timestamp at which the probe request was issued.
+            Optional; populated when the API publisher records it
+            for log correlation. Not used by the Lambda for any
+            decision.
+          example: "2026-05-06T13:50:00Z"
+
+    UploadProbeCompletion:
+      type: object
+      description: |
+        Completion payload published by the upload-probe Lambda to
+        the `upload-probe-completions` SQS queue on the async
+        branch. Mirrors `UploadProbeResponse` (`openapi/api.yaml`)
+        for the success case and additionally carries failure
+        fields (`error_code`, `error_message`) so the API consumer
+        can persist Lambda-side failures (S3 download failed,
+        decoder crashed, etc.) on the upload row alongside
+        successful probes.
+
+        **Conditional schema (mirrors `OperationResult`):**
+        - When `error_code` is **absent**, the payload is treated as
+          a successful probe and `probe_status`,
+          `processing_class_pre_assignment`, and `media_metadata`
+          are REQUIRED.
+        - When `error_code` is **present**, the payload is treated as
+          a Lambda-side failure and only `error_code` +
+          `error_message` are REQUIRED on top of the always-required
+          identification + provenance fields. `probe_status` and
+          peers MAY be absent in this case.
+
+        Note that `probe_status: corrupt` / `unsupported_codec` /
+        `missing_metadata` are **successful** probes that report an
+        unhealthy file — they do NOT populate `error_code`. Reserve
+        `error_code` for "the probe pipeline itself failed".
+
+        Sync invocations do not produce this shape — they return
+        `UploadProbeResponse` directly.
+      required:
+        - file_id
+        - idempotency_key
+        - probed_at
+        - probe_version
+      if:
+        not:
+          required:
+            - error_code
+      then:
+        required:
+          - probe_status
+          - processing_class_pre_assignment
+          - media_metadata
+      else:
+        required:
+          - error_code
+          - error_message
+      properties:
+        file_id:
+          type: string
+          format: uuid
+          description: Upload file identifier (UUID v7) — correlation key.
+          example: "019539ab-1111-7000-8000-000000000010"
+        idempotency_key:
+          type: string
+          description: |
+            Echoed from the originating `UploadProbeRequest` for
+            deduplication on the API consumer side.
+          example: "upload-finalize:019539ab-1111-7000-8000-000000000010"
+        probe_status:
+          $ref: '#/components/schemas/UploadProbeStatus'
+        processing_class_pre_assignment:
+          $ref: '#/components/schemas/UploadProbeProcessingClass'
+        media_metadata:
+          $ref: '#/components/schemas/UploadProbeMediaMetadata'
+        error_code:
+          type: string
+          description: |
+            Machine-readable error code when the probe pipeline
+            itself failed. Reuses the same vocabulary as
+            `OperationResult.error_code` where applicable
+            (`s3_download_failed`, `s3_access_denied`, `timeout`,
+            `out_of_memory`, `decode_failed`, `processing_failed`,
+            `unknown`). Absent on successful probes — including
+            probes that report `probe_status: corrupt /
+            unsupported_codec / missing_metadata`, which are
+            successful probes about an unhealthy file.
+          example: "s3_download_failed"
+        error_message:
+          type: string
+          description: |
+            Human-readable error message paired with `error_code`.
+            Absent on successful probes.
+          example: "Failed to download source file from S3"
+        probed_at:
+          type: string
+          format: date-time
+          description: |
+            ISO-8601 timestamp at which the probe ran (or attempted
+            to run, for failure cases). Always present so the API
+            consumer can timestamp the upload row regardless of
+            outcome. For successful probes this matches
+            `media_metadata.probed_at`; the duplicate top-level
+            field exists so the failure case can still carry a
+            timestamp even when `media_metadata` is omitted.
+          example: "2026-05-06T13:50:01Z"
+        probe_version:
+          type: string
+          description: |
+            Semver of the upload-probe Lambda implementation that
+            produced this completion. Useful for cache invalidation
+            on the API side (re-probe when the prober ships a new
+            extractor) and for log correlation.
+          example: "1.0.0"
+
+    UploadProbeStatus:
+      type: string
+      description: |
+        Outcome of a successful preflight probe. Mirrors
+        `UploadProbeStatus` in `openapi/api.yaml` so SDK generators
+        consuming both specs emit a single typed binding.
+
+        Cross-spec parity is verified by
+        `tests/test_upload_probe_schemas.py` — the OpenAPI side is
+        the source of truth for the value set.
+
+        Note: a `probe_status` value here means the probe pipeline
+        succeeded. Lambda-side failures on the async branch are
+        signalled via `UploadProbeCompletion.error_code` and do not
+        require populating this field.
+      enum:
+        - ok
+        - corrupt
+        - unsupported_codec
+        - missing_metadata
+
+    UploadProbeProcessingClass:
+      type: string
+      description: |
+        Tier-aware pre-assignment. Mirrors
+        `UploadProbeProcessingClass` in `openapi/api.yaml` so SDK
+        generators consuming both specs emit a single typed binding.
+
+        Cross-spec parity is verified by
+        `tests/test_upload_probe_schemas.py` — the OpenAPI side is
+        the source of truth for the value set.
+      enum:
+        - short_form
+        - long_form
+        - blocked
+
+    UploadProbeMediaMetadata:
+      type: object
+      description: |
+        Probe-extracted media metadata. Mirrors
+        `UploadProbeMediaMetadata` in `openapi/api.yaml` so SDK
+        generators consuming both specs emit a single typed binding
+        instead of two `AnonymousSchema_N` placeholders.
+
+        AsyncAPI 3.0 cannot `$ref` across files into the OpenAPI
+        spec, so the shape is duplicated here verbatim. Cross-spec
+        parity is verified by
+        `tests/test_upload_probe_schemas.py` — the OpenAPI side is
+        the source of truth.
+
+        Schema covers the **union** of fields needed by the API's
+        `MetadataResponse` projection across video / audio /
+        document inputs (per the M2 Epic re-scope —
+        [`SrHwuvIl`](https://trello.com/c/SrHwuvIl) — which makes
+        this probe Lambda the universal non-image metadata source
+        feeding `rich_metadata`). The Lambda extractor only
+        populates fields it can derive from the actual container;
+        unrelated fields are simply omitted (absent fields are NOT
+        errors — they reflect "this metadata is not applicable /
+        not extractable" rather than "this metadata failed
+        validation"). `probed_at` is always present.
+      required:
+        - probed_at
+      properties:
+        duration_seconds:
+          type: integer
+          minimum: 0
+          description: Container-reported duration (audio + video).
+        width:
+          type: integer
+          minimum: 1
+          description: Pixel width (image + video; best-effort document).
+        height:
+          type: integer
+          minimum: 1
+          description: Pixel height (image + video; best-effort document).
+        codec:
+          type: string
+          description: |
+            Primary codec identifier as reported by the prober. For
+            video inputs this is the **video** codec; for audio-only
+            inputs this is the audio codec. For video files with
+            audio tracks, the audio codec is reported separately as
+            `audio_codec`. Examples: `h264`, `h265`, `vp9`, `av1`,
+            `aac`, `opus`, `mp3`. Not constrained to an enum — codec
+            strings evolve with FFmpeg releases (per ADR-0007 FFmpeg
+            pin) and SDKs should string-match.
+        audio_codec:
+          type: string
+          description: |
+            Audio codec for video files that carry an audio track.
+            Distinct from `codec` (which is the video codec for
+            video inputs). Absent for video-only / silent video
+            inputs and for audio-only inputs (audio-only inputs put
+            their codec under `codec`).
+        container:
+          type: string
+          description: |
+            Container format. Examples: `mp4`, `webm`, `mov`,
+            `mkv`, `mp3`, `wav`, `flac`. Not constrained to an
+            enum.
+        fps:
+          type: number
+          minimum: 0
+          description: |
+            Container-reported frame rate (video only). Number, not
+            integer — frame rates are commonly fractional (e.g.
+            `29.97`, `23.976`).
+        bitrate_bps:
+          type: integer
+          minimum: 0
+          description: |
+            Overall stream bitrate, **bits per second**. Units in
+            the field name, mirroring `duration_seconds`, so SDKs
+            avoid the kbps-vs-bps guessing trap. Container-reported
+            for video + audio.
+        audio_layout:
+          type: string
+          description: |
+            Channel layout, human-display form. Examples: `mono`,
+            `stereo`, `5.1`, `7.1`. Not constrained. Pairs with the
+            numeric `channels` field (which is what API consumers
+            project into `rich_metadata`); `audio_layout` is
+            preserved on the probe row for UI display ("5.1
+            surround") without forcing the UI to derive a label
+            from the integer.
+        channels:
+          type: integer
+          minimum: 1
+          description: |
+            Numeric audio channel count derived by the Lambda from
+            ffprobe output. Examples: `1` (mono), `2` (stereo), `6`
+            (5.1), `8` (7.1). Pairs with `audio_layout`. Audio +
+            video.
+        sample_rate_hz:
+          type: integer
+          minimum: 1
+          description: |
+            Audio sample rate, **Hertz**. Units in the field name,
+            mirroring `duration_seconds` / `bitrate_bps`. Examples:
+            `44100`, `48000`. Audio + video-with-audio.
+        page_count:
+          type: integer
+          minimum: 0
+          description: |
+            Document page count (PDF / EPUB / DOCX / XLSX / PPTX /
+            ODT / ODS / ODP). `0` for a document the prober opened
+            but found empty.
+        dpi:
+          type: integer
+          minimum: 1
+          description: |
+            Document resolution, single-axis (dots per inch).
+            Single-axis matches the existing `MetadataResponse`
+            contract on the OpenAPI side; the prober reports the
+            page-1 horizontal DPI when the document declares it,
+            otherwise omits the field.
+        probed_at:
+          type: string
+          format: date-time
+          description: |
+            ISO-8601 timestamp at which the probe ran. Idempotent
+            for the same `file_id` — subsequent probe calls return
+            the cached `probed_at`.
 
     # ============================================
     # ENUMS
@@ -1843,52 +3328,102 @@ components:
     OperationType:
       type: string
       description: |
-        Operation type. Appears both inside the message payload and, for
-        non-compression operations, as the SNS `operation_type` filter
-        attribute on the `operations` topic. Compression operations are
-        routed by `job_type` on the separate `job-requests` topic — see
-        `JobRequestAttributes` and the top-level `info.description`.
+        Operation type as carried inside the message **payload** body. This
+        enum is deliberately narrower than the SNS `operation_type`
+        MessageAttribute: the attribute enum permits per-media thumbnail
+        sub-types (`thumbnail_image`, `thumbnail_video`,
+        `thumbnail_document`, `thumbnail_office`) for routing on the
+        `operations` topic, but the payload body always carries the
+        semantic base value (`thumbnail`). See
+        `OperationRequestAttributes.operation_type` for the broader
+        attribute enum and the routing contract. Note that the attribute
+        values the publisher currently emits are governed by the
+        thumbnail migration-window note (top-level `info.description`
+        and `OperationRequestMessage.description`).
+
+        Compression operations are routed by `job_type` on the separate
+        `job-requests` topic — see `JobRequestAttributes` and the top-level
+        `info.description`.
 
         - `compress`: Reduce file size (image, video, audio, document).
           Routes via `job_type` on the `job-requests` topic.
-        - `thumbnail`: Legacy thumbnail value. Routes via
-          `operation_type=thumbnail` on the `operations` topic to the
-          legacy `ops-thumbnail` queue. Currently the only thumbnail
-          value the API publisher emits.
-        - `thumbnail_image`: Image thumbnail sub-type. Routes via
-          `operation_type=thumbnail_image` to `ops-thumbnail-image`.
-          Not yet emitted by the API publisher — adoption is a
-          follow-up API PR with input-MIME dispatch.
-        - `thumbnail_video`: Video thumbnail sub-type. Routes via
-          `operation_type=thumbnail_video` to `ops-thumbnail-video`.
-          Not yet emitted.
-        - `thumbnail_document`: PDF/EPUB thumbnail sub-type. Routes via
-          `operation_type=thumbnail_document` to `ops-thumbnail-document`.
-          Not yet emitted.
-        - `thumbnail_office`: Office document (DOCX/XLSX/PPTX/ODT/ODS/ODP)
-          thumbnail sub-type. Routes via `operation_type=thumbnail_office`
-          to `ops-thumbnail-office`. Not yet emitted.
-        - `watermark`: Apply branding/protection (image only). Routes
-          via `operation_type=watermark` to `ops-watermark`.
+        - `thumbnail`: Thumbnail generation. The payload always carries
+          the base value; the SNS `operation_type` attribute enum
+          additionally permits one of the four sub-type values
+          (`thumbnail_image`, `thumbnail_video`, `thumbnail_document`,
+          `thumbnail_office`) for routing the request to the matching
+          per-media Lambda. During the migration window, the legacy
+          `operation_type=thumbnail` attribute value also remains a
+          valid routing target (to `ops-thumbnail`). See the
+          migration-window note for which values the publisher currently
+          emits.
+        - `image_watermark`: Apply image overlay (file or external_source)
+          onto a base media asset (Path B multi-input with role
+          base+overlay per JobInputV2.role). Stable for static-image bases
+          (image/jpeg, image/png, image/webp); animated GIF and video
+          bases are advertised in `image_watermark.yaml` as `planned` via
+          parallel mime_groups (`image_gif`, `video`) — dispatch returns
+          `feature_not_available` (422) until Lambda support ships.
+          Routes via `operation_type=image_watermark` to
+          `ops-image-watermark`. Per ADR-0004 + I4-CONS + I5 (Trello
+          AKZiOXnd).
+        - `text_watermark`: Render a text overlay (Liberation Sans) onto
+          an image. Single-input. Routes via
+          `operation_type=text_watermark` to `ops-text-watermark`.
+          Per ADR-0004 + I4-CONS.
         - `convert`: Change file format (image, video, audio, document).
           Routes via `operation_type=convert` to `ops-convert`.
         - `merge`: Concatenate/combine multiple files (image, video,
-          audio, document/PDF). Routes via `operation_type=merge` to
-          `ops-merge`. A single Lambda handles all merge output types.
+          audio). Image inputs merge into animated GIF or slideshow
+          video; image collage/grid and PDF concatenation are not
+          supported by the V1 Lambda. Routes via `operation_type=merge`
+          to `ops-merge`. A single Lambda handles the supported merge
+          output types.
         - `archive`: Bundle files into ZIP/tar.gz (media-agnostic).
           Routes via `operation_type=archive` to `ops-archive`. No
           `media_group` attribute is set for archive.
+        - `custom_luma`: Apply a caller-uploaded luma matte to a base
+          video for a custom luma-matte transition effect. Multi-input
+          (Path B with `role: base` + `role: transition_mask` per
+          `JobInputV2.role`). `availability: planned` +
+          `required_tier: pro` 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.
+          When Lambda support lands, routes via
+          `operation_type=custom_luma` to `ops-custom-luma`. Per ADR-
+          0004 + 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 (Path B with `role: base` +
+          `role: overlay` per `JobInputV2.role`). Both mime_groups
+          (`audio`, `video`) are `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. **NOT** the same as
+          `audio_watermark` (steganographic, owned by I20). Per ADR-
+          0004 + 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. Both mime_groups
+          (`audio`, `video` — embed in video's audio track) are
+          `availability: planned` + `required_tier: enterprise` per
+          the operation schema; the API rejects workflow-create with
+          `feature_not_available` (422) + `feature_tier_restricted`
+          (403) until the Lambda ships, so traffic does not reach SNS
+          today. Pairs with `POST /api/audio-watermark/decode` for
+          own-watermarks-only extraction. Per ADR-0004 + I20 (Trello
+          omiCq7Vn).
       enum:
         - compress
         - thumbnail
-        - thumbnail_image
-        - thumbnail_video
-        - thumbnail_document
-        - thumbnail_office
-        - watermark
+        - image_watermark
+        - text_watermark
         - convert
         - merge
         - archive
+        - custom_luma
+        - audio_overlay
+        - audio_watermark
 
     MediaGroup:
       type: string
@@ -1909,10 +3444,9 @@ components:
           ODS, ODP)
 
         For merge, derived from `output_type`:
-        - output_type=image or gif -> image
+        - output_type=gif -> image
         - output_type=video -> video
         - output_type=audio -> audio
-        - output_type=document -> document
 
         Omitted from the SNS attributes for archive (media-agnostic). The
         four thumbnail sub-types map to media_group as follows:
@@ -1935,30 +3469,101 @@ components:
         regardless of the `output_type` value — `output_type` is read by
         the merge Lambda to decide the internal encoding path and output
         format, not to influence SNS routing.
-        - `image`: Collage/grid (ImageMagick montage inside the merge Lambda)
         - `gif`: Animated GIF (ImageMagick convert inside the merge Lambda)
         - `video`: Slideshow from images or video concatenation (FFmpeg inside the merge Lambda)
         - `audio`: Audio concatenation (FFmpeg inside the merge Lambda)
-        - `document`: PDF concatenation (qpdf inside the merge Lambda)
       enum:
-        - image
         - gif
         - video
         - audio
-        - document
+
+    JobInputRole:
+      type: string
+      description: |
+        Role for role-based multi-input operations. Mirrors
+        `JobInputV2.role` in `openapi/api.yaml`:
+        - `image_watermark`: REQUIRED on each entry — exactly
+          one `base` + one `overlay` per job (per ticket I4-CONS).
+        - `custom_luma`: REQUIRED — exactly one `base` + one
+          `transition_mask` per job (per ticket I29).
+        - `audio_overlay`: REQUIRED — exactly one `base` + one
+          `overlay` per job (per ticket I19); reuses
+          `image_watermark`'s role values.
+        - `merge` / `archive`: omit (all inputs share the same
+          role). Future operations may widen this enum.
+
+        Named-schema form lifted from inline at `SourceEntry.role`
+        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).
+      enum:
+        - base
+        - overlay
+        - transition_mask
+
+    ReEncodeDecision:
+      type: string
+      description: |
+        Path chosen for `merge.video` when `re_encode_mode=auto`.
+        Server reports the actual path so callers can see why
+        `auto` took the slow path. Absent for non-`merge.video`
+        operations and for `merge.video` when `re_encode_mode` is
+        `always` or `never` (path was caller-fixed). Per ticket
+        I16-CONS (Trello 7nCZXEru). Workflow-create-time surface
+        on `processing_plan.jobs[]` lands with I15-CONS
+        (Trello YZpBKzOM).
+
+        Named-schema form lifted from inline at
+        `OperationMetrics.re_encode_decision` per ticket QokFw8VR.
+      enum:
+        - stream_copy
+        - re_encode
 
     ProgressStatus:
       type: string
       description: |
-        Status values for progress updates (non-terminal):
-        - started: Lambda picked up the operation
-        - downloading: Downloading source file(s) from S3
-        - processing: Actively processing (compressing, merging, etc.)
-        - uploading: Uploading result to S3
+        Status values for progress updates (non-terminal). Backwards-
+        compatibly extended for long-form video operations per ticket
+        [I27 `1R3K3bsG`](https://trello.com/c/1R3K3bsG) + plan v5
+        §F8.3 round 10 — the `probing` / `decoding` / `encoding`
+        statuses give callers visibility into long-form jobs that
+        internally process inputs sequentially without forcing
+        callers to decompose into multiple jobs.
+
+        Non-long-form operations continue to emit only `started` /
+        `downloading` / `processing` / `uploading` (the V1 pattern);
+        clients that don't need phase visibility can ignore the new
+        statuses without behavioural change.
+
+        - `started`: Lambda picked up the operation.
+        - `downloading`: Downloading source file(s) from S3.
+        - `probing`: Long-form video — server-side metadata probe
+          on inputs (codec / container / framerate / resolution
+          / pixel-format detection driving `re_encode_decision`).
+          Pairs with `phase_input_index` / `phase_total_inputs` so
+          the frontend can render "probing input 2/4". Per I15-CONS
+          / I16-CONS.
+        - `decoding`: Long-form video — decoding inputs ahead of
+          the encode pass. Pairs with `phase_*` fields.
+        - `processing`: Actively processing (compressing, merging,
+          watermarking, etc.). The catch-all phase used by
+          short-form operations and short-form-equivalent stages of
+          long-form operations. May pair with `phase_*` fields when
+          the operation is long-form.
+        - `encoding`: Long-form video — explicit encode-pass status
+          (vs the umbrella `processing`). Surfaces "encoding output
+          42%" when the encode pass is long enough to deserve
+          dedicated visibility. May pair with `phase_*` fields for
+          multi-output operations.
+        - `uploading`: Uploading result to S3.
       enum:
         - started
         - downloading
+        - probing
+        - decoding
         - processing
+        - encoding
         - uploading
 
     ResultStatus: