@giveitsmaller/sdk 0.21.0 → 0.22.0

package/README.md

@@ -56,6 +56,54 @@ for (const artifact of many.artifacts) console.log(artifact.url);
 > only under the same auth that created it; the upload-then-create flow above is
 > consistent by construction. Anonymous-intake uploads are unaffected.
 
+## Known limitation — browser SSE is restricted to one origin
+
+**Applies to the browser build only** (`@giveitsmaller/sdk/browser`), and **only to live progress
+streaming** — `streamEvents()`, and the `run({ useSSE: true })` default that uses it.
+
+Live progress is served from a **separate host** to the rest of the API, and that host allows
+**exactly one browser origin**: the Give It Smaller web app. So from a browser on any other origin:
+
+| what you are doing | works? |
+|---|---|
+| Uploads, workflow create, status, downloads | **Yes** — these stay on the main API host, which allows a **list** of origins (per environment) |
+| `streamEvents()` / SSE progress | **No** — blocked at the CORS preflight |
+
+**Affected consumers:** third-party sites embedding the SDK, embedded/iframe use, and **local
+development against staging** — which is the one most likely to bite first, because it looks like a
+bug in your code.
+
+⚠️ **Local dev against staging is the sharp edge, and the reason is worth stating:** the two hosts
+have *different* CORS policies, for a platform reason rather than an oversight. The main API host
+allows a **list** of origins — and the **staging** list includes the usual localhost dev ports — so a
+browser on `localhost` works against staging today. The stream host allows exactly **one** origin,
+because it is a different API product with no native CORS configuration and nowhere to put a second
+value. So everything keeps working right up until live progress, and then fails with a CORS error —
+which reads like a mistake in your own application rather than a platform limitation.
+
+**Production allows only the production web app on both hosts**, and always has.
+
+**Workaround:** pass `useSSE: false` to `run()`. The SDK falls back to polling, which goes to the
+main API host and is unaffected. Everything else about the call is identical.
+
+**Why it cannot simply be widened:** the stream is cookie-credentialed, and the CORS specification
+forbids combining `Access-Control-Allow-Credentials: true` with `Access-Control-Allow-Origin: *`.
+The header also accepts exactly one origin — a comma-separated list is not valid. Supporting more
+origins requires the server to validate and echo the request's `Origin`, which is planned but not
+shipped.
+
+**On authentication:** prefer an API key (`bearerAuth`) or the anonymous capability token on the
+stream host. Cookie/session auth is accepted by the endpoint but a *credentialed cross-origin*
+request additionally needs the browser to opt in and the server to answer with matching credential
+headers — cookie domain scope alone is not sufficient, and this path is not verified.
+
+**Node consumers are unaffected** — CORS is a browser mechanism. The PHP SDK is unaffected for the
+same reason.
+
+> ⚠️ This limitation is invisible to automated testing: our own app's origin is allowed, so every
+> test and canary we run passes while a consumer on another origin fails. It is written here because
+> nothing else would tell you.
+
 ## Documentation
 
 Full documentation — getting started and concepts, the `GislClient` reference and operation

package/dist/builder.js

@@ -26,7 +26,7 @@
  */
 import { SseEventType, SseOperationProgressDataFromJSON, } from '@giveitsmaller/contracts/openapi';
 import { uploadSource } from './types.js';
-import { GislTimeoutError, GislNetworkError, SseEndedWithoutTerminal } from './errors.js';
+import { GislTimeoutError, GislFanOutTimeoutError, GislNetworkError, SseEndedWithoutTerminal } from './errors.js';
 // Deferred-usage-only import: `Handle` is constructed inside submit() at call
 // time, not at module load, so the builder.ts <-> handle.ts cycle is safe
 // under ESM (handle.ts imports the await-primitives from this module).
@@ -446,13 +446,38 @@ export class MapEachBuilder {
             _checkAborted(options.signal);
             const remaining = deadline - Date.now();
             if (remaining <= 0) {
-                throw new GislTimeoutError(`maxWait elapsed during fan-out (after ${collectedArtifacts.length} child runs)`);
+                // Clean timeout BETWEEN children (no child in flight): the parent + the
+                // children completed so far are recoverable — carry their ids so the
+                // caller polls them and re-runs ONLY the never-created children (4G4FaA9X).
+                throw new GislFanOutTimeoutError(`maxWait elapsed during fan-out (after ${collectedChildResults.length} child runs)`, {
+                    completedWorkflowIds: collectedChildResults.map((r) => r.workflowId),
+                    parentWorkflowId: parentResult.workflowId,
+                });
             }
             const childBuilder = this.fn(art);
-            const childResult = await childBuilder.run({
-                ...options,
-                maxWait: remaining,
-            });
+            let childResult;
+            try {
+                childResult = await childBuilder.run({
+                    ...options,
+                    maxWait: remaining,
+                });
+            }
+            catch (err) {
+                // A CHILD's own deadline elapsed mid-run — the COMMON fan-out timeout
+                // path. Re-throw as a fan-out timeout so the parent + already-completed
+                // children + this in-flight child are ALL recoverable, instead of losing
+                // them behind the child's bare GislTimeoutError (4G4FaA9X). Other errors
+                // (config / API / item failure) propagate unchanged.
+                if (err instanceof GislTimeoutError) {
+                    throw new GislFanOutTimeoutError(`maxWait elapsed during fan-out while a child was running (${collectedChildResults.length} completed)`, {
+                        completedWorkflowIds: collectedChildResults.map((r) => r.workflowId),
+                        parentWorkflowId: parentResult.workflowId,
+                        workflowId: err.workflowId,
+                        cause: err,
+                    });
+                }
+                throw err;
+            }
             collectedChildResults.push(childResult);
             for (const childArt of childResult.artifacts)
                 collectedArtifacts.push(childArt);

package/dist/ergonomic/image_output_routes.d.ts

@@ -85,6 +85,24 @@ export declare function resolveOutputRoute(inputToken: string, outputFormat: str
  * `compressMetadata` `per_value_availability`; same_format only (the only route
  * where value-level options like `metadata` are honored). Returns false when the
  * option / value / group is unknown (no gate).
+ *
+ * PURELY ADDITIVE (SB1wmTJz): planned if ANY consulted group marks this value planned.
+ * The historical group is still consulted, so **every verdict this returned before still
+ * holds** — the change can only turn a missed gate into a gate, never a gate into a
+ * pass. That direction matters: a new false ACCEPT would send a request the server
+ * rejects, which is the failure this function exists to prevent.
+ *
+ * Why not "most specific wins", which reads cleaner: it would flip `webp` +
+ * `color_profile: 'srgb'` from gated to un-gated, because `image_webp` defines
+ * `color_profile` with an empty `per_value_availability`. `RecipeOutputTest`
+ * deliberately pins webp srgb as GATED (v2.134 added `srgb: planned` to the generic
+ * group), and whether webp srgb actually works on the server is not something this
+ * layer can know. Un-gating it on an inference would be exactly the "confident answer
+ * from a check that could not tell you otherwise" pattern. Raised as a question instead.
+ *
+ * What this DOES fix: `image_svg` marks `output_format: 'original'` planned and the
+ * generic group does not, so an SVG input previously sailed through the one marker that
+ * mattered for it — on this gate and on the `output()` gate that shares it.
  */
 export declare function isPlannedValue(inputToken: string, optionKey: string, value: unknown): boolean;
 /**
@@ -117,4 +135,53 @@ export declare const COMPRESS_OPTION_VALUES: Readonly<Record<string, Readonly<Re
  * treated as unknown rather than coerced to a match.
  */
 export declare function isUnknownEnumValue(inputToken: string, optionKey: string, value: unknown): boolean;
+/** A contract `depends_on` rule for a compress-image output option (ehHU08Hu). */
+type OutputDependsOnRule = {
+    readonly requiresKey: string;
+    readonly requiresValue: string;
+} | {
+    readonly requiresAnyOf: readonly string[];
+};
+/**
+ * Contract `depends_on` per compress-image output option, mirroring
+ * `availability.json` `operations.compress.mime_groups.<group>.options.<opt>.depends_on`
+ * (ehHU08Hu). The rule is option-consistent across every image group that carries
+ * the option, so this is a FLAT table (validated group-by-group by
+ * `output-route-conformance.test.ts` / PHP `ImageOutputRouteConformanceTest`).
+ *
+ * Kept as a hand table — NOT a runtime read of the ~238KB availability sidecar —
+ * so the gate stays browser-safe with no contracts-version coupling, exactly like
+ * {@link COMPRESS_OPTION_VALUES}. Mirrored by PHP
+ * `ImageOutputRoutes::OUTPUT_OPTION_DEPENDS_ON`.
+ *
+ * Generalises the 86gAu5Tr auto_quality gate: every option's dependency is
+ * checked uniformly, so quality/lossless/target_size_bytes under `auto_quality`,
+ * `target_size_bytes` without `target_size`, `fit` without width/height, etc. are
+ * all rejected pre-upload instead of only the one hand-coded case.
+ */
+export declare const OUTPUT_OPTION_DEPENDS_ON: Readonly<Record<string, OutputDependsOnRule>>;
+/**
+ * Default of each depended-on key — an ABSENT key resolves to this before the
+ * dependency check (the server applies the same default). `encoding_mode`
+ * defaults to `quality`, so `quality`/`lossless` are valid with no explicit mode,
+ * but `target_size_bytes` / `quality_preset` are not. Pinned to `availability.json`
+ * defaults by the conformance suite.
+ */
+export declare const DEPENDS_ON_KEY_DEFAULTS: Readonly<Record<string, string>>;
+/**
+ * The first contract `depends_on` an already-lowered compress-image wire-option
+ * set violates for the resolved `route`, or `undefined` when every dependency is
+ * satisfied (ehHU08Hu). The caller ({@link Recipe} output lowering) throws
+ * `invalid_option_combination` with the returned message + conflictingFields.
+ * Only options PRESENT in `wireOptions` are checked; a scalar dependency reads
+ * the depended-on key's effective value ({@link DEPENDS_ON_KEY_DEFAULTS} when
+ * absent). A scalar (encoding_mode) dependency is skipped on a `format_change`
+ * (convert has its own deps); universal deps (e.g. `fit → width|height`, identical
+ * in compress + convert) run on BOTH routes. Mirrored by PHP
+ * `ImageOutputRoutes::dependsOnViolation`.
+ */
+export declare function dependsOnViolation(wireOptions: Readonly<Record<string, unknown>>, route: 'same_format' | 'format_change'): {
+    readonly message: string;
+    readonly conflictingFields: readonly string[];
+} | undefined;
 export {};

package/dist/ergonomic/image_output_routes.js

@@ -146,15 +146,38 @@ export function resolveOutputRoute(inputToken, outputFormat) {
         planned: new Set(cell.planned),
     };
 }
-/** Input token → its `compress.image*` mime-group name (for per-value availability lookup). */
-function compressGroupForToken(token) {
-    if (token === 'jpeg')
-        return 'image_jpeg';
-    if (token === 'png')
-        return 'image_png';
-    if (token === 'avif')
-        return 'image_avif';
-    return 'image'; // webp / gif / svg / tiff
+/**
+ * Input token → EVERY `compress.image*` mime-group that can carry a per-value
+ * availability marker for it: the format-specific group when the metadata has one,
+ * PLUS the generic `image` group. Most specific first.
+ *
+ * Both are needed, and the old single-group version lost one or the other whichever
+ * way it chose (SB1wmTJz):
+ * - The generic group carries CROSS-FORMAT markers — `color_profile: 'srgb'` is planned
+ *   there and nowhere else, so a lookup that resolved only to `image_jpeg` never saw it.
+ * - A specific group carries FORMAT-ONLY markers — `image_svg` marks
+ *   `output_format: 'original'` planned (SVG→SVG optimisation is not built) and the
+ *   generic group does not, so a lookup that resolved only to `image` never saw THAT.
+ *
+ * The previous implementation hard-coded `jpeg|png|avif` and fell through to `image`
+ * with a trailing `// webp / gif / svg / tiff`. That comment was true when written and
+ * silently stopped being true when `image_svg` and `image_webp` were added to the
+ * metadata — so SVG inputs missed the one marker that mattered for them, on this gate
+ * AND on the `output()` gate that shares it. Deriving the list from the metadata rather
+ * than a hand-written token list is what stops it going stale a second time; the
+ * mapping is pinned by `output-route-conformance.test.ts`.
+ *
+ * `gif`/`tiff` correctly yield `['image']` alone — the metadata genuinely has no
+ * concrete group for them (verified against its actual key set, not inferred).
+ */
+function compressGroupsForToken(token) {
+    // The historical mapping, PRESERVED EXACTLY. Every verdict it produced today must
+    // keep being produced — see the note on additivity in `isPlannedValue`.
+    const legacy = token === 'jpeg' ? 'image_jpeg' : token === 'png' ? 'image_png' : token === 'avif' ? 'image_avif' : 'image';
+    const specific = `image_${token}`;
+    return specific !== legacy && compressMetadata.mime_groups[specific] !== undefined
+        ? [specific, legacy]
+        : [legacy];
 }
 /**
  * Whether a specific VALUE of an option is `availability: 'planned'` for the
@@ -163,14 +186,32 @@ function compressGroupForToken(token) {
  * `compressMetadata` `per_value_availability`; same_format only (the only route
  * where value-level options like `metadata` are honored). Returns false when the
  * option / value / group is unknown (no gate).
+ *
+ * PURELY ADDITIVE (SB1wmTJz): planned if ANY consulted group marks this value planned.
+ * The historical group is still consulted, so **every verdict this returned before still
+ * holds** — the change can only turn a missed gate into a gate, never a gate into a
+ * pass. That direction matters: a new false ACCEPT would send a request the server
+ * rejects, which is the failure this function exists to prevent.
+ *
+ * Why not "most specific wins", which reads cleaner: it would flip `webp` +
+ * `color_profile: 'srgb'` from gated to un-gated, because `image_webp` defines
+ * `color_profile` with an empty `per_value_availability`. `RecipeOutputTest`
+ * deliberately pins webp srgb as GATED (v2.134 added `srgb: planned` to the generic
+ * group), and whether webp srgb actually works on the server is not something this
+ * layer can know. Un-gating it on an inference would be exactly the "confident answer
+ * from a check that could not tell you otherwise" pattern. Raised as a question instead.
+ *
+ * What this DOES fix: `image_svg` marks `output_format: 'original'` planned and the
+ * generic group does not, so an SVG input previously sailed through the one marker that
+ * mattered for it — on this gate and on the `output()` gate that shares it.
  */
 export function isPlannedValue(inputToken, optionKey, value) {
-    const group = compressMetadata.mime_groups[compressGroupForToken(inputToken)];
-    const opt = group?.options[optionKey];
-    if (opt === undefined)
-        return false;
-    const entry = opt.per_value_availability[String(value)];
-    return entry?.availability === 'planned';
+    for (const groupName of compressGroupsForToken(inputToken)) {
+        const opt = compressMetadata.mime_groups[groupName]?.options[optionKey];
+        if (opt?.per_value_availability[String(value)]?.availability === 'planned')
+            return true;
+    }
+    return false;
 }
 /**
  * Compress-route enum members per image mime-group, mirroring the shipped
@@ -232,3 +273,93 @@ export function isUnknownEnumValue(inputToken, optionKey, value) {
         return false;
     return !(typeof value === 'string' && members.includes(value));
 }
+/**
+ * Contract `depends_on` per compress-image output option, mirroring
+ * `availability.json` `operations.compress.mime_groups.<group>.options.<opt>.depends_on`
+ * (ehHU08Hu). The rule is option-consistent across every image group that carries
+ * the option, so this is a FLAT table (validated group-by-group by
+ * `output-route-conformance.test.ts` / PHP `ImageOutputRouteConformanceTest`).
+ *
+ * Kept as a hand table — NOT a runtime read of the ~238KB availability sidecar —
+ * so the gate stays browser-safe with no contracts-version coupling, exactly like
+ * {@link COMPRESS_OPTION_VALUES}. Mirrored by PHP
+ * `ImageOutputRoutes::OUTPUT_OPTION_DEPENDS_ON`.
+ *
+ * Generalises the 86gAu5Tr auto_quality gate: every option's dependency is
+ * checked uniformly, so quality/lossless/target_size_bytes under `auto_quality`,
+ * `target_size_bytes` without `target_size`, `fit` without width/height, etc. are
+ * all rejected pre-upload instead of only the one hand-coded case.
+ */
+export const OUTPUT_OPTION_DEPENDS_ON = {
+    quality: { requiresKey: 'encoding_mode', requiresValue: 'quality' },
+    lossless: { requiresKey: 'encoding_mode', requiresValue: 'quality' },
+    quality_preset: { requiresKey: 'encoding_mode', requiresValue: 'auto_quality' },
+    target_size_bytes: { requiresKey: 'encoding_mode', requiresValue: 'target_size' },
+    fit: { requiresAnyOf: ['width', 'height'] },
+};
+/**
+ * Default of each depended-on key — an ABSENT key resolves to this before the
+ * dependency check (the server applies the same default). `encoding_mode`
+ * defaults to `quality`, so `quality`/`lossless` are valid with no explicit mode,
+ * but `target_size_bytes` / `quality_preset` are not. Pinned to `availability.json`
+ * defaults by the conformance suite.
+ */
+export const DEPENDS_ON_KEY_DEFAULTS = {
+    encoding_mode: 'quality',
+};
+/**
+ * The first contract `depends_on` an already-lowered compress-image wire-option
+ * set violates for the resolved `route`, or `undefined` when every dependency is
+ * satisfied (ehHU08Hu). The caller ({@link Recipe} output lowering) throws
+ * `invalid_option_combination` with the returned message + conflictingFields.
+ * Only options PRESENT in `wireOptions` are checked; a scalar dependency reads
+ * the depended-on key's effective value ({@link DEPENDS_ON_KEY_DEFAULTS} when
+ * absent). A scalar (encoding_mode) dependency is skipped on a `format_change`
+ * (convert has its own deps); universal deps (e.g. `fit → width|height`, identical
+ * in compress + convert) run on BOTH routes. Mirrored by PHP
+ * `ImageOutputRoutes::dependsOnViolation`.
+ */
+export function dependsOnViolation(wireOptions, route) {
+    for (const [option, rule] of Object.entries(OUTPUT_OPTION_DEPENDS_ON)) {
+        // A nullish value is NOT "set" — the contract `set` condition needs a real
+        // value, and PHP drops null options before lowering, so treat null == absent
+        // for parity (codex: `{ fit: 'max', width: null }` must reject, not bypass).
+        if (wireOptions[option] == null)
+            continue;
+        if ('requiresAnyOf' in rule) {
+            if (!rule.requiresAnyOf.some((key) => wireOptions[key] != null)) {
+                return {
+                    conflictingFields: [option, ...rule.requiresAnyOf],
+                    message: `output(): '${option}' requires at least one of ${rule.requiresAnyOf.join(', ')} to be set ` +
+                        `(its contract dependency). Set ${rule.requiresAnyOf.join(' or ')}, or drop '${option}'.`,
+                };
+            }
+            continue;
+        }
+        // Scalar deps in this (compress-image) table are all on `encoding_mode`, a
+        // same_format optimiser key — validate them on same_format ONLY. The
+        // universal requiresAnyOf dep (fit → width|height) above runs on BOTH routes.
+        //
+        // A format_change routes via `convert`, which has no encoding_mode and carries
+        // its own deps — but those need NO table here (L2Ay7Uak, resolved as a no-op).
+        // Every convert image dep is keyed on `output_format`, and the per-target
+        // `honored` set the lowering already enforces IS that constraint materialised:
+        // `output('gif', { quality: 80 })` is rejected by the honored gate, with a
+        // better message, before this function runs. That equivalence is PINNED by
+        // `output-route-conformance.test.ts` (+ the PHP mirror), which fails closed if
+        // convert ever gains a dep keyed on something other than output_format — which
+        // is the case that would genuinely need a gate here.
+        if (route !== 'same_format')
+            continue;
+        const effective = wireOptions[rule.requiresKey] ?? DEPENDS_ON_KEY_DEFAULTS[rule.requiresKey];
+        if (effective !== rule.requiresValue) {
+            return {
+                conflictingFields: [rule.requiresKey, option],
+                message: `output(): '${option}' requires ${rule.requiresKey} '${rule.requiresValue}' (its contract ` +
+                    `dependency), but ${rule.requiresKey} is '${String(effective)}'. Set ${rule.requiresKey}: ` +
+                    `'${rule.requiresValue}', or drop '${option}'.`,
+            };
+        }
+    }
+    return undefined;
+}

package/dist/ergonomic/option_types.d.ts

@@ -137,6 +137,13 @@ export interface WatermarkOptions {
      * overlays on one base image (z-order = array index). MUTUALLY EXCLUSIVE with
      * the flat single-overlay options above; the server rejects mixing the two as
      * `invalid_options`. image_watermark jpeg/png/webp bases only.
+     *
+     * NOTE: NOT usable via `watermark()` yet — the facade composites a single
+     * overlay (the positional `overlay`, wire source src_1), so `overlays[]` would
+     * reference sources it cannot create. `watermark()` rejects it at lowering
+     * (`overlays_unsupported`); use the flat single-overlay options above instead.
+     * Kept as a valid contract wire key — multi-overlay stacking is a future
+     * feature (Vbbdq9C4).
      */
     overlays?: WatermarkOverlay[];
 }
@@ -154,9 +161,11 @@ export type OutputMetadata = 'strip' | 'keep';
  * Compression mode on the optimiser (same_format) route (contract `encoding_mode`
  * enum). `quality` (default) drives the encode by the quality slider; `target_size`
  * targets a byte budget via the worker's encode-measure loop — STABLE since
- * contracts v2.108.0 (jpeg/webp/avif).
+ * contracts v2.108.0 (jpeg/webp/avif). `auto_quality` lets the worker pick the
+ * quality from a named `quality_preset` (its `depends_on`) — the output lowering
+ * infers it for you when you set `quality_preset` without an `encoding_mode`.
  */
-export type OutputEncodingMode = 'quality' | 'target_size';
+export type OutputEncodingMode = 'quality' | 'target_size' | 'auto_quality';
 /** Chroma subsampling for JPEG output (contract `chroma_subsampling` enum, v2.110.0). `420` smallest → `444` highest fidelity. Honored: same_format jpeg only. */
 export type OutputChromaSubsampling = '420' | '422' | '444';
 /** ICC colour-profile handling (contract `color_profile` enum, v2.112.0). `keep` preserves the embedded profile; `srgb` converts to sRGB; `strip` removes it. Route/value availability is gated by the output lowering. */

package/dist/ergonomic/preset_resolver.d.ts

@@ -76,6 +76,28 @@ export interface ResolveCompressOptionsOutput {
  */
 export declare function _parseTargetSize(value: unknown): number;
 export declare const KNOWN_WIRE_FIELDS: Readonly<Record<PresetMedia, ReadonlySet<string>>>;
+/**
+ * Compress options that are `availability: planned` per mime-group, mirroring the
+ * shipped `availability/availability.json`
+ * `operations.compress.mime_groups.<group>.options.<opt>.availability`.
+ *
+ * Kept as a hand table (NOT a runtime read of the ~238KB availability sidecar) for
+ * the same reasons as {@link IMAGE_OUTPUT_ROUTES}: the gate stays browser-safe, and
+ * — decisively — it has NO dependency on which `@giveitsmaller/contracts` version a
+ * consumer resolved. A generated-metadata read would FAIL OPEN on an older published
+ * contracts (the rtkzl9gr failure mode), and fail-open is the wrong direction for a
+ * gate whose entire job is to fail closed.
+ *
+ * PINNED to `availability.json` by `tests/unit/preset-planned-conformance.test.ts`,
+ * which fails closed in BOTH directions — a contract regen that marks a new option
+ * `planned`, or unmarks one, breaks the build rather than the caller. Mirrored by PHP
+ * `PresetResolver::PLANNED_COMPRESS_OPTIONS`.
+ *
+ * `video.speed` is listed for a faithful projection even though no shipped preset
+ * cell emits it; the conformance test pins the whole projection, not just the keys
+ * we happen to use today.
+ */
+export declare const PLANNED_COMPRESS_OPTIONS: Readonly<Record<PresetMedia, ReadonlySet<string>>>;
 /**
  * Resolve the wire payload + introspection projection for a compress
  * operation call. Throws {@link GislConfigError} before any network

package/dist/ergonomic/preset_resolver.js

@@ -251,6 +251,20 @@ const MEDIA_FIELDS = Object.freeze({
     document_odf: new Set(['stripMetadata', 'stripUnusedStyles']),
     document_epub: new Set(['fontSubsetting', 'stripUnusedCss']),
 });
+const OUT = (key) => ({ verb: 'output', key });
+const CROSS_VERB_OVERRIDES = Object.freeze({
+    image: Object.freeze({
+        width: OUT('width'), height: OUT('height'), fit: OUT('fit'),
+        autoOrient: OUT('auto_orient'), colorProfile: OUT('color_profile'),
+        progressive: OUT('progressive'), lossless: OUT('lossless'),
+        qualityPreset: OUT('quality_preset'), encodingMode: OUT('encoding_mode'),
+        targetSizeBytes: OUT('target_size_bytes'), chromaSubsampling: OUT('chroma_subsampling'),
+        optimizationLevel: OUT('optimization_level'), avifSpeed: OUT('avif_speed'),
+    }),
+    // convert() takes the target format positionally, not as an option.
+    audio: Object.freeze({ outputFormat: { verb: 'convert', key: null } }),
+    video: Object.freeze({ outputFormat: { verb: 'convert', key: null } }),
+});
 function detectMismatchedOverrides(media, overrides) {
     const expected = MEDIA_FIELDS[media];
     const keys = Object.keys(overrides);
@@ -264,6 +278,37 @@ function detectMismatchedOverrides(media, overrides) {
     const unknownFields = keys.filter((k) => !expected.has(k));
     if (unknownFields.length === 0)
         return;
+    // Options that are real for THIS media but belong to another verb are
+    // answered with that verb, before the other-media guess below — otherwise a
+    // key both this media and another one recognises (image `width` vs video
+    // `width`) gets blamed on the wrong media.
+    // Classified PER FIELD, not all-or-nothing: `{ width, codec }` on an image
+    // must still tell the caller that `width` is a legal resize on output(),
+    // rather than reverting to "you passed video options" for the pair.
+    const crossVerb = CROSS_VERB_OVERRIDES[media];
+    const crossVerbFields = crossVerb === undefined ? [] : unknownFields.filter((k) => crossVerb[k] !== undefined);
+    if (crossVerbFields.length > 0 && crossVerb !== undefined) {
+        const strays = unknownFields.filter((k) => crossVerb[k] === undefined);
+        const byVerb = new Map();
+        for (const k of crossVerbFields) {
+            const target = crossVerb[k];
+            const list = byVerb.get(target.verb) ?? [];
+            list.push(target.key ?? k);
+            byVerb.set(target.verb, list);
+        }
+        const clauses = [...byVerb.entries()].map(([verb, keys]) => verb === 'convert'
+            ? `${keys.join(', ')} is the format argument of convert()`
+            : `${keys.join(', ')} ${keys.length === 1 ? 'is an option' : 'are options'} on ${verb}()`);
+        const outputKeys = byVerb.get('output');
+        throw new GislConfigError(`presetOverrides for '${media}' contained ${crossVerbFields.join(', ')}, which ${crossVerbFields.length === 1 ? 'does' : 'do'} not belong on the compress preset surface: ${clauses.join('; ')}.` +
+            (strays.length > 0 ? ` Also unrecognised for '${media}': ${strays.join(', ')}.` : ''), {
+            reason: 'type_mismatch',
+            conflictingFields: unknownFields,
+            suggestion: outputKeys !== undefined
+                ? `Move ${outputKeys.join(', ')} to output(): .output(format, { ${outputKeys[0]}: … }).`
+                : 'Use convert(format) to change the output format.',
+        });
+    }
     // Look up which OTHER media owns every unknown field — if a single
     // OTHER media's field set covers them all, that's a type_mismatch.
     for (const otherMedia of Object.keys(MEDIA_FIELDS)) {
@@ -319,6 +364,35 @@ export const KNOWN_WIRE_FIELDS = Object.freeze({
     document_odf: new Set(['strip_metadata', 'strip_unused_styles']),
     document_epub: new Set(['font_subsetting', 'strip_unused_css']),
 });
+/**
+ * Compress options that are `availability: planned` per mime-group, mirroring the
+ * shipped `availability/availability.json`
+ * `operations.compress.mime_groups.<group>.options.<opt>.availability`.
+ *
+ * Kept as a hand table (NOT a runtime read of the ~238KB availability sidecar) for
+ * the same reasons as {@link IMAGE_OUTPUT_ROUTES}: the gate stays browser-safe, and
+ * — decisively — it has NO dependency on which `@giveitsmaller/contracts` version a
+ * consumer resolved. A generated-metadata read would FAIL OPEN on an older published
+ * contracts (the rtkzl9gr failure mode), and fail-open is the wrong direction for a
+ * gate whose entire job is to fail closed.
+ *
+ * PINNED to `availability.json` by `tests/unit/preset-planned-conformance.test.ts`,
+ * which fails closed in BOTH directions — a contract regen that marks a new option
+ * `planned`, or unmarks one, breaks the build rather than the caller. Mirrored by PHP
+ * `PresetResolver::PLANNED_COMPRESS_OPTIONS`.
+ *
+ * `video.speed` is listed for a faithful projection even though no shipped preset
+ * cell emits it; the conformance test pins the whole projection, not just the keys
+ * we happen to use today.
+ */
+export const PLANNED_COMPRESS_OPTIONS = Object.freeze({
+    image: new Set([]),
+    audio: new Set([]),
+    video: new Set(['speed']),
+    document_office: new Set(['strip_hidden_data', 'strip_macros', 'strip_unused_fonts']),
+    document_odf: new Set(['strip_metadata', 'strip_unused_styles']),
+    document_epub: new Set(['font_subsetting', 'strip_unused_css']),
+});
 function validateMerged(media, merged, explicitKeys, winners) {
     // Unknown-field defence-in-depth: every key must belong to the
     // media's wire surface OR be one of the resolver-derived wire keys
@@ -527,6 +601,26 @@ export function resolveCompressOptions(input) {
         delete acc.merged.bitrate;
         acc.winners.delete('bitrate');
     }
+    // A shipped preset must never put an `availability: planned` option on the wire.
+    // The API rejects a planned option when the KEY IS PRESENT and ignores it when
+    // absent (`CreateWorkflowCommandHandler::recordPlannedFromMap` — a materialized
+    // default deliberately does NOT trigger it), so a value WE synthesized becomes a
+    // 422 `feature_not_available` at create that the caller never asked for. That is
+    // what broke every document compress with an `optimizeFor` in 0.21.0 (5Eksm9s7).
+    //
+    // Drop ONLY the sdkDefault-sourced ones. A planned option from any other layer is
+    // a caller choice — `clientDefault` and `scopedDefault` are user-registered via
+    // `gisl.create({ presetDefaults })` / `client.withPresetDefaults(...)`, not baked
+    // in by us — and is left in place for the server to refuse honestly. Same rule and
+    // same reason as the lossless-bitrate drop above: never silently swallow a key the
+    // caller chose. Do NOT "simplify" either of these into an always-drop; a silent
+    // no-op on an explicit request is worse than an honest 422.
+    for (const key of PLANNED_COMPRESS_OPTIONS[media]) {
+        if (acc.winners.get(key) === 'sdkDefault') {
+            delete acc.merged[key];
+            acc.winners.delete(key);
+        }
+    }
     // 7. Validate the merged payload (post-merge — catches cross-layer
     // disagreements). May throw GislConfigError with resolvedSnapshot.
     const explicitWireKeys = new Set();

package/dist/ergonomic/presets/image_compress.js

@@ -12,10 +12,22 @@
 // `mode` + `iccProfile` were REMOVED — the worker is lossy-only and always
 // strips metadata, so advertising a lossless mode or ICC-profile policy was
 // an over-claim. `progressive` is still a per-JPEG wire option but is no
-// longer carried in the preset cell. `width`/`height`/`fit`/`autoOrient`
-// were removed earlier — the image-compress worker never resized (resize-fit
-// lives on thumbnail/convert; video keeps its own fit). Per-call knobs are
-// deliberately excluded — they belong on the per-call argument shape.
+// longer carried in the preset cell.
+//
+// `width`/`height`/`fit`/`autoOrient` were removed earlier on the grounds that
+// "the image-compress worker never resized". CAREFUL — that is still true of
+// the Rust optimiser crate and NOT true end-to-end. Since contract v2.97.0
+// ("resize lives inside Output") the API canonicalises an image compress
+// carrying width/height/fit into a `convert` op, and convert IS the resize
+// engine, so such a request returns a genuinely resized file. Their absence
+// here is therefore a SURFACE choice, not a capability limit: resize is
+// expressed via `output()` (see `OutputOptions`), which the compress
+// conformance gate records as CROSS_VERB_ROUTING and self-verifies. Reading
+// this comment as "unsupported" is what produced cySAEZHR. Whether compress()
+// should ALSO carry them is an open ergonomic-expansion decision, not a bug.
+//
+// Per-call knobs are deliberately excluded — they belong on the per-call
+// argument shape.
 import { shippedDefaultsFor as f3ShippedDefaultsFor } from '../../generated/sdk_spec/presets.js';
 import { translateEnum } from './_translate.js';
 export class ImageCompressPresetOptions {

package/dist/ergonomic/presets/video_compress.d.ts

@@ -1,6 +1,20 @@
 import { VideoCodec, VideoPreset, VideoFit, AudioCodec, AudioBitrate, OptimizeFor } from '../../generated/sdk_spec/enums.js';
 export interface VideoCompressPresetOptionsInput {
     readonly codec?: VideoCodec;
+    /**
+     * Target output size (`'50MB'`-style string — BINARY units, 1 KB = 1024 — or a byte
+     * count). Derived by the resolver into `target_size_bytes` + `encoding_mode:
+     * 'target_size'`.
+     *
+     * **NOT AVAILABLE FOR LONG INPUTS.** A compress whose input duration routes to the
+     * long-form path rejects it (`reject_long_form_target_size`): 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 — routing is decided
+     * server-side at create-plan time, so there is nothing here to check it against.
+     * Short-form compresses honour it normally. Tracked by `zJN6XIi5`, blocked on a
+     * contract that can express per-execution-path availability. The same limit applies
+     * to {@link MergeOptions.targetSize}.
+     */
     readonly targetSize?: string | number;
     readonly crf?: number;
     readonly preset?: VideoPreset;

package/dist/errors.d.ts

@@ -159,6 +159,21 @@ export declare class GislBalanceExhaustedError extends GislApiError {
 export declare class GislLongFormConcurrencyError extends GislApiError {
     readonly payload: LongFormConcurrencyLimitResponse;
     constructor(statusCode: number, errorMessage: string, payload: LongFormConcurrencyLimitResponse, path?: string, extra?: Omit<GislApiErrorOptions, 'payload'>);
+    /**
+     * ALWAYS `false`, overriding the base 429-implies-retryable heuristic
+     * (UO1xYecu). This 429 is not a rate limit: it carries no `Retry-After` and
+     * clears only when an in-flight long-form workflow finishes, so a back-off
+     * retries into a wall that no amount of waiting-then-retrying opens. The base
+     * accessor reported `true` purely from the status, contradicting this class's
+     * own documented handling ("wait on completion or upgrade — do NOT back off")
+     * and instructing the one recovery that cannot work.
+     *
+     * Overridden per-class rather than via a code table because this is the only
+     * such code today; the general fix — an explicit taxonomy verdict outranking
+     * the status heuristic — arrives with the `error-taxonomy.yaml` `retryable`
+     * enum (contracts `plwcAqBr`), tracked on UO1xYecu.
+     */
+    get retryable(): boolean;
     /** The pricing / upgrade deep link (`links.upgrade`), or `undefined` when absent. */
     get upgradeUrl(): string | undefined;
 }
@@ -459,6 +474,44 @@ export declare class GislTimeoutError extends GislError {
     readonly workflowId?: string;
     constructor(message: string, workflowId?: string);
 }
+/**
+ * A `mapEach` fan-out timed out mid-batch — the deadline elapsed either while a
+ * child was still running (the common case) or cleanly between child runs. The
+ * parent and some children have ALREADY completed, so re-running the whole batch
+ * re-does finished work. This carries their ids so the caller can poll them (via
+ * `client.getWorkflowStatus` / `getWorkflowDownloads`) to recover the finished
+ * work and re-run ONLY the children that were never created.
+ *
+ * Subclasses {@link GislTimeoutError}, so an existing
+ * `catch (e) { if (e instanceof GislTimeoutError) … }` still catches it. The
+ * inherited `workflowId` carries the IN-FLIGHT child — the one that was running
+ * when the deadline elapsed (a child's own timeout, the common path) — or stays
+ * `undefined` when the deadline elapsed cleanly BETWEEN children (no in-flight
+ * child). To recover, poll `workflowId` (if set) + {@link parentWorkflowId} +
+ * {@link completedWorkflowIds}, then re-run only the children that never started.
+ *
+ * NOTE on double-charge: the server-side create-dedupe (DSxwCetg) is what
+ * prevents a byte-identical child re-create from settling a SECOND charge within
+ * the dedup window; this error's job is efficient RECOVERY (skip the completed
+ * work) + defense-in-depth, not the sole charge guard.
+ */
+export declare class GislFanOutTimeoutError extends GislTimeoutError {
+    /** The child workflows that completed before the deadline elapsed. */
+    readonly completedWorkflowIds: readonly string[];
+    /** The parent workflow, which ran to completion before the fan-out began. */
+    readonly parentWorkflowId?: string;
+    constructor(message: string, opts: {
+        completedWorkflowIds: readonly string[];
+        parentWorkflowId?: string;
+        /**
+         * The in-flight child that timed out mid-run (its own deadline elapsed);
+         * `undefined` for a clean between-children timeout with no child running.
+         */
+        workflowId?: string;
+        /** The underlying child {@link GislTimeoutError}, preserved for chaining. */
+        cause?: unknown;
+    });
+}
 /**
  * Transport-level failure: the underlying `fetch` (or other transport) could
  * not produce a usable response — DNS, TCP, TLS, a mid-stream disconnect, or a

package/dist/errors.js

@@ -172,6 +172,23 @@ export class GislLongFormConcurrencyError extends GislApiError {
         super(statusCode, errorMessage, path, undefined, buildOptionsWithPayload(payload, extra));
         this.name = 'GislLongFormConcurrencyError';
     }
+    /**
+     * ALWAYS `false`, overriding the base 429-implies-retryable heuristic
+     * (UO1xYecu). This 429 is not a rate limit: it carries no `Retry-After` and
+     * clears only when an in-flight long-form workflow finishes, so a back-off
+     * retries into a wall that no amount of waiting-then-retrying opens. The base
+     * accessor reported `true` purely from the status, contradicting this class's
+     * own documented handling ("wait on completion or upgrade — do NOT back off")
+     * and instructing the one recovery that cannot work.
+     *
+     * Overridden per-class rather than via a code table because this is the only
+     * such code today; the general fix — an explicit taxonomy verdict outranking
+     * the status heuristic — arrives with the `error-taxonomy.yaml` `retryable`
+     * enum (contracts `plwcAqBr`), tracked on UO1xYecu.
+     */
+    get retryable() {
+        return false;
+    }
     /** The pricing / upgrade deep link (`links.upgrade`), or `undefined` when absent. */
     get upgradeUrl() {
         return this.payload.links?.upgrade;
@@ -505,6 +522,43 @@ export class GislTimeoutError extends GislError {
         this.workflowId = workflowId === '' ? undefined : workflowId;
     }
 }
+/**
+ * A `mapEach` fan-out timed out mid-batch — the deadline elapsed either while a
+ * child was still running (the common case) or cleanly between child runs. The
+ * parent and some children have ALREADY completed, so re-running the whole batch
+ * re-does finished work. This carries their ids so the caller can poll them (via
+ * `client.getWorkflowStatus` / `getWorkflowDownloads`) to recover the finished
+ * work and re-run ONLY the children that were never created.
+ *
+ * Subclasses {@link GislTimeoutError}, so an existing
+ * `catch (e) { if (e instanceof GislTimeoutError) … }` still catches it. The
+ * inherited `workflowId` carries the IN-FLIGHT child — the one that was running
+ * when the deadline elapsed (a child's own timeout, the common path) — or stays
+ * `undefined` when the deadline elapsed cleanly BETWEEN children (no in-flight
+ * child). To recover, poll `workflowId` (if set) + {@link parentWorkflowId} +
+ * {@link completedWorkflowIds}, then re-run only the children that never started.
+ *
+ * NOTE on double-charge: the server-side create-dedupe (DSxwCetg) is what
+ * prevents a byte-identical child re-create from settling a SECOND charge within
+ * the dedup window; this error's job is efficient RECOVERY (skip the completed
+ * work) + defense-in-depth, not the sole charge guard.
+ */
+export class GislFanOutTimeoutError extends GislTimeoutError {
+    /** The child workflows that completed before the deadline elapsed. */
+    completedWorkflowIds;
+    /** The parent workflow, which ran to completion before the fan-out began. */
+    parentWorkflowId;
+    constructor(message, opts) {
+        // The inherited workflowId is the in-flight child (or undefined between children).
+        super(message, opts.workflowId);
+        this.name = 'GislFanOutTimeoutError';
+        this.completedWorkflowIds = [...opts.completedWorkflowIds];
+        this.parentWorkflowId = opts.parentWorkflowId === '' ? undefined : opts.parentWorkflowId;
+        if (opts.cause !== undefined) {
+            this.cause = opts.cause;
+        }
+    }
+}
 /**
  * Transport-level failure: the underlying `fetch` (or other transport) could
  * not produce a usable response — DNS, TCP, TLS, a mid-stream disconnect, or a

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, isUnknownEnumValue, 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),
@@ -1101,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 ` +
@@ -1122,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 ` +
@@ -1147,6 +1149,28 @@ export class Recipe {
             }
             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 };
     }
     /**
@@ -1466,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 };
 }
@@ -1489,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).

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" | "image_dimensions_too_large" | "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",
@@ -506,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([
@@ -522,20 +658,28 @@ export const ERROR_CATEGORIES = Object.freeze({
         "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",
@@ -551,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/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, GislLongFormConcurrencyError, 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';

package/dist/index.core.js

@@ -11,7 +11,10 @@ export { uploadSource, jobOutputSource, externalImportSource, connectionSource,
 // Errors
 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, 

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;

package/dist/sse.js

@@ -105,7 +105,55 @@ export async function* parseSseStream(response, opts = {}) {
                     continue;
                 }
                 if (line.startsWith(':')) {
-                    // Comment line (keep-alive), skip
+                    // Comment line (keep-alive), skip.
+                    //
+                    // ⚠️ DO NOT "FIX" THIS INTO SURFACING COMMENT FRAMES WITHOUT READING
+                    // THIS. Dropping them is CORRECT per the SSE spec — a comment carries
+                    // no event — but it is also LOAD-BEARING FOR A CONSUMER, and that
+                    // consumer is in another repo.
+                    //
+                    // The frontend does NOT close its SSE reader on the terminal event:
+                    // `workflow_completed` patches status and breaks WITHOUT aborting.
+                    // What actually closes the stream is an IDLE WATCHDOG at 20s. That
+                    // watchdog only fires because heartbeats are never yielded here, so
+                    // they never re-arm it — roughly 20s after the last real event the
+                    // reader closes and the PHP worker is released.
+                    //
+                    // HEARTBEAT ~16s vs IDLE TIMEOUT 20s: a FOUR-SECOND MARGIN that holds
+                    // only while the heartbeats are invisible. Surfacing comment frames —
+                    // a completely reasonable change, since EventSource semantics treat
+                    // keep-alive comments as liveness signals that legitimately reset
+                    // timeouts — would CONTINUOUSLY re-arm the watchdog. The stream would
+                    // never go idle, and every completed job left on screen would hold a
+                    // PHP worker for the full 570s. That is worker exhaustion from
+                    // ordinary users leaving tabs open.
+                    //
+                    // A ONE-LINE CHANGE HERE SILENTLY CONVERTS THE FRONTEND FROM BOUNDED
+                    // TO UNBOUNDED, and nothing on either side would flag it.
+                    //
+                    // ⚠️ THIS NOTE IS PERMANENT. DO NOT DELETE IT WHEN THE FRONTEND
+                    // ADDS AN EXPLICIT CLOSE-ON-TERMINAL. That fix removes the TERMINAL
+                    // case and does NOT remove the dependency, because closing finished
+                    // streams was never the watchdog's job — that was a side effect
+                    // nobody knew about until 2026-08-12.
+                    //
+                    // THE WATCHDOG'S ACTUAL JOB IS DETECTING A STREAM THAT HAS GONE
+                    // SILENT WHILE THE WORKFLOW IS STILL RUNNING, and resuming the
+                    // fallback poll. That case survives every fix in flight, and it is
+                    // not exotic: a long operation between progress events produces it
+                    // exactly — heartbeats flowing, no data frames, job still running.
+                    //
+                    // If this parser surfaced comment frames, heartbeats at ~16s would
+                    // re-arm the 20s watchdog FOREVER and STALL DETECTION WOULD NEVER
+                    // FIRE AT ALL, on a stream that is genuinely stuck. The UI would go
+                    // on believing a dead job is fine. That is worse than the worker
+                    // leak: a leak is bounded by 570s, a missed stall is not bounded at
+                    // all.
+                    //
+                    // The PHP SDK does the same thing at GislClient.php (`$line[0] === ':'`),
+                    // verified 2026-08-12 — the two languages agree on this axis, and
+                    // they must stay agreed: this property governs whether a stuck
+                    // stream is EVER detected, so a divergence here is not cosmetic.
                     continue;
                 }
                 const colonIndex = line.indexOf(':');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@giveitsmaller/sdk",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "Node.js SDK for the GISL (Give It Smaller) file compression and processing API",
   "license": "Apache-2.0",
   "type": "module",
@@ -31,7 +31,7 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@giveitsmaller/contracts": "^0.59.0"
+    "@giveitsmaller/contracts": "^0.65.0"
   },
   "devDependencies": {
     "@types/node": "^22",