API reference

sandbox-failure

Import

import * as api from "@fungi.computer/mycelium/sandbox-failure";

Exports

Kind	Export	Description
class	SourceInvalid	A location in the submitted program, never in the host’s source.
class	GuestThrew	Text captured inside the guest’s own exception handler.
class	DeadlineExceeded	The invocation owner decided its execution budget was spent.
class	SandboxBusy	Admission expired before any sandbox work started.
class	Cancelled	The invocation owner accepted cancellation.
class	DispatchLost	Dispatch started, but its transport did not deliver an answer.
class	SandboxCrashed	The sandbox process could not start or stopped before answering.
class	BadResponse	A received envelope could not be decoded. Its reason is operator only.
class	ResultTooLarge	A JSON result exceeded Mycelium’s output budget.
class	ResultNotJson	A result could not be represented as JSON.
class	CapabilityFailed	Failure at a named capability boundary, with an owner-admitted diagnostic.
class	Unknown	A foreign throw violated the typed adapter contract.
type alias	SandboxFailureReference	Optional source reference carried by sandbox failures.
type alias	CapabilityDiagnostic	A capability owner explicitly admits this bounded diagnostic as safe.
type alias	CapabilityFailureFields	Fields admitted by a capability owner, with the original cause kept private.
type alias	SandboxFailure	Closed error channel shared by sandbox adapters and the invocation owner.
function	referenceSandboxFailure()	Copy the failure to correlate one execution without mutating shared host errors.
function	sandboxFailureMessage()	The sole model projection. Transport, parser and raw cause fields stay private.

SourceInvalidclass

A location in the submitted program, never in the host’s source.

Extends

YieldableError<this> & object & Readonly<SandboxFailureReference & object>

Constructors

Constructor

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

Inherited from

Data.TaggedError("SourceInvalid")<
  SandboxFailureReference & {
    readonly line: number;
    readonly column: number;
    readonly excerpt: string;
  }
>.constructor

Properties

ref?

readonly optional ref?: string;

Inherited from

Data.TaggedError("SourceInvalid").ref;

line

readonly line: number;

Inherited from

Data.TaggedError("SourceInvalid").line;

column

readonly column: number;

Inherited from

Data.TaggedError("SourceInvalid").column;

excerpt

readonly excerpt: string;

Inherited from

Data.TaggedError("SourceInvalid").excerpt;

GuestThrewclass

Text captured inside the guest’s own exception handler.

Extends

YieldableError<this> & object & Readonly<SandboxFailureReference & object>

Constructors

Constructor

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

Inherited from

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?

readonly optional ref?: string;

Inherited from

Data.TaggedError("GuestThrew").ref;

missingVariable?

readonly optional missingVariable?: string;

Inherited from

Data.TaggedError("GuestThrew").missingVariable;

transportMessage?

readonly optional transportMessage?: string;

Safe provider envelope carried in the guest exception’s cause, never model text.

Inherited from

Data.TaggedError("GuestThrew").transportMessage;

name

name: string;

Inherited from

Data.TaggedError("GuestThrew").name;

message

message: string;

Inherited from

Data.TaggedError("GuestThrew").message;

DeadlineExceededclass

The invocation owner decided its execution budget was spent.

Extends

YieldableError<this> & object & Readonly<SandboxFailureReference & object>

Constructors

Constructor

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

Inherited from

Data.TaggedError("DeadlineExceeded")<
  SandboxFailureReference & {
    readonly limitMs: number;
    readonly elapsedMs: number;
    readonly acknowledged?: boolean | undefined;
  }
>.constructor

Properties

ref?

readonly optional ref?: string;

Inherited from

Data.TaggedError("DeadlineExceeded").ref;

limitMs

readonly limitMs: number;

Inherited from

Data.TaggedError("DeadlineExceeded").limitMs;

elapsedMs

readonly elapsedMs: number;

Inherited from

Data.TaggedError("DeadlineExceeded").elapsedMs;

acknowledged?

readonly optional acknowledged?: boolean;

Inherited from

Data.TaggedError("DeadlineExceeded").acknowledged;

SandboxBusyclass

Admission expired before any sandbox work started.

Extends

YieldableError<this> & object & Readonly<SandboxFailureReference & object>

Constructors

Constructor

new SandboxBusy(args): SandboxBusy;

Parameters

Parameter	Type
`args`	`{ ref?: string; capacity: number; waitedMs: number; }`
`args.ref?`	`string`
`args.capacity`	`number`
`args.waitedMs`	`number`

Returns

SandboxBusy

Inherited from

Data.TaggedError("SandboxBusy")<
  SandboxFailureReference & {
    readonly capacity: number;
    readonly waitedMs: number;
  }
>.constructor

Properties

ref?

readonly optional ref?: string;

Inherited from

Data.TaggedError("SandboxBusy").ref;

capacity

readonly capacity: number;

Inherited from

Data.TaggedError("SandboxBusy").capacity;

waitedMs

readonly waitedMs: number;

Inherited from

Data.TaggedError("SandboxBusy").waitedMs;

code

readonly code: "sandbox-busy" = "sandbox-busy";

Stable contention code, not a sandbox health failure.

Cancelledclass

The invocation owner accepted cancellation.

Extends

YieldableError<this> & object & Readonly<SandboxFailureReference & object>

Constructors

Constructor

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

Inherited from

Data.TaggedError("Cancelled")<
  SandboxFailureReference & {
    readonly by: "caller" | "operator";
    readonly acknowledged?: boolean | undefined;
  }
>.constructor

Properties

ref?

readonly optional ref?: string;

Inherited from

Data.TaggedError("Cancelled").ref;

by

readonly by: "caller" | "operator";

Inherited from

Data.TaggedError("Cancelled").by;

acknowledged?

readonly optional acknowledged?: boolean;

Inherited from

Data.TaggedError("Cancelled").acknowledged;

DispatchLostclass

Dispatch started, but its transport did not deliver an answer.

Extends

YieldableError<this> & object & Readonly<SandboxFailureReference & object>

Constructors

Constructor

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

Inherited from

Data.TaggedError("DispatchLost")<
  SandboxFailureReference & {
    readonly elapsedMs: number;
    readonly transport: string;
    readonly errno?: string | undefined;
    readonly rawCause: unknown;
  }
>.constructor

Properties

ref?

readonly optional ref?: string;

Inherited from

Data.TaggedError("DispatchLost").ref;

elapsedMs

readonly elapsedMs: number;

Inherited from

Data.TaggedError("DispatchLost").elapsedMs;

transport

readonly transport: string;

Inherited from

Data.TaggedError("DispatchLost").transport;

errno?

readonly optional errno?: string;

Inherited from

Data.TaggedError("DispatchLost").errno;

rawCause

readonly rawCause: unknown;

Inherited from

Data.TaggedError("DispatchLost").rawCause;

SandboxCrashedclass

The sandbox process could not start or stopped before answering.

Extends

YieldableError<this> & object & Readonly<SandboxFailureReference & object>

Constructors

Constructor

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

Inherited from

Data.TaggedError("SandboxCrashed")<
  SandboxFailureReference & {
    readonly exit?: number | undefined;
    readonly errno?: string | undefined;
    readonly rawCause: unknown;
  }
>.constructor

Properties

ref?

readonly optional ref?: string;

Inherited from

Data.TaggedError("SandboxCrashed").ref;

exit?

readonly optional exit?: number;

Inherited from

Data.TaggedError("SandboxCrashed").exit;

errno?

readonly optional errno?: string;

Inherited from

Data.TaggedError("SandboxCrashed").errno;

rawCause

readonly rawCause: unknown;

Inherited from

Data.TaggedError("SandboxCrashed").rawCause;

BadResponseclass

A received envelope could not be decoded. Its reason is operator only.

Extends

YieldableError<this> & object & Readonly<SandboxFailureReference & object>

Constructors

Constructor

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

Inherited from

Data.TaggedError("BadResponse")<
  SandboxFailureReference & {
    readonly reason: string;
    readonly rawCause: unknown;
  }
>.constructor

Properties

ref?

readonly optional ref?: string;

Inherited from

Data.TaggedError("BadResponse").ref;

reason

readonly reason: string;

Inherited from

Data.TaggedError("BadResponse").reason;

rawCause

readonly rawCause: unknown;

Inherited from

Data.TaggedError("BadResponse").rawCause;

ResultTooLargeclass

A JSON result exceeded Mycelium’s output budget.

Extends

YieldableError<this> & object & Readonly<SandboxFailureReference & object>

Constructors

Constructor

new ResultTooLarge(args): ResultTooLarge;

Parameters

Parameter	Type
`args`	`{ ref?: string; size: number; }`
`args.ref?`	`string`
`args.size`	`number`

Returns

ResultTooLarge

Inherited from

Data.TaggedError("ResultTooLarge")<
  SandboxFailureReference & {
    readonly size: number;
  }
>.constructor

Properties

ref?

readonly optional ref?: string;

Inherited from

Data.TaggedError("ResultTooLarge").ref;

size

readonly size: number;

Inherited from

Data.TaggedError("ResultTooLarge").size;

ResultNotJsonclass

A result could not be represented as JSON.

Extends

YieldableError<this> & object & Readonly<SandboxFailureReference & object>

Constructors

Constructor

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

Inherited from

Data.TaggedError("ResultNotJson")<
  SandboxFailureReference & {
    readonly kind: string;
    readonly rawCause?: unknown;
  }
>.constructor

Properties

ref?

readonly optional ref?: string;

Inherited from

Data.TaggedError("ResultNotJson").ref;

kind

readonly kind: string;

Inherited from

Data.TaggedError("ResultNotJson").kind;

rawCause?

readonly optional rawCause?: unknown;

Inherited from

Data.TaggedError("ResultNotJson").rawCause;

CapabilityFailedclass

Failure at a named capability boundary, with an owner-admitted diagnostic.

Extends

YieldableError<this> & object & Readonly<CapabilityFailureFields>

Constructors

Constructor

new CapabilityFailed(fields): CapabilityFailed;

Retain the admitted diagnostic for ordinary Error consumers through the same safe projection.

Parameters

Parameter	Type
`fields`	`CapabilityFailureFields`

Returns

CapabilityFailed

Overrides

Data.TaggedError(
  "CapabilityFailed",
)<CapabilityFailureFields>.constructor

Properties

ref?

readonly optional ref?: string;

Inherited from

Data.TaggedError("CapabilityFailed").ref;

namespace

readonly namespace: string;

Inherited from

Data.TaggedError("CapabilityFailed").namespace;

operation

readonly operation: string;

Inherited from

Data.TaggedError("CapabilityFailed").operation;

rawCause?

readonly optional rawCause?: unknown;

Inherited from

Data.TaggedError("CapabilityFailed").rawCause;

cause

cause: Readonly<{
  kind: "Files" | "Forage" | "InvalidInput" | "Unavailable" | "OperationFailed";
  message: string;
}>;

Inherited from

Data.TaggedError("CapabilityFailed").cause;

Unknownclass

A foreign throw violated the typed adapter contract.

Extends

YieldableError<this> & object & Readonly<SandboxFailureReference & object>

Constructors

Constructor

new Unknown(args): Unknown;

Parameters

Parameter	Type
`args`	`{ ref?: string; rawCause: unknown; }`
`args.ref?`	`string`
`args.rawCause`	`unknown`

Returns

Unknown

Inherited from

Data.TaggedError("Unknown")<
  SandboxFailureReference & {
    readonly rawCause: unknown;
  }
>.constructor

Properties

ref?

readonly optional ref?: string;

Inherited from

Data.TaggedError("Unknown").ref;

rawCause

readonly rawCause: unknown;

Inherited from

Data.TaggedError("Unknown").rawCause;

SandboxFailureReferencetype alias

type SandboxFailureReference = object;

Optional source reference carried by sandbox failures.

Properties

ref?

readonly optional ref?: string;

CapabilityDiagnostictype alias

type CapabilityDiagnostic = Readonly<{
  kind: "Files" | "Forage" | "InvalidInput" | "Unavailable" | "OperationFailed";
  message: string;
}>;

A capability owner explicitly admits this bounded diagnostic as safe.

CapabilityFailureFieldstype alias

type CapabilityFailureFields = object;

Fields admitted by a capability owner, with the original cause kept private.

Properties

ref?

readonly optional ref?: string;

namespace

readonly namespace: string;

operation

readonly operation: string;

cause

readonly cause: CapabilityDiagnostic;

rawCause?

readonly optional rawCause?: unknown;

SandboxFailuretype alias

type SandboxFailure =
  | SourceInvalid
  | GuestThrew
  | DeadlineExceeded
  | SandboxBusy
  | Cancelled
  | DispatchLost
  | SandboxCrashed
  | BadResponse
  | ResultTooLarge
  | ResultNotJson
  | CapabilityFailed
  | Unknown;

Closed error channel shared by sandbox adapters and the invocation owner.

referenceSandboxFailure()function

function referenceSandboxFailure(failure, ref): SandboxFailure;

Copy the failure to correlate one execution without mutating shared host errors.

Parameters

Parameter	Type
`failure`	`SandboxFailure`
`ref`	`string`

Returns

SandboxFailure

sandboxFailureMessage()function

function sandboxFailureMessage(failure, includeReference?): string;

The sole model projection. Transport, parser and raw cause fields stay private.

Parameters

Parameter	Type	Default value
`failure`	`SandboxFailure`	`undefined`
`includeReference`	`boolean`	`true`

Returns

string

sandbox-failure

Import

Exports

SourceInvalidCclass

Extends

Constructors

Constructor

Parameters

Returns

Inherited from

Properties

ref?

Inherited from

line

Inherited from

column

Inherited from

excerpt

Inherited from

GuestThrewCclass

Extends

Constructors

Constructor

Parameters

Returns

Inherited from

Properties

ref?

Inherited from

missingVariable?

Inherited from

transportMessage?

Inherited from

name

Inherited from

message

Inherited from

DeadlineExceededCclass

Extends

Constructors

Constructor

Parameters

Returns

Inherited from

Properties

ref?

Inherited from

limitMs

Inherited from

elapsedMs

Inherited from

acknowledged?

Inherited from

SandboxBusyCclass

Extends

Constructors

Constructor

Parameters

Returns

Inherited from

Properties

ref?

Inherited from

capacity

Inherited from

waitedMs

Inherited from

code

CancelledCclass

Extends

Constructors

Constructor

Parameters

Returns

Inherited from

Properties

ref?

Inherited from

by

Inherited from

SourceInvalidclass

GuestThrewclass

DeadlineExceededclass

SandboxBusyclass

Cancelledclass

DispatchLostclass

SandboxCrashedclass

BadResponseclass

ResultTooLargeclass

ResultNotJsonclass