@giveitsmaller/sdk 0.20.0 → 0.22.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, dependsOnViolation, 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),
@@ -341,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
@@ -363,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;
     }
@@ -395,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} /
@@ -415,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) {
@@ -694,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() {
@@ -741,7 +910,7 @@ 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);
@@ -759,18 +928,25 @@ export class Recipe {
         // 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
@@ -795,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);
@@ -811,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;
@@ -918,7 +1101,7 @@ export class Recipe {
             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)
+                    if (key === 'output_format' || value === undefined || value === null)
                         continue;
                     if (key !== 'quality') {
                         throw new GislConfigError(`output(): '${key}' needs a detectable input format to route; reference the file by ` +
@@ -939,7 +1122,9 @@ export class Recipe {
         }
         const wireOptions = { output_format: resolved.outputFormatWire };
         for (const [key, value] of Object.entries(step.options)) {
-            if (key === 'output_format' || value === undefined)
+            // Drop a null value (as PHP does) so a null option never reaches the wire
+            // and is treated as absent by the depends_on gate — full null parity (codex).
+            if (key === 'output_format' || value === undefined || value === null)
                 continue;
             if (resolved.planned.has(key)) {
                 throw new GislConfigError(`output(): '${key}' is advertised but not available yet on the ${resolved.route} route ` +
@@ -950,11 +1135,42 @@ 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] });
             }
             wireOptions[key] = value;
         }
+        // quality_preset's contract `depends_on: { encoding_mode: auto_quality }`
+        // (86gAu5Tr) — infer the mode when the caller set NONE so the preset forms a
+        // VALID request. SAME_FORMAT only: encoding_mode is a compress optimiser and
+        // quality_preset isn't honored on a format_change. An explicitly-conflicting
+        // mode is rejected by the general depends_on gate below.
+        if (resolved.route === 'same_format' &&
+            wireOptions.quality_preset !== undefined &&
+            wireOptions.encoding_mode === undefined) {
+            wireOptions.encoding_mode = 'auto_quality';
+        }
+        // General contract `depends_on` validation (ehHU08Hu), scoped per route: the
+        // universal fit→width|height dep runs on BOTH routes (identical in compress +
+        // convert); the encoding_mode-family deps run on same_format only. Subsumes
+        // the 86gAu5Tr auto_quality gate plus target_size_bytes-without-target_size,
+        // fit-without-width/height, and any future compress-image depends_on.
+        const dependency = dependsOnViolation(wireOptions, resolved.route);
+        if (dependency !== undefined) {
+            throw new GislConfigError(dependency.message, {
+                reason: 'invalid_option_combination',
+                conflictingFields: [...dependency.conflictingFields],
+            });
+        }
         return { type: resolved.sourceOp, options: wireOptions };
     }
     /**
@@ -1257,8 +1473,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.
@@ -1274,9 +1490,22 @@ function _validateWatermarkOverlay(overlay) {
     }
 }
 function _lowerWatermarkOp(wireOp, options) {
-    // 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).
+    // `overlays[]` (the multi-overlay stack) is a live contract option but is NOT
+    // reachable through watermark(): the facade composites exactly ONE overlay —
+    // the positional `overlay` (wire source src_1) — so overlays[1..] reference
+    // sources it cannot create, any entry is invalid on a non-image base, and the
+    // contract's `minItems: 1` makes an empty array invalid too. Reject it here at
+    // lowering (mutation-safe — reads the FINAL options, catching a post-watermark()
+    // `opts.overlays = [...]`) and point callers at the single-overlay knobs.
+    // Real multi-overlay stacking is a future feature (Vbbdq9C4).
+    if (options.overlays !== undefined) {
+        throw new GislConfigError("watermark(): 'overlays[]' (multi-overlay stacking) is not supported — watermark() composites a " +
+            'single overlay (the positional overlay argument). Use the top-level anchor / opacity / margin_x / ' +
+            'margin_y / overlay_width options to place it. Multi-overlay stacking is a future feature.', { reason: 'overlays_unsupported', conflictingFields: ['overlays'] });
+    }
+    // The remaining watermark options (anchor/opacity/margin_x/margin_y/
+    // overlay_width) are already wire keys; empty options omit the `options` key
+    // (byte-identical to PHP).
     const wire = { ...options };
     return Object.keys(wire).length === 0 ? { type: wireOp } : { type: wireOp, options: wire };
 }
@@ -1297,6 +1526,14 @@ function _lowerWatermarkOp(wireOp, options) {
  */
 async function _uploadInputsAndCreate(client, inputs, toPayload, opts) {
     const { webhook, deadline, onProgress, signal, probeBeforeCreate, probeTimeoutMs, uploadsLabel, workflowLabel } = opts;
+    // Preflight: lower the composed chains with placeholder ids so a route-invalid
+    // option (or any lowering-time gate — overlays, sole_op split, route/enum) in
+    // ANY input's chain — a watermark base/overlay, a merge/archive member — throws
+    // BEFORE we spend a single upload byte. The multi-input analog of the
+    // single-input Recipe.assertOperationsLowerable preflight (0azjb6Rg); mirrors
+    // PHP. The placeholder ids never reach the wire — the payload is discarded
+    // (T3ltXsou). toWorkflowPayload is pure, so re-lowering at create is cheap.
+    toPayload(inputs.map((_, i) => `preflight_${i}`));
     const fileIds = [];
     // Track each freshly-uploaded input's probe-gate inputs (a pre-uploaded id
     // carries no local mime/size, so it is excluded — never probed).
@@ -1479,7 +1716,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 };
@@ -1507,7 +1744,7 @@ 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);
@@ -1524,13 +1761,13 @@ export class FilesRecipe {
         });
         // 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
@@ -1615,9 +1852,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()`.
  *
@@ -1679,9 +1917,9 @@ export class MergedRecipe {
     }
     /**
      * 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).
@@ -1697,12 +1935,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). */
@@ -1728,7 +1973,7 @@ 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);
         const finalStatus = await _awaitTerminal(this.client, {
             workflowId: created.workflowId,
@@ -1739,18 +1984,20 @@ export class MergedRecipe {
             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);
     }
@@ -1939,7 +2186,7 @@ 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);
         const finalStatus = await _awaitTerminal(this.client, {
             workflowId: created.workflowId,
@@ -1950,13 +2197,13 @@ export class ArchivedRecipe {
             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.
@@ -2028,7 +2275,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 {
@@ -2091,8 +2339,9 @@ export class 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
-     * 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).
      *
@@ -2104,12 +2353,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 };
@@ -2118,12 +2367,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). */
@@ -2142,7 +2399,7 @@ 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);
         const finalStatus = await _awaitTerminal(this.client, {
             workflowId: created.workflowId,
@@ -2153,15 +2410,18 @@ export class WatermarkedRecipe {
             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);
     }
@@ -2327,7 +2587,7 @@ export class BatchRecipe {
         // 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 ?? 300_000);
+        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).
@@ -2359,13 +2619,13 @@ export class BatchRecipe {
         });
         // 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`);
+            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);
         }
         const downloader = new LazyHttpDownloader();
         return projectMultiJobToRunResult(created.workflowId, finalStatus, downloads.downloads, this.keyByRef(), downloader);
@@ -2384,7 +2644,7 @@ export class BatchRecipe {
      */
     toWorkflowPayload(fileIds, callbackUrl) {
         const jobs = this.recipes.map((entry, i) => {
-            const oneJob = entry.toWorkflowPayload(fileIds[i]).jobs[0];
+            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.