@fungi.computer/darkroom 0.1.0 → 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

@@ -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<{
@@ -268,6 +275,13 @@ 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.ZodLazy<z.ZodArray<z.ZodReadonly<z.ZodObject<{
@@ -429,6 +443,13 @@ export declare const appMediaModelsOutcomeSchema: z.ZodUnion<readonly [z.ZodLazy
         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<{
@@ -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

@@ -75,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";
@@ -31,16 +32,6 @@ const providerFailureCode = z.lazy(() => z
     .transform((message) => Number(message.split(":", 1)[0]))
     .nullable()
     .catch(null));
-const providerFailureCategory = z.lazy(() => z
-    .enum([
-    "InferenceUpstreamError",
-    "AiInternalError",
-    "TypeError",
-    "AbortError",
-    "TimeoutError",
-    "Error",
-])
-    .catch("Error"));
 // Recognize the refusal, not the generic Workers AI error number or prompt text.
 const safetyFilterMessage = z.lazy(() => z.union([
     z
@@ -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/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/media-binding.d.ts

@@ -1,5 +1,4 @@
 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. */
@@ -272,17 +271,24 @@ export declare const mediaPendingSchema: z.ZodLazy<z.ZodObject<{
     retryAfterSeconds: z.ZodNumber;
 }, 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. */
@@ -44,17 +54,23 @@ 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({
+        /** 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.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. */
@@ -122,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,6 +2,8 @@ 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.ZodLazy<z.ZodObject<{
     computerId: z.ZodString;
@@ -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. */

package/dist/media-operation-owner.js

@@ -3,8 +3,13 @@ import { defineIdFamily } from "@fungi.computer/cairn/id";
 import { mediaGenerationSettingsSchema, validateMediaGenerationSettings, } from "./index.js";
 import { z } from "zod";
 import { reportCatchFailure } from "./failure.js";
-import { MediaSafetyFilterRefusal } from "./execution-error.js";
-const providerRefusalSchema = z.literal("safety_filter_refused");
+import { MediaExecutionError, MediaSafetyFilterRefusal, mediaFailureStageSchema, } from "./execution-error.js";
+import { mediaProviderDiagnosticWireSchema, } from "@fungi.computer/agar/errors";
+const providerFailureSchema = z.strictObject({
+    stage: mediaFailureStageSchema.extract(["provider", "normalization"]),
+    safetyRefused: z.boolean(),
+    provider: mediaProviderDiagnosticWireSchema.optional(),
+});
 const ids = defineIdFamily({
     family: "hub-media-operation",
     version: 1,
@@ -143,7 +148,7 @@ const schemaStatements = [
     dispatched_at INTEGER
   ) STRICT`,
     "CREATE TABLE hub_media_spent_failure (singleton INTEGER PRIMARY KEY CHECK(singleton=1),code TEXT NOT NULL CHECK(code='output_format_mismatch')) STRICT",
-    "CREATE TABLE hub_media_provider_refusal (singleton INTEGER PRIMARY KEY CHECK(singleton=1),code TEXT NOT NULL CHECK(code='safety_filter_refused')) STRICT",
+    "CREATE TABLE hub_media_provider_failure (singleton INTEGER PRIMARY KEY CHECK(singleton=1),failure_json TEXT NOT NULL) STRICT",
 ];
 function fingerprint(input) {
     return JSON.stringify(input);
@@ -235,8 +240,8 @@ export class MediaOperationOwner {
         }
         else {
             // Pre-launch stores use the current fresh schema or get reset by the host.
-            // Missing refusal facts are not healed or incrementally migrated here.
-            this.ctx.storage.sql.exec("SELECT code FROM hub_media_provider_refusal LIMIT 0");
+            // Missing failure facts are not healed or incrementally migrated here.
+            this.ctx.storage.sql.exec("SELECT failure_json FROM hub_media_provider_failure LIMIT 0");
         }
         this.initialized = true;
     }
@@ -301,12 +306,14 @@ export class MediaOperationOwner {
                 code: z.literal("output_format_mismatch"),
             })
                 .parse(failure).code;
-        const refusal = this.ctx.storage.sql
-            .exec("SELECT code FROM hub_media_provider_refusal WHERE singleton=1")
+        const failureRow = this.ctx.storage.sql
+            .exec("SELECT failure_json FROM hub_media_provider_failure WHERE singleton=1")
             .toArray()[0];
-        const providerRefusal = refusal === undefined
+        const providerFailure = failureRow === undefined
             ? null
-            : z.strictObject({ code: providerRefusalSchema }).parse(refusal).code;
+            : this.decodeJson(z
+                .strictObject({ failure_json: z.string().max(1024) })
+                .parse(failureRow).failure_json, providerFailureSchema);
         return Object.freeze({
             operationId: record.operationId,
             requestId: record.requestId,
@@ -314,7 +321,7 @@ export class MediaOperationOwner {
             owner: record.owner,
             state: record.state,
             spentFailure,
-            providerRefusal,
+            providerFailure,
             estimatedCostMilliunits: record.estimatedCostMilliunits,
             image: record.image,
             result: record.result,
@@ -684,8 +691,13 @@ export class MediaOperationOwner {
             // Nothing was delivered; the next retry sees interrupted and releases
             // the billing hold at zero units.
             try {
-                this.interruptGeneration(leaseId, cause instanceof MediaSafetyFilterRefusal
-                    ? "safety_filter_refused"
+                this.interruptGeneration(leaseId, cause instanceof MediaExecutionError &&
+                    (cause.stage === "provider" || cause.stage === "normalization")
+                    ? {
+                        stage: cause.stage,
+                        safetyRefused: cause instanceof MediaSafetyFilterRefusal,
+                        provider: cause.provider,
+                    }
                     : undefined);
             }
             catch (cause) {
@@ -702,8 +714,8 @@ export class MediaOperationOwner {
         this.ctx.storage.sql.exec("UPDATE hub_media_operation SET lease_id=NULL, lease_expires_at=NULL WHERE singleton=1 AND state='writing' AND lease_id=?", leaseId);
     }
     /** An aborted in-flight provider call is terminal for this request ID. */
-    interruptGeneration(leaseId, refusalInput) {
-        const refusal = providerRefusalSchema.optional().parse(refusalInput);
+    interruptGeneration(leaseId, failureInput) {
+        const failure = providerFailureSchema.optional().parse(failureInput);
         const record = this.requireRecord();
         if (record.state !== "generating" || record.leaseId !== leaseId)
             throw new MediaOperationError("lease_lost");
@@ -720,8 +732,8 @@ export class MediaOperationOwner {
                 writeReceipt: null,
                 result: null,
             });
-            if (refusal !== undefined)
-                this.ctx.storage.sql.exec("INSERT INTO hub_media_provider_refusal(singleton,code) VALUES(1,?)", refusal);
+            if (failure !== undefined)
+                this.ctx.storage.sql.exec("INSERT INTO hub_media_provider_failure(singleton,failure_json) VALUES(1,?)", JSON.stringify(failure));
             return this.project(interrupted);
         });
     }

package/dist/media-operation.js

@@ -72,8 +72,13 @@ export function executeMediaOperation(input) {
         }
         if (claim.kind === "interrupted") {
             yield* settleNothing();
-            if (claim.operation.providerRefusal === "safety_filter_refused")
-                return yield* Effect.fail(new MediaSafetyFilterRefusal());
+            const failure = claim.operation.providerFailure;
+            if (failure !== null)
+                return yield* Effect.fail(failure.safetyRefused
+                    ? new MediaSafetyFilterRefusal({ provider: failure.provider })
+                    : new MediaExecutionError(failure.stage, {
+                        provider: failure.provider,
+                    }));
         }
         if (claim.kind !== "claimed" || claim.leaseId === undefined)
             return {
@@ -149,11 +154,16 @@ export function executeMediaOperation(input) {
                 }, "provider").pipe(
                 // A provider failure delivered nothing and wrote no output: end the
                 // request now and release its hold rather than leave it unresolved.
-                Effect.tapError((error) => error.stage === "provider"
-                    ? call(() => input.operation.interruptGeneration(leaseId, error instanceof MediaSafetyFilterRefusal
-                        ? "safety_filter_refused"
-                        : undefined), "operation").pipe(Effect.andThen(settleNothing()), Effect.ignore)
-                    : Effect.void));
+                Effect.tapError((error) => {
+                    const stage = error.stage;
+                    return stage === "provider" || stage === "normalization"
+                        ? call(() => input.operation.interruptGeneration(leaseId, {
+                            stage,
+                            safetyRefused: error instanceof MediaSafetyFilterRefusal,
+                            provider: error.provider,
+                        }), "operation").pipe(Effect.andThen(settleNothing()), Effect.ignore)
+                        : Effect.void;
+                }));
                 if (generation.kind === "interrupted") {
                     yield* settleNothing();
                     return { kind: "interrupted" };

package/dist/server.d.ts

@@ -4,7 +4,7 @@ import { z } from "zod";
 import { validateMediaGenerationSettings, type MediaProvider, type MediaReference, type MediaReferenceBytes } from "./index.js";
 import { type MediaExecution, type MediaMetering } from "./media-operation-contract.js";
 import { MediaExecutionError, type MediaBillingRefusalCode } from "./execution-error.js";
-export { MediaBillingRefusal, MediaExecutionError, type MediaBillingRefusalCode, type MediaFailureStage, } from "./execution-error.js";
+export { MediaBillingRefusal, MediaExecutionError, type MediaBillingRefusalCode, type MediaFailureStage, type MediaExecutionErrorOptions, } from "./execution-error.js";
 export { mediaUnits, type MediaUnits } from "./gateway-models.js";
 export type { MediaMetering, MediaOperation, } from "./media-operation-contract.js";
 export { MediaOperationOwner, mediaOperationDestinationSchema, mediaOperationCoordinatesSchema, mediaOperationStateSchema, mediaImageSchema, mediaOperationResultSchema, } from "./media-operation-owner.js";

package/dist/server.js

@@ -51,6 +51,7 @@ function failure(error, refusalMessages) {
             stage: "provider",
             code: "SAFETY_FILTER_REFUSED",
             retryable: false,
+            provider: error.provider,
         }, { status: 400, headers });
     if (error instanceof MediaExecutionError &&
         error.cause instanceof MediaOutputFormatMismatch)
@@ -105,6 +106,7 @@ function failure(error, refusalMessages) {
         stage: error.stage,
         code: "HOST_FAILURE",
         retryable: error.stage !== "normalization" && error.stage !== "provider",
+        provider: error instanceof MediaExecutionError ? error.provider : undefined,
     }, {
         status: 503,
         headers,