@giveitsmaller/sdk 0.16.0 → 0.18.0

package/dist/file-first.d.ts

@@ -9,9 +9,11 @@
  *
  * Mirrors `packages/php/src/FileFirst/*`.
  */
+import { GislItemFailedError } from './errors.js';
 import { type ProgressEvent } from './builder.js';
 import type { GislClient } from './client.js';
 import type { OperationDownload, WorkflowStatusResponse } from '@giveitsmaller/contracts/openapi';
+import type { ConvertOptions, ThumbnailOptions, TextWatermarkOptions, WatermarkOptions, OutputOptions, OutputFit } from './ergonomic/option_types.js';
 import { OptimizeFor } from './generated/sdk_spec/enums.js';
 import type { PresetDefaults } from './ergonomic/presets/index.js';
 import type { WorkflowCreatePayload } from './types.js';
@@ -66,15 +68,16 @@ export interface ItemResult {
     readonly outputs: readonly OutputFile[];
 }
 /**
- * One failed entry in {@link RunResult.failed}: an input that did not
- * produce a deliverable, paired with the cause. One bad input does not sink
- * the rest of a multi-input run. `error` is `unknown` (mirroring the PHP
- * `\Throwable`) so the caller narrows with `instanceof`. Mirrors the PHP
- * `ItemFailure`.
+ * One failed entry in {@link RunResult.failed}: an input that did not produce a
+ * deliverable, paired with the cause. One bad input does not sink the rest of a
+ * multi-input run. `error` is a typed {@link GislItemFailedError} carrying the
+ * terminal `state` plus the failing operation's `errorMessage`/`errorCode` (when
+ * present), so the caller can branch on the failure WITHOUT string-parsing.
+ * Mirrors the PHP `ItemFailure`.
  */
 export interface ItemFailure {
     readonly key: string | null;
-    readonly error: unknown;
+    readonly error: GislItemFailedError;
 }
 /**
  * Return value of {@link RunResult.downloadTo} — the local paths written,
@@ -159,27 +162,13 @@ export declare class RunResult {
         failed: readonly {
             key: string | null;
             error: string;
+            state: string;
+            errorMessage?: string;
+            errorCode?: string;
         }[];
     };
     private requireDownloader;
 }
-/**
- * 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.
- */
 export declare function projectDownloadsToRunResult(workflowId: string, finalStatus: WorkflowStatusResponse, jobDownloads: readonly {
     files: readonly OperationDownload[];
 }[], key: string | null, downloader?: Downloader): RunResult;
@@ -306,7 +295,7 @@ export declare const fileInput: {
 };
 /** One step in a {@link Recipe}'s chain — an op kind + captured ergonomic args. */
 interface RecipeStep {
-    readonly opType: 'compress' | 'convert' | 'thumbnail' | 'text_watermark';
+    readonly opType: 'compress' | 'convert' | 'thumbnail' | 'text_watermark' | 'output';
     readonly options: Readonly<Record<string, unknown>>;
 }
 /**
@@ -352,22 +341,42 @@ export declare class Recipe {
      * option (the convert op's wire key per the contract); `options` carries any
      * additional per-op convert options.
      */
-    convert(format: string, options?: Record<string, unknown>): Recipe;
+    convert(format: string, options?: ConvertOptions): Recipe;
     /**
-     * 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?: {
-        width?: number;
-        height?: number;
-    } & Record<string, unknown>): Recipe;
+    thumbnail(options: ThumbnailOptions): Recipe;
+    /**
+     * 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?: string, options?: OutputOptions): Recipe;
+    /**
+     * 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: number, height?: number, fit?: OutputFit): Recipe;
     /**
      * 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: string, options?: Record<string, unknown>): Recipe;
+    textWatermark(text: string, options?: TextWatermarkOptions): Recipe;
     /**
      * 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')`),
@@ -380,7 +389,7 @@ export declare class Recipe {
      * `compress`/`convert`/`thumbnail`, then `run`/`submit`). Distinct from
      * {@link textWatermark} (single-input text overlay).
      */
-    watermark(overlay: Recipe, options?: Record<string, unknown>): WatermarkedRecipe;
+    watermark(overlay: Recipe, options?: WatermarkOptions): WatermarkedRecipe;
     /**
      * Lower this recipe to a workflow-create payload against a resolved upload
      * id. Single-input chain → ONE job, `source: upload(fileId)`, ordered
@@ -465,6 +474,26 @@ export declare class Recipe {
     private _uploadAndCreate;
     private withStep;
     private lowerStep;
+    /**
+     * 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.
+     */
+    private lowerOutputStep;
+    /**
+     * 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).
+     */
+    private outputInputToken;
+    /** The original input's image format token (path ext / Blob type / Blob name). */
+    private inputFormatToken;
     private lowerCompressOptions;
     /** Media of the original input (no chain context) — used by the probe gate. */
     private inputMedia;
@@ -555,15 +584,12 @@ export declare class FilesRecipe {
      * lowering builds an internal Recipe that throws the same `GislConfigError`.
      */
     compress(optimize?: OptimizeFor, options?: Record<string, unknown>): FilesRecipe;
-    /** Change every input's format. `format` lowers to the contract `output_format` wire key (via {@link Recipe.convert}), NOT `format`. */
-    convert(format: string, options?: Record<string, unknown>): FilesRecipe;
-    /** Generate a preview of every input. Omitted dimensions are dropped from the wire options. */
-    thumbnail(options?: {
-        width?: number;
-        height?: number;
-    } & Record<string, unknown>): FilesRecipe;
-    /** Apply the same text watermark to every input. */
-    textWatermark(text: string, options?: Record<string, unknown>): FilesRecipe;
+    /** 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: string, options?: ConvertOptions): FilesRecipe;
+    /** Generate a preview of every input. `width` AND `height` are required; validated via the base {@link Recipe} before any upload. */
+    thumbnail(options: ThumbnailOptions): FilesRecipe;
+    /** Apply the same text watermark to every input. Option keys validated via the base {@link Recipe}. */
+    textWatermark(text: string, options?: TextWatermarkOptions): FilesRecipe;
     /**
      * Combine the inputs into ONE output (N→1), in array order (FF3b). Returns a
      * single-output {@link MergedRecipe} you chain further ops on
@@ -694,13 +720,10 @@ export declare class MergedRecipe {
     constructor(inputs: readonly FileInput[], mergeOptions: MergeOptions, postSteps?: readonly RecipeStep[], presetDefaults?: PresetDefaults | undefined, scopedPresetDefaults?: PresetDefaults | undefined, client?: GislClient | undefined);
     /** Reduce the merged output's size. See {@link Recipe.compress}. */
     compress(optimize?: OptimizeFor, options?: Record<string, unknown>): MergedRecipe;
-    /** Change the merged output's format. See {@link Recipe.convert}. */
-    convert(format: string, options?: Record<string, unknown>): MergedRecipe;
-    /** Thumbnail the merged output. Omitted dimensions are dropped from the wire options. */
-    thumbnail(options?: {
-        width?: number;
-        height?: number;
-    } & Record<string, unknown>): MergedRecipe;
+    /** Change the merged output's format. See {@link Recipe.convert}. Option keys validated pre-upload. */
+    convert(format: string, options?: ConvertOptions): MergedRecipe;
+    /** Thumbnail the merged output. `width` AND `height` are required; validated pre-upload. */
+    thumbnail(options: ThumbnailOptions): MergedRecipe;
     /**
      * Lower to the merge DAG: one `passthrough` source job per input + one
      * `merge` job whose `operations[]` is `[merge, ...post-combine ops]`. The
@@ -877,16 +900,13 @@ export declare class WatermarkedRecipe {
     private readonly presetDefaults?;
     private readonly scopedPresetDefaults?;
     private readonly client?;
-    constructor(baseInput: FileInput, baseSteps: readonly RecipeStep[], overlay: Recipe, watermarkOptions: Readonly<Record<string, unknown>>, postSteps?: readonly RecipeStep[], presetDefaults?: PresetDefaults | undefined, scopedPresetDefaults?: PresetDefaults | undefined, client?: GislClient | undefined);
+    constructor(baseInput: FileInput, baseSteps: readonly RecipeStep[], overlay: Recipe, watermarkOptions: WatermarkOptions, postSteps?: readonly RecipeStep[], presetDefaults?: PresetDefaults | undefined, scopedPresetDefaults?: PresetDefaults | undefined, client?: GislClient | undefined);
     /** Reduce the watermarked output's size. See {@link Recipe.compress}. */
     compress(optimize?: OptimizeFor, options?: Record<string, unknown>): WatermarkedRecipe;
-    /** Change the watermarked output's format. See {@link Recipe.convert}. */
-    convert(format: string, options?: Record<string, unknown>): WatermarkedRecipe;
-    /** Thumbnail the watermarked output. Omitted dimensions are dropped from the wire options. */
-    thumbnail(options?: {
-        width?: number;
-        height?: number;
-    } & Record<string, unknown>): WatermarkedRecipe;
+    /** Change the watermarked output's format. See {@link Recipe.convert}. Option keys validated pre-upload. */
+    convert(format: string, options?: ConvertOptions): WatermarkedRecipe;
+    /** Thumbnail the watermarked output. `width` AND `height` are required; validated pre-upload. */
+    thumbnail(options: ThumbnailOptions): WatermarkedRecipe;
     /**
      * 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

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),
             });
         }
     }
@@ -468,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)
@@ -490,13 +488,65 @@ 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 } });
     }
     /**
@@ -512,6 +562,9 @@ export class Recipe {
      * {@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);
@@ -742,6 +795,11 @@ export class Recipe {
         return new Recipe(this.input, this.recipeKey, [...this.steps, step], this.presetDefaults, this.scopedPresetDefaults, this.client);
     }
     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 };
@@ -751,6 +809,103 @@ export class Recipe {
             ? { type: step.opType }
             : { type: step.opType, options };
     }
+    /**
+     * 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
@@ -1162,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));
     }
@@ -1413,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)
@@ -1841,14 +1993,16 @@ export class WatermarkedRecipe {
             options: { ...options, ...(optimize !== undefined ? { optimize } : {}) },
         });
     }
-    /** Change the watermarked output's format. See {@link Recipe.convert}. */
+    /** Change the watermarked output's format. See {@link Recipe.convert}. Option keys validated pre-upload. */
     convert(format, options = {}) {
-        const rest = { ...options };
-        delete rest.format;
-        return this.withStep({ opType: 'convert', options: { ...rest, output_format: format } });
-    }
-    /** Thumbnail the watermarked 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 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)