@giveitsmaller/contracts 0.72.0 → 0.73.0

package/operations/schemas/split.yaml

@@ -172,6 +172,96 @@ 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:
+      #
+      #   `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 BOUND IS ENFORCED AT CREATE TODAY: 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
@@ -288,6 +378,69 @@ operation:
             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.
+
     # Video base — same three modes + precision + processing_class.
     # Long-form routes to `split-video-fargate` (same OperationType,
     # different worker per `processing_class`).
@@ -311,8 +464,7 @@ operation:
           # 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

package/operations/schemas/thumbnail.yaml

@@ -107,8 +107,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:

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
@@ -150,30 +149,78 @@ operation:
             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.)
+
         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

package/operations/schemas/video_watermark.yaml

@@ -76,8 +76,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
@@ -106,34 +105,65 @@ operation:
             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.
+
         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%"). Direction
             is anchor-relative — positive moves toward the frame
             centre.
 
-            **`anchor: center` exception.** When the anchor is `center`
-            the centre is the centre — there is no anchor-relative
-            direction. Non-zero `margin_x` combined with
-            `anchor: center` is rejected by the API at workflow-create
-            time as `invalid_options` (HTTP 422). Same rule as the
-            other watermark operations.
+            **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.**
+
+            **`anchor: center`: margins are IGNORED.** The centre is the
+            centre — there is no anchor-relative direction — so this is a
+            silent no-op rather than a rejection. See the `anchor`
+            description for why a rejection is not usable with a non-zero
+            default.
 
         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. Anchor-relative; positive moves toward
             the frame centre.
 
-            **`anchor: center` exception.** Same rejection rule as
-            `margin_x`.
+            **Defaults to `2%` (inset), for the reasons on `margin_x`**;
+            `"0px"` still gives a true flush. **`anchor: center`: margins
+            are IGNORED**, same as `margin_x`.
 
         opacity:
           type: float

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@giveitsmaller/contracts",
-  "version": "0.72.0",
-  "description": "Generated contract types for GISL (Give It Smaller). Generated from compression_contracts spec v2.203.0.",
-  "gislContractsSpec": "v2.203.0",
+  "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",
   "license": "Apache-2.0",
   "homepage": "https://docs.giveitsmaller.com",
   "bugs": {