@giveitsmaller/contracts 0.58.0 → 0.60.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.188.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.
@@ -1963,7 +1985,7 @@ paths:
                         message: "Inputs use different frame rates (29.97 vs 30); set re_encode_mode to auto or always."
         '429':
           description: |
-            Rate limited. Two distinct triggers share this status — branch
+            Rate limited. Three distinct triggers share this status — branch
             on the `error` code, NOT on the status:
 
             1. **Long-form concurrency cap** — the caller already holds the
@@ -1977,13 +1999,31 @@ paths:
             2. **Infrastructure rate-limit** — too many requests in the
                current window. The links-absent subset of the same shape: a
                plain `ErrorEnvelope` with a `Retry-After` header.
+            3. **Duplicate in progress** — the caller resubmitted an
+               identical workflow whose idempotency claim is already held by
+               an in-flight create (deduplication that prevents a
+               double-charge; ticket
+               [`DSxwCetg`](https://trello.com/c/DSxwCetg)). Body is a plain
+               `ErrorEnvelope`: `error: DUPLICATE_IN_PROGRESS`, `message_key:
+               job.duplicate_in_progress`, **no `Retry-After`** and **no
+               `links`**. **Transient — the caller SHOULD retry:** the retry
+               folds onto the now-attached winning workflow and returns
+               `201` with that existing workflow (the normal create shape),
+               so the winning `workflow_id` is delivered on the retry, not
+               here. There is no id to return at this point — the winner is
+               still mid-create (its `workflow_id` is not yet assigned), which
+               is exactly what "in progress" means. This is why the status is
+               `429` (retry-with-backoff resolves it) rather than `409`.
           headers:
             Retry-After:
               description: |
                 Seconds to wait before retrying. Delta-seconds (RFC 9110).
                 Present ONLY for the infrastructure rate-limit trigger —
-                ABSENT for `LONG_FORM_CONCURRENCY_LIMIT_EXCEEDED` (that
-                limit clears on workflow completion, not on a timer).
+                ABSENT for `LONG_FORM_CONCURRENCY_LIMIT_EXCEEDED` (clears on
+                workflow completion, not a timer) and for
+                `DUPLICATE_IN_PROGRESS` (resolves when the caller retries and
+                folds onto the winning workflow — retry promptly, no fixed
+                back-off window).
               schema:
                 type: integer
                 minimum: 0
@@ -2008,6 +2048,14 @@ paths:
                   value:
                     success: false
                     error: "Too many requests. Please try again later."
+                duplicate_in_progress:
+                  summary: Identical workflow already mid-create (idempotency fold — retry to get the 201-with-existing-workflow)
+                  value:
+                    success: false
+                    error: "DUPLICATE_IN_PROGRESS"
+                    message: "An identical workflow is already being created. Retry in a moment to attach to it."
+                    message_key: "job.duplicate_in_progress"
+                    locale: "en-GB"
         '500':
           description: Internal server error
           content:
@@ -2513,6 +2561,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
   # ============================================
@@ -5552,6 +5780,34 @@ components:
         - planned
         - deprecated
 
+    PerClassAvailabilityEntry:
+      type: object
+      description: |
+        Availability of an option (or one of its values) on ONE execution
+        class. Attached as a value within a `per_class_availability` map,
+        keyed by a `processing_class` name the parent mime_group
+        declares.
+
+        Exists because `processing_class:` is a SIBLING of `options:`,
+        not a parent, so without this overlay "honoured on short-form,
+        unavailable on long-form" is inexpressible and the only
+        instrument is an operation-wide `planned` — which withdraws a
+        working capability from every caller to describe one path's gap.
+
+        **May only RESTRICT** relative to the scope it overlays, never
+        re-open it (`schemas/FORMAT.md` §Precedence; machine-enforced).
+      required:
+        - availability
+      properties:
+        availability:
+          $ref: '#/components/schemas/AvailabilityValue'
+        eta:
+          type: string
+          description: ISO-8601 date or quarter when this class is expected to support it.
+        documentation_url:
+          type: string
+          format: uri
+
     PerValueAvailabilityEntry:
       type: object
       description: |
@@ -5570,11 +5826,50 @@ components:
         present in this map MUST be a subset of the option's `values[]`
         array — verified by `make check-per-value-availability`
         (`scripts/check-per-value-availability.py`).
+
+        **`availability` is ALWAYS required, including when
+        `per_class_availability` is present.** An entry carrying a
+        per-class overlay MUST also state the blanket truth:
+
+            target_size:
+              availability: stable          # true on every other path
+              per_class_availability:
+                long_form_re_encode: { availability: planned }
+
+        **Ruled 2026-07-29, reversing an earlier reading of mine that
+        the absence of a blanket tag was itself the statement.** Three
+        reasons, and the third is the one that decided it:
+
+        1. It keeps the restrict-only check **LOCAL** — the value an
+           overlay is compared against sits in the same entry, instead
+           of requiring a walk up to option/group/operation scope that
+           must be got right at every nesting depth.
+        2. It keeps consumers' parsers correct as written: requiring the
+           blanket value IS the rule they already enforce.
+        3. **It stops the absence of a key carrying meaning.** A reader
+           seeing only `per_class_availability` would have to INFER the
+           general level from a key that is not there — the failure
+           shape this contract spent 2026-07-28 removing everywhere
+           else, and it should not be reintroduced here.
+
+        Nothing is lost by requiring it: the blanket value is `stable`,
+        which is TRUE, and most-cautious inheritance then yields the
+        intended behaviour from the per-class restriction on top.
       required:
         - availability
       properties:
         availability:
           $ref: '#/components/schemas/AvailabilityValue'
+        per_class_availability:
+          type: object
+          description: |
+            Per-execution-class overlay for this enum value: restricts it
+            on named `processing_class` entries of the parent mime_group
+            while leaving the others at the inherited level. Keys MUST be
+            classes the group declares. See `schemas/FORMAT.md`
+            §`per_class_availability`.
+          additionalProperties:
+            $ref: '#/components/schemas/PerClassAvailabilityEntry'
         required_tier:
           description: |
             Tier required to use this enum value. Optional — omit when
@@ -5713,6 +6008,7 @@ components:
 
     UploadSource:
       type: object
+      additionalProperties: false  # closed to the API allowlist {type, file_id} — fZXM5VZd
       description: |
         References an upload created via `POST /api/uploads` (single)
         or completed via `POST /api/uploads/multipart/complete`
@@ -5726,28 +6022,10 @@ 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
+      additionalProperties: false  # closed to the API allowlist {type, from, operation} — fZXM5VZd
       description: |
         References the output of an upstream job in the same workflow.
         Used to chain operations: workflow runs job A first, then job B
@@ -5771,6 +6049,7 @@ components:
 
     ExternalImportToken:
       type: object
+      additionalProperties: false  # closed to the API allowlist {type, external_source_id} — fZXM5VZd
       description: |
         Opaque handle returned by `POST /api/external-imports` for a
         one-shot bearer URL (S3 presigned, GCS signed, Azure SAS,
@@ -5790,6 +6069,7 @@ components:
 
     ConnectionSource:
       type: object
+      additionalProperties: false  # closed to the API allowlist {type, connection_id, path} — fZXM5VZd
       description: |
         Reference to a vaulted connection (pre-registered via
         `POST /api/connections` — owned by cross-repo `compression_api`
@@ -5830,6 +6110,17 @@ components:
 
         Wiring into `JobDefinition` lands via ticket
         [I12 (`Gr0VKFya`)](https://trello.com/c/Gr0VKFya).
+
+        **All four leaves are CLOSED** (`additionalProperties: false`) to
+        exactly the API's per-leaf allowlist (`WorkflowSourceV2Constraint`,
+        which hard-rejects any extra key). This is a deliberate forward-compat
+        stance (ticket [`fZXM5VZd`](https://trello.com/c/fZXM5VZd)): a client
+        sending a *future* additive field fails contract-validation the same way
+        the API already rejects it — so contract and runtime agree. Adding a new
+        field to a leaf therefore requires a paired API-allowlist change in the
+        same co-land. The union aliases themselves (`WorkflowSource`,
+        `MultiInputSource`, `ExternalSource`) stay open — they are `oneOf`
+        dispatchers, not property-bearing objects.
       oneOf:
         - $ref: '#/components/schemas/UploadSource'
         - $ref: '#/components/schemas/JobOutputSource'
@@ -6561,6 +6852,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
@@ -6693,7 +7022,10 @@ components:
         documented string (not a strict enum) so the rate-limit subset
         validates against the same schema and consumers tolerate unknown
         codes; SDKs branch on the `LONG_FORM_CONCURRENCY_LIMIT_EXCEEDED`
-        value to distinguish the two.
+        value to distinguish it. A third links-absent branch shares this
+        `429`: `DUPLICATE_IN_PROGRESS` (idempotency fold, ticket
+        [`DSxwCetg`](https://trello.com/c/DSxwCetg)) — see the endpoint's
+        `429` response description for the full trigger list.
 
         Mirrors the runtime shape produced by `compression_api`'s
         `WorkflowController` +
@@ -6817,6 +7149,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 +9818,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 +9848,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
@@ -9462,6 +9909,82 @@ components:
         - `tier_policy`: emitted when the caller's
           `processing.class_hint` (e.g. `short_form_only`) forced
           the decision rather than input characteristics.
+        - `input_metrics_unavailable`: **the classifier did not have
+          every metric the decision required.** One or more of the
+          duration / size figures it needed was unavailable at
+          create-plan time (e.g. an upload probe had not landed), so a
+          class was DEFAULTED rather than chosen. Note this covers the
+          PARTIAL case as well as the none-at-all case — see below;
+          having *some* metrics is not having the metric the decision
+          required. **This is the only
+          value that does not assert a measurement.** Every other value
+          states a fact about the input; this one states that no such
+          fact was obtained.
+
+          **It is a reason a class was DEFAULTED, not a reason a class
+          was CHOSEN** — despite sitting in `ProcessingClassReason`.
+          Read it as *no routing claim was made*. Consumers MUST NOT
+          read the assigned `processing_class` as evidence the input
+          fits that class's constraints when this reason is present,
+          and MUST NOT surface it as a positive statement about the
+          file.
+
+          **Partial measurement usually counts as unmeasured.** On a
+          multi-input operation, emit this whenever a contributing
+          input lacked the metric the decision needed — a sum over the
+          inputs that happened to be probed is not a measurement of the
+          request, even though it is not empty either. The honest
+          predicate is "did I have every metric this decision required",
+          not "did I have some".
+
+          **The exception, and it is a principle rather than a special
+          case: partial evidence that is DECISIVE is still evidence.**
+          Ask whether the missing data could FALSIFY the claim the
+          reason makes:
+
+          - `within_short_form_limits` claims the input **fits**. An
+            unmeasured input can only ADD to the sum, so it could push
+            the request over the cap — the missing data can falsify the
+            claim. This reason therefore requires COMPLETE measurement,
+            and a partial sum must report `input_metrics_unavailable`.
+          - `input_duration_exceeds_short_form` /
+            `input_size_exceeds_short_form` claim the input **exceeds**
+            a cap. The sums are MONOTONE — they only grow — so once the
+            measured subset alone crosses the cap, the missing data
+            cannot falsify the claim. The escalation is positively
+            evidenced, and the decision did not *need* the missing
+            metric. **Report the real reason, NOT
+            `input_metrics_unavailable`.**
+
+          Reporting "I could not measure" for a decision that WAS
+          positively evidenced is a lie in the opposite direction, and
+          it costs twice: it understates what the server knew, and —
+          because this field carries one value — it MASKS a more
+          specific true reason such as `merge_re_encode_long_form`.
+
+          **Generalise by the falsifiability test, not by the list
+          above.** If a future cap is a band rather than a ceiling, or
+          a metric can reduce a total, the monotonicity no longer holds
+          and the exception does not apply.
+
+          **Known limit, stated so it is not later read as a gap in a
+          completed fix:** an input whose probe landed with a duration
+          of **zero** counts as MEASURED and contributes 0 to the sum.
+          That is indistinguishable from a genuine zero-length input
+          from outside the classifier, so this value does not and
+          cannot cover it.
+
+        **Why this value exists (2026-07-28).** A deduplicated upload
+        (and, independently, a fresh upload racing an async probe)
+        reaches create-plan with no duration, and a 62-minute merge was
+        assigned `short_form` with reason `within_short_form_limits` —
+        an affirmative claim that a 62-minute input fits inside a
+        `PT5M` cap. The fallback was indistinguishable from a genuine
+        measurement, so the mis-route was invisible. A classifier that
+        cannot say *"I did not know"* has no way to be honest; this
+        value is that sentence. Emit it in preference to a
+        measurement-asserting value whenever the metrics were absent,
+        even if the class ultimately chosen happens to be correct.
       enum:
         - within_short_form_limits
         - input_size_exceeds_short_form
@@ -9469,6 +9992,7 @@ components:
         - merge_re_encode_long_form
         - requires_reencode
         - tier_policy
+        - input_metrics_unavailable
 
     ProcessingPlanJob:
       type: object
@@ -9509,6 +10033,90 @@ components:
           $ref: '#/components/schemas/EstimateQuality'
         reason:
           $ref: '#/components/schemas/ProcessingClassReason'
+        dropped_options:
+          type: array
+          description: |
+            Options the SERVER supplied on the caller's behalf and then
+            REMOVED, because the resolved execution path cannot honour
+            them. **Never contains a value the caller sent explicitly** —
+            an explicit option the path cannot honour is refused with
+            `422 feature_not_available`, not silently dropped. That
+            split is the whole rule: a caller who asked for nothing is
+            not punished for our default; a caller who asked for
+            something is told.
+
+            **Why this field exists at all.** Dropping a defaulted
+            option is better than refusing the request, and it is still
+            a silent no-op unless we say so — the caller asked for
+            (say) audio normalisation, we did not do it, and nobody
+            told them. This field is the "we did not do that" sentence,
+            the same honesty requirement as
+            `ProcessingClassReason.input_metrics_unavailable`.
+
+            **🔴 ABSENCE CARRIES NO INFORMATION until every server
+            emits it.** An empty array means "nothing was dropped". An
+            ABSENT array means "this server does not report drops" —
+            consumers MUST NOT read absence as "nothing was dropped".
+            Once the emitting side ships, the array is always present.
+          items:
+            $ref: '#/components/schemas/DroppedOption'
+
+    DroppedOption:
+      type: object
+      description: |
+        One server-supplied option removed from a job before dispatch.
+        **Names the THING, the WHY and the PATH** — the three parts a
+        caller needs to act, and the three a single interpolated string
+        would fuse into something unparseable.
+      required:
+        - option
+        - reason
+      properties:
+        option:
+          type: string
+          description: The option key that was removed, as it appears in the operation schema.
+          example: normalize_audio
+        operation_type:
+          type: string
+          description: |
+            The operation the option belonged to. Present because a job
+            may carry several operations, so the option key alone does
+            not identify where the drop happened.
+          example: merge
+        operation_id:
+          type: string
+          format: uuid
+          description: The specific operation, when the server can attribute the drop to one.
+        processing_class:
+          $ref: '#/components/schemas/ProcessingClass'
+        reason:
+          type: string
+          description: |
+            Why the option was dropped. **A documented vocabulary, NOT a
+            strict enum** — deliberately, following `error_code`: a
+            consumer MUST map known values to a friendly reason and
+            MUST degrade an unknown one, so the vocabulary can grow
+            without breaking clients.
+
+            **Known values:**
+
+            - `unavailable_on_processing_class` — the option is tagged
+              unavailable for the class this job resolved to (see
+              `per_class_availability` in `schemas/FORMAT.md`). The
+              `processing_class` field names which.
+            - `processing_class_unmeasured` — the class could NOT be
+              measured (see
+              `ProcessingClassReason.input_metrics_unavailable`), so the
+              option was dropped rather than refused. **Refusing a
+              caller on a guessed class is the same error as asserting
+              a measurement never taken**, so an unmeasured basis
+              degrades to a drop and never to a 422.
+
+            The class token is deliberately NOT interpolated into this
+            string: the reason and the path are separate fields because
+            a fused `not_available_on_<class>` is unparseable and
+            duplicates `processing_class`.
+          example: unavailable_on_processing_class
 
     ProcessingPlan:
       type: object
@@ -10438,10 +11046,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 +11120,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 +11419,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: |
@@ -10866,11 +11520,29 @@ components:
             Distinct from the workflow/API create-time `ErrorEnvelope.error`
             vocabulary — this is the per-operation processing failure.
 
-            **Retry semantics:** the sibling `is_retryable` marks the transient
-            codes (`out_of_memory`, `timeout`, `s3_download_failed`,
-            `s3_upload_failed`); those are auto-redriven (SQS) and exhausted
-            before a failure surfaces, so a reported failure is always terminal —
-            `is_retryable` only tells the user whether re-submitting is worthwhile.
+            **Retry semantics — DERIVE THEM FROM THIS FIELD.** Retryability is a
+            property OF THE ERROR CODE, not an independent fact about an
+            occurrence: the same code is always equally retryable, so there is
+            no per-response boolean on this surface to read. The transient codes
+            are `out_of_memory`, `timeout`, `s3_download_failed` and
+            `s3_upload_failed`; the AsyncAPI `ErrorCode` enum groups every value
+            under **Retryable** / **Non-retryable** headings and is the source of
+            truth for that mapping.
+
+            Note a reported failure is **always terminal** regardless: transient
+            codes are auto-redriven (SQS) and exhausted before a failure ever
+            surfaces here, so retryability only tells the caller whether
+            **re-submitting** is worthwhile.
+
+            **This docstring previously referred to "the sibling `is_retryable`".
+            There is no such field on the OpenAPI surface** — it exists only on
+            the AsyncAPI worker→API channel, so no generated REST client could
+            ever carry it, and the contract was describing to consumers something
+            it does not deliver (ticket `wdOF3ol4`). Deliberately corrected by
+            REMOVING the promise rather than by adding the field: a per-response
+            boolean would be a second source of truth for a fact the code already
+            determines, free to drift from it, and it would break again when the
+            `retryable` boolean→enum change lands.
 
             **Codes** (closed set; meaning):
             `invalid_options` (options invalid for this op — most common),
@@ -10883,6 +11555,12 @@ components:
             `invalid_key` (storage key invalid),
             `processing_failed` (non-specific processing failure),
             `s3_access_denied` (storage access denied — fail-fast, non-retryable),
+            `input_too_large` (input exceeds our PROCESSING limits — deterministic,
+            user-actionable via downscaling or a higher tier; distinct from the
+            byte caps, which are refused at create and never reach a worker),
+            `never_started` (the operation was terminated without ever running
+            because its job reached a terminal state first — an upstream failure
+            OR a cancellation; API-derived, never worker-emitted),
             `unknown` (unclassified),
             `out_of_memory` (retryable), `timeout` (retryable),
             `s3_download_failed` (retryable), `s3_upload_failed` (retryable).
@@ -11190,7 +11868,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 +12014,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 +12457,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 +12723,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 +12754,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 +13337,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: |
@@ -12639,6 +13464,31 @@ components:
             scoped to a single option (e.g. an operation may have a
             free-tier base option set with one or two `pro`-tier
             advanced options gated this way).
+        per_class_availability:
+          type: object
+          description: |
+            Per-EXECUTION-CLASS overlay for this option: restricts it on named
+            `processing_class` entries of the parent mime_group while leaving
+            the others at the inherited level. Keys MUST be classes the group
+            declares.
+
+            Use this — NOT an operation-wide `availability` — when a worker
+            honours an option on one execution path and refuses it on another.
+            Marking the whole option `planned` would withdraw a working
+            capability from every caller in order to describe one path's gap.
+
+            May only RESTRICT relative to the scope it overlays, never re-open
+            it. See `schemas/FORMAT.md` §`per_class_availability` and
+            §Precedence (machine-enforced by
+            `scripts/check-per-class-availability.py`).
+
+            Note the option-level overlay and the per-VALUE one
+            (`per_value_availability.<value>.per_class_availability`) can
+            coexist: the option-level says the worker refuses the KEY on that
+            path, the value-level says it refuses one VALUE. Most-cautious
+            inheritance applies.
+          additionalProperties:
+            $ref: '#/components/schemas/PerClassAvailabilityEntry'
         per_value_availability:
           $ref: '#/components/schemas/PerValueAvailability'
           description: |