@giveitsmaller/contracts 0.2.0 → 0.2.3

package/asyncapi/events.yaml

@@ -0,0 +1,2012 @@
+asyncapi: 3.0.0
+info:
+  title: GISL Compression Events
+  version: 3.0.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, watermark, merge, archive, convert). Filter attribute:
+      `operation_type`. Subscriptions: one queue per operation type, plus four
+      thumbnail sub-type queues during the migration window.
+
+    **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-watermark`, `operation-merge`, `operation-archive`,
+      `operation-convert`.
+
+    **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.
+
+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, watermark, merge, archive, convert). 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 = watermark` -> `ops-watermark` queue
+      - `operation_type = merge` -> `ops-merge` queue
+      - `operation_type = archive` -> `ops-archive` queue
+      - `operation_type = convert` -> `ops-convert` queue
+
+      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'
+
+  opsWatermark:
+    address: gisl-{env}-{region}-ops-watermark
+    description: |
+      SQS queue for watermark operations (image-only).
+      Subscribed to the `operations` SNS topic with filter
+      `operation_type = watermark`. Handles image-overlay and text-overlay
+      watermark modes on image inputs. Backed by the watermark Lambda
+      (`operation-watermark`).
+    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 (image collage/grid, animated GIF, video
+      slideshow/concat, audio concat, PDF concat) — the `output_type`
+      field on the request determines the encoding path internally, not
+      the routing.
+    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'
+
+  # ============================================
+  # 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.)
+
+  opsWatermarkDlq:
+    address: gisl-{env}-{region}-ops-watermark-dlq
+    description: DLQ for failed 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.)
+
+  # ============================================
+  # 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),
+      watermark, merge, archive, convert. 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, 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'
+
+  consumeWatermarkOperation:
+    action: receive
+    channel:
+      $ref: '#/channels/opsWatermark'
+    summary: Process watermark operation
+    description: |
+      The watermark Lambda consumes watermark requests routed by
+      `operation_type=watermark`. Image-only — handles both
+      image-overlay and text-overlay modes.
+    messages:
+      - $ref: '#/channels/opsWatermark/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 all merge output
+      types (image collage/grid, animated GIF, video slideshow/concat,
+      audio concat, PDF concat). The `output_type` field on the request
+      determines the encoding path internally.
+    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'
+
+  # ============================================
+  # 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'
+
+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, watermark, merge,
+        archive, convert). Published to the `operations` SNS topic;
+        routed by the single-attribute filter `operation_type` to one
+        of the nine ops-family queues.
+
+        **SNS Message Attributes:**
+        - `operation_type`: always present. Values: `thumbnail`,
+          `thumbnail_image`, `thumbnail_video`, `thumbnail_document`,
+          `thumbnail_office`, `watermark`, `merge`, `archive`, `convert`.
+          Used by SNS as the filter attribute on the `operations` topic.
+        - `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, thumbnail_image,
+          thumbnail_video, thumbnail_document, thumbnail_office,
+          watermark, convert): use `source_bucket` + `source_key`.
+          `file_type` required.
+        - Multi-input operations (merge, archive): use `sources` array.
+          Merge additionally requires `output_type`.
+
+        **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
+          headers:
+            operation_type: "thumbnail_image"
+            media_group: "image"
+          payload:
+            job_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e121"
+            operation_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e221"
+            operation_type: "thumbnail_image"
+            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 (image overlay)
+          summary: Apply a PNG logo overlay to a JPEG image
+          headers:
+            operation_type: "watermark"
+            media_group: "image"
+          payload:
+            job_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e118"
+            operation_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e210"
+            operation_type: "watermark"
+            file_type: "image/jpeg"
+            source_bucket: "gisl-stg-euw1-input"
+            source_key: "uploads/018f9c42-eeff/photo.jpg"
+            output_bucket: "gisl-stg-euw1-output"
+            output_key_prefix: "jobs/018f9c42-5d6b-7481-b3df-9fd0a0a5e118/018f9c42-5d6b-7481-b3df-9fd0a0a5e210/"
+            options:
+              watermark_type: "image"
+              watermark_bucket: "gisl-stg-euw1-assets"
+              watermark_key: "brand/logo.png"
+              position: "bottom-right"
+              opacity: 0.6
+        - name: Image Watermark (tiled text overlay)
+          summary: Render a rotated tiled text watermark across a PNG image
+          headers:
+            operation_type: "watermark"
+            media_group: "image"
+          payload:
+            job_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e119"
+            operation_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e211"
+            operation_type: "watermark"
+            file_type: "image/png"
+            source_bucket: "gisl-stg-euw1-input"
+            source_key: "uploads/018f9c42-gghh/screenshot.png"
+            output_bucket: "gisl-stg-euw1-output"
+            output_key_prefix: "jobs/018f9c42-5d6b-7481-b3df-9fd0a0a5e119/018f9c42-5d6b-7481-b3df-9fd0a0a5e211/"
+            options:
+              watermark_type: "text"
+              watermark_mode: "tiled"
+              text: "CONFIDENTIAL"
+              font_size: 64
+              color: "#FF000080"
+              rotation: -45
+              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: PDF Merge
+          summary: Concatenate multiple PDFs into one
+          headers:
+            operation_type: "merge"
+            media_group: "document"
+          payload:
+            job_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e116"
+            operation_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e204"
+            operation_type: "merge"
+            file_type: "application/pdf"
+            output_type: "document"
+            sources:
+              - bucket: "gisl-stg-euw1-output"
+                key: "jobs/018f9c42-aaa1/018f9c42-bbb1/chapter1.pdf"
+              - bucket: "gisl-stg-euw1-output"
+                key: "jobs/018f9c42-aaa2/018f9c42-bbb2/chapter2.pdf"
+            output_bucket: "gisl-stg-euw1-output"
+            output_key_prefix: "jobs/018f9c42-5d6b-7481-b3df-9fd0a0a5e116/018f9c42-5d6b-7481-b3df-9fd0a0a5e204/"
+            options: {}
+        - name: Archive
+          summary: Bundle multiple files into a ZIP archive (no media_group attribute — archive is media-agnostic)
+          headers:
+            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
+    # ============================================
+
+    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
+
+  schemas:
+    # ============================================
+    # 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 == watermark`, `media_group` must equal
+          `image` (watermark is image-only).
+        - 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
+            - watermark
+            - merge
+            - archive
+            - convert
+        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: watermark
+          then:
+            properties:
+              media_group:
+                const: image
+        - 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, thumbnail_image,
+        thumbnail_video, thumbnail_document, thumbnail_office, watermark,
+        convert): use `source_bucket` + `source_key` for the input file.
+        `file_type` is required.
+
+        **Multi-input operations** (merge, archive): use `sources` array.
+        Each entry has `bucket` + `key`. Merge entries may include
+        per-input overrides (e.g. transition type). Merge also requires
+        `output_type`.
+
+        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
+                  - thumbnail_image
+                  - thumbnail_video
+                  - thumbnail_document
+                  - thumbnail_office
+                  - watermark
+                  - convert
+          then:
+            required:
+              - file_type
+              - source_bucket
+              - source_key
+        - if:
+            properties:
+              operation_type:
+                enum: [merge, archive]
+          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).
+            Each entry specifies an S3 location. Order matters for merge (concatenation order).
+            Per-input overrides (e.g. transition) can be inlined on each entry.
+          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).
+        Provides the S3 location and optional per-input overrides.
+      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"
+        transition:
+          type: string
+          description: |
+            Per-input transition override for video merge.
+            Overrides the global transition option for the join point before this input.
+          example: "none"
+        page_range:
+          type: string
+          description: |
+            Page range for PDF merge. Selects specific pages from this input.
+            Format: "1-5", "1,3,5-10". Omit for all pages.
+          example: "1-5"
+
+    # ============================================
+    # OPERATION PROGRESS SCHEMA
+    # ============================================
+
+    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"
+
+    # ============================================
+    # 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.
+      required:
+        - job_id
+        - operation_id
+        - operation_type
+        - status
+      if:
+        properties:
+          status:
+            const: completed
+      then:
+        required:
+          - output_bucket
+          - output_key
+          - output_size_bytes
+      else:
+        required:
+          - error_code
+          - error_message
+          - is_retryable
+      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'
+
+        # Success fields
+        output_bucket:
+          type: string
+          description: S3 bucket where output file is stored (completed only)
+          example: "gisl-stg-euw1-output"
+        output_key:
+          type: string
+          description: S3 key of the output file (completed only)
+          example: "jobs/018f9c42-5d6b/018f9c42-5d6b-e200/photo_compressed.png"
+        output_size_bytes:
+          type: integer
+          format: int64
+          description: Output file size in bytes (completed only)
+          example: 2097152
+        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
+
+    # ============================================
+    # 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, 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
+
+    # ============================================
+    # ENUMS
+    # ============================================
+
+    OperationType:
+      type: string
+      description: |
+        Operation type. Appears both inside the message payload and, for
+        non-compression operations, as the SNS `operation_type` filter
+        attribute on the `operations` topic. Compression operations are
+        routed by `job_type` on the separate `job-requests` topic — see
+        `JobRequestAttributes` and the top-level `info.description`.
+
+        - `compress`: Reduce file size (image, video, audio, document).
+          Routes via `job_type` on the `job-requests` topic.
+        - `thumbnail`: Legacy thumbnail value. Routes via
+          `operation_type=thumbnail` on the `operations` topic to the
+          legacy `ops-thumbnail` queue. Currently the only thumbnail
+          value the API publisher emits.
+        - `thumbnail_image`: Image thumbnail sub-type. Routes via
+          `operation_type=thumbnail_image` to `ops-thumbnail-image`.
+          Not yet emitted by the API publisher — adoption is a
+          follow-up API PR with input-MIME dispatch.
+        - `thumbnail_video`: Video thumbnail sub-type. Routes via
+          `operation_type=thumbnail_video` to `ops-thumbnail-video`.
+          Not yet emitted.
+        - `thumbnail_document`: PDF/EPUB thumbnail sub-type. Routes via
+          `operation_type=thumbnail_document` to `ops-thumbnail-document`.
+          Not yet emitted.
+        - `thumbnail_office`: Office document (DOCX/XLSX/PPTX/ODT/ODS/ODP)
+          thumbnail sub-type. Routes via `operation_type=thumbnail_office`
+          to `ops-thumbnail-office`. Not yet emitted.
+        - `watermark`: Apply branding/protection (image only). Routes
+          via `operation_type=watermark` to `ops-watermark`.
+        - `convert`: Change file format (image, video, audio, document).
+          Routes via `operation_type=convert` to `ops-convert`.
+        - `merge`: Concatenate/combine multiple files (image, video,
+          audio, document/PDF). Routes via `operation_type=merge` to
+          `ops-merge`. A single Lambda handles all merge output types.
+        - `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.
+      enum:
+        - compress
+        - thumbnail
+        - thumbnail_image
+        - thumbnail_video
+        - thumbnail_document
+        - thumbnail_office
+        - watermark
+        - convert
+        - merge
+        - archive
+
+    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=image or gif -> image
+        - output_type=video -> video
+        - output_type=audio -> audio
+        - output_type=document -> document
+
+        Omitted from the SNS attributes for archive (media-agnostic). The
+        four thumbnail sub-types map to media_group as follows:
+        - 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.
+        - `image`: Collage/grid (ImageMagick montage inside the merge Lambda)
+        - `gif`: Animated GIF (ImageMagick convert inside the merge Lambda)
+        - `video`: Slideshow from images or video concatenation (FFmpeg inside the merge Lambda)
+        - `audio`: Audio concatenation (FFmpeg inside the merge Lambda)
+        - `document`: PDF concatenation (qpdf inside the merge Lambda)
+      enum:
+        - image
+        - gif
+        - video
+        - audio
+        - document
+
+    ProgressStatus:
+      type: string
+      description: |
+        Status values for progress updates (non-terminal):
+        - started: Lambda picked up the operation
+        - downloading: Downloading source file(s) from S3
+        - processing: Actively processing (compressing, merging, etc.)
+        - uploading: Uploading result to S3
+      enum:
+        - started
+        - downloading
+        - processing
+        - 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