@giveitsmaller/contracts 0.70.0 → 0.72.0

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).  **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.201.0
+ * The version of the OpenAPI document: 2.203.0
  *
  *
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).

package/dist/operations/audio_to_video.metadata.js

@@ -1,6 +1,6 @@
 // Auto-generated from audio_to_video.yaml -- do not edit
 export const audioToVideoMetadata = {
-    availability: 'stable',
+    availability: 'planned',
     features: {},
     mime_groups: {
         audio: {

package/dist/operations/video_watermark.metadata.js

@@ -1,6 +1,6 @@
 // Auto-generated from video_watermark.yaml -- do not edit
 export const videoWatermarkMetadata = {
-    availability: 'stable',
+    availability: 'planned',
     features: {
         multi_overlay_stack: {
             availability: 'planned',
@@ -11,7 +11,7 @@ export const videoWatermarkMetadata = {
         video: {
             processing_class: {
                 short_form: {
-                    availability: 'stable',
+                    availability: 'planned',
                     constraints: {
                         max_input_duration: 'PT5M',
                         max_input_size_bytes: 524288000,

package/openapi/api.yaml

@@ -89,7 +89,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.201.0
+  version: 2.203.0
   contact:
     name: API Support
 
@@ -9717,9 +9717,9 @@ components:
         - custom_luma: Apply a caller-uploaded luma matte to a base video for a custom luma-matte transition effect. Multi-input (`role: base` + `role: transition_mask`). `availability: planned` + `required_tier: pro`; dispatch returns `feature_not_available` (422) until Lambda ships. Distinct from FFmpeg `xfade=custom` (which is an expression, not an operation). Per ticket I29 (Trello EPUE5Vs1).
         - audio_overlay: Mix a secondary audio asset over a primary audio or video base (DJ tags, podcast intros/outros, station IDs, jingles). Multi-input (`role: base` + `role: overlay`). `availability: planned`; dispatch returns `feature_not_available` (422) until Lambda ships. **NOT** the same as `audio_watermark` — that operation is steganographic (imperceptible identifier embedded for ownership tracking), tracked separately by I20. Per ticket I19 (Trello Xr3Z4GBF).
         - audio_watermark: Embed a steganographic forensic watermark into an audio asset (or a video's audio track) — Cinavia / Resemble PerTh territory. Single-input. `availability: planned` + `required_tier: enterprise`; dispatch returns `feature_not_available` (422) until Lambda ships. Pairs with `POST /api/audio-watermark/decode` for own-watermarks-only extraction. Per ticket I20 (Trello omiCq7Vn).
-        - 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: beta` (Wave A — Lambda backend live; opt-in, MUST NOT return `feature_not_available`; may change with notice). 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: beta` (Wave A — Lambda backend live; opt-in, MUST NOT 422; `short_form` is beta, `long_form` stays `planned` — no live Fargate worker; `multi_overlay_stack` stays `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`; dispatch returns `feature_not_available` (422) until Lambda ships. Per ticket [`4NrRPCgh`](https://trello.com/c/4NrRPCgh) + ADR-0013.
+        - 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: measured 0.300 s of encode per second of output PLUS A 7 s FIXED COST, so the advertised PT2H needs 2167 s against a 900 s platform maximum (0.300 x 7200 alone is 2160 — the intercept is what makes the figure 2167, and a consumer dividing 600 by 0.300 gets a 2000 s in-flight boundary where the real one is 1976 s). 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 ~1976 s ON THE INPUT THE RATE WAS MEASURED WITH (a real photographic 1080p still plus looped real audio), where 0.300 s per second plus a 7 s 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 at 606 s by 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 606 s 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 at 604 s by 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 but NOT yet proven end-to-end per [`rcwvUKhI`](https://trello.com/c/rcwvUKhI); the first customer-path soak has not completed, the 4GB+ speed-up is unmeasured, and the long-form fan-out is flag-gated dark). 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.
         - 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).
 
@@ -10950,9 +10950,11 @@ components:
               planned` so workflow-create returns 422 until Lambda
               ships), `audio_overlay` (joined via ticket
               [I19](https://trello.com/c/Xr3Z4GBF) — same `planned`
-              gating), and `audio_to_video` + `video_watermark` (joined
-              via Wave A [`c3uthIP4`](https://trello.com/c/c3uthIP4) —
-              `availability: beta`, backends live). The multi-input
+              gating), and `audio_to_video` + `video_watermark`
+              (WITHDRAWN 2026-09-15 — `availability: planned`; the backends
+              are live but cannot serve the advertised ceilings, so
+              workflow-create returns `feature_not_available` 422). The
+              multi-input
               shape is contract-defined for all entries.
         - if:
             properties:

package/operation-capabilities/operation-capabilities.json

@@ -51,7 +51,7 @@
       "accepts": [
         "audio"
       ],
-      "availability": "stable",
+      "availability": "planned",
       "input": {
         "max": 2,
         "min": 1,
@@ -638,7 +638,7 @@
       "accepts": [
         "video"
       ],
-      "availability": "stable",
+      "availability": "planned",
       "input": {
         "max": 2,
         "min": 2,
@@ -732,5 +732,5 @@
       "isAnimated": "maybe"
     }
   },
-  "schema_version": "2.201.0"
+  "schema_version": "2.203.0"
 }

package/operations/schemas/audio_to_video.yaml

@@ -2,7 +2,7 @@ schema_version: "2.0.0"
 
 operation:
   type: audio_to_video
-  availability: stable
+  availability: planned
   description: |
     Produce a video from an audio input plus an OPTIONAL still image
     overlay. Use cases: podcast → YouTube uploads, audio-only tracks
@@ -26,10 +26,30 @@ operation:
     A lower framerate plus still-image tuning keeps file size tiny
     when the overlay is a still image (the common case).
 
-    Activated to `availability: beta`: the backend is live (API
-    accepts + publishes), so this is shape-stable + opt-in for callers
-    and MUST NOT return `feature_not_available` — it may still change
-    with notice while beta.
+    `availability: planned` — withdrawn 2026-09-15. Measured encode cost is
+    0.300 s per second of output PLUS A 7 s FIXED COST, so the advertised PT2H
+    needs 2167 s against a 900 s platform maximum. ⚠️ The 7 s is not a rounding
+    detail: 0.300 x 7200 alone is 2160, and a consumer dividing 600 by 0.300
+    derives a 2000 s in-flight boundary where the real one is ~1976 s. Workflow-create returns `feature_not_available` (422).
+
+    ⚠️ An already-accepted workflow is NOT cancelled — availability is checked at
+    create — and it is NOT thereby doomed. ⛔ DO NOT READ THIS AS "in-flight work
+    fails": the 60 s and 120 s cells behind this withdrawal both COMPLETED WITH
+    OUTPUT, which is precisely why the evidence is arithmetic rather than a kill.
+    What fails is an accepted workflow whose OUTPUT DURATION exceeds ~1976 s
+    ⚠️ ON THE INPUT THE RATE WAS MEASURED WITH — a real photographic 1080p STILL
+    plus looped real audio — the point at which 0.300 s/s plus the 7 s 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 —
+    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
+    PUBLISHED (`schemas/manifest-divergence-register.yaml` is working material
+    for the drift gate and is not in the npm tarball).
 
   default: false
   input_model: multi

package/operations/schemas/video_text_watermark.yaml

@@ -22,8 +22,21 @@ operation:
     - `tiled`: text tiled across the source frames at the rotation
       angle.
 
-    `availability: planned` until the cross-repo backend support ships;
-    dispatch returns `feature_not_available` (422) until then.
+    `availability: planned` — withdrawn 2026-09-15. A real 1080p source at the
+    advertised PT5M could not finish inside the worker's 600 s encode cap.
+    Workflow-create returns `feature_not_available` (422).
+
+    ⚠️ An already-accepted workflow is NOT cancelled — availability is checked at
+    create — and it is NOT thereby doomed. ⛔ The withdrawal rests on ONE measured
+    point: a 435 MB / 300 s real 1080p source KILLED at 604 s with no output.
+    Work far enough inside the 600 s cap still completes, and NOTHING MEASURED
+    SAYS WHERE THE BOUNDARY IS. What a caller sees when a job crosses it 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
+    PUBLISHED (`schemas/manifest-divergence-register.yaml` is working material
+    for the drift gate and is not in the npm tarball).
+
   default: false
   input_model: single
   sole_op: true   # bypasses V1 chain validation — must be the only operation in its job (ADR-0025)

package/operations/schemas/video_watermark.yaml

@@ -2,7 +2,7 @@ schema_version: "2.0.0"
 
 operation:
   type: video_watermark
-  availability: stable
+  availability: planned
   description: |
     Apply an image overlay onto a base video
     asset. Multi-input role-based:
@@ -22,16 +22,23 @@ operation:
     unchanged (stream-copied) — the watermark applies to the visual
     track only.
 
-    Activated to `availability: beta` (Wave A, ticket
-    [`c3uthIP4`](https://trello.com/c/c3uthIP4)): the cross-repo backend
-    is live (API accepts + publishes via the operations SNS
-    topic), so the operation and its `short_form` processing class are
-    shape-stable + opt-in and MUST NOT return `feature_not_available`.
-    `long_form` stays `planned` (its long-form path is not yet
-    provisioned) and the `multi_overlay_stack` feature stays `planned`
-    (backend support unconfirmed); requesting those planned sub-features
-    DOES still return `feature_not_available` until they are separately
-    activated.
+    `availability: planned` — withdrawn 2026-09-15. A real 1080p source at the
+    advertised PT5M / 500 MB could not finish inside the worker's 600 s encode
+    cap. Workflow-create returns `feature_not_available` (422).
+
+    ⚠️ An already-accepted workflow is NOT cancelled — availability is checked at
+    create — and it is NOT thereby doomed. ⛔ The withdrawal rests on ONE measured
+    point: the same source plus a PNG overlay, KILLED at 606 s with no output, on
+    3008 MB — 47% more memory than `video_text_watermark` and dead at the same
+    second, which is what rules out resizing the function as the remedy. Work far
+    enough inside the 600 s cap still completes, and NOTHING MEASURED SAYS WHERE
+    THE BOUNDARY IS. What a caller sees when a job crosses it 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
+    PUBLISHED (`schemas/manifest-divergence-register.yaml` is working material
+    for the drift gate and is not in the npm tarball).
+
   default: false
   input_model: multi
   sole_op: true   # bypasses V1 chain validation — must be the only operation in its job (ADR-0025)
@@ -62,7 +69,7 @@ operation:
         - video/webm
       processing_class:
         short_form:
-          availability: stable
+          availability: planned
           constraints:
             max_input_duration: "PT5M"
             max_input_size_bytes: 524288000

package/package.json

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