@giveitsmaller/contracts 0.18.0 → 0.19.0

package/operations/schemas/compress.yaml

@@ -67,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:
@@ -80,16 +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. Applies to lossy outputs
-            (mpeg/aac/ogg/mp4) — CBR/ABR; rejected as invalid_options for
-            lossless outputs (flac/wav, which have no bitrate target). The
-            other knobs (channels/sample_rate/normalize) apply to all formats.
+            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
@@ -235,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

@@ -80,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/package.json

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