@giveitsmaller/contracts 0.18.0 → 0.21.0

package/asyncapi/events.yaml

@@ -1,7 +1,7 @@
 asyncapi: 3.0.0
 info:
   title: GISL Compression Events
-  version: 3.19.0
+  version: 3.20.0
   description: |
     Asynchronous event contracts for the GISL (Give It Smaller) compression service.
 
@@ -31,7 +31,9 @@ info:
       `availability: beta` for its `audio` and `video` mime_groups
       (workers live on staging — [`vKI0CFDu`](https://trello.com/c/vKI0CFDu);
       video activates BOTH classes — `long_form` / `split-video-fargate`
-      proven on staging per [`rcwvUKhI`](https://trello.com/c/rcwvUKhI));
+      deployed + wired on staging but NOT yet proven end-to-end per
+      [`rcwvUKhI`](https://trello.com/c/rcwvUKhI) — first customer-path soak
+      incomplete, 4GB+ speed-up unmeasured, fan-out flag-gated dark);
       its `image_gif` and `document_pdf` mime_groups stay
       `availability: planned`.
       `audio_to_video` and `video_watermark` are `availability: beta`
@@ -218,7 +220,8 @@ channels:
         ship per [`vKI0CFDu`](https://trello.com/c/vKI0CFDu);
         long-form video splits route via `processing_class` to the
         `split-video-fargate` worker — same OperationType, different
-        worker — and stay `availability: planned` until it ships)
+        worker — now also `availability: beta` (worker deployed + wired
+        on staging, e2e-unproven, fan-out flag-gated dark))
       - `operation_type = audio_watermark` -> `ops-audio-watermark`
         queue (gated by `availability: planned` +
         `required_tier: enterprise` per
@@ -1853,12 +1856,16 @@ operations:
       The `operation-split` Lambda (lambdas pre-launch epic Wave A)
       consumes split requests routed by `operation_type=split`. Its
       `audio` + short-form `video` paths are live on staging (lambdas
-      #161 / [`vKI0CFDu`](https://trello.com/c/vKI0CFDu)); the
-      `image_gif` / `document_pdf` workers (and video `long_form` via
-      `split-video-fargate`) remain a cross-repo follow-up. Single-input —
+      #161 / [`vKI0CFDu`](https://trello.com/c/vKI0CFDu)); video
+      `long_form` (via `split-video-fargate`) is now also `beta` —
+      deployed + wired on staging but e2e-unproven, fan-out flag-gated
+      dark; the `image_gif` / `document_pdf` workers remain a cross-repo
+      follow-up. Single-input —
       `media_group` derives from the input MIME prefix per the
       existing single-input rule. `availability: beta` for the `audio`
-      and `video` (short-form) mime_groups (workers live on staging); the
+      and `video` mime_groups (short-form + long-form video both beta;
+      only short-form video reaches this `ops-split` queue — long-form
+      routes via `split-video-fargate`); the
       `image_gif` and `document_pdf` mime_groups stay `availability:
       planned`, and the API rejects their workflow-create with
       `feature_not_available` (422) until those Lambdas ship.
@@ -3554,7 +3561,9 @@ components:
         these three long-form classes are `availability: beta` (compress +
         merge per CON-1; `split.video.long_form` per
         [`rcwvUKhI`](https://trello.com/c/rcwvUKhI), worker
-        `split-video-fargate` proven on staging). `audio_overlay` long-form
+        `split-video-fargate` deployed + wired on staging but NOT yet proven
+        end-to-end — first customer-path soak incomplete, speed-up unmeasured,
+        fan-out flag-gated dark). `audio_overlay` long-form
         (reserve-name-only, no queue) is NOT yet produced and is therefore
         absent from this enum; it gets added when its publisher ships.
 
@@ -3901,6 +3910,32 @@ components:
             exclusive with `outputs[]`. Absent for multi-output operations and
             on failure.
           example: 2097152
+        output_file_type:
+          type: string
+          maxLength: 100
+          description: |
+            OPTIONAL. MIME type of the produced artifact, as reported by the worker
+            that wrote the bytes (single-output completion). Present on completion
+            only; absent on failure. Informative alongside `output_key`, not mutually
+            exclusive — single-output results MAY carry it.
+
+            Name follows the `events.yaml` MIME convention (`OperationRequest.file_type`
+            is the input MIME; `output_file_type` is the output MIME). The OpenAPI/REST
+            surface names the same concept `mime_type`.
+
+            **Purpose (future-proofing per ADR-0022).** The API consumes this MIME +
+            its deterministic MIME→extension map (`DownloadFilenameComputer`) to derive
+            the canonical download extension and the download `Content-Type` header
+            SERVER-SIDE. It is NOT the download filename (the API already has that from
+            the key). For today's traffic the API can infer the output MIME (compress is
+            same-format; the compress+format facade canonicalizes to `convert` whose
+            target is known), so this is **advisory/future-proofing** for a
+            runtime-format-selection path (e.g. `compress output_format=auto|smallest`,
+            currently `planned`/unbuilt) — landed additively now (cf. `watermark_id`) so
+            that path needs no later contract bump. Wire-only: the API derives the
+            ext/Content-Type server-side and does not echo this MIME onto the REST read
+            surface (`OperationDownload`).
+          example: "image/webp"
 
         # Multi-output success fields (per ADR-0009 MultiOutputCompletion)
         outputs:
@@ -3916,13 +3951,15 @@ components:
 
             **`maxItems: 200`** is a worst-case transport-layer defence
             against SQS/SNS's 256 KiB payload cap. Worst-case per-entry size
-            is ~1080 bytes (1024-char `output_key` at the S3 hard limit + ~55
-            bytes JSON envelope per entry); 200 entries × 1080 bytes ≈ 216
-            KB, leaving ~40 KB headroom for the outer message envelope
-            (`job_id`, `operation_id`, `metrics`, `total_output_size_bytes`,
-            etc.). Typical Lambda-generated keys are ~110 chars so the
-            realistic per-message size stays well under the cap; this bound
-            defends against the worst case, not the typical case.
+            is ~1205 bytes (1024-char `output_key` at the S3 hard limit + the
+            100-char-capped `output_file_type` + ~80 bytes JSON envelope per
+            entry); 200 entries × 1205 bytes ≈ 241 KB, leaving ~15 KB headroom
+            for the outer message envelope (`job_id`, `operation_id`,
+            `metrics`, `total_output_size_bytes`, etc.). `output_file_type` is
+            `maxLength: 100` precisely so it cannot blow this bound (real
+            produced MIMEs are <80 chars). Typical Lambda-generated keys are
+            ~110 chars so the realistic per-message size stays well under the
+            cap; this bound defends against the worst case, not the typical case.
 
             Operations that could theoretically exceed 200 outputs from one
             logical operation (e.g. convert PDF->image on a >200-page PDF)
@@ -4044,6 +4081,18 @@ components:
           minimum: 0
           description: Size of this individual output file in bytes.
           example: 262144
+        output_file_type:
+          type: string
+          maxLength: 100
+          description: |
+            OPTIONAL. MIME type of THIS individual output file, as reported by the
+            worker (per-output, multi-output operations). Authoritative per-entry for
+            multi-output (heterogeneous fan-out e.g. convert PDF→image — each entry MAY
+            differ); the top-level `output_file_type` covers the single-output shape.
+            Present on completion only. See ADR-0022 — the API derives the per-output
+            download extension + Content-Type server-side from this MIME via its
+            MIME→extension map. Future-proofing (additive now, cf. `target_id`).
+          example: "image/png"
         page_index:
           type: integer
           minimum: 1
@@ -4732,10 +4781,11 @@ components:
           `processing_class`. `media_group` derives from the input
           MIME prefix per the existing single-input rule (no
           operation-specific conditional needed). `availability: beta`
-          for the `audio` and `video` (short-form) mime_groups
-          (`image_gif` / `document_pdf` and video `long_form` stay
-          `planned`); routes via `operation_type=split`
-          to `ops-split`.
+          for the `audio` and `video` mime_groups — video activates
+          BOTH classes (`short_form` + `long_form` beta; long-form
+          deployed + wired on staging but e2e-unproven, fan-out
+          flag-gated dark). `image_gif` / `document_pdf` stay
+          `planned`. Routes via `operation_type=split` to `ops-split`.
           Per ADR-0004 + ADR-0014
           ([`vKI0CFDu`](https://trello.com/c/vKI0CFDu)).
 

package/availability/availability.json

@@ -1,5 +1,5 @@
 {
-  "capabilities_version": 93,
+  "capabilities_version": 101,
   "endpoints": {
     "DELETE /api/auth/api-keys/{apiKeyId}": {
       "auth": "required",
@@ -29,6 +29,13 @@
       "operation_id": "getUploadMetadata",
       "required_tier": null
     },
+    "GET /api/v2/account/limits": {
+      "auth": "required",
+      "availability": "stable",
+      "identity_scoped": true,
+      "operation_id": "getAccountLimits",
+      "required_tier": null
+    },
     "GET /api/v2/credits/balance": {
       "auth": "required",
       "availability": "stable",
@@ -867,7 +874,7 @@
           "options": {
             "bitrate": {
               "default": 128,
-              "description": "Output bitrate in kbps. Applies to lossy outputs (mpeg/aac/ogg/mp4) \u2014 CBR/ABR; rejected as invalid_options for lossless outputs (flac/wav, which have no bitrate target). The other knobs (channels/sample_rate/normalize) apply to all formats.\n",
+              "description": "Output bitrate in kbps (CBR/ABR). Applies to lossy OUTPUTS. Only a caller-EXPLICIT bitrate against a lossless output is rejected as invalid_options (flac/wav have no bitrate target); the `default: 128` is never the basis for a rejection (ADR-0020 D1, carried into ADR-0023 \u2014 a default a caller did not set is the server's to resolve, and is dropped for a lossless target). The output is the input format unless `output_format` re-targets it: with `output_format: original` the lossy/lossless distinction follows the input MIME (mpeg/aac/ogg/mp4 = lossy \u2192 bitrate applies; flac/wav input \u2192 an explicit bitrate is rejected); with an explicit `output_format`, it follows that target (flac/wav target \u2192 an explicit bitrate is rejected). Not expressed as `depends_on` \u2014 the lossy-output condition is an output-value \u00d7 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.\n",
               "type": "enum",
               "value_type": "integer",
               "values": [
@@ -890,6 +897,19 @@
               "description": "Apply loudness normalization (EBU R128 / -14 LUFS target)",
               "type": "boolean"
             },
+            "output_format": {
+              "default": "original",
+              "description": "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.",
+              "type": "enum",
+              "values": [
+                "original",
+                "mp3",
+                "aac",
+                "ogg",
+                "flac",
+                "wav"
+              ]
+            },
             "sample_rate": {
               "description": "Audio sample rate in Hz",
               "type": "enum",
@@ -1077,7 +1097,24 @@
             },
             "output_format": {
               "default": "original",
-              "description": "Output format. original = keep input format, auto = best for browser support (AVIF > WebP > JPEG based on Accept header hint), smallest = try all supported formats and return the smallest file",
+              "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.",
+              "per_value_availability": {
+                "auto": {
+                  "availability": "planned"
+                },
+                "avif": {
+                  "availability": "planned"
+                },
+                "jpeg": {
+                  "availability": "planned"
+                },
+                "png": {
+                  "availability": "planned"
+                },
+                "smallest": {
+                  "availability": "planned"
+                }
+              },
               "type": "enum",
               "values": [
                 "original",
@@ -1119,8 +1156,14 @@
           ],
           "options": {
             "audio_bitrate": {
-              "default": 128,
-              "description": "Audio track bitrate in kbps",
+              "depends_on": {
+                "audio_codec": [
+                  "aac",
+                  "opus",
+                  "vorbis"
+                ]
+              },
+              "description": "Audio track bitrate in kbps. Only valid with an explicit re-encode audio_codec (aac/opus/vorbis): an explicit audio_bitrate with audio_codec `copy`/omitted is rejected as `invalid_options` at workflow-create (the API enforces this `depends_on`); copy preserves the source bitrate. FE/SDK also prune it pre-submit. No default: a bitrate is only meaningful on an explicit re-encode (matches the worker, which applies none).\n",
               "type": "enum",
               "value_type": "integer",
               "values": [
@@ -1134,7 +1177,7 @@
             },
             "audio_codec": {
               "default": "copy",
-              "description": "Audio codec. copy = passthrough (keep the source audio stream as-is; re-encode only on explicit request) \u2014 aac = widest compatibility, opus = best quality/size. Default is `copy` (ADR-0020 D7): it MATCHES the worker's actual absent-audio behaviour and is container-safe for compress (output container = input container, so the source stream is already compatible). Set an explicit codec to re-encode; an explicit codec the output container cannot carry (e.g. aac on a WebM output) returns invalid_options. A DEFAULT value is never rejected. See FORMAT.md \"Container-conditional defaults\" + ADR-0020.\n",
+              "description": "Audio codec. copy = passthrough (keep the source stream as-is; re-encode only on explicit request) \u2014 aac/opus/vorbis re-encode. Default is `copy` (ADR-0020 D7, carried into ADR-0023): on the same-container path (`output_format` original/absent) the source stream is already container-compatible, so copy is safe. When `output_format` RE-TARGETS the container, an absent/default audio_codec resolves to a container-valid codec via the facade (e.g. webm -> opus), NOT a blind copy of an incompatible stream \u2014 a DEFAULT is never rejected (the exact per-container resolution, incl. ogg vorbis-vs-opus, is an output_format stable-flip prerequisite, ADR-0023 D5). A caller-EXPLICIT codec the resolved container cannot carry (e.g. aac on a webm target) returns invalid_options. See FORMAT.md \"Container-conditional defaults\" + ADR-0023 (supersedes ADR-0020).\n",
               "type": "enum",
               "values": [
                 "aac",
@@ -1145,7 +1188,7 @@
             },
             "codec": {
               "default": "h264",
-              "description": "Video codec. h264 = widest compatibility, h265/av1 = better compression but slower. The default (h264) is the MP4/MOV standard and is CONTAINER-CONDITIONAL: for an output container that cannot carry it (e.g. WebM, which carries VP8/VP9/AV1) the server resolves a container-valid codec (WebM -> vp9). A DEFAULT value is never rejected; only a caller-EXPLICIT incompatible codec returns invalid_options. See FORMAT.md \"Container-conditional defaults\" + ADR-0020.\n",
+              "description": "Video codec. h264 = widest compatibility, h265/av1 = better compression but slower. The default (h264) is the MP4/MOV standard and is CONTAINER-CONDITIONAL against the RESOLVED output container (the explicit `output_format` if set, else the input container): for a container that cannot carry it (e.g. WebM, which carries VP8/VP9/ AV1) the server resolves a container-valid codec (WebM -> vp9). A DEFAULT value is never rejected \u2014 including an explicit `output_format: webm` left at the default `h264` (resolves to vp9, NOT invalid_options); only a caller-EXPLICIT incompatible codec returns invalid_options. See FORMAT.md \"Container-conditional defaults\" + ADR-0023 (supersedes ADR-0020).\n",
               "type": "enum",
               "values": [
                 "h264",
@@ -1166,7 +1209,12 @@
             },
             "encoding_mode": {
               "default": "crf",
-              "description": "crf = constant quality (variable file size), target_size = constrained file size",
+              "description": "crf = constant quality (variable file size). target_size = constrained file size \u2014 `planned`: the worker does not yet implement the two-pass encode (it rejects target_size); crf only today.",
+              "per_value_availability": {
+                "target_size": {
+                  "availability": "planned"
+                }
+              },
               "type": "enum",
               "values": [
                 "crf",
@@ -1175,7 +1223,7 @@
             },
             "faststart": {
               "default": true,
-              "description": "Move the MP4/MOV moov atom to start for progressive web playback. MP4/MOV only. CONTAINER-CONDITIONAL: the default (true) is silently inapplicable for a container with no moov atom (e.g. WebM) \u2014 that is NOT a rejection. Only a caller-EXPLICIT faststart:true on such a container returns invalid_options. See FORMAT.md \"Container-conditional defaults\" + ADR-0020.\n",
+              "description": "Move the MP4/MOV moov atom to start for progressive web playback. MP4/MOV only. CONTAINER-CONDITIONAL against the RESOLVED output container (the explicit `output_format` if set, else the input): the default (true) is silently inapplicable for a container with no moov atom (e.g. WebM) \u2014 that is NOT a rejection. Only a caller-EXPLICIT faststart:true on such a container returns invalid_options. See FORMAT.md \"Container-conditional defaults\" + ADR-0023 (supersedes ADR-0020).\n",
               "type": "boolean"
             },
             "fit": {
@@ -1206,6 +1254,28 @@
               "min": 2,
               "type": "integer"
             },
+            "output_format": {
+              "default": "original",
+              "description": "Output container. original = keep the input container (default, same-format compression). Non-`original` values re-target the container via the API \"compress+format\" facade (one canonicalized convert-with-size-cap pass); see per_value_availability + ADR-0023 + FORMAT.md. When set, the RESOLVED target container determines the valid codec/audio_codec/faststart sets \u2014 an absent/default codec resolves to a container-valid one (e.g. webm -> vp9) and is never rejected; only a caller-EXPLICIT incompatible value is invalid_options.",
+              "per_value_availability": {
+                "mp4": {
+                  "availability": "planned"
+                },
+                "ogg": {
+                  "availability": "planned"
+                },
+                "webm": {
+                  "availability": "planned"
+                }
+              },
+              "type": "enum",
+              "values": [
+                "original",
+                "mp4",
+                "webm",
+                "ogg"
+              ]
+            },
             "preset": {
               "default": "medium",
               "description": "Encoding speed vs compression ratio trade-off",
@@ -1223,10 +1293,11 @@
               ]
             },
             "target_size_bytes": {
+              "availability": "planned",
               "depends_on": {
                 "encoding_mode": "target_size"
               },
-              "description": "Target output file size in bytes (min 1MB).",
+              "description": "Target output file size in bytes (min 1MB). `planned` \u2014 the worker does not yet implement the two-pass target-size encode.",
               "min": 1048576,
               "type": "integer"
             },
@@ -1421,7 +1492,14 @@
           ],
           "options": {
             "codec": {
-              "description": "Video codec for target format. Defaults to the format's standard codec (no literal default \u2014 the required output_format determines it). This is the container-conditional-default principle applied via an explicit container choice. See FORMAT.md \"Container-conditional defaults\" + ADR-0020.\n",
+              "depends_on": {
+                "output_format": [
+                  "mp4",
+                  "webm",
+                  "ogg"
+                ]
+              },
+              "description": "Video codec for target format. Defaults to the format's standard codec (no literal default \u2014 the required output_format determines it). This is the container-conditional-default principle applied via an explicit container choice. See FORMAT.md \"Container-conditional defaults\" + ADR-0023 (supersedes ADR-0020). Not applicable to a `gif` output (no video codec): an explicit `codec` on a `gif` output is rejected as `invalid_options` at workflow-create (the API enforces this `depends_on`); FE/SDK prune it pre-submit.\n",
               "type": "enum",
               "values": [
                 "h264",
@@ -1443,7 +1521,14 @@
             },
             "quality": {
               "default": 23,
-              "description": "CRF value (0 = lossless, 51 = worst)",
+              "depends_on": {
+                "output_format": [
+                  "mp4",
+                  "webm",
+                  "ogg"
+                ]
+              },
+              "description": "CRF value (0 = lossless, 51 = worst). Video outputs only \u2014 NOT applicable to a `gif` output (frame extraction has no CRF). An explicit `quality` on a `gif` output is rejected as `invalid_options` at workflow-create (the API enforces this `depends_on`); FE/SDK prune it pre-submit.\n",
               "max": 51,
               "min": 0,
               "type": "integer"
@@ -2528,7 +2613,7 @@
     "split": {
       "availability": "beta",
       "default": false,
-      "description": "Fan one input file into N outputs across GIF, PDF, audio, and\nvideo MIME families. Single-input \u2014 one input file per job, fanned\ninto N outputs per the per-mime-group catalog. Mirrors the\n`merge` / `convert` catalog-split-by-mime-group pattern.\n\n**Three shared modes** (audio + video; the mode discriminator\ngates which option applies per the `depends_on` rules in this\nschema):\n- `interval`: split every N numeric-seconds.\n- `count`: split into N equal-duration pieces (integer 2..=200).\n- `cut_points`: explicit cut points in numeric-seconds (strictly\n  increasing, no duplicates, each > 0 and < probed duration).\n\n**Plus an audio-only `silence` mode** (`beta`, gated by the\n`silence_mode_audio` feature): cut at detected silence gaps via\nthe worker's ffmpeg `silencedetect` filter. Video stays\nthree-mode.\n\n**GIF + PDF use range-based selection** instead of three modes:\n- GIF (`image_gif`): `frame_range` REQUIRED + `output_format`\n  enum {png,webp,jpg}.\n- PDF (`document_pdf`): `page_range` OR `page_groups` (mutually\n  exclusive per `depends_on`).\n\n**Wire format**: numeric seconds (floats allowed for sub-second\nprecision). NOT ISO 8601 duration strings. Matches FFmpeg /\nCloudinary / Shotstack / AWS MediaConvert conventions.\n\n**200-output hard cap** per ADR-0009 \u00a7D5\n(`OperationResult.outputs[].maxItems: 200`). Preflight rejects\nrequests exceeding this BEFORE work as `invalid_options` (422).\nCap math by mode:\n- `interval`: `ceil(probed_duration / interval) <= 200`\n- `count`: enforced by the option's `min: 2 max: 200` range\n- `cut_points`: `cut_points.len() + 1 <= 200`\n- `silence` (audio): resolved segment count (detected gaps + 1)\n  `<= 200`; preflight rejects as `invalid_options` (422)\n- PDF: resolved page count after expansion `<= 200`\n  (cross-ref [`WgCqnMRa`](https://trello.com/c/WgCqnMRa))\n- GIF: resolved frame count after expansion `<= 200`\n\n**Output naming**: 3-digit zero-padded \u2014 `output-001` ..\n`output-200`. Matches the convert PDF\u2192N precedent.\n\n**Output envelope binding** (per ADR-0014 + ADR-0009 \u00a7D2):\n- `image_gif`: `PositionIndexed` (frame stream-position 0-based\n  ordinal)\n- `document_pdf`: `PageIndexed` (1-based gapless page index)\n- `audio`: `PositionIndexed` (cut stream-position ordinal)\n- `video`: `PositionIndexed` (cut stream-position ordinal)\n\n**`precision` flag** (audio + video only): `fast` (default) =\npacket-boundary approximate cuts; `exact` = re-encode-aligned\nprecise cuts. Mime_group scoping is the gate \u2014 precision does\nNOT apply to GIF or PDF (frame extraction is exact and PDF page\nselection is exact by definition).\n\n**Long-form video** routes to a separate `split-video-fargate`\nLambda (same `split` OperationType, different worker; routing\nvia `processing_class`). No schema-side discriminator beyond MIME\ndetection + `processing_class`.\n\n`availability: beta` for the `audio` and `video` mime_groups\n(workers live on staging \u2014 shape-stable + opt-in, MUST NOT 422).\nVideo activates **both classes**: `video.processing_class.short_form`\nAND `long_form` are `beta` \u2014 the `split-video-fargate` worker is proven\non staging (4GB+ HEVC input \u2192 keyframe-aligned segments;\n[`rcwvUKhI`](https://trello.com/c/rcwvUKhI)). The `image_gif` and\n`document_pdf` mime_groups stay `availability: planned` until their\ncross-repo Lambda workers ship ([`vKI0CFDu`](https://trello.com/c/vKI0CFDu)\n+ lambdas L1); dispatch returns `feature_not_available` (422) for the\nstill-planned groups/classes until then.\n\nPer ADR-0014.\n",
+      "description": "Fan one input file into N outputs across GIF, PDF, audio, and\nvideo MIME families. Single-input \u2014 one input file per job, fanned\ninto N outputs per the per-mime-group catalog. Mirrors the\n`merge` / `convert` catalog-split-by-mime-group pattern.\n\n**Three shared modes** (audio + video; the mode discriminator\ngates which option applies per the `depends_on` rules in this\nschema):\n- `interval`: split every N numeric-seconds.\n- `count`: split into N equal-duration pieces (integer 2..=200).\n- `cut_points`: explicit cut points in numeric-seconds (strictly\n  increasing, no duplicates, each > 0 and < probed duration).\n\n**Plus an audio-only `silence` mode** (`beta`, gated by the\n`silence_mode_audio` feature): cut at detected silence gaps via\nthe worker's ffmpeg `silencedetect` filter. Video stays\nthree-mode.\n\n**GIF + PDF use range-based selection** instead of three modes:\n- GIF (`image_gif`): `frame_range` REQUIRED + `output_format`\n  enum {png,webp,jpg}.\n- PDF (`document_pdf`): `page_range` OR `page_groups` (mutually\n  exclusive per `depends_on`).\n\n**Wire format**: numeric seconds (floats allowed for sub-second\nprecision). NOT ISO 8601 duration strings. Matches FFmpeg /\nCloudinary / Shotstack / AWS MediaConvert conventions.\n\n**200-output hard cap** per ADR-0009 \u00a7D5\n(`OperationResult.outputs[].maxItems: 200`). Preflight rejects\nrequests exceeding this BEFORE work as `invalid_options` (422).\nCap math by mode:\n- `interval`: `ceil(probed_duration / interval) <= 200`\n- `count`: enforced by the option's `min: 2 max: 200` range\n- `cut_points`: `cut_points.len() + 1 <= 200`\n- `silence` (audio): resolved segment count (detected gaps + 1)\n  `<= 200`; preflight rejects as `invalid_options` (422)\n- PDF: resolved page count after expansion `<= 200`\n  (cross-ref [`WgCqnMRa`](https://trello.com/c/WgCqnMRa))\n- GIF: resolved frame count after expansion `<= 200`\n\n**Output naming**: 3-digit zero-padded \u2014 `output-001` ..\n`output-200`. Matches the convert PDF\u2192N precedent.\n\n**Output envelope binding** (per ADR-0014 + ADR-0009 \u00a7D2):\n- `image_gif`: `PositionIndexed` (frame stream-position 0-based\n  ordinal)\n- `document_pdf`: `PageIndexed` (1-based gapless page index)\n- `audio`: `PositionIndexed` (cut stream-position ordinal)\n- `video`: `PositionIndexed` (cut stream-position ordinal)\n\n**`precision` flag** (audio + video only): `fast` (default) =\npacket-boundary approximate cuts; `exact` = re-encode-aligned\nprecise cuts. Mime_group scoping is the gate \u2014 precision does\nNOT apply to GIF or PDF (frame extraction is exact and PDF page\nselection is exact by definition).\n\n**Long-form video** routes to a separate `split-video-fargate`\nLambda (same `split` OperationType, different worker; routing\nvia `processing_class`). No schema-side discriminator beyond MIME\ndetection + `processing_class`.\n\n`availability: beta` for the `audio` and `video` mime_groups\n(workers live on staging \u2014 shape-stable + opt-in, MUST NOT 422).\nVideo activates **both classes**: `video.processing_class.short_form`\nAND `long_form` are `beta` \u2014 the `split-video-fargate` worker is\ndeployed + wired on staging but NOT yet proven end-to-end\n([`rcwvUKhI`](https://trello.com/c/rcwvUKhI); the first customer-path\nsoak has not completed and the 4GB+ speed-up is unmeasured; the\nlong-form fan-out is flag-gated dark). The `image_gif` and\n`document_pdf` mime_groups stay `availability: planned` until their\ncross-repo Lambda workers ship ([`vKI0CFDu`](https://trello.com/c/vKI0CFDu)\n+ lambdas L1); dispatch returns `feature_not_available` (422) for the\nstill-planned groups/classes until then.\n\nPer ADR-0014.\n",
       "features": {
         "silence_mode_audio": {
           "availability": "beta",
@@ -3316,7 +3401,7 @@
       }
     }
   },
-  "schema_version": "2.68.0",
+  "schema_version": "2.78.0",
   "source_commit": null,
   "user_tier": null,
   "workflow_features": {

package/dist/asyncapi/Failure.d.ts

@@ -14,6 +14,7 @@ interface Failure {
     'output_bucket'?: string;
     'output_key'?: string;
     'output_size_bytes'?: number;
+    'output_file_type'?: string;
     'outputs'?: (PageIndexed | PositionIndexed | Unindexed)[];
     'total_output_size_bytes'?: number;
     'metrics'?: OperationMetrics;

package/dist/asyncapi/MultiOutputCompletion.d.ts

@@ -14,6 +14,7 @@ interface MultiOutputCompletion {
     'output_bucket': string;
     'output_key'?: string;
     'output_size_bytes'?: number;
+    'output_file_type'?: string;
     'outputs': (PageIndexed | PositionIndexed | Unindexed)[];
     'total_output_size_bytes': number;
     'metrics'?: OperationMetrics;

package/dist/asyncapi/PageIndexed.d.ts

@@ -1,6 +1,7 @@
 interface PageIndexed {
     'output_key': string;
     'output_size_bytes': number;
+    'output_file_type'?: string;
     'page_index': number;
     'position'?: number;
     'target_id'?: string;

package/dist/asyncapi/PositionIndexed.d.ts

@@ -1,6 +1,7 @@
 interface PositionIndexed {
     'output_key': string;
     'output_size_bytes': number;
+    'output_file_type'?: string;
     'page_index'?: number;
     'position': number;
     'target_id'?: string;

package/dist/asyncapi/SingleOutputCompletion.d.ts

@@ -14,6 +14,7 @@ interface SingleOutputCompletion {
     'output_bucket': string;
     'output_key': string;
     'output_size_bytes': number;
+    'output_file_type'?: string;
     'outputs'?: (PageIndexed | PositionIndexed | Unindexed)[];
     'total_output_size_bytes'?: number;
     'metrics'?: OperationMetrics;

package/dist/asyncapi/Unindexed.d.ts

@@ -1,6 +1,7 @@
 interface Unindexed {
     'output_key': string;
     'output_size_bytes': number;
+    'output_file_type'?: string;
     'page_index'?: number;
     'position'?: number;
     'target_id'?: string;

package/dist/openapi/models/AccountLimitEntry.d.ts

@@ -0,0 +1,54 @@
+/**
+ * GISL Compression API
+ * REST API for the GISL (Give It Smaller) file compression and processing service.  **Architecture:** - Upload files to get a `file_id` - Create workflows referencing uploaded files with operations (compress, thumbnail, image_watermark, text_watermark, merge, archive, convert, custom_luma, audio_overlay, audio_watermark) - Poll status, stream SSE events, or receive webhook callbacks - Download results per operation output  **Response envelope:** All mutation and query endpoints return `{ success: true, data: {...} }` on success and `{ success: false, error: \"...\", details: [...] }` on failure. Exceptions: `GET /api/operations/schema` returns raw JSON (per-tier private caching with ETag revalidation per ADR-0002 + I3), health probes return flat objects, and `POST /api/contact` returns 204 with no body.  **Availability metadata.** This spec uses the `x-availability` vendor extension as **decorative documentation only**. Per [ADR-0001](../docs/decisions/0001-contract-first-availability.md) §1.5, the runtime endpoint `GET /api/operations/schema` (ticket I3) is the authoritative source; the sidecar `availability.json` (ticket I3b) is the authoritative companion (generated, never hand-edited; CI cross-checks runtime ⇄ sidecar). SDKs MUST NOT depend on `x-availability` reaching generated code — code-generators that surface vendor extensions may emit it as documentation, but consumers read availability from the runtime endpoint, not from the generated bindings.  The 5-value vocabulary (`stable | beta | experimental | planned | deprecated`) is defined in the `AvailabilityValue` schema. See `schemas/FORMAT.md` §Availability Taxonomy for the operational rules (parser obligation: absent = stable; per-enum-value granularity is the `per_value_availability` primitive landed via ticket I17).  **Localisation (per ticket [I26](https://trello.com/c/rcnqwgI4)).**  Error responses + paused/blocked workflow statuses carry a localised human-readable `message` alongside a stable, never-localised `message_key`. Machine-readable fields (`error`, enum values, status codes) stay canonical English.  - **Currently committed locales:** `en-GB` only (per ticket   [`4GKyuYo6`](https://trello.com/c/4GKyuYo6)). The I26 carrier   shape (`Accept-Language` + `Content-Language` + `Vary` headers +   `locale` envelope field + `message_key` + `message_params`) is   stable and exercised; the **catalog** of translated `message`   strings is en-GB-only at runtime today. Additional locales (e.g.   `pt-PT`) will be advertised by name when their catalogs ship —   the request/response carrier shape does NOT change when a new   locale lands. Treat unrequested locales as \"machine-code +   `message_key` path is committed; localised `message` prose is   not\" until this prose enumerates them by name. - **Request:** `Accept-Language` header per RFC 9110 §12.5.4 (q-value   negotiation supported). The server selects the best-match locale   from its supported list; falls back to `en-GB` when no match —   which, until additional catalogs land, is every non-`en-GB`   `Accept-Language`. - **Response:** `Content-Language: <locale>` echo on every localised   response; `Vary: Accept-Language` on every response (CDN/cache   correctness — different `Accept-Language` requests produce   different responses). `Vary` is emitted unconditionally so the   header contract does not flip when a second locale ships. - **Fallback locale:** `en-GB` (also the canonical locale for   `message_key` translations and English `message` prose). - **SDK guidance:** switch on `error` (machine code) for typed   error branches; surface `message_key` to client-side i18n   catalogs (SDK companion work tracked at X19, cross-repo);   display `message` for end-user UI; **never parse `message` for   control flow** — it changes per locale.  Carrier shape lives on `ErrorEnvelope` (envelope-level optional `message_key` + `message` + `locale` + `message_params`) and `ValidationErrorEnvelope` (also per-`details[]` entry). Existing 402 / 403 / 422 envelopes (`BalanceExhaustedResponse`, `FeatureNotAvailableResponse`, `FeatureTierRestrictedResponse`, `WorkflowPausedDetail`) inherit the convention.  **Upload thresholds (per tickets [u0ar7Yye](https://trello.com/c/u0ar7Yye) + [58nBQLWQ](https://trello.com/c/58nBQLWQ)).** Canonical upload constants (single-shot cap, multipart chunk size, multipart concurrency default, multipart first-chunk size) live on the `UploadThresholds` schema with `const:`-pinned values. SDK generators emit these as typed binding constants so frontend / API / SDKs reference one source 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.
+ *
+ * The version of the OpenAPI document: 2.78.0
+ *
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+/**
+ * One account limit: the effective value (override ?? tier default),
+ * the tier default, and whether a per-account override is active. The
+ * override mechanism / store is NOT exposed — only the resolved
+ * numbers plus the `overridden` flag.
+ *
+ * @export
+ * @interface AccountLimitEntry
+ */
+export interface AccountLimitEntry {
+    /**
+     * The cap in force for this account, in bytes
+     * (`override ?? tier_default`).
+     *
+     * @type {number}
+     * @memberof AccountLimitEntry
+     */
+    effective: number;
+    /**
+     * The tier's default cap for this limit, in bytes (already public
+     * via the tier model).
+     *
+     * @type {number}
+     * @memberof AccountLimitEntry
+     */
+    tierDefault: number;
+    /**
+     * True iff a per-account override is active (i.e. `effective`
+     * comes from an override rather than the tier default).
+     *
+     * @type {boolean}
+     * @memberof AccountLimitEntry
+     */
+    overridden: boolean;
+}
+/**
+ * Check if a given object implements the AccountLimitEntry interface.
+ */
+export declare function instanceOfAccountLimitEntry(value: object): value is AccountLimitEntry;
+export declare function AccountLimitEntryFromJSON(json: any): AccountLimitEntry;
+export declare function AccountLimitEntryFromJSONTyped(json: any, ignoreDiscriminator: boolean): AccountLimitEntry;
+export declare function AccountLimitEntryToJSON(json: any): AccountLimitEntry;
+export declare function AccountLimitEntryToJSONTyped(value?: AccountLimitEntry | null, ignoreDiscriminator?: boolean): any;

package/dist/openapi/models/AccountLimitEntry.js

@@ -0,0 +1,51 @@
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * GISL Compression API
+ * REST API for the GISL (Give It Smaller) file compression and processing service.  **Architecture:** - Upload files to get a `file_id` - Create workflows referencing uploaded files with operations (compress, thumbnail, image_watermark, text_watermark, merge, archive, convert, custom_luma, audio_overlay, audio_watermark) - Poll status, stream SSE events, or receive webhook callbacks - Download results per operation output  **Response envelope:** All mutation and query endpoints return `{ success: true, data: {...} }` on success and `{ success: false, error: \"...\", details: [...] }` on failure. Exceptions: `GET /api/operations/schema` returns raw JSON (per-tier private caching with ETag revalidation per ADR-0002 + I3), health probes return flat objects, and `POST /api/contact` returns 204 with no body.  **Availability metadata.** This spec uses the `x-availability` vendor extension as **decorative documentation only**. Per [ADR-0001](../docs/decisions/0001-contract-first-availability.md) §1.5, the runtime endpoint `GET /api/operations/schema` (ticket I3) is the authoritative source; the sidecar `availability.json` (ticket I3b) is the authoritative companion (generated, never hand-edited; CI cross-checks runtime ⇄ sidecar). SDKs MUST NOT depend on `x-availability` reaching generated code — code-generators that surface vendor extensions may emit it as documentation, but consumers read availability from the runtime endpoint, not from the generated bindings.  The 5-value vocabulary (`stable | beta | experimental | planned | deprecated`) is defined in the `AvailabilityValue` schema. See `schemas/FORMAT.md` §Availability Taxonomy for the operational rules (parser obligation: absent = stable; per-enum-value granularity is the `per_value_availability` primitive landed via ticket I17).  **Localisation (per ticket [I26](https://trello.com/c/rcnqwgI4)).**  Error responses + paused/blocked workflow statuses carry a localised human-readable `message` alongside a stable, never-localised `message_key`. Machine-readable fields (`error`, enum values, status codes) stay canonical English.  - **Currently committed locales:** `en-GB` only (per ticket   [`4GKyuYo6`](https://trello.com/c/4GKyuYo6)). The I26 carrier   shape (`Accept-Language` + `Content-Language` + `Vary` headers +   `locale` envelope field + `message_key` + `message_params`) is   stable and exercised; the **catalog** of translated `message`   strings is en-GB-only at runtime today. Additional locales (e.g.   `pt-PT`) will be advertised by name when their catalogs ship —   the request/response carrier shape does NOT change when a new   locale lands. Treat unrequested locales as \"machine-code +   `message_key` path is committed; localised `message` prose is   not\" until this prose enumerates them by name. - **Request:** `Accept-Language` header per RFC 9110 §12.5.4 (q-value   negotiation supported). The server selects the best-match locale   from its supported list; falls back to `en-GB` when no match —   which, until additional catalogs land, is every non-`en-GB`   `Accept-Language`. - **Response:** `Content-Language: <locale>` echo on every localised   response; `Vary: Accept-Language` on every response (CDN/cache   correctness — different `Accept-Language` requests produce   different responses). `Vary` is emitted unconditionally so the   header contract does not flip when a second locale ships. - **Fallback locale:** `en-GB` (also the canonical locale for   `message_key` translations and English `message` prose). - **SDK guidance:** switch on `error` (machine code) for typed   error branches; surface `message_key` to client-side i18n   catalogs (SDK companion work tracked at X19, cross-repo);   display `message` for end-user UI; **never parse `message` for   control flow** — it changes per locale.  Carrier shape lives on `ErrorEnvelope` (envelope-level optional `message_key` + `message` + `locale` + `message_params`) and `ValidationErrorEnvelope` (also per-`details[]` entry). Existing 402 / 403 / 422 envelopes (`BalanceExhaustedResponse`, `FeatureNotAvailableResponse`, `FeatureTierRestrictedResponse`, `WorkflowPausedDetail`) inherit the convention.  **Upload thresholds (per tickets [u0ar7Yye](https://trello.com/c/u0ar7Yye) + [58nBQLWQ](https://trello.com/c/58nBQLWQ)).** Canonical upload constants (single-shot cap, multipart chunk size, multipart concurrency default, multipart first-chunk size) live on the `UploadThresholds` schema with `const:`-pinned values. SDK generators emit these as typed binding constants so frontend / API / SDKs reference one source 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.
+ *
+ * The version of the OpenAPI document: 2.78.0
+ *
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+/**
+ * Check if a given object implements the AccountLimitEntry interface.
+ */
+export function instanceOfAccountLimitEntry(value) {
+    if (!('effective' in value) || value['effective'] === undefined)
+        return false;
+    if (!('tierDefault' in value) || value['tierDefault'] === undefined)
+        return false;
+    if (!('overridden' in value) || value['overridden'] === undefined)
+        return false;
+    return true;
+}
+export function AccountLimitEntryFromJSON(json) {
+    return AccountLimitEntryFromJSONTyped(json, false);
+}
+export function AccountLimitEntryFromJSONTyped(json, ignoreDiscriminator) {
+    if (json == null) {
+        return json;
+    }
+    return {
+        'effective': json['effective'],
+        'tierDefault': json['tier_default'],
+        'overridden': json['overridden'],
+    };
+}
+export function AccountLimitEntryToJSON(json) {
+    return AccountLimitEntryToJSONTyped(json, false);
+}
+export function AccountLimitEntryToJSONTyped(value, ignoreDiscriminator = false) {
+    if (value == null) {
+        return value;
+    }
+    return {
+        'effective': value['effective'],
+        'tier_default': value['tierDefault'],
+        'overridden': value['overridden'],
+    };
+}