feat(host): infer typed host call contracts from signatures

Author: fffonion

build.rs

@@ -49,6 +49,12 @@ pub(crate) enum HostBindingKind {
     StaticNonYieldingArgs,
 }
 
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(crate) enum HostExecutionKind {
+    Sync,
+    MaySuspend,
+}
+
 impl HostBindingKind {
     pub(crate) fn render_bind_static_call(&self, name: &str, function_name: &str) -> String {
         let method = match self {
@@ -108,6 +114,7 @@ struct CallableDecl {
     static_return_type: String,
     wrapper: Option<WrapperDecl>,
     host_binding_kind: HostBindingKind,
+    host_execution: HostExecutionKind,
 }
 
 #[derive(Clone, Debug)]
@@ -261,7 +268,6 @@ pub(crate) fn classify_host_binding(function: &ItemFn) -> HostBindingKind {
         return HostBindingKind::StaticArgs;
     }
     if sole_type_argument(&return_type, "VmResult")
-        .or_else(|| sole_type_argument(&return_type, "HostResult"))
         .is_some_and(|inner| matches!(plain_path_type(&inner).as_deref(), Some("CallOutcome")))
     {
         return HostBindingKind::StaticArgs;
@@ -272,6 +278,22 @@ pub(crate) fn classify_host_binding(function: &ItemFn) -> HostBindingKind {
     HostBindingKind::StaticArgs
 }
 
+pub(crate) fn infer_host_execution(function: &ItemFn) -> HostExecutionKind {
+    let return_type = normalized_return_type(&function.sig.output);
+    if contains_host_call_result(&return_type) {
+        HostExecutionKind::MaySuspend
+    } else {
+        HostExecutionKind::Sync
+    }
+}
+
+fn contains_host_call_result(ty: &Type) -> bool {
+    if sole_type_argument(ty, "HostCallResult").is_some() {
+        return true;
+    }
+    sole_type_argument(ty, "VmResult").is_some_and(|inner| contains_host_call_result(&inner))
+}
+
 fn is_supported_ordinary_return_type(ty: &Type) -> bool {
     match ty {
         Type::Group(group) => is_supported_ordinary_return_type(&group.elem),
@@ -282,10 +304,8 @@ fn is_supported_ordinary_return_type(ty: &Type) -> bool {
                 return false;
             };
             match segment.ident.to_string().as_str() {
-                "Option" | "VmResult" | "HostResult" => {
-                    sole_type_argument(ty, &segment.ident.to_string())
-                        .is_some_and(|inner| is_supported_ordinary_return_type(&inner))
-                }
+                "Option" | "VmResult" => sole_type_argument(ty, &segment.ident.to_string())
+                    .is_some_and(|inner| is_supported_ordinary_return_type(&inner)),
                 "Vec" => sole_type_argument(ty, "Vec")
                     .is_some_and(|inner| is_supported_vec_return_type(&inner)),
                 "Value" | "bool" | "i64" | "u32" | "usize" | "f64" | "String" | "str"
@@ -404,6 +424,7 @@ fn parse_source_file(path: &Path, spec: &SourceSpec, _order_offset: usize) -> Ve
             static_return_type: static_return_type_label(&function.sig.output),
             wrapper,
             host_binding_kind: classify_host_binding(function),
+            host_execution: infer_host_execution(function),
         });
     }
     out
@@ -1145,9 +1166,13 @@ fn render_callable_consts(callables: &[&CallableDecl]) -> String {
         .unwrap();
         writeln!(
             &mut out,
-            "#[allow(dead_code)]\nconst {base}_DEF: CallableDef = CallableDef {{ name: {:?}, docs: {:?}, signature: {base}_SIGNATURE }};",
+            "#[allow(dead_code)]\nconst {base}_DEF: CallableDef = CallableDef {{ name: {:?}, docs: {:?}, signature: {base}_SIGNATURE, host_execution: HostExecution::{} }};",
             callable.name,
-            callable.docs
+            callable.docs,
+            match callable.host_execution {
+                HostExecutionKind::Sync => "Sync",
+                HostExecutionKind::MaySuspend => "MaySuspend",
+            }
         )
         .unwrap();
         writeln!(&mut out).unwrap();
@@ -1997,7 +2022,7 @@ fn type_label(ty: &Type) -> String {
                     };
                     format!("{} | null", type_label(inner))
                 }
-                "VmResult" | "BuiltinResult" | "HostResult" => {
+                "VmResult" | "HostCallResult" => {
                     let syn::PathArguments::AngleBracketed(args) = &segment.arguments else {
                         panic!("{ident}<T> requires one generic argument");
                     };

docs/plans/2026-07-16-automatic-host-binding-selection.md

@@ -67,7 +67,7 @@ Run the narrow host/JIT tests. Expected: generated code still selects `bind_stat
 Add `HostBindingKind::{StaticStack, StaticArgs, StaticNonYieldingArgs}` in `build.rs`. Classify in this order:
 
 1. any `Vm` parameter → `StaticStack`;
-2. normalized `CallOutcome`, including `VmResult<CallOutcome>` and `HostResult<CallOutcome>` → `StaticArgs`;
+2. normalized `CallOutcome`, including `VmResult<CallOutcome>` → `StaticArgs`;
 3. all other valid args-only returns → `StaticNonYieldingArgs`.
 
 Use that one classification in generated registry and direct VM binding code. The non-yielding branches must emit `register_static_non_yielding_args` and `bind_static_non_yielding_args_function`.

docs/superpowers/specs/2026-07-16-automatic-host-binding-selection-design.md

@@ -13,10 +13,10 @@ This change covers `#[pd_host_function]` implementations discovered by the RustS
 Introduce one shared build-time classification with these ordered rules:
 
 1. A function with a `Vm` context parameter uses `StaticStack`.
-2. An args-only function whose normalized return type is `CallOutcome`, including `VmResult<CallOutcome>` and `HostResult<CallOutcome>`, uses `StaticArgs`.
+2. An args-only function whose normalized return type is `CallOutcome`, including `VmResult<CallOutcome>`, uses `StaticArgs`.
 3. Every other valid args-only annotated function uses `StaticNonYieldingArgs`.
 
-The third rule is safe because the generated wrapper converts all supported ordinary outputs through `IntoVmValue` into exactly one `Value`. This includes implicit `()`, explicit `()`, and `Option<T>`, which become `Value::Null` when appropriate. `VmResult<T>` and `HostResult<T>` may still return an error; successful calls return exactly one value synchronously.
+The third rule is safe because the generated wrapper converts all supported ordinary outputs through `IntoVmValue` into exactly one `Value`. This includes implicit `()`, explicit `()`, and `Option<T>`, which become `Value::Null` when appropriate. `VmResult<T>` may still return an error; successful calls return exactly one value synchronously.
 
 `CallOutcome` stays on the general static args ABI because it can represent no return value, halt, yield, or pending work. Any signature that cannot be classified safely falls back to the general compatible static binding.
 

pd-host-function/src/lib.rs

@@ -53,6 +53,16 @@ fn parse_name_arg(args: &Punctuated<Meta, Token![,]>) -> Result<LitStr, Error> {
             "expected #[pd_host_function(name = \"...\")]",
         ));
     };
+    if args.len() != 1 {
+        let extra = args
+            .iter()
+            .nth(1)
+            .expect("a non-empty attribute with more than one argument has an extra argument");
+        return Err(Error::new_spanned(
+            extra,
+            "#[pd_host_function] only supports name = \"...\"",
+        ));
+    }
     if !name_value.path.is_ident("name") {
         return Err(Error::new_spanned(
             &name_value.path,
@@ -267,10 +277,7 @@ fn unwrap_vm_result_type(ty: &Type) -> Result<Option<Type>, Error> {
             let Some(segment) = path.path.segments.last() else {
                 return Ok(None);
             };
-            if !matches!(
-                segment.ident.to_string().as_str(),
-                "VmResult" | "HostResult"
-            ) {
+            if segment.ident != "VmResult" {
                 return Ok(None);
             }
             let syn::PathArguments::AngleBracketed(args) = &segment.arguments else {
@@ -352,7 +359,7 @@ fn type_label(ty: &Type) -> Result<String, Error> {
                     let inner_label = type_label(inner)?;
                     Ok(format!("{inner_label} | null"))
                 }
-                "VmResult" | "BuiltinResult" | "HostResult" => {
+                "VmResult" | "HostCallResult" => {
                     let syn::PathArguments::AngleBracketed(args) = &segment.arguments else {
                         return Err(Error::new_spanned(
                             &segment.arguments,
@@ -472,3 +479,58 @@ fn uses_taken_extractor(ty: &Type) -> bool {
         _ => false,
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::expand_pd_host_function;
+    use syn::{ItemFn, Meta, Token, parse_quote, punctuated::Punctuated};
+
+    #[test]
+    fn accepts_host_call_result_from_the_function_signature() {
+        let attr: Punctuated<Meta, Token![,]> = parse_quote!(name = "test::suspend");
+        let item: ItemFn = parse_quote! {
+            /// Returns a value after a host operation completes.
+            #[pd_host_function(name = "test::suspend")]
+            fn suspend() -> VmResult<HostCallResult<Value>> {
+                todo!()
+            }
+        };
+
+        let expanded = expand_pd_host_function(attr, item)
+            .expect("HostCallResult should be accepted from the return signature");
+        assert!(expanded.to_string().contains("HostCallResult"));
+    }
+
+    #[test]
+    fn rejects_host_result_compatibility_wrapper() {
+        let attr: Punctuated<Meta, Token![,]> = parse_quote!(name = "test::legacy");
+        let item: ItemFn = parse_quote! {
+            /// Legacy result wrapper must be rejected.
+            #[pd_host_function(name = "test::legacy")]
+            fn legacy() -> HostResult<Value> {
+                todo!()
+            }
+        };
+
+        let error = expand_pd_host_function(attr, item)
+            .expect_err("HostResult must not be accepted as a return wrapper");
+        assert!(error.to_string().contains("unsupported callable type"));
+    }
+
+    #[test]
+    fn rejects_async_attribute_instead_of_treating_it_as_a_host_contract() {
+        let attr: Punctuated<Meta, Token![,]> =
+            parse_quote!(name = "test::suspend", r#async = true);
+        let item: ItemFn = parse_quote! {
+            /// Returns a value after a host operation completes.
+            #[pd_host_function(name = "test::suspend")]
+            fn suspend() -> VmResult<HostCallResult<Value>> {
+                todo!()
+            }
+        };
+
+        let error = expand_pd_host_function(attr, item)
+            .expect_err("the pd-host-function macro must not accept an async attribute");
+        assert!(error.to_string().contains("only supports name"));
+    }
+}

src/builtins/metadata.rs

@@ -42,11 +42,18 @@ pub struct CallableSignature {
     pub return_type: &'static str,
 }
 
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum HostExecution {
+    Sync,
+    MaySuspend,
+}
+
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub struct CallableDef {
     pub name: &'static str,
     pub docs: &'static str,
     pub signature: CallableSignature,
+    pub host_execution: HostExecution,
 }
 
 #[allow(dead_code)]

src/builtins/mod.rs

@@ -5,7 +5,9 @@ mod metadata;
 #[cfg(feature = "runtime")]
 pub(crate) mod runtime;
 
-pub use self::metadata::{CallableDef, CallableParam, CallableParamType, CallableSignature};
+pub use self::metadata::{
+    CallableDef, CallableParam, CallableParamType, CallableSignature, HostExecution,
+};
 use crate::ValueType;
 #[cfg(feature = "runtime")]
 pub(crate) use crate::vm::{HostFunctionRegistry, Value, Vm, VmResult};

src/builtins/runtime/io.rs

@@ -9,7 +9,7 @@ use std::task::{Context, Poll};
 use futures_channel::oneshot;
 use pd_host_function::pd_host_function;
 
-use super::BuiltinResult;
+use super::HostCallResult;
 use crate::vm::{CallReturn, HostOpId, Value, Vm, VmError, VmResult};
 
 pub(crate) struct IoState {
@@ -87,7 +87,11 @@ pub(super) fn close_all_handles(vm: &mut Vm) {
 
 /// Opens a file handle for runtime I/O.
 #[pd_host_function(name = "io::open")]
-pub(super) fn builtin_io_open(vm: &mut Vm, path: &str, mode: &str) -> VmResult<BuiltinResult<i64>> {
+pub(super) fn builtin_io_open(
+    vm: &mut Vm,
+    path: &str,
+    mode: &str,
+) -> VmResult<HostCallResult<i64>> {
     let reserved_id = io_reserve_handle_id(vm);
     let path = path.to_string();
     let mode = mode.to_string();
@@ -133,7 +137,7 @@ pub(super) fn builtin_io_open(vm: &mut Vm, path: &str, mode: &str) -> VmResult<B
             },
         }
     })?;
-    Ok(BuiltinResult::Pending(op_id))
+    Ok(HostCallResult::Pending(op_id))
 }
 
 /// Starts a child process and returns a process-backed handle.
@@ -142,7 +146,7 @@ pub(super) fn builtin_io_popen(
     vm: &mut Vm,
     command: &str,
     mode: &str,
-) -> VmResult<BuiltinResult<i64>> {
+) -> VmResult<HostCallResult<i64>> {
     if mode != "r" && mode != "w" {
         return Err(VmError::HostError(format!(
             "unsupported io_popen mode '{mode}', expected r or w"
@@ -191,12 +195,12 @@ pub(super) fn builtin_io_popen(
             result: Ok(CallReturn::one(Value::Int(reserved_id))),
         }
     })?;
-    Ok(BuiltinResult::Pending(op_id))
+    Ok(HostCallResult::Pending(op_id))
 }
 
 /// Reads all remaining text from an I/O handle.
 #[pd_host_function(name = "io::read_all")]
-pub(super) fn builtin_io_read_all(vm: &mut Vm, handle_id: i64) -> VmResult<BuiltinResult<String>> {
+pub(super) fn builtin_io_read_all(vm: &mut Vm, handle_id: i64) -> VmResult<HostCallResult<String>> {
     let handle = io_take_handle(vm, handle_id)?;
     let op_id = schedule_io_task(vm, move || {
         let mut handle = handle;
@@ -232,12 +236,15 @@ pub(super) fn builtin_io_read_all(vm: &mut Vm, handle_id: i64) -> VmResult<Built
             result,
         }
     })?;
-    Ok(BuiltinResult::Pending(op_id))
+    Ok(HostCallResult::Pending(op_id))
 }
 
 /// Reads a single line of text from an I/O handle.
 #[pd_host_function(name = "io::read_line")]
-pub(super) fn builtin_io_read_line(vm: &mut Vm, handle_id: i64) -> VmResult<BuiltinResult<String>> {
+pub(super) fn builtin_io_read_line(
+    vm: &mut Vm,
+    handle_id: i64,
+) -> VmResult<HostCallResult<String>> {
     let handle = io_take_handle(vm, handle_id)?;
     let op_id = schedule_io_task(vm, move || {
         let mut handle = handle;
@@ -268,7 +275,7 @@ pub(super) fn builtin_io_read_line(vm: &mut Vm, handle_id: i64) -> VmResult<Buil
             result,
         }
     })?;
-    Ok(BuiltinResult::Pending(op_id))
+    Ok(HostCallResult::Pending(op_id))
 }
 
 /// Writes text to an I/O handle.
@@ -277,7 +284,7 @@ pub(super) fn builtin_io_write(
     vm: &mut Vm,
     handle_id: i64,
     text: &str,
-) -> VmResult<BuiltinResult<i64>> {
+) -> VmResult<HostCallResult<i64>> {
     let bytes = text.as_bytes().to_vec();
     let handle = io_take_handle(vm, handle_id)?;
     let op_id = schedule_io_task(vm, move || {
@@ -313,12 +320,12 @@ pub(super) fn builtin_io_write(
             result,
         }
     })?;
-    Ok(BuiltinResult::Pending(op_id))
+    Ok(HostCallResult::Pending(op_id))
 }
 
 /// Flushes buffered output for an I/O handle.
 #[pd_host_function(name = "io::flush")]
-pub(super) fn builtin_io_flush(vm: &mut Vm, handle_id: i64) -> VmResult<BuiltinResult<bool>> {
+pub(super) fn builtin_io_flush(vm: &mut Vm, handle_id: i64) -> VmResult<HostCallResult<bool>> {
     let handle = io_take_handle(vm, handle_id)?;
     let op_id = schedule_io_task(vm, move || {
         let mut handle = handle;
@@ -351,31 +358,31 @@ pub(super) fn builtin_io_flush(vm: &mut Vm, handle_id: i64) -> VmResult<BuiltinR
             result,
         }
     })?;
-    Ok(BuiltinResult::Pending(op_id))
+    Ok(HostCallResult::Pending(op_id))
 }
 
 /// Closes an I/O handle.
 #[pd_host_function(name = "io::close")]
-pub(super) fn builtin_io_close(vm: &mut Vm, handle_id: i64) -> VmResult<BuiltinResult<bool>> {
+pub(super) fn builtin_io_close(vm: &mut Vm, handle_id: i64) -> VmResult<HostCallResult<bool>> {
     let handle = io_take_handle(vm, handle_id)?;
     let op_id = schedule_io_task(vm, move || IoAsyncCompletion {
         restored_handle: None,
         result: close_io_handle(handle).map(|_| CallReturn::one(Value::Bool(true))),
     })?;
-    Ok(BuiltinResult::Pending(op_id))
+    Ok(HostCallResult::Pending(op_id))
 }
 
 /// Returns whether a file system path exists.
 #[pd_host_function(name = "io::exists")]
-pub(super) fn builtin_io_exists(vm: &mut Vm, path: &str) -> VmResult<BuiltinResult<bool>> {
+pub(super) fn builtin_io_exists(vm: &mut Vm, path: &str) -> VmResult<HostCallResult<bool>> {
     let path = path.to_string();
     let op_id = schedule_io_task(vm, move || IoAsyncCompletion {
         restored_handle: None,
         result: Ok(CallReturn::one(Value::Bool(
             std::path::Path::new(path.as_str()).exists(),
         ))),
     })?;
-    Ok(BuiltinResult::Pending(op_id))
+    Ok(HostCallResult::Pending(op_id))
 }
 
 fn spawn_shell_command(command: &str, mode: &str) -> VmResult<Child> {