@giveitsmaller/contracts 0.40.0 → 0.42.0

package/operations/schemas/convert.yaml

@@ -81,12 +81,9 @@ operation:
           honored_on: [format_change]
           description: >-
             Background colour as a 6-digit hex (`#RRGGBB`, e.g. `#ffffff`) for
-            transparent images converted to JPEG (the format-change→JPEG
-            alpha-flatten — Output's transparency fill control). HEX ONLY: the
-            worker honours only `#RRGGBB` and silently drops a CSS named colour
-            (e.g. `magenta`) to the white default, so the `pattern` rejects a
-            non-hex value as `invalid_options` rather than advertising an inert
-            free-form string (e2e staging-verified 2026-06-22).
+            transparent images converted to JPEG (the alpha-flatten fill colour
+            when converting to JPEG). HEX ONLY: a non-hex value (e.g. a CSS named
+            colour) is rejected rather than silently falling back.
         metadata:
           type: enum
           values: [strip, keep]
@@ -94,32 +91,26 @@ operation:
           availability: planned
           honored_on: [format_change]
           description: >-
-            Metadata handling on the format-change (convert/transcoder) route.
-            `strip` = remove all EXIF/IPTC/XMP (default), `keep` = preserve. `planned`
-            — the convert worker re-encodes from pixels and does not yet preserve
-            metadata across a format change, so the API returns feature_not_available
-            (rather than "Unknown option" on a format-change request — e2e/api flagged
-            2026-06-23). This is a new (planned) surface, so it carries no deprecated
-            `all` alias — unlike compress.image.metadata, which keeps `all` for its
-            existing callers. Stable-flip gated on lambdas proving convert-route
-            metadata preservation; the honoured target subset may narrow (avif/heic
-            targets re-encode and cannot keep).
+            Metadata handling across a format change. `strip` = remove all
+            EXIF/IPTC/XMP (default), `keep` = preserve. `planned` — metadata is not
+            yet preserved across a format change. The honoured target subset may
+            narrow (avif/heic targets are re-encoded and cannot keep metadata).
         width:
           type: integer
           min: 1
           max: 16384
           honored_on: [format_change]
           description: >-
-            Resize-inside-Output: target width in pixels (1-16384; width*height <=
-            max_output_pixels). The convert worker resizes (Lanczos) before encode;
-            single transformed output. NOT honored for SVG input (the worker
-            rejects svg resize). Input-gated — see the resize comment above.
+            Target width in pixels (1-16384; width × height must not exceed the
+            group's maximum output area). Resizes the image before encoding (one
+            transformed output). NOT honored for SVG input. Optional; omit to keep
+            the source dimensions.
         height:
           type: integer
           min: 1
           max: 16384
           honored_on: [format_change]
-          description: "Resize-inside-Output: target height in pixels (1-16384; width*height <= max_output_pixels). Not honored for SVG input. See `width`."
+          description: "Target height in pixels (1-16384; width × height must not exceed the group's maximum output area). Not honored for SVG input. See `width`."
         fit:
           type: enum
           values: [max, crop, scale]
@@ -127,11 +118,11 @@ operation:
           depends_on: { width: set, height: set, logic: or }
           honored_on: [format_change]
           description: >-
-            Resize mode. `max` (default) = fit within bounds, preserving aspect ratio
-            and NEVER upscaling — it caps at the source dimensions. This IS the
-            "no-enlarge" behaviour (there is no separate `no_enlarge` flag — the
-            worker has no such key). `crop`/`scale` = exact dimensions (`scale`
-            deliberately enlarges past source). Applies only when width or height is set.
+            Resize mode. `max` (default) = fit within the given bounds, preserving
+            aspect ratio and never upscaling (caps at the source dimensions — this is
+            the "no-enlarge" behaviour). `crop`/`scale` = exact dimensions (`scale`
+            deliberately enlarges past the source). Applies only when width or height
+            is set.
         color_profile:
           type: enum
           values: [keep, srgb, strip]
@@ -139,22 +130,21 @@ operation:
           availability: planned
           honored_on: [format_change]
           description: >-
-            ICC colour-profile handling on the transcoder (format-change) route —
-            mirrors compress.image.color_profile (its own control, decoupled from
-            metadata). `keep` (default) = preserve; `srgb` = convert to sRGB
-            (incl. CMYK→sRGB); `strip` = drop. `planned` — the convert worker
-            re-encodes from pixels and does not yet preserve/convert the profile.
-            Declared HERE so the API re-validates the rewritten Output convert op.
+            Colour-profile handling — a dedicated control, separate from `metadata`
+            so that stripping metadata never silently shifts colours. `keep`
+            (default) = preserve the embedded colour profile; `srgb` = convert to
+            sRGB (also handles CMYK → sRGB); `strip` = drop the profile. `planned` —
+            not yet supported.
         auto_orient:
           type: boolean
           default: true
-          availability: planned
           honored_on: [format_change]
           description: >-
-            Bake EXIF orientation into the pixels on the transcoder (format-change)
-            route — mirrors compress.image.auto_orient. `planned` — the convert worker
-            does not yet apply the orientation transform. Declared HERE so the API
-            re-validates the rewritten Output convert op.
+            Bake EXIF orientation into the pixels (honour the camera/device rotation
+            tag) so the output displays upright everywhere, then drop the
+            now-redundant orientation tag. Default `true`; no-op for inputs without
+            an orientation tag. The format-change re-encodes from pixels, so other
+            (non-orientation) metadata is not carried across.
 
     # svg is VECTOR: it converts (rasterises) to a raster format, but CANNOT be
     # raster-resized — the convert worker rejects svg resize. Split out of
@@ -186,8 +176,8 @@ operation:
           honored_on: [format_change]
           description: >-
             Background colour as a 6-digit hex (`#RRGGBB`) for transparent SVG
-            rasterised to JPEG (alpha-flatten). HEX ONLY — non-hex is rejected as
-            `invalid_options` (see convert.image.background).
+            rasterised to JPEG (alpha-flatten). HEX ONLY — a non-hex value is
+            rejected (see convert.image.background).
 
     # gif is animated raster: it converts to a STILL image (first frame / rasterise —
     # the existing image targets, stable) AND — NEW, planned — to VIDEO (mp4/webm):
@@ -215,12 +205,10 @@ operation:
             Target format. The still-image targets (jpeg/png/webp/avif/gif/tiff) take
             the first frame / rasterise. `mp4` / `webm` are the GIF→VIDEO transcode
             targets — the animated GIF becomes a muted, play-once video (`mp4` =
-            H.264 / yuv420p / +faststart, plays everywhere; `webm` = VP9, smaller).
-            STABLE — worker-proven on staging (lambdas PR #268, deployed git-6783cb9:
-            gif→mp4 ~70% smaller / gif→webm ~84% smaller, valid containers +
-            worker-set Content-Type, real decode-every-frame transcode). GIFs are
-            silent (no audio stream); the GIF infinite-loop becomes a playback
-            attribute (`<video loop>`) the player sets, NOT baked into the file.
+            H.264, plays everywhere; `webm` = VP9, smaller), typically far smaller
+            than the original GIF. GIFs are silent (no audio stream); the GIF
+            infinite-loop becomes a playback attribute (`<video loop>`) the player
+            sets, NOT baked into the file.
         quality:
           type: integer
           min: 1
@@ -231,7 +219,7 @@ operation:
           description: >-
             Output quality for the lossy STILL-IMAGE targets (jpeg/webp/avif). The
             video targets (mp4/webm) use a sensible default encode quality in v1 —
-            there is no exposed CRF knob yet (planned-first; may be added later).
+            there is no exposed CRF knob yet (may be added later).
         background:
           type: string
           pattern: "^#[0-9a-fA-F]{6}$"
@@ -239,8 +227,8 @@ operation:
           honored_on: [format_change]
           description: >-
             Background colour as a 6-digit hex (`#RRGGBB`) for a transparent GIF
-            flattened to JPEG (alpha-flatten). HEX ONLY — non-hex is rejected as
-            `invalid_options` (see convert.image.background).
+            flattened to JPEG (alpha-flatten). HEX ONLY — a non-hex value is
+            rejected (see convert.image.background).
         metadata:
           type: enum
           values: [strip, keep]
@@ -248,25 +236,27 @@ operation:
           availability: planned
           honored_on: [format_change]
           description: >-
-            Metadata handling on the format-change route (still-image targets).
-            `planned` — mirrors convert.image.metadata (the convert worker does not
-            yet preserve metadata across a format change). The video targets carry no
+            Metadata handling for the still-image targets. `planned` — metadata is
+            not yet preserved across a format change. The video targets carry no
             EXIF/IPTC/XMP.
         width:
           type: integer
           min: 1
           max: 16384
+          depends_on: { output_format: [jpeg, png, webp, avif, gif, tiff] }
           honored_on: [format_change]
           description: >-
-            Resize-inside-Output: target width in pixels (1-16384; width*height <=
-            max_output_pixels). Applies to the still-image targets; for the planned
-            mp4/webm video targets, resize applicability is settled at the worker flip.
+            Target width in pixels (1-16384; width × height must not exceed the
+            group's maximum output area). Scoped to the STILL-IMAGE targets only —
+            resizing while transcoding to the mp4/webm video targets is not yet
+            supported, so width/height are not accepted for the video targets.
         height:
           type: integer
           min: 1
           max: 16384
+          depends_on: { output_format: [jpeg, png, webp, avif, gif, tiff] }
           honored_on: [format_change]
-          description: "Resize-inside-Output: target height in pixels (1-16384; width*height <= max_output_pixels). See `width`."
+          description: "Target height in pixels (1-16384; width × height must not exceed the group's maximum output area). Scoped to the still-image targets — see `width`."
         fit:
           type: enum
           values: [max, crop, scale]
@@ -276,7 +266,8 @@ operation:
           description: >-
             Resize mode. `max` (default) = fit within bounds, preserving aspect ratio
             and never upscaling; `crop`/`scale` = exact dimensions. Applies only when
-            width or height is set.
+            width or height is set — and width/height are still-image-only here, so fit
+            is transitively unreachable for the mp4/webm video targets.
         color_profile:
           type: enum
           values: [keep, srgb, strip]
@@ -285,23 +276,22 @@ operation:
           depends_on: { output_format: [jpeg, png, webp, avif, gif, tiff] }
           honored_on: [format_change]
           description: >-
-            ICC colour-profile handling (format-change route) — mirrors
-            compress.image.color_profile. `keep` (default)/`srgb`/`strip`. `planned`.
-            SCOPED via depends_on to the STILL-IMAGE targets only — the video targets
-            (mp4/webm) carry no ICC, so color_profile is not accepted for a gif→video
-            output (it would be inert). Declared HERE so the API re-validates the
-            rewritten Output op.
+            Colour-profile handling — `keep` (default) = preserve the embedded colour
+            profile; `srgb` = convert to sRGB; `strip` = drop the profile. `planned`
+            — not yet supported. Scoped to the STILL-IMAGE targets only — the video
+            targets (mp4/webm) carry no colour profile, so this is not accepted for a
+            gif→video output.
         auto_orient:
           type: boolean
           default: true
-          availability: planned
           depends_on: { output_format: [jpeg, png, webp, avif, gif, tiff] }
           honored_on: [format_change]
           description: >-
-            Bake EXIF orientation into the pixels (format-change route) — mirrors
-            compress.image.auto_orient. `planned`. SCOPED via depends_on to the
+            Bake EXIF orientation into the pixels so the output displays upright
+            everywhere. Default `true`; no-op for inputs without an orientation tag
+            (a GIF carries none, so this is a no-op for GIF input). Scoped to the
             STILL-IMAGE targets only — the video targets (mp4/webm) carry no EXIF
-            orientation. Declared HERE so the API re-validates the rewritten Output op.
+            orientation.
 
     video:
       mimes:
@@ -365,11 +355,10 @@ operation:
           # compress.video/compress.audio (planned) + merge per_input trim (float
           # SECONDS, "from beginning / from end") — NO cross-op divergence.
           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`]. Live for all video
-            outputs (gif/mp4/webm/ogg).
+            Trim from beginning in seconds (absent = from the start). The clip
+            is cut before transcoding — the user's "trim a video then make a GIF"
+            path. The kept clip is [`trim_start`, input_duration − `trim_end`]. Live
+            for all video outputs (gif/mp4/webm/ogg).
         trim_end:
           type: float
           min: 0
@@ -395,8 +384,8 @@ operation:
           default: 15
           depends_on: { output_format: gif }
           description: >
-            Output frame rate for video → GIF (ffmpeg `fps` filter). Lower = fewer
-            frames = smaller file. Video → GIF only.
+            Output frame rate for video → GIF. Lower = fewer frames = smaller file.
+            Video → GIF only.
         width:
           type: integer
           min: 1
@@ -413,7 +402,7 @@ operation:
           default: 256
           depends_on: { output_format: gif }
           description: >
-            GIF palette size (ffmpeg `palettegen` max_colors). Fewer colors = smaller file.
+            GIF palette size (the palette generation max colours). Fewer colors = smaller file.
         loop:
           type: integer
           min: -1
@@ -427,7 +416,7 @@ operation:
           default: bayer
           depends_on: { output_format: gif }
           description: >
-            GIF dithering method (ffmpeg `paletteuse`). `bayer` is a good size/quality
+            GIF dithering method. `bayer` is a good size/quality
             balance; `none` is smallest (may band).
 
     audio:
@@ -472,16 +461,12 @@ operation:
             Page selection (e.g. '1-5,8'). Each resolved page produces a
             separate output file. **Maximum 200 resolved entries per
             request** — aligns with the `OperationResult.outputs[]`
-            `maxItems: 200` cap per ADR-0009 §D5
-            (`docs/decisions/0009-multi-output-result-envelope.md`).
-            Expressions resolving to more than 200 entries (e.g.
-            `'1-201'`, `'1-100,102-205'`) are out of contract.
-            Duplicate or overlapping entries (e.g. `'1,1'`,
+            `maxItems: 200` cap. Expressions resolving to more than 200
+            entries (e.g. `'1-201'`, `'1-100,102-205'`) are out of
+            contract. Duplicate or overlapping entries (e.g. `'1,1'`,
             `'1-100,50-150'`) are counted toward the cap as parsed;
             deduplication, if any, is a runtime concern and is NOT part
-            of this contract. Enforcement at the API edge validator and
-            the Lambda runtime is tracked under WgCqnMRa follow-ups
-            (cross-repo: API + Lambdas `bFlEXizR`).
+            of this contract.
         dpi:
           type: integer
           min: 72

package/operations/schemas/custom_luma.yaml

@@ -10,28 +10,23 @@ operation:
     by Cloudinary's deprecated luma-matte custom transitions and
     intended as a paid-tier (`pro`+) creative feature.
 
-    **NOT** related to FFmpeg's `xfade=custom` filter (which is an
-    expression-mode parameter on the same `xfade` filter). The
-    `merge.transition.custom` value is tagged `planned` as an advisory
-    that points callers at this dedicated operation for caller-uploaded
-    luma-matte transitions.
+    **NOT** related to the `xfade=custom` expression-mode transition
+    parameter. The `merge.transition.custom` value is tagged `planned`
+    as an advisory that points callers at this dedicated operation for
+    caller-uploaded luma-matte transitions.
 
     Multi-input: exactly one input with `role: base` (the source
     video being transitioned) + exactly one input with
     `role: transition_mask` (the luma matte — a video whose pixel
     luminance drives the transition reveal — bright = revealed,
-    dark = held). Each input is a `MultiInputSource` — imported
+    dark = held). Each input is imported
     externally, referenced from a vault connection, or an upstream
     `job_output` (uploads are NOT referenced directly inside inputs[]).
     An uploaded base or mask enters via a `passthrough` source job
     referenced by `{ type: job_output, from: <id> }` (per ticket
     4som89Uh).
 
-    Per ADR-0001 §1.3 (Tension 1 — `planned` operations return
-    `feature_not_available` HTTP 422 until Lambda support ships).
-    Per ADR-0004 §"V2 JobDefinition" + plan v5 §F4 round 6
-    (codex-corrected — `xfade=custom` is an expression, not a
-    transition; this operation is the deliberate alternative).
+    `planned` — not yet supported.
   default: false
   input_model: multi
   sole_op: true   # bypasses V1 chain validation — must be the only operation in its job (ADR-0025)

package/operations/schemas/image_watermark.yaml

@@ -6,7 +6,7 @@ operation:
     Apply an image overlay onto a base media
     asset. Multi-input: exactly one input with role: base (the source
     asset) + exactly one with role: overlay (the watermark). Each input
-    is a `MultiInputSource` — an external_import handle, a vault
+    is 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 that job via
@@ -15,23 +15,32 @@ operation:
     Stable today for static-image bases (image/jpeg, image/png,
     image/webp); animated GIF bases are advertised as `planned` via
     the parallel `image_gif` mime_group — schema is contract-defined,
-    dispatch returns `feature_not_available` (422) until Lambda
-    support ships. Per Tension 1 (ADR-0001) + plan v5 §F4 round 6.
+    dispatch returns `feature_not_available` (422) until backend
+    support ships.
+
+    TIFF (image/tiff) and BMP (image/bmp) bases are likewise advertised
+    as `planned` via the parallel `image_tiff` / `image_bmp` mime_groups.
+    Both formats are already decodable and the worker's encode arms are a
+    cheap add (shared `image`-crate encoders), so each flips to `stable`
+    once its arm ships and is proven. Because watermark output mirrors the
+    input format (`produces: same_as_input`), advertising a base format is
+    only honest when the worker can both decode AND encode it — which
+    holds for TIFF/BMP but not for HEIC/AVIF (no encoder) or SVG (cannot
+    re-emit svg from a rasterised composite); those stay out of scope.
 
     **Video bases are NOT supported by `image_watermark`.** Use the
     dedicated `video_watermark` operation
-    (`schemas/operations/video_watermark.yaml`) which routes through
-    FFmpeg overlay + re-encode. Per ADR-0013.
+    (`schemas/operations/video_watermark.yaml`), which overlays and
+    re-encodes the video.
 
     **Audio is explicitly NOT supported.** For audio overlay (DJ tags,
     podcast intros, jingles), use the `audio_overlay` operation
     (declared in schemas/operations/audio_overlay.yaml at
     `availability: planned`).
 
-    Source capped at 100 megapixels for image bases (raised from 25MP —
-    lambdas #250, proven on the 45.9MP report case); per-frame caps for
-    animated GIF bases will be defined when the corresponding Lambda
-    support ships. Per ADR-0004 §"V2 JobDefinition" + plan v5 §F1.
+    Source capped at 100 megapixels for image bases; per-frame caps for
+    animated GIF bases will be defined when the corresponding backend
+    support ships.
   default: false
   input_model: multi
   sole_op: true   # bypasses V1 chain validation — must be the only operation in its job (ADR-0025)
@@ -55,11 +64,11 @@ operation:
       availability: planned
       description: |
         Allow up to 8 overlay inputs per job (currently capped at 1
-        overlay). Per-overlay placement via JobInputV2.per_input_options.
-        Lambda-side support not yet confirmed; tagged planned per
-        ADR-0001 §1.4. Scope is image-base only at the time this feature
-        was specified; extension to GIF / video bases tracks alongside
-        the corresponding mime_group `planned` → `stable` flips.
+        overlay). Per-overlay placement via per-input placement options.
+        Backend support not yet confirmed; tagged planned. Scope is
+        image-base only at the time this feature was specified; extension
+        to GIF / video bases tracks alongside the corresponding mime_group
+        `planned` → `stable` flips.
 
   mime_groups:
     image:
@@ -208,6 +217,149 @@ operation:
             width. Aspect ratio preserved. Omit to use the original
             overlay size.
 
+    # TIFF base — separate group because backend support ships in its own
+    # wave: the format is already decodable, but the encode arm (shared
+    # `image`-crate TiffEncoder) is pending. Tagged `planned` until the arm
+    # ships and is proven, then flips to `stable` (cross-repo UANjD38A).
+    image_tiff:
+      availability: planned
+      mimes:
+        - image/tiff
+      options:
+        anchor:
+          type: enum
+          values:
+            - top_left
+            - top_center
+            - top_right
+            - center_left
+            - center
+            - center_right
+            - bottom_left
+            - bottom_center
+            - bottom_right
+          default: bottom_right
+          description: |
+            9-grid anchor position on the base image. Combined with
+            margin_x and margin_y for fine-grained offset from the
+            anchor point.
+
+        margin_x:
+          type: string
+          pattern: '^\d+(\.\d+)?(px|%)$'
+          default: "0px"
+          description: |
+            Horizontal offset from the anchor in pixels or percentage of
+            base width. Anchor-relative; positive moves toward the image
+            centre.
+
+            **`anchor: center` exception.** Same rejection rule as the
+            `image` mime_group — non-zero `margin_x` with
+            `anchor: center` is rejected by the API at workflow-create
+            time as `invalid_options` (HTTP 422).
+
+        margin_y:
+          type: string
+          pattern: '^\d+(\.\d+)?(px|%)$'
+          default: "0px"
+          description: |
+            Vertical offset from the anchor in pixels or percentage of
+            base height. Anchor-relative; positive moves toward the image
+            centre.
+
+            **`anchor: center` exception.** Same rejection rule as the
+            `image` mime_group — non-zero `margin_y` with
+            `anchor: center` is rejected by the API at workflow-create
+            time as `invalid_options` (HTTP 422).
+
+        opacity:
+          type: float
+          min: 0.0
+          max: 1.0
+          default: 0.5
+          description: |
+            Overlay opacity (0 = fully transparent, 1 = fully opaque).
+            Clamped to range.
+
+        overlay_width:
+          type: string
+          pattern: '^\d+(\.\d+)?(px|%)$'
+          description: |
+            Optional overlay width as pixels or percentage of base
+            width. Aspect ratio preserved. Omit to use the original
+            overlay size.
+
+    # BMP base — separate group for the same reason as image_tiff: decode
+    # is ready, the encode arm (shared `image`-crate BmpEncoder) is pending.
+    # Tagged `planned` until the arm ships and is proven (cross-repo UANjD38A).
+    image_bmp:
+      availability: planned
+      mimes:
+        - image/bmp
+      options:
+        anchor:
+          type: enum
+          values:
+            - top_left
+            - top_center
+            - top_right
+            - center_left
+            - center
+            - center_right
+            - bottom_left
+            - bottom_center
+            - bottom_right
+          default: bottom_right
+          description: |
+            9-grid anchor position on the base image. Combined with
+            margin_x and margin_y for fine-grained offset from the
+            anchor point.
+
+        margin_x:
+          type: string
+          pattern: '^\d+(\.\d+)?(px|%)$'
+          default: "0px"
+          description: |
+            Horizontal offset from the anchor in pixels or percentage of
+            base width. Anchor-relative; positive moves toward the image
+            centre.
+
+            **`anchor: center` exception.** Same rejection rule as the
+            `image` mime_group — non-zero `margin_x` with
+            `anchor: center` is rejected by the API at workflow-create
+            time as `invalid_options` (HTTP 422).
+
+        margin_y:
+          type: string
+          pattern: '^\d+(\.\d+)?(px|%)$'
+          default: "0px"
+          description: |
+            Vertical offset from the anchor in pixels or percentage of
+            base height. Anchor-relative; positive moves toward the image
+            centre.
+
+            **`anchor: center` exception.** Same rejection rule as the
+            `image` mime_group — non-zero `margin_y` with
+            `anchor: center` is rejected by the API at workflow-create
+            time as `invalid_options` (HTTP 422).
+
+        opacity:
+          type: float
+          min: 0.0
+          max: 1.0
+          default: 0.5
+          description: |
+            Overlay opacity (0 = fully transparent, 1 = fully opaque).
+            Clamped to range.
+
+        overlay_width:
+          type: string
+          pattern: '^\d+(\.\d+)?(px|%)$'
+          description: |
+            Optional overlay width as pixels or percentage of base
+            width. Aspect ratio preserved. Omit to use the original
+            overlay size.
+
     # Video base mime_group REMOVED per ADR-0013 — video watermarking
     # is now owned by the dedicated `video_watermark` operation
     # (`schemas/operations/video_watermark.yaml`). The previous

package/operations/schemas/merge.yaml

@@ -33,7 +33,7 @@ operation:
           type: enum
           values: [gif, video]
           required: true
-          description: "Result format: animated GIF or slideshow video. No default — caller must pick explicitly (image/collage and document/PDF concat are not supported by the V1 merge Lambda)."
+          description: "Result format: animated GIF or slideshow video. No default — caller must pick explicitly (image/collage and document/PDF concat are not supported by V1 merge)."
         # --- Options for output_type: gif ---
         delay:
           type: integer
@@ -397,7 +397,7 @@ operation:
             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
+            input's own duration, enforced at processing time, not statically
             bounded here.
         trim_end:
           type: float
@@ -406,7 +406,7 @@ operation:
             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
+            duration, enforced at processing time, not statically bounded
             here.
 
     audio:
@@ -491,7 +491,7 @@ operation:
             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
+            input's own duration, enforced at processing time, not statically
             bounded here.
         trim_end:
           type: float
@@ -500,5 +500,5 @@ operation:
             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
+            duration, enforced at processing time, not statically bounded
             here.

package/operations/schemas/passthrough.yaml

@@ -6,13 +6,13 @@ operation:
   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
+    no compression, no transformation, no backend 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`
+    V2 narrows the input source to exclude upload-direct (a multi-input source
     — 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
@@ -38,8 +38,8 @@ operation:
     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).
+    [`4som89Uh`](https://trello.com/c/4som89Uh) (planned→beta flip;
+    self-complete code deployed API-side).
   default: false
   input_model: single