first pass

Author: sxlijin

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

@@ -10,6 +10,13 @@
 /// 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`.
+///
+/// `args` is a two-element pack the VM builds in `host_closure_call_sysop`:
+/// `[positional_required_args, { optional_name: value }]`. The VM has already
+/// split the call by the callable's declared params (using the captured
+/// `Object::HostClosure`), dropping omitted optionals — so each bridge applies
+/// its own calling convention (TS `$opts`, Python kwargs) without needing the
+/// callee type on the wire.
 function call_host_value<T, E>(handle: HostValue, args: unknown[])
     -> T throws E {
   $rust_io_function

baml_language/crates/baml_cli/src/snapshots/baml_cli__describe_command_tests__render_builtin_package_listing.snap

@@ -101,8 +101,8 @@ function         future.any                       <builtin>/baml/ns_future/futur
 class            glob.ScanOptions                 <builtin>/baml/ns_glob/glob.baml:2
 class            glob.Glob                        <builtin>/baml/ns_glob/glob.baml:18
 function         glob.new                         <builtin>/baml/ns_glob/glob.baml:34
-function         host.call_host_value             <builtin>/baml/ns_host/host.baml:13
-class            host.HostValue                   <builtin>/baml/ns_host/host.baml:20
+function         host.call_host_value             <builtin>/baml/ns_host/host.baml:20
+class            host.HostValue                   <builtin>/baml/ns_host/host.baml:27
 class            http.Request                     <builtin>/baml/ns_http/http.baml:8
 class            http.Response                    <builtin>/baml/ns_http/http.baml:16
 class            http.SseStream                   <builtin>/baml/ns_http/http.baml:94

baml_language/crates/baml_tests/projects/broken_syntax/optional_parameter_defaults/callback_param_defaults.baml

@@ -0,0 +1,9 @@
+// A host-callable parameter whose callable type tries to give one of its own
+// arguments a default (`y: int = 10`). A default is a property of a function
+// *declaration*, not a function *type*, so the parser rejects it — the same
+// `E0010` rule that rejects `type T = (a: int = 1) -> int`, here exercised in
+// the host-callback parameter position. This pins that an optional callback
+// argument must be written with the `?` marker (`y?: int`), never a default.
+function call_with_defaulted_callback(callback: (x: int, y: int = 10) -> string, x: int) -> string {
+    callback(x)
+}

baml_language/crates/baml_tests/snapshots/broken_syntax/optional_parameter_defaults/baml_tests__broken_syntax__optional_parameter_defaults__01_lexer__callback_param_defaults.snap

@@ -585,6 +585,10 @@ impl BexEngine {
                     ret_ty: Box::new(ret),
                     throws_ty: Box::new(normalized_throws),
                     arity: params.len(),
+                    // Capture the declared params (names + optionality) so the VM
+                    // can split the call args into positional + supplied-optional
+                    // (by name) on dispatch, for the per-bridge argument reshape.
+                    params: Box::new(params.clone()),
                 };
                 Value::object(
                     holder

baml_language/crates/baml_tests/snapshots/broken_syntax/optional_parameter_defaults/baml_tests__broken_syntax__optional_parameter_defaults__02_parser__callback_param_defaults.snap

@@ -3,8 +3,9 @@
 //! through `SysOp::BamlHostCallHostValue` when BAML code invokes it.
 //!
 //! The tests stand up a fake host dispatcher that:
-//! 1. Decodes the engine-side `BamlOutboundValue` args (a list of typed
-//!    `BamlOutboundValue`s, per `host_impls::call_host_value`).
+//! 1. Decodes the engine-side `BamlToHostArgs` list (the resolved, declared-order
+//!    supplied args, per `host_impls::call_host_value`) and flattens it back to
+//!    a positional list.
 //! 2. Looks up the per-key behaviour registered by the test.
 //! 3. Calls `sys_native::host_dispatch::complete_with_value` (or
 //!    `complete_with_error`) directly with a `BexExternalValue`. This
@@ -32,7 +33,7 @@ use bex_engine::{
     BexEngine, BexExternalValue, CancellationToken, EngineError, FunctionCallContextBuilder,
 };
 use bex_resource_types::{HostValueArc, HostValueKind};
-use bridge_ctypes::baml_core::cffi::{BamlOutboundValue, baml_outbound_value};
+use bridge_ctypes::baml_core::cffi::{BamlOutboundValue, BamlToHostArgs, baml_outbound_value};
 use common::compile_for_engine;
 use indexmap::IndexMap;
 use prost::Message;
@@ -202,25 +203,23 @@ extern "C" fn global_dispatch(host_value_key: u64, call_id: u32, args: *const u8
         unsafe { std::slice::from_raw_parts(args, length) }.to_vec()
     };
 
-    let outbound = match BamlOutboundValue::decode(bytes.as_slice()) {
+    // The engine sends a `BamlToHostArgs` list it already resolved against the
+    // callable's declared params (omitted optionals dropped), in declared order.
+    // Real bridges apply their calling convention (TS `$opts`, Python kwargs);
+    // these tests invoke positionally, so we take every arg's value in order.
+    // The callables exercised here have no optional params.
+    let to_host_args = match BamlToHostArgs::decode(bytes.as_slice()) {
         Ok(v) => v,
         Err(e) => {
             complete_with_test_error(call_id, "DecodeError", &format!("decode failure: {e}"));
             return;
         }
     };
-
-    let items: Vec<BamlOutboundValue> = match outbound.value {
-        Some(baml_outbound_value::Value::ListValue(list)) => list.items,
-        other => {
-            complete_with_test_error(
-                call_id,
-                "ProtocolError",
-                &format!("expected ListValue in dispatch args, got {other:?}"),
-            );
-            return;
-        }
-    };
+    let items: Vec<BamlOutboundValue> = to_host_args
+        .args
+        .into_iter()
+        .filter_map(|arg| arg.value)
+        .collect();
 
     // Clone the behaviour out and drop the lock before invoking it; keep the
     // entry so the same key can be dispatched again (reusable callable).
@@ -452,9 +451,9 @@ async fn host_callable_invoked_from_native_map_continuation() {
 
 // ============================================================================
 // Operand-layout pin: the VM hand-builds the `SysOp::BamlHostCallHostValue`
-//        args as `[handle, args_array, ret_ty, throws_ty]` to match the
+//        args as `[handle, args_pack, ret_ty, throws_ty]` to match the
 //        codegen-generated glue (`sys_ops/.../io_generated.rs` extracts `__arg0`
-//        as the handle via `as_owned_but_very_slow`, `__arg1` as the args list,
+//        as the handle via `as_owned_but_very_slow`, `__arg1` as the args pack,
 //        and `__arg2`/`type_arg_0` + `__arg3`/`type_arg_1` via
 //        `as_baml_type_owned`). Nothing else pins this contract,
 //        so a future codegen change to the type-arg operand position (or a swap
@@ -465,13 +464,15 @@ async fn host_callable_invoked_from_native_map_continuation() {
 //     registered key (the behaviour table lookup by `host_value_key` succeeds);
 //     if `args[0]` were not the handle, `as_owned_but_very_slow` would not yield
 //     a `HostValue` and the sys-op would fail with a `TypeError` before dispatch.
-//   * `args[1]` (args array) — asserted to decode to exactly the user args, in
-//     order: `[Int(7), Int(8)]`. If `args[1]` carried the ret_ty `Object::Type`
-//     instead, the glue's `BexExternalValue::Array` extraction would fail.
+//   * `args[1]` (args pack) — the `[positional_array, optional_map]` pair the VM
+//     builds; the dispatch decodes the `BamlToHostArgs` list and asserts the
+//     values are exactly the user args, in order: `[Int(7), Int(8)]`. If
+//     `args[1]` carried the ret_ty `Object::Type` instead, the glue's
+//     `BexExternalValue::Array` extraction would fail.
 //   * `args[2]` (ret_ty) — proven to carry the declared return `RuntimeTy` (`int`):
 //     the host returns the sum (an `Int`), which only passes return-type
 //     validation if `type_arg_0` decoded to `int`. If `args[2]` carried the
-//     args array instead, `as_baml_type_owned` would fail and the call would
+//     args pack instead, `as_baml_type_owned` would fail and the call would
 //     error before reaching the host.
 //   * `args[3]` (throws_ty) — packed by codegen and consumed by the
 //     engine's host-throw injection site (`lib.rs::execute_sys_op` →