@fungi.computer/darkroom 0.0.0-stage → 0.1.0

package/docs/api/server.md

@@ -0,0 +1,1672 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/darkroom**](README.md)
+
+---
+
+[@fungi.computer/darkroom](modules.md) / server
+
+# server
+
+## Classes
+
+### MediaExecutionError
+
+A bounded stage marker for failures that cross the Media HTTP boundary.
+
+#### Extends
+
+- `Error`
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new MediaExecutionError(stage, options?): MediaExecutionError;
+```
+
+###### Parameters
+
+| Parameter  | Type                                      | Description                                 |
+| ---------- | ----------------------------------------- | ------------------------------------------- |
+| `stage`    | [`MediaFailureStage`](#mediafailurestage) | Execution stage where the failure occurred. |
+| `options?` | `ErrorOptions`                            | -                                           |
+
+###### Returns
+
+[`MediaExecutionError`](#mediaexecutionerror)
+
+###### Overrides
+
+```ts
+Error.constructor;
+```
+
+#### Properties
+
+##### stage
+
+```ts
+readonly stage: MediaFailureStage;
+```
+
+Execution stage where the failure occurred.
+
+---
+
+### MediaBillingRefusal
+
+A definitive billing refusal before dispatch; nothing was generated or charged.
+
+#### Extends
+
+- `Error`
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new MediaBillingRefusal(code): MediaBillingRefusal;
+```
+
+###### Parameters
+
+| Parameter | Type                                                  | Description                        |
+| --------- | ----------------------------------------------------- | ---------------------------------- |
+| `code`    | [`MediaBillingRefusalCode`](#mediabillingrefusalcode) | Bounded refusal or failure reason. |
+
+###### Returns
+
+[`MediaBillingRefusal`](#mediabillingrefusal)
+
+###### Overrides
+
+```ts
+Error.constructor;
+```
+
+#### Properties
+
+##### code
+
+```ts
+readonly code: MediaBillingRefusalCode;
+```
+
+Bounded refusal or failure reason.
+
+---
+
+### MediaOperationOwner
+
+Own exact replay, dispatch leases, retained output and save recovery in SQL and
+object storage.
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new MediaOperationOwner(
+   ctx,
+   env,
+   provider?,
+   hooks?
+): MediaOperationOwner;
+```
+
+###### Parameters
+
+| Parameter   | Type                                                           |
+| ----------- | -------------------------------------------------------------- |
+| `ctx`       | [`MediaOperationContext`](#mediaoperationcontext)              |
+| `env`       | [`MediaOperationEnvironment`](#mediaoperationenvironment)      |
+| `provider?` | () => [`MediaProvider`](index.md#mediaprovider) \| `undefined` |
+| `hooks?`    | [`MediaOperationHooks`](#mediaoperationhooks)                  |
+
+###### Returns
+
+[`MediaOperationOwner`](#mediaoperationowner)
+
+#### Methods
+
+##### read()
+
+```ts
+read():
+  | 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.
+
+###### 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(namespace, requestId): MediaErasurePreflight;
+```
+
+Check host namespace, request identity and inactivity before erasure.
+
+###### Parameters
+
+| Parameter   | Type     |
+| ----------- | -------- |
+| `namespace` | `string` |
+| `requestId` | `string` |
+
+###### Returns
+
+[`MediaErasurePreflight`](#mediaerasurepreflight)
+
+##### erase()
+
+```ts
+erase(namespace, requestId): Promise<Readonly<{
+  clear: boolean;
+}>>;
+```
+
+Erase inactive output and local storage, then retain the durable erasure marker.
+
+###### Parameters
+
+| Parameter   | Type     |
+| ----------- | -------- |
+| `namespace` | `string` |
+| `requestId` | `string` |
+
+###### Returns
+
+`Promise`\<`Readonly`\<\{ `clear`: `boolean`; \}\>\>
+
+##### readErasure()
+
+```ts
+readErasure(): Promise<Readonly<{
+  clear: boolean;
+}>>;
+```
+
+Read back empty SQL, alarm and retained output with the durable erasure marker.
+
+###### Returns
+
+`Promise`\<`Readonly`\<\{ `clear`: `boolean`; \}\>\>
+
+##### admit()
+
+```ts
+admit(
+   actorUserId,
+   coordinatesInput,
+   requestId,
+   input
+): MediaOperationDecision;
+```
+
+Capture immutable host identity and input, replaying exact requests and refusing
+changed input.
+
+###### Parameters
+
+| Parameter                    | Type                                              | Description                      |
+| ---------------------------- | ------------------------------------------------- | -------------------------------- |
+| `actorUserId`                | `string`                                          | -                                |
+| `coordinatesInput`           | \{ `namespace`: `string`; `owner`: `string`; \}   | -                                |
+| `coordinatesInput.namespace` | `string`                                          | Host isolation namespace.        |
+| `coordinatesInput.owner`     | `string`                                          | Host owner within the namespace. |
+| `requestId`                  | `string`                                          | -                                |
+| `input`                      | [`MediaOperationRequest`](#mediaoperationrequest) | -                                |
+
+###### Returns
+
+[`MediaOperationDecision`](#mediaoperationdecision)
+
+##### claim()
+
+```ts
+claim(): 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.
+
+###### Returns
+
+`Promise`\<`Readonly`\<\{ `kind`: \| `"admitted"` \| `"succeeded"` \|
+`"interrupted"` \| `"conflict"` \| `"replayed"` \| `"claimed"` \| `"pending"`;
+`operation`: [`MediaOperationProjection`](#mediaoperationprojection);
+`leaseId?`: `string`; \}\>\>
+
+##### recordEstimate()
+
+```ts
+recordEstimate(leaseId, costMilliunits): 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;
+}>;
+```
+
+Pin the admitted price and begin the generation lease.
+
+###### Parameters
+
+| Parameter        | Type     |
+| ---------------- | -------- |
+| `leaseId`        | `string` |
+| `costMilliunits` | `number` |
+
+###### 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`; \}\>
+
+##### dispatchInBackground()
+
+```ts
+dispatchInBackground(leaseId, references): 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                                                                                                                                                                 |
+| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `leaseId`    | `string`                                                                                                                                                             |
+| `references` | 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(): Promise<void>;
+```
+
+Run a background generation once; a retried alarm never redispatches.
+
+###### Returns
+
+`Promise`\<`void`\>
+
+##### interruptGeneration()
+
+```ts
+interruptGeneration(leaseId, refusalInput?): MediaOperationProjection;
+```
+
+An aborted in-flight provider call is terminal for this request ID.
+
+###### Parameters
+
+| Parameter       | Type                      |
+| --------------- | ------------------------- |
+| `leaseId`       | `string`                  |
+| `refusalInput?` | `"safety_filter_refused"` |
+
+###### Returns
+
+[`MediaOperationProjection`](#mediaoperationprojection)
+
+##### recordGenerated()
+
+```ts
+recordGenerated(
+   leaseId,
+   bytes,
+   formatInput
+): Promise<MediaRetentionResult>;
+```
+
+Retain immutable provider output before making the save state visible.
+
+###### Parameters
+
+| Parameter     | Type         |
+| ------------- | ------------ |
+| `leaseId`     | `string`     |
+| `bytes`       | `Uint8Array` |
+| `formatInput` | `string`     |
+
+###### Returns
+
+`Promise`\<[`MediaRetentionResult`](#mediaretentionresult)\>
+
+##### readGenerated()
+
+```ts
+readGenerated(leaseId): Promise<Uint8Array<ArrayBufferLike>>;
+```
+
+Read exact retained bytes under the current save lease.
+
+###### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `leaseId` | `string` |
+
+###### Returns
+
+`Promise`\<`Uint8Array`\<`ArrayBufferLike`\>\>
+
+##### releaseWrite()
+
+```ts
+releaseWrite(leaseId): MediaOperationProjection;
+```
+
+A fixed-path exact-byte save is safe to retry without repeating generation.
+
+###### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `leaseId` | `string` |
+
+###### Returns
+
+[`MediaOperationProjection`](#mediaoperationprojection)
+
+##### recordWritten()
+
+```ts
+recordWritten(
+   leaseId,
+   receipt,
+   written
+): 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;
+}>;
+```
+
+Record a destination write and move to idempotent settlement.
+
+###### Parameters
+
+| Parameter        | Type                                         | Description             |
+| ---------------- | -------------------------------------------- | ----------------------- |
+| `leaseId`        | `string`                                     | -                       |
+| `receipt`        | `string`                                     | -                       |
+| `written`        | \{ `bytes`: `number`; `format`: `string`; \} | -                       |
+| `written.bytes`  | `number`                                     | Output byte length.     |
+| `written.format` | `string`                                     | Actual output encoding. |
+
+###### 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`; \}\>
+
+##### recordWrittenWithoutSettlement()
+
+```ts
+recordWrittenWithoutSettlement(
+   leaseId,
+   receipt,
+   written
+): 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;
+}>;
+```
+
+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             |
+| ---------------- | -------------------------------------------- | ----------------------- |
+| `leaseId`        | `string`                                     | -                       |
+| `receipt`        | `string`                                     | -                       |
+| `written`        | \{ `bytes`: `number`; `format`: `string`; \} | -                       |
+| `written.bytes`  | `number`                                     | Output byte length.     |
+| `written.format` | `string`                                     | Actual output encoding. |
+
+###### 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`; \}\>
+
+##### recordSucceeded()
+
+```ts
+recordSucceeded(leaseId, resultInput): 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;
+}>;
+```
+
+Commit the settled receipt after verifying the saved output and admitted price.
+
+###### Parameters
+
+| Parameter                    | Type                                                                                               | Description                                                     |
+| ---------------------------- | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
+| `leaseId`                    | `string`                                                                                           | -                                                               |
+| `resultInput`                | \{ `generationId`: `string`; `bytes`: `number`; `format`: `string`; `costMilliunits`: `number`; \} | -                                                               |
+| `resultInput.generationId`   | `string`                                                                                           | Durable operation identifier.                                   |
+| `resultInput.bytes`          | `number`                                                                                           | Output byte length.                                             |
+| `resultInput.format`         | `string`                                                                                           | Actual output encoding.                                         |
+| `resultInput.costMilliunits` | `number`                                                                                           | Admitted price in milliunits, where 1 cent is 1,000 milliunits. |
+
+###### 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`; \}\>
+
+##### releaseEstimate()
+
+```ts
+releaseEstimate(leaseId): MediaOperationProjection;
+```
+
+Release preparation or refused admission so the same request can retry.
+
+###### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `leaseId` | `string` |
+
+###### Returns
+
+[`MediaOperationProjection`](#mediaoperationprojection)
+
+## Type Aliases
+
+### MediaFailureStage
+
+```ts
+type MediaFailureStage = Exclude<
+  z.output<typeof mediaFailureStageSchema>,
+  "admission" | "settings"
+>;
+```
+
+Execution stage at which a generation failed.
+
+---
+
+### MediaBillingRefusalCode
+
+```ts
+type MediaBillingRefusalCode =
+  "insufficient_credits" | "daily_limit_reached" | "denied";
+```
+
+Why the host's billing owner refused to admit a new generation.
+
+---
+
+### MediaUnits
+
+```ts
+type MediaUnits = Readonly<{
+  unit: "image" | "video_second";
+  units: number;
+}>;
+```
+
+What one generation bills: whole images, or seconds of video.
+
+---
+
+### MediaMetering
+
+```ts
+type MediaMetering = Readonly<{
+  admit: (input) => Promise<
+    Readonly<{
+      priceMilliunits: number;
+    }>
+  >;
+  settle: (input) => Promise<void>;
+}>;
+```
+
+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.
+
+---
+
+### MediaOperation
+
+```ts
+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]>>>;
+};
+```
+
+Local or RPC methods consumed by a replay-safe generation.
+
+---
+
+### MediaOperationRequest
+
+```ts
+type MediaOperationRequest = MediaGenerationSettings &
+  z.output<typeof mediaOperationDestinationSchema>;
+```
+
+Normalized generation and its fixed destination, captured for exact replay.
+
+---
+
+### MediaOperationCoordinates
+
+```ts
+type MediaOperationCoordinates = z.output<
+  typeof mediaOperationCoordinatesSchema
+>;
+```
+
+Host-owned namespace and owner identity for one durable operation.
+
+---
+
+### MediaOperationState
+
+```ts
+type MediaOperationState = z.output<typeof mediaOperationStateSchema>;
+```
+
+Durable generation, save and settlement states.
+
+---
+
+### MediaImage
+
+```ts
+type MediaImage = z.output<typeof mediaImageSchema>;
+```
+
+Byte length and encoding of generated or saved output.
+
+---
+
+### MediaOperationResult
+
+```ts
+type MediaOperationResult = z.output<typeof mediaOperationResultSchema>;
+```
+
+Settled generation receipt with the host-admitted customer price.
+
+---
+
+### MediaOperationProjection
+
+```ts
+type MediaOperationProjection = Readonly<{
+  operationId: string;
+  requestId: string;
+  namespace: string;
+  owner: string;
+  state: MediaOperationState;
+  spentFailure: "output_format_mismatch" | null;
+  providerRefusal: "safety_filter_refused" | null;
+  estimatedCostMilliunits: number | null;
+  image: MediaImage | null;
+  result: MediaOperationResult | null;
+  createdAt: number;
+  updatedAt: number;
+}>;
+```
+
+The only operation shape safe to return outside the owner.
+
+---
+
+### MediaOperationDecision
+
+```ts
+type MediaOperationDecision = Readonly<{
+  kind:
+    | "admitted"
+    | "conflict"
+    | "replayed"
+    | "claimed"
+    | "pending"
+    | "succeeded"
+    | "interrupted";
+  operation: MediaOperationProjection;
+  leaseId?: string;
+}>;
+```
+
+An admission or claim decision with a safe operation projection.
+
+---
+
+### MediaErasurePreflight
+
+```ts
+type MediaErasurePreflight = Readonly<{
+  namespace: string;
+  requestId: string;
+  erased: boolean;
+}>;
+```
+
+Scoped inactivity observation made before destructive erasure.
+
+---
+
+### MediaErasureReadback
+
+```ts
+type MediaErasureReadback = Readonly<{
+  clear: boolean;
+}>;
+```
+
+Evidence that retained output, SQL and alarms were erased.
+
+---
+
+### MediaRetentionResult
+
+```ts
+type MediaRetentionResult =
+  | MediaOperationProjection
+  | Readonly<{
+      kind: "refused";
+      code: "output_format_mismatch";
+    }>;
+```
+
+Retained output projection, or a terminal spent format refusal.
+
+---
+
+### MediaOperationHooks
+
+```ts
+type MediaOperationHooks = Readonly<{
+  namespace?: () => string | null;
+}>;
+```
+
+Optional host facts that pin a namespace before operation admission.
+
+---
+
+### MediaOperationEnvironment
+
+```ts
+type MediaOperationEnvironment = Readonly<{
+  APP_ARTIFACTS: MediaOperationBucket;
+}>;
+```
+
+Retained-output storage supplied by the host.
+
+---
+
+### MediaOperationStorage
+
+```ts
+type MediaOperationStorage = object;
+```
+
+SQL rows stay untrusted until the owner decodes their stored representation.
+
+#### Properties
+
+##### sql
+
+```ts
+sql: object;
+```
+
+Native synchronous SQL interface.
+
+###### exec()
+
+```ts
+exec(query, ...bindings): object;
+```
+
+Execute a native SQL statement with positional bindings.
+
+###### Parameters
+
+| Parameter     | Type                               |
+| ------------- | ---------------------------------- |
+| `query`       | `string`                           |
+| ...`bindings` | (`string` \| `number` \| `null`)[] |
+
+###### Returns
+
+| Name        | Type                      | Description                                                |
+| ----------- | ------------------------- | ---------------------------------------------------------- |
+| `toArray()` | () => readonly `object`[] | Read the native SQL rows as objects for boundary decoding. |
+
+#### Methods
+
+##### transactionSync()
+
+```ts
+transactionSync<T>(body): T;
+```
+
+Run one atomic synchronous local mutation.
+
+###### Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `T`            |
+
+###### Parameters
+
+| Parameter | Type      |
+| --------- | --------- |
+| `body`    | () => `T` |
+
+###### Returns
+
+`T`
+
+##### isErased()
+
+```ts
+isErased(): Promise<boolean>;
+```
+
+Read the durable erasure marker.
+
+###### Returns
+
+`Promise`\<`boolean`\>
+
+##### markErased()
+
+```ts
+markErased(): Promise<void>;
+```
+
+Persist the durable erasure marker.
+
+###### Returns
+
+`Promise`\<`void`\>
+
+##### listKeys()
+
+```ts
+listKeys(): Promise<readonly string[]>;
+```
+
+List local key-value storage keys for erasure readback.
+
+###### Returns
+
+`Promise`\<readonly `string`[]\>
+
+##### deleteAlarm()
+
+```ts
+deleteAlarm(): Promise<void>;
+```
+
+Remove any scheduled background alarm.
+
+###### Returns
+
+`Promise`\<`void`\>
+
+##### deleteAll()
+
+```ts
+deleteAll(): Promise<void>;
+```
+
+Remove local SQL and key-value storage.
+
+###### Returns
+
+`Promise`\<`void`\>
+
+##### getAlarm()
+
+```ts
+getAlarm(): Promise<number | null>;
+```
+
+Read the current background alarm, or null.
+
+###### Returns
+
+`Promise`\<`number` \| `null`\>
+
+##### setAlarm()
+
+```ts
+setAlarm(timestamp): Promise<void>;
+```
+
+Schedule background generation at the given timestamp.
+
+###### Parameters
+
+| Parameter   | Type     |
+| ----------- | -------- |
+| `timestamp` | `number` |
+
+###### Returns
+
+`Promise`\<`void`\>
+
+---
+
+### MediaOperationContext
+
+```ts
+type MediaOperationContext = object;
+```
+
+The identity, serialization and storage owned by one media operation.
+
+#### Properties
+
+##### id
+
+```ts
+id: object;
+```
+
+Durable operation identity selected by the host.
+
+###### name
+
+```ts
+name: string | undefined;
+```
+
+Stable error name or durable object name.
+
+##### storage
+
+```ts
+storage: MediaOperationStorage;
+```
+
+Host-owned SQL, key-value storage and alarms.
+
+#### Methods
+
+##### blockConcurrencyWhile()
+
+```ts
+blockConcurrencyWhile<T>(body): Promise<T>;
+```
+
+Serialize asynchronous owner initialization with requests.
+
+###### Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `T`            |
+
+###### Parameters
+
+| Parameter | Type                   |
+| --------- | ---------------------- |
+| `body`    | () => `Promise`\<`T`\> |
+
+###### Returns
+
+`Promise`\<`T`\>
+
+---
+
+### MediaOperationObject
+
+```ts
+type MediaOperationObject = Readonly<{
+  key: string;
+  version: string;
+  size: number;
+  httpMetadata?: Readonly<{
+    contentType?: string;
+  }>;
+}>;
+```
+
+Object metadata consumed by retention and recovery; mirrors the native R2 fields
+used here.
+
+---
+
+### MediaOperationBucket
+
+```ts
+type MediaOperationBucket = object;
+```
+
+Exact object operations needed for immutable media outputs and references.
+
+#### Methods
+
+##### put()
+
+```ts
+put(
+   key,
+   bytes,
+   options?
+): Promise<
+  | Readonly<{
+  version: string;
+}>
+| null>;
+```
+
+Conditionally retain immutable provider bytes or background reference bytes.
+
+###### Parameters
+
+| Parameter  | Type                                                                                                                                                                                                              |
+| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `key`      | `string`                                                                                                                                                                                                          |
+| `bytes`    | `Uint8Array`                                                                                                                                                                                                      |
+| `options?` | `Readonly`\<\{ `onlyIf?`: `Readonly`\<\{ `etagDoesNotMatch`: `string`; \}\>; `httpMetadata?`: `Readonly`\<\{ `contentType`: `string`; \}\>; `customMetadata?`: `Readonly`\<`Record`\<`string`, `string`\>\>; \}\> |
+
+###### Returns
+
+`Promise`\< \| `Readonly`\<\{ `version`: `string`; \}\> \| `null`\>
+
+##### head()
+
+```ts
+head(key): Promise<
+  | Readonly<{
+  key: string;
+  version: string;
+  size: number;
+  httpMetadata?: Readonly<{
+     contentType?: string;
+  }>;
+}>
+| null>;
+```
+
+Read immutable object metadata without loading bytes.
+
+###### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `key`     | `string` |
+
+###### Returns
+
+`Promise`\< \| `Readonly`\<\{ `key`: `string`; `version`: `string`; `size`:
+`number`; `httpMetadata?`: `Readonly`\<\{ `contentType?`: `string`; \}\>; \}\>
+\| `null`\>
+
+##### get()
+
+```ts
+get(key): Promise<
+  | Omit<Readonly<{
+  key: string;
+  version: string;
+  size: number;
+  httpMetadata?: Readonly<{
+     contentType?: string;
+  }>;
+}>, "httpMetadata"> & Readonly<{
+  customMetadata?: Readonly<Record<string, string>>;
+  arrayBuffer: () => Promise<ArrayBuffer>;
+}>
+| null>;
+```
+
+Read retained object bytes and metadata.
+
+###### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `key`     | `string` |
+
+###### Returns
+
+`Promise`\< \| `Omit`\<`Readonly`\<\{ `key`: `string`; `version`: `string`;
+`size`: `number`; `httpMetadata?`: `Readonly`\<\{ `contentType?`: `string`;
+\}\>; \}\>, `"httpMetadata"`\> & `Readonly`\<\{ `customMetadata?`:
+`Readonly`\<`Record`\<`string`, `string`\>\>; `arrayBuffer`: () =>
+`Promise`\<`ArrayBuffer`\>; \}\> \| `null`\>
+
+##### delete()
+
+```ts
+delete(key): Promise<void>;
+```
+
+Delete the owner-selected object key.
+
+###### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `key`     | `string` |
+
+###### Returns
+
+`Promise`\<`void`\>
+
+---
+
+### MediaScope
+
+```ts
+type MediaScope = Readonly<{
+  actorId: string;
+  namespace: string;
+  owner: string;
+  destinationId: string;
+}>;
+```
+
+Identity supplied by the admitting host, never selected by a request body.
+
+---
+
+### MediaRefusalMessages
+
+```ts
+type MediaRefusalMessages = Readonly<Record<MediaBillingRefusalCode, string>>;
+```
+
+Customer-visible refusal text owned by a metered host.
+
+---
+
+### MediaServiceHost
+
+```ts
+type MediaServiceHost = Readonly<{
+  scope: MediaScope;
+  operations: {
+     getByName: MediaOperation;
+  };
+  provider: MediaProvider;
+  beforeAdmit?: (requestId) => Promise<void>;
+  authorizeGeneration?: () => Promise<void>;
+  destination: Readonly<{
+     authorize: (path) => Promise<void>;
+     write: (path, bytes) => Promise<void>;
+     readReference?: (reference) => Promise<MediaReferenceBytes>;
+  }>;
+  onFailure?: (error) => Response | undefined;
+}> &
+  | Readonly<{
+  metering: "unmetered";
+  refusalMessages?: never;
+}>
+  | Readonly<{
+  metering: MediaMetering;
+  refusalMessages: MediaRefusalMessages;
+}>;
+```
+
+Host authority, durable operations, provider, metering and destination access.
+
+---
+
+### MediaGenerationRequest
+
+```ts
+type MediaGenerationRequest = Readonly<{
+  requestId: string;
+  path: string;
+  settings: Parameters<typeof validateMediaGenerationSettings>[0];
+  outputFormat?: z.output<typeof mediaRequestSchema>["outputFormat"];
+}>;
+```
+
+One Media generation request, already carrying its idempotency key.
+
+---
+
+### MediaGenerationOutcome
+
+```ts
+type MediaGenerationOutcome =
+  | Readonly<{
+      kind: "succeeded";
+      path: string;
+      bytes: number;
+      costMilliunits: number;
+      format: "png" | "jpeg" | "gif" | "webp" | "mp4";
+      height: number;
+      model: string;
+      width: number;
+    }>
+  | Readonly<{
+      kind: "pending";
+      background: boolean;
+      retryAfterSeconds: number;
+    }>
+  | Readonly<{
+      kind: "conflict";
+    }>
+  | Readonly<{
+      kind: "interrupted";
+    }>
+  | Readonly<{
+      kind: "unavailable";
+    }>;
+```
+
+The typed result of one generation, shared by the Hono route and the Agent path.
+
+## Variables
+
+### mediaResultSchema
+
+```ts
+const mediaResultSchema: ZodObject<
+  {
+    bytes: ZodNumber;
+    costMilliunits: ZodNumber;
+    path: ZodString;
+    format: ZodEnum<{
+      png: "png";
+      jpeg: "jpeg";
+      gif: "gif";
+      webp: "webp";
+      mp4: "mp4";
+    }>;
+    height: ZodNumber;
+    model: ZodString;
+    width: ZodNumber;
+  },
+  $strict
+>;
+```
+
+Decode a completed generation, destination path and estimated or settled price.
+
+---
+
+### mediaOperationDestinationSchema
+
+```ts
+const mediaOperationDestinationSchema: ZodObject<
+  {
+    computerId: ZodString;
+    path: ZodString;
+    outputFormat: ZodOptional<
+      ZodEnum<{
+        png: "png";
+        jpeg: "jpeg";
+        webp: "webp";
+      }>
+    >;
+  },
+  $strict
+>;
+```
+
+Fixed generation destination captured before provider dispatch.
+
+---
+
+### mediaOperationCoordinatesSchema
+
+```ts
+const mediaOperationCoordinatesSchema: ZodObject<
+  {
+    namespace: ZodString;
+    owner: ZodString;
+  },
+  $strict
+>;
+```
+
+Decode host namespace and owner identity.
+
+---
+
+### mediaOperationStateSchema
+
+```ts
+const mediaOperationStateSchema: ZodEnum<{
+  admitted: "admitted";
+  estimating: "estimating";
+  generating: "generating";
+  writing: "writing";
+  charging: "charging";
+  written: "written";
+  succeeded: "succeeded";
+  interrupted: "interrupted";
+}>;
+```
+
+Decode durable generation, save and settlement states.
+
+---
+
+### mediaImageSchema
+
+```ts
+const mediaImageSchema: ZodObject<
+  {
+    bytes: ZodNumber;
+    format: ZodString;
+  },
+  $strict
+>;
+```
+
+Decode retained or saved output size and encoding.
+
+---
+
+### mediaOperationResultSchema
+
+```ts
+const mediaOperationResultSchema: ZodObject<
+  {
+    generationId: ZodString;
+    bytes: ZodNumber;
+    format: ZodString;
+    costMilliunits: ZodNumber;
+  },
+  $strict
+>;
+```
+
+Decode the settled receipt, including the host-admitted customer price.
+
+---
+
+### mediaRequestSchema
+
+```ts
+const mediaRequestSchema: ZodObject<{
+  path: ZodString;
+  settings: ZodObject<{
+     model: ZodString;
+     prompt: ZodString;
+     width: ZodNumber;
+     height: ZodNumber;
+     steps: ZodOptional<ZodNumber>;
+     durationSeconds: ZodOptional<ZodNumber>;
+     resolution: ZodOptional<ZodEnum<{
+        p480: "480p";
+        p720: "720p";
+        p1080: "1080p";
+        p4k: "4k";
+     }>>;
+     aspectRatio: ZodOptional<ZodEnum<{
+        wide: "16:9";
+        landscape: "4:3";
+        square: "1:1";
+        portrait: "3:4";
+        tall: "9:16";
+        ultrawide: "21:9";
+        ultratall: "9:21";
+     }>>;
+     generateAudio: ZodOptional<ZodBoolean>;
+     references: ZodOptional<ZodArray<ZodObject<{
+        computerId: ZodString;
+        path: ZodString;
+        role: ZodOptional<ZodEnum<{
+           first: ...;
+           last: ...;
+           reference: ...;
+        }>>;
+     }, $strict>>>;
+  }, $strict>;
+  outputFormat: ZodOptional<ZodEnum<{
+     png: "png";
+     jpeg: "jpeg";
+     webp: "webp";
+  }>>;
+}, $strict>;
+```
+
+Decode relative service generation input. Identity comes from the host.
+
+---
+
+### mediaPendingSchema
+
+```ts
+const mediaPendingSchema: ZodObject<
+  {
+    status: ZodLiteral<"pending">;
+    retryAfterSeconds: ZodNumber;
+  },
+  $strict
+>;
+```
+
+A background (video) generation in progress; retry the same request id.
+
+## Functions
+
+### mediaUnits()
+
+```ts
+function mediaUnits(settings): MediaUnits;
+```
+
+Billing units for validated settings; video bills its requested length.
+
+#### Parameters
+
+| Parameter  | Type                                                          |
+| ---------- | ------------------------------------------------------------- |
+| `settings` | [`MediaGenerationSettings`](index.md#mediagenerationsettings) |
+
+#### Returns
+
+[`MediaUnits`](#mediaunits)
+
+---
+
+### generateMedia()
+
+```ts
+function generateMedia(host, request, signal?): Promise<MediaGenerationOutcome>;
+```
+
+Generate through the Effect core with a Promise boundary preserving typed domain
+failures.
+
+#### Parameters
+
+| Parameter | Type                                                |
+| --------- | --------------------------------------------------- |
+| `host`    | [`MediaServiceHost`](#mediaservicehost)             |
+| `request` | [`MediaGenerationRequest`](#mediagenerationrequest) |
+| `signal?` | `AbortSignal`                                       |
+
+#### Returns
+
+`Promise`\<[`MediaGenerationOutcome`](#mediagenerationoutcome)\>
+
+---
+
+### createMediaService()
+
+```ts
+function createMediaService(host): Hono<BlankEnv, BlankSchema, "/">;
+```
+
+Relative HTTP routes; the caller admits identity and supplies destination
+access.
+
+#### Parameters
+
+| Parameter | Type                                    |
+| --------- | --------------------------------------- |
+| `host`    | [`MediaServiceHost`](#mediaservicehost) |
+
+#### Returns
+
+`Hono`\<`BlankEnv`, `BlankSchema`, `"/"`\>