@fungi.computer/darkroom 0.0.0-stage → 0.1.0

package/dist/media-operation-contract.js

@@ -0,0 +1,29 @@
+import * as z from "zod";
+/** Decode a completed generation, destination path and estimated or settled price. */
+export const mediaResultSchema = z.strictObject({
+    /** Output byte length. */
+    bytes: z.number().int().positive(),
+    /** Admitted price in milliunits, where 1 cent is 1,000 milliunits. */
+    costMilliunits: z.number().int().nonnegative(),
+    /** Fixed destination or reference file path. */
+    path: z.string().min(1).max(1_024),
+    /** Actual output encoding. */
+    format: z.enum({
+        /** PNG image encoding. */
+        png: "png",
+        /** JPEG image encoding. */
+        jpeg: "jpeg",
+        /** GIF image encoding. */
+        gif: "gif",
+        /** WebP image encoding. */
+        webp: "webp",
+        /** MP4 video encoding. */
+        mp4: "mp4",
+    }),
+    /** Requested image height or nominal video selector, not decoded MP4 dimensions. */
+    height: z.number().int().positive(),
+    /** Provider catalog model identifier. */
+    model: z.string().min(1).max(256),
+    /** Requested image width or nominal video selector, not decoded MP4 dimensions. */
+    width: z.number().int().positive(),
+});

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

@@ -0,0 +1,55 @@
+import { DurableObject } from "cloudflare:workers";
+import { type MediaAiPort } from "./cloudflare/provider.js";
+import type { MediaProvider } from "./index.js";
+import { MediaOperationOwner, type MediaOperationEnvironment } from "./media-operation-owner.js";
+export type { MediaOperationRequest, MediaOperationCoordinates, MediaOperationEnvironment, } from "./media-operation-owner.js";
+/** Retention storage and native background provider bindings for the operation DO. */
+export type MediaOperationCloudflareEnvironment = MediaOperationEnvironment & Readonly<{
+    /** Workers AI binding for alarm-driven generation. */
+    AI?: MediaAiPort;
+    /** Optional AI Gateway route for background calls. */
+    AI_GATEWAY_ID?: string;
+}>;
+/** Cloudflare lifecycle and RPC surface around the durable media owner. */
+export declare class MediaOperationDO extends DurableObject<MediaOperationCloudflareEnvironment> {
+    protected readonly owner: MediaOperationOwner;
+    constructor(ctx: DurableObjectState, env: MediaOperationCloudflareEnvironment);
+    /** A host may pin the namespace through its own local lifecycle facts. */
+    protected retainedNamespace(): string | null;
+    /** Hosts may supply their own provider for background generation. */
+    protected mediaProvider(): MediaProvider | undefined;
+    /** {@inheritDoc MediaOperationOwner.read} */
+    read(...input: Parameters<MediaOperationOwner["read"]>): ReturnType<MediaOperationOwner["read"]>;
+    /** {@inheritDoc MediaOperationOwner.preflightErasure} */
+    preflightErasure(...input: Parameters<MediaOperationOwner["preflightErasure"]>): ReturnType<MediaOperationOwner["preflightErasure"]>;
+    /** {@inheritDoc MediaOperationOwner.erase} */
+    erase(...input: Parameters<MediaOperationOwner["erase"]>): ReturnType<MediaOperationOwner["erase"]>;
+    /** {@inheritDoc MediaOperationOwner.readErasure} */
+    readErasure(...input: Parameters<MediaOperationOwner["readErasure"]>): ReturnType<MediaOperationOwner["readErasure"]>;
+    /** {@inheritDoc MediaOperationOwner.admit} */
+    admit(...input: Parameters<MediaOperationOwner["admit"]>): ReturnType<MediaOperationOwner["admit"]>;
+    /** {@inheritDoc MediaOperationOwner.claim} */
+    claim(...input: Parameters<MediaOperationOwner["claim"]>): ReturnType<MediaOperationOwner["claim"]>;
+    /** {@inheritDoc MediaOperationOwner.recordEstimate} */
+    recordEstimate(...input: Parameters<MediaOperationOwner["recordEstimate"]>): ReturnType<MediaOperationOwner["recordEstimate"]>;
+    /** {@inheritDoc MediaOperationOwner.dispatchInBackground} */
+    dispatchInBackground(...input: Parameters<MediaOperationOwner["dispatchInBackground"]>): ReturnType<MediaOperationOwner["dispatchInBackground"]>;
+    /** {@inheritDoc MediaOperationOwner.alarm} */
+    alarm(...input: Parameters<MediaOperationOwner["alarm"]>): ReturnType<MediaOperationOwner["alarm"]>;
+    /** {@inheritDoc MediaOperationOwner.interruptGeneration} */
+    interruptGeneration(...input: Parameters<MediaOperationOwner["interruptGeneration"]>): ReturnType<MediaOperationOwner["interruptGeneration"]>;
+    /** {@inheritDoc MediaOperationOwner.recordGenerated} */
+    recordGenerated(...input: Parameters<MediaOperationOwner["recordGenerated"]>): ReturnType<MediaOperationOwner["recordGenerated"]>;
+    /** {@inheritDoc MediaOperationOwner.readGenerated} */
+    readGenerated(...input: Parameters<MediaOperationOwner["readGenerated"]>): ReturnType<MediaOperationOwner["readGenerated"]>;
+    /** {@inheritDoc MediaOperationOwner.releaseWrite} */
+    releaseWrite(...input: Parameters<MediaOperationOwner["releaseWrite"]>): ReturnType<MediaOperationOwner["releaseWrite"]>;
+    /** {@inheritDoc MediaOperationOwner.recordWritten} */
+    recordWritten(...input: Parameters<MediaOperationOwner["recordWritten"]>): ReturnType<MediaOperationOwner["recordWritten"]>;
+    /** {@inheritDoc MediaOperationOwner.recordWrittenWithoutSettlement} */
+    recordWrittenWithoutSettlement(...input: Parameters<MediaOperationOwner["recordWrittenWithoutSettlement"]>): ReturnType<MediaOperationOwner["recordWrittenWithoutSettlement"]>;
+    /** {@inheritDoc MediaOperationOwner.recordSucceeded} */
+    recordSucceeded(...input: Parameters<MediaOperationOwner["recordSucceeded"]>): ReturnType<MediaOperationOwner["recordSucceeded"]>;
+    /** {@inheritDoc MediaOperationOwner.releaseEstimate} */
+    releaseEstimate(...input: Parameters<MediaOperationOwner["releaseEstimate"]>): ReturnType<MediaOperationOwner["releaseEstimate"]>;
+}

package/dist/media-operation-do.js

@@ -0,0 +1,105 @@
+import { DurableObject } from "cloudflare:workers";
+import { createWorkersAiMediaProvider, } from "./cloudflare/provider.js";
+import { MediaOperationOwner, } from "./media-operation-owner.js";
+/** Cloudflare lifecycle and RPC surface around the durable media owner. */
+export class MediaOperationDO extends DurableObject {
+    owner;
+    constructor(ctx, env) {
+        super(ctx, env);
+        this.owner = new MediaOperationOwner({
+            id: { name: ctx.id.name },
+            blockConcurrencyWhile: (body) => ctx.blockConcurrencyWhile(body),
+            storage: {
+                sql: ctx.storage.sql,
+                transactionSync: (body) => ctx.storage.transactionSync(body),
+                isErased: async () => (await ctx.storage.get("botanical:erased")) === true,
+                markErased: () => ctx.storage.put("botanical:erased", true),
+                listKeys: async () => [...(await ctx.storage.list()).keys()],
+                deleteAlarm: () => ctx.storage.deleteAlarm(),
+                deleteAll: () => ctx.storage.deleteAll(),
+                getAlarm: () => ctx.storage.getAlarm(),
+                setAlarm: (timestamp) => ctx.storage.setAlarm(timestamp),
+            },
+        }, env, () => this.mediaProvider(), { namespace: () => this.retainedNamespace() });
+    }
+    /** A host may pin the namespace through its own local lifecycle facts. */
+    retainedNamespace() {
+        return null;
+    }
+    /** Hosts may supply their own provider for background generation. */
+    mediaProvider() {
+        if (this.env.AI === undefined)
+            return undefined;
+        return createWorkersAiMediaProvider(this.env.AI, this.env.AI_GATEWAY_ID === undefined
+            ? undefined
+            : { gateway: { id: this.env.AI_GATEWAY_ID } });
+    }
+    /** {@inheritDoc MediaOperationOwner.read} */
+    read(...input) {
+        return this.owner.read(...input);
+    }
+    /** {@inheritDoc MediaOperationOwner.preflightErasure} */
+    preflightErasure(...input) {
+        return this.owner.preflightErasure(...input);
+    }
+    /** {@inheritDoc MediaOperationOwner.erase} */
+    erase(...input) {
+        return this.owner.erase(...input);
+    }
+    /** {@inheritDoc MediaOperationOwner.readErasure} */
+    readErasure(...input) {
+        return this.owner.readErasure(...input);
+    }
+    /** {@inheritDoc MediaOperationOwner.admit} */
+    admit(...input) {
+        return this.owner.admit(...input);
+    }
+    /** {@inheritDoc MediaOperationOwner.claim} */
+    claim(...input) {
+        return this.owner.claim(...input);
+    }
+    /** {@inheritDoc MediaOperationOwner.recordEstimate} */
+    recordEstimate(...input) {
+        return this.owner.recordEstimate(...input);
+    }
+    /** {@inheritDoc MediaOperationOwner.dispatchInBackground} */
+    dispatchInBackground(...input) {
+        return this.owner.dispatchInBackground(...input);
+    }
+    /** {@inheritDoc MediaOperationOwner.alarm} */
+    alarm(...input) {
+        return this.owner.alarm(...input);
+    }
+    /** {@inheritDoc MediaOperationOwner.interruptGeneration} */
+    interruptGeneration(...input) {
+        return this.owner.interruptGeneration(...input);
+    }
+    /** {@inheritDoc MediaOperationOwner.recordGenerated} */
+    recordGenerated(...input) {
+        return this.owner.recordGenerated(...input);
+    }
+    /** {@inheritDoc MediaOperationOwner.readGenerated} */
+    readGenerated(...input) {
+        return this.owner.readGenerated(...input);
+    }
+    /** {@inheritDoc MediaOperationOwner.releaseWrite} */
+    releaseWrite(...input) {
+        return this.owner.releaseWrite(...input);
+    }
+    /** {@inheritDoc MediaOperationOwner.recordWritten} */
+    recordWritten(...input) {
+        return this.owner.recordWritten(...input);
+    }
+    /** {@inheritDoc MediaOperationOwner.recordWrittenWithoutSettlement} */
+    recordWrittenWithoutSettlement(...input) {
+        return this.owner.recordWrittenWithoutSettlement(...input);
+    }
+    /** {@inheritDoc MediaOperationOwner.recordSucceeded} */
+    recordSucceeded(...input) {
+        return this.owner.recordSucceeded(...input);
+    }
+    /** {@inheritDoc MediaOperationOwner.releaseEstimate} */
+    releaseEstimate(...input) {
+        return this.owner.releaseEstimate(...input);
+    }
+}

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

@@ -0,0 +1,301 @@
+import { type MediaGenerationSettings } from "./index.js";
+import { z } from "zod";
+import type { MediaOperationContext, MediaOperationBucket } from "./media-operation-storage.js";
+import type { MediaProvider, MediaReferenceBytes } from "./index.js";
+/** Fixed generation destination captured before provider dispatch. */
+export declare const mediaOperationDestinationSchema: z.ZodLazy<z.ZodObject<{
+    computerId: z.ZodString;
+    path: z.ZodString;
+    outputFormat: z.ZodOptional<z.ZodEnum<{
+        readonly png: "png";
+        readonly jpeg: "jpeg";
+        readonly webp: "webp";
+    }>>;
+}, z.core.$strict>>;
+/** Normalized generation and its fixed destination, captured for exact replay. */
+export type MediaOperationRequest = MediaGenerationSettings & z.output<typeof mediaOperationDestinationSchema>;
+/** Decode host namespace and owner identity. */
+export declare const mediaOperationCoordinatesSchema: z.ZodObject<{
+    namespace: z.ZodString;
+    owner: z.ZodString;
+}, z.core.$strict>;
+/** Host-owned namespace and owner identity for one durable operation. */
+export type MediaOperationCoordinates = z.output<typeof mediaOperationCoordinatesSchema>;
+/** Decode durable generation, save and settlement states. */
+export declare const mediaOperationStateSchema: z.ZodEnum<{
+    /** Host identity and input captured. */
+    readonly admitted: "admitted";
+    /** Exclusive input preparation lease. */
+    readonly estimating: "estimating";
+    /** Provider dispatch admitted; output not yet retained. */
+    readonly generating: "generating";
+    /** Generated output retained; destination save in progress. */
+    readonly writing: "writing";
+    /** Destination committed; idempotent host settlement pending. */
+    readonly charging: "charging";
+    /** Unmetered generation and destination write completed with a quote. */
+    readonly written: "written";
+    /** Generation and settlement completed. */
+    readonly succeeded: "succeeded";
+    /** Provider execution ended without a reusable output. */
+    readonly interrupted: "interrupted";
+}>;
+/** Durable generation, save and settlement states. */
+export type MediaOperationState = z.output<typeof mediaOperationStateSchema>;
+/** Decode retained or saved output size and encoding. */
+export declare const mediaImageSchema: z.ZodLazy<z.ZodObject<{
+    bytes: z.ZodNumber;
+    format: z.ZodString;
+}, z.core.$strict>>;
+/** Byte length and encoding of generated or saved output. */
+export type MediaImage = z.output<typeof mediaImageSchema>;
+/** Decode the settled receipt, including the host-admitted customer price. */
+export declare const mediaOperationResultSchema: z.ZodLazy<z.ZodObject<{
+    generationId: z.ZodString;
+    bytes: z.ZodNumber;
+    format: z.ZodString;
+    costMilliunits: z.ZodNumber;
+}, z.core.$strict>>;
+/** Settled generation receipt with the host-admitted customer price. */
+export type MediaOperationResult = z.output<typeof mediaOperationResultSchema>;
+/** The only operation shape safe to return outside the owner. */
+export type MediaOperationProjection = Readonly<{
+    /** Durable object name identifying this operation. */
+    operationId: string;
+    /** Retry identity chosen by the caller. */
+    requestId: string;
+    /** Host isolation namespace. */
+    namespace: string;
+    /** Host owner within the namespace. */
+    owner: string;
+    /** Current durable lifecycle state. */
+    state: MediaOperationState;
+    /** Terminal format mismatch after provider execution. */
+    spentFailure: "output_format_mismatch" | null;
+    /** Definitive provider refusal with no delivered or billable output. */
+    providerRefusal: "safety_filter_refused" | null;
+    /** Pinned host price or unmetered quote. */
+    estimatedCostMilliunits: number | null;
+    /** Retained or saved image metadata. */
+    image: MediaImage | null;
+    /** Settled receipt when generation and billing completed. */
+    result: MediaOperationResult | null;
+    /** Admission timestamp in milliseconds since the epoch. */
+    createdAt: number;
+    /** Last transition timestamp in milliseconds since the epoch. */
+    updatedAt: number;
+}>;
+/** An admission or claim decision with a safe operation projection. */
+export type MediaOperationDecision = Readonly<{
+    /** Admission or claim outcome. */
+    kind: "admitted" | "conflict" | "replayed" | "claimed" | "pending" | "succeeded" | "interrupted";
+    /** Safe persisted projection for this decision. */
+    operation: MediaOperationProjection;
+    /** Exclusive dispatch or save lease when claimed. */
+    leaseId?: string;
+}>;
+/** Scoped inactivity observation made before destructive erasure. */
+export type MediaErasurePreflight = Readonly<{
+    /** Namespace supplied by the host's resource roster. */
+    namespace: string;
+    /** Named operation request supplied by that roster. */
+    requestId: string;
+    /** Whether durable erasure has already completed. */
+    erased: boolean;
+}>;
+/** Evidence that retained output, SQL and alarms were erased. */
+export type MediaErasureReadback = Readonly<{
+    /** True only after all local data and retained output are absent. */
+    clear: boolean;
+}>;
+/** Retained output projection, or a terminal spent format refusal. */
+export type MediaRetentionResult = MediaOperationProjection | Readonly<{
+    /** Provider execution finished with an unusable pinned format. */
+    kind: "refused";
+    /** Stable mismatch reason recorded before settlement. */
+    code: "output_format_mismatch";
+}>;
+/** Optional host facts that pin a namespace before operation admission. */
+export type MediaOperationHooks = Readonly<{
+    /** Read the namespace already owned by host-local facts, or null when unbound. */
+    namespace?: () => string | null;
+}>;
+/** Retained-output storage supplied by the host. */
+export type MediaOperationEnvironment = Readonly<{
+    /** Bucket retaining exact output and background reference bytes. */
+    APP_ARTIFACTS: MediaOperationBucket;
+}>;
+/** Own exact replay, dispatch leases, retained output and save recovery in SQL and object storage. */
+export declare class MediaOperationOwner {
+    private readonly ctx;
+    private readonly env;
+    private readonly provider?;
+    private readonly hooks;
+    private erased;
+    private readonly leaseMs;
+    /**
+     * A background (video) generation holds its lease past the 15-minute alarm
+     * wall-clock limit, so a live alarm is never mistaken for a lost one.
+     */
+    private readonly backgroundLeaseMs;
+    private initialized;
+    /**
+     * The host supplies the provider for background alarm generations.
+     */
+    protected mediaProvider(): MediaProvider | undefined;
+    constructor(ctx: MediaOperationContext, env: MediaOperationEnvironment, provider?: (() => MediaProvider | undefined) | undefined, hooks?: MediaOperationHooks);
+    private ensureSchema;
+    private decodeJson;
+    private decode;
+    private project;
+    private readRecord;
+    /** Read the safe persisted operation projection, or null before admission or after erasure. */
+    read(): MediaOperationProjection | null;
+    /** Check host namespace, request identity and inactivity before erasure. */
+    preflightErasure(namespace: string, requestId: string): MediaErasurePreflight;
+    /** Erase inactive output and local storage, then retain the durable erasure marker. */
+    erase(namespace: string, requestId: string): Promise<Readonly<{
+        /** True only after all local data and retained output are absent. */
+        clear: boolean;
+    }>>;
+    /** Read back empty SQL, alarm and retained output with the durable erasure marker. */
+    readErasure(): Promise<MediaErasureReadback>;
+    private erasureOutputKey;
+    private requireRecord;
+    private update;
+    private transition;
+    /** Capture immutable host identity and input, replaying exact requests and refusing changed input. */
+    admit(actorUserId: string, coordinatesInput: MediaOperationCoordinates, requestId: string, input: MediaOperationRequest): MediaOperationDecision;
+    /** Claim a safe dispatch or save lease, recovering retained output without redispatching inference. */
+    claim(): Promise<MediaOperationDecision>;
+    /** Pin the admitted price and begin the generation lease. */
+    recordEstimate(leaseId: string, costMilliunits: number): Readonly<{
+        /** Durable object name identifying this operation. */
+        operationId: string;
+        /** Retry identity chosen by the caller. */
+        requestId: string;
+        /** Host isolation namespace. */
+        namespace: string;
+        /** Host owner within the namespace. */
+        owner: string;
+        /** Current durable lifecycle state. */
+        state: MediaOperationState;
+        /** Terminal format mismatch after provider execution. */
+        spentFailure: "output_format_mismatch" | null;
+        /** Definitive provider refusal with no delivered or billable output. */
+        providerRefusal: "safety_filter_refused" | null;
+        /** Pinned host price or unmetered quote. */
+        estimatedCostMilliunits: number | null;
+        /** Retained or saved image metadata. */
+        image: MediaImage | null;
+        /** Settled receipt when generation and billing completed. */
+        result: MediaOperationResult | null;
+        /** Admission timestamp in milliseconds since the epoch. */
+        createdAt: number;
+        /** Last transition timestamp in milliseconds since the epoch. */
+        updatedAt: number;
+    }>;
+    /**
+     * Hand a long (video) generation to this owner's alarm. The caller's request
+     * returns at once; the alarm dispatches the provider exactly once, retains
+     * the output, and releases the lease so a later retry saves and charges it.
+     */
+    dispatchInBackground(leaseId: string, references: readonly MediaReferenceBytes[]): Promise<MediaOperationProjection>;
+    /** Run a background generation once; a retried alarm never redispatches. */
+    alarm(): Promise<void>;
+    /** An aborted in-flight provider call is terminal for this request ID. */
+    interruptGeneration(leaseId: string, refusalInput?: NonNullable<MediaOperationProjection["providerRefusal"]>): MediaOperationProjection;
+    /** Retain immutable provider output before making the save state visible. */
+    recordGenerated(leaseId: string, bytes: Uint8Array, formatInput: string): Promise<MediaRetentionResult>;
+    /** Read exact retained bytes under the current save lease. */
+    readGenerated(leaseId: string): Promise<Uint8Array>;
+    /** A fixed-path exact-byte save is safe to retry without repeating generation. */
+    releaseWrite(leaseId: string): MediaOperationProjection;
+    /** Record a destination write and move to idempotent settlement. */
+    recordWritten(leaseId: string, receipt: string, written: MediaImage): Readonly<{
+        /** Durable object name identifying this operation. */
+        operationId: string;
+        /** Retry identity chosen by the caller. */
+        requestId: string;
+        /** Host isolation namespace. */
+        namespace: string;
+        /** Host owner within the namespace. */
+        owner: string;
+        /** Current durable lifecycle state. */
+        state: MediaOperationState;
+        /** Terminal format mismatch after provider execution. */
+        spentFailure: "output_format_mismatch" | null;
+        /** Definitive provider refusal with no delivered or billable output. */
+        providerRefusal: "safety_filter_refused" | null;
+        /** Pinned host price or unmetered quote. */
+        estimatedCostMilliunits: number | null;
+        /** Retained or saved image metadata. */
+        image: MediaImage | null;
+        /** Settled receipt when generation and billing completed. */
+        result: MediaOperationResult | null;
+        /** Admission timestamp in milliseconds since the epoch. */
+        createdAt: number;
+        /** Last transition timestamp in milliseconds since the epoch. */
+        updatedAt: number;
+    }>;
+    /**
+     * Persist a completed Computer write without claiming billing success.
+     * A lost receipt may replay the exact retained bytes to the captured path;
+     * it never repeats provider generation.
+     */
+    recordWrittenWithoutSettlement(leaseId: string, receipt: string, written: MediaImage): Readonly<{
+        /** Durable object name identifying this operation. */
+        operationId: string;
+        /** Retry identity chosen by the caller. */
+        requestId: string;
+        /** Host isolation namespace. */
+        namespace: string;
+        /** Host owner within the namespace. */
+        owner: string;
+        /** Current durable lifecycle state. */
+        state: MediaOperationState;
+        /** Terminal format mismatch after provider execution. */
+        spentFailure: "output_format_mismatch" | null;
+        /** Definitive provider refusal with no delivered or billable output. */
+        providerRefusal: "safety_filter_refused" | null;
+        /** Pinned host price or unmetered quote. */
+        estimatedCostMilliunits: number | null;
+        /** Retained or saved image metadata. */
+        image: MediaImage | null;
+        /** Settled receipt when generation and billing completed. */
+        result: MediaOperationResult | null;
+        /** Admission timestamp in milliseconds since the epoch. */
+        createdAt: number;
+        /** Last transition timestamp in milliseconds since the epoch. */
+        updatedAt: number;
+    }>;
+    /** Commit the settled receipt after verifying the saved output and admitted price. */
+    recordSucceeded(leaseId: string, resultInput: MediaOperationResult): Readonly<{
+        /** Durable object name identifying this operation. */
+        operationId: string;
+        /** Retry identity chosen by the caller. */
+        requestId: string;
+        /** Host isolation namespace. */
+        namespace: string;
+        /** Host owner within the namespace. */
+        owner: string;
+        /** Current durable lifecycle state. */
+        state: MediaOperationState;
+        /** Terminal format mismatch after provider execution. */
+        spentFailure: "output_format_mismatch" | null;
+        /** Definitive provider refusal with no delivered or billable output. */
+        providerRefusal: "safety_filter_refused" | null;
+        /** Pinned host price or unmetered quote. */
+        estimatedCostMilliunits: number | null;
+        /** Retained or saved image metadata. */
+        image: MediaImage | null;
+        /** Settled receipt when generation and billing completed. */
+        result: MediaOperationResult | null;
+        /** Admission timestamp in milliseconds since the epoch. */
+        createdAt: number;
+        /** Last transition timestamp in milliseconds since the epoch. */
+        updatedAt: number;
+    }>;
+    /** Release preparation or refused admission so the same request can retry. */
+    releaseEstimate(leaseId: string): MediaOperationProjection;
+}