@giveitsmaller/contracts 0.72.0 → 0.76.0

package/operations/schemas/custom_luma.yaml

@@ -3,12 +3,12 @@ schema_version: "2.0.0"
 operation:
   type: custom_luma
   availability: planned
-  required_tier: pro
   description: |
     Apply a caller-uploaded luma matte (transition-mask) over a base
     video to produce a custom luma-matte transition effect. Inspired
     by Cloudinary's deprecated luma-matte custom transitions and
-    intended as a paid-tier (`pro`+) creative feature.
+    intended as a creative feature, metered by credits like every
+    other operation (no tier gate — decision 26, 2026-09-23).
 
     **NOT** related to the `xfade=custom` expression-mode transition
     parameter. The `merge.transition.custom` value is tagged `planned`
@@ -52,13 +52,12 @@ operation:
         - video/webm
       processing_class:
         # F8 long-form video tier (per ticket I15-CONS). custom_luma
-        # is itself `availability: planned` + `required_tier: pro`
-        # at the operation level; the per-class shape lands now to
+        # is itself `availability: planned` at the operation level
+        # (no tier gate — decision 26, owner ruling 2026-09-23); the per-class shape lands now to
         # keep SDK/sidecar shape forward-compatible when the operation
         # ships.
         short_form:
           availability: planned
-          required_tier: pro
           constraints:
             max_input_duration: "PT5M"
             max_input_size_bytes: 524288000
@@ -68,8 +67,7 @@ operation:
           # merge.video.long_form_re_encode). Per-tier caps per ADR-0011 —
           # advertised shape; availability gates execution off (422).
           availability: planned
-          required_tier: pro
-          constraints:                            # baseline = Pro
+          constraints:                            # baseline = every tier without a per_tier_constraints override
             max_input_duration: "PT12H"
             max_input_size_bytes: 5000000000       # 5 GB (Pro)
             max_output_size_bytes: 5000000000

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
@@ -190,8 +196,7 @@ operation:
           # max_total_duration (24h single-pass budget, SPIKE-0); size is the
           # per-tier secondary cap.
           availability: stable
-          required_tier: pro
-          constraints:                              # baseline = Pro (lowest permitted)
+          constraints:                              # baseline = every tier without a per_tier_constraints override
             max_total_duration: "PT24H"              # 24h (was PT12H) — binding Enterprise ceiling
             max_total_input_size_bytes: 5000000000   # 5 GB combined (Pro)
           per_tier_constraints:

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
@@ -172,6 +179,104 @@ operation:
     # Audio base — three modes + precision flag.
     audio:
       availability: beta
+
+      # 🔴 THE WORKER IMPOSES NO BYTE CEILING ON AUDIO. Declared OUT LOUD rather
+      # than left silent, because silence and "no limit" look identical to a
+      # consumer and this contract has already been bitten by that: on
+      # 2026-08-26 a 128,232,024-byte EPUB was ACCEPTED, BILLED, and then
+      # refused by a 104,857,600 worker ceiling that appeared in no schema.
+      # Accepted, billed, refused — see FORMAT.md §`input_size_bound`.
+      #
+      # Confirmed in `compression_lambdas` `crates/split` at 22aec09, by reading
+      # rather than inferring: `process_audio` receives `actual_size` and uses it
+      # for exactly ONE thing — reporting it back as `original_size_bytes`. It is
+      # never compared against anything. The 524,288,000 guard in that crate is
+      # on the VIDEO path only (its error text says "split video: input size …
+      # exceeds the short-form ceiling"); audio never reaches it.
+      #
+      # ⚠️ THIS IS A STATEMENT ABOUT THE BOUND'S KIND, NOT A PROMISE OF UNLIMITED
+      # INPUT. A large audio file still fails — it fails on a CLOCK, which a
+      # consumer cannot pre-validate against and must not be told it can.
+      input_size_bound: processing_time
+
+      # ⛔ NO `max_input_duration` HERE, AND THE ABSENCE IS A DECISION THIS TIME.
+      # 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
+      #           terminal result with `error_code: invalid_options`.
+      #   `fast`  has no check at all. Past the point where its deadline
+      #           saturates, the budget stops growing while the work keeps
+      #           growing: it degrades into a TIMEOUT rather than a named
+      #           refusal.
+      #
+      # 🔴 **TWO LIMITS EXIST AND THE SMALLER ONE BINDS. THE CRATE NAMES THE
+      # LARGER.** The worker carries an internal time budget; 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.** There is a band of inputs that PASS the budget
+      # check — the worker judges them fine — and are then hard-killed by the
+      # platform mid-encode, with no named cause. The check does not protect the
+      # caller at the top of its own range; it just does not refuse them.
+      #
+      # ⚠️ **IT DOES NOT MAKE THE REFUSAL UNREACHABLE, AND AN EARLIER DRAFT OF
+      # THIS COMMENT SAID IT DID.** `exact_budget_fits` runs immediately after
+      # download and probe and BEFORE any re-encode (`processor.rs`, whose own
+      # comment says it rejects "upfront rather than timing out mid-run"), so a
+      # long-but-small input reaches it in seconds and does return
+      # `invalid_options`. **The draft conflated two different quantities:** the
+      # PROBED INPUT DURATION the check reads, and the ELAPSED WALL CLOCK the
+      # platform timeout measures. Those are different axes — which is the exact
+      # error this whole correction exists to fix, committed inside the fix.
+      #
+      # ⛔ **NO FIGURE IS PUBLISHED HERE, DELIBERATELY** (hub decision 509).
+      # v2.205.0 published numbers keyed to the crate constant — the LARGER limit,
+      # the one that does not bind — which is the same mistake its own entry warns
+      # about: *taking the number the code names without asking what the platform
+      # does first*. The figure lands only when lambdas' internal-budget derivation
+      # settles AND a job is measured near it. **A number that is wrong is worse
+      # than an absent number the shape explains**, because a consumer will
+      # pre-validate against it.
+      #
+      # ⚠️ **THIS IS AN AUDIO-ONLY EXPOSURE, AND THE REASON IS THIS VERY ABSENCE.**
+      # The `video` group's `short_form` class declares `max_input_duration`, which
+      # the API ENFORCES AT CREATE well below any of these boundaries, so a video
+      # job never reaches the inversion; long-form video is a different worker
+      # entirely. Audio declares no duration cap — that is what leaves the clock
+      # bound reachable here and nowhere else.
+      #
+      # ⇒ A single group-level number would be wrong in one direction or the
+      # other. Declaring one WOULD make the API refuse at CREATE — a declared
+      # 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 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.
+      # There is no `per_value_constraints` primitive (only `per_tier_`), so the
+      # per-value rule lives on the `precision` option where the caller choosing
+      # it reads it — the same placement as every other cross-field rule in this
+      # contract. Tracked: the missing `per_value_constraints` vocabulary and the
+      # asymmetry that `fast` refuses nothing, both on
+      # https://trello.com/c/YsaOzPU1 . The figure itself: 02FfdivD.
+      #
+      # ⚠️ NOT MEASURED, AND THAT IS THE SECOND REASON FOR NO FIGURE. Every
+      # boundary here is READ FROM SOURCE, not observed: lambdas' audio fixtures
+      # top out at 145 s, a small fraction of any candidate cap. They say what the
+      # code WILL do, not what it DOES near the boundary on a real file.
       mimes:
         - audio/mpeg
         - audio/aac
@@ -278,15 +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).
+          # 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,
@@ -305,14 +501,16 @@ 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
-          required_tier: pro
-          constraints:                            # baseline = Pro
+          constraints:                            # baseline = every tier without a per_tier_constraints override
             max_input_duration: "PT12H"
             max_input_size_bytes: 5000000000       # 5 GB (Pro)
             max_output_size_bytes: 5000000000
@@ -379,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}$"
@@ -107,8 +112,7 @@ operation:
           # advertised shape; availability gates execution off (422).
           # No max_output_size_bytes: thumbnail output is a single bounded image.
           availability: planned
-          required_tier: pro
-          constraints:                            # baseline = Pro
+          constraints:                            # baseline = every tier without a per_tier_constraints override
             max_input_duration: "PT12H"
             max_input_size_bytes: 5000000000       # 5 GB (Pro)
           per_tier_constraints:
@@ -458,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/transform.yaml

@@ -146,8 +146,7 @@ operation:
             max_output_size_bytes: 524288000
         long_form:
           availability: planned
-          required_tier: pro
-          constraints:                            # baseline = Pro
+          constraints:                            # baseline = every tier without a per_tier_constraints override
             max_input_duration: "PT12H"
             max_input_size_bytes: 5000000000       # 5 GB (Pro)
             max_output_size_bytes: 5000000000

package/operations/schemas/video_text_watermark.yaml

@@ -55,8 +55,7 @@ operation:
             max_output_size_bytes: 524288000
         long_form:
           availability: planned
-          required_tier: pro
-          constraints:                            # baseline = Pro
+          constraints:                            # baseline = every tier without a per_tier_constraints override
             max_input_duration: "PT12H"
             max_input_size_bytes: 5000000000       # 5 GB (Pro)
             max_output_size_bytes: 5000000000
@@ -102,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
@@ -144,36 +147,90 @@ 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).
+          # 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
           pattern: '^\d+(\.\d+)?(px|%)$'
-          default: "0px"
+          default: "2%"
           description: |
             Horizontal offset from the anchor as pixels (e.g. "40px")
             or percentage of video frame width (e.g. "5%").
             Anchor-relative. Ignored when `watermark_mode: tiled`.
 
-            **`anchor: center` exception** (watermark_mode: single
-            only). Non-zero `margin_x` combined with `anchor: center`
-            is rejected by the API at workflow-create time as
-            `invalid_options` (HTTP 422).
+            **Defaults to `2%`, i.e. INSET from the frame edge**, because
+            a watermark flush against the edge is the wrong default for
+            video: player chrome, safe-area cropping and letterboxing all
+            eat the outermost pixels. **A true flush remains available by
+            passing `"0px"` explicitly** — the default is a default, not a
+            floor.
+
+            **`anchor: center`: margins are IGNORED** (watermark_mode:
+            single only). They are meaningless when the label is centred,
+            and this is deliberately a silent no-op rather than a
+            rejection. See the `anchor` description for why rejection is
+            not available here.
 
         margin_y:
           type: string
           pattern: '^\d+(\.\d+)?(px|%)$'
-          default: "0px"
+          default: "2%"
           description: |
             Vertical offset from the anchor as pixels or percentage of
             video frame height. Ignored when `watermark_mode: tiled`.
 
-            **`anchor: center` exception** (watermark_mode: single
-            only). Same rejection rule as `margin_x`.
+            **Defaults to `2%` (inset), for the reasons on `margin_x`**;
+            `"0px"` still gives a true flush. **`anchor: center`: ignored**,
+            same as `margin_x`.
 
         opacity:
           type: float