feat(compiler): allocate locals per script frame

Author: fffonion

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

pd-vm-nostd/src/error.rs

@@ -14,6 +14,12 @@ pub enum VmError {
     InvalidCall(u16),
     InvalidCallable,
     InvalidCallablePrototype(u32),
+    /// Frame metadata (root binding slots, parameter or capture slots)
+    /// does not match the script frame layout.
+    InvalidFrameState(&'static str),
+    /// `CallScript` targeted a prototype whose capture layout requires an
+    /// environment; a static script call can never supply one.
+    CallScriptRequiresEnvironment(u32),
     CallStackOverflow,
     InvalidCallStackLimit(usize),
     InvalidCallArity {
@@ -52,6 +58,11 @@ impl fmt::Display for VmError {
             Self::InvalidCallablePrototype(index) => {
                 write!(f, "invalid callable prototype: {index}")
             }
+            Self::InvalidFrameState(detail) => write!(f, "invalid frame state: {detail}"),
+            Self::CallScriptRequiresEnvironment(prototype_id) => write!(
+                f,
+                "callscript prototype {prototype_id} requires a callable environment"
+            ),
             Self::CallStackOverflow => f.write_str("script call stack overflow"),
             Self::InvalidCallStackLimit(limit) => {
                 write!(
@@ -96,6 +107,22 @@ pub enum WireError {
     InvalidDebugFlag(u8),
     InvalidValueType(u8),
     InvalidCaptureBindingMode(u8),
+    /// `CallScript` referenced a prototype id that is out of range or does
+    /// not target a script function.
+    InvalidCallScriptTarget {
+        prototype_id: u32,
+    },
+    /// `CallScript` declared an argc that disagrees with the prototype arity.
+    InvalidCallScriptArity {
+        prototype_id: u32,
+        expected: u8,
+        got: u8,
+    },
+    /// An instruction operand is truncated by the end of the code blob.
+    TruncatedOperand {
+        opcode: u8,
+        expected_bytes: usize,
+    },
     InvalidUtf8,
     LengthTooLarge(&'static str, usize),
     SchemaTooDeep,
@@ -119,6 +146,25 @@ impl fmt::Display for WireError {
             Self::InvalidCaptureBindingMode(value) => {
                 write!(f, "invalid capture binding mode: {value}")
             }
+            Self::InvalidCallScriptTarget { prototype_id } => write!(
+                f,
+                "callscript prototype {prototype_id} does not target a script function"
+            ),
+            Self::InvalidCallScriptArity {
+                prototype_id,
+                expected,
+                got,
+            } => write!(
+                f,
+                "callscript prototype {prototype_id} arity mismatch: expected {expected}, got {got}"
+            ),
+            Self::TruncatedOperand {
+                opcode,
+                expected_bytes,
+            } => write!(
+                f,
+                "truncated operand for opcode {opcode:#04x}: expected {expected_bytes} bytes"
+            ),
             Self::InvalidUtf8 => f.write_str("invalid UTF-8 in VMBC string"),
             Self::LengthTooLarge(field, length) => {
                 write!(f, "{field} length is too large: {length}")

pd-vm-nostd/src/program.rs

@@ -230,6 +230,12 @@ pub enum OpCode {
     Not = 0x17,
     Lshr = 0x18,
     CallValue = 0x19,
+    /// Static direct script-function call: `prototype_id:u32 LE, argc:u8`.
+    ///
+    /// Mirrors the std ISA contract (opcode 0x1A, five operand bytes); the
+    /// decoder validates the target prototype and arity against the callable
+    /// metadata so an environment-free script call is a supported operation.
+    CallScript = 0x1A,
 }
 
 impl OpCode {
@@ -238,6 +244,7 @@ impl OpCode {
             Self::Ldc | Self::Br | Self::Brfalse => 4,
             Self::Ldloc | Self::Stloc | Self::CallValue => 1,
             Self::Call => 3,
+            Self::CallScript => 5,
             _ => 0,
         }
     }
@@ -274,6 +281,7 @@ impl TryFrom<u8> for OpCode {
             0x17 => Ok(Self::Not),
             0x18 => Ok(Self::Lshr),
             0x19 => Ok(Self::CallValue),
+            0x1a => Ok(Self::CallScript),
             _ => Err(()),
         }
     }