@giveitsmaller/contracts 0.50.0 → 0.51.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.148.0
+  version: 2.152.0
   contact:
     name: API Support
 
@@ -4653,6 +4653,200 @@ paths:
               schema:
                 $ref: '#/components/schemas/ErrorEnvelope'
 
+  # ============================================
+  # BILLING CHECKOUT ENDPOINT
+  # ============================================
+
+  /api/billing/checkout:
+    post:
+      summary: Start a Stripe hosted-Checkout session
+      description: |
+        Create a Stripe **hosted Checkout** session for a subscription
+        upgrade or a credit-pack purchase, and return the Stripe-hosted
+        `checkout_url` for the frontend to redirect the browser to.
+
+        The client supplies only `type` + `key`; the Stripe
+        `success_url` / `cancel_url` redirect targets are **server-set**.
+
+        Gated behind the server `STRIPE_CHECKOUT_ENABLED` flag: while the
+        flag is OFF the endpoint returns `422` `feature_not_available`
+        (`FeatureNotAvailableResponse`, single violation
+        `endpoint.billing.checkout`, `availability: planned`) so the
+        frontend can hide/disable the upgrade affordance without
+        hard-coding the rollout state.
+
+        The Stripe **webhook** (`POST /api/webhooks/stripe`) is a
+        server-to-server, signature-authenticated callback and is
+        deliberately **not** part of this client contract.
+
+        Per the Stripe go-live (routed 2026-07-02).
+      operationId: createBillingCheckoutSession
+      security: [{bearerAuth: []}, {sessionAuth: []}]  # required (IS_AUTHENTICATED_FULLY; anonymous/partial sessions → 401)
+      x-identity-scoped: true  # the checkout session is created for the authenticated caller
+      tags:
+        - Billing
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/BillingCheckoutRequest'
+            examples:
+              subscription_pro:
+                summary: Upgrade to the Pro subscription
+                value:
+                  type: subscription
+                  key: pro
+              credit_pack:
+                summary: Buy a 25-credit pack
+                value:
+                  type: pack
+                  key: pack_25
+      responses:
+        '200':
+          description: Checkout session created; redirect the browser to `checkout_url`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/BillingCheckoutSuccessEnvelope'
+              example:
+                success: true
+                data:
+                  checkout_url: "https://checkout.stripe.com/c/pay/cs_test_a1b2c3"
+                  session_id: "cs_test_a1b2c3"
+        '400':
+          description: "Malformed JSON request body (`error: INVALID_JSON`)."
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: INVALID_JSON
+                message: "Malformed JSON in request body."
+        '401':
+          description: |
+            Authentication required (`error: UNAUTHORIZED`). Anonymous or
+            partially-authenticated (remember-me) sessions are rejected —
+            the endpoint requires a fully-authenticated caller.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: UNAUTHORIZED
+                message: "Authentication required."
+        '422':
+          description: |
+            One of three flavours — dispatch on `error_type` (present only
+            on the feature-gate branch), then on the `error` machine code:
+
+            - **`error_type: feature_not_available`**
+              (`FeatureNotAvailableResponse`, carries `violations[]`) —
+              checkout is flag-gated OFF (`STRIPE_CHECKOUT_ENABLED=false`).
+              The single violation names feature `endpoint.billing.checkout`
+              (`availability: planned`). The frontend hides the upgrade
+              affordance on this branch.
+            - **`error: VALIDATION_FAILED`** (plain `ErrorEnvelope`, no
+              `error_type`) — `type` is missing or not one of
+              `subscription` / `pack`, or `key` is empty.
+            - **`error: UNPROCESSABLE_ENTITY`** (plain `ErrorEnvelope`, no
+              `error_type`) — the `type` + `key` pair does not resolve to a
+              provisioned plan or pack (a mismatched pair such as
+              `subscription` + `pack_10`, or an unknown/unprovisioned
+              `key`). The pairing is validated server-side, not by the
+              request schema.
+          content:
+            application/json:
+              schema:
+                # Non-overlapping oneOf, discriminable by `error_type` presence:
+                # the flag-off branch (FeatureNotAvailableResponse) always carries
+                # `error_type: feature_not_available` + `violations[]`; the generic
+                # validation branch is a plain ErrorEnvelope with NO `error_type`
+                # (the `not: required` guard keeps the two branches mutually
+                # exclusive so a feature-gate body cannot also match the generic
+                # branch — the workflows 422 uses a discriminated oneOf, but that
+                # needs `error_type` on every branch, which these two flat codes
+                # do not carry).
+                oneOf:
+                  - $ref: '#/components/schemas/FeatureNotAvailableResponse'
+                  - allOf:
+                      - $ref: '#/components/schemas/ErrorEnvelope'
+                      - not:
+                          required: [error_type]
+              examples:
+                feature_not_available:
+                  summary: Checkout flag is off (STRIPE_CHECKOUT_ENABLED=false)
+                  value:
+                    success: false
+                    error_type: feature_not_available
+                    error: FEATURE_NOT_AVAILABLE
+                    message: "Checkout is not yet available."
+                    violations:
+                      - feature: endpoint.billing.checkout
+                        availability: planned
+                        message_key: feature.not_available
+                validation_failed:
+                  summary: Missing / invalid type or empty key
+                  value:
+                    success: false
+                    error: VALIDATION_FAILED
+                    message: "Invalid checkout request: 'type' must be 'subscription' or 'pack' and 'key' is required."
+                unprocessable_entity:
+                  summary: type/key pair does not resolve to a provisioned plan or pack
+                  value:
+                    success: false
+                    error: UNPROCESSABLE_ENTITY
+                    message: "The requested plan or pack is not available."
+        '429':
+          description: |
+            Rate limit exceeded (`error: TOO_MANY_REQUESTS`). The billing
+            endpoint family has its own tiered limiter; the response carries
+            `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset`
+            headers.
+          headers:
+            X-RateLimit-Limit:
+              required: false
+              description: Requests permitted in the current window.
+              schema:
+                type: integer
+                minimum: 0
+            X-RateLimit-Remaining:
+              required: false
+              description: Requests remaining in the current window.
+              schema:
+                type: integer
+                minimum: 0
+            X-RateLimit-Reset:
+              required: false
+              description: Unix epoch seconds when the current window resets.
+              schema:
+                type: integer
+                minimum: 0
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '503':
+          description: |
+            Checkout temporarily unavailable — the flag is on but Stripe is
+            not configured on the server (`error: SERVICE_UNAVAILABLE`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: SERVICE_UNAVAILABLE
+                message: "Checkout is temporarily unavailable."
+        '500':
+          description: Internal server error (e.g. an unexpected Stripe SDK error).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+
   # ============================================
   # CONTACT ENDPOINT
   # ============================================
@@ -5828,6 +6022,78 @@ components:
         tier:
           $ref: '#/components/schemas/UserTier'
 
+    BillingCheckoutRequest:
+      type: object
+      additionalProperties: false
+      description: |
+        Request body for `POST /api/billing/checkout`. The client supplies
+        only the target `type` + `key`; the Stripe `success_url` /
+        `cancel_url` redirect targets are server-set. Unknown extra
+        properties are rejected.
+
+        Valid `key` values partition by `type`:
+        - `type: subscription` → `key` ∈ { `pro`, `max` }
+        - `type: pack` → `key` ∈ { `pack_10`, `pack_25`, `pack_50` }
+
+        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`;
+        a missing `type` or empty `key` returns `422` `VALIDATION_FAILED`.
+      required:
+        - type
+        - key
+      properties:
+        type:
+          type: string
+          enum: [subscription, pack]
+          description: |
+            Whether the checkout is for a recurring `subscription` upgrade
+            or a one-off credit `pack` purchase.
+        key:
+          type: string
+          enum: [pro, max, pack_10, pack_25, pack_50]
+          description: |
+            The specific plan or pack to purchase. Must be consistent with
+            `type` (subscription → `pro` / `max`; pack → `pack_10` /
+            `pack_25` / `pack_50`) — the pairing is server-validated.
+
+    BillingCheckoutSession:
+      type: object
+      # Open payload (the response-data target stays open for additive
+      # evolution — matches CreditsBalanceResponse / AccountLimits; the
+      # enclosing BillingCheckoutSuccessEnvelope is the closed shape). New
+      # top-level fields (e.g. an expiry) may be added without a breaking
+      # change.
+      description: |
+        The created Stripe hosted-Checkout session — the redirect URL plus
+        the Stripe session id.
+      required:
+        - checkout_url
+        - session_id
+      properties:
+        checkout_url:
+          type: string
+          format: uri
+          description: The Stripe-hosted Checkout URL to redirect the browser to.
+        session_id:
+          type: string
+          description: |
+            The Stripe Checkout Session id (`cs_...`). Opaque; useful for
+            correlation / observability.
+
+    BillingCheckoutSuccessEnvelope:
+      type: object
+      additionalProperties: false
+      required:
+        - success
+        - data
+      properties:
+        success:
+          type: boolean
+          enum: [true]
+        data:
+          $ref: '#/components/schemas/BillingCheckoutSession'
+
     CreditsBalanceSuccessEnvelope:
       type: object
       additionalProperties: false
@@ -7314,7 +7580,7 @@ components:
         - thumbnail_office: Office document (DOCX/XLSX/PPTX/ODT/ODS/ODP)
           thumbnail sub-type. Backed by a dedicated LibreOffice Lambda.
           Emitted by the publisher for office-document inputs.
-        - image_watermark: Image overlay onto a base IMAGE asset. Multi-input (Path B with role: base + overlay). Each input is a `MultiInputSource` (external_import / connection / job_output — no upload-direct); an uploaded base or overlay enters via a `passthrough` source job referenced by `job_output`. Stable for static-image bases (jpeg/png/webp); TIFF (`image_tiff`) and BMP (`image_bmp`) bases are now `stable` too (flipped 2026-06-30, UANjD38A). Animated GIF (`image_gif`) bases stay `planned` via a parallel mime_group — dispatch returns `feature_not_available` (422) until Lambda support ships. Video bases are NOT supported by image_watermark — use the dedicated `video_watermark` operation per ADR-0013. Per ADR-0004 + I4-CONS + I5 (Trello AKZiOXnd).
+        - image_watermark: Image overlay onto a base IMAGE asset. Multi-input (Path B, role-based): one `base` + 1–8 `overlay` inputs (`input` min 2 / max 9). A single overlay uses the flat placement options (`anchor` / `margin_x` / `margin_y` / `opacity` / `overlay_width`); 2–8 overlays use the index-aligned `overlays[]` array (multi_overlay_stack, LIVE 2026-07-01) — the two are mutually exclusive. Each input is a `MultiInputSource` (external_import / connection / job_output — no upload-direct); an uploaded base or overlay enters via a `passthrough` source job referenced by `job_output`. Stable for static-image bases (jpeg/png/webp); TIFF (`image_tiff`) and BMP (`image_bmp`) bases are now `stable` too (flipped 2026-06-30, UANjD38A). Animated GIF (`image_gif`) bases stay `planned` via a parallel mime_group — dispatch returns `feature_not_available` (422) until Lambda support ships. Video bases are NOT supported by image_watermark — use the dedicated `video_watermark` operation per ADR-0013. Per ADR-0004 + I4-CONS + I5 (Trello AKZiOXnd).
         - text_watermark: Text overlay rendered onto an image (Liberation Sans). Single-input. Stable for jpeg/png/webp; TIFF (`image_tiff`) and BMP (`image_bmp`) inputs are now `stable` too (flipped 2026-06-30, UANjD38A). Per ADR-0004 + I4-CONS.
         - merge: Concatenate/combine multiple files into one (images, video, audio). Multi-input. Image inputs merge into animated GIF or slideshow video; image collage/grid and PDF concatenation are not supported by the V1 Lambda.
         - archive: Bundle files into ZIP/tar.gz (all types). Multi-input.
@@ -7366,7 +7632,7 @@ components:
           thumbnail_video, thumbnail_document, thumbnail_office,
           text_watermark, convert, audio_watermark,
           video_text_watermark, split, passthrough)
-        - multi: Multiple input files (merge, archive, image_watermark, custom_luma, audio_overlay, audio_to_video, video_watermark). audio_to_video is the first role-based op with an OPTIONAL role (min_inputs=1, max_inputs=2 — see `per_role_cardinality`); video_watermark mirrors `image_watermark`'s 2-required pattern on video bases.
+        - multi: Multiple input files (merge, archive, image_watermark, custom_luma, audio_overlay, audio_to_video, video_watermark). audio_to_video is the first role-based op with an OPTIONAL role (min_inputs=1, max_inputs=2 — see `per_role_cardinality`); video_watermark is a fixed base+overlay pair (exactly one each, min_inputs=max_inputs=2) on video bases; image_watermark widened to base + 1–8 overlays (min 2 / max 9) with the multi_overlay_stack flip (2026-07-01).
       enum:
         - single
         - multi
@@ -9839,10 +10105,10 @@ components:
             [`RrxdUBGZ`](https://trello.com/c/RrxdUBGZ) / `i2J8AMy6`.
         credits:
           description: |
-            OPTIONAL. Per-workflow credit summary (`reserved` / `refunded` /
-            `net` + settlement `state`) for the credits-per-run readout — what
-            this run cost. `null` for legacy workflows with no credit record.
-            See `WorkflowCreditSummary`. Per ticket `7XbqXO1B`.
+            OPTIONAL. Per-workflow credit summary — the net cost of the run
+            (`used`). `null` for legacy workflows with no credit record (or
+            while a run has no final charge yet). See `WorkflowCreditSummary`.
+            Per ticket `7XbqXO1B` (reshaped to `{ used }`-only per `DsHbIlC1`).
           oneOf:
             - $ref: '#/components/schemas/WorkflowCreditSummary'
             - type: 'null'
@@ -9988,66 +10254,46 @@ components:
             $ref: '#/components/schemas/WorkflowSummaryJob'
         credits:
           description: |
-            OPTIONAL. Per-workflow credit summary (`reserved` / `refunded` /
-            `net` + settlement `state`) so the list row can show what each run
-            cost. `null` for legacy workflows with no credit record. Same shape
-            as `WorkflowStatusResponse.credits`. Per ticket `7XbqXO1B`.
+            OPTIONAL. Per-workflow credit summary — the net cost of the run
+            (`used`) so the list row can show what each run cost. `null` for
+            legacy workflows with no credit record. Same shape as
+            `WorkflowStatusResponse.credits`. Per ticket `7XbqXO1B` (reshaped to
+            `{ used }`-only per `DsHbIlC1`).
           oneOf:
             - $ref: '#/components/schemas/WorkflowCreditSummary'
             - type: 'null'
 
     WorkflowCreditSummary:
       type: object
+      additionalProperties: false
       description: |
-        Per-workflow credit summary for the workflows-history read
-        (credits-per-run). Exposes the billing-ledger figures so the UI can show
-        what a run cost without treating an in-flight reservation as a final
-        charge — `state` distinguishes a held reservation from a settled charge.
-        Additive; the enclosing `credits` field is `null` for legacy workflows
-        with no credit record. Per ticket `7XbqXO1B`.
+        Per-workflow credit summary for the workflow reads — the net cost of a
+        run. Exposes ONLY `used` (the net credits charged); the internal
+        reservation mechanics (`reserved` / `refunded` / lifecycle `state`) are
+        deliberately NOT surfaced — a user-facing cost readout needs only the
+        net figure, and `reserved` would leak a worst-case COGS estimate. The
+        schema is CLOSED (`additionalProperties: false`) so the removed
+        reservation fields cannot leak back into the payload.
+
+        The enclosing `credits` field is `null` for legacy workflows with no
+        credit record, and may be `null`/absent while a run has no charge yet.
+        Per ticket `7XbqXO1B` (reshaped to `{ used }` per `DsHbIlC1` — product
+        decision to show net cost only).
       required:
-        - reserved
-        - refunded
-        - net
-        - state
+        - used
       properties:
-        reserved:
-          type: integer
-          minimum: 0
-          description: Credits reserved (held) for the workflow at create time.
-        refunded:
+        used:
           type: integer
           minimum: 0
           description: |
-            Credits refunded back to the caller (e.g. on failure / partial
-            completion / released reservation).
-        net:
-          type: integer
-          minimum: 0
-          description: |
-            Net credits charged for the run (`reserved` − `refunded`).
-            AUTHORITATIVE for every non-`active` `state` (both `settled` and
-            `released`); only while `state` is `active` is it a
-            current-but-not-yet-final figure.
-        state:
-          type: string
-          enum: [active, settled, released]
-          description: |
-            A UI-facing PROJECTION of the workflow's billing-ledger reservation
-            lifecycle into three states — the API maps the underlying ledger
-            states into exactly one of these (consumers read only this projected
-            value, not the raw ledger state):
-            - `active` — reservation held, charge NOT yet final (a UI MUST NOT
-              present `net` as the final cost).
-            - `settled` — final charge applied; `net` is authoritative.
-            - `released` — the reservation reached a terminal NON-settled
-              outcome (released / cancelled / expired / fully-refunded — they
-              all project here); `net` is authoritative (typically 0, or the
-              partial charge that stuck).
-
-            Both non-`active` states are TERMINAL with an authoritative `net`;
-            the `active` vs non-`active` split is the only distinction a cost
-            readout needs (don't show a final figure while `active`).
+            Net credits charged for the run (the value the old `net` field
+            carried). AUTHORITATIVE (final) only once the workflow reaches a
+            TERMINAL status — while the run is in flight this is a
+            current-but-not-yet-final figure. Consumers MUST gate any "final
+            cost" display on the workflow's terminal status: the removed `state`
+            field previously carried the active-vs-final distinction, so read
+            the workflow status instead (do not present `used` as the final
+            charge while the run is still in flight).
 
     CodegenSource:
       type: object

package/operation-capabilities/operation-capabilities.json

@@ -294,7 +294,7 @@
       ],
       "availability": "stable",
       "input": {
-        "max": 2,
+        "max": 9,
         "min": 2,
         "model": "multi",
         "roles": [
@@ -302,6 +302,46 @@
           "overlay"
         ]
       },
+      "option_conflicts": [
+        {
+          "availability": "stable",
+          "constraint_id": "image_watermark.overlays_vs_flat_options",
+          "message": "`overlays[]` (multi-overlay) is mutually exclusive with the flat single-overlay options (anchor / margin_x / margin_y / opacity / overlay_width) \u2014 set one mode, not both.",
+          "when": {
+            "all": [
+              {
+                "field": "image_watermark.overlays",
+                "isSet": true
+              },
+              {
+                "any": [
+                  {
+                    "field": "image_watermark.anchor",
+                    "isSet": true
+                  },
+                  {
+                    "field": "image_watermark.margin_x",
+                    "isSet": true
+                  },
+                  {
+                    "field": "image_watermark.margin_y",
+                    "isSet": true
+                  },
+                  {
+                    "field": "image_watermark.opacity",
+                    "isSet": true
+                  },
+                  {
+                    "field": "image_watermark.overlay_width",
+                    "isSet": true
+                  }
+                ]
+              }
+            ]
+          },
+          "wire_code": "invalid_options"
+        }
+      ],
       "produces": {
         "same_as_input": true
       },
@@ -525,5 +565,5 @@
       "isAnimated": "maybe"
     }
   },
-  "schema_version": "2.148.0"
+  "schema_version": "2.152.0"
 }

package/operations/schemas/image_watermark.yaml

@@ -44,30 +44,53 @@ operation:
   input_model: multi
   sole_op: true   # bypasses V1 chain validation — must be the only operation in its job (ADR-0025)
   min_inputs: 2
-  max_inputs: 2
+  max_inputs: 9
 
-  # Per-role input-count constraints (ADR-0015). Both roles REQUIRED,
-  # exactly one each. Arithmetic-consistency rule (CI-checked):
-  # - sum(role.min) == min_inputs  (1 + 1 = 2)
-  # - sum(role.max) == max_inputs  (1 + 1 = 2)
+  # Per-role input-count constraints (ADR-0015). base REQUIRED exactly one;
+  # overlay 1-8 (multi-overlay stack LIVE 2026-07-01). Arithmetic-consistency
+  # rule (CI-checked): sum(role.min) == min_inputs (1 + 1 = 2); sum(role.max) ==
+  # max_inputs (1 + 8 = 9). Per-role counts are WORKER-enforced (the API validates
+  # only the coarse TOTAL via input min/max); per_role_cardinality is advisory.
   per_role_cardinality:
     base:
       min: 1
       max: 1
     overlay:
       min: 1
-      max: 1
+      max: 8
 
   features:
     multi_overlay_stack:
-      availability: planned
+      # LIVE 2026-07-01: flipped planned->stable on the lambdas worker proof
+      # (operation-image-watermark git-2999507, digest-verified;
+      # prove-multi-overlay-staging.sh — 3 index-aligned overlays each rendering
+      # their own colour at their anchor; mutex + cardinality worker-enforced).
+      # Co-landed with `input` max 2->9 + per_role overlay{1,8} + overlays[]
+      # executable + api's overlays[] validation & FNA-gate removal (uUdre4jg).
+      # availability set EXPLICITLY (matches the audio_overlay / video_watermark
+      # multi_overlay_stack features, which stay `planned` — their workers are
+      # unproven for multi-overlay).
+      availability: stable
       description: |
-        Allow up to 8 overlay inputs per job (currently capped at 1
-        overlay). Per-overlay placement via per-input placement options.
-        Backend support not yet confirmed; tagged planned. Scope is
-        image-base only at the time this feature was specified; extension
-        to GIF / video bases tracks alongside the corresponding mime_group
-        `planned` → `stable` flips.
+        Stack up to 8 overlay inputs on one base image, each with its own
+        placement via the `overlays[]` array option (index-aligned to the
+        overlay-role sources; see the `image` group's `overlays` option).
+        `overlays[]` is mutually exclusive with the flat single-overlay options,
+        which remain the 1-overlay back-compat path.
+
+        **Base-format scope: multi-overlay (`overlays[]`) is on the `image`
+        group (jpeg/png/webp) ONLY** — the format the worker proved. The
+        stable `image_tiff` / `image_bmp` bases support the SINGLE-overlay flat
+        options but NOT `overlays[]` yet (multi-overlay on those bases needs its
+        own worker proof — a base-format extension, separate from the group's
+        stable single-overlay flip). GIF / video bases remain out of scope.
+
+        The op-level `input` max 9 / `per_role_cardinality` overlay `{1,8}` is
+        the MAXIMUM (the jpeg/png/webp base); input-cardinality has no per-mime-
+        group primitive, so a `>1`-overlay request on a tiff/bmp base — which
+        has no `overlays[]` to place the extra overlays — is rejected as
+        `invalid_options` (API + worker). Effective per-base overlay count:
+        jpeg/png/webp = 1–8, tiff/bmp = 1.
 
   mime_groups:
     image:
@@ -144,6 +167,91 @@ operation:
             Optional overlay width as either pixels (e.g. "200px") or
             percentage of base image width (e.g. "30%"). Aspect ratio is
             preserved. Omit to use the original overlay size.
+        overlays:
+          type: array
+          minItems: 1
+          maxItems: 8
+          # LIVE 2026-07-01 (no availability tag = stable): the multi-overlay-stack
+          # surface (features.multi_overlay_stack), flipped planned->stable on the
+          # lambdas worker proof (git-2999507). INDEX-ALIGNED to the overlay-role
+          # sources: overlays[i] applies to overlay source i. The option DSL has no
+          # source-array-length-match primitive, so `len(overlays) == overlay-source
+          # count` is WORKER-enforced (invalid_options otherwise) — prose below.
+          # Cardinality (co-design with lambdas + api): per-role counts are
+          # WORKER-enforced (base{1,1} + overlay{1,8}); the API validates only the
+          # coarse TOTAL input count via `input` min/max (2..9), so
+          # per_role_cardinality stays ADVISORY. The item sub-schema mirrors the flat
+          # single-overlay options (JSON-Schema forms per the render_variants.targets
+          # array-of-objects precedent).
+          # COEXISTENCE: `overlays[]` is MUTUALLY EXCLUSIVE with the flat
+          # single-overlay options (anchor/margin_x/margin_y/opacity/
+          # overlay_width) — setting both in one request is `invalid_options`
+          # (api create-validation + worker). No silent precedence; the caller
+          # picks ONE mode. (The option DSL has no cross-option-group mutex
+          # primitive, so this is validator-enforced, documented here + in prose.)
+          description: |
+            Per-overlay placement for the multi-overlay stack — one entry per
+            overlay source, INDEX-ALIGNED: `overlays[i]` applies to overlay
+            source `i`. Stacks up to 8 overlays on one base
+            (`features.multi_overlay_stack`). `len(overlays)` MUST equal the
+            number of overlay-role sources (worker-enforced; `invalid_options`
+            otherwise).
+
+            **Z-order = array index (painter's order, bottom → top).** Overlays
+            are composited in array/source order: `overlays[0]` first (bottom),
+            then `overlays[1]`, … `overlays[N-1]` LAST (on top). Where two
+            overlays overlap, the higher index wins. There is no per-overlay
+            `z` field — the index IS the z-order. (Deterministic in the worker;
+            identical per-frame for animated-WebP bases.)
+
+            **Mutually exclusive with the flat single-overlay options**
+            (`anchor` / `margin_x` / `margin_y` / `opacity` / `overlay_width`):
+            a request that sets BOTH `overlays[]` and any flat option is
+            rejected as `invalid_options` (API create-validation + worker) —
+            there is no silent precedence. Use the flat options for the
+            single-overlay path, `overlays[]` for the multi path.
+
+            LIVE (flipped `planned` -> stable 2026-07-01 on the lambdas worker
+            proof, co-landed with `input` max 2 -> 9 + `per_role_cardinality`
+            overlay `{1,8}` + api's overlays[] validation & FNA-gate removal).
+            The single-overlay FLAT options remain the 1-overlay back-compat path.
+          items:
+            type: object
+            properties:
+              anchor:
+                type: string
+                enum:
+                  - top_left
+                  - top_center
+                  - top_right
+                  - center_left
+                  - center
+                  - center_right
+                  - bottom_left
+                  - bottom_center
+                  - bottom_right
+                default: bottom_right
+                description: 9-grid anchor position on the base image (per-overlay; see the flat `anchor`).
+              margin_x:
+                type: string
+                pattern: '^\d+(\.\d+)?(px|%)$'
+                default: "0px"
+                description: Horizontal offset from the anchor (px or % of base width), anchor-relative (see the flat `margin_x`).
+              margin_y:
+                type: string
+                pattern: '^\d+(\.\d+)?(px|%)$'
+                default: "0px"
+                description: Vertical offset from the anchor (px or % of base height), anchor-relative (see the flat `margin_y`).
+              opacity:
+                type: number
+                minimum: 0
+                maximum: 1
+                default: 0.5
+                description: Overlay opacity (0 transparent .. 1 opaque), clamped.
+              overlay_width:
+                type: string
+                pattern: '^\d+(\.\d+)?(px|%)$'
+                description: Optional overlay width (px or % of base width); aspect preserved. Omit for original size.
 
     # Animated GIF base — separate group because the rendering path is
     # frame-preserving (each frame composited with the overlay), distinct

package/package.json

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