@giveitsmaller/contracts 0.89.0 → 0.91.0

package/dist/openapi/runtime.d.ts

@@ -2,7 +2,7 @@
  * GISL Compression API
  * REST API for the GISL (Give It Smaller) file compression and processing service.  **Architecture:** - Upload files to get a `file_id` - Create workflows referencing uploaded files with operations (compress, thumbnail, image_watermark, text_watermark, merge, archive, convert, custom_luma, audio_overlay, audio_watermark) - Poll status, stream SSE events, or receive webhook callbacks - Download results per operation output  **Response envelope:** All mutation and query endpoints return `{ success: true, data: {...} }` on success and `{ success: false, error: \"...\", details: [...] }` on failure. Exceptions: `GET /api/operations/schema` returns raw JSON (per-tier private caching with ETag revalidation per ADR-0002 + I3), health probes return flat objects, and `POST /api/contact` returns 204 with no body.  **Availability metadata.** This spec uses the `x-availability` vendor extension as **decorative documentation only**. Per [ADR-0001](../docs/decisions/0001-contract-first-availability.md) §1.5, the runtime endpoint `GET /api/operations/schema` (ticket I3) is the authoritative source; the sidecar `availability.json` (ticket I3b) is the authoritative companion (generated, never hand-edited; CI cross-checks runtime ⇄ sidecar). SDKs MUST NOT depend on `x-availability` reaching generated code — code-generators that surface vendor extensions may emit it as documentation, but consumers read availability from the runtime endpoint, not from the generated bindings.  The 5-value vocabulary (`stable | beta | experimental | planned | deprecated`) is defined in the `AvailabilityValue` schema. See `schemas/FORMAT.md` §Availability Taxonomy for the operational rules (parser obligation: absent = stable; per-enum-value granularity is the `per_value_availability` primitive landed via ticket I17).  **Free-text string fields: `x-string-vocabulary` (ticket [`Q79yjcFF`](https://trello.com/c/Q79yjcFF)).** A `type: string` field with no `enum` that names example values says, as data, what a client may do with them (the same marker is used in the AsyncAPI document): - `open` — a vocabulary that grows. Each published value keeps its   meaning, the SET is not closed: switch on the values you know and   handle an unknown one as the generic case (e.g. `ErrorEnvelope.error`). - `advisory` — explanatory text. Display or log it; **never switch on   it** (e.g. `SseWorkflowTerminalData.reason`). - `none` — not a vocabulary at all (an expression or an identifier,   e.g. `OptionSchema.pattern`). A field whose description hedges with \"common values\" or \"free-form\" must carry the marker; a test enforces it.  **Localisation (per ticket [I26](https://trello.com/c/rcnqwgI4)).**  Error responses + paused/blocked workflow statuses carry a localised human-readable `message` alongside a stable, never-localised `message_key`. Machine-readable fields (`error`, enum values, status codes) stay canonical English.  - **Currently committed locales:** `en-GB` only (per ticket   [`4GKyuYo6`](https://trello.com/c/4GKyuYo6)). The I26 carrier   shape (`Accept-Language` + `Content-Language` + `Vary` headers +   `locale` envelope field + `message_key` + `message_params`) is   stable and exercised; the **catalog** of translated `message`   strings is en-GB-only at runtime today. Additional locales (e.g.   `pt-PT`) will be advertised by name when their catalogs ship —   the request/response carrier shape does NOT change when a new   locale lands. Treat unrequested locales as \"machine-code +   `message_key` path is committed; localised `message` prose is   not\" until this prose enumerates them by name. - **Request:** `Accept-Language` header per RFC 9110 §12.5.4 (q-value   negotiation supported). The server selects the best-match locale   from its supported list; falls back to `en-GB` when no match —   which, until additional catalogs land, is every non-`en-GB`   `Accept-Language`. - **Response:** `Content-Language: <locale>` echo on every localised   response; `Vary: Accept-Language` on every response (CDN/cache   correctness — different `Accept-Language` requests produce   different responses). `Vary` is emitted unconditionally so the   header contract does not flip when a second locale ships. - **Fallback locale:** `en-GB` (also the canonical locale for   `message_key` translations and English `message` prose). - **SDK guidance:** switch on `error` (machine code) for typed   error branches; surface `message_key` to client-side i18n   catalogs (SDK companion work tracked at X19, cross-repo);   display `message` for end-user UI; **never parse `message` for   control flow** — it changes per locale.  Carrier shape lives on `ErrorEnvelope` (envelope-level optional `message_key` + `message` + `locale` + `message_params`) and `ValidationErrorEnvelope` (also per-`details[]` entry). Existing 402 / 403 / 422 envelopes (`BalanceExhaustedResponse`, `FeatureNotAvailableResponse`, `FeatureTierRestrictedResponse`, `WorkflowPausedDetail`) inherit the convention.  **Upload thresholds (per tickets [u0ar7Yye](https://trello.com/c/u0ar7Yye) + [58nBQLWQ](https://trello.com/c/58nBQLWQ)).** Canonical upload constants (single-shot cap, multipart chunk size, multipart concurrency default, multipart first-chunk size) live on the `UploadThresholds` schema with `const:`-pinned values. SDK generators emit these as typed binding constants so frontend / API / SDKs reference one source 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.
  *
- * The version of the OpenAPI document: 2.225.0
+ * The version of the OpenAPI document: 2.229.0
  *
  *
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).

package/dist/openapi/runtime.js

@@ -4,7 +4,7 @@
  * GISL Compression API
  * REST API for the GISL (Give It Smaller) file compression and processing service.  **Architecture:** - Upload files to get a `file_id` - Create workflows referencing uploaded files with operations (compress, thumbnail, image_watermark, text_watermark, merge, archive, convert, custom_luma, audio_overlay, audio_watermark) - Poll status, stream SSE events, or receive webhook callbacks - Download results per operation output  **Response envelope:** All mutation and query endpoints return `{ success: true, data: {...} }` on success and `{ success: false, error: \"...\", details: [...] }` on failure. Exceptions: `GET /api/operations/schema` returns raw JSON (per-tier private caching with ETag revalidation per ADR-0002 + I3), health probes return flat objects, and `POST /api/contact` returns 204 with no body.  **Availability metadata.** This spec uses the `x-availability` vendor extension as **decorative documentation only**. Per [ADR-0001](../docs/decisions/0001-contract-first-availability.md) §1.5, the runtime endpoint `GET /api/operations/schema` (ticket I3) is the authoritative source; the sidecar `availability.json` (ticket I3b) is the authoritative companion (generated, never hand-edited; CI cross-checks runtime ⇄ sidecar). SDKs MUST NOT depend on `x-availability` reaching generated code — code-generators that surface vendor extensions may emit it as documentation, but consumers read availability from the runtime endpoint, not from the generated bindings.  The 5-value vocabulary (`stable | beta | experimental | planned | deprecated`) is defined in the `AvailabilityValue` schema. See `schemas/FORMAT.md` §Availability Taxonomy for the operational rules (parser obligation: absent = stable; per-enum-value granularity is the `per_value_availability` primitive landed via ticket I17).  **Free-text string fields: `x-string-vocabulary` (ticket [`Q79yjcFF`](https://trello.com/c/Q79yjcFF)).** A `type: string` field with no `enum` that names example values says, as data, what a client may do with them (the same marker is used in the AsyncAPI document): - `open` — a vocabulary that grows. Each published value keeps its   meaning, the SET is not closed: switch on the values you know and   handle an unknown one as the generic case (e.g. `ErrorEnvelope.error`). - `advisory` — explanatory text. Display or log it; **never switch on   it** (e.g. `SseWorkflowTerminalData.reason`). - `none` — not a vocabulary at all (an expression or an identifier,   e.g. `OptionSchema.pattern`). A field whose description hedges with \"common values\" or \"free-form\" must carry the marker; a test enforces it.  **Localisation (per ticket [I26](https://trello.com/c/rcnqwgI4)).**  Error responses + paused/blocked workflow statuses carry a localised human-readable `message` alongside a stable, never-localised `message_key`. Machine-readable fields (`error`, enum values, status codes) stay canonical English.  - **Currently committed locales:** `en-GB` only (per ticket   [`4GKyuYo6`](https://trello.com/c/4GKyuYo6)). The I26 carrier   shape (`Accept-Language` + `Content-Language` + `Vary` headers +   `locale` envelope field + `message_key` + `message_params`) is   stable and exercised; the **catalog** of translated `message`   strings is en-GB-only at runtime today. Additional locales (e.g.   `pt-PT`) will be advertised by name when their catalogs ship —   the request/response carrier shape does NOT change when a new   locale lands. Treat unrequested locales as \"machine-code +   `message_key` path is committed; localised `message` prose is   not\" until this prose enumerates them by name. - **Request:** `Accept-Language` header per RFC 9110 §12.5.4 (q-value   negotiation supported). The server selects the best-match locale   from its supported list; falls back to `en-GB` when no match —   which, until additional catalogs land, is every non-`en-GB`   `Accept-Language`. - **Response:** `Content-Language: <locale>` echo on every localised   response; `Vary: Accept-Language` on every response (CDN/cache   correctness — different `Accept-Language` requests produce   different responses). `Vary` is emitted unconditionally so the   header contract does not flip when a second locale ships. - **Fallback locale:** `en-GB` (also the canonical locale for   `message_key` translations and English `message` prose). - **SDK guidance:** switch on `error` (machine code) for typed   error branches; surface `message_key` to client-side i18n   catalogs (SDK companion work tracked at X19, cross-repo);   display `message` for end-user UI; **never parse `message` for   control flow** — it changes per locale.  Carrier shape lives on `ErrorEnvelope` (envelope-level optional `message_key` + `message` + `locale` + `message_params`) and `ValidationErrorEnvelope` (also per-`details[]` entry). Existing 402 / 403 / 422 envelopes (`BalanceExhaustedResponse`, `FeatureNotAvailableResponse`, `FeatureTierRestrictedResponse`, `WorkflowPausedDetail`) inherit the convention.  **Upload thresholds (per tickets [u0ar7Yye](https://trello.com/c/u0ar7Yye) + [58nBQLWQ](https://trello.com/c/58nBQLWQ)).** Canonical upload constants (single-shot cap, multipart chunk size, multipart concurrency default, multipart first-chunk size) live on the `UploadThresholds` schema with `const:`-pinned values. SDK generators emit these as typed binding constants so frontend / API / SDKs reference one source 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.
  *
- * The version of the OpenAPI document: 2.225.0
+ * The version of the OpenAPI document: 2.229.0
  *
  *
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).

package/dist/operations/compress.d.ts

@@ -315,6 +315,10 @@ export interface CompressVideoOptions {
     trim_end?: number;
     speed?: number;
 }
+export interface CompressDocumentPdfOptions {
+    quality?: number;
+    max_image_dimension?: number;
+}
 export interface CompressDocumentOfficeOptions {
     quality?: number;
     strip_macros?: boolean;

package/dist/operations/compress.metadata.js

@@ -396,6 +396,20 @@ export const compressMetadata = {
             },
             per_input_options: {},
         },
+        document_pdf: {
+            availability: 'beta',
+            processing_class: {},
+            per_mime_availability: {},
+            options: {
+                quality: {
+                    per_value_availability: {},
+                },
+                max_image_dimension: {
+                    per_value_availability: {},
+                },
+            },
+            per_input_options: {},
+        },
         document_office: {
             processing_class: {},
             per_mime_availability: {},

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.229.0
   contact:
     name: API Support
 
@@ -2094,6 +2094,38 @@ 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.
+            - Input password-protected. A job whose `upload` source has a
+              completed probe with `probe_status: password_protected` is
+              refused at create. `ValidationErrorEnvelope` with `error:
+              "INPUT_PASSWORD_PROTECTED"`; one `details[]` entry `{field:
+              "source", message: "..."}`. Client copy: "This PDF is
+              password-protected. Remove the password and upload it again."
+              A file that reaches a worker encrypted (no probe) fails
+              `invalid_format`; the worker attaches `message_key`
+              `document.pdf.password_protected`
+              (`schemas/operation-message-keys.yaml`) once lambdas ships it —
+              until then the bare `invalid_format` headline applies.
             - 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 +2178,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 +2315,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 +10824,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 +12196,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
@@ -13110,6 +13164,14 @@ components:
           could not extract enough metadata to make a routing
           decision. Caller may proceed at their own risk; the
           workflow-create routing fallback applies.
+        - `password_protected`: the file is encrypted (a PDF with a
+          password), so it cannot be read. Caller removes the password
+          and uploads again. Distinct from `corrupt`, which says the file
+          is damaged (e2e prod proof, 2026-10-10).
+          **Rollout order (strict readers exist):** the API and the SDKs
+          accept this value BEFORE the prober emits it — a reader that maps
+          the enum strictly (api's ProbeStatus, the generated Python SDK)
+          fails to decode an unknown value despite `x-enum-openness: open`.
       # OPEN. `ok` is the only proceed value and everything else is a reason not to,
       # so a consumer branches on `ok` rather than enumerating failures. A new
       # failure reason is additive and an old consumer treats it correctly as
@@ -13120,6 +13182,7 @@ components:
         - corrupt
         - unsupported_codec
         - missing_metadata
+        - password_protected
 
     UploadProbeProcessingClass:
       type: string
@@ -14468,7 +14531,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 +14639,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 +16959,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.229.0"
 }

package/operations/schemas/compress.yaml

@@ -1545,6 +1545,49 @@ 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:
+      # planned -> beta 2026-10-10 (owner decision 744): worker live on prod
+      # (gisl-prod-euw1-compression-document = documents/v2.1.0, git-a396b6a);
+      # staging proof in availability/staging-verification-log.yaml. A signed PDF
+      # comes back unchanged (already_optimal); an encrypted PDF fails invalid_format.
+      availability: beta
+      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.91.0",
+  "description": "Generated contract types for GISL (Give It Smaller). Generated from compression_contracts spec v2.229.0.",
+  "gislContractsSpec": "v2.229.0",
   "license": "Apache-2.0",
   "homepage": "https://docs.giveitsmaller.com",
   "bugs": {