@giveitsmaller/contracts 0.17.0 → 0.19.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.66.0
+  version: 2.73.0
   contact:
     name: API Support
 
@@ -168,7 +168,7 @@ paths:
                   mime_type: "image/jpeg"
                   size_bytes: 2457600
                   constraints_applied:
-                    max_size_bytes: 104857600
+                    max_size_bytes: 10485760
                     max_duration_seconds: null
                     processing_class_pre_assignment: short_form
         '400':
@@ -232,7 +232,7 @@ paths:
                 $ref: '#/components/schemas/ErrorEnvelope'
               example:
                 success: false
-                error: "File size exceeds maximum allowed (500MB)"
+                error: "File size exceeds maximum allowed (100 GiB)"
         '415':
           description: |
             Unsupported file type at the contract level (no tier permits
@@ -280,13 +280,13 @@ paths:
                     upload_duration_exceeds_tier: '#/components/schemas/UploadDurationExceedsTierResponse'
               examples:
                 size_exceeds_tier:
-                  summary: Free-tier caller uploads a 200MB file (cap is 100MB)
+                  summary: Free-tier caller uploads a 200MB file (cap is 10 MiB)
                   value:
                     success: false
-                    error: "Upload exceeds size cap for free tier (max 100MB; pro permits up to 5GB)."
+                    error: "Upload exceeds size cap for free tier (max 10 MiB; pro permits up to 5 GiB)."
                     error_type: "upload_size_exceeds_tier"
                     current_tier: "free"
-                    max_size_bytes: 104857600
+                    max_size_bytes: 10485760
                     required_tier: "pro"
                 duration_exceeds_tier:
                   summary: Pro-tier caller uploads a 30-minute video (cap is 5min on short_form)
@@ -4465,6 +4465,100 @@ paths:
               schema:
                 $ref: '#/components/schemas/ErrorEnvelope'
 
+  # ============================================
+  # ACCOUNT LIMITS ENDPOINT
+  # ============================================
+
+  /api/v2/account/limits:
+    get:
+      summary: Get the caller's effective account limits
+      description: |
+        Returns the authed caller's **effective** (override-aware) account
+        limits. `effective = per-account override ?? tier_default`. Until a
+        per-account override is set, every limit's `effective` equals its
+        `tier_default` and `overridden` is `false`.
+
+        These are **request-level tier-quota** limits — the per-file upload
+        cap (`UserTier.maxFileSizeBytes`) and the merge combined-size band.
+        They are **distinct** from the per-operation **processing-class**
+        band caps in each operation schema's `processing_class.constraints`
+        (which `GET /api/operations/schema` advertises account-agnostically
+        as tier DEFAULTS). This endpoint is the account-scoped,
+        override-aware **effective** view — the pre-upload cap surface
+        previously missing (tickets
+        [`zcRRQHVC`](https://trello.com/c/zcRRQHVC) +
+        [`uKsFzORi`](https://trello.com/c/uKsFzORi)).
+
+        v1 keys: `max_upload_size_bytes` (per-file upload cap) and
+        `max_total_input_size_bytes` (merge combined-size band). SDKs/FE
+        gate the upload affordance on
+        `limits.max_upload_size_bytes.effective`, surface
+        `tier_default` for upgrade-prompt copy, and show an
+        "extended limit" affordance when `overridden` is `true`.
+
+        Per ticket [`ViRVI2MP`](https://trello.com/c/ViRVI2MP).
+      operationId: getAccountLimits
+      security: [{bearerAuth: []}, {sessionAuth: []}]  # required (identity-scoped to caller's account)
+      x-identity-scoped: true  # caller's account limits — per ADR-0016 §D4 sample
+      tags:
+        - Billing
+      responses:
+        '200':
+          description: Effective account-limits snapshot
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AccountLimitsSuccessEnvelope'
+              examples:
+                free_tier_defaults:
+                  summary: Free tier, no overrides (effective == tier_default)
+                  value:
+                    success: true
+                    data:
+                      tier: free
+                      limits:
+                        max_upload_size_bytes:
+                          effective: 10485760
+                          tier_default: 10485760
+                          overridden: false
+                        max_total_input_size_bytes:
+                          effective: 1073741824
+                          tier_default: 1073741824
+                          overridden: false
+                enterprise_with_upload_override:
+                  summary: Enterprise tier with a raised per-account upload override
+                  value:
+                    success: true
+                    data:
+                      tier: enterprise
+                      limits:
+                        max_upload_size_bytes:
+                          effective: 128849018880
+                          tier_default: 107374182400
+                          overridden: true
+                        max_total_input_size_bytes:
+                          effective: 120000000000
+                          tier_default: 120000000000
+                          overridden: false
+        '401':
+          description: Authentication required.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '429':
+          description: Rate limit exceeded
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '500':
+          description: Internal server error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+
   # ============================================
   # CONTACT ENDPOINT
   # ============================================
@@ -5645,6 +5739,98 @@ components:
         data:
           $ref: '#/components/schemas/CreditsBalanceResponse'
 
+    AccountLimitsSuccessEnvelope:
+      type: object
+      additionalProperties: false
+      required:
+        - success
+        - data
+      properties:
+        success:
+          type: boolean
+          enum: [true]
+        data:
+          $ref: '#/components/schemas/AccountLimits'
+
+    AccountLimits:
+      type: object
+      # Open payload (response data target stays open for additive evolution —
+      # the success-envelope tightening convention; new top-level fields may
+      # be added without a breaking change).
+      description: |
+        The caller's effective (override-aware) account limits
+        (`GET /api/v2/account/limits`, ticket
+        [`ViRVI2MP`](https://trello.com/c/ViRVI2MP)). `tier` is the caller's
+        subscription tier; `limits` maps a fixed v1 key set to each limit's
+        effective / tier-default / override state.
+
+        **v1 limit keys** (both REQUIRED):
+        - `max_upload_size_bytes`: the per-FILE upload cap
+          (`UserTier.maxFileSizeBytes` — the request-level tier quota the
+          upload endpoints enforce). **Distinct** from the per-operation
+          processing ceiling `max_input_size_bytes` in operation schemas
+          (different axis AND number). Tier defaults: free 10 MiB, pro 5 GiB,
+          enterprise 100 GiB.
+        - `max_total_input_size_bytes`: the effective merge combined-input
+          size cap (the summed-inputs ceiling). Same key as the
+          operation-schema merge band; the band is processing-class +
+          tier dependent (`short_form_concat` baseline 1 GiB; the
+          `long_form_re_encode` band where the tier permits it — Pro 5 GB,
+          Enterprise 120 GB). The server resolves the effective value for
+          the caller.
+      required:
+        - tier
+        - limits
+      properties:
+        tier:
+          $ref: '#/components/schemas/UserTier'
+        limits:
+          type: object
+          # Typed-open: the v1 keys below are REQUIRED + frozen, but future
+          # limit keys may be added additively (each an AccountLimitEntry) —
+          # forward-compatible per the open-payload convention.
+          additionalProperties:
+            $ref: '#/components/schemas/AccountLimitEntry'
+          required:
+            - max_upload_size_bytes
+            - max_total_input_size_bytes
+          properties:
+            max_upload_size_bytes:
+              $ref: '#/components/schemas/AccountLimitEntry'
+            max_total_input_size_bytes:
+              $ref: '#/components/schemas/AccountLimitEntry'
+
+    AccountLimitEntry:
+      type: object
+      additionalProperties: false
+      description: |
+        One account limit: the effective value (override ?? tier default),
+        the tier default, and whether a per-account override is active. The
+        override mechanism / store is NOT exposed — only the resolved
+        numbers plus the `overridden` flag.
+      required:
+        - effective
+        - tier_default
+        - overridden
+      properties:
+        effective:
+          type: integer
+          minimum: 1
+          description: |
+            The cap in force for this account, in bytes
+            (`override ?? tier_default`).
+        tier_default:
+          type: integer
+          minimum: 1
+          description: |
+            The tier's default cap for this limit, in bytes (already public
+            via the tier model).
+        overridden:
+          type: boolean
+          description: |
+            True iff a per-account override is active (i.e. `effective`
+            comes from an override rather than the tier default).
+
     CreditTransaction:
       type: object
       description: |
@@ -6263,13 +6449,20 @@ components:
 
         Tier capability summary (informational; canonical limits are
         enforced server-side per `UserTier.php`):
-        - `free`: 10 MB max upload; image MIMEs only; 50 monthly credits;
+        - `free`: 10 MiB max upload; image MIMEs only; 50 monthly credits;
           0 overdraft; 1× rate-limit baseline.
-        - `pro`: 500 MB max upload; image + video + document MIMEs; 1000
+        - `pro`: 5 GiB max upload; image + video + document MIMEs; 1000
           monthly credits; 200 overdraft; 5× rate-limit.
-        - `enterprise`: 2 GB max upload; image + video + document + audio
+        - `enterprise`: 100 GiB max upload; image + video + document + audio
           MIMEs; 10000 monthly credits; 5000 overdraft; 20× rate-limit.
 
+        The "max upload" figures are the per-file upload cap
+        (`UserTier.maxFileSizeBytes`) — the request-level tier quota,
+        surfaced override-aware via `GET /api/v2/account/limits`
+        (`max_upload_size_bytes`). They are DISTINCT from the per-operation
+        processing-class band caps (`processing_class.constraints` in the
+        operation schemas; e.g. the 120 GB Enterprise merge combined band).
+
         Used by `TierRestrictionResponse.current_tier` /
         `TierRestrictionResponse.required_tier` and by
         `FeatureViolation.required_tier`.
@@ -6920,7 +7113,7 @@ components:
         - audio_to_video: Produce a video from an audio input plus an OPTIONAL still image overlay. Multi-input role-based with the first OPTIONAL role on the contract (`role: base` audio required, `role: overlay` image 0..1 — see `per_role_cardinality`). When overlay is omitted, the video uses a solid background colour. `availability: beta` (Wave A — Lambda backend live; opt-in, MUST NOT return `feature_not_available`; may change with notice). Per ticket [`SlluxMBN`](https://trello.com/c/SlluxMBN) + ADR-0015 (introduces `per_role_cardinality` vocab).
         - video_watermark: Apply an image overlay onto a base video via FFmpeg's `overlay` filter. Multi-input role-based (`role: base` video + `role: overlay` image, exactly one of each per `per_role_cardinality`). Re-encode required; audio stream-copy passthrough. Distinct from `image_watermark` (pure-Rust/image-only). `availability: beta` (Wave A — Lambda backend live; opt-in, MUST NOT 422; `short_form` is beta, `long_form` stays `planned` — no live Fargate worker; `multi_overlay_stack` stays `planned`). Per ticket [`4NrRPCgh`](https://trello.com/c/4NrRPCgh) + ADR-0013.
         - video_text_watermark: Render a text overlay onto a base video via FFmpeg's `drawtext` filter. Single-input — text and styling in options. Same `watermark_mode` (single/tiled), anchor + margin vocab as `text_watermark`. Re-encode required; audio stream-copy passthrough. `availability: planned`; dispatch returns `feature_not_available` (422) until Lambda ships. Per ticket [`4NrRPCgh`](https://trello.com/c/4NrRPCgh) + ADR-0013.
-        - split: Fan one input file into N outputs across GIF / PDF / audio / video MIME families. Single-input per-mime-group catalog (mirrors merge/convert): GIF uses `frame_range` (REQUIRED) + `output_format`; PDF uses `page_range` OR `page_groups` (mutually exclusive); audio + video use a `mode` discriminator (interval/count/cut_points) + numeric-seconds wire format + `precision` flag (fast/exact). 200-output hard cap per ADR-0009 §D5 with per-mode preflight math; output naming `output-001..output-200`. Long-form video routes to a separate `split-video-fargate` worker via `processing_class`. `availability: beta` for the `audio` and `video` mime_groups (workers live on staging — shape-stable + opt-in, MUST NOT 422); video activates BOTH classes (`video.processing_class.short_form: beta` AND `long_form: beta` — `split-video-fargate` proven on staging per [`rcwvUKhI`](https://trello.com/c/rcwvUKhI)). The `image_gif` and `document_pdf` mime_groups stay `availability: planned` and dispatch returns `feature_not_available` (422) until their workers ship. Per ticket [`vKI0CFDu`](https://trello.com/c/vKI0CFDu) + ADR-0014.
+        - split: Fan one input file into N outputs across GIF / PDF / audio / video MIME families. Single-input per-mime-group catalog (mirrors merge/convert): GIF uses `frame_range` (REQUIRED) + `output_format`; PDF uses `page_range` OR `page_groups` (mutually exclusive); audio + video use a `mode` discriminator (interval/count/cut_points) + numeric-seconds wire format + `precision` flag (fast/exact). 200-output hard cap per ADR-0009 §D5 with per-mode preflight math; output naming `output-001..output-200`. Long-form video routes to a separate `split-video-fargate` worker via `processing_class`. `availability: beta` for the `audio` and `video` mime_groups (workers live on staging — shape-stable + opt-in, MUST NOT 422); video activates BOTH classes (`video.processing_class.short_form: beta` AND `long_form: beta` — `split-video-fargate` deployed + wired on staging but NOT yet proven end-to-end per [`rcwvUKhI`](https://trello.com/c/rcwvUKhI); the first customer-path soak has not completed, the 4GB+ speed-up is unmeasured, and the long-form fan-out is flag-gated dark). The `image_gif` and `document_pdf` mime_groups stay `availability: planned` and dispatch returns `feature_not_available` (422) until their workers ship. Per ticket [`vKI0CFDu`](https://trello.com/c/vKI0CFDu) + ADR-0014.
         - passthrough: Inert lossless source operation. A single-input source job whose SOLE operation is `passthrough` emits its source bytes UNCHANGED — no compression, no Lambda. The API self-completes the job at publish (terminal output = the upload `{bucket, key}` unchanged). Its purpose is to feed an uploaded file into a multi-input operation LOSSLESSLY: because `JobInputV2.source` is narrowed to exclude upload-direct, an upload that must enter a `merge` / `archive` / `image_watermark` op enters via a `passthrough` source job referenced downstream by `{type: job_output, from: <id>}` — preserving billing / DAG / lineage. Distinct from `operations: []` (which keeps its implicit-compress meaning on a single-input upload job); `passthrough` is the EXPLICIT lossless path via the "non-empty `operations[]` without `compress` = compression opt-out" rule. Media-agnostic; no options. `availability: beta` — activated (the inputs[]-narrowing + passthrough self-complete mechanism is deployed API-side); workflow-create accepts `passthrough` source jobs and MUST NOT return `feature_not_available`. **Never published to SNS** — deliberately absent from the AsyncAPI routing enums (API self-completes; no `ops-passthrough` queue). Per ticket [`4som89Uh`](https://trello.com/c/4som89Uh) + ADR-0004 (planned→beta flip).
 
         Both the legacy `thumbnail` value and the four sub-type values
@@ -10885,12 +11078,24 @@ components:
             when `type: enum`. Keys MUST be a subset of `values[]`;
             each entry value is a `depends_on`-shaped condition mapping
             that the named enum value REQUIRES. Distinct from
-            option-level `depends_on` (which gates applicability with
-            silent-ignore semantics); `per_value_depends_on` rejects
-            the request with `invalid_options` when the named value is
-            chosen and the condition is not met. Verified by
+            option-level `depends_on`, which gates the WHOLE option's
+            applicability and IS enforced by the API at workflow-create
+            (`OperationOptionsValidator`: a submitted option whose gate is
+            unmet is rejected as `invalid_options`; an absent one is
+            inactive). `per_value_depends_on` instead constrains a single
+            VALUE of an otherwise-active option. ENFORCEMENT NOTE: the API's
+            create-time validator does NOT yet evaluate `per_value_depends_on`
+            (only option-level `depends_on`); it is shape-checked metadata
+            that SDK/FE consume to gate the value, with the worker as the
+            reject backstop (a future API version may add create-time
+            enforcement, contract-first). When unmet it logically requires
+            the request be rejected as `invalid_options` (intent; per the
+            enforcement note above this is not yet API-create-enforced), the
+            option itself staying active. The KEY/SHAPE (keys are a subset of
+            `values[]`; condition cross-refs resolve) is verified by
             `make check-per-value-depends-on` (CI guard, ticket
-            [`bsV3FWM5`](https://trello.com/c/bsV3FWM5)). Runtime
+            [`bsV3FWM5`](https://trello.com/c/bsV3FWM5)) — shape only, NOT
+            runtime/worker enforcement. Runtime
             emission ships verbatim alongside other availability
             metadata. See `schemas/FORMAT.md` §per_value_depends_on.
           additionalProperties: true

package/operations/schemas/compress.yaml

@@ -16,6 +16,18 @@ operation:
         - image/svg+xml
         - image/tiff
         - image/avif
+      per_mime_availability:
+        # avif INPUT decode shipped in the compress-image worker via libheif
+        # (lambdas w34Taquf, #210). beta: live + opt-in, shape-stable.
+        # Re-add after the v2.67.0 interim crash-window drop (aYPbNVKD Phase 2).
+        # image/heic is intentionally NOT re-added to compress: compress is
+        # decode-only and there is no HEIC encoder, so the worker rejects a
+        # declared image/heic (FormatMismatch). heic stays on convert+thumbnail.
+        # WORKER LIMIT (not yet contract-expressible — F3 follow-up): the
+        # compress-image worker caps avif INPUT at 20MB (compression_processor.rs),
+        # below the general image size budget. Per-MIME input-size caps have no
+        # contract vocab today; tracked for the image-size-cap mechanism (F3).
+        image/avif: { availability: beta }
       options:
         mode:
           type: enum
@@ -55,9 +67,35 @@ operation:
           type: enum
           values: [original, auto, smallest, jpeg, png, webp, avif]
           default: original
+          per_value_availability:
+            # FACADE (VcPeRWdD): "compress + change format" resolves to a SINGLE
+            # combined convert-with-size-cap pass canonicalized API-side (the
+            # compress worker stays same-format — it never reads output_format).
+            # Non-`original` values were a live untagged-`stable` silent no-op
+            # (worker ignored them, returned a same-format file at 200) — the
+            # hlKCslIu-class over-claim. Tagged `planned` until each value's
+            # facade piece lands (API canonicalization + lambdas encode), then
+            # flipped `stable` per value with capability proof (ADR-0001/0006).
+            # ALL non-`original` values are tagged `planned`: the compress+format
+            # FACADE path (API canonicalization → convert) is not live for ANY
+            # value until [API] IsjNT2PJ ships, so even jpeg/avif are dormant-safe
+            # `planned` in this lead PR (without the marker the canonicalizer would
+            # dispatch them to a not-live path). They flip `stable` per value as
+            # each facade piece lands + capability proof (ADR-0001/0006): jpeg/avif
+            # first (closest — shipped foldImageEncodeOperations), then png (API
+            # fold), webp (lambdas lossy-webp PfGs5PBT), auto/smallest (runtime
+            # selection, unbuilt). `original` (same-format, today's behaviour) stays stable.
+            auto:     { availability: planned }   # runtime Accept-best selection — unbuilt
+            smallest: { availability: planned }   # runtime try-all-smallest selection — unbuilt
+            jpeg:     { availability: planned }   # facade path not live until IsjNT2PJ
+            png:      { availability: planned }   # facade path not live until IsjNT2PJ
+            webp:     { availability: planned }   # + needs lambdas lossy-webp (PfGs5PBT)
+            avif:     { availability: planned }   # facade path not live until IsjNT2PJ
           description: >-
-            Output format. original = keep input format, auto = best for browser support
-            (AVIF > WebP > JPEG based on Accept header hint), smallest = try all supported formats and return the smallest file
+            Output format. original = keep input format (default); auto = best for browser
+            support (AVIF > WebP > JPEG via Accept hint); smallest = try all supported formats,
+            return the smallest. Non-`original` values are served by the API "compress+format"
+            facade (one combined convert-with-size-cap pass); see per_value_availability + FORMAT.md.
 
     audio:
       mimes:
@@ -68,12 +106,47 @@ operation:
         - audio/wav
         - audio/mp4
       options:
+        output_format:
+          type: enum
+          values: [original, mp3, aac, ogg, flac, wav]
+          default: original
+          per_value_availability:
+            # FACADE (VcPeRWdD): "compress audio + change format" resolves to a
+            # SINGLE API-canonicalized convert pass (the API computes a discrete
+            # target bitrate; convert honours it via -b:a — no compress-worker
+            # change, no source-relative cap needed for audio). Non-`original`
+            # values are facade-pending until the API canonicalization lands,
+            # then flipped `stable` per value. `original` (same-format, today's
+            # behaviour) stays stable. Values mirror convert.audio.output_format.
+            mp3:  { availability: planned }
+            aac:  { availability: planned }
+            ogg:  { availability: planned }
+            flac: { availability: planned }
+            wav:  { availability: planned }
+          description: >-
+            Output audio format. original = keep input format (default, same-format
+            compression). Non-`original` values re-target the container/codec via the
+            API "compress+format" facade (one canonicalized convert pass); see FORMAT.md.
         bitrate:
           type: enum
           value_type: integer
           values: [64, 96, 128, 192, 256, 320]
           default: 128
-          description: "Output bitrate in kbps"
+          description: >
+            Output bitrate in kbps (CBR/ABR). Applies to lossy OUTPUTS. Only a
+            caller-EXPLICIT bitrate against a lossless output is rejected as
+            invalid_options (flac/wav have no bitrate target); the `default: 128` is
+            never the basis for a rejection (ADR-0020 D1 — a default a caller did not set
+            is the server's to resolve, and is dropped for a lossless target). The output
+            is the input format unless `output_format` re-targets it: with
+            `output_format: original` the lossy/lossless distinction follows the input MIME
+            (mpeg/aac/ogg/mp4 = lossy → bitrate applies; flac/wav input → an explicit
+            bitrate is rejected); with an explicit `output_format`, it follows that target
+            (flac/wav target → an explicit bitrate is rejected). Not expressed as
+            `depends_on` — the lossy-output condition is an output-value × input-MIME
+            cross-axis the option-to-option `depends_on` cannot model without dropping
+            `original` and breaking same-format callers. The other knobs
+            (channels/sample_rate/normalize) apply to all formats.
         channels:
           type: integer
           min: 1
@@ -219,8 +292,23 @@ operation:
           type: enum
           value_type: integer
           values: [64, 96, 128, 192, 256, 320]
-          default: 128
-          description: "Audio track bitrate in kbps"
+          # depends_on is ENFORCED AT CREATE: the API's OperationOptionsValidator
+          # excludes an option whose dependsOn is unmet from the active set, then
+          # flags a SUBMITTED inactive option as unknownOption → invalid_options.
+          # So an explicit audio_bitrate with audio_codec copy/omitted is REJECTED
+          # at workflow-create (staging-triage #4's "validate at CREATE"). FE/SDK
+          # also prune it pre-submit; the worker (video_encode_options.rs) is the
+          # deeper backstop. The reported failure is closed by the create-reject
+          # + the preset audioBitrate drop. NO API code needed (existing validator).
+          depends_on: { audio_codec: [aac, opus, vorbis] }
+          description: >
+            Audio track bitrate in kbps. Only valid with an explicit re-encode
+            audio_codec (aac/opus/vorbis): an explicit audio_bitrate with
+            audio_codec `copy`/omitted is rejected as `invalid_options` at
+            workflow-create (the API enforces this `depends_on`); copy preserves
+            the source bitrate. FE/SDK also prune it pre-submit. No default: a
+            bitrate is only meaningful on an explicit re-encode (matches the
+            worker, which applies none).
         trim_start:
           type: float
           min: 0

package/operations/schemas/convert.yaml

@@ -19,6 +19,13 @@ operation:
         - image/vnd.microsoft.icon
         - image/avif
         - image/heic
+      per_mime_availability:
+        # avif/heic input decode shipped in the convert worker via libheif
+        # (lambdas w34Taquf, #210). beta: live + opt-in, shape-stable.
+        # Re-add after the v2.67.0 interim crash-window drop (aYPbNVKD Phase 2).
+        # (avif is also a valid OUTPUT via output_format — ravif encode.)
+        image/avif: { availability: beta }
+        image/heic: { availability: beta }
       options:
         output_format:
           type: enum
@@ -73,18 +80,29 @@ operation:
         codec:
           type: enum
           values: [h264, h265, vp9, av1]
+          depends_on: { output_format: [mp4, webm, ogg] }
           description: >
             Video codec for target format. Defaults to the format's standard
             codec (no literal default — the required output_format determines
             it). This is the container-conditional-default principle applied via
             an explicit container choice. See FORMAT.md
             "Container-conditional defaults" + ADR-0020.
+            Not applicable to a `gif` output (no video codec): an explicit
+            `codec` on a `gif` output is rejected as `invalid_options` at
+            workflow-create (the API enforces this `depends_on`); FE/SDK prune
+            it pre-submit.
         quality:
           type: integer
           min: 0
           max: 51
           default: 23
-          description: "CRF value (0 = lossless, 51 = worst)"
+          depends_on: { output_format: [mp4, webm, ogg] }
+          description: >
+            CRF value (0 = lossless, 51 = worst). Video outputs only — NOT
+            applicable to a `gif` output (frame extraction has no CRF). An
+            explicit `quality` on a `gif` output is rejected as `invalid_options`
+            at workflow-create (the API enforces this `depends_on`); FE/SDK
+            prune it pre-submit.
 
     audio:
       mimes:

package/operations/schemas/split.yaml

@@ -69,9 +69,11 @@ operation:
     `availability: beta` for the `audio` and `video` mime_groups
     (workers live on staging — shape-stable + opt-in, MUST NOT 422).
     Video activates **both classes**: `video.processing_class.short_form`
-    AND `long_form` are `beta` — the `split-video-fargate` worker is proven
-    on staging (4GB+ HEVC input → keyframe-aligned segments;
-    [`rcwvUKhI`](https://trello.com/c/rcwvUKhI)). The `image_gif` and
+    AND `long_form` are `beta` — the `split-video-fargate` worker is
+    deployed + wired on staging but NOT yet proven end-to-end
+    ([`rcwvUKhI`](https://trello.com/c/rcwvUKhI); the first customer-path
+    soak has not completed and the 4GB+ speed-up is unmeasured; the
+    long-form fan-out is flag-gated dark). The `image_gif` and
     `document_pdf` mime_groups stay `availability: planned` until their
     cross-repo Lambda workers ship ([`vKI0CFDu`](https://trello.com/c/vKI0CFDu)
     + lambdas L1); dispatch returns `feature_not_available` (422) for the
@@ -296,10 +298,11 @@ operation:
             max_input_size_bytes: 524288000
             max_output_size_bytes: 524288000
         long_form:
-          # planned -> beta (rcwvUKhI): split-video-fargate worker proven on
-          # staging (4GB+ HEVC -> keyframe-aligned segments). Routes per
-          # ADR-0014 §D10 — same split OperationType, dedicated stream-copy
-          # segmenter binary (NOT the long-form compress worker).
+          # planned -> beta (rcwvUKhI): split-video-fargate worker deployed +
+          # wired on staging but NOT yet proven end-to-end (first customer-path
+          # soak incomplete; 4GB+ speed-up unmeasured; fan-out flag-gated dark).
+          # Routes per ADR-0014 §D10 — same split OperationType, dedicated
+          # stream-copy segmenter binary (NOT the long-form compress worker).
           availability: beta
           required_tier: pro
           constraints:                            # baseline = Pro

package/operations/schemas/thumbnail.yaml

@@ -17,6 +17,12 @@ operation:
         - image/bmp
         - image/avif
         - image/heic
+      per_mime_availability:
+        # avif/heic decode shipped in the thumbnail-image worker via libheif
+        # (lambdas w34Taquf, #210). beta: live + opt-in, shape-stable.
+        # Re-add after the v2.67.0 interim crash-window drop (aYPbNVKD Phase 2).
+        image/avif: { availability: beta }
+        image/heic: { availability: beta }
       options:
         width:
           type: integer

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@giveitsmaller/contracts",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "description": "Generated contract types for GISL (Give It Smaller)",
   "license": "MIT",
   "type": "module",