@giveitsmaller/contracts 0.85.0 → 0.87.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.220.0
+  version: 2.223.0
   contact:
     name: API Support
 
@@ -1098,13 +1098,12 @@ paths:
         bad ones before submit.
 
         Per ticket [I28 `KbVAnGCm`](https://trello.com/c/KbVAnGCm).
-        `availability: planned`. The upload-probe Lambda exists and runs
-        asynchronously when an upload is finalised; this endpoint returns
-        the cached result when one exists and `feature_not_available`
-        (422) when none does yet. It does not invoke the probe itself.
-        (A `planned` endpoint that answers 200 is inconsistent with the
-        availability taxonomy; the flip decision is tracked separately,
-        card `kAT0i5A6`.) Per Tension 1 (ADR-0001 §1.3).
+        `availability: beta` (card `kAT0i5A6`, on a production
+        observation, 2026-10-01). The upload-probe Lambda runs
+        asynchronously when an upload is finalised (measured on prod:
+        about 3 s for a 3 s clip); this endpoint returns the cached
+        result when one exists and a 422 when none does yet. It does not
+        invoke the probe itself.
 
         **SDK helper intent.** SDKs are expected to expose a
         `client.preflight_clips([file_ids])` helper that compiles to N
@@ -1128,7 +1127,7 @@ paths:
       x-identity-scoped: true  # ownership-scoped per ADR-0016 D3
       tags:
         - Upload
-      x-availability: planned
+      x-availability: beta
       parameters:
         - name: id
           in: path
@@ -1223,14 +1222,49 @@ paths:
                 $ref: '#/components/schemas/ErrorEnvelope'
         '422':
           description: |
-            No probe result is cached for this upload yet (the probe runs
-            asynchronously after the upload is finalised) — returned as
-            `FeatureNotAvailableResponse` with `error_type:
-            feature_not_available`. Per Tension 1 (ADR-0001 §1.3).
+            No probe result is cached for this upload. Discriminated on
+            `error_type` (ADR-0018), card
+            [`tRVvMOvy`](https://trello.com/c/tRVvMOvy):
+            - `probe_not_ready` → `UploadProbeNotReadyResponse`: the probe
+              has not landed YET. **Retry** (`Retry-After` when present).
+            - `probe_not_applicable` → `UploadProbeNotApplicableResponse`:
+              this upload's type is never probed (e.g. an image, whose
+              metadata is read inline at upload). **Terminal — do not
+              retry**; no result will ever exist.
+            - `feature_not_available` → `FeatureNotAvailableResponse`
+              with `violations[].availability: planned`:
+              **TRANSITIONAL.** What the server sends today for BOTH
+              causes above. It predates this endpoint's move to `beta`
+              and does NOT mean the endpoint is unavailable. Retry it
+              **with a ceiling** — it can be the terminal case. The
+              server switches to the two arms above only after an SDK
+              release that reads them is published; when this arm is
+              removed is an owner decision.
+          headers:
+            Retry-After:
+              required: false
+              description: |
+                Optional, on the `probe_not_ready` branch only: suggested
+                seconds before the next poll. Delta-seconds (RFC 9110).
+                Absent ⇒ poll on your own backoff (measured on prod
+                2026-10-01: about 3 s from upload to a result for a 3 s
+                clip).
+              schema:
+                type: integer
+                minimum: 0
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/FeatureNotAvailableResponse'
+                oneOf:
+                  - $ref: '#/components/schemas/UploadProbeNotReadyResponse'
+                  - $ref: '#/components/schemas/UploadProbeNotApplicableResponse'
+                  - $ref: '#/components/schemas/FeatureNotAvailableResponse'
+                discriminator:
+                  propertyName: error_type
+                  mapping:
+                    probe_not_ready: '#/components/schemas/UploadProbeNotReadyResponse'
+                    probe_not_applicable: '#/components/schemas/UploadProbeNotApplicableResponse'
+                    feature_not_available: '#/components/schemas/FeatureNotAvailableResponse'
         '429':
           description: |
             Rate limit exceeded. Probe is rate-limited independently
@@ -3699,10 +3733,10 @@ paths:
       # ROUTE ADDED: compression_api #804 (merge 85dd49fa, 2026-09-30) serves
       # the public POST route, owner-scoped (ownership denial 404). It was
       # `planned` since 2026-08-12 (yi4TDKVJ) because no route existed. Now
-      # `beta` on a staging customer-path round-trip (e2e, 2026-09-30,
-      # availability/staging-verification-log.yaml). `stable` needs a prod
-      # observation once api's release carrying #804 is on prod.
-      x-availability: beta
+      # `beta` on a staging customer-path round-trip, then `stable` on a PROD
+      # round-trip (e2e, 2026-09-30, api build 1.16.0,
+      # availability/prod-verification-log.yaml).
+      x-availability: stable
       operationId: archiveWorkflow
       security: [{bearerAuth: []}, {sessionAuth: []}]  # required (explicit 401 in response set)
       x-identity-scoped: true  # workflow-ownership-scoped per ADR-0016 D3
@@ -3797,10 +3831,10 @@ paths:
       # ROUTE ADDED: compression_api #804 (merge 85dd49fa, 2026-09-30) serves
       # the public POST route, owner-scoped (ownership denial 404). It was
       # `planned` since 2026-08-12 (yi4TDKVJ) because no route existed. Now
-      # `beta` on a staging customer-path round-trip (e2e, 2026-09-30,
-      # availability/staging-verification-log.yaml). `stable` needs a prod
-      # observation once api's release carrying #804 is on prod.
-      x-availability: beta
+      # `beta` on a staging customer-path round-trip, then `stable` on a PROD
+      # round-trip (e2e, 2026-09-30, api build 1.16.0,
+      # availability/prod-verification-log.yaml).
+      x-availability: stable
       operationId: restoreWorkflow
       security: [{bearerAuth: []}, {sessionAuth: []}]  # required (explicit 401 in response set)
       x-identity-scoped: true  # workflow-ownership-scoped per ADR-0016 D3
@@ -6627,6 +6661,7 @@ paths:
                           effective: 128849018880
                           tier_default: 107374182400
                           overridden: true
+                          ceiling_basis: unproven
                         max_total_input_size_bytes:
                           effective: 120000000000
                           tier_default: 120000000000
@@ -8629,6 +8664,18 @@ components:
           description: |
             The tier's default cap for this limit, in the same unit as
             `effective` (already public via the tier model).
+        ceiling_basis:
+          # OPTIONAL in this expand step (xApHyTY3, from api 5pyX06rE); api
+          # emits it after this publishes.
+          $ref: '#/components/schemas/CeilingBasisValue'
+          description: |
+            Whether `effective` is a PROVEN value (owner decision 607(d) /
+            610(4)(d)). `unproven` (e.g. the Max and Enterprise
+            `max_upload_size_bytes`): the API still enforces it; present it
+            as "up to X (not yet verified)" (FORMAT.md obligation 10). ⛔
+            **ABSENT IS NOT `proven`** — it means the server made no claim,
+            so a consumer must not advertise the value as verified on its
+            strength.
         overridden:
           type: boolean
           description: |
@@ -10098,6 +10145,44 @@ components:
               items:
                 $ref: '#/components/schemas/FeatureViolation'
 
+    UploadProbeNotReadyResponse:
+      description: |
+        422 from `POST /api/uploads/{id}/probe`: the upload's server-side
+        probe has not landed YET. Retryable — poll again after
+        `Retry-After` (when present) or your own backoff. Distinct from
+        `probe_pending` (`ProbePendingResponse`, workflow-create, carries
+        `job_ref`) so each code keeps one shape. Card
+        [`tRVvMOvy`](https://trello.com/c/tRVvMOvy).
+      allOf:
+        - $ref: '#/components/schemas/ErrorEnvelope'
+        - type: object
+          required:
+            - error_type
+          properties:
+            error_type:
+              type: string
+              enum:
+                - probe_not_ready
+              description: Discriminator for the probe endpoint's 422 oneOf. Always `probe_not_ready`.
+
+    UploadProbeNotApplicableResponse:
+      description: |
+        422 from `POST /api/uploads/{id}/probe`: this upload's type is
+        never probed (e.g. an image, whose metadata is read inline at
+        upload), so no result will ever exist. **Terminal — do not
+        retry.** Card [`tRVvMOvy`](https://trello.com/c/tRVvMOvy).
+      allOf:
+        - $ref: '#/components/schemas/ErrorEnvelope'
+        - type: object
+          required:
+            - error_type
+          properties:
+            error_type:
+              type: string
+              enum:
+                - probe_not_applicable
+              description: Discriminator for the probe endpoint's 422 oneOf. Always `probe_not_applicable`.
+
     ProbePendingResponse:
       description: |
         422 response on `POST /api/workflows` when the probe-pending
@@ -10662,7 +10747,7 @@ components:
         - audio_to_video: Produce a video from an audio input plus an OPTIONAL still image overlay. Multi-input role-based with the first OPTIONAL role on the contract (`role: base` audio required, `role: overlay` image 0..1 — see `per_role_cardinality`). When overlay is omitted, the video uses a solid background colour. `availability: planned` — WITHDRAWN 2026-09-15: the measured encode cost (a per-second rate PLUS A FIXED COST) puts the advertised PT2H at more than twice the 900 s platform maximum (dropping the fixed cost moves the in-flight boundary by tens of seconds; figures in the CHANGELOG entry for 2.203.0, derived and tested from the divergence register). Returns `feature_not_available` (422) at workflow-create. An already-accepted workflow is not cancelled (availability is checked at create) and fails only when its output duration exceeds the derived ceiling (divergence register `evidence.derived.ceiling_s`) ON THE INPUT THE RATE WAS MEASURED WITH (a real photographic 1080p still plus looped real audio), where the measured rate plus the fixed cost reaches the worker's 600 s cap — the 60 s and 120 s measured cells both COMPLETED. The driver is the STILL'S RESOLUTION, not duration alone: a 4K still is roughly 4x the rate (unmeasured), which would put the boundary near a quarter of that, and this schema places no constraint on the overlay's resolution. Per ticket [`SlluxMBN`](https://trello.com/c/SlluxMBN) + ADR-0015 (introduces `per_role_cardinality` vocab).
         - video_watermark: Apply an image overlay onto a base video via FFmpeg's `overlay` filter. Multi-input role-based (`role: base` video + `role: overlay` image, exactly one of each per `per_role_cardinality`). Re-encode required; audio stream-copy passthrough. Distinct from `image_watermark` (pure-Rust/image-only). `availability: planned` — WITHDRAWN 2026-09-15, operation AND `short_form`: a real 1080p source at the advertised PT5M / 500 MB was killed just past the worker's 600 s encode cap, no output. Returns `feature_not_available` (422) at workflow-create; an already-accepted workflow is not cancelled and fails only if it exceeds that cap; the kill is ONE measured point and nothing measured says where the boundary is. `long_form` and `multi_overlay_stack` were already `planned`. Per ticket [`4NrRPCgh`](https://trello.com/c/4NrRPCgh) + ADR-0013.
         - video_text_watermark: Render a text overlay onto a base video via FFmpeg's `drawtext` filter. Single-input — text and styling in options. Same `watermark_mode` (single/tiled), anchor + margin vocab as `text_watermark`. Re-encode required; audio stream-copy passthrough. `availability: planned` — WITHDRAWN 2026-09-15, operation AND `short_form`: a real 1080p source at the advertised PT5M was killed just past the worker's 600 s encode cap. Returns `feature_not_available` (422) at workflow-create. ⚠️ This entry previously read "until Lambda ships", which was wrong in a way that mattered: the worker SHIPPED and runs — it is the CEILING that cannot be served. Per ticket [`4NrRPCgh`](https://trello.com/c/4NrRPCgh) + ADR-0013.
-        - split: Fan one input file into N outputs across GIF / PDF / audio / video MIME families. Single-input per-mime-group catalog (mirrors merge/convert): GIF uses `frame_range` (REQUIRED) + `output_format`; PDF uses `page_range` OR `page_groups` (mutually exclusive); audio + video use a `mode` discriminator (interval/count/cut_points) + numeric-seconds wire format + `precision` flag (fast/exact). 200-output hard cap per ADR-0009 §D5 with per-mode preflight math; output naming `output-001..output-200`. Long-form video routes to a separate `split-video-fargate` worker via `processing_class`. `availability: beta` for the `audio` and `video` mime_groups (workers live on staging — shape-stable + opt-in, MUST NOT 422); video activates BOTH classes (`video.processing_class.short_form: beta` AND `long_form: beta` — `split-video-fargate` deployed + wired on staging; it stays `beta` until a PRODUCTION `customer_path` run is recorded in `availability/prod-verification-log.yaml` per [`rcwvUKhI`](https://trello.com/c/rcwvUKhI)). The `image_gif` and `document_pdf` mime_groups stay `availability: planned` and dispatch returns `feature_not_available` (422) until their workers ship. Per ticket [`vKI0CFDu`](https://trello.com/c/vKI0CFDu) + ADR-0014.
+        - split: Fan one input file into N outputs across GIF / PDF / audio / video MIME families. Single-input per-mime-group catalog (mirrors merge/convert): GIF uses `frame_range` (REQUIRED) + `output_format`; PDF uses `page_range` OR `page_groups` (mutually exclusive); audio + video use a `mode` discriminator (interval/count/cut_points) + numeric-seconds wire format + `precision` flag (fast/exact). 200-output hard cap per ADR-0009 §D5 with per-mode preflight math; output naming `output-001..output-200`. Long-form video routes to a separate `split-video-fargate` worker via `processing_class`. `availability: beta` for the `audio` and `video` mime_groups (workers live on staging — shape-stable + opt-in, MUST NOT 422); video activates BOTH classes (`video.processing_class.short_form: beta` AND `long_form: beta` — `split-video-fargate` deployed + wired on staging; it stays `beta` until a PRODUCTION `customer_path` run is recorded in `availability/prod-verification-log.yaml` per [`rcwvUKhI`](https://trello.com/c/rcwvUKhI)). The `image_gif` mime_group is `stable` and `document_pdf` is `beta` (2026-10-01). Per ticket [`vKI0CFDu`](https://trello.com/c/vKI0CFDu) + ADR-0014.
         - passthrough: Inert lossless source operation. A single-input source job whose SOLE operation is `passthrough` emits its source bytes UNCHANGED — no compression, no Lambda. The API self-completes the job at publish (terminal output = the upload `{bucket, key}` unchanged). Its purpose is to feed an uploaded file into a multi-input operation LOSSLESSLY: because `JobInputV2.source` is narrowed to exclude upload-direct, an upload that must enter a `merge` / `archive` / `image_watermark` op enters via a `passthrough` source job referenced downstream by `{type: job_output, from: <id>}` — preserving billing / DAG / lineage. Distinct from `operations: []` (which keeps its implicit-compress meaning on a single-input upload job); `passthrough` is the EXPLICIT lossless path via the "non-empty `operations[]` without `compress` = compression opt-out" rule. Media-agnostic; no options. `availability: beta` — activated (the inputs[]-narrowing + passthrough self-complete mechanism is deployed API-side); workflow-create accepts `passthrough` source jobs and MUST NOT return `feature_not_available`. **Never published to SNS** — deliberately absent from the AsyncAPI routing enums (API self-completes; no `ops-passthrough` queue). Per ticket [`4som89Uh`](https://trello.com/c/4som89Uh) + ADR-0004 (planned→beta flip).
 
         - transform: Geometric/orientation transform — v1 = rotate (0/90/180/270) + flip (none/horizontal/vertical/both), ADR-0026. Single-input; `produces: same_as_input` (geometry preserves format/container). Chainable (NOT sole_op); canonical single-job chain order is `transform → convert → compress → thumbnail` (geometry before encode/derive so downstream width/height/fit refer to the final frame). Media groups: image (still jpeg/png/webp + animated `image_gif`), video (mp4/webm), document (PDF page-rotate only — no flip); audio not supported. ALL groups `availability: planned` (epic `fhiWebI0`) — workflow-create returns `feature_not_available` (422) until per-media Lambdas ship. A no-op transform (`rotate: 0` + `flip: none`) is rejected as `invalid_options`. The public operation type is `transform`; the API resolves an internal per-media SNS routing sub-type (`transform_image` / `transform_video` / `transform_document`) — those sub-types are routing-only and are NOT part of this public enum. Per ADR-0026.
@@ -14864,6 +14949,29 @@ components:
             requested `target_size_bytes`. `false` is an honest best-effort outcome
             (target unreachable at min quality), NOT a failure. Present only for a
             target_size output. Mirrors `OperationMetrics.target_size_met`.
+        already_optimal:
+          type: boolean
+          description: |
+            OPTIONAL. `true` when this file IS the original input, returned
+            unchanged because compressing it would not have made it smaller
+            (owner decision 645(4): a success; the no-charge rule and its
+            current rollout — the API still charges until it ships, and only
+            short-form compress returns this today — are stated once, on
+            `OperationResultMetadata.already_optimal`). Same value as
+            `OperationResultMetadata.already_optimal` on `/status`, projected
+            here so a per-file result built from `/downloads` does not need a
+            second read (sdks `bYOCX61m`). Absent or `false`: an ordinary
+            output; treat the two the same. Mirrors
+            `OperationMetrics.already_optimal`.
+          example: true
+        already_optimal_kind:
+          type: string
+          enum: [not_smaller]
+          description: |
+            OPTIONAL, only with `already_optimal: true`. Same value and meaning
+            as `OperationResultMetadata.already_optimal_kind`; absent or unknown:
+            neutral "already optimised" copy.
+          example: not_smaller
         measured_quality:
           type: number
           format: double
@@ -16068,8 +16176,8 @@ components:
         Recursive condition node (the `Cond` field-token model, ADR-0024
         §2). Exactly ONE form per node — a boolean combinator (`all` /
         `any` / `not`) OR a single leaf test. A leaf tests one `field`
-        token with exactly one operator (`equals` / `in` / `isSet`),
-        except `opSelected` which is a standalone leaf asserting a
+        token with exactly one operator (`equals` / `in` / `isSet` /
+        `numericZero`), except `opSelected` which is a standalone leaf asserting a
         sibling operation of that type is present in the job. Consumers
         compute field tokens locally from the resolved request (no new
         wire field). Modelled as a `oneOf` of the valid forms (each
@@ -16132,6 +16240,33 @@ components:
               description: |
                 Leaf test — asserts `field` is present/set. Only the
                 positive form is used; negate via a wrapping `not` node.
+        - type: object
+          additionalProperties: false
+          required: [field, numericZero]
+          properties:
+            field:
+              type: string
+              description: Field token under test.
+            numericZero:
+              type: boolean
+              enum: [true]  # not `const` — ADR-0010 (generators mis-emit boolean const)
+              x-matches: '^0+(\.0+)?(px|%)$'
+              description: |
+                Leaf test — `field` is an offset whose number is zero,
+                whatever its spelling (`0px`, `00%`, `0.000px`). True iff
+                the String-coerced value fully matches `x-matches`; any
+                other value is false, including `-0`, `+0` and `.0`,
+                which the offset pattern `^\d+(\.\d+)?(px|%)$` refuses
+                anyway. An unresolved field behaves as it does for
+                `equals` / `in`. This regex is NORMATIVE. api's
+                `float == 0` test agrees with it on every offset a float
+                represents faithfully; it differs only where a cast
+                underflows (hundreds of fractional zeros before a non-zero
+                digit), which api reads as zero and this leaf does not.
+                Like every operator here, its semantics live in this
+                schema, not in `operation-capabilities.json`. Only the positive
+                form is used; negate via a wrapping `not` node. Card
+                `6jTnFnTh`: replaces lexical `in` lists of zero spellings.
         - type: object
           additionalProperties: false
           required: [opSelected]
@@ -16995,14 +17130,24 @@ components:
           "up to X (not yet verified)". Each becomes `proven`, or is
           lowered to the largest passing value, after its staging corner run.
       additionalProperties:
-        type: string
-        # CLOSED: a consumer decides how to present the limit from it.
-        x-enum-openness: closed
-        enum: [proven, unproven]
+        $ref: '#/components/schemas/CeilingBasisValue'
       example:
         max_input_size_bytes: unproven
         max_input_duration: unproven
 
+    CeilingBasisValue:
+      type: string
+      description: |
+        Whether ONE declared ceiling is proven (owner decision 607(d)). The
+        single vocabulary for `CeilingBasis` (per-ceiling map on a group or
+        class) and `AccountLimitEntry.ceiling_basis` (one account limit).
+        `proven`: a recorded run passed at 95% or more of the value.
+        `unproven`: still ENFORCED, not yet run at the value; present as
+        "up to X (not yet verified)" (FORMAT.md obligation 10).
+      # CLOSED: a consumer decides how to present the limit from it.
+      x-enum-openness: closed
+      enum: [proven, unproven]
+
     ResolutionBand:
       type: string
       description: |

package/operation-capabilities/operation-capabilities.json

@@ -513,12 +513,7 @@
                       {
                         "not": {
                           "field": "image_watermark.margin_x",
-                          "in": [
-                            "0px",
-                            "0%",
-                            "0.0px",
-                            "0.0%"
-                          ]
+                          "numericZero": true
                         }
                       }
                     ]
@@ -532,12 +527,7 @@
                       {
                         "not": {
                           "field": "image_watermark.margin_y",
-                          "in": [
-                            "0px",
-                            "0%",
-                            "0.0px",
-                            "0.0%"
-                          ]
+                          "numericZero": true
                         }
                       }
                     ]
@@ -657,12 +647,7 @@
                       {
                         "not": {
                           "field": "text_watermark.margin_x",
-                          "in": [
-                            "0px",
-                            "0%",
-                            "0.0px",
-                            "0.0%"
-                          ]
+                          "numericZero": true
                         }
                       }
                     ]
@@ -676,12 +661,7 @@
                       {
                         "not": {
                           "field": "text_watermark.margin_y",
-                          "in": [
-                            "0px",
-                            "0%",
-                            "0.0px",
-                            "0.0%"
-                          ]
+                          "numericZero": true
                         }
                       }
                     ]
@@ -859,5 +839,5 @@
       "isAnimated": "maybe"
     }
   },
-  "schema_version": "2.220.0"
+  "schema_version": "2.223.0"
 }

package/operations/schemas/audio_overlay.yaml

@@ -110,8 +110,8 @@ operation:
             max_output_size_bytes: 5000000000
           per_tier_constraints:
             max:
-              max_input_size_bytes: 50000000000    # 50 GB (Max self-serve band)
-              max_output_size_bytes: 50000000000
+              max_input_size_bytes: 53687091200    # 50 GiB = api's Max upload cap (decision 677)
+              max_output_size_bytes: 53687091200
             enterprise:
               max_input_size_bytes: 107374182400   # 100 GiB = api's Enterprise upload cap (owner 649(2))
               max_output_size_bytes: 107374182400
@@ -303,8 +303,8 @@ operation:
             max_output_size_bytes: 5000000000
           per_tier_constraints:
             max:
-              max_input_size_bytes: 50000000000    # 50 GB (Max self-serve band)
-              max_output_size_bytes: 50000000000
+              max_input_size_bytes: 53687091200    # 50 GiB = api's Max upload cap (decision 677)
+              max_output_size_bytes: 53687091200
             enterprise:
               max_input_size_bytes: 107374182400   # 100 GiB = api's Enterprise upload cap (owner 649(2))
               max_output_size_bytes: 107374182400

package/operations/schemas/audio_to_video.yaml

@@ -40,12 +40,11 @@ operation:
     What fails is an accepted workflow whose OUTPUT DURATION exceeds the derived ceiling (`evidence.derived.ceiling_s` in the register)
     ⚠️ ON THE INPUT THE RATE WAS MEASURED WITH — a real photographic 1080p STILL
     plus looped real audio — the point at which the measured rate plus the fixed
-    cost reaches the 600 s cap. ⛔ THE DRIVER IS THE STILL'S RESOLUTION, NOT THE
-    DURATION ALONE: a 4K still is roughly 4x the rate (recorded as UNMEASURED),
-    which would put the boundary near a quarter of that figure, and this schema
-    places NO constraint on the overlay's resolution. Other still resolutions and
-    other output settings are likewise unmeasured, and the contract does not
-    claim which direction they move —
+    cost reaches the SERVED cap (the worker's 600 s times the register's
+    `headroom`, kikOfB6G), not the raw cap. ⛔ THE DRIVER IS THE STILL'S RESOLUTION, NOT THE
+    DURATION ALONE: a 4K still is MEASURED materially slower (2026-10-02), and the
+    short_form ceiling below is set from that worst case; this schema places NO
+    constraint on the overlay's resolution. Stills above 4K are unmeasured —
     and what the caller then sees is NOT SETTLED — see the CHANGELOG entry for
     2.203.0; this contract does not pin a worker's error classification. Measured figures and the conditions for re-listing are in the
     CHANGELOG entry for 2.203.0 — the only one of the two records that is
@@ -85,9 +84,38 @@ operation:
         - audio/opus
         - audio/mp4
         - audio/x-m4a
-      ceiling_basis:   # 607(d): proven at the declared value, or not yet (FORMAT.md §ceiling_basis)
-        max_input_duration: unproven
-      max_input_duration: "PT2H"   # 2h input ceiling (KzrquIX7; mirrors worker MAX_AUDIO_DURATION_SECS 7200, strict >)
+      # Input caps live on the processing classes, not here (XOR rule, FORMAT.md
+      # §group-level input caps). d5cywEIR / HN-33 step 1.
+      processing_class:
+        # The Lambda path. Its ceiling is what finishes inside the worker's FFmpeg
+        # cap on REAL content, measured by lambdas on staging 2026-10-01 (points
+        # and fit in this operation's `evidence` block in
+        # schemas/manifest-divergence-register.yaml; a test holds the two equal).
+        # Encode time depends on the OUTPUT resolution and on the STILL's
+        # resolution, not on the input, so this is ONE ceiling: the slowest
+        # measured combination, a 3840x2160 still at `fhd_1080p` output (the
+        # worker decodes and scales the still on every frame; lambdas
+        # `5pWDD20e` scales it once, after which this is re-measured and rises).
+        # RESIDUAL, stated: a still ABOVE 4K is unmeasured and the schema caps no
+        # overlay resolution, so such an input can exceed the cap at this
+        # duration; 5pWDD20e removes the still-resolution dependence entirely.
+        # Every offered output was measured (sd_480p, hd_720p, fhd_1080p).
+        # Longer inputs route to long_form.
+        short_form:
+          availability: planned
+          ceiling_basis:   # 607(d): proven at the declared value, or not yet (FORMAT.md §ceiling_basis)
+            max_input_duration: unproven
+          constraints:
+            max_input_duration: "PT11M35S"   # floor((cap * headroom - intercept) / slope), 4K still at fhd_1080p
+        # The Fargate route (no invocation ceiling). The duration is the worker's
+        # own guard, MAX_AUDIO_DURATION_SECS 7200 (strict >; KzrquIX7). Planned
+        # until a policy-79 record from the Fargate path exists.
+        long_form:
+          availability: planned
+          ceiling_basis:   # 607(d): proven at the declared value, or not yet (FORMAT.md §ceiling_basis)
+            max_input_duration: unproven
+          constraints:
+            max_input_duration: "PT2H"
       options:
         output_resolution:
           type: enum

package/operations/schemas/audio_watermark.yaml

@@ -75,8 +75,8 @@ operation:
             max_output_size_bytes: 5000000000
           per_tier_constraints:
             max:
-              max_input_size_bytes: 50000000000    # 50 GB (Max self-serve band)
-              max_output_size_bytes: 50000000000
+              max_input_size_bytes: 53687091200    # 50 GiB = api's Max upload cap (decision 677)
+              max_output_size_bytes: 53687091200
             enterprise:
               max_input_size_bytes: 107374182400   # 100 GiB = api's Enterprise upload cap (owner 649(2))
               max_output_size_bytes: 107374182400
@@ -181,8 +181,8 @@ operation:
             max_output_size_bytes: 5000000000
           per_tier_constraints:
             max:
-              max_input_size_bytes: 50000000000    # 50 GB (Max self-serve band)
-              max_output_size_bytes: 50000000000
+              max_input_size_bytes: 53687091200    # 50 GiB = api's Max upload cap (decision 677)
+              max_output_size_bytes: 53687091200
             enterprise:
               max_input_size_bytes: 107374182400   # 100 GiB = api's Enterprise upload cap (owner 649(2))
               max_output_size_bytes: 107374182400

package/operations/schemas/compress.yaml

@@ -746,11 +746,21 @@ operation:
           min: 1
           max: 16384
           honored_on: [same_format, format_change]
+          # oK7WlNaY: lambdas convert image_convert.rs (animation-preserving FFmpeg path) refuses any resize; scale-filter follow-up msP9wWoO. Loop-extension-less GIFs read as static: 0McJYHGy.
           description: >-
             Target width in pixels (1-16384; width × height must not exceed the
             group's maximum output area). Resizes the image as part of the operation
             (one transformed output, replacing the source). Optional; omit to keep the
             source dimensions.
+            Not supported for an ANIMATED image whose output keeps the animation
+            (an animated GIF or WebP converted to GIF or WebP). Where the
+            server can tell the input is animated it refuses at create with 422
+            `feature_not_available`, feature `operation.image.resize.animated`;
+            where it cannot tell, the job is accepted and fails with
+            `invalid_options` — except a multi-frame GIF with no loop extension,
+            which is currently treated as static: it is resized and comes out as
+            its first frame only. Resize a static image, or choose a still output
+            format.
         height:
           type: integer
           min: 1
@@ -992,11 +1002,21 @@ operation:
           min: 1
           max: 16384
           honored_on: [same_format, format_change]
+          # oK7WlNaY: lambdas convert image_convert.rs (animation-preserving FFmpeg path) refuses any resize; scale-filter follow-up msP9wWoO. Loop-extension-less GIFs read as static: 0McJYHGy.
           description: >-
             Target width in pixels (1-16384; width × height must not exceed the
             group's maximum output area). Resizes the image as part of the operation
             (one transformed output, replacing the source). Optional; omit to keep the
             source dimensions.
+            Not supported for an ANIMATED image whose output keeps the animation
+            (an animated GIF or WebP converted to GIF or WebP). Where the
+            server can tell the input is animated it refuses at create with 422
+            `feature_not_available`, feature `operation.image.resize.animated`;
+            where it cannot tell, the job is accepted and fails with
+            `invalid_options` — except a multi-frame GIF with no loop extension,
+            which is currently treated as static: it is resized and comes out as
+            its first frame only. Resize a static image, or choose a still output
+            format.
         height:
           type: integer
           min: 1
@@ -1176,8 +1196,8 @@ operation:
             max_output_size_bytes: 5000000000
           per_tier_constraints:
             max:
-              max_input_size_bytes: 50000000000    # 50 GB (Max self-serve band)
-              max_output_size_bytes: 50000000000
+              max_input_size_bytes: 53687091200    # 50 GiB = api's Max upload cap (decision 677)
+              max_output_size_bytes: 53687091200
             enterprise:
               max_input_size_bytes: 107374182400   # 100 GiB = api's Enterprise upload cap (owner 649(2))
               max_output_size_bytes: 107374182400

package/operations/schemas/convert.yaml

@@ -97,11 +97,21 @@ operation:
           min: 1
           max: 16384
           honored_on: [format_change]
+          # oK7WlNaY: lambdas convert image_convert.rs (animation-preserving FFmpeg path) refuses any resize; scale-filter follow-up msP9wWoO. Loop-extension-less GIFs read as static: 0McJYHGy.
           description: >-
             Target width in pixels (1-16384; width × height must not exceed the
             group's maximum output area). Resizes the image before encoding (one
             transformed output). NOT honored for SVG input. Optional; omit to keep
             the source dimensions.
+            Not supported for an ANIMATED image whose output keeps the animation
+            (an animated GIF or WebP converted to GIF or WebP). Where the
+            server can tell the input is animated it refuses at create with 422
+            `feature_not_available`, feature `operation.image.resize.animated`;
+            where it cannot tell, the job is accepted and fails with
+            `invalid_options` — except a multi-frame GIF with no loop extension,
+            which is currently treated as static: it is resized and comes out as
+            its first frame only. Resize a static image, or choose a still output
+            format.
         height:
           type: integer
           min: 1
@@ -201,8 +211,9 @@ operation:
           values: [jpeg, png, webp, avif, gif, tiff, mp4, webm]
           required: true
           description: >-
-            Target format. The still-image targets (jpeg/png/webp/avif/gif/tiff) take
-            the first frame / rasterise. `mp4` / `webm` are the GIF→VIDEO transcode
+            Target format. `jpeg` / `png` / `avif` / `tiff` take the first frame. `gif`
+            and `webp` keep an animated GIF's animation (a static GIF stays a single
+            frame). `mp4` / `webm` are the GIF→VIDEO transcode
             targets — the animated GIF becomes a muted, play-once video (`mp4` =
             H.264, plays everywhere; `webm` = VP9, smaller), typically far smaller
             than the original GIF. GIFs are silent (no audio stream); the GIF
@@ -240,11 +251,21 @@ operation:
           max: 16384
           depends_on: { output_format: [jpeg, png, webp, avif, gif, tiff] }
           honored_on: [format_change]
+          # oK7WlNaY: lambdas convert image_convert.rs (animation-preserving FFmpeg path) refuses any resize; scale-filter follow-up msP9wWoO. Loop-extension-less GIFs read as static: 0McJYHGy.
           description: >-
             Target width in pixels (1-16384; width × height must not exceed the
             group's maximum output area). Scoped to the STILL-IMAGE targets only —
             resizing while transcoding to the mp4/webm video targets is not yet
             supported, so width/height are not accepted for the video targets.
+            Not supported for an ANIMATED image whose output keeps the animation
+            (an animated GIF or WebP converted to GIF or WebP). Where the
+            server can tell the input is animated it refuses at create with 422
+            `feature_not_available`, feature `operation.image.resize.animated`;
+            where it cannot tell, the job is accepted and fails with
+            `invalid_options` — except a multi-frame GIF with no loop extension,
+            which is currently treated as static: it is resized and comes out as
+            its first frame only. Resize a static image, or choose a still output
+            format.
         height:
           type: integer
           min: 1
@@ -349,8 +370,8 @@ operation:
             max_output_size_bytes: 5000000000
           per_tier_constraints:
             max:
-              max_input_size_bytes: 50000000000    # 50 GB (Max self-serve band)
-              max_output_size_bytes: 50000000000
+              max_input_size_bytes: 53687091200    # 50 GiB = api's Max upload cap (decision 677)
+              max_output_size_bytes: 53687091200
             enterprise:
               max_input_size_bytes: 107374182400   # 100 GiB = api's Enterprise upload cap (owner 649(2))
               max_output_size_bytes: 107374182400

package/operations/schemas/custom_luma.yaml

@@ -81,8 +81,8 @@ operation:
             max_output_size_bytes: 5000000000
           per_tier_constraints:
             max:
-              max_input_size_bytes: 50000000000    # 50 GB (Max self-serve band)
-              max_output_size_bytes: 50000000000
+              max_input_size_bytes: 53687091200    # 50 GiB = api's Max upload cap (decision 677)
+              max_output_size_bytes: 53687091200
             enterprise:
               max_input_size_bytes: 107374182400   # 100 GiB = api's Enterprise upload cap (owner 649(2))
               max_output_size_bytes: 107374182400

package/operations/schemas/merge.yaml

@@ -168,7 +168,8 @@ operation:
         # but ROUTING (which class) is DURATION/SIZE-driven at
         # create-plan, NOT concat-compatibility: the API resolver
         # assigns long_form when summed input duration exceeds the
-        # short_form cap (PT5M) OR summed size exceeds 1 GiB; it has no
+        # short_form cap (PT5M) OR summed size exceeds 500 MiB
+        # (524,288,000 B, the short_form_concat cap); it has no
         # per-input codec/pixfmt at create-plan to decide re-encode-need
         # (MAVh1blw; api d363a4ab). re_encode-vs-stream-copy is a WORKER
         # SUB-MODE WITHIN EACH class, not a long-form differentiator:
@@ -406,6 +407,9 @@ operation:
           min: 0
           max: 51
           default: 23
+          # On long_form_re_encode `encoding_mode` is dropped, and this gate reads its
+          # DEFAULT (`crf`) — FORMAT.md §depends_on rule 5 (aoxAfyt7) — so crf is honoured
+          # there; the long-form worker reads it (merge_processor.rs parse_crf).
           depends_on: { re_encode_mode: [auto, always], encoding_mode: crf }
           description: "Constant Rate Factor when encoding_mode=crf. Lower = higher quality / larger file."