@giveitsmaller/contracts 0.2.0 → 0.3.0

package/asyncapi/events.yaml

@@ -0,0 +1,3617 @@
+asyncapi: 3.0.0
+info:
+  title: GISL Compression Events
+  version: 3.2.0
+  description: |
+    Asynchronous event contracts for the GISL (Give It Smaller) compression service.
+
+    **Architecture Overview — Dual-Family SNS Topology**
+
+    The API publishes operation requests to **two** SNS topics, split by semantic
+    family. Each topic uses a single-attribute filter policy; there is no
+    compound-filter routing anywhere in the live topology:
+
+    - **`gisl-{env}-{region}-job-requests`** — compression routing only.
+      Filter attribute: `job_type`. Subscriptions: four per-media-type queues
+      (`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, image_watermark, text_watermark, merge, archive, convert,
+      custom_luma, audio_overlay, audio_watermark). Filter attribute:
+      `operation_type`. Subscriptions: one queue per operation type, plus four
+      thumbnail sub-type queues during the migration window. `custom_luma`,
+      `audio_overlay`, and `audio_watermark` are `availability: planned`
+      (per [I29](https://trello.com/c/EPUE5Vs1) +
+      [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):
+
+    - For `operation_type == compress`: publish to the `job-requests` topic
+      with a single `job_type = {mediaGroup}` message attribute. Do **not**
+      set `operation_type` or `media_group` as attributes on this branch —
+      the media group is encoded as `job_type` and no other attribute is
+      used as a filter on this topic.
+    - For all other operation types: publish to the `operations` topic with
+      `operation_type = {type}` as the filter attribute. Additionally, set
+      `media_group = {mediaGroup}` as an informational message attribute
+      where a media group is meaningful (omit for archive). This second
+      attribute is **not** used as an SNS filter — it is preserved for
+      consumer observability and log correlation.
+
+    `media_group` is never a field in the message payload body. It exists
+    only as an SNS MessageAttribute on the `operations` topic branch.
+
+    **Thumbnail migration window.** The terraform topology has both the
+    legacy `ops-thumbnail` queue and four new sub-type queues
+    (`ops-thumbnail-{image,video,document,office}`) live simultaneously.
+    The API publisher currently emits the legacy `operation_type=thumbnail`
+    only; adoption of the four sub-type values (`thumbnail_image`,
+    `thumbnail_video`, `thumbnail_document`, `thumbnail_office`) is a
+    follow-up API PR. Both routing targets are documented in this contract
+    because both are valid during the migration.
+
+    **Notifications (Lambda -> API).** Lambda functions publish progress
+    and result notifications to the FIFO SNS topic
+    `gisl-{env}-{region}-notifications-operations.fifo`. The API consumes
+    from the corresponding FIFO SQS queue via a Raw Message Delivery
+    subscription. This notification path is unchanged from previous
+    releases.
+
+    **Lambda inventory** (post Option A):
+
+    - **Jobs family** (compression, 4 Lambdas), routed by `job_type`:
+      `compression-image`, `compression-video`, `compression-audio`,
+      `compression-document`. Each handles `compress` only for its media
+      type.
+    - **Operations family** (non-compression), routed by `operation_type`:
+      `operation-thumbnail` (legacy, retiring after migration),
+      `operation-thumbnail-image`, `operation-thumbnail-video`,
+      `operation-thumbnail-document`, `operation-thumbnail-office`,
+      `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**
+
+    - `JobRequest`: API -> compression Lambda (via `job-requests` topic).
+    - `OperationRequest`: API -> non-compression Lambda (via `operations`
+      topic).
+    - `OperationProgress`: Lambda -> API (progress updates, stored in Redis).
+    - `OperationResult`: Lambda -> API (terminal state, stored in DB).
+
+    `JobRequest` and `OperationRequest` share the same payload schema
+    (`OperationRequest`). They differ only in the SNS message attributes set
+    as headers, captured in two separate header schemas (`JobRequestAttributes`
+    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
+    protocol: sqs
+    description: LocalStack for local development
+  staging:
+    host: sqs.eu-west-1.amazonaws.com
+    protocol: sqs
+    description: AWS SQS - Staging environment
+
+defaultContentType: application/json
+
+channels:
+  # ============================================
+  # SNS REQUEST TOPICS (API -> Lambda)
+  # ============================================
+
+  jobRequestsTopic:
+    address: gisl-{env}-{region}-job-requests
+    description: |
+      SNS topic where the API publishes **compression** operation requests.
+      Filter attribute: `job_type` (single-attribute filter policy, not
+      compound). Subscriptions fan out to four per-media-type compression
+      queues, keyed by `job_type` value.
+
+      **Filter vocabulary:**
+      - `job_type = image` -> `jobs-image` queue
+      - `job_type = video` -> `jobs-video` queue
+      - `job_type = audio` -> `jobs-audio` queue
+      - `job_type = document` -> `jobs-document` queue
+
+      The API's Option A publisher sets only `job_type` as a message
+      attribute on this branch. `operation_type` and `media_group` are
+      **not** set on this branch — the media group is encoded as
+      `job_type` and no other attribute is used as a filter on this topic.
+      See the `publishJobRequest` operation below for the publisher
+      branching rule.
+    parameters:
+      env:
+        description: Environment (local, stg, prod)
+      region:
+        description: AWS region abbreviation (euw1, use1, etc.)
+    messages:
+      jobRequest:
+        $ref: '#/components/messages/JobRequestMessage'
+
+  operationsTopic:
+    address: gisl-{env}-{region}-operations
+    description: |
+      SNS topic where the API publishes **non-compression** operation
+      requests (thumbnail, image_watermark, text_watermark, merge, archive, convert, custom_luma, audio_overlay, audio_watermark). Filter
+      attribute: `operation_type` (single-attribute filter policy).
+      Subscriptions fan out to per-operation-type queues, keyed by
+      `operation_type` value.
+
+      **Filter vocabulary:**
+      - `operation_type = thumbnail` -> `ops-thumbnail` queue (legacy)
+      - `operation_type = thumbnail_image` -> `ops-thumbnail-image` queue
+      - `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 = 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**
+      message attribute where a media group is meaningful (omitted for
+      archive). `media_group` is **not** used by SNS as a routing filter
+      on this topic — it is preserved for consumer observability and log
+      correlation. See the `publishOperationRequest` operation below for
+      the publisher branching rule.
+
+      **Thumbnail migration window.** The legacy `ops-thumbnail` queue and
+      the four sub-type queues are all live simultaneously. The API
+      publisher currently emits `operation_type=thumbnail` (legacy);
+      adoption of the four sub-type values is a follow-up API PR. Both
+      paths are valid routing targets today.
+    parameters:
+      env:
+        description: Environment (local, stg, prod)
+      region:
+        description: AWS region abbreviation (euw1, use1, etc.)
+    messages:
+      operationRequest:
+        $ref: '#/components/messages/OperationRequestMessage'
+
+  # ============================================
+  # JOBS FAMILY - COMPRESSION QUEUES (per media type)
+  # ============================================
+
+  jobsImage:
+    address: gisl-{env}-{region}-jobs-image
+    description: |
+      SQS queue for image compression jobs.
+      Subscribed to the `job-requests` SNS topic with filter
+      `job_type = image`. Handles `compress` only for image inputs.
+    parameters:
+      env:
+        description: Environment (local, stg, prod)
+      region:
+        description: AWS region abbreviation (euw1, use1, etc.)
+    messages:
+      jobRequest:
+        $ref: '#/components/messages/JobRequestMessage'
+
+  jobsVideo:
+    address: gisl-{env}-{region}-jobs-video
+    description: |
+      SQS queue for video compression jobs.
+      Subscribed to the `job-requests` SNS topic with filter
+      `job_type = video`. Handles `compress` only for video inputs.
+    parameters:
+      env:
+        description: Environment (local, stg, prod)
+      region:
+        description: AWS region abbreviation (euw1, use1, etc.)
+    messages:
+      jobRequest:
+        $ref: '#/components/messages/JobRequestMessage'
+
+  jobsAudio:
+    address: gisl-{env}-{region}-jobs-audio
+    description: |
+      SQS queue for audio compression jobs.
+      Subscribed to the `job-requests` SNS topic with filter
+      `job_type = audio`. Handles `compress` only for audio inputs.
+    parameters:
+      env:
+        description: Environment (local, stg, prod)
+      region:
+        description: AWS region abbreviation (euw1, use1, etc.)
+    messages:
+      jobRequest:
+        $ref: '#/components/messages/JobRequestMessage'
+
+  jobsDocument:
+    address: gisl-{env}-{region}-jobs-document
+    description: |
+      SQS queue for document compression jobs.
+      Subscribed to the `job-requests` SNS topic with filter
+      `job_type = document`. Handles `compress` only for document inputs.
+    parameters:
+      env:
+        description: Environment (local, stg, prod)
+      region:
+        description: AWS region abbreviation (euw1, use1, etc.)
+    messages:
+      jobRequest:
+        $ref: '#/components/messages/JobRequestMessage'
+
+  # ============================================
+  # JOBS FAMILY - DEAD LETTER QUEUES
+  # ============================================
+
+  jobsImageDlq:
+    address: gisl-{env}-{region}-jobs-image-dlq
+    description: DLQ for failed image compression jobs. Messages land here after 5 failed processing attempts.
+    parameters:
+      env:
+        description: Environment (local, stg, prod)
+      region:
+        description: AWS region abbreviation (euw1, use1, etc.)
+
+  jobsVideoDlq:
+    address: gisl-{env}-{region}-jobs-video-dlq
+    description: DLQ for failed video compression jobs. Messages land here after 5 failed processing attempts.
+    parameters:
+      env:
+        description: Environment (local, stg, prod)
+      region:
+        description: AWS region abbreviation (euw1, use1, etc.)
+
+  jobsAudioDlq:
+    address: gisl-{env}-{region}-jobs-audio-dlq
+    description: DLQ for failed audio compression jobs. Messages land here after 5 failed processing attempts.
+    parameters:
+      env:
+        description: Environment (local, stg, prod)
+      region:
+        description: AWS region abbreviation (euw1, use1, etc.)
+
+  jobsDocumentDlq:
+    address: gisl-{env}-{region}-jobs-document-dlq
+    description: DLQ for failed document compression jobs. Messages land here after 5 failed processing attempts.
+    parameters:
+      env:
+        description: Environment (local, stg, prod)
+      region:
+        description: AWS region abbreviation (euw1, use1, etc.)
+
+  # ============================================
+  # OPS FAMILY - NON-COMPRESSION OPERATION QUEUES
+  # ============================================
+
+  opsThumbnail:
+    address: gisl-{env}-{region}-ops-thumbnail
+    description: |
+      SQS queue for legacy thumbnail operations.
+      Subscribed to the `operations` SNS topic with filter
+      `operation_type = thumbnail`.
+
+      **Migration window**: This is the legacy routing target and is
+      currently the only one the API publisher emits for (via
+      `operation_type=thumbnail`). It handles thumbnail requests for all
+      media types. Retirement is planned after the API publisher adopts
+      the four sub-type values (`thumbnail_image`, `thumbnail_video`,
+      `thumbnail_document`, `thumbnail_office`) in a follow-up API PR.
+    parameters:
+      env:
+        description: Environment (local, stg, prod)
+      region:
+        description: AWS region abbreviation (euw1, use1, etc.)
+    messages:
+      operationRequest:
+        $ref: '#/components/messages/OperationRequestMessage'
+
+  opsThumbnailImage:
+    address: gisl-{env}-{region}-ops-thumbnail-image
+    description: |
+      SQS queue for image thumbnail operations.
+      Subscribed to the `operations` SNS topic with filter
+      `operation_type = thumbnail_image`. Backed by the Rust image
+      thumbnail Lambda (`operation-thumbnail-image`).
+
+      Not yet receiving traffic — the API publisher currently emits
+      `operation_type=thumbnail` (legacy) and will flip to
+      `thumbnail_image` after a follow-up API PR adds input-MIME dispatch.
+    parameters:
+      env:
+        description: Environment (local, stg, prod)
+      region:
+        description: AWS region abbreviation (euw1, use1, etc.)
+    messages:
+      operationRequest:
+        $ref: '#/components/messages/OperationRequestMessage'
+
+  opsThumbnailVideo:
+    address: gisl-{env}-{region}-ops-thumbnail-video
+    description: |
+      SQS queue for video thumbnail operations.
+      Subscribed to the `operations` SNS topic with filter
+      `operation_type = thumbnail_video`. Backed by the FFmpeg video
+      thumbnail Lambda (`operation-thumbnail-video`).
+
+      Not yet receiving traffic — the API publisher currently emits
+      `operation_type=thumbnail` (legacy) and will flip to
+      `thumbnail_video` after a follow-up API PR adds input-MIME dispatch.
+    parameters:
+      env:
+        description: Environment (local, stg, prod)
+      region:
+        description: AWS region abbreviation (euw1, use1, etc.)
+    messages:
+      operationRequest:
+        $ref: '#/components/messages/OperationRequestMessage'
+
+  opsThumbnailDocument:
+    address: gisl-{env}-{region}-ops-thumbnail-document
+    description: |
+      SQS queue for PDF/EPUB document thumbnail operations.
+      Subscribed to the `operations` SNS topic with filter
+      `operation_type = thumbnail_document`. Backed by the Ghostscript
+      document thumbnail Lambda (`operation-thumbnail-document`).
+
+      Not yet receiving traffic — the API publisher currently emits
+      `operation_type=thumbnail` (legacy) and will flip to
+      `thumbnail_document` after a follow-up API PR adds input-MIME
+      dispatch.
+    parameters:
+      env:
+        description: Environment (local, stg, prod)
+      region:
+        description: AWS region abbreviation (euw1, use1, etc.)
+    messages:
+      operationRequest:
+        $ref: '#/components/messages/OperationRequestMessage'
+
+  opsThumbnailOffice:
+    address: gisl-{env}-{region}-ops-thumbnail-office
+    description: |
+      SQS queue for office document thumbnail operations
+      (DOCX, XLSX, PPTX, ODT, ODS, ODP).
+      Subscribed to the `operations` SNS topic with filter
+      `operation_type = thumbnail_office`. Backed by the LibreOffice
+      thumbnail Lambda (`operation-thumbnail-office`).
+
+      Not yet receiving traffic — the API publisher currently emits
+      `operation_type=thumbnail` (legacy) and will flip to
+      `thumbnail_office` after a follow-up API PR adds input-MIME
+      dispatch.
+    parameters:
+      env:
+        description: Environment (local, stg, prod)
+      region:
+        description: AWS region abbreviation (euw1, use1, etc.)
+    messages:
+      operationRequest:
+        $ref: '#/components/messages/OperationRequestMessage'
+
+  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 text_watermark operations (single-input, image-only).
+      Subscribed to the `operations` SNS topic with filter
+      `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)
+      region:
+        description: AWS region abbreviation (euw1, use1, etc.)
+    messages:
+      operationRequest:
+        $ref: '#/components/messages/OperationRequestMessage'
+
+  opsMerge:
+    address: gisl-{env}-{region}-ops-merge
+    description: |
+      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 (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)
+      region:
+        description: AWS region abbreviation (euw1, use1, etc.)
+    messages:
+      operationRequest:
+        $ref: '#/components/messages/OperationRequestMessage'
+
+  opsArchive:
+    address: gisl-{env}-{region}-ops-archive
+    description: |
+      SQS queue for archive operations (ZIP/tar.gz bundling).
+      Subscribed to the `operations` SNS topic with filter
+      `operation_type = archive`. Media-agnostic: accepts mixed input
+      types. Backed by the archive Lambda (`operation-archive`).
+    parameters:
+      env:
+        description: Environment (local, stg, prod)
+      region:
+        description: AWS region abbreviation (euw1, use1, etc.)
+    messages:
+      operationRequest:
+        $ref: '#/components/messages/OperationRequestMessage'
+
+  opsConvert:
+    address: gisl-{env}-{region}-ops-convert
+    description: |
+      SQS queue for convert operations (format conversion).
+      Subscribed to the `operations` SNS topic with filter
+      `operation_type = convert`. Handles format conversion across all
+      media types (image, video, audio, document). Backed by the convert
+      Lambda (`operation-convert`).
+    parameters:
+      env:
+        description: Environment (local, stg, prod)
+      region:
+        description: AWS region abbreviation (euw1, use1, etc.)
+    messages:
+      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
+  # ============================================
+
+  opsThumbnailDlq:
+    address: gisl-{env}-{region}-ops-thumbnail-dlq
+    description: DLQ for failed legacy thumbnail operations. Messages land here after 5 failed processing attempts.
+    parameters:
+      env:
+        description: Environment (local, stg, prod)
+      region:
+        description: AWS region abbreviation (euw1, use1, etc.)
+
+  opsThumbnailImageDlq:
+    address: gisl-{env}-{region}-ops-thumbnail-image-dlq
+    description: DLQ for failed image thumbnail operations. Messages land here after 5 failed processing attempts.
+    parameters:
+      env:
+        description: Environment (local, stg, prod)
+      region:
+        description: AWS region abbreviation (euw1, use1, etc.)
+
+  opsThumbnailVideoDlq:
+    address: gisl-{env}-{region}-ops-thumbnail-video-dlq
+    description: DLQ for failed video thumbnail operations. Messages land here after 5 failed processing attempts.
+    parameters:
+      env:
+        description: Environment (local, stg, prod)
+      region:
+        description: AWS region abbreviation (euw1, use1, etc.)
+
+  opsThumbnailDocumentDlq:
+    address: gisl-{env}-{region}-ops-thumbnail-document-dlq
+    description: DLQ for failed document thumbnail operations. Messages land here after 5 failed processing attempts.
+    parameters:
+      env:
+        description: Environment (local, stg, prod)
+      region:
+        description: AWS region abbreviation (euw1, use1, etc.)
+
+  opsThumbnailOfficeDlq:
+    address: gisl-{env}-{region}-ops-thumbnail-office-dlq
+    description: DLQ for failed office thumbnail operations. Messages land here after 5 failed processing attempts.
+    parameters:
+      env:
+        description: Environment (local, stg, prod)
+      region:
+        description: AWS region abbreviation (euw1, use1, etc.)
+
+  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)
+      region:
+        description: AWS region abbreviation (euw1, use1, etc.)
+
+  opsMergeDlq:
+    address: gisl-{env}-{region}-ops-merge-dlq
+    description: DLQ for failed merge operations. Messages land here after 5 failed processing attempts.
+    parameters:
+      env:
+        description: Environment (local, stg, prod)
+      region:
+        description: AWS region abbreviation (euw1, use1, etc.)
+
+  opsArchiveDlq:
+    address: gisl-{env}-{region}-ops-archive-dlq
+    description: DLQ for failed archive operations. Messages land here after 5 failed processing attempts.
+    parameters:
+      env:
+        description: Environment (local, stg, prod)
+      region:
+        description: AWS region abbreviation (euw1, use1, etc.)
+
+  opsConvertDlq:
+    address: gisl-{env}-{region}-ops-convert-dlq
+    description: DLQ for failed convert operations. Messages land here after 5 failed processing attempts.
+    parameters:
+      env:
+        description: Environment (local, stg, prod)
+      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)
+  # ============================================
+
+  notificationsOperationsTopic:
+    address: gisl-{env}-{region}-notifications-operations.fifo
+    description: |
+      FIFO SNS topic where Lambdas publish all operation notifications (progress and results).
+      API subscribes via FIFO SQS with Raw Message Delivery enabled.
+
+      **FIFO Publishing Requirements:**
+      - MessageGroupId: Use operation_id (ensures ordering per operation)
+      - MessageDeduplicationId: Not required (content-based deduplication enabled)
+    parameters:
+      env:
+        description: Environment (local, stg, prod)
+      region:
+        description: AWS region abbreviation (euw1, use1, etc.)
+    messages:
+      operationProgress:
+        $ref: '#/components/messages/OperationProgressMessage'
+      operationResult:
+        $ref: '#/components/messages/OperationResultMessage'
+
+  notificationsOperationsQueue:
+    address: gisl-{env}-{region}-notifications-operations.fifo
+    description: |
+      FIFO SQS queue subscribed to notifications-operations SNS topic.
+      Receives both OperationProgress and OperationResult messages.
+      Raw Message Delivery enabled (no SNS envelope).
+
+      FIFO ensures message ordering per operation (operation_id used as MessageGroupId).
+      This guarantees OperationProgress messages arrive before OperationResult.
+    parameters:
+      env:
+        description: Environment (local, stg, prod)
+      region:
+        description: AWS region abbreviation (euw1, use1, etc.)
+    messages:
+      operationProgress:
+        $ref: '#/components/messages/OperationProgressMessage'
+      operationResult:
+        $ref: '#/components/messages/OperationResultMessage'
+
+  notificationsOperationsDlq:
+    address: gisl-{env}-{region}-notifications-operations-dlq.fifo
+    description: DLQ for failed notification processing. Messages land here after 5 failed processing attempts.
+    parameters:
+      env:
+        description: Environment (local, stg, prod)
+      region:
+        description: AWS region abbreviation (euw1, use1, etc.)
+
+operations:
+  # ============================================
+  # PUBLISH OPERATIONS (API -> SNS)
+  # ============================================
+
+  publishJobRequest:
+    action: send
+    channel:
+      $ref: '#/channels/jobRequestsTopic'
+    summary: Publish a compression job request to the job-requests SNS topic.
+    description: |
+      Compression-branch publisher path. Invoked by the API for any
+      operation with `operation_type == compress`, regardless of media
+      type. The target SNS topic filters subscriptions on `job_type`
+      alone.
+
+      **Message attribute set on this branch:** `{job_type}` only. The
+      publisher does **not** set `operation_type` or `media_group` on
+      this branch — the media group is encoded as `job_type` and no
+      other attribute is used as a filter on this topic.
+
+      **`job_type` value derivation:** the API derives `job_type` from
+      its `OperationMediaGroupResolver` output
+      (`image` | `video` | `audio` | `document`) at publish time.
+
+      See `info.description` above for the full publisher branching rule.
+    messages:
+      - $ref: '#/channels/jobRequestsTopic/messages/jobRequest'
+
+  publishOperationRequest:
+    action: send
+    channel:
+      $ref: '#/channels/operationsTopic'
+    summary: Publish a non-compression operation request to the operations SNS topic.
+    description: |
+      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),
+      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
+      media-agnostic). `operation_type` is the filter attribute;
+      `media_group` is informational metadata preserved for consumer
+      observability and log correlation and is **not** used by SNS as a
+      routing filter.
+
+      See `info.description` above for the full publisher branching rule.
+    messages:
+      - $ref: '#/channels/operationsTopic/messages/operationRequest'
+
+  # ============================================
+  # CONSUME OPERATIONS - JOBS FAMILY (COMPRESSION)
+  # ============================================
+
+  consumeImageOperation:
+    action: receive
+    channel:
+      $ref: '#/channels/jobsImage'
+    summary: Process image compression job
+    description: |
+      The image compression Lambda consumes jobs for image inputs.
+      Handles `compress` only. Non-compression image operations
+      (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'
+
+  consumeVideoOperation:
+    action: receive
+    channel:
+      $ref: '#/channels/jobsVideo'
+    summary: Process video compression job
+    description: |
+      The video compression Lambda consumes jobs for video inputs.
+      Handles `compress` only. Non-compression video operations
+      (thumbnail, convert, merge) are routed to their respective queues
+      on the ops-family under the `operations` topic.
+    messages:
+      - $ref: '#/channels/jobsVideo/messages/jobRequest'
+
+  consumeAudioOperation:
+    action: receive
+    channel:
+      $ref: '#/channels/jobsAudio'
+    summary: Process audio compression job
+    description: |
+      The audio compression Lambda consumes jobs for audio inputs.
+      Handles `compress` only. Non-compression audio operations
+      (convert, merge) are routed to their respective queues on the
+      ops-family under the `operations` topic.
+    messages:
+      - $ref: '#/channels/jobsAudio/messages/jobRequest'
+
+  consumeDocumentOperation:
+    action: receive
+    channel:
+      $ref: '#/channels/jobsDocument'
+    summary: Process document compression job
+    description: |
+      The document compression Lambda consumes jobs for document inputs.
+      Handles `compress` only. Non-compression document operations
+      (thumbnail, convert, merge) are routed to their respective queues
+      on the ops-family under the `operations` topic.
+    messages:
+      - $ref: '#/channels/jobsDocument/messages/jobRequest'
+
+  # ============================================
+  # CONSUME OPERATIONS - OPS FAMILY (NON-COMPRESSION)
+  # ============================================
+
+  consumeThumbnailOperation:
+    action: receive
+    channel:
+      $ref: '#/channels/opsThumbnail'
+    summary: Process legacy thumbnail operation
+    description: |
+      The legacy thumbnail Lambda consumes thumbnail requests routed
+      by `operation_type=thumbnail`. Handles thumbnail generation for
+      all media types in a single Lambda. This is the current live
+      routing target for the API publisher; it will be retired after
+      the publisher adopts the four sub-type values.
+    messages:
+      - $ref: '#/channels/opsThumbnail/messages/operationRequest'
+
+  consumeThumbnailImageOperation:
+    action: receive
+    channel:
+      $ref: '#/channels/opsThumbnailImage'
+    summary: Process image thumbnail operation
+    description: |
+      The image thumbnail Lambda consumes thumbnail requests routed by
+      `operation_type=thumbnail_image`. Backed by a Rust image crate.
+      Not yet receiving traffic — see channel description.
+    messages:
+      - $ref: '#/channels/opsThumbnailImage/messages/operationRequest'
+
+  consumeThumbnailVideoOperation:
+    action: receive
+    channel:
+      $ref: '#/channels/opsThumbnailVideo'
+    summary: Process video thumbnail operation
+    description: |
+      The video thumbnail Lambda consumes thumbnail requests routed by
+      `operation_type=thumbnail_video`. Backed by FFmpeg. Not yet
+      receiving traffic — see channel description.
+    messages:
+      - $ref: '#/channels/opsThumbnailVideo/messages/operationRequest'
+
+  consumeThumbnailDocumentOperation:
+    action: receive
+    channel:
+      $ref: '#/channels/opsThumbnailDocument'
+    summary: Process document thumbnail operation
+    description: |
+      The document (PDF/EPUB) thumbnail Lambda consumes thumbnail
+      requests routed by `operation_type=thumbnail_document`. Backed by
+      Ghostscript. Not yet receiving traffic — see channel description.
+    messages:
+      - $ref: '#/channels/opsThumbnailDocument/messages/operationRequest'
+
+  consumeThumbnailOfficeOperation:
+    action: receive
+    channel:
+      $ref: '#/channels/opsThumbnailOffice'
+    summary: Process office document thumbnail operation
+    description: |
+      The office document (DOCX/XLSX/PPTX/ODT/ODS/ODP) thumbnail Lambda
+      consumes thumbnail requests routed by
+      `operation_type=thumbnail_office`. Backed by LibreOffice. Not yet
+      receiving traffic — see channel description.
+    messages:
+      - $ref: '#/channels/opsThumbnailOffice/messages/operationRequest'
+
+  consumeImageWatermarkOperation:
+    action: receive
+    channel:
+      $ref: '#/channels/opsImageWatermark'
+    summary: Process image_watermark operation
+    description: |
+      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/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
+    channel:
+      $ref: '#/channels/opsMerge'
+    summary: Process merge operation
+    description: |
+      The merge Lambda consumes merge requests routed by
+      `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'
+
+  consumeArchiveOperation:
+    action: receive
+    channel:
+      $ref: '#/channels/opsArchive'
+    summary: Process archive operation
+    description: |
+      The archive Lambda consumes archive requests routed by
+      `operation_type=archive`. Media-agnostic: bundles files of any
+      type into ZIP/tar.gz.
+    messages:
+      - $ref: '#/channels/opsArchive/messages/operationRequest'
+
+  consumeConvertOperation:
+    action: receive
+    channel:
+      $ref: '#/channels/opsConvert'
+    summary: Process convert operation
+    description: |
+      The convert Lambda consumes convert requests routed by
+      `operation_type=convert`. Handles format conversion across all
+      media types (image, video, audio, document).
+    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
+  # ============================================
+
+  publishOperationProgress:
+    action: send
+    channel:
+      $ref: '#/channels/notificationsOperationsTopic'
+    summary: Publish operation progress update
+    description: |
+      Lambda publishes progress updates during operation processing.
+      These are lightweight messages for real-time status tracking.
+    messages:
+      - $ref: '#/channels/notificationsOperationsTopic/messages/operationProgress'
+
+  publishOperationResult:
+    action: send
+    channel:
+      $ref: '#/channels/notificationsOperationsTopic'
+    summary: Publish operation result
+    description: |
+      Lambda publishes the final result when operation completes or fails.
+      This is a terminal message with full details.
+    messages:
+      - $ref: '#/channels/notificationsOperationsTopic/messages/operationResult'
+
+  consumeOperationNotifications:
+    action: receive
+    channel:
+      $ref: '#/channels/notificationsOperationsQueue'
+    summary: Consume operation notifications
+    description: |
+      API worker consumes both progress and result notifications from SQS.
+      - OperationProgress: Update Redis cache for real-time status (forwarded to frontend via SSE)
+      - OperationResult: Update database Operation entity, derive Job/Workflow status
+    messages:
+      - $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:
+    # ============================================
+    # JOB REQUEST MESSAGE (compression branch)
+    # ============================================
+
+    JobRequestMessage:
+      name: JobRequest
+      title: Compression Job Request
+      summary: Request to process a compression operation
+      description: |
+        Message sent by the API to request processing of a **compression**
+        operation. Published to the `job-requests` SNS topic; routed by the
+        single-attribute filter `job_type` to one of the four
+        per-media-type compression queues.
+
+        **SNS Message Attributes (routing):**
+        - `job_type`: always present. Values: `image`, `video`, `audio`,
+          `document`. Used by SNS as the filter attribute on the
+          `job-requests` topic.
+
+        No other message attributes are set on this branch by the API
+        publisher. `operation_type` and `media_group` are **not** set —
+        the media group is encoded as `job_type`.
+
+        **Payload:** uses the shared `OperationRequest` schema. For
+        compression, `operation_type` inside the payload is always
+        `compress`, `file_type` is set to the input MIME, and the
+        `source_bucket` / `source_key` fields identify the input.
+      contentType: application/json
+      headers:
+        $ref: '#/components/schemas/JobRequestAttributes'
+      payload:
+        $ref: '#/components/schemas/OperationRequest'
+      examples:
+        - name: Image Compression
+          summary: Compress a PNG image with lossy mode
+          headers:
+            job_type: "image"
+          payload:
+            job_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e112"
+            operation_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e200"
+            operation_type: "compress"
+            file_type: "image/png"
+            source_bucket: "gisl-stg-euw1-input"
+            source_key: "uploads/018f9c42-aabb/photo.png"
+            output_bucket: "gisl-stg-euw1-output"
+            output_key_prefix: "jobs/018f9c42-5d6b-7481-b3df-9fd0a0a5e112/018f9c42-5d6b-7481-b3df-9fd0a0a5e200/"
+            options:
+              mode: "lossy"
+              quality: 80
+              metadata: "copyright"
+        - name: Video Compression
+          summary: Compress an MP4 video
+          headers:
+            job_type: "video"
+          payload:
+            job_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e113"
+            operation_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e201"
+            operation_type: "compress"
+            file_type: "video/mp4"
+            source_bucket: "gisl-stg-euw1-input"
+            source_key: "uploads/018f9c42-ccdd/video.mp4"
+            output_bucket: "gisl-stg-euw1-output"
+            output_key_prefix: "jobs/018f9c42-5d6b-7481-b3df-9fd0a0a5e113/018f9c42-5d6b-7481-b3df-9fd0a0a5e201/"
+            options:
+              codec: "h265"
+              crf: 28
+              preset: "medium"
+
+    # ============================================
+    # OPERATION REQUEST MESSAGE (non-compression branch)
+    # ============================================
+
+    OperationRequestMessage:
+      name: OperationRequest
+      title: Non-Compression Operation Request
+      summary: Request to process a non-compression operation
+      description: |
+        Message sent by the API to request processing of any
+        **non-compression** operation (thumbnail, image_watermark,
+        text_watermark, merge, archive, convert, custom_luma,
+        audio_overlay, audio_watermark). Published to the
+        `operations` SNS topic; routed by the single-attribute filter
+        `operation_type` to one of the ops-family queues.
+
+        **SNS Message Attributes:**
+        - `operation_type`: always present. Values: `thumbnail`,
+          `thumbnail_image`, `thumbnail_video`, `thumbnail_document`,
+          `thumbnail_office`, `image_watermark`, `text_watermark`,
+          `merge`, `archive`, `convert`, `custom_luma`,
+          `audio_overlay`, `audio_watermark`. Used by SNS as the
+          filter attribute on the `operations` topic.
+        - `media_group`: informational metadata, present for every
+          operation except `archive` (which is media-agnostic). Values:
+          `image`, `video`, `audio`, `document`. **Not** used by SNS as
+          a routing filter — preserved for consumer observability and
+          log correlation.
+
+        **Input models:**
+        - 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
+        `operation_type=thumbnail_{image,video,document,office}` (new)
+        are valid routing targets. The API publisher currently emits
+        the legacy value only; sub-type adoption is a follow-up API PR.
+      contentType: application/json
+      headers:
+        $ref: '#/components/schemas/OperationRequestAttributes'
+      payload:
+        $ref: '#/components/schemas/OperationRequest'
+      examples:
+        - name: Thumbnail (legacy)
+          summary: Generate a thumbnail for an image using the legacy thumbnail routing target
+          headers:
+            operation_type: "thumbnail"
+            media_group: "image"
+          payload:
+            job_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e120"
+            operation_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e220"
+            operation_type: "thumbnail"
+            file_type: "image/jpeg"
+            source_bucket: "gisl-stg-euw1-input"
+            source_key: "uploads/018f9c42-iijj/photo.jpg"
+            output_bucket: "gisl-stg-euw1-output"
+            output_key_prefix: "jobs/018f9c42-5d6b-7481-b3df-9fd0a0a5e120/018f9c42-5d6b-7481-b3df-9fd0a0a5e220/"
+            options:
+              width: 320
+              height: 240
+              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. 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"
+            file_type: "image/png"
+            source_bucket: "gisl-stg-euw1-input"
+            source_key: "uploads/018f9c42-kkll/screenshot.png"
+            output_bucket: "gisl-stg-euw1-output"
+            output_key_prefix: "jobs/018f9c42-5d6b-7481-b3df-9fd0a0a5e121/018f9c42-5d6b-7481-b3df-9fd0a0a5e221/"
+            options:
+              width: 512
+              height: 512
+              fit: "max"
+              format: "webp"
+        - name: Image Watermark (file overlay)
+          summary: Apply a PNG logo overlay to a JPEG image (V2 multi-input Path B)
+          headers:
+            operation_type: "image_watermark"
+            media_group: "image"
+          payload:
+            job_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e118"
+            operation_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e210"
+            operation_type: "image_watermark"
+            file_type: "image/jpeg"
+            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:
+              anchor: "bottom_right"
+              margin_x: "20px"
+              margin_y: "20px"
+              opacity: 0.6
+              overlay_width: "200px"
+        - name: Text Watermark (tiled)
+          summary: Render a rotated tiled text watermark across a PNG image (V2 single-input)
+          headers:
+            operation_type: "text_watermark"
+            media_group: "image"
+          payload:
+            job_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e119"
+            operation_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e211"
+            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:
+              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
+          summary: Convert a PNG image to WebP
+          headers:
+            operation_type: "convert"
+            media_group: "image"
+          payload:
+            job_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e122"
+            operation_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e222"
+            operation_type: "convert"
+            file_type: "image/png"
+            source_bucket: "gisl-stg-euw1-input"
+            source_key: "uploads/018f9c42-mmnn/diagram.png"
+            output_bucket: "gisl-stg-euw1-output"
+            output_key_prefix: "jobs/018f9c42-5d6b-7481-b3df-9fd0a0a5e122/018f9c42-5d6b-7481-b3df-9fd0a0a5e222/"
+            options:
+              output_format: "webp"
+              quality: 85
+        - name: Video Merge
+          summary: Concatenate multiple video files
+          headers:
+            operation_type: "merge"
+            media_group: "video"
+          payload:
+            job_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e114"
+            operation_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e202"
+            operation_type: "merge"
+            file_type: "video/mp4"
+            output_type: "video"
+            sources:
+              - bucket: "gisl-stg-euw1-output"
+                key: "jobs/018f9c42-aaa1/018f9c42-bbb1/intro.mp4"
+              - bucket: "gisl-stg-euw1-output"
+                key: "jobs/018f9c42-aaa2/018f9c42-bbb2/content.mp4"
+              - bucket: "gisl-stg-euw1-output"
+                key: "jobs/018f9c42-aaa3/018f9c42-bbb3/outro.mp4"
+                transition: "none"
+            output_bucket: "gisl-stg-euw1-output"
+            output_key_prefix: "jobs/018f9c42-5d6b-7481-b3df-9fd0a0a5e114/018f9c42-5d6b-7481-b3df-9fd0a0a5e202/"
+            options:
+              transition: "crossfade"
+              crossfade_duration: 1.0
+        - name: Image Merge to GIF
+          summary: Merge multiple images into an animated GIF
+          headers:
+            operation_type: "merge"
+            media_group: "image"
+          payload:
+            job_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e115"
+            operation_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e203"
+            operation_type: "merge"
+            file_type: "image/png"
+            output_type: "gif"
+            sources:
+              - bucket: "gisl-stg-euw1-output"
+                key: "jobs/018f9c42-aaa1/018f9c42-bbb1/frame1.png"
+              - bucket: "gisl-stg-euw1-output"
+                key: "jobs/018f9c42-aaa2/018f9c42-bbb2/frame2.png"
+              - bucket: "gisl-stg-euw1-output"
+                key: "jobs/018f9c42-aaa3/018f9c42-bbb3/frame3.png"
+            output_bucket: "gisl-stg-euw1-output"
+            output_key_prefix: "jobs/018f9c42-5d6b-7481-b3df-9fd0a0a5e115/018f9c42-5d6b-7481-b3df-9fd0a0a5e203/"
+            options:
+              frame_delay: 100
+              loop: true
+        - name: Archive
+          summary: Bundle multiple files into a ZIP archive (no media_group attribute — archive is media-agnostic)
+          headers:
+            operation_type: "archive"
+          payload:
+            job_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e117"
+            operation_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e205"
+            operation_type: "archive"
+            sources:
+              - bucket: "gisl-stg-euw1-output"
+                key: "jobs/018f9c42-aaa1/018f9c42-bbb1/photo_compressed.png"
+              - bucket: "gisl-stg-euw1-output"
+                key: "jobs/018f9c42-aaa2/018f9c42-bbb2/video_compressed.mp4"
+              - bucket: "gisl-stg-euw1-output"
+                key: "jobs/018f9c42-aaa3/018f9c42-bbb3/report_compressed.pdf"
+            output_bucket: "gisl-stg-euw1-output"
+            output_key_prefix: "jobs/018f9c42-5d6b-7481-b3df-9fd0a0a5e117/018f9c42-5d6b-7481-b3df-9fd0a0a5e205/"
+            options:
+              format: "zip"
+
+    # ============================================
+    # OPERATION PROGRESS MESSAGE
+    # ============================================
+
+    OperationProgressMessage:
+      name: OperationProgress
+      title: Operation Progress
+      summary: Progress update during operation processing
+      description: |
+        Lightweight message published by Lambda during operation processing.
+        Used for real-time status tracking via SSE to the frontend.
+
+        **API Handling:**
+        - First progress (started): Update Operation status to in_progress in DB
+        - Subsequent progress: Update Redis cache only (not DB), forward via SSE
+
+        **Frontend Consumption:**
+        - Via SSE endpoint: GET /api/workflows/{id}/events
+      contentType: application/json
+      headers:
+        $ref: '#/components/schemas/FifoMessageHeaders'
+      payload:
+        $ref: '#/components/schemas/OperationProgress'
+      examples:
+        - name: Operation Started
+          summary: Operation has been picked up by Lambda
+          payload:
+            job_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e112"
+            operation_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e200"
+            operation_type: "compress"
+            status: "started"
+            progress: 0
+        - name: Downloading
+          summary: Lambda is downloading file from S3
+          payload:
+            job_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e112"
+            operation_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e200"
+            operation_type: "compress"
+            status: "downloading"
+            progress: 10
+            stage: "Fetching file from S3"
+        - name: Processing
+          summary: Lambda is actively processing the operation
+          payload:
+            job_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e112"
+            operation_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e200"
+            operation_type: "compress"
+            status: "processing"
+            progress: 55
+            stage: "Compressing image"
+        - name: Uploading
+          summary: Lambda is uploading result to S3
+          payload:
+            job_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e112"
+            operation_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e200"
+            operation_type: "compress"
+            status: "uploading"
+            progress: 90
+            stage: "Saving result to S3"
+
+    # ============================================
+    # 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
+      summary: Final result when operation completes or fails
+      description: |
+        Terminal message published by Lambda when operation finishes.
+        Contains full details including output location, metrics, or error information.
+
+        **API Handling:**
+        - Update Operation entity status in DB
+        - Derive Job status from its operations (all completed -> job completed)
+        - Derive Workflow status from its jobs
+        - Clear Redis cache for this operation
+        - Forward event via SSE to frontend
+
+        **Idempotency:**
+        - Check if Operation already has a result before updating
+      contentType: application/json
+      headers:
+        $ref: '#/components/schemas/FifoMessageHeaders'
+      payload:
+        $ref: '#/components/schemas/OperationResult'
+      examples:
+        - name: Successful Compression
+          summary: Compress operation completed with metrics
+          payload:
+            job_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e112"
+            operation_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e200"
+            operation_type: "compress"
+            status: "completed"
+            output_bucket: "gisl-stg-euw1-output"
+            output_key: "jobs/018f9c42-5d6b/018f9c42-5d6b-e200/photo_compressed.png"
+            output_size_bytes: 2097152
+            metrics:
+              original_size_bytes: 5242880
+              output_size_bytes: 2097152
+              compression_ratio: 0.40
+              duration_ms: 1500
+        - name: Successful Merge
+          summary: Video merge completed
+          payload:
+            job_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e114"
+            operation_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e202"
+            operation_type: "merge"
+            status: "completed"
+            output_bucket: "gisl-stg-euw1-output"
+            output_key: "jobs/018f9c42-5d6b/018f9c42-5d6b-e202/merged.mp4"
+            output_size_bytes: 157286400
+            metrics:
+              input_count: 3
+              output_size_bytes: 157286400
+              duration_ms: 8500
+        - name: Failed - Invalid Format
+          summary: Operation failed due to unsupported file format
+          payload:
+            job_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e113"
+            operation_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e201"
+            operation_type: "compress"
+            status: "failed"
+            error_code: "invalid_format"
+            error_message: "Unsupported file format: image/bmp"
+            is_retryable: false
+            last_progress: 10
+        - name: Failed - Retryable
+          summary: Operation failed with retryable S3 error
+          payload:
+            job_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e112"
+            operation_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e200"
+            operation_type: "compress"
+            status: "failed"
+            error_code: "s3_download_failed"
+            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
+    # ============================================
+
+    FifoMessageHeaders:
+      type: object
+      description: |
+        Required headers for FIFO SNS/SQS messaging.
+        These ensure message ordering and deduplication.
+      required:
+        - MessageGroupId
+      properties:
+        MessageGroupId:
+          type: string
+          description: |
+            Groups messages for FIFO ordering. Messages with the same
+            MessageGroupId are processed in order. Use operation_id to ensure
+            all messages for an operation are ordered correctly.
+          example: "018f9c42-5d6b-7481-b3df-9fd0a0a5e200"
+
+    # ============================================
+    # SNS MESSAGE ATTRIBUTES - COMPRESSION BRANCH
+    # ============================================
+
+    JobRequestAttributes:
+      type: object
+      description: |
+        SNS message attributes for the compression-branch publish path
+        (`publishJobRequest`). These are set as SNS message attributes on
+        messages sent to the `job-requests` topic, not in the payload.
+
+        Only `job_type` is set on this branch. The Option A publisher in
+        `compression_api` does **not** set `operation_type` or
+        `media_group` as attributes on compression messages — the media
+        group is encoded as `job_type` and no other attribute is used as
+        a filter on this topic. `job_type` is derived from the API's
+        `OperationMediaGroupResolver` output at publish time.
+
+        SNS uses `job_type` as the filter attribute on the `job-requests`
+        topic; subscriptions route by `job_type` value to the four
+        per-media-type compression queues.
+      required:
+        - job_type
+      properties:
+        job_type:
+          type: string
+          description: |
+            Media type category used as the SNS filter attribute on the
+            `job-requests` topic. The sole routing key for compression
+            traffic.
+          enum:
+            - image
+            - video
+            - audio
+            - document
+
+    # ============================================
+    # SNS MESSAGE ATTRIBUTES - NON-COMPRESSION BRANCH
+    # ============================================
+
+    OperationRequestAttributes:
+      type: object
+      description: |
+        SNS message attributes for the non-compression-branch publish path
+        (`publishOperationRequest`). These are set as SNS message
+        attributes on messages sent to the `operations` topic, not in the
+        payload.
+
+        SNS uses `operation_type` as the filter attribute on the
+        `operations` topic; subscriptions route by `operation_type` value
+        to per-operation queues. `media_group` is a second attribute the
+        Option A publisher always sets on non-archive operations, but it
+        is **not** used by SNS as a routing filter — it is informational
+        metadata preserved for consumer observability and log correlation.
+
+        **Required-attribute contract** (encoded in the `allOf`
+        conditionals below, matching the runtime guarantee in
+        `compression_api`'s `AwsSnsOperationPublisherAdapter.php:63-73`):
+
+        - `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 = 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`
+          - `thumbnail_video` -> `video`
+          - `thumbnail_document` -> `document`
+          - `thumbnail_office` -> `document` (office files are routed as
+            documents at the media_group level)
+      required:
+        - operation_type
+      properties:
+        operation_type:
+          type: string
+          description: |
+            Operation type used as the SNS filter attribute on the
+            `operations` topic. The sole routing key for non-compression
+            traffic.
+          enum:
+            - thumbnail
+            - thumbnail_image
+            - thumbnail_video
+            - thumbnail_document
+            - thumbnail_office
+            - image_watermark
+            - text_watermark
+            - merge
+            - archive
+            - convert
+            - custom_luma
+            - audio_overlay
+            - audio_watermark
+        media_group:
+          type: string
+          description: |
+            Media category. **Informational metadata, not an SNS filter
+            attribute.** Set by the Option A publisher on every
+            non-compress, non-archive operation for consumer observability
+            and log correlation. Omitted for archive (media-agnostic).
+
+            For single-input operations, derived from `file_type` MIME
+            prefix. For merge, derived from `output_type`.
+          enum:
+            - image
+            - video
+            - audio
+            - document
+      allOf:
+        - if:
+            properties:
+              operation_type:
+                not:
+                  const: archive
+          then:
+            required:
+              - media_group
+        - if:
+            properties:
+              operation_type:
+                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:
+                const: thumbnail_image
+          then:
+            properties:
+              media_group:
+                const: image
+        - if:
+            properties:
+              operation_type:
+                const: thumbnail_video
+          then:
+            properties:
+              media_group:
+                const: video
+        - if:
+            properties:
+              operation_type:
+                const: thumbnail_document
+          then:
+            properties:
+              media_group:
+                const: document
+        - if:
+            properties:
+              operation_type:
+                const: thumbnail_office
+          then:
+            properties:
+              media_group:
+                const: document
+
+    # ============================================
+    # OPERATION REQUEST PAYLOAD SCHEMA (shared by both messages)
+    # ============================================
+
+    OperationRequest:
+      type: object
+      description: |
+        Message format for operation request payloads. Shared between
+        `JobRequestMessage` (compression branch) and
+        `OperationRequestMessage` (non-compression branch). Published by
+        API to SNS, consumed by Lambda from SQS.
+
+        **Single-input operations** (compress, thumbnail, text_watermark,
+        convert): use `source_bucket` + `source_key` for the input file.
+        `file_type` is required.
+
+        **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
+        the compression branch, the routing equivalent is the `job_type`
+        MessageAttribute, also not in the payload.
+      required:
+        - job_id
+        - operation_id
+        - operation_type
+        - output_bucket
+        - output_key_prefix
+      allOf:
+        - if:
+            properties:
+              operation_type:
+                enum:
+                  - compress
+                  - thumbnail
+                  - text_watermark
+                  - convert
+                  - audio_watermark
+          then:
+            required:
+              - file_type
+              - source_bucket
+              - source_key
+        - if:
+            properties:
+              operation_type:
+                enum: [merge, archive, image_watermark, custom_luma, audio_overlay]
+          then:
+            required:
+              - sources
+        - if:
+            properties:
+              operation_type:
+                const: merge
+          then:
+            required:
+              - output_type
+      properties:
+        job_id:
+          type: string
+          format: uuid
+          description: Parent job identifier (UUID v7)
+          example: "018f9c42-5d6b-7481-b3df-9fd0a0a5e112"
+        operation_id:
+          type: string
+          format: uuid
+          description: Unique operation identifier (UUID v7)
+          example: "018f9c42-5d6b-7481-b3df-9fd0a0a5e200"
+        operation_type:
+          $ref: '#/components/schemas/OperationType'
+        workflow_id:
+          type: string
+          format: uuid
+          description: Parent workflow identifier (UUID v7). Present when operation belongs to a workflow.
+          example: "018f9c42-5d6b-7481-b3df-9fd0a0a5e100"
+        file_type:
+          type: string
+          description: |
+            MIME type of the input file. Required for single-input operations.
+            For multi-input operations, represents the primary/expected input type.
+
+            Examples by media group:
+            - image: image/png, image/jpeg, image/webp, image/avif, image/gif, image/svg+xml, image/tiff
+            - video: video/mp4, video/webm
+            - audio: audio/mpeg, audio/ogg, audio/wav, audio/flac, audio/aac
+            - document:
+              - application/pdf
+              - application/vnd.openxmlformats-officedocument.wordprocessingml.document (DOCX)
+              - application/vnd.openxmlformats-officedocument.spreadsheetml.sheet (XLSX)
+              - application/vnd.openxmlformats-officedocument.presentationml.presentation (PPTX)
+              - application/vnd.oasis.opendocument.text (ODT)
+              - application/vnd.oasis.opendocument.spreadsheet (ODS)
+              - application/vnd.oasis.opendocument.presentation (ODP)
+              - application/epub+zip (EPUB)
+          example: "image/png"
+
+        # Single-input fields
+        source_bucket:
+          type: string
+          description: S3 bucket containing the source file (single-input operations)
+          example: "gisl-stg-euw1-input"
+        source_key:
+          type: string
+          description: S3 key of the source file (single-input operations)
+          example: "uploads/018f9c42-aabb/photo.png"
+
+        # Multi-input fields
+        sources:
+          type: array
+          description: |
+            Input files for multi-input operations (merge, archive,
+            image_watermark, custom_luma, audio_overlay). Each entry
+            specifies an S3 location. Order matters for merge
+            (concatenation order). Per-input overrides (e.g.
+            transition) can be inlined on each entry.
+            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
+
+        # Output
+        output_bucket:
+          type: string
+          description: S3 bucket for the operation output
+          example: "gisl-stg-euw1-output"
+        output_key_prefix:
+          type: string
+          description: |
+            S3 key prefix for operation output. Lambda writes output files under this prefix.
+            Convention: jobs/{job_id}/{operation_id}/
+          example: "jobs/018f9c42-5d6b-7481-b3df-9fd0a0a5e112/018f9c42-5d6b-7481-b3df-9fd0a0a5e200/"
+
+        # Merge-specific
+        output_type:
+          $ref: '#/components/schemas/MergeOutputType'
+
+        # Operation options
+        options:
+          type: object
+          description: |
+            Operation-specific options. Schema varies by operation_type and media_group.
+            Validated by the API before publishing. Lambda trusts these are valid.
+            See the OpenAPI spec for per-operation-type option schemas.
+          additionalProperties: true
+
+        # V2 placeholders
+        source_credentials:
+          type: object
+          description: |
+            Credentials for accessing source files in external storage (V2).
+            Not used in V1 — all sources are in GISL-managed S3 buckets.
+          additionalProperties: true
+        export:
+          type: object
+          description: |
+            Export configuration for writing output to external storage (V2).
+            Not used in V1 — all outputs go to GISL-managed S3 buckets.
+          additionalProperties: true
+
+    SourceEntry:
+      type: object
+      description: |
+        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
+      properties:
+        bucket:
+          type: string
+          description: S3 bucket containing the source file
+          example: "gisl-stg-euw1-output"
+        key:
+          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"
+
+    # ============================================
+    # OPERATION PROGRESS SCHEMA
+    # ============================================
+
+    OperationProgress:
+      type: object
+      description: |
+        Lightweight progress update message.
+        Published frequently during operation processing.
+        Stored in Redis, not database (except first "started" status).
+
+        **Important**: Progress reaches 100 only on successful completion.
+        On failure, progress stops at the last known value.
+      required:
+        - job_id
+        - operation_id
+        - operation_type
+        - status
+        - progress
+      properties:
+        job_id:
+          type: string
+          format: uuid
+          description: Parent job identifier for correlation
+          example: "018f9c42-5d6b-7481-b3df-9fd0a0a5e112"
+        operation_id:
+          type: string
+          format: uuid
+          description: Operation identifier matching the original request
+          example: "018f9c42-5d6b-7481-b3df-9fd0a0a5e200"
+        operation_type:
+          $ref: '#/components/schemas/OperationType'
+        status:
+          $ref: '#/components/schemas/ProgressStatus'
+        progress:
+          type: integer
+          minimum: 0
+          maximum: 100
+          description: Progress percentage (0-100)
+          example: 55
+        stage:
+          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
+    # ============================================
+
+    OperationResult:
+      type: object
+      description: |
+        Terminal message with full operation results.
+        Stored in database as part of the Operation entity.
+
+        **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
+      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
+          format: uuid
+          description: Parent job identifier for correlation
+          example: "018f9c42-5d6b-7481-b3df-9fd0a0a5e112"
+        operation_id:
+          type: string
+          format: uuid
+          description: Operation identifier matching the original request
+          example: "018f9c42-5d6b-7481-b3df-9fd0a0a5e200"
+        operation_type:
+          $ref: '#/components/schemas/OperationType'
+        status:
+          $ref: '#/components/schemas/ResultStatus'
+
+        # Shared success field (both single- and multi-output)
+        output_bucket:
+          type: string
+          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. 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. 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'
+
+        # Failure fields
+        error_code:
+          $ref: '#/components/schemas/ErrorCode'
+        error_message:
+          type: string
+          description: Human-readable error message (failed only)
+          example: "Unsupported file format: image/bmp"
+        is_retryable:
+          type: boolean
+          description: Whether the operation could be retried (failed only)
+          default: false
+        last_progress:
+          type: integer
+          minimum: 0
+          maximum: 100
+          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
+    # ============================================
+
+    OperationMetrics:
+      type: object
+      description: |
+        Operation-specific metrics. Content varies by operation type.
+        All metrics include duration_ms. Compression includes size/ratio.
+        Merge includes input count. Archive includes file count and total size.
+      properties:
+        original_size_bytes:
+          type: integer
+          format: int64
+          description: Original file size in bytes (compress, convert, thumbnail, image_watermark, text_watermark)
+          example: 5242880
+        output_size_bytes:
+          type: integer
+          format: int64
+          description: Output file size in bytes
+          example: 2097152
+        compression_ratio:
+          type: number
+          format: float
+          minimum: 0
+          maximum: 1
+          description: |
+            Ratio of output to original size (0.0 to 1.0, lower = more compression).
+            Only present for compress operations.
+          example: 0.40
+        duration_ms:
+          type: integer
+          format: int64
+          description: Total processing time in milliseconds
+          example: 1500
+        input_count:
+          type: integer
+          description: Number of input files (merge, archive)
+          example: 3
+        file_count:
+          type: integer
+          description: Number of files in archive (archive only)
+          example: 30
+        total_input_size_bytes:
+          type: integer
+          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
+    # ============================================
+
+    OperationType:
+      type: string
+      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`: 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). 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
+        - image_watermark
+        - text_watermark
+        - convert
+        - merge
+        - archive
+        - custom_luma
+        - audio_overlay
+        - audio_watermark
+
+    MediaGroup:
+      type: string
+      description: |
+        Media category. Used as an **informational** SNS message attribute
+        on the `operations` topic only — preserved for consumer
+        observability and log correlation, and **not** used by SNS as a
+        routing filter. Routing on the `operations` topic is by
+        `operation_type` alone; routing on the `job-requests` topic is by
+        `job_type` (see `JobRequestAttributes`).
+
+        Derived by the publisher from MIME type prefix for single-input
+        operations:
+        - image/* -> image
+        - video/* -> video
+        - audio/* -> audio
+        - document types -> document (PDF, EPUB, DOCX, XLSX, PPTX, ODT,
+          ODS, ODP)
+
+        For merge, derived from `output_type`:
+        - output_type=gif -> image
+        - output_type=video -> video
+        - output_type=audio -> audio
+
+        Omitted from the SNS attributes for archive (media-agnostic). The
+        four thumbnail sub-types map to media_group as follows:
+        - thumbnail_image -> image
+        - thumbnail_video -> video
+        - thumbnail_document -> document
+        - thumbnail_office -> document (office files folded under
+          `document` at the media_group level)
+      enum:
+        - image
+        - video
+        - audio
+        - document
+
+    MergeOutputType:
+      type: string
+      description: |
+        Output format for merge operations. All merge operations route to
+        the single `ops-merge` Lambda via `operation_type=merge`
+        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.
+        - `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)
+      enum:
+        - gif
+        - video
+        - audio
+
+    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). 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:
+      type: string
+      description: |
+        Status values for operation results (terminal):
+        - completed: Operation finished successfully
+        - failed: Operation encountered an error
+      enum:
+        - completed
+        - failed
+
+    ErrorCode:
+      type: string
+      description: |
+        Machine-readable error code for categorization and retry logic.
+
+        **Retryable errors** (SQS will retry automatically):
+        - s3_download_failed: Source file download failed
+        - s3_upload_failed: Output file upload failed
+        - s3_access_denied: Permission denied (might be temporary)
+        - out_of_memory: Lambda ran out of memory
+        - timeout: Lambda execution timed out
+
+        **Non-retryable errors** (message sent to DLQ):
+        - invalid_format: Unsupported or corrupted file
+        - format_mismatch: MIME type doesn't match content
+        - decode_failed: Cannot decode/parse file
+        - processing_failed: Processing library error
+        - output_too_large: Output larger than original (compress only)
+        - invalid_options: Invalid operation options
+        - missing_source: Source file not found in S3
+        - invalid_key: S3 key is malformed
+        - invalid_request: Operation request validation failed
+        - unknown: Unclassified error
+      enum:
+        - s3_download_failed
+        - s3_upload_failed
+        - s3_access_denied
+        - out_of_memory
+        - timeout
+        - invalid_format
+        - format_mismatch
+        - decode_failed
+        - processing_failed
+        - output_too_large
+        - invalid_options
+        - missing_source
+        - invalid_key
+        - invalid_request
+        - unknown