@giveitsmaller/contracts 0.9.0 → 0.17.0

package/openapi/api.yaml

@@ -14,7 +14,7 @@ info:
     All mutation and query endpoints return `{ success: true, data: {...} }` on success
     and `{ success: false, error: "...", details: [...] }` on failure.
     Exceptions: `GET /api/operations/schema` returns raw JSON (per-tier
-    private caching with ETag/Last-Modified revalidation per ADR-0002 + I3),
+    private caching with ETag revalidation per ADR-0002 + I3),
     health probes return flat objects, and `POST /api/contact` returns
     204 with no body.
 
@@ -89,7 +89,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.31.0
+  version: 2.66.0
   contact:
     name: API Support
 
@@ -1133,6 +1133,60 @@ paths:
   # ============================================
 
   /api/workflows:
+    get:
+      summary: List the caller's workflows
+      description: |
+        Cursor-paginated, **user-scoped** summary list of the caller's
+        workflows, most-recent-first (`created_at DESC`, with an id
+        tiebreaker for same-second rows). Each row is a **lightweight
+        summary** (id / status / created_at + per-job type+status + a
+        deliverable-output count) for list rendering — it deliberately does
+        NOT inline per-operation `result_metadata` or output details (avoids
+        N×M×K payload blow-up). Drill in via `GET /api/workflows/{id}/status`
+        (per-op detail incl. `result_metadata`) and
+        `GET /api/workflows/{id}/downloads` (deliverables). Rows persist until
+        GDPR purge — workflows whose 24h download window has expired are still
+        listed. Per ticket [`nLK1IO1k`](https://trello.com/c/nLK1IO1k) (A1).
+      operationId: listWorkflows
+      security: [{bearerAuth: []}, {sessionAuth: []}]  # required (explicit 401 — user-scoped list, no anonymous access)
+      x-identity-scoped: true  # caller's own workflows — implicit identity-scoped, per ADR-0016 D3 (cf. credits/usage)
+      tags:
+        - Workflows
+      parameters:
+        - name: cursor
+          in: query
+          required: false
+          description: |
+            Opaque pagination cursor from a previous page's `next_cursor`.
+            Omit (or send empty) for the first page; walk pages by passing
+            each `next_cursor` until `is_truncated: false`. Encodes the
+            `(created_at, id)` position — treat as opaque, do not parse.
+          schema:
+            type: string
+        - name: limit
+          in: query
+          required: false
+          description: Maximum rows per page (1-100; default 20).
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 100
+            default: 20
+      responses:
+        '200':
+          description: Cursor-paginated summary list of the caller's workflows.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/WorkflowListSuccessEnvelope'
+        '401':
+          description: |
+            Authentication required — anonymous callers cannot list
+            workflows (the list is user-scoped).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
     post:
       summary: Create a workflow
       description: |
@@ -1149,10 +1203,17 @@ paths:
           custom_luma, audio_overlay, audio_to_video, video_watermark):
           provide `inputs[]` with
           `JobInputV2` entries. Each entry has its own `source`
-          (same `WorkflowSource` union), plus optional `role`
+          (a `MultiInputSource` — the 3-leaf subset of `WorkflowSource`
+          that **excludes `upload`**: `job_output` / `external_import` /
+          `connection`), plus optional `role`
           (image_watermark, custom_luma, audio_overlay, audio_to_video,
           video_watermark) and
-          `per_input_options`.
+          `per_input_options`. To feed an uploaded file into a
+          multi-input op, create a `passthrough` source job (single-input,
+          `operations: [{type: passthrough}]`) and reference it from
+          `inputs[].source` as `{type: job_output, from: <id>}` — see the
+          `v2_merge_two_uploads` example and the `passthrough` bullet in
+          `OperationType`.
 
         Exactly one of `source` or `inputs` is required per job.
 
@@ -1184,6 +1245,26 @@ paths:
         still receives the implicit `compress` — see above). Per
         [ADR-0004](../docs/decisions/0004-job-shape.md).
 
+        **Inert passthrough (lossless source jobs).** A single-input
+        source job whose SOLE operation is `passthrough`
+        (`operations: [{type: passthrough}]`) emits its source bytes
+        UNCHANGED — no compression, no transformation, no Lambda. This
+        is the EXPLICIT lossless path (built on the opt-out rule above:
+        a non-empty `operations[]` without `compress`); it is distinct
+        from `operations: []`, which KEEPS its implicit-compress meaning
+        on a single-input upload job. The API **self-completes** a
+        passthrough job at publish: the job's terminal output IS the
+        upload's `{bucket, key}` unchanged, and `passthrough` is **never
+        published to SNS** (no `ops-passthrough` queue; absent from the
+        AsyncAPI routing enums). Its purpose is to bridge an uploaded
+        file into a multi-input op (`merge` / `archive` /
+        `image_watermark` / …): since `JobInputV2.source` excludes
+        upload-direct, the upload becomes a `passthrough` source job
+        that the downstream multi-input job references via
+        `{type: job_output, from: <id>}` — preserving billing / DAG /
+        lineage. Per ticket
+        [`4som89Uh`](https://trello.com/c/4som89Uh).
+
         **Multi-input constraint:** multi-input jobs (`inputs[]`) must
         have exactly one operation, which must be a multi-input type
         (`merge`, `archive`, `image_watermark`, `custom_luma`,
@@ -1213,7 +1294,14 @@ paths:
         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)
+      # x-identity-scoped: the request body dereferences identity-bound upload refs.
+      # CARVE-OUT (ADR-0016 Amendment, nGYbgChX): cross-identity/anonymous upload refs
+      # are 404 UPLOAD_NOT_FOUND IDOR/BOLA-masked (NEVER 403) so the response does not
+      # reveal another user's upload exists — see the createWorkflow 404 response.
+      # ADR-0016 D3's generic "identity-scoped -> 403" gloss over-claimed for uploads;
+      # the runtime always 404-masked (CreateWorkflowCommandHandler.php:132-148).
+      # (§D4 sample showed identity_scoped: false; B3 audit flipped to true per §D3 — SDK-acked 2026-05-28.)
+      x-identity-scoped: true
       tags:
         - Workflow
       requestBody:
@@ -1235,6 +1323,26 @@ paths:
                           options:
                             mode: lossy
                             quality: 80
+              v2_flat_single_source:
+                summary: >-
+                  V2 flat form (D0Gsri8V) — top-level source + operations,
+                  no jobs[] wrapper. Exactly equivalent to wrapping these in
+                  jobs:[{source,operations}]. Compress + a thumbnail derived
+                  from the original.
+                value:
+                  source:
+                    type: upload
+                    file_id: "019539ab-1111-7000-8000-000000000001"
+                  operations:
+                    - type: compress
+                      options:
+                        mode: lossy
+                        quality: 80
+                    - type: thumbnail
+                      base: original
+                      options:
+                        width: 320
+                        height: 240
               v2_chain_compress_thumbnail:
                 summary: V2 chained compress -> thumbnail (id required on first job)
                 value:
@@ -1254,16 +1362,28 @@ paths:
                             width: 320
                             height: 240
               v2_merge_two_uploads:
-                summary: V2 multi-input merge (two uploads, no role)
+                summary: V2 multi-input merge (two uploads via passthrough source jobs)
                 value:
                   jobs:
+                    - id: src_a
+                      source:
+                        type: upload
+                        file_id: "019539ab-1111-7000-8000-000000000001"
+                      operations:
+                        - type: passthrough
+                    - id: src_b
+                      source:
+                        type: upload
+                        file_id: "019539ab-1111-7000-8000-000000000002"
+                      operations:
+                        - type: passthrough
                     - inputs:
                         - source:
-                            type: upload
-                            file_id: "019539ab-1111-7000-8000-000000000001"
+                            type: job_output
+                            from: src_a
                         - source:
-                            type: upload
-                            file_id: "019539ab-1111-7000-8000-000000000002"
+                            type: job_output
+                            from: src_b
                       operations:
                         - type: merge
               v2_external_import:
@@ -1534,14 +1654,36 @@ paths:
                     error_type: "balance_exhausted"
                     required_action: "wait_for_renewal"
         '404':
-          description: Referenced file_id not found
+          description: |
+            A referenced upload was not found. Returns the stable machine
+            code `UPLOAD_NOT_FOUND` (`message_key: "upload.not_found"`).
+
+            Uploads are referenced via `jobs[].source` (a `WorkflowSource`
+            with `type: upload`), including the `passthrough` source jobs
+            that bridge an uploaded file into a multi-input operation —
+            multi-input `inputs[].source` cannot reference an upload
+            directly (`MultiInputSource` excludes the `upload` leaf).
+
+            **BOLA/IDOR existence-mask (deliberate, security-reasoned):**
+            this 404 is ALSO returned when the upload exists but is owned
+            by a different identity (or an anonymous workflow references an
+            owned upload) — reported as not-found, **never 403**, so the
+            response does not reveal that another user's upload exists.
+            Consistent with the workflow-owner 404s on
+            cancel / resume / get-workflow. Ownerless (anonymous-intake)
+            uploads have no owner to violate and stay usable by any caller.
+            See [ADR-0016](../docs/decisions/0016-per-endpoint-auth-identity-modeling.md)
+            §"Amendment — upload IDOR mask".
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorEnvelope'
               example:
                 success: false
-                error: "Upload not found: 019539ab-1111-7000-8000-999999999999"
+                error: "UPLOAD_NOT_FOUND"
+                message: "Upload not found"
+                message_key: "upload.not_found"
+                locale: "en-GB"
         '422':
           description: |
             Semantically invalid request. One of:
@@ -2241,10 +2383,11 @@ paths:
 
         **Per-tier private caching.** Per ADR-0002, the response is
         per-caller; CDN-style public caching is NOT used. Clients
-        revalidate via `ETag` (strong) and/or `Last-Modified` headers —
-        send `If-None-Match` / `If-Modified-Since` on subsequent
-        requests; the server returns `304 Not Modified` when the cached
-        response is still fresh.
+        revalidate via the strong `ETag` — send `If-None-Match` on
+        subsequent requests; the server returns `304 Not Modified` when
+        the cached response is still fresh. The content `ETag` is the
+        **sole** conditional validator (per `sUyA9ZXD`): `If-Modified-Since`
+        is **not** honored and `Last-Modified` is informational only.
 
         Cache-key composition (server-side): `user_tier + schema_version + capabilities_version + environment`.
 
@@ -2289,9 +2432,11 @@ paths:
           in: header
           required: false
           description: |
-            Conditional revalidation: send the previously-received
-            `Last-Modified` value (HTTP-date) to receive `304 Not
-            Modified` when the response is still fresh.
+            **NOT honored for conditional `304` (per `sUyA9ZXD`).** The
+            server ignores `If-Modified-Since`; the content `ETag`
+            (`If-None-Match`) is the sole conditional validator. Retained
+            for backward compatibility — sending it has no effect on
+            freshness; use `If-None-Match` instead.
           schema:
             type: string
             format: http-date
@@ -2300,7 +2445,7 @@ paths:
         '200':
           description: |
             Operation schema (raw JSON, no ResponseEnvelope). Tier-scoped
-            per caller; revalidate via `ETag` / `Last-Modified`.
+            per caller; revalidate via the `ETag` (`If-None-Match`).
           headers:
             Cache-Control:
               schema:
@@ -2323,8 +2468,10 @@ paths:
                 type: string
                 format: http-date
               description: |
-                HTTP-date of last response generation. Clients may send
-                `If-Modified-Since: <date>` for revalidation.
+                HTTP-date of last response generation. **Informational
+                only** — NOT a conditional validator (the server does not
+                honor `If-Modified-Since`, per `sUyA9ZXD`). Use the `ETag`
+                (`If-None-Match`) for revalidation.
               example: "Sun, 26 Apr 2026 09:00:00 GMT"
           content:
             application/json:
@@ -2385,10 +2532,10 @@ paths:
                                 values: ["max", "crop", "scale"]
         '304':
           description: |
-            Cached response is still fresh. Server emits `ETag` +
-            `Last-Modified` headers matching the client's revalidation
-            request (`If-None-Match` and/or `If-Modified-Since`). Body
-            empty.
+            Cached response is still fresh (the client's `If-None-Match`
+            matched the current content `ETag`). Server emits `ETag` +
+            (informational) `Last-Modified` headers. `If-Modified-Since`
+            does not drive this response (per `sUyA9ZXD`). Body empty.
           headers:
             Cache-Control:
               schema:
@@ -2740,22 +2887,7 @@ paths:
           content:
             application/json:
               schema:
-                type: object
-                required:
-                  - success
-                  - data
-                properties:
-                  success:
-                    type: boolean
-                    enum: [true]
-                  data:
-                    type: object
-                    description: |
-                      Empty object on logout success — preserves the
-                      `{ success: true, data: {...} }` envelope
-                      invariant from `info.description`. Logout has
-                      no return payload; the data slot is always
-                      `{}`.
+                $ref: '#/components/schemas/EmptySuccessEnvelope'
               example:
                 success: true
                 data: {}
@@ -2788,241 +2920,1270 @@ paths:
               schema:
                 $ref: '#/components/schemas/ErrorEnvelope'
 
-  # ============================================
-  # EXTERNAL IMPORT ENDPOINT (ticket I10)
-  # ============================================
-
-  /api/external-imports:
+  /api/auth/register:
     post:
-      summary: Register a one-shot external import URL
+      summary: Register a new account
       description: |
-        Register a one-shot bearer URL (S3 presigned / GCS signed /
-        Azure SAS / Dropbox shared link / public HTTPS) and receive an
-        opaque `external_source_id` handle. Subsequent workflows
-        reference the handle via `WorkflowSource` of `type:
-        external_import`; the original URL + password are encrypted
-        server-side and never returned in any response.
-
-        Per [ADR-0005](../docs/decisions/0005-external-sources.md) — see
-        §"SSRF posture" for the 8 validation rules applied at
-        registration time AND again at fetch time.
-
-        **Availability:** `planned` — runtime depends on cross-repo
-        ticket [`MbosYtJD`](https://trello.com/c/MbosYtJD) (Lambda team
-        publishes capability manifest) and the
-        [`POST /api/connections`](https://trello.com/c/MbosYtJD) vault
-        endpoint shipping. The contract surface ships now (contract-first
-        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
+        Creates an unverified account from an email/password pair and
+        dispatches a verification email. The account exists but cannot
+        authenticate until the verification token is redeemed at
+        `POST /api/auth/verify-email`.
+
+        Disposable / blocklisted email domains and other invalid-argument
+        rejections collapse into a non-validation `422` envelope
+        (`error: UNPROCESSABLE_ENTITY`, no `details[]`) — distinct from the
+        structured `ValidationErrorEnvelope` returned for malformed input.
+      operationId: registerUser
+      security: []  # anonymous (sign-up entry point — no creds yet)
       tags:
-        - Upload
+        - Auth
       requestBody:
         required: true
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/ExternalImportRequest'
+              type: object
+              required:
+                - email
+                - password
+              properties:
+                email:
+                  type: string
+                  format: email
+                  maxLength: 254
+                password:
+                  type: string
+                  minLength: 8
+                  maxLength: 128
+            example:
+              email: "user@example.com"
+              password: "s3cretpw"
       responses:
         '201':
-          description: External-import handle created.
+          description: |
+            Account created. A verification email has been dispatched; the
+            account cannot authenticate until verified.
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ExternalImportCreatedSuccessEnvelope'
+                $ref: '#/components/schemas/EmptySuccessEnvelope'
               example:
                 success: true
-                data:
-                  external_source_id: "019539ab-2222-7000-8000-000000000001"
-                  expires_at: "2026-04-26T15:00:00Z"
-                  provider: "s3_presigned"
+                data: {}
         '400':
-          description: Validation failed (missing url, malformed URI, scheme not https).
+          description: Request body is invalid (malformed JSON, wrong field types, or body too large).
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorEnvelope'
               example:
                 success: false
-                error: "URL is required and must be https://"
-        '403':
-          description: |
-            Forbidden — SSRF policy violation (private IP, loopback,
-            cloud metadata endpoint), tier-quota restriction, or
-            provider not enabled for caller's tier.
-          content:
-            application/json:
-              schema:
-                oneOf:
-                  - $ref: '#/components/schemas/TierRestrictionResponse'
-                  - $ref: '#/components/schemas/FeatureTierRestrictedResponse'
-                  - $ref: '#/components/schemas/ErrorEnvelope'
+                error: "Request body is invalid."
         '422':
           description: |
-            Unprocessable URL — DNS resolution failed, target
-            unreachable, content-type / magic-byte sniff failed,
-            `expires_at` already past, or `feature_not_available`
-            (provider tagged `planned` for caller's tier).
+            Structured input validation failure (`ValidationErrorEnvelope`,
+            `error_type: validation_error`).
+
+            A non-validation `422` (`error: UNPROCESSABLE_ENTITY`, no
+            `details[]`) is also returned for disposable/blocklisted email
+            domains.
           content:
             application/json:
               schema:
                 oneOf:
                   - $ref: '#/components/schemas/ValidationErrorEnvelope'
-                  - $ref: '#/components/schemas/FeatureNotAvailableResponse'
+                  - $ref: '#/components/schemas/AuthRejectionEnvelope'
                 discriminator:
                   propertyName: error_type
                   mapping:
                     validation_error: '#/components/schemas/ValidationErrorEnvelope'
-                    feature_not_available: '#/components/schemas/FeatureNotAvailableResponse'
+                    unprocessable_entity: '#/components/schemas/AuthRejectionEnvelope'
+              example:
+                success: false
+                error_type: validation_error
+                error: "Validation failed"
+                details:
+                  - field: "password"
+                    message: "This value is too short."
         '429':
-          description: Rate limit exceeded
+          description: |
+            Rate limit exceeded (too many registration attempts in the
+            current window). Carries a `Retry-After` response header per the
+            convention established at `POST /api/auth/login`.
+          headers:
+            Retry-After:
+              description: Seconds to wait before retrying. Delta-seconds (RFC 9110).
+              schema:
+                type: integer
+                minimum: 0
+              example: 60
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorEnvelope'
         '500':
-          description: Internal server error
+          description: Internal server error.
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorEnvelope'
 
-  # ============================================
-  # AUDIO WATERMARK DECODE
-  # ============================================
-
-  /api/audio-watermark/decode:
+  /api/auth/verify-email:
     post:
-      summary: Decode an embedded audio watermark
+      summary: Verify an account email address
       description: |
-        Extract the steganographic watermark embedded by a prior
-        `audio_watermark` operation (per ticket
-        [I20](https://trello.com/c/omiCq7Vn)). Pairs with the
-        `audio_watermark` operation declared in
-        `schemas/operations/audio_watermark.yaml` — the operation
-        embeds; this endpoint decodes.
-
-        **Tier-restricted.** This endpoint is `enterprise`-only. Free
-        and `pro` callers receive a 403 `feature_tier_restricted`.
-        Anonymous callers receive a 401.
-
-        **Scope: own watermarks only.** The decoder will refuse to
-        extract from media the caller did not mark themselves
-        (server-side audit log of watermark origin per
-        `watermark_id`). Per spike S11 acceptance — this avoids the
-        privacy implications of arbitrary-media decode while still
-        serving the forensic-tracking use case (find a leaked asset
-        on a third-party platform, decode the watermark, look up the
-        distribution channel that received the marked copy).
-
-        **Rate-limited.** Request rate per caller is enforced
-        independently from the workflow-create rate limit; abusive
-        decode patterns flag for audit per [ADR-0001](../docs/decisions/0001-contract-first-availability.md).
-
-        **`availability: planned`** — operation Lambda + decode
-        Lambda are cross-repo follow-up. The endpoint declaration
-        ships now (contract-first); the runtime returns
-        `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)
+        Redeems a verification token emailed at registration time, marking
+        the account verified so it can authenticate. A failed or expired
+        verification collapses into a non-validation `422` envelope
+        (no `details[]`) — distinct from the structured
+        `ValidationErrorEnvelope` returned for malformed input.
+      operationId: verifyEmail
+      security: []  # anonymous (token-bearer — pre-authentication)
       tags:
-        - AudioWatermark
-      x-availability: planned
+        - Auth
       requestBody:
         required: true
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/AudioWatermarkDecodeRequest'
+              type: object
+              required:
+                - token
+              properties:
+                token:
+                  type: string
+                  minLength: 1
+                  maxLength: 128
+            example:
+              token: "8f3c1d9a4b2e6f0c1a7d5e9b3c2f4a6d"
       responses:
         '200':
-          description: Watermark successfully extracted.
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/AudioWatermarkDecodeResponse'
-        '401':
-          description: Authentication required (anonymous callers).
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ErrorEnvelope'
-        '403':
-          description: |
-            Tier insufficient (free / pro caller) — returned as
-            `FeatureTierRestrictedResponse` with
-            `error_type: feature_tier_restricted`. Per ADR-0001 §1.3.
+          description: Email verified. The account can now authenticate.
           content:
             application/json:
               schema:
-                oneOf:
-                  - $ref: '#/components/schemas/TierRestrictionResponse'
-                  - $ref: '#/components/schemas/FeatureTierRestrictedResponse'
-                discriminator:
-                  propertyName: error_type
-                  mapping:
-                    tier_restriction: '#/components/schemas/TierRestrictionResponse'
-                    feature_tier_restricted: '#/components/schemas/FeatureTierRestrictedResponse'
-        '404':
-          description: |
-            No watermark detected in the supplied asset, OR the
-            detected watermark was not issued by this caller (the
-            scope-limit applies — own-watermarks-only).
+                $ref: '#/components/schemas/EmptySuccessEnvelope'
+              example:
+                success: true
+                data: {}
+        '400':
+          description: Request body is invalid (malformed JSON, wrong field types, or body too large).
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: "Request body is invalid."
         '422':
           description: |
-            Either generic validation error
-            (`ValidationErrorEnvelope`) or the operation is `planned`
-            and the runtime Lambda has not yet shipped
-            (`FeatureNotAvailableResponse` with `error_type:
-            feature_not_available`).
+            Structured input validation failure (`ValidationErrorEnvelope`,
+            `error_type: validation_error`).
+
+            A non-validation `422` (`error: UNPROCESSABLE_ENTITY`, no
+            `details[]`) is returned when the verification link is invalid
+            or expired.
           content:
             application/json:
               schema:
                 oneOf:
                   - $ref: '#/components/schemas/ValidationErrorEnvelope'
-                  - $ref: '#/components/schemas/FeatureNotAvailableResponse'
+                  - $ref: '#/components/schemas/AuthRejectionEnvelope'
                 discriminator:
                   propertyName: error_type
                   mapping:
                     validation_error: '#/components/schemas/ValidationErrorEnvelope'
-                    feature_not_available: '#/components/schemas/FeatureNotAvailableResponse'
+                    unprocessable_entity: '#/components/schemas/AuthRejectionEnvelope'
+              example:
+                success: false
+                error_type: validation_error
+                error: "Validation failed"
+                details:
+                  - field: "token"
+                    message: "This value should not be blank."
         '429':
           description: |
-            Rate limit exceeded for decode requests. Decode
-            rate-limit is enforced independently from
-            workflow-create.
+            Rate limit exceeded (too many verification attempts in the
+            current window). Carries a `Retry-After` response header.
+          headers:
+            Retry-After:
+              description: Seconds to wait before retrying. Delta-seconds (RFC 9110).
+              schema:
+                type: integer
+                minimum: 0
+              example: 60
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorEnvelope'
         '500':
-          description: Internal server error
+          description: Internal server error.
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorEnvelope'
 
-  # ============================================
-  # CREDITS + BILLING ENDPOINTS (F9 — per ticket I23)
-  # ============================================
-
-  /api/v2/credits/balance:
-    get:
-      summary: Get current credit balance
+  /api/auth/forgot-password:
+    post:
+      summary: Request a password-reset email
+      description: |
+        Dispatches a password-reset email if the address maps to an account.
+
+        **Anti-enumeration: this endpoint ALWAYS returns `200`**, even when
+        the email does not correspond to any account. Callers cannot use the
+        response to discover whether an account exists. The only non-success
+        responses are structured input validation (`422`) and rate-limiting
+        (`429`).
+      operationId: forgotPassword
+      security: []  # anonymous (account-recovery entry point)
+      tags:
+        - Auth
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - email
+              properties:
+                email:
+                  type: string
+                  format: email
+            example:
+              email: "user@example.com"
+      responses:
+        '200':
+          description: |
+            Request accepted. A reset email is dispatched only if the address
+            maps to an account; the response shape is identical either way
+            (anti-enumeration).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/EmptySuccessEnvelope'
+              example:
+                success: true
+                data: {}
+        '400':
+          description: Request body is invalid (malformed JSON, wrong field types, or body too large).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: "Request body is invalid."
+        '422':
+          description: Structured input validation failure (malformed `email`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ValidationErrorEnvelope'
+              example:
+                success: false
+                error_type: validation_error
+                error: "Validation failed"
+                details:
+                  - field: "email"
+                    message: "This value is not a valid email address."
+        '429':
+          description: |
+            Rate limit exceeded (too many reset requests in the current
+            window). Carries a `Retry-After` response header.
+          headers:
+            Retry-After:
+              description: Seconds to wait before retrying. Delta-seconds (RFC 9110).
+              schema:
+                type: integer
+                minimum: 0
+              example: 60
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+
+  /api/auth/reset-password:
+    post:
+      summary: Reset a password using a reset token
+      description: |
+        Sets a new password using a token issued by
+        `POST /api/auth/forgot-password`. An invalid or expired token is
+        rejected with a flat `400 BAD_REQUEST` envelope — distinct from the
+        structured `422 ValidationErrorEnvelope` returned for malformed input.
+      operationId: resetPassword
+      security: []  # anonymous (token-bearer — pre-authentication)
+      tags:
+        - Auth
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - token
+                - password
+              properties:
+                token:
+                  type: string
+                  minLength: 1
+                password:
+                  type: string
+                  minLength: 8
+            example:
+              token: "8f3c1d9a4b2e6f0c1a7d5e9b3c2f4a6d"
+              password: "news3cretpw"
+      responses:
+        '200':
+          description: Password reset. The caller can now authenticate with the new password.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/EmptySuccessEnvelope'
+              example:
+                success: true
+                data: {}
+        '400':
+          description: |
+            The reset token is invalid, expired, or already consumed
+            (`error: BAD_REQUEST`). Distinct from the structured `422`
+            returned for malformed input.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: "BAD_REQUEST"
+        '422':
+          description: Structured input validation failure (e.g. blank `token`, short `password`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ValidationErrorEnvelope'
+              example:
+                success: false
+                error_type: validation_error
+                error: "Validation failed"
+                details:
+                  - field: "password"
+                    message: "This value is too short."
+        '429':
+          description: |
+            Rate limit exceeded (too many reset attempts in the current
+            window). Carries a `Retry-After` response header.
+          headers:
+            Retry-After:
+              description: Seconds to wait before retrying. Delta-seconds (RFC 9110).
+              schema:
+                type: integer
+                minimum: 0
+              example: 60
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+
+  /api/auth/change-password:
+    post:
+      summary: Change the authenticated user's password
+      description: |
+        Changes the caller's password after re-verifying the current one.
+        Requires an authenticated principal (session cookie or bearer token).
+
+        A wrong `current_password` is rejected with a flat `400 BAD_REQUEST`
+        envelope — distinct from the structured `422 ValidationErrorEnvelope`
+        returned for malformed input. `details[].field` values use the wire
+        keys `current_password` / `new_password`.
+      operationId: changePassword
+      security: [{bearerAuth: []}, {sessionAuth: []}]  # required (authenticated principal)
+      x-identity-scoped: true  # identity-bound (caller's own credential)
+      tags:
+        - Auth
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - current_password
+                - new_password
+              properties:
+                current_password:
+                  type: string
+                  minLength: 1
+                new_password:
+                  type: string
+                  minLength: 8
+            example:
+              current_password: "olds3cretpw"
+              new_password: "news3cretpw"
+      responses:
+        '200':
+          description: Password changed.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/EmptySuccessEnvelope'
+              example:
+                success: true
+                data: {}
+        '400':
+          description: |
+            The supplied `current_password` is incorrect
+            (`error: BAD_REQUEST`). Distinct from the structured `422`
+            returned for malformed input.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: "BAD_REQUEST"
+        '401':
+          description: No authenticated principal.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: "AUTHENTICATION_REQUIRED"
+                error_type: "authentication_required"
+                message: "Authentication required."
+        '404':
+          description: |
+            The authenticated principal no longer resolves to a stored user
+            (`error: USER_NOT_FOUND`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: "USER_NOT_FOUND"
+        '422':
+          description: Structured input validation failure (e.g. blank `current_password`, short `new_password`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ValidationErrorEnvelope'
+              example:
+                success: false
+                error_type: validation_error
+                error: "Validation failed"
+                details:
+                  - field: "new_password"
+                    message: "This value is too short."
+        '429':
+          description: |
+            Rate limit exceeded. Carries a `Retry-After` response header.
+          headers:
+            Retry-After:
+              description: Seconds to wait before retrying. Delta-seconds (RFC 9110).
+              schema:
+                type: integer
+                minimum: 0
+              example: 60
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+
+  /api/auth/confirm-email-change:
+    post:
+      summary: Confirm a pending email-address change
+      description: |
+        Redeems a token issued when the caller requested an email change via
+        `PATCH /api/auth/profile`, applying the new address to the account.
+
+        Failure modes carry their own `error_type` discriminators
+        (`token_not_found`, etc.) on the flat `ErrorEnvelope` shape and are
+        distinct from the structured `422 ValidationErrorEnvelope` returned
+        for malformed input.
+      operationId: confirmEmailChange
+      security: []  # anonymous (token-bearer — confirmation link)
+      tags:
+        - Auth
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - token
+              properties:
+                token:
+                  type: string
+                  minLength: 1
+            example:
+              token: "8f3c1d9a4b2e6f0c1a7d5e9b3c2f4a6d"
+      responses:
+        '200':
+          description: Email address changed.
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    type: boolean
+                    enum: [true]
+                  data:
+                    type: object
+                    required:
+                      - message
+                    properties:
+                      message:
+                        type: string
+              example:
+                success: true
+                data:
+                  message: "Email address has been changed successfully."
+        '400':
+          description: "Malformed or otherwise rejected confirmation (`error: BAD_REQUEST`)."
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: "BAD_REQUEST"
+        '404':
+          description: |
+            The confirmation token does not match any pending email change
+            (`error: TOKEN_NOT_FOUND`, `error_type: token_not_found`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: "TOKEN_NOT_FOUND"
+                error_type: "token_not_found"
+        '409':
+          description: |
+            The target email address was claimed by another account before
+            confirmation (`error: EMAIL_TAKEN`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: "EMAIL_TAKEN"
+        '410':
+          description: |
+            The confirmation token has expired or was already used
+            (`error: TOKEN_EXPIRED` or `TOKEN_USED`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: "TOKEN_EXPIRED"
+        '422':
+          description: Structured input validation failure (e.g. blank `token`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ValidationErrorEnvelope'
+              example:
+                success: false
+                error_type: validation_error
+                error: "Validation failed"
+                details:
+                  - field: "token"
+                    message: "This value should not be blank."
+        '500':
+          description: Internal server error.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+
+  /api/auth/api-keys:
+    post:
+      summary: Create an API key for the authenticated user
+      description: |
+        Mints a new API key for the caller. The plaintext `key` is returned
+        **once** in the creation response and never again — store it
+        immediately.
+
+        **Session-auth only.** API-key management requires session
+        authentication; callers authenticated via an API key (bearer) are
+        rejected with `403`. This prevents an API key from minting further
+        keys.
+      operationId: createApiKey
+      security: [{sessionAuth: []}]  # session-only (API-key callers get 403)
+      x-identity-scoped: true  # identity-bound (caller's own keys)
+      tags:
+        - Auth
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - name
+              properties:
+                name:
+                  type: string
+                  minLength: 1
+                  maxLength: 50
+            example:
+              name: "ci-pipeline"
+      responses:
+        '201':
+          description: |
+            API key created. The plaintext `key` is shown here once and is
+            never recoverable afterwards.
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    type: boolean
+                    enum: [true]
+                  data:
+                    type: object
+                    required:
+                      - id
+                      - name
+                      - prefix
+                      - created_at
+                      - key
+                    properties:
+                      id:
+                        $ref: '#/components/schemas/UuidV7'
+                      name:
+                        type: string
+                      prefix:
+                        type: string
+                        description: Short non-secret identifier prefix for the key.
+                      created_at:
+                        type: string
+                        format: date-time
+                      key:
+                        type: string
+                        description: Plaintext API key — shown once, never returned again.
+              example:
+                success: true
+                data:
+                  id: "019539ab-1111-7000-8000-000000000010"
+                  name: "ci-pipeline"
+                  prefix: "gisl_ci"
+                  created_at: "2026-06-02T12:00:00Z"
+                  key: "gisl_ci_8f3c1d9a4b2e6f0c1a7d5e9b3c2f4a6d"
+        '400':
+          description: Request body is invalid (malformed JSON, wrong field types, or body too large).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: "Request body is invalid."
+        '401':
+          description: No authenticated principal.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: "AUTHENTICATION_REQUIRED"
+                error_type: "authentication_required"
+                message: "Authentication required."
+        '403':
+          description: |
+            The caller authenticated via an API key (bearer); key management
+            requires session authentication.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: "FORBIDDEN"
+        '422':
+          description: |
+            Discriminated `oneOf` on `error_type` (per
+            [ADR-0019](../docs/decisions/0019-auth-422-discriminated-oneof.md)):
+            - **`validation_error`** (`ValidationErrorEnvelope`, with
+              `details[]`) — structured input validation failure (e.g.
+              blank or over-long `name`).
+            - **`unprocessable_entity`** (`AuthRejectionEnvelope`, flat,
+              no `details[]`) — domain rejection: duplicate or otherwise
+              invalid key name (`error: UNPROCESSABLE_ENTITY`).
+          content:
+            application/json:
+              schema:
+                oneOf:
+                  - $ref: '#/components/schemas/ValidationErrorEnvelope'
+                  - $ref: '#/components/schemas/AuthRejectionEnvelope'
+                discriminator:
+                  propertyName: error_type
+                  mapping:
+                    validation_error: '#/components/schemas/ValidationErrorEnvelope'
+                    unprocessable_entity: '#/components/schemas/AuthRejectionEnvelope'
+              example:
+                success: false
+                error_type: validation_error
+                error: "Validation failed"
+                details:
+                  - field: "name"
+                    message: "This value should not be blank."
+        '429':
+          description: |
+            Rate limit exceeded. Carries a `Retry-After` response header.
+          headers:
+            Retry-After:
+              description: Seconds to wait before retrying. Delta-seconds (RFC 9110).
+              schema:
+                type: integer
+                minimum: 0
+              example: 60
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '500':
+          description: Internal server error.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+
+  /api/auth/api-keys/{apiKeyId}:
+    delete:
+      summary: Revoke an API key for the authenticated user
+      description: |
+        Revokes (permanently deletes) one of the caller's API keys by id.
+
+        **Session-auth only.** Like key creation, revocation requires session
+        authentication; callers authenticated via an API key (bearer) are
+        rejected with `403`. This prevents an API key from revoking other
+        keys.
+
+        **Identity-scoped.** The revoke is bound to the caller's own keys, so
+        a key id that belongs to another account is indistinguishable from a
+        non-existent one — both return `404`.
+      operationId: revokeApiKey
+      security: [{sessionAuth: []}]  # session-only (API-key callers get 403)
+      x-identity-scoped: true  # identity-bound (caller's own keys)
+      tags:
+        - Auth
+      parameters:
+        - name: apiKeyId
+          in: path
+          required: true
+          description: Identifier of the API key to revoke (from the creation response `id`).
+          schema:
+            $ref: '#/components/schemas/UuidV7'
+      responses:
+        '200':
+          description: |
+            API key revoked. The body is the shared empty-success envelope
+            (`data` is an empty object, never `null`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/EmptySuccessEnvelope'
+              example:
+                success: true
+                data: {}
+        '400':
+          description: The `apiKeyId` path segment is not a well-formed identifier.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: "INVALID_ID"
+        '401':
+          description: No authenticated principal.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: "AUTHENTICATION_REQUIRED"
+                error_type: "authentication_required"
+                message: "Authentication required."
+        '403':
+          description: |
+            The caller authenticated via an API key (bearer); key management
+            requires session authentication.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: "FORBIDDEN"
+        '404':
+          description: |
+            No API key with this id belongs to the caller — the key does not
+            exist, or it belongs to another account (identity-scoped, so the
+            two cases are indistinguishable).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: "API_KEY_NOT_FOUND"
+        '500':
+          description: Internal server error.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+
+  /api/auth/profile:
+    patch:
+      summary: Update the authenticated user's profile
+      description: |
+        Updates the caller's display name and/or email after re-verifying
+        the current password. **At least one of `name` or `email` must be
+        provided**, otherwise the request is rejected with `400`.
+
+        Changing the email does not apply it immediately — it triggers an
+        email-change confirmation flow redeemed at
+        `POST /api/auth/confirm-email-change`; the response signals this via
+        `email_change_requested`.
+
+        Note the two distinct `422` shapes: structured input validation
+        uses `ValidationErrorEnvelope`, whereas the `EMAIL_SAME` business
+        rejection (new email equals current) is a flat `ErrorEnvelope` that
+        is also a `422` but **not** the validation envelope.
+        `details[].field` values use the wire keys `current_password` /
+        `name` / `email`.
+      operationId: updateProfile
+      security: [{bearerAuth: []}, {sessionAuth: []}]  # required (authenticated principal)
+      x-identity-scoped: true  # identity-bound (caller's own profile)
+      tags:
+        - Auth
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - current_password
+              properties:
+                current_password:
+                  type: string
+                  minLength: 1
+                name:
+                  type:
+                    - string
+                    - "null"
+                  maxLength: 255
+                email:
+                  type:
+                    - string
+                    - "null"
+                  format: email
+                  maxLength: 254
+            example:
+              current_password: "s3cretpw"
+              name: "Jane Doe"
+              email: "jane.new@example.com"
+      responses:
+        '200':
+          description: |
+            Profile updated. `name_changed` and `email_change_requested`
+            flag which mutations took effect; an email change is pending
+            confirmation rather than applied.
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    type: boolean
+                    enum: [true]
+                  data:
+                    type: object
+                    required:
+                      - updated
+                    properties:
+                      updated:
+                        type: boolean
+                        enum: [true]
+                      name_changed:
+                        type: boolean
+                        enum: [true]
+                      email_change_requested:
+                        type: boolean
+                        enum: [true]
+                      message:
+                        type: string
+              example:
+                success: true
+                data:
+                  updated: true
+                  name_changed: true
+                  email_change_requested: true
+                  message: "A confirmation email has been sent to your new address."
+        '400':
+          description: |
+            No mutable field was provided — at least one of `name` or `email`
+            is required (`error: BAD_REQUEST`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: "BAD_REQUEST"
+        '401':
+          description: No authenticated principal.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: "AUTHENTICATION_REQUIRED"
+                error_type: "authentication_required"
+                message: "Authentication required."
+        '403':
+          description: |
+            The supplied `current_password` is incorrect
+            (`error: INVALID_PASSWORD`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: "INVALID_PASSWORD"
+        '404':
+          description: |
+            The authenticated principal no longer resolves to a stored user
+            (`error: USER_NOT_FOUND`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: "USER_NOT_FOUND"
+        '409':
+          description: |
+            The requested email is already claimed by another account
+            (`error: EMAIL_TAKEN`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: "EMAIL_TAKEN"
+        '422':
+          description: |
+            Structured input validation failure (`ValidationErrorEnvelope`,
+            `error_type: validation_error`).
+
+            A non-validation `422` (`error: EMAIL_SAME`, `error_type:
+            email_same`, no `details[]`) is returned when the new email
+            equals the current one — a flat `ErrorEnvelope` that is also
+            `422` but **not** the validation envelope.
+          content:
+            application/json:
+              schema:
+                oneOf:
+                  - $ref: '#/components/schemas/ValidationErrorEnvelope'
+                  - $ref: '#/components/schemas/AuthRejectionEnvelope'
+                discriminator:
+                  propertyName: error_type
+                  mapping:
+                    validation_error: '#/components/schemas/ValidationErrorEnvelope'
+                    email_same: '#/components/schemas/AuthRejectionEnvelope'
+              example:
+                success: false
+                error_type: validation_error
+                error: "Validation failed"
+                details:
+                  - field: "email"
+                    message: "This value is not a valid email address."
+        '429':
+          description: |
+            Rate limit exceeded. Carries a `Retry-After` response header.
+          headers:
+            Retry-After:
+              description: Seconds to wait before retrying. Delta-seconds (RFC 9110).
+              schema:
+                type: integer
+                minimum: 0
+              example: 60
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '500':
+          description: Internal server error.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+
+  # ============================================
+  # EXTERNAL IMPORT ENDPOINT (ticket I10)
+  # ============================================
+
+  /api/external-imports:
+    post:
+      summary: Register a one-shot external import URL
+      description: |
+        Register a one-shot bearer URL (S3 presigned / GCS signed /
+        Azure SAS / Dropbox shared link / public HTTPS) and receive an
+        opaque `external_source_id` handle. Subsequent workflows
+        reference the handle via `WorkflowSource` of `type:
+        external_import`; the original URL + password are encrypted
+        server-side and never returned in any response.
+
+        Per [ADR-0005](../docs/decisions/0005-external-sources.md) — see
+        §"SSRF posture" for the 8 validation rules applied at
+        registration time AND again at fetch time.
+
+        **Availability:** `planned` — runtime depends on cross-repo
+        ticket [`MbosYtJD`](https://trello.com/c/MbosYtJD) (Lambda team
+        publishes capability manifest) and the
+        [`POST /api/connections`](https://trello.com/c/MbosYtJD) vault
+        endpoint shipping. The contract surface ships now (contract-first
+        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
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ExternalImportRequest'
+      responses:
+        '201':
+          description: External-import handle created.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ExternalImportCreatedSuccessEnvelope'
+              example:
+                success: true
+                data:
+                  external_source_id: "019539ab-2222-7000-8000-000000000001"
+                  expires_at: "2026-04-26T15:00:00Z"
+                  provider: "s3_presigned"
+        '400':
+          description: Validation failed (missing url, malformed URI, scheme not https).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: "URL is required and must be https://"
+        '403':
+          description: |
+            Forbidden — SSRF policy violation (private IP, loopback,
+            cloud metadata endpoint), tier-quota restriction, or
+            provider not enabled for caller's tier.
+          content:
+            application/json:
+              schema:
+                oneOf:
+                  - $ref: '#/components/schemas/TierRestrictionResponse'
+                  - $ref: '#/components/schemas/FeatureTierRestrictedResponse'
+                  - $ref: '#/components/schemas/ErrorEnvelope'
+        '422':
+          description: |
+            Unprocessable URL — DNS resolution failed, target
+            unreachable, content-type / magic-byte sniff failed,
+            `expires_at` already past, or `feature_not_available`
+            (provider tagged `planned` for caller's tier).
+          content:
+            application/json:
+              schema:
+                oneOf:
+                  - $ref: '#/components/schemas/ValidationErrorEnvelope'
+                  - $ref: '#/components/schemas/FeatureNotAvailableResponse'
+                discriminator:
+                  propertyName: error_type
+                  mapping:
+                    validation_error: '#/components/schemas/ValidationErrorEnvelope'
+                    feature_not_available: '#/components/schemas/FeatureNotAvailableResponse'
+        '429':
+          description: Rate limit exceeded
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '500':
+          description: Internal server error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+
+  # ============================================
+  # AUDIO WATERMARK DECODE
+  # ============================================
+
+  /api/audio-watermark/decode:
+    post:
+      summary: Decode an embedded audio watermark
+      description: |
+        Extract the steganographic watermark embedded by a prior
+        `audio_watermark` operation (per ticket
+        [I20](https://trello.com/c/omiCq7Vn)). Pairs with the
+        `audio_watermark` operation declared in
+        `schemas/operations/audio_watermark.yaml` — the operation
+        embeds; this endpoint decodes.
+
+        **Tier-restricted.** This endpoint is `enterprise`-only. Free
+        and `pro` callers receive a 403 `feature_tier_restricted`.
+        Anonymous callers receive a 401.
+
+        **Scope: own watermarks only.** The decoder will refuse to
+        extract from media the caller did not mark themselves
+        (server-side audit log of watermark origin per
+        `watermark_id`). Per spike S11 acceptance — this avoids the
+        privacy implications of arbitrary-media decode while still
+        serving the forensic-tracking use case (find a leaked asset
+        on a third-party platform, decode the watermark, look up the
+        distribution channel that received the marked copy).
+
+        **Rate-limited.** Request rate per caller is enforced
+        independently from the workflow-create rate limit; abusive
+        decode patterns flag for audit per [ADR-0001](../docs/decisions/0001-contract-first-availability.md).
+
+        **`availability: planned`** — operation Lambda + decode
+        Lambda are cross-repo follow-up. The endpoint declaration
+        ships now (contract-first); the runtime returns
+        `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
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AudioWatermarkDecodeRequest'
+      responses:
+        '200':
+          description: Watermark successfully extracted.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AudioWatermarkDecodeResponse'
+        '401':
+          description: Authentication required (anonymous callers).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '403':
+          description: |
+            Tier insufficient (free / pro caller) — returned as
+            `FeatureTierRestrictedResponse` with
+            `error_type: feature_tier_restricted`. Per ADR-0001 §1.3.
+          content:
+            application/json:
+              schema:
+                oneOf:
+                  - $ref: '#/components/schemas/TierRestrictionResponse'
+                  - $ref: '#/components/schemas/FeatureTierRestrictedResponse'
+                discriminator:
+                  propertyName: error_type
+                  mapping:
+                    tier_restriction: '#/components/schemas/TierRestrictionResponse'
+                    feature_tier_restricted: '#/components/schemas/FeatureTierRestrictedResponse'
+        '404':
+          description: |
+            No watermark detected in the supplied asset, OR the
+            detected watermark was not issued by this caller (the
+            scope-limit applies — own-watermarks-only).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '422':
+          description: |
+            Either generic validation error
+            (`ValidationErrorEnvelope`) or the operation is `planned`
+            and the runtime Lambda has not yet shipped
+            (`FeatureNotAvailableResponse` with `error_type:
+            feature_not_available`).
+          content:
+            application/json:
+              schema:
+                oneOf:
+                  - $ref: '#/components/schemas/ValidationErrorEnvelope'
+                  - $ref: '#/components/schemas/FeatureNotAvailableResponse'
+                discriminator:
+                  propertyName: error_type
+                  mapping:
+                    validation_error: '#/components/schemas/ValidationErrorEnvelope'
+                    feature_not_available: '#/components/schemas/FeatureNotAvailableResponse'
+        '429':
+          description: |
+            Rate limit exceeded for decode requests. Decode
+            rate-limit is enforced independently from
+            workflow-create.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '500':
+          description: Internal server error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+
+  # ============================================
+  # CREDITS + BILLING ENDPOINTS (F9 — per ticket I23)
+  # ============================================
+
+  /api/v2/credits/balance:
+    get:
+      summary: Get current credit balance
       description: |
         Returns a snapshot of the caller's credit position at request
         time. Per ticket [I23 `DffjC3zm`](https://trello.com/c/DffjC3zm)
@@ -3469,6 +4630,37 @@ components:
         success:
           type: boolean
 
+    EmptyData:
+      type: object
+      additionalProperties: false
+      description: |
+        No-payload success `data` slot — always an empty object `{}`,
+        never `null`. Preserves the `{ success: true, data: {...} }`
+        envelope invariant for operations that return no body (auth
+        side-effect endpoints: register, logout, verify-email,
+        forgot-password, reset-password, change-password). Modelled as
+        an explicit empty object (not `type: null`) so every SDK
+        generator emits a clean type — a `null`-typed `data` makes
+        typescript-fetch import a non-existent `Null` model (TS2307)
+        and crashes the python openapi-generator (`getPydanticType`).
+        See ticket [VGqxO3fO](https://trello.com/c/VGqxO3fO).
+
+    EmptySuccessEnvelope:
+      type: object
+      description: |
+        Success envelope for no-payload operations. `data` is always
+        the empty object `{}`. Shared by the auth side-effect endpoints
+        so their codegen stays clean and uniform.
+      required:
+        - success
+        - data
+      properties:
+        success:
+          type: boolean
+          enum: [true]
+        data:
+          $ref: '#/components/schemas/EmptyData'
+
     ErrorEnvelope:
       type: object
       description: |
@@ -3525,6 +4717,17 @@ components:
               would exceed the S3 multipart capacity cap. Pre-S3
               server-side capacity gate; distinct from tier-quota
               rejections (`upload_size_exceeds_tier`).
+
+            Workflow-create code (per ticket
+            [`nGYbgChX`](https://trello.com/c/nGYbgChX) / sdks
+            [`DRjIyMt9`](https://trello.com/c/DRjIyMt9)):
+            - `UPLOAD_NOT_FOUND` (404) — a `POST /api/workflows` request
+              references an upload that does not exist OR exists but is
+              owned by a different identity (deliberate BOLA/IDOR
+              existence-mask: reported as not-found, **never 403**, so the
+              response does not reveal another user's upload exists).
+              `message_key: "upload.not_found"`. See the createWorkflow
+              404 response + ADR-0016 Amendment.
         message:
           type: string
           description: |
@@ -3691,6 +4894,82 @@ components:
                   `ErrorEnvelope.message_params`. Excludes cost
                   numbers.
 
+    AuthRejectionEnvelope:
+      type: object
+      description: |
+        Flat **domain-rejection** 422 envelope for the auth surface — the
+        non-validation branch of the auth-422 `oneOf` (per
+        [ADR-0019](../docs/decisions/0019-auth-422-discriminated-oneof.md),
+        the sibling adoption of [ADR-0018](../docs/decisions/0018-universal-422-error-type-discriminator.md)
+        anticipated for non-workflow `oneOf` sites). Distinct from
+        `ValidationErrorEnvelope`: it has **no `details[]`** (the
+        rejection is a single business-rule failure, not a field-by-field
+        validation report). Carries the same I26 localisation triple as
+        `ErrorEnvelope`.
+
+        Returned alongside `ValidationErrorEnvelope` on the four auth
+        endpoints that have a domain-reject 422 branch: `register`
+        (disposable/blocklisted email), `verify-email` (invalid/expired
+        token), `api-keys` POST (duplicate/invalid key name) — all
+        `error: UNPROCESSABLE_ENTITY`, `error_type: unprocessable_entity`
+        — and `profile` PATCH (`error: EMAIL_SAME`, `error_type:
+        email_same`, new email equals current).
+
+        **`error_type` vs `error`** (per ADR-0018): `error_type` is the
+        `oneOf` branch discriminator; the specific failure stays in the
+        `error` machine code. `email_same` is retained as its own
+        discriminator value (pre-existing wire shape) rather than folded
+        into `unprocessable_entity`; both map to this envelope.
+      required:
+        - success
+        - error
+        - error_type
+      properties:
+        success:
+          type: boolean
+          enum: [false]
+        error:
+          type: string
+          description: |
+            Stable machine-readable failure code. `UNPROCESSABLE_ENTITY`
+            for the generic auth domain rejections (register /
+            verify-email / api-keys); `EMAIL_SAME` for the profile
+            new-email-equals-current rejection. Canonical English; never
+            localised. See `ErrorEnvelope.error`.
+        error_type:
+          type: string
+          enum:
+            - unprocessable_entity
+            - email_same
+          description: |
+            Discriminator for the auth-422 `oneOf` (per ADR-0019). Names
+            the envelope **shape**, not the failure — the failure is in
+            `error`. `unprocessable_entity` for the generic flat auth
+            rejections; `email_same` preserved as the profile-specific
+            pre-existing wire value. Both resolve to this
+            `AuthRejectionEnvelope`. Distinct from
+            `ValidationErrorEnvelope.error_type` (`validation_error`),
+            the other branch of the auth-422 `oneOf`.
+        message:
+          type: string
+          description: |
+            Human-readable message, localised per `Accept-Language`
+            (fallback `en-GB`). Never parse for control flow. See
+            `ErrorEnvelope.message`.
+        message_key:
+          type: string
+          description: |
+            Stable canonical lookup key for the message. Never localised.
+            See `ErrorEnvelope.message_key`.
+        locale:
+          type: string
+          description: BCP 47 locale tag echoing `Content-Language`. See `ErrorEnvelope.locale`.
+          example: "en-GB"
+        message_params:
+          type: object
+          additionalProperties: true
+          description: Optional interpolation values for the localised `message`. See `ErrorEnvelope.message_params`.
+
     ReEncodeDecision:
       type: string
       description: |
@@ -3849,11 +5128,13 @@ components:
         — 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).
+        All five role-based ops now declare `per_role_cardinality`
+        (audio_to_video, video_watermark, audio_overlay,
+        image_watermark, custom_luma — the last three migrated from
+        prose-only by ticket oAP5BQOx). Absence of the block keeps
+        prose-only semantics for any future role-based op until it
+        migrates to the predicate form; the `JobInputRole` description
+        remains the human-readable companion to the rules.
 
         Per ticket [`SlluxMBN`](https://trello.com/c/SlluxMBN) /
         ADR-0015. Consumed by `OperationInputRoleValidator` in
@@ -3892,8 +5173,10 @@ components:
     # ============================================
     #
     # Per ADR-0005. WorkflowSource is the discriminated union consumed
-    # by V2 JobDefinition.source / JobInputV2.source (wired by I12).
-    # ExternalDestination is the write-side counterpart.
+    # by V2 single-input JobDefinition.source (wired by I12). Multi-input
+    # JobInputV2.source consumes the narrower MultiInputSource (excludes
+    # the upload leaf; see MultiInputSource). ExternalDestination is the
+    # write-side counterpart.
 
     UploadSource:
       type: object
@@ -3985,8 +5268,11 @@ components:
 
     WorkflowSource:
       description: |
-        Discriminated union of source leaves consumed by V2
-        `JobDefinition.source` and `JobInputV2.source`. Per
+        Discriminated union of source leaves (all 4, including
+        `upload`) consumed by V2 single-input `JobDefinition.source`.
+        Multi-input `JobInputV2.source` consumes the narrower
+        `MultiInputSource` (this union minus the `upload` leaf) — see
+        that schema and `JobInputV2`. Per
         [ADR-0005](../docs/decisions/0005-external-sources.md) +
         [ADR-0004](../docs/decisions/0004-job-shape.md).
 
@@ -4005,6 +5291,30 @@ components:
           external_import: '#/components/schemas/ExternalImportToken'
           connection: '#/components/schemas/ConnectionSource'
 
+    MultiInputSource:
+      description: |
+        Discriminated union of source leaves consumed by `JobInputV2.source`
+        (multi-input operation inputs). A 3-leaf subset of `WorkflowSource`
+        that **excludes the `upload` leaf** — uploads cannot be referenced
+        directly inside a multi-input `inputs[]` array. An uploaded file
+        that must feed a multi-input operation enters via a `passthrough`
+        source job (a single-input job with `operations: [{type: passthrough}]`)
+        and is referenced here as `{ type: job_output, from: <id> }`, which
+        preserves billing / DAG / lineage. Structured like the `ExternalSource`
+        subset alias but retaining `job_output` (the passthrough bridge).
+        Per ticket [`4som89Uh`](https://trello.com/c/4som89Uh) + ADR-0004 /
+        ADR-0005.
+      oneOf:
+        - $ref: '#/components/schemas/JobOutputSource'
+        - $ref: '#/components/schemas/ExternalImportToken'
+        - $ref: '#/components/schemas/ConnectionSource'
+      discriminator:
+        propertyName: type
+        mapping:
+          job_output: '#/components/schemas/JobOutputSource'
+          external_import: '#/components/schemas/ExternalImportToken'
+          connection: '#/components/schemas/ConnectionSource'
+
     ExternalSource:
       description: |
         Subset alias of `WorkflowSource` that excludes uploads and
@@ -4324,6 +5634,7 @@ components:
 
     CreditsBalanceSuccessEnvelope:
       type: object
+      additionalProperties: false
       required:
         - success
         - data
@@ -4494,6 +5805,7 @@ components:
 
     CreditsUsageSuccessEnvelope:
       type: object
+      additionalProperties: false
       required:
         - success
         - data
@@ -4651,6 +5963,7 @@ components:
 
     WorkflowCancelSuccessEnvelope:
       type: object
+      additionalProperties: false
       required:
         - success
         - data
@@ -4686,6 +5999,7 @@ components:
 
     WorkflowResumeSuccessEnvelope:
       type: object
+      additionalProperties: false
       required:
         - success
         - data
@@ -5595,7 +6909,7 @@ components:
         - thumbnail_office: Office document (DOCX/XLSX/PPTX/ODT/ODS/ODP)
           thumbnail sub-type. Backed by a dedicated LibreOffice Lambda.
           Emitted by the publisher for office-document inputs.
-        - 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).
+        - image_watermark: Image overlay onto a base IMAGE asset. Multi-input (Path B with role: base + overlay). Each input is a `MultiInputSource` (external_import / connection / job_output — no upload-direct); an uploaded base or overlay enters via a `passthrough` source job referenced by `job_output`. 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.
@@ -5606,7 +6920,8 @@ components:
         - 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: beta` (Wave A — Lambda backend live; opt-in, MUST NOT return `feature_not_available`; may change with notice). 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: beta` (Wave A — Lambda backend live; opt-in, MUST NOT 422; `short_form` is beta, `long_form` stays `planned` — no live Fargate worker; `multi_overlay_stack` stays `planned`). 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: beta` for the `audio` mime_group (worker live on staging — shape-stable + opt-in, MUST NOT 422); the `image_gif`, `document_pdf`, and `video` mime_groups stay `availability: planned` and dispatch returns `feature_not_available` (422) until their workers ship. Per ticket [`vKI0CFDu`](https://trello.com/c/vKI0CFDu) + ADR-0014.
+        - 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: beta` for the `audio` and `video` mime_groups (workers live on staging — shape-stable + opt-in, MUST NOT 422); video activates BOTH classes (`video.processing_class.short_form: beta` AND `long_form: beta` — `split-video-fargate` proven on staging per [`rcwvUKhI`](https://trello.com/c/rcwvUKhI)). The `image_gif` and `document_pdf` mime_groups stay `availability: planned` and dispatch returns `feature_not_available` (422) until their workers ship. Per ticket [`vKI0CFDu`](https://trello.com/c/vKI0CFDu) + ADR-0014.
+        - passthrough: Inert lossless source operation. A single-input source job whose SOLE operation is `passthrough` emits its source bytes UNCHANGED — no compression, no Lambda. The API self-completes the job at publish (terminal output = the upload `{bucket, key}` unchanged). Its purpose is to feed an uploaded file into a multi-input operation LOSSLESSLY: because `JobInputV2.source` is narrowed to exclude upload-direct, an upload that must enter a `merge` / `archive` / `image_watermark` op enters via a `passthrough` source job referenced downstream by `{type: job_output, from: <id>}` — preserving billing / DAG / lineage. Distinct from `operations: []` (which keeps its implicit-compress meaning on a single-input upload job); `passthrough` is the EXPLICIT lossless path via the "non-empty `operations[]` without `compress` = compression opt-out" rule. Media-agnostic; no options. `availability: beta` — activated (the inputs[]-narrowing + passthrough self-complete mechanism is deployed API-side); workflow-create accepts `passthrough` source jobs and MUST NOT return `feature_not_available`. **Never published to SNS** — deliberately absent from the AsyncAPI routing enums (API self-completes; no `ops-passthrough` queue). Per ticket [`4som89Uh`](https://trello.com/c/4som89Uh) + ADR-0004 (planned→beta flip).
 
         Both the legacy `thumbnail` value and the four sub-type values
         are valid routing targets today during the thumbnail migration
@@ -5625,6 +6940,7 @@ components:
         - thumbnail_office
         - image_watermark
         - text_watermark
+        - render_variants
         - merge
         - archive
         - convert
@@ -5635,6 +6951,7 @@ components:
         - video_watermark
         - video_text_watermark
         - split
+        - passthrough
 
     OperationInputModel:
       type: string
@@ -5643,7 +6960,7 @@ components:
         - single: One input file (compress, thumbnail, thumbnail_image,
           thumbnail_video, thumbnail_document, thumbnail_office,
           text_watermark, convert, audio_watermark,
-          video_text_watermark, split)
+          video_text_watermark, split, passthrough)
         - 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
@@ -5811,6 +7128,7 @@ components:
 
     UploadSuccessEnvelope:
       type: object
+      additionalProperties: false
       required:
         - success
         - data
@@ -6423,6 +7741,7 @@ components:
 
     MetadataSuccessEnvelope:
       type: object
+      additionalProperties: false
       required:
         - success
         - data
@@ -6439,15 +7758,82 @@ components:
 
     WorkflowCreateRequest:
       type: object
-      required:
-        - jobs
+      description: |
+        Create a workflow. **Two mutually-exclusive request forms:**
+
+        - **Explicit jobs** — `jobs[]` (+ optional `workflow_edges`), the
+          full multi-job DAG form. Use for multi-job workflows, role-based
+          / multi-input operations, output-as-role-input chains, explicit
+          edges, or `delivery.selection.type: explicit`.
+        - **Flat (single-job sugar)** — top-level `source` + `operations[]`,
+          **exactly equivalent to `jobs: [{ source, operations }]`** (per
+          ticket [`D0Gsri8V`](https://trello.com/c/D0Gsri8V)). The server
+          lowers it into one `JobDefinition` and validates it as such —
+          inheriting every `JobDefinition` guard verbatim — then runs the
+          existing single-job canonicalizer. For the file-first
+          dump-and-go case: one input + a set of single-input operations
+          (a chain plus `base`-derived branches like thumbnail / split).
+
+        The two forms are mutually exclusive (a request supplies exactly
+        one — enforced by the `oneOf` below); they are NOT combined.
+
+        Because the flat form lowers to ONE single-input job, its
+        `operations[]` admits only **single-input** operation types. The
+        multi-input / role operations (`merge`, `archive`,
+        `image_watermark`, `custom_luma`, `audio_overlay`,
+        `audio_to_video`, `video_watermark` — the enum at the
+        `JobDefinition` multi-input guard) require `inputs[]` and MUST use
+        the explicit `jobs[]` form; the server rejects them in flat mode
+        via that same `JobDefinition` guard after lowering (not a
+        separate structural rule). The flat form also does **not** support
+        `workflow_edges` or `delivery.selection.type: explicit` — both
+        need a named job id the single implicit job has none of; use
+        explicit `jobs[]` for those. Delivery defaults and selection
+        otherwise behave exactly as for one explicit job.
+      oneOf:
+        - title: Explicit jobs form
+          required: [jobs]
+          not:
+            anyOf:
+              - required: [source]
+              - required: [operations]
+        - title: Flat single-job form
+          required: [source, operations]
+          not:
+            anyOf:
+              - required: [jobs]
+              - required: [workflow_edges]
       properties:
         jobs:
           type: array
-          description: List of jobs in this workflow
+          description: |
+            List of jobs in this workflow (the explicit-jobs form).
+            Mutually exclusive with the flat `source` + `operations`
+            form — supply exactly one.
           minItems: 1
           items:
             $ref: '#/components/schemas/JobDefinition'
+        source:
+          $ref: '#/components/schemas/WorkflowSource'
+          description: |
+            Flat-form single input source. Present only in the flat form
+            (with `operations`); equivalent to a single explicit job's
+            `source`. Single-input `WorkflowSource` (4-leaf union incl.
+            `upload`) — multi-input role-based jobs use explicit
+            `jobs[].inputs[]`. See the schema description for the
+            flat/explicit mutex.
+        operations:
+          type: array
+          minItems: 1
+          description: |
+            Flat-form operation set (the unordered operations applied to
+            the top-level `source`). Present only in the flat form (with
+            `source`); equivalent to a single explicit job's
+            `operations[]` and lowered + canonicalized identically.
+            Single-input operation types only (see the schema
+            description). Each entry is an `OperationDefinition`.
+          items:
+            $ref: '#/components/schemas/OperationDefinition'
         workflow_edges:
           type: array
           description: |
@@ -6596,7 +7982,10 @@ components:
             Multi-input list for `merge`, `archive`, `image_watermark`,
             `custom_luma`, `audio_overlay`, `audio_to_video`, and
             `video_watermark`. Each
-            entry is a `JobInputV2` with its own `WorkflowSource`.
+            entry is a `JobInputV2` with its own `MultiInputSource` (the
+            3-leaf subset of `WorkflowSource` that excludes upload-direct;
+            uploads enter via a `passthrough` source job referenced by
+            `job_output`).
             Mutually exclusive with `source` — the V2 shape boundary
             stays `source` (single-input) XOR `inputs[]` (multi-input
             role-based) per ADR-0004 / I12.
@@ -6615,10 +8004,23 @@ components:
         operations:
           type: array
           description: |
-            Ordered list of operations. Executed sequentially — each
+            Unordered **set** of operations for this job. The API
+            canonicalizes them to a deterministic order — submitted order
+            does not affect the result (same set, any order → same plan →
+            same bytes). The resolved canonical order is echoed in the
+            response `composition_plan` (see
+            `WorkflowCreateResponse.composition_plan`). Each canonical chain
             operation consumes the previous operation's output; all
             intermediate and final outputs are kept.
 
+            Order-independence is over a *well-formed* set: conflicting or
+            duplicate same-stage operations (e.g. two `compress` with
+            different options) are resolved or rejected by the
+            canonicalization engine — the contract does not enumerate the
+            conflict-resolution rules (engine-side, like the opaque
+            processing-time estimator). A rejected set surfaces as a
+            `validation_error` (422); it is not silently ordered.
+
             Multi-input jobs (with `inputs[]`) must have exactly one
             operation, and it must be a multi-input type (`merge`,
             `archive`, `image_watermark`, `custom_luma`,
@@ -6669,21 +8071,66 @@ components:
               via Wave A [`c3uthIP4`](https://trello.com/c/c3uthIP4) —
               `availability: beta`, backends live). The multi-input
               shape is contract-defined for all entries.
+        - if:
+            properties:
+              operations:
+                contains:
+                  type: object
+                  properties:
+                    type:
+                      const: passthrough
+                  required: [type]
+            required: [operations]
+          then:
+            properties:
+              operations:
+                minItems: 1
+                maxItems: 1
+                items:
+                  properties:
+                    type:
+                      const: passthrough
+              source:
+                properties:
+                  type:
+                    const: upload
+                required: [type]
+            required: [source]
+            description: |
+              `passthrough` constraint. A `passthrough` operation MUST be
+              the SOLE operation of a SINGLE-INPUT job whose `source.type`
+              is `upload` (i.e. `operations: [{type: passthrough}]` with
+              `source: {type: upload, ...}`): never chained with another
+              operation, never on `inputs[]`, never on a non-`upload`
+              source. `passthrough` is an inert lossless bridge that the
+              API self-completes at publish with the upload's `{bucket,
+              key}` as the job output (see the `passthrough` bullet under
+              `OperationType` and the `POST /api/workflows` description),
+              so it is meaningful only for an uploaded source feeding a
+              downstream multi-input op via `job_output`. The shared
+              `OperationType` enum makes `passthrough` syntactically
+              expressible elsewhere; this guard makes those uses
+              schema-invalid rather than deferring rejection to the
+              backend.
 
     JobInputV2:
       type: object
       description: |
         V2 multi-input entry per [ADR-0004](../docs/decisions/0004-job-shape.md)
         §"JobInputV2". Replaces V1 `JobInput`. Each entry carries its own
-        `source` (a `WorkflowSource` value — same union used at
-        `JobDefinition.source`), so multi-input jobs can mix uploads,
-        external imports, vault connections, and upstream job outputs
-        within a single inputs[] array.
+        `source` (a `MultiInputSource` value — the 3-leaf subset of
+        `WorkflowSource` that **excludes upload-direct**), so multi-input
+        jobs can mix external imports, vault connections, and upstream job
+        outputs within a single inputs[] array. An uploaded file enters a
+        multi-input op via a `passthrough` source job (single-input,
+        `operations: [{type: passthrough}]`) referenced here as
+        `{ type: job_output, from: <id> }` — not as a direct `upload`
+        source (per ticket [`4som89Uh`](https://trello.com/c/4som89Uh)).
       required:
         - source
       properties:
         source:
-          $ref: '#/components/schemas/WorkflowSource'
+          $ref: '#/components/schemas/MultiInputSource'
         role:
           type: string
           description: |
@@ -6757,6 +8204,24 @@ components:
             rules. For example, `quality` is only valid when `mode: lossy` for
             compress operations.
           additionalProperties: true
+        base:
+          type: string
+          enum:
+            - processed_base
+            - original
+          default: processed_base
+          description: |
+            For **derived artifacts** (`thumbnail`, `split`): which canonical
+            composition node this artifact branches from. Symbolic-only for
+            v1 (no per-operation references — caller-visible op ids do not
+            exist at submit time).
+            - `processed_base` (default): the fully-processed base —
+              post-everything, so the artifact carries the watermark + encode.
+            - `original`: the untouched source file.
+            Ignored for chain operations (compress, convert, watermark, merge,
+            audio). The resolved branch point is echoed as
+            `CompositionPlanOperation.derived_from` (a `node_id`) in
+            `composition_plan`. See the operation-composition model.
 
     # ============================================
     # WORKFLOW DELIVERY (ticket I8-CONS)
@@ -6787,6 +8252,13 @@ components:
             Optional operation type filter when the job has multiple
             operations. Omit to select the last operation's output.
 
+            **`availability: planned`** — per-operation-output grain is
+            not yet honoured: the API currently rejects a non-empty
+            `operation` filter with `feature_not_available` (422), even
+            though `delivery.selection` `all_outputs`/`explicit` are
+            `stable` at JOB grain (per `cse3wt2s` / T5b). Deferred to a
+            follow-up; omit it (job-grain selection) for now.
+
     DeliverySelection:
       type: object
       description: |
@@ -6802,8 +8274,10 @@ components:
             Selection strategy:
             - `terminal` (default): bundle all jobs with no outgoing
               edges (computed from `JobOutputSource.from` references).
-            - `all_outputs`: bundle every operation output in the
-              workflow, including intermediates.
+            - `all_outputs`: bundle every **job's** output in the
+              workflow, including intermediates (job-grain). Per-operation
+              output selection within a job is NOT yet available — see the
+              `DeliveryOutputRef.operation` filter (`planned`).
             - `explicit`: bundle only the refs listed in `refs[]`.
               Mutually exclusive with per-job `JobDefinition.deliver: true`
               (validator rejects 422 if both are present).
@@ -6813,19 +8287,21 @@ components:
             - explicit
           per_value_availability:
             terminal:    { availability: stable }
-            all_outputs: { availability: planned }
-            explicit:    { availability: planned }
-          # Availability flipped beta → planned per ticket
-          # [`co0CERtJ`](https://trello.com/c/co0CERtJ) — the API
-          # runtime currently 422s every non-default `selection.type`
-          # with `feature_not_available`, which per the
-          # `info.description` availability taxonomy IS the `planned`
-          # behaviour (`stable`/`beta` MUST NOT 422). When the API
-          # threads the request-level `delivery.selection` shape, this
-          # flips back. Terminal stays `stable` because the runtime
-          # honours it as the implicit default (`DeliveryPlanComputer`
-          # computes terminal selection regardless of whether the
-          # caller supplied a `delivery` block).
+            all_outputs: { availability: stable }
+            explicit:    { availability: stable }
+          # Availability flipped planned → stable per ticket
+          # [`cse3wt2s`](https://trello.com/c/cse3wt2s) (T5b delivery-
+          # selection go-live, co-land with API PR #365). The two-gate
+          # flip: co0CERtJ downgraded these to `planned` to match the
+          # runtime, which 422'd every non-default `selection.type`; the
+          # API now ACCEPTS `all_outputs`/`explicit` at JOB grain
+          # (`DeliveryPlanComputer` threads the request-level
+          # `delivery.selection`), so the contract flips back to `stable`.
+          # The `all_outputs` claim is narrowed to job-grain to stay
+          # conformant; per-operation-output grain + the
+          # `DeliveryOutputRef.operation` filter stay `planned` (the API
+          # still 422s the operation filter — deferred follow-up). Terminal
+          # stays `stable` (the implicit default).
         refs:
           type: array
           description: |
@@ -6953,6 +8429,18 @@ components:
           description: |
             Set when `reason: consumed_by`. The id of the downstream
             job that consumes this output.
+        node_id:
+          type: string
+          description: |
+            Symbolic composition `node_id` correlating this delivered output
+            to its canonical node in `composition_plan` (e.g. `encode`,
+            `thumbnail`, `processed_base`). Lets consumers label and group
+            delivered files by composition role. **Optional** — emitted once
+            the canonicalization engine is live (optional-then-promote,
+            mirroring `composition_plan`); absent until then. This is the
+            additive carrier; the normative
+            `/downloads == delivery_plan.outputs[]` rendezvous invariant is
+            introduced with the delivery-selection promotion, not here.
 
     DeliveryPlan:
       type: object
@@ -7211,6 +8699,205 @@ components:
         class_hint:
           $ref: '#/components/schemas/ProcessingClassHint'
 
+    # ============================================
+    # CANONICAL COMPOSITION PLAN (operation-composition epic)
+    # ============================================
+    # Response-side single source of truth for operation composition.
+    # The API accepts an unordered operation SET (per source) and
+    # canonicalizes it to a deterministic DAG; this plan exposes the
+    # resolved order, per-op chain group/position, derived-artifact
+    # lineage, and image-encode capabilities so FE + SDK read the model
+    # instead of hardcoding it. Additive-first: these schemas ship OPEN
+    # (no `additionalProperties: false`, no `allOf`) — flat objects to
+    # avoid the inherited-field-closure footgun, and OPEN so the
+    # canonicalization engine (later epic phases) can add correlation
+    # fields before a separate tightening cut. All correlation fields
+    # (`node_id`, `operation_id`, `requested_operations`, capability
+    # keys) are pinned now so the eventual `additionalProperties: false`
+    # cut has nothing to break.
+
+    CompositionPlan:
+      type: object
+      description: |
+        Canonical composition plan for a workflow — emitted on
+        `WorkflowCreateResponse.composition_plan`. Tells callers the
+        deterministic order the submitted operation set resolved to, the
+        per-operation chain group/position, derived-artifact lineage, and
+        the image-encode capabilities that gate format/quality choices.
+
+        `canonical_order` is the informational pipeline spine; per-op
+        detail lives on each `CompositionPlanOperation`.
+      required:
+        - canonical_order
+        - jobs
+        - capabilities
+      properties:
+        canonical_order:
+          type: array
+          description: |
+            The canonical pipeline spine (single mutated stream), as an
+            ordered list of `chain_group` stage names. The known image/AV
+            spine is `merge` (fan-in) → `image_watermark` → `text_watermark`
+            → `audio` → `encode` (terminal: convert+compress folded) →
+            `derived` (fan-out: thumbnail/split). Informational — read per-op
+            `chain_group` / `chain_position` for placement. The geometry
+            stage is intentionally not exposed as a node for v1 (image
+            resize/fit live inside the thumbnail node).
+
+            **Open string, NOT a fixed enum** (mirrors
+            `ProcessingPlanJob.execution_pool`): the canonical model still
+            covers operation classes not in the image-pipeline spine
+            (`archive`, `passthrough`, `audio_to_video`, …) and the engine's
+            final stage taxonomy is pinned alongside the canonicalization
+            engine (later epic phases). The values are tightened to an enum
+            in the same gated cut that adds `additionalProperties: false`,
+            once the engine emits the complete set. Consumers MUST treat
+            unknown stage names as forward-compatible.
+          items:
+            type: string
+        jobs:
+          type: array
+          description: Per-job canonical composition. Empty `[]` is permitted.
+          items:
+            $ref: '#/components/schemas/CompositionPlanJob'
+        capabilities:
+          $ref: '#/components/schemas/ImageEncodeCapabilities'
+
+    CompositionPlanJob:
+      type: object
+      description: Per-job entry in a `CompositionPlan` — the canonical operations for one job.
+      required:
+        - job_id
+        - operations
+      properties:
+        job_id:
+          $ref: '#/components/schemas/UuidV7'
+        operations:
+          type: array
+          description: The job's operations in canonical (resolved) order.
+          items:
+            $ref: '#/components/schemas/CompositionPlanOperation'
+
+    CompositionPlanOperation:
+      type: object
+      description: |
+        The canonical view of one operation within a job — its symbolic
+        composition node, resolved chain placement, and (for derived
+        artifacts) the node it branches from.
+      required:
+        - node_id
+        - type
+        - chain_group
+        - chain_position
+      properties:
+        node_id:
+          type: string
+          description: |
+            Stable **symbolic** canonical node id (e.g. `original`,
+            `processed_base`, `encode`, `thumbnail`). The correlation key
+            used by `derived_from`, `DeliveryPlanOutput.node_id`, and
+            `OperationDownload.node_id` to tie delivered files back to a
+            canonical node. **NOT** the operation UUID. (SSE stays
+            per-operation by design — it is not a delivery-plan projection
+            and does not carry `node_id`.)
+          example: encode
+        operation_id:
+          $ref: '#/components/schemas/UuidV7'
+        type:
+          $ref: '#/components/schemas/OperationType'
+          description: |
+            The canonical operation type of this node. For the folded
+            terminal `encode` node (`chain_group: encode`) this is the
+            encode operation `compress` — `convert` folds INTO it (a single
+            terminal encode, never a double-encode), and the folded source
+            operations are listed in `requested_operations`. For all other
+            nodes `type` is the operation as submitted.
+        chain_group:
+          type: string
+          description: |
+            Which canonical stage this operation belongs to. **Open string,
+            NOT a fixed enum** (mirrors `ProcessingPlanJob.execution_pool`) —
+            the stage taxonomy is pinned alongside the canonicalization
+            engine and tightened to an enum in the same gated cut that adds
+            `additionalProperties: false`; consumers MUST treat unknown
+            stage names as forward-compatible. The watermark stages are
+            **media-agnostic overlay stages**, not image-only. Known stages:
+            - `merge`: fan-in.
+            - `image_watermark`: raster/image-overlay watermark stage —
+              covers the `image_watermark` AND `video_watermark` operation
+              types.
+            - `text_watermark`: text-overlay watermark stage — covers the
+              `text_watermark` AND `video_text_watermark` operation types.
+            - `audio`: audio operations (e.g. `audio_overlay`,
+              `audio_to_video`).
+            - `encode`: the folded convert+compress terminal encode stage.
+            - `derived`: fan-out artifact (`thumbnail` / `split`).
+            Operation classes outside the image/AV spine (e.g. `archive`
+            bundling, `passthrough` bridge jobs) carry their own stage names
+            once the engine pins them. (The geometry/resize stage is not
+            exposed as a node for v1 — image resize lives inside the
+            `thumbnail` worker.)
+        chain_position:
+          type: integer
+          minimum: 0
+          description: Deterministic resolved position within the canonical chain.
+        derived_from:
+          type: string
+          description: |
+            Set only for derived operations (`thumbnail`, `split`): the
+            `node_id` this artifact branches from (symbolic; resolved from
+            the request-side `OperationDefinition.base`). Absent for chain
+            operations.
+          example: processed_base
+        requested_operations:
+          type: array
+          description: |
+            Image-fold audit trail: the request operation types that were
+            absorbed into this single canonical node. For the folded
+            `encode` node this is e.g. `[convert, compress]` — the caller
+            still submits both, but composition exposes ONE `encode` node
+            (no false double-encode). Absent when no fold occurred.
+          items:
+            $ref: '#/components/schemas/OperationType'
+
+    ImageEncodeCapabilities:
+      type: object
+      description: |
+        Image-encode-stage capability flags that gate format/quality
+        choices for the canonical `encode` node. **Image-encode-scoped**
+        — these caveats apply to the image encode pass only, not to
+        video / audio / document encoding. Surfaced so FE/SDK do not
+        promise capabilities the worker cannot honour (e.g. a WebP
+        quality slider the convert path silently ignores).
+      required:
+        - webp_quality_supported
+        - background_flatten
+      properties:
+        webp_quality_supported:
+          type: boolean
+          description: |
+            Whether quality-controlled (lossy) WebP encode is available.
+            `false` today: WebP via the convert/encode path is
+            lossless-only and the `quality` option is silently ignored
+            (quality-controlled WebP is only reachable via `compress`).
+            Consumers MUST NOT offer a WebP quality control when this is
+            `false`.
+          example: false
+        background_flatten:
+          type: string
+          description: |
+            Whether alpha→non-alpha background flattening is available at
+            encode time. `conditional` today: flatten fires only when an
+            alpha source is encoded to a non-alpha output (e.g. PNG→JPEG).
+            - `unsupported`: never applied.
+            - `conditional`: applied only on alpha→non-alpha transitions.
+            - `supported`: always available.
+          enum:
+            - unsupported
+            - conditional
+            - supported
+          example: conditional
+
     # ============================================
     # UPLOAD PREFLIGHT PROBE (per ticket I28)
     # ============================================
@@ -7416,6 +9103,7 @@ components:
 
     UploadProbeSuccessEnvelope:
       type: object
+      additionalProperties: false
       description: |
         Success envelope wrapping `UploadProbeResponse` on
         `POST /api/uploads/{id}/probe` 200 responses, per ticket
@@ -7603,6 +9291,24 @@ components:
             frontend can preview routing decisions before the
             workflow runs. Estimation algorithm is server-side and
             deliberately opaque per plan v5 §F8.2.
+        composition_plan:
+          $ref: '#/components/schemas/CompositionPlan'
+          description: |
+            Server-computed canonical composition plan — the single
+            source of truth for how the submitted operation **set** was
+            canonicalized into a deterministic DAG (canonical order,
+            per-op chain group/position, derived-artifact lineage, and
+            image-encode capabilities). Frontend + SDK read this instead
+            of hardcoding the pipeline order (which today lives only in
+            the API), so click-order never changes the result.
+
+            **OPTIONAL (optional-then-promote).** The canonicalization
+            engine that emits it ships in later phases of the
+            operation-composition epic; until it is live the server omits
+            this field rather than emitting a partial plan. Promoted to
+            required once the engine emits reliably (the same
+            optional-then-promote path `delivery_plan` / `processing_plan`
+            took). Consumers MUST treat it as may-be-absent.
         warnings:
           type: array
           description: |
@@ -7640,6 +9346,7 @@ components:
 
     WorkflowCreateSuccessEnvelope:
       type: object
+      additionalProperties: false
       required:
         - success
         - data
@@ -7691,9 +9398,25 @@ components:
             (per ticket [I24](https://trello.com/c/e50uXLcl)). Carries
             `paused_at`, `expires_at`, `required_action`, and
             actionable `links` (resume / top_up / upgrade).
+        composition_plan:
+          $ref: '#/components/schemas/CompositionPlan'
+          description: |
+            Server-computed canonical composition plan, echoed on the
+            status read so a frontend reload / resume can re-derive the
+            canonicalized DAG (canonical order, per-op chain
+            group/position, derived-artifact lineage, image-encode
+            capabilities) without re-submitting. Identical shape and
+            semantics to `WorkflowCreateResponse.composition_plan`.
+
+            **OPTIONAL (optional-then-promote).** The canonicalization
+            engine that emits it ships in later phases of the
+            operation-composition epic; the server omits the field until
+            it is live (mirroring the create side). Per ticket
+            [`RrxdUBGZ`](https://trello.com/c/RrxdUBGZ) / `i2J8AMy6`.
 
     WorkflowStatusSuccessEnvelope:
       type: object
+      additionalProperties: false
       required:
         - success
         - data
@@ -7704,6 +9427,118 @@ components:
         data:
           $ref: '#/components/schemas/WorkflowStatusResponse'
 
+    JobMediaClass:
+      type: string
+      description: |
+        The media class of a job (the kind of media it processes), distinct
+        from an operation's step `type` (`convert` / `compress` / …). `mixed`
+        is a multi-input job spanning more than one class (e.g. an archive or
+        a merge of heterogeneous inputs). Used in the lightweight workflows
+        list row so a UI can label/group rows by media without drilling into
+        per-operation detail.
+      enum:
+        - image
+        - video
+        - audio
+        - document
+        - mixed
+
+    WorkflowSummaryJob:
+      type: object
+      description: |
+        Minimal per-job entry in a `WorkflowSummary` row — `job_type` (media
+        class) + status for list rendering. Per-operation detail (op step
+        types, `result_metadata`) is the drill-in
+        `GET /api/workflows/{id}/status`; outputs are
+        `GET /api/workflows/{id}/downloads`.
+      required:
+        - job_id
+        - ref
+        - job_type
+        - status
+      properties:
+        job_id:
+          $ref: '#/components/schemas/UuidV7'
+        ref:
+          type: string
+          description: Workflow-local job ref (matches `JobResponse.ref`).
+        job_type:
+          $ref: '#/components/schemas/JobMediaClass'
+        status:
+          $ref: '#/components/schemas/JobStatus'
+
+    WorkflowSummary:
+      type: object
+      description: |
+        Lightweight summary row for `GET /api/workflows` (list). Carries
+        just enough for a list view — id / status / created_at + per-job
+        `{ ref, job_type (media class), status }` — and deliberately does
+        NOT inline per-operation detail, `result_metadata`, output counts,
+        or download URLs (those are the drill-in `GET /{id}/status` +
+        `GET /{id}/downloads` reads; keeping rows lean avoids N×M×K payload
+        blow-up). Field naming mirrors `WorkflowStatusResponse`
+        (`workflow_id`, snake_case).
+      required:
+        - workflow_id
+        - status
+        - created_at
+        - jobs
+      properties:
+        workflow_id:
+          $ref: '#/components/schemas/UuidV7'
+        status:
+          $ref: '#/components/schemas/WorkflowStatus'
+        created_at:
+          type: string
+          format: date-time
+          description: ISO-8601 workflow-creation timestamp (the list sort key, DESC).
+        jobs:
+          type: array
+          items:
+            $ref: '#/components/schemas/WorkflowSummaryJob'
+
+    WorkflowListResponse:
+      type: object
+      description: |
+        Cursor-paginated page of workflow summaries (most-recent-first).
+        Walk pages by passing `next_cursor` as the next request's `cursor`
+        query parameter until `is_truncated: false`. Cursor pagination
+        (opaque `(created_at, id)` token) mirrors the multipart-parts
+        listing convention — NOT the offset-based `/api/v2/credits/usage`.
+      required:
+        - workflows
+        - is_truncated
+      properties:
+        workflows:
+          type: array
+          description: This page of workflow summary rows (most-recent-first).
+          items:
+            $ref: '#/components/schemas/WorkflowSummary'
+        next_cursor:
+          description: |
+            Opaque cursor — pass as the next request's `cursor` query
+            parameter to fetch the following page. `null` on the final page
+            (or when `is_truncated: false`). Treat as opaque; do not parse.
+          oneOf:
+            - type: string
+            - type: 'null'
+        is_truncated:
+          type: boolean
+          description: '`true` when more pages remain; `false` on the final page.'
+
+    WorkflowListSuccessEnvelope:
+      type: object
+      additionalProperties: false
+      required:
+        - success
+        - data
+      properties:
+        success:
+          type: boolean
+          enum: [true]
+        data:
+          $ref: '#/components/schemas/WorkflowListResponse'
+
     JobResponse:
       type: object
       description: Job status within a workflow response
@@ -7771,6 +9606,18 @@ components:
           description: Progress percentage (0-100). Present when in_progress or completed.
         result:
           $ref: '#/components/schemas/OperationResult'
+        result_metadata:
+          $ref: '#/components/schemas/OperationResultMetadata'
+          description: |
+            Whitelisted operation-level metadata (the read projection — what
+            `GET /api/workflows/{id}/status` emits per operation). Optional;
+            present once an operation produces a whitelisted key. Distinct
+            from `result` (the deliverable output): this carries small
+            per-operation metadata, not the file. The `/status` read carries
+            ONLY this `result_metadata` for op-level detail — the output
+            `result` (`download_url`/`size_bytes`) is read via
+            `GET /api/workflows/{id}/downloads` per the rmP7ndhK/ZjVXHkYK
+            narrowing. Per ticket `dw048NKk` (A2) / `EurbZLMH` (B1).
         error_code:
           type: string
           description: |
@@ -7787,6 +9634,32 @@ components:
             absent otherwise. Mirrors `SseOperationFailedData.error_message`.
           example: "output_too_large: Output (12156489 bytes) is not smaller than input (6187609 bytes)"
 
+    OperationResultMetadata:
+      type: object
+      additionalProperties: false
+      description: |
+        Whitelisted, named operation-level result metadata — a **CLOSED**
+        set of declared keys. The API serves ONLY these declared keys (a
+        whitelist projection), never the raw stored metadata bag, so internal
+        diagnostics never leak. New keys are **additive named cuts** (the
+        `additionalProperties: false` closure is the point — an unmodelled
+        key is a coordinated contract change, not a silent rollout). Twin of
+        the AsyncAPI `OperationResultMetadata` (wire ↔ read parity). Distinct
+        from `OperationResult` (the deliverable output file): this carries
+        small per-operation metadata, not the output. Per `EurbZLMH` (B1).
+      properties:
+        watermark_id:
+          type: string
+          format: uuid
+          description: |
+            UUIDv7 of the watermark embedded by an `audio_watermark`
+            operation (for later decode/verify). **Display-only / not yet
+            populated** — gated on the audio_watermark Lambda (`EvPl5fkH`,
+            B3) + the watermark registry (B2, deferred). The field +
+            whitelist ship now (additive) so the result_metadata pipeline +
+            read projection land without a later contract bump; absent in
+            practice until B3 is live.
+
     OperationResult:
       type: object
       description: |
@@ -7808,7 +9681,20 @@ components:
           description: Key in the customer's export destination (if export configured)
         metrics:
           type: object
-          description: Operation-specific performance metrics
+          description: |
+            Operation-specific performance metrics, carried on the
+            **completion result** surface (SSE `operation.completed`
+            result / result-on-poll), NOT on the workflow **status**
+            read (confirmed ZjVXHkYK / api). `GET /api/workflows/{id}`
+            serialises each operation as `{id, type, status}` plus a
+            conditional `error_message`/`error_code` — it does NOT carry
+            `result.metrics`, so `re_encode_decision` / `re_encode_reason`
+            are not readable from the status poll. Canonical reads for
+            those: the per-job `processing_class` echo (on the status
+            response) for the route, and `GET /api/workflows/{id}/downloads`
+            (per-output `size_bytes`) for the authoritative output size.
+            Note `metrics` has no `output_size_bytes` field — output size
+            lives on `size_bytes` / the downloads endpoint.
           properties:
             compression_ratio:
               type: number
@@ -7849,6 +9735,7 @@ components:
 
     WorkflowDownloadSuccessEnvelope:
       type: object
+      additionalProperties: false
       required:
         - success
         - data
@@ -7902,9 +9789,10 @@ components:
           not: { required: [page_index] }
         - title: Unindexed
           description: |
-            Output without an explicit indexing field — every legacy
-            single-output download. Schema-valid; emitted by all
-            non-fan-out operations.
+            Output without a page/position indexing field — every legacy
+            single-output download AND `render_variants` variant outputs
+            (which carry the optional `target_id` correlation field but are
+            not page/position indexed).
           not:
             anyOf:
               - required: [page_index]
@@ -7947,6 +9835,32 @@ components:
             any current operation; declared for parity with
             `OperationResultOutputEntry.position`. Per ADR-0009 §D2.
           example: 0
+        target_id:
+          type: string
+          pattern: '^[A-Za-z0-9._-]+$'
+          maxLength: 64
+          description: |
+            The caller-assigned `id` of the `render_variants` target that
+            produced this output, echoed verbatim (the image-fan-out
+            addressing contract). Carried on the `Unindexed` branch (variant
+            outputs are not page/position indexed); no operation emits
+            `target_id` together with `page_index` / `position`. Mirrors
+            `OperationResultOutputEntry.target_id`. Per ticket `w3EwzHYd`.
+          example: "thumb-2x"
+        node_id:
+          type: string
+          description: |
+            Symbolic composition `node_id` correlating this download to its
+            canonical node in `WorkflowCreateResponse.composition_plan` (e.g.
+            `encode`, `thumbnail`, `processed_base`). Lets consumers label and
+            group delivered files by composition role (e.g. sdks `byNode()`,
+            FE "Main image" / "Thumbnail" labels). **Optional** — emitted once
+            the canonicalization engine is live (optional-then-promote,
+            mirroring `composition_plan` and `DeliveryPlanOutput.node_id`);
+            absent until then. Additive carrier only; the normative
+            `/downloads == delivery_plan.outputs[]` rendezvous invariant
+            lands with the delivery-selection promotion, not here.
+          example: thumbnail
 
     # ============================================
     # SSE EVENT SCHEMAS
@@ -8041,7 +9955,21 @@ components:
 
     SseOperationCompletedData:
       type: object
-      description: Payload for `operation.completed` events
+      description: |
+        Payload for `operation.completed` events.
+
+        **`result` is intentionally OPTIONAL** (not in `required`) — the
+        API does not always emit it on `operation.completed` (confirmed
+        rmP7ndhK / api `Tu78AGpe`):
+        - **Multi-output completions** (e.g. `split` → N outputs): the
+          flat single-output `result` shape can't carry N outputs, so
+          `result` is omitted by design and the outputs are read from
+          the downloads endpoint (`GET /api/workflows/{id}/downloads`).
+        - **Stale-load race**: a transient frame published before the
+          operation resolves against the snapshot may omit `result`;
+          it is repaired by a refetch.
+        Consumers MUST treat `result` as may-be-absent on
+        `operation.completed` and fall back to the downloads endpoint.
       required:
         - job_ref
         - operation_id
@@ -8468,8 +10396,10 @@ components:
         **Caching.** Per-tier private caching with ETag-based revalidation
         (per ADR-0002). Public CDN caching is NOT used because the cache
         key includes the caller's `user_tier`. Clients send
-        `If-None-Match` (and/or `If-Modified-Since`) to revalidate; the
-        server returns `304 Not Modified` when fresh.
+        `If-None-Match` to revalidate; the server returns `304 Not
+        Modified` when fresh. The content `ETag` is the sole conditional
+        validator — `If-Modified-Since` is not honored and `Last-Modified`
+        is informational only (per `sUyA9ZXD`).
 
         Cache-key composition: `user_tier + schema_version + capabilities_version + environment`.
       required:
@@ -8610,6 +10540,28 @@ components:
                       properties:
                         per_value_availability:
                           $ref: '#/components/schemas/PerValueAvailability'
+        image_encode_capabilities:
+          description: |
+            Pre-flight image-encode capability matrix
+            (`webp_quality_supported`, `background_flatten`, …) — **IDENTICAL
+            shape to `composition_plan.capabilities`** on the create-workflow
+            201, surfaced here so SDK/FE can fail-fast guard
+            format/quality/alpha-flatten choices BEFORE submitting a workflow.
+            Reuses the same API-side producer so the two can never disagree.
+
+            **Tier-invariant.** This is a fixed codec/hardware capability fact
+            (what the image encoders CAN do), NOT an entitlement — identical
+            for every tier including anonymous. Deliberately carries no
+            `availability` tag, no `per_value_availability`, and does NOT vary
+            by `user_tier` (even though the enclosing response is tier-scoped).
+
+            **Optional in the wire envelope** (same incremental-mirroring
+            stance as `endpoints` / `workflow_features`): the committed sidecar
+            MAY emit it; the runtime `GET /api/operations/schema` emits it once
+            the API generator catches up. Consumers MUST tolerate its absence
+            and its presence from either source. Per ticket
+            [`kybXQe2S`](https://trello.com/c/kybXQe2S).
+          $ref: '#/components/schemas/ImageEncodeCapabilities'
 
     EndpointProjection:
       type: object
@@ -8640,8 +10592,17 @@ components:
             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
+            access is rejected — OR acts on the caller's implicit
             identity-scoped data (credits balance, own session).
+
+            The rejection code is usually `403`, but some endpoints
+            **existence-mask cross-identity references as `404`** (BOLA/
+            IDOR: a 403 would leak that the resource exists). The
+            `createWorkflow` upload reference is the canonical case —
+            cross-owner uploads return `404 UPLOAD_NOT_FOUND`, never 403
+            (per the ADR-0016 amendment). Consumers MUST NOT assume
+            `identity_scoped: true` implies a 403 specifically; read the
+            per-operation error responses for the exact code.
         required_tier:
           description: |
             Endpoint-level entitlement gate. Reserved/null today —
@@ -8728,9 +10689,10 @@ components:
             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).
+            Present on all five role-based ops (audio_to_video,
+            video_watermark, audio_overlay, image_watermark,
+            custom_luma); absent on non-role ops (merge, archive)
+            where all inputs share a single role.
         accepts_mixed_types:
           type: boolean
           description: Whether mixed MIME types are allowed (archive only)
@@ -8814,6 +10776,37 @@ components:
             [I3](https://trello.com/c/eCWIpug8); until then the
             contract advertises the field shape but the endpoint
             does not yet surface the field.
+        processing_class:
+          type: object
+          description: |
+            Optional per-mime-group processing-class block (per ticket
+            [I15-CONS `YZpBKzOM`](https://trello.com/c/YZpBKzOM) + plan
+            v5 §F8 long-form routing). Keyed by `ProcessingClass` enum
+            value (`short_form` / `long_form` / `short_form_concat` /
+            `long_form_re_encode`); each entry advertises that routing
+            class's availability, tier gate, and size/duration caps.
+
+            Present only on mime_groups subject to short-form vs
+            long-form routing — typically `video`; per F8 also `audio`
+            for `audio_overlay` / `audio_watermark`. Absence means "no
+            per-class routing exposed": consumers MUST treat absent as
+            "no routing decision exposed" and MUST NOT coerce it to
+            `short_form` (FORMAT.md §`processing_class` parser
+            obligation 2 / ADR-0001 §1.4).
+
+            The runtime endpoint (`GET /api/operations/schema`) and the
+            `availability/availability.json` sidecar emit this block
+            verbatim from the source operation YAML (including any
+            `per_tier_constraints` overlay — copied through as an
+            opaque subtree). SDK + frontend consumers gate UI on the
+            per-class `availability` + `required_tier` and surface the
+            caller's effective caps as the binding limits. Surfacing
+            this on the typed model retires the raw-ops-schema HTTP
+            workaround per ticket
+            [`yWeBr81O`](https://trello.com/c/yWeBr81O). See
+            `schemas/FORMAT.md` §`processing_class:` block.
+          additionalProperties:
+            $ref: '#/components/schemas/ProcessingClassEntry'
         options:
           type: object
           description: Options specific to this MIME group, keyed by option name
@@ -8917,6 +10910,104 @@ components:
             The "set" sentinel means the option has any value. "logic" can be "and" (default) or "or".
           additionalProperties: true
 
+    ProcessingClassConstraints:
+      type: object
+      additionalProperties: false
+      description: |
+        Numeric size / duration caps for a single processing class (or
+        a per-tier override of those caps). All fields optional; the
+        `max_input_*` keys apply to single-input mime_groups while the
+        `max_total_*` keys apply to multi-input merge-style mime_groups
+        (a merge can have many small inputs whose combined size triggers
+        long-form). Byte caps are positive integers; duration caps are
+        ISO-8601 duration strings (e.g. `PT5M`). Field set is CI-fixed —
+        `scripts/check-per-tier-constraints.py` rejects unknown keys and
+        bad value types. See `schemas/FORMAT.md` §`constraints` sub-block.
+      properties:
+        max_input_duration:
+          type: string
+          description: |
+            Max per-input duration as an ISO-8601 duration string.
+            Single-input mime_groups.
+          example: "PT5M"
+        max_input_size_bytes:
+          type: integer
+          minimum: 1
+          description: Max per-input file size in bytes. Single-input mime_groups.
+        max_output_size_bytes:
+          type: integer
+          minimum: 1
+          description: Max output file size in bytes. Any mime_group.
+        max_total_duration:
+          type: string
+          description: |
+            Max combined duration across all inputs as an ISO-8601
+            duration string. Multi-input (merge) mime_groups.
+          example: "PT1H"
+        max_total_input_size_bytes:
+          type: integer
+          minimum: 1
+          description: Max combined input size in bytes. Multi-input (merge) mime_groups.
+
+    ProcessingClassEntry:
+      type: object
+      description: |
+        Single processing-class entry within a mime_group's
+        `processing_class` map (per ticket
+        [I15-CONS `YZpBKzOM`](https://trello.com/c/YZpBKzOM)). Mirrors
+        `PerValueAvailabilityEntry` (availability + optional tier / eta /
+        documentation_url) plus per-class `constraints` and an optional
+        `per_tier_constraints` overlay. Surfaced on the typed getSchema
+        model per ticket [`yWeBr81O`](https://trello.com/c/yWeBr81O).
+        See `schemas/FORMAT.md` §`processing_class:` block.
+      required:
+        - availability
+      properties:
+        availability:
+          $ref: '#/components/schemas/AvailabilityValue'
+          description: Per-class availability tag.
+        required_tier:
+          description: |
+            Tier required to use this class. Optional — omit when the
+            class is gated by readiness rather than subscription.
+            `null` is equivalent to omitted (no tier restriction).
+          oneOf:
+            - $ref: '#/components/schemas/UserTier'
+            - type: 'null'
+        eta:
+          type: string
+          description: |
+            ISO-8601 date (`2026-09-15`) or quarter (`2026-Q3`) when
+            this class is expected to ship. Only meaningful for
+            `availability: planned`.
+        documentation_url:
+          type: string
+          format: uri
+          description: Optional link to processing-class documentation.
+        constraints:
+          $ref: '#/components/schemas/ProcessingClassConstraints'
+          description: |
+            Baseline caps for the lowest tier this class's
+            `required_tier` permits. Overlaid per-caller by
+            `per_tier_constraints` (see below).
+        per_tier_constraints:
+          type: object
+          description: |
+            Optional per-tier numeric-cap override map (per
+            [ADR-0011](../docs/decisions/0011-per-tier-processing-class-constraints.md),
+            ticket [`z4GDTUMx`](https://trello.com/c/z4GDTUMx)). Keys
+            MUST be a subset of the `UserTier` enum and SHOULD name only
+            tiers HIGHER than the class baseline (CI-enforced by
+            `scripts/check-per-tier-constraints.py`). Each value
+            overrides `constraints` field-by-field for callers of that
+            tier. A consumer that ignores this map reads `constraints`
+            and sees the smallest permitted-tier cap — it can never
+            over-promise. `per_tier_constraints` sizes caps, it does
+            NOT grant access (eligibility stays governed by
+            `availability` + `required_tier`).
+          additionalProperties:
+            $ref: '#/components/schemas/ProcessingClassConstraints'
+
     # ============================================
     # RETRY SCHEMAS
     # ============================================
@@ -8942,6 +11033,7 @@ components:
 
     RetrySuccessEnvelope:
       type: object
+      additionalProperties: false
       required:
         - success
         - data