@giveitsmaller/contracts 0.91.0 → 0.93.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.229.0
+  version: 2.231.0
   contact:
     name: API Support
 
@@ -2149,15 +2149,52 @@ paths:
               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).
+              carries one, the API refuses that difference at create too.
+              **A video merge WAITS for its inputs' upload probes**, for every
+              caller (owner decision 755, the decision-734 pattern): while any
+              `upload` input is unprobed the create is answered `probe_pending`
+              (`job_ref` = the merge job's ref); after
+              `video.probe_wait_bound_seconds` from that upload
+              (`schemas/anonymous-policy.yaml`), or once its probe lands `ok`
+              without the measured field, that AXIS fails open and the worker
+              gate is its only check for it. An axis that IS known is still
+              decided at create: the summed upload sizes are known without a
+              probe, so a non-uniform set over 500 MiB is refused
+              `MERGE_OVER_LIMIT` (`size_bytes`) even when a duration is missing. That bound is what keeps a probe that
+              never lands from making a create that never succeeds (the
+              2026-09-24 ruling on api's `nmYdwHAH`, which admitted unprobed
+              inputs outright, is superseded by 755 within the window). **An
+              input that is an upstream job's output** has no upload probe and
+              is admitted, as before.
+            - Video merge over the short-form limit (owner decision 755, card
+              `E7iYw68p`). A video merge whose inputs are NOT concat-uniform
+              (a difference in a stream attribute listed under
+              `input_uniformity` above, NOT mixed audio topology, which
+              `short_form_concat` cannot run at any length and keeps
+              `INPUTS_NOT_CONCAT_UNIFORM`) can only
+              run `short_form_concat`, so when their measured total exceeds that
+              class's `max_total_duration` (`PT5M`) or
+              `max_total_input_size_bytes` (500 MiB) it is refused at create.
+              `ValidationErrorEnvelope` with `error: "MERGE_OVER_LIMIT"`; one
+              `details[]` entry `{operation: "merge", field: "inputs",
+              message, message_key, message_params, ceiling}` where `ceiling`
+              is `InputCeilingViolation` with `bound_by: "merge"`, `axis`
+              `duration_seconds` (`actual` = the summed probe durations,
+              rounded UP to whole seconds) or `size_bytes`, and `maximum` the
+              class ceiling in the same unit. Duration is reported when both
+              exceed. `message_key` is `error.merge.combined_too_long`
+              (duration) or `error.merge.combined_too_large` (size);
+              `message_params` repeat `ceiling`. Client copy: "These clips are
+              too long to merge together: {actual} in total, the limit is
+              {maximum}. Trim them, or use clips with the same format and
+              resolution, which can be merged at any length." This REPLACES
+              `INPUTS_NOT_CONCAT_UNIFORM` for such a set, because shortening is
+              the remedy that works. **Precedence:** a request with
+              `re_encode_mode: never` that cannot stream-copy is answered
+              `REQUIRES_REENCODE` first (its remedy, `auto` or `always`, is
+              the caller's choice and may change the outcome); only then is
+              the total checked. A concat-uniform set over the limit is not
+              refused: it routes `long_form_re_encode`.
 
             **Branch dispatch via the `error_type` discriminator** (per
             [ADR-0018](../docs/decisions/0018-universal-422-error-type-discriminator.md)).
@@ -2181,7 +2218,9 @@ paths:
               gate is on and a job's upload has not yet been probed. The gate
               is on for a guest's video create, and for EVERY caller's
               video->GIF `convert` of an `upload` source (owner decision 734,
-              so `GIF_TOO_LONG` is decided at create); in both cases only until
+              so `GIF_TOO_LONG` is decided at create) and video `merge` of
+              `upload` inputs (owner decision 755, so `MERGE_OVER_LIMIT` is
+              decided at create); in every case only until
               `video.probe_wait_bound_seconds` after the upload.
 
             The prior 422 shape is otherwise preserved unchanged — the
@@ -2252,6 +2291,54 @@ paths:
                     details:
                       - field: "workflow_edges"
                         message: "Workflow edges form a cycle."
+                merge_over_limit:
+                  summary: Non-uniform video merge over the short-form total (owner decision 755)
+                  value:
+                    success: false
+                    error_type: "validation_error"
+                    error: "MERGE_OVER_LIMIT"
+                    message: "These clips are too long to merge together."
+                    details:
+                      - operation: "merge"
+                        field: "inputs"
+                        message: "These clips are too long to merge together: 412 s in total, the limit is 300 s. Trim them, or use clips with the same format and resolution, which can be merged at any length."
+                        message_key: "error.merge.combined_too_long"
+                        message_params:
+                          axis: "duration_seconds"
+                          actual: 412
+                          maximum: 300
+                          bound_by: "merge"
+                          input_mime: "video/mp4"
+                        ceiling:
+                          axis: "duration_seconds"
+                          actual: 412
+                          maximum: 300
+                          bound_by: "merge"
+                          input_mime: "video/mp4"
+                input_exceeds_ceiling:
+                  summary: An input over a declared ceiling, bound by a later operation (cxTBYffD)
+                  value:
+                    success: false
+                    error_type: "validation_error"
+                    error: "VALIDATION_FAILED"
+                    message: "Validation failed for operation 'thumbnail' on job ref 'a'."
+                    details:
+                      - operation: "thumbnail"
+                        field: "source"
+                        message: "Input file size (128232024 bytes) exceeds the maximum 104857600 bytes supported for operation 'thumbnail' on 'application/epub+zip'."
+                        message_key: "error.input_exceeds_ceiling"
+                        message_params:
+                          axis: "size_bytes"
+                          actual: 128232024
+                          maximum: 104857600
+                          bound_by: "thumbnail"
+                          input_mime: "application/epub+zip"
+                        ceiling:
+                          axis: "size_bytes"
+                          actual: 128232024
+                          maximum: 104857600
+                          bound_by: "thumbnail"
+                          input_mime: "application/epub+zip"
                 feature_not_available:
                   summary: Workflow references planned features
                   value:
@@ -7562,7 +7649,10 @@ components:
             `re_encode_mode: never` and incompatible inputs; caller
             resolves by switching to `re_encode_mode: auto` or `always`),
             `CYCLIC_WORKFLOW_EDGES` (cyclic/self explicit `workflow_edges`,
-            per `g8PPkbNu`).
+            per `g8PPkbNu`). **Planned, not yet emitted:** `MERGE_OVER_LIMIT`
+            (a non-uniform video merge over `short_form_concat`'s total;
+            `details[].ceiling` carries the numbers, owner decision 755; the
+            API emits it once xuVTM06N ships, see the taxonomy row).
             ⚠️ **`INVALID_OPTIONS` is NOT a create-time wire code**, though
             earlier text here said it was and the example showed it: the
             API has always sent `VALIDATION_FAILED` for option failures
@@ -7639,6 +7729,69 @@ components:
                   `{ "min": 1, "max": 100, "given": 200 }`). See
                   `ErrorEnvelope.message_params`. Excludes cost
                   numbers.
+              ceiling:
+                $ref: '#/components/schemas/InputCeilingViolation'
+
+    InputCeilingViolation:
+      type: object
+      additionalProperties: false
+      description: |
+        Present on a `details[]` entry when the entry reports a measured
+        quantity exceeding a declared ceiling, as data (cards
+        [`cxTBYffD`](https://trello.com/c/cxTBYffD), `E7iYw68p`). It carries
+        what `message` says in prose, so a client can show "22.4 MB, limit
+        20 MiB" and branch on "too large" without reading English. The
+        entry's `message_params` repeat these fields for the localised text.
+
+        Two uses today, told apart by the entry's `message_key`:
+        - `error.input_exceeds_ceiling`: ONE input over an unbanded group's
+          `max_input_size_bytes`, a pixel ceiling, or a duration ceiling.
+        - `error.merge.combined_too_long` / `error.merge.combined_too_large`:
+          the COMBINED inputs of a non-uniform video merge over
+          `short_form_concat`'s total (`MERGE_OVER_LIMIT`, owner decision
+          755). `axis` is the total's axis and `bound_by` is `merge`.
+
+        A job that merely routes to a higher processing class is not an
+        error here: an escalation that finds no class able to take the input
+        is `ProcessingClassExceedsBandResponse`, never this.
+
+        **Optional and additive.** Its absence on a size refusal means the
+        server predates this field; fall back to `message`. Do not read
+        absence as "not a ceiling refusal".
+      required:
+        - axis
+        - actual
+        - maximum
+        - bound_by
+      properties:
+        axis:
+          type: string
+          x-string-vocabulary: open
+          description: |
+            Which quantity exceeded its ceiling. Values today:
+            `size_bytes`, `pixels`, `duration_seconds`. The set is open:
+            treat an unknown axis as "input too large" and show `message`.
+        actual:
+          type: integer
+          format: int64
+          minimum: 0
+          description: The input's measured value on `axis` (bytes, pixels, or whole seconds rounded UP).
+        maximum:
+          type: integer
+          format: int64
+          minimum: 0
+          description: The binding ceiling on `axis`, in the same unit as `actual`.
+        bound_by:
+          type: string
+          description: |
+            The operation whose ceiling binds. **Not always the operation
+            that ingests the file**: in a `[compress, thumbnail]` job the
+            thumbnail's tighter ceiling can refuse a file `compress`
+            accepts, and then this is `thumbnail`. The smallest applicable
+            ceiling across the job's operations is the one reported.
+        input_mime:
+          type: string
+          description: The input's MIME type, as the ceiling was looked up.
 
     AuthRejectionEnvelope:
       type: object
@@ -16284,6 +16437,12 @@ components:
             Where the constraint is evaluated. `api` marks constraints the
             API create-path enforces (vs purely-advisory ones consumers
             mirror for UX). Absent ⇒ unscoped/advisory.
+            Always `api` when `when` reads an API-SUPPLIED token, which is
+            never on the wire, so a client cannot evaluate it and skips the
+            constraint (the API is the backstop): `processing_class`
+            (short/long-form routing) and `input_is_animated` (upload
+            metadata; tri-state, absent = unknown, so `equals: true` never
+            fires on an unknown input).
           enum: [api]
         requires_field:
           type: string

package/operation-capabilities/operation-capabilities.json

@@ -101,6 +101,59 @@
       ],
       "availability": "stable",
       "excludes": [
+        {
+          "availability": "stable",
+          "constraint_id": "compress.image.resize.animated",
+          "eval_scope": "api",
+          "message": "Resizing an animated GIF or WebP that stays animated is not available yet. Resize a still image, or convert to a still format.",
+          "when": {
+            "all": [
+              {
+                "field": "input_mime",
+                "in": [
+                  "image/gif",
+                  "image/webp"
+                ]
+              },
+              {
+                "equals": true,
+                "field": "input_is_animated"
+              },
+              {
+                "not": {
+                  "all": [
+                    {
+                      "field": "convert.output_format",
+                      "isSet": true
+                    },
+                    {
+                      "not": {
+                        "field": "convert.output_format",
+                        "in": [
+                          "gif",
+                          "webp"
+                        ]
+                      }
+                    }
+                  ]
+                }
+              },
+              {
+                "any": [
+                  {
+                    "field": "compress.width",
+                    "isSet": true
+                  },
+                  {
+                    "field": "compress.height",
+                    "isSet": true
+                  }
+                ]
+              }
+            ]
+          },
+          "wire_code": "feature_not_available"
+        },
         {
           "availability": "stable",
           "constraint_id": "compress.audio.format_facade.knob",
@@ -441,6 +494,61 @@
         "video"
       ],
       "availability": "stable",
+      "excludes": [
+        {
+          "availability": "stable",
+          "constraint_id": "convert.image.resize.animated",
+          "eval_scope": "api",
+          "message": "Resizing an animated GIF or WebP that stays animated is not available yet. Resize a still image, or convert to a still format.",
+          "when": {
+            "all": [
+              {
+                "field": "input_mime",
+                "in": [
+                  "image/gif",
+                  "image/webp"
+                ]
+              },
+              {
+                "equals": true,
+                "field": "input_is_animated"
+              },
+              {
+                "not": {
+                  "all": [
+                    {
+                      "field": "convert.output_format",
+                      "isSet": true
+                    },
+                    {
+                      "not": {
+                        "field": "convert.output_format",
+                        "in": [
+                          "gif",
+                          "webp"
+                        ]
+                      }
+                    }
+                  ]
+                }
+              },
+              {
+                "any": [
+                  {
+                    "field": "convert.width",
+                    "isSet": true
+                  },
+                  {
+                    "field": "convert.height",
+                    "isSet": true
+                  }
+                ]
+              }
+            ]
+          },
+          "wire_code": "feature_not_available"
+        }
+      ],
       "input": {
         "model": "single"
       },
@@ -868,5 +976,5 @@
       "isAnimated": "maybe"
     }
   },
-  "schema_version": "2.229.0"
+  "schema_version": "2.231.0"
 }

package/operations/schemas/merge.yaml

@@ -200,6 +200,12 @@ operation:
           ceiling_basis:   # 607(d): proven at the declared value, or not yet (FORMAT.md §ceiling_basis)
             max_total_input_size_bytes: proven
             max_total_duration: proven
+          # OWNER DECISION 755 (E7iYw68p): a NON-UNIFORM set can only run this
+          # class (long_form_re_encode refuses it), so over these totals it is
+          # refused at create with MERGE_OVER_LIMIT and the numbers
+          # (details[].ceiling), instead of INPUTS_NOT_CONCAT_UNIFORM. The API
+          # waits for the inputs' probes to measure the total. A uniform set
+          # over them routes long_form_re_encode as before.
           constraints:
             max_total_duration: "PT5M"
             max_total_input_size_bytes: 524288000    # 500 MiB combined (the stream-copy ceiling; was 1 GiB)

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@giveitsmaller/contracts",
-  "version": "0.91.0",
-  "description": "Generated contract types for GISL (Give It Smaller). Generated from compression_contracts spec v2.229.0.",
-  "gislContractsSpec": "v2.229.0",
+  "version": "0.93.0",
+  "description": "Generated contract types for GISL (Give It Smaller). Generated from compression_contracts spec v2.231.0.",
+  "gislContractsSpec": "v2.231.0",
   "license": "Apache-2.0",
   "homepage": "https://docs.giveitsmaller.com",
   "bugs": {