@giveitsmaller/contracts 0.58.0 → 0.60.0

package/operations/schemas/thumbnail.yaml

@@ -69,7 +69,7 @@ operation:
           description: >-
             Output quality for lossy thumbnail formats (jpg / webp / png): higher =
             better quality, larger file. For PNG, `quality` < 100 applies lossy palette
-            quantization (imagequant — transparency preserved); `quality: 100` keeps the
+            quantization (transparency preserved); `quality: 100` keeps the
             PNG lossless. Per-format effective default (server-resolved when `quality`
             is unset, per ADR-0020 D1): PNG → 70 (more aggressive — thumbnails target
             small files), jpg/webp → 85. The schema `default` is the nominal jpg/webp
@@ -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,176 @@ 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:
+      # STABLE as of 2026-07-21 (pL16ZfOw Wave 3). EPUB cover-extract is deployed
+      # AND staging-verified against live fixtures — the precondition lambdas'
+      # own manifest (operation-thumbnail-document.yaml:65-71) names.
+      #
+      # PROOF (direct invoke against the deployed stg alias, bypassing the API;
+      # repeatable via lambdas' scripts/prove-epub-thumbnail-staging.sh):
+      #   deployed artifact  gisl-stg-euw1-operation-thumbnail-document
+      #                      Code.ImageUri :git-128722e (#319)
+      #   EPUB3 properties="cover-image"  PASS  233084 -> 97051 B, 320x320 PNG
+      #                      job 019f851a-4b1a-7188-9eba-ac29125a8cda
+      #   EPUB2 <meta name="cover">       PASS  out=97276 B, PNG
+      #                      job 019f851a-6dee-72aa-8706-1a3141fe93c1
+      #   cover-ABSENT (NEGATIVE CONTROL) no output object produced
+      # The third cell is what makes the other two mean anything: without it the
+      # proof could not distinguish "extracts covers" from "emits something
+      # regardless of input". A proof that cannot return the inconvenient answer
+      # is not a proof.
+      #
+      # HISTORY (2026-07-17, G9O6yrQD): split out of `document` and downgraded
+      # stable -> planned, correctly at the time — the crate then had no non-PDF
+      # path (document_thumbnailer.rs:229 called pdftocairo with the format
+      # literally "pdf", and an EPUB is a ZIP of XHTML). The mime had leaked from
+      # `compress.document_epub` into `thumbnail.document`. Siblings were swept;
+      # that was the only leak.
+      # NOTE ON THE DEADLOCK THIS SAT IN, because it will recur: while `planned`,
+      # the API 422s at create, so no traffic can EVER reach the worker, so no
+      # log can ever accumulate — the feature could not earn its way out of
+      # `planned` through a gate that `planned` itself holds shut. Silence on a
+      # path that is silent BY CONSTRUCTION is not evidence of anything. The only
+      # exit is a direct invoke that bypasses the API, and that step must be an
+      # OWNED, DATED task — this one sat unowned in a manifest comment for three
+      # days while the capability was finished and deployed.
+      #
+      # 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 SHIPPED: 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).
+      #
+      # LIFECYCLE, current as of 2026-07-21: cover-extract is STABLE and
+      # staging-proven. `source: page` (paginate + render XHTML) is the separate,
+      # expensive half — it is NOT advertised at all, because the worker rejects
+      # it (InvalidOptions) and a stable enum value that 422s is the defect this
+      # group's history is about. It is not `planned` either: an unadvertised
+      # value and a planned one are different promises, and only one of them is
+      # true here. Re-add it additively when a renderer ships AND is proven.
+      mimes:
+        - application/epub+zip
+      max_output_pixels: 16000000
+      options:
+        source:
+          type: enum
+          values: [cover]
+          default: cover
+          # `page` is NOT offered here. Only cover-extract is implemented; the
+          # worker rejects `source: page` on an EPUB with InvalidOptions (no
+          # pure-Rust EPUB page renderer exists — lambdas'
+          # operation-thumbnail-document.yaml:60-61). Now that this group is
+          # `stable`, leaving `page` in the enum would advertise a value that
+          # 422s — precisely the "stable MUST NOT 422" defect (ADR-0001) this
+          # group's own history is about. Caught by codex on the flip PR, which
+          # would otherwise have restored one broken promise while shipping
+          # another.
+          #
+          # THIS IS NOT A REQUEST-ENUM NARROWING. The narrowing rule protects
+          # callers who succeed TODAY (see the `document` group below, where
+          # `cover` is retained inert for exactly that reason). No caller has
+          # ever had a working `source: page` on an EPUB: this group has been
+          # group-level `planned` since it was created on 2026-07-17, so the API
+          # 422'd every request to it, and before the split the crate had no
+          # non-PDF path at all. Zero working callers, both sides of the split.
+          #
+          # An ENUM rejection is also the right instrument rather than a
+          # per-value availability tag: per-value `planned` on a non-output_format
+          # option is ADVISORY and unenforced (FORMAT.md), which would let the API
+          # accept the job and dispatch it to a worker that rejects it — a silent
+          # accept-then-fail, worse than not advertising. Re-add `page` when a
+          # renderer ships and is proven, as an additive change.
+          #
+          # Original group-scoped-default note, still true: `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` (the only supported value) = extract the EPUB's declared cover
+            image — 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 — 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
+            — 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 —
+            an undecided-reject note on a STABLE route would leave consumers unable
+            to handle a case they will certainly meet.
+        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.60.0",
   "description": "Generated contract types for GISL (Give It Smaller)",
   "license": "Apache-2.0",
   "type": "module",