@giveitsmaller/contracts 0.86.0 → 0.88.0

package/operations/schemas/compress.yaml

@@ -746,11 +746,21 @@ operation:
           min: 1
           max: 16384
           honored_on: [same_format, format_change]
+          # oK7WlNaY: lambdas convert image_convert.rs (animation-preserving FFmpeg path) refuses any resize; scale-filter follow-up msP9wWoO. Loop-extension-less GIFs read as static: 0McJYHGy.
           description: >-
             Target width in pixels (1-16384; width × height must not exceed the
             group's maximum output area). Resizes the image as part of the operation
             (one transformed output, replacing the source). Optional; omit to keep the
             source dimensions.
+            Not supported for an ANIMATED image whose output keeps the animation
+            (an animated GIF or WebP converted to GIF or WebP). Where the
+            server can tell the input is animated it refuses at create with 422
+            `feature_not_available`, feature `operation.image.resize.animated`;
+            where it cannot tell, the job is accepted and fails with
+            `invalid_options` — except a multi-frame GIF with no loop extension,
+            which is currently treated as static: it is resized and comes out as
+            its first frame only. Resize a static image, or choose a still output
+            format.
         height:
           type: integer
           min: 1
@@ -992,11 +1002,21 @@ operation:
           min: 1
           max: 16384
           honored_on: [same_format, format_change]
+          # oK7WlNaY: lambdas convert image_convert.rs (animation-preserving FFmpeg path) refuses any resize; scale-filter follow-up msP9wWoO. Loop-extension-less GIFs read as static: 0McJYHGy.
           description: >-
             Target width in pixels (1-16384; width × height must not exceed the
             group's maximum output area). Resizes the image as part of the operation
             (one transformed output, replacing the source). Optional; omit to keep the
             source dimensions.
+            Not supported for an ANIMATED image whose output keeps the animation
+            (an animated GIF or WebP converted to GIF or WebP). Where the
+            server can tell the input is animated it refuses at create with 422
+            `feature_not_available`, feature `operation.image.resize.animated`;
+            where it cannot tell, the job is accepted and fails with
+            `invalid_options` — except a multi-frame GIF with no loop extension,
+            which is currently treated as static: it is resized and comes out as
+            its first frame only. Resize a static image, or choose a still output
+            format.
         height:
           type: integer
           min: 1
@@ -1053,6 +1073,19 @@ operation:
         - audio/flac
         - audio/wav
         - audio/mp4
+      # NO INPUT CEILING DECLARED — DELIBERATELY, hub decisions 708/709 (ypreI0Bx).
+      # Measured (test_assets slice 10, staging, 2026-10-07): the binding bound on
+      # the `original` route is the worker's 209,715,200 B OUTPUT cap; largest
+      # passing input mp3 320k 380,002,580 B, flac 204,911,198 B, wav 48k/24-bit
+      # 201,600,044 B. The mp3 figure holds for 320 kbps ONLY: compress re-encodes
+      # a low-bitrate mp3 at its 64 kbps floor, so the same bytes are far longer
+      # and can hit the 180 s ffmpeg timeout first — unmeasured (test_assets
+      # correction, 2026-10-07). KNOWN LATE FAILURE: an input past those is accepted and
+      # fails on the worker. Not declared because a group-level cap is enforced
+      # before route selection, and `output_format != original` is served by the
+      # convert facade, which is unmeasured — a cap would newly refuse requests
+      # that may work. Gate: test_assets' convert.audio measurement, then one cap
+      # = min over both routes; per-format groups are card yzLzpHAZ.
       options:
         output_format:
           type: enum
@@ -1071,9 +1104,15 @@ operation:
           #   Output audio format. original = keep input format (default, same-format compression).
           #   Non-`original` values re-target the container/codec via the API "compress+format"
           #   facade (one canonicalized convert pass); see FORMAT.md.
+          # WAV under `original` resolves to FLAC (lambdas compression-audio
+          # format.rs output_extension: Wav -> flac): PCM WAV cannot get smaller as
+          # WAV, so the lossless compress is FLAC. Measured on prod 2026-10-06 (e2e
+          # tier 6). Card SFv9Ms5C.
           description: >-
             Output audio format. original = keep input format (default, same-format
-            compression). Other values change the format as part of the same job.
+            compression), except WAV: a WAV is compressed losslessly to FLAC, because
+            uncompressed WAV cannot get smaller as WAV. Other values change the
+            format as part of the same job.
         bitrate:
           type: enum
           value_type: integer

package/operations/schemas/convert.yaml

@@ -97,11 +97,21 @@ operation:
           min: 1
           max: 16384
           honored_on: [format_change]
+          # oK7WlNaY: lambdas convert image_convert.rs (animation-preserving FFmpeg path) refuses any resize; scale-filter follow-up msP9wWoO. Loop-extension-less GIFs read as static: 0McJYHGy.
           description: >-
             Target width in pixels (1-16384; width × height must not exceed the
             group's maximum output area). Resizes the image before encoding (one
             transformed output). NOT honored for SVG input. Optional; omit to keep
             the source dimensions.
+            Not supported for an ANIMATED image whose output keeps the animation
+            (an animated GIF or WebP converted to GIF or WebP). Where the
+            server can tell the input is animated it refuses at create with 422
+            `feature_not_available`, feature `operation.image.resize.animated`;
+            where it cannot tell, the job is accepted and fails with
+            `invalid_options` — except a multi-frame GIF with no loop extension,
+            which is currently treated as static: it is resized and comes out as
+            its first frame only. Resize a static image, or choose a still output
+            format.
         height:
           type: integer
           min: 1
@@ -201,8 +211,9 @@ operation:
           values: [jpeg, png, webp, avif, gif, tiff, mp4, webm]
           required: true
           description: >-
-            Target format. The still-image targets (jpeg/png/webp/avif/gif/tiff) take
-            the first frame / rasterise. `mp4` / `webm` are the GIF→VIDEO transcode
+            Target format. `jpeg` / `png` / `avif` / `tiff` take the first frame. `gif`
+            and `webp` keep an animated GIF's animation (a static GIF stays a single
+            frame). `mp4` / `webm` are the GIF→VIDEO transcode
             targets — the animated GIF becomes a muted, play-once video (`mp4` =
             H.264, plays everywhere; `webm` = VP9, smaller), typically far smaller
             than the original GIF. GIFs are silent (no audio stream); the GIF
@@ -240,11 +251,21 @@ operation:
           max: 16384
           depends_on: { output_format: [jpeg, png, webp, avif, gif, tiff] }
           honored_on: [format_change]
+          # oK7WlNaY: lambdas convert image_convert.rs (animation-preserving FFmpeg path) refuses any resize; scale-filter follow-up msP9wWoO. Loop-extension-less GIFs read as static: 0McJYHGy.
           description: >-
             Target width in pixels (1-16384; width × height must not exceed the
             group's maximum output area). Scoped to the STILL-IMAGE targets only —
             resizing while transcoding to the mp4/webm video targets is not yet
             supported, so width/height are not accepted for the video targets.
+            Not supported for an ANIMATED image whose output keeps the animation
+            (an animated GIF or WebP converted to GIF or WebP). Where the
+            server can tell the input is animated it refuses at create with 422
+            `feature_not_available`, feature `operation.image.resize.animated`;
+            where it cannot tell, the job is accepted and fails with
+            `invalid_options` — except a multi-frame GIF with no loop extension,
+            which is currently treated as static: it is resized and comes out as
+            its first frame only. Resize a static image, or choose a still output
+            format.
         height:
           type: integer
           min: 1

package/operations/schemas/merge.yaml

@@ -168,7 +168,8 @@ operation:
         # but ROUTING (which class) is DURATION/SIZE-driven at
         # create-plan, NOT concat-compatibility: the API resolver
         # assigns long_form when summed input duration exceeds the
-        # short_form cap (PT5M) OR summed size exceeds 1 GiB; it has no
+        # short_form cap (PT5M) OR summed size exceeds 500 MiB
+        # (524,288,000 B, the short_form_concat cap); it has no
         # per-input codec/pixfmt at create-plan to decide re-encode-need
         # (MAVh1blw; api d363a4ab). re_encode-vs-stream-copy is a WORKER
         # SUB-MODE WITHIN EACH class, not a long-form differentiator:
@@ -202,6 +203,20 @@ operation:
           constraints:
             max_total_duration: "PT5M"
             max_total_input_size_bytes: 524288000    # 500 MiB combined (the stream-copy ceiling; was 1 GiB)
+          # MIXED AUDIO TOPOLOGY (zO6vH8Ow, e2e prod 2026-10-06). This class
+          # re-encodes heterogeneous inputs, so it needs no attribute uniformity,
+          # but it cannot re-encode inputs where some carry audio and others do
+          # not (lambdas merge_processor.rs: ReEncode verdict + AudioTopology::Mixed
+          # -> invalid_options, "merge V1 cannot re-encode mixed-audio topology").
+          # Such inputs cannot stream-copy either, so they are always refused.
+          # Declared so the API refuses at create (api uVcpKow1) instead of the
+          # worker after acceptance. Silence-padding the missing track is the
+          # same parked product decision as long_form's structural list.
+          input_uniformity:
+            refusal: INPUTS_NOT_CONCAT_UNIFORM
+            structural:
+              - input_audio_topology_mixed
+            attributes: {}
         long_form_re_encode:
           # planned -> beta (CON-1, ADR-0011) -> stable (CON-2b, HWNXo1kk):
           # staging-proven 2026-07-07 via long-form-merge.spec.ts Phase 2
@@ -406,6 +421,9 @@ operation:
           min: 0
           max: 51
           default: 23
+          # On long_form_re_encode `encoding_mode` is dropped, and this gate reads its
+          # DEFAULT (`crf`) — FORMAT.md §depends_on rule 5 (aoxAfyt7) — so crf is honoured
+          # there; the long-form worker reads it (merge_processor.rs parse_crf).
           depends_on: { re_encode_mode: [auto, always], encoding_mode: crf }
           description: "Constant Rate Factor when encoding_mode=crf. Lower = higher quality / larger file."
 
@@ -606,7 +624,16 @@ operation:
           type: enum
           values: [audio]
           required: false
-          description: "Output format for audio merge (concatenation). Currently fixed at 'audio'. Optional — API injects this default post-validation so callers may omit it."
+          # The output is ALWAYS AAC in an MP4 container (audio/mp4, .m4a), whatever the
+          # inputs: lambdas merge_processor.rs output_extension_for, pinned by a test;
+          # api's OperationChainMimeResolver derives audio/mp4. Measured on prod
+          # 2026-10-06 (e2e tier 3: MP3 inputs -> MP4). Card QjtIq0dv; a choice of
+          # container is lambdas Z6KLrDfl.
+          description: >-
+            Output format for audio merge (concatenation). Currently fixed at 'audio': the
+            merged file is always AAC audio in an MP4 container (.m4a, audio/mp4), whatever the
+            input formats. Optional — API injects this default post-validation so callers may
+            omit it.
         transition:
           type: enum
           # audio_transition catalog (per ticket I18, FORMAT.md §"Audio

package/operations/schemas/split.yaml

@@ -65,8 +65,8 @@ operation:
       `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.
+      Specified 2026-09-25 and `beta` since 2026-10-01 (card `jGTLrpzK`), on
+      a staging run of both modes; `stable` needs a production record.
     - `audio`: `PositionIndexed` (cut stream-position ordinal)
     - `video`: `PositionIndexed` (cut stream-position ordinal)
 
@@ -85,10 +85,10 @@ operation:
     `availability: beta` for the `audio` and `video` mime_groups
     (shape-stable + opt-in, MUST NOT 422). Video activates **both
     classes**: `video.processing_class.short_form` AND `long_form` are
-    `beta`. The `image_gif` and `document_pdf` mime_groups stay
-    `availability: planned` until their cross-repo backend support ships;
-    dispatch returns `feature_not_available` (422) for the still-planned
-    groups/classes until then.
+    `beta`. The `document_pdf` mime_group is `beta` too (2026-10-01), and
+    `image_gif` is `stable` (GIF to frames, 2026-06-21). A value or class
+    still tagged `planned` (e.g. `precision: exact`) is refused with
+    `feature_not_available` (422).
   default: false
   input_model: single
   sole_op: true   # bypasses V1 chain validation — must be the only operation in its job (ADR-0025)
@@ -139,9 +139,18 @@ operation:
 
     # PDF base — page-split via qpdf or pdftk equivalent.
     document_pdf:
-      availability: planned
+      availability: beta   # jGTLrpzK, 2026-10-01: staging worker-direct proof, both modes
       mimes:
         - application/pdf
+      # Byte bound (lambdas, 2026-10-01): the worker downloads the PDF to /tmp
+      # (10,240 MB ephemeral on stg + prod) and qpdf keeps EVERY output there
+      # until the job ends, so input + all outputs share it, and outputs can
+      # exceed the input (shared resources copied per piece: 1.20x measured on
+      # page_groups 3). 2 GiB leaves that headroom. Above free /tmp the worker
+      # refuses input_too_large up front; running out mid-job is a write error.
+      ceiling_basis:   # 607(d): proven at the declared value, or not yet (FORMAT.md §ceiling_basis)
+        max_input_size_bytes: unproven
+      max_input_size_bytes: 2147483648   # 2 GiB
       options:
         mode:
           type: enum

package/operations/schemas/thumbnail.yaml

@@ -2,7 +2,12 @@ schema_version: "1.0.0"
 
 operation:
   type: thumbnail
-  description: "Resize an image to specific dimensions, or extract a preview frame/page from a video or document. For images this is a full resizer (1-16384px), not just small previews."
+  description: >-
+    Resize an image to specific dimensions, or extract a preview frame/page from a video
+    or document. For images this is a full resizer (1-16384px), not just small previews.
+    An image or video thumbnail must follow a compress or convert in the same job; a
+    document thumbnail may stand alone. Image types that compress does not accept (BMP,
+    HEIC) therefore need a convert first.
   default: false
   input_model: single
 
@@ -105,15 +110,20 @@ operation:
           availability: stable
           # RAISED 2026-09-26 (owner decision, 607(d)) to what the worker PROVED
           # (lambdas staging corner run, git-2166848): 30 min passes in ~1 s (FFmpeg
-          # seeks without decoding the footage before it), and size passes to
-          # 995,015,958 B; it FAILS at ~1 GiB because the input is downloaded whole
-          # to a 1 GiB /tmp. 950,000,000 B leaves headroom under that failure.
+          # seeks without decoding the footage before it). Size was then bound by
+          # the 1 GiB /tmp download (950,000,000 B).
+          # RAISED 2026-10-06 (7ds526za): the worker now reads the source by
+          # presigned URL (lambdas KE1uIegv / git-1c01ba4; on PROD in git-0a837e4
+          # since 2026-10-06 19:40Z), so /tmp no longer bounds input. Staging
+          # proved a 2,075,069,492 B 1080p MP4 in 9.3 s using 128 MB of 3008 MB.
+          # Declared at 2,000,000,000 B: below the largest proven input, not an
+          # extrapolation past it.
           ceiling_basis:   # 607(d): proven at the declared value, or not yet (FORMAT.md §ceiling_basis)
             max_input_size_bytes: proven
             max_input_duration: proven
           constraints:
             max_input_duration: "PT30M"
-            max_input_size_bytes: 950000000
+            max_input_size_bytes: 2000000000
         long_form:
           # Stays planned (CON-1 flips only compress.video.long_form +
           # merge.video.long_form_re_encode). Per-tier caps per ADR-0011 —

package/operations/schemas/video_text_watermark.yaml

@@ -96,20 +96,20 @@ operation:
           resolution_bands:
             le_720p:
               basis: measured
-              derivation: { slope_s_per_s: 2.167, intercept_s: 3.0, cap_s: 600 }
+              derivation: { slope_s_per_s: 2.551, intercept_s: 4.8, cap_s: 504 }
               constraints:
-                max_input_duration: "PT4M35S"     # floor((cap - intercept) / slope)
+                max_input_duration: "PT3M15S"     # floor((cap - intercept) / slope)
             p1080:
               basis: measured
-              derivation: { slope_s_per_s: 4.867, intercept_s: -3.0, cap_s: 600 }
+              derivation: { slope_s_per_s: 5.748, intercept_s: -1.9, cap_s: 504 }
               constraints:
-                max_input_duration: "PT2M3S"      # floor((cap - intercept) / slope)
+                max_input_duration: "PT1M28S"      # floor((cap - intercept) / slope)
             gt_1080p:
               basis: not_served
             unknown:
               basis: ruled
               constraints:
-                max_input_duration: "PT4M35S"     # = le_720p (decision 343)
+                max_input_duration: "PT3M15S"     # = le_720p (decision 343)
         long_form:
           availability: planned
           ceiling_basis:   # 607(d): proven at the declared value, or not yet (FORMAT.md §ceiling_basis)

package/operations/schemas/video_watermark.yaml

@@ -77,6 +77,33 @@ operation:
             max_input_duration: "PT5M"
             max_input_size_bytes: 524288000
             max_output_size_bytes: 524288000
+          # B4PA1JnA (HN-33 step 1): the duration this class actually serves on
+          # the Lambda cap, per resolution band, measured on real footage. Same
+          # method and shape as video_text_watermark: the POINTS live in this
+          # operation's `evidence` block in
+          # schemas/manifest-divergence-register.yaml, `derivation` is their
+          # least-squares line, each ceiling is that line solved for the cap and
+          # FLOORED, and tests hold the two equal. `cap_s` is the SERVED cap: the
+          # worker's 600 s times the register's `headroom` 0.84 (kikOfB6G). `gt_1080p` is not served (no
+          # real >1080p source has been measured); `unknown` takes the le_720p
+          # ceiling (decision 343, as video_text_watermark).
+          resolution_bands:
+            le_720p:
+              basis: measured
+              derivation: { slope_s_per_s: 2.336, intercept_s: -0.9, cap_s: 504 }
+              constraints:
+                max_input_duration: "PT3M36S"     # floor((cap - intercept) / slope)
+            p1080:
+              basis: measured
+              derivation: { slope_s_per_s: 5.262, intercept_s: 1.2, cap_s: 504 }
+              constraints:
+                max_input_duration: "PT1M35S"     # floor((cap - intercept) / slope)
+            gt_1080p:
+              basis: not_served
+            unknown:
+              basis: ruled
+              constraints:
+                max_input_duration: "PT3M36S"     # = le_720p (decision 343)
         long_form:
           availability: planned
           ceiling_basis:   # 607(d): proven at the declared value, or not yet (FORMAT.md §ceiling_basis)

package/package.json

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