@giveitsmaller/contracts 0.58.0 → 0.60.0

package/operation-capabilities/operation-capabilities.json

@@ -732,5 +732,5 @@
       "isAnimated": "maybe"
     }
   },
-  "schema_version": "2.171.0"
+  "schema_version": "2.188.0"
 }

package/operations/schemas/audio_overlay.yaml

@@ -241,7 +241,6 @@ operation:
           type: float
           min: -80.0
           max: -10.0
-          default: -50.0
           availability: planned
           description: |
             Silence threshold (dB) for the `sync_to_silence` feature.
@@ -254,7 +253,6 @@ operation:
           type: integer
           min: 50
           max: 30000
-          default: 500
           availability: planned
           description: |
             Minimum silence duration (milliseconds) to qualify as an
@@ -412,7 +410,6 @@ operation:
           type: float
           min: -80.0
           max: -10.0
-          default: -50.0
           availability: planned
           description: |
             Silence threshold (dB) for `sync_to_silence`. Inert
@@ -422,7 +419,6 @@ operation:
           type: integer
           min: 50
           max: 30000
-          default: 500
           availability: planned
           description: |
             Minimum silence duration (milliseconds) for

package/operations/schemas/audio_to_video.yaml

@@ -64,6 +64,7 @@ operation:
         - audio/opus
         - audio/mp4
         - audio/x-m4a
+      max_input_duration: "PT2H"   # 2h input ceiling (KzrquIX7; mirrors worker MAX_AUDIO_DURATION_SECS 7200, strict >)
       options:
         output_resolution:
           type: enum

package/operations/schemas/compress.yaml

@@ -24,10 +24,14 @@ operation:
     # fixed `all` — BOTH now superseded by the image-options work: RESIZE
     # (width/height/fit) is back STABLE (v2.97.0, the route-aware Output model);
     # `metadata` is strip/keep (canonical `strip`, deprecated `all`); `auto_orient`
-    # is re-added PLANNED (wave-2, below); and the old `icc_profile` is superseded by
-    # the decoupled `color_profile` control (wave-2, planned — ICC handling is its
-    # own axis, NOT folded into metadata-strip; that fold-in was the silent-colour-
-    # shift bug). See the per-option blocks for the live shape.
+    # is STABLE; and the old `icc_profile` is superseded by the decoupled
+    # `color_profile` control, also STABLE (only the `srgb` VALUE on the gif/tiff
+    # `image` group is still planned) — ICC handling is its own axis, NOT folded
+    # into metadata-strip; that fold-in was the silent-colour-shift bug.
+    # THE PER-OPTION BLOCKS ARE AUTHORITATIVE; this header is orientation only.
+    # (auto_orient/color_profile read "wave-2, planned" here until 2026-07-21,
+    # long after both went stable — a stale comment nearly got relayed to a
+    # consumer as fact. A comment cannot fail a test; do not cite one as shape.)
     #
     # output_format (replicated identically per group): the LIVE concrete
     # targets are `original` (no-op, default) and `webp` (the one proven
@@ -90,6 +94,7 @@ operation:
       # Resize-inside-Output shares the convert resize engine's 16MP output-area
       # wall — the per-axis 16384 cap can't express it (FORMAT.md §max_output_pixels).
       max_output_pixels: 16000000
+      max_input_size_bytes: 524288000   # 500 MiB compress input ceiling (uKsFzORi)
       options:
         quality:
           type: integer
@@ -261,7 +266,19 @@ operation:
       mimes:
         - image/png
       max_output_pixels: 16000000
+      max_input_size_bytes: 524288000   # 500 MiB compress input ceiling (uKsFzORi)
       options:
+        # PROVENANCE (author-side, NOT user-facing — kept out of the description per
+        # 7KkNSvdv / FE BhVwdlhQ: no implementation detail or licence copy in user text):
+        #   PNG lossy quantization is `imagequant` (GPL-3.0-or-later OR commercial);
+        #   lossless is `oxipng` (MIT — no licence claim). imagequant is licence-cleared
+        #   for our server-side SaaS backend ONLY — NOT a blanket clearance: static
+        #   linking makes the binary a combined GPLv3 work, so any future distribution
+        #   (desktop / on-prem) re-opens it. Also covers GIF quantisation (5mwmSb3t).
+        #   Ruling: the user (antoniocs), 2026-06-26, quoted verbatim in *lambdas*
+        #   ADR-0012 (compression_lambdas/docs/explanation/decisions/
+        #   0012-lossy-png-quantization-licensing.md — the LAMBDAS ADR, distinct from
+        #   contracts' own ADR-0012 band-ceiling). Was cited as card `kkajDFXD`.
         quality:
           type: integer
           min: 1
@@ -270,12 +287,12 @@ operation:
           honored_on: [same_format]
           description: >-
             Compression quality (1-100). For PNG this is the SINGLE lossy/lossless
-            control: `quality` < 100 applies lossy palette quantization (imagequant —
-            licence-cleared for our server-side SaaS backend, `kkajDFXD`; the value is
-            the quantization level), while `quality: 100` keeps the PNG lossless (oxipng
-            optimisation only — tune the lossless effort via `optimization_level`).
-            1 = smallest file, 100 = best quality / lossless. There is no separate
-            lossy/lossless toggle for PNG — it is purely quality-driven.
+            control: `quality` < 100 applies lossy palette quantization (the value is
+            the quantization level), while `quality: 100` keeps the PNG lossless
+            (lossless optimisation only — tune the lossless effort via
+            `optimization_level`). 1 = smallest file, 100 = best quality / lossless.
+            There is no separate lossy/lossless toggle for PNG — it is purely
+            quality-driven.
         metadata:
           type: enum
           values: [strip, keep, all]
@@ -385,6 +402,7 @@ operation:
       mimes:
         - image/avif
       max_output_pixels: 16000000
+      max_input_size_bytes: 20971520   # 20 MiB compress input ceiling (uKsFzORi; AVIF decode OOM guard, worker AVIF_MAX_MB)
       options:
         quality:
           type: integer
@@ -544,6 +562,7 @@ operation:
       mimes:
         - image/webp
       max_output_pixels: 16000000
+      max_input_size_bytes: 524288000   # 500 MiB compress input ceiling (uKsFzORi)
       options:
         quality:
           type: integer
@@ -701,10 +720,68 @@ operation:
     # optimiser `lossless` knob does not apply. SVG compression is SVGO; only
     # quality/metadata/output_format carry. NO Resize / lossless / area cap here.
     image_svg:
+      # SVG -> SVG optimisation via SVGO is STABLE and working. Restored
+      # 2026-07-21 (G9O6yrQD); Form-A attestation is compression-image.yaml
+      # `compress.image` accepts (lambdas #325).
+      #
+      # WHY THIS BLOCK IS WRITTEN DEFENSIVELY: on 2026-07-17 this group was
+      # downgraded to `planned` on the strength of a single stale COMMENT in the
+      # lambda manifest ("SVG is a follow-up"). The worker had implemented SVGO
+      # all along — image_compressor.rs:211 maps image/svg+xml, :1225
+      # compress_svg shells to the SVGO binary via ToolRunner, and the crate
+      # Dockerfile builds and ships it. Staging had proved it the day before:
+      # job 019f6aa3-d275-7b10-a5cf-58acc705c7e2, 43777 -> 33061 bytes (24.5%),
+      # "Operation completed successfully".
+      # Because `original` is ALSO this option's default, and the API
+      # materializes defaults before the availability gate (api 4a7a2628,
+      # 2026-07-17 20:16), the downgrade 422'd SVG compress at create for EVERY
+      # website user — the workbench never sends output_format, so the bare path
+      # is the only path a customer has. A working, deployed, customer-facing
+      # capability was dark for four days (e2e J3sbGMSb).
+      # The rule that came out of it (hub standing policy, 2026-07-21): a
+      # downgrade MUST cite worker CODE or a STAGING LOG positively showing the
+      # capability does NOT work. An absent manifest entry is NOT evidence of an
+      # absent capability, and where no evidence exists either way the answer is
+      # "we do not know", which BLOCKS the downgrade rather than licensing it.
+      #
+      # THE GROUP STAYS STABLE. A group-level `planned` would ALSO gate off
+      # `output_format: webp`, which works today via the convert facade — the
+      # over-narrow the user's standing rule forbids ("exclude only on EVIDENCE
+      # OF BREAKAGE", 2026-07-07).
+      #
+      # NOT "LOSSLESS" — do not describe this route as lossless anywhere
+      # user-facing. `tools/svgo/svgo.ts` enables `preset-default`, which
+      # includes `convertPathData`; that rounds path coordinates (default
+      # floatPrecision 3), so geometry changes within a rounding tolerance.
+      # "Visually preserving" is the honest wording. (The worker does set
+      # lossless=true internally at image_compressor.rs:1778, but it lands in
+      # CompressionResult.settings which CompressionProcessor discards — its own
+      # NOTE at :1782 — so it reaches no consumer, and nothing should start
+      # claiming it.)
       mimes:
         - image/svg+xml
+      # KNOWN OVER-ADVERTISEMENT, DELIBERATELY LEFT AS-IS — do NOT lower this
+      # unilaterally. compress_svg holds the markup in memory and caps SVGO
+      # output at 100 MiB (image_compressor.rs:1241), so the 500 MiB image/*
+      # default over-states what the SVG route can actually serve: a valid input
+      # inside the advertised limit can fail on the worker cap. Codex flagged it
+      # on the flip PR and it is a real gap.
+      #
+      # It stays 500 MiB here because this value is an API-ENFORCED constant, not
+      # documentation — tests/test_group_input_caps.py pins these to the api
+      # enforcer, so changing the contract alone would create contract-vs-enforcer
+      # DRIFT rather than fix anything. Lowering it needs an api co-land, and a
+      # figure lambdas has actually measured (the only SVG datapoint today is a
+      # 43 KB fixture). Ticket filed; lambdas already flagged a per-format cap as
+      # their follow-up.
+      #
+      # PRE-EXISTING, not introduced by the 2026-07-21 restore: the same 500 MiB
+      # applied while this route was stable before 2026-07-17. Recorded rather
+      # than silently carried.
+      max_input_size_bytes: 524288000   # 500 MiB compress input ceiling (uKsFzORi; image/* default)
       options:
-        # No `quality`: compress SVG is SVG->SVG via SVGO (lossless vector optimise);
+        # No `quality`: compress SVG is SVG->SVG via SVGO (VISUALLY PRESERVING
+        # vector optimise — not lossless; see the group note above on convertPathData);
         # `quality` is never passed to the worker, so a quality slider here is a no-op
         # (removed — lambdas worker-code investigation, the SVG-quality ticket). Raster
         # output (the webp facade route) goes through convert, which carries its own
@@ -729,8 +806,26 @@ operation:
             auto:     { availability: planned }
             smallest: { availability: planned }
           description: >-
-            Output format. original = keep input format (default); webp = recompress to
-            WebP. Concrete format changes are handled by the convert operation. `auto` /
+            Output format. `original` = keep input format — SVG -> SVG optimisation
+            via SVGO. **STABLE and working** (restored 2026-07-21, G9O6yrQD;
+            worker-proven on staging job 019f6aa3-d275-7b10-a5cf-58acc705c7e2 at
+            24.5% reduction, Form-A attested in lambdas #325). It is also the schema
+            `default`, so a bare `compress` on an SVG takes this route.
+            Optimisation is **visually preserving, NOT lossless** — SVGO's
+            `preset-default` includes `convertPathData`, which rounds path
+            coordinates within a tolerance.
+            NOTE for anyone re-reading history here: this value was `planned` from
+            2026-07-17 to 2026-07-21 on a false premise, and because the API
+            materializes an omitted default before the availability gate (api
+            4a7a2628), that tag 422'd EVERY website SVG compress at create — the
+            workbench does not send `output_format`, so the defaulted path is the
+            only path a customer has. A `planned` DEFAULT is therefore never a
+            partial restriction; it is a total one. Weigh that before tagging any
+            future default `planned`.
+            `webp` = recompress to WebP: **STABLE and working today** — this facade
+            route canonicalizes to the `convert` operation (`convert.image_svg` carries
+            its own quality), which is why this group is NOT gated at group level.
+            Concrete format changes are handled by the convert operation. `auto` /
             `smallest` are PLANNED auto-format directives (the server picks the
             best/smallest candidate format, reported via the result `mime_type`) —
             selection strategies, not concrete targets, planned until supported. See
@@ -743,6 +838,7 @@ operation:
         - image/gif
         - image/tiff
       max_output_pixels: 16000000
+      max_input_size_bytes: 524288000   # 500 MiB compress input ceiling (uKsFzORi)
       options:
         quality:
           type: integer
@@ -1136,7 +1232,6 @@ operation:
           type: float
           min: 0.25
           max: 4.0
-          default: 1.0
           availability: planned
           # SHORT-FORM only, mirroring trim: the long-form (Fargate) path does not
           # apply speed, so it is rejected at create via the
@@ -1147,7 +1242,7 @@ operation:
           # lambdas — a pre-flip rename is cheap while planned. Audio pitch is
           # PRESERVED via ffmpeg `atempo` (tempo-shift, NOT `asetrate` resample).
           description: >
-            Playback speed multiplier. 1.0 = unchanged (default), 2.0 = twice as
+            Playback speed multiplier. 1.0 = unchanged, 2.0 = twice as
             fast (half the output duration), 0.5 = half speed (double the
             duration); range 0.25–4.0. Audio PITCH IS PRESERVED (a tempo-shift,
             not a resample — ffmpeg `atempo` semantics), so a 2.0x clip sounds
@@ -1173,6 +1268,7 @@ operation:
         - application/vnd.openxmlformats-officedocument.wordprocessingml.document
         - application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
         - application/vnd.openxmlformats-officedocument.presentationml.presentation
+      max_input_size_bytes: 104857600   # 100 MiB compress input ceiling (uKsFzORi; zip-based worker MAX_INPUT_SIZE)
       # See the document_pdf honesty note: the worker reads ONLY `quality` today;
       # the per-format options are `planned` (advertised-ahead, FE-hidden).
       options:
@@ -1189,17 +1285,14 @@ operation:
         # if a distinct image-vs-document quality split is genuinely wanted (small wiring).
         strip_macros:
           type: boolean
-          default: true
           availability: planned
           description: "Remove VBA macros and ActiveX controls. `planned` — not yet supported."
         strip_hidden_data:
           type: boolean
-          default: true
           availability: planned
           description: "Remove revisions, comments, personal info, hidden rows/columns, and speaker notes. `planned` — not yet supported."
         strip_unused_fonts:
           type: boolean
-          default: false
           availability: planned
           description: "Remove embedded fonts not referenced in the document. Risk: may affect rendering on systems without the font installed. `planned` — not yet supported."
 
@@ -1208,6 +1301,7 @@ operation:
         - application/vnd.oasis.opendocument.text
         - application/vnd.oasis.opendocument.spreadsheet
         - application/vnd.oasis.opendocument.presentation
+      max_input_size_bytes: 104857600   # 100 MiB compress input ceiling (uKsFzORi; zip-based worker MAX_INPUT_SIZE)
       # See the document_pdf honesty note: worker reads ONLY `quality`; the rest `planned`.
       options:
         quality:
@@ -1223,18 +1317,17 @@ operation:
         # if a distinct image-vs-document quality split is genuinely wanted (small wiring).
         strip_metadata:
           type: boolean
-          default: true
           availability: planned
           description: "Remove document metadata (author, revision history, comments). `planned` — not yet supported."
         strip_unused_styles:
           type: boolean
-          default: false
           availability: planned
           description: "Remove style definitions not referenced in document content. `planned` — not yet supported."
 
     document_epub:
       mimes:
         - application/epub+zip
+      max_input_size_bytes: 104857600   # 100 MiB compress input ceiling (uKsFzORi; zip-based worker MAX_INPUT_SIZE)
       # See the document_pdf honesty note: worker reads ONLY `quality`; the rest `planned`.
       options:
         quality:
@@ -1250,11 +1343,9 @@ operation:
         # if a distinct image-vs-document quality split is genuinely wanted (small wiring).
         font_subsetting:
           type: boolean
-          default: true
           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 supported."
         strip_unused_css:
           type: boolean
-          default: false
           availability: planned
           description: "Remove CSS rules not referenced by any content. Risk: may affect rendering in some readers. `planned` — not yet supported."

package/operations/schemas/convert.yaml

@@ -83,13 +83,14 @@ operation:
         metadata:
           type: enum
           values: [strip, keep]
-          default: strip
           availability: planned
           honored_on: [format_change]
           description: >-
             Metadata handling across a format change. `strip` = remove all
-            EXIF/IPTC/XMP (default), `keep` = preserve. `planned` — metadata is not
-            yet preserved across a format change. The honoured target subset may
+            EXIF/IPTC/XMP, `keep` = preserve. `planned` — metadata is not
+            yet preserved across a format change, so this option carries **no
+            default**: omit it and the worker's own behaviour applies. The
+            honoured target subset may
             narrow (avif/heic targets are re-encoded and cannot keep metadata).
         width:
           type: integer
@@ -463,7 +464,12 @@ operation:
           default: "1"
           description: |
             Page selection (e.g. '1-5,8'). Each resolved page produces a
-            separate output file. **Maximum 200 resolved entries per
+            separate output file whose `page_index` is the **literal source
+            page number** — a sparse selection stays sparse: `pages: '1-5,8'`
+            yields outputs with `page_index` `1,2,3,4,5,8` (NOT renumbered
+            `1..6`), and `pages: '5-7'` yields `5,6,7`. The download `filename`
+            suffix is a separate 0-based array position and does NOT track the
+            page number. **Maximum 200 resolved entries per
             request** — aligns with the `OperationResult.outputs[]`
             `maxItems: 200` cap. Expressions resolving to more than 200
             entries (e.g. `'1-201'`, `'1-100,102-205'`) are out of

package/operations/schemas/merge.yaml

@@ -124,9 +124,26 @@ operation:
           type: integer
           min: 1
           max: 60
-          default: 30
+          # `availability: planned` AND the `default:` REMOVED — the two halves
+          # are one fix, not two. The V1 merge worker hardcodes 30 fps
+          # (`filter_graph.rs:3` `TARGET_FPS = 30`) and rejects the `fps` key on
+          # PRESENCE, so it rejected requests asking for the frame rate it was
+          # already about to produce. A schema-driven client materialises the
+          # defaults whose `depends_on` is satisfied, so `default: 30` was itself
+          # what put the rejected key on the wire — every UI slideshow merge sent
+          # `fps: 30` and died at run time without the caller touching anything.
+          # Marking it `planned` while KEEPING the default would only move that
+          # death earlier (422 at create for every slideshow, per api's
+          # materialise-to-evaluate gate #551). Dropping the default stops the key
+          # being sent at all, so slideshows produce 30 fps exactly as before, and
+          # only a caller who explicitly asks for a rate gets an honest 422.
+          # Worker-side follow-up to actually honour it: lambdas EJOfg8c9.
+          availability: planned
           depends_on: { output_type: video }
-          description: "Output frame rate"
+          description: >-
+            Output frame rate. **Not yet configurable** — slideshow output is
+            currently produced at a fixed 30 fps; setting this explicitly is
+            rejected (`feature_not_available`). Omit it to get 30 fps.
         video_format:
           type: enum
           values: [mp4, webm]
@@ -249,7 +266,26 @@ operation:
         normalize_audio:
           type: boolean
           default: true
-          description: "Normalize audio levels across all clips"
+          # 🔴 UNAVAILABLE ON LONG-FORM — and this one needed a RULING, not a
+          # mechanical marking. Long-form FORCES loudnorm off, so:
+          #   accepting the default `true` is a SILENT NO-OP — the caller asked
+          #     for normalisation and we quietly skip it;
+          #   refusing it kills EVERY defaulted long-form merge.
+          # Neither is acceptable, which is precisely the situation this overlay
+          # exists for: the defaulted value is DROPPED AND REPORTED rather than
+          # silently ignored or fatal.
+          #
+          # POSITION 4 in the worker's first-hit `LONG_FORM_REJECTED` array, and
+          # it has NO `depends_on` at all — so it materialises on every merge
+          # unconditionally. Fixing `encoding_mode` alone would move the failure
+          # from position 2 to position 4 with a different message and an
+          # identical outcome for the customer.
+          per_class_availability:
+            long_form_re_encode: { availability: planned }
+          description: >-
+            Normalize audio levels across all clips. NOT available on the
+            long-form path, which forces loudness normalisation off — a defaulted
+            value is dropped and reported there rather than silently ignored.
 
         re_encode_mode:
           type: enum
@@ -308,8 +344,59 @@ operation:
           values: [crf, target_size]
           default: crf
           depends_on: { re_encode_mode: [auto, always] }
+          # 🔴 THE WHOLE OPTION IS UNAVAILABLE ON LONG-FORM, NOT JUST ONE VALUE.
+          # The long-form Fargate worker refuses `encoding_mode` BY PRESENCE — it
+          # does not read the value at all (`LONG_FORM_REJECTED`, position 2).
+          #
+          # This was previously declared only on the `target_size` VALUE, which
+          # said `crf` was honoured on long-form. It is not. So the API's
+          # drop-vs-422 rule looked at a defaulted `encoding_mode: crf`, found it
+          # available, and passed it to a worker that rejects the key — and every
+          # merge left on automatic settings failed at the worker after a 201.
+          # THE RULE WAS CORRECT; ITS INPUT WAS A LIE (user report 2026-07-29,
+          # workflow 019fae34-d903-7bfe-9ab4-5e5f0b7a9bc4).
+          #
+          # `depends_on: re_encode_mode ∈ [auto, always]` is SATISFIED by default
+          # (`re_encode_mode` defaults to `auto`), so this materialises on every
+          # merge. Nobody chose it.
+          #
+          # Effect once api reads this: a DEFAULTED value is dropped and reported
+          # on `dropped_options[]`, and the merge runs on the path's native
+          # single-pass CRF. An EXPLICIT value still 422s, correctly — the caller
+          # asked for something this path cannot do.
+          per_class_availability:
+            long_form_re_encode: { availability: planned }
           per_value_depends_on:
             target_size: { codec: [h264] }
+          per_value_availability:
+            # `target_size` is honoured on the SHORT-FORM path (the worker
+            # parses+validates it and selects two-pass FFmpeg orchestration),
+            # but the long-form Fargate path is single-pass-CRF BY CONSTRUCTION
+            # in Phase 2 — two-pass target-size lands in Phase 3. So this is a
+            # per-EXECUTION-PATH limitation, not an operation-wide one.
+            #
+            # Marking the whole option `planned` would withdraw a real, working
+            # short-form capability from every customer in order to describe a
+            # long-form gap — the SVG withdrawal mirrored. `per_class_availability`
+            # is the instrument that lets us say the true thing instead.
+            #
+            # LIVE CASE, not hypothetical: both SDKs SYNTHESIZE
+            # `encoding_mode: target_size` whenever the caller sets an ergonomic
+            # `targetSize` (merge.ts / MergeBuilder.php), so a caller who never
+            # typed this key reaches Fargate with it set and the job dies mid-
+            # execution. With this overlay the API can refuse at CREATE with an
+            # honest `feature_not_available` naming target-size-on-long-form,
+            # while the identical call on short-form inputs keeps working
+            # unchanged. sdks `zJN6XIi5`.
+            target_size:
+              # Blanket truth stated explicitly alongside the overlay: `stable`
+              # is TRUE — short-form honours target_size end to end. The overlay
+              # restricts one class on top, and most-cautious inheritance yields
+              # the intended behaviour. Required by PerValueAvailabilityEntry so
+              # the absence of a key never has to carry meaning.
+              availability: stable
+              per_class_availability:
+                long_form_re_encode: { availability: planned }
           # target_size is currently codec=h264 only — h265 / vp9 / av1
           # each require a different encoder invocation and are tracked
           # as separate per-codec Lambda follow-ups. The

package/operations/schemas/render_variants.yaml

@@ -7,13 +7,36 @@ operation:
   # ticket w3EwzHYd. Worker = the shared convert image-encode stack + FitMode
   # (lambdas-confirmed reuse: image_convert.rs encode + domain/thumbnailer.rs).
   #
-  # availability: planned — the worker (lambdas 08q0ySAc) + its SNS subscription
-  # (terraform MNuDYJaY) are downstream of this contract, so the server returns
-  # `feature_not_available` (422) until they are live. The planned -> beta flip
-  # is a SEPARATE lockstep cut once the worker + wire are up (the two-gate rule;
-  # never flip beta ahead of the publisher). Source MIMEs are jpeg/png/webp only
-  # — AVIF is encode-only in the worker stack (decode unsupported), so it is a
-  # valid `output_format` target but NOT a source input.
+  # availability: planned — the blocker is that the worker has NEVER BEEN
+  # EXERCISED, not that it does not exist. Flip gate: lambdas px2OKk42 (a
+  # direct-invoke staging proof asserting TRANSFORMATION — each output's decoded
+  # pixel dimensions match its requested target, and two differently-sized
+  # targets differ from each other; "N outputs exist" passes for any re-encode).
+  # The flip to beta is a SEPARATE lockstep cut (the two-gate rule; never flip
+  # beta ahead of the publisher).
+  #
+  # This comment previously justified `planned` by asserting that the worker
+  # (08q0ySAc) and its SNS subscription (terraform MNuDYJaY) did not exist yet.
+  # Both halves were measured FALSE on 2026-07-28: the Lambda is deployed
+  # (`gisl-stg-euw1-operation-render-variants`, image git-fe33902) and its event
+  # source mapping has been `Enabled` on the queue since 2026-06-09. What is
+  # true is that it has never run — zero log streams, against a positive control
+  # showing non-zero for merge / compression-image / video-text-watermark in the
+  # same query. DEPLOYED and WIRED are not PROVEN, so this stays `planned`.
+  #
+  # Deliberately restated as the GATE being waited on rather than a snapshot of
+  # another repo's infrastructure: a gate cannot rot, a restated snapshot does —
+  # this one had gone false underneath us, which is the SVG failure shape. Do
+  # not reintroduce cross-repo state claims here; cite the owning repo's ticket.
+  #
+  # No caller impact at any point: `render_variants` is a capability-only
+  # artifact op and is deliberately NOT an API `OperationType` enum case, so it
+  # is unreachable from the API regardless of this value (API activation is
+  # uDW3k2Gw, Backlog P2 — the worker proof does not depend on it).
+  #
+  # Source MIMEs are jpeg/png/webp only — AVIF is encode-only in the worker
+  # stack (decode unsupported), so it is a valid `output_format` target but NOT
+  # a source input.
   description: "Generate multiple resized / re-encoded image variants from a single source image in one operation (image fan-out)."
   availability: planned
   input_model: single

package/operations/schemas/split.yaml

@@ -44,13 +44,23 @@ operation:
       (cross-ref [`WgCqnMRa`](https://trello.com/c/WgCqnMRa))
     - GIF: resolved frame count after expansion `<= 200`
 
-    **Output naming**: 3-digit zero-padded — `output-001` ..
-    `output-200`. Matches the convert PDF→N precedent.
+    **Output naming (S3 object key)**: the object-key leaf is 3-digit
+    zero-padded — `output-001` .. `output-200` (ADR-0014 §D9). This binds the
+    **S3 object key**, NOT the user-facing download filename — the API
+    synthesises that separately (see `OperationDownload.filename` in
+    `openapi/api.yaml`). Only the **3-digit zero-padding** follows the convert
+    PDF→N precedent — convert keys are `page-NNN.ext`, split keys are
+    `output-NNN.ext`.
 
     **Output envelope binding**:
     - `image_gif`: `PositionIndexed` (frame stream-position 0-based
       ordinal)
-    - `document_pdf`: `PageIndexed` (1-based gapless page index)
+    - `document_pdf`: `PageIndexed` (1-based literal source page number).
+      **`mode: page_range` only** — each output is one page, so `page_index` is
+      that page. For **`mode: page_groups`** an output spans multiple source
+      pages, so a single `page_index` cannot name them all; that grouped-output
+      semantics is NOT specified by this correction and is deferred (do not
+      assume it is the group's first page — that is unverified).
     - `audio`: `PositionIndexed` (cut stream-position ordinal)
     - `video`: `PositionIndexed` (cut stream-position ordinal)