@fungi.computer/darkroom 0.3.1 → 0.4.1

package/README.md

@@ -113,9 +113,8 @@ save fails. An ambiguous provider execution is never silently dispatched again.
 
 Declare `metering: "unmetered"` when your host pays its provider directly. A
 metered host supplies idempotent `admit` and `settle` functions plus its own
-`refusalMessages` for insufficient credit, daily limits and denied spending.
-Quotes are estimates. Your metering owner decides the customer price and
-settlement.
+`refusalMessages` for insufficient credit and denied spending. Quotes are
+estimates. Your metering owner decides the customer price and settlement.
 
 A recognized provider safety refusal returns HTTP 400 with
 `code: "SAFETY_FILTER_REFUSED"`, `stage: "provider"`, and `retryable: false`.
@@ -162,12 +161,26 @@ 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.
+provider boundary classifies code `2021` as the optional, closed
+`provider.reason: "credits_exhausted"`. On 2026-10-27, a real GPT Image 2 call
+from the Prints UI returned
+`AiGatewayError: 2021: Insufficient AI Gateway credits`. The original evidence
+is `~/Botanical-cto/receipts/prints-e2e/REPORT.md:51` ("Follow-up 2"; no charge
+recorded at line 53) and
+`~/Botanical-cto/receipts/prints-e2e/gwfix/results.json` (02:01 local; GPT Image
+2 call at `2026-10-27T01:01:04.296Z`). The error object contained only
+`name: "AiGatewayError"` and `message: "2021: Insufficient AI Gateway credits"`;
+no HTTP status was recorded. This is observed provider wording from a real UI
+call, not a published guarantee that every Cloudflare `2021` means a zero
+balance. Apps consume the typed reason without interpreting provider numbers or
+public error prose, and should direct the owner to check AI Gateway credits and
+billing rather than infer the account balance. It is separate from the host's
+`INSUFFICIENT_CREDIT` Team billing refusal. 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
@@ -177,8 +190,8 @@ host. The other entries use ordinary platform web types.
 
 For Workers AI, use `createWorkersAiMediaProvider(env.AI)` from `cloudflare` and
 add an `AI` binding to your host. `createImagesReferenceFitter` prepares bounded
-reference images through an Images binding. Your host authorizes each reference
-read.
+reference images through an Images binding, using the selected catalog model
+passed to the fitter. Your host authorizes each reference read.
 
 `stripPrivateProvenance(bytes)` from `provenance` removes prompt and lineage
 metadata while preserving the AI marker, print ID and image encoding. It returns
@@ -187,9 +200,20 @@ bytes, MIME type and filename extension. The public XMP format uses
 
 ## Limits
 
-References are bounded to four files, 512 pixels per side and 8 MiB per image.
-Still-image output and public downloads are bounded to 32 MiB. Catalog models
-may impose tighter limits. Video output has its own 64 MiB provider bound.
+References are bounded to four files and 8 MiB per image. Image-model references
+keep a maximum 512-pixel long edge. Video-model frames and references preserve
+their aspect ratio and are fitted by the short edge to 320 pixels, growing
+smaller inputs when necessary; resolved video references must have a short edge
+of at least 320 pixels. Still-image output and public downloads are bounded to
+32 MiB. Catalog models may impose tighter limits. Video output has its own 64
+MiB provider bound.
+
+The 8 MiB reference budget also applies after transformation: extreme panoramas
+can still exceed the encoded-byte budget, even though video references have no
+512-pixel long-edge cap. Celld Hub reference fitting requires a
+[paired Hub and edge release](../../services/hub-edge/README.md#paired-hub-and-edge-release);
+the linked section includes the draft Fungi 0.7.1 release note and mixed-version
+failure window.
 
 Private-provenance export supports PNG, JPEG and WebP. GIF without XMP remains
 index-only. Signed, malformed and unsupported images return a typed refusal. The

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

@@ -1,4 +1,211 @@
 import * as z from "zod";
+/** A labelled estimate for one explicitly described generation, never a receipt. */
+export declare const mediaModelPriceEstimateSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"estimate">;
+    basis: z.ZodEnum<{
+        /** Provider cost before the host's billing policy. */
+        readonly "provider-cost": "provider-cost";
+        /** Team charge estimate after the host's billing policy. */
+        readonly "team-price": "team-price";
+    }>;
+    costMilliunits: z.ZodNumber;
+    settings: z.ZodObject<{
+        model: z.ZodString;
+        prompt: z.ZodString;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+        steps: z.ZodOptional<z.ZodNumber>;
+        durationSeconds: z.ZodOptional<z.ZodNumber>;
+        resolution: z.ZodOptional<z.ZodEnum<{
+            readonly p480: "480p";
+            readonly p720: "720p";
+            readonly p768: "768p";
+            readonly p1080: "1080p";
+            readonly p4k: "4k";
+        }>>;
+        aspectRatio: z.ZodOptional<z.ZodEnum<{
+            readonly wide: "16:9";
+            readonly landscape: "4:3";
+            readonly square: "1:1";
+            readonly portrait: "3:4";
+            readonly tall: "9:16";
+            readonly ultrawide: "21:9";
+            readonly ultratall: "9:21";
+        }>>;
+        generateAudio: z.ZodOptional<z.ZodBoolean>;
+        references: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            computerId: z.ZodString;
+            path: z.ZodString;
+            role: z.ZodOptional<z.ZodEnum<{
+                readonly first: "first-frame";
+                readonly last: "last-frame";
+                readonly reference: "reference";
+            }>>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+/** Host catalog projection; provider metadata remains owned by the sole catalog. */
+export declare const mediaCatalogModelSchema: z.ZodReadonly<z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    kind: z.ZodEnum<{
+        readonly image: "image";
+        readonly video: "video";
+    }>;
+    tier: z.ZodEnum<{
+        readonly draft: "draft";
+        readonly balanced: "balanced";
+        readonly premium: "premium";
+        readonly max: "max";
+    }>;
+    outputFormats: z.ZodReadonly<z.ZodArray<z.ZodEnum<{
+        readonly png: "png";
+        readonly jpeg: "jpeg";
+        readonly webp: "webp";
+    }>>>;
+    maxPromptLength: z.ZodNumber;
+    input: z.ZodLazy<z.ZodReadonly<z.ZodObject<{
+        transport: z.ZodEnum<{
+            readonly json: "json";
+            readonly multipart: "multipart";
+        }>;
+        dimensions: z.ZodEnum<{
+            readonly none: "none";
+            readonly own: "own";
+        }>;
+        maxDimension: z.ZodNullable<z.ZodNumber>;
+        maxDimensionDocumented: z.ZodBoolean;
+        defaultWidth: z.ZodNumber;
+        defaultHeight: z.ZodNumber;
+        steps: z.ZodEnum<{
+            readonly steps: "steps";
+            readonly num_steps: "num_steps";
+            readonly fixed: "fixed";
+        }>;
+        maxSteps: z.ZodNullable<z.ZodNumber>;
+        defaultSteps: z.ZodNullable<z.ZodNumber>;
+        referenceField: z.ZodNullable<z.ZodString>;
+        maxReferences: z.ZodNumber;
+    }, z.core.$strict>>>;
+    sizes: z.ZodNullable<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+    video: z.ZodNullable<z.ZodLazy<z.ZodReadonly<z.ZodObject<{
+        minSeconds: z.ZodNumber;
+        maxSeconds: z.ZodNumber;
+        defaultSeconds: z.ZodNumber;
+        durations: z.ZodReadonly<z.ZodArray<z.ZodNumber>>;
+        provider: z.ZodEnum<{
+            readonly seedance: "seedance";
+            readonly veo: "veo";
+            readonly minimax: "minimax";
+        }>;
+        formats: z.ZodReadonly<z.ZodArray<z.ZodLazy<z.ZodReadonly<z.ZodObject<{
+            resolution: z.ZodEnum<{
+                readonly p480: "480p";
+                readonly p720: "720p";
+                readonly p768: "768p";
+                readonly p1080: "1080p";
+                readonly p4k: "4k";
+            }>;
+            aspectRatio: z.ZodEnum<{
+                readonly wide: "16:9";
+                readonly landscape: "4:3";
+                readonly square: "1:1";
+                readonly portrait: "3:4";
+                readonly tall: "9:16";
+                readonly ultrawide: "21:9";
+                readonly ultratall: "9:21";
+            }>;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strict>>>>>;
+        defaultResolution: z.ZodEnum<{
+            readonly p480: "480p";
+            readonly p720: "720p";
+            readonly p768: "768p";
+            readonly p1080: "1080p";
+            readonly p4k: "4k";
+        }>;
+        defaultAspectRatio: z.ZodEnum<{
+            readonly wide: "16:9";
+            readonly landscape: "4:3";
+            readonly square: "1:1";
+            readonly portrait: "3:4";
+            readonly tall: "9:16";
+            readonly ultrawide: "21:9";
+            readonly ultratall: "9:21";
+        }>;
+        supportsAudio: z.ZodBoolean;
+        defaultGenerateAudio: z.ZodNullable<z.ZodBoolean>;
+        referenceRoles: z.ZodReadonly<z.ZodArray<z.ZodEnum<{
+            readonly first: "first-frame";
+            readonly last: "last-frame";
+            readonly reference: "reference";
+        }>>>;
+        maxReferenceImages: z.ZodNumber;
+        referenceResolutions: z.ZodReadonly<z.ZodArray<z.ZodEnum<{
+            readonly p480: "480p";
+            readonly p720: "720p";
+            readonly p768: "768p";
+            readonly p1080: "1080p";
+            readonly p4k: "4k";
+        }>>>;
+        prices: z.ZodReadonly<z.ZodArray<z.ZodReadonly<z.ZodObject<{
+            resolution: z.ZodEnum<{
+                readonly p480: "480p";
+                readonly p720: "720p";
+                readonly p768: "768p";
+                readonly p1080: "1080p";
+                readonly p4k: "4k";
+            }>;
+            silentMilliunitsPerSecond: z.ZodNumber;
+            audioMilliunitsPerSecond: z.ZodNumber;
+        }, z.core.$strict>>>>;
+    }, z.core.$strict>>>>;
+    priceEstimate: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodLiteral<"estimate">;
+        basis: z.ZodEnum<{
+            /** Provider cost before the host's billing policy. */
+            readonly "provider-cost": "provider-cost";
+            /** Team charge estimate after the host's billing policy. */
+            readonly "team-price": "team-price";
+        }>;
+        costMilliunits: z.ZodNumber;
+        settings: z.ZodObject<{
+            model: z.ZodString;
+            prompt: z.ZodString;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+            steps: z.ZodOptional<z.ZodNumber>;
+            durationSeconds: z.ZodOptional<z.ZodNumber>;
+            resolution: z.ZodOptional<z.ZodEnum<{
+                readonly p480: "480p";
+                readonly p720: "720p";
+                readonly p768: "768p";
+                readonly p1080: "1080p";
+                readonly p4k: "4k";
+            }>>;
+            aspectRatio: z.ZodOptional<z.ZodEnum<{
+                readonly wide: "16:9";
+                readonly landscape: "4:3";
+                readonly square: "1:1";
+                readonly portrait: "3:4";
+                readonly tall: "9:16";
+                readonly ultrawide: "21:9";
+                readonly ultratall: "9:21";
+            }>>;
+            generateAudio: z.ZodOptional<z.ZodBoolean>;
+            references: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                computerId: z.ZodString;
+                path: z.ZodString;
+                role: z.ZodOptional<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>>;
 /** Bounded catalog decoded by the App media broker before host filtering. */
 export declare const mediaModelsSchema: z.ZodLazy<z.ZodArray<z.ZodReadonly<z.ZodObject<{
     id: z.ZodString;
@@ -116,6 +323,50 @@ export declare const mediaModelsSchema: z.ZodLazy<z.ZodArray<z.ZodReadonly<z.Zod
             audioMilliunitsPerSecond: z.ZodNumber;
         }, z.core.$strict>>>>;
     }, z.core.$strict>>>>;
+    priceEstimate: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodLiteral<"estimate">;
+        basis: z.ZodEnum<{
+            /** Provider cost before the host's billing policy. */
+            readonly "provider-cost": "provider-cost";
+            /** Team charge estimate after the host's billing policy. */
+            readonly "team-price": "team-price";
+        }>;
+        costMilliunits: z.ZodNumber;
+        settings: z.ZodObject<{
+            model: z.ZodString;
+            prompt: z.ZodString;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+            steps: z.ZodOptional<z.ZodNumber>;
+            durationSeconds: z.ZodOptional<z.ZodNumber>;
+            resolution: z.ZodOptional<z.ZodEnum<{
+                readonly p480: "480p";
+                readonly p720: "720p";
+                readonly p768: "768p";
+                readonly p1080: "1080p";
+                readonly p4k: "4k";
+            }>>;
+            aspectRatio: z.ZodOptional<z.ZodEnum<{
+                readonly wide: "16:9";
+                readonly landscape: "4:3";
+                readonly square: "1:1";
+                readonly portrait: "3:4";
+                readonly tall: "9:16";
+                readonly ultrawide: "21:9";
+                readonly ultratall: "9:21";
+            }>>;
+            generateAudio: z.ZodOptional<z.ZodBoolean>;
+            references: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                computerId: z.ZodString;
+                path: z.ZodString;
+                role: z.ZodOptional<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>>>>;
 /** An absolute output path on the Computer admitted by the App host. */
 export declare const destinationSchema: z.ZodObject<{
@@ -206,6 +457,8 @@ export declare const appMediaBrokerFailureSchema: z.ZodObject<{
         readonly INSUFFICIENT_CREDIT: "INSUFFICIENT_CREDIT";
         readonly HOST_FAILURE: "HOST_FAILURE";
         readonly INVALID_ARGUMENT: "INVALID_ARGUMENT";
+        readonly MEDIA_PROVIDER_FAILURE: "MEDIA_PROVIDER_FAILURE";
+        readonly MEDIA_PROVIDER_FAILURE_UNCHARGED: "MEDIA_PROVIDER_FAILURE_UNCHARGED";
         readonly SAFETY_FILTER_REFUSED: "SAFETY_FILTER_REFUSED";
     }>;
     message: z.ZodString;
@@ -223,13 +476,7 @@ 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>>>;
+    provider: z.ZodOptional<z.ZodType<import("@fungi.computer/agar/errors").MediaProviderDiagnostic, unknown, z.core.$ZodTypeInternals<import("@fungi.computer/agar/errors").MediaProviderDiagnostic, 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<{
@@ -260,6 +507,8 @@ export declare const appMediaRefusalSchema: z.ZodUnion<readonly [z.ZodObject<{
         readonly INSUFFICIENT_CREDIT: "INSUFFICIENT_CREDIT";
         readonly HOST_FAILURE: "HOST_FAILURE";
         readonly INVALID_ARGUMENT: "INVALID_ARGUMENT";
+        readonly MEDIA_PROVIDER_FAILURE: "MEDIA_PROVIDER_FAILURE";
+        readonly MEDIA_PROVIDER_FAILURE_UNCHARGED: "MEDIA_PROVIDER_FAILURE_UNCHARGED";
         readonly SAFETY_FILTER_REFUSED: "SAFETY_FILTER_REFUSED";
     }>;
     message: z.ZodString;
@@ -277,13 +526,7 @@ 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>>>;
+    provider: z.ZodOptional<z.ZodType<import("@fungi.computer/agar/errors").MediaProviderDiagnostic, unknown, z.core.$ZodTypeInternals<import("@fungi.computer/agar/errors").MediaProviderDiagnostic, 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<{
@@ -402,6 +645,50 @@ export declare const appMediaModelsOutcomeSchema: z.ZodUnion<readonly [z.ZodLazy
             audioMilliunitsPerSecond: z.ZodNumber;
         }, z.core.$strict>>>>;
     }, z.core.$strict>>>>;
+    priceEstimate: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodLiteral<"estimate">;
+        basis: z.ZodEnum<{
+            /** Provider cost before the host's billing policy. */
+            readonly "provider-cost": "provider-cost";
+            /** Team charge estimate after the host's billing policy. */
+            readonly "team-price": "team-price";
+        }>;
+        costMilliunits: z.ZodNumber;
+        settings: z.ZodObject<{
+            model: z.ZodString;
+            prompt: z.ZodString;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+            steps: z.ZodOptional<z.ZodNumber>;
+            durationSeconds: z.ZodOptional<z.ZodNumber>;
+            resolution: z.ZodOptional<z.ZodEnum<{
+                readonly p480: "480p";
+                readonly p720: "720p";
+                readonly p768: "768p";
+                readonly p1080: "1080p";
+                readonly p4k: "4k";
+            }>>;
+            aspectRatio: z.ZodOptional<z.ZodEnum<{
+                readonly wide: "16:9";
+                readonly landscape: "4:3";
+                readonly square: "1:1";
+                readonly portrait: "3:4";
+                readonly tall: "9:16";
+                readonly ultrawide: "21:9";
+                readonly ultratall: "9:21";
+            }>>;
+            generateAudio: z.ZodOptional<z.ZodBoolean>;
+            references: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                computerId: z.ZodString;
+                path: z.ZodString;
+                role: z.ZodOptional<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.ZodUnion<readonly [z.ZodObject<{
     error: z.ZodEnum<{
         /** The broker refused the input representation or selection. */
@@ -430,6 +717,8 @@ export declare const appMediaModelsOutcomeSchema: z.ZodUnion<readonly [z.ZodLazy
         readonly INSUFFICIENT_CREDIT: "INSUFFICIENT_CREDIT";
         readonly HOST_FAILURE: "HOST_FAILURE";
         readonly INVALID_ARGUMENT: "INVALID_ARGUMENT";
+        readonly MEDIA_PROVIDER_FAILURE: "MEDIA_PROVIDER_FAILURE";
+        readonly MEDIA_PROVIDER_FAILURE_UNCHARGED: "MEDIA_PROVIDER_FAILURE_UNCHARGED";
         readonly SAFETY_FILTER_REFUSED: "SAFETY_FILTER_REFUSED";
     }>;
     message: z.ZodString;
@@ -447,13 +736,7 @@ 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>>>;
+    provider: z.ZodOptional<z.ZodType<import("@fungi.computer/agar/errors").MediaProviderDiagnostic, unknown, z.core.$ZodTypeInternals<import("@fungi.computer/agar/errors").MediaProviderDiagnostic, unknown>>>;
 }, z.core.$strict>]>]>;
 /** Completed generation, Agar polling result, or an existing broker refusal. */
 export declare const appMediaGenerationOutcomeSchema: z.ZodUnion<readonly [z.ZodObject<{
@@ -504,6 +787,8 @@ export declare const appMediaGenerationOutcomeSchema: z.ZodUnion<readonly [z.Zod
         readonly INSUFFICIENT_CREDIT: "INSUFFICIENT_CREDIT";
         readonly HOST_FAILURE: "HOST_FAILURE";
         readonly INVALID_ARGUMENT: "INVALID_ARGUMENT";
+        readonly MEDIA_PROVIDER_FAILURE: "MEDIA_PROVIDER_FAILURE";
+        readonly MEDIA_PROVIDER_FAILURE_UNCHARGED: "MEDIA_PROVIDER_FAILURE_UNCHARGED";
         readonly SAFETY_FILTER_REFUSED: "SAFETY_FILTER_REFUSED";
     }>;
     message: z.ZodString;
@@ -521,11 +806,5 @@ 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>>>;
+    provider: z.ZodOptional<z.ZodType<import("@fungi.computer/agar/errors").MediaProviderDiagnostic, unknown, z.core.$ZodTypeInternals<import("@fungi.computer/agar/errors").MediaProviderDiagnostic, unknown>>>;
 }, z.core.$strict>]>]>;

package/dist/app-media-contracts.js

@@ -3,8 +3,33 @@ import { listMediaModels, mediaModelSchema } from "./model-catalog.js";
 import { mediaResultSchema } from "./media-operation-contract.js";
 import { pendingSchema } from "@fungi.computer/agar/backend-definition";
 import { mediaFailureSchema } from "./browser-failure.js";
+import { mediaGenerationSettingsSchema } from "./index.js";
+/** A labelled estimate for one explicitly described generation, never a receipt. */
+export const mediaModelPriceEstimateSchema = z.strictObject({
+    /** Quotes are indicative; the admitted generation owns its charge. */
+    kind: z.literal("estimate"),
+    /** Unmetered hosts pay provider cost; funded hosts apply their billing policy. */
+    basis: z.enum({
+        /** Provider cost before the host's billing policy. */
+        "provider-cost": "provider-cost",
+        /** Team charge estimate after the host's billing policy. */
+        "team-price": "team-price",
+    }),
+    /** Milliunits of a cent, at the quoted settings. */
+    costMilliunits: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
+    /** Defaults, a one-character prompt and no references; varying these changes cost. */
+    settings: mediaGenerationSettingsSchema,
+});
+/** Host catalog projection; provider metadata remains owned by the sole catalog. */
+export const mediaCatalogModelSchema = mediaModelSchema
+    .unwrap()
+    .extend({
+    /** Optional host estimate with explicit assumptions and funding basis. */
+    priceEstimate: mediaModelPriceEstimateSchema.optional(),
+})
+    .readonly();
 /** Bounded catalog decoded by the App media broker before host filtering. */
-export const mediaModelsSchema = z.lazy(() => z.array(mediaModelSchema).max(listMediaModels().length));
+export const mediaModelsSchema = z.lazy(() => z.array(mediaCatalogModelSchema).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. */

package/dist/browser-failure.d.ts

@@ -29,17 +29,15 @@ export declare const mediaFailureSchema: z.ZodObject<{
         readonly HOST_FAILURE: "HOST_FAILURE";
         /** The host refused the selected input. */
         readonly INVALID_ARGUMENT: "INVALID_ARGUMENT";
+        /** The inference provider did not complete generation. */
+        readonly MEDIA_PROVIDER_FAILURE: "MEDIA_PROVIDER_FAILURE";
+        /** The host confirmed zero-unit customer settlement after provider failure. */
+        readonly MEDIA_PROVIDER_FAILURE_UNCHARGED: "MEDIA_PROVIDER_FAILURE_UNCHARGED";
         /** The model's safety filter refused generation. */
         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>>>;
+    provider: z.ZodOptional<z.ZodType<import("@fungi.computer/agar/errors").MediaProviderDiagnostic, unknown, z.core.$ZodTypeInternals<import("@fungi.computer/agar/errors").MediaProviderDiagnostic, 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

@@ -19,6 +19,10 @@ export const mediaFailureSchema = z.strictObject({
         HOST_FAILURE: "HOST_FAILURE",
         /** The host refused the selected input. */
         INVALID_ARGUMENT: "INVALID_ARGUMENT",
+        /** The inference provider did not complete generation. */
+        MEDIA_PROVIDER_FAILURE: "MEDIA_PROVIDER_FAILURE",
+        /** The host confirmed zero-unit customer settlement after provider failure. */
+        MEDIA_PROVIDER_FAILURE_UNCHARGED: "MEDIA_PROVIDER_FAILURE_UNCHARGED",
         /** The model's safety filter refused generation. */
         SAFETY_FILTER_REFUSED: "SAFETY_FILTER_REFUSED",
     }),
@@ -27,8 +31,9 @@ export const mediaFailureSchema = z.strictObject({
     /** Allowlisted provider facts only; the original cause never crosses HTTP. */
     provider: mediaProviderDiagnosticWireSchema.optional(),
 });
-const decodeJson = Schema.decodeUnknownOption(Schema.fromJsonString(Schema.Json));
 function parseMediaFailureJson(json) {
+    // Schema-only App consumers must not retain the browser's JSON decoder.
+    const decodeJson = Schema.decodeUnknownOption(Schema.fromJsonString(Schema.Json));
     const parsed = mediaFailureSchema.safeParse(Option.getOrUndefined(decodeJson(json)));
     return parsed.success ? parsed.data : null;
 }

package/dist/cloudflare/provider.d.ts

@@ -1,4 +1,26 @@
-import { type MediaAiResult, type MediaGenerationSettings, type MediaProvider, type MediaReferenceBytes } from "../index.js";
+import { type MediaModel, type MediaAiResult, type MediaGenerationSettings, type MediaProvider, type MediaReferenceBytes } from "../index.js";
+/** Quote the catalog defaults through the exact estimator used before dispatch. */
+export declare function estimateMediaModel(model: MediaModel): {
+    /** An indicative quote, not an admitted generation receipt. */
+    kind: "estimate";
+    /** Provider cost before the host's billing policy. */
+    basis: "provider-cost";
+    /** Catalog defaults, a one-character prompt and no references. */
+    settings: Readonly<{
+        model: string;
+        prompt: string;
+        width: number;
+        height: number;
+        steps?: number;
+        durationSeconds?: number;
+        resolution?: import("../model-catalog.js").MediaVideoResolution;
+        aspectRatio?: import("../model-catalog.js").MediaVideoAspectRatio;
+        generateAudio?: boolean;
+        references?: readonly import("../index.js").MediaReference[];
+    }>;
+    /** Estimated provider milliunits of a cent for these exact settings. */
+    costMilliunits: number;
+};
 /** Workers AI results vary by model; the provider decodes them at this boundary. */
 export type MediaAiPort = {
     /** Dispatch to the native Workers AI binding. */