feat(bridges): support providing host callables as lambdas with optional args (#3787)

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

## Release Notes

* **New Features**
* Improved TypeScript callable typings for optional parameters using a
trailing `$opts?: { ... }` object.

* **Bug Fixes**
* Host-callable dispatch now consistently routes required positional
arguments separately from named optional arguments, with omitted
optionals correctly using the host’s defaults.
* Updated host-call argument payload handling to support the new
argument envelope consistently across runtimes.

* **Documentation**
* Expanded documentation describing the expected host-call argument
structure and optional semantics.

* **Tests**
* Added/updated fixtures and end-to-end tests for optional-argument
behavior and validation (including broken-syntax cases).
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: sxlijin

baml_language/Cargo.lock

@@ -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_builtins2/baml_std/baml/ns_host/host.baml

@@ -105,8 +105,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_cli/src/snapshots/baml_cli__describe_command_tests__render_builtin_package_listing.snap

@@ -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/projects/broken_syntax/optional_parameter_defaults/callback_param_defaults.baml

@@ -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