@giveitsmaller/contracts 0.18.0 → 0.21.0

package/operations/schemas/compress.yaml

@@ -67,9 +67,36 @@ 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).
+            # Values flip `stable` per value as each facade piece lands: `webp` is
+            # DONE (see the stable-flip note below); the rest stay `planned` — auto/
+            # smallest (runtime selection, unbuilt), jpeg/png/avif (no canonicalization
+            # live yet). `original` (same-format, today's behaviour) stays stable.
+            # WEBP STABLE-FLIP (VcPeRWdD): webp is now FUNCTIONAL end-to-end — API B
+            # (#422) canonicalizes compress(image,webp)→convert(webp,quality) + lambdas
+            # lossy-webp (PfGs5PBT) is live+proven on staging — so webp is removed from
+            # this map (untagged = stable, ADR-0001 §1.4). jpeg/png/avif/auto/smallest
+            # stay `planned` (their canonicalization is NOT in API B — flipping them now
+            # would stop the 422 while they still dispatch to the same-format worker =
+            # silent no-op, re-opening the over-claim).
+            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 its own canonicalization
+            png:      { availability: planned }   # facade path not live until its own canonicalization
+            avif:     { availability: planned }   # facade path not live until its own canonicalization
           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 +107,42 @@ operation:
         - audio/wav
         - audio/mp4
       options:
+        output_format:
+          type: enum
+          values: [original, mp3, aac, ogg, flac, wav]
+          default: original
+          # FACADE (VcPeRWdD -> RTokti20 stable-flip): "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).
+          # All non-`original` values are now LIVE (API canonicalization landed,
+          # convert.audio worker live) so the per_value_availability block is
+          # removed => untagged = stable (ADR-0001 §1.4). Values mirror
+          # convert.audio.output_format.
+          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, carried into ADR-0023 — 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
@@ -149,6 +202,37 @@ operation:
               max_input_size_bytes: 120000000000   # 120 GB (Enterprise enforced ceiling)
               max_output_size_bytes: 120000000000
       options:
+        output_format:
+          type: enum
+          values: [original, mp4, webm, ogg]
+          default: original
+          per_value_availability:
+            # FACADE Phase-2 (8t2iEd4f, ADR-0023 — supersedes ADR-0020).
+            # "compress video + change container" resolves to a SINGLE API-
+            # canonicalized convert(output_format=X + source-relative size-cap)
+            # pass — the compress worker stays same-format and NEVER reads
+            # output_format. Non-`original` values lead `planned` until the API
+            # canonicalization + the convert-video size-cap (lambdas 6M5Bz0zf)
+            # land and each value flips `stable` with capability proof (ADR-0006).
+            # `original` (same-format, today's behaviour) stays stable. gif is
+            # EXCLUDED (animation target, not a compress output — use convert/
+            # merge). ogg inherits convert.video's PRE-EXISTING Theora codec-enum
+            # gap (ADR-0023 D6); ogg-video codec/audio resolution is an explicit
+            # ogg stable-flip prerequisite. The API enforces planned->422
+            # feature_not_available generically (per-op effective-input-MIME);
+            # activated on the API re-vendor of this cut.
+            mp4:  { availability: planned }
+            webm: { availability: planned }
+            ogg:  { availability: planned }
+          description: >-
+            Output container. original = keep the input container (default,
+            same-format compression). Non-`original` values re-target the
+            container via the API "compress+format" facade (one canonicalized
+            convert-with-size-cap pass); see per_value_availability + ADR-0023 +
+            FORMAT.md. When set, the RESOLVED target container determines the
+            valid codec/audio_codec/faststart sets — an absent/default codec
+            resolves to a container-valid one (e.g. webm -> vp9) and is never
+            rejected; only a caller-EXPLICIT incompatible value is invalid_options.
         codec:
           type: enum
           values: [h264, h265, vp9, av1]
@@ -156,18 +240,33 @@ operation:
           description: >
             Video codec. h264 = widest compatibility, h265/av1 = better
             compression but slower. The default (h264) is the MP4/MOV standard
-            and is CONTAINER-CONDITIONAL: for an output container that cannot
-            carry it (e.g. WebM, which carries VP8/VP9/AV1) the server resolves
-            a container-valid codec (WebM -> vp9). A DEFAULT value is never
-            rejected; only a caller-EXPLICIT incompatible codec returns
-            invalid_options. See FORMAT.md "Container-conditional defaults" +
-            ADR-0020.
+            and is CONTAINER-CONDITIONAL against the RESOLVED output container
+            (the explicit `output_format` if set, else the input container): for
+            a container that cannot carry it (e.g. WebM, which carries VP8/VP9/
+            AV1) the server resolves a container-valid codec (WebM -> vp9). A
+            DEFAULT value is never rejected — including an explicit
+            `output_format: webm` left at the default `h264` (resolves to vp9,
+            NOT invalid_options); only a caller-EXPLICIT incompatible codec
+            returns invalid_options. See FORMAT.md "Container-conditional
+            defaults" + ADR-0023 (supersedes ADR-0020).
         encoding_mode:
           type: enum
           values: [crf, target_size]
           default: crf
-          # target_size is implemented as a two-pass encode in the worker.
-          description: "crf = constant quality (variable file size), target_size = constrained file size"
+          per_value_availability:
+            # honesty gate (hlKCslIu): the compress-video worker does NOT
+            # implement target_size two-pass — it REJECTS it
+            # (crates/shared/src/domain/video_encode_options.rs:248-259;
+            # lambdas-confirmed). `planned` until two-pass ships; `crf` (the
+            # default) stays stable. NOTE the current worker reject surfaces as
+            # `invalid_options`, NOT `feature_not_available` — `planned` is the
+            # honest availability signal (lets FE/SDK hide it) ahead of an edge-
+            # gate / the implementation. See ADR-0023 D8.
+            target_size: { availability: planned }
+          description: >-
+            crf = constant quality (variable file size). target_size =
+            constrained file size — `planned`: the worker does not yet implement
+            the two-pass encode (it rejects target_size); crf only today.
         crf:
           type: integer
           min: 0
@@ -178,9 +277,13 @@ operation:
         target_size_bytes:
           type: integer
           min: 1048576
+          availability: planned
           depends_on: { encoding_mode: target_size }
-          # Met via a two-pass encode in the worker.
-          description: "Target output file size in bytes (min 1MB)."
+          # honesty gate (hlKCslIu): two-pass NOT implemented — the worker
+          # REJECTS target_size_bytes (video_encode_options.rs:255-259), so this
+          # option is `planned`. The current reject is `invalid_options`, not
+          # feature_not_available; flips stable when two-pass ships. See ADR-0023 D8.
+          description: "Target output file size in bytes (min 1MB). `planned` — the worker does not yet implement the two-pass target-size encode."
         preset:
           type: enum
           values: [ultrafast, superfast, veryfast, faster, fast, medium, slow, slower, veryslow]
@@ -212,31 +315,53 @@ operation:
           default: true
           description: >
             Move the MP4/MOV moov atom to start for progressive web playback.
-            MP4/MOV only. CONTAINER-CONDITIONAL: the default (true) is silently
-            inapplicable for a container with no moov atom (e.g. WebM) — that
-            is NOT a rejection. Only a caller-EXPLICIT faststart:true on such a
-            container returns invalid_options. See FORMAT.md
-            "Container-conditional defaults" + ADR-0020.
+            MP4/MOV only. CONTAINER-CONDITIONAL against the RESOLVED output
+            container (the explicit `output_format` if set, else the input): the
+            default (true) is silently inapplicable for a container with no moov
+            atom (e.g. WebM) — that is NOT a rejection. Only a caller-EXPLICIT
+            faststart:true on such a container returns invalid_options. See
+            FORMAT.md "Container-conditional defaults" + ADR-0023 (supersedes
+            ADR-0020).
         audio_codec:
           type: enum
           values: [aac, opus, vorbis, copy]
           default: copy
           description: >
-            Audio codec. copy = passthrough (keep the source audio stream as-is;
-            re-encode only on explicit request) — aac = widest compatibility,
-            opus = best quality/size. Default is `copy` (ADR-0020 D7): it MATCHES
-            the worker's actual absent-audio behaviour and is container-safe for
-            compress (output container = input container, so the source stream is
-            already compatible). Set an explicit codec to re-encode; an explicit
-            codec the output container cannot carry (e.g. aac on a WebM output)
-            returns invalid_options. A DEFAULT value is never rejected. See
-            FORMAT.md "Container-conditional defaults" + ADR-0020.
+            Audio codec. copy = passthrough (keep the source stream as-is;
+            re-encode only on explicit request) — aac/opus/vorbis re-encode.
+            Default is `copy` (ADR-0020 D7, carried into ADR-0023): on the
+            same-container path (`output_format` original/absent) the source
+            stream is already container-compatible, so copy is safe. When
+            `output_format` RE-TARGETS the container, an absent/default
+            audio_codec resolves to a container-valid codec via the facade
+            (e.g. webm -> opus), NOT a blind copy of an incompatible stream — a
+            DEFAULT is never rejected (the exact per-container resolution, incl.
+            ogg vorbis-vs-opus, is an output_format stable-flip prerequisite,
+            ADR-0023 D5). A caller-EXPLICIT codec the resolved container cannot
+            carry (e.g. aac on a webm target) returns invalid_options. See
+            FORMAT.md "Container-conditional defaults" + ADR-0023 (supersedes
+            ADR-0020).
         audio_bitrate:
           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.
+            "Container-conditional defaults" + ADR-0023 (supersedes 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.21.0",
   "description": "Generated contract types for GISL (Give It Smaller)",
   "license": "MIT",
   "type": "module",