@giveitsmaller/contracts 0.4.0 → 0.7.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.17.0
   contact:
     name: API Support
 
@@ -103,6 +103,14 @@ tags:
   - name: AudioWatermark
     description: Steganographic audio watermark embed and decode
 
+# Spec-root default per ADR-0016 D2: anonymous-OK unless overridden
+# per-operation. Every inbound operation declares an explicit `security:`
+# block (one of `[]`, `[{bearerAuth: []}, {sessionAuth: []}]`, or
+# `[{}, {bearerAuth: []}, {sessionAuth: []}]`) so the contract is
+# self-documenting — `[]` here protects against future endpoints that
+# accidentally inherit a stricter default.
+security: []
+
 paths:
   # ============================================
   # UPLOAD ENDPOINTS
@@ -122,6 +130,7 @@ paths:
         (10 MB). Files above this size MUST use the multipart upload flow
         instead (`POST /api/uploads/multipart/initiate`).
       operationId: uploadFile
+      security: [{}, {bearerAuth: []}, {sessionAuth: []}]  # optional (anon-OK; auth attribution if present)
       tags:
         - Upload
       requestBody:
@@ -321,6 +330,7 @@ paths:
 
         After all parts are uploaded to S3, call the complete endpoint to finalise.
       operationId: multipartInitiate
+      security: [{}, {bearerAuth: []}, {sessionAuth: []}]  # optional (anon-tolerant; manifest.userId pinned to caller if authed)
       tags:
         - Upload
       requestBody:
@@ -455,6 +465,8 @@ paths:
         rule and additionally refuse anonymous-initiated sessions
         outright (returning 403 `MULTIPART_SESSION_AUTH_REQUIRED`).
       operationId: multipartComplete
+      security: [{}, {bearerAuth: []}, {sessionAuth: []}]  # optional (anon-tolerant; ownership-scoped per HxUmVr3Y when manifest.userId set)
+      x-identity-scoped: true  # session/ownership-scoped per ADR-0016 D3
       tags:
         - Upload
       requestBody:
@@ -550,6 +562,8 @@ paths:
         Completion-readiness is client-derived (walk all pages, compare
         the count of returned parts to `total_parts`).
       operationId: multipartStatus
+      security: [{bearerAuth: []}, {sessionAuth: []}]  # required (anon-initiated sessions rejected with MULTIPART_SESSION_AUTH_REQUIRED — see ErrorCode.authentication_required prose)
+      x-identity-scoped: true  # session/ownership-scoped per ADR-0016 D3
       tags:
         - Upload
       parameters:
@@ -674,6 +688,8 @@ paths:
         **Authentication required.** Same `MULTIPART_SESSION_*` codes
         apply as on `/status`.
       operationId: multipartPresign
+      security: [{bearerAuth: []}, {sessionAuth: []}]  # required (anon-initiated sessions rejected; resume-only endpoint)
+      x-identity-scoped: true  # session/ownership-scoped per ADR-0016 D3
       tags:
         - Upload
       parameters:
@@ -793,6 +809,8 @@ paths:
         **Authentication required.** Same `MULTIPART_SESSION_*` codes
         apply as on `/status` and `/presign`.
       operationId: multipartKeepalive
+      security: [{bearerAuth: []}, {sessionAuth: []}]  # required (anon-initiated sessions rejected; resume-only endpoint)
+      x-identity-scoped: true  # session/ownership-scoped per ADR-0016 D3
       tags:
         - Upload
       parameters:
@@ -868,6 +886,8 @@ paths:
         - **Audio:** duration, bitrate, channels, sample_rate, codec
         - **Documents:** page_count, dimensions (for PDF)
       operationId: getUploadMetadata
+      security: [{}, {bearerAuth: []}, {sessionAuth: []}]  # optional (anon-OK; identity-scoped to caller's session/identity)
+      x-identity-scoped: true  # ownership-scoped per ADR-0016 D3
       tags:
         - Upload
       parameters:
@@ -955,6 +975,8 @@ paths:
         same `probed_at` timestamp + result (cached server-side per
         upload).
       operationId: probeUpload
+      security: [{bearerAuth: []}, {sessionAuth: []}]  # required (explicit 401 in response set; ownership-scoped)
+      x-identity-scoped: true  # ownership-scoped per ADR-0016 D3
       tags:
         - Upload
       x-availability: planned
@@ -968,82 +990,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:
@@ -1163,6 +1195,8 @@ paths:
         idempotency-key wire shape for retried reservation attempts
         is deferred per ADR-0001 §1.7 row 5.
       operationId: createWorkflow
+      security: [{}, {bearerAuth: []}, {sessionAuth: []}]  # optional (anon-OK on free-tier baseline; auth required for tier-gated operations)
+      x-identity-scoped: true  # request body dereferences upload file_ids — cross-identity references return 403 per ADR-0016 D3 (NOTE: §D4 ADR sample showed identity_scoped: false; B3 audit flipped to true per §D3 principle — SDK-acked 2026-05-28)
       tags:
         - Workflow
       requestBody:
@@ -1495,8 +1529,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 +1546,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 +1568,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 +1595,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
@@ -1613,6 +1680,8 @@ paths:
         Each operation includes its current progress and, when completed, its result
         (download URL, size, metrics).
       operationId: getWorkflowStatus
+      security: [{}, {bearerAuth: []}, {sessionAuth: []}]  # optional (anon-OK; identity-scoped to workflow owner)
+      x-identity-scoped: true  # workflow-ownership-scoped per ADR-0016 D3
       tags:
         - Workflow
       parameters:
@@ -1694,6 +1763,8 @@ paths:
         Each job's operations are listed with their output files and pre-signed
         download URLs.
       operationId: getWorkflowDownloads
+      security: [{}, {bearerAuth: []}, {sessionAuth: []}]  # optional (anon-OK; identity-scoped to workflow owner)
+      x-identity-scoped: true  # workflow-ownership-scoped per ADR-0016 D3
       tags:
         - Workflow
       parameters:
@@ -1766,7 +1837,38 @@ 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
+      security: [{}, {bearerAuth: []}, {sessionAuth: []}]  # optional (anon-OK; identity-scoped to workflow owner)
+      x-identity-scoped: true  # workflow-ownership-scoped per ADR-0016 D3
       tags:
         - Workflow
       parameters:
@@ -1830,6 +1932,8 @@ paths:
         cancel response is the binding "no further reservations
         will be made" signal.
       operationId: cancelWorkflow
+      security: [{bearerAuth: []}, {sessionAuth: []}]  # required (explicit 401 in response set)
+      x-identity-scoped: true  # workflow-ownership-scoped per ADR-0016 D3
       tags:
         - Workflow
       parameters:
@@ -1932,6 +2036,8 @@ paths:
         a 409 (no-op — the workflow is already running, terminal,
         or cancelled).
       operationId: resumeWorkflow
+      security: [{bearerAuth: []}, {sessionAuth: []}]  # required (explicit 401 in response set)
+      x-identity-scoped: true  # workflow-ownership-scoped per ADR-0016 D3
       tags:
         - Workflow
       parameters:
@@ -2053,6 +2159,7 @@ paths:
         on `OptionSchema` (ticket I17). Clients should use these to build
         dynamic forms with availability-aware UX.
       operationId: getOperationsSchema
+      security: [{}, {bearerAuth: []}, {sessionAuth: []}]  # optional (anon-OK returns free-tier baseline; auth tier-scopes the response)
       tags:
         - Operations
       parameters:
@@ -2215,6 +2322,8 @@ paths:
         The original failed operation is marked as `retried` and a new operation with
         a new ID is created in `pending` state.
       operationId: retryOperation
+      security: [{}, {bearerAuth: []}, {sessionAuth: []}]  # optional (anon-OK; identity-scoped to operation owner)
+      x-identity-scoped: true  # operation-ownership-scoped per ADR-0016 D3
       tags:
         - Operations
       parameters:
@@ -2268,6 +2377,7 @@ paths:
       summary: Liveness probe
       description: Kubernetes liveness probe endpoint
       operationId: liveness
+      security: []  # anonymous (k8s probe — auth irrelevant)
       tags:
         - Health
       responses:
@@ -2285,6 +2395,7 @@ paths:
       summary: Readiness probe
       description: Kubernetes readiness probe endpoint - checks database and cache connectivity
       operationId: readiness
+      security: []  # anonymous (k8s probe — auth irrelevant)
       tags:
         - Health
       responses:
@@ -2321,6 +2432,7 @@ paths:
           - `429` — infrastructure rate-limit (too many attempts in the current
             window). Distinct from `account_locked`, which is persisted state.
       operationId: loginUser
+      security: []  # anonymous (entry point — you're logging in, no creds yet)
       tags:
         - Auth
       requestBody:
@@ -2508,6 +2620,8 @@ paths:
         endpoint since `AuthController.php:19-22`; this declaration
         catches the contract up).
       operationId: logoutUser
+      security: [{bearerAuth: []}, {sessionAuth: []}]  # required (logout requires an authenticated principal to invalidate)
+      x-identity-scoped: true  # identity-bound (caller's own session) per ADR-0016 D3 — by symmetry with credits/balance per §D4 sample
       tags:
         - Auth
       responses:
@@ -2602,6 +2716,14 @@ paths:
         per ADR-0001 §1.3); the runtime endpoint returns `404` until
         cross-repo wiring lands.
       operationId: createExternalImport
+      # Auth: REQUIRED defensively. Endpoint is availability:planned (no
+      # controller yet); but the endpoint stores encrypted server-side
+      # secrets (bearer URLs, passwords) and anon-callable secret
+      # storage is almost certainly wrong. Locking the contract here
+      # while we still own the source of truth; runtime tightens to
+      # match when the controller lands. Per ADR-0016 / karen review
+      # on yN309QVb-B2.
+      security: [{bearerAuth: []}, {sessionAuth: []}]
       x-availability: planned
       tags:
         - Upload
@@ -2708,6 +2830,7 @@ paths:
         `feature_not_available` (422) until the Lambda lands. Per
         Tension 1 (ADR-0001 §1.3).
       operationId: decodeAudioWatermark
+      security: [{bearerAuth: []}, {sessionAuth: []}]  # required (explicit 401 in response set; tier-gated runtime call)
       tags:
         - AudioWatermark
       x-availability: planned
@@ -2805,6 +2928,8 @@ paths:
         SDKs gate UI on `available_credits` for the spend-now affordance
         and on `tier` for tier-upgrade prompts.
       operationId: getCreditsBalance
+      security: [{bearerAuth: []}, {sessionAuth: []}]  # required (identity-scoped to caller's wallet)
+      x-identity-scoped: true  # caller's wallet — per ADR-0016 §D4 sample
       tags:
         - Billing
       responses:
@@ -2884,6 +3009,8 @@ paths:
 
         Default page is 20 transactions, ordered most-recent-first.
       operationId: getCreditsUsage
+      security: [{bearerAuth: []}, {sessionAuth: []}]  # required (identity-scoped to caller's usage history)
+      x-identity-scoped: true  # caller's usage history — per ADR-0016 D3
       tags:
         - Billing
       parameters:
@@ -3067,6 +3194,7 @@ paths:
         On success, returns 204 with no body. The API sends the message via its
         configured delivery channel (e.g. email, queue).
       operationId: submitContact
+      security: []  # anonymous (public contact form)
       tags:
         - Contact
       requestBody:
@@ -3153,6 +3281,38 @@ webhooks:
           description: Callback acknowledged (no body)
 
 components:
+  # Per ADR-0016: auth presence is modeled with OpenAPI-native
+  # `security` / `securitySchemes` (NOT a custom `auth:` field) so codegen,
+  # spectral, and oasdiff understand it natively. Two schemes — the same
+  # Symfony `api` firewall accepts BOTH a bearer API-key and a login-session
+  # cookie. Per-operation `security:` blocks OR the two schemes for the
+  # three idioms (anonymous / required / optional). Spec root carries
+  # `security: []` default (anonymous-OK); per-operation overrides flip
+  # the requirement.
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      description: |
+        API-key bearer authentication. The `ApiKeyAuthenticator`
+        (Symfony `api` firewall) validates
+        `Authorization: Bearer <api-key>` per the prose under
+        `ErrorCode.authentication_required`.
+    sessionAuth:
+      type: apiKey
+      in: cookie
+      name: PHPSESSID
+      description: |
+        Login-session cookie authentication. The `ApiEntryPoint`
+        (Symfony `api` firewall) recognises an authenticated session
+        when the cookie is present and the session has a valid
+        principal. Set by `POST /api/auth/login`; cleared by
+        `POST /api/auth/logout`. Cookie name `PHPSESSID` follows the
+        Symfony / PHP default — no `framework.session.name` override
+        in `compression/config/packages/framework.yaml` as of v2.16.6
+        verification. Update this declaration if the API repo ever
+        adds a `session.name` override.
+
   schemas:
     # ============================================
     # SHARED PRIMITIVES
@@ -3498,6 +3658,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 +4961,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 +5418,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 +5426,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 +5454,10 @@ components:
         - custom_luma
         - audio_overlay
         - audio_watermark
+        - audio_to_video
+        - video_watermark
+        - video_text_watermark
+        - split
 
     OperationInputModel:
       type: string
@@ -5193,8 +5465,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 +6415,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 +6441,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 +6473,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 +6520,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 +7166,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 +7189,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 +7803,289 @@ 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.
+
+        **v2.16.1 attempted PHP-template fix (superseded by v2.16.5).**
+        The v2.16.1 cut introduced the shared `SseCompletionBase`
+        schema declaring `result_kind: { enum: [single, multi] }` (both
+        literal values together) and had the branch wrappers
+        allOf-merge it. The intent was to fix the v2.15.3 design where
+        `result_kind` was declared only as `enum: [single]` /
+        `enum: [multi]` inside each branch's inline `allOf` block —
+        which made the openapi-generator PHP template flatten only one
+        branch's enum into `getResultKindAllowableValues()`. The
+        v2.16.1 verification at the time confirmed PHP emitted both
+        values, but against the v2.15.3-generated tree, not against a
+        fresh v2.16.1 regen. SDKs later caught (via codex on the
+        v2.16.3 regen, surfaced by ChSmslxj) that v2.16.1's shared-base
+        fix did NOT actually propagate through the PHP template — the
+        template visits each oneOf branch's allOf and only flattens the
+        per-branch single-value enum, NOT the shared base's full-union
+        enum. PHP root model still emitted `RESULT_KIND_MULTI` only
+        (the second branch's value). SseCompletionBase is RETAINED in
+        v2.16.5 for documentation + JSON Schema branch identification
+        + consumers that traverse the allOf chain, but on its own it
+        is NOT load-bearing for PHP correctness.
+
+        **v2.16.5 ChSmslxj PHP-template fix (load-bearing).**
+        Declares `result_kind` with the full `enum: [single, multi]`
+        directly on the ROOT `SseOperationCompletionResult` schema as
+        a sibling of `oneOf` and `discriminator` (with `type: object`
+        + `required: [result_kind]`). The openapi-generator PHP
+        template flattens this root enum cleanly into
+        `getResultKindAllowableValues()`, emitting both
+        `RESULT_KIND_SINGLE` and `RESULT_KIND_MULTI`. The triple
+        declaration (root + SseCompletionBase + per-branch wrappers)
+        is harmless redundancy: the root carries the full union for
+        the PHP template; SseCompletionBase carries the full union
+        for allOf-chain consumers; per-branch wrappers pin to a
+        single literal value for OpenAPI discriminator semantics +
+        JSON Schema branch identification. TypeScript dispatch is
+        unchanged (`switch (json['result_kind'])` reads the
+        snake_case wire key directly — verified on openapi-generator-
+        cli v7.21.0).
+      type: object
+      required:
+        - result_kind
+      properties:
+        result_kind:
+          type: string
+          enum: [single, multi]
+          description: |
+            Discriminator field. The full `[single, multi]` enum is
+            declared directly on the root (this object) so the
+            openapi-generator PHP template flattens both literal
+            values into `getResultKindAllowableValues()` per
+            ChSmslxj. Also declared on the shared `SseCompletionBase`
+            (retained for consumers that traverse the allOf chain)
+            and on each per-branch wrapper (single-value enum pinning
+            the branch). The triple declaration is harmless redundancy
+            necessary for PHP template flattening.
+      oneOf:
+        - $ref: '#/components/schemas/SseSingleOutputCompletion'
+        - $ref: '#/components/schemas/SseMultiOutputCompletionWithKind'
+      discriminator:
+        propertyName: result_kind
+        mapping:
+          single: '#/components/schemas/SseSingleOutputCompletion'
+          multi: '#/components/schemas/SseMultiOutputCompletionWithKind'
+
+    SseCompletionBase:
+      type: object
+      description: |
+        Shared base schema for the two `SseOperationCompletionResult`
+        branches. Declares the `result_kind` discriminator field as a
+        `[single, multi]` enum with both literal values, then each branch
+        wrapper allOf-merges this base + its body schema.
+
+        **Rationale (v2.16.1):** the v2.15.3 design declared `result_kind`
+        as a single-value `enum [single]` / `enum [multi]` inside each
+        branch's inline `allOf` block. The openapi-generator PHP template
+        for this shape flattens only the FIRST branch's discriminator enum
+        into the root `getResultKindAllowableValues()` list, so PHP
+        deserialisation rejects the other branch's wire value as invalid.
+        Promoting `result_kind` to a shared base with the full union
+        `enum [single, multi]` makes PHP accept both values; the
+        per-branch `enum [single]` / `enum [multi]` (kept on the wrappers
+        for JSON Schema-level branch identification + OpenAPI
+        discriminator semantics) does not regress. TypeScript dispatch
+        continues to use `switch (json['result_kind'])` — confirmed by
+        codegen verification on openapi-generator-cli v7.21.0.
+      required:
+        - result_kind
+      properties:
+        result_kind:
+          type: string
+          enum: [single, multi]
+          description: |
+            Discriminator field on `SseOperationCompletionResult`. The
+            API SSE serializer emits `"single"` for single-output
+            completion payloads and `"multi"` for multi-output payloads;
+            generated SDK dispatch routes on this value to pick the
+            correct branch deserializer.
+
+    SseSingleOutputCompletion:
+      description: |
+        Single-output branch of `SseOperationCompletionResult` — wraps
+        `OperationResult` + the shared `SseCompletionBase` + pins
+        `result_kind` to the literal `"single"`. See
+        `SseOperationCompletionResult` description for the rationale +
+        codegen-quirk context.
+      allOf:
+        - $ref: '#/components/schemas/OperationResult'
+        - $ref: '#/components/schemas/SseCompletionBase'
+        - type: object
+          properties:
+            result_kind:
+              type: string
+              enum: [single]
+
+    SseMultiOutputCompletionWithKind:
+      description: |
+        Multi-output branch of `SseOperationCompletionResult` — wraps
+        `SseMultiOutputCompletion` + the shared `SseCompletionBase` +
+        pins `result_kind` to the literal `"multi"`. See
+        `SseOperationCompletionResult` description for the rationale +
+        codegen-quirk context.
+      allOf:
+        - $ref: '#/components/schemas/SseMultiOutputCompletion'
+        - $ref: '#/components/schemas/SseCompletionBase'
+        - type: object
+          properties:
+            result_kind:
+              type: string
+              enum: [multi]
+
+    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
@@ -7679,6 +8285,84 @@ components:
             availability metadata per I1 / I17).
           additionalProperties:
             $ref: '#/components/schemas/OperationSchemaDefinition'
+        endpoints:
+          type: object
+          description: |
+            Flat per-endpoint auth/identity projection per
+            [ADR-0016](../docs/decisions/0016-per-endpoint-auth-identity-modeling.md)
+            §D4. Keys are `<METHOD> <PATH>` literals (e.g.
+            `"POST /api/workflows"`); values declare the auth axis +
+            identity-scoping + reserved tier/availability slots +
+            operation_id for SDK ergonomic-layer consumption.
+
+            Webhook operations are EXCLUDED per ADR-0016 §D5 — outbound
+            HMAC-signed callbacks use a separate auth model.
+
+            **Optional in the wire envelope** to keep the runtime
+            endpoint's mirroring obligation incremental: the
+            committed sidecar (yN309QVb-B3 / v2.17.0+) emits this
+            block authoritatively; the runtime `GET /api/operations/
+            schema` MAY mirror it once the API team's runtime
+            generator catches up. Consumers MUST tolerate absent
+            `endpoints` from the runtime endpoint (read the sidecar
+            instead) and MUST tolerate present `endpoints` from
+            either source.
+          additionalProperties:
+            $ref: '#/components/schemas/EndpointProjection'
+
+    EndpointProjection:
+      type: object
+      description: |
+        Per-endpoint projection entry per ADR-0016 §D4. Five fields;
+        `required_tier` and `availability` at endpoint level are
+        reserved/null today (operation-level `required_tier` continues
+        to flow via `operations.*.required_tier`; every shipped
+        endpoint is currently `availability: stable`).
+      required:
+        - auth
+        - identity_scoped
+        - required_tier
+        - availability
+        - operation_id
+      properties:
+        auth:
+          type: string
+          enum: [anonymous, optional, required]
+          description: |
+            3-value projection of the operation's `security:` block:
+            `anonymous` (`security: []`), `optional` (`security`
+            contains the empty requirement `{}`), `required`
+            (otherwise).
+        identity_scoped:
+          type: boolean
+          description: |
+            Value of the `x-identity-scoped` vendor extension on the
+            operation (default `false`). True iff the operation
+            targets an identity-bound resource and cross-identity
+            access returns 403 — OR acts on the caller's implicit
+            identity-scoped data (credits balance, own session).
+        required_tier:
+          description: |
+            Endpoint-level entitlement gate. Reserved/null today —
+            operation-level `required_tier` flows via
+            `operations.*.required_tier` and is NOT duplicated here.
+          oneOf:
+            - $ref: '#/components/schemas/UserTier'
+            - type: 'null'
+        availability:
+          type: string
+          enum: [stable, beta, experimental, planned, deprecated]
+          description: |
+            Endpoint-level availability tag. Currently always
+            `"stable"` for shipped endpoints. Reserved for future
+            `planned` / `deprecated` endpoint-level annotation.
+        operation_id:
+          type: string
+          description: |
+            OpenAPI `operationId` for the operation. SDK code
+            generators anchor on this for method naming; including
+            it in the sidecar saves a round-trip to `openapi/api.yaml`.
+            Per the SDK ask at ADR-0016 B1 sign-off.
 
     OperationSchemaDefinition:
       type: object
@@ -7726,11 +8410,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)
@@ -7840,6 +8539,7 @@ components:
             - boolean
             - enum
             - string
+            - array
         description:
           type: string
           description: Human-readable description