@giveitsmaller/contracts 0.34.0 → 0.35.0

package/operation-capabilities/operation-capabilities.json

@@ -140,6 +140,33 @@
             ]
           },
           "wire_code": "feature_not_available"
+        },
+        {
+          "availability": "stable",
+          "constraint_id": "compress.video.trim.longform",
+          "eval_scope": "api",
+          "message": "Trimming is not yet available for long-form video. Trim a short-form clip, or chain a split op.",
+          "when": {
+            "all": [
+              {
+                "equals": "long_form",
+                "field": "processing_class"
+              },
+              {
+                "any": [
+                  {
+                    "field": "compress.trim_start",
+                    "isSet": true
+                  },
+                  {
+                    "field": "compress.trim_end",
+                    "isSet": true
+                  }
+                ]
+              }
+            ]
+          },
+          "wire_code": "feature_not_available"
         }
       ],
       "input": {
@@ -471,5 +498,5 @@
       "isAnimated": "maybe"
     }
   },
-  "schema_version": "2.97.0"
+  "schema_version": "2.102.0"
 }

package/operations/schemas/compress.yaml

@@ -52,17 +52,18 @@ operation:
     #   thumbnail.yaml stays the preview op untouched. Flat keys keyed to the
     #   Output (compress) op, matching thumbnail.yaml's resize shape.
     #
-    # The remaining PHASE 1 controls land availability:planned (ANTI-REGRESSION:
-    # no stable-flip until the worker honours it + API proves representability —
-    # plan §2.5; FE-hidden / API-422 until then). They are route-CONDITIONAL,
-    # which is why they ride the route-aware honored_on model:
-    #   lossless (jpeg/webp)  -> the worker `lossless` bool the API has never
-    #     emitted (product-parked); planned, optimiser (same_format) route only.
-    #   metadata: keep        -> un-hardcode keep_metadata=false; planned value
-    #     on the existing `metadata` enum.
-    #   lossy (png)           -> palette quantization (pngquant/imagequant-class);
-    #     planned + licensing-gated by the lambdas spike — do NOT stable-flip
-    #     until that confirms a permissive path.
+    # STABLE on the optimiser (same_format) route (all worker-proven 2026-06-23):
+    #   lossless (jpeg/webp) — worker honours the `lossless` bool, API emits it.
+    #   metadata: keep — preserve EXIF/ICC/XMP (libcaesium; lambdas PR #260). keep
+    #     is honored on libcaesium (jpeg/png/webp/gif/tiff) ONLY; AVIF (ravif) +
+    #     SVG (SVGO) re-encode from pixels so `keep` is NOT in their enum (worker
+    #     would reject it). metadata `all` (strip) is the universal default.
+    #
+    # Still availability:planned (ANTI-REGRESSION — no stable-flip until worker-
+    # proven; plan §2.5):
+    #   lossy (png) -> palette quantization (pngquant/imagequant-class); planned +
+    #     licensing-gated by the lambdas spike — do NOT stable-flip until that
+    #     confirms a permissive path.
     image_jpeg:
       mimes:
         - image/jpeg
@@ -81,16 +82,12 @@ operation:
           type: enum
           values: [all, keep]
           default: all
-          per_value_availability:
-            keep: { availability: planned }
           honored_on: [same_format]
           description: >-
-            Metadata handling. `all` = strip all EXIF/IPTC/XMP (default, the only
-            live behaviour — the compress worker hardcodes keep_metadata=false).
-            `keep` = preserve metadata — `planned` (the worker cannot preserve it
-            yet; un-hardcoding keep_metadata is the Phase 1 keep/strip toggle).
-            Optimiser (same_format) route — the format-change transcoder has no
-            metadata-preservation control today.
+            Metadata handling (optimiser/same_format route). `all` = strip all
+            EXIF/IPTC/XMP (default). `keep` = preserve EXIF/ICC/XMP — STABLE
+            (worker-proven, libcaesium; lambdas PR #260, staging round-trip +
+            unit test). Any other value is rejected as invalid_options.
         progressive:
           type: boolean
           default: true
@@ -108,12 +105,13 @@ operation:
         lossless:
           type: boolean
           default: false
-          availability: planned
           honored_on: [same_format]
           description: >-
-            Encode losslessly (JPEG optimiser path). `planned` — the worker carries
-            a `lossless` bool the API has never emitted (product-parked: a lossless
-            output can be LARGER than lossy). Optimiser (same_format) route only.
+            Lossless JPEG re-optimisation (optimiser path): optimises the Huffman
+            tables WITHOUT re-encoding pixels — bit-preserving on the pixel data,
+            no quality loss (it cannot recover detail a lossy JPEG already lost).
+            STABLE — the compress-image worker honours the `lossless` bool
+            (un-parked 2026-06-23). Optimiser (same_format) route only.
         width:
           type: integer
           min: 1
@@ -158,16 +156,12 @@ operation:
           type: enum
           values: [all, keep]
           default: all
-          per_value_availability:
-            keep: { availability: planned }
           honored_on: [same_format]
           description: >-
-            Metadata handling. `all` = strip all EXIF/IPTC/XMP (default, the only
-            live behaviour — the compress worker hardcodes keep_metadata=false).
-            `keep` = preserve metadata — `planned` (the worker cannot preserve it
-            yet; un-hardcoding keep_metadata is the Phase 1 keep/strip toggle).
-            Optimiser (same_format) route — the format-change transcoder has no
-            metadata-preservation control today.
+            Metadata handling (optimiser/same_format route). `all` = strip all
+            EXIF/IPTC/XMP (default). `keep` = preserve EXIF/ICC/XMP — STABLE
+            (worker-proven, libcaesium; lambdas PR #260, staging round-trip +
+            unit test). Any other value is rejected as invalid_options.
         optimization_level:
           type: integer
           min: 0
@@ -247,18 +241,14 @@ operation:
           description: "Compression quality (1 = smallest file, 100 = best quality)."
         metadata:
           type: enum
-          values: [all, keep]
+          values: [all]
           default: all
-          per_value_availability:
-            keep: { availability: planned }
           honored_on: [same_format]
           description: >-
-            Metadata handling. `all` = strip all EXIF/IPTC/XMP (default, the only
-            live behaviour — the compress worker hardcodes keep_metadata=false).
-            `keep` = preserve metadata — `planned` (the worker cannot preserve it
-            yet; un-hardcoding keep_metadata is the Phase 1 keep/strip toggle).
-            Optimiser (same_format) route — the format-change transcoder has no
-            metadata-preservation control today.
+            Metadata handling. `all` = strip all EXIF/IPTC/XMP (the only supported
+            value). `keep` is NOT offered for AVIF — ravif re-encodes from pixels
+            and cannot preserve metadata (the worker rejects `keep` as
+            invalid_options).
         avif_speed:
           type: integer
           min: 1
@@ -323,16 +313,12 @@ operation:
           type: enum
           values: [all, keep]
           default: all
-          per_value_availability:
-            keep: { availability: planned }
           honored_on: [same_format]
           description: >-
-            Metadata handling. `all` = strip all EXIF/IPTC/XMP (default, the only
-            live behaviour — the compress worker hardcodes keep_metadata=false).
-            `keep` = preserve metadata — `planned` (the worker cannot preserve it
-            yet; un-hardcoding keep_metadata is the Phase 1 keep/strip toggle).
-            Optimiser (same_format) route — the format-change transcoder has no
-            metadata-preservation control today.
+            Metadata handling (optimiser/same_format route). `all` = strip all
+            EXIF/IPTC/XMP (default). `keep` = preserve EXIF/ICC/XMP — STABLE
+            (worker-proven, libcaesium; lambdas PR #260, staging round-trip +
+            unit test). Any other value is rejected as invalid_options.
         output_format:
           type: enum
           values: [original, webp]
@@ -345,12 +331,12 @@ operation:
         lossless:
           type: boolean
           default: false
-          availability: planned
           honored_on: [same_format]
           description: >-
-            Encode WebP losslessly (optimiser path). `planned` — the worker carries a
-            `lossless` bool the API has never emitted (product-parked: lossless can be
-            LARGER). Optimiser (same_format) route only.
+            Encode WebP losslessly (optimiser path): a genuine lossless WebP encode.
+            STABLE — the compress-image worker honours the `lossless` bool (un-parked
+            2026-06-23). Note a lossless encode can be LARGER than a lossy one at the
+            same visual quality. Optimiser (same_format) route only.
         width:
           type: integer
           min: 1
@@ -395,15 +381,13 @@ operation:
           description: "Compression quality (1 = smallest file, 100 = best quality)."
         metadata:
           type: enum
-          values: [all, keep]
+          values: [all]
           default: all
-          per_value_availability:
-            keep: { availability: planned }
           honored_on: [same_format]
           description: >-
-            Metadata handling. `all` = strip all metadata (default, live). `keep` =
-            preserve metadata — `planned` (worker cannot preserve yet). Optimiser
-            (same_format) route.
+            Metadata handling. `all` = strip all metadata (the only supported value).
+            `keep` is NOT offered for SVG — SVGO optimises the markup and cannot
+            preserve a metadata block (the worker rejects `keep` as invalid_options).
         output_format:
           type: enum
           values: [original, webp]
@@ -433,16 +417,12 @@ operation:
           type: enum
           values: [all, keep]
           default: all
-          per_value_availability:
-            keep: { availability: planned }
           honored_on: [same_format]
           description: >-
-            Metadata handling. `all` = strip all EXIF/IPTC/XMP (default, the only
-            live behaviour — the compress worker hardcodes keep_metadata=false).
-            `keep` = preserve metadata — `planned` (the worker cannot preserve it
-            yet; un-hardcoding keep_metadata is the Phase 1 keep/strip toggle).
-            Optimiser (same_format) route — the format-change transcoder has no
-            metadata-preservation control today.
+            Metadata handling (optimiser/same_format route). `all` = strip all
+            EXIF/IPTC/XMP (default). `keep` = preserve EXIF/ICC/XMP — STABLE
+            (worker-proven, libcaesium; lambdas PR #260, staging round-trip +
+            unit test). Any other value is rejected as invalid_options.
         output_format:
           type: enum
           values: [original, webp]
@@ -542,18 +522,19 @@ operation:
         trim_start:
           type: float
           min: 0
-          availability: planned
           description: >
-            Trim from beginning in seconds. Gated `planned` (qZI5EK9j):
-            no compression worker implements per-clip trim yet, so the
-            server returns `feature_not_available` rather than accepting
-            and silently ignoring it. Flips to `stable` when a worker
-            lands; to trim today, chain a `split` op.
+            Trim from beginning in seconds (absent = from the start). STABLE
+            (qZI5EK9j) — the compress-audio worker cuts the clip before encoding
+            (input-side ffmpeg `-ss`/`-t`; lambdas PR #259), SAME FROM-END
+            semantic as compress.video / convert / merge: the kept clip is
+            [`trim_start`, input_duration − `trim_end`].
         trim_end:
           type: float
           min: 0
-          availability: planned
-          description: "Trim from end in seconds. Gated `planned` (qZI5EK9j) — see `trim_start`."
+          description: >
+            Trim from end in seconds (absent = to the end). Removes this many
+            seconds from the end; with `trim_start` the kept clip is
+            [`trim_start`, input_duration − `trim_end`]. STABLE — see `trim_start`.
 
     video:
       mimes:
@@ -749,18 +730,22 @@ operation:
         trim_start:
           type: float
           min: 0
-          availability: planned
           description: >
-            Trim from beginning in seconds. Gated `planned` (qZI5EK9j):
-            no compression worker implements per-clip trim yet, so the
-            server returns `feature_not_available` rather than accepting
-            and silently ignoring it. Flips to `stable` when a worker
-            lands; to trim today, chain a `split` op.
+            Trim from beginning in seconds (absent = from the start). STABLE
+            (qZI5EK9j) — the compress-video worker cuts the clip before encoding
+            (input-side ffmpeg `-ss`/`-t`; lambdas PR #258), SAME FROM-END
+            semantic as convert/merge: the kept clip is [`trim_start`,
+            input_duration − `trim_end`]. SHORT-FORM only — for long-form video
+            the server returns `feature_not_available` (trim a short clip, or
+            chain a `split`); see the compress.video.trim.longform constraint.
         trim_end:
           type: float
           min: 0
-          availability: planned
-          description: "Trim from end in seconds. Gated `planned` (qZI5EK9j) — see `trim_start`."
+          description: >
+            Trim from end in seconds (absent = to the end). Removes this many
+            seconds from the end; with `trim_start` the kept clip is
+            [`trim_start`, input_duration − `trim_end`]. STABLE — see
+            `trim_start` (short-form only; long-form → `feature_not_available`).
 
     document_pdf:
       mimes:

package/operations/schemas/convert.yaml

@@ -49,9 +49,17 @@ operation:
           description: "Output quality for lossy formats"
         background:
           type: string
+          pattern: "^#[0-9a-fA-F]{6}$"
           depends_on: { output_format: jpeg }
           honored_on: [format_change]
-          description: "Background colour (hex, e.g. '#ffffff') for transparent images converted to JPEG (the format-change→JPEG alpha-flatten — Output's transparency fill control)."
+          description: >-
+            Background colour as a 6-digit hex (`#RRGGBB`, e.g. `#ffffff`) for
+            transparent images converted to JPEG (the format-change→JPEG
+            alpha-flatten — Output's transparency fill control). HEX ONLY: the
+            worker honours only `#RRGGBB` and silently drops a CSS named colour
+            (e.g. `magenta`) to the white default, so the `pattern` rejects a
+            non-hex value as `invalid_options` rather than advertising an inert
+            free-form string (e2e staging-verified 2026-06-22).
 
     video:
       mimes:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@giveitsmaller/contracts",
-  "version": "0.34.0",
+  "version": "0.35.0",
   "description": "Generated contract types for GISL (Give It Smaller)",
   "license": "MIT",
   "type": "module",