feat(vm): add typed array and struct guest operations
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good

Add seven Registry-backed collection opcodes with bounded verification, complete value groups, transactional publication and exact attempt costs. Publish ISA, memory and cycle contracts, producer handoff and the completed lesson.

Validate with 925 workspace tests, optimized collection suites and all eight coverage domain gates. Make headless fixture directory names unique for parallel tests.
This commit is contained in:
2026-10-08 10:36:20 +01:00
parent 8732f4b0f4
commit 86bade3e1f
27 changed files with 1591 additions and 46 deletions
@@ -360,6 +360,29 @@ pub fn assemble(src: &str) -> Result<Vec<u8>, AsmError> {
emit_u32(parse_u32_any(ops)?, &mut out);
}
"STRUCT_GET" | "STRUCT_SET" => {
let (a, b) = parse_keyvals(ops)?;
let (ty, field) = parse_pair(a, "type", b, "field")?;
let op =
if mn == "STRUCT_GET" { CoreOpCode::StructGet } else { CoreOpCode::StructSet };
emit_u16(op as u16, &mut out);
emit_u32(ty, &mut out);
emit_u32(field, &mut out);
}
"STRUCT_NEW" | "ARRAY_NEW" | "ARRAY_LEN" | "ARRAY_GET" | "ARRAY_SET" => {
if ops.is_empty() {
return Err(AsmError::MissingOperand(line.into()));
}
let op = match mn {
"STRUCT_NEW" => CoreOpCode::StructNew,
"ARRAY_NEW" => CoreOpCode::ArrayNew,
"ARRAY_LEN" => CoreOpCode::ArrayLen,
"ARRAY_GET" => CoreOpCode::ArrayGet,
_ => CoreOpCode::ArraySet,
};
emit_u16(op as u16, &mut out);
emit_u32(parse_u32_any(ops)?, &mut out);
}
"DYN_PACK" | "DYN_UNPACK" | "DYN_CAN_UNPACK" => {
if ops.is_empty() {
return Err(AsmError::MissingOperand(line.into()));
@@ -63,10 +63,20 @@ fn format_operand(op: CoreOpCode, imm: &[u8]) -> String {
| CoreOpCode::Hostcall
| CoreOpCode::DynPack
| CoreOpCode::DynUnpack
| CoreOpCode::DynCanUnpack => {
| CoreOpCode::DynCanUnpack
| CoreOpCode::StructNew
| CoreOpCode::ArrayNew
| CoreOpCode::ArrayLen
| CoreOpCode::ArrayGet
| CoreOpCode::ArraySet => {
let v = u32::from_le_bytes(imm.try_into().unwrap());
format!("{}", v)
}
CoreOpCode::StructGet | CoreOpCode::StructSet => {
let ty = u32::from_le_bytes(imm[..4].try_into().unwrap());
let field = u32::from_le_bytes(imm[4..].try_into().unwrap());
format!("type={}, field={}", ty, field)
}
CoreOpCode::RefIsExact
| CoreOpCode::RefImplements
| CoreOpCode::RefToTrait
+26 -2
View File
@@ -218,6 +218,15 @@ pub enum OpCode {
RefToTrait = 0x95,
/// REF_CAST: source:TypeId, target:TypeId; requires validated Registry metadata.
RefCast = 0x96,
// Registry-backed collection operations. cycles() is their base component.
StructNew = 0xA0,
StructGet = 0xA1,
StructSet = 0xA2,
ArrayNew = 0xA3,
ArrayLen = 0xA4,
ArrayGet = 0xA5,
ArraySet = 0xA6,
}
impl TryFrom<u16> for OpCode {
@@ -282,6 +291,13 @@ impl TryFrom<u16> for OpCode {
0x94 => Ok(OpCode::RefImplements),
0x95 => Ok(OpCode::RefToTrait),
0x96 => Ok(OpCode::RefCast),
0xA0 => Ok(OpCode::StructNew),
0xA1 => Ok(OpCode::StructGet),
0xA2 => Ok(OpCode::StructSet),
0xA3 => Ok(OpCode::ArrayNew),
0xA4 => Ok(OpCode::ArrayLen),
0xA5 => Ok(OpCode::ArrayGet),
0xA6 => Ok(OpCode::ArraySet),
_ => Err(format!("Invalid OpCode: 0x{:04X}", value)),
}
@@ -289,8 +305,9 @@ impl TryFrom<u16> for OpCode {
}
impl OpCode {
/// Returns the cost of the instruction in VM cycles.
/// This is used for performance monitoring and resource limiting (Certification).
/// Returns fixed VM cycles, or the base component for collection operations.
/// Collection execution adds Registry widths and valid construction length;
/// callers must not use this base alone as the complete attempt cost.
pub fn cycles(&self) -> u64 {
match self {
OpCode::Nop => 1,
@@ -350,6 +367,13 @@ impl OpCode {
OpCode::RefImplements => 4,
OpCode::RefToTrait => 5,
OpCode::RefCast => 4,
OpCode::StructNew => 8,
OpCode::StructGet => 3,
OpCode::StructSet => 4,
OpCode::ArrayNew => 8,
OpCode::ArrayLen => 3,
OpCode::ArrayGet => 3,
OpCode::ArraySet => 4,
}
}
}
@@ -599,6 +599,76 @@ impl OpCodeSpecExt for OpCode {
may_trap: true,
is_safepoint: false,
},
OpCode::StructNew => OpcodeSpec {
name: "STRUCT_NEW",
imm_bytes: 4,
pops: None,
pushes: None,
is_branch: false,
is_terminator: false,
may_trap: true,
is_safepoint: false,
},
OpCode::StructGet => OpcodeSpec {
name: "STRUCT_GET",
imm_bytes: 8,
pops: None,
pushes: None,
is_branch: false,
is_terminator: false,
may_trap: true,
is_safepoint: false,
},
OpCode::StructSet => OpcodeSpec {
name: "STRUCT_SET",
imm_bytes: 8,
pops: None,
pushes: None,
is_branch: false,
is_terminator: false,
may_trap: true,
is_safepoint: false,
},
OpCode::ArrayNew => OpcodeSpec {
name: "ARRAY_NEW",
imm_bytes: 4,
pops: None,
pushes: None,
is_branch: false,
is_terminator: false,
may_trap: true,
is_safepoint: false,
},
OpCode::ArrayLen => OpcodeSpec {
name: "ARRAY_LEN",
imm_bytes: 4,
pops: None,
pushes: None,
is_branch: false,
is_terminator: false,
may_trap: true,
is_safepoint: false,
},
OpCode::ArrayGet => OpcodeSpec {
name: "ARRAY_GET",
imm_bytes: 4,
pops: None,
pushes: None,
is_branch: false,
is_terminator: false,
may_trap: true,
is_safepoint: false,
},
OpCode::ArraySet => OpcodeSpec {
name: "ARRAY_SET",
imm_bytes: 4,
pops: None,
pushes: None,
is_branch: false,
is_terminator: false,
may_trap: true,
is_safepoint: false,
},
OpCode::FrameSync => OpcodeSpec {
name: "FRAME_SYNC",
imm_bytes: 0,
@@ -178,6 +178,8 @@ pub struct OwnedField {
}
#[derive(Debug, PartialEq, Eq)]
pub struct StructLayout {
/// Sum of execution-slot widths, resolved once for deterministic NEW charging.
pub initialization_slots: u64,
pub size: usize,
pub alignment: usize,
pub fields: Vec<FieldLayout>,
@@ -277,9 +279,13 @@ impl Registry {
.count();
let mut owned = b.vector(owned_count, Q::RegistryBytes)?;
let (mut size, mut alignment) = (0, 1);
let mut initialization_slots = 0u64;
for field in fields {
b.work(1)?;
let layout = layouts[field.type_id.0 as usize].storage;
initialization_slots = initialization_slots
.checked_add(u64::from(layout.slots))
.ok_or_else(overflow)?;
size = align(size, layout.alignment)?;
offsets.push(FieldLayout { type_id: field.type_id, offset: size });
if layout.ownership != Ownership::Plain {
@@ -289,6 +295,7 @@ impl Registry {
alignment = alignment.max(layout.alignment);
}
layouts[i].instance = Some(StructLayout {
initialization_slots,
size: align(size, alignment)?,
alignment,
fields: offsets,
@@ -76,6 +76,46 @@ impl DecodedInstr<'_> {
};
(source_layout.storage.slots, pushes)
}
Op::StructNew
| Op::StructGet
| Op::StructSet
| Op::ArrayNew
| Op::ArrayLen
| Op::ArrayGet
| Op::ArraySet => {
let (id, field) = if matches!(self.opcode, Op::StructGet | Op::StructSet) {
self.imm_u32x2().map_err(|_| malformed())?
} else {
(self.imm_u32().map_err(|_| malformed())?, 0)
};
let (_, layout) = type_info(id)?;
if matches!(self.opcode, Op::StructNew | Op::StructGet | Op::StructSet) {
let instance = layout.instance.as_ref().ok_or_else(|| bad_category(id))?;
match self.opcode {
Op::StructNew => (0, 1),
op => {
let f = instance
.fields
.get(field as usize)
.ok_or_else(|| bad_category(id).member(field))?;
let w = registry.type_layout(f.type_id).unwrap().storage.slots;
if op == Op::StructGet {
(1, w)
} else {
(1 + w, 0)
}
}
}
} else {
let array = layout.array.as_ref().ok_or_else(|| bad_category(id))?;
let w = registry.type_layout(array.element_type_id).unwrap().storage.slots;
match self.opcode {
Op::ArrayNew | Op::ArrayLen => (1, 1),
Op::ArrayGet => (2, w),
_ => (2 + w, 0),
}
}
}
_ => unreachable!("requires_registry is defined by the typed opcode catalogue"),
};
Ok(Some(RegistryStackEffect { pops, pushes }))
@@ -126,3 +126,79 @@ fn decoder_extreme_pc_does_not_overflow() {
));
assert_eq!(Op::DynPack as u16, 0x0090);
}
#[test]
fn collection_literal_encodings_roundtrip_and_reject_every_truncation() {
for (text, bytes, base) in [
("STRUCT_NEW 16909060", vec![0xa0, 0, 4, 3, 2, 1], 8),
("STRUCT_GET type=16909060, field=84281096", vec![0xa1, 0, 4, 3, 2, 1, 8, 7, 6, 5], 3),
("STRUCT_SET type=16909060, field=84281096", vec![0xa2, 0, 4, 3, 2, 1, 8, 7, 6, 5], 4),
("ARRAY_NEW 16909060", vec![0xa3, 0, 4, 3, 2, 1], 8),
("ARRAY_LEN 16909060", vec![0xa4, 0, 4, 3, 2, 1], 3),
("ARRAY_GET 16909060", vec![0xa5, 0, 4, 3, 2, 1], 3),
("ARRAY_SET 16909060", vec![0xa6, 0, 4, 3, 2, 1], 4),
] {
assert_eq!(assemble(text).unwrap(), bytes);
assert_eq!(disassemble(&bytes).unwrap(), text);
let op = decode_next(0, &bytes).unwrap().opcode;
assert_eq!(op.cycles(), base);
assert!(op.requires_registry() && op.spec().may_trap);
assert!(!op.spec().is_safepoint && !op.spec().is_branch && !op.spec().is_terminator);
for n in 0..bytes.len() {
assert!(decode_next(0, &bytes[..n]).is_err());
}
}
for bad in [
"STRUCT_NEW",
"ARRAY_NEW -1",
"ARRAY_GET 4294967296",
"ARRAY_LEN 1 2",
"STRUCT_GET type=1",
"STRUCT_SET type=1, field=2, field=3",
"STRUCT_GET type=1, field=-1",
] {
assert!(assemble(bad).is_err(), "{bad}");
}
}
#[test]
fn collection_effects_and_cached_initialization_width_are_exact() {
let mut d = RegistryDeclarations::default();
d.types = vec![
TypeDecl { name: None, kind: TypeKind::Builtin(BuiltinId::PIXEL) },
TypeDecl {
name: None,
kind: TypeKind::Struct(vec![
NamedType { type_id: TypeId(0), name: None },
NamedType { type_id: TypeId(1), name: None },
]),
},
TypeDecl { name: None, kind: TypeKind::Array(TypeId(0)) },
];
let r = Registry::resolve(d, 0, &mut LoadBudget::new(Default::default())).unwrap();
assert_eq!(
r.type_layout(TypeId(1)).unwrap().instance.as_ref().unwrap().initialization_slots,
4
);
for (s, pops, pushes) in [
("STRUCT_NEW 1", 0, 1),
("STRUCT_GET type=1, field=0", 1, 3),
("STRUCT_SET type=1, field=0", 4, 0),
("ARRAY_NEW 2", 1, 1),
("ARRAY_LEN 2", 1, 1),
("ARRAY_GET 2", 2, 3),
("ARRAY_SET 2", 5, 0),
] {
let code = assemble(s).unwrap();
assert_eq!(
decode_next(0, &code).unwrap().registry_stack_effect(&r).unwrap(),
Some(RegistryStackEffect { pops, pushes })
);
}
for s in ["STRUCT_NEW 0", "ARRAY_NEW 1", "STRUCT_GET type=1, field=2", "ARRAY_GET 99"] {
let code = assemble(s).unwrap();
assert_eq!(
decode_next(0, &code).unwrap().registry_stack_effect(&r).unwrap_err().code,
LoadCode::InvalidReference
);
}
}
+77 -31
View File
@@ -3,6 +3,7 @@ use crate::call_frame::CallFrame;
use crate::object::{ObjectHeader, ObjectKind};
use crate::resource_budget::{
BudgetVec, Reservation, ResourceFailure, ResourceReason, RuntimeBudget, RuntimeResource as Q,
VecGrowth,
};
use crate::typed_storage::TypedStorage;
use crate::value_contract::{self, ValueError, ValueGroup};
@@ -62,6 +63,19 @@ impl StoredAllocation {
}
}
// Candidate allocations own all reservations until a fully initialized object
// is published. Dropping the candidate leaves handle tables unchanged.
struct PreparedInsertion {
storage: BudgetVec<StoredObject>,
new_slot: Option<PreparedSlot>,
}
struct PreparedSlot {
charge: Reservation,
objects: Option<VecGrowth<Option<StoredAllocation>>>,
generations: Option<VecGrowth<u32>>,
free: Option<VecGrowth<usize>>,
}
/// Execution state of a coroutine.
#[derive(Debug, Copy, Clone, Eq, PartialEq)]
pub enum CoroutineState {
@@ -157,24 +171,35 @@ impl Heap {
Ok(())
}
fn insert_object(&mut self, obj: StoredObject) -> Result<HeapRef, ResourceFailure> {
fn prepare_insertion(&self) -> Result<PreparedInsertion, ResourceFailure> {
self.check_slot()?;
let mut storage = BudgetVec::new(&self.budget, Q::GuestBytes);
storage.push(obj)?;
let obj = StoredAllocation(storage);
let bytes = obj.bytes();
let handle = if let Some(&idx) = self.free_list.last() {
self.free_list.pop();
debug_assert!(self.objects[idx].is_none());
self.objects[idx] = Some(obj);
HeapRef { index: idx as u32, generation: self.generations[idx] }
storage.reserve(1)?;
let new_slot = if self.free_list.is_empty() {
Some(PreparedSlot {
charge: self.budget.reserve(Q::HandleSlots, 1)?,
objects: self.objects.prepare_growth(1)?,
generations: self.generations.prepare_growth(1)?,
free: self
.free_list
.prepare_growth(self.objects.len() + 1 - self.free_list.len())?,
})
} else {
let slot_charge = self.budget.reserve(Q::HandleSlots, 1)?;
// Stage all three capacities. Failure drops the candidate buffers and
// object, without publishing a slot or retaining partial table growth.
let objects = self.objects.prepare_growth(1)?;
let generations = self.generations.prepare_growth(1)?;
let free =
self.free_list.prepare_growth(self.objects.len() + 1 - self.free_list.len())?;
None
};
Ok(PreparedInsertion { storage, new_slot })
}
fn insert_object(&mut self, obj: StoredObject) -> Result<HeapRef, ResourceFailure> {
let prepared = self.prepare_insertion()?;
Ok(self.commit_insertion(prepared, obj))
}
fn commit_insertion(&mut self, mut prepared: PreparedInsertion, obj: StoredObject) -> HeapRef {
prepared.storage.push(obj).expect("object header reserved before initialization");
let obj = StoredAllocation(prepared.storage);
let bytes = obj.bytes();
let handle = if let Some(PreparedSlot { charge: slot_charge, objects, generations, free }) =
prepared.new_slot
{
self.objects.commit_growth(objects);
self.generations.commit_growth(generations);
self.free_list.commit_growth(free);
@@ -183,10 +208,15 @@ impl Heap {
self.generations.push(1).expect("reserved generation slot");
self.slots_charge.absorb(slot_charge);
HeapRef { index: idx as u32, generation: 1 }
} else {
let idx = self.free_list.pop().expect("reserved reusable handle");
debug_assert!(self.objects[idx].is_none());
self.objects[idx] = Some(obj);
HeapRef { index: idx as u32, generation: self.generations[idx] }
};
self.used_bytes.fetch_add(bytes, Ordering::Relaxed);
self.allocation_count.fetch_add(1, Ordering::Relaxed);
Ok(handle)
handle
}
#[cfg(test)]
@@ -523,14 +553,26 @@ impl Heap {
}
Ok(storage.type_id())
}
pub(crate) fn typed_array_len(
&self,
r: HeapRef,
registry: &Registry,
) -> Result<usize, ValueError> {
self.concrete_type(r, registry)?;
let storage = self.typed_object(r)?;
if registry.type_layout(storage.type_id()).unwrap().array.is_none() {
return Err(ValueError::Type);
}
Ok(storage.len())
}
pub(crate) fn allocate_typed_struct(
&mut self,
registry: Arc<Registry>,
type_id: TypeId,
) -> Result<HeapRef, ValueError> {
self.check_slot()?;
let prepared = self.prepare_insertion()?;
let storage = TypedStorage::new_struct(registry, type_id, &self.budget)?;
self.insert_typed(ObjectKind::Struct, 0, storage)
Ok(self.insert_typed(prepared, ObjectKind::Struct, 0, storage))
}
pub(crate) fn allocate_typed_array(
&mut self,
@@ -538,25 +580,29 @@ impl Heap {
type_id: TypeId,
count: u32,
) -> Result<HeapRef, ValueError> {
self.check_slot()?;
let prepared = self.prepare_insertion()?;
let storage = TypedStorage::new_array(registry, type_id, count, &self.budget)?;
self.insert_typed(ObjectKind::Array, count, storage)
Ok(self.insert_typed(prepared, ObjectKind::Array, count, storage))
}
fn insert_typed(
&mut self,
prepared: PreparedInsertion,
kind: ObjectKind,
count: u32,
storage: TypedStorage,
) -> Result<HeapRef, ValueError> {
Ok(self.insert_object(StoredObject {
header: ObjectHeader::new(kind, count),
payload: BudgetVec::new(&self.budget, Q::GuestBytes),
array_elems: None,
closure_env: None,
coroutine: None,
typed: Some(storage),
dynamic_box: None,
})?)
) -> HeapRef {
self.commit_insertion(
prepared,
StoredObject {
header: ObjectHeader::new(kind, count),
payload: BudgetVec::new(&self.budget, Q::GuestBytes),
array_elems: None,
closure_env: None,
coroutine: None,
typed: Some(storage),
dynamic_box: None,
},
)
}
pub(crate) fn load_typed(
&self,
+2
View File
@@ -1,3 +1,5 @@
#[cfg(test)]
extern crate self as prometeu_vm;
mod builtins;
mod call_frame;
mod input_intrinsics;
@@ -410,6 +410,34 @@ fn transfer(
working[base + offset] = Fact::Carrier(abi_mask(*abi));
}
}
Op::StructNew | Op::ArrayNew => {
group(
&mut working[base..],
registry,
TypeId(instruction.imm_u32().unwrap()),
(instruction.pc as u64) << 32,
budget,
)?;
}
Op::ArrayLen => {
budget.work(1)?;
working[base] = Fact::Carrier(I64);
}
Op::StructGet | Op::ArrayGet => {
budget.work(3)?;
let (id, field) = if instruction.opcode == Op::StructGet {
instruction.imm_u32x2().unwrap()
} else {
(instruction.imm_u32().unwrap(), 0)
};
let layout = registry.type_layout(TypeId(id)).unwrap();
let ty = if instruction.opcode == Op::StructGet {
layout.instance.as_ref().unwrap().fields[field as usize].type_id
} else {
layout.array.unwrap().element_type_id
};
group(&mut working[base..], registry, ty, (instruction.pc as u64) << 32, budget)?;
}
Op::DynPack => {
budget.work(1)?;
let ty = TypeId(instruction.imm_u32().unwrap());
@@ -651,6 +679,32 @@ fn check(
base += registry.type_layout(parameter.type_id).unwrap().storage.slots as usize;
}
}
Op::ArrayNew => require(working[end - 1], I64, 0, registry, budget)?,
Op::StructGet | Op::StructSet | Op::ArrayLen | Op::ArrayGet | Op::ArraySet => {
budget.work(3)?;
let (id, field) = if matches!(instruction.opcode, Op::StructGet | Op::StructSet) {
instruction.imm_u32x2().unwrap()
} else {
(instruction.imm_u32().unwrap(), 0)
};
let ty = TypeId(id);
let effect = instruction.registry_stack_effect(registry)?.unwrap();
let base = end - effect.pops as usize;
check_group(&working[base..base + 1], ty, registry, budget)?;
let array = matches!(instruction.opcode, Op::ArrayGet | Op::ArraySet);
if array {
require(working[base + 1], I64, 1, registry, budget)?;
}
if matches!(instruction.opcode, Op::StructSet | Op::ArraySet) {
let layout = registry.type_layout(ty).unwrap();
let value_ty = if array {
layout.array.unwrap().element_type_id
} else {
layout.instance.as_ref().unwrap().fields[field as usize].type_id
};
check_group(&working[base + 1 + usize::from(array)..], value_ty, registry, budget)?;
}
}
Op::DynPack => {
budget.work(1)?;
let ty = TypeId(instruction.imm_u32().unwrap());
@@ -58,6 +58,10 @@ impl RuntimeBudget {
fn state(&self) -> MutexGuard<'_, State> {
self.0.lock().unwrap_or_else(std::sync::PoisonError::into_inner)
}
#[cfg(test)]
pub(crate) fn test_lower_limit(&self, resource: RuntimeResource, limit: u64) {
self.state().limits.0[resource as usize] = limit;
}
pub fn used(&self, resource: RuntimeResource) -> u64 {
self.state().used[resource as usize]
}
@@ -342,3 +342,6 @@ pub(crate) mod tests;
#[cfg(test)]
mod ownership_tests;
#[cfg(test)]
pub(crate) use allocation::refuse_next_allocation;
@@ -6,6 +6,22 @@ use crate::resource_budget::{
use std::alloc::{Layout, alloc_zeroed, dealloc};
use std::ptr::NonNull;
#[cfg(test)]
thread_local! { static REFUSE_NEXT: std::cell::Cell<bool> = const { std::cell::Cell::new(false) }; }
#[cfg(test)]
pub(crate) struct RefusalGuard;
#[cfg(test)]
impl Drop for RefusalGuard {
fn drop(&mut self) {
REFUSE_NEXT.with(|flag| flag.set(false));
}
}
#[cfg(test)]
pub(crate) fn refuse_next_allocation() -> RefusalGuard {
REFUSE_NEXT.with(|flag| flag.set(true));
RefusalGuard
}
#[derive(Debug)]
pub(super) struct Allocation {
ptr: NonNull<u8>,
@@ -26,6 +42,14 @@ impl Allocation {
budget.failure(Q::GuestBytes, ResourceReason::SizeOverflow, size as u64)
})?;
let charge = budget.reserve(Q::GuestBytes, size as u64)?;
#[cfg(test)]
if REFUSE_NEXT.with(|flag| flag.replace(false)) {
return Err(budget.failure(
Q::GuestBytes,
ResourceReason::AllocationFailed,
size as u64,
));
}
let ptr = if size == 0 {
// Never dereferenced/deallocated; no element exists in an empty payload.
NonNull::dangling()
@@ -1,4 +1,7 @@
use crate::resource_budget::BudgetVec;
mod collections;
#[cfg(test)]
mod collections_tests;
mod dynamic;
mod gc;
mod loader;
@@ -1410,6 +1413,20 @@ impl VirtualMachine {
let (source, target) = instr.imm_u32x2().unwrap();
return self.execute_reference(opcode, source, target, start_pc as u32);
}
OpCode::StructNew
| OpCode::StructGet
| OpCode::StructSet
| OpCode::ArrayNew
| OpCode::ArrayLen
| OpCode::ArrayGet
| OpCode::ArraySet => {
let (ty, field) = if matches!(opcode, OpCode::StructGet | OpCode::StructSet) {
instr.imm_u32x2().unwrap()
} else {
(instr.imm_u32().unwrap(), 0)
};
return self.execute_collection(opcode, ty, field, start_pc as u32);
}
OpCode::FrameSync => {
// Marks the logical end of a frame: consume cycles and signal to the driver
self.cycles += OpCode::FrameSync.cycles();
@@ -0,0 +1,194 @@
//! Whole-group collection attempts: charge, validate, reserve, prepare, commit.
use super::*;
use crate::resource_budget::ResourceReason;
use crate::value_contract::{self, ValueError, ValueGroup};
use prometeu_bytecode::registry::TypeId;
impl VirtualMachine {
pub(super) fn execute_collection(
&mut self,
opcode: OpCode,
id: u32,
field: u32,
pc: u32,
) -> Result<(), LogicalFrameEndingReason> {
let image = self.validated_image.clone().ok_or_else(|| {
self.trap(
prometeu_bytecode::TRAP_ILLEGAL_INSTRUCTION,
opcode as u16,
"Instruction requires a validated Program Registry".into(),
pc,
)
})?;
let registry = image.registry();
let ty = TypeId(id);
let layout = registry.type_layout(ty).expect("validated collection type");
let is_array = layout.array.is_some();
let value_ty = if let Some(array) = layout.array {
Some(array.element_type_id)
} else if matches!(opcode, OpCode::StructGet | OpCode::StructSet) {
Some(layout.instance.as_ref().unwrap().fields[field as usize].type_id)
} else {
None
};
let width =
value_ty.map(|t| registry.type_layout(t).unwrap().storage.slots as usize).unwrap_or(0);
let (consumed, produced) = match opcode {
OpCode::StructNew => (0, 1),
OpCode::ArrayNew | OpCode::ArrayLen => (1, 1),
OpCode::StructGet => (1, width),
OpCode::ArrayGet => (2, width),
OpCode::StructSet => (1 + width, 0),
OpCode::ArraySet => (2 + width, 0),
_ => unreachable!(),
};
let available = self.temporary_slots() >= consumed;
let base = self.operand_stack.len().saturating_sub(consumed);
let length = if opcode == OpCode::ArrayNew && available {
match self.operand_stack[base] {
Value::Int64(n) => Some(n),
_ => None,
}
} else {
None
};
let work = match opcode {
OpCode::StructNew => layout.instance.as_ref().unwrap().initialization_slots,
OpCode::ArrayNew => length
.and_then(|n| u32::try_from(n).ok())
.map(|n| {
u64::from(n)
.checked_mul(width as u64)
.ok_or_else(|| self.collection_size_trap(opcode, pc, u64::MAX))
})
.transpose()?
.unwrap_or(0),
OpCode::StructGet | OpCode::ArrayGet | OpCode::StructSet | OpCode::ArraySet => {
width as u64
}
_ => 0,
};
let cost = opcode
.cycles()
.checked_add(work)
.ok_or_else(|| self.collection_size_trap(opcode, pc, u64::MAX))?;
self.cycles += cost;
if !available {
return Err(self.trap(
TRAP_STACK_UNDERFLOW,
opcode as u16,
"Incomplete collection operands".into(),
pc,
));
}
let mut receiver = None;
let mut index = field as usize;
if !matches!(opcode, OpCode::StructNew | OpCode::ArrayNew) {
let r = match self.operand_stack[base] {
Value::Null => return Err(self.value_trap(ValueError::NullReference, opcode, pc)),
Value::HeapRef(r) => r,
_ => return Err(self.value_trap(ValueError::Type, opcode, pc)),
};
let actual =
self.heap.concrete_type(r, registry).map_err(|e| self.value_trap(e, opcode, pc))?;
if actual != ty {
return Err(self.value_trap(ValueError::Type, opcode, pc));
}
receiver = Some(r);
if matches!(opcode, OpCode::ArrayGet | OpCode::ArraySet) {
let n = match self.operand_stack[base + 1] {
Value::Int64(n) => n,
_ => return Err(self.value_trap(ValueError::Type, opcode, pc)),
};
let len = self
.heap
.typed_array_len(r, registry)
.map_err(|e| self.value_trap(e, opcode, pc))?;
index = usize::try_from(n)
.ok()
.filter(|n| *n < len)
.ok_or_else(|| self.value_trap(ValueError::Bounds, opcode, pc))?;
}
}
let count = if opcode == OpCode::ArrayNew {
let n = length.ok_or_else(|| self.value_trap(ValueError::Type, opcode, pc))?;
if n < 0 {
return Err(self.value_trap(ValueError::Bounds, opcode, pc));
}
u32::try_from(n).map_err(|_| self.collection_size_trap(opcode, pc, n as u64))?
} else {
0
};
let set = matches!(opcode, OpCode::StructSet | OpCode::ArraySet);
let source = base + 1 + usize::from(is_array);
if set {
value_contract::validate(
registry,
&self.heap,
value_ty.unwrap(),
&self.operand_stack[source..],
)
.map_err(|e| self.value_trap(e, opcode, pc))?;
}
let growth = self
.operand_stack
.prepare_growth(produced.saturating_sub(consumed))
.map_err(|e| self.resource_trap(e, opcode, pc))?;
let result = match opcode {
OpCode::StructNew => {
let r = self
.heap
.allocate_typed_struct(registry.clone(), ty)
.map_err(|e| self.value_trap(e, opcode, pc))?;
ValueGroup::new(&[Value::HeapRef(r)])
}
OpCode::ArrayNew => {
let r = self
.heap
.allocate_typed_array(registry.clone(), ty, count)
.map_err(|e| self.value_trap(e, opcode, pc))?;
ValueGroup::new(&[Value::HeapRef(r)])
}
OpCode::ArrayLen => {
let len = self
.heap
.typed_array_len(receiver.unwrap(), registry)
.map_err(|e| self.value_trap(e, opcode, pc))?;
ValueGroup::new(&[Value::Int64(len as i64)])
}
OpCode::StructGet | OpCode::ArrayGet => self
.heap
.load_typed(registry, receiver.unwrap(), index)
.map_err(|e| self.value_trap(e, opcode, pc))?,
OpCode::StructSet | OpCode::ArraySet => {
self.heap
.store_typed(registry, receiver.unwrap(), index, &self.operand_stack[source..])
.map_err(|e| self.value_trap(e, opcode, pc))?;
ValueGroup::new(&[])
}
_ => unreachable!(),
};
self.operand_stack.commit_growth(growth);
self.operand_stack.truncate(base);
self.operand_stack
.extend_from_slice(result.as_slice())
.expect("result capacity reserved before publication");
Ok(())
}
fn collection_size_trap(
&self,
opcode: OpCode,
pc: u32,
requested: u64,
) -> LogicalFrameEndingReason {
self.resource_trap(
self.budget.failure(
RuntimeResource::GuestBytes,
ResourceReason::SizeOverflow,
requested,
),
opcode,
pc,
)
}
}
@@ -0,0 +1,508 @@
use super::*;
#[path = "../../tests/support/collections.rs"]
mod support;
use crate::value_contract::ValueError;
use prometeu_bytecode::assemble;
use support::Native;
fn vm(text: &str, limits: RuntimeLimits) -> VirtualMachine {
let mut vm =
VirtualMachine::from_image(support::load(&assemble(text).unwrap()).unwrap(), limits);
vm.prepare_boot_call().unwrap();
vm
}
fn attempt(
text: &str,
values: &[Value],
limits: RuntimeLimits,
cost: u64,
) -> (VirtualMachine, Result<(), LogicalFrameEndingReason>) {
let mut prefix = String::new();
for i in 0..values.len() {
prefix += &format!("GET_GLOBAL {i}\n");
}
let mut vm = vm(&(prefix + text + "\nHALT"), limits);
vm.globals.extend_from_slice(values).unwrap();
for _ in values {
vm.step(&mut Native, &mut HostContext::new(None)).unwrap();
}
let before = vm.cycles;
let result = vm.step(&mut Native, &mut HostContext::new(None));
assert_eq!(vm.cycles - before, cost);
(vm, result)
}
fn trap(result: Result<(), LogicalFrameEndingReason>, code: u32) {
match result.unwrap_err() {
LogicalFrameEndingReason::Trap(info) => assert_eq!(info.code, code),
other => panic!("{other:?}"),
}
}
#[test]
fn new_attempt_costs_budget_and_transactional_refusal() {
for (length, cost, fault) in [
(Value::Int64(-1), 8, TRAP_OOB),
(Value::Int32(10), 8, TRAP_TYPE),
(Value::Null, 8, TRAP_TYPE),
(Value::Int64(u32::MAX as i64 + 1), 8, TRAP_RESOURCE_LIMIT),
(Value::Int64(10), 28, TRAP_RESOURCE_LIMIT),
] {
let limits = RuntimeLimits::default()
.lowered(RuntimeResource::GuestBytes, size_of::<crate::heap::StoredObject>() as u64)
.unwrap();
let (vm, result) = attempt("ARRAY_NEW 12", std::slice::from_ref(&length), limits, cost);
trap(result, fault);
assert_eq!(vm.operand_stack.as_slice(), &[length]);
assert_eq!(
vm.budget.used(RuntimeResource::GuestBytes),
size_of::<crate::heap::StoredObject>() as u64
);
assert_eq!(vm.budget.used(RuntimeResource::HandleSlots), 1);
}
let mut vm = vm("PUSH_I64 10\nARRAY_NEW 12\nHALT", RuntimeLimits::default());
vm.step(&mut Native, &mut HostContext::new(None)).unwrap();
let pc = vm.pc;
let cycles = vm.cycles;
let r = vm.run_budget(0, &mut Native, &mut HostContext::new(None)).unwrap();
assert_eq!((r.cycles_used, r.steps_executed), (0, 0));
assert_eq!((vm.pc, vm.cycles), (pc, cycles));
let r = vm.run_budget(1, &mut Native, &mut HostContext::new(None)).unwrap();
assert_eq!(
(r.cycles_used, r.steps_executed, r.reason),
(28, 1, LogicalFrameEndingReason::BudgetExhausted)
);
let limits = RuntimeLimits::default()
.lowered(RuntimeResource::GuestBytes, size_of::<crate::heap::StoredObject>() as u64)
.unwrap();
let mut vm = vm_for_refusal(limits);
let r = vm.run_budget(1, &mut Native, &mut HostContext::new(None)).unwrap();
assert_eq!((r.cycles_used, r.steps_executed), (28, 0));
assert!(matches!(r.reason, LogicalFrameEndingReason::Trap(_)));
}
fn vm_for_refusal(limits: RuntimeLimits) -> VirtualMachine {
let mut v = vm("PUSH_I64 10\nARRAY_NEW 12\nHALT", limits);
v.step(&mut Native, &mut HostContext::new(None)).unwrap();
v
}
#[test]
fn underflow_is_charged_without_consuming_frame_storage() {
let mut vm = vm("GET_GLOBAL 0\nARRAY_NEW 12\nHALT", RuntimeLimits::default());
vm.pc = 6;
let before = vm.cycles;
trap(vm.step(&mut Native, &mut HostContext::new(None)), TRAP_STACK_UNDERFLOW);
assert_eq!(vm.cycles - before, 8);
assert!(vm.operand_stack.is_empty());
}
#[test]
fn receiver_then_index_then_group_checks_preserve_operands_and_storage() {
let mut vm = vm(
"GET_GLOBAL 0\nGET_GLOBAL 1\nGET_GLOBAL 2\nGET_GLOBAL 3\nGET_GLOBAL 4\nARRAY_SET 13\nHALT",
RuntimeLimits::default(),
);
let registry = vm.validated_image.as_ref().unwrap().registry().clone();
let r = vm
.heap
.allocate_typed_array(registry.clone(), prometeu_bytecode::registry::TypeId(13), 1)
.unwrap();
let old = [Value::Int64(1), Value::Int64(2), Value::Int64(3)];
vm.heap.store_typed(&registry, r, 0, &old).unwrap();
for (receiver, index, fault) in [
(Value::Null, Value::Int32(0), TRAP_NULL_REFERENCE),
(Value::HeapRef(r), Value::Int32(0), TRAP_TYPE),
(Value::HeapRef(r), Value::Int64(1), TRAP_OOB),
(Value::HeapRef(r), Value::Int64(0), TRAP_TYPE),
] {
vm.pc = 0;
vm.operand_stack.clear();
vm.globals.clear();
let inputs = [receiver, index, Value::Int64(7), Value::Int64(8), Value::Int64(-1)];
vm.globals.extend_from_slice(&inputs).unwrap();
for _ in 0..5 {
vm.step(&mut Native, &mut HostContext::new(None)).unwrap();
}
let before = vm.cycles;
trap(vm.step(&mut Native, &mut HostContext::new(None)), fault);
assert_eq!(vm.cycles - before, 7);
assert_eq!(vm.operand_stack.as_slice(), &inputs);
assert_eq!(vm.heap.load_typed(&registry, r, 0).unwrap().as_slice(), &old);
}
assert_eq!(vm.heap.concrete_type(r, &registry), Ok(prometeu_bytecode::registry::TypeId(13)));
let foreign = support::load(&assemble("HALT").unwrap()).unwrap();
assert_eq!(vm.heap.concrete_type(r, foreign.registry()), Err(ValueError::Type));
}
#[test]
fn default_groups_and_roundtrip_all_storage_types_keep_identity_and_owners() {
let mut vm = vm("STRUCT_NEW 9\nSET_GLOBAL 0\nHALT", RuntimeLimits::default());
vm.step(&mut Native, &mut HostContext::new(None)).unwrap();
let Value::HeapRef(r) = vm.operand_stack[0] else { panic!() };
let registry = vm.validated_image.as_ref().unwrap().registry().clone();
let defaults = [
vec![Value::Int32(0)],
vec![Value::Int64(0)],
vec![Value::Float(0.)],
vec![Value::Boolean(false)],
vec![Value::Null],
vec![Value::Float(0.), Value::Float(0.)],
vec![Value::Int64(0)],
vec![Value::Int64(0), Value::Int64(0), Value::Int64(0)],
vec![Value::Null, Value::Null],
vec![Value::Null],
vec![Value::Null, Value::Null],
vec![Value::Null],
];
for (field, group) in defaults.iter().enumerate() {
assert_eq!(vm.heap.load_typed(&registry, r, field).unwrap().as_slice(), group);
}
// Present Trait implementation zero and shared String/Dynamic/reference values.
let string = Value::String(std::sync::Arc::from("owned"));
for (field, group) in [
(4, vec![string.clone()]),
(8, vec![Value::Int64(4), string]),
(9, vec![Value::HeapRef(r)]),
(10, vec![Value::HeapRef(r), Value::Int64(0)]),
] {
vm.heap.store_typed(&registry, r, field, &group).unwrap();
assert_eq!(vm.heap.load_typed(&registry, r, field).unwrap().as_slice(), group);
}
}
#[test]
fn decoded_stores_and_reads_preserve_complete_native_and_reference_groups() {
for (field, group) in [
(0, vec![Value::Int32(7)]),
(1, vec![Value::Int64(8)]),
(2, vec![Value::Float(1.)]),
(3, vec![Value::Boolean(true)]),
(4, vec![Value::String(std::sync::Arc::from(""))]),
(5, vec![Value::Float(1.), Value::Float(2.)]),
(6, vec![Value::Int64(u32::MAX.into())]),
(7, vec![Value::Int64(1), Value::Int64(2), Value::Int64(3)]),
(8, vec![Value::Null, Value::Null]),
(9, vec![Value::Null]),
(10, vec![Value::Null, Value::Null]),
(11, vec![Value::Null]),
] {
let mut text = "STRUCT_NEW 9\nSET_GLOBAL 0\nGET_GLOBAL 0\n".to_string();
for i in 0..group.len() {
text += &format!("GET_GLOBAL {}\n", i + 1);
}
text += &format!(
"STRUCT_SET type=9, field={field}\nGET_GLOBAL 0\nSTRUCT_GET type=9, field={field}\nHALT"
);
let mut v = vm(&text, RuntimeLimits::default());
v.globals.push(Value::Null).unwrap();
v.globals.extend_from_slice(&group).unwrap();
assert_eq!(
v.run_budget(10_000, &mut Native, &mut HostContext::new(None)).unwrap().reason,
LogicalFrameEndingReason::Halted
);
assert_eq!(v.operand_stack.as_slice(), group);
}
}
#[test]
fn provisional_allocation_and_handle_refusals_publish_nothing() {
for quota in [
RuntimeResource::HandleSlots,
RuntimeResource::AuxiliaryBytes,
RuntimeResource::TemporaryBytes,
] {
let mut v = vm("PUSH_I64 10\nARRAY_NEW 12\nHALT", RuntimeLimits::default());
v.step(&mut Native, &mut HostContext::new(None)).unwrap();
// Test-only accounting state: lower the resource ceiling to current usage
// after boot, without changing any production constructor/check.
let current = v.budget.used(quota);
v.budget.test_lower_limit(quota, current);
let guest = v.budget.used(RuntimeResource::GuestBytes);
let live = v.heap.len();
let allocations = v.heap.allocation_count();
let before = v.cycles;
trap(v.step(&mut Native, &mut HostContext::new(None)), TRAP_RESOURCE_LIMIT);
assert_eq!(v.cycles - before, 28);
assert_eq!(v.heap.len(), live);
assert_eq!(v.heap.allocation_count(), allocations);
assert_eq!(v.operand_stack.as_slice(), &[Value::Int64(10)]);
assert_eq!(v.budget.used(RuntimeResource::GuestBytes), guest);
}
let mut v = vm("PUSH_I64 10\nARRAY_NEW 12\nHALT", RuntimeLimits::default());
v.step(&mut Native, &mut HostContext::new(None)).unwrap();
let guest = v.budget.used(RuntimeResource::GuestBytes);
let guard = crate::typed_storage::refuse_next_allocation();
let failure = v.step(&mut Native, &mut HostContext::new(None));
drop(guard);
let LogicalFrameEndingReason::Trap(t) = failure.unwrap_err() else { panic!() };
assert_eq!(
t.resource.unwrap().reason,
crate::resource_budget::ResourceReason::AllocationFailed
);
assert_eq!(v.budget.used(RuntimeResource::GuestBytes), guest);
assert_eq!(v.operand_stack.as_slice(), &[Value::Int64(10)]);
assert_eq!(v.heap.len(), 1);
}
#[test]
fn rooted_native_owners_boxes_traits_and_cycles_survive_then_reclaim_at_real_safepoints() {
let text = "STRUCT_NEW 9\nSET_GLOBAL 0\nGET_GLOBAL 0\nSTRUCT_GET type=9, field=4\nSET_GLOBAL 9\nPUSH_I64 1\nARRAY_NEW 17\nSET_GLOBAL 1\nGET_GLOBAL 1\nPUSH_I64 0\nGET_GLOBAL 0\nARRAY_SET 17\nGET_GLOBAL 0\nGET_GLOBAL 0\nSTRUCT_SET type=9, field=9\nGET_GLOBAL 0\nGET_GLOBAL 0\nREF_TO_TRAIT source=9, target=10\nSTRUCT_SET type=9, field=10\nGET_GLOBAL 0\nPUSH_F64 f64:0x3ff0000000000000\nPUSH_F64 f64:0x4000000000000000\nDYN_PACK 5\nSTRUCT_SET type=9, field=8\nGET_GLOBAL 0\nGET_GLOBAL 2\nSTRUCT_SET type=9, field=4\nPUSH_I64 1\nARRAY_NEW 14\nSET_GLOBAL 3\nGET_GLOBAL 3\nPUSH_I64 0\nGET_GLOBAL 2\nARRAY_SET 14\nPUSH_I64 1\nARRAY_NEW 15\nSET_GLOBAL 4\nGET_GLOBAL 4\nPUSH_I64 0\nGET_GLOBAL 2\nDYN_PACK 4\nARRAY_SET 15\nFRAME_SYNC\nGET_GLOBAL 9\nSET_GLOBAL 2\nGET_GLOBAL 9\nSET_GLOBAL 3\nFRAME_SYNC\nGET_GLOBAL 9\nSET_GLOBAL 0\nGET_GLOBAL 9\nSET_GLOBAL 1\nGET_GLOBAL 9\nSET_GLOBAL 4\nSTRUCT_NEW 19\nPOP_N 1\nFRAME_SYNC\nHALT";
let mut v = vm(text, RuntimeLimits::default());
v.gc_alloc_threshold = 1;
v.globals.resize(3, Value::Null).unwrap();
v.push(Value::String(std::sync::Arc::from("one content"))).unwrap();
let string = v.pop().unwrap();
v.globals[2] = string;
assert_eq!(
v.run_budget(10_000, &mut Native, &mut HostContext::new(None)).unwrap().reason,
LogicalFrameEndingReason::FrameSync
);
let Value::HeapRef(node) = v.globals[0] else { panic!() };
let registry = v.validated_image.as_ref().unwrap().registry().clone();
assert_eq!(
v.heap.load_typed(&registry, node, 10).unwrap().as_slice(),
&[Value::HeapRef(node), Value::Int64(0)]
);
assert_eq!(v.budget.used(RuntimeResource::StringBytes), 11);
assert_eq!(v.budget.used(RuntimeResource::StringAllocations), 1);
assert_eq!(
v.run_budget(10_000, &mut Native, &mut HostContext::new(None)).unwrap().reason,
LogicalFrameEndingReason::FrameSync
);
assert!(v.heap.is_valid(node));
assert_eq!(v.budget.used(RuntimeResource::StringAllocations), 1);
assert_eq!(
v.run_budget(10_000, &mut Native, &mut HostContext::new(None)).unwrap().reason,
LogicalFrameEndingReason::FrameSync
);
assert!(!v.heap.is_valid(node));
assert_eq!(v.heap.len(), 1);
assert_eq!(v.budget.used(RuntimeResource::StringBytes), 0);
assert_eq!(v.budget.used(RuntimeResource::StringAllocations), 0);
assert_eq!(v.heap.concrete_type(node, &registry), Err(ValueError::InvalidHandle));
}
#[test]
fn exact_struct_weights_and_empty_construction_charge_once() {
for (ty, cost) in [(19, 8), (21, 13)] {
let (v, result) = attempt(&format!("STRUCT_NEW {ty}"), &[], RuntimeLimits::default(), cost);
result.unwrap();
assert!(matches!(v.operand_stack[0], Value::HeapRef(_)));
}
let (v, result) = attempt("ARRAY_NEW 12", &[Value::Int64(0)], RuntimeLimits::default(), 8);
result.unwrap();
assert!(matches!(v.operand_stack[0], Value::HeapRef(_)));
}
#[test]
fn arrays_of_every_builtin_and_reference_view_default_and_roundtrip_by_decoded_ops() {
for (ty, default, value) in [
(11, vec![Value::Int32(0)], vec![Value::Int32(7)]),
(22, vec![Value::Int64(0)], vec![Value::Int64(8)]),
(23, vec![Value::Float(0.)], vec![Value::Float(1.)]),
(24, vec![Value::Boolean(false)], vec![Value::Boolean(true)]),
(14, vec![Value::Null], vec![Value::String(std::sync::Arc::from("shared"))]),
(12, vec![Value::Float(0.), Value::Float(0.)], vec![Value::Float(1.), Value::Float(2.)]),
(25, vec![Value::Int64(0)], vec![Value::Int64(42)]),
(
13,
vec![Value::Int64(0), Value::Int64(0), Value::Int64(0)],
vec![Value::Int64(1), Value::Int64(2), Value::Int64(3)],
),
(15, vec![Value::Null, Value::Null], vec![Value::Int64(4), Value::Null]),
(16, vec![Value::Null, Value::Null], vec![Value::Null, Value::Null]),
(17, vec![Value::Null], vec![Value::Null]),
(18, vec![Value::Null], vec![Value::Null]),
] {
let mut text = format!(
"PUSH_I64 1\nARRAY_NEW {ty}\nSET_GLOBAL 0\nGET_GLOBAL 0\nPUSH_I64 0\nARRAY_GET {ty}\nPOP_N {}\nGET_GLOBAL 0\nPUSH_I64 0\n",
value.len()
);
for i in 0..value.len() {
text += &format!("GET_GLOBAL {}\n", i + 1);
}
text += &format!("ARRAY_SET {ty}\nGET_GLOBAL 0\nPUSH_I64 0\nARRAY_GET {ty}\nHALT");
let mut v = vm(&text, RuntimeLimits::default());
v.globals.push(Value::Null).unwrap();
v.globals.extend_from_slice(&value).unwrap();
for _ in 0..6 {
v.step(&mut Native, &mut HostContext::new(None)).unwrap();
}
assert_eq!(v.operand_stack.as_slice(), default);
assert_eq!(
v.run_budget(10_000, &mut Native, &mut HostContext::new(None)).unwrap().reason,
LogicalFrameEndingReason::Halted
);
assert_eq!(v.operand_stack.as_slice(), value);
}
}
#[test]
fn invalid_stale_wrong_nominal_and_foreign_registry_receivers_are_charged_and_preserved() {
let mut v = vm("GET_GLOBAL 0\nARRAY_LEN 11\nHALT", RuntimeLimits::default());
let registry = v.validated_image.as_ref().unwrap().registry().clone();
let wrong = v
.heap
.allocate_typed_struct(registry.clone(), prometeu_bytecode::registry::TypeId(19))
.unwrap();
let foreign = support::load(&assemble("HALT").unwrap()).unwrap();
let foreign_ref = v
.heap
.allocate_typed_array(
foreign.registry().clone(),
prometeu_bytecode::registry::TypeId(11),
0,
)
.unwrap();
for (value, code) in [
(Value::Int32(0), TRAP_TYPE),
(Value::Null, TRAP_NULL_REFERENCE),
(Value::HeapRef(HeapRef { index: u32::MAX, generation: 1 }), TRAP_INVALID_HANDLE),
(
Value::HeapRef(HeapRef { index: wrong.index, generation: wrong.generation + 1 }),
TRAP_INVALID_HANDLE,
),
(Value::HeapRef(wrong), TRAP_TYPE),
(Value::HeapRef(foreign_ref), TRAP_TYPE),
] {
v.pc = 0;
v.operand_stack.clear();
v.globals.clear();
v.globals.push(value.clone()).unwrap();
v.step(&mut Native, &mut HostContext::new(None)).unwrap();
let before = v.cycles;
trap(v.step(&mut Native, &mut HostContext::new(None)), code);
assert_eq!(v.cycles - before, 3);
assert_eq!(v.operand_stack.as_slice(), &[value]);
}
}
#[test]
fn malformed_trait_and_dynamic_stores_reject_the_whole_group() {
for (ty, group) in [
(16, vec![Value::Null, Value::Int64(0)]),
(16, vec![Value::Int32(0), Value::Null]),
(15, vec![Value::Null, Value::Int32(0)]),
(15, vec![Value::Int64(5), Value::Int32(0)]),
(15, vec![Value::Int64(999), Value::Null]),
] {
let text = format!(
"PUSH_I64 1\nARRAY_NEW {ty}\nSET_GLOBAL 0\nGET_GLOBAL 0\nPUSH_I64 0\nGET_GLOBAL 1\nGET_GLOBAL 2\nARRAY_SET {ty}\nHALT"
);
let mut v = vm(&text, RuntimeLimits::default());
v.globals.push(Value::Null).unwrap();
v.globals.extend_from_slice(&group).unwrap();
for _ in 0..7 {
v.step(&mut Native, &mut HostContext::new(None)).unwrap();
}
let sources = v.operand_stack.as_slice().to_vec();
let before = v.cycles;
trap(v.step(&mut Native, &mut HostContext::new(None)), TRAP_TYPE);
assert_eq!(v.cycles - before, 6);
assert_eq!(v.operand_stack.as_slice(), sources);
let Value::HeapRef(r) = v.globals[0] else { panic!() };
let registry = v.validated_image.as_ref().unwrap().registry();
assert_eq!(
v.heap.load_typed(registry, r, 0).unwrap().as_slice(),
&[Value::Null, Value::Null]
);
}
}
#[test]
fn legacy_verifier_rejects_every_collection_even_when_unreachable() {
for text in [
"STRUCT_NEW 9",
"STRUCT_GET type=9, field=0",
"STRUCT_SET type=9, field=0",
"ARRAY_NEW 11",
"ARRAY_LEN 11",
"ARRAY_GET 11",
"ARRAY_SET 11",
] {
let code = assemble(&format!("HALT\n{text}")).unwrap();
let f =
prometeu_bytecode::FunctionMeta { code_len: code.len() as u32, ..Default::default() };
assert!(matches!(
crate::verifier::Verifier::verify(&code, &[f]),
Err(crate::verifier::VerifierError::RegistryRequired { pc: 2, .. })
));
}
}
#[test]
fn invalid_string_overwrite_keeps_the_previous_native_owner() {
let text = "STRUCT_NEW 9\nSET_GLOBAL 0\nGET_GLOBAL 0\nGET_GLOBAL 1\nSTRUCT_SET type=9, field=4\nGET_GLOBAL 0\nGET_GLOBAL 2\nSTRUCT_SET type=9, field=4\nHALT";
let mut v = vm(text, RuntimeLimits::default());
let text: std::sync::Arc<str> = std::sync::Arc::from("old owner");
v.globals
.extend_from_slice(&[Value::Null, Value::String(text.clone()), Value::Int32(3)])
.unwrap();
for _ in 0..7 {
v.step(&mut Native, &mut HostContext::new(None)).unwrap();
}
let sources = v.operand_stack.as_slice().to_vec();
let before = v.cycles;
trap(v.step(&mut Native, &mut HostContext::new(None)), TRAP_TYPE);
assert_eq!(v.cycles - before, 5);
assert_eq!(v.operand_stack.as_slice(), sources);
let Value::HeapRef(r) = v.globals[0] else { panic!() };
let registry = v.validated_image.as_ref().unwrap().registry();
let group = v.heap.load_typed(registry, r, 4).unwrap();
let Value::String(stored) = &group.as_slice()[0] else { panic!() };
assert!(std::sync::Arc::ptr_eq(stored, &text));
}
#[test]
fn pixel_get_cost_bounds_and_result_reservation_failures_preserve_sources() {
for lowered in
[None, Some(RuntimeResource::AuxiliaryBytes), Some(RuntimeResource::TemporaryBytes)]
{
let mut v = vm("GET_GLOBAL 0\nGET_GLOBAL 1\nARRAY_GET 13\nHALT", RuntimeLimits::default());
let registry = v.validated_image.as_ref().unwrap().registry().clone();
let r = v
.heap
.allocate_typed_array(registry.clone(), prometeu_bytecode::registry::TypeId(13), 1)
.unwrap();
v.globals
.extend_from_slice(&[
Value::HeapRef(r),
Value::Int64(if lowered.is_none() { 1 } else { 0 }),
])
.unwrap();
for _ in 0..2 {
v.step(&mut Native, &mut HostContext::new(None)).unwrap();
}
if let Some(q) = lowered {
v.budget.test_lower_limit(q, v.budget.used(q));
}
let sources = v.operand_stack.as_slice().to_vec();
let before = v.cycles;
trap(
v.step(&mut Native, &mut HostContext::new(None)),
if lowered.is_none() { TRAP_OOB } else { TRAP_RESOURCE_LIMIT },
);
assert_eq!(v.cycles - before, 6);
assert_eq!(v.operand_stack.as_slice(), sources);
assert_eq!(
v.heap.load_typed(&registry, r, 0).unwrap().as_slice(),
&[Value::Int64(0), Value::Int64(0), Value::Int64(0)]
);
}
}
#[test]
fn incomplete_set_group_does_not_consume_a_frame_local_and_still_charges_static_cost() {
let code = assemble(
"GET_GLOBAL 0\nGET_GLOBAL 1\nGET_GLOBAL 2\nGET_GLOBAL 3\nGET_GLOBAL 4\nARRAY_SET 13\nHALT",
)
.unwrap();
let mut declarations = support::declarations(code.len());
declarations.functions[0].local_slots = 1;
let image = crate::ValidatedProgramImage::load(
&support::bytes_with(&code, declarations),
&mut prometeu_bytecode::load_limits::LoadBudget::new(Default::default()),
NONE,
)
.unwrap();
let mut v = VirtualMachine::from_image(image, RuntimeLimits::default());
v.prepare_boot_call().unwrap();
v.operand_stack[0] = Value::Int64(123);
v.pc = 30;
v.operand_stack
.extend_from_slice(&[Value::Null, Value::Int64(0), Value::Int64(1), Value::Int64(2)])
.unwrap();
let before = v.cycles;
let sources = v.operand_stack.as_slice().to_vec();
trap(v.step(&mut Native, &mut HostContext::new(None)), TRAP_STACK_UNDERFLOW);
assert_eq!(v.cycles - before, 7);
assert_eq!(v.operand_stack.as_slice(), sources);
assert_eq!(v.operand_stack[0], Value::Int64(123));
}
@@ -0,0 +1,134 @@
#[path = "support/collections.rs"]
mod support;
use prometeu_bytecode::{Value, assemble};
use prometeu_hal::HostContext;
use prometeu_vm::{LogicalFrameEndingReason, VirtualMachine, resource_budget::RuntimeLimits};
use support::{Native, load};
fn run(code: &[u8]) -> Vec<Value> {
let mut vm = VirtualMachine::from_image(load(code).unwrap(), RuntimeLimits::default());
vm.prepare_boot_call().unwrap();
let r = vm.run_budget(10_000, &mut Native, &mut HostContext::new(None)).unwrap();
assert_eq!(r.reason, LogicalFrameEndingReason::Halted);
vm.operand_stack_top(32).to_vec()
}
#[test]
fn independent_bytes_execute_default_array_and_len_on_sealed_image() {
let code = [0x14, 0, 2, 0, 0, 0, 0, 0, 0, 0, 0xa3, 0, 11, 0, 0, 0, 0xa4, 0, 11, 0, 0, 0, 1, 0];
assert_eq!(run(&code), [Value::Int64(2)]);
}
#[test]
fn guest_aliases_mutate_same_instance_and_groups_roundtrip_without_boxing() {
let code=assemble("STRUCT_NEW 9\nSET_GLOBAL 0\nGET_GLOBAL 0\nPUSH_F64 f64:0x3ff8000000000000\nPUSH_F64 f64:0x4004000000000000\nSTRUCT_SET type=9, field=5\nGET_GLOBAL 0\nSTRUCT_GET type=9, field=5\nPUSH_I64 2\nARRAY_NEW 17\nSET_GLOBAL 1\nGET_GLOBAL 1\nPUSH_I64 0\nGET_GLOBAL 0\nARRAY_SET 17\nGET_GLOBAL 1\nPUSH_I64 0\nARRAY_GET 17\nPUSH_I32 42\nSTRUCT_SET type=9, field=0\nGET_GLOBAL 0\nSTRUCT_GET type=9, field=0\nGET_GLOBAL 1\nARRAY_LEN 17\nHALT").unwrap();
assert_eq!(
run(&code),
[Value::Int64(2), Value::Int32(42), Value::Float(2.5), Value::Float(1.5)]
);
}
#[test]
fn every_builtin_group_can_be_stored_and_loaded_by_decoded_struct_operations() {
for (field, push, expected) in [
(0, "PUSH_I32 23", vec![Value::Int32(23)]),
(1, "PUSH_I64 23", vec![Value::Int64(23)]),
(2, "PUSH_F64 f64:0x4004000000000000", vec![Value::Float(2.5)]),
(3, "PUSH_BOOL 1", vec![Value::Boolean(true)]),
(4, "GET_GLOBAL 0\nSTRUCT_GET type=9, field=4", vec![Value::Null]),
(
5,
"PUSH_F64 f64:0x3ff8000000000000\nPUSH_F64 f64:0x4004000000000000",
vec![Value::Float(2.5), Value::Float(1.5)],
),
(6, "PUSH_I64 4294967295", vec![Value::Int64(4294967295)]),
(
7,
"PUSH_I64 1\nPUSH_I64 2\nPUSH_I64 3",
vec![Value::Int64(3), Value::Int64(2), Value::Int64(1)],
),
(8, "PUSH_F64 f64:0x3ff8000000000000\nPUSH_F64 f64:0x4004000000000000\nDYN_PACK 5", vec![]),
] {
let code=assemble(&format!("STRUCT_NEW 9\nSET_GLOBAL 0\nGET_GLOBAL 0\n{push}\nSTRUCT_SET type=9, field={field}\nGET_GLOBAL 0\nSTRUCT_GET type=9, field={field}\n{}HALT",if field==8 {"DYN_UNPACK 5\n"}else{""})).unwrap();
let actual = run(&code);
assert_eq!(
actual,
if field == 8 { vec![Value::Float(2.5), Value::Float(1.5)] } else { expected }
);
}
}
#[test]
fn verifier_rejects_proven_types_metadata_and_unreachable_invalid_fields() {
for text in [
"ARRAY_NEW 0\nHALT",
"STRUCT_NEW 11\nHALT",
"HALT\nSTRUCT_GET type=9, field=12",
"PUSH_I32 1\nARRAY_NEW 11\nHALT",
"STRUCT_NEW 19\nSTRUCT_GET type=9, field=0\nHALT",
"STRUCT_NEW 9\nPUSH_BOOL 1\nSTRUCT_SET type=9, field=0\nHALT",
"PUSH_I64 1\nARRAY_NEW 13\nPUSH_F64 f64:0x3ff0000000000000\nARRAY_GET 13\nHALT",
] {
assert!(load(&assemble(text).unwrap()).is_err(), "{text}");
}
}
#[test]
fn empty_instances_have_identity_and_nested_array_references_preserve_aliases() {
let code=assemble("STRUCT_NEW 19\nSTRUCT_NEW 19\nEQ\nPUSH_I64 0\nARRAY_NEW 11\nARRAY_LEN 11\nPUSH_I64 1\nARRAY_NEW 18\nSET_GLOBAL 0\nGET_GLOBAL 0\nPUSH_I64 0\nPUSH_I64 2\nARRAY_NEW 11\nARRAY_SET 18\nGET_GLOBAL 0\nPUSH_I64 0\nARRAY_GET 18\nARRAY_LEN 11\nHALT").unwrap();
assert_eq!(run(&code), [Value::Int64(2), Value::Int64(0), Value::Boolean(false)]);
}
#[test]
fn converged_unknown_receiver_join_keeps_runtime_checks_and_valid_branch_executes() {
let text = "PUSH_BOOL 1\nJMP_IF_FALSE 31\nPUSH_I64 1\nARRAY_NEW 11\nJMP 47\nPUSH_I64 1\nARRAY_NEW 14\nARRAY_LEN 11\nHALT";
assert_eq!(run(&assemble(text).unwrap()), [Value::Int64(1)]);
let mut vm = VirtualMachine::from_image(
load(&assemble(&text.replace("PUSH_BOOL 1", "PUSH_BOOL 0")).unwrap()).unwrap(),
RuntimeLimits::default(),
);
vm.prepare_boot_call().unwrap();
let r = vm.run_budget(10_000, &mut Native, &mut HostContext::new(None)).unwrap();
let LogicalFrameEndingReason::Trap(t) = r.reason else { panic!() };
assert_eq!(t.code, prometeu_bytecode::TRAP_TYPE);
assert_eq!(t.opcode, 0xa4);
assert_eq!(t.pc, 47);
}
#[test]
fn verifier_rejects_group_tearing_jumps_into_immediates_and_unequal_height_joins() {
for text in [
"STRUCT_NEW 9\nSTRUCT_GET type=9, field=5\nPOP_N 1\nPUSH_I32 1\nSTRUCT_NEW 9\nSWAP\nSTRUCT_SET type=9, field=5\nHALT",
"JMP 8\nSTRUCT_NEW 9\nHALT",
"PUSH_BOOL 1\nJMP_IF_FALSE 21\nSTRUCT_NEW 9\nJMP 21\nHALT",
] {
assert!(load(&assemble(text).unwrap()).is_err(), "{text}");
}
}
#[test]
fn collection_load_limits_and_analysis_refusals_keep_context_and_refund_scratch() {
use prometeu_bytecode::load_limits::{LoadBudget, LoadCode, LoadLimits, LoadResource};
use prometeu_hal::syscalls::caps::NONE;
use prometeu_vm::{ValidatedProgramImage, VmInitError};
let code = assemble("PUSH_I64 1\nARRAY_NEW 13\nPUSH_I64 0\nARRAY_GET 13\nHALT").unwrap();
let mut d = support::declarations(code.len());
d.functions[0].max_stack_slots = 2;
assert!(load(&code).is_ok());
let bytes = support::bytes_with(&code, d);
let e = ValidatedProgramImage::load(&bytes, &mut LoadBudget::new(Default::default()), NONE)
.unwrap_err();
let VmInitError::RegistryLoadFailed(e) = e else { panic!() };
assert_eq!(e.code, LoadCode::InvalidCode);
assert_eq!(e.function, Some(0));
assert_eq!(e.pc, Some(26));
let bytes = support::bytes(&code);
for limits in [
LoadLimits { work: 1, ..Default::default() },
LoadLimits { temporary_bytes: 1, ..Default::default() },
LoadLimits { registry_bytes: 1, ..Default::default() },
] {
let mut budget = LoadBudget::new(limits);
let VmInitError::RegistryLoadFailed(e) =
ValidatedProgramImage::load(&bytes, &mut budget, NONE).unwrap_err()
else {
panic!()
};
assert_eq!(e.code, LoadCode::ResourceLimit);
assert_eq!(budget.used(LoadResource::TemporaryBytes), 0);
assert_eq!(budget.used(LoadResource::RegistryBytes), 0);
}
}
@@ -0,0 +1,99 @@
#![allow(dead_code)]
use prometeu_bytecode::load_limits::LoadBudget;
use prometeu_bytecode::registry::*;
use prometeu_bytecode::registry_codec::PbxModule;
use prometeu_hal::{HostContext, HostReturn, NativeInterface};
use prometeu_vm::ValidatedProgramImage;
use std::sync::Arc;
pub struct Native;
impl NativeInterface for Native {
fn syscall(
&mut self,
_: u32,
_: &[prometeu_bytecode::Value],
_: &mut HostReturn,
_: &mut HostContext,
) -> Result<(), prometeu_hal::vm_fault::VmFault> {
panic!("no native call expected")
}
}
pub fn declarations(code_len: usize) -> RegistryDeclarations {
let mut types: Vec<_> = [
BuiltinId::INT32,
BuiltinId::INT64,
BuiltinId::FLOAT,
BuiltinId::BOOL,
BuiltinId::STRING,
BuiltinId::VEC2,
BuiltinId::COLOR,
BuiltinId::PIXEL,
BuiltinId::DYNAMIC,
]
.into_iter()
.map(|id| TypeDecl { name: None, kind: TypeKind::Builtin(id) })
.collect();
let field = |id| NamedType { type_id: TypeId(id), name: None };
types.extend([
TypeDecl {
name: Some("Node".into()),
kind: TypeKind::Struct((0..=9).chain([10, 11]).map(field).collect()),
},
TypeDecl { name: None, kind: TypeKind::Trait(vec![]) },
TypeDecl { name: None, kind: TypeKind::Array(TypeId(0)) },
TypeDecl { name: None, kind: TypeKind::Array(TypeId(5)) },
TypeDecl { name: None, kind: TypeKind::Array(TypeId(7)) },
TypeDecl { name: None, kind: TypeKind::Array(TypeId(4)) },
TypeDecl { name: None, kind: TypeKind::Array(TypeId(8)) },
TypeDecl { name: None, kind: TypeKind::Array(TypeId(10)) },
TypeDecl { name: None, kind: TypeKind::Array(TypeId(9)) },
TypeDecl { name: None, kind: TypeKind::Array(TypeId(11)) },
TypeDecl { name: None, kind: TypeKind::Struct(vec![]) },
TypeDecl { name: None, kind: TypeKind::Struct(vec![]) },
]);
types.push(TypeDecl {
name: None,
kind: TypeKind::Struct([0, 5, 10].into_iter().map(field).collect()),
});
for id in [1, 2, 3, 6] {
types.push(TypeDecl { name: None, kind: TypeKind::Array(TypeId(id)) });
}
RegistryDeclarations {
types,
functions: vec![FunctionDecl {
code_len: code_len as u32,
local_slots: 0,
max_stack_slots: 32,
..Default::default()
}],
implementations: vec![ImplementationDecl {
owner: TypeId(9),
trait_id: TypeId(10),
methods: vec![],
}],
}
}
pub fn bytes(code: &[u8]) -> Vec<u8> {
bytes_with(code, declarations(code.len()))
}
pub fn bytes_with(code: &[u8], declarations: RegistryDeclarations) -> Vec<u8> {
let registry =
Registry::resolve(declarations, code.len(), &mut LoadBudget::new(Default::default()))
.unwrap();
PbxModule {
registry: &registry,
code,
constants: &[],
debug: None,
exports: &[],
syscalls: &[],
}
.serialize(&mut LoadBudget::new(Default::default()))
.unwrap()
}
pub fn load(code: &[u8]) -> Result<Arc<ValidatedProgramImage>, prometeu_vm::VmInitError> {
ValidatedProgramImage::load(
&bytes(code),
&mut LoadBudget::new(Default::default()),
prometeu_hal::syscalls::caps::NONE,
)
}
@@ -0,0 +1,33 @@
#[path = "../../../console/prometeu-vm/tests/support/collections.rs"]
mod support;
use prometeu_bytecode::{assemble, Value};
use prometeu_hal::HostContext;
use prometeu_vm::{resource_budget::RuntimeLimits, LogicalFrameEndingReason, VirtualMachine};
#[test]
fn serialized_guest_cycle_and_dynamic_box_cross_real_safepoints_then_reclaim() {
let mut text="STRUCT_NEW 9\nSET_GLOBAL 0\nGET_GLOBAL 0\nSTRUCT_GET type=9, field=4\nSET_GLOBAL 9\nGET_GLOBAL 0\nGET_GLOBAL 0\nSTRUCT_SET type=9, field=9\nGET_GLOBAL 0\nGET_GLOBAL 0\nREF_TO_TRAIT source=9, target=10\nSTRUCT_SET type=9, field=10\nGET_GLOBAL 0\nPUSH_F64 f64:0x3ff0000000000000\nPUSH_F64 f64:0x4000000000000000\nDYN_PACK 5\nSTRUCT_SET type=9, field=8\nPUSH_I64 1\nARRAY_NEW 17\nSET_GLOBAL 1\nGET_GLOBAL 1\nPUSH_I64 0\nGET_GLOBAL 0\nARRAY_SET 17\nGET_GLOBAL 9\nSET_GLOBAL 0\n".to_string();
// Meet the actual default GC trigger using guest instructions, without a
// private heap mutation or a production GC policy change.
for _ in 0..1024 {
text += "STRUCT_NEW 19\nPOP_N 1\n";
}
text+="FRAME_SYNC\nGET_GLOBAL 1\nPUSH_I64 0\nARRAY_GET 17\nSTRUCT_GET type=9, field=8\nDYN_UNPACK 5\nPOP_N 2\nGET_GLOBAL 9\nSET_GLOBAL 1\n";
for _ in 0..1024 {
text += "STRUCT_NEW 19\nPOP_N 1\n";
}
text += "FRAME_SYNC\nHALT";
let mut vm = VirtualMachine::from_image(
support::load(&assemble(&text).unwrap()).unwrap(),
RuntimeLimits::default(),
);
vm.prepare_boot_call().unwrap();
let r = vm.run_budget(100_000, &mut support::Native, &mut HostContext::new(None)).unwrap();
assert_eq!(r.reason, LogicalFrameEndingReason::FrameSync);
assert_eq!(vm.heap().len(), 4); // main coroutine, Array, Node, Dynamic box
vm.step(&mut support::Native, &mut HostContext::new(None)).unwrap();
let Value::HeapRef(array) = vm.operand_stack_top(1)[0] else { panic!() };
let r = vm.run_budget(100_000, &mut support::Native, &mut HostContext::new(None)).unwrap();
assert_eq!(r.reason, LogicalFrameEndingReason::FrameSync);
assert_eq!(vm.heap().len(), 1);
assert!(!vm.heap().is_valid(array));
}
@@ -448,12 +448,15 @@ fn assert_same_state(left: &HostState, right: &HostState) {
}
fn temp_cart(name: &str) -> String {
// Clock resolution does not guarantee distinct names for parallel tests.
static NEXT_FIXTURE: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
let sequence = NEXT_FIXTURE.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
let dir = std::env::temp_dir().join(format!(
"prometeu-headless-{name}-{}-{}",
"prometeu-headless-{name}-{}-{}-{sequence}",
std::process::id(),
std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).unwrap().as_nanos()
));
fs::create_dir_all(&dir).expect("temp cartridge dir");
fs::create_dir(&dir).expect("unique temp cartridge dir");
dir.to_string_lossy().into_owned()
}
@@ -0,0 +1,63 @@
---
id: LSN-0060
ticket: game-state-collections-and-objects
title: Collection Attempts Preserve Groups and Charge Work Before Publication
created: 2026-10-08
tags: [vm, bytecode, collections, ownership, budget]
---
## Context
DEC-0046, accepted from AGD-0054, established seven typed Array/Struct guest operations. PLN-0177 implemented them through the delivered Registry and sealed PBX v1 image/session boundary. This lesson explains the published result; the normative sources are the [collection ISA](../../../docs/specs/runtime/02-vm-instruction-set.md#typed-collection-instructions), [memory contract](../../../docs/specs/runtime/03-memory-stack-heap-and-allocation.md#typed-array-and-struct-storage) and [attempt charging](../../../docs/specs/runtime/01-time-model-and-cycles.md#collection-attempt-charging). The [producer handoff](../../../docs/vm-arch/collection-producer-handoff.md) supplies emission and integration oracles.
The Registry foundation already separated semantic identity, execution carriers and stored layouts. Collection instructions make that separation observable to guest code. The independent delivery leaves production initialize and v0 example migration with their existing integration owner; validated local programs demonstrate the new capabilities without claiming consumer activation.
## Key Decisions and Published Patterns
### A Runtime Capability Is Smaller Than an SDK Library
Fixed-length Array access and mutable Struct fields are enough to support language-defined containers. List growth, Set equality/hashing and Map collision policies belong to SDKs. Keeping those policies outside the runtime allows languages to share storage primitives while choosing their own abstractions. Array<Struct> stores references: copying an element preserves identity and aliasing instead of cloning an object graph.
A vec2 is two execution slots, but an Array reference is one regardless of its length. NEW initialization work uses those semantic widths; native size/alignment still determines memory reservations. The Struct width sum is cached once in bounded Registry resolution. Conflating these quantities would make virtual cycles depend on host representation or recursively charge referenced instances.
### Attempted Work and Published State Are Separate Accounts
A failed operation can preserve all guest-visible values while still consuming cycles. For ten vec2 elements, the attempt costs 8 + 10*2 = 28 even if memory quota refuses it. Invalid length carriers cannot supply a valid N and take the base path. This distinction makes refusal observable as charged work rather than a free repeated probe.
The instruction obtains validated metadata, detects incomplete temporary operands, charges once, validates ordered inputs and then reserves/prepares its result. NEW stages operand growth, object header and handle-table candidates before typed initialization. Complete publication has no subsequent fallible reservation. On failure, provisional owners drop; source operands and old storage remain live. Existing auxiliary capacity semantics remain distinct from rollback of unpublished candidates.
This is also why a parameterless opcode cost API is insufficient for collection accounting. It supplies a base; execution resolves the full attempt cost and returns outside the fixed-cost dispatch epilogue. Otherwise the VM could silently undercharge or charge twice.
### Complete Groups Keep Native and Guest Ownership Together
GET and SET handle complete Registry groups. Trait receiver and ImplementationId move together; implementation zero remains valid. Dynamic retains its TypeId/payload relation and shares existing immutable boxes. String copies retain Arc identity and accounting provenance, with null distinct from an empty String. A rejected overwrite does not release the prior native owner.
Receiver validation precedes index carrier/bounds, and SET group validation follows both. This order provides a stable first fault while avoiding mutation or early source consumption. The finite verifier rejects proven type/group conflicts after convergence, but an Unknown join still reaches runtime checks. Static proof does not remove generation, null or bounds checking.
### An Indivisible Instruction Can Overshoot Its Slice
The scheduler's cycle slice is an admission boundary between instructions. A positive balance admits a complete collection operation. At ten-vec2 ARRAY_NEW, run_budget(1) reports 28 cycles and one successful step before BudgetExhausted when continuation exists. A quota-refused attempt reports Trap and the same cycles, with zero successful target steps. Zero budget executes nothing.
Collection allocation does not create an implicit safepoint to satisfy quota. Roots and native owners remain live through the instruction and are reconciled at established FRAME_SYNC boundaries. A guest-created cycle can survive while an Array root reaches it, then become reclaimable when roots disappear. Weak String ledgers release content charges after the last native owner disappears and reconciliation runs; quota counters do not promise immediate RSS reduction.
## Evidence and Practical Limits
The bytecode suite checks independent literal encodings, every truncated prefix, textual roundtrips, exact effects and cached weights. Sealed serialized-v1 conformance executes default initialization, builtin groups, nested arrays, aliases and conservative Unknown joins. Decoded VM tests cover exact costs, malformed groups, stale/foreign/nominal receivers, a real frame temporary floor, resource refusals and test-only allocation failure. The layer graph crosses actual FRAME_SYNC using the unchanged default GC trigger, retaining a Node/Array/Trait/Dynamic box and reclaiming them after roots are removed. Native ownership evidence retains one String allocation shared through field/array/direct Dynamic until final-owner reconciliation.
Final validation ran formatting, workspace Clippy, workspace tests, optimized collection suites, LLVM coverage and all eight unchanged domain gates. The workspace and coverage runs each passed 925 tests with 9 explicitly ignored tests. Optimized collection suites passed 15 VM tests and 8 sealed conformance tests. Ignored cases are three measurement probes, five localhost debugger tests and one packaged-installation smoke; none is counted as executed. The code baseline was `8732f4b0f4a944d234037687c5cfb5be22b756a8`, followed by this working-tree delivery.
A repeated workspace run exposed an intermittent preexisting headless fixture boot failure. Its isolated test and full host suite passed. The fixture used clock-derived temporary directory names; adding a process-local atomic sequence and exclusive directory creation removes that collision risk without changing host or runtime behavior. The final fresh workspace and coverage runs include this fixture correction.
These results establish operation-specific behavior on the validated v1 path. They do not establish external compiler/SDK activation, production migration, prolonged cross-host stability, representative-game headroom or native allocator/RSS guarantees. Dummy Boy and Stress still emit v0; the optional palette smoke is explicitly excluded and handed off with its prerequisite and frame/allocation/root oracles.
## Pitfalls
- Treating the Array TypeId as its element TypeId, or accepting a physically similar nominal type, breaks the semantic contract.
- Splitting a Trait/Dynamic group, popping a receiver before checking the full attempt, or dropping an old String before validation creates partial state changes.
- Charging only on success, using only the opcode base, or rejecting an instruction because its full cycles exceed the remaining slice changes the accepted time model.
- Triggering eager GC inside NEW to fit quota creates a new scheduling/root boundary.
- Using raw heap helper tests alone misses decode, bounded verification, frame floors, cost epilogues and the sealed image boundary.
## Takeaways
Treat a collection instruction as a charged ownership transaction. Resolve widths from immutable metadata, keep groups whole, validate before dependent mutation/allocation and publish only complete results. Use serialized guest programs and real safepoints to prove those boundaries, then let language SDKs compose container policies from the runtime capabilities.
+10 -1
View File
@@ -3,7 +3,7 @@
Domain: machine timing and cycles
Function: normative
Didactic companion: [`../learn/mental-model-time-and-cycles.md`](../runtime/learn/mental-model-time-and-cycles.md)
Didactic companion: [`../learn/mental-model-time-and-cycles.md`](../../../discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0017-mental-model-time-and-cycles.md)
## 1 Scope
@@ -158,3 +158,12 @@ enemy.updateAI(): 1,012 cycles
## Program Registry v1 integration
The [Dynamic/reference instruction table](02c-program-registry-and-pbx-v1.md#dynamic-and-reference-instructions) specifies fixed costs of 8/4/3/4/4/5/4 cycles for opcodes 0x0090–0x0096. Each decoded attempt charges once, including a trap. Input retains the existing one-cycle INTRINSIC rule. Load work quotas are deterministic analysis units, not execution cycles or a wall-clock timeout.
## Collection Attempt Charging
The [collection ISA table](02-vm-instruction-set.md#typed-collection-instructions) defines complete costs. Metadata widths determine costs independently of native sizeof, allocator, timing, optimizer and GC. Each decoded collection attempt is charged exactly once before validation/refusal. Fixed costs apply even to underflow, invalid receiver, bounds and rejected value groups. ARRAY_NEW charges 8 + N*w(E) whenever an available exact Int64 length is in 0..u32::MAX, including quota/allocation refusal; absent, wrong-carrier, negative or above-u32 length charges eight. Rejected loads execute and charge no guest instruction.
Examples: empty Struct/Array costs eight; a Struct containing Int32, vec2 and Trait costs thirteen; ten vec2 elements cost twenty-eight even on quota refusal; pixel GET costs six including bounds failure; pixel SET costs seven including group rejection; LEN costs three including receiver failure. Charged cycles are never refunded by rollback.
Budget admission remains between instructions. Zero executes nothing. A positive remaining budget admits the entire next instruction, which may overshoot; continuation then returns BudgetExhausted before the following instruction. Thus ARRAY_NEW of ten vec2 under run_budget(1) consumes twenty-eight cycles. Trap takes priority on refusal, with the same cycle delta and no successful target step. steps_executed counts only successful steps; cycles_used includes failed attempts. Collection operations add no implicit frame sync, tick, GC or coroutine switch, no extra length cap and no cycle pre-admission rule.
@@ -131,3 +131,26 @@ The PVM is:
## Program Registry v1 integration
[Program Registry and PBX v1](02c-program-registry-and-pbx-v1.md) defines typed immediate domains, opcodes 0x0090–0x0096, complete multi-slot groups and conservative type-flow verification. Unknown facts require runtime validation and do not alone reject an otherwise valid join. Opcode bytes remain u16; TypeId immediates are u32 little-endian.
## Typed Collection Instructions
These instructions require a validated Program Registry. Opcodes are u16 little-endian; TypeId and field immediates are u32 little-endian. T is the receiver descriptor, F its declared field type, E its Array element type. Stack order below is bottom to top; groups retain Registry component order.
| Instruction | Code | Immediate | Bytes | Stack effect | Full attempt cycles |
| --- | --- | --- | ---: | --- | --- |
| STRUCT_NEW T | 0x00A0 | T | 6 | [] → ref<T> | 8 + sum(w(fields)) |
| STRUCT_GET type=T, field=f | 0x00A1 | T, f | 10 | ref<T> → slots(F) | 3 + w(F) |
| STRUCT_SET type=T, field=f | 0x00A2 | T, f | 10 | ref<T>, slots(F) → [] | 4 + w(F) |
| ARRAY_NEW T | 0x00A3 | T | 6 | length:Int64 → ref<T> | 8 + N*w(E), valid N; otherwise 8 |
| ARRAY_LEN T | 0x00A4 | T | 6 | ref<T> → length:Int64 | 3 |
| ARRAY_GET T | 0x00A5 | T | 6 | ref<T>, index:Int64 → slots(E) | 3 + w(E) |
| ARRAY_SET T | 0x00A6 | T | 6 | ref<T>, index:Int64, slots(E) → [] | 4 + w(E) |
w is the resolved execution-slot width: scalar, String, color and concrete references use one; vec2, Trait and Dynamic use two; pixel uses three. Reference width never traverses referenced instances. The Struct construction sum is cached during bounded Registry resolution, with no PBX schema change. `OpCode::cycles()` supplies only the base component for these instructions.
STRUCT operations require a Struct descriptor; ARRAY operations require an Array descriptor, never its element TypeId or BuiltinId. Fields are immediate owner-local indices in declaration order. Every operation may trap; none branches, terminates or constitutes a safepoint. All instructions, including unreachable ones, undergo bounded structural verification and exact Registry height analysis. Finite type/group facts converge before proven conflicts are rejected. Unknown facts retain runtime checking; locals have no permanent type.
After charging the attempt, incomplete temporary operands trap with STACK_UNDERFLOW. Instance operations check receiver carrier, absence, liveness/generation, category, Registry and exact TypeId first; array access then checks exact Int64 index and bounds; SET checks the complete value group last. There is no numeric, Trait or Dynamic coercion. Negative lengths or indices and indices at/above length trap with OOB (0x03); wrong carriers/types/groups trap with TYPE (0x04); absent receivers with NULL_REFERENCE (0x0E); invalid/dead/stale handles with INVALID_HANDLE (0x0F). Positive lengths above u32, checked size/cost overflow, resource quotas and recoverable allocation failures trap with RESOURCE_LIMIT (0x10), preserving resource reason/requested/limit. Static invalid TypeIds/categories/fields produce LOAD_INVALID_REFERENCE; proven stack/type conflicts produce LOAD_INVALID_CODE. Runtime TrapInfo preserves the attempted PC, opcode and available source span.
Publication and ownership follow [typed collection memory](03-memory-stack-heap-and-allocation.md); charging follows [time and cycles](01-time-model-and-cycles.md). See the [producer handoff](../../vm-arch/collection-producer-handoff.md) for independent byte oracles and construction examples. Production consumers must enter through the validated PBX v1 image boundary described in [Program Registry](02c-program-registry-and-pbx-v1.md).
@@ -132,8 +132,7 @@ The PVM uses a **mark-sweep collector**.
GC may run when:
- heap usage exceeds threshold;
- allocation pressure is high.
- the configured allocation threshold is reached at an established safepoint.
### Root set
@@ -167,8 +166,8 @@ Implications:
If allocation fails:
- the VM may trigger GC;
- if pressure remains unresolved, allocation may trap or fail according to the runtime contract.
- the attempt refuses with the applicable structured resource fault;
- it does not trigger reentrant GC or scheduling to satisfy its quota.
### Deallocation
@@ -204,3 +203,14 @@ Any violation results in a trap or rejected program image.
## Program Registry v1 integration
[Program Registry and PBX v1](02c-program-registry-and-pbx-v1.md#values-storage-and-initialization) specifies compact typed layouts, defaults, native String/Dynamic ownership and generational handles. Its [memory quotas](02c-program-registry-and-pbx-v1.md#memory-ownership-and-quotas) apply jointly before allocation. Registry metadata is immutable image-owned native memory, outside guest GC. Stack/local execution retains Value.
## Typed Array and Struct Storage
Registry-backed Arrays have fixed u32 lengths; Structs have mutable declared fields. Instances use resolved aligned offsets/strides and ownership maps. Builtins remain inline; Struct/Array fields and elements hold references. Copies preserve identity and aliasing, including nested arrays. List, Set and Map policies and implementations belong to each language SDK, composed from runtime Array capabilities.
NEW fully initializes all storage before publishing a handle: primitive/builtin canonical zeros, null String and concrete references, absent Trait [Null, Null], and untyped-null Dynamic [Null, Null]. Empty instances remain valid identities. No source constructor, callback or referenced instance/subarray is invoked or allocated implicitly. A frontend may root a default instance, store fields and call its own constructor.
GET copies a complete group and native owners without implicit boxing; SET validates the entire group before replacing it. String copies retain Arc ownership/provenance/accounting; null and empty String differ. Trait stores receiver and ImplementationId together (zero is a valid implementation); Dynamic preserves its complete pair and shares existing immutable boxes.
After validation, an attempt provisionally reserves net stack growth and construction resources, keeping source operands/roots alive. It prepares complete defaults/results before publication. Commit replaces the whole stored group or publishes the complete result, then consumes operands. No fallible reservation/allocation follows publication. Refusal preserves operands and prior storage/owners, publishes no partial handle, and releases provisional reservations/owners. Attempted work/cycles are retained; preexisting auxiliary capacities follow their existing growth contract. NEW never invokes reentrant GC or scheduling to satisfy quota. GC remains confined to established safepoints; live transitively rooted graphs and native owners survive them, while unrooted cycles become reclaimable.
+5 -1
View File
@@ -12,7 +12,7 @@ Machine boundary:
Authority rule:
- This document is normative for bytecode-level encoding and opcode surface.
- Runtime-wide invariants still live in [`../../ARCHITECTURE.md`](../../ARCHITECTURE.md).
- Runtime-wide invariants still live in [`ARCHITECTURE.md`](ARCHITECTURE.md).
- If a bytecode-level rule here conflicts with runtime architecture, the conflict must be resolved explicitly in both documents; neither should drift silently.
#### Encoding Rules
@@ -164,3 +164,7 @@ Static opcode metadata must represent Registry-dependent slot effects as unresol
never as zero. Resolve the semantic widths and immediate categories from the validated
Registry. Encoding/decoding support alone does not authorize execution: a slot-only
image/verifier must reject these instructions until typed-image integration is present.
#### Registry-backed collections
STRUCT_NEW (0x00A0), STRUCT_GET (0x00A1), STRUCT_SET (0x00A2), ARRAY_NEW (0x00A3), ARRAY_LEN (0x00A4), ARRAY_GET (0x00A5) and ARRAY_SET (0x00A6) require a validated Registry. Their exact immediates, full group effects, attempt costs and failure ordering are normative in the [typed collection instruction table](../specs/runtime/02-vm-instruction-set.md#typed-collection-instructions). These operations have no implicit conversion or safepoint. See the [producer handoff](collection-producer-handoff.md) for emission oracles.
@@ -0,0 +1,67 @@
# Typed collection producer and consumer handoff
The [collection ISA](../specs/runtime/02-vm-instruction-set.md#typed-collection-instructions), [memory contract](../specs/runtime/03-memory-stack-heap-and-allocation.md#typed-array-and-struct-storage) and [attempt charging](../specs/runtime/01-time-model-and-cycles.md#collection-attempt-charging) are normative. This interface has executable evidence through locally serialized PBX v1, `ValidatedProgramImage::load` and `VirtualMachine::from_image`. Production initialize and example generators still require coordinated v1 migration; no external SDK or frontend activation is implied.
## Encoding and complete groups
Opcodes are little-endian u16, followed by little-endian u32 immediates. TypeId is the receiver descriptor, independent of BuiltinId and element TypeId. Struct field indices are immediate, owner-local declaration positions. Array lengths/indices and LEN results use exact Int64 carriers; length must fit u32. References are exact nominal/invariant Registry types. There is no implicit conversion or array covariance.
| Operation | Code | Payload | Stack bottom → top |
| --- | --- | --- | --- |
| STRUCT_NEW | 0xA0 | TypeId | [] → ref |
| STRUCT_GET | 0xA1 | TypeId, field | ref → complete field group |
| STRUCT_SET | 0xA2 | TypeId, field | ref, complete field group → [] |
| ARRAY_NEW | 0xA3 | TypeId | Int64 length → ref |
| ARRAY_LEN | 0xA4 | TypeId | ref → Int64 length |
| ARRAY_GET | 0xA5 | TypeId | ref, Int64 index → complete element group |
| ARRAY_SET | 0xA6 | TypeId | ref, Int64 index, complete element group → [] |
The single-immediate forms are six bytes; field forms are ten. Width is one for scalar/String/color/concrete references, two for vec2/Trait/Dynamic, three for pixel. A Trait contains receiver then ImplementationId; Dynamic contains TypeId then payload. Preserve the whole group, including absent [Null, Null]. ImplementationId zero is valid. GET does not implicitly box; Dynamic copies share immutable boxes. NEW initializes canonical defaults without constructing referenced instances. Arrays have fixed lengths. SDKs implement List, Set and Map algorithms using these runtime capabilities.
Evaluate source expressions under the language's ordering rules into temporaries, then load receiver, index (if applicable) and components in Registry order. Runtime validation does not define source expression evaluation order: it checks receiver first, index carrier/bounds next, and a SET group last.
## Default-then-store construction oracle
With TypeId 0 = Int32 and TypeId 1 = Struct{value: TypeId 0}, the frontend can emit:
```text
STRUCT_NEW 1
SET_GLOBAL 0
GET_GLOBAL 0
PUSH_I32 42
STRUCT_SET type=1, field=0
GET_GLOBAL 0
STRUCT_GET type=1, field=0
HALT
```
The default value before the store is Int32 zero; the final value is Int32 42. A language-specific constructor can be called after rooting/storing under its own rules. NEW does not call it. Global/local slots used by this example remain the producer's responsibility.
With TypeId 11 = Array<Int32>, independent code bytes for length two followed by LEN and HALT are:
```text
14 00 02 00 00 00 00 00 00 00
A3 00 0B 00 00 00
A4 00 0B 00 00 00
01 00
```
The final stack is [Int64(2)]. Generic independent immediate oracles use T=0x01020304 and f=0x05060708: NEW is `A0 00 04 03 02 01`; GET is `A1 00 04 03 02 01 08 07 06 05`; SET starts `A2 00` with that same payload. Array NEW/LEN/GET/SET start `A3 00`, `A4 00`, `A5 00`, `A6 00`, each with `04 03 02 01`. Their descriptor tables must actually contain the referenced IDs for execution; these large-ID bytes are encoding oracles only.
## Costs, budgets and faults
Full costs are NEW 8 plus initialized execution slots, GET 3 plus value width, SET 4 plus value width, LEN 3. Struct sums are resolved/cached at load. ARRAY_NEW with valid Int64 N in 0..u32::MAX charges 8+N*w(E), including allocation refusal; unavailable/wrong/negative/above-u32 length charges eight. Every decoded attempt charges once, including traps. `OpCode::cycles()` is only the base for collection operations.
Ten vec2 elements cost 28; pixel GET/SET cost 6/7; empty construction costs 8. With positive remaining budget, the whole instruction executes, possibly overshooting. Budget zero does nothing. `run_budget(1)` at ARRAY_NEW ten vec2 with continuation returns BudgetExhausted, 28 cycles, one successful step; refused construction returns Trap, 28 cycles, zero successful target steps. No intra-instruction GC/tick/switch occurs.
Static bad IDs/categories/fields reject load with typed LOAD_INVALID_REFERENCE context; proven heights/types reject with LOAD_INVALID_CODE. Runtime faults retain attempted opcode/PC/span: incomplete temporary operands use STACK_UNDERFLOW; absence NULL_REFERENCE 0x0E; invalid/dead/stale handle INVALID_HANDLE 0x0F; wrong carrier/category/Registry/exact type/group TYPE 0x04; negative/out-of-range index or negative length OOB 0x03; above-u32 length, checked overflow and quotas/allocation refusal RESOURCE_LIMIT 0x10. Resource reason/requested/limit remain attached. Failed attempts preserve source operands and previous complete storage/owners, publish no partial handle and release provisional resources without refunding cycles.
## Consumer integration and evidence
Consumers must recognize all seven encodings, invoke Registry-derived effects in bounded structural/height/type verification and use validated-image execution. Metadata-free/legacy verification rejects these instructions with RegistryRequired. Reuse compact typed storage, default initialization, native ownership maps and generational handles; do not replace them with raw Value arrays or SDK container implementations.
Executable oracles live in bytecode `tests/registry_isa.rs`, VM `tests/collection_conformance.rs`, VM `virtual_machine/collections_tests.rs` and layer `tests/typed_collections.rs`. They cover independent bytes, default/alias/group operations, attempt costs and refusals, malformed/proven types, ownership and actual FRAME_SYNC graph reclamation. VM unit tests inject otherwise unreachable invalid state only inside tests. Optimized ownership/conformance runs complement debug evidence.
Dummy Boy and Stress currently emit PBX version 0. The optional Dummy Boy palette migration therefore belongs with production v1 integration: initialize one global-rooted Array<color> containing red/green/blue, mirror its frame counter in exact Int64 at the same initialization/increment points, select mirror modulo ARRAY_LEN using ARRAY_GET, and compare six logical frames. Preserve phase/drawing and verify one array allocation plus safepoint retention. This independent collection delivery does not migrate those producers or claim that smoke has run.
The published patterns and validation limits are explained in [Collection Attempts Preserve Groups and Charge Work Before Publication](../../discussion/lessons/DSC-0051-game-state-collections-and-objects/LSN-0060-collection-attempts-preserve-groups-and-charge-work-before-publication.md).
+2 -4
View File
@@ -8,7 +8,7 @@ The rationale and published mechanisms are explained in [Registry Boundaries and
The bounded writer/owned decoder, sealed `ValidatedProgramImage::load`, shared
session factory, typed direct-call/return boundaries, Dynamic/reference execution,
fixed input catalogue and string accounting have executable tests. The production
fixed input catalogue, typed collection operations and string accounting have executable tests. The production
`initialize` transition, removal of old unchecked entry points, all producer
migration and both regenerated runtime examples remain pending. Existing closure
receivers need a typed callable contract; none of the four accepted Registry
@@ -26,9 +26,7 @@ categories may be used as a provisional closure type.
| Conformance | Add migrated producer/example/callable evidence to this handoff and the existing conformance matrix. |
| Publication | Audit final coordinated publication, legacy removal, traceability and migrated workspace/examples. |
This integration reuses the delivered Registry foundation. Guest collection
operations, new strings/bytes/save APIs, coordinated stress and representative-game
headroom each require their own technical contract or validation workload.
This integration reuses the delivered Registry foundation and [typed collection producer interface](collection-producer-handoff.md). New strings/bytes/save APIs, coordinated stress and representative-game headroom each require their own technical contract or validation workload.
The external Studio handoff targets are the build-pipeline
`backend/bytecode/BytecodeModule.java` and `backend/irvm/IRVMIntrinsicRegistry.java`,