feat(compiler): finalize frame-local typing and ownership

Author: fffonion

build.rs

@@ -1201,9 +1201,9 @@ fn render_callable_consts(callables: &[&CallableDecl]) -> String {
         for param in &callable.params {
             writeln!(
                 &mut out,
-                "    CallableParam {{ name: {:?}, ty: CallableParamType::{}, optional: {} }},",
+                "    CallableParam {{ name: {:?}, ty: {}, optional: {} }},",
                 param.name,
-                callable_param_variant(&param.ty_label),
+                callable_param_expr(&param.ty_label),
                 param.optional
             )
             .unwrap();
@@ -1626,18 +1626,38 @@ fn callable_const_base(callable: &CallableDecl) -> String {
     to_shouty_snake(&format!("{prefix}_{}", callable.rust_ident))
 }
 
-fn callable_param_variant(label: &str) -> &'static str {
+pub(crate) fn callable_param_expr(label: &str) -> String {
     match label {
-        "any" => "Any",
-        "null" => "Null",
-        "int" => "Int",
-        "float" => "Float",
-        "bool" => "Bool",
-        "string" => "String",
-        "bytes" => "Bytes",
-        "array" => "Array",
-        "map" => "Map",
-        "number" => "Number",
+        "any" => "CallableParamType::Any".to_string(),
+        "null" => "CallableParamType::Null".to_string(),
+        "int" => "CallableParamType::Int".to_string(),
+        "float" => "CallableParamType::Float".to_string(),
+        "bool" => "CallableParamType::Bool".to_string(),
+        "string" => "CallableParamType::String".to_string(),
+        "bytes" => "CallableParamType::Bytes".to_string(),
+        "array" => "CallableParamType::Array".to_string(),
+        "map" => "CallableParamType::Map".to_string(),
+        "number" => "CallableParamType::Number".to_string(),
+        other if other.starts_with("fn(") => {
+            let (params, result) = other
+                .strip_prefix("fn(")
+                .and_then(|value| value.split_once(") -> "))
+                .unwrap_or_else(|| panic!("invalid callable schema '{other}'"));
+            let params = if params.is_empty() {
+                Vec::new()
+            } else {
+                params
+                    .split(", ")
+                    .map(callable_param_expr)
+                    .collect::<Vec<_>>()
+            };
+            let result = callable_param_expr(result);
+            format!(
+                "CallableParamType::Callable(CallableType {{ params: &[{}], return_type: &{} }})",
+                params.join(", "),
+                result
+            )
+        }
         other => panic!("unsupported callable param type '{other}'"),
     }
 }
@@ -2063,7 +2083,7 @@ fn static_return_type_label(output: &ReturnType) -> String {
     value_type_from_label(&return_type_label(output)).to_string()
 }
 
-fn type_label(ty: &Type) -> String {
+pub(crate) fn type_label(ty: &Type) -> String {
     match ty {
         Type::Group(group) => type_label(&group.elem),
         Type::Paren(paren) => type_label(&paren.elem),
@@ -2101,6 +2121,7 @@ fn type_label(ty: &Type) -> String {
                 "Array" | "VmArray" | "VmArrayRef" | "VmArrayHandle" => "array".to_string(),
                 "Map" | "VmMap" | "VmMapRef" | "VmMapHandle" => "map".to_string(),
                 "Number" | "NumberValue" => "number".to_string(),
+                "VmCallable" => callable_type_label(segment),
                 "Unknown" | "UnknownValue" => "unknown".to_string(),
                 "CallOutcome" => "unknown".to_string(),
                 "Option" => {
@@ -2129,6 +2150,25 @@ fn type_label(ty: &Type) -> String {
     }
 }
 
+fn callable_type_label(segment: &syn::PathSegment) -> String {
+    let syn::PathArguments::AngleBracketed(args) = &segment.arguments else {
+        panic!("VmCallable requires a function signature");
+    };
+    let Some(syn::GenericArgument::Type(Type::BareFn(function))) = args.args.first() else {
+        panic!("VmCallable requires fn(...) -> ...");
+    };
+    let params = function
+        .inputs
+        .iter()
+        .map(|input| type_label(&input.ty))
+        .collect::<Vec<_>>();
+    let result = match &function.output {
+        ReturnType::Default => "null".to_string(),
+        ReturnType::Type(_, ty) => type_label(ty),
+    };
+    format!("fn({}) -> {result}", params.join(", "))
+}
+
 fn type_label_for_vec(segment: &syn::PathSegment) -> String {
     let syn::PathArguments::AngleBracketed(args) = &segment.arguments else {
         panic!("Vec<T> requires one generic argument");
@@ -2303,3 +2343,26 @@ fn find_matching_paren(source: &str) -> usize {
     }
     panic!("unterminated macro invocation");
 }
+
+#[cfg(test)]
+mod callable_schema_tests {
+    use super::*;
+    use syn::parse_quote;
+
+    #[test]
+    fn build_metadata_renders_typed_callable_parameters() {
+        let ty: Type = parse_quote!(VmCallable<fn(VmMap) -> VmMap>);
+        assert_eq!(type_label(&ty), "fn(map) -> map");
+        assert_eq!(
+            callable_param_expr("fn(map) -> map"),
+            "CallableParamType::Callable(CallableType { params: &[CallableParamType::Map], return_type: &CallableParamType::Map })"
+        );
+
+        let float_ty: Type = parse_quote!(VmCallable<fn(f64) -> f64>);
+        assert_eq!(type_label(&float_ty), "fn(float) -> float");
+        assert_eq!(
+            callable_param_expr("fn(float) -> float"),
+            "CallableParamType::Callable(CallableType { params: &[CallableParamType::Float], return_type: &CallableParamType::Float })"
+        );
+    }
+}

docs/callable-runtime.md

@@ -1,15 +1,24 @@
 # Script call frames and callable values
 
-RustScript bytecode format version 11 (VMBC v11) introduces runtime script call frames, first-class callable values, and the static builtin ID catalog.
+RustScript bytecode format version 12 (VMBC v12) carries runtime script call frames, first-class callable values, the static builtin ID catalog, and the direct script-call opcode. Version 11 introduced frames, callable values, and the static catalog; version 12 adds `callscript` for statically resolved named calls.
 
 ## Bytecode contract
 
 - `call <import:u16> <argc:u8>` remains the direct host/builtin operation; the `u16` operand is an explicit static builtin call index from the catalog (or a host-import slot) — never a count-derived offset.
 - `callvalue <argc:u8>` consumes a stack segment in `callee, arg0, ..., argN` order.
+- `callscript <prototype_id:u32> <argc:u8>` calls a statically resolved named script function by prototype ID. It consumes only `argc` arguments; no callable value is taken from the stack, so environment-free named functions can be called without a hidden callable local.
 - callable environments are bound through the internal builtin call path; callable creation adds no bytecode opcode.
 - `ret` completes the active script frame. A nested frame leaves exactly one result at the caller segment base, using `null` when the body produced no value. Root `ret` keeps the historical program-result stack behavior.
 
-VMBC v11 is a hard format boundary. Decoders reject all earlier versions (v10 and below) with a deterministic unsupported-version error; there is no compatibility decoder and no old-ID alias. The stream includes script-function entry ranges, callable prototypes, function regions, root callable bindings, and call indices drawn from the static builtin catalog. PDRC v6 recordings and AOT artifacts (format 7, ABI 7) use their corresponding bumped versions and include callable metadata in cache identity.
+### Call ownership
+
+The three call opcodes differ in who owns the callee and what the frame must provide:
+
+- `call` — the callee is owned by the static builtin catalog (or the host-import slot). The frame contributes only `argc` arguments; there is no callable value anywhere in the program.
+- `callvalue` — the callee is a `Value::Callable` owned by the caller operand stack at the call site, and remains the caller's responsibility after the call. This path carries environments, closures, and any callable whose identity or capture state is runtime-valued.
+- `callscript` — the callee is owned by program callable metadata (the prototype table). The frame contributes only `argc` arguments and no callable value, but unlike `call` the callee is a script function rather than a builtin, so the call enters a new script frame with its own local base.
+
+VMBC v12 is a hard format boundary. Decoders reject all earlier versions (v11 and below) with a deterministic unsupported-version error; there is no compatibility decoder and no old-ID alias. The stream includes script-function entry ranges, callable prototypes, function regions, root callable bindings, and call indices drawn from the static builtin catalog. PDRC v6 recordings and AOT artifacts (format 8, ABI 8) use their corresponding bumped versions and include callable metadata in cache identity.
 
 ## Static builtin IDs
 
@@ -18,7 +27,7 @@ Every VM-visible builtin (ordinary, internal, and special-call) has one explicit
 - **Immutable explicit IDs.** IDs never change once assigned. Adding or reordering catalog entries never renumbers existing entries; new builtins take the next free ID in their documented block (extension `0x0000..=0xFF8F` for future builtins and host imports, special-call `0xFF90..=0xFFA1`, ordinary `0xFFA2..=0xFFFF`). The reserved sentinel gap `0xFF90..=0xFF92` stays unassigned.
 - **Build-time validation.** The build fails on duplicate IDs, duplicate source names, duplicate Rust variants, out-of-block IDs, class/gate inconsistencies, a discovered runtime callable without an explicit ID, or a catalog entry without a runtime callable.
 - **Shared std/no-std IDs.** `pd-vm-nostd` dispatches on the same static indices through the checked-in generated mirror `pd-vm-nostd/src/generated_builtin_ids.rs`; the workspace test `static_builtin_ids_are_frozen` fails when the mirror drifts from the catalog.
-- **One-time format break.** The static ID migration bumped VMBC to v11 (and the internal bytecode ABI to 11). Older VMBC versions are rejected, never decoded.
+- **Format breaks are permanent.** The static ID migration bumped VMBC to v11 (and the internal bytecode ABI to 11); the `callscript` opcode break bumped both to v12. Versions below the current format are rejected, never decoded.
 
 ## Runtime model
 
@@ -29,10 +38,24 @@ Each script invocation owns:
 - frame-local count;
 - active prototype and callable identity.
 
-Arguments, captures, named callable bindings, and the self binding are installed before control moves to the function entry. Recursive calls therefore allocate independent local storage and are limited to 1,024 script frames.
+Arguments, captures, hidden callable bindings for materialized named functions, and the self binding are installed before control moves to the function entry. Recursive calls therefore allocate independent local storage and are limited to 1,024 script frames.
 
 Branches are restricted to the active function region. Validation rejects cross-region targets before execution, and the interpreter repeats the check at runtime.
 
+## Frame-local allocation and callable materialization
+
+Each script invocation frame is an independent local-address space with its own `local_base`. Locals that are live at the same time inside one frame interfere and receive distinct relative slot numbers; locals that belong to different frames never interfere and may reuse the same relative slot number, because the runtime frame bases already separate them. A statically resolved named call keeps the caller's argument slots and post-call values live in the caller frame, while the callee body's locals are analyzed inside the callee frame.
+
+Named functions receive a hidden callable slot only when runtime `Value::Callable` identity is actually required:
+
+- the function is exported under the `ExportedCallable { local_slot }` contract;
+- the function is referenced as a value (stored, passed, or returned);
+- the function captures an environment;
+- a dynamic call site can target the function (invoked slot or argument flow into an invoked parameter);
+- the function's runtime self identity is required by a capturing or dynamic recursion path.
+
+Functions that only receive plain direct calls — including non-capturing direct recursion — are lowered through `callscript` by prototype ID and consume no hidden callable local. The compiler reports the aggregate frame-local count (data slots plus materialized callable slots) in `FrameLocalLimitExceeded` diagnostics, so overflow reports real counts instead of a sentinel. Genuine same-frame pressure beyond 256 simultaneous locals keeps failing until wide local bytecode lands.
+
 ## Callable identity and lifetime
 
 A callable contains its prototype ID, kind, and optional environment. The Program/Store owns the callable lifetime. Capture-free function items compare by prototype identity inside that Program; closures compare by runtime environment identity. Callable constants are forbidden; functions are initialized from Program metadata and closures are materialized at their declaration site.
@@ -57,8 +80,8 @@ Polling drives execution and provides backpressure: at most one event item is bu
 
 ## Optimized backends
 
-Whole-program AOT and Trace JIT use the same builtin call path (static catalog IDs) for environment binding and native frame dispatch for `callvalue`. Script-frame entry and return preserve frame-relative locals and typed continuations.
+Whole-program AOT and Trace JIT use the same builtin call path (static catalog IDs) for environment binding, native frame dispatch for `callvalue`, and prototype-direct native dispatch for `callscript`. Script-frame entry and return preserve frame-relative locals and typed continuations.
 
 ## Embedded runtime
 
-`pd-vm-nostd` decodes the same VMBC v11 callable metadata and executes callable binding, `callvalue`, recursive frames, captures, and direct host targets using `core` plus `alloc`, dispatching on the identical static builtin IDs via its checked-in generated mirror.
+`pd-vm-nostd` decodes the same VMBC v12 callable metadata and executes callable binding, `callvalue`, `callscript`, recursive frames, captures, and direct host targets using `core` plus `alloc`, dispatching on the identical static builtin IDs via its checked-in generated mirror.

pd-host-function/src/lib.rs

@@ -531,6 +531,7 @@ fn type_label(ty: &Type) -> Result<String, Error> {
                 "Array" | "VmArray" | "VmArrayRef" | "VmArrayHandle" => Ok("array".to_string()),
                 "Map" | "VmMap" | "VmMapRef" | "VmMapHandle" => Ok("map".to_string()),
                 "Number" | "NumberValue" => Ok("number".to_string()),
+                "VmCallable" => callable_type_label(segment),
                 "Unknown" | "UnknownValue" => Ok("unknown".to_string()),
                 "CallOutcome" => Ok("unknown".to_string()),
                 "Option" => {
@@ -575,6 +576,31 @@ fn type_label(ty: &Type) -> Result<String, Error> {
     }
 }
 
+fn callable_type_label(segment: &syn::PathSegment) -> Result<String, Error> {
+    let syn::PathArguments::AngleBracketed(args) = &segment.arguments else {
+        return Err(Error::new_spanned(
+            &segment.arguments,
+            "VmCallable requires a function signature",
+        ));
+    };
+    let Some(syn::GenericArgument::Type(Type::BareFn(function))) = args.args.first() else {
+        return Err(Error::new_spanned(
+            args,
+            "VmCallable requires fn(...) -> ...",
+        ));
+    };
+    let params = function
+        .inputs
+        .iter()
+        .map(|input| type_label(&input.ty))
+        .collect::<Result<Vec<_>, _>>()?;
+    let result = match &function.output {
+        ReturnType::Default => "null".to_string(),
+        ReturnType::Type(_, ty) => type_label(ty)?,
+    };
+    Ok(format!("fn({}) -> {result}", params.join(", ")))
+}
+
 fn type_label_for_vec(segment: &syn::PathSegment) -> Result<String, Error> {
     let syn::PathArguments::AngleBracketed(args) = &segment.arguments else {
         return Err(Error::new_spanned(
@@ -672,8 +698,8 @@ fn uses_taken_extractor(ty: &Type) -> bool {
 
 #[cfg(test)]
 mod tests {
-    use super::expand_pd_host_function;
-    use syn::{ItemFn, Meta, Token, parse_quote, punctuated::Punctuated};
+    use super::{expand_pd_host_function, type_label};
+    use syn::{ItemFn, Meta, Token, Type, parse_quote, punctuated::Punctuated};
 
     #[test]
     fn accepts_host_call_result_from_the_function_signature() {
@@ -779,4 +805,23 @@ mod tests {
                 .contains("parameters must be owned and 'static")
         );
     }
+
+    #[test]
+    fn callable_wrapper_preserves_parameter_and_result_schema() {
+        let ty: Type = parse_quote!(VmCallable<fn(VmMap) -> VmMap>);
+        assert_eq!(type_label(&ty).unwrap(), "fn(map) -> map");
+        let attr: Punctuated<Meta, Token![,]> = parse_quote!(name = "test::stream");
+        let item: ItemFn = parse_quote! {
+            /// Starts a synthetic callable stream.
+            fn stream(callback: VmCallable<fn(VmMap) -> VmMap>) -> VmResult<CallOutcome> {
+                todo!()
+            }
+        };
+        let expanded = expand_pd_host_function(attr, item).unwrap().to_string();
+        assert!(expanded.contains("VmCallable < fn (VmMap) -> VmMap >"));
+        assert!(expanded.contains("borrow_arg"));
+
+        let float_ty: Type = parse_quote!(VmCallable<fn(f64) -> f64>);
+        assert_eq!(type_label(&float_ty).unwrap(), "fn(float) -> float");
+    }
 }

pd-vm-nostd/README.md

@@ -6,7 +6,7 @@ compiler, parser, CLI, debugger, JIT/AOT backends, filesystem support, and opera
 
 ## Runtime surface
 
-- VMBC v11 decoding with script-call and callable metadata
+- VMBC v12 decoding with environment-free `CallScript` direct script calls alongside dynamic callable calls
 - stack, local, and recursive script-frame execution for direct bytecode opcodes
 - instruction fuel with pause/resume support
 - synchronous named host bindings and dynamic host dispatch