@giveitsmaller/contracts 0.73.0 → 0.78.0

package/operations/schemas/convert.yaml

@@ -352,6 +352,17 @@ operation:
             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.
+            Left at 23 (the default) when converting an MP4 to MOV and the
+            streams can be carried over as they are, the video is copied without
+            re-encoding, so its quality is unchanged. Choose any other value to
+            force a re-encode.
+          # AUTHOR NOTES (rFBKrheN, 2026-09-24): a value EQUAL to the default is
+          # read as defaulted — the contract's own proxy (FORMAT.md per-class drop
+          # rule; api PerClassOptionAvailabilityResolver::wasChosenByTheCaller),
+          # because the SDKs and the frontend materialise every default. lambdas
+          # #439 implements the stream-copy (MP4 -> MOV only: MOV is not a
+          # convert.video INPUT). A caller who truly wants a re-encode
+          # at exactly 23 cannot express it; accepted, since the copy is lossless.
         trim_start:
           type: float
           min: 0

package/operations/schemas/merge.yaml

@@ -41,7 +41,13 @@ operation:
           max: 5000
           default: 500
           depends_on: { output_type: gif }
-          description: "Milliseconds between frames"
+          # GIF stores frame delays in centiseconds (DkucstQG, lambdas MSG
+          # 482596c7): 15 ms alternates 20/10 per frame on prod ffmpeg 7.1.1 today;
+          # lambdas KbmfS94r rounds uniformly to the nearest 10 ms. Deliberately NOT
+          # `multipleOf: 10` — that would 422 values accepted today.
+          description: >-
+            Milliseconds between frames. GIF timing has a 10 ms resolution, so use
+            a multiple of 10 — other values cannot be shown exactly.
         loop_count:
           type: integer
           min: 0
@@ -190,6 +196,34 @@ operation:
           # max_total_duration (24h single-pass budget, SPIKE-0); size is the
           # per-tier secondary cap.
           availability: stable
+          # CONCAT-UNIFORMITY (MjzzPCWt, 2026-09-24). This class concatenates
+          # with the FFmpeg concat demuxer, which requires every input to share
+          # its stream layout and stream attributes. A heterogeneous pair was
+          # ACCEPTED on prod and then FAILED at the worker
+          # (input_stream_topology_mismatch; e2e wf 01a0d261). Reasons are
+          # lambdas' re_encode.rs classifier names. `structural` is PERMANENT
+          # (reconciling it, e.g. silence-padding a missing audio track, is a
+          # parked product decision); `attributes` holds until the
+          # heterogeneous re-encode (lambdas Phase 3: Y2Wgf028 / 9QlXjCCI /
+          # DjtJchlt / XY94t9N4) ships, and is lifted per attribute once proven.
+          # The API refuses at create with INPUTS_NOT_CONCAT_UNIFORM for every
+          # reason its upload probe can see; the worker gate is the backstop for
+          # the rest (see the openapi 422 description for the coverage rule).
+          input_uniformity:
+            refusal: INPUTS_NOT_CONCAT_UNIFORM
+            structural:                  # permanent
+              - input_count_below_minimum
+              - input_topology_not_single_video
+              - input_topology_multi_audio
+              - input_topology_extra_streams
+              - input_stream_topology_mismatch
+              - input_stream_order_mismatch
+            attributes:                  # until the heterogeneous re-encode ships
+              video: [codec, codec_tag, framerate, pix_fmt, profile, resolution, sar, timebase]
+              audio: [codec, sample_rate, channels, channel_layout, sample_fmt, timebase]
+              # Not a stream kind: a video/audio stream FIELD present on one
+              # input and absent on another (lambdas' input_metadata_inconsistent).
+              field_presence: [input_metadata_inconsistent]
           constraints:                              # baseline = every tier without a per_tier_constraints override
             max_total_duration: "PT24H"              # 24h (was PT12H) — binding Enterprise ceiling
             max_total_input_size_bytes: 5000000000   # 5 GB combined (Pro)

package/operations/schemas/split.yaml

@@ -56,17 +56,24 @@ operation:
     - `image_gif`: `PositionIndexed` (frame stream-position 0-based
       ordinal)
     - `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).
+      With **`mode: page_range`** each output is one page, so `page_index` is
+      that page. With **`mode: page_groups`** each output is a group of
+      consecutive pages and `page_index` is the group's FIRST source page;
+      the group covers `page_index` .. `page_index + page_groups - 1`, and
+      the last group ends at the document's last page (so it may be
+      shorter). Verified in the worker, not assumed: `compression_lambdas`
+      `crates/split/src/processor.rs` passes each range's START page as the
+      index, over ranges from `resolve_page_groups` (`pdf_range.rs`, tests
+      `page_groups_remainder` / `page_groups_size_larger_than_total`).
+      Specified 2026-09-25 (card `jGTLrpzK`); the group stays `planned`
+      until a production record exists.
     - `audio`: `PositionIndexed` (cut stream-position ordinal)
     - `video`: `PositionIndexed` (cut stream-position ordinal)
 
     **`precision` flag** (audio + video only): `fast` (default) =
     packet-boundary approximate cuts; `exact` = re-encode-aligned
-    precise cuts. Mime_group scoping is the gate — precision does
+    precise cuts (`planned` — the API refuses it at create until the
+    re-encode path is priced). Mime_group scoping is the gate — precision does
     NOT apply to GIF or PDF (frame extraction is exact and PDF page
     selection is exact by definition).
 
@@ -92,8 +99,9 @@ operation:
       description: |
         Silence-detect cut mode for audio (`mode: silence` —
         server-side silence detection). `beta`: shape-stable + opt-in.
-        The mode ships dark until the API regenerates enum validation
-        to accept `mode: silence`. The `silence` enum value carries a
+        Accepted at workflow-create by any API build that vendors this
+        value, since the validator reads the enum from the vendored
+        schema. The `silence` enum value carries a
         matching `per_value_availability: beta` on `audio.mode`.
 
   mime_groups:
@@ -149,12 +157,17 @@ operation:
           pattern: '^\d+(-\d+)?(,\d+(-\d+)?)*$'
           required: true
           depends_on: { mode: page_range }
-          description: |
-            Page-range expression (e.g. "1-5", "1,3,5-7", "10-20").
-            1-based inclusive. Required when `mode: page_range`.
-            Resolved page count MUST be <= 200 (`invalid_options`
-            422 if exceeded — cross-ref
-            [`WgCqnMRa`](https://trello.com/c/WgCqnMRa)).
+          # AUTHOR NOTES (moved out of the user-facing description, ewOlw35Z,
+          # 2026-09-23 — frontend shows option descriptions to users). Preserved verbatim:
+          #   Page-range expression (e.g. "1-5", "1,3,5-7", "10-20").
+          #   1-based inclusive. Required when `mode: page_range`.
+          #   Resolved page count MUST be <= 200 (`invalid_options`
+          #   422 if exceeded — cross-ref
+          #   [`WgCqnMRa`](https://trello.com/c/WgCqnMRa)).
+          description: >-
+            Pages to extract, e.g. "1-5", "1,3,5-7" or "10-20" — 1-based and
+            inclusive. Required when `mode: page_range`. At most 200 pages;
+            more is refused with `invalid_options`.
 
         page_groups:
           type: integer
@@ -196,6 +209,13 @@ operation:
       # The two `precision` values have genuinely different duration behaviour
       # and the contract has no primitive that can say so:
       #
+      # 🔴 TODAY THE API REFUSES `exact` AT CREATE for every split (audio and
+      # video) — the deliberate "re-encode path not yet priced" gate
+      # (`compression_api` SplitOptionsValidator, reported 2026-09-23, Q8QsYYNn).
+      # So `exact` never reaches a worker, and `per_value_availability` tags it
+      # `planned`. The worker behaviour below is what `exact` WILL do once the
+      # API admits it:
+      #
       #   `exact` computes a time budget from the probed duration and refuses
       #           when it does not fit — WORKER-SIDE, after download and probe
       #           (`processor.rs` reads `probe.duration_secs`), returning a
@@ -247,7 +267,8 @@ operation:
       # ceiling is enforced there — withdrawing `fast` jobs that complete today,
       # which is the direction the SVG incident ran in. A higher number would
       # under-state what `exact` refuses.
-      # ⚠️ AND NEITHER BOUND IS ENFORCED AT CREATE TODAY: both are worker-side,
+      # ⚠️ AND NEITHER DURATION BOUND IS ENFORCED AT CREATE TODAY (`exact` is
+      # refused at create outright, which is not a duration bound): both are worker-side,
       # after the job is accepted, billed and downloaded. Declaring one would MOVE
       # the refusal earlier, which is a real improvement for the value it fits and
       # a real withdrawal for the value it does not.
@@ -368,78 +389,106 @@ operation:
           type: enum
           values: [fast, exact]
           default: fast
+          per_value_availability:
+            # The API refuses `exact` at create for every split — the deliberate
+            # unpriced re-encode gate (Q8QsYYNn). Advertising it as callable
+            # was a silent rejection of a spec-valid value.
+            exact: { availability: planned }
           # Don't use "keyframe" language here — that's video-only;
           # audio drift is packet-boundary.
-          description: |
-            Cut precision. Under `fast`, audio cuts are
-            packet-boundary approximate (drift bounded by codec
-            packet size — typically <= 23ms for AAC, <= 26ms for
-            MP3). Under `exact`, the server re-encodes to align cuts
-            precisely at the requested timestamps (slower, larger
-            output, but sample-accurate).
-
-            🔴 **THE TWO VALUES HAVE DIFFERENT DURATION LIMITS, AND ONLY
-            ONE OF THEM REFUSES.** This is stated here, on the option a
-            caller chooses, because the group declares
-            `input_size_bound: processing_time` and no
-            `max_input_duration` — there is no per-value constraint
-            primitive to carry it.
-
-            ⛔ **NEITHER VALUE GIVES A PRE-FLIGHT SIGNAL. BOTH FAIL AFTER
-            THE JOB IS ACCEPTED AND BILLED.** No duration ceiling is
-            declared on this group, so the API cannot enforce one at
-            create; the worker's own check reads a probe result, which
-            means the input has already been uploaded, accepted and
-            downloaded.
-
-            - **`exact`: refused when its computed time budget does not
-              fit** — but WORKER-SIDE, after download and probe. The job
-              returns a terminal `OperationResult` with `error_code:
-              invalid_options`. ⚠️ It is NOT an HTTP 422 and it is not a
-              create-time rejection: a worker cannot emit a status code.
-              The boundary does not move with `count` — once the cap
-              binds, the per-output term stops mattering.
-            - **`fast` (the default): no boundary and no refusal at
-              all.** Past the point where its deadline saturates, the time
-              budget stops growing while the work does, so the job fails
-              as a **TIMEOUT** rather than with any reason a caller can
-              act on.
-
-            🔴 **TWO LIMITS EXIST AND THE SMALLER ONE BINDS.** The worker
-            carries an internal time budget and the Lambda function
-            carries a platform timeout; **the effective boundary is the
-            LOWER of the two**, and the internal budget sits ABOVE the
-            platform timeout.
-
-            ⇒ **`exact`'s refusal threshold is calibrated to a limit that
-            is not the one that ends the job.** Its check does fire, and
-            fires early — it reads the probe result before any re-encode
-            starts, so a long-but-small input is refused within seconds.
-            But there is a band of inputs it judges FINE which the
-            platform then hard-kills mid-encode, with no named cause. **So
-            `exact` refusing is a reliable signal; `exact` NOT refusing is
-            not a promise the job will finish.**
-
-            ⛔ **NO SECONDS FIGURE IS GIVEN HERE, DELIBERATELY.** v2.205.0
-            published figures keyed to the crate constant — the larger
-            limit, the one that does not bind. The effective number lands
-            only when that derivation settles AND a job is measured near
-            it. **A published number a caller pre-validates against is
-            worse wrong than absent**; the shape above is what a caller can
-            actually act on today, which is: do not rely on either value
-            failing gracefully.
-
-            ⇒ `exact` at least names a cause when it is reached; `fast`
-            never does. **Both are the accept-then-bill-then-fail shape**,
-            which is the very thing this group's `input_size_bound`
-            declaration exists to stop happening silently on the BYTE
-            axis. On the DURATION axis it is stated here and not yet
-            fixed.
-
-            ⚠️ Read from `compression_lambdas` `crates/split`. **NOT
-            measured** — their audio fixtures reach 145 s, a small
-            fraction of any candidate cap, so this describes what the code
-            will do rather than observed behaviour at the boundary.
+          # AUTHOR NOTES (moved out of the user-facing description, ewOlw35Z,
+          # 2026-09-23 — frontend shows option descriptions to users). Preserved verbatim:
+          #   Cut precision. Under `fast`, audio cuts are
+          #   packet-boundary approximate (drift bounded by codec
+          #   packet size — typically <= 23ms for AAC, <= 26ms for
+          #   MP3). Under `exact`, the server re-encodes to align cuts
+          #   precisely at the requested timestamps (slower, larger
+          #   output, but sample-accurate).
+          #
+          #   🔴 **THE TWO VALUES HAVE DIFFERENT DURATION LIMITS, AND ONLY
+          #   ONE OF THEM REFUSES.** This is stated here, on the option a
+          #   caller chooses, because the group declares
+          #   `input_size_bound: processing_time` and no
+          #   `max_input_duration` — there is no per-value constraint
+          #   primitive to carry it.
+          #
+          #   🔴 **TODAY `exact` IS REFUSED AT CREATE** — the API does not
+          #   yet admit it for any split (the re-encode path is not yet
+          #   priced), so it is tagged `planned` and a request carrying it
+          #   is rejected before anything is uploaded, accepted or billed.
+          #   **Everything below about `exact` describes the worker, i.e.
+          #   what it will do once the API admits it.**
+          #
+          #   `exact` is refused at create with `feature_not_available` (422),
+          #   the contract's answer for a `planned` value (api
+          #   SplitOptionsValidator leaves it to the generic planned-option
+          #   gate; SplitAudioActivationCreateTest asserts the error_type).
+          #   A consumer should not send it, as the `planned` tag says.
+          #
+          #   ⛔ **`fast` GIVES NO PRE-FLIGHT SIGNAL, and neither will
+          #   `exact` once admitted: both fail AFTER THE JOB IS ACCEPTED
+          #   AND BILLED.** No duration ceiling is declared on this group,
+          #   so the API cannot enforce one at create; the worker's own
+          #   check reads a probe result, which means the input has already
+          #   been uploaded, accepted and downloaded.
+          #
+          #   - **`exact` (once admitted): refused when its computed time
+          #     budget does not fit** — but WORKER-SIDE, after download and
+          #     probe. The job
+          #     returns a terminal `OperationResult` with `error_code:
+          #     invalid_options`. ⚠️ It is NOT an HTTP 422 and it is not a
+          #     create-time rejection: a worker cannot emit a status code.
+          #     The boundary does not move with `count` — once the cap
+          #     binds, the per-output term stops mattering.
+          #   - **`fast` (the default): no boundary and no refusal at
+          #     all.** Past the point where its deadline saturates, the time
+          #     budget stops growing while the work does, so the job fails
+          #     as a **TIMEOUT** rather than with any reason a caller can
+          #     act on.
+          #
+          #   🔴 **TWO LIMITS EXIST AND THE SMALLER ONE BINDS.** The worker
+          #   carries an internal time budget and the Lambda function
+          #   carries a platform timeout; **the effective boundary is the
+          #   LOWER of the two**, and the internal budget sits ABOVE the
+          #   platform timeout.
+          #
+          #   ⇒ **`exact`'s refusal threshold is calibrated to a limit that
+          #   is not the one that ends the job.** Its check does fire, and
+          #   fires early — it reads the probe result before any re-encode
+          #   starts, so a long-but-small input is refused within seconds.
+          #   But there is a band of inputs it judges FINE which the
+          #   platform then hard-kills mid-encode, with no named cause. **So
+          #   `exact` refusing is a reliable signal; `exact` NOT refusing is
+          #   not a promise the job will finish.**
+          #
+          #   ⛔ **NO SECONDS FIGURE IS GIVEN HERE, DELIBERATELY.** v2.205.0
+          #   published figures keyed to the crate constant — the larger
+          #   limit, the one that does not bind. The effective number lands
+          #   only when that derivation settles AND a job is measured near
+          #   it. **A published number a caller pre-validates against is
+          #   worse wrong than absent**; the shape above is what a caller can
+          #   actually act on today, which is: do not rely on either value
+          #   failing gracefully.
+          #
+          #   ⇒ `exact` (once admitted) at least names a cause when it is
+          #   reached; `fast` never does. **On today's customer path only
+          #   `fast` is the accept-then-bill-then-fail shape**,
+          #   which is the very thing this group's `input_size_bound`
+          #   declaration exists to stop happening silently on the BYTE
+          #   axis. On the DURATION axis it is stated here and not yet
+          #   fixed.
+          #
+          #   ⚠️ Read from `compression_lambdas` `crates/split`. **NOT
+          #   measured** — their audio fixtures reach 145 s, a small
+          #   fraction of any candidate cap, so this describes what the code
+          #   will do rather than observed behaviour at the boundary.
+          description: >-
+            Cut precision. `fast` (default) cuts at packet boundaries, so each cut
+            can drift by a few milliseconds (typically up to about 23 ms for AAC and
+            26 ms for MP3). `exact` re-encodes to cut precisely at the requested
+            timestamps; it is not yet available and is refused when the workflow is
+            created. Very long audio can run out of processing time and fail rather
+            than be refused up front.
 
     # Video base — same three modes + precision + processing_class.
     # Long-form routes to `split-video-fargate` (same OperationType,
@@ -458,9 +507,12 @@ operation:
             max_input_size_bytes: 524288000
             max_output_size_bytes: 524288000
         long_form:
-          # planned -> beta (rcwvUKhI): split-video-fargate worker deployed +
-          # wired on staging but NOT yet proven end-to-end (first customer-path
-          # soak incomplete; 4GB+ speed-up unmeasured; fan-out flag-gated dark).
+          # planned -> beta (rcwvUKhI). Stays beta until a PRODUCTION
+          # `customer_path` run is recorded in availability/prod-verification-
+          # log.yaml; worker-direct staging runs up to 3.99 GiB are in the
+          # staging log as partial evidence only (no environment axis). Fan-out admission is
+          # the API's LONGFORM_FANOUT_ADMISSION_ENABLED, set per environment in
+          # compression_terraform; not restated here.
           # Routes per ADR-0014 §D10 — same split OperationType, dedicated
           # stream-copy segmenter binary (NOT the long-form compress worker).
           availability: beta
@@ -531,6 +583,10 @@ operation:
           type: enum
           values: [fast, exact]
           default: fast
+          per_value_availability:
+            # Refused at create by the API for every split (Q8QsYYNn) as
+            # `feature_not_available`; see the note on `audio.options.precision`.
+            exact: { availability: planned }
           description: |
             Cut precision. Under `fast`, video cuts are keyframe-
             aligned (drift bounded by GOP size — typically up to 1-2

package/operations/schemas/thumbnail.yaml

@@ -66,14 +66,19 @@ operation:
           max: 100
           default: 85
           depends_on: { format: [jpg, webp, png] }
+          # AUTHOR NOTES (moved out of the user-facing description, ewOlw35Z,
+          # 2026-09-23 — frontend shows option descriptions to users). Preserved verbatim:
+          #   Output quality for lossy thumbnail formats (jpg / webp / png): higher = better
+          #   quality, larger file. For PNG, `quality` < 100 applies lossy palette quantization
+          #   (transparency preserved); `quality: 100` keeps the PNG lossless. Per-format effective
+          #   default (server-resolved when `quality` is unset, per ADR-0020 D1): PNG → 70 (more
+          #   aggressive — thumbnails target small files), jpg/webp → 85. The schema `default` is
+          #   the nominal jpg/webp value (85); the FE shows 70 as the initial PNG slider value.
           description: >-
-            Output quality for lossy thumbnail formats (jpg / webp / png): higher =
-            better quality, larger file. For PNG, `quality` < 100 applies lossy palette
-            quantization (transparency preserved); `quality: 100` keeps the
-            PNG lossless. Per-format effective default (server-resolved when `quality`
-            is unset, per ADR-0020 D1): PNG → 70 (more aggressive — thumbnails target
-            small files), jpg/webp → 85. The schema `default` is the nominal jpg/webp
-            value (85); the FE shows 70 as the initial PNG slider value.
+            Output quality for jpg, webp and png thumbnails: higher = better quality,
+            larger file. For PNG, a value below 100 reduces the colour palette
+            (transparency is kept) and 100 keeps it lossless. When unset, PNG
+            thumbnails use 70 and jpg/webp use 85.
         background:
           type: string
           pattern: "^#[0-9a-fA-F]{6}$"
@@ -457,26 +462,29 @@ operation:
           #                            Cargo.lock via usvg; `quick-xml` is absent.
           # The build's real shape lives in the ticket and in lambdas' crate. This
           # file states the CONTRACT: what is advertised, and what the API gates.
+          # AUTHOR NOTES (moved out of the user-facing description, ewOlw35Z,
+          # 2026-09-23 — frontend shows option descriptions to users). Preserved verbatim:
+          #   `cover` (the only supported value) = extract the EPUB's declared cover image — the
+          #   cheap path, no rendering. Cover lookup supports both mechanisms: the EPUB 3
+          #   `cover-image` property on an OPF manifest item, AND the legacy EPUB 2 `<meta
+          #   name="cover" content="..."/>` pointing at a manifest item — supporting only the former
+          #   would miss a large slice of real-world files. Both are staging-proven (pL16ZfOw Wave
+          #   3). A cover image is OPTIONAL per W3C EPUB 3.3, so a cover-less EPUB is a REAL and
+          #   expected case: it fails with `error_code: processing_failed` and `is_retryable:
+          #   false`. That is the live behaviour, not an aspiration — the worker classifies it as
+          #   `CoverError::NoCoverDeclared` and maps it there (`epub/error.rs`), and
+          #   non-retryability is DERIVED from the code rather than set per-call, so it cannot
+          #   drift. A cover-less EPUB will not grow a cover, so retrying is always futile. A more
+          #   specific code would be better, and is NOT promised here: `ErrorCode` (asyncapi) is a
+          #   CLOSED enum with no "no cover" member, so adding one is a real cross-repo co-land
+          #   (enum edit -> SDK regen -> lockstep). Until then this description states what actually
+          #   happens — an undecided-reject note on a STABLE route would leave consumers unable to
+          #   handle a case they will certainly meet.
           description: >-
-            `cover` (the only supported value) = extract the EPUB's declared cover
-            image — the cheap path, no rendering. Cover lookup supports both
-            mechanisms: the EPUB 3 `cover-image` property on an OPF manifest item,
-            AND the legacy EPUB 2 `<meta name="cover" content="..."/>` pointing at a
-            manifest item — supporting only the former would miss a large slice of
-            real-world files. Both are staging-proven (pL16ZfOw Wave 3).
-            A cover image is OPTIONAL per W3C EPUB 3.3, so a cover-less EPUB is a
-            REAL and expected case: it fails with `error_code: processing_failed`
-            and `is_retryable: false`. That is the live behaviour, not an aspiration
-            — the worker classifies it as `CoverError::NoCoverDeclared` and maps it
-            there (`epub/error.rs`), and non-retryability is DERIVED from the code
-            rather than set per-call, so it cannot drift. A cover-less EPUB will not
-            grow a cover, so retrying is always futile.
-            A more specific code would be better, and is NOT promised here:
-            `ErrorCode` (asyncapi) is a CLOSED enum with no "no cover" member, so
-            adding one is a real cross-repo co-land (enum edit -> SDK regen ->
-            lockstep). Until then this description states what actually happens —
-            an undecided-reject note on a STABLE route would leave consumers unable
-            to handle a case they will certainly meet.
+            `cover` (the only supported value) uses the EPUB's declared cover image;
+            no pages are rendered. Both EPUB 3 and legacy EPUB 2 cover declarations
+            are recognised. An EPUB without a cover cannot produce a thumbnail: the
+            job fails with `processing_failed` and retrying will not help.
         width:
           type: integer
           min: 1