@giveitsmaller/contracts 0.73.0 → 0.76.0

package/operations/schemas/split.yaml

@@ -66,7 +66,8 @@ operation:
 
     **`precision` flag** (audio + video only): `fast` (default) =
     packet-boundary approximate cuts; `exact` = re-encode-aligned
-    precise cuts. Mime_group scoping is the gate — precision does
+    precise cuts (`planned` — the API refuses it at create until the
+    re-encode path is priced). Mime_group scoping is the gate — precision does
     NOT apply to GIF or PDF (frame extraction is exact and PDF page
     selection is exact by definition).
 
@@ -92,8 +93,9 @@ operation:
       description: |
         Silence-detect cut mode for audio (`mode: silence` —
         server-side silence detection). `beta`: shape-stable + opt-in.
-        The mode ships dark until the API regenerates enum validation
-        to accept `mode: silence`. The `silence` enum value carries a
+        Accepted at workflow-create by any API build that vendors this
+        value, since the validator reads the enum from the vendored
+        schema. The `silence` enum value carries a
         matching `per_value_availability: beta` on `audio.mode`.
 
   mime_groups:
@@ -149,12 +151,17 @@ operation:
           pattern: '^\d+(-\d+)?(,\d+(-\d+)?)*$'
           required: true
           depends_on: { mode: page_range }
-          description: |
-            Page-range expression (e.g. "1-5", "1,3,5-7", "10-20").
-            1-based inclusive. Required when `mode: page_range`.
-            Resolved page count MUST be <= 200 (`invalid_options`
-            422 if exceeded — cross-ref
-            [`WgCqnMRa`](https://trello.com/c/WgCqnMRa)).
+          # AUTHOR NOTES (moved out of the user-facing description, ewOlw35Z,
+          # 2026-09-23 — frontend shows option descriptions to users). Preserved verbatim:
+          #   Page-range expression (e.g. "1-5", "1,3,5-7", "10-20").
+          #   1-based inclusive. Required when `mode: page_range`.
+          #   Resolved page count MUST be <= 200 (`invalid_options`
+          #   422 if exceeded — cross-ref
+          #   [`WgCqnMRa`](https://trello.com/c/WgCqnMRa)).
+          description: >-
+            Pages to extract, e.g. "1-5", "1,3,5-7" or "10-20" — 1-based and
+            inclusive. Required when `mode: page_range`. At most 200 pages;
+            more is refused with `invalid_options`.
 
         page_groups:
           type: integer
@@ -196,6 +203,13 @@ operation:
       # The two `precision` values have genuinely different duration behaviour
       # and the contract has no primitive that can say so:
       #
+      # 🔴 TODAY THE API REFUSES `exact` AT CREATE for every split (audio and
+      # video) — the deliberate "re-encode path not yet priced" gate
+      # (`compression_api` SplitOptionsValidator, reported 2026-09-23, Q8QsYYNn).
+      # So `exact` never reaches a worker, and `per_value_availability` tags it
+      # `planned`. The worker behaviour below is what `exact` WILL do once the
+      # API admits it:
+      #
       #   `exact` computes a time budget from the probed duration and refuses
       #           when it does not fit — WORKER-SIDE, after download and probe
       #           (`processor.rs` reads `probe.duration_secs`), returning a
@@ -247,7 +261,8 @@ operation:
       # ceiling is enforced there — withdrawing `fast` jobs that complete today,
       # which is the direction the SVG incident ran in. A higher number would
       # under-state what `exact` refuses.
-      # ⚠️ AND NEITHER BOUND IS ENFORCED AT CREATE TODAY: both are worker-side,
+      # ⚠️ AND NEITHER DURATION BOUND IS ENFORCED AT CREATE TODAY (`exact` is
+      # refused at create outright, which is not a duration bound): both are worker-side,
       # after the job is accepted, billed and downloaded. Declaring one would MOVE
       # the refusal earlier, which is a real improvement for the value it fits and
       # a real withdrawal for the value it does not.
@@ -368,78 +383,106 @@ operation:
           type: enum
           values: [fast, exact]
           default: fast
+          per_value_availability:
+            # The API refuses `exact` at create for every split — the deliberate
+            # unpriced re-encode gate (Q8QsYYNn). Advertising it as callable
+            # was a silent rejection of a spec-valid value.
+            exact: { availability: planned }
           # Don't use "keyframe" language here — that's video-only;
           # audio drift is packet-boundary.
-          description: |
-            Cut precision. Under `fast`, audio cuts are
-            packet-boundary approximate (drift bounded by codec
-            packet size — typically <= 23ms for AAC, <= 26ms for
-            MP3). Under `exact`, the server re-encodes to align cuts
-            precisely at the requested timestamps (slower, larger
-            output, but sample-accurate).
-
-            🔴 **THE TWO VALUES HAVE DIFFERENT DURATION LIMITS, AND ONLY
-            ONE OF THEM REFUSES.** This is stated here, on the option a
-            caller chooses, because the group declares
-            `input_size_bound: processing_time` and no
-            `max_input_duration` — there is no per-value constraint
-            primitive to carry it.
-
-            ⛔ **NEITHER VALUE GIVES A PRE-FLIGHT SIGNAL. BOTH FAIL AFTER
-            THE JOB IS ACCEPTED AND BILLED.** No duration ceiling is
-            declared on this group, so the API cannot enforce one at
-            create; the worker's own check reads a probe result, which
-            means the input has already been uploaded, accepted and
-            downloaded.
-
-            - **`exact`: refused when its computed time budget does not
-              fit** — but WORKER-SIDE, after download and probe. The job
-              returns a terminal `OperationResult` with `error_code:
-              invalid_options`. ⚠️ It is NOT an HTTP 422 and it is not a
-              create-time rejection: a worker cannot emit a status code.
-              The boundary does not move with `count` — once the cap
-              binds, the per-output term stops mattering.
-            - **`fast` (the default): no boundary and no refusal at
-              all.** Past the point where its deadline saturates, the time
-              budget stops growing while the work does, so the job fails
-              as a **TIMEOUT** rather than with any reason a caller can
-              act on.
-
-            🔴 **TWO LIMITS EXIST AND THE SMALLER ONE BINDS.** The worker
-            carries an internal time budget and the Lambda function
-            carries a platform timeout; **the effective boundary is the
-            LOWER of the two**, and the internal budget sits ABOVE the
-            platform timeout.
-
-            ⇒ **`exact`'s refusal threshold is calibrated to a limit that
-            is not the one that ends the job.** Its check does fire, and
-            fires early — it reads the probe result before any re-encode
-            starts, so a long-but-small input is refused within seconds.
-            But there is a band of inputs it judges FINE which the
-            platform then hard-kills mid-encode, with no named cause. **So
-            `exact` refusing is a reliable signal; `exact` NOT refusing is
-            not a promise the job will finish.**
-
-            ⛔ **NO SECONDS FIGURE IS GIVEN HERE, DELIBERATELY.** v2.205.0
-            published figures keyed to the crate constant — the larger
-            limit, the one that does not bind. The effective number lands
-            only when that derivation settles AND a job is measured near
-            it. **A published number a caller pre-validates against is
-            worse wrong than absent**; the shape above is what a caller can
-            actually act on today, which is: do not rely on either value
-            failing gracefully.
-
-            ⇒ `exact` at least names a cause when it is reached; `fast`
-            never does. **Both are the accept-then-bill-then-fail shape**,
-            which is the very thing this group's `input_size_bound`
-            declaration exists to stop happening silently on the BYTE
-            axis. On the DURATION axis it is stated here and not yet
-            fixed.
-
-            ⚠️ Read from `compression_lambdas` `crates/split`. **NOT
-            measured** — their audio fixtures reach 145 s, a small
-            fraction of any candidate cap, so this describes what the code
-            will do rather than observed behaviour at the boundary.
+          # AUTHOR NOTES (moved out of the user-facing description, ewOlw35Z,
+          # 2026-09-23 — frontend shows option descriptions to users). Preserved verbatim:
+          #   Cut precision. Under `fast`, audio cuts are
+          #   packet-boundary approximate (drift bounded by codec
+          #   packet size — typically <= 23ms for AAC, <= 26ms for
+          #   MP3). Under `exact`, the server re-encodes to align cuts
+          #   precisely at the requested timestamps (slower, larger
+          #   output, but sample-accurate).
+          #
+          #   🔴 **THE TWO VALUES HAVE DIFFERENT DURATION LIMITS, AND ONLY
+          #   ONE OF THEM REFUSES.** This is stated here, on the option a
+          #   caller chooses, because the group declares
+          #   `input_size_bound: processing_time` and no
+          #   `max_input_duration` — there is no per-value constraint
+          #   primitive to carry it.
+          #
+          #   🔴 **TODAY `exact` IS REFUSED AT CREATE** — the API does not
+          #   yet admit it for any split (the re-encode path is not yet
+          #   priced), so it is tagged `planned` and a request carrying it
+          #   is rejected before anything is uploaded, accepted or billed.
+          #   **Everything below about `exact` describes the worker, i.e.
+          #   what it will do once the API admits it.**
+          #
+          #   `exact` is refused at create with `feature_not_available` (422),
+          #   the contract's answer for a `planned` value (api
+          #   SplitOptionsValidator leaves it to the generic planned-option
+          #   gate; SplitAudioActivationCreateTest asserts the error_type).
+          #   A consumer should not send it, as the `planned` tag says.
+          #
+          #   ⛔ **`fast` GIVES NO PRE-FLIGHT SIGNAL, and neither will
+          #   `exact` once admitted: both fail AFTER THE JOB IS ACCEPTED
+          #   AND BILLED.** No duration ceiling is declared on this group,
+          #   so the API cannot enforce one at create; the worker's own
+          #   check reads a probe result, which means the input has already
+          #   been uploaded, accepted and downloaded.
+          #
+          #   - **`exact` (once admitted): refused when its computed time
+          #     budget does not fit** — but WORKER-SIDE, after download and
+          #     probe. The job
+          #     returns a terminal `OperationResult` with `error_code:
+          #     invalid_options`. ⚠️ It is NOT an HTTP 422 and it is not a
+          #     create-time rejection: a worker cannot emit a status code.
+          #     The boundary does not move with `count` — once the cap
+          #     binds, the per-output term stops mattering.
+          #   - **`fast` (the default): no boundary and no refusal at
+          #     all.** Past the point where its deadline saturates, the time
+          #     budget stops growing while the work does, so the job fails
+          #     as a **TIMEOUT** rather than with any reason a caller can
+          #     act on.
+          #
+          #   🔴 **TWO LIMITS EXIST AND THE SMALLER ONE BINDS.** The worker
+          #   carries an internal time budget and the Lambda function
+          #   carries a platform timeout; **the effective boundary is the
+          #   LOWER of the two**, and the internal budget sits ABOVE the
+          #   platform timeout.
+          #
+          #   ⇒ **`exact`'s refusal threshold is calibrated to a limit that
+          #   is not the one that ends the job.** Its check does fire, and
+          #   fires early — it reads the probe result before any re-encode
+          #   starts, so a long-but-small input is refused within seconds.
+          #   But there is a band of inputs it judges FINE which the
+          #   platform then hard-kills mid-encode, with no named cause. **So
+          #   `exact` refusing is a reliable signal; `exact` NOT refusing is
+          #   not a promise the job will finish.**
+          #
+          #   ⛔ **NO SECONDS FIGURE IS GIVEN HERE, DELIBERATELY.** v2.205.0
+          #   published figures keyed to the crate constant — the larger
+          #   limit, the one that does not bind. The effective number lands
+          #   only when that derivation settles AND a job is measured near
+          #   it. **A published number a caller pre-validates against is
+          #   worse wrong than absent**; the shape above is what a caller can
+          #   actually act on today, which is: do not rely on either value
+          #   failing gracefully.
+          #
+          #   ⇒ `exact` (once admitted) at least names a cause when it is
+          #   reached; `fast` never does. **On today's customer path only
+          #   `fast` is the accept-then-bill-then-fail shape**,
+          #   which is the very thing this group's `input_size_bound`
+          #   declaration exists to stop happening silently on the BYTE
+          #   axis. On the DURATION axis it is stated here and not yet
+          #   fixed.
+          #
+          #   ⚠️ Read from `compression_lambdas` `crates/split`. **NOT
+          #   measured** — their audio fixtures reach 145 s, a small
+          #   fraction of any candidate cap, so this describes what the code
+          #   will do rather than observed behaviour at the boundary.
+          description: >-
+            Cut precision. `fast` (default) cuts at packet boundaries, so each cut
+            can drift by a few milliseconds (typically up to about 23 ms for AAC and
+            26 ms for MP3). `exact` re-encodes to cut precisely at the requested
+            timestamps; it is not yet available and is refused when the workflow is
+            created. Very long audio can run out of processing time and fail rather
+            than be refused up front.
 
     # Video base — same three modes + precision + processing_class.
     # Long-form routes to `split-video-fargate` (same OperationType,
@@ -458,9 +501,12 @@ operation:
             max_input_size_bytes: 524288000
             max_output_size_bytes: 524288000
         long_form:
-          # planned -> beta (rcwvUKhI): split-video-fargate worker deployed +
-          # wired on staging but NOT yet proven end-to-end (first customer-path
-          # soak incomplete; 4GB+ speed-up unmeasured; fan-out flag-gated dark).
+          # planned -> beta (rcwvUKhI). Stays beta until a PRODUCTION
+          # `customer_path` run is recorded in availability/prod-verification-
+          # log.yaml; worker-direct staging runs up to 3.99 GiB are in the
+          # staging log as partial evidence only (no environment axis). Fan-out admission is
+          # the API's LONGFORM_FANOUT_ADMISSION_ENABLED, set per environment in
+          # compression_terraform; not restated here.
           # Routes per ADR-0014 §D10 — same split OperationType, dedicated
           # stream-copy segmenter binary (NOT the long-form compress worker).
           availability: beta
@@ -531,6 +577,10 @@ operation:
           type: enum
           values: [fast, exact]
           default: fast
+          per_value_availability:
+            # Refused at create by the API for every split (Q8QsYYNn) as
+            # `feature_not_available`; see the note on `audio.options.precision`.
+            exact: { availability: planned }
           description: |
             Cut precision. Under `fast`, video cuts are keyframe-
             aligned (drift bounded by GOP size — typically up to 1-2

package/operations/schemas/thumbnail.yaml

@@ -66,14 +66,19 @@ operation:
           max: 100
           default: 85
           depends_on: { format: [jpg, webp, png] }
+          # AUTHOR NOTES (moved out of the user-facing description, ewOlw35Z,
+          # 2026-09-23 — frontend shows option descriptions to users). Preserved verbatim:
+          #   Output quality for lossy thumbnail formats (jpg / webp / png): higher = better
+          #   quality, larger file. For PNG, `quality` < 100 applies lossy palette quantization
+          #   (transparency preserved); `quality: 100` keeps the PNG lossless. Per-format effective
+          #   default (server-resolved when `quality` is unset, per ADR-0020 D1): PNG → 70 (more
+          #   aggressive — thumbnails target small files), jpg/webp → 85. The schema `default` is
+          #   the nominal jpg/webp value (85); the FE shows 70 as the initial PNG slider value.
           description: >-
-            Output quality for lossy thumbnail formats (jpg / webp / png): higher =
-            better quality, larger file. For PNG, `quality` < 100 applies lossy palette
-            quantization (transparency preserved); `quality: 100` keeps the
-            PNG lossless. Per-format effective default (server-resolved when `quality`
-            is unset, per ADR-0020 D1): PNG → 70 (more aggressive — thumbnails target
-            small files), jpg/webp → 85. The schema `default` is the nominal jpg/webp
-            value (85); the FE shows 70 as the initial PNG slider value.
+            Output quality for jpg, webp and png thumbnails: higher = better quality,
+            larger file. For PNG, a value below 100 reduces the colour palette
+            (transparency is kept) and 100 keeps it lossless. When unset, PNG
+            thumbnails use 70 and jpg/webp use 85.
         background:
           type: string
           pattern: "^#[0-9a-fA-F]{6}$"
@@ -457,26 +462,29 @@ operation:
           #                            Cargo.lock via usvg; `quick-xml` is absent.
           # The build's real shape lives in the ticket and in lambdas' crate. This
           # file states the CONTRACT: what is advertised, and what the API gates.
+          # AUTHOR NOTES (moved out of the user-facing description, ewOlw35Z,
+          # 2026-09-23 — frontend shows option descriptions to users). Preserved verbatim:
+          #   `cover` (the only supported value) = extract the EPUB's declared cover image — the
+          #   cheap path, no rendering. Cover lookup supports both mechanisms: the EPUB 3
+          #   `cover-image` property on an OPF manifest item, AND the legacy EPUB 2 `<meta
+          #   name="cover" content="..."/>` pointing at a manifest item — supporting only the former
+          #   would miss a large slice of real-world files. Both are staging-proven (pL16ZfOw Wave
+          #   3). A cover image is OPTIONAL per W3C EPUB 3.3, so a cover-less EPUB is a REAL and
+          #   expected case: it fails with `error_code: processing_failed` and `is_retryable:
+          #   false`. That is the live behaviour, not an aspiration — the worker classifies it as
+          #   `CoverError::NoCoverDeclared` and maps it there (`epub/error.rs`), and
+          #   non-retryability is DERIVED from the code rather than set per-call, so it cannot
+          #   drift. A cover-less EPUB will not grow a cover, so retrying is always futile. A more
+          #   specific code would be better, and is NOT promised here: `ErrorCode` (asyncapi) is a
+          #   CLOSED enum with no "no cover" member, so adding one is a real cross-repo co-land
+          #   (enum edit -> SDK regen -> lockstep). Until then this description states what actually
+          #   happens — an undecided-reject note on a STABLE route would leave consumers unable to
+          #   handle a case they will certainly meet.
           description: >-
-            `cover` (the only supported value) = extract the EPUB's declared cover
-            image — the cheap path, no rendering. Cover lookup supports both
-            mechanisms: the EPUB 3 `cover-image` property on an OPF manifest item,
-            AND the legacy EPUB 2 `<meta name="cover" content="..."/>` pointing at a
-            manifest item — supporting only the former would miss a large slice of
-            real-world files. Both are staging-proven (pL16ZfOw Wave 3).
-            A cover image is OPTIONAL per W3C EPUB 3.3, so a cover-less EPUB is a
-            REAL and expected case: it fails with `error_code: processing_failed`
-            and `is_retryable: false`. That is the live behaviour, not an aspiration
-            — the worker classifies it as `CoverError::NoCoverDeclared` and maps it
-            there (`epub/error.rs`), and non-retryability is DERIVED from the code
-            rather than set per-call, so it cannot drift. A cover-less EPUB will not
-            grow a cover, so retrying is always futile.
-            A more specific code would be better, and is NOT promised here:
-            `ErrorCode` (asyncapi) is a CLOSED enum with no "no cover" member, so
-            adding one is a real cross-repo co-land (enum edit -> SDK regen ->
-            lockstep). Until then this description states what actually happens —
-            an undecided-reject note on a STABLE route would leave consumers unable
-            to handle a case they will certainly meet.
+            `cover` (the only supported value) uses the EPUB's declared cover image;
+            no pages are rendered. Both EPUB 3 and legacy EPUB 2 cover declarations
+            are recognised. An EPUB without a cover cannot produce a thumbnail: the
+            job fails with `processing_failed` and retrying will not help.
         width:
           type: integer
           min: 1

package/operations/schemas/video_text_watermark.yaml

@@ -101,13 +101,17 @@ operation:
             ticket).
 
         rotation:
+          # AUTHOR NOTES: planned, and its -45.0 default REMOVED (clGOsvp2).
+          # lambdas' armed-defaults adjudication (D0DwvmjV, 2026-09-24, row 125)
+          # found the worker never reads it — drawtext is emitted unrotated — so
+          # the default was an armed promise nobody keeps. Marking alone does not
+          # disarm a default; it has to go. Restore both when the worker rotates.
           type: float
           min: -360.0
           max: 360.0
-          default: -45.0
+          availability: planned
           description: |
-            Rotation angle in degrees. Default -45° suits tiled mode
-            (angled diagonal pattern). Clamped to range.
+            Rotation angle of the watermark text, in degrees. Not available yet.
 
         watermark_mode:
           type: enum
@@ -143,50 +147,56 @@ operation:
             - bottom_center
             - bottom_right
           default: bottom_right
-          description: |
-            9-grid anchor position. For `watermark_mode: single`, the
-            text label is placed at this anchor + margin_x/margin_y
-            offset on each frame. For `watermark_mode: tiled`, anchor
-            is ignored (tiles fill the frame).
-
-            🔴 **`center` IGNORES `margin_x` / `margin_y` rather than
-            rejecting them. THE REJECTION AS WRITTEN CANNOT SURVIVE A
-            NON-ZERO DEFAULT; IGNORING IS THE REPLACEMENT THAT WAS CHOSEN.**
-            The sibling operations still reject a non-zero
-            margin at `anchor: center` as `invalid_options` (422), and
-            that rule is sound THERE because their margin default is
-            `0px`: a client that materialises the default sends `0px`,
-            which is not non-zero, so only a caller who actually asked
-            for an offset is ever refused.
-
-            ⛔ **Here the default is `2%`, and that makes the rejection
-            rule unusable as written.** Schema-driven clients fill contract
-            defaults BEFORE sending, so a request with `anchor: center`
-            arrives carrying `margin_x: "2%"` whether the caller chose it
-            or never mentioned margins at all. **After default
-            materialisation an explicit value and a defaulted one are
-            INDISTINGUISHABLE on the wire**, so a rejection cannot
-            separate the mistake it exists to catch from the overwhelming
-            majority of requests that simply accepted the default. It
-            would 422 almost every centred watermark.
-
-            ⚠️ **Rejection is not the only alternative, and this text does
-            not claim it was forced.** A reject-if-it-differs-from-the-
-            default rule would survive materialisation exactly as the zero
-            rule does for the siblings. **Ignoring is the behaviour CHOSEN**
-            under hub decision 465, because margins are meaningless when the
-            label is centred and a no-op is kinder than a 422 on a request
-            that renders correctly. The cost is stated: a caller who
-            deliberately passes a margin with `anchor: center` gets silence
-            rather than a correction.
-
-            ⚠️ **DO NOT "align" `text_watermark` or `image_watermark` to
-            this on the strength of the operation NAME.** Their rejection
-            still works because their default is still `0px`. Changing one
-            of THOSE defaults to non-zero is what would force the same move
-            there — the trigger is a non-zero default, never the operation
-            name. (`video_watermark` moved with this operation because its
-            default moved too, under the same decision.)
+          # AUTHOR NOTES (moved out of the user-facing description, ewOlw35Z,
+          # 2026-09-23 — frontend shows option descriptions to users). Preserved verbatim:
+          #   9-grid anchor position. For `watermark_mode: single`, the
+          #   text label is placed at this anchor + margin_x/margin_y
+          #   offset on each frame. For `watermark_mode: tiled`, anchor
+          #   is ignored (tiles fill the frame).
+          #
+          #   🔴 **`center` IGNORES `margin_x` / `margin_y` rather than
+          #   rejecting them. THE REJECTION AS WRITTEN CANNOT SURVIVE A
+          #   NON-ZERO DEFAULT; IGNORING IS THE REPLACEMENT THAT WAS CHOSEN.**
+          #   The sibling operations still reject a non-zero
+          #   margin at `anchor: center` as `invalid_options` (422), and
+          #   that rule is sound THERE because their margin default is
+          #   `0px`: a client that materialises the default sends `0px`,
+          #   which is not non-zero, so only a caller who actually asked
+          #   for an offset is ever refused.
+          #
+          #   ⛔ **Here the default is `2%`, and that makes the rejection
+          #   rule unusable as written.** Schema-driven clients fill contract
+          #   defaults BEFORE sending, so a request with `anchor: center`
+          #   arrives carrying `margin_x: "2%"` whether the caller chose it
+          #   or never mentioned margins at all. **After default
+          #   materialisation an explicit value and a defaulted one are
+          #   INDISTINGUISHABLE on the wire**, so a rejection cannot
+          #   separate the mistake it exists to catch from the overwhelming
+          #   majority of requests that simply accepted the default. It
+          #   would 422 almost every centred watermark.
+          #
+          #   ⚠️ **Rejection is not the only alternative, and this text does
+          #   not claim it was forced.** A reject-if-it-differs-from-the-
+          #   default rule would survive materialisation exactly as the zero
+          #   rule does for the siblings. **Ignoring is the behaviour CHOSEN**
+          #   under hub decision 465, because margins are meaningless when the
+          #   label is centred and a no-op is kinder than a 422 on a request
+          #   that renders correctly. The cost is stated: a caller who
+          #   deliberately passes a margin with `anchor: center` gets silence
+          #   rather than a correction.
+          #
+          #   ⚠️ **DO NOT "align" `text_watermark` or `image_watermark` to
+          #   this on the strength of the operation NAME.** Their rejection
+          #   still works because their default is still `0px`. Changing one
+          #   of THOSE defaults to non-zero is what would force the same move
+          #   there — the trigger is a non-zero default, never the operation
+          #   name. (`video_watermark` moved with this operation because its
+          #   default moved too, under the same decision.)
+          description: >-
+            Where the text is placed on each frame, on a 3x3 grid. For
+            `watermark_mode: single` the text sits at this anchor, offset by
+            `margin_x` / `margin_y`. For `watermark_mode: tiled` the anchor is
+            ignored. With `center`, the margins are ignored.
 
         margin_x:
           type: string

package/operations/schemas/video_watermark.yaml

@@ -101,34 +101,39 @@ operation:
             - bottom_center
             - bottom_right
           default: bottom_right
-          description: |
-            9-grid anchor position on each video frame. Same vocabulary
-            as `image_watermark.image` and `text_watermark.image`.
-
-            🔴 **`center` IGNORES `margin_x` / `margin_y` rather than
-            rejecting them. The rejection as written cannot survive a
-            non-zero default; ignoring is the replacement that was CHOSEN.
-            The trigger is the DEFAULT, not this operation.** Schema-driven
-            clients materialise contract
-            defaults BEFORE sending, so with a non-zero default a centred
-            request arrives carrying `margin_x: "2%"` whether the caller
-            chose it or never mentioned margins. **After materialisation
-            an explicit value and a defaulted one are indistinguishable on
-            the wire**, so the old `invalid_options` (422) rule would
-            refuse nearly every centred watermark.
-
-            ⚠️ Rejection is not the only alternative — a
-            reject-if-it-differs-from-the-default rule would also survive
-            materialisation. **Ignoring is the behaviour CHOSEN** under hub
-            decision 465, because margins are meaningless when the label is
-            centred. The cost is stated: a caller who deliberately passes a
-            margin with `anchor: center` gets silence, not a correction.
-
-            ⚠️ **The trigger is a NON-ZERO DEFAULT, never an operation
-            name.** `image_watermark` and `text_watermark` keep their 422
-            because their defaults are still `0px`, where a materialised
-            default is not non-zero and only a deliberate offset is
-            refused.
+          # AUTHOR NOTES (moved out of the user-facing description, ewOlw35Z,
+          # 2026-09-23 — frontend shows option descriptions to users). Preserved verbatim:
+          #   9-grid anchor position on each video frame. Same vocabulary
+          #   as `image_watermark.image` and `text_watermark.image`.
+          #
+          #   🔴 **`center` IGNORES `margin_x` / `margin_y` rather than
+          #   rejecting them. The rejection as written cannot survive a
+          #   non-zero default; ignoring is the replacement that was CHOSEN.
+          #   The trigger is the DEFAULT, not this operation.** Schema-driven
+          #   clients materialise contract
+          #   defaults BEFORE sending, so with a non-zero default a centred
+          #   request arrives carrying `margin_x: "2%"` whether the caller
+          #   chose it or never mentioned margins. **After materialisation
+          #   an explicit value and a defaulted one are indistinguishable on
+          #   the wire**, so the old `invalid_options` (422) rule would
+          #   refuse nearly every centred watermark.
+          #
+          #   ⚠️ Rejection is not the only alternative — a
+          #   reject-if-it-differs-from-the-default rule would also survive
+          #   materialisation. **Ignoring is the behaviour CHOSEN** under hub
+          #   decision 465, because margins are meaningless when the label is
+          #   centred. The cost is stated: a caller who deliberately passes a
+          #   margin with `anchor: center` gets silence, not a correction.
+          #
+          #   ⚠️ **The trigger is a NON-ZERO DEFAULT, never an operation
+          #   name.** `image_watermark` and `text_watermark` keep their 422
+          #   because their defaults are still `0px`, where a materialised
+          #   default is not non-zero and only a deliberate offset is
+          #   refused.
+          description: >-
+            Where the watermark is placed on each frame, on a 3x3 grid (the same
+            positions as image and text watermarks). With `center`, `margin_x` /
+            `margin_y` are ignored.
 
         margin_x:
           type: string

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@giveitsmaller/contracts",
-  "version": "0.73.0",
-  "description": "Generated contract types for GISL (Give It Smaller). Generated from compression_contracts spec v2.208.0.",
-  "gislContractsSpec": "v2.208.0",
+  "version": "0.76.0",
+  "description": "Generated contract types for GISL (Give It Smaller). Generated from compression_contracts spec v2.211.0.",
+  "gislContractsSpec": "v2.211.0",
   "license": "Apache-2.0",
   "homepage": "https://docs.giveitsmaller.com",
   "bugs": {