@giveitsmaller/contracts 0.34.0 → 0.36.0

package/operations/schemas/compress.yaml

@@ -44,29 +44,33 @@ operation:
     # 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.
+    # RESIZE-INSIDE-OUTPUT ships STABLE (hub-directed fast-path, 2026-06-22;
+    # engine corrected per API worker-verification n4CmaDE8, 2026-06-23):
+    #   width / height / fit + max_output_pixels. The CONVERT worker is the image
+    #   resize engine for the WHOLE Output op (image_convert.rs, Lanczos, 1-16384,
+    #   16MP cap, svg-reject; live #257) — the compress optimiser has NO resize.
+    #   The API routes BOTH arms through convert (same_format = convert to the same
+    #   token; format_change = convert to the target), so these keys are declared
+    #   HERE (the facade entry) AND on convert.image (where the worker reads them +
+    #   the API re-validates the rewritten op). REPLACE transform, ONE output —
+    #   NOT thumbnail's derivative/preview semantics; thumbnail.yaml untouched.
     #
-    # 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
-      # Resize-inside-Output (planned) shares thumbnail-image's 16MP output-area
+      # Resize-inside-Output shares the convert resize engine's 16MP output-area
       # wall — the per-axis 16384 cap can't express it (FORMAT.md §max_output_pixels).
       max_output_pixels: 16000000
       options:
@@ -75,22 +79,46 @@ operation:
           min: 1
           max: 100
           default: 80
+          depends_on: { encoding_mode: quality }
           honored_on: [same_format]
-          description: "Compression quality (1 = smallest file, 100 = best quality)."
+          description: >-
+            Compression quality (1 = smallest file, 100 = best quality). Active in
+            `quality` mode (default); in `target_size` mode the encode-measure loop
+            owns quality, so this option is inactive.
+        encoding_mode:
+          type: enum
+          values: [quality, target_size]
+          default: quality
+          per_value_availability:
+            target_size: { availability: planned }
+          honored_on: [same_format]
+          description: >-
+            Compression mode (mirrors compress.video). `quality` = the `quality`
+            slider drives the encode (default, live). `target_size` = `planned` —
+            hit a byte budget via the worker's encode-measure-binary-search loop
+            (lambdas building; jpeg/webp/avif only). Optimiser (same_format) route.
+        target_size_bytes:
+          type: integer
+          min: 1024
+          availability: planned
+          depends_on: { encoding_mode: target_size }
+          honored_on: [same_format]
+          description: >-
+            Target output size in bytes (min 1024 = 1 KiB). `planned` — the image
+            encode-measure loop binary-searches quality to land at or under the
+            target; best-effort if the target is unreachable at min quality (the
+            result reports the chosen quality + whether the target was met).
+            Optimiser (same_format) route.
         metadata:
           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 +136,16 @@ operation:
         lossless:
           type: boolean
           default: false
-          availability: planned
+          depends_on: { encoding_mode: quality }
           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). Only in `quality` mode — incompatible with
+            `target_size` (the byte-budget loop is inherently lossy). Optimiser
+            (same_format) route only.
         width:
           type: integer
           min: 1
@@ -122,8 +154,9 @@ operation:
           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.
+            ONE transformed output) using the proven convert resize engine (Lanczos;
+            the API routes Output resize through the convert worker, BOTH routes —
+            the compress optimiser has no resize) — it is NOT the derivative `thumbnail` op.
             Optional; omit to keep the source dimensions.
         height:
           type: integer
@@ -138,9 +171,12 @@ operation:
           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.
+            Resize mode. `max` (default) = fit within bounds, preserving aspect ratio
+            and NEVER upscaling — it caps at the source dimensions. This IS the
+            "no-enlarge" behaviour (there is no separate `no_enlarge` flag — the
+            worker has no such key). `crop`/`scale` = exact dimensions (`scale`
+            deliberately enlarges past source). Applies only when width or height is
+            set, on whichever Output route runs.
 
     image_png:
       mimes:
@@ -158,16 +194,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
@@ -203,8 +235,9 @@ operation:
           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.
+            ONE transformed output) using the proven convert resize engine (Lanczos;
+            the API routes Output resize through the convert worker, BOTH routes —
+            the compress optimiser has no resize) — it is NOT the derivative `thumbnail` op.
             Optional; omit to keep the source dimensions.
         height:
           type: integer
@@ -219,9 +252,12 @@ operation:
           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.
+            Resize mode. `max` (default) = fit within bounds, preserving aspect ratio
+            and NEVER upscaling — it caps at the source dimensions. This IS the
+            "no-enlarge" behaviour (there is no separate `no_enlarge` flag — the
+            worker has no such key). `crop`/`scale` = exact dimensions (`scale`
+            deliberately enlarges past source). Applies only when width or height is
+            set, on whichever Output route runs.
 
     image_avif:
       availability: beta
@@ -243,22 +279,47 @@ operation:
           min: 1
           max: 100
           default: 80
+          depends_on: { encoding_mode: quality }
           honored_on: [same_format]
-          description: "Compression quality (1 = smallest file, 100 = best quality)."
+          description: >-
+            Compression quality (1 = smallest file, 100 = best quality). Active in
+            `quality` mode (default); in `target_size` mode the encode-measure loop
+            owns quality, so this option is inactive.
+        encoding_mode:
+          type: enum
+          values: [quality, target_size]
+          default: quality
+          per_value_availability:
+            target_size: { availability: planned }
+          honored_on: [same_format]
+          description: >-
+            Compression mode (mirrors compress.video). `quality` = the `quality`
+            slider drives the encode (default, live). `target_size` = `planned` —
+            hit a byte budget via the worker's encode-measure-binary-search loop
+            (lambdas building; jpeg/webp/avif only). AVIF encodes are slow, so the
+            loop caps iterations. Optimiser (same_format) route.
+        target_size_bytes:
+          type: integer
+          min: 1024
+          availability: planned
+          depends_on: { encoding_mode: target_size }
+          honored_on: [same_format]
+          description: >-
+            Target output size in bytes (min 1024 = 1 KiB). `planned` — the image
+            encode-measure loop binary-searches quality to land at or under the
+            target; best-effort if the target is unreachable at min quality (the
+            result reports the chosen quality + whether the target was met).
+            Optimiser (same_format) route.
         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
@@ -283,8 +344,9 @@ operation:
           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.
+            ONE transformed output) using the proven convert resize engine (Lanczos;
+            the API routes Output resize through the convert worker, BOTH routes —
+            the compress optimiser has no resize) — it is NOT the derivative `thumbnail` op.
             Optional; omit to keep the source dimensions.
         height:
           type: integer
@@ -299,9 +361,12 @@ operation:
           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.
+            Resize mode. `max` (default) = fit within bounds, preserving aspect ratio
+            and NEVER upscaling — it caps at the source dimensions. This IS the
+            "no-enlarge" behaviour (there is no separate `no_enlarge` flag — the
+            worker has no such key). `crop`/`scale` = exact dimensions (`scale`
+            deliberately enlarges past source). Applies only when width or height is
+            set, on whichever Output route runs.
 
     # 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
@@ -317,22 +382,46 @@ operation:
           min: 1
           max: 100
           default: 80
+          depends_on: { encoding_mode: quality }
           honored_on: [same_format]
-          description: "Compression quality (1 = smallest file, 100 = best quality)."
+          description: >-
+            Compression quality (1 = smallest file, 100 = best quality). Active in
+            `quality` mode (default); in `target_size` mode the encode-measure loop
+            owns quality, so this option is inactive.
+        encoding_mode:
+          type: enum
+          values: [quality, target_size]
+          default: quality
+          per_value_availability:
+            target_size: { availability: planned }
+          honored_on: [same_format]
+          description: >-
+            Compression mode (mirrors compress.video). `quality` = the `quality`
+            slider drives the encode (default, live). `target_size` = `planned` —
+            hit a byte budget via the worker's encode-measure-binary-search loop
+            (lambdas building; jpeg/webp/avif only). Optimiser (same_format) route.
+        target_size_bytes:
+          type: integer
+          min: 1024
+          availability: planned
+          depends_on: { encoding_mode: target_size }
+          honored_on: [same_format]
+          description: >-
+            Target output size in bytes (min 1024 = 1 KiB). `planned` — the image
+            encode-measure loop binary-searches quality to land at or under the
+            target; best-effort if the target is unreachable at min quality (the
+            result reports the chosen quality + whether the target was met).
+            Optimiser (same_format) route.
         metadata:
           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 +434,15 @@ operation:
         lossless:
           type: boolean
           default: false
-          availability: planned
+          depends_on: { encoding_mode: quality }
           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. Only in `quality` mode — incompatible with
+            `target_size` (the byte-budget loop is inherently lossy). Optimiser
+            (same_format) route only.
         width:
           type: integer
           min: 1
@@ -359,8 +451,9 @@ operation:
           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.
+            ONE transformed output) using the proven convert resize engine (Lanczos;
+            the API routes Output resize through the convert worker, BOTH routes —
+            the compress optimiser has no resize) — it is NOT the derivative `thumbnail` op.
             Optional; omit to keep the source dimensions.
         height:
           type: integer
@@ -375,9 +468,12 @@ operation:
           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.
+            Resize mode. `max` (default) = fit within bounds, preserving aspect ratio
+            and NEVER upscaling — it caps at the source dimensions. This IS the
+            "no-enlarge" behaviour (there is no separate `no_enlarge` flag — the
+            worker has no such key). `crop`/`scale` = exact dimensions (`scale`
+            deliberately enlarges past source). 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
@@ -395,15 +491,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 +527,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]
@@ -460,8 +550,9 @@ operation:
           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.
+            ONE transformed output) using the proven convert resize engine (Lanczos;
+            the API routes Output resize through the convert worker, BOTH routes —
+            the compress optimiser has no resize) — it is NOT the derivative `thumbnail` op.
             Optional; omit to keep the source dimensions.
         height:
           type: integer
@@ -476,9 +567,12 @@ operation:
           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.
+            Resize mode. `max` (default) = fit within bounds, preserving aspect ratio
+            and NEVER upscaling — it caps at the source dimensions. This IS the
+            "no-enlarge" behaviour (there is no separate `no_enlarge` flag — the
+            worker has no such key). `crop`/`scale` = exact dimensions (`scale`
+            deliberately enlarges past source). Applies only when width or height is
+            set, on whichever Output route runs.
 
     audio:
       mimes:
@@ -542,18 +636,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 +844,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

@@ -8,12 +8,16 @@ operation:
 
   mime_groups:
     image:
+      # svg is split into convert.image_svg (below): it rasterises to raster
+      # formats but CANNOT be raster-resized (worker rejects svg resize), so it
+      # must NOT sit in a group that declares width/height/fit — else the raw
+      # schema / availability / accepted-options advertise svg resize. Mirrors
+      # compress.image_svg.
       mimes:
         - image/jpeg
         - image/png
         - image/gif
         - image/webp
-        - image/svg+xml
         - image/tiff
         - image/bmp
         - image/vnd.microsoft.icon
@@ -33,6 +37,20 @@ operation:
       # 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.
+      #
+      # RESIZE: convert is the image resize ENGINE for the WHOLE Output op (both
+      # routes) — the compress optimiser has NO resize code (it never reads
+      # width/height/fit). The API carries width/height/fit onto the convert op
+      # for BOTH arms: format_change = convert to the requested format; same_format
+      # = convert to the SAME format token (the optimiser leg delegates resize to
+      # the transcoder — see compress.image resize comments). So width/height/fit
+      # are declared HERE (the worker reads them: image_convert.rs ->
+      # shared::image::resize_request_from_job, full validation + 16MP cap + svg
+      # REJECT + animation preserve; live #257). svg INPUT cannot be raster-resized
+      # (worker rejects as invalid_options) — the output-keyed projection lists
+      # resize on every format_change target, so it is INPUT-GATED: consumers
+      # cross-ref same_format[input] (svg has no resize) before offering it.
+      max_output_pixels: 16000000          # worker MAX_OUTPUT_PIXELS; parity with compress.image
       options:
         output_format:
           type: enum
@@ -49,9 +67,78 @@ 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 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).
+        width:
+          type: integer
+          min: 1
+          max: 16384
+          honored_on: [format_change]
+          description: >-
+            Resize-inside-Output: target width in pixels (1-16384; width*height <=
+            max_output_pixels). The convert worker resizes (Lanczos) before encode;
+            single transformed output. NOT honored for SVG input (the worker
+            rejects svg resize). Input-gated — see the resize comment above.
+        height:
+          type: integer
+          min: 1
+          max: 16384
+          honored_on: [format_change]
+          description: "Resize-inside-Output: target height in pixels (1-16384; width*height <= max_output_pixels). Not honored for SVG input. See `width`."
+        fit:
+          type: enum
+          values: [max, crop, scale]
+          default: max
+          depends_on: { width: set, height: set, logic: or }
+          honored_on: [format_change]
+          description: >-
+            Resize mode. `max` (default) = fit within bounds, preserving aspect ratio
+            and NEVER upscaling — it caps at the source dimensions. This IS the
+            "no-enlarge" behaviour (there is no separate `no_enlarge` flag — the
+            worker has no such key). `crop`/`scale` = exact dimensions (`scale`
+            deliberately enlarges past source). Applies only when width or height is set.
+
+    # svg is VECTOR: it converts (rasterises) to a raster format, but CANNOT be
+    # raster-resized — the convert worker rejects svg resize. Split out of
+    # convert.image so width/height/fit are STRUCTURALLY absent for svg input:
+    # the API validates an svg op against THIS group + rejects resize at create
+    # (not prose), and raw schema / availability / accepted-options never
+    # advertise svg resize. Mirrors compress.image_svg. NO resize, NO area cap.
+    image_svg:
+      mimes:
+        - image/svg+xml
+      options:
+        output_format:
+          type: enum
+          values: [jpeg, png, webp, avif, gif, tiff]
+          required: true
+          description: "Target raster format (SVG is rasterised, then encoded)."
+        quality:
+          type: integer
+          min: 1
+          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 }
           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`) for transparent SVG
+            rasterised to JPEG (alpha-flatten). HEX ONLY — non-hex is rejected as
+            `invalid_options` (see convert.image.background).
 
     video:
       mimes: