@fungi.computer/oyster 0.0.0-stage → 0.1.0

package/docs/api/host.md

@@ -0,0 +1,1328 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/oyster**](README.md)
+
+---
+
+[@fungi.computer/oyster](modules.md) / host
+
+# host
+
+## Classes
+
+### ReleaseError
+
+Why a Release could not be read; the host maps it to an HTTP refusal.
+
+#### Extends
+
+- `Error`
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new ReleaseError(
+   code,
+   message,
+   options?
+): ReleaseError;
+```
+
+###### Parameters
+
+| Parameter  | Type                                                                                       |
+| ---------- | ------------------------------------------------------------------------------------------ |
+| `code`     | \| `"artifact_missing"` \| `"digest_mismatch"` \| `"invalid_release"` \| `"asset_missing"` |
+| `message`  | `string`                                                                                   |
+| `options?` | `ErrorOptions`                                                                             |
+
+###### Returns
+
+[`ReleaseError`](#releaseerror)
+
+###### Overrides
+
+```ts
+Error.constructor;
+```
+
+#### Properties
+
+##### name
+
+```ts
+readonly name: "ReleaseError" = "ReleaseError";
+```
+
+###### Overrides
+
+```ts
+Error.name;
+```
+
+##### code
+
+```ts
+readonly code:
+  | "artifact_missing"
+  | "digest_mismatch"
+  | "invalid_release"
+  | "asset_missing";
+```
+
+## Type Aliases
+
+### CapabilityMethodKind
+
+```ts
+type CapabilityMethodKind = Schema.Schema.Type<
+  typeof capabilityMethodKindSchema
+>;
+```
+
+The four supported capability method kinds.
+
+---
+
+### CapabilityDescriptor
+
+```ts
+type CapabilityDescriptor = Schema.Schema.Type<
+  typeof capabilityDescriptorSchema
+>;
+```
+
+A page descriptor carries routing, never the authority to use a capability.
+
+---
+
+### OysterVisitor
+
+```ts
+type OysterVisitor = Readonly<{
+  actor: Readonly<{
+    kind: "visitor";
+  }>;
+}>;
+```
+
+The anonymous reader of a public installation. The host admits it only when
+authentication refuses; it reaches that App's page and its `read` methods.
+
+---
+
+### OysterPrincipal
+
+```ts
+type OysterPrincipal = TenantPrincipal | OysterVisitor;
+```
+
+Who an admitted request acts for: an authenticated tenant principal or the
+visitor.
+
+---
+
+### OysterAuthResult
+
+```ts
+type OysterAuthResult =
+  | Readonly<{
+      kind: "admitted";
+      principal: TenantPrincipal;
+    }>
+  | Readonly<{
+      kind: "refused";
+      status: 401 | 403 | 404 | 429;
+      retryAfter?: number;
+    }>;
+```
+
+The outcome of authenticating one request.
+
+---
+
+### OysterAuth
+
+```ts
+type OysterAuth = Readonly<{
+  resolve: (actor) => Promise<TenantPrincipal | null>;
+  authenticate: (request) => Promise<OysterAuthResult>;
+  login?: (request) => Promise<Response>;
+}>;
+```
+
+The host's sign-in: who may use this Oyster.
+
+---
+
+### InstallationCommit
+
+```ts
+type InstallationCommit =
+  | Readonly<{
+      ok: true;
+    }>
+  | Readonly<{
+      ok: false;
+      code: "stale_authority";
+    }>;
+```
+
+A serializable registry commit result, including across native DO RPC.
+
+---
+
+### InstallationStore
+
+```ts
+type InstallationStore = InstallationReader &
+  Readonly<{
+    put: (installation) => Promise<void>;
+    compareAndPut: (
+      installation,
+      expectedAuthorityVersion,
+    ) => Promise<InstallationCommit>;
+  }>;
+```
+
+Durable commits remain with the host's registry; reads are tenant-scoped.
+
+---
+
+### OysterJson
+
+```ts
+type OysterJson = Schema.Json;
+```
+
+A JSON value crossing the method boundary.
+
+---
+
+### InstanceResult
+
+```ts
+type InstanceResult<T> =
+  | Readonly<{
+      ok: true;
+      value: T;
+    }>
+  | Readonly<{
+      ok: false;
+      code: AppInstanceErrorCode | "failed";
+      causeClass?:
+        | "Error"
+        | "TypeError"
+        | "RangeError"
+        | "SyntaxError"
+        | "AbortError"
+        | "TimeoutError"
+        | "Other";
+    }>;
+```
+
+The result of one Instance operation; refusals carry Oyster's error code.
+
+#### Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `T`            |
+
+---
+
+### InstanceHandle
+
+```ts
+type InstanceHandle = Readonly<{
+  apply: (state, release) => Promise<InstanceResult<Instance>>;
+  onGitPush: (facts, fact) => Promise<void>;
+  syncRefused: (facts, refusal) => Promise<void>;
+  authorizeGitPush: (facts, question) => Promise<GitPushVerdict>;
+  fetch: (facts, request) => Promise<Response>;
+  gill: (facts, api, source, input) => Promise<InstanceResult<GillReply>>;
+  call: (facts, api, name, input) => Promise<InstanceResult<AppMethodReply>>;
+}>;
+```
+
+One running App Instance, wherever the host runs it.
+
+---
+
+### InstanceDirectory
+
+```ts
+type InstanceDirectory = Readonly<{
+  get: (instanceId, limits?) => InstanceHandle;
+}>;
+```
+
+Finds the running Instance for an Instance ID.
+
+---
+
+### OysterMcp
+
+```ts
+type OysterMcp = Readonly<{
+  handleRequest: (request) => Promise<Response>;
+  close?: () => Promise<void>;
+}>;
+```
+
+An MCP endpoint mounted at `/mcp`.
+
+---
+
+### OysterGitHost
+
+```ts
+type OysterGitHost = Readonly<{
+  writerOf: Extract<
+    GitWriter,
+    {
+      kind: "actor";
+    }
+  >;
+  workflowPass?: Promise<Readonly<{
+    kind: "actor";
+    actor: HostActor;
+    role?: "owner" | "member";
+    workflow?: WorkflowAttestation & object;
+  }> | null>;
+  buildPass?: Promise<Readonly<{
+    kind: "actor";
+    actor: HostActor;
+    role?: "owner" | "member";
+    workflow?: WorkflowAttestation & object;
+  }> | null>;
+  git: Promise<
+    Readonly<{
+      push: Promise<
+        Readonly<{
+          status: number;
+          headers: Readonly<Record<string, string>>;
+          body: Uint8Array;
+        }>
+      >;
+      read: Promise<
+        Readonly<{
+          status: number;
+          headers: Readonly<Record<string, string>>;
+          body: Uint8Array;
+        }>
+      >;
+      binding: GitBinding;
+    }>
+  >;
+}>;
+```
+
+What Oyster's git door needs from the host beyond sign-in and Instances.
+
+---
+
+### CapabilityAdmission
+
+```ts
+type CapabilityAdmission = Readonly<{
+  principal: TenantPrincipal;
+  installation: Installation;
+}>;
+```
+
+The host's admission of one capability request: who, for which installation.
+
+---
+
+### CapabilityEnv
+
+```ts
+type CapabilityEnv = object;
+```
+
+Capability routes read the host's admission from `c.env`; they never
+authenticate.
+
+#### Properties
+
+##### Bindings
+
+```ts
+Bindings: CapabilityAdmission;
+```
+
+---
+
+### OysterCapability
+
+```ts
+type OysterCapability = Readonly<CapabilityDescriptor & object>;
+```
+
+A capability adapter whose routes require live installation admission.
+
+---
+
+### OysterVariables
+
+```ts
+type OysterVariables = object;
+```
+
+What the host stamps once per request; inner routes read it with `c.get`.
+
+#### Properties
+
+##### principal
+
+```ts
+principal: OysterPrincipal;
+```
+
+##### installation?
+
+```ts
+optional installation?: Installation;
+```
+
+---
+
+### OysterEnv
+
+```ts
+type OysterEnv = object;
+```
+
+Owner routes run after the host's owner guard and read `c.get("principal")`.
+
+#### Properties
+
+##### Variables
+
+```ts
+Variables: OysterVariables;
+```
+
+---
+
+### OysterHost
+
+```ts
+type OysterHost = Readonly<{
+  auth: OysterAuth;
+  backgroundOriginKey?: () => Promise<CryptoKey>;
+  artifacts: ArtifactStore;
+  installations: InstallationStore;
+  instances: InstanceDirectory;
+  computerId?: string;
+  computer?: (principal) => KnapsackComputer | null | Promise<KnapsackComputer | null>;
+  appToolPolicy?: (actor) =>
+     | AppToolPolicy
+     | null
+    | Promise<AppToolPolicy | null>;
+  keys?: Readonly<{
+     live: Promise<
+        | Readonly<{
+        keyId: string;
+        owner: string;
+        grantVersion: number;
+        grants: readonly Grant<...>[];
+      }>
+       | null>;
+  }>;
+  guestLimits?: Partial<GuestLimits>;
+  mcp?: OysterMcp;
+  git?: OysterGitHost;
+  ownerRoutes?: Hono<OysterEnv>;
+  capabilities?: readonly OysterCapability[];
+  workbench?: Readonly<{
+     directory: Promise<Readonly<{
+        apps: readonly AppDirectoryEntry[];
+        roles: OysterRootRoles;
+        computer?: Readonly<{
+           computerId: string;
+           name: string;
+        }>;
+     }>>;
+     storage: Pick<AppStorageWire, "read" | "write" | "reset"> & Readonly<{
+        events: Promise<Response>;
+     }>;
+  }>;
+  homeInstallationId?: string;
+  pageScript?: string;
+  title?: string;
+}>;
+```
+
+Everything a host supplies to run Oyster.
+
+---
+
+### ArtifactStore
+
+```ts
+type ArtifactStore = Readonly<{
+  get: (artifactRef) => Promise<Uint8Array | null>;
+  put: (artifactRef, bytes) => Promise<void>;
+}>;
+```
+
+Immutable Release bytes addressed by their artifact reference.
+
+---
+
+### VerifiedRelease
+
+```ts
+type VerifiedRelease = Readonly<{
+  release: Release;
+  build: AppBuild;
+  api: AppApi | null;
+  declaration: AppDeclaration | null;
+  ui:
+    | Readonly<{
+        kind: "html";
+        artifactRef: ArtifactRef;
+        digest: Sha256Digest;
+      }>
+    | Readonly<{
+        kind: "assets";
+        build: AssetBuild;
+      }>
+    | null;
+  backend: Readonly<{
+    artifactRef: ArtifactRef;
+    digest: Sha256Digest;
+  }> | null;
+}>;
+```
+
+A Release whose root, UI and backend artifacts were read and verified.
+
+## Variables
+
+### capabilityMethodKindSchema
+
+```ts
+const capabilityMethodKindSchema: Literals<
+  readonly ["json", "transport", "read", "write"]
+>;
+```
+
+How an admitted capability method is exposed to the App.
+
+---
+
+### capabilityMethodSchema
+
+```ts
+const capabilityMethodSchema: Union<
+  readonly [
+    Struct<{
+      kind: Literal<"transport">;
+      method: Literals<
+        readonly [
+          "GET",
+          "POST",
+          "PUT",
+          "DELETE",
+          "PATCH",
+          "HEAD",
+          "OPTIONS",
+          "ANY",
+        ]
+      >;
+      path: String;
+    }>,
+    Struct<{
+      kind: Literals<readonly ["json", "read", "write"]>;
+      method: Literals<
+        readonly ["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"]
+      >;
+      path: String;
+    }>,
+  ]
+>;
+```
+
+The HTTP operation exposed by one capability method on an Oyster page.
+
+---
+
+### capabilityDescriptorSchema
+
+```ts
+const capabilityDescriptorSchema: Struct<{
+  id: String;
+  version: Number;
+  base: String;
+  methods: $Record<
+    String,
+    Union<
+      readonly [
+        Struct<{
+          kind: Literal<"transport">;
+          method: Literals<
+            readonly [
+              "GET",
+              "POST",
+              "PUT",
+              "DELETE",
+              "PATCH",
+              "HEAD",
+              "OPTIONS",
+              "ANY",
+            ]
+          >;
+          path: String;
+        }>,
+        Struct<{
+          kind: Literals<readonly ["json", "read", "write"]>;
+          method: Literals<
+            readonly [
+              "GET",
+              "POST",
+              "PUT",
+              "DELETE",
+              "PATCH",
+              "HEAD",
+              "OPTIONS",
+            ]
+          >;
+          path: String;
+        }>,
+      ]
+    >
+  >;
+}>;
+```
+
+The serializable part of a capability admitted to an installation's page.
+
+---
+
+### defaultAssetPolicy
+
+```ts
+const defaultAssetPolicy: AssetBuildPolicy;
+```
+
+Default bounds for an App's UI asset build.
+
+## Functions
+
+### oysterPrincipalIsVisitor()
+
+```ts
+function oysterPrincipalIsVisitor(
+  principal,
+): principal is Readonly<{ actor: Readonly<{ kind: "visitor" }> }>;
+```
+
+Narrow an admitted principal to the anonymous public reader.
+
+#### Parameters
+
+| Parameter   | Type                                  |
+| ----------- | ------------------------------------- |
+| `principal` | [`OysterPrincipal`](#oysterprincipal) |
+
+#### Returns
+
+`principal is Readonly<{ actor: Readonly<{ kind: "visitor" }> }>`
+
+---
+
+### oysterPrincipalIsOwner()
+
+```ts
+function oysterPrincipalIsOwner(
+  principal,
+): principal is Readonly<{
+  actor: { kind: "member"; memberId: string };
+  role: "owner";
+}>;
+```
+
+True only for a member admitted with the owner role.
+
+#### Parameters
+
+| Parameter   | Type                                  |
+| ----------- | ------------------------------------- |
+| `principal` | [`OysterPrincipal`](#oysterprincipal) |
+
+#### Returns
+
+`principal is Readonly<{ actor: { kind: "member"; memberId: string }; role: "owner" }>`
+
+---
+
+### oysterPrincipalId()
+
+```ts
+function oysterPrincipalId(principal): string;
+```
+
+Stable actor identity for host storage and backend attribution.
+
+#### Parameters
+
+| Parameter   | Type                                           |
+| ----------- | ---------------------------------------------- |
+| `principal` | [`TenantPrincipal`](tenant.md#tenantprincipal) |
+
+#### Returns
+
+`string`
+
+---
+
+### installOrSelect()
+
+```ts
+function installOrSelect(
+  host,
+  installationId,
+  release,
+  principal,
+): Promise<Response>;
+```
+
+Install a Release at `installationId`, or switch an already-live one onto it:
+the one path the POST install and PUT release-select routes share, and that a
+build owner's own install call reaches too. Nothing there (or only a deleted
+installation) is a fresh install; a live installation is switched in place,
+refusing a change of the installation's App identity.
+
+#### Parameters
+
+| Parameter        | Type                                  |
+| ---------------- | ------------------------------------- |
+| `host`           | [`OysterHost`](#oysterhost)           |
+| `installationId` | `string`                              |
+| `release`        | `Release`                             |
+| `principal`      | [`OysterPrincipal`](#oysterprincipal) |
+
+#### Returns
+
+`Promise`\<`Response`\>
+
+---
+
+### createOyster()
+
+```ts
+function createOyster(host): Hono<OysterEnv>;
+```
+
+Create the Oyster App server: a Hono app that installs App Releases, serves
+their UI, forwards their backend requests and methods to their Instances, and
+mounts the host's MCP endpoint. The host's adapters decide where state lives and
+who may sign in.
+
+#### Parameters
+
+| Parameter | Type                        |
+| --------- | --------------------------- |
+| `host`    | [`OysterHost`](#oysterhost) |
+
+#### Returns
+
+`Hono`\<[`OysterEnv`](#oysterenv)\>
+
+---
+
+### sha256()
+
+```ts
+function sha256(bytes): Promise<string>;
+```
+
+Hex SHA-256 digest in Puffball's `sha256:<hex>` form.
+
+#### Parameters
+
+| Parameter | Type         |
+| --------- | ------------ |
+| `bytes`   | `Uint8Array` |
+
+#### Returns
+
+`Promise`\<`string`\>
+
+---
+
+### parseRelease()
+
+```ts
+function parseRelease(value): Release;
+```
+
+Decode an untrusted Release record, as an install request carries it.
+
+#### Parameters
+
+| Parameter | Type      |
+| --------- | --------- |
+| `value`   | `unknown` |
+
+#### Returns
+
+`Release`
+
+---
+
+### verifyRelease()
+
+```ts
+function verifyRelease(
+   store,
+   release,
+   policy?,
+   readAssets?
+): Promise<Readonly<{
+  release: Release;
+  build:   | {
+     declaration?: Readonly<{
+        api?: Readonly<{
+           methods: ...;
+           toolFamily?: ...;
+           events?: ...;
+        }>;
+        displayName?: string;
+        capabilities: readonly (
+           | "agent.list"
+           | "agent.manage"
+           | "agent.rename"
+           | "agent.toolPolicy"
+           | "agent.read"
+           | "agent.send"
+           | "computer.list"
+           | "computer.readFile"
+           | "computer.writeFile"
+           | "computer.execute"
+           | "llm.generation"
+           | "media.generation"
+           | "games:servers"
+           | "git.repository"
+           | "apps.open"
+           | "apps.call"
+           | "app.storage"
+           | "app.events.emit"
+           | "team.workbenchHost"
+           | "marketplace.browse"
+           | "marketplace.purchase"
+           | "workflow.run"
+           | "workflow.publish"
+           | "workflow.arm"
+           | "world"
+           | "channels.read"
+          | "channels.personal.manage")[];
+        calls?: readonly Readonly<...>[];
+        guidance?: string;
+        handlers: readonly "file.open"[];
+        receives?: readonly "git.push"[];
+        icon?: string;
+        roles: readonly ("dashboard" | "inbox" | "files" | "media" | "sessions" | "terminal")[];
+        storage?: readonly Readonly<...>[];
+        commands?: readonly Readonly<...>[];
+        gills?: readonly Readonly<...>[];
+        backend?: Readonly<{
+           bindings: ...;
+           sync?: ...;
+        }>;
+     }>;
+     format: "fungi-app-v1";
+     ui: {
+        mediaType: "text/html; charset=utf-8" | "application/vnd.fungi.app-assets+json";
+        artifactRef: ArtifactRef;
+        digest: Sha256Digest;
+        version: string;
+        byteLength: number;
+     };
+     backend: {
+        mediaType: "application/vnd.fungi.app-backend+json";
+        artifactRef: ArtifactRef;
+        digest: Sha256Digest;
+        version: string;
+        byteLength: number;
+     };
+   }
+     | {
+     declaration?: Readonly<{
+        api?: Readonly<{
+           methods: ...;
+           toolFamily?: ...;
+           events?: ...;
+        }>;
+        displayName?: string;
+        capabilities: readonly (
+           | "agent.list"
+           | "agent.manage"
+           | "agent.rename"
+           | "agent.toolPolicy"
+           | "agent.read"
+           | "agent.send"
+           | "computer.list"
+           | "computer.readFile"
+           | "computer.writeFile"
+           | "computer.execute"
+           | "llm.generation"
+           | "media.generation"
+           | "games:servers"
+           | "git.repository"
+           | "apps.open"
+           | "apps.call"
+           | "app.storage"
+           | "app.events.emit"
+           | "team.workbenchHost"
+           | "marketplace.browse"
+           | "marketplace.purchase"
+           | "workflow.run"
+           | "workflow.publish"
+           | "workflow.arm"
+           | "world"
+           | "channels.read"
+          | "channels.personal.manage")[];
+        calls?: readonly Readonly<...>[];
+        guidance?: string;
+        handlers: readonly "file.open"[];
+        receives?: readonly "git.push"[];
+        icon?: string;
+        roles: readonly ("dashboard" | "inbox" | "files" | "media" | "sessions" | "terminal")[];
+        storage?: readonly Readonly<...>[];
+        commands?: readonly Readonly<...>[];
+        gills?: readonly Readonly<...>[];
+        backend?: Readonly<{
+           bindings: ...;
+           sync?: ...;
+        }>;
+     }>;
+     format: "fungi-app-v1";
+     ui: {
+        mediaType: "text/html; charset=utf-8" | "application/vnd.fungi.app-assets+json";
+        artifactRef: ArtifactRef;
+        digest: Sha256Digest;
+        version: string;
+        byteLength: number;
+     };
+   }
+     | {
+     declaration?: Readonly<{
+        api?: Readonly<{
+           methods: ...;
+           toolFamily?: ...;
+           events?: ...;
+        }>;
+        displayName?: string;
+        capabilities: readonly (
+           | "agent.list"
+           | "agent.manage"
+           | "agent.rename"
+           | "agent.toolPolicy"
+           | "agent.read"
+           | "agent.send"
+           | "computer.list"
+           | "computer.readFile"
+           | "computer.writeFile"
+           | "computer.execute"
+           | "llm.generation"
+           | "media.generation"
+           | "games:servers"
+           | "git.repository"
+           | "apps.open"
+           | "apps.call"
+           | "app.storage"
+           | "app.events.emit"
+           | "team.workbenchHost"
+           | "marketplace.browse"
+           | "marketplace.purchase"
+           | "workflow.run"
+           | "workflow.publish"
+           | "workflow.arm"
+           | "world"
+           | "channels.read"
+          | "channels.personal.manage")[];
+        calls?: readonly Readonly<...>[];
+        guidance?: string;
+        handlers: readonly "file.open"[];
+        receives?: readonly "git.push"[];
+        icon?: string;
+        roles: readonly ("dashboard" | "inbox" | "files" | "media" | "sessions" | "terminal")[];
+        storage?: readonly Readonly<...>[];
+        commands?: readonly Readonly<...>[];
+        gills?: readonly Readonly<...>[];
+        backend?: Readonly<{
+           bindings: ...;
+           sync?: ...;
+        }>;
+     }>;
+     format: "fungi-app-v1";
+     backend: {
+        mediaType: "application/vnd.fungi.app-backend+json";
+        artifactRef: ArtifactRef;
+        digest: Sha256Digest;
+        version: string;
+        byteLength: number;
+     };
+   };
+  api:   | Readonly<{
+     methods: Readonly<Record<string, Readonly<{
+        description: string;
+        input: object;
+        output: object;
+        effect: ... | ... | ...;
+        requires: readonly ...;
+        pending?: ... | ...;
+        hidden?: ... | ...;
+        anonymous?: ... | ...;
+     }>>>;
+     toolFamily?: Readonly<{
+        name: string;
+        list: string;
+        call: string;
+     }>;
+     events?: Readonly<Record<string, Readonly<{
+        description: ...;
+        payload: ...;
+     }>>>;
+   }>
+     | null;
+  declaration:   | Readonly<{
+     api?: Readonly<{
+        methods: Readonly<Record<..., ...>>;
+        toolFamily?: Readonly<...>;
+        events?: Readonly<...>;
+     }>;
+     displayName?: string;
+     capabilities: readonly (
+        | "agent.list"
+        | "agent.manage"
+        | "agent.rename"
+        | "agent.toolPolicy"
+        | "agent.read"
+        | "agent.send"
+        | "computer.list"
+        | "computer.readFile"
+        | "computer.writeFile"
+        | "computer.execute"
+        | "llm.generation"
+        | "media.generation"
+        | "games:servers"
+        | "git.repository"
+        | "apps.open"
+        | "apps.call"
+        | "app.storage"
+        | "app.events.emit"
+        | "team.workbenchHost"
+        | "marketplace.browse"
+        | "marketplace.purchase"
+        | "workflow.run"
+        | "workflow.publish"
+        | "workflow.arm"
+        | "world"
+        | "channels.read"
+       | "channels.personal.manage")[];
+     calls?: readonly Readonly<{
+        appId: string;
+        methods: readonly ...[];
+     }>[];
+     guidance?: string;
+     handlers: readonly "file.open"[];
+     receives?: readonly "git.push"[];
+     icon?: string;
+     roles: readonly ("dashboard" | "inbox" | "files" | "media" | "sessions" | "terminal")[];
+     storage?: readonly Readonly<{
+        key: string;
+        scopes: readonly ...[];
+        maxBytes: number;
+     }>[];
+     commands?: readonly Readonly<{
+        id: string;
+        title: string;
+        category: string;
+        description?: ... | ...;
+        sigil?: ... | ...;
+        projections?: ... | ...;
+     }>[];
+     gills?: readonly Readonly<{
+        id: string;
+        source: string;
+        title: string;
+        params?: ... | ...;
+        watch?: ... | ...;
+        desktop?: ... | ...;
+     }>[];
+     backend?: Readonly<{
+        bindings: readonly Readonly<...>[];
+        sync?: Readonly<...>;
+     }>;
+   }>
+     | null;
+  ui:   | Readonly<{
+     kind: "html";
+     artifactRef: ArtifactRef;
+     digest: Sha256Digest;
+   }>
+     | Readonly<{
+     kind: "assets";
+     build: {
+        format: "fungi-assets-v1";
+        base: string;
+        assets: readonly object[];
+     };
+   }>
+     | null;
+  backend:   | Readonly<{
+     artifactRef: ArtifactRef;
+     digest: Sha256Digest;
+   }>
+     | null;
+}>>;
+```
+
+Read a Release root and verify every artifact it names: the UI document or asset
+build (and each asset object), and the backend descriptor.
+
+#### Parameters
+
+| Parameter                 | Type                                                                                                               | Default value        | Description                                                                                                          |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------ | -------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `store`                   | [`ArtifactStore`](#artifactstore)                                                                                  | `undefined`          | -                                                                                                                    |
+| `release`                 | `Release`                                                                                                          | `undefined`          | -                                                                                                                    |
+| `policy`                  | \{ `maxManifestBytes`: `number`; `maxObjects`: `number`; `maxObjectBytes`: `number`; `maxTotalBytes`: `number`; \} | `defaultAssetPolicy` | -                                                                                                                    |
+| `policy.maxManifestBytes` | `number`                                                                                                           | `undefined`          | -                                                                                                                    |
+| `policy.maxObjects`       | `number`                                                                                                           | `undefined`          | -                                                                                                                    |
+| `policy.maxObjectBytes`   | `number`                                                                                                           | `undefined`          | -                                                                                                                    |
+| `policy.maxTotalBytes`    | `number`                                                                                                           | `undefined`          | -                                                                                                                    |
+| `readAssets`              | `boolean`                                                                                                          | `true`               | Read and check every UI asset now. Serving can skip this: each asset is verified against its digest when it is read. |
+
+#### Returns
+
+`Promise`\<`Readonly`\<\{ `release`: `Release`; `build`: \| \{ `declaration?`:
+`Readonly`\<\{ `api?`: `Readonly`\<\{ `methods`: ...; `toolFamily?`: ...;
+`events?`: ...; \}\>; `displayName?`: `string`; `capabilities`: readonly ( \|
+`"agent.list"` \| `"agent.manage"` \| `"agent.rename"` \| `"agent.toolPolicy"`
+\| `"agent.read"` \| `"agent.send"` \| `"computer.list"` \|
+`"computer.readFile"` \| `"computer.writeFile"` \| `"computer.execute"` \|
+`"llm.generation"` \| `"media.generation"` \| `"games:servers"` \|
+`"git.repository"` \| `"apps.open"` \| `"apps.call"` \| `"app.storage"` \|
+`"app.events.emit"` \| `"team.workbenchHost"` \| `"marketplace.browse"` \|
+`"marketplace.purchase"` \| `"workflow.run"` \| `"workflow.publish"` \|
+`"workflow.arm"` \| `"world"` \| `"channels.read"` \|
+`"channels.personal.manage"`)[]; `calls?`: readonly `Readonly`\<...\>[];
+`guidance?`: `string`; `handlers`: readonly `"file.open"`[]; `receives?`:
+readonly `"git.push"`[]; `icon?`: `string`; `roles`: readonly (`"dashboard"` \|
+`"inbox"` \| `"files"` \| `"media"` \| `"sessions"` \| `"terminal"`)[];
+`storage?`: readonly `Readonly`\<...\>[]; `commands?`: readonly
+`Readonly`\<...\>[]; `gills?`: readonly `Readonly`\<...\>[]; `backend?`:
+`Readonly`\<\{ `bindings`: ...; `sync?`: ...; \}\>; \}\>; `format`:
+`"fungi-app-v1"`; `ui`: \{ `mediaType`: `"text/html; charset=utf-8"` \|
+`"application/vnd.fungi.app-assets+json"`; `artifactRef`: `ArtifactRef`;
+`digest`: `Sha256Digest`; `version`: `string`; `byteLength`: `number`; \};
+`backend`: \{ `mediaType`: `"application/vnd.fungi.app-backend+json"`;
+`artifactRef`: `ArtifactRef`; `digest`: `Sha256Digest`; `version`: `string`;
+`byteLength`: `number`; \}; \} \| \{ `declaration?`: `Readonly`\<\{ `api?`:
+`Readonly`\<\{ `methods`: ...; `toolFamily?`: ...; `events?`: ...; \}\>;
+`displayName?`: `string`; `capabilities`: readonly ( \| `"agent.list"` \|
+`"agent.manage"` \| `"agent.rename"` \| `"agent.toolPolicy"` \| `"agent.read"`
+\| `"agent.send"` \| `"computer.list"` \| `"computer.readFile"` \|
+`"computer.writeFile"` \| `"computer.execute"` \| `"llm.generation"` \|
+`"media.generation"` \| `"games:servers"` \| `"git.repository"` \| `"apps.open"`
+\| `"apps.call"` \| `"app.storage"` \| `"app.events.emit"` \|
+`"team.workbenchHost"` \| `"marketplace.browse"` \| `"marketplace.purchase"` \|
+`"workflow.run"` \| `"workflow.publish"` \| `"workflow.arm"` \| `"world"` \|
+`"channels.read"` \| `"channels.personal.manage"`)[]; `calls?`: readonly
+`Readonly`\<...\>[]; `guidance?`: `string`; `handlers`: readonly
+`"file.open"`[]; `receives?`: readonly `"git.push"`[]; `icon?`: `string`;
+`roles`: readonly (`"dashboard"` \| `"inbox"` \| `"files"` \| `"media"` \|
+`"sessions"` \| `"terminal"`)[]; `storage?`: readonly `Readonly`\<...\>[];
+`commands?`: readonly `Readonly`\<...\>[]; `gills?`: readonly
+`Readonly`\<...\>[]; `backend?`: `Readonly`\<\{ `bindings`: ...; `sync?`: ...;
+\}\>; \}\>; `format`: `"fungi-app-v1"`; `ui`: \{ `mediaType`:
+`"text/html; charset=utf-8"` \| `"application/vnd.fungi.app-assets+json"`;
+`artifactRef`: `ArtifactRef`; `digest`: `Sha256Digest`; `version`: `string`;
+`byteLength`: `number`; \}; \} \| \{ `declaration?`: `Readonly`\<\{ `api?`:
+`Readonly`\<\{ `methods`: ...; `toolFamily?`: ...; `events?`: ...; \}\>;
+`displayName?`: `string`; `capabilities`: readonly ( \| `"agent.list"` \|
+`"agent.manage"` \| `"agent.rename"` \| `"agent.toolPolicy"` \| `"agent.read"`
+\| `"agent.send"` \| `"computer.list"` \| `"computer.readFile"` \|
+`"computer.writeFile"` \| `"computer.execute"` \| `"llm.generation"` \|
+`"media.generation"` \| `"games:servers"` \| `"git.repository"` \| `"apps.open"`
+\| `"apps.call"` \| `"app.storage"` \| `"app.events.emit"` \|
+`"team.workbenchHost"` \| `"marketplace.browse"` \| `"marketplace.purchase"` \|
+`"workflow.run"` \| `"workflow.publish"` \| `"workflow.arm"` \| `"world"` \|
+`"channels.read"` \| `"channels.personal.manage"`)[]; `calls?`: readonly
+`Readonly`\<...\>[]; `guidance?`: `string`; `handlers`: readonly
+`"file.open"`[]; `receives?`: readonly `"git.push"`[]; `icon?`: `string`;
+`roles`: readonly (`"dashboard"` \| `"inbox"` \| `"files"` \| `"media"` \|
+`"sessions"` \| `"terminal"`)[]; `storage?`: readonly `Readonly`\<...\>[];
+`commands?`: readonly `Readonly`\<...\>[]; `gills?`: readonly
+`Readonly`\<...\>[]; `backend?`: `Readonly`\<\{ `bindings`: ...; `sync?`: ...;
+\}\>; \}\>; `format`: `"fungi-app-v1"`; `backend`: \{ `mediaType`:
+`"application/vnd.fungi.app-backend+json"`; `artifactRef`: `ArtifactRef`;
+`digest`: `Sha256Digest`; `version`: `string`; `byteLength`: `number`; \}; \};
+`api`: \| `Readonly`\<\{ `methods`: `Readonly`\<`Record`\<`string`,
+`Readonly`\<\{ `description`: `string`; `input`: `object`; `output`: `object`;
+`effect`: ... \| ... \| ...; `requires`: readonly ...; `pending?`: ... \| ...;
+`hidden?`: ... \| ...; `anonymous?`: ... \| ...; \}\>\>\>; `toolFamily?`:
+`Readonly`\<\{ `name`: `string`; `list`: `string`; `call`: `string`; \}\>;
+`events?`: `Readonly`\<`Record`\<`string`, `Readonly`\<\{ `description`: ...;
+`payload`: ...; \}\>\>\>; \}\> \| `null`; `declaration`: \| `Readonly`\<\{
+`api?`: `Readonly`\<\{ `methods`: `Readonly`\<`Record`\<..., ...\>\>;
+`toolFamily?`: `Readonly`\<...\>; `events?`: `Readonly`\<...\>; \}\>;
+`displayName?`: `string`; `capabilities`: readonly ( \| `"agent.list"` \|
+`"agent.manage"` \| `"agent.rename"` \| `"agent.toolPolicy"` \| `"agent.read"`
+\| `"agent.send"` \| `"computer.list"` \| `"computer.readFile"` \|
+`"computer.writeFile"` \| `"computer.execute"` \| `"llm.generation"` \|
+`"media.generation"` \| `"games:servers"` \| `"git.repository"` \| `"apps.open"`
+\| `"apps.call"` \| `"app.storage"` \| `"app.events.emit"` \|
+`"team.workbenchHost"` \| `"marketplace.browse"` \| `"marketplace.purchase"` \|
+`"workflow.run"` \| `"workflow.publish"` \| `"workflow.arm"` \| `"world"` \|
+`"channels.read"` \| `"channels.personal.manage"`)[]; `calls?`: readonly
+`Readonly`\<\{ `appId`: `string`; `methods`: readonly ...[]; \}\>[];
+`guidance?`: `string`; `handlers`: readonly `"file.open"`[]; `receives?`:
+readonly `"git.push"`[]; `icon?`: `string`; `roles`: readonly (`"dashboard"` \|
+`"inbox"` \| `"files"` \| `"media"` \| `"sessions"` \| `"terminal"`)[];
+`storage?`: readonly `Readonly`\<\{ `key`: `string`; `scopes`: readonly ...[];
+`maxBytes`: `number`; \}\>[]; `commands?`: readonly `Readonly`\<\{ `id`:
+`string`; `title`: `string`; `category`: `string`; `description?`: ... \| ...;
+`sigil?`: ... \| ...; `projections?`: ... \| ...; \}\>[]; `gills?`: readonly
+`Readonly`\<\{ `id`: `string`; `source`: `string`; `title`: `string`; `params?`:
+... \| ...; `watch?`: ... \| ...; `desktop?`: ... \| ...; \}\>[]; `backend?`:
+`Readonly`\<\{ `bindings`: readonly `Readonly`\<...\>[]; `sync?`:
+`Readonly`\<...\>; \}\>; \}\> \| `null`; `ui`: \| `Readonly`\<\{ `kind`:
+`"html"`; `artifactRef`: `ArtifactRef`; `digest`: `Sha256Digest`; \}\> \|
+`Readonly`\<\{ `kind`: `"assets"`; `build`: \{ `format`: `"fungi-assets-v1"`;
+`base`: `string`; `assets`: readonly `object`[]; \}; \}\> \| `null`; `backend`:
+\| `Readonly`\<\{ `artifactRef`: `ArtifactRef`; `digest`: `Sha256Digest`; \}\>
+\| `null`; \}\>\>
+
+---
+
+### resolveBackend()
+
+```ts
+function resolveBackend(store, release): Promise<
+  | Readonly<{
+  digest: Sha256Digest;
+  backend: DurableBackend;
+  declaration:   | Readonly<{
+     api?: Readonly<{
+        methods: Readonly<...>;
+        toolFamily?: ... | ...;
+        events?: ... | ...;
+     }>;
+     displayName?: string;
+     capabilities: readonly (
+        | "agent.list"
+        | "agent.manage"
+        | "agent.rename"
+        | "agent.toolPolicy"
+        | "agent.read"
+        | "agent.send"
+        | "computer.list"
+        | "computer.readFile"
+        | "computer.writeFile"
+        | "computer.execute"
+        | "llm.generation"
+        | "media.generation"
+        | "games:servers"
+        | "git.repository"
+        | "apps.open"
+        | "apps.call"
+        | "app.storage"
+        | "app.events.emit"
+        | "team.workbenchHost"
+        | "marketplace.browse"
+        | "marketplace.purchase"
+        | "workflow.run"
+        | "workflow.publish"
+        | "workflow.arm"
+        | "world"
+        | "channels.read"
+       | "channels.personal.manage")[];
+     calls?: readonly Readonly<{
+        appId: ...;
+        methods: ...;
+     }>[];
+     guidance?: string;
+     handlers: readonly "file.open"[];
+     receives?: readonly "git.push"[];
+     icon?: string;
+     roles: readonly ("dashboard" | "inbox" | "files" | "media" | "sessions" | "terminal")[];
+     storage?: readonly Readonly<{
+        key: ...;
+        scopes: ...;
+        maxBytes: ...;
+     }>[];
+     commands?: readonly Readonly<{
+        id: ...;
+        title: ...;
+        category: ...;
+        description?: ...;
+        sigil?: ...;
+        projections?: ...;
+     }>[];
+     gills?: readonly Readonly<{
+        id: ...;
+        source: ...;
+        title: ...;
+        params?: ...;
+        watch?: ...;
+        desktop?: ...;
+     }>[];
+     backend?: Readonly<{
+        bindings: readonly ...[];
+        sync?: ... | ...;
+     }>;
+   }>
+     | null;
+}>
+| null>;
+```
+
+Resolve a Release to its verified durable backend without reading its UI: the
+root artifact, then the backend descriptor it names.
+
+#### Parameters
+
+| Parameter | Type                              |
+| --------- | --------------------------------- |
+| `store`   | [`ArtifactStore`](#artifactstore) |
+| `release` | `Release`                         |
+
+#### Returns
+
+`Promise`\< \| `Readonly`\<\{ `digest`: `Sha256Digest`; `backend`:
+`DurableBackend`; `declaration`: \| `Readonly`\<\{ `api?`: `Readonly`\<\{
+`methods`: `Readonly`\<...\>; `toolFamily?`: ... \| ...; `events?`: ... \| ...;
+\}\>; `displayName?`: `string`; `capabilities`: readonly ( \| `"agent.list"` \|
+`"agent.manage"` \| `"agent.rename"` \| `"agent.toolPolicy"` \| `"agent.read"`
+\| `"agent.send"` \| `"computer.list"` \| `"computer.readFile"` \|
+`"computer.writeFile"` \| `"computer.execute"` \| `"llm.generation"` \|
+`"media.generation"` \| `"games:servers"` \| `"git.repository"` \| `"apps.open"`
+\| `"apps.call"` \| `"app.storage"` \| `"app.events.emit"` \|
+`"team.workbenchHost"` \| `"marketplace.browse"` \| `"marketplace.purchase"` \|
+`"workflow.run"` \| `"workflow.publish"` \| `"workflow.arm"` \| `"world"` \|
+`"channels.read"` \| `"channels.personal.manage"`)[]; `calls?`: readonly
+`Readonly`\<\{ `appId`: ...; `methods`: ...; \}\>[]; `guidance?`: `string`;
+`handlers`: readonly `"file.open"`[]; `receives?`: readonly `"git.push"`[];
+`icon?`: `string`; `roles`: readonly (`"dashboard"` \| `"inbox"` \| `"files"` \|
+`"media"` \| `"sessions"` \| `"terminal"`)[]; `storage?`: readonly
+`Readonly`\<\{ `key`: ...; `scopes`: ...; `maxBytes`: ...; \}\>[]; `commands?`:
+readonly `Readonly`\<\{ `id`: ...; `title`: ...; `category`: ...;
+`description?`: ...; `sigil?`: ...; `projections?`: ...; \}\>[]; `gills?`:
+readonly `Readonly`\<\{ `id`: ...; `source`: ...; `title`: ...; `params?`: ...;
+`watch?`: ...; `desktop?`: ...; \}\>[]; `backend?`: `Readonly`\<\{ `bindings`:
+readonly ...[]; `sync?`: ... \| ...; \}\>; \}\> \| `null`; \}\> \| `null`\>
+
+## References
+
+### GuestLimits
+
+Re-exports [GuestLimits](cloudflare.md#guestlimits)