@giveitsmaller/sdk 0.19.0 → 0.21.0

package/dist/file-first.js

@@ -14,7 +14,7 @@ import { _detectCompressMedia, _detectAudioLossless, _consumeSseToTerminal, _pol
 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 { resolveOutputRoute, tokenForMime, tokenForPath, isPlannedValue, isUnknownEnumValue, 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),
@@ -159,9 +159,10 @@ export class RunResult {
     toJSON() {
         // Re-project each OutputFile to exactly its known fields so structurally
         // compatible inputs carrying extra properties can't leak into the JSON.
-        // The target-size fields (chosenQuality/targetSizeMet) are OMITTED when
-        // undefined, mirroring PHP's omit-when-null so non-target-size outputs
-        // stay byte-identical across languages.
+        // The projected optional fields (chosenQuality/targetSizeMet and the
+        // auto_quality measuredQuality/qualityMetric) are OMITTED when undefined,
+        // mirroring PHP's omit-when-null so outputs lacking them stay
+        // byte-identical across languages.
         const file = (o) => ({
             url: o.url,
             filename: o.filename,
@@ -169,6 +170,8 @@ export class RunResult {
             operation: o.operation,
             ...(o.chosenQuality !== undefined ? { chosenQuality: o.chosenQuality } : {}),
             ...(o.targetSizeMet !== undefined ? { targetSizeMet: o.targetSizeMet } : {}),
+            ...(o.measuredQuality !== undefined ? { measuredQuality: o.measuredQuality } : {}),
+            ...(o.qualityMetric !== undefined ? { qualityMetric: o.qualityMetric } : {}),
         });
         const rest = {
             artifacts: this.artifacts.map(file),
@@ -230,6 +233,8 @@ export function projectDownloadsToRunResult(workflowId, finalStatus, jobDownload
                 // non-target-size output carries no chosenQuality/targetSizeMet key.
                 ...(f.chosenQuality !== undefined ? { chosenQuality: f.chosenQuality } : {}),
                 ...(f.targetSizeMet !== undefined ? { targetSizeMet: f.targetSizeMet } : {}),
+                ...(f.measuredQuality !== undefined ? { measuredQuality: f.measuredQuality } : {}),
+                ...(f.qualityMetric !== undefined ? { qualityMetric: f.qualityMetric } : {}),
             });
         }
     }
@@ -293,6 +298,8 @@ export function projectMultiJobToRunResult(workflowId, finalStatus, jobDownloads
             // single-job projector).
             ...(f.chosenQuality !== undefined ? { chosenQuality: f.chosenQuality } : {}),
             ...(f.targetSizeMet !== undefined ? { targetSizeMet: f.targetSizeMet } : {}),
+            ...(f.measuredQuality !== undefined ? { measuredQuality: f.measuredQuality } : {}),
+            ...(f.qualityMetric !== undefined ? { qualityMetric: f.qualityMetric } : {}),
         }));
         // The flat artifacts[] keeps every job's outputs in job order.
         artifacts.push(...outputs);
@@ -334,10 +341,54 @@ export function isFanoutStatus(finalStatus) {
     return jobs.length > 0 && jobs.every((job) => _FANOUT_REF.test(job.ref));
 }
 const _MERGE_SRC_REF = /^src_\d+$/;
+/**
+ * Job id/ref for the DOWNSTREAM job that carries post-`sole_op` steps. A
+ * `sole_op` op (image_watermark / video_watermark / merge — ADR-0025) MUST be
+ * the only op in its job, so when a caller chains `compress()` / `convert()` /
+ * `thumbnail()` / `transform()` after `watermark()` / `merge()`, those steps
+ * lower into this separate job that consumes the sole_op output via
+ * `job_output` (the server derives the DAG from the `from` reference — no
+ * explicit `workflow_edges` needed). When present it is the TERMINAL deliverable,
+ * so `run()` / the {@link Handle} project THIS job's output, and the status-shape
+ * detectors accept it alongside the sole_op + `src_{i}` refs. PIiUit28.
+ */
+export const _POST_STEP_JOB_REF = 'post';
+/**
+ * Job id/ref for the UPSTREAM job carrying any steps that PRECEDE a single-input
+ * `sole_op` op (e.g. `.compress().textWatermark()`): the pre-steps run in this
+ * job, the `sole_op` job then consumes its output via `job_output`. Distinct
+ * from the multi-input `src_{i}` fan-in refs. IQc01rj0.
+ */
+export const _PRE_STEP_JOB_REF = 'pre';
+/**
+ * Wire op types the API marks `sole_op` (ADR-0025) — the op MUST be the ONLY op
+ * in its job. Mirrors `operation-capabilities.json` `operations.<op>.sole_op`,
+ * inlined as a browser-safe const (the raw-JSON sidecar subpath is Node-only)
+ * and PINNED to that projection by `sole-op-conformance.test.ts` — a contract
+ * regen that flips an op's `sole_op` fails there. The single-input
+ * {@link Recipe.toWorkflowPayload} reads THIS set to split a chain at every
+ * sole_op boundary into a `job_output`-linked job chain (so
+ * `.textWatermark('x').compress()` lowers to a valid DAG, not a contract-invalid
+ * co-bundled job). Mirrored by PHP `Recipe::SOLE_OP_TYPES`. IQc01rj0.
+ * @internal
+ */
+export const SOLE_OP_TYPES = new Set([
+    'archive',
+    'audio_overlay',
+    'audio_to_video',
+    'custom_luma',
+    'image_watermark',
+    'merge',
+    'split',
+    'text_watermark',
+    'video_text_watermark',
+    'video_watermark',
+]);
 /**
  * True when a terminal status describes a fluent `files([...]).merge(...)`
  * combine — at least one job ref `merge` and every OTHER job ref is `src_{i}`
- * (the ids the {@link MergedRecipe} lowering assigns). The data-driven seam that
+ * or the downstream `post` job (the ids the {@link MergedRecipe} lowering
+ * assigns; `post` carries any post-combine steps). The data-driven seam that
  * lets {@link Handle.wait}/{@link Handle.result} project ONLY the merged output
  * — filtering the `src_*` passthrough plumbing — even after a
  * `client.workflow(id)` reattach (no construction-time marker), matching
@@ -356,6 +407,9 @@ export function isMergeStatus(finalStatus) {
             hasMerge = true;
             continue;
         }
+        // The downstream post-`sole_op` steps job (PIiUit28) is part of a merge DAG.
+        if (job.ref === _POST_STEP_JOB_REF)
+            continue;
         if (!_MERGE_SRC_REF.test(job.ref))
             return false;
     }
@@ -388,9 +442,10 @@ export function isArchiveStatus(finalStatus) {
 }
 /**
  * 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
+ * — at least one job ref `watermark` and every OTHER job ref is `src_{i}` or
+ * the downstream `post` job (the ids the {@link WatermarkedRecipe} lowering
+ * assigns: `src_0` base, `src_1` overlay, `post` any post-watermark steps).
+ * 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} /
@@ -408,11 +463,117 @@ export function isWatermarkStatus(finalStatus) {
             hasWatermark = true;
             continue;
         }
+        // The downstream post-`sole_op` steps job (PIiUit28) is part of a watermark DAG.
+        if (job.ref === _POST_STEP_JOB_REF)
+            continue;
         if (!_MERGE_SRC_REF.test(job.ref))
             return false;
     }
     return hasWatermark;
 }
+/**
+ * True when a terminal status describes a SINGLE-INPUT `sole_op` chain — e.g.
+ * `.textWatermark('x').compress()` lowered to a `text_watermark` job + a
+ * downstream `post` job (and an optional upstream `pre` job for steps before the
+ * sole_op). Every job ref is a `sole_op` wire type ({@link SOLE_OP_TYPES}) or the
+ * `pre`/`post` chain refs, with NO `src_{i}` fan-in ref (which distinguishes it
+ * from the multi-input merge/watermark/archive DAGs). Lets a submitted/reattached
+ * {@link Handle} project ONLY the terminal deliverable — filtering the
+ * intermediate sole_op artifact — without builder state. IQc01rj0.
+ *
+ * @internal Exported for the file-first `Handle`; not part of the public API.
+ */
+export function isSoleOpChainStatus(finalStatus) {
+    const jobs = finalStatus.jobs ?? [];
+    if (jobs.length === 0)
+        return false;
+    let hasSoleOp = false;
+    for (const job of jobs) {
+        if (SOLE_OP_TYPES.has(job.ref)) {
+            hasSoleOp = true;
+            continue;
+        }
+        if (job.ref === _PRE_STEP_JOB_REF || job.ref === _POST_STEP_JOB_REF)
+            continue;
+        return false;
+    }
+    return hasSoleOp;
+}
+/**
+ * The terminal deliverable ref for a single-input `sole_op` chain status: the
+ * downstream `post` job when present, else the `sole_op` job itself (the ref in
+ * {@link SOLE_OP_TYPES}). Mirrors how the merge/watermark paths pick their
+ * terminal via {@link terminalOutputRef} in `handle.ts`. IQc01rj0.
+ *
+ * @internal
+ */
+export function soleOpChainDeliverableRef(finalStatus) {
+    // Determine the terminal from the DAG (the job refs), NOT from which downloads
+    // exist: if the `post` job is in the graph it IS the deliverable even when it
+    // FAILED and produced no download — filtering to it then yields no artifact +
+    // the failure surfaces via the status, rather than silently exposing the
+    // successful intermediate sole_op artifact (codex).
+    const refs = (finalStatus.jobs ?? []).map((j) => j.ref);
+    const soleOpRef = refs.find((r) => SOLE_OP_TYPES.has(r)) ?? '';
+    return refs.includes(_POST_STEP_JOB_REF) ? _POST_STEP_JOB_REF : soleOpRef;
+}
+/**
+ * Split a single-input operation chain into a `job_output`-linked job chain at
+ * its `sole_op` boundary (IQc01rj0). A `sole_op` op (ADR-0025) MUST be the ONLY
+ * op in its job, so `.textWatermark('x').compress()` cannot lower to one
+ * co-bundled job — the `text_watermark` runs alone (job id = its op type) and
+ * the trailing steps lower into a downstream `post` job that consumes it via
+ * `job_output`; steps that PRECEDE the sole_op run in an upstream `pre` job.
+ *
+ * Returns a single job verbatim (NO `id`) when no split is needed — no sole_op,
+ * or a lone sole_op already alone — so the vast majority of recipes keep their
+ * byte-identical one-job shape. Throws when the chain carries more than one
+ * sole_op op (a single-input recipe reaches at most one sole_op verb today;
+ * supporting N is a follow-up).
+ */
+function _splitSingleInputJobs(ops, fileId) {
+    const soleCount = ops.reduce((n, op) => (SOLE_OP_TYPES.has(op.type) ? n + 1 : n), 0);
+    if (soleCount > 1) {
+        throw new GislConfigError('This recipe chains more than one sole_op operation (e.g. two textWatermark() steps), ' +
+            'which is not supported yet — apply them as separate workflows.', { reason: 'multi_sole_op_unsupported' });
+    }
+    const i = ops.findIndex((op) => SOLE_OP_TYPES.has(op.type));
+    if (i === -1 || (i === 0 && ops.length === 1)) {
+        // No sole_op, or a lone sole_op already alone → one job, no id (unchanged).
+        return [{ source: uploadSource(fileId), operations: [...ops] }];
+    }
+    const preOps = ops.slice(0, i);
+    const soleOp = ops[i];
+    const postOps = ops.slice(i + 1);
+    const jobs = [];
+    if (preOps.length > 0) {
+        jobs.push({ id: _PRE_STEP_JOB_REF, source: uploadSource(fileId), operations: [...preOps] });
+    }
+    jobs.push({
+        id: soleOp.type,
+        source: preOps.length > 0 ? jobOutputSource(_PRE_STEP_JOB_REF) : uploadSource(fileId),
+        operations: [soleOp],
+    });
+    if (postOps.length > 0) {
+        jobs.push({ id: _POST_STEP_JOB_REF, source: jobOutputSource(soleOp.type), operations: [...postOps] });
+    }
+    return jobs;
+}
+/**
+ * The single job of a NESTED single-input lowering, asserting it did not split
+ * (IQc01rj0). A nested Recipe used as a watermark base/overlay or a fan-out
+ * entry that itself carries a `sole_op` op alongside OTHER steps splits into a
+ * job chain; folding that chain into the OUTER DAG (as a `src_{i}`/`file-{i}`
+ * job) is not supported yet, so fail fast rather than silently drop the
+ * split-off downstream job (the whole point of the split).
+ */
+function _nestedSingleJob(payload, context) {
+    if (payload.jobs.length !== 1) {
+        throw new GislConfigError(`A ${context} recipe chains a sole_op op (e.g. textWatermark()) alongside other steps, which ` +
+            'is not supported here yet — apply the sole_op step in a standalone recipe.', { reason: 'nested_sole_op_unsupported' });
+    }
+    return payload.jobs[0];
+}
 /** Named constructors for {@link FileInput} — mirror the PHP static factories. */
 export const fileInput = {
     path(path) {
@@ -438,6 +599,48 @@ export const fileInput = {
         return { kind: 'uploadId', fileId };
     },
 };
+/**
+ * Await a workflow to a terminal status — SSE first with a poll fallback, or
+ * poll-direct when `useSSE` is false. The single shared implementation behind
+ * every file-first `run()` (Recipe, FilesRecipe, MergedRecipe, ArchivedRecipe,
+ * WatermarkedRecipe), mirroring the operation-first
+ * `OperationBuilder.awaitTerminal` (in `builder.ts`). Callers pass
+ * `useSSE: options.useSSE ?? true` so the default stays SSE-first (today's
+ * behaviour); `useSSE: false` skips the SSE attempt entirely and polls —
+ * useful when an intermediary proxy blocks SSE.
+ *
+ * @internal Not part of the caller-facing fluent surface.
+ */
+async function _awaitTerminal(client, args) {
+    if (args.useSSE) {
+        try {
+            return await _consumeSseToTerminal(client, {
+                workflowId: args.workflowId,
+                deadline: args.deadline,
+                signal: args.signal,
+                onProgress: args.onProgress,
+            });
+        }
+        catch (err) {
+            // TDqmkWpX: poll-fallback ONLY on a clean SSE stream-end
+            // (SseEndedWithoutTerminal) or a typed transport error (GislNetworkError).
+            // Everything else — caller-deadline, abort, an API error from /events, an
+            // onProgress callback throw (propagates as-is, NOT wrapped), anything
+            // unexpected — MUST propagate; re-issuing the same doomed request via poll
+            // would mask it. Mirrors the PHP BuilderInternals::awaitTerminal sealed-
+            // marker discipline.
+            if (!(err instanceof SseEndedWithoutTerminal || err instanceof GislNetworkError)) {
+                throw err;
+            }
+        }
+    }
+    return await _pollToTerminal(client, {
+        workflowId: args.workflowId,
+        deadline: args.deadline,
+        signal: args.signal,
+        pollIntervalMs: args.pollIntervalMs,
+    });
+}
 /**
  * The file-first builder value. `client.file(path)` returns a `Recipe`;
  * single-input operations called on it (`compress`, `convert`, `thumbnail`,
@@ -522,6 +725,27 @@ export class Recipe {
         }
         return this.withStep({ opType: 'thumbnail', options: wire });
     }
+    /**
+     * Geometric transform: rotate (0/90/180/270°) and/or flip. Chainable — the
+     * canonical single-job order is `transform → convert → compress → thumbnail`,
+     * so downstream size options refer to the final (post-transform) frame.
+     *
+     * Passthrough: `rotate`/`flip` are forwarded as-is; the SDK does NOT narrow
+     * per media (a `flip` on a PDF input passes SDK validation but the server
+     * rejects it — documents rotate only). The transform op is `availability:
+     * planned` today, so workflow-create returns `feature_not_available` (422)
+     * until the per-media Lambdas ship. A no-op (`rotate:0` + `flip:none`) is
+     * rejected server-side as `invalid_options`.
+     */
+    transform(options = {}) {
+        validateVerbOptions('transform', options);
+        const wire = {};
+        for (const [key, value] of Object.entries(options)) {
+            if (value !== undefined)
+                wire[key] = value;
+        }
+        return this.withStep({ opType: 'transform', 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
@@ -591,7 +815,8 @@ export class Recipe {
      * (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
+     * `overlay_width`, or `overlays[]` for the multi-overlay stack). Returns a
+     * {@link WatermarkedRecipe} (chain post-watermark
      * `compress`/`convert`/`thumbnail`, then `run`/`submit`). Distinct from
      * {@link textWatermark} (single-input text overlay).
      */
@@ -623,10 +848,25 @@ export class Recipe {
      */
     toWorkflowPayload(fileId, callbackUrl) {
         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 };
-        return callbackUrl === undefined ? { jobs: [job] } : { jobs: [job], callback_url: callbackUrl };
+        // Split at any `sole_op` boundary into a `job_output`-linked chain (IQc01rj0);
+        // a chain with no sole_op stays a single byte-identical job. Job key order
+        // (id?, source, operations) matches the PHP `toWire()` — byte-identical JSON.
+        const jobs = _splitSingleInputJobs(operations, fileId);
+        return callbackUrl === undefined ? { jobs } : { jobs, callback_url: callbackUrl };
+    }
+    /**
+     * Trigger the per-step lowering purely for its validation side effects
+     * (route honoring, planned / out-of-enum values, `media_unknown`), discarding
+     * the result. Called BEFORE uploading bytes so a route-invalid recipe fails
+     * fast instead of after the upload is spent — parity with PHP
+     * `assertOperationsLowerable`. Lowering reads only `steps` + the input token,
+     * not the upload id, so this is a faithful preflight (0azjb6Rg).
+     */
+    assertOperationsLowerable() {
+        const ops = this.steps.map((step, i) => this.lowerStep(step, i));
+        // Also run the sole_op split so a multi-sole_op recipe fails pre-upload
+        // (IQc01rj0). The placeholder id is discarded — only the throw matters.
+        _splitSingleInputJobs(ops, 'preflight');
     }
     /** The result-addressing key passed to `file()`, or undefined. */
     key() {
@@ -670,54 +910,43 @@ export class Recipe {
         if (this.client === undefined) {
             throw new GislConfigError('Recipe.run() requires a client; build the recipe via gisl().file(...) rather than constructing Recipe directly.', { reason: 'no_client' });
         }
-        const deadline = Date.now() + _parseMaxWait(options.maxWait ?? 300_000);
+        const deadline = Date.now() + _parseMaxWait(options.maxWait ?? 600_000);
         // 1+2. Upload (when required) + create the workflow. Shared with submit()
         // (which passes a webhook → callback_url). run() passes no webhook.
         const created = await this._uploadAndCreate(undefined, deadline, onProgress, signal, options.probeBeforeCreate, options.probeTimeoutMs);
-        // 3. Wait to terminal status — SSE first, poll on a genuine SSE error.
-        // Caller-aborted + deadline-elapsed errors MUST propagate (not transient).
-        let finalStatus;
-        try {
-            finalStatus = await _consumeSseToTerminal(this.client, {
-                workflowId: created.workflowId,
-                deadline,
-                signal,
-                onProgress,
-            });
-        }
-        catch (err) {
-            // TDqmkWpX: poll-fallback ONLY on a clean SSE stream-end
-            // (SseEndedWithoutTerminal) or a typed transport error (GislNetworkError).
-            // Everything else — caller-deadline, abort, an API error from /events, an
-            // onProgress callback throw (propagates as-is, NOT wrapped), anything
-            // unexpected — MUST propagate; re-issuing the same doomed request via poll
-            // would mask it. Mirrors the PHP BuilderInternals::awaitTerminal sealed-
-            // marker discipline.
-            if (!(err instanceof SseEndedWithoutTerminal || err instanceof GislNetworkError)) {
-                throw err;
-            }
-            finalStatus = await _pollToTerminal(this.client, {
-                workflowId: created.workflowId,
-                deadline,
-                signal,
-                pollIntervalMs: options.pollIntervalMs,
-            });
-        }
+        // 3. Wait to terminal status — SSE first, poll on a genuine SSE error
+        // (or poll-direct when `useSSE: false`). Caller-aborted + deadline-elapsed
+        // errors MUST propagate (not transient) — see _awaitTerminal.
+        const finalStatus = await _awaitTerminal(this.client, {
+            workflowId: created.workflowId,
+            deadline,
+            signal,
+            onProgress,
+            pollIntervalMs: options.pollIntervalMs,
+            useSSE: options.useSSE ?? true,
+        });
         // 4. Fetch downloads. The maxWait deadline covers upload + create + wait +
         // downloads, so check before issuing the request (mirrors builder.ts).
         if (Date.now() >= deadline) {
-            throw new GislTimeoutError(`Workflow ${created.workflowId} reached terminal status but maxWait elapsed before downloads could be fetched`);
+            throw new GislTimeoutError(`Workflow ${created.workflowId} reached terminal status but maxWait elapsed before downloads could be fetched`, created.workflowId);
         }
         const downloads = await this.client.getWorkflowDownloads(created.workflowId);
         // TDqmkWpX: re-check AFTER the downloads fetch so a slow getWorkflowDownloads
         // cannot return a success past the advertised maxWait deadline.
         if (Date.now() >= deadline) {
-            throw new GislTimeoutError(`Workflow ${created.workflowId} downloads fetch completed after maxWait elapsed`);
+            throw new GislTimeoutError(`Workflow ${created.workflowId} downloads fetch completed after maxWait elapsed`, created.workflowId);
         }
         // Download URLs from getWorkflowDownloads are pre-signed and require no SDK
         // auth, so the downloader issues a plain unauthenticated fetch.
         const downloader = new LazyHttpDownloader();
-        return projectDownloadsToRunResult(created.workflowId, finalStatus, downloads.downloads, this.recipeKey ?? null, downloader);
+        // A single-input `sole_op` split (IQc01rj0, e.g. textWatermark().compress())
+        // produces a job chain — project ONLY the terminal deliverable, filtering the
+        // intermediate sole_op artifact (mirrors the merge/watermark terminal filter
+        // and Handle.project so submit()/reattach agree with run()).
+        const runDownloads = isSoleOpChainStatus(finalStatus)
+            ? downloads.downloads.filter((d) => d.ref === soleOpChainDeliverableRef(finalStatus))
+            : downloads.downloads;
+        return projectDownloadsToRunResult(created.workflowId, finalStatus, runDownloads, this.recipeKey ?? null, downloader);
     }
     /**
      * Fire-and-forget the recipe: upload the input (when required), create the
@@ -742,7 +971,7 @@ export class Recipe {
         // submit() is fire-and-forget — NO whole-run deadline. The upload may be
         // large (a multi-GB master, example 12) and is bounded by the HTTP client's
         // own request timeout, not an arbitrary submit-side cap. Pass `undefined`
-        // so the post-upload deadline check is skipped: a 300s cap here would throw
+        // so the post-upload deadline check is skipped: a 600s cap here would throw
         // on a slow-but-successful big upload before createWorkflow (codex).
         const created = await this._uploadAndCreate(webhook, undefined, undefined, undefined, options?.probeBeforeCreate, options?.probeTimeoutMs);
         return new Handle(created.workflowId, created.webhookSecret != null ? created.webhookSecret : undefined, this.client, this.recipeKey ?? null);
@@ -758,6 +987,13 @@ export class Recipe {
      * slow upload must not proceed to createWorkflow past the deadline.
      */
     async _uploadAndCreate(webhook, deadline, onProgress, signal, probeBeforeCreate, probeTimeoutMs) {
+        // 0. Preflight the operation lowering BEFORE any upload so a route-invalid
+        // recipe (an unhonored / planned / out-of-enum option, or media_unknown on a
+        // bare upload-id input) fails fast instead of after the upload bytes are
+        // spent — parity with PHP's uploadAndCreate (0azjb6Rg). Lowering does not
+        // depend on the upload id, so a clean preflight guarantees the real
+        // toWorkflowPayload() lowering below also succeeds.
+        this.assertOperationsLowerable();
         // 1. Resolve the upload id. A pre-uploaded id skips the upload entirely;
         // a path / blob is uploaded now, emitting {phase:'upload'} progress.
         let fileId;
@@ -897,6 +1133,15 @@ export class Recipe {
                     `(${resolved.inputToken} → ${requested ?? resolved.inputToken}). ` +
                     'Check it applies to this format/route combination.', { reason: 'option_not_on_route', conflictingFields: [key] });
             }
+            // Enum-membership gate (rtkzl9gr): reject a value outside the option's
+            // enum before upload (e.g. `metadata: 'keep'` on avif/svg, whose enum is
+            // ['strip','all']). same_format only — the compress option enums apply
+            // definitionally there; a format_change routes via convert, whose enums
+            // may differ, so we leave it to the (conservative) planned gate.
+            if (resolved.route === 'same_format' && isUnknownEnumValue(resolved.inputToken, key, value)) {
+                throw new GislConfigError(`output(): '${key}: ${String(value)}' is not an accepted value for '${key}' on ` +
+                    `'${resolved.inputToken}' images. Check the values this format's route accepts.`, { reason: 'invalid_option_value', 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] });
             }
@@ -1204,8 +1449,8 @@ function _resolveWatermarkWireOp(base) {
             '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' });
+    throw new GislConfigError(`watermark does not support ${media} base files — overlay watermarking targets image or video bases. ` +
+        'textWatermark() is image-only, so it is not an alternative for document or audio bases.', { reason: 'unsupported_media' });
 }
 /**
  * Validate a watermark overlay locally: the overlay role is always an IMAGE.
@@ -1221,8 +1466,9 @@ function _validateWatermarkOverlay(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).
+    // Watermark options (anchor/opacity/margin_x/margin_y/overlay_width, or the
+    // multi-overlay overlays[] stack) 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 };
 }
@@ -1361,6 +1607,10 @@ export class FilesRecipe {
     thumbnail(options) {
         return this.withStep(this.baseRecipe().thumbnail(options));
     }
+    /** Apply the same geometric transform (rotate/flip) to every input. Validated via the base {@link Recipe}. */
+    transform(options = {}) {
+        return this.withStep(this.baseRecipe().transform(options));
+    }
     /** 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));
@@ -1421,7 +1671,7 @@ export class FilesRecipe {
     toWorkflowPayload(fileIds, callbackUrl) {
         const jobs = this.inputs.map((input, i) => {
             const single = new Recipe(input, undefined, this.steps, this.presetDefaults, this.scopedPresetDefaults);
-            const oneJob = single.toWorkflowPayload(fileIds[i]).jobs[0];
+            const oneJob = _nestedSingleJob(single.toWorkflowPayload(fileIds[i]), 'fan-out');
             // Key order (id, source, operations) matches the PHP `toWire()` so the
             // JSON-string serialisation is byte-identical across languages.
             return { id: `file-${i}`, source: oneJob.source, operations: oneJob.operations };
@@ -1449,42 +1699,30 @@ export class FilesRecipe {
         if (this.client === undefined) {
             throw new GislConfigError('FilesRecipe.run() requires a client; build the fan-out via gisl().files(...) rather than constructing FilesRecipe directly.', { reason: 'no_client' });
         }
-        const deadline = Date.now() + _parseMaxWait(options.maxWait ?? 300_000);
+        const deadline = Date.now() + _parseMaxWait(options.maxWait ?? 600_000);
         // 1+2. Upload EVERY input + create ONE multi-job workflow. Shared with
         // submit() (which passes a webhook → callback_url and no deadline).
         const created = await this._uploadAllAndCreate(undefined, deadline, onProgress, signal, options.probeBeforeCreate, options.probeTimeoutMs);
         // 3. Wait to terminal status — SSE first, poll on a genuine SSE error.
         // `partially_failed` is a normal terminal state here (the helper treats it
         // as terminal); only caller-aborted / deadline / API errors propagate.
-        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,
-            });
-        }
+        const finalStatus = await _awaitTerminal(this.client, {
+            workflowId: created.workflowId,
+            deadline,
+            signal,
+            onProgress,
+            pollIntervalMs: options.pollIntervalMs,
+            useSSE: options.useSSE ?? true,
+        });
         // 4. Fetch downloads + project per-job into the partitioned RunResult.
         if (Date.now() >= deadline) {
-            throw new GislTimeoutError(`Workflow ${created.workflowId} reached terminal status but maxWait elapsed before downloads could be fetched`);
+            throw new GislTimeoutError(`Workflow ${created.workflowId} reached terminal status but maxWait elapsed before downloads could be fetched`, created.workflowId);
         }
         const downloads = await this.client.getWorkflowDownloads(created.workflowId);
         // TDqmkWpX: re-check AFTER the downloads fetch so a slow getWorkflowDownloads
         // cannot return a success past the advertised maxWait deadline.
         if (Date.now() >= deadline) {
-            throw new GislTimeoutError(`Workflow ${created.workflowId} downloads fetch completed after maxWait elapsed`);
+            throw new GislTimeoutError(`Workflow ${created.workflowId} downloads fetch completed after maxWait elapsed`, created.workflowId);
         }
         // keyByRef maps each job ref ("file-{i}") to the partition key. Today the
         // key is just the index string; the Map seam leaves room for the FF3b
@@ -1569,9 +1807,10 @@ export class FilesRecipe {
  *
  * **Lowering (one workflow):** each input is uploaded once and wrapped in its
  * own single-input `passthrough` source job (`src_N`); the `merge` job consumes
- * those via `job_output` inputs (array order = play order) and carries the merge
- * op FIRST in its `operations[]`, followed by any post-combine ops (compress /
- * convert / thumbnail) so they run on the merged output in the same job. The
+ * those via `job_output` inputs (array order = play order). `merge` is
+ * `sole_op` (ADR-0025), so it is the ONLY op in its job; any post-combine ops
+ * (compress / convert / thumbnail / transform) lower into a downstream `post`
+ * job that consumes the merged output via `job_output`. The
  * merge-level wire options reuse {@link wireMergeOptions} so a fluent merge
  * lowers identically to the operation-first `client.merge()`.
  *
@@ -1621,11 +1860,21 @@ export class MergedRecipe {
         }
         return this.withStep({ opType: 'thumbnail', options: wire });
     }
+    /** Geometric transform (rotate/flip) of the merged output. Passthrough; see {@link Recipe.transform}. */
+    transform(options = {}) {
+        validateVerbOptions('transform', options);
+        const wire = {};
+        for (const [key, value] of Object.entries(options)) {
+            if (value !== undefined)
+                wire[key] = value;
+        }
+        return this.withStep({ opType: 'transform', options: wire });
+    }
     /**
      * Lower to the merge DAG: one `passthrough` source job per input + one
-     * `merge` job whose `operations[]` is `[merge, ...post-combine ops]`. The
-     * merge job's `inputs[]` consume the source jobs via `job_output` in input
-     * (play) order.
+     * `merge` job whose `operations[]` is exactly `[merge]` (sole_op). The merge
+     * job's `inputs[]` consume the source jobs via `job_output` in input (play)
+     * order; any post-combine ops lower into a downstream `post` job.
      *
      * @internal Consumed by {@link run} (after uploading all inputs), {@link submit}
      *   (with a webhook), and the cross-language parity harness (with fixed ids).
@@ -1641,12 +1890,19 @@ export class MergedRecipe {
             sourceJobs.push({ id: srcId, source: uploadSource(fileId), operations: [{ type: 'passthrough' }] });
             inputs.push({ source: jobOutputSource(srcId) });
         });
-        const operations = [
-            { type: 'merge', options: wireMergeOptions(this.mergeOptions, mediaKind) },
-            ...this.lowerPostSteps(mediaKind),
-        ];
-        const mergeJob = { id: 'merge', inputs, operations };
+        // `merge` is `sole_op` (ADR-0025): the op MUST be alone in its job.
+        // Post-merge steps lower into a DOWNSTREAM job (see {@link _POST_STEP_JOB_REF})
+        // that consumes the merge output via `job_output`. PIiUit28.
+        const mergeJob = {
+            id: 'merge',
+            inputs,
+            operations: [{ type: 'merge', options: wireMergeOptions(this.mergeOptions, mediaKind) }],
+        };
         const jobs = [...sourceJobs, mergeJob];
+        const postOps = this.lowerPostSteps(mediaKind);
+        if (postOps.length > 0) {
+            jobs.push({ id: _POST_STEP_JOB_REF, source: jobOutputSource('merge'), operations: postOps });
+        }
         return callbackUrl === undefined ? { jobs } : { jobs, callback_url: callbackUrl };
     }
     /** The number of inputs being combined (introspection / tests). */
@@ -1672,41 +1928,31 @@ export class MergedRecipe {
         if (this.client === undefined) {
             throw new GislConfigError('MergedRecipe.run() requires a client; build the merge via gisl().files(...).merge(...) rather than constructing MergedRecipe directly.', { reason: 'no_client' });
         }
-        const deadline = Date.now() + _parseMaxWait(options.maxWait ?? 300_000);
+        const deadline = Date.now() + _parseMaxWait(options.maxWait ?? 600_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,
-            });
-        }
+        const finalStatus = await _awaitTerminal(this.client, {
+            workflowId: created.workflowId,
+            deadline,
+            signal,
+            onProgress,
+            pollIntervalMs: options.pollIntervalMs,
+            useSSE: options.useSSE ?? true,
+        });
         if (Date.now() >= deadline) {
-            throw new GislTimeoutError(`Workflow ${created.workflowId} reached terminal status but maxWait elapsed before downloads could be fetched`);
+            throw new GislTimeoutError(`Workflow ${created.workflowId} reached terminal status but maxWait elapsed before downloads could be fetched`, created.workflowId);
         }
         const downloads = await this.client.getWorkflowDownloads(created.workflowId);
         // TDqmkWpX: re-check AFTER the downloads fetch so a slow getWorkflowDownloads
         // cannot return a success past the advertised maxWait deadline.
         if (Date.now() >= deadline) {
-            throw new GislTimeoutError(`Workflow ${created.workflowId} downloads fetch completed after maxWait elapsed`);
-        }
-        // Project ONLY the merge job's output — the `src_*` passthrough jobs
-        // re-expose the raw uploads, which are plumbing, not the deliverable
-        // (mirrors the operation-first merge.ts `ref === 'merge'` filter + PHP).
-        const mergeDownloads = downloads.downloads.filter((d) => d.ref === 'merge');
+            throw new GislTimeoutError(`Workflow ${created.workflowId} downloads fetch completed after maxWait elapsed`, created.workflowId);
+        }
+        // Project ONLY the terminal deliverable — the `src_*` passthrough jobs
+        // re-expose the raw uploads (plumbing). Post-merge steps lower into the
+        // downstream `_POST_STEP_JOB_REF` job, which is then the deliverable;
+        // otherwise the `merge` job is (mirrors merge.ts + PHP).
+        const outputRef = this.postSteps.length > 0 ? _POST_STEP_JOB_REF : 'merge';
+        const mergeDownloads = downloads.downloads.filter((d) => d.ref === outputRef);
         const downloader = new LazyHttpDownloader();
         return projectDownloadsToRunResult(created.workflowId, finalStatus, mergeDownloads, null, downloader);
     }
@@ -1895,36 +2141,24 @@ export class ArchivedRecipe {
         if (this.client === undefined) {
             throw new GislConfigError('ArchivedRecipe.run() requires a client; build the bundle via gisl().files(...).archive(...) rather than constructing ArchivedRecipe directly.', { reason: 'no_client' });
         }
-        const deadline = Date.now() + _parseMaxWait(options.maxWait ?? 300_000);
+        const deadline = Date.now() + _parseMaxWait(options.maxWait ?? 600_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,
-            });
-        }
+        const finalStatus = await _awaitTerminal(this.client, {
+            workflowId: created.workflowId,
+            deadline,
+            signal,
+            onProgress,
+            pollIntervalMs: options.pollIntervalMs,
+            useSSE: options.useSSE ?? true,
+        });
         if (Date.now() >= deadline) {
-            throw new GislTimeoutError(`Workflow ${created.workflowId} reached terminal status but maxWait elapsed before downloads could be fetched`);
+            throw new GislTimeoutError(`Workflow ${created.workflowId} reached terminal status but maxWait elapsed before downloads could be fetched`, created.workflowId);
         }
         const downloads = await this.client.getWorkflowDownloads(created.workflowId);
         // TDqmkWpX: re-check AFTER the downloads fetch so a slow getWorkflowDownloads
         // cannot return a success past the advertised maxWait deadline.
         if (Date.now() >= deadline) {
-            throw new GislTimeoutError(`Workflow ${created.workflowId} downloads fetch completed after maxWait elapsed`);
+            throw new GislTimeoutError(`Workflow ${created.workflowId} downloads fetch completed after maxWait elapsed`, created.workflowId);
         }
         // Project ONLY the archive job's output — the `src_*` passthrough jobs
         // re-expose the raw uploads, which are plumbing, not the deliverable.
@@ -1996,7 +2230,8 @@ export class ArchivedRecipe {
  * `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
+ * `compress`/`convert`/`thumbnail`/`transform` steps lower into a downstream
+ * `post` job on the watermark output (`image_watermark` is `sole_op`). Mirrors
  * {@link MergedRecipe}. `textWatermark` is intentionally NOT a post-verb here.
  */
 export class WatermarkedRecipe {
@@ -2046,11 +2281,22 @@ export class WatermarkedRecipe {
         }
         return this.withStep({ opType: 'thumbnail', options: wire });
     }
+    /** Geometric transform (rotate/flip) of the watermarked output. Passthrough; see {@link Recipe.transform}. */
+    transform(options = {}) {
+        validateVerbOptions('transform', options);
+        const wire = {};
+        for (const [key, value] of Object.entries(options)) {
+            if (value !== undefined)
+                wire[key] = value;
+        }
+        return this.withStep({ opType: 'transform', 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
+     * them via `job_output` (role base/overlay). The watermark op is `sole_op`
+     * (ADR-0025), so `operations[]` is exactly `[image_watermark|video_watermark]`;
+     * any post-watermark ops lower into a downstream `post` job. `fileIds` is
      * `[baseId, overlayId]` (upload order). Throws pre-lowering if the base media
      * is undetectable/unsupported (the planned-op gate).
      *
@@ -2062,12 +2308,12 @@ export class WatermarkedRecipe {
         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
+            ? _nestedSingleJob(new Recipe(this.baseInput, undefined, this.baseSteps, this.presetDefaults, this.scopedPresetDefaults)
+                .toWorkflowPayload(baseId), 'watermark base').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
+            ? _nestedSingleJob(this.overlay.toWorkflowPayload(overlayId), 'watermark overlay').operations
             : [{ type: 'passthrough' }];
         // Key order (id, source, operations) matches PHP toWire() — byte-identical JSON.
         const srcBase = { id: 'src_0', source: uploadSource(baseId), operations: baseOps };
@@ -2076,12 +2322,20 @@ export class WatermarkedRecipe {
             { 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 };
+        // `image_watermark` / `video_watermark` are `sole_op` (ADR-0025): the op
+        // MUST be alone in its job. Post-watermark steps lower into a DOWNSTREAM
+        // job (see {@link _POST_STEP_JOB_REF}) that consumes the watermark output
+        // via `job_output`. PIiUit28.
+        const watermarkJob = {
+            id: 'watermark',
+            inputs,
+            operations: [_lowerWatermarkOp(wireOp, this.watermarkOptions)],
+        };
         const jobs = [srcBase, srcOverlay, watermarkJob];
+        const postOps = this.lowerPostSteps(wireOp);
+        if (postOps.length > 0) {
+            jobs.push({ id: _POST_STEP_JOB_REF, source: jobOutputSource('watermark'), operations: postOps });
+        }
         return callbackUrl === undefined ? { jobs } : { jobs, callback_url: callbackUrl };
     }
     /** The number of post-watermark ops chained so far (introspection / tests). */
@@ -2100,38 +2354,29 @@ export class WatermarkedRecipe {
         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 deadline = Date.now() + _parseMaxWait(options.maxWait ?? 600_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,
-            });
-        }
+        const finalStatus = await _awaitTerminal(this.client, {
+            workflowId: created.workflowId,
+            deadline,
+            signal,
+            onProgress,
+            pollIntervalMs: options.pollIntervalMs,
+            useSSE: options.useSSE ?? true,
+        });
         if (Date.now() >= deadline) {
-            throw new GislTimeoutError(`Workflow ${created.workflowId} reached terminal status but maxWait elapsed before downloads could be fetched`);
+            throw new GislTimeoutError(`Workflow ${created.workflowId} reached terminal status but maxWait elapsed before downloads could be fetched`, created.workflowId);
         }
         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');
+            throw new GislTimeoutError(`Workflow ${created.workflowId} downloads fetch completed after maxWait elapsed`, created.workflowId);
+        }
+        // Project ONLY the terminal deliverable — the `src_*` passthrough jobs
+        // re-expose the raw base/overlay uploads (plumbing). When post-watermark
+        // steps were chained they lowered into the downstream `_POST_STEP_JOB_REF`
+        // job, which is now the deliverable; otherwise the `watermark` job is.
+        const outputRef = this.postSteps.length > 0 ? _POST_STEP_JOB_REF : 'watermark';
+        const watermarkDownloads = downloads.downloads.filter((d) => d.ref === outputRef);
         const downloader = new LazyHttpDownloader();
         return projectDownloadsToRunResult(created.workflowId, finalStatus, watermarkDownloads, null, downloader);
     }
@@ -2200,3 +2445,275 @@ export class WatermarkedRecipe {
         return new WatermarkedRecipe(this.baseInput, this.baseSteps, this.overlay, this.watermarkOptions, [...this.postSteps, step], this.presetDefaults, this.scopedPresetDefaults, this.client);
     }
 }
+/**
+ * Identity key for batch cross-entry upload dedupe — mirrors the merge
+ * builder's `assetIdentity` (`merge.ts`). Two batch entries whose inputs share
+ * an identity upload ONCE and point both jobs at the shared fileId. `path` uses
+ * the EXACT caller-provided string (no trim / normalise / case-fold, so
+ * `'./a.jpg'` and `'/abs/a.jpg'` do NOT dedupe — by design); `blob` uses
+ * referential identity via a run-local token map (two distinct-but-equal Blobs
+ * still upload twice); `uploadId` uses the fileId itself (already upload-free,
+ * so deduping it is a pure no-op). `blobTokens` is threaded in so a single
+ * planning pass shares one token space.
+ */
+function inputIdentity(input, blobTokens) {
+    switch (input.kind) {
+        case 'path':
+            return `path:${input.path}`;
+        case 'uploadId':
+            return `id:${input.fileId}`;
+        case 'blob': {
+            let token = blobTokens.get(input.blob);
+            if (token === undefined) {
+                token = blobTokens.size;
+                blobTokens.set(input.blob, token);
+            }
+            return `blob:${token}`;
+        }
+    }
+}
+/**
+ * The keyed multi-recipe batch builder (FF7 / MFaCjL8d). `client.batch([r1, r2, …])`
+ * runs N DISTINCT single-input keyed {@link Recipe}s as ONE workflow; the
+ * partitioned {@link RunResult} addresses each entry's outputs by the caller key
+ * given at `client.file(input, key)` time (`res.byKey('hero')`), and one failed
+ * entry lands in `failed` without sinking the rest.
+ *
+ * **v1 scope (locked):** `.run()` only (no `submit()` / reattach — a follow-up);
+ * single-input {@link Recipe} entries only — the multi-input builders
+ * ({@link FilesRecipe}, {@link MergedRecipe}, {@link WatermarkedRecipe},
+ * {@link ArchivedRecipe}) are REJECTED pre-upload. Cross-entry upload dedupe
+ * IS applied (1LwSJcz1): two entries sourcing the SAME input (by
+ * {@link inputIdentity}) upload ONCE and share the resulting fileId —
+ * correctness-neutral (same bytes → same per-job output), it only elides
+ * redundant uploads. Observable caveat: `onProgress` upload-phase events drop
+ * to one-per-UNIQUE input rather than one-per-entry.
+ *
+ * **Lowering (one workflow):** for each entry `i`, lower its single job via
+ * {@link Recipe.toWorkflowPayload} and re-id it `b{i}` — a POSITIONAL namespace
+ * DISTINCT from the fan-out `file-{i}` / merge-archive-watermark `src_{i}` refs so
+ * a future reattach can't misdetect the wire as a fan-out / merge. `keyByRef`
+ * maps each `b{i}` ref to that entry's caller key, so
+ * {@link projectMultiJobToRunResult} partitions per entry (1 job ↔ 1 key:
+ * `completed` → `succeeded`, else → `failed` with a {@link GislItemFailedError}).
+ *
+ * **Immutability:** the ctor is CLIENT-ONLY (the ordered entries + the client) —
+ * entries are already-built Recipes that captured their own preset defaults at
+ * `client.file(...)` time, so batch never re-plumbs
+ * presetDefaults/scopedPresetDefaults. Mirrors the PHP `BatchRecipe`.
+ */
+export class BatchRecipe {
+    client;
+    recipes;
+    constructor(recipes, client) {
+        this.client = client;
+        // DEFENSIVE COPY (TS-only): snapshot the caller's array so a later mutation
+        // of it (splice/push after construction, or during an in-flight run()) can't
+        // desync the uploaded fileIds from the lowered jobs/keys — validation,
+        // upload, lowering + keyByRef all iterate this frozen order. PHP is
+        // value-semantics-safe already (arrays copy on pass).
+        this.recipes = [...recipes];
+    }
+    /**
+     * Execute the batch end-to-end: validate + lowering-preflight EVERY entry
+     * BEFORE any upload, upload each entry's input, create ONE multi-job workflow
+     * (one `b{i}` job per entry), await a terminal state (SSE with poll fallback,
+     * honouring `useSSE`), then partition the per-job downloads into a keyed
+     * {@link RunResult}. `partially_failed` is a NORMAL terminal state here — the
+     * completed entries land in `succeeded`, the rest in `failed`.
+     *
+     * Requires a client bound at construction time — `gisl().batch([...])` wires
+     * it; a directly-constructed {@link BatchRecipe} (e.g. a lowering-only test)
+     * throws {@link GislConfigError}. Mirrors the fan-out {@link FilesRecipe.run}.
+     */
+    async run(options = {}) {
+        const signal = options.signal;
+        const onProgress = options.onProgress;
+        if (this.client === undefined) {
+            throw new GislConfigError('BatchRecipe.run() requires a client; build the batch via gisl().batch([...]) rather than constructing BatchRecipe directly.', { reason: 'no_client' });
+        }
+        // Validate + lowering-preflight EVERY entry BEFORE any upload: a structural
+        // violation (bad type / missing / duplicate key) or an invalid lowering
+        // aborts here so no input uploads. NOTE — like FilesRecipe, TS does NOT
+        // pre-check path readability: a nonexistent/unreadable path surfaces INSIDE
+        // uploadFile during upload, so an earlier entry's input may already be
+        // uploaded when a later entry's path fails. (PHP pre-checks path/resource
+        // uploadability; this TS/PHP difference mirrors each language's existing
+        // FilesRecipe behavior and is intentionally NOT closed here — a TS
+        // path-precheck would diverge batch from FilesRecipe.)
+        this.validatePreUpload();
+        const deadline = Date.now() + _parseMaxWait(options.maxWait ?? 600_000);
+        // 1+2. Upload each entry's input + create ONE multi-job workflow. batch v1
+        // sends NO webhook (run()-only), so `callback_url` is omitted from the
+        // payload (the closure receives `callbackUrl` undefined).
+        // Dedupe cross-entry uploads: collapse to the first-appearance-unique input
+        // list, upload each unique input ONCE, then expand the returned unique
+        // fileIds back to one-per-entry (in entry order) so the b{i} jobs + keyByRef
+        // stay N-length and correctness-neutral. See planUploads / inputIdentity.
+        const { uniqueInputs, entryToUnique } = this.planUploads();
+        const created = await _uploadInputsAndCreate(this.client, uniqueInputs, (uniqueFileIds, callbackUrl) => this.toWorkflowPayload(entryToUnique.map((u) => uniqueFileIds[u]), callbackUrl), {
+            webhook: undefined,
+            deadline,
+            onProgress,
+            signal,
+            probeBeforeCreate: options.probeBeforeCreate,
+            probeTimeoutMs: options.probeTimeoutMs,
+            uploadsLabel: 'batch',
+            workflowLabel: 'the batch workflow',
+        });
+        // 3. Wait to terminal status — SSE first, poll on a genuine SSE error (or
+        // poll-direct when `useSSE: false`). Caller-aborted + deadline errors
+        // propagate (not transient) — see _awaitTerminal.
+        const finalStatus = await _awaitTerminal(this.client, {
+            workflowId: created.workflowId,
+            deadline,
+            signal,
+            onProgress,
+            pollIntervalMs: options.pollIntervalMs,
+            useSSE: options.useSSE ?? true,
+        });
+        // 4. Fetch downloads + project per-job into the keyed RunResult.
+        if (Date.now() >= deadline) {
+            throw new GislTimeoutError(`Workflow ${created.workflowId} reached terminal status but maxWait elapsed before downloads could be fetched`, created.workflowId);
+        }
+        const downloads = await this.client.getWorkflowDownloads(created.workflowId);
+        // TDqmkWpX: re-check AFTER the downloads fetch so a slow getWorkflowDownloads
+        // cannot return a success past the advertised maxWait deadline.
+        if (Date.now() >= deadline) {
+            throw new GislTimeoutError(`Workflow ${created.workflowId} downloads fetch completed after maxWait elapsed`, created.workflowId);
+        }
+        const downloader = new LazyHttpDownloader();
+        return projectMultiJobToRunResult(created.workflowId, finalStatus, downloads.downloads, this.keyByRef(), downloader);
+    }
+    /**
+     * Lower the batch to ONE multi-job workflow-create payload against a list of
+     * resolved upload ids (one per entry, in entry order). Each entry `i` becomes
+     * ONE job re-id'd `b{i}` carrying that entry's lowered `source` + `operations`.
+     * Composes the single-file {@link Recipe.toWorkflowPayload} per entry so each
+     * keeps its own media-hint + preset resolution and lowering logic is not
+     * duplicated. `callback_url` is built in ONLY when a webhook is supplied
+     * (batch v1 run() supplies none, so it is omitted).
+     *
+     * @internal Consumed by {@link run} (after uploading) and the cross-language
+     *   golden-payload lowering test (with fixed ids). Not caller-facing.
+     */
+    toWorkflowPayload(fileIds, callbackUrl) {
+        const jobs = this.recipes.map((entry, i) => {
+            const oneJob = _nestedSingleJob(entry.toWorkflowPayload(fileIds[i]), 'batch');
+            // Positional id `b{i}` — a namespace DISTINCT from the fan-out `file-{i}` /
+            // merge `src_{i}` refs. Key order (id, source, operations) matches the PHP
+            // `toWire()` so the JSON serialisation is byte-identical across languages.
+            return { id: `b${i}`, source: oneJob.source, operations: oneJob.operations };
+        });
+        return callbackUrl === undefined ? { jobs } : { jobs, callback_url: callbackUrl };
+    }
+    /** The number of recipe entries in this batch (introspection / tests). */
+    get recipeCount() {
+        return this.recipes.length;
+    }
+    // ---------------------------------------------------------------------------
+    /**
+     * Validate the batch AND lowering-preflight every entry BEFORE any upload
+     * fires — an invalid entry costs no bandwidth. TWO PASSES (mirrors PHP
+     * `BatchRecipe`'s structural-loop-then-preflight-loop), throwing
+     * {@link GislConfigError}:
+     *  0. empty batch → `no_recipes` (checked first).
+     *  PASS 1 (structural, ALL entries in order):
+     *    - a KNOWN multi-input builder (checked FIRST — they do NOT extend
+     *      {@link Recipe}, so the not-a-Recipe catch-all would otherwise misreport
+     *      them as plain type errors) → `multi_input_recipe_unsupported`;
+     *    - a non-{@link Recipe} entry → `invalid_recipe`;
+     *    - a missing/empty key → `missing_key`;
+     *    - a duplicate key → `duplicate_key`.
+     *  PASS 2 (lowering preflight, ALL entries): lower each entry (via
+     *    {@link Recipe.toWorkflowPayload}) so an invalid lowering throws BEFORE any
+     *    upload, mirroring what {@link FilesRecipe} lowers pre-create.
+     *
+     * Two passes so a batch with MULTIPLE distinct violations throws the SAME
+     * reason regardless of entry order (a structural error anywhere wins over a
+     * lowering error elsewhere) — converging TS + PHP error reporting. The
+     * offending key/index rides the MESSAGE (not `conflictingFields`, which is
+     * reserved for wire FIELD names).
+     */
+    validatePreUpload() {
+        if (this.recipes.length === 0) {
+            throw new GislConfigError('batch() requires at least one recipe. Pass an ordered array of ' +
+                'client.file(input, key).<op>(...) recipes, each with a unique key.', { reason: 'no_recipes' });
+        }
+        // PASS 1 — structural checks across ALL entries in order.
+        const seenKeys = new Set();
+        this.recipes.forEach((rawEntry, i) => {
+            // Treat each entry as unknown for the runtime type guards: the public
+            // signature is ReadonlyArray<Recipe>, but a plain-JS caller can pass
+            // anything, and the multi-input builders are structurally Recipe-adjacent.
+            const entry = rawEntry;
+            // ORDER MATTERS (codex r2 #1): check the KNOWN multi-input builders FIRST.
+            // They do NOT extend Recipe, so the not-a-Recipe catch-all below would
+            // otherwise misreport them as plain caller type errors.
+            if (entry instanceof FilesRecipe ||
+                entry instanceof MergedRecipe ||
+                entry instanceof WatermarkedRecipe ||
+                entry instanceof ArchivedRecipe) {
+                throw new GislConfigError(`batch() entry at index ${i} is a multi-input recipe (${entry.constructor.name}), ` +
+                    'which is not supported in batch v1 — batch accepts only single-input keyed recipes ' +
+                    '(client.file(input, key).<op>(...)). Run the multi-input recipe on its own.', { reason: 'multi_input_recipe_unsupported' });
+            }
+            // THEN the catch-all: not a Recipe at all (null / string / plain object).
+            if (!(entry instanceof Recipe)) {
+                throw new GislConfigError(`batch() entry at index ${i} is not a recipe. Build each entry via ` +
+                    'client.file(input, key).<op>(...) before passing it to batch().', { reason: 'invalid_recipe' });
+            }
+            // Keys are the result address → each entry needs a unique, non-empty key.
+            const key = entry.key();
+            if (key === undefined || key === '') {
+                throw new GislConfigError(`batch() entry at index ${i} has no key. Every batch entry needs a unique non-empty key ` +
+                    "(client.file(input, 'key')) to address its result.", { reason: 'missing_key' });
+            }
+            if (seenKeys.has(key)) {
+                throw new GislConfigError(`batch() has a duplicate key '${key}' (entry at index ${i}). Every batch entry needs a unique key.`, { reason: 'duplicate_key' });
+            }
+            seenKeys.add(key);
+        });
+        // PASS 2 — lowering preflight across ALL entries (each is now known to be a
+        // Recipe). Lower each entry now so an invalid lowering (e.g. an undetectable
+        // input + optimize, an unrepresentable output route) throws BEFORE any
+        // upload. The 'preflight' id is a throwaway placeholder — run() re-lowers
+        // against the real upload ids post-upload.
+        this.recipes.forEach((entry) => {
+            entry.toWorkflowPayload('preflight');
+        });
+    }
+    /**
+     * Collapse the entry inputs to a first-appearance-unique list for cross-entry
+     * upload dedupe: two entries sourcing the SAME input (by {@link inputIdentity})
+     * upload ONCE and share the fileId. Returns the ordered `uniqueInputs` plus an
+     * `entryToUnique` index map (length N, entry order) so {@link run} can expand
+     * the unique fileIds back to one-per-entry before {@link toWorkflowPayload} —
+     * keeping the b{i} refs + {@link keyByRef} N-length and correctness-neutral.
+     */
+    planUploads() {
+        const blobTokens = new Map();
+        const identityToUnique = new Map();
+        const uniqueInputs = [];
+        const entryToUnique = this.recipes.map((entry) => {
+            const input = entry.recipeInput;
+            const id = inputIdentity(input, blobTokens);
+            let uniqueIndex = identityToUnique.get(id);
+            if (uniqueIndex === undefined) {
+                uniqueIndex = uniqueInputs.length;
+                uniqueInputs.push(input);
+                identityToUnique.set(id, uniqueIndex);
+            }
+            return uniqueIndex;
+        });
+        return { uniqueInputs, entryToUnique };
+    }
+    /** Map each `b{i}` job ref to that entry's caller key (validated non-empty). */
+    keyByRef() {
+        const map = new Map();
+        this.recipes.forEach((entry, i) => {
+            map.set(`b${i}`, entry.key() ?? null);
+        });
+        return map;
+    }
+}