@giveitsmaller/contracts 0.73.0 → 0.78.0

package/operations/schemas/compress.yaml

@@ -83,11 +83,14 @@ operation:
     #     SVG (SVGO) re-encode from pixels so `keep` is NOT in their enum (worker
     #     would reject it). metadata `all` (strip) is the universal default.
     #
-    # Still availability:planned (ANTI-REGRESSION — no stable-flip until worker-
-    # proven; plan §2.5):
-    #   lossy (png) -> palette quantization (pngquant/imagequant-class); planned +
-    #     licensing-gated by the lambdas spike — do NOT stable-flip until that
-    #     confirms a permissive path.
+    # lossy (png) -> palette quantization (imagequant via libcaesium): STABLE
+    #   (owner decision 2026-09-24 21:20, option B on lambdas card 4azmqbm6). It
+    #   was already what production served: the worker never sets
+    #   `png.optimize`, so libcaesium 0.20.0 takes `lossy()` on EVERY PNG compress
+    #   (png.rs compress_in_memory) and the lossless oxipng path is unreachable.
+    #   This text previously called it planned and licensing-gated; the owner
+    #   accepts the licensing reading (imagequant GPL-3, server-side use only —
+    #   see the image_png provenance note below).
     image_jpeg:
       mimes:
         - image/jpeg
@@ -191,15 +194,23 @@ operation:
           per_value_availability:
             auto:     { availability: planned }
             smallest: { availability: planned }
+          # AUTHOR NOTES (moved out of the user-facing description, ewOlw35Z,
+          # 2026-09-23 — user copy must not point at FORMAT.md). Preserved verbatim:
+          #   Output format. original = keep input format (default); webp = recompress to 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.
           description: >-
             Output format. original = keep input format (default); webp = recompress to
             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.
+            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.
         lossless:
           type: boolean
           default: false
@@ -285,14 +296,22 @@ operation:
           max: 100
           default: 80
           honored_on: [same_format]
+          # AUTHOR NOTES (4azmqbm6, 2026-09-24). The old text said `quality: 100`
+          # keeps the PNG lossless. It never did: libcaesium 0.20.0 png.rs runs
+          # imagequant (`liq.set_quality(0, quality)`, quantize, remap to a
+          # palette) for every value, because the worker never sets
+          # `png.optimize`. A PNG with more than 256 colours therefore loses
+          # colours even at 100. Owner option B keeps that behaviour and states it.
+          # Frontend's "Best-Quality PNG lossless" (BhVwdlhQ) relied on the old
+          # sentence and was told.
           description: >-
-            Compression quality (1-100). For PNG this is the SINGLE lossy/lossless
-            control: `quality` < 100 applies lossy palette quantization (the value is
-            the quantization level), while `quality: 100` keeps the PNG lossless
-            (lossless optimisation only — tune the lossless effort via
-            `optimization_level`). 1 = smallest file, 100 = best quality / lossless.
-            There is no separate lossy/lossless toggle for PNG — it is purely
-            quality-driven.
+            Compression quality (1-100). PNG compression reduces the image to a
+            palette of at most 256 colours at every quality setting; this is what
+            makes PNGs smaller. 1 = smallest file, 100 = closest to the original.
+            No value is guaranteed lossless, including 100: when an image with
+            more than 256 colours (a photo, a gradient) is made smaller, it loses
+            some colour detail. If compressing would not make the file smaller,
+            the original is returned unchanged.
         metadata:
           type: enum
           values: [strip, keep, all]
@@ -315,8 +334,12 @@ operation:
           min: 0
           max: 6
           default: 3
-          honored_on: [same_format]
-          description: "PNG optimization effort (0-6). Higher = smaller file, slower encode. Default 3."
+          honored_on: []   # ACCEPTED BUT INERT (Nqd3TdC6): honoured on no route; FORMAT.md §honored_on
+          # AUTHOR NOTES (4azmqbm6, 2026-09-24): read only by libcaesium's lossless
+          # (oxipng) path, which compress never takes (see `quality`). Kept so a
+          # request that sends it is still accepted; it changes nothing.
+          description: >-
+            Currently has no effect on PNG output: it is accepted and ignored.
         output_format:
           type: enum
           values: [original, webp, auto, smallest]
@@ -324,15 +347,23 @@ operation:
           per_value_availability:
             auto:     { availability: planned }
             smallest: { availability: planned }
+          # AUTHOR NOTES (moved out of the user-facing description, ewOlw35Z,
+          # 2026-09-23 — user copy must not point at FORMAT.md). Preserved verbatim:
+          #   Output format. original = keep input format (default); webp = recompress to 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.
           description: >-
             Output format. original = keep input format (default); webp = recompress to
             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.
+            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.
         width:
           type: integer
           min: 1
@@ -395,10 +426,9 @@ operation:
       # image/heic is intentionally NOT a compress input: compress is decode-only
       # and there is no HEIC encoder, so the worker rejects a declared image/heic
       # (FormatMismatch). heic stays on convert+thumbnail.
-      # WORKER LIMIT (not yet contract-expressible — F3 follow-up): the
-      # compress-image worker caps avif INPUT at 20MB (compression_processor.rs),
-      # below the general image size budget. Per-MIME input-size caps have no
-      # contract vocab today; tracked for the image-size-cap mechanism (F3).
+      # WORKER LIMIT: the compress-image worker caps avif INPUT at 20 MiB
+      # (compression_processor.rs AVIF_MAX_MB), below the general image size
+      # budget. This group's `max_input_size_bytes` declares it.
       mimes:
         - image/avif
       max_output_pixels: 16000000
@@ -487,15 +517,23 @@ operation:
           per_value_availability:
             auto:     { availability: planned }
             smallest: { availability: planned }
+          # AUTHOR NOTES (moved out of the user-facing description, ewOlw35Z,
+          # 2026-09-23 — user copy must not point at FORMAT.md). Preserved verbatim:
+          #   Output format. original = keep input format (default); webp = recompress to 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.
           description: >-
             Output format. original = keep input format (default); webp = recompress to
             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.
+            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.
         width:
           type: integer
           min: 1
@@ -643,15 +681,23 @@ operation:
           per_value_availability:
             auto:     { availability: planned }
             smallest: { availability: planned }
+          # AUTHOR NOTES (moved out of the user-facing description, ewOlw35Z,
+          # 2026-09-23 — user copy must not point at FORMAT.md). Preserved verbatim:
+          #   Output format. original = keep input format (default); webp = recompress to 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.
           description: >-
             Output format. original = keep input format (default); webp = recompress to
             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.
+            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.
         lossless:
           type: boolean
           default: false
@@ -805,31 +851,32 @@ operation:
           per_value_availability:
             auto:     { availability: planned }
             smallest: { availability: planned }
+          # AUTHOR NOTES (moved out of the user-facing description, ewOlw35Z,
+          # 2026-09-23 — frontend shows option descriptions to users). Preserved verbatim:
+          #   Output format. `original` = keep input format — SVG -> SVG optimisation via SVGO.
+          #   **STABLE and working** (restored 2026-07-21, G9O6yrQD; worker-proven on staging job
+          #   019f6aa3-d275-7b10-a5cf-58acc705c7e2 at 24.5% reduction, Form-A attested in lambdas
+          #   #325). It is also the schema `default`, so a bare `compress` on an SVG takes this
+          #   route. Optimisation is **visually preserving, NOT lossless** — SVGO's `preset-default`
+          #   includes `convertPathData`, which rounds path coordinates within a tolerance. NOTE for
+          #   anyone re-reading history here: this value was `planned` from 2026-07-17 to 2026-07-21
+          #   on a false premise, and because the API materializes an omitted default before the
+          #   availability gate (api 4a7a2628), that tag 422'd EVERY website SVG compress at create
+          #   — the workbench does not send `output_format`, so the defaulted path is the only path
+          #   a customer has. A `planned` DEFAULT is therefore never a partial restriction; it is a
+          #   total one. Weigh that before tagging any future default `planned`. `webp` = recompress
+          #   to WebP: **STABLE and working today** — this facade route canonicalizes to the
+          #   `convert` operation (`convert.image_svg` carries its own quality), which is why this
+          #   group is NOT gated at group level. 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.
           description: >-
-            Output format. `original` = keep input format — SVG -> SVG optimisation
-            via SVGO. **STABLE and working** (restored 2026-07-21, G9O6yrQD;
-            worker-proven on staging job 019f6aa3-d275-7b10-a5cf-58acc705c7e2 at
-            24.5% reduction, Form-A attested in lambdas #325). It is also the schema
-            `default`, so a bare `compress` on an SVG takes this route.
-            Optimisation is **visually preserving, NOT lossless** — SVGO's
-            `preset-default` includes `convertPathData`, which rounds path
-            coordinates within a tolerance.
-            NOTE for anyone re-reading history here: this value was `planned` from
-            2026-07-17 to 2026-07-21 on a false premise, and because the API
-            materializes an omitted default before the availability gate (api
-            4a7a2628), that tag 422'd EVERY website SVG compress at create — the
-            workbench does not send `output_format`, so the defaulted path is the
-            only path a customer has. A `planned` DEFAULT is therefore never a
-            partial restriction; it is a total one. Weigh that before tagging any
-            future default `planned`.
-            `webp` = recompress to WebP: **STABLE and working today** — this facade
-            route canonicalizes to the `convert` operation (`convert.image_svg` carries
-            its own quality), which is why this group is NOT gated at group level.
-            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.
+            Output format. `original` (the default) keeps SVG and optimises it; the
+            result looks the same but is not byte-for-byte lossless — path coordinates
+            are rounded within a small tolerance. `webp` converts the image to WebP.
+            `auto` and `smallest` (let the server pick the best or smallest format)
+            are planned and not yet available.
 
     # gif/tiff: raster Resize is engine-proven (both are in thumbnail-images), but
     # the optimiser `lossless` knob is WebP-only — not advertised here.
@@ -846,9 +893,19 @@ operation:
           max: 100
           default: 80
           honored_on: [same_format]
+          # AUTHOR NOTES (IJofpQLI, 2026-09-24): lambdas' proof audit found the
+          # TIFF path (libcaesium 0.20.0 tiff.rs:98-100) takes only the algorithm
+          # and deflate level; quality is not an input, so it is IGNORED for
+          # image/tiff. Stated so the ignore is not silent. The structural fix
+          # (split this group into image_gif + image_tiff, the latter without
+          # quality) changes a group key consumers read, so it waits on a
+          # coordinated decision; the card stays open for it.
           description: >-
             Compression quality (1 = smallest file, 100 = best quality). For animated
             GIF this is honoured but real-world size reduction is typically small.
+            Ignored when a TIFF stays a TIFF: it is re-encoded losslessly, so this
+            setting has no effect on a TIFF output. It does apply when a TIFF is
+            converted to another format (for example WebP).
         metadata:
           type: enum
           values: [strip, keep, all]
@@ -873,15 +930,23 @@ operation:
           per_value_availability:
             auto:     { availability: planned }
             smallest: { availability: planned }
+          # AUTHOR NOTES (moved out of the user-facing description, ewOlw35Z,
+          # 2026-09-23 — user copy must not point at FORMAT.md). Preserved verbatim:
+          #   Output format. original = keep input format (default); webp = recompress to 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.
           description: >-
             Output format. original = keep input format (default); webp = recompress to
             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.
+            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.
         width:
           type: integer
           min: 1
@@ -961,10 +1026,14 @@ operation:
           # convert.audio worker live) so the per_value_availability block is
           # removed => untagged = stable (ADR-0001 §1.4). Values mirror
           # convert.audio.output_format.
+          # AUTHOR NOTES (moved out of the user-facing description, ewOlw35Z,
+          # 2026-09-23 — user copy must not point at FORMAT.md). Preserved verbatim:
+          #   Output audio format. original = keep input format (default, same-format compression).
+          #   Non-`original` values re-target the container/codec via the API "compress+format"
+          #   facade (one canonicalized convert pass); see FORMAT.md.
           description: >-
             Output audio format. original = keep input format (default, same-format
-            compression). Non-`original` values re-target the container/codec via the
-            API "compress+format" facade (one canonicalized convert pass); see FORMAT.md.
+            compression). Other values change the format as part of the same job.
         bitrate:
           type: enum
           value_type: integer
@@ -1084,30 +1153,45 @@ operation:
             mp4:  { availability: planned }
             webm: { availability: planned }
             ogg:  { availability: planned }
+          # AUTHOR NOTES (moved out of the user-facing description, ewOlw35Z,
+          # 2026-09-23 — user copy must not point at FORMAT.md). Preserved verbatim:
+          #   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
+          #   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.
           description: >-
-            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 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.
+            Output container. original = keep the input container (default, same-format
+            compression). Other values change the container as part of the same job, keeping
+            the size cap. 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]
           default: h264
-          description: >
-            Video codec. h264 = widest compatibility, h265/av1 = better
-            compression but slower. The default (h264) is the MP4/MOV standard
-            and is CONTAINER-CONDITIONAL against the RESOLVED output container
-            (the explicit `output_format` if set, else the input container): for
-            a container that cannot carry it (e.g. WebM, which carries VP8/VP9/
-            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 rejected); only a caller-EXPLICIT incompatible codec is rejected.
-            See FORMAT.md "Container-conditional defaults".
+          # AUTHOR NOTES (moved out of the user-facing description, ewOlw35Z,
+          # 2026-09-23 — user copy must not point at FORMAT.md). Preserved verbatim:
+          #   Video codec. h264 = widest compatibility, h265/av1 = better compression but slower.
+          #   The default (h264) is the MP4/MOV standard and is CONTAINER-CONDITIONAL against the
+          #   RESOLVED output container (the explicit `output_format` if set, else the input
+          #   container): for a container that cannot carry it (e.g. WebM, which carries VP8/VP9/
+          #   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 rejected); only a caller-EXPLICIT incompatible codec is
+          #   rejected. See FORMAT.md "Container-conditional defaults".
+          description: >-
+            Video codec. h264 = widest compatibility, h265/av1 = better compression but
+            slower. The default (h264) is the MP4/MOV standard and is CONTAINER-CONDITIONAL
+            against the RESOLVED output container (the explicit `output_format` if set, else
+            the input container): for a container that cannot carry it (e.g. WebM, which
+            carries VP8/VP9/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 rejected); only a
+            caller-EXPLICIT incompatible codec is rejected.
         encoding_mode:
           type: enum
           values: [crf, target_size]
@@ -1121,38 +1205,48 @@ operation:
           # per-value-availability tag: option availability is binary and cannot be
           # output-container-scoped (same cross-axis limitation as
           # compress.audio.bitrate's lossy-output rule). crf is universal. ADR-0023 D8.
-          description: |
-            `crf` = constant quality. `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 two-pass for this container ships.
-
-            🔴 **`crf` DOES NOT MEAN UNCONSTRAINED FILE SIZE. THIS DESCRIPTION USED TO
-            SAY "variable file size" AND THAT WAS FALSE BY OMISSION.** For **mp4/MOV
-            output**, the worker additionally derives a **source-relative peak-bitrate
-            ceiling of roughly 60% of the source video bitrate** (`-maxrate`/`-bufsize`),
-            and **it binds regardless of an explicit `crf`** — constrained-CRF. The `crf`
-            value is still honoured as the **quality ceiling**; the cap adds a peak
-            ceiling on top of it.
-
-            ⚠️ **Scope, because "we cap every video" would be a second false sentence:**
-            the cap is **mp4/MOV only** — WebM/VP9 discards it and skips the probe
-            entirely — and it is **best-effort**, so an unprobeable source gets no cap.
-
-            ⭐ **Why it exists, which is also why the old wording surprised in the wrong
-            direction:** plain CRF alone **INFLATES already-efficient sources** — an
-            efficient HEVC re-encoded to H.264 at CRF 23/25/30 grows. The compress
-            contract is *reduce file size*, so the cap is what makes shrinking reliable.
-            A caller who deliberately pins a low `crf` on an efficient source therefore
-            gets a constrained-CRF transcode rather than a byte-for-byte original: a
-            deliberate, accepted shift.
-
-            🔴 **THIS DESCRIPTION IS BOUND TO THE WORKER, NOT DATED AGAINST IT.**
-            `tests/test_bitrate_cap_disclosure_matches_the_worker.py` reads
-            `compression_lambdas` at `origin/main` and fails if the cap stops
-            being source-relative, stops being mp4/MOV-only, or stops deriving
-            from a source probe. **An as-of date would make a superseded
-            sentence look deliberate**; a gate makes it go red instead.
+          # AUTHOR NOTES (moved out of the user-facing description, ewOlw35Z,
+          # 2026-09-23 — frontend shows option descriptions to users). Preserved verbatim:
+          #   `crf` = constant quality. `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 two-pass for this container ships.
+          #
+          #   🔴 **`crf` DOES NOT MEAN UNCONSTRAINED FILE SIZE. THIS DESCRIPTION USED TO
+          #   SAY "variable file size" AND THAT WAS FALSE BY OMISSION.** For **mp4/MOV
+          #   output**, the worker additionally derives a **source-relative peak-bitrate
+          #   ceiling of roughly 60% of the source video bitrate** (`-maxrate`/`-bufsize`),
+          #   and **it binds regardless of an explicit `crf`** — constrained-CRF. The `crf`
+          #   value is still honoured as the **quality ceiling**; the cap adds a peak
+          #   ceiling on top of it.
+          #
+          #   ⚠️ **Scope, because "we cap every video" would be a second false sentence:**
+          #   the cap is **mp4/MOV only** — WebM/VP9 discards it and skips the probe
+          #   entirely — and it is **best-effort**, so an unprobeable source gets no cap.
+          #
+          #   ⭐ **Why it exists, which is also why the old wording surprised in the wrong
+          #   direction:** plain CRF alone **INFLATES already-efficient sources** — an
+          #   efficient HEVC re-encoded to H.264 at CRF 23/25/30 grows. The compress
+          #   contract is *reduce file size*, so the cap is what makes shrinking reliable.
+          #   A caller who deliberately pins a low `crf` on an efficient source therefore
+          #   gets a constrained-CRF transcode rather than a byte-for-byte original: a
+          #   deliberate, accepted shift.
+          #
+          #   🔴 **THIS DESCRIPTION IS BOUND TO THE WORKER, NOT DATED AGAINST IT.**
+          #   `tests/test_bitrate_cap_disclosure_matches_the_worker.py` reads
+          #   `compression_lambdas` at `origin/main` and fails if the cap stops
+          #   being source-relative, stops being mp4/MOV-only, or stops deriving
+          #   from a source probe. **An as-of date would make a superseded
+          #   sentence look deliberate**; a gate makes it go red instead.
+          description: >-
+            `crf` = constant quality. `target_size` = aim for a specific output file
+            size (two-pass); available for mp4/MOV output only — for webm/ogg output
+            and long-form video it is refused with `feature_not_available` (use
+            `crf`). With `crf` on mp4/MOV output the file size is still bounded: a
+            source-relative peak-bitrate ceiling (about 60% of the source video
+            bitrate) keeps already-efficient sources from growing. That ceiling is
+            mp4/MOV only and best-effort — it is skipped when the source bitrate
+            cannot be read.
         crf:
           type: integer
           min: 0
@@ -1176,37 +1270,44 @@ operation:
           type: enum
           values: [ultrafast, superfast, veryfast, faster, fast, medium, slow, slower, veryslow]
           default: medium
-          description: |
-            x264/x265 encoder effort. **A SIZE LEVER, CONDITIONALLY** — it moves
-            output size **only while the mp4/MOV peak-bitrate cap is NOT binding.**
-
-            **Measured by `compression_lambdas`, medium vs slow, all else held:**
-
-                crf 30, cap inert    1,220,156 vs 1,144,043 bytes   6.2% apart
-                crf 18, cap binding  2,514,788 vs 2,516,986 bytes   0.09% apart
-
-            🔴 **THE MECHANISM IS MECHANICAL, NOT EMPIRICAL, AND EXPLAINS BOTH ROWS.**
-            In pure CRF the encoder targets constant QUALITY, so a slower preset spends
-            its extra effort producing a **smaller file at the same quality**. Once
-            `-maxrate` binds the encode is rate-limited, so the extra effort can only go
-            into **picture at a fixed size** — an axis a size measurement cannot see.
-
-            ⚠️ **This description previously said `preset` was effort-only and that `crf`
-            was the size lever. That was wrong**, and it was wrong because a 0.09% figure
-            measured on a **cap-binding** clip was generalised into a property of `preset`.
-            **A measurement is not a property until you know what held it.**
-
-            ⇒ **Callers optimising for size:** `crf` is the primary lever; `preset` adds
-            real reduction **only when the cap is not already constraining the encode** —
-            which is exactly the high-`crf`, small-output end. See `encoding_mode` for what
-            the cap is and when it applies.
-
-            ⚠️ **What the extra effort buys once the cap DOES bind is mechanically
-            implied and empirically UNCONFIRMED.** The mechanism says it must go
-            into picture; `compression_lambdas` could not see a difference on 2x
-            crops, but that was **one frame of one 5-second clip**, and preset
-            differences concentrate in high-motion frames that were not
-            deliberately sampled. **Recorded as unestablished, not asserted.**
+          # AUTHOR NOTES (moved out of the user-facing description, ewOlw35Z,
+          # 2026-09-23 — frontend shows option descriptions to users). Preserved verbatim:
+          #   x264/x265 encoder effort. **A SIZE LEVER, CONDITIONALLY** — it moves
+          #   output size **only while the mp4/MOV peak-bitrate cap is NOT binding.**
+          #
+          #   **Measured by `compression_lambdas`, medium vs slow, all else held:**
+          #
+          #       crf 30, cap inert    1,220,156 vs 1,144,043 bytes   6.2% apart
+          #       crf 18, cap binding  2,514,788 vs 2,516,986 bytes   0.09% apart
+          #
+          #   🔴 **THE MECHANISM IS MECHANICAL, NOT EMPIRICAL, AND EXPLAINS BOTH ROWS.**
+          #   In pure CRF the encoder targets constant QUALITY, so a slower preset spends
+          #   its extra effort producing a **smaller file at the same quality**. Once
+          #   `-maxrate` binds the encode is rate-limited, so the extra effort can only go
+          #   into **picture at a fixed size** — an axis a size measurement cannot see.
+          #
+          #   ⚠️ **This description previously said `preset` was effort-only and that `crf`
+          #   was the size lever. That was wrong**, and it was wrong because a 0.09% figure
+          #   measured on a **cap-binding** clip was generalised into a property of `preset`.
+          #   **A measurement is not a property until you know what held it.**
+          #
+          #   ⇒ **Callers optimising for size:** `crf` is the primary lever; `preset` adds
+          #   real reduction **only when the cap is not already constraining the encode** —
+          #   which is exactly the high-`crf`, small-output end. See `encoding_mode` for what
+          #   the cap is and when it applies.
+          #
+          #   ⚠️ **What the extra effort buys once the cap DOES bind is mechanically
+          #   implied and empirically UNCONFIRMED.** The mechanism says it must go
+          #   into picture; `compression_lambdas` could not see a difference on 2x
+          #   crops, but that was **one frame of one 5-second clip**, and preset
+          #   differences concentrate in high-motion frames that were not
+          #   deliberately sampled. **Recorded as unestablished, not asserted.**
+          description: >-
+            Encoder effort for mp4/MOV output (x264/x265); other output formats
+            ignore it. Slower presets take longer and can produce a smaller file at
+            the same quality — but only while the peak-bitrate ceiling described
+            under `encoding_mode` is not already limiting the output. For size,
+            `crf` is the main lever.
         width:
           type: integer
           min: 2
@@ -1231,31 +1332,48 @@ operation:
         faststart:
           type: boolean
           default: true
-          description: >
-            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".
+          # AUTHOR NOTES (moved out of the user-facing description, ewOlw35Z,
+          # 2026-09-23 — user copy must not point at FORMAT.md). Preserved verbatim:
+          #   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".
+          description: >-
+            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.
         audio_codec:
           type: enum
           values: [aac, opus, vorbis, copy]
           default: copy
-          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`: 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".
+          # AUTHOR NOTES (moved out of the user-facing description, ewOlw35Z,
+          # 2026-09-23 — user copy must not point at FORMAT.md). Preserved verbatim:
+          #   Audio codec. copy = passthrough (keep the source stream as-is; re-encode only on
+          #   explicit request) — aac/opus/vorbis re-encode. 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".
+          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`: 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.
         audio_bitrate:
           type: enum
           value_type: integer