@giveitsmaller/contracts 0.33.0 → 0.35.0

package/operations/schemas/compress.yaml

@@ -33,28 +33,66 @@ operation:
     # dangling coming-soon values are dishonest at source; every other format
     # change is the convert operation's job (all stable). Re-add a target here
     # only when its compress+format canonicalization actually ships.
+    #
+    # ---- ROUTE-AWARE "OUTPUT" model (image-options Phase 0, tewB37Jg) ----
+    # The user-facing "Output" operation IS this compress op + output_format:
+    # the API routes by comparing the authored/resolved output_format to the
+    # input format — same_format (output_format == input, or `original`) runs
+    # the libcaesium OPTIMISER; format_change runs the convert TRANSCODER (the
+    # VcPeRWdD facade). Each option carries `honored_on: [<route>...]` declaring
+    # which route's worker reads it (absent ≡ all routes its depends_on admits;
+    # see FORMAT.md §"Route-aware Output model"). The derived per-(media, route,
+    # output_format) projection is accepted-options/image-output-routes.json.
+    #
+    # RESIZE-INSIDE-OUTPUT ships STABLE (hub-directed fast-path, 2026-06-22):
+    #   width / height / fit + max_output_pixels — backed by the PROVEN image
+    #   resize engine (thumbnail-images Lanczos, 1-16384, 16MP cap; live), routed
+    #   onto the Output path. Resize is a REPLACE transform inside Output (ONE
+    #   transformed output) — NOT thumbnail's derivative/preview semantics;
+    #   thumbnail.yaml stays the preview op untouched. Flat keys keyed to the
+    #   Output (compress) op, matching thumbnail.yaml's resize shape.
+    #
+    # 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
+      # Resize-inside-Output (planned) shares thumbnail-image's 16MP output-area
+      # wall — the per-axis 16384 cap can't express it (FORMAT.md §max_output_pixels).
+      max_output_pixels: 16000000
       options:
         quality:
           type: integer
           min: 1
           max: 100
           default: 80
+          honored_on: [same_format]
           description: "Compression quality (1 = smallest file, 100 = best quality)."
         metadata:
           type: enum
-          values: [all]
+          values: [all, keep]
           default: all
+          honored_on: [same_format]
           description: >-
-            Metadata handling. `all` = strip all EXIF/IPTC/XMP — the only supported
-            behaviour (the compress worker always strips; preservation is not
-            currently available).
+            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
-          description: "Enable progressive JPEG rendering (a low-quality preview renders first, then refines). JPEG only."
+          honored_on: [same_format]
+          description: "Enable progressive JPEG rendering (a low-quality preview renders first, then refines). JPEG only — the optimiser (same_format) route."
         output_format:
           type: enum
           values: [original, webp]
@@ -64,31 +102,73 @@ operation:
             WebP — the one live compress+format target (proven on staging). Other format
             changes (jpeg/png/avif/gif/tiff) are the convert operation's job, not compress.
             See FORMAT.md.
+        lossless:
+          type: boolean
+          default: false
+          honored_on: [same_format]
+          description: >-
+            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
+          max: 16384
+          honored_on: [same_format, format_change]
+          description: >-
+            Resize-inside-Output: target width in pixels (1-16384; width*height <=
+            max_output_pixels). Resize the image as part of Output (replace semantics,
+            ONE transformed output) using the proven image resize engine (Lanczos,
+            shared with thumbnail-images) — it is NOT the derivative `thumbnail` op.
+            Optional; omit to keep the source dimensions.
+        height:
+          type: integer
+          min: 1
+          max: 16384
+          honored_on: [same_format, format_change]
+          description: "Resize-inside-Output: target height in pixels (1-16384; width*height <= max_output_pixels). Resize replaces the image (one output). Optional — see `width`."
+        fit:
+          type: enum
+          values: [max, crop, scale]
+          default: max
+          depends_on: { width: set, height: set, logic: or }
+          honored_on: [same_format, format_change]
+          description: >-
+            Resize mode. max = fit within bounds (preserves aspect ratio, no crop),
+            crop/scale = exact dimensions. Applies only when width or height is set,
+            on whichever Output route runs.
 
     image_png:
       mimes:
         - image/png
+      max_output_pixels: 16000000
       options:
         quality:
           type: integer
           min: 1
           max: 100
           default: 80
+          honored_on: [same_format]
           description: "Compression quality (1 = smallest file, 100 = best quality)."
         metadata:
           type: enum
-          values: [all]
+          values: [all, keep]
           default: all
+          honored_on: [same_format]
           description: >-
-            Metadata handling. `all` = strip all EXIF/IPTC/XMP — the only supported
-            behaviour (the compress worker always strips; preservation is not
-            currently available).
+            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
           max: 6
           default: 3
-          description: "PNG optimization effort (0-6, oxipng). Higher = smaller file, slower encode. Default 3."
+          honored_on: [same_format]
+          description: "PNG optimization effort (0-6, oxipng). Higher = smaller file, slower encode. Default 3. Optimiser (same_format) route."
         output_format:
           type: enum
           values: [original, webp]
@@ -98,6 +178,44 @@ operation:
             WebP — the one live compress+format target (proven on staging). Other format
             changes (jpeg/png/avif/gif/tiff) are the convert operation's job, not compress.
             See FORMAT.md.
+        lossy:
+          type: boolean
+          default: false
+          availability: planned
+          honored_on: [same_format]
+          description: >-
+            Lossy PNG palette quantization (pngquant/imagequant-class) — a large
+            saving for flat-colour PNGs. `planned` AND LICENSING-GATED: do not
+            stable-flip until the lambdas licensing spike confirms a permissive
+            quantizer path (libimagequant/pngquant is GPL-or-commercial). Optimiser
+            (same_format) route only.
+        width:
+          type: integer
+          min: 1
+          max: 16384
+          honored_on: [same_format, format_change]
+          description: >-
+            Resize-inside-Output: target width in pixels (1-16384; width*height <=
+            max_output_pixels). Resize the image as part of Output (replace semantics,
+            ONE transformed output) using the proven image resize engine (Lanczos,
+            shared with thumbnail-images) — it is NOT the derivative `thumbnail` op.
+            Optional; omit to keep the source dimensions.
+        height:
+          type: integer
+          min: 1
+          max: 16384
+          honored_on: [same_format, format_change]
+          description: "Resize-inside-Output: target height in pixels (1-16384; width*height <= max_output_pixels). Resize replaces the image (one output). Optional — see `width`."
+        fit:
+          type: enum
+          values: [max, crop, scale]
+          default: max
+          depends_on: { width: set, height: set, logic: or }
+          honored_on: [same_format, format_change]
+          description: >-
+            Resize mode. max = fit within bounds (preserves aspect ratio, no crop),
+            crop/scale = exact dimensions. Applies only when width or height is set,
+            on whichever Output route runs.
 
     image_avif:
       availability: beta
@@ -112,27 +230,32 @@ operation:
       # contract vocab today; tracked for the image-size-cap mechanism (F3).
       mimes:
         - image/avif
+      max_output_pixels: 16000000
       options:
         quality:
           type: integer
           min: 1
           max: 100
           default: 80
+          honored_on: [same_format]
           description: "Compression quality (1 = smallest file, 100 = best quality)."
         metadata:
           type: enum
           values: [all]
           default: all
+          honored_on: [same_format]
           description: >-
-            Metadata handling. `all` = strip all EXIF/IPTC/XMP — the only supported
-            behaviour (the compress worker always strips; preservation is not
-            currently available).
+            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
           max: 10
           default: 4
-          description: "AVIF encode speed (1-10, ravif). Lower = smaller file, slower encode; higher = faster, larger. Default 4."
+          honored_on: [same_format]
+          description: "AVIF encode speed (1-10, ravif). Lower = smaller file, slower encode; higher = faster, larger. Default 4. Optimiser (same_format) route."
         output_format:
           type: enum
           values: [original, webp]
@@ -142,30 +265,164 @@ operation:
             WebP — the one live compress+format target (proven on staging). Other format
             changes (jpeg/png/avif/gif/tiff) are the convert operation's job, not compress.
             See FORMAT.md.
+        width:
+          type: integer
+          min: 1
+          max: 16384
+          honored_on: [same_format, format_change]
+          description: >-
+            Resize-inside-Output: target width in pixels (1-16384; width*height <=
+            max_output_pixels). Resize the image as part of Output (replace semantics,
+            ONE transformed output) using the proven image resize engine (Lanczos,
+            shared with thumbnail-images) — it is NOT the derivative `thumbnail` op.
+            Optional; omit to keep the source dimensions.
+        height:
+          type: integer
+          min: 1
+          max: 16384
+          honored_on: [same_format, format_change]
+          description: "Resize-inside-Output: target height in pixels (1-16384; width*height <= max_output_pixels). Resize replaces the image (one output). Optional — see `width`."
+        fit:
+          type: enum
+          values: [max, crop, scale]
+          default: max
+          depends_on: { width: set, height: set, logic: or }
+          honored_on: [same_format, format_change]
+          description: >-
+            Resize mode. max = fit within bounds (preserves aspect ratio, no crop),
+            crop/scale = exact dimensions. Applies only when width or height is set,
+            on whichever Output route runs.
 
-    image:
+    # webp split out of the former bundled image group: it is the one input that
+    # carries BOTH Resize (raster, proven in thumbnail-images) AND the optimiser
+    # `lossless` knob. gif/tiff (below) resize but have no lossless; svg is vector
+    # (no raster resize, no lossless) — see image_svg.
+    image_webp:
       mimes:
         - image/webp
-        - image/gif
+      max_output_pixels: 16000000
+      options:
+        quality:
+          type: integer
+          min: 1
+          max: 100
+          default: 80
+          honored_on: [same_format]
+          description: "Compression quality (1 = smallest file, 100 = best quality)."
+        metadata:
+          type: enum
+          values: [all, keep]
+          default: all
+          honored_on: [same_format]
+          description: >-
+            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]
+          default: original
+          description: >-
+            Output format. original = keep input format (default); webp = recompress to
+            WebP — the one live compress+format target (proven on staging). Other format
+            changes (jpeg/png/avif/gif/tiff) are the convert operation's job, not compress.
+            See FORMAT.md.
+        lossless:
+          type: boolean
+          default: false
+          honored_on: [same_format]
+          description: >-
+            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
+          max: 16384
+          honored_on: [same_format, format_change]
+          description: >-
+            Resize-inside-Output: target width in pixels (1-16384; width*height <=
+            max_output_pixels). Resize the image as part of Output (replace semantics,
+            ONE transformed output) using the proven image resize engine (Lanczos,
+            shared with thumbnail-images) — it is NOT the derivative `thumbnail` op.
+            Optional; omit to keep the source dimensions.
+        height:
+          type: integer
+          min: 1
+          max: 16384
+          honored_on: [same_format, format_change]
+          description: "Resize-inside-Output: target height in pixels (1-16384; width*height <= max_output_pixels). Resize replaces the image (one output). Optional — see `width`."
+        fit:
+          type: enum
+          values: [max, crop, scale]
+          default: max
+          depends_on: { width: set, height: set, logic: or }
+          honored_on: [same_format, format_change]
+          description: >-
+            Resize mode. max = fit within bounds (preserves aspect ratio, no crop),
+            crop/scale = exact dimensions. Applies only when width or height is set,
+            on whichever Output route runs.
+
+    # svg is VECTOR: no raster resize (thumbnail-images does not list svg), and the
+    # optimiser `lossless` knob does not apply. SVG compression is SVGO; only
+    # quality/metadata/output_format carry. NO Resize / lossless / area cap here.
+    image_svg:
+      mimes:
         - image/svg+xml
+      options:
+        quality:
+          type: integer
+          min: 1
+          max: 100
+          default: 80
+          honored_on: [same_format]
+          description: "Compression quality (1 = smallest file, 100 = best quality)."
+        metadata:
+          type: enum
+          values: [all]
+          default: all
+          honored_on: [same_format]
+          description: >-
+            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]
+          default: original
+          description: >-
+            Output format. original = keep input format (default); webp = recompress to
+            WebP. Other format changes are the convert operation's job. See FORMAT.md.
+
+    # gif/tiff: raster Resize is engine-proven (both are in thumbnail-images), but
+    # the optimiser `lossless` knob is WebP-only — not advertised here.
+    image:
+      mimes:
+        - image/gif
         - image/tiff
+      max_output_pixels: 16000000
       options:
         quality:
           type: integer
           min: 1
           max: 100
           default: 80
+          honored_on: [same_format]
           description: >-
             Compression quality (1 = smallest file, 100 = best quality). For animated
             GIF the worker honours this but real-world size reduction is typically small.
         metadata:
           type: enum
-          values: [all]
+          values: [all, keep]
           default: all
+          honored_on: [same_format]
           description: >-
-            Metadata handling. `all` = strip all EXIF/IPTC/XMP — the only supported
-            behaviour (the compress worker always strips; preservation is not
-            currently available).
+            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]
@@ -175,6 +432,33 @@ operation:
             WebP — the one live compress+format target (proven on staging). Other format
             changes (jpeg/png/avif/gif/tiff) are the convert operation's job, not compress.
             See FORMAT.md.
+        width:
+          type: integer
+          min: 1
+          max: 16384
+          honored_on: [same_format, format_change]
+          description: >-
+            Resize-inside-Output: target width in pixels (1-16384; width*height <=
+            max_output_pixels). Resize the image as part of Output (replace semantics,
+            ONE transformed output) using the proven image resize engine (Lanczos,
+            shared with thumbnail-images) — it is NOT the derivative `thumbnail` op.
+            Optional; omit to keep the source dimensions.
+        height:
+          type: integer
+          min: 1
+          max: 16384
+          honored_on: [same_format, format_change]
+          description: "Resize-inside-Output: target height in pixels (1-16384; width*height <= max_output_pixels). Resize replaces the image (one output). Optional — see `width`."
+        fit:
+          type: enum
+          values: [max, crop, scale]
+          default: max
+          depends_on: { width: set, height: set, logic: or }
+          honored_on: [same_format, format_change]
+          description: >-
+            Resize mode. max = fit within bounds (preserves aspect ratio, no crop),
+            crop/scale = exact dimensions. Applies only when width or height is set,
+            on whichever Output route runs.
 
     audio:
       mimes:
@@ -238,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:
@@ -445,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

@@ -26,6 +26,13 @@ operation:
         # (avif is also a valid OUTPUT via output_format — ravif encode.)
         image/avif: { availability: beta }
         image/heic: { availability: beta }
+      # convert.image is the TRANSCODER leg of the route-aware image "Output"
+      # model (FORMAT.md §"Route-aware Output model"): a format_change Output
+      # route (output_format != input) runs here. Its options carry
+      # `honored_on: [format_change]` so the merged per-(media, route,
+      # output_format) projection (accepted-options/image-output-routes.json)
+      # attributes them to the transcoder path — `background` is the canonical
+      # transparency→JPEG fill on format-change-to-jpeg, already live + stable.
       options:
         output_format:
           type: enum
@@ -38,11 +45,21 @@ operation:
           max: 100
           default: 85
           depends_on: { output_format: [jpeg, webp, avif] }
+          honored_on: [format_change]
           description: "Output quality for lossy formats"
         background:
           type: string
+          pattern: "^#[0-9a-fA-F]{6}$"
           depends_on: { output_format: jpeg }
-          description: "Background colour (hex, e.g. '#ffffff') for transparent images converted to JPEG"
+          honored_on: [format_change]
+          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.33.0",
+  "version": "0.35.0",
   "description": "Generated contract types for GISL (Give It Smaller)",
   "license": "MIT",
   "type": "module",
@@ -27,6 +27,7 @@
     "./asyncapi/events.yaml": "./asyncapi/events.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",
     "./operation-capabilities/operation-capabilities.json": "./operation-capabilities/operation-capabilities.json",
     "./operations/schemas/archive.yaml": "./operations/schemas/archive.yaml",
     "./operations/schemas/audio_overlay.yaml": "./operations/schemas/audio_overlay.yaml",
@@ -52,6 +53,7 @@
     "operations/schemas/",
     "availability/availability.json",
     "accepted-options/accepted-options.json",
+    "accepted-options/image-output-routes.json",
     "operation-capabilities/operation-capabilities.json"
   ],
   "scripts": {