@giveitsmaller/contracts 0.3.0 → 0.4.0

package/openapi/api.yaml

@@ -75,7 +75,7 @@ info:
     of truth instead of hardcoding magic numbers. A runtime
     `GET /api/uploads/limits` endpoint for dynamic discovery
     (per-tier / per-environment overrides) is a deferred follow-up.
-  version: 2.7.1
+  version: 2.12.0
   contact:
     name: API Support
 
@@ -302,7 +302,7 @@ paths:
         for the remaining parts. The client uploads parts 2-N directly to S3.
 
         **Recommended client behaviour:** chunk size
-        `UploadThresholds.multipart_chunk_size` (5 MiB) with
+        `UploadThresholds.multipart_chunk_size` (16 MiB) with
         `UploadThresholds.multipart_concurrency_default` parallel uploads.
         The server returns `recommended_chunk_size` per file based on
         first-chunk throughput; SDKs SHOULD prefer that runtime value when
@@ -311,9 +311,10 @@ paths:
         **Chunk sizing strategy:**
         - First chunk: fixed `UploadThresholds.multipart_first_chunk_size` = 8 MiB (sent to API)
         - Remaining chunks: API calculates `recommended_chunk_size` from throughput * 5s,
-          clamped to 5MB-100MB
-        - The last part may be smaller than 5MB (S3 allows this for the final part)
-        - Maximum 500 parts per upload
+          clamped to 16 MiB–100 MiB
+        - The last part may be smaller than 16 MiB (S3 allows this for the final part)
+        - Maximum 10,000 parts per upload (the S3 multipart hard limit;
+          raised from 500 by CON-1/ADR-0011 for the 120 GB Enterprise envelope)
 
         **Pre-signed URL TTL:**
         Dynamic based on estimated upload duration * 2, clamped between 900s and 3600s.
@@ -343,7 +344,7 @@ paths:
                   first_chunk_etag: '"d8e8fca2dc0f896fd7cb4cb0031ba249"'
                   first_chunk_size_bytes: 8388608
                   total_parts: 5
-                  recommended_chunk_size: 10485760
+                  recommended_chunk_size: 16777216
                   presigned_urls:
                     - part_number: 2
                       url: "https://gisl-stg-euw1-input.s3.eu-west-1.amazonaws.com/uploads/...?X-Amz-Expires=1800&..."
@@ -444,6 +445,15 @@ paths:
 
         The API calls S3 CompleteMultipartUpload and persists the upload record.
         No job or workflow is created — use `POST /api/workflows` to process the file.
+
+        **Ownership enforcement** (per session-resume work, ticket
+        [`HxUmVr3Y`](https://trello.com/c/HxUmVr3Y)): when
+        `manifest.userId` is non-null, `multipart/complete` refuses
+        completion by any caller other than the original authenticator
+        (returns 403 `MULTIPART_SESSION_OWNERSHIP`). The sister
+        endpoints `/status`, `/presign`, `/keepalive` apply the same
+        rule and additionally refuse anonymous-initiated sessions
+        outright (returning 403 `MULTIPART_SESSION_AUTH_REQUIRED`).
       operationId: multipartComplete
       tags:
         - Upload
@@ -479,6 +489,20 @@ paths:
               example:
                 success: false
                 error: "Missing ETags for parts: 3, 5"
+        '403':
+          description: |
+            Forbidden — session's `manifest.userId` is non-null and
+            differs from the authenticated caller. Per ticket
+            [`HxUmVr3Y`](https://trello.com/c/HxUmVr3Y) ownership
+            enforcement (carried by the same controller path as the
+            three new resume endpoints).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: "MULTIPART_SESSION_OWNERSHIP"
         '404':
           description: Upload session not found or expired
           content:
@@ -495,6 +519,341 @@ paths:
               schema:
                 $ref: '#/components/schemas/ErrorEnvelope'
 
+  /api/uploads/multipart/{uploadId}/status:
+    get:
+      summary: Cursor over uploaded parts of an in-flight multipart session
+      description: |
+        Returns the list of parts already received by S3 for an in-flight
+        multipart session. Used by SDKs to resume an interrupted upload —
+        the client walks the cursor pages, collects which `part_number`
+        slots are filled, and re-presigns / re-uploads only the missing
+        slots via `POST /api/uploads/multipart/{uploadId}/presign`.
+
+        The response shape is a 1:1 passthrough of the S3 ListParts API —
+        `next_part_number_marker` and `is_truncated` mirror the upstream
+        wire shape verbatim (no translation layer, zero impedance
+        mismatch for SDKs that already speak S3 vocabulary).
+
+        **Authentication required.** Anonymous-initiated sessions (allowed
+        at `/initiate` today; the `8LABloaz` follow-up flips that to
+        require-auth) cannot use this endpoint and receive 403
+        `MULTIPART_SESSION_AUTH_REQUIRED`. Authenticated callers can only
+        list parts of sessions they initiated (403
+        `MULTIPART_SESSION_OWNERSHIP` otherwise).
+
+        Cursor semantics: pass `cursor=0` (default) for the first page;
+        the server returns up to `limit` parts plus `next_part_number_marker`
+        and `is_truncated`. To walk: pass each `next_part_number_marker`
+        as the next request's `cursor` until `is_truncated: false`. The
+        marker is `null` on the final page.
+
+        Completion-readiness is client-derived (walk all pages, compare
+        the count of returned parts to `total_parts`).
+      operationId: multipartStatus
+      tags:
+        - Upload
+      parameters:
+        - name: uploadId
+          in: path
+          required: true
+          description: Multipart upload session identifier from the initiate response.
+          schema:
+            $ref: '#/components/schemas/UuidV7'
+        - name: cursor
+          in: query
+          required: false
+          description: |
+            S3 ListParts `PartNumberMarker` (the part-number to start
+            listing **after**). `0` (default) returns from the first
+            part. Walk by passing each response's
+            `next_part_number_marker` until `is_truncated: false`.
+          schema:
+            type: integer
+            minimum: 0
+            maximum: 9999
+            default: 0
+        - name: limit
+          in: query
+          required: false
+          description: |
+            Page size — maximum number of parts returned per request.
+            `1000` is the default and the upstream S3 `MaxParts` cap.
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 1000
+            default: 1000
+      responses:
+        '200':
+          description: Page of uploaded parts.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MultipartStatusSuccessEnvelope'
+              example:
+                success: true
+                data:
+                  upload_id: "019539ab-1111-7000-8000-000000000001"
+                  multipart_upload_id: "5MqcMpgg9_pKVdoO9.X9eK0w2g3Sq5_h"
+                  cloud_key: "uploads/01/019539ab-1111-7000-8000-000000000001/source"
+                  total_parts: 5
+                  uploaded_parts:
+                    - part_number: 1
+                      etag: '"d8e8fca2dc0f896fd7cb4cb0031ba249"'
+                      size_bytes: 8388608
+                      last_modified: "2026-05-20T13:30:00.000Z"
+                    - part_number: 2
+                      etag: '"7c3e2c4b6e3e7e0e8f9d1a2b3c4d5e6f"'
+                      size_bytes: 16777216
+                      last_modified: "2026-05-20T13:31:14.000Z"
+                  next_part_number_marker: null
+                  is_truncated: false
+                  manifest_expires_at: "2026-05-22T13:31:14.000Z"
+                  recommended_chunk_size: 16777216
+        '401':
+          description: Authentication required.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '403':
+          description: |
+            Forbidden — either the session was anonymously initiated
+            (`MULTIPART_SESSION_AUTH_REQUIRED`) or the authenticated
+            caller is not the session owner (`MULTIPART_SESSION_OWNERSHIP`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              examples:
+                auth_required:
+                  summary: Anonymous-initiated session
+                  value:
+                    success: false
+                    error: "MULTIPART_SESSION_AUTH_REQUIRED"
+                ownership:
+                  summary: Session belongs to a different authenticated caller
+                  value:
+                    success: false
+                    error: "MULTIPART_SESSION_OWNERSHIP"
+        '404':
+          description: Multipart session not found or expired.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: "MULTIPART_SESSION_NOT_FOUND"
+        '500':
+          description: Internal server error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+
+  /api/uploads/multipart/{uploadId}/presign:
+    post:
+      summary: Sparse re-presign of multipart parts (resume / retry)
+      description: |
+        Returns fresh pre-signed PUT URLs for a caller-supplied subset
+        of part numbers. Used by SDKs to (a) resume an interrupted
+        upload after the original presigned URLs have expired, and
+        (b) retry individual failed PUTs without re-presigning the
+        whole upload.
+
+        Part numbers MUST satisfy `2 ≤ n ≤ total_parts`. **Part 1 is
+        rejected** because the manifest stores its ETag from `/initiate`
+        — re-presigning part 1 would break the eventual
+        `multipart/complete` call. Request the list with
+        `uniqueItems`; duplicates are rejected with a 400.
+
+        At most 100 part numbers per request. SDKs paginate larger
+        sets across multiple `/presign` calls.
+
+        **Authentication required.** Same `MULTIPART_SESSION_*` codes
+        apply as on `/status`.
+      operationId: multipartPresign
+      tags:
+        - Upload
+      parameters:
+        - name: uploadId
+          in: path
+          required: true
+          description: Multipart upload session identifier from the initiate response.
+          schema:
+            $ref: '#/components/schemas/UuidV7'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/MultipartPresignRequest'
+      responses:
+        '200':
+          description: Pre-signed URLs returned for the requested parts.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MultipartPresignSuccessEnvelope'
+              example:
+                success: true
+                data:
+                  upload_id: "019539ab-1111-7000-8000-000000000001"
+                  presigned_urls:
+                    - part_number: 3
+                      url: "https://gisl-stg-euw1-input.s3.eu-west-1.amazonaws.com/uploads/...?X-Amz-Expires=1800&..."
+                      expires_at: "2026-05-20T14:01:14.000Z"
+                    - part_number: 5
+                      url: "https://gisl-stg-euw1-input.s3.eu-west-1.amazonaws.com/uploads/...?X-Amz-Expires=1800&..."
+                      expires_at: "2026-05-20T14:01:14.000Z"
+        '400':
+          description: |
+            Validation failed — e.g. body too large, malformed JSON,
+            `part_numbers` empty / >100, contains duplicates, contains
+            `1`, contains values outside `[2, total_parts]`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: "part_numbers must contain unique values in [2, total_parts]; part 1 is sealed"
+        '401':
+          description: Authentication required.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '403':
+          description: |
+            Forbidden — either the session was anonymously initiated
+            (`MULTIPART_SESSION_AUTH_REQUIRED`) or the authenticated
+            caller is not the session owner (`MULTIPART_SESSION_OWNERSHIP`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              examples:
+                auth_required:
+                  value:
+                    success: false
+                    error: "MULTIPART_SESSION_AUTH_REQUIRED"
+                ownership:
+                  value:
+                    success: false
+                    error: "MULTIPART_SESSION_OWNERSHIP"
+        '404':
+          description: Multipart session not found or expired.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: "MULTIPART_SESSION_NOT_FOUND"
+        '422':
+          description: |
+            Session no longer accepts re-presign requests because the
+            assembled object would exceed the S3 multipart capacity
+            cap. Pre-S3 server-side capacity gate; distinct from
+            tier-quota rejections at `/initiate` time.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: "FILE_TOO_LARGE_FOR_MULTIPART"
+        '500':
+          description: Internal server error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+
+  /api/uploads/multipart/{uploadId}/keepalive:
+    post:
+      summary: Refresh the multipart session manifest TTL
+      description: |
+        Resets the session manifest's TTL to 48 h ahead of now. The
+        server uses an atomic Redis `EXPIRE`; the operation is
+        idempotent — calling it multiple times in succession produces
+        the same effective TTL window.
+
+        SDKs SHOULD call this periodically on resume flows (e.g. once
+        per minute while a resumable upload is paused) to prevent the
+        manifest from lapsing. The manifest TTL is decoupled from
+        individual presigned-URL TTLs (which are typically 900s–3600s);
+        re-presigning expired URLs requires the manifest still be
+        alive.
+
+        Empty request body.
+
+        **Authentication required.** Same `MULTIPART_SESSION_*` codes
+        apply as on `/status` and `/presign`.
+      operationId: multipartKeepalive
+      tags:
+        - Upload
+      parameters:
+        - name: uploadId
+          in: path
+          required: true
+          description: Multipart upload session identifier from the initiate response.
+          schema:
+            $ref: '#/components/schemas/UuidV7'
+      responses:
+        '200':
+          description: Manifest TTL refreshed; new expiry returned.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MultipartKeepaliveSuccessEnvelope'
+              example:
+                success: true
+                data:
+                  upload_id: "019539ab-1111-7000-8000-000000000001"
+                  manifest_expires_at: "2026-05-22T13:31:14.000Z"
+        '401':
+          description: Authentication required.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '403':
+          description: |
+            Forbidden — either the session was anonymously initiated
+            (`MULTIPART_SESSION_AUTH_REQUIRED`) or the authenticated
+            caller is not the session owner (`MULTIPART_SESSION_OWNERSHIP`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              examples:
+                auth_required:
+                  value:
+                    success: false
+                    error: "MULTIPART_SESSION_AUTH_REQUIRED"
+                ownership:
+                  value:
+                    success: false
+                    error: "MULTIPART_SESSION_OWNERSHIP"
+        '404':
+          description: Multipart session not found or expired.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: "MULTIPART_SESSION_NOT_FOUND"
+        '500':
+          description: Internal server error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+
   /api/uploads/{id}/metadata:
     get:
       summary: Get file metadata
@@ -762,12 +1121,21 @@ paths:
         side-effect dependencies that don't surface as `from`
         references).
 
-        **Default operation:** if `operations` is omitted on a
-        single-input job with `source: { type: upload, ... }`, the
-        default is `[{ "type": "compress" }]` with default options for
-        the detected MIME type. Multi-input jobs must always specify
+        **Default operation:** if `operations` is omitted — or
+        explicitly empty (`[]`) — on a single-input job with
+        `source: { type: upload, ... }`, the default is
+        `[{ "type": "compress" }]` with default options for the
+        detected MIME type. Multi-input jobs must always specify
         operations explicitly.
 
+        **Compression opt-out:** V2 has no `skip_compression` flag —
+        `operations[]` *is* the chain. To opt a job out of
+        compression, send an explicit non-empty `operations[]` that
+        does not include `compress`; on a single-input upload job an
+        empty `[]` does *not* opt out (it is treated as omitted and
+        still receives the implicit `compress` — see above). Per
+        [ADR-0004](../docs/decisions/0004-job-shape.md).
+
         **Multi-input constraint:** multi-input jobs (`inputs[]`) must
         have exactly one operation, which must be a multi-input type
         (`merge`, `archive`, `image_watermark`, `custom_luma`, or
@@ -1077,7 +1445,7 @@ paths:
                 error: "Upload not found: 019539ab-1111-7000-8000-999999999999"
         '422':
           description: |
-            Semantically invalid request. Either:
+            Semantically invalid request. One of:
 
             - Generic validation error (unknown operation type, invalid
               option combinations, cyclic dependency in workflow_edges,
@@ -1090,6 +1458,22 @@ paths:
               with `error_type: feature_not_available`. Per ADR-0001
               §1.3 Tension 1 rule, the server MUST honour tagged
               availability.
+            - Processing-class band-ceiling overflow — returned as
+              `ProcessingClassExceedsBandResponse` with `error_type:
+              processing_class_exceeds_band`. Fires when one or more
+              jobs cannot be classified because input size/duration
+              exceeds the `long_form` (or `long_form_re_encode`)
+              ceiling under the caller's effective per-tier caps
+              (`per_tier_constraints` overlay per
+              [ADR-0011](../docs/decisions/0011-per-tier-processing-class-constraints.md)).
+              Per-violation `required_tier` names the tier (if any)
+              whose `per_tier_constraints` would accommodate the
+              request (`null` = no tier resolves, e.g. enterprise
+              already at the 120 GB hard ceiling). Distinct from
+              `TierRestrictionResponse` (403, request-level upload
+              quota — see [ADR-0012](../docs/decisions/0012-processing-class-band-reject-envelope.md)
+              for the band-vs-tier split). Per ADR-0001 §F6
+              batched-violations rule, `violations[]` is fail-all.
             - Re-encode required (per ticket I16-CONS, Trello
               `7nCZXEru`). Returned for `merge.video` jobs with
               `re_encode_mode: never` when the compatibility probe
@@ -1108,27 +1492,29 @@ paths:
             Backward-compatibility note: the prior 422 shape
             (`ValidationErrorEnvelope`) is preserved unchanged — its
             `details[]` array is the structural signature consumers
-            duck-type against. The new `FeatureNotAvailableResponse`
-            branch carries `error_type: feature_not_available` +
-            `violations[]` instead. The `REQUIRES_REENCODE` flavour
-            reuses `ValidationErrorEnvelope` (a user-fixable validation
-            error in the same family as `INVALID_OPTIONS`) and is
-            distinguished by the stable `error: "REQUIRES_REENCODE"`
-            string code rather than a new `error_type` enum value.
-            Branches are distinguishable by required fields (`details`
-            vs `error_type`+`violations`), so plain `oneOf` matches
-            without a discriminator object — see `openapi/api.yaml`
-            §"FEATURE AVAILABILITY ENVELOPES" commentary for the
-            convention rationale (no discriminator here because
-            `ValidationErrorEnvelope` has no `error_type` field;
-            OpenAPI 3.1 discriminators require the property to be
-            present on every branch).
+            duck-type against. `FeatureNotAvailableResponse` carries
+            `error_type: feature_not_available` + `violations[]`;
+            `ProcessingClassExceedsBandResponse` carries `error_type:
+            processing_class_exceeds_band` + `violations[]`. The
+            `REQUIRES_REENCODE` flavour reuses `ValidationErrorEnvelope`
+            (a user-fixable validation error in the same family as
+            `INVALID_OPTIONS`) and is distinguished by the stable
+            `error: "REQUIRES_REENCODE"` string code rather than a new
+            `error_type` enum value. Branches are distinguishable by
+            required-field shape (`details` vs `error_type` value), so
+            plain `oneOf` matches without a discriminator object — see
+            `openapi/api.yaml` §"FEATURE AVAILABILITY ENVELOPES"
+            commentary for the convention rationale (no discriminator
+            here because `ValidationErrorEnvelope` has no `error_type`
+            field; OpenAPI 3.1 discriminators require the property to
+            be present on every branch).
           content:
             application/json:
               schema:
                 oneOf:
                   - $ref: '#/components/schemas/ValidationErrorEnvelope'
                   - $ref: '#/components/schemas/FeatureNotAvailableResponse'
+                  - $ref: '#/components/schemas/ProcessingClassExceedsBandResponse'
               examples:
                 validation_error:
                   summary: Generic validation error (legacy shape)
@@ -1155,6 +1541,43 @@ paths:
                         documentation_url: "https://docs.giveitsmaller.com/operations/audio_overlay"
                       - feature: "operation.merge.mime_group.image.option.transition.dissolve"
                         availability: "experimental"
+                processing_class_exceeds_band_combined_size:
+                  summary: |
+                    merge job whose summed inputs (130 GB) exceed the
+                    Enterprise long_form_re_encode ceiling (120 GB
+                    hard cap per ADR-0011). Terminal — no tier
+                    resolves it; `required_tier` is null.
+                  value:
+                    success: false
+                    error: "Workflow contains inputs that exceed the long-form processing-class ceiling"
+                    error_type: "processing_class_exceeds_band"
+                    violations:
+                      - reason: "combined_size_exceeds_long_form"
+                        job_ref: "stitched"
+                        operation: "merge"
+                        processing_class: "long_form_re_encode"
+                        actual: 130000000000
+                        ceiling: 120000000000
+                        required_tier: null
+                        documentation_url: "https://docs.giveitsmaller.com/processing-class/long-form"
+                processing_class_exceeds_band_single_input_duration:
+                  summary: |
+                    compress.video job whose single input duration
+                    (15 hours = 54000s) exceeds the Pro long_form
+                    `max_input_duration` (PT12H = 43200s). Upgrade to
+                    Enterprise resolves the duration cap.
+                  value:
+                    success: false
+                    error: "Workflow contains inputs that exceed the long-form processing-class ceiling"
+                    error_type: "processing_class_exceeds_band"
+                    violations:
+                      - reason: "input_duration_exceeds_long_form"
+                        job_ref: "job_0"
+                        operation: "compress"
+                        processing_class: "long_form"
+                        actual: 54000
+                        ceiling: 43200
+                        required_tier: "enterprise"
                 requires_reencode:
                   summary: merge.video re_encode_mode=never with incompatible inputs (I16-CONS)
                   value:
@@ -2796,6 +3219,25 @@ components:
             `REQUIRES_REENCODE`). Canonical English; never localised.
             SDKs duck-type on this field for typed error-branch
             helpers.
+
+            Multipart-session resume codes (per ticket
+            [`HxUmVr3Y`](https://trello.com/c/HxUmVr3Y), V2.10.0):
+            - `MULTIPART_SESSION_NOT_FOUND` (404) — upload_id does
+              not match an in-flight session (expired / never
+              existed / wrong account namespace). Fired by /status,
+              /presign, /keepalive.
+            - `MULTIPART_SESSION_OWNERSHIP` (403) — authenticated
+              caller is not the session owner. Fired by /status,
+              /presign, /keepalive, /complete (when manifest.userId
+              is non-null and differs).
+            - `MULTIPART_SESSION_AUTH_REQUIRED` (403) — session was
+              anonymously initiated; the three resume endpoints
+              require authentication. The `8LABloaz` follow-up will
+              flip `/initiate` to also require auth.
+            - `FILE_TOO_LARGE_FOR_MULTIPART` (422) — assembled object
+              would exceed the S3 multipart capacity cap. Pre-S3
+              server-side capacity gate; distinct from tier-quota
+              rejections (`upload_size_exceeds_tier`).
         message:
           type: string
           description: |
@@ -4274,8 +4716,12 @@ components:
         rejection.
 
         The 422 response is delivered alongside `ValidationErrorEnvelope`
-        via `oneOf + discriminator` on `error_type` — see the 422
-        response on `POST /api/workflows`.
+        and `ProcessingClassExceedsBandResponse` via a naked `oneOf`
+        (duck-typed on required-field shape — `details` vs `error_type`
+        value: `feature_not_available` vs `processing_class_exceeds_band`).
+        No discriminator object is used because `ValidationErrorEnvelope`
+        has no `error_type` field. See the 422 response on
+        `POST /api/workflows`.
       allOf:
         - $ref: '#/components/schemas/ErrorEnvelope'
         - type: object
@@ -4299,6 +4745,205 @@ components:
               items:
                 $ref: '#/components/schemas/FeatureViolation'
 
+    ProcessingClassRejectReason:
+      type: string
+      description: |
+        Why a job cannot be classified — input size/duration exceeds
+        the `long_form` (or `long_form_re_encode`) ceiling under the
+        caller's effective per-tier caps (per
+        [ADR-0011](../docs/decisions/0011-per-tier-processing-class-constraints.md)
+        `per_tier_constraints`). Distinct from `ProcessingClassReason`
+        (which describes WHY a job got its assigned class — success-
+        path advisory).
+
+        Reasons are split by the violated constraint key on the
+        processing-class block (per `schemas/FORMAT.md`
+        §"`processing_class:` block"):
+
+        - `input_size_exceeds_long_form` /
+          `input_duration_exceeds_long_form`: a **single input**
+          exceeds the per-input ceiling (`max_input_size_bytes` /
+          `max_input_duration`). Applies to single-input operations
+          (compress, convert, thumbnail, text_watermark,
+          audio_watermark) AND per-input checks on multi-input
+          operations with per-input caps (image_watermark,
+          custom_luma, audio_overlay).
+        - `combined_size_exceeds_long_form` /
+          `combined_duration_exceeds_long_form`: the **summed** inputs
+          exceed the multi-input combined ceiling
+          (`max_total_input_size_bytes` / `max_total_duration`).
+          Applies to operations whose `processing_class.<class>.
+          constraints` carries `max_total_*` — merge today.
+      enum:
+        - input_size_exceeds_long_form
+        - input_duration_exceeds_long_form
+        - combined_size_exceeds_long_form
+        - combined_duration_exceeds_long_form
+
+    ProcessingClassBandViolation:
+      type: object
+      description: |
+        One band-ceiling overflow on a workflow-create reject. Carries
+        the I26 localisation quad on the violation (mirrors
+        `FeatureViolation`); envelope-level localisation rides via
+        `allOf [ErrorEnvelope]` on `ProcessingClassExceedsBandResponse`.
+
+        `job_ref`, `actual`, `ceiling`, `operation`, and
+        `processing_class` are REQUIRED — the server always knows them
+        at reject time and consumers rely on them to (a) correlate
+        fail-all violations back to the offending job in multi-job
+        workflows and (b) render "X exceeded by Y" without re-deriving
+        caps from the per-tier overlay.
+      required:
+        - reason
+        - job_ref
+        - operation
+        - processing_class
+        - actual
+        - ceiling
+      properties:
+        reason:
+          $ref: '#/components/schemas/ProcessingClassRejectReason'
+        job_ref:
+          type: string
+          description: |
+            Workflow-local job identifier — `JobDefinition.id` if the
+            caller supplied one, otherwise the auto-generated `job_N`
+            positional token assigned by the server during request
+            validation (e.g. `job_0`, `job_1`). Workflow-create rejects
+            fire BEFORE persisted server UUIDs are assigned; `job_ref`
+            is the request-local handle that survives across reject
+            and (later) success paths. Per `JobDefinition.id` pattern
+            + auto-generation rules.
+          example: "stitched"
+        input_index:
+          type: integer
+          minimum: 0
+          description: |
+            0-based ordinal into `JobDefinition.inputs[]` identifying
+            the specific input that violated the per-input ceiling.
+            Set ONLY on `input_*_exceeds_long_form` reasons for
+            multi-input operations; omitted on single-input
+            operations (no positional ambiguity) and on
+            `combined_*_exceeds_long_form` reasons (whole-job
+            violation across all inputs).
+        operation:
+          $ref: '#/components/schemas/OperationType'
+          description: Operation type that triggered the band-ceiling reject.
+        processing_class:
+          $ref: '#/components/schemas/ProcessingClass'
+          description: |
+            The class whose ceiling was exceeded — typically `long_form`
+            or `long_form_re_encode`.
+        actual:
+          type: integer
+          minimum: 0
+          description: |
+            Observed value. Bytes for `*_size_exceeds_long_form`
+            reasons; whole seconds for `*_duration_exceeds_long_form`
+            reasons.
+        ceiling:
+          type: integer
+          minimum: 0
+          description: |
+            Effective per-tier ceiling for this caller (same units as
+            `actual`). The binding cap after `per_tier_constraints`
+            overlay; lets consumers render "X exceeded by Y" without
+            re-deriving caps from the per-tier overlay.
+        required_tier:
+          description: |
+            Optional. When a HIGHER tier exists whose
+            `per_tier_constraints` would accommodate this request, the
+            server SHOULD set `required_tier` to that tier — consumers
+            can offer an upgrade nudge. `null` (or omitted) means
+            **no tier resolves** the overflow (e.g. enterprise already
+            hits the 120 GB hard ceiling per
+            [ADR-0011](../docs/decisions/0011-per-tier-processing-class-constraints.md)
+            D1–D4).
+
+            Distinct from `TierRestrictionResponse.required_tier`
+            which names a tier whose request-level upload cap
+            satisfies the request — this field names a tier whose
+            long-form processing-class cap satisfies it. Per
+            [ADR-0012](../docs/decisions/0012-processing-class-band-reject-envelope.md)
+            for the band-vs-tier split.
+          oneOf:
+            - $ref: '#/components/schemas/UserTier'
+            - type: 'null'
+        documentation_url:
+          type: string
+          format: uri
+          description: Optional link to processing-class documentation.
+        message_key:
+          type: string
+          description: Per I26. See `ErrorEnvelope.message_key`.
+        message:
+          type: string
+          description: |
+            Per I26. Human-readable, localised per `Accept-Language`.
+            Never parse for control flow.
+        locale:
+          type: string
+          description: BCP 47 locale tag. See `ErrorEnvelope.locale`.
+        message_params:
+          type: object
+          additionalProperties: true
+          description: |
+            Per I26. Optional interpolation values for the localised
+            `message`. Excludes cost numbers.
+
+    ProcessingClassExceedsBandResponse:
+      description: |
+        422 response body when one or more jobs cannot be classified
+        because input size/duration exceeds the `long_form` (or
+        `long_form_re_encode`) ceiling under the caller's effective
+        per-tier caps (per
+        [ADR-0011](../docs/decisions/0011-per-tier-processing-class-constraints.md)
+        `per_tier_constraints`).
+
+        Distinct from `TierRestrictionResponse` (403, request-level
+        tier-quota — resolvable by upload-size reduction or quota
+        change) and from `FeatureNotAvailableResponse` (422, feature
+        tagged not-yet-shipped — resolvable by waiting for the
+        availability flip). Resolution path is per-violation:
+        `required_tier` on each `ProcessingClassBandViolation` names
+        the tier (if any) whose `per_tier_constraints` would
+        accommodate the request; `null` means terminal (e.g. enterprise
+        already at the 120 GB hard ceiling).
+
+        Per
+        [ADR-0012](../docs/decisions/0012-processing-class-band-reject-envelope.md)
+        for the band-vs-tier rationale and routing rule (why this
+        envelope is 422, not an extension of `TierRestrictionResponse`
+        on 403).
+
+        Delivered on `POST /api/workflows` 422 in a naked `oneOf`
+        alongside `ValidationErrorEnvelope` and
+        `FeatureNotAvailableResponse` — branches distinguished by
+        required-field shape (`details` vs `error_type` value).
+      allOf:
+        - $ref: '#/components/schemas/ErrorEnvelope'
+        - type: object
+          required:
+            - error_type
+            - violations
+          properties:
+            error_type:
+              type: string
+              enum:
+                - processing_class_exceeds_band
+              description: Discriminator for the 422 oneOf. Always `processing_class_exceeds_band` for this envelope.
+            violations:
+              type: array
+              minItems: 1
+              description: |
+                One entry per offending job/input. Per ADR-0001 §F6
+                batched-violations rule, multiple violations in a
+                single request are ALL returned here (fail-all, not
+                fail-fast).
+              items:
+                $ref: '#/components/schemas/ProcessingClassBandViolation'
+
     FeatureTierRestrictedResponse:
       description: |
         403 response body when a workflow references one or more features
@@ -4634,11 +5279,18 @@ components:
         multipart_chunk_size:
           type: integer
           format: int64
-          const: 5242880
+          const: 16777216
           description: |
             Recommended chunk size in bytes for multipart upload
-            chunks (5 MiB / 5,242,880 bytes — 1024-based). Matches
-            the existing TS SDK default. The server's
+            chunks (16 MiB / 16,777,216 bytes — 1024-based). Raised
+            from 5 MiB by CON-1 (ADR-0011): S3 caps a multipart
+            upload at 10,000 parts, and the Enterprise envelope is a
+            120 GB hard ceiling. At 16 MiB a 120 GiB object needs
+            7,680 parts (≤ 10,000, inside AWS's 16–64 MB recommended
+            band); 5 MiB would need 24,576 and 10 MiB 12,288 — both
+            exceed the S3 limit. **Wire-incompatible change** — SDKs
+            pin this as a compile-time constant, so CON-1 and SDK-2
+            ship as a non-independently-mergeable pair. The server's
             `MultipartInitiateResponse` returns a
             `recommended_chunk_size` per file based on first-chunk
             throughput; SDKs SHOULD prefer that runtime value when
@@ -4807,27 +5459,43 @@ components:
         total_parts:
           type: integer
           minimum: 2
-          maximum: 500
+          maximum: 10000
           description: |
             Total number of parts. The client slices the remaining file into
             exactly (total_parts - 1) chunks using recommended_chunk_size.
-            The last chunk may be smaller.
+            The last chunk may be smaller. Maximum raised 500 → 10,000 by
+            CON-1 (ADR-0011) — 10,000 is the S3 multipart hard part limit;
+            500 contract-capped uploads at ≈ 50 GB, below the 120 GB
+            Enterprise envelope.
           example: 5
         recommended_chunk_size:
           type: integer
-          minimum: 5242880
+          minimum: 16777216
           maximum: 104857600
           description: |
             Chunk size in bytes for remaining parts. Calculated from first chunk
-            throughput * 5s target, clamped to 5MB-100MB. The last chunk may be
-            smaller than 5MB.
-          example: 10485760
+            throughput * 5s target, clamped to 16 MiB–100 MiB. The last chunk
+            may be smaller than 16 MiB. Minimum raised 5 MiB → 16 MiB by CON-1
+            (ADR-0011) so the runtime value never falls below the
+            `UploadThresholds.multipart_chunk_size` constant SDKs fall back to
+            (the S3 10,000-part limit at the 120 GB Enterprise ceiling).
+          example: 16777216
         presigned_urls:
           type: array
           description: |
             Pre-signed S3 PUT URLs for parts 2 through total_parts.
             Each URL accepts a PUT request with raw chunk bytes as body.
             Collect the ETag from each S3 response for the complete request.
+
+            NOTE (CON-1/ADR-0011): with `total_parts` now bounded by the
+            S3 hard limit (10,000), a maximal Enterprise upload implies a
+            large URL set. The server is NOT required to return every URL
+            in one synchronous response — bounded-batch / paginated URL
+            delivery and resumable re-fetch are owned by API-2
+            (durable upload session) and SDK-3 (presigned batching +
+            paginated ListParts). Consumers MUST NOT assume a single
+            initiate response carries all `total_parts - 1` URLs at the
+            high end of the range; treat this array as the first batch.
           items:
             $ref: '#/components/schemas/PresignedUrlPart'
         constraints_applied:
@@ -4940,6 +5608,249 @@ components:
         data:
           $ref: '#/components/schemas/MultipartCompleteResponse'
 
+    # ============================================
+    # MULTIPART SESSION RESUME SCHEMAS (HxUmVr3Y)
+    # ============================================
+
+    MultipartPartListing:
+      type: object
+      description: |
+        One uploaded part as reported by the S3 multipart ListParts
+        API. The /status response carries an array of these. Mirrors
+        the S3 wire shape verbatim so the response is a 1:1 passthrough
+        with no translation layer.
+      required:
+        - part_number
+        - etag
+        - size_bytes
+        - last_modified
+      properties:
+        part_number:
+          type: integer
+          minimum: 1
+          maximum: 10000
+          description: |
+            S3 multipart part number. Part 1 is always present in a
+            healthy session (uploaded synchronously at `/initiate`);
+            parts 2–N follow.
+        etag:
+          type: string
+          description: |
+            ETag returned by S3 for the part. Quoted MD5 hex by default;
+            preserve quotes verbatim as S3 emits them.
+          example: '"d8e8fca2dc0f896fd7cb4cb0031ba249"'
+        size_bytes:
+          type: integer
+          format: int64
+          minimum: 0
+          description: Part size in bytes (as reported by S3).
+        last_modified:
+          type: string
+          format: date-time
+          description: ISO-8601 timestamp from S3 ListParts `LastModified`.
+
+    MultipartStatusResponse:
+      type: object
+      description: |
+        Resume-state snapshot for an in-flight multipart session. The
+        `data` payload on `GET /api/uploads/multipart/{uploadId}/status`.
+      required:
+        - upload_id
+        - multipart_upload_id
+        - cloud_key
+        - total_parts
+        - uploaded_parts
+        - next_part_number_marker
+        - is_truncated
+        - manifest_expires_at
+        - recommended_chunk_size
+      properties:
+        upload_id:
+          $ref: '#/components/schemas/UuidV7'
+          description: Session identifier (matches the path `uploadId` and the initiate response `upload_id`).
+        multipart_upload_id:
+          type: string
+          description: |
+            S3 multipart upload identifier returned by `CreateMultipartUpload`.
+            Opaque to API consumers; emitted for diagnostic visibility
+            (SDK logs / dashboards correlating against AWS CloudTrail).
+        cloud_key:
+          type: string
+          description: |
+            S3 object key under which the assembled object will be
+            stored on `multipart/complete`. Opaque to consumers.
+        total_parts:
+          type: integer
+          minimum: 2
+          maximum: 10000
+          description: |
+            Total number of parts the client must upload to complete
+            the session. Same value as `MultipartInitiateResponse.total_parts`
+            and stable for the lifetime of the session.
+        uploaded_parts:
+          type: array
+          description: |
+            Parts already present in S3 for this session, as reported
+            by S3 ListParts at request time. May be empty (no parts
+            uploaded yet) or partial (resume mid-upload). Order is the
+            S3-native part-number ascending.
+          items:
+            $ref: '#/components/schemas/MultipartPartListing'
+        next_part_number_marker:
+          description: |
+            S3 ListParts cursor — pass this as the next request's
+            `cursor` query parameter to fetch the following page.
+            `null` on the final page (or when `is_truncated: false`).
+            Mirrors the S3 `NextPartNumberMarker` field verbatim.
+
+            Upper bound matches the request `cursor` query parameter
+            range (`0..9999`) so SDKs can round-trip the marker
+            verbatim — `total_parts` caps at 10,000 and the cursor
+            semantically means "list after part N", so the highest
+            reachable marker is 9,999 (any cursor of 10,000 would
+            return an empty page).
+          oneOf:
+            - type: integer
+              minimum: 0
+              maximum: 9999
+            - type: 'null'
+        is_truncated:
+          type: boolean
+          description: |
+            `true` when more pages remain; `false` on the final page.
+            Mirrors the S3 ListParts `IsTruncated` field verbatim.
+        manifest_expires_at:
+          description: |
+            ISO-8601 expiry timestamp of the session manifest. `null`
+            when the TTL has lapsed or was not initialised — in that
+            case, callers SHOULD invoke
+            `POST /api/uploads/multipart/{uploadId}/keepalive` to
+            re-establish a 48 h window before re-presigning. The
+            manifest TTL is decoupled from individual presigned-URL
+            TTLs.
+          oneOf:
+            - type: string
+              format: date-time
+            - type: 'null'
+        recommended_chunk_size:
+          type: integer
+          minimum: 16777216
+          maximum: 104857600
+          description: |
+            Chunk size (bytes) the server recommends for any remaining
+            parts in this session — identical to
+            `MultipartInitiateResponse.recommended_chunk_size` (16 MiB
+            floor / 100 MiB ceiling per CON-1 / ADR-0011). Returned on
+            every page so the client doesn't need to retain the
+            initiate response across a resume.
+
+    MultipartStatusSuccessEnvelope:
+      type: object
+      required:
+        - success
+        - data
+      properties:
+        success:
+          type: boolean
+          enum: [true]
+        data:
+          $ref: '#/components/schemas/MultipartStatusResponse'
+
+    MultipartPresignRequest:
+      type: object
+      description: |
+        Caller-supplied subset of part numbers to re-presign. Request
+        body for `POST /api/uploads/multipart/{uploadId}/presign`.
+      required:
+        - part_numbers
+      properties:
+        part_numbers:
+          type: array
+          minItems: 1
+          maxItems: 100
+          uniqueItems: true
+          description: |
+            Part numbers to re-presign. Each entry MUST satisfy
+            `2 ≤ n ≤ total_parts` from the initiate response —
+            **Part 1 is rejected** because the manifest stores its
+            ETag from `/initiate` and re-presigning would break the
+            eventual `multipart/complete` call. Cap of 100 entries
+            per request; SDKs paginate larger resume sets across
+            multiple `/presign` calls.
+          items:
+            type: integer
+            minimum: 2
+            maximum: 10000
+
+    MultipartPresignResponse:
+      type: object
+      description: |
+        Pre-signed URLs for the parts requested via
+        `MultipartPresignRequest.part_numbers`. The `data` payload on
+        `POST /api/uploads/multipart/{uploadId}/presign`.
+      required:
+        - upload_id
+        - presigned_urls
+      properties:
+        upload_id:
+          $ref: '#/components/schemas/UuidV7'
+          description: Session identifier (echoes the path `uploadId`).
+        presigned_urls:
+          type: array
+          minItems: 1
+          maxItems: 100
+          description: |
+            One pre-signed PUT URL per requested part number, in the
+            same order as `MultipartPresignRequest.part_numbers`. Each
+            item carries `part_number` + `url` + `expires_at` —
+            same shape as `MultipartInitiateResponse.presigned_urls[]`.
+          items:
+            $ref: '#/components/schemas/PresignedUrlPart'
+
+    MultipartPresignSuccessEnvelope:
+      type: object
+      required:
+        - success
+        - data
+      properties:
+        success:
+          type: boolean
+          enum: [true]
+        data:
+          $ref: '#/components/schemas/MultipartPresignResponse'
+
+    MultipartKeepaliveResponse:
+      type: object
+      description: |
+        Refreshed manifest TTL for an in-flight multipart session. The
+        `data` payload on `POST /api/uploads/multipart/{uploadId}/keepalive`.
+      required:
+        - upload_id
+        - manifest_expires_at
+      properties:
+        upload_id:
+          $ref: '#/components/schemas/UuidV7'
+          description: Session identifier (echoes the path `uploadId`).
+        manifest_expires_at:
+          type: string
+          format: date-time
+          description: |
+            ISO-8601 expiry timestamp of the refreshed manifest. Always
+            non-null on a successful 200 response — keepalive
+            unconditionally extends the TTL to 48 h ahead of `now`.
+
+    MultipartKeepaliveSuccessEnvelope:
+      type: object
+      required:
+        - success
+        - data
+      properties:
+        success:
+          type: boolean
+          enum: [true]
+        data:
+          $ref: '#/components/schemas/MultipartKeepaliveResponse'
+
     # ============================================
     # METADATA SCHEMAS
     # ============================================
@@ -6293,6 +7204,21 @@ components:
           description: Progress percentage (0-100). Present when in_progress or completed.
         result:
           $ref: '#/components/schemas/OperationResult'
+        error_code:
+          type: string
+          description: |
+            Machine-readable failure code. Present when `status` is `failed`;
+            absent otherwise. Mirrors `SseOperationFailedData.error_code` — the
+            same diagnostic the SSE `operation.failed` event carries, surfaced
+            here for polling consumers. Plain string (consumers duck-type on
+            it), e.g. `output_too_large`.
+          example: "output_too_large"
+        error_message:
+          type: string
+          description: |
+            Human-readable failure detail. Present when `status` is `failed`;
+            absent otherwise. Mirrors `SseOperationFailedData.error_message`.
+          example: "output_too_large: Output (12156489 bytes) is not smaller than input (6187609 bytes)"
 
     OperationResult:
       type: object
@@ -6370,12 +7296,37 @@ components:
 
     OperationDownload:
       type: object
+      description: |
+        A single deliverable output file for an operation. For multi-output
+        fan-out (e.g. convert PDF->image emits one file per page), each entry
+        carries an indexing field. This is the REST projection of the same
+        indexing model the AsyncAPI `OperationResultOutputEntry` defines per
+        ADR-0009 §D2 — `page_index` for PDF-page outputs, `position` for
+        generic ordinals, mutually exclusive within an entry.
       required:
         - operation
         - operation_id
         - filename
         - size_bytes
         - download_url
+      oneOf:
+        - title: PageIndexed
+          description: PDF-page output (convert PDF->image).
+          required: [page_index]
+          not: { required: [position] }
+        - title: PositionIndexed
+          description: Generic ordinal output (frame strip, chapter split).
+          required: [position]
+          not: { required: [page_index] }
+        - title: Unindexed
+          description: |
+            Output without an explicit indexing field — every legacy
+            single-output download. Schema-valid; emitted by all
+            non-fan-out operations.
+          not:
+            anyOf:
+              - required: [page_index]
+              - required: [position]
       properties:
         operation:
           type: string
@@ -6394,6 +7345,26 @@ components:
           type: string
           format: uri
           description: Pre-signed download URL
+        page_index:
+          type: integer
+          minimum: 1
+          description: |
+            1-based page number for PDF-page fan-out outputs (convert
+            PDF->image). Gapless within an operation (an N-page conversion
+            emits `page_index` 1..N). Mutually exclusive with `position`.
+            Absent on non-indexed (single-output) downloads. Mirrors
+            `OperationResultOutputEntry.page_index`. Per ADR-0009 §D2.
+          example: 1
+        position:
+          type: integer
+          minimum: 0
+          description: |
+            0-based ordinal for non-PDF multi-output operations (e.g. frame
+            strip, chapter split). Mutually exclusive with `page_index`.
+            Absent on non-indexed downloads. Forward-looking — not emitted by
+            any current operation; declared for parity with
+            `OperationResultOutputEntry.position`. Per ADR-0009 §D2.
+          example: 0
 
     # ============================================
     # SSE EVENT SCHEMAS