@fungi.computer/darkroom 0.3.0 → 0.4.0

package/dist/cloudflare/provider.js

@@ -1,12 +1,31 @@
 import { z } from "zod";
 import * as Redacted from "effect/Redacted";
-import { buildProviderInput, getMediaModel, estimateImageMilliunits, normalizeMediaProviderOutput, mediaProviderWireSchema, } from "../index.js";
+import { buildProviderInput, getMediaModel, estimateImageMilliunits, normalizeMediaProviderOutput, mediaProviderWireSchema, validateMediaGenerationSettings, } 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";
 import { readResponseBytes } from "../index.js";
+/** Quote the catalog defaults through the exact estimator used before dispatch. */
+export function estimateMediaModel(model) {
+    const settings = validateMediaGenerationSettings({
+        model: model.id,
+        prompt: "x",
+        width: model.input.defaultWidth,
+        height: model.input.defaultHeight,
+    });
+    return {
+        /** 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,
+        /** Estimated provider milliunits of a cent for these exact settings. */
+        costMilliunits: estimate(settings, []),
+    };
+}
 export function estimate(settings, references) {
     const params = {
         width: settings.width,
@@ -25,15 +44,21 @@ export function estimate(settings, references) {
     }
 }
 // Workers AI prefixes upstream error messages with its numeric internal code.
-// Parse only that bounded identifier; the remaining message is never logged.
+// Parse only that bounded identifier; printable prose is separately decoded.
 const providerFailureCode = z.lazy(() => z
     .string()
     .regex(/^\d{4,5}: /u)
     .transform((message) => Number(message.split(":", 1)[0]))
     .nullable()
     .catch(null));
+// Observed in a real Flux replay: HTTP 400/code 3030. Match the complete
+// bounded refusal, not 3030 itself; the code is not documented as transient.
+const outputFlaggedMessage = z
+    .string()
+    .regex(/^(?:\d{4,5}: )?(?:AiError: ){0,3}Your output has been flagged\. Please choose another prompt \/ input image combination \([0-9a-f-]{36}\)$/u);
 // Recognize the refusal, not the generic Workers AI error number or prompt text.
 const safetyFilterMessage = z.lazy(() => z.union([
+    outputFlaggedMessage,
     z
         .string()
         .regex(/(?:^|:\s)(?:AiError:\s)?Input prompt contains NSFW content\b/iu),
@@ -78,16 +103,28 @@ function routedOptions(options, signal, input) {
 }
 /** 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.
+    const category = decodeMediaProviderErrorCategory(cause instanceof Error ? cause.name : undefined);
+    const code = providerFailureCode.parse(cause instanceof Error ? cause.message : undefined);
+    // Observed 2026-10-27 in a real GPT Image 2 call from the Prints UI:
+    // "AiGatewayError: 2021: Insufficient AI Gateway credits" (no charge).
+    // Sources: ~/Botanical-cto/receipts/prints-e2e/REPORT.md:51 ("Follow-up 2")
+    // and ~/Botanical-cto/receipts/prints-e2e/gwfix/results.json (02:01 local;
+    // call at 2026-10-27T01:01:04.296Z). The error had only name and message;
+    // no HTTP status was recorded. This is observed wording, not a general
+    // Cloudflare code guarantee. Keep numeric classification at this owner.
+    const provider = code === 2021
+        ? { category, code, reason: "credits_exhausted" }
+        : { category, code };
+    const safeMessage = outputFlaggedMessage.safeParse(cause instanceof Error ? cause.message : undefined);
+    // The maintained Workers AI errors expose name/message, not a Response or
+    // cause chain. Only the complete, bounded refusal grammar above is safe to
+    // print. Unmodeled upstream prose/bodies can echo private request content;
+    // retain the original error (including any nested details) only as redacted.
     console.error("Media provider request failed", {
         model,
         providerCode: provider.code,
         category: provider.category,
+        providerMessage: safeMessage.success ? safeMessage.data : undefined,
     }, Redacted.make(cause));
     return cause instanceof Error &&
         safetyFilterMessage.safeParse(cause.message).success
@@ -145,15 +182,31 @@ export async function generate(ai, settings, references, signal, options, fetchR
     catch (cause) {
         throw new MediaExecutionError("normalization", { cause });
     }
-    let providerValue;
-    try {
-        providerValue = await ai.run(settings.model, workersAiInput(providerInput), routedOptions(options, signal, {
+    const invoke = async () => {
+        return ai.run(settings.model, workersAiInput(providerInput), routedOptions(options, signal, {
             stream: providerInput.transport === "multipart",
             images: references.length,
         }));
+    };
+    let providerValue;
+    try {
+        providerValue = await invoke();
     }
     catch (cause) {
-        throw providerFailure(settings.model, cause);
+        // Only 3040 is documented as capacity temporarily exceeded:
+        // https://developers.cloudflare.com/workers-ai/platform/errors/
+        // One product-call retry, never a test retry. Rebuild the multipart body
+        // inside invoke: a failed binding call may already have consumed it.
+        if (providerFailureCode.parse(cause instanceof Error ? cause.message : undefined) !== 3040 ||
+            signal?.aborted)
+            throw providerFailure(settings.model, cause);
+        try {
+            providerValue = await invoke();
+        }
+        catch (cause) {
+            // One terminal diagnostic for the product call, not one per attempt.
+            throw providerFailure(settings.model, cause);
+        }
     }
     try {
         return await normalizeMediaProviderOutput(mediaProviderWireSchema.parse(providerValue));

package/dist/cloudflare/reference-images.d.ts

@@ -5,13 +5,13 @@ export type MediaImagePort = {
     info(input: ReadableStream<Uint8Array>): ReturnType<ImagesBinding["info"]>;
     /** Start the native resize and encode chain. */
     input(input: ReadableStream<Uint8Array>): {
-        /** Apply the native scale-down transform. */
+        /** Apply the native aspect-preserving resize. */
         transform(options: {
             /** Image width in pixels. */
             width: number;
             /** Image height in pixels. */
             height: number;
-            fit: "scale-down";
+            fit: "scale-down" | "contain";
         }): {
             /** Encode the transformed image through the native Images binding. */
             output(options: {
@@ -30,8 +30,8 @@ export type MediaImagePort = {
 };
 /**
  * Media's reference preparation on the Images binding: decode the real bytes,
- * scale an oversized image down to MAX_REFERENCE_DIMENSION as PNG, then decode
- * the output so its metadata describes the bytes actually sent.
+ * fit the selected model's reference size as PNG, then decode the output so
+ * its metadata describes the bytes actually sent.
  */
 export declare function createImagesReferenceFitter(images: MediaImagePort): ReferenceImageFitter;
 /**

package/dist/cloudflare/reference-images.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
-import { MAX_REFERENCE_BYTES, MAX_REFERENCE_DIMENSION, MediaSettingsError, viewDimensionSchema, } from "../index.js";
+import { MAX_REFERENCE_BYTES, MediaSettingsError, viewDimensionSchema, } from "../index.js";
+import { referenceImageTransform } from "../reference-image-size.js";
 /** The retained `read_image` encoding: JPEG at quality 80. */
 const VIEW_JPEG_QUALITY = 80;
 const metadata = z.lazy(() => z.object({
@@ -21,11 +22,11 @@ const stream = (bytes) => new ReadableStream({
 });
 /**
  * Media's reference preparation on the Images binding: decode the real bytes,
- * scale an oversized image down to MAX_REFERENCE_DIMENSION as PNG, then decode
- * the output so its metadata describes the bytes actually sent.
+ * fit the selected model's reference size as PNG, then decode the output so
+ * its metadata describes the bytes actually sent.
  */
 export function createImagesReferenceFitter(images) {
-    return async (input) => {
+    return async (input, model) => {
         let bytes = input;
         let info;
         try {
@@ -35,15 +36,11 @@ export function createImagesReferenceFitter(images) {
             // The Images failure detail is never surfaced; the caller's bytes are.
             throw new MediaSettingsError("reference image is not a supported image");
         }
-        if (info.width > MAX_REFERENCE_DIMENSION ||
-            info.height > MAX_REFERENCE_DIMENSION) {
+        const transform = referenceImageTransform(model, info.width, info.height);
+        if (info.width !== transform.width || info.height !== transform.height) {
             const output = await images
                 .input(stream(bytes))
-                .transform({
-                width: MAX_REFERENCE_DIMENSION,
-                height: MAX_REFERENCE_DIMENSION,
-                fit: "scale-down",
-            })
+                .transform(transform)
                 .output({
                 format: "image/png",
             });

package/dist/execution-error.d.ts

@@ -31,6 +31,8 @@ export type MediaFailureStage = Exclude<z.output<typeof mediaFailureStageSchema>
 export type MediaExecutionErrorOptions = ErrorOptions & {
     /** Safe provider facts, when the failure came from provider transport. */
     readonly provider?: MediaProviderDiagnostic | undefined;
+    /** Confirmed zero-unit customer settlement, never an upstream billing claim. */
+    readonly customerCharge?: "none" | undefined;
 };
 /** A bounded stage marker for failures that cross the Media HTTP boundary. */
 export declare class MediaExecutionError extends Error {
@@ -38,6 +40,8 @@ export declare class MediaExecutionError extends Error {
     readonly stage: MediaFailureStage;
     /** Safe provider facts only; the original cause remains private. */
     readonly provider: MediaProviderDiagnostic | undefined;
+    /** Unknown unless the execution owner confirmed zero-unit settlement. */
+    readonly customerCharge: "none" | "unknown";
     constructor(
     /** Execution stage where the failure occurred. */
     stage: MediaFailureStage, options?: MediaExecutionErrorOptions);

package/dist/execution-error.js

@@ -30,12 +30,15 @@ export class MediaExecutionError extends Error {
     stage;
     /** Safe provider facts only; the original cause remains private. */
     provider;
+    /** Unknown unless the execution owner confirmed zero-unit settlement. */
+    customerCharge;
     constructor(
     /** Execution stage where the failure occurred. */
     stage, options) {
         super(`Media ${stage} failed`, options);
         this.stage = stage;
         this.name = "MediaExecutionError";
+        this.customerCharge = options?.customerCharge ?? "unknown";
         this.provider =
             options?.provider === undefined
                 ? undefined

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import * as z from "zod";
+export { MAX_REFERENCE_DIMENSION } from "./reference-image-size.js";
 import { type MediaVideoReferenceRole, type MediaVideoModelId, type MediaVideoResolution, type MediaVideoAspectRatio } from "./model-catalog.js";
 export { mediaFailureStageSchema } from "./execution-error.js";
 export { MAX_MEDIA_PROMPT_LENGTH, getMediaModel, MAX_REFERENCE_COUNT, listMediaModels, mediaModelInputSchema, mediaModelSchema, mediaRequestedImageFormatSchema, mediaModels, mediaModelTierSchema, MediaSettingsError, mediaVideoModelIdSchema, mediaVideoResolutionSchema, mediaVideoAspectRatioSchema, mediaVideoReferenceRoleSchema, mediaVideoFormatSchema, mediaVideoSchema, } from "./model-catalog.js";
@@ -64,10 +65,10 @@ export type MediaProvider = (settings: MediaGenerationSettings, references: read
     /** Actual output encoding. */
     format: string;
 }>>;
-/** A decoded reference image, scaled within MAX_REFERENCE_DIMENSION. */
+/** A decoded reference image, fitted for the selected model. */
 export type FittedReferenceImage = Omit<MediaReferenceBytes, "filename">;
-/** Decode one reference image and scale it within Media's dimension bound. */
-export type ReferenceImageFitter = (bytes: Uint8Array) => Promise<FittedReferenceImage>;
+/** Decode and fit a reference: image long edge ≤512, video short edge ≥320. */
+export type ReferenceImageFitter = (bytes: Uint8Array, model: string) => Promise<FittedReferenceImage>;
 /** The long-edge bounds a viewer may ask for when fitting an image to look at. */
 export declare const MIN_VIEW_DIMENSION = 256;
 /** Maximum long-edge size accepted by an image viewer, in pixels. */
@@ -80,8 +81,6 @@ export declare const viewDimensionSchema: z.ZodLazy<z.ZodNumber>;
  * a lossy JPEG, so a viewer can step the dimension down to meet a byte budget.
  */
 export type ImageViewFitter = (bytes: Uint8Array, maxDimension: number) => Promise<FittedReferenceImage>;
-/** Maximum reference width and height sent to inference, in pixels. */
-export declare const MAX_REFERENCE_DIMENSION = 512;
 /** Maximum decoded bytes per reference image. */
 export declare const MAX_REFERENCE_BYTES: number;
 /** Maximum retained still-image output bytes. */
@@ -123,7 +122,7 @@ export declare const mediaGenerationSettingsSchema: z.ZodObject<{
 }, z.core.$strict>;
 /** Caller settings before model defaults and refinements are applied. */
 export type MediaGenerationSettingsInput = z.input<typeof mediaGenerationSettingsSchema>;
-/** App selections contain paths; the host supplies the admitted Computer. */
+/** A reference may select another Computer; identity never grants access. */
 export declare const mediaGenerationSelectionSchema: z.ZodObject<{
     model: z.ZodString;
     prompt: z.ZodString;
@@ -149,6 +148,7 @@ export declare const mediaGenerationSelectionSchema: z.ZodObject<{
     }>>;
     generateAudio: z.ZodOptional<z.ZodBoolean>;
     references: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        computerId: z.ZodOptional<z.ZodString>;
         path: z.ZodString;
         role: z.ZodOptional<z.ZodEnum<{
             readonly first: "first-frame";
@@ -161,12 +161,14 @@ export declare const mediaGenerationSelectionSchema: z.ZodObject<{
 export type MediaGenerationSelection = z.output<typeof mediaGenerationSelectionSchema>;
 /** Validate caller settings and apply retained model defaults. */
 export declare const validateMediaGenerationSettings: (raw: MediaGenerationSettingsInput) => MediaGenerationSettings;
-/** Validate path-only selections without inventing a Computer identity. */
+/** Validate selections without granting Computer authority. */
 export declare const validateMediaGenerationSelection: (raw: z.input<typeof mediaGenerationSelectionSchema>) => Readonly<Omit<MediaGenerationSettings, "references"> & {
     /** Host-authorized reference images. */
     references?: readonly Readonly<{
         /** Fixed destination or reference file path. */
         path: string;
+        /** Optional reference Computer; authorization remains host-owned. */
+        computerId?: string;
         /** Video-only reference role. */
         role?: MediaVideoReferenceRole;
     }>[];
@@ -247,8 +249,8 @@ export type MediaVideoSelection = Readonly<{
 export declare function validateMediaVideoSelection(raw: MediaVideoSelectionInput): MediaVideoSelection;
 /** Host-authorized reader for decoded reference images. */
 export type MediaReferenceReader = Readonly<{
-    /** Authorize and read one reference into bounded decoded image bytes. */
-    read: (reference: MediaReference) => Promise<MediaReferenceBytes>;
+    /** Authorize and fit one reference for the selected catalog model. */
+    read: (reference: MediaReference, model: string) => Promise<MediaReferenceBytes>;
 }>;
 /** Resolve only provider-accepted references through the caller's reader. */
 export declare const resolveMediaReferences: (settings: MediaGenerationSettings, reader: MediaReferenceReader) => Promise<readonly MediaReferenceBytes[]>;

package/dist/index.js

@@ -1,5 +1,7 @@
 import * as z from "zod";
 import { reportCatchFailure } from "./failure.js";
+import { referenceImageSizeIsValid } from "./reference-image-size.js";
+export { MAX_REFERENCE_DIMENSION } from "./reference-image-size.js";
 import { getMediaModel, MAX_REFERENCE_COUNT, MediaSettingsError, mediaVideoModelIdSchema, mediaVideoResolutionSchema, mediaVideoAspectRatioSchema, mediaVideoReferenceRoleSchema, MAX_MEDIA_PROMPT_LENGTH, } from "./model-catalog.js";
 export { mediaFailureStageSchema } from "./execution-error.js";
 export { MAX_MEDIA_PROMPT_LENGTH, getMediaModel, MAX_REFERENCE_COUNT, listMediaModels, mediaModelInputSchema, mediaModelSchema, mediaRequestedImageFormatSchema, mediaModels, mediaModelTierSchema, MediaSettingsError, mediaVideoModelIdSchema, mediaVideoResolutionSchema, mediaVideoAspectRatioSchema, mediaVideoReferenceRoleSchema, mediaVideoFormatSchema, mediaVideoSchema, } from "./model-catalog.js";
@@ -11,8 +13,6 @@ export const MAX_VIEW_DIMENSION = 512;
 export const viewDimensionSchema = z.lazy(() => z.number().int().min(MIN_VIEW_DIMENSION).max(MAX_VIEW_DIMENSION));
 /** Reference images in one video request: every verified video model's catalog value. */
 const MAX_VIDEO_REFERENCE_COUNT = 4;
-/** Maximum reference width and height sent to inference, in pixels. */
-export const MAX_REFERENCE_DIMENSION = 512;
 /** Maximum decoded bytes per reference image. */
 export const MAX_REFERENCE_BYTES = 8 * 1024 * 1024;
 /** Maximum retained still-image output bytes. */
@@ -74,12 +74,14 @@ export const mediaGenerationSettingsSchema = z
         .optional(),
 })
     .strict();
-/** App selections contain paths; the host supplies the admitted Computer. */
+/** A reference may select another Computer; identity never grants access. */
 export const mediaGenerationSelectionSchema = mediaGenerationSettingsSchema.extend({
     /** Host-authorized reference images. */
     references: z
         .array(z
         .object({
+        /** Omit for the selected Computer; the host authorizes every named Computer. */
+        computerId: z.string().min(1).max(256).optional(),
         /** Fixed destination or reference file path. */
         path: z.string().min(1).max(4_096),
         /** Video-only reference role. */
@@ -96,15 +98,16 @@ export const validateMediaGenerationSettings = (raw) => {
         throw new MediaSettingsError("generation settings are invalid");
     return normalizeGenerationSettings(parsed.data, normalizeReference);
 };
-/** Validate path-only selections without inventing a Computer identity. */
+/** Validate selections without granting Computer authority. */
 export const validateMediaGenerationSelection = (raw) => {
     const parsed = mediaGenerationSelectionSchema.safeParse(raw);
     if (!parsed.success)
         throw new MediaSettingsError("generation settings are invalid");
     return normalizeGenerationSettings(parsed.data, (reference) => {
-        const selection = {
-            path: requiredString(reference.path, "reference path"),
-        };
+        const path = requiredString(reference.path, "reference path");
+        const selection = reference.computerId === undefined
+            ? { path }
+            : { path, computerId: reference.computerId };
         if (reference.role === undefined)
             return selection;
         return { ...selection, role: reference.role };
@@ -292,14 +295,13 @@ export const resolveMediaReferences = async (settings, reader) => {
         throw new MediaSettingsError(`${model.id} accepts at most ${String(model.input.maxReferences)} reference images`);
     const resolved = [];
     for (const reference of references) {
-        const image = await reader.read(reference);
+        const image = await reader.read(reference, settings.model);
         if (!imageFormats.has(image.format) ||
             !Number.isSafeInteger(image.width) ||
             !Number.isSafeInteger(image.height) ||
             image.width < 1 ||
             image.height < 1 ||
-            image.width > MAX_REFERENCE_DIMENSION ||
-            image.height > MAX_REFERENCE_DIMENSION ||
+            !referenceImageSizeIsValid(settings.model, image.width, image.height) ||
             !(image.bytes instanceof Uint8Array) ||
             image.bytes.byteLength === 0 ||
             image.bytes.byteLength > MAX_REFERENCE_BYTES)

package/dist/media-binding.d.ts

@@ -26,6 +26,7 @@ export declare const mediaImageBindingInputSchema: z.ZodObject<{
         width: z.ZodNumber;
         height: z.ZodNumber;
         references: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            computerId: z.ZodOptional<z.ZodString>;
             path: z.ZodString;
             role: z.ZodOptional<z.ZodEnum<{
                 readonly first: "first-frame";
@@ -112,6 +113,7 @@ export declare const mediaBindingGenerationSchema: z.ZodDiscriminatedUnion<[z.Zo
         width: z.ZodNumber;
         height: z.ZodNumber;
         references: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            computerId: z.ZodOptional<z.ZodString>;
             path: z.ZodString;
             role: z.ZodOptional<z.ZodEnum<{
                 readonly first: "first-frame";
@@ -173,7 +175,7 @@ export declare const mediaBindingGenerationSchema: z.ZodDiscriminatedUnion<[z.Zo
 }, z.core.$strict>], "kind">;
 /** Parsed generation command consumed by either host. */
 export type MediaBindingGeneration = z.output<typeof mediaBindingGenerationSchema>;
-/** Maintained MEDIA method grammar; guest input carries no principal or Computer. */
+/** Maintained MEDIA grammar; reference selectors carry no Computer authority. */
 export declare const mediaBindingCallSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     operation: z.ZodLiteral<"models">;
     input: z.ZodObject<{}, z.core.$strict>;
@@ -203,6 +205,7 @@ export declare const mediaBindingCallSchema: z.ZodDiscriminatedUnion<[z.ZodObjec
             width: z.ZodNumber;
             height: z.ZodNumber;
             references: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                computerId: z.ZodOptional<z.ZodString>;
                 path: z.ZodString;
                 role: z.ZodOptional<z.ZodEnum<{
                     readonly first: "first-frame";
@@ -286,7 +289,7 @@ export declare function parseMediaBindingCall(raw: z.core.util.JSONType): Readon
 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. */
+    /** Validated references with explicit Computer identities, authorized by the host. */
     settings: MediaGenerationSettings;
     /** Optional image encoding; video output remains MP4. */
     outputFormat?: z.output<typeof mediaRequestedImageFormatSchema>;

package/dist/media-binding.js

@@ -51,7 +51,7 @@ export const mediaBindingGenerationSchema = z.discriminatedUnion("kind", [
     mediaImageBindingInputSchema,
     mediaVideoBindingInputSchema,
 ]);
-/** Maintained MEDIA method grammar; guest input carries no principal or Computer. */
+/** Maintained MEDIA grammar; reference selectors carry no Computer authority. */
 export const mediaBindingCallSchema = z.discriminatedUnion("operation", [
     z.strictObject({
         /** Read the model catalog without dispatching generation. */
@@ -120,7 +120,12 @@ export function mediaBindingRequest(input, computerId) {
     if (references !== undefined)
         attached = {
             ...settings,
-            references: references.map((reference) => ({ ...reference, computerId })),
+            references: references.map((reference) => ({
+                ...reference,
+                computerId: "computerId" in reference
+                    ? (reference.computerId ?? computerId)
+                    : computerId,
+            })),
         };
     const request = {
         path: `${input.libraryPath}/prints-${input.requestId}.${format}`,

package/dist/media-generation.js

@@ -47,10 +47,10 @@ export function runMediaGeneration(host, request, signal) {
             generation: {
                 prepare: async () => {
                     const references = await resolveMediaReferences(settings, {
-                        read: (reference) => {
+                        read: (reference, model) => {
                             if (host.destination.readReference === undefined)
                                 throw new MediaSettingsError("reference images are unavailable");
-                            return host.destination.readReference(reference);
+                            return host.destination.readReference(reference, model);
                         },
                     });
                     const costMilliunits = estimate(settings, references);

package/dist/media-operation.js

@@ -1,10 +1,21 @@
 import { MediaExecutionError, MediaOutputFormatMismatch, MediaSafetyFilterRefusal, } from "./execution-error.js";
 import * as Effect from "effect/Effect";
+import { reportCatchFailure } from "./failure.js";
 import { mediaUnits } from "./gateway-models.js";
 import { getMediaModel } from "./model-catalog.js";
 import { embedProvenance } from "./provenance.js";
 import { z } from "zod";
 import { mediaGenerationSettingsSchema, validateMediaGenerationSettings, } from "./index.js";
+function unchargedFailure(error) {
+    const options = {
+        cause: error.cause,
+        provider: error.provider,
+        customerCharge: "none",
+    };
+    return error instanceof MediaSafetyFilterRefusal
+        ? new MediaSafetyFilterRefusal(options)
+        : new MediaExecutionError(error.stage, options);
+}
 function call(body, stage) {
     return Effect.tryPromise({
         try: () => Promise.resolve(body()),
@@ -49,10 +60,10 @@ export function executeMediaOperation(input) {
         const operationId = admission.operation.operationId;
         const billed = mediaUnits(validateMediaGenerationSettings(mediaGenerationSettingsSchema.strip().parse(input.request)));
         const background = getMediaModel(input.request.model)?.kind === "video";
-        /** Release a held price when nothing will be delivered; best effort, idempotent. */
+        /** Best-effort release; true proves customer settlement, not supplier billing. */
         const settleNothing = () => metering === null
-            ? Effect.void
-            : call(() => metering.settle({ operationId, units: 0 }), "billing").pipe(Effect.ignore);
+            ? Effect.succeed(false)
+            : call(() => metering.settle({ operationId, units: 0 }), "billing").pipe(Effect.match({ onFailure: () => false, onSuccess: () => true }));
         const claim = yield* call(() => input.operation.claim(), "operation");
         if (claim.kind === "succeeded" &&
             claim.operation.image !== null &&
@@ -71,14 +82,16 @@ export function executeMediaOperation(input) {
             }));
         }
         if (claim.kind === "interrupted") {
-            yield* settleNothing();
+            const uncharged = yield* settleNothing();
             const failure = claim.operation.providerFailure;
-            if (failure !== null)
-                return yield* Effect.fail(failure.safetyRefused
+            if (failure !== null) {
+                const error = failure.safetyRefused
                     ? new MediaSafetyFilterRefusal({ provider: failure.provider })
                     : new MediaExecutionError(failure.stage, {
                         provider: failure.provider,
-                    }));
+                    });
+                return yield* Effect.fail(uncharged ? unchargedFailure(error) : error);
+            }
         }
         if (claim.kind !== "claimed" || claim.leaseId === undefined)
             return {
@@ -154,16 +167,22 @@ 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) => {
+                Effect.catch((error) => Effect.gen(function* () {
                     const stage = error.stage;
-                    return stage === "provider" || stage === "normalization"
-                        ? call(() => input.operation.interruptGeneration(leaseId, {
+                    if (stage === "provider" || stage === "normalization") {
+                        const uncharged = yield* call(() => input.operation.interruptGeneration(leaseId, {
                             stage,
                             safetyRefused: error instanceof MediaSafetyFilterRefusal,
                             provider: error.provider,
-                        }), "operation").pipe(Effect.andThen(settleNothing()), Effect.ignore)
-                        : Effect.void;
-                }));
+                        }), "operation").pipe(Effect.andThen(settleNothing()), Effect.catch((cause) => {
+                            reportCatchFailure("media-operation-interrupt", cause);
+                            return Effect.succeed(false);
+                        }));
+                        if (uncharged)
+                            return yield* Effect.fail(unchargedFailure(error));
+                    }
+                    return yield* Effect.fail(error);
+                })));
                 if (generation.kind === "interrupted") {
                     yield* settleNothing();
                     return { kind: "interrupted" };

package/dist/reference-image-size.d.ts

@@ -0,0 +1,10 @@
+/** Maximum long edge for image-model references, in pixels. */
+export declare const MAX_REFERENCE_DIMENSION = 512;
+/** Aspect-preserving native resize; only video references may be enlarged. */
+export declare function referenceImageTransform(modelId: string, width: number, height: number): {
+    width: number;
+    height: number;
+    fit: "contain" | "scale-down";
+};
+/** Validate actual decoded output, rather than trusting requested resize dimensions. */
+export declare function referenceImageSizeIsValid(modelId: string, width: number, height: number): boolean;

package/dist/reference-image-size.js

@@ -0,0 +1,37 @@
+import { getMediaModel, MediaSettingsError } from "./model-catalog.js";
+/** Maximum long edge for image-model references, in pixels. */
+export const MAX_REFERENCE_DIMENSION = 512;
+const MIN_VIDEO_REFERENCE_DIMENSION = 320;
+/** One owner for both native fitting and the resolved-reference boundary. */
+function sizing(modelId) {
+    const model = getMediaModel(modelId);
+    if (model === undefined)
+        throw new MediaSettingsError("unknown Media model");
+    return model.video === null
+        ? { edge: "long", dimension: MAX_REFERENCE_DIMENSION }
+        : { edge: "short", dimension: MIN_VIDEO_REFERENCE_DIMENSION };
+}
+/** Aspect-preserving native resize; only video references may be enlarged. */
+export function referenceImageTransform(modelId, width, height) {
+    const rule = sizing(modelId);
+    const edge = rule.edge === "short" ? Math.min(width, height) : Math.max(width, height);
+    const ratio = rule.edge === "short"
+        ? rule.dimension / edge
+        : Math.min(1, rule.dimension / edge);
+    // A video's bounding box must not round its long edge down and squeeze
+    // the actual decoded short edge below the provider minimum.
+    const round = rule.edge === "short" ? Math.ceil : Math.round;
+    return {
+        width: Math.max(1, round(width * ratio)),
+        height: Math.max(1, round(height * ratio)),
+        // Small video frames must grow; image references must never grow.
+        fit: rule.edge === "short" ? "contain" : "scale-down",
+    };
+}
+/** Validate actual decoded output, rather than trusting requested resize dimensions. */
+export function referenceImageSizeIsValid(modelId, width, height) {
+    const rule = sizing(modelId);
+    return rule.edge === "short"
+        ? Math.min(width, height) >= rule.dimension
+        : Math.max(width, height) <= rule.dimension;
+}

package/dist/server.d.ts

@@ -1,3 +1,4 @@
+export { estimateMediaModel } from "./cloudflare/provider.js";
 export { mediaPendingSchema, mediaBindingCallSchema, mediaBindingGenerationSchema, mediaImageBindingInputSchema, mediaVideoBindingInputSchema, parseMediaBindingCall, mediaBindingRequest, readMediaBindingReply, type MediaBindingCall, type MediaBindingGeneration, type MediaBindingRequest, } from "./media-binding.js";
 import { Hono } from "hono";
 import { z } from "zod";
@@ -90,8 +91,8 @@ export type MediaServiceHost = Readonly<{
         authorize: (path: string) => Promise<void>;
         /** Save exact generated bytes to the admitted destination. */
         write: (path: string, bytes: Uint8Array) => Promise<void>;
-        /** Authorize and decode one selected reference image. */
-        readReference?: (reference: MediaReference) => Promise<MediaReferenceBytes>;
+        /** Authorize and fit one selected reference image for the catalog model. */
+        readReference?: (reference: MediaReference, model: string) => Promise<MediaReferenceBytes>;
     }>;
     /** Translate host authority failures; undefined uses the shared Media failure. */
     onFailure?: (error: MediaExecutionError) => Response | undefined;