@giveitsmaller/contracts 0.3.0 → 0.5.0

package/operations/schemas/audio_overlay.yaml

@@ -79,12 +79,18 @@ operation:
             max_input_size_bytes: 524288000
             max_output_size_bytes: 524288000
         long_form:
+          # Stays planned (CON-1 flips only compress.video.long_form +
+          # merge.video.long_form_re_encode). Per-tier caps per ADR-0011.
           availability: planned
           required_tier: pro
-          constraints:
+          constraints:                            # baseline = Pro
             max_input_duration: "PT12H"
-            max_input_size_bytes: 21474836480
-            max_output_size_bytes: 21474836480
+            max_input_size_bytes: 5000000000       # 5 GB (Pro)
+            max_output_size_bytes: 5000000000
+          per_tier_constraints:
+            enterprise:
+              max_input_size_bytes: 120000000000   # 120 GB (Enterprise enforced ceiling)
+              max_output_size_bytes: 120000000000
       options:
         start_at:
           type: float
@@ -257,12 +263,18 @@ operation:
             max_input_size_bytes: 524288000
             max_output_size_bytes: 524288000
         long_form:
+          # Stays planned (CON-1 flips only compress.video.long_form +
+          # merge.video.long_form_re_encode). Per-tier caps per ADR-0011.
           availability: planned
           required_tier: pro
-          constraints:
+          constraints:                            # baseline = Pro
             max_input_duration: "PT12H"
-            max_input_size_bytes: 21474836480
-            max_output_size_bytes: 21474836480
+            max_input_size_bytes: 5000000000       # 5 GB (Pro)
+            max_output_size_bytes: 5000000000
+          per_tier_constraints:
+            enterprise:
+              max_input_size_bytes: 120000000000   # 120 GB (Enterprise enforced ceiling)
+              max_output_size_bytes: 120000000000
       options:
         start_at:
           type: float

package/operations/schemas/audio_to_video.yaml

@@ -0,0 +1,122 @@
+schema_version: "2.0.0"
+
+operation:
+  type: audio_to_video
+  availability: planned
+  description: |
+    Produce a video from an audio input plus an OPTIONAL still image
+    overlay. Use cases: podcast → YouTube uploads, audio-only tracks
+    that need a video container for platforms requiring it, branded
+    audio releases with a static cover image.
+
+    **Role asymmetry.** First role-based operation on the contract
+    with an OPTIONAL role — REQUIRED `base` (audio source) +
+    OPTIONAL `overlay` (still image, 0..1). When `overlay` is
+    omitted, the video uses a solid `background_color`. The
+    machine-readable cardinality lives in `per_role_cardinality`
+    on this schema (per ADR-0015). API consumption site:
+    `OperationInputRoleValidator` (rule table) consumed by
+    `SchemaValidationService.php` in `compression_api`.
+
+    **Input vs output asymmetry.** The single `mime_groups.audio`
+    block keys the INPUT MIME family (the `base` role input is
+    audio). The OUTPUT is always video — `output_format` controls
+    the container; `mime_groups` is NOT the output type. Mirrors
+    the `audio_overlay.video` group pattern (input-keyed).
+
+    Re-encode required (audio → video composition always re-encodes).
+    Lower framerate + FFmpeg `-tune stillimage` keeps file size
+    tiny when the overlay is a still image (the common case).
+
+    Per ticket [`SlluxMBN`](https://trello.com/c/SlluxMBN) +
+    ADR-0015. `availability: planned` until the cross-repo Lambda
+    support ships; the API rejects workflow-create with
+    `feature_not_available` (422) until then.
+
+  default: false
+  input_model: multi
+  min_inputs: 1
+  max_inputs: 2
+
+  # Per-role input-count constraints — first role-based op with
+  # an OPTIONAL role. See ADR-0015 for the vocab primitive.
+  # Arithmetic-consistency rule (CI-checked):
+  # - sum(role.min) == min_inputs  (1 + 0 = 1)
+  # - sum(role.max) == max_inputs  (1 + 1 = 2)
+  per_role_cardinality:
+    base:
+      min: 1
+      max: 1
+    overlay:
+      min: 0
+      max: 1
+
+  mime_groups:
+    audio:
+      # INPUT MIME family for the `base` role. Output is video via
+      # `output_format` — NOT determined by this mime_group key.
+      mimes:
+        - audio/mpeg
+        - audio/aac
+        - audio/wav
+        - audio/x-wav
+        - audio/flac
+        - audio/ogg
+        - audio/opus
+        - audio/x-m4a
+      options:
+        output_resolution:
+          type: enum
+          values: [hd_720p, fhd_1080p, sd_480p]
+          default: hd_720p
+          description: |
+            Output video resolution. `hd_720p` = 1280×720 (default),
+            `fhd_1080p` = 1920×1080, `sd_480p` = 854×480. Choose
+            lower for small file size; higher when the overlay image
+            quality warrants it.
+        background_color:
+          type: string
+          default: "#000000"
+          description: |
+            Hex `#RRGGBB` solid background colour. Used only when
+            `overlay` is omitted (no image input). When an `overlay`
+            image is provided, the background colour is invisible
+            behind the image (subject to `image_fit`).
+        image_fit:
+          type: enum
+          values: [contain, cover, stretch]
+          default: contain
+          description: |
+            How to fit the overlay image into the output frame.
+            `contain` = letterbox (preserve aspect ratio, may show
+            background); `cover` = crop (fill the frame, may crop
+            the image); `stretch` = distort to fit (preserves no
+            aspect ratio). Default `contain` preserves the image
+            aesthetic.
+        framerate:
+          type: integer
+          min: 1
+          max: 60
+          default: 2
+          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
+            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).
+        output_format:
+          type: enum
+          values: [mp4]
+          default: mp4
+          description: |
+            Output container format. V1 supports `mp4` only. Future
+            additions (webm, mov) await Lambda follow-up.
+
+  # NOTE: role-MIME constraint (base MUST be audio, overlay MUST be
+  # image) is documented in prose only for V1. ADR-0015 records this
+  # as future-work — a `per_role_mime_compat` vocab primitive can be
+  # added when a second role-based op needs the asymmetry (today
+  # only audio_to_video has it). The API edge validator enforces
+  # the role→MIME constraint at workflow-create time per the prose
+  # contract.

package/operations/schemas/audio_watermark.yaml

@@ -58,12 +58,16 @@ operation:
             max_input_size_bytes: 524288000
             max_output_size_bytes: 524288000
         long_form:
+          # Stays planned (CON-1 flips only compress.video.long_form +
+          # merge.video.long_form_re_encode). required_tier: enterprise,
+          # so baseline IS the Enterprise cap and there is NO
+          # per_tier_constraints (no tier above enterprise) — ADR-0011 D2.
           availability: planned
           required_tier: enterprise
-          constraints:
+          constraints:                            # baseline = Enterprise (lowest permitted)
             max_input_duration: "PT12H"
-            max_input_size_bytes: 21474836480
-            max_output_size_bytes: 21474836480
+            max_input_size_bytes: 120000000000     # 120 GB (Enterprise enforced ceiling)
+            max_output_size_bytes: 120000000000
       options:
         payload:
           type: string
@@ -146,12 +150,16 @@ operation:
             max_input_size_bytes: 524288000
             max_output_size_bytes: 524288000
         long_form:
+          # Stays planned (CON-1 flips only compress.video.long_form +
+          # merge.video.long_form_re_encode). required_tier: enterprise,
+          # so baseline IS the Enterprise cap and there is NO
+          # per_tier_constraints (no tier above enterprise) — ADR-0011 D2.
           availability: planned
           required_tier: enterprise
-          constraints:
+          constraints:                            # baseline = Enterprise (lowest permitted)
             max_input_duration: "PT12H"
-            max_input_size_bytes: 21474836480
-            max_output_size_bytes: 21474836480
+            max_input_size_bytes: 120000000000     # 120 GB (Enterprise enforced ceiling)
+            max_output_size_bytes: 120000000000
       options:
         payload:
           type: string

package/operations/schemas/compress.yaml

@@ -130,12 +130,18 @@ operation:
             max_input_size_bytes: 524288000        # 500 MiB
             max_output_size_bytes: 524288000
         long_form:
-          availability: planned
+          # planned -> beta (CON-1, ADR-0011): staging/internal proving
+          # gate before the stable claim (CON-2a). Per-tier caps per D3.
+          availability: beta
           required_tier: pro
-          constraints:
+          constraints:                            # baseline = Pro (lowest permitted tier)
             max_input_duration: "PT12H"
-            max_input_size_bytes: 21474836480      # 20 GiB
-            max_output_size_bytes: 21474836480
+            max_input_size_bytes: 5000000000       # 5 GB (Pro)
+            max_output_size_bytes: 5000000000
+          per_tier_constraints:
+            enterprise:
+              max_input_size_bytes: 120000000000   # 120 GB (Enterprise enforced ceiling)
+              max_output_size_bytes: 120000000000
       options:
         codec:
           type: enum

package/operations/schemas/convert.yaml

@@ -51,12 +51,19 @@ operation:
             max_input_size_bytes: 524288000
             max_output_size_bytes: 524288000
         long_form:
+          # Stays planned (CON-1 flips only compress.video.long_form +
+          # merge.video.long_form_re_encode). Per-tier caps per ADR-0011 —
+          # advertised shape; availability gates execution off (422).
           availability: planned
           required_tier: pro
-          constraints:
+          constraints:                            # baseline = Pro
             max_input_duration: "PT12H"
-            max_input_size_bytes: 21474836480
-            max_output_size_bytes: 21474836480
+            max_input_size_bytes: 5000000000       # 5 GB (Pro)
+            max_output_size_bytes: 5000000000
+          per_tier_constraints:
+            enterprise:
+              max_input_size_bytes: 120000000000   # 120 GB (Enterprise enforced ceiling)
+              max_output_size_bytes: 120000000000
       options:
         output_format:
           type: enum

package/operations/schemas/custom_luma.yaml

@@ -54,12 +54,19 @@ operation:
             max_input_size_bytes: 524288000
             max_output_size_bytes: 524288000
         long_form:
+          # Stays planned (CON-1 flips only compress.video.long_form +
+          # merge.video.long_form_re_encode). Per-tier caps per ADR-0011 —
+          # advertised shape; availability gates execution off (422).
           availability: planned
           required_tier: pro
-          constraints:
+          constraints:                            # baseline = Pro
             max_input_duration: "PT12H"
-            max_input_size_bytes: 21474836480
-            max_output_size_bytes: 21474836480
+            max_input_size_bytes: 5000000000       # 5 GB (Pro)
+            max_output_size_bytes: 5000000000
+          per_tier_constraints:
+            enterprise:
+              max_input_size_bytes: 120000000000   # 120 GB (Enterprise enforced ceiling)
+              max_output_size_bytes: 120000000000
       options:
         duration:
           type: float

package/operations/schemas/image_watermark.yaml

@@ -10,11 +10,15 @@ operation:
     per WorkflowSource (ticket I10).
 
     Stable today for static-image bases (image/jpeg, image/png,
-    image/webp); animated GIF and video bases are advertised as
-    `planned` via parallel mime_groups (`image_gif`, `video`) — schema
-    is contract-defined, dispatch returns `feature_not_available` (422)
-    until Lambda support ships. Per Tension 1 (ADR-0001) +
-    plan v5 §F4 round 6.
+    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.
+
+    **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.
 
     **Audio is explicitly NOT supported.** For audio overlay (DJ tags,
     podcast intros, jingles), use the `audio_overlay` operation
@@ -22,7 +26,7 @@ operation:
     `availability: planned`).
 
     Source capped at 25 megapixels for image bases (V1 watermark
-    precedent retained); per-frame caps for GIF / video bases will be
+    precedent retained); per-frame caps for animated GIF bases will be
     defined when the corresponding Lambda support ships.
     Per ADR-0004 §"V2 JobDefinition" + plan v5 §F1.
   default: false
@@ -188,93 +192,8 @@ operation:
             width. Aspect ratio preserved. Omit to use the original
             overlay size.
 
-    # Video base — single planned block covering common web video
-    # containers. Per-frame megapixel cap, codec acceptance and frame-
-    # rate constraints will be defined when the video-watermark Lambda
-    # ships (follow-up cross-repo ticket; tracked in plan v5 §F4
-    # round 6).
-    video:
-      availability: planned
-      mimes:
-        - video/mp4
-        - video/webm
-      processing_class:
-        # F8 long-form tier (per ticket I15-CONS Decisions §2). Both
-        # classes `planned` because the video mime_group itself is
-        # `planned` at the group level. Forward-compatible with future
-        # Lambda activation.
-        short_form:
-          availability: planned
-          constraints:
-            max_input_duration: "PT5M"
-            max_input_size_bytes: 524288000
-            max_output_size_bytes: 524288000
-        long_form:
-          availability: planned
-          required_tier: pro
-          constraints:
-            max_input_duration: "PT12H"
-            max_input_size_bytes: 21474836480
-            max_output_size_bytes: 21474836480
-      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 each video frame. Same semantics
-            as the `image` group.
-
-        margin_x:
-          type: string
-          pattern: '^\d+(\.\d+)?(px|%)$'
-          default: "0px"
-          description: |
-            Horizontal offset from the anchor in pixels or percentage of
-            video frame width. Anchor-relative; positive moves toward
-            the frame 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
-            video frame height. Anchor-relative; positive moves toward
-            the frame 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 video
-            frame 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
+    # `availability: planned` advertising had no consumers; the
+    # dedicated operation is the canonical landing site.

package/operations/schemas/merge.yaml

@@ -151,11 +151,17 @@ operation:
             max_total_duration: "PT5M"
             max_total_input_size_bytes: 1073741824   # 1 GiB combined
         long_form_re_encode:
-          availability: planned
+          # planned -> beta (CON-1, ADR-0011): staging proving gate before
+          # stable (CON-2b). Binding cap = max_total_duration (24h single-
+          # pass budget, SPIKE-0); size is the per-tier secondary cap.
+          availability: beta
           required_tier: pro
-          constraints:
-            max_total_duration: "PT12H"
-            max_total_input_size_bytes: 21474836480
+          constraints:                              # baseline = Pro (lowest permitted)
+            max_total_duration: "PT24H"              # 24h (was PT12H) — binding Enterprise ceiling
+            max_total_input_size_bytes: 5000000000   # 5 GB combined (Pro)
+          per_tier_constraints:
+            enterprise:
+              max_total_input_size_bytes: 120000000000  # 120 GB combined (Enterprise)
       options:
         output_type:
           type: enum