@giveitsmaller/contracts 0.40.0 → 0.42.0

package/operations/schemas/compress.yaml

@@ -100,30 +100,30 @@ operation:
           honored_on: [same_format]
           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.
+            `quality` mode (default); in `target_size` mode the quality is chosen
+            automatically to hit the size budget, 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.
+            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.
         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.
+            Target output size in bytes (min 1024 = 1 KiB). The encoder searches for
+            the highest quality that lands at or under this size; if the target can't
+            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`.
         metadata:
           type: enum
           values: [strip, keep, all]
@@ -132,54 +132,47 @@ operation:
             all: { availability: deprecated }
           honored_on: [same_format]
           description: >-
-            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). `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.
+            Metadata handling. `strip` = remove all EXIF/IPTC/XMP (default). `keep` =
+            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:
-            # 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).
+            # 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: >-
-            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.
+            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).
         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."
+          description: "Enable progressive JPEG rendering (a low-quality preview renders first, then refines). JPEG only."
         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.
+            `420` (4:2:0) = smallest, chroma at quarter resolution (typical for web
+            photos); `422` (4:2:2) = half horizontal resolution; `444` (4:4:4) = full
+            chroma (largest, best for sharp colour edges / text). JPEG only.
+            INCOMPATIBLE with `lossless` (any chroma value): a lossless JPEG copies the
+            existing coefficients and cannot resample chroma.
         output_format:
           type: enum
           values: [original, webp, auto, smallest]
@@ -189,45 +182,39 @@ operation:
             smallest: { availability: planned }
           description: >-
             Output format. original = keep input format (default); webp = recompress to
-            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.
-            `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.
+            WebP. Concrete format changes (jpeg/png/avif/gif/tiff) are handled by the
+            convert operation. `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, and stay `planned` until supported. 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). Only in `quality` mode — incompatible with
-            `target_size` (the byte-budget loop is inherently lossy). Optimiser
-            (same_format) route only.
+            Lossless JPEG re-optimisation: re-packs the file WITHOUT re-encoding the
+            pixels — no quality loss (it cannot recover detail a lossy JPEG already
+            lost). Only in `quality` mode — incompatible with `target_size` (hitting a
+            byte budget is inherently lossy).
         width:
           type: integer
           min: 1
           max: 16384
           honored_on: [same_format, format_change]
           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 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.
+            Target width in pixels (1-16384; width × height must not exceed the
+            group's maximum output area). Resizes the image as part of the operation
+            (one transformed output, replacing the source). Optional; omit to keep the
+            source dimensions.
         height:
           type: integer
           min: 1
           max: 16384
           honored_on: [same_format, format_change]
-          description: "Resize-inside-Output: target height in pixels (1-16384; width*height <= max_output_pixels). Resize replaces the image (one output). Optional — see `width`."
+          description: "Target height in pixels (1-16384; width × height within the group's max output area). Resizes the image (one output). Optional — see `width`."
         fit:
           type: enum
           values: [max, crop, scale]
@@ -235,12 +222,11 @@ operation:
           depends_on: { width: set, height: set, logic: or }
           honored_on: [same_format, format_change]
           description: >-
-            Resize mode. `max` (default) = fit within bounds, preserving aspect ratio
-            and NEVER upscaling — it caps at the source dimensions. This IS the
-            "no-enlarge" behaviour (there is no separate `no_enlarge` flag — the
-            worker has no such key). `crop`/`scale` = exact dimensions (`scale`
-            deliberately enlarges past source). Applies only when width or height is
-            set, on whichever Output route runs.
+            Resize mode. `max` (default) = fit within the given bounds, preserving
+            aspect ratio and never upscaling (caps at the source dimensions — this is
+            the "no-enlarge" behaviour). `crop`/`scale` = exact dimensions (`scale`
+            deliberately enlarges past the source). Applies only when width or height
+            is set.
         color_profile:
           type: enum
           values: [keep, srgb, strip]
@@ -248,26 +234,21 @@ operation:
           availability: planned
           honored_on: [same_format, format_change]
           description: >-
-            ICC colour-profile handling — its OWN control, DECOUPLED from `metadata`
-            (stripping metadata must NOT silently shift colours; that coupling is the
-            correctness bug this fixes). `keep` (default) = preserve the embedded
-            profile; `srgb` = convert to sRGB (also handles CMYK→sRGB); `strip` = drop
-            the profile (smallest — only when the consumer manages colour itself).
-            `planned` — the worker does not yet honour it (today the default strips ICC
-            during metadata-strip; the fix preserves it). Applies on BOTH Output routes
-            (optimiser preserves; transcoder preserves/converts). Worker-proven flip.
+            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.
         auto_orient:
           type: boolean
           default: true
-          availability: planned
           honored_on: [same_format, format_change]
           description: >-
             Bake EXIF orientation into the pixels (honour the camera/device rotation
             tag) so the output displays upright everywhere, then drop the now-redundant
-            orientation tag. `planned` — a restored control (was removed): the worker
-            must apply the EXIF-orientation transform before encode on both Output
-            routes. Default `true` (a behaviour change, proven planned-first). No-op for
-            inputs without an orientation tag.
+            orientation tag. Default `true`; no-op for inputs without an orientation
+            tag. On an already-rotated image the pixels are re-encoded (near-lossless),
+            which can drop other (non-orientation) metadata even with `metadata: keep`.
 
     image_png:
       mimes:
@@ -289,40 +270,38 @@ operation:
             all: { availability: deprecated }
           honored_on: [same_format]
           description: >-
-            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). `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.
+            Metadata handling. `strip` = remove all EXIF/IPTC/XMP (default). `keep` =
+            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:
-            # 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).
+            # 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: >-
-            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.
+            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).
         optimization_level:
           type: integer
           min: 0
           max: 6
           default: 3
           honored_on: [same_format]
-          description: "PNG optimization effort (0-6, oxipng). Higher = smaller file, slower encode. Default 3. Optimiser (same_format) route."
+          description: "PNG optimization effort (0-6). Higher = smaller file, slower encode. Default 3."
         output_format:
           type: enum
           values: [original, webp, auto, smallest]
@@ -332,43 +311,37 @@ operation:
             smallest: { availability: planned }
           description: >-
             Output format. original = keep input format (default); webp = recompress to
-            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.
-            `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.
+            WebP. Concrete format changes (jpeg/png/avif/gif/tiff) are handled by the
+            convert operation. `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, and stay `planned` until supported. See
+            FORMAT.md.
         lossy:
           type: boolean
           default: false
           availability: planned
           honored_on: [same_format]
           description: >-
-            Lossy PNG palette quantization (pngquant/imagequant-class) — a large
-            saving for flat-colour PNGs. `planned` AND LICENSING-GATED: do not
-            stable-flip until the lambdas licensing spike confirms a permissive
-            quantizer path (libimagequant/pngquant is GPL-or-commercial). Optimiser
-            (same_format) route only.
+            Lossy PNG palette quantization — a large saving for flat-colour PNGs.
+            `planned` — not yet supported.
         width:
           type: integer
           min: 1
           max: 16384
           honored_on: [same_format, format_change]
           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 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.
+            Target width in pixels (1-16384; width × height must not exceed the
+            group's maximum output area). Resizes the image as part of the operation
+            (one transformed output, replacing the source). Optional; omit to keep the
+            source dimensions.
         height:
           type: integer
           min: 1
           max: 16384
           honored_on: [same_format, format_change]
-          description: "Resize-inside-Output: target height in pixels (1-16384; width*height <= max_output_pixels). Resize replaces the image (one output). Optional — see `width`."
+          description: "Target height in pixels (1-16384; width × height within the group's max output area). Resizes the image (one output). Optional — see `width`."
         fit:
           type: enum
           values: [max, crop, scale]
@@ -376,12 +349,11 @@ operation:
           depends_on: { width: set, height: set, logic: or }
           honored_on: [same_format, format_change]
           description: >-
-            Resize mode. `max` (default) = fit within bounds, preserving aspect ratio
-            and NEVER upscaling — it caps at the source dimensions. This IS the
-            "no-enlarge" behaviour (there is no separate `no_enlarge` flag — the
-            worker has no such key). `crop`/`scale` = exact dimensions (`scale`
-            deliberately enlarges past source). Applies only when width or height is
-            set, on whichever Output route runs.
+            Resize mode. `max` (default) = fit within the given bounds, preserving
+            aspect ratio and never upscaling (caps at the source dimensions — this is
+            the "no-enlarge" behaviour). `crop`/`scale` = exact dimensions (`scale`
+            deliberately enlarges past the source). Applies only when width or height
+            is set.
         color_profile:
           type: enum
           values: [keep, srgb, strip]
@@ -389,26 +361,21 @@ operation:
           availability: planned
           honored_on: [same_format, format_change]
           description: >-
-            ICC colour-profile handling — its OWN control, DECOUPLED from `metadata`
-            (stripping metadata must NOT silently shift colours; that coupling is the
-            correctness bug this fixes). `keep` (default) = preserve the embedded
-            profile; `srgb` = convert to sRGB (also handles CMYK→sRGB); `strip` = drop
-            the profile (smallest — only when the consumer manages colour itself).
-            `planned` — the worker does not yet honour it (today the default strips ICC
-            during metadata-strip; the fix preserves it). Applies on BOTH Output routes
-            (optimiser preserves; transcoder preserves/converts). Worker-proven flip.
+            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.
         auto_orient:
           type: boolean
           default: true
-          availability: planned
           honored_on: [same_format, format_change]
           description: >-
             Bake EXIF orientation into the pixels (honour the camera/device rotation
             tag) so the output displays upright everywhere, then drop the now-redundant
-            orientation tag. `planned` — a restored control (was removed): the worker
-            must apply the EXIF-orientation transform before encode on both Output
-            routes. Default `true` (a behaviour change, proven planned-first). No-op for
-            inputs without an orientation tag.
+            orientation tag. Default `true`; no-op for inputs without an orientation
+            tag. On an already-rotated image the pixels are re-encoded (near-lossless),
+            which can drop other (non-orientation) metadata even with `metadata: keep`.
 
     image_avif:
       availability: beta
@@ -434,31 +401,31 @@ operation:
           honored_on: [same_format]
           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.
+            `quality` mode (default); in `target_size` mode the quality is chosen
+            automatically to hit the size budget, 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.
+            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.
         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.
+            Target output size in bytes (min 1024 = 1 KiB). The encoder searches for
+            the highest quality that lands at or under this size; if the target can't
+            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`.
         metadata:
           type: enum
           values: [strip, all]
@@ -469,16 +436,15 @@ operation:
           description: >-
             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).
+            `strip`). `keep` is NOT offered for AVIF — it is re-encoded from pixels and
+            cannot preserve metadata.
         avif_speed:
           type: integer
           min: 1
           max: 10
           default: 4
           honored_on: [same_format]
-          description: "AVIF encode speed (1-10, ravif). Lower = smaller file, slower encode; higher = faster, larger. Default 4. Optimiser (same_format) route."
+          description: "AVIF encode speed (1-10). Lower = smaller file, slower encode; higher = faster, larger. Default 4."
         output_format:
           type: enum
           values: [original, webp, auto, smallest]
@@ -488,32 +454,29 @@ operation:
             smallest: { availability: planned }
           description: >-
             Output format. original = keep input format (default); webp = recompress to
-            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.
-            `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.
+            WebP. Concrete format changes (jpeg/png/avif/gif/tiff) are handled by the
+            convert operation. `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, and stay `planned` until supported. See
+            FORMAT.md.
         width:
           type: integer
           min: 1
           max: 16384
           honored_on: [same_format, format_change]
           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 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.
+            Target width in pixels (1-16384; width × height must not exceed the
+            group's maximum output area). Resizes the image as part of the operation
+            (one transformed output, replacing the source). Optional; omit to keep the
+            source dimensions.
         height:
           type: integer
           min: 1
           max: 16384
           honored_on: [same_format, format_change]
-          description: "Resize-inside-Output: target height in pixels (1-16384; width*height <= max_output_pixels). Resize replaces the image (one output). Optional — see `width`."
+          description: "Target height in pixels (1-16384; width × height within the group's max output area). Resizes the image (one output). Optional — see `width`."
         fit:
           type: enum
           values: [max, crop, scale]
@@ -521,12 +484,11 @@ operation:
           depends_on: { width: set, height: set, logic: or }
           honored_on: [same_format, format_change]
           description: >-
-            Resize mode. `max` (default) = fit within bounds, preserving aspect ratio
-            and NEVER upscaling — it caps at the source dimensions. This IS the
-            "no-enlarge" behaviour (there is no separate `no_enlarge` flag — the
-            worker has no such key). `crop`/`scale` = exact dimensions (`scale`
-            deliberately enlarges past source). Applies only when width or height is
-            set, on whichever Output route runs.
+            Resize mode. `max` (default) = fit within the given bounds, preserving
+            aspect ratio and never upscaling (caps at the source dimensions — this is
+            the "no-enlarge" behaviour). `crop`/`scale` = exact dimensions (`scale`
+            deliberately enlarges past the source). Applies only when width or height
+            is set.
         color_profile:
           type: enum
           values: [keep, srgb, strip]
@@ -534,26 +496,21 @@ operation:
           availability: planned
           honored_on: [same_format, format_change]
           description: >-
-            ICC colour-profile handling — its OWN control, DECOUPLED from `metadata`
-            (stripping metadata must NOT silently shift colours; that coupling is the
-            correctness bug this fixes). `keep` (default) = preserve the embedded
-            profile; `srgb` = convert to sRGB (also handles CMYK→sRGB); `strip` = drop
-            the profile (smallest — only when the consumer manages colour itself).
-            `planned` — the worker does not yet honour it (today the default strips ICC
-            during metadata-strip; the fix preserves it). Applies on BOTH Output routes
-            (optimiser preserves; transcoder preserves/converts). Worker-proven flip.
+            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.
         auto_orient:
           type: boolean
           default: true
-          availability: planned
           honored_on: [same_format, format_change]
           description: >-
             Bake EXIF orientation into the pixels (honour the camera/device rotation
             tag) so the output displays upright everywhere, then drop the now-redundant
-            orientation tag. `planned` — a restored control (was removed): the worker
-            must apply the EXIF-orientation transform before encode on both Output
-            routes. Default `true` (a behaviour change, proven planned-first). No-op for
-            inputs without an orientation tag.
+            orientation tag. Default `true`; no-op for inputs without an orientation
+            tag. On an already-rotated image the pixels are re-encoded (near-lossless),
+            which can drop other (non-orientation) metadata even with `metadata: keep`.
 
     # 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
@@ -573,30 +530,30 @@ operation:
           honored_on: [same_format]
           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.
+            `quality` mode (default); in `target_size` mode the quality is chosen
+            automatically to hit the size budget, 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.
+            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.
         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.
+            Target output size in bytes (min 1024 = 1 KiB). The encoder searches for
+            the highest quality that lands at or under this size; if the target can't
+            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`.
         metadata:
           type: enum
           values: [strip, keep, all]
@@ -605,33 +562,31 @@ operation:
             all: { availability: deprecated }
           honored_on: [same_format]
           description: >-
-            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). `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.
+            Metadata handling. `strip` = remove all EXIF/IPTC/XMP (default). `keep` =
+            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:
-            # 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).
+            # 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: >-
-            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.
+            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).
         output_format:
           type: enum
           values: [original, webp, auto, smallest]
@@ -641,44 +596,39 @@ operation:
             smallest: { availability: planned }
           description: >-
             Output format. original = keep input format (default); webp = recompress to
-            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.
-            `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.
+            WebP. Concrete format changes (jpeg/png/avif/gif/tiff) are handled by the
+            convert operation. `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, and stay `planned` until supported. 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. Only in `quality` mode — incompatible with
-            `target_size` (the byte-budget loop is inherently lossy). Optimiser
-            (same_format) route only.
+            Encode WebP losslessly: a genuine lossless WebP encode. Note a lossless
+            encode can be LARGER than a lossy one at the same visual quality. Only in
+            `quality` mode — incompatible with `target_size` (hitting a byte budget is
+            inherently lossy).
         width:
           type: integer
           min: 1
           max: 16384
           honored_on: [same_format, format_change]
           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 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.
+            Target width in pixels (1-16384; width × height must not exceed the
+            group's maximum output area). Resizes the image as part of the operation
+            (one transformed output, replacing the source). Optional; omit to keep the
+            source dimensions.
         height:
           type: integer
           min: 1
           max: 16384
           honored_on: [same_format, format_change]
-          description: "Resize-inside-Output: target height in pixels (1-16384; width*height <= max_output_pixels). Resize replaces the image (one output). Optional — see `width`."
+          description: "Target height in pixels (1-16384; width × height within the group's max output area). Resizes the image (one output). Optional — see `width`."
         fit:
           type: enum
           values: [max, crop, scale]
@@ -686,12 +636,11 @@ operation:
           depends_on: { width: set, height: set, logic: or }
           honored_on: [same_format, format_change]
           description: >-
-            Resize mode. `max` (default) = fit within bounds, preserving aspect ratio
-            and NEVER upscaling — it caps at the source dimensions. This IS the
-            "no-enlarge" behaviour (there is no separate `no_enlarge` flag — the
-            worker has no such key). `crop`/`scale` = exact dimensions (`scale`
-            deliberately enlarges past source). Applies only when width or height is
-            set, on whichever Output route runs.
+            Resize mode. `max` (default) = fit within the given bounds, preserving
+            aspect ratio and never upscaling (caps at the source dimensions — this is
+            the "no-enlarge" behaviour). `crop`/`scale` = exact dimensions (`scale`
+            deliberately enlarges past the source). Applies only when width or height
+            is set.
         color_profile:
           type: enum
           values: [keep, srgb, strip]
@@ -699,26 +648,21 @@ operation:
           availability: planned
           honored_on: [same_format, format_change]
           description: >-
-            ICC colour-profile handling — its OWN control, DECOUPLED from `metadata`
-            (stripping metadata must NOT silently shift colours; that coupling is the
-            correctness bug this fixes). `keep` (default) = preserve the embedded
-            profile; `srgb` = convert to sRGB (also handles CMYK→sRGB); `strip` = drop
-            the profile (smallest — only when the consumer manages colour itself).
-            `planned` — the worker does not yet honour it (today the default strips ICC
-            during metadata-strip; the fix preserves it). Applies on BOTH Output routes
-            (optimiser preserves; transcoder preserves/converts). Worker-proven flip.
+            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.
         auto_orient:
           type: boolean
           default: true
-          availability: planned
           honored_on: [same_format, format_change]
           description: >-
             Bake EXIF orientation into the pixels (honour the camera/device rotation
             tag) so the output displays upright everywhere, then drop the now-redundant
-            orientation tag. `planned` — a restored control (was removed): the worker
-            must apply the EXIF-orientation transform before encode on both Output
-            routes. Default `true` (a behaviour change, proven planned-first). No-op for
-            inputs without an orientation tag.
+            orientation tag. Default `true`; no-op for inputs without an orientation
+            tag. On an already-rotated image the pixels are re-encoded (near-lossless),
+            which can drop other (non-orientation) metadata even with `metadata: keep`.
 
     # 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
@@ -744,9 +688,8 @@ operation:
           description: >-
             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).
+            `strip`). `keep` is NOT offered for SVG — optimising the markup cannot
+            preserve a metadata block.
         output_format:
           type: enum
           values: [original, webp, auto, smallest]
@@ -756,10 +699,10 @@ operation:
             smallest: { availability: planned }
           description: >-
             Output format. original = keep input format (default); webp = recompress to
-            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
+            WebP. Concrete format changes are handled by the convert operation. `auto` /
+            `smallest` are PLANNED auto-format directives (the server picks the
+            best/smallest candidate format, reported via the result `mime_type`) —
+            selection strategies, not concrete targets, planned until supported. See
             FORMAT.md.
 
     # gif/tiff: raster Resize is engine-proven (both are in thumbnail-images), but
@@ -778,7 +721,7 @@ operation:
           honored_on: [same_format]
           description: >-
             Compression quality (1 = smallest file, 100 = best quality). For animated
-            GIF the worker honours this but real-world size reduction is typically small.
+            GIF this is honoured but real-world size reduction is typically small.
         metadata:
           type: enum
           values: [strip, keep, all]
@@ -787,33 +730,31 @@ operation:
             all: { availability: deprecated }
           honored_on: [same_format]
           description: >-
-            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). `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.
+            Metadata handling. `strip` = remove all EXIF/IPTC/XMP (default). `keep` =
+            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:
-            # 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).
+            # 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: >-
-            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.
+            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).
         output_format:
           type: enum
           values: [original, webp, auto, smallest]
@@ -823,32 +764,29 @@ operation:
             smallest: { availability: planned }
           description: >-
             Output format. original = keep input format (default); webp = recompress to
-            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.
-            `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.
+            WebP. Concrete format changes (jpeg/png/avif/gif/tiff) are handled by the
+            convert operation. `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, and stay `planned` until supported. See
+            FORMAT.md.
         width:
           type: integer
           min: 1
           max: 16384
           honored_on: [same_format, format_change]
           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 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.
+            Target width in pixels (1-16384; width × height must not exceed the
+            group's maximum output area). Resizes the image as part of the operation
+            (one transformed output, replacing the source). Optional; omit to keep the
+            source dimensions.
         height:
           type: integer
           min: 1
           max: 16384
           honored_on: [same_format, format_change]
-          description: "Resize-inside-Output: target height in pixels (1-16384; width*height <= max_output_pixels). Resize replaces the image (one output). Optional — see `width`."
+          description: "Target height in pixels (1-16384; width × height within the group's max output area). Resizes the image (one output). Optional — see `width`."
         fit:
           type: enum
           values: [max, crop, scale]
@@ -856,12 +794,11 @@ operation:
           depends_on: { width: set, height: set, logic: or }
           honored_on: [same_format, format_change]
           description: >-
-            Resize mode. `max` (default) = fit within bounds, preserving aspect ratio
-            and NEVER upscaling — it caps at the source dimensions. This IS the
-            "no-enlarge" behaviour (there is no separate `no_enlarge` flag — the
-            worker has no such key). `crop`/`scale` = exact dimensions (`scale`
-            deliberately enlarges past source). Applies only when width or height is
-            set, on whichever Output route runs.
+            Resize mode. `max` (default) = fit within the given bounds, preserving
+            aspect ratio and never upscaling (caps at the source dimensions — this is
+            the "no-enlarge" behaviour). `crop`/`scale` = exact dimensions (`scale`
+            deliberately enlarges past the source). Applies only when width or height
+            is set.
         color_profile:
           type: enum
           values: [keep, srgb, strip]
@@ -869,26 +806,21 @@ operation:
           availability: planned
           honored_on: [same_format, format_change]
           description: >-
-            ICC colour-profile handling — its OWN control, DECOUPLED from `metadata`
-            (stripping metadata must NOT silently shift colours; that coupling is the
-            correctness bug this fixes). `keep` (default) = preserve the embedded
-            profile; `srgb` = convert to sRGB (also handles CMYK→sRGB); `strip` = drop
-            the profile (smallest — only when the consumer manages colour itself).
-            `planned` — the worker does not yet honour it (today the default strips ICC
-            during metadata-strip; the fix preserves it). Applies on BOTH Output routes
-            (optimiser preserves; transcoder preserves/converts). Worker-proven flip.
+            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.
         auto_orient:
           type: boolean
           default: true
-          availability: planned
           honored_on: [same_format, format_change]
           description: >-
             Bake EXIF orientation into the pixels (honour the camera/device rotation
             tag) so the output displays upright everywhere, then drop the now-redundant
-            orientation tag. `planned` — a restored control (was removed): the worker
-            must apply the EXIF-orientation transform before encode on both Output
-            routes. Default `true` (a behaviour change, proven planned-first). No-op for
-            inputs without an orientation tag.
+            orientation tag. Default `true`; no-op for inputs without an orientation
+            tag. On an already-rotated image the pixels are re-encoded (near-lossless),
+            which can drop other (non-orientation) metadata even with `metadata: keep`.
 
     audio:
       mimes:
@@ -924,7 +856,7 @@ operation:
             Output bitrate in kbps (CBR/ABR). Applies to lossy OUTPUTS. Only a
             caller-EXPLICIT bitrate against a lossless output is rejected as
             invalid_options (flac/wav have no bitrate target); the `default: 128` is
-            never the basis for a rejection (ADR-0020 D1, carried into ADR-0023 — a default a caller did not set
+            never the basis for a rejection (a default a caller did not set
             is the server's to resolve, and is dropped for a lossless target). The output
             is the input format unless `output_format` re-targets it: with
             `output_format: original` the lossy/lossless distinction follows the input MIME
@@ -953,18 +885,17 @@ operation:
           type: float
           min: 0
           description: >
-            Trim from beginning in seconds (absent = from the start). STABLE
-            (qZI5EK9j) — the compress-audio worker cuts the clip before encoding
-            (input-side ffmpeg `-ss`/`-t`; lambdas PR #259), SAME FROM-END
-            semantic as compress.video / convert / merge: the kept clip is
-            [`trim_start`, input_duration − `trim_end`].
+            Trim from beginning in seconds (absent = from the start). The clip
+            is cut before encoding, with the same from-end semantic as compress.video
+            / convert / merge: the kept clip is [`trim_start`, input_duration −
+            `trim_end`].
         trim_end:
           type: float
           min: 0
           description: >
             Trim from end in seconds (absent = to the end). Removes this many
             seconds from the end; with `trim_start` the kept clip is
-            [`trim_start`, input_duration − `trim_end`]. STABLE — see `trim_start`.
+            [`trim_start`, input_duration − `trim_end`]. See `trim_start`.
 
     video:
       mimes:
@@ -1021,11 +952,11 @@ operation:
             Output container. original = keep the input container (default,
             same-format compression). Non-`original` values re-target the
             container via the API "compress+format" facade (one canonicalized
-            convert-with-size-cap pass); see per_value_availability + ADR-0023 +
-            FORMAT.md. When set, the RESOLVED target container determines the
-            valid codec/audio_codec/faststart sets — an absent/default codec
-            resolves to a container-valid one (e.g. webm -> vp9) and is never
-            rejected; only a caller-EXPLICIT incompatible value is invalid_options.
+            convert-with-size-cap pass); see FORMAT.md. When set, the RESOLVED
+            target container determines the valid codec/audio_codec/faststart
+            sets — an absent/default codec resolves to a container-valid one
+            (e.g. webm -> vp9) and is never rejected; only a caller-EXPLICIT
+            incompatible value is rejected.
         codec:
           type: enum
           values: [h264, h265, vp9, av1]
@@ -1039,9 +970,8 @@ operation:
             AV1) the server resolves a container-valid codec (WebM -> vp9). A
             DEFAULT value is never rejected — including an explicit
             `output_format: webm` left at the default `h264` (resolves to vp9,
-            NOT invalid_options); only a caller-EXPLICIT incompatible codec
-            returns invalid_options. See FORMAT.md "Container-conditional
-            defaults" + ADR-0023 (supersedes ADR-0020).
+            not rejected); only a caller-EXPLICIT incompatible codec is rejected.
+            See FORMAT.md "Container-conditional defaults".
         encoding_mode:
           type: enum
           values: [crf, target_size]
@@ -1059,7 +989,7 @@ operation:
             crf = constant quality (variable file size). target_size = constrained
             output file size (two-pass). target_size is LIVE for mp4/MOV output; for
             webm/ogg output and long-form the server returns `feature_not_available`
-            (use crf there) until VP9 two-pass ships.
+            (use crf there) until two-pass for this container ships.
         crf:
           type: integer
           min: 0
@@ -1075,10 +1005,10 @@ operation:
           # like encoding_mode:target_size — feature_not_available for webm/ogg +
           # long-form until VP9 two-pass ships. min 1MiB (the two-pass 1MiB floor).
           description: >-
-            Target output file size in bytes (min 1MiB). The libx264 two-pass encode
-            lands the output at or under the target (a safety undershoot + audio
-            reserve apply). mp4/MOV output only — webm/ogg + long-form return
-            `feature_not_available` until VP9 two-pass ships.
+            Target output file size in bytes (min 1MiB). A two-pass encode lands the
+            output at or under the target (a safety undershoot + audio reserve apply).
+            mp4/MOV output only — webm/ogg + long-form return `feature_not_available`
+            until two-pass for this container ships.
         preset:
           type: enum
           values: [ultrafast, superfast, veryfast, faster, fast, medium, slow, slower, veryslow]
@@ -1088,12 +1018,12 @@ operation:
           type: integer
           min: 2
           max: 7680
-          description: "Output width in pixels. Must be an EVEN integer >= 2 (yuv420p chroma-subsampling); odd values are rejected as invalid_options by the encoder."
+          description: "Output width in pixels. Must be an even integer ≥ 2; odd values are rejected by the encoder."
         height:
           type: integer
           min: 2
           max: 4320
-          description: "Output height in pixels. Must be an EVEN integer >= 2 (yuv420p chroma-subsampling); odd values are rejected as invalid_options by the encoder."
+          description: "Output height in pixels. Must be an even integer ≥ 2; odd values are rejected by the encoder."
         fit:
           type: enum
           values: [max, crop, scale, pad]
@@ -1109,14 +1039,13 @@ operation:
           type: boolean
           default: true
           description: >
-            Move the MP4/MOV moov atom to start for progressive web playback.
-            MP4/MOV only. CONTAINER-CONDITIONAL against the RESOLVED output
-            container (the explicit `output_format` if set, else the input): the
-            default (true) is silently inapplicable for a container with no moov
-            atom (e.g. WebM) — that is NOT a rejection. Only a caller-EXPLICIT
-            faststart:true on such a container returns invalid_options. See
-            FORMAT.md "Container-conditional defaults" + ADR-0023 (supersedes
-            ADR-0020).
+            Move the MP4/MOV moov atom to the front so the file starts playing
+            before it is fully downloaded (progressive web playback). MP4/MOV only.
+            CONTAINER-CONDITIONAL against the RESOLVED output container (the explicit
+            `output_format` if set, else the input): the default (true) is silently
+            inapplicable for a container with no moov atom (e.g. WebM) — that is NOT a
+            rejection. Only a caller-EXPLICIT faststart:true on such a container is
+            rejected. See FORMAT.md "Container-conditional defaults".
         audio_codec:
           type: enum
           values: [aac, opus, vorbis, copy]
@@ -1124,18 +1053,16 @@ operation:
           description: >
             Audio codec. copy = passthrough (keep the source stream as-is;
             re-encode only on explicit request) — aac/opus/vorbis re-encode.
-            Default is `copy` (ADR-0020 D7, carried into ADR-0023): on the
-            same-container path (`output_format` original/absent) the source
-            stream is already container-compatible, so copy is safe. When
-            `output_format` RE-TARGETS the container, an absent/default
-            audio_codec resolves to a container-valid codec via the facade
-            (e.g. webm -> opus), NOT a blind copy of an incompatible stream — a
-            DEFAULT is never rejected (the exact per-container resolution, incl.
-            ogg vorbis-vs-opus, is an output_format stable-flip prerequisite,
-            ADR-0023 D5). A caller-EXPLICIT codec the resolved container cannot
-            carry (e.g. aac on a webm target) returns invalid_options. See
-            FORMAT.md "Container-conditional defaults" + ADR-0023 (supersedes
-            ADR-0020).
+            Default is `copy`: on the same-container path (`output_format`
+            original/absent) the source stream is already container-compatible,
+            so copy is safe. When `output_format` RE-TARGETS the container, an
+            absent/default audio_codec resolves to a container-valid codec via the
+            facade (e.g. webm -> opus), NOT a blind copy of an incompatible stream
+            — a DEFAULT is never rejected (the exact per-container resolution,
+            incl. ogg vorbis-vs-opus, is an output_format stable-flip
+            prerequisite). A caller-EXPLICIT codec the resolved container cannot
+            carry (e.g. aac on a webm target) is rejected. See FORMAT.md
+            "Container-conditional defaults".
         audio_bitrate:
           type: enum
           value_type: integer
@@ -1152,21 +1079,17 @@ operation:
           description: >
             Audio track bitrate in kbps. Only valid with an explicit re-encode
             audio_codec (aac/opus/vorbis): an explicit audio_bitrate with
-            audio_codec `copy`/omitted is rejected as `invalid_options` at
-            workflow-create (the API enforces this `depends_on`); copy preserves
-            the source bitrate. FE/SDK also prune it pre-submit. No default: a
-            bitrate is only meaningful on an explicit re-encode (matches the
-            worker, which applies none).
+            audio_codec `copy`/omitted is rejected; copy preserves the source
+            bitrate. No default: a bitrate is only meaningful on an explicit
+            re-encode.
         trim_start:
           type: float
           min: 0
           description: >
-            Trim from beginning in seconds (absent = from the start). STABLE
-            (qZI5EK9j) — the compress-video worker cuts the clip before encoding
-            (input-side ffmpeg `-ss`/`-t`; lambdas PR #258), SAME FROM-END
-            semantic as convert/merge: the kept clip is [`trim_start`,
-            input_duration − `trim_end`]. SHORT-FORM only — for long-form video
-            the server returns `feature_not_available` (trim a short clip, or
+            Trim from beginning in seconds (absent = from the start). The clip
+            is cut before encoding, with the same from-end semantic as convert/merge:
+            the kept clip is [`trim_start`, input_duration − `trim_end`]. SHORT-FORM
+            only — for long-form video this is not supported (trim a short clip, or
             chain a `split`); see the compress.video.trim.longform constraint.
         trim_end:
           type: float
@@ -1174,8 +1097,8 @@ operation:
           description: >
             Trim from end in seconds (absent = to the end). Removes this many
             seconds from the end; with `trim_start` the kept clip is
-            [`trim_start`, input_duration − `trim_end`]. STABLE — see
-            `trim_start` (short-form only; long-form → `feature_not_available`).
+            [`trim_start`, input_duration − `trim_end`]. See `trim_start`
+            (short-form only; long-form is not supported).
 
     document_pdf:
       mimes:
@@ -1198,39 +1121,39 @@ operation:
           min: 1
           max: 100
           default: 50
-          description: "Compression quality (1 = smallest, 100 = best). Maps to a Ghostscript preset. Overridden by `profile` when that is set."
+          description: "Compression quality (1 = smallest, 100 = best). Maps to a compression preset. Overridden by `profile` when that is set."
         profile:
           type: enum
           values: [screen, ebook, printer, prepress]
           description: >-
-            Ghostscript optimization preset, pinned directly (overrides the
-            quality→preset mapping). screen = lowest-res / smallest, ebook = mid,
-            printer = 300dpi, prepress = print-production. Optional — omit to let
-            `quality` drive the preset.
+            Compression preset, pinned directly (overrides the quality→preset
+            mapping). screen = lowest-res / smallest, ebook = mid, printer =
+            300dpi, prepress = print-production. Optional — omit to let `quality`
+            drive the preset.
         grayscale:
           type: boolean
           default: false
-          description: "Convert all images to grayscale (smaller output; discards colour). Worker-honored."
+          description: "Convert all images to grayscale (smaller output; discards colour)."
         image_dpi:
           type: integer
           min: 72
           max: 600
-          description: "Downsample images above this DPI (72–600 inclusive). Omit to keep the worker's DPI analysis. Out-of-range is rejected as invalid_options."
+          description: "Downsample images above this DPI (72–600 inclusive). Omit to use automatic DPI analysis. Out-of-range is rejected."
         colorspace:
           type: enum
           values: [unchanged, rgb, cmyk, grayscale]
           default: unchanged
           availability: planned
-          description: "Output color space. `planned` — not yet read by the worker (use `grayscale` for grayscale conversion)."
+          description: "Output color space. `planned` — not yet supported (use `grayscale` for grayscale conversion)."
         pages:
           type: string
           availability: planned
-          description: "Page selection (e.g. '1-5,8,10-12'). Omit to keep all pages. `planned` — not yet read by the worker."
+          description: "Page selection (e.g. '1-5,8,10-12'). Omit to keep all pages. `planned` — not yet supported."
         flatten_forms:
           type: boolean
           default: false
           availability: planned
-          description: "Flatten interactive form fields into static content. `planned` — not yet read by the worker."
+          description: "Flatten interactive form fields into static content. `planned` — not yet supported."
 
     document_office:
       mimes:
@@ -1245,29 +1168,29 @@ operation:
           min: 1
           max: 100
           default: 50
-          description: "Compression quality (1 = smallest, 100 = best). The only worker-honored document option today."
+          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 read by the worker (use `quality`)."
+          description: "Recompress embedded images at this quality level (1 = smallest, 100 = best). `planned` — not yet supported (use `quality`)."
         strip_macros:
           type: boolean
           default: true
           availability: planned
-          description: "Remove VBA macros and ActiveX controls. `planned` — not yet read by the worker."
+          description: "Remove VBA macros and ActiveX controls. `planned` — not yet supported."
         strip_hidden_data:
           type: boolean
           default: true
           availability: planned
-          description: "Remove revisions, comments, personal info, hidden rows/columns, and speaker notes. `planned` — not yet read by the worker."
+          description: "Remove revisions, comments, personal info, hidden rows/columns, and speaker notes. `planned` — not yet supported."
         strip_unused_fonts:
           type: boolean
           default: false
           availability: planned
-          description: "Remove embedded fonts not referenced in the document. Risk: may affect rendering on systems without the font installed. `planned` — not yet read by the worker."
+          description: "Remove embedded fonts not referenced in the document. Risk: may affect rendering on systems without the font installed. `planned` — not yet supported."
 
     document_odf:
       mimes:
@@ -1281,24 +1204,24 @@ operation:
           min: 1
           max: 100
           default: 50
-          description: "Compression quality (1 = smallest, 100 = best). The only worker-honored document option today."
+          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 read by the worker (use `quality`)."
+          description: "Recompress embedded images at this quality level. `planned` — not yet supported (use `quality`)."
         strip_metadata:
           type: boolean
           default: true
           availability: planned
-          description: "Remove document metadata (author, revision history, comments). `planned` — not yet read by the worker."
+          description: "Remove document metadata (author, revision history, comments). `planned` — not yet supported."
         strip_unused_styles:
           type: boolean
           default: false
           availability: planned
-          description: "Remove style definitions not referenced in document content. `planned` — not yet read by the worker."
+          description: "Remove style definitions not referenced in document content. `planned` — not yet supported."
 
     document_epub:
       mimes:
@@ -1310,21 +1233,21 @@ operation:
           min: 1
           max: 100
           default: 50
-          description: "Compression quality (1 = smallest, 100 = best). The only worker-honored document option today."
+          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 read by the worker (use `quality`)."
+          description: "Recompress embedded images at this quality level. `planned` — not yet supported (use `quality`)."
         font_subsetting:
           type: boolean
           default: true
           availability: planned
-          description: "Subset embedded fonts to only include glyphs used in the document. Significant size reduction for books with large font files. `planned` — not yet read by the worker."
+          description: "Subset embedded fonts to only include glyphs used in the document. Significant size reduction for books with large font files. `planned` — not yet supported."
         strip_unused_css:
           type: boolean
           default: false
           availability: planned
-          description: "Remove CSS rules not referenced by any content. Risk: may affect rendering in some readers. `planned` — not yet read by the worker."
+          description: "Remove CSS rules not referenced by any content. Risk: may affect rendering in some readers. `planned` — not yet supported."