@giveitsmaller/contracts 0.82.0 → 0.84.0

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.217.0
+  version: 2.219.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:
@@ -1813,13 +1828,31 @@ paths:
               credential) requested an operation outside the anonymous
               allow-list. `operation` names the first such operation.
               A register-wall: signing in is the remedy, not upgrading.
-            - `anonymous_quota_exhausted`: an anonymous caller has used
-              its per-IP workflow allowance for the rolling 24 hours.
-              Also a register-wall.
-
-            Both anonymous walls are checked BEFORE the workflow is
-            built, and neither consumes the caller's anonymous
-            allowance. An authenticated caller never receives either.
+            - `anonymous_quota_exhausted`: this create would cost more
+              credits than the caller's per-IP allowance has left in the
+              rolling 24 hours (`schemas/anonymous-policy.yaml`
+              `allowance`). Also a register-wall. Carries `allowance`,
+              `remaining` and `cost`, and `Retry-After` unless the request
+              costs more than the whole allowance.
+            - `anonymous_limit_exceeded`: an anonymous caller's input
+              exceeds a guest-only limit (today: video duration). Also a
+              register-wall.
+
+            The anonymous walls are checked BEFORE the workflow is
+            built, and none consumes the caller's anonymous
+            allowance. An authenticated caller never receives any.
+          headers:
+            Retry-After:
+              required: false
+              description: |
+                Present only on `anonymous_quota_exhausted`, and only when
+                the request's `cost` fits the `allowance` at all: seconds
+                until enough of the caller's rolling 24 h credit window
+                frees up for it. Delta-seconds (RFC 9110). Signing in
+                remains the immediate remedy.
+              schema:
+                type: integer
+                minimum: 0
           content:
             application/json:
               schema:
@@ -1828,6 +1861,7 @@ paths:
                   - $ref: '#/components/schemas/FeatureTierRestrictedResponse'
                   - $ref: '#/components/schemas/AnonymousOperationNotAllowedResponse'
                   - $ref: '#/components/schemas/AnonymousQuotaExhaustedResponse'
+                  - $ref: '#/components/schemas/AnonymousLimitExceededResponse'
                 discriminator:
                   propertyName: error_type
                   mapping:
@@ -1835,6 +1869,7 @@ paths:
                     feature_tier_restricted: '#/components/schemas/FeatureTierRestrictedResponse'
                     anonymous_operation_not_allowed: '#/components/schemas/AnonymousOperationNotAllowedResponse'
                     anonymous_quota_exhausted: '#/components/schemas/AnonymousQuotaExhaustedResponse'
+                    anonymous_limit_exceeded: '#/components/schemas/AnonymousLimitExceededResponse'
               examples:
                 feature_tier_restricted:
                   summary: Free tier referencing a Pro-tier operation
@@ -1866,6 +1901,21 @@ paths:
                     message: "Sign up to keep compressing."
                     message_key: "error.anonymous_quota_exhausted"
                     locale: "en-GB"
+                    allowance: 30
+                    remaining: 2
+                    cost: 5
+                anonymous_limit_exceeded:
+                  summary: Anonymous caller's video is longer than the guest cap
+                  value:
+                    success: false
+                    error: "ANONYMOUS_LIMIT_EXCEEDED"
+                    error_type: "anonymous_limit_exceeded"
+                    message: "Sign up to process videos longer than a minute."
+                    message_key: "error.anonymous_limit_exceeded"
+                    locale: "en-GB"
+                    limit: "video_duration_seconds"
+                    actual: 95
+                    maximum: 60
         '402':
           description: |
             Credit reservation failed (per ticket
@@ -2069,7 +2119,12 @@ 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. 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
@@ -2292,6 +2347,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
@@ -2538,6 +2599,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)
@@ -2845,6 +2915,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
@@ -6193,12 +6337,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)
@@ -6207,10 +6351,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.
@@ -8251,7 +8395,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: |
@@ -9773,19 +9920,36 @@ components:
     AnonymousQuotaExhaustedResponse:
       description: |
         403 from `POST /api/workflows` when an ANONYMOUS caller (no
-        credential) has used its per-IP workflow allowance for the
-        rolling 24 hours. A register-wall, distinct from the generic
-        `429`: the remedy is signing in, not waiting.
+        credential) asks for a workflow that would cost more CREDITS than
+        its per-IP allowance has left in the rolling 24 hours
+        (`schemas/anonymous-policy.yaml` `allowance`, priced with the same
+        operation weights as a signed-in caller). The request is refused
+        whole; nothing runs. A register-wall, distinct from the generic
+        `429`: the remedy is signing in.
+
+        The recovery figures are REQUIRED fields of this envelope, not
+        localisation parameters (`ErrorEnvelope.message_params` excludes
+        cost numbers): `allowance`, `remaining` and `cost`, in credits.
+
+        Two cases, told apart by `cost` against `allowance`:
+        - `cost <= allowance`: waiting helps. The response carries
+          `Retry-After`, the seconds until enough of the window frees up.
+        - `cost > allowance`: the request can NEVER fit a guest window
+          (the body is not bounded to the allowance). No `Retry-After`;
+          only signing in, or a smaller request, helps.
 
         Mirrors `compression_api`'s `WorkflowController` register-wall
-        (`JobsErrorCode::AnonymousQuotaExhausted`). The allowance is only
-        consumed by a workflow that is actually created, so a refused
-        request does not use it up.
+        (`JobsErrorCode::AnonymousQuotaExhausted`). Credits are charged
+        only by a workflow that is actually created, and released on
+        failure, so a refused request does not use any up.
       allOf:
         - $ref: '#/components/schemas/ErrorEnvelope'
         - type: object
           required:
             - error_type
+            - allowance
+            - remaining
+            - cost
           properties:
             error:
               enum:
@@ -9795,6 +9959,64 @@ components:
               type: string
               enum:
                 - anonymous_quota_exhausted
+            allowance:
+              type: integer
+              minimum: 0
+              description: Credits per rolling 24 h for this IP (the policy value).
+            remaining:
+              type: integer
+              minimum: 0
+              description: Credits left in the window when the request was refused.
+            cost:
+              type: integer
+              minimum: 1
+              description: |
+                What this request would have charged. When it exceeds
+                `allowance`, the request can never fit and `Retry-After`
+                is absent.
+    AnonymousLimitExceededResponse:
+      description: |
+        403 from `POST /api/workflows` when an ANONYMOUS caller's input
+        exceeds a guest-only limit declared in
+        `schemas/anonymous-policy.yaml`. Today the one such limit is the
+        video duration cap (`video.max_duration_seconds`), measured on the
+        upload probe's duration; the create waits for the probe first. A
+        register-wall: signing in lifts the guest limit (the signed-in
+        caller's ordinary class ceilings then apply). Not a
+        processing-class refusal: no class or tier ceiling is involved.
+      allOf:
+        - $ref: '#/components/schemas/ErrorEnvelope'
+        - type: object
+          required:
+            - error_type
+            - limit
+            - actual
+            - maximum
+          properties:
+            error:
+              enum:
+                - ANONYMOUS_LIMIT_EXCEEDED
+            error_type:
+              description: Discriminator for the 403 oneOf. Always `anonymous_limit_exceeded` for this envelope.
+              type: string
+              enum:
+                - anonymous_limit_exceeded
+            limit:
+              description: |
+                Which guest limit was exceeded. OPEN: a consumer that does
+                not know a value shows the envelope's localised message.
+              type: string
+              x-enum-openness: open
+              enum:
+                - video_duration_seconds
+            actual:
+              type: integer
+              minimum: 0
+              description: The input's value, in the unit `limit` names (seconds, rounded up).
+            maximum:
+              type: integer
+              minimum: 0
+              description: The guest limit, from `schemas/anonymous-policy.yaml`.
     FeatureViolation:
       type: object
       description: |
@@ -9914,7 +10136,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
@@ -12372,13 +12599,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
@@ -12400,7 +12630,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.
@@ -12447,12 +12678,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
@@ -13958,6 +14206,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: |
@@ -14067,7 +14352,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),
@@ -14166,7 +14453,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
@@ -17057,6 +17372,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.217.0"
+  "schema_version": "2.219.0"
 }

package/operations/schemas/compress.yaml

@@ -1217,9 +1217,10 @@ operation:
             Output container. original = keep the input container (default, same-format
             compression). Other values change the container as part of the same job, keeping
             the size cap. When set, the RESOLVED target container determines the valid
-            codec/audio_codec/faststart sets — an absent/default codec resolves to a
-            container-valid one (e.g. webm -> vp9) and is never rejected; only a
-            caller-EXPLICIT incompatible value is rejected.
+            codec/audio_codec/faststart sets — an absent or default-equal value (sent equal
+            to its default counts as the default) resolves to a container-valid one (e.g.
+            webm -> vp9), is never rejected, and is reported in dropped_options; only a
+            NON-default incompatible value is rejected.
         codec:
           type: enum
           values: [h264, h265, vp9, av1]
@@ -1241,8 +1242,10 @@ operation:
             the input container): for a container that cannot carry it (e.g. WebM, which
             carries VP8/VP9/AV1) the server resolves a container-valid codec (WebM -> vp9).
             A DEFAULT value is never rejected — including an explicit `output_format: webm`
-            left at the default `h264` (resolves to vp9, not rejected); only a
-            caller-EXPLICIT incompatible codec is rejected.
+            left at the default `h264` (resolves to vp9, not rejected). A value equal to the
+            default counts as the default even when sent, and the substitution is reported
+            in dropped_options. Only a NON-default codec the container cannot carry is
+            rejected (e.g. h265 on WebM).
         encoding_mode:
           type: enum
           values: [crf, target_size]
@@ -1395,9 +1398,9 @@ operation:
             Move the MP4/MOV moov atom to the front so the file starts playing before it is
             fully downloaded (progressive web playback). MP4/MOV only. CONTAINER-CONDITIONAL
             against the RESOLVED output container (the explicit `output_format` if set, else
-            the input): the default (true) is silently inapplicable for a container with no
-            moov atom (e.g. WebM) — that is NOT a rejection. Only a caller-EXPLICIT
-            faststart:true on such a container is rejected.
+            the input): on a container with no moov atom (e.g. WebM) the default (true),
+            omitted or sent, is dropped and reported in dropped_options — never a rejection.
+            false there asks for nothing and is accepted.
         audio_codec:
           type: enum
           values: [aac, opus, vorbis, copy]
@@ -1422,9 +1425,11 @@ operation:
             the container, an absent/default audio_codec resolves to a container-valid codec
             via the facade (e.g. webm -> opus), NOT a blind copy of an incompatible stream —
             a DEFAULT is never rejected (the exact per-container resolution, incl. ogg
-            vorbis-vs-opus, is an output_format stable-flip prerequisite). A caller-EXPLICIT
-            codec the resolved container cannot carry (e.g. aac on a webm target) is
-            rejected.
+            vorbis-vs-opus, is an output_format stable-flip prerequisite). `copy` sent
+            explicitly counts as the default: if the source audio cannot be copied into the
+            target container it is re-encoded to the container default (webm -> opus) and
+            reported in dropped_options. A NON-default codec the resolved container cannot
+            carry (e.g. aac on a webm target) is rejected.
         audio_bitrate:
           type: enum
           value_type: integer