@zackbart/connecta 0.28.1 → 0.30.0

package/dist/executor-admission.d.ts

@@ -65,6 +65,7 @@ export declare class AdmissionController {
     snapshot(): AdmissionSnapshot;
     acquire(options?: {
         signal?: AbortSignal;
+        wait?: boolean;
     }): Promise<AdmissionLease>;
     close(): void;
     private overloaded;

package/dist/executor-admission.js

@@ -14,9 +14,7 @@ export class ExecutorAdmissionError extends Error {
         this.code = code;
         this.name = "ExecutorAdmissionError";
         this.retryable = code === "executor_overloaded";
-        if (opts.retryAfterMs !== undefined &&
-            Number.isFinite(opts.retryAfterMs) &&
-            opts.retryAfterMs >= 0) {
+        if (opts.retryAfterMs !== undefined && Number.isFinite(opts.retryAfterMs) && opts.retryAfterMs >= 0) {
             this.retryAfterMs = Math.trunc(opts.retryAfterMs);
         }
     }
@@ -72,9 +70,8 @@ export class AdmissionController {
         this.maxQueueSize = nonNegativeWhole(options.maxQueueSize, "maxQueueSize");
         this.queueTimeoutMs = positiveWhole(options.queueTimeoutMs, "queueTimeoutMs");
         this.retryAfterMs = nonNegativeWhole(options.retryAfterMs ?? this.queueTimeoutMs, "retryAfterMs");
-        this.maxDurationMs = options.maxDurationMs === undefined
-            ? undefined
-            : positiveWhole(options.maxDurationMs, "maxDurationMs");
+        this.maxDurationMs =
+            options.maxDurationMs === undefined ? undefined : positiveWhole(options.maxDurationMs, "maxDurationMs");
         if (this.maxDurationMs !== undefined && this.maxDurationMs > 2_147_483_647) {
             throw new TypeError("maxDurationMs must be at most 2,147,483,647 milliseconds.");
         }
@@ -129,9 +126,7 @@ export class AdmissionController {
     }
     makeLease(waitMs) {
         const id = Symbol("admission lease");
-        const record = this.maxDurationMs !== undefined
-            ? { expiresAt: Date.now() + this.maxDurationMs }
-            : {};
+        const record = this.maxDurationMs !== undefined ? { expiresAt: Date.now() + this.maxDurationMs } : {};
         this.leases.set(id, record);
         return {
             waitMs,
@@ -202,9 +197,7 @@ export class AdmissionController {
         }
         // A queued request's own timer reaps the earliest admitted lease. A
         // fallback check covers a briefly empty lease map after a handoff.
-        return Number.isFinite(next)
-            ? Math.max(1, next - Date.now())
-            : 250;
+        return Number.isFinite(next) ? Math.max(1, next - Date.now()) : 250;
     }
     remove(waiter) {
         const index = this.waiters.indexOf(waiter);
@@ -233,7 +226,7 @@ export class AdmissionController {
     // static block is the one place outside an instance method that may read
     // this bookkeeping while emitting nothing there.
     static {
-        provideAdmissionProgram((controller, signal) => Effect.suspend(() => {
+        provideAdmissionProgram((controller, signal, wait) => Effect.suspend(() => {
             controller.reapExpired();
             if (controller.closed) {
                 controller.closedTotal++;
@@ -248,6 +241,10 @@ export class AdmissionController {
                 controller.admittedTotal++;
                 return Effect.succeed(controller.makeLease(0));
             }
+            if (!wait) {
+                controller.rejectedTotal++;
+                return Effect.fail(controller.overloaded("No executor slot is free for nested execution. Invoke the operation directly, after this program ends."));
+            }
             if (controller.waiters.length >= controller.maxQueueSize) {
                 controller.rejectedTotal++;
                 return Effect.fail(controller.overloaded("Executor queue is full."));
@@ -284,8 +281,7 @@ export class AdmissionController {
 }
 /** Preserve the one-method Workers seam while recognizing richer Node executors. */
 export function isAdmittingExecutor(executor) {
-    return ("acquire" in executor &&
-        typeof executor.acquire === "function");
+    return "acquire" in executor && typeof executor.acquire === "function";
 }
 /** Terminal- and JSON-safe upper bound for an executor's self-reported name. */
 const MAX_EXECUTOR_NAME_LENGTH = 40;

package/dist/executor-contract.d.ts

@@ -0,0 +1,20 @@
+import type { AdmittingExecutor, Executor } from "./types.js";
+type ExecutorLifecycle = "leased" | "self-managed";
+export declare function brandExecutor<T extends Executor>(executor: T, lifecycle: ExecutorLifecycle): T;
+export declare function assertExecutor(executor: Executor): void;
+/** Explicitly accept responsibility for a custom sandbox's run resources. */
+export interface CustomExecutorOptions {
+    /**
+     * The custom executor owns guest termination and resource cleanup, including
+     * budget exhaustion, cancellation, and deadlines. Connecta cannot add these
+     * guarantees to an executor that exposes only execute().
+     */
+    lifecycle: "self-managed";
+}
+/**
+ * Opt a custom sandbox into createConnecta without changing the original object.
+ * Delegated methods retain their original receiver, including private fields.
+ */
+export declare function customExecutor(executor: AdmittingExecutor, options: CustomExecutorOptions): AdmittingExecutor;
+export declare function customExecutor(executor: Executor, options: CustomExecutorOptions): Executor;
+export {};

package/dist/executor-contract.js

@@ -0,0 +1,48 @@
+import { executorName, isAdmittingExecutor } from "./executor-admission.js";
+// Symbol.for and a data descriptor survive duplicate packages and minification.
+// This is a construction contract, not a security boundary against host config.
+const EXECUTOR_BRAND = Symbol.for("connecta.executor");
+export function brandExecutor(executor, lifecycle) {
+    Object.defineProperty(executor, EXECUTOR_BRAND, {
+        value: Object.freeze({ version: 1, lifecycle }),
+        enumerable: false,
+        writable: false,
+        configurable: false,
+    });
+    return executor;
+}
+export function assertExecutor(executor) {
+    const descriptor = Object.getOwnPropertyDescriptor(executor, EXECUTOR_BRAND);
+    const brand = descriptor?.value;
+    if (typeof executor.execute === "function" &&
+        descriptor?.enumerable === false &&
+        brand?.version === 1 &&
+        (brand.lifecycle === "leased" || brand.lifecycle === "self-managed"))
+        return;
+    throw new Error("ConnectaConfig.executor must declare its lifecycle. Unbranded executors, including " +
+        "upstream DynamicWorkerExecutor, are unsupported because request-owned resources " +
+        "must be released when a run ends. Use one of these options: " +
+        'import { workerExecutor } from "@zackbart/connecta/worker"; ' +
+        "executor: workerExecutor({ loader: env.LOADER }); " +
+        'import { quickJsExecutor } from "@zackbart/connecta/quickjs"; executor: quickJsExecutor(); ' +
+        'or import { customExecutor } from "@zackbart/connecta"; ' +
+        'executor: customExecutor(myExecutor, { lifecycle: "self-managed" }).');
+}
+export function customExecutor(executor, options) {
+    if (options?.lifecycle !== "self-managed" || typeof executor?.execute !== "function") {
+        throw new Error('customExecutor requires an executor and { lifecycle: "self-managed" }.');
+    }
+    const name = executorName(executor);
+    const wrapper = {
+        ...(name ? { name } : {}),
+        execute: executor.execute.bind(executor),
+        ...(executor.close ? { close: executor.close.bind(executor) } : {}),
+        ...(isAdmittingExecutor(executor)
+            ? {
+                acquire: executor.acquire.bind(executor),
+                ...(executor.admissionSnapshot ? { admissionSnapshot: executor.admissionSnapshot.bind(executor) } : {}),
+            }
+            : {}),
+    };
+    return brandExecutor(wrapper, "self-managed");
+}

package/dist/executor-result.js

@@ -1,6 +1,6 @@
 import { msg } from "./errors.js";
 /** ~6k tokens. Sandbox code should filter data down before returning. */
-const MAX_EXECUTE_RESULT_CHARS = 24_000;
+export const MAX_EXECUTE_RESULT_CHARS = 24_000;
 export const MAX_EXECUTE_LOG_CHARS = 4_000;
 export function serializeResultText(value) {
     const serialized = JSON.stringify(value);
@@ -18,30 +18,45 @@ const TRUNCATION_HINT = "filter/map/slice data inside execute_code and return on
  * of what the program returned, and truncation happens exactly once no matter
  * how many hops the value takes.
  */
-function truncationEnvelope(text) {
+function truncationEnvelope(text, maxChars, totalChars = text.length, hint = TRUNCATION_HINT) {
     const base = {
         truncated: true,
         preview: "",
-        totalChars: text.length,
-        hint: TRUNCATION_HINT,
+        totalChars,
+        hint,
     };
-    let budget = Math.max(0, MAX_EXECUTE_RESULT_CHARS - JSON.stringify(base).length);
+    let budget = Math.max(0, maxChars - JSON.stringify(base).length);
     for (let attempt = 0; attempt < 8 && budget > 0; attempt += 1) {
         const candidate = { ...base, preview: text.slice(0, budget) };
         const size = JSON.stringify(candidate).length;
-        if (size <= MAX_EXECUTE_RESULT_CHARS)
+        if (size <= maxChars)
             return candidate;
         // Every character costs at least one serialized character, so scaling by
         // the overshoot ratio (minus a step) strictly shrinks the budget.
-        budget = Math.max(0, Math.floor(budget * (MAX_EXECUTE_RESULT_CHARS / size)) - 8);
+        budget = Math.max(0, Math.floor(budget * (maxChars / size)) - 8);
     }
     return { ...base, preview: text.slice(0, budget) };
 }
-export function guardExecuteResultValue(value) {
+export function guardExecuteResultValue(value, maxChars = MAX_EXECUTE_RESULT_CHARS, hintPrefix) {
+    const hint = hintPrefix ? `${hintPrefix} ${TRUNCATION_HINT}` : TRUNCATION_HINT;
     const text = serializeResultText(value);
-    if (text.length <= MAX_EXECUTE_RESULT_CHARS)
+    if (text.length <= maxChars)
         return value;
-    return truncationEnvelope(text);
+    // A custom executor may already have guarded this value at a larger cap.
+    // Shrink its preview once more without nesting notices or losing original size.
+    if (value !== null && typeof value === "object") {
+        const prior = value;
+        if (prior.truncated === true &&
+            prior.hint === TRUNCATION_HINT &&
+            typeof prior.preview === "string" &&
+            typeof prior.totalChars === "number" &&
+            Number.isSafeInteger(prior.totalChars) &&
+            prior.totalChars >= prior.preview.length &&
+            Object.keys(value).length === 4) {
+            return truncationEnvelope(prior.preview, maxChars, prior.totalChars, hint);
+        }
+    }
+    return truncationEnvelope(text, maxChars, text.length, hint);
 }
 export function truncateExecuteText(text, max) {
     if (text.length <= max)
@@ -49,8 +64,8 @@ export function truncateExecuteText(text, max) {
     return `${text.slice(0, max)}\n--- TRUNCATED (${text.length} chars total) — filter/map/slice data inside your code and return only what you need ---`;
 }
 /**
- * Apply the public execute_code result/log policy before a child result enters
- * IPC. The parent repeats the guard for third-party Executor implementations.
+ * Validate serialization before IPC without discarding the program return.
+ * The host applies the presentation cap after it can stash the full value.
  */
 export function prepareExecuteResultForTransport(outcome) {
     // QuickJS already bounds captured logs at source (entries + cumulative
@@ -63,12 +78,14 @@ export function prepareExecuteResultForTransport(outcome) {
         return {
             result: undefined,
             error: outcome.error,
+            ...(outcome.failure ? { failure: outcome.failure } : {}),
             ...(logs ? { logs } : {}),
         };
     }
     try {
+        serializeResultText(outcome.result);
         return {
-            result: guardExecuteResultValue(outcome.result),
+            result: outcome.result,
             ...(logs ? { logs } : {}),
         };
     }

package/dist/executors/quickjs-child.js

@@ -1,6 +1,7 @@
 import { prepareExecuteResultForTransport } from "../executor-result.js";
+import { InvocationFailure } from "../invocation.js";
 import { msg } from "../errors.js";
-import { MAX_QUICKJS_IPC_BYTES, MAX_QUICKJS_HOST_RPC_BYTES, serializedBytes, stringifyBounded, } from "./quickjs-protocol.js";
+import { MAX_QUICKJS_IPC_BYTES, MAX_QUICKJS_RESULT_BYTES, QUICKJS_RESULT_CHUNK_CHARS, MAX_QUICKJS_HOST_RPC_BYTES, serializedBytes, stringifyBounded, } from "./quickjs-protocol.js";
 import { executeQuickJs, prepareQuickJs } from "./quickjs-runtime.js";
 let activeJobId;
 let nextCallId = 1;
@@ -38,9 +39,7 @@ function provider(name, jobId, prelude) {
                 return result;
             };
         },
-        getOwnPropertyDescriptor: (_target, key) => typeof key === "string"
-            ? { configurable: true, enumerable: false }
-            : undefined,
+        getOwnPropertyDescriptor: (_target, key) => typeof key === "string" ? { configurable: true, enumerable: false } : undefined,
     });
     return { name, fns: functions, ...(prelude ? { prelude } : {}) };
 }
@@ -52,6 +51,13 @@ function fixedTransportFailure(message) {
         },
     };
 }
+function sendResult(jobId, payloadJson) {
+    for (let offset = 0; offset + QUICKJS_RESULT_CHUNK_CHARS < payloadJson.length; offset += QUICKJS_RESULT_CHUNK_CHARS) {
+        send({ type: "result-chunk", jobId, payloadJson: payloadJson.slice(offset, offset + QUICKJS_RESULT_CHUNK_CHARS) });
+    }
+    const tail = Math.floor((payloadJson.length - 1) / QUICKJS_RESULT_CHUNK_CHARS) * QUICKJS_RESULT_CHUNK_CHARS;
+    send({ type: "result", jobId, payloadJson: payloadJson.slice(tail) });
+}
 async function run(payload) {
     if (activeJobId !== undefined) {
         throw new Error("QuickJS child received overlapping executions.");
@@ -70,12 +76,12 @@ async function run(payload) {
         };
         let payloadJson;
         try {
-            payloadJson = stringifyBounded(prepared, "QuickJS execution result");
+            payloadJson = stringifyBounded(prepared, "QuickJS execution result", MAX_QUICKJS_RESULT_BYTES);
         }
         catch (err) {
-            payloadJson = JSON.stringify(fixedTransportFailure(`QuickJS execution result exceeded the ${MAX_QUICKJS_IPC_BYTES}-byte IPC limit: ${msg(err)}`));
+            payloadJson = JSON.stringify(fixedTransportFailure(`QuickJS execution result exceeded the ${MAX_QUICKJS_RESULT_BYTES}-byte aggregate transport limit: ${msg(err)}`));
         }
-        send({ type: "result", jobId: payload.id, payloadJson });
+        sendResult(payload.id, payloadJson);
     }
     finally {
         activeJobId = undefined;
@@ -104,7 +110,7 @@ process.on("message", (message) => {
             if (result.ok)
                 request.resolve(result.value);
             else
-                request.reject(new Error(result.error));
+                request.reject(result.call ? new InvocationFailure(result.call) : new Error(result.error));
         }
         catch (err) {
             request.reject(new Error(`Invalid host result: ${msg(err)}`));
@@ -119,7 +125,7 @@ process.on("message", (message) => {
     const payload = JSON.parse(message.payloadJson);
     void run(payload).catch((err) => {
         const payloadJson = JSON.stringify(fixedTransportFailure(`QuickJS child failed: ${msg(err)}`));
-        send({ type: "result", jobId: payload.id, payloadJson });
+        sendResult(payload.id, payloadJson);
         activeJobId = undefined;
     });
 });

package/dist/executors/quickjs-protocol.js

@@ -1,10 +1,9 @@
-// An execution result is serialized once into payloadJson and again as that
-// string is embedded in ChildToParentMessage. Captured logs therefore get a
-// separate 512 KiB budget measured after both JSON encodings. The final result
-// is shaped to 24k characters; even if every character takes its worst-case
-// seven transport bytes, that leaves ample structural overhead below this hard
-// process.send ceiling.
+// Result messages remain bounded even when a full return travels in chunks.
+// The host's presentation guard stashes the completed value after assembly.
 export const MAX_QUICKJS_IPC_BYTES = 1024 * 1024;
+/** Aggregate result transport bound, independent of per-message IPC and log caps. */
+export const MAX_QUICKJS_RESULT_BYTES = 64 * 1024 * 1024;
+export const QUICKJS_RESULT_CHUNK_CHARS = 65_536;
 export const MAX_QUICKJS_LOG_TRANSPORT_BYTES = 512 * 1024;
 /** Preserve #84's stopgap before a host value enters the child/WASM process. */
 export const MAX_QUICKJS_HOST_RPC_BYTES = 256 * 1024;

package/dist/executors/quickjs-runtime.js

@@ -7,10 +7,11 @@
 // running the provider function; `executePendingJobs` drives guest
 // continuations from a host-side loop. Values cross the boundary as JSON, so
 // provider args/results must be JSON-serializable.
-import { getQuickJS, } from "quickjs-emscripten";
+import { getQuickJS } from "quickjs-emscripten";
+import { InvocationFailure } from "../invocation.js";
 import { msg } from "../errors.js";
 import { withoutProgramTerminator } from "../program-source.js";
-import { hostCallLabel, MAX_QUICKJS_LOG_TRANSPORT_BYTES, serializedBytes, } from "./quickjs-protocol.js";
+import { hostCallLabel, MAX_QUICKJS_LOG_TRANSPORT_BYTES, serializedBytes } from "./quickjs-protocol.js";
 /** Load and compile the shared QuickJS WASM module before a run budget starts. */
 export async function prepareQuickJs() {
     await getQuickJS();
@@ -82,8 +83,8 @@ export function normalizeCode(code) {
  * and fail closed there.
  */
 function setupScript(providers) {
-    // X11: raw replies carry an authenticated frame. Capture the bridge and
-    // codec before guest code runs, and expose only the decoded provider calls.
+    // Capture the host bridge and codec before guest code runs.
+    // Rejections are native guest Errors created and retained by the host.
     const lines = [
         `(() => {
   const call = globalThis.__call;
@@ -102,7 +103,6 @@ function setupScript(providers) {
   })();
   const invoke = async (ns, fn, args) => {
     const r = parse(await call(ns, fn, stringify(args)));
-    if (!r.ok) throw new GuestError(r.error);
     return r.value;
   };
   const namespace = (ns) => freeze(new ProxyConstructor(create(null), {
@@ -117,24 +117,14 @@ function setupScript(providers) {
         if (p.prelude)
             lines.push(p.prelude);
     }
-    lines.push(`const GuestError = globalThis.Error;
-})();`);
+    lines.push(`})();`);
     return lines.join("\n");
 }
-/** True when a dumped error is QuickJS's deadline-interrupt signal. */
-function isInterrupt(dumped) {
-    if (!dumped || typeof dumped !== "object")
-        return false;
-    const e = dumped;
-    return e.name === "InternalError" && e.message === "interrupted";
-}
 function formatGuestError(dumped) {
     if (dumped && typeof dumped === "object") {
         const e = dumped;
         if (e.message != null) {
-            return e.name != null && e.name !== "Error"
-                ? `${String(e.name)}: ${String(e.message)}`
-                : String(e.message);
+            return e.name != null && e.name !== "Error" ? `${String(e.name)}: ${String(e.message)}` : String(e.message);
         }
     }
     return typeof dumped === "string" ? dumped : JSON.stringify(dumped);
@@ -166,6 +156,7 @@ function installBridge(ctx, providers, logs, onLog) {
         aborted: false,
         wake: () => { },
         waitForSettle: Promise.resolve(),
+        failures: [],
     };
     armWake(bridge);
     // Keep both the in-memory character budget and the twice-JSON-encoded
@@ -195,8 +186,7 @@ function installBridge(ctx, providers, logs, onLog) {
         }
         const entryTransportBytes = logTransportBytes(entry);
         if (logTotalChars + entry.length > MAX_LOG_TOTAL_CHARS ||
-            logTotalTransportBytes + entryTransportBytes >
-                MAX_QUICKJS_LOG_TRANSPORT_BYTES - MAX_LOG_MARKER_TRANSPORT_BYTES) {
+            logTotalTransportBytes + entryTransportBytes > MAX_QUICKJS_LOG_TRANSPORT_BYTES - MAX_LOG_MARKER_TRANSPORT_BYTES) {
             captureLog(LOG_SIZE_LIMIT_MARKER);
             logBudgetSpent = true;
             return;
@@ -211,9 +201,7 @@ function installBridge(ctx, providers, logs, onLog) {
     const invoke = async (ns, fn, argsJson) => {
         try {
             const provider = byName.get(ns);
-            const f = provider && Object.hasOwn(provider.fns, fn)
-                ? provider.fns[fn]
-                : undefined;
+            const f = provider && Object.hasOwn(provider.fns, fn) ? provider.fns[fn] : undefined;
             if (!f)
                 throw new Error(`Unknown function ${ns}.${fn}`);
             const args = JSON.parse(argsJson);
@@ -231,10 +219,10 @@ function installBridge(ctx, providers, logs, onLog) {
             if (exceedsUtf8ByteLimit(json, MAX_HOST_RESULT_BYTES)) {
                 throw new Error(`Host result from ${label} exceeds the ${MAX_HOST_RESULT_BYTES}-byte serialized bridge limit.`);
             }
-            return json;
+            return { json };
         }
         catch (err) {
-            return JSON.stringify({ ok: false, error: msg(err) });
+            return { error: err };
         }
     };
     const callFn = ctx.newFunction("__call", (nsH, fnH, argsH) => {
@@ -243,16 +231,42 @@ function installBridge(ctx, providers, logs, onLog) {
         const argsJson = ctx.getString(argsH);
         const deferred = ctx.newPromise();
         bridge.pending++;
-        void invoke(ns, fn, argsJson).then((json) => {
+        void invoke(ns, fn, argsJson).then((reply) => {
             bridge.pending--;
             if (bridge.aborted) {
                 // Context is (about to be) torn down — settle nothing, free our handles.
                 deferred.dispose();
             }
             else {
-                const h = ctx.newString(json);
-                deferred.resolve(h);
-                h.dispose();
+                if ("json" in reply) {
+                    const h = ctx.newString(reply.json);
+                    deferred.resolve(h);
+                    h.dispose();
+                }
+                else {
+                    const error = ctx.newError();
+                    const message = ctx.unwrapResult(ctx.evalCode(JSON.stringify(msg(reply.error).slice(0, 4_000))));
+                    ctx.setProp(error, "message", message);
+                    message.dispose();
+                    if (reply.error instanceof InvocationFailure) {
+                        const call = reply.error.details;
+                        // The error identity and typed facts stay in host state. A guest
+                        // may edit public fields without changing the retained failure.
+                        bridge.failures.push({ error: error.dup(), call });
+                        for (const [key, value] of Object.entries({
+                            code: call.code,
+                            retryable: call.retryable,
+                            details: call,
+                            data: call,
+                        })) {
+                            const property = ctx.unwrapResult(ctx.evalCode(`(${JSON.stringify(value)})`));
+                            ctx.setProp(error, key, property);
+                            property.dispose();
+                        }
+                    }
+                    deferred.reject(error);
+                    error.dispose();
+                }
             }
             bridge.wake();
         });
@@ -296,14 +310,18 @@ export async function executeQuickJs(code, providers, options, onLog) {
         if (!inGuest)
             return false;
         wallInterrupted = Date.now() >= deadline;
-        cpuInterrupted =
-            cpuUsedMs + (Date.now() - segmentStarted) >= cpuTimeMs;
+        cpuInterrupted = cpuUsedMs + (Date.now() - segmentStarted) >= cpuTimeMs;
         return wallInterrupted || cpuInterrupted;
     });
+    let describeError;
     const logs = [];
     const bridge = installBridge(ctx, providers, logs, onLog);
     const finish = (r) => {
         bridge.aborted = true;
+        describeError?.dispose();
+        for (const failure of bridge.failures)
+            failure.error.dispose();
+        bridge.failures.length = 0;
         // Outstanding host calls still hold deferred-promise handles; their
         // callbacks free them and wake the drain, which disposes the context
         // once the last straggler settles. Re-arm before every wait so the
@@ -326,32 +344,119 @@ export async function executeQuickJs(code, providers, options, onLog) {
         }
         return logs.length > 0 ? { ...r, logs } : r;
     };
-    const fail = (error) => finish({ result: undefined, error });
+    const rejected = (error) => {
+        // Interrupt/deadline facts are host state, never inferred by inspecting
+        // the thrown value. Do not reenter a guest whose budget has ended.
+        if (wallInterrupted || Date.now() >= deadline)
+            return timedOut();
+        if (cpuInterrupted || cpuUsedMs >= cpuTimeMs)
+            return { result: undefined, error: cpuTimeoutError };
+        const call = bridge.failures.find((failure) => ctx.eq(failure.error, error))?.call;
+        let description = { name: "Error", message: "Program threw a value." };
+        const type = ctx.typeof(error);
+        if (type === "string")
+            description = ctx.getString(error).slice(0, 4000);
+        else if (type === "number")
+            description = ctx.getNumber(error);
+        else if (type === "undefined")
+            description = "undefined";
+        else if (type === "boolean")
+            description = ctx.eq(error, ctx.true);
+        else if (ctx.eq(error, ctx.null))
+            description = null;
+        else if (describeError) {
+            const describe = describeError;
+            const described = runGuest(() => ctx.callFunction(describe, ctx.undefined, error));
+            if (described.error)
+                described.error.dispose();
+            else {
+                description = JSON.parse(ctx.getString(described.value)) ?? description;
+                described.value.dispose();
+            }
+            if (wallInterrupted || Date.now() >= deadline)
+                return timedOut();
+            if (cpuInterrupted || cpuUsedMs >= cpuTimeMs)
+                return { result: undefined, error: cpuTimeoutError };
+        }
+        const name = description && typeof description === "object" && "name" in description && typeof description.name === "string"
+            ? description.name
+            : "Error";
+        const stack = description && typeof description === "object" && "stack" in description && typeof description.stack === "string"
+            ? description.stack
+            : "";
+        const location = /:(\d+)(?::\d+)?\)?(?:\n|$)/.exec(stack);
+        return {
+            result: undefined,
+            error: formatGuestError(description).slice(0, 4000),
+            failure: {
+                name,
+                ...(call ? { call } : {}),
+                ...(location ? { line: Math.max(1, Number(location[1]) - 1) } : {}),
+            },
+        };
+    };
     const timedOut = () => ({
         result: undefined,
         error: timeoutError,
+        failure: {
+            name: "TimeoutError",
+            timeout: { elapsedMs: Date.now() - (deadline - timeoutMs), deadlineMs: timeoutMs },
+        },
         timedOut: true,
     });
+    // Keep this diagnostic function in a host-owned handle. Error.isError
+    // checks the native brand without Proxy traps. Own data descriptors of
+    // native Errors are safe to read; accessors and arbitrary thrown objects
+    // get a fixed description instead of dump's guest serialization/getters.
+    const described = runGuest(() => ctx.evalCode(`(() => {
+        const isError = Error.isError;
+        const descriptor = Object.getOwnPropertyDescriptor;
+        const prototypeOf = Object.getPrototypeOf;
+        const hasOwn = Function.prototype.call.bind(Object.prototype.hasOwnProperty);
+        const slice = Function.prototype.call.bind(String.prototype.slice);
+        const stringify = JSON.stringify;
+        const prototypes = [
+          [Error.prototype, "Error"], [TypeError.prototype, "TypeError"],
+          [SyntaxError.prototype, "SyntaxError"], [ReferenceError.prototype, "ReferenceError"],
+          [RangeError.prototype, "RangeError"], [EvalError.prototype, "EvalError"],
+          [URIError.prototype, "URIError"], [AggregateError.prototype, "AggregateError"]
+        ];
+        return (error) => {
+          if (!isError(error)) return "null";
+          const text = (key, fallback, limit) => {
+            const own = descriptor(error, key);
+            return own && hasOwn(own, "value") && typeof own.value === "string"
+              ? slice(own.value, 0, limit) : fallback;
+          };
+          const prototype = prototypeOf(error);
+          let name = "Error";
+          for (let i = 0; i < prototypes.length; i++) {
+            if (prototype === prototypes[i][0]) { name = prototypes[i][1]; break; }
+          }
+          return stringify({ __proto__: null, name: text("name", name, 64),
+            message: text("message", "Program threw a value.", 4000), stack: text("stack", "", 1000) });
+        };
+      })()`));
+    if (described.error) {
+        const rejection = rejected(described.error);
+        described.error.dispose();
+        return finish(rejection);
+    }
+    describeError = described.value;
     const setup = runGuest(() => ctx.evalCode(setupScript(providers)));
     if (setup.error) {
-        const detail = formatGuestError(ctx.dump(setup.error));
+        const rejection = rejected(setup.error);
         setup.error.dispose();
-        if (wallInterrupted)
-            return finish(timedOut());
-        if (cpuInterrupted)
-            return fail(cpuTimeoutError);
-        return fail(`Sandbox setup failed: ${detail}`);
+        return finish(rejection.timedOut || cpuInterrupted
+            ? rejection
+            : { ...rejection, error: `Sandbox setup failed: ${rejection.error}` });
     }
     setup.value.dispose();
     const evaluated = runGuest(() => ctx.evalCode(`Promise.resolve((\n${normalizeCode(code)}\n)())`));
     if (evaluated.error) {
-        const dumped = ctx.dump(evaluated.error);
+        const rejection = rejected(evaluated.error);
         evaluated.error.dispose();
-        if (isInterrupt(dumped) && wallInterrupted)
-            return finish(timedOut());
-        if (isInterrupt(dumped) && cpuInterrupted)
-            return fail(cpuTimeoutError);
-        return fail(formatGuestError(dumped));
+        return finish(rejection);
     }
     const promiseHandle = evaluated.value;
     // Drive the guest: run microtask jobs, inspect the result promise,
@@ -364,15 +469,9 @@ export async function executeQuickJs(code, providers, options, onLog) {
             }
             const jobs = runGuest(() => ctx.runtime.executePendingJobs());
             if (jobs.error) {
-                const dumped = ctx.dump(jobs.error);
+                const rejection = rejected(jobs.error);
                 jobs.error.dispose();
-                if (isInterrupt(dumped) && wallInterrupted) {
-                    return timedOut();
-                }
-                if (isInterrupt(dumped) && cpuInterrupted) {
-                    return { result: undefined, error: cpuTimeoutError };
-                }
-                return { result: undefined, error: formatGuestError(dumped) };
+                return rejection;
             }
             const state = ctx.getPromiseState(promiseHandle);
             if (state.type === "fulfilled") {
@@ -381,15 +480,9 @@ export async function executeQuickJs(code, providers, options, onLog) {
                 return { result };
             }
             if (state.type === "rejected") {
-                const dumped = ctx.dump(state.error);
+                const rejection = rejected(state.error);
                 state.error.dispose();
-                if (isInterrupt(dumped) && wallInterrupted) {
-                    return timedOut();
-                }
-                if (isInterrupt(dumped) && cpuInterrupted) {
-                    return { result: undefined, error: cpuTimeoutError };
-                }
-                return { result: undefined, error: formatGuestError(dumped) };
+                return rejection;
             }
             if (bridge.pending === 0) {
                 return {