@giveitsmaller/contracts 0.3.0 → 0.5.0

package/openapi/api.yaml

@@ -75,7 +75,7 @@ info:
     of truth instead of hardcoding magic numbers. A runtime
     `GET /api/uploads/limits` endpoint for dynamic discovery
     (per-tier / per-environment overrides) is a deferred follow-up.
-  version: 2.7.1
+  version: 2.15.3
   contact:
     name: API Support
 
@@ -302,7 +302,7 @@ paths:
         for the remaining parts. The client uploads parts 2-N directly to S3.
 
         **Recommended client behaviour:** chunk size
-        `UploadThresholds.multipart_chunk_size` (5 MiB) with
+        `UploadThresholds.multipart_chunk_size` (16 MiB) with
         `UploadThresholds.multipart_concurrency_default` parallel uploads.
         The server returns `recommended_chunk_size` per file based on
         first-chunk throughput; SDKs SHOULD prefer that runtime value when
@@ -311,9 +311,10 @@ paths:
         **Chunk sizing strategy:**
         - First chunk: fixed `UploadThresholds.multipart_first_chunk_size` = 8 MiB (sent to API)
         - Remaining chunks: API calculates `recommended_chunk_size` from throughput * 5s,
-          clamped to 5MB-100MB
-        - The last part may be smaller than 5MB (S3 allows this for the final part)
-        - Maximum 500 parts per upload
+          clamped to 16 MiB–100 MiB
+        - The last part may be smaller than 16 MiB (S3 allows this for the final part)
+        - Maximum 10,000 parts per upload (the S3 multipart hard limit;
+          raised from 500 by CON-1/ADR-0011 for the 120 GB Enterprise envelope)
 
         **Pre-signed URL TTL:**
         Dynamic based on estimated upload duration * 2, clamped between 900s and 3600s.
@@ -343,7 +344,7 @@ paths:
                   first_chunk_etag: '"d8e8fca2dc0f896fd7cb4cb0031ba249"'
                   first_chunk_size_bytes: 8388608
                   total_parts: 5
-                  recommended_chunk_size: 10485760
+                  recommended_chunk_size: 16777216
                   presigned_urls:
                     - part_number: 2
                       url: "https://gisl-stg-euw1-input.s3.eu-west-1.amazonaws.com/uploads/...?X-Amz-Expires=1800&..."
@@ -444,6 +445,15 @@ paths:
 
         The API calls S3 CompleteMultipartUpload and persists the upload record.
         No job or workflow is created — use `POST /api/workflows` to process the file.
+
+        **Ownership enforcement** (per session-resume work, ticket
+        [`HxUmVr3Y`](https://trello.com/c/HxUmVr3Y)): when
+        `manifest.userId` is non-null, `multipart/complete` refuses
+        completion by any caller other than the original authenticator
+        (returns 403 `MULTIPART_SESSION_OWNERSHIP`). The sister
+        endpoints `/status`, `/presign`, `/keepalive` apply the same
+        rule and additionally refuse anonymous-initiated sessions
+        outright (returning 403 `MULTIPART_SESSION_AUTH_REQUIRED`).
       operationId: multipartComplete
       tags:
         - Upload
@@ -479,6 +489,20 @@ paths:
               example:
                 success: false
                 error: "Missing ETags for parts: 3, 5"
+        '403':
+          description: |
+            Forbidden — session's `manifest.userId` is non-null and
+            differs from the authenticated caller. Per ticket
+            [`HxUmVr3Y`](https://trello.com/c/HxUmVr3Y) ownership
+            enforcement (carried by the same controller path as the
+            three new resume endpoints).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: "MULTIPART_SESSION_OWNERSHIP"
         '404':
           description: Upload session not found or expired
           content:
@@ -495,6 +519,341 @@ paths:
               schema:
                 $ref: '#/components/schemas/ErrorEnvelope'
 
+  /api/uploads/multipart/{uploadId}/status:
+    get:
+      summary: Cursor over uploaded parts of an in-flight multipart session
+      description: |
+        Returns the list of parts already received by S3 for an in-flight
+        multipart session. Used by SDKs to resume an interrupted upload —
+        the client walks the cursor pages, collects which `part_number`
+        slots are filled, and re-presigns / re-uploads only the missing
+        slots via `POST /api/uploads/multipart/{uploadId}/presign`.
+
+        The response shape is a 1:1 passthrough of the S3 ListParts API —
+        `next_part_number_marker` and `is_truncated` mirror the upstream
+        wire shape verbatim (no translation layer, zero impedance
+        mismatch for SDKs that already speak S3 vocabulary).
+
+        **Authentication required.** Anonymous-initiated sessions (allowed
+        at `/initiate` today; the `8LABloaz` follow-up flips that to
+        require-auth) cannot use this endpoint and receive 403
+        `MULTIPART_SESSION_AUTH_REQUIRED`. Authenticated callers can only
+        list parts of sessions they initiated (403
+        `MULTIPART_SESSION_OWNERSHIP` otherwise).
+
+        Cursor semantics: pass `cursor=0` (default) for the first page;
+        the server returns up to `limit` parts plus `next_part_number_marker`
+        and `is_truncated`. To walk: pass each `next_part_number_marker`
+        as the next request's `cursor` until `is_truncated: false`. The
+        marker is `null` on the final page.
+
+        Completion-readiness is client-derived (walk all pages, compare
+        the count of returned parts to `total_parts`).
+      operationId: multipartStatus
+      tags:
+        - Upload
+      parameters:
+        - name: uploadId
+          in: path
+          required: true
+          description: Multipart upload session identifier from the initiate response.
+          schema:
+            $ref: '#/components/schemas/UuidV7'
+        - name: cursor
+          in: query
+          required: false
+          description: |
+            S3 ListParts `PartNumberMarker` (the part-number to start
+            listing **after**). `0` (default) returns from the first
+            part. Walk by passing each response's
+            `next_part_number_marker` until `is_truncated: false`.
+          schema:
+            type: integer
+            minimum: 0
+            maximum: 9999
+            default: 0
+        - name: limit
+          in: query
+          required: false
+          description: |
+            Page size — maximum number of parts returned per request.
+            `1000` is the default and the upstream S3 `MaxParts` cap.
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 1000
+            default: 1000
+      responses:
+        '200':
+          description: Page of uploaded parts.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MultipartStatusSuccessEnvelope'
+              example:
+                success: true
+                data:
+                  upload_id: "019539ab-1111-7000-8000-000000000001"
+                  multipart_upload_id: "5MqcMpgg9_pKVdoO9.X9eK0w2g3Sq5_h"
+                  cloud_key: "uploads/01/019539ab-1111-7000-8000-000000000001/source"
+                  total_parts: 5
+                  uploaded_parts:
+                    - part_number: 1
+                      etag: '"d8e8fca2dc0f896fd7cb4cb0031ba249"'
+                      size_bytes: 8388608
+                      last_modified: "2026-05-20T13:30:00.000Z"
+                    - part_number: 2
+                      etag: '"7c3e2c4b6e3e7e0e8f9d1a2b3c4d5e6f"'
+                      size_bytes: 16777216
+                      last_modified: "2026-05-20T13:31:14.000Z"
+                  next_part_number_marker: null
+                  is_truncated: false
+                  manifest_expires_at: "2026-05-22T13:31:14.000Z"
+                  recommended_chunk_size: 16777216
+        '401':
+          description: Authentication required.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '403':
+          description: |
+            Forbidden — either the session was anonymously initiated
+            (`MULTIPART_SESSION_AUTH_REQUIRED`) or the authenticated
+            caller is not the session owner (`MULTIPART_SESSION_OWNERSHIP`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              examples:
+                auth_required:
+                  summary: Anonymous-initiated session
+                  value:
+                    success: false
+                    error: "MULTIPART_SESSION_AUTH_REQUIRED"
+                ownership:
+                  summary: Session belongs to a different authenticated caller
+                  value:
+                    success: false
+                    error: "MULTIPART_SESSION_OWNERSHIP"
+        '404':
+          description: Multipart session not found or expired.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: "MULTIPART_SESSION_NOT_FOUND"
+        '500':
+          description: Internal server error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+
+  /api/uploads/multipart/{uploadId}/presign:
+    post:
+      summary: Sparse re-presign of multipart parts (resume / retry)
+      description: |
+        Returns fresh pre-signed PUT URLs for a caller-supplied subset
+        of part numbers. Used by SDKs to (a) resume an interrupted
+        upload after the original presigned URLs have expired, and
+        (b) retry individual failed PUTs without re-presigning the
+        whole upload.
+
+        Part numbers MUST satisfy `2 ≤ n ≤ total_parts`. **Part 1 is
+        rejected** because the manifest stores its ETag from `/initiate`
+        — re-presigning part 1 would break the eventual
+        `multipart/complete` call. Request the list with
+        `uniqueItems`; duplicates are rejected with a 400.
+
+        At most 100 part numbers per request. SDKs paginate larger
+        sets across multiple `/presign` calls.
+
+        **Authentication required.** Same `MULTIPART_SESSION_*` codes
+        apply as on `/status`.
+      operationId: multipartPresign
+      tags:
+        - Upload
+      parameters:
+        - name: uploadId
+          in: path
+          required: true
+          description: Multipart upload session identifier from the initiate response.
+          schema:
+            $ref: '#/components/schemas/UuidV7'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/MultipartPresignRequest'
+      responses:
+        '200':
+          description: Pre-signed URLs returned for the requested parts.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MultipartPresignSuccessEnvelope'
+              example:
+                success: true
+                data:
+                  upload_id: "019539ab-1111-7000-8000-000000000001"
+                  presigned_urls:
+                    - part_number: 3
+                      url: "https://gisl-stg-euw1-input.s3.eu-west-1.amazonaws.com/uploads/...?X-Amz-Expires=1800&..."
+                      expires_at: "2026-05-20T14:01:14.000Z"
+                    - part_number: 5
+                      url: "https://gisl-stg-euw1-input.s3.eu-west-1.amazonaws.com/uploads/...?X-Amz-Expires=1800&..."
+                      expires_at: "2026-05-20T14:01:14.000Z"
+        '400':
+          description: |
+            Validation failed — e.g. body too large, malformed JSON,
+            `part_numbers` empty / >100, contains duplicates, contains
+            `1`, contains values outside `[2, total_parts]`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: "part_numbers must contain unique values in [2, total_parts]; part 1 is sealed"
+        '401':
+          description: Authentication required.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '403':
+          description: |
+            Forbidden — either the session was anonymously initiated
+            (`MULTIPART_SESSION_AUTH_REQUIRED`) or the authenticated
+            caller is not the session owner (`MULTIPART_SESSION_OWNERSHIP`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              examples:
+                auth_required:
+                  value:
+                    success: false
+                    error: "MULTIPART_SESSION_AUTH_REQUIRED"
+                ownership:
+                  value:
+                    success: false
+                    error: "MULTIPART_SESSION_OWNERSHIP"
+        '404':
+          description: Multipart session not found or expired.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: "MULTIPART_SESSION_NOT_FOUND"
+        '422':
+          description: |
+            Session no longer accepts re-presign requests because the
+            assembled object would exceed the S3 multipart capacity
+            cap. Pre-S3 server-side capacity gate; distinct from
+            tier-quota rejections at `/initiate` time.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: "FILE_TOO_LARGE_FOR_MULTIPART"
+        '500':
+          description: Internal server error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+
+  /api/uploads/multipart/{uploadId}/keepalive:
+    post:
+      summary: Refresh the multipart session manifest TTL
+      description: |
+        Resets the session manifest's TTL to 48 h ahead of now. The
+        server uses an atomic Redis `EXPIRE`; the operation is
+        idempotent — calling it multiple times in succession produces
+        the same effective TTL window.
+
+        SDKs SHOULD call this periodically on resume flows (e.g. once
+        per minute while a resumable upload is paused) to prevent the
+        manifest from lapsing. The manifest TTL is decoupled from
+        individual presigned-URL TTLs (which are typically 900s–3600s);
+        re-presigning expired URLs requires the manifest still be
+        alive.
+
+        Empty request body.
+
+        **Authentication required.** Same `MULTIPART_SESSION_*` codes
+        apply as on `/status` and `/presign`.
+      operationId: multipartKeepalive
+      tags:
+        - Upload
+      parameters:
+        - name: uploadId
+          in: path
+          required: true
+          description: Multipart upload session identifier from the initiate response.
+          schema:
+            $ref: '#/components/schemas/UuidV7'
+      responses:
+        '200':
+          description: Manifest TTL refreshed; new expiry returned.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MultipartKeepaliveSuccessEnvelope'
+              example:
+                success: true
+                data:
+                  upload_id: "019539ab-1111-7000-8000-000000000001"
+                  manifest_expires_at: "2026-05-22T13:31:14.000Z"
+        '401':
+          description: Authentication required.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '403':
+          description: |
+            Forbidden — either the session was anonymously initiated
+            (`MULTIPART_SESSION_AUTH_REQUIRED`) or the authenticated
+            caller is not the session owner (`MULTIPART_SESSION_OWNERSHIP`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              examples:
+                auth_required:
+                  value:
+                    success: false
+                    error: "MULTIPART_SESSION_AUTH_REQUIRED"
+                ownership:
+                  value:
+                    success: false
+                    error: "MULTIPART_SESSION_OWNERSHIP"
+        '404':
+          description: Multipart session not found or expired.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: "MULTIPART_SESSION_NOT_FOUND"
+        '500':
+          description: Internal server error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+
   /api/uploads/{id}/metadata:
     get:
       summary: Get file metadata
@@ -609,82 +968,92 @@ paths:
       responses:
         '200':
           description: |
-            Probe completed. The `probe_status` field indicates
+            Probe completed. The `data.probe_status` field indicates
             whether the file is workflow-ready (`ok`) or has issues
             that warrant exclusion / re-upload.
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/UploadProbeResponse'
+                $ref: '#/components/schemas/UploadProbeSuccessEnvelope'
               examples:
                 ok_short_form:
                   summary: Short-form clip probed cleanly
                   value:
-                    file_id: "019539ab-1111-7000-8000-000000000001"
-                    probe_status: "ok"
-                    media_metadata:
-                      duration_seconds: 187
-                      width: 1920
-                      height: 1080
-                      codec: "h264"
-                      container: "mp4"
-                      audio_layout: "stereo"
-                      probed_at: "2026-04-26T13:50:00Z"
-                    processing_class_pre_assignment: "short_form"
+                    success: true
+                    data:
+                      file_id: "019539ab-1111-7000-8000-000000000001"
+                      probe_status: "ok"
+                      media_metadata:
+                        duration_seconds: 187
+                        width: 1920
+                        height: 1080
+                        codec: "h264"
+                        container: "mp4"
+                        audio_layout: "stereo"
+                        probed_at: "2026-04-26T13:50:00Z"
+                      processing_class_pre_assignment: "short_form"
                 ok_long_form:
                   summary: Long-form clip — full M2 union populated (video + audio fields)
                   value:
-                    file_id: "019539ab-1111-7000-8000-000000000002"
-                    probe_status: "ok"
-                    media_metadata:
-                      duration_seconds: 5400
-                      width: 3840
-                      height: 2160
-                      codec: "h265"
-                      audio_codec: "aac"
-                      container: "mp4"
-                      fps: 23.976
-                      bitrate_bps: 18000000
-                      audio_layout: "stereo"
-                      channels: 2
-                      sample_rate_hz: 48000
-                      probed_at: "2026-04-26T13:50:00Z"
-                    processing_class_pre_assignment: "long_form"
+                    success: true
+                    data:
+                      file_id: "019539ab-1111-7000-8000-000000000002"
+                      probe_status: "ok"
+                      media_metadata:
+                        duration_seconds: 5400
+                        width: 3840
+                        height: 2160
+                        codec: "h265"
+                        audio_codec: "aac"
+                        container: "mp4"
+                        fps: 23.976
+                        bitrate_bps: 18000000
+                        audio_layout: "stereo"
+                        channels: 2
+                        sample_rate_hz: 48000
+                        probed_at: "2026-04-26T13:50:00Z"
+                      processing_class_pre_assignment: "long_form"
                 corrupt:
                   summary: File header damaged — caller should exclude
                   value:
-                    file_id: "019539ab-1111-7000-8000-000000000003"
-                    probe_status: "corrupt"
-                    media_metadata:
-                      probed_at: "2026-04-26T13:50:00Z"
-                    processing_class_pre_assignment: "blocked"
+                    success: true
+                    data:
+                      file_id: "019539ab-1111-7000-8000-000000000003"
+                      probe_status: "corrupt"
+                      media_metadata:
+                        probed_at: "2026-04-26T13:50:00Z"
+                      processing_class_pre_assignment: "blocked"
                 unsupported_codec:
                   summary: Container readable but codec unsupported
                   value:
-                    file_id: "019539ab-1111-7000-8000-000000000004"
-                    probe_status: "unsupported_codec"
-                    media_metadata:
-                      duration_seconds: 600
-                      width: 1280
-                      height: 720
-                      codec: "prores_4444"
-                      container: "mov"
-                      probed_at: "2026-04-26T13:50:00Z"
-                    processing_class_pre_assignment: "blocked"
+                    success: true
+                    data:
+                      file_id: "019539ab-1111-7000-8000-000000000004"
+                      probe_status: "unsupported_codec"
+                      media_metadata:
+                        duration_seconds: 600
+                        width: 1280
+                        height: 720
+                        codec: "prores_4444"
+                        container: "mov"
+                        probed_at: "2026-04-26T13:50:00Z"
+                      processing_class_pre_assignment: "blocked"
                 blocked_by_tier:
                   summary: Free-tier caller probes a long-form clip
                   value:
-                    file_id: "019539ab-1111-7000-8000-000000000005"
-                    probe_status: "ok"
-                    media_metadata:
-                      duration_seconds: 5400
-                      width: 1920
-                      height: 1080
-                      codec: "h264"
-                      container: "mp4"
-                      audio_layout: "stereo"
-                      probed_at: "2026-04-26T13:50:00Z"
-                    processing_class_pre_assignment: "blocked"
+                    success: true
+                    data:
+                      file_id: "019539ab-1111-7000-8000-000000000005"
+                      probe_status: "ok"
+                      media_metadata:
+                        duration_seconds: 5400
+                        width: 1920
+                        height: 1080
+                        codec: "h264"
+                        container: "mp4"
+                        audio_layout: "stereo"
+                        probed_at: "2026-04-26T13:50:00Z"
+                      processing_class_pre_assignment: "blocked"
         '401':
           description: Authentication required.
           content:
@@ -762,12 +1131,21 @@ paths:
         side-effect dependencies that don't surface as `from`
         references).
 
-        **Default operation:** if `operations` is omitted on a
-        single-input job with `source: { type: upload, ... }`, the
-        default is `[{ "type": "compress" }]` with default options for
-        the detected MIME type. Multi-input jobs must always specify
+        **Default operation:** if `operations` is omitted — or
+        explicitly empty (`[]`) — on a single-input job with
+        `source: { type: upload, ... }`, the default is
+        `[{ "type": "compress" }]` with default options for the
+        detected MIME type. Multi-input jobs must always specify
         operations explicitly.
 
+        **Compression opt-out:** V2 has no `skip_compression` flag —
+        `operations[]` *is* the chain. To opt a job out of
+        compression, send an explicit non-empty `operations[]` that
+        does not include `compress`; on a single-input upload job an
+        empty `[]` does *not* opt out (it is treated as omitted and
+        still receives the implicit `compress` — see above). Per
+        [ADR-0004](../docs/decisions/0004-job-shape.md).
+
         **Multi-input constraint:** multi-input jobs (`inputs[]`) must
         have exactly one operation, which must be a multi-input type
         (`merge`, `archive`, `image_watermark`, `custom_luma`, or
@@ -1077,7 +1455,7 @@ paths:
                 error: "Upload not found: 019539ab-1111-7000-8000-999999999999"
         '422':
           description: |
-            Semantically invalid request. Either:
+            Semantically invalid request. One of:
 
             - Generic validation error (unknown operation type, invalid
               option combinations, cyclic dependency in workflow_edges,
@@ -1090,6 +1468,22 @@ paths:
               with `error_type: feature_not_available`. Per ADR-0001
               §1.3 Tension 1 rule, the server MUST honour tagged
               availability.
+            - Processing-class band-ceiling overflow — returned as
+              `ProcessingClassExceedsBandResponse` with `error_type:
+              processing_class_exceeds_band`. Fires when one or more
+              jobs cannot be classified because input size/duration
+              exceeds the `long_form` (or `long_form_re_encode`)
+              ceiling under the caller's effective per-tier caps
+              (`per_tier_constraints` overlay per
+              [ADR-0011](../docs/decisions/0011-per-tier-processing-class-constraints.md)).
+              Per-violation `required_tier` names the tier (if any)
+              whose `per_tier_constraints` would accommodate the
+              request (`null` = no tier resolves, e.g. enterprise
+              already at the 120 GB hard ceiling). Distinct from
+              `TierRestrictionResponse` (403, request-level upload
+              quota — see [ADR-0012](../docs/decisions/0012-processing-class-band-reject-envelope.md)
+              for the band-vs-tier split). Per ADR-0001 §F6
+              batched-violations rule, `violations[]` is fail-all.
             - Re-encode required (per ticket I16-CONS, Trello
               `7nCZXEru`). Returned for `merge.video` jobs with
               `re_encode_mode: never` when the compatibility probe
@@ -1108,27 +1502,49 @@ paths:
             Backward-compatibility note: the prior 422 shape
             (`ValidationErrorEnvelope`) is preserved unchanged — its
             `details[]` array is the structural signature consumers
-            duck-type against. The new `FeatureNotAvailableResponse`
-            branch carries `error_type: feature_not_available` +
-            `violations[]` instead. The `REQUIRES_REENCODE` flavour
-            reuses `ValidationErrorEnvelope` (a user-fixable validation
-            error in the same family as `INVALID_OPTIONS`) and is
-            distinguished by the stable `error: "REQUIRES_REENCODE"`
-            string code rather than a new `error_type` enum value.
-            Branches are distinguishable by required fields (`details`
-            vs `error_type`+`violations`), so plain `oneOf` matches
-            without a discriminator object — see `openapi/api.yaml`
-            §"FEATURE AVAILABILITY ENVELOPES" commentary for the
-            convention rationale (no discriminator here because
-            `ValidationErrorEnvelope` has no `error_type` field;
-            OpenAPI 3.1 discriminators require the property to be
-            present on every branch).
+            duck-type against. `FeatureNotAvailableResponse` carries
+            `error_type: feature_not_available` + `violations[]`;
+            `ProcessingClassExceedsBandResponse` carries `error_type:
+            processing_class_exceeds_band` + `violations[]`.
+            `ProbePendingResponse` carries `error_type: probe_pending`
+            + `job_ref` (and NO `violations[]` / `details[]`), emitted
+            when the probe-pending gate is on and a job's upload has
+            not yet been probed. The `REQUIRES_REENCODE` flavour reuses
+            `ValidationErrorEnvelope`
+            (a user-fixable validation error in the same family as
+            `INVALID_OPTIONS`) and is distinguished by the stable
+            `error: "REQUIRES_REENCODE"` string code rather than a new
+            `error_type` enum value. Branches are distinguishable by
+            required-field shape (`details` vs `error_type` value), so
+            plain `oneOf` matches without a discriminator object — see
+            `openapi/api.yaml` §"FEATURE AVAILABILITY ENVELOPES"
+            commentary for the convention rationale (no discriminator
+            here because `ValidationErrorEnvelope` has no `error_type`
+            field; OpenAPI 3.1 discriminators require the property to
+            be present on every branch).
+          headers:
+            Retry-After:
+              required: false
+              description: |
+                Optional, best-effort. Present only on the
+                `probe_pending` branch — suggested seconds to wait
+                before re-polling the upload probe and retrying the
+                workflow. Delta-seconds (RFC 9110), mirroring the 429
+                login path's `Retry-After` convention. Absent until the
+                server-side probe-staleness bound (API `e1Idv6UL`)
+                lands; consumers MUST treat absence as "retry on your
+                own backoff schedule."
+              schema:
+                type: integer
+                minimum: 0
           content:
             application/json:
               schema:
                 oneOf:
                   - $ref: '#/components/schemas/ValidationErrorEnvelope'
                   - $ref: '#/components/schemas/FeatureNotAvailableResponse'
+                  - $ref: '#/components/schemas/ProcessingClassExceedsBandResponse'
+                  - $ref: '#/components/schemas/ProbePendingResponse'
               examples:
                 validation_error:
                   summary: Generic validation error (legacy shape)
@@ -1155,6 +1571,56 @@ paths:
                         documentation_url: "https://docs.giveitsmaller.com/operations/audio_overlay"
                       - feature: "operation.merge.mime_group.image.option.transition.dissolve"
                         availability: "experimental"
+                probe_pending:
+                  summary: |
+                    Probe-pending gate is on and a single-op video
+                    compress references an upload whose server-side
+                    probe has not yet landed. Client polls the upload
+                    probe endpoint, then re-POSTs the workflow. The
+                    `Retry-After` header (5s here) hints the poll delay.
+                  value:
+                    success: false
+                    error: "Upload probe has not completed; poll the upload probe endpoint and retry"
+                    error_type: "probe_pending"
+                    job_ref: "job_0"
+                    message_key: "error.probe_pending"
+                processing_class_exceeds_band_combined_size:
+                  summary: |
+                    merge job whose summed inputs (130 GB) exceed the
+                    Enterprise long_form_re_encode ceiling (120 GB
+                    hard cap per ADR-0011). Terminal — no tier
+                    resolves it; `required_tier` is null.
+                  value:
+                    success: false
+                    error: "Workflow contains inputs that exceed the long-form processing-class ceiling"
+                    error_type: "processing_class_exceeds_band"
+                    violations:
+                      - reason: "combined_size_exceeds_long_form"
+                        job_ref: "stitched"
+                        operation: "merge"
+                        processing_class: "long_form_re_encode"
+                        actual: 130000000000
+                        ceiling: 120000000000
+                        required_tier: null
+                        documentation_url: "https://docs.giveitsmaller.com/processing-class/long-form"
+                processing_class_exceeds_band_single_input_duration:
+                  summary: |
+                    compress.video job whose single input duration
+                    (15 hours = 54000s) exceeds the Pro long_form
+                    `max_input_duration` (PT12H = 43200s). Upgrade to
+                    Enterprise resolves the duration cap.
+                  value:
+                    success: false
+                    error: "Workflow contains inputs that exceed the long-form processing-class ceiling"
+                    error_type: "processing_class_exceeds_band"
+                    violations:
+                      - reason: "input_duration_exceeds_long_form"
+                        job_ref: "job_0"
+                        operation: "compress"
+                        processing_class: "long_form"
+                        actual: 54000
+                        ceiling: 43200
+                        required_tier: "enterprise"
                 requires_reencode:
                   summary: merge.video re_encode_mode=never with incompatible inputs (I16-CONS)
                   value:
@@ -1343,6 +1809,35 @@ paths:
         event: workflow.completed
         data: {"workflow_id":"wf-uuid","status":"completed"}
         ```
+
+        **Reconnect & delivery semantics:**
+
+        Delivery is **at-least-once per connection with no client-driven
+        resume**. The server does **not** read an inbound `Last-Event-ID`
+        header; each connection re-derives state from scratch and replays
+        every underlying stream from the start. Consequently **terminal events
+        (`operation.completed` / `operation.failed`, `job.completed` /
+        `job.failed`, `workflow.completed` / `workflow.failed` /
+        `workflow.partially_failed`) are re-delivered on every (re)connection**.
+        Within a single connection events are not duplicated (the cursor
+        advances as events are sent), so duplicates only arise across
+        reconnects. Clients MUST therefore treat the stream as idempotent and
+        dedupe terminal events themselves (e.g. by `operation_id` + event type,
+        or by workflow/job terminal status) rather than relying on
+        resume-from-cursor. Resume-from-`Last-Event-ID` is **not** implemented;
+        if added later it will be a separate, explicitly-specified feature.
+
+        **`id:` field (SSE event id):** emitted **only on operation frames**
+        (`operation.progress` / `operation.completed` / `operation.failed`),
+        where it carries the underlying stream's event id. **Transition frames**
+        (`job.completed` / `job.failed`, `workflow.*`) carry **no `id:`**.
+        Because there is no `Last-Event-ID` resume, any emitted `id:` is
+        informational only — clients cannot use it to resume a stream.
+
+        **Framing vs payload:** the `Sse*Data` component schemas describe only
+        the `data:` JSON payload of each event. The SSE envelope framing itself
+        (the `id:` and `event:` lines) is transport-level and intentionally
+        **not** schema-described.
       operationId: streamWorkflowEvents
       tags:
         - Workflow
@@ -2796,6 +3291,25 @@ components:
             `REQUIRES_REENCODE`). Canonical English; never localised.
             SDKs duck-type on this field for typed error-branch
             helpers.
+
+            Multipart-session resume codes (per ticket
+            [`HxUmVr3Y`](https://trello.com/c/HxUmVr3Y), V2.10.0):
+            - `MULTIPART_SESSION_NOT_FOUND` (404) — upload_id does
+              not match an in-flight session (expired / never
+              existed / wrong account namespace). Fired by /status,
+              /presign, /keepalive.
+            - `MULTIPART_SESSION_OWNERSHIP` (403) — authenticated
+              caller is not the session owner. Fired by /status,
+              /presign, /keepalive, /complete (when manifest.userId
+              is non-null and differs).
+            - `MULTIPART_SESSION_AUTH_REQUIRED` (403) — session was
+              anonymously initiated; the three resume endpoints
+              require authentication. The `8LABloaz` follow-up will
+              flip `/initiate` to also require auth.
+            - `FILE_TOO_LARGE_FOR_MULTIPART` (422) — assembled object
+              would exceed the S3 multipart capacity cap. Pre-S3
+              server-side capacity gate; distinct from tier-quota
+              rejections (`upload_size_exceeds_tier`).
         message:
           type: string
           description: |
@@ -3056,6 +3570,62 @@ components:
       additionalProperties:
         $ref: '#/components/schemas/PerValueAvailabilityEntry'
 
+    PerRoleCardinality:
+      type: object
+      description: |
+        Map of role-name → `PerRoleCardinalityEntry`. Attached to
+        a role-based multi-input operation's `per_role_cardinality`
+        field to declare the required and maximum input count per
+        role. **Cardinality overlay, not availability overlay** —
+        sits alongside `PerValueAvailability` / `PerMimeAvailability`
+        structurally but expresses a different concern.
+
+        Keys MUST be a subset of the `JobInputRole` enum
+        (CI-checked by `scripts/check-per-role-cardinality.py`).
+        The script additionally enforces arithmetic-consistency:
+        `sum(role.min) == OperationSchemaDefinition.min_inputs`
+        and `sum(role.max) == OperationSchemaDefinition.max_inputs`
+        — this is the load-bearing invariant that makes the
+        primitive useful.
+
+        Absence of `per_role_cardinality` on a role-based op keeps
+        the current prose-only semantics (image_watermark /
+        audio_overlay / custom_luma encode their role rules in
+        prose at `JobInputRole`'s description today; migration to
+        predicate form is per-op follow-up work).
+
+        Per ticket [`SlluxMBN`](https://trello.com/c/SlluxMBN) /
+        ADR-0015. Consumed by `OperationInputRoleValidator` in
+        `compression_api` (rule table becomes data-driven) and by
+        SDK generators when emitting typed role-binding helpers.
+      additionalProperties:
+        $ref: '#/components/schemas/PerRoleCardinalityEntry'
+
+    PerRoleCardinalityEntry:
+      type: object
+      description: |
+        Per-role cardinality entry. `min: 0` makes the role optional.
+        `max: 1` is the most common upper bound (one base, one
+        overlay); future role-based ops may declare higher maxima
+        (e.g. multi-overlay video composites). Both fields default to
+        `1` when absent on a role key — but consumers SHOULD treat
+        absence of either field as a contract bug surfaced by
+        `scripts/check-per-role-cardinality.py` rather than silently
+        defaulting.
+      required:
+        - min
+        - max
+      properties:
+        min:
+          type: integer
+          minimum: 0
+          description: Minimum input count for this role (0 = optional).
+        max:
+          type: integer
+          minimum: 1
+          description: |
+            Maximum input count for this role. MUST be >= `min`.
+
     # ============================================
     # EXTERNAL SOURCES + DESTINATIONS
     # ============================================
@@ -4274,8 +4844,12 @@ components:
         rejection.
 
         The 422 response is delivered alongside `ValidationErrorEnvelope`
-        via `oneOf + discriminator` on `error_type` — see the 422
-        response on `POST /api/workflows`.
+        and `ProcessingClassExceedsBandResponse` via a naked `oneOf`
+        (duck-typed on required-field shape — `details` vs `error_type`
+        value: `feature_not_available` vs `processing_class_exceeds_band`).
+        No discriminator object is used because `ValidationErrorEnvelope`
+        has no `error_type` field. See the 422 response on
+        `POST /api/workflows`.
       allOf:
         - $ref: '#/components/schemas/ErrorEnvelope'
         - type: object
@@ -4299,31 +4873,278 @@ components:
               items:
                 $ref: '#/components/schemas/FeatureViolation'
 
-    FeatureTierRestrictedResponse:
+    ProbePendingResponse:
       description: |
-        403 response body when a workflow references one or more features
-        gated by a higher subscription tier than the caller has.
-
-        Distinct from `TierRestrictionResponse` (also 403): this envelope
-        is per-feature granularity (operation / mime_group / option /
-        per_value); `TierRestrictionResponse` is request-level (file size
-        or MIME). The two envelopes are discriminated by `error_type` at
-        the response `oneOf` level.
+        422 response on `POST /api/workflows` when the probe-pending
+        gate (API `av1J0rEF`, shipped behind a default-OFF feature flag)
+        is enabled and a job references an upload whose server-side
+        probe has not yet completed at workflow-create time. Rather than
+        silently routing the job as `short_form` (which hard-fails long
+        video clips), the server rejects with this envelope so the
+        client can recover deterministically.
+
+        **Recovery contract.** Poll `POST /api/uploads/{id}/probe` for
+        the pending upload until its `probe_status` is terminal
+        (`ok` → re-`POST /api/workflows` the same request; `corrupt` /
+        `unsupported_codec` → surface the probe error, do not retry).
+        The `Retry-After` response header (when present) carries the
+        suggested delay in seconds before the next poll/retry.
+
+        Delivered alongside `ValidationErrorEnvelope`,
+        `FeatureNotAvailableResponse`, and
+        `ProcessingClassExceedsBandResponse` via the naked `oneOf` on
+        the 422 response — duck-typed on required-field shape: this
+        branch is the only one carrying `error_type: probe_pending`
+        and it has neither `details` (ValidationErrorEnvelope) nor
+        `violations` (the other two typed envelopes), so it matches
+        exactly one branch.
       allOf:
         - $ref: '#/components/schemas/ErrorEnvelope'
         - type: object
           required:
             - error_type
-            - violations
+            - job_ref
           properties:
             error_type:
               type: string
               enum:
-                - feature_tier_restricted
-              description: Discriminator for the 403 oneOf. Always `feature_tier_restricted`.
-            violations:
-              type: array
-              minItems: 1
+                - probe_pending
+              description: Discriminator for the 422 oneOf. Always `probe_pending`.
+            job_ref:
+              type: string
+              description: |
+                Workflow-local identifier of the job whose upload-probe
+                has not landed — `JobDefinition.id` if the caller
+                supplied one, else the auto-generated `job_N` token.
+                Mirrors `ProcessingClassBandViolation.job_ref`; NOT
+                `format: uuid` because workflow-create rejects fire
+                before server-side UUIDs are assigned.
+              example: "job_0"
+
+    ProcessingClassRejectReason:
+      type: string
+      description: |
+        Why a job cannot be classified — input size/duration exceeds
+        the `long_form` (or `long_form_re_encode`) ceiling under the
+        caller's effective per-tier caps (per
+        [ADR-0011](../docs/decisions/0011-per-tier-processing-class-constraints.md)
+        `per_tier_constraints`). Distinct from `ProcessingClassReason`
+        (which describes WHY a job got its assigned class — success-
+        path advisory).
+
+        Reasons are split by the violated constraint key on the
+        processing-class block (per `schemas/FORMAT.md`
+        §"`processing_class:` block"):
+
+        - `input_size_exceeds_long_form` /
+          `input_duration_exceeds_long_form`: a **single input**
+          exceeds the per-input ceiling (`max_input_size_bytes` /
+          `max_input_duration`). Applies to single-input operations
+          (compress, convert, thumbnail, text_watermark,
+          audio_watermark) AND per-input checks on multi-input
+          operations with per-input caps (image_watermark,
+          custom_luma, audio_overlay).
+        - `combined_size_exceeds_long_form` /
+          `combined_duration_exceeds_long_form`: the **summed** inputs
+          exceed the multi-input combined ceiling
+          (`max_total_input_size_bytes` / `max_total_duration`).
+          Applies to operations whose `processing_class.<class>.
+          constraints` carries `max_total_*` — merge today.
+      enum:
+        - input_size_exceeds_long_form
+        - input_duration_exceeds_long_form
+        - combined_size_exceeds_long_form
+        - combined_duration_exceeds_long_form
+
+    ProcessingClassBandViolation:
+      type: object
+      description: |
+        One band-ceiling overflow on a workflow-create reject. Carries
+        the I26 localisation quad on the violation (mirrors
+        `FeatureViolation`); envelope-level localisation rides via
+        `allOf [ErrorEnvelope]` on `ProcessingClassExceedsBandResponse`.
+
+        `job_ref`, `actual`, `ceiling`, `operation`, and
+        `processing_class` are REQUIRED — the server always knows them
+        at reject time and consumers rely on them to (a) correlate
+        fail-all violations back to the offending job in multi-job
+        workflows and (b) render "X exceeded by Y" without re-deriving
+        caps from the per-tier overlay.
+      required:
+        - reason
+        - job_ref
+        - operation
+        - processing_class
+        - actual
+        - ceiling
+      properties:
+        reason:
+          $ref: '#/components/schemas/ProcessingClassRejectReason'
+        job_ref:
+          type: string
+          description: |
+            Workflow-local job identifier — `JobDefinition.id` if the
+            caller supplied one, otherwise the auto-generated `job_N`
+            positional token assigned by the server during request
+            validation (e.g. `job_0`, `job_1`). Workflow-create rejects
+            fire BEFORE persisted server UUIDs are assigned; `job_ref`
+            is the request-local handle that survives across reject
+            and (later) success paths. Per `JobDefinition.id` pattern
+            + auto-generation rules.
+          example: "stitched"
+        input_index:
+          type: integer
+          minimum: 0
+          description: |
+            0-based ordinal into `JobDefinition.inputs[]` identifying
+            the specific input that violated the per-input ceiling.
+            Set ONLY on `input_*_exceeds_long_form` reasons for
+            multi-input operations; omitted on single-input
+            operations (no positional ambiguity) and on
+            `combined_*_exceeds_long_form` reasons (whole-job
+            violation across all inputs).
+        operation:
+          $ref: '#/components/schemas/OperationType'
+          description: Operation type that triggered the band-ceiling reject.
+        processing_class:
+          $ref: '#/components/schemas/ProcessingClass'
+          description: |
+            The class whose ceiling was exceeded — typically `long_form`
+            or `long_form_re_encode`.
+        actual:
+          type: integer
+          minimum: 0
+          description: |
+            Observed value. Bytes for `*_size_exceeds_long_form`
+            reasons; whole seconds for `*_duration_exceeds_long_form`
+            reasons.
+        ceiling:
+          type: integer
+          minimum: 0
+          description: |
+            Effective per-tier ceiling for this caller (same units as
+            `actual`). The binding cap after `per_tier_constraints`
+            overlay; lets consumers render "X exceeded by Y" without
+            re-deriving caps from the per-tier overlay.
+        required_tier:
+          description: |
+            Optional. When a HIGHER tier exists whose
+            `per_tier_constraints` would accommodate this request, the
+            server SHOULD set `required_tier` to that tier — consumers
+            can offer an upgrade nudge. `null` (or omitted) means
+            **no tier resolves** the overflow (e.g. enterprise already
+            hits the 120 GB hard ceiling per
+            [ADR-0011](../docs/decisions/0011-per-tier-processing-class-constraints.md)
+            D1–D4).
+
+            Distinct from `TierRestrictionResponse.required_tier`
+            which names a tier whose request-level upload cap
+            satisfies the request — this field names a tier whose
+            long-form processing-class cap satisfies it. Per
+            [ADR-0012](../docs/decisions/0012-processing-class-band-reject-envelope.md)
+            for the band-vs-tier split.
+          oneOf:
+            - $ref: '#/components/schemas/UserTier'
+            - type: 'null'
+        documentation_url:
+          type: string
+          format: uri
+          description: Optional link to processing-class documentation.
+        message_key:
+          type: string
+          description: Per I26. See `ErrorEnvelope.message_key`.
+        message:
+          type: string
+          description: |
+            Per I26. Human-readable, localised per `Accept-Language`.
+            Never parse for control flow.
+        locale:
+          type: string
+          description: BCP 47 locale tag. See `ErrorEnvelope.locale`.
+        message_params:
+          type: object
+          additionalProperties: true
+          description: |
+            Per I26. Optional interpolation values for the localised
+            `message`. Excludes cost numbers.
+
+    ProcessingClassExceedsBandResponse:
+      description: |
+        422 response body when one or more jobs cannot be classified
+        because input size/duration exceeds the `long_form` (or
+        `long_form_re_encode`) ceiling under the caller's effective
+        per-tier caps (per
+        [ADR-0011](../docs/decisions/0011-per-tier-processing-class-constraints.md)
+        `per_tier_constraints`).
+
+        Distinct from `TierRestrictionResponse` (403, request-level
+        tier-quota — resolvable by upload-size reduction or quota
+        change) and from `FeatureNotAvailableResponse` (422, feature
+        tagged not-yet-shipped — resolvable by waiting for the
+        availability flip). Resolution path is per-violation:
+        `required_tier` on each `ProcessingClassBandViolation` names
+        the tier (if any) whose `per_tier_constraints` would
+        accommodate the request; `null` means terminal (e.g. enterprise
+        already at the 120 GB hard ceiling).
+
+        Per
+        [ADR-0012](../docs/decisions/0012-processing-class-band-reject-envelope.md)
+        for the band-vs-tier rationale and routing rule (why this
+        envelope is 422, not an extension of `TierRestrictionResponse`
+        on 403).
+
+        Delivered on `POST /api/workflows` 422 in a naked `oneOf`
+        alongside `ValidationErrorEnvelope` and
+        `FeatureNotAvailableResponse` — branches distinguished by
+        required-field shape (`details` vs `error_type` value).
+      allOf:
+        - $ref: '#/components/schemas/ErrorEnvelope'
+        - type: object
+          required:
+            - error_type
+            - violations
+          properties:
+            error_type:
+              type: string
+              enum:
+                - processing_class_exceeds_band
+              description: Discriminator for the 422 oneOf. Always `processing_class_exceeds_band` for this envelope.
+            violations:
+              type: array
+              minItems: 1
+              description: |
+                One entry per offending job/input. Per ADR-0001 §F6
+                batched-violations rule, multiple violations in a
+                single request are ALL returned here (fail-all, not
+                fail-fast).
+              items:
+                $ref: '#/components/schemas/ProcessingClassBandViolation'
+
+    FeatureTierRestrictedResponse:
+      description: |
+        403 response body when a workflow references one or more features
+        gated by a higher subscription tier than the caller has.
+
+        Distinct from `TierRestrictionResponse` (also 403): this envelope
+        is per-feature granularity (operation / mime_group / option /
+        per_value); `TierRestrictionResponse` is request-level (file size
+        or MIME). The two envelopes are discriminated by `error_type` at
+        the response `oneOf` level.
+      allOf:
+        - $ref: '#/components/schemas/ErrorEnvelope'
+        - type: object
+          required:
+            - error_type
+            - violations
+          properties:
+            error_type:
+              type: string
+              enum:
+                - feature_tier_restricted
+              description: Discriminator for the 403 oneOf. Always `feature_tier_restricted`.
+            violations:
+              type: array
+              minItems: 1
               description: |
                 One entry per tier-gated feature. Each `FeatureViolation`
                 MUST set `required_tier` to the tier that would satisfy
@@ -4509,7 +5330,7 @@ components:
         - thumbnail_office: Office document (DOCX/XLSX/PPTX/ODT/ODS/ODP)
           thumbnail sub-type. Backed by a dedicated LibreOffice Lambda.
           Not yet emitted.
-        - image_watermark: Image overlay (file or external_source) onto a base media asset. Multi-input (Path B with role: base + overlay). Stable for image bases (jpeg/png/webp); animated GIF and video bases are advertised as `planned` via parallel mime_groups (`image_gif`, `video`) — dispatch returns `feature_not_available` (422) until Lambda support ships. Per ADR-0004 + I4-CONS + I5 (Trello AKZiOXnd).
+        - image_watermark: Image overlay (file or external_source) onto a base IMAGE asset. Multi-input (Path B with role: base + overlay). Stable for static-image bases (jpeg/png/webp); animated GIF is advertised as `planned` via the `image_gif` mime_group — dispatch returns `feature_not_available` (422) until Lambda support ships. Video bases are NOT supported by image_watermark — use the dedicated `video_watermark` operation per ADR-0013. Per ADR-0004 + I4-CONS + I5 (Trello AKZiOXnd).
         - text_watermark: Text overlay rendered onto an image (Liberation Sans). Single-input. Per ADR-0004 + I4-CONS.
         - merge: Concatenate/combine multiple files into one (images, video, audio). Multi-input. Image inputs merge into animated GIF or slideshow video; image collage/grid and PDF concatenation are not supported by the V1 Lambda.
         - archive: Bundle files into ZIP/tar.gz (all types). Multi-input.
@@ -4517,6 +5338,10 @@ components:
         - custom_luma: Apply a caller-uploaded luma matte to a base video for a custom luma-matte transition effect. Multi-input (`role: base` + `role: transition_mask`). `availability: planned` + `required_tier: pro`; dispatch returns `feature_not_available` (422) until Lambda ships. Distinct from FFmpeg `xfade=custom` (which is an expression, not an operation). Per ticket I29 (Trello EPUE5Vs1).
         - audio_overlay: Mix a secondary audio asset over a primary audio or video base (DJ tags, podcast intros/outros, station IDs, jingles). Multi-input (`role: base` + `role: overlay`). `availability: planned`; dispatch returns `feature_not_available` (422) until Lambda ships. **NOT** the same as `audio_watermark` — that operation is steganographic (imperceptible identifier embedded for ownership tracking), tracked separately by I20. Per ticket I19 (Trello Xr3Z4GBF).
         - audio_watermark: Embed a steganographic forensic watermark into an audio asset (or a video's audio track) — Cinavia / Resemble PerTh territory. Single-input. `availability: planned` + `required_tier: enterprise`; dispatch returns `feature_not_available` (422) until Lambda ships. Pairs with `POST /api/audio-watermark/decode` for own-watermarks-only extraction. Per ticket I20 (Trello omiCq7Vn).
+        - audio_to_video: Produce a video from an audio input plus an OPTIONAL still image overlay. Multi-input role-based with the first OPTIONAL role on the contract (`role: base` audio required, `role: overlay` image 0..1 — see `per_role_cardinality`). When overlay is omitted, the video uses a solid background colour. `availability: planned`; dispatch returns `feature_not_available` (422) until Lambda ships. Per ticket [`SlluxMBN`](https://trello.com/c/SlluxMBN) + ADR-0015 (introduces `per_role_cardinality` vocab).
+        - video_watermark: Apply an image overlay onto a base video via FFmpeg's `overlay` filter. Multi-input role-based (`role: base` video + `role: overlay` image, exactly one of each per `per_role_cardinality`). Re-encode required; audio stream-copy passthrough. Distinct from `image_watermark` (pure-Rust/image-only). `availability: planned`; dispatch returns `feature_not_available` (422) until Lambda ships. Per ticket [`4NrRPCgh`](https://trello.com/c/4NrRPCgh) + ADR-0013.
+        - video_text_watermark: Render a text overlay onto a base video via FFmpeg's `drawtext` filter. Single-input — text and styling in options. Same `watermark_mode` (single/tiled), anchor + margin vocab as `text_watermark`. Re-encode required; audio stream-copy passthrough. `availability: planned`; dispatch returns `feature_not_available` (422) until Lambda ships. Per ticket [`4NrRPCgh`](https://trello.com/c/4NrRPCgh) + ADR-0013.
+        - split: Fan one input file into N outputs across GIF / PDF / audio / video MIME families. Single-input per-mime-group catalog (mirrors merge/convert): GIF uses `frame_range` (REQUIRED) + `output_format`; PDF uses `page_range` OR `page_groups` (mutually exclusive); audio + video use a `mode` discriminator (interval/count/cut_points) + numeric-seconds wire format + `precision` flag (fast/exact). 200-output hard cap per ADR-0009 §D5 with per-mode preflight math; output naming `output-001..output-200`. Long-form video routes to a separate `split-video-fargate` worker via `processing_class`. `availability: planned`; dispatch returns `feature_not_available` (422) until Lambda ships. Per ticket [`vKI0CFDu`](https://trello.com/c/vKI0CFDu) + ADR-0014.
 
         Both the legacy `thumbnail` value and the four sub-type values
         are valid routing targets today during the thumbnail migration
@@ -4541,6 +5366,10 @@ components:
         - custom_luma
         - audio_overlay
         - audio_watermark
+        - audio_to_video
+        - video_watermark
+        - video_text_watermark
+        - split
 
     OperationInputModel:
       type: string
@@ -4548,8 +5377,9 @@ components:
         Whether the operation accepts a single file or multiple files:
         - single: One input file (compress, thumbnail, thumbnail_image,
           thumbnail_video, thumbnail_document, thumbnail_office,
-          text_watermark, convert, audio_watermark)
-        - multi: Multiple input files (merge, archive, image_watermark, custom_luma, audio_overlay)
+          text_watermark, convert, audio_watermark,
+          video_text_watermark, split)
+        - multi: Multiple input files (merge, archive, image_watermark, custom_luma, audio_overlay, audio_to_video, video_watermark). audio_to_video is the first role-based op with an OPTIONAL role (min_inputs=1, max_inputs=2 — see `per_role_cardinality`); video_watermark mirrors `image_watermark`'s 2-required pattern on video bases.
       enum:
         - single
         - multi
@@ -4634,11 +5464,18 @@ components:
         multipart_chunk_size:
           type: integer
           format: int64
-          const: 5242880
+          const: 16777216
           description: |
             Recommended chunk size in bytes for multipart upload
-            chunks (5 MiB / 5,242,880 bytes — 1024-based). Matches
-            the existing TS SDK default. The server's
+            chunks (16 MiB / 16,777,216 bytes — 1024-based). Raised
+            from 5 MiB by CON-1 (ADR-0011): S3 caps a multipart
+            upload at 10,000 parts, and the Enterprise envelope is a
+            120 GB hard ceiling. At 16 MiB a 120 GiB object needs
+            7,680 parts (≤ 10,000, inside AWS's 16–64 MB recommended
+            band); 5 MiB would need 24,576 and 10 MiB 12,288 — both
+            exceed the S3 limit. **Wire-incompatible change** — SDKs
+            pin this as a compile-time constant, so CON-1 and SDK-2
+            ship as a non-independently-mergeable pair. The server's
             `MultipartInitiateResponse` returns a
             `recommended_chunk_size` per file based on first-chunk
             throughput; SDKs SHOULD prefer that runtime value when
@@ -4807,27 +5644,43 @@ components:
         total_parts:
           type: integer
           minimum: 2
-          maximum: 500
+          maximum: 10000
           description: |
             Total number of parts. The client slices the remaining file into
             exactly (total_parts - 1) chunks using recommended_chunk_size.
-            The last chunk may be smaller.
+            The last chunk may be smaller. Maximum raised 500 → 10,000 by
+            CON-1 (ADR-0011) — 10,000 is the S3 multipart hard part limit;
+            500 contract-capped uploads at ≈ 50 GB, below the 120 GB
+            Enterprise envelope.
           example: 5
         recommended_chunk_size:
           type: integer
-          minimum: 5242880
+          minimum: 16777216
           maximum: 104857600
           description: |
             Chunk size in bytes for remaining parts. Calculated from first chunk
-            throughput * 5s target, clamped to 5MB-100MB. The last chunk may be
-            smaller than 5MB.
-          example: 10485760
+            throughput * 5s target, clamped to 16 MiB–100 MiB. The last chunk
+            may be smaller than 16 MiB. Minimum raised 5 MiB → 16 MiB by CON-1
+            (ADR-0011) so the runtime value never falls below the
+            `UploadThresholds.multipart_chunk_size` constant SDKs fall back to
+            (the S3 10,000-part limit at the 120 GB Enterprise ceiling).
+          example: 16777216
         presigned_urls:
           type: array
           description: |
             Pre-signed S3 PUT URLs for parts 2 through total_parts.
             Each URL accepts a PUT request with raw chunk bytes as body.
             Collect the ETag from each S3 response for the complete request.
+
+            NOTE (CON-1/ADR-0011): with `total_parts` now bounded by the
+            S3 hard limit (10,000), a maximal Enterprise upload implies a
+            large URL set. The server is NOT required to return every URL
+            in one synchronous response — bounded-batch / paginated URL
+            delivery and resumable re-fetch are owned by API-2
+            (durable upload session) and SDK-3 (presigned batching +
+            paginated ListParts). Consumers MUST NOT assume a single
+            initiate response carries all `total_parts - 1` URLs at the
+            high end of the range; treat this array as the first batch.
           items:
             $ref: '#/components/schemas/PresignedUrlPart'
         constraints_applied:
@@ -4940,6 +5793,249 @@ components:
         data:
           $ref: '#/components/schemas/MultipartCompleteResponse'
 
+    # ============================================
+    # MULTIPART SESSION RESUME SCHEMAS (HxUmVr3Y)
+    # ============================================
+
+    MultipartPartListing:
+      type: object
+      description: |
+        One uploaded part as reported by the S3 multipart ListParts
+        API. The /status response carries an array of these. Mirrors
+        the S3 wire shape verbatim so the response is a 1:1 passthrough
+        with no translation layer.
+      required:
+        - part_number
+        - etag
+        - size_bytes
+        - last_modified
+      properties:
+        part_number:
+          type: integer
+          minimum: 1
+          maximum: 10000
+          description: |
+            S3 multipart part number. Part 1 is always present in a
+            healthy session (uploaded synchronously at `/initiate`);
+            parts 2–N follow.
+        etag:
+          type: string
+          description: |
+            ETag returned by S3 for the part. Quoted MD5 hex by default;
+            preserve quotes verbatim as S3 emits them.
+          example: '"d8e8fca2dc0f896fd7cb4cb0031ba249"'
+        size_bytes:
+          type: integer
+          format: int64
+          minimum: 0
+          description: Part size in bytes (as reported by S3).
+        last_modified:
+          type: string
+          format: date-time
+          description: ISO-8601 timestamp from S3 ListParts `LastModified`.
+
+    MultipartStatusResponse:
+      type: object
+      description: |
+        Resume-state snapshot for an in-flight multipart session. The
+        `data` payload on `GET /api/uploads/multipart/{uploadId}/status`.
+      required:
+        - upload_id
+        - multipart_upload_id
+        - cloud_key
+        - total_parts
+        - uploaded_parts
+        - next_part_number_marker
+        - is_truncated
+        - manifest_expires_at
+        - recommended_chunk_size
+      properties:
+        upload_id:
+          $ref: '#/components/schemas/UuidV7'
+          description: Session identifier (matches the path `uploadId` and the initiate response `upload_id`).
+        multipart_upload_id:
+          type: string
+          description: |
+            S3 multipart upload identifier returned by `CreateMultipartUpload`.
+            Opaque to API consumers; emitted for diagnostic visibility
+            (SDK logs / dashboards correlating against AWS CloudTrail).
+        cloud_key:
+          type: string
+          description: |
+            S3 object key under which the assembled object will be
+            stored on `multipart/complete`. Opaque to consumers.
+        total_parts:
+          type: integer
+          minimum: 2
+          maximum: 10000
+          description: |
+            Total number of parts the client must upload to complete
+            the session. Same value as `MultipartInitiateResponse.total_parts`
+            and stable for the lifetime of the session.
+        uploaded_parts:
+          type: array
+          description: |
+            Parts already present in S3 for this session, as reported
+            by S3 ListParts at request time. May be empty (no parts
+            uploaded yet) or partial (resume mid-upload). Order is the
+            S3-native part-number ascending.
+          items:
+            $ref: '#/components/schemas/MultipartPartListing'
+        next_part_number_marker:
+          description: |
+            S3 ListParts cursor — pass this as the next request's
+            `cursor` query parameter to fetch the following page.
+            `null` on the final page (or when `is_truncated: false`).
+            Mirrors the S3 `NextPartNumberMarker` field verbatim.
+
+            Upper bound matches the request `cursor` query parameter
+            range (`0..9999`) so SDKs can round-trip the marker
+            verbatim — `total_parts` caps at 10,000 and the cursor
+            semantically means "list after part N", so the highest
+            reachable marker is 9,999 (any cursor of 10,000 would
+            return an empty page).
+          oneOf:
+            - type: integer
+              minimum: 0
+              maximum: 9999
+            - type: 'null'
+        is_truncated:
+          type: boolean
+          description: |
+            `true` when more pages remain; `false` on the final page.
+            Mirrors the S3 ListParts `IsTruncated` field verbatim.
+        manifest_expires_at:
+          description: |
+            ISO-8601 expiry timestamp of the session manifest. `null`
+            when the TTL has lapsed or was not initialised — in that
+            case, callers SHOULD invoke
+            `POST /api/uploads/multipart/{uploadId}/keepalive` to
+            re-establish a 48 h window before re-presigning. The
+            manifest TTL is decoupled from individual presigned-URL
+            TTLs.
+          oneOf:
+            - type: string
+              format: date-time
+            - type: 'null'
+        recommended_chunk_size:
+          type: integer
+          minimum: 16777216
+          maximum: 104857600
+          description: |
+            Chunk size (bytes) the server recommends for any remaining
+            parts in this session — identical to
+            `MultipartInitiateResponse.recommended_chunk_size` (16 MiB
+            floor / 100 MiB ceiling per CON-1 / ADR-0011). Returned on
+            every page so the client doesn't need to retain the
+            initiate response across a resume.
+
+    MultipartStatusSuccessEnvelope:
+      type: object
+      required:
+        - success
+        - data
+      properties:
+        success:
+          type: boolean
+          enum: [true]
+        data:
+          $ref: '#/components/schemas/MultipartStatusResponse'
+
+    MultipartPresignRequest:
+      type: object
+      description: |
+        Caller-supplied subset of part numbers to re-presign. Request
+        body for `POST /api/uploads/multipart/{uploadId}/presign`.
+      required:
+        - part_numbers
+      properties:
+        part_numbers:
+          type: array
+          minItems: 1
+          maxItems: 100
+          uniqueItems: true
+          description: |
+            Part numbers to re-presign. Each entry MUST satisfy
+            `2 ≤ n ≤ total_parts` from the initiate response —
+            **Part 1 is rejected** because the manifest stores its
+            ETag from `/initiate` and re-presigning would break the
+            eventual `multipart/complete` call. Cap of 100 entries
+            per request; SDKs paginate larger resume sets across
+            multiple `/presign` calls.
+          items:
+            type: integer
+            minimum: 2
+            maximum: 10000
+
+    MultipartPresignResponse:
+      type: object
+      description: |
+        Pre-signed URLs for the parts requested via
+        `MultipartPresignRequest.part_numbers`. The `data` payload on
+        `POST /api/uploads/multipart/{uploadId}/presign`.
+      required:
+        - upload_id
+        - presigned_urls
+      properties:
+        upload_id:
+          $ref: '#/components/schemas/UuidV7'
+          description: Session identifier (echoes the path `uploadId`).
+        presigned_urls:
+          type: array
+          minItems: 1
+          maxItems: 100
+          description: |
+            One pre-signed PUT URL per requested part number, in the
+            same order as `MultipartPresignRequest.part_numbers`. Each
+            item carries `part_number` + `url` + `expires_at` —
+            same shape as `MultipartInitiateResponse.presigned_urls[]`.
+          items:
+            $ref: '#/components/schemas/PresignedUrlPart'
+
+    MultipartPresignSuccessEnvelope:
+      type: object
+      required:
+        - success
+        - data
+      properties:
+        success:
+          type: boolean
+          enum: [true]
+        data:
+          $ref: '#/components/schemas/MultipartPresignResponse'
+
+    MultipartKeepaliveResponse:
+      type: object
+      description: |
+        Refreshed manifest TTL for an in-flight multipart session. The
+        `data` payload on `POST /api/uploads/multipart/{uploadId}/keepalive`.
+      required:
+        - upload_id
+        - manifest_expires_at
+      properties:
+        upload_id:
+          $ref: '#/components/schemas/UuidV7'
+          description: Session identifier (echoes the path `uploadId`).
+        manifest_expires_at:
+          type: string
+          format: date-time
+          description: |
+            ISO-8601 expiry timestamp of the refreshed manifest. Always
+            non-null on a successful 200 response — keepalive
+            unconditionally extends the TTL to 48 h ahead of `now`.
+
+    MultipartKeepaliveSuccessEnvelope:
+      type: object
+      required:
+        - success
+        - data
+      properties:
+        success:
+          type: boolean
+          enum: [true]
+        data:
+          $ref: '#/components/schemas/MultipartKeepaliveResponse'
+
     # ============================================
     # METADATA SCHEMAS
     # ============================================
@@ -5231,10 +6327,21 @@ components:
           type: array
           description: |
             Multi-input list for `merge`, `archive`, `image_watermark`,
-            `custom_luma`, and `audio_overlay`. Each entry is a
-            `JobInputV2` with its own `WorkflowSource`. Mutually
-            exclusive with `source`.
-          minItems: 2
+            `custom_luma`, `audio_overlay`, and `audio_to_video`. Each
+            entry is a `JobInputV2` with its own `WorkflowSource`.
+            Mutually exclusive with `source` — the V2 shape boundary
+            stays `source` (single-input) XOR `inputs[]` (multi-input
+            role-based) per ADR-0004 / I12.
+
+            **Minimum input count = sum of role minima** declared in
+            the operation's `per_role_cardinality` (per ticket
+            [`SlluxMBN`](https://trello.com/c/SlluxMBN) ADR-0015).
+            `audio_to_video` requires 1 input (`base` audio; `overlay`
+            optional, 0..1); all other role-based ops require 2+ today.
+            The schema floor here is `minItems: 1` to admit the
+            audio_to_video case; per-operation gates enforce the
+            actual count via `OperationSchemaDefinition.min_inputs`.
+          minItems: 1
           items:
             $ref: '#/components/schemas/JobInputV2'
         operations:
@@ -5246,8 +6353,8 @@ components:
 
             Multi-input jobs (with `inputs[]`) must have exactly one
             operation, and it must be a multi-input type (`merge`,
-            `archive`, `image_watermark`, `custom_luma`, or
-            `audio_overlay`).
+            `archive`, `image_watermark`, `custom_luma`,
+            `audio_overlay`, or `audio_to_video`).
           items:
             $ref: '#/components/schemas/OperationDefinition'
         deliver:
@@ -5278,7 +6385,7 @@ components:
                 items:
                   properties:
                     type:
-                      enum: [merge, archive, image_watermark, custom_luma, audio_overlay]
+                      enum: [merge, archive, image_watermark, custom_luma, audio_overlay, audio_to_video, video_watermark]
             required: [operations]
             description: |
               Multi-input jobs must have exactly one operation, and it
@@ -5325,6 +6432,21 @@ components:
               `overlay` value already declared for `image_watermark`
               — semantics differ by operation type, but the same
               role label keeps the enum compact.
+            - `audio_to_video`: REQUIRED `base` (audio source); OPTIONAL
+              `overlay` (still image, 0..1). FIRST role-based op with
+              an OPTIONAL role — see `per_role_cardinality` for the
+              machine-readable cardinality declaration (per ticket
+              [`SlluxMBN`](https://trello.com/c/SlluxMBN) /
+              ADR-0015). Reuses `base` + `overlay` role values
+              already declared for `image_watermark` / `audio_overlay`.
+            - `video_watermark`: REQUIRED; values `base` (the source
+              video) or `overlay` (the watermark image). Exactly one
+              of each per job — `per_role_cardinality { base: 1/1,
+              overlay: 1/1 }`. First non-introductory adoption of the
+              `per_role_cardinality` vocab (per ticket
+              [`4NrRPCgh`](https://trello.com/c/4NrRPCgh) /
+              ADR-0013). `video_text_watermark` is single-input (no
+              `role` field — text comes from options).
             - `merge` / `archive`: omit (all inputs share the same role).
 
             `text_watermark` is single-input via `JobDefinition.source`
@@ -5956,7 +7078,9 @@ components:
     UploadProbeResponse:
       type: object
       description: |
-        Response body for `POST /api/uploads/{id}/probe` per ticket
+        Payload schema carried on the `data` field of
+        `UploadProbeSuccessEnvelope` returned by
+        `POST /api/uploads/{id}/probe`, per ticket
         [I28 `KbVAnGCm`](https://trello.com/c/KbVAnGCm). Designed
         so SDKs can compile a `client.preflight_clips([file_ids])`
         helper into N parallel probes and aggregate by
@@ -5977,6 +7101,29 @@ components:
         processing_class_pre_assignment:
           $ref: '#/components/schemas/UploadProbeProcessingClass'
 
+    UploadProbeSuccessEnvelope:
+      type: object
+      description: |
+        Success envelope wrapping `UploadProbeResponse` on
+        `POST /api/uploads/{id}/probe` 200 responses, per ticket
+        [`9XlWEnZU`](https://trello.com/c/9XlWEnZU). Mirrors the
+        spec-wide `*SuccessEnvelope` convention (`{success: true,
+        data: <payload>}`) used by every other 2xx endpoint; the
+        probe endpoint shipped during the v2.3 declared-but-pending
+        phase missing the wrap. The API
+        (`ApiResponseTrait::respondSuccess` in `compression_api`)
+        already emits this shape — the envelope brings the contract
+        in line with the wire.
+      required:
+        - success
+        - data
+      properties:
+        success:
+          type: boolean
+          enum: [true]
+        data:
+          $ref: '#/components/schemas/UploadProbeResponse'
+
     # ============================================
     # UPLOAD-SIDE GATING (per ticket I15-CONS F8.1)
     # ============================================
@@ -6293,6 +7440,21 @@ components:
           description: Progress percentage (0-100). Present when in_progress or completed.
         result:
           $ref: '#/components/schemas/OperationResult'
+        error_code:
+          type: string
+          description: |
+            Machine-readable failure code. Present when `status` is `failed`;
+            absent otherwise. Mirrors `SseOperationFailedData.error_code` — the
+            same diagnostic the SSE `operation.failed` event carries, surfaced
+            here for polling consumers. Plain string (consumers duck-type on
+            it), e.g. `output_too_large`.
+          example: "output_too_large"
+        error_message:
+          type: string
+          description: |
+            Human-readable failure detail. Present when `status` is `failed`;
+            absent otherwise. Mirrors `SseOperationFailedData.error_message`.
+          example: "output_too_large: Output (12156489 bytes) is not smaller than input (6187609 bytes)"
 
     OperationResult:
       type: object
@@ -6370,12 +7532,37 @@ components:
 
     OperationDownload:
       type: object
+      description: |
+        A single deliverable output file for an operation. For multi-output
+        fan-out (e.g. convert PDF->image emits one file per page), each entry
+        carries an indexing field. This is the REST projection of the same
+        indexing model the AsyncAPI `OperationResultOutputEntry` defines per
+        ADR-0009 §D2 — `page_index` for PDF-page outputs, `position` for
+        generic ordinals, mutually exclusive within an entry.
       required:
         - operation
         - operation_id
         - filename
         - size_bytes
         - download_url
+      oneOf:
+        - title: PageIndexed
+          description: PDF-page output (convert PDF->image).
+          required: [page_index]
+          not: { required: [position] }
+        - title: PositionIndexed
+          description: Generic ordinal output (frame strip, chapter split).
+          required: [position]
+          not: { required: [page_index] }
+        - title: Unindexed
+          description: |
+            Output without an explicit indexing field — every legacy
+            single-output download. Schema-valid; emitted by all
+            non-fan-out operations.
+          not:
+            anyOf:
+              - required: [page_index]
+              - required: [position]
       properties:
         operation:
           type: string
@@ -6394,6 +7581,26 @@ components:
           type: string
           format: uri
           description: Pre-signed download URL
+        page_index:
+          type: integer
+          minimum: 1
+          description: |
+            1-based page number for PDF-page fan-out outputs (convert
+            PDF->image). Gapless within an operation (an N-page conversion
+            emits `page_index` 1..N). Mutually exclusive with `position`.
+            Absent on non-indexed (single-output) downloads. Mirrors
+            `OperationResultOutputEntry.page_index`. Per ADR-0009 §D2.
+          example: 1
+        position:
+          type: integer
+          minimum: 0
+          description: |
+            0-based ordinal for non-PDF multi-output operations (e.g. frame
+            strip, chapter split). Mutually exclusive with `page_index`.
+            Absent on non-indexed downloads. Forward-looking — not emitted by
+            any current operation; declared for parity with
+            `OperationResultOutputEntry.position`. Per ADR-0009 §D2.
+          example: 0
 
     # ============================================
     # SSE EVENT SCHEMAS
@@ -6508,7 +7715,207 @@ components:
           type: integer
           const: 100
         result:
-          $ref: '#/components/schemas/OperationResult'
+          $ref: '#/components/schemas/SseOperationCompletionResult'
+
+    SseOperationCompletionResult:
+      description: |
+        Result payload carried on the SSE `operation.completed` event
+        (`SseOperationCompletedData.result`). A 2-branch `oneOf` mirroring the
+        single-output vs multi-output completion split of the AsyncAPI
+        `OperationResult` union (per [ADR-0009](../docs/decisions/0009-multi-output-result-envelope.md)),
+        projected into the client-facing (download-URL) shape rather than the
+        S3-wire shape.
+
+        - **Single-output**: `SseSingleOutputCompletion` (allOf wrap of
+          `OperationResult` + a `result_kind: "single"` discriminator field).
+          `download_url` + `size_bytes`, optional `export_key` / `metrics`. Every
+          operation that produces one canonical output.
+        - **Multi-output**: `SseMultiOutputCompletionWithKind` (allOf wrap of
+          `SseMultiOutputCompletion` + a `result_kind: "multi"` discriminator
+          field). `outputs[]` + `total_output_size_bytes`. Used by convert
+          PDF->image and future fan-out operations.
+
+        Failure is **not** a branch here — it is carried by the separate
+        `operation.failed` event (`SseOperationFailedData`), unlike the AsyncAPI
+        `OperationResult` which folds failure into the same union.
+
+        **Branch dispatch via `result_kind` discriminator.** The branches are
+        disambiguated by an explicit `result_kind` field (`"single"` |
+        `"multi"`) that the API SSE emitter populates. The wrapper allOf shape
+        keeps the underlying `OperationResult` and `SseMultiOutputCompletion`
+        schemas unchanged (they continue to be used elsewhere — REST polling,
+        AsyncAPI Lambda→API — without the discriminator). The discriminator
+        approach replaces the v2.15.1 bare-`$ref` design, which dispatched
+        correctly at validation but generated TS deserialization code that
+        checked camelCase property names against snake_case wire payloads —
+        silent data-loss on every single-output completion. The
+        discriminator-based dispatch reads the snake_case wire key directly
+        (`switch (json['result_kind'])`), avoiding the case-mismatch bug
+        entirely.
+      oneOf:
+        - $ref: '#/components/schemas/SseSingleOutputCompletion'
+        - $ref: '#/components/schemas/SseMultiOutputCompletionWithKind'
+      discriminator:
+        propertyName: result_kind
+        mapping:
+          single: '#/components/schemas/SseSingleOutputCompletion'
+          multi: '#/components/schemas/SseMultiOutputCompletionWithKind'
+
+    SseSingleOutputCompletion:
+      description: |
+        Single-output branch of `SseOperationCompletionResult` — wraps
+        `OperationResult` with a `result_kind: "single"` discriminator field
+        so the openapi-generator dispatch can route by wire-format key
+        (`result_kind`) rather than by structural property presence.
+        See `SseOperationCompletionResult` description for the rationale.
+      allOf:
+        - $ref: '#/components/schemas/OperationResult'
+        - type: object
+          required:
+            - result_kind
+          properties:
+            result_kind:
+              type: string
+              enum: [single]
+              description: |
+                Discriminator. Always the literal `"single"` for this branch.
+                Emitted by the API SSE serializer; consumed by
+                `SseOperationCompletionResult` dispatch.
+
+    SseMultiOutputCompletionWithKind:
+      description: |
+        Multi-output branch of `SseOperationCompletionResult` — wraps
+        `SseMultiOutputCompletion` with a `result_kind: "multi"` discriminator
+        field. See `SseOperationCompletionResult` description for the
+        rationale.
+      allOf:
+        - $ref: '#/components/schemas/SseMultiOutputCompletion'
+        - type: object
+          required:
+            - result_kind
+          properties:
+            result_kind:
+              type: string
+              enum: [multi]
+              description: |
+                Discriminator. Always the literal `"multi"` for this branch.
+                Emitted by the API SSE serializer; consumed by
+                `SseOperationCompletionResult` dispatch.
+
+    SseMultiOutputCompletion:
+      type: object
+      description: |
+        Multi-output completion body for the SSE `operation.completed` event.
+        Per-output details plus an aggregate size, mirroring the AsyncAPI
+        `MultiOutputCompletion` branch of `OperationResult` (per
+        [ADR-0009](../docs/decisions/0009-multi-output-result-envelope.md)) in
+        the client-facing (download-URL) projection.
+      required:
+        - outputs
+        - total_output_size_bytes
+      properties:
+        outputs:
+          type: array
+          minItems: 1
+          maxItems: 200
+          description: |
+            Per-output deliverables for a multi-output operation (e.g. convert
+            PDF->image emits one entry per page). Consumers use `outputs.length`
+            for the count — per ADR-0009 §D4 a denormalised `output_count` was
+            deliberately rejected. `maxItems: 200` mirrors the AsyncAPI
+            `OperationResult.outputs` transport bound.
+          items:
+            $ref: '#/components/schemas/SseMultiOutputResultEntry'
+        total_output_size_bytes:
+          type: integer
+          format: int64
+          minimum: 0
+          description: |
+            Aggregate size of all `outputs[]` in bytes. Equals
+            `sum(outputs[].size_bytes)`. Per ADR-0009 §D4 this is denormalised
+            against the per-entry sum; consumers SHOULD trust the per-entry sum
+            if the two disagree (and log a warning).
+          example: 786432
+        metrics:
+          type: object
+          description: Operation-specific performance metrics (aggregate)
+          properties:
+            compression_ratio:
+              type: number
+              format: double
+              description: Ratio of output size to input size (e.g. 0.45 = 55% reduction)
+            duration_ms:
+              type: integer
+              description: Processing time in milliseconds
+
+    SseMultiOutputResultEntry:
+      type: object
+      description: |
+        A single deliverable output file in an SSE multi-output
+        `operation.completed` result (`SseMultiOutputCompletion.outputs[]`).
+        This is the SSE-local, client-facing twin of the AsyncAPI
+        `OperationResultOutputEntry` (which is S3-wire: `output_key`) and is
+        deliberately **decoupled** from the REST `OperationDownload` schema — it
+        carries `download_url` + `size_bytes` and the same `page_index` /
+        `position` indexing model defined per
+        [ADR-0009](../docs/decisions/0009-multi-output-result-envelope.md) §D2
+        (`page_index` for PDF-page outputs, `position` for generic ordinals,
+        mutually exclusive within an entry).
+      required:
+        - download_url
+        - size_bytes
+      oneOf:
+        - title: PageIndexed
+          description: PDF-page output (convert PDF->image).
+          required: [page_index]
+          not: { required: [position] }
+        - title: PositionIndexed
+          description: Generic ordinal output (frame strip, chapter split).
+          required: [position]
+          not: { required: [page_index] }
+        - title: Unindexed
+          description: |
+            Output without an explicit indexing field. Reserved for future
+            operations that index by something other than page/position.
+            Schema-valid but not currently emitted by any operation.
+          not:
+            anyOf:
+              - required: [page_index]
+              - required: [position]
+      properties:
+        download_url:
+          type: string
+          format: uri
+          description: Pre-signed download URL for this individual output file.
+        size_bytes:
+          type: integer
+          format: int64
+          minimum: 0
+          description: |
+            Size of this individual output file in bytes. `minimum: 0` mirrors
+            the AsyncAPI `OperationResultOutputEntry.output_size_bytes` bound and
+            keeps `total_output_size_bytes` (the sum of these) internally
+            consistent.
+        page_index:
+          type: integer
+          minimum: 1
+          description: |
+            1-based page number for PDF-page fan-out outputs (convert
+            PDF->image). Gapless within an operation (an N-page conversion
+            emits `page_index` 1..N). Mutually exclusive with `position`.
+            Absent on non-indexed outputs. Mirrors
+            `OperationResultOutputEntry.page_index`. Per ADR-0009 §D2.
+          example: 1
+        position:
+          type: integer
+          minimum: 0
+          description: |
+            0-based ordinal for non-PDF multi-output operations (e.g. frame
+            strip, chapter split). Mutually exclusive with `page_index`.
+            Absent on non-indexed outputs. Forward-looking — not emitted by any
+            current operation; declared for parity with
+            `OperationResultOutputEntry.position`. Per ADR-0009 §D2.
+          example: 0
 
     SseOperationFailedData:
       type: object
@@ -6755,11 +8162,26 @@ components:
           $ref: '#/components/schemas/OperationInputModel'
         min_inputs:
           type: integer
-          description: Minimum number of inputs (multi-input operations only)
-          minimum: 2
+          description: |
+            Minimum number of inputs (multi-input operations only).
+            `audio_to_video` declares `min_inputs: 1` (first
+            role-based op with an optional role); all other
+            role-based ops declare `min_inputs: 2`. Per
+            `per_role_cardinality` semantics (ADR-0015), this value
+            equals the sum of role-level minima.
+          minimum: 1
         max_inputs:
           type: integer
           description: Maximum number of inputs (multi-input operations only)
+        per_role_cardinality:
+          $ref: '#/components/schemas/PerRoleCardinality'
+          description: |
+            Optional per-role input-count overlay for role-based
+            multi-input operations. Per ticket
+            [`SlluxMBN`](https://trello.com/c/SlluxMBN) / ADR-0015.
+            Absent on operations whose role rules are still encoded
+            in prose only (image_watermark, audio_overlay,
+            custom_luma — per-op migration follow-ups).
         accepts_mixed_types:
           type: boolean
           description: Whether mixed MIME types are allowed (archive only)