@giveitsmaller/contracts 0.79.0 → 0.80.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.214.0
+  version: 2.215.0
   contact:
     name: API Support
 
@@ -6543,11 +6543,9 @@ paths:
         **How to observe the grant:** poll `GET /api/v2/credits/usage`
         for a transaction whose `reference_id` equals the `session_id`
         returned here, and whose `reference_type` is
-        `stripe_checkout_session`. **Today that is the only
-        client-observable correlation** between a checkout and its credits.
-        `GET /api/billing/checkout/{sessionId}/status` is declared as the
-        second one, but it is `planned` (a `422 feature_not_available`)
-        until the API implements it.
+        `stripe_checkout_session`. The other, simpler
+        correlation is `GET /api/billing/checkout/{sessionId}/status`
+        (`beta` since 2026-09-25): poll it until `paid`.
 
         🔴 **MATCH ON `reference_type` + `reference_id`, AND DO NOT
         FILTER ON `type`.** The pack grant is written as an
@@ -6784,6 +6782,15 @@ paths:
         BEFORE the API builds it (hub ruling, Option A, 2026-08-29); the API
         half is [`JHrV4MUg`](https://trello.com/c/JHrV4MUg).
 
+        **`beta` since 2026-09-25**: api v1.14.0 (which ships it) is live on
+        PROD, verified by api from the running service (ECS
+        `gisl-prod-euw1-api:27`, image = ECR v1.14.0, the
+        `checkout_sessions` migration applied) and confirmed by the hub.
+        Production has exercised only the `unknown` path. **It becomes
+        `stable` after the first real PAID checkout on prod** (the owner's or
+        a customer's, evidenced from api logs or the ledger; never a
+        synthetic live session) shows `pending` then `paid` for its session.
+
         **Why it exists:** between "checkout created" and "the provider's
         callback lands" nothing used to record that the session existed or
         whose it was — so a post-checkout page, asked about the NORMAL
@@ -6823,7 +6830,7 @@ paths:
       operationId: getCheckoutSessionStatus
       security: [{bearerAuth: []}, {sessionAuth: []}]  # required; answers only about the caller's own sessions
       x-identity-scoped: true  # a session belongs to the caller who created it
-      x-availability: planned
+      x-availability: beta
       tags:
         - Billing
       parameters:
@@ -6843,8 +6850,7 @@ paths:
             caller's (see the collapse rationale above). An id the router
             cannot route (for example invalid UTF-8 such as `cs_%FF`) is a
             `404` before this endpoint runs; that answer is the same for
-            every caller and every session, so it reveals nothing. While the endpoint is `planned` it
-            answers `422 feature_not_available` instead.
+            every caller and every session, so it reveals nothing.
           content:
             application/json:
               schema:
@@ -6887,13 +6893,6 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorEnvelope'
-        '422':
-          description: |
-            `feature_not_available` while this endpoint is `planned`.
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/FeatureNotAvailableResponse'
         '429':
           description: |
             Rate limit exceeded. This endpoint is limited as a STATUS POLL
@@ -10426,9 +10425,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` (no tier gate); 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` (no tier gate since 2026-09-23); 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: 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.
+        - audio_to_video: Produce a video from an audio input plus an OPTIONAL still image overlay. Multi-input role-based with the first OPTIONAL role on the contract (`role: base` audio required, `role: overlay` image 0..1 — see `per_role_cardinality`). When overlay is omitted, the video uses a solid background colour. `availability: planned` — WITHDRAWN 2026-09-15: the measured encode cost (a per-second rate PLUS A FIXED COST) puts the advertised PT2H at more than twice the 900 s platform maximum (dropping the fixed cost moves the in-flight boundary by tens of seconds; figures in the CHANGELOG entry for 2.203.0, derived and tested from the divergence register). Returns `feature_not_available` (422) at workflow-create. An already-accepted workflow is not cancelled (availability is checked at create) and fails only when its output duration exceeds the derived ceiling (divergence register `evidence.derived.ceiling_s`) ON THE INPUT THE RATE WAS MEASURED WITH (a real photographic 1080p still plus looped real audio), where the measured rate plus the fixed cost reaches the worker's 600 s cap — the 60 s and 120 s measured cells both COMPLETED. The driver is the STILL'S RESOLUTION, not duration alone: a 4K still is roughly 4x the rate (unmeasured), which would put the boundary near a quarter of that, and this schema places no constraint on the overlay's resolution. Per ticket [`SlluxMBN`](https://trello.com/c/SlluxMBN) + ADR-0015 (introduces `per_role_cardinality` vocab).
+        - video_watermark: Apply an image overlay onto a base video via FFmpeg's `overlay` filter. Multi-input role-based (`role: base` video + `role: overlay` image, exactly one of each per `per_role_cardinality`). Re-encode required; audio stream-copy passthrough. Distinct from `image_watermark` (pure-Rust/image-only). `availability: planned` — WITHDRAWN 2026-09-15, operation AND `short_form`: a real 1080p source at the advertised PT5M / 500 MB was killed just past the worker's 600 s encode cap, no output. Returns `feature_not_available` (422) at workflow-create; an already-accepted workflow is not cancelled and fails only if it exceeds that cap; the kill is ONE measured point and nothing measured says where the boundary is. `long_form` and `multi_overlay_stack` were already `planned`. Per ticket [`4NrRPCgh`](https://trello.com/c/4NrRPCgh) + ADR-0013.
+        - video_text_watermark: Render a text overlay onto a base video via FFmpeg's `drawtext` filter. Single-input — text and styling in options. Same `watermark_mode` (single/tiled), anchor + margin vocab as `text_watermark`. Re-encode required; audio stream-copy passthrough. `availability: planned` — WITHDRAWN 2026-09-15, operation AND `short_form`: a real 1080p source at the advertised PT5M was killed just past the worker's 600 s encode cap. Returns `feature_not_available` (422) at workflow-create. ⚠️ This entry previously read "until Lambda ships", which was wrong in a way that mattered: the worker SHIPPED and runs — it is the CEILING that cannot be served. Per ticket [`4NrRPCgh`](https://trello.com/c/4NrRPCgh) + ADR-0013.
         - split: Fan one input file into N outputs across GIF / PDF / audio / video MIME families. Single-input per-mime-group catalog (mirrors merge/convert): GIF uses `frame_range` (REQUIRED) + `output_format`; PDF uses `page_range` OR `page_groups` (mutually exclusive); audio + video use a `mode` discriminator (interval/count/cut_points) + numeric-seconds wire format + `precision` flag (fast/exact). 200-output hard cap per ADR-0009 §D5 with per-mode preflight math; output naming `output-001..output-200`. Long-form video routes to a separate `split-video-fargate` worker via `processing_class`. `availability: beta` for the `audio` and `video` mime_groups (workers live on staging — shape-stable + opt-in, MUST NOT 422); video activates BOTH classes (`video.processing_class.short_form: beta` AND `long_form: beta` — `split-video-fargate` deployed + wired on staging; it stays `beta` until a PRODUCTION `customer_path` run is recorded in `availability/prod-verification-log.yaml` per [`rcwvUKhI`](https://trello.com/c/rcwvUKhI)). The `image_gif` and `document_pdf` mime_groups stay `availability: planned` and dispatch returns `feature_not_available` (422) until their workers ship. Per ticket [`vKI0CFDu`](https://trello.com/c/vKI0CFDu) + ADR-0014.
         - 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).
 

package/operation-capabilities/operation-capabilities.json

@@ -860,5 +860,5 @@
       "isAnimated": "maybe"
     }
   },
-  "schema_version": "2.214.0"
+  "schema_version": "2.215.0"
 }

package/operations/schemas/audio_to_video.yaml

@@ -26,20 +26,21 @@ operation:
     A lower framerate plus still-image tuning keeps file size tiny
     when the overlay is a still image (the common case).
 
-    `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).
+    `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 Lambda platform maximum. ⚠️ The fixed cost is not a rounding
+    detail: dropping it moves the in-flight boundary by tens of seconds. The
+    figures are in the CHANGELOG entry for 2.203.0, derived and tested from the
+    divergence register (6gdvD3yZ). 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
+    What fails is an accepted workflow whose OUTPUT DURATION exceeds the derived ceiling (`evidence.derived.ceiling_s` in the register)
     ⚠️ ON THE INPUT THE RATE WAS MEASURED WITH — a real photographic 1080p STILL
-    plus looped real audio — the point at which 0.300 s/s plus the 7 s fixed cost
-    reaches the 600 s cap. ⛔ THE DRIVER IS THE STILL'S RESOLUTION, NOT THE
+    plus looped real audio — the point at which the measured rate plus the fixed
+    cost reaches the 600 s cap. ⛔ THE DRIVER IS THE STILL'S RESOLUTION, NOT THE
     DURATION ALONE: a 4K still is roughly 4x the rate (recorded as UNMEASURED),
     which would put the boundary near a quarter of that figure, and this schema
     places NO constraint on the overlay's resolution. Other still resolutions and

package/operations/schemas/video_text_watermark.yaml

@@ -28,7 +28,7 @@ operation:
 
     ⚠️ 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.
+    point: a real 1080p source at the sold ceiling, KILLED just past the 600 s cap 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
@@ -65,19 +65,18 @@ operation:
           # move DOWN, not up.
           #
           # Encode time is a LINE, slope AND intercept, and each ceiling is that
-          # line solved for the cap and FLOORED: `derivation` holds the inputs
-          # and a test recomputes the ceiling from them. ⛔ Dropping the
-          # intercept gives 276 s at 720p, and 2.167 × 276 + 3 = 601.1 s — past
-          # the cap the number exists to respect (the CHANGELOG 2.203.0 record
-          # made this correction once already). One constant generates both
-          # rows, ~2.35 s per megapixel-second on this worker; when the cap is
-          # derived from the runtime deadline (3JT9S3On) the rows are
-          # RECOMPUTED from `derivation`, not re-measured. An earlier
-          # extrapolation of 145 s at 1080p measured 124 s-before-the-intercept:
-          # 18% optimistic, the same direction as every estimate that day.
+          # line solved for the cap and FLOORED. The measured POINTS live in ONE
+          # place, this operation's `evidence` block in
+          # schemas/manifest-divergence-register.yaml (6gdvD3yZ). `derivation`
+          # below is the line those points give, and a test asserts the two
+          # agree (tests/test_evidence_figures_are_derived.py). Dropping the
+          # intercept over-sells 720p past the cap, which the CHANGELOG 2.203.0
+          # record corrected once already; the checker recomputes every ceiling
+          # from `derivation`. When the cap is derived from the runtime deadline
+          # (3JT9S3On) the rows are RECOMPUTED, not re-measured.
           #
-          # `gt_1080p` is NOT SERVED on short_form: the constant predicts ~31 s
-          # of 4K, an extrapolation 4x beyond anything measured, and neither
+          # `gt_1080p` is NOT SERVED on short_form: the constant's prediction
+          # for 4K is an extrapolation 4x beyond anything measured, and neither
           # lambdas nor contracts publishes it as a number. One real 4K cell
           # replaces it with a measured row.
           #
@@ -96,12 +95,12 @@ operation:
               basis: measured
               derivation: { slope_s_per_s: 2.167, intercept_s: 3.0, cap_s: 600 }
               constraints:
-                max_input_duration: "PT4M35S"     # 275 s = floor((600 - 3) / 2.167)
+                max_input_duration: "PT4M35S"     # floor((cap - intercept) / slope)
             p1080:
               basis: measured
               derivation: { slope_s_per_s: 4.867, intercept_s: -3.0, cap_s: 600 }
               constraints:
-                max_input_duration: "PT2M3S"      # 123 s = floor((600 + 3) / 4.867)
+                max_input_duration: "PT2M3S"      # floor((cap - intercept) / slope)
             gt_1080p:
               basis: not_served
             unknown:

package/operations/schemas/video_watermark.yaml

@@ -28,8 +28,8 @@ operation:
 
     ⚠️ 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
+    point: the same source plus a PNG overlay, KILLED just past the 600 s cap with no output, on
+    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

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@giveitsmaller/contracts",
-  "version": "0.79.0",
-  "description": "Generated contract types for GISL (Give It Smaller). Generated from compression_contracts spec v2.214.0.",
-  "gislContractsSpec": "v2.214.0",
+  "version": "0.80.0",
+  "description": "Generated contract types for GISL (Give It Smaller). Generated from compression_contracts spec v2.215.0.",
+  "gislContractsSpec": "v2.215.0",
   "license": "Apache-2.0",
   "homepage": "https://docs.giveitsmaller.com",
   "bugs": {
@@ -30,6 +30,7 @@
     },
     "./openapi/api.yaml": "./openapi/api.yaml",
     "./asyncapi/events.yaml": "./asyncapi/events.yaml",
+    "./resolution-bands.yaml": "./resolution-bands.yaml",
     "./availability/availability.json": "./availability/availability.json",
     "./accepted-options/accepted-options.json": "./accepted-options/accepted-options.json",
     "./accepted-options/image-output-routes.json": "./accepted-options/image-output-routes.json",
@@ -63,7 +64,8 @@
     "accepted-options/accepted-options.json",
     "accepted-options/image-output-routes.json",
     "operation-capabilities/operation-capabilities.json",
-    "code-builder/code-builder-metadata.json"
+    "code-builder/code-builder-metadata.json",
+    "resolution-bands.yaml"
   ],
   "scripts": {
     "clean": "node -e \"require('node:fs').rmSync('dist', {recursive: true, force: true})\"",

package/resolution-bands.yaml

@@ -0,0 +1,32 @@
+# Resolution bands — the ONE declaration of the band names and their bounds.
+#
+# Read by `processing_class.<class>.resolution_bands` in schemas/operations/*.yaml
+# (every band below, plus `unknown_band`, must be declared there), by
+# scripts/check-resolution-bands.py, and by consumers that pick a band for an
+# input. The OpenAPI `ResolutionBand` enum is these names plus `unknown_band`,
+# held equal by a test. Do not restate the bounds anywhere else.
+#
+# A band is chosen by FRAME PIXELS = width x height from the upload probe,
+# never by height alone: a portrait 1080x1920 clip is the same work as its
+# landscape twin. Measured reason (lambdas, 2026-09-15, GxQPL4IY): encode cost
+# is linear in megapixel-seconds — 2.351 s per Mpx·s at 720p, 2.347 at 1080p,
+# 0.2% apart — so pixel count is the axis the cost runs on.
+#
+# An input lands in the FIRST band whose `max_frame_pixels` it does not
+# exceed; the last band has no bound. ORDER IS LOAD-BEARING and the checker
+# enforces it: strictly ascending bounds, exactly one unbounded band, last.
+#
+# `unknown_band` applies when the probe has no width or no height. It is a
+# DECLARED band with its own ceilings in every class, never a fallback each
+# consumer implements (decision 343).
+
+schema_version: "1.0.0"
+
+bands:
+  - name: le_720p
+    max_frame_pixels: 921600    # 1280 x 720
+  - name: p1080
+    max_frame_pixels: 2073600   # 1920 x 1080
+  - name: gt_1080p
+
+unknown_band: unknown