@fungi.computer/oyster 0.0.0-stage → 0.0.1

package/docs/api/cloudflare.md

@@ -0,0 +1,421 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/oyster**](README.md)
+
+---
+
+[@fungi.computer/oyster](modules.md) / cloudflare
+
+# cloudflare
+
+## Type Aliases
+
+### FrameBindingProps
+
+```ts
+type FrameBindingProps = Readonly<{
+  instanceId: string;
+  binding: AppBackendBindingName;
+  frameId: string;
+}>;
+```
+
+Host-minted caller-frame routing props; never supplied by the App.
+
+---
+
+### FrameBindingMethod
+
+```ts
+type FrameBindingMethod<Result> = Readonly<{
+  decodeArgs: (raw) => readonly unknown[];
+  decodeResult: z.ZodType<Result>["parse"];
+  requiredOperations: (args) => readonly string[];
+}>;
+```
+
+The host's maintained positional argument/result codecs and operation policy.
+
+#### Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `Result`       |
+
+---
+
+### FrameBindingMethods
+
+```ts
+type FrameBindingMethods<Result> = Readonly<
+  Partial<
+    Record<
+      AppBackendBindingName,
+      Readonly<Record<string, FrameBindingMethod<Result>>>
+    >
+  >
+>;
+```
+
+Method descriptors for the closed App binding vocabulary.
+
+#### Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `Result`       |
+
+---
+
+### AppFacetStub
+
+```ts
+type AppFacetStub = Readonly<{
+  fetch: (request) => Promise<Response>;
+}>;
+```
+
+Native facet handle; method RPCs are decoded at the invocation boundary.
+
+---
+
+### AppInstanceContext
+
+```ts
+type AppInstanceContext<FacetClass> = Readonly<{
+  id: Readonly<{
+    name?: string;
+  }>;
+  storage: WatchdogSqliteOwner;
+  facets: Readonly<{
+    get: (name, prepare) => AppFacetStub;
+    abort: (name, reason) => void;
+    delete: (name) => void;
+  }>;
+}>;
+```
+
+Only the native storage and facet capabilities used by an App Instance.
+`FacetClass` is the host's Durable Object class type (`DurableObjectClass` on
+workerd, celld and Cloudflare); Oyster passes it through unopened.
+
+#### Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `FacetClass`   |
+
+---
+
+### AppWorkerCode
+
+```ts
+type AppWorkerCode = Readonly<{
+  compatibilityDate: string;
+  mainModule: string;
+  modules: Readonly<Record<string, string>>;
+  env: object;
+  globalOutbound: null;
+  limits: GuestLimits;
+}>;
+```
+
+The module set the Worker Loader runs for one App backend.
+
+---
+
+### AppInstanceLoader
+
+```ts
+type AppInstanceLoader<FacetClass> = Readonly<{
+  get: (
+    id,
+    configure,
+  ) => Readonly<{
+    getDurableObjectClass: (exportName) => FacetClass;
+  }>;
+}>;
+```
+
+Loader memoization and class lookup; entrypoint access is not required.
+
+#### Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `FacetClass`   |
+
+---
+
+### FrameBindingReply
+
+```ts
+type FrameBindingReply<Value> =
+  | Readonly<{
+      kind: "result";
+      value: Value;
+    }>
+  | Readonly<{
+      kind: "local_refusal";
+      code: AppInstanceErrorCode;
+    }>;
+```
+
+Private RPC envelope. Domain results, including domain refusals, stay inside
+value.
+
+#### Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `Value`        |
+
+---
+
+### FrameBindingWire
+
+```ts
+type FrameBindingWire<Methods> = {
+  [Name in keyof Methods]: Methods[Name] extends (
+    args: infer Args,
+  ) => Promise<infer Value>
+    ? (args: Args) => Promise<FrameBindingReply<Value>>
+    : never;
+};
+```
+
+Native entrypoint methods carry the envelope; guest interfaces are restored by
+wrap.
+
+#### Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `Methods`      |
+
+---
+
+### GuestLimits
+
+```ts
+type GuestLimits = Readonly<{
+  cpuMs: number;
+  subRequests: number;
+}>;
+```
+
+Per-invocation budgets enforced by the guest Worker Loader, including facets.
+
+## Variables
+
+### MAX\_APP\_REPLY\_BYTES
+
+```ts
+const MAX_APP_REPLY_BYTES: number;
+```
+
+Retained shard reply ceiling; replies settle before the frame aborts its facet.
+
+---
+
+### backgroundFrameMethods
+
+```ts
+const backgroundFrameMethods: object;
+```
+
+Shared replay-only port codecs. Origin input is verified by the host and fails
+with a typed refusal.
+
+#### Type Declaration
+
+| Name                                          | Type                                                                                                | Description                                                                    |
+| --------------------------------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| <a id="property-background"></a> `BACKGROUND` | `object`                                                                                            | -                                                                              |
+| `BACKGROUND.admit`                            | `object`                                                                                            | -                                                                              |
+| `BACKGROUND.admit.decodeArgs()`               | (`raw`) => \[`unknown`\] \| `undefined`[]                                                           | Malformed arity supplies invalid origin evidence for the host's typed refusal. |
+| `BACKGROUND.admit.decodeResult()`             | (`raw`) => \| \{ `kind`: `"admitted"`; \} \| \{ `kind`: `"refused"`; `code`: `"access_changed"`; \} | Preserve the host's closed admitted/refused result.                            |
+| `BACKGROUND.admit.requiredOperations()`       | () => `string`[]                                                                                    | Only the host-minted replay grant supplies this operation.                     |
+
+---
+
+### frameBindingPropsSchema
+
+```ts
+const frameBindingPropsSchema: Struct<{
+  instanceId: Codec<InstanceId, string, never, never>;
+  frameId: String;
+  binding: refine<
+    | "BACKGROUND"
+    | "GIT"
+    | "EVENTS"
+    | "APPS"
+    | "WORKFLOWS"
+    | "APP_STORAGE"
+    | "MEDIA"
+    | "COMPUTER"
+    | "INBOX"
+    | "AGENTS",
+    String
+  >;
+}>;
+```
+
+The shared RPC boundary decoder for host-minted invocation binding props.
+
+## Functions
+
+### captureFrameBindingReply()
+
+```ts
+function captureFrameBindingReply<Value>(
+  run,
+): Promise<FrameBindingReply<Value>>;
+```
+
+Encode supervisor refusals before native RPC can discard Error properties.
+
+#### Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `Value`        |
+
+#### Parameters
+
+| Parameter | Type                       |
+| --------- | -------------------------- |
+| `run`     | () => `Promise`\<`Value`\> |
+
+#### Returns
+
+`Promise`\<[`FrameBindingReply`](#framebindingreply)\<`Value`\>\>
+
+---
+
+### decodeFrameBindingProps()
+
+```ts
+function decodeFrameBindingProps(raw): FrameBindingProps;
+```
+
+Decode a host routing packet or refuse it before any Instance lookup.
+
+#### Parameters
+
+| Parameter | Type      |
+| --------- | --------- |
+| `raw`     | `unknown` |
+
+#### Returns
+
+[`FrameBindingProps`](#framebindingprops)
+
+---
+
+### frameBindingEntrypoint()
+
+```ts
+function frameBindingEntrypoint<Env, Result>(
+  methods,
+  dispatch,
+): typeof WorkerEntrypoint;
+```
+
+One native binding factory for both Hub and standalone, preserving RPC values.
+
+#### Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `Env`          |
+| `Result`       |
+
+#### Parameters
+
+| Parameter  | Type                                                                                                      |
+| ---------- | --------------------------------------------------------------------------------------------------------- |
+| `methods`  | [`FrameBindingMethods`](#framebindingmethods)\<`Result`\>                                                 |
+| `dispatch` | (`env`, `props`, `method`, `args`) => `Promise`\<[`FrameBindingReply`](#framebindingreply)\<`unknown`\>\> |
+
+#### Returns
+
+_typeof_ `WorkerEntrypoint`
+
+---
+
+### createCloudflareInvocationGate()
+
+```ts
+function createCloudflareInvocationGate<Host, FacetClass>(
+  ctx,
+  close,
+): InvocationGate<Host>;
+```
+
+End the native App facet before shared frame admission releases its permit.
+
+#### Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `Host`         |
+| `FacetClass`   |
+
+#### Parameters
+
+| Parameter | Type                                                                              |
+| --------- | --------------------------------------------------------------------------------- |
+| `ctx`     | `Pick`\<[`AppInstanceContext`](#appinstancecontext)\<`FacetClass`\>, `"facets"`\> |
+| `close`   | (`frame`) => `Promise`\<`void`\>                                                  |
+
+#### Returns
+
+[`InvocationGate`](invocation.md#invocationgate)\<`Host`\>
+
+---
+
+### createCloudflareAppInstance()
+
+```ts
+function createCloudflareAppInstance<FacetClass, Host>(
+  ctx,
+  loader,
+  resolve,
+  guestEnv,
+  limits?,
+): AppInstance<Host>;
+```
+
+Run an App Instance inside a SQLite-backed Durable Object on workerd, celld or
+Cloudflare. Supervisor state lives in the Durable Object's own SQLite; the App
+backend runs in a named `app` facet loaded through the Worker Loader, so its
+database survives Release replacement and stays separate from the supervisor.
+Guest code gets only host gatekeeper bindings and no ambient outbound access.
+
+#### Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `FacetClass`   |
+| `Host`         |
+
+#### Parameters
+
+| Parameter  | Type                                                                                                                                              | Description                                                             |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| `ctx`      | [`AppInstanceContext`](#appinstancecontext)\<`FacetClass`\>                                                                                       | The Durable Object's name, storage and facets.                          |
+| `loader`   | \| `Readonly`\<\{ `get`: (`id`, `configure`) => `Readonly`\<\{ `getDurableObjectClass`: (`exportName`) => `FacetClass`; \}\>; \}\> \| `undefined` | The Worker Loader binding; without it backend execution is unavailable. |
+| `resolve`  | (`release`, `scope`) => `Effect`\<`Readonly`\<\{ `release`: `Release`; `digest`: `Sha256Digest`; `backend`: `DurableBackend`; \}\>, `Error`\>     | Resolves a Release ID to its verified durable backend.                  |
+| `guestEnv` | (`frame`) => `object`                                                                                                                             | Mints loopbacks bound to the captured invocation frame.                 |
+| `limits?`  | `Partial`\<`Readonly`\<\{ `cpuMs`: `number`; `subRequests`: `number`; \}\>\>                                                                      | Guest CPU and subrequest budgets; omitted fields use safe defaults.     |
+
+#### Returns
+
+[`AppInstance`](index.md#appinstance)\<`Host`\>
+
+## References
+
+### BackgroundFrameState
+
+Re-exports [BackgroundFrameState](invocation.md#backgroundframestate)

package/docs/api/computer.md

@@ -0,0 +1,203 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/oyster**](README.md)
+
+---
+
+[@fungi.computer/oyster](modules.md) / computer
+
+# computer
+
+## Type Aliases
+
+### ComputerTerminalSelection
+
+```ts
+type ComputerTerminalSelection = Readonly<{
+  computerId: string | null;
+  terminalUrl: string | null;
+}>;
+```
+
+Current host admission for the Computer captured when the terminal opened.
+
+---
+
+### ComputerTerminalAccess
+
+```ts
+type ComputerTerminalAccess = (
+  signal,
+) => Promise<ComputerTerminalSelection> & object;
+```
+
+Host admission on connection and lease renewal; unleased input rechecks it.
+
+#### Type Declaration
+
+| Name                | Type                     | Description                                                     |
+| ------------------- | ------------------------ | --------------------------------------------------------------- |
+| `leaseExpiresAt()?` | () => `number` \| `null` | Current admission deadline, when the host uses expiring leases. |
+
+---
+
+### ComputerTerminalConnect
+
+```ts
+type ComputerTerminalConnect = (terminalUrl, input) => WebSocket;
+```
+
+Host transport construction; the shared protocol owns PTY session identity.
+
+#### Parameters
+
+| Parameter     | Type                                                              |
+| ------------- | ----------------------------------------------------------------- |
+| `terminalUrl` | `string`                                                          |
+| `input`       | `ComputerTerminalSize` & `Readonly`\<\{ `session`: `string`; \}\> |
+
+#### Returns
+
+`WebSocket`
+
+---
+
+### ComputerTerminalHostOptions
+
+```ts
+type ComputerTerminalHostOptions = Readonly<{
+  terminalUrl: string;
+  computerId: string | null;
+  hostWindow: Readonly<{
+    setTimeout: (callback, delayMs) => number;
+    clearTimeout: (timer) => void;
+  }>;
+  ensureAccess: ComputerTerminalAccess;
+  connect: ComputerTerminalConnect;
+  mountSignal: AbortSignal | undefined;
+}>;
+```
+
+Host policy and browser lifetime surrounding the retained PTY protocol.
+
+---
+
+### ComputerTerminalHost
+
+```ts
+type ComputerTerminalHost = object;
+```
+
+Terminal operations and lifetime for one admitted App window.
+
+#### Methods
+
+##### open()
+
+```ts
+open(size): Promise<AppComputerTerminal>;
+```
+
+Open an admitted PTY and retain its session across transport reconnects.
+
+###### Parameters
+
+| Parameter | Type                   |
+| --------- | ---------------------- |
+| `size`    | `ComputerTerminalSize` |
+
+###### Returns
+
+`Promise`\<`AppComputerTerminal`\>
+
+##### \[dispose\]()
+
+```ts
+dispose: void;
+```
+
+Close every terminal when the App window's host lifetime ends.
+
+###### Returns
+
+`void`
+
+## Variables
+
+### ComputerTerminalHost
+
+```ts
+ComputerTerminalHost: (options) => ComputerTerminalHost;
+```
+
+Construct the shared terminal owner with host policy and transport edges.
+
+Construct the shared terminal owner with host policy and transport edges.
+
+#### Parameters
+
+| Parameter | Type                                                          |
+| --------- | ------------------------------------------------------------- |
+| `options` | [`ComputerTerminalHostOptions`](#computerterminalhostoptions) |
+
+#### Returns
+
+[`ComputerTerminalHost`](#computerterminalhost-1)
+
+---
+
+### computerSlots
+
+```ts
+const computerSlots: object;
+```
+
+Computer routes supplied by the host; execution stays in the Computer runtime.
+
+#### Type Declaration
+
+| Name                                        | Type                | Default value               |
+| ------------------------------------------- | ------------------- | --------------------------- |
+| <a id="property-ports"></a> `ports`         | `object`            | -                           |
+| `ports.id`                                  | `string`            | `computerPorts.id`          |
+| `ports.version`                             | `number`            | `computerPorts.version`     |
+| `ports.base`                                | `"/computer/"`      | `"/computer/"`              |
+| `ports.methods`                             | `object`            | -                           |
+| `ports.methods.list`                        | `object`            | -                           |
+| `ports.methods.list.kind`                   | `"json"`            | `"json"`                    |
+| `ports.methods.list.method`                 | `"GET"`             | `"GET"`                     |
+| `ports.methods.list.path`                   | `"ports"`           | `"ports"`                   |
+| `ports.methods.expose`                      | `object`            | -                           |
+| `ports.methods.expose.kind`                 | `"json"`            | `"json"`                    |
+| `ports.methods.expose.method`               | `"POST"`            | `"POST"`                    |
+| `ports.methods.expose.path`                 | `"ports/expose"`    | `"ports/expose"`            |
+| `ports.methods.unexpose`                    | `object`            | -                           |
+| `ports.methods.unexpose.kind`               | `"json"`            | `"json"`                    |
+| `ports.methods.unexpose.method`             | `"POST"`            | `"POST"`                    |
+| `ports.methods.unexpose.path`               | `"ports/unexpose"`  | `"ports/unexpose"`          |
+| <a id="property-processes"></a> `processes` | `object`            | -                           |
+| `processes.id`                              | `string`            | `computerProcesses.id`      |
+| `processes.version`                         | `number`            | `computerProcesses.version` |
+| `processes.base`                            | `"/computer/"`      | `"/computer/"`              |
+| `processes.methods`                         | `object`            | -                           |
+| `processes.methods.start`                   | `object`            | -                           |
+| `processes.methods.start.kind`              | `"json"`            | `"json"`                    |
+| `processes.methods.start.method`            | `"POST"`            | `"POST"`                    |
+| `processes.methods.start.path`              | `"processes/start"` | `"processes/start"`         |
+| `processes.methods.list`                    | `object`            | -                           |
+| `processes.methods.list.kind`               | `"json"`            | `"json"`                    |
+| `processes.methods.list.method`             | `"GET"`             | `"GET"`                     |
+| `processes.methods.list.path`               | `"processes"`       | `"processes"`               |
+| `processes.methods.kill`                    | `object`            | -                           |
+| `processes.methods.kill.kind`               | `"json"`            | `"json"`                    |
+| `processes.methods.kill.method`             | `"POST"`            | `"POST"`                    |
+| `processes.methods.kill.path`               | `"processes/kill"`  | `"processes/kill"`          |
+| <a id="property-terminal"></a> `terminal`   | `object`            | -                           |
+| `terminal.id`                               | `string`            | `computerTerminal.id`       |
+| `terminal.version`                          | `number`            | `computerTerminal.version`  |
+| `terminal.base`                             | `"/computer/"`      | `"/computer/"`              |
+| `terminal.methods`                          | `object`            | -                           |
+| `terminal.methods.open`                     | `object`            | -                           |
+| `terminal.methods.open.kind`                | `"transport"`       | `"transport"`               |
+| `terminal.methods.open.method`              | `"GET"`             | `"GET"`                     |
+| `terminal.methods.open.path`                | `"terminal"`        | `"terminal"`                |