@giveitsmaller/contracts 0.58.0 → 0.60.0

package/accepted-options/accepted-options.json

@@ -1088,6 +1088,19 @@
         },
         "output_format_option": null
       },
+      "document_epub": {
+        "accepted_options": {
+          "*": [
+            "fit",
+            "format",
+            "height",
+            "quality",
+            "source",
+            "width"
+          ]
+        },
+        "output_format_option": null
+      },
       "image": {
         "accepted_options": {
           "*": [
@@ -1187,5 +1200,5 @@
       }
     }
   },
-  "schema_version": "2.171.0"
+  "schema_version": "2.188.0"
 }

package/accepted-options/image-output-routes.json

@@ -246,5 +246,5 @@
       "source_op": "compress"
     }
   },
-  "schema_version": "2.171.0"
+  "schema_version": "2.188.0"
 }

package/asyncapi/events.yaml

@@ -4186,9 +4186,13 @@ components:
 
             **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
+            the canonical download extension SERVER-SIDE (it does NOT set
+            `Content-Type` from this field). It is NOT the download filename — the API synthesises that
+            from the upload's `original_name`, and `output_file_type` feeds only the
+            download EXTENSION (see `OperationDownload.filename` in
+            `openapi/api.yaml` for the full synthesis; the presigner sets
+            `Content-Disposition`, and `Content-Type` is not derived from this
+            field). 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`,
@@ -4199,7 +4203,7 @@ components:
             completion-result surface as `OperationResult.mime_type` (advisory/optional —
             the OpenAPI surface names the concept `mime_type`), so the client can name the
             server-chosen format for the savings readout. The download `OperationDownload`
-            schema still carries no echo: the API derives its ext/Content-Type server-side.
+            schema still carries no echo: the API derives its download extension server-side.
           example: "image/webp"
 
         # Multi-output success fields (per ADR-0009 MultiOutputCompletion)
@@ -4355,16 +4359,20 @@ components:
             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`).
+            download extension server-side from this MIME via its
+            MIME→extension map (it does NOT set `Content-Type` from this field;
+            the presigner sets `Content-Disposition` only). Future-proofing (additive now, cf. `target_id`).
           example: "image/png"
         page_index:
           type: integer
           minimum: 1
           description: |
-            1-based page number for PDF-page outputs. Gapless within an
-            operation (an N-page conversion emits `page_index` 1..N). Mutually
-            exclusive with `position`. Per ADR-0009 §D2.
+            1-based **literal source page number** for PDF-page outputs —
+            the actual page from the input PDF. A full conversion emits `1..N`;
+            a sparse `pages` selection (e.g. `'1-5,8'`) emits exactly the
+            selected pages (`1,2,3,4,5,8`) — gapless ONLY for a full conversion.
+            Mutually exclusive with `position`. Normative semantics:
+            ADR-0009 §D2.
           example: 1
         position:
           type: integer
@@ -5444,6 +5452,23 @@ components:
         - invalid_key: Storage key is malformed
         - invalid_request: Operation request validation failed
         - s3_access_denied: Storage access denied (IAM/permissions) — fail-fast; a 403 never clears on retry
+        - input_too_large: Input exceeds our PROCESSING limits (e.g. decoded pixel
+          budget) — deterministic; the same file is refused forever. User-actionable:
+          downscale, or a tier with a higher ceiling. **Distinct from the byte caps**
+          (`max_input_size_bytes`), which the API enforces at CREATE and 422s — those
+          never reach a worker, so a worker-emitted `input_too_large` can only ever
+          mean a processing limit found at decode time. **Do not use `decode_failed`
+          for this**: that means "we could not parse the file" and renders to the
+          customer as "it may be corrupted", which accuses a clean file.
+        - never_started: The operation was terminated WITHOUT EVER RUNNING, because the
+          job it belonged to reached a terminal state first — either an upstream/same-job
+          operation failed, **or the workflow was cancelled**. Deliberately named for what
+          happened to THIS operation rather than for the cause: a cause-named code
+          (`upstream_failed`) would be FALSE on the cancel path, where nothing upstream
+          failed and the user simply pressed cancel. **Uniquely in this enum, no worker
+          emits it** — the API derives it from job state, so do not look for the worker
+          that produces it. Non-retryable: retrying an operation that never ran is
+          meaningless; the caller re-submits the workflow.
         - unknown: Unclassified error
       enum:
         - s3_download_failed
@@ -5460,4 +5485,6 @@ components:
         - missing_source
         - invalid_key
         - invalid_request
+        - input_too_large
+        - never_started
         - unknown

package/availability/availability.json

@@ -1,5 +1,5 @@
 {
-  "capabilities_version": 168,
+  "capabilities_version": 178,
   "endpoints": {
     "DELETE /api/auth/api-keys/{apiKeyId}": {
       "auth": "required",
@@ -253,6 +253,13 @@
       "operation_id": "createWorkflow",
       "required_tier": null
     },
+    "POST /api/workflows/{id}/archive": {
+      "auth": "required",
+      "availability": "stable",
+      "identity_scoped": true,
+      "operation_id": "archiveWorkflow",
+      "required_tier": null
+    },
     "POST /api/workflows/{id}/cancel": {
       "auth": "required",
       "availability": "stable",
@@ -260,6 +267,13 @@
       "operation_id": "cancelWorkflow",
       "required_tier": null
     },
+    "POST /api/workflows/{id}/restore": {
+      "auth": "required",
+      "availability": "stable",
+      "identity_scoped": true,
+      "operation_id": "restoreWorkflow",
+      "required_tier": null
+    },
     "POST /api/workflows/{id}/resume": {
       "auth": "required",
       "availability": "stable",
@@ -408,7 +422,6 @@
             },
             "min_silence_ms": {
               "availability": "planned",
-              "default": 500,
               "description": "Minimum silence duration (milliseconds) to qualify as an\nanchor region for `sync_to_silence`. Inert until that\nfeature flips to stable.\n",
               "max": 30000,
               "min": 50,
@@ -438,7 +451,6 @@
             },
             "silence_threshold_db": {
               "availability": "planned",
-              "default": -50.0,
               "description": "Silence threshold (dB) for the `sync_to_silence` feature.\nBase audio below this level for at least `min_silence_ms`\nqualifies as a silence region into which the overlay can\nbe anchored. Inert until\n`features.sync_to_silence.availability` flips to stable.\n",
               "max": -10.0,
               "min": -80.0,
@@ -564,7 +576,6 @@
             },
             "min_silence_ms": {
               "availability": "planned",
-              "default": 500,
               "description": "Minimum silence duration (milliseconds) for\n`sync_to_silence`. Inert until that feature flips to\nstable.\n",
               "max": 30000,
               "min": 50,
@@ -604,7 +615,6 @@
             },
             "silence_threshold_db": {
               "availability": "planned",
-              "default": -50.0,
               "description": "Silence threshold (dB) for `sync_to_silence`. Inert\nuntil that feature flips to stable.\n",
               "max": -10.0,
               "min": -80.0,
@@ -669,6 +679,7 @@
       "max_inputs": 2,
       "mime_groups": {
         "audio": {
+          "max_input_duration": "PT2H",
           "mimes": [
             "audio/mpeg",
             "audio/aac",
@@ -964,13 +975,13 @@
           }
         },
         "document_epub": {
+          "max_input_size_bytes": 104857600,
           "mimes": [
             "application/epub+zip"
           ],
           "options": {
             "font_subsetting": {
               "availability": "planned",
-              "default": true,
               "description": "Subset embedded fonts to only include glyphs used in the document. Significant size reduction for books with large font files. `planned` \u2014 not yet supported.",
               "type": "boolean"
             },
@@ -983,13 +994,13 @@
             },
             "strip_unused_css": {
               "availability": "planned",
-              "default": false,
               "description": "Remove CSS rules not referenced by any content. Risk: may affect rendering in some readers. `planned` \u2014 not yet supported.",
               "type": "boolean"
             }
           }
         },
         "document_odf": {
+          "max_input_size_bytes": 104857600,
           "mimes": [
             "application/vnd.oasis.opendocument.text",
             "application/vnd.oasis.opendocument.spreadsheet",
@@ -1005,19 +1016,18 @@
             },
             "strip_metadata": {
               "availability": "planned",
-              "default": true,
               "description": "Remove document metadata (author, revision history, comments). `planned` \u2014 not yet supported.",
               "type": "boolean"
             },
             "strip_unused_styles": {
               "availability": "planned",
-              "default": false,
               "description": "Remove style definitions not referenced in document content. `planned` \u2014 not yet supported.",
               "type": "boolean"
             }
           }
         },
         "document_office": {
+          "max_input_size_bytes": 104857600,
           "mimes": [
             "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
             "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
@@ -1033,25 +1043,23 @@
             },
             "strip_hidden_data": {
               "availability": "planned",
-              "default": true,
               "description": "Remove revisions, comments, personal info, hidden rows/columns, and speaker notes. `planned` \u2014 not yet supported.",
               "type": "boolean"
             },
             "strip_macros": {
               "availability": "planned",
-              "default": true,
               "description": "Remove VBA macros and ActiveX controls. `planned` \u2014 not yet supported.",
               "type": "boolean"
             },
             "strip_unused_fonts": {
               "availability": "planned",
-              "default": false,
               "description": "Remove embedded fonts not referenced in the document. Risk: may affect rendering on systems without the font installed. `planned` \u2014 not yet supported.",
               "type": "boolean"
             }
           }
         },
         "image": {
+          "max_input_size_bytes": 524288000,
           "max_output_pixels": 16000000,
           "mimes": [
             "image/gif",
@@ -1175,6 +1183,7 @@
           }
         },
         "image_avif": {
+          "max_input_size_bytes": 20971520,
           "max_output_pixels": 16000000,
           "mimes": [
             "image/avif"
@@ -1345,6 +1354,7 @@
           }
         },
         "image_jpeg": {
+          "max_input_size_bytes": 524288000,
           "max_output_pixels": 16000000,
           "mimes": [
             "image/jpeg"
@@ -1537,6 +1547,7 @@
           }
         },
         "image_png": {
+          "max_input_size_bytes": 524288000,
           "max_output_pixels": 16000000,
           "mimes": [
             "image/png"
@@ -1643,7 +1654,7 @@
             },
             "quality": {
               "default": 80,
-              "description": "Compression quality (1-100). For PNG this is the SINGLE lossy/lossless control: `quality` < 100 applies lossy palette quantization (imagequant \u2014 licence-cleared for our server-side SaaS backend, `kkajDFXD`; the value is the quantization level), while `quality: 100` keeps the PNG lossless (oxipng optimisation only \u2014 tune the lossless effort via `optimization_level`). 1 = smallest file, 100 = best quality / lossless. There is no separate lossy/lossless toggle for PNG \u2014 it is purely quality-driven.",
+              "description": "Compression quality (1-100). For PNG this is the SINGLE lossy/lossless control: `quality` < 100 applies lossy palette quantization (the value is the quantization level), while `quality: 100` keeps the PNG lossless (lossless optimisation only \u2014 tune the lossless effort via `optimization_level`). 1 = smallest file, 100 = best quality / lossless. There is no separate lossy/lossless toggle for PNG \u2014 it is purely quality-driven.",
               "honored_on": [
                 "same_format"
               ],
@@ -1664,6 +1675,7 @@
           }
         },
         "image_svg": {
+          "max_input_size_bytes": 524288000,
           "mimes": [
             "image/svg+xml"
           ],
@@ -1687,7 +1699,7 @@
             },
             "output_format": {
               "default": "original",
-              "description": "Output format. original = keep input format (default); webp = recompress to WebP. Concrete format changes are handled by the convert operation. `auto` / `smallest` are PLANNED auto-format directives (the server picks the best/smallest candidate format, reported via the result `mime_type`) \u2014 selection strategies, not concrete targets, planned until supported. See FORMAT.md.",
+              "description": "Output format. `original` = keep input format \u2014 SVG -> SVG optimisation via SVGO. **STABLE and working** (restored 2026-07-21, G9O6yrQD; worker-proven on staging job 019f6aa3-d275-7b10-a5cf-58acc705c7e2 at 24.5% reduction, Form-A attested in lambdas #325). It is also the schema `default`, so a bare `compress` on an SVG takes this route. Optimisation is **visually preserving, NOT lossless** \u2014 SVGO's `preset-default` includes `convertPathData`, which rounds path coordinates within a tolerance. NOTE for anyone re-reading history here: this value was `planned` from 2026-07-17 to 2026-07-21 on a false premise, and because the API materializes an omitted default before the availability gate (api 4a7a2628), that tag 422'd EVERY website SVG compress at create \u2014 the workbench does not send `output_format`, so the defaulted path is the only path a customer has. A `planned` DEFAULT is therefore never a partial restriction; it is a total one. Weigh that before tagging any future default `planned`. `webp` = recompress to WebP: **STABLE and working today** \u2014 this facade route canonicalizes to the `convert` operation (`convert.image_svg` carries its own quality), which is why this group is NOT gated at group level. Concrete format changes are handled by the convert operation. `auto` / `smallest` are PLANNED auto-format directives (the server picks the best/smallest candidate format, reported via the result `mime_type`) \u2014 selection strategies, not concrete targets, planned until supported. See FORMAT.md.",
               "per_value_availability": {
                 "auto": {
                   "availability": "planned"
@@ -1707,6 +1719,7 @@
           }
         },
         "image_webp": {
+          "max_input_size_bytes": 524288000,
           "max_output_pixels": 16000000,
           "mimes": [
             "image/webp"
@@ -2019,8 +2032,7 @@
             },
             "speed": {
               "availability": "planned",
-              "default": 1.0,
-              "description": "Playback speed multiplier. 1.0 = unchanged (default), 2.0 = twice as fast (half the output duration), 0.5 = half speed (double the duration); range 0.25\u20134.0. Audio PITCH IS PRESERVED (a tempo-shift, not a resample \u2014 ffmpeg `atempo` semantics), so a 2.0x clip sounds sped up, not chipmunked. Applied BEFORE an explicit `fps`: speed re-times the stream, then `fps` (if set) resamples the retimed stream to the target rate. SHORT-FORM only \u2014 long-form video returns `feature_not_available` (adjust a short clip, or chain a `split`); see the compress.video.speed.longform constraint.\n",
+              "description": "Playback speed multiplier. 1.0 = unchanged, 2.0 = twice as fast (half the output duration), 0.5 = half speed (double the duration); range 0.25\u20134.0. Audio PITCH IS PRESERVED (a tempo-shift, not a resample \u2014 ffmpeg `atempo` semantics), so a 2.0x clip sounds sped up, not chipmunked. Applied BEFORE an explicit `fps`: speed re-times the stream, then `fps` (if set) resamples the retimed stream to the target rate. SHORT-FORM only \u2014 long-form video returns `feature_not_available` (adjust a short clip, or chain a `split`); see the compress.video.speed.longform constraint.\n",
               "max": 4.0,
               "min": 0.25,
               "type": "float"
@@ -2157,7 +2169,7 @@
             },
             "pages": {
               "default": "1",
-              "description": "Page selection (e.g. '1-5,8'). Each resolved page produces a\nseparate output file. **Maximum 200 resolved entries per\nrequest** \u2014 aligns with the `OperationResult.outputs[]`\n`maxItems: 200` cap. Expressions resolving to more than 200\nentries (e.g. `'1-201'`, `'1-100,102-205'`) are out of\ncontract. Duplicate or overlapping entries (e.g. `'1,1'`,\n`'1-100,50-150'`) are counted toward the cap as parsed;\ndeduplication, if any, is a runtime concern and is NOT part\nof this contract.\n",
+              "description": "Page selection (e.g. '1-5,8'). Each resolved page produces a\nseparate output file whose `page_index` is the **literal source\npage number** \u2014 a sparse selection stays sparse: `pages: '1-5,8'`\nyields outputs with `page_index` `1,2,3,4,5,8` (NOT renumbered\n`1..6`), and `pages: '5-7'` yields `5,6,7`. The download `filename`\nsuffix is a separate 0-based array position and does NOT track the\npage number. **Maximum 200 resolved entries per\nrequest** \u2014 aligns with the `OperationResult.outputs[]`\n`maxItems: 200` cap. Expressions resolving to more than 200\nentries (e.g. `'1-201'`, `'1-100,102-205'`) are out of\ncontract. Duplicate or overlapping entries (e.g. `'1,1'`,\n`'1-100,50-150'`) are counted toward the cap as parsed;\ndeduplication, if any, is a runtime concern and is NOT part\nof this contract.\n",
               "type": "string"
             }
           }
@@ -2237,8 +2249,7 @@
             },
             "metadata": {
               "availability": "planned",
-              "default": "strip",
-              "description": "Metadata handling across a format change. `strip` = remove all EXIF/IPTC/XMP (default), `keep` = preserve. `planned` \u2014 metadata is not yet preserved across a format change. The honoured target subset may narrow (avif/heic targets are re-encoded and cannot keep metadata).",
+              "description": "Metadata handling across a format change. `strip` = remove all EXIF/IPTC/XMP, `keep` = preserve. `planned` \u2014 metadata is not yet preserved across a format change, so this option carries **no default**: omit it and the worker's own behaviour applies. The honoured target subset may narrow (avif/heic targets are re-encoded and cannot keep metadata).",
               "honored_on": [
                 "format_change"
               ],
@@ -3100,11 +3111,11 @@
               "type": "float"
             },
             "fps": {
-              "default": 30,
+              "availability": "planned",
               "depends_on": {
                 "output_type": "video"
               },
-              "description": "Output frame rate",
+              "description": "Output frame rate. **Not yet configurable** \u2014 slideshow output is currently produced at a fixed 30 fps; setting this explicitly is rejected (`feature_not_available`). Omit it to get 30 fps.",
               "max": 60,
               "min": 1,
               "type": "integer"
@@ -3343,6 +3354,21 @@
                 ]
               },
               "description": "CRF aims for a quality level and lets the file size vary;\ntarget_size aims for a fixed output file size. `target_size`\ncurrently works with `codec=h264` only \u2014 a request pairing it\nwith another codec is rejected as `invalid_options`.\n",
+              "per_class_availability": {
+                "long_form_re_encode": {
+                  "availability": "planned"
+                }
+              },
+              "per_value_availability": {
+                "target_size": {
+                  "availability": "stable",
+                  "per_class_availability": {
+                    "long_form_re_encode": {
+                      "availability": "planned"
+                    }
+                  }
+                }
+              },
               "per_value_depends_on": {
                 "target_size": {
                   "codec": [
@@ -3358,7 +3384,12 @@
             },
             "normalize_audio": {
               "default": true,
-              "description": "Normalize audio levels across all clips",
+              "description": "Normalize audio levels across all clips. NOT available on the long-form path, which forces loudness normalisation off \u2014 a defaulted value is dropped and reported there rather than silently ignored.",
+              "per_class_availability": {
+                "long_form_re_encode": {
+                  "availability": "planned"
+                }
+              },
               "type": "boolean"
             },
             "output_type": {
@@ -3824,7 +3855,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\nserver-side silence detection. Video stays three-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 common\nvideo-tooling conventions.\n\n**200-output hard cap** (`OperationResult.outputs[].maxItems:\n200`). 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**:\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 long-form processing\npath (same `split` OperationType; routing via `processing_class`).\nNo schema-side discriminator beyond MIME detection +\n`processing_class`.\n\n`availability: beta` for the `audio` and `video` mime_groups\n(shape-stable + opt-in, MUST NOT 422). Video activates **both\nclasses**: `video.processing_class.short_form` AND `long_form` are\n`beta`. The `image_gif` and `document_pdf` mime_groups stay\n`availability: planned` until their cross-repo backend support ships;\ndispatch returns `feature_not_available` (422) for the still-planned\ngroups/classes until then.\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\nserver-side silence detection. Video stays three-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 common\nvideo-tooling conventions.\n\n**200-output hard cap** (`OperationResult.outputs[].maxItems:\n200`). 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 (S3 object key)**: the object-key leaf is 3-digit\nzero-padded \u2014 `output-001` .. `output-200` (ADR-0014 \u00a7D9). This binds the\n**S3 object key**, NOT the user-facing download filename \u2014 the API\nsynthesises that separately (see `OperationDownload.filename` in\n`openapi/api.yaml`). Only the **3-digit zero-padding** follows the convert\nPDF\u2192N precedent \u2014 convert keys are `page-NNN.ext`, split keys are\n`output-NNN.ext`.\n\n**Output envelope binding**:\n- `image_gif`: `PositionIndexed` (frame stream-position 0-based\n  ordinal)\n- `document_pdf`: `PageIndexed` (1-based literal source page number).\n  **`mode: page_range` only** \u2014 each output is one page, so `page_index` is\n  that page. For **`mode: page_groups`** an output spans multiple source\n  pages, so a single `page_index` cannot name them all; that grouped-output\n  semantics is NOT specified by this correction and is deferred (do not\n  assume it is the group's first page \u2014 that is unverified).\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 long-form processing\npath (same `split` OperationType; routing via `processing_class`).\nNo schema-side discriminator beyond MIME detection +\n`processing_class`.\n\n`availability: beta` for the `audio` and `video` mime_groups\n(shape-stable + opt-in, MUST NOT 422). Video activates **both\nclasses**: `video.processing_class.short_form` AND `long_form` are\n`beta`. The `image_gif` and `document_pdf` mime_groups stay\n`availability: planned` until their cross-repo backend support ships;\ndispatch returns `feature_not_available` (422) for the still-planned\ngroups/classes until then.\n",
       "features": {
         "silence_mode_audio": {
           "availability": "beta",
@@ -4386,7 +4417,6 @@
           "max_output_pixels": 16000000,
           "mimes": [
             "application/pdf",
-            "application/epub+zip",
             "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
             "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
             "application/vnd.openxmlformats-officedocument.presentationml.presentation",
@@ -4445,7 +4475,7 @@
             },
             "source": {
               "default": "page",
-              "description": "page = render a specific page/slide, cover = extract cover image (EPUB only, ignored for other formats)",
+              "description": "`page` = render a specific page/slide. `cover` = extract a cover image \u2014 only meaningful for EPUB inputs, which are served by the `document_epub` group; on PDF/office/ODF it is accepted and IGNORED (retained for backward compatibility).",
               "type": "enum",
               "values": [
                 "page",
@@ -4460,6 +4490,67 @@
             }
           }
         },
+        "document_epub": {
+          "max_output_pixels": 16000000,
+          "mimes": [
+            "application/epub+zip"
+          ],
+          "options": {
+            "fit": {
+              "default": "crop",
+              "description": "Resize mode",
+              "type": "enum",
+              "values": [
+                "max",
+                "crop",
+                "scale"
+              ]
+            },
+            "format": {
+              "default": "jpg",
+              "description": "Output format for the thumbnail",
+              "type": "enum",
+              "values": [
+                "jpg",
+                "png",
+                "webp"
+              ]
+            },
+            "height": {
+              "description": "Target height in pixels (1-16384; width*height <= 16MP). Optional \u2014 see `width` for the omitted-default behaviour.",
+              "max": 16384,
+              "min": 1,
+              "type": "integer"
+            },
+            "quality": {
+              "default": 85,
+              "depends_on": {
+                "format": [
+                  "jpg",
+                  "webp"
+                ]
+              },
+              "description": "Output quality for lossy thumbnail formats (jpg/webp): higher = better quality, larger file. Ignored for png (lossless).",
+              "max": 100,
+              "min": 1,
+              "type": "integer"
+            },
+            "source": {
+              "default": "cover",
+              "description": "`cover` (the only supported value) = extract the EPUB's declared cover image \u2014 the cheap path, no rendering. Cover lookup supports both mechanisms: the EPUB 3 `cover-image` property on an OPF manifest item, AND the legacy EPUB 2 `<meta name=\"cover\" content=\"...\"/>` pointing at a manifest item \u2014 supporting only the former would miss a large slice of real-world files. Both are staging-proven (pL16ZfOw Wave 3). A cover image is OPTIONAL per W3C EPUB 3.3, so a cover-less EPUB is a REAL and expected case: it fails with `error_code: processing_failed` and `is_retryable: false`. That is the live behaviour, not an aspiration \u2014 the worker classifies it as `CoverError::NoCoverDeclared` and maps it there (`epub/error.rs`), and non-retryability is DERIVED from the code rather than set per-call, so it cannot drift. A cover-less EPUB will not grow a cover, so retrying is always futile. A more specific code would be better, and is NOT promised here: `ErrorCode` (asyncapi) is a CLOSED enum with no \"no cover\" member, so adding one is a real cross-repo co-land (enum edit -> SDK regen -> lockstep). Until then this description states what actually happens \u2014 an undecided-reject note on a STABLE route would leave consumers unable to handle a case they will certainly meet.",
+              "type": "enum",
+              "values": [
+                "cover"
+              ]
+            },
+            "width": {
+              "description": "Target width in pixels (1-16384; width*height <= 16MP). Optional \u2014 when omitted the server applies an aspect-preserving default (both omitted \u2192 longest edge 320px; only one of width/height provided \u2192 the other is derived from the source aspect ratio).",
+              "max": 16384,
+              "min": 1,
+              "type": "integer"
+            }
+          }
+        },
         "image": {
           "max_output_pixels": 16000000,
           "mimes": [
@@ -4516,7 +4607,7 @@
                   "png"
                 ]
               },
-              "description": "Output quality for lossy thumbnail formats (jpg / webp / png): higher = better quality, larger file. For PNG, `quality` < 100 applies lossy palette quantization (imagequant \u2014 transparency preserved); `quality: 100` keeps the PNG lossless. Per-format effective default (server-resolved when `quality` is unset, per ADR-0020 D1): PNG \u2192 70 (more aggressive \u2014 thumbnails target small files), jpg/webp \u2192 85. The schema `default` is the nominal jpg/webp value (85); the FE shows 70 as the initial PNG slider value.",
+              "description": "Output quality for lossy thumbnail formats (jpg / webp / png): higher = better quality, larger file. For PNG, `quality` < 100 applies lossy palette quantization (transparency preserved); `quality: 100` keeps the PNG lossless. Per-format effective default (server-resolved when `quality` is unset, per ADR-0020 D1): PNG \u2192 70 (more aggressive \u2014 thumbnails target small files), jpg/webp \u2192 85. The schema `default` is the nominal jpg/webp value (85); the FE shows 70 as the initial PNG slider value.",
               "max": 100,
               "min": 1,
               "type": "integer"
@@ -5006,7 +5097,7 @@
       "sole_op": true
     }
   },
-  "schema_version": "2.171.0",
+  "schema_version": "2.188.0",
   "source_commit": null,
   "user_tier": null,
   "workflow_features": {
@@ -5039,6 +5130,24 @@
           }
         }
       }
+    },
+    "processing": {
+      "class_hint": {
+        "per_value_availability": {
+          "auto": {
+            "availability": "stable"
+          },
+          "long_form_allowed": {
+            "availability": "planned"
+          },
+          "long_form_preferred": {
+            "availability": "planned"
+          },
+          "short_form_only": {
+            "availability": "planned"
+          }
+        }
+      }
     }
   }
 }