@boundaryml/baml-bridge-web 0.0.0 → 0.15.0

package/dist/workerd/shared/proto.js

@@ -4,10 +4,11 @@
 // Decodes the BamlOutboundResult envelope → TS objects (call results), and
 // bare BamlOutboundValue bytes → TS objects (host-callable args).
 import { baml_bridge } from './proto/baml_cffi.js';
-import { BamlHandle, BamlImage, BamlAudio, BamlVideo, BamlPdf, registerHostCallable, releaseHostCallable, completeHostCall, } from '../native.js';
+import { BamlHandle, BamlImage, BamlAudio, BamlVideo, BamlPdf, registerHostCallable, releaseHostCallable, completeHostCall, getRuntime, newFunctionCall, } from '../native.js';
 import { BamlStream } from './stream.js';
-import { BamlAbortError, BamlCancelledError, BamlError, BamlPanic } from './errors.js';
-import { registerHostOpaque, tryRehydrateHostValueByKey, } from './host_value_registry.js';
+import { BamlAbortError, BamlCancelledError, BamlClientError, BamlError, BamlInvalidArgumentError, BamlPanic } from './errors.js';
+import { handleExitPanic } from './platform.js';
+import { registerHostOpaque, releaseHostOpaque, tryRehydrateHostValueByKey, } from './host_value_registry.js';
 import { getTypeMap } from './typemap.js';
 import { lowerTypeToWireTy, outboundTyToBamlType } from './wire_ty.js';
 const CallFunctionArgs = baml_bridge.cffi.v1.CallFunctionArgs;
@@ -30,6 +31,16 @@ export class HostCallableSyncError extends Error {
         this.name = 'HostCallableSyncError';
     }
 }
+function rollbackHostCallables(keys) {
+    for (let index = keys.length - 1; index >= 0; index -= 1) {
+        try {
+            releaseHostCallable(keys[index]);
+        }
+        catch {
+            // Best-effort cleanup; never mask the original encode failure.
+        }
+    }
+}
 /**
  * Generic-class instances declare their TypeVar names (declaration order) in a
  * static `$generic` field that codegen emits; this reads it back. Returns the
@@ -81,8 +92,8 @@ function setInboundValue(iv, value, ctx) {
         // path. Any future dispatch-backed handle type must be guarded here.
         if (ctx.syncMode && value.handleType === BamlHandleType.HOST_VALUE_CALLABLE) {
             throw new HostCallableSyncError('host callables are only supported on the async call path; use the async API ' +
-                '(callFunction) instead of callFunctionSync. The sync path blocks the Node main ' +
-                'thread, so the host callback can never run and the call would hang.');
+                '(callFunction) instead of callFunctionSync. The sync path occupies the single ' +
+                'JavaScript/bridge event loop, so the host callback cannot await a future turn.');
         }
         // The Rust inbound decoder drains handle-table entries. Send a fresh
         // cloned key so the JS-owned handle remains valid for later calls.
@@ -113,8 +124,8 @@ function setInboundValue(iv, value, ctx) {
         // tsfn, which would otherwise be orphaned).
         if (ctx.syncMode) {
             throw new HostCallableSyncError('host callables are only supported on the async call path; use the async API ' +
-                '(callFunction) instead of callFunctionSync. The sync path blocks the Node main ' +
-                'thread, so the host callback can never run and the call would hang.');
+                '(callFunction) instead of callFunctionSync. The sync path occupies the single ' +
+                'JavaScript/bridge event loop, so the host callback cannot await a future turn.');
         }
         // JS callable → register a dispatch wrapper in the host-value
         // registry and emit `Handle{key, HOST_VALUE_CALLABLE}`. The Rust
@@ -136,13 +147,12 @@ function setInboundValue(iv, value, ctx) {
         iv.listValue = { values: listVal };
     }
     else if (value !== null && typeof value === 'object') {
-        // Any remaining object — a plain object OR a codegen-emitted class
-        // instance (e.g. `new Resume({...})`) — encodes as `map_value` with
-        // no FQN tag. The Rust side's `coerce_arg_to_declared_type` reshapes
-        // it against the function's declared parameter type (the 10a
-        // typemap-free encode simplification). `Object.entries` yields the
-        // class's own enumerable fields, set by the constructor's
-        // `Object.assign(this, init)`. The specific built-in wrappers
+        // Any remaining object is either a plain object or a codegen-emitted
+        // class instance. Plain objects encode as `map_value` and are reshaped
+        // against contextual types; generated instances carry a sparse nominal
+        // annotation when the typemap identifies their constructor.
+        // `Object.entries` yields the class's own enumerable fields, set by the
+        // constructor's `Object.assign(this, init)`. The specific built-in wrappers
         // (BamlHandle/BamlStream/media) are handled by the instanceof
         // branches above, so they never reach here.
         //
@@ -173,30 +183,27 @@ function setInboundValue(iv, value, ctx) {
                     setInboundValue(childVal, v, ctx);
                     classFields.push({ stringKey: k, value: childVal });
                 }
-                iv.classValue = { classTy: { name: fqn }, fields: classFields };
+                iv.valueType = { classTy: { name: fqn } };
+                iv.classValue = { fields: classFields };
                 return;
             }
         }
-        // Generic class instance → a FQN-tagged `class_value` carrying the
-        // value-level class type-args channel (`class_ty`). Unlike a non-generic
-        // class instance (which encodes as a bare `map_value` for the engine to
-        // reshape against the declared param type), a generic instance MUST send
-        // its concrete type args: the engine strictly rejects coercing a bare map
-        // into a generic class slot ("a bare map carries no class type
-        // arguments"). The args come from the optional `$types` instance field;
-        // an absent binding lowers to the unknown/top type. Mirrors
-        // bridge_python's pydantic-generic-metadata path in proto.py, which sets
-        // `class_value.class_ty` for a generic instance.
+        // A codegen class instance has nominal identity even though its payload
+        // is structurally object-shaped. Preserve that identity with a sparse
+        // node annotation. For a generic class, include exact args when every
+        // `$types` entry is present; otherwise send only the class name. The
+        // engine may refine that nominal hint from one contextual class but
+        // will not use it to choose between two concrete instantiations of the
+        // same generic class in a union.
         if (isClassInstance) {
+            const fqn = getTypeMap().jsTypeToBamlType(value.constructor);
             const params = genericParamNames(value);
-            if (params) {
-                const fqn = getTypeMap().jsTypeToBamlType(value.constructor);
+            if (fqn) {
                 const userTypes = value.$types;
-                const typeArgs = params.map((p) => lowerTypeToWireTy(userTypes?.[p]));
                 const classFields = [];
                 for (const [k, v] of Object.entries(value)) {
                     // Skip method bindings (behavior, not state) and the synthetic
-                    // `$types` carrier (it rides `class_ty`, not the field list).
+                    // `$types` carrier (it rides `value_type`, not the field list).
                     if (typeof v === 'function')
                         continue;
                     if (k === '$types')
@@ -205,7 +212,14 @@ function setInboundValue(iv, value, ctx) {
                     setInboundValue(childVal, v, ctx);
                     classFields.push({ stringKey: k, value: childVal });
                 }
-                iv.classValue = { classTy: { name: fqn, typeArgs }, fields: classFields };
+                if (params && userTypes !== undefined && params.every((p) => userTypes[p] !== undefined)) {
+                    const typeArgs = params.map((p) => lowerTypeToWireTy(userTypes[p]));
+                    iv.valueType = { classTy: { name: fqn, typeArgs } };
+                }
+                else {
+                    iv.valueType = { classTy: { name: fqn, typeArgs: [] } };
+                }
+                iv.classValue = { fields: classFields };
                 return;
             }
         }
@@ -236,8 +250,8 @@ function setInboundValue(iv, value, ctx) {
  * host-value table and is normally released only when the engine GCs the
  * `HostClosure` it allocated and fires the C release callback (a GC-timed
  * release, drained by the engine after collection).
- * Because the Node tsfn is built with `weak::<false>` it keeps a strong libuv
- * ref, so a *leaked* registry entry can also keep the Node process from
+ * Because the host bridge is built with `weak::<false>` it keeps a strong host event loop
+ * ref, so a *leaked* registry entry can also keep the JavaScript realm from
  * exiting — which is exactly why the encode-error rollback below matters: if a
  * later kwarg fails, the engine never sees (and so never releases) the keys we
  * already registered, so we release them here.
@@ -247,6 +261,9 @@ export function encodeCallArgs(kwargs, options) {
     if (callId === 0n) {
         throw new TypeError('callId must be a nonzero uint64');
     }
+    if (options.functionName !== undefined && options.functionHandle !== undefined) {
+        throw new TypeError('exactly one BAML call target may be set');
+    }
     const ctx = { syncMode: options.syncMode ?? false, registered: [] };
     try {
         const entries = [];
@@ -265,22 +282,17 @@ export function encodeCallArgs(kwargs, options) {
             kwargs: entries,
             callId: callId.toString(),
             typeArgs,
+            functionName: options.functionName,
+            functionHandle: options.functionHandle,
         });
         return Uint8Array.from(CallFunctionArgs.encode(msg).finish());
     }
     catch (err) {
         // Roll back any host callables registered before the failure so
-        // they don't leak in the registry (and pin the libuv loop) for the
-        // life of the process — the call never reaches the engine, so the
+        // they don't leak in the registry (and pin the host event loop loop) for the
+        // life of the runtime — the call never reaches the engine, so the
         // engine would never release them.
-        for (const k of ctx.registered) {
-            try {
-                releaseHostCallable(k);
-            }
-            catch {
-                // Best-effort cleanup; never mask the original error.
-            }
-        }
+        rollbackHostCallables(ctx.registered);
         throw err;
     }
 }
@@ -376,6 +388,9 @@ function decodeValueHolder(holder, typeMap) {
             throw new BamlError('decoded handle has HANDLE_UNSPECIFIED handle_type');
         }
         const handle = new BamlHandle(holder.handleValue.key, ht);
+        if (ht === BamlHandleType.FUNCTION_REF) {
+            return decodeBamlClosure(handle, holder.handleValue.ty?.function);
+        }
         if (ht === BamlHandleType.ADT_MEDIA_IMAGE)
             return BamlImage._fromHandle(handle);
         if (ht === BamlHandleType.ADT_MEDIA_AUDIO)
@@ -387,14 +402,14 @@ function decodeValueHolder(holder, typeMap) {
         if (ht === BamlHandleType.ADT_TAGGED_HEAP_HANDLE) {
             // Dispatch via the typemap: every tagged-heap class self-registers
             // under its engine FQN (codegen emits the entry, e.g.
-            // `baml.llm.Stream → BamlStream`), so any class is reachable without
+            // `ai.stream.Stream → BamlStream`), so any class is reachable without
             // special-casing here. Mirrors bridge_python's `_decode_handle`
             // ADT_TAGGED_HEAP_HANDLE arm (sdks/python/.../proto.py).
             // The handle's `ty` is a full `BamlTy`; the typed-wrapper FQN lives
             // on its class variant (a non-class `ty` reads back as `''`).
             const fqn = holder.handleValue.ty?.classTy?.name ?? '';
             const Cls = typeMap.getClass(fqn);
-            return Cls._fromHandle(handle);
+            return Cls._fromHandle(handle, fqn);
         }
         // ADT_MEDIA_GENERIC has no typed wrapper — stays a bare BamlHandle.
         return handle;
@@ -411,6 +426,45 @@ function decodeValueHolder(holder, typeMap) {
     // null BAML result.
     return null;
 }
+function decodeBamlClosure(handle, functionTy) {
+    const params = functionTy?.params ?? [];
+    const required = params.filter((param) => param.mode !== baml_bridge.cffi.v1.BamlTyFunctionParamMode.BAML_TY_FUNCTION_PARAM_MODE_OPTIONAL);
+    const optional = params.filter((param) => param.mode === baml_bridge.cffi.v1.BamlTyFunctionParamMode.BAML_TY_FUNCTION_PARAM_MODE_OPTIONAL);
+    const requiredNames = required.map((param, index) => param.name ?? `arg${index}`);
+    const optionalNames = new Set(optional.map((param, index) => param.name ?? `arg${required.length + index}`));
+    return (...args) => {
+        if (args.length > requiredNames.length + 1) {
+            throw new TypeError(`got ${args.length} arguments but this BAML closure accepts ` +
+                `${requiredNames.length} required arguments and one optional-arguments object`);
+        }
+        const kwargs = {};
+        const positionalCount = Math.min(args.length, requiredNames.length);
+        for (let index = 0; index < positionalCount; index += 1) {
+            kwargs[requiredNames[index]] = args[index];
+        }
+        if (args.length > requiredNames.length) {
+            const options = args[requiredNames.length];
+            if (options === null || Array.isArray(options) || typeof options !== 'object') {
+                throw new TypeError('optional BAML closure arguments must be passed as an object');
+            }
+            for (const [name, value] of Object.entries(options)) {
+                if (!optionalNames.has(name)) {
+                    throw new TypeError(`unknown optional argument ${JSON.stringify(name)}`);
+                }
+                if (value !== undefined)
+                    kwargs[name] = value;
+            }
+        }
+        const runtime = getRuntime();
+        const callId = BigInt(newFunctionCall());
+        const encodedArgs = encodeCallArgs(kwargs, {
+            syncMode: true,
+            callId,
+            functionHandle: handle.key,
+        });
+        return decodeCallResult(runtime.callFunctionSync(encodedArgs));
+    };
+}
 /**
  * Decode a `class_value` to a typed instance via the typemap. When the FQN is
  * in the typemap (the generated-SDK path), construct `new Cls(fieldDict)`
@@ -448,7 +502,7 @@ function decodeClass(classValue, typeMap) {
             // Repopulate a generic instance's `$types` from the wire's positional
             // `type_args` (the value-level type channel), keyed by the class's
             // static `$generic` param names — the decode-side mirror of the
-            // encoder's `class_ty`. Defined non-enumerable so it neither perturbs
+            // encoder's sparse `value_type`. Defined non-enumerable so it neither perturbs
             // structural equality (`toEqual`) nor re-encodes as a data field,
             // while still being readable by a later generic instance-method call.
             const params = Array.isArray(Ctor.$generic) ? Ctor.$generic : null;
@@ -602,13 +656,25 @@ function cancellationAbortError(message) {
         reason: new BamlCancelledError(message),
     });
 }
+function errorForClassName(formatted, detail) {
+    switch (detail.className) {
+        case 'baml.errors.InvalidArgument':
+            return new BamlInvalidArgumentError(formatted, detail);
+        case 'baml.errors.GenericSdkError':
+        case 'baml.errors.CompilationError':
+        case 'baml.errors.AccessError':
+            return new BamlClientError(formatted, detail);
+        default:
+            return new BamlError(formatted, detail);
+    }
+}
 /**
  * Decode a `BamlOutboundResult` envelope (the engine's call-result wire shape
  * after 31c/31e). The `ok` arm returns the decoded value; the `error`/`panic`
  * arms **throw** a `BamlError`/`BamlPanic` carrying the fully decoded thrown
  * value (`.value`), the BAML trace (`.bamlTrace`), and the class FQN
  * (`.className`), with a readable formatted `.message`. An `is_exit_panic`
- * (clean `baml.sys.exit`) terminates the process via `process.exit(code)`
+ * (clean `baml.sys.exit`) terminates the runtime via `runtime.exit(code)`
  * rather than throwing.
  */
 export function decodeCallResult(data) {
@@ -619,10 +685,10 @@ export function decodeCallResult(data) {
             const { value, className, message } = decodeThrown(result.error?.value);
             const trace = result.error?.trace ?? [];
             // Same-host rehydration: a `baml.errors.HostCallable` carrying a
-            // `_handle` that still resolves in this process's host-value
+            // `_handle` that still resolves in this runtime's host-value
             // registry re-throws the *original* JS error object the bridge
             // registered on the inbound throw — preserving `raised === caught`
-            // identity. Foreign runtimes (a different Node process, the
+            // identity. Foreign runtimes (a different JavaScript realm, the
             // Python bridge) and released keys fall through to the
             // metadata-bearing `BamlError(HostCallable)` wrapper below.
             if (className === 'baml.errors.HostCallable' && value !== null && typeof value === 'object') {
@@ -636,24 +702,21 @@ export function decodeCallResult(data) {
             if (className === CANCELLED_PANIC_CLASS) {
                 throw cancellationAbortError(formatted);
             }
-            throw new BamlError(formatted, { value, bamlTrace: trace, className });
+            throw errorForClassName(formatted, { value, bamlTrace: trace, className });
         }
         case 'panic': {
             const panic = result.panic;
-            if (panic?.isExitPanic) {
-                // Clean process-exit panic: exit after flushing telemetry (the
-                // registered `process.once('exit', flushEvents)` hook fires
-                // synchronously inside process.exit), rather than throwing.
-                const code = Number(panic.exitCode ?? 0);
-                process.exit(code);
-            }
             const { value, className, message } = decodeThrown(panic?.value);
             const trace = panic?.trace ?? [];
             const formatted = formatThrownMessage('panic', className ?? '', message, trace);
             if (className === CANCELLED_PANIC_CLASS) {
                 throw cancellationAbortError(formatted);
             }
-            throw new BamlPanic(formatted, { value, bamlTrace: trace, className });
+            const fallback = new BamlPanic(formatted, { value, bamlTrace: trace, className });
+            if (panic?.isExitPanic) {
+                handleExitPanic(Number(panic.exitCode ?? 0), fallback);
+            }
+            throw fallback;
         }
         case 'ok':
         default:
@@ -665,7 +728,7 @@ export function decodeCallResult(data) {
 //
 // When BAML invokes a `HostValue` registered via `registerHostCallable`, the
 // engine fires the C `HostDispatchFn`, which schedules the per-callable
-// `ThreadsafeFunction` (built from the wrapper below) onto the libuv event
+// `ThreadsafeFunction` (built from the wrapper below) onto the host event loop event
 // loop with `(callId, argsBytes)`. The wrapper decodes args, invokes the
 // user function, encodes the result (or error), and forwards the result
 // back to the engine via `completeHostCall`.
@@ -675,7 +738,7 @@ export function decodeCallResult(data) {
 // side calls into `_decode_value_holder` / `_set_inbound_value` directly
 // inside the Rust dispatch callback (under the GIL) rather than going
 // through a JS-side wrapper. Node's tsfn model makes the wrapper natural.
-function makeHostCallableDispatch(userFn) {
+export function makeHostCallableDispatch(userFn) {
     return (callId, argsBytes) => {
         // Every reachable exit from this wrapper must complete `callId`
         // exactly once — if it doesn't, the engine awaits the in-flight call
@@ -706,7 +769,7 @@ function makeHostCallableDispatch(userFn) {
                 sendHostCallableError(callId, err);
                 return;
             }
-            // Async callables: the wrapper resolves the promise on the libuv
+            // Async callables: the wrapper resolves the promise on the host event loop
             // loop and then forwards the result. The engine has released its
             // heap permit while awaiting `complete_host_call`, so JS-side
             // delay is safe (mirrors the Python `run_until_complete` model).
@@ -738,7 +801,7 @@ function isPromiseLike(value) {
 function sendHostCallableResult(callId, value) {
     let bytes;
     // Result-encode path (host → engine): no sync guard (we're already on
-    // libuv). We do track registrations, though — a callable nested in the
+    // host event loop). We do track registrations, though — a callable nested in the
     // result is registered before encoding finishes, and if encoding then
     // throws, the bytes never reach the engine, so it never decodes (and
     // never releases) the callable. Roll those back on failure, mirroring the
@@ -751,14 +814,7 @@ function sendHostCallableResult(callId, value) {
         bytes = Uint8Array.from(InboundValue.encode(msg).finish());
     }
     catch (err) {
-        for (const k of ctx.registered) {
-            try {
-                releaseHostCallable(k);
-            }
-            catch {
-                // Best-effort cleanup; never mask the original error.
-            }
-        }
+        rollbackHostCallables(ctx.registered);
         sendHostCallableError(callId, err);
         return;
     }
@@ -788,14 +844,12 @@ function buildHostCallableInbound(className, message, traceback, handleKey) {
         stringField('message', message),
         stringField('class_name', className),
         stringField('language', 'nodejs'),
+        stringField('traceback', traceback ?? ''),
     ];
-    if (traceback != null) {
-        fields.push(stringField('traceback', traceback));
-    }
     fields.push(handleField);
     return InboundValue.create({
+        valueType: { classTy: { name: 'baml.errors.HostCallable' } },
         classValue: InboundClassValue.create({
-            classTy: { name: 'baml.errors.HostCallable' },
             fields,
         }),
     });
@@ -811,9 +865,40 @@ function buildHostCallableInbound(className, message, traceback, handleKey) {
 // skips `0`), so a real registered key can never collide.
 //
 // Cast through `as unknown as HandleKey` because `HandleKey` is a native
-// napi class with private fields; protobufjs only reads the public
+// native class with private fields; protobufjs only reads the public
 // `{low, high}` shape and the wire serializes them identically.
 const UNRESOLVED_HOST_ERROR_KEY = { low: 0, high: 0 };
+/** Encode a BamlError's wrapped value with its concrete generated-class FQN.
+ * Ordinary function arguments may use a bare map because the declared
+ * parameter supplies the target class. A thrown value has no such coercion
+ * context: the engine must see the class identity before it can validate the
+ * callable's declared `throws` contract. */
+function setInboundTypedThrowValue(iv, value, ctx) {
+    if (value !== null && typeof value === 'object') {
+        const proto = Object.getPrototypeOf(value);
+        const isClassInstance = proto !== Object.prototype && proto !== null;
+        if (isClassInstance) {
+            const fqn = getTypeMap().jsTypeToBamlType(value.constructor);
+            if (fqn) {
+                const params = genericParamNames(value);
+                const userTypes = value.$types;
+                const typeArgs = params?.map((param) => lowerTypeToWireTy(userTypes?.[param])) ?? [];
+                const fields = [];
+                for (const [key, fieldValue] of Object.entries(value)) {
+                    if (typeof fieldValue === 'function' || key === '$types')
+                        continue;
+                    const child = {};
+                    setInboundValue(child, fieldValue, ctx);
+                    fields.push({ stringKey: key, value: child });
+                }
+                iv.valueType = { classTy: { name: fqn, typeArgs } };
+                iv.classValue = { fields };
+                return;
+            }
+        }
+    }
+    setInboundValue(iv, value, ctx);
+}
 function sendHostCallableError(callId, err) {
     // Normal error path: never leaves the call uncompleted. If building or
     // encoding the Instance throws (e.g. `describeError`, proto `create` /
@@ -845,7 +930,7 @@ function sendHostCallableError(callId, err) {
             const ctx = { syncMode: false, registered: [] };
             try {
                 const iv = InboundValue.create({});
-                setInboundValue(iv, err.value, ctx);
+                setInboundTypedThrowValue(iv, err.value, ctx);
                 const bytes = Uint8Array.from(InboundValue.encode(iv).finish());
                 completeHostCall(callId, 1, bytes);
                 return;
@@ -855,25 +940,18 @@ function sendHostCallableError(callId, err) {
                 // registrations its nested fields triggered and fall through
                 // to the opaque-handle path below. The fall-through is
                 // intentional: the throw must still reach the engine even if
-                // the typed-value encode broke, so we never leave the call
+                // the sparse typed-node encode broke, so we never leave the call
                 // hanging. Each release is wrapped in its own try/catch so
                 // a single bad entry doesn't abort the rest of the rollback
                 // and leak the remaining registrations (mirrors the other
                 // rollback sites in `setInboundValue` and
                 // `sendHostCallableResult`).
-                for (const key of ctx.registered) {
-                    try {
-                        releaseHostCallable(key);
-                    }
-                    catch {
-                        // Best-effort cleanup; never mask the original error.
-                    }
-                }
+                rollbackHostCallables(ctx.registered);
             }
         }
         // Opaque-handle path: a `baml.errors.HostCallable` Instance carrying
         // a handle to the originating JS error so the BAML→host decoder on
-        // the same Node process can rehydrate the *same* exception object
+        // the same JavaScript realm can rehydrate the *same* exception object
         // on round-trip (`raised === caught` identity). Foreign runtimes /
         // released keys fall back to metadata.
         //
@@ -887,19 +965,20 @@ function sendHostCallableError(callId, err) {
         // original Proxy. Identity loss here is the right trade — the
         // alternative is hanging the call.
         //
-        // Registration-leak edge case (rare, bounded): if encoding succeeds
-        // through `registerHostOpaque` but `buildHostCallableInbound` or
-        // `InboundValue.encode` fails after, the TS map entry stays alive
-        // with no corresponding engine-side `HostValueArc` to release it,
-        // so it lives until process exit. Both downstream calls are deeply
-        // mechanical (build a proto message, serialize fixed-shape fields)
-        // and don't depend on `err`'s shape, so this is effectively
-        // unreachable outside protobufjs / native-binding corruption.
+        // Register transactionally: if fixed-shape payload construction,
+        // encoding, or delivery fails before Rust retains the handle, remove
+        // the opaque entry before falling back to the last-resort payload.
         const { className, message, stack } = describeError(err);
         const handleKey = registerHostOpaque(err);
-        const inbound = buildHostCallableInbound(className, message, stack, handleKey);
-        const bytes = Uint8Array.from(InboundValue.encode(inbound).finish());
-        completeHostCall(callId, 1, bytes);
+        try {
+            const inbound = buildHostCallableInbound(className, message, stack, handleKey);
+            const bytes = Uint8Array.from(InboundValue.encode(inbound).finish());
+            completeHostCall(callId, 1, bytes);
+        }
+        catch (innerErr) {
+            releaseHostOpaque(handleKey);
+            throw innerErr;
+        }
     }
     catch (innerErr) {
         completeHostCallLastResort(callId, innerErr);
@@ -911,7 +990,7 @@ function sendHostCallableError(callId, err) {
  * error object, so the only ways it can fail are a broken proto runtime or a
  * broken native binding — at which point nothing can complete the call. We
  * swallow any throw here to avoid surfacing an unhandled rejection on the
- * libuv loop; the engine's lack of completion would then be the
+ * host event loop loop; the engine's lack of completion would then be the
  * (unavoidable) failure mode.
  */
 function completeHostCallLastResort(callId, err) {
@@ -922,7 +1001,7 @@ function completeHostCallLastResort(callId, err) {
     }
     catch (innerErr) {
         // Nothing more we can safely do — a throw here would surface as an
-        // unhandled rejection on the libuv loop. The engine's lack of
+        // unhandled rejection on the host event loop loop. The engine's lack of
         // completion will then be the (unavoidable) failure mode; log so the
         // failure is at least attributable.
         console.error('BAML internal: last-resort host-call completion failed; call will hang.', { callId, originalError: safeStringify(err), lastResortError: innerErr });
@@ -940,17 +1019,31 @@ function safeStringify(err) {
 }
 function describeError(err) {
     if (err instanceof Error) {
+        const rawName = err.name;
+        const rawMessage = err.message;
+        const rawStack = err.stack;
         return {
-            className: err.name || err.constructor.name || 'Error',
-            message: err.message || String(err),
-            stack: err.stack ?? undefined,
+            className: typeof rawName === 'string' && rawName.length > 0
+                ? rawName
+                : err.constructor.name || 'Error',
+            message: typeof rawMessage === 'string' && rawMessage.length > 0
+                ? rawMessage
+                : safeStringify(err),
+            stack: rawStack == null
+                ? undefined
+                : typeof rawStack === 'string'
+                    ? rawStack
+                    : safeStringify(rawStack),
         };
     }
     if (err != null && typeof err === 'object') {
         const ctor = err.constructor;
-        const className = ctor?.name && ctor.name !== 'Object' ? ctor.name : 'Error';
-        return { className, message: String(err), stack: undefined };
+        const rawName = ctor?.name;
+        const className = typeof rawName === 'string' && rawName.length > 0 && rawName !== 'Object'
+            ? rawName
+            : 'Error';
+        return { className, message: safeStringify(err), stack: undefined };
     }
-    return { className: 'Error', message: String(err), stack: undefined };
+    return { className: 'Error', message: safeStringify(err), stack: undefined };
 }
 //# sourceMappingURL=proto.js.map