@fungi.computer/darkroom 0.0.1 → 0.2.0

package/dist/index.d.ts

@@ -73,7 +73,7 @@ export declare const MIN_VIEW_DIMENSION = 256;
 /** Maximum long-edge size accepted by an image viewer, in pixels. */
 export declare const MAX_VIEW_DIMENSION = 512;
 /** Decode a viewer long-edge size within the supported pixel bounds. */
-export declare const viewDimensionSchema: z.ZodNumber;
+export declare const viewDimensionSchema: z.ZodLazy<z.ZodNumber>;
 /**
  * Decode one image and re-encode it for a model to look at: scaled within
  * `maxDimension` on the long edge (bounded by {@link viewDimensionSchema}) as
@@ -174,18 +174,18 @@ export declare const validateMediaGenerationSelection: (raw: z.input<typeof medi
     }>[];
 }>;
 /** Path-only video reference; the host supplies authority and reads its bytes. */
-export declare const mediaVideoReferenceSchema: z.ZodObject<{
+export declare const mediaVideoReferenceSchema: z.ZodLazy<z.ZodObject<{
     path: z.ZodString;
     role: z.ZodEnum<{
         readonly first: "first-frame";
         readonly last: "last-frame";
         readonly reference: "reference";
     }>;
-}, z.core.$strict>;
+}, z.core.$strict>>;
 /** One path-only video reference. */
 export type MediaVideoReference = z.output<typeof mediaVideoReferenceSchema>;
 /** Neutral video selection; model-specific combinations are checked by validateMediaVideoSelection. */
-export declare const mediaVideoSelectionSchema: z.ZodObject<{
+export declare const mediaVideoSelectionSchema: z.ZodLazy<z.ZodObject<{
     model: z.ZodEnum<{
         readonly seedance: "bytedance/seedance-2.0";
         readonly seedanceFast: "bytedance/seedance-2.0-fast";
@@ -213,15 +213,15 @@ export declare const mediaVideoSelectionSchema: z.ZodObject<{
     }>>;
     durationSeconds: z.ZodOptional<z.ZodNumber>;
     generateAudio: z.ZodOptional<z.ZodBoolean>;
-    references: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    references: z.ZodOptional<z.ZodArray<z.ZodLazy<z.ZodObject<{
         path: z.ZodString;
         role: z.ZodEnum<{
             readonly first: "first-frame";
             readonly last: "last-frame";
             readonly reference: "reference";
         }>;
-    }, z.core.$strict>>>;
-}, z.core.$strict>;
+    }, z.core.$strict>>>>;
+}, z.core.$strict>>;
 /** Caller video selection before defaults and model-specific refinements. */
 export type MediaVideoSelectionInput = z.input<typeof mediaVideoSelectionSchema>;
 /** Normalized path-only video settings, ready for host-authorized reference hydration. */
@@ -313,21 +313,21 @@ export type MediaProviderOutput = Readonly<{
     entries: readonly MediaProviderImageEntry[];
 }>;
 /** Decode the Workers AI binding's raw output at the provider boundary. */
-export declare const mediaProviderWireSchema: z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodObject<{
+export declare const mediaProviderWireSchema: z.ZodLazy<z.ZodUnion<readonly [z.ZodLazy<z.ZodUnion<readonly [z.ZodObject<{
     image: z.ZodString;
 }, z.core.$strip>, z.ZodObject<{
-    image: z.ZodArray<z.ZodObject<{
+    image: z.ZodArray<z.ZodLazy<z.ZodObject<{
         base64: z.ZodOptional<z.ZodString>;
         data: z.ZodOptional<z.ZodString>;
         url: z.ZodOptional<z.ZodURL>;
-    }, z.core.$strict>>;
+    }, z.core.$strict>>>;
 }, z.core.$strip>, z.ZodObject<{
-    images: z.ZodArray<z.ZodObject<{
+    images: z.ZodArray<z.ZodLazy<z.ZodObject<{
         base64: z.ZodOptional<z.ZodString>;
         data: z.ZodOptional<z.ZodString>;
         url: z.ZodOptional<z.ZodURL>;
-    }, z.core.$strict>>;
-}, z.core.$strip>]>, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>, z.ZodCustom<Response, Response>, z.ZodCustom<ReadableStream<Uint8Array<ArrayBufferLike>>, ReadableStream<Uint8Array<ArrayBufferLike>>>]>;
+    }, z.core.$strict>>>;
+}, z.core.$strip>]>>, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>, z.ZodCustom<Response, Response>, z.ZodCustom<ReadableStream<Uint8Array<ArrayBufferLike>>, ReadableStream<Uint8Array<ArrayBufferLike>>>]>>;
 /** Supported raw provider representations, decoded by mediaProviderWireSchema. */
 export type MediaProviderWire = z.output<typeof mediaProviderWireSchema>;
 /** Native Workers AI output or an already decoded provider representation. */

package/dist/index.js

@@ -8,11 +8,7 @@ export const MIN_VIEW_DIMENSION = 256;
 /** Maximum long-edge size accepted by an image viewer, in pixels. */
 export const MAX_VIEW_DIMENSION = 512;
 /** Decode a viewer long-edge size within the supported pixel bounds. */
-export const viewDimensionSchema = z
-    .number()
-    .int()
-    .min(MIN_VIEW_DIMENSION)
-    .max(MAX_VIEW_DIMENSION);
+export const viewDimensionSchema = z.lazy(() => z.number().int().min(MIN_VIEW_DIMENSION).max(MAX_VIEW_DIMENSION));
 /** Maximum reference files in one generation request. */
 export const MAX_REFERENCE_COUNT = 4;
 /** Maximum reference width and height sent to inference, in pixels. */
@@ -219,14 +215,14 @@ function normalizeGenerationSettings(input, normalize) {
     return Object.freeze(normalized);
 }
 /** Path-only video reference; the host supplies authority and reads its bytes. */
-export const mediaVideoReferenceSchema = z.strictObject({
+export const mediaVideoReferenceSchema = z.lazy(() => z.strictObject({
     /** Selected image path, trimmed and nonblank after validation. */
     path: z.string().min(1).max(4_096),
     /** Explicit first frame, last frame, or reference-image role. */
     role: mediaVideoReferenceRoleSchema,
-});
+}));
 /** Neutral video selection; model-specific combinations are checked by validateMediaVideoSelection. */
-export const mediaVideoSelectionSchema = z.strictObject({
+export const mediaVideoSelectionSchema = z.lazy(() => z.strictObject({
     /** Verified catalog model identifier. */
     model: mediaVideoModelIdSchema,
     /** Trimmed prompt; Seedance allows 2,000 characters, Veo uses the retained host cap of 2,048. */
@@ -245,7 +241,7 @@ export const mediaVideoSelectionSchema = z.strictObject({
         .array(mediaVideoReferenceSchema)
         .max(MAX_REFERENCE_COUNT)
         .optional(),
-});
+}));
 /** Validate supported model/size/duration/reference combinations before authority or billing admission. */
 export function validateMediaVideoSelection(raw) {
     const parsed = mediaVideoSelectionSchema.safeParse(raw);
@@ -352,7 +348,7 @@ export const buildProviderInput = (settings, references = []) => {
         body,
     });
 };
-const providerEntrySchema = z
+const providerEntrySchema = z.lazy(() => z
     .object({
     /** Base64-encoded image data. */
     base64: z.string().optional(),
@@ -364,8 +360,8 @@ const providerEntrySchema = z
         .refine((value) => /^https?:\/\//iu.test(value), "provider image URLs must use HTTP(S)")
         .optional(),
 })
-    .strict();
-const providerEnvelopeSchema = z.union([
+    .strict());
+const providerEnvelopeSchema = z.lazy(() => z.union([
     z.object({
         /** Encoded provider image. */
         image: z.string().min(1),
@@ -378,14 +374,14 @@ const providerEnvelopeSchema = z.union([
         /** Provider output image entries. */
         images: z.array(providerEntrySchema),
     }),
-]);
+]));
 /** Decode the Workers AI binding's raw output at the provider boundary. */
-export const mediaProviderWireSchema = z.union([
+export const mediaProviderWireSchema = z.lazy(() => z.union([
     providerEnvelopeSchema,
     z.instanceof(Uint8Array),
     z.instanceof(Response),
     z.custom((value) => value instanceof ReadableStream),
-]);
+]));
 /** Parse the provider wire envelope before normalization. */
 export const parseMediaProviderOutput = (value) => {
     if (value instanceof Uint8Array)

package/dist/media-binding.d.ts

@@ -1,11 +1,10 @@
 import * as z from "zod";
-import * as Schema from "effect/Schema";
 import { mediaRequestedImageFormatSchema, type MediaGenerationSettings } from "./index.js";
 export { mediaResultSchema } from "./media-operation-contract.js";
 /** Image settings and path references crossing a scoped MEDIA binding. */
 export declare const mediaImageBindingInputSchema: z.ZodObject<{
     kind: z.ZodLiteral<"image">;
-    requestId: z.ZodString;
+    requestId: z.ZodLazy<z.ZodString>;
     libraryPath: z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>;
     settings: z.ZodObject<{
         resolution: z.ZodOptional<z.ZodEnum<{
@@ -48,9 +47,9 @@ export declare const mediaImageBindingInputSchema: z.ZodObject<{
 /** Video settings and path references crossing the same scoped binding. */
 export declare const mediaVideoBindingInputSchema: z.ZodObject<{
     kind: z.ZodLiteral<"video">;
-    requestId: z.ZodString;
+    requestId: z.ZodLazy<z.ZodString>;
     libraryPath: z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>;
-    settings: z.ZodObject<{
+    settings: z.ZodLazy<z.ZodObject<{
         model: z.ZodEnum<{
             readonly seedance: "bytedance/seedance-2.0";
             readonly seedanceFast: "bytedance/seedance-2.0-fast";
@@ -78,20 +77,20 @@ export declare const mediaVideoBindingInputSchema: z.ZodObject<{
         }>>;
         durationSeconds: z.ZodOptional<z.ZodNumber>;
         generateAudio: z.ZodOptional<z.ZodBoolean>;
-        references: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        references: z.ZodOptional<z.ZodArray<z.ZodLazy<z.ZodObject<{
             path: z.ZodString;
             role: z.ZodEnum<{
                 readonly first: "first-frame";
                 readonly last: "last-frame";
                 readonly reference: "reference";
             }>;
-        }, z.core.$strict>>>;
-    }, z.core.$strict>;
+        }, z.core.$strict>>>>;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 /** One generation identity, including the App-owned folder captured for replay. */
 export declare const mediaBindingGenerationSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     kind: z.ZodLiteral<"image">;
-    requestId: z.ZodString;
+    requestId: z.ZodLazy<z.ZodString>;
     libraryPath: z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>;
     settings: z.ZodObject<{
         resolution: z.ZodOptional<z.ZodEnum<{
@@ -132,9 +131,9 @@ export declare const mediaBindingGenerationSchema: z.ZodDiscriminatedUnion<[z.Zo
     }>>;
 }, z.core.$strict>, z.ZodObject<{
     kind: z.ZodLiteral<"video">;
-    requestId: z.ZodString;
+    requestId: z.ZodLazy<z.ZodString>;
     libraryPath: z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>;
-    settings: z.ZodObject<{
+    settings: z.ZodLazy<z.ZodObject<{
         model: z.ZodEnum<{
             readonly seedance: "bytedance/seedance-2.0";
             readonly seedanceFast: "bytedance/seedance-2.0-fast";
@@ -162,15 +161,15 @@ export declare const mediaBindingGenerationSchema: z.ZodDiscriminatedUnion<[z.Zo
         }>>;
         durationSeconds: z.ZodOptional<z.ZodNumber>;
         generateAudio: z.ZodOptional<z.ZodBoolean>;
-        references: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        references: z.ZodOptional<z.ZodArray<z.ZodLazy<z.ZodObject<{
             path: z.ZodString;
             role: z.ZodEnum<{
                 readonly first: "first-frame";
                 readonly last: "last-frame";
                 readonly reference: "reference";
             }>;
-        }, z.core.$strict>>>;
-    }, z.core.$strict>;
+        }, z.core.$strict>>>>;
+    }, z.core.$strict>>;
 }, z.core.$strict>], "kind">;
 /** Parsed generation command consumed by either host. */
 export type MediaBindingGeneration = z.output<typeof mediaBindingGenerationSchema>;
@@ -182,7 +181,7 @@ export declare const mediaBindingCallSchema: z.ZodDiscriminatedUnion<[z.ZodObjec
     operation: z.ZodLiteral<"generate">;
     input: z.ZodDiscriminatedUnion<[z.ZodObject<{
         kind: z.ZodLiteral<"image">;
-        requestId: z.ZodString;
+        requestId: z.ZodLazy<z.ZodString>;
         libraryPath: z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>;
         settings: z.ZodObject<{
             resolution: z.ZodOptional<z.ZodEnum<{
@@ -223,9 +222,9 @@ export declare const mediaBindingCallSchema: z.ZodDiscriminatedUnion<[z.ZodObjec
         }>>;
     }, z.core.$strict>, z.ZodObject<{
         kind: z.ZodLiteral<"video">;
-        requestId: z.ZodString;
+        requestId: z.ZodLazy<z.ZodString>;
         libraryPath: z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>;
-        settings: z.ZodObject<{
+        settings: z.ZodLazy<z.ZodObject<{
             model: z.ZodEnum<{
                 readonly seedance: "bytedance/seedance-2.0";
                 readonly seedanceFast: "bytedance/seedance-2.0-fast";
@@ -253,36 +252,43 @@ export declare const mediaBindingCallSchema: z.ZodDiscriminatedUnion<[z.ZodObjec
             }>>;
             durationSeconds: z.ZodOptional<z.ZodNumber>;
             generateAudio: z.ZodOptional<z.ZodBoolean>;
-            references: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            references: z.ZodOptional<z.ZodArray<z.ZodLazy<z.ZodObject<{
                 path: z.ZodString;
                 role: z.ZodEnum<{
                     readonly first: "first-frame";
                     readonly last: "last-frame";
                     readonly reference: "reference";
                 }>;
-            }, z.core.$strict>>>;
-        }, z.core.$strict>;
+            }, z.core.$strict>>>>;
+        }, z.core.$strict>>;
     }, z.core.$strict>], "kind">;
 }, z.core.$strict>], "operation">;
 /** Parsed call consumed by host admission and transport. */
 export type MediaBindingCall = z.output<typeof mediaBindingCallSchema>;
 /** Background-generation reply emitted by the durable service. */
-export declare const mediaPendingSchema: z.ZodObject<{
+export declare const mediaPendingSchema: z.ZodLazy<z.ZodObject<{
     status: z.ZodLiteral<"pending">;
     retryAfterSeconds: z.ZodNumber;
-}, z.core.$strict>;
+}, z.core.$strict>>;
 /** Parsing and model refusal stay shared; authorization remains host-owned. */
-export declare function parseMediaBindingCall(raw: Schema.Json): Readonly<{
+export declare function parseMediaBindingCall(raw: z.core.util.JSONType): Readonly<{
+    /** The binding input passed its shared grammar. */
     kind: "parsed";
+    /** Validated command for host admission. */
     call: MediaBindingCall;
 }> | Readonly<{
+    /** Input size, grammar or model selection was refused. */
     kind: "refused";
+    /** Safe refusal returned without provider dispatch. */
     result: z.core.util.JSONType;
 }>;
 /** Relative service input after the host attaches its trusted Computer to references. */
 export type MediaBindingRequest = Readonly<{
+    /** Host-selected output filename within the App's library folder. */
     path: string;
+    /** Validated selection with the host's Computer attached to references. */
     settings: MediaGenerationSettings;
+    /** Optional image encoding; video output remains MP4. */
     outputFormat?: z.output<typeof mediaRequestedImageFormatSchema>;
 }>;
 /** Choose the same fixed filename on both hosts without a recursive App lookup. */

package/dist/media-binding.js

@@ -13,12 +13,17 @@ const mediaBindingLibraryPathSchema = z
     .refine(Schema.is(mediaLibraryPathSchema), "Select an absolute library folder");
 /** Image settings and path references crossing a scoped MEDIA binding. */
 export const mediaImageBindingInputSchema = z.strictObject({
+    /** Select image generation rather than video. */
     kind: z.literal("image"),
+    /** Attempt identity retained through polling and replay. */
     requestId: mediaRequestIdSchema,
+    /** App-owned absolute folder; the host supplies Computer authority. */
     libraryPath: mediaBindingLibraryPathSchema,
+    /** Image model selection, references and inference settings. */
     settings: mediaGenerationSelectionSchema
         .omit({ durationSeconds: true })
         .extend({
+        /** Optional inference-step count for models that support it. */
         steps: z
             .number()
             .int()
@@ -27,13 +32,18 @@ export const mediaImageBindingInputSchema = z.strictObject({
             .optional(),
     })
         .refine((settings) => getMediaModel(settings.model)?.kind === "image", "Select an image model from listModels"),
+    /** Requested image encoding, validated against the selected model. */
     outputFormat: mediaRequestedImageFormatSchema.optional(),
 });
 /** Video settings and path references crossing the same scoped binding. */
 export const mediaVideoBindingInputSchema = z.strictObject({
+    /** Select video generation rather than an image. */
     kind: z.literal("video"),
+    /** Attempt identity retained through polling and replay. */
     requestId: mediaRequestIdSchema,
+    /** App-owned absolute folder; the host supplies Computer authority. */
     libraryPath: mediaBindingLibraryPathSchema,
+    /** Catalog-backed video model, size, duration and references. */
     settings: mediaVideoSelectionSchema,
 });
 /** One generation identity, including the App-owned folder captured for replay. */
@@ -43,17 +53,26 @@ export const mediaBindingGenerationSchema = z.discriminatedUnion("kind", [
 ]);
 /** Maintained MEDIA method grammar; guest input carries no principal or Computer. */
 export const mediaBindingCallSchema = z.discriminatedUnion("operation", [
-    z.strictObject({ operation: z.literal("models"), input: z.strictObject({}) }),
     z.strictObject({
+        /** Read the model catalog without dispatching generation. */
+        operation: z.literal("models"),
+        /** Catalog reads carry no guest authority or generation settings. */
+        input: z.strictObject({}),
+    }),
+    z.strictObject({
+        /** Execute or poll one admitted generation identity. */
         operation: z.literal("generate"),
+        /** The App's captured generation selection and library folder. */
         input: mediaBindingGenerationSchema,
     }),
 ]);
 /** Background-generation reply emitted by the durable service. */
-export const mediaPendingSchema = z.strictObject({
+export const mediaPendingSchema = z.lazy(() => z.strictObject({
+    /** Background work has been accepted but is not yet delivered. */
     status: z.literal("pending"),
+    /** Host-supplied delay before polling the same attempt again. */
     retryAfterSeconds: z.number().int().positive(),
-});
+}));
 /** Parsing and model refusal stay shared; authorization remains host-owned. */
 export function parseMediaBindingCall(raw) {
     if (new TextEncoder().encode(JSON.stringify(raw)).byteLength > 64 * 1024)
@@ -119,12 +138,15 @@ export async function readMediaBindingReply(input, computerId, response) {
         const failure = mediaFailureSchema.safeParse(value);
         if (!failure.success)
             return { error: "unavailable" };
-        return z.json().parse(appMediaBrokerFailureSchema.parse({
+        const projected = {
             error: failure.data.code,
             message: failure.data.error,
             stage: failure.data.stage,
             retryable: failure.data.retryable,
-        }));
+        };
+        if (failure.data.provider !== undefined)
+            projected.provider = failure.data.provider;
+        return z.json().parse(appMediaBrokerFailureSchema.parse(projected));
     }
     if (input.operation === "models")
         return z.json().parse(mediaModelsSchema.parse(value));

package/dist/media-operation-owner.d.ts

@@ -2,8 +2,10 @@ import { type MediaGenerationSettings } from "./index.js";
 import { z } from "zod";
 import type { MediaOperationContext, MediaOperationBucket } from "./media-operation-storage.js";
 import type { MediaProvider, MediaReferenceBytes } from "./index.js";
+import { type MediaFailureStage } from "./execution-error.js";
+import { type MediaProviderDiagnostic } from "@fungi.computer/agar/errors";
 /** Fixed generation destination captured before provider dispatch. */
-export declare const mediaOperationDestinationSchema: z.ZodObject<{
+export declare const mediaOperationDestinationSchema: z.ZodLazy<z.ZodObject<{
     computerId: z.ZodString;
     path: z.ZodString;
     outputFormat: z.ZodOptional<z.ZodEnum<{
@@ -11,7 +13,7 @@ export declare const mediaOperationDestinationSchema: z.ZodObject<{
         readonly jpeg: "jpeg";
         readonly webp: "webp";
     }>>;
-}, z.core.$strict>;
+}, z.core.$strict>>;
 /** Normalized generation and its fixed destination, captured for exact replay. */
 export type MediaOperationRequest = MediaGenerationSettings & z.output<typeof mediaOperationDestinationSchema>;
 /** Decode host namespace and owner identity. */
@@ -43,19 +45,19 @@ export declare const mediaOperationStateSchema: z.ZodEnum<{
 /** Durable generation, save and settlement states. */
 export type MediaOperationState = z.output<typeof mediaOperationStateSchema>;
 /** Decode retained or saved output size and encoding. */
-export declare const mediaImageSchema: z.ZodObject<{
+export declare const mediaImageSchema: z.ZodLazy<z.ZodObject<{
     bytes: z.ZodNumber;
     format: z.ZodString;
-}, z.core.$strict>;
+}, z.core.$strict>>;
 /** Byte length and encoding of generated or saved output. */
 export type MediaImage = z.output<typeof mediaImageSchema>;
 /** Decode the settled receipt, including the host-admitted customer price. */
-export declare const mediaOperationResultSchema: z.ZodObject<{
+export declare const mediaOperationResultSchema: z.ZodLazy<z.ZodObject<{
     generationId: z.ZodString;
     bytes: z.ZodNumber;
     format: z.ZodString;
     costMilliunits: z.ZodNumber;
-}, z.core.$strict>;
+}, z.core.$strict>>;
 /** Settled generation receipt with the host-admitted customer price. */
 export type MediaOperationResult = z.output<typeof mediaOperationResultSchema>;
 /** The only operation shape safe to return outside the owner. */
@@ -72,8 +74,15 @@ export type MediaOperationProjection = Readonly<{
     state: MediaOperationState;
     /** Terminal format mismatch after provider execution. */
     spentFailure: "output_format_mismatch" | null;
-    /** Definitive provider refusal with no delivered or billable output. */
-    providerRefusal: "safety_filter_refused" | null;
+    /** Safe terminal provider failure; no original cause or provider message. */
+    providerFailure: Readonly<{
+        /** Provider dispatch or output normalization, not a save failure. */
+        stage: Extract<MediaFailureStage, "provider" | "normalization">;
+        /** Preserve the model's safety refusal classification on replay. */
+        safetyRefused: boolean;
+        /** Allowlisted facts only; never the original error message or cause. */
+        provider?: MediaProviderDiagnostic | undefined;
+    }> | null;
     /** Pinned host price or unmetered quote. */
     estimatedCostMilliunits: number | null;
     /** Retained or saved image metadata. */
@@ -182,8 +191,15 @@ export declare class MediaOperationOwner {
         state: MediaOperationState;
         /** Terminal format mismatch after provider execution. */
         spentFailure: "output_format_mismatch" | null;
-        /** Definitive provider refusal with no delivered or billable output. */
-        providerRefusal: "safety_filter_refused" | null;
+        /** Safe terminal provider failure; no original cause or provider message. */
+        providerFailure: Readonly<{
+            /** Provider dispatch or output normalization, not a save failure. */
+            stage: Extract<MediaFailureStage, "provider" | "normalization">;
+            /** Preserve the model's safety refusal classification on replay. */
+            safetyRefused: boolean;
+            /** Allowlisted facts only; never the original error message or cause. */
+            provider?: MediaProviderDiagnostic | undefined;
+        }> | null;
         /** Pinned host price or unmetered quote. */
         estimatedCostMilliunits: number | null;
         /** Retained or saved image metadata. */
@@ -204,7 +220,7 @@ export declare class MediaOperationOwner {
     /** Run a background generation once; a retried alarm never redispatches. */
     alarm(): Promise<void>;
     /** An aborted in-flight provider call is terminal for this request ID. */
-    interruptGeneration(leaseId: string, refusalInput?: NonNullable<MediaOperationProjection["providerRefusal"]>): MediaOperationProjection;
+    interruptGeneration(leaseId: string, failureInput?: NonNullable<MediaOperationProjection["providerFailure"]>): MediaOperationProjection;
     /** Retain immutable provider output before making the save state visible. */
     recordGenerated(leaseId: string, bytes: Uint8Array, formatInput: string): Promise<MediaRetentionResult>;
     /** Read exact retained bytes under the current save lease. */
@@ -225,8 +241,15 @@ export declare class MediaOperationOwner {
         state: MediaOperationState;
         /** Terminal format mismatch after provider execution. */
         spentFailure: "output_format_mismatch" | null;
-        /** Definitive provider refusal with no delivered or billable output. */
-        providerRefusal: "safety_filter_refused" | null;
+        /** Safe terminal provider failure; no original cause or provider message. */
+        providerFailure: Readonly<{
+            /** Provider dispatch or output normalization, not a save failure. */
+            stage: Extract<MediaFailureStage, "provider" | "normalization">;
+            /** Preserve the model's safety refusal classification on replay. */
+            safetyRefused: boolean;
+            /** Allowlisted facts only; never the original error message or cause. */
+            provider?: MediaProviderDiagnostic | undefined;
+        }> | null;
         /** Pinned host price or unmetered quote. */
         estimatedCostMilliunits: number | null;
         /** Retained or saved image metadata. */
@@ -256,8 +279,15 @@ export declare class MediaOperationOwner {
         state: MediaOperationState;
         /** Terminal format mismatch after provider execution. */
         spentFailure: "output_format_mismatch" | null;
-        /** Definitive provider refusal with no delivered or billable output. */
-        providerRefusal: "safety_filter_refused" | null;
+        /** Safe terminal provider failure; no original cause or provider message. */
+        providerFailure: Readonly<{
+            /** Provider dispatch or output normalization, not a save failure. */
+            stage: Extract<MediaFailureStage, "provider" | "normalization">;
+            /** Preserve the model's safety refusal classification on replay. */
+            safetyRefused: boolean;
+            /** Allowlisted facts only; never the original error message or cause. */
+            provider?: MediaProviderDiagnostic | undefined;
+        }> | null;
         /** Pinned host price or unmetered quote. */
         estimatedCostMilliunits: number | null;
         /** Retained or saved image metadata. */
@@ -283,8 +313,15 @@ export declare class MediaOperationOwner {
         state: MediaOperationState;
         /** Terminal format mismatch after provider execution. */
         spentFailure: "output_format_mismatch" | null;
-        /** Definitive provider refusal with no delivered or billable output. */
-        providerRefusal: "safety_filter_refused" | null;
+        /** Safe terminal provider failure; no original cause or provider message. */
+        providerFailure: Readonly<{
+            /** Provider dispatch or output normalization, not a save failure. */
+            stage: Extract<MediaFailureStage, "provider" | "normalization">;
+            /** Preserve the model's safety refusal classification on replay. */
+            safetyRefused: boolean;
+            /** Allowlisted facts only; never the original error message or cause. */
+            provider?: MediaProviderDiagnostic | undefined;
+        }> | null;
         /** Pinned host price or unmetered quote. */
         estimatedCostMilliunits: number | null;
         /** Retained or saved image metadata. */