@giveitsmaller/contracts 0.73.0 → 0.76.0

package/operations/schemas/compress.yaml

@@ -191,15 +191,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
@@ -324,15 +332,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 +411,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 +502,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 +666,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 +836,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.
@@ -873,15 +905,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 +1001,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 +1128,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 +1180,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 +1245,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 +1307,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

package/operations/schemas/convert.yaml

@@ -352,6 +352,17 @@ operation:
             NOT applicable to a `gif` output (frame extraction has no CRF). An explicit
             `crf` on a `gif` output is rejected as `invalid_options` at workflow-create
             (the API enforces this `depends_on`); FE/SDK prune it pre-submit.
+            Left at 23 (the default) when converting an MP4 to MOV and the
+            streams can be carried over as they are, the video is copied without
+            re-encoding, so its quality is unchanged. Choose any other value to
+            force a re-encode.
+          # AUTHOR NOTES (rFBKrheN, 2026-09-24): a value EQUAL to the default is
+          # read as defaulted — the contract's own proxy (FORMAT.md per-class drop
+          # rule; api PerClassOptionAvailabilityResolver::wasChosenByTheCaller),
+          # because the SDKs and the frontend materialise every default. lambdas
+          # #439 implements the stream-copy (MP4 -> MOV only: MOV is not a
+          # convert.video INPUT). A caller who truly wants a re-encode
+          # at exactly 23 cannot express it; accepted, since the copy is lossless.
         trim_start:
           type: float
           min: 0

package/operations/schemas/merge.yaml

@@ -41,7 +41,13 @@ operation:
           max: 5000
           default: 500
           depends_on: { output_type: gif }
-          description: "Milliseconds between frames"
+          # GIF stores frame delays in centiseconds (DkucstQG, lambdas MSG
+          # 482596c7): 15 ms alternates 20/10 per frame on prod ffmpeg 7.1.1 today;
+          # lambdas KbmfS94r rounds uniformly to the nearest 10 ms. Deliberately NOT
+          # `multipleOf: 10` — that would 422 values accepted today.
+          description: >-
+            Milliseconds between frames. GIF timing has a 10 ms resolution, so use
+            a multiple of 10 — other values cannot be shown exactly.
         loop_count:
           type: integer
           min: 0