Host callable errors (#3680)

When a host function called from BAML throws an error, we can take one
of three paths:
1. If the error type violates the BAML error type contract, then a
`HostContractViolation` panic is raised in BAML
2. If the error type is convertible into a BAML type (e.g. codegenned
type or primitive) then it is raised in BAML
3. Otherwise the error type is not convertible and is saved to the host
value table. The handle to it wrapped in a `HostCallable` BAML error
which is thrown in BAML. If the `HostCallable` is returned back out to
the host then it will get the value from the table.

This also includes making sysop errors properly catchable: previously
all sysop errors were just converted into fatal internal engine errors.

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Native host exceptions can round-trip and be rehydrated by SDKs;
Node/Python SDKs expose registry/lookup helpers to preserve original
Error identity.
* Typed host-throws supported and a new HostContractViolation panic
reports host contract mismatches.

* **Bug Fixes**
* IO/env/filesystem/http errors now surface clearer categories (e.g.,
InvalidArgument, ParseError) for non-UTF‑8 and invalid inputs.
* Async/bridge error paths unified so thrown payloads, tracebacks, and
error propagation behave more consistently.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Sam Lijin <sam@boundaryml.com>

Author: 2kai2kai2

baml_language/Cargo.lock

@@ -265,6 +265,7 @@ web-time = "1.1.0"
 getrandom = { version = "0.2" }
 getrandom_03 = { package = "getrandom", version = "0.3", features = [ "wasm_js" ] }
 num-bigint = { version = "0.4", features = [ "rand", "serde" ] }
+num-traits = { version = "0.2" }
 rsa = { version = "0.9", default-features = false, features = [ "std", "pem" ] }
 sha2 = { version = "0.10", features = [ "oid" ] }
 

baml_language/Cargo.toml

@@ -1,5 +1,9 @@
 /// Returns the value of the environment variable `key`, or `null` if not set.
-function get(key: string) -> string? throws root.errors.Io {
+///
+/// Throws `ParseError` if the variable is set but its value is not valid
+/// UTF-8 (the native bridge surfaces `std::env::VarError::NotUnicode` as a
+/// catchable parse error).
+function get(key: string) -> string? throws root.errors.Io | root.errors.ParseError {
   $rust_io_function
 }
 

baml_language/crates/baml_builtins2/baml_std/baml/ns_env/env.baml

@@ -50,17 +50,22 @@ class DevOther {
   message string
 }
 
-/// The host runtime panicked.
-class HostPanic {
-  message string
-}
-
 class HostCallable {
   message string
   class_name string
   language string
   traceback string?
-  category int
+  // Opaque slot carrying the bridge SDK's same-host rehydration handle.
+  // Always populated on the wire by the originating bridge — a `HostCallable`
+  // with no `_handle` is not a valid BAML value. The originating bridge
+  // can resolve the handle back to the original native exception object
+  // (same-process round-trip → `raised === caught` identity); foreign
+  // runtimes receive the same handle on the wire but their local lookup
+  // misses, at which point the host SDK degrades to constructing an
+  // exception from the metadata fields above. The fallback is a
+  // *lookup-result* concern on the host side, not a wire shape — the
+  // field itself is required.
+  _handle $rust_type
 }
 
 /// A catch-all SDK-boundary failure with no more specific class. Synthesized

baml_language/crates/baml_builtins2/baml_std/baml/ns_errors/errors.baml

@@ -1,44 +1,51 @@
 /// A handle to an open file. Use `baml.fs.open` to obtain one.
+///
+/// Every `File.*` method can throw `InvalidArgument` when the underlying
+/// handle has already been closed (e.g. by a prior `close()`); read-string
+/// methods can additionally throw `ParseError` on non-UTF-8 input.
 class File {
   _handle $rust_type
 
   /// Reads the entire remaining file contents as a UTF-8 string.
-  function text(self) -> string throws root.errors.Io {
+  function text(self) -> string throws root.errors.Io | root.errors.InvalidArgument | root.errors.ParseError {
     $rust_io_function
   }
 
   /// Reads the entire remaining file contents as raw bytes.
-  function bytes(self) -> uint8array throws root.errors.Io {
+  function bytes(self) -> uint8array throws root.errors.Io | root.errors.InvalidArgument {
     $rust_io_function
   }
 
   /// Reads up to `n` bytes from the file and returns them as a UTF-8 string.
-  function read(self, n: int) -> string throws root.errors.Io {
+  function read(self, n: int) -> string throws root.errors.Io | root.errors.InvalidArgument | root.errors.ParseError {
     $rust_io_function
   }
 
   /// Reads up to `n` bytes from the file and returns them as raw bytes.
-  function read_bytes(self, n: int) -> uint8array throws root.errors.Io {
+  function read_bytes(self, n: int) -> uint8array throws root.errors.Io | root.errors.InvalidArgument {
     $rust_io_function
   }
 
   /// Closes the file handle, flushing any pending writes.
-  function close(self) -> null throws root.errors.Io {
+  function close(self) -> null throws root.errors.Io | root.errors.InvalidArgument {
     $rust_io_function
   }
 
   /// Moves the file cursor. `whence` is `"start"`, `"current"`, or `"end"`. Returns the new cursor position in bytes.
-  function seek_from(self, whence: "start" | "current" | "end", offset: int) -> int throws root.errors.Io {
+  ///
+  /// Throws `InvalidArgument` if `offset` is negative when paired with
+  /// `whence="start"` (the underlying syscall takes an unsigned offset).
+  function seek_from(self, whence: "start" | "current" | "end", offset: int) -> int throws root.errors.Io | root.errors.InvalidArgument {
     $rust_io_function
   }
 
   /// Writes `data` to the file at the current cursor position. Returns the number of bytes written.
-  function write(self, data: string) -> int throws root.errors.Io {
+  function write(self, data: string) -> int throws root.errors.Io | root.errors.InvalidArgument {
     $rust_io_function
   }
 
   /// Writes raw bytes `data` to the file at the current cursor position. Returns the number of bytes written.
-  function write_bytes(self, data: uint8array) -> int throws root.errors.Io {
+  function write_bytes(self, data: uint8array) -> int throws root.errors.Io | root.errors.InvalidArgument {
     $rust_io_function
   }
 }
@@ -47,7 +54,7 @@ class File {
 ///
 /// Mode values: `"r"` (read), `"r+"` (read/write), `"w"` (write/truncate),
 /// `"w+"` (read/write/truncate), `"a"` (append), `"a+"` (read/append).
-function open(path: string, mode: "r" | "r+" | "w" | "w+" | "a" | "a+") -> File throws root.errors.Io {
+function open(path: string, mode: "r" | "r+" | "w" | "w+" | "a" | "a+") -> File throws root.errors.Io | root.errors.InvalidArgument {
   $rust_io_function
 }
 
@@ -67,7 +74,8 @@ function size(path: string) -> int throws root.errors.Io {
 }
 
 /// Reads the entire contents of the file at `path` as a UTF-8 string.
-function read(path: string) -> string throws root.errors.Io {
+/// Throws `ParseError` if the file's bytes are not valid UTF-8.
+function read(path: string) -> string throws root.errors.Io | root.errors.ParseError {
   $rust_io_function
 }
 

baml_language/crates/baml_builtins2/baml_std/baml/ns_fs/fs.baml

@@ -1,12 +1,17 @@
 /// Internal: invoked only by compiler-synthesized host-callable wrapper
 /// closures. Not directly callable by user code.
 ///
-/// `T` is the expected return type, delivered to the native handler at
-/// runtime via the type-arg channel. The handler validates both the
-/// inbound `args` and the host's returned value against the declared
-/// signature, raising `root.errors.HostCallable` on mismatch.
-function call_host_value<T>(handle: HostValue, args: unknown[])
-    -> T throws root.errors.HostCallable {
+/// `T` is the expected return type and `E` the declared error contract,
+/// both delivered to the native handler at runtime via the type-arg channel
+/// (`type_arg_0` / `type_arg_1`). The completion site validates the host's
+/// returned value against `T` and the thrown value against `E`: a return
+/// that doesn't inhabit `T` and a throw that isn't a subtype of `E` both
+/// become `baml.panics.HostContractViolation` (uncatchable). An on-contract
+/// throw rides the VM's normal exception unwinder. A host value left
+/// untyped at the boundary erases `E` to `unknown`, which accepts any
+/// thrown value — including an opaque `baml.errors.HostCallable`.
+function call_host_value<T, E>(handle: HostValue, args: unknown[])
+    -> T throws E {
   $rust_io_function
 }
 

baml_language/crates/baml_builtins2/baml_std/baml/ns_host/host.baml

@@ -84,4 +84,13 @@ class SdkPanic {
   message string
 }
 
-type Panic = DivisionByZero | IndexOutOfBounds | InvalidFieldAccess | MapKeyNotFound | StackOverflow | AssertionFailed | Unreachable | Cancelled | UserPanic | Exit | AllocFailure | HostUnavailable | NegativeBitShift | SdkPanic
+/// A host callable violated its typed contract: it returned a value of the
+/// wrong type, or threw a value that does not match its declared error
+/// contract. Catchable like any other panic.
+class HostContractViolation {
+  message string
+  class_name string?
+  language string?
+}
+
+type Panic = DivisionByZero | IndexOutOfBounds | InvalidFieldAccess | MapKeyNotFound | StackOverflow | AssertionFailed | Unreachable | Cancelled | UserPanic | Exit | AllocFailure | HostUnavailable | NegativeBitShift | SdkPanic | HostContractViolation

baml_language/crates/baml_builtins2/baml_std/baml/ns_panics/panics.baml

@@ -593,12 +593,33 @@ pub fn generate_sys_op_enum(io_builtins: &[NativeBuiltin]) -> String {
             let variant = format_ident!("{}", b.sys_op_variant_name());
             // `None` (no clause) is rejected during extraction; `Some([])`
             // (`throws never`) and `None` both map to no error categories.
+            // A `throws` entry that names one of the builtin's generic params
+            // (e.g. `call_host_value<T, E> ... throws E`) is a *dynamic* error
+            // contract, not a fixed `SysOpErrorCategory`. The static category
+            // list cannot represent a mix of "concrete X" + "dynamic E" — the
+            // dynamic component would be silently dropped, leaving
+            // `validate_sys_op_error` to wrongly reject any `E`-shaped throw
+            // as off-contract. Apply an all-or-nothing rule: if *any* throws
+            // entry is generic, emit an empty list ("accept any category")
+            // and defer the entire contract check to runtime. Concrete-only
+            // contracts still emit a precise category list. (The `throws`
+            // clause stays non-empty either way, so the builtin remains
+            // `is_fallible`.)
             match &b.throws {
-                Some(cats) if !cats.is_empty() => {
-                    let cats: Vec<_> = cats.iter().map(|t| format_ident!("{}", t)).collect();
-                    quote! { SysOp::#variant => &[#(SysOpErrorCategory::#cats),*] }
+                Some(cats) => {
+                    let has_generic_throw = cats.iter().any(|t| b.generics.iter().any(|g| g == t));
+                    if has_generic_throw {
+                        quote! { SysOp::#variant => &[] }
+                    } else {
+                        let cats: Vec<_> = cats.iter().map(|t| format_ident!("{}", t)).collect();
+                        if cats.is_empty() {
+                            quote! { SysOp::#variant => &[] }
+                        } else {
+                            quote! { SysOp::#variant => &[#(SysOpErrorCategory::#cats),*] }
+                        }
+                    }
                 }
-                _ => quote! { SysOp::#variant => &[] },
+                None => quote! { SysOp::#variant => &[] },
             }
         })
         .collect();
@@ -1383,7 +1404,7 @@ fn emit_glue_method(
                 }
                 Err(e) => SysOpResult::Ready(Err(OpError::new(
                     SysOp::#variant_ident,
-                    OpErrorKind::AccessError(e),
+                    bex_vm_types::errors::VmBamlError::AccessError { message: e.to_string() },
                 ))),
             }
         }
@@ -1739,7 +1760,7 @@ fn emit_free_fn_glue(
                 }
                 Err(e) => SysOpResult::Ready(Err(OpError::new(
                     SysOp::#variant_ident,
-                    OpErrorKind::AccessError(e),
+                    bex_vm_types::errors::VmBamlError::AccessError { message: e.to_string() },
                 ))),
             }
         }
@@ -1816,7 +1837,9 @@ fn emit_sys_ops_struct(io_builtins: &[NativeBuiltin]) -> TokenStream {
                         t.get_sys_op_fn(#path_str, heap, permit, args, ctx, call_id)
                             .unwrap_or_else(|| SysOpResult::Ready(Err(OpError::new(
                                 SysOp::#variant_ident,
-                                OpErrorKind::Unsupported,
+                                bex_vm_types::errors::VmBamlError::Unsupported {
+                                    message: "Operation not supported on this platform".to_string(),
+                                },
                             ))))
                     })
                 }
@@ -1841,7 +1864,9 @@ fn emit_sys_ops_struct(io_builtins: &[NativeBuiltin]) -> TokenStream {
                 std::sync::Arc::new(move |_, _, _, _, _| {
                     SysOpResult::Ready(Err(OpError::new(
                         operation,
-                        OpErrorKind::Unsupported,
+                        bex_vm_types::errors::VmBamlError::Unsupported {
+                            message: "Operation not supported on this platform".to_string(),
+                        },
                     )))
                 })
             }

baml_language/crates/baml_builtins2_codegen/src/codegen_io.rs

@@ -1046,7 +1046,7 @@ mod tests {
             .iter()
             .find(|b| b.path == "baml.fs.open")
             .unwrap();
-        assert_eq!(fs_open.throws, throws(&["Io"]));
+        assert_eq!(fs_open.throws, throws(&["Io", "InvalidArgument"]));
 
         let net_connect = io_builtins
             .iter()

baml_language/crates/baml_builtins2_codegen/src/extract.rs

@@ -2,5 +2,5 @@
 source: crates/baml_cli/src/describe_command_tests.rs
 expression: output
 ---
-function         env.get                          <builtin>/baml/ns_env/env.baml:2
-function         env.get_or_panic                 <builtin>/baml/ns_env/env.baml:7
+function         env.get                          <builtin>/baml/ns_env/env.baml:6
+function         env.get_or_panic                 <builtin>/baml/ns_env/env.baml:11