@giveitsmaller/contracts 0.76.0 → 0.79.0

package/openapi/api.yaml

@@ -103,7 +103,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.211.0
+  version: 2.214.0
   contact:
     name: API Support
 
@@ -1782,17 +1782,32 @@ paths:
               more operations / mime_groups / options gated by a higher
               subscription tier than the caller has. Each violation is
               listed in `violations[]` with `required_tier` populated.
+            - `anonymous_operation_not_allowed`: an ANONYMOUS caller (no
+              credential) requested an operation outside the anonymous
+              allow-list. `operation` names the first such operation.
+              A register-wall: signing in is the remedy, not upgrading.
+            - `anonymous_quota_exhausted`: an anonymous caller has used
+              its per-IP workflow allowance for the rolling 24 hours.
+              Also a register-wall.
+
+            Both anonymous walls are checked BEFORE the workflow is
+            built, and neither consumes the caller's anonymous
+            allowance. An authenticated caller never receives either.
           content:
             application/json:
               schema:
                 oneOf:
                   - $ref: '#/components/schemas/TierRestrictionResponse'
                   - $ref: '#/components/schemas/FeatureTierRestrictedResponse'
+                  - $ref: '#/components/schemas/AnonymousOperationNotAllowedResponse'
+                  - $ref: '#/components/schemas/AnonymousQuotaExhaustedResponse'
                 discriminator:
                   propertyName: error_type
                   mapping:
                     tier_restriction: '#/components/schemas/TierRestrictionResponse'
                     feature_tier_restricted: '#/components/schemas/FeatureTierRestrictedResponse'
+                    anonymous_operation_not_allowed: '#/components/schemas/AnonymousOperationNotAllowedResponse'
+                    anonymous_quota_exhausted: '#/components/schemas/AnonymousQuotaExhaustedResponse'
               examples:
                 feature_tier_restricted:
                   summary: Free tier referencing a Pro-tier operation
@@ -1805,6 +1820,25 @@ paths:
                         availability: "stable"
                         required_tier: "pro"
                         documentation_url: "https://docs.giveitsmaller.com/operations/image_watermark"
+                anonymous_operation_not_allowed:
+                  summary: Anonymous caller requesting an operation outside the allow-list
+                  value:
+                    success: false
+                    error: "ANONYMOUS_OPERATION_NOT_ALLOWED"
+                    error_type: "anonymous_operation_not_allowed"
+                    message: "Sign up to use the 'text_watermark' operation."
+                    message_key: "error.anonymous_operation_not_allowed"
+                    locale: "en-GB"
+                    operation: "text_watermark"
+                anonymous_quota_exhausted:
+                  summary: Anonymous caller past its rolling-24h allowance
+                  value:
+                    success: false
+                    error: "ANONYMOUS_QUOTA_EXHAUSTED"
+                    error_type: "anonymous_quota_exhausted"
+                    message: "Sign up to keep compressing."
+                    message_key: "error.anonymous_quota_exhausted"
+                    locale: "en-GB"
         '402':
           description: |
             Credit reservation failed (per ticket
@@ -1939,6 +1973,37 @@ paths:
               Caller resolves by switching to `re_encode_mode: auto`
               or `always`. The compatibility-probe algorithm is
               server-side and deliberately opaque per plan v5 §F8.2.
+            - Inputs not concat-uniform (ticket `MjzzPCWt`). Returned for a
+              job that routes to a processing class declaring
+              `input_uniformity` (today `merge.video.long_form_re_encode`)
+              when its inputs differ in stream layout or in a listed
+              attribute. `ValidationErrorEnvelope` with `error:
+              "INPUTS_NOT_CONCAT_UNIFORM"`; `details[]` entries are shaped
+              `{operation: "merge", field: "inputs[i].<attribute> vs
+              inputs[j].<attribute>", message: "..."}`, one per difference.
+              **Coverage rule:** the API refuses every difference its upload
+              probe can see WITH THE WORKER GATE'S SEMANTICS (audio present
+              on one input and not another; video codec, resolution; audio
+              codec, layout, channels, sample rate). NOT frame rate: the
+              probe's `fps` is the AVERAGE rate, which legitimately drifts
+              between concat-uniform clips, while the worker compares
+              `r_frame_rate`, so comparing `fps` would refuse valid merges.
+              Differences the probe does not carry with the worker's
+              semantics yet (frame rate as `r_frame_rate`, stream counts
+              beyond one video / one audio, stream order, pix_fmt, SAR,
+              timebase, codec_tag, profile, sample_fmt) are
+              refused by the worker after acceptance until the upload prober
+              emits them; the probe schema declares them
+              (`UploadProbeMediaMetadata`, card `lGeDDi4V`), and once a probe
+              carries one, the API refuses that difference at create too. **An input whose probe has not
+              completed is ADMITTED**, and the worker gate is its only
+              check, the same as **an input that is an upstream job's
+              output** (which has no upload probe). It does NOT get the
+              `probe_pending` branch: a probe that never lands cannot be
+              told apart from one still running, so refusing until it
+              lands could make a create that never succeeds (ruled
+              2026-09-24 on api's `nmYdwHAH`, matching api's disabled
+              single-operation probe gate).
 
             **Branch dispatch via the `error_type` discriminator** (per
             [ADR-0018](../docs/decisions/0018-universal-422-error-type-discriminator.md)).
@@ -2086,6 +2151,16 @@ paths:
                         actual: 54000
                         ceiling: 43200
                         required_tier: "enterprise"
+                inputs_not_concat_uniform:
+                  summary: merge.video long_form_re_encode with one input lacking audio (MjzzPCWt)
+                  value:
+                    success: false
+                    error_type: "validation_error"
+                    error: "INPUTS_NOT_CONCAT_UNIFORM"
+                    details:
+                      - operation: "merge"
+                        field: "inputs[0].audio vs inputs[1].audio"
+                        message: "Input 1 has no audio track and input 0 has one; long-form merge needs every input to share the same streams."
                 requires_reencode:
                   summary: merge.video re_encode_mode=never with incompatible inputs (I16-CONS)
                   value:
@@ -3323,7 +3398,9 @@ paths:
         Per ticket [I24 `e50uXLcl`](https://trello.com/c/e50uXLcl).
 
         Resume succeeds only when the caller's `available_credits`
-        cover the next reservation the server would attempt. If the
+        cover the reservation the server re-takes for the workflow's
+        remaining work (the same estimate `WorkflowPausedDetail`'s
+        `required_action: resume` is computed from). If the
         balance is still insufficient, the response is 402
         `BalanceExhaustedResponse` (mirroring the workflow-create
         flow per ticket I23) and the workflow remains
@@ -5127,6 +5204,33 @@ paths:
                           type: object
                       billing:
                         type: object
+                        properties:
+                          checkout_sessions:
+                            type: array
+                            description: |
+                              Every checkout session the account started that
+                              the API recorded (ticket `JHrV4MUg`). Sessions
+                              created before that record existed are absent.
+                            items:
+                              type: object
+                              required: [session_id, mode, created_at, fulfilled_at]
+                              properties:
+                                session_id:
+                                  type: string
+                                mode:
+                                  type: string
+                                  description: The checkout mode (`payment` for a credit pack, `subscription`).
+                                  # OPEN: the provider's checkout mode, recorded as created; a
+                                  # new mode is informational in an export, not a decision input.
+                                  x-enum-openness: open
+                                  enum: [payment, subscription]
+                                created_at:
+                                  type: string
+                                  format: date-time
+                                fulfilled_at:
+                                  type: ['string', 'null']
+                                  format: date-time
+                                  description: When the purchase was applied; `null` while it has not been.
         '401':
           description: No authenticated principal.
           content:
@@ -6627,20 +6731,24 @@ paths:
             headers.
           headers:
             X-RateLimit-Limit:
-              required: false
+              required: true
               description: Requests permitted in the current window.
               schema:
                 type: integer
                 minimum: 0
             X-RateLimit-Remaining:
-              required: false
+              required: true
               description: Requests remaining in the current window.
               schema:
                 type: integer
                 minimum: 0
             X-RateLimit-Reset:
-              required: false
-              description: Unix epoch seconds when the current window resets.
+              required: true
+              description: |
+                SECONDS UNTIL the current window resets (a delay, not a
+                timestamp). This said "Unix epoch seconds" until 2026-09-25;
+                api has always sent the delay, and both SDKs parse it as one
+                (card `KqPDtD9J`).
               schema:
                 type: integer
                 minimum: 0
@@ -6684,9 +6792,17 @@ paths:
 
         | `status` | meaning |
         |---|---|
-        | `paid` | the purchase this session was for has been applied to the caller's account — for a credit **pack**, a credit transaction referencing this session exists; for a **subscription**, the subscription it started is active on the caller's account |
+        | `paid` | the purchase this session was for has been applied to the caller's account — for a credit **pack**, a credit transaction referencing this session exists; for a **subscription**, the subscription it started is still linked to the caller's billing account (see below) |
         | `pending` | the session is recorded as created BY THE CALLER and its purchase has not been applied yet — **not a failure** |
-        | `unknown` | anything else |
+        | `unknown` | anything else, including a session created before this endpoint shipped (nothing recorded it) |
+
+        **Subscription `paid` means LINKED, not IN GOOD STANDING** (ruled
+        2026-09-25 on api's `JHrV4MUg`). It holds while the subscription the
+        session started is still linked to the caller's billing account; a
+        `past_due` or `incomplete` subscription that is still linked reads
+        `paid`. It becomes `unknown` once the provider reports the
+        subscription deleted. A stricter meaning needs the subscription's
+        status recorded, which the API does not do today.
 
         🔴 **`unknown` DELIBERATELY COLLAPSES "not yours" WITH "never
         existed". This is a decision, not missing detail.** Telling them
@@ -6722,9 +6838,12 @@ paths:
         '200':
           description: |
             The session's status for this caller. **Once implemented, always
-            200 for an authenticated caller**, whatever the session id —
-            `unknown` is the answer for anything not provably the caller's (see
-            the collapse rationale above). While the endpoint is `planned` it
+            200 for an authenticated caller, for any session id the router
+            accepts** — `unknown` is the answer for anything not provably the
+            caller's (see the collapse rationale above). An id the router
+            cannot route (for example invalid UTF-8 such as `cs_%FF`) is a
+            `404` before this endpoint runs; that answer is the same for
+            every caller and every session, so it reveals nothing. While the endpoint is `planned` it
             answers `422 feature_not_available` instead.
           content:
             application/json:
@@ -6758,6 +6877,16 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorEnvelope'
+        '404':
+          description: |
+            The ROUTER could not route the path (for example a session id
+            with invalid UTF-8). Returned before this endpoint runs, the same
+            for every caller and every session id, so it says nothing about
+            any session.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
         '422':
           description: |
             `feature_not_available` while this endpoint is `planned`.
@@ -6765,6 +6894,40 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/FeatureNotAvailableResponse'
+        '429':
+          description: |
+            Rate limit exceeded. This endpoint is limited as a STATUS POLL
+            (the same family as the other polling reads), independently of
+            `POST /api/billing/checkout`, so polling a pending session never
+            spends the caller's checkout-creation budget. `error:
+            TOO_MANY_REQUESTS`. No `Retry-After`; back off by
+            `X-RateLimit-Reset`.
+          headers:
+            X-RateLimit-Limit:
+              required: true
+              description: Requests permitted in the most constrained window.
+              schema:
+                type: integer
+                minimum: 0
+            X-RateLimit-Remaining:
+              required: true
+              description: Requests remaining in that window.
+              schema:
+                type: integer
+                minimum: 0
+            X-RateLimit-Reset:
+              required: true
+              description: |
+                SECONDS UNTIL that window resets (a delay, not a
+                timestamp) — what api's limiter sends
+                (`TieredRateLimiterService`: retry-after timestamp minus now).
+              schema:
+                type: integer
+                minimum: 0
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
 
   # ============================================
   # CONTACT ENDPOINT
@@ -7306,12 +7469,23 @@ components:
     ReEncodeDecision:
       type: string
       description: |
-        Path chosen for `merge.video` when `re_encode_mode=auto`.
-        Server reports the actual path so callers can see why
-        `auto` took the slow path. Absent for non-`merge.video`
-        operations and for `merge.video` when `re_encode_mode` is
-        `always` or `never` (path was caller-fixed). Per ticket
-        I16-CONS (Trello 7nCZXEru).
+        Path the worker actually took for a SUCCESSFUL `merge.video`,
+        reported in EVERY `re_encode_mode`: `always` reports `re_encode`;
+        `never` reports `stream_copy`; `auto` reports whichever path it
+        chose. Absent for non-`merge.video` operations and on any failed
+        operation, even one that carries other metrics such as sizes or
+        cost figures (for example a `never`
+        request whose inputs need a re-encode, or a long-form merge the
+        uniformity gate refuses before the path is decided). Per ticket I16-CONS (Trello
+        7nCZXEru).
+
+        ⚠️ An earlier revision said the field was ABSENT under `always` /
+        `never`. The worker never behaved that way (it reports the path
+        in every mode), and the same contract listed an `always`-mode
+        reason as an example, so the text contradicted itself. The
+        worker's behaviour is the canonical one (ruled 2026-09-24 on
+        compression_e2e's report); a consumer MUST NOT assert absence
+        on a successful merge under a caller-fixed mode.
 
         Mirrors the AsyncAPI `ReEncodeDecision` (and
         `OperationMetrics.re_encode_decision`); exposed on the REST
@@ -9043,15 +9217,28 @@ components:
 
     WorkflowPauseRequiredAction:
       type: string
+      x-enum-openness: open
       description: |
-        Action the caller must take to resume a paused workflow.
-        Same enum as `BalanceExhaustedResponse.required_action` —
-        the pause cause is always insufficient credits, so the
-        resolution affordances align.
+        Action the caller must take to resume a paused workflow. The
+        first three match `BalanceExhaustedResponse.required_action`.
+        `resume` (ticket `xNatWWpO`, api #747): the account can afford
+        the resume NOW, so the only action is to resume: call the
+        `resumeWorkflow` operation (`POST /api/workflows/{id}/resume`).
+        `links.resume`, when present, is a UI deep link, not the API
+        call. The
+        API emits it when the balance, plus this month's pending grant
+        for the base tier, covers the same cost estimate the resume
+        handler reserves — so `/status` and resume agree. A UI must not
+        offer a top-up, upgrade or pack for it.
+        **Open enum:** handle an unknown value as the generic case.
+        ⚠️ Rollout order, because a strict SDK deserialiser throws on an
+        unknown value: SDKs tolerate unknown values and are published
+        first, and only then does the API emit `resume`.
       enum:
         - add_credits
         - upgrade_plan
         - wait_for_renewal
+        - resume
 
     # ============================================
     # WORKFLOW ADVISORY WARNINGS (per ticket I25)
@@ -9202,9 +9389,10 @@ components:
 
         SDK + frontend gate UI on `required_action` to render the
         appropriate "Top up to resume" / "Upgrade plan to resume" /
-        "Wait for renewal" affordance, with `links.resume` enabling
-        a one-click POST to `/api/workflows/{id}/resume` once the
-        balance is sufficient.
+        "Wait for renewal" affordance — or, for `resume`, only the
+        resume action. The resume itself is the `resumeWorkflow`
+        operation (`POST /api/workflows/{id}/resume`); `links.resume` is
+        the frontend page where a user can do it, not that API call.
       required:
         - paused_at
         - expires_at
@@ -9252,9 +9440,11 @@ components:
               type: string
               format: uri
               description: |
-                Deep link to the resume action — typically
-                `POST /api/workflows/{id}/resume` exposed via the
-                frontend's "resume" UI.
+                URL of the frontend page for this workflow (e.g.
+                `{frontend}/{locale}/profile/workflows/{id}`), where the
+                user can resume it. **NOT the API call:** a client resumes
+                with the `resumeWorkflow` operation
+                (`POST /api/workflows/{id}/resume`).
             top_up:
               type: string
               format: uri
@@ -9515,6 +9705,67 @@ components:
     # FEATURE AVAILABILITY ENVELOPES
     # ============================================
 
+    AnonymousOperationNotAllowedResponse:
+      description: |
+        403 from `POST /api/workflows` when an ANONYMOUS caller (no
+        credential) requests an operation outside the anonymous
+        allow-list. A register-wall: the frontend renders a sign-up
+        prompt, since no tier upgrade applies to a caller without an
+        account.
+
+        Mirrors `compression_api`'s `WorkflowController` register-wall
+        (`JobsErrorCode::AnonymousOperationNotAllowed`), which checks
+        every operation in the body and names the FIRST disallowed one.
+
+        ⚠️ **The allow-list itself is NOT yet declared in this contract**
+        (ticket [`UQ7zROTr`](https://trello.com/c/UQ7zROTr)), so a client
+        can parse this refusal but cannot yet predict it. Do not hard-code
+        the list from this description: it deliberately names none.
+      allOf:
+        - $ref: '#/components/schemas/ErrorEnvelope'
+        - type: object
+          required:
+            - error_type
+            - operation
+          properties:
+            error:
+              enum:
+                - ANONYMOUS_OPERATION_NOT_ALLOWED
+            error_type:
+              description: Discriminator for the 403 oneOf. Always `anonymous_operation_not_allowed` for this envelope.
+              type: string
+              enum:
+                - anonymous_operation_not_allowed
+            operation:
+              description: |
+                The first operation in the request body that an anonymous
+                caller may not run.
+              $ref: '#/components/schemas/OperationType'
+    AnonymousQuotaExhaustedResponse:
+      description: |
+        403 from `POST /api/workflows` when an ANONYMOUS caller (no
+        credential) has used its per-IP workflow allowance for the
+        rolling 24 hours. A register-wall, distinct from the generic
+        `429`: the remedy is signing in, not waiting.
+
+        Mirrors `compression_api`'s `WorkflowController` register-wall
+        (`JobsErrorCode::AnonymousQuotaExhausted`). The allowance is only
+        consumed by a workflow that is actually created, so a refused
+        request does not use it up.
+      allOf:
+        - $ref: '#/components/schemas/ErrorEnvelope'
+        - type: object
+          required:
+            - error_type
+          properties:
+            error:
+              enum:
+                - ANONYMOUS_QUOTA_EXHAUSTED
+            error_type:
+              description: Discriminator for the 403 oneOf. Always `anonymous_quota_exhausted` for this envelope.
+              type: string
+              enum:
+                - anonymous_quota_exhausted
     FeatureViolation:
       type: object
       description: |
@@ -9671,9 +9922,11 @@ components:
     ProcessingClassRejectReason:
       type: string
       description: |
-        Why a job cannot be classified — input size/duration exceeds
-        the `long_form` (or `long_form_re_encode`) ceiling under the
-        caller's effective per-tier caps (per
+        Why a job cannot be classified: an input exceeds the ceiling of
+        the last class it could reach — the `long_form` (or
+        `long_form_re_encode`) ceiling, or the `short_form` ceiling when
+        `long_form` is not available — or its resolution band is not
+        served. Ceilings are the caller's effective per-tier caps (per
         [ADR-0011](../docs/decisions/0011-per-tier-processing-class-constraints.md)
         `per_tier_constraints`). Distinct from `ProcessingClassReason`
         (which describes WHY a job got its assigned class — success-
@@ -9697,11 +9950,35 @@ components:
           (`max_total_input_size_bytes` / `max_total_duration`).
           Applies to operations whose `processing_class.<class>.
           constraints` carries `max_total_*` — merge today.
+        - `input_size_exceeds_short_form_no_long_form` /
+          `input_duration_exceeds_short_form_no_long_form`: a single input exceeds the
+          `short_form` ceiling (the band's, when the class declares
+          `resolution_bands`) AND the job cannot escalate to `long_form`
+          because that class is not available. `processing_class` on the
+          violation is `short_form`. Added 2026-09-25 for api `nslA1V1S`;
+          before, such a refusal had to borrow a `*_long_form` reason.
+          The `_no_long_form` suffix keeps these distinct from
+          `ProcessingClassReason`'s `*_exceeds_short_form`, which means
+          the job ESCALATED (the two enums are kept disjoint on purpose).
+        - `resolution_band_not_served`: the input's resolution band is
+          `basis: not_served` on the class (FORMAT.md §`resolution_bands`),
+          so no duration or size fits. `actual` is the input's FRAME
+          PIXELS (width x height) and `ceiling` is the `max_frame_pixels`
+          of the highest band the class DOES serve; `resolution_band`
+          names the band. The `unknown` band is never `not_served` (CI),
+          so this reason always has a measured `actual`.
+      # OPEN: a new reason is a new refusal cause. A consumer that does not know
+      # one shows the envelope's localised message; `actual` / `ceiling` stay
+      # integers in the unit the reason names.
+      x-enum-openness: open
       enum:
         - input_size_exceeds_long_form
         - input_duration_exceeds_long_form
         - combined_size_exceeds_long_form
         - combined_duration_exceeds_long_form
+        - input_size_exceeds_short_form_no_long_form
+        - input_duration_exceeds_short_form_no_long_form
+        - resolution_band_not_served
 
     ProcessingClassBandViolation:
       type: object
@@ -9717,6 +9994,14 @@ components:
         fail-all violations back to the offending job in multi-job
         workflows and (b) render "X exceeded by Y" without re-deriving
         caps from the per-tier overlay.
+      # A not_served refusal names the band it refused (codex #606).
+      if:
+        properties:
+          reason:
+            const: resolution_band_not_served
+        required: [reason]
+      then:
+        required: [resolution_band]
       required:
         - reason
         - job_ref
@@ -9745,10 +10030,11 @@ components:
           description: |
             0-based ordinal into `JobDefinition.inputs[]` identifying
             the specific input that violated the per-input ceiling.
-            Set ONLY on `input_*_exceeds_long_form` reasons for
-            multi-input operations; omitted on single-input
-            operations (no positional ambiguity) and on
-            `combined_*_exceeds_long_form` reasons (whole-job
+            Set on every PER-INPUT reason (`input_*_exceeds_long_form`,
+            `input_*_exceeds_short_form_no_long_form`,
+            `resolution_band_not_served`) for multi-input operations;
+            omitted on single-input operations (no positional ambiguity)
+            and on `combined_*_exceeds_long_form` reasons (whole-job
             violation across all inputs).
         operation:
           $ref: '#/components/schemas/OperationType'
@@ -9756,15 +10042,27 @@ components:
         processing_class:
           $ref: '#/components/schemas/ProcessingClass'
           description: |
-            The class whose ceiling was exceeded — typically `long_form`
-            or `long_form_re_encode`.
+            The class whose ceiling was exceeded: `long_form` /
+            `long_form_re_encode`, or `short_form` for the
+            `*_exceeds_short_form_no_long_form` reasons and for a
+            `not_served` band on short_form.
+        resolution_band:
+          $ref: '#/components/schemas/ResolutionBand'
+          description: |
+            The band whose ceiling `ceiling` is, when the class declares
+            `resolution_bands`; omitted otherwise. EXCEPTION: for
+            `resolution_band_not_served` it names the INPUT's (unserved)
+            band, and `ceiling` is the highest served band's
+            `max_frame_pixels`, not this band's. `unknown` means the
+            resolution could not be determined — a different customer
+            action from a known-resolution overflow.
         actual:
           type: integer
           minimum: 0
           description: |
-            Observed value. Bytes for `*_size_exceeds_long_form`
-            reasons; whole seconds for `*_duration_exceeds_long_form`
-            reasons.
+            Observed value. Bytes for `*_size_exceeds_*` reasons; whole
+            seconds for `*_duration_exceeds_*` reasons; frame pixels
+            (width x height) for `resolution_band_not_served`.
         ceiling:
           type: integer
           minimum: 0
@@ -9772,7 +10070,9 @@ components:
             Effective per-tier ceiling for this caller (same units as
             `actual`). The binding cap after `per_tier_constraints`
             overlay; lets consumers render "X exceeded by Y" without
-            re-deriving caps from the per-tier overlay.
+            re-deriving caps from the per-tier overlay. EXCEPTION: for
+            `resolution_band_not_served` it is the highest served band's
+            `max_frame_pixels` (a resolution bound, not a per-tier cap).
         required_tier:
           description: |
             Optional. When a HIGHER tier exists whose
@@ -10011,9 +10311,14 @@ components:
         - `failed`: All jobs finished, at least one failed, none succeeded.
         - `partially_failed`: Some jobs succeeded, some failed.
         - `paused_insufficient_credits`: Workflow paused at a job/
-          stage boundary because the next reservation exceeded the
-          caller's available credits. Pause occurs at boundaries
-          only — never mid-stream within a running operation.
+          stage boundary because it no longer holds a credit
+          reservation. The API reserves the FULL estimated cost at
+          create (a 402 there if the balance is short), so a normal run
+          never pauses; this is a defence for a workflow whose
+          reservation was released mid-flight (e.g. by an orphan
+          clean-up). There is no per-stage reservation (ticket
+          `mNA2uv3y`). Pause occurs at boundaries only — never
+          mid-stream within a running operation.
           Resumable via `POST /api/workflows/{id}/resume` once the
           caller tops up; expires after a 7-day TTL by default.
         - `cancelled`: Caller-initiated termination via
@@ -12026,6 +12331,15 @@ components:
           $ref: '#/components/schemas/EstimateQuality'
         reason:
           $ref: '#/components/schemas/ProcessingClassReason'
+        resolution_band:
+          $ref: '#/components/schemas/ResolutionBand'
+          description: |
+            The resolution band whose ceiling the class decision was taken
+            against, when the operation's classes declare
+            `resolution_bands`; omitted otherwise. `unknown` says the
+            resolution could not be determined, so `reason` (which names the
+            AXIS, e.g. `input_duration_exceeds_short_form`) was judged against
+            the `unknown` band's ceiling.
         dropped_options:
           type: array
           description: |
@@ -12564,6 +12878,84 @@ components:
             contract on the OpenAPI side; the prober reports the
             page-1 horizontal DPI when the document declares it,
             otherwise omits the field.
+        # STREAM TOPOLOGY + CONCAT ATTRIBUTES (lGeDDi4V, for MjzzPCWt): what the
+        # API needs to refuse a non-concat-uniform long-form merge at create.
+        # Defined with the SAME semantics as compression_lambdas' merge gate
+        # (re_encode.rs TopologyCounts / classify_non_uniform), or the
+        # create-time refusal and the worker gate would disagree. All OPTIONAL:
+        # a prober that has not emitted them yet simply omits them.
+        video_stream_count:
+          type: integer
+          minimum: 0
+          description: Streams whose ffprobe `codec_type` is `video`.
+        audio_stream_count:
+          type: integer
+          minimum: 0
+          description: Streams whose ffprobe `codec_type` is `audio`.
+        other_stream_count:
+          type: integer
+          minimum: 0
+          description: |
+            Every other stream: `codec_type` subtitle, data, attachment,
+            or unknown — the worker gate's `other` bucket.
+        stream_order:
+          type: array
+          items:
+            type: string
+            enum: [video, audio, other]
+          description: |
+            Per stream index, in container order, its kind (`other` as
+            above). Two inputs are order-compatible iff these are equal.
+        r_frame_rate:
+          type: string
+          pattern: '^[0-9]+/[0-9]+$'
+          description: |
+            ffprobe `r_frame_rate` of the video stream, raw (`30000/1001`;
+            ffprobe's `0/0` is carried as-is and means UNUSABLE). NOT the
+            average rate in `fps`, which drifts between concat-uniform
+            clips. **The worker's frame-rate rule, which a create-time
+            comparison must reproduce exactly:** (1) `r_frame_rate` and
+            `avg_frame_rate` must each be present on all inputs or absent
+            on all (else `input_metadata_inconsistent`); (2) if every
+            input has a usable `r_frame_rate`, compare those as parsed
+            rationals; (3) otherwise compare `avg_frame_rate` as parsed
+            rationals. Both comparisons are by VALUE (`60/2` equals `30/1`),
+            never by string.
+        avg_frame_rate:
+          type: string
+          pattern: '^[0-9]+/[0-9]+$'
+          description: |
+            ffprobe `avg_frame_rate` of the video stream, raw rational.
+            Presence-checked always; compared only as the fallback in the
+            `r_frame_rate` rule. `fps` is its lossy numeric form.
+        pix_fmt:
+          type: string
+          x-string-vocabulary: none
+          description: ffprobe `pix_fmt` of the video stream (e.g. `yuv420p`).
+        sar:
+          type: string
+          pattern: '^[0-9]+:[0-9]+$'
+          description: Sample aspect ratio of the video stream (`1:1`).
+        video_time_base:
+          type: string
+          pattern: '^[0-9]+/[0-9]+$'
+          description: ffprobe `time_base` of the video stream (`1/30000`).
+        audio_time_base:
+          type: string
+          pattern: '^[0-9]+/[0-9]+$'
+          description: ffprobe `time_base` of the audio stream (`1/48000`).
+        codec_tag:
+          type: string
+          x-string-vocabulary: none
+          description: ffprobe `codec_tag_string` of the video stream (e.g. `avc1`).
+        profile:
+          type: string
+          x-string-vocabulary: none
+          description: ffprobe `profile` of the video stream (e.g. `High`).
+        sample_fmt:
+          type: string
+          x-string-vocabulary: none
+          description: ffprobe `sample_fmt` of the audio stream (e.g. `fltp`).
         probed_at:
           type: string
           format: date-time
@@ -13871,8 +14263,8 @@ components:
               x-string-vocabulary: advisory
               description: |
                 Advisory explanation for `re_encode_decision` (e.g.
-                `all_inputs_compatible`, `explicit_always_mode`,
-                `input_codec_mismatch`, `input_framerate_mismatch`).
+                `compatible_inputs`, `always_mode_forces_re_encode`,
+                `input_video_codec_mismatch`, `long_form_stream_copy`).
                 Free-form string — not an enum — so the Lambda can emit
                 human-readable diagnostics that evolve without contract
                 changes. Mirrors `OperationMetrics.re_encode_reason`.
@@ -14184,6 +14576,10 @@ components:
             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`.
+            For a `split` of a PDF with `mode: page_groups`, each output holds
+            a GROUP of pages and `page_index` is the group's FIRST source
+            page; the group covers `page_index` .. `page_index + page_groups
+            - 1`, and the last group ends at the document's last page.
             Normative semantics: ADR-0009 §D2.
             Absent on non-indexed (single-output) downloads. Mirrors
             `OperationResultOutputEntry.page_index`. Per ADR-0009 §D2.
@@ -14355,6 +14751,17 @@ components:
           const: 100
         result:
           $ref: '#/components/schemas/SseOperationCompletionResult'
+        result_metadata:
+          $ref: '#/components/schemas/OperationResultMetadata'
+          description: |
+            OPTIONAL. The same whitelisted per-operation metadata the REST
+            operation object serves as `result_metadata` (a sibling of
+            `result` there too): `already_optimal`, `estimated_saving_pct`,
+            `watermark_id`. It lets the completion frame say "already
+            optimal" without a follow-up read. Absent means the frame does
+            not carry it, NOT that the operation has no metadata; a consumer
+            that needs it falls back to the REST read. Card `Fu372Ze7`
+            (api), contracts `DIDOPiZQ`.
 
     SseOperationCompletionResult:
       description: |
@@ -14629,6 +15036,10 @@ components:
             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`.
+            For a `split` of a PDF with `mode: page_groups`, each output holds
+            a GROUP of pages and `page_index` is the group's FIRST source
+            page; the group covers `page_index` .. `page_index + page_groups
+            - 1`, and the last group ends at the document's last page.
             Normative semantics: ADR-0009 §D2.
             Absent on non-indexed outputs. Mirrors
             `OperationResultOutputEntry.page_index`. Per ADR-0009 §D2.
@@ -16025,7 +16436,10 @@ components:
             on the optimiser path (e.g. JPEG `progressive`); `[format_change]`
             only on the transcoder path (e.g. `background` alpha-flatten to JPEG).
             ABSENT ≡ honored on every route the option's `depends_on` already
-            admits (back-compat — existing options need no tag). Orthogonal to
+            admits (back-compat — existing options need no tag). An EMPTY
+            list `[]` ≡ ACCEPTED BUT INERT: the option is still accepted on
+            the wire but no route honours it, so it is never visible and
+            never in `honored_options` (card `Nqd3TdC6`). Orthogonal to
             `availability`: a `planned` option still declares the route it WILL
             be honoured on. Consumers derive option visibility from
             `honored_on` ∩ active-route ∩ (availability != planned) ∩ depends_on.
@@ -16119,6 +16533,69 @@ components:
             Baseline caps for the lowest tier this class's
             `required_tier` permits. Overlaid per-caller by
             `per_tier_constraints` (see below).
+        input_uniformity:
+          type: object
+          additionalProperties: false
+          description: |
+            Present on a class that CONCATENATES inputs without normalising
+            them (today `merge.video.long_form_re_encode`, ticket `MjzzPCWt`):
+            every input must share its stream layout (`structural`, a
+            permanent requirement) and its stream attributes (`attributes`,
+            until the heterogeneous re-encode ships). The names are the
+            worker gate's reason vocabulary. A request that breaks it is
+            refused at create with the `refusal` code where the API's upload
+            probe can see the difference; the worker gate refuses the rest.
+          required: [refusal, structural, attributes]
+          properties:
+            refusal:
+              type: string
+              enum: [INPUTS_NOT_CONCAT_UNIFORM]
+              description: The `ErrorEnvelope.error` code of the create-time refusal.
+            structural:
+              type: array
+              items: {type: string}
+              description: Permanent stream-layout requirements (worker gate reason names).
+            attributes:
+              type: object
+              additionalProperties:
+                type: array
+                items: {type: string}
+              description: |
+                Per stream kind (`video`, `audio`), the attributes every input
+                must share until the heterogeneous re-encode ships; plus
+                `field_presence`: a video/audio stream field present on one
+                input and absent on another.
+        resolution_bands:
+          type: object
+          description: |
+            Optional per-resolution ceilings for this class (ticket
+            [`GxQPL4IY`](https://trello.com/c/GxQPL4IY)). Keys are EVERY
+            `ResolutionBand` value — each band in
+            `schemas/resolution-bands.yaml` plus `unknown` — so when the
+            block is present a consumer never has to invent a ceiling.
+            An input is placed in a band by its probe's frame pixels
+            (width x height); `unknown` applies when the probe has no
+            width or height. A band only TIGHTENS `constraints` (after
+            the `per_tier_constraints` overlay): the effective ceiling on
+            an axis is the smaller of the two, and an axis the band omits
+            falls through to the class. An input over its band's ceiling
+            exceeds this class, exactly as one over `constraints` does.
+            Absent = no resolution axis; `constraints` binds at every
+            resolution. CI-checked by `scripts/check-resolution-bands.py`.
+            See `schemas/FORMAT.md` §`resolution_bands`.
+          # Every band is REQUIRED: a consumer must never invent a ceiling. The
+          # property names are the `ResolutionBand` enum, held equal by a test.
+          additionalProperties: false
+          required: [le_720p, p1080, gt_1080p, unknown]
+          properties:
+            le_720p:
+              $ref: '#/components/schemas/ResolutionBandCeiling'
+            p1080:
+              $ref: '#/components/schemas/ResolutionBandCeiling'
+            gt_1080p:
+              $ref: '#/components/schemas/ResolutionBandCeiling'
+            unknown:
+              $ref: '#/components/schemas/ResolutionBandCeiling'
         per_tier_constraints:
           type: object
           description: |
@@ -16137,6 +16614,108 @@ components:
           additionalProperties:
             $ref: '#/components/schemas/ProcessingClassConstraints'
 
+    ResolutionBand:
+      type: string
+      description: |
+        A resolution band (ticket [`GxQPL4IY`](https://trello.com/c/GxQPL4IY)).
+        The band names and their frame-pixel bounds are declared ONCE in
+        `schemas/resolution-bands.yaml`; this enum is those names plus the
+        `unknown` band, held equal by a test.
+
+        - `le_720p`, `p1080`, `gt_1080p`: ascending frame-pixel bands
+          (width x height). Their bounds are `max_frame_pixels` in
+          `schemas/resolution-bands.yaml` and are deliberately not
+          restated here.
+        - `unknown`: the upload probe reported no width or no height, so the
+          resolution could not be determined. A refusal or escalation under
+          this band means "we could not tell this file's resolution", which
+          calls for a different action (re-upload, wait for the probe,
+          contact us) than "your file is too long".
+
+        Pixels, not height: a portrait clip lands in the same band as its
+        landscape twin.
+      # CLOSED. The band a consumer computes decides which ceiling it enforces;
+      # an unrecognised band cannot be mapped to a ceiling safely in either
+      # direction, so a new band is a contract event consumers must learn.
+      x-enum-openness: closed
+      enum:
+        - le_720p
+        - p1080
+        - gt_1080p
+        - unknown
+
+    ResolutionBandCeiling:
+      type: object
+      additionalProperties: false
+      description: |
+        One band's ceiling within `ProcessingClassEntry.resolution_bands`.
+        `basis` is REQUIRED so no consumer inherits a default for a band
+        nobody measured. `not_served` carries neither `constraints` nor
+        `derivation`; `measured` carries both; `ruled` carries
+        `constraints` only.
+      required:
+        - basis
+      allOf:
+        - if:
+            properties: {basis: {const: not_served}}
+          then:
+            not:
+              anyOf:
+                - required: [constraints]
+                - required: [derivation]
+          else:
+            required: [constraints]
+        - if:
+            properties: {basis: {const: measured}}
+          then:
+            required: [derivation]
+          else:
+            not:
+              required: [derivation]
+      properties:
+        basis:
+          type: string
+          description: |
+            - `measured`: the ceiling is derived from measured encode time;
+              `derivation` carries the line it was solved from.
+            - `ruled`: a policy value, not a measurement (today: the
+              `unknown` band, which takes the `le_720p` ceiling).
+            - `not_served`: this class does not serve inputs in this band.
+              No `constraints`; an input in this band exceeds the class
+              (for `short_form`: it escalates to `long_form`, or is refused
+              where `long_form` is not available).
+          # CLOSED: each value changes what a consumer enforces.
+          x-enum-openness: closed
+          enum: [measured, ruled, not_served]
+        constraints:
+          type: object
+          additionalProperties: false
+          description: Present unless `basis` is `not_served`.
+          minProperties: 1
+          properties:
+            max_input_duration:
+              type: string
+              description: ISO-8601 duration; the band's input duration ceiling.
+              example: "PT4M35S"
+        derivation:
+          type: object
+          additionalProperties: false
+          description: |
+            Present only when `basis` is `measured`. Encode time was measured
+            as a line, `slope_s_per_s x duration + intercept_s`; the ceiling is
+            that line solved for `cap_s` and FLOORED, so it never promises a
+            duration that crosses the cap. CI recomputes the ceiling from these.
+          required: [slope_s_per_s, intercept_s, cap_s]
+          properties:
+            slope_s_per_s:
+              type: number
+              exclusiveMinimum: 0
+            intercept_s:
+              type: number
+            cap_s:
+              type: number
+              exclusiveMinimum: 0
+
     # ============================================
     # RETRY SCHEMAS
     # ============================================