@giveitsmaller/contracts 0.73.0 → 0.76.0

package/README.md

@@ -5,8 +5,8 @@
 
 | | |
 |---|---|
-| Package version | `0.73.0` |
-| Generated from spec | **`v2.208.0`** |
+| Package version | `0.76.0` |
+| Generated from spec | **`v2.211.0`** |
 
 ## Two version lines, and they are not comparable
 

package/accepted-options/accepted-options.json

@@ -1214,5 +1214,5 @@
       }
     }
   },
-  "schema_version": "2.208.0"
+  "schema_version": "2.211.0"
 }

package/accepted-options/image-output-routes.json

@@ -246,5 +246,5 @@
       "source_op": "compress"
     }
   },
-  "schema_version": "2.208.0"
+  "schema_version": "2.211.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
@@ -4471,6 +4496,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 +4511,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 +4549,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:
@@ -4671,6 +4731,7 @@ 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`,
@@ -4698,6 +4759,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 +4826,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,6 +4856,7 @@ 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`,
@@ -4848,6 +4919,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)
@@ -5241,6 +5341,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 +5430,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 +5486,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)).
@@ -5714,6 +5821,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 +5868,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 +5913,5 @@ components:
         - invalid_request
         - input_too_large
         - never_started
+        - processing_limit_exceeded
         - unknown