@giveitsmaller/contracts 0.22.0 → 0.24.0

package/operations/schemas/convert.yaml

@@ -76,33 +76,53 @@ operation:
           type: enum
           values: [mp4, webm, ogg, gif]
           required: true
-          description: "Target format"
-        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-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:
+          # The video codec is DETERMINED by the target container, NOT a caller
+          # choice: the convert-video worker hard-wires it per container
+          # (mp4 -> H.264/libx264, webm -> VP9, ogg -> Theora, gif -> palette;
+          # lambdas-confirmed video_convert.rs). The former `codec` option
+          # (enum h264/h265/vp9/av1) was a SILENT NO-OP — the worker never read
+          # it — so it was removed (honesty pass, 2026-06-20). To choose a codec,
+          # use compress.video (which has a real, worker-honored `codec`).
+          description: "Target format. The video codec is fixed by the container (mp4->H.264, webm->VP9, ogg->Theora, gif->palette) — not caller-selectable."
+        crf:
           type: integer
           min: 0
           max: 51
           default: 23
           depends_on: { output_format: [mp4, webm, ogg] }
+          # Renamed `quality` -> `crf` (2026-06-20) to match compress.video.crf
+          # and stop the misnomer: this is a Constant Rate Factor (0=best/lossless,
+          # 51=worst), the INVERSE of convert.image.quality (1-100, higher=better).
+          description: >
+            CRF (Constant Rate Factor): 0 = lossless/best, 51 = worst. Lower = higher
+            quality + larger file (the inverse of image `quality`). Video outputs only —
+            NOT applicable to a `gif` output (frame extraction has no CRF). An explicit
+            `crf` on a `gif` output is rejected as `invalid_options` at workflow-create
+            (the API enforces this `depends_on`); FE/SDK prune it pre-submit.
+        trim_start:
+          type: float
+          min: 0
+          availability: planned
+          # SAME semantic as compress.video / compress.audio / merge per_input trim
+          # (float SECONDS, "from beginning / from end") so there is NO cross-op
+          # divergence — merge's per_input trim is the worker-implemented reference.
+          description: >
+            Trim from beginning in seconds (absent = from the start). The
+            convert-video worker cuts the clip before transcoding — the user's
+            "trim a video then make a GIF" path. The kept clip is
+            [`trim_start`, input_duration − `trim_end`]. Gated `planned` until the
+            convert-trim worker ships + staging-proves; flips `stable` for the
+            video outputs (gif/mp4/webm/ogg) then.
+        trim_end:
+          type: float
+          min: 0
+          availability: planned
+          # "From END" in seconds (NOT absolute end, NOT duration) — matches merge/
+          # compress. Worker keeps [trim_start, input_duration - trim_end].
           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.
+            Trim from end in seconds (absent = to the end of the clip). Removes this
+            many seconds from the end; combined with `trim_start` the kept clip is
+            [`trim_start`, input_duration − `trim_end`]. Gated `planned` — see `trim_start`.
 
     audio:
       mimes:
@@ -115,16 +135,18 @@ operation:
       options:
         output_format:
           type: enum
-          values: [mp3, aac, ogg, flac, wav]
+          values: [mp3, aac, ogg, opus, flac, wav]
           required: true
+          # `opus` added 2026-06-20 — the convert-audio worker produces it
+          # (audio/ogg container, .opus extension; lambdas-confirmed live).
           description: "Target format"
         bitrate:
           type: enum
           value_type: integer
           values: [64, 96, 128, 192, 256, 320]
           default: 128
-          depends_on: { output_format: [mp3, aac, ogg] }
-          description: "Output bitrate in kbps (lossy formats only)"
+          depends_on: { output_format: [mp3, aac, ogg, opus] }
+          description: "Output bitrate in kbps (lossy formats only — mp3/aac/ogg/opus)"
 
     # Only PDF conversion is supported. Office/ODF/EPUB conversion would require
     # LibreOffice which is not available in the document Lambda.

package/operations/schemas/custom_luma.yaml

@@ -34,6 +34,7 @@ operation:
     transition; this operation is the deliberate alternative).
   default: false
   input_model: multi
+  sole_op: true   # bypasses V1 chain validation — must be the only operation in its job (ADR-0025)
   min_inputs: 2
   max_inputs: 2
 

package/operations/schemas/image_watermark.yaml

@@ -34,6 +34,7 @@ operation:
     Per ADR-0004 §"V2 JobDefinition" + plan v5 §F1.
   default: false
   input_model: multi
+  sole_op: true   # bypasses V1 chain validation — must be the only operation in its job (ADR-0025)
   min_inputs: 2
   max_inputs: 2
 

package/operations/schemas/merge.yaml

@@ -5,6 +5,7 @@ operation:
   description: "Combine multiple files into one"
   default: false
   input_model: multi
+  sole_op: true   # bypasses V1 chain validation — must be the only operation in its job (ADR-0025)
   min_inputs: 2
   max_inputs: 10
   # All merge operations route to the single `ops-merge` Lambda via

package/operations/schemas/split.yaml

@@ -82,6 +82,7 @@ operation:
     Per ADR-0014.
   default: false
   input_model: single
+  sole_op: true   # bypasses V1 chain validation — must be the only operation in its job (ADR-0025)
 
   features:
     silence_mode_audio:

package/operations/schemas/text_watermark.yaml

@@ -14,6 +14,7 @@ operation:
       pattern); rotation default -45° and tile_spacing controls density.
   default: false
   input_model: single
+  sole_op: true   # bypasses V1 chain validation — must be the only operation in its job (ADR-0025)
 
   mime_groups:
     image:

package/operations/schemas/thumbnail.yaml

@@ -46,6 +46,13 @@ operation:
           values: [jpg, png, webp]
           default: jpg
           description: "Output format for the thumbnail"
+        quality:
+          type: integer
+          min: 1
+          max: 100
+          default: 85
+          depends_on: { format: [jpg, webp] }
+          description: "Output quality for lossy thumbnail formats (jpg/webp): higher = better quality, larger file. Ignored for png (lossless)."
 
     video:
       mimes:
@@ -101,6 +108,13 @@ operation:
           values: [jpg, png, webp]
           default: jpg
           description: "Output format for the thumbnail"
+        quality:
+          type: integer
+          min: 1
+          max: 100
+          default: 85
+          depends_on: { format: [jpg, webp] }
+          description: "Output quality for lossy thumbnail formats (jpg/webp): higher = better quality, larger file. Ignored for png (lossless)."
 
     document:
       mimes:
@@ -152,3 +166,10 @@ operation:
           values: [jpg, png, webp]
           default: jpg
           description: "Output format for the thumbnail"
+        quality:
+          type: integer
+          min: 1
+          max: 100
+          default: 85
+          depends_on: { format: [jpg, webp] }
+          description: "Output quality for lossy thumbnail formats (jpg/webp): higher = better quality, larger file. Ignored for png (lossless)."

package/operations/schemas/video_text_watermark.yaml

@@ -30,6 +30,7 @@ operation:
     [`4NrRPCgh`](https://trello.com/c/4NrRPCgh)).
   default: false
   input_model: single
+  sole_op: true   # bypasses V1 chain validation — must be the only operation in its job (ADR-0025)
 
   mime_groups:
     video:

package/operations/schemas/video_watermark.yaml

@@ -38,6 +38,7 @@ operation:
     [`SlluxMBN`'s sibling `4NrRPCgh`](https://trello.com/c/4NrRPCgh)).
   default: false
   input_model: multi
+  sole_op: true   # bypasses V1 chain validation — must be the only operation in its job (ADR-0025)
   min_inputs: 2
   max_inputs: 2
 

package/package.json

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