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
Generated
+5
View File
@@ -2054,6 +2054,7 @@ dependencies = [
"prometeu-hal",
"prometeu-host-desktop-winit",
"prometeu-host-headless",
"prometeu-test-support",
"serde_json",
]
@@ -2073,6 +2074,7 @@ dependencies = [
"prometeu-drivers",
"prometeu-hal",
"prometeu-system",
"prometeu-test-support",
"prometeu-vm",
]
@@ -2113,6 +2115,7 @@ dependencies = [
"prometeu-firmware",
"prometeu-hal",
"prometeu-system",
"prometeu-test-support",
"prometeu-vm",
"serde",
"serde_json",
@@ -2139,6 +2142,7 @@ dependencies = [
"prometeu-bytecode",
"prometeu-drivers",
"prometeu-hal",
"prometeu-test-support",
"prometeu-vm",
"serde_json",
]
@@ -2147,6 +2151,7 @@ dependencies = [
name = "prometeu-test-support"
version = "0.1.0"
dependencies = [
"prometeu-bytecode",
"rand",
]
@@ -58,7 +58,7 @@ fn parse_f64_bits(s: &str) -> Result<u64, AsmError> {
}
fn parse_keyvals(s: &str) -> Result<(&str, &str), AsmError> {
// Parses formats like: "fn=123, captures=2" or "fn=3, argc=1"
// Parses keyed u32 immediates such as "fn=123, type=2" or "type=3, method=1"
let mut parts = s.split(',');
let a = parts.next().ok_or_else(|| AsmError::MissingOperand(s.into()))?.trim();
let b = parts.next().ok_or_else(|| AsmError::MissingOperand(s.into()))?.trim();
@@ -102,6 +102,7 @@ pub fn assemble(src: &str) -> Result<Vec<u8>, AsmError> {
"NOP" => {
emit_u16(CoreOpCode::Nop as u16, &mut out);
}
"POP" => emit_u16(CoreOpCode::Pop as u16, &mut out),
"HALT" => {
emit_u16(CoreOpCode::Halt as u16, &mut out);
}
@@ -177,8 +178,8 @@ pub fn assemble(src: &str) -> Result<Vec<u8>, AsmError> {
"RET" => {
emit_u16(CoreOpCode::Ret as u16, &mut out);
}
"YIELD" => {
emit_u16(CoreOpCode::Yield as u16, &mut out);
"YIELD" | "SLEEP" | "SPAWN" => {
return Err(AsmError::InvalidOperand("retired coroutine instruction".into()))
}
"FRAME_SYNC" => {
emit_u16(CoreOpCode::FrameSync as u16, &mut out);
@@ -284,60 +285,35 @@ pub fn assemble(src: &str) -> Result<Vec<u8>, AsmError> {
emit_u16(CoreOpCode::Call as u16, &mut out);
emit_u32(parse_u32_any(ops)?, &mut out);
}
"CALL_CLOSURE" => {
"CALL_CLOSURE" | "GET_CAPTURE" => {
if ops.is_empty() {
return Err(AsmError::MissingOperand(line.into()));
}
let (k, v) =
ops.split_once('=').ok_or_else(|| AsmError::InvalidOperand(ops.into()))?;
if k.trim() != "argc" {
return Err(AsmError::InvalidOperand(ops.into()));
}
emit_u16(CoreOpCode::CallClosure as u16, &mut out);
emit_u32(parse_u32_any(v)?, &mut out);
}
"MAKE_CLOSURE" => {
if ops.is_empty() {
return Err(AsmError::MissingOperand(line.into()));
}
let (a, b) = parse_keyvals(ops)?;
// Accept either order but require exact key names
let (fn_id, captures) = if a.starts_with("fn=") && b.starts_with("captures=") {
parse_pair(a, "fn", b, "captures")?
} else if a.starts_with("captures=") && b.starts_with("fn=") {
let (cap, fid) = parse_pair(a, "captures", b, "fn")?;
(fid, cap)
let opcode = if mn == "CALL_CLOSURE" {
CoreOpCode::CallClosure
} else {
return Err(AsmError::InvalidOperand(ops.into()));
CoreOpCode::GetCapture
};
emit_u16(CoreOpCode::MakeClosure as u16, &mut out);
emit_u32(fn_id, &mut out);
emit_u32(captures, &mut out);
}
"SPAWN" => {
if ops.is_empty() {
return Err(AsmError::MissingOperand(line.into()));
}
let (a, b) = parse_keyvals(ops)?;
let (fn_id, argc) = if a.starts_with("fn=") && b.starts_with("argc=") {
parse_pair(a, "fn", b, "argc")?
} else if a.starts_with("argc=") && b.starts_with("fn=") {
let (ac, fid) = parse_pair(a, "argc", b, "fn")?;
(fid, ac)
} else {
return Err(AsmError::InvalidOperand(ops.into()));
};
emit_u16(CoreOpCode::Spawn as u16, &mut out);
emit_u32(fn_id, &mut out);
emit_u32(argc, &mut out);
}
"SLEEP" => {
if ops.is_empty() {
return Err(AsmError::MissingOperand(line.into()));
}
emit_u16(CoreOpCode::Sleep as u16, &mut out);
emit_u16(opcode as u16, &mut out);
emit_u32(parse_u32_any(ops)?, &mut out);
}
"MAKE_CLOSURE" | "CALL_TRAIT" => {
let (a, b) = parse_keyvals(ops)?;
let (key_a, key_b, opcode) = if mn == "MAKE_CLOSURE" {
("fn", "type", CoreOpCode::MakeClosure)
} else {
("type", "method", CoreOpCode::CallTrait)
};
let (first, second) = if a.starts_with(&format!("{}=", key_a)) {
parse_pair(a, key_a, b, key_b)?
} else {
let (second, first) = parse_pair(a, key_b, b, key_a)?;
(first, second)
};
emit_u16(opcode as u16, &mut out);
emit_u32(first, &mut out);
emit_u32(second, &mut out);
}
"HOSTCALL" => {
if ops.is_empty() {
return Err(AsmError::MissingOperand(line.into()));
@@ -10,9 +10,9 @@
//! - `MNEMONIC <imm>` for 1-operand instructions (decimal unless stated).
//! - Special operand formats:
//! - `PUSH_F64 f64:0xhhhhhhhhhhhhhhhh` — exact IEEE-754 bits in hex (little-endian to_bits()).
//! - `MAKE_CLOSURE fn=<u32>, captures=<u32>`
//! - `SPAWN fn=<u32>, argc=<u32>`
//! - `CALL_CLOSURE argc=<u32>`
//! - `MAKE_CLOSURE fn=<u32>, type=<u32>`
//! - Retired SPAWN/YIELD/SLEEP are identified for diagnostics only.
//! - `CALL_CLOSURE <FnTypeId>`
//! - `HOSTCALL <index>` is printed in decimal because it is a `SYSC` table index.
//! - `SYSCALL` is printed as `SYSCALL 0xhhhh` (numeric id in hex) to avoid cross-crate deps.
//!
@@ -60,6 +60,8 @@ fn format_operand(op: CoreOpCode, imm: &[u8]) -> String {
| CoreOpCode::SetLocal
| CoreOpCode::Call
| CoreOpCode::Sleep
| CoreOpCode::GetCapture
| CoreOpCode::CallClosure
| CoreOpCode::Hostcall
| CoreOpCode::DynPack
| CoreOpCode::DynUnpack
@@ -88,11 +90,14 @@ fn format_operand(op: CoreOpCode, imm: &[u8]) -> String {
CoreOpCode::MakeClosure => {
let fn_id = u32::from_le_bytes(imm[0..4].try_into().unwrap());
let cap = u32::from_le_bytes(imm[4..8].try_into().unwrap());
format!("fn={}, captures={}", fn_id, cap)
format!("fn={}, type={}", fn_id, cap)
}
CoreOpCode::CallClosure => {
let argc = u32::from_le_bytes(imm.try_into().unwrap());
format!("argc={}", argc)
CoreOpCode::CallTrait => {
let (ty, method) = (
u32::from_le_bytes(imm[..4].try_into().unwrap()),
u32::from_le_bytes(imm[4..].try_into().unwrap()),
);
format!("type={}, method={}", ty, method)
}
CoreOpCode::Spawn => {
let fn_id = u32::from_le_bytes(imm[0..4].try_into().unwrap());
@@ -1,98 +0,0 @@
//! Shared bytecode layout utilities, used by both compiler (emitter/linker)
//! and the VM (verifier/loader). This ensures a single source of truth for
//! how function ranges, instruction boundaries, and pc→function lookups are
//! interpreted post-link.
use crate::model::FunctionMeta;
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct FunctionLayout {
pub start: usize,
pub end: usize, // exclusive
}
/// Precompute canonical [start, end) ranges for all functions.
///
/// Contract:
/// - Ranges are computed by sorting functions by `code_offset` (stable),
/// then using the next function's start as the current end; the last
/// function ends at `code_len_total`.
/// - The returned vector is indexed by the original function indices.
pub fn compute_function_layouts(
functions: &[FunctionMeta],
code_len_total: usize,
) -> Vec<FunctionLayout> {
// Build index array and sort by start offset (stable to preserve relative order).
let mut idxs: Vec<usize> = (0..functions.len()).collect();
idxs.sort_by_key(|&i| functions[i].code_offset as usize);
// Optional guard: offsets should be strictly increasing (duplicates are suspicious).
for w in idxs.windows(2) {
if let [a, b] = *w {
let sa = functions[a].code_offset as usize;
let sb = functions[b].code_offset as usize;
debug_assert!(
sa < sb,
"Function code_offset must be strictly increasing: {} vs {} (indices {} and {})",
sa,
sb,
a,
b
);
}
}
let mut out = vec![FunctionLayout { start: 0, end: 0 }; functions.len()];
for (pos, &i) in idxs.iter().enumerate() {
let start = functions[i].code_offset as usize;
let end = if pos + 1 < idxs.len() {
functions[idxs[pos + 1]].code_offset as usize
} else {
code_len_total
};
out[i] = FunctionLayout { start, end };
}
out
}
#[cfg(test)]
mod tests {
use super::*;
fn build_funcs(offsets: &[usize], lens: Option<&[usize]>) -> Vec<FunctionMeta> {
let mut v = Vec::new();
for (i, off) in offsets.iter().copied().enumerate() {
let len_u32 = lens.and_then(|ls| ls.get(i).copied()).unwrap_or(0) as u32;
v.push(FunctionMeta {
code_offset: off as u32,
code_len: len_u32,
param_slots: 0,
local_slots: 0,
return_slots: 0,
max_stack_slots: 0,
});
}
v
}
#[test]
fn compute_function_layouts_end_is_next_start() {
// Synthetic functions with known offsets: 0, 10, 25; total_len = 40
let funcs = build_funcs(&[0, 10, 25], None);
let layouts = compute_function_layouts(&funcs, 40);
assert_eq!(layouts.len(), 3);
assert_eq!(layouts[0], FunctionLayout { start: 0, end: 10 });
assert_eq!(layouts[1], FunctionLayout { start: 10, end: 25 });
assert_eq!(layouts[2], FunctionLayout { start: 25, end: 40 });
for i in 0..3 {
let l = &layouts[i];
assert_eq!(
l.end - l.start,
(funcs.get(i + 1).map(|n| n.code_offset as usize).unwrap_or(40))
- (funcs[i].code_offset as usize)
);
}
}
}
+2 -3
View File
@@ -3,7 +3,6 @@ pub mod assembler;
mod decoder;
mod disassembler;
pub mod isa; // canonical ISA boundary (core and future profiles)
mod layout;
pub mod model;
mod opcode;
mod opcode_spec;
@@ -20,8 +19,8 @@ pub use abi::{
pub use assembler::{assemble, AsmError};
pub use decoder::{decode_next, DecodeError, DecodedInstr};
pub use disassembler::disassemble;
pub use layout::{compute_function_layouts, FunctionLayout};
pub use model::{BytecodeLoader, FunctionMeta, LoadError, SyscallDecl, PBX_MAGIC};
pub use model::{LoadError, SyscallDecl, PBX_MAGIC};
pub use program_image::ExecutionFunction;
pub use program_image::ProgramImage;
pub use resource_failure::{ResourceFailure, ResourceReason, RuntimeResource};
pub use value::{string_materialization_count, HeapRef, Value};
@@ -57,6 +57,12 @@ pub enum LoadReason {
TraitCategory,
DuplicateBuiltin,
DuplicateArray,
DuplicateFn,
StructuralTypeCycle,
CaptureIndex,
CaptureCount,
CapturedDirectCall,
RemovedOpcode,
ArrayCycle,
DuplicateImplementation,
MethodCount,
@@ -1,7 +1,5 @@
use crate::abi::SourceSpan;
use crate::opcode::OpCode;
use serde::{Deserialize, Serialize};
use std::collections::HashSet;
/// An entry in the Constant Pool.
///
@@ -42,16 +40,6 @@ pub enum LoadError {
UnexpectedEof,
}
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
pub struct FunctionMeta {
pub code_offset: u32,
pub code_len: u32,
pub param_slots: u16,
pub local_slots: u16,
pub return_slots: u16,
pub max_stack_slots: u16,
}
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct DebugInfo {
pub pc_to_span: Vec<(u32, SourceSpan)>, // Sorted by PC
@@ -73,876 +61,4 @@ pub struct SyscallDecl {
pub ret_slots: u16,
}
const SECTION_KIND_CONST_POOL: u32 = 0;
const SECTION_KIND_FUNCTIONS: u32 = 1;
const SECTION_KIND_CODE: u32 = 2;
const SECTION_KIND_DEBUG: u32 = 3;
const SECTION_KIND_EXPORTS: u32 = 4;
const SECTION_KIND_SYSCALLS: u32 = 5;
pub const PBX_MAGIC: [u8; 4] = *b"PBX\0";
/// Represents the final serialized format of a PBX v0 module.
///
/// This structure is a pure data container for the PBX format. It does NOT
/// contain any linker-like logic (symbol resolution, patching, etc.).
/// All multi-module programs must be flattened and linked by the compiler
/// before being serialized into this format.
#[derive(Debug, Clone, PartialEq)]
pub struct BytecodeModule {
pub version: u16,
pub const_pool: Vec<ConstantPoolEntry>,
pub functions: Vec<FunctionMeta>,
pub code: Vec<u8>,
pub debug_info: Option<DebugInfo>,
pub exports: Vec<Export>,
pub syscalls: Vec<SyscallDecl>,
}
impl BytecodeModule {
pub fn serialize(&self) -> Vec<u8> {
let cp_data = self.serialize_const_pool();
let func_data = self.serialize_functions();
let code_data = self.code.clone();
let debug_data =
self.debug_info.as_ref().map(|di| self.serialize_debug(di)).unwrap_or_default();
let export_data = self.serialize_exports();
let syscall_data = self.serialize_syscalls();
let mut final_sections = Vec::new();
if !cp_data.is_empty() {
final_sections.push((SECTION_KIND_CONST_POOL, cp_data));
}
if !func_data.is_empty() {
final_sections.push((SECTION_KIND_FUNCTIONS, func_data));
}
if !code_data.is_empty() {
final_sections.push((SECTION_KIND_CODE, code_data));
}
if !debug_data.is_empty() {
final_sections.push((SECTION_KIND_DEBUG, debug_data));
}
if !export_data.is_empty() {
final_sections.push((SECTION_KIND_EXPORTS, export_data));
}
final_sections.push((SECTION_KIND_SYSCALLS, syscall_data));
let mut out = Vec::new();
// Magic "PBX\0"
out.extend_from_slice(&PBX_MAGIC);
// Version 0
out.extend_from_slice(&0u16.to_le_bytes());
// Endianness 0 (Little Endian), Reserved
out.extend_from_slice(&[0u8, 0u8]);
// section_count
out.extend_from_slice(&(final_sections.len() as u32).to_le_bytes());
// padding to 32 bytes
out.extend_from_slice(&[0u8; 20]);
let mut current_offset = 32 + (final_sections.len() as u32 * 12);
// Write section table
for (kind, data) in &final_sections {
let k: u32 = *kind;
out.extend_from_slice(&k.to_le_bytes());
out.extend_from_slice(&current_offset.to_le_bytes());
out.extend_from_slice(&(data.len() as u32).to_le_bytes());
current_offset += data.len() as u32;
}
// Write section data
for (_, data) in final_sections {
out.extend_from_slice(&data);
}
out
}
fn serialize_const_pool(&self) -> Vec<u8> {
if self.const_pool.is_empty() {
return Vec::new();
}
let mut data = Vec::new();
data.extend_from_slice(&(self.const_pool.len() as u32).to_le_bytes());
for entry in &self.const_pool {
match entry {
ConstantPoolEntry::Null => data.push(0),
ConstantPoolEntry::Int64(v) => {
data.push(1);
data.extend_from_slice(&v.to_le_bytes());
}
ConstantPoolEntry::Float64(v) => {
data.push(2);
data.extend_from_slice(&v.to_le_bytes());
}
ConstantPoolEntry::Boolean(v) => {
data.push(3);
data.push(if *v { 1 } else { 0 });
}
ConstantPoolEntry::String(v) => {
data.push(4);
let s_bytes = v.as_bytes();
data.extend_from_slice(&(s_bytes.len() as u32).to_le_bytes());
data.extend_from_slice(s_bytes);
}
ConstantPoolEntry::Int32(v) => {
data.push(5);
data.extend_from_slice(&v.to_le_bytes());
}
}
}
data
}
fn serialize_functions(&self) -> Vec<u8> {
if self.functions.is_empty() {
return Vec::new();
}
let mut data = Vec::new();
data.extend_from_slice(&(self.functions.len() as u32).to_le_bytes());
for f in &self.functions {
data.extend_from_slice(&f.code_offset.to_le_bytes());
data.extend_from_slice(&f.code_len.to_le_bytes());
data.extend_from_slice(&f.param_slots.to_le_bytes());
data.extend_from_slice(&f.local_slots.to_le_bytes());
data.extend_from_slice(&f.return_slots.to_le_bytes());
data.extend_from_slice(&f.max_stack_slots.to_le_bytes());
}
data
}
fn serialize_debug(&self, di: &DebugInfo) -> Vec<u8> {
let mut data = Vec::new();
data.extend_from_slice(&(di.pc_to_span.len() as u32).to_le_bytes());
for (pc, span) in &di.pc_to_span {
data.extend_from_slice(&pc.to_le_bytes());
data.extend_from_slice(&span.file_id.to_le_bytes());
data.extend_from_slice(&span.start.to_le_bytes());
data.extend_from_slice(&span.end.to_le_bytes());
}
data.extend_from_slice(&(di.function_names.len() as u32).to_le_bytes());
for (idx, name) in &di.function_names {
data.extend_from_slice(&idx.to_le_bytes());
let n_bytes = name.as_bytes();
data.extend_from_slice(&(n_bytes.len() as u32).to_le_bytes());
data.extend_from_slice(n_bytes);
}
data
}
fn serialize_exports(&self) -> Vec<u8> {
if self.exports.is_empty() {
return Vec::new();
}
let mut data = Vec::new();
data.extend_from_slice(&(self.exports.len() as u32).to_le_bytes());
for exp in &self.exports {
data.extend_from_slice(&exp.func_idx.to_le_bytes());
let s_bytes = exp.symbol.as_bytes();
data.extend_from_slice(&(s_bytes.len() as u32).to_le_bytes());
data.extend_from_slice(s_bytes);
}
data
}
fn serialize_syscalls(&self) -> Vec<u8> {
let mut data = Vec::new();
data.extend_from_slice(&(self.syscalls.len() as u32).to_le_bytes());
for syscall in &self.syscalls {
let module = syscall.module.as_bytes();
let name = syscall.name.as_bytes();
assert!(u16::try_from(module.len()).is_ok(), "SYSC module name exceeds u16 length");
assert!(u16::try_from(name.len()).is_ok(), "SYSC syscall name exceeds u16 length");
data.extend_from_slice(&(module.len() as u16).to_le_bytes());
data.extend_from_slice(module);
data.extend_from_slice(&(name.len() as u16).to_le_bytes());
data.extend_from_slice(name);
data.extend_from_slice(&syscall.version.to_le_bytes());
data.extend_from_slice(&syscall.arg_slots.to_le_bytes());
data.extend_from_slice(&syscall.ret_slots.to_le_bytes());
}
data
}
}
pub struct BytecodeLoader;
impl BytecodeLoader {
pub fn load(bytes: &[u8]) -> Result<BytecodeModule, LoadError> {
if bytes.len() < 32 {
return Err(LoadError::UnexpectedEof);
}
// Magic "PBX\0"
if bytes[0..4] != PBX_MAGIC[..] {
return Err(LoadError::InvalidMagic);
}
let version = u16::from_le_bytes([bytes[4], bytes[5]]);
if version != 0 {
return Err(LoadError::InvalidVersion);
}
let endianness = bytes[6];
if endianness != 0 {
// 0 = Little Endian
return Err(LoadError::InvalidEndianness);
}
let section_count = u32::from_le_bytes([bytes[8], bytes[9], bytes[10], bytes[11]]);
let mut sections = Vec::new();
let mut pos = 32;
for _ in 0..section_count {
if pos + 12 > bytes.len() {
return Err(LoadError::UnexpectedEof);
}
let kind =
u32::from_le_bytes([bytes[pos], bytes[pos + 1], bytes[pos + 2], bytes[pos + 3]]);
let offset = u32::from_le_bytes([
bytes[pos + 4],
bytes[pos + 5],
bytes[pos + 6],
bytes[pos + 7],
]);
let length = u32::from_le_bytes([
bytes[pos + 8],
bytes[pos + 9],
bytes[pos + 10],
bytes[pos + 11],
]);
// Basic bounds check
if (offset as usize) + (length as usize) > bytes.len() {
return Err(LoadError::SectionOutOfBounds);
}
sections.push((kind, offset, length));
pos += 12;
}
// Check for overlapping sections
for i in 0..sections.len() {
for j in i + 1..sections.len() {
let (_, o1, l1) = sections[i];
let (_, o2, l2) = sections[j];
if (o1 < o2 + l2) && (o2 < o1 + l1) {
return Err(LoadError::OverlappingSections);
}
}
}
let mut module = BytecodeModule {
version,
const_pool: Vec::new(),
functions: Vec::new(),
code: Vec::new(),
debug_info: None,
exports: Vec::new(),
syscalls: Vec::new(),
};
let mut has_syscalls = false;
for (kind, offset, length) in sections {
let section_data = &bytes[offset as usize..(offset + length) as usize];
match kind {
SECTION_KIND_CONST_POOL => {
// Const Pool
module.const_pool = parse_const_pool(section_data)?;
}
SECTION_KIND_FUNCTIONS => {
// Functions
module.functions = parse_functions(section_data)?;
}
SECTION_KIND_CODE => {
// Code
module.code = section_data.to_vec();
}
SECTION_KIND_DEBUG => {
// Debug Info
module.debug_info = Some(parse_debug_section(section_data)?);
}
SECTION_KIND_EXPORTS => {
// Exports
module.exports = parse_exports(section_data)?;
}
SECTION_KIND_SYSCALLS => {
module.syscalls = parse_syscalls(section_data)?;
has_syscalls = true;
}
_ => {} // Skip unknown or optional sections
}
}
if !has_syscalls {
return Err(LoadError::MissingSyscallSection);
}
// Additional validations
validate_module(&module)?;
Ok(module)
}
}
fn parse_const_pool(data: &[u8]) -> Result<Vec<ConstantPoolEntry>, LoadError> {
if data.is_empty() {
return Ok(Vec::new());
}
if data.len() < 4 {
return Err(LoadError::MalformedSection);
}
let count = u32::from_le_bytes([data[0], data[1], data[2], data[3]]) as usize;
let mut cp = Vec::with_capacity(count);
let mut pos = 4;
for _ in 0..count {
if pos >= data.len() {
return Err(LoadError::UnexpectedEof);
}
let tag = data[pos];
pos += 1;
match tag {
0 => cp.push(ConstantPoolEntry::Null),
1 => {
// Int64
if pos + 8 > data.len() {
return Err(LoadError::UnexpectedEof);
}
let val = i64::from_le_bytes(data[pos..pos + 8].try_into().unwrap());
cp.push(ConstantPoolEntry::Int64(val));
pos += 8;
}
2 => {
// Float64
if pos + 8 > data.len() {
return Err(LoadError::UnexpectedEof);
}
let val = f64::from_le_bytes(data[pos..pos + 8].try_into().unwrap());
cp.push(ConstantPoolEntry::Float64(val));
pos += 8;
}
3 => {
// Boolean
if pos >= data.len() {
return Err(LoadError::UnexpectedEof);
}
cp.push(ConstantPoolEntry::Boolean(data[pos] != 0));
pos += 1;
}
4 => {
// String
if pos + 4 > data.len() {
return Err(LoadError::UnexpectedEof);
}
let len = u32::from_le_bytes(data[pos..pos + 4].try_into().unwrap()) as usize;
pos += 4;
if pos + len > data.len() {
return Err(LoadError::UnexpectedEof);
}
let s = String::from_utf8_lossy(&data[pos..pos + len]).into_owned();
cp.push(ConstantPoolEntry::String(s));
pos += len;
}
5 => {
// Int32
if pos + 4 > data.len() {
return Err(LoadError::UnexpectedEof);
}
let val = i32::from_le_bytes(data[pos..pos + 4].try_into().unwrap());
cp.push(ConstantPoolEntry::Int32(val));
pos += 4;
}
_ => return Err(LoadError::MalformedSection),
}
}
Ok(cp)
}
fn parse_functions(data: &[u8]) -> Result<Vec<FunctionMeta>, LoadError> {
if data.is_empty() {
return Ok(Vec::new());
}
if data.len() < 4 {
return Err(LoadError::MalformedSection);
}
let count = u32::from_le_bytes([data[0], data[1], data[2], data[3]]) as usize;
let mut functions = Vec::with_capacity(count);
let mut pos = 4;
for _ in 0..count {
if pos + 16 > data.len() {
return Err(LoadError::UnexpectedEof);
}
let code_offset = u32::from_le_bytes(data[pos..pos + 4].try_into().unwrap());
let code_len = u32::from_le_bytes(data[pos + 4..pos + 8].try_into().unwrap());
let param_slots = u16::from_le_bytes(data[pos + 8..pos + 10].try_into().unwrap());
let local_slots = u16::from_le_bytes(data[pos + 10..pos + 12].try_into().unwrap());
let return_slots = u16::from_le_bytes(data[pos + 12..pos + 14].try_into().unwrap());
let max_stack_slots = u16::from_le_bytes(data[pos + 14..pos + 16].try_into().unwrap());
functions.push(FunctionMeta {
code_offset,
code_len,
param_slots,
local_slots,
return_slots,
max_stack_slots,
});
pos += 16;
}
Ok(functions)
}
fn parse_debug_section(data: &[u8]) -> Result<DebugInfo, LoadError> {
if data.is_empty() {
return Ok(DebugInfo::default());
}
if data.len() < 8 {
return Err(LoadError::MalformedSection);
}
let mut pos = 0;
// PC to Span table
let span_count = u32::from_le_bytes(data[pos..pos + 4].try_into().unwrap()) as usize;
pos += 4;
let mut pc_to_span = Vec::with_capacity(span_count);
for _ in 0..span_count {
if pos + 16 > data.len() {
return Err(LoadError::UnexpectedEof);
}
let pc = u32::from_le_bytes(data[pos..pos + 4].try_into().unwrap());
let file_id = u32::from_le_bytes(data[pos + 4..pos + 8].try_into().unwrap());
let start = u32::from_le_bytes(data[pos + 8..pos + 12].try_into().unwrap());
let end = u32::from_le_bytes(data[pos + 12..pos + 16].try_into().unwrap());
pc_to_span.push((pc, SourceSpan { file_id, start, end }));
pos += 16;
}
// Function names table
if pos + 4 > data.len() {
return Err(LoadError::UnexpectedEof);
}
let func_name_count = u32::from_le_bytes(data[pos..pos + 4].try_into().unwrap()) as usize;
pos += 4;
let mut function_names = Vec::with_capacity(func_name_count);
for _ in 0..func_name_count {
if pos + 8 > data.len() {
return Err(LoadError::UnexpectedEof);
}
let func_idx = u32::from_le_bytes(data[pos..pos + 4].try_into().unwrap());
let name_len = u32::from_le_bytes(data[pos + 4..pos + 8].try_into().unwrap()) as usize;
pos += 8;
if pos + name_len > data.len() {
return Err(LoadError::UnexpectedEof);
}
let name = String::from_utf8_lossy(&data[pos..pos + name_len]).into_owned();
function_names.push((func_idx, name));
pos += name_len;
}
Ok(DebugInfo { pc_to_span, function_names })
}
fn parse_exports(data: &[u8]) -> Result<Vec<Export>, LoadError> {
if data.is_empty() {
return Ok(Vec::new());
}
if data.len() < 4 {
return Err(LoadError::MalformedSection);
}
let count = u32::from_le_bytes([data[0], data[1], data[2], data[3]]) as usize;
let mut exports = Vec::with_capacity(count);
let mut pos = 4;
for _ in 0..count {
if pos + 8 > data.len() {
return Err(LoadError::UnexpectedEof);
}
let func_idx = u32::from_le_bytes(data[pos..pos + 4].try_into().unwrap());
let name_len = u32::from_le_bytes(data[pos + 4..pos + 8].try_into().unwrap()) as usize;
pos += 8;
if pos + name_len > data.len() {
return Err(LoadError::UnexpectedEof);
}
let symbol = String::from_utf8_lossy(&data[pos..pos + name_len]).into_owned();
exports.push(Export { symbol, func_idx });
pos += name_len;
}
Ok(exports)
}
fn parse_syscalls(data: &[u8]) -> Result<Vec<SyscallDecl>, LoadError> {
if data.len() < 4 {
return Err(LoadError::MalformedSection);
}
let count = u32::from_le_bytes([data[0], data[1], data[2], data[3]]) as usize;
let mut syscalls = Vec::with_capacity(count);
let mut pos = 4;
for _ in 0..count {
if pos + 2 > data.len() {
return Err(LoadError::UnexpectedEof);
}
let module_len = u16::from_le_bytes(data[pos..pos + 2].try_into().unwrap()) as usize;
pos += 2;
if pos + module_len > data.len() {
return Err(LoadError::UnexpectedEof);
}
let module = std::str::from_utf8(&data[pos..pos + module_len])
.map_err(|_| LoadError::InvalidUtf8)?;
pos += module_len;
if pos + 2 > data.len() {
return Err(LoadError::UnexpectedEof);
}
let name_len = u16::from_le_bytes(data[pos..pos + 2].try_into().unwrap()) as usize;
pos += 2;
if pos + name_len > data.len() {
return Err(LoadError::UnexpectedEof);
}
let name =
std::str::from_utf8(&data[pos..pos + name_len]).map_err(|_| LoadError::InvalidUtf8)?;
pos += name_len;
if pos + 6 > data.len() {
return Err(LoadError::UnexpectedEof);
}
let version = u16::from_le_bytes(data[pos..pos + 2].try_into().unwrap());
let arg_slots = u16::from_le_bytes(data[pos + 2..pos + 4].try_into().unwrap());
let ret_slots = u16::from_le_bytes(data[pos + 4..pos + 6].try_into().unwrap());
pos += 6;
syscalls.push(SyscallDecl {
module: module.to_owned(),
name: name.to_owned(),
version,
arg_slots,
ret_slots,
});
}
if pos != data.len() {
return Err(LoadError::MalformedSection);
}
Ok(syscalls)
}
fn validate_module(module: &BytecodeModule) -> Result<(), LoadError> {
let mut syscall_identities = HashSet::with_capacity(module.syscalls.len());
for syscall in &module.syscalls {
if !syscall_identities.insert((
syscall.module.clone(),
syscall.name.clone(),
syscall.version,
)) {
return Err(LoadError::DuplicateSyscallIdentity);
}
}
for func in &module.functions {
// Opcode stream bounds
if (func.code_offset as usize) + (func.code_len as usize) > module.code.len() {
return Err(LoadError::InvalidFunctionIndex);
}
}
// Basic opcode scan for const pool indices
let mut pos = 0;
while pos < module.code.len() {
if pos + 2 > module.code.len() {
break; // Unexpected EOF in middle of opcode, maybe should be error
}
let op_val = u16::from_le_bytes([module.code[pos], module.code[pos + 1]]);
let opcode = OpCode::try_from(op_val).map_err(|_| LoadError::InvalidOpcode)?;
pos += 2;
match opcode {
OpCode::PushConst => {
if pos + 4 > module.code.len() {
return Err(LoadError::UnexpectedEof);
}
let idx =
u32::from_le_bytes(module.code[pos..pos + 4].try_into().unwrap()) as usize;
if idx >= module.const_pool.len() {
return Err(LoadError::InvalidConstIndex);
}
pos += 4;
}
OpCode::PushI32
| OpCode::Jmp
| OpCode::JmpIfFalse
| OpCode::JmpIfTrue
| OpCode::GetGlobal
| OpCode::SetGlobal
| OpCode::GetLocal
| OpCode::SetLocal
| OpCode::PopN
| OpCode::Hostcall
| OpCode::Syscall
| OpCode::Intrinsic => {
pos += 4;
}
OpCode::PushI64 | OpCode::PushF64 => {
pos += 8;
}
OpCode::PushBool => {
pos += 1;
}
OpCode::Call => {
pos += 4;
}
_ => {}
}
}
Ok(())
}
#[cfg(test)]
mod tests {
use super::*;
fn create_header(section_count: u32) -> Vec<u8> {
let mut h = vec![0u8; 32];
h[0..4].copy_from_slice(&PBX_MAGIC);
h[4..6].copy_from_slice(&0u16.to_le_bytes()); // version
h[6] = 0; // endianness
h[8..12].copy_from_slice(&section_count.to_le_bytes());
h
}
fn minimal_module() -> BytecodeModule {
BytecodeModule {
version: 0,
const_pool: vec![],
functions: vec![],
code: vec![],
debug_info: None,
exports: vec![],
syscalls: vec![],
}
}
fn build_pbx_with_sections(sections: Vec<(u32, Vec<u8>)>) -> Vec<u8> {
let mut data = create_header(sections.len() as u32);
let mut offset = 32 + (sections.len() as u32 * 12);
for (kind, section_data) in &sections {
data.extend_from_slice(&kind.to_le_bytes());
data.extend_from_slice(&offset.to_le_bytes());
data.extend_from_slice(&(section_data.len() as u32).to_le_bytes());
offset += section_data.len() as u32;
}
for (_, section_data) in sections {
data.extend_from_slice(&section_data);
}
data
}
#[test]
fn test_invalid_magic() {
let mut data = create_header(0);
data[0..4].copy_from_slice(b"PBS\0");
assert_eq!(BytecodeLoader::load(&data), Err(LoadError::InvalidMagic));
}
#[test]
fn test_invalid_version() {
let mut data = create_header(0);
data[4] = 1;
assert_eq!(BytecodeLoader::load(&data), Err(LoadError::InvalidVersion));
}
#[test]
fn test_invalid_endianness() {
let mut data = create_header(0);
data[6] = 1;
assert_eq!(BytecodeLoader::load(&data), Err(LoadError::InvalidEndianness));
}
#[test]
fn test_overlapping_sections() {
let mut data = create_header(2);
// Section 1: Kind 0, Offset 64, Length 32
data.extend_from_slice(&0u32.to_le_bytes());
data.extend_from_slice(&64u32.to_le_bytes());
data.extend_from_slice(&32u32.to_le_bytes());
// Section 2: Kind 1, Offset 80, Length 32 (Overlaps with Section 1)
data.extend_from_slice(&1u32.to_le_bytes());
data.extend_from_slice(&80u32.to_le_bytes());
data.extend_from_slice(&32u32.to_le_bytes());
// Ensure data is long enough for the offsets
data.resize(256, 0);
assert_eq!(BytecodeLoader::load(&data), Err(LoadError::OverlappingSections));
}
#[test]
fn test_section_out_of_bounds() {
let mut data = create_header(1);
// Section 1: Kind 0, Offset 64, Length 1000
data.extend_from_slice(&0u32.to_le_bytes());
data.extend_from_slice(&64u32.to_le_bytes());
data.extend_from_slice(&1000u32.to_le_bytes());
data.resize(256, 0);
assert_eq!(BytecodeLoader::load(&data), Err(LoadError::SectionOutOfBounds));
}
#[test]
fn test_invalid_function_code_offset() {
let mut data = create_header(3);
// Section 1: Functions, Kind 1, Offset 80, Length 20 (Header 4 + 1 entry 16)
data.extend_from_slice(&1u32.to_le_bytes());
data.extend_from_slice(&80u32.to_le_bytes());
data.extend_from_slice(&20u32.to_le_bytes());
// Section 2: Code, Kind 2, Offset 128, Length 10
data.extend_from_slice(&2u32.to_le_bytes());
data.extend_from_slice(&128u32.to_le_bytes());
data.extend_from_slice(&10u32.to_le_bytes());
// Section 3: SYSC, Kind 5, Offset 160, Length 4 (empty)
data.extend_from_slice(&5u32.to_le_bytes());
data.extend_from_slice(&160u32.to_le_bytes());
data.extend_from_slice(&4u32.to_le_bytes());
data.resize(256, 0);
// Setup functions section
let func_data_start = 80;
data[func_data_start..func_data_start + 4].copy_from_slice(&1u32.to_le_bytes()); // 1 function
let entry_start = func_data_start + 4;
data[entry_start..entry_start + 4].copy_from_slice(&5u32.to_le_bytes()); // code_offset = 5
data[entry_start + 4..entry_start + 8].copy_from_slice(&10u32.to_le_bytes()); // code_len = 10
// 5 + 10 = 15 > 10 (code section length)
data[160..164].copy_from_slice(&0u32.to_le_bytes());
assert_eq!(BytecodeLoader::load(&data), Err(LoadError::InvalidFunctionIndex));
}
#[test]
fn test_invalid_const_index() {
let mut data = create_header(3);
// Section 1: Const Pool, Kind 0, Offset 80, Length 4 (Empty CP)
data.extend_from_slice(&0u32.to_le_bytes());
data.extend_from_slice(&80u32.to_le_bytes());
data.extend_from_slice(&4u32.to_le_bytes());
// Section 2: Code, Kind 2, Offset 128, Length 6 (PushConst 0)
data.extend_from_slice(&2u32.to_le_bytes());
data.extend_from_slice(&128u32.to_le_bytes());
data.extend_from_slice(&6u32.to_le_bytes());
// Section 3: SYSC, Kind 5, Offset 160, Length 4 (empty)
data.extend_from_slice(&5u32.to_le_bytes());
data.extend_from_slice(&160u32.to_le_bytes());
data.extend_from_slice(&4u32.to_le_bytes());
data.resize(256, 0);
// Setup empty CP
data[80..84].copy_from_slice(&0u32.to_le_bytes());
// Setup code with PushConst 0
data[128..130].copy_from_slice(&(OpCode::PushConst as u16).to_le_bytes());
data[130..134].copy_from_slice(&0u32.to_le_bytes());
data[160..164].copy_from_slice(&0u32.to_le_bytes());
assert_eq!(BytecodeLoader::load(&data), Err(LoadError::InvalidConstIndex));
}
#[test]
fn test_missing_sysc_section_is_rejected() {
let data = create_header(0);
assert_eq!(BytecodeLoader::load(&data), Err(LoadError::MissingSyscallSection));
}
#[test]
fn test_valid_minimal_load_with_empty_sysc() {
let data = minimal_module().serialize();
let module = BytecodeLoader::load(&data).unwrap();
assert_eq!(module.version, 0);
assert!(module.const_pool.is_empty());
assert!(module.functions.is_empty());
assert!(module.code.is_empty());
assert!(module.syscalls.is_empty());
}
#[test]
fn test_valid_sysc_roundtrip() {
let mut module = minimal_module();
module.syscalls = vec![SyscallDecl {
module: "gfx2d".into(),
name: "draw_line".into(),
version: 1,
arg_slots: 4,
ret_slots: 0,
}];
let data = module.serialize();
let loaded = BytecodeLoader::load(&data).unwrap();
assert_eq!(loaded.syscalls, module.syscalls);
}
#[test]
fn test_malformed_sysc_section_is_rejected() {
let data = build_pbx_with_sections(vec![(SECTION_KIND_SYSCALLS, vec![1, 0, 0])]);
assert_eq!(BytecodeLoader::load(&data), Err(LoadError::MalformedSection));
}
#[test]
fn test_invalid_utf8_in_sysc_section_is_rejected() {
let mut sysc = Vec::new();
sysc.extend_from_slice(&1u32.to_le_bytes());
sysc.extend_from_slice(&1u16.to_le_bytes());
sysc.push(0xFF);
sysc.extend_from_slice(&1u16.to_le_bytes());
sysc.push(b'x');
sysc.extend_from_slice(&1u16.to_le_bytes());
sysc.extend_from_slice(&0u16.to_le_bytes());
sysc.extend_from_slice(&0u16.to_le_bytes());
let data = build_pbx_with_sections(vec![(SECTION_KIND_SYSCALLS, sysc)]);
assert_eq!(BytecodeLoader::load(&data), Err(LoadError::InvalidUtf8));
}
#[test]
fn test_duplicate_sysc_identity_is_rejected() {
let mut module = minimal_module();
module.syscalls = vec![
SyscallDecl {
module: "system".into(),
name: "has_cart".into(),
version: 1,
arg_slots: 0,
ret_slots: 1,
},
SyscallDecl {
module: "system".into(),
name: "has_cart".into(),
version: 1,
arg_slots: 0,
ret_slots: 1,
},
];
let data = module.serialize();
assert_eq!(BytecodeLoader::load(&data), Err(LoadError::DuplicateSyscallIdentity));
}
}
+13 -36
View File
@@ -143,46 +143,20 @@ pub enum OpCode {
/// Returns from the current function.
/// Stack: [return_val] -> [return_val]
Ret = 0x51,
/// Creates a closure capturing values from the operand stack (Model B).
/// Operands: fn_id (u32), capture_count (u32)
/// Stack before: [..., captured_N, ..., captured_1]
/// Pops capture_count values (top-first), preserves order as [captured_1..captured_N]
/// and stores them inside the closure environment. Pushes a HeapRef to the closure.
/// Create a typed instance: FunctionId, FnTypeId. Captures come from metadata.
MakeClosure = 0x52,
/// Calls a closure value with hidden arg0 semantics (Model B).
/// Operand: arg_count (u32) — number of user-supplied args (excludes hidden arg0)
/// Stack before: [..., argN, ..., arg1, closure_ref]
/// Behavior:
/// - Pops `closure_ref` and validates it is a Closure.
/// - Pops `arg_count` user args.
/// - Fetches `fn_id` from the closure and creates a new call frame.
/// - Injects hidden arg0 = closure_ref, followed by user args as arg1..argN.
/// Invoke with expected FnTypeId; environment belongs to CallFrame, not arg0.
CallClosure = 0x53,
// --- 7.x Concurrency / Coroutines ---
/// Spawns a new coroutine to run a function with arguments.
/// Operands: fn_id (u32), arg_count (u32)
/// Semantics:
/// - Pops `arg_count` arguments from the current operand stack (top-first),
/// preserving user order as arg1..argN for the callee.
/// - Allocates a new Coroutine object with its own stack and a single entry frame
/// pointing at `fn_id`.
/// - Enqueues the coroutine into the scheduler ready queue.
/// - Does NOT switch execution immediately; current coroutine continues.
/// Retired opcode, recognized only for load rejection and diagnostics.
Spawn = 0x54,
/// Cooperatively yields the current coroutine. Execution continues
/// until the next VM safepoint (FRAME_SYNC), where the scheduler
/// may switch to another ready coroutine.
/// Retired opcode, recognized only for load rejection and diagnostics.
Yield = 0x55,
/// Suspends the current coroutine for a number of logical ticks.
/// Operand: duration_ticks (u32)
/// Semantics:
/// - Set the coroutine wake tick to `current_tick + duration_ticks`.
/// - End the current logical frame (as if reaching FRAME_SYNC).
/// - The coroutine will resume execution on or after the wake tick.
/// Retired opcode, recognized only for load rejection and diagnostics.
Sleep = 0x56,
/// Copy complete current-frame capture group by declaration index.
GetCapture = 0x57,
/// Dispatch through an immutable implementation: TraitTypeId, method index.
CallTrait = 0x58,
// --- 6.8 Peripherals and System ---
/// Pre-load host binding call by `SYSC` table index.
@@ -280,6 +254,8 @@ impl TryFrom<u16> for OpCode {
0x54 => Ok(OpCode::Spawn),
0x55 => Ok(OpCode::Yield),
0x56 => Ok(OpCode::Sleep),
0x57 => Ok(OpCode::GetCapture),
0x58 => Ok(OpCode::CallTrait),
0x70 => Ok(OpCode::Syscall),
0x71 => Ok(OpCode::Hostcall),
0x72 => Ok(OpCode::Intrinsic),
@@ -352,7 +328,8 @@ impl OpCode {
OpCode::Call => 5,
OpCode::Ret => 4,
OpCode::MakeClosure => 8,
OpCode::CallClosure => 6,
OpCode::CallClosure | OpCode::CallTrait => 6,
OpCode::GetCapture => 2,
OpCode::Spawn => 6,
OpCode::Yield => 1,
OpCode::Sleep => 1,
@@ -13,13 +13,13 @@ pub struct OpcodeSpec {
pub is_branch: bool, // has a control-flow target
pub is_terminator: bool, // ends basic block: JMP/RET/TRAP/HALT
pub may_trap: bool, // runtime trap possible
/// Marks this opcode as a VM safepoint. Used by GC/scheduler policies.
/// Marks this opcode as a VM safepoint. Used by GC policies. Last-root RET is also a contextual GC opportunity.
pub is_safepoint: bool,
}
pub trait OpCodeSpecExt {
fn spec(&self) -> OpcodeSpec;
/// These instructions cannot be verified from slot-only FunctionMeta.
/// These instructions cannot be verified from slot-only ExecutionFunction.
fn requires_registry(&self) -> bool {
self.spec().pops.is_none() || self.spec().pushes.is_none()
}
@@ -438,30 +438,27 @@ impl OpCodeSpecExt for OpCode {
may_trap: false,
is_safepoint: false,
},
OpCode::MakeClosure => OpcodeSpec {
name: "MAKE_CLOSURE",
// Two u32 immediates: fn_id and capture_count
imm_bytes: 8,
// Dynamic, depends on capture_count; keep 0 here for verifier-free spec
pops: Some(0),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
is_safepoint: false,
},
OpCode::CallClosure => OpcodeSpec {
name: "CALL_CLOSURE",
// One u32 immediate: arg_count (user args, excludes hidden arg0)
imm_bytes: 4,
// Dynamic: pops closure_ref + arg_count; keep 0 in spec layer
pops: Some(0),
pushes: Some(0),
is_branch: false,
is_terminator: false,
may_trap: true,
is_safepoint: false,
},
OpCode::MakeClosure | OpCode::CallClosure | OpCode::GetCapture | OpCode::CallTrait => {
OpcodeSpec {
name: match self {
OpCode::MakeClosure => "MAKE_CLOSURE",
OpCode::CallClosure => "CALL_CLOSURE",
OpCode::GetCapture => "GET_CAPTURE",
_ => "CALL_TRAIT",
},
imm_bytes: if matches!(self, OpCode::MakeClosure | OpCode::CallTrait) {
8
} else {
4
},
pops: None,
pushes: None,
is_branch: false,
is_terminator: false,
may_trap: true,
is_safepoint: false,
}
}
OpCode::Spawn => OpcodeSpec {
name: "SPAWN",
// Two u32 immediates: fn_id and arg_count
@@ -480,11 +477,11 @@ impl OpCodeSpecExt for OpCode {
pops: Some(0),
pushes: Some(0),
is_branch: false,
// Not a block terminator; effect realized at safepoint
// Retired encoding: retained for diagnostic decoding only.
is_terminator: false,
may_trap: false,
// Treated as a safepoint marker for cooperative scheduling
is_safepoint: true,
// Loading rejects this opcode, including unreachable occurrences.
is_safepoint: false,
},
OpCode::Sleep => OpcodeSpec {
name: "SLEEP",
@@ -493,11 +490,11 @@ impl OpCodeSpecExt for OpCode {
pops: Some(0),
pushes: Some(0),
is_branch: false,
// Ends execution at safepoint after instruction completes
// Retired encoding: retained for diagnostic decoding only.
is_terminator: false,
may_trap: false,
// Considered a safepoint since it forces a frame boundary
is_safepoint: true,
// Loading rejects this opcode, including unreachable occurrences.
is_safepoint: false,
},
OpCode::Hostcall => OpcodeSpec {
name: "HOSTCALL",
@@ -1,43 +1,35 @@
/// Resolved execution widths derived from sealed Registry metadata.
/// This cache is never serialized as a PBX function signature.
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
pub struct ExecutionFunction {
pub code_offset: u32,
pub code_len: u32,
pub param_slots: u16,
pub local_slots: u16,
pub return_slots: u16,
pub max_stack_slots: u16,
}
use crate::abi::TrapInfo;
use crate::model::{BytecodeModule, ConstantPoolEntry, DebugInfo, Export, FunctionMeta};
use crate::model::DebugInfo;
use crate::value::Value;
use serde::{Deserialize, Serialize};
use std::collections::HashMap;
use std::sync::Arc;
/// Represents a fully linked, executable PBX program image.
///
/// Under the Prometeu architecture, the ProgramImage is a "closed-world" artifact
/// produced by the compiler. All linking, relocation, and symbol resolution
/// MUST be performed by the compiler before this image is created.
///
/// The runtime (VM) assumes this image is authoritative and performs no
/// additional linking or fixups.
/// Immutable execution payload/cache, produced during sealed image publication.
/// This container does not authorize execution. VM sessions require the private
/// ValidatedProgramImage factory, including bounded Registry/ISA/native checks.
#[derive(Debug, Clone, Default)]
pub struct ProgramImage {
pub rom: Arc<[u8]>,
pub constant_pool: Arc<[Value]>,
pub functions: Arc<[FunctionMeta]>,
pub functions: Arc<[ExecutionFunction]>,
pub debug_info: Option<Arc<DebugInfo>>,
pub exports: Arc<HashMap<String, u32>>,
}
impl ProgramImage {
pub fn new(
rom: Vec<u8>,
constant_pool: Vec<Value>,
functions: Vec<FunctionMeta>,
debug_info: Option<DebugInfo>,
exports: HashMap<String, u32>,
) -> Self {
Self {
rom: Arc::from(rom),
constant_pool: Arc::from(constant_pool),
functions: Arc::from(functions),
debug_info: debug_info.map(Arc::new),
exports: Arc::new(exports),
}
}
pub fn create_trap(&self, code: u32, opcode: u16, mut message: String, pc: u32) -> TrapInfo {
let span = self
.debug_info
@@ -64,61 +56,3 @@ impl ProgramImage {
.map(|(_, name)| name.as_str())
}
}
impl From<BytecodeModule> for ProgramImage {
fn from(module: BytecodeModule) -> Self {
let constant_pool: Vec<Value> = module
.const_pool
.iter()
.map(|entry| match entry {
ConstantPoolEntry::Null => Value::Null,
ConstantPoolEntry::Int64(v) => Value::Int64(*v),
ConstantPoolEntry::Float64(v) => Value::Float(*v),
ConstantPoolEntry::Boolean(v) => Value::Boolean(*v),
ConstantPoolEntry::String(v) => Value::string(v.clone()),
ConstantPoolEntry::Int32(v) => Value::Int32(*v),
})
.collect();
let mut exports = HashMap::new();
for export in module.exports {
exports.insert(export.symbol, export.func_idx);
}
ProgramImage::new(module.code, constant_pool, module.functions, module.debug_info, exports)
}
}
impl From<ProgramImage> for BytecodeModule {
fn from(program: ProgramImage) -> Self {
let const_pool = program
.constant_pool
.iter()
.map(|v| match v {
Value::Null => ConstantPoolEntry::Null,
Value::Int64(v) => ConstantPoolEntry::Int64(*v),
Value::Float(v) => ConstantPoolEntry::Float64(*v),
Value::Boolean(v) => ConstantPoolEntry::Boolean(*v),
Value::String(v) => ConstantPoolEntry::String(v.to_string()),
Value::Int32(v) => ConstantPoolEntry::Int32(*v),
Value::HeapRef(_) => ConstantPoolEntry::Null,
})
.collect();
let exports = program
.exports
.iter()
.map(|(symbol, &func_idx)| Export { symbol: symbol.clone(), func_idx })
.collect();
BytecodeModule {
version: 0,
const_pool,
functions: program.functions.as_ref().to_vec(),
code: program.rom.as_ref().to_vec(),
debug_info: program.debug_info.as_deref().cloned(),
exports,
syscalls: Vec::new(),
}
}
}
+175 -21
View File
@@ -28,6 +28,17 @@ pub struct Signature {
pub parameters: Vec<NamedType>,
pub results: Vec<TypeId>,
}
impl Signature {
pub fn same_types(&self, other: &Self) -> bool {
self.parameters.len() == other.parameters.len()
&& self
.parameters
.iter()
.map(|p| p.type_id)
.eq(other.parameters.iter().map(|p| p.type_id))
&& self.results == other.results
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct MethodDecl {
pub name: Option<String>,
@@ -39,6 +50,7 @@ pub enum TypeKind {
Struct(Vec<NamedType>),
Array(TypeId),
Trait(Vec<MethodDecl>),
Fn(Signature),
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TypeDecl {
@@ -53,6 +65,8 @@ pub struct FunctionDecl {
pub code_len: u32,
pub local_slots: u32,
pub max_stack_slots: u32,
/// Ordered logical capture groups, encoded in the separate PBX section 8.
pub captures: Vec<TypeId>,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ImplementationDecl {
@@ -197,11 +211,21 @@ pub struct TypeLayout {
pub storage: StorageLayout,
pub instance: Option<StructLayout>,
pub array: Option<ArrayLayout>,
pub callable: Option<FunctionLayout>,
pub methods: Vec<FunctionLayout>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct CaptureLayout {
pub type_id: TypeId,
pub slot_offset: u32,
pub slots: u32,
}
#[derive(Debug, PartialEq, Eq)]
pub struct FunctionLayout {
pub parameter_slots: u32,
pub result_slots: u32,
pub capture_slots: u32,
pub captures: Vec<CaptureLayout>,
}
#[derive(Debug)]
@@ -258,10 +282,27 @@ impl Registry {
}
_ => StorageLayout::new(8, 8, 1, Ownership::GuestReference, DefaultKind::Null),
};
layouts.push(TypeLayout { storage, instance: None, array: None });
layouts.push(TypeLayout {
storage,
instance: None,
array: None,
callable: None,
methods: Vec::new(),
});
}
for (i, t) in d.types.iter().enumerate() {
b.work(1)?;
if let TypeKind::Fn(s) = &t.kind {
layouts[i].callable = Some(resolve_signature(s, &layouts, b)?);
}
if let TypeKind::Trait(methods) = &t.kind {
let mut resolved = b.vector(methods.len(), Q::RegistryBytes)?;
for method in methods {
b.work(1)?;
resolved.push(resolve_signature(&method.signature, &layouts, b)?);
}
layouts[i].methods = resolved;
}
if let TypeKind::Array(element_type_id) = t.kind {
let element = layouts[element_type_id.0 as usize].storage;
layouts[i].array = Some(ArrayLayout {
@@ -335,7 +376,20 @@ impl Registry {
.in_function(i as u32, Some(f.code_offset)));
}
ranges.push((f.code_offset, end, i as u32));
functions.push(FunctionLayout { parameter_slots: params, result_slots: results });
let mut captures = b.vector(f.captures.len(), Q::RegistryBytes)?;
let mut capture_slots = 0u32;
for &type_id in &f.captures {
b.work(1)?;
let slots = layouts[type_id.0 as usize].storage.slots;
captures.push(CaptureLayout { type_id, slot_offset: capture_slots, slots });
capture_slots = capture_slots.checked_add(slots).ok_or_else(overflow)?;
}
functions.push(FunctionLayout {
parameter_slots: params,
result_slots: results,
capture_slots,
captures,
});
}
sort_work(ranges.len(), b)?;
ranges.sort_unstable();
@@ -369,6 +423,12 @@ impl Registry {
}
for (j, (method, id)) in methods.iter().zip(&imp.methods).enumerate() {
let signature = &d.functions[id.0 as usize].signature;
if !d.functions[id.0 as usize].captures.is_empty() {
return Err(E::new(C::InvalidRegistry, R::CapturedDirectCall)
.in_section(7)
.record(i as u32)
.member(j as u32));
}
b.work(signature.parameters.len() + signature.results.len() + 1)?;
if signature.parameters.first().map(|p| p.type_id) != Some(imp.owner)
|| signature.parameters.len() != method.signature.parameters.len() + 1
@@ -403,6 +463,21 @@ impl Registry {
fn overflow() -> E {
E::new(C::ResourceLimit, R::Overflow)
}
fn resolve_signature(
s: &Signature,
layouts: &[TypeLayout],
b: &mut LoadBudget,
) -> Result<FunctionLayout, E> {
let parameter_slots = width(s.parameters.iter().map(|p| p.type_id), layouts, b)?;
let result_slots = width(s.results.iter().copied(), layouts, b)?;
if u64::from(parameter_slots) > b.frame_limit() {
return Err(E::new(C::InvalidRegistry, R::FrameSlots));
}
if u64::from(result_slots) > b.result_limit() {
return Err(E::new(C::InvalidRegistry, R::ReturnSlots));
}
Ok(FunctionLayout { parameter_slots, result_slots, capture_slots: 0, captures: Vec::new() })
}
fn align(n: usize, a: usize) -> Result<usize, E> {
n.checked_add(a - 1).map(|v| v & !(a - 1)).ok_or_else(overflow)
}
@@ -457,6 +532,34 @@ fn signature(s: &Signature, d: &RegistryDeclarations, b: &mut LoadBudget) -> Res
}
Ok(())
}
fn signature_order(
a: &Signature,
b: &Signature,
budget: &mut LoadBudget,
) -> Result<std::cmp::Ordering, E> {
use std::cmp::Ordering;
for (a, b) in a.parameters.iter().zip(&b.parameters) {
budget.work(1)?;
let order = a.type_id.cmp(&b.type_id);
if order != Ordering::Equal {
return Ok(order);
}
}
budget.work(1)?;
let order = a.parameters.len().cmp(&b.parameters.len());
if order != Ordering::Equal {
return Ok(order);
}
for (a, b) in a.results.iter().zip(&b.results) {
budget.work(1)?;
let order = a.cmp(b);
if order != Ordering::Equal {
return Ok(order);
}
}
budget.work(1)?;
Ok(a.results.len().cmp(&b.results.len()))
}
/// Validate all edges before indexed layout resolution; IDs remain table positions.
pub(crate) fn validate_declarations(d: &RegistryDeclarations, b: &mut LoadBudget) -> Result<(), E> {
b.charge(Q::Types, d.types.len() as u64)?;
@@ -478,6 +581,7 @@ pub(crate) fn validate_declarations(d: &RegistryDeclarations, b: &mut LoadBudget
Ok(())
}
TypeKind::Struct(fields) => named(fields, d, b),
TypeKind::Fn(s) => signature(s, d, b),
TypeKind::Trait(methods) => {
b.charge(Q::NestedRecords, methods.len() as u64)?;
for m in methods {
@@ -504,39 +608,87 @@ pub(crate) fn validate_declarations(d: &RegistryDeclarations, b: &mut LoadBudget
}
b.refund(Q::TemporaryBytes, (constructors.capacity() * size_of::<(i32, u32, u32)>()) as u64);
drop(constructors);
// Iterative tri-color walk: every Array has one successor; nominal nodes terminate walks.
let mut colors = b.vector::<u8>(d.types.len(), Q::TemporaryBytes)?;
colors.resize(d.types.len(), 0);
for start in 0..d.types.len() {
// Sorted Fn indices use fallible, metered comparisons; names are never keys.
let mut fns = b.vector::<usize>(d.types.len(), Q::TemporaryBytes)?;
for (id, t) in d.types.iter().enumerate() {
b.work(1)?;
let mut node = start;
while colors[node] == 0 {
b.work(1)?;
colors[node] = 1;
match d.types[node].kind {
TypeKind::Array(id) => node = id.0 as usize,
_ => break,
let TypeKind::Fn(key) = &t.kind else { continue };
let (mut lo, mut hi) = (0, fns.len());
while lo < hi {
let mid = lo + (hi - lo) / 2;
let TypeKind::Fn(other) = &d.types[fns[mid]].kind else { unreachable!() };
match signature_order(key, other, b)? {
std::cmp::Ordering::Equal => {
return Err(E::new(C::InvalidRegistry, R::DuplicateFn)
.in_section(6)
.record(id as u32))
}
std::cmp::Ordering::Less => hi = mid,
std::cmp::Ordering::Greater => lo = mid + 1,
}
}
if colors[node] == 1 && matches!(d.types[node].kind, TypeKind::Array(_)) {
return Err(E::new(C::InvalidRegistry, R::ArrayCycle).record(node as u32));
b.work(fns.len() - lo + 1)?;
fns.insert(lo, id);
}
b.refund(Q::TemporaryBytes, (fns.capacity() * size_of::<usize>()) as u64);
drop(fns);
// Iterative DFS processes each structural edge once; nominal nodes are leaves.
let mut colors = b.vector::<u8>(d.types.len(), Q::TemporaryBytes)?;
b.work(d.types.len())?;
colors.resize(d.types.len(), 0);
let mut walk = b.vector::<(usize, usize)>(d.types.len(), Q::TemporaryBytes)?;
for start in 0..d.types.len() {
b.work(1)?;
if colors[start] != 0 {
continue;
}
node = start;
while colors[node] == 1 {
colors[start] = 1;
walk.push((start, 0));
while let Some((node, edge)) = walk.last_mut() {
b.work(1)?;
colors[node] = 2;
match d.types[node].kind {
TypeKind::Array(id) => node = id.0 as usize,
_ => break,
let next = match &d.types[*node].kind {
TypeKind::Array(id) if *edge == 0 => Some(*id),
TypeKind::Fn(s) => s.parameters.get(*edge).map(|p| p.type_id).or_else(|| {
edge.checked_sub(s.parameters.len()).and_then(|e| s.results.get(e)).copied()
}),
_ => None,
};
*edge += 1;
if let Some(id) = next {
let id = id.0 as usize;
if colors[id] == 1 {
b.work(walk.len())?;
let reason =
if walk.iter().any(|(n, _)| matches!(d.types[*n].kind, TypeKind::Fn(_))) {
R::StructuralTypeCycle
} else {
R::ArrayCycle
};
return Err(E::new(C::InvalidRegistry, reason).in_section(6).record(id as u32));
}
if colors[id] == 0 {
colors[id] = 1;
walk.push((id, 0));
}
} else {
colors[*node] = 2;
walk.pop();
}
}
}
b.refund(Q::TemporaryBytes, colors.capacity() as u64);
b.refund(Q::TemporaryBytes, (walk.capacity() * size_of::<(usize, usize)>()) as u64);
drop(colors);
drop(walk);
for (i, f) in d.functions.iter().enumerate() {
b.work(1)?;
name(&f.name, b).map_err(|e| e.in_section(1).record(i as u32))?;
signature(&f.signature, d, b).map_err(|e| e.in_section(1).record(i as u32))?;
b.charge(Q::NestedRecords, f.captures.len() as u64)?;
for (j, &id) in f.captures.iter().enumerate() {
b.work(1)?;
type_ref(id, d).map_err(|e| e.in_section(8).record(i as u32).member(j as u32))?;
}
}
for (i, imp) in d.implementations.iter().enumerate() {
b.work(1)?;
@@ -590,6 +742,7 @@ fn charge_declarations(d: &RegistryDeclarations, b: &mut LoadBudget) -> Result<(
charge_name(&t.name, b)?;
match &t.kind {
TypeKind::Struct(fields) => charge_named(fields, b)?,
TypeKind::Fn(s) => charge_signature(s, b)?,
TypeKind::Trait(methods) => {
charge_vec(methods, b)?;
for m in methods {
@@ -605,6 +758,7 @@ fn charge_declarations(d: &RegistryDeclarations, b: &mut LoadBudget) -> Result<(
b.work(1)?;
charge_name(&f.name, b)?;
charge_signature(&f.signature, b)?;
charge_vec(&f.captures, b)?;
}
for imp in &d.implementations {
b.work(1)?;
@@ -14,7 +14,7 @@ pub struct Section<'a> {
}
#[derive(Debug)]
pub struct PbxEnvelope<'a> {
sections: [Option<Section<'a>>; 8],
sections: [Option<Section<'a>>; 9],
}
impl<'a> PbxEnvelope<'a> {
pub fn section(&self, kind: u32) -> Option<Section<'a>> {
@@ -47,12 +47,12 @@ impl<'a> PbxEnvelope<'a> {
if directory_end > bytes.len() {
return Err(E::new(C::InvalidFormat, R::Truncated));
}
let mut result = Self { sections: [None; 8] };
let mut result = Self { sections: [None; 9] };
for i in 0..count {
b.work(13)?;
let pos = 32 + i * 12;
let kind = u32::from_le_bytes(bytes[pos..pos + 4].try_into().unwrap());
if kind > 7 {
if kind > 8 {
return Err(E::new(C::UnsupportedFormat, R::SectionKind).at(kind, pos));
}
if result.sections[kind as usize].is_some() {
@@ -83,7 +83,7 @@ impl<'a> PbxEnvelope<'a> {
result.sections[kind as usize] =
Some(Section { kind, offset: start, bytes: &bytes[start..end] });
}
for kind in [0, 1, 2, 4, 5, 6, 7] {
for kind in [0, 1, 2, 4, 5, 6, 7, 8] {
if result.sections[kind].is_none() {
return Err(E::new(C::InvalidFormat, R::MissingSection).at(kind as u32, 8));
}
@@ -103,7 +103,8 @@ impl<'a> PbxEnvelope<'a> {
];
let before = resources.map(|r| b.used(r));
let types = Reader::new(self.section(6).unwrap(), b).types()?;
let functions = Reader::new(self.section(1).unwrap(), b).functions()?;
let mut functions = Reader::new(self.section(1).unwrap(), b).functions()?;
Reader::new(self.section(8).unwrap(), b).captures(&mut functions)?;
let implementations = Reader::new(self.section(7).unwrap(), b).implementations()?;
// Ownership moves from parse scratch to retained Registry. No clone or
// simultaneous second declaration allocation occurs at this boundary.
@@ -226,6 +227,7 @@ impl<'a, 'b> Reader<'a, 'b> {
0 => TypeKind::Builtin(BuiltinId(self.u32()?)),
1 => TypeKind::Struct(self.named()?),
2 => TypeKind::Array(TypeId(self.u32()?)),
4 => TypeKind::Fn(self.signature()?),
3 => {
let (mut methods, n) = self.list(Q::NestedRecords, 9)?;
for j in 0..n {
@@ -258,6 +260,7 @@ impl<'a, 'b> Reader<'a, 'b> {
code_len: self.u32()?,
local_slots: self.u32()?,
max_stack_slots: self.u32()?,
captures: Vec::new(),
})
})()
.map_err(|e: E| e.record(i as u32))?;
@@ -266,6 +269,26 @@ impl<'a, 'b> Reader<'a, 'b> {
self.finish()?;
Ok(out)
}
fn captures(mut self, functions: &mut [FunctionDecl]) -> Result<(), E> {
let n = self.u32()? as usize;
if n != functions.len() {
let mut error = self.error(C::InvalidFormat, R::CaptureCount);
error.requested = Some(n as u64);
error.limit = Some(functions.len() as u64);
return Err(error);
}
for (i, function) in functions.iter_mut().enumerate() {
self.budget.work(1)?;
let (mut captures, n) =
self.list(Q::NestedRecords, 4).map_err(|e| e.record(i as u32))?;
for _ in 0..n {
self.budget.work(1)?;
captures.push(TypeId(self.u32()?));
}
function.captures = captures;
}
self.finish()
}
fn implementations(mut self) -> Result<Vec<ImplementationDecl>, E> {
let (mut out, n) = self.list(Q::Implementations, 12)?;
for i in 0..n {
@@ -298,17 +321,17 @@ pub struct SectionData<'a> {
/// Assemble strict v1 sections. The output buffer is charged to temporary load storage.
pub fn encode_envelope(sections: &[SectionData<'_>], b: &mut LoadBudget) -> Result<Vec<u8>, E> {
b.transaction(|b| {
let mut by_kind = [None; 8];
let mut by_kind = [None; 9];
for section in sections {
b.work(1)?;
if section.kind > 7 {
if section.kind > 8 {
return Err(E::new(C::UnsupportedFormat, R::SectionKind));
}
if by_kind[section.kind as usize].replace(section.bytes).is_some() {
return Err(E::new(C::InvalidFormat, R::DuplicateSection));
}
}
for k in [0, 1, 2, 4, 5, 6, 7] {
for k in [0, 1, 2, 4, 5, 6, 7, 8] {
if by_kind[k].is_none() {
return Err(E::new(C::InvalidFormat, R::MissingSection).at(k as u32, 8));
}
@@ -347,6 +370,7 @@ pub struct RegistrySections {
pub types: Vec<u8>,
pub functions: Vec<u8>,
pub implementations: Vec<u8>,
pub captures: Vec<u8>,
}
/// Field-by-field serialization of already resolved Registry declarations.
/// There is no source-language inference or unsupported-value-to-null fallback.
@@ -361,12 +385,14 @@ pub fn encode_registry(registry: &Registry, b: &mut LoadBudget) -> Result<Regist
TypeKind::Struct(_) => 1,
TypeKind::Array(_) => 2,
TypeKind::Trait(_) => 3,
TypeKind::Fn(_) => 4,
})?;
w.name(&t.name)?;
match &t.kind {
TypeKind::Builtin(id) => w.u32(id.0)?,
TypeKind::Struct(fields) => w.named(fields)?,
TypeKind::Array(id) => w.u32(id.0)?,
TypeKind::Fn(s) => w.signature(s)?,
TypeKind::Trait(methods) => {
w.count(methods.len())?;
for m in methods {
@@ -402,7 +428,17 @@ pub fn encode_registry(registry: &Registry, b: &mut LoadBudget) -> Result<Regist
}
Ok(())
})?;
Ok(RegistrySections { types, functions, implementations })
let captures = write_section(b, |w| {
w.count(d.functions.len())?;
for f in &d.functions {
w.count(f.captures.len())?;
for id in &f.captures {
w.u32(id.0)?;
}
}
Ok(())
})?;
Ok(RegistrySections { types, functions, implementations, captures })
})
}
// Count first so a malicious producer cannot trigger unbounded geometric growth.
@@ -70,9 +70,9 @@ impl<'a> ParsedPbx<'a> {
}
/// Re-encode validated tables in canonical directory order; debug absence is preserved.
pub fn encode(&self, budget: &mut LoadBudget) -> Result<Vec<u8>, E> {
let mut sections = [SectionData { kind: 0, bytes: &[] }; 8];
let mut sections = [SectionData { kind: 0, bytes: &[] }; 9];
let mut count = 0;
for kind in 0..8 {
for kind in 0..9 {
if let Some(section) = self.section(kind) {
sections[count] = SectionData { kind, bytes: section.bytes };
count += 1;
@@ -43,7 +43,7 @@ impl PbxModule<'_> {
.debug
.map(|di| write_section(budget, |w| self.write_debug(di, w)))
.transpose()?;
let mut sections = [SectionData { kind: 0, bytes: &[] }; 8];
let mut sections = [SectionData { kind: 0, bytes: &[] }; 9];
let mut count = 0;
for (kind, bytes) in [
(0, Some(constants.as_slice())),
@@ -54,6 +54,7 @@ impl PbxModule<'_> {
(5, Some(syscalls.as_slice())),
(6, Some(registry.types.as_slice())),
(7, Some(registry.implementations.as_slice())),
(8, Some(registry.captures.as_slice())),
] {
if let Some(bytes) = bytes {
sections[count] = SectionData { kind, bytes };
@@ -2,7 +2,7 @@
use crate::decoder::DecodedInstr;
use crate::isa::core::{CoreOpCode as Op, CoreOpCodeSpecExt};
use crate::load_limits::{IdDomain, LoadCode, LoadFailure, LoadReason};
use crate::registry::{Registry, TypeId, TypeKind};
use crate::registry::{FunctionId, Registry, TypeId, TypeKind};
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct RegistryStackEffect {
@@ -11,6 +11,27 @@ pub struct RegistryStackEffect {
}
impl DecodedInstr<'_> {
/// Capture effects require the enclosing function's resolved environment.
pub fn registry_stack_effect_in(
&self,
registry: &Registry,
function: FunctionId,
) -> Result<Option<RegistryStackEffect>, LoadFailure> {
if self.opcode == Op::GetCapture {
let index = self
.imm_u32()
.map_err(|_| LoadFailure::new(LoadCode::InvalidCode, LoadReason::Truncated))?;
let capture = registry
.function_layout(function)
.and_then(|f| f.captures.get(index as usize))
.ok_or_else(|| {
LoadFailure::new(LoadCode::InvalidReference, LoadReason::CaptureIndex)
.member(index)
})?;
return Ok(Some(RegistryStackEffect { pops: 0, pushes: capture.slots }));
}
self.registry_stack_effect(registry)
}
/// Resolve an instruction's exact group widths and check immediate domains.
/// None means this is not a Registry instruction, not a zero stack effect.
/// This does not prove that the values on the stack satisfy the signature.
@@ -43,6 +64,42 @@ impl DecodedInstr<'_> {
e
};
let (pops, pushes) = match self.opcode {
Op::MakeClosure => {
let (function, ty) = self.imm_u32x2().map_err(|_| malformed())?;
let (_, layout) = type_info(ty)?;
if layout.callable.is_none() {
return Err(bad_category(ty));
}
let target = registry.function_layout(FunctionId(function)).ok_or_else(|| {
LoadFailure::new(LoadCode::InvalidReference, LoadReason::FunctionId)
.reference(IdDomain::Function, function)
})?;
(target.capture_slots, 1)
}
Op::CallClosure => {
let ty = self.imm_u32().map_err(|_| malformed())?;
let (_, layout) = type_info(ty)?;
let signature = layout.callable.as_ref().ok_or_else(|| bad_category(ty))?;
(
signature.parameter_slots.checked_add(1).ok_or_else(malformed)?,
signature.result_slots,
)
}
Op::GetCapture => {
return Err(LoadFailure::new(LoadCode::InvalidReference, LoadReason::CaptureIndex))
}
Op::CallTrait => {
let (ty, method) = self.imm_u32x2().map_err(|_| malformed())?;
let (_, layout) = type_info(ty)?;
let signature = layout
.methods
.get(method as usize)
.ok_or_else(|| bad_category(ty).member(method))?;
(
signature.parameter_slots.checked_add(2).ok_or_else(malformed)?,
signature.result_slots,
)
}
Op::DynPack | Op::DynUnpack | Op::DynCanUnpack => {
let id = self.imm_u32().map_err(|_| malformed())?;
let (_, layout) = type_info(id)?;
@@ -9,7 +9,7 @@ fn emit(op: CoreOpCode, imm: Option<&[u8]>, out: &mut Vec<u8>) {
}
#[test]
fn roundtrip_disasm_assemble_byte_equal_with_closures_and_coroutines() {
fn roundtrip_disasm_assemble_byte_equal_with_typed_callables() {
// Program: PUSH_I32 7; MAKE_CLOSURE fn=1,captures=0; CALL_CLOSURE argc=1;
// SPAWN fn=2,argc=1; YIELD; SLEEP 3; HOSTCALL 2; SYSCALL 0x1003; FRAME_SYNC; HALT
let mut prog = Vec::new();
@@ -22,15 +22,9 @@ fn roundtrip_disasm_assemble_byte_equal_with_closures_and_coroutines() {
emit(CoreOpCode::MakeClosure, Some(&mc), &mut prog);
// CALL_CLOSURE argc=1
emit(CoreOpCode::CallClosure, Some(&1u32.to_le_bytes()), &mut prog);
// SPAWN (fn=2, argc=1)
let mut sp = [0u8; 8];
sp[0..4].copy_from_slice(&2u32.to_le_bytes());
sp[4..8].copy_from_slice(&1u32.to_le_bytes());
emit(CoreOpCode::Spawn, Some(&sp), &mut prog);
// YIELD
emit(CoreOpCode::Yield, None, &mut prog);
// SLEEP 3
emit(CoreOpCode::Sleep, Some(&3u32.to_le_bytes()), &mut prog);
emit(CoreOpCode::GetCapture, Some(&0u32.to_le_bytes()), &mut prog);
let trait_call = [7u32.to_le_bytes(), 0u32.to_le_bytes()].concat();
emit(CoreOpCode::CallTrait, Some(&trait_call), &mut prog);
// HOSTCALL sysc[2]
emit(CoreOpCode::Hostcall, Some(&2u32.to_le_bytes()), &mut prog);
// SYSCALL gfx2d.draw_line (0x1003)
@@ -17,7 +17,7 @@ fn snapshot_representative_program_is_stable() {
mc[0..4].copy_from_slice(&1u32.to_le_bytes());
mc[4..8].copy_from_slice(&0u32.to_le_bytes());
emit(CoreOpCode::MakeClosure, Some(&mc), &mut prog);
// CALL_CLOSURE argc=1
// CALL_CLOSURE 1
emit(CoreOpCode::CallClosure, Some(&1u32.to_le_bytes()), &mut prog);
// SPAWN (fn=2, argc=1)
let mut sp = [0u8; 8];
@@ -38,6 +38,6 @@ fn snapshot_representative_program_is_stable() {
emit(CoreOpCode::Halt, None, &mut prog);
let text = disassemble(&prog).expect("disasm ok");
let expected = "PUSH_I32 7\nMAKE_CLOSURE fn=1, captures=0\nCALL_CLOSURE argc=1\nSPAWN fn=2, argc=1\nYIELD\nSLEEP 3\nHOSTCALL 2\nSYSCALL 0x1003\nFRAME_SYNC\nHALT";
let expected = "PUSH_I32 7\nMAKE_CLOSURE fn=1, type=0\nCALL_CLOSURE 1\nSPAWN fn=2, argc=1\nYIELD\nSLEEP 3\nHOSTCALL 2\nSYSCALL 0x1003\nFRAME_SYNC\nHALT";
assert_eq!(text, expected);
}
@@ -7,6 +7,116 @@ use prometeu_bytecode::registry_codec::*;
fn budget() -> LoadBudget {
LoadBudget::new(LoadLimits::default())
}
#[test]
fn fn_keys_ignore_names_but_preserve_logical_parameter_and_result_order() {
let signature = Signature { parameters: vec![named(0)], results: vec![TypeId(1)] };
let mut renamed = signature.clone();
renamed.parameters[0].name = Some("renamed".into());
let d = RegistryDeclarations {
types: vec![
builtin(BuiltinId::INT32),
builtin(BuiltinId::INT64),
TypeDecl { name: Some("a".into()), kind: TypeKind::Fn(signature.clone()) },
TypeDecl { name: Some("b".into()), kind: TypeKind::Fn(renamed) },
],
..Default::default()
};
let e = resolve(d).unwrap_err();
assert_eq!((e.code, e.reason), (LoadCode::InvalidRegistry, LoadReason::DuplicateFn));
let r = resolve(RegistryDeclarations {
types: vec![
builtin(BuiltinId::INT32),
builtin(BuiltinId::INT64),
TypeDecl { name: None, kind: TypeKind::Fn(signature) },
TypeDecl {
name: None,
kind: TypeKind::Fn(Signature {
parameters: vec![named(1)],
results: vec![TypeId(0)],
}),
},
],
..Default::default()
})
.unwrap();
let layout = r.type_layout(TypeId(2)).unwrap();
assert_eq!(layout.storage.slots, 1);
assert_eq!(layout.storage.size, 8);
assert_eq!(layout.storage.alignment, 8);
assert_eq!(layout.storage.default, DefaultKind::Null);
}
#[test]
fn fn_descriptor_bytes_are_independent_of_execution_width_caches() {
let r = resolve(RegistryDeclarations {
types: vec![
builtin(BuiltinId::INT32),
builtin(BuiltinId::VEC2),
TypeDecl {
name: None,
kind: TypeKind::Fn(Signature {
parameters: vec![named(1)],
results: vec![TypeId(0)],
}),
},
],
..Default::default()
})
.unwrap();
let sections = encode_registry(&r, &mut budget()).unwrap();
assert_eq!(sections.types,hex("03 00 00 00 00 00 10 00 00 00 00 00 02 00 00 00 04 00 01 00 00 00 01 00 00 00 00 01 00 00 00 00 00 00 00"));
let callable = r.type_layout(TypeId(2)).unwrap().callable.as_ref().unwrap();
assert_eq!((callable.parameter_slots, callable.result_slots), (2, 1));
}
#[test]
fn fn_array_structural_cycles_reject_and_nominal_anchors_terminate() {
let mut types = vec![
TypeDecl {
name: None,
kind: TypeKind::Fn(Signature { parameters: vec![named(1)], results: vec![] }),
},
TypeDecl { name: None, kind: TypeKind::Array(TypeId(0)) },
];
assert_eq!(
resolve(RegistryDeclarations { types: types.clone(), ..Default::default() })
.unwrap_err()
.reason,
LoadReason::StructuralTypeCycle
);
types[1].kind = TypeKind::Struct(vec![named(0)]);
resolve(RegistryDeclarations { types, ..Default::default() }).unwrap();
}
#[test]
fn captures_section_has_independent_bytes_and_strict_shape() {
let r = resolve(RegistryDeclarations {
types: vec![builtin(BuiltinId::INT32), builtin(BuiltinId::VEC2)],
functions: vec![FunctionDecl {
code_len: 2,
captures: vec![TypeId(1), TypeId(0)],
..Default::default()
}],
..Default::default()
})
.unwrap();
let sections = encode_registry(&r, &mut budget()).unwrap();
assert_eq!(sections.captures, hex("01 00 00 00 02 00 00 00 01 00 00 00 00 00 00 00"));
let layout = r.function_layout(FunctionId(0)).unwrap();
assert_eq!(layout.capture_slots, 3);
assert_eq!(layout.captures[1].slot_offset, 2);
for (payload, reason) in [
(hex("00 00 00 00"), LoadReason::CaptureCount),
(hex("01 00 00 00 01 00 00 00"), LoadReason::Truncated),
(hex("01 00 00 00 00 00 00 00 00"), LoadReason::TrailingBytes),
(hex("01 00 00 00 01 00 00 00 ff ff ff ff"), LoadReason::TypeId),
] {
let e = OwnedPbx::parse(&with_section(8, &payload), &mut budget()).unwrap_err();
assert_eq!(e.reason, reason);
assert_eq!(e.section, Some(8));
}
}
fn named(id: u32) -> NamedType {
NamedType { type_id: TypeId(id), name: None }
}
@@ -21,20 +131,21 @@ fn hex(s: &str) -> Vec<u8> {
}
// Independently specified PBX, not generated by any production serializer.
// Header 32 bytes, seven directory entries (84 bytes), payload starts at 116.
// constants=116/4, functions=120/29, code=149/2, exports=151/4,
// syscalls=155/4, types=159/10, implementations=169/4. Total=173.
// Header 32 bytes, eight directory entries (96 bytes), payload starts at 128.
// constants=128/4, functions=132/29, code=161/2, exports=163/4,
// syscalls=167/4, types=171/10, implementations=181/4. Total=193.
fn minimal_bytes() -> Vec<u8> {
hex("
50 42 58 00 01 00 00 00 07 00 00 00
50 42 58 00 01 00 00 00 08 00 00 00
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
00 00 00 00 74 00 00 00 04 00 00 00
01 00 00 00 78 00 00 00 1d 00 00 00
02 00 00 00 95 00 00 00 02 00 00 00
04 00 00 00 97 00 00 00 04 00 00 00
05 00 00 00 9b 00 00 00 04 00 00 00
06 00 00 00 9f 00 00 00 0a 00 00 00
07 00 00 00 a9 00 00 00 04 00 00 00
00 00 00 00 80 00 00 00 04 00 00 00
01 00 00 00 84 00 00 00 1d 00 00 00
02 00 00 00 a1 00 00 00 02 00 00 00
04 00 00 00 a3 00 00 00 04 00 00 00
05 00 00 00 a7 00 00 00 04 00 00 00
06 00 00 00 ab 00 00 00 0a 00 00 00
07 00 00 00 b5 00 00 00 04 00 00 00
08 00 00 00 b9 00 00 00 08 00 00 00
00 00 00 00
01 00 00 00 00 00 00 00 00 00 00 00 00
00 00 00 00 02 00 00 00 00 00 00 00 00 00 00 00
@@ -42,7 +153,8 @@ fn minimal_bytes() -> Vec<u8> {
00 00 00 00
00 00 00 00
01 00 00 00 00 00 13 00 00 00
00 00 00 00")
00 00 00 00
01 00 00 00 00 00 00 00")
}
fn minimal_registry() -> Registry {
resolve(RegistryDeclarations {
@@ -55,6 +167,9 @@ fn minimal_registry() -> Registry {
fn envelope(types: &[u8], functions: &[u8], implementations: &[u8]) -> Vec<u8> {
let empty = [0; 4];
let code = [1, 0];
let n = u32::from_le_bytes(functions[..4].try_into().unwrap()) as usize;
let mut captures = vec![0; 4 + 4 * n];
captures[..4].copy_from_slice(&(n as u32).to_le_bytes());
encode_envelope(
&[
SectionData { kind: 0, bytes: &empty },
@@ -64,6 +179,7 @@ fn envelope(types: &[u8], functions: &[u8], implementations: &[u8]) -> Vec<u8> {
SectionData { kind: 5, bytes: &empty },
SectionData { kind: 6, bytes: types },
SectionData { kind: 7, bytes: implementations },
SectionData { kind: 8, bytes: &captures },
],
&mut budget(),
)
@@ -74,10 +190,10 @@ fn writer_matches_independent_minimal_envelope() {
let sections = encode_registry(&minimal_registry(), &mut budget()).unwrap();
let bytes = envelope(&sections.types, &sections.functions, &sections.implementations);
assert_eq!(bytes, minimal_bytes());
assert_eq!(bytes.len(), 173);
assert_eq!(bytes.len(), 193);
let mut b = budget();
let env = PbxEnvelope::parse(&bytes, &mut b).unwrap();
assert_eq!(env.section(2).unwrap().offset, 149);
assert_eq!(env.section(2).unwrap().offset, 161);
let registry = env.resolve_registry(&mut b).unwrap();
assert_eq!(registry.declarations(), minimal_registry().declarations());
assert_eq!(b.used(LoadResource::TemporaryBytes), 0);
@@ -384,10 +500,10 @@ fn envelope_mutations_have_typed_reasons() {
(6, 1, LoadCode::InvalidFormat, LoadReason::Endianness),
(7, 1, LoadCode::InvalidFormat, LoadReason::Reserved),
(31, 1, LoadCode::InvalidFormat, LoadReason::Reserved),
(32, 8, LoadCode::UnsupportedFormat, LoadReason::SectionKind),
(32, 9, LoadCode::UnsupportedFormat, LoadReason::SectionKind),
(44, 0, LoadCode::InvalidFormat, LoadReason::DuplicateSection),
(36, 0, LoadCode::InvalidFormat, LoadReason::Overlap),
(48, 116, LoadCode::InvalidFormat, LoadReason::Overlap),
(48, 128, LoadCode::InvalidFormat, LoadReason::Overlap),
] {
let mut bytes = minimal_bytes();
bytes[offset] = value;
@@ -402,6 +518,16 @@ fn mandatory_empty_sections_are_required() {
let err = PbxEnvelope::parse(&bytes, &mut budget()).unwrap_err();
assert_eq!(err.reason, LoadReason::MissingSection);
assert_eq!(err.section, Some(0));
let mut bytes = minimal_bytes();
bytes[116] = 3; // captures replaced by optional debug
let err = PbxEnvelope::parse(&bytes, &mut budget()).unwrap_err();
assert_eq!(err.reason, LoadReason::MissingSection);
assert_eq!(err.section, Some(8));
let mut bytes = minimal_bytes();
bytes[104] = 8; // duplicate captures directory entry
let err = PbxEnvelope::parse(&bytes, &mut budget()).unwrap_err();
assert_eq!(err.reason, LoadReason::DuplicateSection);
assert_eq!(err.section, Some(8));
}
#[test]
fn record_flags_utf8_trailing_bytes_and_unknown_categories_fail() {
@@ -412,7 +538,7 @@ fn record_flags_utf8_trailing_bytes_and_unknown_categories_fail() {
let implementations = env.section(7).unwrap().bytes;
for (types, reason) in [
(hex("01 00 00 00 00 02 13 00 00 00"), LoadReason::InvalidFlag),
(hex("01 00 00 00 04 00 13 00 00 00"), LoadReason::Category),
(hex("01 00 00 00 05 00 13 00 00 00"), LoadReason::Category),
(hex("01 00 00 00 00 01 01 00 00 00 ff 13 00 00 00"), LoadReason::Utf8),
(hex("01 00 00 00 00 00 13 00 00 00 ff"), LoadReason::TrailingBytes),
(hex("01 00 00 00 00 00 00 01 00 00"), LoadReason::Builtin),
@@ -577,7 +703,12 @@ fn multi_slot_signatures_derive_counts_and_validate_exact_trait_pair() {
let r = resolve(implemented()).unwrap();
assert_eq!(
r.function_layout(FunctionId(0)),
Some(&FunctionLayout { parameter_slots: 3, result_slots: 2 })
Some(&FunctionLayout {
parameter_slots: 3,
result_slots: 2,
capture_slots: 0,
captures: vec![]
})
);
let mut d = implemented();
d.functions[0].signature.parameters.swap(0, 1);
@@ -655,7 +786,7 @@ fn with_section(kind: u32, payload: &[u8]) -> Vec<u8> {
let mut b = budget();
let env = PbxEnvelope::parse(&bytes, &mut b).unwrap();
let mut sections = Vec::new();
for k in 0..8 {
for k in 0..9 {
if k == kind {
sections.push(SectionData { kind: k, bytes: payload });
} else if let Some(section) = env.section(k) {
@@ -870,6 +1001,7 @@ fn independent_multi_slot_signature_fixture_has_no_serialized_widths() {
SectionData { kind: 5, bytes: &empty },
SectionData { kind: 6, bytes: &types },
SectionData { kind: 7, bytes: &empty },
SectionData { kind: 8, bytes: &[1, 0, 0, 0, 0, 0, 0, 0] },
],
&mut budget(),
)
@@ -877,7 +1009,12 @@ fn independent_multi_slot_signature_fixture_has_no_serialized_widths() {
let parsed = ParsedPbx::parse(&bytes, &mut budget()).unwrap();
assert_eq!(
parsed.registry().function_layout(FunctionId(0)),
Some(&FunctionLayout { parameter_slots: 2, result_slots: 2 })
Some(&FunctionLayout {
parameter_slots: 2,
result_slots: 2,
capture_slots: 0,
captures: vec![]
})
);
let sections = encode_registry(parsed.registry(), &mut budget()).unwrap();
assert_eq!(sections.functions, functions);
@@ -12,3 +12,4 @@ prometeu-hal = { path = "../prometeu-hal" }
[dev-dependencies]
prometeu-drivers = { path = "../prometeu-drivers" }
prometeu-bytecode = { path = "../prometeu-bytecode" }
prometeu-test-support = { path = "../../dev/prometeu-test-support" }
@@ -3,12 +3,16 @@ use crate::firmware::firmware_state::{
FirmwareState, GameRunningStep, LoadCartridgeStep, ResetStep,
};
use crate::firmware::prometeu_context::PrometeuContext;
#[cfg(test)]
use prometeu_bytecode::registry::FunctionDecl;
use prometeu_hal::app_mode::AppMode;
use prometeu_hal::cartridge::Cartridge;
use prometeu_hal::log::LogSource;
use prometeu_hal::telemetry::CertificationConfig;
use prometeu_hal::{InputSignals, RuntimePlatform};
use prometeu_system::{PrometeuHub, ResidentGameState, SystemOS};
#[cfg(test)]
use prometeu_test_support::program::{TestProgram, int64_signature};
/// PROMETEU Firmware.
///
@@ -252,7 +256,7 @@ mod tests {
use crate::firmware::firmware_state::HubHomeStep;
use crate::firmware::resident_game_termination::{self, ResidentGameTerminationOutcome};
use prometeu_bytecode::assembler::assemble;
use prometeu_bytecode::model::{BytecodeModule, FunctionMeta, SyscallDecl};
use prometeu_bytecode::model::SyscallDecl;
use prometeu_drivers::{GlyphBankPoolAccess, SceneBankPoolAccess, TestPlatform};
use prometeu_hal::RuntimePlatform;
use prometeu_hal::app_mode::AppMode;
@@ -345,13 +349,17 @@ mod tests {
fn halting_program() -> Vec<u8> {
let code = assemble("HALT").expect("assemble");
BytecodeModule {
version: 0,
TestProgram {
const_pool: vec![],
functions: vec![FunctionMeta {
functions: vec![FunctionDecl {
code_offset: 0,
code_len: code.len() as u32,
..Default::default()
signature: int64_signature(0, 0),
captures: vec![],
name: None,
local_slots: 0,
max_stack_slots: 256,
}],
code,
debug_info: None,
@@ -381,13 +389,17 @@ mod tests {
fn trapping_game_cartridge() -> Cartridge {
let code = assemble("PUSH_BOOL 1\nHOSTCALL 0\nHALT").expect("assemble");
let program = BytecodeModule {
version: 0,
let program = TestProgram {
const_pool: vec![],
functions: vec![FunctionMeta {
functions: vec![FunctionDecl {
code_offset: 0,
code_len: code.len() as u32,
..Default::default()
signature: int64_signature(0, 0),
captures: vec![],
name: None,
local_slots: 0,
max_stack_slots: 256,
}],
code,
debug_info: None,
@@ -497,7 +509,7 @@ mod tests {
match &firmware.state {
FirmwareState::AppCrashes(step) => match &step.report {
CrashReport::VmInit { error } => {
assert!(matches!(error, prometeu_vm::VmInitError::InvalidFormat));
assert!(matches!(error, prometeu_vm::VmInitError::RegistryLoadFailed(_)));
}
other => panic!("expected VmInit crash report, got {:?}", other),
},
@@ -12,3 +12,4 @@ prometeu-hal = { path = "../prometeu-hal" }
[dev-dependencies]
prometeu-drivers = { path = "../prometeu-drivers" }
prometeu-test-support = { path = "../../dev/prometeu-test-support" }
@@ -4,7 +4,8 @@ use crate::services::memcard::MemcardService;
use prometeu_bytecode::TRAP_TYPE;
use prometeu_bytecode::Value;
use prometeu_bytecode::assembler::assemble;
use prometeu_bytecode::model::{BytecodeModule, ConstantPoolEntry, FunctionMeta, SyscallDecl};
use prometeu_bytecode::model::{ConstantPoolEntry, SyscallDecl};
use prometeu_bytecode::registry::FunctionDecl;
use prometeu_drivers::TestPlatform;
use prometeu_drivers::{GlyphBankPoolInstaller, MemoryBanks, SceneBankPoolInstaller};
use prometeu_hal::AudioOpStatus;
@@ -22,6 +23,7 @@ use prometeu_hal::syscalls::caps;
use prometeu_hal::tile::Tile;
use prometeu_hal::tilemap::TileMap;
use prometeu_hal::{InputSignals, RuntimePlatform};
use prometeu_test_support::program::{TestProgram, int64_signature};
use prometeu_vm::VmInitError;
use std::collections::HashMap;
use std::sync::Arc;
@@ -96,13 +98,17 @@ fn serialized_single_function_module_with_consts(
const_pool: Vec<ConstantPoolEntry>,
syscalls: Vec<SyscallDecl>,
) -> Vec<u8> {
BytecodeModule {
version: 0,
TestProgram {
const_pool,
functions: vec![FunctionMeta {
functions: vec![FunctionDecl {
code_offset: 0,
code_len: code.len() as u32,
..Default::default()
signature: int64_signature(0, 0),
captures: vec![],
name: None,
local_slots: 0,
max_stack_slots: 256,
}],
code,
debug_info: None,
@@ -233,6 +239,8 @@ fn initialize_vm_succeeds_when_cartridge_capabilities_cover_hostcalls() {
assert!(res.is_ok());
assert_eq!(runtime.current_app_id, 42);
assert!(vm.is_halted());
vm.prepare_boot_call().unwrap();
assert!(!vm.is_halted());
}
@@ -679,40 +687,11 @@ fn tick_system_profile_can_use_shared_log_transport() {
}
#[test]
fn tick_returns_panic_report_distinct_from_trap() {
let mut runtime = VirtualMachineRuntime::new(None);
let mut log_service = LogService::new(4096);
let mut fs = VirtualFS::new();
let mut fs_state = FsState::Unmounted;
let mut memcard = MemcardService::new();
let mut open_files: HashMap<u32, String> = HashMap::new();
let mut next_handle = 1;
let mut vm = VirtualMachine::new(assemble("HOSTCALL 0\nHALT").expect("assemble"), vec![]);
let mut platform = TestPlatform::new();
let signals = InputSignals::default();
let report = runtime
.tick(
&mut log_service,
&mut fs,
&mut fs_state,
&mut memcard,
&mut open_files,
&mut next_handle,
&mut vm,
&signals,
&mut platform,
)
.expect("panic must surface as runtime error");
match report {
CrashReport::VmPanic { message, pc } => {
assert!(message.contains("HOSTCALL 0 reached execution without loader patching"));
assert!(pc.is_some());
}
other => panic!("expected VmPanic crash report, got {:?}", other),
}
assert!(matches!(runtime.last_crash_report, Some(CrashReport::VmPanic { .. })));
fn unpatched_hostcall_is_rejected_before_tick() {
let bytes = serialized_single_function_module(assemble("HOSTCALL 0\nHALT").unwrap(), vec![]);
let mut vm = VirtualMachine::default();
assert!(vm.initialize(bytes).is_err());
assert!(vm.is_halted());
}
#[test]
@@ -390,9 +390,8 @@ impl VirtualMachineRuntime {
self.frame_scheduler.complete_game_frame();
}
if run.reason == LogicalFrameEndingReason::FrameSync {
self.needs_prepare_entry_call = true;
}
self.needs_prepare_entry_call =
run.reason == LogicalFrameEndingReason::EndOfRom;
if self.debug_step_request {
self.paused = true;
@@ -3,4 +3,6 @@ pub struct CallFrame {
pub return_pc: u32,
pub stack_base: usize,
pub func_idx: usize,
/// Active Fn owner; keeps the immutable environment alive until return.
pub closure: Option<prometeu_bytecode::HeapRef>,
}
+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] {
@@ -33,7 +33,6 @@ fn forge_box(heap: &mut Heap, registry: Arc<Registry>, ty: TypeId, values: &[Val
payload: BudgetVec::new(&heap.budget, Q::GuestBytes),
array_elems: None,
closure_env: None,
coroutine: None,
typed: None,
dynamic_box: Some(dynamic_box),
})
-1
View File
@@ -14,7 +14,6 @@ mod roots;
mod program_image;
#[allow(dead_code)]
mod registry_verifier;
mod scheduler;
pub use program_image::{ImageStringLease, ValidatedProgramImage};
// Image/session creation and native provenance consume this in step 19.
#[allow(dead_code)]
@@ -1,5 +1,5 @@
use crate::call_frame::CallFrame;
use prometeu_bytecode::FunctionMeta;
use prometeu_bytecode::ExecutionFunction;
use prometeu_bytecode::{TRAP_INVALID_LOCAL, TrapInfo};
// /// Computes the absolute stack index for the start of the current frame's locals (including args).
@@ -15,7 +15,7 @@ pub fn local_index(frame: &CallFrame, slot: u32) -> usize {
/// Validates that a local slot index is within the valid range for the function.
/// Range: 0 <= slot < (param_slots + local_slots)
pub fn check_local_slot(
meta: &FunctionMeta,
meta: &ExecutionFunction,
slot: u32,
opcode: u16,
pc: u32,
+6 -14
View File
@@ -26,15 +26,15 @@
//! defined by each object kind; the GC treats it as an opaque metadata field.
//!
//! Closure-specific note: for `ObjectKind::Closure`, `payload_len` is the
//! fixed size `8` and the payload layout is exactly two little-endian `u32`s:
//! `[fn_id][env_len]`. The captured environment values themselves are NOT in
//! fixed size `12` and the payload layout is exactly three little-endian `u32`s:
//! `[fn_id][env_len][FnTypeId]`. The captured environment values themselves are NOT in
//! the raw payload; they live in a separate GC-visible area managed by the
//! heap (see `Heap`), and the GC must traverse exactly `env_len` values from
//! that environment slice.
//!
//! Notes:
//! - The GC only relies on `flags` (mark bit) and `kind` to traverse/trace.
//! Actual traversal logic will be implemented elsewhere in future PRs.
//! The heap traverses resolved typed reference maps and closure environments.
//! - The header is intentionally compact (8 bytes on most targets) to minimize
//! per-object overhead.
//!
@@ -66,8 +66,8 @@ pub enum ObjectKind {
/// Compiled closure/function value.
///
/// Invariants for `payload_len` and payload layout:
/// - `payload_len == 8` (fixed).
/// - payload bytes are `[fn_id: u32][env_len: u32]` (little-endian).
/// - `payload_len == 12` (fixed).
/// - payload bytes are `[fn_id: u32][env_len: u32][FnTypeId: u32]` (little-endian).
/// - The `env_len` captured values are stored out-of-line in the heap so
/// they remain directly visible to the GC during traversal.
Closure = 3,
@@ -80,15 +80,7 @@ pub enum ObjectKind {
#[allow(dead_code)] // Reserved for host/native integrations
UserData = 5,
/// Coroutine object: suspended execution context with its own stack/frames.
///
/// Notes:
/// - Stack/frames are stored in typed fields inside the heap storage
/// (not inside raw `payload` bytes) so the GC can traverse their
/// contained `HeapRef`s directly.
/// - `payload_len` is 0 for this fixed-layout object.
Coroutine = 6,
// Tag 6 is reserved for the retired Coroutine kind.
/// Registry-defined Struct with a compact typed instance payload.
Struct = 7,
@@ -8,7 +8,7 @@ use prometeu_bytecode::load_limits::{
use prometeu_bytecode::model::{ConstantPoolEntry as K, DebugInfo, Export};
use prometeu_bytecode::registry::{FunctionId, Registry};
use prometeu_bytecode::registry_codec::OwnedPbx;
use prometeu_bytecode::{FunctionMeta, ProgramImage, Value};
use prometeu_bytecode::{ExecutionFunction, ProgramImage, Value};
use prometeu_hal::syscalls::{CapFlags, DeclaredLoadError, SyscallResolved};
use std::collections::HashMap;
use std::sync::{Arc, Mutex, Weak};
@@ -144,6 +144,11 @@ impl ValidatedProgramImage {
if module.registry.declarations().functions.is_empty() {
return Err(E::new(C::InvalidEntrypoint, R::FunctionId).in_function(0, None).into());
}
if !module.registry.declarations().functions[0].captures.is_empty() {
return Err(E::new(C::InvalidEntrypoint, R::CapturedDirectCall)
.in_function(0, None)
.into());
}
bind(&mut module, b, capabilities)?;
crate::registry_verifier::validate_registry_types(
&module.code,
@@ -153,7 +158,7 @@ impl ValidatedProgramImage {
)?;
let mut functions =
scratch::<FunctionMeta>(module.registry.declarations().functions.len(), b)?;
scratch::<ExecutionFunction>(module.registry.declarations().functions.len(), b)?;
for (index, f) in module.registry.declarations().functions.iter().enumerate() {
b.work(1)?;
let slots = module.registry.function_layout(FunctionId(index as u32)).unwrap();
@@ -165,7 +170,7 @@ impl ValidatedProgramImage {
.in_function(index as u32, Some(f.code_offset))
})
};
functions.push(FunctionMeta {
functions.push(ExecutionFunction {
code_offset: f.code_offset,
code_len: f.code_len,
param_slots: narrow(slots.parameter_slots)?,
@@ -88,7 +88,7 @@ fn validate_inner(
)?;
}
instruction
.registry_stack_effect(registry)
.registry_stack_effect_in(registry, FunctionId(function_id))
.map_err(|e| contextual(e, start + pc))?;
match instruction.opcode {
Op::Jmp | Op::JmpIfTrue | Op::JmpIfFalse => {
@@ -117,19 +117,37 @@ fn validate_inner(
return Err(with_id(reference_error(fail(R::ConstantIndex)), id));
}
}
Op::Call | Op::MakeClosure | Op::Spawn => {
Op::Spawn | Op::Yield | Op::Sleep => return Err(fail(R::RemovedOpcode)),
Op::Call | Op::MakeClosure => {
let id = if instruction.opcode == Op::Call {
instruction.imm_u32().unwrap()
} else {
instruction.imm_u32x2().unwrap().0
};
let callee = registry.function_layout(FunctionId(id)).ok_or_else(|| {
reference_error(fail(R::FunctionId)).reference(IdDomain::Function, id)
})?;
if instruction.opcode == Op::Spawn
&& instruction.imm_u32x2().unwrap().1 != callee.parameter_slots
{
return Err(fail(R::Signature).reference(IdDomain::Function, id));
let target =
registry.declarations().functions.get(id as usize).ok_or_else(
|| {
reference_error(fail(R::FunctionId))
.reference(IdDomain::Function, id)
},
)?;
if instruction.opcode == Op::Call && !target.captures.is_empty() {
return Err(
fail(R::CapturedDirectCall).reference(IdDomain::Function, id)
);
}
if instruction.opcode == Op::MakeClosure {
let ty = instruction.imm_u32x2().unwrap().1;
let prometeu_bytecode::registry::TypeKind::Fn(signature) =
&registry.declarations().types[ty as usize].kind
else {
unreachable!()
};
budget
.work(signature.parameters.len() + signature.results.len() + 1)?;
if !signature.same_types(&target.signature) {
return Err(fail(R::Signature).reference(IdDomain::Function, id));
}
}
}
Op::Hostcall => {
@@ -1,6 +1,6 @@
//! Bounded basic-block stack analysis. This does not publish an image or prove
//! semantic argument types. Closure target facts preserve the existing known
//! callee restriction; no guest callable descriptor is invented here.
//! semantic argument types. Fn stack effects come from the expected Registry
//! signature; concrete target facts never gate an indirect call.
use super::*;
#[derive(Clone, Copy, PartialEq, Eq)]
@@ -108,15 +108,14 @@ fn analyze(
4
},
)?;
let effect = instruction.registry_stack_effect(registry)?.unwrap();
let effect =
instruction.registry_stack_effect_in(registry, FunctionId(id))?.unwrap();
(u64::from(effect.pops), u64::from(effect.pushes))
} else {
(u64::from(spec.pops.unwrap()), u64::from(spec.pushes.unwrap()))
};
match instruction.opcode {
Op::PopN => effect = (u64::from(instruction.imm_u32().unwrap()), 0),
Op::MakeClosure => effect = (u64::from(instruction.imm_u32x2().unwrap().1), 1),
Op::Spawn => effect = (u64::from(instruction.imm_u32x2().unwrap().1), 0),
Op::Call => {
budget.work(1)?;
let callee = registry
@@ -124,30 +123,6 @@ fn analyze(
.unwrap();
effect = (u64::from(callee.parameter_slots), u64::from(callee.result_slots));
}
Op::CallClosure => {
let arguments = u64::from(instruction.imm_u32().unwrap());
if (height as u64) < arguments + 1 {
return Err(count_error(R::StackUnderflow, height as u64, arguments + 1));
}
budget.work(2)?;
let target = match working[locals + height - 1] {
Fact::Closure(target) => target,
Fact::NonClosure => return Err(E::new(C::InvalidCode, R::NotClosure)),
Fact::Unknown => {
return Err(E::new(C::InvalidCode, R::UnknownClosureCallee));
}
};
let callee = registry.function_layout(FunctionId(target)).unwrap();
if u64::from(callee.parameter_slots) != arguments + 1 {
return Err(count_error(
R::Signature,
arguments + 1,
u64::from(callee.parameter_slots),
)
.reference(IdDomain::Function, target));
}
effect = (arguments + 1, u64::from(callee.result_slots));
}
Op::Ret => {
if height != results {
return Err(count_error(R::ReturnHeight, height as u64, results as u64));
@@ -169,9 +144,6 @@ fn analyze(
.unwrap();
effect = (native.arg_slots() as u64, native.ret_slots() as u64);
}
Op::Yield if height != 0 => {
return Err(count_error(R::InvalidYield, height as u64, 0));
}
_ => {}
}
if (height as u64) < effect.0 {
@@ -20,6 +20,14 @@ fn registry(code: &[u8], functions: Vec<FunctionDecl>) -> Registry {
TypeDecl { name: None, kind: TypeKind::Builtin(B::VEC2) },
TypeDecl { name: None, kind: TypeKind::Struct(vec![]) },
TypeDecl { name: None, kind: TypeKind::Trait(vec![]) },
TypeDecl { name: None, kind: TypeKind::Fn(Signature::default()) },
TypeDecl {
name: None,
kind: TypeKind::Fn(Signature {
parameters: vec![NamedType { type_id: TypeId(0), name: None }],
results: vec![],
}),
},
],
functions,
implementations: vec![],
@@ -221,48 +229,36 @@ fn stack_analysis_straight_line_storage_is_bounded_by_blocks_not_instruction_fra
}
#[test]
fn stack_analysis_retains_unknown_closure_and_yield_safety_rules() {
let mut code = vec![];
arg(&mut code, Op::GetLocal, 0);
arg(&mut code, Op::CallClosure, 0);
op(&mut code, Op::Halt);
fn stack_analysis_accepts_unknown_fn_targets_and_rejects_removed_opcodes() {
let code = prometeu_bytecode::assemble("GET_LOCAL 0\nCALL_CLOSURE 4\nHALT").unwrap();
let f = FunctionDecl {
signature: Signature {
parameters: vec![NamedType { type_id: TypeId(0), name: None }],
parameters: vec![NamedType { type_id: TypeId(4), name: None }],
results: vec![],
},
..function(&code)
};
let r = registry(&code, vec![f]);
assert_eq!(stacks(&code, &r).unwrap_err().reason, R::UnknownClosureCallee);
let mut code = vec![];
arg(&mut code, Op::GetLocal, 0);
arg(&mut code, Op::CallClosure, 0);
let r = registry(&code, vec![FunctionDecl { local_slots: 1, ..function(&code) }]);
assert_eq!(stacks(&code, &r).unwrap_err().reason, R::NotClosure);
let mut code = vec![];
arg(&mut code, Op::PushI32, 0);
op(&mut code, Op::Yield);
let r = registry(&code, vec![function(&code)]);
assert_eq!(stacks(&code, &r).unwrap_err().reason, R::InvalidYield);
stacks(&code, &r).unwrap();
for opcode in [Op::Yield, Op::Sleep, Op::Spawn] {
let mut code = vec![];
op(&mut code, Op::Halt);
op(&mut code, opcode);
code.resize(code.len() + opcode.spec().imm_bytes as usize, 0);
let r = registry(&code, vec![function(&code)]);
assert_eq!(check(&code, &r).unwrap_err().reason, R::RemovedOpcode);
}
}
#[test]
fn stack_analysis_preserves_closure_facts_through_permutations_before_rejecting_bad_arity() {
let mut code = vec![];
arg(&mut code, Op::PushI32, 0);
arg(&mut code, Op::MakeClosure, 1);
code.extend_from_slice(&0u32.to_le_bytes());
op(&mut code, Op::Swap);
op(&mut code, Op::Pop);
op(&mut code, Op::Dup);
op(&mut code, Op::Pop);
arg(&mut code, Op::SetLocal, 0);
arg(&mut code, Op::GetLocal, 0);
arg(&mut code, Op::CallClosure, 0);
op(&mut code, Op::Halt);
fn expected_fn_signature_checks_argument_height_after_permutations() {
let mut code=prometeu_bytecode::assemble("PUSH_I32 0\nMAKE_CLOSURE fn=1,type=5\nSWAP\nPOP\nDUP\nPOP\nSET_LOCAL 0\nGET_LOCAL 0\nCALL_CLOSURE 5\nHALT").unwrap();
let end = code.len();
op(&mut code, Op::Ret);
let signature = Signature {
parameters: vec![NamedType { type_id: TypeId(0), name: None }],
results: vec![],
};
let r = registry(
&code,
vec![
@@ -272,18 +268,14 @@ fn stack_analysis_preserves_closure_facts_through_permutations_before_rejecting_
max_stack_slots: 2,
..function(&code)
},
FunctionDecl { code_offset: end as u32, code_len: 2, ..Default::default() },
FunctionDecl { signature, code_offset: end as u32, code_len: 2, ..Default::default() },
],
);
let e = stacks(&code, &r).unwrap_err();
// The callee deliberately lacks hidden arg0: this fixture is rejected,
// and does not invent a typed descriptor for a valid guest closure.
assert_eq!((e.reason, e.referenced_id), (R::Signature, Some(1)));
assert_eq!((e.requested, e.limit), (Some(1), Some(0)));
assert_eq!(stacks(&code, &r).unwrap_err().reason, R::StackUnderflow);
}
#[test]
fn stack_analysis_checks_closure_counts_without_wraparound() {
fn expected_fn_type_ids_never_wrap_or_become_argument_counts() {
for operation in [Op::MakeClosure, Op::CallClosure] {
let mut code = vec![];
if operation == Op::MakeClosure {
@@ -294,9 +286,7 @@ fn stack_analysis_checks_closure_counts_without_wraparound() {
}
op(&mut code, Op::Halt);
let r = registry(&code, vec![function(&code)]);
let e = stacks(&code, &r).unwrap_err();
assert_eq!(e.reason, R::StackUnderflow);
assert_eq!(e.limit, Some(u64::from(u32::MAX) + u64::from(operation == Op::CallClosure)));
assert_eq!(stacks(&code, &r).unwrap_err().reason, R::TypeId);
}
}
@@ -471,7 +461,7 @@ fn unreachable_function_constant_boolean_and_native_operands_are_checked() {
#[test]
fn spawn_arity_does_not_truncate_and_closure_function_ids_are_checked() {
for (operation, function_id, count, reason) in
[(Op::Spawn, 0, 65_536, R::Signature), (Op::MakeClosure, 1, 0, R::FunctionId)]
[(Op::Spawn, 0, 65_536, R::RemovedOpcode), (Op::MakeClosure, 1, 4, R::FunctionId)]
{
let mut code = vec![];
op(&mut code, Op::Halt);
@@ -24,7 +24,6 @@ enum Fact {
Int64(i64),
Group { ty: TypeId, part: u32, origin: u64 },
Dynamic { part: u32, origin: u64 },
Closure(u32),
}
pub(crate) fn validate_registry_types(
@@ -102,7 +101,16 @@ fn analyze(
while pc < end {
*at_pc = pc;
let instruction = metered_decode(pc, body, budget)?;
transfer(&instruction, &mut working, locals, &mut height, registry, constants, budget)?;
transfer(
&instruction,
&mut working,
locals,
&mut height,
registry,
constants,
id,
budget,
)?;
let spec = instruction.opcode.spec();
if spec.is_branch {
let target = instruction.imm_u32().unwrap() as usize;
@@ -150,7 +158,16 @@ fn analyze(
*at_pc = pc;
let instruction = metered_decode(pc, body, budget)?;
check(&instruction, &working, locals, height, registry, id, budget)?;
transfer(&instruction, &mut working, locals, &mut height, registry, constants, budget)?;
transfer(
&instruction,
&mut working,
locals,
&mut height,
registry,
constants,
id,
budget,
)?;
if instruction.opcode.spec().is_terminator {
break;
}
@@ -178,7 +195,7 @@ fn group(
fn component(registry: &Registry, ty: TypeId, part: u32, budget: &mut LoadBudget) -> Result<u8, E> {
budget.work(1)?;
Ok(match &registry.declarations().types[ty.0 as usize].kind {
TypeKind::Struct(_) | TypeKind::Array(_) => REFERENCE | NULL,
TypeKind::Struct(_) | TypeKind::Array(_) | TypeKind::Fn(_) => REFERENCE | NULL,
TypeKind::Trait(_) => {
if part == 0 {
REFERENCE | NULL
@@ -208,7 +225,6 @@ fn mask(fact: Fact, registry: &Registry, budget: &mut LoadBudget) -> Result<u8,
Fact::Null => NULL,
Fact::Carrier(mask) => mask,
Fact::Int64(_) => I64,
Fact::Closure(_) => REFERENCE,
Fact::Group { ty, part, .. } => return component(registry, ty, part, budget),
Fact::Dynamic { part: 0, .. } => I64 | NULL,
Fact::Dynamic { .. } => ANY,
@@ -244,6 +260,7 @@ fn transfer(
height: &mut usize,
registry: &Registry,
constants: &[Constant],
id: u32,
budget: &mut LoadBudget,
) -> Result<(), E> {
budget.work(1)?;
@@ -251,7 +268,7 @@ fn transfer(
let spec = opcode.spec();
let (mut pops, mut pushes) = if opcode.requires_registry() {
budget.work(4)?;
let effect = instruction.registry_stack_effect(registry)?.unwrap();
let effect = instruction.registry_stack_effect_in(registry, FunctionId(id))?.unwrap();
(effect.pops as usize, effect.pushes as usize)
} else {
(spec.pops.unwrap() as usize, spec.pushes.unwrap() as usize)
@@ -260,22 +277,27 @@ fn transfer(
let mut native = None;
match opcode {
Op::PopN => pops = instruction.imm_u32().unwrap() as usize,
Op::MakeClosure => pops = instruction.imm_u32x2().unwrap().1 as usize,
Op::Spawn => pops = instruction.imm_u32x2().unwrap().1 as usize,
Op::Call | Op::CallClosure => {
Op::Call => {
let target = instruction.imm_u32().unwrap();
budget.work(1)?;
let target = if opcode == Op::Call {
instruction.imm_u32().unwrap()
} else {
let Fact::Closure(target) = working[locals + *height - 1] else {
return Err(E::new(C::InvalidCode, R::UnknownClosureCallee));
};
target
};
let layout = registry.function_layout(FunctionId(target)).unwrap();
pops = layout.parameter_slots as usize;
pushes = layout.result_slots as usize;
call = Some(target);
call = Some(&registry.declarations().functions[target as usize].signature);
}
Op::CallClosure => {
let ty = instruction.imm_u32().unwrap();
let TypeKind::Fn(s) = &registry.declarations().types[ty as usize].kind else {
unreachable!()
};
call = Some(s);
}
Op::CallTrait => {
let (ty, method) = instruction.imm_u32x2().unwrap();
let TypeKind::Trait(methods) = &registry.declarations().types[ty as usize].kind else {
unreachable!()
};
call = Some(&methods[method as usize].signature);
}
Op::Ret => {
// Stack analysis has already proved exact height; no continuation.
@@ -387,14 +409,19 @@ fn transfer(
Constant::String(_) => Fact::Carrier(STRING),
};
}
Op::MakeClosure => {
budget.work(1)?;
working[base] = Fact::Closure(instruction.imm_u32x2().unwrap().0);
Op::MakeClosure | Op::GetCapture => {
let ty = if opcode == Op::MakeClosure {
TypeId(instruction.imm_u32x2().unwrap().1)
} else {
registry.function_layout(FunctionId(id)).unwrap().captures
[instruction.imm_u32().unwrap() as usize]
.type_id
};
group(&mut working[base..], registry, ty, (instruction.pc as u64) << 32, budget)?;
}
Op::Call | Op::CallClosure => {
let signature = &registry.declarations().functions[call.unwrap() as usize].signature;
Op::Call | Op::CallClosure | Op::CallTrait => {
let mut offset = base;
for (index, ty) in signature.results.iter().enumerate() {
for (index, ty) in call.unwrap().results.iter().enumerate() {
offset += group(
&mut working[offset..],
registry,
@@ -572,11 +599,6 @@ fn check_group(
budget.work(2)?;
let kind = &registry.declarations().types[ty.0 as usize].kind;
let width = registry.type_layout(ty).unwrap().storage.slots as usize;
if matches!(values[0], Fact::Closure(_))
&& matches!(kind, TypeKind::Struct(_) | TypeKind::Array(_) | TypeKind::Trait(_))
{
return Err(mismatch(0).reference(IdDomain::Type, ty.0));
}
budget.work(1)?;
if let Fact::Group { ty: source, part: 0, origin } = values[0] {
budget.work(1)?;
@@ -634,12 +656,8 @@ fn check(
budget.work(1)?;
let end = locals + height;
match instruction.opcode {
Op::Call | Op::Spawn => {
let target = if instruction.opcode == Op::Call {
instruction.imm_u32().unwrap()
} else {
instruction.imm_u32x2().unwrap().0
};
Op::Call => {
let target = instruction.imm_u32().unwrap();
budget.work(1)?;
let callee = registry.function_layout(FunctionId(target)).unwrap();
let mut base = end - callee.parameter_slots as usize;
@@ -659,21 +677,35 @@ fn check(
base += registry.type_layout(*ty).unwrap().storage.slots as usize;
}
}
Op::CallClosure => {
budget.work(1)?;
let Fact::Closure(target) = working[end - 1] else {
return Err(E::new(C::InvalidCode, R::UnknownClosureCallee));
};
let parameters =
&registry.declarations().functions[target as usize].signature.parameters;
budget.work(1)?;
let receiver = parameters.first().unwrap();
if registry.type_layout(receiver.type_id).unwrap().storage.slots != 1 {
return Err(mismatch(0));
Op::MakeClosure => {
let target = instruction.imm_u32x2().unwrap().0;
let layout = registry.function_layout(FunctionId(target)).unwrap();
let mut base = end - layout.capture_slots as usize;
for capture in &layout.captures {
check_group(&working[base..], capture.type_id, registry, budget)?;
base += capture.slots as usize;
}
check_group(&working[end - 1..end], receiver.type_id, registry, budget)?;
let mut base = end - instruction.imm_u32().unwrap() as usize - 1;
for parameter in parameters.iter().skip(1) {
}
Op::CallClosure | Op::CallTrait => {
let (ty, view_slots, signature) = if instruction.opcode == Op::CallClosure {
let ty = TypeId(instruction.imm_u32().unwrap());
let TypeKind::Fn(signature) = &registry.declarations().types[ty.0 as usize].kind
else {
unreachable!()
};
(ty, 1, signature)
} else {
let (ty, method) = instruction.imm_u32x2().unwrap();
let TypeKind::Trait(methods) = &registry.declarations().types[ty as usize].kind
else {
unreachable!()
};
(TypeId(ty), 2, &methods[method as usize].signature)
};
check_group(&working[end - view_slots..end], ty, registry, budget)?;
let effect = instruction.registry_stack_effect_in(registry, FunctionId(id))?.unwrap();
let mut base = end - effect.pops as usize;
for parameter in &signature.parameters {
check_group(&working[base..], parameter.type_id, registry, budget)?;
budget.work(1)?;
base += registry.type_layout(parameter.type_id).unwrap().storage.slots as usize;
@@ -688,7 +720,7 @@ fn check(
(instruction.imm_u32().unwrap(), 0)
};
let ty = TypeId(id);
let effect = instruction.registry_stack_effect(registry)?.unwrap();
let effect = instruction.registry_stack_effect_in(registry, FunctionId(id))?.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);
@@ -32,6 +32,7 @@ fn function(
max: u32,
) -> FunctionDecl {
FunctionDecl {
captures: vec![],
code_offset: offset as u32,
code_len: len as u32,
local_slots: locals,
@@ -283,7 +284,7 @@ fn known_closure_receivers_are_not_faked_as_user_struct_types() {
let r =
registry(&code, vec![function(0, end, &[], &[], 0, 1), function(end, 2, &[9], &[], 0, 0)]);
// No provisional callable descriptor: a Closure is never a guest Struct.
assert_eq!(check(&code, &r, &[]).unwrap_err().reason, R::TypeMismatch);
assert_eq!(check(&code, &r, &[]).unwrap_err().reason, R::Category);
}
#[test]
@@ -1,6 +1,5 @@
//! Session accounting shared by owners, with reservations refunded on failure/drop.
//! These quotas account VM domains, not process RSS or allocator metadata.
use std::collections::VecDeque;
use std::sync::{Arc, Mutex, MutexGuard};
pub use prometeu_bytecode::{ResourceFailure, ResourceReason, RuntimeResource};
@@ -58,6 +57,9 @@ impl RuntimeBudget {
fn state(&self) -> MutexGuard<'_, State> {
self.0.lock().unwrap_or_else(std::sync::PoisonError::into_inner)
}
pub(crate) fn limits(&self) -> RuntimeLimits {
self.state().limits.clone()
}
#[cfg(test)]
pub(crate) fn test_lower_limit(&self, resource: RuntimeResource, limit: u64) {
self.state().limits.0[resource as usize] = limit;
@@ -157,74 +159,6 @@ impl Drop for Reservation {
}
}
/// Scheduler storage owns its capacity charge, including unused capacity.
/// During growth, the old allocation is also covered by a temporary reservation.
#[derive(Debug)]
pub(crate) struct BudgetQueue<T> {
data: VecDeque<T>,
charge: Reservation,
}
impl<T> BudgetQueue<T> {
#[cfg(test)]
pub(crate) fn capacity_bytes(&self) -> u64 {
self.charge.amount
}
pub fn new(budget: &RuntimeBudget) -> Self {
Self { data: VecDeque::new(), charge: budget.empty_charge(RuntimeResource::AuxiliaryBytes) }
}
#[cfg(test)]
pub fn len(&self) -> usize {
self.data.len()
}
pub fn is_empty(&self) -> bool {
self.data.is_empty()
}
pub fn pop_front(&mut self) -> Option<T> {
self.data.pop_front()
}
pub fn reserve(&mut self, additional: usize) -> Result<(), ResourceFailure> {
let b = &self.charge.budget;
let q = RuntimeResource::AuxiliaryBytes;
let required = self
.data
.len()
.checked_add(additional)
.ok_or_else(|| b.failure(q, ResourceReason::SizeOverflow, u64::MAX))?;
if required <= self.data.capacity() {
return Ok(());
}
// Exact growth prevents a geometric allocation from exceeding the available quota.
let bytes = b.bytes::<T>(required, q)?;
let mut extra = b.reserve(q, bytes - self.charge.amount)?;
let _temporary = b.reserve(RuntimeResource::TemporaryBytes, self.charge.amount)?;
let mut candidate = VecDeque::new();
candidate
.try_reserve_exact(required)
.map_err(|_| b.failure(q, ResourceReason::AllocationFailed, bytes))?;
let actual = b.bytes::<T>(candidate.capacity(), q)?;
// If the allocator reports excess capacity, reject before publishing the new buffer.
extra.resize(actual - self.charge.amount)?;
candidate.append(&mut self.data);
self.data = candidate;
self.charge.absorb(extra);
Ok(())
}
pub fn push_back(&mut self, value: T) -> Result<(), ResourceFailure> {
self.reserve(1)?;
self.data.push_back(value);
Ok(())
}
pub fn insert(&mut self, index: usize, value: T) -> Result<(), ResourceFailure> {
self.reserve(1)?;
self.data.insert(index, value);
Ok(())
}
pub fn partition_point(&self, predicate: impl FnMut(&T) -> bool) -> usize {
self.data.partition_point(predicate)
}
}
#[cfg(test)]
mod tests {
use super::*;
@@ -268,21 +202,21 @@ mod tests {
}
#[test]
fn queue_capacity_is_retained_until_drop_and_transfer_does_not_charge_twice() {
fn stack_capacity_is_retained_until_drop_and_transfer_does_not_charge_twice() {
let budget =
RuntimeBudget::new(RuntimeLimits::default().lowered(AuxiliaryBytes, 16).unwrap());
let mut queue = BudgetQueue::<u64>::new(&budget);
queue.push_back(11).unwrap();
queue.push_back(22).unwrap();
let mut queue = BudgetVec::<u64>::new(&budget, RuntimeResource::AuxiliaryBytes);
queue.push(11).unwrap();
queue.push(22).unwrap();
assert_eq!(budget.used(AuxiliaryBytes), 16);
assert!(queue.push_back(33).is_err());
assert_eq!(queue.pop_front(), Some(11));
assert!(queue.push(33).is_err());
assert_eq!(queue.pop(), Some(22));
assert_eq!(budget.used(AuxiliaryBytes), 16);
queue.push_back(44).unwrap(); // reuse retained capacity
queue.push(44).unwrap(); // reuse retained capacity
let mut moved = queue;
assert_eq!(budget.used(AuxiliaryBytes), 16);
assert_eq!(moved.pop_front(), Some(22));
assert_eq!(moved.pop_front(), Some(44));
assert_eq!(moved.pop(), Some(44));
assert_eq!(moved.pop(), Some(11));
drop(moved);
assert_eq!(budget.used(AuxiliaryBytes), 0);
assert_eq!(budget.used(TemporaryBytes), 0);
@@ -296,13 +230,13 @@ mod tests {
.lowered(TemporaryBytes, 0)
.unwrap();
let budget = RuntimeBudget::new(limits);
let mut queue = BudgetQueue::<u64>::new(&budget);
queue.push_back(11).unwrap();
let error = queue.push_back(22).unwrap_err();
let mut queue = BudgetVec::<u64>::new(&budget, RuntimeResource::AuxiliaryBytes);
queue.push(11).unwrap();
let error = queue.push(22).unwrap_err();
assert_eq!((error.resource, error.requested), (TemporaryBytes, 8));
assert_eq!(budget.used(AuxiliaryBytes), 8);
assert_eq!(queue.pop_front(), Some(11));
assert_eq!(queue.pop_front(), None);
assert_eq!(queue.pop(), Some(11));
assert_eq!(queue.pop(), None);
assert_eq!(budget.used(TemporaryBytes), 0);
}
@@ -313,16 +247,16 @@ mod tests {
budget.bytes::<u64>(usize::MAX, AuxiliaryBytes).unwrap_err().reason,
ResourceReason::SizeOverflow
);
let mut queue = BudgetQueue::<u64>::new(&budget);
queue.push_back(11).unwrap();
let mut queue = BudgetVec::<u64>::new(&budget, RuntimeResource::AuxiliaryBytes);
queue.push(11).unwrap();
assert_eq!(queue.reserve(usize::MAX).unwrap_err().reason, ResourceReason::SizeOverflow);
assert_eq!(budget.used(AuxiliaryBytes), 8);
assert_eq!(queue.pop_front(), Some(11));
assert_eq!(queue.pop(), Some(11));
}
}
/// Contiguous execution storage. The capacity reservation travels with the buffer
/// when a coroutine suspends/resumes, and is refunded only when storage is dropped.
/// across ordinary calls; charges are refunded only when storage is dropped.
#[derive(Debug)]
pub struct BudgetVec<T> {
data: Vec<T>,
@@ -440,13 +374,6 @@ impl<T> BudgetVec<T> {
pub(crate) fn native_result_buffer(&mut self) -> &mut Vec<T> {
&mut self.data
}
#[cfg(test)]
pub(crate) fn fixture(data: Vec<T>) -> Self {
let budget = RuntimeBudget::default();
let bytes = budget.bytes::<T>(data.capacity(), RuntimeResource::AuxiliaryBytes).unwrap();
let charge = budget.reserve(RuntimeResource::AuxiliaryBytes, bytes).unwrap();
Self { data, charge }
}
}
impl<T> std::ops::Deref for BudgetVec<T> {
type Target = [T];
-184
View File
@@ -1,184 +0,0 @@
use crate::resource_budget::{BudgetQueue, ResourceFailure, RuntimeBudget};
use prometeu_bytecode::HeapRef;
/// Deterministic cooperative scheduler core.
///
/// Policy:
/// - FIFO for ready coroutines.
/// - Sleeping coroutines are ordered by `wake_tick` and moved to ready when `wake_tick <= current_tick`.
/// - No randomness, no preemption, no context switching here.
#[derive(Debug)]
pub struct Scheduler {
/// Queue of runnable coroutines (FIFO)
ready_queue: BudgetQueue<HeapRef>,
/// Sleeping list kept sorted by (wake_tick, insertion_order)
sleeping: BudgetQueue<SleepEntry>,
/// Currently selected coroutine (purely informational here)
current: Option<HeapRef>,
/// Monotonic counter to preserve deterministic order for same wake_tick
next_seq: u64,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
struct SleepEntry {
wake_tick: u64,
seq: u64,
coro: HeapRef,
}
impl Scheduler {
#[cfg(test)]
pub(crate) fn capacity_bytes(&self) -> u64 {
self.ready_queue.capacity_bytes() + self.sleeping.capacity_bytes()
}
#[cfg(test)]
pub fn new() -> Self {
Self::with_budget(&RuntimeBudget::default())
}
pub fn with_budget(budget: &RuntimeBudget) -> Self {
Self {
ready_queue: BudgetQueue::new(budget),
sleeping: BudgetQueue::new(budget),
current: None,
next_seq: 0,
}
}
pub fn reserve_ready(&mut self) -> Result<(), ResourceFailure> {
self.ready_queue.reserve(1)
}
// ---------- Ready queue operations ----------
/// Enqueue a coroutine to the ready FIFO.
pub fn enqueue_ready(&mut self, coro: HeapRef) -> Result<(), ResourceFailure> {
self.ready_queue.push_back(coro)
}
/// Dequeue next ready coroutine (front of FIFO).
pub fn dequeue_next(&mut self) -> Option<HeapRef> {
self.ready_queue.pop_front()
}
#[cfg(test)]
pub fn is_ready_empty(&self) -> bool {
self.ready_queue.is_empty()
}
#[cfg(test)]
pub fn ready_len(&self) -> usize {
self.ready_queue.len()
}
// ---------- Current tracking (no switching here) ----------
pub fn set_current(&mut self, coro: Option<HeapRef>) {
self.current = coro;
}
#[cfg(test)]
pub fn current(&self) -> Option<HeapRef> {
self.current
}
pub fn clear_current(&mut self) {
self.current = None;
}
// ---------- Sleeping operations ----------
/// Put a coroutine to sleep until `wake_tick`.
/// A coroutine is woken when `current_tick >= wake_tick`.
/// The sleeping list is kept stably ordered to guarantee determinism.
pub fn sleep_until(&mut self, coro: HeapRef, wake_tick: u64) -> Result<(), ResourceFailure> {
let entry = SleepEntry { wake_tick, seq: self.next_seq, coro };
let idx =
self.sleeping.partition_point(|e| (e.wake_tick, e.seq) <= (entry.wake_tick, entry.seq));
self.sleeping.insert(idx, entry)?;
self.next_seq = self.next_seq.wrapping_add(1);
Ok(())
}
/// Reserve the destination before removing any sleeping entries. A failed
/// transfer preserves both queues and never loses a runnable coroutine.
pub fn wake_ready(&mut self, current_tick: u64) -> Result<(), ResourceFailure> {
let split = self.sleeping.partition_point(|e| e.wake_tick <= current_tick);
self.ready_queue.reserve(split)?;
for _ in 0..split {
let entry = self.sleeping.pop_front().expect("validated sleeping prefix");
self.ready_queue.push_back(entry.coro)?;
}
Ok(())
}
/// Returns true if there are any sleeping coroutines.
pub fn has_sleeping(&self) -> bool {
!self.sleeping.is_empty()
}
}
#[cfg(test)]
mod tests {
use super::*;
fn hr(id: u32) -> HeapRef {
HeapRef { index: id, generation: 1 }
}
#[test]
fn fifo_ready_queue_is_deterministic() {
let mut s = Scheduler::new();
s.enqueue_ready(hr(1)).unwrap();
s.enqueue_ready(hr(2)).unwrap();
s.enqueue_ready(hr(3)).unwrap();
assert_eq!(s.ready_len(), 3);
assert_eq!(s.dequeue_next(), Some(hr(1)));
assert_eq!(s.dequeue_next(), Some(hr(2)));
assert_eq!(s.dequeue_next(), Some(hr(3)));
assert_eq!(s.dequeue_next(), None);
}
#[test]
fn sleeping_wake_is_stable_and_fifo_by_insertion() {
let mut s = Scheduler::new();
s.sleep_until(hr(10), 5).unwrap(); // first with wake at 5
s.sleep_until(hr(11), 5).unwrap(); // second with same wake
s.sleep_until(hr(12), 6).unwrap(); // later wake
// Before tick 5: nothing wakes
s.wake_ready(4).unwrap();
assert!(s.is_ready_empty());
// At tick 5: first two wake in insertion order
s.wake_ready(5).unwrap();
assert_eq!(s.dequeue_next(), Some(hr(10)));
assert_eq!(s.dequeue_next(), Some(hr(11)));
assert!(s.is_ready_empty());
// At tick 6: last one wakes
s.wake_ready(6).unwrap();
assert_eq!(s.dequeue_next(), Some(hr(12)));
assert!(s.is_ready_empty());
}
#[test]
fn wake_refusal_preserves_sleepers_and_fifo_order() {
use crate::resource_budget::{RuntimeLimits, RuntimeResource};
let budget = RuntimeBudget::new(
RuntimeLimits::default()
.lowered(RuntimeResource::AuxiliaryBytes, (2 * size_of::<SleepEntry>()) as u64)
.unwrap(),
);
let mut s = Scheduler::with_budget(&budget);
s.sleep_until(hr(1), 4).unwrap();
s.sleep_until(hr(2), 4).unwrap();
let charged = budget.used(RuntimeResource::AuxiliaryBytes);
assert!(s.wake_ready(4).is_err());
assert_eq!(budget.used(RuntimeResource::AuxiliaryBytes), charged);
assert_eq!(budget.used(RuntimeResource::TemporaryBytes), 0);
assert!(s.is_ready_empty());
assert_eq!(s.sleeping.pop_front().unwrap().coro, hr(1));
assert_eq!(s.sleeping.pop_front().unwrap().coro, hr(2));
drop(s);
assert_eq!(budget.used(RuntimeResource::AuxiliaryBytes), 0);
}
}
@@ -103,7 +103,7 @@ impl TypedStorage {
// until every native value is constructed. Count advances only after init.
unsafe {
match self.registry.declarations().types[ty.0 as usize].kind {
TypeKind::Struct(_) | TypeKind::Array(_) => {
TypeKind::Struct(_) | TypeKind::Array(_) | TypeKind::Fn(_) => {
self.data.init(offset, HeapRef::NULL)
}
TypeKind::Trait(_) => self.data.init(
@@ -135,7 +135,7 @@ impl TypedStorage {
// immutable Registry. Only matching typed writes can change its contents.
let result = unsafe {
match self.registry.declarations().types[ty.0 as usize].kind {
TypeKind::Struct(_) | TypeKind::Array(_) => {
TypeKind::Struct(_) | TypeKind::Array(_) | TypeKind::Fn(_) => {
let r = *self.data.get::<HeapRef>(offset);
ValueGroup::new(&[if r.is_null() { Value::Null } else { Value::HeapRef(r) }])
}
@@ -205,12 +205,13 @@ impl TypedStorage {
// &mut self gives exclusive access. Native assignment drops exactly once.
unsafe {
match (&self.registry.declarations().types[ty.0 as usize].kind, values) {
(TypeKind::Struct(_) | TypeKind::Array(_), [Value::Null]) => {
(TypeKind::Struct(_) | TypeKind::Array(_) | TypeKind::Fn(_), [Value::Null]) => {
self.data.replace(offset, HeapRef::NULL)
}
(TypeKind::Struct(_) | TypeKind::Array(_), [Value::HeapRef(r)]) => {
self.data.replace(offset, *r)
}
(
TypeKind::Struct(_) | TypeKind::Array(_) | TypeKind::Fn(_),
[Value::HeapRef(r)],
) => self.data.replace(offset, *r),
(TypeKind::Trait(_), [Value::Null, Value::Null]) => self.data.replace(
offset,
TraitSlot { receiver: HeapRef::NULL, implementation: 0, padding: 0 },
@@ -67,6 +67,11 @@ pub(crate) fn validate(
}
_ => false,
},
TypeKind::Fn(_) => match &values[0] {
Value::Null => true,
Value::HeapRef(r) if !r.is_null() => heap.closure_type(*r)? == type_id,
_ => false,
},
TypeKind::Trait(_) => return validate_trait(registry, heap, type_id, values),
TypeKind::Builtin(B::DYNAMIC) => return validate_dynamic(registry, heap, values),
TypeKind::Builtin(id) => match (*id, values) {
File diff suppressed because it is too large Load Diff
File diff suppressed because it is too large Load Diff
@@ -0,0 +1,291 @@
//! Typed callable boundaries: validate and reserve before consuming any owner.
use super::*;
use crate::value_contract::{self, ValueError};
use prometeu_bytecode::registry::{FunctionId, Signature, TypeId, TypeKind};
impl VirtualMachine {
pub(super) fn execute_callable(
&mut self,
op: OpCode,
a: u32,
b: u32,
pc: u32,
) -> Result<(), LogicalFrameEndingReason> {
let image = self
.validated_image
.clone()
.ok_or_else(|| self.value_trap(ValueError::Type, op, pc))?;
let registry = image.registry();
let width = match op {
OpCode::MakeClosure => {
registry.function_layout(FunctionId(a)).map_or(0, |f| u64::from(f.capture_slots))
}
OpCode::GetCapture => self
.call_stack
.last()
.and_then(|f| registry.function_layout(FunctionId(f.func_idx as u32)))
.and_then(|f| f.captures.get(a as usize))
.map_or(0, |c| u64::from(c.slots)),
_ => 0,
};
let cost = op.cycles().checked_add(width).ok_or_else(|| {
self.resource_trap(
self.budget.failure(
RuntimeResource::TemporaryBytes,
crate::resource_budget::ResourceReason::SizeOverflow,
u64::MAX,
),
op,
pc,
)
})?;
self.cycles += cost;
let end = self.operand_stack.len();
match op {
OpCode::MakeClosure => {
let target = registry
.declarations()
.functions
.get(a as usize)
.ok_or_else(|| self.value_trap(ValueError::Type, op, pc))?;
let TypeKind::Fn(signature) = &registry
.declarations()
.types
.get(b as usize)
.ok_or_else(|| self.value_trap(ValueError::Type, op, pc))?
.kind
else {
return Err(self.value_trap(ValueError::Type, op, pc));
};
if !signature.same_types(&target.signature) {
return Err(self.value_trap(ValueError::Type, op, pc));
}
let layout = registry.function_layout(FunctionId(a)).unwrap();
let count = layout.capture_slots as usize;
self.callable_stack_check(count, op, pc)?;
let base = end - count;
for capture in &layout.captures {
let start = base + capture.slot_offset as usize;
value_contract::validate(
registry,
&self.heap,
capture.type_id,
&self.operand_stack[start..start + capture.slots as usize],
)
.map_err(|e| self.value_trap(e, op, pc))?;
}
let growth = self
.operand_stack
.prepare_growth(usize::from(count == 0))
.map_err(|e| self.resource_trap(e, op, pc))?;
let instance = self
.heap
.alloc_typed_closure(a, TypeId(b), &self.operand_stack[base..])
.map_err(|e| self.resource_trap(e, op, pc))?;
self.operand_stack.commit_growth(growth);
self.operand_stack.truncate(base);
self.operand_stack
.push(Value::HeapRef(instance))
.expect("reserved callable result");
}
OpCode::GetCapture => {
let frame = self
.call_stack
.last()
.ok_or_else(|| self.value_trap(ValueError::Type, op, pc))?;
let owner =
frame.closure.ok_or_else(|| self.value_trap(ValueError::Type, op, pc))?;
let capture = registry
.function_layout(FunctionId(frame.func_idx as u32))
.and_then(|f| f.captures.get(a as usize))
.ok_or_else(|| self.value_trap(ValueError::Type, op, pc))?;
let range =
capture.slot_offset as usize..(capture.slot_offset + capture.slots) as usize;
let values = self
.heap
.closure_env_slice(owner)
.and_then(|env| env.get(range))
.ok_or_else(|| self.value_trap(ValueError::Type, op, pc))?;
value_contract::validate(registry, &self.heap, capture.type_id, values)
.map_err(|e| self.value_trap(e, op, pc))?;
// Every logical stored group has at most three slots; clone owners before growth.
let values = crate::value_contract::ValueGroup::new(values);
let growth = self
.operand_stack
.prepare_growth(capture.slots as usize)
.map_err(|e| self.resource_trap(e, op, pc))?;
self.operand_stack.commit_growth(growth);
self.operand_stack
.extend_from_slice(values.as_slice())
.expect("reserved capture group");
}
OpCode::CallClosure => {
let ty = TypeId(a);
let decl = registry
.declarations()
.types
.get(a as usize)
.ok_or_else(|| self.value_trap(ValueError::Type, op, pc))?;
let TypeKind::Fn(signature) = &decl.kind else {
return Err(self.value_trap(ValueError::Type, op, pc));
};
let p = registry.type_layout(ty).unwrap().callable.as_ref().unwrap().parameter_slots
as usize;
self.callable_stack_check(p + 1, op, pc)?;
let closure = match self.operand_stack[end - 1] {
Value::Null => return Err(self.value_trap(ValueError::NullReference, op, pc)),
Value::HeapRef(r) => r,
_ => return Err(self.value_trap(ValueError::Type, op, pc)),
};
value_contract::validate(registry, &self.heap, ty, &self.operand_stack[end - 1..])
.map_err(|e| self.value_trap(e, op, pc))?;
let target = self
.heap
.closure_fn_id(closure)
.ok_or_else(|| self.value_trap(ValueError::Type, op, pc))?
as usize;
let declaration = registry
.declarations()
.functions
.get(target)
.ok_or_else(|| self.value_trap(ValueError::Type, op, pc))?;
if !signature.same_types(&declaration.signature) {
return Err(self.value_trap(ValueError::Type, op, pc));
}
let layout = registry.function_layout(FunctionId(target as u32)).unwrap();
if self.heap.closure_env_slice(closure).map(|v| v.len())
!= Some(layout.capture_slots as usize)
{
return Err(self.value_trap(ValueError::Type, op, pc));
}
let base = end - p - 1;
self.check_signature_group(target, false, &self.operand_stack[base..end - 1])
.map_err(|(_, e)| self.value_trap(e, op, pc))?;
self.install_callable_frame(target, base, Some(closure), 1, false, op, pc)?;
}
OpCode::CallTrait => {
let TypeKind::Trait(methods) = &registry
.declarations()
.types
.get(a as usize)
.ok_or_else(|| self.value_trap(ValueError::Type, op, pc))?
.kind
else {
return Err(self.value_trap(ValueError::Type, op, pc));
};
let method = methods
.get(b as usize)
.ok_or_else(|| self.value_trap(ValueError::Type, op, pc))?;
let p = registry.type_layout(TypeId(a)).unwrap().methods[b as usize].parameter_slots
as usize;
self.callable_stack_check(p + 2, op, pc)?;
let view = &self.operand_stack[end - 2..];
value_contract::validate(registry, &self.heap, TypeId(a), view)
.map_err(|e| self.value_trap(e, op, pc))?;
if matches!(view, [Value::Null, Value::Null]) {
return Err(self.value_trap(ValueError::NullReference, op, pc));
}
let implementation = value_contract::u32_carrier(&view[1])
.map_err(|e| self.value_trap(e, op, pc))?;
let target = registry.declarations().implementations[implementation as usize]
.methods[b as usize]
.0 as usize;
if !registry.declarations().functions[target].captures.is_empty() {
return Err(self.value_trap(ValueError::Type, op, pc));
}
let base = end - p - 2;
self.check_callable_parameters(
&method.signature,
&self.operand_stack[base..end - 2],
op,
pc,
)?;
self.install_callable_frame(target, base, None, 1, true, op, pc)?;
}
_ => unreachable!(),
}
Ok(())
}
fn callable_stack_check(
&self,
count: usize,
op: OpCode,
pc: u32,
) -> Result<(), LogicalFrameEndingReason> {
if self.temporary_slots() < count {
Err(self.trap(
TRAP_STACK_UNDERFLOW,
op as u16,
"Callable argument underflow".into(),
pc,
))
} else {
Ok(())
}
}
fn check_callable_parameters(
&self,
signature: &Signature,
values: &[Value],
op: OpCode,
pc: u32,
) -> Result<(), LogicalFrameEndingReason> {
let registry = self.validated_image.as_ref().unwrap().registry();
let mut at = 0;
for parameter in &signature.parameters {
let width = registry.type_layout(parameter.type_id).unwrap().storage.slots as usize;
value_contract::validate(
registry,
&self.heap,
parameter.type_id,
&values[at..at + width],
)
.map_err(|e| self.value_trap(e, op, pc))?;
at += width;
}
Ok(())
}
fn install_callable_frame(
&mut self,
target: usize,
base: usize,
closure: Option<HeapRef>,
discard: usize,
receiver_last: bool,
op: OpCode,
pc: u32,
) -> Result<(), LogicalFrameEndingReason> {
self.check_call_depth().map_err(|e| self.resource_trap(e, op, pc))?;
let function = &self.program.functions[target];
let locals = function.local_slots as usize;
let code = function.code_offset as usize;
let stack_growth = self
.operand_stack
.prepare_growth(locals.saturating_sub(discard))
.map_err(|e| self.resource_trap(e, op, pc))?;
let frame_growth =
self.call_stack.prepare_growth(1).map_err(|e| self.resource_trap(e, op, pc))?;
self.operand_stack.commit_growth(stack_growth);
self.call_stack.commit_growth(frame_growth);
self.operand_stack.truncate(self.operand_stack.len() - discard);
if receiver_last {
self.operand_stack[base..].rotate_right(1);
}
for _ in 0..locals {
self.operand_stack.push(Value::Null).expect("reserved locals");
}
self.call_stack
.push(CallFrame {
return_pc: self.pc as u32,
stack_base: base,
func_idx: target,
closure,
})
.expect("reserved call frame");
self.pc = code;
Ok(())
}
}
@@ -0,0 +1,333 @@
use super::*;
#[path = "../../tests/support/callables.rs"]
mod support;
use support::*;
fn session(
bodies: &[(
&str,
prometeu_bytecode::registry::Signature,
Vec<prometeu_bytecode::registry::TypeId>,
)],
limits: RuntimeLimits,
) -> VirtualMachine {
let mut v = VirtualMachine::from_image(image(bodies, vec![]).unwrap(), limits);
v.prepare_boot_call().unwrap();
v
}
#[test]
fn fn_creation_identity_aliasing_and_capture_order() {
let mut v = vm(&[
(
"PUSH_I32 11\nPUSH_I32 22\nMAKE_CLOSURE fn=1,type=4\nDUP\nSET_GLOBAL 0\nSET_GLOBAL 1\nPUSH_I32 11\nPUSH_I32 22\nMAKE_CLOSURE fn=1,type=4\nSET_GLOBAL 2\nGET_GLOBAL 0\nCALL_CLOSURE 4\nRET",
sig(&[], &[0]),
vec![],
),
(
"GET_CAPTURE 0\nGET_CAPTURE 1\nSUB\nRET",
sig(&[], &[0]),
vec![prometeu_bytecode::registry::TypeId(0); 2],
),
]);
assert_eq!(run(&mut v, 1000).reason, LogicalFrameEndingReason::EndOfRom);
assert_eq!(v.operand_stack_top(1), vec![Value::Int32(-11)]);
assert_eq!(v.globals[0], v.globals[1]);
assert_ne!(v.globals[0], v.globals[2]);
}
#[test]
fn multi_slot_capture_is_one_logical_group() {
let mut v = vm(&[
(
"PUSH_F64 f64:0x3ff0000000000000\nPUSH_F64 f64:0x4000000000000000\nMAKE_CLOSURE fn=1,type=13\nCALL_CLOSURE 13\nRET",
sig(&[], &[2]),
vec![],
),
("GET_CAPTURE 0\nRET", sig(&[], &[2]), vec![prometeu_bytecode::registry::TypeId(2)]),
]);
let r = run(&mut v, 1000);
assert_eq!(r.reason, LogicalFrameEndingReason::EndOfRom);
assert_eq!(v.operand_stack_top(2), vec![Value::Float(2.), Value::Float(1.)]);
// 2 pushes + (8+2) creation + 6 call + (2+2) capture + two returns.
assert_eq!(r.cycles_used, 2 * OpCode::PushF64.cycles() + 10 + 6 + 4 + 8);
}
#[test]
fn callable_budget_zero_preserves_state_and_positive_slice_finishes_one_instruction() {
let mut v = vm(&[
(
"PUSH_F64 f64:0x3ff0000000000000\nPUSH_F64 f64:0x4000000000000000\nMAKE_CLOSURE fn=1,type=13\nCALL_CLOSURE 13\nRET",
sig(&[], &[2]),
vec![],
),
("GET_CAPTURE 0\nRET", sig(&[], &[2]), vec![prometeu_bytecode::registry::TypeId(2)]),
]);
for _ in 0..2 {
v.step(&mut Native, &mut HostContext::new(None)).unwrap();
}
// Creation, indirect call and complete-group capture are each atomic even
// when their cost exceeds the remaining positive slice.
for cost in [10, 6, 4] {
let before = (
v.pc,
v.cycles,
v.operand_stack.as_slice().to_vec(),
v.call_stack.len(),
v.heap.allocation_count(),
);
let zero = run(&mut v, 0);
assert_eq!((zero.cycles_used, zero.steps_executed), (0, 0));
assert_eq!(zero.reason, LogicalFrameEndingReason::BudgetExhausted);
assert_eq!(
(
v.pc,
v.cycles,
v.operand_stack.as_slice().to_vec(),
v.call_stack.len(),
v.heap.allocation_count()
),
before
);
let one = run(&mut v, 1);
assert_eq!((one.cycles_used, one.steps_executed), (cost, 1));
assert_eq!(one.reason, LogicalFrameEndingReason::BudgetExhausted);
}
assert_eq!(run(&mut v, 100).reason, LogicalFrameEndingReason::EndOfRom);
assert_eq!(v.operand_stack_top(2), vec![Value::Float(2.), Value::Float(1.)]);
}
#[test]
fn closure_call_depth_failure_preserves_fn_and_charges_once() {
let mut v = session(
&[
("MAKE_CLOSURE fn=1,type=9\nCALL_CLOSURE 9\nRET", sig(&[], &[]), vec![]),
("RET", sig(&[], &[]), vec![]),
],
RuntimeLimits::default().lowered(RuntimeResource::CallDepth, 1).unwrap(),
);
v.step(&mut Native, &mut HostContext::new(None)).unwrap();
let sources = v.operand_stack.as_slice().to_vec();
let before = v.cycles;
let result = v.step(&mut Native, &mut HostContext::new(None));
assert!(matches!(result,Err(LogicalFrameEndingReason::Trap(t)) if t.code==TRAP_RESOURCE_LIMIT));
assert_eq!(v.cycles - before, 6);
assert_eq!(v.call_stack.len(), 1);
assert_eq!(v.operand_stack.as_slice(), sources);
}
#[test]
fn null_and_stale_fn_calls_trap_without_consuming_source() {
for value in [Value::Null, Value::HeapRef(HeapRef { index: 99, generation: 1 })] {
let mut v = vm(&[("GET_GLOBAL 0\nCALL_CLOSURE 4\nRET", sig(&[], &[0]), vec![])]);
v.globals.push(value.clone()).unwrap();
v.step(&mut Native, &mut HostContext::new(None)).unwrap();
let before = v.cycles;
assert!(
matches!(v.step(&mut Native,&mut HostContext::new(None)),Err(LogicalFrameEndingReason::Trap(t)) if t.code==TRAP_NULL_REFERENCE || t.code==TRAP_INVALID_HANDLE)
);
assert_eq!(v.cycles - before, 6);
assert_eq!(v.operand_stack.last(), Some(&value));
}
}
#[test]
fn closure_quota_refusal_keeps_captures_and_owners() {
for resource in [RuntimeResource::HandleSlots, RuntimeResource::GuestBytes] {
let mut v = session(
&[
("PUSH_I32 7\nMAKE_CLOSURE fn=1,type=4\nPOP\nRET", sig(&[], &[]), vec![]),
(
"GET_CAPTURE 0\nRET",
sig(&[], &[0]),
vec![prometeu_bytecode::registry::TypeId(0)],
),
],
RuntimeLimits::default().lowered(resource, 0).unwrap(),
);
v.step(&mut Native, &mut HostContext::new(None)).unwrap();
let before = v.cycles;
let sources = v.operand_stack.as_slice().to_vec();
assert!(
matches!(v.step(&mut Native,&mut HostContext::new(None)),Err(LogicalFrameEndingReason::Trap(t)) if t.code==TRAP_RESOURCE_LIMIT)
);
assert_eq!(v.cycles - before, 9);
assert_eq!(v.operand_stack.as_slice(), sources);
assert_eq!(v.heap.allocation_count(), 0);
}
}
#[test]
fn closure_temporary_growth_refusal_preserves_capture() {
let mut v = vm(&[
(
"MAKE_CLOSURE fn=2,type=4\nPOP\nPUSH_I32 7\nMAKE_CLOSURE fn=1,type=4\nPOP\nRET",
sig(&[], &[]),
vec![],
),
("GET_CAPTURE 0\nRET", sig(&[], &[0]), vec![prometeu_bytecode::registry::TypeId(0)]),
("PUSH_I32 0\nRET", sig(&[], &[0]), vec![]),
]);
for _ in 0..3 {
v.step(&mut Native, &mut HostContext::new(None)).unwrap();
}
v.budget.test_lower_limit(RuntimeResource::TemporaryBytes, 0);
let sources = v.operand_stack.as_slice().to_vec();
let count = v.heap.allocation_count();
let before = v.cycles;
assert!(
matches!(v.step(&mut Native,&mut HostContext::new(None)),Err(LogicalFrameEndingReason::Trap(t)) if t.code==TRAP_RESOURCE_LIMIT)
);
assert_eq!(v.cycles - before, 9);
assert_eq!(v.operand_stack.as_slice(), sources);
assert_eq!(v.heap.allocation_count(), count);
assert_eq!(v.budget.used(RuntimeResource::TemporaryBytes), 0);
}
#[test]
fn root_return_gc_roots_fn_result_before_collecting() {
let mut v = vm(&[
("PUSH_I32 55\nMAKE_CLOSURE fn=1,type=4\nRET", sig(&[], &[4]), vec![]),
("GET_CAPTURE 0\nRET", sig(&[], &[0]), vec![prometeu_bytecode::registry::TypeId(0)]),
]);
v.gc_alloc_threshold = 1;
assert_eq!(run(&mut v, 1000).reason, LogicalFrameEndingReason::EndOfRom);
assert_eq!(v.heap.len(), 1);
assert_eq!(v.call_stack.len(), 0);
let Value::HeapRef(owner) = v.operand_stack[0] else { panic!() };
assert!(v.heap.is_valid(owner));
assert_eq!(v.heap.closure_env_slice(owner).unwrap(), &[Value::Int32(55)]);
}
#[test]
fn unreachable_closure_cell_cycle_is_collected_at_sync() {
let mut v = vm(&[
(
"STRUCT_NEW 15\nDUP\nMAKE_CLOSURE fn=1,type=4\nSTRUCT_SET type=15,field=0\nFRAME_SYNC\nRET",
sig(&[], &[]),
vec![],
),
("PUSH_I32 1\nRET", sig(&[], &[0]), vec![prometeu_bytecode::registry::TypeId(15)]),
]);
v.gc_alloc_threshold = 1;
assert_eq!(run(&mut v, 1000).reason, LogicalFrameEndingReason::FrameSync);
assert_eq!(v.heap.allocation_count(), 2);
assert_eq!(v.heap.len(), 0);
assert_eq!(v.budget.used(RuntimeResource::GuestBytes), 0);
}
#[test]
fn mixed_trait_dynamic_string_vec2_captures_survive_sync_and_root_return() {
use prometeu_bytecode::registry::*;
let root = "STRUCT_NEW 5\nREF_TO_TRAIT source=5,target=7\nPUSH_F64 f64:0x3ff0000000000000\nPUSH_F64 f64:0x4000000000000000\nDYN_PACK 2\nPUSH_CONST 0\nPUSH_F64 f64:0x4008000000000000\nPUSH_F64 f64:0x4010000000000000\nMAKE_CLOSURE fn=1,type=17\nCALL_CLOSURE 17\nRET";
let bodies = [
(root, sig(&[], &[7, 11, 3, 2]), vec![]),
(
"FRAME_SYNC\nGET_CAPTURE 0\nGET_CAPTURE 1\nGET_CAPTURE 2\nGET_CAPTURE 3\nRET",
sig(&[], &[7, 11, 3, 2]),
vec![TypeId(7), TypeId(11), TypeId(3), TypeId(2)],
),
("PUSH_I32 0\nRET", sig(&[5], &[0]), vec![]),
];
let implementation =
ImplementationDecl { owner: TypeId(5), trait_id: TypeId(7), methods: vec![FunctionId(2)] };
let image = image_constants(
&bodies,
vec![implementation],
&[prometeu_bytecode::model::ConstantPoolEntry::String("native capture".into())],
)
.unwrap();
let mut v = VirtualMachine::from_image(image, RuntimeLimits::default());
v.prepare_boot_call().unwrap();
v.gc_alloc_threshold = 1;
assert_eq!(run(&mut v, 1000).reason, LogicalFrameEndingReason::FrameSync);
assert_eq!(v.heap.len(), 3);
assert_eq!(run(&mut v, 1000).reason, LogicalFrameEndingReason::EndOfRom);
let values = v.operand_stack.as_slice();
assert_eq!(values.len(), 7);
assert_eq!(values[4], Value::string("native capture"));
assert_eq!(values[5..], [Value::Float(3.), Value::Float(4.)]);
let registry = v.validated_image.as_ref().unwrap().registry();
crate::value_contract::validate(registry, &v.heap, TypeId(7), &values[..2]).unwrap();
crate::value_contract::validate(registry, &v.heap, TypeId(11), &values[2..4]).unwrap();
}
#[test]
fn fn_snapshot_is_not_a_guest_root_or_an_import_authority() {
use prometeu_bytecode::registry::TypeId;
let mut v = vm(&[
("MAKE_CLOSURE fn=1,type=4\nRET", sig(&[], &[4]), vec![]),
("PUSH_I32 73\nRET", sig(&[], &[0]), vec![]),
("RET", sig(&[], &[]), vec![]),
]);
v.gc_alloc_threshold = 1;
assert_eq!(run(&mut v, 1000).reason, LogicalFrameEndingReason::EndOfRom);
let snapshot = v.operand_stack_top(1);
let Value::HeapRef(owner) = snapshot[0] else { panic!() };
v.prepare_call("2").unwrap();
v.heap.alloc_typed_closure(1, TypeId(4), &[]).unwrap();
assert_eq!(run(&mut v, 1000).reason, LogicalFrameEndingReason::EndOfRom);
assert!(!v.heap.is_valid(owner));
let other =
image(&[("GET_LOCAL 0\nCALL_CLOSURE 4\nRET", sig(&[4], &[0]), vec![])], vec![]).unwrap();
let mut other = VirtualMachine::from_image(other, RuntimeLimits::default());
assert!(matches!(
other.prepare_call_with_args("0", &snapshot),
Err(VmInitError::EntrypointArgumentsInvalid { trap_code: TRAP_INVALID_HANDLE, .. })
));
assert_eq!(other.call_stack.len(), 0);
}
#[test]
fn malformed_trait_views_trap_once_and_preserve_sources() {
use prometeu_bytecode::registry::*;
let bodies = [
("GET_GLOBAL 0\nGET_GLOBAL 1\nCALL_TRAIT type=7,method=0\nRET", sig(&[], &[0]), vec![]),
("PUSH_I32 1\nRET", sig(&[5], &[0]), vec![]),
];
let implementation =
ImplementationDecl { owner: TypeId(5), trait_id: TypeId(7), methods: vec![FunctionId(1)] };
let image = image(&bodies, vec![implementation]).unwrap();
for case in 0..5 {
let mut v = VirtualMachine::from_image(image.clone(), RuntimeLimits::default());
v.prepare_boot_call().unwrap();
let wrong = v.heap.allocate_typed_struct(image.registry().clone(), TypeId(8)).unwrap();
let (values, expected) = match case {
0 => ([Value::Null, Value::Null], TRAP_NULL_REFERENCE),
1 => (
[Value::HeapRef(HeapRef { index: 99, generation: 1 }), Value::Int64(0)],
TRAP_INVALID_HANDLE,
),
2 => ([Value::HeapRef(wrong), Value::Int64(0)], TRAP_TYPE),
3 => ([Value::Null, Value::Int64(99)], TRAP_TYPE),
_ => ([Value::HeapRef(wrong), Value::Int32(0)], TRAP_TYPE),
};
v.globals.extend_from_slice(&values).unwrap();
for _ in 0..2 {
v.step(&mut Native, &mut HostContext::new(None)).unwrap();
}
let sources = v.operand_stack.as_slice().to_vec();
let before = v.cycles;
assert!(
matches!(v.step(&mut Native,&mut HostContext::new(None)),Err(LogicalFrameEndingReason::Trap(t)) if t.code==expected)
);
assert_eq!(v.cycles - before, 6);
assert_eq!(v.operand_stack.as_slice(), sources);
assert_eq!(v.call_stack.len(), 1);
}
}
#[test]
fn recursive_fn_calls_use_bounded_ordinary_frames() {
let mut v = session(
&[
("MAKE_CLOSURE fn=1,type=9\nCALL_CLOSURE 9\nRET", sig(&[], &[]), vec![]),
("MAKE_CLOSURE fn=1,type=9\nCALL_CLOSURE 9\nRET", sig(&[], &[]), vec![]),
],
RuntimeLimits::default().lowered(RuntimeResource::CallDepth, 4).unwrap(),
);
assert!(
matches!(run(&mut v,1000).reason,LogicalFrameEndingReason::Trap(t) if t.code==TRAP_RESOURCE_LIMIT && t.opcode==0x53)
);
assert_eq!(v.call_stack.len(), 4);
}
@@ -51,11 +51,8 @@ fn new_attempt_costs_budget_and_transactional_refusal() {
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);
assert_eq!(vm.budget.used(RuntimeResource::GuestBytes), 0);
assert_eq!(vm.budget.used(RuntimeResource::HandleSlots), 0);
}
let mut vm = vm("PUSH_I64 10\nARRAY_NEW 12\nHALT", RuntimeLimits::default());
vm.step(&mut Native, &mut HostContext::new(None)).unwrap();
@@ -208,6 +205,9 @@ fn provisional_allocation_and_handle_refusals_publish_nothing() {
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.
if quota == RuntimeResource::TemporaryBytes {
v.heap.allocate_object(crate::object::ObjectKind::Bytes, &[]).unwrap();
}
let current = v.budget.used(quota);
v.budget.test_lower_limit(quota, current);
let guest = v.budget.used(RuntimeResource::GuestBytes);
@@ -234,7 +234,7 @@ fn provisional_allocation_and_handle_refusals_publish_nothing() {
);
assert_eq!(v.budget.used(RuntimeResource::GuestBytes), guest);
assert_eq!(v.operand_stack.as_slice(), &[Value::Int64(10)]);
assert_eq!(v.heap.len(), 1);
assert_eq!(v.heap.len(), 0);
}
#[test]
fn rooted_native_owners_boxes_traits_and_cycles_survive_then_reclaim_at_real_safepoints() {
@@ -268,7 +268,7 @@ fn rooted_native_owners_boxes_traits_and_cycles_survive_then_reclaim_at_real_saf
LogicalFrameEndingReason::FrameSync
);
assert!(!v.heap.is_valid(node));
assert_eq!(v.heap.len(), 1);
assert_eq!(v.heap.len(), 0);
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));
@@ -399,23 +399,18 @@ fn malformed_trait_and_dynamic_stores_reject_the_whole_group() {
}
#[test]
fn legacy_verifier_rejects_every_collection_even_when_unreachable() {
fn typed_loader_rejects_out_of_registry_collections_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",
"STRUCT_NEW 99",
"STRUCT_GET type=99,field=0",
"STRUCT_SET type=99,field=0",
"ARRAY_NEW 99",
"ARRAY_LEN 99",
"ARRAY_GET 99",
"ARRAY_SET 99",
] {
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, .. })
));
assert!(support::load(&code).is_err());
}
}
#[test]
@@ -2,114 +2,33 @@ use super::*;
impl VirtualMachine {
pub(super) fn handle_safepoint(&mut self) -> Result<(), ResourceFailure> {
if self.gc_alloc_threshold > 0 {
let live_now = self.heap.len();
let since_last = live_now.saturating_sub(self.last_gc_live_count);
if since_last >= self.gc_alloc_threshold {
// Parameters/locals are already in the operand buffer. Stream roots
// without a duplicate collection; suspended contexts are scanned by Heap.
let roots = self
.operand_stack
.iter()
.chain(self.globals.iter())
.filter_map(crate::roots::value_heap_ref)
.chain(self.current_coro);
self.heap.mark_session_roots(roots)?;
self.heap.sweep();
self.last_gc_live_count = self.heap.len();
}
if self.gc_alloc_threshold > 0
&& self.heap.len().saturating_sub(self.last_gc_live_count) >= self.gc_alloc_threshold
{
let roots = self
.operand_stack
.iter()
.chain(self.globals.iter())
.filter_map(crate::roots::value_heap_ref)
.chain(self.call_stack.iter().filter_map(|frame| frame.closure));
self.heap.mark_session_roots(roots)?;
self.heap.sweep();
self.last_gc_live_count = self.heap.len();
}
if let Some(strings) = &self.strings {
strings.reconcile();
}
self.current_tick = self.current_tick.wrapping_add(1);
self.scheduler.wake_ready(self.current_tick)?;
let mut switched_out = false;
if let Some(cur) = self.current_coro {
if let Some(wake) = self.sleep_requested_until {
self.scheduler.sleep_until(cur, wake)?;
self.sleep_requested_until = None;
if let Some(co) = self.heap.coroutine_data_mut(cur) {
co.pc = self.pc;
co.stack = self.operand_stack.take();
co.frames = self.call_stack.take();
co.state = CoroutineState::Sleeping;
co.wake_tick = wake;
}
self.current_coro = None;
self.scheduler.clear_current();
switched_out = true;
} else if self.yield_requested {
self.scheduler.enqueue_ready(cur)?;
if let Some(co) = self.heap.coroutine_data_mut(cur) {
co.pc = self.pc;
co.stack = self.operand_stack.take();
co.frames = self.call_stack.take();
co.state = CoroutineState::Ready;
}
self.current_coro = None;
self.scheduler.clear_current();
switched_out = true;
} else if self.halted || self.pc >= self.program.rom.len() {
if let Some(co) = self.heap.coroutine_data_mut(cur) {
co.pc = self.pc;
co.stack = self.operand_stack.take();
co.frames = self.call_stack.take();
co.state = CoroutineState::Finished;
}
self.current_coro = None;
self.scheduler.clear_current();
switched_out = true;
}
}
if self.current_coro.is_none() {
if let Some(next) = self.scheduler.dequeue_next() {
if let Some(co) = self.heap.coroutine_data_mut(next) {
self.pc = co.pc;
self.operand_stack = co.stack.take();
self.call_stack = co.frames.take();
co.state = CoroutineState::Running;
}
self.current_coro = Some(next);
self.scheduler.set_current(self.current_coro);
} else if switched_out && !self.scheduler.has_sleeping() {
self.halted = true;
}
} else {
self.scheduler.set_current(self.current_coro);
}
self.yield_requested = false;
Ok(())
}
pub fn visit_roots<V: RootVisitor + ?Sized>(&self, visitor: &mut V) {
for value in &self.operand_stack {
for value in self.operand_stack.iter().chain(self.globals.iter()) {
visit_value_for_roots(value, visitor);
}
for frame in &self.call_stack {
if let Some(func_meta) = self.program.functions.get(frame.func_idx) {
let start = frame.stack_base;
let frame_slots =
(func_meta.param_slots as usize) + (func_meta.local_slots as usize);
let mut end = start.saturating_add(frame_slots);
if end > self.operand_stack.len() {
end = self.operand_stack.len();
}
for index in start..end {
if let Some(value) = self.operand_stack.get(index) {
visit_value_for_roots(value, visitor);
}
}
if let Some(closure) = frame.closure {
visitor.visit_heap_ref(closure);
}
}
for global in &self.globals {
visit_value_for_roots(global, visitor);
}
}
}
@@ -1,128 +1,15 @@
use super::*;
fn patch_module_hostcalls(
module: &mut BytecodeModule,
capabilities: prometeu_hal::syscalls::CapFlags,
) -> Result<(), LoaderPatchError> {
let resolved =
prometeu_hal::syscalls::resolve_declared_program_syscalls(&module.syscalls, capabilities)
.map_err(LoaderPatchError::ResolveFailed)?;
let mut used = vec![false; module.syscalls.len()];
let mut pc = 0usize;
while pc < module.code.len() {
let instr = decode_next(pc, &module.code).map_err(LoaderPatchError::DecodeFailed)?;
let next_pc = instr.next_pc;
match instr.opcode {
OpCode::Hostcall => {
let sysc_index = instr.imm_u32().map_err(LoaderPatchError::DecodeFailed)?;
let Some(resolved_syscall) = resolved.get(sysc_index as usize) else {
return Err(LoaderPatchError::HostcallIndexOutOfBounds {
pc,
sysc_index,
syscalls_len: resolved.len(),
});
};
used[sysc_index as usize] = true;
module.code[pc..pc + 2].copy_from_slice(&(OpCode::Syscall as u16).to_le_bytes());
module.code[pc + 2..pc + 6].copy_from_slice(&resolved_syscall.id.to_le_bytes());
}
OpCode::Syscall => {
return Err(LoaderPatchError::RawSyscallInPreloadArtifact {
pc,
syscall_id: instr.imm_u32().map_err(LoaderPatchError::DecodeFailed)?,
});
}
_ => {}
}
pc = next_pc;
}
for (index, (was_used, decl)) in used.iter().zip(&module.syscalls).enumerate() {
if !was_used {
return Err(LoaderPatchError::UnusedSyscallDecl {
sysc_index: index as u32,
module: decl.module.clone(),
name: decl.name.clone(),
version: decl.version,
});
}
}
let mut pc = 0usize;
while pc < module.code.len() {
let instr = decode_next(pc, &module.code).map_err(LoaderPatchError::DecodeFailed)?;
if instr.opcode == OpCode::Hostcall {
return Err(LoaderPatchError::HostcallRemaining {
pc,
sysc_index: instr.imm_u32().map_err(LoaderPatchError::DecodeFailed)?,
});
}
pc = instr.next_pc;
}
Ok(())
}
impl VirtualMachine {
/// Load only the bounded sealed-v1 image; failure leaves an empty halted session.
pub fn initialize(&mut self, program_bytes: Vec<u8>) -> Result<(), VmInitError> {
self.program = ProgramImage::default();
self.validated_image = None;
self.strings = None;
self.pc = 0;
self.operand_stack.clear();
self.call_stack.clear();
self.globals.clear();
self.heap = Heap::with_budget(&self.budget);
self.cycles = 0;
self.halted = true;
self.last_gc_live_count = 0;
self.current_tick = 0;
self.sleep_requested_until = None;
self.scheduler = Scheduler::with_budget(&self.budget);
self.current_coro = None;
let program = match prometeu_bytecode::BytecodeLoader::load(&program_bytes) {
Ok(mut module) => {
patch_module_hostcalls(&mut module, self.capabilities)
.map_err(VmInitError::LoaderPatchFailed)?;
let max_stacks = Verifier::verify(&module.code, &module.functions)
.map_err(VmInitError::VerificationFailed)?;
let mut program = ProgramImage::from(module);
let mut functions = program.functions.as_ref().to_vec();
for (func, max_stack) in functions.iter_mut().zip(max_stacks) {
func.max_stack_slots = max_stack;
}
program.functions = std::sync::Arc::from(functions);
program
}
Err(prometeu_bytecode::LoadError::InvalidVersion) => {
return Err(VmInitError::UnsupportedFormat);
}
Err(prometeu_bytecode::LoadError::InvalidMagic) => {
return Err(VmInitError::InvalidFormat);
}
Err(prometeu_bytecode::LoadError::UnexpectedEof) if program_bytes.len() < 32 => {
return Err(VmInitError::InvalidFormat);
}
Err(e) => return Err(VmInitError::ImageLoadFailed(e)),
};
let pc = program
.functions
.first()
.map(|f| f.code_offset as usize)
.ok_or(VmInitError::EntrypointNotFound)?;
self.program = program;
self.pc = pc;
self.halted = false;
let caps = self.capabilities;
let limits = self.budget.limits().clone();
*self = Self::empty(limits.clone());
self.capabilities = caps;
let mut load = prometeu_bytecode::load_limits::LoadBudget::new(Default::default());
let image = crate::ValidatedProgramImage::load(&program_bytes, &mut load, caps)?;
*self = Self::from_image(image, limits);
Ok(())
}
@@ -153,7 +40,11 @@ impl VirtualMachine {
.map(|export| export.func_idx as usize)
.ok_or(VmInitError::EntrypointNotFound)?
} else {
self.program.exports.get(entrypoint).map(|&idx| idx as usize).ok_or(()).unwrap_or(0)
self.program
.exports
.get(entrypoint)
.map(|&idx| idx as usize)
.ok_or(VmInitError::EntrypointNotFound)?
};
self.prepare_call_by_index(func_idx, arguments)
@@ -164,7 +55,28 @@ impl VirtualMachine {
func_idx: usize,
arguments: &[Value],
) -> Result<(), VmInitError> {
#[cfg(not(test))]
if self.validated_image.is_none() {
return Err(VmInitError::EntrypointNotFound);
}
if self.validated_image.is_some() {
if self
.validated_image
.as_ref()
.unwrap()
.registry()
.declarations()
.functions
.get(func_idx)
.is_some_and(|f| !f.captures.is_empty())
{
return Err(prometeu_bytecode::load_limits::LoadFailure::new(
prometeu_bytecode::load_limits::LoadCode::InvalidEntrypoint,
prometeu_bytecode::load_limits::LoadReason::CapturedDirectCall,
)
.in_function(func_idx as u32, None)
.into());
}
self.check_signature_group(func_idx, false, arguments).map_err(|(slot, error)| {
if self.program.functions.get(func_idx).is_none() {
VmInitError::EntrypointNotFound
@@ -192,13 +104,6 @@ impl VirtualMachine {
.prepare_growth(total_slots.saturating_sub(self.operand_stack.len()))?;
let frame_growth =
self.call_stack.prepare_growth(1usize.saturating_sub(self.call_stack.len()))?;
let main_href = self.heap.allocate_coroutine(
callee.code_offset as usize,
CoroutineState::Running,
0,
BudgetVec::new(&self.budget, RuntimeResource::AuxiliaryBytes),
BudgetVec::new(&self.budget, RuntimeResource::AuxiliaryBytes),
)?;
self.operand_stack.commit_growth(stack_growth);
self.call_stack.commit_growth(frame_growth);
self.pc = callee.code_offset as usize;
@@ -223,10 +128,9 @@ impl VirtualMachine {
return_pc: self.program.rom.len() as u32,
stack_base: 0,
func_idx,
closure: None,
})?;
self.current_coro = Some(main_href);
self.scheduler.set_current(self.current_coro);
Ok(())
}
}
@@ -36,6 +36,7 @@ fn function(
max: u32,
) -> FunctionDecl {
FunctionDecl {
captures: vec![],
name: Some(format!("f{offset}")),
code_offset: offset as u32,
code_len: len as u32,
@@ -162,7 +163,7 @@ fn decoded_dynamic_scalar_string_reference_and_null_paths_have_exact_attempt_cos
let mut vm = dynamic_vm(OpCode::DynCanUnpack, target, 2, 1, RuntimeLimits::default());
load_globals_and_step(&mut vm, &[Value::Null, Value::Null]).unwrap();
assert_eq!(vm.operand_stack.as_slice(), &[Value::Boolean(expected)]);
assert_eq!(vm.heap.len(), 1); // Only the entry coroutine, no query allocation.
assert_eq!(vm.heap.len(), 0); // Only the entry coroutine, no query allocation.
}
}
@@ -199,7 +200,7 @@ fn decoded_dynamic_box_roundtrip_and_identity_never_nest_boxes() {
vm.step(&mut Native, &mut HostContext::new(None)).unwrap();
assert_eq!(vm.cycles - before, 4);
assert_eq!(vm.operand_stack.as_slice(), values.as_slice());
assert_eq!(vm.heap.len(), 2);
assert_eq!(vm.heap.len(), 1);
}
}
@@ -231,7 +232,7 @@ fn decoded_trait_box_is_the_only_receiver_root_across_frame_sync_gc() {
));
assert!(vm.heap.is_valid(receiver));
assert!(vm.heap.is_valid(box_handle));
assert_eq!(vm.heap.len(), 3); // Coroutine, immutable box and its receiver.
assert_eq!(vm.heap.len(), 2); // Immutable box and its receiver.
vm.step(&mut Native, &mut HostContext::new(None)).unwrap();
assert_eq!(vm.operand_stack.as_slice(), &[Value::HeapRef(receiver), Value::Int64(0)]);
vm.step(&mut Native, &mut HostContext::new(None)).unwrap();
@@ -244,7 +245,7 @@ fn decoded_trait_box_is_the_only_receiver_root_across_frame_sync_gc() {
));
assert!(!vm.heap.is_valid(receiver));
assert!(!vm.heap.is_valid(box_handle));
assert_eq!(vm.heap.len(), 1);
assert_eq!(vm.heap.len(), 0);
}
#[test]
@@ -274,7 +275,7 @@ fn decoded_box_quota_failure_leaves_unpacked_values_rooted_and_unchanged() {
5,
2,
2,
RuntimeLimits::default().lowered(RuntimeResource::HandleSlots, 1).unwrap(),
RuntimeLimits::default().lowered(RuntimeResource::HandleSlots, 0).unwrap(),
);
let input = [Value::Float(1.), Value::Float(2.)];
let guest_before = vm.budget.used(RuntimeResource::GuestBytes);
@@ -282,7 +283,7 @@ fn decoded_box_quota_failure_leaves_unpacked_values_rooted_and_unchanged() {
matches!(load_globals_and_step(&mut vm,&input),Err(LogicalFrameEndingReason::Trap(info)) if info.code==TRAP_RESOURCE_LIMIT)
);
assert_eq!(vm.operand_stack.as_slice(), &input);
assert_eq!(vm.heap.len(), 1);
assert_eq!(vm.heap.len(), 0);
assert_eq!(vm.budget.used(RuntimeResource::GuestBytes), guest_before);
}
@@ -389,7 +390,7 @@ fn decoded_null_queries_are_false_and_null_conversions_are_absent() {
_ => vec![Value::Null],
};
assert_eq!(vm.operand_stack.as_slice(), expected.as_slice());
assert_eq!(vm.heap.len(), 1);
assert_eq!(vm.heap.len(), 0);
}
}
}
@@ -460,7 +461,7 @@ fn decoded_stale_handle_is_an_invalid_handle_even_when_target_type_differs() {
let mut vm = reference_vm(operation, 9, target);
let registry = vm.validated_image.as_ref().unwrap().registry().clone();
let receiver = vm.heap.allocate_typed_struct(registry, TypeId(9)).unwrap();
vm.heap.mark_from_roots(vm.current_coro).unwrap();
vm.heap.mark_from_roots([]).unwrap();
vm.heap.sweep();
let input = [Value::HeapRef(receiver)];
assert!(
@@ -553,19 +554,26 @@ fn native_string_failures_cannot_publish_partial_results_even_if_handler_ignores
Ok(())
}
}
let mut code = vec![];
arg(&mut code, OpCode::Syscall, prometeu_hal::syscalls::Syscall::SystemHasCart as u32);
let mut vm = VirtualMachine::with_runtime_limits(
code,
vec![],
let code = prometeu_bytecode::assemble("HOSTCALL 0\nHALT").unwrap();
let mut program =
prometeu_test_support::program::TestProgram::single(code, Default::default(), 0, 1);
program.syscalls = vec![prometeu_bytecode::model::SyscallDecl {
module: "system".into(),
name: "has_cart".into(),
version: 1,
arg_slots: 0,
ret_slots: 1,
}];
let image = crate::ValidatedProgramImage::load(
&program.serialize(),
&mut LoadBudget::new(Default::default()),
prometeu_hal::syscalls::caps::SYSTEM,
)
.unwrap();
let mut vm = VirtualMachine::from_image(
image,
RuntimeLimits::default().lowered(RuntimeResource::StringBytes, 2).unwrap(),
);
vm.program.functions = Arc::from(vec![prometeu_bytecode::FunctionMeta {
code_len: 6,
max_stack_slots: 1,
..Default::default()
}]);
vm.set_capabilities(prometeu_hal::syscalls::caps::SYSTEM);
vm.prepare_boot_call().unwrap();
let report = vm.run_budget(100, &mut ReturnsString, &mut HostContext::new(None)).unwrap();
// This synthetic native implementation tests the bounded writer, not the
@@ -139,7 +139,49 @@ fn intrinsic_boundaries_reject_implicit_carrier_conversions_in_execution() {
"PUSH_I64 1\nPUSH_F64 f64:0x4000000000000000\nINTRINSIC 0x1001", // Float/Float required
"PUSH_I64 -1\nINTRINSIC 0x1106", // out-of-range color
] {
let mut vm = VirtualMachine::new(assemble(source).unwrap(), vec![]);
let bytes = prometeu_test_support::program::TestProgram::single(
assemble(&(source.to_string() + "\nHALT")).unwrap(),
Default::default(),
0,
8,
)
.serialize();
let known = prometeu_vm::ValidatedProgramImage::load(
&bytes,
&mut prometeu_bytecode::load_limits::LoadBudget::new(Default::default()),
0,
);
if let Err(error) = known {
assert!(
matches!(error,prometeu_vm::VmInitError::RegistryLoadFailed(e) if e.code==prometeu_bytecode::load_limits::LoadCode::InvalidCode && e.reason==prometeu_bytecode::load_limits::LoadReason::TypeMismatch)
);
}
// Globals deliberately hide the concrete carrier from static facts;
// the same rejected values must still fault at the runtime boundary.
let lines: Vec<_> = source.lines().collect();
let mut unknown = String::new();
for (i, line) in lines[..lines.len() - 1].iter().enumerate() {
unknown.push_str(&format!("{line}\nSET_GLOBAL {i}\n"));
}
for i in 0..lines.len() - 1 {
unknown.push_str(&format!("GET_GLOBAL {i}\n"));
}
unknown.push_str(lines.last().unwrap());
unknown.push_str("\nHALT");
let bytes = prometeu_test_support::program::TestProgram::single(
assemble(&unknown).unwrap(),
Default::default(),
0,
8,
)
.serialize();
let image = prometeu_vm::ValidatedProgramImage::load(
&bytes,
&mut prometeu_bytecode::load_limits::LoadBudget::new(Default::default()),
0,
)
.unwrap();
let mut vm = VirtualMachine::from_image(image, Default::default());
vm.prepare_call("0").expect("prepare entry call");
let report = vm.run_budget(100, &mut NoSyscalls, &mut HostContext::new(None)).unwrap();
assert!(
@@ -45,6 +45,7 @@ fn named_arguments_preserve_source_effect_order_and_call_in_signature_order_with
vec![]
};
functions.push(FunctionDecl {
captures: vec![],
name: Some(["main", "effectX", "effectY", "combine"][index].into()),
signature: Signature {
parameters,
@@ -6,18 +6,19 @@ use prometeu_vm::{
resource_budget::{RuntimeLimits, RuntimeResource},
};
// Independent executable oracle: 32-byte header, seven directory entries,
// payload at 116, one Bool import, one zero-slot HALT function; total 173.
// Independent executable oracle: 32-byte header, eight directory entries,
// payload at 128, one Bool import, one zero-slot HALT function; total 193.
fn minimal() -> Vec<u8> {
"50 42 58 00 01 00 00 00 07 00 00 00
"50 42 58 00 01 00 00 00 08 00 00 00
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
00 00 00 00 74 00 00 00 04 00 00 00
01 00 00 00 78 00 00 00 1d 00 00 00
02 00 00 00 95 00 00 00 02 00 00 00
04 00 00 00 97 00 00 00 04 00 00 00
05 00 00 00 9b 00 00 00 04 00 00 00
06 00 00 00 9f 00 00 00 0a 00 00 00
07 00 00 00 a9 00 00 00 04 00 00 00
00 00 00 00 80 00 00 00 04 00 00 00
01 00 00 00 84 00 00 00 1d 00 00 00
02 00 00 00 a1 00 00 00 02 00 00 00
04 00 00 00 a3 00 00 00 04 00 00 00
05 00 00 00 a7 00 00 00 04 00 00 00
06 00 00 00 ab 00 00 00 0a 00 00 00
07 00 00 00 b5 00 00 00 04 00 00 00
08 00 00 00 b9 00 00 00 08 00 00 00
00 00 00 00
01 00 00 00 00 00 00 00 00 00 00 00 00
00 00 00 00 02 00 00 00 00 00 00 00 00 00 00 00
@@ -25,7 +26,8 @@ fn minimal() -> Vec<u8> {
00 00 00 00
00 00 00 00
01 00 00 00 00 00 13 00 00 00
00 00 00 00"
00 00 00 00
01 00 00 00 00 00 00 00"
.split_whitespace()
.map(|byte| u8::from_str_radix(byte, 16).unwrap())
.collect()
@@ -46,7 +48,7 @@ impl NativeInterface for Native {
#[test]
fn independent_v1_bytes_load_publish_and_execute_through_the_public_sealed_boundary() {
let bytes = minimal();
assert_eq!(bytes.len(), 173);
assert_eq!(bytes.len(), 193);
let mut load = LoadBudget::new(Default::default());
let image = ValidatedProgramImage::load(&bytes, &mut load, caps::NONE).unwrap();
assert_eq!(load.used(LoadResource::TemporaryBytes), 0);
@@ -63,9 +65,9 @@ fn independent_v1_bytes_load_publish_and_execute_through_the_public_sealed_bound
fn single_violation_oracles_reject_before_image_publication_with_typed_context() {
for (offset, replacement, code, reason, pc) in [
(4, 0, LoadCode::UnsupportedFormat, LoadReason::Version, None),
(165, 0, LoadCode::UnsupportedFormat, LoadReason::Builtin, None),
(149, 0xff, LoadCode::InvalidCode, LoadReason::UnknownOpcode, Some(0)),
(149, 0x11, LoadCode::InvalidCode, LoadReason::StackUnderflow, Some(0)),
(177, 0, LoadCode::UnsupportedFormat, LoadReason::Builtin, None),
(161, 0xff, LoadCode::InvalidCode, LoadReason::UnknownOpcode, Some(0)),
(161, 0x11, LoadCode::InvalidCode, LoadReason::StackUnderflow, Some(0)),
] {
let mut bytes = minimal();
bytes[offset] = replacement;
+2 -2
View File
@@ -10,10 +10,10 @@ use prometeu_vm::VirtualMachine;
#[test]
fn vm_instantiation_is_stable() {
// Create a VM with empty ROM and empty constant pool.
let vm = VirtualMachine::new(vec![], vec![]);
let vm = VirtualMachine::default();
// Basic invariant checks that should remain stable across refactors.
assert_eq!(vm.pc(), 0);
assert!(!vm.is_halted());
assert!(vm.is_halted());
}
#[test]
@@ -0,0 +1,127 @@
use prometeu_bytecode::Value;
use prometeu_bytecode::assembler::assemble;
use prometeu_bytecode::load_limits::LoadBudget;
use prometeu_bytecode::registry::*;
use prometeu_bytecode::registry_codec::PbxModule;
use prometeu_hal::syscalls::caps;
use prometeu_hal::vm_fault::VmFault;
use prometeu_hal::{HostContext, HostReturn, NativeInterface};
use prometeu_vm::resource_budget::RuntimeLimits;
use prometeu_vm::{ValidatedProgramImage, VirtualMachine, VmInitError};
pub struct Native;
impl NativeInterface for Native {
fn syscall(
&mut self,
_: u32,
_: &[Value],
_: &mut HostReturn,
_: &mut HostContext,
) -> Result<(), VmFault> {
panic!("no syscall in callable fixtures")
}
}
pub fn param(id: u32) -> NamedType {
NamedType { type_id: TypeId(id), name: None }
}
pub fn sig(parameters: &[u32], results: &[u32]) -> Signature {
Signature {
parameters: parameters.iter().map(|&i| param(i)).collect(),
results: results.iter().map(|&i| TypeId(i)).collect(),
}
}
pub fn types() -> Vec<TypeDecl> {
vec![
TypeKind::Builtin(BuiltinId::INT32),
TypeKind::Builtin(BuiltinId::FLOAT),
TypeKind::Builtin(BuiltinId::VEC2),
TypeKind::Builtin(BuiltinId::STRING),
TypeKind::Fn(sig(&[], &[0])),
TypeKind::Struct(vec![param(0)]),
TypeKind::Fn(sig(&[], &[4, 4])),
TypeKind::Trait(vec![MethodDecl { name: None, signature: sig(&[], &[0]) }]),
TypeKind::Struct(vec![param(0)]),
TypeKind::Fn(sig(&[], &[])),
TypeKind::Array(TypeId(4)),
TypeKind::Builtin(BuiltinId::DYNAMIC),
TypeKind::Fn(sig(&[2], &[2])),
TypeKind::Fn(sig(&[], &[2])),
TypeKind::Fn(sig(&[], &[1, 1])),
TypeKind::Struct(vec![param(4)]),
TypeKind::Fn(sig(&[], &[3])),
TypeKind::Fn(sig(&[], &[7, 11, 3, 2])),
TypeKind::Fn(sig(&[4], &[4])),
]
.into_iter()
.map(|kind| TypeDecl { name: None, kind })
.collect()
}
pub fn image(
bodies: &[(&str, Signature, Vec<TypeId>)],
implementations: Vec<ImplementationDecl>,
) -> Result<std::sync::Arc<ValidatedProgramImage>, VmInitError> {
image_constants(bodies, implementations, &[])
}
pub fn image_constants(
bodies: &[(&str, Signature, Vec<TypeId>)],
implementations: Vec<ImplementationDecl>,
constants: &[prometeu_bytecode::model::ConstantPoolEntry],
) -> Result<std::sync::Arc<ValidatedProgramImage>, VmInitError> {
let bytes = bytes(bodies, implementations, constants)?;
ValidatedProgramImage::load(&bytes, &mut LoadBudget::new(Default::default()), caps::NONE)
}
pub fn bytes(
bodies: &[(&str, Signature, Vec<TypeId>)],
implementations: Vec<ImplementationDecl>,
constants: &[prometeu_bytecode::model::ConstantPoolEntry],
) -> Result<Vec<u8>, prometeu_bytecode::load_limits::LoadFailure> {
bytes_with_syscalls(bodies, implementations, constants, &[])
}
pub fn bytes_with_syscalls(
bodies: &[(&str, Signature, Vec<TypeId>)],
implementations: Vec<ImplementationDecl>,
constants: &[prometeu_bytecode::model::ConstantPoolEntry],
syscalls: &[prometeu_bytecode::model::SyscallDecl],
) -> Result<Vec<u8>, prometeu_bytecode::load_limits::LoadFailure> {
let mut code = vec![];
let mut functions = vec![];
for (source, signature, captures) in bodies {
let body = assemble(source).unwrap();
functions.push(FunctionDecl {
signature: signature.clone(),
captures: captures.clone(),
code_offset: code.len() as u32,
code_len: body.len() as u32,
local_slots: 4,
max_stack_slots: 32,
..Default::default()
});
code.extend(body);
}
let mut budget = LoadBudget::new(Default::default());
let registry = Registry::resolve(
RegistryDeclarations { types: types(), functions, implementations },
code.len(),
&mut budget,
)?;
let bytes = PbxModule {
registry: &registry,
constants,
code: &code,
debug: None,
exports: &[],
syscalls,
}
.serialize(&mut budget)?;
Ok(bytes)
}
pub fn vm(bodies: &[(&str, Signature, Vec<TypeId>)]) -> VirtualMachine {
let mut vm =
VirtualMachine::from_image(image(bodies, vec![]).unwrap(), RuntimeLimits::default());
vm.prepare_boot_call().unwrap();
vm
}
pub fn run(vm: &mut VirtualMachine, budget: u64) -> prometeu_vm::BudgetReport {
vm.run_budget(budget, &mut Native, &mut HostContext::new(None)).unwrap()
}
@@ -1,45 +1,21 @@
//! Regression test: input is no longer exposed through the syscall registry.
use prometeu_bytecode::isa::core::CoreOpCode as OpCode;
use prometeu_hal::vm_fault::VmFault;
use prometeu_vm::{HostContext, HostReturn, NativeInterface, VirtualMachine};
fn enc_op(op: OpCode) -> [u8; 2] {
(op as u16).to_le_bytes()
}
//! Removed native IDs cannot enter the sealed execution path.
use prometeu_bytecode::assemble;
use prometeu_test_support::program::{TestProgram, int64_signature};
use prometeu_vm::{LoaderPatchError, ValidatedProgramImage, VmInitError};
#[test]
fn vm_rejects_legacy_input_syscall_id() {
// Legacy input syscall id (PadGetUp) must now be rejected as unknown syscall.
let mut rom = Vec::new();
rom.extend_from_slice(&enc_op(OpCode::Syscall));
rom.extend_from_slice(&0x2200u32.to_le_bytes());
rom.extend_from_slice(&enc_op(OpCode::Halt));
struct NoopNative;
impl NativeInterface for NoopNative {
fn syscall(
&mut self,
_id: u32,
_args: &[prometeu_bytecode::Value],
_ret: &mut HostReturn,
_ctx: &mut HostContext,
) -> Result<(), VmFault> {
Ok(())
}
}
let mut vm = VirtualMachine::new(rom, vec![]);
let mut native = NoopNative;
let mut ctx = HostContext::new(None);
vm.prepare_call("0").expect("prepare entry call");
vm.set_capabilities(prometeu_hal::syscalls::caps::ALL);
let report = vm.run_budget(100, &mut native, &mut ctx).expect("VM run failed");
match report.reason {
prometeu_vm::LogicalFrameEndingReason::Trap(trap) => {
assert_eq!(trap.code, prometeu_bytecode::TRAP_INVALID_SYSCALL);
assert!(trap.message.contains("Unknown syscall"));
}
other => panic!("Expected invalid syscall trap, got {:?}", other),
}
fn loader_rejects_legacy_input_syscall_id() {
let bytes =
TestProgram::single(assemble("SYSCALL 0x2200\nHALT").unwrap(), int64_signature(0, 0), 0, 4)
.serialize();
assert!(matches!(
ValidatedProgramImage::load(
&bytes,
&mut prometeu_bytecode::load_limits::LoadBudget::new(Default::default()),
0
),
Err(VmInitError::LoaderPatchFailed(LoaderPatchError::RawSyscallInPreloadArtifact {
syscall_id: 0x2200,
..
}))
));
}
@@ -0,0 +1,246 @@
mod support {
pub mod callables;
}
use prometeu_bytecode::{
Value,
load_limits::{LoadCode, LoadReason},
registry::*,
};
use prometeu_vm::{
LogicalFrameEndingReason, VirtualMachine, VmInitError,
resource_budget::{RuntimeLimits, RuntimeResource},
};
use support::callables::*;
#[test]
fn captures_are_not_public_parameters_and_survive_creator_return() {
let mut vm = vm(&[
("CALL 1\nSET_GLOBAL 0\nGET_GLOBAL 0\nCALL_CLOSURE 4\nRET", sig(&[], &[0]), vec![]),
("PUSH_I32 42\nMAKE_CLOSURE fn=2,type=4\nRET", sig(&[], &[4]), vec![]),
("GET_CAPTURE 0\nRET", sig(&[], &[0]), vec![TypeId(0)]),
]);
assert_eq!(run(&mut vm, 1000).reason, LogicalFrameEndingReason::EndOfRom);
assert_eq!(vm.operand_stack_top(1).to_vec(), vec![Value::Int32(42)]);
}
#[test]
fn factory_returns_two_callbacks_sharing_a_mutable_cell() {
let factory = "STRUCT_NEW 5\nSET_LOCAL 0\nGET_LOCAL 0\nMAKE_CLOSURE fn=2,type=4\nGET_LOCAL 0\nMAKE_CLOSURE fn=3,type=4\nRET";
let increment = "GET_CAPTURE 0\nDUP\nSTRUCT_GET type=5,field=0\nPUSH_I32 1\nADD\nSTRUCT_SET type=5,field=0\nGET_CAPTURE 0\nSTRUCT_GET type=5,field=0\nRET";
let mut vm = vm(&[
(
"CALL 1\nSET_GLOBAL 1\nSET_GLOBAL 0\nGET_GLOBAL 0\nCALL_CLOSURE 4\nPOP\nGET_GLOBAL 0\nCALL_CLOSURE 4\nPOP\nGET_GLOBAL 1\nCALL_CLOSURE 4\nRET",
sig(&[], &[0]),
vec![],
),
(factory, sig(&[], &[4, 4]), vec![]),
(increment, sig(&[], &[0]), vec![TypeId(5)]),
("GET_CAPTURE 0\nSTRUCT_GET type=5,field=0\nRET", sig(&[], &[0]), vec![TypeId(5)]),
]);
assert_eq!(run(&mut vm, 10000).reason, LogicalFrameEndingReason::EndOfRom);
assert_eq!(vm.operand_stack_top(1).to_vec(), vec![Value::Int32(2)]);
}
#[test]
fn independent_factories_do_not_share_mutable_cells() {
let factory = "STRUCT_NEW 5\nSET_LOCAL 0\nGET_LOCAL 0\nMAKE_CLOSURE fn=2,type=4\nGET_LOCAL 0\nMAKE_CLOSURE fn=3,type=4\nRET";
let increment = "GET_CAPTURE 0\nDUP\nSTRUCT_GET type=5,field=0\nPUSH_I32 1\nADD\nSTRUCT_SET type=5,field=0\nGET_CAPTURE 0\nSTRUCT_GET type=5,field=0\nRET";
let root = "CALL 1\nSET_GLOBAL 1\nSET_GLOBAL 0\nCALL 1\nSET_GLOBAL 3\nSET_GLOBAL 2\nGET_GLOBAL 0\nCALL_CLOSURE 4\nPOP\nGET_GLOBAL 1\nCALL_CLOSURE 4\nGET_GLOBAL 3\nCALL_CLOSURE 4\nRET";
let mut v = vm(&[
(root, sig(&[], &[0, 0]), vec![]),
(factory, sig(&[], &[4, 4]), vec![]),
(increment, sig(&[], &[0]), vec![TypeId(5)]),
("GET_CAPTURE 0\nSTRUCT_GET type=5,field=0\nRET", sig(&[], &[0]), vec![TypeId(5)]),
]);
assert_eq!(run(&mut v, 1000).reason, LogicalFrameEndingReason::EndOfRom);
assert_eq!(v.operand_stack_top(2), vec![Value::Int32(0), Value::Int32(1)]);
}
#[test]
fn captured_direct_calls_and_invalid_capture_indices_reject_at_load() {
for (root, body, captures, reason) in [
("CALL 1\nRET", "GET_CAPTURE 0\nRET", vec![TypeId(0)], LoadReason::CapturedDirectCall),
(
"PUSH_I32 1\nMAKE_CLOSURE fn=1,type=4\nCALL_CLOSURE 4\nRET",
"GET_CAPTURE 1\nRET",
vec![TypeId(0)],
LoadReason::CaptureIndex,
),
] {
assert!(
matches!(image(&[(root,sig(&[],&[0]),vec![]),(body,sig(&[],&[0]),captures)],vec![]),Err(VmInitError::RegistryLoadFailed(e)) if e.reason==reason)
);
}
}
#[test]
fn host_cannot_prepare_a_capturing_body_or_capturant_trait_implementation() {
let image = image(
&[("RET", sig(&[], &[]), vec![]), ("GET_CAPTURE 0\nRET", sig(&[], &[0]), vec![TypeId(0)])],
vec![],
)
.unwrap();
let mut v = VirtualMachine::from_image(image, Default::default());
assert!(
matches!(v.prepare_call("1"),Err(VmInitError::RegistryLoadFailed(e)) if e.code==LoadCode::InvalidEntrypoint && e.reason==LoadReason::CapturedDirectCall)
);
let result = support::callables::image(
&[("RET", sig(&[], &[]), vec![]), ("GET_CAPTURE 0\nRET", sig(&[5], &[0]), vec![TypeId(0)])],
vec![ImplementationDecl {
owner: TypeId(5),
trait_id: TypeId(7),
methods: vec![FunctionId(1)],
}],
);
assert!(
matches!(result,Err(VmInitError::RegistryLoadFailed(e)) if e.code==LoadCode::InvalidRegistry && e.reason==LoadReason::CapturedDirectCall)
);
}
#[test]
fn sync_and_gc_retain_active_frame_environment_after_fn_operand_is_consumed() {
let mut body = "MAKE_CLOSURE fn=2,type=4\nPOP\n".repeat(1030);
body.push_str("FRAME_SYNC\nGET_CAPTURE 0\nRET");
let mut vm = vm(&[
("PUSH_I32 73\nMAKE_CLOSURE fn=1,type=4\nCALL_CLOSURE 4\nRET", sig(&[], &[0]), vec![]),
(&body, sig(&[], &[0]), vec![TypeId(0)]),
("PUSH_I32 1\nRET", sig(&[], &[0]), vec![]),
]);
assert_eq!(run(&mut vm, 100000).reason, LogicalFrameEndingReason::FrameSync);
assert_eq!(vm.heap().len(), 1);
assert!(!vm.call_stack_is_empty());
assert_eq!(run(&mut vm, 1000).reason, LogicalFrameEndingReason::EndOfRom);
assert_eq!(vm.operand_stack_top(1).to_vec(), vec![Value::Int32(73)]);
}
#[test]
fn recurring_roots_use_no_heap_execution_objects_or_handle_quota() {
let image = image(&[("RET", sig(&[], &[]), vec![])], vec![]).unwrap();
let limits = RuntimeLimits::default().lowered(RuntimeResource::HandleSlots, 0).unwrap();
let mut vm = VirtualMachine::from_image(image, limits);
for _ in 0..3000 {
vm.prepare_boot_call().unwrap();
assert_eq!(run(&mut vm, 20).reason, LogicalFrameEndingReason::EndOfRom);
}
assert_eq!(vm.heap().allocation_count(), 0);
assert_eq!(vm.heap().len(), 0);
}
#[test]
fn logical_result_groups_distinguish_equal_width_signatures_at_load() {
let result = image(
&[
("MAKE_CLOSURE fn=1,type=14\nPOP\nRET", sig(&[], &[]), vec![]),
(
"PUSH_F64 f64:0x3ff0000000000000\nPUSH_F64 f64:0x4000000000000000\nRET",
sig(&[], &[2]),
vec![],
),
],
vec![],
);
assert!(
matches!(result,Err(VmInitError::RegistryLoadFailed(e)) if e.code==LoadCode::InvalidCode && e.reason==LoadReason::Signature)
);
}
#[test]
fn trait_dispatch_selects_exact_receiver_first_implementation() {
let bodies = [
(
"STRUCT_NEW 5\nREF_TO_TRAIT source=5,target=7\nCALL_TRAIT type=7,method=0\nSTRUCT_NEW 8\nREF_TO_TRAIT source=8,target=7\nCALL_TRAIT type=7,method=0\nADD\nRET",
sig(&[], &[0]),
vec![],
),
("PUSH_I32 10\nRET", sig(&[5], &[0]), vec![]),
("PUSH_I32 20\nRET", sig(&[8], &[0]), vec![]),
];
let impls = vec![
ImplementationDecl { owner: TypeId(5), trait_id: TypeId(7), methods: vec![FunctionId(1)] },
ImplementationDecl { owner: TypeId(8), trait_id: TypeId(7), methods: vec![FunctionId(2)] },
];
let mut vm =
VirtualMachine::from_image(image(&bodies, impls).unwrap(), RuntimeLimits::default());
vm.prepare_boot_call().unwrap();
assert_eq!(run(&mut vm, 1000).reason, LogicalFrameEndingReason::EndOfRom);
assert_eq!(vm.operand_stack_top(1).to_vec(), vec![Value::Int32(30)]);
}
#[test]
fn fn_survives_struct_array_dynamic_storage_and_pass_return() {
let source = "STRUCT_NEW 15\nSET_LOCAL 0\nGET_LOCAL 0\nMAKE_CLOSURE fn=2,type=4\nSTRUCT_SET type=15,field=0\nPUSH_I64 1\nARRAY_NEW 10\nSET_LOCAL 1\nGET_LOCAL 1\nPUSH_I64 0\nGET_LOCAL 0\nSTRUCT_GET type=15,field=0\nARRAY_SET 10\nGET_LOCAL 1\nPUSH_I64 0\nARRAY_GET 10\nDYN_PACK 4\nDYN_UNPACK 4\nCALL 1\nCALL_CLOSURE 4\nRET";
let mut v = vm(&[
(source, sig(&[], &[0]), vec![]),
("GET_LOCAL 0\nRET", sig(&[4], &[4]), vec![]),
("PUSH_I32 81\nRET", sig(&[], &[0]), vec![]),
]);
assert_eq!(run(&mut v, 1000).reason, LogicalFrameEndingReason::EndOfRom);
assert_eq!(v.operand_stack_top(1), vec![Value::Int32(81)]);
}
#[test]
fn branch_selects_unknown_concrete_target_under_one_signature() {
for selected in [false, true] {
let mut code = prometeu_bytecode::assemble(&format!(
"PUSH_BOOL {}\nJMP_IF_FALSE 0\nMAKE_CLOSURE fn=1,type=4\nJMP 0",
u8::from(selected)
))
.unwrap();
let otherwise = code.len() as u32;
code.extend(prometeu_bytecode::assemble("MAKE_CLOSURE fn=2,type=4").unwrap());
let join = code.len() as u32;
code.extend(prometeu_bytecode::assemble("CALL_CLOSURE 4\nRET").unwrap());
code[5..9].copy_from_slice(&otherwise.to_le_bytes());
code[21..25].copy_from_slice(&join.to_le_bytes());
let source = prometeu_bytecode::disassemble(&code).unwrap();
let mut v = vm(&[
(&source, sig(&[], &[0]), vec![]),
("PUSH_I32 12\nRET", sig(&[], &[0]), vec![]),
("PUSH_I32 34\nRET", sig(&[], &[0]), vec![]),
]);
assert_eq!(run(&mut v, 1000).reason, LogicalFrameEndingReason::EndOfRom);
assert_eq!(v.operand_stack_top(1), vec![Value::Int32(if selected { 12 } else { 34 })]);
}
}
#[test]
fn bound_trait_receiver_adapter_keeps_view_in_capture_environment() {
let bodies = [
(
"STRUCT_NEW 5\nREF_TO_TRAIT source=5,target=7\nMAKE_CLOSURE fn=2,type=4\nCALL_CLOSURE 4\nRET",
sig(&[], &[0]),
vec![],
),
("PUSH_I32 91\nRET", sig(&[5], &[0]), vec![]),
("GET_CAPTURE 0\nCALL_TRAIT type=7,method=0\nRET", sig(&[], &[0]), vec![TypeId(7)]),
];
let implementation =
ImplementationDecl { owner: TypeId(5), trait_id: TypeId(7), methods: vec![FunctionId(1)] };
let mut v = VirtualMachine::from_image(
image(&bodies, vec![implementation]).unwrap(),
Default::default(),
);
v.prepare_boot_call().unwrap();
assert_eq!(run(&mut v, 1000).reason, LogicalFrameEndingReason::EndOfRom);
assert_eq!(v.operand_stack_top(1), vec![Value::Int32(91)]);
}
#[test]
fn native_string_capture_survives_factory_return() {
let bodies = [
("CALL 1\nCALL_CLOSURE 16\nRET", sig(&[], &[3]), vec![]),
("PUSH_CONST 0\nMAKE_CLOSURE fn=2,type=16\nRET", sig(&[], &[16]), vec![]),
("GET_CAPTURE 0\nRET", sig(&[], &[3]), vec![TypeId(3)]),
];
let mut v = VirtualMachine::from_image(
image_constants(
&bodies,
vec![],
&[prometeu_bytecode::model::ConstantPoolEntry::String("escaped owner".into())],
)
.unwrap(),
Default::default(),
);
v.prepare_boot_call().unwrap();
assert_eq!(run(&mut v, 1000).reason, LogicalFrameEndingReason::EndOfRom);
assert_eq!(v.operand_stack_top(1), vec![Value::string("escaped owner")]);
}
@@ -3,7 +3,7 @@ use prometeu_hal::{HostContext, HostReturn, NativeInterface, SyscallId};
use prometeu_vm::{BudgetReport, LogicalFrameEndingReason, VirtualMachine};
#[test]
fn scheduler_wake_and_ready_order_is_deterministic() {
fn single_context_frame_continuation_is_deterministic() {
// Black-box determinism: run a tiny program twice and ensure it yields the same sequence
// of LogicalFrameEndingReason for identical budgets.
@@ -39,7 +39,20 @@ fn scheduler_wake_and_ready_order_is_deterministic() {
emit(CoreOpCode::Halt, None, &mut rom);
let run_once = || -> Vec<LogicalFrameEndingReason> {
let mut vm = VirtualMachine::new(rom.clone(), vec![]);
let bytes = prometeu_test_support::program::TestProgram::single(
rom.clone(),
Default::default(),
0,
4,
)
.serialize();
let image = prometeu_vm::ValidatedProgramImage::load(
&bytes,
&mut prometeu_bytecode::load_limits::LoadBudget::new(Default::default()),
0,
)
.unwrap();
let mut vm = VirtualMachine::from_image(image, Default::default());
vm.prepare_call("0").expect("prepare entry call");
let mut native = NoopNative;
let mut ctx = HostContext::new(None);
@@ -23,11 +23,11 @@ fn serialized_guest_cycle_and_dynamic_box_cross_real_safepoints_then_reclaim() {
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
assert_eq!(vm.heap().len(), 3); // 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_eq!(vm.heap().len(), 0);
assert!(!vm.heap().is_valid(array));
}
@@ -0,0 +1,12 @@
#[allow(dead_code)]
#[path = "../../../console/prometeu-vm/tests/support/callables.rs"]
mod support;
use prometeu_bytecode::{registry::TypeId, Value};
use prometeu_vm::LogicalFrameEndingReason;
#[test]
fn tuple_returned_callbacks_capture_state_across_a_real_frame_boundary() {
let mut vm=support::vm(&[("CALL 1\nSET_GLOBAL 1\nSET_GLOBAL 0\nFRAME_SYNC\nGET_GLOBAL 0\nCALL_CLOSURE 4\nGET_GLOBAL 1\nCALL_CLOSURE 4\nRET",support::sig(&[],&[0,0]),vec![]),("PUSH_I32 13\nMAKE_CLOSURE fn=2,type=4\nPUSH_I32 29\nMAKE_CLOSURE fn=2,type=4\nRET",support::sig(&[],&[4,4]),vec![]),("GET_CAPTURE 0\nRET",support::sig(&[],&[0]),vec![TypeId(0)])]);
assert_eq!(support::run(&mut vm, 1000).reason, LogicalFrameEndingReason::FrameSync);
assert_eq!(support::run(&mut vm, 1000).reason, LogicalFrameEndingReason::EndOfRom);
assert_eq!(vm.operand_stack_top(2), vec![Value::Int32(29), Value::Int32(13)]);
}
@@ -2,9 +2,11 @@ use prometeu_vm::{VirtualMachine, VmInitError};
#[test]
fn invalid_image_format_is_rejected_before_execution() {
// Provide bytes that are not a valid PBX image. The VM must reject it with InvalidFormat.
// Provide bytes that are not a valid PBX image. The VM must reject it with a structured load error.
let program_bytes = b"NOT_PBX_IMAGE".to_vec();
let mut vm = VirtualMachine::default();
let result = vm.initialize(program_bytes);
assert!(matches!(result, Err(VmInitError::InvalidFormat)));
assert!(
matches!(result,Err(VmInitError::RegistryLoadFailed(e)) if e.code==prometeu_bytecode::load_limits::LoadCode::InvalidFormat)
);
}
@@ -36,11 +36,20 @@ fn vm_executes_valid_program_in_slices() {
emit(CoreOpCode::PushI32, Some(&2i32.to_le_bytes()), &mut rom);
emit(CoreOpCode::PushI32, Some(&3i32.to_le_bytes()), &mut rom);
emit(CoreOpCode::Add, None, &mut rom);
emit(CoreOpCode::SetGlobal, Some(&0u32.to_le_bytes()), &mut rom);
emit(CoreOpCode::FrameSync, None, &mut rom);
emit(CoreOpCode::GetGlobal, Some(&0u32.to_le_bytes()), &mut rom);
emit(CoreOpCode::Halt, None, &mut rom);
// Construct VM directly; assume input is already verified.
let mut vm = VirtualMachine::new(rom, vec![]);
let bytes = prometeu_test_support::program::TestProgram::single(rom, Default::default(), 0, 8)
.serialize();
let image = prometeu_vm::ValidatedProgramImage::load(
&bytes,
&mut prometeu_bytecode::load_limits::LoadBudget::new(Default::default()),
0,
)
.unwrap();
let mut vm = VirtualMachine::from_image(image, Default::default());
vm.prepare_call("0").expect("prepare entry call");
let mut native = NoopNative;
@@ -6,3 +6,4 @@ license.workspace = true
[dependencies]
rand = { version = "0.8", features = ["std", "std_rng"] }
prometeu-bytecode = { path = "../../console/prometeu-bytecode" }
@@ -106,3 +106,5 @@ mod tests {
assert_eq!(c.now_millis(), 1032);
}
}
pub mod program;
@@ -0,0 +1,87 @@
//! Explicit typed test producers. All bytes use the official bounded v1 writer;
//! executable tests still go through ValidatedProgramImage::load.
use prometeu_bytecode::{
load_limits::LoadBudget,
model::{ConstantPoolEntry, DebugInfo, Export, SyscallDecl},
registry::*,
registry_codec::PbxModule,
};
#[derive(Default)]
pub struct TestProgram {
pub const_pool: Vec<ConstantPoolEntry>,
pub functions: Vec<FunctionDecl>,
pub code: Vec<u8>,
pub debug_info: Option<DebugInfo>,
pub exports: Vec<Export>,
pub syscalls: Vec<SyscallDecl>,
}
/// Scalar Int64 signatures for tests that explicitly choose this carrier.
/// Other carriers and multi-slot logical values must declare their own TypeIds.
pub fn int64_signature(parameters: usize, results: usize) -> Signature {
Signature {
parameters: (0..parameters).map(|_| NamedType { type_id: TypeId(0), name: None }).collect(),
results: vec![TypeId(0); results],
}
}
pub fn scalar_catalog() -> Vec<TypeDecl> {
[
BuiltinId::INT64,
BuiltinId::INT32,
BuiltinId::FLOAT,
BuiltinId::BOOL,
BuiltinId::STRING,
BuiltinId::DYNAMIC,
BuiltinId::VEC2,
BuiltinId::PIXEL,
BuiltinId::COLOR,
]
.into_iter()
.map(|id| TypeDecl { name: None, kind: TypeKind::Builtin(id) })
.collect()
}
impl TestProgram {
pub fn single(
code: Vec<u8>,
signature: Signature,
local_slots: u32,
max_stack_slots: u32,
) -> Self {
Self {
functions: vec![FunctionDecl {
name: None,
signature,
captures: vec![],
code_offset: 0,
code_len: code.len() as u32,
local_slots,
max_stack_slots,
}],
code,
..Self::default()
}
}
pub fn serialize(&self) -> Vec<u8> {
let mut budget = LoadBudget::new(Default::default());
let registry = Registry::resolve(
RegistryDeclarations {
types: scalar_catalog(),
functions: self.functions.clone(),
implementations: vec![],
},
self.code.len(),
&mut budget,
)
.expect("typed test declarations");
PbxModule {
registry: &registry,
constants: &self.const_pool,
code: &self.code,
debug: self.debug_info.as_ref(),
exports: &self.exports,
syscalls: &self.syscalls,
}
.serialize(&mut budget)
.expect("official bounded v1 writer")
}
}
@@ -22,3 +22,6 @@ getrandom = "0.3"
[[bench]]
name = "temporal"
harness = false
[dev-dependencies]
prometeu-test-support = { path = "../../dev/prometeu-test-support" }
@@ -1,3 +1,5 @@
use prometeu_bytecode::registry::FunctionDecl;
use prometeu_test_support::program::{TestProgram, int64_signature};
use std::fs;
use std::hint::black_box;
use std::path::{Path, PathBuf};
@@ -5,7 +7,7 @@ use std::time::{Instant, SystemTime, UNIX_EPOCH};
use prometeu_bytecode::SourceSpan;
use prometeu_bytecode::assembler::assemble;
use prometeu_bytecode::model::{BytecodeModule, DebugInfo, Export, FunctionMeta};
use prometeu_bytecode::model::{DebugInfo, Export};
use prometeu_host_headless::{AdvanceFramesStop, HeadlessHost};
const SAMPLE_FRAMES: u64 = 300;
@@ -47,17 +49,17 @@ fn benchmark_cartridge() -> PathBuf {
));
fs::create_dir_all(&directory).expect("create benchmark cartridge");
let code = assemble("FRAME_SYNC\nRET\n").expect("assemble benchmark program");
let module = BytecodeModule {
version: 0,
let code = assemble("RET\n").expect("assemble benchmark program");
let module = TestProgram {
const_pool: vec![],
functions: vec![FunctionMeta {
functions: vec![FunctionDecl {
code_offset: 0,
code_len: code.len() as u32,
param_slots: 0,
local_slots: 0,
return_slots: 0,
max_stack_slots: 1,
signature: int64_signature(0, 0),
captures: vec![],
name: None,
}],
code,
debug_info: Some(DebugInfo {
@@ -45,3 +45,107 @@ fn load_failure_wire_uses_shared_structured_serializer_and_no_runtime_pc() {
assert_eq!(wire["initError"]["load"]["requested"], 23);
assert_eq!(wire["initError"]["load"]["limit"], 22);
}
#[test]
fn executed_closure_quota_refusal_reaches_wire_with_machine_fields() {
use prometeu_bytecode::{
assemble, load_limits::LoadBudget, registry::*, registry_codec::PbxModule,
};
use prometeu_hal::{HostContext, HostReturn, NativeInterface};
use prometeu_vm::{
LogicalFrameEndingReason, ValidatedProgramImage, VirtualMachine,
resource_budget::RuntimeLimits,
};
let mut code = assemble("MAKE_CLOSURE fn=1,type=0\nPOP\nRET").unwrap();
let end = code.len() as u32;
code.extend(assemble("RET").unwrap());
let mut budget = LoadBudget::new(Default::default());
let registry = Registry::resolve(
RegistryDeclarations {
types: vec![TypeDecl { name: None, kind: TypeKind::Fn(Default::default()) }],
functions: vec![
FunctionDecl { code_len: end, max_stack_slots: 1, ..Default::default() },
FunctionDecl { code_offset: end, code_len: 2, ..Default::default() },
],
implementations: vec![],
},
code.len(),
&mut budget,
)
.unwrap();
let bytes = PbxModule {
registry: &registry,
code: &code,
constants: &[],
debug: None,
exports: &[],
syscalls: &[],
}
.serialize(&mut budget)
.unwrap();
let image =
ValidatedProgramImage::load(&bytes, &mut LoadBudget::new(Default::default()), 0).unwrap();
let mut vm = VirtualMachine::from_image(
image,
RuntimeLimits::default().lowered(RuntimeResource::HandleSlots, 0).unwrap(),
);
vm.prepare_boot_call().unwrap();
struct NoNative;
impl NativeInterface for NoNative {
fn syscall(
&mut self,
_: u32,
_: &[prometeu_bytecode::Value],
_: &mut HostReturn,
_: &mut HostContext,
) -> Result<(), prometeu_hal::vm_fault::VmFault> {
panic!("no native call expected")
}
}
let LogicalFrameEndingReason::Trap(trap) =
vm.run_budget(100, &mut NoNative, &mut HostContext::new(None)).unwrap().reason
else {
panic!("quota must refuse creation")
};
let wire = fault(&CrashReport::VmTrap { trap });
assert_eq!(wire["trap"]["code"], TRAP_RESOURCE_LIMIT);
assert_eq!(wire["trap"]["opcode"], 0x52);
assert_eq!(wire["trap"]["pc"], 0);
assert_eq!(wire["trap"]["resource"]["resource"], "HandleSlots");
assert_eq!(wire["trap"]["resource"]["requested"], 1);
assert_eq!(wire["trap"]["resource"]["limit"], 0);
}
#[test]
fn active_host_native_type_fault_preserves_wire_machine_fields() {
use prometeu_bytecode::{assemble, model::SyscallDecl};
let mut program = prometeu_test_support::program::TestProgram::single(
assemble("PUSH_BOOL 1\nHOSTCALL 0\nRET").unwrap(),
Default::default(),
0,
1,
);
program.syscalls.push(SyscallDecl {
module: "gfx2d".into(),
name: "clear".into(),
version: 1,
arg_slots: 1,
ret_slots: 0,
});
let dir = std::env::temp_dir().join(format!("prometeu-native-wire-{}", std::process::id()));
std::fs::create_dir_all(&dir).unwrap();
std::fs::write(dir.join("program.pbx"), program.serialize()).unwrap();
std::fs::write(dir.join("manifest.json"), r#"{"magic":"PMTU","cartridge_version":1,"app_id":78,"title":"Native fault","app_version":"1.0.0","app_mode":"Game","capabilities":["gfx2d"]}"#).unwrap();
let mut host = crate::HeadlessHost::new();
host.boot(dir.to_string_lossy()).unwrap();
let crate::AdvanceFrameOutcome::Faulted(report) = host.advance_frame().unwrap() else {
panic!("clear requires an integer color")
};
let wire = fault(&report);
assert_eq!(wire["trap"]["code"], prometeu_bytecode::TRAP_TYPE);
assert_eq!(wire["trap"]["opcode"], 0x70);
assert_eq!(wire["trap"]["pc"], 3);
assert_eq!(wire["pc"], 3);
assert_eq!(wire["initError"], Value::Null);
std::fs::remove_dir_all(dir).unwrap();
}
@@ -431,10 +431,12 @@ impl RuntimePlatform for HeadlessPlatform {
#[cfg(test)]
mod tests {
use prometeu_bytecode::registry::FunctionDecl;
use prometeu_test_support::program::{TestProgram, int64_signature};
use std::fs;
use prometeu_bytecode::assembler::assemble;
use prometeu_bytecode::model::{BytecodeModule, Export, FunctionMeta};
use prometeu_bytecode::model::Export;
use super::{AdvanceFrameOutcome, HeadlessHost};
@@ -467,16 +469,16 @@ mod tests {
fs::create_dir_all(&directory).expect("create test cartridge");
let code = assemble("JMP 0\n").expect("assemble non-closing program");
let module = BytecodeModule {
version: 0,
let module = TestProgram {
const_pool: vec![],
functions: vec![FunctionMeta {
functions: vec![FunctionDecl {
code_offset: 0,
code_len: code.len() as u32,
param_slots: 0,
local_slots: 0,
return_slots: 0,
max_stack_slots: 1,
signature: int64_signature(0, 0),
captures: vec![],
name: None,
}],
code,
debug_info: None,
@@ -1,9 +1,11 @@
use prometeu_bytecode::registry::FunctionDecl;
use prometeu_test_support::program::{TestProgram, int64_signature};
use std::fs;
use std::path::Path;
use prometeu_bytecode::SourceSpan;
use prometeu_bytecode::assembler::assemble;
use prometeu_bytecode::model::{BytecodeModule, DebugInfo, Export, FunctionMeta, SyscallDecl};
use prometeu_bytecode::model::{DebugInfo, Export, SyscallDecl};
use prometeu_hal::InputSignals;
use prometeu_hal::app_mode::AppMode;
use prometeu_hal::color::Color;
@@ -487,9 +489,9 @@ fn color_program() -> Vec<u8> {
INTRINSIC 0x210E\n"));
let jump_to_blue = rom.len() + 2;
rom.extend(asm("JMP_IF_FALSE 0"));
rom.extend(asm(&format!("PUSH_I64 {RED}\nHOSTCALL 0\nFRAME_SYNC\nRET\n")));
rom.extend(asm(&format!("PUSH_I64 {RED}\nHOSTCALL 0\nRET\n")));
let blue_at = rom.len() as u32;
rom.extend(asm(&format!("PUSH_I64 {BLUE}\nHOSTCALL 0\nFRAME_SYNC\nRET\n")));
rom.extend(asm(&format!("PUSH_I64 {BLUE}\nHOSTCALL 0\nRET\n")));
rom[jump_to_blue..jump_to_blue + 4].copy_from_slice(&blue_at.to_le_bytes());
module(rom, color_syscalls())
}
@@ -497,20 +499,20 @@ fn color_program() -> Vec<u8> {
fn input_edge_program() -> Vec<u8> {
let mut rom = Vec::new();
let pressed_jump = emit_right_predicate(&mut rom, 0x210C);
rom.extend(asm(&format!("PUSH_I64 {RED}\nHOSTCALL 0\nFRAME_SYNC\nRET\n")));
rom.extend(asm(&format!("PUSH_I64 {RED}\nHOSTCALL 0\nRET\n")));
let released_at = rom.len() as u32;
rom[pressed_jump..pressed_jump + 4].copy_from_slice(&released_at.to_le_bytes());
let released_jump = emit_right_predicate(&mut rom, 0x210D);
rom.extend(asm(&format!("PUSH_I64 {GREEN}\nHOSTCALL 0\nFRAME_SYNC\nRET\n")));
rom.extend(asm(&format!("PUSH_I64 {GREEN}\nHOSTCALL 0\nRET\n")));
let down_at = rom.len() as u32;
rom[released_jump..released_jump + 4].copy_from_slice(&down_at.to_le_bytes());
let down_jump = emit_right_predicate(&mut rom, 0x210E);
rom.extend(asm(&format!("PUSH_I64 {BLUE}\nHOSTCALL 0\nFRAME_SYNC\nRET\n")));
rom.extend(asm(&format!("PUSH_I64 {BLUE}\nHOSTCALL 0\nRET\n")));
let idle_at = rom.len() as u32;
rom[down_jump..down_jump + 4].copy_from_slice(&idle_at.to_le_bytes());
rom.extend(asm(&format!("PUSH_I64 {BLACK}\nHOSTCALL 0\nFRAME_SYNC\nRET\n")));
rom.extend(asm(&format!("PUSH_I64 {BLACK}\nHOSTCALL 0\nRET\n")));
module(rom, gfx_syscalls())
}
@@ -525,20 +527,20 @@ fn emit_right_predicate(rom: &mut Vec<u8>, predicate: u32) -> usize {
fn touch_edge_program() -> Vec<u8> {
let mut rom = Vec::new();
let pressed_jump = emit_touch_predicate(&mut rom, 0x2130);
rom.extend(asm(&format!("PUSH_I64 {RED}\nHOSTCALL 0\nFRAME_SYNC\nRET\n")));
rom.extend(asm(&format!("PUSH_I64 {RED}\nHOSTCALL 0\nRET\n")));
let released_at = rom.len() as u32;
rom[pressed_jump..pressed_jump + 4].copy_from_slice(&released_at.to_le_bytes());
let released_jump = emit_touch_predicate(&mut rom, 0x2131);
rom.extend(asm(&format!("PUSH_I64 {GREEN}\nHOSTCALL 0\nFRAME_SYNC\nRET\n")));
rom.extend(asm(&format!("PUSH_I64 {GREEN}\nHOSTCALL 0\nRET\n")));
let down_at = rom.len() as u32;
rom[released_jump..released_jump + 4].copy_from_slice(&down_at.to_le_bytes());
let down_jump = emit_touch_predicate(&mut rom, 0x2132);
rom.extend(asm(&format!("PUSH_I64 {BLUE}\nHOSTCALL 0\nFRAME_SYNC\nRET\n")));
rom.extend(asm(&format!("PUSH_I64 {BLUE}\nHOSTCALL 0\nRET\n")));
let idle_at = rom.len() as u32;
rom[down_jump..down_jump + 4].copy_from_slice(&idle_at.to_le_bytes());
rom.extend(asm(&format!("PUSH_I64 {BLACK}\nHOSTCALL 0\nFRAME_SYNC\nRET\n")));
rom.extend(asm(&format!("PUSH_I64 {BLACK}\nHOSTCALL 0\nRET\n")));
module(rom, gfx_syscalls())
}
@@ -557,7 +559,7 @@ fn emit_touch_predicate(rom: &mut Vec<u8>, predicate: u32) -> usize {
fn fault_program() -> Vec<u8> {
// `INTRINSIC 0xDEADBEEF` is rejected by the loader as `VerificationFailed`.
// `TRAP` is a legal instruction that becomes `CrashReport::VmTrap` at runtime.
module(asm("TRAP\nFRAME_SYNC\nRET\n"), vec![])
module(asm("TRAP\nRET\n"), vec![])
}
fn delayed_fault_program() -> Vec<u8> {
@@ -567,7 +569,7 @@ fn delayed_fault_program() -> Vec<u8> {
rom.extend(asm("JMP_IF_FALSE 0\nTRAP\n"));
let continue_at = rom.len() as u32;
rom[continue_jump..continue_jump + 4].copy_from_slice(&continue_at.to_le_bytes());
rom.extend(asm(&format!("PUSH_I64 {BLACK}\nHOSTCALL 0\nFRAME_SYNC\nRET\n")));
rom.extend(asm(&format!("PUSH_I64 {BLACK}\nHOSTCALL 0\nRET\n")));
module(rom, gfx_syscalls())
}
@@ -575,7 +577,7 @@ fn multi_tick_program() -> Vec<u8> {
let mut rom = asm("PUSH_I32 30000\nSET_LOCAL 0\n");
let loop_at = rom.len() as u32;
rom.extend(asm("GET_LOCAL 0\nPUSH_I32 1\nSUB\nSET_LOCAL 0\nGET_LOCAL 0\nPUSH_I32 0\nGT\n"));
rom.extend(asm(&format!("JMP_IF_TRUE {loop_at}\nFRAME_SYNC\nRET\n")));
rom.extend(asm(&format!("JMP_IF_TRUE {loop_at}\nRET\n")));
module_with_locals(rom, vec![], 1)
}
@@ -613,16 +615,16 @@ fn module(code: Vec<u8>, syscalls: Vec<SyscallDecl>) -> Vec<u8> {
}
fn module_with_locals(code: Vec<u8>, syscalls: Vec<SyscallDecl>, local_slots: u16) -> Vec<u8> {
BytecodeModule {
version: 0,
TestProgram {
const_pool: vec![],
functions: vec![FunctionMeta {
functions: vec![FunctionDecl {
code_offset: 0,
code_len: code.len() as u32,
param_slots: 0,
local_slots,
return_slots: 0,
local_slots: u32::from(local_slots),
max_stack_slots: 8,
signature: int64_signature(0, 0),
captures: vec![],
name: None,
}],
code,
debug_info: Some(DebugInfo {
@@ -1,5 +1,7 @@
//! Independent catalogue and execution oracles for the fixed input ABI.
use prometeu_bytecode::{TRAP_INVALID_INTRINSIC, TRAP_UNAVAILABLE, Value, assembler::assemble};
use prometeu_test_support::program::{TestProgram, int64_signature};
use prometeu_vm::ValidatedProgramImage;
// Independent catalogue and execution oracles for the fixed input ABI.
use prometeu_bytecode::{TRAP_UNAVAILABLE, Value, assembler::assemble};
use prometeu_drivers::TestPlatform;
use prometeu_hal::{InputSignals, RuntimePlatform, vm_fault::VmFault};
use prometeu_vm::{
@@ -188,7 +190,7 @@ fn vm_queries_charge_one_cycle_each_and_allocate_no_guest_objects() {
for id in 0x2100..=0x2135 {
source.push_str(&format!("INTRINSIC {id}\n"));
}
let mut vm = VirtualMachine::new(assemble(&source).unwrap(), vec![]);
let mut vm = query_vm(assemble(&(source + "HALT\n")).unwrap());
vm.prepare_call("0").expect("prepare entry call");
let objects = vm.heap().len();
let mut platform = TestPlatform::new();
@@ -216,16 +218,36 @@ fn every_known_query_faults_when_unavailable_and_rejects_arguments() {
(meta.implementation)(&[Value::Int64(0)], &mut ctx),
Err(IntrinsicExecutionError::ArityMismatch { expected: 0, got: 1 })
);
let mut vm = VirtualMachine::new(assemble(&format!("INTRINSIC {id}\n")).unwrap(), vec![]);
let mut vm = query_vm(assemble(&format!("INTRINSIC {id}\nHALT")).unwrap());
vm.prepare_call("0").expect("prepare entry call");
let report = vm.run_budget(10, &mut NoSyscalls, &mut ctx).unwrap();
assert!(matches!(report.reason, LogicalFrameEndingReason::Trap(trap)
if trap.code == TRAP_UNAVAILABLE && trap.pc == 0));
assert!(vm.operand_stack_top(1).is_empty());
}
let mut vm = VirtualMachine::new(assemble("INTRINSIC 0x2136\n").unwrap(), vec![]);
vm.prepare_call("0").expect("prepare entry call");
let report = vm.run_budget(10, &mut NoSyscalls, &mut HostContext::new(None)).unwrap();
assert!(matches!(report.reason, LogicalFrameEndingReason::Trap(trap)
if trap.code == TRAP_INVALID_INTRINSIC));
let bytes = TestProgram::single(
assemble("INTRINSIC 0x2136\nHALT").unwrap(),
int64_signature(0, 0),
0,
64,
)
.serialize();
let error = ValidatedProgramImage::load(
&bytes,
&mut prometeu_bytecode::load_limits::LoadBudget::new(Default::default()),
0,
)
.unwrap_err();
assert!(matches!(error, prometeu_vm::VmInitError::RegistryLoadFailed(_)));
}
fn query_vm(code: Vec<u8>) -> VirtualMachine {
let bytes = TestProgram::single(code, int64_signature(0, 0), 0, 64).serialize();
let image = ValidatedProgramImage::load(
&bytes,
&mut prometeu_bytecode::load_limits::LoadBudget::new(Default::default()),
0,
)
.unwrap();
VirtualMachine::from_image(image, Default::default())
}
@@ -0,0 +1,248 @@
#[allow(dead_code)]
#[path = "../../../console/prometeu-vm/tests/support/callables.rs"]
mod callables;
use callables::{bytes, sig};
use prometeu_bytecode::{Value, registry::TypeId};
use prometeu_host_headless::{AdvanceFrameOutcome, HeadlessHost};
fn cartridge(program: &[u8], name: &str) -> std::path::PathBuf {
let dir =
std::env::temp_dir().join(format!("prometeu-typed-runtime-{}-{name}", std::process::id()));
std::fs::create_dir_all(&dir).unwrap();
std::fs::write(dir.join("program.pbx"), program).unwrap();
std::fs::write(dir.join("manifest.json"),r#"{"magic":"PMTU","cartridge_version":1,"app_id":77,"title":"Typed runtime","app_version":"1.0.0","app_mode":"Game","capabilities":[]}"#).unwrap();
dir
}
#[test]
fn sync_in_callee_or_closure_resumes_next_pc_with_locals_and_init_once() {
for captured in [false, true] {
let root = "GET_GLOBAL 0\nPUSH_I32 0\nEQ\nJMP_IF_FALSE 52\nPUSH_I32 1\nSET_GLOBAL 0\nGET_GLOBAL 1\nPUSH_I32 1\nADD\nSET_GLOBAL 1\nGET_GLOBAL 2\nPUSH_I32 1\nADD\nSET_GLOBAL 2\nCALL 1\nGET_GLOBAL 1\nGET_GLOBAL 2\nGET_GLOBAL 3\nRET";
let callee = "PUSH_I32 73\nSET_LOCAL 0\nFRAME_SYNC\nGET_LOCAL 0\nSET_GLOBAL 3\nRET";
let adapter = "PUSH_I32 73\nMAKE_CLOSURE fn=2,type=9\nCALL_CLOSURE 9\nRET";
let closure = "GET_CAPTURE 0\nSET_LOCAL 0\nFRAME_SYNC\nGET_LOCAL 0\nSET_GLOBAL 3\nRET";
let mut bodies = vec![
(root, sig(&[], &[0, 0, 0]), vec![]),
(if captured { adapter } else { callee }, sig(&[], &[]), vec![]),
];
if captured {
bodies.push((closure, sig(&[], &[]), vec![TypeId(0)]));
}
let program = bytes(&bodies, vec![], &[]).unwrap();
let dir = cartridge(&program, if captured { "closure" } else { "callee" });
let mut host = HeadlessHost::new();
host.boot(dir.to_string_lossy()).unwrap();
for entry in 1..=3 {
let AdvanceFrameOutcome::FrameCompleted { logical_frame_index: sync, .. } =
host.advance_frame().unwrap()
else {
panic!("sync failed {:?}", host.get_fault())
};
assert_eq!(sync, (entry * 2 - 1) as u64);
let sync_pc = host.get_state().pc;
assert!(sync_pc > 0);
let first = host.capture_frame().unwrap();
let AdvanceFrameOutcome::FrameCompleted { logical_frame_index: completion, .. } =
host.advance_frame().unwrap()
else {
panic!("root failed {:?}", host.get_fault())
};
assert_eq!(completion, (entry * 2) as u64);
assert_eq!(
&*host.get_state().stack_top,
&[Value::Int32(73), Value::Int32(entry), Value::Int32(1)]
);
let second = host.capture_frame().unwrap();
assert_ne!(first.frame.frame_id, second.frame.frame_id);
}
std::fs::remove_dir_all(dir).unwrap();
}
}
#[test]
fn regenerated_cartridges_run_six_complete_frames_on_production_host() {
use prometeu_hal::{
HostContext, HostReturn, NativeInterface,
syscalls::{Syscall, caps},
};
struct Effects {
scene_binds: usize,
frame_commands: usize,
}
impl NativeInterface for Effects {
fn syscall(
&mut self,
id: u32,
_: &[Value],
results: &mut HostReturn,
_: &mut HostContext,
) -> Result<(), prometeu_hal::vm_fault::VmFault> {
let syscall = Syscall::from_u32(id).unwrap();
if syscall == Syscall::ComposerBindScene {
self.scene_binds += 1;
}
if matches!(syscall, Syscall::GfxClear | Syscall::ComposerSetCamera) {
self.frame_commands += 1;
}
for _ in 0..syscall.results_count() {
results.push_int(0);
}
Ok(())
}
}
let root =
std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("../../..").join("test-cartridges");
for name in ["dummy-boy", "stress-console"] {
let mut host = HeadlessHost::new();
host.boot(root.join(name).to_string_lossy()).unwrap();
let mut hashes = vec![];
for expected in 1..=6 {
let AdvanceFrameOutcome::FrameCompleted { logical_frame_index, .. } =
host.advance_frame().unwrap()
else {
panic!("{name}: {:?}", host.get_fault())
};
assert_eq!(logical_frame_index, expected);
let frame = host.capture_frame().unwrap();
hashes.push(
frame
.frame
.pixels
.iter()
.fold(0u64, |sum, &p| sum.wrapping_mul(31).wrapping_add(p as u64)),
);
assert_eq!(frame.logical_frame_index, expected);
}
assert!(hashes.windows(2).all(|h| h[0] != h[1]), "{name} visuals did not progress");
assert!(host.get_fault().is_none());
// Observe the original program's one-time scene binding separately
// from the real host's visual smoke; no guest globals are exposed.
let program = std::fs::read(root.join(name).join("program.pbx")).unwrap();
let image = prometeu_vm::ValidatedProgramImage::load(
&program,
&mut prometeu_bytecode::load_limits::LoadBudget::new(Default::default()),
caps::ALL,
)
.unwrap();
let mut vm = prometeu_vm::VirtualMachine::from_image(image, Default::default());
let mut effects = Effects { scene_binds: 0, frame_commands: 0 };
for _ in 0..6 {
vm.prepare_boot_call().unwrap();
assert_eq!(
vm.run_budget(1_000_000, &mut effects, &mut HostContext::new(None)).unwrap().reason,
prometeu_vm::LogicalFrameEndingReason::EndOfRom,
);
}
assert_eq!(effects.frame_commands, 6);
assert_eq!(effects.scene_binds, usize::from(name == "stress-console"));
}
}
#[test]
fn budget_exhaustion_inside_fn_keeps_the_same_open_logical_frame() {
let mut body = "NOP\n".repeat(260_000);
body.push_str("GET_CAPTURE 0\nRET");
let program = bytes(
&[
("PUSH_I32 37\nMAKE_CLOSURE fn=1,type=4\nCALL_CLOSURE 4\nRET", sig(&[], &[0]), vec![]),
(&body, sig(&[], &[0]), vec![TypeId(0)]),
],
vec![],
&[],
)
.unwrap();
let dir = cartridge(&program, "budget");
let mut host = HeadlessHost::new();
host.boot(dir.to_string_lossy()).unwrap();
let before = host.get_state();
assert!(matches!(
host.advance_frame().unwrap(),
AdvanceFrameOutcome::FrameCompleted { logical_frame_index: 1, .. }
));
let after = host.get_state();
assert!(after.tick_index >= before.tick_index + 2);
assert_eq!(&*after.stack_top, &[Value::Int32(37)]);
assert_eq!(host.capture_frame().unwrap().logical_frame_index, 1);
std::fs::remove_dir_all(dir).unwrap();
}
#[test]
fn active_host_preserves_removed_opcode_load_context_and_null_fn_trap() {
let mut program = bytes(&[("HALT", sig(&[], &[]), vec![])], vec![], &[]).unwrap();
let mut budget = prometeu_bytecode::load_limits::LoadBudget::new(Default::default());
let code = prometeu_bytecode::registry_codec::PbxEnvelope::parse(&program, &mut budget)
.unwrap()
.section(2)
.unwrap()
.offset;
program[code..code + 2].copy_from_slice(&0x55u16.to_le_bytes());
let dir = cartridge(&program, "removed");
let mut host = HeadlessHost::new();
let Err(prometeu_host_headless::HostError::BootFailed { report: Some(report), .. }) =
host.boot(dir.to_string_lossy())
else {
panic!("invalid opcode must fail boot")
};
let diagnostic = report.init_diagnostic().unwrap();
assert_eq!(diagnostic["load"]["code"], "LOAD_INVALID_CODE");
assert_eq!(diagnostic["load"]["reason"], "RemovedOpcode");
assert_eq!(diagnostic["load"]["section"], 2);
assert_eq!(diagnostic["load"]["function"], 0);
std::fs::remove_dir_all(dir).unwrap();
let program = bytes(
&[(
"STRUCT_NEW 15\nSTRUCT_GET type=15,field=0\nCALL_CLOSURE 4\nRET",
sig(&[], &[0]),
vec![],
)],
vec![],
&[],
)
.unwrap();
let dir = cartridge(&program, "null");
let mut host = HeadlessHost::new();
host.boot(dir.to_string_lossy()).unwrap();
let AdvanceFrameOutcome::Faulted(prometeu_system::CrashReport::VmTrap { trap }) =
host.advance_frame().unwrap()
else {
panic!("null callback must trap")
};
assert_eq!(
(trap.code, trap.opcode, trap.pc),
(prometeu_bytecode::TRAP_NULL_REFERENCE, 0x53, 16)
);
std::fs::remove_dir_all(dir).unwrap();
}
#[test]
fn typed_native_argument_fault_inside_callback_reaches_active_host() {
let program = callables::bytes_with_syscalls(
&[
("MAKE_CLOSURE fn=1,type=9\nCALL_CLOSURE 9\nRET", sig(&[], &[]), vec![]),
("PUSH_BOOL 1\nSET_GLOBAL 0\nGET_GLOBAL 0\nHOSTCALL 0\nRET", sig(&[], &[]), vec![]),
],
vec![],
&[],
&[prometeu_bytecode::model::SyscallDecl {
module: "gfx2d".into(),
name: "clear".into(),
version: 1,
arg_slots: 1,
ret_slots: 0,
}],
)
.unwrap();
let dir = cartridge(&program, "native-fault");
std::fs::write(dir.join("manifest.json"), r#"{"magic":"PMTU","cartridge_version":1,"app_id":77,"title":"Typed runtime","app_version":"1.0.0","app_mode":"Game","capabilities":["gfx2d"]}"#).unwrap();
let mut host = HeadlessHost::new();
host.boot(dir.to_string_lossy()).unwrap();
let AdvanceFrameOutcome::Faulted(report @ prometeu_system::CrashReport::VmTrap { .. }) =
host.advance_frame().unwrap()
else {
panic!("clear requires an integer color carrier")
};
let prometeu_system::CrashReport::VmTrap { trap } = &report else { unreachable!() };
assert_eq!((trap.code, trap.opcode, trap.pc), (prometeu_bytecode::TRAP_TYPE, 0x70, 33));
assert_eq!(host.get_fault().as_ref(), Some(&report));
std::fs::remove_dir_all(dir).unwrap();
}
+30 -21
View File
@@ -1,6 +1,9 @@
use anyhow::Result;
use prometeu_bytecode::assembler::assemble;
use prometeu_bytecode::model::{BytecodeModule, DebugInfo, Export, FunctionMeta, SyscallDecl};
use prometeu_bytecode::load_limits::LoadBudget;
use prometeu_bytecode::model::{DebugInfo, Export, SyscallDecl};
use prometeu_bytecode::registry::{FunctionDecl, Registry, RegistryDeclarations};
use prometeu_bytecode::registry_codec::PbxModule;
use prometeu_hal::color::Color;
use std::fs;
use std::path::PathBuf;
@@ -54,7 +57,6 @@ pub fn build_program() -> Vec<u8> {
PUSH_I64 {}\n\
GET_LOCAL 0\n\
HOSTCALL 1\n\
FRAME_SYNC\n\
RET",
Color::WHITE.raw()
)));
@@ -64,24 +66,30 @@ pub fn build_program() -> Vec<u8> {
patch_jump(&mut rom, jump_to_blue_case_offset, blue_case);
patch_jump(&mut rom, jump_to_draw_after_green_offset, draw);
BytecodeModule {
version: 0,
const_pool: vec![],
functions: vec![FunctionMeta {
code_offset: 0,
code_len: rom.len() as u32,
param_slots: 0,
local_slots: 1,
return_slots: 0,
max_stack_slots: 8,
}],
code: rom,
debug_info: Some(DebugInfo {
pc_to_span: vec![],
function_names: vec![(0, "main".into())],
}),
exports: vec![Export { symbol: "main".into(), func_idx: 0 }],
syscalls: vec![
let code = rom;
let debug = DebugInfo { pc_to_span: vec![], function_names: vec![(0, "main".into())] };
let exports = [Export { symbol: "main".into(), func_idx: 0 }];
let registry = Registry::resolve(
RegistryDeclarations {
functions: vec![FunctionDecl {
code_len: code.len() as u32,
local_slots: 1,
max_stack_slots: 8,
..Default::default()
}],
..Default::default()
},
code.len(),
&mut LoadBudget::new(Default::default()),
)
.expect("resolved program declarations");
PbxModule {
registry: &registry,
constants: &[],
code: &code,
debug: Some(&debug),
exports: &exports,
syscalls: &[
SyscallDecl {
module: "gfx2d".into(),
name: "clear".into(),
@@ -98,7 +106,8 @@ pub fn build_program() -> Vec<u8> {
},
],
}
.serialize()
.serialize(&mut LoadBudget::new(Default::default()))
.expect("bounded v1 program")
}
pub fn manifest_json() -> Vec<u8> {
+37 -32
View File
@@ -1,8 +1,9 @@
use anyhow::Result;
use prometeu_bytecode::assembler::assemble;
use prometeu_bytecode::model::{
BytecodeModule, ConstantPoolEntry, DebugInfo, Export, FunctionMeta, SyscallDecl,
};
use prometeu_bytecode::load_limits::LoadBudget;
use prometeu_bytecode::model::{ConstantPoolEntry, DebugInfo, Export, SyscallDecl};
use prometeu_bytecode::registry::{FunctionDecl, Registry, RegistryDeclarations};
use prometeu_bytecode::registry_codec::PbxModule;
use prometeu_hal::asset::{
AssetCodec, AssetEntry, AssetId, BankType, PreloadEntry, SCENE_DECODED_LAYER_OVERHEAD_BYTES_V1,
SCENE_LAYER_COUNT_V1, SCENE_PAYLOAD_MAGIC_V1, SCENE_PAYLOAD_VERSION_V1,
@@ -81,34 +82,38 @@ pub fn generate() -> Result<()> {
heavy_load(&mut rom);
// light_load(&mut rom);
let functions = vec![FunctionMeta {
code_offset: 0,
code_len: rom.len() as u32,
param_slots: 0,
local_slots: 2,
return_slots: 0,
max_stack_slots: 32,
}];
let module = BytecodeModule {
version: 0,
const_pool: vec![
ConstantPoolEntry::String("stress".into()),
ConstantPoolEntry::String("frame".into()),
ConstantPoolEntry::String("overlay".into()),
ConstantPoolEntry::String("composer".into()),
],
functions,
code: rom,
debug_info: Some(DebugInfo {
pc_to_span: vec![],
function_names: vec![(0, "main".into())],
}),
exports: vec![Export { symbol: "main".into(), func_idx: 0 }],
syscalls,
};
let bytes = module.serialize();
let registry = Registry::resolve(
RegistryDeclarations {
functions: vec![FunctionDecl {
code_len: rom.len() as u32,
local_slots: 2,
max_stack_slots: 32,
..Default::default()
}],
..Default::default()
},
rom.len(),
&mut LoadBudget::new(Default::default()),
)
.expect("resolved program declarations");
let constants = vec![
ConstantPoolEntry::String("stress".into()),
ConstantPoolEntry::String("frame".into()),
ConstantPoolEntry::String("overlay".into()),
ConstantPoolEntry::String("composer".into()),
];
let debug = DebugInfo { pc_to_span: vec![], function_names: vec![(0, "main".into())] };
let exports = [Export { symbol: "main".into(), func_idx: 0 }];
let bytes = PbxModule {
registry: &registry,
constants: &constants,
code: &rom,
debug: Some(&debug),
exports: &exports,
syscalls: &syscalls,
}
.serialize(&mut LoadBudget::new(Default::default()))
.expect("bounded v1 program");
let mut out_dir = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
out_dir.pop(); // pbxgen-stress
@@ -209,7 +214,7 @@ fn heavy_load(rom: &mut Vec<u8>) {
rom.extend(asm("PUSH_I32 2\nPUSH_CONST 0\nHOSTCALL 1"));
let after_log = rom.len() as u32;
rom.extend(asm("FRAME_SYNC\nRET"));
rom.extend(asm("RET"));
let patch = |buf: &mut Vec<u8>, imm_offset: usize, target: u32| {
buf[imm_offset..imm_offset + 4].copy_from_slice(&target.to_le_bytes());
+1
View File
@@ -36,3 +36,4 @@ prometeu-bytecode = { path = "../../console/prometeu-bytecode" }
prometeu-hal = { path = "../../console/prometeu-hal" }
base64 = "0.22"
png = "0.17"
prometeu-test-support = { path = "../../dev/prometeu-test-support" }
@@ -1,8 +1,10 @@
use base64::{Engine as _, engine::general_purpose::STANDARD};
use prometeu_bytecode::SourceSpan;
use prometeu_bytecode::assembler::assemble;
use prometeu_bytecode::model::{BytecodeModule, DebugInfo, Export, FunctionMeta, SyscallDecl};
use prometeu_bytecode::model::{DebugInfo, Export, SyscallDecl};
use prometeu_bytecode::registry::FunctionDecl;
use prometeu_host_headless::{AdvanceFramesStop, HeadlessHost};
use prometeu_test_support::program::{TestProgram, int64_signature};
use serde_json::{Value, json};
use std::collections::HashMap;
use std::fs;
@@ -175,16 +177,16 @@ fn cartridge(code: &str, gfx: bool) -> TempDir {
fn cartridge_bytes(code: Vec<u8>, gfx: bool) -> TempDir {
let dir = TempDir::new();
let module = BytecodeModule {
version: 0,
let module = TestProgram {
const_pool: vec![],
functions: vec![FunctionMeta {
functions: vec![FunctionDecl {
code_offset: 0,
code_len: code.len() as u32,
param_slots: 0,
local_slots: 0,
return_slots: 0,
max_stack_slots: 8,
signature: int64_signature(0, 0),
captures: vec![],
name: None,
}],
code,
debug_info: Some(DebugInfo {
@@ -216,7 +218,7 @@ fn cartridge_bytes(code: Vec<u8>, gfx: bool) -> TempDir {
}
fn colored_cart() -> TempDir {
cartridge("PUSH_I64 4278190335\nHOSTCALL 0\nFRAME_SYNC\nRET\n", true)
cartridge("PUSH_I64 4278190335\nHOSTCALL 0\nRET\n", true)
}
fn boot(client: &mut Client, dir: &TempDir) {
client.ok("boot", json!({"path":dir.0}));
@@ -342,12 +344,10 @@ fn independent_processes_match_pixels_ids_state_and_fault() {
// Color is selected by the real normalized RIGHT-down intrinsic.
let mut code = assemble("INTRINSIC 0x210E\n").unwrap();
let jump = code.len() + 2;
code.extend(
assemble("JMP_IF_FALSE 0\nPUSH_I64 4278190335\nHOSTCALL 0\nFRAME_SYNC\nRET\n").unwrap(),
);
code.extend(assemble("JMP_IF_FALSE 0\nPUSH_I64 4278190335\nHOSTCALL 0\nRET\n").unwrap());
let blue = code.len() as u32;
code[jump..jump + 4].copy_from_slice(&blue.to_le_bytes());
code.extend(assemble("PUSH_I64 65535\nHOSTCALL 0\nFRAME_SYNC\nRET\n").unwrap());
code.extend(assemble("PUSH_I64 65535\nHOSTCALL 0\nRET\n").unwrap());
let dir = cartridge_bytes(code, true);
let run = |c: &mut Client| {
boot(c, &dir);
@@ -382,7 +382,7 @@ fn partial_guest_fault_and_host_watchdog_are_distinct_outcomes() {
code.extend(assemble("JMP_IF_FALSE 0\nTRAP\n").unwrap());
let next = code.len() as u32;
code[jump..jump + 4].copy_from_slice(&next.to_le_bytes());
code.extend(assemble("PUSH_I64 255\nHOSTCALL 0\nFRAME_SYNC\nRET\n").unwrap());
code.extend(assemble("PUSH_I64 255\nHOSTCALL 0\nRET\n").unwrap());
let dir = cartridge_bytes(code, true);
let mut c = Client::new(&["--stdio"]);
c.initialize();
@@ -405,7 +405,7 @@ fn partial_guest_fault_and_host_watchdog_are_distinct_outcomes() {
#[test]
fn faults_and_boot_failures_are_structured_not_log_parsing() {
let dir = cartridge("TRAP\nFRAME_SYNC\nRET\n", false);
let dir = cartridge("TRAP\nRET\n", false);
let mut c = Client::new(&["--stdio"]);
c.initialize();
boot(&mut c, &dir);
@@ -949,6 +949,12 @@
"TraitCategory",
"DuplicateBuiltin",
"DuplicateArray",
"DuplicateFn",
"StructuralTypeCycle",
"CaptureIndex",
"CaptureCount",
"CapturedDirectCall",
"RemovedOpcode",
"ArrayCycle",
"DuplicateImplementation",
"MethodCount",
@@ -0,0 +1,177 @@
---
id: LSN-0061
ticket: vm-closures-captures-and-dynamic-calls
title: Typed Callables and Frame-Owned Continuations
created: 2026-10-08
tags: [vm, bytecode, closures, ownership, callbacks]
---
## Context
DEC-0047 established typed first-class function values, explicit capture metadata,
trait dispatch and a single directly owned VM execution context. Its runtime
delivery also activated the existing sealed Registry provider in production and
migrated internal producers. This lesson records the implemented result of
DSC-0052; the workflow scaffolding is disposable, while these explanations and the
[discussion index](../../index.ndjson) persist.
The normative references are [function values and closures](../../../docs/specs/runtime/02b-vm-function-values-and-closures.md),
[Registry and PBX v1](../../../docs/specs/runtime/02c-program-registry-and-pbx-v1.md),
[frame continuation](../../../docs/specs/runtime/09a-coroutines-and-cooperative-scheduling.md)
and [memory ownership](../../../docs/specs/runtime/03-memory-stack-heap-and-allocation.md).
The earlier [Registry lesson](../DSC-0058-program-registry-type-and-function-metadata/LSN-0059-registry-boundaries-and-owned-values.md)
explains the provider foundation; its historical production handoff is now
implemented in this runtime.
## Key Decisions
### Logical signatures survive flattening
A function value's structural identity includes both ordered parameter TypeIds
and ordered result TypeIds. Names, concrete FunctionId, capture types and physical
slot counts do not define that identity. Consequently, one Vec2 result and two
Float results remain distinct even though each occupies two execution slots.
Returning two callbacks likewise means two logical Fn results, each carried by
one handle. Tuple flattening needs to retain the logical lists before deriving
widths; counting slots cannot recover the signature afterward.
The Registry rejects duplicate Fn keys and structural cycles through Array/Fn
edges. Nominal Struct/Trait anchors end that structural traversal. Recursive
function calls, capturing another Fn and cyclic runtime objects remain useful
and legal: they are different kinds of recursion from an infinitely expanding
structural type descriptor.
### Environments belong to call frames
Every MAKE_CLOSURE creates a distinct heap instance, including an empty
environment. Copies preserve that instance's identity. The environment's declared
capture groups are separate from the public function signature; no hidden arg0
is inserted. CALL_CLOSURE consumes the caller's Fn operand and makes the active
CallFrame retain its environment. GET_CAPTURE copies a complete declared group,
while GET_LOCAL addresses only public parameters and ordinary locals.
Immutable bindings can be copied into environments. A shared mutable binding can
use a private typed Struct cell captured by reference. In the implemented factory
tests, two callbacks update/read one cell, while a second factory allocates an
independent cell. This reuses existing field access, reference maps and GC rather
than introducing a second mutation mechanism. Lexical mutability and fresh-binding
rules still belong to frontend lowering. Capturing a reference preserves object
sharing; it does not freeze the referenced object.
Bound methods can use explicit adapters that capture a receiver or complete Trait
view. CALL_TRAIT itself resolves an immutable implementation-table entry: the
caller places explicit arguments before the view; the callee receives its concrete
receiver first and receives no ImplementationId parameter or closure environment.
Capturing implementation targets are rejected because that dispatch cannot
provide their environment.
### A frame boundary differs from entry completion
VM owns its PC, operand stack, call stack and globals directly. Preparing an entry
allocates no Coroutine object. Guest coroutine instructions and ready/sleeping
queues were removed; the independent render scheduler and asset workers retain
their own protocols.
FRAME_SYNC ends a logical frame and preserves the next PC, live operands, locals
and environments. It can occur inside an ordinary callee or a closure. Preparing
boot again after this boundary would replay the caller and abandon that
continuation. Successful RET of the last root instead completes the entry, so a
recurring host can prepare FunctionId 0 on the next frame while preserving the
global init guard. Budget exhaustion preserves the current open frame and does
not submit another visual packet or give callbacks an extra budget.
These distinctions let consumers advance persistent operations through short
ordinary frame steps and call Fn values when appropriate. The runtime does not
need suspended coroutine instances to represent callbacks. UI/tween consumers
and native callback registration/delivery need their own integration contracts;
this delivery created neither API.
## Patterns and Algorithms
The sealed image resolves ordered group layouts and capture offsets once. PBX v1
adds Fn tag 4 and requires captures section 8, including explicit empty lists for
noncapturing bodies. The function-table encoding stays unchanged. Mandatory
metadata provides a deterministic rejection boundary for older images rather
than guessing captures from public argument widths. Internal producers and both
shipped cartridges now use the same bounded writer and production loader.
Callable boundaries validate complete groups and reserve capacity before
consuming operands or publishing a frame/object. Their attempt costs are 8+C
for creation, 6 for an indirect call, 2+W for capture access and 6 for Trait dispatch.
Faults retain the charged attempt cost and preserve callable source operands and
owners. A positive slice admits one whole instruction even when its cost exceeds
the remaining budget; budget zero admits no instruction. Allocation refusal does
not trigger rescue GC.
GC roots include every live operand/global and the Closure retained by every
active frame. Environments trace whole groups, including Trait/Dynamic components,
references, shared cells and String owners. Successful root return transfers
results to the operand stack before threshold collection. Those results remain
roots until consumption, replacement, reset or unload. Threshold opportunities
are FRAME_SYNC and successful last-root RET; an ordinary callee return or entry
preparation adds no collection event. Unreachable closure/cell cycles are collected
by the existing mark-sweep algorithm.
An inspection ValueSnapshot can retain native String content, but copying a raw
HeapRef does not establish a guest root or authorize cross-session import.
Compact handle bits cannot identify foreign provenance if numerical handles
collide. Trusted native callers must preserve session provenance; the runtime
does not gain a generic Fn retention/delivery API from inspection snapshots.
## Pitfalls
- Comparing physical widths loses logical argument/result identity.
- Adding captures to public parameters makes function types depend on lowering
details and shifts ordinary local addressing.
- Rooting only the caller's Fn operand loses an active environment after that
operand is consumed. Rooting frame environments fixes its full lifetime.
- Restarting entry after FRAME_SYNC loses nested continuations; retaining context
after completed root RET fails to implement recurring entry execution.
- Treating callback calls as another scheduling phase changes frame/budget
semantics. These calls are ordinary execution in the same context.
- Keeping an unchecked fixture constructor for valid programs leaves a second
execution authority. Valid fixtures now use official sealed images; test-only
corrupted-state injection remains limited to defensive failure probes.
## Published Evidence
The final `cargo test --workspace` run passed 880 tests with zero failures and
9 existing ignored tests. It exercised the bytecode, VM, HAL, System, firmware,
layer, both host, generator and CLI packages. The ignored cases are three explicit
layout/load/ownership measurement probes, five desktop localhost transport tests
and one packaged-installation smoke requiring an extracted distribution archive.
None is claimed as executed. `cargo fmt --all -- --check`, `git diff --check` and
`discussion validate` passed; edited documentation and published lesson links
were checked for local targets and workflow references were removed from docs.
Discriminating evidence includes:
- Registry v1: 37 passed / 1 ignored, independent 193-byte minimal module,
independent Fn/capture payload bytes, mandatory-section failures, logical
signature identity and finite structural graph checks. Registry ISA: 7 passed.
- VM callable unit probes: 13 passed, including attempt costs, zero budget,
overshoot, quota rollback, active/result roots, mixed capture ownership,
malformed Trait views, bounded recursive calls and unreachable cycles.
- VM `typed_closures`: 13 passed, including unknown selected targets, Fn
pass/return/Struct/Array/Dynamic storage, independent factories, bound adapters,
direct captured-target rejection and 3000 recurring entries with zero execution
heap allocations under a zero handle quota.
- Layer tuple-returned callbacks and frame continuation: one passing case each.
Existing typed collection/native/string/reference cases also pass through the
sealed execution path.
- Headless `typed_runtime`: 5 passed. Nested callee/closure sync retains local 73
and init count 1 across six frames; a long nested Fn spans budget slices without
opening another frame. Native type and null-Fn traps plus removed-opcode load
rejection retain machine context. Wire tests additionally cover executed closure
quota refusal and an active native type fault.
- Both generator binaries regenerated their program.pbx files. Dummy Boy and
Stress each complete six production-host frames with progressing visuals;
direct sealed-image side-effect observation confirms six frame-command
executions and exactly one Stress scene bind. Manifests/assets are unchanged.
This is bounded functional regression evidence, not long-run soak or game
headroom certification. The [producer handoff](../../../docs/vm-arch/registry-producer-handoff.md)
names external compiler targets and acceptance cases: exact v1 metadata/bytes,
logical signatures, named-argument evaluation order, capture lowering, callable
behavior and structured failures. Studio/FE adaptation remains consumer work and
has not been executed by this runtime delivery.
@@ -167,3 +167,7 @@ The [collection ISA table](02-vm-instruction-set.md#typed-collection-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.
## Typed Callable Costs
Charge each admitted attempt once, including trap: MAKE_CLOSURE 8+C (declared capture-slot sum), CALL_CLOSURE 6, GET_CAPTURE 2+W (selected complete-group width), CALL_TRAIT 6. Direct CALL/RET retain 5/4. No extra callback budget, partial-instruction pause or GC-cycle redesign. Zero budget executes nothing; positive budget may admit an instruction that overshoots. Root-return GC does not grant cycles, advance frames or invoke guest cleanup.
+13 -10
View File
@@ -22,7 +22,7 @@ This chapter does not fully restate:
- detailed value and calling semantics;
- heap/gate/GC internals;
- coroutine scheduling internals;
- single-context continuation internals;
- host ABI policy.
Those now live in focused companion specs:
@@ -55,19 +55,19 @@ Each frame:
2. the VM runs until:
- the frame budget is consumed; or
- a `FRAME_SYNC` instruction is reached;
3. at `FRAME_SYNC`, the VM reaches the primary safepoint for GC and cooperative scheduling;
3. at `FRAME_SYNC`, the VM reaches the primary safepoint for threshold GC and host handoff;
4. control returns to firmware/runtime orchestration.
`FRAME_SYNC` is the primary VM synchronization point. It is the boundary where the machine can safely account for:
- GC opportunity;
- coroutine handoff;
- logical frame handoff;
- frame-completion semantics;
- deterministic return to firmware.
## 4 Instruction Families
The public VM instruction surface is documented at the bytecode level in [`../virtual-machine/ISA_CORE.md`](../../vm-arch/ISA_CORE.md). At the machine/spec level, the instruction families are:
The public VM instruction surface is documented at the bytecode level in [Core ISA](../../vm-arch/ISA_CORE.md). At the machine/spec level, the instruction families are:
- execution control:
- `NOP`, `HALT`, `JMP`, `JMP_IF_FALSE`, `JMP_IF_TRUE`, `TRAP`, `FRAME_SYNC`
@@ -78,14 +78,15 @@ The public VM instruction surface is documented at the bytecode level in [`../vi
- variable access:
- globals and locals
- function calls:
- `CALL`, `RET`
- `CALL`, `RET`, `CALL_TRAIT`
- function values:
- `MAKE_CLOSURE`, `CALL_CLOSURE`
- cooperative concurrency:
- `SPAWN`, `YIELD`, `SLEEP`
- `MAKE_CLOSURE`, `CALL_CLOSURE`, `GET_CAPTURE`
- VM/host boundary:
- `HOSTCALL`, `SYSCALL`, `INTRINSIC`
Former coroutine numbers 0x54–0x56 are reserved. `SPAWN`, `YIELD` and `SLEEP`
reject during loading, including unreachable code, and cannot be emitted by the assembler.
The machine-level rule is simple:
- opcodes define explicit behavior;
@@ -113,7 +114,7 @@ The verifier is structural. It does not replace runtime validation of dynamic va
- [`02b-vm-function-values-and-closures.md`](02b-vm-function-values-and-closures.md) defines closure representation and function-value behavior.
- [`03-memory-stack-heap-and-allocation.md`](03-memory-stack-heap-and-allocation.md) defines stack/heap, handles, object layout, and GC.
- [`09-events-and-concurrency.md`](09-events-and-concurrency.md) defines events, timers, and the frame boundary model.
- [`09a-coroutines-and-cooperative-scheduling.md`](09a-coroutines-and-cooperative-scheduling.md) defines coroutine lifecycle and scheduling.
- [`09a-coroutines-and-cooperative-scheduling.md`](09a-coroutines-and-cooperative-scheduling.md) defines single-context continuation and entry completion.
- [`16-host-abi-and-syscalls.md`](16-host-abi-and-syscalls.md) defines the syscall ABI boundary.
## 7 Summary
@@ -125,7 +126,7 @@ The PVM is:
- frame-synchronized;
- verifier-gated;
- closure-capable;
- coroutine-capable;
- single execution context; retired SPAWN/YIELD/SLEEP are rejected;
- embedded inside the larger PROMETEU console model, not equal to it.
## Program Registry v1 integration
@@ -154,3 +155,5 @@ STRUCT operations require a Struct descriptor; ARRAY operations require an Array
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).
Typed callable instructions are MAKE_CLOSURE `(FunctionId,FnTypeId)`, CALL_CLOSURE `(FnTypeId)`, GET_CAPTURE `(index)` and CALL_TRAIT `(TraitTypeId,method_index)`. Their groups, encodings and attempted costs are defined in the [Fn contract](02b-vm-function-values-and-closures.md). Numbers 0x54–0x56 stay reserved and reject anywhere at load.
@@ -125,7 +125,7 @@ RET requires exactly R temporaries, validates ordered types, releases frame owne
Verifier decodes every function range, validates instruction boundaries/IDs/jump destinations, and analyzes structurally reachable control flow. Track temporary height and local/temporary facts in a finite domain: Unknown, known null, carrier facts and proven semantic/multi-slot groups. Initial parameters follow signatures; other locals start null. GET copies facts; SET replaces. Equal facts survive joins; conflicting facts become Unknown, while unequal heights are rejected. Do not require one permanent local type or infer unbounded unions/branch conditions.
Use a bounded worklist to fixed point, reprocessing widened states; decide state-dependent type errors after convergence so visitation order cannot cause rejection. Signature contracts suffice for calls; no interprocedural body inference is required. Partial group mutation invalidates relational facts. Unknown is not proof of compatibility and does not alone reject code: retain complete runtime checks. Type knowledge alone does not eliminate null/generation/bounds checks. Retain current UnknownClosureCallee protection until the separate callable/closure/coroutine contract provides a replacement contract. Exceeding memory/work budget rejects loading, never skips verification.
Use a bounded worklist to fixed point, reprocessing widened states; decide state-dependent type errors after convergence so visitation order cannot cause rejection. Signature contracts suffice for calls; no interprocedural body inference is required. Partial group mutation invalidates relational facts. Unknown is not proof of compatibility and does not alone reject code: retain complete runtime checks. Type knowledge alone does not eliminate null/generation/bounds checks. CALL_CLOSURE uses expected FnTypeId to establish parameter/result groups even for unknown concrete targets. GET_CAPTURE accesses typed metadata of the enclosing function; environment is retained by CallFrame without hidden arg0. Known mismatch rejects, Unknown retains runtime checks. Exceeding memory/work budget rejects loading, never skips verification.
Builtin IDs, exact slot carriers, nullable defaults and stored layouts are defined in [Program Registry and PBX v1](02c-program-registry-and-pbx-v1.md#values-storage-and-initialization). A fixed list of results does not imply a tuple object or boxing. Parameter names are optional signature metadata; frontend argument reordering must preserve source evaluation order.
@@ -3,68 +3,98 @@
Domain: VM closures and function values
Function: normative
This chapter defines how the PVM models first-class function values.
Didactic companion: [Typed Callables and Frame-Owned Continuations](../../../discussion/lessons/DSC-0052-vm-closures-captures-and-dynamic-calls/LSN-0061-typed-callables-and-frame-owned-continuations.md).
## 1 First-Class Function Model
## 1 Typed First-Class Functions
The PVM treats user function values as closures.
Registry Fn (tag 4) contains Signature: ordered logical parameter/result TypeIds.
Optional names are metadata. Identity is exactly these lists, excluding FunctionId,
captures and physical widths. Duplicate Fn keys reject without ID remapping or
variance. One Vec2 result and two Float results differ despite equal slot counts.
Structural expansion through Array elements and Fn parameters/results MUST be
finite; nominal Struct/Trait stop expansion. Forward references, recursive calls,
captured Fn values and runtime object cycles remain legal.
This means:
Fn occupies one Value slot, an 8-byte/8-aligned guest HeapRef in typed storage, and
defaults to Null. Invoking absence traps. Fn is allowed in parameters/results,
Struct/Array/Dynamic; REF_* retain their category rules and Fn does not implement
Trait implicitly. Syscalls are not first-class values.
- functions can be stored in variables;
- functions can be passed as arguments;
- functions can be returned from other functions;
- function values carry explicit runtime representation.
## 2 Instances and Captures
Even functions without captures may be represented as closures with an empty capture set.
Every value uses a heap Closure, including empty captures:
`Closure { fn_type_id, function_id, typed_capture_components[] }`.
Distinct creation has distinct identity; copying a reference preserves identity.
Equality compares handles, never code/environment. Target and capture bindings
are immutable; objects referenced by them may remain mutable.
## 2 Closure Layout
Immutable bindings are captured by value. Shared mutable lexical bindings use
private typed Struct cells with ordinary field operations, common to creator and
closures. Another factory can allocate another cell. No Cell category or
SET_CAPTURE is introduced; language lowering belongs to each frontend.
Closures are heap objects.
PBX v1 MUST include exactly one captures section, kind 8: little-endian
`function_count:u32`, then per FunctionId `capture_count:u32` and ordered capture
TypeIds:u32. Outer count equals the function table; empty lists are explicit.
Offsets/widths/maps derive at load. Records, capacities and graph work use existing
budgets. Images lacking this section or using old closure encodings reject.
Conceptual layout:
## 3 Calls and Environments
```
Closure {
func_id
captures[]
}
```
Opcodes are u16, immediates u32, all little-endian:
Captures may be:
| Instruction | Immediates | Stack / attempted cost |
| --- | --- | --- |
| MAKE_CLOSURE 0x52 | FunctionId, FnTypeId | capture groups -> Fn; 8+C |
| CALL_CLOSURE 0x53 | expected FnTypeId | args..., Fn -> results... after RET; 6 |
| GET_CAPTURE 0x57 | capture index | append complete capture group; 2+W |
| CALL_TRAIT 0x58 | TraitTypeId, method index | args..., receiver, ImplementationId -> results...; 6 |
- copied values;
- handles to heap objects.
C is declared capture-slot sum; W is indexed capture width. Charge once per
attempt including traps. CALL/RET retain 5/4; zero budget executes nothing and
positive budget admits a whole instruction, which may overshoot.
Closure environments are part of the GC root graph as long as the closure remains reachable.
CALL_CLOSURE validates expected Fn type and target signature. CallFrame retains
the Closure as environment root, without hidden arg0 in public parameters.
GET_LOCAL addresses public parameters/locals; GET_CAPTURE reads that frame's
indexed environment. Nested calls own separate environments. Nonempty-capture
bodies cannot be entered by direct CALL or host preparation without environment.
A bound-method Fn can use an explicit adapter capturing its receiver.
## 3 Direct and Indirect Calls
CALL_TRAIT validates the complete view and resolves FunctionId through the
immutable implementation table. Callee gets concrete receiver first, then explicit
method arguments; ImplementationId is not a parameter. Exact method signatures
and empty target captures are required. Absent/malformed/stale/incompatible views
fault. No lookup by name, implicit wrappers, variance or adaptations are added.
The PVM supports two forms of invocation:
## 4 Verification, Faults and Resources
| Opcode | Description |
| -------------- | -------------------------------------- |
| `CALL` | Direct call by function id |
| `CALL_CLOSURE` | Indirect call through a closure handle |
Expected FnTypeId supplies parameter/result groups even for unknown concrete
targets. Known mismatch rejects loading; Unknown retains full runtime checks.
Validate every instruction and metadata before image publication. Creation,
call and capture access validate whole groups and reserve capacity before consume
or publication. Refusal preserves operands/owners and publishes no partial object
or frame; provisional reservations refund and attempted cycles remain. No quota
rescue GC. Use existing distinct NullReference/InvalidHandle/Type/Resource traps.
Fn can invoke syscalls, mutate and fault: no purity flag, fault isolation, separate
budget, guest unwind or rollback of earlier body effects.
For `CALL_CLOSURE`:
## 5 Context, GC and Host
1. the closure handle is read from the stack;
2. the VM resolves the target function;
3. captured environment state becomes available to the callee according to the closure calling convention.
VM owns one PC, operand/call stacks and globals directly. FRAME_SYNC retains
frames/locals/environments and resumes next PC in any body. Budget exhaustion
retains the same logical frame. Last-root RET completes entry, rooting results
before threshold GC. Recurring host entry remains FunctionId 0 with init once.
## 4 Verification and Safety
Threshold GC opportunities are FRAME_SYNC and successful last-root RET. Roots
include globals, live stack values, Closures retained by every active CallFrame
and legally retained native/host roots. Trace whole capture groups and shared
cells; unreachable cycles collect. Results remain roots until consumed/replaced,
reset/unload. No GC at ordinary callee RET or allocation/quota rescue.
HeapRef copies/inspection snapshots establish no guest roots or cross-session
imports. No native registration/delivery/reentry API is created here. Guest
callbacks are ordinary Fn calls in the main execution context.
The verifier ensures, at minimum:
- closure call sites have coherent arity;
- invalid closure call shapes are rejected or trapped according to the verifier/runtime boundary;
- return-slot contracts remain valid.
Handle validity, heap reachability, and dynamic misuse remain subject to runtime checks where static proof is not possible.
## 5 Relationship to Memory and GC
- Closure objects live in heap memory, so their object model is constrained by [`03-memory-stack-heap-and-allocation.md`](03-memory-stack-heap-and-allocation.md).
- Captured heap references participate in the GC root graph.
- Closures are function values, not syscalls; syscall calls remain a separate non-first-class boundary defined in [`16-host-abi-and-syscalls.md`](16-host-abi-and-syscalls.md).
See [memory](03-memory-stack-heap-and-allocation.md),
[Registry/PBX](02c-program-registry-and-pbx-v1.md) and
[host ABI](16-host-abi-and-syscalls.md).
@@ -3,7 +3,7 @@
Domain: VM program metadata, binary format, typed storage and resource boundaries
Function: normative
This chapter defines the required v1 contract; implementation is being migrated and this publication is not a claim that all execution paths already satisfy it. The callable/closure/coroutine type boundary remains separately specified: no provisional untyped reference type is authorized. Existing closure/coroutine behavior must be preserved until its approved replacement can be integrated.
The production loader, internal producers and runtime examples use this sealed v1 contract. Typed Fn and frame environments follow [the function-value contract](02b-vm-function-values-and-closures.md); retired coroutine instructions reject at load. No provisional untyped reference is authorized.
Didactic companion: [Registry Boundaries and Owned Values](../../../discussion/lessons/DSC-0058-program-registry-type-and-function-metadata/LSN-0059-registry-boundaries-and-owned-values.md).
@@ -15,11 +15,11 @@ The requirements below use MUST/MUST NOT semantics. The Registry owns type/funct
- Registry logically joins Type Registry and Function Registry. It belongs to ProgramImage, is immutable after successful resolution, and is shared across sessions. Metadata is native, outside the guest GC heap; it has no HeapRef and remains alive while any image consumer needs it. Code, constants, exports and debug are separate responsibilities.
- TypeId, FunctionId and ImplementationId are distinct u32 newtypes, dense zero-based table indices local to the image. TraitId is a TypeId checked as Trait, not a separate namespace. Field and method indices are owner-local. BuiltinId, IntrinsicId and constant-pool tags are separate domains. Names never establish identity.
- Struct/Trait are nominal; identical names/layouts do not merge them. Producers link references and deduplicate the same declaration across modules. Array identity is structural by element TypeId, invariant and mutable, with length on instances; nested arrays store array references.
- One descriptor per imported BuiltinId and per Array element TypeId; duplicate records are rejected without loader remapping. Forward references and nominal reference recursion are legal. Array-only cycles and infinite inline layouts, overflow and wrong-category references are rejected with bounded graph processing. Runtime object cycles remain legal.
- Four descriptor categories: Builtin, Struct, Array, Trait. No Service or input endpoint category. Services lower to a nominal Struct and one rooted global instance per session; singleton language rules stay in the frontend. Builtin-value trait adapters are explicit Struct allocations with separate nominal identity.
- One descriptor per imported BuiltinId and per Array element TypeId; duplicate records are rejected without loader remapping. Forward references and nominal reference recursion are legal. Cycles exclusively through Array/Fn structural edges and infinite inline layouts, overflow and wrong-category references are rejected with bounded graph processing. Runtime object cycles remain legal.
- Five descriptor categories: Builtin, Struct, Array, Trait, Fn. Fn identity is its ordered parameter/result TypeIds, ignoring names; duplicate Fn keys reject. Nominal Struct/Trait stop structural expansion. No Service or input endpoint category. Services lower to a nominal Struct and one rooted global instance per session; singleton language rules stay in the frontend. Builtin-value trait adapters are explicit Struct allocations with separate nominal identity.
- Function signatures contain ordered typed parameters/results. Results have fixed semantic arity; zero results means zero slots, not null, and multiple results do not require tuple objects. A vec2 is one semantic result occupying two slots. Widths are derived, not duplicated in PBX.
- Parameter names are optional signature metadata independent of debug. Frontends reorder named arguments to signature order while preserving source evaluation order, using temporaries. Mixing/default-argument syntax and diagnostics stay with frontends; optional/default parameters are not implicitly introduced.
- Trait implementations are unique per (Struct, Trait), complete, immutable and ordered by method index. Explicit parameter/result TypeIds, order and arity match exactly; the implementation function has its concrete receiver as first parameter. No variance or implicit adaptation: frontend adapter functions may satisfy the exact signature. Actual trait dispatch belongs to the separate callable/closure/coroutine contract.
- Trait implementations are unique per (Struct, Trait), complete, immutable and ordered by method index. Explicit parameter/result TypeIds, order and arity match exactly; the implementation function has its concrete receiver as first parameter. No variance or implicit adaptation: frontend adapter functions may satisfy the exact signature. CALL_TRAIT resolves TraitTypeId/method index through this immutable table; targets have empty captures and receive concrete receiver first, never ImplementationId as an argument.
## PBX v1 encoding
@@ -35,6 +35,7 @@ PBX v1 only: magic `PBX\0`, little-endian, 32-byte header, zero reserved bytes a
| 5 | syscalls | exactly once |
| 6 | types | exactly once |
| 7 | implementations | exactly once |
| 8 | captures | exactly once |
The fixed header is:
@@ -73,11 +74,13 @@ Encoding primitives: list=`count:u32` followed by records; optional name=`presen
| Record | Exact field order |
| --- | --- |
| Type | kind:u8, optional name, category payload; tags 0 Builtin / 1 Struct / 2 Array / 3 Trait |
| Type | kind:u8, optional name, category payload; tags 0 Builtin / 1 Struct / 2 Array / 3 Trait / 4 Fn |
| Builtin payload | builtin_id:u32 |
| Struct payload | ordered field list |
| Array payload | element_type_id:u32 |
| Trait payload | ordered method list; each method has optional name, explicit-parameter list, result list; concrete receiver is not repeated here |
| Fn payload | ordered parameter list, result list; names do not define identity |
| Captures section | function_count:u32, then each FunctionId in order: capture_count:u32 and TypeIds:u32; counts match functions, empty lists explicit |
| Function | optional name, parameter list, result list, code_offset:u32, code_len:u32, local_slots:u32, max_stack_slots:u32 |
| Implementation | owner_type_id:u32, trait_type_id:u32, method_count:u32, FunctionIds:u32 in trait-method order; count must match |
@@ -103,7 +106,7 @@ Unlisted BuiltinIds, including zero and removed input IDs 0x0100–0x0102, canno
Preserve declared field order; round each offset to field alignment and final payload size to maximum alignment. Empty Struct has payload zero, alignment one, but retains object identity/header. Array stride is aligned stored-element size; Array<Struct> stores references, not Struct payloads. Checked arithmetic precedes allocation. Padding is not data or a GC reference. Allocate truly aligned storage or use appropriate accesses; Vec<u8> does not justify unsafe casts. Native Arc/Value layouts are target-dependent and never a portable PBX ABI.
Defaults apply before publication/GC, including reused storage: Int32/Int64 zero, Float +0.0, Bool false, Struct/Array/String references null, vec2 (+0,+0), color transparent raw zero, pixel (0,0,transparent), trait absent, Dynamic untyped null. Do not instantiate referenced objects/subarrays or invoke source constructors. Empty arrays require no element values. Catalog defaults are resolved without arbitrary per-element callbacks. Native values must be constructed correctly rather than assumed valid after memset.
Defaults apply before publication/GC, including reused storage: Int32/Int64 zero, Float +0.0, Bool false, Struct/Array/Fn/String references null, vec2 (+0,+0), color transparent raw zero, pixel (0,0,transparent), trait absent, Dynamic untyped null. Do not instantiate referenced objects/subarrays or invoke source constructors. Empty arrays require no element values. Catalog defaults are resolved without arbitrary per-element callbacks. Native values must be constructed correctly rather than assumed valid after memset.
Heap references: index:u32 + generation:u32, stored size/alignment 8, still one Value::HeapRef slot. Generation starts at one; zero is reserved. Compact null=(0,0), while index zero remains valid with a live generation. Other generation-zero pairs are invalid. Validate index/liveness/generation/type before dereference. Increment generation on reclamation; retire the slot after its maximum-generation incarnation rather than wrap. Handles belong to their heap/session; native boundaries preserve provenance without introducing a heap ID into this encoding.
@@ -143,7 +146,7 @@ RET requires exactly R temporaries, validates ordered types, releases frame owne
Verifier decodes every function range, validates instruction boundaries/IDs/jump destinations, and analyzes structurally reachable control flow. Track temporary height and local/temporary facts in a finite domain: Unknown, known null, carrier facts and proven semantic/multi-slot groups. Initial parameters follow signatures; other locals start null. GET copies facts; SET replaces. Equal facts survive joins; conflicting facts become Unknown, while unequal heights are rejected. Do not require one permanent local type or infer unbounded unions/branch conditions.
Use a bounded worklist to fixed point, reprocessing widened states; decide state-dependent type errors after convergence so visitation order cannot cause rejection. Signature contracts suffice for calls; no interprocedural body inference is required. Partial group mutation invalidates relational facts. Unknown is not proof of compatibility and does not alone reject code: retain complete runtime checks. Type knowledge alone does not eliminate null/generation/bounds checks. Retain current UnknownClosureCallee protection until the separate callable/closure/coroutine contract provides a replacement contract. Exceeding memory/work budget rejects loading, never skips verification.
Use a bounded worklist to fixed point, reprocessing widened states; decide state-dependent type errors after convergence so visitation order cannot cause rejection. Signature contracts suffice for calls; no interprocedural body inference is required. Partial group mutation invalidates relational facts. Unknown is not proof of compatibility and does not alone reject code: retain complete runtime checks. Type knowledge alone does not eliminate null/generation/bounds checks. CALL_CLOSURE derives ordered parameter/result groups from its expected FnTypeId, including unknown concrete targets; known mismatches reject, unknown values retain runtime checks. Exceeding memory/work budget rejects loading, never skips verification.
## Input
@@ -232,5 +235,5 @@ Nested records count fields, methods, parameters/results and implementation Func
| Runtime operation temporary buffers | 64 MiB per session |
| Call depth including entry frame | 1,024 frames per execution flow |
Auxiliary state includes capacities of active/suspended Value stacks, frames, globals, handles/free lists, scheduler queues, string ledgers and persistent GC structures. Moving stacks between VM and coroutine transfers charges; never bill the same stack in both auxiliary and heap domains. Coroutine header/own payload remains heap-owned. Per-flow depth and per-frame cap coexist with aggregate session auxiliary cap. No separate task quota/lifecycle design is added here. Constants are checked at load; runtime excess traps. Growth must not geometrically reserve beyond available quota. Cycle/frame budgets remain separate. Asset and host admission limits are outside these totals.
Auxiliary state includes capacities of the VM operand stack, CallFrames, globals, handles/free lists, string ledgers and persistent GC structures. The VM owns one context directly; entry preparation allocates no heap execution object. Closure headers and capture payloads remain heap-owned. Call depth and per-frame cap coexist with aggregate session auxiliary cap. Constants are checked at load; runtime excess traps. Growth must not geometrically reserve beyond available quota. Cycle/frame budgets remain separate. Asset and host admission limits are outside these totals.
@@ -113,7 +113,7 @@ Properties:
- there is no raw pointer arithmetic in the VM model;
- layout rules are explicit and verifier/runtime-friendly.
Closures and coroutine-owned state may build on top of this memory model, but their behavioral rules are documented separately:
Closures and frame-owned environments use this memory model; their behavioral rules are documented separately:
- [`02b-vm-function-values-and-closures.md`](02b-vm-function-values-and-closures.md)
- [`09a-coroutines-and-cooperative-scheduling.md`](09a-coroutines-and-cooperative-scheduling.md)
@@ -126,7 +126,7 @@ The PVM uses a **mark-sweep collector**.
- non-moving in the baseline model;
- runs only at safepoints;
- primary safepoint: `FRAME_SYNC`.
- threshold opportunities: `FRAME_SYNC` and successful last-root `RET`, after rooting results.
### GC triggers
@@ -141,7 +141,6 @@ The collector marks from:
- operand stack;
- call stack frames;
- global variables;
- coroutine-owned execution state;
- closure environments;
- host-held roots where the host legally retains VM heap references.
@@ -195,7 +194,7 @@ Any violation results in a trap or rejected program image.
- [`02a-vm-values-and-calling-convention.md`](02a-vm-values-and-calling-convention.md) defines stack values and tuple/call-slot semantics.
- [`02b-vm-function-values-and-closures.md`](02b-vm-function-values-and-closures.md) defines closure function values.
- [`09a-coroutines-and-cooperative-scheduling.md`](09a-coroutines-and-cooperative-scheduling.md) defines coroutine state and scheduling behavior.
- [`09a-coroutines-and-cooperative-scheduling.md`](09a-coroutines-and-cooperative-scheduling.md) defines direct execution ownership and frame continuation.
- [`15-asset-management.md`](15-asset-management.md) defines asset-bank surfaces outside VM heap ownership.
- [`08-save-memory-and-memcard.md`](08-save-memory-and-memcard.md) defines save storage outside VM heap ownership.
- [`16a-syscall-policies.md`](16a-syscall-policies.md) defines host-root rules and host/heap interaction policy.
@@ -214,3 +213,7 @@ NEW fully initializes all storage before publishing a handle: primitive/builtin
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.
## Typed Fn and Root-Return Collection
Threshold GC opportunities are FRAME_SYNC and successful RET of the last root, after results are transferred and rooted. No automatic GC at ordinary callee RET, entry preparation or allocation/quota refusal. VM owns its single execution context directly. Roots include globals, all live operand values, Closures retained by every active CallFrame and legally retained native/host roots. Trace complete typed capture/cell graphs; unreachable cycles collect. Inspection snapshots and raw handle copies create no guest root or session import. Results remain roots until consumed/replaced/reset/unload. Scratch refusal preserves owners and prohibits partial sweep.
+1 -1
View File
@@ -3,7 +3,7 @@
Domain: virtual hardware: graphics
Function: normative
Didactic companion: [`../learn/mental-model-gfx.md`](../runtime/learn/mental-model-gfx.md)
Didactic companion: [GFX Mental Model](../../../discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0011-mental-model-gfx.md)
## 1. Overview
@@ -5,7 +5,7 @@ Function: normative
This chapter defines events, timers, faults, and the frame-boundary model of the PROMETEU machine.
Coroutine lifecycle and cooperative scheduling details now live in a dedicated companion chapter.
Single-context continuation and retired coroutine operations are defined in the companion lifecycle chapter.
## 1 Core Philosophy
@@ -250,7 +250,9 @@ PROMETEU discourages:
## 12 Relationship to Other Specs
- [`09a-coroutines-and-cooperative-scheduling.md`](09a-coroutines-and-cooperative-scheduling.md) defines coroutine lifecycle and scheduling behavior.
- [`09a-coroutines-and-cooperative-scheduling.md`](09a-coroutines-and-cooperative-scheduling.md) defines single-context continuation, root completion and retired coroutine operations.
- [`10-debug-inspection-and-profiling.md`](10-debug-inspection-and-profiling.md) defines observability and diagnostics surfaces.
- [`12-firmware-pos-and-prometeuhub.md`](12-firmware-pos-and-prometeuhub.md) defines firmware orchestration at machine level.
- [`02-vm-instruction-set.md`](02-vm-instruction-set.md) defines VM execution inside this frame model.
Logical frames also complete on successful RET of the last root. FRAME_SYNC instead preserves context and resumes next PC; budget exhaustion preserves the same open frame. Neither preparation nor callback calls create a coroutine scheduling phase.
@@ -1,107 +1,36 @@
# Coroutines and Cooperative Scheduling
# Single Execution Context and Frame Continuation
Domain: VM coroutine model
Domain: VM execution lifecycle
Function: normative
This chapter isolates PROMETEU coroutine semantics from the broader event/frame model.
VM directly owns one PC, operand stack, call stack and globals. Entry preparation
does not allocate a heap execution object. There are no guest coroutine instances,
ready/sleeping queues, sleeper clock or coroutine scheduling phase.
## 1 Coroutine Model
SPAWN/YIELD/SLEEP are retired; 0x54–0x56 remain reserved. Loading MUST reject them
before execution, including unreachable code. Assembler rejects their mnemonics;
diagnostic decoding can identify retired numbers. No compatibility mode exists.
Other instruction numbers are unchanged.
PROMETEU provides coroutines as the only guest-visible concurrency model.
FRAME_SYNC closes a logical frame and preserves context. It has zero stack effect,
is not a terminator, can occur in any body and resumes next PC. Host MUST NOT
prepare fresh entry solely because sync occurred. Budget exhaustion/breakpoints
preserve the same open frame without draw publication or extra callback budget.
Coroutines are:
Successful RET of the last root completes entry and leaves rooted results on VM
stack. Recurring host may prepare FunctionId 0 next logical frame, preserving
globals/init guard. Callee RET does not close a frame. Replacement preparation
validates/reserves before releasing owners. HALT/trap/reset/unload retain their
contracts.
- cooperative;
- deterministic;
- scheduled only at safepoints;
- never preemptive.
Threshold GC opportunities are sync and successful root RET after result rooting.
Preparation, ordinary callee RET and allocation failure add no opportunity. GC
advances no clock/frame, grants no budget and invokes no guest cleanup/callback.
Asset/render workers retain their independent protocols and run no guest code;
no physical-core affinity is implied.
There is:
- no parallel execution;
- no hidden threads;
- no scheduler behavior outside explicit machine rules.
## 2 Coroutine Lifecycle
Each coroutine can be in one of the following states:
- `Ready`
- `Running`
- `Sleeping`
- `Finished`
Coroutine-local execution state includes, conceptually:
```
Coroutine {
call_stack
operand_stack
state
}
```
## 3 Scheduling
At each eligible scheduling boundary:
1. the scheduler selects the next coroutine;
2. ordering remains deterministic;
3. execution continues within the frame-budget model.
Baseline policy:
- round-robin or equivalent deterministic ordering;
- no surprise priority inversion hidden from the model;
- no preemption between safepoints.
## 4 Coroutine Operations
Typical operations:
| Operation | Description |
| --------- | ----------------------------- |
| `spawn` | Create a coroutine |
| `yield` | Voluntarily suspend execution |
| `sleep` | Suspend for N frames |
`yield` and `sleep` only take effect at safepoints.
## 5 Interaction with the Frame Loop
Coroutine scheduling happens inside the frame model, not beside it.
Conceptually:
```
FRAME N
------------------------
Sample Input
Deliver Events
Schedule Coroutine
Run VM
FRAME_SYNC
------------------------
```
This preserves:
- deterministic replay;
- explicit cost accounting;
- consistent host/runtime handoff.
## 6 Costs and Determinism
Coroutine management:
- consumes cycles;
- contributes to certification/cost reporting;
- remains part of the deterministic execution trace.
Nothing about scheduling is "free" or hidden.
## 7 Relationship to Other Specs
- [`09-events-and-concurrency.md`](09-events-and-concurrency.md) defines the broader frame/event model.
- [`02-vm-instruction-set.md`](02-vm-instruction-set.md) defines coroutine-related instruction families.
- [`03-memory-stack-heap-and-allocation.md`](03-memory-stack-heap-and-allocation.md) defines coroutine-owned execution state in the memory model.
Persistent operations can advance through short steps in normal frame execution
and invoke typed Fn callbacks. UI/SDK APIs and future coroutine protocols require
separate contracts. See [Fn](02b-vm-function-values-and-closures.md),
[events](09-events-and-concurrency.md) and
[memory](03-memory-stack-heap-and-allocation.md).
@@ -3,7 +3,7 @@
Domain: machine diagnostics
Function: normative
Didactic companion: [`../learn/mental-model-observability-and-debugging.md`](../runtime/learn/mental-model-observability-and-debugging.md)
Didactic companion: [Observability and Debugging Mental Model](../../../discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0013-mental-model-observability-and-debugging.md)
## 1 Scope
@@ -29,7 +29,7 @@ The VM does not own the machine lifecycle. Firmware does.
- **PVM**: the VM subsystem that executes cartridge bytecode.
- **Cartridge**: the executable package loaded by firmware.
- **AppMode**: cartridge mode, currently `Game` or `System`.
- **Logical frame**: execution unit completed when the app reaches `FRAME_SYNC`.
- **Logical frame**: execution unit completed when the app reaches FRAME_SYNC or successfully returns from its last root. Sync preserves next-PC continuation; root return completes entry.
- **Host tick**: the host-driven outer update tick.
- **Process**: technical execution owned by POS lifecycle.
- **Task**: navigable presence associated with an app flow.
@@ -73,7 +73,7 @@ POS is responsible for:
At the VM boundary, POS must preserve:
- logical-frame semantics;
- `FRAME_SYNC` as the canonical frame boundary;
- `FRAME_SYNC` and successful last-root `RET` as logical frame boundaries;
- deterministic transition from host tick to VM slice execution.
Firmware must not treat a single global VM object as the canonical execution
@@ -336,9 +336,9 @@ These states express machine orchestration above the VM. They are not guest-visi
For game-mode execution, firmware/runtime coordination preserves:
- input latched per logical frame;
- execution in host-driven slices until `FRAME_SYNC`;
- execution in host-driven slices until `FRAME_SYNC` or successful last-root `RET`;
- present only when a logical frame completes;
- no frame present when budget ends before `FRAME_SYNC`.
- no frame present when budget ends before a logical frame boundary.
This keeps the machine model deterministic and observable.
+4
View File
@@ -221,3 +221,7 @@ The cartridge spec therefore distinguishes:
## Program Registry v1 integration
Program payloads MUST use the PBX v1 envelope and mandatory sections defined in [Program Registry and PBX v1](02c-program-registry-and-pbx-v1.md#pbx-v1-encoding). The file limit is 64 MiB and Code is limited to 32 MiB. Unsupported versions are rejected; runtime examples are regenerated rather than converted by a compatibility loader. The existing func_id = 0 boot authority is unchanged.
## Fn Execution Boundary
Typed Fn callbacks execute as ordinary guest calls on the single VM context. Boot remains physical FunctionId 0; preparation requires an empty capture environment and existing argument checks. FRAME_SYNC preserves context for next-PC resumption; successful last-root RET completes entry and leaves rooted results before threshold GC. No native callback registration, retention or reentry API is introduced; raw HeapRef/ValueSnapshot copies do not establish guest roots or authorize cross-session imports. Syscalls remain non-first-class.
@@ -387,3 +387,7 @@ Only user-defined functions and closures are first-class.
## Program Registry v1 integration
Native boundaries MUST respect the [Registry typed-value and ownership contract](02c-program-registry-and-pbx-v1.md): exact carriers and complete groups, generational reference validation, string provenance and preallocation quotas. Existing SYSC binding errors remain structured and separate from Registry errors. Input consists of 54 VM-owned fixed queries, never endpoint objects or host syscalls.
## Fn Execution Boundary
Typed Fn callbacks execute as ordinary guest calls on the single VM context. Boot remains physical FunctionId 0; preparation requires an empty capture environment and existing argument checks. FRAME_SYNC preserves context for next-PC resumption; successful last-root RET completes entry and leaves rooted results before threshold GC. No native callback registration, retention or reentry API is introduced; raw HeapRef/ValueSnapshot copies do not establish guest roots or authorize cross-session imports. Syscalls remain non-first-class.
@@ -179,3 +179,7 @@ This keeps the host ABI compatible with a deterministic frame machine.
- [`03-memory-stack-heap-and-allocation.md`](03-memory-stack-heap-and-allocation.md) defines VM heap ownership and handles.
- [`10-debug-inspection-and-profiling.md`](10-debug-inspection-and-profiling.md) defines visibility of cost and diagnostics.
- domain chapters (e.g. `04`, `05`, `15`) define per-operation status tables.
## Fn Execution Boundary
Typed Fn callbacks execute as ordinary guest calls on the single VM context. Boot remains physical FunctionId 0; preparation requires an empty capture environment and existing argument checks. FRAME_SYNC preserves context for next-PC resumption; successful last-root RET completes entry and leaves rooted results before threshold GC. No native callback registration, retention or reentry API is introduced; raw HeapRef/ValueSnapshot copies do not establish guest roots or authorize cross-session imports. Syscalls remain non-first-class.
+1 -2
View File
@@ -23,7 +23,6 @@ Does not belong in `docs/specs/runtime/` as the primary canonical source:
- bytecode-level ISA:
[`../virtual-machine/ISA_CORE.md`](../../vm-arch/ISA_CORE.md);
- pedagogical guides and learning material:
[`../learn/README.md`](../runtime/learn/README.md) and
[published lessons](../../../discussion/lessons/).
## Organization Rules
@@ -87,7 +86,7 @@ In the current state, no chapter under the active `docs/specs/runtime/` root is
| [`07-touch-peripheral.md`](07-touch-peripheral.md) | virtual hardware: touch | normative |
| [`08-save-memory-and-memcard.md`](08-save-memory-and-memcard.md) | virtual hardware: save memory | normative |
| [`09-events-and-concurrency.md`](09-events-and-concurrency.md) | machine events and frame scheduling | normative |
| [`09a-coroutines-and-cooperative-scheduling.md`](09a-coroutines-and-cooperative-scheduling.md) | VM coroutine model | normative |
| [`09a-coroutines-and-cooperative-scheduling.md`](09a-coroutines-and-cooperative-scheduling.md) | Single execution context and frame continuation | normative |
| [`10-debug-inspection-and-profiling.md`](10-debug-inspection-and-profiling.md) | machine diagnostics | normative |
| [`11-portability-and-cross-platform-execution.md`](11-portability-and-cross-platform-execution.md) | portability contract | normative |
| [`11a-headless-automation-protocol.md`](11a-headless-automation-protocol.md) | external headless host automation | normative |
+54 -45
View File
@@ -2,7 +2,7 @@ Prometeu VM Runtime — Canonical Architecture
Status: canonical
This document is the authoritative architectural reference for the Prometeu VM runtime. It reflects the implementation as it exists today and defines the invariants that govern architectural changes in the VM layer.
This document is the authoritative architectural reference for the Prometeu VM runtime. It defines the invariants that govern architectural changes in the VM layer.
Scope boundary:
@@ -14,7 +14,7 @@ Scope boundary:
Document roles:
- This file is normative for VM/runtime architecture.
- Detailed domain specifications may live under `docs/runtime/specs/`, but they must not contradict this document where VM/runtime invariants are concerned.
- Detailed domain specifications may live under `docs/specs/runtime/`, but they must not contradict this document where VM/runtime invariants are concerned.
- Future architectural changes become authoritative when this document is updated.
- The machine-wide fantasy console framing lives in the runtime specs manual and related domain specs; those documents are complementary, not competing VM architecture sources.
@@ -30,10 +30,10 @@ Maintenance rule:
- Operand stack + call frames; bytecode is fetched from a ROM/program image with a separate constant pool.
- GC‑managed heap
- Non‑compacting mark–sweep collector; stable object handles (`HeapRef`) while live. Sweep invalidates unreachable handles; objects are never moved.
- Closures (Model B)
- First‑class closures with a heap‑allocated environment. The closure object is passed to the callee as a hidden `arg0` when invoking a closure.
- Cooperative coroutines
- Deterministic, cooperative scheduling. Switching and GC occur only at explicit safepoints (`FRAME_SYNC`).
- Typed first-class Fn
- Structural logical parameter/result signatures and heap Closure environments retained by CallFrames, without hidden arg0.
- Single execution context
- VM directly owns PC, stacks and globals; no heap Coroutine or guest scheduler. GC opportunities are FRAME_SYNC and successful last-root RET after result rooting.
- Unified syscall ABI
- PBX pre-load artifacts declare canonical host bindings in `SYSC` and encode call sites as `HOSTCALL <sysc_index>`. The loader resolves and patches them to numeric `SYSCALL <id>` before verification/execution. Capability gating is enforced at load and checked again defensively at runtime. Syscalls are not first‑class values.
@@ -57,20 +57,19 @@ Maintenance rule:
- Variable-length arrays use the Registry element layout and defaults. Primitive/builtin values are stored directly; Struct/Array elements contain generational references. Native String/Dynamic slots retain their ownership rules. Stack/local execution continues to use `Value`.
- Closures
- Carry a function identifier and a captured environment (a slice/vector of `Value`s stored with the closure). Captured `HeapRef`s are traversed by the GC.
- Coroutines
- Heap‑resident coroutine records (state + wake time + suspended operand stack and call frames). These act as GC roots when suspended.
- Structs and Dynamic boxes
- Typed payloads use resolved reference/ownership maps. Private Struct cells can share mutable captured bindings.
Notes:
- Literals like strings and numbers are sourced from the constant pool in the program image; heap allocation is only used for runtime objects (closures, arrays, coroutine records, and any future heap kinds). The constant pool never embeds raw `HeapRef`s.
- Literals like strings and numbers are sourced from the constant pool in the program image; heap allocation is only used for runtime objects (closures, arrays, Structs and Dynamic boxes). The constant pool never embeds raw `HeapRef`s.
2.3 GC Roots
- VM roots
- Current operand stack and call frames of the running coroutine (or main context).
- Suspended coroutines
- All heap‑resident, suspended coroutine objects are treated as roots. Their saved stacks/frames are scanned during marking.
- Root traversal
- The VM exposes a root‑visitor that walks the operand stack, frames, and coroutine records to feed the collector. The collector then follows children from each object kind (e.g., array elements, closure environments, coroutine stacks).
- Roots comprise globals, all live operand values, Closure owners in every active
CallFrame and legally retained native/host roots. Inspection snapshots are not
guest roots. Tracing visits complete typed fields, arrays, captures and cells.
- Root results are transferred/rooted before the last frame is removed or GC runs,
and remain owned until consumed/replaced/reset/unloaded. Unreachable cycles collect.
3. Execution Model
@@ -85,20 +84,22 @@ Notes:
3.2 Safepoints
- `FRAME_SYNC` is the only safepoint.
- At `FRAME_SYNC`, the VM performs two actions in a well‑defined order:
1) Garbage‑collection opportunity: root enumeration + mark–sweep.
2) Scheduler handoff: the currently running coroutine may yield/sleep, and a next ready coroutine is selected deterministically.
- No other opcode constitutes a GC or scheduling safepoint. Syscalls do not implicitly trigger GC or rescheduling.
- Threshold GC opportunities are FRAME_SYNC and successful RET of the last root,
after result rooting. Ordinary callee RET, entry preparation, syscalls and
allocation/quota refusal do not collect. GC adds no guest callback, clock/frame
advance, budget grant or partial sweep on scratch failure.
3.3 Scheduler Behavior (Cooperative Coroutines)
3.3 Single Context and Host Continuation
- Coroutines are cooperative and scheduled deterministically (FIFO among ready coroutines).
- `YIELD` and `SLEEP` take effect at `FRAME_SYNC`:
- `YIELD` places the current coroutine at the end of the ready queue.
- `SLEEP` parks the current coroutine until its exact `wake_tick`, after which it re‑enters the ready queue at the correct point.
- `SPAWN` creates a new coroutine with its own stack/frames recorded in the heap and enqueues it deterministically.
- No preemption: the VM never interrupts a coroutine between safepoints.
- FRAME_SYNC may occur in any body, has no stack effect and resumes next PC with
live frames/locals/environments. It closes the logical frame but does not restart
entry. Budget exhaustion/breakpoints preserve the same open logical frame.
- Last-root RET completes entry. Recurring host prepares FunctionId 0 next frame,
preserving globals/init guard; preparation validates/reserves before replacing
previous owners and allocates no Coroutine. HALT/trap/reset/unload retain their
contracts. Render/asset workers remain independent of guest execution.
- SPAWN/YIELD/SLEEP are retired: numbers 0x54–0x56 stay reserved and all uses reject
at load, including unreachable code. No compatibility scheduler remains.
4. Verification Model
@@ -119,25 +120,33 @@ The verifier statically checks bytecode for structural safety and stack‑shape
- Syscalls
- The verifier runs only on the patched executable image. `HOSTCALL` is invalid at verification time. Final `SYSCALL` IDs must exist per `SyscallMeta`, and arity/declared return slot counts must match metadata.
- Closures
- `CALL_CLOSURE` is only allowed on closure values; the callee function must be known; argument counts for closure calls must match.
- Coroutines
- `YIELD` context must be valid; `SPAWN` argument counts are validated.
- Expected FnTypeId determines complete parameter/result groups even when the concrete FunctionId is unknown. Known mismatch rejects; Unknown retains runtime checks. Capture indices and target metadata are checked, and direct entry into capturing bodies rejects.
- Trait calls
- Exact method signatures and complete views resolve through immutable tables; concrete receiver is the first callee parameter, with no capture environment.
4.2 Runtime vs Verifier Guarantees
- The Registry verifier checks structure and stack shape and conservatively tracks known types through control flow. It rejects proved incompatibilities; Unknown values retain runtime checks at typed boundaries. Numeric domain checks, polymorphic comparisons and concrete syscall argument validation may still trap at runtime. The legacy production loader remains pending the callable migration described below.
- The Registry verifier checks structure and stack shape and conservatively tracks known types through control flow. It rejects proved incompatibilities; Unknown values retain runtime checks at typed boundaries. Numeric domain checks, polymorphic comparisons and concrete syscall argument validation may still trap at runtime.
- Capability gating for syscalls is enforced at load from cartridge capability flags and checked again at runtime by the VM/native interface.
5. Closures (Model B) — Calling Convention
-------------------------------------------
5. Typed Fn and Environments
----------------------------
- Creation
- `MAKE_CLOSURE` captures N values from the operand stack into a heap‑allocated environment alongside a function identifier. The opcode _pushes a `HeapRef` to the new closure.
- Call
- `CALL_CLOSURE` invokes a closure. The closure object itself is supplied to the callee as a hidden `arg0`. User‑visible arguments follow the function’s declared arity.
- Access to captures
- The callee can access captured values via the closure’s environment. Captured `HeapRef`s are traced by the GC.
- Fn identity is ordered logical parameter/result TypeIds; names, target and captures
are metadata. Pure Array/Fn structural cycles reject; nominal anchors stop expansion.
- MAKE_CLOSURE takes FunctionId/FnTypeId, captures full declared groups and pushes a
distinct one-slot instance. Immutable bindings copy values; mutable bindings can
share private typed Struct cells. Metadata lives in required PBX section 8.
- CALL_CLOSURE takes expected FnTypeId and retains the Closure in CallFrame, without
public arg0. GET_CAPTURE takes an index and copies a complete group. Direct calls
to capturing bodies reject; bound receivers use explicit adapter bodies.
- Fn is valid in Struct/Array/Dynamic, defaults Null and compares instance identity.
It gains no REF_* casts, Trait implementations, fault isolation or separate budget.
- Validate/reserve before consume/publication; faults preserve input owners and expose
no partial frame/object. Costs are 8+C / 6 / 2+W including traps, charged once.
- CALL_TRAIT takes TraitTypeId/method index, consumes explicit args and a complete
view, then passes concrete receiver first. Exact immutable-table dispatch costs 6.
6. Unified Syscall ABI
@@ -160,11 +169,11 @@ The verifier statically checks bytecode for structural safety and stack‑shape
- Collector
- Non‑moving mark–sweep.
- Triggers
- GC runs only at `FRAME_SYNC` safepoints.
- Threshold GC runs at FRAME_SYNC and successful last-root RET after result rooting.
- Liveness
- Roots comprise: the live VM stack/frames and all suspended coroutines. The collector traverses object‑specific children (array elements, closure environments, coroutine stacks).
- Globals, live operand values and active-frame Closures root complete typed object graphs, including cells and legally retained host/native owners.
- Determinism
- GC opportunities and scheduling order are tied to `FRAME_SYNC`, ensuring repeatable execution traces across runs with the same inputs.
- Opportunities depend on execution boundaries and thresholds, preserving deterministic guest execution with the same inputs.
8. Non‑Goals
@@ -180,12 +189,12 @@ The verifier statically checks bytecode for structural safety and stack‑shape
--------------------------
- Keep the public surface minimal and metadata‑driven (e.g., syscalls via `SyscallMeta`).
- Do not assume implicit safepoints; schedule and GC only at `FRAME_SYNC`.
- Preserve explicit GC opportunities and root results before root-return collection.
- When adding new opcodes or object kinds, extend the verifier and GC traversal accordingly (children enumeration, environment scanning, root sets).
- Update this document alongside any architectural change that affects runtime invariants.
## Program Registry v1
The [Program Registry contract](../specs/runtime/02c-program-registry-and-pbx-v1.md) defines immutable image-owned Type/Function metadata linked by dense IDs. Descriptors are native metadata outside guest GC; nominal identity does not depend on names. Stack/local execution retains Value, while typed storage uses resolved aligned layouts. PBX v1 is the sole target format; publication requires full bounded validation. Callable/closure/coroutine typed integration awaits its separate contract and must preserve existing behavior until then.
The [Program Registry contract](../specs/runtime/02c-program-registry-and-pbx-v1.md) defines immutable image-owned Type/Function metadata linked by dense IDs. Descriptors are native metadata outside guest GC; nominal identity does not depend on names. Stack/local execution retains Value, while typed storage uses resolved aligned layouts. PBX v1 is the sole target format; publication requires full bounded validation. Fn tag 4 and mandatory captures section 8 extend the Registry; no old-schema fallback is permitted.
`ValidatedProgramImage::load` publishes a shared image only after bounded decoding, native binding and Registry verification; `VirtualMachine::from_image` creates sessions that consume its typed signatures, constants and conversion instructions. Production `initialize` and the existing example generators remain pending coordinated migration that preserves typed callable behavior. [Registry Boundaries and Owned Values](../../discussion/lessons/DSC-0058-program-registry-type-and-function-metadata/LSN-0059-registry-boundaries-and-owned-values.md) explains the published mechanisms. The [producer handoff](registry-producer-handoff.md) documents schema, input IDs and named-argument order, while [layout evidence](registry-layout-evidence.md) records reproducible load/access/GC measurements and the current publication boundary.
`ValidatedProgramImage::load` publishes a shared image only after bounded decoding, native binding and Registry verification; `VirtualMachine::from_image` creates sessions that consume its typed signatures, constants and conversion instructions. Production and internal generators must use this sole sealed-v1 path. Typed Fn integration and legacy removal are implemented together; publication alone is not proof that every consumer has migrated. [Registry Boundaries and Owned Values](../../discussion/lessons/DSC-0058-program-registry-type-and-function-metadata/LSN-0059-registry-boundaries-and-owned-values.md) explains the published mechanisms. The [producer handoff](registry-producer-handoff.md) documents schema, input IDs and named-argument order, while [layout evidence](registry-layout-evidence.md) records reproducible load/access/GC measurements and the current publication boundary.
+11 -11
View File
@@ -64,13 +64,13 @@ Authority rule:
- Functions and scopes:
- `CALL u32` — call by function index; argument/result arity per function metadata.
- `RET` — return from current function (block terminator).
- `MAKE_CLOSURE u32,u32` — create closure from `(fn_id, capture_count)`.
- `CALL_CLOSURE u32` — invoke closure with `arg_count` user arguments.
- `MAKE_CLOSURE u32,u32` — create typed closure from `(FunctionId, FnTypeId)`; cost 8+C.
- `CALL_CLOSURE u32` — invoke against expected FnTypeId; cost 6.
- `GET_CAPTURE u32` (0x57) — copy indexed complete capture group from current frame; cost 2+W.
- `CALL_TRAIT u32,u32` (0x58) — invoke TraitTypeId/method index through complete view; cost 6.
- Concurrency:
- `SPAWN u32,u32` — create coroutine for `(fn_id, arg_count)`.
- `YIELD` — request cooperative yield at the next safepoint.
- `SLEEP u32` — request suspension for a logical tick duration.
- Retired execution operations:
- 0x54–0x56 (SPAWN/YIELD/SLEEP) remain reserved and reject at load, including unreachable code. Diagnostic decoding may identify them; no execution or assembler emission is permitted.
- System/Timing:
- `HOSTCALL u32` — PBX pre-load host binding call by `SYSC` table index; the loader must resolve and rewrite it before verification or execution.
@@ -110,7 +110,7 @@ For exact immediates and stack effects, see `CoreOpCode::spec()` which is the si
- The canonical decoder is `prometeu_bytecode::decode_next(pc, bytes)`.
- It uses the Core ISA spec to determine immediate size and the canonical `next_pc`.
- Unknown or legacy opcodes must produce a deterministic `UnknownOpcode` error.
- Unknown opcodes produce deterministic UnknownOpcode errors; recognized retired opcodes produce structured load rejection before execution.
#### Module Boundary
@@ -122,20 +122,20 @@ For exact immediates and stack effects, see `CoreOpCode::spec()` which is the si
#### Scope Notes
- "Core ISA" in the current repository means the canonical opcode surface implemented by the runtime today.
- It includes closures, coroutines, `HOSTCALL` patching semantics, `INTRINSIC`, and `FRAME_SYNC`.
- It includes typed closures, trait calls, `HOSTCALL` patching semantics, `INTRINSIC`, and `FRAME_SYNC`.
- It does not, by itself, define higher-level runtime policy such as crash taxonomy, firmware behavior, cartridge lifecycle, or host service organization. Those belong to the canonical runtime architecture and related specs.
#### FRAME_SYNC — Semantics and Placement (Bytecode Level)
- Semantics:
- `FRAME_SYNC` is a zero-operand instruction and does not modify the operand stack.
- It marks a VM safepoint for GC and the cooperative scheduler. In `CoreOpcodeSpec` this is exposed as `spec.is_safepoint == true`.
- On execution, the VM may suspend the current coroutine until the next frame boundary and/or perform GC. After resuming, execution continues at the next instruction.
- It marks a VM safepoint for threshold GC. In `CoreOpcodeSpec` this is exposed as `spec.is_safepoint == true`.
- Execution returns to the host at the logical frame boundary, preserving the single context. Resumption continues at the next instruction with live frames/locals/environments. Successful last-root RET is a separate GC opportunity after result rooting and completes that entry.
- Placement rules (representable and checkable):
- `FRAME_SYNC` may appear anywhere inside a function body where normal instructions can appear. It is NOT a block terminator (`spec.is_terminator == false`).
- Instruction boundaries are canonical: encoders/emitters must only place `FRAME_SYNC` at valid instruction PCs. The verifier already enforces “jump-to-boundary” and end-exclusive `[start, end)` function ranges using the canonical layout routine.
- Entrypoints that represent a render/update loop SHOULD ensure at least one reachable `FRAME_SYNC` along every long-running path to provide deterministic safepoints for GC/scheduling. This policy is semantic and may be enforced by higher-level tooling; at the bytecode level it is representable via `spec.is_safepoint` and can be counted by static analyzers.
- Entrypoints that represent a render/update loop SHOULD ensure at least one reachable `FRAME_SYNC` along every long-running path to provide deterministic safepoints for GC/frame handoff. This policy is semantic and may be enforced by higher-level tooling; at the bytecode level it is representable via `spec.is_safepoint` and can be counted by static analyzers.
- Disassembly:
- Disassemblers must print the mnemonic `FRAME_SYNC` verbatim for this opcode.
+8 -3
View File
@@ -1,6 +1,6 @@
# 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.
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, internal test producers and both example generators use the same sealed v1 path. External SDK/frontend adaptation remains a separate consumer obligation.
## Encoding and complete groups
@@ -58,10 +58,15 @@ Static bad IDs/categories/fields reject load with typed LOAD_INVALID_REFERENCE c
## 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.
Consumers must recognize all seven encodings, invoke Registry-derived effects in bounded structural/height/type verification and use validated-image execution. The metadata-free verifier and legacy decoder have been removed. 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.
Dummy Boy and Stress emit sealed PBX v1, including empty captures sections, and
run through the production host. Fn is a one-slot nullable HeapRef value in fields
and arrays; Dynamic can carry it with its exact Fn TypeId. Closure environments and
shared private cells participate in existing reference maps. Default construction
never invokes callbacks. Threshold GC runs at FRAME_SYNC and successful last-root
RET after rooting results. Quota refusal cannot invoke rescue GC.
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).
+49 -33
View File
@@ -3,30 +3,22 @@
This document describes the Registry v1 producer and consumer interfaces. The normative contract
is [Program Registry and PBX v1](../specs/runtime/02c-program-registry-and-pbx-v1.md).
The rationale and published mechanisms are explained in [Registry Boundaries and Owned Values](../../discussion/lessons/DSC-0058-program-registry-type-and-function-metadata/LSN-0059-registry-boundaries-and-owned-values.md).
The completed callable and production integration is explained in [Typed Callables and Frame-Owned Continuations](../../discussion/lessons/DSC-0052-vm-closures-captures-and-dynamic-calls/LSN-0061-typed-callables-and-frame-owned-continuations.md).
## Publication state
The bounded writer/owned decoder, sealed `ValidatedProgramImage::load`, shared
session factory, typed direct-call/return boundaries, Dynamic/reference execution,
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
categories may be used as a provisional closure type.
The production `initialize` path uses bounded `ValidatedProgramImage::load` and
`VirtualMachine::from_image`. The v0 decoder, slot-only verifier, scheduler and
unchecked executable constructors have been removed. Internal test producers,
Dummy Boy and Stress emit sealed v1 with typed Fn metadata and mandatory captures.
The runtime retains existing constant/string ownership, collections, Dynamic and
reference boundaries. The separate render frame scheduler remains active.
### Pending production integration
| Component | Pending implementation and validation |
| --- | --- |
| Loader and image | Switch production initialize to the sealed strict v1 factory; retire old decoder and unchecked entry points while preserving typed callable behavior. |
| Constant ownership | Complete image/constant provenance on migrated production entry points using the delivered ledgers and native retention domains. |
| Verification | Route production loads through bounded Registry verification; remove the old verifier while adding typed callable checks. |
| Diagnostics | Audit structured load/runtime/native diagnostics through the final active loader and hosts. |
| Producers and examples | Migrate producers/fixtures, regenerate dummy-boy and stress-console PBX files, and execute both through the active runtime. These generators are ordinary programs sharing the production consumer being migrated. |
| 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 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.
Fn values, frame-owned capture environments, typed indirect calls and receiver-first
trait dispatch use [the function-value contract](../specs/runtime/02b-vm-function-values-and-closures.md).
FRAME_SYNC resumes next PC; successful root RET permits recurring entry preparation.
New strings/bytes/save APIs, long-run stress and representative-game headroom require
separate technical contracts and workloads.
The external Studio handoff targets are the build-pipeline
`backend/bytecode/BytecodeModule.java` and `backend/irvm/IRVMIntrinsicRegistry.java`,
@@ -40,7 +32,7 @@ repository publishes requirements and oracles; those modules have not been edite
Emit PBX version 1 only. The header is 32 bytes: magic at 0, u16 version at 4,
little-endian flag 0 at 6, reserved zero at 7, section count at 8 and twenty zero
bytes at 12. Directory entries are file-relative u32 kind/offset/length triples.
Mandatory kinds are 0, 1, 2, 4, 5, 6 and 7; debug kind 3 is optional. Keep empty
Mandatory kinds are 0, 1, 2, 4, 5, 6, 7 and 8; debug kind 3 is optional. Keep empty
mandatory tables with count zero. Never skip unknown sections or retain a legacy
fallback. Use the canonical chapter's field order and UTF-8 rules, not Rust layouts.
@@ -66,18 +58,19 @@ unknown declarations, invalid indices and unused declarations are rejected.
## Independent binary oracles
The manually specified minimal executable in
`crates/console/prometeu-bytecode/tests/registry_v1.rs::minimal_bytes` is 173 bytes.
Its directory begins at 32; seven entries end at 116:
`crates/console/prometeu-bytecode/tests/registry_v1.rs::minimal_bytes` is 193 bytes.
Its directory begins at 32; eight entries end at 128:
| Kind | Offset | Length | Payload |
| --- | ---: | ---: | --- |
| constants | 116 | 4 | count 0 |
| functions | 120 | 29 | one unnamed zero-parameter/result function, offset 0, length 2, locals/max 0 |
| code | 149 | 2 | `01 00` (HALT) |
| exports | 151 | 4 | count 0 |
| syscalls | 155 | 4 | count 0 |
| types | 159 | 10 | one unnamed Bool import, BuiltinId `0x0013` |
| implementations | 169 | 4 | count 0 |
| constants | 128 | 4 | count 0 |
| functions | 132 | 29 | one unnamed zero-parameter/result function, offset 0, length 2, locals/max 0 |
| code | 161 | 2 | `01 00` (HALT) |
| exports | 163 | 4 | count 0 |
| syscalls | 167 | 4 | count 0 |
| types | 171 | 10 | one unnamed Bool import, BuiltinId `0x0013` |
| implementations | 181 | 4 | count 0 |
| captures | 185 | 8 | function count 1; empty environment |
The independent multi-slot fixture in the same suite declares `fn(vec2)->vec2`
with TypeId 0, no serialized widths, no extra locals and max 2. Its fourteen code
@@ -128,11 +121,11 @@ human wording or manufacture runtime PCs for rejected loads.
| Consumer | Accepted handoff | Status / remaining ownership |
| --- | --- | --- |
| Studio/PBS | PBX schema, signatures/names, effect-order and binary oracles, nine imports, all input IDs and diagnostics | External implementation and source-language tests pending; no external edits claimed |
| Collections | Typed aligned layouts/defaults, exact storage groups, reference/native maps and checked adapters | Internal containers are tested; guest collection operations/costs/GC integration require a complete operation contract |
| Callables | Function/implementation tables and direct-call contracts; exact trait views | Callable/capture/dispatch/coroutine semantics and coordinated producer migration remain pending |
| Collections | Typed aligned layouts/defaults, exact storage groups, reference/native maps and checked adapters | Typed collection operations, costs, complete-group storage and GC execute through the active sealed loader |
| Callables | Function/implementation tables and direct-call contracts; exact trait views | Fn, typed captures, CALL_CLOSURE/GET_CAPTURE/CALL_TRAIT and single-context production migration are implemented |
| Strings/bytes/save | Arc strings, image/session Weak ledgers, bounded native writers and explicit import/export provenance | Existing string paths are integrated; new operations and their operation-specific evidence remain pending |
| Resource stability | Product ceilings, generational handles, fallible capacity reservations and structured faults | Focused ownership/quota rollback is core evidence; coordinated long-run/cross-host stress requires separate workloads |
| Reference game | Runtime contract, example migration requirement and technical measurements | Game workload/headroom/readiness requires representative-game evidence, not unit test counts |
| Reference game | Runtime contract, migrated example images and focused technical measurements | Game workload/headroom/readiness requires representative-game evidence, not unit test counts |
Image constant allocations are shared between sessions without a session-content
charge. New/imported runtime allocations belong to their session; equal text does
@@ -141,3 +134,26 @@ Arc. `ValueSnapshot` keeps domain owners alive while tooling retains values and
serializes only the ordinary value list. Cross-session import copies external
content into the destination domain. Stored String slots remain `Option<Arc<str>>`;
native ownership is not a guest GC reference or an input hardware carrier.
## Callable producer obligations
Emit Fn tag 4 with ordered logical parameter AND result TypeIds; parameter names do
not change identity. Emit one descriptor per signature. Array/Fn structural cycles
must terminate at nominal Struct/Trait anchors. Function bodies carry no hidden arg0.
Captures section 8 contains a u32 function count and, for every FunctionId in order,
a u32 capture count followed by ordered TypeIds; emit explicit empty lists too.
Mutable bindings lower to shared private typed Struct cells; immutable captures
copy their complete values. CALL/host preparation cannot enter capturing bodies.
MAKE_CLOSURE 0x52 carries FunctionId/FnTypeId (10 bytes), CALL_CLOSURE 0x53 carries
expected FnTypeId (6), GET_CAPTURE 0x57 carries environment-group index (6), and
CALL_TRAIT 0x58 carries TraitTypeId/method index (10). Costs are 8+C, 6, 2+W and 6.
Trait views follow explicit arguments; the target receives its concrete receiver
first. Typed Fn can be stored in Struct/Array/Dynamic but cannot implement Trait.
SPAWN/YIELD/SLEEP 0x54–0x56 reject anywhere in code. Old captures=/argc= assembler
forms reject. Neither callbacks nor captures introduce a scheduling phase.
External compiler acceptance requires these exact bytes and signatures, Fn
pass/return/storage, shared cells, named-argument evaluation order, nested sync
continuation and structured failure tests. The runtime's binary/behavioral oracles
are available; no external implementation is claimed.
Binary file not shown.
Binary file not shown.