@giveitsmaller/contracts 0.59.0 → 0.60.0

package/openapi/api.yaml

@@ -89,7 +89,7 @@ info:
     of truth instead of hardcoding magic numbers. A runtime
     `GET /api/uploads/limits` endpoint for dynamic discovery
     (per-tier / per-environment overrides) is a deferred follow-up.
-  version: 2.180.0
+  version: 2.188.0
   contact:
     name: API Support
 
@@ -1985,7 +1985,7 @@ paths:
                         message: "Inputs use different frame rates (29.97 vs 30); set re_encode_mode to auto or always."
         '429':
           description: |
-            Rate limited. Two distinct triggers share this status — branch
+            Rate limited. Three distinct triggers share this status — branch
             on the `error` code, NOT on the status:
 
             1. **Long-form concurrency cap** — the caller already holds the
@@ -1999,13 +1999,31 @@ paths:
             2. **Infrastructure rate-limit** — too many requests in the
                current window. The links-absent subset of the same shape: a
                plain `ErrorEnvelope` with a `Retry-After` header.
+            3. **Duplicate in progress** — the caller resubmitted an
+               identical workflow whose idempotency claim is already held by
+               an in-flight create (deduplication that prevents a
+               double-charge; ticket
+               [`DSxwCetg`](https://trello.com/c/DSxwCetg)). Body is a plain
+               `ErrorEnvelope`: `error: DUPLICATE_IN_PROGRESS`, `message_key:
+               job.duplicate_in_progress`, **no `Retry-After`** and **no
+               `links`**. **Transient — the caller SHOULD retry:** the retry
+               folds onto the now-attached winning workflow and returns
+               `201` with that existing workflow (the normal create shape),
+               so the winning `workflow_id` is delivered on the retry, not
+               here. There is no id to return at this point — the winner is
+               still mid-create (its `workflow_id` is not yet assigned), which
+               is exactly what "in progress" means. This is why the status is
+               `429` (retry-with-backoff resolves it) rather than `409`.
           headers:
             Retry-After:
               description: |
                 Seconds to wait before retrying. Delta-seconds (RFC 9110).
                 Present ONLY for the infrastructure rate-limit trigger —
-                ABSENT for `LONG_FORM_CONCURRENCY_LIMIT_EXCEEDED` (that
-                limit clears on workflow completion, not on a timer).
+                ABSENT for `LONG_FORM_CONCURRENCY_LIMIT_EXCEEDED` (clears on
+                workflow completion, not a timer) and for
+                `DUPLICATE_IN_PROGRESS` (resolves when the caller retries and
+                folds onto the winning workflow — retry promptly, no fixed
+                back-off window).
               schema:
                 type: integer
                 minimum: 0
@@ -2030,6 +2048,14 @@ paths:
                   value:
                     success: false
                     error: "Too many requests. Please try again later."
+                duplicate_in_progress:
+                  summary: Identical workflow already mid-create (idempotency fold — retry to get the 201-with-existing-workflow)
+                  value:
+                    success: false
+                    error: "DUPLICATE_IN_PROGRESS"
+                    message: "An identical workflow is already being created. Retry in a moment to attach to it."
+                    message_key: "job.duplicate_in_progress"
+                    locale: "en-GB"
         '500':
           description: Internal server error
           content:
@@ -5754,6 +5780,34 @@ components:
         - planned
         - deprecated
 
+    PerClassAvailabilityEntry:
+      type: object
+      description: |
+        Availability of an option (or one of its values) on ONE execution
+        class. Attached as a value within a `per_class_availability` map,
+        keyed by a `processing_class` name the parent mime_group
+        declares.
+
+        Exists because `processing_class:` is a SIBLING of `options:`,
+        not a parent, so without this overlay "honoured on short-form,
+        unavailable on long-form" is inexpressible and the only
+        instrument is an operation-wide `planned` — which withdraws a
+        working capability from every caller to describe one path's gap.
+
+        **May only RESTRICT** relative to the scope it overlays, never
+        re-open it (`schemas/FORMAT.md` §Precedence; machine-enforced).
+      required:
+        - availability
+      properties:
+        availability:
+          $ref: '#/components/schemas/AvailabilityValue'
+        eta:
+          type: string
+          description: ISO-8601 date or quarter when this class is expected to support it.
+        documentation_url:
+          type: string
+          format: uri
+
     PerValueAvailabilityEntry:
       type: object
       description: |
@@ -5772,11 +5826,50 @@ components:
         present in this map MUST be a subset of the option's `values[]`
         array — verified by `make check-per-value-availability`
         (`scripts/check-per-value-availability.py`).
+
+        **`availability` is ALWAYS required, including when
+        `per_class_availability` is present.** An entry carrying a
+        per-class overlay MUST also state the blanket truth:
+
+            target_size:
+              availability: stable          # true on every other path
+              per_class_availability:
+                long_form_re_encode: { availability: planned }
+
+        **Ruled 2026-07-29, reversing an earlier reading of mine that
+        the absence of a blanket tag was itself the statement.** Three
+        reasons, and the third is the one that decided it:
+
+        1. It keeps the restrict-only check **LOCAL** — the value an
+           overlay is compared against sits in the same entry, instead
+           of requiring a walk up to option/group/operation scope that
+           must be got right at every nesting depth.
+        2. It keeps consumers' parsers correct as written: requiring the
+           blanket value IS the rule they already enforce.
+        3. **It stops the absence of a key carrying meaning.** A reader
+           seeing only `per_class_availability` would have to INFER the
+           general level from a key that is not there — the failure
+           shape this contract spent 2026-07-28 removing everywhere
+           else, and it should not be reintroduced here.
+
+        Nothing is lost by requiring it: the blanket value is `stable`,
+        which is TRUE, and most-cautious inheritance then yields the
+        intended behaviour from the per-class restriction on top.
       required:
         - availability
       properties:
         availability:
           $ref: '#/components/schemas/AvailabilityValue'
+        per_class_availability:
+          type: object
+          description: |
+            Per-execution-class overlay for this enum value: restricts it
+            on named `processing_class` entries of the parent mime_group
+            while leaving the others at the inherited level. Keys MUST be
+            classes the group declares. See `schemas/FORMAT.md`
+            §`per_class_availability`.
+          additionalProperties:
+            $ref: '#/components/schemas/PerClassAvailabilityEntry'
         required_tier:
           description: |
             Tier required to use this enum value. Optional — omit when
@@ -5915,6 +6008,7 @@ components:
 
     UploadSource:
       type: object
+      additionalProperties: false  # closed to the API allowlist {type, file_id} — fZXM5VZd
       description: |
         References an upload created via `POST /api/uploads` (single)
         or completed via `POST /api/uploads/multipart/complete`
@@ -5931,6 +6025,7 @@ components:
 
     JobOutputSource:
       type: object
+      additionalProperties: false  # closed to the API allowlist {type, from, operation} — fZXM5VZd
       description: |
         References the output of an upstream job in the same workflow.
         Used to chain operations: workflow runs job A first, then job B
@@ -5954,6 +6049,7 @@ components:
 
     ExternalImportToken:
       type: object
+      additionalProperties: false  # closed to the API allowlist {type, external_source_id} — fZXM5VZd
       description: |
         Opaque handle returned by `POST /api/external-imports` for a
         one-shot bearer URL (S3 presigned, GCS signed, Azure SAS,
@@ -5973,6 +6069,7 @@ components:
 
     ConnectionSource:
       type: object
+      additionalProperties: false  # closed to the API allowlist {type, connection_id, path} — fZXM5VZd
       description: |
         Reference to a vaulted connection (pre-registered via
         `POST /api/connections` — owned by cross-repo `compression_api`
@@ -6013,6 +6110,17 @@ components:
 
         Wiring into `JobDefinition` lands via ticket
         [I12 (`Gr0VKFya`)](https://trello.com/c/Gr0VKFya).
+
+        **All four leaves are CLOSED** (`additionalProperties: false`) to
+        exactly the API's per-leaf allowlist (`WorkflowSourceV2Constraint`,
+        which hard-rejects any extra key). This is a deliberate forward-compat
+        stance (ticket [`fZXM5VZd`](https://trello.com/c/fZXM5VZd)): a client
+        sending a *future* additive field fails contract-validation the same way
+        the API already rejects it — so contract and runtime agree. Adding a new
+        field to a leaf therefore requires a paired API-allowlist change in the
+        same co-land. The union aliases themselves (`WorkflowSource`,
+        `MultiInputSource`, `ExternalSource`) stay open — they are `oneOf`
+        dispatchers, not property-bearing objects.
       oneOf:
         - $ref: '#/components/schemas/UploadSource'
         - $ref: '#/components/schemas/JobOutputSource'
@@ -6914,7 +7022,10 @@ components:
         documented string (not a strict enum) so the rate-limit subset
         validates against the same schema and consumers tolerate unknown
         codes; SDKs branch on the `LONG_FORM_CONCURRENCY_LIMIT_EXCEEDED`
-        value to distinguish the two.
+        value to distinguish it. A third links-absent branch shares this
+        `429`: `DUPLICATE_IN_PROGRESS` (idempotency fold, ticket
+        [`DSxwCetg`](https://trello.com/c/DSxwCetg)) — see the endpoint's
+        `429` response description for the full trigger list.
 
         Mirrors the runtime shape produced by `compression_api`'s
         `WorkflowController` +
@@ -9798,6 +9909,82 @@ components:
         - `tier_policy`: emitted when the caller's
           `processing.class_hint` (e.g. `short_form_only`) forced
           the decision rather than input characteristics.
+        - `input_metrics_unavailable`: **the classifier did not have
+          every metric the decision required.** One or more of the
+          duration / size figures it needed was unavailable at
+          create-plan time (e.g. an upload probe had not landed), so a
+          class was DEFAULTED rather than chosen. Note this covers the
+          PARTIAL case as well as the none-at-all case — see below;
+          having *some* metrics is not having the metric the decision
+          required. **This is the only
+          value that does not assert a measurement.** Every other value
+          states a fact about the input; this one states that no such
+          fact was obtained.
+
+          **It is a reason a class was DEFAULTED, not a reason a class
+          was CHOSEN** — despite sitting in `ProcessingClassReason`.
+          Read it as *no routing claim was made*. Consumers MUST NOT
+          read the assigned `processing_class` as evidence the input
+          fits that class's constraints when this reason is present,
+          and MUST NOT surface it as a positive statement about the
+          file.
+
+          **Partial measurement usually counts as unmeasured.** On a
+          multi-input operation, emit this whenever a contributing
+          input lacked the metric the decision needed — a sum over the
+          inputs that happened to be probed is not a measurement of the
+          request, even though it is not empty either. The honest
+          predicate is "did I have every metric this decision required",
+          not "did I have some".
+
+          **The exception, and it is a principle rather than a special
+          case: partial evidence that is DECISIVE is still evidence.**
+          Ask whether the missing data could FALSIFY the claim the
+          reason makes:
+
+          - `within_short_form_limits` claims the input **fits**. An
+            unmeasured input can only ADD to the sum, so it could push
+            the request over the cap — the missing data can falsify the
+            claim. This reason therefore requires COMPLETE measurement,
+            and a partial sum must report `input_metrics_unavailable`.
+          - `input_duration_exceeds_short_form` /
+            `input_size_exceeds_short_form` claim the input **exceeds**
+            a cap. The sums are MONOTONE — they only grow — so once the
+            measured subset alone crosses the cap, the missing data
+            cannot falsify the claim. The escalation is positively
+            evidenced, and the decision did not *need* the missing
+            metric. **Report the real reason, NOT
+            `input_metrics_unavailable`.**
+
+          Reporting "I could not measure" for a decision that WAS
+          positively evidenced is a lie in the opposite direction, and
+          it costs twice: it understates what the server knew, and —
+          because this field carries one value — it MASKS a more
+          specific true reason such as `merge_re_encode_long_form`.
+
+          **Generalise by the falsifiability test, not by the list
+          above.** If a future cap is a band rather than a ceiling, or
+          a metric can reduce a total, the monotonicity no longer holds
+          and the exception does not apply.
+
+          **Known limit, stated so it is not later read as a gap in a
+          completed fix:** an input whose probe landed with a duration
+          of **zero** counts as MEASURED and contributes 0 to the sum.
+          That is indistinguishable from a genuine zero-length input
+          from outside the classifier, so this value does not and
+          cannot cover it.
+
+        **Why this value exists (2026-07-28).** A deduplicated upload
+        (and, independently, a fresh upload racing an async probe)
+        reaches create-plan with no duration, and a 62-minute merge was
+        assigned `short_form` with reason `within_short_form_limits` —
+        an affirmative claim that a 62-minute input fits inside a
+        `PT5M` cap. The fallback was indistinguishable from a genuine
+        measurement, so the mis-route was invisible. A classifier that
+        cannot say *"I did not know"* has no way to be honest; this
+        value is that sentence. Emit it in preference to a
+        measurement-asserting value whenever the metrics were absent,
+        even if the class ultimately chosen happens to be correct.
       enum:
         - within_short_form_limits
         - input_size_exceeds_short_form
@@ -9805,6 +9992,7 @@ components:
         - merge_re_encode_long_form
         - requires_reencode
         - tier_policy
+        - input_metrics_unavailable
 
     ProcessingPlanJob:
       type: object
@@ -9845,6 +10033,90 @@ components:
           $ref: '#/components/schemas/EstimateQuality'
         reason:
           $ref: '#/components/schemas/ProcessingClassReason'
+        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
+            something is told.
+
+            **Why this field exists at all.** Dropping a defaulted
+            option is better than refusing the request, and it is still
+            a silent no-op unless we say so — the caller asked for
+            (say) audio normalisation, we did not do it, and nobody
+            told them. This field is the "we did not do that" sentence,
+            the same honesty requirement as
+            `ProcessingClassReason.input_metrics_unavailable`.
+
+            **🔴 ABSENCE CARRIES NO INFORMATION until every server
+            emits it.** An empty array means "nothing was dropped". An
+            ABSENT array means "this server does not report drops" —
+            consumers MUST NOT read absence as "nothing was dropped".
+            Once the emitting side ships, the array is always present.
+          items:
+            $ref: '#/components/schemas/DroppedOption'
+
+    DroppedOption:
+      type: object
+      description: |
+        One server-supplied option removed from a job 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.
+      required:
+        - option
+        - reason
+      properties:
+        option:
+          type: string
+          description: The option key that was removed, as it appears in the operation schema.
+          example: normalize_audio
+        operation_type:
+          type: string
+          description: |
+            The operation the option belonged to. Present because a job
+            may carry several operations, so the option key alone does
+            not identify where the drop happened.
+          example: merge
+        operation_id:
+          type: string
+          format: uuid
+          description: The specific operation, when the server can attribute the drop to one.
+        processing_class:
+          $ref: '#/components/schemas/ProcessingClass'
+        reason:
+          type: string
+          description: |
+            Why the option was dropped. **A documented vocabulary, NOT a
+            strict enum** — deliberately, following `error_code`: a
+            consumer MUST map known values to a friendly reason and
+            MUST degrade an unknown one, so the vocabulary can grow
+            without breaking clients.
+
+            **Known values:**
+
+            - `unavailable_on_processing_class` — the option is tagged
+              unavailable for the class this job resolved to (see
+              `per_class_availability` in `schemas/FORMAT.md`). The
+              `processing_class` field names which.
+            - `processing_class_unmeasured` — the class could NOT be
+              measured (see
+              `ProcessingClassReason.input_metrics_unavailable`), so the
+              option was dropped rather than refused. **Refusing a
+              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.
+
+            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
 
     ProcessingPlan:
       type: object
@@ -11248,11 +11520,29 @@ components:
             Distinct from the workflow/API create-time `ErrorEnvelope.error`
             vocabulary — this is the per-operation processing failure.
 
-            **Retry semantics:** the sibling `is_retryable` marks the transient
-            codes (`out_of_memory`, `timeout`, `s3_download_failed`,
-            `s3_upload_failed`); those are auto-redriven (SQS) and exhausted
-            before a failure surfaces, so a reported failure is always terminal —
-            `is_retryable` only tells the user whether re-submitting is worthwhile.
+            **Retry semantics — DERIVE THEM FROM THIS FIELD.** Retryability is a
+            property OF THE ERROR CODE, not an independent fact about an
+            occurrence: the same code is always equally retryable, so there is
+            no per-response boolean on this surface to read. The transient codes
+            are `out_of_memory`, `timeout`, `s3_download_failed` and
+            `s3_upload_failed`; the AsyncAPI `ErrorCode` enum groups every value
+            under **Retryable** / **Non-retryable** headings and is the source of
+            truth for that mapping.
+
+            Note a reported failure is **always terminal** regardless: transient
+            codes are auto-redriven (SQS) and exhausted before a failure ever
+            surfaces here, so retryability only tells the caller whether
+            **re-submitting** is worthwhile.
+
+            **This docstring previously referred to "the sibling `is_retryable`".
+            There is no such field on the OpenAPI surface** — it exists only on
+            the AsyncAPI worker→API channel, so no generated REST client could
+            ever carry it, and the contract was describing to consumers something
+            it does not deliver (ticket `wdOF3ol4`). Deliberately corrected by
+            REMOVING the promise rather than by adding the field: a per-response
+            boolean would be a second source of truth for a fact the code already
+            determines, free to drift from it, and it would break again when the
+            `retryable` boolean→enum change lands.
 
             **Codes** (closed set; meaning):
             `invalid_options` (options invalid for this op — most common),
@@ -11265,6 +11555,12 @@ components:
             `invalid_key` (storage key invalid),
             `processing_failed` (non-specific processing failure),
             `s3_access_denied` (storage access denied — fail-fast, non-retryable),
+            `input_too_large` (input exceeds our PROCESSING limits — deterministic,
+            user-actionable via downscaling or a higher tier; distinct from the
+            byte caps, which are refused at create and never reach a worker),
+            `never_started` (the operation was terminated without ever running
+            because its job reached a terminal state first — an upstream failure
+            OR a cancellation; API-derived, never worker-emitted),
             `unknown` (unclassified),
             `out_of_memory` (retryable), `timeout` (retryable),
             `s3_download_failed` (retryable), `s3_upload_failed` (retryable).
@@ -13168,6 +13464,31 @@ components:
             scoped to a single option (e.g. an operation may have a
             free-tier base option set with one or two `pro`-tier
             advanced options gated this way).
+        per_class_availability:
+          type: object
+          description: |
+            Per-EXECUTION-CLASS overlay for this option: restricts it on named
+            `processing_class` entries of the parent mime_group while leaving
+            the others at the inherited level. Keys MUST be classes the group
+            declares.
+
+            Use this — NOT an operation-wide `availability` — when a worker
+            honours an option on one execution path and refuses it on another.
+            Marking the whole option `planned` would withdraw a working
+            capability from every caller in order to describe one path's gap.
+
+            May only RESTRICT relative to the scope it overlays, never re-open
+            it. See `schemas/FORMAT.md` §`per_class_availability` and
+            §Precedence (machine-enforced by
+            `scripts/check-per-class-availability.py`).
+
+            Note the option-level overlay and the per-VALUE one
+            (`per_value_availability.<value>.per_class_availability`) can
+            coexist: the option-level says the worker refuses the KEY on that
+            path, the value-level says it refuses one VALUE. Most-cautious
+            inheritance applies.
+          additionalProperties:
+            $ref: '#/components/schemas/PerClassAvailabilityEntry'
         per_value_availability:
           $ref: '#/components/schemas/PerValueAvailability'
           description: |

package/operation-capabilities/operation-capabilities.json

@@ -732,5 +732,5 @@
       "isAnimated": "maybe"
     }
   },
-  "schema_version": "2.180.0"
+  "schema_version": "2.188.0"
 }

package/operations/schemas/audio_overlay.yaml

@@ -241,7 +241,6 @@ operation:
           type: float
           min: -80.0
           max: -10.0
-          default: -50.0
           availability: planned
           description: |
             Silence threshold (dB) for the `sync_to_silence` feature.
@@ -254,7 +253,6 @@ operation:
           type: integer
           min: 50
           max: 30000
-          default: 500
           availability: planned
           description: |
             Minimum silence duration (milliseconds) to qualify as an
@@ -412,7 +410,6 @@ operation:
           type: float
           min: -80.0
           max: -10.0
-          default: -50.0
           availability: planned
           description: |
             Silence threshold (dB) for `sync_to_silence`. Inert
@@ -422,7 +419,6 @@ operation:
           type: integer
           min: 50
           max: 30000
-          default: 500
           availability: planned
           description: |
             Minimum silence duration (milliseconds) for