@giveitsmaller/contracts 0.9.0 → 0.17.0

package/operations/schemas/archive.yaml

@@ -19,4 +19,4 @@ operation:
       type: enum
       values: [flat, by_job]
       default: flat
-      description: "flat = all files in root, by_job = subfolder per source job"
+      description: "flat = all files together at the top level; by_job = a separate subfolder for each source"

package/operations/schemas/audio_overlay.yaml

@@ -20,9 +20,12 @@ operation:
     (`features.multi_overlay_stack`) but Lambda-side implementation
     deferred.
 
-    The overlay can be uploaded directly, imported externally, or
-    referenced from a vault connection per `WorkflowSource` (from
-    I10). The base is whatever single-asset source the workflow
+    Each input is a `MultiInputSource` — imported externally,
+    referenced from a vault connection, or an upstream `job_output`
+    (uploads are NOT referenced directly inside inputs[]). An uploaded
+    overlay or base enters via a `passthrough` source job referenced by
+    `{ type: job_output, from: <id> }` (per ticket 4som89Uh). The base
+    is whatever single-asset source the workflow
     upstream has — for `mime_groups.audio`, the base is the primary
     audio track; for `mime_groups.video`, the overlay is mixed into
     the video's audio track and the visual track passes through
@@ -36,6 +39,18 @@ operation:
   min_inputs: 2
   max_inputs: 2
 
+  # Per-role input-count constraints (ADR-0015). Both roles REQUIRED,
+  # exactly one each. Arithmetic-consistency rule (CI-checked):
+  # - sum(role.min) == min_inputs  (1 + 1 = 2)
+  # - sum(role.max) == max_inputs  (1 + 1 = 2)
+  per_role_cardinality:
+    base:
+      min: 1
+      max: 1
+    overlay:
+      min: 1
+      max: 1
+
   features:
     multi_overlay_stack:
       availability: planned
@@ -132,11 +147,12 @@ operation:
           default: mix
           description: |
             How the overlay combines with the base audio:
-            - `mix`: simple sum (overlay + base; both audible).
-            - `duck`: side-chain compress the base under the overlay
-              (base attenuates while overlay plays — broadcast pattern).
+            - `mix`: both play together (overlay added on top; both audible).
+            - `duck`: the base audio dips while the overlay plays, then
+              returns — the broadcast voice-over pattern.
             - `replace`: mute the base for the overlay's duration
               (overlay only; useful for hard-cut station IDs).
+          # `duck` is implemented as a side-chain compressor in the worker.
           per_value_availability:
             duck: { availability: planned }
 
@@ -147,8 +163,8 @@ operation:
           default: -20.0
           depends_on: { mode: duck }
           description: |
-            Side-chain threshold (dB). Base audio is ducked when the
-            overlay exceeds this level. Only applies when `mode: duck`.
+            Level (dB) the overlay must reach before the base audio
+            ducks. Only applies when `mode: duck`.
 
         duck_ratio:
           type: float
@@ -157,8 +173,8 @@ operation:
           default: 4.0
           depends_on: { mode: duck }
           description: |
-            Side-chain compression ratio. Higher values produce more
-            aggressive ducking. Only applies when `mode: duck`.
+            How strongly the base ducks — higher values dip it more
+            aggressively. Only applies when `mode: duck`.
 
         duck_attack_ms:
           type: integer
@@ -304,7 +320,7 @@ operation:
           values: [mix, duck, replace]
           default: mix
           description: |
-            Same modes as the audio mime_group. `replace` mutes the
+            Same modes as for audio overlays. `replace` mutes the
             base video's audio for the overlay's duration.
           per_value_availability:
             duck: { availability: planned }
@@ -315,7 +331,7 @@ operation:
           max: 0.0
           default: -20.0
           depends_on: { mode: duck }
-          description: "Side-chain threshold (dB). Only applies when `mode: duck`."
+          description: "Level (dB) the overlay must reach before the base audio ducks. Only applies when `mode: duck`."
 
         duck_ratio:
           type: float
@@ -323,7 +339,7 @@ operation:
           max: 20.0
           default: 4.0
           depends_on: { mode: duck }
-          description: "Side-chain compression ratio. Only applies when `mode: duck`."
+          description: "How strongly the base ducks — higher values dip it more aggressively. Only applies when `mode: duck`."
 
         duck_attack_ms:
           type: integer

package/operations/schemas/audio_to_video.yaml

@@ -65,6 +65,7 @@ operation:
         - audio/flac
         - audio/ogg
         - audio/opus
+        - audio/mp4
         - audio/x-m4a
       options:
         output_resolution:
@@ -100,10 +101,10 @@ operation:
           min: 1
           max: 60
           default: 2
+          # Low framerate + the encoder's still-image tuning keeps size tiny.
           description: |
-            Output video framerate. Default `2` fps — combined with
-            FFmpeg `-tune stillimage`, keeps the file size tiny for
-            the common case of a single still overlay. Raise for
+            Output video framerate. Default `2` fps keeps the file size
+            tiny for the common case of a single still overlay. Raise for
             animated overlays (not supported in V1 — overlay must be
             a still image) or platform requirements (e.g. YouTube
             recommends 24+ fps; some platforms accept lower).
@@ -112,8 +113,8 @@ operation:
           values: [mp4]
           default: mp4
           description: |
-            Output container format. V1 supports `mp4` only. Future
-            additions (webm, mov) await Lambda follow-up.
+            Output container format. V1 supports `mp4` only; webm and mov
+            are planned additions.
 
   # NOTE: role-MIME constraint (base MUST be audio, overlay MUST be
   # image) is documented in prose only for V1. ADR-0015 records this

package/operations/schemas/audio_watermark.yaml

@@ -76,7 +76,7 @@ operation:
             Optional caller-supplied payload to embed (max 256
             characters). Use cases: ownership marker, distribution
             channel ID, license key. When omitted, the server
-            generates a UUID-v7 `watermark_id` and embeds that
+            generates an identifier automatically and embeds that
             instead; the generated ID is returned on
             `OperationResult` so the caller can subsequently call
             the decode endpoint to verify.
@@ -85,18 +85,20 @@ operation:
           type: enum
           values: [auto, psychoacoustic, neural]
           default: auto
+          # `psychoacoustic` follows Resemble's open-source PerTh
+          # library as the path-to-prod reference; `neural` is a
+          # deep-generative embedding.
           description: |
             Watermarking algorithm:
             - `auto`: server selects the best available method for the
               input (currently maps to `psychoacoustic`; will widen as
               `neural` ships).
-            - `psychoacoustic`: classical masking-curve embedding.
-              Resemble's open-source PerTh library provides the path-
-              to-prod reference implementation. Survives MP3/AAC at
-              moderate bitrates and broadcast chains.
-            - `neural`: ML-based embedding (deep generative). Higher
-              survival under aggressive transcoding + analog-hole
-              capture; longer encoding time + non-deterministic.
+            - `psychoacoustic`: hides the mark below what the ear can
+              hear, so it stays inaudible. Survives MP3/AAC at moderate
+              bitrates and broadcast chains.
+            - `neural`: machine-learning embedding. Higher survival
+              under aggressive re-encoding and microphone re-recording;
+              longer encoding time and non-deterministic.
           per_value_availability:
             # `auto` + `psychoacoustic` land first (PerTh path-to-prod);
             # `neural` lands later via Lambda follow-up.
@@ -114,9 +116,9 @@ operation:
             - `compression_resistant` (default): survives multiple
               MP3/AAC re-encodes at typical streaming bitrates.
             - `broadcast_grade`: survives broadcast compression
-              chains, EQ, dynamic-range compression, and analog-hole
-              capture (microphone re-recording). Higher embedding
-              time + slightly larger perceptual footprint.
+              chains, EQ, dynamic-range compression, and microphone
+              re-recording. Higher embedding time + slightly larger
+              perceptual footprint.
 
         density:
           type: enum
@@ -166,16 +168,16 @@ operation:
           required: false
           description: |
             Optional caller-supplied payload to embed (max 256
-            characters). When omitted, the server generates a UUID-v7
-            `watermark_id` and embeds that instead.
+            characters). When omitted, the server generates an
+            identifier automatically and embeds that instead.
 
         method:
           type: enum
           values: [auto, psychoacoustic, neural]
           default: auto
           description: |
-            Watermarking algorithm. Same semantics as the `audio`
-            mime_group; embedded into the video's audio track only.
+            Watermarking algorithm. Same as for an audio input;
+            embedded into the video's audio track only.
           per_value_availability:
             neural: { availability: planned }
 
@@ -183,7 +185,7 @@ operation:
           type: enum
           values: [light, compression_resistant, broadcast_grade]
           default: compression_resistant
-          description: "Survival profile. Same semantics as audio mime_group."
+          description: "Survival profile. Same as for an audio input."
 
         density:
           type: enum

package/operations/schemas/compress.yaml

@@ -29,22 +29,12 @@ operation:
           default: 80
           depends_on: { mode: lossy }
           description: "Compression quality (1 = smallest file, 100 = best quality). Only applies to lossy mode."
-        width:
-          type: integer
-          min: 1
-          max: 16384
-          description: "Maximum output width in pixels"
-        height:
-          type: integer
-          min: 1
-          max: 16384
-          description: "Maximum output height in pixels"
-        fit:
-          type: enum
-          values: [max, crop, scale]
-          default: max
-          depends_on: { width: set, height: set, logic: or }
-          description: "Resize mode. max = fit within bounds, crop = fill and trim, scale = force exact dimensions. Only applies when width or height is set."
+        # width / height / fit / auto_orient were REMOVED from compress.image
+        # per EsD1hs5u — the libcaesium image-compress worker recompresses
+        # ONLY and silently IGNORED them (accept-then-ignore). Image resize +
+        # EXIF auto-orient are served by the `thumbnail` op; format change by
+        # `convert`. The `video` mime_group KEEPS width/height/fit (ffmpeg
+        # honors them — do not remove there).
         metadata:
           type: enum
           values: [all, none, copyright, sensitive]
@@ -57,10 +47,6 @@ operation:
           values: [preserve, strip, srgb]
           default: preserve
           description: "ICC color profile handling. preserve = keep original, strip = remove, srgb = convert to sRGB"
-        auto_orient:
-          type: boolean
-          default: true
-          description: "Auto-rotate based on EXIF orientation"
         progressive:
           type: boolean
           default: true
@@ -105,17 +91,24 @@ operation:
         trim_start:
           type: float
           min: 0
-          description: "Trim from beginning in seconds"
+          availability: planned
+          description: >
+            Trim from beginning in seconds. Gated `planned` (qZI5EK9j):
+            no compression worker implements per-clip trim yet, so the
+            server returns `feature_not_available` rather than accepting
+            and silently ignoring it. Flips to `stable` when a worker
+            lands; to trim today, chain a `split` op.
         trim_end:
           type: float
           min: 0
-          description: "Trim from end in seconds"
+          availability: planned
+          description: "Trim from end in seconds. Gated `planned` (qZI5EK9j) — see `trim_start`."
 
     video:
       mimes:
         - video/mp4
         - video/webm
-        - video/ogg
+        - video/quicktime
       processing_class:
         # F8 long-form video tier (per ticket I15-CONS, Trello YZpBKzOM).
         # Public contract uses logical names only — backend selection is
@@ -144,12 +137,21 @@ operation:
           type: enum
           values: [h264, h265, vp9, av1]
           default: h264
-          description: "Video codec. h264 = widest compatibility, h265/av1 = better compression but slower"
+          description: >
+            Video codec. h264 = widest compatibility, h265/av1 = better
+            compression but slower. The default (h264) is the MP4/MOV standard
+            and is CONTAINER-CONDITIONAL: for an output container that cannot
+            carry it (e.g. WebM, which carries VP8/VP9/AV1) the server resolves
+            a container-valid codec (WebM -> vp9). A DEFAULT value is never
+            rejected; only a caller-EXPLICIT incompatible codec returns
+            invalid_options. See FORMAT.md "Container-conditional defaults" +
+            ADR-0020.
         encoding_mode:
           type: enum
           values: [crf, target_size]
           default: crf
-          description: "crf = constant quality (variable file size), target_size = constrained file size (two-pass)"
+          # target_size is implemented as a two-pass encode in the worker.
+          description: "crf = constant quality (variable file size), target_size = constrained file size"
         crf:
           type: integer
           min: 0
@@ -161,7 +163,8 @@ operation:
           type: integer
           min: 1048576
           depends_on: { encoding_mode: target_size }
-          description: "Target output file size in bytes (min 1MB). Two-pass encoding to meet this target."
+          # Met via a two-pass encode in the worker.
+          description: "Target output file size in bytes (min 1MB)."
         preset:
           type: enum
           values: [ultrafast, superfast, veryfast, faster, fast, medium, slow, slower, veryslow]
@@ -169,14 +172,14 @@ operation:
           description: "Encoding speed vs compression ratio trade-off"
         width:
           type: integer
-          min: 1
+          min: 2
           max: 7680
-          description: "Output width in pixels"
+          description: "Output width in pixels. Must be an EVEN integer >= 2 (yuv420p chroma-subsampling); odd values are rejected as invalid_options by the encoder."
         height:
           type: integer
-          min: 1
+          min: 2
           max: 4320
-          description: "Output height in pixels"
+          description: "Output height in pixels. Must be an EVEN integer >= 2 (yuv420p chroma-subsampling); odd values are rejected as invalid_options by the encoder."
         fit:
           type: enum
           values: [max, crop, scale, pad]
@@ -191,12 +194,27 @@ operation:
         faststart:
           type: boolean
           default: true
-          description: "Move MP4 moov atom to start for progressive web playback (MP4 only)"
+          description: >
+            Move the MP4/MOV moov atom to start for progressive web playback.
+            MP4/MOV only. CONTAINER-CONDITIONAL: the default (true) is silently
+            inapplicable for a container with no moov atom (e.g. WebM) — that
+            is NOT a rejection. Only a caller-EXPLICIT faststart:true on such a
+            container returns invalid_options. See FORMAT.md
+            "Container-conditional defaults" + ADR-0020.
         audio_codec:
           type: enum
           values: [aac, opus, vorbis, copy]
-          default: aac
-          description: "Audio codec. aac = widest compatibility, opus = best quality/size, copy = passthrough"
+          default: copy
+          description: >
+            Audio codec. copy = passthrough (keep the source audio stream as-is;
+            re-encode only on explicit request) — aac = widest compatibility,
+            opus = best quality/size. Default is `copy` (ADR-0020 D7): it MATCHES
+            the worker's actual absent-audio behaviour and is container-safe for
+            compress (output container = input container, so the source stream is
+            already compatible). Set an explicit codec to re-encode; an explicit
+            codec the output container cannot carry (e.g. aac on a WebM output)
+            returns invalid_options. A DEFAULT value is never rejected. See
+            FORMAT.md "Container-conditional defaults" + ADR-0020.
         audio_bitrate:
           type: enum
           value_type: integer
@@ -206,11 +224,18 @@ operation:
         trim_start:
           type: float
           min: 0
-          description: "Trim from beginning in seconds"
+          availability: planned
+          description: >
+            Trim from beginning in seconds. Gated `planned` (qZI5EK9j):
+            no compression worker implements per-clip trim yet, so the
+            server returns `feature_not_available` rather than accepting
+            and silently ignoring it. Flips to `stable` when a worker
+            lands; to trim today, chain a `split` op.
         trim_end:
           type: float
           min: 0
-          description: "Trim from end in seconds"
+          availability: planned
+          description: "Trim from end in seconds. Gated `planned` (qZI5EK9j) — see `trim_start`."
 
     document_pdf:
       mimes:

package/operations/schemas/convert.yaml

@@ -73,7 +73,12 @@ operation:
         codec:
           type: enum
           values: [h264, h265, vp9, av1]
-          description: "Video codec for target format. Defaults to format's standard codec."
+          description: >
+            Video codec for target format. Defaults to the format's standard
+            codec (no literal default — the required output_format determines
+            it). This is the container-conditional-default principle applied via
+            an explicit container choice. See FORMAT.md
+            "Container-conditional defaults" + ADR-0020.
         quality:
           type: integer
           min: 0

package/operations/schemas/custom_luma.yaml

@@ -20,9 +20,12 @@ operation:
     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). The mask can be uploaded directly, imported
-    externally, or referenced from a vault connection per
-    `WorkflowSource` (from I10).
+    dark = held). Each input is a `MultiInputSource` — 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).
@@ -34,6 +37,18 @@ operation:
   min_inputs: 2
   max_inputs: 2
 
+  # Per-role input-count constraints (ADR-0015). Both roles REQUIRED,
+  # exactly one each. Arithmetic-consistency rule (CI-checked):
+  # - sum(role.min) == min_inputs  (1 + 1 = 2)
+  # - sum(role.max) == max_inputs  (1 + 1 = 2)
+  per_role_cardinality:
+    base:
+      min: 1
+      max: 1
+    transition_mask:
+      min: 1
+      max: 1
+
   mime_groups:
     video:
       mimes:

package/operations/schemas/image_watermark.yaml

@@ -3,11 +3,14 @@ schema_version: "2.0.0"
 operation:
   type: image_watermark
   description: |
-    Apply an image overlay (file or external source) onto a base media
+    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). The overlay
-    can be an upload, an external_import handle, or a vault connection
-    per WorkflowSource (ticket I10).
+    asset) + exactly one with role: overlay (the watermark). 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 that job via
+    `{ type: job_output, from: <id> }` (per ticket 4som89Uh).
 
     Stable today for static-image bases (image/jpeg, image/png,
     image/webp); animated GIF bases are advertised as `planned` via
@@ -34,6 +37,18 @@ operation:
   min_inputs: 2
   max_inputs: 2
 
+  # Per-role input-count constraints (ADR-0015). Both roles REQUIRED,
+  # exactly one each. Arithmetic-consistency rule (CI-checked):
+  # - sum(role.min) == min_inputs  (1 + 1 = 2)
+  # - sum(role.max) == max_inputs  (1 + 1 = 2)
+  per_role_cardinality:
+    base:
+      min: 1
+      max: 1
+    overlay:
+      min: 1
+      max: 1
+
   features:
     multi_overlay_stack:
       availability: planned
@@ -66,9 +81,9 @@ operation:
             - bottom_right
           default: bottom_right
           description: |
-            9-grid anchor position on the base image. Mirrors
-            Mux/Cloudinary positioning. Combined with margin_x and
-            margin_y for fine-grained offset from the anchor point.
+            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