@giveitsmaller/contracts 0.67.0 → 0.69.0

package/operation-capabilities/operation-capabilities.json

@@ -732,5 +732,5 @@
       "isAnimated": "maybe"
     }
   },
-  "schema_version": "2.196.0"
+  "schema_version": "2.199.0"
 }

package/operations/schemas/compress.yaml

@@ -727,7 +727,7 @@ operation:
       # WHY THIS BLOCK IS WRITTEN DEFENSIVELY: on 2026-07-17 this group was
       # downgraded to `planned` on the strength of a single stale COMMENT in the
       # lambda manifest ("SVG is a follow-up"). The worker had implemented SVGO
-      # all along — image_compressor.rs:211 maps image/svg+xml, :1225
+      # all along — image_compressor.rs:211 maps image/svg+xml, :1227
       # compress_svg shells to the SVGO binary via ToolRunner, and the crate
       # Dockerfile builds and ships it. Staging had proved it the day before:
       # job 019f6aa3-d275-7b10-a5cf-58acc705c7e2, 43777 -> 33061 bytes (24.5%),
@@ -754,15 +754,15 @@ operation:
       # includes `convertPathData`; that rounds path coordinates (default
       # floatPrecision 3), so geometry changes within a rounding tolerance.
       # "Visually preserving" is the honest wording. (The worker does set
-      # lossless=true internally at image_compressor.rs:1778, but it lands in
+      # lossless=true internally at image_compressor.rs:1781, but it lands in
       # CompressionResult.settings which CompressionProcessor discards — its own
-      # NOTE at :1782 — so it reaches no consumer, and nothing should start
+      # NOTE at :1784 — so it reaches no consumer, and nothing should start
       # claiming it.)
       mimes:
         - image/svg+xml
       # KNOWN OVER-ADVERTISEMENT, DELIBERATELY LEFT AS-IS — do NOT lower this
       # unilaterally. compress_svg holds the markup in memory and caps SVGO
-      # output at 100 MiB (image_compressor.rs:1241), so the 500 MiB image/*
+      # output at 100 MiB (image_compressor.rs:1243), so the 500 MiB image/*
       # default over-states what the SVG route can actually serve: a valid input
       # inside the advertised limit can fail on the worker cap. Codex flagged it
       # on the flip PR and it is a real gap.
@@ -1114,11 +1114,38 @@ operation:
           # per-value-availability tag: option availability is binary and cannot be
           # output-container-scoped (same cross-axis limitation as
           # compress.audio.bitrate's lossy-output rule). crf is universal. ADR-0023 D8.
-          description: >-
-            crf = constant quality (variable file size). target_size = constrained
-            output file size (two-pass). target_size is LIVE for mp4/MOV output; for
-            webm/ogg output and long-form the server returns `feature_not_available`
-            (use crf there) until two-pass for this container ships.
+          description: |
+            `crf` = constant quality. `target_size` = constrained output file size
+            (two-pass). `target_size` is LIVE for mp4/MOV output; for webm/ogg output
+            and long-form the server returns `feature_not_available` (use `crf` there)
+            until two-pass for this container ships.
+
+            🔴 **`crf` DOES NOT MEAN UNCONSTRAINED FILE SIZE. THIS DESCRIPTION USED TO
+            SAY "variable file size" AND THAT WAS FALSE BY OMISSION.** For **mp4/MOV
+            output**, the worker additionally derives a **source-relative peak-bitrate
+            ceiling of roughly 60% of the source video bitrate** (`-maxrate`/`-bufsize`),
+            and **it binds regardless of an explicit `crf`** — constrained-CRF. The `crf`
+            value is still honoured as the **quality ceiling**; the cap adds a peak
+            ceiling on top of it.
+
+            ⚠️ **Scope, because "we cap every video" would be a second false sentence:**
+            the cap is **mp4/MOV only** — WebM/VP9 discards it and skips the probe
+            entirely — and it is **best-effort**, so an unprobeable source gets no cap.
+
+            ⭐ **Why it exists, which is also why the old wording surprised in the wrong
+            direction:** plain CRF alone **INFLATES already-efficient sources** — an
+            efficient HEVC re-encoded to H.264 at CRF 23/25/30 grows. The compress
+            contract is *reduce file size*, so the cap is what makes shrinking reliable.
+            A caller who deliberately pins a low `crf` on an efficient source therefore
+            gets a constrained-CRF transcode rather than a byte-for-byte original: a
+            deliberate, accepted shift.
+
+            🔴 **THIS DESCRIPTION IS BOUND TO THE WORKER, NOT DATED AGAINST IT.**
+            `tests/test_bitrate_cap_disclosure_matches_the_worker.py` reads
+            `compression_lambdas` at `origin/main` and fails if the cap stops
+            being source-relative, stops being mp4/MOV-only, or stops deriving
+            from a source probe. **An as-of date would make a superseded
+            sentence look deliberate**; a gate makes it go red instead.
         crf:
           type: integer
           min: 0
@@ -1142,7 +1169,37 @@ operation:
           type: enum
           values: [ultrafast, superfast, veryfast, faster, fast, medium, slow, slower, veryslow]
           default: medium
-          description: "Encoding speed vs compression ratio trade-off"
+          description: |
+            x264/x265 encoder effort. **A SIZE LEVER, CONDITIONALLY** — it moves
+            output size **only while the mp4/MOV peak-bitrate cap is NOT binding.**
+
+            **Measured by `compression_lambdas`, medium vs slow, all else held:**
+
+                crf 30, cap inert    1,220,156 vs 1,144,043 bytes   6.2% apart
+                crf 18, cap binding  2,514,788 vs 2,516,986 bytes   0.09% apart
+
+            🔴 **THE MECHANISM IS MECHANICAL, NOT EMPIRICAL, AND EXPLAINS BOTH ROWS.**
+            In pure CRF the encoder targets constant QUALITY, so a slower preset spends
+            its extra effort producing a **smaller file at the same quality**. Once
+            `-maxrate` binds the encode is rate-limited, so the extra effort can only go
+            into **picture at a fixed size** — an axis a size measurement cannot see.
+
+            ⚠️ **This description previously said `preset` was effort-only and that `crf`
+            was the size lever. That was wrong**, and it was wrong because a 0.09% figure
+            measured on a **cap-binding** clip was generalised into a property of `preset`.
+            **A measurement is not a property until you know what held it.**
+
+            ⇒ **Callers optimising for size:** `crf` is the primary lever; `preset` adds
+            real reduction **only when the cap is not already constraining the encode** —
+            which is exactly the high-`crf`, small-output end. See `encoding_mode` for what
+            the cap is and when it applies.
+
+            ⚠️ **What the extra effort buys once the cap DOES bind is mechanically
+            implied and empirically UNCONFIRMED.** The mechanism says it must go
+            into picture; `compression_lambdas` could not see a difference on 2x
+            crops, but that was **one frame of one 5-second clip**, and preset
+            differences concentrate in high-motion frames that were not
+            deliberately sampled. **Recorded as unestablished, not asserted.**
         width:
           type: integer
           min: 2

package/operations/schemas/thumbnail.yaml

@@ -160,15 +160,108 @@ operation:
           depends_on: { format: [jpg, webp] }
           description: "Output quality for lossy thumbnail formats (jpg/webp): higher = better quality, larger file. Ignored for png (lossless)."
 
-    document:
+    # SPLIT FROM THE FORMER `document` GROUP (jLxWpQEZ). PDF and office/ODF
+    # thumbnails are rendered by DIFFERENT WORKERS with DIFFERENT input bounds,
+    # and one group cannot carry two ceilings honestly — a single group-level
+    # number would have capped PDF at the office limit and over-refused PDFs the
+    # worker handles fine.
+    document_pdf:
       mimes:
         - application/pdf
+      # 🔴 NO BYTE CEILING, SAID EXPLICITLY RATHER THAN LEFT ABSENT.
+      # The Poppler render path is bounded by PROCESSING TIME, not input size.
+      # `FORMAT.md` says an absent `max_input_size_bytes` means NOT ADVERTISED
+      # and explicitly NOT "no limit exists" — so silence here would be
+      # indistinguishable from the omission that let a 100 MiB EPUB refusal hide
+      # behind a 200 MiB declaration. A consumer must be able to tell "we did not
+      # fill this in" from "there is genuinely no size bound".
+      input_size_bound: processing_time
+      # Same 16MP output-area wall as image (width*height <= max_output_pixels).
+      # The page is rendered at 150 DPI (render-side ~25MP raster) then resized;
+      # the output file is capped at 50MB (worker-enforced, prose-only).
+      max_output_pixels: 16000000
+      options:
+        source:
+          type: enum
+          values: [page, cover]
+          default: page
+          # `cover` is RETAINED here deliberately (G9O6yrQD / codex #322). EPUB — the
+          # only input it ever meant anything for — moved to the `document_epub`
+          # group, so `cover` is now inert for every mime in THIS group. Removing it
+          # looked like tidying a phantom, but it is a REQUEST-ENUM NARROWING: a
+          # caller sending `source: cover` with a PDF succeeds today (the worker
+          # ignores it) and would start getting a 422 invalid_options. That is a
+          # caller-visible break for zero benefit, and "nobody sends it" is not a
+          # reason (the same reasoning was wrong for declared_duration_seconds, which
+          # turned out settable on npm-latest). Retiring it properly = tag it
+          # `deprecated` -> migrate -> remove, which is its own cut, not a drive-by
+          # in a defect fix.
+          description: >-
+            `page` = render a specific page/slide. `cover` = extract a cover image —
+            only meaningful for EPUB inputs, which are served by the `document_epub`
+            group; on PDF/office/ODF it is accepted and IGNORED (retained for
+            backward compatibility).
+        page:
+          type: integer
+          min: 1
+          default: 1
+          depends_on: { source: page }
+          description: >-
+            1-based index of the printed page to render, after print-layout
+            pagination is applied. For office formats this is the page in the
+            document's print layout — NOT a 1:1 sheet/slide index: a spreadsheet
+            sheet may span multiple printed pages and multi-sheet workbooks
+            paginate their sheets in order. For PDF inputs it is the PDF page
+            number directly.
+        width:
+          type: integer
+          min: 1
+          max: 16384
+          description: >-
+            Target width in pixels (1-16384; width*height <= 16MP). Optional — when
+            omitted the server applies an aspect-preserving default (both omitted →
+            longest edge 320px; only one of width/height provided → the other is
+            derived from the source aspect ratio).
+        height:
+          type: integer
+          min: 1
+          max: 16384
+          description: >-
+            Target height in pixels (1-16384; width*height <= 16MP). Optional — see
+            `width` for the omitted-default behaviour.
+        fit:
+          type: enum
+          values: [max, crop, scale]
+          default: crop
+          description: "Resize mode"
+        format:
+          type: enum
+          values: [jpg, png, webp]
+          default: jpg
+          description: "Output format for the thumbnail"
+        quality:
+          type: integer
+          min: 1
+          max: 100
+          default: 85
+          depends_on: { format: [jpg, webp] }
+          description: "Output quality for lossy thumbnail formats (jpg/webp): higher = better quality, larger file. Ignored for png (lossless)."
+
+
+    # SPLIT FROM THE FORMER `document` GROUP (jLxWpQEZ) — see `document_pdf`.
+    document_office:
+      mimes:
         - application/vnd.openxmlformats-officedocument.wordprocessingml.document
         - application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
         - application/vnd.openxmlformats-officedocument.presentationml.presentation
         - application/vnd.oasis.opendocument.text
         - application/vnd.oasis.opendocument.spreadsheet
         - application/vnd.oasis.opendocument.presentation
+      # LibreOffice worker input ceiling, mirroring the Rust `MAX_INPUT_SIZE`
+      # literal and the value `compression_lambdas`' manifest has declared since
+      # 2026-08-25. Undeclared here until now, which is why a create could be
+      # accepted and then refused: see jLxWpQEZ.
+      max_input_size_bytes: 157286400
       # Same 16MP output-area wall as image (width*height <= max_output_pixels).
       # The page is rendered at 150 DPI (render-side ~25MP raster) then resized;
       # the output file is capped at 50MB (worker-enforced, prose-only).
@@ -301,6 +394,12 @@ operation:
       # true here. Re-add it additively when a renderer ships AND is proven.
       mimes:
         - application/epub+zip
+      # EPUB thumbnail worker input ceiling, mirroring the Rust `MAX_INPUT_SIZE`
+      # literal. ⚠️ `compression_lambdas`' manifest has declared this number since
+      # 2026-07-18 — THIRTY-NINE DAYS before a 128,232,024-byte EPUB was accepted,
+      # billed, and refused by it on 2026-08-26. The number was public on their
+      # side the whole time; the silence was HERE. jLxWpQEZ.
+      max_input_size_bytes: 104857600
       max_output_pixels: 16000000
       options:
         source:

package/package.json

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