@fungi.computer/mycelium 0.0.0-stage → 0.0.1

package/dist/sandbox-boundary.js

@@ -0,0 +1,325 @@
+import { nanoid } from "@fungi.computer/cairn";
+import { ForageError } from "@fungi.computer/forage";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import { z } from "zod";
+import { InvalidOperationInput } from "./errors.js";
+import { SourceInvalid, GuestThrew, DeadlineExceeded, Cancelled, DispatchLost, SandboxCrashed, BadResponse, ResultTooLarge, ResultNotJson, CapabilityFailed, Unknown, referenceSandboxFailure, sandboxFailureMessage, } from "./sandbox-failure.js";
+const ownedFailureSchema = z.union([
+    z.instanceof(SourceInvalid),
+    z.instanceof(GuestThrew),
+    z.instanceof(DeadlineExceeded),
+    z.instanceof(Cancelled),
+    z.instanceof(DispatchLost),
+    z.instanceof(SandboxCrashed),
+    z.instanceof(BadResponse),
+    z.instanceof(ResultTooLarge),
+    z.instanceof(ResultNotJson),
+    z.instanceof(CapabilityFailed),
+    z.instanceof(Unknown),
+]);
+/** The one interpretation boundary for foreign in-process values and rejections. */
+const foreignValueSchema = z
+    .unknown()
+    .pipe(z.union([
+    z
+        .instanceof(Error)
+        .transform((value) => ({ kind: "error", value })),
+    z.null().transform((value) => ({ kind: "null", value })),
+    z
+        .undefined()
+        .transform((value) => ({ kind: "undefined", value })),
+    z.string().transform((value) => ({ kind: "string", value })),
+    z.boolean().transform((value) => ({ kind: "boolean", value })),
+    z
+        .union([z.number(), z.nan(), z.literal(Infinity), z.literal(-Infinity)])
+        .transform((value) => ({ kind: "number", value })),
+    z.bigint().transform((value) => ({ kind: "bigint", value })),
+    z.symbol().transform((value) => ({ kind: "symbol", value })),
+    z
+        .instanceof(Function)
+        .transform((value) => ({ kind: "function", value })),
+    z
+        .array(z.unknown())
+        .transform((value) => ({ kind: "array", value })),
+    z
+        .union([z.instanceof(Object), z.record(z.string(), z.unknown())])
+        .transform((value) => ({ kind: "object", value })),
+    z.unknown().transform(() => ({ kind: "opaque" })),
+]));
+/** Admit only errors constructed by the sandbox owner, using the maintained decoder. */
+export function isSandboxFailure(cause) {
+    return ownedFailureSchema.safeParse(cause).success;
+}
+/** Foreign throws stay private until an owner admits a diagnostic. */
+export function sandboxFailure(cause) {
+    const owned = ownedFailureSchema.safeParse(cause);
+    return owned.success ? owned.data : new Unknown({ rawCause: cause });
+}
+/** Label a rejected JSON value without caller-owned reflection. */
+export function sandboxValueKind(value) {
+    const decoded = foreignValueSchema.parse(value);
+    switch (decoded.kind) {
+        case "error":
+        case "array":
+        case "null":
+            return "object";
+        default:
+            return decoded.kind;
+    }
+}
+const bindingInputSchema = z.json().optional();
+/** Decode the RPC argument before any capability callback observes it. */
+export function sandboxBindingInput(value) {
+    return bindingInputSchema.parse(value);
+}
+/** Full operator representation, including nested errors, aggregates and cycles. */
+export function sandboxOperatorValue(cause) {
+    return operatorValue(cause, new Set());
+}
+function operatorValue(cause, seen) {
+    const decoded = foreignValueSchema.parse(cause);
+    switch (decoded.kind) {
+        case "null":
+        case "undefined":
+            return null;
+        case "string":
+        case "boolean":
+            return decoded.value;
+        case "number":
+            return Number.isFinite(decoded.value)
+                ? decoded.value
+                : String(decoded.value);
+        case "bigint":
+        case "symbol":
+            return String(decoded.value);
+        case "function":
+            return { kind: "function", name: decoded.value.name };
+        case "opaque":
+            return { kind: "opaque" };
+        case "error":
+        case "array":
+        case "object": {
+            const value = decoded.value;
+            // Zod copies arrays and records. Track their original input identities,
+            // retaining references only for this traversal's active ancestors.
+            if (seen.has(cause))
+                return { kind: "circular_reference" };
+            seen.add(cause);
+            try {
+                if (decoded.kind === "array")
+                    return decoded.value.map((item) => operatorValue(item, seen));
+                const fields = Object.fromEntries(Object.entries(value).map(([key, item]) => [
+                    key,
+                    operatorValue(item, seen),
+                ]));
+                if (decoded.kind === "error") {
+                    const error = decoded.value;
+                    fields.name = error.name;
+                    fields.message = error.message;
+                    if (error.stack !== undefined)
+                        fields.stack = error.stack;
+                    if (error.cause !== undefined)
+                        fields.cause = operatorValue(error.cause, seen);
+                    if (error instanceof AggregateError)
+                        fields.errors = operatorValue(error.errors, seen);
+                }
+                return fields;
+            }
+            finally {
+                seen.delete(cause);
+            }
+        }
+    }
+}
+const missingVariable = z
+    .object({
+    name: z.literal("ReferenceError"),
+    message: z
+        .string()
+        .regex(/^[\p{ID_Start}_$][\p{ID_Continue}$]* is not defined$/u),
+})
+    .transform((value) => ({
+    ...value,
+    missingVariable: value.message.slice(0, -" is not defined".length),
+}));
+const guestDiagnosticSchema = z
+    .union([missingVariable, z.object({ name: z.string(), message: z.string() })])
+    .and(z.object({ transportMessage: z.string().max(512).optional() }));
+/** Decode the engine's guest-owned diagnostic once; renderers receive typed fields. */
+export function sandboxGuestFailure(cause, bindings = {}) {
+    const diagnostic = guestDiagnosticSchema.parse(cause);
+    if ("missingVariable" in diagnostic) {
+        for (const [namespace, operations] of Object.entries(bindings))
+            for (const operation of Object.keys(operations))
+                if (`${namespace}_${operation}` === diagnostic.missingVariable)
+                    return new GuestThrew({
+                        name: diagnostic.name,
+                        message: `${diagnostic.message}. Call the operation as a method: ${namespace}.${operation}(...).`,
+                    });
+    }
+    return new GuestThrew(diagnostic);
+}
+const transportEnvelopeSchema = z.strictObject({
+    v: z.literal(1),
+    kind: z.literal("sandbox_failure"),
+    tag: z.enum([
+        "SourceInvalid",
+        "GuestThrew",
+        "DeadlineExceeded",
+        "Cancelled",
+        "DispatchLost",
+        "SandboxCrashed",
+        "BadResponse",
+        "ResultTooLarge",
+        "ResultNotJson",
+        "CapabilityFailed",
+        "Unknown",
+    ]),
+    ref: z.string().min(1).max(32),
+    message: z.string().max(160),
+});
+const decodeJsonText = Schema.decodeUnknownResult(Schema.fromJsonString(Schema.Unknown));
+const jsonTextSchema = z.string().transform((text, context) => {
+    const decoded = decodeJsonText(text);
+    if (Result.isFailure(decoded)) {
+        context.addIssue({
+            code: "custom",
+            message: "Invalid sandbox transport JSON",
+        });
+        return z.NEVER;
+    }
+    return decoded.success;
+});
+const transportMessageSchema = jsonTextSchema.pipe(transportEnvelopeSchema);
+const returnedOperationFailure = z.strictObject({
+    error: transportMessageSchema,
+});
+/** Error.message is the SDK's wire carrier; only this safe, bounded envelope crosses it. */
+export function sandboxTransportMessage(failure, ref) {
+    const envelope = transportEnvelopeSchema.parse({
+        v: 1,
+        kind: "sandbox_failure",
+        tag: failure._tag,
+        ref,
+        message: sandboxFailureMessage(failure, false)
+            .replace(/\p{Cc}|\p{Cf}/gu, " ")
+            .slice(0, 160),
+    });
+    return JSON.stringify(envelope);
+}
+/** Recovery uses the decoded identity, never a match against diagnostic text. */
+export function recoverSandboxFailure(failure, failures) {
+    if (failure._tag !== "GuestThrew")
+        return failure;
+    const decoded = transportMessageSchema.safeParse(failure.transportMessage ?? failure.message);
+    if (!decoded.success)
+        return failure;
+    const original = failures.get(decoded.data.ref);
+    return original?._tag === decoded.data.tag ? original : failure;
+}
+const executorFailureSchema = z
+    .unknown()
+    .pipe(z.union([
+    z
+        .literal("Execution timed out")
+        .transform(() => ({ kind: "deadline" })),
+    z
+        .unknown()
+        .transform((rawCause) => ({ kind: "bad_response", rawCause })),
+]));
+/** Decode Codemode's documented error carrier before adapters choose a failure. */
+export function sandboxExecutorFailure(cause, limitMs, elapsedMs) {
+    const decoded = executorFailureSchema.parse(cause);
+    return decoded.kind === "deadline"
+        ? new DeadlineExceeded({ limitMs, elapsedMs })
+        : new BadResponse({
+            reason: "executor failed outside guest handler",
+            rawCause: decoded.rawCause,
+        });
+}
+/** Decode a transport-owned errno without reflecting on a foreign throw in adapters. */
+export function sandboxTransportErrno(cause) {
+    const error = z.instanceof(Error).safeParse(cause);
+    if (!error.success)
+        return undefined;
+    const decoded = z.object({ code: z.string() }).safeParse(error.data);
+    return decoded.success ? decoded.data.code : undefined;
+}
+/** Admit Acorn's documented offset from a syntax exception at this boundary. */
+export function sandboxSourceError(cause) {
+    const error = z.instanceof(SyntaxError).safeParse(cause);
+    if (!error.success)
+        return undefined;
+    const decoded = z
+        .object({ pos: z.number().int().nonnegative() })
+        .safeParse(error.data);
+    return decoded.success ? { pos: decoded.data.pos } : undefined;
+}
+/** Capability owners supply an admission schema; decoding and foreign fallback stay here. */
+export function sandboxCapabilityFailure(cause, namespace, operation, admitted = z.never()) {
+    const diagnostic = (fields) => new CapabilityFailed({
+        namespace,
+        operation,
+        cause: fields,
+        rawCause: cause,
+    });
+    return z
+        .unknown()
+        .pipe(z.union([
+        ownedFailureSchema,
+        admitted.transform(diagnostic),
+        z
+            .instanceof(ForageError)
+            .transform((error) => diagnostic({ kind: "Forage", message: error.message })),
+        z.instanceof(InvalidOperationInput).transform((error) => diagnostic({
+            kind: "InvalidInput",
+            message: `Invalid operation input: ${z.prettifyError({ issues: error.issues })}; use forage.describe`,
+        })),
+        z.unknown().transform((rawCause) => new Unknown({ rawCause })),
+    ]))
+        .parse(cause);
+}
+const maximumRecordedFailures = 128;
+/** One boundary owns RPC decoding, safe transport and invocation-scoped recovery. */
+export function sandboxBindingBoundary(bindings) {
+    const failures = new Map();
+    const capture = (failure) => {
+        if (failures.size >= maximumRecordedFailures)
+            throw new Error("Too many failed capability calls; split this execute call");
+        const ref = nanoid();
+        const referenced = referenceSandboxFailure(failure, ref);
+        failures.set(ref, referenced);
+        return sandboxTransportMessage(referenced, ref);
+    };
+    // Store the original cause in this invocation before constructing the safe
+    // guest carrier. It must never become an Error.cause exposed to the guest.
+    const captureError = (failure) => new Error(capture(failure));
+    return Object.freeze({
+        capture,
+        bindings: Object.freeze(Object.fromEntries(Object.entries(bindings).map(([namespace, operations]) => [
+            namespace,
+            Object.freeze(Object.fromEntries(Object.entries(operations).map(([operation, invoke]) => {
+                const call = async (input) => {
+                    if (failures.size >= maximumRecordedFailures)
+                        throw new Error("Too many failed capability calls; split this execute call");
+                    try {
+                        return await invoke(sandboxBindingInput(input));
+                    }
+                    catch (rawCause) {
+                        throw captureError(sandboxCapabilityFailure(rawCause, namespace, operation));
+                    }
+                };
+                return [operation, call];
+            }))),
+        ]))),
+        recover: (failure) => recoverSandboxFailure(failure, failures),
+        returnedFailure: (value) => {
+            const decoded = returnedOperationFailure.safeParse(value);
+            if (!decoded.success)
+                return undefined;
+            const original = failures.get(decoded.data.error.ref);
+            return original?._tag === decoded.data.error.tag ? original : undefined;
+        },
+    });
+}

package/dist/sandbox-failure-event.d.ts

@@ -0,0 +1,15 @@
+import * as Schema from "effect/Schema";
+import type { z } from "zod";
+/** Shared structural grammar for durable operator facts and client inspection. */
+export declare const SandboxFailureEventSchema: Schema.Struct<{
+    readonly kind: Schema.Literal<"sandbox_failure">;
+    readonly ref: Schema.String;
+    readonly executionId: Schema.String;
+    readonly adapter: Schema.String;
+    readonly buildSha: Schema.NullOr<Schema.String>;
+    readonly tag: Schema.Literals<readonly ["SourceInvalid", "GuestThrew", "DeadlineExceeded", "Cancelled", "DispatchLost", "SandboxCrashed", "BadResponse", "ResultTooLarge", "ResultNotJson", "CapabilityFailed", "Unknown"]>;
+    readonly fields: Schema.$Record<Schema.String, Schema.Codec<z.core.util.JSONType, z.core.util.JSONType, never, never>>;
+    readonly healthAlert: Schema.Boolean;
+}>;
+/** Full operator diagnostics, excluded from model conversation and default reads. */
+export type SandboxFailureEvent = typeof SandboxFailureEventSchema.Type;

package/dist/sandbox-failure-event.js

@@ -0,0 +1,34 @@
+import * as Schema from "effect/Schema";
+const operatorJsonValue = Schema.suspend(() => Schema.Union([
+    Schema.Null,
+    Schema.Boolean,
+    Schema.Finite,
+    Schema.String,
+    Schema.mutable(Schema.Array(operatorJsonValue)),
+    Schema.mutableKey(Schema.Record(Schema.String, operatorJsonValue)),
+]));
+const reference = Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(256));
+const identity = Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(128));
+/** Shared structural grammar for durable operator facts and client inspection. */
+export const SandboxFailureEventSchema = Schema.Struct({
+    kind: Schema.Literal("sandbox_failure"),
+    ref: reference,
+    executionId: reference,
+    adapter: identity,
+    buildSha: Schema.NullOr(identity),
+    tag: Schema.Literals([
+        "SourceInvalid",
+        "GuestThrew",
+        "DeadlineExceeded",
+        "Cancelled",
+        "DispatchLost",
+        "SandboxCrashed",
+        "BadResponse",
+        "ResultTooLarge",
+        "ResultNotJson",
+        "CapabilityFailed",
+        "Unknown",
+    ]),
+    fields: Schema.Record(Schema.String, operatorJsonValue),
+    healthAlert: Schema.Boolean,
+});

package/dist/sandbox-failure.d.ts

@@ -0,0 +1,128 @@
+/** Optional source reference carried by sandbox failures. */
+export type SandboxFailureReference = {
+    readonly ref?: string | undefined;
+};
+declare const SourceInvalid_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "SourceInvalid";
+} & Readonly<A>;
+/** A location in the submitted program, never in the host's source. */
+export declare class SourceInvalid extends SourceInvalid_base<SandboxFailureReference & {
+    readonly line: number;
+    readonly column: number;
+    readonly excerpt: string;
+}> {
+}
+declare const GuestThrew_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "GuestThrew";
+} & Readonly<A>;
+/** Text captured inside the guest's own exception handler. */
+export declare class GuestThrew extends GuestThrew_base<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;
+}> {
+}
+declare const DeadlineExceeded_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "DeadlineExceeded";
+} & Readonly<A>;
+/** The invocation owner decided its execution budget was spent. */
+export declare class DeadlineExceeded extends DeadlineExceeded_base<SandboxFailureReference & {
+    readonly limitMs: number;
+    readonly elapsedMs: number;
+    readonly acknowledged?: boolean | undefined;
+}> {
+}
+declare const Cancelled_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "Cancelled";
+} & Readonly<A>;
+/** The invocation owner accepted cancellation. */
+export declare class Cancelled extends Cancelled_base<SandboxFailureReference & {
+    readonly by: "caller" | "operator";
+    readonly acknowledged?: boolean | undefined;
+}> {
+}
+declare const DispatchLost_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "DispatchLost";
+} & Readonly<A>;
+/** Dispatch started, but its transport did not deliver an answer. */
+export declare class DispatchLost extends DispatchLost_base<SandboxFailureReference & {
+    readonly elapsedMs: number;
+    readonly transport: string;
+    readonly errno?: string | undefined;
+    readonly rawCause: unknown;
+}> {
+}
+declare const SandboxCrashed_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "SandboxCrashed";
+} & Readonly<A>;
+/** The sandbox process could not start or stopped before answering. */
+export declare class SandboxCrashed extends SandboxCrashed_base<SandboxFailureReference & {
+    readonly exit?: number | undefined;
+    readonly errno?: string | undefined;
+    readonly rawCause: unknown;
+}> {
+}
+declare const BadResponse_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "BadResponse";
+} & Readonly<A>;
+/** A received envelope could not be decoded. Its reason is operator only. */
+export declare class BadResponse extends BadResponse_base<SandboxFailureReference & {
+    readonly reason: string;
+    readonly rawCause: unknown;
+}> {
+}
+declare const ResultTooLarge_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "ResultTooLarge";
+} & Readonly<A>;
+/** A JSON result exceeded Mycelium's output budget. */
+export declare class ResultTooLarge extends ResultTooLarge_base<SandboxFailureReference & {
+    readonly size: number;
+}> {
+}
+declare const ResultNotJson_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "ResultNotJson";
+} & Readonly<A>;
+/** A result could not be represented as JSON. */
+export declare class ResultNotJson extends ResultNotJson_base<SandboxFailureReference & {
+    readonly kind: string;
+    readonly rawCause?: unknown;
+}> {
+}
+/** A capability owner explicitly admits this bounded diagnostic as safe. */
+export type CapabilityDiagnostic = Readonly<{
+    kind: "Files" | "Forage" | "InvalidInput" | "Unavailable" | "OperationFailed";
+    message: string;
+}>;
+/** Fields admitted by a capability owner, with the original cause kept private. */
+export type CapabilityFailureFields = {
+    readonly ref?: string;
+    readonly namespace: string;
+    readonly operation: string;
+    readonly cause: CapabilityDiagnostic;
+    readonly rawCause?: unknown;
+};
+declare const CapabilityFailed_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "CapabilityFailed";
+} & Readonly<A>;
+/** Failure at a named capability boundary, with an owner-admitted diagnostic. */
+export declare class CapabilityFailed extends CapabilityFailed_base<CapabilityFailureFields> {
+    /** Retain the admitted diagnostic for ordinary Error consumers through the same safe projection. */
+    constructor(fields: CapabilityFailureFields);
+}
+declare const Unknown_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "Unknown";
+} & Readonly<A>;
+/** A foreign throw violated the typed adapter contract. */
+export declare class Unknown extends Unknown_base<SandboxFailureReference & {
+    readonly rawCause: unknown;
+}> {
+}
+/** Closed error channel shared by sandbox adapters and the invocation owner. */
+export type SandboxFailure = SourceInvalid | GuestThrew | DeadlineExceeded | Cancelled | DispatchLost | SandboxCrashed | BadResponse | ResultTooLarge | ResultNotJson | CapabilityFailed | Unknown;
+/** Copy the failure to correlate one execution without mutating shared host errors. */
+export declare function referenceSandboxFailure(failure: SandboxFailure, ref: string): SandboxFailure;
+/** The sole model projection. Transport, parser and raw cause fields stay private. */
+export declare function sandboxFailureMessage(failure: SandboxFailure, includeReference?: boolean): string;
+export {};

package/dist/sandbox-failure.js

@@ -0,0 +1,161 @@
+import * as Data from "effect/Data";
+/** A location in the submitted program, never in the host's source. */
+export class SourceInvalid extends Data.TaggedError("SourceInvalid") {
+}
+/** Text captured inside the guest's own exception handler. */
+export class GuestThrew extends Data.TaggedError("GuestThrew") {
+}
+/** The invocation owner decided its execution budget was spent. */
+export class DeadlineExceeded extends Data.TaggedError("DeadlineExceeded") {
+}
+/** The invocation owner accepted cancellation. */
+export class Cancelled extends Data.TaggedError("Cancelled") {
+}
+/** Dispatch started, but its transport did not deliver an answer. */
+export class DispatchLost extends Data.TaggedError("DispatchLost") {
+}
+/** The sandbox process could not start or stopped before answering. */
+export class SandboxCrashed extends Data.TaggedError("SandboxCrashed") {
+}
+/** A received envelope could not be decoded. Its reason is operator only. */
+export class BadResponse extends Data.TaggedError("BadResponse") {
+}
+/** A JSON result exceeded Mycelium's output budget. */
+export class ResultTooLarge extends Data.TaggedError("ResultTooLarge") {
+}
+/** A result could not be represented as JSON. */
+export class ResultNotJson extends Data.TaggedError("ResultNotJson") {
+}
+/** Failure at a named capability boundary, with an owner-admitted diagnostic. */
+export class CapabilityFailed extends Data.TaggedError("CapabilityFailed") {
+    /** Retain the admitted diagnostic for ordinary Error consumers through the same safe projection. */
+    constructor(fields) {
+        super(fields);
+        this.message = sandboxFailureMessage(this);
+    }
+}
+/** A foreign throw violated the typed adapter contract. */
+export class Unknown extends Data.TaggedError("Unknown") {
+}
+/** Copy the failure to correlate one execution without mutating shared host errors. */
+export function referenceSandboxFailure(failure, ref) {
+    switch (failure._tag) {
+        case "SourceInvalid":
+            return new SourceInvalid({
+                line: failure.line,
+                column: failure.column,
+                excerpt: failure.excerpt,
+                ref,
+            });
+        case "GuestThrew":
+            return new GuestThrew({
+                name: failure.name,
+                message: failure.message,
+                missingVariable: failure.missingVariable,
+                transportMessage: failure.transportMessage,
+                ref,
+            });
+        case "DeadlineExceeded":
+            return new DeadlineExceeded({
+                limitMs: failure.limitMs,
+                elapsedMs: failure.elapsedMs,
+                acknowledged: failure.acknowledged,
+                ref,
+            });
+        case "Cancelled":
+            return new Cancelled({
+                by: failure.by,
+                acknowledged: failure.acknowledged,
+                ref,
+            });
+        case "DispatchLost":
+            return new DispatchLost({
+                elapsedMs: failure.elapsedMs,
+                transport: failure.transport,
+                errno: failure.errno,
+                rawCause: failure.rawCause,
+                ref,
+            });
+        case "SandboxCrashed":
+            return new SandboxCrashed({
+                exit: failure.exit,
+                errno: failure.errno,
+                rawCause: failure.rawCause,
+                ref,
+            });
+        case "BadResponse":
+            return new BadResponse({
+                reason: failure.reason,
+                rawCause: failure.rawCause,
+                ref,
+            });
+        case "ResultTooLarge":
+            return new ResultTooLarge({ size: failure.size, ref });
+        case "ResultNotJson":
+            return new ResultNotJson({
+                kind: failure.kind,
+                rawCause: failure.rawCause,
+                ref,
+            });
+        case "CapabilityFailed":
+            return new CapabilityFailed({
+                namespace: failure.namespace,
+                operation: failure.operation,
+                cause: failure.cause,
+                rawCause: failure.rawCause,
+                ref,
+            });
+        case "Unknown":
+            return new Unknown({ rawCause: failure.rawCause, ref });
+    }
+}
+/** The sole model projection. Transport, parser and raw cause fields stay private. */
+export function sandboxFailureMessage(failure, includeReference = true) {
+    let text;
+    switch (failure._tag) {
+        case "SourceInvalid":
+            text = `SyntaxError in submitted source line ${String(failure.line)}, column ${String(failure.column)}: ${failure.excerpt.slice(0, 160)}. Nothing ran. Fix quote/heredoc nesting: quote multi-line shell text with a JavaScript template literal or \\n escapes; escape backticks and \${ inside it. If a nested heredoc is hard to quote, write the script with Files, then execute it.`;
+            break;
+        case "GuestThrew": {
+            const name = failure.name.slice(0, 80);
+            const message = failure.message.slice(0, 512);
+            const missing = failure.missingVariable;
+            text = `${name}: ${message}${missing === undefined ? "" : `. Declare ${missing} with const or let before assigning it; this sandbox does not create implicit globals. Each execute call has its own variables.`}`;
+            break;
+        }
+        case "DeadlineExceeded":
+            text = `execute hit its ${String(failure.limitMs)} ms deadline after ${String(failure.elapsedMs)} ms; split the work or persist progress${failure.acknowledged === false ? "; sandbox did not acknowledge cancellation" : ""}`;
+            break;
+        case "Cancelled":
+            text =
+                failure.acknowledged === false
+                    ? "Sandbox did not acknowledge cancellation"
+                    : "Execution was cancelled";
+            break;
+        case "DispatchLost":
+            text = `The sandbox lost contact after ${String(failure.elapsedMs)} ms; a running command may still be running; check its effects before retrying`;
+            break;
+        case "SandboxCrashed":
+            text =
+                "The sandbox process stopped before answering; check effects before retrying";
+            break;
+        case "BadResponse":
+            text =
+                "The sandbox returned an unreadable result; retry once, split the call if it recurs";
+            break;
+        case "ResultTooLarge":
+            text = "Sandbox result exceeds 256 KiB";
+            break;
+        case "ResultNotJson":
+            text = "Sandbox returned non-JSON data";
+            break;
+        case "CapabilityFailed":
+            text = failure.cause.message.slice(0, 1000);
+            break;
+        case "Unknown":
+            return `The sandbox failed for an unrecognized reason${includeReference ? ` (ref ${failure.ref ?? "unavailable"})` : ""}`;
+    }
+    return !includeReference || failure.ref === undefined
+        ? text
+        : `${text} (ref ${failure.ref})`;
+}