@giveitsmaller/sdk 0.21.0 → 0.25.0

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,26 @@
 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.
+     * The same limit applies to {@link MergeOptions.targetSize}.
+     * Short-form compresses honour it normally.
+     *
+     * The contract CAN now express this — `per_class_availability` scopes an option to
+     * a processing class, vendored at v2.195.0 and pinned by
+     * `tests/unit/per-class-availability-conformance.test.ts`. That buys an honest 422
+     * from the API at CREATE rather than a job dying mid-execution; it does NOT become
+     * a client-side gate, because routing is still decided server-side and a duration
+     * heuristic here would be wrong at the boundary. Tracked by `zJN6XIi5`.
+     */
     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;
 }
@@ -374,6 +389,31 @@ export declare class GislConfigError extends GislError {
 export declare class GislMissingCredentialsError extends GislConfigError {
     constructor(message: string);
 }
+/**
+ * `streamEvents` was called on a client whose configuration has **no declared
+ * SSE stream host**. Local-only — thrown before any I/O.
+ *
+ * ⚠️ **THIS ERROR IS A CONTROL, NOT A DEFECT.** The stream lives on a second
+ * host, and the SDK will not guess it from `baseUrl`. Deriving `stream.*` from
+ * `api.*` by string surgery is a *convention*, and a convention is precisely
+ * what put production on the gateway path: the frontend's prod build had no
+ * stream host configured, fell back to the API host silently, and the failure
+ * was invisible until it was measured. Raising here is the loud version of
+ * that same situation.
+ *
+ * Both named environments resolve as of contracts `v2.195.0` (#410), which
+ * declared the production stream host. This now fires only for a
+ * configuration nothing declares — e.g. a bare `baseUrl` with no
+ * `environment` and no `streamBaseUrl`.
+ *
+ * Recover by passing `{streamBaseUrl}` to `gisl.create()` / `new GislClient()`,
+ * setting `GISL_STREAM_BASE_URL`, or constructing with an `{environment}` that
+ * declares one. `run()` does NOT surface this error — it treats an undeclared
+ * stream host as "SSE unavailable for this configuration" and polls instead.
+ */
+export declare class GislStreamHostNotDeclaredError extends GislConfigError {
+    constructor(message: string);
+}
 /**
  * The caller used `gisl.anonymous()` and then invoked an operation that is
  * not in the anonymous-capable allowlist. Local-only — thrown before any I/O.
@@ -460,17 +500,153 @@ export declare class GislTimeoutError extends GislError {
     constructor(message: string, workflowId?: string);
 }
 /**
- * Transport-level failure: the underlying `fetch` (or other transport) could
- * not produce a usable response — DNS, TCP, TLS, a mid-stream disconnect, or a
- * non-ok status / empty body when fetching a result download. Mirrors the PHP
- * `Gisl\Sdk\Errors\GislNetworkError`. Subclasses `GislError` (not
- * `GislApiError`) because it carries no contract error envelope. The concrete
- * file-first {@link Downloader} raises this when the output URL cannot be read
- * (a destination-WRITE failure is `GislSinkError` reason `write_failed`).
+ * 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;
+    });
+}
+/**
+ * Base for every failure that happened **off the contract envelope** — the
+ * request did not come back as a typed API error, it came back (or failed to)
+ * at the transport or raw-HTTP level. Subclasses `GislError` rather than
+ * `GislApiError` because there is no error envelope to carry.
+ *
+ * ⚠️ **NEVER THROWN DIRECTLY — it is a hierarchy node, not an error code
+ * (`t2qCrjdr`).** Everything that used to throw it now throws
+ * {@link GislTransportError} or {@link GislDownloadHttpError}, because the two
+ * cases cannot share one honest answer to "should I retry this?":
+ *
+ * | case | retry? |
+ * |---|---|
+ * | DNS / TCP / TLS / mid-stream disconnect | **yes** — transient by nature |
+ * | a `404` on a signed download URL | **no** — permanent, retrying burns time |
+ *
+ * `retryable: true` would recommend retrying a permanent failure and
+ * `retryable: false` would discourage retrying a genuine transient one, so
+ * contracts correctly refused to declare this class in
+ * `sdk-spec/error-taxonomy.yaml` at all. The fix is the split, not a caveat in
+ * a description field: **a claim must hold on every path that reaches it.**
+ *
+ * **Kept as the base ON PURPOSE, so this is not a breaking change.** Every
+ * existing `catch (e) { if (e instanceof GislNetworkError) … }` — including the
+ * SSE poll-fallback in `builder.ts` / `merge.ts` / `handle.ts` /
+ * `file-first.ts` — keeps catching exactly what it caught before. Narrow to a
+ * subclass only where you actually need to tell the two apart.
+ *
+ * Mirrors the PHP `Gisl\Sdk\Errors\GislNetworkError`.
  */
 export declare class GislNetworkError extends GislError {
     constructor(message: string);
 }
+/**
+ * The transport could not deliver a usable response: DNS, TCP, TLS, a
+ * mid-stream disconnect, a `fetch` rejection, or a 2xx that arrived with no
+ * body at all. **Always retryable** — nothing about these says the request was
+ * wrong, only that it did not get through.
+ *
+ * The empty-body case lives here rather than with
+ * {@link GislDownloadHttpError} deliberately: the server said 2xx, so it is not
+ * an HTTP-level refusal — a response that promised bytes and delivered none is
+ * a delivery failure, and retrying is the right advice.
+ *
+ * The concrete file-first `Downloader` raises this when an output URL cannot be
+ * read (a destination-WRITE failure is `GislSinkError` reason `write_failed`).
+ */
+export declare class GislTransportError extends GislNetworkError {
+    constructor(message: string);
+    /**
+     * Always `true`. The request did not get through; nothing about that says it
+     * was wrong, so retrying is the correct advice.
+     *
+     * Present as a real accessor rather than only as prose — an unbacked claim in
+     * a docblock is the exact defect `t2qCrjdr` exists to remove, and shipping
+     * the split without it would have reproduced it one level down.
+     */
+    get retryable(): boolean;
+}
+/**
+ * The request was never put on the wire because the client refused to send it —
+ * a malformed URI or an otherwise unsendable request. **Never retryable:**
+ * re-issuing the identical request fails identically, so backing off only
+ * wastes the caller's deadline.
+ *
+ * ⚠️ **THE TWO LANGUAGES DETECT THIS DIFFERENTLY, AND TS DETECTS LESS.** PSR-18
+ * distinguishes a network failure (`NetworkExceptionInterface`) from an
+ * unsendable request (`RequestExceptionInterface`), so the PHP SDK classifies
+ * every such failure. `fetch` surfaces both as an indistinguishable
+ * `TypeError`, so the TS SDK can only catch the cases it can see BEFORE the
+ * call — today, a URL that does not parse (`http-downloader`). A `fetch`
+ * rejection is still reported as {@link GislTransportError}, because guessing
+ * would put a permanent failure back in the retryable bucket, which is the very
+ * thing this split removed.
+ *
+ * So: same class, same meaning, same `retryable` in both SDKs — narrower
+ * detection in TypeScript. Stated here because a cross-language consumer would
+ * otherwise reasonably assume parity of COVERAGE from parity of TYPE.
+ */
+export declare class GislRequestNotSentError extends GislNetworkError {
+    constructor(message: string);
+    /** Always `false` — the request never left, and re-sending it will not change that. */
+    get retryable(): boolean;
+}
+/**
+ * A download URL answered with a **non-2xx status**. The server was reached and
+ * replied; it simply refused. Distinct from {@link GislTransportError} because
+ * retrying is usually pointless — and `retryable` says so honestly, derived
+ * from the status rather than fixed for the class.
+ *
+ * `status` is carried as a field so a consumer distinguishing a permanent `404`
+ * from a transient `503` does not have to parse the message string — the second
+ * half of `t2qCrjdr`.
+ *
+ * Raised on result-download fetches (signed URLs), NOT on GISL-API calls: an
+ * API non-2xx carries a contract error envelope and surfaces as the matching
+ * {@link GislApiError} subclass instead.
+ */
+export declare class GislDownloadHttpError extends GislNetworkError {
+    /** The HTTP status the download URL responded with. */
+    readonly status: number;
+    constructor(message: string, status: number);
+    /**
+     * Whether retrying this download could plausibly succeed. Derived from the
+     * status by the same rule the API errors use (`408` / `429` / `5xx`), so a
+     * `404` reports `false` and a `503` reports `true` — the distinction the
+     * unsplit class could not express.
+     */
+    get retryable(): boolean;
+}
 /**
  * Internal control-flow marker (TDqmkWpX): the SSE event stream closed cleanly
  * WITHOUT a terminal (`workflow_completed`/`failed`/`partially_failed`) event.