feat(vm)!: implement typed callables and single-context execution
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good

Add structural Fn signatures, typed capture environments, indirect calls and Trait dispatch while preserving logical parameter and result groups, ownership and budgets.

Remove guest coroutine execution and legacy loading. Activate bounded sealed PBX v1 with mandatory capture metadata, preserve frame continuations and root return results, and migrate producers and shipped cartridges.

Publish coordinated specs, handoffs and the completed runtime lesson. Validation: 880 workspace tests passed, 9 existing tests ignored; both cartridges completed six production-host frames.
This commit is contained in:
2026-10-09 05:47:24 +01:00
parent 86bade3e1f
commit ec84a6bba5
96 changed files with 3656 additions and 6075 deletions
+30 -204
View File
@@ -1,5 +1,4 @@
mod dynamic_box;
use crate::call_frame::CallFrame;
use crate::object::{ObjectHeader, ObjectKind};
use crate::resource_budget::{
BudgetVec, Reservation, ResourceFailure, ResourceReason, RuntimeBudget, RuntimeResource as Q,
@@ -30,8 +29,6 @@ pub struct StoredObject {
/// they stay directly GC-visible. The GC must traverse exactly `env_len`
/// entries from this slice, in order.
pub closure_env: Option<BudgetVec<Value>>,
/// Optional coroutine data for `ObjectKind::Coroutine`.
pub coroutine: Option<CoroutineData>,
/// Registry-backed compact Struct/Array fields, never raw Value elements.
typed: Option<TypedStorage>,
/// Immutable native Value slots; not accessible through collection helpers.
@@ -76,26 +73,6 @@ struct PreparedSlot {
free: Option<VecGrowth<usize>>,
}
/// Execution state of a coroutine.
#[derive(Debug, Copy, Clone, Eq, PartialEq)]
pub enum CoroutineState {
Ready,
Running,
Sleeping,
Finished,
// Faulted,
}
/// Stored payload for coroutine objects.
#[derive(Debug)]
pub struct CoroutineData {
pub pc: usize,
pub state: CoroutineState,
pub wake_tick: u64,
pub stack: BudgetVec<Value>,
pub frames: BudgetVec<CallFrame>,
}
/// Non-moving, generation-checked heap with safepoint mark/sweep.
#[derive(Debug)]
pub struct Heap {
@@ -127,25 +104,6 @@ impl Heap {
self.used_bytes.fetch_sub(old, Ordering::Relaxed);
self.used_bytes.fetch_add(new, Ordering::Relaxed);
}
#[cfg(test)]
pub(crate) fn table_capacity_bytes(&self) -> u64 {
self.objects.accounted_bytes()
+ self.generations.accounted_bytes()
+ self.free_list.accounted_bytes()
}
#[cfg(test)]
pub(crate) fn execution_capacity_bytes(&self) -> u64 {
self.objects
.iter()
.flatten()
.filter_map(|object| object.coroutine.as_ref())
.map(|co| {
(co.stack.capacity() * size_of::<Value>()
+ co.frames.capacity() * size_of::<CallFrame>()) as u64
})
.sum()
}
#[cfg(test)]
pub fn new() -> Self {
@@ -233,7 +191,6 @@ impl Heap {
payload,
array_elems: None,
closure_env: None,
coroutine: None,
typed: None,
dynamic_box: None,
})
@@ -249,7 +206,6 @@ impl Heap {
payload: BudgetVec::new(&self.budget, Q::GuestBytes),
array_elems: Some(elems),
closure_env: None,
coroutine: None,
typed: None,
dynamic_box: None,
})
@@ -261,44 +217,25 @@ impl Heap {
})
}
pub fn alloc_closure(
pub(crate) fn alloc_typed_closure(
&mut self,
fn_id: u32,
fn_type: TypeId,
env_values: &[Value],
) -> Result<HeapRef, ResourceFailure> {
self.check_slot()?;
let env_len = self.payload_len(env_values.len())?;
let mut bytes = [0; 8];
let mut bytes = [0; 12];
bytes[..4].copy_from_slice(&fn_id.to_le_bytes());
bytes[4..].copy_from_slice(&env_len.to_le_bytes());
bytes[4..8].copy_from_slice(&env_len.to_le_bytes());
bytes[8..12].copy_from_slice(&fn_type.0.to_le_bytes());
let payload = BudgetVec::from_slice(&self.budget, Q::GuestBytes, &bytes)?;
let env = BudgetVec::from_slice(&self.budget, Q::GuestBytes, env_values)?;
self.insert_object(StoredObject {
header: ObjectHeader::new(ObjectKind::Closure, 8),
header: ObjectHeader::new(ObjectKind::Closure, 12),
payload,
array_elems: None,
closure_env: Some(env),
coroutine: None,
typed: None,
dynamic_box: None,
})
}
pub fn allocate_coroutine(
&mut self,
pc: usize,
state: CoroutineState,
wake_tick: u64,
stack: BudgetVec<Value>,
frames: BudgetVec<CallFrame>,
) -> Result<HeapRef, ResourceFailure> {
self.check_slot()?;
self.insert_object(StoredObject {
header: ObjectHeader::new(ObjectKind::Coroutine, 0),
payload: BudgetVec::new(&self.budget, Q::GuestBytes),
array_elems: None,
closure_env: None,
coroutine: Some(CoroutineData { pc, state, wake_tick, stack, frames }),
typed: None,
dynamic_box: None,
})
@@ -313,28 +250,6 @@ impl Heap {
r.generation != 0 && self.generations[idx] == r.generation && self.objects[idx].is_some()
}
/// Returns a shared reference to the coroutine data for the given handle, if it is a Coroutine.
#[cfg(test)]
pub fn coroutine_data(&self, r: HeapRef) -> Option<&CoroutineData> {
if !self.is_valid(r) {
return None;
}
let idx = r.index as usize;
self.objects.get(idx).and_then(|slot| slot.as_ref()).and_then(|obj| obj.coroutine.as_ref())
}
/// Returns a mutable reference to the coroutine data for the given handle, if it is a Coroutine.
pub fn coroutine_data_mut(&mut self, r: HeapRef) -> Option<&mut CoroutineData> {
if !self.is_valid(r) {
return None;
}
let idx = r.index as usize;
self.objects
.get_mut(idx)
.and_then(|slot| slot.as_mut())
.and_then(|obj| obj.coroutine.as_mut())
}
/// Get immutable access to an object's header by handle.
pub fn header(&self, r: HeapRef) -> Option<&ObjectHeader> {
if !self.is_valid(r) {
@@ -351,6 +266,22 @@ impl Heap {
self.objects.get_mut(r.index as usize).and_then(|slot| slot.as_mut()).map(|o| &mut o.header)
}
pub(crate) fn closure_type(&self, r: HeapRef) -> Result<TypeId, ValueError> {
if !self.is_valid(r) {
return Err(ValueError::InvalidHandle);
}
let object = self.objects[r.index as usize].as_ref().unwrap();
if object.header.kind != ObjectKind::Closure || object.payload.len() != 12 {
return Err(ValueError::Type);
}
Ok(TypeId(u32::from_le_bytes(object.payload[8..12].try_into().unwrap())))
}
#[cfg(test)]
pub fn alloc_closure(&mut self, fn_id: u32, env: &[Value]) -> Result<HeapRef, ResourceFailure> {
self.alloc_typed_closure(fn_id, TypeId(0), env)
}
/// Read the `fn_id` stored in a closure object. Returns None if kind mismatch or invalid ref.
pub fn closure_fn_id(&self, r: HeapRef) -> Option<u32> {
if !self.is_valid(r) {
@@ -364,15 +295,14 @@ impl Heap {
if slot.payload.len() < 8 {
return None;
}
debug_assert_eq!(slot.header.payload_len, 8);
debug_assert_eq!(slot.header.payload_len, 12);
let mut bytes = [0u8; 4];
bytes.copy_from_slice(&slot.payload[0..4]);
Some(u32::from_le_bytes(bytes))
}
/// Get the captured environment slice of a closure. Returns None if kind mismatch or invalid ref.
#[cfg(test)]
pub fn closure_env_slice(&self, r: HeapRef) -> Option<&[Value]> {
pub(crate) fn closure_env_slice(&self, r: HeapRef) -> Option<&[Value]> {
if !self.is_valid(r) {
return None;
}
@@ -399,14 +329,14 @@ impl Heap {
&mut self,
roots: I,
) -> Result<(), ResourceFailure> {
self.mark(roots, false)
self.mark(roots)
}
pub fn mark_session_roots<I: IntoIterator<Item = HeapRef>>(
&mut self,
roots: I,
) -> Result<(), ResourceFailure> {
self.mark(roots, true)
self.mark(roots)
}
fn enqueue_mark(&mut self, r: HeapRef, stack: &mut BudgetVec<HeapRef>) {
@@ -425,35 +355,16 @@ impl Heap {
ObjectKind::Array => obj.array_elems.as_deref().unwrap_or(&[]),
ObjectKind::Closure => obj.closure_env.as_deref().unwrap_or(&[]),
ObjectKind::DynamicBox => obj.dynamic_box.as_ref().map_or(&[], DynamicBox::values),
ObjectKind::Coroutine => obj.coroutine.as_ref().map_or(&[], |co| co.stack.as_slice()),
_ => &[],
}
}
fn mark<I: IntoIterator<Item = HeapRef>>(
&mut self,
roots: I,
suspended: bool,
) -> Result<(), ResourceFailure> {
fn mark<I: IntoIterator<Item = HeapRef>>(&mut self, roots: I) -> Result<(), ResourceFailure> {
let mut stack = BudgetVec::new(&self.budget, Q::TemporaryBytes);
stack.reserve(self.len())?; // Fail before changing any mark bit.
for root in roots {
self.enqueue_mark(root, &mut stack);
}
if suspended {
for idx in 0..self.objects.len() {
let root =
self.objects[idx].as_ref().and_then(|o| o.coroutine.as_ref()).is_some_and(
|co| matches!(co.state, CoroutineState::Ready | CoroutineState::Sleeping),
);
if root {
self.enqueue_mark(
HeapRef { index: idx as u32, generation: self.generations[idx] },
&mut stack,
);
}
}
}
while let Some(r) = stack.pop() {
let typed_count = self.objects[r.index as usize]
.as_ref()
@@ -515,18 +426,6 @@ impl Heap {
pub fn allocation_count(&self) -> u64 {
self.allocation_count.load(Ordering::Relaxed)
}
/// Enumerate handles of coroutines that are currently suspended (i.e., not running):
/// Ready or Sleeping. These must be treated as GC roots by the runtime so their
/// stacks/frames are scanned during mark.
#[cfg(test)]
pub fn suspended_coroutine_handles(&self) -> impl Iterator<Item = HeapRef> + '_ {
self.objects.iter().enumerate().filter_map(|(idx, slot)| {
let co = slot.as_ref()?.coroutine.as_ref()?;
matches!(co.state, CoroutineState::Ready | CoroutineState::Sleeping)
.then_some(HeapRef { index: idx as u32, generation: self.generations[idx] })
})
}
}
// Internal consumer seam for PLN-0176 step 18 / AGD-0054. Executable image
@@ -598,7 +497,6 @@ impl Heap {
payload: BudgetVec::new(&self.budget, Q::GuestBytes),
array_elems: None,
closure_env: None,
coroutine: None,
typed: Some(storage),
dynamic_box: None,
},
@@ -656,7 +554,6 @@ impl Heap {
payload: BudgetVec::new(&self.budget, Q::GuestBytes),
array_elems: None,
closure_env: None,
coroutine: None,
typed: None,
dynamic_box: Some(dynamic_box),
})?)
@@ -750,38 +647,6 @@ mod tests {
assert_eq!(heap.generations[last.index as usize], u32::MAX);
}
#[test]
fn null_zero_generation_and_dead_coroutine_handles_are_rejected() {
let mut heap = Heap::new();
let old = heap
.allocate_coroutine(
0,
CoroutineState::Ready,
0,
BudgetVec::fixture(vec![]),
BudgetVec::fixture(vec![]),
)
.unwrap();
assert!(!heap.is_valid(HeapRef::NULL));
assert!(!heap.is_valid(HeapRef { index: 1, generation: 0 }));
assert!(!heap.is_valid(HeapRef { index: u32::MAX, generation: 1 }));
heap.sweep();
let next = heap
.allocate_coroutine(
2,
CoroutineState::Ready,
0,
BudgetVec::fixture(vec![]),
BudgetVec::fixture(vec![]),
)
.unwrap();
assert!(heap.coroutine_data(old).is_none());
assert!(heap.coroutine_data_mut(old).is_none());
assert_eq!(heap.suspended_coroutine_handles().collect::<Vec<_>>(), vec![next]);
assert_eq!(size_of::<HeapRef>(), 8);
assert_eq!(align_of::<HeapRef>(), 8);
}
#[test]
fn basic_allocation_returns_valid_refs() {
let mut heap = Heap::new();
@@ -808,45 +673,6 @@ mod tests {
assert_eq!(h3.payload_len, 0);
}
#[test]
fn allocate_and_transition_coroutine() {
let mut heap = Heap::new();
// Create a coroutine with a small stack containing a HeapRef to verify GC traversal later.
let obj_ref = heap.allocate_object(ObjectKind::Bytes, &[4, 5, 6]).unwrap();
let coro = heap
.allocate_coroutine(
0,
CoroutineState::Ready,
0,
BudgetVec::fixture(vec![Value::Int32(1), Value::HeapRef(obj_ref)]),
BudgetVec::fixture(vec![CallFrame { return_pc: 0, stack_base: 0, func_idx: 0 }]),
)
.unwrap();
let hdr = heap.header(coro).unwrap();
assert_eq!(hdr.kind, ObjectKind::Coroutine);
assert_eq!(hdr.payload_len, 0);
// Manually mutate state transitions via access to inner data.
{
let slot = heap.objects.get_mut(coro.index as usize).and_then(|s| s.as_mut()).unwrap();
let co = slot.coroutine.as_mut().unwrap();
assert_eq!(co.state, CoroutineState::Ready);
co.state = CoroutineState::Running;
assert_eq!(co.state, CoroutineState::Running);
co.state = CoroutineState::Sleeping;
co.wake_tick = 42;
assert_eq!(co.wake_tick, 42);
co.state = CoroutineState::Finished;
assert_eq!(co.state, CoroutineState::Finished);
}
// GC should mark the object referenced from the coroutine stack when the coroutine is a root.
heap.mark_from_roots([coro]).unwrap();
assert!(heap.header(obj_ref).unwrap().is_marked());
}
#[test]
fn mark_reachable_through_array() {
let mut heap = Heap::new();
@@ -910,7 +736,7 @@ mod tests {
let h = heap.header(c).unwrap();
assert_eq!(h.kind, ObjectKind::Closure);
// payload has only metadata (8 bytes)
assert_eq!(h.payload_len, 8);
assert_eq!(h.payload_len, 12);
assert_eq!(heap.closure_fn_id(c), Some(42));
let env = heap.closure_env_slice(c).unwrap();
assert_eq!(env.len(), 0);
@@ -925,7 +751,7 @@ mod tests {
let h = heap.header(c).unwrap();
assert_eq!(h.kind, ObjectKind::Closure);
assert_eq!(h.payload_len, 8);
assert_eq!(h.payload_len, 12);
assert_eq!(heap.closure_fn_id(c), Some(7));
let env = heap.closure_env_slice(c).unwrap();
assert_eq!(env, &env_vals[..]);
@@ -1146,7 +972,7 @@ mod tests {
#[test]
fn guest_header_and_payload_limits_refund_failed_construction() {
let required = (size_of::<StoredObject>() + 8 + size_of::<Value>()) as u64;
let required = (size_of::<StoredObject>() + 12 + size_of::<Value>()) as u64;
let (mut heap, budget) = tiny_heap(Q::GuestBytes, required - 1);
assert_eq!(heap.alloc_closure(0, &[Value::Int64(9)]).unwrap_err().resource, Q::GuestBytes);
for q in [Q::GuestBytes, Q::HandleSlots, Q::AuxiliaryBytes, Q::TemporaryBytes] {