@fungi.computer/darkroom 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,81 @@
+/** SQL rows stay untrusted until the owner decodes their stored representation. */
+export type MediaOperationStorage = {
+    /** Native synchronous SQL interface. */
+    sql: {
+        /** Execute a native SQL statement with positional bindings. */
+        exec(query: string, ...bindings: (string | number | null)[]): {
+            /** Read the native SQL rows as objects for boundary decoding. */
+            toArray(): readonly object[];
+        };
+    };
+    /** Run one atomic synchronous local mutation. */
+    transactionSync<T>(body: () => T): T;
+    /** Read the durable erasure marker. */
+    isErased(): Promise<boolean>;
+    /** Persist the durable erasure marker. */
+    markErased(): Promise<void>;
+    /** List local key-value storage keys for erasure readback. */
+    listKeys(): Promise<readonly string[]>;
+    /** Remove any scheduled background alarm. */
+    deleteAlarm(): Promise<void>;
+    /** Remove local SQL and key-value storage. */
+    deleteAll(): Promise<void>;
+    /** Read the current background alarm, or null. */
+    getAlarm(): Promise<number | null>;
+    /** Schedule background generation at the given timestamp. */
+    setAlarm(timestamp: number): Promise<void>;
+};
+/** The identity, serialization and storage owned by one media operation. */
+export type MediaOperationContext = {
+    /** Durable operation identity selected by the host. */
+    id: {
+        /** Stable error name or durable object name. */
+        name: string | undefined;
+    };
+    /** Host-owned SQL, key-value storage and alarms. */
+    storage: MediaOperationStorage;
+    /** Serialize asynchronous owner initialization with requests. */
+    blockConcurrencyWhile<T>(body: () => Promise<T>): Promise<T>;
+};
+/** Object metadata consumed by retention and recovery; mirrors the native R2 fields used here. */
+export type MediaOperationObject = Readonly<{
+    /** Immutable output key. */
+    key: string;
+    /** Object version captured when its exact bytes were written. */
+    version: string;
+    /** Stored byte length. */
+    size: number;
+    /** Actual retained MIME type. */
+    httpMetadata?: Readonly<{
+        /** MIME type of the retained output. */ contentType?: string;
+    }>;
+}>;
+/** Exact object operations needed for immutable media outputs and references. */
+export type MediaOperationBucket = {
+    /** Conditionally retain immutable provider bytes or background reference bytes. */
+    put(key: string, bytes: Uint8Array, options?: Readonly<{
+        /** Native R2 conditional write, used once for an immutable output. */
+        onlyIf?: Readonly<{
+            /** Refuse an existing output key. */ etagDoesNotMatch: string;
+        }>;
+        /** MIME type for exact-output recovery. */
+        httpMetadata?: Readonly<{
+            /** MIME type of the retained output. */ contentType: string;
+        }>;
+        /** Decoded reference format and dimensions for background generation. */
+        customMetadata?: Readonly<Record<string, string>>;
+    }>): Promise<Readonly<{
+        /** Stored immutable object version. */ version: string;
+    }> | null>;
+    /** Read immutable object metadata without loading bytes. */
+    head(key: string): Promise<MediaOperationObject | null>;
+    /** Read retained object bytes and metadata. */
+    get(key: string): Promise<(Omit<MediaOperationObject, "httpMetadata"> & Readonly<{
+        /** Stored background reference metadata. */
+        customMetadata?: Readonly<Record<string, string>>;
+        /** Read the exact retained object bytes. */
+        arrayBuffer: () => Promise<ArrayBuffer>;
+    }>) | null>;
+    /** Delete the owner-selected object key. */
+    delete(key: string): Promise<void>;
+};

package/dist/media-operation-storage.js

@@ -0,0 +1 @@
+export {};

package/dist/media-operation.d.ts

@@ -0,0 +1,33 @@
+import { MediaExecutionError } from "./execution-error.js";
+import * as Effect from "effect/Effect";
+import type { MediaExecution } from "./media-operation-contract.js";
+/**
+ * Own one replay-safe Media execution. Network effects stay outside storage
+ * transactions; the durable operation hides its transition sequence.
+ */
+export declare function executeMediaOperation(input: MediaExecution): Effect.Effect<{
+    kind: "conflict";
+    bytes?: never;
+    format?: never;
+    costMilliunits?: never;
+} | {
+    kind: "succeeded";
+    bytes: number;
+    format: string;
+    costMilliunits: number;
+} | {
+    readonly kind: "pending" | "unavailable";
+    bytes?: never;
+    format?: never;
+    costMilliunits?: never;
+} | {
+    kind: "accepted";
+    bytes?: never;
+    format?: never;
+    costMilliunits?: never;
+} | {
+    kind: "interrupted";
+    bytes?: never;
+    format?: never;
+    costMilliunits?: never;
+}, MediaExecutionError, never>;

package/dist/media-operation.js

@@ -0,0 +1,230 @@
+import { MediaExecutionError, MediaOutputFormatMismatch, MediaSafetyFilterRefusal, } from "./execution-error.js";
+import * as Effect from "effect/Effect";
+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 call(body, stage) {
+    return Effect.tryPromise({
+        try: () => Promise.resolve(body()),
+        catch: (cause) => cause instanceof MediaExecutionError
+            ? cause
+            : new MediaExecutionError(stage, {
+                cause: cause instanceof Error ? cause : new Error(String(cause)),
+            }),
+    });
+}
+function untilAborted(signal, body) {
+    if (signal === undefined)
+        return body();
+    if (signal.aborted)
+        return Promise.reject(new Error("Media generation was cancelled", { cause: signal.reason }));
+    return new Promise((resolve, reject) => {
+        const abort = () => {
+            reject(new Error("Media generation was cancelled", { cause: signal.reason }));
+        };
+        signal.addEventListener("abort", abort, { once: true });
+        Promise.resolve()
+            .then(body)
+            .then(resolve, reject)
+            .finally(() => {
+            signal.removeEventListener("abort", abort);
+        });
+        if (signal.aborted)
+            abort();
+    });
+}
+/**
+ * Own one replay-safe Media execution. Network effects stay outside storage
+ * transactions; the durable operation hides its transition sequence.
+ */
+export function executeMediaOperation(input) {
+    return Effect.gen(function* () {
+        const admission = yield* call(() => input.operation.admit(input.actorUserId, input.coordinates, input.requestId, input.request), "operation");
+        if (admission.kind === "conflict")
+            return { kind: "conflict" };
+        yield* call(input.destination.authorize, "destination-authorization");
+        const metering = input.metering === "unmetered" ? null : input.metering;
+        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. */
+        const settleNothing = () => metering === null
+            ? Effect.void
+            : call(() => metering.settle({ operationId, units: 0 }), "billing").pipe(Effect.ignore);
+        const claim = yield* call(() => input.operation.claim(), "operation");
+        if (claim.kind === "succeeded" &&
+            claim.operation.image !== null &&
+            claim.operation.estimatedCostMilliunits !== null)
+            return {
+                kind: "succeeded",
+                bytes: claim.operation.image.bytes,
+                format: claim.operation.image.format,
+                costMilliunits: claim.operation.estimatedCostMilliunits,
+            };
+        if (claim.kind === "interrupted" && claim.operation.spentFailure !== null) {
+            if (metering !== null)
+                yield* call(() => metering.settle({ operationId, units: billed.units }), "billing");
+            return yield* Effect.fail(new MediaExecutionError("artifact", {
+                cause: new MediaOutputFormatMismatch(),
+            }));
+        }
+        if (claim.kind === "interrupted") {
+            yield* settleNothing();
+            if (claim.operation.providerRefusal === "safety_filter_refused")
+                return yield* Effect.fail(new MediaSafetyFilterRefusal());
+        }
+        if (claim.kind !== "claimed" || claim.leaseId === undefined)
+            return {
+                kind: claim.kind === "pending" ? "pending" : "unavailable",
+            };
+        const leaseId = claim.leaseId;
+        let costMilliunits;
+        let image;
+        if (claim.operation.state === "charging" &&
+            claim.operation.image !== null &&
+            claim.operation.estimatedCostMilliunits !== null) {
+            // The save committed; only the idempotent settlement remains.
+            image = claim.operation.image;
+            costMilliunits = claim.operation.estimatedCostMilliunits;
+        }
+        else {
+            let output;
+            if (claim.operation.state === "writing" &&
+                claim.operation.image !== null &&
+                claim.operation.estimatedCostMilliunits !== null) {
+                output = {
+                    bytes: yield* call(() => input.operation.readGenerated(leaseId), "artifact"),
+                    format: claim.operation.image.format,
+                };
+                costMilliunits = claim.operation.estimatedCostMilliunits;
+            }
+            else {
+                // A retained save never rereads reference files or recomputes its quote.
+                const releaseEstimate = () => call(() => input.operation.releaseEstimate(leaseId), "operation").pipe(Effect.ignore);
+                const prepared = yield* call(input.generation.prepare, "estimate").pipe(Effect.tapError(releaseEstimate));
+                // Billing admission is the last gate before durable dispatch. A refusal
+                // returns the request to admitted, so the same request id can retry.
+                costMilliunits =
+                    metering === null
+                        ? prepared.costMilliunits
+                        : (yield* call(() => metering.admit({
+                            operationId,
+                            model: input.request.model,
+                            unit: billed.unit,
+                            units: billed.units,
+                            providerCostMilliunits: prepared.costMilliunits,
+                        }), "billing").pipe(Effect.tapError(releaseEstimate))).priceMilliunits;
+                yield* call(() => input.operation.recordEstimate(leaseId, costMilliunits), "estimate");
+                if (background) {
+                    // Video outlives one request: the owner's alarm generates, and a
+                    // retry of this request id saves and charges the retained output.
+                    yield* call(() => input.operation.dispatchInBackground(leaseId, prepared.references), "operation").pipe(Effect.tapError(() => call(() => input.operation.interruptGeneration(leaseId), "operation").pipe(Effect.andThen(settleNothing()), Effect.ignore)));
+                    return { kind: "accepted" };
+                }
+                const generation = yield* call(async () => {
+                    let output;
+                    try {
+                        output = await untilAborted(input.signal, () => prepared.run(input.signal));
+                    }
+                    catch (cause) {
+                        if (!input.signal?.aborted)
+                            throw cause;
+                        await input.operation.interruptGeneration(leaseId);
+                        return {
+                            kind: "interrupted",
+                        };
+                    }
+                    if (input.signal?.aborted) {
+                        await input.operation.interruptGeneration(leaseId);
+                        return {
+                            kind: "interrupted",
+                        };
+                    }
+                    return {
+                        kind: "generated",
+                        output,
+                    };
+                }, "provider").pipe(
+                // A provider failure delivered nothing and wrote no output: end the
+                // request now and release its hold rather than leave it unresolved.
+                Effect.tapError((error) => error.stage === "provider"
+                    ? call(() => input.operation.interruptGeneration(leaseId, error instanceof MediaSafetyFilterRefusal
+                        ? "safety_filter_refused"
+                        : undefined), "operation").pipe(Effect.andThen(settleNothing()), Effect.ignore)
+                    : Effect.void));
+                if (generation.kind === "interrupted") {
+                    yield* settleNothing();
+                    return { kind: "interrupted" };
+                }
+                output = generation.output;
+                const recorded = yield* call(() => input.operation.recordGenerated(leaseId, output.bytes, output.format), "artifact");
+                if ("kind" in recorded) {
+                    // The provider ran. The owner recorded a durable spent failure before
+                    // this idempotent charge, so replay cannot refund or redispatch it.
+                    if (metering !== null)
+                        yield* call(() => metering.settle({ operationId, units: billed.units }), "billing");
+                    return yield* Effect.fail(new MediaExecutionError("artifact", {
+                        cause: new MediaOutputFormatMismatch(),
+                    }));
+                }
+            }
+            // Embedded fresh from the recorded (unembedded) bytes on every attempt,
+            // including a retry of a "writing" lease: deterministic facts in, so a
+            // retry writes byte-identical output. A charged generation is never
+            // failed over metadata, so a malformed or truncated provider image is
+            // written as-is; embedProvenance never throws.
+            const format = z
+                .enum(["png", "jpeg", "gif", "webp", "mp4"])
+                .safeParse(output.format);
+            const provenance = format.success
+                ? yield* call(() => embedProvenance(output.bytes, format.data, {
+                    printId: operationId,
+                    model: input.request.model,
+                    prompt: input.request.prompt,
+                    createdAt: admission.operation.createdAt,
+                }), "operation")
+                : {
+                    bytes: output.bytes,
+                    embedded: false,
+                    reason: "unsupported-format",
+                };
+            if (!provenance.embedded)
+                console.warn("Media provenance not embedded", {
+                    format: output.format,
+                    reason: provenance.reason,
+                });
+            yield* call(() => input.destination.write(provenance.bytes), "destination-write").pipe(Effect.tapError(() => call(() => input.operation.releaseWrite(leaseId), "operation").pipe(Effect.ignore)));
+            image = {
+                bytes: provenance.bytes.byteLength,
+                format: output.format,
+            };
+            if (metering === null) {
+                yield* call(() => input.operation.recordWrittenWithoutSettlement(leaseId, "computer-write-committed", image), "operation");
+                return {
+                    kind: "succeeded",
+                    bytes: image.bytes,
+                    format: image.format,
+                    costMilliunits,
+                };
+            }
+            yield* call(() => input.operation.recordWritten(leaseId, "computer-write-committed", image), "operation");
+        }
+        if (metering === null)
+            return { kind: "unavailable" };
+        yield* call(() => metering.settle({ operationId, units: billed.units }), "billing");
+        yield* call(() => input.operation.recordSucceeded(leaseId, {
+            generationId: operationId,
+            bytes: image.bytes,
+            format: image.format,
+            costMilliunits,
+        }), "operation");
+        return {
+            kind: "succeeded",
+            bytes: image.bytes,
+            format: image.format,
+            costMilliunits,
+        };
+    });
+}