@giveitsmaller/contracts 0.50.0 → 0.53.0

package/operations/schemas/image_watermark.yaml

@@ -44,30 +44,53 @@ operation:
   input_model: multi
   sole_op: true   # bypasses V1 chain validation — must be the only operation in its job (ADR-0025)
   min_inputs: 2
-  max_inputs: 2
+  max_inputs: 9
 
-  # 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 input-count constraints (ADR-0015). base REQUIRED exactly one;
+  # overlay 1-8 (multi-overlay stack LIVE 2026-07-01). Arithmetic-consistency
+  # rule (CI-checked): sum(role.min) == min_inputs (1 + 1 = 2); sum(role.max) ==
+  # max_inputs (1 + 8 = 9). Per-role counts are WORKER-enforced (the API validates
+  # only the coarse TOTAL via input min/max); per_role_cardinality is advisory.
   per_role_cardinality:
     base:
       min: 1
       max: 1
     overlay:
       min: 1
-      max: 1
+      max: 8
 
   features:
     multi_overlay_stack:
-      availability: planned
+      # LIVE 2026-07-01: flipped planned->stable on the lambdas worker proof
+      # (operation-image-watermark git-2999507, digest-verified;
+      # prove-multi-overlay-staging.sh — 3 index-aligned overlays each rendering
+      # their own colour at their anchor; mutex + cardinality worker-enforced).
+      # Co-landed with `input` max 2->9 + per_role overlay{1,8} + overlays[]
+      # executable + api's overlays[] validation & FNA-gate removal (uUdre4jg).
+      # availability set EXPLICITLY (matches the audio_overlay / video_watermark
+      # multi_overlay_stack features, which stay `planned` — their workers are
+      # unproven for multi-overlay).
+      availability: stable
       description: |
-        Allow up to 8 overlay inputs per job (currently capped at 1
-        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.
+        Stack up to 8 overlay inputs on one base image, each with its own
+        placement via the `overlays[]` array option (index-aligned to the
+        overlay-role sources; see the `image` group's `overlays` option).
+        `overlays[]` is mutually exclusive with the flat single-overlay options,
+        which remain the 1-overlay back-compat path.
+
+        **Base-format scope: multi-overlay (`overlays[]`) is on the `image`
+        group (jpeg/png/webp) ONLY** — the format the worker proved. The
+        stable `image_tiff` / `image_bmp` bases support the SINGLE-overlay flat
+        options but NOT `overlays[]` yet (multi-overlay on those bases needs its
+        own worker proof — a base-format extension, separate from the group's
+        stable single-overlay flip). GIF / video bases remain out of scope.
+
+        The op-level `input` max 9 / `per_role_cardinality` overlay `{1,8}` is
+        the MAXIMUM (the jpeg/png/webp base); input-cardinality has no per-mime-
+        group primitive, so a `>1`-overlay request on a tiff/bmp base — which
+        has no `overlays[]` to place the extra overlays — is rejected as
+        `invalid_options` (API + worker). Effective per-base overlay count:
+        jpeg/png/webp = 1–8, tiff/bmp = 1.
 
   mime_groups:
     image:
@@ -144,6 +167,91 @@ operation:
             Optional overlay width as either pixels (e.g. "200px") or
             percentage of base image width (e.g. "30%"). Aspect ratio is
             preserved. Omit to use the original overlay size.
+        overlays:
+          type: array
+          minItems: 1
+          maxItems: 8
+          # LIVE 2026-07-01 (no availability tag = stable): the multi-overlay-stack
+          # surface (features.multi_overlay_stack), flipped planned->stable on the
+          # lambdas worker proof (git-2999507). INDEX-ALIGNED to the overlay-role
+          # sources: overlays[i] applies to overlay source i. The option DSL has no
+          # source-array-length-match primitive, so `len(overlays) == overlay-source
+          # count` is WORKER-enforced (invalid_options otherwise) — prose below.
+          # Cardinality (co-design with lambdas + api): per-role counts are
+          # WORKER-enforced (base{1,1} + overlay{1,8}); the API validates only the
+          # coarse TOTAL input count via `input` min/max (2..9), so
+          # per_role_cardinality stays ADVISORY. The item sub-schema mirrors the flat
+          # single-overlay options (JSON-Schema forms per the render_variants.targets
+          # array-of-objects precedent).
+          # COEXISTENCE: `overlays[]` is MUTUALLY EXCLUSIVE with the flat
+          # single-overlay options (anchor/margin_x/margin_y/opacity/
+          # overlay_width) — setting both in one request is `invalid_options`
+          # (api create-validation + worker). No silent precedence; the caller
+          # picks ONE mode. (The option DSL has no cross-option-group mutex
+          # primitive, so this is validator-enforced, documented here + in prose.)
+          description: |
+            Per-overlay placement for the multi-overlay stack — one entry per
+            overlay source, INDEX-ALIGNED: `overlays[i]` applies to overlay
+            source `i`. Stacks up to 8 overlays on one base
+            (`features.multi_overlay_stack`). `len(overlays)` MUST equal the
+            number of overlay-role sources (worker-enforced; `invalid_options`
+            otherwise).
+
+            **Z-order = array index (painter's order, bottom → top).** Overlays
+            are composited in array/source order: `overlays[0]` first (bottom),
+            then `overlays[1]`, … `overlays[N-1]` LAST (on top). Where two
+            overlays overlap, the higher index wins. There is no per-overlay
+            `z` field — the index IS the z-order. (Deterministic in the worker;
+            identical per-frame for animated-WebP bases.)
+
+            **Mutually exclusive with the flat single-overlay options**
+            (`anchor` / `margin_x` / `margin_y` / `opacity` / `overlay_width`):
+            a request that sets BOTH `overlays[]` and any flat option is
+            rejected as `invalid_options` (API create-validation + worker) —
+            there is no silent precedence. Use the flat options for the
+            single-overlay path, `overlays[]` for the multi path.
+
+            LIVE (flipped `planned` -> stable 2026-07-01 on the lambdas worker
+            proof, co-landed with `input` max 2 -> 9 + `per_role_cardinality`
+            overlay `{1,8}` + api's overlays[] validation & FNA-gate removal).
+            The single-overlay FLAT options remain the 1-overlay back-compat path.
+          items:
+            type: object
+            properties:
+              anchor:
+                type: string
+                enum:
+                  - 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 (per-overlay; see the flat `anchor`).
+              margin_x:
+                type: string
+                pattern: '^\d+(\.\d+)?(px|%)$'
+                default: "0px"
+                description: Horizontal offset from the anchor (px or % of base width), anchor-relative (see the flat `margin_x`).
+              margin_y:
+                type: string
+                pattern: '^\d+(\.\d+)?(px|%)$'
+                default: "0px"
+                description: Vertical offset from the anchor (px or % of base height), anchor-relative (see the flat `margin_y`).
+              opacity:
+                type: number
+                minimum: 0
+                maximum: 1
+                default: 0.5
+                description: Overlay opacity (0 transparent .. 1 opaque), clamped.
+              overlay_width:
+                type: string
+                pattern: '^\d+(\.\d+)?(px|%)$'
+                description: Optional overlay width (px or % of base width); aspect preserved. Omit for original size.
 
     # Animated GIF base — separate group because the rendering path is
     # frame-preserving (each frame composited with the overlay), distinct

package/operations/schemas/transform.yaml

@@ -0,0 +1,196 @@
+schema_version: "2.0.0"
+
+operation:
+  type: transform
+  availability: planned
+  description: |
+    Apply a geometric / orientation transform to a media asset. **v1 supports
+    rotate + flip only** (orientation transforms) — it does NOT do crop, scale,
+    skew, or colour transforms. The name is deliberately `transform` (not
+    `orient`) to leave room for a future `crop` on the same op; do not read the
+    name as advertising arbitrary affine transforms. Full design + normative
+    order-of-operations, routing topology, chain order, media gating, and
+    billing model: ADR-0026.
+
+    **Params (per media group):**
+    - `rotate` — `0 | 90 | 180 | 270` degrees clockwise (default `0`).
+    - `flip` — `none | horizontal | vertical | both` mirror (default `none`).
+      `horizontal` = left↔right (the selfie/webcam mirror-correction),
+      `vertical` = top↔bottom, `both` = both axes.
+
+    **Normative order-of-operations (v1 has NO arbitrary sequence).** For a
+    single `transform` op the worker applies, in this fixed order:
+    1. (images) normalize display orientation from EXIF,
+    2. apply `rotate`,
+    3. apply `flip` in the FINAL (post-rotate) display axes,
+    4. (images) write pixels with the orientation tag reset/removed.
+    So `flip: horizontal` always means left↔right in the *visible result*, even
+    after a 90/270 rotate. See ADR-0026 §Order-of-operations.
+
+    **auto_orient coexistence.** `transform` reads the image honouring EXIF
+    orientation, applies rotate/flip, and emits normalized-orientation pixels —
+    so a downstream `compress`/`convert` `auto_orient` is a no-op. Raw
+    stored-pixel rotation that ignores EXIF is out of scope for v1.
+
+    **No-op is rejected at create.** A `transform` with `rotate: 0` AND
+    `flip: none` (for documents: `rotate: 0`) does nothing, so the API rejects
+    it as `invalid_options` at create — there is no billed, worker-dispatched
+    no-op (mirrors the API facade gate that rejects inert option combos). At
+    least one of `rotate`/`flip` must be non-default.
+
+    **Media scope (v1).** IMAGE **still-raster** (jpeg/png/webp) and animated
+    GIF; VIDEO (mp4/webm); DOCUMENT is PDF-rotate ONLY (no flip — the
+    `document_pdf` group offers `rotate` alone). AUDIO is intentionally absent
+    (no spatial geometry). SVG, HEIC/AVIF, and non-PDF documents
+    (Office/ODF/EPUB) are out of scope for v1 and are not advertised.
+    **Animated PNG (APNG) and animated WebP** are NOT covered by the
+    still-raster `image` group's activation proof — like animated GIF, a
+    pixel-baking geometry op would drop frames / animation metadata. Before the
+    `image` group flips stable the worker MUST either reject animated PNG/WebP
+    variants at probe or transform ALL frames + preserve animation metadata
+    (same bar as the `image_gif` group). Everything ships `availability:
+    planned` first and flips per media on worker capability-source proof
+    (ADR-0006) — each activation co-updates schema availability + AsyncAPI
+    routing + API OperationType/chain/pricing + the billing weight row together
+    (ADR-0026 §Rollout).
+
+    **Routing (thumbnail precedent).** The payload `operation_type` stays the
+    base value `transform`; the API publisher resolves the effective input MIME
+    to an SNS `operation_type` routing-attribute sub-type
+    (`transform_image` / `transform_video` / `transform_document`). Those
+    sub-types are ROUTING ATTRIBUTES ONLY — never persisted or public operation
+    types (they are absent from the OperationType payload enum). The
+    `document_pdf` group routes under `transform_document` (media-family level,
+    even though v1 is PDF-only). See ADR-0026 §Routing + asyncapi/events.yaml.
+  default: false
+  input_model: single
+  # Chains normally (ADR-0025: absent ≡ false; set explicitly to document intent).
+  # Canonical single-job order is transform -> convert -> compress -> thumbnail
+  # (ADR-0026): orientation runs before resize/encode so downstream width/height/fit
+  # refer to the final visual frame, and rotate never triggers a second video encode.
+  sole_op: false
+
+  mime_groups:
+    image:
+      # Still-raster first. availability:planned until the image worker
+      # (Rust `image` crate: fliph/flipv/rotate90/180/270 — already vendored for
+      # resize/thumbnail) is capability-proven, then flips stable per ADR-0006.
+      # STILL jpeg/png/webp only: animated PNG (APNG) + animated WebP are NOT
+      # covered by this group's still-raster proof (a pixel-bake drops frames /
+      # animation metadata) — they must be rejected at probe OR handled with
+      # all-frames + animation-metadata preservation (GIF bar) before the flip.
+      availability: planned
+      mimes:
+        - image/jpeg
+        - image/png
+        - image/webp
+      options:
+        rotate:
+          type: enum
+          value_type: integer
+          values: [0, 90, 180, 270]
+          default: 0
+          description: >-
+            Clockwise rotation in degrees. Applied BEFORE `flip` (see the
+            operation-level normative order-of-operations).
+        flip:
+          type: enum
+          values: [none, horizontal, vertical, both]
+          default: none
+          description: >-
+            Mirror the image. `horizontal` = left↔right, `vertical` = top↔bottom,
+            `both` = both axes. Applied AFTER `rotate`, in the final (post-rotate)
+            display axes, so `horizontal` always means left↔right in the visible
+            result.
+
+    image_gif:
+      # Animated GIF as a parallel planned group (mirrors image_watermark's
+      # image_gif). Only honest once the worker transforms ALL frames AND
+      # preserves animation metadata (frame delays, loop count, disposal);
+      # dispatch returns feature_not_available (422) until that ships. Do NOT
+      # flip stable on the still-raster proof alone.
+      availability: planned
+      mimes:
+        - image/gif
+      options:
+        rotate:
+          type: enum
+          value_type: integer
+          values: [0, 90, 180, 270]
+          default: 0
+          description: "Clockwise rotation in degrees (all frames). Applied before `flip`."
+        flip:
+          type: enum
+          values: [none, horizontal, vertical, both]
+          default: none
+          description: "Mirror all frames. Applied after `rotate`, in final display axes."
+
+    video:
+      # mp4/webm first (the FFmpeg containers we already decode AND encode).
+      # hflip/vflip + transpose bake into pixels → a real re-encode (no
+      # stream-copy shortcut), so it costs compute like any transcode (billing
+      # weight 10, ADR-0026). quicktime/mov and other containers follow the same
+      # decode-AND-encode proof discipline and are not advertised in v1.
+      mimes:
+        - video/mp4
+        - video/webm
+      processing_class:
+        # F8 long-form video tier (ADR-0011). Both classes ship planned; short_form
+        # is first-in-line to flip on the FFmpeg worker proof, long_form stays
+        # planned until the Fargate re-encode route is real and costed (ADR-0026).
+        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:                            # baseline = Pro
+            max_input_duration: "PT12H"
+            max_input_size_bytes: 5000000000       # 5 GB (Pro)
+            max_output_size_bytes: 5000000000
+          per_tier_constraints:
+            max:
+              max_input_size_bytes: 50000000000    # 50 GB (Max self-serve band)
+              max_output_size_bytes: 50000000000
+            enterprise:
+              max_input_size_bytes: 120000000000   # 120 GB (Enterprise enforced ceiling)
+              max_output_size_bytes: 120000000000
+      options:
+        rotate:
+          type: enum
+          value_type: integer
+          values: [0, 90, 180, 270]
+          default: 0
+          description: >-
+            Clockwise rotation in degrees (FFmpeg `transpose`). Applied BEFORE
+            `flip`. Re-encodes the video.
+        flip:
+          type: enum
+          values: [none, horizontal, vertical, both]
+          default: none
+          description: >-
+            Mirror the video (FFmpeg `hflip` / `vflip`). `horizontal` = left↔right,
+            `vertical` = top↔bottom, `both` = both. Applied AFTER `rotate`, in the
+            final display axes. Re-encodes the video.
+
+    document_pdf:
+      # PDF-rotate ONLY (page rotation for scanned/phone PDFs). NO flip — mirror
+      # is not a clean promise for documents. Office/ODF/EPUB are NOT covered
+      # (page rotation there is not same_as_input). availability:planned,
+      # flips beta/stable separately on worker proof; routes under the
+      # media-family attribute transform_document (ADR-0026 §Routing).
+      availability: planned
+      mimes:
+        - application/pdf
+      options:
+        rotate:
+          type: enum
+          value_type: integer
+          values: [0, 90, 180, 270]
+          default: 0
+          description: >-
+            Clockwise page rotation in degrees, applied to the rendered page
+            orientation. `flip` is NOT offered for documents in v1.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@giveitsmaller/contracts",
-  "version": "0.50.0",
+  "version": "0.53.0",
   "description": "Generated contract types for GISL (Give It Smaller)",
   "license": "MIT",
   "type": "module",
@@ -29,6 +29,7 @@
     "./accepted-options/accepted-options.json": "./accepted-options/accepted-options.json",
     "./accepted-options/image-output-routes.json": "./accepted-options/image-output-routes.json",
     "./operation-capabilities/operation-capabilities.json": "./operation-capabilities/operation-capabilities.json",
+    "./code-builder/code-builder-metadata.json": "./code-builder/code-builder-metadata.json",
     "./operations/schemas/archive.yaml": "./operations/schemas/archive.yaml",
     "./operations/schemas/audio_overlay.yaml": "./operations/schemas/audio_overlay.yaml",
     "./operations/schemas/audio_to_video.yaml": "./operations/schemas/audio_to_video.yaml",
@@ -43,6 +44,7 @@
     "./operations/schemas/split.yaml": "./operations/schemas/split.yaml",
     "./operations/schemas/text_watermark.yaml": "./operations/schemas/text_watermark.yaml",
     "./operations/schemas/thumbnail.yaml": "./operations/schemas/thumbnail.yaml",
+    "./operations/schemas/transform.yaml": "./operations/schemas/transform.yaml",
     "./operations/schemas/video_text_watermark.yaml": "./operations/schemas/video_text_watermark.yaml",
     "./operations/schemas/video_watermark.yaml": "./operations/schemas/video_watermark.yaml"
   },
@@ -54,7 +56,8 @@
     "availability/availability.json",
     "accepted-options/accepted-options.json",
     "accepted-options/image-output-routes.json",
-    "operation-capabilities/operation-capabilities.json"
+    "operation-capabilities/operation-capabilities.json",
+    "code-builder/code-builder-metadata.json"
   ],
   "scripts": {
     "clean": "node -e \"require('node:fs').rmSync('dist', {recursive: true, force: true})\"",