@giveitsmaller/contracts 0.7.0 → 0.9.0

package/asyncapi/events.yaml

@@ -1,7 +1,7 @@
 asyncapi: 3.0.0
 info:
   title: GISL Compression Events
-  version: 3.2.0
+  version: 3.9.0
   description: |
     Asynchronous event contracts for the GISL (Give It Smaller) compression service.
 
@@ -21,16 +21,20 @@ info:
       video_watermark, video_text_watermark, split). Filter attribute:
       `operation_type`. Subscriptions: one queue per operation type,
       plus four thumbnail sub-type queues during the migration window.
-      `custom_luma`, `audio_overlay`, `audio_watermark`,
-      `audio_to_video`, `video_watermark`, `video_text_watermark`, and
-      `split` are `availability: planned` (per
-      [I29](https://trello.com/c/EPUE5Vs1) +
+      `custom_luma`, `audio_overlay`, `audio_watermark`, and
+      `video_text_watermark` are `availability: planned`
+      (per [I29](https://trello.com/c/EPUE5Vs1) +
       [I19](https://trello.com/c/Xr3Z4GBF) +
       [I20](https://trello.com/c/omiCq7Vn) +
-      [`SlluxMBN`](https://trello.com/c/SlluxMBN) +
-      [`4NrRPCgh`](https://trello.com/c/4NrRPCgh) +
-      [`vKI0CFDu`](https://trello.com/c/vKI0CFDu)) — their queues are
-      declared but receive no traffic until Lambda ships.
+      [`4NrRPCgh`](https://trello.com/c/4NrRPCgh)) — their queues are
+      declared but receive no traffic until Lambda ships. `split` is
+      `availability: beta` for its `audio` mime_group (worker live on
+      staging — [`vKI0CFDu`](https://trello.com/c/vKI0CFDu)); its
+      `image_gif`, `document_pdf`, and `video` mime_groups stay
+      `availability: planned`.
+      `audio_to_video` and `video_watermark` are `availability: beta`
+      (Wave A activation [`c3uthIP4`](https://trello.com/c/c3uthIP4) —
+      backends live; the API accepts + publishes, traffic flows).
       `audio_watermark` additionally requires `enterprise` tier.
 
     **Publisher branching rule** (implemented in `compression_api`'s
@@ -54,11 +58,13 @@ info:
     **Thumbnail migration window.** The terraform topology has both the
     legacy `ops-thumbnail` queue and four new sub-type queues
     (`ops-thumbnail-{image,video,document,office}`) live simultaneously.
-    The API publisher currently emits the legacy `operation_type=thumbnail`
-    only; adoption of the four sub-type values (`thumbnail_image`,
-    `thumbnail_video`, `thumbnail_document`, `thumbnail_office`) is a
-    follow-up API PR. Both routing targets are documented in this contract
-    because both are valid during the migration.
+    The API publisher emits the four sub-type values (`thumbnail_image`,
+    `thumbnail_video`, `thumbnail_document`, `thumbnail_office`) on the
+    SNS `operation_type` attribute, resolved from each operation's
+    effective input MIME; the legacy `operation_type=thumbnail` attribute
+    is retained as a valid routing target during the migration window but
+    is no longer emitted. Both routing targets are documented in this
+    contract because both remain valid during the migration.
 
     **Notifications (Lambda -> API).** Lambda functions publish progress
     and result notifications to the FIFO SNS topic
@@ -191,19 +197,23 @@ channels:
         [I19](https://trello.com/c/Xr3Z4GBF) — same `feature_not_
         available` 422 gating)
       - `operation_type = audio_to_video` -> `ops-audio-to-video` queue
-        (gated by `availability: planned` until Lambda ships per
-        [`SlluxMBN`](https://trello.com/c/SlluxMBN) — same
-        `feature_not_available` 422 gating)
+        (`availability: beta` — Wave A activated per
+        [`SlluxMBN`](https://trello.com/c/SlluxMBN) +
+        [`c3uthIP4`](https://trello.com/c/c3uthIP4); backend live, traffic
+        flows)
       - `operation_type = video_watermark` -> `ops-video-watermark`
-        queue (gated by `availability: planned` until Lambda ships per
-        [`4NrRPCgh`](https://trello.com/c/4NrRPCgh) — same gating)
+        queue (`availability: beta` — Wave A activated per
+        [`4NrRPCgh`](https://trello.com/c/4NrRPCgh) +
+        [`c3uthIP4`](https://trello.com/c/c3uthIP4); backend live)
       - `operation_type = video_text_watermark` ->
         `ops-video-text-watermark` queue (gated by
         `availability: planned` until Lambda ships per
         [`4NrRPCgh`](https://trello.com/c/4NrRPCgh) — same gating)
-      - `operation_type = split` -> `ops-split` queue (gated by
-        `availability: planned` until Lambda ships per
-        [`vKI0CFDu`](https://trello.com/c/vKI0CFDu) — same gating;
+      - `operation_type = split` -> `ops-split` queue (the `audio`
+        mime_group is `availability: beta` — audio split traffic
+        reaches this queue; `image_gif` / `document_pdf` / `video`
+        stay `availability: planned` until their Lambdas ship per
+        [`vKI0CFDu`](https://trello.com/c/vKI0CFDu);
         long-form video splits route via `processing_class` to the
         `split-video-fargate` worker, same OperationType, different
         worker)
@@ -223,9 +233,11 @@ channels:
 
       **Thumbnail migration window.** The legacy `ops-thumbnail` queue and
       the four sub-type queues are all live simultaneously. The API
-      publisher currently emits `operation_type=thumbnail` (legacy);
-      adoption of the four sub-type values is a follow-up API PR. Both
-      paths are valid routing targets today.
+      publisher emits the four sub-type values on the SNS `operation_type`
+      attribute (resolved from effective input MIME); the legacy
+      `operation_type=thumbnail` attribute is retained as a valid routing
+      target but is no longer emitted. Both paths are valid routing
+      targets today.
     parameters:
       env:
         description: Environment (local, stg, prod)
@@ -245,6 +257,12 @@ channels:
       SQS queue for image compression jobs.
       Subscribed to the `job-requests` SNS topic with filter
       `job_type = image`. Handles `compress` only for image inputs.
+    bindings:
+      sqs:
+        queue:
+          name: gisl-{env}-{region}-jobs-image
+          fifoQueue: false
+        bindingVersion: '0.2.0'
     parameters:
       env:
         description: Environment (local, stg, prod)
@@ -260,6 +278,12 @@ channels:
       SQS queue for video compression jobs.
       Subscribed to the `job-requests` SNS topic with filter
       `job_type = video`. Handles `compress` only for video inputs.
+    bindings:
+      sqs:
+        queue:
+          name: gisl-{env}-{region}-jobs-video
+          fifoQueue: false
+        bindingVersion: '0.2.0'
     parameters:
       env:
         description: Environment (local, stg, prod)
@@ -275,6 +299,12 @@ channels:
       SQS queue for audio compression jobs.
       Subscribed to the `job-requests` SNS topic with filter
       `job_type = audio`. Handles `compress` only for audio inputs.
+    bindings:
+      sqs:
+        queue:
+          name: gisl-{env}-{region}-jobs-audio
+          fifoQueue: false
+        bindingVersion: '0.2.0'
     parameters:
       env:
         description: Environment (local, stg, prod)
@@ -290,6 +320,12 @@ channels:
       SQS queue for document compression jobs.
       Subscribed to the `job-requests` SNS topic with filter
       `job_type = document`. Handles `compress` only for document inputs.
+    bindings:
+      sqs:
+        queue:
+          name: gisl-{env}-{region}-jobs-document
+          fifoQueue: false
+        bindingVersion: '0.2.0'
     parameters:
       env:
         description: Environment (local, stg, prod)
@@ -350,12 +386,14 @@ channels:
       Subscribed to the `operations` SNS topic with filter
       `operation_type = thumbnail`.
 
-      **Migration window**: This is the legacy routing target and is
-      currently the only one the API publisher emits for (via
-      `operation_type=thumbnail`). It handles thumbnail requests for all
-      media types. Retirement is planned after the API publisher adopts
-      the four sub-type values (`thumbnail_image`, `thumbnail_video`,
-      `thumbnail_document`, `thumbnail_office`) in a follow-up API PR.
+      **Migration window**: This is the legacy routing target. It is
+      retained as a valid routing target (via `operation_type=thumbnail`)
+      and handles thumbnail requests for all media types, but the API
+      publisher no longer emits it — the publisher now emits the four
+      sub-type values (`thumbnail_image`, `thumbnail_video`,
+      `thumbnail_document`, `thumbnail_office`), resolved from each
+      operation's effective input MIME. Retirement of this legacy queue
+      follows once no traffic remains.
     parameters:
       env:
         description: Environment (local, stg, prod)
@@ -373,9 +411,10 @@ channels:
       `operation_type = thumbnail_image`. Backed by the Rust image
       thumbnail Lambda (`operation-thumbnail-image`).
 
-      Not yet receiving traffic — the API publisher currently emits
-      `operation_type=thumbnail` (legacy) and will flip to
-      `thumbnail_image` after a follow-up API PR adds input-MIME dispatch.
+      Receives traffic for image inputs — the API publisher emits
+      `operation_type=thumbnail_image` on the SNS attribute (resolved from
+      the operation's effective input MIME); the payload `operation_type`
+      field stays `thumbnail`.
     parameters:
       env:
         description: Environment (local, stg, prod)
@@ -393,9 +432,10 @@ channels:
       `operation_type = thumbnail_video`. Backed by the FFmpeg video
       thumbnail Lambda (`operation-thumbnail-video`).
 
-      Not yet receiving traffic — the API publisher currently emits
-      `operation_type=thumbnail` (legacy) and will flip to
-      `thumbnail_video` after a follow-up API PR adds input-MIME dispatch.
+      Receives traffic for video inputs — the API publisher emits
+      `operation_type=thumbnail_video` on the SNS attribute (resolved from
+      the operation's effective input MIME); the payload `operation_type`
+      field stays `thumbnail`.
     parameters:
       env:
         description: Environment (local, stg, prod)
@@ -413,10 +453,10 @@ channels:
       `operation_type = thumbnail_document`. Backed by the Ghostscript
       document thumbnail Lambda (`operation-thumbnail-document`).
 
-      Not yet receiving traffic — the API publisher currently emits
-      `operation_type=thumbnail` (legacy) and will flip to
-      `thumbnail_document` after a follow-up API PR adds input-MIME
-      dispatch.
+      Receives traffic for PDF/EPUB inputs — the API publisher emits
+      `operation_type=thumbnail_document` on the SNS attribute (resolved
+      from the operation's effective input MIME); the payload
+      `operation_type` field stays `thumbnail`.
     parameters:
       env:
         description: Environment (local, stg, prod)
@@ -435,10 +475,10 @@ channels:
       `operation_type = thumbnail_office`. Backed by the LibreOffice
       thumbnail Lambda (`operation-thumbnail-office`).
 
-      Not yet receiving traffic — the API publisher currently emits
-      `operation_type=thumbnail` (legacy) and will flip to
-      `thumbnail_office` after a follow-up API PR adds input-MIME
-      dispatch.
+      Receives traffic for office-document inputs — the API publisher
+      emits `operation_type=thumbnail_office` on the SNS attribute
+      (resolved from the operation's effective input MIME); the payload
+      `operation_type` field stays `thumbnail`.
     parameters:
       env:
         description: Environment (local, stg, prod)
@@ -614,11 +654,11 @@ channels:
       `role: overlay` image OPTIONAL — see `per_role_cardinality`
       on the operation schema).
 
-      `availability: planned` per the operation schema; the API
-      rejects workflow-create with `feature_not_available` (422)
-      until the Lambda ships, so traffic does not reach this queue
-      today. Backed by the `operation-audio-to-video` Lambda
-      (cross-repo follow-up — lambdas pre-launch epic Wave A).
+      `availability: beta` per the operation schema (Wave A activated,
+      [`c3uthIP4`](https://trello.com/c/c3uthIP4)): the API accepts +
+      publishes, so traffic flows to this queue (MUST NOT 422). Backed
+      by the `operation-audio-to-video` Lambda (live; lambdas pre-launch
+      epic Wave A).
 
       Per ADR-0004 + ADR-0015
       ([`SlluxMBN`](https://trello.com/c/SlluxMBN)).
@@ -642,10 +682,12 @@ channels:
       (no operation-specific conditional needed in
       OperationRequestAttributes).
 
-      `availability: planned` per the operation schema; the API
-      rejects workflow-create with `feature_not_available` (422)
-      until the Lambda ships, so traffic does not reach this queue
-      today. Backed by the `operation-split` Lambda (cross-repo
+      `availability: beta` for the `audio` mime_group (worker live on
+      staging — audio split traffic reaches this queue); the
+      `image_gif`, `document_pdf`, and `video` mime_groups stay
+      `availability: planned`, and the API rejects their
+      workflow-create with `feature_not_available` (422) until those
+      Lambdas ship. Backed by the `operation-split` Lambda (cross-repo
       follow-up — lambdas pre-launch epic Wave A, ticket
       [DbpJpVtm-sibling-L1](https://trello.com/c/vKI0CFDu)
       [`vKI0CFDu`](https://trello.com/c/vKI0CFDu)).
@@ -678,11 +720,12 @@ channels:
       (Path B with `role: base` video + `role: overlay` image,
       exactly one of each per `per_role_cardinality`).
 
-      `availability: planned` per the operation schema; the API
-      rejects workflow-create with `feature_not_available` (422)
-      until the Lambda ships, so traffic does not reach this queue
-      today. Backed by the `operation-video-watermark` Lambda (cross-
-      repo follow-up — lambdas pre-launch epic Wave A, ticket
+      `availability: beta` per the operation schema (Wave A activated,
+      [`c3uthIP4`](https://trello.com/c/c3uthIP4)): the API accepts +
+      publishes, so traffic flows to this queue (MUST NOT 422). The
+      `short_form` processing class is beta; `long_form` stays planned
+      (no live Fargate worker). Backed by the `operation-video-watermark`
+      Lambda (live; lambdas pre-launch epic Wave A, ticket
       [DbpJpVtm](https://trello.com/c/DbpJpVtm)).
 
       Distinct from `image_watermark` (pure-Rust image-only) — see
@@ -900,9 +943,9 @@ channels:
     description: |
       DLQ for failed audio_to_video operations (per ticket
       [`SlluxMBN`](https://trello.com/c/SlluxMBN) / ADR-0015).
-      Messages land here after 5 failed processing attempts. No
-      traffic reaches this queue while audio_to_video is
-      `availability: planned`.
+      Messages land here after 5 failed processing attempts.
+      audio_to_video is `availability: beta` (Wave A activated) so
+      this queue now receives real failures.
     parameters:
       env:
         description: Environment (local, stg, prod)
@@ -914,9 +957,9 @@ channels:
     description: |
       DLQ for failed video_watermark operations (per ticket
       [`4NrRPCgh`](https://trello.com/c/4NrRPCgh) / ADR-0013).
-      Messages land here after 5 failed processing attempts. No
-      traffic reaches this queue while video_watermark is
-      `availability: planned`.
+      Messages land here after 5 failed processing attempts.
+      video_watermark is `availability: beta` (Wave A activated) so
+      this queue now receives real failures.
     parameters:
       env:
         description: Environment (local, stg, prod)
@@ -942,9 +985,10 @@ channels:
     description: |
       DLQ for failed split operations (per ticket
       [`vKI0CFDu`](https://trello.com/c/vKI0CFDu) / ADR-0014).
-      Messages land here after 5 failed processing attempts. No
-      traffic reaches this queue while split is `availability:
-      planned`.
+      Messages land here after 5 failed processing attempts. Live for
+      the `split` `audio` mime_group (now `availability: beta`); the
+      `image_gif`, `document_pdf`, and `video` groups stay
+      `availability: planned` and carry no traffic yet.
     parameters:
       env:
         description: Environment (local, stg, prod)
@@ -1112,6 +1156,79 @@ channels:
       region:
         description: AWS region abbreviation (euw1, use1, etc.)
 
+  # ============================================
+  # LONG-FORM CLAIM-CHECK QUEUES (direct-to-SQS, Fargate-processed)
+  # ============================================
+  # Distinct delivery mechanism from the SNS-fanout jobs/ops families:
+  # the API publishes a LongFormJobMessage claim-check DIRECTLY to these
+  # per-op-class SQS queues (no SNS topic, no filter routing). A
+  # terraform-owned launcher (EventBridge Pipe, filter=none) consumes
+  # and forks a Fargate task. Two classes are live (compress, merge);
+  # split-video-longform (queue provisioned, publisher deferred per
+  # rcwvUKhI) and audio-overlay-longform (reserve-name-only, no queue)
+  # are NOT modeled as channels — they carry no traffic yet.
+
+  longformCompressVideo:
+    address: gisl-{env}-{region}-ops-compress-video-longform
+    description: |
+      SQS queue for long-form video compression jobs (`compress.video.long_form`,
+      `availability: beta`). The API publishes a `LongFormJobMessage` claim-check
+      here directly (NOT via SNS); a terraform-owned launcher reads the spec from
+      S3 (`pointer`) and runs a Fargate task. `max_receive_count = 2` (ADR-0007).
+
+      On this queue the publisher always sets `operation_type: compress`. The
+      shared `LongFormJobMessage` enum permits `{compress, merge}` (mirroring the
+      shared `JobRequestMessage` across the per-media `jobs-*` queues); per-queue
+      `operation_type` is a publisher invariant documented here, not a separate
+      message schema.
+    parameters:
+      env:
+        description: Environment (local, stg, prod)
+      region:
+        description: AWS region abbreviation (euw1, use1, etc.)
+    messages:
+      longFormJob:
+        $ref: '#/components/messages/LongFormJobMessage'
+
+  longformCompressVideoDlq:
+    address: gisl-{env}-{region}-ops-compress-video-longform-dlq
+    description: DLQ for failed long-form video compression jobs. Messages land here after 2 failed processing attempts (ADR-0007).
+    parameters:
+      env:
+        description: Environment (local, stg, prod)
+      region:
+        description: AWS region abbreviation (euw1, use1, etc.)
+
+  longformMergeVideoReencode:
+    address: gisl-{env}-{region}-ops-merge-video-longform-reencode
+    description: |
+      SQS queue for long-form merge re-encode jobs (`merge.video.long_form_re_encode`,
+      `availability: beta`). The API publishes a `LongFormJobMessage` claim-check
+      here directly (NOT via SNS); a terraform-owned launcher reads the spec from
+      S3 (`pointer`) and runs a Fargate task. `max_receive_count = 2` (ADR-0007).
+
+      On this queue the publisher always sets `operation_type: merge` (shared
+      `LongFormJobMessage` enum permits `{compress, merge}`; per-queue
+      `operation_type` is a publisher invariant documented here, not a separate
+      schema).
+    parameters:
+      env:
+        description: Environment (local, stg, prod)
+      region:
+        description: AWS region abbreviation (euw1, use1, etc.)
+    messages:
+      longFormJob:
+        $ref: '#/components/messages/LongFormJobMessage'
+
+  longformMergeVideoReencodeDlq:
+    address: gisl-{env}-{region}-ops-merge-video-longform-reencode-dlq
+    description: DLQ for failed long-form merge re-encode jobs. Messages land here after 2 failed processing attempts (ADR-0007).
+    parameters:
+      env:
+        description: Environment (local, stg, prod)
+      region:
+        description: AWS region abbreviation (euw1, use1, etc.)
+
 operations:
   # ============================================
   # PUBLISH OPERATIONS (API -> SNS)
@@ -1235,9 +1352,10 @@ operations:
     description: |
       The legacy thumbnail Lambda consumes thumbnail requests routed
       by `operation_type=thumbnail`. Handles thumbnail generation for
-      all media types in a single Lambda. This is the current live
-      routing target for the API publisher; it will be retired after
-      the publisher adopts the four sub-type values.
+      all media types in a single Lambda. Retained as a valid routing
+      target during the migration window, but the API publisher no
+      longer emits `operation_type=thumbnail` (it emits the four
+      sub-type values); this queue is retired once no traffic remains.
     messages:
       - $ref: '#/channels/opsThumbnail/messages/operationRequest'
 
@@ -1249,7 +1367,7 @@ operations:
     description: |
       The image thumbnail Lambda consumes thumbnail requests routed by
       `operation_type=thumbnail_image`. Backed by a Rust image crate.
-      Not yet receiving traffic — see channel description.
+      Receives traffic for image inputs — see channel description.
     messages:
       - $ref: '#/channels/opsThumbnailImage/messages/operationRequest'
 
@@ -1260,8 +1378,8 @@ operations:
     summary: Process video thumbnail operation
     description: |
       The video thumbnail Lambda consumes thumbnail requests routed by
-      `operation_type=thumbnail_video`. Backed by FFmpeg. Not yet
-      receiving traffic — see channel description.
+      `operation_type=thumbnail_video`. Backed by FFmpeg. Receives
+      traffic for video inputs — see channel description.
     messages:
       - $ref: '#/channels/opsThumbnailVideo/messages/operationRequest'
 
@@ -1273,7 +1391,8 @@ operations:
     description: |
       The document (PDF/EPUB) thumbnail Lambda consumes thumbnail
       requests routed by `operation_type=thumbnail_document`. Backed by
-      Ghostscript. Not yet receiving traffic — see channel description.
+      Ghostscript. Receives traffic for PDF/EPUB inputs — see channel
+      description.
     messages:
       - $ref: '#/channels/opsThumbnailDocument/messages/operationRequest'
 
@@ -1285,8 +1404,8 @@ operations:
     description: |
       The office document (DOCX/XLSX/PPTX/ODT/ODS/ODP) thumbnail Lambda
       consumes thumbnail requests routed by
-      `operation_type=thumbnail_office`. Backed by LibreOffice. Not yet
-      receiving traffic — see channel description.
+      `operation_type=thumbnail_office`. Backed by LibreOffice. Receives
+      traffic for office-document inputs — see channel description.
     messages:
       - $ref: '#/channels/opsThumbnailOffice/messages/operationRequest'
 
@@ -1401,14 +1520,18 @@ operations:
       $ref: '#/channels/opsSplit'
     summary: Process split operation
     description: |
-      The `operation-split` Lambda (cross-repo follow-up — lambdas
-      pre-launch epic Wave A, not yet shipped) consumes split
-      requests routed by `operation_type=split`. Single-input —
+      The `operation-split` Lambda (lambdas pre-launch epic Wave A)
+      consumes split requests routed by `operation_type=split`. Its
+      `audio` path is live on staging (lambdas #161); the
+      `image_gif` / `document_pdf` / `video` workers remain a
+      cross-repo follow-up. Single-input —
       `media_group` derives from the input MIME prefix per the
-      existing single-input rule. `availability: planned`; the API
-      rejects workflow-create with `feature_not_available` (422)
-      until the Lambda ships, so traffic does not reach this channel
-      today. Long-form video splits route to a separate
+      existing single-input rule. `availability: beta` for the `audio`
+      mime_group (worker live on staging); the `image_gif`,
+      `document_pdf`, and `video` mime_groups stay `availability:
+      planned`, and the API rejects their workflow-create with
+      `feature_not_available` (422) until those Lambdas ship.
+      Long-form video splits route to a separate
       `split-video-fargate` worker via `processing_class`.
       Per ADR-0004 + ADR-0014
       ([`vKI0CFDu`](https://trello.com/c/vKI0CFDu)).
@@ -1422,14 +1545,14 @@ operations:
     summary: Process video_watermark operation
     description: |
       The `operation-video-watermark` Lambda (cross-repo follow-up —
-      lambdas pre-launch epic Wave A, not yet shipped) consumes
+      lambdas pre-launch epic Wave A, live) consumes
       video_watermark requests routed by
       `operation_type=video_watermark`. Multi-input role-based with
       `role: base` video + `role: overlay` image (exactly one of
-      each per `per_role_cardinality`). `availability: planned`; the
-      API rejects workflow-create with `feature_not_available` (422)
-      until the Lambda ships, so traffic does not reach this channel
-      today.
+      each per `per_role_cardinality`). `availability: beta` (Wave A
+      activated, [`c3uthIP4`](https://trello.com/c/c3uthIP4)): the API
+      accepts + publishes (MUST NOT 422), so traffic flows to this
+      channel. `short_form` is beta; `long_form` stays planned.
       Per ADR-0004 + ADR-0013
       ([`4NrRPCgh`](https://trello.com/c/4NrRPCgh)).
     messages:
@@ -1461,14 +1584,14 @@ operations:
     summary: Process audio_to_video operation
     description: |
       The `operation-audio-to-video` Lambda (cross-repo follow-up —
-      lambdas pre-launch epic Wave A, not yet shipped) consumes
+      lambdas pre-launch epic Wave A, live) consumes
       audio_to_video requests routed by
       `operation_type=audio_to_video`. Multi-input role-based with
       role asymmetry (Path B with `role: base` audio REQUIRED +
       `role: overlay` image OPTIONAL per `per_role_cardinality`).
-      `availability: planned`; the API rejects workflow-create with
-      `feature_not_available` (422) until the Lambda ships, so
-      traffic does not reach this channel today.
+      `availability: beta` (Wave A activated,
+      [`c3uthIP4`](https://trello.com/c/c3uthIP4)): the API accepts +
+      publishes (MUST NOT 422), so traffic flows to this channel.
       Per ADR-0004 + ADR-0015
       ([`SlluxMBN`](https://trello.com/c/SlluxMBN)).
     messages:
@@ -1606,6 +1729,64 @@ operations:
     messages:
       - $ref: '#/channels/uploadProbeCompletionsQueue/messages/uploadProbeCompletion'
 
+  # ============================================
+  # LONG-FORM CLAIM-CHECK PRODUCERS (API -> SQS, direct)
+  # ============================================
+
+  publishLongFormCompressVideo:
+    action: send
+    channel:
+      $ref: '#/channels/longformCompressVideo'
+    summary: Publish a long-form video compression claim-check.
+    description: |
+      The API (`SqsLongFormOperationPublisherAdapter`) writes the full job
+      spec to S3 and publishes a `LongFormJobMessage` claim-check **directly**
+      to this SQS queue (NOT via SNS — no message attributes). `operation_type`
+      is `compress`, `processing_class` is `long_form`.
+    messages:
+      - $ref: '#/channels/longformCompressVideo/messages/longFormJob'
+
+  publishLongFormMergeVideoReencode:
+    action: send
+    channel:
+      $ref: '#/channels/longformMergeVideoReencode'
+    summary: Publish a long-form merge re-encode claim-check.
+    description: |
+      As `publishLongFormCompressVideo`, for `operation_type = merge`
+      (`merge.video.long_form_re_encode`). Direct-to-SQS claim-check; no SNS.
+    messages:
+      - $ref: '#/channels/longformMergeVideoReencode/messages/longFormJob'
+
+  # ============================================
+  # LONG-FORM CLAIM-CHECK CONSUMERS (launcher -> Fargate)
+  # ============================================
+
+  consumeLongFormCompressVideo:
+    action: receive
+    channel:
+      $ref: '#/channels/longformCompressVideo'
+    summary: Consume a long-form video compression claim-check.
+    description: |
+      A terraform-owned launcher (EventBridge Pipe, filter=none -> launcher
+      Lambda) reads the `LongFormJobMessage` from this queue, resolves the
+      full job spec from S3 via `pointer`, and runs a Fargate task. The
+      launcher forks on `operation_type` (`compress`) + `processing_class`
+      (`long_form`). Failures redrive to the DLQ after `max_receive_count = 2`.
+    messages:
+      - $ref: '#/channels/longformCompressVideo/messages/longFormJob'
+
+  consumeLongFormMergeVideoReencode:
+    action: receive
+    channel:
+      $ref: '#/channels/longformMergeVideoReencode'
+    summary: Consume a long-form merge re-encode claim-check.
+    description: |
+      As `consumeLongFormCompressVideo`, for `operation_type = merge`
+      (`merge.video.long_form_re_encode`). The launcher resolves the spec
+      from S3 via `pointer` and runs the merge-re-encode Fargate task.
+    messages:
+      - $ref: '#/channels/longformMergeVideoReencode/messages/longFormJob'
+
 components:
   messages:
     # ============================================
@@ -1689,7 +1870,7 @@ components:
         **non-compression** operation (thumbnail, image_watermark,
         text_watermark, merge, archive, convert, custom_luma,
         audio_overlay, audio_watermark, audio_to_video,
-        video_watermark, video_text_watermark). Published to the
+        video_watermark, video_text_watermark, split). Published to the
         `operations` SNS topic; routed by the single-attribute
         filter `operation_type` to one of the ops-family queues.
 
@@ -1699,8 +1880,8 @@ components:
           `thumbnail_office`, `image_watermark`, `text_watermark`,
           `merge`, `archive`, `convert`, `custom_luma`,
           `audio_overlay`, `audio_watermark`, `audio_to_video`,
-          `video_watermark`, `video_text_watermark`. Used by SNS as
-          the filter attribute on the `operations` topic.
+          `video_watermark`, `video_text_watermark`, `split`. Used by
+          SNS as the filter attribute on the `operations` topic.
         - `media_group`: informational metadata, present for every
           operation except `archive` (which is media-agnostic). Values:
           `image`, `video`, `audio`, `document`. **Not** used by SNS as
@@ -1709,7 +1890,8 @@ components:
 
         **Input models:**
         - Single-input operations (thumbnail, text_watermark, convert,
-          audio_watermark): use `source_bucket` + `source_key`.
+          audio_watermark, video_text_watermark, split): use
+          `source_bucket` + `source_key`.
           `file_type` required. For `thumbnail`, the SNS
           `operation_type` attribute is permitted to carry a per-media
           sub-type value for routing (see `OperationRequestAttributes`
@@ -1719,23 +1901,29 @@ components:
           `required_tier: enterprise` so workflow-create rejects with
           422 + 403 today.
         - Multi-input operations (merge, archive, image_watermark,
-          custom_luma, audio_overlay, audio_to_video): use `sources`
-          array. Merge additionally requires `output_type`.
-          image_watermark, custom_luma, audio_overlay, and
-          audio_to_video use `role` per `JobInputV2.role`.
+          custom_luma, audio_overlay, audio_to_video, video_watermark):
+          use `sources` array. Merge additionally requires `output_type`.
+          image_watermark, custom_luma, audio_overlay, audio_to_video,
+          and video_watermark use `role` per `JobInputV2.role`.
           audio_to_video has role asymmetry — REQUIRED `base` (audio)
           + OPTIONAL `overlay` (image 0..1) per
           `per_role_cardinality`; sum-of-role-minima drives the
           minimum `sources` count (1 for audio_to_video; 2 for all
-          other role-based ops today). custom_luma, audio_overlay,
-          and audio_to_video are `availability: planned` so
-          workflow-create rejects with 422 today.
+          other role-based ops today). custom_luma and audio_overlay
+          are `availability: planned` so workflow-create rejects with
+          422 today (audio_to_video and video_watermark are now `beta` —
+          Wave A activated).
 
         **Migration window note.** During the thumbnail sub-type
         migration, both `operation_type=thumbnail` (legacy) and
         `operation_type=thumbnail_{image,video,document,office}` (new)
-        are valid routing targets. The API publisher currently emits
-        the legacy value only; sub-type adoption is a follow-up API PR.
+        are valid routing targets. The API publisher emits the per-media
+        sub-type value on the SNS `operation_type` attribute (resolved
+        from the operation's effective input MIME); the payload
+        `operation_type` field always remains `thumbnail`. The legacy
+        bare `thumbnail` attribute value is retained as a valid routing
+        target during the migration window but is no longer emitted by
+        the publisher.
       contentType: application/json
       headers:
         $ref: '#/components/schemas/OperationRequestAttributes'
@@ -1912,6 +2100,48 @@ components:
             options:
               format: "zip"
 
+    # ============================================
+    # LONG-FORM CLAIM-CHECK JOB MESSAGE (direct-to-SQS, no SNS)
+    # ============================================
+
+    LongFormJobMessage:
+      name: LongFormJob
+      title: Long-Form Claim-Check Job Message
+      summary: Claim-check job message for long-form (Fargate) operations
+      description: |
+        Published by the API **directly to a per-op-class long-form SQS queue**
+        (not via SNS) and consumed by a terraform-owned launcher (EventBridge
+        Pipe, filter=none -> launcher Lambda -> ECS RunTask). The launcher reads
+        the message body, resolves the full job spec from S3 via `pointer`, and
+        forks the Fargate task on `operation_type` + `processing_class`.
+
+        **No SNS message attributes / headers** — long-form does not flow
+        through an SNS topic, so unlike `JobRequestMessage` /
+        `OperationRequestMessage` this message carries no `headers` block.
+
+        See the `LongFormJobMessage` schema for the claim-check field set and
+        the `processing_class` ratification rationale.
+      contentType: application/json
+      payload:
+        $ref: '#/components/schemas/LongFormJobMessage'
+      examples:
+        - name: Long-form video compression
+          summary: compress.video.long_form claim-check
+          payload:
+            pointer: "job-specs/018f9c42-5d6b-7481-b3df-9fd0a0a5e112.json"
+            job_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e112"
+            operation_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e200"
+            operation_type: "compress"
+            processing_class: "long_form"
+        - name: Long-form merge re-encode
+          summary: merge.video.long_form_re_encode claim-check
+          payload:
+            pointer: "job-specs/018f9c42-5d6b-7481-b3df-9fd0a0a5e113.json"
+            job_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e113"
+            operation_id: "018f9c42-5d6b-7481-b3df-9fd0a0a5e201"
+            operation_type: "merge"
+            processing_class: "long_form"
+
     # ============================================
     # OPERATION PROGRESS MESSAGE
     # ============================================
@@ -2450,9 +2680,10 @@ components:
           prefix per ADR-0015 — the operation is multi-input
           role-based with role asymmetry: required audio base +
           optional image overlay; routing follows the `base` role).
-          The operation is `availability: planned` per
-          [`SlluxMBN`](https://trello.com/c/SlluxMBN), so this
-          constraint is contract-defined but not exercised today.
+          The operation is `availability: beta` per
+          [`SlluxMBN`](https://trello.com/c/SlluxMBN) +
+          [`c3uthIP4`](https://trello.com/c/c3uthIP4) (Wave A activated),
+          so this constraint is exercised on live traffic.
         - For `operation_type = image_watermark`, `media_group` must
           equal `image` while only the stable `image` mime_group is
           dispatchable. The schema declares `image_gif` and `video`
@@ -2630,17 +2861,18 @@ components:
         API to SNS, consumed by Lambda from SQS.
 
         **Single-input operations** (compress, thumbnail, text_watermark,
-        convert): use `source_bucket` + `source_key` for the input file.
-        `file_type` is required.
+        convert, audio_watermark, video_text_watermark, split): use
+        `source_bucket` + `source_key` for the input file. `file_type` is
+        required.
 
         **Multi-input operations** (merge, archive, image_watermark,
-        custom_luma, audio_overlay, audio_to_video): use `sources`
-        array. Each entry has `bucket` + `key`. Merge entries may
-        include per-input overrides (e.g. transition type). Merge
-        also requires `output_type`. custom_luma, audio_overlay, and
-        audio_to_video are
-        `availability: planned` so workflow-create rejects with 422
-        today; the wire shape is contract-defined.
+        custom_luma, audio_overlay, audio_to_video, video_watermark):
+        use `sources` array. Each entry has `bucket` + `key`. Merge
+        entries may include per-input overrides (e.g. transition type).
+        Merge also requires `output_type`. custom_luma and audio_overlay
+        are `availability: planned` so workflow-create rejects with 422
+        today (audio_to_video + video_watermark are now `beta` — Wave A
+        activated, backends live); the wire shape is contract-defined.
 
         Note: `media_group` is **not** a field in this payload. It exists
         only as an SNS MessageAttribute on the non-compression branch; on
@@ -2738,12 +2970,13 @@ components:
           description: |
             Input files for multi-input operations (merge, archive,
             image_watermark, custom_luma, audio_overlay,
-            audio_to_video). Each entry specifies an S3 location.
-            Order matters for merge (concatenation order). Per-input
-            overrides (e.g. transition) can be inlined on each entry.
-            Role-based multi-input operations (image_watermark,
-            custom_luma, audio_overlay, audio_to_video) require a
-            `role` discriminator on each entry — see `SourceEntry.role`.
+            audio_to_video, video_watermark). Each entry specifies an
+            S3 location. Order matters for merge (concatenation order).
+            Per-input overrides (e.g. transition) can be inlined on each
+            entry. Role-based multi-input operations (image_watermark,
+            custom_luma, audio_overlay, audio_to_video, video_watermark)
+            require a `role` discriminator on each entry — see
+            `SourceEntry.role`.
 
             **Minimum source count = sum of role minima** declared in
             the operation's `per_role_cardinality` (per ticket
@@ -2795,11 +3028,84 @@ components:
             Not used in V1 — all outputs go to GISL-managed S3 buckets.
           additionalProperties: true
 
+    LongFormJobMessage:
+      type: object
+      description: |
+        Claim-check job message for long-form (Fargate-processed) operations.
+        Emitted by the API **directly to the per-op-class long-form SQS queues**
+        (NOT via SNS) — see the `longformCompressVideo` / `longformMergeVideoReencode`
+        channels. The full job spec is written to S3 and this message carries only
+        a `pointer` (the claim check) plus routing/identity fields; the consumer
+        (a terraform-owned launcher Lambda fronting a Fargate worker, invoked via
+        an EventBridge Pipe with no filter) reads the spec from S3 and forks the
+        task on `operation_type` + `processing_class`.
+
+        Distinct from `OperationRequest` (the SNS-routed short-form payload):
+        long-form has its own dedicated SQS queues, carries no SNS message
+        attributes/headers, and uses a claim-check body. `processing_class` is
+        ratified here — and ONLY here — as the logical long-form discriminator
+        (per [ADR-0014](../docs/decisions/0014-split-operation.md) §D10 and
+        `schemas/FORMAT.md` §F8). The physical worker / `execution_pool` /
+        backend-dotted form (e.g. `compress.video.long_form`) is deliberately
+        NOT on the wire — the launcher mints it internally.
+
+        **Live `operation_type` subset: `compress`, `merge`** — the two
+        long-form classes flipped to `availability: beta` (CON-1). `split`
+        long-form (queue provisioned, publisher deferred —
+        [`rcwvUKhI`](https://trello.com/c/rcwvUKhI)) and `audio_overlay`
+        long-form (reserve-name-only, no queue) are NOT yet produced and are
+        therefore absent from this enum; they get added when their publishers
+        ship.
+
+        **Scope: the API producer's first-publish.** This schema models the
+        message the API publishes to the long-form queues — the 5 fields above.
+        It is intentionally an **open object** (no `additionalProperties: false`):
+        these queues may also carry downstream-produced messages (e.g. a
+        `FargateRunner` retry republish of chained long-form ops) whose body
+        shape is owned by the worker/lambdas contract, NOT this schema. Those
+        are out of scope here and are not constrained by `LongFormJobMessage`;
+        consumers validating against this schema MUST tolerate additional or
+        differently-shaped redriven messages. The producer contract this schema
+        pins is the **required** set.
+      required:
+        - pointer
+        - job_id
+        - operation_id
+        - operation_type
+        - processing_class
+      properties:
+        pointer:
+          type: string
+          pattern: '^job-specs/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.json$'
+          description: |
+            Claim-check pointer to the full job spec: an S3 object **key**
+            (NOT a full `s3://` URI, NOT a `{bucket,key}` object), resolved
+            relative to the **input bucket** — the bucket is not encoded in
+            the pointer; the consumer resolves it from its own input-bucket
+            config. Const prefix `job-specs/`; the object is `<jobId>.json`
+            (UUID v7).
+          example: "job-specs/018f9c42-5d6b-7481-b3df-9fd0a0a5e112.json"
+        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/LongFormOperationType'
+        processing_class:
+          $ref: '#/components/schemas/LongFormProcessingClass'
+
     SourceEntry:
       type: object
       description: |
         A single source file for multi-input operations (merge,
-        archive, image_watermark, custom_luma, audio_overlay).
+        archive, image_watermark, custom_luma, audio_overlay,
+        audio_to_video, video_watermark).
         Provides the S3 location, optional per-input overrides, and
         the `role` discriminator for role-based multi-input
         operations.
@@ -2822,9 +3128,52 @@ components:
         transition:
           type: string
           description: |
-            Per-input transition override for video merge.
-            Overrides the global transition option for the join point before this input.
+            Per-input transition override for the join point before this
+            input. Applies to both video and audio merge — see the
+            per-media per-input transition catalogs in
+            `schemas/operations/merge.yaml`
+            (`merge.video.per_input_options` / `merge.audio.per_input_options`),
+            which the API validates against. Overrides the global
+            `options.transition` for this join point.
           example: "none"
+        crossfade_duration:
+          type: number
+          minimum: 0
+          maximum: 10.0
+          description: |
+            Per-input crossfade duration override, in seconds, for the
+            join point before this input. Overrides the global
+            `options.crossfade_duration` for this join point. Per the
+            `depends_on` on `merge.*.per_input_options.crossfade_duration`
+            (which resolves against the sibling per-input option, see
+            FORMAT.md), this takes effect only when this input's own
+            `transition` override is `crossfade` — pair it with
+            `transition: crossfade` on the same entry; it does NOT key off
+            the global `options.transition`. Mirrors
+            `merge.*.per_input_options.crossfade_duration` in
+            `schemas/operations/merge.yaml` — the API validates this
+            per-input value but, until this slot existed, dropped it at the
+            wire boundary (the slot lets the merge Lambda's audio path
+            honour it). The 0–10s bound here is a broad transport envelope;
+            the effective per-media limits (video crossfade `0.1`–`5.0`,
+            audio `0`–`10`) are enforced by the per-mime-group
+            operation-options schema in `merge.yaml`, which the API
+            validates against before publishing.
+          example: 1.0
+        gap_duration:
+          type: number
+          minimum: 0
+          maximum: 10.0
+          description: |
+            Per-input silence/gap duration override, in seconds, inserted
+            before this input at the join point. Overrides the global
+            `options.gap_duration` for this join point. Mirrors
+            `merge.audio.per_input_options.gap_duration` in
+            `schemas/operations/merge.yaml` (no transition dependency) —
+            added alongside `crossfade_duration` so the API does not
+            silently drop this sibling per-input audio override at the wire
+            boundary.
+          example: 0.5
 
     # ============================================
     # OPERATION PROGRESS SCHEMA
@@ -2891,8 +3240,9 @@ components:
             `phase_input_index`. For single-input operations (most
             ops) `phase_total_inputs: 1` and `phase_input_index: 1`
             during the relevant phase. For multi-input merge,
-            archive, image_watermark, custom_luma, and audio_overlay,
-            this matches the inputs[] count. Per ticket I27.
+            archive, image_watermark, custom_luma, audio_overlay,
+            audio_to_video, and video_watermark, this matches the
+            inputs[] count. Per ticket I27.
           example: 4
 
     # ============================================
@@ -3567,12 +3917,22 @@ components:
           description: Container-reported duration (audio + video).
         width:
           type: integer
+          format: int64
           minimum: 1
-          description: Pixel width (image + video; best-effort document).
+          description: |
+            Pixel width (image + video; best-effort document). Declared
+            `int64` so Rust SDK generators emit `i64` instead of the
+            default `i32`; `i32` is fine for everything ffmpeg/libcaesium
+            handles today but the format hint keeps the door open for
+            scientific / RAW imagery without future SDK churn (per
+            ticket [`0sTmbUsc`](https://trello.com/c/0sTmbUsc)).
         height:
           type: integer
+          format: int64
           minimum: 1
-          description: Pixel height (image + video; best-effort document).
+          description: |
+            Pixel height (image + video; best-effort document). See
+            `width` for the `format: int64` rationale.
         codec:
           type: string
           description: |
@@ -3607,12 +3967,16 @@ components:
             `29.97`, `23.976`).
         bitrate_bps:
           type: integer
+          format: int64
           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.
+            for video + audio. Declared `int64` so Rust SDK
+            generators emit `i64` instead of `i32`; `i32` caps at
+            ~2.1 Gbps which is tight for future 4K/8K/RAW workloads
+            (per ticket [`0sTmbUsc`](https://trello.com/c/0sTmbUsc)).
         audio_layout:
           type: string
           description: |
@@ -3759,10 +4123,10 @@ components:
           the first OPTIONAL role on the contract — `role: base`
           audio required, `role: overlay` image 0..1 per
           `per_role_cardinality`). When overlay is omitted, the video
-          uses a solid background colour. `availability: planned` per
-          the operation schema; the API rejects workflow-create with
-          `feature_not_available` (422) until the Lambda ships, so
-          traffic does not reach SNS today. `media_group` is derived
+          uses a solid background colour. `availability: beta` (Wave A,
+          [`c3uthIP4`](https://trello.com/c/c3uthIP4)) — the Lambda
+          backend is live, so the API accepts + publishes (MUST NOT 422);
+          traffic flows to SNS. `media_group` is derived
           from the `base` role input MIME prefix per ADR-0015 (always
           `audio` for audio_to_video). Routes via
           `operation_type=audio_to_video` to `ops-audio-to-video`.
@@ -3773,7 +4137,9 @@ components:
           of each per `per_role_cardinality { base: 1/1, overlay:
           1/1 }`). Re-encode required; audio stream-copy passthrough.
           Distinct from `image_watermark` (pure-Rust/image-only —
-          see ADR-0013). `availability: planned`; routes via
+          see ADR-0013). `availability: beta` (Wave A, `c3uthIP4` —
+          Lambda backend live; `short_form` beta, `long_form` stays
+          `planned`); routes via
           `operation_type=video_watermark` to `ops-video-watermark`.
           Per ADR-0004 + ADR-0013
           ([`4NrRPCgh`](https://trello.com/c/4NrRPCgh)).
@@ -3795,8 +4161,10 @@ components:
           a separate `split-video-fargate` worker via
           `processing_class`. `media_group` derives from the input
           MIME prefix per the existing single-input rule (no
-          operation-specific conditional needed). `availability:
-          planned`; routes via `operation_type=split` to `ops-split`.
+          operation-specific conditional needed). `availability: beta`
+          for the `audio` mime_group (`image_gif` / `document_pdf` /
+          `video` stay `planned`); routes via `operation_type=split`
+          to `ops-split`.
           Per ADR-0004 + ADR-0014
           ([`vKI0CFDu`](https://trello.com/c/vKI0CFDu)).
       enum:
@@ -3934,6 +4302,47 @@ components:
         - stream_copy
         - re_encode
 
+    LongFormOperationType:
+      type: string
+      description: |
+        Coarse operation verb for the long-form claim-check job
+        (`LongFormJobMessage.operation_type`). Deliberately a call-site
+        **subset** of `OperationType` — only the long-form classes the API
+        actually publishes today (`compress`, `merge`). NOT the full
+        `OperationType` enum (which would over-promise the wire). Future
+        long-form publishers (e.g. `split` per
+        [`rcwvUKhI`](https://trello.com/c/rcwvUKhI)) widen this enum when
+        they ship.
+
+        Named-schema form lifted from inline at
+        `LongFormJobMessage.operation_type` per ticket
+        [`A3DyuYUd`](https://trello.com/c/A3DyuYUd) — generated SDK bindings
+        emit a stable typed name instead of an `AnonymousSchema_N`
+        placeholder.
+      enum:
+        - compress
+        - merge
+
+    LongFormProcessingClass:
+      type: string
+      description: |
+        Logical processing class on the long-form claim-check wire
+        (`LongFormJobMessage.processing_class`) — always the literal
+        `long_form` (never `short_form` / `blocked`; those exist only on the
+        upload-probe response and HTTP plan surfaces). The launcher forks on
+        this field; do not confuse it with the backend worker identity, which
+        stays off the wire per `schemas/FORMAT.md` §F8.
+
+        A single-value enum (not a JSON-Schema `const`): named + `enum` is the
+        repo's proven typed-codegen form (mirrors `JobInputRole` /
+        `ReEncodeDecision`), whereas `const` degraded to an unconstrained
+        `String` in SDK generators. Lifted from inline at
+        `LongFormJobMessage.processing_class` per ticket
+        [`A3DyuYUd`](https://trello.com/c/A3DyuYUd). Single-member enum
+        validates identically to the prior `const long_form`.
+      enum:
+        - long_form
+
     ProgressStatus:
       type: string
       description: |