@giveitsmaller/contracts 0.48.0 → 0.51.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
@@ -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
@@ -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,8 +675,6 @@ 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
@@ -657,8 +683,9 @@ operation:
             carry one, otherwise convert to sRGB and bake the colours in so they survive
             (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]
@@ -1185,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
@@ -1221,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
@@ -1250,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

package/operations/schemas/convert.yaml

@@ -25,20 +25,16 @@ operation:
         - image/avif
         - image/heic
         - image/heif
-      per_mime_availability:
-        # avif/heic/heif input decode in the convert worker via libheif (the
-        # opt-in beta tier — heavier/newer decode path). beta: live + opt-in,
-        # shape-stable. avif/heic re-added after the v2.67.0 crash-window drop
-        # (aYPbNVKD Phase 2). image/heif is the accept-list ALIAS of the HEIF
-        # container (same libheif decode as heic) — added 2026-06-24, lambdas
-        # PR #265 (deployed git-7b13754) staging-proved heif→jpeg + heif→png
-        # (decode→encode via libheif; pure accept-list widening, no verify_mime).
-        # Kept beta to match heic/avif (the libheif tier); flip the whole tier
-        # to stable as a deliberate GA-finish if product wants it.
-        # (avif is also a valid OUTPUT via output_format — ravif encode.)
-        image/avif: { availability: beta }
-        image/heic: { availability: beta }
-        image/heif: { availability: beta }
+      # avif/heic/heif input decode in the convert worker via libheif is now
+      # GA-STABLE — no per_mime_availability tag = stable (the group default),
+      # promoted beta→stable 2026-06-30 on the lambdas GA attestation: libheif
+      # decode (w34Taquf #210/#211; heif accept-list alias #265, git-7b13754)
+      # has been LIVE on staging since 2026-06-14, e2e decode-smoke green, zero
+      # decode failures since. Standard files are GA; exotic variants (10-bit /
+      # HDR / multi-image HEIC) decode best-effort. heif is the accept-list ALIAS
+      # of the HEIF container (same libheif decode as heic; pure accept-list
+      # widening, no verify_mime). (avif is also a valid OUTPUT via output_format
+      # — ravif encode.)
       # convert.image is the TRANSCODER leg of the route-aware image "Output"
       # model (FORMAT.md §"Route-aware Output model"): a format_change Output
       # route (output_format != input) runs here. Its options carry
@@ -183,18 +179,17 @@ operation:
             rejected (see convert.image.background).
 
     # gif is animated raster: it converts to a STILL image (first frame / rasterise —
-    # the existing image targets, stable) AND — NEW, planned — to VIDEO (mp4/webm):
-    # the GIF→video transcode (animated GIF → muted, play-once video; ~85-95% smaller
-    # than the GIF; card oEjNe9gT). Split out of convert.image so ONLY gif advertises
-    # the mp4/webm video targets (a jpeg/png input must not show them). The output
+    # the existing image targets, stable) AND to VIDEO (mp4/webm): the GIF→video
+    # transcode (animated GIF → muted, play-once video; ~85-95% smaller than the
+    # GIF; card oEjNe9gT). Split out of convert.image so ONLY gif advertises the
+    # mp4/webm video targets (a jpeg/png input must not show them). The output
     # crosses the media boundary image→video; per codex convergence this stays
     # operation_type=convert (the convert worker's video_convert path owns the ffmpeg
     # mp4/webm encode — NOT a new op, NOT the compression-video worker). mp4/webm are
-    # per_value_availability:planned and flip INDEPENDENTLY (like target_size's
-    # per-format flip) on lambdas worker-proof + API representability + the API's
-    # output-aware billing override (convert.image_gif→video is video-class encode
-    # work, NOT a cheap image transcode — the API must not price it as convert.image;
-    # API owns that, ticket 0Z4zunCr). Planned-first anti-regression (image-options §2.5).
+    # now STABLE (flipped planned→stable in v2.114.0 #258 on lambdas worker-proof);
+    # the API applies an output-aware billing override (convert.image_gif→video is
+    # video-class encode work, NOT a cheap image transcode — priced as video, not
+    # convert.image; API owns that, ticket 0Z4zunCr).
     image_gif:
       mimes:
         - image/gif
@@ -232,16 +227,12 @@ operation:
             Background colour as a 6-digit hex (`#RRGGBB`) for a transparent GIF
             flattened to JPEG (alpha-flatten). HEX ONLY — a non-hex value is
             rejected (see convert.image.background).
-        metadata:
-          type: enum
-          values: [strip, keep]
-          default: strip
-          availability: planned
-          honored_on: [format_change]
-          description: >-
-            Metadata handling for the still-image targets. `planned` — metadata is
-            not yet preserved across a format change. The video targets carry no
-            EXIF/IPTC/XMP.
+        # metadata REMOVED 2026-06-30 (hub honesty decision; won't-do): the GIF INPUT
+        # carries no standard EXIF/IPTC/XMP/ICC, so "preserve metadata across the
+        # format change" has nothing to preserve (colour is already handled by
+        # color_profile=keep's sRGB bake). The video targets carry no metadata either.
+        # (convert.image — a real raster group — keeps its metadata option; only the
+        # GIF-input group's metadata was a phantom.)
         width:
           type: integer
           min: 1
@@ -330,22 +321,28 @@ operation:
       options:
         output_format:
           type: enum
-          values: [mp4, webm, ogg, gif]
+          values: [mp4, webm, ogg, gif, mov, mkv]
           required: true
           # The video codec is DETERMINED by the target container, NOT a caller
           # choice: the convert-video worker hard-wires it per container
-          # (mp4 -> H.264/libx264, webm -> VP9, ogg -> Theora, gif -> palette;
-          # lambdas-confirmed video_convert.rs). The former `codec` option
-          # (enum h264/h265/vp9/av1) was a SILENT NO-OP — the worker never read
-          # it — so it was removed (honesty pass, 2026-06-20). To choose a codec,
-          # use compress.video (which has a real, worker-honored `codec`).
-          description: "Target format. The video codec is fixed by the container (mp4->H.264, webm->VP9, ogg->Theora, gif->palette) — not caller-selectable."
+          # (mp4 -> H.264/libx264, webm -> VP9, ogg -> Theora, gif -> palette,
+          # mov -> H.264/libx264, mkv -> H.264/libx264; lambdas-confirmed
+          # video_convert.rs). mov + mkv added 2026-06-30 on the lambdas staging proof
+          # (operation-convert #287, prove-convert-video-formats-staging.sh 2/2 PASS:
+          # mp4->mov [Content-Type video/quicktime, vcodec h264] + mp4->mkv
+          # [video/x-matroska, vcodec h264], real re-encodes, container-by-extension).
+          # Added STABLE — no per_value gating, matching the rest of this enum (the
+          # proof is in hand; they are h264 in a different container, same codec as the
+          # already-GA mp4). The former `codec` option (enum h264/h265/vp9/av1) was a
+          # SILENT NO-OP — the worker never read it — so it was removed (honesty pass,
+          # 2026-06-20). To choose a codec, use compress.video (real worker-honored `codec`).
+          description: "Target format. The video codec is fixed by the container (mp4->H.264, webm->VP9, ogg->Theora, gif->palette, mov->H.264, mkv->H.264) — not caller-selectable."
         crf:
           type: integer
           min: 0
           max: 51
           default: 23
-          depends_on: { output_format: [mp4, webm, ogg] }
+          depends_on: { output_format: [mp4, webm, ogg, mov, mkv] }
           # Renamed `quality` -> `crf` (2026-06-20) to match compress.video.crf
           # and stop the misnomer: this is a Constant Rate Factor (0=best/lossless,
           # 51=worst), the INVERSE of convert.image.quality (1-100, higher=better).
@@ -365,7 +362,7 @@ operation:
             Trim from beginning in seconds (absent = from the start). The clip
             is cut before transcoding — the user's "trim a video then make a GIF"
             path. The kept clip is [`trim_start`, input_duration − `trim_end`]. Live
-            for all video outputs (gif/mp4/webm/ogg).
+            for all video outputs.
         trim_end:
           type: float
           min: 0