@giveitsmaller/sdk 0.20.0 → 0.22.0

package/dist/client.js

@@ -4,8 +4,8 @@
 // blobByteSource, which never touches these). Kept as a STATIC import (not a
 // dynamic one) so `vi.mock('node:fs/promises')` still intercepts it in tests.
 import { open, stat, basename } from './node-fs.js';
-import { AudioWatermarkDecodeRequestToJSON, AudioWatermarkDecodeResponseFromJSON, ExternalImportCreatedResponseFromJSON, ExternalImportRequestToJSON, LoginUser200ResponseDataFromJSON, AccountLimitsFromJSON, CreditsBalanceResponseFromJSON, CreditsUsageResponseFromJSON, UploadResponseFromJSON, UploadProbeResponseFromJSON, MultipartInitiateResponseFromJSON, MultipartInitiateRequestMetadataHintToJSON, MultipartCompleteResponseFromJSON, MultipartCompleteRequestToJSON, WorkflowCancelResponseFromJSON, WorkflowCreateResponseFromJSON, WorkflowResumeResponseFromJSON, WorkflowStatusResponseFromJSON, WorkflowListResponseFromJSON, WorkflowDownloadResponseFromJSON, MetadataResponseFromJSON, OperationsSchemaResponseFromJSON, RetryResponseFromJSON, WorkflowStatus, AuthErrorResponseFromJSON, AuthErrorType, AuthRejectionEnvelopeFromJSON, AuthRejectionEnvelopeErrorTypeEnum, BalanceExhaustedResponseFromJSON, BalanceExhaustedResponseRequiredActionEnum, FeatureNotAvailableResponseFromJSON, FeatureTierRestrictedResponseFromJSON, TierRestrictionKind, TierRestrictionResponseFromJSON, UserTier, WorkflowExpiredResponseFromJSON, ProbePendingResponseFromJSON, UploadSizeExceedsTierResponseFromJSON, UploadDurationExceedsTierResponseFromJSON, UploadConstraintsAppliedProcessingClassPreAssignmentEnum, UploadThresholdsSingleShotMaxBytesEnum, UploadThresholdsMultipartChunkSizeEnum, UploadThresholdsMultipartConcurrencyDefaultEnum, } from '@giveitsmaller/contracts/openapi';
-import { GislAbortError, GislApiError, GislAuthError, GislAuthRejectionError, GislBalanceExhaustedError, GislError, GislFeatureNotAvailableError, GislFeatureTierRestrictedError, GislMultipartPartCountError, GislMultipartPartError, GislMultipartSessionNotFoundError, GislMultipartSessionOwnershipError, GislMultipartSessionAuthRequiredError, GislTierRestrictedError, GislTimeoutError, GislProbePendingError, GislUploadCapExceededError, GislValidationError, GislWorkflowExpiredError, } from './errors.js';
+import { AudioWatermarkDecodeRequestToJSON, AudioWatermarkDecodeResponseFromJSON, ExternalImportCreatedResponseFromJSON, ExternalImportRequestToJSON, LoginUser200ResponseDataFromJSON, AccountLimitsFromJSON, CreditsBalanceResponseFromJSON, CreditsUsageResponseFromJSON, UploadResponseFromJSON, UploadProbeResponseFromJSON, MultipartInitiateResponseFromJSON, MultipartInitiateRequestMetadataHintToJSON, MultipartCompleteResponseFromJSON, MultipartCompleteRequestToJSON, WorkflowCancelResponseFromJSON, WorkflowCreateResponseFromJSON, WorkflowResumeResponseFromJSON, WorkflowStatusResponseFromJSON, WorkflowListResponseFromJSON, WorkflowDownloadResponseFromJSON, MetadataResponseFromJSON, OperationsSchemaResponseFromJSON, RetryResponseFromJSON, WorkflowStatus, AuthErrorResponseFromJSON, AuthErrorType, AuthRejectionEnvelopeFromJSON, AuthRejectionEnvelopeErrorTypeEnum, BalanceExhaustedResponseFromJSON, BalanceExhaustedResponseRequiredActionEnum, FeatureNotAvailableResponseFromJSON, FeatureTierRestrictedResponseFromJSON, LongFormConcurrencyLimitResponseFromJSON, TierRestrictionKind, TierRestrictionResponseFromJSON, UserTier, WorkflowExpiredResponseFromJSON, ProbePendingResponseFromJSON, UploadSizeExceedsTierResponseFromJSON, UploadDurationExceedsTierResponseFromJSON, UploadConstraintsAppliedProcessingClassPreAssignmentEnum, UploadThresholdsSingleShotMaxBytesEnum, UploadThresholdsMultipartChunkSizeEnum, UploadThresholdsMultipartConcurrencyDefaultEnum, } from '@giveitsmaller/contracts/openapi';
+import { GislAbortError, GislApiError, GislAuthError, GislAuthRejectionError, GislBalanceExhaustedError, GislError, GislFeatureNotAvailableError, GislFeatureTierRestrictedError, GislLongFormConcurrencyError, GislMultipartPartCountError, GislMultipartPartError, GislMultipartSessionNotFoundError, GislMultipartSessionOwnershipError, GislMultipartSessionAuthRequiredError, GislTierRestrictedError, GislTimeoutError, GislProbePendingError, GislUploadCapExceededError, GislValidationError, GislWorkflowExpiredError, } from './errors.js';
 // The `Retry-After` millisecond parser lives in the shared retry-metadata
 // module (extracted to break the client ↔ errors circular import); re-imported
 // here so the retry-loop timing stays byte-identical.
@@ -59,7 +59,25 @@ const S3_MAX_MULTIPART_PARTS = 10_000;
 // exists to prevent). codex review (high).
 const RECOMMENDED_CHUNK_SIZE_MAX_BYTES = 104_857_600; // 100 MiB
 const DEFAULT_POLL_INTERVAL_MS = 2_000;
-const DEFAULT_POLL_TIMEOUT_MS = 300_000; // 5 min
+const DEFAULT_POLL_TIMEOUT_MS = 600_000; // 10 min
+/**
+ * Re-tag a bare per-request transport {@link GislTimeoutError} with the workflow
+ * it was scoped to, so a timed-out workflow read (status / downloads) stays
+ * recoverable. No-op for any other error and for a timeout that already carries
+ * an id. See `oYumKo6y`. (PHP transport failures surface as `GislNetworkError`,
+ * so this enrichment is TS-only.)
+ */
+function withWorkflowIdOnTimeout(err, workflowId) {
+    if (!(err instanceof GislTimeoutError) || err.workflowId !== undefined)
+        return err;
+    const enriched = new GislTimeoutError(err.message, workflowId);
+    // Preserve the original throw site + chain the cause — the enriched error is
+    // a re-tag, not a new failure, so diagnostics should still point at the
+    // transport timeout.
+    enriched.stack = err.stack;
+    enriched.cause = err;
+    return enriched;
+}
 // Anonymous-read capability header. An anonymous (null-owner) workflow create
 // returns a one-time `cap` token (WorkflowCreateResponse.cap); the session-less
 // caller passes it back on status/downloads/events reads via this header so the
@@ -98,6 +116,18 @@ function headersToRecord(headers) {
     });
     return r;
 }
+// Canonical human-readable fallback when a failure envelope carries NO `message`
+// field. Kept IDENTICAL to the PHP SDK (`GislClient::fallbackErrorMessage`) so a
+// message-absent error surfaces byte-identical `.message` text across SDKs
+// (card U7MACpOj). Used by BOTH error-construction paths (`handleResponse` and
+// the `getSchema` raw-response path) so they cannot drift. The machine code
+// stays on `.errorCode` — this string is human DISPLAY text only; never parse
+// it. `error` absent → `unknown_error` (PHP parity). Historically TS leaked the
+// SCREAMING_SNAKE `error` code as `.message`, diverging from PHP's synthetic
+// sentence; this unifies them on the human-shaped form.
+function fallbackErrorMessage(status, errorCode) {
+    return `Request failed with status ${status} (${errorCode ?? 'unknown_error'}).`;
+}
 function isValidationDetails(value) {
     return (Array.isArray(value) &&
         value.length > 0 &&
@@ -484,13 +514,16 @@ export class GislClient {
             };
             // Human-readable text comes from `message` (the I26 localised field).
             // `error` is the stable, never-localised SCREAMING_SNAKE machine code —
-            // NOT display text. Surfacing `error` as the thrown error's `.message`
-            // regressed consumers that render the human string (x9Lbf6uy). Fall back
-            // to `error` when `message` is absent (deployed contract guarantees
-            // `message` on conforming error envelopes). Machine dispatch keys off
-            // `error_type` (below), unchanged.
+            // NOT display text (surfacing it as `.message` regressed consumers that
+            // render the human string, x9Lbf6uy). When `message` is absent (the
+            // deployed contract guarantees it on conforming error envelopes), fall
+            // back to the canonical synthetic sentence — byte-identical to the PHP
+            // SDK — instead of leaking the machine code (card U7MACpOj). The code is
+            // still carried on `.errorCode`. Machine dispatch keys off `error_type`
+            // (below), unchanged.
             const status = response.status;
-            const errorMessage = json.message ?? json.error ?? 'Unknown error';
+            const errorMessage = json.message ??
+                fallbackErrorMessage(status, typeof json.error === 'string' ? json.error : undefined);
             // Validation-details branch first — preserve existing shape so callers
             // matching on `instanceof GislValidationError` keep working.
             if (isValidationDetails(json.details)) {
@@ -595,6 +628,15 @@ export class GislClient {
                 tryThrowCap(UploadDurationExceedsTierResponseFromJSON, 'duration_tier', (p) => isInEnum(p.currentTier, UserTier) &&
                     typeof p.maxDurationSeconds === 'number');
             }
+            // Long-form concurrency limit (429) — a TIER quota, DISTINCT from a
+            // generic infra rate-limit 429. Dispatched on the machine `error` CODE
+            // (this envelope carries NO `error_type`); a generic rate-limit 429 has a
+            // different/absent code, so it falls through to the base GislApiError
+            // where `retryAfterSeconds` applies. The validator re-asserts the code so
+            // a malformed envelope falls through rather than mis-typing.
+            if (status === 429 && json.error === 'LONG_FORM_CONCURRENCY_LIMIT_EXCEEDED') {
+                tryThrowStructured(LongFormConcurrencyLimitResponseFromJSON, GislLongFormConcurrencyError, (p) => p.error === 'LONG_FORM_CONCURRENCY_LIMIT_EXCEEDED');
+            }
             // 413 = the absolute across-tier cap. The contract models 413 as a
             // plain `ErrorEnvelope` (no `error_type` discriminator, no typed
             // payload — api.yaml), so dispatch purely on status with no FromJSON
@@ -1603,10 +1645,15 @@ export class GislClient {
      * authenticated reads. A wrong/missing cap on a null-owner workflow is a 404.
      */
     async getWorkflowStatus(workflowId, opts = {}) {
-        return this.request('GET', `/api/workflows/${encodeURIComponent(workflowId)}/status`, {
-            deserialize: WorkflowStatusResponseFromJSON,
-            headers: workflowCapabilityHeaders(opts.capability),
-        });
+        try {
+            return await this.request('GET', `/api/workflows/${encodeURIComponent(workflowId)}/status`, {
+                deserialize: WorkflowStatusResponseFromJSON,
+                headers: workflowCapabilityHeaders(opts.capability),
+            });
+        }
+        catch (err) {
+            throw withWorkflowIdOnTimeout(err, workflowId);
+        }
     }
     /**
      * Poll until the workflow reaches a terminal status.
@@ -1624,7 +1671,7 @@ export class GislClient {
                 return status;
             }
             if (Date.now() + intervalMs > deadline) {
-                throw new GislTimeoutError(`Workflow ${workflowId} did not complete within ${timeoutMs}ms`);
+                throw new GislTimeoutError(`Workflow ${workflowId} did not complete within ${timeoutMs}ms`, workflowId);
             }
             await new Promise((resolve) => setTimeout(resolve, intervalMs));
         }
@@ -1681,10 +1728,15 @@ export class GislClient {
      * authenticated reads. A wrong/missing cap on a null-owner workflow is a 404.
      */
     async getWorkflowDownloads(workflowId, opts = {}) {
-        return this.request('GET', `/api/workflows/${encodeURIComponent(workflowId)}/downloads`, {
-            deserialize: WorkflowDownloadResponseFromJSON,
-            headers: workflowCapabilityHeaders(opts.capability),
-        });
+        try {
+            return await this.request('GET', `/api/workflows/${encodeURIComponent(workflowId)}/downloads`, {
+                deserialize: WorkflowDownloadResponseFromJSON,
+                headers: workflowCapabilityHeaders(opts.capability),
+            });
+        }
+        catch (err) {
+            throw withWorkflowIdOnTimeout(err, workflowId);
+        }
     }
     /**
      * Stream SSE events for a workflow. Returns an async iterable.
@@ -1862,22 +1914,26 @@ export class GislClient {
             return { notModified: true, etag, lastModified };
         }
         if (!response.ok) {
-            let errorMessage = 'Unknown error';
             let errorCode;
+            // Seed with the canonical synthetic sentence (unknown_error) so the
+            // message-absent JSON branch below reuses the SAME helper as
+            // handleResponse + PHP — that message-absent JSON envelope is the
+            // U7MACpOj parity target. A non-JSON body is a rare edge that keeps
+            // this seed (it does NOT claim byte-parity with PHP's non-JSON path,
+            // which throws a distinct GislError).
+            let errorMessage = fallbackErrorMessage(response.status, undefined);
             try {
                 const errJson = (await response.json());
-                // Prefer the human `message`; `error` is the machine code (x9Lbf6uy).
-                if (errJson.message)
-                    errorMessage = errJson.message;
-                else if (errJson.error)
-                    errorMessage = errJson.error;
                 // Surface the machine code as errorCode too (parity with handleResponse
                 // + PHP), even when `message` supplied the human text.
                 if (typeof errJson.error === 'string')
                     errorCode = errJson.error;
+                // Prefer the human `message`; else the canonical synthetic sentence —
+                // NOT the raw machine code (x9Lbf6uy / U7MACpOj).
+                errorMessage = errJson.message ?? fallbackErrorMessage(response.status, errorCode);
             }
             catch {
-                // Non-JSON body — keep generic message, no machine code.
+                // Non-JSON body — keep the generic synthetic message, no machine code.
             }
             // This throw is OUTSIDE handleResponse (rawResponse:true / 304 path), so
             // build the response-header surface from the in-scope `response` here.
@@ -1949,15 +2005,18 @@ export class GislClient {
      * via that cookie when the client is configured with
      * `useSessionCookie: true`.
      *
-     * Failure modes per ticket FX6mbTJD:
-     * - **401** `invalid_credentials` (collapsed with unverified
-     *   accounts for anti-enumeration) → `GislAuthError`.
-     * - **403** account-state failures (`account_locked`,
-     *   `account_disabled`, `account_deleted`,
-     *   `account_deletion_expired`) → `GislAuthError`.
+     * Failure modes per ticket FX6mbTJD (login narrowed at contracts
+     * v2.166.0 authsec — no 403 account-state branch on login):
+     * - **401** `invalid_credentials` (wrong password, unverified, OR
+     *   unknown account — all collapsed for anti-enumeration) →
+     *   `GislAuthError`.
      * - **429** infrastructure rate-limit → `GislApiError` with
      *   the `Retry-After` header echoed on the response.
      *
+     * The account-status error types (`account_locked` / `account_disabled`
+     * / `account_deleted` / `account_deletion_expired`) still exist but are
+     * emitted on the API-key path + live-session enforcement, not on login.
+     *
      * Node session persistence (cookie-jar across processes) is out of
      * scope — this method only touches the request side.
      */

package/dist/ergonomic/image_output_routes.d.ts

@@ -85,6 +85,103 @@ 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;
+/**
+ * Compress-route enum members per image mime-group, mirroring the shipped
+ * `availability/availability.json` `operations.compress.mime_groups.<group>.
+ * options.<opt>.values`. Kept as a hand table (NOT a runtime read of the ~238KB
+ * availability sidecar) so the enum-membership gate stays browser-safe, exactly
+ * like {@link IMAGE_OUTPUT_ROUTES} — and, crucially, so the gate has NO
+ * dependency on a contracts version that carries the enum in a compact form (a
+ * generated-metadata `values` field would fail open on an older published
+ * `@giveitsmaller/contracts`). PINNED to `availability.json` by
+ * `output-route-conformance.test.ts`; a contract regen that adds/changes an
+ * enum member fails there. Mirrored by PHP `ImageOutputRoutes::COMPRESS_OPTION_VALUES`.
+ *
+ * `image_svg`/`image_avif` carry the NARROW `metadata: ['strip','all']` (no
+ * `keep`) — the reason a value gate that consulted only the generic `image`
+ * group (`['strip','keep','all']`) let `metadata: 'keep'` reach a server 422 on
+ * those bases (rtkzl9gr). `output_format` is listed for a faithful projection
+ * mirror but is never gated here (the Output lowering owns it positionally).
+ */
+export declare const COMPRESS_OPTION_VALUES: Readonly<Record<string, Readonly<Record<string, readonly string[]>>>>;
+/**
+ * Whether a VALUE lies OUTSIDE the option's compress-route enum for the given
+ * input format — the pre-upload enum-membership gate (rtkzl9gr). Reads the hand
+ * {@link COMPRESS_OPTION_VALUES} table. Returns false when the option is not an
+ * enum on this group (no entry), so a non-enum option (e.g. integer `quality`)
+ * is never gated. Meaningful only on the same_format (compress) route, where
+ * the compress option enums definitionally apply. Membership is STRICT: a value
+ * whose type differs from the string enum members (e.g. numeric `420`) is
+ * 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

@@ -29,8 +29,18 @@
 import { compressMetadata } from '@giveitsmaller/contracts/operations';
 /** The resize option keys — input-keyed, raster-only (see module doc). */
 export const RESIZE_KEYS = ['width', 'height', 'fit'];
-/** Set form of {@link RESIZE_KEYS} for `string`-keyed membership tests. */
-const RESIZE_KEY_SET = new Set(RESIZE_KEYS);
+/**
+ * Options whose availability follows the INPUT format's raster capability, not
+ * the output format — resize (`width`/`height`/`fit`) plus `auto_orient`. The
+ * projection lists them on every `format_change` cell (keyed by OUTPUT), so on
+ * a format change they must be re-gated against the INPUT's `same_format` cell:
+ * a raster input carries them, an SVG (vector) input does not. Before rtkzl9gr
+ * only the resize keys were input-gated, so `auto_orient` leaked onto the
+ * `svg → raster` route and was rejected server-side.
+ */
+const INPUT_GATED_KEYS = [...RESIZE_KEYS, 'auto_orient'];
+/** Set form of {@link INPUT_GATED_KEYS} for `string`-keyed membership tests. */
+const INPUT_GATED_KEY_SET = new Set(INPUT_GATED_KEYS);
 /** Image area cap shared by every resizable route (projection `max_output_pixels`). */
 export const MAX_OUTPUT_PIXELS = 16_000_000;
 /**
@@ -117,33 +127,57 @@ export function resolveOutputRoute(inputToken, outputFormat) {
     const cell = IMAGE_OUTPUT_ROUTES.format_change[outToken];
     if (cell === undefined)
         return undefined;
-    // Resize is INPUT-gated. Since v2.103.0 convert is the resize engine, so the
-    // projection lists width/height/fit on EVERY format_change cell — but an SVG
-    // INPUT cannot be raster-resized (the convert worker rejects it). So strip the
-    // cell's resize keys and re-add only those the INPUT's same_format cell honors:
-    // raster inputs carry them, svg does not. The transcoder options (output_format/
-    // quality/background) ride the cell directly.
-    const transcoderHonored = cell.honored.filter((k) => !RESIZE_KEY_SET.has(k));
+    // Resize + auto_orient are INPUT-gated (see {@link INPUT_GATED_KEYS}). Since
+    // v2.103.0 convert is the resize engine, so the projection lists width/height/
+    // fit AND auto_orient on EVERY format_change cell — but an SVG INPUT cannot be
+    // raster-resized or auto-oriented (the convert worker rejects it). So strip
+    // the cell's input-gated keys and re-add only those the INPUT's same_format
+    // cell honors: raster inputs carry them, svg does not. The transcoder options
+    // (output_format/quality/background/color_profile) ride the cell directly.
+    const transcoderHonored = cell.honored.filter((k) => !INPUT_GATED_KEY_SET.has(k));
     const inCell = IMAGE_OUTPUT_ROUTES.same_format[inputToken];
-    const resize = inCell ? RESIZE_KEYS.filter((k) => inCell.honored.includes(k)) : [];
+    const inputGated = inCell ? INPUT_GATED_KEYS.filter((k) => inCell.honored.includes(k)) : [];
     return {
         route: 'format_change',
         sourceOp: 'convert',
         outputFormatWire: outToken,
         inputToken,
-        honored: new Set([...transcoderHonored, ...resize]),
+        honored: new Set([...transcoderHonored, ...inputGated]),
         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
@@ -152,12 +186,180 @@ 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)
+    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
+ * `availability/availability.json` `operations.compress.mime_groups.<group>.
+ * options.<opt>.values`. Kept as a hand table (NOT a runtime read of the ~238KB
+ * availability sidecar) so the enum-membership gate stays browser-safe, exactly
+ * like {@link IMAGE_OUTPUT_ROUTES} — and, crucially, so the gate has NO
+ * dependency on a contracts version that carries the enum in a compact form (a
+ * generated-metadata `values` field would fail open on an older published
+ * `@giveitsmaller/contracts`). PINNED to `availability.json` by
+ * `output-route-conformance.test.ts`; a contract regen that adds/changes an
+ * enum member fails there. Mirrored by PHP `ImageOutputRoutes::COMPRESS_OPTION_VALUES`.
+ *
+ * `image_svg`/`image_avif` carry the NARROW `metadata: ['strip','all']` (no
+ * `keep`) — the reason a value gate that consulted only the generic `image`
+ * group (`['strip','keep','all']`) let `metadata: 'keep'` reach a server 422 on
+ * those bases (rtkzl9gr). `output_format` is listed for a faithful projection
+ * mirror but is never gated here (the Output lowering owns it positionally).
+ */
+export const COMPRESS_OPTION_VALUES = {
+    image: { color_profile: ['keep', 'srgb', 'strip'], fit: ['max', 'crop', 'scale'], metadata: ['strip', 'keep', 'all'], output_format: ['original', 'webp', 'auto', 'smallest'] },
+    image_jpeg: { chroma_subsampling: ['420', '422', '444'], color_profile: ['keep', 'srgb', 'strip'], encoding_mode: ['quality', 'target_size', 'auto_quality'], fit: ['max', 'crop', 'scale'], metadata: ['strip', 'keep', 'all'], output_format: ['original', 'webp', 'auto', 'smallest'], quality_preset: ['best', 'good', 'fair', 'low'] },
+    image_png: { color_profile: ['keep', 'srgb', 'strip'], fit: ['max', 'crop', 'scale'], metadata: ['strip', 'keep', 'all'], output_format: ['original', 'webp', 'auto', 'smallest'] },
+    image_avif: { color_profile: ['keep', 'srgb', 'strip'], encoding_mode: ['quality', 'target_size', 'auto_quality'], fit: ['max', 'crop', 'scale'], metadata: ['strip', 'all'], output_format: ['original', 'webp', 'auto', 'smallest'], quality_preset: ['best', 'good', 'fair', 'low'] },
+    image_svg: { metadata: ['strip', 'all'], output_format: ['original', 'webp', 'auto', 'smallest'] },
+    image_webp: { color_profile: ['keep', 'srgb', 'strip'], encoding_mode: ['quality', 'target_size', 'auto_quality'], fit: ['max', 'crop', 'scale'], metadata: ['strip', 'keep', 'all'], output_format: ['original', 'webp', 'auto', 'smallest'], quality_preset: ['best', 'good', 'fair', 'low'] },
+};
+/**
+ * The compress mime-group whose enum members are authoritative for an image
+ * token's SAME_FORMAT route — the exact `image_<token>` group when
+ * {@link COMPRESS_OPTION_VALUES} carries one, else the generic `image` group
+ * (gif/tiff).
+ *
+ * Deliberately DISTINCT from {@link compressGroupForToken} (which the planned
+ * gate uses). The planned gate routes webp/gif/svg/tiff through the generic
+ * `image` group, where cross-format `planned` markers live (e.g. `srgb`).
+ * Enum MEMBERSHIP is the opposite: it needs the format-specific enum, because
+ * `image_svg`'s `metadata` enum is the narrow `[strip, all]` while the generic
+ * group's is `[strip, keep, all]` — so only the specific group rejects
+ * `metadata: 'keep'` on SVG (and AVIF, which already maps specifically).
+ */
+function enumGroupForToken(token) {
+    const specific = `image_${token}`;
+    return COMPRESS_OPTION_VALUES[specific] !== undefined ? specific : 'image';
+}
+/**
+ * Whether a VALUE lies OUTSIDE the option's compress-route enum for the given
+ * input format — the pre-upload enum-membership gate (rtkzl9gr). Reads the hand
+ * {@link COMPRESS_OPTION_VALUES} table. Returns false when the option is not an
+ * enum on this group (no entry), so a non-enum option (e.g. integer `quality`)
+ * is never gated. Meaningful only on the same_format (compress) route, where
+ * the compress option enums definitionally apply. Membership is STRICT: a value
+ * whose type differs from the string enum members (e.g. numeric `420`) is
+ * treated as unknown rather than coerced to a match.
+ */
+export function isUnknownEnumValue(inputToken, optionKey, value) {
+    const members = COMPRESS_OPTION_VALUES[enumGroupForToken(inputToken)]?.[optionKey];
+    if (members === undefined)
         return false;
-    const entry = opt.per_value_availability[String(value)];
-    return entry?.availability === 'planned';
+    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. */