@fungi.computer/darkroom 0.0.1 → 0.2.0

package/README.md

@@ -156,9 +156,18 @@ Agar's public `pendingSchema`. `appMediaModelsOutcomeSchema` and
 closed admission codes, the Media attachment-budget refusal, the existing
 `agentAppMediaLibraryFailureSchema`, and `appMediaBrokerFailureSchema`. The
 latter preserves the broker projection: HTTP `code` becomes `error`, HTTP
-`error` becomes `message`, and `stage` and `retryable` stay unchanged. HTTP
-failures and transport envelopes are separate representations and do not decode
-as these outcomes.
+`error` becomes `message`, and `stage`, `retryable` and optional `provider`
+facts stay unchanged. HTTP failures and transport envelopes are separate
+representations and do not decode as these outcomes.
+
+Provider facts use Agar's canonical Media grammar: an allowlisted error category
+and bounded numeric code, or `result_download` and a native HTTP status. The
+durable owner retains those facts through interruption and replay, including
+safety refusals, without retaining the original error message or cause in the
+failure record. A terminal provider failure never redispatches the paid attempt.
+The fresh pre-release schema replaces the safety-only refusal table; old preview
+stores require an explicit host reset, not an automatic migration or dual
+reader.
 
 See the [generated API](docs/api/README.md) for signatures and host ports. The
 Cloudflare entry needs the native Workers type declarations in a TypeScript

package/dist/app-media-contracts.d.ts

@@ -1,6 +1,6 @@
 import * as z from "zod";
 /** Bounded catalog decoded by the App media broker before host filtering. */
-export declare const mediaModelsSchema: z.ZodArray<z.ZodReadonly<z.ZodObject<{
+export declare const mediaModelsSchema: z.ZodLazy<z.ZodArray<z.ZodReadonly<z.ZodObject<{
     id: z.ZodString;
     label: z.ZodString;
     kind: z.ZodEnum<{
@@ -18,7 +18,7 @@ export declare const mediaModelsSchema: z.ZodArray<z.ZodReadonly<z.ZodObject<{
         readonly jpeg: "jpeg";
         readonly webp: "webp";
     }>>>;
-    input: z.ZodReadonly<z.ZodObject<{
+    input: z.ZodLazy<z.ZodReadonly<z.ZodObject<{
         transport: z.ZodEnum<{
             readonly json: "json";
             readonly multipart: "multipart";
@@ -39,9 +39,9 @@ export declare const mediaModelsSchema: z.ZodArray<z.ZodReadonly<z.ZodObject<{
         defaultSteps: z.ZodNullable<z.ZodNumber>;
         referenceField: z.ZodNullable<z.ZodString>;
         maxReferences: z.ZodNumber;
-    }, z.core.$strict>>;
+    }, z.core.$strict>>>;
     sizes: z.ZodNullable<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
-    video: z.ZodNullable<z.ZodReadonly<z.ZodObject<{
+    video: z.ZodNullable<z.ZodLazy<z.ZodReadonly<z.ZodObject<{
         minSeconds: z.ZodNumber;
         maxSeconds: z.ZodNumber;
         defaultSeconds: z.ZodNumber;
@@ -51,7 +51,7 @@ export declare const mediaModelsSchema: z.ZodArray<z.ZodReadonly<z.ZodObject<{
             readonly veo: "veo";
             readonly minimax: "minimax";
         }>;
-        formats: z.ZodReadonly<z.ZodArray<z.ZodReadonly<z.ZodObject<{
+        formats: z.ZodReadonly<z.ZodArray<z.ZodLazy<z.ZodReadonly<z.ZodObject<{
             resolution: z.ZodEnum<{
                 readonly p480: "480p";
                 readonly p720: "720p";
@@ -70,7 +70,7 @@ export declare const mediaModelsSchema: z.ZodArray<z.ZodReadonly<z.ZodObject<{
             }>;
             width: z.ZodNumber;
             height: z.ZodNumber;
-        }, z.core.$strict>>>>;
+        }, z.core.$strict>>>>>;
         defaultResolution: z.ZodEnum<{
             readonly p480: "480p";
             readonly p720: "720p";
@@ -113,8 +113,8 @@ export declare const mediaModelsSchema: z.ZodArray<z.ZodReadonly<z.ZodObject<{
             silentMilliunitsPerSecond: z.ZodNumber;
             audioMilliunitsPerSecond: z.ZodNumber;
         }, z.core.$strict>>>>;
-    }, z.core.$strict>>>;
-}, z.core.$strict>>>;
+    }, z.core.$strict>>>>;
+}, z.core.$strict>>>>;
 /** An absolute output path on the Computer admitted by the App host. */
 export declare const destinationSchema: z.ZodObject<{
     computerId: z.ZodString;
@@ -153,11 +153,11 @@ export declare const appMediaAdmissionErrorSchema: z.ZodObject<{
     }>;
 }, z.core.$strict>;
 /** Attachment budget refusal emitted by the Media reservation owner. */
-export declare const appMediaBudgetRefusalSchema: z.ZodObject<{
+export declare const appMediaBudgetRefusalSchema: z.ZodLazy<z.ZodObject<{
     error: z.ZodLiteral<"attachment_budget_exceeded">;
     kind: z.ZodLiteral<"media">;
     retryAfterMs: z.ZodNumber;
-}, z.core.$strict>;
+}, z.core.$strict>>;
 /** Existing Media admission refusals, without an admitted selector or callable. */
 export declare const appMediaAdmissionRefusalSchema: z.ZodUnion<readonly [z.ZodObject<{
     error: z.ZodEnum<{
@@ -170,11 +170,11 @@ export declare const appMediaAdmissionRefusalSchema: z.ZodUnion<readonly [z.ZodO
         /** Admission could not resolve the current resource. */
         readonly unavailable: "unavailable";
     }>;
-}, z.core.$strict>, z.ZodObject<{
+}, z.core.$strict>, z.ZodLazy<z.ZodObject<{
     error: z.ZodLiteral<"attachment_budget_exceeded">;
     kind: z.ZodLiteral<"media">;
     retryAfterMs: z.ZodNumber;
-}, z.core.$strict>]>;
+}, z.core.$strict>>]>;
 /** Admission errors plus invalid/oversized inputs emitted directly by the broker. */
 export declare const appMediaBrokerErrorSchema: z.ZodObject<{
     error: z.ZodEnum<{
@@ -193,10 +193,10 @@ export declare const appMediaBrokerErrorSchema: z.ZodObject<{
     }>;
 }, z.core.$strict>;
 /** Missing-library refusal decoded and returned by the App media broker. */
-export declare const agentAppMediaLibraryFailureSchema: z.ZodObject<{
+export declare const agentAppMediaLibraryFailureSchema: z.ZodLazy<z.ZodObject<{
     error: z.ZodLiteral<"library_unavailable">;
     message: z.ZodString;
-}, z.core.$strict>;
+}, z.core.$strict>>;
 /** Broker projection of an HTTP failure: code becomes error and error becomes message. */
 export declare const appMediaBrokerFailureSchema: z.ZodObject<{
     error: z.ZodEnum<{
@@ -221,6 +221,13 @@ export declare const appMediaBrokerFailureSchema: z.ZodObject<{
         readonly "destination-write": "destination-write";
     }>;
     retryable: z.ZodBoolean;
+    provider: z.ZodOptional<z.ZodPipe<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodTransform<Readonly<{
+        category: "InferenceUpstreamError" | "AiInternalError" | "TypeError" | "AbortError" | "TimeoutError" | "Error";
+        code: number | null;
+    }> | Readonly<{
+        category: "result_download";
+        status: number;
+    }>, unknown>>>;
 }, z.core.$strict>;
 /** Refusal payloads emitted by the App media broker, separate from transport errors. */
 export declare const appMediaRefusalSchema: z.ZodUnion<readonly [z.ZodObject<{
@@ -238,14 +245,14 @@ export declare const appMediaRefusalSchema: z.ZodUnion<readonly [z.ZodObject<{
         /** Admission could not resolve the current resource. */
         readonly unavailable: "unavailable";
     }>;
-}, z.core.$strict>, z.ZodObject<{
+}, z.core.$strict>, z.ZodLazy<z.ZodObject<{
     error: z.ZodLiteral<"attachment_budget_exceeded">;
     kind: z.ZodLiteral<"media">;
     retryAfterMs: z.ZodNumber;
-}, z.core.$strict>, z.ZodObject<{
+}, z.core.$strict>>, z.ZodLazy<z.ZodObject<{
     error: z.ZodLiteral<"library_unavailable">;
     message: z.ZodString;
-}, z.core.$strict>, z.ZodObject<{
+}, z.core.$strict>>, z.ZodObject<{
     error: z.ZodEnum<{
         readonly CAPABILITY_DENIED: "CAPABILITY_DENIED";
         readonly INSUFFICIENT_CREDIT: "INSUFFICIENT_CREDIT";
@@ -268,9 +275,16 @@ export declare const appMediaRefusalSchema: z.ZodUnion<readonly [z.ZodObject<{
         readonly "destination-write": "destination-write";
     }>;
     retryable: z.ZodBoolean;
+    provider: z.ZodOptional<z.ZodPipe<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodTransform<Readonly<{
+        category: "InferenceUpstreamError" | "AiInternalError" | "TypeError" | "AbortError" | "TimeoutError" | "Error";
+        code: number | null;
+    }> | Readonly<{
+        category: "result_download";
+        status: number;
+    }>, unknown>>>;
 }, z.core.$strict>]>;
 /** Model-list payload or an existing broker refusal. */
-export declare const appMediaModelsOutcomeSchema: z.ZodUnion<readonly [z.ZodArray<z.ZodReadonly<z.ZodObject<{
+export declare const appMediaModelsOutcomeSchema: z.ZodUnion<readonly [z.ZodLazy<z.ZodArray<z.ZodReadonly<z.ZodObject<{
     id: z.ZodString;
     label: z.ZodString;
     kind: z.ZodEnum<{
@@ -288,7 +302,7 @@ export declare const appMediaModelsOutcomeSchema: z.ZodUnion<readonly [z.ZodArra
         readonly jpeg: "jpeg";
         readonly webp: "webp";
     }>>>;
-    input: z.ZodReadonly<z.ZodObject<{
+    input: z.ZodLazy<z.ZodReadonly<z.ZodObject<{
         transport: z.ZodEnum<{
             readonly json: "json";
             readonly multipart: "multipart";
@@ -309,9 +323,9 @@ export declare const appMediaModelsOutcomeSchema: z.ZodUnion<readonly [z.ZodArra
         defaultSteps: z.ZodNullable<z.ZodNumber>;
         referenceField: z.ZodNullable<z.ZodString>;
         maxReferences: z.ZodNumber;
-    }, z.core.$strict>>;
+    }, z.core.$strict>>>;
     sizes: z.ZodNullable<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
-    video: z.ZodNullable<z.ZodReadonly<z.ZodObject<{
+    video: z.ZodNullable<z.ZodLazy<z.ZodReadonly<z.ZodObject<{
         minSeconds: z.ZodNumber;
         maxSeconds: z.ZodNumber;
         defaultSeconds: z.ZodNumber;
@@ -321,7 +335,7 @@ export declare const appMediaModelsOutcomeSchema: z.ZodUnion<readonly [z.ZodArra
             readonly veo: "veo";
             readonly minimax: "minimax";
         }>;
-        formats: z.ZodReadonly<z.ZodArray<z.ZodReadonly<z.ZodObject<{
+        formats: z.ZodReadonly<z.ZodArray<z.ZodLazy<z.ZodReadonly<z.ZodObject<{
             resolution: z.ZodEnum<{
                 readonly p480: "480p";
                 readonly p720: "720p";
@@ -340,7 +354,7 @@ export declare const appMediaModelsOutcomeSchema: z.ZodUnion<readonly [z.ZodArra
             }>;
             width: z.ZodNumber;
             height: z.ZodNumber;
-        }, z.core.$strict>>>>;
+        }, z.core.$strict>>>>>;
         defaultResolution: z.ZodEnum<{
             readonly p480: "480p";
             readonly p720: "720p";
@@ -383,8 +397,8 @@ export declare const appMediaModelsOutcomeSchema: z.ZodUnion<readonly [z.ZodArra
             silentMilliunitsPerSecond: z.ZodNumber;
             audioMilliunitsPerSecond: z.ZodNumber;
         }, z.core.$strict>>>>;
-    }, z.core.$strict>>>;
-}, z.core.$strict>>>, z.ZodUnion<readonly [z.ZodObject<{
+    }, z.core.$strict>>>>;
+}, z.core.$strict>>>>, z.ZodUnion<readonly [z.ZodObject<{
     error: z.ZodEnum<{
         /** The broker refused the input representation or selection. */
         readonly invalid: "invalid";
@@ -399,14 +413,14 @@ export declare const appMediaModelsOutcomeSchema: z.ZodUnion<readonly [z.ZodArra
         /** Admission could not resolve the current resource. */
         readonly unavailable: "unavailable";
     }>;
-}, z.core.$strict>, z.ZodObject<{
+}, z.core.$strict>, z.ZodLazy<z.ZodObject<{
     error: z.ZodLiteral<"attachment_budget_exceeded">;
     kind: z.ZodLiteral<"media">;
     retryAfterMs: z.ZodNumber;
-}, z.core.$strict>, z.ZodObject<{
+}, z.core.$strict>>, z.ZodLazy<z.ZodObject<{
     error: z.ZodLiteral<"library_unavailable">;
     message: z.ZodString;
-}, z.core.$strict>, z.ZodObject<{
+}, z.core.$strict>>, z.ZodObject<{
     error: z.ZodEnum<{
         readonly CAPABILITY_DENIED: "CAPABILITY_DENIED";
         readonly INSUFFICIENT_CREDIT: "INSUFFICIENT_CREDIT";
@@ -429,6 +443,13 @@ export declare const appMediaModelsOutcomeSchema: z.ZodUnion<readonly [z.ZodArra
         readonly "destination-write": "destination-write";
     }>;
     retryable: z.ZodBoolean;
+    provider: z.ZodOptional<z.ZodPipe<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodTransform<Readonly<{
+        category: "InferenceUpstreamError" | "AiInternalError" | "TypeError" | "AbortError" | "TimeoutError" | "Error";
+        code: number | null;
+    }> | Readonly<{
+        category: "result_download";
+        status: number;
+    }>, unknown>>>;
 }, z.core.$strict>]>]>;
 /** Completed generation, Agar polling result, or an existing broker refusal. */
 export declare const appMediaGenerationOutcomeSchema: z.ZodUnion<readonly [z.ZodObject<{
@@ -466,14 +487,14 @@ export declare const appMediaGenerationOutcomeSchema: z.ZodUnion<readonly [z.Zod
         /** Admission could not resolve the current resource. */
         readonly unavailable: "unavailable";
     }>;
-}, z.core.$strict>, z.ZodObject<{
+}, z.core.$strict>, z.ZodLazy<z.ZodObject<{
     error: z.ZodLiteral<"attachment_budget_exceeded">;
     kind: z.ZodLiteral<"media">;
     retryAfterMs: z.ZodNumber;
-}, z.core.$strict>, z.ZodObject<{
+}, z.core.$strict>>, z.ZodLazy<z.ZodObject<{
     error: z.ZodLiteral<"library_unavailable">;
     message: z.ZodString;
-}, z.core.$strict>, z.ZodObject<{
+}, z.core.$strict>>, z.ZodObject<{
     error: z.ZodEnum<{
         readonly CAPABILITY_DENIED: "CAPABILITY_DENIED";
         readonly INSUFFICIENT_CREDIT: "INSUFFICIENT_CREDIT";
@@ -496,4 +517,11 @@ export declare const appMediaGenerationOutcomeSchema: z.ZodUnion<readonly [z.Zod
         readonly "destination-write": "destination-write";
     }>;
     retryable: z.ZodBoolean;
+    provider: z.ZodOptional<z.ZodPipe<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodTransform<Readonly<{
+        category: "InferenceUpstreamError" | "AiInternalError" | "TypeError" | "AbortError" | "TimeoutError" | "Error";
+        code: number | null;
+    }> | Readonly<{
+        category: "result_download";
+        status: number;
+    }>, unknown>>>;
 }, z.core.$strict>]>]>;

package/dist/app-media-contracts.js

@@ -4,9 +4,7 @@ import { mediaResultSchema } from "./media-operation-contract.js";
 import { pendingSchema } from "@fungi.computer/agar/backend-definition";
 import { mediaFailureSchema } from "./browser-failure.js";
 /** Bounded catalog decoded by the App media broker before host filtering. */
-export const mediaModelsSchema = z
-    .array(mediaModelSchema)
-    .max(listMediaModels().length);
+export const mediaModelsSchema = z.lazy(() => z.array(mediaModelSchema).max(listMediaModels().length));
 /** An absolute output path on the Computer admitted by the App host. */
 export const destinationSchema = z.strictObject({
     /** Computer admitted by the host. */
@@ -36,14 +34,14 @@ export const appMediaAdmissionErrorSchema = z.strictObject({
     }),
 });
 /** Attachment budget refusal emitted by the Media reservation owner. */
-export const appMediaBudgetRefusalSchema = z.strictObject({
+export const appMediaBudgetRefusalSchema = z.lazy(() => z.strictObject({
     /** The attachment's operation budget refused this request. */
     error: z.literal("attachment_budget_exceeded"),
     /** Media reservations use the Media budget, not exec or write. */
     kind: z.literal("media"),
     /** Delay emitted by the reservation owner. */
     retryAfterMs: z.number(),
-});
+}));
 /** Existing Media admission refusals, without an admitted selector or callable. */
 export const appMediaAdmissionRefusalSchema = z.union([
     appMediaAdmissionErrorSchema,
@@ -61,12 +59,12 @@ export const appMediaBrokerErrorSchema = appMediaAdmissionErrorSchema.extend({
     }),
 });
 /** Missing-library refusal decoded and returned by the App media broker. */
-export const agentAppMediaLibraryFailureSchema = z.strictObject({
+export const agentAppMediaLibraryFailureSchema = z.lazy(() => z.strictObject({
     /** The calling Installation's library is unavailable. */
     error: z.literal("library_unavailable"),
     /** Existing library-owner presentation copy. */
     message: z.string().max(4096),
-});
+}));
 /** Broker projection of an HTTP failure: code becomes error and error becomes message. */
 export const appMediaBrokerFailureSchema = z.strictObject({
     /** Original typed HTTP failure code. */
@@ -77,6 +75,8 @@ export const appMediaBrokerFailureSchema = z.strictObject({
     stage: mediaFailureSchema.shape.stage,
     /** Original retry truth. */
     retryable: mediaFailureSchema.shape.retryable,
+    /** Original bounded provider facts, when available. */
+    provider: mediaFailureSchema.shape.provider,
 });
 /** Refusal payloads emitted by the App media broker, separate from transport errors. */
 export const appMediaRefusalSchema = z.union([

package/dist/browser-failure.d.ts

@@ -33,6 +33,13 @@ export declare const mediaFailureSchema: z.ZodObject<{
         readonly SAFETY_FILTER_REFUSED: "SAFETY_FILTER_REFUSED";
     }>;
     retryable: z.ZodBoolean;
+    provider: z.ZodOptional<z.ZodPipe<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodTransform<Readonly<{
+        category: "InferenceUpstreamError" | "AiInternalError" | "TypeError" | "AbortError" | "TimeoutError" | "Error";
+        code: number | null;
+    }> | Readonly<{
+        category: "result_download";
+        status: number;
+    }>, unknown>>>;
 }, z.core.$strict>;
 /** Sanitized Media failure carried from the authenticated host to Agar. */
 export type MediaFailure = z.output<typeof mediaFailureSchema>;

package/dist/browser-failure.js

@@ -2,6 +2,7 @@ import * as z from "zod";
 import { mediaFailureStageSchema } from "./execution-error.js";
 import { Option, Schema } from "effect";
 import { reportCatchFailure } from "./failure.js";
+import { mediaProviderDiagnosticWireSchema } from "@fungi.computer/agar/errors";
 /** Sanitized HTTP refusal emitted by a Media host and decoded at the browser boundary. */
 export const mediaFailureSchema = z.strictObject({
     /** Host-supplied presentation copy. */
@@ -23,6 +24,8 @@ export const mediaFailureSchema = z.strictObject({
     }),
     /** Whether repeating this exact attempt may recover. */
     retryable: z.boolean(),
+    /** Allowlisted provider facts only; the original cause never crosses HTTP. */
+    provider: mediaProviderDiagnosticWireSchema.optional(),
 });
 const decodeJson = Schema.decodeUnknownOption(Schema.fromJsonString(Schema.Json));
 function parseMediaFailureJson(json) {

package/dist/cloudflare/provider.js

@@ -2,6 +2,7 @@ import { z } from "zod";
 import * as Redacted from "effect/Redacted";
 import { buildProviderInput, getMediaModel, estimateImageMilliunits, normalizeMediaProviderOutput, mediaProviderWireSchema, } from "../index.js";
 import { MediaExecutionError, MediaSafetyFilterRefusal, } from "../execution-error.js";
+import { decodeMediaProviderErrorCategory, } from "@fungi.computer/agar/errors";
 import { estimateGatewayMilliunits, gatewayInput, isGatewayModel, } from "../gateway-models.js";
 import { GATEWAY_VIDEO_MAX_BYTES, gatewayOutputSchema, isMp4, } from "../gateway-wire.js";
 import { videoProviderAdapters } from "../video-providers/index.js";
@@ -25,31 +26,21 @@ export function estimate(settings, references) {
 }
 // Workers AI prefixes upstream error messages with its numeric internal code.
 // Parse only that bounded identifier; the remaining message is never logged.
-const providerFailureCode = z
+const providerFailureCode = z.lazy(() => z
     .string()
     .regex(/^\d{4,5}: /u)
     .transform((message) => Number(message.split(":", 1)[0]))
     .nullable()
-    .catch(null);
-const providerFailureCategory = z
-    .enum([
-    "InferenceUpstreamError",
-    "AiInternalError",
-    "TypeError",
-    "AbortError",
-    "TimeoutError",
-    "Error",
-])
-    .catch("Error");
+    .catch(null));
 // Recognize the refusal, not the generic Workers AI error number or prompt text.
-const safetyFilterMessage = z.union([
+const safetyFilterMessage = z.lazy(() => z.union([
     z
         .string()
         .regex(/(?:^|:\s)(?:AiError:\s)?Input prompt contains NSFW content\b/iu),
     // Veo's documented input-policy refusal; keep its details private as well.
     // https://docs.cloud.google.com/vertex-ai/generative-ai/docs/video/responsible-ai-and-usage-guidelines
     z.string().regex(/\bit might violate our policies\b/iu),
-]);
+]));
 /** Encode multipart once with the platform's boundary, as required by AI.run. */
 function workersAiInput(payload) {
     if (payload.transport === "json")
@@ -64,17 +55,21 @@ function workersAiInput(payload) {
 }
 /** Retain the original provider failure alongside its bounded code and category. */
 function providerFailure(model, cause) {
+    const provider = {
+        category: decodeMediaProviderErrorCategory(cause instanceof Error ? cause.name : undefined),
+        code: providerFailureCode.parse(cause instanceof Error ? cause.message : undefined),
+    };
     // Workers correlates this structured event with the request trace. Never log
     // the provider message/body: either can contain customer prompt content.
     console.error("Media provider request failed", {
         model,
-        providerCode: providerFailureCode.parse(cause instanceof Error ? cause.message : undefined),
-        category: providerFailureCategory.parse(cause instanceof Error ? cause.name : undefined),
+        providerCode: provider.code,
+        category: provider.category,
     }, Redacted.make(cause));
     return cause instanceof Error &&
         safetyFilterMessage.safeParse(cause.message).success
-        ? new MediaSafetyFilterRefusal({ cause })
-        : new MediaExecutionError("provider", { cause });
+        ? new MediaSafetyFilterRefusal({ cause, provider })
+        : new MediaExecutionError("provider", { cause, provider });
 }
 /** Run a gateway model and fetch its result URL within the byte bound. */
 async function generateThroughGateway(ai, settings, references, signal, options, fetchResult, outputFormat) {
@@ -95,7 +90,9 @@ async function generateThroughGateway(ai, settings, references, signal, options,
             const url = videoProviderAdapters[model.video.provider].decodeResultUrl(providerValue);
             const response = await fetchResult(url, { signal: signal ?? null });
             if (!response.ok)
-                throw new Error("gateway video result unavailable");
+                throw new MediaExecutionError("normalization", {
+                    provider: { category: "result_download", status: response.status },
+                });
             const bytes = await readResponseBytes(response, GATEWAY_VIDEO_MAX_BYTES);
             if (!isMp4(bytes))
                 throw new Error("gateway video is not an MP4");
@@ -107,6 +104,8 @@ async function generateThroughGateway(ai, settings, references, signal, options,
         }), { fetchUrl: (url) => fetchResult(url, { signal: signal ?? null }) });
     }
     catch (cause) {
+        if (cause instanceof MediaExecutionError)
+            throw cause;
         throw new MediaExecutionError("normalization", { cause });
     }
 }

package/dist/cloudflare/reference-images.js

@@ -2,11 +2,11 @@ import { z } from "zod";
 import { MAX_REFERENCE_BYTES, MAX_REFERENCE_DIMENSION, MediaSettingsError, viewDimensionSchema, } from "../index.js";
 /** The retained `read_image` encoding: JPEG at quality 80. */
 const VIEW_JPEG_QUALITY = 80;
-const metadata = z.object({
+const metadata = z.lazy(() => z.object({
     format: z.enum(["image/png", "image/jpeg", "image/gif", "image/webp"]),
     width: z.number().int().positive(),
     height: z.number().int().positive(),
-});
+}));
 const formats = {
     "image/png": "png",
     "image/jpeg": "jpeg",

package/dist/cost-estimate.js

@@ -4,7 +4,7 @@ import * as z from "zod";
 const TILE = 512;
 const MAX_DIMENSION = 4_096;
 const MAX_REFERENCES = 4;
-const imageParamsSchema = z
+const imageParamsSchema = z.lazy(() => z
     .object({
     width: z.number().int().min(1).max(MAX_DIMENSION),
     height: z.number().int().min(1).max(MAX_DIMENSION),
@@ -19,7 +19,7 @@ const imageParamsSchema = z
         .max(MAX_REFERENCES)
         .optional(),
 })
-    .strict();
+    .strict());
 const invalid = (message) => {
     throw new MediaSettingsError(`image cost parameters are invalid: ${message}`);
 };

package/dist/execution-error.d.ts

@@ -1,4 +1,5 @@
 import * as z from "zod";
+import { type MediaProviderDiagnostic } from "@fungi.computer/agar/errors";
 /** Public diagnostic labels only; never provider messages or request data. */
 export declare const mediaFailureStageSchema: z.ZodEnum<{
     /** Host admission before operation creation. */
@@ -26,17 +27,24 @@ export declare const mediaFailureStageSchema: z.ZodEnum<{
 }>;
 /** Execution stage at which a generation failed. */
 export type MediaFailureStage = Exclude<z.output<typeof mediaFailureStageSchema>, "admission" | "settings">;
+/** Private cause plus an independently decoded, safe provider diagnostic. */
+export type MediaExecutionErrorOptions = ErrorOptions & {
+    /** Safe provider facts, when the failure came from provider transport. */
+    readonly provider?: MediaProviderDiagnostic | undefined;
+};
 /** A bounded stage marker for failures that cross the Media HTTP boundary. */
 export declare class MediaExecutionError extends Error {
     /** Execution stage where the failure occurred. */
     readonly stage: MediaFailureStage;
+    /** Safe provider facts only; the original cause remains private. */
+    readonly provider: MediaProviderDiagnostic | undefined;
     constructor(
     /** Execution stage where the failure occurred. */
-    stage: MediaFailureStage, options?: ErrorOptions);
+    stage: MediaFailureStage, options?: MediaExecutionErrorOptions);
 }
 /** A provider safety filter refused generation; no output was delivered. */
 export declare class MediaSafetyFilterRefusal extends MediaExecutionError {
-    constructor(options?: ErrorOptions);
+    constructor(options?: MediaExecutionErrorOptions);
 }
 /** Why the host's billing owner refused to admit a new generation. */
 export type MediaBillingRefusalCode = "insufficient_credits" | "daily_limit_reached" | "denied";

package/dist/execution-error.js

@@ -1,4 +1,5 @@
 import * as z from "zod";
+import { decodeMediaProviderDiagnostic, } from "@fungi.computer/agar/errors";
 /** Public diagnostic labels only; never provider messages or request data. */
 export const mediaFailureStageSchema = z.enum({
     /** Host admission before operation creation. */
@@ -27,12 +28,18 @@ export const mediaFailureStageSchema = z.enum({
 /** A bounded stage marker for failures that cross the Media HTTP boundary. */
 export class MediaExecutionError extends Error {
     stage;
+    /** Safe provider facts only; the original cause remains private. */
+    provider;
     constructor(
     /** Execution stage where the failure occurred. */
     stage, options) {
         super(`Media ${stage} failed`, options);
         this.stage = stage;
         this.name = "MediaExecutionError";
+        this.provider =
+            options?.provider === undefined
+                ? undefined
+                : decodeMediaProviderDiagnostic(options.provider);
     }
 }
 /** A provider safety filter refused generation; no output was delivered. */

package/dist/gateway-wire.d.ts

@@ -1,15 +1,15 @@
 import { z } from "zod";
 /** A result URL every gateway provider must return as plain HTTPS. */
-export declare const resultUrl: z.ZodURL;
+export declare const resultUrl: z.ZodLazy<z.ZodURL>;
 /** The Unified AI gateway's normalized answer: a completed state and one
  * result URL. Seedance and Veo answer this way; MiniMax does not. */
-export declare const gatewayOutputSchema: z.ZodObject<{
+export declare const gatewayOutputSchema: z.ZodLazy<z.ZodObject<{
     state: z.ZodOptional<z.ZodLiteral<"Completed">>;
     result: z.ZodObject<{
-        image: z.ZodOptional<z.ZodURL>;
-        video: z.ZodOptional<z.ZodURL>;
+        image: z.ZodOptional<z.ZodLazy<z.ZodURL>>;
+        video: z.ZodOptional<z.ZodLazy<z.ZodURL>>;
     }, z.core.$loose>;
-}, z.core.$loose>;
+}, z.core.$loose>>;
 /** Byte ceilings for fetched results; video stays within Worker memory. */
 export declare const GATEWAY_VIDEO_MAX_BYTES: number;
 /** An MP4 carries an `ftyp` box at byte 4. */

package/dist/gateway-wire.js

@@ -1,17 +1,17 @@
 import { z } from "zod";
 /** A result URL every gateway provider must return as plain HTTPS. */
-export const resultUrl = z
+export const resultUrl = z.lazy(() => z
     .url()
-    .refine((value) => value.startsWith("https://"), "result URLs must be HTTPS");
+    .refine((value) => value.startsWith("https://"), "result URLs must be HTTPS"));
 /** The Unified AI gateway's normalized answer: a completed state and one
  * result URL. Seedance and Veo answer this way; MiniMax does not. */
-export const gatewayOutputSchema = z.looseObject({
+export const gatewayOutputSchema = z.lazy(() => z.looseObject({
     state: z.literal("Completed").optional(),
     result: z.looseObject({
         image: resultUrl.optional(),
         video: resultUrl.optional(),
     }),
-});
+}));
 /** Byte ceilings for fetched results; video stays within Worker memory. */
 export const GATEWAY_VIDEO_MAX_BYTES = 64 * 1024 * 1024;
 /** An MP4 carries an `ftyp` box at byte 4. */