@giveitsmaller/contracts 0.83.0 → 0.85.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.218.0
+ * The version of the OpenAPI document: 2.220.0
  *
  *
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).

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.218.0
+ * The version of the OpenAPI document: 2.220.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.218.0
+ * The version of the OpenAPI document: 2.220.0
  *
  *
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).

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.218.0
+  version: 2.220.0
   contact:
     name: API Support
 
@@ -1472,9 +1472,20 @@ paths:
         immutable ledger transaction is written in the same DB
         transaction as the workflow row; the response's
         `processing_plan` reflects the same estimate the reservation
-        was sized against. Refunds (e.g. on terminal failure that the
-        server policy refunds) are emitted as separate ledger rows
-        referencing the reservation via `reference_id`. The
+        was sized against. **Callers pay only for successful results,
+        per job** (owner decisions 610(4) and 635; the policy is data in
+        `schemas/pricing-policy.yaml`). Each job that completes is charged;
+        a job that fails after its retries is refunded, as is cancelled
+        work (a workflow paused for credits has its reservation released at
+        the pause and reserved again on resume), so a `partially_failed`
+        workflow is charged for the jobs that completed. A long-form fan-out is settled
+        at what it actually used and the difference is refunded. Uploading
+        is free; an operation on a larger input costs more, through the
+        size surcharge in that file. Refunds are separate ledger rows
+        referencing the reservation via `reference_id`. ⚠️ **Contract-first:**
+        until api ships the per-job change, the API refunds the WHOLE
+        reservation when any job fails, so a `partially_failed` workflow is
+        charged nothing (`pricing-policy.yaml` `charge.api_today`). The
         idempotency-key wire shape for retried reservation attempts
         is deferred per ADR-0001 §1.7 row 5.
       operationId: createWorkflow
@@ -1580,7 +1591,11 @@ paths:
                         - type: compress
       responses:
         '201':
-          description: Workflow created
+          description: |
+            Workflow created. A long video `compress` that the API runs as an
+            internal fan-out appears as ONE job with ONE `compress` operation
+            whose id is the one `/status` and SSE report; see **LONG-FORM
+            FAN-OUT: ONE PUBLIC ROW** on `GET /api/workflows/{id}/events`.
           content:
             application/json:
               schema:
@@ -2016,7 +2031,7 @@ paths:
               Per-violation `required_tier` names the tier (if any)
               whose `per_tier_constraints` would accommodate the
               request (`null` = no tier resolves, e.g. enterprise
-              already at the 120 GB hard ceiling). Distinct from
+              already at its hard ceiling). Distinct from
               `TierRestrictionResponse` (403, request-level upload
               quota — see [ADR-0012](../docs/decisions/0012-processing-class-band-reject-envelope.md)
               for the band-vs-tier split). Per ADR-0001 §F6
@@ -2104,7 +2119,13 @@ paths:
                 Optional, best-effort. Present only on the
                 `probe_pending` branch — suggested seconds to wait
                 before re-polling the upload probe and retrying the
-                workflow. Delta-seconds (RFC 9110), mirroring the 429
+                workflow. **A guest (no credential) cannot poll the probe**
+                (`POST /api/uploads/{id}/probe` requires sign-in): it retries
+                the create itself. After `video.probe_wait_bound_seconds` from the upload
+                the create proceeds without a duration (guest unknown-duration rule). A `probe_pending` refusal does not count
+                against the guest per-minute create limit and reserves no
+                guest allowance credits (`schemas/anonymous-policy.yaml`
+                `video`). Delta-seconds (RFC 9110), mirroring the 429
                 login path's `Retry-After` convention. Absent until the
                 server-side probe-staleness bound (API `e1Idv6UL`)
                 lands; consumers MUST treat absence as "retry on your
@@ -2327,6 +2348,12 @@ paths:
         Retrieve the current status of a workflow with nested job and operation breakdown.
         Each operation includes its current progress and, when completed, its result
         (download URL, size, metrics).
+
+        A long video `compress` that the API runs as an internal fan-out
+        (split, segments, concat) appears here as ONE job with ONE `compress`
+        operation. See **LONG-FORM FAN-OUT: ONE PUBLIC ROW** on
+        `GET /api/workflows/{id}/events`, which is normative for this
+        endpoint too.
       operationId: getWorkflowStatus
       security: [{}, {bearerAuth: []}, {sessionAuth: []}]  # optional (anon-OK; identity-scoped to workflow owner)
       x-identity-scoped: true  # workflow-ownership-scoped per ADR-0016 D3
@@ -2573,6 +2600,15 @@ paths:
               schema:
                 $ref: '#/components/schemas/ErrorEnvelope'
 
+  # LONG-FORM FAN-OUT fold (section in the description below), read from
+  # compression_api main 2a8dd8d5, paths under compression/src/Jobs/:
+  #   fold + public ids:  Domain/Service/FanOutClusterFolder.php:22-47,218-239,332-354,452-545
+  #   ids:                Domain/Service/FanOutNodeIdFactory.php:82-94,176-196
+  #   public op shape:    Domain/ValueObject/FanOutPublicOperation.php:45,85-87
+  #   SSE frames:         Application/Service/WorkflowSseService.php:333-350,563-671
+  #   create 201 row:     Presentation/Http/Controller/WorkflowController.php:543-589,725-740
+  #   fallback path:      Application/Service/LongFormFanOutBuilder.php:784-830
+  #   concat auto-retry:  Infrastructure/Messaging/Handler/OperationResultHandler.php:712-730
   /api/workflows/{id}/events:
     get:
       summary: Stream workflow events (SSE)
@@ -2880,6 +2916,80 @@ paths:
         (the `id:` and `event:` lines) is transport-level and intentionally
         **not** schema-described.
 
+        ### LONG-FORM FAN-OUT: ONE PUBLIC ROW
+
+        This section is normative for **every read surface**; the `/status`
+        and create-201 descriptions point here rather than restate it.
+
+        The API may run a long video `compress` as an internal fan-out: one
+        `split` job, then N parallel segment `compress` jobs, then a
+        stream-copy concat (`merge`). It applies only to a root job holding a
+        single `compress`, and only one such job per workflow. Today the API
+        also requires that no other job depends on it; a client must not rely
+        on that: if a fanned-out job has dependants, they read the joined
+        output, exactly as they would read the job's output unsplit.
+        **Clients never see the fan-out.** The API folds it into
+        ONE public job with ONE public operation on the create 201,
+        `GET /status` and this stream, and into ONE job row on
+        `GET /api/workflows` (whose rows carry no operations; read the
+        operation from `/status`). On `GET /downloads` the joined file is
+        listed under the original `job_ref` with operation `compress`, when
+        it is delivered at all: only once it is complete, only if the
+        delivery selection includes that job, and only while retained. The
+        internal jobs and operations do not appear on any surface, and this
+        stream sends no frame for them.
+
+        | field | value |
+        |---|---|
+        | `job_ref` / `ref` | the client's **original** job ref, on every surface and every path below |
+        | `job_id` | one server-chosen id for the public job, the same before and after the split expands |
+        | `operation_id` / `operations[0].id` | one server-chosen id, the same on the 201, `/status` and this stream, before and after the split expands (exceptions below) |
+        | `type` | `compress` (never `split` or `merge`), including the output-name marker |
+        | `processing_class` (`/status`, `processing_plan`) | `long_form` |
+        | `depends_on` | `[]` |
+        | outputs | exactly one: the joined file |
+
+        **On this stream** the public operation gets zero or more
+        `operation.progress` frames, then ONE `operation.completed` or ONE
+        `operation.failed`, then ONE `job.completed` or `job.failed` for the
+        public job. A failure can arrive with no progress frame before it,
+        so the terminal frame may be the first one. These frames
+        carry **no `id:` line**. `operation.completed` carries no
+        `result_metadata`, and its `result` stays optional as on every
+        `SseOperationCompletedData`: when it is absent, read the output from
+        `GET /downloads`. `job.failed` can arrive in a later frame batch
+        than `operation.failed`.
+
+        **Progress** is weighted by phase: split 10, segments 80 (shared
+        equally), concat 10. Until the split finishes and the segments exist,
+        it **stays at or below 10**: a long bar at 10% is the split running,
+        not a stall. On this stream it never decreases within one connection.
+        `GET /status` reads a snapshot per poll and can dip briefly between
+        polls. Clients that must not show a backwards bar hold their own
+        maximum per `job_ref`.
+
+        **Failure.** Any failed segment fails the whole public operation. The
+        reported `error_code` is the causing failure; a `never_started`
+        collateral code is reported only when there is no causing one.
+
+        **The operation id is NOT stable in two cases. Key the row on
+        `job_ref`, which is.**
+        1. **Unsplittable input.** When the split finds the file cannot be
+           split, the API runs one plain long-form `compress` instead. It has
+           a **new** `job_id` and `operation_id`, under the same `job_ref`.
+           The first id gets no terminal frame. Its progress starts again
+           from 0, so a bar keyed on `job_ref` goes back from 10 to 0 once.
+        2. **Automatic retry of the concat step.** The retry is a new
+           operation with a new id, and the public row then shows that id.
+           User retries (`POST /api/operations/{id}/retry`) are refused for
+           the internal operations.
+
+        **Downloads.** Before the split finishes the public job's
+        `/downloads` row lists no files; while segments run it can be
+        absent; it lists the one output once the concat completes. On the
+        unsplittable path there is no concat: the fallback `compress` job
+        is an ordinary row and lists its output when it completes.
+
         ### AUTH ON THE STREAM HOST: the CREDENTIAL decides, not the caller
 
         **Two axes, and conflating them is what made two earlier versions of this
@@ -3586,29 +3696,13 @@ paths:
         a **409** — cancel it first (`POST /api/workflows/{id}/cancel`) or wait
         for it to finish. Archiving does NOT change the workflow's status; it
         stays terminal and the response echoes it unchanged.
-      # ⚠️ NO PUBLIC HTTP ROUTE EXISTS FOR THIS. Downgraded to `planned`
-      # 2026-08-12 (yi4TDKVJ, raised by sdks + codex) on POSITIVE evidence, as
-      # standing policy 3 requires — not on an absent attestation, which policy
-      # 4 says is not enough:
-      #   * no `#[Route(...)]` matching archive/restore anywhere in
-      #     compression_api's `src/`;
-      #   * no `api/workflows/{id}/archive` or `/restore` path in `src/` or
-      #     `config/`;
-      #   * verified independently by sdks (named commit) and by codex reading
-      #     the list controller and its repository.
-      #
-      # ⚠️ CORRECTION TO THE RELAYED EVIDENCE, because it changes the ticket
-      # rather than the verdict: the claim reaching this repo was that a grep
-      # for `archiveWorkflow|/archive|archived` over `src` and `config`
-      # "returns NO OUTPUT". IT DOES NOT — `ArchiveWorkflowCommand`,
-      # `ArchiveWorkflowCommandHandler` and a `RestoreWorkflow` command all
-      # EXIST, and there is an ADMIN CRUD controller that archives. So this is
-      # **implemented in the application layer and not exposed on the public
-      # API**, which is a different thing from "nothing behind it". The verdict
-      # is unchanged — an unroutable capability is unreachable, so `planned` is
-      # correct — but anyone scoping the work should know a handler already
-      # exists.
-      x-availability: planned
+      # 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
       operationId: archiveWorkflow
       security: [{bearerAuth: []}, {sessionAuth: []}]  # required (explicit 401 in response set)
       x-identity-scoped: true  # workflow-ownership-scoped per ADR-0016 D3
@@ -3700,29 +3794,13 @@ paths:
         `status` is the workflow's unchanged status (any `WorkflowStatus`
         value), not a fixed terminal subset. There is no 409: un-archiving is
         always safe.
-      # ⚠️ NO PUBLIC HTTP ROUTE EXISTS FOR THIS. Downgraded to `planned`
-      # 2026-08-12 (yi4TDKVJ, raised by sdks + codex) on POSITIVE evidence, as
-      # standing policy 3 requires — not on an absent attestation, which policy
-      # 4 says is not enough:
-      #   * no `#[Route(...)]` matching archive/restore anywhere in
-      #     compression_api's `src/`;
-      #   * no `api/workflows/{id}/archive` or `/restore` path in `src/` or
-      #     `config/`;
-      #   * verified independently by sdks (named commit) and by codex reading
-      #     the list controller and its repository.
-      #
-      # ⚠️ CORRECTION TO THE RELAYED EVIDENCE, because it changes the ticket
-      # rather than the verdict: the claim reaching this repo was that a grep
-      # for `archiveWorkflow|/archive|archived` over `src` and `config`
-      # "returns NO OUTPUT". IT DOES NOT — `ArchiveWorkflowCommand`,
-      # `ArchiveWorkflowCommandHandler` and a `RestoreWorkflow` command all
-      # EXIST, and there is an ADMIN CRUD controller that archives. So this is
-      # **implemented in the application layer and not exposed on the public
-      # API**, which is a different thing from "nothing behind it". The verdict
-      # is unchanged — an unroutable capability is unreachable, so `planned` is
-      # correct — but anyone scoping the work should know a handler already
-      # exists.
-      x-availability: planned
+      # 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
       operationId: restoreWorkflow
       security: [{bearerAuth: []}, {sessionAuth: []}]  # required (explicit 401 in response set)
       x-identity-scoped: true  # workflow-ownership-scoped per ADR-0016 D3
@@ -6228,12 +6306,12 @@ paths:
                   value:
                     success: true
                     data:
-                      monthly_balance: 1200
+                      monthly_balance: 800
                       purchased_balance: 5000
-                      overdraft_limit: 500
+                      overdraft_limit: 200
                       overdraft_debt: 0
-                      available_credits: 6700
-                      monthly_allowance: 2000
+                      available_credits: 6000
+                      monthly_allowance: 1000
                       tier: pro
                 pro_overdrafted:
                   summary: Pro tier in overdraft (monthly + purchased exhausted)
@@ -6242,10 +6320,10 @@ paths:
                     data:
                       monthly_balance: 0
                       purchased_balance: 0
-                      overdraft_limit: 500
-                      overdraft_debt: 350
-                      available_credits: 150
-                      monthly_allowance: 2000
+                      overdraft_limit: 200
+                      overdraft_debt: 150
+                      available_credits: 50
+                      monthly_allowance: 1000
                       tier: pro
         '401':
           description: Authentication required.
@@ -8286,7 +8364,10 @@ components:
         overdraft_debt:
           type: integer
           minimum: 0
-          description: Credits currently owed against the overdraft pool.
+          description: >-
+            Credits currently owed against the overdraft pool. Repaid one
+            credit for one credit from the next monthly grant, on every
+            plan (`schemas/pricing-policy.yaml` `overdraft.repayment_ratio`).
         available_credits:
           type: integer
           description: |
@@ -9893,6 +9974,14 @@ components:
               description: |
                 Which guest limit was exceeded. OPEN: a consumer that does
                 not know a value shows the envelope's localised message.
+                `video_duration_seconds` is only ever sent for a MEASURED
+                duration: a guest video whose duration is unknown (the probe
+                could not measure one, or had not landed within
+                `video.probe_wait_bound_seconds` of the upload) is allowed, not
+                refused, as an ordinary guest create that reserves allowance
+                credits and counts against the per-minute create limit (owner
+                decision 648, `schemas/anonymous-policy.yaml`
+                `video.unknown_duration`).
               type: string
               x-enum-openness: open
               enum:
@@ -10024,7 +10113,12 @@ components:
         (`ok` → re-`POST /api/workflows` the same request; `corrupt` /
         `unsupported_codec` → surface the probe error, do not retry).
         The `Retry-After` response header (when present) carries the
-        suggested delay in seconds before the next poll/retry.
+        suggested delay in seconds before the next poll/retry. **A guest
+        (no credential) cannot poll**: the probe endpoint requires
+        sign-in, so a guest re-`POST`s the same create on `Retry-After`
+        or its own backoff; the refusal does not count against its
+        per-minute create limit or allowance
+        (`schemas/anonymous-policy.yaml` `video`).
 
         Delivered alongside `ValidationErrorEnvelope`,
         `FeatureNotAvailableResponse`, and
@@ -10219,7 +10313,7 @@ components:
             server SHOULD set `required_tier` to that tier — consumers
             can offer an upgrade nudge. `null` (or omitted) means
             **no tier resolves** the overflow (e.g. enterprise already
-            hits the 120 GB hard ceiling per
+            hits its hard ceiling per
             [ADR-0011](../docs/decisions/0011-per-tier-processing-class-constraints.md)
             D1–D4).
 
@@ -10271,7 +10365,7 @@ components:
         `required_tier` on each `ProcessingClassBandViolation` names
         the tier (if any) whose `per_tier_constraints` would
         accommodate the request; `null` means terminal (e.g. enterprise
-        already at the 120 GB hard ceiling).
+        already at its hard ceiling).
 
         Per
         [ADR-0012](../docs/decisions/0012-processing-class-band-reject-envelope.md)
@@ -10730,8 +10824,9 @@ components:
             Recommended chunk size in bytes for multipart upload
             chunks (16 MiB / 16,777,216 bytes — 1024-based). Raised
             from 5 MiB by CON-1 (ADR-0011): S3 caps a multipart
-            upload at 10,000 parts, and the Enterprise envelope is a
-            120 GB hard ceiling. At 16 MiB a 120 GiB object needs
+            upload at 10,000 parts, and the Enterprise envelope was
+            sized at 120 GB (the per-file ceiling is now 100 GiB, owner
+            649(2), which fits with margin). At 16 MiB a 120 GiB object needs
             7,680 parts (≤ 10,000, inside AWS's 16–64 MB recommended
             band); 5 MiB would need 24,576 and 10 MiB 12,288 — both
             exceed the S3 limit. **Wire-incompatible change** — SDKs
@@ -12482,13 +12577,16 @@ components:
         dropped_options:
           type: array
           description: |
-            Options the SERVER supplied on the caller's behalf and then
-            REMOVED, because the resolved execution path cannot honour
-            them. **Never contains a value the caller sent explicitly** —
-            an explicit option the path cannot honour is refused with
-            `422 feature_not_available`, not silently dropped. That
-            split is the whole rule: a caller who asked for nothing is
-            not punished for our default; a caller who asked for
+            Options holding their DEFAULT (supplied by the server, or
+            sent by the client equal to the schema default, which reads as
+            defaulted — `schemas/FORMAT.md` "Container-conditional
+            defaults") that were then REMOVED or SUBSTITUTED, because the
+            resolved execution path or output container cannot honour
+            them. **Never contains a caller's choice** — a value that
+            differs from the default and cannot be honoured is refused
+            (`422 feature_not_available` / `invalid_options`), not
+            dropped. That split is the whole rule: a caller who asked for
+            nothing is not punished for our default; a caller who asked for
             something is told.
 
             **Why this field exists at all.** Dropping a defaulted
@@ -12510,7 +12608,8 @@ components:
     DroppedOption:
       type: object
       description: |
-        One server-supplied option removed from a job before dispatch.
+        One defaulted option (server-supplied, or sent equal to its
+        schema default) removed or substituted before dispatch.
         **Names the THING, the WHY and the PATH** — the three parts a
         caller needs to act, and the three a single interpolated string
         would fuse into something unparseable.
@@ -12557,12 +12656,29 @@ components:
               caller on a guessed class is the same error as asserting
               a measurement never taken**, so an unmeasured basis
               degrades to a drop and never to a 422.
+            - `container_incompatible_default` — the option held its
+              schema default (omitted, or sent equal to the default),
+              and the output container cannot carry that value, so the
+              container's own default was applied instead; the applied
+              value is in `resolved_value` (e.g. `codec` `h264` on a
+              WebM output → `vp9`; `audio_codec` `copy` of AAC into
+              WebM → `opus`). See `schemas/FORMAT.md`
+              "Container-conditional defaults". Contract-first (api
+              `PSJ1vBC7`).
 
             The class token is deliberately NOT interpolated into this
             string: the reason and the path are separate fields because
             a fused `not_available_on_<class>` is unparseable and
             duplicates `processing_class`.
           example: unavailable_on_processing_class
+        resolved_value:
+          type: string
+          description: |
+            OPTIONAL. The value the server applied in place of the
+            dropped one, when it substituted a value rather than
+            removing the option (`reason: container_incompatible_default`).
+            Absent for a plain drop.
+          example: vp9
 
     ProcessingPlan:
       type: object
@@ -14068,6 +14184,43 @@ components:
             `input_filename`. Ticket [`j2s6T2qf`](https://trello.com/c/j2s6T2qf)
             (FE before→after size, workflow-view launch ask).
           example: 491520
+        input_uploaded_at:
+          type: string
+          format: date-time
+          description: |
+            OPTIONAL. When the server finished receiving the job's input
+            upload: a single-shot upload's accept, or a multipart
+            `complete`. For a job with several uploaded inputs (e.g. a
+            merge), the LATEST of them, since the job cannot start before
+            its last input arrives; inputs that are not uploads (another
+            job's output, an import) are ignored. Absent when the job has no
+            uploaded input, and until the API records it. Card
+            [`6EOlMAz4`](https://trello.com/c/6EOlMAz4) (e2e performance
+            baseline, owner decisions 630/635): with `started_at` and
+            `completed_at` it separates upload, queue and processing time on
+            the server clock. Contract-first: api populates it in a
+            follow-up; a client must treat absence as "not recorded".
+          example: "2026-09-29T21:00:00Z"
+        started_at:
+          type: string
+          format: date-time
+          description: |
+            OPTIONAL. When the job's first operation started processing (the
+            first progress report from a worker). Absent while the job is
+            queued, and for a job that never started. Server clock. See
+            `input_uploaded_at`.
+          example: "2026-09-29T21:00:04Z"
+        completed_at:
+          type: string
+          format: date-time
+          description: |
+            OPTIONAL. When the job reached a terminal `JobStatus`
+            (`completed` or `failed`), on the server clock. Absent while
+            the job is not terminal.
+            `completed_at - started_at` is the job's EXECUTION SPAN: for a
+            chain of operations it includes any wait between them, so it is
+            not pure processing time. See `input_uploaded_at`.
+          example: "2026-09-29T21:00:19Z"
         processing_class:
           $ref: '#/components/schemas/ProcessingClass'
           description: |
@@ -14177,7 +14330,9 @@ components:
             `invalid_format` (input type unsupported),
             `format_mismatch` (declared MIME ≠ content),
             `decode_failed` (input unreadable/corrupt),
-            `output_too_large` (output exceeded the size limit),
+            `output_too_large` (output exceeded the size limit; NOT for a
+            same-format `compress`, which returns the original with
+            `already_optimal` instead — owner decision 645(4)),
             `missing_source` (source not found — fail-fast),
             `invalid_key` (storage key invalid),
             `processing_failed` (non-specific processing failure),
@@ -14276,7 +14431,35 @@ components:
             "already optimised", not as "same size". On an ordinary result it
             is absent or `false`; treat the two the same. Projected by the API from the wire
             `OperationMetrics.already_optimal` (ticket `roNRMilt`).
+            **Charged nothing** (owner decision 645(4),
+            `schemas/pricing-policy.yaml` `charge.not_charged`): the
+            operation's cost is refunded; other operations in the job are
+            charged as usual. Applies to a completed `compress` on the
+            resolved `same_format` route (`output_format` original, absent, or
+            equal to the input's format; not the format-change facade, where
+            the original is not what was asked for). A same-format compress
+            that cannot shrink the file returns this, never `output_too_large`.
+            ⚠️ **Today this holds for SHORT-FORM compress only.** Long-form
+            compress still fails `output_too_large` until lambdas ships its
+            long-form copy path; do not promise "already optimised" or "no
+            charge" for a long-form file before then. Contract-first: until api
+            ships, the operation is charged (`charge.not_charged_api_today`).
+            `already_optimal_kind` says which kind of "already optimised" it
+            was.
           example: true
+        already_optimal_kind:
+          type: string
+          enum: [not_smaller]
+          description: |
+            OPTIONAL, only with `already_optimal: true`: WHY the original was
+            returned. `not_smaller` — the file was compressed and the result
+            was not smaller, so there is no quality trade-off to explain. It
+            is the only kind any worker produces today (no production path
+            declines to encode an efficient source). Absent, or a value you do
+            not know: show neutral "already optimised" copy.
+            Contract-first (card `cDZuuyg8`): projected from the wire
+            `OperationMetrics.already_optimal_kind` once workers emit it.
+          example: not_smaller
         estimated_saving_pct:
           type: number
           minimum: 0
@@ -17167,6 +17350,16 @@ components:
         app:
           type: boolean
           description: Application is running
+        build:
+          type: string
+          description: |
+            OPTIONAL. The release the running image was built as (the API's
+            `APP_VERSION`, e.g. `1.15.2-rc.1`; `dev` for a local build;
+            `unknown` when unset). Unauthenticated on purpose: a timing run
+            reads it before and after, so a code-only deploy in the middle
+            of the run is detectable (card `6EOlMAz4`, e2e performance
+            baseline). Opaque: compare for equality, do not parse.
+          example: "1.15.2-rc.1"
 
     ReadinessResponse:
       type: object

package/operation-capabilities/operation-capabilities.json

@@ -253,7 +253,6 @@
               {
                 "field": "compress.codec",
                 "in": [
-                  "h264",
                   "h265"
                 ]
               }
@@ -860,5 +859,5 @@
       "isAnimated": "maybe"
     }
   },
-  "schema_version": "2.218.0"
+  "schema_version": "2.220.0"
 }

package/operations/schemas/audio_overlay.yaml

@@ -113,8 +113,8 @@ operation:
               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
+              max_input_size_bytes: 107374182400   # 100 GiB = api's Enterprise upload cap (owner 649(2))
+              max_output_size_bytes: 107374182400
       options:
         start_at:
           type: float
@@ -306,8 +306,8 @@ operation:
               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
+              max_input_size_bytes: 107374182400   # 100 GiB = api's Enterprise upload cap (owner 649(2))
+              max_output_size_bytes: 107374182400
       options:
         start_at:
           type: float