@giveitsmaller/contracts 0.58.0 → 0.59.0

package/openapi/api.yaml

@@ -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.171.0
+  version: 2.180.0
   contact:
     name: API Support
 
@@ -1192,6 +1192,28 @@ paths:
             minimum: 1
             maximum: 100
             default: 20
+        - name: archived
+          in: query
+          required: false
+          description: |
+            Archived-row filter (ticket
+            [`j2s6T2qf`](https://trello.com/c/j2s6T2qf)). **Default `false`**:
+            archived workflows are EXCLUDED, so archiving declutters the
+            default view. **`true`**: list ONLY archived workflows (the
+            "archive" view, for review or recovery via
+            `POST /api/workflows/{id}/restore`).
+
+            Archiving is a **recoverable declutter, NOT a delete** — an
+            archived workflow keeps every record and stays fully readable via
+            `GET /api/workflows/{id}/status` and its downloads; only this list
+            hides it by default. Archive an individual workflow via
+            `POST /api/workflows/{id}/archive`, restore it via
+            `POST /api/workflows/{id}/restore`. (A future "show both" view, if
+            needed, would be a separate additive parameter — this boolean
+            stays exclude-vs-archived-only.)
+          schema:
+            type: boolean
+            default: false
       responses:
         '200':
           description: Cursor-paginated summary list of the caller's workflows.
@@ -2513,6 +2535,186 @@ paths:
               schema:
                 $ref: '#/components/schemas/ErrorEnvelope'
 
+  /api/workflows/{id}/archive:
+    post:
+      summary: Archive a workflow
+      description: |
+        Archive a terminal workflow so it drops out of the caller's default
+        workflow list. **Recoverable declutter, NOT a delete** — the workflow,
+        its jobs, its operations, and its outputs are all retained and stay
+        fully readable: `GET /api/workflows/{id}/status` and every download
+        link keep working unchanged. Archiving only hides the row from the
+        default `GET /api/workflows` view; `?archived=true` lists archived
+        rows, and `POST /api/workflows/{id}/restore` brings one back.
+
+        Archive sets a dedicated `archived` flag that is **distinct from
+        deletion** — it is the Gmail-style "archive" (reversible, user-owned),
+        not the admin-only hard delete, and it does NOT set any soft-delete /
+        `deleted_at` state. Hard deletion is not exposed to callers.
+
+        Owner-scoped. Idempotent — archiving an already-archived workflow
+        returns 200 with the same shape (`archived_at` reflects the FIRST
+        archive instant, unchanged by a re-archive).
+
+        **Terminal workflows only.** Archive is allowed only once the workflow
+        has reached a terminal status (`completed`, `failed`,
+        `partially_failed`, `cancelled`, `expired`). Archiving an active
+        workflow (`pending`, `in_progress`, `paused_insufficient_credits`) is
+        a **409** — cancel it first (`POST /api/workflows/{id}/cancel`) or wait
+        for it to finish. Archiving does NOT change the workflow's status; it
+        stays terminal and the response echoes it unchanged.
+      operationId: archiveWorkflow
+      security: [{bearerAuth: []}, {sessionAuth: []}]  # required (explicit 401 in response set)
+      x-identity-scoped: true  # workflow-ownership-scoped per ADR-0016 D3
+      tags:
+        - Workflow
+      parameters:
+        - name: id
+          in: path
+          required: true
+          description: Workflow ID (UUID v7)
+          schema:
+            $ref: '#/components/schemas/UuidV7'
+      responses:
+        '200':
+          description: Workflow archived (or already archived — idempotent).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/WorkflowArchiveSuccessEnvelope'
+              examples:
+                archived:
+                  summary: Archive a completed workflow
+                  value:
+                    success: true
+                    data:
+                      workflow_id: "019539ac-2222-7000-8000-000000000001"
+                      status: "completed"
+                      archived: true
+                      archived_at: "2026-07-17T20:15:00Z"
+                idempotent_rearchive:
+                  summary: Archiving an already-archived workflow
+                  value:
+                    success: true
+                    data:
+                      workflow_id: "019539ac-2222-7000-8000-000000000002"
+                      status: "failed"
+                      archived: true
+                      archived_at: "2026-07-17T19:55:00Z"
+        '401':
+          description: Authentication required.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '404':
+          description: Workflow not found OR not owned by the caller (same shape — no ownership leak).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '409':
+          description: |
+            Workflow is in a non-terminal state (`pending`, `in_progress`,
+            `paused_insufficient_credits`) and cannot be archived yet — only
+            terminal workflows are archivable. Cancel it first
+            (`POST /api/workflows/{id}/cancel`) or wait for it to finish, then
+            retry. Check status via `GET /api/workflows/{id}/status`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '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'
+
+  /api/workflows/{id}/restore:
+    post:
+      summary: Restore (un-archive) a workflow
+      description: |
+        Restore a previously-archived workflow so it reappears in the caller's
+        default `GET /api/workflows` list. The exact inverse of
+        `POST /api/workflows/{id}/archive` — it clears the `archived` flag and
+        nothing else. Status, jobs, operations, outputs, and download links are
+        untouched (archiving never hid or changed any of those; it only hid the
+        list row).
+
+        Owner-scoped. Idempotent — restoring a workflow that is not archived
+        is a harmless no-op that returns 200 with `archived: false`. Because a
+        non-archived workflow can be in any lifecycle state, the echoed
+        `status` is the workflow's unchanged status (any `WorkflowStatus`
+        value), not a fixed terminal subset. There is no 409: un-archiving is
+        always safe.
+      operationId: restoreWorkflow
+      security: [{bearerAuth: []}, {sessionAuth: []}]  # required (explicit 401 in response set)
+      x-identity-scoped: true  # workflow-ownership-scoped per ADR-0016 D3
+      tags:
+        - Workflow
+      parameters:
+        - name: id
+          in: path
+          required: true
+          description: Workflow ID (UUID v7)
+          schema:
+            $ref: '#/components/schemas/UuidV7'
+      responses:
+        '200':
+          description: Workflow restored (or was already not archived — idempotent).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/WorkflowRestoreSuccessEnvelope'
+              examples:
+                restored:
+                  summary: Restore an archived workflow
+                  value:
+                    success: true
+                    data:
+                      workflow_id: "019539ac-2222-7000-8000-000000000001"
+                      status: "completed"
+                      archived: false
+                idempotent_restore:
+                  summary: Restoring a workflow that was not archived
+                  value:
+                    success: true
+                    data:
+                      workflow_id: "019539ac-2222-7000-8000-000000000002"
+                      status: "in_progress"
+                      archived: false
+        '401':
+          description: Authentication required.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '404':
+          description: Workflow not found OR not owned by the caller (same shape — no ownership leak).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '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'
+
   # ============================================
   # OPERATIONS ENDPOINTS
   # ============================================
@@ -5726,25 +5928,6 @@ components:
           const: upload
         file_id:
           $ref: '#/components/schemas/UuidV7'
-        declared_duration_seconds:
-          type:
-            - number
-            - "null"
-          minimum: 0
-          description: |
-            OPTIONAL client-declared media duration in seconds, measured on the
-            client **before** upload (e.g. the browser's
-            `HTMLVideoElement.duration`). A **routing hint** for long-form
-            classification only ([`frlwBuQ5`](https://trello.com/c/frlwBuQ5)):
-            the server prefers its own authoritative media probe and falls back
-            to this value **only when the async probe duration is null** (e.g.
-            the probe has not completed at classification time). It never
-            overrides a successful probe, and is not billed against — duration
-            billing uses the probed value. Omit (or `null`) when unknown —
-            **absent behaves exactly as today** (probe-only). Ignored for
-            non-timed media. Only meaningful on an `upload` source (the one the
-            client measured locally); other source leaves do not carry it.
-          example: 187.5
 
     JobOutputSource:
       type: object
@@ -6561,6 +6744,44 @@ components:
         offset:
           type: integer
           minimum: 0
+        current_cycle_net_spent:
+          type: integer
+          minimum: 0
+          description: |
+            OPTIONAL/additive. Net credits the caller has spent in the CURRENT
+            billing cycle — the monthly-grant period (ledger rows with
+            `created_at` >= the current cycle start). Integer credit units, same
+            as `CreditTransaction.amount` and the balance fields.
+
+            **"Net" = credits actually consumed**, i.e. reservation debits minus
+            the credit-returns that give credits back:
+
+                net = Σ |workflow-reservation debits|
+                      − Σ |credit-return rows|
+
+            Rows are identified by **`reference_type`, NOT `type`** — there is
+            no `type: refund` row. The debit is
+            `reference_type: workflow_reservation` (a negative `amount`); the
+            credit-return family is `reference_type` ∈ {`workflow_settle_refund`,
+            `workflow_reservation_release`, `workflow_pause_release`,
+            `workflow_expiry_release`} (positive amounts). This nets a fully
+            released / cancelled / expired reservation to ~0 and a settled one to
+            its non-refundable consumed portion — so it reflects credits ACTUALLY
+            consumed, not gross reservations (a raw settled-sum would overstate
+            spend, since the returns are separate positive rows). Mirrors the
+            reserved-minus-refunded semantics of the API's authoritative
+            `WorkflowCreditSummary` reads. **Absent** for legacy/unsupported
+            reads — treat as unknown, not `0`. Per ticket
+            [`5aXGShPy`](https://trello.com/c/5aXGShPy).
+        lifetime_net_spent:
+          type: integer
+          minimum: 0
+          description: |
+            OPTIONAL/additive. Same net-of-credit-returns formula as
+            `current_cycle_net_spent`, but ALL-TIME (no cycle window) — the
+            caller's total credits ever consumed. Integer credit units.
+            **Absent** for legacy/unsupported reads — treat as unknown, not `0`.
+            Per ticket [`5aXGShPy`](https://trello.com/c/5aXGShPy).
 
     CreditsUsageSuccessEnvelope:
       type: object
@@ -6817,6 +7038,99 @@ components:
         data:
           $ref: '#/components/schemas/WorkflowResumeResponse'
 
+    WorkflowArchiveResponse:
+      type: object
+      description: |
+        Response body for `POST /api/workflows/{id}/archive` (ticket
+        [`j2s6T2qf`](https://trello.com/c/j2s6T2qf)). Archiving sets the
+        `archived` flag so the row drops from the default workflow list; it
+        does NOT change the workflow's status, delete anything, or hide it from
+        `GET /api/workflows/{id}/status` or its downloads. Reversible via
+        `POST /api/workflows/{id}/restore`.
+      required:
+        - workflow_id
+        - status
+        - archived
+        - archived_at
+      properties:
+        workflow_id:
+          $ref: '#/components/schemas/UuidV7'
+        status:
+          type: string
+          enum:
+            - completed
+            - failed
+            - partially_failed
+            - cancelled
+            - expired
+          description: |
+            The workflow's UNCHANGED terminal status — archive never mutates
+            status, only sets the archived flag. Constrained to the terminal
+            subset of `WorkflowStatus` (the only archivable states); an active
+            workflow is a 409, never a 200.
+        archived:
+          type: boolean
+          enum: [true]
+          description: Always `true` on a 200 — the workflow is archived.
+        archived_at:
+          type: string
+          format: date-time
+          description: |
+            ISO-8601 timestamp the workflow was FIRST archived. Idempotent —
+            a re-archive of an already-archived workflow returns the original
+            `archived_at`, unchanged.
+
+    WorkflowArchiveSuccessEnvelope:
+      type: object
+      additionalProperties: false
+      required:
+        - success
+        - data
+      properties:
+        success:
+          type: boolean
+          enum: [true]
+        data:
+          $ref: '#/components/schemas/WorkflowArchiveResponse'
+
+    WorkflowRestoreResponse:
+      type: object
+      description: |
+        Response body for `POST /api/workflows/{id}/restore` (ticket
+        [`j2s6T2qf`](https://trello.com/c/j2s6T2qf)). Restoring clears the
+        `archived` flag so the workflow reappears in the default list. The
+        inverse of archive — status, jobs, outputs, and downloads are
+        untouched.
+      required:
+        - workflow_id
+        - status
+        - archived
+      properties:
+        workflow_id:
+          $ref: '#/components/schemas/UuidV7'
+        status:
+          $ref: '#/components/schemas/WorkflowStatus'
+        archived:
+          type: boolean
+          enum: [false]
+          description: |
+            Always `false` on a 200 — the workflow is no longer archived
+            (or was never archived; restore is an idempotent no-op there).
+            No `archived_at` is returned once restored.
+
+    WorkflowRestoreSuccessEnvelope:
+      type: object
+      additionalProperties: false
+      required:
+        - success
+        - data
+      properties:
+        success:
+          type: boolean
+          enum: [true]
+        data:
+          $ref: '#/components/schemas/WorkflowRestoreResponse'
+
     WorkflowExpiredResponse:
       allOf:
         - $ref: '#/components/schemas/ErrorEnvelope'
@@ -9393,12 +9707,29 @@ components:
       description: |
         Caller-supplied logical-policy hint on `WorkflowCreateRequest`.
         NOT a backend selector — server is final authority on routing.
+
+        `auto` is the only committed value; the other three are
+        `planned` — the API runtime returns `422 feature_not_available`
+        for any non-`auto` value until they ship. Value availability is
+        carried by `per_value_availability` below and promoted to the
+        authoritative sidecar as
+        `workflow_features.processing.class_hint` (keyed by request-shape
+        path, mirroring `workflow_features.delivery.mode`; the decorative
+        `x-availability`/openapi is not authoritative — consumers read the
+        runtime endpoint / sidecar).
+
         - `auto` (default): server routes safely.
-        - `short_form_only`: fail fast (422 with `reason:
-          tier_policy`) if any job would require `long_form`.
-        - `long_form_allowed`: caller accepts slower queue/runtime
-          semantics.
-        - `long_form_preferred`: prefer `long_form` pool when
+        - `short_form_only` (planned): once shipped, fails fast when any
+          job would require `long_form`. The dedicated fail-fast reject
+          envelope is defined at graduation (co-design with the API
+          handler); while planned the reject is the standard
+          `feature_not_available`. NOTE: `tier_policy` is a success-path
+          advisory reason on `ProcessingClassReason` (why an honored
+          hint drove classification), NOT a 422 reject reason —
+          `ProcessingClassRejectReason` stays ceiling-reasons only.
+        - `long_form_allowed` (planned): caller accepts slower
+          queue/runtime semantics.
+        - `long_form_preferred` (planned): prefer `long_form` pool when
           eligible (test/isolation use cases).
       enum:
         - auto
@@ -9406,6 +9737,11 @@ components:
         - long_form_allowed
         - long_form_preferred
       default: auto
+      per_value_availability:
+        auto: { availability: stable }
+        short_form_only: { availability: planned }
+        long_form_allowed: { availability: planned }
+        long_form_preferred: { availability: planned }
 
     EstimateQuality:
       type: string
@@ -10438,10 +10774,16 @@ components:
           minimum: 0
           description: |
             OPTIONAL. Final job output size in bytes — the right side of the
-            savings readout. The aggregate deliverable size for the job (the
-            authoritative per-output sizes remain on
-            `GET /{id}/downloads`). Absent until the job completes / when not
-            applicable.
+            before→after savings readout. The **main/terminal deliverable's**
+            size: the **highest-position completed non-thumbnail** operation's
+            output — **NOT a sum across the job's operations** (a thumbnail's
+            size is excluded; for a compress+thumbnail job this is the compressed
+            output). Authoritative per-output sizes remain on
+            `GET /{id}/downloads`. Populated from the highest-position COMPLETED
+            op, so it is **PROVISIONAL while the job is still running** (a
+            later-completing op can become the main deliverable and change this
+            value) and final only once the job reaches a **terminal** status.
+            Absent until a non-thumbnail op has completed with a recorded size.
           example: 491520
         operation_types:
           type: array
@@ -10506,6 +10848,24 @@ components:
           oneOf:
             - $ref: '#/components/schemas/WorkflowCreditSummary'
             - type: 'null'
+        archived:
+          type: boolean
+          description: |
+            Whether this workflow is archived (hidden from the default list;
+            surfaced only via `?archived=true`). Set by
+            `POST /api/workflows/{id}/archive`, cleared by
+            `POST /api/workflows/{id}/restore`. Archiving is a recoverable
+            declutter — it does NOT delete the workflow or hide it from
+            `GET /api/workflows/{id}/status` or its downloads. **OPTIONAL
+            (additive)** — absent is treated as `false` (not archived),
+            covering legacy rows written before this field existed. Per ticket
+            [`j2s6T2qf`](https://trello.com/c/j2s6T2qf).
+        archived_at:
+          type: string
+          format: date-time
+          description: |
+            ISO-8601 timestamp the workflow was archived. Present only when
+            `archived: true`; absent otherwise. Additive/optional.
 
     WorkflowCreditSummary:
       type: object
@@ -10787,6 +11147,28 @@ components:
             per-operation `OperationResult.size_bytes` / `GET /{id}/downloads`).
             OPTIONAL for the same webhook-payload reason as `input_filename`.
           example: 1258291
+        output_size_bytes:
+          type: integer
+          format: int64
+          minimum: 0
+          description: |
+            OPTIONAL. Final job output size in bytes — the **right** side of the
+            before→after savings readout. The **main/terminal deliverable's**
+            size: the **highest-position completed non-thumbnail** operation's
+            output — **NOT a sum across the job's operations** (a thumbnail's
+            size is excluded; for a compress+thumbnail job this is the compressed
+            output). Authoritative per-output sizes remain on
+            `GET /{id}/downloads`. The drill-in mirror of
+            `WorkflowSummaryJob.output_size_bytes` (same semantics); pairs with
+            `input_size_bytes` above. Populated from the highest-position
+            COMPLETED op, so it is **PROVISIONAL while the job is still running**
+            (a later-completing op can become the main deliverable and change
+            this value) and final only once the job reaches a **terminal**
+            status. Absent until a non-thumbnail op has completed with a recorded
+            size, and OPTIONAL for the same webhook-payload reason as
+            `input_filename`. Ticket [`j2s6T2qf`](https://trello.com/c/j2s6T2qf)
+            (FE before→after size, workflow-view launch ask).
+          example: 491520
         processing_class:
           $ref: '#/components/schemas/ProcessingClass'
           description: |
@@ -11190,7 +11572,100 @@ components:
           $ref: '#/components/schemas/UuidV7'
         filename:
           type: string
-          description: Output filename
+          description: |
+            The **download filename** the API synthesises for this output — a
+            human-friendly, extension-bearing name. This is a DIFFERENT surface
+            from the S3 object key (an opaque UUID/`output-NNN` leaf governed by
+            ADR-0014 §D9); the two are independent by design. Composed as
+            `<stem><marker><suffix><.ext>`:
+
+            - **stem** — derived from the originating upload's `original_name`
+              (a chained job resolves through its upstream to the original
+              upload; path separators, control characters and quotes stripped);
+              collapses to `download` if the sanitised stem is empty. When there
+              is **no** original name at all (a `job_output`-sourced job with no
+              upstream upload, or an unrecorded/purged name — rare), the whole
+              field falls back to the S3-key basename **as-is, unmarked**; the
+              per-op marker below applies only to the `original_name`-derived
+              stem, so that fallback path is the one unlabelled case and is
+              outside this map's scope.
+            - **marker** — a per-operation label so **every** processed output
+              is self-describing: it names what the output IS and disambiguates
+              the different operations of a job from each other and from the
+              original (ticket [`50obWMbm`](https://trello.com/c/50obWMbm), user
+              launch feedback — the user hit a watermarked-main + thumbnail
+              collision within one job). **Scope:** the marker resolves
+              within-job and vs-original ambiguity, NOT workflow-wide uniqueness
+              — two SEPARATE jobs running the same op on the same-named upload
+              still produce the same name (a rarer case a job/node identifier
+              would address; out of scope for this label map). **Invariant, with
+              two explicit exceptions:** every op below **except `passthrough`**
+              carries a non-empty marker, so a terminal deliverable **derived
+              from an `original_name`** never falls back to a bare, op-less stem
+              (the bug this fixes). The two exceptions are inline: `passthrough`
+              (the identity op — its output IS the original) and the
+              no-`original_name` S3-key fallback described under **stem** above. The
+              canonical marker is keyed on the **public (masked) operation
+              type** — a long-form concat surfaces as `compress` and carries its
+              marker:
+                - `compress` → `-compressed`
+                - `thumbnail` (and the `thumbnail_image` / `thumbnail_video` /
+                  `thumbnail_document` / `thumbnail_office` sub-types, which all
+                  surface publicly as `thumbnail`) → `-thumbnail`
+                - `image_watermark` / `text_watermark` / `video_watermark` /
+                  `video_text_watermark` / `audio_watermark` → `-watermarked`
+                - `convert` → `-converted` (the extension changes too, but the
+                  marker keeps naming consistent — no operation is a special case)
+                - `merge` → `-merged`
+                - `transform` → `-transformed`
+                - `custom_luma` → `-graded`
+                - `audio_overlay` → `-overlay`
+                - `audio_to_video` → `-video`
+                - `render_variants` → `-variant`
+                - `split` → `-part`, plus the `-<n>` piece suffix (below) when
+                  the run yields more than one piece. The word-marker is required
+                  because a split can legally produce a SINGLE output (e.g.
+                  `frame_range: "5-5"`, a one-page PDF range, or an interval that
+                  exceeds the media duration) — without it a single-piece split
+                  would fall back to the bare original stem.
+                - `archive` → `-archive` (the archive OPERATION's output). Note:
+                  the workflow `delivery.bundle` path names its zip from
+                  `delivery.bundle_filename` instead — that is a separate surface
+                  and takes precedence when a bundle is requested.
+                - `passthrough` → **none, by design** — it emits the input
+                  UNCHANGED (it is the identity/plumbing op), so its output IS the
+                  original file and carries the original name. It is normally
+                  consumed by a downstream job (not a terminal deliverable); when
+                  it is a leaf, returning the original name is correct, not a
+                  mislabel.
+              **This whole map is co-owned with `compression_api`'s
+              `DownloadFilenameComputer`** (as the `MIME_EXTENSION` table is) —
+              api implements it; contracts is the normative source.
+            - **suffix** — `-<n>` **only** when the operation produced more than
+              one output. `<n>` is the output's **0-based position in the
+              producer's `outputs[]` array** — a uniqueness key. It is
+              **INDEPENDENT of `page_index` and must NOT be read as a page
+              number**: a `pages: '5-7'` PDF fan-out emits
+              `{ filename: "report-converted-0.png", page_index: 5 }` (PDF→PNG is a
+              `convert`, hence `-converted`) — the `-0` is the
+              array position, `5` is the source page. Reconciling them is a bug.
+            - **.ext** — the extension of the **actual produced format**, never
+              the input's and never guessed. Resolved from the worker-reported
+              `output_file_type` (AsyncAPI `OperationResult.output_file_type`,
+              ADR-0022) when present — authoritative for formats the API cannot
+              infer (e.g. `compress.output_format` ∈ `{auto, smallest}`) — else
+              derived from the operation chain. The chain additionally
+              disambiguates a MIME→extension collision even when the MIME is
+              known (`audio/ogg` → `.ogg` for Vorbis vs `.opus` for Opus). When
+              the produced format is
+              genuinely unknown at download time the name is emitted with **no
+              extension** rather than a wrong one. `split` and `audio_to_video`
+              derive to no format, so their extension comes **only** from
+              `output_file_type`.
+
+            Sanitised for JSON (Unicode-safe); the `Content-Disposition` header
+            on the presigned `download_url` is ASCII-sanitised separately, so
+            the two user-visible names may legitimately differ.
           example: "photo.jpg"
         size_bytes:
           type: integer
@@ -11243,9 +11718,14 @@ components:
           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`.
+            1-based **literal source page number** for PDF-page fan-out
+            outputs (convert PDF->image) — the actual page from the input PDF.
+            A full conversion emits `1..N`; a sparse `pages` selection (e.g.
+            `'1-5,8'`) emits exactly the selected pages (`1,2,3,4,5,8`), so it
+            is gapless ONLY for a full conversion, not for a sparse selection.
+            NOT the download `filename` suffix (that is a 0-based array
+            position — see `OperationDownload.filename`). Mutually exclusive with `position`.
+            Normative semantics: ADR-0009 §D2.
             Absent on non-indexed (single-output) downloads. Mirrors
             `OperationResultOutputEntry.page_index`. Per ADR-0009 §D2.
           example: 1
@@ -11681,9 +12161,14 @@ components:
           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`.
+            1-based **literal source page number** for PDF-page fan-out
+            outputs (convert PDF->image) — the actual page from the input PDF.
+            A full conversion emits `1..N`; a sparse `pages` selection (e.g.
+            `'1-5,8'`) emits exactly the selected pages (`1,2,3,4,5,8`), so it
+            is gapless ONLY for a full conversion, not for a sparse selection.
+            NOT the download `filename` suffix (that is a 0-based array
+            position — see `OperationDownload.filename`). Mutually exclusive with `position`.
+            Normative semantics: ADR-0009 §D2.
             Absent on non-indexed outputs. Mirrors
             `OperationResultOutputEntry.page_index`. Per ADR-0009 §D2.
           example: 1
@@ -11942,6 +12427,8 @@ components:
               schema)
             - `delivery.selection.type.per_value_availability` (from the
               `DeliverySelection.type` schema)
+            - `processing.class_hint.per_value_availability` (from the
+              `ProcessingClassHint` enum — ticket `tK81wZKJ`)
 
             Closes the co0CERtJ (v2.19.0) authority-hierarchy gap: those
             `planned` downgrades lived only in the (decorative per ADR-0001
@@ -11971,6 +12458,14 @@ components:
                       properties:
                         per_value_availability:
                           $ref: '#/components/schemas/PerValueAvailability'
+            processing:
+              type: object
+              properties:
+                class_hint:
+                  type: object
+                  properties:
+                    per_value_availability:
+                      $ref: '#/components/schemas/PerValueAvailability'
         image_encode_capabilities:
           description: |
             Pre-flight image-encode capability matrix
@@ -12546,6 +13041,40 @@ components:
             [I3](https://trello.com/c/eCWIpug8); until then the
             contract advertises the field shape but the endpoint
             does not yet surface the field.
+        max_input_size_bytes:
+          type: integer
+          format: int64
+          minimum: 1
+          description: |
+            Optional mime-group-level INPUT-file size ceiling in BYTES
+            (ticket [`uKsFzORi`](https://trello.com/c/uKsFzORi)). Sibling of
+            `max_output_pixels`. **Applies to the enclosing operation's input** —
+            currently authored on `compress` image/document groups (the API
+            enforces it on compress input only: AVIF 20 MiB, other images 500 MiB,
+            office/ODF/EPUB 100 MiB). A consumer MUST scope it to the operation
+            whose schema carries it and MUST NOT assume it applies to other
+            operations. An oversize input is rejected at create-time (ADR-0012
+            band-ceiling 422 family).
+
+            **XOR with `processing_class` caps (ADR-0011):** a group carries this
+            group-level cap ONLY when it has NO `processing_class` band. Banded
+            media (e.g. `video`) put input caps in
+            `processing_class.<class>.constraints.max_input_size_bytes` instead —
+            never both, so the input ceiling lives in exactly one place per group.
+            CI-enforced by `scripts/check-per-tier-constraints.py`.
+        max_input_duration:
+          type: string
+          description: |
+            Optional mime-group-level INPUT duration ceiling as an ISO-8601
+            duration string (ticket [`KzrquIX7`](https://trello.com/c/KzrquIX7)) —
+            e.g. `"PT2H"`. Sibling of `max_output_pixels`; same
+            XOR-with-`processing_class` rule as `max_input_size_bytes`
+            (group-level ONLY where no `processing_class` band; banded media use
+            `processing_class.<class>.constraints.max_input_duration`). Currently
+            authored on `audio_to_video.audio` (2h input cap, mirroring the
+            worker's audio-duration limit). Over-cap inputs are rejected at
+            create-time.
+          example: "PT2H"
         processing_class:
           type: object
           description: |