@giveitsmaller/contracts 0.9.0 → 0.17.0

package/operations/schemas/merge.yaml

@@ -75,10 +75,8 @@ operation:
           depends_on: { output_type: video }
           description: |
             Transition effect between images in the slideshow output.
-            Catalog from FFmpeg 7.1.1 xfade filter (per ADR-0007). See
-            per_value_availability for per-value rollout state. The
-            `none` value is a sentinel ("no transition / hard cut"),
-            not an FFmpeg preset.
+            `none` means a hard cut with no transition. Some effects
+            are still rolling out — check their availability.
           per_value_availability:
             # Untagged values default to stable per ADR-0001 §1.4.
             smoothleft:   { availability: beta }
@@ -139,12 +137,27 @@ operation:
       mimes:
         - video/mp4
         - video/webm
+        - video/quicktime
       processing_class:
         # F8 long-form video tier (per ticket I15-CONS). Merge uses
-        # alias class names because its differentiator is concat-
-        # compatibility (I16-CONS re_encode_mode) rather than just
-        # size/duration — a small merge can still need long_form
-        # when inputs require re-encoding.
+        # alias class names (short_form_concat / long_form_re_encode),
+        # but ROUTING (which class) is DURATION/SIZE-driven at
+        # create-plan, NOT concat-compatibility: the API resolver
+        # assigns long_form when summed input duration exceeds the
+        # short_form cap (PT5M) OR summed size exceeds 1 GiB; it has no
+        # per-input codec/pixfmt at create-plan to decide re-encode-need
+        # (MAVh1blw; api d363a4ab). re_encode-vs-stream-copy is a WORKER
+        # SUB-MODE WITHIN EACH class, not a long-form differentiator:
+        # short-form (filter_complex) re-encodes heterogeneous inputs +
+        # crossfade fine; long_form_re_encode (FFmpeg concat-demuxer)
+        # REQUIRES UNIFORM inputs and re-encodes them (e.g. uniform VP9 ->
+        # mp4). So long_form_re_encode = LONG-duration/size + uniform-but-
+        # not-stream-copyable. HETEROGENEOUS long merges (per-input codec
+        # mismatch at long duration) are the deferred Phase-3 gap (NOT
+        # built; concat-demuxer uniformity-rejects them). The earlier
+        # "a small merge can need long_form when inputs require
+        # re-encoding" claim was an over-claim describing a future
+        # two-trigger state — corrected here.
         short_form_concat:
           availability: stable
           constraints:
@@ -183,9 +196,8 @@ operation:
                    custom, wipetl, wipetr, wipebl]
           default: none
           description: |
-            Default transition between clips. Catalog from FFmpeg 7.1.1
-            xfade filter (per ADR-0007). See per_value_availability for
-            per-value rollout state.
+            Default transition between clips. Some effects are still
+            rolling out — check their availability.
           per_value_availability:
             smoothleft:   { availability: beta }
             smoothright:  { availability: beta }
@@ -291,33 +303,37 @@ operation:
           depends_on: { re_encode_mode: [auto, always] }
           per_value_depends_on:
             target_size: { codec: [h264] }
+          # target_size is currently codec=h264 only — h265 / vp9 / av1
+          # each require a different encoder invocation and are tracked
+          # as separate per-codec Lambda follow-ups. The
+          # per_value_depends_on block above gates encoding_mode=target_size
+          # on codec ∈ [h264], so a request pairing target_size with
+          # {h265, vp9, av1} is rejected as invalid_options whether or not
+          # target_size_bytes is supplied — closing the gap left by the
+          # previous option-level depends_on (which only triggered when
+          # target_size_bytes was present). Per ticket bsV3FWM5.
           description: |
-            CRF (quality-targeted) vs target_size (two-pass to fixed file size).
-            `target_size` is currently `codec=h264` only — libx265 / libvpx-vp9 / libsvtav1 each
-            require a different two-pass invocation and are tracked as separate per-codec
-            Lambda follow-ups. The `per_value_depends_on` block above gates
-            `encoding_mode=target_size` itself on `codec ∈ [h264]`, so a request with
-            `encoding_mode=target_size + codec ∈ {h265, vp9, av1}` is rejected as
-            `invalid_options` regardless of whether `target_size_bytes` is supplied —
-            closing the gap left by the previous option-level `depends_on` (which only
-            triggered when `target_size_bytes` was present in the payload). Per ticket
-            [`bsV3FWM5`](https://trello.com/c/bsV3FWM5).
+            CRF aims for a quality level and lets the file size vary;
+            target_size aims for a fixed output file size. `target_size`
+            currently works with `codec=h264` only — a request pairing it
+            with another codec is rejected as `invalid_options`.
 
         target_size_bytes:
           type: integer
           min: 1048576
           depends_on: { re_encode_mode: [auto, always], encoding_mode: target_size }
+          # h264-only — the codec gate lives on
+          # encoding_mode.per_value_depends_on.target_size.codec (per ticket
+          # bsV3FWM5); this option's own depends_on no longer duplicates it.
+          # The practical floor below is enforced by the h264 encoder.
           description: |
-            Two-pass target file size in bytes (minimum 1 MiB). Required when
-            `encoding_mode=target_size`. h264-only — the codec gate now lives on
-            `encoding_mode.per_value_depends_on.target_size.codec` (per ticket
-            [`bsV3FWM5`](https://trello.com/c/bsV3FWM5)); this option's own
-            `depends_on` no longer duplicates it.
+            Target file size in bytes (minimum 1 MiB). Required when
+            `encoding_mode=target_size`, which is h264-only.
 
-            Practical floor: a ~100 kbps post-AAC video bitrate (i.e. `target_size_bytes`
-            corresponding to less than ~100 kbps of video after subtracting the 160 kbps
-            AAC audio track over the merged duration) is silently floored by libx264 and
-            the resulting file will not honour the requested `target_size_bytes`.
+            Practical floor: if the target works out to less than
+            ~100 kbps of video (after subtracting the ~160 kbps AAC audio
+            track over the merged duration), the encoder floors it and the
+            resulting file will not honour the requested `target_size_bytes`.
             Publishers targeting very small outputs should size accordingly.
 
       per_input_options:
@@ -373,6 +389,24 @@ operation:
           max: 5.0
           depends_on: { transition: crossfade }
           description: "Override crossfade duration for this join point"
+        trim_start:
+          type: float
+          min: 0
+          description: |
+            Trim from beginning in seconds (per-input). Applied to this
+            input BEFORE any transition/crossfade. Matches the
+            `compress` trim semantic. No `max` — the upper bound is the
+            input's own duration, enforced by the worker, not statically
+            bounded here.
+        trim_end:
+          type: float
+          min: 0
+          description: |
+            Trim from end in seconds (per-input). Applied to this input
+            BEFORE any transition/crossfade. Matches the `compress` trim
+            semantic. No `max` — the upper bound is the input's own
+            duration, enforced by the worker, not statically bounded
+            here.
 
     audio:
       # Audio transition catalog is intentionally separate from the
@@ -404,12 +438,13 @@ operation:
           # xfade catalog on merge.image / merge.video.
           values: [none, crossfade]
           default: none
+          # Audio-only catalog (acrossfade-backed); see FORMAT.md §"Audio
+          # vs visual transition catalogs (merge)" for the additions
+          # policy. Future values are added with per_value_availability
+          # per ADR-0001 §1.4.
           description: |
-            Default transition between clips. Audio-only catalog
-            (acrossfade-backed); see FORMAT.md §"Audio vs visual
-            transition catalogs (merge)" for additions policy. Future
-            values (e.g. `fade_curve` variants) will be added with
-            `per_value_availability` per ADR-0001 §1.4.
+            Transition between audio clips. `none` joins them with a
+            hard cut; `crossfade` blends one into the next.
         crossfade_duration:
           type: float
           min: 0
@@ -448,3 +483,21 @@ operation:
           min: 0
           max: 10.0
           description: "Override gap duration for this join point"
+        trim_start:
+          type: float
+          min: 0
+          description: |
+            Trim from beginning in seconds (per-input). Applied to this
+            input BEFORE any transition/crossfade. Matches the
+            `compress` trim semantic. No `max` — the upper bound is the
+            input's own duration, enforced by the worker, not statically
+            bounded here.
+        trim_end:
+          type: float
+          min: 0
+          description: |
+            Trim from end in seconds (per-input). Applied to this input
+            BEFORE any transition/crossfade. Matches the `compress` trim
+            semantic. No `max` — the upper bound is the input's own
+            duration, enforced by the worker, not statically bounded
+            here.

package/operations/schemas/passthrough.yaml

@@ -0,0 +1,49 @@
+schema_version: "1.0.0"
+
+operation:
+  type: passthrough
+  availability: beta
+  description: |
+    Inert lossless source operation. A single-input source job whose
+    SOLE operation is `passthrough` emits its source bytes UNCHANGED —
+    no compression, no transformation, no Lambda dispatch. The API
+    self-completes the job at workflow-create/publish time: the job's
+    terminal output IS the upload's `{bucket, key}` unchanged.
+
+    **Purpose.** Lets an uploaded file enter a multi-input operation
+    (`merge` / `archive` / `image_watermark` / etc.) LOSSLESSLY. Since
+    V2 narrows `JobInputV2.source` to exclude upload-direct (`MultiInputSource`
+    — job_output / external_import / connection only), an upload that
+    must feed a multi-input op enters via a `passthrough` source job
+    referenced downstream by `{ type: job_output, from: <id> }`. This
+    preserves billing / DAG / lineage that direct upload-in-inputs[]
+    would bypass.
+
+    **Distinct from `operations: []`.** An empty `operations[]` on a
+    single-input upload job KEEPS its implicit-compress meaning (see
+    `POST /api/workflows` description). `passthrough` is the EXPLICIT
+    lossless opt-out chosen via the existing rule "non-empty
+    `operations[]` without `compress` = compression opt-out" — it is a
+    sole, named operation, not an empty chain.
+
+    **Never published to SNS.** Because the API self-completes the job
+    at publish, `passthrough` is INTENTIONALLY absent from the AsyncAPI
+    routing enums (`OperationType`, `OperationRequestAttributes.operation_type`)
+    and has no `ops-passthrough` queue. It never appears on the wire as
+    a request message.
+
+    Media-agnostic (no `mime_groups`): it accepts any uploaded MIME and
+    copies it verbatim, so there are no per-MIME options or constraints.
+    `availability: beta` — the API self-completion path is LIVE (the
+    inputs[]-narrowing + passthrough self-complete mechanism is deployed),
+    so workflow-create accepts `passthrough` source jobs and MUST NOT
+    return `feature_not_available`. Activated per ticket
+    [`4som89Uh`](https://trello.com/c/4som89Uh) + ADR-0004 (planned→beta
+    flip; self-complete code deployed API-side).
+  default: false
+  input_model: single
+
+  # DELIBERATELY absent from the operation chain matrix
+  # (docs/matrices/operation-chains.md). passthrough is a sole-op source
+  # node, not a chainable transform — with no `mime_groups` it produces
+  # zero matrix rows, which is correct: nothing chains onto or after it.

package/operations/schemas/render_variants.yaml

@@ -0,0 +1,117 @@
+schema_version: "2.0.0"
+
+operation:
+  type: render_variants
+  # Generate N resized/re-encoded image variants from ONE decoded source in a
+  # single operation (image fan-out). Per spike GA2kiRY8 / epic nksLtV28,
+  # ticket w3EwzHYd. Worker = the shared convert image-encode stack + FitMode
+  # (lambdas-confirmed reuse: image_convert.rs encode + domain/thumbnailer.rs).
+  #
+  # availability: planned — the worker (lambdas 08q0ySAc) + its SNS subscription
+  # (terraform MNuDYJaY) are downstream of this contract, so the server returns
+  # `feature_not_available` (422) until they are live. The planned -> beta flip
+  # is a SEPARATE lockstep cut once the worker + wire are up (the two-gate rule;
+  # never flip beta ahead of the publisher). Source MIMEs are jpeg/png/webp only
+  # — AVIF is encode-only in the worker stack (decode unsupported), so it is a
+  # valid `output_format` target but NOT a source input.
+  description: "Generate multiple resized / re-encoded image variants from a single source image in one operation (image fan-out)."
+  availability: planned
+  input_model: single
+
+  mime_groups:
+    image:
+      availability: planned
+      mimes:
+        - image/jpeg
+        - image/png
+        - image/webp
+      options:
+        targets:
+          type: array
+          required: true
+          minItems: 1
+          maxItems: 20
+          # Each target is encoded independently from the single decoded
+          # source. Width/height are individually optional at the type level;
+          # the cross-field rule (fit crop/scale => BOTH required; fit max =>
+          # at least one) is worker-enforced and rejected as `invalid_options`,
+          # not expressed structurally here (the option DSL has no per-item
+          # conditional-required primitive). Documented in prose below.
+          description: |
+            One output variant per entry (max 20). Each variant is resized /
+            re-encoded independently from the single decoded source; the
+            operation succeeds or fails **atomically** — there are no partial
+            outputs. Each result output echoes its target's `id` back as
+            `target_id` so callers can map outputs to the variants they asked
+            for.
+
+            Dimensions: `fit: max` needs at least one of `width` / `height`
+            (aspect preserved, output may be smaller than the box). `fit: crop`
+            and `fit: scale` require BOTH `width` and `height` (they produce an
+            exact-size output). A target whose dimensions exceed the source is
+            rejected (`invalid_options`) unless `allow_upscale: true`.
+          items:
+            type: object
+            required:
+              - id
+            properties:
+              id:
+                type: string
+                pattern: '^[A-Za-z0-9._-]+$'
+                maxLength: 64
+                # `id` must be unique within the array — this is the addressing
+                # key, so duplicates would map two outputs to one `target_id`.
+                # JSON Schema `uniqueItems` only catches wholesale-identical
+                # target objects, not same-`id`-different-dims; the worker
+                # rejects duplicate ids as `invalid_options` (worker-enforced,
+                # like the dimension rules).
+                description: |
+                  Caller-assigned identifier, unique within the array
+                  (duplicate ids are rejected as `invalid_options`). Echoed
+                  verbatim as `target_id` on the matching result output — the
+                  addressing contract.
+              width:
+                type: integer
+                minimum: 1
+                maximum: 16384
+                description: "Target width in pixels. Required together with height for fit crop/scale; for fit max, at least one of width/height is required."
+              height:
+                type: integer
+                minimum: 1
+                maximum: 16384
+                description: "Target height in pixels. Required together with width for fit crop/scale; for fit max, at least one of width/height is required."
+              fit:
+                type: string
+                enum:
+                  - max
+                  - crop
+                  - scale
+                default: max
+                description: |
+                  Resize mode. max = fit within the box, aspect preserved
+                  (output may be smaller); needs at least one dimension.
+                  crop = fill and trim to exact width x height. scale = force
+                  exact width x height. crop and scale require both dimensions.
+              quality:
+                type: integer
+                minimum: 1
+                maximum: 100
+                default: 85
+                description: "Encode quality (lossy formats only — jpeg / webp / avif). Accepted but ignored for png (lossless)."
+              output_format:
+                type: string
+                enum:
+                  - jpeg
+                  - png
+                  - webp
+                  - avif
+                description: "Output format for this variant. When omitted, the source format is preserved."
+              background:
+                type: string
+                pattern: '^#[0-9A-Fa-f]{6}$'
+                default: "#FFFFFF"
+                description: "Background colour (hex #RRGGBB), applied only when flattening a transparent source into an opaque format (e.g. a PNG with alpha rendered to JPEG). Ignored otherwise."
+              allow_upscale:
+                type: boolean
+                default: false
+                description: "When false (default), a target whose dimensions exceed the source is rejected (`invalid_options`). Set true to permit upscaling. fit max never upscales."

package/operations/schemas/split.yaml

@@ -9,14 +9,19 @@ operation:
     into N outputs per the per-mime-group catalog. Mirrors the
     `merge` / `convert` catalog-split-by-mime-group pattern.
 
-    **Three modes** (audio + video; the mode discriminator gates which
-    of the three options applies per the `depends_on` rules in this
+    **Three shared modes** (audio + video; the mode discriminator
+    gates which option applies per the `depends_on` rules in this
     schema):
     - `interval`: split every N numeric-seconds.
     - `count`: split into N equal-duration pieces (integer 2..=200).
     - `cut_points`: explicit cut points in numeric-seconds (strictly
       increasing, no duplicates, each > 0 and < probed duration).
 
+    **Plus an audio-only `silence` mode** (`beta`, gated by the
+    `silence_mode_audio` feature): cut at detected silence gaps via
+    the worker's ffmpeg `silencedetect` filter. Video stays
+    three-mode.
+
     **GIF + PDF use range-based selection** instead of three modes:
     - GIF (`image_gif`): `frame_range` REQUIRED + `output_format`
       enum {png,webp,jpg}.
@@ -34,6 +39,8 @@ operation:
     - `interval`: `ceil(probed_duration / interval) <= 200`
     - `count`: enforced by the option's `min: 2 max: 200` range
     - `cut_points`: `cut_points.len() + 1 <= 200`
+    - `silence` (audio): resolved segment count (detected gaps + 1)
+      `<= 200`; preflight rejects as `invalid_options` (422)
     - PDF: resolved page count after expansion `<= 200`
       (cross-ref [`WgCqnMRa`](https://trello.com/c/WgCqnMRa))
     - GIF: resolved frame count after expansion `<= 200`
@@ -59,12 +66,16 @@ operation:
     via `processing_class`). No schema-side discriminator beyond MIME
     detection + `processing_class`.
 
-    `availability: beta` for the `audio` mime_group (worker live on
-    staging per lambdas #161 — shape-stable + opt-in, MUST NOT 422).
-    The `image_gif`, `document_pdf`, and `video` 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 those groups until then.
+    `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
+    `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
+    still-planned groups/classes until then.
 
     Per ADR-0014.
   default: false
@@ -72,13 +83,14 @@ operation:
 
   features:
     silence_mode_audio:
-      availability: planned
+      availability: beta
       description: |
         Silence-detect cut mode for audio (`mode: silence` —
-        Cinavia/Resemble territory, server-side silence detection).
-        OUT of V1 (Lambda support not yet shipped); declared as a
-        future-work feature here so SDK consumers see the gate.
-        Picked up as a separate post-launch ticket.
+        server-side silence detection in the audio split worker).
+        `beta`: shape-stable + opt-in. The worker is built; the mode
+        ships dark until the API regenerates enum validation to accept
+        `mode: silence`. The `silence` enum value carries a matching
+        `per_value_availability: beta` on `audio.mode`.
 
   mime_groups:
     # Animated GIF base — parallel mime_group naming follows the
@@ -161,13 +173,17 @@ operation:
       options:
         mode:
           type: enum
-          values: [interval, count, cut_points]
+          values: [interval, count, cut_points, silence]
           default: interval
+          per_value_availability:
+            silence: { availability: beta }
           description: |
             Split strategy:
             - `interval`: cut every `interval` seconds.
             - `count`: cut into `count` equal-duration pieces.
             - `cut_points`: cut at explicit timestamps.
+            - `silence`: cut at detected silence gaps (audio-only,
+              `beta` via the `silence_mode_audio` feature gate).
 
         interval:
           type: float
@@ -212,37 +228,79 @@ operation:
             200-output cap declaratively. Only valid when
             `mode: cut_points`.
 
+        silence_threshold_db:
+          type: float
+          max: 0.0
+          default: -50.0
+          depends_on: { mode: silence }
+          # Maps to the worker's silence-detection noise floor.
+          description: |
+            Noise floor below which audio counts as silence, in dBFS
+            (negative; 0.0 = full scale). Strictly negative in
+            practice; `max: 0.0` is the declarative ceiling (a 0 dB
+            "silence" floor is degenerate, like the strict bounds
+            documented in prose for `cut_points`). Only valid when
+            `mode: silence`.
+
+        silence_min_duration:
+          type: float
+          min: 0.001
+          default: 0.75
+          depends_on: { mode: silence }
+          # Maps to the worker's silence-detection minimum-duration parameter.
+          description: |
+            Minimum duration of a silence gap, in numeric seconds
+            (sub-second allowed), before it is treated as a cut point.
+            `min: 0.001` is the strict-positive sub-second idiom
+            (cf. `interval`). Only valid when `mode: silence`.
+
+        silence_handling:
+          type: enum
+          values: [keep_at_end]
+          default: keep_at_end
+          depends_on: { mode: silence }
+          description: |
+            How detected silence is handled at segment boundaries.
+            `keep_at_end`: trailing silence stays appended to the
+            preceding segment (no separate silence-only outputs).
+            Only valid when `mode: silence`.
+
         precision:
           type: enum
           values: [fast, exact]
           default: fast
+          # Don't use "keyframe" language here — that's video-only;
+          # audio drift is packet-boundary.
           description: |
             Cut precision. Under `fast`, audio cuts are
             packet-boundary approximate (drift bounded by codec
             packet size — typically <= 23ms for AAC, <= 26ms for
             MP3). Under `exact`, the Lambda re-encodes to align cuts
             precisely at the requested timestamps (slower, larger
-            output, but sample-accurate). Avoid "keyframe" language
-            — that's video-only; audio drift is packet-boundary.
+            output, but sample-accurate).
 
     # Video base — same three modes + precision + processing_class.
     # Long-form routes to `split-video-fargate` (same OperationType,
     # different worker per `processing_class`).
     video:
-      availability: planned
+      availability: beta
       mimes:
         - video/mp4
         - video/webm
+        - video/quicktime
       processing_class:
         short_form:
-          availability: planned
+          availability: beta
           constraints:
             max_input_duration: "PT5M"
             max_input_size_bytes: 524288000
             max_output_size_bytes: 524288000
         long_form:
-          # Routes to split-video-fargate worker per ADR-0014.
-          availability: planned
+          # 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).
+          availability: beta
           required_tier: pro
           constraints:                            # baseline = Pro
             max_input_duration: "PT12H"

package/operations/schemas/text_watermark.yaml

@@ -25,10 +25,10 @@ operation:
         text:
           type: string
           required: true
+          # Rendered with the bundled Liberation Sans (SIL OFL); a single
+          # text overlay is capped at 4 megapixels before rendering fails.
           description: |
-            Watermark text. Must be non-empty. Rendered with bundled
-            Liberation Sans (SIL OFL). A single text overlay is capped
-            at 4 megapixels before rendering fails.
+            Watermark text. Must be non-empty.
 
         font_size:
           type: float
@@ -59,11 +59,11 @@ operation:
           min: -360.0
           max: 360.0
           default: -45.0
+          # Tiled canvas is capped at 25 megapixels pre-rotation with a
+          # 5000 px maximum side length.
           description: |
             Rotation angle in degrees. Default -45° suits tiled mode
-            (angled diagonal pattern). Clamped to range. Tiled canvas is
-            capped at 25 megapixels pre-rotation with 5000 px maximum
-            side length.
+            (angled diagonal pattern). Clamped to range.
 
         watermark_mode:
           type: enum

package/operations/schemas/thumbnail.yaml

@@ -45,7 +45,7 @@ operation:
       mimes:
         - video/mp4
         - video/webm
-        - video/ogg
+        - video/quicktime
       processing_class:
         # F8 long-form video tier (per ticket I15-CONS). Thumbnail
         # extracts a single frame, so size/duration caps reflect

package/operations/schemas/video_text_watermark.yaml

@@ -58,9 +58,9 @@ operation:
         text:
           type: string
           required: true
+          # Rendered with the bundled Liberation Sans (SIL OFL).
           description: |
-            Watermark text. Must be non-empty. Rendered with bundled
-            Liberation Sans (SIL OFL).
+            Watermark text. Must be non-empty.
 
         font_size:
           type: float

package/operations/schemas/video_watermark.yaml

@@ -4,12 +4,15 @@ operation:
   type: video_watermark
   availability: beta
   description: |
-    Apply an image overlay (file or external source) onto a base video
+    Apply an image overlay onto a base video
     asset using FFmpeg's `overlay` filter. Multi-input role-based:
     exactly one input with `role: base` (the source video) + exactly
-    one with `role: overlay` (the watermark image). The overlay can be
-    an upload, an external_import handle, or a vault connection per
-    `WorkflowSource`.
+    one with `role: overlay` (the watermark image). Each input is a
+    `MultiInputSource` — an external_import handle, a vault connection,
+    or an upstream `job_output` (uploads are NOT referenced directly
+    inside inputs[]). To use an uploaded base or overlay, feed it through
+    a `passthrough` source job and reference it via `{ type: job_output,
+    from: <id> }` (per ticket 4som89Uh).
 
     **Dedicated operation, not an extension of `image_watermark`.**
     `image_watermark` is pure-Rust/no-FFmpeg and handles

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@giveitsmaller/contracts",
-  "version": "0.9.0",
+  "version": "0.17.0",
   "description": "Generated contract types for GISL (Give It Smaller)",
   "license": "MIT",
   "type": "module",
@@ -35,6 +35,8 @@
     "./operations/schemas/custom_luma.yaml": "./operations/schemas/custom_luma.yaml",
     "./operations/schemas/image_watermark.yaml": "./operations/schemas/image_watermark.yaml",
     "./operations/schemas/merge.yaml": "./operations/schemas/merge.yaml",
+    "./operations/schemas/passthrough.yaml": "./operations/schemas/passthrough.yaml",
+    "./operations/schemas/render_variants.yaml": "./operations/schemas/render_variants.yaml",
     "./operations/schemas/split.yaml": "./operations/schemas/split.yaml",
     "./operations/schemas/text_watermark.yaml": "./operations/schemas/text_watermark.yaml",
     "./operations/schemas/thumbnail.yaml": "./operations/schemas/thumbnail.yaml",