@giveitsmaller/contracts 0.47.0 → 0.50.0

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
@@ -127,14 +123,17 @@ operation:
           type: enum
           values: [keep, srgb, strip]
           default: keep
-          availability: planned
           honored_on: [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. `planned` —
-            not yet supported.
+            (default) = preserve your colours: embed the ICC profile where the target
+            format can 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. The worker reads
+            the input ICC for every accepted raster input (JPEG/PNG/WebP/TIFF, plus
+            HEIF/AVIF via the ISO-BMFF `colr` box).
         auto_orient:
           type: boolean
           default: true
@@ -180,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
@@ -229,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
@@ -272,15 +266,16 @@ operation:
           type: enum
           values: [keep, srgb, strip]
           default: keep
-          availability: planned
           depends_on: { output_format: [jpeg, png, webp, avif, gif, tiff] }
           honored_on: [format_change]
           description: >-
-            Colour-profile handling — `keep` (default) = preserve the embedded colour
-            profile; `srgb` = convert to sRGB; `strip` = drop the profile. `planned`
-            — not yet supported. Scoped to the STILL-IMAGE targets only — the video
-            targets (mp4/webm) carry no colour profile, so this is not accepted for a
-            gif→video output.
+            Colour-profile handling — `keep` (default) = preserve your colours (embed
+            where the target carries an ICC, else bake to sRGB; a no-op for the GIF
+            input itself, which carries no profile); `srgb` = convert to sRGB
+            (transform pixels to sRGB, emit untagged — no embedded ICC, the web
+            default); `strip` = drop the profile. Scoped to the STILL-IMAGE targets
+            only — the video targets (mp4/webm) carry no colour profile, so this is
+            not accepted for a gif→video output.
         auto_orient:
           type: boolean
           default: true
@@ -326,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).
@@ -361,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

package/operations/schemas/image_watermark.yaml

@@ -18,15 +18,14 @@ operation:
     dispatch returns `feature_not_available` (422) until backend
     support ships.
 
-    TIFF (image/tiff) and BMP (image/bmp) bases are likewise advertised
-    as `planned` via the parallel `image_tiff` / `image_bmp` mime_groups.
-    Both formats are already decodable and the worker's encode arms are a
-    cheap add (shared `image`-crate encoders), so each flips to `stable`
-    once its arm ships and is proven. Because watermark output mirrors the
-    input format (`produces: same_as_input`), advertising a base format is
-    only honest when the worker can both decode AND encode it — which
-    holds for TIFF/BMP but not for HEIC/AVIF (no encoder) or SVG (cannot
-    re-emit svg from a rasterised composite); those stay out of scope.
+    TIFF (image/tiff) and BMP (image/bmp) bases are now `stable` too
+    (flipped planned->stable 2026-06-30 on the lambdas staging proof,
+    UANjD38A / #296) via the parallel `image_tiff` / `image_bmp`
+    mime_groups. Because watermark output mirrors the input format
+    (`produces: same_as_input`), advertising a base format is only honest
+    when the worker can both decode AND encode it — which holds for
+    TIFF/BMP but not for HEIC/AVIF (no encoder) or SVG (cannot re-emit svg
+    from a rasterised composite); those stay out of scope.
 
     **Video bases are NOT supported by `image_watermark`.** Use the
     dedicated `video_watermark` operation
@@ -217,12 +216,13 @@ operation:
             width. Aspect ratio preserved. Omit to use the original
             overlay size.
 
-    # TIFF base — separate group because backend support ships in its own
-    # wave: the format is already decodable, but the encode arm (shared
-    # `image`-crate TiffEncoder) is pending. Tagged `planned` until the arm
-    # ships and is proven, then flips to `stable` (cross-repo UANjD38A).
+    # TIFF base — separate group (its backend arm shipped in its own wave).
+    # Now STABLE (flipped 2026-06-30 — see the group comment below).
     image_tiff:
-      availability: planned
+      # planned->stable 2026-06-30 (UANjD38A): lambdas staging-proved the TIFF
+      # image-watermark encode (composited output md5 != base, decodable as TIFF,
+      # PR #296 c664d80; encoder shipped dark in #274). Manifest lists image/tiff in
+      # accepts + outputs.
       mimes:
         - image/tiff
       options:
@@ -289,11 +289,12 @@ operation:
             width. Aspect ratio preserved. Omit to use the original
             overlay size.
 
-    # BMP base — separate group for the same reason as image_tiff: decode
-    # is ready, the encode arm (shared `image`-crate BmpEncoder) is pending.
-    # Tagged `planned` until the arm ships and is proven (cross-repo UANjD38A).
+    # BMP base — separate group for the same reason as image_tiff. Now
+    # STABLE (flipped 2026-06-30 — see the group comment below).
     image_bmp:
-      availability: planned
+      # planned->stable 2026-06-30 (UANjD38A): lambdas staging-proved the BMP
+      # image-watermark encode (composited + decodable as BMP, PR #296 c664d80;
+      # encoder shipped dark in #274). Manifest lists image/bmp in accepts + outputs.
       mimes:
         - image/bmp
       options:

package/operations/schemas/text_watermark.yaml

@@ -15,14 +15,13 @@ operation:
       pattern); rotation default -45° and tile_spacing controls density.
 
     Stable today for image/jpeg, image/png, image/webp inputs. TIFF
-    (image/tiff) and BMP (image/bmp) inputs are advertised as `planned`
-    via the parallel `image_tiff` / `image_bmp` mime_groups — both are
-    already decodable and the worker's encode arms are a cheap add
-    (shared `image`-crate encoders), so each flips to `stable` once its
-    arm ships and is proven. Output mirrors the input format
-    (`produces: same_as_input`), so a format is only advertised when the
-    worker can both decode AND encode it; HEIC/AVIF (no encoder) and SVG
-    (cannot re-emit svg from a rasterised composite) stay out of scope.
+    (image/tiff) and BMP (image/bmp) inputs are now `stable` too (flipped
+    planned->stable 2026-06-30 on the lambdas staging proof, UANjD38A /
+    #296) via the parallel `image_tiff` / `image_bmp` mime_groups. Output
+    mirrors the input format (`produces: same_as_input`), so a format is
+    only advertised when the worker can both decode AND encode it;
+    HEIC/AVIF (no encoder) and SVG (cannot re-emit svg from a rasterised
+    composite) stay out of scope.
   default: false
   input_model: single
   sole_op: true   # bypasses V1 chain validation — must be the only operation in its job (ADR-0025)
@@ -158,14 +157,14 @@ operation:
             `color` already encodes transparency, so opacity is usually
             left at 1.0 and transparency is set via the color hex.
 
-    # TIFF input — separate group because backend support ships in its own
-    # wave: the format is already decodable, but the encode arm (shared
-    # `image`-crate TiffEncoder) is pending. Tagged `planned` until the arm
-    # ships and is proven, then flips to `stable` (cross-repo UANjD38A).
+    # TIFF input — separate group (its backend arm shipped in its own wave).
+    # Now STABLE (flipped 2026-06-30 — see the group comment below).
     # Text-rendering options are format-independent, so the shape mirrors
     # the canonical `image` group exactly.
     image_tiff:
-      availability: planned
+      # planned->stable 2026-06-30 (UANjD38A): lambdas staging-proved the TIFF
+      # text-watermark encode (composited + decodable as TIFF, PR #296 c664d80;
+      # encoder shipped dark in #274). Manifest lists image/tiff in accepts + outputs.
       mimes:
         - image/tiff
       options:
@@ -284,11 +283,12 @@ operation:
             `color` already encodes transparency, so opacity is usually
             left at 1.0 and transparency is set via the color hex.
 
-    # BMP input — separate group for the same reason as image_tiff: decode
-    # is ready, the encode arm (shared `image`-crate BmpEncoder) is pending.
-    # Tagged `planned` until the arm ships and is proven (cross-repo UANjD38A).
+    # BMP input — separate group for the same reason as image_tiff. Now
+    # STABLE (flipped 2026-06-30 — see the group comment below).
     image_bmp:
-      availability: planned
+      # planned->stable 2026-06-30 (UANjD38A): lambdas staging-proved the BMP
+      # text-watermark encode (composited + decodable as BMP, PR #296 c664d80;
+      # encoder shipped dark in #274). Manifest lists image/bmp in accepts + outputs.
       mimes:
         - image/bmp
       options:

package/operations/schemas/thumbnail.yaml

@@ -17,12 +17,12 @@ operation:
         - image/bmp
         - image/avif
         - image/heic
-      per_mime_availability:
-        # avif/heic decode shipped in the thumbnail-image worker via libheif
-        # (lambdas w34Taquf, #210). beta: live + opt-in, shape-stable.
-        # Re-add after the v2.67.0 interim crash-window drop (aYPbNVKD Phase 2).
-        image/avif: { availability: beta }
-        image/heic: { availability: beta }
+      # avif/heic decode in the thumbnail-image worker via libheif (lambdas
+      # w34Taquf, #210) 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 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.
       # Output-area wall (lambdas thumbnail-image MAX_OUTPUT_PIXELS): the FE
       # pre-validates width*height <= max_output_pixels. The per-axis max (16384)
       # is NOT the real limit — e.g. 6000x6000 (36MP) is rejected though each axis
@@ -36,72 +36,20 @@ operation:
           type: integer
           min: 1
           max: 16384
-          required: true
-          description: "Target width in pixels (1-16384; width*height <= 16MP). For image input this is a full resize, not just a small preview."
-        height:
-          type: integer
-          min: 1
-          max: 16384
-          required: true
-          description: "Target height in pixels (1-16384; width*height <= 16MP). For image input this is a full resize, not just a small preview."
-        fit:
-          type: enum
-          values: [max, crop, scale]
-          default: crop
-          description: "Resize mode"
-        format:
-          type: enum
-          values: [jpg, png, webp]
-          default: jpg
-          description: "Output format for the thumbnail"
-        quality:
-          type: integer
-          min: 1
-          max: 100
-          default: 85
-          depends_on: { format: [jpg, webp] }
-          description: "Output quality for lossy thumbnail formats (jpg/webp): higher = better quality, larger file. Ignored for png (lossless)."
-        background:
-          type: string
-          pattern: "^#[0-9a-fA-F]{6}$"
-          depends_on: { format: jpg }
           description: >-
-            Background colour as a 6-digit hex (`#RRGGBB`, e.g. `#ffffff`) for a
-            transparent image (e.g. PNG/WebP with alpha) resized to an opaque JPG
-            thumbnail — the alpha-flatten fill colour. Mirrors
-            convert.image.background. HEX ONLY: a non-hex value (e.g. a CSS named
-            colour) is rejected rather than advertising an inert free-form string.
-            When omitted, transparency is flattened onto white. JPG output only:
-            PNG/WebP keep alpha, so the flatten (and this option) do not apply.
-
-    # SVG input (planned, UANjD38A). SVG is split into its own parallel mime_group
-    # (group-level `availability: planned`, which the API gates -> feature_not_available)
-    # rather than tagged inside the stable `image` group, because per-MIME planned is
-    # advisory/not enforced. SVG rasterises to a bitmap cleanly, so render->resize for
-    # thumbnail is feasible. Flip planned -> stable
-    # (or beta) once the worker proves svg-rasterise input. Shares the `image` group's
-    # option shape (FORMAT.md "Parallel groups").
-    image_svg:
-      availability: planned
-      mimes:
-        - image/svg+xml
-      max_output_pixels: 16000000
-      options:
-        # IMAGE input is a full resizer (Lanczos): width/height accept the
-        # worker's real 1-16384px range (area-capped above) — this op is the
-        # image-resize path, surfaced in the UI as "Resize", not only thumbnails.
-        width:
-          type: integer
-          min: 1
-          max: 16384
-          required: true
-          description: "Target width in pixels (1-16384; width*height <= 16MP). For image input this is a full resize, not just a small preview."
+            Target width in pixels (1-16384; width*height <= 16MP). For image input
+            this is a full resize, not just a small preview. Optional — when omitted
+            the server applies an aspect-preserving default (both omitted → longest
+            edge 320px; only one of width/height provided → the other is derived from
+            the source aspect ratio), so non-square images are never distorted.
         height:
           type: integer
           min: 1
           max: 16384
-          required: true
-          description: "Target height in pixels (1-16384; width*height <= 16MP). For image input this is a full resize, not just a small preview."
+          description: >-
+            Target height in pixels (1-16384; width*height <= 16MP). For image input
+            this is a full resize. Optional — see `width` for the omitted-default
+            (aspect-preserving) behaviour.
         fit:
           type: enum
           values: [max, crop, scale]
@@ -117,8 +65,15 @@ operation:
           min: 1
           max: 100
           default: 85
-          depends_on: { format: [jpg, webp] }
-          description: "Output quality for lossy thumbnail formats (jpg/webp): higher = better quality, larger file. Ignored for png (lossless)."
+          depends_on: { format: [jpg, webp, png] }
+          description: >-
+            Output quality for lossy thumbnail formats (jpg / webp / png): higher =
+            better quality, larger file. For PNG, `quality` < 100 applies lossy palette
+            quantization (imagequant — transparency preserved); `quality: 100` keeps the
+            PNG lossless. Per-format effective default (server-resolved when `quality`
+            is unset, per ADR-0020 D1): PNG → 70 (more aggressive — thumbnails target
+            small files), jpg/webp → 85. The schema `default` is the nominal jpg/webp
+            value (85); the FE shows 70 as the initial PNG slider value.
         background:
           type: string
           pattern: "^#[0-9a-fA-F]{6}$"
@@ -175,14 +130,18 @@ operation:
           type: integer
           min: 1
           max: 16384
-          required: true
-          description: "Target width in pixels (1-16384; width*height <= 16MP). Rounded down to an even number."
+          description: >-
+            Target width in pixels (1-16384; width*height <= 16MP). Rounded down to an
+            even number. Optional — when omitted the server applies an aspect-preserving
+            default (both omitted → longest edge 320px; only one of width/height
+            provided → the other is derived from the source aspect ratio).
         height:
           type: integer
           min: 1
           max: 16384
-          required: true
-          description: "Target height in pixels (1-16384; width*height <= 16MP). Rounded down to an even number."
+          description: >-
+            Target height in pixels (1-16384; width*height <= 16MP). Rounded down to an
+            even number. Optional — see `width` for the omitted-default behaviour.
         fit:
           type: enum
           values: [max, crop, scale]
@@ -237,14 +196,18 @@ operation:
           type: integer
           min: 1
           max: 16384
-          required: true
-          description: "Target width in pixels (1-16384; width*height <= 16MP)."
+          description: >-
+            Target width in pixels (1-16384; width*height <= 16MP). Optional — when
+            omitted the server applies an aspect-preserving default (both omitted →
+            longest edge 320px; only one of width/height provided → the other is
+            derived from the source aspect ratio).
         height:
           type: integer
           min: 1
           max: 16384
-          required: true
-          description: "Target height in pixels (1-16384; width*height <= 16MP)."
+          description: >-
+            Target height in pixels (1-16384; width*height <= 16MP). Optional — see
+            `width` for the omitted-default behaviour.
         fit:
           type: enum
           values: [max, crop, scale]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@giveitsmaller/contracts",
-  "version": "0.47.0",
+  "version": "0.50.0",
   "description": "Generated contract types for GISL (Give It Smaller)",
   "license": "MIT",
   "type": "module",