@giveitsmaller/contracts 0.58.0 → 0.59.0

package/operation-capabilities/operation-capabilities.json

@@ -732,5 +732,5 @@
       "isAnimated": "maybe"
     }
   },
-  "schema_version": "2.171.0"
+  "schema_version": "2.180.0"
 }

package/operations/schemas/audio_to_video.yaml

@@ -64,6 +64,7 @@ operation:
         - audio/opus
         - audio/mp4
         - audio/x-m4a
+      max_input_duration: "PT2H"   # 2h input ceiling (KzrquIX7; mirrors worker MAX_AUDIO_DURATION_SECS 7200, strict >)
       options:
         output_resolution:
           type: enum

package/operations/schemas/compress.yaml

@@ -90,6 +90,7 @@ operation:
       # Resize-inside-Output shares the convert resize engine's 16MP output-area
       # wall — the per-axis 16384 cap can't express it (FORMAT.md §max_output_pixels).
       max_output_pixels: 16000000
+      max_input_size_bytes: 524288000   # 500 MiB compress input ceiling (uKsFzORi)
       options:
         quality:
           type: integer
@@ -261,6 +262,7 @@ operation:
       mimes:
         - image/png
       max_output_pixels: 16000000
+      max_input_size_bytes: 524288000   # 500 MiB compress input ceiling (uKsFzORi)
       options:
         quality:
           type: integer
@@ -385,6 +387,7 @@ operation:
       mimes:
         - image/avif
       max_output_pixels: 16000000
+      max_input_size_bytes: 20971520   # 20 MiB compress input ceiling (uKsFzORi; AVIF decode OOM guard, worker AVIF_MAX_MB)
       options:
         quality:
           type: integer
@@ -544,6 +547,7 @@ operation:
       mimes:
         - image/webp
       max_output_pixels: 16000000
+      max_input_size_bytes: 524288000   # 500 MiB compress input ceiling (uKsFzORi)
       options:
         quality:
           type: integer
@@ -701,8 +705,32 @@ operation:
     # optimiser `lossless` knob does not apply. SVG compression is SVGO; only
     # quality/metadata/output_format carry. NO Resize / lossless / area cap here.
     image_svg:
+      # G9O6yrQD (2026-07-17): the SAME-FORMAT route only (`output_format: original`,
+      # SVG -> SVG via SVGO) is downgraded stable -> planned — see the
+      # `output_format.per_value_availability` below. The worker does not implement
+      # it: `compression_lambdas/manifests/compression-image.yaml:17` verbatim,
+      # "SVG is a follow-up." An unimplemented route advertised `stable` violates
+      # "stable MUST NOT 422" (ADR-0001) — the defect fixed for `class_hint` in
+      # v2.172.0.
+      #
+      # THE GROUP STAYS STABLE ON PURPOSE. A group-level `planned` here would ALSO
+      # gate off `output_format: webp`, which WORKS TODAY: the webp facade route
+      # canonicalizes to `convert` (see the output_format description below), and
+      # `convert.image_svg` is stable. Gating the group would advertise LESS than we
+      # actually built — the exact over-narrow the user's standing rule forbids
+      # ("exclude only on EVIDENCE OF BREAKAGE", 2026-07-07). Caught by codex on #322.
+      #
+      # `output_format`-VALUE granularity is the right axis AND is enforced: per
+      # FORMAT.md the API create-gate enforces planned -> feature_not_available (422)
+      # at group / operation / output_format-VALUE granularity. (Contrast a planned
+      # INPUT MIME, which needs a parallel group because per_mime_availability is
+      # advisory-only. The input here is fine; only one output route is unbuilt.)
+      #
+      # Flip `original` back to stable when lambdas lands SVGO + a Form-A manifest
+      # entry (ADR-0006). `convert.image_svg` (SVG -> raster) is UNAFFECTED.
       mimes:
         - image/svg+xml
+      max_input_size_bytes: 524288000   # 500 MiB compress input ceiling (uKsFzORi; image/* default)
       options:
         # No `quality`: compress SVG is SVG->SVG via SVGO (lossless vector optimise);
         # `quality` is never passed to the worker, so a quality slider here is a no-op
@@ -726,11 +754,29 @@ operation:
           values: [original, webp, auto, smallest]
           default: original
           per_value_availability:
+            original: { availability: planned }
             auto:     { availability: planned }
             smallest: { availability: planned }
           description: >-
-            Output format. original = keep input format (default); webp = recompress to
-            WebP. Concrete format changes are handled by the convert operation. `auto` /
+            Output format. `original` = keep input format — SVG -> SVG optimisation via
+            SVGO. **`original` is PLANNED** (G9O6yrQD): the worker does not implement
+            SVG->SVG optimisation yet ("SVG is a follow-up"), so it returns
+            `feature_not_available` (422) rather than 422ing under a `stable` claim.
+            It is also the schema `default`. **KNOWN ENFORCEMENT GAP (api co-land
+            owed):** the API's per-value gate only inspects an EXPLICITLY submitted
+            `output_format` (`CreateWorkflowCommandHandler`: `$requestedFormat =
+            $opDef->options['output_format'] ?? null; if (is_scalar(...))`), so an
+            OMITTED value is not materialized to its default before the check and
+            bypasses this tag — a bare `compress` on an SVG still dispatches and
+            fails at the worker instead of returning a clean 422. `original` is the
+            first PLANNED DEFAULT in the contract, so nothing exercised that path
+            before. The tag is correct and truthful regardless; closing the gap is
+            api's (gate against the effective default). Ask for `webp` meanwhile —
+            that route works.
+            `webp` = recompress to WebP: **STABLE and working today** — 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`) —
             selection strategies, not concrete targets, planned until supported. See
@@ -743,6 +789,7 @@ operation:
         - image/gif
         - image/tiff
       max_output_pixels: 16000000
+      max_input_size_bytes: 524288000   # 500 MiB compress input ceiling (uKsFzORi)
       options:
         quality:
           type: integer
@@ -1173,6 +1220,7 @@ operation:
         - application/vnd.openxmlformats-officedocument.wordprocessingml.document
         - application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
         - application/vnd.openxmlformats-officedocument.presentationml.presentation
+      max_input_size_bytes: 104857600   # 100 MiB compress input ceiling (uKsFzORi; zip-based worker MAX_INPUT_SIZE)
       # See the document_pdf honesty note: the worker reads ONLY `quality` today;
       # the per-format options are `planned` (advertised-ahead, FE-hidden).
       options:
@@ -1208,6 +1256,7 @@ operation:
         - application/vnd.oasis.opendocument.text
         - application/vnd.oasis.opendocument.spreadsheet
         - application/vnd.oasis.opendocument.presentation
+      max_input_size_bytes: 104857600   # 100 MiB compress input ceiling (uKsFzORi; zip-based worker MAX_INPUT_SIZE)
       # See the document_pdf honesty note: worker reads ONLY `quality`; the rest `planned`.
       options:
         quality:
@@ -1235,6 +1284,7 @@ operation:
     document_epub:
       mimes:
         - application/epub+zip
+      max_input_size_bytes: 104857600   # 100 MiB compress input ceiling (uKsFzORi; zip-based worker MAX_INPUT_SIZE)
       # See the document_pdf honesty note: worker reads ONLY `quality`; the rest `planned`.
       options:
         quality:

package/operations/schemas/convert.yaml

@@ -463,7 +463,12 @@ operation:
           default: "1"
           description: |
             Page selection (e.g. '1-5,8'). Each resolved page produces a
-            separate output file. **Maximum 200 resolved entries per
+            separate output file whose `page_index` is the **literal source
+            page number** — a sparse selection stays sparse: `pages: '1-5,8'`
+            yields outputs with `page_index` `1,2,3,4,5,8` (NOT renumbered
+            `1..6`), and `pages: '5-7'` yields `5,6,7`. The download `filename`
+            suffix is a separate 0-based array position and does NOT track the
+            page number. **Maximum 200 resolved entries per
             request** — aligns with the `OperationResult.outputs[]`
             `maxItems: 200` cap. Expressions resolving to more than 200
             entries (e.g. `'1-201'`, `'1-100,102-205'`) are out of

package/operations/schemas/split.yaml

@@ -44,13 +44,23 @@ operation:
       (cross-ref [`WgCqnMRa`](https://trello.com/c/WgCqnMRa))
     - GIF: resolved frame count after expansion `<= 200`
 
-    **Output naming**: 3-digit zero-padded — `output-001` ..
-    `output-200`. Matches the convert PDF→N precedent.
+    **Output naming (S3 object key)**: the object-key leaf is 3-digit
+    zero-padded — `output-001` .. `output-200` (ADR-0014 §D9). This binds the
+    **S3 object key**, NOT the user-facing download filename — the API
+    synthesises that separately (see `OperationDownload.filename` in
+    `openapi/api.yaml`). Only the **3-digit zero-padding** follows the convert
+    PDF→N precedent — convert keys are `page-NNN.ext`, split keys are
+    `output-NNN.ext`.
 
     **Output envelope binding**:
     - `image_gif`: `PositionIndexed` (frame stream-position 0-based
       ordinal)
-    - `document_pdf`: `PageIndexed` (1-based gapless page index)
+    - `document_pdf`: `PageIndexed` (1-based literal source page number).
+      **`mode: page_range` only** — each output is one page, so `page_index` is
+      that page. For **`mode: page_groups`** an output spans multiple source
+      pages, so a single `page_index` cannot name them all; that grouped-output
+      semantics is NOT specified by this correction and is deferred (do not
+      assume it is the group's first page — that is unverified).
     - `audio`: `PositionIndexed` (cut stream-position ordinal)
     - `video`: `PositionIndexed` (cut stream-position ordinal)
 

package/operations/schemas/thumbnail.yaml

@@ -163,7 +163,6 @@ operation:
     document:
       mimes:
         - application/pdf
-        - application/epub+zip
         - application/vnd.openxmlformats-officedocument.wordprocessingml.document
         - application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
         - application/vnd.openxmlformats-officedocument.presentationml.presentation
@@ -179,7 +178,22 @@ operation:
           type: enum
           values: [page, cover]
           default: page
-          description: "page = render a specific page/slide, cover = extract cover image (EPUB only, ignored for other formats)"
+          # `cover` is RETAINED here deliberately (G9O6yrQD / codex #322). EPUB — the
+          # only input it ever meant anything for — moved to the `document_epub`
+          # group, so `cover` is now inert for every mime in THIS group. Removing it
+          # looked like tidying a phantom, but it is a REQUEST-ENUM NARROWING: a
+          # caller sending `source: cover` with a PDF succeeds today (the worker
+          # ignores it) and would start getting a 422 invalid_options. That is a
+          # caller-visible break for zero benefit, and "nobody sends it" is not a
+          # reason (the same reasoning was wrong for declared_duration_seconds, which
+          # turned out settable on npm-latest). Retiring it properly = tag it
+          # `deprecated` -> migrate -> remove, which is its own cut, not a drive-by
+          # in a defect fix.
+          description: >-
+            `page` = render a specific page/slide. `cover` = extract a cover image —
+            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).
         page:
           type: integer
           min: 1
@@ -225,3 +239,130 @@ operation:
           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)."
+
+    document_epub:
+      availability: planned
+      # G9O6yrQD (2026-07-17): split out of `document` and downgraded stable ->
+      # planned. EPUB thumbnails are NOT implemented and 422 today:
+      # `compression_lambdas/crates/thumbnail-documents/src/document_thumbnailer.rs:229`
+      # calls `pdftocairo` with the input format literally "pdf" and the crate has NO
+      # non-PDF path — an EPUB is a ZIP of XHTML, which pdftocairo cannot open. A
+      # stable claim that 422s violates "stable MUST NOT 422" (ADR-0001) — the same
+      # defect fixed for `class_hint` in v2.172.0. Likely provenance: the mime leaked
+      # from `compress.document_epub` (which genuinely DOES handle EPUB via zip
+      # re-pack) into `thumbnail.document`. Swept the siblings — this was the ONLY
+      # leak; the office/ODF mimes shared with compress are legitimately served by
+      # the `operation-thumbnail-office` (LibreOffice) Lambda.
+      #
+      # `planned`, NOT dropped — the USER wants EPUB thumbnails BUILT (2026-07-17):
+      # "we advertise EPUB thumbnails <-- ... we should be able to open them no??".
+      # `planned` = spec defined, backend returns feature_not_available (422) until it
+      # ships. lambdas is costing the build.
+      #
+      # A PARALLEL GROUP is REQUIRED — NOT `per_mime_availability: planned` on the
+      # `document` group. Per FORMAT.md, per-MIME `planned` is advisory and NOT
+      # enforced: it would leave the API accepting the job and dispatching it to a
+      # worker that cannot handle it (a silent accept-then-fail — worse than not
+      # advertising). Group-level `availability` is what the API create-gate enforces.
+      # Same pattern as the image_watermark `image_tiff`/`image_bmp` groups while
+      # planned (UANjD38A), which flipped stable together once the encoders shipped.
+      #
+      # `source: cover` is only MEANINGFUL here — it was always EPUB-only ("ignored
+      # for other formats"). It is deliberately RETAINED in the `document` group too,
+      # accepted-and-ignored for backward compatibility: removing it there would be a
+      # request-enum narrowing that 422s callers who send `cover` with a PDF today
+      # (codex, #322). Inert-but-accepted there; load-bearing here. It is also the
+      # design of record for
+      # how this ships: extract the OPF-declared cover from the zip and resize (no
+      # renderer, no new heavy dep — reuses the zip path compress.document_epub
+      # already has). `source: page` on an EPUB is the separate, expensive half
+      # (paginate + render XHTML). Both advertised planned; they may graduate
+      # independently.
+      mimes:
+        - application/epub+zip
+      max_output_pixels: 16000000
+      options:
+        source:
+          type: enum
+          values: [page, cover]
+          default: cover
+          # Group-scoped default: `cover`, NOT the `document` group's `page`.
+          # `cover` is the half being built; `page` (paginate + render XHTML) is out
+          # of reach — LibreOffice's EPUB filter is EXPORT-ONLY (it writes EPUB,
+          # cannot open one), leaving a headless browser (Lambda-hostile) or a
+          # pure-Rust renderer that doesn't exist at thumbnail quality. Defaulting
+          # to `page` would route every bare EPUB request into the unbuilt half.
+          #
+          # 2026-07-17: FOUR COST CLAIMS STRUCK from this comment — every one was
+          # false, and they were stamped "lambdas-confirmed", so a reader got them
+          # back from the CONTRACT as settled fact. Struck rather than corrected:
+          # a cost estimate does not belong in a contract at all. It cannot be
+          # tested, it rots silently, and this file is the press that made it
+          # quotable — lambdas' own guess reached them back through here as
+          # corroboration, which is how it survived three re-quotes.
+          #   "~200-250 lines"      -> measured ~1,150-1,200. Grew 5x, and never
+          #                            once downward: every rise came from someone
+          #                            opening the code instead of quoting the file.
+          #   "`infer` already detects EPUB"  -> `infer` is a dep of `shared` only
+          #                            and is NEVER called on the thumbnail path.
+          #                            (It was read from a code COMMENT, not a call.)
+          #   "`zip` already does the re-pack" -> true of a DIFFERENT crate.
+          #   "quick-xml/roxmltree the ONLY new dep" -> 5-6 deps. And they are not
+          #                            interchangeable: `roxmltree` is already in
+          #                            Cargo.lock via usvg; `quick-xml` is absent.
+          # The build's real shape lives in the ticket and in lambdas' crate. This
+          # file states the CONTRACT: what is advertised, and what the API gates.
+          description: >-
+            `cover` (default) = extract the EPUB's declared cover image — the cheap
+            path, no rendering. `page` = render a paginated page of the book's XHTML.
+            Cover lookup MUST support 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 —
+            supporting only the former misses a large slice of real-world files.
+            A cover image is OPTIONAL per W3C EPUB 3.3, so a cover-less EPUB is a
+            real case. The reject shape for it is NOT yet decided and is deliberately
+            unpromised here: `ErrorCode` (asyncapi) is a CLOSED enum with no
+            "no cover" member, so a distinct code is a real cross-repo co-land
+            (enum edit -> SDK regen -> lockstep), not a free string. It is settled
+            when this group graduates — do not infer one from this description.
+        page:
+          type: integer
+          min: 1
+          default: 1
+          depends_on: { source: page }
+          description: >-
+            1-based index of the printed page to render, after the book's
+            print-layout pagination is applied.
+        width:
+          type: integer
+          min: 1
+          max: 16384
+          description: >-
+            Target width in pixels (1-16384; width*height <= 16MP). Optional — when
+            omitted the server applies an aspect-preserving default (both omitted →
+            longest edge 320px; only one of width/height provided → the other is
+            derived from the source aspect ratio).
+        height:
+          type: integer
+          min: 1
+          max: 16384
+          description: >-
+            Target height in pixels (1-16384; width*height <= 16MP). Optional — see
+            `width` for the omitted-default behaviour.
+        fit:
+          type: enum
+          values: [max, crop, scale]
+          default: crop
+          description: "Resize mode"
+        format:
+          type: enum
+          values: [jpg, png, webp]
+          default: jpg
+          description: "Output format for the thumbnail"
+        quality:
+          type: integer
+          min: 1
+          max: 100
+          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)."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@giveitsmaller/contracts",
-  "version": "0.58.0",
+  "version": "0.59.0",
   "description": "Generated contract types for GISL (Give It Smaller)",
   "license": "Apache-2.0",
   "type": "module",