@giveitsmaller/contracts 0.73.0 → 0.78.0

package/operations/schemas/video_text_watermark.yaml

@@ -53,6 +53,61 @@ operation:
             max_input_duration: "PT5M"
             max_input_size_bytes: 524288000
             max_output_size_bytes: 524288000
+          # Resolution bands (GxQPL4IY, HN-33 step 1; bounds in
+          # schemas/resolution-bands.yaml). A band only TIGHTENS the class
+          # ceiling above; an input over its band's ceiling exceeds short_form.
+          #
+          # MEASURED by compression_lambdas on staging, 2026-09-15 (decision
+          # 367), `git-c9df285` v55, video_text_watermark only. Labels every row
+          # carries: looped-source · uncontended · current-cap-600s · 2026-09-15.
+          # ⚠️ The source is 26 s of real footage LOOPED — optimistic for rate
+          # control. When test_assets rows #1 / #3 replace it the ceilings
+          # move DOWN, not up.
+          #
+          # Encode time is a LINE, slope AND intercept, and each ceiling is that
+          # line solved for the cap and FLOORED: `derivation` holds the inputs
+          # and a test recomputes the ceiling from them. ⛔ Dropping the
+          # intercept gives 276 s at 720p, and 2.167 × 276 + 3 = 601.1 s — past
+          # the cap the number exists to respect (the CHANGELOG 2.203.0 record
+          # made this correction once already). One constant generates both
+          # rows, ~2.35 s per megapixel-second on this worker; when the cap is
+          # derived from the runtime deadline (3JT9S3On) the rows are
+          # RECOMPUTED from `derivation`, not re-measured. An earlier
+          # extrapolation of 145 s at 1080p measured 124 s-before-the-intercept:
+          # 18% optimistic, the same direction as every estimate that day.
+          #
+          # `gt_1080p` is NOT SERVED on short_form: the constant predicts ~31 s
+          # of 4K, an extrapolation 4x beyond anything measured, and neither
+          # lambdas nor contracts publishes it as a number. One real 4K cell
+          # replaces it with a measured row.
+          #
+          # `unknown` (no width or height from the probe) is RULED, not
+          # measured (decision 343): it takes the le_720p ceiling — the
+          # LONGEST-duration band, which is what "widest band" means here; the
+          # >1080p band is the most RESTRICTIVE one. api's evidence for a
+          # generous value (dated 2026-09-15): the probe race is a 1-9 s
+          # client-timing window, and prod saw two video files in 30 days,
+          # both a 5.9 MB / 26 s 1080p file. ⚠️ n=2 is a bounded bet, not a
+          # distribution. Residual, left open on purpose: a probe-less 4K
+          # five-minute file passes create under `unknown` and dies in the
+          # worker.
+          resolution_bands:
+            le_720p:
+              basis: measured
+              derivation: { slope_s_per_s: 2.167, intercept_s: 3.0, cap_s: 600 }
+              constraints:
+                max_input_duration: "PT4M35S"     # 275 s = floor((600 - 3) / 2.167)
+            p1080:
+              basis: measured
+              derivation: { slope_s_per_s: 4.867, intercept_s: -3.0, cap_s: 600 }
+              constraints:
+                max_input_duration: "PT2M3S"      # 123 s = floor((600 + 3) / 4.867)
+            gt_1080p:
+              basis: not_served
+            unknown:
+              basis: ruled
+              constraints:
+                max_input_duration: "PT4M35S"     # = le_720p (decision 343)
         long_form:
           availability: planned
           constraints:                            # baseline = every tier without a per_tier_constraints override
@@ -101,13 +156,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 +202,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.78.0",
+  "description": "Generated contract types for GISL (Give It Smaller). Generated from compression_contracts spec v2.213.0.",
+  "gislContractsSpec": "v2.213.0",
   "license": "Apache-2.0",
   "homepage": "https://docs.giveitsmaller.com",
   "bugs": {