@giveitsmaller/contracts 0.85.0 → 0.86.0

package/dist/openapi/models/WorkflowWarningSeverity.js

@@ -4,7 +4,7 @@
  * 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 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).  **Free-text string fields: `x-string-vocabulary` (ticket [`Q79yjcFF`](https://trello.com/c/Q79yjcFF)).** A `type: string` field with no `enum` that names example values says, as data, what a client may do with them (the same marker is used in the AsyncAPI document): - `open` — a vocabulary that grows. Each published value keeps its   meaning, the SET is not closed: switch on the values you know and   handle an unknown one as the generic case (e.g. `ErrorEnvelope.error`). - `advisory` — explanatory text. Display or log it; **never switch on   it** (e.g. `SseWorkflowTerminalData.reason`). - `none` — not a vocabulary at all (an expression or an identifier,   e.g. `OptionSchema.pattern`). A field whose description hedges with \"common values\" or \"free-form\" must carry the marker; a test enforces it.  **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.220.0
+ * The version of the OpenAPI document: 2.221.0
  *
  *
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).

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

@@ -28,12 +28,14 @@ export * from './CapabilityConditionOneOf3.js';
 export * from './CapabilityConditionOneOf4.js';
 export * from './CapabilityConditionOneOf5.js';
 export * from './CapabilityConditionOneOf6.js';
+export * from './CapabilityConditionOneOf7.js';
 export * from './CapabilityConstraint.js';
 export * from './CapabilityInputSpec.js';
 export * from './CapabilityProduces.js';
 export * from './CapabilityProducesOneOf.js';
 export * from './CapabilityProducesOneOf1.js';
 export * from './CapabilityProducesOneOf2.js';
+export * from './CeilingBasisValue.js';
 export * from './ChangePasswordRequest.js';
 export * from './CheckoutSessionStatusResponse.js';
 export * from './CheckoutSessionStatusResponseData.js';
@@ -164,6 +166,7 @@ export * from './PerRoleCardinalityEntry.js';
 export * from './PerValueAvailabilityEntry.js';
 export * from './PresignedUrlPart.js';
 export * from './ProbePendingResponse.js';
+export * from './ProbeUpload422Response.js';
 export * from './ProcessingClass.js';
 export * from './ProcessingClassBandViolation.js';
 export * from './ProcessingClassConstraints.js';
@@ -218,6 +221,8 @@ export * from './UploadDurationExceedsTierResponse.js';
 export * from './UploadFile403Response.js';
 export * from './UploadFile422Response.js';
 export * from './UploadProbeMediaMetadata.js';
+export * from './UploadProbeNotApplicableResponse.js';
+export * from './UploadProbeNotReadyResponse.js';
 export * from './UploadProbeProcessingClass.js';
 export * from './UploadProbeResponse.js';
 export * from './UploadProbeStatus.js';

package/dist/openapi/models/index.js

@@ -30,12 +30,14 @@ export * from './CapabilityConditionOneOf3.js';
 export * from './CapabilityConditionOneOf4.js';
 export * from './CapabilityConditionOneOf5.js';
 export * from './CapabilityConditionOneOf6.js';
+export * from './CapabilityConditionOneOf7.js';
 export * from './CapabilityConstraint.js';
 export * from './CapabilityInputSpec.js';
 export * from './CapabilityProduces.js';
 export * from './CapabilityProducesOneOf.js';
 export * from './CapabilityProducesOneOf1.js';
 export * from './CapabilityProducesOneOf2.js';
+export * from './CeilingBasisValue.js';
 export * from './ChangePasswordRequest.js';
 export * from './CheckoutSessionStatusResponse.js';
 export * from './CheckoutSessionStatusResponseData.js';
@@ -166,6 +168,7 @@ export * from './PerRoleCardinalityEntry.js';
 export * from './PerValueAvailabilityEntry.js';
 export * from './PresignedUrlPart.js';
 export * from './ProbePendingResponse.js';
+export * from './ProbeUpload422Response.js';
 export * from './ProcessingClass.js';
 export * from './ProcessingClassBandViolation.js';
 export * from './ProcessingClassConstraints.js';
@@ -220,6 +223,8 @@ export * from './UploadDurationExceedsTierResponse.js';
 export * from './UploadFile403Response.js';
 export * from './UploadFile422Response.js';
 export * from './UploadProbeMediaMetadata.js';
+export * from './UploadProbeNotApplicableResponse.js';
+export * from './UploadProbeNotReadyResponse.js';
 export * from './UploadProbeProcessingClass.js';
 export * from './UploadProbeResponse.js';
 export * from './UploadProbeStatus.js';

package/dist/openapi/runtime.d.ts

@@ -2,7 +2,7 @@
  * 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 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).  **Free-text string fields: `x-string-vocabulary` (ticket [`Q79yjcFF`](https://trello.com/c/Q79yjcFF)).** A `type: string` field with no `enum` that names example values says, as data, what a client may do with them (the same marker is used in the AsyncAPI document): - `open` — a vocabulary that grows. Each published value keeps its   meaning, the SET is not closed: switch on the values you know and   handle an unknown one as the generic case (e.g. `ErrorEnvelope.error`). - `advisory` — explanatory text. Display or log it; **never switch on   it** (e.g. `SseWorkflowTerminalData.reason`). - `none` — not a vocabulary at all (an expression or an identifier,   e.g. `OptionSchema.pattern`). A field whose description hedges with \"common values\" or \"free-form\" must carry the marker; a test enforces it.  **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.220.0
+ * The version of the OpenAPI document: 2.221.0
  *
  *
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).

package/dist/openapi/runtime.js

@@ -4,7 +4,7 @@
  * 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 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).  **Free-text string fields: `x-string-vocabulary` (ticket [`Q79yjcFF`](https://trello.com/c/Q79yjcFF)).** A `type: string` field with no `enum` that names example values says, as data, what a client may do with them (the same marker is used in the AsyncAPI document): - `open` — a vocabulary that grows. Each published value keeps its   meaning, the SET is not closed: switch on the values you know and   handle an unknown one as the generic case (e.g. `ErrorEnvelope.error`). - `advisory` — explanatory text. Display or log it; **never switch on   it** (e.g. `SseWorkflowTerminalData.reason`). - `none` — not a vocabulary at all (an expression or an identifier,   e.g. `OptionSchema.pattern`). A field whose description hedges with \"common values\" or \"free-form\" must carry the marker; a test enforces it.  **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.220.0
+ * The version of the OpenAPI document: 2.221.0
  *
  *
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).

package/openapi/README.md

@@ -10,7 +10,7 @@
 - **Generator:** [openapi-generator-cli](https://openapi-generator.tech/) v7.21.0
   (Docker image: `openapitools/openapi-generator-cli:v7.21.0`)
 - **Generator preset:** `typescript-fetch`, models only
-- **Files:** 270
+- **Files:** 275
 
 ## Contents
 

package/openapi/api.yaml

@@ -103,7 +103,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.220.0
+  version: 2.221.0
   contact:
     name: API Support
 
@@ -1098,13 +1098,12 @@ paths:
         bad ones before submit.
 
         Per ticket [I28 `KbVAnGCm`](https://trello.com/c/KbVAnGCm).
-        `availability: planned`. The upload-probe Lambda exists and runs
-        asynchronously when an upload is finalised; this endpoint returns
-        the cached result when one exists and `feature_not_available`
-        (422) when none does yet. It does not invoke the probe itself.
-        (A `planned` endpoint that answers 200 is inconsistent with the
-        availability taxonomy; the flip decision is tracked separately,
-        card `kAT0i5A6`.) Per Tension 1 (ADR-0001 §1.3).
+        `availability: beta` (card `kAT0i5A6`, on a production
+        observation, 2026-10-01). The upload-probe Lambda runs
+        asynchronously when an upload is finalised (measured on prod:
+        about 3 s for a 3 s clip); this endpoint returns the cached
+        result when one exists and a 422 when none does yet. It does not
+        invoke the probe itself.
 
         **SDK helper intent.** SDKs are expected to expose a
         `client.preflight_clips([file_ids])` helper that compiles to N
@@ -1128,7 +1127,7 @@ paths:
       x-identity-scoped: true  # ownership-scoped per ADR-0016 D3
       tags:
         - Upload
-      x-availability: planned
+      x-availability: beta
       parameters:
         - name: id
           in: path
@@ -1223,14 +1222,49 @@ paths:
                 $ref: '#/components/schemas/ErrorEnvelope'
         '422':
           description: |
-            No probe result is cached for this upload yet (the probe runs
-            asynchronously after the upload is finalised) — returned as
-            `FeatureNotAvailableResponse` with `error_type:
-            feature_not_available`. Per Tension 1 (ADR-0001 §1.3).
+            No probe result is cached for this upload. Discriminated on
+            `error_type` (ADR-0018), card
+            [`tRVvMOvy`](https://trello.com/c/tRVvMOvy):
+            - `probe_not_ready` → `UploadProbeNotReadyResponse`: the probe
+              has not landed YET. **Retry** (`Retry-After` when present).
+            - `probe_not_applicable` → `UploadProbeNotApplicableResponse`:
+              this upload's type is never probed (e.g. an image, whose
+              metadata is read inline at upload). **Terminal — do not
+              retry**; no result will ever exist.
+            - `feature_not_available` → `FeatureNotAvailableResponse`
+              with `violations[].availability: planned`:
+              **TRANSITIONAL.** What the server sends today for BOTH
+              causes above. It predates this endpoint's move to `beta`
+              and does NOT mean the endpoint is unavailable. Retry it
+              **with a ceiling** — it can be the terminal case. The
+              server switches to the two arms above only after an SDK
+              release that reads them is published; when this arm is
+              removed is an owner decision.
+          headers:
+            Retry-After:
+              required: false
+              description: |
+                Optional, on the `probe_not_ready` branch only: suggested
+                seconds before the next poll. Delta-seconds (RFC 9110).
+                Absent ⇒ poll on your own backoff (measured on prod
+                2026-10-01: about 3 s from upload to a result for a 3 s
+                clip).
+              schema:
+                type: integer
+                minimum: 0
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/FeatureNotAvailableResponse'
+                oneOf:
+                  - $ref: '#/components/schemas/UploadProbeNotReadyResponse'
+                  - $ref: '#/components/schemas/UploadProbeNotApplicableResponse'
+                  - $ref: '#/components/schemas/FeatureNotAvailableResponse'
+                discriminator:
+                  propertyName: error_type
+                  mapping:
+                    probe_not_ready: '#/components/schemas/UploadProbeNotReadyResponse'
+                    probe_not_applicable: '#/components/schemas/UploadProbeNotApplicableResponse'
+                    feature_not_available: '#/components/schemas/FeatureNotAvailableResponse'
         '429':
           description: |
             Rate limit exceeded. Probe is rate-limited independently
@@ -3699,10 +3733,10 @@ paths:
       # ROUTE ADDED: compression_api #804 (merge 85dd49fa, 2026-09-30) serves
       # the public POST route, owner-scoped (ownership denial 404). It was
       # `planned` since 2026-08-12 (yi4TDKVJ) because no route existed. Now
-      # `beta` on a staging customer-path round-trip (e2e, 2026-09-30,
-      # availability/staging-verification-log.yaml). `stable` needs a prod
-      # observation once api's release carrying #804 is on prod.
-      x-availability: beta
+      # `beta` on a staging customer-path round-trip, then `stable` on a PROD
+      # round-trip (e2e, 2026-09-30, api build 1.16.0,
+      # availability/prod-verification-log.yaml).
+      x-availability: stable
       operationId: archiveWorkflow
       security: [{bearerAuth: []}, {sessionAuth: []}]  # required (explicit 401 in response set)
       x-identity-scoped: true  # workflow-ownership-scoped per ADR-0016 D3
@@ -3797,10 +3831,10 @@ paths:
       # ROUTE ADDED: compression_api #804 (merge 85dd49fa, 2026-09-30) serves
       # the public POST route, owner-scoped (ownership denial 404). It was
       # `planned` since 2026-08-12 (yi4TDKVJ) because no route existed. Now
-      # `beta` on a staging customer-path round-trip (e2e, 2026-09-30,
-      # availability/staging-verification-log.yaml). `stable` needs a prod
-      # observation once api's release carrying #804 is on prod.
-      x-availability: beta
+      # `beta` on a staging customer-path round-trip, then `stable` on a PROD
+      # round-trip (e2e, 2026-09-30, api build 1.16.0,
+      # availability/prod-verification-log.yaml).
+      x-availability: stable
       operationId: restoreWorkflow
       security: [{bearerAuth: []}, {sessionAuth: []}]  # required (explicit 401 in response set)
       x-identity-scoped: true  # workflow-ownership-scoped per ADR-0016 D3
@@ -6627,6 +6661,7 @@ paths:
                           effective: 128849018880
                           tier_default: 107374182400
                           overridden: true
+                          ceiling_basis: unproven
                         max_total_input_size_bytes:
                           effective: 120000000000
                           tier_default: 120000000000
@@ -8629,6 +8664,18 @@ components:
           description: |
             The tier's default cap for this limit, in the same unit as
             `effective` (already public via the tier model).
+        ceiling_basis:
+          # OPTIONAL in this expand step (xApHyTY3, from api 5pyX06rE); api
+          # emits it after this publishes.
+          $ref: '#/components/schemas/CeilingBasisValue'
+          description: |
+            Whether `effective` is a PROVEN value (owner decision 607(d) /
+            610(4)(d)). `unproven` (e.g. the Max and Enterprise
+            `max_upload_size_bytes`): the API still enforces it; present it
+            as "up to X (not yet verified)" (FORMAT.md obligation 10). ⛔
+            **ABSENT IS NOT `proven`** — it means the server made no claim,
+            so a consumer must not advertise the value as verified on its
+            strength.
         overridden:
           type: boolean
           description: |
@@ -10098,6 +10145,44 @@ components:
               items:
                 $ref: '#/components/schemas/FeatureViolation'
 
+    UploadProbeNotReadyResponse:
+      description: |
+        422 from `POST /api/uploads/{id}/probe`: the upload's server-side
+        probe has not landed YET. Retryable — poll again after
+        `Retry-After` (when present) or your own backoff. Distinct from
+        `probe_pending` (`ProbePendingResponse`, workflow-create, carries
+        `job_ref`) so each code keeps one shape. Card
+        [`tRVvMOvy`](https://trello.com/c/tRVvMOvy).
+      allOf:
+        - $ref: '#/components/schemas/ErrorEnvelope'
+        - type: object
+          required:
+            - error_type
+          properties:
+            error_type:
+              type: string
+              enum:
+                - probe_not_ready
+              description: Discriminator for the probe endpoint's 422 oneOf. Always `probe_not_ready`.
+
+    UploadProbeNotApplicableResponse:
+      description: |
+        422 from `POST /api/uploads/{id}/probe`: this upload's type is
+        never probed (e.g. an image, whose metadata is read inline at
+        upload), so no result will ever exist. **Terminal — do not
+        retry.** Card [`tRVvMOvy`](https://trello.com/c/tRVvMOvy).
+      allOf:
+        - $ref: '#/components/schemas/ErrorEnvelope'
+        - type: object
+          required:
+            - error_type
+          properties:
+            error_type:
+              type: string
+              enum:
+                - probe_not_applicable
+              description: Discriminator for the probe endpoint's 422 oneOf. Always `probe_not_applicable`.
+
     ProbePendingResponse:
       description: |
         422 response on `POST /api/workflows` when the probe-pending
@@ -14864,6 +14949,29 @@ components:
             requested `target_size_bytes`. `false` is an honest best-effort outcome
             (target unreachable at min quality), NOT a failure. Present only for a
             target_size output. Mirrors `OperationMetrics.target_size_met`.
+        already_optimal:
+          type: boolean
+          description: |
+            OPTIONAL. `true` when this file IS the original input, returned
+            unchanged because compressing it would not have made it smaller
+            (owner decision 645(4): a success; the no-charge rule and its
+            current rollout — the API still charges until it ships, and only
+            short-form compress returns this today — are stated once, on
+            `OperationResultMetadata.already_optimal`). Same value as
+            `OperationResultMetadata.already_optimal` on `/status`, projected
+            here so a per-file result built from `/downloads` does not need a
+            second read (sdks `bYOCX61m`). Absent or `false`: an ordinary
+            output; treat the two the same. Mirrors
+            `OperationMetrics.already_optimal`.
+          example: true
+        already_optimal_kind:
+          type: string
+          enum: [not_smaller]
+          description: |
+            OPTIONAL, only with `already_optimal: true`. Same value and meaning
+            as `OperationResultMetadata.already_optimal_kind`; absent or unknown:
+            neutral "already optimised" copy.
+          example: not_smaller
         measured_quality:
           type: number
           format: double
@@ -16068,8 +16176,8 @@ components:
         Recursive condition node (the `Cond` field-token model, ADR-0024
         §2). Exactly ONE form per node — a boolean combinator (`all` /
         `any` / `not`) OR a single leaf test. A leaf tests one `field`
-        token with exactly one operator (`equals` / `in` / `isSet`),
-        except `opSelected` which is a standalone leaf asserting a
+        token with exactly one operator (`equals` / `in` / `isSet` /
+        `numericZero`), except `opSelected` which is a standalone leaf asserting a
         sibling operation of that type is present in the job. Consumers
         compute field tokens locally from the resolved request (no new
         wire field). Modelled as a `oneOf` of the valid forms (each
@@ -16132,6 +16240,33 @@ components:
               description: |
                 Leaf test — asserts `field` is present/set. Only the
                 positive form is used; negate via a wrapping `not` node.
+        - type: object
+          additionalProperties: false
+          required: [field, numericZero]
+          properties:
+            field:
+              type: string
+              description: Field token under test.
+            numericZero:
+              type: boolean
+              enum: [true]  # not `const` — ADR-0010 (generators mis-emit boolean const)
+              x-matches: '^0+(\.0+)?(px|%)$'
+              description: |
+                Leaf test — `field` is an offset whose number is zero,
+                whatever its spelling (`0px`, `00%`, `0.000px`). True iff
+                the String-coerced value fully matches `x-matches`; any
+                other value is false, including `-0`, `+0` and `.0`,
+                which the offset pattern `^\d+(\.\d+)?(px|%)$` refuses
+                anyway. An unresolved field behaves as it does for
+                `equals` / `in`. This regex is NORMATIVE. api's
+                `float == 0` test agrees with it on every offset a float
+                represents faithfully; it differs only where a cast
+                underflows (hundreds of fractional zeros before a non-zero
+                digit), which api reads as zero and this leaf does not.
+                Like every operator here, its semantics live in this
+                schema, not in `operation-capabilities.json`. Only the positive
+                form is used; negate via a wrapping `not` node. Card
+                `6jTnFnTh`: replaces lexical `in` lists of zero spellings.
         - type: object
           additionalProperties: false
           required: [opSelected]
@@ -16995,14 +17130,24 @@ components:
           "up to X (not yet verified)". Each becomes `proven`, or is
           lowered to the largest passing value, after its staging corner run.
       additionalProperties:
-        type: string
-        # CLOSED: a consumer decides how to present the limit from it.
-        x-enum-openness: closed
-        enum: [proven, unproven]
+        $ref: '#/components/schemas/CeilingBasisValue'
       example:
         max_input_size_bytes: unproven
         max_input_duration: unproven
 
+    CeilingBasisValue:
+      type: string
+      description: |
+        Whether ONE declared ceiling is proven (owner decision 607(d)). The
+        single vocabulary for `CeilingBasis` (per-ceiling map on a group or
+        class) and `AccountLimitEntry.ceiling_basis` (one account limit).
+        `proven`: a recorded run passed at 95% or more of the value.
+        `unproven`: still ENFORCED, not yet run at the value; present as
+        "up to X (not yet verified)" (FORMAT.md obligation 10).
+      # CLOSED: a consumer decides how to present the limit from it.
+      x-enum-openness: closed
+      enum: [proven, unproven]
+
     ResolutionBand:
       type: string
       description: |

package/operation-capabilities/operation-capabilities.json

@@ -513,12 +513,7 @@
                       {
                         "not": {
                           "field": "image_watermark.margin_x",
-                          "in": [
-                            "0px",
-                            "0%",
-                            "0.0px",
-                            "0.0%"
-                          ]
+                          "numericZero": true
                         }
                       }
                     ]
@@ -532,12 +527,7 @@
                       {
                         "not": {
                           "field": "image_watermark.margin_y",
-                          "in": [
-                            "0px",
-                            "0%",
-                            "0.0px",
-                            "0.0%"
-                          ]
+                          "numericZero": true
                         }
                       }
                     ]
@@ -657,12 +647,7 @@
                       {
                         "not": {
                           "field": "text_watermark.margin_x",
-                          "in": [
-                            "0px",
-                            "0%",
-                            "0.0px",
-                            "0.0%"
-                          ]
+                          "numericZero": true
                         }
                       }
                     ]
@@ -676,12 +661,7 @@
                       {
                         "not": {
                           "field": "text_watermark.margin_y",
-                          "in": [
-                            "0px",
-                            "0%",
-                            "0.0px",
-                            "0.0%"
-                          ]
+                          "numericZero": true
                         }
                       }
                     ]
@@ -859,5 +839,5 @@
       "isAnimated": "maybe"
     }
   },
-  "schema_version": "2.220.0"
+  "schema_version": "2.221.0"
 }

package/operations/schemas/audio_overlay.yaml

@@ -110,8 +110,8 @@ operation:
             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
+              max_input_size_bytes: 53687091200    # 50 GiB = api's Max upload cap (decision 677)
+              max_output_size_bytes: 53687091200
             enterprise:
               max_input_size_bytes: 107374182400   # 100 GiB = api's Enterprise upload cap (owner 649(2))
               max_output_size_bytes: 107374182400
@@ -303,8 +303,8 @@ operation:
             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
+              max_input_size_bytes: 53687091200    # 50 GiB = api's Max upload cap (decision 677)
+              max_output_size_bytes: 53687091200
             enterprise:
               max_input_size_bytes: 107374182400   # 100 GiB = api's Enterprise upload cap (owner 649(2))
               max_output_size_bytes: 107374182400

package/operations/schemas/audio_watermark.yaml

@@ -75,8 +75,8 @@ operation:
             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
+              max_input_size_bytes: 53687091200    # 50 GiB = api's Max upload cap (decision 677)
+              max_output_size_bytes: 53687091200
             enterprise:
               max_input_size_bytes: 107374182400   # 100 GiB = api's Enterprise upload cap (owner 649(2))
               max_output_size_bytes: 107374182400
@@ -181,8 +181,8 @@ operation:
             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
+              max_input_size_bytes: 53687091200    # 50 GiB = api's Max upload cap (decision 677)
+              max_output_size_bytes: 53687091200
             enterprise:
               max_input_size_bytes: 107374182400   # 100 GiB = api's Enterprise upload cap (owner 649(2))
               max_output_size_bytes: 107374182400

package/operations/schemas/compress.yaml

@@ -1176,8 +1176,8 @@ operation:
             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
+              max_input_size_bytes: 53687091200    # 50 GiB = api's Max upload cap (decision 677)
+              max_output_size_bytes: 53687091200
             enterprise:
               max_input_size_bytes: 107374182400   # 100 GiB = api's Enterprise upload cap (owner 649(2))
               max_output_size_bytes: 107374182400

package/operations/schemas/convert.yaml

@@ -349,8 +349,8 @@ operation:
             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
+              max_input_size_bytes: 53687091200    # 50 GiB = api's Max upload cap (decision 677)
+              max_output_size_bytes: 53687091200
             enterprise:
               max_input_size_bytes: 107374182400   # 100 GiB = api's Enterprise upload cap (owner 649(2))
               max_output_size_bytes: 107374182400

package/operations/schemas/custom_luma.yaml

@@ -81,8 +81,8 @@ operation:
             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
+              max_input_size_bytes: 53687091200    # 50 GiB = api's Max upload cap (decision 677)
+              max_output_size_bytes: 53687091200
             enterprise:
               max_input_size_bytes: 107374182400   # 100 GiB = api's Enterprise upload cap (owner 649(2))
               max_output_size_bytes: 107374182400

package/operations/schemas/split.yaml

@@ -530,8 +530,8 @@ operation:
             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
+              max_input_size_bytes: 53687091200    # 50 GiB = api's Max upload cap (decision 677)
+              max_output_size_bytes: 53687091200
             enterprise:
               max_input_size_bytes: 107374182400   # 100 GiB = api's Enterprise upload cap (owner 649(2))
               max_output_size_bytes: 107374182400

package/operations/schemas/thumbnail.yaml

@@ -130,7 +130,7 @@ operation:
             max_input_size_bytes: 5000000000       # 5 GB (Pro)
           per_tier_constraints:
             max:
-              max_input_size_bytes: 50000000000    # 50 GB (Max self-serve band)
+              max_input_size_bytes: 53687091200    # 50 GiB = api's Max upload cap (decision 677)
             enterprise:
               max_input_size_bytes: 107374182400   # 100 GiB = api's Enterprise upload cap (owner 649(2))
       # Same 16MP output-area wall as image (width*height <= max_output_pixels).

package/operations/schemas/transform.yaml

@@ -160,8 +160,8 @@ operation:
             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
+              max_input_size_bytes: 53687091200    # 50 GiB = api's Max upload cap (decision 677)
+              max_output_size_bytes: 53687091200
             enterprise:
               max_input_size_bytes: 107374182400   # 100 GiB = api's Enterprise upload cap (owner 649(2))
               max_output_size_bytes: 107374182400

package/operations/schemas/video_text_watermark.yaml

@@ -123,8 +123,8 @@ operation:
             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
+              max_input_size_bytes: 53687091200    # 50 GiB = api's Max upload cap (decision 677)
+              max_output_size_bytes: 53687091200
             enterprise:
               max_input_size_bytes: 107374182400   # 100 GiB = api's Enterprise upload cap (owner 649(2))
               max_output_size_bytes: 107374182400

package/operations/schemas/video_watermark.yaml

@@ -90,8 +90,8 @@ operation:
             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
+              max_input_size_bytes: 53687091200    # 50 GiB = api's Max upload cap (decision 677)
+              max_output_size_bytes: 53687091200
             enterprise:
               max_input_size_bytes: 107374182400   # 100 GiB = api's Enterprise upload cap (owner 649(2))
               max_output_size_bytes: 107374182400