@giveitsmaller/contracts 0.47.0 → 0.50.0

package/operations/schemas/compress.yaml

@@ -104,15 +104,23 @@ operation:
             automatically to hit the size budget, so this option is inactive.
         encoding_mode:
           type: enum
-          values: [quality, target_size]
+          values: [quality, target_size, auto_quality]
           default: quality
+          # auto_quality flipped planned->stable 2026-06-30 on the lambdas staging
+          # proof (compression-image git-122a329, harness PR #294): the SSIM-target
+          # search is calibrated — the `good` preset measures ~0.95 across jpeg/webp/
+          # avif and the best/good/fair/low ladder is monotonic. All three
+          # encoding_mode values are now live (ticket PQMWCqfR; no ADR).
           honored_on: [same_format]
           description: >-
             Compression mode. `quality` = the `quality` slider drives the encode
             (default). `target_size` = automatically find the highest quality that
             fits a byte budget (set via `target_size_bytes`); if the budget can't be
             met even at the lowest quality, the closest result is returned, and the
-            original is kept if re-encoding wouldn't be smaller.
+            original is kept if re-encoding wouldn't be smaller. `auto_quality` = hit
+            a named perceptual-quality target (set via `quality_preset`) and let the
+            worker pick the encoder quality that meets it — the perceptual twin of
+            `target_size` (which targets bytes); the result reports the chosen quality.
         target_size_bytes:
           type: integer
           min: 1024
@@ -124,6 +132,20 @@ operation:
             be met even at the lowest quality, the closest result is returned (the
             result reports the chosen quality and whether the target was met). Requires
             `encoding_mode: target_size`.
+        quality_preset:
+          type: enum
+          values: [best, good, fair, low]
+          default: good
+          depends_on: { encoding_mode: auto_quality }
+          honored_on: [same_format]
+          description: >-
+            Named perceptual-quality target for `encoding_mode: auto_quality`
+            (best > good > fair > low; `good` is the default). The worker runs a
+            perceptual-target search and picks the encoder quality that meets the
+            named tier — the wire carries the NAME only, so the tier→target mapping
+            stays worker-internal and calibration-tunable without a contract change.
+            Requires `encoding_mode: auto_quality`. The achieved perceptual score is
+            reported on the result as `metrics.measured_quality` (+ `metrics.quality_metric`).
         metadata:
           type: enum
           values: [strip, keep, all]
@@ -136,27 +158,11 @@ operation:
             preserve EXIF, colour profile, and XMP. `all` is a DEPRECATED alias of
             `strip` (kept for older callers; emits Deprecation/Sunset headers — migrate
             to `strip`). Any other value is rejected.
-        keep_metadata:
-          type: array
-          items:
-            # JSON-Schema `enum:` (not the DSL `type: enum`) on a string item: the
-            # SDK operation-schema parser's valid array-item types are
-            # {number,integer,float,string,object} — `type: enum` is rejected, so the
-            # categories are carried as a JSON-Schema `enum` constraint on a string
-            # item. Consumers (FE) read the allowed categories structurally from the
-            # sidecar; SDK codegen sees a string array (the enum key is value-only) —
-            # wire-identical (a JSON array of strings).
-            type: string
-            enum: [copyright, gps, date]
-          uniqueItems: true
-          availability: planned
-          depends_on: { metadata: strip }
-          honored_on: [same_format]
-          description: >-
-            Selectively keep only certain metadata categories and strip the rest —
-            refines `metadata: strip`. Allowed categories: `copyright`, `gps`
-            (location), `date` (capture time); combinable. `planned` — selective keep
-            is not yet supported (use `metadata: keep` to preserve everything).
+        # keep_metadata (selective copyright/gps/date) REMOVED 2026-06-30 (hub honesty
+        # decision): the compress worker (libcaesium) does ALL-OR-NOTHING keep/strip
+        # only — no per-category control, and selective EXIF/XMP surgery is unscheduled
+        # (lambdas, M-L build). Use `metadata: keep` for all-or-nothing preservation.
+        # Re-add the selective primitive when that worker support is built + scheduled.
         progressive:
           type: boolean
           default: true
@@ -237,7 +243,7 @@ operation:
             that stripping metadata never silently shifts colours. `keep` (default) =
             preserve your colours: embed the ICC profile where the output format can
             carry one, otherwise convert to sRGB and bake the colours in so they survive
-            (never a silent drop); `srgb` = convert to sRGB (also handles CMYK → sRGB);
+            (never a silent drop); `srgb` = convert to sRGB (transform pixels to sRGB, emit untagged — no embedded ICC, the web default; CMYK/grayscale best-effort);
             `strip` = drop the profile (smallest — only when the consumer manages colour
             itself).
         auto_orient:
@@ -262,7 +268,14 @@ operation:
           max: 100
           default: 80
           honored_on: [same_format]
-          description: "Compression quality (1 = smallest file, 100 = best quality)."
+          description: >-
+            Compression quality (1-100). For PNG this is the SINGLE lossy/lossless
+            control: `quality` < 100 applies lossy palette quantization (imagequant —
+            licence-cleared for our server-side SaaS backend, `kkajDFXD`; the value is
+            the quantization level), while `quality: 100` keeps the PNG lossless (oxipng
+            optimisation only — tune the lossless effort via `optimization_level`).
+            1 = smallest file, 100 = best quality / lossless. There is no separate
+            lossy/lossless toggle for PNG — it is purely quality-driven.
         metadata:
           type: enum
           values: [strip, keep, all]
@@ -275,27 +288,11 @@ operation:
             preserve EXIF, colour profile, and XMP. `all` is a DEPRECATED alias of
             `strip` (kept for older callers; emits Deprecation/Sunset headers — migrate
             to `strip`). Any other value is rejected.
-        keep_metadata:
-          type: array
-          items:
-            # JSON-Schema `enum:` (not the DSL `type: enum`) on a string item: the
-            # SDK operation-schema parser's valid array-item types are
-            # {number,integer,float,string,object} — `type: enum` is rejected, so the
-            # categories are carried as a JSON-Schema `enum` constraint on a string
-            # item. Consumers (FE) read the allowed categories structurally from the
-            # sidecar; SDK codegen sees a string array (the enum key is value-only) —
-            # wire-identical (a JSON array of strings).
-            type: string
-            enum: [copyright, gps, date]
-          uniqueItems: true
-          availability: planned
-          depends_on: { metadata: strip }
-          honored_on: [same_format]
-          description: >-
-            Selectively keep only certain metadata categories and strip the rest —
-            refines `metadata: strip`. Allowed categories: `copyright`, `gps`
-            (location), `date` (capture time); combinable. `planned` — selective keep
-            is not yet supported (use `metadata: keep` to preserve everything).
+        # keep_metadata (selective copyright/gps/date) REMOVED 2026-06-30 (hub honesty
+        # decision): the compress worker (libcaesium) does ALL-OR-NOTHING keep/strip
+        # only — no per-category control, and selective EXIF/XMP surgery is unscheduled
+        # (lambdas, M-L build). Use `metadata: keep` for all-or-nothing preservation.
+        # Re-add the selective primitive when that worker support is built + scheduled.
         optimization_level:
           type: integer
           min: 0
@@ -319,14 +316,6 @@ operation:
             reporting the chosen format via the result `mime_type`. They are selection
             strategies, not concrete targets, and stay `planned` until supported. See
             FORMAT.md.
-        lossy:
-          type: boolean
-          default: false
-          availability: planned
-          honored_on: [same_format]
-          description: >-
-            Lossy PNG palette quantization — a large saving for flat-colour PNGs.
-            `planned` — not yet supported.
         width:
           type: integer
           min: 1
@@ -365,7 +354,7 @@ operation:
             that stripping metadata never silently shifts colours. `keep` (default) =
             preserve your colours: embed the ICC profile where the output format can
             carry one, otherwise convert to sRGB and bake the colours in so they survive
-            (never a silent drop); `srgb` = convert to sRGB (also handles CMYK → sRGB);
+            (never a silent drop); `srgb` = convert to sRGB (transform pixels to sRGB, emit untagged — no embedded ICC, the web default; CMYK/grayscale best-effort);
             `strip` = drop the profile (smallest — only when the consumer manages colour
             itself).
         auto_orient:
@@ -380,9 +369,12 @@ operation:
             which can drop other (non-orientation) metadata even with `metadata: keep`.
 
     image_avif:
-      availability: beta
-      # avif INPUT decode shipped in the compress-image worker via libheif
-      # (lambdas w34Taquf, #210). beta: live + opt-in, shape-stable.
+      # avif INPUT compress (libheif decode + ravif re-encode) is now GA-STABLE —
+      # flipped beta->stable 2026-06-30 on the lambdas attestation: decode+re-encode
+      # proven 1-46MP (quality / target_size / auto_quality all green), AND the
+      # large-image crash path is now guarded (#295, compression-image git-74b3161,
+      # digest-verified): inputs >~70MP return a clean non-retryable InvalidRequest
+      # instead of an OOM process-kill, so GA carries no crash path.
       # image/heic is intentionally NOT a compress input: compress is decode-only
       # and there is no HEIC encoder, so the worker rejects a declared image/heic
       # (FormatMismatch). heic stays on convert+thumbnail.
@@ -407,16 +399,25 @@ operation:
             automatically to hit the size budget, so this option is inactive.
         encoding_mode:
           type: enum
-          values: [quality, target_size]
+          values: [quality, target_size, auto_quality]
           default: quality
+          # auto_quality flipped planned->stable 2026-06-30 on the lambdas staging
+          # proof (compression-image git-122a329, harness PR #294): the SSIM-target
+          # search is calibrated — the `good` preset measures ~0.95 across jpeg/webp/
+          # avif and the best/good/fair/low ladder is monotonic. All three
+          # encoding_mode values are now live (ticket PQMWCqfR; no ADR).
           honored_on: [same_format]
           description: >-
             Compression mode. `quality` = the `quality` slider drives the encode
             (default). `target_size` = automatically find the highest quality that
             fits a byte budget (set via `target_size_bytes`); if the budget can't be
             met even at the lowest quality, the closest result is returned, and the
-            original is kept if re-encoding wouldn't be smaller. AVIF encoding is
-            slower, so the search is bounded and may stop slightly above the budget.
+            original is kept if re-encoding wouldn't be smaller. `auto_quality` = hit
+            a named perceptual-quality target (set via `quality_preset`) and let the
+            worker pick the encoder quality that meets it — the perceptual twin of
+            `target_size` (which targets bytes); the result reports the chosen quality.
+            AVIF encoding is slower, so the search is bounded and may stop slightly
+            above the budget.
         target_size_bytes:
           type: integer
           min: 1024
@@ -428,6 +429,20 @@ operation:
             be met even at the lowest quality, the closest result is returned (the
             result reports the chosen quality and whether the target was met). Requires
             `encoding_mode: target_size`.
+        quality_preset:
+          type: enum
+          values: [best, good, fair, low]
+          default: good
+          depends_on: { encoding_mode: auto_quality }
+          honored_on: [same_format]
+          description: >-
+            Named perceptual-quality target for `encoding_mode: auto_quality`
+            (best > good > fair > low; `good` is the default). The worker runs a
+            perceptual-target search and picks the encoder quality that meets the
+            named tier — the wire carries the NAME only, so the tier→target mapping
+            stays worker-internal and calibration-tunable without a contract change.
+            Requires `encoding_mode: auto_quality`. The achieved perceptual score is
+            reported on the result as `metrics.measured_quality` (+ `metrics.quality_metric`).
         metadata:
           type: enum
           values: [strip, all]
@@ -495,14 +510,21 @@ operation:
           type: enum
           values: [keep, srgb, strip]
           default: keep
-          availability: planned
           honored_on: [same_format, format_change]
           description: >-
             Colour-profile handling — a dedicated control, separate from `metadata` so
             that stripping metadata never silently shifts colours. `keep` (default) =
-            preserve the embedded colour profile; `srgb` = convert to sRGB (also
-            handles CMYK → sRGB); `strip` = drop the profile (smallest — only when the
-            consumer manages colour itself). `planned` — not yet supported.
+            preserve your colours: embed the ICC profile where the output format can
+            carry one, otherwise convert to sRGB and bake the colours in so they survive
+            (never a silent drop — for AVIF the gamut is baked to sRGB); `srgb` = convert
+            to sRGB (transform pixels to sRGB, emit untagged — no embedded ICC, the web
+            default; CMYK/grayscale best-effort); `strip` = drop the profile (smallest —
+            only when the consumer manages colour itself). All three values are live on
+            compress AVIF — `srgb` flipped planned->stable 2026-06-30 on the lambdas
+            proof (wide-gamut-p3-icc.avif: srgb bakes untagged, whole-image RMSE 0.041 /
+            92% pixels shifted vs strip). Note: on AVIF `keep` and `srgb` both bake the
+            gamut to sRGB by design, so keep_px == srgb_px; the proving inequality is
+            srgb != strip, which holds.
         auto_orient:
           type: boolean
           default: true
@@ -536,15 +558,23 @@ operation:
             automatically to hit the size budget, so this option is inactive.
         encoding_mode:
           type: enum
-          values: [quality, target_size]
+          values: [quality, target_size, auto_quality]
           default: quality
+          # auto_quality flipped planned->stable 2026-06-30 on the lambdas staging
+          # proof (compression-image git-122a329, harness PR #294): the SSIM-target
+          # search is calibrated — the `good` preset measures ~0.95 across jpeg/webp/
+          # avif and the best/good/fair/low ladder is monotonic. All three
+          # encoding_mode values are now live (ticket PQMWCqfR; no ADR).
           honored_on: [same_format]
           description: >-
             Compression mode. `quality` = the `quality` slider drives the encode
             (default). `target_size` = automatically find the highest quality that
             fits a byte budget (set via `target_size_bytes`); if the budget can't be
             met even at the lowest quality, the closest result is returned, and the
-            original is kept if re-encoding wouldn't be smaller.
+            original is kept if re-encoding wouldn't be smaller. `auto_quality` = hit
+            a named perceptual-quality target (set via `quality_preset`) and let the
+            worker pick the encoder quality that meets it — the perceptual twin of
+            `target_size` (which targets bytes); the result reports the chosen quality.
         target_size_bytes:
           type: integer
           min: 1024
@@ -556,6 +586,20 @@ operation:
             be met even at the lowest quality, the closest result is returned (the
             result reports the chosen quality and whether the target was met). Requires
             `encoding_mode: target_size`.
+        quality_preset:
+          type: enum
+          values: [best, good, fair, low]
+          default: good
+          depends_on: { encoding_mode: auto_quality }
+          honored_on: [same_format]
+          description: >-
+            Named perceptual-quality target for `encoding_mode: auto_quality`
+            (best > good > fair > low; `good` is the default). The worker runs a
+            perceptual-target search and picks the encoder quality that meets the
+            named tier — the wire carries the NAME only, so the tier→target mapping
+            stays worker-internal and calibration-tunable without a contract change.
+            Requires `encoding_mode: auto_quality`. The achieved perceptual score is
+            reported on the result as `metrics.measured_quality` (+ `metrics.quality_metric`).
         metadata:
           type: enum
           values: [strip, keep, all]
@@ -568,27 +612,11 @@ operation:
             preserve EXIF, colour profile, and XMP. `all` is a DEPRECATED alias of
             `strip` (kept for older callers; emits Deprecation/Sunset headers — migrate
             to `strip`). Any other value is rejected.
-        keep_metadata:
-          type: array
-          items:
-            # JSON-Schema `enum:` (not the DSL `type: enum`) on a string item: the
-            # SDK operation-schema parser's valid array-item types are
-            # {number,integer,float,string,object} — `type: enum` is rejected, so the
-            # categories are carried as a JSON-Schema `enum` constraint on a string
-            # item. Consumers (FE) read the allowed categories structurally from the
-            # sidecar; SDK codegen sees a string array (the enum key is value-only) —
-            # wire-identical (a JSON array of strings).
-            type: string
-            enum: [copyright, gps, date]
-          uniqueItems: true
-          availability: planned
-          depends_on: { metadata: strip }
-          honored_on: [same_format]
-          description: >-
-            Selectively keep only certain metadata categories and strip the rest —
-            refines `metadata: strip`. Allowed categories: `copyright`, `gps`
-            (location), `date` (capture time); combinable. `planned` — selective keep
-            is not yet supported (use `metadata: keep` to preserve everything).
+        # keep_metadata (selective copyright/gps/date) REMOVED 2026-06-30 (hub honesty
+        # decision): the compress worker (libcaesium) does ALL-OR-NOTHING keep/strip
+        # only — no per-category control, and selective EXIF/XMP surgery is unscheduled
+        # (lambdas, M-L build). Use `metadata: keep` for all-or-nothing preservation.
+        # Re-add the selective primitive when that worker support is built + scheduled.
         output_format:
           type: enum
           values: [original, webp, auto, smallest]
@@ -647,18 +675,17 @@ operation:
           type: enum
           values: [keep, srgb, strip]
           default: keep
-          per_value_availability:
-            srgb: { availability: planned }
           honored_on: [same_format, format_change]
           description: >-
             Colour-profile handling — a dedicated control, separate from `metadata` so
             that stripping metadata never silently shifts colours. `keep` (default) =
             preserve your colours: embed the ICC profile where the output format can
             carry one, otherwise convert to sRGB and bake the colours in so they survive
-            (never a silent drop); `srgb` = convert to sRGB (also handles CMYK → sRGB);
+            (never a silent drop); `srgb` = convert to sRGB (transform pixels to sRGB, emit untagged — no embedded ICC, the web default; CMYK/grayscale best-effort);
             `strip` = drop the profile (smallest — only when the consumer manages colour
-            itself). On the WebP same-format route `srgb` is `planned` (the byte-level
-            optimiser does not yet run the sRGB transform); `keep` and `strip` are live.
+            itself). All three values are live on the WebP same-format route — the sRGB
+            pixel transform is staging-proven (lambdas compression-image git-13b5000:
+            srgb output untagged + a real pixel shift vs strip).
         auto_orient:
           type: boolean
           default: true
@@ -677,13 +704,11 @@ operation:
       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)."
+        # No `quality`: compress SVG is SVG->SVG via SVGO (lossless vector optimise);
+        # `quality` is never passed to the worker, so a quality slider here is a no-op
+        # (removed — lambdas worker-code investigation, the SVG-quality ticket). Raster
+        # output (the webp facade route) goes through convert, which carries its own
+        # quality on convert.image_svg.
         metadata:
           type: enum
           values: [strip, all]
@@ -740,27 +765,11 @@ operation:
             preserve EXIF, colour profile, and XMP. `all` is a DEPRECATED alias of
             `strip` (kept for older callers; emits Deprecation/Sunset headers — migrate
             to `strip`). Any other value is rejected.
-        keep_metadata:
-          type: array
-          items:
-            # JSON-Schema `enum:` (not the DSL `type: enum`) on a string item: the
-            # SDK operation-schema parser's valid array-item types are
-            # {number,integer,float,string,object} — `type: enum` is rejected, so the
-            # categories are carried as a JSON-Schema `enum` constraint on a string
-            # item. Consumers (FE) read the allowed categories structurally from the
-            # sidecar; SDK codegen sees a string array (the enum key is value-only) —
-            # wire-identical (a JSON array of strings).
-            type: string
-            enum: [copyright, gps, date]
-          uniqueItems: true
-          availability: planned
-          depends_on: { metadata: strip }
-          honored_on: [same_format]
-          description: >-
-            Selectively keep only certain metadata categories and strip the rest —
-            refines `metadata: strip`. Allowed categories: `copyright`, `gps`
-            (location), `date` (capture time); combinable. `planned` — selective keep
-            is not yet supported (use `metadata: keep` to preserve everything).
+        # keep_metadata (selective copyright/gps/date) REMOVED 2026-06-30 (hub honesty
+        # decision): the compress worker (libcaesium) does ALL-OR-NOTHING keep/strip
+        # only — no per-category control, and selective EXIF/XMP surgery is unscheduled
+        # (lambdas, M-L build). Use `metadata: keep` for all-or-nothing preservation.
+        # Re-add the selective primitive when that worker support is built + scheduled.
         output_format:
           type: enum
           values: [original, webp, auto, smallest]
@@ -809,14 +818,21 @@ operation:
           type: enum
           values: [keep, srgb, strip]
           default: keep
-          availability: planned
+          per_value_availability:
+            srgb: { availability: planned }
           honored_on: [same_format, format_change]
           description: >-
             Colour-profile handling — a dedicated control, separate from `metadata` so
             that stripping metadata never silently shifts colours. `keep` (default) =
-            preserve the embedded colour profile; `srgb` = convert to sRGB (also
-            handles CMYK → sRGB); `strip` = drop the profile (smallest — only when the
-            consumer manages colour itself). `planned` — not yet supported.
+            preserve your colours: embed the ICC profile where the output format can
+            carry one, otherwise convert to sRGB and bake the colours in so they survive
+            (never a silent drop — for TIFF inputs the gamut is baked to sRGB; GIF carries
+            no profile so this is a no-op); `srgb` = convert to sRGB (transform pixels to
+            sRGB, emit untagged — no embedded ICC, the web default; CMYK/grayscale
+            best-effort); `strip` = drop the profile (smallest — only when the consumer
+            manages colour itself). On compress `srgb` is `planned` for this group (the
+            sRGB pixel transform is wired for JPEG/PNG only so far); `keep` and `strip`
+            are live.
         auto_orient:
           type: boolean
           default: true
@@ -1178,13 +1194,11 @@ operation:
           max: 100
           default: 50
           description: "Compression quality (1 = smallest, 100 = best). The only document compression option supported today."
-        image_quality:
-          type: integer
-          min: 1
-          max: 100
-          default: 80
-          availability: planned
-          description: "Recompress embedded images at this quality level (1 = smallest, 100 = best). `planned` — not yet supported (use `quality`)."
+        # image_quality REMOVED 2026-06-30 (hub honesty decision): redundant — the
+        # zip-based document worker ALREADY recompresses embedded jpeg/png/webp/gif
+        # via libcaesium, driven by the general `quality` option (capability is LIVE).
+        # The separate `image_quality` knob was unwired (a planned no-op). Re-add only
+        # if a distinct image-vs-document quality split is genuinely wanted (small wiring).
         strip_macros:
           type: boolean
           default: true
@@ -1214,13 +1228,11 @@ operation:
           max: 100
           default: 50
           description: "Compression quality (1 = smallest, 100 = best). The only document compression option supported today."
-        image_quality:
-          type: integer
-          min: 1
-          max: 100
-          default: 80
-          availability: planned
-          description: "Recompress embedded images at this quality level. `planned` — not yet supported (use `quality`)."
+        # image_quality REMOVED 2026-06-30 (hub honesty decision): redundant — the
+        # zip-based document worker ALREADY recompresses embedded jpeg/png/webp/gif
+        # via libcaesium, driven by the general `quality` option (capability is LIVE).
+        # The separate `image_quality` knob was unwired (a planned no-op). Re-add only
+        # if a distinct image-vs-document quality split is genuinely wanted (small wiring).
         strip_metadata:
           type: boolean
           default: true
@@ -1243,13 +1255,11 @@ operation:
           max: 100
           default: 50
           description: "Compression quality (1 = smallest, 100 = best). The only document compression option supported today."
-        image_quality:
-          type: integer
-          min: 1
-          max: 100
-          default: 80
-          availability: planned
-          description: "Recompress embedded images at this quality level. `planned` — not yet supported (use `quality`)."
+        # image_quality REMOVED 2026-06-30 (hub honesty decision): redundant — the
+        # zip-based document worker ALREADY recompresses embedded jpeg/png/webp/gif
+        # via libcaesium, driven by the general `quality` option (capability is LIVE).
+        # The separate `image_quality` knob was unwired (a planned no-op). Re-add only
+        # if a distinct image-vs-document quality split is genuinely wanted (small wiring).
         font_subsetting:
           type: boolean
           default: true