@giveitsmaller/contracts 0.76.0 → 0.78.0

package/operation-capabilities/operation-capabilities.json

@@ -492,6 +492,62 @@
             ]
           },
           "wire_code": "invalid_options"
+        },
+        {
+          "availability": "stable",
+          "constraint_id": "image_watermark.center_anchor_needs_zero_margin",
+          "message": "`anchor: center` needs `margin_x` and `margin_y` to be zero (or absent): a margin has no direction from the centre. Use a peripheral anchor and a positive margin to nudge a roughly-centred mark.",
+          "when": {
+            "all": [
+              {
+                "equals": "center",
+                "field": "image_watermark.anchor"
+              },
+              {
+                "any": [
+                  {
+                    "all": [
+                      {
+                        "field": "image_watermark.margin_x",
+                        "isSet": true
+                      },
+                      {
+                        "not": {
+                          "field": "image_watermark.margin_x",
+                          "in": [
+                            "0px",
+                            "0%",
+                            "0.0px",
+                            "0.0%"
+                          ]
+                        }
+                      }
+                    ]
+                  },
+                  {
+                    "all": [
+                      {
+                        "field": "image_watermark.margin_y",
+                        "isSet": true
+                      },
+                      {
+                        "not": {
+                          "field": "image_watermark.margin_y",
+                          "in": [
+                            "0px",
+                            "0%",
+                            "0.0px",
+                            "0.0%"
+                          ]
+                        }
+                      }
+                    ]
+                  }
+                ]
+              }
+            ]
+          },
+          "wire_code": "invalid_options"
         }
       ],
       "produces": {
@@ -566,6 +622,78 @@
       "input": {
         "model": "single"
       },
+      "option_conflicts": [
+        {
+          "availability": "stable",
+          "constraint_id": "text_watermark.center_anchor_needs_zero_margin",
+          "message": "`anchor: center` needs `margin_x` and `margin_y` to be zero (or absent): a margin has no direction from the centre. Use a peripheral anchor and a positive margin to nudge a roughly-centred mark.",
+          "when": {
+            "all": [
+              {
+                "equals": "center",
+                "field": "text_watermark.anchor"
+              },
+              {
+                "any": [
+                  {
+                    "not": {
+                      "field": "text_watermark.watermark_mode",
+                      "isSet": true
+                    }
+                  },
+                  {
+                    "equals": "single",
+                    "field": "text_watermark.watermark_mode"
+                  }
+                ]
+              },
+              {
+                "any": [
+                  {
+                    "all": [
+                      {
+                        "field": "text_watermark.margin_x",
+                        "isSet": true
+                      },
+                      {
+                        "not": {
+                          "field": "text_watermark.margin_x",
+                          "in": [
+                            "0px",
+                            "0%",
+                            "0.0px",
+                            "0.0%"
+                          ]
+                        }
+                      }
+                    ]
+                  },
+                  {
+                    "all": [
+                      {
+                        "field": "text_watermark.margin_y",
+                        "isSet": true
+                      },
+                      {
+                        "not": {
+                          "field": "text_watermark.margin_y",
+                          "in": [
+                            "0px",
+                            "0%",
+                            "0.0px",
+                            "0.0%"
+                          ]
+                        }
+                      }
+                    ]
+                  }
+                ]
+              }
+            ]
+          },
+          "wire_code": "invalid_options"
+        }
+      ],
       "produces": {
         "same_as_input": true
       },
@@ -732,5 +860,5 @@
       "isAnimated": "maybe"
     }
   },
-  "schema_version": "2.211.0"
+  "schema_version": "2.213.0"
 }

package/operations/schemas/compress.yaml

@@ -83,11 +83,14 @@ operation:
     #     SVG (SVGO) re-encode from pixels so `keep` is NOT in their enum (worker
     #     would reject it). metadata `all` (strip) is the universal default.
     #
-    # Still availability:planned (ANTI-REGRESSION — no stable-flip until worker-
-    # proven; plan §2.5):
-    #   lossy (png) -> palette quantization (pngquant/imagequant-class); planned +
-    #     licensing-gated by the lambdas spike — do NOT stable-flip until that
-    #     confirms a permissive path.
+    # lossy (png) -> palette quantization (imagequant via libcaesium): STABLE
+    #   (owner decision 2026-09-24 21:20, option B on lambdas card 4azmqbm6). It
+    #   was already what production served: the worker never sets
+    #   `png.optimize`, so libcaesium 0.20.0 takes `lossy()` on EVERY PNG compress
+    #   (png.rs compress_in_memory) and the lossless oxipng path is unreachable.
+    #   This text previously called it planned and licensing-gated; the owner
+    #   accepts the licensing reading (imagequant GPL-3, server-side use only —
+    #   see the image_png provenance note below).
     image_jpeg:
       mimes:
         - image/jpeg
@@ -293,14 +296,22 @@ operation:
           max: 100
           default: 80
           honored_on: [same_format]
+          # AUTHOR NOTES (4azmqbm6, 2026-09-24). The old text said `quality: 100`
+          # keeps the PNG lossless. It never did: libcaesium 0.20.0 png.rs runs
+          # imagequant (`liq.set_quality(0, quality)`, quantize, remap to a
+          # palette) for every value, because the worker never sets
+          # `png.optimize`. A PNG with more than 256 colours therefore loses
+          # colours even at 100. Owner option B keeps that behaviour and states it.
+          # Frontend's "Best-Quality PNG lossless" (BhVwdlhQ) relied on the old
+          # sentence and was told.
           description: >-
-            Compression quality (1-100). For PNG this is the SINGLE lossy/lossless
-            control: `quality` < 100 applies lossy palette quantization (the value is
-            the quantization level), while `quality: 100` keeps the PNG lossless
-            (lossless optimisation only — tune the lossless effort via
-            `optimization_level`). 1 = smallest file, 100 = best quality / lossless.
-            There is no separate lossy/lossless toggle for PNG — it is purely
-            quality-driven.
+            Compression quality (1-100). PNG compression reduces the image to a
+            palette of at most 256 colours at every quality setting; this is what
+            makes PNGs smaller. 1 = smallest file, 100 = closest to the original.
+            No value is guaranteed lossless, including 100: when an image with
+            more than 256 colours (a photo, a gradient) is made smaller, it loses
+            some colour detail. If compressing would not make the file smaller,
+            the original is returned unchanged.
         metadata:
           type: enum
           values: [strip, keep, all]
@@ -323,8 +334,12 @@ operation:
           min: 0
           max: 6
           default: 3
-          honored_on: [same_format]
-          description: "PNG optimization effort (0-6). Higher = smaller file, slower encode. Default 3."
+          honored_on: []   # ACCEPTED BUT INERT (Nqd3TdC6): honoured on no route; FORMAT.md §honored_on
+          # AUTHOR NOTES (4azmqbm6, 2026-09-24): read only by libcaesium's lossless
+          # (oxipng) path, which compress never takes (see `quality`). Kept so a
+          # request that sends it is still accepted; it changes nothing.
+          description: >-
+            Currently has no effect on PNG output: it is accepted and ignored.
         output_format:
           type: enum
           values: [original, webp, auto, smallest]
@@ -878,9 +893,19 @@ operation:
           max: 100
           default: 80
           honored_on: [same_format]
+          # AUTHOR NOTES (IJofpQLI, 2026-09-24): lambdas' proof audit found the
+          # TIFF path (libcaesium 0.20.0 tiff.rs:98-100) takes only the algorithm
+          # and deflate level; quality is not an input, so it is IGNORED for
+          # image/tiff. Stated so the ignore is not silent. The structural fix
+          # (split this group into image_gif + image_tiff, the latter without
+          # quality) changes a group key consumers read, so it waits on a
+          # coordinated decision; the card stays open for it.
           description: >-
             Compression quality (1 = smallest file, 100 = best quality). For animated
             GIF this is honoured but real-world size reduction is typically small.
+            Ignored when a TIFF stays a TIFF: it is re-encoded losslessly, so this
+            setting has no effect on a TIFF output. It does apply when a TIFF is
+            converted to another format (for example WebP).
         metadata:
           type: enum
           values: [strip, keep, all]

package/operations/schemas/merge.yaml

@@ -196,6 +196,34 @@ operation:
           # max_total_duration (24h single-pass budget, SPIKE-0); size is the
           # per-tier secondary cap.
           availability: stable
+          # CONCAT-UNIFORMITY (MjzzPCWt, 2026-09-24). This class concatenates
+          # with the FFmpeg concat demuxer, which requires every input to share
+          # its stream layout and stream attributes. A heterogeneous pair was
+          # ACCEPTED on prod and then FAILED at the worker
+          # (input_stream_topology_mismatch; e2e wf 01a0d261). Reasons are
+          # lambdas' re_encode.rs classifier names. `structural` is PERMANENT
+          # (reconciling it, e.g. silence-padding a missing audio track, is a
+          # parked product decision); `attributes` holds until the
+          # heterogeneous re-encode (lambdas Phase 3: Y2Wgf028 / 9QlXjCCI /
+          # DjtJchlt / XY94t9N4) ships, and is lifted per attribute once proven.
+          # The API refuses at create with INPUTS_NOT_CONCAT_UNIFORM for every
+          # reason its upload probe can see; the worker gate is the backstop for
+          # the rest (see the openapi 422 description for the coverage rule).
+          input_uniformity:
+            refusal: INPUTS_NOT_CONCAT_UNIFORM
+            structural:                  # permanent
+              - input_count_below_minimum
+              - input_topology_not_single_video
+              - input_topology_multi_audio
+              - input_topology_extra_streams
+              - input_stream_topology_mismatch
+              - input_stream_order_mismatch
+            attributes:                  # until the heterogeneous re-encode ships
+              video: [codec, codec_tag, framerate, pix_fmt, profile, resolution, sar, timebase]
+              audio: [codec, sample_rate, channels, channel_layout, sample_fmt, timebase]
+              # Not a stream kind: a video/audio stream FIELD present on one
+              # input and absent on another (lambdas' input_metadata_inconsistent).
+              field_presence: [input_metadata_inconsistent]
           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)

package/operations/schemas/split.yaml

@@ -56,11 +56,17 @@ operation:
     - `image_gif`: `PositionIndexed` (frame stream-position 0-based
       ordinal)
     - `document_pdf`: `PageIndexed` (1-based literal source page number).
-      **`mode: page_range` only** — each output is one page, so `page_index` is
-      that page. For **`mode: page_groups`** an output spans multiple source
-      pages, so a single `page_index` cannot name them all; that grouped-output
-      semantics is NOT specified by this correction and is deferred (do not
-      assume it is the group's first page — that is unverified).
+      With **`mode: page_range`** each output is one page, so `page_index` is
+      that page. With **`mode: page_groups`** each output is a group of
+      consecutive pages and `page_index` is the group's FIRST source page;
+      the group covers `page_index` .. `page_index + page_groups - 1`, and
+      the last group ends at the document's last page (so it may be
+      shorter). Verified in the worker, not assumed: `compression_lambdas`
+      `crates/split/src/processor.rs` passes each range's START page as the
+      index, over ranges from `resolve_page_groups` (`pdf_range.rs`, tests
+      `page_groups_remainder` / `page_groups_size_larger_than_total`).
+      Specified 2026-09-25 (card `jGTLrpzK`); the group stays `planned`
+      until a production record exists.
     - `audio`: `PositionIndexed` (cut stream-position ordinal)
     - `video`: `PositionIndexed` (cut stream-position ordinal)
 

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

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@giveitsmaller/contracts",
-  "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",
+  "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": {