@giveitsmaller/contracts 0.59.0 → 0.61.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.189.0
   contact:
     name: API Support
 
@@ -1450,6 +1450,7 @@ paths:
                     data:
                       workflow_id: "019539ac-2222-7000-8000-000000000001"
                       status: "pending"
+                      anonymous: false
                       created_at: "2026-04-26T14:30:00Z"
                       jobs:
                         - ref: "main"
@@ -1488,6 +1489,7 @@ paths:
                     data:
                       workflow_id: "019539ac-2222-7000-8000-000000000002"
                       status: "pending"
+                      anonymous: false
                       created_at: "2026-04-26T14:30:00Z"
                       jobs:
                         - ref: "file1"
@@ -1985,7 +1987,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 +2001,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 +2050,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:
@@ -2062,12 +2090,55 @@ paths:
           schema:
             type: string
           description: |
-            Capability token (the `cap` from the anonymous workflow-create
-            response) authorizing this read for a **null-owner** workflow.
-            Optional — an authenticated owner does not need it. A wrong or
-            missing cap on a null-owner workflow returns 404 `WorkflowNotFound`
-            (no existence oracle — not 401/403). Per ticket
-            [`YQt88cq2`](https://trello.com/c/YQt88cq2).
+            Capability token (the `cap` from the workflow-create response)
+            authorizing this read. Optional — an authenticated owner does not
+            need it.
+
+            **`cap` is emitted only for anonymous (null-owner) creates TODAY,
+            but do not read anything about OWNERSHIP from that** — see the
+            `anonymous` field on the create response, which is the only
+            supported way to determine it. This sentence used to describe `cap`
+            as the anonymous-create token, and that phrasing is what licensed a
+            consumer to treat its presence as proof of anonymity.
+
+            **A wrong or missing cap returns 404 `WorkflowNotFound`, never
+            401/403 — and that holds for an OWNED workflow too**, not only a
+            null-owner one, whenever the caller cannot otherwise prove they may
+            read it. The reason is stated here rather than left as a rule,
+            because a prohibition without its reason gets overturned by whoever
+            reads it next: **a 403 would be an existence oracle.** It would let
+            an unauthorized caller distinguish "this workflow exists and is not
+            yours" from "no such workflow", which is exactly what the
+            null-owner case deliberately avoids — and it is strictly worse on an
+            owned workflow, where existence is tied to an identifiable account.
+
+            **Scope — what a capability grants WHEN it authorizes:
+            `/status`, `/downloads` and `/events`, these three read paths and
+            only these.** No write, no cancel, no retry, no archive. The
+            authorizer is the single authority for all three, and **any
+            asymmetry between the three paths would be a second authorizer in
+            disguise.**
+
+            **WHEN a capability authorizes is a separate question, and TODAY
+            THE ANSWER IS NARROWER: a null-owner workflow only.** An OWNED
+            workflow authorizes on the session/owner match and **ignores the
+            capability entirely** — presenting one does not grant a read. Do
+            not implement capability acceptance on owned workflows from this
+            paragraph.
+
+            That is scheduled to change: under
+            [`H9dOu7kZ`](https://trello.com/c/H9dOu7kZ) an owned workflow will
+            authorize on **owner match OR a valid capability**, so that a
+            logged-in caller can authorize a read against the separate stream
+            host. **Until that ships, the scope rule above describes the grant,
+            not its availability on owned workflows** — the two were stated as
+            one sentence in the first draft of this text, which read as though
+            capability acceptance were already ownership-independent. It is
+            not.
+
+            Per ticket [`YQt88cq2`](https://trello.com/c/YQt88cq2); 404-vs-403
+            and the scope rule confirmed against the implementation by api,
+            2026-08-11 ([`H9dOu7kZ`](https://trello.com/c/H9dOu7kZ)).
       responses:
         '200':
           description: Workflow status retrieved
@@ -2162,12 +2233,55 @@ paths:
           schema:
             type: string
           description: |
-            Capability token (the `cap` from the anonymous workflow-create
-            response) authorizing this read for a **null-owner** workflow.
-            Optional — an authenticated owner does not need it. A wrong or
-            missing cap on a null-owner workflow returns 404 `WorkflowNotFound`
-            (no existence oracle — not 401/403). Per ticket
-            [`YQt88cq2`](https://trello.com/c/YQt88cq2).
+            Capability token (the `cap` from the workflow-create response)
+            authorizing this read. Optional — an authenticated owner does not
+            need it.
+
+            **`cap` is emitted only for anonymous (null-owner) creates TODAY,
+            but do not read anything about OWNERSHIP from that** — see the
+            `anonymous` field on the create response, which is the only
+            supported way to determine it. This sentence used to describe `cap`
+            as the anonymous-create token, and that phrasing is what licensed a
+            consumer to treat its presence as proof of anonymity.
+
+            **A wrong or missing cap returns 404 `WorkflowNotFound`, never
+            401/403 — and that holds for an OWNED workflow too**, not only a
+            null-owner one, whenever the caller cannot otherwise prove they may
+            read it. The reason is stated here rather than left as a rule,
+            because a prohibition without its reason gets overturned by whoever
+            reads it next: **a 403 would be an existence oracle.** It would let
+            an unauthorized caller distinguish "this workflow exists and is not
+            yours" from "no such workflow", which is exactly what the
+            null-owner case deliberately avoids — and it is strictly worse on an
+            owned workflow, where existence is tied to an identifiable account.
+
+            **Scope — what a capability grants WHEN it authorizes:
+            `/status`, `/downloads` and `/events`, these three read paths and
+            only these.** No write, no cancel, no retry, no archive. The
+            authorizer is the single authority for all three, and **any
+            asymmetry between the three paths would be a second authorizer in
+            disguise.**
+
+            **WHEN a capability authorizes is a separate question, and TODAY
+            THE ANSWER IS NARROWER: a null-owner workflow only.** An OWNED
+            workflow authorizes on the session/owner match and **ignores the
+            capability entirely** — presenting one does not grant a read. Do
+            not implement capability acceptance on owned workflows from this
+            paragraph.
+
+            That is scheduled to change: under
+            [`H9dOu7kZ`](https://trello.com/c/H9dOu7kZ) an owned workflow will
+            authorize on **owner match OR a valid capability**, so that a
+            logged-in caller can authorize a read against the separate stream
+            host. **Until that ships, the scope rule above describes the grant,
+            not its availability on owned workflows** — the two were stated as
+            one sentence in the first draft of this text, which read as though
+            capability acceptance were already ownership-independent. It is
+            not.
+
+            Per ticket [`YQt88cq2`](https://trello.com/c/YQt88cq2); 404-vs-403
+            and the scope rule confirmed against the implementation by api,
+            2026-08-11 ([`H9dOu7kZ`](https://trello.com/c/H9dOu7kZ)).
       responses:
         '200':
           description: Download URLs retrieved
@@ -2282,12 +2396,55 @@ paths:
           schema:
             type: string
           description: |
-            Capability token (the `cap` from the anonymous workflow-create
-            response) authorizing this read for a **null-owner** workflow.
-            Optional — an authenticated owner does not need it. A wrong or
-            missing cap on a null-owner workflow returns 404 `WorkflowNotFound`
-            (no existence oracle — not 401/403). Per ticket
-            [`YQt88cq2`](https://trello.com/c/YQt88cq2).
+            Capability token (the `cap` from the workflow-create response)
+            authorizing this read. Optional — an authenticated owner does not
+            need it.
+
+            **`cap` is emitted only for anonymous (null-owner) creates TODAY,
+            but do not read anything about OWNERSHIP from that** — see the
+            `anonymous` field on the create response, which is the only
+            supported way to determine it. This sentence used to describe `cap`
+            as the anonymous-create token, and that phrasing is what licensed a
+            consumer to treat its presence as proof of anonymity.
+
+            **A wrong or missing cap returns 404 `WorkflowNotFound`, never
+            401/403 — and that holds for an OWNED workflow too**, not only a
+            null-owner one, whenever the caller cannot otherwise prove they may
+            read it. The reason is stated here rather than left as a rule,
+            because a prohibition without its reason gets overturned by whoever
+            reads it next: **a 403 would be an existence oracle.** It would let
+            an unauthorized caller distinguish "this workflow exists and is not
+            yours" from "no such workflow", which is exactly what the
+            null-owner case deliberately avoids — and it is strictly worse on an
+            owned workflow, where existence is tied to an identifiable account.
+
+            **Scope — what a capability grants WHEN it authorizes:
+            `/status`, `/downloads` and `/events`, these three read paths and
+            only these.** No write, no cancel, no retry, no archive. The
+            authorizer is the single authority for all three, and **any
+            asymmetry between the three paths would be a second authorizer in
+            disguise.**
+
+            **WHEN a capability authorizes is a separate question, and TODAY
+            THE ANSWER IS NARROWER: a null-owner workflow only.** An OWNED
+            workflow authorizes on the session/owner match and **ignores the
+            capability entirely** — presenting one does not grant a read. Do
+            not implement capability acceptance on owned workflows from this
+            paragraph.
+
+            That is scheduled to change: under
+            [`H9dOu7kZ`](https://trello.com/c/H9dOu7kZ) an owned workflow will
+            authorize on **owner match OR a valid capability**, so that a
+            logged-in caller can authorize a read against the separate stream
+            host. **Until that ships, the scope rule above describes the grant,
+            not its availability on owned workflows** — the two were stated as
+            one sentence in the first draft of this text, which read as though
+            capability acceptance were already ownership-independent. It is
+            not.
+
+            Per ticket [`YQt88cq2`](https://trello.com/c/YQt88cq2); 404-vs-403
+            and the scope rule confirmed against the implementation by api,
+            2026-08-11 ([`H9dOu7kZ`](https://trello.com/c/H9dOu7kZ)).
 
             **SSE transport note:** native browser `EventSource` cannot set
             request headers (its constructor accepts only `url` + `withCredentials`
@@ -5754,6 +5911,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 +5957,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 +6139,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 +6156,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 +6180,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 +6200,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 +6241,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 +7153,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 +10040,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 +10123,7 @@ components:
         - merge_re_encode_long_form
         - requires_reencode
         - tier_policy
+        - input_metrics_unavailable
 
     ProcessingPlanJob:
       type: object
@@ -9845,6 +10164,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
@@ -10470,9 +10873,43 @@ components:
         - processing_plan
         - warnings
         - created_at
+        - anonymous
       properties:
         workflow_id:
           $ref: '#/components/schemas/UuidV7'
+        anonymous:
+          type: boolean
+          readOnly: true
+          # REQUIRED and NOT nullable, deliberately: absence must be
+          # STRUCTURALLY IMPOSSIBLE rather than merely discouraged. A field a
+          # client is told to rely on, which can be missing, is a field the
+          # client will write a fallback for — and the fallback here is the
+          # exact inference this field exists to replace.
+          #
+          # END OF LIFE, recorded now while it costs nothing: this is a boolean
+          # because there are exactly TWO creation modes today. If a third ever
+          # appears (service account, delegated key), THIS FIELD IS AT END OF
+          # LIFE and the fix is an enum — do NOT add a second boolean beside it.
+          # Two booleans encoding three states is how a field stops being
+          # answerable. Building the enum today would be premature; the marker
+          # is not.
+          description: |
+            Whether this workflow was created **without an owning account**.
+            **Always present.**
+
+            Clients MUST use this field to determine anonymity and **MUST NOT
+            infer it from the presence or absence of `cap`.** That inference
+            was licensed by this contract's own earlier wording, was correct
+            when written, and is being withdrawn: `cap` is scheduled to become
+            present for owned workflows too
+            ([`H9dOu7kZ`](https://trello.com/c/H9dOu7kZ)), at which point any
+            client deriving ownership from it silently misclassifies every
+            authenticated workflow.
+
+            This field ships FIRST and alone, ahead of that change, so no
+            consumer has to be correct at the same instant a producer changes
+            behaviour.
+          example: false
         status:
           $ref: '#/components/schemas/WorkflowStatus'
         created_at:
@@ -10568,13 +11005,27 @@ components:
             - "null"
           readOnly: true
           description: |
-            Per-workflow capability token (plaintext). Present ONLY for an
-            **anonymous (null-owner)** workflow create — it is the bearer that
-            authorizes reads of this workflow without a session. ABSENT for
-            authenticated creates (the session authorizes those). Like
+            Per-workflow capability token (plaintext) — the bearer that
+            authorizes reads of this workflow without a session. Like
             `webhook_secret`, this is the only time it is exposed; it does not
             appear in status queries.
 
+            **Do NOT use the presence or absence of this field to determine
+            whether a workflow is anonymous — read `anonymous` instead.** Today
+            `cap` is emitted only for anonymous (null-owner) creates and is
+            absent for authenticated ones, so the inference currently *works*;
+            that is precisely why it needs stating. It is scheduled to stop
+            being true ([`H9dOu7kZ`](https://trello.com/c/H9dOu7kZ)): `cap` will
+            be minted for owned workflows so that a logged-in caller can
+            authorize a read against the separate stream host, where a session
+            cookie does not reach.
+
+            The prohibition lives here, in the contract text, rather than only
+            in a consumer's code review, because a consumer that encoded the
+            old wording accurately was reading this contract correctly — that
+            is the contract working, and it is this text's job to withdraw the
+            licence.
+
             Pass it as the `X-Workflow-Capability` request header on
             `GET /api/workflows/{id}/status` / `/downloads` / `/events`. A wrong
             or missing cap on a null-owner workflow returns **404**
@@ -11248,11 +11699,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 +11734,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 +13643,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: |