@giveitsmaller/contracts 0.46.0 → 0.47.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.130.0
+  version: 2.133.0
   contact:
     name: API Support
 
@@ -1899,11 +1899,52 @@ paths:
                         field: "inputs[0].framerate vs inputs[1].framerate"
                         message: "Inputs use different frame rates (29.97 vs 30); set re_encode_mode to auto or always."
         '429':
-          description: Rate limit exceeded
+          description: |
+            Rate limited. Two distinct triggers share this status — branch
+            on the `error` code, NOT on the status:
+
+            1. **Long-form concurrency cap** — the caller already holds the
+               maximum number of concurrent in-flight long-form (Fargate)
+               workflows their tier permits (Pro 2 / Max 5; Enterprise +
+               Free uncapped). Body is `LongFormConcurrencyLimitResponse`:
+               `error: LONG_FORM_CONCURRENCY_LIMIT_EXCEEDED`, `message_key:
+               job.long_form_concurrency_exceeded`, a `links.upgrade` CTA,
+               and **no `Retry-After`** — the limit clears when an in-flight
+               long-form workflow finishes, not on a timer.
+            2. **Infrastructure rate-limit** — too many requests in the
+               current window. The links-absent subset of the same shape: a
+               plain `ErrorEnvelope` with a `Retry-After` header.
+          headers:
+            Retry-After:
+              description: |
+                Seconds to wait before retrying. Delta-seconds (RFC 9110).
+                Present ONLY for the infrastructure rate-limit trigger —
+                ABSENT for `LONG_FORM_CONCURRENCY_LIMIT_EXCEEDED` (that
+                limit clears on workflow completion, not on a timer).
+              schema:
+                type: integer
+                minimum: 0
+              example: 60
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ErrorEnvelope'
+                $ref: '#/components/schemas/LongFormConcurrencyLimitResponse'
+              examples:
+                long_form_concurrency_exceeded:
+                  summary: Caller already holds the max concurrent long-form workflows for their tier
+                  value:
+                    success: false
+                    error: "LONG_FORM_CONCURRENCY_LIMIT_EXCEEDED"
+                    message: "You already have the maximum of 5 concurrent long-form workflows for your tier. Wait for one to finish or upgrade for a higher limit."
+                    message_key: "job.long_form_concurrency_exceeded"
+                    locale: "en-GB"
+                    links:
+                      upgrade: "https://giveitsmaller.com/pricing"
+                infrastructure_rate_limit:
+                  summary: Too many requests in the current window (generic throttle, carries Retry-After)
+                  value:
+                    success: false
+                    error: "Too many requests. Please try again later."
         '500':
           description: Internal server error
           content:
@@ -4875,6 +4916,14 @@ components:
               response does not reveal another user's upload exists).
               `message_key: "upload.not_found"`. See the createWorkflow
               404 response + ADR-0016 Amendment.
+            - `LONG_FORM_CONCURRENCY_LIMIT_EXCEEDED` (429) — caller already
+              holds the maximum concurrent in-flight long-form workflows
+              their tier permits (Pro 2 / Max 5; Enterprise uncapped).
+              DISTINCT from an infra rate-limit 429: carries no
+              `Retry-After` (it clears on workflow completion) and adds a
+              `links.upgrade` CTA. `message_key:
+              "job.long_form_concurrency_exceeded"`. See the createWorkflow
+              429 response + `LongFormConcurrencyLimitResponse`.
         message:
           type: string
           description: |
@@ -6190,6 +6239,54 @@ components:
                   format: uri
                   description: Top-up deep link.
 
+    LongFormConcurrencyLimitResponse:
+      type: object
+      description: |
+        `429` response body for `POST /api/workflows` when the caller
+        already holds the maximum number of concurrent in-flight
+        long-form (Fargate) workflows their tier permits
+        (`UserTier.maxConcurrentLongFormJobs`: Pro 2 / Max 5; Enterprise
+        + Free uncapped — Free has no long-form access at all). Carried
+        on a `429` but DISTINCT from an infrastructure rate-limit `429`:
+
+        - `error` is the stable code `LONG_FORM_CONCURRENCY_LIMIT_EXCEEDED`
+          (`message_key: job.long_form_concurrency_exceeded`).
+        - **No `Retry-After`.** The limit clears when an in-flight
+          long-form workflow finishes, not on a timer — the client waits
+          on workflow completion (or upgrades), it does not back off for
+          N seconds.
+        - Carries `links.upgrade` (the pricing / upgrade deep link) so the
+          frontend can render a "raise your concurrent long-form limit"
+          CTA rather than "try again later".
+
+        A generic infrastructure rate-limit `429` on this endpoint is the
+        links-absent subset of this shape: a plain `ErrorEnvelope` with a
+        `Retry-After` header and no `links`. `error` is left as a
+        documented string (not a strict enum) so the rate-limit subset
+        validates against the same schema and consumers tolerate unknown
+        codes; SDKs branch on the `LONG_FORM_CONCURRENCY_LIMIT_EXCEEDED`
+        value to distinguish the two.
+
+        Mirrors the runtime shape produced by `compression_api`'s
+        `WorkflowController` +
+        `CreateWorkflowResult::longFormConcurrencyExceeded`
+        (PR #484, API ticket CSPBSIVm).
+      allOf:
+        - $ref: '#/components/schemas/ErrorEnvelope'
+        - type: object
+          properties:
+            links:
+              type: object
+              description: |
+                Caller-actionable URLs. Carries `upgrade` for the
+                long-form concurrency `429`; absent on the infrastructure
+                rate-limit subset.
+              properties:
+                upgrade:
+                  type: string
+                  format: uri
+                  description: Upgrade-plan / pricing deep link.
+
     # ============================================
     # WORKFLOW LIFECYCLE — CANCEL / RESUME (per ticket I24)
     # ============================================
@@ -6543,14 +6640,32 @@ components:
         Subscription tier. Mirrors the API-side
         `App\Identity\Domain\Enums\UserTier` PHP enum.
 
+        Ordering is `free` < `pro` < `max` < `enterprise` (the
+        upgrade-resolver / `isHigherThan` ordinal in `UserTier.php`).
+        `max` is the top **self-serve** tier — Pro plus audio + larger
+        long-form bands; Enterprise remains the negotiated tier above it.
+
         Tier capability summary (informational; canonical limits are
         enforced server-side per `UserTier.php`):
         - `free`: 10 MiB max upload; image MIMEs only; 50 monthly credits;
-          0 overdraft; 1× rate-limit baseline.
+          0 overdraft; 1× rate-limit baseline. No long-form access
+          (video/audio are MIME-gated away from Free).
         - `pro`: 5 GiB max upload; image + video + document MIMEs; 1000
-          monthly credits; 200 overdraft; 5× rate-limit.
+          monthly credits; 200 overdraft; 5× rate-limit; up to 2 concurrent
+          in-flight long-form jobs.
+        - `max`: 50 GiB max upload; image + video + document + audio MIMEs;
+          7500 monthly credits; 2500 overdraft; 15× rate-limit; up to 5
+          concurrent in-flight long-form jobs.
         - `enterprise`: 100 GiB max upload; image + video + document + audio
-          MIMEs; 10000 monthly credits; 5000 overdraft; 20× rate-limit.
+          MIMEs; 10000 monthly credits; 5000 overdraft; 20× rate-limit;
+          uncapped concurrent long-form jobs.
+
+        **Concurrent long-form jobs** is a hard per-tier ceiling on the
+        number of in-flight long-form (Fargate) workflows a caller may
+        hold at once — exceeding it returns a typed `429`
+        `LONG_FORM_CONCURRENCY_LIMIT_EXCEEDED` (see the `POST /api/workflows`
+        429 response). Pro's 2-job cap is enforced as of the Max-tier
+        launch.
 
         The "max upload" figures are the per-file upload cap
         (`UserTier.maxFileSizeBytes`) — the request-level tier quota,
@@ -6565,6 +6680,7 @@ components:
       enum:
         - free
         - pro
+        - max
         - enterprise
 
     TierRestrictionKind:
@@ -9730,6 +9846,14 @@ components:
           oneOf:
             - $ref: '#/components/schemas/WorkflowCreditSummary'
             - type: 'null'
+        codegen_source:
+          $ref: '#/components/schemas/CodegenSource'
+          description: |
+            OPTIONAL, drill-in-only "code for this run" / replay projection — the
+            allowlisted, re-submittable shape of the original request (for an SDK
+            snippet / "run it again"). Absent until the API populates it. NOT a
+            dump of the persisted option bag; see `CodegenSource`. Per ticket
+            `LO0R5gzk`.
 
     WorkflowStatusSuccessEnvelope:
       type: object
@@ -9925,6 +10049,165 @@ components:
             the `active` vs non-`active` split is the only distinction a cost
             readout needs (don't show a final figure while `active`).
 
+    CodegenSource:
+      type: object
+      description: |
+        Drill-in-only "code for this run" / replay projection — a DEDICATED,
+        ALLOWLISTED mirror of the SAFE, user-authored parts of the original
+        workflow-create request, so a consumer can regenerate it (an SDK
+        snippet, a "run it again" action).
+
+        **NOT an echo of the persisted option bag.** The create path
+        canonicalizes/defaults options and stores internal fan-out +
+        orchestration detail — synthetic `passthrough` source jobs,
+        derived-artifact nodes, per-output expansion, server-defaulted/
+        canonicalized internal option keys — none of which is a stable public
+        contract. This type carries ONLY the re-submittable request shape and
+        EXCLUDES all of that plus runtime results.
+
+        **Detail-only** — `WorkflowStatusResponse` only, NEVER `WorkflowSummary`
+        (payload + the list view doesn't need it). OPTIONAL: the projector ships
+        incrementally; the field is absent until the API populates it.
+
+        **Scope: the reproducible JOB graph only.** Workflow-level request
+        fields (`delivery` / `export` / `processing`) are deliberately NOT part
+        of this projection — a replay re-applies the caller's own delivery /
+        export choices. Per ticket `LO0R5gzk`.
+      required:
+        - jobs
+      properties:
+        jobs:
+          type: array
+          description: |
+            The reproducible, user-authored jobs in request order. Internal /
+            synthetic jobs (e.g. server-injected `passthrough` source jobs) are
+            excluded.
+          items:
+            $ref: '#/components/schemas/CodegenSourceJob'
+
+    CodegenSourceJob:
+      type: object
+      description: |
+        One job's re-submittable shape — the allowlisted mirror of
+        `JobDefinition`. `source` (single-input) and `inputs` (role-based
+        multi-input) are mutually exclusive, as in the create request.
+      required:
+        - operations
+      properties:
+        ref:
+          type: string
+          description: |
+            The job's workflow-local ref (the authored `JobDefinition.id`, or the
+            server `job_N` when unauthored) — preserved so chain `from`
+            references between jobs round-trip on replay.
+        deliver:
+          type: boolean
+          description: |
+            Mirrors `JobDefinition.deliver` — whether this (possibly
+            intermediate) job's output was promoted for delivery. Preserved so a
+            replay delivers the same set of outputs. Omitted ⇒ default `false`.
+        source:
+          description: |
+            Single-input source (single-input ops). Mutually exclusive with
+            `inputs`. A `job_output` / `external_import` / `connection` source
+            round-trips verbatim — the same three `MultiInputSource` leaves,
+            inlined here as a FLAT union of concrete records rather than
+            nesting the `MultiInputSource` `oneOf` as a member
+            (`oneOf`-in-`oneOf` is not code-generatable by openapi-generator —
+            ticket `H6wwypmO`); a user UPLOAD is represented by a
+            `CodegenUploadPlaceholder` (no bytes/keys — the original upload is
+            consumed/expired). Distinguished structurally: the three source
+            leaves carry `type` (`job_output` / `external_import` /
+            `connection`), the placeholder carries `kind: upload_placeholder`.
+          oneOf:
+            - $ref: '#/components/schemas/JobOutputSource'
+            - $ref: '#/components/schemas/ExternalImportToken'
+            - $ref: '#/components/schemas/ConnectionSource'
+            - $ref: '#/components/schemas/CodegenUploadPlaceholder'
+        inputs:
+          type: array
+          description: |
+            Role-based multi-input list. Mutually exclusive with `source`. (A
+            multi-input job never references a raw upload directly — an upload
+            enters via a `passthrough` source job referenced here as
+            `job_output`.)
+          items:
+            $ref: '#/components/schemas/CodegenSourceInput'
+        operations:
+          type: array
+          items:
+            $ref: '#/components/schemas/CodegenSourceOperation'
+
+    CodegenSourceInput:
+      type: object
+      description: |
+        One multi-input entry — the allowlisted mirror of `JobInputV2`: a
+        reproducible `MultiInputSource` (`job_output` / `external_import` /
+        `connection` — the canonical request leaves, which round-trip
+        `from`+`operation` / external handle / `connection_id`+`path` verbatim)
+        plus the input `role` and authored `per_input_options`.
+      required:
+        - source
+      properties:
+        source:
+          $ref: '#/components/schemas/MultiInputSource'
+        role:
+          type: string
+          enum: [base, overlay, transition_mask]
+          description: |
+            Input role for role-based multi-input ops (omitted where the op has a
+            single implicit role). Mirrors the `JobInputRole` request vocabulary;
+            keep in sync if that enum widens.
+        per_input_options:
+          type: object
+          description: |
+            Per-input options for this input, as authored — public keys only
+            (internal/defaulted keys excluded).
+          additionalProperties: true
+
+    CodegenUploadPlaceholder:
+      type: object
+      description: |
+        Stand-in for a user UPLOAD source in a replay projection — descriptive
+        metadata so a consumer can re-prompt for an equivalent file. NOT the
+        bytes or storage key (the original upload is consumed/expired), so it is
+        deliberately NOT a re-submittable `UploadSource`.
+      required:
+        - kind
+      properties:
+        kind:
+          type: string
+          enum: [upload_placeholder]
+          description: Discriminates this stand-in from a re-submittable `MultiInputSource`.
+        filename:
+          type: string
+          maxLength: 1024
+        mime_type:
+          type: string
+          maxLength: 100
+        size_bytes:
+          type: integer
+          format: int64
+          minimum: 0
+
+    CodegenSourceOperation:
+      type: object
+      description: |
+        One operation in re-submittable form: the public operation `type` + the
+        user-authored public `options` (allowlisted — server-defaulted /
+        canonicalized internal keys are excluded; what's present is what the
+        caller would re-send). Option keys are operation-specific — see the
+        per-operation schemas for the typed shapes.
+      required:
+        - type
+      properties:
+        type:
+          $ref: '#/components/schemas/OperationType'
+        options:
+          type: object
+          description: Public, user-authored options for this operation (as submitted).
+          additionalProperties: true
+
     WorkflowListResponse:
       type: object
       description: |

package/operation-capabilities/operation-capabilities.json

@@ -515,5 +515,5 @@
       "isAnimated": "maybe"
     }
   },
-  "schema_version": "2.130.0"
+  "schema_version": "2.133.0"
 }

package/operations/schemas/audio_overlay.yaml

@@ -102,6 +102,9 @@ operation:
             max_input_size_bytes: 5000000000       # 5 GB (Pro)
             max_output_size_bytes: 5000000000
           per_tier_constraints:
+            max:
+              max_input_size_bytes: 50000000000    # 50 GB (Max self-serve band)
+              max_output_size_bytes: 50000000000
             enterprise:
               max_input_size_bytes: 120000000000   # 120 GB (Enterprise enforced ceiling)
               max_output_size_bytes: 120000000000
@@ -287,6 +290,9 @@ operation:
             max_input_size_bytes: 5000000000       # 5 GB (Pro)
             max_output_size_bytes: 5000000000
           per_tier_constraints:
+            max:
+              max_input_size_bytes: 50000000000    # 50 GB (Max self-serve band)
+              max_output_size_bytes: 50000000000
             enterprise:
               max_input_size_bytes: 120000000000   # 120 GB (Enterprise enforced ceiling)
               max_output_size_bytes: 120000000000

package/operations/schemas/audio_watermark.yaml

@@ -3,6 +3,14 @@ schema_version: "2.0.0"
 operation:
   type: audio_watermark
   availability: planned
+  # required_tier stays `enterprise` after the Max tier (TaAvvGm4): Max gains
+  # the audio MIME *entitlement* (it can compress / convert / overlay / split
+  # audio), but forensic audio watermarking (Cinavia / Resemble PerTh) is a
+  # premium Enterprise differentiator, NOT basic audio processing — Max is
+  # "Pro + audio + larger long-form bands, NOT Enterprise". MIME entitlement
+  # (the UserTier capability summary) and a per-operation `required_tier` gate
+  # are orthogonal axes, so a Max caller having audio is not contradicted by
+  # this op being Enterprise-only. (Reassessed per TaAvvGm4 scope item 3.)
   required_tier: enterprise
   description: |
     Embed a steganographic forensic watermark into an audio asset (or
@@ -43,9 +51,12 @@ operation:
       processing_class:
         # F8 long-form tier (per ticket I15-CONS). audio_watermark is
         # `availability: planned` + `required_tier: enterprise` at the
-        # operation level; per-class entries inherit the enterprise
-        # tier (long_form widens further to enterprise as the natural
-        # superset of pro).
+        # operation level (see the op-level note re: the Max tier — this
+        # premium forensic feature is Enterprise-only despite Max having
+        # the audio MIME entitlement); per-class entries inherit the
+        # enterprise tier, so the baseline IS the Enterprise cap and no
+        # per_tier_constraints (max/...) is declared — there is no tier
+        # above the baseline (ADR-0011 D2).
         short_form:
           availability: planned
           required_tier: enterprise

package/operations/schemas/compress.yaml

@@ -928,6 +928,9 @@ operation:
             max_input_size_bytes: 5000000000       # 5 GB (Pro)
             max_output_size_bytes: 5000000000
           per_tier_constraints:
+            max:
+              max_input_size_bytes: 50000000000    # 50 GB (Max self-serve band)
+              max_output_size_bytes: 50000000000
             enterprise:
               max_input_size_bytes: 120000000000   # 120 GB (Enterprise enforced ceiling)
               max_output_size_bytes: 120000000000

package/operations/schemas/convert.yaml

@@ -317,6 +317,9 @@ operation:
             max_input_size_bytes: 5000000000       # 5 GB (Pro)
             max_output_size_bytes: 5000000000
           per_tier_constraints:
+            max:
+              max_input_size_bytes: 50000000000    # 50 GB (Max self-serve band)
+              max_output_size_bytes: 50000000000
             enterprise:
               max_input_size_bytes: 120000000000   # 120 GB (Enterprise enforced ceiling)
               max_output_size_bytes: 120000000000

package/operations/schemas/custom_luma.yaml

@@ -74,6 +74,9 @@ operation:
             max_input_size_bytes: 5000000000       # 5 GB (Pro)
             max_output_size_bytes: 5000000000
           per_tier_constraints:
+            max:
+              max_input_size_bytes: 50000000000    # 50 GB (Max self-serve band)
+              max_output_size_bytes: 50000000000
             enterprise:
               max_input_size_bytes: 120000000000   # 120 GB (Enterprise enforced ceiling)
               max_output_size_bytes: 120000000000

package/operations/schemas/merge.yaml

@@ -174,6 +174,8 @@ operation:
             max_total_duration: "PT24H"              # 24h (was PT12H) — binding Enterprise ceiling
             max_total_input_size_bytes: 5000000000   # 5 GB combined (Pro)
           per_tier_constraints:
+            max:
+              max_total_input_size_bytes: 50000000000   # 50 GB combined (Max self-serve band)
             enterprise:
               max_total_input_size_bytes: 120000000000  # 120 GB combined (Enterprise)
       options:

package/operations/schemas/split.yaml

@@ -307,6 +307,9 @@ operation:
             max_input_size_bytes: 5000000000       # 5 GB (Pro)
             max_output_size_bytes: 5000000000
           per_tier_constraints:
+            max:
+              max_input_size_bytes: 50000000000    # 50 GB (Max self-serve band)
+              max_output_size_bytes: 50000000000
             enterprise:
               max_input_size_bytes: 120000000000   # 120 GB
               max_output_size_bytes: 120000000000

package/operations/schemas/thumbnail.yaml

@@ -157,6 +157,8 @@ operation:
             max_input_duration: "PT12H"
             max_input_size_bytes: 5000000000       # 5 GB (Pro)
           per_tier_constraints:
+            max:
+              max_input_size_bytes: 50000000000    # 50 GB (Max self-serve band)
             enterprise:
               max_input_size_bytes: 120000000000   # 120 GB (Enterprise enforced ceiling)
       # Same 16MP output-area wall as image (width*height <= max_output_pixels).

package/operations/schemas/video_text_watermark.yaml

@@ -48,6 +48,9 @@ operation:
             max_input_size_bytes: 5000000000       # 5 GB (Pro)
             max_output_size_bytes: 5000000000
           per_tier_constraints:
+            max:
+              max_input_size_bytes: 50000000000    # 50 GB (Max self-serve band)
+              max_output_size_bytes: 50000000000
             enterprise:
               max_input_size_bytes: 120000000000   # 120 GB (Enterprise enforced ceiling)
               max_output_size_bytes: 120000000000

package/operations/schemas/video_watermark.yaml

@@ -75,6 +75,9 @@ operation:
             max_input_size_bytes: 5000000000       # 5 GB (Pro)
             max_output_size_bytes: 5000000000
           per_tier_constraints:
+            max:
+              max_input_size_bytes: 50000000000    # 50 GB (Max self-serve band)
+              max_output_size_bytes: 50000000000
             enterprise:
               max_input_size_bytes: 120000000000   # 120 GB (Enterprise enforced ceiling)
               max_output_size_bytes: 120000000000

package/package.json

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