@giveitsmaller/contracts 0.87.0 → 0.89.0

package/operation-capabilities/operation-capabilities.json

@@ -101,6 +101,55 @@
       ],
       "availability": "stable",
       "excludes": [
+        {
+          "availability": "stable",
+          "constraint_id": "compress.audio.format_facade.knob",
+          "message": "channels, sample_rate, normalize and trim are not available when compress changes the audio format. Use output_format original, or a convert operation.",
+          "when": {
+            "all": [
+              {
+                "equals": "audio",
+                "field": "input_mime_group"
+              },
+              {
+                "field": "output_format",
+                "in": [
+                  "mp3",
+                  "aac",
+                  "ogg",
+                  "opus",
+                  "flac",
+                  "wav"
+                ]
+              },
+              {
+                "any": [
+                  {
+                    "field": "compress.channels",
+                    "isSet": true
+                  },
+                  {
+                    "field": "compress.sample_rate",
+                    "isSet": true
+                  },
+                  {
+                    "field": "compress.normalize",
+                    "isSet": true
+                  },
+                  {
+                    "field": "compress.trim_start",
+                    "isSet": true
+                  },
+                  {
+                    "field": "compress.trim_end",
+                    "isSet": true
+                  }
+                ]
+              }
+            ]
+          },
+          "wire_code": "feature_not_available"
+        },
         {
           "availability": "stable",
           "constraint_id": "compress.video.target_size.container",
@@ -691,16 +740,26 @@
           "constraint_id": "thumbnail.requires_chain_predecessor",
           "message": "thumbnail must follow a compress or convert operation.",
           "when": {
-            "not": {
-              "any": [
-                {
-                  "opSelected": "compress"
-                },
-                {
-                  "opSelected": "convert"
+            "all": [
+              {
+                "not": {
+                  "any": [
+                    {
+                      "opSelected": "compress"
+                    },
+                    {
+                      "opSelected": "convert"
+                    }
+                  ]
                 }
-              ]
-            }
+              },
+              {
+                "not": {
+                  "equals": "document",
+                  "field": "input_mime_group"
+                }
+              }
+            ]
           },
           "wire_code": "INVALID_OPERATION_ORDER"
         }
@@ -839,5 +898,5 @@
       "isAnimated": "maybe"
     }
   },
-  "schema_version": "2.223.0"
+  "schema_version": "2.225.0"
 }

package/operations/schemas/audio_to_video.yaml

@@ -41,12 +41,10 @@ operation:
     ⚠️ ON THE INPUT THE RATE WAS MEASURED WITH — a real photographic 1080p STILL
     plus looped real audio — the point at which the measured rate plus the fixed
     cost reaches the SERVED cap (the worker's 600 s times the register's
-    `headroom`, kikOfB6G), not the raw cap. ⛔ THE DRIVER IS THE STILL'S RESOLUTION, NOT THE
-    DURATION ALONE: a 4K still is MEASURED materially slower (2026-10-02), and the
-    short_form ceiling below is set from that worst case; this schema places NO
-    constraint on the overlay's resolution. Stills above 4K are unmeasured —
-    and what the caller then sees is NOT SETTLED — see the CHANGELOG entry for
-    2.203.0; this contract does not pin a worker's error classification. Measured figures and the conditions for re-listing are in the
+    `headroom`, kikOfB6G), not the raw cap. The still's resolution no longer drives
+    the time: since the worker fits the still ONCE (lambdas 5pWDD20e, 2026-10-06), a
+    4K still measures within 2% of a 1080p one, so the short_form ceiling below is
+    set by the slowest OUTPUT resolution measured. Measured figures and the conditions for re-listing are in the
     CHANGELOG entry for 2.203.0 — the only one of the two records that is
     PUBLISHED (`schemas/manifest-divergence-register.yaml` is working material
     for the drift gate and is not in the npm tarball).
@@ -91,14 +89,12 @@ operation:
         # cap on REAL content, measured by lambdas on staging 2026-10-01 (points
         # and fit in this operation's `evidence` block in
         # schemas/manifest-divergence-register.yaml; a test holds the two equal).
-        # Encode time depends on the OUTPUT resolution and on the STILL's
-        # resolution, not on the input, so this is ONE ceiling: the slowest
-        # measured combination, a 3840x2160 still at `fhd_1080p` output (the
-        # worker decodes and scales the still on every frame; lambdas
-        # `5pWDD20e` scales it once, after which this is re-measured and rises).
-        # RESIDUAL, stated: a still ABOVE 4K is unmeasured and the schema caps no
-        # overlay resolution, so such an input can exceed the cap at this
-        # duration; 5pWDD20e removes the still-resolution dependence entirely.
+        # Encode time depends on the OUTPUT resolution, not on the input, so this
+        # is ONE ceiling: the slowest measured combination. Since lambdas
+        # `5pWDD20e` (fit the still ONCE; on prod in git-0a837e4) a 4K still costs
+        # what a 1080p one does (re-measured to 2160 s, zgzSm3Ag), so the
+        # binding series is now an OLDER, pre-fit-once measurement (fhd_1080p,
+        # lambdas 2026-10-01) — conservative: fit-once only made encodes faster.
         # Every offered output was measured (sd_480p, hd_720p, fhd_1080p).
         # Longer inputs route to long_form.
         short_form:
@@ -106,7 +102,7 @@ operation:
           ceiling_basis:   # 607(d): proven at the declared value, or not yet (FORMAT.md §ceiling_basis)
             max_input_duration: unproven
           constraints:
-            max_input_duration: "PT11M35S"   # floor((cap * headroom - intercept) / slope), 4K still at fhd_1080p
+            max_input_duration: "PT29M43S"   # min of the register's derived ceiling_s over offered outputs + the 4K still (fhd_1080p binds)
         # The Fargate route (no invocation ceiling). The duration is the worker's
         # own guard, MAX_AUDIO_DURATION_SECS 7200 (strict >; KzrquIX7). Planned
         # until a policy-79 record from the Fargate path exists.

package/operations/schemas/compress.yaml

@@ -1073,6 +1073,23 @@ 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. convert.audio was then measured too (2026-10-07): WAV output
+      # is DURATION-bound (~1,080 s at 48 kHz stereo), so no single group value fits
+      # either route (decision 709: stay without a cap). Per-format groups: yzLzpHAZ.
+      # LATE FAILURES ARE TYPED (nWtWmdbn): the output cap -> `output_too_large`;
+      # the worker's input+output working storage (2,148,286,464 B) ->
+      # `input_too_large` — never `unknown`.
       options:
         output_format:
           type: enum
@@ -1091,9 +1108,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
@@ -1113,7 +1136,9 @@ operation:
             `depends_on` — the lossy-output condition is an output-value × input-MIME
             cross-axis the option-to-option `depends_on` cannot model without dropping
             `original` and breaking same-format callers. The other knobs
-            (channels/sample_rate/normalize) apply to all formats.
+            (channels, sample_rate, normalize, trim) apply only with `output_format`
+            absent or `original`: with any explicit `output_format` they are refused
+            with `feature_not_available` (constraint compress.audio.format_facade.knob).
         channels:
           type: integer
           min: 1

package/operations/schemas/convert.yaml

@@ -445,7 +445,9 @@ operation:
         # ffmpeg-native (palettegen/paletteuse), gated `depends_on output_format: gif`.
         # STABLE — lambdas staging-proven (convert #248: custom fps=10/width=320/
         # max_colors=64/loop=2/dither=floyd_steinberg = 31 frames, 320x180, 117KB vs
-        # default 46 frames/640x360/257KB; each lever demonstrably applied). Shapes
+        # default 46 frames/640x360/257KB; each lever demonstrably applied). HISTORICAL:
+        # that "default" run used the OLD defaults (fps 15, width 640); owner decision
+        # 698(5) (card mcWeBGMB, 2026-10-07) moved them to fps 12 / width 480. Shapes
         # pinned with lambdas pre-code (their ffmpeg impl, NOT gifsicle). `lossy` is
         # deliberately NOT here — it needs the gifsicle binary (a fast-follow);
         # lambdas pings when that pass lands.
@@ -453,7 +455,7 @@ operation:
           type: float
           min: 1
           max: 50
-          default: 15
+          default: 12   # was 15; owner decision 698(5), mcWeBGMB
           depends_on: { output_format: gif }
           description: >
             Output frame rate for video → GIF. Lower = fewer frames = smaller file.
@@ -462,7 +464,7 @@ operation:
           type: integer
           min: 1
           max: 4096
-          default: 640
+          default: 480   # was 640; owner decision 698(5), mcWeBGMB
           depends_on: { output_format: gif }
           description: >
             Maximum output width in pixels — a downscale-only CAP (a source narrower
@@ -506,7 +508,14 @@ operation:
           required: true
           # `opus` added 2026-06-20 — the convert-audio worker produces it
           # (audio/ogg container, .opus extension; lambdas-confirmed live).
-          description: "Target format"
+          # WAV DURATION LIMIT (nWtWmdbn, test_assets slice 10, staging 2026-10-07): WAV
+          # output is uncompressed, so it hits the worker's 209,715,200 B output cap at
+          # 192,000 B/s (48 kHz stereo 16-bit): last pass 1,080 s, first fail 1,100 s,
+          # whatever the input codec. Stated in the description; no cap is declared (decisions 708/709).
+          description: >-
+            Target format. WAV is uncompressed, so its length is limited by size: about
+            18 minutes at 48 kHz stereo 16-bit, longer for mono or lower sample rates,
+            shorter for more channels or higher rates. Past that the job fails.
         bitrate:
           type: enum
           value_type: integer

package/operations/schemas/merge.yaml

@@ -203,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
@@ -610,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/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/package.json

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