@giveitsmaller/contracts 0.73.0 → 0.78.0

package/asyncapi/events.yaml

@@ -5,6 +5,9 @@ info:
   description: |
     Asynchronous event contracts for the GISL (Give It Smaller) compression service.
 
+    Free-text string fields carry `x-string-vocabulary` (`open` / `advisory` /
+    `none`), defined in `openapi/api.yaml` `info.description` (ticket Q79yjcFF).
+
     **Architecture Overview — Dual-Family SNS Topology**
 
     The API publishes operation requests to **two** SNS topics, split by semantic
@@ -41,12 +44,15 @@ info:
       `availability: beta` for its `audio` and `video` mime_groups
       (workers live on staging — [`vKI0CFDu`](https://trello.com/c/vKI0CFDu);
       video activates BOTH classes — `long_form` / `split-video-fargate`
-      deployed + wired on staging but NOT yet proven end-to-end per
-      [`rcwvUKhI`](https://trello.com/c/rcwvUKhI) — first customer-path soak
-      incomplete, 4GB+ speed-up unmeasured, fan-out flag-gated dark);
+      stays `beta` until a PRODUCTION `customer_path` run is recorded in
+      `availability/prod-verification-log.yaml` per
+      [`rcwvUKhI`](https://trello.com/c/rcwvUKhI) — worker-direct staging runs
+      up to 3.99 GiB are recorded in the staging log as partial evidence
+      only; fan-out admission is the API's
+      `LONGFORM_FANOUT_ADMISSION_ENABLED`, set per environment in
+      compression_terraform, and not restated here);
       its `image_gif` and `document_pdf` mime_groups stay
       `availability: planned`.
-      `audio_watermark` additionally requires `enterprise` tier.
 
     **Publisher branching rule** (implemented in `compression_api`'s
     `AwsSnsOperationPublisherAdapter` under Option A):
@@ -91,19 +97,28 @@ info:
       `compression-document`. Each handles `compress` only for its media
       type.
     - **Operations family** (non-compression), routed by `operation_type`:
-      `operation-thumbnail` (legacy, retiring after migration),
       `operation-thumbnail-image`, `operation-thumbnail-video`,
       `operation-thumbnail-document`, `operation-thumbnail-office`,
       `operation-image-watermark`, `operation-text-watermark`,
-      `operation-merge`, `operation-archive`,
-      `operation-convert`,
-      `operation-custom-luma` (planned per ticket I29 — not yet shipped),
-      `operation-audio-overlay` (planned per ticket I19 — not yet shipped),
-      `operation-audio-watermark` (planned per ticket I20 —
-      enterprise-tier; not yet shipped),
+      `operation-video-watermark`, `operation-video-text-watermark`,
+      `operation-audio-to-video`, `operation-merge`, `operation-split`,
+      `operation-archive`, `operation-convert`,
+      `operation-render-variants` (its operation is still `planned`).
+      This list is asserted against compression_lambdas'
+      `scripts/build-deploy-matrix.py` roster by
+      `tests/test_asyncapi_lambda_inventory_matches_roster.py`; the
+      `upload-probe` Lambda is in that roster too but is not
+      `operation_type`-routed.
+    - **Retired**: the legacy bare `operation-thumbnail` — retired on
+      staging and absent from the roster (terraform still names a prod-only
+      instance; contracts card `NMKIN5LE`).
+    - **Declared but not shipped** (no worker in the roster):
+      `operation-custom-luma` (planned per ticket I29),
+      `operation-audio-overlay` (planned per ticket I19),
+      `operation-audio-watermark` (planned per ticket I20),
       `operation-transform-image`, `operation-transform-video`,
       `operation-transform-document` (all planned per epic fhiWebI0 /
-      ADR-0026 — not yet shipped).
+      ADR-0026).
 
     **Message Types**
 
@@ -234,19 +249,19 @@ channels:
         ship per [`vKI0CFDu`](https://trello.com/c/vKI0CFDu);
         long-form video splits route via `processing_class` to the
         `split-video-fargate` worker — same OperationType, different
-        worker — now also `availability: beta` (worker deployed + wired
-        on staging, e2e-unproven, fan-out flag-gated dark))
+        worker — now also `availability: beta` (stays beta until a
+        production `customer_path` run is recorded in the prod verification log))
       - `operation_type = audio_watermark` -> `ops-audio-watermark`
-        queue (gated by `availability: planned` +
-        `required_tier: enterprise` per
-        [I20](https://trello.com/c/omiCq7Vn) — same 422 gating, plus
-        a 403 `feature_tier_restricted` for non-enterprise callers)
+        queue (gated by `availability: planned` per
+        [I20](https://trello.com/c/omiCq7Vn) — same 422 gating; no
+        tier gate since 2026-09-23)
       - `operation_type = render_variants` -> `ops-render-variants`
-        queue (gated by `availability: planned` until the worker +
-        SNS subscription ship per
+        queue (the `operation-render-variants` worker exists; gated by
+        `availability: planned` until its staging proof is recorded and it
+        is deployed to production, and
+        refused by the API until it gains an `OperationType` case — per
         [`w3EwzHYd`](https://trello.com/c/w3EwzHYd) /
-        [`MNuDYJaY`](https://trello.com/c/MNuDYJaY) — same
-        `feature_not_available` 422 gating)
+        [`MNuDYJaY`](https://trello.com/c/MNuDYJaY))
       - `operation_type = transform_image` -> `ops-transform-image` queue
       - `operation_type = transform_video` -> `ops-transform-video` queue
       - `operation_type = transform_document` -> `ops-transform-document`
@@ -1014,11 +1029,10 @@ channels:
       `operation_type = audio_watermark`. Single-input.
 
       Both mime_groups (`audio`, `video` — embed in video's audio
-      track) are `availability: planned` + `required_tier:
-      enterprise` per the operation schema; the API rejects workflow-
-      create with `feature_not_available` (422) until the Lambda
-      ships, plus 403 `feature_tier_restricted` for non-enterprise
-      callers, so traffic does not reach this queue today. Backed
+      track) are `availability: planned` per the operation schema;
+      the API rejects workflow-create with `feature_not_available`
+      (422) until the Lambda ships, so traffic does not reach this
+      queue today. Backed
       by the `operation-audio-watermark` Lambda (cross-repo follow-up;
       not yet shipped).
 
@@ -1053,8 +1067,8 @@ channels:
       `operations` SNS topic with filter `operation_type = render_variants`.
       Backed by the render_variants Lambda (`operation-render-variants`).
       No traffic reaches this queue while render_variants is
-      `availability: planned` (per ticket w3EwzHYd — same `feature_not_
-      available` 422 gating until the worker + this subscription ship).
+      `availability: planned` and the API has no `OperationType` case for
+      it (per ticket w3EwzHYd).
     bindings:
       sqs:
         queue:
@@ -1222,7 +1236,7 @@ channels:
       DLQ for failed audio_watermark operations (per ticket I20).
       Messages land here after 5 failed processing attempts. No
       traffic reaches this queue while audio_watermark is
-      `availability: planned` + `required_tier: enterprise`.
+      `availability: planned`.
     parameters:
       env:
         description: Environment (local, stg, prod)
@@ -2087,9 +2101,9 @@ operations:
       consumes split requests routed by `operation_type=split`. Its
       `audio` + short-form `video` paths are live on staging (lambdas
       #161 / [`vKI0CFDu`](https://trello.com/c/vKI0CFDu)); video
-      `long_form` (via `split-video-fargate`) is now also `beta` —
-      deployed + wired on staging but e2e-unproven, fan-out flag-gated
-      dark; the `image_gif` / `document_pdf` workers remain a cross-repo
+      `long_form` (via `split-video-fargate`) is now also `beta`, and
+      stays beta until a production `customer_path` run is recorded in the
+      prod verification log; the `image_gif` / `document_pdf` workers remain a cross-repo
       follow-up. Single-input —
       `media_group` derives from the input MIME prefix per the
       existing single-input rule. `availability: beta` for the `audio`
@@ -2218,11 +2232,9 @@ operations:
       The `operation-audio-watermark` Lambda (cross-repo follow-up —
       not yet shipped) consumes audio_watermark requests routed by
       `operation_type=audio_watermark`. Single-input. Both mime_groups
-      (`audio`, `video`) are `availability: planned` +
-      `required_tier: enterprise`; the API rejects workflow-create
-      with `feature_not_available` (422) until the Lambda ships, plus
-      403 `feature_tier_restricted` for non-enterprise callers, so
-      traffic does not reach this channel today.
+      (`audio`, `video`) are `availability: planned`; the API rejects
+      workflow-create with `feature_not_available` (422) until the
+      Lambda ships, so traffic does not reach this channel today.
       Per ADR-0004 + I20 (Trello omiCq7Vn).
     messages:
       - $ref: '#/channels/opsAudioWatermark/messages/operationRequest'
@@ -2239,14 +2251,14 @@ operations:
         bindingVersion: '0.2.0'
     summary: Process render_variants operation
     description: |
-      The `operation-render-variants` Lambda (cross-repo follow-up —
-      not yet shipped) consumes render_variants requests routed by
-      `operation_type=render_variants`. Single-input image fan-out (one
-      source image to N resized / re-encoded variants). `availability:
-      planned`; the API rejects workflow-create with
-      `feature_not_available` (422) until the Lambda + this subscription
-      ship, so traffic does not reach this channel today. Per ticket
-      w3EwzHYd.
+      The `operation-render-variants` Lambda consumes render_variants
+      requests routed by `operation_type=render_variants`. Single-input
+      image fan-out (one source image to N resized / re-encoded variants).
+      `availability: planned` until its staging proof is recorded (lambdas
+      `px2OKk42`) AND it is deployed to production — availability has no
+      environment axis. The API refuses a create naming `render_variants` until
+      it gains an `OperationType` case for it (api `uDW3k2Gw`), so no
+      traffic reaches this channel until then. Per ticket w3EwzHYd.
     messages:
       - $ref: '#/channels/opsRenderVariants/messages/operationRequest'
 
@@ -2646,9 +2658,8 @@ components:
           sub-type value for routing (see `OperationRequestAttributes`
           and the migration-window note below); the payload
           `operation_type` field always remains `thumbnail`.
-          `audio_watermark` is `availability: planned` +
-          `required_tier: enterprise` so workflow-create rejects with
-          422 + 403 today.
+          `audio_watermark` is `availability: planned` so
+          workflow-create rejects with 422 today.
         - Multi-input operations (merge, archive, image_watermark,
           custom_luma, audio_overlay, audio_to_video, video_watermark):
           use `sources` array. Merge additionally requires `output_type`.
@@ -3450,8 +3461,7 @@ components:
         - For `operation_type = audio_watermark`, `media_group` must
           equal `audio` or `video` (audio_watermark supports both —
           embedding into an audio asset or into a video's audio
-          track). Both mime_groups are `availability: planned` +
-          `required_tier: enterprise` per
+          track). Both mime_groups are `availability: planned` per
           [I20](https://trello.com/c/omiCq7Vn), so this constraint is
           contract-defined but not exercised today.
         - For `operation_type = audio_to_video`, `media_group` must
@@ -3887,9 +3897,11 @@ components:
         — both staging-proven 2026-07-07 (Form-B ADR-0006). Only
         `split.video.long_form` remains `availability: beta`
         (per [`rcwvUKhI`](https://trello.com/c/rcwvUKhI), worker
-        `split-video-fargate` deployed + wired on staging but NOT yet proven
-        end-to-end — first customer-path soak incomplete, speed-up unmeasured,
-        fan-out flag-gated dark). `audio_overlay` long-form
+        `split-video-fargate`) until a production `customer_path` run is
+        recorded in `availability/prod-verification-log.yaml` (worker-direct
+        staging runs are partial evidence only); fan-out admission is the API's
+        `LONGFORM_FANOUT_ADMISSION_ENABLED`, set per environment in
+        compression_terraform. `audio_overlay` long-form
         (reserve-name-only, no queue) is NOT yet produced and is therefore
         absent from this enum; it gets added when its publisher ships.
 
@@ -3935,6 +3947,19 @@ components:
           $ref: '#/components/schemas/LongFormOperationType'
         processing_class:
           $ref: '#/components/schemas/LongFormProcessingClass'
+        traceparent:
+          type: string
+          pattern: '^00-(?!0{32})[0-9a-f]{32}-(?!0{16})[0-9a-f]{16}-[0-9a-f]{2}$'
+          description: |
+            OPTIONAL W3C Trace Context `traceparent` (version `00`) of the
+            producer's span, so the long-form task joins the producer's trace.
+            The launcher forwards a well-formed value to the Fargate task as the
+            environment variable `GISL_CL_PARENT_TRACEPARENT`. An all-zero
+            trace-id or parent-id is invalid (W3C), and so is any other version.
+            A malformed or absent value is IGNORED: the job runs without the
+            parent trace and never fails for it. Producers: the API's long-form
+            publisher and lambdas' republish. Ticket JiqICJWX (terraform #502).
+          example: "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
 
     SourceEntry:
       type: object
@@ -4168,9 +4193,13 @@ components:
         2. **A `completed` never supersedes another `completed`.** Keep the
            first; a second is a duplicate delivery of the same outcome.
         3. **Two `failed` results are NOT ordered by this contract.** Keep the
-           first `error_code` and record that another arrived. See the limit
-           below — this is the case the contract cannot yet decide, and saying
-           so is deliberate.
+           first `error_code` and record that another arrived. `attempt`
+           (below) does NOT order them: it is per SQS message, and a DLQ
+           redrive starts a new message.
+        4. **A consumer MUST surface a second terminal, never drop it
+           silently** — count it, log it or alarm on it. Rules 1–3 decide the
+           STATE; a producer emitting contradictory terminals must still be
+           visible.
 
         ### Supersession replaces the WHOLE result, not just the status
 
@@ -4210,12 +4239,13 @@ components:
         and by nothing else. Using metrics to arbitrate would make the answer
         depend on how long a machine happened to take.
 
-        ### 🔴 THE MISSING FIELD, RECORDED AS A FINDING
+        ### 🔴 THE MISSING ORDERING FIELD, RECORDED AS A FINDING
 
         **There is no producer-stamped ordering field on `OperationResult`
-        today.** No attempt counter, no producer timestamp, no sequence number —
-        `job_id`, `operation_id`, `operation_type`, `status` and the payload, and
-        nothing that says *which invocation produced this*.
+        today.** No durable per-operation counter, no producer timestamp, no
+        sequence number. The optional `attempt` (declared 2026-09-25, below)
+        says which DELIVERY of one SQS message produced a result; it is not
+        durable per `operation_id`, so it is diagnostic and NOT an ordering key.
 
         That absence is why rule 3 exists: **two failures cannot be ordered, and
         the contract does not pretend otherwise.** Telling consumers to fall back
@@ -4223,17 +4253,33 @@ components:
         transport property, and a rule that reads it as producer intent is wrong
         in a way no consumer can detect.
 
-        **The field this needs is an `attempt` counter** — monotonically
-        increasing per `operation_id`, stamped by the producer — because it does
-        not depend on a clock, and two invocations are tens of minutes apart in
-        wall time (27–81 minutes of visibility timeout, measured above) but
-        ADJACENT in attempt number. **Not declared here**: the producer
-        must confirm it can supply it (SQS exposes `ApproximateReceiveCount` to
-        the handler, which is a candidate, not a decision). Specifying a field
-        the producer has not agreed to emit is how a contract acquires a
-        promise nothing keeps.
-
-        Once `attempt` exists, higher wins, and it subsumes rules 1–3.
+        **The field this needs is an `attempt` counter** — per `operation_id`,
+        stamped by the producer — because it does not depend on a clock, and
+        two invocations are tens of minutes apart in wall time (27–81 minutes
+        of visibility timeout, measured above) but ADJACENT in attempt number.
+
+        **`attempt` is DECLARED (2026-09-25, card `HPXNdNqp`), OPTIONAL, and
+        DIAGNOSTIC.** `compression_lambdas` confirmed both paths can emit it:
+        the Lambda path from the SQS record's `ApproximateReceiveCount`
+        (1-based), the Fargate path from `GISL_CL_JOB_ATTEMPT` + 1. It is a
+        HINT for the log line rule 4 requires: two terminals with DIFFERENT
+        values came from different deliveries. EQUAL values prove nothing (a
+        launcher redelivery repeats a value, and the terminal event itself can
+        be delivered twice), so a consumer cannot use it to classify a pair
+        as harmless.
+
+        ⛔ **It is NOT an ordering key, and no rule above reads it.** Its
+        meaning depends on the path, so values from different paths or
+        across a redrive are not comparable:
+        - **Lambda:** the SQS receive count of one message. A DLQ redrive
+          makes a NEW message whose count starts again, so a later
+          invocation can carry a LOWER value.
+        - **Fargate:** a retry counter carried in the message body, so it
+          survives a redrive, but a launcher redelivery of the same message
+          repeats the value. Ordering two faileds needs a counter that is durable
+        per `operation_id` across redrives; none exists, so rule 3 stands.
+        (An earlier draft of this change let `attempt` order faileds; codex
+        review found the redrive reset, and it was withdrawn before merge.)
 
         ### 🔴 THE PARENT IS NOT COVERED BY THIS RULE, AND THAT IS A GAP
 
@@ -4353,6 +4399,17 @@ components:
           $ref: '#/components/schemas/OperationType'
         status:
           $ref: '#/components/schemas/ResultStatus'
+        attempt:
+          type: integer
+          minimum: 1
+          description: |
+            OPTIONAL, DIAGNOSTIC, 1-based. Which attempt produced this result,
+            with path-specific meaning: on Lambda the SQS receive count (it
+            restarts after a DLQ redrive), on Fargate a retry counter carried
+            in the message (it survives a redrive but repeats on a launcher
+            redelivery). MUST NOT be used to order results; see "THE MISSING
+            ORDERING FIELD" above. Card `HPXNdNqp`.
+          example: 1
 
         # Shared success field (both single- and multi-output)
         output_bucket:
@@ -4471,6 +4528,10 @@ components:
           type: string
           description: Human-readable error message (failed only)
           example: "Unsupported file format: image/bmp"
+        message_key:
+          $ref: '#/components/schemas/OperationMessageKey'
+        message_params:
+          $ref: '#/components/schemas/OperationMessageParams'
         is_retryable:
           type: boolean
           description: Whether the operation could be retried (failed only)
@@ -4482,6 +4543,34 @@ components:
           description: Progress percentage when the operation failed (failed only)
           example: 10
 
+    OperationMessageKey:
+      type: string
+      x-string-vocabulary: open
+      pattern: '^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$'
+      description: |
+        Stable, never-localised key REFINING `error_code` on a failed
+        operation, so a client can show specific, localised copy (e.g.
+        `thumbnail.epub.no_cover`). OPTIONAL, failed only. Every value is
+        declared, with the codes it may accompany and its parameters, in
+        `schemas/operation-message-keys.yaml` (the one registry). A client
+        that does not know a key, or receives one whose registry
+        `error_codes` do not include this `error_code`, ignores the key and
+        falls back to the `error_code` headline;
+        retry is still decided from the code. Ticket U7GQhjhX.
+      example: "thumbnail.epub.no_cover"
+
+    OperationMessageParams:
+      type: object
+      additionalProperties:
+        type: [string, integer, number, boolean]
+      description: |
+        Interpolation values for `message_key`, named and typed in
+        `schemas/operation-message-keys.yaml`. JSON scalars only (string,
+        integer, number, boolean) — no nested objects. Absent when the key
+        declares no parameters (`params: {}`), and carries exactly the
+        registry's parameters otherwise. Never carries free-text
+        diagnostics; those stay in `error_message`.
+
     OperationResultMetadata:
       type: object
       additionalProperties: false
@@ -4492,7 +4581,10 @@ components:
         whitelist projection on the read side), never the raw bag, so
         internal diagnostics never leak. New keys are **additive named
         cuts**. Twin of the OpenAPI `OperationResultMetadata` (wire ↔ read
-        parity — same named-prop shape). Distinct from the deliverable
+        parity — same named-prop shape), except that the REST twin also
+        serves `already_optimal` / `estimated_saving_pct`, projected from
+        `OperationMetrics` (the worker emits them there). Distinct from the
+        deliverable
         output (`output_key` / `outputs[]`): small per-operation metadata,
         not the file. Per ticket EurbZLMH (B1).
       properties:
@@ -4581,6 +4673,10 @@ components:
             selected pages (`1,2,3,4,5,8`) — gapless ONLY for a full conversion.
             Mutually exclusive with `position`. Normative semantics:
             ADR-0009 §D2.
+            For a `split` of a PDF with `mode: page_groups`, each output holds
+            a GROUP of pages and `page_index` is the group's FIRST source
+            page; the group covers `page_index` .. `page_index + page_groups
+            - 1`, and the last group ends at the document's last page.
           example: 1
         position:
           type: integer
@@ -4671,10 +4767,11 @@ components:
           format: date-time
         reason:
           type: string
+          x-string-vocabulary: advisory
           description: |
             Optional advisory reason. Free-form string; not enumerated.
             Examples: `all jobs completed successfully`,
-            `next reservation exceeded available_credits` (when
+            `no active reservation at a publish boundary` (when
             transitioning to `paused_insufficient_credits`),
             `caller requested cancel`, `paused_insufficient_credits
             past expires_at`, `dispatch timeout`.
@@ -4698,6 +4795,14 @@ components:
         Operation-specific metrics. Content varies by operation type.
         All metrics include duration_ms. Compression includes size/ratio.
         Merge includes input count. Archive includes file count and total size.
+      # estimated_saving_pct only means something on an already-optimal result.
+      if:
+        required: [estimated_saving_pct]
+      then:
+        required: [already_optimal]
+        properties:
+          already_optimal:
+            const: true
       properties:
         original_size_bytes:
           type: integer
@@ -4757,6 +4862,7 @@ components:
           example: 0.9501
         quality_metric:
           type: string
+          x-string-vocabulary: advisory
           description: |
             The perceptual metric that produced `measured_quality` — a FREE-FORM
             string (NOT an enum) so the worker can change or upgrade the metric
@@ -4786,15 +4892,16 @@ components:
           $ref: '#/components/schemas/ReEncodeDecision'
         re_encode_reason:
           type: string
+          x-string-vocabulary: advisory
           description: |
             Advisory explanation for `re_encode_decision` (e.g.
-            `all_inputs_compatible`, `explicit_always_mode`,
-            `input_codec_mismatch`, `input_framerate_mismatch`).
+            `compatible_inputs`, `always_mode_forces_re_encode`,
+            `input_video_codec_mismatch`, `long_form_stream_copy`).
             Free-form string — not an enum — so the Lambda can emit
             human-readable diagnostics that evolve without contract
             churn (compatibility-probe algorithm stays opaque per
             plan v5 §F8.2). Per ticket I16-CONS.
-          example: input_codec_mismatch
+          example: input_video_codec_mismatch
         # COGS AWS-cost metrics (ticket 2cacyYNE) — the real per-op AWS-cost
         # inputs the API's COGS record consumes (emitted by lambdas yJe65EMa,
         # surfaced by api MWssQbFS), replacing the wall-clock/bytes COGS proxy
@@ -4848,6 +4955,35 @@ components:
             `memory_mb`. Present for long-form (Fargate) ops once the worker
             emits it.
           example: 45000
+        # Already-optimal passthrough (roNRMilt, FE lZVjFFTA). A compress that
+        # does not shrink the file (or is declined before encoding because the
+        # source is already efficient) is a SUCCESS returning the ORIGINAL
+        # bytes with compression_ratio 1.0 — never a failure. These keys let
+        # the API tell the user WHY. The API projects both onto the REST
+        # `OperationResultMetadata` (same names); diagnostic evidence such as
+        # `source_bpp` / `threshold_bpp` stays wire-only and is never served.
+        already_optimal:
+          type: boolean
+          description: |
+            `true` when the stored output IS the original input, unchanged,
+            because compressing it would not have made it smaller. Set by the
+            compression processor itself, never by an individual worker's
+            extras. Absent or `false` on an ordinary compression; consumers
+            treat the two the same.
+          example: true
+        estimated_saving_pct:
+          type: number
+          minimum: 0
+          maximum: 100
+          description: |
+            OPTIONAL, only with `already_optimal: true`, and only when the
+            worker declined BEFORE encoding on an efficiency estimate: the
+            worker's estimate of how much smaller, as a percentage of the input
+            bytes, a re-encode would have made the file. Absent when the worker
+            encoded and measured instead (then the measured result, not an
+            estimate, is why it declined). An estimate, not a promise — do not
+            present it as a guaranteed figure.
+          example: 3.5
 
     # ============================================
     # UPLOAD PROBE PAYLOADS (per ticket vBlEurU7)
@@ -5226,6 +5362,84 @@ components:
             contract on the OpenAPI side; the prober reports the
             page-1 horizontal DPI when the document declares it,
             otherwise omits the field.
+        # STREAM TOPOLOGY + CONCAT ATTRIBUTES (lGeDDi4V, for MjzzPCWt): what the
+        # API needs to refuse a non-concat-uniform long-form merge at create.
+        # Defined with the SAME semantics as compression_lambdas' merge gate
+        # (re_encode.rs TopologyCounts / classify_non_uniform), or the
+        # create-time refusal and the worker gate would disagree. All OPTIONAL:
+        # a prober that has not emitted them yet simply omits them.
+        video_stream_count:
+          type: integer
+          minimum: 0
+          description: Streams whose ffprobe `codec_type` is `video`.
+        audio_stream_count:
+          type: integer
+          minimum: 0
+          description: Streams whose ffprobe `codec_type` is `audio`.
+        other_stream_count:
+          type: integer
+          minimum: 0
+          description: |
+            Every other stream: `codec_type` subtitle, data, attachment,
+            or unknown — the worker gate's `other` bucket.
+        stream_order:
+          type: array
+          items:
+            type: string
+            enum: [video, audio, other]
+          description: |
+            Per stream index, in container order, its kind (`other` as
+            above). Two inputs are order-compatible iff these are equal.
+        r_frame_rate:
+          type: string
+          pattern: '^[0-9]+/[0-9]+$'
+          description: |
+            ffprobe `r_frame_rate` of the video stream, raw (`30000/1001`;
+            ffprobe's `0/0` is carried as-is and means UNUSABLE). NOT the
+            average rate in `fps`, which drifts between concat-uniform
+            clips. **The worker's frame-rate rule, which a create-time
+            comparison must reproduce exactly:** (1) `r_frame_rate` and
+            `avg_frame_rate` must each be present on all inputs or absent
+            on all (else `input_metadata_inconsistent`); (2) if every
+            input has a usable `r_frame_rate`, compare those as parsed
+            rationals; (3) otherwise compare `avg_frame_rate` as parsed
+            rationals. Both comparisons are by VALUE (`60/2` equals `30/1`),
+            never by string.
+        avg_frame_rate:
+          type: string
+          pattern: '^[0-9]+/[0-9]+$'
+          description: |
+            ffprobe `avg_frame_rate` of the video stream, raw rational.
+            Presence-checked always; compared only as the fallback in the
+            `r_frame_rate` rule. `fps` is its lossy numeric form.
+        pix_fmt:
+          type: string
+          x-string-vocabulary: none
+          description: ffprobe `pix_fmt` of the video stream (e.g. `yuv420p`).
+        sar:
+          type: string
+          pattern: '^[0-9]+:[0-9]+$'
+          description: Sample aspect ratio of the video stream (`1:1`).
+        video_time_base:
+          type: string
+          pattern: '^[0-9]+/[0-9]+$'
+          description: ffprobe `time_base` of the video stream (`1/30000`).
+        audio_time_base:
+          type: string
+          pattern: '^[0-9]+/[0-9]+$'
+          description: ffprobe `time_base` of the audio stream (`1/48000`).
+        codec_tag:
+          type: string
+          x-string-vocabulary: none
+          description: ffprobe `codec_tag_string` of the video stream (e.g. `avc1`).
+        profile:
+          type: string
+          x-string-vocabulary: none
+          description: ffprobe `profile` of the video stream (e.g. `High`).
+        sample_fmt:
+          type: string
+          x-string-vocabulary: none
+          description: ffprobe `sample_fmt` of the audio stream (e.g. `fltp`).
         probed_at:
           type: string
           format: date-time
@@ -5241,6 +5455,15 @@ components:
     OperationType:
       type: string
       description: |
+        ⚠️ **HOMONYM: this is NOT the `OperationType` in `openapi/api.yaml`.**
+        That one is the CREATE surface (every operation a caller may
+        request, incl. `passthrough` and the per-media thumbnail sub-types);
+        this one is the narrower PAYLOAD vocabulary. Same name, different
+        membership, both emitted by the SDK generators — the import path is
+        the only distinguisher. Not renamed: a rename breaks every consumer
+        of either generated type (bFy3zo5Y). The subset relation is asserted
+        in `schemas/cross-document-enums.yaml`.
+
         Operation type as carried inside the message **payload** body. This
         enum is deliberately narrower than the SNS `operation_type`
         MessageAttribute: the attribute enum permits per-media thumbnail
@@ -5321,11 +5544,9 @@ components:
           into an audio asset (or a video's audio track) — Cinavia /
           Resemble PerTh territory. Single-input. Both mime_groups
           (`audio`, `video` — embed in video's audio track) are
-          `availability: planned` + `required_tier: enterprise` per
-          the operation schema; the API rejects workflow-create with
-          `feature_not_available` (422) + `feature_tier_restricted`
-          (403) until the Lambda ships, so traffic does not reach SNS
-          today. Pairs with `POST /api/audio-watermark/decode` for
+          `availability: planned` per the operation schema; the API
+          rejects workflow-create with `feature_not_available` (422)
+          until the Lambda ships, so traffic does not reach SNS today. Pairs with `POST /api/audio-watermark/decode` for
           own-watermarks-only extraction. Per ADR-0004 + I20 (Trello
           omiCq7Vn).
         - `audio_to_video`: Produce a video from an audio input plus an
@@ -5379,8 +5600,8 @@ components:
           operation-specific conditional needed). `availability: beta`
           for the `audio` and `video` mime_groups — video activates
           BOTH classes (`short_form` + `long_form` beta; long-form
-          deployed + wired on staging but e2e-unproven, fan-out
-          flag-gated dark). `image_gif` / `document_pdf` stay
+          stays beta until a production `customer_path` run is recorded
+          in the prod verification log). `image_gif` / `document_pdf` stay
           `planned`. Routes via `operation_type=split` to `ops-split`.
           Per ADR-0004 + ADR-0014
           ([`vKI0CFDu`](https://trello.com/c/vKI0CFDu)).
@@ -5534,12 +5755,23 @@ components:
     ReEncodeDecision:
       type: string
       description: |
-        Path chosen for `merge.video` when `re_encode_mode=auto`.
-        Server reports the actual path so callers can see why
-        `auto` took the slow path. Absent for non-`merge.video`
-        operations and for `merge.video` when `re_encode_mode` is
-        `always` or `never` (path was caller-fixed). Per ticket
-        I16-CONS (Trello 7nCZXEru). Workflow-create-time surface
+        Path the worker actually took for a SUCCESSFUL `merge.video`,
+        reported in EVERY `re_encode_mode`: `always` reports `re_encode`;
+        `never` reports `stream_copy`; `auto` reports whichever path it
+        chose. Absent for non-`merge.video` operations and on any failed
+        operation, even one that carries other metrics such as sizes or
+        cost figures (for example a `never`
+        request whose inputs need a re-encode, or a long-form merge the
+        uniformity gate refuses before the path is decided). Per ticket I16-CONS (Trello
+        7nCZXEru).
+
+        ⚠️ An earlier revision said the field was ABSENT under `always` /
+        `never`. The worker never behaved that way (it reports the path
+        in every mode), and the same contract listed an `always`-mode
+        reason as an example, so the text contradicted itself. The
+        worker's behaviour is the canonical one (ruled 2026-09-24 on
+        compression_e2e's report); a consumer MUST NOT assert absence
+        on a successful merge under a caller-fixed mode. Workflow-create-time surface
         on `processing_plan.jobs[]` lands with I15-CONS
         (Trello YZpBKzOM).
 
@@ -5714,6 +5946,9 @@ components:
         error, not a statement about how many times the platform has already
         tried. See `OperationResult` for the supersession rule.
 
+        The retryable set below is also machine-readable as `x-retryable` on
+        this schema; read that rather than parsing this list.
+
         **Retryable errors** (transient — re-submitting may succeed):
         - s3_download_failed: Source file download failed
         - s3_upload_failed: Output file upload failed
@@ -5758,7 +5993,34 @@ components:
           emits it** — the API derives it from job state, so do not look for the worker
           that produces it. Non-retryable: retrying an operation that never ran is
           meaningless; the caller re-submits the workflow.
+        - processing_limit_exceeded: A processing tool was killed at its configured
+          processing budget (e.g. an encoder stopped at its time cap) for THIS
+          input. Deterministic: the same input with the same options hits the same
+          budget again, so it is **non-retryable** — distinct from `timeout`, which
+          is transient and retryable. Added 2026-09-23 (card `9BWwPcbA`, hub ruling
+          option (c)): retry stays decided by the CODE, never by a wire boolean
+          overriding it. **Rollout order:** declared here first; the API maps it
+          non-retryable (an API that does not yet know it degrades an unknown code
+          to "not retried", so a slipped order fails safe); workers emit it only
+          after that API release is live. Until then a cap kill still arrives as
+          `timeout`.
+          **Emit it ONLY for a budget that is a function of the input**, i.e. a cap
+          the worker sets from the input (duration, resolution, pixels) whose
+          exhaustion would recur on any healthy host. A wall-clock deadline that
+          may have been exhausted by transient conditions (contention, a slow
+          download, the Lambda invocation timeout) is `timeout`, NOT this code.
+          When the worker cannot tell which it hit, it emits `timeout`: a wrong
+          `timeout` costs one retry, a wrong `processing_limit_exceeded` fails a
+          job that would have succeeded.
         - unknown: Unclassified error
+      # Machine-readable twin of the "Retryable errors" list above, for
+      # consumers (api) that must agree with it. A test asserts the two are
+      # EQUAL and that every enum value is in exactly one of the two lists.
+      x-retryable:
+        - s3_download_failed
+        - s3_upload_failed
+        - out_of_memory
+        - timeout
       enum:
         - s3_download_failed
         - s3_upload_failed
@@ -5776,4 +6038,5 @@ components:
         - invalid_request
         - input_too_large
         - never_started
+        - processing_limit_exceeded
         - unknown