@giveitsmaller/contracts 0.50.0 → 0.53.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.154.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
@@ -6921,7 +7187,7 @@ components:
           exceeds the per-input ceiling (`max_input_size_bytes` /
           `max_input_duration`). Applies to single-input operations
           (compress, convert, thumbnail, text_watermark,
-          audio_watermark) AND per-input checks on multi-input
+          audio_watermark, transform) AND per-input checks on multi-input
           operations with per-input caps (image_watermark,
           custom_luma, audio_overlay).
         - `combined_size_exceeds_long_form` /
@@ -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.
@@ -7328,6 +7594,8 @@ components:
         - split: Fan one input file into N outputs across GIF / PDF / audio / video MIME families. Single-input per-mime-group catalog (mirrors merge/convert): GIF uses `frame_range` (REQUIRED) + `output_format`; PDF uses `page_range` OR `page_groups` (mutually exclusive); audio + video use a `mode` discriminator (interval/count/cut_points) + numeric-seconds wire format + `precision` flag (fast/exact). 200-output hard cap per ADR-0009 §D5 with per-mode preflight math; output naming `output-001..output-200`. Long-form video routes to a separate `split-video-fargate` worker via `processing_class`. `availability: beta` for the `audio` and `video` mime_groups (workers live on staging — shape-stable + opt-in, MUST NOT 422); video activates BOTH classes (`video.processing_class.short_form: beta` AND `long_form: beta` — `split-video-fargate` deployed + wired on staging but NOT yet proven end-to-end per [`rcwvUKhI`](https://trello.com/c/rcwvUKhI); the first customer-path soak has not completed, the 4GB+ speed-up is unmeasured, and the long-form fan-out is flag-gated dark). The `image_gif` and `document_pdf` mime_groups stay `availability: planned` and dispatch returns `feature_not_available` (422) until their workers ship. Per ticket [`vKI0CFDu`](https://trello.com/c/vKI0CFDu) + ADR-0014.
         - passthrough: Inert lossless source operation. A single-input source job whose SOLE operation is `passthrough` emits its source bytes UNCHANGED — no compression, no Lambda. The API self-completes the job at publish (terminal output = the upload `{bucket, key}` unchanged). Its purpose is to feed an uploaded file into a multi-input operation LOSSLESSLY: because `JobInputV2.source` is narrowed to exclude upload-direct, an upload that must enter a `merge` / `archive` / `image_watermark` op enters via a `passthrough` source job referenced downstream by `{type: job_output, from: <id>}` — preserving billing / DAG / lineage. Distinct from `operations: []` (which keeps its implicit-compress meaning on a single-input upload job); `passthrough` is the EXPLICIT lossless path via the "non-empty `operations[]` without `compress` = compression opt-out" rule. Media-agnostic; no options. `availability: beta` — activated (the inputs[]-narrowing + passthrough self-complete mechanism is deployed API-side); workflow-create accepts `passthrough` source jobs and MUST NOT return `feature_not_available`. **Never published to SNS** — deliberately absent from the AsyncAPI routing enums (API self-completes; no `ops-passthrough` queue). Per ticket [`4som89Uh`](https://trello.com/c/4som89Uh) + ADR-0004 (planned→beta flip).
 
+        - transform: Geometric/orientation transform — v1 = rotate (0/90/180/270) + flip (none/horizontal/vertical/both), ADR-0026. Single-input; `produces: same_as_input` (geometry preserves format/container). Chainable (NOT sole_op); canonical single-job chain order is `transform → convert → compress → thumbnail` (geometry before encode/derive so downstream width/height/fit refer to the final frame). Media groups: image (still jpeg/png/webp + animated `image_gif`), video (mp4/webm), document (PDF page-rotate only — no flip); audio not supported. ALL groups `availability: planned` (epic `fhiWebI0`) — workflow-create returns `feature_not_available` (422) until per-media Lambdas ship. A no-op transform (`rotate: 0` + `flip: none`) is rejected as `invalid_options`. The public operation type is `transform`; the API resolves an internal per-media SNS routing sub-type (`transform_image` / `transform_video` / `transform_document`) — those sub-types are routing-only and are NOT part of this public enum. Per ADR-0026.
+
         Both the legacy `thumbnail` value and the four sub-type values
         are valid routing targets today during the thumbnail migration
         window. See `asyncapi/events.yaml` for the full routing
@@ -7356,6 +7624,7 @@ components:
         - video_watermark
         - video_text_watermark
         - split
+        - transform
         - passthrough
 
     OperationInputModel:
@@ -7365,8 +7634,8 @@ components:
         - single: One input file (compress, thumbnail, thumbnail_image,
           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.
+          video_text_watermark, split, transform, 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 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
@@ -9142,12 +9411,18 @@ components:
           description: |
             The canonical pipeline spine (single mutated stream), as an
             ordered list of `chain_group` stage names. The known image/AV
-            spine is `merge` (fan-in) → `image_watermark` → `text_watermark`
-            → `audio` → `encode` (terminal: convert+compress folded) →
-            `derived` (fan-out: thumbnail/split). Informational — read per-op
-            `chain_group` / `chain_position` for placement. The geometry
-            stage is intentionally not exposed as a node for v1 (image
-            resize/fit live inside the thumbnail node).
+            spine is `transform` (geometry: rotate/flip) → `merge` (fan-in)
+            → `image_watermark` → `text_watermark` → `audio` → `encode`
+            (terminal: convert+compress folded) → `derived` (fan-out:
+            thumbnail/split). Informational — read per-op `chain_group` /
+            `chain_position` for placement. The `transform` geometry stage
+            (ADR-0026) runs FIRST — orientation before resize/encode so
+            downstream width/height/fit refer to the final frame; its
+            canonical single-job order is `transform → convert → compress →
+            thumbnail`. It is `availability: planned` (epic `fhiWebI0`) — no
+            transform nodes are produced until it activates. (Image
+            resize/fit still live inside the `thumbnail` node — that is a
+            separate stage from the `transform` op.)
 
             **Open string, NOT a fixed enum** (mirrors
             `ProcessingPlanJob.execution_pool`): the canonical model still
@@ -9227,6 +9502,9 @@ components:
             `additionalProperties: false`; consumers MUST treat unknown
             stage names as forward-compatible. The watermark stages are
             **media-agnostic overlay stages**, not image-only. Known stages:
+            - `transform`: geometry stage (rotate/flip) — covers the
+              `transform` operation type. Runs first in the spine (ADR-0026);
+              `availability: planned` until activation.
             - `merge`: fan-in.
             - `image_watermark`: raster/image-overlay watermark stage —
               covers the `image_watermark` AND `video_watermark` operation
@@ -9839,10 +10117,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 +10266,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
       },
@@ -414,6 +454,21 @@
       },
       "sole_op": false
     },
+    "transform": {
+      "accepts": [
+        "document",
+        "image",
+        "video"
+      ],
+      "availability": "planned",
+      "input": {
+        "model": "single"
+      },
+      "produces": {
+        "same_as_input": true
+      },
+      "sole_op": false
+    },
     "video_text_watermark": {
       "accepts": [
         "video"
@@ -525,5 +580,5 @@
       "isAnimated": "maybe"
     }
   },
-  "schema_version": "2.148.0"
+  "schema_version": "2.154.0"
 }