@giveitsmaller/contracts 0.89.0 → 0.90.0

package/dist/operations/split.metadata.js

@@ -1,6 +1,6 @@
 // Auto-generated from split.yaml -- do not edit
 export const splitMetadata = {
-    availability: 'beta',
+    availability: 'stable',
     sole_op: true,
     features: {
         silence_mode_audio: {
@@ -23,7 +23,7 @@ export const splitMetadata = {
             per_input_options: {},
         },
         document_pdf: {
-            availability: 'beta',
+            availability: 'stable',
             processing_class: {},
             per_mime_availability: {},
             options: {

package/openapi/README.md

@@ -10,7 +10,7 @@
 - **Generator:** [openapi-generator-cli](https://openapi-generator.tech/) v7.21.0
   (Docker image: `openapitools/openapi-generator-cli:v7.21.0`)
 - **Generator preset:** `typescript-fetch`, models only
-- **Files:** 275
+- **Files:** 276
 
 ## Contents
 

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.225.0
+  version: 2.227.0
   contact:
     name: API Support
 
@@ -2094,6 +2094,27 @@ 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.
+            - GIF too long (ticket `zfFnNYRY`, hub decision 715). A
+              `convert` of video with `output_format: gif` whose KEPT window
+              (input duration minus `trim_start` and `trim_end`) exceeds the
+              option's `per_value_constraints.gif.max_kept_duration` (`PT10S`).
+              `ValidationErrorEnvelope` with `error: "GIF_TOO_LONG"`; one
+              `details[]` entry `{operation: "convert", option:
+              "output_format", field: "kept_duration", message: "..."}`. The
+              message steers: trim to 10 s, or choose `mp4` / `webm`. **The
+              API waits for the upload probe** for a video->GIF convert whose
+              source is an `upload`, for EVERY caller, signed in or not (owner
+              decision 734): until the
+              duration is known the create is answered `probe_pending` (retry
+              it); after `video.probe_wait_bound_seconds` from the upload
+              (`schemas/anonymous-policy.yaml`), or once the probe lands
+              `ok` without a duration or `missing_metadata`, it proceeds and
+              the worker enforces the same limit. A probe that lands `corrupt` or `unsupported_codec`
+              keeps its terminal handling (surface it; do not retry), as
+              `ProbePendingResponse` describes. Same `ProbePendingResponse` shape (`job_ref`,
+              `Retry-After`). A source with no upload probe (`job_output`,
+              `external_import`, `connection`) is not waited on: it is admitted
+              and the worker enforces the limit.
             - 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`,
@@ -2146,7 +2167,11 @@ paths:
               `ProcessingClassExceedsBandResponse` (`violations[]`).
             - `probe_pending` → `ProbePendingResponse` (`job_ref`, no
               `violations[]`/`details[]`), emitted when the probe-pending
-              gate is on and a job's upload has not yet been probed.
+              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
+              `video.probe_wait_bound_seconds` after the upload.
 
             The prior 422 shape is otherwise preserved unchanged — the
             `details[]` / `violations[]` / `job_ref` required-field shapes
@@ -2279,6 +2304,17 @@ paths:
                         actual: 54000
                         ceiling: 43200
                         required_tier: "enterprise"
+                gif_too_long:
+                  summary: convert video -> gif with a kept window over 10 s (zfFnNYRY)
+                  value:
+                    success: false
+                    error_type: "validation_error"
+                    error: "GIF_TOO_LONG"
+                    details:
+                      - operation: "convert"
+                        option: "output_format"
+                        field: "kept_duration"
+                        message: "A GIF can be at most 10 seconds; this keeps 42 seconds. Trim it to 10 seconds, or choose mp4 or webm."
                 inputs_not_concat_uniform:
                   summary: merge.video long_form_re_encode with one input lacking audio (MjzzPCWt)
                   value:
@@ -10777,7 +10813,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` mime_group is `stable` and `document_pdf` is `beta` (2026-10-01). 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 operation, the `image_gif` mime_group and `document_pdf` are `stable` (prod-proven, owner decision 729, 2026-10-08); `audio` and `video` stay `beta` by their own tags. 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.
@@ -12149,15 +12185,22 @@ components:
           enum:
             - processed_base
             - original
-          default: processed_base
           description: |
             For **derived artifacts** (`thumbnail`, `split`): which canonical
             composition node this artifact branches from. Symbolic-only for
             v1 (no per-operation references — caller-visible op ids do not
-            exist at submit time).
-            - `processed_base` (default): the fully-processed base —
-              post-everything, so the artifact carries the watermark + encode.
-            - `original`: the untouched source file.
+            exist at submit time). **The default depends on the operation**
+            (owner decision 720, 2026-10-08): `thumbnail` defaults to
+            `original`; `split` defaults to `processed_base`.
+            - `processed_base`: the fully-processed base — post-everything,
+              so the artifact carries the watermark + encode, and it runs
+              after the chain.
+            - `original`: the untouched source file. The artifact runs
+              ALONGSIDE the chain (it does not wait for it). Each operation is
+              judged at create against its own ceilings on its own input: a
+              `base: original` thumbnail against the thumbnail ceilings on the
+              original upload. The job still completes when every operation
+              finishes and fails if any fails.
             Ignored for chain operations (compress, convert, watermark, merge,
             audio). The resolved branch point is echoed as
             `CompositionPlanOperation.derived_from` (a `node_id`) in
@@ -14468,7 +14511,9 @@ components:
             `decode_failed` (input unreadable/corrupt),
             `output_too_large` (output exceeded the size limit; NOT for a
             same-format `compress`, which returns the original with
-            `already_optimal` instead — owner decision 645(4)),
+            `already_optimal` instead — owner decision 645(4) — but only when
+            the original satisfies EVERY option the request set; see
+            `OperationMetrics.already_optimal` in the AsyncAPI contract),
             `missing_source` (source not found — fail-fast),
             `invalid_key` (storage key invalid),
             `processing_failed` (non-specific processing failure),
@@ -14574,7 +14619,11 @@ components:
             resolved `same_format` route (`output_format` original, absent, or
             equal to the input's format; not the format-change facade, where
             the original is not what was asked for). A same-format compress
-            that cannot shrink the file returns this, never `output_too_large`.
+            that cannot shrink the file returns this, not `output_too_large` —
+            but ONLY when the original satisfies EVERY option the request set
+            (e.g. not when it asks for a trim, a different channel count, sample
+            rate or bitrate, or new image dimensions); otherwise the failure is
+            `output_too_large` (CvaZWNzO).
             ⚠️ **Today this holds for SHORT-FORM compress only.** Long-form
             compress still fails `output_too_large` until lambdas ships its
             long-form copy path; do not promise "already optimised" or "no
@@ -16890,6 +16939,24 @@ components:
             by `make check-per-value-availability` (CI guard, ticket
             [I17 `0gwtwCav`](https://trello.com/c/0gwtwCav)). Runtime
             emission lands with I3.
+        per_value_constraints:
+          type: object
+          description: |
+            Per-enum-value limits, only meaningful when `type: enum`. Keys
+            MUST be a subset of `values[]`; each entry holds limits that
+            apply only when the request selects that value. Today one
+            constraint: `max_kept_duration` (ISO 8601) — the input's
+            duration minus `trim_start` and `trim_end` may not exceed it;
+            refused at create with `GIF_TOO_LONG` for `convert` video
+            `output_format: gif` (card `zfFnNYRY`). See FORMAT.md
+            §`per_value_constraints`.
+          additionalProperties:
+            type: object
+            additionalProperties: false
+            properties:
+              max_kept_duration:
+                type: string
+                format: duration
         per_value_depends_on:
           type: object
           description: |

package/operation-capabilities/operation-capabilities.json

@@ -643,7 +643,7 @@
         "image",
         "video"
       ],
-      "availability": "beta",
+      "availability": "stable",
       "input": {
         "model": "single"
       },
@@ -734,36 +734,6 @@
         "video"
       ],
       "availability": "stable",
-      "excludes": [
-        {
-          "availability": "stable",
-          "constraint_id": "thumbnail.requires_chain_predecessor",
-          "message": "thumbnail must follow a compress or convert operation.",
-          "when": {
-            "all": [
-              {
-                "not": {
-                  "any": [
-                    {
-                      "opSelected": "compress"
-                    },
-                    {
-                      "opSelected": "convert"
-                    }
-                  ]
-                }
-              },
-              {
-                "not": {
-                  "equals": "document",
-                  "field": "input_mime_group"
-                }
-              }
-            ]
-          },
-          "wire_code": "INVALID_OPERATION_ORDER"
-        }
-      ],
       "input": {
         "model": "single"
       },
@@ -898,5 +868,5 @@
       "isAnimated": "maybe"
     }
   },
-  "schema_version": "2.225.0"
+  "schema_version": "2.227.0"
 }

package/operations/schemas/compress.yaml

@@ -1545,6 +1545,45 @@ operation:
     # rather than the generic unsupported-input reject. EPUB/office/ODF compress and
     # PDF thumbnail/split/convert/transform are UNTOUCHED (Ghostscript's other uses,
     # incl. PDF thumbnails, migrate to Poppler on the lambdas side — no contract change).
+    #
+    # RE-DECLARED 2026-10-08 (owner decision 729 item 1; card U5EPPRPc) on a
+    # permissive stack: qpdf + pikepdf + Pillow (spike: vm_shared/compression_project/
+    # 10_Now/2026-10-08-pdf-compress-spike.md). Re-encodes embedded images (JPEG at
+    # `quality`, longest side capped at `max_image_dimension`) plus a lossless
+    # structural pass, behind a never-larger guard (a result that is not smaller
+    # returns the input, `already_optimal`). Spike: 65-90% on image-heavy and
+    # scanned PDFs at SSIM ~0.997, 1-15% on text-only. `planned` until lambdas builds
+    # the worker and api routes it (co-land: contracts -> lambdas -> api -> e2e).
+    # ONLY the options the worker will read are declared.
+    document_pdf:
+      availability: planned
+      mimes:
+        - application/pdf
+      # Input ceiling (lambdas, 2026-10-09: the worker CLI takes it as a REQUIRED
+      # --max-input-bytes and holds no number of its own). 200 MiB, the value every
+      # other compress document group declares. Not measured on the PDF worker
+      # (not built yet), so `unproven` until lambdas' corner run.
+      ceiling_basis:   # 607(d): proven at the declared value, or not yet (FORMAT.md §ceiling_basis)
+        max_input_size_bytes: unproven
+      max_input_size_bytes: 209715200   # 200 MiB
+      options:
+        quality:
+          type: integer
+          min: 1
+          max: 100
+          default: 70
+          description: >-
+            JPEG quality for the images inside the PDF (1 = smallest, 100 = best).
+            Text and vector content are not re-encoded.
+        max_image_dimension:
+          type: integer
+          min: 64
+          max: 10000
+          default: 1600
+          description: >-
+            Largest width or height, in pixels, for each image inside the PDF; larger
+            images are scaled down, keeping their shape. Smaller images are left as
+            they are.
 
     document_office:
       mimes:

package/operations/schemas/convert.yaml

@@ -380,6 +380,16 @@ operation:
           type: enum
           values: [mp4, webm, ogg, gif, mov, mkv]
           required: true
+          # GIF LENGTH CAP (hub decision 715 applying owner decision 698(6), card
+          # zfFnNYRY): a GIF's KEPT window (input duration minus trim_start and
+          # trim_end) may not exceed PT10S — at the 12 fps / 480 px defaults that
+          # is ~7 MB (lambdas: ~0.71 MB/s), inside Slack/Discord's ~8 MB. Refused at
+          # create with GIF_TOO_LONG; steer: trim to 10 s, or choose mp4/webm
+          # (animated WebP from video is not offered: card d7KfRjvw). FORMAT.md
+          # §per_value_constraints. The worker backstops the same value.
+          per_value_constraints:
+            gif:
+              max_kept_duration: "PT10S"
           # The video codec is DETERMINED by the target container, NOT a caller
           # choice: the convert-video worker hard-wires it per container
           # (mp4 -> H.264/libx264, webm -> VP9, ogg -> Theora, gif -> palette,

package/operations/schemas/split.yaml

@@ -2,7 +2,7 @@ schema_version: "2.0.0"
 
 operation:
   type: split
-  availability: beta
+  availability: stable   # 2026-10-08 (decision 729): the OPERATION is stable so a stable group can resolve stable; every other group pins its own availability below
   description: |
     Fan one input file into N outputs across GIF, PDF, audio, and
     video MIME families. Single-input — one input file per job, fanned
@@ -85,8 +85,9 @@ operation:
     `availability: beta` for the `audio` and `video` mime_groups
     (shape-stable + opt-in, MUST NOT 422). Video activates **both
     classes**: `video.processing_class.short_form` AND `long_form` are
-    `beta`. The `document_pdf` mime_group is `beta` too (2026-10-01), and
-    `image_gif` is `stable` (GIF to frames, 2026-06-21). A value or class
+    `beta`. The `document_pdf` mime_group is `stable` (owner decision 729,
+    prod-proven 2026-10-08), and `image_gif` is `stable` (GIF to frames,
+    prod-proven 2026-10-08). A value or class
     still tagged `planned` (e.g. `precision: exact`) is refused with
     `feature_not_available` (422).
   default: false
@@ -139,7 +140,7 @@ operation:
 
     # PDF base — page-split via qpdf or pdftk equivalent.
     document_pdf:
-      availability: beta   # jGTLrpzK, 2026-10-01: staging worker-direct proof, both modes
+      availability: stable   # owner decision 729 item 2: PROD proof of both modes (e2e, 2026-10-08); beta since 2026-10-01 (jGTLrpzK)
       mimes:
         - application/pdf
       # Byte bound (lambdas, 2026-10-01): the worker downloads the PDF to /tmp

package/operations/schemas/thumbnail.yaml

@@ -5,9 +5,9 @@ operation:
   description: >-
     Resize an image to specific dimensions, or extract a preview frame/page from a video
     or document. For images this is a full resizer (1-16384px), not just small previews.
-    An image or video thumbnail must follow a compress or convert in the same job; a
-    document thumbnail may stand alone. Image types that compress does not accept (BMP,
-    HEIC) therefore need a convert first.
+    A thumbnail can be the only operation on an image, video or document upload. In a job with other operations
+    it is made from the ORIGINAL file by default, alongside them; set `base:
+    processed_base` to make it from the processed result instead.
   default: false
   input_model: single
 
@@ -33,6 +33,17 @@ operation:
       # is NOT the real limit — e.g. 6000x6000 (36MP) is rejected though each axis
       # is < 16384; 6000x2000 (12MP) is fine. The worker enforces this regardless.
       max_output_pixels: 16000000
+      # INPUT CEILINGS (owner decision 720, 2026-10-08): a thumbnail may now be the
+      # first operation, so it is judged on the ORIGINAL upload at create. Values
+      # mirror compress.image (370 MB / 90 MP, lambdas' 607(d) corner run on the
+      # COMPRESSION worker) — lambdas states they fit thumbnail-image's /tmp and its
+      # 100 MP decode cap, with no worker change. Not measured on THIS worker, so
+      # `unproven`.
+      ceiling_basis:   # 607(d): proven at the declared value, or not yet (FORMAT.md §ceiling_basis)
+        max_input_size_bytes: unproven
+        max_input_pixels: unproven
+      max_input_size_bytes: 370000000
+      max_input_pixels: 90000000
       options:
         # IMAGE input is a full resizer (Lanczos): width/height accept the
         # worker's real 1-16384px range (area-capped above) — this op is the

package/package.json

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