@giveitsmaller/contracts 0.35.0 → 0.37.0

package/operations/schemas/compress.yaml

@@ -25,14 +25,27 @@ operation:
     # 2026-06-20, lossless parked). width/height/fit/auto_orient stay removed
     # (EsD1hs5u — worker recompresses only; resize -> thumbnail, format -> convert).
     #
-    # output_format (replicated identically per group): only the LIVE targets
-    # are advertised — `original` (no-op, default) and `webp` (the one proven
+    # output_format (replicated identically per group): the LIVE concrete
+    # targets are `original` (no-op, default) and `webp` (the one proven
     # compress+format pass: a single API-canonicalized convert-with-size-cap;
-    # the compress worker itself never reads output_format). The planned
-    # facade targets (auto/smallest/jpeg/png/avif) were PRUNED 2026-06-21 —
-    # 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.
+    # the compress worker itself never reads output_format). The concrete
+    # facade targets jpeg/png/avif stay PRUNED (pruned 2026-06-21) — a dangling
+    # coming-soon DUPLICATE of a concrete format is dishonest at source when
+    # every such format change is already the convert operation's job (all
+    # stable). Re-add a concrete target here only when its compress+format
+    # canonicalization actually ships.
+    #
+    # `auto` / `smallest` are the EXCEPTION (re-added 2026-06-23, planned, the
+    # auto-format differentiator): they are SELECTION STRATEGIES, not concrete
+    # formats — the server encodes to several candidate formats and returns the
+    # best (`auto` = the most suitable; `smallest` = the absolute fewest bytes),
+    # reporting the chosen format via the result `mime_type`. `convert` cannot
+    # express "pick the smallest" (it needs an explicit target), so these
+    # genuinely belong on this compress Output facade, not on convert — that is
+    # why they are NOT dangling duplicates. Both stay `per_value_availability:
+    # planned` until the API try-all-return-smallest logic + worker proof land
+    # (coordinated with api + frontend). They are EXCLUDED from the projection's
+    # facade_managed_outputs (not single-target canonicalizations).
     #
     # ---- ROUTE-AWARE "OUTPUT" model (image-options Phase 0, tewB37Jg) ----
     # The user-facing "Output" operation IS this compress op + output_format:
@@ -44,13 +57,16 @@ 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.
     #
     # STABLE on the optimiser (same_format) route (all worker-proven 2026-06-23):
     #   lossless (jpeg/webp) — worker honours the `lossless` bool, API emits it.
@@ -67,7 +83,7 @@ operation:
     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:
@@ -76,42 +92,120 @@ 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
+          honored_on: [same_format]
+          description: >-
+            Compression mode (mirrors compress.video). `quality` = the `quality`
+            slider drives the encode (default). `target_size` = hit a byte budget via
+            the worker's encode-measure-binary-search loop — STABLE (worker-proven on
+            staging, lambdas git-870a7c2: re-encode under target + best-effort below
+            floor + original-wins, all proven). Optimiser (same_format) route.
+        target_size_bytes:
+          type: integer
+          min: 1024
+          depends_on: { encoding_mode: target_size }
+          honored_on: [same_format]
+          description: >-
+            Target output size in bytes (min 1024 = 1 KiB). 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). STABLE (worker-proven, lambdas
+            git-870a7c2). Optimiser (same_format) route.
         metadata:
           type: enum
-          values: [all, keep]
-          default: all
+          values: [strip, keep, all]
+          default: strip
+          per_value_availability:
+            all: { availability: deprecated }
           honored_on: [same_format]
           description: >-
-            Metadata handling (optimiser/same_format route). `all` = strip all
+            Metadata handling (optimiser/same_format route). `strip` = remove 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.
+            (worker-proven, libcaesium; lambdas PR #260, staging round-trip + unit
+            test). `all` is a DEPRECATED alias of `strip` (the pre-2026-06-23 token;
+            `all` reading as "strip all" was counterintuitive) — still accepted,
+            emits Deprecation/Sunset, migrate to `strip`. The API lowers `strip`→`all`
+            at the worker boundary. Any other value is rejected as invalid_options.
+        keep_metadata:
+          type: array
+          items:
+            # items.type is `string` (not `enum`) deliberately: the valid categories
+            # are listed below + enforced by the API at the stable-flip. SDK operation-
+            # schema codegen does not yet support typed array-of-enum (restore `enum` +
+            # values:[copyright,gps,date] when that lands — likely at this option's
+            # stable-flip). Wire-identical either way (a JSON array of strings).
+            type: string
+          uniqueItems: true
+          availability: planned
+          depends_on: { metadata: strip }
+          honored_on: [same_format]
+          description: >-
+            Selective per-category metadata keep (optimiser/same_format route):
+            preserve ONLY these categories and strip the rest — refines the strip
+            path (`metadata: strip`). Valid categories: `copyright`, `gps` (location),
+            `date` (capture time); combinable. `planned` — the worker does not yet
+            do selective keep (use `metadata: keep` to preserve everything), so the
+            API returns feature_not_available until lambdas proves it.
         progressive:
           type: boolean
           default: true
           honored_on: [same_format]
           description: "Enable progressive JPEG rendering (a low-quality preview renders first, then refines). JPEG only — the optimiser (same_format) route."
+        chroma_subsampling:
+          type: enum
+          values: ["420", "422", "444"]
+          honored_on: [same_format]
+          description: >-
+            JPEG chroma subsampling — the colour-resolution/size trade-off.
+            `420` (4:2:0) = smallest, chroma at quarter resolution (default-ish for
+            web photos); `422` (4:2:2) = half-horizontal; `444` (4:4:4) = full chroma
+            (largest, best for sharp colour edges / text). JPEG ONLY (declared on
+            image_jpeg only — ravif hardcodes 4:4:4, libwebp lossy locks 4:2:0).
+            String values (the worker strict-matches strings). STABLE — worker-proven
+            on staging (lambdas PR #264, deployed git-f2bef85: output JPEG SOF luma
+            sampling bytes verified 0x22/0x21/0x11 for 420/422/444). INCOMPATIBLE with
+            `lossless` (any chroma value): lossless JPEG is a DCT-coefficient copy and
+            cannot resample chroma — see the chroma_subsampling.lossless_conflict
+            constraint.
         output_format:
           type: enum
-          values: [original, webp]
+          values: [original, webp, auto, smallest]
           default: original
+          per_value_availability:
+            auto:     { availability: planned }
+            smallest: { availability: planned }
           description: >-
             Output format. original = keep input format (default); webp = recompress to
-            WebP — the one live compress+format target (proven on staging). Other format
+            WebP — the one live compress+format target (proven on staging). Concrete format
             changes (jpeg/png/avif/gif/tiff) are the convert operation's job, not compress.
-            See FORMAT.md.
+            `auto` / `smallest` are PLANNED auto-format directives — the server encodes to
+            several candidate formats and returns the best (`auto` = the most suitable;
+            `smallest` = the absolute fewest bytes), reporting the chosen format via the
+            result `mime_type`. They are SELECTION STRATEGIES, not concrete targets (convert
+            cannot express "pick the smallest"), so they live here and stay `planned` until
+            the API try-all-return-smallest logic + worker proof land. See FORMAT.md.
         lossless:
           type: boolean
           default: false
+          depends_on: { encoding_mode: quality }
           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.
+            (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
@@ -120,8 +214,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
@@ -136,9 +231,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:
@@ -154,14 +252,39 @@ operation:
           description: "Compression quality (1 = smallest file, 100 = best quality)."
         metadata:
           type: enum
-          values: [all, keep]
-          default: all
+          values: [strip, keep, all]
+          default: strip
+          per_value_availability:
+            all: { availability: deprecated }
           honored_on: [same_format]
           description: >-
-            Metadata handling (optimiser/same_format route). `all` = strip all
+            Metadata handling (optimiser/same_format route). `strip` = remove 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.
+            (worker-proven, libcaesium; lambdas PR #260, staging round-trip + unit
+            test). `all` is a DEPRECATED alias of `strip` (the pre-2026-06-23 token;
+            `all` reading as "strip all" was counterintuitive) — still accepted,
+            emits Deprecation/Sunset, migrate to `strip`. The API lowers `strip`→`all`
+            at the worker boundary. Any other value is rejected as invalid_options.
+        keep_metadata:
+          type: array
+          items:
+            # items.type is `string` (not `enum`) deliberately: the valid categories
+            # are listed below + enforced by the API at the stable-flip. SDK operation-
+            # schema codegen does not yet support typed array-of-enum (restore `enum` +
+            # values:[copyright,gps,date] when that lands — likely at this option's
+            # stable-flip). Wire-identical either way (a JSON array of strings).
+            type: string
+          uniqueItems: true
+          availability: planned
+          depends_on: { metadata: strip }
+          honored_on: [same_format]
+          description: >-
+            Selective per-category metadata keep (optimiser/same_format route):
+            preserve ONLY these categories and strip the rest — refines the strip
+            path (`metadata: strip`). Valid categories: `copyright`, `gps` (location),
+            `date` (capture time); combinable. `planned` — the worker does not yet
+            do selective keep (use `metadata: keep` to preserve everything), so the
+            API returns feature_not_available until lambdas proves it.
         optimization_level:
           type: integer
           min: 0
@@ -171,13 +294,21 @@ operation:
           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]
+          values: [original, webp, auto, smallest]
           default: original
+          per_value_availability:
+            auto:     { availability: planned }
+            smallest: { availability: planned }
           description: >-
             Output format. original = keep input format (default); webp = recompress to
-            WebP — the one live compress+format target (proven on staging). Other format
+            WebP — the one live compress+format target (proven on staging). Concrete format
             changes (jpeg/png/avif/gif/tiff) are the convert operation's job, not compress.
-            See FORMAT.md.
+            `auto` / `smallest` are PLANNED auto-format directives — the server encodes to
+            several candidate formats and returns the best (`auto` = the most suitable;
+            `smallest` = the absolute fewest bytes), reporting the chosen format via the
+            result `mime_type`. They are SELECTION STRATEGIES, not concrete targets (convert
+            cannot express "pick the smallest"), so they live here and stay `planned` until
+            the API try-all-return-smallest logic + worker proof land. See FORMAT.md.
         lossy:
           type: boolean
           default: false
@@ -197,8 +328,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
@@ -213,9 +345,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
@@ -237,18 +372,48 @@ 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
+          honored_on: [same_format]
+          description: >-
+            Compression mode (mirrors compress.video). `quality` = the `quality`
+            slider drives the encode (default). `target_size` = hit a byte budget via
+            the worker's encode-measure-binary-search loop — STABLE (worker-proven on
+            staging, lambdas git-870a7c2: re-encode under target + best-effort +
+            original-wins). AVIF encodes are slow, so the loop caps iterations (a
+            6-iteration cap, ~18s worst case). Optimiser (same_format) route.
+        target_size_bytes:
+          type: integer
+          min: 1024
+          depends_on: { encoding_mode: target_size }
+          honored_on: [same_format]
+          description: >-
+            Target output size in bytes (min 1024 = 1 KiB). 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). STABLE (worker-proven, lambdas
+            git-870a7c2). Optimiser (same_format) route.
         metadata:
           type: enum
-          values: [all]
-          default: all
+          values: [strip, all]
+          default: strip
+          per_value_availability:
+            all: { availability: deprecated }
           honored_on: [same_format]
           description: >-
-            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).
+            Metadata handling. `strip` = remove all EXIF/IPTC/XMP (default, the only
+            supported behaviour). `all` is a DEPRECATED alias of `strip` (migrate to
+            `strip`; the API lowers it at the worker boundary). `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
@@ -258,13 +423,21 @@ operation:
           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]
+          values: [original, webp, auto, smallest]
           default: original
+          per_value_availability:
+            auto:     { availability: planned }
+            smallest: { availability: planned }
           description: >-
             Output format. original = keep input format (default); webp = recompress to
-            WebP — the one live compress+format target (proven on staging). Other format
+            WebP — the one live compress+format target (proven on staging). Concrete format
             changes (jpeg/png/avif/gif/tiff) are the convert operation's job, not compress.
-            See FORMAT.md.
+            `auto` / `smallest` are PLANNED auto-format directives — the server encodes to
+            several candidate formats and returns the best (`auto` = the most suitable;
+            `smallest` = the absolute fewest bytes), reporting the chosen format via the
+            result `mime_type`. They are SELECTION STRATEGIES, not concrete targets (convert
+            cannot express "pick the smallest"), so they live here and stay `planned` until
+            the API try-all-return-smallest logic + worker proof land. See FORMAT.md.
         width:
           type: integer
           min: 1
@@ -273,8 +446,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
@@ -289,9 +463,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
@@ -307,36 +484,98 @@ 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
+          honored_on: [same_format]
+          description: >-
+            Compression mode (mirrors compress.video). `quality` = the `quality`
+            slider drives the encode (default). `target_size` = hit a byte budget via
+            the worker's encode-measure-binary-search loop — STABLE (worker-proven on
+            staging, lambdas git-870a7c2: re-encode under target + best-effort below
+            floor + original-wins, all proven). Optimiser (same_format) route.
+        target_size_bytes:
+          type: integer
+          min: 1024
+          depends_on: { encoding_mode: target_size }
+          honored_on: [same_format]
+          description: >-
+            Target output size in bytes (min 1024 = 1 KiB). 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). STABLE (worker-proven, lambdas
+            git-870a7c2). Optimiser (same_format) route.
         metadata:
           type: enum
-          values: [all, keep]
-          default: all
+          values: [strip, keep, all]
+          default: strip
+          per_value_availability:
+            all: { availability: deprecated }
           honored_on: [same_format]
           description: >-
-            Metadata handling (optimiser/same_format route). `all` = strip all
+            Metadata handling (optimiser/same_format route). `strip` = remove 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.
+            (worker-proven, libcaesium; lambdas PR #260, staging round-trip + unit
+            test). `all` is a DEPRECATED alias of `strip` (the pre-2026-06-23 token;
+            `all` reading as "strip all" was counterintuitive) — still accepted,
+            emits Deprecation/Sunset, migrate to `strip`. The API lowers `strip`→`all`
+            at the worker boundary. Any other value is rejected as invalid_options.
+        keep_metadata:
+          type: array
+          items:
+            # items.type is `string` (not `enum`) deliberately: the valid categories
+            # are listed below + enforced by the API at the stable-flip. SDK operation-
+            # schema codegen does not yet support typed array-of-enum (restore `enum` +
+            # values:[copyright,gps,date] when that lands — likely at this option's
+            # stable-flip). Wire-identical either way (a JSON array of strings).
+            type: string
+          uniqueItems: true
+          availability: planned
+          depends_on: { metadata: strip }
+          honored_on: [same_format]
+          description: >-
+            Selective per-category metadata keep (optimiser/same_format route):
+            preserve ONLY these categories and strip the rest — refines the strip
+            path (`metadata: strip`). Valid categories: `copyright`, `gps` (location),
+            `date` (capture time); combinable. `planned` — the worker does not yet
+            do selective keep (use `metadata: keep` to preserve everything), so the
+            API returns feature_not_available until lambdas proves it.
         output_format:
           type: enum
-          values: [original, webp]
+          values: [original, webp, auto, smallest]
           default: original
+          per_value_availability:
+            auto:     { availability: planned }
+            smallest: { availability: planned }
           description: >-
             Output format. original = keep input format (default); webp = recompress to
-            WebP — the one live compress+format target (proven on staging). Other format
+            WebP — the one live compress+format target (proven on staging). Concrete format
             changes (jpeg/png/avif/gif/tiff) are the convert operation's job, not compress.
-            See FORMAT.md.
+            `auto` / `smallest` are PLANNED auto-format directives — the server encodes to
+            several candidate formats and returns the best (`auto` = the most suitable;
+            `smallest` = the absolute fewest bytes), reporting the chosen format via the
+            result `mime_type`. They are SELECTION STRATEGIES, not concrete targets (convert
+            cannot express "pick the smallest"), so they live here and stay `planned` until
+            the API try-all-return-smallest logic + worker proof land. See FORMAT.md.
         lossless:
           type: boolean
           default: false
+          depends_on: { encoding_mode: quality }
           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.
+            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
@@ -345,8 +584,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
@@ -361,9 +601,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
@@ -381,20 +624,31 @@ operation:
           description: "Compression quality (1 = smallest file, 100 = best quality)."
         metadata:
           type: enum
-          values: [all]
-          default: all
+          values: [strip, all]
+          default: strip
+          per_value_availability:
+            all: { availability: deprecated }
           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).
+            Metadata handling. `strip` = remove all metadata (default, the only
+            supported behaviour). `all` is a DEPRECATED alias of `strip` (migrate to
+            `strip`; the API lowers it at the worker boundary). `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]
+          values: [original, webp, auto, smallest]
           default: original
+          per_value_availability:
+            auto:     { availability: planned }
+            smallest: { availability: planned }
           description: >-
             Output format. original = keep input format (default); webp = recompress to
-            WebP. Other format changes are the convert operation's job. See FORMAT.md.
+            WebP. Concrete format changes are the convert operation's job. `auto` /
+            `smallest` are PLANNED auto-format directives (server picks the best/smallest
+            candidate format, reported via the result `mime_type`) — selection strategies,
+            not concrete targets, planned until the API logic + worker proof land. 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.
@@ -415,23 +669,56 @@ operation:
             GIF the worker honours this but real-world size reduction is typically small.
         metadata:
           type: enum
-          values: [all, keep]
-          default: all
+          values: [strip, keep, all]
+          default: strip
+          per_value_availability:
+            all: { availability: deprecated }
           honored_on: [same_format]
           description: >-
-            Metadata handling (optimiser/same_format route). `all` = strip all
+            Metadata handling (optimiser/same_format route). `strip` = remove 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.
+            (worker-proven, libcaesium; lambdas PR #260, staging round-trip + unit
+            test). `all` is a DEPRECATED alias of `strip` (the pre-2026-06-23 token;
+            `all` reading as "strip all" was counterintuitive) — still accepted,
+            emits Deprecation/Sunset, migrate to `strip`. The API lowers `strip`→`all`
+            at the worker boundary. Any other value is rejected as invalid_options.
+        keep_metadata:
+          type: array
+          items:
+            # items.type is `string` (not `enum`) deliberately: the valid categories
+            # are listed below + enforced by the API at the stable-flip. SDK operation-
+            # schema codegen does not yet support typed array-of-enum (restore `enum` +
+            # values:[copyright,gps,date] when that lands — likely at this option's
+            # stable-flip). Wire-identical either way (a JSON array of strings).
+            type: string
+          uniqueItems: true
+          availability: planned
+          depends_on: { metadata: strip }
+          honored_on: [same_format]
+          description: >-
+            Selective per-category metadata keep (optimiser/same_format route):
+            preserve ONLY these categories and strip the rest — refines the strip
+            path (`metadata: strip`). Valid categories: `copyright`, `gps` (location),
+            `date` (capture time); combinable. `planned` — the worker does not yet
+            do selective keep (use `metadata: keep` to preserve everything), so the
+            API returns feature_not_available until lambdas proves it.
         output_format:
           type: enum
-          values: [original, webp]
+          values: [original, webp, auto, smallest]
           default: original
+          per_value_availability:
+            auto:     { availability: planned }
+            smallest: { availability: planned }
           description: >-
             Output format. original = keep input format (default); webp = recompress to
-            WebP — the one live compress+format target (proven on staging). Other format
+            WebP — the one live compress+format target (proven on staging). Concrete format
             changes (jpeg/png/avif/gif/tiff) are the convert operation's job, not compress.
-            See FORMAT.md.
+            `auto` / `smallest` are PLANNED auto-format directives — the server encodes to
+            several candidate formats and returns the best (`auto` = the most suitable;
+            `smallest` = the absolute fewest bytes), reporting the chosen format via the
+            result `mime_type`. They are SELECTION STRATEGIES, not concrete targets (convert
+            cannot express "pick the smallest"), so they live here and stay `planned` until
+            the API try-all-return-smallest logic + worker proof land. See FORMAT.md.
         width:
           type: integer
           min: 1
@@ -440,8 +727,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
@@ -456,9 +744,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: