@giveitsmaller/sdk 0.20.0 → 0.22.0

package/dist/generated/sdk_spec/enums.d.ts

@@ -63,20 +63,6 @@ export declare const AudioSampleRate: {
     readonly _48000: 48000;
 };
 export type AudioSampleRate = typeof AudioSampleRate[keyof typeof AudioSampleRate];
-export declare const PdfProfile: {
-    readonly Screen: "screen";
-    readonly Ebook: "ebook";
-    readonly Printer: "printer";
-    readonly Prepress: "prepress";
-};
-export type PdfProfile = typeof PdfProfile[keyof typeof PdfProfile];
-export declare const PdfColorspace: {
-    readonly Unchanged: "unchanged";
-    readonly Rgb: "rgb";
-    readonly Cmyk: "cmyk";
-    readonly Grayscale: "grayscale";
-};
-export type PdfColorspace = typeof PdfColorspace[keyof typeof PdfColorspace];
 /** Catalog of every ergonomic enum (canonicalName → wire). */
 export declare const ERGONOMIC_ENUMS: {
     readonly OptimizeFor: {
@@ -135,16 +121,4 @@ export declare const ERGONOMIC_ENUMS: {
         readonly _44100: 44100;
         readonly _48000: 48000;
     };
-    readonly PdfProfile: {
-        readonly Screen: "screen";
-        readonly Ebook: "ebook";
-        readonly Printer: "printer";
-        readonly Prepress: "prepress";
-    };
-    readonly PdfColorspace: {
-        readonly Unchanged: "unchanged";
-        readonly Rgb: "rgb";
-        readonly Cmyk: "cmyk";
-        readonly Grayscale: "grayscale";
-    };
 };

package/dist/generated/sdk_spec/enums.js

@@ -77,20 +77,6 @@ export const AudioSampleRate = {
     _44100: 44100,
     _48000: 48000,
 };
-// PDF Ghostscript preset. Screen = smallest; Ebook = mid; Printer = 300dpi; Prepress = print-production.
-export const PdfProfile = {
-    Screen: "screen",
-    Ebook: "ebook",
-    Printer: "printer",
-    Prepress: "prepress",
-};
-// PDF output color space.
-export const PdfColorspace = {
-    Unchanged: "unchanged",
-    Rgb: "rgb",
-    Cmyk: "cmyk",
-    Grayscale: "grayscale",
-};
 /** Catalog of every ergonomic enum (canonicalName → wire). */
 export const ERGONOMIC_ENUMS = {
     OptimizeFor,
@@ -102,6 +88,4 @@ export const ERGONOMIC_ENUMS = {
     AudioBitrate,
     AudioCodec,
     AudioSampleRate,
-    PdfProfile,
-    PdfColorspace,
 };

package/dist/generated/sdk_spec/errors.d.ts

@@ -1,4 +1,4 @@
-export type ErrorCode = "missing_credentials" | "feature_requires_auth" | "undeclared_asset" | "unused_asset" | "per_input_options_not_supported" | "chain_cardinality_mismatch" | "multipart_part_invalid" | "multipart_part_count_exceeded" | "timeout" | "aborted" | "validation_failed" | "validation_error" | "cyclic_workflow_edges" | "workflow_edge_references_unknown_job" | "reserved_job_id_pattern" | "cyclic_job_output_source_graph" | "auth_failed" | "feature_tier_restricted" | "tier_restriction" | "multipart_session_ownership" | "multipart_session_auth_required" | "multipart_session_not_found" | "upload_not_found" | "workflow_expired" | "balance_exhausted" | "feature_not_available" | "upload_size_exceeds_tier" | "upload_duration_exceeds_tier" | "probe_pending" | "requires_reencode" | "invalid_options" | "invalid_combination" | "missing_dependency" | "unsupported_value" | "type_mismatch" | "upload_failed" | "workflow_failed";
+export type ErrorCode = "missing_credentials" | "feature_requires_auth" | "undeclared_asset" | "unused_asset" | "per_input_options_not_supported" | "chain_cardinality_mismatch" | "multipart_part_invalid" | "multipart_part_count_exceeded" | "timeout" | "aborted" | "validation_failed" | "validation_error" | "cyclic_workflow_edges" | "workflow_edge_references_unknown_job" | "reserved_job_id_pattern" | "cyclic_job_output_source_graph" | "auth_failed" | "feature_tier_restricted" | "tier_restriction" | "multipart_session_ownership" | "multipart_session_auth_required" | "multipart_session_not_found" | "upload_not_found" | "workflow_expired" | "balance_exhausted" | "feature_not_available" | "upload_size_exceeds_tier" | "upload_duration_exceeds_tier" | "probe_pending" | "requires_reencode" | "invalid_options" | "invalid_combination" | "missing_dependency" | "unsupported_value" | "type_mismatch" | "image_dimensions_too_large" | "upload_failed" | "workflow_failed" | "long_form_concurrency_limit_exceeded" | "unprocessable_entity" | "email_same" | "config_error" | "bundle_already_archived" | "fan_out_timeout" | "no_such_key" | "result_not_ready" | "sink_error" | "item_failed";
 export type ErrorCategory = 'api' | 'config' | 'network' | 'auth' | 'validation' | 'chain';
 export type ErrorStatus = 'wired' | 'planned';
 export interface ErrorEntry {

package/dist/generated/sdk_spec/errors.js

@@ -377,7 +377,7 @@ export const ERROR_CODES = Object.freeze({
         status: "wired",
         httpStatus: 422,
         retryable: true,
-        sdkClass: "GislApiError",
+        sdkClass: "GislProbePendingError",
         description: "422 on workflow create — upload probing not yet complete; retry after the upload finishes probing. Wire `error_type: \"probe_pending\"`.",
         metadataSchema: Object.freeze({
             "jobRef": "string",
@@ -467,6 +467,17 @@ export const ERROR_CODES = Object.freeze({
             "actual": "string",
         }),
     }),
+    "image_dimensions_too_large": Object.freeze({
+        code: "image_dimensions_too_large",
+        category: "api",
+        source: "ErrorEnvelope.error",
+        status: "wired",
+        httpStatus: 413,
+        retryable: false,
+        sdkClass: "GislUploadCapExceededError",
+        description: "413 — POST /api/uploads rejected a decodable raster image whose pixel area (width × height) exceeds the configured ceiling (UPLOAD_MAX_IMAGE_PIXELS, default 16 MP), read from the file header before decode (I0Rqj4jo). Wire `IMAGE_DIMENSIONS_TOO_LARGE`; flat ErrorEnvelope (no details[]). A pixel-dimension member of the upload-cap family — GislUploadCapExceededError, alongside the size/duration caps — matching the SDKs' existing status-based 413 dispatch (NOT GislValidationError, which is the structured-422 class). Retry only after downscaling the input.",
+        metadataSchema: Object.freeze({}),
+    }),
     "upload_failed": Object.freeze({
         code: "upload_failed",
         category: "network",
@@ -495,6 +506,142 @@ export const ERROR_CODES = Object.freeze({
             "jobErrors": "array",
         }),
     }),
+    "long_form_concurrency_limit_exceeded": Object.freeze({
+        code: "long_form_concurrency_limit_exceeded",
+        category: "api",
+        source: "ErrorEnvelope.error",
+        status: "wired",
+        httpStatus: 429,
+        retryable: false,
+        sdkClass: "GislLongFormConcurrencyError",
+        description: "429 — the caller's tier long-form concurrency allowance is exhausted. Wire value is UPPERCASE `LONG_FORM_CONCURRENCY_LIMIT_EXCEEDED` (api.yaml:1995); this file's `code:` follows the taxonomy's lowercase convention. Dispatched on the machine `error` code, NOT on the status: a generic infra rate-limit 429 carries a different/absent code and falls through to base GislApiError where retryAfterSeconds applies. Do not widen this entry to the status.",
+        metadataSchema: Object.freeze({
+            "currentTier": "string",
+            "maxDurationSeconds": "number",
+        }),
+    }),
+    "unprocessable_entity": Object.freeze({
+        code: "unprocessable_entity",
+        category: "auth",
+        source: "error_type",
+        status: "wired",
+        httpStatus: 422,
+        retryable: false,
+        sdkClass: "GislAuthRejectionError",
+        description: "422 on an auth-side-effect endpoint (register / verify-email / api-keys) — the request was well-formed but rejected on domain grounds. Dispatched on MEMBERSHIP of AuthRejectionEnvelope.error_type, per ADR-0019.",
+        metadataSchema: Object.freeze({
+            "errorType": "string",
+        }),
+    }),
+    "email_same": Object.freeze({
+        code: "email_same",
+        category: "auth",
+        source: "error_type",
+        status: "wired",
+        httpStatus: 422,
+        retryable: false,
+        sdkClass: "GislAuthRejectionError",
+        description: "422 on profile PATCH — the submitted email matches the current one, so there is nothing to change. Same envelope and sdkClass as unprocessable_entity; separate row because the wire value differs.",
+        metadataSchema: Object.freeze({
+            "errorType": "string",
+        }),
+    }),
+    "config_error": Object.freeze({
+        code: "config_error",
+        category: "config",
+        source: "SDK_local",
+        status: "wired",
+        httpStatus: null,
+        retryable: false,
+        sdkClass: "GislConfigError",
+        description: "Client-side configuration rejected before any request — thrown directly (preset resolver, output() gates), not only as a base class. `reason` carries the discriminator: `unknown_field` and `type_mismatch` are values of THIS field and deliberately have no rows of their own.",
+        metadataSchema: Object.freeze({
+            "reason": "string",
+            "conflictingFields": "array",
+            "resolvedSnapshot": "object",
+            "suggestion": "string",
+        }),
+    }),
+    "bundle_already_archived": Object.freeze({
+        code: "bundle_already_archived",
+        category: "config",
+        source: "SDK_local",
+        status: "planned",
+        httpStatus: null,
+        retryable: false,
+        sdkClass: "GislBundleAlreadyArchivedError",
+        description: "PLANNED — not reachable in any shipped build. Raised when a bundle operation targets an already-archived bundle, once `.bundle()` ships. Do not write handler code against this yet.",
+        metadataSchema: Object.freeze({}),
+    }),
+    "fan_out_timeout": Object.freeze({
+        code: "fan_out_timeout",
+        category: "network",
+        source: "SDK_local",
+        status: "wired",
+        httpStatus: null,
+        retryable: true,
+        sdkClass: "GislFanOutTimeoutError",
+        description: "A fan-out deadline elapsed before all children finished. The three metadata fields are the reason this is declared separately from GislTimeoutError: completedWorkflowIds are the children that DID finish, parentWorkflowId ran to completion before the fan-out began, and the inherited workflowId is the in-flight child — absent on a clean between-children timeout.",
+        metadataSchema: Object.freeze({
+            "completedWorkflowIds": "array",
+            "parentWorkflowId": "string",
+            "workflowId": "string",
+        }),
+    }),
+    "no_such_key": Object.freeze({
+        code: "no_such_key",
+        category: "chain",
+        source: "SDK_local",
+        status: "wired",
+        httpStatus: null,
+        retryable: false,
+        sdkClass: "GislNoSuchKeyError",
+        description: "The caller asked for a mapEach result key that does not exist in the output. NOTE the key itself is NOT captured in metadata today — it is interpolated into the message only, so consumers cannot branch on which key was missing.",
+        metadataSchema: Object.freeze({}),
+    }),
+    "result_not_ready": Object.freeze({
+        code: "result_not_ready",
+        category: "validation",
+        source: "SDK_local",
+        status: "wired",
+        httpStatus: null,
+        retryable: true,
+        sdkClass: "GislResultNotReadyError",
+        description: "The caller read a result before the workflow reached a terminal state. `state` carries the non-terminal status observed.",
+        metadataSchema: Object.freeze({
+            "workflowId": "string",
+            "state": "string",
+        }),
+    }),
+    "sink_error": Object.freeze({
+        code: "sink_error",
+        category: "config",
+        source: "SDK_local",
+        status: "wired",
+        httpStatus: null,
+        retryable: false,
+        sdkClass: "GislSinkError",
+        description: "A caller-supplied output sink could not be used. Branch on `reason` — the values span both caller setup (invalid_directory, duplicate_filename) and runtime write outcomes (write_failed, partial_failure), so the category is a best fit rather than an exact one.",
+        metadataSchema: Object.freeze({
+            "reason": "string",
+        }),
+    }),
+    "item_failed": Object.freeze({
+        code: "item_failed",
+        category: "api",
+        source: "SDK_local",
+        status: "wired",
+        httpStatus: null,
+        retryable: false,
+        sdkClass: "GislItemFailedError",
+        description: "CARRIED, not thrown — an entry in a per-item failed[] collection describing one item's server-side failure. `errorCode` carries the server's own code where present; prefer branching on that over this entry.",
+        metadataSchema: Object.freeze({
+            "key": "string",
+            "state": "string",
+            "errorMessage": "string",
+            "errorCode": "string",
+        }),
+    }),
 });
 export const ERROR_CATEGORIES = Object.freeze({
     api: Object.freeze([
@@ -509,21 +656,30 @@ export const ERROR_CATEGORIES = Object.freeze({
         "upload_duration_exceeds_tier",
         "probe_pending",
         "requires_reencode",
+        "image_dimensions_too_large",
         "workflow_failed",
+        "long_form_concurrency_limit_exceeded",
+        "item_failed",
     ]),
     config: Object.freeze([
         "missing_credentials",
         "feature_requires_auth",
+        "config_error",
+        "bundle_already_archived",
+        "sink_error",
     ]),
     network: Object.freeze([
         "timeout",
         "aborted",
         "upload_failed",
+        "fan_out_timeout",
     ]),
     auth: Object.freeze([
         "auth_failed",
         "multipart_session_ownership",
         "multipart_session_auth_required",
+        "unprocessable_entity",
+        "email_same",
     ]),
     validation: Object.freeze([
         "multipart_part_invalid",
@@ -539,11 +695,13 @@ export const ERROR_CATEGORIES = Object.freeze({
         "missing_dependency",
         "unsupported_value",
         "type_mismatch",
+        "result_not_ready",
     ]),
     chain: Object.freeze([
         "undeclared_asset",
         "unused_asset",
         "per_input_options_not_supported",
         "chain_cardinality_mismatch",
+        "no_such_key",
     ]),
 });

package/dist/generated/sdk_spec/presets.js

@@ -50,20 +50,6 @@ export const PRESETS = Object.freeze({
             "preset": "Slow",
         }),
     }),
-    "document_pdf_compress": Object.freeze({
-        Size: Object.freeze({
-            "profile": "Screen",
-            "grayscale": true,
-        }),
-        Balanced: Object.freeze({
-            "profile": "Ebook",
-            "grayscale": false,
-        }),
-        Quality: Object.freeze({
-            "profile": "Printer",
-            "grayscale": false,
-        }),
-    }),
     "document_office_compress": Object.freeze({
         Size: Object.freeze({
             "stripMacros": true,

package/dist/generated/sdk_spec/version.d.ts

@@ -1,3 +1,3 @@
-export declare const SDK_SPEC_VERSION: "2.2.0";
+export declare const SDK_SPEC_VERSION: "2.3.0";
 export declare const PRESET_VERSION: "1.6";
-export declare const PRESET_CONFIG_HASH: "sha256:0fe215aede1da13430380384c58226d074c3b8344c091efc53e097c2930a34f7";
+export declare const PRESET_CONFIG_HASH: "sha256:354814f7906f85be6a6ca5ede6c0722c83cdc058fd658a9bb2b0996520466c6d";

package/dist/generated/sdk_spec/version.js

@@ -1,6 +1,6 @@
 // CODE GENERATED — DO NOT EDIT.
 // Source: compression_contracts/sdk-spec/ (see sdk-spec/README.md).
 // Regenerate with: scripts/generate.py.
-export const SDK_SPEC_VERSION = "2.2.0";
+export const SDK_SPEC_VERSION = "2.3.0";
 export const PRESET_VERSION = "1.6";
-export const PRESET_CONFIG_HASH = "sha256:0fe215aede1da13430380384c58226d074c3b8344c091efc53e097c2930a34f7";
+export const PRESET_CONFIG_HASH = "sha256:354814f7906f85be6a6ca5ede6c0722c83cdc058fd658a9bb2b0996520466c6d";

package/dist/gisl.d.ts

@@ -22,6 +22,7 @@ import { type ResolveCredentialsOptions, type ResolveEndpointOptions } from './c
 import type { CreditsUsageOptions, GislClientConfig, CapabilitiesSnapshot } from './types.js';
 import type { AccountLimits, CreditsBalanceResponse, CreditsUsageResponse, OperationCapability, OperationType } from '@giveitsmaller/contracts/openapi';
 import { OperationBuilder } from './builder.js';
+import type { ConvertOptions, ThumbnailOptions } from './ergonomic/option_types.js';
 import { MergeBuilder, type Asset, type MergeOptions } from './merge.js';
 import { PresetDefaults } from './ergonomic/presets/index.js';
 import { Recipe, FilesRecipe, BatchRecipe, type FileInput } from './file-first.js';
@@ -129,8 +130,26 @@ export type ErgonomicClient = GislClient & {
      */
     workflow(id: string): Handle;
     compress(input: string | Blob, options?: Record<string, unknown>): OperationBuilder;
-    convert(input: string | Blob, options?: Record<string, unknown>): OperationBuilder;
-    thumbnail(input: string | Blob, options?: Record<string, unknown>): OperationBuilder;
+    /**
+     * Single-op convert. The target format rides the bag as the required
+     * `output_format` (the single-op builder has no positional format — that is
+     * the file-first `Recipe.convert(format, …)` surface). Extra keys are the
+     * typed {@link ConvertOptions}. A missing `output_format` is a compile-time
+     * error (uFbM31dC); an unknown key is a compile-time error for an INLINE bag
+     * only — aliased bags bypass TS excess-property checks — so the runtime guard
+     * remains the backstop (also for untyped JS callers).
+     */
+    convert(input: string | Blob, options: ConvertOptions & {
+        output_format: string;
+    }): OperationBuilder;
+    /**
+     * Single-op thumbnail. {@link ThumbnailOptions} requires `width` + `height`;
+     * omitting either is a compile-time error (uFbM31dC). An unknown key is a
+     * compile-time error for an INLINE bag only — aliased bags bypass TS
+     * excess-property checks — so the runtime guard remains the backstop (also
+     * for untyped JS callers).
+     */
+    thumbnail(input: string | Blob, options: ThumbnailOptions): OperationBuilder;
     /** Geometric transform (rotate/flip). Passthrough; the op is `planned` (server 422s until Lambdas ship). */
     transform(input: string | Blob, options?: Record<string, unknown>): OperationBuilder;
     /**

package/dist/handle.d.ts

@@ -97,7 +97,7 @@ export declare class Handle {
      * This is the ONLY blocking accessor on a `Handle`.
      *
      * @param maxWait Wall-clock deadline for the wait + downloads (string suffix
-     *   `'2h'`/`'30m'`/`'120s'` or a number of milliseconds). Defaults to 300s,
+     *   `'2h'`/`'30m'`/`'120s'` or a number of milliseconds). Defaults to 600s,
      *   matching `Recipe.run()` / the PHP `Handle::wait()` default.
      * @throws {GislConfigError} reason `no_client` when no client is bound.
      * @throws {GislTimeoutError} when `maxWait` elapses before terminal.
@@ -125,6 +125,11 @@ export declare class Handle {
      *    empty `keyByRef`, so each input's key is recovered from its `file-{i}`
      *    ref (`"0"`, `"1"`, …). A submitted/reattached fan-out carries no
      *    caller-supplied keys — keyed fan-out is a separate concern.
+     *  - A `merge` / `archive` / `watermark` shape ({@link isMergeStatus} /
+     *    {@link isArchiveStatus} / {@link isWatermarkStatus}) → project ONLY the
+     *    terminal deliverable, filtering the `src_*` passthrough plumbing. The
+     *    terminal ref is the downstream `post` job when post-`sole_op` steps were
+     *    chained ({@link terminalOutputRef}), else the sole_op job itself.
      *  - Anything else (the single-file {@link Recipe} path) →
      *    {@link projectDownloadsToRunResult} keyed by this handle's `#key`
      *    (the recipe key from a file-first `submit()`, or `null` on reattach).

package/dist/handle.js

@@ -34,7 +34,7 @@
  */
 import { GislConfigError, GislNetworkError, GislResultNotReadyError, GislTimeoutError, SseEndedWithoutTerminal, } from './errors.js';
 import { _consumeSseToTerminal, _pollToTerminal, _parseMaxWait, } from './builder.js';
-import { projectDownloadsToRunResult, projectMultiJobToRunResult, isFanoutStatus, isMergeStatus, isArchiveStatus, isWatermarkStatus, } from './file-first.js';
+import { projectDownloadsToRunResult, projectMultiJobToRunResult, isFanoutStatus, isMergeStatus, isArchiveStatus, isWatermarkStatus, isSoleOpChainStatus, soleOpChainDeliverableRef, _POST_STEP_JOB_REF, } from './file-first.js';
 import { LazyHttpDownloader } from './lazy-downloader.js';
 /**
  * The terminal workflow states. A status response in any of these states
@@ -80,6 +80,16 @@ export class StatusSnapshot {
         return { workflowId: this.workflowId, state: this.state };
     }
 }
+/**
+ * The terminal deliverable's job ref for a `sole_op` DAG: the downstream
+ * post-steps job ({@link _POST_STEP_JOB_REF}, present when the caller chained
+ * ops after `watermark()` / `merge()`) when it exists, else the `sole_op` job
+ * itself. Lets a submitted/reattached {@link Handle} project the final output —
+ * not the intermediate `sole_op` artifact — without builder state. PIiUit28.
+ */
+function terminalOutputRef(jobDownloads, soleOpRef) {
+    return jobDownloads.some((d) => d.ref === _POST_STEP_JOB_REF) ? _POST_STEP_JOB_REF : soleOpRef;
+}
 /**
  * Handle to a created workflow. Carries `workflowId` + an optional
  * `webhookSecret` (the data the operation-first/merge `submit()` returns)
@@ -139,12 +149,12 @@ export class Handle {
      * This is the ONLY blocking accessor on a `Handle`.
      *
      * @param maxWait Wall-clock deadline for the wait + downloads (string suffix
-     *   `'2h'`/`'30m'`/`'120s'` or a number of milliseconds). Defaults to 300s,
+     *   `'2h'`/`'30m'`/`'120s'` or a number of milliseconds). Defaults to 600s,
      *   matching `Recipe.run()` / the PHP `Handle::wait()` default.
      * @throws {GislConfigError} reason `no_client` when no client is bound.
      * @throws {GislTimeoutError} when `maxWait` elapses before terminal.
      */
-    async wait(maxWait = 300_000, onProgress) {
+    async wait(maxWait = 600_000, onProgress) {
         const client = this.requireClient();
         const deadline = Date.now() + _parseMaxWait(maxWait);
         let finalStatus;
@@ -172,13 +182,13 @@ export class Handle {
             });
         }
         if (Date.now() >= deadline) {
-            throw new GislTimeoutError(`Workflow ${this.workflowId} reached terminal status but maxWait elapsed before downloads could be fetched`);
+            throw new GislTimeoutError(`Workflow ${this.workflowId} reached terminal status but maxWait elapsed before downloads could be fetched`, this.workflowId);
         }
         const downloads = await client.getWorkflowDownloads(this.workflowId);
         // TDqmkWpX: re-check AFTER the downloads fetch so a slow getWorkflowDownloads
         // cannot return a success past the advertised maxWait.
         if (Date.now() >= deadline) {
-            throw new GislTimeoutError(`Workflow ${this.workflowId} downloads fetch completed after maxWait elapsed`);
+            throw new GislTimeoutError(`Workflow ${this.workflowId} downloads fetch completed after maxWait elapsed`, this.workflowId);
         }
         return this.project(finalStatus, downloads.downloads);
     }
@@ -212,6 +222,11 @@ export class Handle {
      *    empty `keyByRef`, so each input's key is recovered from its `file-{i}`
      *    ref (`"0"`, `"1"`, …). A submitted/reattached fan-out carries no
      *    caller-supplied keys — keyed fan-out is a separate concern.
+     *  - A `merge` / `archive` / `watermark` shape ({@link isMergeStatus} /
+     *    {@link isArchiveStatus} / {@link isWatermarkStatus}) → project ONLY the
+     *    terminal deliverable, filtering the `src_*` passthrough plumbing. The
+     *    terminal ref is the downstream `post` job when post-`sole_op` steps were
+     *    chained ({@link terminalOutputRef}), else the sole_op job itself.
      *  - Anything else (the single-file {@link Recipe} path) →
      *    {@link projectDownloadsToRunResult} keyed by this handle's `#key`
      *    (the recipe key from a file-first `submit()`, or `null` on reattach).
@@ -221,13 +236,16 @@ export class Handle {
         if (isFanoutStatus(finalStatus)) {
             return projectMultiJobToRunResult(this.workflowId, finalStatus, jobDownloads, new Map(), downloader);
         }
-        // A fluent `files([...]).merge(...)` combine — project ONLY the merged
-        // output, filtering the `src_*` passthrough plumbing (which re-exposes the
-        // raw inputs). Matches MergedRecipe.run()'s `ref === 'merge'` filter so a
+        // A fluent `files([...]).merge(...)` combine — project ONLY the terminal
+        // deliverable, filtering the `src_*` passthrough plumbing (which re-exposes
+        // the raw inputs). Matches MergedRecipe.run()'s terminal-output filter so a
         // submitted/reattached merge handle never surfaces the input artifacts
         // alongside the combined output (codex c1).
         if (isMergeStatus(finalStatus)) {
-            const mergeDownloads = jobDownloads.filter((d) => d.ref === 'merge');
+            // Post-merge steps (PIiUit28) lower into the downstream `_POST_STEP_JOB_REF`
+            // job, which is then the deliverable; otherwise the `merge` job is.
+            const mergeOutputRef = terminalOutputRef(jobDownloads, 'merge');
+            const mergeDownloads = jobDownloads.filter((d) => d.ref === mergeOutputRef);
             return projectDownloadsToRunResult(this.workflowId, finalStatus, mergeDownloads, null, downloader);
         }
         // A fluent `files([...]).archive(...)` bundle — project ONLY the archive
@@ -237,14 +255,25 @@ export class Handle {
             const archiveDownloads = jobDownloads.filter((d) => d.ref === 'archive');
             return projectDownloadsToRunResult(this.workflowId, finalStatus, archiveDownloads, null, downloader);
         }
-        // A fluent `file(...).watermark(overlay)` — project ONLY the watermark
-        // output, filtering the `src_*` (base/overlay) passthrough plumbing. Matches
-        // WatermarkedRecipe.run()'s `ref === 'watermark'` filter so a
+        // A fluent `file(...).watermark(overlay)` — project ONLY the terminal
+        // deliverable, filtering the `src_*` (base/overlay) passthrough plumbing.
+        // Matches WatermarkedRecipe.run()'s terminal-output filter so a
         // submitted/reattached watermark handle never surfaces the raw inputs.
         if (isWatermarkStatus(finalStatus)) {
-            const watermarkDownloads = jobDownloads.filter((d) => d.ref === 'watermark');
+            const watermarkOutputRef = terminalOutputRef(jobDownloads, 'watermark');
+            const watermarkDownloads = jobDownloads.filter((d) => d.ref === watermarkOutputRef);
             return projectDownloadsToRunResult(this.workflowId, finalStatus, watermarkDownloads, null, downloader);
         }
+        // A single-input `sole_op` chain — e.g. `.textWatermark('x').compress()`
+        // lowered to a `text_watermark` job + downstream `post` job (IQc01rj0).
+        // Project ONLY the terminal deliverable, filtering the intermediate sole_op
+        // artifact. The recipe key is preserved (unlike the multi-input branches):
+        // this is the single-file path with a terminal-ref filter.
+        if (isSoleOpChainStatus(finalStatus)) {
+            const soleOpRef = soleOpChainDeliverableRef(finalStatus);
+            const soleOpDownloads = jobDownloads.filter((d) => d.ref === soleOpRef);
+            return projectDownloadsToRunResult(this.workflowId, finalStatus, soleOpDownloads, this.#key, downloader);
+        }
         return projectDownloadsToRunResult(this.workflowId, finalStatus, jobDownloads, this.#key, downloader);
     }
     /**

package/dist/index.core.d.ts

@@ -3,7 +3,7 @@ export { parseSseStream } from './sse.js';
 export type { CreditsUsageOptions, ListWorkflowsOptions, GetSchemaOptions, GetSchemaResult, CapabilitiesSnapshot, PreflightClipError, PreflightClipsResult, ProbeWaitOptions, ProbeWaitResult, GislClientConfig, GislSseEvent, GislSseParseFailure, UploadOptions, WaitOptions, WorkflowCreatePayload, OperationDef, WorkflowSourcePayload, MultiInputSourcePayload, UploadSourcePayload, JobOutputSourcePayload, ExternalImportSourcePayload, ConnectionSourcePayload, JobInputV2Payload, JobDefinitionPayload, ExternalDestinationPayload, DeliveryPayload, DeliveryModePayload, DeliveryBundleFormatPayload, DeliverySelectionPayload, DeliverySelectionTypePayload, DeliveryOutputRefPayload, WorkflowProcessingPayload, ProcessingClassHintPayload, MultipartCheckpointState, _Sdk3HandCodedUploadedPart, _Sdk3HandCodedMultipartStatusResult, _Sdk3HandCodedPresignedPart, _Sdk3HandCodedPresignPartsResult, _Sdk3HandCodedKeepaliveResult, } from './types.js';
 export { uploadSource, jobOutputSource, externalImportSource, connectionSource, } from './types.js';
 export type { GislConfigErrorMetadata } from './errors.js';
-export { GislError, GislApiError, GislValidationError, GislBalanceExhaustedError, GislTierRestrictedError, GislFeatureTierRestrictedError, GislFeatureNotAvailableError, GislWorkflowExpiredError, GislProbePendingError, GislAuthError, GislUploadCapExceededError, GislMultipartPartError, GislMultipartPartCountError, GislMultipartSessionNotFoundError, GislMultipartSessionOwnershipError, GislMultipartSessionAuthRequiredError, GislTimeoutError, GislAbortError, GislNetworkError, GislConfigError, GislMissingCredentialsError, GislFeatureRequiresAuthError, GislUndeclaredAssetError, GislUnusedAssetError, GislPerInputOptionsNotSupportedError, GislChainCardinalityMismatchError, GislBundleAlreadyArchivedError, GislNoSuchKeyError, GislSinkError, GislItemFailedError, GislResultNotReadyError, } from './errors.js';
+export { GislError, GislApiError, GislValidationError, GislBalanceExhaustedError, GislLongFormConcurrencyError, GislTierRestrictedError, GislFeatureTierRestrictedError, GislFeatureNotAvailableError, GislWorkflowExpiredError, GislProbePendingError, GislAuthError, GislUploadCapExceededError, GislMultipartPartError, GislMultipartPartCountError, GislMultipartSessionNotFoundError, GislMultipartSessionOwnershipError, GislMultipartSessionAuthRequiredError, GislTimeoutError, GislFanOutTimeoutError, GislAbortError, GislNetworkError, GislConfigError, GislMissingCredentialsError, GislFeatureRequiresAuthError, GislUndeclaredAssetError, GislUnusedAssetError, GislPerInputOptionsNotSupportedError, GislChainCardinalityMismatchError, GislBundleAlreadyArchivedError, GislNoSuchKeyError, GislSinkError, GislItemFailedError, GislResultNotReadyError, } from './errors.js';
 export type { GislApiErrorOptions, GislUploadCapKind } from './errors.js';
 export type { ErrorCategory } from './generated/sdk_spec/errors.js';
 export { RunResult } from './file-first.js';
@@ -20,20 +20,20 @@ export { BatchRecipe } from './file-first.js';
 export { Handle, StatusSnapshot } from './handle.js';
 export { gisl, create } from './gisl.js';
 export type { GislCreateOptions, Environment, ErgonomicClient, SingleInputOperationType, MultiInputOperationType, } from './gisl.js';
-export { presetDefaults, PresetDefaults, type PresetMedia, type PresetOp, type AnyPresetOptions, ImageCompressPresetOptions, type ImageCompressPresetOptionsInput, AudioCompressPresetOptions, type AudioCompressPresetOptionsInput, VideoCompressPresetOptions, type VideoCompressPresetOptionsInput, DocumentPdfCompressPresetOptions, type DocumentPdfCompressPresetOptionsInput, DocumentOfficeCompressPresetOptions, type DocumentOfficeCompressPresetOptionsInput, DocumentOdfCompressPresetOptions, type DocumentOdfCompressPresetOptionsInput, DocumentEpubCompressPresetOptions, type DocumentEpubCompressPresetOptionsInput, OptimizeFor, ImageMetadataPolicy, ImageFormat, VideoCodec, VideoPreset, VideoFit, AudioBitrate, AudioCodec, AudioSampleRate, PdfProfile, PdfColorspace, } from './ergonomic/presets/index.js';
+export { presetDefaults, PresetDefaults, type PresetMedia, type PresetOp, type AnyPresetOptions, ImageCompressPresetOptions, type ImageCompressPresetOptionsInput, AudioCompressPresetOptions, type AudioCompressPresetOptionsInput, VideoCompressPresetOptions, type VideoCompressPresetOptionsInput, DocumentOfficeCompressPresetOptions, type DocumentOfficeCompressPresetOptionsInput, DocumentOdfCompressPresetOptions, type DocumentOdfCompressPresetOptionsInput, DocumentEpubCompressPresetOptions, type DocumentEpubCompressPresetOptionsInput, OptimizeFor, ImageMetadataPolicy, ImageFormat, VideoCodec, VideoPreset, VideoFit, AudioBitrate, AudioCodec, AudioSampleRate, } from './ergonomic/presets/index.js';
 export { OperationBuilder, MapEachBuilder } from './builder.js';
 export { MergeBuilder, asset, handle, clip } from './merge.js';
 export type { Asset, ClipEntry, ClipOptions, MergeMediaKind, MergeOptions, SequenceEntry, } from './merge.js';
 export type { Artifact, ArtifactRef, JobBreakdown, OperationBreakdown, ProcessingProgressEvent, ProgressEvent, ResolvedOptions, ResolvedOptionsSources, Result, RunOptions, SubmitOptions, UploadProgressEvent, } from './builder.js';
 export { PRESET_VERSION, resolveCompressOptions } from './ergonomic/preset_resolver.js';
 export type { ResolveCompressOptionsInput, ResolveCompressOptionsOutput, } from './ergonomic/preset_resolver.js';
-export type { AccountLimits, AccountLimitsLimits, AccountLimitEntry, AudioWatermarkDecodeRequest, AudioWatermarkDecodeResponse, ContactRequest, CreditsBalanceResponse, CreditsUsageResponse, CreditTransaction, ExternalImportCreatedResponse, ExternalImportRequest, LoginUserRequest, LoginUser200ResponseData, LoginUser200ResponseDataUser, WorkflowCancelResponse, WorkflowResumeResponse, WorkflowPausedDetail, WorkflowPausedDetailLinks, UploadResponse, UploadConstraintsApplied, UploadProbeResponse, UploadProbeMediaMetadata, MultipartInitiateRequestMetadataHint, WorkflowCreateResponse, WorkflowStatusResponse, WorkflowListResponse, WorkflowSummary, WorkflowDownloadResponse, MetadataResponse, MetadataResponseDimensions, MetadataResponseExif, MetadataResponseExifGps, OperationsSchemaResponse, OperationCapability, OutputProperties, ImageEncodeCapabilities, OperationSchemaDefinition, MimeGroupSchema, OptionSchema, PerValueAvailabilityEntry, PerRoleCardinalityEntry, RetryResponse, JobDownload, OperationDownload, DownloadBundle, WebhookPayload, WebhookOperationContext, JobResponse, OperationResponse, OperationResult, OperationResultMetrics, ExternalDestination, Delivery, DeliveryPlan, DeliveryPlanOutput, WorkflowProcessing, ProcessingPlan, ProcessingPlanJob, WorkflowEdge, WorkflowWarning, JobInputV2, WorkflowSource, UploadSource, JobOutputSource, ConnectionSource, ExternalImportToken, BalanceExhaustedResponse, BalanceExhaustedResponseAllOfLinks, TierRestrictionResponse, FeatureTierRestrictedResponse, FeatureNotAvailableResponse, FeatureViolation, WorkflowExpiredResponse, ProbePendingResponse, AuthErrorResponse, } from '@giveitsmaller/contracts/openapi';
+export type { AccountLimits, AccountLimitsLimits, AccountLimitEntry, AudioWatermarkDecodeRequest, AudioWatermarkDecodeResponse, ContactRequest, CreditsBalanceResponse, CreditsUsageResponse, CreditTransaction, ExternalImportCreatedResponse, ExternalImportRequest, LoginUserRequest, LoginUser200ResponseData, LoginUser200ResponseDataUser, WorkflowCancelResponse, WorkflowResumeResponse, WorkflowPausedDetail, WorkflowPausedDetailLinks, UploadResponse, UploadConstraintsApplied, UploadProbeResponse, UploadProbeMediaMetadata, MultipartInitiateRequestMetadataHint, WorkflowCreateResponse, WorkflowStatusResponse, WorkflowListResponse, WorkflowSummary, WorkflowDownloadResponse, MetadataResponse, MetadataResponseDimensions, MetadataResponseExif, MetadataResponseExifGps, OperationsSchemaResponse, OperationCapability, OutputProperties, ImageEncodeCapabilities, OperationSchemaDefinition, MimeGroupSchema, OptionSchema, PerValueAvailabilityEntry, PerRoleCardinalityEntry, RetryResponse, JobDownload, OperationDownload, DownloadBundle, WebhookPayload, WebhookOperationContext, JobResponse, OperationResponse, OperationResult, OperationResultMetrics, ExternalDestination, Delivery, DeliveryPlan, DeliveryPlanOutput, WorkflowProcessing, ProcessingPlan, ProcessingPlanJob, WorkflowEdge, WorkflowWarning, JobInputV2, WorkflowSource, UploadSource, JobOutputSource, ConnectionSource, ExternalImportToken, BalanceExhaustedResponse, BalanceExhaustedResponseAllOfLinks, LongFormConcurrencyLimitResponse, LongFormConcurrencyLimitResponseAllOfLinks, TierRestrictionResponse, FeatureTierRestrictedResponse, FeatureNotAvailableResponse, FeatureViolation, WorkflowExpiredResponse, ProbePendingResponse, AuthErrorResponse, } from '@giveitsmaller/contracts/openapi';
 export { AudioWatermarkDecodeRequestMethodHintEnum, AudioWatermarkDecodeResponseMethodEnum, OperationInputModel, ExternalImportRequestProviderHintEnum, ContactSubject, CreditTransactionSourceBucket, UploadProbeStatus, UploadProbeProcessingClass, WorkflowCancelBillingEffect, WorkflowPauseRequiredAction, WorkflowStatus, WarningType, WorkflowWarningSeverity, OperationType, SseEventType, CallbackEventType, OperationStatus, JobStatus, JobInputV2RoleEnum, AuthErrorType, TierRestrictionKind, BalanceExhaustedResponseRequiredActionEnum, ProcessingClassReason, DeliveryPlanReason, UserTier, ProcessingClass, } from '@giveitsmaller/contracts/openapi';
 export type { SseOperationProgressData, SseOperationCompletedData, SseOperationFailedData, SseJobCompletedData, SseJobFailedData, SseWorkflowTerminalData, } from '@giveitsmaller/contracts/openapi';
 export type { MultiOutputCompletion, PageIndexed, PositionIndexed, Unindexed, } from '@giveitsmaller/contracts/asyncapi';
 import type { MultiOutputCompletion as _MultiOutputCompletion } from '@giveitsmaller/contracts/asyncapi';
 export type OperationResultOutputEntry = _MultiOutputCompletion['outputs'][number];
-export type { CompressImageOptions, CompressImageJpegOptions, CompressImagePngOptions, CompressImageAvifOptions, CompressVideoOptions, CompressAudioOptions, CompressDocumentPdfOptions, CompressDocumentOfficeOptions, CompressDocumentOdfOptions, CompressDocumentEpubOptions, ThumbnailImageOptions, ThumbnailVideoOptions, ThumbnailDocumentOptions, TransformImageOptions, TransformImageGifOptions, TransformVideoOptions, TransformDocumentPdfOptions, ConvertImageOptions, ConvertVideoOptions, ConvertAudioOptions, ConvertDocumentPdfOptions, MergeImageOptions, MergeVideoOptions, MergeVideoPerInputOptions, MergeAudioOptions, MergeAudioPerInputOptions, ArchiveOptions, ImageWatermarkImageOptions, ImageWatermarkImageGifOptions, TextWatermarkImageOptions, CustomLumaVideoOptions, AudioOverlayAudioOptions, AudioOverlayVideoOptions, AudioWatermarkAudioOptions, AudioWatermarkVideoOptions, AudioToVideoAudioOptions, VideoWatermarkVideoOptions, VideoTextWatermarkVideoOptions, SplitImageGifOptions, SplitDocumentPdfOptions, SplitAudioOptions, SplitVideoOptions, } from '@giveitsmaller/contracts/operations';
+export type { CompressImageOptions, CompressImageJpegOptions, CompressImagePngOptions, CompressImageAvifOptions, CompressVideoOptions, CompressAudioOptions, CompressDocumentOfficeOptions, CompressDocumentOdfOptions, CompressDocumentEpubOptions, ThumbnailImageOptions, ThumbnailVideoOptions, ThumbnailDocumentOptions, TransformImageOptions, TransformImageGifOptions, TransformVideoOptions, TransformDocumentPdfOptions, ConvertImageOptions, ConvertVideoOptions, ConvertAudioOptions, ConvertDocumentPdfOptions, MergeImageOptions, MergeVideoOptions, MergeVideoPerInputOptions, MergeAudioOptions, MergeAudioPerInputOptions, ArchiveOptions, ImageWatermarkImageOptions, ImageWatermarkImageGifOptions, TextWatermarkImageOptions, CustomLumaVideoOptions, AudioOverlayAudioOptions, AudioOverlayVideoOptions, AudioWatermarkAudioOptions, AudioWatermarkVideoOptions, AudioToVideoAudioOptions, VideoWatermarkVideoOptions, VideoTextWatermarkVideoOptions, SplitImageGifOptions, SplitDocumentPdfOptions, SplitAudioOptions, SplitVideoOptions, } from '@giveitsmaller/contracts/operations';
 export { ImageWatermarkImageAnchor, ImageWatermarkImageGifAnchor, TextWatermarkImageAnchor, TextWatermarkImageFontFamily, TextWatermarkImageWatermarkMode, AudioOverlayAudioMode, AudioOverlayVideoMode, AudioOverlayVideoNoAudioTrackBehaviour, AudioWatermarkAudioMethod, AudioWatermarkAudioRobustness, AudioWatermarkAudioDensity, AudioWatermarkVideoMethod, AudioWatermarkVideoRobustness, AudioWatermarkVideoDensity, AudioToVideoAudioOutputResolution, AudioToVideoAudioImageFit, AudioToVideoAudioOutputFormat, VideoWatermarkVideoAnchor, VideoTextWatermarkVideoFontFamily, VideoTextWatermarkVideoWatermarkMode, VideoTextWatermarkVideoAnchor, SplitImageGifOutputFormat, SplitDocumentPdfMode, SplitAudioMode, SplitAudioPrecision, SplitVideoMode, SplitVideoPrecision, } from '@giveitsmaller/contracts/operations';
 export { archiveMetadata, audioOverlayMetadata, audioWatermarkMetadata, compressMetadata, convertMetadata, customLumaMetadata, imageWatermarkMetadata, mergeMetadata, textWatermarkMetadata, thumbnailMetadata, audioToVideoMetadata, videoWatermarkMetadata, videoTextWatermarkMetadata, splitMetadata, transformMetadata, } from '@giveitsmaller/contracts/operations';
 export type { ConvertOptions, ThumbnailOptions, TransformOptions, TextWatermarkOptions, WatermarkOptions, WatermarkOverlay, WatermarkAnchor, } from './ergonomic/option_types.js';

package/dist/index.core.js

@@ -9,9 +9,12 @@ export { GislClient, DEFAULT_MULTIPART_FIRST_CHUNK_SIZE } from './client.js';
 export { parseSseStream } from './sse.js';
 export { uploadSource, jobOutputSource, externalImportSource, connectionSource, } from './types.js';
 // Errors
-export { GislError, GislApiError, GislValidationError, GislBalanceExhaustedError, GislTierRestrictedError, GislFeatureTierRestrictedError, GislFeatureNotAvailableError, GislWorkflowExpiredError, GislProbePendingError, GislAuthError, GislUploadCapExceededError, GislMultipartPartError, GislMultipartPartCountError, 
+export { GislError, GislApiError, GislValidationError, GislBalanceExhaustedError, GislLongFormConcurrencyError, GislTierRestrictedError, GislFeatureTierRestrictedError, GislFeatureNotAvailableError, GislWorkflowExpiredError, GislProbePendingError, GislAuthError, GislUploadCapExceededError, GislMultipartPartError, GislMultipartPartCountError, 
 // SDK-3 (Wb6ebOMM) — typed errors for the 3 resume-support endpoints.
-GislMultipartSessionNotFoundError, GislMultipartSessionOwnershipError, GislMultipartSessionAuthRequiredError, GislTimeoutError, GislAbortError, 
+GislMultipartSessionNotFoundError, GislMultipartSessionOwnershipError, GislMultipartSessionAuthRequiredError, GislTimeoutError, 
+// 4G4FaA9X — mapEach fan-out timed out mid-batch; carries the completed
+// child ids + parent id so the caller can recover without a whole-batch re-run.
+GislFanOutTimeoutError, GislAbortError, 
 // FF2b / tywwynmN — transport-level failure (mirrors PHP GislNetworkError);
 // raised by the file-first HttpDownloader when an output URL cannot be read.
 GislNetworkError, 
@@ -77,7 +80,7 @@ export { gisl, create } from './gisl.js';
 // Ergonomic preset defaults (T4a / VhIj4S7T) — typed leaf DTOs + immutable
 // `PresetDefaults` builder + `presetDefaults()` factory + ergonomic enum
 // re-exports. Resolver wiring (T4b) consumes `PresetDefaults.cellFor()`.
-export { presetDefaults, PresetDefaults, ImageCompressPresetOptions, AudioCompressPresetOptions, VideoCompressPresetOptions, DocumentPdfCompressPresetOptions, DocumentOfficeCompressPresetOptions, DocumentOdfCompressPresetOptions, DocumentEpubCompressPresetOptions, OptimizeFor, ImageMetadataPolicy, ImageFormat, VideoCodec, VideoPreset, VideoFit, AudioBitrate, AudioCodec, AudioSampleRate, PdfProfile, PdfColorspace, } from './ergonomic/presets/index.js';
+export { presetDefaults, PresetDefaults, ImageCompressPresetOptions, AudioCompressPresetOptions, VideoCompressPresetOptions, DocumentOfficeCompressPresetOptions, DocumentOdfCompressPresetOptions, DocumentEpubCompressPresetOptions, OptimizeFor, ImageMetadataPolicy, ImageFormat, VideoCodec, VideoPreset, VideoFit, AudioBitrate, AudioCodec, AudioSampleRate, } from './ergonomic/presets/index.js';
 // Operation-builder surface (T2 / xVDTIm8C) — `client.compress/convert/thumbnail`
 // returns an `OperationBuilder`; `.run()` projects to a flat `Result` /
 // `.submit({webhook})` returns a `Handle`. Progress events are the

package/dist/merge.d.ts

@@ -103,6 +103,29 @@ export interface MergeOptions {
     readonly preset?: string;
     /** Video output dimensions `WxH` (e.g. `"1920x1080"`); omit to inherit from inputs. Video merge only. */
     readonly targetResolution?: string;
+    /**
+     * Target output size (bytes, or a `'50MB'`-style string). Lowered to wire
+     * `target_size_bytes`, and the SDK also sets `encoding_mode: 'target_size'` alongside
+     * it. Video merge only.
+     *
+     * **UNITS ARE DECIMAL HERE (1 KB = 1000), UNLIKE `compress`.** `compress`'s
+     * `targetSize` parses the same strings as BINARY (1 KB = 1024), so `'50MB'` means
+     * 50,000,000 bytes on a merge and 52,428,800 bytes on a compress. That divergence is
+     * NOT deliberate — it contradicts the pinned convention that every human-readable
+     * size string in this SDK is binary — and it has a sharp edge: the contract floor for
+     * `target_size_bytes` is 1 MiB (1,048,576), so `'1MB'` here resolves to 1,000,000 and
+     * is rejected as below the minimum. Prefer an explicit byte count until this is
+     * reconciled. Tracked by `YOCz0i74`; changing it moves bytes for existing callers, so
+     * it is a deliberate decision rather than a silent correction.
+     *
+     * **NOT AVAILABLE FOR LONG INPUTS.** Merges whose summed input duration routes to
+     * the long-form Fargate path reject both keys — that path is single-pass-CRF by
+     * construction and two-pass target-size is unbuilt. The request fails during
+     * execution, and the SDK cannot warn earlier: the routing decision is made
+     * server-side at create-plan time, so there is nothing here to check it against.
+     * Short-form merges honour it normally. Tracked by `zJN6XIi5`, blocked on a
+     * contract that can express per-execution-path availability.
+     */
     readonly targetSize?: string | number;
     readonly transitionDuration?: number;
     readonly fps?: number;