@giveitsmaller/contracts 0.9.0 → 0.16.0

package/operations/schemas/passthrough.yaml

@@ -0,0 +1,49 @@
+schema_version: "1.0.0"
+
+operation:
+  type: passthrough
+  availability: beta
+  description: |
+    Inert lossless source operation. A single-input source job whose
+    SOLE operation is `passthrough` emits its source bytes UNCHANGED —
+    no compression, no transformation, no Lambda dispatch. The API
+    self-completes the job at workflow-create/publish time: the job's
+    terminal output IS the upload's `{bucket, key}` unchanged.
+
+    **Purpose.** Lets an uploaded file enter a multi-input operation
+    (`merge` / `archive` / `image_watermark` / etc.) LOSSLESSLY. Since
+    V2 narrows `JobInputV2.source` to exclude upload-direct (`MultiInputSource`
+    — job_output / external_import / connection only), an upload that
+    must feed a multi-input op enters via a `passthrough` source job
+    referenced downstream by `{ type: job_output, from: <id> }`. This
+    preserves billing / DAG / lineage that direct upload-in-inputs[]
+    would bypass.
+
+    **Distinct from `operations: []`.** An empty `operations[]` on a
+    single-input upload job KEEPS its implicit-compress meaning (see
+    `POST /api/workflows` description). `passthrough` is the EXPLICIT
+    lossless opt-out chosen via the existing rule "non-empty
+    `operations[]` without `compress` = compression opt-out" — it is a
+    sole, named operation, not an empty chain.
+
+    **Never published to SNS.** Because the API self-completes the job
+    at publish, `passthrough` is INTENTIONALLY absent from the AsyncAPI
+    routing enums (`OperationType`, `OperationRequestAttributes.operation_type`)
+    and has no `ops-passthrough` queue. It never appears on the wire as
+    a request message.
+
+    Media-agnostic (no `mime_groups`): it accepts any uploaded MIME and
+    copies it verbatim, so there are no per-MIME options or constraints.
+    `availability: beta` — the API self-completion path is LIVE (the
+    inputs[]-narrowing + passthrough self-complete mechanism is deployed),
+    so workflow-create accepts `passthrough` source jobs and MUST NOT
+    return `feature_not_available`. Activated per ticket
+    [`4som89Uh`](https://trello.com/c/4som89Uh) + ADR-0004 (planned→beta
+    flip; self-complete code deployed API-side).
+  default: false
+  input_model: single
+
+  # DELIBERATELY absent from the operation chain matrix
+  # (docs/matrices/operation-chains.md). passthrough is a sole-op source
+  # node, not a chainable transform — with no `mime_groups` it produces
+  # zero matrix rows, which is correct: nothing chains onto or after it.

package/operations/schemas/render_variants.yaml

@@ -0,0 +1,117 @@
+schema_version: "2.0.0"
+
+operation:
+  type: render_variants
+  # Generate N resized/re-encoded image variants from ONE decoded source in a
+  # single operation (image fan-out). Per spike GA2kiRY8 / epic nksLtV28,
+  # ticket w3EwzHYd. Worker = the shared convert image-encode stack + FitMode
+  # (lambdas-confirmed reuse: image_convert.rs encode + domain/thumbnailer.rs).
+  #
+  # availability: planned — the worker (lambdas 08q0ySAc) + its SNS subscription
+  # (terraform MNuDYJaY) are downstream of this contract, so the server returns
+  # `feature_not_available` (422) until they are live. The planned -> beta flip
+  # is a SEPARATE lockstep cut once the worker + wire are up (the two-gate rule;
+  # never flip beta ahead of the publisher). Source MIMEs are jpeg/png/webp only
+  # — AVIF is encode-only in the worker stack (decode unsupported), so it is a
+  # valid `output_format` target but NOT a source input.
+  description: "Generate multiple resized / re-encoded image variants from a single source image in one operation (image fan-out)."
+  availability: planned
+  input_model: single
+
+  mime_groups:
+    image:
+      availability: planned
+      mimes:
+        - image/jpeg
+        - image/png
+        - image/webp
+      options:
+        targets:
+          type: array
+          required: true
+          minItems: 1
+          maxItems: 20
+          # Each target is encoded independently from the single decoded
+          # source. Width/height are individually optional at the type level;
+          # the cross-field rule (fit crop/scale => BOTH required; fit max =>
+          # at least one) is worker-enforced and rejected as `invalid_options`,
+          # not expressed structurally here (the option DSL has no per-item
+          # conditional-required primitive). Documented in prose below.
+          description: |
+            One output variant per entry (max 20). Each variant is resized /
+            re-encoded independently from the single decoded source; the
+            operation succeeds or fails **atomically** — there are no partial
+            outputs. Each result output echoes its target's `id` back as
+            `target_id` so callers can map outputs to the variants they asked
+            for.
+
+            Dimensions: `fit: max` needs at least one of `width` / `height`
+            (aspect preserved, output may be smaller than the box). `fit: crop`
+            and `fit: scale` require BOTH `width` and `height` (they produce an
+            exact-size output). A target whose dimensions exceed the source is
+            rejected (`invalid_options`) unless `allow_upscale: true`.
+          items:
+            type: object
+            required:
+              - id
+            properties:
+              id:
+                type: string
+                pattern: '^[A-Za-z0-9._-]+$'
+                maxLength: 64
+                # `id` must be unique within the array — this is the addressing
+                # key, so duplicates would map two outputs to one `target_id`.
+                # JSON Schema `uniqueItems` only catches wholesale-identical
+                # target objects, not same-`id`-different-dims; the worker
+                # rejects duplicate ids as `invalid_options` (worker-enforced,
+                # like the dimension rules).
+                description: |
+                  Caller-assigned identifier, unique within the array
+                  (duplicate ids are rejected as `invalid_options`). Echoed
+                  verbatim as `target_id` on the matching result output — the
+                  addressing contract.
+              width:
+                type: integer
+                minimum: 1
+                maximum: 16384
+                description: "Target width in pixels. Required together with height for fit crop/scale; for fit max, at least one of width/height is required."
+              height:
+                type: integer
+                minimum: 1
+                maximum: 16384
+                description: "Target height in pixels. Required together with width for fit crop/scale; for fit max, at least one of width/height is required."
+              fit:
+                type: string
+                enum:
+                  - max
+                  - crop
+                  - scale
+                default: max
+                description: |
+                  Resize mode. max = fit within the box, aspect preserved
+                  (output may be smaller); needs at least one dimension.
+                  crop = fill and trim to exact width x height. scale = force
+                  exact width x height. crop and scale require both dimensions.
+              quality:
+                type: integer
+                minimum: 1
+                maximum: 100
+                default: 85
+                description: "Encode quality (lossy formats only — jpeg / webp / avif). Accepted but ignored for png (lossless)."
+              output_format:
+                type: string
+                enum:
+                  - jpeg
+                  - png
+                  - webp
+                  - avif
+                description: "Output format for this variant. When omitted, the source format is preserved."
+              background:
+                type: string
+                pattern: '^#[0-9A-Fa-f]{6}$'
+                default: "#FFFFFF"
+                description: "Background colour (hex #RRGGBB), applied only when flattening a transparent source into an opaque format (e.g. a PNG with alpha rendered to JPEG). Ignored otherwise."
+              allow_upscale:
+                type: boolean
+                default: false
+                description: "When false (default), a target whose dimensions exceed the source is rejected (`invalid_options`). Set true to permit upscaling. fit max never upscales."

package/operations/schemas/split.yaml

@@ -9,14 +9,19 @@ operation:
     into N outputs per the per-mime-group catalog. Mirrors the
     `merge` / `convert` catalog-split-by-mime-group pattern.
 
-    **Three modes** (audio + video; the mode discriminator gates which
-    of the three options applies per the `depends_on` rules in this
+    **Three shared modes** (audio + video; the mode discriminator
+    gates which option applies per the `depends_on` rules in this
     schema):
     - `interval`: split every N numeric-seconds.
     - `count`: split into N equal-duration pieces (integer 2..=200).
     - `cut_points`: explicit cut points in numeric-seconds (strictly
       increasing, no duplicates, each > 0 and < probed duration).
 
+    **Plus an audio-only `silence` mode** (`beta`, gated by the
+    `silence_mode_audio` feature): cut at detected silence gaps via
+    the worker's ffmpeg `silencedetect` filter. Video stays
+    three-mode.
+
     **GIF + PDF use range-based selection** instead of three modes:
     - GIF (`image_gif`): `frame_range` REQUIRED + `output_format`
       enum {png,webp,jpg}.
@@ -34,6 +39,8 @@ operation:
     - `interval`: `ceil(probed_duration / interval) <= 200`
     - `count`: enforced by the option's `min: 2 max: 200` range
     - `cut_points`: `cut_points.len() + 1 <= 200`
+    - `silence` (audio): resolved segment count (detected gaps + 1)
+      `<= 200`; preflight rejects as `invalid_options` (422)
     - PDF: resolved page count after expansion `<= 200`
       (cross-ref [`WgCqnMRa`](https://trello.com/c/WgCqnMRa))
     - GIF: resolved frame count after expansion `<= 200`
@@ -59,12 +66,15 @@ operation:
     via `processing_class`). No schema-side discriminator beyond MIME
     detection + `processing_class`.
 
-    `availability: beta` for the `audio` mime_group (worker live on
-    staging per lambdas #161 — shape-stable + opt-in, MUST NOT 422).
-    The `image_gif`, `document_pdf`, and `video` mime_groups stay
-    `availability: planned` until their cross-repo Lambda workers ship
-    ([`vKI0CFDu`](https://trello.com/c/vKI0CFDu) + lambdas L1); dispatch
-    returns `feature_not_available` (422) for those groups until then.
+    `availability: beta` for the `audio` and `video` mime_groups
+    (workers live on staging — shape-stable + opt-in, MUST NOT 422).
+    Video activates **short-form only**: `video.processing_class.short_form`
+    is `beta`; `long_form` (the `split-video-fargate` worker) stays
+    `availability: planned` until that worker ships. The `image_gif` and
+    `document_pdf` mime_groups also stay `availability: planned` until their
+    cross-repo Lambda workers ship ([`vKI0CFDu`](https://trello.com/c/vKI0CFDu)
+    + lambdas L1); dispatch returns `feature_not_available` (422) for the
+    still-planned groups/classes until then.
 
     Per ADR-0014.
   default: false
@@ -72,13 +82,14 @@ operation:
 
   features:
     silence_mode_audio:
-      availability: planned
+      availability: beta
       description: |
         Silence-detect cut mode for audio (`mode: silence` —
-        Cinavia/Resemble territory, server-side silence detection).
-        OUT of V1 (Lambda support not yet shipped); declared as a
-        future-work feature here so SDK consumers see the gate.
-        Picked up as a separate post-launch ticket.
+        server-side silence detection in the audio split worker).
+        `beta`: shape-stable + opt-in. The worker is built; the mode
+        ships dark until the API regenerates enum validation to accept
+        `mode: silence`. The `silence` enum value carries a matching
+        `per_value_availability: beta` on `audio.mode`.
 
   mime_groups:
     # Animated GIF base — parallel mime_group naming follows the
@@ -161,13 +172,17 @@ operation:
       options:
         mode:
           type: enum
-          values: [interval, count, cut_points]
+          values: [interval, count, cut_points, silence]
           default: interval
+          per_value_availability:
+            silence: { availability: beta }
           description: |
             Split strategy:
             - `interval`: cut every `interval` seconds.
             - `count`: cut into `count` equal-duration pieces.
             - `cut_points`: cut at explicit timestamps.
+            - `silence`: cut at detected silence gaps (audio-only,
+              `beta` via the `silence_mode_audio` feature gate).
 
         interval:
           type: float
@@ -212,30 +227,69 @@ operation:
             200-output cap declaratively. Only valid when
             `mode: cut_points`.
 
+        silence_threshold_db:
+          type: float
+          max: 0.0
+          default: -50.0
+          depends_on: { mode: silence }
+          # Maps to the worker's silence-detection noise floor.
+          description: |
+            Noise floor below which audio counts as silence, in dBFS
+            (negative; 0.0 = full scale). Strictly negative in
+            practice; `max: 0.0` is the declarative ceiling (a 0 dB
+            "silence" floor is degenerate, like the strict bounds
+            documented in prose for `cut_points`). Only valid when
+            `mode: silence`.
+
+        silence_min_duration:
+          type: float
+          min: 0.001
+          default: 0.75
+          depends_on: { mode: silence }
+          # Maps to the worker's silence-detection minimum-duration parameter.
+          description: |
+            Minimum duration of a silence gap, in numeric seconds
+            (sub-second allowed), before it is treated as a cut point.
+            `min: 0.001` is the strict-positive sub-second idiom
+            (cf. `interval`). Only valid when `mode: silence`.
+
+        silence_handling:
+          type: enum
+          values: [keep_at_end]
+          default: keep_at_end
+          depends_on: { mode: silence }
+          description: |
+            How detected silence is handled at segment boundaries.
+            `keep_at_end`: trailing silence stays appended to the
+            preceding segment (no separate silence-only outputs).
+            Only valid when `mode: silence`.
+
         precision:
           type: enum
           values: [fast, exact]
           default: fast
+          # Don't use "keyframe" language here — that's video-only;
+          # audio drift is packet-boundary.
           description: |
             Cut precision. Under `fast`, audio cuts are
             packet-boundary approximate (drift bounded by codec
             packet size — typically <= 23ms for AAC, <= 26ms for
             MP3). Under `exact`, the Lambda re-encodes to align cuts
             precisely at the requested timestamps (slower, larger
-            output, but sample-accurate). Avoid "keyframe" language
-            — that's video-only; audio drift is packet-boundary.
+            output, but sample-accurate).
 
     # Video base — same three modes + precision + processing_class.
     # Long-form routes to `split-video-fargate` (same OperationType,
     # different worker per `processing_class`).
     video:
-      availability: planned
+      availability: beta
       mimes:
         - video/mp4
         - video/webm
+        - video/quicktime
       processing_class:
         short_form:
-          availability: planned
+          availability: beta
           constraints:
             max_input_duration: "PT5M"
             max_input_size_bytes: 524288000

package/operations/schemas/text_watermark.yaml

@@ -25,10 +25,10 @@ operation:
         text:
           type: string
           required: true
+          # Rendered with the bundled Liberation Sans (SIL OFL); a single
+          # text overlay is capped at 4 megapixels before rendering fails.
           description: |
-            Watermark text. Must be non-empty. Rendered with bundled
-            Liberation Sans (SIL OFL). A single text overlay is capped
-            at 4 megapixels before rendering fails.
+            Watermark text. Must be non-empty.
 
         font_size:
           type: float
@@ -59,11 +59,11 @@ operation:
           min: -360.0
           max: 360.0
           default: -45.0
+          # Tiled canvas is capped at 25 megapixels pre-rotation with a
+          # 5000 px maximum side length.
           description: |
             Rotation angle in degrees. Default -45° suits tiled mode
-            (angled diagonal pattern). Clamped to range. Tiled canvas is
-            capped at 25 megapixels pre-rotation with 5000 px maximum
-            side length.
+            (angled diagonal pattern). Clamped to range.
 
         watermark_mode:
           type: enum

package/operations/schemas/thumbnail.yaml

@@ -45,7 +45,7 @@ operation:
       mimes:
         - video/mp4
         - video/webm
-        - video/ogg
+        - video/quicktime
       processing_class:
         # F8 long-form video tier (per ticket I15-CONS). Thumbnail
         # extracts a single frame, so size/duration caps reflect

package/operations/schemas/video_text_watermark.yaml

@@ -58,9 +58,9 @@ operation:
         text:
           type: string
           required: true
+          # Rendered with the bundled Liberation Sans (SIL OFL).
           description: |
-            Watermark text. Must be non-empty. Rendered with bundled
-            Liberation Sans (SIL OFL).
+            Watermark text. Must be non-empty.
 
         font_size:
           type: float

package/operations/schemas/video_watermark.yaml

@@ -4,12 +4,15 @@ operation:
   type: video_watermark
   availability: beta
   description: |
-    Apply an image overlay (file or external source) onto a base video
+    Apply an image overlay onto a base video
     asset using FFmpeg's `overlay` filter. Multi-input role-based:
     exactly one input with `role: base` (the source video) + exactly
-    one with `role: overlay` (the watermark image). The overlay can be
-    an upload, an external_import handle, or a vault connection per
-    `WorkflowSource`.
+    one with `role: overlay` (the watermark image). Each input is a
+    `MultiInputSource` — an external_import handle, a vault connection,
+    or an upstream `job_output` (uploads are NOT referenced directly
+    inside inputs[]). To use an uploaded base or overlay, feed it through
+    a `passthrough` source job and reference it via `{ type: job_output,
+    from: <id> }` (per ticket 4som89Uh).
 
     **Dedicated operation, not an extension of `image_watermark`.**
     `image_watermark` is pure-Rust/no-FFmpeg and handles

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@giveitsmaller/contracts",
-  "version": "0.9.0",
+  "version": "0.16.0",
   "description": "Generated contract types for GISL (Give It Smaller)",
   "license": "MIT",
   "type": "module",
@@ -35,6 +35,8 @@
     "./operations/schemas/custom_luma.yaml": "./operations/schemas/custom_luma.yaml",
     "./operations/schemas/image_watermark.yaml": "./operations/schemas/image_watermark.yaml",
     "./operations/schemas/merge.yaml": "./operations/schemas/merge.yaml",
+    "./operations/schemas/passthrough.yaml": "./operations/schemas/passthrough.yaml",
+    "./operations/schemas/render_variants.yaml": "./operations/schemas/render_variants.yaml",
     "./operations/schemas/split.yaml": "./operations/schemas/split.yaml",
     "./operations/schemas/text_watermark.yaml": "./operations/schemas/text_watermark.yaml",
     "./operations/schemas/thumbnail.yaml": "./operations/schemas/thumbnail.yaml",

package/dist/openapi/models/LogoutUser200Response.d.ts

@@ -1,50 +0,0 @@
-/**
- * GISL Compression API
- * REST API for the GISL (Give It Smaller) file compression and processing service.  **Architecture:** - Upload files to get a `file_id` - Create workflows referencing uploaded files with operations (compress, thumbnail, image_watermark, text_watermark, merge, archive, convert, custom_luma, audio_overlay, audio_watermark) - Poll status, stream SSE events, or receive webhook callbacks - Download results per operation output  **Response envelope:** All mutation and query endpoints return `{ success: true, data: {...} }` on success and `{ success: false, error: \"...\", details: [...] }` on failure. Exceptions: `GET /api/operations/schema` returns raw JSON (per-tier private caching with ETag/Last-Modified revalidation per ADR-0002 + I3), health probes return flat objects, and `POST /api/contact` returns 204 with no body.  **Availability metadata.** This spec uses the `x-availability` vendor extension as **decorative documentation only**. Per [ADR-0001](../docs/decisions/0001-contract-first-availability.md) §1.5, the runtime endpoint `GET /api/operations/schema` (ticket I3) is the authoritative source; the sidecar `availability.json` (ticket I3b) is the authoritative companion (generated, never hand-edited; CI cross-checks runtime ⇄ sidecar). SDKs MUST NOT depend on `x-availability` reaching generated code — code-generators that surface vendor extensions may emit it as documentation, but consumers read availability from the runtime endpoint, not from the generated bindings.  The 5-value vocabulary (`stable | beta | experimental | planned | deprecated`) is defined in the `AvailabilityValue` schema. See `schemas/FORMAT.md` §Availability Taxonomy for the operational rules (parser obligation: absent = stable; per-enum-value granularity is the `per_value_availability` primitive landed via ticket I17).  **Localisation (per ticket [I26](https://trello.com/c/rcnqwgI4)).**  Error responses + paused/blocked workflow statuses carry a localised human-readable `message` alongside a stable, never-localised `message_key`. Machine-readable fields (`error`, enum values, status codes) stay canonical English.  - **Currently committed locales:** `en-GB` only (per ticket   [`4GKyuYo6`](https://trello.com/c/4GKyuYo6)). The I26 carrier   shape (`Accept-Language` + `Content-Language` + `Vary` headers +   `locale` envelope field + `message_key` + `message_params`) is   stable and exercised; the **catalog** of translated `message`   strings is en-GB-only at runtime today. Additional locales (e.g.   `pt-PT`) will be advertised by name when their catalogs ship —   the request/response carrier shape does NOT change when a new   locale lands. Treat unrequested locales as \"machine-code +   `message_key` path is committed; localised `message` prose is   not\" until this prose enumerates them by name. - **Request:** `Accept-Language` header per RFC 9110 §12.5.4 (q-value   negotiation supported). The server selects the best-match locale   from its supported list; falls back to `en-GB` when no match —   which, until additional catalogs land, is every non-`en-GB`   `Accept-Language`. - **Response:** `Content-Language: <locale>` echo on every localised   response; `Vary: Accept-Language` on every response (CDN/cache   correctness — different `Accept-Language` requests produce   different responses). `Vary` is emitted unconditionally so the   header contract does not flip when a second locale ships. - **Fallback locale:** `en-GB` (also the canonical locale for   `message_key` translations and English `message` prose). - **SDK guidance:** switch on `error` (machine code) for typed   error branches; surface `message_key` to client-side i18n   catalogs (SDK companion work tracked at X19, cross-repo);   display `message` for end-user UI; **never parse `message` for   control flow** — it changes per locale.  Carrier shape lives on `ErrorEnvelope` (envelope-level optional `message_key` + `message` + `locale` + `message_params`) and `ValidationErrorEnvelope` (also per-`details[]` entry). Existing 402 / 403 / 422 envelopes (`BalanceExhaustedResponse`, `FeatureNotAvailableResponse`, `FeatureTierRestrictedResponse`, `WorkflowPausedDetail`) inherit the convention.  **Upload thresholds (per tickets [u0ar7Yye](https://trello.com/c/u0ar7Yye) + [58nBQLWQ](https://trello.com/c/58nBQLWQ)).** Canonical upload constants (single-shot cap, multipart chunk size, multipart concurrency default, multipart first-chunk size) live on the `UploadThresholds` schema with `const:`-pinned values. SDK generators emit these as typed binding constants so frontend / API / SDKs reference one source 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.
- *
- * The version of the OpenAPI document: 2.31.0
- *
- *
- * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
- * https://openapi-generator.tech
- * Do not edit the class manually.
- */
-/**
- *
- * @export
- * @interface LogoutUser200Response
- */
-export interface LogoutUser200Response {
-    /**
-     *
-     * @type {LogoutUser200ResponseSuccessEnum}
-     * @memberof LogoutUser200Response
-     */
-    success: LogoutUser200ResponseSuccessEnum;
-    /**
-     * Empty object on logout success — preserves the
-     * `{ success: true, data: {...} }` envelope
-     * invariant from `info.description`. Logout has
-     * no return payload; the data slot is always
-     * `{}`.
-     *
-     * @type {object}
-     * @memberof LogoutUser200Response
-     */
-    data: object;
-}
-/**
- * @export
- */
-export declare const LogoutUser200ResponseSuccessEnum: {
-    readonly true: true;
-};
-export type LogoutUser200ResponseSuccessEnum = typeof LogoutUser200ResponseSuccessEnum[keyof typeof LogoutUser200ResponseSuccessEnum];
-/**
- * Check if a given object implements the LogoutUser200Response interface.
- */
-export declare function instanceOfLogoutUser200Response(value: object): value is LogoutUser200Response;
-export declare function LogoutUser200ResponseFromJSON(json: any): LogoutUser200Response;
-export declare function LogoutUser200ResponseFromJSONTyped(json: any, ignoreDiscriminator: boolean): LogoutUser200Response;
-export declare function LogoutUser200ResponseToJSON(json: any): LogoutUser200Response;
-export declare function LogoutUser200ResponseToJSONTyped(value?: LogoutUser200Response | null, ignoreDiscriminator?: boolean): any;

package/dist/openapi/models/LogoutUser200Response.js

@@ -1,53 +0,0 @@
-/* tslint:disable */
-/* eslint-disable */
-/**
- * GISL Compression API
- * REST API for the GISL (Give It Smaller) file compression and processing service.  **Architecture:** - Upload files to get a `file_id` - Create workflows referencing uploaded files with operations (compress, thumbnail, image_watermark, text_watermark, merge, archive, convert, custom_luma, audio_overlay, audio_watermark) - Poll status, stream SSE events, or receive webhook callbacks - Download results per operation output  **Response envelope:** All mutation and query endpoints return `{ success: true, data: {...} }` on success and `{ success: false, error: \"...\", details: [...] }` on failure. Exceptions: `GET /api/operations/schema` returns raw JSON (per-tier private caching with ETag/Last-Modified revalidation per ADR-0002 + I3), health probes return flat objects, and `POST /api/contact` returns 204 with no body.  **Availability metadata.** This spec uses the `x-availability` vendor extension as **decorative documentation only**. Per [ADR-0001](../docs/decisions/0001-contract-first-availability.md) §1.5, the runtime endpoint `GET /api/operations/schema` (ticket I3) is the authoritative source; the sidecar `availability.json` (ticket I3b) is the authoritative companion (generated, never hand-edited; CI cross-checks runtime ⇄ sidecar). SDKs MUST NOT depend on `x-availability` reaching generated code — code-generators that surface vendor extensions may emit it as documentation, but consumers read availability from the runtime endpoint, not from the generated bindings.  The 5-value vocabulary (`stable | beta | experimental | planned | deprecated`) is defined in the `AvailabilityValue` schema. See `schemas/FORMAT.md` §Availability Taxonomy for the operational rules (parser obligation: absent = stable; per-enum-value granularity is the `per_value_availability` primitive landed via ticket I17).  **Localisation (per ticket [I26](https://trello.com/c/rcnqwgI4)).**  Error responses + paused/blocked workflow statuses carry a localised human-readable `message` alongside a stable, never-localised `message_key`. Machine-readable fields (`error`, enum values, status codes) stay canonical English.  - **Currently committed locales:** `en-GB` only (per ticket   [`4GKyuYo6`](https://trello.com/c/4GKyuYo6)). The I26 carrier   shape (`Accept-Language` + `Content-Language` + `Vary` headers +   `locale` envelope field + `message_key` + `message_params`) is   stable and exercised; the **catalog** of translated `message`   strings is en-GB-only at runtime today. Additional locales (e.g.   `pt-PT`) will be advertised by name when their catalogs ship —   the request/response carrier shape does NOT change when a new   locale lands. Treat unrequested locales as \"machine-code +   `message_key` path is committed; localised `message` prose is   not\" until this prose enumerates them by name. - **Request:** `Accept-Language` header per RFC 9110 §12.5.4 (q-value   negotiation supported). The server selects the best-match locale   from its supported list; falls back to `en-GB` when no match —   which, until additional catalogs land, is every non-`en-GB`   `Accept-Language`. - **Response:** `Content-Language: <locale>` echo on every localised   response; `Vary: Accept-Language` on every response (CDN/cache   correctness — different `Accept-Language` requests produce   different responses). `Vary` is emitted unconditionally so the   header contract does not flip when a second locale ships. - **Fallback locale:** `en-GB` (also the canonical locale for   `message_key` translations and English `message` prose). - **SDK guidance:** switch on `error` (machine code) for typed   error branches; surface `message_key` to client-side i18n   catalogs (SDK companion work tracked at X19, cross-repo);   display `message` for end-user UI; **never parse `message` for   control flow** — it changes per locale.  Carrier shape lives on `ErrorEnvelope` (envelope-level optional `message_key` + `message` + `locale` + `message_params`) and `ValidationErrorEnvelope` (also per-`details[]` entry). Existing 402 / 403 / 422 envelopes (`BalanceExhaustedResponse`, `FeatureNotAvailableResponse`, `FeatureTierRestrictedResponse`, `WorkflowPausedDetail`) inherit the convention.  **Upload thresholds (per tickets [u0ar7Yye](https://trello.com/c/u0ar7Yye) + [58nBQLWQ](https://trello.com/c/58nBQLWQ)).** Canonical upload constants (single-shot cap, multipart chunk size, multipart concurrency default, multipart first-chunk size) live on the `UploadThresholds` schema with `const:`-pinned values. SDK generators emit these as typed binding constants so frontend / API / SDKs reference one source 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.
- *
- * The version of the OpenAPI document: 2.31.0
- *
- *
- * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
- * https://openapi-generator.tech
- * Do not edit the class manually.
- */
-/**
- * @export
- */
-export const LogoutUser200ResponseSuccessEnum = {
-    true: true
-};
-/**
- * Check if a given object implements the LogoutUser200Response interface.
- */
-export function instanceOfLogoutUser200Response(value) {
-    if (!('success' in value) || value['success'] === undefined)
-        return false;
-    if (!('data' in value) || value['data'] === undefined)
-        return false;
-    return true;
-}
-export function LogoutUser200ResponseFromJSON(json) {
-    return LogoutUser200ResponseFromJSONTyped(json, false);
-}
-export function LogoutUser200ResponseFromJSONTyped(json, ignoreDiscriminator) {
-    if (json == null) {
-        return json;
-    }
-    return {
-        'success': json['success'],
-        'data': json['data'],
-    };
-}
-export function LogoutUser200ResponseToJSON(json) {
-    return LogoutUser200ResponseToJSONTyped(json, false);
-}
-export function LogoutUser200ResponseToJSONTyped(value, ignoreDiscriminator = false) {
-    if (value == null) {
-        return value;
-    }
-    return {
-        'success': value['success'],
-        'data': value['data'],
-    };
-}