@giveitsmaller/sdk 0.15.0 → 0.17.0

package/dist/file-first.js

@@ -9,10 +9,12 @@
  *
  * Mirrors `packages/php/src/FileFirst/*`.
  */
-import { GislConfigError, GislNetworkError, GislNoSuchKeyError, GislSinkError, GislTimeoutError, SseEndedWithoutTerminal } from './errors.js';
+import { GislConfigError, GislItemFailedError, GislNetworkError, GislNoSuchKeyError, GislSinkError, GislTimeoutError, SseEndedWithoutTerminal } from './errors.js';
 import { _detectCompressMedia, _detectAudioLossless, _consumeSseToTerminal, _pollToTerminal, _parseMaxWait, _checkAborted, _cappedProbeTimeoutMs, } from './builder.js';
 import { LazyHttpDownloader } from './lazy-downloader.js';
 import { resolveCompressOptions, } from './ergonomic/preset_resolver.js';
+import { validateVerbOptions, assertThumbnailDimensions } from './ergonomic/option_validation.js';
+import { resolveOutputRoute, tokenForMime, tokenForPath, isPlannedValue, FACADE_MANAGED_OUTPUTS, } from './ergonomic/image_output_routes.js';
 import { OptimizeFor } from './generated/sdk_spec/enums.js';
 import { uploadSource, jobOutputSource } from './types.js';
 // Value import used only at call-time (inside MergedRecipe.toWorkflowPayload),
@@ -150,10 +152,16 @@ export class RunResult {
         const rest = {
             artifacts: this.artifacts.map(file),
             succeeded: this.succeeded.map((i) => ({ key: i.key, outputs: i.outputs.map(file) })),
-            failed: this.failed.map((f) => ({
-                key: f.key,
-                error: f.error instanceof Error ? f.error.message : String(f.error),
-            })),
+            // Field order (key, error, state, errorMessage?, errorCode?) is fixed to
+            // match the PHP ItemFailure::toArray() so JSON-string parity holds; the two
+            // optional keys are OMITTED when absent (cancel/expire carry only state),
+            // mirroring PHP's omit-when-null (NOT emitted as `undefined`/`null`).
+            failed: this.failed.map((f) => {
+                const e = f.error;
+                const base = { key: f.key, error: e.message, state: e.state };
+                const withMsg = e.errorMessage === undefined ? base : { ...base, errorMessage: e.errorMessage };
+                return e.errorCode === undefined ? withMsg : { ...withMsg, errorCode: e.errorCode };
+            }),
         };
         const head = { workflowId: this.workflowId, state: this.state, ok: this.ok };
         // Insert `url` BETWEEN ok and artifacts when present, matching the PHP
@@ -173,22 +181,15 @@ export class RunResult {
     }
 }
 /**
- * Flatten the terminal workflow status + its downloads into a {@link RunResult}.
- *
- * Shared by {@link Recipe.run} (passes its recipe key) and the file-first
- * {@link Handle} reattach surface (`Handle.wait()`/`Handle.result()`, FF5a —
- * passes `null` because a reattached handle carries no recipe key).
- *
- * **Partition invariant (carries a prior codex-review fix — do NOT let it
- * drift):** success is ONLY `state === 'completed'`. Every other terminal
- * state — `failed`, `partially_failed`, `cancelled`, `expired`,
- * `paused_insufficient_credits` — partitions into `failed[]` so a caller's
- * `ok`/`succeeded` check can never treat a cancelled/expired/paused run as a
- * clean result.
- *
- * @internal Exported for reuse by the file-first `Handle`; not part of the
- *   caller-facing fluent surface.
+ * Extract the human + machine error from the FIRST failing operation in `ops`
+ * (the first op carrying an `errorMessage` OR `errorCode`), reading BOTH from the
+ * SAME op so a code from one op can't pair with a message from another. Both are
+ * absent for terminal states with no failing op (cancel/expire/credit-pause).
  */
+function firstOpError(ops) {
+    const op = ops.find((o) => o.errorMessage !== undefined || o.errorCode !== undefined);
+    return { errorMessage: op?.errorMessage, errorCode: op?.errorCode };
+}
 export function projectDownloadsToRunResult(workflowId, finalStatus, jobDownloads, key, downloader) {
     // Flatten to the lean OutputFile[] (the four file-first fields only).
     const artifacts = [];
@@ -210,14 +211,10 @@ export function projectDownloadsToRunResult(workflowId, finalStatus, jobDownload
         failed = [];
     }
     else {
-        const firstError = (finalStatus.jobs ?? [])
-            .flatMap((j) => j.operations ?? [])
-            .map((op) => op.errorMessage)
-            .find((m) => m !== undefined);
+        // First failing op across ALL jobs (downloads path is whole-workflow scoped).
+        const { errorMessage, errorCode } = firstOpError((finalStatus.jobs ?? []).flatMap((j) => j.operations ?? []));
         succeeded = [];
-        failed = [
-            { key, error: new Error(firstError !== undefined ? `${state}: ${firstError}` : state) },
-        ];
+        failed = [{ key, error: new GislItemFailedError(key, state, errorMessage, errorCode) }];
     }
     return new RunResult(workflowId, state, artifacts, succeeded, failed, downloader);
 }
@@ -269,12 +266,11 @@ export function projectMultiJobToRunResult(workflowId, finalStatus, jobDownloads
             succeeded.push({ key, outputs });
         }
         else {
-            const firstError = (job.operations ?? [])
-                .map((op) => op.errorMessage)
-                .find((m) => m !== undefined);
+            // Per-job scoped: read the error from THIS job's ops only.
+            const { errorMessage, errorCode } = firstOpError(job.operations ?? []);
             failed.push({
                 key,
-                error: new Error(firstError !== undefined ? `${job.status}: ${firstError}` : String(job.status)),
+                error: new GislItemFailedError(key, String(job.status), errorMessage, errorCode),
             });
         }
     }
@@ -356,6 +352,33 @@ export function isArchiveStatus(finalStatus) {
     }
     return hasArchive;
 }
+/**
+ * True when a terminal status describes a fluent `file(...).watermark(overlay)`
+ * — at least one job ref `watermark` and every OTHER job ref is `src_{i}` (the
+ * ids the {@link WatermarkedRecipe} lowering assigns: `src_0` base, `src_1`
+ * overlay). Lets {@link Handle.wait}/{@link Handle.result} AND
+ * {@link WatermarkedRecipe.run} project ONLY the watermark output — filtering
+ * the `src_*` passthrough plumbing — even after a `client.workflow(id)` reattach.
+ * Mutually exclusive with {@link isFanoutStatus} / {@link isMergeStatus} /
+ * {@link isArchiveStatus}.
+ *
+ * @internal Exported for the file-first `Handle`; not part of the public API.
+ */
+export function isWatermarkStatus(finalStatus) {
+    const jobs = finalStatus.jobs ?? [];
+    if (jobs.length === 0)
+        return false;
+    let hasWatermark = false;
+    for (const job of jobs) {
+        if (job.ref === 'watermark') {
+            hasWatermark = true;
+            continue;
+        }
+        if (!_MERGE_SRC_REF.test(job.ref))
+            return false;
+    }
+    return hasWatermark;
+}
 /** Named constructors for {@link FileInput} — mirror the PHP static factories. */
 export const fileInput = {
     path(path) {
@@ -441,21 +464,23 @@ export class Recipe {
      * additional per-op convert options.
      */
     convert(format, options = {}) {
+        // Eager pre-upload key validation (rejects unknown keys + a user-supplied
+        // output_format/format, which this verb owns via the `format` argument).
+        validateVerbOptions('convert', options);
         // The convert op's wire key is `output_format` (contract: convert.yaml,
-        // required, all media), NOT `format`. Spread options FIRST so the explicit
-        // shorthand wins over an `output_format` key in the bag.
-        // The shorthand owns the format → a stray legacy `format` key in the bag is
-        // not a valid convert option; drop it so the wire never carries both keys.
-        const rest = { ...options };
-        delete rest.format;
-        return this.withStep({ opType: 'convert', options: { ...rest, output_format: format } });
+        // required, all media), NOT `format`. Validation above guarantees the bag
+        // carries neither `format` nor `output_format`, so no drop is needed.
+        return this.withStep({ opType: 'convert', options: { ...options, output_format: format } });
     }
     /**
-     * Generate a preview. Width and/or height in pixels; any additional per-op
-     * thumbnail options pass through. An omitted (`undefined`) value is dropped
-     * from the wire options (not sent as `undefined`).
+     * Generate a preview / resize. `width` AND `height` are required (the contract
+     * marks both required for image/video/document); any additional per-op
+     * thumbnail option passes through. An omitted (`undefined`) optional value is
+     * dropped from the wire options (not sent as `undefined`).
      */
-    thumbnail(options = {}) {
+    thumbnail(options) {
+        validateVerbOptions('thumbnail', options);
+        assertThumbnailDimensions(options);
         const wire = {};
         for (const [key, value] of Object.entries(options)) {
             if (value !== undefined)
@@ -463,15 +488,91 @@ export class Recipe {
         }
         return this.withStep({ opType: 'thumbnail', options: wire });
     }
+    /**
+     * Produce ONE transformed image: keep or change format, plus quality, resize
+     * and route-honored controls. The single user-facing image transform — the SDK
+     * resolves the route from `(input format, output_format)` against the contract's
+     * image-output-routes projection and lowers to that route's wire op:
+     * same-format → `compress` (optimiser, `output_format: 'original'`), format-change
+     * → `convert` (transcoder, `output_format: <fmt>`). Only options the resolved
+     * route honors are sent; a planned or not-honored option throws BEFORE upload.
+     * Resize (`width`/`height`/`fit`, via `options` or {@link resize}) stays on the
+     * SAME op — one output, never a separate thumbnail.
+     *
+     * `format` omitted → keep the input format (same-format optimiser route).
+     */
+    output(format, options = {}) {
+        // Eager pre-upload key validation (coarse: rejects keys no image route honors,
+        // + a bag-supplied output_format/format which the positional `format` owns).
+        validateVerbOptions('output', options);
+        const wire = {};
+        for (const [key, value] of Object.entries(options)) {
+            if (value !== undefined)
+                wire[key] = value;
+        }
+        // Store the REQUESTED format token under `output_format`; lowerOutputStep
+        // resolves the route and rewrites it to the wire value ('original' for
+        // same-format). Omitted format → no output_format key → same-format route.
+        if (format !== undefined)
+            wire.output_format = format;
+        return this.withStep({ opType: 'output', options: wire });
+    }
+    /**
+     * Resize as part of the Output transform. Merges `width`/`height`/`fit` into the
+     * PRECEDING `output()` step (one artifact); if no Output step precedes, appends a
+     * same-format Output step carrying the resize. Never emits a `thumbnail` op.
+     * `height` is optional — width-only resize preserves aspect ratio. Resize is
+     * raster-only (e.g. an SVG input has no resize on its route → throws at lower).
+     */
+    resize(width, height, fit) {
+        const resizeOptions = { width };
+        if (height !== undefined)
+            resizeOptions.height = height;
+        if (fit !== undefined)
+            resizeOptions.fit = fit;
+        const steps = [...this.steps];
+        const last = steps[steps.length - 1];
+        if (last !== undefined && last.opType === 'output') {
+            steps[steps.length - 1] = { opType: 'output', options: { ...last.options, ...resizeOptions } };
+            return new Recipe(this.input, this.recipeKey, steps, this.presetDefaults, this.scopedPresetDefaults, this.client);
+        }
+        return this.withStep({ opType: 'output', options: resizeOptions });
+    }
     /**
      * Apply a text watermark. Single-input (the text is an option, not a
      * secondary file) — lowers to the `text_watermark` op with a `text` option;
      * `options` carries any additional per-op watermark options.
      */
     textWatermark(text, options = {}) {
-        // Spread options FIRST so the explicit `text` argument is authoritative.
+        // Eager pre-upload validation (rejects unknown keys + a user-supplied `text`,
+        // which this verb owns via the first argument).
+        validateVerbOptions('textWatermark', options);
         return this.withStep({ opType: 'text_watermark', options: { ...options, text } });
     }
+    /**
+     * Composite an image OVERLAY onto this file (a multi-input op). `overlay` is a
+     * secondary file-NODE (a {@link Recipe} — e.g. `client.file('logo.png')`),
+     * itself optionally processed first. Routes by THIS file's effective media:
+     * image base → `image_watermark` (stable), video base → `video_watermark`
+     * (beta). Audio/document/animated-GIF/unsupported-subtype/undetectable bases
+     * throw locally BEFORE any upload (the planned-op gate). `options` carries the
+     * wire watermark options (`anchor`, `opacity`, `margin_x`, `margin_y`,
+     * `overlay_width`). Returns a {@link WatermarkedRecipe} (chain post-watermark
+     * `compress`/`convert`/`thumbnail`, then `run`/`submit`). Distinct from
+     * {@link textWatermark} (single-input text overlay).
+     */
+    watermark(overlay, options = {}) {
+        // Eager pre-upload key validation (against image_watermark ∪ video_watermark,
+        // since the base media may be undetectable here; routing is gated separately).
+        validateVerbOptions('watermark', options);
+        // Eager gate when the base media is KNOWN (unit-testable pre-upload); an
+        // undetectable base is DEFERRED — re-checked pre-upload in run()/submit().
+        const base = _watermarkEffectiveBase(this.input, this.steps);
+        if (base.media !== undefined)
+            _resolveWatermarkWireOp(base);
+        _validateWatermarkOverlay(overlay);
+        return new WatermarkedRecipe(this.input, this.steps, overlay, options, [], this.presetDefaults, this.scopedPresetDefaults, this.client);
+    }
     /**
      * Lower this recipe to a workflow-create payload against a resolved upload
      * id. Single-input chain → ONE job, `source: upload(fileId)`, ordered
@@ -487,7 +588,7 @@ export class Recipe {
      *   fixed id). Not part of the caller-facing fluent surface.
      */
     toWorkflowPayload(fileId, callbackUrl) {
-        const operations = this.steps.map((step) => this.lowerStep(step));
+        const operations = this.steps.map((step, i) => this.lowerStep(step, i));
         // Key order (source, operations) matches the PHP `toWire()` so the
         // JSON-string serialisation is byte-identical across languages.
         const job = { source: uploadSource(fileId), operations };
@@ -509,6 +610,15 @@ export class Recipe {
     get recipeSteps() {
         return this.steps;
     }
+    /**
+     * The primary input this recipe operates on. Read by {@link WatermarkedRecipe}
+     * to lift an overlay Recipe's input (for upload + media inference + src-job
+     * lowering) without making the ctor field public.
+     * @internal
+     */
+    get recipeInput() {
+        return this.input;
+    }
     /**
      * Execute the recipe end-to-end: upload the input (when required), create
      * the workflow, await a terminal state (SSE with poll fallback), then
@@ -684,15 +794,119 @@ export class Recipe {
     withStep(step) {
         return new Recipe(this.input, this.recipeKey, [...this.steps, step], this.presetDefaults, this.scopedPresetDefaults, this.client);
     }
-    lowerStep(step) {
-        const options = step.opType === 'compress' ? this.lowerCompressOptions(step.options) : { ...step.options };
+    lowerStep(step, stepIndex) {
+        // The internal `output` step lowers to a `compress`/`convert` wire op per the
+        // route projection (it owns its own type + options resolution + gating).
+        if (step.opType === 'output')
+            return this.lowerOutputStep(step, stepIndex);
+        // After the early return, `step.opType` narrows to the wire op kinds.
+        const options = step.opType === 'compress'
+            ? this.lowerCompressOptions(step.options, stepIndex)
+            : { ...step.options };
         // Empty options omit the `options` wire key entirely, so TS (undefined →
         // absent) and PHP (null → absent) serialise byte-identically.
         return Object.keys(options).length === 0
             ? { type: step.opType }
             : { type: step.opType, options };
     }
-    lowerCompressOptions(stepOptions) {
+    /**
+     * Lower an `output` step to its route's wire op. Resolves the route from the
+     * (chain-folded) input format token + the requested `output_format`, then emits
+     * `compress` (same_format) or `convert` (format_change) carrying only the
+     * route-honored options. A planned option (e.g. `lossless`), an option not
+     * honored on the resolved route (e.g. `progressive` on a format-change), a
+     * planned per-value (e.g. `metadata: 'keep'`), or an unrepresentable route all
+     * throw a typed {@link GislConfigError} BEFORE upload. Resize (`width`/`height`/
+     * `fit`) is input-keyed (raster only) and rides whichever op the route selects.
+     */
+    lowerOutputStep(step, stepIndex) {
+        const requested = typeof step.options.output_format === 'string' ? step.options.output_format : undefined;
+        const inputToken = this.outputInputToken(stepIndex);
+        if (inputToken === undefined) {
+            // Undetectable input (bare upload id / unnamed blob) → the route can't be
+            // resolved. Only the legacy compress facade for a facade-managed output
+            // (webp) + quality is expressible without knowing the input; anything else
+            // (resize, a same-format optimise, a non-facade target) needs a detectable
+            // input. Mirrors lowerCompressOptions' media_unknown fail-fast.
+            if (requested !== undefined && FACADE_MANAGED_OUTPUTS.includes(requested)) {
+                const facade = { output_format: requested };
+                for (const [key, value] of Object.entries(step.options)) {
+                    if (key === 'output_format' || value === undefined)
+                        continue;
+                    if (key !== 'quality') {
+                        throw new GislConfigError(`output(): '${key}' needs a detectable input format to route; reference the file by ` +
+                            'a path with an extension (or a named/typed Blob) rather than a bare upload id.', { reason: 'media_unknown', conflictingFields: [key] });
+                    }
+                    facade[key] = value;
+                }
+                return { type: 'compress', options: facade };
+            }
+            throw new GislConfigError('output() needs a detectable input format to resolve the route (same-format optimise vs ' +
+                'format-change transcode); reference the file by a path with an extension, or a Blob with ' +
+                'a media type / filename, rather than a bare upload id.', { reason: 'media_unknown', conflictingFields: ['output_format'] });
+        }
+        const resolved = resolveOutputRoute(inputToken, requested);
+        if (resolved === undefined) {
+            throw new GislConfigError(`output(): cannot produce ${requested === undefined ? 'this output' : `'${requested}'`} ` +
+                `from a '${inputToken}' input — no such image Output route.`, { reason: 'unsupported_route', conflictingFields: ['output_format'] });
+        }
+        const wireOptions = { output_format: resolved.outputFormatWire };
+        for (const [key, value] of Object.entries(step.options)) {
+            if (key === 'output_format' || value === undefined)
+                continue;
+            if (resolved.planned.has(key)) {
+                throw new GislConfigError(`output(): '${key}' is advertised but not available yet on the ${resolved.route} route ` +
+                    `for '${resolved.inputToken}' images (planned). It will work once stable-flipped.`, { reason: 'feature_not_available', conflictingFields: [key] });
+            }
+            if (!resolved.honored.has(key)) {
+                throw new GislConfigError(`output(): '${key}' is not honored on the ${resolved.route} route ` +
+                    `(${resolved.inputToken} → ${requested ?? resolved.inputToken}). ` +
+                    'Check it applies to this format/route combination.', { reason: 'option_not_on_route', conflictingFields: [key] });
+            }
+            if (isPlannedValue(resolved.inputToken, key, value)) {
+                throw new GislConfigError(`output(): '${key}: ${String(value)}' is advertised but not available yet (planned).`, { reason: 'feature_not_available', conflictingFields: [key] });
+            }
+            wireOptions[key] = value;
+        }
+        return { type: resolved.sourceOp, options: wireOptions };
+    }
+    /**
+     * The input format token an `output` step at `uptoIndex` operates on — the
+     * original input's token, FOLDED through preceding `convert`/`output` steps that
+     * change the format (mirrors {@link compressMediaHint}). Undefined when the input
+     * media is not inferable (a bare upload id / unnamed, untyped Blob).
+     */
+    outputInputToken(uptoIndex) {
+        let token = this.inputFormatToken();
+        if (uptoIndex === undefined)
+            return token;
+        for (let i = 0; i < uptoIndex; i++) {
+            const prior = this.steps[i];
+            if (prior.opType === 'convert' || prior.opType === 'output') {
+                const fmt = prior.options.output_format;
+                // A same-format `output` step carries no output_format (or 'original') →
+                // token unchanged; a format target (e.g. 'webp') advances it.
+                if (typeof fmt === 'string')
+                    token = tokenForPath(`f.${fmt}`) ?? token;
+            }
+        }
+        return token;
+    }
+    /** The original input's image format token (path ext / Blob type / Blob name). */
+    inputFormatToken() {
+        if (this.input.kind === 'path')
+            return tokenForPath(this.input.path);
+        if (this.input.kind === 'blob') {
+            const blob = this.input.blob;
+            const fromType = blob.type ? tokenForMime(blob.type) : undefined;
+            if (fromType !== undefined)
+                return fromType;
+            const name = blob.name;
+            return name !== undefined ? tokenForPath(name) : undefined;
+        }
+        return undefined; // uploadId — undetectable
+    }
+    lowerCompressOptions(stepOptions, uptoIndex) {
         // Mirror the op-first resolver precedence (OperationBuilder._resolve in
         // builder.ts): optimize = preset layer, presetOverrides = callPresetOverride
         // layer, the rest = explicit layer.
@@ -716,7 +930,7 @@ export class Recipe {
                     : typeof presetOverrides;
             throw new GislConfigError(`compress 'presetOverrides' must be a *CompressPresetOptions object; got ${got}.`, { reason: 'invalid_preset_overrides', conflictingFields: ['presetOverrides'] });
         }
-        const media = this.compressMediaHint();
+        const media = this.compressMediaHint(uptoIndex);
         if (media === undefined) {
             // Cannot infer a media class (a Blob without a recognised name, or a
             // bare upload id) → preset resolution is impossible. Fail FAST rather
@@ -739,7 +953,7 @@ export class Recipe {
         }
         const input = { media, op: 'compress', explicitOptions };
         if (media === 'audio') {
-            input.audioLossless = this.compressAudioLossless();
+            input.audioLossless = this.compressAudioLossless(uptoIndex);
         }
         if (this.presetDefaults !== undefined) {
             input.presetDefaults = this.presetDefaults;
@@ -758,16 +972,52 @@ export class Recipe {
         }
         return { ...resolveCompressOptions(input).wireOptions };
     }
-    compressMediaHint() {
-        if (this.input.kind === 'path') {
+    /** Media of the original input (no chain context) — used by the probe gate. */
+    inputMedia() {
+        if (this.input.kind === 'path')
             return _detectCompressMedia(this.input.path);
-        }
-        if (this.input.kind === 'blob') {
+        if (this.input.kind === 'blob')
             return _detectCompressMedia(this.input.blob);
-        }
         return undefined;
     }
-    compressAudioLossless() {
+    /**
+     * The media class a `compress` step at `uptoIndex` actually operates on. With no
+     * chain context (`uptoIndex` undefined) this is the original input's media. With
+     * context, FOLD the preceding `convert` steps: each `convert(output_format)` changes
+     * the media the next step sees (56N4chXY / N8eESzQN — a chain like
+     * `mp3 -> convert(flac) -> compress` must resolve against flac, not mp3). Reuses the
+     * synthetic-filename detection precedent from {@link MergedRecipe} (`merged.<ext>`).
+     */
+    compressMediaHint(uptoIndex) {
+        let media = this.inputMedia();
+        if (uptoIndex === undefined)
+            return media;
+        for (let i = 0; i < uptoIndex; i++) {
+            const step = this.steps[i];
+            if (step.opType === 'convert') {
+                const fmt = step.options.output_format;
+                if (typeof fmt === 'string')
+                    media = _resolveConvertOutputMedia(media, fmt);
+            }
+        }
+        return media;
+    }
+    /**
+     * Whether the media a `compress` step at `uptoIndex` operates on is lossless audio.
+     * Determined by the most recent preceding `convert` target (`flac`/`wav` -> lossless)
+     * when there is one, else by the original input. Lossless is unaffected by the
+     * video/ogg guard (ogg is never lossless either way).
+     */
+    compressAudioLossless(uptoIndex) {
+        if (uptoIndex !== undefined) {
+            for (let i = uptoIndex - 1; i >= 0; i--) {
+                const step = this.steps[i];
+                if (step.opType === 'convert') {
+                    const fmt = step.options.output_format;
+                    return typeof fmt === 'string' ? _detectAudioLossless(`f.${fmt}`) : false;
+                }
+            }
+        }
         if (this.input.kind === 'path')
             return _detectAudioLossless(this.input.path);
         if (this.input.kind === 'blob')
@@ -775,6 +1025,252 @@ export class Recipe {
         return false;
     }
 }
+/**
+ * Media of a `convert` step's output, given the media of its source. Reuses the
+ * extension classifier on a synthetic `f.<format>`, with ONE guard: a video source
+ * converted to `ogg` stays video (an OGG *video* container — `ogg` otherwise lands in
+ * the audio extension list, which would mis-resolve a video output to audio). A video
+ * source to `gif` is left as the classifier's `image` result (animated-GIF compress is
+ * image-class). Per the 56N4chXY plan review (architect + karen).
+ */
+function _resolveConvertOutputMedia(source, outputFormat) {
+    if (source === 'video' && outputFormat.toLowerCase() === 'ogg')
+        return 'video';
+    return _detectCompressMedia(`f.${outputFormat}`);
+}
+// ── Watermark routing + planned-op gating (FF4a) ────────────────────────────
+/**
+ * The single SDK-side source of truth for which `(wire op, base mime)`
+ * combinations the file-first `watermark()` verb may emit, and their
+ * availability. The generated typed metadata sidecar does NOT carry the
+ * supported-mime allowlist (`MimeGroupMetadata` has no `mimes` field and
+ * `per_mime_availability` is empty for these ops), so this hand table is the
+ * gate's source — PINNED to the generated `availability.json` by a conformance
+ * test (mirrors the wire-key-conformance pattern): a contract regen that
+ * changes the supported mimes or availability of `image_watermark` /
+ * `video_watermark` fails that test. The gate reads ONLY this table.
+ * @internal
+ */
+export const WATERMARK_CAPABILITY = {
+    image_watermark: {
+        image: { mimes: ['image/jpeg', 'image/png', 'image/webp'], availability: 'stable' },
+        image_gif: { mimes: ['image/gif'], availability: 'planned' },
+    },
+    video_watermark: {
+        video: { mimes: ['video/mp4', 'video/webm'], availability: 'beta' },
+    },
+};
+const _WATERMARK_SHIPPABLE = new Set(['stable', 'beta']);
+// extension → canonical MIME for the watermark gate. Covers the supported
+// formats PLUS common known-but-unsupported ones so the gate throws an
+// actionable "unsupported subtype" rather than silently routing a format the
+// server will reject.
+const _WATERMARK_EXT_MIME = {
+    jpg: 'image/jpeg', jpeg: 'image/jpeg', png: 'image/png', webp: 'image/webp', gif: 'image/gif',
+    avif: 'image/avif', heic: 'image/heic', heif: 'image/heif', tiff: 'image/tiff', tif: 'image/tiff', bmp: 'image/bmp',
+    mp4: 'video/mp4', webm: 'video/webm', mov: 'video/quicktime', mkv: 'video/x-matroska',
+    avi: 'video/x-msvideo', wmv: 'video/x-ms-wmv', flv: 'video/x-flv', m4v: 'video/x-m4v',
+};
+function _watermarkPathMime(path) {
+    const ext = path.toLowerCase().split('.').pop();
+    return ext !== undefined ? _WATERMARK_EXT_MIME[ext] : undefined;
+}
+/**
+ * The watermark MIME of a base/overlay Blob. Mirrors `_detectCompressMedia`'s
+ * mime-first-else-filename precedence: a declared `Blob.type` is used ONLY when
+ * it is media-bearing (image/ video/ audio/ — params stripped, lowercased); a
+ * generic/unknown type (e.g. `application/octet-stream`) falls back to the
+ * `File.name` extension, so a filename-hinted in-memory base routes like a path.
+ */
+function _watermarkBlobMime(blob) {
+    const raw = blob.type ? blob.type.split(';')[0].trim().toLowerCase() : '';
+    if (raw.startsWith('image/') || raw.startsWith('video/') || raw.startsWith('audio/')) {
+        return raw;
+    }
+    return _watermarkPathMime(blob.name ?? '');
+}
+/**
+ * Resolve the effective `(media, mime)` a watermark op operates on, folding the
+ * preceding `convert` (output media + format) AND `thumbnail` (always an image
+ * output) steps — mirrors {@link Recipe.compressMediaHint}'s convert fold, plus
+ * the thumbnail→image rule (codex review). Reused for the base and the overlay.
+ */
+function _watermarkEffectiveBase(input, steps) {
+    let media = input.kind === 'path'
+        ? _detectCompressMedia(input.path)
+        : input.kind === 'blob'
+            ? _detectCompressMedia(input.blob)
+            : undefined;
+    let mime = input.kind === 'path'
+        ? _watermarkPathMime(input.path)
+        : input.kind === 'blob'
+            ? _watermarkBlobMime(input.blob)
+            : undefined;
+    for (const step of steps) {
+        if (step.opType === 'convert') {
+            const fmt = step.options.output_format;
+            if (typeof fmt === 'string') {
+                media = _resolveConvertOutputMedia(media, fmt);
+                mime = _WATERMARK_EXT_MIME[fmt.toLowerCase()];
+            }
+        }
+        else if (step.opType === 'thumbnail') {
+            // A thumbnail of a video/PDF/image is always an image output.
+            media = 'image';
+            mime = 'image/png';
+        }
+    }
+    // Recover the coarse media from a usable (already-normalised) mime when the
+    // case-sensitive media classifier could not (e.g. an oddly-cased `Image/PNG`
+    // content-type) — keeps the gate self-consistent: a usable mime implies media.
+    if (media === undefined && mime !== undefined) {
+        if (mime.startsWith('image/'))
+            media = 'image';
+        else if (mime.startsWith('video/'))
+            media = 'video';
+        else if (mime.startsWith('audio/'))
+            media = 'audio';
+    }
+    return { media, mime };
+}
+/**
+ * Resolve the wire op (`image_watermark` / `video_watermark`) for a watermark
+ * base, or THROW {@link GislConfigError} pre-upload — the planned-op gate. The
+ * capability is read from {@link WATERMARK_CAPABILITY} (data-driven, contract-
+ * pinned): a base mime in a `{stable,beta}` group routes; a `planned` group
+ * (animated GIF base) throws; a known image/video subtype outside the allowlist
+ * (AVIF/HEIC/MOV/…) throws "unsupported"; audio/document throw "not supported".
+ * An undetectable base media throws an actionable error (the caller defers the
+ * eager check at `.watermark()` time and re-runs this pre-upload).
+ */
+function _resolveWatermarkWireOp(base) {
+    const { media, mime } = base;
+    if (media === undefined) {
+        throw new GislConfigError("watermark needs a detectable base media to route to image_watermark / video_watermark, " +
+            'but the input has no inferable type (a pre-uploaded file id or unnamed/typeless Blob carries ' +
+            'no extension or MIME). Use a path with a file extension, a Blob with a type, or a named resource.', { reason: 'media_unknown' });
+    }
+    if (mime !== undefined) {
+        for (const wireOp of Object.keys(WATERMARK_CAPABILITY)) {
+            const groups = WATERMARK_CAPABILITY[wireOp];
+            for (const group of Object.values(groups)) {
+                if (group.mimes.includes(mime)) {
+                    if (_WATERMARK_SHIPPABLE.has(group.availability))
+                        return wireOp;
+                    throw new GislConfigError(`watermark for ${mime} bases is not yet available (${wireOp} is '${group.availability}'). ` +
+                        'The contract schema is defined but the server returns feature_not_available until it ships.', { reason: 'feature_not_available' });
+                }
+            }
+        }
+    }
+    if (media === 'image' || media === 'video') {
+        throw new GislConfigError(`watermark does not support ${mime ?? media} base files. image_watermark accepts ` +
+            'image/jpeg, image/png, image/webp; video_watermark accepts video/mp4, video/webm. ' +
+            'Convert the base to a supported format first.', { reason: 'unsupported_media' });
+    }
+    throw new GislConfigError(`watermark does not support ${media} base files — overlay watermarking targets image or video bases ` +
+        '(audio overlay and luma matte are planned operations). Use textWatermark() for document/text watermarks.', { reason: 'unsupported_media' });
+}
+/**
+ * Validate a watermark overlay locally: the overlay role is always an IMAGE.
+ * A KNOWN non-image overlay (audio/video/document) throws pre-upload; an
+ * undetectable overlay media is ALLOWED (it doesn't affect routing, so the
+ * server enforces it). The overlay's effective media folds its own steps.
+ */
+function _validateWatermarkOverlay(overlay) {
+    const { media } = _watermarkEffectiveBase(overlay.recipeInput, overlay.recipeSteps);
+    if (media !== undefined && media !== 'image') {
+        throw new GislConfigError(`watermark overlay must be an image; got a ${media} overlay. The overlay is the watermark image ` +
+            'composited onto the base — pass an image file (or a recipe whose output is an image).', { reason: 'invalid_overlay_media', conflictingFields: ['overlay'] });
+    }
+}
+function _lowerWatermarkOp(wireOp, options) {
+    // Watermark options (anchor/opacity/margin_x/margin_y/overlay_width) are
+    // already wire keys; empty options omit the `options` key (byte-identical to PHP).
+    const wire = { ...options };
+    return Object.keys(wire).length === 0 ? { type: wireOp } : { type: wireOp, options: wire };
+}
+/**
+ * Shared multi-input upload-then-create tail for the multi-input recipes
+ * ({@link FilesRecipe}, {@link MergedRecipe}, {@link ArchivedRecipe},
+ * {@link WatermarkedRecipe}). Uploads each fresh input (passing through upload
+ * progress), tracks the multipart-video uploads for the best-effort
+ * probe-before-create, then builds the payload via `toPayload` and creates the
+ * workflow. Abort + deadline are re-checked between every phase, exactly as the
+ * per-recipe copies did before this was extracted (xxy5Rlsy).
+ *
+ * Recipe-specific behaviour stays with the caller: `validatePreUpload()` runs
+ * BEFORE this call (Merged/Archived/Watermarked), and the input source
+ * (`this.inputs` vs `this.inputsInOrder()`) plus the timeout-message nouns
+ * (`uploadsLabel`/`workflowLabel`) are passed in so the thrown messages are
+ * byte-identical to the originals.
+ */
+async function _uploadInputsAndCreate(client, inputs, toPayload, opts) {
+    const { webhook, deadline, onProgress, signal, probeBeforeCreate, probeTimeoutMs, uploadsLabel, workflowLabel } = opts;
+    const fileIds = [];
+    // Track each freshly-uploaded input's probe-gate inputs (a pre-uploaded id
+    // carries no local mime/size, so it is excluded — never probed).
+    const probeTargets = [];
+    for (const input of inputs) {
+        // Fail fast between uploads — a deadline that elapses mid-batch should not
+        // force every remaining input to upload before throwing.
+        _checkAborted(signal);
+        if (deadline !== undefined && Date.now() >= deadline) {
+            throw new GislTimeoutError(`maxWait elapsed during ${uploadsLabel} uploads before all inputs were uploaded`);
+        }
+        if (input.kind === 'uploadId') {
+            fileIds.push(input.fileId);
+        }
+        else {
+            const source = input.kind === 'path' ? input.path : input.blob;
+            const up = await client.uploadFile(source, {
+                signal,
+                ...(onProgress !== undefined
+                    ? {
+                        onProgress: (uploadedBytes, totalBytes) => {
+                            onProgress({ phase: 'upload', uploadedBytes, totalBytes });
+                        },
+                    }
+                    : {}),
+            });
+            fileIds.push(up.fileId);
+            probeTargets.push({
+                fileId: up.fileId,
+                isVideo: _detectCompressMedia(source) === 'video',
+                sizeBytes: up.sizeBytes,
+            });
+        }
+    }
+    _checkAborted(signal);
+    if (deadline !== undefined && Date.now() >= deadline) {
+        throw new GislTimeoutError(`Uploads completed but maxWait elapsed before ${workflowLabel} could be created`);
+    }
+    // Best-effort probe-before-create for the multipart-video inputs. Run the
+    // waits CONCURRENTLY (Promise.all): each is bounded by the SAME capped
+    // timeout, so the aggregate wall-clock stays ~timeout rather than N×timeout.
+    // The cap is the remaining maxWait budget so the waits cannot push
+    // createWorkflow past the caller's deadline. Never-bounce, so a give-up just
+    // proceeds.
+    const cappedProbeTimeoutMs = _cappedProbeTimeoutMs(probeTimeoutMs, deadline);
+    await Promise.all(probeTargets.map((t) => client.maybeWaitForVideoProbe(t.fileId, {
+        enabled: probeBeforeCreate ?? true,
+        isVideo: t.isVideo,
+        sizeBytes: t.sizeBytes,
+        timeoutMs: cappedProbeTimeoutMs,
+        signal,
+    })));
+    // A cancel arriving during a FINAL successful probe request must not still
+    // create the workflow (the probe waits return landed without a final abort
+    // re-check), so check here BEFORE createWorkflow.
+    _checkAborted(signal);
+    // RE-CHECK the deadline AFTER the probe waits (they consume time).
+    if (deadline !== undefined && Date.now() >= deadline) {
+        throw new GislTimeoutError(`Probe wait completed but maxWait elapsed before ${workflowLabel} could be created`);
+    }
+    const created = await client.createWorkflow(toPayload(fileIds, webhook));
+    _checkAborted(signal);
+    return created;
+}
 /**
  * The homogeneous fan-out builder value (FF3a). `client.files([a, b, c])`
  * returns a `FilesRecipe`; the op-chain methods (`compress`, `convert`,
@@ -821,15 +1317,15 @@ export class FilesRecipe {
     compress(optimize, options = {}) {
         return this.withStep(this.baseRecipe().compress(optimize, options));
     }
-    /** Change every input's format. `format` lowers to the contract `output_format` wire key (via {@link Recipe.convert}), NOT `format`. */
+    /** Change every input's format. `format` lowers to the contract `output_format` wire key (via {@link Recipe.convert}), NOT `format`. Option keys are validated (via the base {@link Recipe}) before any upload. */
     convert(format, options = {}) {
         return this.withStep(this.baseRecipe().convert(format, options));
     }
-    /** Generate a preview of every input. Omitted dimensions are dropped from the wire options. */
-    thumbnail(options = {}) {
+    /** Generate a preview of every input. `width` AND `height` are required; validated via the base {@link Recipe} before any upload. */
+    thumbnail(options) {
         return this.withStep(this.baseRecipe().thumbnail(options));
     }
-    /** Apply the same text watermark to every input. */
+    /** Apply the same text watermark to every input. Option keys validated via the base {@link Recipe}. */
     textWatermark(text, options = {}) {
         return this.withStep(this.baseRecipe().textWatermark(text, options));
     }
@@ -1000,69 +1496,16 @@ export class FilesRecipe {
      * deadline checks are skipped.
      */
     async _uploadAllAndCreate(webhook, deadline, onProgress, signal, probeBeforeCreate, probeTimeoutMs) {
-        const fileIds = [];
-        // Track each freshly-uploaded input's probe-gate inputs (a pre-uploaded id
-        // carries no local mime/size, so it is excluded — never probed).
-        const probeTargets = [];
-        for (const input of this.inputs) {
-            // Fail fast between uploads — a deadline that elapses mid-batch should
-            // not force every remaining input to upload before throwing.
-            _checkAborted(signal);
-            if (deadline !== undefined && Date.now() >= deadline) {
-                throw new GislTimeoutError('maxWait elapsed during fan-out uploads before all inputs were uploaded');
-            }
-            if (input.kind === 'uploadId') {
-                fileIds.push(input.fileId);
-            }
-            else {
-                const source = input.kind === 'path' ? input.path : input.blob;
-                const up = await this.client.uploadFile(source, {
-                    signal,
-                    ...(onProgress !== undefined
-                        ? {
-                            onProgress: (uploadedBytes, totalBytes) => {
-                                onProgress({ phase: 'upload', uploadedBytes, totalBytes });
-                            },
-                        }
-                        : {}),
-                });
-                fileIds.push(up.fileId);
-                probeTargets.push({
-                    fileId: up.fileId,
-                    isVideo: _detectCompressMedia(source) === 'video',
-                    sizeBytes: up.sizeBytes,
-                });
-            }
-        }
-        _checkAborted(signal);
-        if (deadline !== undefined && Date.now() >= deadline) {
-            throw new GislTimeoutError('Uploads completed but maxWait elapsed before workflow could be created');
-        }
-        // Best-effort probe-before-create for the multipart-video inputs. Run the
-        // waits CONCURRENTLY (Promise.all): each is bounded by the SAME capped
-        // timeout, so the aggregate wall-clock stays ~timeout rather than N×timeout.
-        // The cap is the remaining maxWait budget so the waits cannot push
-        // createWorkflow past the caller's deadline. Never-bounce, so a give-up
-        // just proceeds.
-        const cappedProbeTimeoutMs = _cappedProbeTimeoutMs(probeTimeoutMs, deadline);
-        await Promise.all(probeTargets.map((t) => this.client.maybeWaitForVideoProbe(t.fileId, {
-            enabled: probeBeforeCreate ?? true,
-            isVideo: t.isVideo,
-            sizeBytes: t.sizeBytes,
-            timeoutMs: cappedProbeTimeoutMs,
+        return _uploadInputsAndCreate(this.client, this.inputs, (fileIds, callbackUrl) => this.toWorkflowPayload(fileIds, callbackUrl), {
+            webhook,
+            deadline,
+            onProgress,
             signal,
-        })));
-        // A cancel arriving during a FINAL successful probe request must not still
-        // create the workflow (the probe waits return landed without a final abort
-        // re-check), so check here BEFORE createWorkflow.
-        _checkAborted(signal);
-        // RE-CHECK the deadline AFTER the probe waits (they consume time).
-        if (deadline !== undefined && Date.now() >= deadline) {
-            throw new GislTimeoutError('Probe wait completed but maxWait elapsed before workflow could be created');
-        }
-        const created = await this.client.createWorkflow(this.toWorkflowPayload(fileIds, webhook));
-        _checkAborted(signal);
-        return created;
+            probeBeforeCreate,
+            probeTimeoutMs,
+            uploadsLabel: 'fan-out',
+            workflowLabel: 'workflow',
+        });
     }
     /**
      * The shared single-file {@link Recipe} that captures the op chain (input is
@@ -1125,19 +1568,16 @@ export class MergedRecipe {
             options: { ...options, ...(optimize !== undefined ? { optimize } : {}) },
         });
     }
-    /** Change the merged output's format. See {@link Recipe.convert}. */
+    /** Change the merged output's format. See {@link Recipe.convert}. Option keys validated pre-upload. */
     convert(format, options = {}) {
-        // The convert op's wire key is `output_format` (contract: convert.yaml,
-        // required, all media), NOT `format`. Spread options FIRST so the explicit
-        // shorthand wins over an `output_format` key in the bag.
-        // The shorthand owns the format → a stray legacy `format` key in the bag is
-        // not a valid convert option; drop it so the wire never carries both keys.
-        const rest = { ...options };
-        delete rest.format;
-        return this.withStep({ opType: 'convert', options: { ...rest, output_format: format } });
-    }
-    /** Thumbnail the merged output. Omitted dimensions are dropped from the wire options. */
-    thumbnail(options = {}) {
+        validateVerbOptions('convert', options);
+        // Validation guarantees the bag carries neither `format` nor `output_format`.
+        return this.withStep({ opType: 'convert', options: { ...options, output_format: format } });
+    }
+    /** Thumbnail the merged output. `width` AND `height` are required; validated pre-upload. */
+    thumbnail(options) {
+        validateVerbOptions('thumbnail', options);
+        assertThumbnailDimensions(options);
         const wire = {};
         for (const [key, value] of Object.entries(options)) {
             if (value !== undefined)
@@ -1259,65 +1699,16 @@ export class MergedRecipe {
      */
     async _uploadAllAndCreate(webhook, deadline, onProgress, signal, probeBeforeCreate, probeTimeoutMs) {
         this.validatePreUpload();
-        const fileIds = [];
-        // Per-input video detection: merge's inferMediaKind decides the OUTPUT
-        // media, not each input's, so detect per input via _detectCompressMedia.
-        // A pre-uploaded id carries no local mime/size, so it is never probed.
-        const probeTargets = [];
-        for (const input of this.inputs) {
-            _checkAborted(signal);
-            if (deadline !== undefined && Date.now() >= deadline) {
-                throw new GislTimeoutError('maxWait elapsed during merge uploads before all inputs were uploaded');
-            }
-            if (input.kind === 'uploadId') {
-                fileIds.push(input.fileId);
-            }
-            else {
-                const source = input.kind === 'path' ? input.path : input.blob;
-                const up = await this.client.uploadFile(source, {
-                    signal,
-                    ...(onProgress !== undefined
-                        ? {
-                            onProgress: (uploadedBytes, totalBytes) => {
-                                onProgress({ phase: 'upload', uploadedBytes, totalBytes });
-                            },
-                        }
-                        : {}),
-                });
-                fileIds.push(up.fileId);
-                probeTargets.push({
-                    fileId: up.fileId,
-                    isVideo: _detectCompressMedia(source) === 'video',
-                    sizeBytes: up.sizeBytes,
-                });
-            }
-        }
-        _checkAborted(signal);
-        if (deadline !== undefined && Date.now() >= deadline) {
-            throw new GislTimeoutError('Uploads completed but maxWait elapsed before the merge workflow could be created');
-        }
-        // Best-effort, concurrent probe-before-create for the multipart-video
-        // inputs (never-bounce; each capped to the remaining maxWait budget so the
-        // waits cannot push createWorkflow past the caller's deadline).
-        const cappedProbeTimeoutMs = _cappedProbeTimeoutMs(probeTimeoutMs, deadline);
-        await Promise.all(probeTargets.map((t) => this.client.maybeWaitForVideoProbe(t.fileId, {
-            enabled: probeBeforeCreate ?? true,
-            isVideo: t.isVideo,
-            sizeBytes: t.sizeBytes,
-            timeoutMs: cappedProbeTimeoutMs,
+        return _uploadInputsAndCreate(this.client, this.inputs, (fileIds, callbackUrl) => this.toWorkflowPayload(fileIds, callbackUrl), {
+            webhook,
+            deadline,
+            onProgress,
             signal,
-        })));
-        // A cancel arriving during a FINAL successful probe request must not still
-        // create the workflow (the probe waits return landed without a final abort
-        // re-check), so check here BEFORE createWorkflow.
-        _checkAborted(signal);
-        // RE-CHECK the deadline AFTER the probe waits (they consume time).
-        if (deadline !== undefined && Date.now() >= deadline) {
-            throw new GislTimeoutError('Probe wait completed but maxWait elapsed before the merge workflow could be created');
-        }
-        const created = await this.client.createWorkflow(this.toWorkflowPayload(fileIds, webhook));
-        _checkAborted(signal);
-        return created;
+            probeBeforeCreate,
+            probeTimeoutMs,
+            uploadsLabel: 'merge',
+            workflowLabel: 'the merge workflow',
+        });
     }
     /**
      * Reject an invalid combine BEFORE any upload fires — mirrors the operation-
@@ -1524,65 +1915,16 @@ export class ArchivedRecipe {
     // ---------------------------------------------------------------------------
     async _uploadAllAndCreate(webhook, deadline, onProgress, signal, probeBeforeCreate, probeTimeoutMs) {
         this.validatePreUpload();
-        const fileIds = [];
-        // Archive is media-agnostic (no inference) — detect per input via
-        // _detectCompressMedia so only video uploads are probed. A pre-uploaded id
-        // carries no local mime/size, so it is never probed.
-        const probeTargets = [];
-        for (const input of this.inputs) {
-            _checkAborted(signal);
-            if (deadline !== undefined && Date.now() >= deadline) {
-                throw new GislTimeoutError('maxWait elapsed during archive uploads before all inputs were uploaded');
-            }
-            if (input.kind === 'uploadId') {
-                fileIds.push(input.fileId);
-            }
-            else {
-                const source = input.kind === 'path' ? input.path : input.blob;
-                const up = await this.client.uploadFile(source, {
-                    signal,
-                    ...(onProgress !== undefined
-                        ? {
-                            onProgress: (uploadedBytes, totalBytes) => {
-                                onProgress({ phase: 'upload', uploadedBytes, totalBytes });
-                            },
-                        }
-                        : {}),
-                });
-                fileIds.push(up.fileId);
-                probeTargets.push({
-                    fileId: up.fileId,
-                    isVideo: _detectCompressMedia(source) === 'video',
-                    sizeBytes: up.sizeBytes,
-                });
-            }
-        }
-        _checkAborted(signal);
-        if (deadline !== undefined && Date.now() >= deadline) {
-            throw new GislTimeoutError('Uploads completed but maxWait elapsed before the archive workflow could be created');
-        }
-        // Best-effort, concurrent probe-before-create for the multipart-video
-        // inputs (never-bounce; each capped to the remaining maxWait budget so the
-        // waits cannot push createWorkflow past the caller's deadline).
-        const cappedProbeTimeoutMs = _cappedProbeTimeoutMs(probeTimeoutMs, deadline);
-        await Promise.all(probeTargets.map((t) => this.client.maybeWaitForVideoProbe(t.fileId, {
-            enabled: probeBeforeCreate ?? true,
-            isVideo: t.isVideo,
-            sizeBytes: t.sizeBytes,
-            timeoutMs: cappedProbeTimeoutMs,
+        return _uploadInputsAndCreate(this.client, this.inputs, (fileIds, callbackUrl) => this.toWorkflowPayload(fileIds, callbackUrl), {
+            webhook,
+            deadline,
+            onProgress,
             signal,
-        })));
-        // A cancel arriving during a FINAL successful probe request must not still
-        // create the workflow (the probe waits return landed without a final abort
-        // re-check), so check here BEFORE createWorkflow.
-        _checkAborted(signal);
-        // RE-CHECK the deadline AFTER the probe waits (they consume time).
-        if (deadline !== undefined && Date.now() >= deadline) {
-            throw new GislTimeoutError('Probe wait completed but maxWait elapsed before the archive workflow could be created');
-        }
-        const created = await this.client.createWorkflow(this.toWorkflowPayload(fileIds, webhook));
-        _checkAborted(signal);
-        return created;
+            probeBeforeCreate,
+            probeTimeoutMs,
+            uploadsLabel: 'archive',
+            workflowLabel: 'the archive workflow',
+        });
     }
     /**
      * Reject an invalid bundle BEFORE any upload fires — the archive schema allows
@@ -1610,3 +1952,215 @@ export class ArchivedRecipe {
         return out;
     }
 }
+/**
+ * The single-output recipe you're in AFTER `file(base).watermark(overlay, …)`
+ * (FF4a). Composites an image OVERLAY onto the base (image_watermark for image
+ * bases, video_watermark for video bases — routed at lowering by the base's
+ * effective media). A multi-input op: base + overlay each enter via their own
+ * `passthrough` source job (`src_0` base, `src_1` overlay; their own preceding
+ * steps lower into those jobs), and the `watermark` job consumes them via
+ * `job_output` inputs tagged `role: base` / `role: overlay`. Post-watermark
+ * `compress`/`convert`/`thumbnail` chain onto the watermark output. Mirrors
+ * {@link MergedRecipe}. `textWatermark` is intentionally NOT a post-verb here.
+ */
+export class WatermarkedRecipe {
+    baseInput;
+    baseSteps;
+    overlay;
+    watermarkOptions;
+    postSteps;
+    presetDefaults;
+    scopedPresetDefaults;
+    client;
+    constructor(baseInput, baseSteps, overlay, watermarkOptions, postSteps = [], presetDefaults, scopedPresetDefaults, client) {
+        this.baseInput = baseInput;
+        this.baseSteps = baseSteps;
+        this.overlay = overlay;
+        this.watermarkOptions = watermarkOptions;
+        this.postSteps = postSteps;
+        this.presetDefaults = presetDefaults;
+        this.scopedPresetDefaults = scopedPresetDefaults;
+        this.client = client;
+    }
+    /** Reduce the watermarked output's size. See {@link Recipe.compress}. */
+    compress(optimize, options = {}) {
+        if (optimize !== undefined && !Object.values(OptimizeFor).includes(optimize)) {
+            const allowed = Object.values(OptimizeFor).join(', ');
+            throw new GislConfigError(`compress 'optimize' must be one of ${allowed}; got '${String(optimize)}'.`, { reason: 'invalid_optimize', conflictingFields: ['optimize'] });
+        }
+        return this.withStep({
+            opType: 'compress',
+            options: { ...options, ...(optimize !== undefined ? { optimize } : {}) },
+        });
+    }
+    /** Change the watermarked output's format. See {@link Recipe.convert}. Option keys validated pre-upload. */
+    convert(format, options = {}) {
+        validateVerbOptions('convert', options);
+        // Validation guarantees the bag carries neither `format` nor `output_format`.
+        return this.withStep({ opType: 'convert', options: { ...options, output_format: format } });
+    }
+    /** Thumbnail the watermarked output. `width` AND `height` are required; validated pre-upload. */
+    thumbnail(options) {
+        validateVerbOptions('thumbnail', options);
+        assertThumbnailDimensions(options);
+        const wire = {};
+        for (const [key, value] of Object.entries(options)) {
+            if (value !== undefined)
+                wire[key] = value;
+        }
+        return this.withStep({ opType: 'thumbnail', options: wire });
+    }
+    /**
+     * Lower to the watermark DAG: a `src_0` passthrough/base-steps job + a `src_1`
+     * passthrough/overlay-steps job + one `watermark` job whose `inputs[]` consume
+     * them via `job_output` (role base/overlay) and whose `operations[]` is
+     * `[image_watermark|video_watermark, ...post-watermark ops]`. `fileIds` is
+     * `[baseId, overlayId]` (upload order). Throws pre-lowering if the base media
+     * is undetectable/unsupported (the planned-op gate).
+     *
+     * @internal Consumed by {@link run}/{@link submit} (after upload) + the parity harness.
+     */
+    toWorkflowPayload(fileIds, callbackUrl) {
+        const wireOp = _resolveWatermarkWireOp(_watermarkEffectiveBase(this.baseInput, this.baseSteps));
+        const baseId = fileIds[0];
+        const overlayId = fileIds[1];
+        // src_0: the base (its preceding steps, else a lossless passthrough).
+        const baseOps = this.baseSteps.length > 0
+            ? new Recipe(this.baseInput, undefined, this.baseSteps, this.presetDefaults, this.scopedPresetDefaults)
+                .toWorkflowPayload(baseId).jobs[0].operations
+            : [{ type: 'passthrough' }];
+        // src_1: the overlay recipe (its own steps, else a lossless passthrough).
+        const overlayOps = this.overlay.recipeSteps.length > 0
+            ? this.overlay.toWorkflowPayload(overlayId).jobs[0].operations
+            : [{ type: 'passthrough' }];
+        // Key order (id, source, operations) matches PHP toWire() — byte-identical JSON.
+        const srcBase = { id: 'src_0', source: uploadSource(baseId), operations: baseOps };
+        const srcOverlay = { id: 'src_1', source: uploadSource(overlayId), operations: overlayOps };
+        const inputs = [
+            { source: jobOutputSource('src_0'), role: 'base' },
+            { source: jobOutputSource('src_1'), role: 'overlay' },
+        ];
+        const operations = [
+            _lowerWatermarkOp(wireOp, this.watermarkOptions),
+            ...this.lowerPostSteps(wireOp),
+        ];
+        const watermarkJob = { id: 'watermark', inputs, operations };
+        const jobs = [srcBase, srcOverlay, watermarkJob];
+        return callbackUrl === undefined ? { jobs } : { jobs, callback_url: callbackUrl };
+    }
+    /** The number of post-watermark ops chained so far (introspection / tests). */
+    get stepCount() {
+        return this.postSteps.length;
+    }
+    /**
+     * Execute end-to-end: upload base + overlay, create the watermark workflow,
+     * await terminal (SSE with poll fallback), then resolve ONLY the watermark
+     * output into a {@link RunResult}. Requires a client bound at construction.
+     * Mirrors {@link MergedRecipe.run}.
+     */
+    async run(options = {}) {
+        const signal = options.signal;
+        const onProgress = options.onProgress;
+        if (this.client === undefined) {
+            throw new GislConfigError('WatermarkedRecipe.run() requires a client; build the watermark via gisl().file(...).watermark(...) rather than constructing WatermarkedRecipe directly.', { reason: 'no_client' });
+        }
+        const deadline = Date.now() + _parseMaxWait(options.maxWait ?? 300_000);
+        const created = await this._uploadAllAndCreate(undefined, deadline, onProgress, signal, options.probeBeforeCreate, options.probeTimeoutMs);
+        let finalStatus;
+        try {
+            finalStatus = await _consumeSseToTerminal(this.client, {
+                workflowId: created.workflowId,
+                deadline,
+                signal,
+                onProgress,
+            });
+        }
+        catch (err) {
+            if (!(err instanceof SseEndedWithoutTerminal || err instanceof GislNetworkError)) {
+                throw err;
+            }
+            finalStatus = await _pollToTerminal(this.client, {
+                workflowId: created.workflowId,
+                deadline,
+                signal,
+                pollIntervalMs: options.pollIntervalMs,
+            });
+        }
+        if (Date.now() >= deadline) {
+            throw new GislTimeoutError(`Workflow ${created.workflowId} reached terminal status but maxWait elapsed before downloads could be fetched`);
+        }
+        const downloads = await this.client.getWorkflowDownloads(created.workflowId);
+        if (Date.now() >= deadline) {
+            throw new GislTimeoutError(`Workflow ${created.workflowId} downloads fetch completed after maxWait elapsed`);
+        }
+        // Project ONLY the watermark job's output — the `src_*` passthrough jobs
+        // re-expose the raw base/overlay uploads, which are plumbing.
+        const watermarkDownloads = downloads.downloads.filter((d) => d.ref === 'watermark');
+        const downloader = new LazyHttpDownloader();
+        return projectDownloadsToRunResult(created.workflowId, finalStatus, watermarkDownloads, null, downloader);
+    }
+    /**
+     * Fire-and-forget: upload base + overlay + create the watermark workflow
+     * (wiring `webhook` into `callback_url` when given), return a client-bound
+     * {@link Handle}. Does NOT wait for terminal status. Mirrors {@link MergedRecipe.submit}.
+     */
+    async submit(webhook, options) {
+        if (this.client === undefined) {
+            throw new GislConfigError('WatermarkedRecipe.submit() requires a client; build the watermark via gisl().file(...).watermark(...) rather than constructing WatermarkedRecipe directly.', { reason: 'no_client' });
+        }
+        const created = await this._uploadAllAndCreate(webhook, undefined, undefined, undefined, options?.probeBeforeCreate, options?.probeTimeoutMs);
+        return new Handle(created.workflowId, created.webhookSecret != null ? created.webhookSecret : undefined, this.client, null);
+    }
+    // ---------------------------------------------------------------------------
+    /** Base + overlay inputs, in upload/lowering order (`[base, overlay]`). */
+    inputsInOrder() {
+        return [this.baseInput, this.overlay.recipeInput];
+    }
+    /**
+     * Validate the watermark BEFORE any upload: the base must route to a shippable
+     * wire op (throws for undetectable/unsupported/planned bases), and the overlay
+     * must be an image. Shared by {@link run}/{@link submit}. Mirrors
+     * {@link MergedRecipe.validatePreUpload}.
+     */
+    validatePreUpload() {
+        _resolveWatermarkWireOp(_watermarkEffectiveBase(this.baseInput, this.baseSteps));
+        _validateWatermarkOverlay(this.overlay);
+    }
+    /**
+     * Upload base + overlay (verbatim for a pre-uploaded id; uploading a path /
+     * blob otherwise) then create ONE watermark workflow. Validates pre-upload.
+     * Shared first half of {@link run} + {@link submit}; mirrors
+     * {@link MergedRecipe._uploadAllAndCreate}.
+     */
+    async _uploadAllAndCreate(webhook, deadline, onProgress, signal, probeBeforeCreate, probeTimeoutMs) {
+        this.validatePreUpload();
+        return _uploadInputsAndCreate(this.client, this.inputsInOrder(), (fileIds, callbackUrl) => this.toWorkflowPayload(fileIds, callbackUrl), {
+            webhook,
+            deadline,
+            onProgress,
+            signal,
+            probeBeforeCreate,
+            probeTimeoutMs,
+            uploadsLabel: 'watermark',
+            workflowLabel: 'the watermark workflow',
+        });
+    }
+    /**
+     * Lower the post-watermark chain over a synthetic input whose extension
+     * matches the watermark OUTPUT media (image→png, video→mp4) so
+     * `compress(optimize)` resolves the correct preset — mirrors
+     * {@link MergedRecipe.lowerPostSteps}.
+     */
+    lowerPostSteps(wireOp) {
+        if (this.postSteps.length === 0) {
+            return [];
+        }
+        const ext = wireOp === 'video_watermark' ? 'mp4' : 'png';
+        const synthetic = fileInput.path(`watermarked.${ext}`);
+        const recipe = new Recipe(synthetic, undefined, this.postSteps, this.presetDefaults, this.scopedPresetDefaults);
+        return recipe.toWorkflowPayload('watermarked').jobs[0].operations;
+    }
+    withStep(step) {
+        return new WatermarkedRecipe(this.baseInput, this.baseSteps, this.overlay, this.watermarkOptions, [...this.postSteps, step], this.presetDefaults, this.scopedPresetDefaults, this.client);
+    }
+}