@giveitsmaller/contracts 0.22.0 → 0.23.0

package/openapi/api.yaml

@@ -89,7 +89,7 @@ info:
     of truth instead of hardcoding magic numbers. A runtime
     `GET /api/uploads/limits` endpoint for dynamic discovery
     (per-tier / per-environment overrides) is a deferred follow-up.
-  version: 2.79.0
+  version: 2.83.0
   contact:
     name: API Support
 
@@ -1321,7 +1321,6 @@ paths:
                       operations:
                         - type: compress
                           options:
-                            mode: lossy
                             quality: 80
               v2_flat_single_source:
                 summary: >-
@@ -1336,7 +1335,6 @@ paths:
                   operations:
                     - type: compress
                       options:
-                        mode: lossy
                         quality: 80
                     - type: thumbnail
                       base: original
@@ -2440,7 +2438,8 @@ paths:
         - `operation`: Filter to a specific operation type
 
         The schema includes conditional validation rules using
-        `depends_on` (e.g. `quality` is only valid when `mode: lossy`).
+        `depends_on` (e.g. `crf` is only valid when `encoding_mode: crf`
+        for compress video).
         Per-enum-value availability uses the `per_value_availability` map
         on `OptionSchema` (ticket I17). Clients should use these to build
         dynamic forms with availability-aware UX.
@@ -2540,18 +2539,19 @@ paths:
                         # ticket IXE7QDxe — operation-level `options`
                         # is omitted for ops with mime_groups.
                         mime_groups:
-                          image:
-                            mimes: ["image/jpeg", "image/png", "image/webp"]
+                          # Illustrative shape only. Real compress.image ships
+                          # per-input-format groups (image_jpeg/image_png/
+                          # image_avif/image); image compress is lossy-only
+                          # (Option B) — no `mode`/`icc_profile`.
+                          image_jpeg:
+                            mimes: ["image/jpeg"]
                             options:
-                              mode:
-                                type: "enum"
-                                values: ["lossy", "lossless", "auto"]
                               quality:
                                 type: "integer"
                                 min: 1
                                 max: 100
-                                depends_on:
-                                  mode: "lossy"
+                              progressive:
+                                type: "boolean"
                       thumbnail:
                         description: "Generate a preview image from the source file"
                         default: false
@@ -8481,8 +8481,8 @@ components:
             See `GET /api/operations/schema` for the full schema.
 
             Options are validated against the schema using JSON Schema if/then/else
-            rules. For example, `quality` is only valid when `mode: lossy` for
-            compress operations.
+            rules. For example, `crf` is only valid when `encoding_mode: crf`
+            for compress video operations.
           additionalProperties: true
         base:
           type: string
@@ -10982,6 +10982,23 @@ components:
         max_inputs:
           type: integer
           description: Maximum number of inputs (multi-input operations only)
+        sole_op:
+          type: boolean
+          description: |
+            When `true`, this operation MUST be the only operation in its job —
+            it cannot be chained with other operations in the same job's
+            `operations[]`. To combine it with another operation (e.g. watermark
+            + compress), model them as SEPARATE jobs linked via `workflow_edges`
+            (the downstream job's `source` references the upstream via
+            `job_output`). Optional — absent means `false` (the operation chains
+            normally). Set on the ten ops the API bars from co-bundling
+            (`OperationType::bypassesV1ChainValidator()`): the multi-input ops
+            (merge, archive, image_watermark, video_watermark, audio_overlay,
+            audio_to_video, custom_luma) and the single-input fan-out / leaf ops
+            (text_watermark, video_text_watermark, split). SDK + frontend gate on
+            this to DISABLE-or-EXPLAIN an invalid op-combination before submit,
+            instead of surfacing a workflow-create 422. Per ADR-0025 (interim
+            signal ahead of the full operation-compatibility model, ADR-0024).
         per_role_cardinality:
           $ref: '#/components/schemas/PerRoleCardinality'
           description: |

package/operations/schemas/archive.yaml

@@ -5,6 +5,7 @@ operation:
   description: "Bundle multiple files into a single archive"
   default: false
   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: 50
   accepts_mixed_types: true
@@ -19,4 +20,11 @@ operation:
       type: enum
       values: [flat, by_job]
       default: flat
-      description: "flat = all files together at the top level; by_job = a separate subfolder for each source"
+      per_value_availability:
+        # The archive worker produces a FLAT bundle today; it does not yet read
+        # folder_structure (lambdas-confirmed — the option was a silent no-op for
+        # `by_job`). `flat` (the default, today's behaviour) stays stable; `by_job`
+        # is advertised-ahead `planned` (returns feature_not_available) until the
+        # worker implements per-source subfoldering. Honesty pass 2026-06-20.
+        by_job: { availability: planned }
+      description: "flat = all files together at the top level (default); by_job = a separate subfolder for each source (planned — not yet honored by the worker)"

package/operations/schemas/audio_overlay.yaml

@@ -36,6 +36,7 @@ operation:
     ADR-0004 §"V2 JobDefinition" + plan v5 §F1 round 6.
   default: false
   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
 

package/operations/schemas/audio_to_video.yaml

@@ -37,6 +37,7 @@ operation:
 
   default: false
   input_model: multi
+  sole_op: true   # bypasses V1 chain validation — must be the only operation in its job (ADR-0025)
   min_inputs: 1
   max_inputs: 2
 

package/operations/schemas/compress.yaml

@@ -7,86 +7,186 @@ operation:
   input_model: single
 
   mime_groups:
-    image:
+    # ---- IMAGE compress: per-input-format groups (Option B honesty pass) ----
+    # compress is SAME-FORMAT — the libcaesium worker recompresses the input
+    # format; an output format change is the API "compress+format" facade
+    # (output_format, below). Option applicability genuinely varies by input
+    # format, so image ships as parallel per-format mime_groups (FORMAT.md
+    # "Parallel mime_group naming" — materially different option shape):
+    #   image_jpeg -> + progressive   (JPEG-only)
+    #   image_png  -> + optimization_level (PNG-only)
+    #   image_avif -> + avif_speed    (AVIF-only)
+    #   image      -> webp/gif/svg/tiff (quality + output_format only)
+    # The worker reads quality/progressive/optimization_level/avif_speed (+ a
+    # `lossless` bool the API never emits). It HARDCODES metadata-strip, so
+    # `metadata` is a single fixed `all`. `mode` (lossy/lossless/auto) and
+    # `icc_profile` were REMOVED — the worker never read them and the API passed
+    # them verbatim; image compress is LOSSY-ONLY today (product decision
+    # 2026-06-20, lossless parked). width/height/fit/auto_orient stay removed
+    # (EsD1hs5u — worker recompresses only; resize -> thumbnail, format -> convert).
+    #
+    # output_format FACADE (replicated identically per group): non-`original`
+    # values resolve to a SINGLE API-canonicalized convert-with-size-cap pass
+    # (the compress worker never reads output_format). `webp` is live+proven
+    # (untagged = stable, ADR-0001 §1.4); auto/smallest/jpeg/png/avif stay
+    # `planned` until each value's canonicalization lands (per-value stable-flip
+    # with capability proof, ADR-0001/0006). `original` stays stable.
+    image_jpeg:
       mimes:
         - image/jpeg
+      options:
+        quality:
+          type: integer
+          min: 1
+          max: 100
+          default: 80
+          description: "Compression quality (1 = smallest file, 100 = best quality)."
+        metadata:
+          type: enum
+          values: [all]
+          default: all
+          description: >-
+            Metadata handling. `all` = strip all EXIF/IPTC/XMP — the only supported
+            behaviour (the compress worker always strips; preservation is not
+            currently available).
+        progressive:
+          type: boolean
+          default: true
+          description: "Enable progressive JPEG rendering (a low-quality preview renders first, then refines). JPEG only."
+        output_format:
+          type: enum
+          values: [original, auto, smallest, jpeg, png, webp, avif]
+          default: original
+          per_value_availability:
+            auto:     { availability: planned }   # runtime Accept-best selection — unbuilt
+            smallest: { availability: planned }   # runtime try-all-smallest selection — unbuilt
+            jpeg:     { availability: planned }   # facade path not live until its own canonicalization
+            png:      { availability: planned }   # facade path not live until its own canonicalization
+            avif:     { availability: planned }   # facade path not live until its own canonicalization
+          description: >-
+            Output format. original = keep input format (default); auto = best for browser
+            support (AVIF > WebP > JPEG via Accept hint); smallest = try all supported formats,
+            return the smallest. Non-`original` values are served by the API "compress+format"
+            facade (one combined convert-with-size-cap pass); see per_value_availability + FORMAT.md.
+
+    image_png:
+      mimes:
         - image/png
-        - image/gif
+      options:
+        quality:
+          type: integer
+          min: 1
+          max: 100
+          default: 80
+          description: "Compression quality (1 = smallest file, 100 = best quality)."
+        metadata:
+          type: enum
+          values: [all]
+          default: all
+          description: >-
+            Metadata handling. `all` = strip all EXIF/IPTC/XMP — the only supported
+            behaviour (the compress worker always strips; preservation is not
+            currently available).
+        optimization_level:
+          type: integer
+          min: 0
+          max: 6
+          default: 3
+          description: "PNG optimization effort (0-6, oxipng). Higher = smaller file, slower encode. Default 3."
+        output_format:
+          type: enum
+          values: [original, auto, smallest, jpeg, png, webp, avif]
+          default: original
+          per_value_availability:
+            auto:     { availability: planned }   # runtime Accept-best selection — unbuilt
+            smallest: { availability: planned }   # runtime try-all-smallest selection — unbuilt
+            jpeg:     { availability: planned }   # facade path not live until its own canonicalization
+            png:      { availability: planned }   # facade path not live until its own canonicalization
+            avif:     { availability: planned }   # facade path not live until its own canonicalization
+          description: >-
+            Output format. original = keep input format (default); auto = best for browser
+            support (AVIF > WebP > JPEG via Accept hint); smallest = try all supported formats,
+            return the smallest. Non-`original` values are served by the API "compress+format"
+            facade (one combined convert-with-size-cap pass); see per_value_availability + FORMAT.md.
+
+    image_avif:
+      availability: beta
+      # avif INPUT decode shipped in the compress-image worker via libheif
+      # (lambdas w34Taquf, #210). beta: live + opt-in, shape-stable.
+      # image/heic is intentionally NOT a compress input: compress is decode-only
+      # and there is no HEIC encoder, so the worker rejects a declared image/heic
+      # (FormatMismatch). heic stays on convert+thumbnail.
+      # WORKER LIMIT (not yet contract-expressible — F3 follow-up): the
+      # compress-image worker caps avif INPUT at 20MB (compression_processor.rs),
+      # below the general image size budget. Per-MIME input-size caps have no
+      # contract vocab today; tracked for the image-size-cap mechanism (F3).
+      mimes:
+        - image/avif
+      options:
+        quality:
+          type: integer
+          min: 1
+          max: 100
+          default: 80
+          description: "Compression quality (1 = smallest file, 100 = best quality)."
+        metadata:
+          type: enum
+          values: [all]
+          default: all
+          description: >-
+            Metadata handling. `all` = strip all EXIF/IPTC/XMP — the only supported
+            behaviour (the compress worker always strips; preservation is not
+            currently available).
+        avif_speed:
+          type: integer
+          min: 1
+          max: 10
+          default: 4
+          description: "AVIF encode speed (1-10, ravif). Lower = smaller file, slower encode; higher = faster, larger. Default 4."
+        output_format:
+          type: enum
+          values: [original, auto, smallest, jpeg, png, webp, avif]
+          default: original
+          per_value_availability:
+            auto:     { availability: planned }   # runtime Accept-best selection — unbuilt
+            smallest: { availability: planned }   # runtime try-all-smallest selection — unbuilt
+            jpeg:     { availability: planned }   # facade path not live until its own canonicalization
+            png:      { availability: planned }   # facade path not live until its own canonicalization
+            avif:     { availability: planned }   # facade path not live until its own canonicalization
+          description: >-
+            Output format. original = keep input format (default); auto = best for browser
+            support (AVIF > WebP > JPEG via Accept hint); smallest = try all supported formats,
+            return the smallest. Non-`original` values are served by the API "compress+format"
+            facade (one combined convert-with-size-cap pass); see per_value_availability + FORMAT.md.
+
+    image:
+      mimes:
         - image/webp
+        - image/gif
         - image/svg+xml
         - image/tiff
-        - image/avif
-      per_mime_availability:
-        # avif INPUT decode shipped in the compress-image worker via libheif
-        # (lambdas w34Taquf, #210). beta: live + opt-in, shape-stable.
-        # Re-add after the v2.67.0 interim crash-window drop (aYPbNVKD Phase 2).
-        # image/heic is intentionally NOT re-added to compress: compress is
-        # decode-only and there is no HEIC encoder, so the worker rejects a
-        # declared image/heic (FormatMismatch). heic stays on convert+thumbnail.
-        # WORKER LIMIT (not yet contract-expressible — F3 follow-up): the
-        # compress-image worker caps avif INPUT at 20MB (compression_processor.rs),
-        # below the general image size budget. Per-MIME input-size caps have no
-        # contract vocab today; tracked for the image-size-cap mechanism (F3).
-        image/avif: { availability: beta }
       options:
-        mode:
-          type: enum
-          values: [lossy, lossless, auto]
-          default: lossy
-          description: "Compression algorithm. lossy = smaller file, lossless = no quality loss, auto = best for format"
         quality:
           type: integer
           min: 1
           max: 100
           default: 80
-          depends_on: { mode: lossy }
-          description: "Compression quality (1 = smallest file, 100 = best quality). Only applies to lossy mode."
-        # 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).
+          description: >-
+            Compression quality (1 = smallest file, 100 = best quality). For animated
+            GIF the worker honours this but real-world size reduction is typically small.
         metadata:
           type: enum
-          values: [all, none, copyright, sensitive]
+          values: [all]
           default: all
           description: >-
-            Metadata handling. all = strip everything (smallest file), none = keep all EXIF/IPTC/XMP,
-            copyright = keep only copyright/author fields, sensitive = keep EXIF but strip GPS/location (GDPR-friendly)
-        icc_profile:
-          type: enum
-          values: [preserve, strip, srgb]
-          default: preserve
-          description: "ICC color profile handling. preserve = keep original, strip = remove, srgb = convert to sRGB"
-        progressive:
-          type: boolean
-          default: true
-          description: "Enable progressive rendering (JPEG only). Renders low-quality preview first, then refines."
+            Metadata handling. `all` = strip all EXIF/IPTC/XMP — the only supported
+            behaviour (the compress worker always strips; preservation is not
+            currently available).
         output_format:
           type: enum
           values: [original, auto, smallest, jpeg, png, webp, avif]
           default: original
           per_value_availability:
-            # FACADE (VcPeRWdD): "compress + change format" resolves to a SINGLE
-            # combined convert-with-size-cap pass canonicalized API-side (the
-            # compress worker stays same-format — it never reads output_format).
-            # Non-`original` values were a live untagged-`stable` silent no-op
-            # (worker ignored them, returned a same-format file at 200) — the
-            # hlKCslIu-class over-claim. Tagged `planned` until each value's
-            # facade piece lands (API canonicalization + lambdas encode), then
-            # flipped `stable` per value with capability proof (ADR-0001/0006).
-            # Values flip `stable` per value as each facade piece lands: `webp` is
-            # DONE (see the stable-flip note below); the rest stay `planned` — auto/
-            # smallest (runtime selection, unbuilt), jpeg/png/avif (no canonicalization
-            # live yet). `original` (same-format, today's behaviour) stays stable.
-            # WEBP STABLE-FLIP (VcPeRWdD): webp is now FUNCTIONAL end-to-end — API B
-            # (#422) canonicalizes compress(image,webp)→convert(webp,quality) + lambdas
-            # lossy-webp (PfGs5PBT) is live+proven on staging — so webp is removed from
-            # this map (untagged = stable, ADR-0001 §1.4). jpeg/png/avif/auto/smallest
-            # stay `planned` (their canonicalization is NOT in API B — flipping them now
-            # would stop the 422 while they still dispatch to the same-format worker =
-            # silent no-op, re-opening the over-claim).
             auto:     { availability: planned }   # runtime Accept-best selection — unbuilt
             smallest: { availability: planned }   # runtime try-all-smallest selection — unbuilt
             jpeg:     { availability: planned }   # facade path not live until its own canonicalization
@@ -381,86 +481,139 @@ operation:
     document_pdf:
       mimes:
         - application/pdf
+      # DOCUMENT-COMPRESS HONESTY (2026-06-20): the worker reads ONLY `quality`
+      # and maps it to a Ghostscript preset (76-100=/prepress, 51-75=/printer,
+      # 26-50=/ebook, 0-25=/screen) + a DPI-analysis fallback (compression-documents
+      # pdf.rs, lambdas-confirmed). The per-format options (profile/colorspace/
+      # pages/flatten_forms) are spec-defined but NOT yet read by the worker, so
+      # they are tagged `availability: planned` (advertised-ahead; FE hides them
+      # per the bare-planned-hide rule) rather than pruned — preserving the
+      # designed feature set for a future build (hub ruling). Per ADR-0001 §1.4.
       options:
+        quality:
+          type: integer
+          min: 1
+          max: 100
+          default: 50
+          description: "Compression quality (1 = smallest, 100 = best). Maps to a document compression preset (the only worker-honored document option today)."
         profile:
           type: enum
           values: [web, print, archive, max]
           default: web
-          description: "Optimization profile. web = aggressive (downsample images, strip metadata), print = preserve quality, archive = PDF/A compliance, max = smallest file"
+          availability: planned
+          description: >-
+            Optimization profile. web = aggressive (downsample images, strip
+            metadata), print = preserve quality, archive = PDF/A compliance,
+            max = smallest file. `planned` — not yet read by the worker (use `quality`).
         colorspace:
           type: enum
           values: [unchanged, rgb, cmyk, grayscale]
           default: unchanged
-          description: "Output color space"
+          availability: planned
+          description: "Output color space. `planned` — not yet read by the worker."
         pages:
           type: string
-          description: "Page selection (e.g. '1-5,8,10-12'). Omit to keep all pages."
+          availability: planned
+          description: "Page selection (e.g. '1-5,8,10-12'). Omit to keep all pages. `planned` — not yet read by the worker."
         flatten_forms:
           type: boolean
           default: false
-          description: "Flatten interactive form fields into static content"
+          availability: planned
+          description: "Flatten interactive form fields into static content. `planned` — not yet read by the worker."
 
     document_office:
       mimes:
         - application/vnd.openxmlformats-officedocument.wordprocessingml.document
         - application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
         - application/vnd.openxmlformats-officedocument.presentationml.presentation
+      # See the document_pdf honesty note: the worker reads ONLY `quality` today;
+      # the per-format options are `planned` (advertised-ahead, FE-hidden).
       options:
+        quality:
+          type: integer
+          min: 1
+          max: 100
+          default: 50
+          description: "Compression quality (1 = smallest, 100 = best). The only worker-honored document option today."
         image_quality:
           type: integer
           min: 1
           max: 100
           default: 80
-          description: "Recompress embedded images at this quality level (1 = smallest, 100 = best)"
+          availability: planned
+          description: "Recompress embedded images at this quality level (1 = smallest, 100 = best). `planned` — not yet read by the worker (use `quality`)."
         strip_macros:
           type: boolean
           default: true
-          description: "Remove VBA macros and ActiveX controls"
+          availability: planned
+          description: "Remove VBA macros and ActiveX controls. `planned` — not yet read by the worker."
         strip_hidden_data:
           type: boolean
           default: true
-          description: "Remove revisions, comments, personal info, hidden rows/columns, and speaker notes"
+          availability: planned
+          description: "Remove revisions, comments, personal info, hidden rows/columns, and speaker notes. `planned` — not yet read by the worker."
         strip_unused_fonts:
           type: boolean
           default: false
-          description: "Remove embedded fonts not referenced in the document. Risk: may affect rendering on systems without the font installed"
+          availability: planned
+          description: "Remove embedded fonts not referenced in the document. Risk: may affect rendering on systems without the font installed. `planned` — not yet read by the worker."
 
     document_odf:
       mimes:
         - application/vnd.oasis.opendocument.text
         - application/vnd.oasis.opendocument.spreadsheet
         - application/vnd.oasis.opendocument.presentation
+      # See the document_pdf honesty note: worker reads ONLY `quality`; the rest `planned`.
       options:
+        quality:
+          type: integer
+          min: 1
+          max: 100
+          default: 50
+          description: "Compression quality (1 = smallest, 100 = best). The only worker-honored document option today."
         image_quality:
           type: integer
           min: 1
           max: 100
           default: 80
-          description: "Recompress embedded images at this quality level"
+          availability: planned
+          description: "Recompress embedded images at this quality level. `planned` — not yet read by the worker (use `quality`)."
         strip_metadata:
           type: boolean
           default: true
-          description: "Remove document metadata (author, revision history, comments)"
+          availability: planned
+          description: "Remove document metadata (author, revision history, comments). `planned` — not yet read by the worker."
         strip_unused_styles:
           type: boolean
           default: false
-          description: "Remove style definitions not referenced in document content"
+          availability: planned
+          description: "Remove style definitions not referenced in document content. `planned` — not yet read by the worker."
 
     document_epub:
       mimes:
         - application/epub+zip
+      # See the document_pdf honesty note: worker reads ONLY `quality`; the rest `planned`.
       options:
+        quality:
+          type: integer
+          min: 1
+          max: 100
+          default: 50
+          description: "Compression quality (1 = smallest, 100 = best). The only worker-honored document option today."
         image_quality:
           type: integer
           min: 1
           max: 100
           default: 80
-          description: "Recompress embedded images at this quality level"
+          availability: planned
+          description: "Recompress embedded images at this quality level. `planned` — not yet read by the worker (use `quality`)."
         font_subsetting:
           type: boolean
           default: true
-          description: "Subset embedded fonts to only include glyphs used in the document. Significant size reduction for books with large font files"
+          availability: planned
+          description: "Subset embedded fonts to only include glyphs used in the document. Significant size reduction for books with large font files. `planned` — not yet read by the worker."
         strip_unused_css:
           type: boolean
           default: false
-          description: "Remove CSS rules not referenced by any content. Risk: may affect rendering in some readers"
+          availability: planned
+          description: "Remove CSS rules not referenced by any content. Risk: may affect rendering in some readers. `planned` — not yet read by the worker."

package/operations/schemas/convert.yaml

@@ -76,33 +76,29 @@ operation:
           type: enum
           values: [mp4, webm, ogg, gif]
           required: true
-          description: "Target format"
-        codec:
-          type: enum
-          values: [h264, h265, vp9, av1]
-          depends_on: { output_format: [mp4, webm, ogg] }
-          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-0023 (supersedes ADR-0020).
-            Not applicable to a `gif` output (no video codec): an explicit
-            `codec` on a `gif` output is rejected as `invalid_options` at
-            workflow-create (the API enforces this `depends_on`); FE/SDK prune
-            it pre-submit.
-        quality:
+          # The video codec is DETERMINED by the target container, NOT a caller
+          # choice: the convert-video worker hard-wires it per container
+          # (mp4 -> H.264/libx264, webm -> VP9, ogg -> Theora, gif -> palette;
+          # lambdas-confirmed video_convert.rs). The former `codec` option
+          # (enum h264/h265/vp9/av1) was a SILENT NO-OP — the worker never read
+          # it — so it was removed (honesty pass, 2026-06-20). To choose a codec,
+          # use compress.video (which has a real, worker-honored `codec`).
+          description: "Target format. The video codec is fixed by the container (mp4->H.264, webm->VP9, ogg->Theora, gif->palette) — not caller-selectable."
+        crf:
           type: integer
           min: 0
           max: 51
           default: 23
           depends_on: { output_format: [mp4, webm, ogg] }
+          # Renamed `quality` -> `crf` (2026-06-20) to match compress.video.crf
+          # and stop the misnomer: this is a Constant Rate Factor (0=best/lossless,
+          # 51=worst), the INVERSE of convert.image.quality (1-100, higher=better).
           description: >
-            CRF value (0 = lossless, 51 = worst). Video outputs only — NOT
-            applicable to a `gif` output (frame extraction has no CRF). An
-            explicit `quality` on a `gif` output is rejected as `invalid_options`
-            at workflow-create (the API enforces this `depends_on`); FE/SDK
-            prune it pre-submit.
+            CRF (Constant Rate Factor): 0 = lossless/best, 51 = worst. Lower = higher
+            quality + larger file (the inverse of image `quality`). Video outputs only —
+            NOT applicable to a `gif` output (frame extraction has no CRF). An explicit
+            `crf` on a `gif` output is rejected as `invalid_options` at workflow-create
+            (the API enforces this `depends_on`); FE/SDK prune it pre-submit.
 
     audio:
       mimes:
@@ -115,16 +111,18 @@ operation:
       options:
         output_format:
           type: enum
-          values: [mp3, aac, ogg, flac, wav]
+          values: [mp3, aac, ogg, opus, flac, wav]
           required: true
+          # `opus` added 2026-06-20 — the convert-audio worker produces it
+          # (audio/ogg container, .opus extension; lambdas-confirmed live).
           description: "Target format"
         bitrate:
           type: enum
           value_type: integer
           values: [64, 96, 128, 192, 256, 320]
           default: 128
-          depends_on: { output_format: [mp3, aac, ogg] }
-          description: "Output bitrate in kbps (lossy formats only)"
+          depends_on: { output_format: [mp3, aac, ogg, opus] }
+          description: "Output bitrate in kbps (lossy formats only — mp3/aac/ogg/opus)"
 
     # Only PDF conversion is supported. Office/ODF/EPUB conversion would require
     # LibreOffice which is not available in the document Lambda.

package/operations/schemas/custom_luma.yaml

@@ -34,6 +34,7 @@ operation:
     transition; this operation is the deliberate alternative).
   default: false
   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
 

package/operations/schemas/image_watermark.yaml

@@ -34,6 +34,7 @@ operation:
     Per ADR-0004 §"V2 JobDefinition" + plan v5 §F1.
   default: false
   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
 

package/operations/schemas/merge.yaml

@@ -5,6 +5,7 @@ operation:
   description: "Combine multiple files into one"
   default: false
   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: 10
   # All merge operations route to the single `ops-merge` Lambda via

package/operations/schemas/split.yaml

@@ -82,6 +82,7 @@ operation:
     Per ADR-0014.
   default: false
   input_model: single
+  sole_op: true   # bypasses V1 chain validation — must be the only operation in its job (ADR-0025)
 
   features:
     silence_mode_audio:

package/operations/schemas/text_watermark.yaml

@@ -14,6 +14,7 @@ operation:
       pattern); rotation default -45° and tile_spacing controls density.
   default: false
   input_model: single
+  sole_op: true   # bypasses V1 chain validation — must be the only operation in its job (ADR-0025)
 
   mime_groups:
     image: