@giveitsmaller/contracts 0.4.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.12.0
+  version: 2.15.3
   contact:
     name: API Support
 
@@ -968,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:
@@ -1495,8 +1505,12 @@ paths:
             duck-type against. `FeatureNotAvailableResponse` carries
             `error_type: feature_not_available` + `violations[]`;
             `ProcessingClassExceedsBandResponse` carries `error_type:
-            processing_class_exceeds_band` + `violations[]`. The
-            `REQUIRES_REENCODE` flavour reuses `ValidationErrorEnvelope`
+            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
@@ -1508,6 +1522,21 @@ paths:
             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:
@@ -1515,6 +1544,7 @@ paths:
                   - $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)
@@ -1541,6 +1571,19 @@ 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
@@ -1766,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
@@ -3498,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
     # ============================================
@@ -4745,6 +4873,54 @@ components:
               items:
                 $ref: '#/components/schemas/FeatureViolation'
 
+    ProbePendingResponse:
+      description: |
+        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
+            - job_ref
+          properties:
+            error_type:
+              type: string
+              enum:
+                - 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: |
@@ -5154,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.
@@ -5162,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
@@ -5186,6 +5366,10 @@ components:
         - custom_luma
         - audio_overlay
         - audio_watermark
+        - audio_to_video
+        - video_watermark
+        - video_text_watermark
+        - split
 
     OperationInputModel:
       type: string
@@ -5193,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
@@ -6142,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:
@@ -6157,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:
@@ -6189,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
@@ -6236,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`
@@ -6867,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
@@ -6888,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)
     # ============================================
@@ -7479,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
@@ -7726,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)