@giveitsmaller/contracts 0.40.0 → 0.42.0

package/operations/schemas/split.yaml

@@ -19,8 +19,7 @@ operation:
 
     **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.
+    server-side silence detection. Video stays three-mode.
 
     **GIF + PDF use range-based selection** instead of three modes:
     - GIF (`image_gif`): `frame_range` REQUIRED + `output_format`
@@ -29,11 +28,11 @@ operation:
       exclusive per `depends_on`).
 
     **Wire format**: numeric seconds (floats allowed for sub-second
-    precision). NOT ISO 8601 duration strings. Matches FFmpeg /
-    Cloudinary / Shotstack / AWS MediaConvert conventions.
+    precision). NOT ISO 8601 duration strings. Matches common
+    video-tooling conventions.
 
-    **200-output hard cap** per ADR-0009 §D5
-    (`OperationResult.outputs[].maxItems: 200`). Preflight rejects
+    **200-output hard cap** (`OperationResult.outputs[].maxItems:
+    200`). Preflight rejects
     requests exceeding this BEFORE work as `invalid_options` (422).
     Cap math by mode:
     - `interval`: `ceil(probed_duration / interval) <= 200`
@@ -48,7 +47,7 @@ operation:
     **Output naming**: 3-digit zero-padded — `output-001` ..
     `output-200`. Matches the convert PDF→N precedent.
 
-    **Output envelope binding** (per ADR-0014 + ADR-0009 §D2):
+    **Output envelope binding**:
     - `image_gif`: `PositionIndexed` (frame stream-position 0-based
       ordinal)
     - `document_pdf`: `PageIndexed` (1-based gapless page index)
@@ -61,25 +60,18 @@ operation:
     NOT apply to GIF or PDF (frame extraction is exact and PDF page
     selection is exact by definition).
 
-    **Long-form video** routes to a separate `split-video-fargate`
-    Lambda (same `split` OperationType, different worker; routing
-    via `processing_class`). No schema-side discriminator beyond MIME
-    detection + `processing_class`.
+    **Long-form video** routes to a separate long-form processing
+    path (same `split` OperationType; routing via `processing_class`).
+    No schema-side discriminator beyond MIME detection +
+    `processing_class`.
 
     `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
-    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
-    still-planned groups/classes until then.
-
-    Per ADR-0014.
+    (shape-stable + opt-in, MUST NOT 422). Video activates **both
+    classes**: `video.processing_class.short_form` AND `long_form` are
+    `beta`. The `image_gif` and `document_pdf` mime_groups stay
+    `availability: planned` until their cross-repo backend support ships;
+    dispatch returns `feature_not_available` (422) for the still-planned
+    groups/classes until then.
   default: false
   input_model: single
   sole_op: true   # bypasses V1 chain validation — must be the only operation in its job (ADR-0025)
@@ -89,11 +81,10 @@ operation:
       availability: beta
       description: |
         Silence-detect cut mode for audio (`mode: silence` —
-        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`.
+        server-side silence detection). `beta`: shape-stable + opt-in.
+        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
@@ -283,7 +274,7 @@ operation:
             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
+            MP3). Under `exact`, the server re-encodes to align cuts
             precisely at the requested timestamps (slower, larger
             output, but sample-accurate).
 
@@ -378,6 +369,6 @@ operation:
           description: |
             Cut precision. Under `fast`, video cuts are keyframe-
             aligned (drift bounded by GOP size — typically up to 1-2
-            seconds depending on encoder). Under `exact`, the Lambda
+            seconds depending on encoder). Under `exact`, the backend
             re-encodes to align cuts precisely at the requested
             timestamps (slower, larger output, but frame-accurate).

package/operations/schemas/text_watermark.yaml

@@ -5,15 +5,24 @@ operation:
   description: |
     Render a text overlay onto an image using bundled Liberation Sans
     (SIL OFL). Single-input — text comes from options, not from a file
-    input. Source capped at 100 megapixels in `single` mode (raised from
-    25MP — lambdas #250, proven on the 45.9MP report case). `tiled` mode
-    keeps the 25-megapixel canvas bound (see `tile_spacing` /
-    `watermark_mode`). Per ADR-0004 §"V2 JobDefinition" + plan v5 §F1.
+    input. Source capped at 100 megapixels in `single` mode. `tiled`
+    mode keeps the 25-megapixel canvas bound (see `tile_spacing` /
+    `watermark_mode`).
 
     Two rendering modes:
     - `single`: one label rendered at the anchor + margin position.
     - `tiled`: text tiled across the source image (Cinavia / Adobe Stock
       pattern); rotation default -45° and tile_spacing controls density.
+
+    Stable today for image/jpeg, image/png, image/webp inputs. TIFF
+    (image/tiff) and BMP (image/bmp) inputs are advertised as `planned`
+    via the parallel `image_tiff` / `image_bmp` mime_groups — both 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. Output mirrors the input format
+    (`produces: same_as_input`), so a format is only advertised when the
+    worker can both decode AND encode it; HEIC/AVIF (no encoder) and SVG
+    (cannot re-emit svg from a rasterised composite) stay out of scope.
   default: false
   input_model: single
   sole_op: true   # bypasses V1 chain validation — must be the only operation in its job (ADR-0025)
@@ -148,3 +157,252 @@ operation:
             Text overlay opacity. Default 1.0 — the alpha channel of
             `color` already encodes transparency, so opacity is usually
             left at 1.0 and transparency is set via the color hex.
+
+    # TIFF input — 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).
+    # Text-rendering options are format-independent, so the shape mirrors
+    # the canonical `image` group exactly.
+    image_tiff:
+      availability: planned
+      mimes:
+        - image/tiff
+      options:
+        text:
+          type: string
+          required: true
+          description: |
+            Watermark text. Must be non-empty.
+
+        font_size:
+          type: float
+          min: 8.0
+          max: 512.0
+          default: 48.0
+          description: Font size in pixels. Clamped to range.
+
+        color:
+          type: string
+          default: "#FFFFFF80"
+          pattern: '^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$'
+          description: |
+            Text colour as hex RGB (#RRGGBB) or RGBA (#RRGGBBAA).
+            Default is white with 50% alpha.
+
+        font_family:
+          type: enum
+          values:
+            - liberation_sans
+          default: liberation_sans
+          description: |
+            Font family. V2.0 ships with bundled Liberation Sans only;
+            user-uploaded fonts are a future extension (separate ticket).
+
+        rotation:
+          type: float
+          min: -360.0
+          max: 360.0
+          default: -45.0
+          description: |
+            Rotation angle in degrees. Default -45° suits tiled mode
+            (angled diagonal pattern). Clamped to range.
+
+        watermark_mode:
+          type: enum
+          values: [single, tiled]
+          default: single
+          description: |
+            Rendering mode:
+            - `single`: one label placed at the anchor + margin offset.
+            - `tiled`: repeated tiles across the entire source image at
+              the rotation angle.
+
+        tile_spacing:
+          type: integer
+          min: 0
+          max: 1000
+          depends_on: { watermark_mode: tiled }
+          description: |
+            Spacing between tiled labels in pixels. Defaults to font_size
+            when omitted. Only applies when watermark_mode is tiled.
+
+        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. For watermark_mode: single, the text
+            label is placed at this anchor + margin_x/margin_y offset.
+            For watermark_mode: tiled, anchor is ignored (tiles fill the
+            source image).
+
+        margin_x:
+          type: string
+          pattern: '^\d+(\.\d+)?(px|%)$'
+          default: "0px"
+          description: |
+            Horizontal offset from the anchor as pixels (e.g. "40px") or
+            percentage of base width (e.g. "5%"). Direction is
+            anchor-relative. Ignored when watermark_mode: tiled.
+
+            **`anchor: center` exception** (watermark_mode: single only).
+            Non-zero `margin_x` combined with `anchor: center` is rejected
+            by the API at workflow-create time as `invalid_options`
+            (HTTP 422). Not applicable to watermark_mode: tiled, where
+            anchor + margin are ignored entirely.
+
+        margin_y:
+          type: string
+          pattern: '^\d+(\.\d+)?(px|%)$'
+          default: "0px"
+          description: |
+            Vertical offset from the anchor as pixels or percentage of
+            base height. Ignored when watermark_mode: tiled.
+
+            **`anchor: center` exception** (watermark_mode: single only).
+            Same rejection rule as `margin_x` — 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: 1.0
+          description: |
+            Text overlay opacity. Default 1.0 — the alpha channel of
+            `color` already encodes transparency, so opacity is usually
+            left at 1.0 and transparency is set via the color hex.
+
+    # BMP input — 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:
+        text:
+          type: string
+          required: true
+          description: |
+            Watermark text. Must be non-empty.
+
+        font_size:
+          type: float
+          min: 8.0
+          max: 512.0
+          default: 48.0
+          description: Font size in pixels. Clamped to range.
+
+        color:
+          type: string
+          default: "#FFFFFF80"
+          pattern: '^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$'
+          description: |
+            Text colour as hex RGB (#RRGGBB) or RGBA (#RRGGBBAA).
+            Default is white with 50% alpha.
+
+        font_family:
+          type: enum
+          values:
+            - liberation_sans
+          default: liberation_sans
+          description: |
+            Font family. V2.0 ships with bundled Liberation Sans only;
+            user-uploaded fonts are a future extension (separate ticket).
+
+        rotation:
+          type: float
+          min: -360.0
+          max: 360.0
+          default: -45.0
+          description: |
+            Rotation angle in degrees. Default -45° suits tiled mode
+            (angled diagonal pattern). Clamped to range.
+
+        watermark_mode:
+          type: enum
+          values: [single, tiled]
+          default: single
+          description: |
+            Rendering mode:
+            - `single`: one label placed at the anchor + margin offset.
+            - `tiled`: repeated tiles across the entire source image at
+              the rotation angle.
+
+        tile_spacing:
+          type: integer
+          min: 0
+          max: 1000
+          depends_on: { watermark_mode: tiled }
+          description: |
+            Spacing between tiled labels in pixels. Defaults to font_size
+            when omitted. Only applies when watermark_mode is tiled.
+
+        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. For watermark_mode: single, the text
+            label is placed at this anchor + margin_x/margin_y offset.
+            For watermark_mode: tiled, anchor is ignored (tiles fill the
+            source image).
+
+        margin_x:
+          type: string
+          pattern: '^\d+(\.\d+)?(px|%)$'
+          default: "0px"
+          description: |
+            Horizontal offset from the anchor as pixels (e.g. "40px") or
+            percentage of base width (e.g. "5%"). Direction is
+            anchor-relative. Ignored when watermark_mode: tiled.
+
+            **`anchor: center` exception** (watermark_mode: single only).
+            Non-zero `margin_x` combined with `anchor: center` is rejected
+            by the API at workflow-create time as `invalid_options`
+            (HTTP 422). Not applicable to watermark_mode: tiled, where
+            anchor + margin are ignored entirely.
+
+        margin_y:
+          type: string
+          pattern: '^\d+(\.\d+)?(px|%)$'
+          default: "0px"
+          description: |
+            Vertical offset from the anchor as pixels or percentage of
+            base height. Ignored when watermark_mode: tiled.
+
+            **`anchor: center` exception** (watermark_mode: single only).
+            Same rejection rule as `margin_x` — 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: 1.0
+          description: |
+            Text overlay opacity. Default 1.0 — the alpha channel of
+            `color` already encodes transparency, so opacity is usually
+            left at 1.0 and transparency is set via the color hex.

package/operations/schemas/thumbnail.yaml

@@ -61,6 +61,76 @@ operation:
           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)."
+        background:
+          type: string
+          pattern: "^#[0-9a-fA-F]{6}$"
+          depends_on: { format: jpg }
+          description: >-
+            Background colour as a 6-digit hex (`#RRGGBB`, e.g. `#ffffff`) for a
+            transparent image (e.g. PNG/WebP with alpha) resized to an opaque JPG
+            thumbnail — the alpha-flatten fill colour. Mirrors
+            convert.image.background. HEX ONLY: a non-hex value (e.g. a CSS named
+            colour) is rejected rather than advertising an inert free-form string.
+            When omitted, transparency is flattened onto white. JPG output only:
+            PNG/WebP keep alpha, so the flatten (and this option) do not apply.
+
+    # SVG input (planned, UANjD38A). SVG is split into its own parallel mime_group
+    # (group-level `availability: planned`, which the API gates -> feature_not_available)
+    # rather than tagged inside the stable `image` group, because per-MIME planned is
+    # advisory/not enforced. SVG rasterises to a bitmap cleanly, so render->resize for
+    # thumbnail is feasible. Flip planned -> stable
+    # (or beta) once the worker proves svg-rasterise input. Shares the `image` group's
+    # option shape (FORMAT.md "Parallel groups").
+    image_svg:
+      availability: planned
+      mimes:
+        - image/svg+xml
+      max_output_pixels: 16000000
+      options:
+        # IMAGE input is a full resizer (Lanczos): width/height accept the
+        # worker's real 1-16384px range (area-capped above) — this op is the
+        # image-resize path, surfaced in the UI as "Resize", not only thumbnails.
+        width:
+          type: integer
+          min: 1
+          max: 16384
+          required: true
+          description: "Target width in pixels (1-16384; width*height <= 16MP). For image input this is a full resize, not just a small preview."
+        height:
+          type: integer
+          min: 1
+          max: 16384
+          required: true
+          description: "Target height in pixels (1-16384; width*height <= 16MP). For image input this is a full resize, not just a small preview."
+        fit:
+          type: enum
+          values: [max, crop, scale]
+          default: crop
+          description: "Resize mode"
+        format:
+          type: enum
+          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)."
+        background:
+          type: string
+          pattern: "^#[0-9a-fA-F]{6}$"
+          depends_on: { format: jpg }
+          description: >-
+            Background colour as a 6-digit hex (`#RRGGBB`, e.g. `#ffffff`) for a
+            transparent image (e.g. PNG/WebP with alpha) resized to an opaque JPG
+            thumbnail — the alpha-flatten fill colour. Mirrors
+            convert.image.background. HEX ONLY: a non-hex value (e.g. a CSS named
+            colour) is rejected rather than advertising an inert free-form string.
+            When omitted, transparency is flattened onto white. JPG output only:
+            PNG/WebP keep alpha, so the flatten (and this option) do not apply.
 
     video:
       mimes:
@@ -104,13 +174,13 @@ operation:
           min: 1
           max: 16384
           required: true
-          description: "Target width in pixels (1-16384; width*height <= 16MP). Rounded down to an even number by the worker."
+          description: "Target width in pixels (1-16384; width*height <= 16MP). Rounded down to an even number."
         height:
           type: integer
           min: 1
           max: 16384
           required: true
-          description: "Target height in pixels (1-16384; width*height <= 16MP). Rounded down to an even number by the worker."
+          description: "Target height in pixels (1-16384; width*height <= 16MP). Rounded down to an even number."
         fit:
           type: enum
           values: [max, crop, scale]
@@ -157,7 +227,7 @@ operation:
           description: >-
             1-based index of the printed page to render, after print-layout
             pagination is applied. For office formats this is the page in the
-            LibreOffice PDF export — NOT a 1:1 sheet/slide index: a spreadsheet
+            document's print layout — NOT a 1:1 sheet/slide index: a spreadsheet
             sheet may span multiple printed pages and multi-sheet workbooks
             paginate their sheets in order. For PDF inputs it is the PDF page
             number directly.

package/operations/schemas/video_text_watermark.yaml

@@ -5,29 +5,25 @@ operation:
   availability: planned
   description: |
     Render a text overlay onto a base video using bundled Liberation
-    Sans (SIL OFL) via FFmpeg's `drawtext` filter. Single-input — the
-    text and its styling come from options, not from a file input.
-    Per ADR-0013.
+    Sans (SIL OFL). Single-input — the text and its styling come from
+    options, not from a file input.
 
     **Dedicated operation, not an extension of `text_watermark`.**
-    `text_watermark` renders onto images (single-pass Rust path);
-    `video_text_watermark` renders per-frame via FFmpeg drawtext +
-    re-encode (overlay = pixel modification, no stream-copy escape).
-    Different runtime, different deploy unit.
+    `text_watermark` renders onto images (single-pass); per-frame video
+    text rendering requires a re-encode (overlay = pixel modification,
+    no stream-copy escape). Different runtime.
 
     **Audio passthrough.** The base video's audio stream is preserved
-    unchanged via FFmpeg stream-copy — the watermark applies to the
-    visual track only.
+    unchanged (stream-copied) — the watermark applies to the visual
+    track only.
 
     Two rendering modes (mirrors `text_watermark`):
     - `single`: one label rendered at the anchor + margin position.
     - `tiled`: text tiled across the source frames at the rotation
       angle.
 
-    `availability: planned` until the cross-repo Lambda support ships;
-    dispatch returns `feature_not_available` (422) until then. Per
-    ADR-0013 + lambdas pre-launch epic Wave A (ticket
-    [`4NrRPCgh`](https://trello.com/c/4NrRPCgh)).
+    `availability: planned` until the cross-repo backend support ships;
+    dispatch returns `feature_not_available` (422) until then.
   default: false
   input_model: single
   sole_op: true   # bypasses V1 chain validation — must be the only operation in its job (ADR-0025)

package/operations/schemas/video_watermark.yaml

@@ -5,37 +5,33 @@ operation:
   availability: beta
   description: |
     Apply an image overlay onto a base video
-    asset using FFmpeg's `overlay` filter. Multi-input role-based:
+    asset. Multi-input role-based:
     exactly one input with `role: base` (the source video) + exactly
     one with `role: overlay` (the watermark image). Each input is a
-    `MultiInputSource` — an external_import handle, a vault connection,
+    a multi-input source — 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
-    image-on-image overlay only. `video_watermark` requires FFmpeg's
-    overlay filter + re-encode + a different deploy unit (no
-    stream-copy escape — overlay = pixel modification). Per ADR-0013.
+    `image_watermark` handles image-on-image overlay only.
+    `video_watermark` requires an overlay + re-encode (no stream-copy escape — overlay = pixel modification).
 
     **Audio passthrough.** The base video's audio stream is preserved
-    unchanged via FFmpeg stream-copy — the watermark applies to the
-    visual track only.
+    unchanged (stream-copied) — the watermark applies to the visual
+    track only.
 
     Activated to `availability: beta` (Wave A, ticket
-    [`c3uthIP4`](https://trello.com/c/c3uthIP4)): the cross-repo Lambda
-    backend is live (API accepts + publishes via the operations SNS
+    [`c3uthIP4`](https://trello.com/c/c3uthIP4)): the cross-repo backend
+    is live (API accepts + publishes via the operations SNS
     topic), so the operation and its `short_form` processing class are
     shape-stable + opt-in and MUST NOT return `feature_not_available`.
-    `long_form` stays `planned` (no live Fargate worker yet — its
-    long-form path is not provisioned) and the `multi_overlay_stack`
-    feature stays `planned` (Lambda support unconfirmed); requesting
-    those planned sub-features DOES still return `feature_not_available`
-    until they are separately activated. Per ADR-0013 + lambdas
-    pre-launch epic Wave A (ticket
-    [`SlluxMBN`'s sibling `4NrRPCgh`](https://trello.com/c/4NrRPCgh)).
+    `long_form` stays `planned` (its long-form path is not yet
+    provisioned) and the `multi_overlay_stack` feature stays `planned`
+    (backend support unconfirmed); requesting those planned sub-features
+    DOES still return `feature_not_available` until they are separately
+    activated.
   default: false
   input_model: multi
   sole_op: true   # bypasses V1 chain validation — must be the only operation in its job (ADR-0025)
@@ -55,10 +51,9 @@ 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. Mirrors the same-named feature on
-        `image_watermark`.
+        overlay). Per-overlay placement via per-input placement options.
+        Backend support not yet confirmed; tagged planned. Mirrors
+        the same-named feature on `image_watermark`.
 
   mime_groups:
     video:

package/package.json

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