@giveitsmaller/contracts 0.28.0 → 0.30.0

package/dist/operations/split.metadata.js

@@ -9,7 +9,6 @@ export const splitMetadata = {
     },
     mime_groups: {
         image_gif: {
-            availability: 'planned',
             processing_class: {},
             per_mime_availability: {},
             options: {

package/openapi/api.yaml

@@ -89,7 +89,7 @@ info:
     of truth instead of hardcoding magic numbers. A runtime
     `GET /api/uploads/limits` endpoint for dynamic discovery
     (per-tier / per-environment overrides) is a deferred follow-up.
-  version: 2.89.0
+  version: 2.92.0
   contact:
     name: API Support
 

package/operation-capabilities/operation-capabilities.json

@@ -0,0 +1,495 @@
+{
+  "operations": {
+    "archive": {
+      "accepts": [
+        "*"
+      ],
+      "availability": "stable",
+      "input": {
+        "max": 50,
+        "min": 2,
+        "model": "multi"
+      },
+      "produces": {
+        "from_option": "format"
+      },
+      "sole_op": true
+    },
+    "audio_overlay": {
+      "accepts": [
+        "audio",
+        "video"
+      ],
+      "availability": "planned",
+      "excludes": [
+        {
+          "availability": "stable",
+          "constraint_id": "audio_overlay.requires_audio_output",
+          "message": "audio_overlay needs an output that carries an audio track; {output_format} has none.",
+          "when": {
+            "equals": false,
+            "field": "output_format.hasAudioTrack"
+          },
+          "wire_code": "OPERATION_NOT_VALID_FOR_OUTPUT"
+        }
+      ],
+      "input": {
+        "max": 2,
+        "min": 2,
+        "model": "multi",
+        "roles": [
+          "base",
+          "overlay"
+        ]
+      },
+      "produces": {
+        "same_as_input": true
+      },
+      "sole_op": true
+    },
+    "audio_to_video": {
+      "accepts": [
+        "audio"
+      ],
+      "availability": "beta",
+      "input": {
+        "max": 2,
+        "min": 1,
+        "model": "multi",
+        "roles": [
+          "base",
+          "overlay"
+        ]
+      },
+      "produces": {
+        "fixed": "mp4"
+      },
+      "sole_op": true
+    },
+    "audio_watermark": {
+      "accepts": [
+        "audio",
+        "video"
+      ],
+      "availability": "planned",
+      "excludes": [
+        {
+          "availability": "stable",
+          "constraint_id": "audio_watermark.requires_audio_output",
+          "message": "audio_watermark embeds in an audio track; {output_format} carries none.",
+          "when": {
+            "equals": false,
+            "field": "output_format.hasAudioTrack"
+          },
+          "wire_code": "OPERATION_NOT_VALID_FOR_OUTPUT"
+        }
+      ],
+      "input": {
+        "model": "single"
+      },
+      "produces": {
+        "same_as_input": true
+      },
+      "sole_op": false
+    },
+    "compress": {
+      "accepts": [
+        "audio",
+        "document",
+        "image",
+        "video"
+      ],
+      "availability": "stable",
+      "excludes": [
+        {
+          "availability": "stable",
+          "constraint_id": "compress.video.target_size.container",
+          "message": "target_size encoding is mp4/MOV-only; not yet available for {output_format} output. Use crf.",
+          "when": {
+            "all": [
+              {
+                "equals": "target_size",
+                "field": "compress.encoding_mode"
+              },
+              {
+                "field": "output_format",
+                "in": [
+                  "webm",
+                  "ogg"
+                ]
+              }
+            ]
+          },
+          "wire_code": "feature_not_available"
+        },
+        {
+          "availability": "stable",
+          "constraint_id": "compress.video.target_size.longform",
+          "eval_scope": "api",
+          "message": "target_size two-pass is not yet available for long-form video. Use crf.",
+          "when": {
+            "all": [
+              {
+                "equals": "target_size",
+                "field": "compress.encoding_mode"
+              },
+              {
+                "equals": "long_form",
+                "field": "processing_class"
+              }
+            ]
+          },
+          "wire_code": "feature_not_available"
+        }
+      ],
+      "input": {
+        "model": "single"
+      },
+      "option_conflicts": [
+        {
+          "constraint_id": "compress.video.target_size.codec_conflict",
+          "message": "target_size requires the h264 codec (two-pass is libx264-only); {compress.codec} is incompatible.",
+          "when": {
+            "all": [
+              {
+                "equals": "target_size",
+                "field": "compress.encoding_mode"
+              },
+              {
+                "field": "compress.codec",
+                "isSet": true
+              },
+              {
+                "field": "compress.codec",
+                "in": [
+                  "h265",
+                  "vp9",
+                  "av1"
+                ]
+              }
+            ]
+          },
+          "wire_code": "invalid_options"
+        }
+      ],
+      "produces": {
+        "same_as_input": true
+      },
+      "requires": [
+        {
+          "constraint_id": "compress.video.target_size.bytes_required",
+          "message": "target_size_bytes is required when encoding_mode is target_size.",
+          "requires_field": "compress.target_size_bytes",
+          "when": {
+            "equals": "target_size",
+            "field": "compress.encoding_mode"
+          },
+          "wire_code": "invalid_options"
+        }
+      ],
+      "sole_op": false
+    },
+    "convert": {
+      "accepts": [
+        "audio",
+        "document",
+        "image",
+        "video"
+      ],
+      "availability": "stable",
+      "input": {
+        "model": "single"
+      },
+      "produces": {
+        "from_option": "output_format"
+      },
+      "sole_op": false
+    },
+    "custom_luma": {
+      "accepts": [
+        "video"
+      ],
+      "availability": "planned",
+      "excludes": [
+        {
+          "availability": "stable",
+          "constraint_id": "custom_luma.video_output_only",
+          "message": "custom_luma produces a video transition; it is not applicable to {output_format}.",
+          "when": {
+            "not": {
+              "field": "output_format",
+              "in": [
+                "mp4",
+                "webm",
+                "ogg"
+              ]
+            }
+          },
+          "wire_code": "OPERATION_NOT_VALID_FOR_OUTPUT"
+        }
+      ],
+      "input": {
+        "max": 2,
+        "min": 2,
+        "model": "multi",
+        "roles": [
+          "base",
+          "transition_mask"
+        ]
+      },
+      "produces": {
+        "same_as_input": true
+      },
+      "sole_op": true
+    },
+    "image_watermark": {
+      "accepts": [
+        "image"
+      ],
+      "availability": "stable",
+      "input": {
+        "max": 2,
+        "min": 2,
+        "model": "multi",
+        "roles": [
+          "base",
+          "overlay"
+        ]
+      },
+      "produces": {
+        "same_as_input": true
+      },
+      "sole_op": true
+    },
+    "merge": {
+      "accepts": [
+        "audio",
+        "image",
+        "video"
+      ],
+      "availability": "stable",
+      "input": {
+        "max": 10,
+        "min": 2,
+        "model": "multi"
+      },
+      "produces": {
+        "from_option": "output_type"
+      },
+      "sole_op": true
+    },
+    "passthrough": {
+      "accepts": [
+        "*"
+      ],
+      "availability": "beta",
+      "input": {
+        "model": "single"
+      },
+      "produces": {
+        "same_as_input": true
+      },
+      "sole_op": false
+    },
+    "render_variants": {
+      "accepts": [
+        "image"
+      ],
+      "availability": "planned",
+      "input": {
+        "model": "single"
+      },
+      "produces": {
+        "same_as_input": true
+      },
+      "sole_op": false
+    },
+    "split": {
+      "accepts": [
+        "audio",
+        "document",
+        "image",
+        "video"
+      ],
+      "availability": "beta",
+      "excludes": [
+        {
+          "availability": "stable",
+          "constraint_id": "split.requires_chain_predecessor",
+          "message": "split must follow a compress or convert operation.",
+          "when": {
+            "not": {
+              "any": [
+                {
+                  "opSelected": "compress"
+                },
+                {
+                  "opSelected": "convert"
+                }
+              ]
+            }
+          },
+          "wire_code": "INVALID_OPERATION_ORDER"
+        }
+      ],
+      "input": {
+        "model": "single"
+      },
+      "produces": {
+        "from_option": "output_format"
+      },
+      "sole_op": true
+    },
+    "text_watermark": {
+      "accepts": [
+        "image"
+      ],
+      "availability": "stable",
+      "input": {
+        "model": "single"
+      },
+      "produces": {
+        "same_as_input": true
+      },
+      "sole_op": true
+    },
+    "thumbnail": {
+      "accepts": [
+        "document",
+        "image",
+        "video"
+      ],
+      "availability": "stable",
+      "excludes": [
+        {
+          "availability": "stable",
+          "constraint_id": "thumbnail.requires_chain_predecessor",
+          "message": "thumbnail must follow a compress or convert operation.",
+          "when": {
+            "not": {
+              "any": [
+                {
+                  "opSelected": "compress"
+                },
+                {
+                  "opSelected": "convert"
+                }
+              ]
+            }
+          },
+          "wire_code": "INVALID_OPERATION_ORDER"
+        }
+      ],
+      "input": {
+        "model": "single"
+      },
+      "produces": {
+        "from_option": "format"
+      },
+      "sole_op": false
+    },
+    "video_text_watermark": {
+      "accepts": [
+        "video"
+      ],
+      "availability": "planned",
+      "input": {
+        "model": "single"
+      },
+      "produces": {
+        "same_as_input": true
+      },
+      "sole_op": true
+    },
+    "video_watermark": {
+      "accepts": [
+        "video"
+      ],
+      "availability": "beta",
+      "input": {
+        "max": 2,
+        "min": 2,
+        "model": "multi",
+        "roles": [
+          "base",
+          "overlay"
+        ]
+      },
+      "produces": {
+        "same_as_input": true
+      },
+      "sole_op": true
+    }
+  },
+  "output_properties": {
+    "aac": {
+      "hasAudioTrack": true,
+      "isAnimated": false
+    },
+    "avif": {
+      "hasAudioTrack": false,
+      "isAnimated": false
+    },
+    "bmp": {
+      "hasAudioTrack": false,
+      "isAnimated": false
+    },
+    "flac": {
+      "hasAudioTrack": true,
+      "isAnimated": false
+    },
+    "gif": {
+      "hasAudioTrack": false,
+      "isAnimated": true
+    },
+    "heic": {
+      "hasAudioTrack": false,
+      "isAnimated": false
+    },
+    "jpeg": {
+      "hasAudioTrack": false,
+      "isAnimated": false
+    },
+    "jpg": {
+      "hasAudioTrack": false,
+      "isAnimated": false
+    },
+    "mp3": {
+      "hasAudioTrack": true,
+      "isAnimated": false
+    },
+    "mp4": {
+      "hasAudioTrack": true,
+      "isAnimated": false
+    },
+    "ogg": {
+      "hasAudioTrack": true,
+      "isAnimated": false
+    },
+    "opus": {
+      "hasAudioTrack": true,
+      "isAnimated": false
+    },
+    "png": {
+      "hasAudioTrack": false,
+      "isAnimated": false
+    },
+    "tiff": {
+      "hasAudioTrack": false,
+      "isAnimated": false
+    },
+    "wav": {
+      "hasAudioTrack": true,
+      "isAnimated": false
+    },
+    "webm": {
+      "hasAudioTrack": true,
+      "isAnimated": false
+    },
+    "webp": {
+      "hasAudioTrack": false,
+      "isAnimated": "maybe"
+    }
+  },
+  "schema_version": "2.92.0"
+}

package/operations/schemas/compress.yaml

@@ -25,12 +25,14 @@ operation:
     # 2026-06-20, lossless parked). width/height/fit/auto_orient stay removed
     # (EsD1hs5u — worker recompresses only; resize -> thumbnail, format -> convert).
     #
-    # output_format FACADE (replicated identically per group): non-`original`
-    # values resolve to a SINGLE API-canonicalized convert-with-size-cap pass
-    # (the compress worker never reads output_format). `webp` is live+proven
-    # (untagged = stable, ADR-0001 §1.4); auto/smallest/jpeg/png/avif stay
-    # `planned` until each value's canonicalization lands (per-value stable-flip
-    # with capability proof, ADR-0001/0006). `original` stays stable.
+    # output_format (replicated identically per group): only the LIVE targets
+    # are advertised — `original` (no-op, default) and `webp` (the one proven
+    # compress+format pass: a single API-canonicalized convert-with-size-cap;
+    # the compress worker itself never reads output_format). The planned
+    # facade targets (auto/smallest/jpeg/png/avif) were PRUNED 2026-06-21 —
+    # dangling coming-soon values are dishonest at source; every other format
+    # change is the convert operation's job (all stable). Re-add a target here
+    # only when its compress+format canonicalization actually ships.
     image_jpeg:
       mimes:
         - image/jpeg
@@ -55,19 +57,13 @@ operation:
           description: "Enable progressive JPEG rendering (a low-quality preview renders first, then refines). JPEG only."
         output_format:
           type: enum
-          values: [original, auto, smallest, jpeg, png, webp, avif]
+          values: [original, webp]
           default: original
-          per_value_availability:
-            auto:     { availability: planned }   # runtime Accept-best selection — unbuilt
-            smallest: { availability: planned }   # runtime try-all-smallest selection — unbuilt
-            jpeg:     { availability: planned }   # facade path not live until its own canonicalization
-            png:      { availability: planned }   # facade path not live until its own canonicalization
-            avif:     { availability: planned }   # facade path not live until its own canonicalization
           description: >-
-            Output format. original = keep input format (default); auto = best for browser
-            support (AVIF > WebP > JPEG via Accept hint); smallest = try all supported formats,
-            return the smallest. Non-`original` values are served by the API "compress+format"
-            facade (one combined convert-with-size-cap pass); see per_value_availability + FORMAT.md.
+            Output format. original = keep input format (default); webp = recompress to
+            WebP — the one live compress+format target (proven on staging). Other format
+            changes (jpeg/png/avif/gif/tiff) are the convert operation's job, not compress.
+            See FORMAT.md.
 
     image_png:
       mimes:
@@ -95,19 +91,13 @@ operation:
           description: "PNG optimization effort (0-6, oxipng). Higher = smaller file, slower encode. Default 3."
         output_format:
           type: enum
-          values: [original, auto, smallest, jpeg, png, webp, avif]
+          values: [original, webp]
           default: original
-          per_value_availability:
-            auto:     { availability: planned }   # runtime Accept-best selection — unbuilt
-            smallest: { availability: planned }   # runtime try-all-smallest selection — unbuilt
-            jpeg:     { availability: planned }   # facade path not live until its own canonicalization
-            png:      { availability: planned }   # facade path not live until its own canonicalization
-            avif:     { availability: planned }   # facade path not live until its own canonicalization
           description: >-
-            Output format. original = keep input format (default); auto = best for browser
-            support (AVIF > WebP > JPEG via Accept hint); smallest = try all supported formats,
-            return the smallest. Non-`original` values are served by the API "compress+format"
-            facade (one combined convert-with-size-cap pass); see per_value_availability + FORMAT.md.
+            Output format. original = keep input format (default); webp = recompress to
+            WebP — the one live compress+format target (proven on staging). Other format
+            changes (jpeg/png/avif/gif/tiff) are the convert operation's job, not compress.
+            See FORMAT.md.
 
     image_avif:
       availability: beta
@@ -145,19 +135,13 @@ operation:
           description: "AVIF encode speed (1-10, ravif). Lower = smaller file, slower encode; higher = faster, larger. Default 4."
         output_format:
           type: enum
-          values: [original, auto, smallest, jpeg, png, webp, avif]
+          values: [original, webp]
           default: original
-          per_value_availability:
-            auto:     { availability: planned }   # runtime Accept-best selection — unbuilt
-            smallest: { availability: planned }   # runtime try-all-smallest selection — unbuilt
-            jpeg:     { availability: planned }   # facade path not live until its own canonicalization
-            png:      { availability: planned }   # facade path not live until its own canonicalization
-            avif:     { availability: planned }   # facade path not live until its own canonicalization
           description: >-
-            Output format. original = keep input format (default); auto = best for browser
-            support (AVIF > WebP > JPEG via Accept hint); smallest = try all supported formats,
-            return the smallest. Non-`original` values are served by the API "compress+format"
-            facade (one combined convert-with-size-cap pass); see per_value_availability + FORMAT.md.
+            Output format. original = keep input format (default); webp = recompress to
+            WebP — the one live compress+format target (proven on staging). Other format
+            changes (jpeg/png/avif/gif/tiff) are the convert operation's job, not compress.
+            See FORMAT.md.
 
     image:
       mimes:
@@ -184,19 +168,13 @@ operation:
             currently available).
         output_format:
           type: enum
-          values: [original, auto, smallest, jpeg, png, webp, avif]
+          values: [original, webp]
           default: original
-          per_value_availability:
-            auto:     { availability: planned }   # runtime Accept-best selection — unbuilt
-            smallest: { availability: planned }   # runtime try-all-smallest selection — unbuilt
-            jpeg:     { availability: planned }   # facade path not live until its own canonicalization
-            png:      { availability: planned }   # facade path not live until its own canonicalization
-            avif:     { availability: planned }   # facade path not live until its own canonicalization
           description: >-
-            Output format. original = keep input format (default); auto = best for browser
-            support (AVIF > WebP > JPEG via Accept hint); smallest = try all supported formats,
-            return the smallest. Non-`original` values are served by the API "compress+format"
-            facade (one combined convert-with-size-cap pass); see per_value_availability + FORMAT.md.
+            Output format. original = keep input format (default); webp = recompress to
+            WebP — the one live compress+format target (proven on staging). Other format
+            changes (jpeg/png/avif/gif/tiff) are the convert operation's job, not compress.
+            See FORMAT.md.
 
     audio:
       mimes:

package/operations/schemas/split.yaml

@@ -98,8 +98,13 @@ operation:
   mime_groups:
     # Animated GIF base — parallel mime_group naming follows the
     # `image_gif` precedent established by `image_watermark.image_gif`.
+    # availability flipped planned -> stable (2026-06-21, user-greenlit): the
+    # split-gif worker is built + deployed (lambdas) and proven on staging
+    # (e2e). Create-acceptance also requires the API `operation_weights` row
+    # `split.image_gif` (proposed weight 2, by analogy to split.audio=2 /
+    # archive=2 — pending the user's pricing approval); this flip co-lands with
+    # that weight (the activation third-gate, per split.video precedent).
     image_gif:
-      availability: planned
       mimes:
         - image/gif
       options:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@giveitsmaller/contracts",
-  "version": "0.28.0",
+  "version": "0.30.0",
   "description": "Generated contract types for GISL (Give It Smaller)",
   "license": "MIT",
   "type": "module",
@@ -27,6 +27,7 @@
     "./asyncapi/events.yaml": "./asyncapi/events.yaml",
     "./availability/availability.json": "./availability/availability.json",
     "./accepted-options/accepted-options.json": "./accepted-options/accepted-options.json",
+    "./operation-capabilities/operation-capabilities.json": "./operation-capabilities/operation-capabilities.json",
     "./operations/schemas/archive.yaml": "./operations/schemas/archive.yaml",
     "./operations/schemas/audio_overlay.yaml": "./operations/schemas/audio_overlay.yaml",
     "./operations/schemas/audio_to_video.yaml": "./operations/schemas/audio_to_video.yaml",
@@ -50,7 +51,8 @@
     "asyncapi/events.yaml",
     "operations/schemas/",
     "availability/availability.json",
-    "accepted-options/accepted-options.json"
+    "accepted-options/accepted-options.json",
+    "operation-capabilities/operation-capabilities.json"
   ],
   "scripts": {
     "clean": "node -e \"require('node:fs').rmSync('dist', {recursive: true, force: true})\"",