@fungi.computer/mycelium 0.0.0-stage → 0.0.2

package/docs/api/sandbox-failure.md

@@ -0,0 +1,1133 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/mycelium**](README.md)
+
+---
+
+[@fungi.computer/mycelium](README.md) / sandbox-failure
+
+# sandbox-failure
+
+## Classes
+
+### SourceInvalid
+
+A location in the submitted program, never in the host's source.
+
+#### Extends
+
+- `YieldableError`\<`this`\> & `object` &
+  `Readonly`\<[`SandboxFailureReference`](#sandboxfailurereference) & `object`\>
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new SourceInvalid(args): SourceInvalid;
+```
+
+###### Parameters
+
+| Parameter      | Type                                                                               |
+| -------------- | ---------------------------------------------------------------------------------- |
+| `args`         | \{ `ref?`: `string`; `line`: `number`; `column`: `number`; `excerpt`: `string`; \} |
+| `args.ref?`    | `string`                                                                           |
+| `args.line`    | `number`                                                                           |
+| `args.column`  | `number`                                                                           |
+| `args.excerpt` | `string`                                                                           |
+
+###### Returns
+
+[`SourceInvalid`](#sourceinvalid)
+
+###### Inherited from
+
+```ts
+Data.TaggedError("SourceInvalid")<
+  SandboxFailureReference & {
+    readonly line: number;
+    readonly column: number;
+    readonly excerpt: string;
+  }
+>.constructor
+```
+
+#### Properties
+
+##### ref?
+
+```ts
+readonly optional ref?: string;
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("SourceInvalid").ref;
+```
+
+##### line
+
+```ts
+readonly line: number;
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("SourceInvalid").line;
+```
+
+##### column
+
+```ts
+readonly column: number;
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("SourceInvalid").column;
+```
+
+##### excerpt
+
+```ts
+readonly excerpt: string;
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("SourceInvalid").excerpt;
+```
+
+---
+
+### GuestThrew
+
+Text captured inside the guest's own exception handler.
+
+#### Extends
+
+- `YieldableError`\<`this`\> & `object` &
+  `Readonly`\<[`SandboxFailureReference`](#sandboxfailurereference) & `object`\>
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new GuestThrew(args): GuestThrew;
+```
+
+###### Parameters
+
+| Parameter                | Type                                                                                                                        | Description                                                                      |
+| ------------------------ | --------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `args`                   | \{ `ref?`: `string`; `name`: `string`; `message`: `string`; `missingVariable?`: `string`; `transportMessage?`: `string`; \} | -                                                                                |
+| `args.ref?`              | `string`                                                                                                                    | -                                                                                |
+| `args.name`              | `string`                                                                                                                    | -                                                                                |
+| `args.message`           | `string`                                                                                                                    | -                                                                                |
+| `args.missingVariable?`  | `string`                                                                                                                    | -                                                                                |
+| `args.transportMessage?` | `string`                                                                                                                    | Safe provider envelope carried in the guest exception's cause, never model text. |
+
+###### Returns
+
+[`GuestThrew`](#guestthrew)
+
+###### Inherited from
+
+```ts
+Data.TaggedError("GuestThrew")<
+  SandboxFailureReference & {
+    readonly name: string;
+    readonly message: string;
+    readonly missingVariable?: string | undefined;
+    / Safe provider envelope carried in the guest exception's cause, never model text. /
+    readonly transportMessage?: string | undefined;
+  }
+>.constructor
+```
+
+#### Properties
+
+##### ref?
+
+```ts
+readonly optional ref?: string;
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("GuestThrew").ref;
+```
+
+##### missingVariable?
+
+```ts
+readonly optional missingVariable?: string;
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("GuestThrew").missingVariable;
+```
+
+##### transportMessage?
+
+```ts
+readonly optional transportMessage?: string;
+```
+
+Safe provider envelope carried in the guest exception's cause, never model text.
+
+###### Inherited from
+
+```ts
+Data.TaggedError("GuestThrew").transportMessage;
+```
+
+##### name
+
+```ts
+name: string;
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("GuestThrew").name;
+```
+
+##### message
+
+```ts
+message: string;
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("GuestThrew").message;
+```
+
+---
+
+### DeadlineExceeded
+
+The invocation owner decided its execution budget was spent.
+
+#### Extends
+
+- `YieldableError`\<`this`\> & `object` &
+  `Readonly`\<[`SandboxFailureReference`](#sandboxfailurereference) & `object`\>
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new DeadlineExceeded(args): DeadlineExceeded;
+```
+
+###### Parameters
+
+| Parameter            | Type                                                                                            |
+| -------------------- | ----------------------------------------------------------------------------------------------- |
+| `args`               | \{ `ref?`: `string`; `limitMs`: `number`; `elapsedMs`: `number`; `acknowledged?`: `boolean`; \} |
+| `args.ref?`          | `string`                                                                                        |
+| `args.limitMs`       | `number`                                                                                        |
+| `args.elapsedMs`     | `number`                                                                                        |
+| `args.acknowledged?` | `boolean`                                                                                       |
+
+###### Returns
+
+[`DeadlineExceeded`](#deadlineexceeded)
+
+###### Inherited from
+
+```ts
+Data.TaggedError("DeadlineExceeded")<
+  SandboxFailureReference & {
+    readonly limitMs: number;
+    readonly elapsedMs: number;
+    readonly acknowledged?: boolean | undefined;
+  }
+>.constructor
+```
+
+#### Properties
+
+##### ref?
+
+```ts
+readonly optional ref?: string;
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("DeadlineExceeded").ref;
+```
+
+##### limitMs
+
+```ts
+readonly limitMs: number;
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("DeadlineExceeded").limitMs;
+```
+
+##### elapsedMs
+
+```ts
+readonly elapsedMs: number;
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("DeadlineExceeded").elapsedMs;
+```
+
+##### acknowledged?
+
+```ts
+readonly optional acknowledged?: boolean;
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("DeadlineExceeded").acknowledged;
+```
+
+---
+
+### Cancelled
+
+The invocation owner accepted cancellation.
+
+#### Extends
+
+- `YieldableError`\<`this`\> & `object` &
+  `Readonly`\<[`SandboxFailureReference`](#sandboxfailurereference) & `object`\>
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new Cancelled(args): Cancelled;
+```
+
+###### Parameters
+
+| Parameter            | Type                                                                                  |
+| -------------------- | ------------------------------------------------------------------------------------- |
+| `args`               | \{ `ref?`: `string`; `by`: `"caller"` \| `"operator"`; `acknowledged?`: `boolean`; \} |
+| `args.ref?`          | `string`                                                                              |
+| `args.by`            | `"caller"` \| `"operator"`                                                            |
+| `args.acknowledged?` | `boolean`                                                                             |
+
+###### Returns
+
+[`Cancelled`](#cancelled)
+
+###### Inherited from
+
+```ts
+Data.TaggedError("Cancelled")<
+  SandboxFailureReference & {
+    readonly by: "caller" | "operator";
+    readonly acknowledged?: boolean | undefined;
+  }
+>.constructor
+```
+
+#### Properties
+
+##### ref?
+
+```ts
+readonly optional ref?: string;
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("Cancelled").ref;
+```
+
+##### by
+
+```ts
+readonly by: "caller" | "operator";
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("Cancelled").by;
+```
+
+##### acknowledged?
+
+```ts
+readonly optional acknowledged?: boolean;
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("Cancelled").acknowledged;
+```
+
+---
+
+### DispatchLost
+
+Dispatch started, but its transport did not deliver an answer.
+
+#### Extends
+
+- `YieldableError`\<`this`\> & `object` &
+  `Readonly`\<[`SandboxFailureReference`](#sandboxfailurereference) & `object`\>
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new DispatchLost(args): DispatchLost;
+```
+
+###### Parameters
+
+| Parameter        | Type                                                                                                             |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `args`           | \{ `ref?`: `string`; `elapsedMs`: `number`; `transport`: `string`; `errno?`: `string`; `rawCause`: `unknown`; \} |
+| `args.ref?`      | `string`                                                                                                         |
+| `args.elapsedMs` | `number`                                                                                                         |
+| `args.transport` | `string`                                                                                                         |
+| `args.errno?`    | `string`                                                                                                         |
+| `args.rawCause`  | `unknown`                                                                                                        |
+
+###### Returns
+
+[`DispatchLost`](#dispatchlost)
+
+###### Inherited from
+
+```ts
+Data.TaggedError("DispatchLost")<
+  SandboxFailureReference & {
+    readonly elapsedMs: number;
+    readonly transport: string;
+    readonly errno?: string | undefined;
+    readonly rawCause: unknown;
+  }
+>.constructor
+```
+
+#### Properties
+
+##### ref?
+
+```ts
+readonly optional ref?: string;
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("DispatchLost").ref;
+```
+
+##### elapsedMs
+
+```ts
+readonly elapsedMs: number;
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("DispatchLost").elapsedMs;
+```
+
+##### transport
+
+```ts
+readonly transport: string;
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("DispatchLost").transport;
+```
+
+##### errno?
+
+```ts
+readonly optional errno?: string;
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("DispatchLost").errno;
+```
+
+##### rawCause
+
+```ts
+readonly rawCause: unknown;
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("DispatchLost").rawCause;
+```
+
+---
+
+### SandboxCrashed
+
+The sandbox process could not start or stopped before answering.
+
+#### Extends
+
+- `YieldableError`\<`this`\> & `object` &
+  `Readonly`\<[`SandboxFailureReference`](#sandboxfailurereference) & `object`\>
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new SandboxCrashed(args): SandboxCrashed;
+```
+
+###### Parameters
+
+| Parameter       | Type                                                                                  |
+| --------------- | ------------------------------------------------------------------------------------- |
+| `args`          | \{ `ref?`: `string`; `exit?`: `number`; `errno?`: `string`; `rawCause`: `unknown`; \} |
+| `args.ref?`     | `string`                                                                              |
+| `args.exit?`    | `number`                                                                              |
+| `args.errno?`   | `string`                                                                              |
+| `args.rawCause` | `unknown`                                                                             |
+
+###### Returns
+
+[`SandboxCrashed`](#sandboxcrashed)
+
+###### Inherited from
+
+```ts
+Data.TaggedError("SandboxCrashed")<
+  SandboxFailureReference & {
+    readonly exit?: number | undefined;
+    readonly errno?: string | undefined;
+    readonly rawCause: unknown;
+  }
+>.constructor
+```
+
+#### Properties
+
+##### ref?
+
+```ts
+readonly optional ref?: string;
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("SandboxCrashed").ref;
+```
+
+##### exit?
+
+```ts
+readonly optional exit?: number;
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("SandboxCrashed").exit;
+```
+
+##### errno?
+
+```ts
+readonly optional errno?: string;
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("SandboxCrashed").errno;
+```
+
+##### rawCause
+
+```ts
+readonly rawCause: unknown;
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("SandboxCrashed").rawCause;
+```
+
+---
+
+### BadResponse
+
+A received envelope could not be decoded. Its reason is operator only.
+
+#### Extends
+
+- `YieldableError`\<`this`\> & `object` &
+  `Readonly`\<[`SandboxFailureReference`](#sandboxfailurereference) & `object`\>
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new BadResponse(args): BadResponse;
+```
+
+###### Parameters
+
+| Parameter       | Type                                                               |
+| --------------- | ------------------------------------------------------------------ |
+| `args`          | \{ `ref?`: `string`; `reason`: `string`; `rawCause`: `unknown`; \} |
+| `args.ref?`     | `string`                                                           |
+| `args.reason`   | `string`                                                           |
+| `args.rawCause` | `unknown`                                                          |
+
+###### Returns
+
+[`BadResponse`](#badresponse)
+
+###### Inherited from
+
+```ts
+Data.TaggedError("BadResponse")<
+  SandboxFailureReference & {
+    readonly reason: string;
+    readonly rawCause: unknown;
+  }
+>.constructor
+```
+
+#### Properties
+
+##### ref?
+
+```ts
+readonly optional ref?: string;
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("BadResponse").ref;
+```
+
+##### reason
+
+```ts
+readonly reason: string;
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("BadResponse").reason;
+```
+
+##### rawCause
+
+```ts
+readonly rawCause: unknown;
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("BadResponse").rawCause;
+```
+
+---
+
+### ResultTooLarge
+
+A JSON result exceeded Mycelium's output budget.
+
+#### Extends
+
+- `YieldableError`\<`this`\> & `object` &
+  `Readonly`\<[`SandboxFailureReference`](#sandboxfailurereference) & `object`\>
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new ResultTooLarge(args): ResultTooLarge;
+```
+
+###### Parameters
+
+| Parameter   | Type                                      |
+| ----------- | ----------------------------------------- |
+| `args`      | \{ `ref?`: `string`; `size`: `number`; \} |
+| `args.ref?` | `string`                                  |
+| `args.size` | `number`                                  |
+
+###### Returns
+
+[`ResultTooLarge`](#resulttoolarge)
+
+###### Inherited from
+
+```ts
+Data.TaggedError("ResultTooLarge")<
+  SandboxFailureReference & {
+    readonly size: number;
+  }
+>.constructor
+```
+
+#### Properties
+
+##### ref?
+
+```ts
+readonly optional ref?: string;
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("ResultTooLarge").ref;
+```
+
+##### size
+
+```ts
+readonly size: number;
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("ResultTooLarge").size;
+```
+
+---
+
+### ResultNotJson
+
+A result could not be represented as JSON.
+
+#### Extends
+
+- `YieldableError`\<`this`\> & `object` &
+  `Readonly`\<[`SandboxFailureReference`](#sandboxfailurereference) & `object`\>
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new ResultNotJson(args): ResultNotJson;
+```
+
+###### Parameters
+
+| Parameter        | Type                                                              |
+| ---------------- | ----------------------------------------------------------------- |
+| `args`           | \{ `ref?`: `string`; `kind`: `string`; `rawCause?`: `unknown`; \} |
+| `args.ref?`      | `string`                                                          |
+| `args.kind`      | `string`                                                          |
+| `args.rawCause?` | `unknown`                                                         |
+
+###### Returns
+
+[`ResultNotJson`](#resultnotjson)
+
+###### Inherited from
+
+```ts
+Data.TaggedError("ResultNotJson")<
+  SandboxFailureReference & {
+    readonly kind: string;
+    readonly rawCause?: unknown;
+  }
+>.constructor
+```
+
+#### Properties
+
+##### ref?
+
+```ts
+readonly optional ref?: string;
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("ResultNotJson").ref;
+```
+
+##### kind
+
+```ts
+readonly kind: string;
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("ResultNotJson").kind;
+```
+
+##### rawCause?
+
+```ts
+readonly optional rawCause?: unknown;
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("ResultNotJson").rawCause;
+```
+
+---
+
+### CapabilityFailed
+
+Failure at a named capability boundary, with an owner-admitted diagnostic.
+
+#### Extends
+
+- `YieldableError`\<`this`\> & `object` &
+  `Readonly`\<[`CapabilityFailureFields`](#capabilityfailurefields)\>
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new CapabilityFailed(fields): CapabilityFailed;
+```
+
+Retain the admitted diagnostic for ordinary Error consumers through the same
+safe projection.
+
+###### Parameters
+
+| Parameter | Type                                                  |
+| --------- | ----------------------------------------------------- |
+| `fields`  | [`CapabilityFailureFields`](#capabilityfailurefields) |
+
+###### Returns
+
+[`CapabilityFailed`](#capabilityfailed)
+
+###### Overrides
+
+```ts
+Data.TaggedError(
+  "CapabilityFailed",
+)<CapabilityFailureFields>.constructor
+```
+
+#### Properties
+
+##### ref?
+
+```ts
+readonly optional ref?: string;
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("CapabilityFailed").ref;
+```
+
+##### namespace
+
+```ts
+readonly namespace: string;
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("CapabilityFailed").namespace;
+```
+
+##### operation
+
+```ts
+readonly operation: string;
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("CapabilityFailed").operation;
+```
+
+##### rawCause?
+
+```ts
+readonly optional rawCause?: unknown;
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("CapabilityFailed").rawCause;
+```
+
+##### cause
+
+```ts
+cause: Readonly<{
+  kind: "Files" | "Forage" | "InvalidInput" | "Unavailable" | "OperationFailed";
+  message: string;
+}>;
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("CapabilityFailed").cause;
+```
+
+---
+
+### Unknown
+
+A foreign throw violated the typed adapter contract.
+
+#### Extends
+
+- `YieldableError`\<`this`\> & `object` &
+  `Readonly`\<[`SandboxFailureReference`](#sandboxfailurereference) & `object`\>
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new Unknown(args): Unknown;
+```
+
+###### Parameters
+
+| Parameter       | Type                                           |
+| --------------- | ---------------------------------------------- |
+| `args`          | \{ `ref?`: `string`; `rawCause`: `unknown`; \} |
+| `args.ref?`     | `string`                                       |
+| `args.rawCause` | `unknown`                                      |
+
+###### Returns
+
+[`Unknown`](#unknown)
+
+###### Inherited from
+
+```ts
+Data.TaggedError("Unknown")<
+  SandboxFailureReference & {
+    readonly rawCause: unknown;
+  }
+>.constructor
+```
+
+#### Properties
+
+##### ref?
+
+```ts
+readonly optional ref?: string;
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("Unknown").ref;
+```
+
+##### rawCause
+
+```ts
+readonly rawCause: unknown;
+```
+
+###### Inherited from
+
+```ts
+Data.TaggedError("Unknown").rawCause;
+```
+
+## Type Aliases
+
+### SandboxFailureReference
+
+```ts
+type SandboxFailureReference = object;
+```
+
+Optional source reference carried by sandbox failures.
+
+#### Properties
+
+##### ref?
+
+```ts
+readonly optional ref?: string;
+```
+
+---
+
+### CapabilityDiagnostic
+
+```ts
+type CapabilityDiagnostic = Readonly<{
+  kind: "Files" | "Forage" | "InvalidInput" | "Unavailable" | "OperationFailed";
+  message: string;
+}>;
+```
+
+A capability owner explicitly admits this bounded diagnostic as safe.
+
+---
+
+### CapabilityFailureFields
+
+```ts
+type CapabilityFailureFields = object;
+```
+
+Fields admitted by a capability owner, with the original cause kept private.
+
+#### Properties
+
+##### ref?
+
+```ts
+readonly optional ref?: string;
+```
+
+##### namespace
+
+```ts
+readonly namespace: string;
+```
+
+##### operation
+
+```ts
+readonly operation: string;
+```
+
+##### cause
+
+```ts
+readonly cause: CapabilityDiagnostic;
+```
+
+##### rawCause?
+
+```ts
+readonly optional rawCause?: unknown;
+```
+
+---
+
+### SandboxFailure
+
+```ts
+type SandboxFailure =
+  | SourceInvalid
+  | GuestThrew
+  | DeadlineExceeded
+  | Cancelled
+  | DispatchLost
+  | SandboxCrashed
+  | BadResponse
+  | ResultTooLarge
+  | ResultNotJson
+  | CapabilityFailed
+  | Unknown;
+```
+
+Closed error channel shared by sandbox adapters and the invocation owner.
+
+## Functions
+
+### referenceSandboxFailure()
+
+```ts
+function referenceSandboxFailure(failure, ref): SandboxFailure;
+```
+
+Copy the failure to correlate one execution without mutating shared host errors.
+
+#### Parameters
+
+| Parameter | Type                                |
+| --------- | ----------------------------------- |
+| `failure` | [`SandboxFailure`](#sandboxfailure) |
+| `ref`     | `string`                            |
+
+#### Returns
+
+[`SandboxFailure`](#sandboxfailure)
+
+---
+
+### sandboxFailureMessage()
+
+```ts
+function sandboxFailureMessage(failure, includeReference?): string;
+```
+
+The sole model projection. Transport, parser and raw cause fields stay private.
+
+#### Parameters
+
+| Parameter          | Type                                | Default value |
+| ------------------ | ----------------------------------- | ------------- |
+| `failure`          | [`SandboxFailure`](#sandboxfailure) | `undefined`   |
+| `includeReference` | `boolean`                           | `true`        |
+
+#### Returns
+
+`string`