@giveitsmaller/contracts 0.59.0 → 0.61.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
@@ -241,23 +241,38 @@ operation:
           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.
+      # 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.
       #
-      # `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.
+      # 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
@@ -273,20 +288,52 @@ operation:
       # 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.
+      # 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: [page, cover]
+          values: [cover]
           default: cover
-          # Group-scoped default: `cover`, NOT the `document` group's `page`.
+          # `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
@@ -313,26 +360,25 @@ operation:
           # 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.
+            `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 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.
+            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

package/package.json

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