@giveitsmaller/contracts 0.62.0 → 0.65.0

package/openapi/api.yaml

@@ -89,7 +89,7 @@ info:
     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.
-  version: 2.191.0
+  version: 2.194.0
   contact:
     name: API Support
 
@@ -1229,7 +1229,21 @@ paths:
         - name: archived
           in: query
           required: false
-          description: |
+          x-availability: planned
+          description: |
+            🔴 **NOT IMPLEMENTED — see the `planned` note below. A server
+            that does not support this parameter SILENTLY IGNORES IT and
+            returns the DEFAULT (non-archived) list.** That is the dangerous
+            half of this feature and the reason it is called out here rather
+            than only on the endpoints: `POST .../archive` would 404, which is
+            loud and teaches the caller immediately, whereas
+            **`archived=true` returns a 200 carrying the wrong rows.** A
+            consumer asking for their archive receives their NON-archived
+            workflows and is told nothing. **Silent wrong data beats a 404
+            every time for damage.**
+            Until the server implements it, a client MUST NOT present an
+            "archived" view built on this parameter.
+
             Archived-row filter (ticket
             [`j2s6T2qf`](https://trello.com/c/j2s6T2qf)). **Default `false`**:
             archived workflows are EXCLUDED, so archiving declutters the
@@ -2355,6 +2369,160 @@ paths:
   /api/workflows/{id}/events:
     get:
       summary: Stream workflow events (SSE)
+      # THE STREAM DOES NOT LIVE ON THE API HOST. THAT IS A CONTRACT FACT,
+      # DECLARED PER-OPERATION, AND DELIBERATELY NOT A CONVENTION.
+      #
+      # ⚠️ RULING (hub, 2026-08-14, on sdks' recommendation with api agreeing):
+      # SPLIT HOSTS, DECLARED PER-OPERATION. Not string surgery on `api.*`, not
+      # a per-client rule. The reason is not aesthetic — IT IS THAT A CONVENTION
+      # CAN ONLY FAIL SILENTLY. The frontend carried `VITE_SSE_BASE_URL`
+      # (created 2026-06-17) and preferred it when set; PROD NEVER SET IT, so
+      # prod silently fell back to the gateway path and inherited an entry point
+      # that cannot stream — for weeks, while everyone believed SSE worked. A
+      # declared per-operation server cannot fail that way.
+      #
+      # 🔴 WHAT THIS DECLARATION DOES **NOT** DO, STATED BECAUSE IT IS THE
+      # DIFFERENCE BETWEEN DECLARED AND IN EFFECT: it does not repoint any
+      # existing client. Both shipped SDKs resolve EVERY url from a single
+      # configured base — PHP `GislClient::streamEvents()` builds from the same
+      # base URL as everything else, and TypeScript does likewise — and the
+      # generators emit models and supporting files rather than per-operation
+      # server handling. **A CLIENT CONFIGURED FOR `api.*` KEEPS SENDING SSE TO
+      # `api.*` AFTER THIS LANDS.**
+      #
+      # ⇒ This block makes the routing a CONTRACT FACT that a client can
+      # consume. Consuming it is a change to endpoint RESOLUTION in two
+      # languages (sdks' `VUozk5Bc`), and it is theirs. Writing "a generated
+      # client picks the host up from the contract" would be the same
+      # declared-equals-working error this comment exists to warn about.
+      #
+      # THE RULE, STATED SO NOBODY DERIVES A DIFFERENT ONE: this is the ONLY
+      # operation with its own `servers`. Every other endpoint uses the
+      # root-level `servers:`. The stream API happens to proxy `ANY /{proxy+}`
+      # — the whole API — so "route SSE at the stream host" could have meant
+      # "move everything"; IT DOES NOT. Split per-endpoint, and the split is
+      # expressed here rather than in three consumers' READMEs.
+      #
+      # WHY THE API HOST CANNOT DO THIS — mechanism, not a workaround (api,
+      # 2026-08-13, relayed via the hub; contracts has not measured it):
+      # `api.*` is an API Gateway **HTTP API** with `integration_timeout_ms`
+      # 29000 against a **30s hard AWS ceiling with no quota path**, and
+      # `responseTransferMode: STREAM` is **REST-only**. `stream.*` is a REST
+      # API with a 900000ms timeout and STREAM set. Raising a number fixes
+      # nothing.
+      #
+      # THE REVERT CONDITION IS MET. This block was reverted on 2026-08-12
+      # (27d606c) with a named gate: "re-lands when the path is PROVEN".
+      # e2e then measured `stream.staging` streaming — `:ok` at 0.0s, frames
+      # over 165s, ~16s heartbeats — while `api.staging` 503s at 29.35s, which
+      # is the integration timeout firing to the millisecond. Measured AND
+      # mechanistically explained, which is what the gate asked for.
+      #
+      # ⚠️ THERE IS STILL DELIBERATELY NO PRODUCTION ENTRY, and the reason is
+      # UNCHANGED by the staging proof: PROD HAS NEVER HAD A PROVEN STREAM.
+      # Declaring a prod host would be a contract fact pointing at something
+      # unproven, which is worse than the gap because it LOOKS resolved — the
+      # same error this block exists to prevent, committed in the opposite
+      # direction. The gate is the same one, applied to prod: a first-byte
+      # timestamp on a heartbeat from the prod stream host.
+      servers:
+        - url: http://localhost:8080
+          # WHICH ROOT SERVER THIS ENTRY REPLACES. Without it a client has to
+          # infer the mapping from ordering or hostname shape — which is a
+          # per-client rule, i.e. the exact thing declaring the split was meant
+          # to remove. A client matches its CONFIGURED base against
+          # `x-replaces` exactly and takes `url`; no convention, no ordering
+          # dependency, and an unmatched base is an honest "no override for the
+          # host you are pointed at" rather than a guess.
+          x-replaces: http://localhost:8080
+          description: |
+            Local development. Same origin as the rest of the API — local runs
+            do NOT reproduce the split-host topology, so a client that works
+            locally has **not** exercised the cross-origin path. Treat a local
+            pass as evidence about your code and not about the routing.
+        - url: https://stream.staging.giveitsmaller.com
+          x-replaces: https://api.staging.giveitsmaller.com
+          description: |
+            Staging stream host. A SEPARATE PUBLIC ENTRY POINT from
+            `api.staging.giveitsmaller.com`, which is why it is declared here
+            rather than inherited: the API host fronts an integration with no
+            response-streaming mode, and this is the only endpoint that needs
+            streaming.
+
+            ⚠️ **THIS HOST ALLOWS EXACTLY ONE CORS ORIGIN, AND IT IS A
+            DIFFERENT POLICY FROM THE API HOST.** The stream stack sets
+            `cors_allow_origin` (**singular**) to the frontend host alone, in
+            **both** environments. The API host sets `cors_allow_origins`
+            (**plural**) — and **the list differs BY ENVIRONMENT**:
+
+                staging api host   localhost:5173, localhost:3000, www.staging…
+                prod    api host   www.giveitsmaller.com   ← NO localhost, never had
+                both    stream     the frontend host only  (singular)
+
+            ⇒ **A BROWSER ON localhost CAN CALL THE STAGING API HOST AND
+            CANNOT CALL EITHER STREAM HOST.** The break is **conditional on a
+            local build choosing this host**: the frontend's local build leaves
+            `VITE_SSE_BASE_URL` unset and falls back to the API host, so nothing
+            breaks today (measured by `compression_frontend`, 2026-08-14). **A
+            client that DOES point a localhost browser here is blocked, and the
+            failure arrives as a CORS error that reads as a configuration
+            mistake in their own app.**
+
+            **This is a local-development concern only; prod never permitted
+            localhost on any host** (measured by `compression_terraform`,
+            2026-08-14 — an earlier version of this note gave the staging list
+            without saying it was staging's, which would have read as universal
+            and turned a dev-experience issue into an apparent launch one).
+
+            ⚠️ **"Just add another origin" is not a CONFIG CHANGE here, and
+            the reason is our implementation rather than an AWS limit.** An API
+            Gateway **HTTP** API has a native, declarative CORS configuration
+            that takes a LIST and echoes whichever origin matches. A **REST**
+            API has no equivalent declarative feature — the value is whatever
+            the preflight MOCK integration and the backend return — so
+            multi-origin support is possible but must be **built**
+            (validate-the-Origin-then-echo), which is a change with its own
+            correctness risk rather than an extra list entry.
+
+            *(An earlier version of this note said a REST API simply cannot do
+            it. That is wrong: AWS documents that for proxy integrations the
+            BACKEND returns `Access-Control-Allow-Origin`, so per-origin
+            responses are available to anyone willing to implement them.
+            Stating a platform prohibition where an implementation choice
+            exists closes a door that is open.)*
+
+            The credentialed case does foreclose the other escape: with
+            `Allow-Credentials: true` the origin header cannot be `*`.
+
+            The same applies to embedded and third-party consumers, and to any
+            **browser build of a published SDK**: `@giveitsmaller/sdk` ships a
+            browser entry point whose client carries `streamEvents`, so this is
+            a published-surface limit rather than an internal one.
+
+            A server-side caller is unaffected. **The origin list is a property
+            of the deployed stack, not of this contract** — it is stated here
+            because a client author reading only the URL cannot discover it, and
+            it changes only in `compression_terraform`.
+
+            ⚠️ **AUTH ON THIS HOST IS CROSS-ORIGIN, AND `sessionAuth` IS THE
+            ONE THAT MAY NOT SURVIVE IT.** This operation advertises
+            `bearerAuth`, `sessionAuth` and anonymous access — but the security
+            list describes what the ENDPOINT accepts, not what a browser can
+            deliver to a different origin.
+
+            **Cookie domain scope is necessary and NOT sufficient.** A
+            credentialed cross-origin request additionally requires the client
+            to opt in (`EventSource { withCredentials: true }`, or `fetch`
+            with `credentials: 'include'`) **and** the server to answer with
+            `Access-Control-Allow-Credentials` and a non-wildcard origin. Bearer
+            and capability headers likewise need the header to be permitted by
+            the preflight response.
+
+            **None of that is verified by this contract, and contracts has not
+            measured it.** ⇒ **A browser client SHOULD prefer `bearerAuth` or
+            the anonymous capability header on this host**, and should treat
+            cookie-based session auth over it as unproven until somebody
+            measures a credentialed cross-origin stream.
       description: |
         Server-Sent Events endpoint for real-time workflow progress. The server pushes
         events as workflow, job, and operation statuses change.
@@ -2754,6 +2922,29 @@ paths:
         a **409** — cancel it first (`POST /api/workflows/{id}/cancel`) or wait
         for it to finish. Archiving does NOT change the workflow's status; it
         stays terminal and the response echoes it unchanged.
+      # ⚠️ NO PUBLIC HTTP ROUTE EXISTS FOR THIS. Downgraded to `planned`
+      # 2026-08-12 (yi4TDKVJ, raised by sdks + codex) on POSITIVE evidence, as
+      # standing policy 3 requires — not on an absent attestation, which policy
+      # 4 says is not enough:
+      #   * no `#[Route(...)]` matching archive/restore anywhere in
+      #     compression_api's `src/`;
+      #   * no `api/workflows/{id}/archive` or `/restore` path in `src/` or
+      #     `config/`;
+      #   * verified independently by sdks (named commit) and by codex reading
+      #     the list controller and its repository.
+      #
+      # ⚠️ CORRECTION TO THE RELAYED EVIDENCE, because it changes the ticket
+      # rather than the verdict: the claim reaching this repo was that a grep
+      # for `archiveWorkflow|/archive|archived` over `src` and `config`
+      # "returns NO OUTPUT". IT DOES NOT — `ArchiveWorkflowCommand`,
+      # `ArchiveWorkflowCommandHandler` and a `RestoreWorkflow` command all
+      # EXIST, and there is an ADMIN CRUD controller that archives. So this is
+      # **implemented in the application layer and not exposed on the public
+      # API**, which is a different thing from "nothing behind it". The verdict
+      # is unchanged — an unroutable capability is unreachable, so `planned` is
+      # correct — but anyone scoping the work should know a handler already
+      # exists.
+      x-availability: planned
       operationId: archiveWorkflow
       security: [{bearerAuth: []}, {sessionAuth: []}]  # required (explicit 401 in response set)
       x-identity-scoped: true  # workflow-ownership-scoped per ADR-0016 D3
@@ -2845,6 +3036,29 @@ paths:
         `status` is the workflow's unchanged status (any `WorkflowStatus`
         value), not a fixed terminal subset. There is no 409: un-archiving is
         always safe.
+      # ⚠️ NO PUBLIC HTTP ROUTE EXISTS FOR THIS. Downgraded to `planned`
+      # 2026-08-12 (yi4TDKVJ, raised by sdks + codex) on POSITIVE evidence, as
+      # standing policy 3 requires — not on an absent attestation, which policy
+      # 4 says is not enough:
+      #   * no `#[Route(...)]` matching archive/restore anywhere in
+      #     compression_api's `src/`;
+      #   * no `api/workflows/{id}/archive` or `/restore` path in `src/` or
+      #     `config/`;
+      #   * verified independently by sdks (named commit) and by codex reading
+      #     the list controller and its repository.
+      #
+      # ⚠️ CORRECTION TO THE RELAYED EVIDENCE, because it changes the ticket
+      # rather than the verdict: the claim reaching this repo was that a grep
+      # for `archiveWorkflow|/archive|archived` over `src` and `config`
+      # "returns NO OUTPUT". IT DOES NOT — `ArchiveWorkflowCommand`,
+      # `ArchiveWorkflowCommandHandler` and a `RestoreWorkflow` command all
+      # EXIST, and there is an ADMIN CRUD controller that archives. So this is
+      # **implemented in the application layer and not exposed on the public
+      # API**, which is a different thing from "nothing behind it". The verdict
+      # is unchanged — an unroutable capability is unreachable, so `planned` is
+      # correct — but anyone scoping the work should know a handler already
+      # exists.
+      x-availability: planned
       operationId: restoreWorkflow
       security: [{bearerAuth: []}, {sessionAuth: []}]  # required (explicit 401 in response set)
       x-identity-scoped: true  # workflow-ownership-scoped per ADR-0016 D3
@@ -4867,13 +5081,10 @@ paths:
                     properties:
                       updated:
                         type: boolean
-                        enum: [true]
                       name_changed:
                         type: boolean
-                        enum: [true]
                       email_change_requested:
                         type: boolean
-                        enum: [true]
                       message:
                         type: string
               example:
@@ -5642,7 +5853,7 @@ paths:
                   type: subscription
                   key: pro
               credit_pack:
-                summary: Buy a 25-credit pack
+                summary: Buy the £25 credit pack
                 value:
                   type: pack
                   key: pack_25
@@ -7061,6 +7272,17 @@ components:
         - `type: subscription` → `key` ∈ { `pro`, `max` }
         - `type: pack` → `key` ∈ { `pack_10`, `pack_25`, `pack_50` }
 
+        ⚠️ **The number in a pack SKU is the PRICE IN POUNDS, not a credit
+        count** — `pack_25` is the £25 pack, and the credits it grants are a
+        different number entirely, roughly two orders of magnitude larger.
+        **How many** is server-side (api's versioned Stripe catalog) and is
+        deliberately not restated here, because a credit grant that lives in
+        two places drifts — and the copy a customer reads before paying is the
+        one that must not be stale. Clients that need to show it read it from
+        the server; they never infer it from the SKU. *An example on this very
+        endpoint read the SKU as a quantity until 2026-08-12, so the axis is
+        named here rather than assumed obvious.*
+
         The `type` ↔ `key` pairing is validated **server-side**, not by this
         schema (the `key` enum lists all values across both types). A
         mismatched or unprovisioned pair returns `422` `UNPROCESSABLE_ENTITY`;
@@ -7888,7 +8110,6 @@ components:
             workflow is a 409, never a 200.
         archived:
           type: boolean
-          enum: [true]
           description: Always `true` on a 200 — the workflow is archived.
         archived_at:
           type: string
@@ -7930,7 +8151,6 @@ components:
           $ref: '#/components/schemas/WorkflowStatus'
         archived:
           type: boolean
-          enum: [false]
           description: |
             Always `false` on a 200 — the workflow is no longer archived
             (or was never archived; restore is an idempotent no-op there).
@@ -13748,7 +13968,6 @@ components:
           properties:
             same_as_input:
               type: boolean
-              enum: [true]
         - type: object
           additionalProperties: false
           required: [from_option]
@@ -13877,7 +14096,6 @@ components:
               description: Field token under test.
             isSet:
               type: boolean
-              enum: [true]
               description: |
                 Leaf test — asserts `field` is present/set. Only the
                 positive form is used; negate via a wrapping `not` node.
@@ -13917,11 +14135,16 @@ components:
     EndpointProjection:
       type: object
       description: |
-        Per-endpoint projection entry per ADR-0016 §D4. Five fields;
-        `required_tier` and `availability` at endpoint level are
-        reserved/null today (operation-level `required_tier` continues
-        to flow via `operations.*.required_tier`; every shipped
-        endpoint is currently `availability: stable`).
+        Per-endpoint projection entry per ADR-0016 §D4. Five required
+        fields plus an OPTIONAL `servers`; `required_tier` at endpoint
+        level is reserved/null today (operation-level `required_tier`
+        continues to flow via `operations.*.required_tier`).
+
+        ⚠️ **`availability` is DERIVED from the operation's
+        `x-availability` and is no longer always `stable`** — an
+        earlier version of this description said every shipped endpoint
+        was `stable`, which was true only because the generator
+        hardcoded it.
       required:
         - auth
         - identity_scoped
@@ -13929,6 +14152,54 @@ components:
         - availability
         - operation_id
       properties:
+        servers:
+          type: array
+          minItems: 1
+          description: |
+            OPTIONAL. Present **only** when the operation overrides the
+            root host — today, the SSE stream endpoint alone.
+
+            **Absence means "inherits the root `servers`" and is not a
+            gap.** Emitting a copy of the root on every entry would put
+            one value on 43 rows, which conveys nothing and would invite
+            a consumer to read this projection as the routing source of
+            record for endpoints that have no override.
+
+            ⚠️ **This field exists because the declaration was
+            unreachable without it.** The routing split is declared on
+            the operation in `openapi/api.yaml`, but SDK consumers read
+            this sidecar rather than parsing the spec at runtime — so a
+            host declared only in the spec was in the same position as
+            the convention it replaced.
+          items:
+            type: object
+            additionalProperties: false
+            required: [url, replaces]
+            properties:
+              url:
+                type: string
+                format: uri
+                description: The host serving this operation.
+              replaces:
+                type: string
+                minLength: 1
+                description: |
+                  **The ROOT server URL this entry overrides.** A client
+                  matches its own configured base against this exactly
+                  and takes `url`.
+
+                  ⚠️ **Without it the mapping has to be inferred** from
+                  list ordering or hostname shape — which is a
+                  per-client rule, and therefore the precise thing that
+                  declaring the split was meant to remove. An
+                  unmatched base is an honest *"no override for the host
+                  you are pointed at"* rather than a guess.
+              description:
+                type: string
+                description: |
+                  Verbatim from the operation's server entry. Carries
+                  the caveats a URL cannot — CORS scope, whether the
+                  entry exercises the split-host topology at all.
         auth:
           type: string
           enum: [anonymous, optional, required]
@@ -13966,9 +14237,17 @@ components:
           type: string
           enum: [stable, beta, experimental, planned, deprecated]
           description: |
-            Endpoint-level availability tag. Currently always
-            `"stable"` for shipped endpoints. Reserved for future
-            `planned` / `deprecated` endpoint-level annotation.
+            Endpoint-level availability, **DERIVED from the operation's
+            `x-availability`** and defaulting to `stable` when the
+            operation declares none.
+
+            ⚠️ **It is NOT always `stable`.** This description used to
+            say it was, and the sidecar agreed with it — because the
+            generator HARDCODED the value. Four endpoints read `planned`
+            today, three of which (`probeUpload`,
+            `createExternalImport`, `decodeAudioWatermark`) had declared
+            `planned` in the spec all along and were silently
+            contradicted.
         operation_id:
           type: string
           description: |

package/operation-capabilities/operation-capabilities.json

@@ -732,5 +732,5 @@
       "isAnimated": "maybe"
     }
   },
-  "schema_version": "2.191.0"
+  "schema_version": "2.194.0"
 }

package/operations/README.md

@@ -0,0 +1,17 @@
+# TypeScript -- Operation Option Models
+
+> **Auto-generated** -- do not edit manually. Changes will be overwritten on the next generation run.
+>
+> Regenerate with: `make project/generate-tests`
+
+## Source
+
+- **Spec:** `compression_contracts/schemas/operations/*.yaml` (custom schema format)
+- **Generator:** Custom Python emitter (`scripts/generators/operation_schema/typescript.py`)
+- **Files:** 35
+
+## Contents
+
+TypeScript enums and interfaces for per-operation options (compression quality, thumbnail dimensions, conversion formats, etc.).
+
+Operation types covered: archive, audio_overlay, audio_to_video, audio_watermark, compress, convert, custom_luma, image_watermark, merge, passthrough, render_variants, split, text_watermark, thumbnail, transform, video_text_watermark, video_watermark.

package/operations/schemas/compress.yaml

@@ -1268,7 +1268,25 @@ 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)
+      # 200 MiB. RAISED from 100 MiB (Y0tkvebF, lambdas-measured 2026-08-12).
+      # The old cap was real in MECHANISM and calibrated against the WRONG
+      # NUMBER: the ZIP strategy needs Read+Seek so the whole document is in
+      # memory (peak ~= 2x input + largest entry), and the worker comment
+      # justified 100 MiB as fitting "a Lambda with 512 MB+ memory" — but
+      # gisl-{stg,prod}-euw1-compression-document is 3008 MiB, six times that.
+      # At 200 MiB input, peak ~= 450 MiB = 15% of the function.
+      #
+      # WHY IT HAD TO MOVE: hub decision 22 raises the free UPLOAD cap to
+      # ~150 MB, which sits ABOVE this PROCESSING cap — so a free user would
+      # upload a 140 MB DOCX successfully and have the OPERATION reject it.
+      # Under the old 10 MiB upload cap that window could not exist; raising
+      # the upload cap created it.
+      #
+      # ⚠️ The ZIP-bomb guards are a DIFFERENT axis and did NOT move:
+      # MAX_IMAGE_ENTRY_SIZE 50 MB, MAX_ZIP_ENTRIES 10,000,
+      # MAX_CUMULATIVE_IMAGE_BYTES 500 MB bound what a document expands INTO;
+      # this bounds what we ACCEPT.
+      max_input_size_bytes: 209715200
       # See the document_pdf honesty note: the worker reads ONLY `quality` today;
       # the per-format options are `planned` (advertised-ahead, FE-hidden).
       options:
@@ -1301,7 +1319,25 @@ 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)
+      # 200 MiB. RAISED from 100 MiB (Y0tkvebF, lambdas-measured 2026-08-12).
+      # The old cap was real in MECHANISM and calibrated against the WRONG
+      # NUMBER: the ZIP strategy needs Read+Seek so the whole document is in
+      # memory (peak ~= 2x input + largest entry), and the worker comment
+      # justified 100 MiB as fitting "a Lambda with 512 MB+ memory" — but
+      # gisl-{stg,prod}-euw1-compression-document is 3008 MiB, six times that.
+      # At 200 MiB input, peak ~= 450 MiB = 15% of the function.
+      #
+      # WHY IT HAD TO MOVE: hub decision 22 raises the free UPLOAD cap to
+      # ~150 MB, which sits ABOVE this PROCESSING cap — so a free user would
+      # upload a 140 MB DOCX successfully and have the OPERATION reject it.
+      # Under the old 10 MiB upload cap that window could not exist; raising
+      # the upload cap created it.
+      #
+      # ⚠️ The ZIP-bomb guards are a DIFFERENT axis and did NOT move:
+      # MAX_IMAGE_ENTRY_SIZE 50 MB, MAX_ZIP_ENTRIES 10,000,
+      # MAX_CUMULATIVE_IMAGE_BYTES 500 MB bound what a document expands INTO;
+      # this bounds what we ACCEPT.
+      max_input_size_bytes: 209715200
       # See the document_pdf honesty note: worker reads ONLY `quality`; the rest `planned`.
       options:
         quality:
@@ -1327,7 +1363,25 @@ operation:
     document_epub:
       mimes:
         - application/epub+zip
-      max_input_size_bytes: 104857600   # 100 MiB compress input ceiling (uKsFzORi; zip-based worker MAX_INPUT_SIZE)
+      # 200 MiB. RAISED from 100 MiB (Y0tkvebF, lambdas-measured 2026-08-12).
+      # The old cap was real in MECHANISM and calibrated against the WRONG
+      # NUMBER: the ZIP strategy needs Read+Seek so the whole document is in
+      # memory (peak ~= 2x input + largest entry), and the worker comment
+      # justified 100 MiB as fitting "a Lambda with 512 MB+ memory" — but
+      # gisl-{stg,prod}-euw1-compression-document is 3008 MiB, six times that.
+      # At 200 MiB input, peak ~= 450 MiB = 15% of the function.
+      #
+      # WHY IT HAD TO MOVE: hub decision 22 raises the free UPLOAD cap to
+      # ~150 MB, which sits ABOVE this PROCESSING cap — so a free user would
+      # upload a 140 MB DOCX successfully and have the OPERATION reject it.
+      # Under the old 10 MiB upload cap that window could not exist; raising
+      # the upload cap created it.
+      #
+      # ⚠️ The ZIP-bomb guards are a DIFFERENT axis and did NOT move:
+      # MAX_IMAGE_ENTRY_SIZE 50 MB, MAX_ZIP_ENTRIES 10,000,
+      # MAX_CUMULATIVE_IMAGE_BYTES 500 MB bound what a document expands INTO;
+      # this bounds what we ACCEPT.
+      max_input_size_bytes: 209715200
       # See the document_pdf honesty note: worker reads ONLY `quality`; the rest `planned`.
       options:
         quality:

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@giveitsmaller/contracts",
-  "version": "0.62.0",
-  "description": "Generated contract types for GISL (Give It Smaller)",
+  "version": "0.65.0",
+  "description": "Generated contract types for GISL (Give It Smaller). Generated from compression_contracts spec v2.194.0.",
+  "gislContractsSpec": "v2.194.0",
   "license": "Apache-2.0",
   "type": "module",
   "main": "./dist/index.js",
@@ -49,6 +50,7 @@
     "./operations/schemas/video_watermark.yaml": "./operations/schemas/video_watermark.yaml"
   },
   "files": [
+    "README.md",
     "dist/",
     "openapi/api.yaml",
     "asyncapi/events.yaml",