@fungi.computer/darkroom 0.0.0-stage → 0.1.0

package/docs/api/cloudflare.md

@@ -0,0 +1,678 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/darkroom**](README.md)
+
+---
+
+[@fungi.computer/darkroom](modules.md) / cloudflare
+
+# cloudflare
+
+## Classes
+
+### MediaOperationDO
+
+Cloudflare lifecycle and RPC surface around the durable media owner.
+
+#### Extends
+
+- `DurableObject`\<[`MediaOperationCloudflareEnvironment`](#mediaoperationcloudflareenvironment)\>
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new MediaOperationDO(ctx, env): MediaOperationDO;
+```
+
+###### Parameters
+
+| Parameter | Type                                                                          |
+| --------- | ----------------------------------------------------------------------------- |
+| `ctx`     | `DurableObjectState`                                                          |
+| `env`     | [`MediaOperationCloudflareEnvironment`](#mediaoperationcloudflareenvironment) |
+
+###### Returns
+
+[`MediaOperationDO`](#mediaoperationdo)
+
+###### Overrides
+
+```ts
+DurableObject<MediaOperationCloudflareEnvironment>.constructor
+```
+
+#### Methods
+
+##### read()
+
+```ts
+read(...input):
+  | Readonly<{
+  operationId: string;
+  requestId: string;
+  namespace: string;
+  owner: string;
+  state:   | "admitted"
+     | "estimating"
+     | "generating"
+     | "writing"
+     | "charging"
+     | "written"
+     | "succeeded"
+     | "interrupted";
+  spentFailure: "output_format_mismatch" | null;
+  providerRefusal: "safety_filter_refused" | null;
+  estimatedCostMilliunits: number | null;
+  image:   | {
+     bytes: number;
+     format: string;
+   }
+     | null;
+  result:   | {
+     generationId: string;
+     bytes: number;
+     format: string;
+     costMilliunits: number;
+   }
+     | null;
+  createdAt: number;
+  updatedAt: number;
+}>
+  | null;
+```
+
+Read the safe persisted operation projection, or null before admission or after
+erasure.
+
+###### Parameters
+
+| Parameter  | Type |
+| ---------- | ---- |
+| ...`input` | \[\] |
+
+###### Returns
+
+\| `Readonly`\<\{ `operationId`: `string`; `requestId`: `string`; `namespace`:
+`string`; `owner`: `string`; `state`: \| `"admitted"` \| `"estimating"` \|
+`"generating"` \| `"writing"` \| `"charging"` \| `"written"` \| `"succeeded"` \|
+`"interrupted"`; `spentFailure`: `"output_format_mismatch"` \| `null`;
+`providerRefusal`: `"safety_filter_refused"` \| `null`;
+`estimatedCostMilliunits`: `number` \| `null`; `image`: \| \{ `bytes`: `number`;
+`format`: `string`; \} \| `null`; `result`: \| \{ `generationId`: `string`;
+`bytes`: `number`; `format`: `string`; `costMilliunits`: `number`; \} \| `null`;
+`createdAt`: `number`; `updatedAt`: `number`; \}\> \| `null`
+
+##### preflightErasure()
+
+```ts
+preflightErasure(...input): ReturnType<MediaOperationOwner["preflightErasure"]>;
+```
+
+Check host namespace, request identity and inactivity before erasure.
+
+###### Parameters
+
+| Parameter  | Type                   | Description |
+| ---------- | ---------------------- | ----------- |
+| ...`input` | \[`string`, `string`\] | -           |
+
+###### Returns
+
+`ReturnType`\<[`MediaOperationOwner`](server.md#mediaoperationowner)\[`"preflightErasure"`\]\>
+
+##### erase()
+
+```ts
+erase(...input): Promise<Readonly<{
+  clear: boolean;
+}>>;
+```
+
+Erase inactive output and local storage, then retain the durable erasure marker.
+
+###### Parameters
+
+| Parameter  | Type                   | Description |
+| ---------- | ---------------------- | ----------- |
+| ...`input` | \[`string`, `string`\] | -           |
+
+###### Returns
+
+`Promise`\<`Readonly`\<\{ `clear`: `boolean`; \}\>\>
+
+##### readErasure()
+
+```ts
+readErasure(...input): Promise<Readonly<{
+  clear: boolean;
+}>>;
+```
+
+Read back empty SQL, alarm and retained output with the durable erasure marker.
+
+###### Parameters
+
+| Parameter  | Type |
+| ---------- | ---- |
+| ...`input` | \[\] |
+
+###### Returns
+
+`Promise`\<`Readonly`\<\{ `clear`: `boolean`; \}\>\>
+
+##### admit()
+
+```ts
+admit(...input): ReturnType<MediaOperationOwner["admit"]>;
+```
+
+Capture immutable host identity and input, replaying exact requests and refusing
+changed input.
+
+###### Parameters
+
+| Parameter  | Type                                                                                         | Description |
+| ---------- | -------------------------------------------------------------------------------------------- | ----------- |
+| ...`input` | \[`string`, `object`, `string`, [`MediaOperationRequest`](server.md#mediaoperationrequest)\] | -           |
+
+###### Returns
+
+`ReturnType`\<[`MediaOperationOwner`](server.md#mediaoperationowner)\[`"admit"`\]\>
+
+##### claim()
+
+```ts
+claim(...input): Promise<Readonly<{
+  kind:   | "admitted"
+     | "succeeded"
+     | "interrupted"
+     | "conflict"
+     | "replayed"
+     | "claimed"
+     | "pending";
+  operation: MediaOperationProjection;
+  leaseId?: string;
+}>>;
+```
+
+Claim a safe dispatch or save lease, recovering retained output without
+redispatching inference.
+
+###### Parameters
+
+| Parameter  | Type |
+| ---------- | ---- |
+| ...`input` | \[\] |
+
+###### Returns
+
+`Promise`\<`Readonly`\<\{ `kind`: \| `"admitted"` \| `"succeeded"` \|
+`"interrupted"` \| `"conflict"` \| `"replayed"` \| `"claimed"` \| `"pending"`;
+`operation`: [`MediaOperationProjection`](server.md#mediaoperationprojection);
+`leaseId?`: `string`; \}\>\>
+
+##### recordEstimate()
+
+```ts
+recordEstimate(...input): ReturnType<MediaOperationOwner["recordEstimate"]>;
+```
+
+Pin the admitted price and begin the generation lease.
+
+###### Parameters
+
+| Parameter  | Type                   | Description |
+| ---------- | ---------------------- | ----------- |
+| ...`input` | \[`string`, `number`\] | -           |
+
+###### Returns
+
+`ReturnType`\<[`MediaOperationOwner`](server.md#mediaoperationowner)\[`"recordEstimate"`\]\>
+
+##### dispatchInBackground()
+
+```ts
+dispatchInBackground(...input): Promise<Readonly<{
+  operationId: string;
+  requestId: string;
+  namespace: string;
+  owner: string;
+  state:   | "admitted"
+     | "estimating"
+     | "generating"
+     | "writing"
+     | "charging"
+     | "written"
+     | "succeeded"
+     | "interrupted";
+  spentFailure: "output_format_mismatch" | null;
+  providerRefusal: "safety_filter_refused" | null;
+  estimatedCostMilliunits: number | null;
+  image:   | {
+     bytes: number;
+     format: string;
+   }
+     | null;
+  result:   | {
+     generationId: string;
+     bytes: number;
+     format: string;
+     costMilliunits: number;
+   }
+     | null;
+  createdAt: number;
+  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.
+
+###### Parameters
+
+| Parameter  | Type                                                                                                                                                                               | Description |
+| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
+| ...`input` | \[`string`, readonly `Readonly`\<\{ `bytes`: `Uint8Array`; `format`: [`ImageFormat`](index.md#imageformat); `width`: `number`; `height`: `number`; `filename?`: `string`; \}\>[]\] | -           |
+
+###### Returns
+
+`Promise`\<`Readonly`\<\{ `operationId`: `string`; `requestId`: `string`;
+`namespace`: `string`; `owner`: `string`; `state`: \| `"admitted"` \|
+`"estimating"` \| `"generating"` \| `"writing"` \| `"charging"` \| `"written"`
+\| `"succeeded"` \| `"interrupted"`; `spentFailure`: `"output_format_mismatch"`
+\| `null`; `providerRefusal`: `"safety_filter_refused"` \| `null`;
+`estimatedCostMilliunits`: `number` \| `null`; `image`: \| \{ `bytes`: `number`;
+`format`: `string`; \} \| `null`; `result`: \| \{ `generationId`: `string`;
+`bytes`: `number`; `format`: `string`; `costMilliunits`: `number`; \} \| `null`;
+`createdAt`: `number`; `updatedAt`: `number`; \}\>\>
+
+##### alarm()
+
+```ts
+alarm(...input): Promise<void>;
+```
+
+Run a background generation once; a retried alarm never redispatches.
+
+###### Parameters
+
+| Parameter  | Type |
+| ---------- | ---- |
+| ...`input` | \[\] |
+
+###### Returns
+
+`Promise`\<`void`\>
+
+###### Overrides
+
+```ts
+DurableObject.alarm;
+```
+
+##### interruptGeneration()
+
+```ts
+interruptGeneration(...input): ReturnType<MediaOperationOwner["interruptGeneration"]>;
+```
+
+An aborted in-flight provider call is terminal for this request ID.
+
+###### Parameters
+
+| Parameter  | Type                                    | Description |
+| ---------- | --------------------------------------- | ----------- |
+| ...`input` | \[`string`, `"safety_filter_refused"`\] | -           |
+
+###### Returns
+
+`ReturnType`\<[`MediaOperationOwner`](server.md#mediaoperationowner)\[`"interruptGeneration"`\]\>
+
+##### recordGenerated()
+
+```ts
+recordGenerated(...input): Promise<MediaRetentionResult>;
+```
+
+Retain immutable provider output before making the save state visible.
+
+###### Parameters
+
+| Parameter  | Type                                                      | Description |
+| ---------- | --------------------------------------------------------- | ----------- |
+| ...`input` | \[`string`, `Uint8Array`\<`ArrayBufferLike`\>, `string`\] | -           |
+
+###### Returns
+
+`Promise`\<[`MediaRetentionResult`](server.md#mediaretentionresult)\>
+
+##### readGenerated()
+
+```ts
+readGenerated(...input): Promise<Uint8Array<ArrayBufferLike>>;
+```
+
+Read exact retained bytes under the current save lease.
+
+###### Parameters
+
+| Parameter  | Type         | Description |
+| ---------- | ------------ | ----------- |
+| ...`input` | \[`string`\] | -           |
+
+###### Returns
+
+`Promise`\<`Uint8Array`\<`ArrayBufferLike`\>\>
+
+##### releaseWrite()
+
+```ts
+releaseWrite(...input): ReturnType<MediaOperationOwner["releaseWrite"]>;
+```
+
+A fixed-path exact-byte save is safe to retry without repeating generation.
+
+###### Parameters
+
+| Parameter  | Type         | Description |
+| ---------- | ------------ | ----------- |
+| ...`input` | \[`string`\] | -           |
+
+###### Returns
+
+`ReturnType`\<[`MediaOperationOwner`](server.md#mediaoperationowner)\[`"releaseWrite"`\]\>
+
+##### recordWritten()
+
+```ts
+recordWritten(...input): ReturnType<MediaOperationOwner["recordWritten"]>;
+```
+
+Record a destination write and move to idempotent settlement.
+
+###### Parameters
+
+| Parameter  | Type                             | Description |
+| ---------- | -------------------------------- | ----------- |
+| ...`input` | \[`string`, `string`, `object`\] | -           |
+
+###### Returns
+
+`ReturnType`\<[`MediaOperationOwner`](server.md#mediaoperationowner)\[`"recordWritten"`\]\>
+
+##### recordWrittenWithoutSettlement()
+
+```ts
+recordWrittenWithoutSettlement(...input): ReturnType<MediaOperationOwner["recordWrittenWithoutSettlement"]>;
+```
+
+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.
+
+###### Parameters
+
+| Parameter  | Type                             | Description |
+| ---------- | -------------------------------- | ----------- |
+| ...`input` | \[`string`, `string`, `object`\] | -           |
+
+###### Returns
+
+`ReturnType`\<[`MediaOperationOwner`](server.md#mediaoperationowner)\[`"recordWrittenWithoutSettlement"`\]\>
+
+##### recordSucceeded()
+
+```ts
+recordSucceeded(...input): ReturnType<MediaOperationOwner["recordSucceeded"]>;
+```
+
+Commit the settled receipt after verifying the saved output and admitted price.
+
+###### Parameters
+
+| Parameter  | Type                   | Description |
+| ---------- | ---------------------- | ----------- |
+| ...`input` | \[`string`, `object`\] | -           |
+
+###### Returns
+
+`ReturnType`\<[`MediaOperationOwner`](server.md#mediaoperationowner)\[`"recordSucceeded"`\]\>
+
+##### releaseEstimate()
+
+```ts
+releaseEstimate(...input): ReturnType<MediaOperationOwner["releaseEstimate"]>;
+```
+
+Release preparation or refused admission so the same request can retry.
+
+###### Parameters
+
+| Parameter  | Type         | Description |
+| ---------- | ------------ | ----------- |
+| ...`input` | \[`string`\] | -           |
+
+###### Returns
+
+`ReturnType`\<[`MediaOperationOwner`](server.md#mediaoperationowner)\[`"releaseEstimate"`\]\>
+
+## Type Aliases
+
+### MediaAiResult
+
+```ts
+type MediaAiResult = Awaited<ReturnType<Ai["run"]>> | MediaProviderWire;
+```
+
+Native Workers AI output or an already decoded provider representation.
+
+---
+
+### MediaAiPort
+
+```ts
+type MediaAiPort = object;
+```
+
+Workers AI results vary by model; the provider decodes them at this boundary.
+
+#### Methods
+
+##### run()
+
+```ts
+run(
+   model,
+   input,
+   options?
+): Promise<MediaAiResult>;
+```
+
+Dispatch to the native Workers AI binding.
+
+###### Parameters
+
+| Parameter  | Type                            |
+| ---------- | ------------------------------- |
+| `model`    | `string`                        |
+| `input`    | `Record`\<`string`, `unknown`\> |
+| `options?` | `AiOptions`                     |
+
+###### Returns
+
+`Promise`\<[`MediaAiResult`](#mediaairesult)\>
+
+---
+
+### MediaImagePort
+
+```ts
+type MediaImagePort = object;
+```
+
+Only image metadata and the bounded resize chain are consumed by Media.
+
+#### Methods
+
+##### info()
+
+```ts
+info(input): Promise<ImageInfoResponse>;
+```
+
+Read decoded image metadata through the Images binding.
+
+###### Parameters
+
+| Parameter | Type                                                  |
+| --------- | ----------------------------------------------------- |
+| `input`   | `ReadableStream`\<`Uint8Array`\<`ArrayBufferLike`\>\> |
+
+###### Returns
+
+`Promise`\<`ImageInfoResponse`\>
+
+##### input()
+
+```ts
+input(input): object;
+```
+
+Start the native resize and encode chain.
+
+###### Parameters
+
+| Parameter | Type                                                  |
+| --------- | ----------------------------------------------------- |
+| `input`   | `ReadableStream`\<`Uint8Array`\<`ArrayBufferLike`\>\> |
+
+###### Returns
+
+| Name          | Type                    | Description                            |
+| ------------- | ----------------------- | -------------------------------------- |
+| `transform()` | (`options`) => `object` | Apply the native scale-down transform. |
+
+---
+
+### MediaOperationCloudflareEnvironment
+
+```ts
+type MediaOperationCloudflareEnvironment = MediaOperationEnvironment &
+  Readonly<{
+    AI?: MediaAiPort;
+    AI_GATEWAY_ID?: string;
+  }>;
+```
+
+Retention storage and native background provider bindings for the operation DO.
+
+## Functions
+
+### createWorkersAiMediaProvider()
+
+```ts
+function createWorkersAiMediaProvider(ai, options?): MediaProvider;
+```
+
+Media's provider port on the Workers AI binding, with fixed options such as the
+AI Gateway route.
+
+#### Parameters
+
+| Parameter  | Type                          |
+| ---------- | ----------------------------- |
+| `ai`       | [`MediaAiPort`](#mediaaiport) |
+| `options?` | `AiOptions`                   |
+
+#### Returns
+
+[`MediaProvider`](index.md#mediaprovider)
+
+---
+
+### createImagesReferenceFitter()
+
+```ts
+function createImagesReferenceFitter(images): ReferenceImageFitter;
+```
+
+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.
+
+#### Parameters
+
+| Parameter | Type                                |
+| --------- | ----------------------------------- |
+| `images`  | [`MediaImagePort`](#mediaimageport) |
+
+#### Returns
+
+[`ReferenceImageFitter`](index.md#referenceimagefitter)
+
+---
+
+### createImagesViewFitter()
+
+```ts
+function createImagesViewFitter(images): ImageViewFitter;
+```
+
+Fit one image for a model to look at on the Images binding: always re-encode it
+as JPEG (quality 80), scaled down within `maxDimension`, and decode the output
+so its metadata describes the bytes actually returned.
+
+#### Parameters
+
+| Parameter | Type                                |
+| --------- | ----------------------------------- |
+| `images`  | [`MediaImagePort`](#mediaimageport) |
+
+#### Returns
+
+[`ImageViewFitter`](index.md#imageviewfitter)
+
+## References
+
+### MediaOperationCoordinates
+
+Re-exports [MediaOperationCoordinates](server.md#mediaoperationcoordinates)
+
+---
+
+### MediaOperationRequest
+
+Re-exports [MediaOperationRequest](server.md#mediaoperationrequest)
+
+---
+
+### MediaOperationOwner
+
+Re-exports [MediaOperationOwner](server.md#mediaoperationowner)
+
+---
+
+### MediaOperationContext
+
+Re-exports [MediaOperationContext](server.md#mediaoperationcontext)
+
+---
+
+### MediaOperationStorage
+
+Re-exports [MediaOperationStorage](server.md#mediaoperationstorage)
+
+---
+
+### MediaOperationBucket
+
+Re-exports [MediaOperationBucket](server.md#mediaoperationbucket)
+
+---
+
+### MediaOperationObject
+
+Re-exports [MediaOperationObject](server.md#mediaoperationobject)

package/docs/api/effect.md

@@ -0,0 +1,39 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/darkroom**](README.md)
+
+---
+
+[@fungi.computer/darkroom](modules.md) / effect
+
+# effect
+
+## Functions
+
+### runMediaGeneration()
+
+```ts
+function runMediaGeneration(
+  host,
+  request,
+  signal?,
+): Effect<MediaGenerationOutcome, MediaSettingsError | MediaExecutionError>;
+```
+
+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.
+
+#### Parameters
+
+| Parameter | Type                                                         |
+| --------- | ------------------------------------------------------------ |
+| `host`    | [`MediaServiceHost`](server.md#mediaservicehost)             |
+| `request` | [`MediaGenerationRequest`](server.md#mediagenerationrequest) |
+| `signal?` | `AbortSignal`                                                |
+
+#### Returns
+
+`Effect`\<[`MediaGenerationOutcome`](server.md#mediagenerationoutcome), \|
+[`MediaSettingsError`](index.md#mediasettingserror) \|
+[`MediaExecutionError`](server.md#mediaexecutionerror)\>