@fungi.computer/darkroom 0.0.0-stage → 0.0.1

package/dist/media-binding.d.ts

@@ -0,0 +1,291 @@
+import * as z from "zod";
+import * as Schema from "effect/Schema";
+import { mediaRequestedImageFormatSchema, type MediaGenerationSettings } from "./index.js";
+export { mediaResultSchema } from "./media-operation-contract.js";
+/** Image settings and path references crossing a scoped MEDIA binding. */
+export declare const mediaImageBindingInputSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"image">;
+    requestId: z.ZodString;
+    libraryPath: z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>;
+    settings: z.ZodObject<{
+        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";
+        }>>;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+        references: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            role: z.ZodOptional<z.ZodEnum<{
+                readonly first: "first-frame";
+                readonly last: "last-frame";
+                readonly reference: "reference";
+            }>>;
+        }, z.core.$strict>>>;
+        model: z.ZodString;
+        prompt: z.ZodString;
+        generateAudio: z.ZodOptional<z.ZodBoolean>;
+        steps: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+    outputFormat: z.ZodOptional<z.ZodEnum<{
+        readonly png: "png";
+        readonly jpeg: "jpeg";
+        readonly webp: "webp";
+    }>>;
+}, z.core.$strict>;
+/** Video settings and path references crossing the same scoped binding. */
+export declare const mediaVideoBindingInputSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"video">;
+    requestId: z.ZodString;
+    libraryPath: z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>;
+    settings: z.ZodObject<{
+        model: z.ZodEnum<{
+            readonly seedance: "bytedance/seedance-2.0";
+            readonly seedanceFast: "bytedance/seedance-2.0-fast";
+            readonly seedanceMini: "bytedance/seedance-2.0-mini";
+            readonly veo: "google/veo-3.1";
+            readonly veoFast: "google/veo-3.1-fast";
+            readonly minimaxH3Max: "minimax/h3-max";
+        }>;
+        prompt: z.ZodString;
+        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";
+        }>>;
+        durationSeconds: z.ZodOptional<z.ZodNumber>;
+        generateAudio: z.ZodOptional<z.ZodBoolean>;
+        references: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            role: z.ZodEnum<{
+                readonly first: "first-frame";
+                readonly last: "last-frame";
+                readonly reference: "reference";
+            }>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+/** One generation identity, including the App-owned folder captured for replay. */
+export declare const mediaBindingGenerationSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"image">;
+    requestId: z.ZodString;
+    libraryPath: z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>;
+    settings: z.ZodObject<{
+        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";
+        }>>;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+        references: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            role: z.ZodOptional<z.ZodEnum<{
+                readonly first: "first-frame";
+                readonly last: "last-frame";
+                readonly reference: "reference";
+            }>>;
+        }, z.core.$strict>>>;
+        model: z.ZodString;
+        prompt: z.ZodString;
+        generateAudio: z.ZodOptional<z.ZodBoolean>;
+        steps: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+    outputFormat: z.ZodOptional<z.ZodEnum<{
+        readonly png: "png";
+        readonly jpeg: "jpeg";
+        readonly webp: "webp";
+    }>>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"video">;
+    requestId: z.ZodString;
+    libraryPath: z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>;
+    settings: z.ZodObject<{
+        model: z.ZodEnum<{
+            readonly seedance: "bytedance/seedance-2.0";
+            readonly seedanceFast: "bytedance/seedance-2.0-fast";
+            readonly seedanceMini: "bytedance/seedance-2.0-mini";
+            readonly veo: "google/veo-3.1";
+            readonly veoFast: "google/veo-3.1-fast";
+            readonly minimaxH3Max: "minimax/h3-max";
+        }>;
+        prompt: z.ZodString;
+        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";
+        }>>;
+        durationSeconds: z.ZodOptional<z.ZodNumber>;
+        generateAudio: z.ZodOptional<z.ZodBoolean>;
+        references: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            role: z.ZodEnum<{
+                readonly first: "first-frame";
+                readonly last: "last-frame";
+                readonly reference: "reference";
+            }>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>;
+}, z.core.$strict>], "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. */
+export declare const mediaBindingCallSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    operation: z.ZodLiteral<"models">;
+    input: z.ZodObject<{}, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    operation: z.ZodLiteral<"generate">;
+    input: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"image">;
+        requestId: z.ZodString;
+        libraryPath: z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>;
+        settings: z.ZodObject<{
+            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";
+            }>>;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+            references: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                path: z.ZodString;
+                role: z.ZodOptional<z.ZodEnum<{
+                    readonly first: "first-frame";
+                    readonly last: "last-frame";
+                    readonly reference: "reference";
+                }>>;
+            }, z.core.$strict>>>;
+            model: z.ZodString;
+            prompt: z.ZodString;
+            generateAudio: z.ZodOptional<z.ZodBoolean>;
+            steps: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>;
+        outputFormat: z.ZodOptional<z.ZodEnum<{
+            readonly png: "png";
+            readonly jpeg: "jpeg";
+            readonly webp: "webp";
+        }>>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"video">;
+        requestId: z.ZodString;
+        libraryPath: z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>;
+        settings: z.ZodObject<{
+            model: z.ZodEnum<{
+                readonly seedance: "bytedance/seedance-2.0";
+                readonly seedanceFast: "bytedance/seedance-2.0-fast";
+                readonly seedanceMini: "bytedance/seedance-2.0-mini";
+                readonly veo: "google/veo-3.1";
+                readonly veoFast: "google/veo-3.1-fast";
+                readonly minimaxH3Max: "minimax/h3-max";
+            }>;
+            prompt: z.ZodString;
+            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";
+            }>>;
+            durationSeconds: z.ZodOptional<z.ZodNumber>;
+            generateAudio: z.ZodOptional<z.ZodBoolean>;
+            references: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                path: z.ZodString;
+                role: z.ZodEnum<{
+                    readonly first: "first-frame";
+                    readonly last: "last-frame";
+                    readonly reference: "reference";
+                }>;
+            }, z.core.$strict>>>;
+        }, z.core.$strict>;
+    }, z.core.$strict>], "kind">;
+}, z.core.$strict>], "operation">;
+/** Parsed call consumed by host admission and transport. */
+export type MediaBindingCall = z.output<typeof mediaBindingCallSchema>;
+/** Background-generation reply emitted by the durable service. */
+export declare const mediaPendingSchema: z.ZodObject<{
+    status: z.ZodLiteral<"pending">;
+    retryAfterSeconds: z.ZodNumber;
+}, z.core.$strict>;
+/** Parsing and model refusal stay shared; authorization remains host-owned. */
+export declare function parseMediaBindingCall(raw: Schema.Json): Readonly<{
+    kind: "parsed";
+    call: MediaBindingCall;
+}> | Readonly<{
+    kind: "refused";
+    result: z.core.util.JSONType;
+}>;
+/** Relative service input after the host attaches its trusted Computer to references. */
+export type MediaBindingRequest = Readonly<{
+    path: string;
+    settings: MediaGenerationSettings;
+    outputFormat?: z.output<typeof mediaRequestedImageFormatSchema>;
+}>;
+/** Choose the same fixed filename on both hosts without a recursive App lookup. */
+export declare function mediaBindingRequest(input: MediaBindingGeneration, computerId: string): MediaBindingRequest;
+/** Decode bounded service replies once for both MEDIA host bindings. */
+export declare function readMediaBindingReply(input: MediaBindingCall, computerId: string, response: Response): Promise<z.core.util.JSONType>;

package/dist/media-binding.js

@@ -0,0 +1,146 @@
+import * as z from "zod";
+import * as Schema from "effect/Schema";
+import { pending } from "@fungi.computer/agar/backend-definition";
+import { mediaRequestIdSchema } from "@fungi.computer/agar/media-request-id";
+import { mediaLibraryPathSchema } from "@fungi.computer/agar/media-library";
+import { getMediaModel, mediaGenerationSelectionSchema, mediaRequestedImageFormatSchema, mediaVideoSelectionSchema, validateMediaGenerationSelection, validateMediaVideoSelection, MediaSettingsError, readResponseBytes, } from "./index.js";
+export { mediaResultSchema } from "./media-operation-contract.js";
+import { mediaFailureSchema } from "./browser-failure.js";
+import { appMediaBrokerFailureSchema, appMediaGenerationResultSchema, mediaModelsSchema, } from "./app-media-contracts.js";
+/** The App owns its folder; the host owns Computer identity and the output filename. */
+const mediaBindingLibraryPathSchema = z
+    .string()
+    .refine(Schema.is(mediaLibraryPathSchema), "Select an absolute library folder");
+/** Image settings and path references crossing a scoped MEDIA binding. */
+export const mediaImageBindingInputSchema = z.strictObject({
+    kind: z.literal("image"),
+    requestId: mediaRequestIdSchema,
+    libraryPath: mediaBindingLibraryPathSchema,
+    settings: mediaGenerationSelectionSchema
+        .omit({ durationSeconds: true })
+        .extend({
+        steps: z
+            .number()
+            .int()
+            .nonnegative()
+            .max(Number.MAX_SAFE_INTEGER)
+            .optional(),
+    })
+        .refine((settings) => getMediaModel(settings.model)?.kind === "image", "Select an image model from listModels"),
+    outputFormat: mediaRequestedImageFormatSchema.optional(),
+});
+/** Video settings and path references crossing the same scoped binding. */
+export const mediaVideoBindingInputSchema = z.strictObject({
+    kind: z.literal("video"),
+    requestId: mediaRequestIdSchema,
+    libraryPath: mediaBindingLibraryPathSchema,
+    settings: mediaVideoSelectionSchema,
+});
+/** One generation identity, including the App-owned folder captured for replay. */
+export const mediaBindingGenerationSchema = z.discriminatedUnion("kind", [
+    mediaImageBindingInputSchema,
+    mediaVideoBindingInputSchema,
+]);
+/** Maintained MEDIA method grammar; guest input carries no principal or Computer. */
+export const mediaBindingCallSchema = z.discriminatedUnion("operation", [
+    z.strictObject({ operation: z.literal("models"), input: z.strictObject({}) }),
+    z.strictObject({
+        operation: z.literal("generate"),
+        input: mediaBindingGenerationSchema,
+    }),
+]);
+/** Background-generation reply emitted by the durable service. */
+export const mediaPendingSchema = z.strictObject({
+    status: z.literal("pending"),
+    retryAfterSeconds: z.number().int().positive(),
+});
+/** Parsing and model refusal stay shared; authorization remains host-owned. */
+export function parseMediaBindingCall(raw) {
+    if (new TextEncoder().encode(JSON.stringify(raw)).byteLength > 64 * 1024)
+        return { kind: "refused", result: { error: "too_large" } };
+    const parsed = mediaBindingCallSchema.safeParse(raw);
+    if (!parsed.success)
+        return { kind: "refused", result: { error: "invalid" } };
+    if (parsed.data.operation === "generate") {
+        try {
+            if (parsed.data.input.kind === "image")
+                validateMediaGenerationSelection(parsed.data.input.settings);
+            else
+                validateMediaVideoSelection(parsed.data.input.settings);
+        }
+        catch (cause) {
+            if (!(cause instanceof MediaSettingsError))
+                throw cause;
+            return {
+                kind: "refused",
+                result: {
+                    error: "INVALID_ARGUMENT",
+                    message: cause.message,
+                    stage: "settings",
+                    retryable: false,
+                },
+            };
+        }
+    }
+    return { kind: "parsed", call: parsed.data };
+}
+/** Choose the same fixed filename on both hosts without a recursive App lookup. */
+export function mediaBindingRequest(input, computerId) {
+    const selected = input.kind === "image"
+        ? validateMediaGenerationSelection(input.settings)
+        : validateMediaVideoSelection(input.settings);
+    const { references, ...settings } = selected;
+    const model = getMediaModel(input.settings.model);
+    const format = input.kind === "video"
+        ? "mp4"
+        : (input.outputFormat ??
+            (model?.outputFormats.includes("png")
+                ? "png"
+                : (model?.outputFormats[0] ?? "png")));
+    let attached = settings;
+    if (references !== undefined)
+        attached = {
+            ...settings,
+            references: references.map((reference) => ({ ...reference, computerId })),
+        };
+    const request = {
+        path: `${input.libraryPath}/prints-${input.requestId}.${format}`,
+        settings: attached,
+    };
+    if (input.kind === "image" && input.outputFormat !== undefined)
+        return { ...request, outputFormat: input.outputFormat };
+    return request;
+}
+/** Decode bounded service replies once for both MEDIA host bindings. */
+export async function readMediaBindingReply(input, computerId, response) {
+    const bytes = await readResponseBytes(new Response(response.body, { headers: response.headers }), 240 * 1024);
+    const value = JSON.parse(new TextDecoder().decode(bytes));
+    if (!response.ok) {
+        const failure = mediaFailureSchema.safeParse(value);
+        if (!failure.success)
+            return { error: "unavailable" };
+        return z.json().parse(appMediaBrokerFailureSchema.parse({
+            error: failure.data.code,
+            message: failure.data.error,
+            stage: failure.data.stage,
+            retryable: failure.data.retryable,
+        }));
+    }
+    if (input.operation === "models")
+        return z.json().parse(mediaModelsSchema.parse(value));
+    if (response.status === 202) {
+        if (input.input.kind === "image")
+            return { error: "unavailable" };
+        return z
+            .json()
+            .parse(pending(mediaPendingSchema.parse(value).retryAfterSeconds * 1000));
+    }
+    const result = appMediaGenerationResultSchema.parse(value);
+    if (result.destination.computerId !== computerId ||
+        (input.input.kind === "video"
+            ? result.format !== "mp4"
+            : input.input.outputFormat !== undefined &&
+                result.format !== input.input.outputFormat))
+        return { error: "unavailable" };
+    return z.json().parse(result);
+}

package/dist/media-generation.d.ts

@@ -0,0 +1,10 @@
+import * as Effect from "effect/Effect";
+import { MediaSettingsError } from "./index.js";
+import { MediaExecutionError } from "./execution-error.js";
+import type { MediaServiceHost, MediaGenerationRequest, MediaGenerationOutcome } from "./server.js";
+/**
+ * Validate, admit, dispatch and save one generation against `host`. Shared by
+ * the `/generate` Hono route and the Agent image tool so both run the exact
+ * same admission, billing and destination-write sequence.
+ */
+export declare function runMediaGeneration(host: MediaServiceHost, request: MediaGenerationRequest, signal?: AbortSignal): Effect.Effect<MediaGenerationOutcome, MediaExecutionError | MediaSettingsError>;

package/dist/media-generation.js

@@ -0,0 +1,110 @@
+import * as Effect from "effect/Effect";
+import { getMediaModel, validateMediaGenerationSettings, resolveMediaReferences, MediaSettingsError, } from "./index.js";
+import { estimate } from "./cloudflare/provider.js";
+import { executeMediaOperation } from "./media-operation.js";
+import { MediaExecutionError } from "./execution-error.js";
+import { mediaResultSchema } from "./media-operation-contract.js";
+/**
+ * Validate, admit, dispatch and save one generation against `host`. Shared by
+ * the `/generate` Hono route and the Agent image tool so both run the exact
+ * same admission, billing and destination-write sequence.
+ */
+export function runMediaGeneration(host, request, signal) {
+    return Effect.gen(function* () {
+        const settings = yield* Effect.try({
+            try: () => validateMediaGenerationSettings(request.settings),
+            catch: () => new MediaSettingsError("invalid generation settings"),
+        });
+        if (request.outputFormat !== undefined &&
+            !getMediaModel(settings.model)?.outputFormats.includes(request.outputFormat))
+            return yield* Effect.fail(new MediaSettingsError("model cannot produce the requested image format"));
+        const path = request.path;
+        const beforeAdmit = host.beforeAdmit;
+        if (beforeAdmit !== undefined)
+            yield* Effect.tryPromise({
+                try: () => beforeAdmit(request.requestId),
+                catch: (cause) => new MediaExecutionError("generation-authorization", { cause }),
+            });
+        const execution = {
+            operation: host.operations.getByName(`media:${request.requestId}`),
+            actorUserId: host.scope.actorId,
+            coordinates: {
+                namespace: host.scope.namespace,
+                owner: host.scope.owner,
+            },
+            requestId: request.requestId,
+            request: {
+                ...settings,
+                computerId: host.scope.destinationId,
+                path,
+                outputFormat: request.outputFormat,
+            },
+            metering: host.metering,
+            destination: {
+                authorize: () => host.destination.authorize(path),
+                write: (bytes) => host.destination.write(path, bytes),
+            },
+            generation: {
+                prepare: async () => {
+                    const references = await resolveMediaReferences(settings, {
+                        read: (reference) => {
+                            if (host.destination.readReference === undefined)
+                                throw new MediaSettingsError("reference images are unavailable");
+                            return host.destination.readReference(reference);
+                        },
+                    });
+                    const costMilliunits = estimate(settings, references);
+                    // Reference preparation may suspend. This final authority check is
+                    // the new-generation admission cutoff, before durable dispatch.
+                    try {
+                        await host.authorizeGeneration?.();
+                    }
+                    catch (cause) {
+                        throw new MediaExecutionError("generation-authorization", {
+                            cause,
+                        });
+                    }
+                    return {
+                        costMilliunits,
+                        references,
+                        run: (runSignal) => host.provider(settings, references, runSignal, request.outputFormat),
+                    };
+                },
+            },
+        };
+        if (signal !== undefined)
+            execution.signal = signal;
+        const outcome = yield* executeMediaOperation(execution);
+        if (outcome.kind === "conflict")
+            return { kind: "conflict" };
+        if (outcome.kind === "accepted" ||
+            (outcome.kind === "pending" &&
+                getMediaModel(settings.model)?.kind === "video"))
+            // A video generation runs in the background; retry this request id.
+            return {
+                kind: "pending",
+                background: true,
+                retryAfterSeconds: 5,
+            };
+        if (outcome.kind === "pending")
+            return {
+                kind: "pending",
+                background: false,
+                retryAfterSeconds: 5,
+            };
+        if (outcome.kind === "interrupted")
+            return { kind: "interrupted" };
+        if (outcome.kind !== "succeeded")
+            return { kind: "unavailable" };
+        return {
+            kind: "succeeded",
+            bytes: outcome.bytes,
+            costMilliunits: outcome.costMilliunits,
+            path,
+            format: mediaResultSchema.shape.format.parse(outcome.format),
+            height: settings.height,
+            model: settings.model,
+            width: settings.width,
+        };
+    });
+}

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

@@ -0,0 +1,104 @@
+import * as z from "zod";
+import type { MediaOperationOwner, MediaOperationCoordinates, MediaOperationRequest } from "./media-operation-owner.js";
+import type { MediaUnits } from "./gateway-models.js";
+import type { MediaReferenceBytes } from "./index.js";
+/**
+ * The host's billing owner for Media. Every call is keyed by the durable
+ * operation id and must be idempotent: a lost acknowledgement is retried with
+ * the same id and must never admit, hold, or charge twice.
+ */
+export type MediaMetering = Readonly<{
+    /**
+     * Admit one generation and hold its price before any provider dispatch.
+     * Throws {@link MediaBillingRefusal} for a definitive refusal. Returns the
+     * customer price in milliunits (1 cent = 1,000 milliunits).
+     */
+    admit: (input: Readonly<{
+        /** Durable operation name. */
+        operationId: string;
+        /** Provider catalog model identifier. */
+        model: string;
+        /** Billing unit and count: one image, or seconds of video. */
+        unit: MediaUnits["unit"];
+        /** Number of admitted or delivered units. */
+        units: number;
+        /** Provider cost of all units together. */
+        providerCostMilliunits: number;
+    }>) => Promise<Readonly<{
+        /** Host-admitted customer price. */
+        priceMilliunits: number;
+    }>>;
+    /** Settle delivered units: all admitted units once saved, 0 when nothing was delivered. */
+    settle: (input: Readonly<{
+        /** Durable operation name. */
+        operationId: string;
+        /** Number of admitted or delivered units. */
+        units: number;
+    }>) => Promise<void>;
+}>;
+/** Local or RPC methods consumed by a replay-safe generation. */
+export type MediaOperation = {
+    [Method in "admit" | "claim" | "dispatchInBackground" | "interruptGeneration" | "readGenerated" | "recordEstimate" | "recordGenerated" | "recordSucceeded" | "recordWritten" | "recordWrittenWithoutSettlement" | "releaseEstimate" | "releaseWrite"]: (...input: Parameters<MediaOperationOwner[Method]>) => ReturnType<MediaOperationOwner[Method]> | Promise<Awaited<ReturnType<MediaOperationOwner[Method]>>>;
+};
+/** Admitted identity, durable operation and host effects for one generation. */
+export type MediaExecution = Readonly<{
+    /** Durable owner methods for this generation. */
+    operation: MediaOperation;
+    /** Host-admitted actor identifier. */
+    actorUserId: string;
+    /** Host namespace and owner identity. */
+    coordinates: MediaOperationCoordinates;
+    /** Stable caller request identity reused on retries. */
+    requestId: string;
+    /** Captured generation and fixed destination. */
+    request: MediaOperationRequest;
+    /** The billing owner, or `unmetered` when the host pays its own provider. */
+    metering: MediaMetering | "unmetered";
+    /** Optional cancellation signal. */
+    signal?: AbortSignal;
+    /** Host-owned destination authorization and writing. */
+    destination: Readonly<{
+        /** Check host permission before writing or dispatching generation. */
+        authorize: () => Promise<void>;
+        /** Save exact generated bytes to the admitted destination. */
+        write: (bytes: Uint8Array) => Promise<void>;
+    }>;
+    /** Reference preparation and provider dispatch effects. */
+    generation: Readonly<{
+        /** Resolve references and price before provider dispatch. */
+        prepare: () => Promise<Readonly<{
+            /** Estimated provider cost in milliunits, where 1 cent is 1,000 milliunits. */
+            costMilliunits: number;
+            /** Host-authorized reference images. */
+            references: readonly MediaReferenceBytes[];
+            /** Dispatch one provider call with the prepared inputs. */
+            run: (signal?: AbortSignal) => Promise<Readonly<{
+                /** Generated output bytes. */
+                bytes: Uint8Array;
+                /** Actual output encoding. */
+                format: string;
+            }>>;
+        }>>;
+    }>;
+}>;
+/** Decode a completed generation, destination path and estimated or settled price. */
+export declare const mediaResultSchema: z.ZodObject<{
+    bytes: z.ZodNumber;
+    costMilliunits: z.ZodNumber;
+    path: z.ZodString;
+    format: z.ZodEnum<{
+        /** PNG image encoding. */
+        readonly png: "png";
+        /** JPEG image encoding. */
+        readonly jpeg: "jpeg";
+        /** GIF image encoding. */
+        readonly gif: "gif";
+        /** WebP image encoding. */
+        readonly webp: "webp";
+        /** MP4 video encoding. */
+        readonly mp4: "mp4";
+    }>;
+    height: z.ZodNumber;
+    model: z.ZodString;
+    width: z.ZodNumber;
+}, z.core.$strict>;