10 Commits
54 changed files with 2061 additions and 197 deletions
@@ -56,4 +56,6 @@ pub struct TrapInfo {
pub pc: u32,
/// Optional source span information if debug symbols are available.
pub span: Option<SourceSpan>,
/// Machine-readable quota context; messages are not its serialization.
pub resource: Option<crate::ResourceFailure>,
}
@@ -8,6 +8,7 @@ pub mod model;
mod opcode;
mod opcode_spec;
mod program_image;
mod resource_failure;
mod value;
pub use abi::{
@@ -22,6 +23,7 @@ pub use disassembler::disassemble;
pub use layout::{compute_function_layouts, FunctionLayout};
pub use model::{BytecodeLoader, FunctionMeta, LoadError, SyscallDecl, PBX_MAGIC};
pub use program_image::ProgramImage;
pub use resource_failure::{ResourceFailure, ResourceReason, RuntimeResource};
pub use value::{string_materialization_count, HeapRef, Value};
pub mod load_limits;
@@ -1,17 +1,25 @@
//! Shared PBX v1 resource limits and structured validation failures.
//! Counters are deterministic; a failed reservation never changes usage.
use serde::{Deserialize, Serialize};
use std::fmt;
const MIB: u64 = 1_048_576;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum LoadCode {
#[serde(rename = "LOAD_INVALID_FORMAT")]
InvalidFormat,
#[serde(rename = "LOAD_UNSUPPORTED_FORMAT")]
UnsupportedFormat,
#[serde(rename = "LOAD_INVALID_REFERENCE")]
InvalidReference,
#[serde(rename = "LOAD_INVALID_REGISTRY")]
InvalidRegistry,
#[serde(rename = "LOAD_INVALID_CODE")]
InvalidCode,
#[serde(rename = "LOAD_RESOURCE_LIMIT")]
ResourceLimit,
#[serde(rename = "LOAD_INVALID_ENTRYPOINT")]
InvalidEntrypoint,
}
impl LoadCode {
@@ -27,7 +35,7 @@ impl LoadCode {
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum LoadReason {
Magic,
Version,
@@ -80,7 +88,7 @@ pub enum LoadReason {
InvalidYield,
TypeMismatch,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[repr(usize)]
pub enum LoadResource {
PbxBytes,
@@ -98,14 +106,14 @@ pub enum LoadResource {
}
const RESOURCE_COUNT: usize = 12;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum IdDomain {
Type,
Function,
Implementation,
}
#[derive(Debug, Clone, PartialEq, Eq)]
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct LoadFailure {
pub code: LoadCode,
pub reason: LoadReason,
@@ -262,10 +270,11 @@ impl LoadLimits {
pub struct LoadBudget {
limits: LoadLimits,
used: [u64; RESOURCE_COUNT],
peak: [u64; RESOURCE_COUNT],
}
impl LoadBudget {
pub fn new(limits: LoadLimits) -> Self {
Self { limits, used: [0; RESOURCE_COUNT] }
Self { limits, used: [0; RESOURCE_COUNT], peak: [0; RESOURCE_COUNT] }
}
pub fn limit(&self, r: LoadResource) -> u64 {
self.limits.ceiling(r).min(LoadLimits::default().ceiling(r))
@@ -285,6 +294,12 @@ impl LoadBudget {
pub fn used(&self, r: LoadResource) -> u64 {
self.used[r as usize]
}
/// Highest admitted reservation total during this budget's lifetime.
/// Refunds and failed load transactions retain this measurement; refused
/// charges do not increase it. This is accounted capacity, not process RSS.
pub fn peak_usage(&self, r: LoadResource) -> u64 {
self.peak[r as usize]
}
pub fn charge(&mut self, r: LoadResource, amount: u64) -> Result<(), LoadFailure> {
let next = self
.used(r)
@@ -292,6 +307,7 @@ impl LoadBudget {
.ok_or_else(|| LoadFailure::new(LoadCode::ResourceLimit, LoadReason::Overflow))?;
self.check(r, next)?;
self.used[r as usize] = next;
self.peak[r as usize] = self.peak[r as usize].max(next);
Ok(())
}
pub fn check(&self, r: LoadResource, amount: u64) -> Result<(), LoadFailure> {
@@ -348,3 +364,29 @@ impl LoadBudget {
result
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn peak_tracks_admitted_capacity_through_refunds_and_failed_transactions() {
let mut budget = LoadBudget::new(LoadLimits { temporary_bytes: 10, ..Default::default() });
budget.charge(LoadResource::TemporaryBytes, 3).unwrap();
let result: Result<(), LoadFailure> = budget.transaction(|budget| {
budget.charge(LoadResource::TemporaryBytes, 7)?;
budget.work(2)?;
budget.charge(LoadResource::TemporaryBytes, 1)
});
assert!(result.is_err());
assert_eq!(budget.used(LoadResource::TemporaryBytes), 3);
assert_eq!(budget.peak_usage(LoadResource::TemporaryBytes), 10);
assert_eq!(budget.used(LoadResource::Work), 2);
assert_eq!(budget.peak_usage(LoadResource::Work), 2);
budget.refund(LoadResource::TemporaryBytes, 3);
assert_eq!(budget.used(LoadResource::TemporaryBytes), 0);
assert_eq!(budget.peak_usage(LoadResource::TemporaryBytes), 10);
assert!(budget.charge(LoadResource::TemporaryBytes, u64::MAX).is_err());
assert_eq!(budget.peak_usage(LoadResource::TemporaryBytes), 10);
}
}
@@ -50,7 +50,7 @@ impl ProgramImage {
}
}
TrapInfo { code, opcode, message, pc, span }
TrapInfo { code, opcode, message, pc, span, resource: None }
}
pub fn find_function_index(&self, pc: u32) -> Option<usize> {
@@ -0,0 +1,40 @@
//! Resource fault context shared by the VM, native boundary and host tooling.
//! Accounting and product ceilings remain owned by the runtime budget.
use serde::{Deserialize, Serialize};
use std::fmt;
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[repr(usize)]
pub enum RuntimeResource {
GuestBytes,
HandleSlots,
AuxiliaryBytes,
TemporaryBytes,
StringBytes,
StringAllocations,
IndividualStringBytes,
CallDepth,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum ResourceReason {
Limit,
SizeOverflow,
AllocationFailed,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub struct ResourceFailure {
pub resource: RuntimeResource,
pub reason: ResourceReason,
pub requested: u64,
pub limit: u64,
}
impl fmt::Display for ResourceFailure {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(
f,
"{:?}: {:?}, requested {}, limit {}",
self.resource, self.reason, self.requested, self.limit
)
}
}
impl std::error::Error for ResourceFailure {}
@@ -164,8 +164,7 @@ fn owned_payload_refusal_rolls_back_all_ownership_and_preserves_prior_budget() {
assert_eq!(b.used(LoadResource::RegistryBytes), 3);
assert_eq!(b.used(LoadResource::Types), 0);
assert_eq!(b.used(LoadResource::ConstantEntries), 0);
let mut limits = LoadLimits::default();
limits.temporary_bytes = 1;
let limits = LoadLimits { temporary_bytes: 1, ..Default::default() };
let mut b = LoadBudget::new(limits);
assert_eq!(
OwnedPbx::parse(&bytes, &mut b).unwrap_err().resource,
@@ -560,9 +560,7 @@ mod tests {
let mut bank =
GlyphBank::with_palette_count(tile_size, size, size, palette_id as usize + 1);
bank.palette_mut(palette_id).unwrap()[1] = color;
for pixel in &mut bank.pixel_indices {
*pixel = 1;
}
bank.pixel_indices.fill(1);
bank
}
@@ -266,9 +266,7 @@ mod tests {
fn make_glyph_bank() -> GlyphBank {
let mut bank = GlyphBank::new(TileSize::Size8, 8, 8);
bank.palette_mut(0).unwrap()[1] = Color::RED;
for pixel in &mut bank.pixel_indices {
*pixel = 1;
}
bank.pixel_indices.fill(1);
bank
}
@@ -55,6 +55,7 @@ mod tests {
message: "type mismatch".into(),
pc: 0x44,
span: None,
resource: None,
},
},
};
@@ -79,6 +79,9 @@ pub enum DebugEvent {
pc: Option<u32>,
trap_code: Option<u32>,
opcode: Option<u16>,
span: Option<prometeu_bytecode::SourceSpan>,
resource: Option<prometeu_bytecode::ResourceFailure>,
init: Option<serde_json::Value>,
},
#[serde(rename = "cert")]
Cert { rule: String, used: u64, limit: u64, frame_index: u64 },
@@ -138,6 +141,9 @@ mod tests {
pc: Some(12),
trap_code: Some(4),
opcode: Some(0x70),
span: None,
resource: None,
init: None,
};
let json = serde_json::to_string(&event).unwrap();
+21 -7
View File
@@ -5,6 +5,7 @@ use std::sync::Arc;
/// Native producers describe their output before materializing guest content.
/// The VM provides the session allocator; HAL does not own guest quotas.
pub trait GuestStringAllocator {
fn byte_limit(&self) -> u64;
fn build(
&mut self,
length: usize,
@@ -23,6 +24,16 @@ pub struct HostReturn<'a> {
}
impl<'a> HostReturn<'a> {
fn size_overflow(&mut self) -> VmFault {
let error = VmFault::ResourceLimit(prometeu_bytecode::ResourceFailure {
resource: prometeu_bytecode::RuntimeResource::StringBytes,
reason: prometeu_bytecode::ResourceReason::SizeOverflow,
requested: u64::MAX,
limit: self.strings.byte_limit(),
});
self.failure = Some(error.clone());
error
}
pub fn new(
stack: &'a mut Vec<Value>,
result_slots: usize,
@@ -97,14 +108,14 @@ impl<'a> HostReturn<'a> {
length = length.checked_add(part.len()).ok_or(std::fmt::Error)?;
Ok(())
})
.map_err(|_| size_overflow())?;
.map_err(|_| self.size_overflow())?;
self.push_string_with_len(length, &mut |writer| {
lossy_chunks(bytes, &mut |part| writer.write_str(part))
})
}
pub fn push_hex(&mut self, bytes: &[u8]) -> Result<(), VmFault> {
const HEX: &[u8; 16] = b"0123456789abcdef";
let length = bytes.len().checked_mul(2).ok_or_else(size_overflow)?;
let length = bytes.len().checked_mul(2).ok_or_else(|| self.size_overflow())?;
self.push_string_with_len(length, &mut |writer| {
for &byte in bytes {
let pair = [HEX[(byte >> 4) as usize], HEX[(byte & 15) as usize]];
@@ -121,9 +132,9 @@ impl<'a> HostReturn<'a> {
let mut length = 0usize;
for (index, part) in parts.clone().enumerate() {
if index > 0 {
length = length.checked_add(separator.len()).ok_or_else(size_overflow)?;
length = length.checked_add(separator.len()).ok_or_else(|| self.size_overflow())?;
}
length = length.checked_add(part.len()).ok_or_else(size_overflow)?;
length = length.checked_add(part.len()).ok_or_else(|| self.size_overflow())?;
}
self.push_string_with_len(length, &mut |writer| {
for (index, part) in parts.clone().enumerate() {
@@ -137,9 +148,6 @@ impl<'a> HostReturn<'a> {
}
}
fn size_overflow() -> VmFault {
VmFault::Trap(prometeu_bytecode::TRAP_RESOURCE_LIMIT, "Native string length overflow".into())
}
fn lossy_chunks(
mut bytes: &[u8],
emit: &mut dyn FnMut(&str) -> std::fmt::Result,
@@ -169,6 +177,9 @@ mod tests {
use super::*;
struct RejectStrings;
impl GuestStringAllocator for RejectStrings {
fn byte_limit(&self) -> u64 {
0
}
fn build(
&mut self,
_length: usize,
@@ -198,6 +209,9 @@ mod tests {
struct Collect;
impl GuestStringAllocator for Collect {
fn byte_limit(&self) -> u64 {
u64::MAX
}
fn build(
&mut self,
length: usize,
@@ -39,7 +39,8 @@ pub enum LoadError {
}
/// Load-time error for PBX-declared syscall resolution.
#[derive(Debug, Clone, PartialEq, Eq)]
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(tag = "reason", rename_all = "snake_case")]
pub enum DeclaredLoadError {
UnknownSyscall {
module: String,
@@ -1,6 +1,7 @@
#[derive(Debug, PartialEq, Clone)]
pub enum VmFault {
Trap(u32, String),
ResourceLimit(prometeu_bytecode::ResourceFailure),
Panic(String),
Unavailable,
}
@@ -1,6 +1,7 @@
use prometeu_bytecode::TrapInfo;
use prometeu_vm::VmInitError;
use std::fmt;
mod init_diagnostic;
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum CrashReport {
@@ -10,6 +11,20 @@ pub enum CrashReport {
}
impl CrashReport {
/// The same machine fields serve headless and desktop transports.
pub fn init_diagnostic(&self) -> Option<serde_json::Value> {
match self {
Self::VmInit { error } => Some(init_diagnostic::serialize(error)),
_ => None,
}
}
pub fn resource_failure(&self) -> Option<prometeu_bytecode::ResourceFailure> {
match self {
Self::VmTrap { trap } => trap.resource,
Self::VmInit { error: VmInitError::RuntimeResourceLimit(resource) } => Some(*resource),
_ => None,
}
}
pub fn kind(&self) -> &'static str {
match self {
Self::VmTrap { .. } => "vm_trap",
@@ -0,0 +1,132 @@
use prometeu_vm::VmInitError;
use serde_json::{Value, json};
pub(super) fn serialize(error: &VmInitError) -> Value {
let code = match error {
VmInitError::RegistryLoadFailed(_) => "registry_load_failed",
VmInitError::RuntimeResourceLimit(_) => "runtime_resource_limit",
VmInitError::InvalidFormat => "invalid_format",
VmInitError::UnsupportedFormat => "unsupported_format",
VmInitError::ImageLoadFailed(_) => "image_load_failed",
VmInitError::LoaderPatchFailed(_) => "loader_patch_failed",
VmInitError::EntrypointNotFound => "entrypoint_not_found",
VmInitError::EntrypointArgumentsInvalid { .. } => "entrypoint_arguments_invalid",
VmInitError::VerificationFailed(_) => "verification_failed",
};
let mut result = json!({"code":code,"message":format!("{error:?}")});
match error {
VmInitError::RegistryLoadFailed(load) => {
result["load"] = json!(load);
result["load"]["code"] = json!(load.code.tag());
}
VmInitError::RuntimeResourceLimit(resource) => result["resource"] = json!(resource),
VmInitError::EntrypointArgumentsInvalid { function, slot, trap_code } => {
result["entry"] = json!({"function":function,"slot":slot,"trapCode":trap_code});
}
VmInitError::LoaderPatchFailed(patch) => {
use prometeu_vm::LoaderPatchError as P;
result["binding"] = match patch {
P::ResolveFailed(native) => json!(native),
P::HostcallIndexOutOfBounds { pc, sysc_index, syscalls_len } => {
json!({"reason":"hostcall_index_out_of_bounds","pc":pc,"syscallIndex":sysc_index,"syscallsLength":syscalls_len})
}
P::RawSyscallInPreloadArtifact { pc, syscall_id } => {
json!({"reason":"raw_syscall","pc":pc,"syscallId":syscall_id})
}
P::UnusedSyscallDecl { sysc_index, module, name, version } => {
json!({"reason":"unused_syscall","syscallIndex":sysc_index,"module":module,"name":name,"version":version})
}
P::HostcallRemaining { pc, sysc_index } => {
json!({"reason":"hostcall_remaining","pc":pc,"syscallIndex":sysc_index})
}
P::DecodeFailed(_) => json!({"reason":"decode_failed"}),
};
}
_ => {}
}
result
}
#[cfg(test)]
mod tests {
use super::*;
use crate::CrashReport;
use prometeu_bytecode::{
ResourceFailure, ResourceReason, RuntimeResource,
load_limits::{IdDomain, LoadCode, LoadFailure, LoadReason},
};
#[test]
fn load_tag_and_reference_context_survive_without_fabricating_runtime_pc() {
let error = LoadFailure::new(LoadCode::InvalidReference, LoadReason::TypeId)
.at(6, 159)
.record(4)
.member(2)
.reference(IdDomain::Type, 77)
.in_function(3, Some(18));
let report = CrashReport::VmInit { error: VmInitError::RegistryLoadFailed(error) };
assert_eq!(report.pc(), None);
let wire = report.init_diagnostic().unwrap();
assert_eq!(wire["code"], "registry_load_failed");
assert_eq!(wire["load"]["code"], "LOAD_INVALID_REFERENCE");
for (field, value) in [
("section", 6),
("offset", 159),
("record", 4),
("member", 2),
("referenced_id", 77),
("function", 3),
("pc", 18),
] {
assert_eq!(wire["load"][field], value);
}
assert_eq!(wire["load"]["id_domain"], "Type");
assert_eq!(wire["load"]["reason"], "TypeId");
}
#[test]
fn native_abi_and_resource_context_are_machine_fields() {
let native = prometeu_hal::syscalls::DeclaredLoadError::AbiMismatch {
module: "system".into(),
name: "has_cart".into(),
version: 1,
declared_arg_slots: 0,
declared_ret_slots: 2,
expected_arg_slots: 0,
expected_ret_slots: 1,
};
let wire = serialize(&VmInitError::LoaderPatchFailed(
prometeu_vm::LoaderPatchError::ResolveFailed(native),
));
assert_eq!(wire["binding"]["reason"], "abi_mismatch");
assert_eq!(wire["binding"]["module"], "system");
assert_eq!(wire["binding"]["declared_ret_slots"], 2);
assert_eq!(wire["binding"]["expected_ret_slots"], 1);
let resource = ResourceFailure {
resource: RuntimeResource::CallDepth,
reason: ResourceReason::Limit,
requested: 3,
limit: 2,
};
let report = CrashReport::VmInit { error: VmInitError::RuntimeResourceLimit(resource) };
assert_eq!(report.resource_failure(), Some(resource));
let wire = report.init_diagnostic().unwrap();
assert_eq!(wire["resource"]["resource"], "CallDepth");
assert_eq!(wire["resource"]["reason"], "Limit");
assert_eq!(wire["resource"]["requested"], 3);
assert_eq!(wire["resource"]["limit"], 2);
}
#[test]
fn all_load_codes_serialize_to_the_normative_tags() {
for code in [
LoadCode::InvalidFormat,
LoadCode::UnsupportedFormat,
LoadCode::InvalidReference,
LoadCode::InvalidRegistry,
LoadCode::InvalidCode,
LoadCode::ResourceLimit,
LoadCode::InvalidEntrypoint,
] {
assert_eq!(json!(code), code.tag());
assert_eq!(serde_json::from_value::<LoadCode>(json!(code)).unwrap(), code);
}
}
}
@@ -151,9 +151,7 @@ fn runtime_test_glyph_bank(tile_size: TileSize, palette_id: u8, color: Color) ->
let size = tile_size as usize;
let mut bank = GlyphBank::with_palette_count(tile_size, size, size, palette_id as usize + 1);
bank.palette_mut(palette_id).unwrap()[1] = color;
for pixel in &mut bank.pixel_indices {
*pixel = 1;
}
bank.pixel_indices.fill(1);
bank
}
@@ -76,12 +76,12 @@ impl VirtualMachineRuntime {
vm: &mut VirtualMachine,
platform: &mut dyn RuntimePlatform,
) -> Option<CrashReport> {
if vm.call_stack_is_empty() {
if let Err(error) = vm.prepare_boot_call() {
let report = CrashReport::VmInit { error };
self.last_crash_report = Some(report.clone());
return Some(report);
}
if vm.call_stack_is_empty()
&& let Err(error) = vm.prepare_boot_call()
{
let report = CrashReport::VmInit { error };
self.last_crash_report = Some(report.clone());
return Some(report);
}
let step_result = {
let mut ctx = HostContext::new_platform(Some(platform));
+14 -14
View File
@@ -1036,6 +1036,20 @@ fn color_transparent(
color_const(Color::TRANSPARENT)
}
/// Loader-side lookup charges each catalogue record before examining it.
pub(crate) fn metered_lookup_intrinsic(
id: u32,
budget: &mut prometeu_bytecode::load_limits::LoadBudget,
) -> Result<Option<&'static IntrinsicMeta>, prometeu_bytecode::load_limits::LoadFailure> {
for meta in INTRINSICS.iter().chain(crate::input_intrinsics::INPUT_INTRINSICS.iter()) {
budget.work(1)?;
if meta.id == id {
return Ok(Some(meta));
}
}
Ok(None)
}
#[cfg(test)]
mod tests {
use super::*;
@@ -1196,17 +1210,3 @@ mod tests {
assert_eq!(pixel.field("color").map(|field| field.start_slot), Some(2));
}
}
/// Loader-side lookup charges each catalogue record before examining it.
pub(crate) fn metered_lookup_intrinsic(
id: u32,
budget: &mut prometeu_bytecode::load_limits::LoadBudget,
) -> Result<Option<&'static IntrinsicMeta>, prometeu_bytecode::load_limits::LoadFailure> {
for meta in INTRINSICS.iter().chain(crate::input_intrinsics::INPUT_INTRINSICS.iter()) {
budget.work(1)?;
if meta.id == id {
return Ok(Some(meta));
}
}
Ok(None)
}
+6 -6
View File
@@ -380,12 +380,12 @@ impl Heap {
}
fn enqueue_mark(&mut self, r: HeapRef, stack: &mut BudgetVec<HeapRef>) {
if let Some(header) = self.header_mut(r) {
if !header.is_marked() {
// Each live object enters at most once; reserve(len()) bounds the entire traversal.
header.set_marked(true);
stack.push(r).expect("mark worklist reserved for every live object");
}
if let Some(header) = self.header_mut(r)
&& !header.is_marked()
{
// Each live object enters at most once; reserve(len()) bounds the entire traversal.
header.set_marked(true);
stack.push(r).expect("mark worklist reserved for every live object");
}
}
@@ -30,6 +30,7 @@ pub fn check_local_slot(
message: format!("Local slot {} out of bounds for function (limit {})", slot, limit),
pc,
span: None,
resource: None,
})
}
}
@@ -258,3 +258,31 @@ fn constant_strings_share_image_domain_across_sessions_and_native_snapshots() {
let Value::String(text) = &snapshot[0] else { panic!() };
assert_eq!(text.as_ref(), "shared");
}
#[test]
#[ignore = "explicit release measurement; not a timing assertion"]
fn sealed_image_load_probe() {
use std::time::Instant;
let constants: Vec<_> =
(0..512).map(|index| K::String(format!("{index:04}:{}", "x".repeat(59)))).collect();
let bytes = fixture(&[1, 0], 0, &constants, None, &[]);
let mut budget = budget();
let start = Instant::now();
let image = ValidatedProgramImage::load(&bytes, &mut budget, caps::NONE).unwrap();
let elapsed = start.elapsed().as_nanos();
assert_eq!(image.constant_content(), (32768, 512));
assert_eq!(budget.used(Q::TemporaryBytes), 0);
println!(
"image arch={} pbx={} registry={} payload={} work={} peak_scratch={} retained_scratch={} strings={} allocations={} load_ns={}",
std::env::consts::ARCH,
bytes.len(),
image.registry_bytes(),
image.payload_bytes(),
budget.used(Q::Work),
budget.peak_usage(Q::TemporaryBytes),
budget.used(Q::TemporaryBytes),
image.constant_content().0,
image.constant_content().1,
elapsed
);
}
@@ -193,8 +193,8 @@ fn stack_analysis_refunds_all_state_buffers_and_preserves_prior_ownership() {
b.charge(Q::RegistryBytes, 11).unwrap();
validate_registry_stacks(&code, &r, 1, &mut b).unwrap();
assert_eq!((b.used(Q::TemporaryBytes), b.used(Q::RegistryBytes)), (7, 11));
let mut limits = LoadLimits::default();
limits.temporary_bytes = 32; // Decode maps fit; CFG/state/work buffers cannot all fit.
// Decode maps fit; CFG/state/work buffers cannot all fit.
let limits = LoadLimits { temporary_bytes: 32, ..Default::default() };
let mut b = LoadBudget::new(limits);
b.charge(Q::TemporaryBytes, 7).unwrap();
let e = validate_registry_stacks(&code, &r, 1, &mut b).unwrap_err();
@@ -214,8 +214,7 @@ fn stack_analysis_straight_line_storage_is_bounded_by_blocks_not_instruction_fra
&code,
vec![FunctionDecl { local_slots: 300, max_stack_slots: 0, ..function(&code) }],
);
let mut limits = LoadLimits::default();
limits.temporary_bytes = 41_000;
let limits = LoadLimits { temporary_bytes: 41_000, ..Default::default() };
let mut b = LoadBudget::new(limits);
validate_registry_stacks(&code, &r, 1, &mut b).unwrap();
assert_eq!(b.used(Q::TemporaryBytes), 0);
@@ -336,8 +335,7 @@ fn stack_analysis_charges_work_for_loop_reprocessing_and_refunds_on_exhaustion()
);
let mut b = LoadBudget::new(Default::default());
validate_registry_stacks(&code, &r, 1, &mut b).unwrap();
let mut limits = LoadLimits::default();
limits.work = b.used(Q::Work) - 1;
let limits = LoadLimits { work: b.used(Q::Work) - 1, ..Default::default() };
let mut limited = LoadBudget::new(limits);
limited.charge(Q::TemporaryBytes, 7).unwrap();
let e = validate_registry_stacks(&code, &r, 1, &mut limited).unwrap_err();
@@ -433,8 +431,7 @@ fn local_bounds_use_derived_parameter_widths_and_u32_local_counts() {
let e = check(&bad, &r).unwrap_err();
assert_eq!((e.reason, e.member), (R::LocalSlot, Some(slot)));
}
let mut limits = LoadLimits::default();
limits.frame_slots = 74;
let limits = LoadLimits { frame_slots: 74, ..Default::default() };
let mut budget = LoadBudget::new(limits);
let e = validate_registry_instructions(&code, &r, 1, &mut budget).unwrap_err();
assert_eq!(e.reason, R::FrameSlots); // 2 parameters + 69 locals + 4 temporaries = 75.
@@ -506,8 +503,7 @@ fn scratch_is_refunded_per_function_and_preserves_prior_load_ownership() {
FunctionDecl { code_offset: 2, code_len: 2, ..function(&code) },
],
);
let mut limits = LoadLimits::default();
limits.temporary_bytes = 8;
let limits = LoadLimits { temporary_bytes: 8, ..Default::default() };
let mut budget = LoadBudget::new(limits);
budget.charge(Q::TemporaryBytes, 5).unwrap();
budget.charge(Q::RegistryBytes, 10).unwrap();
@@ -227,12 +227,12 @@ fn invalidate(
}
budget.work(working.len() * 2)?;
for fact in working {
if let Fact::Group { ty, part, origin: other } = *fact {
if origin == other {
let carrier = component(registry, ty, part, budget)?;
budget.work(1)?;
*fact = if carrier == ANY { Fact::Unknown } else { Fact::Carrier(carrier) };
}
if let Fact::Group { ty, part, origin: other } = *fact
&& origin == other
{
let carrier = component(registry, ty, part, budget)?;
budget.work(1)?;
*fact = if carrier == ANY { Fact::Unknown } else { Fact::Carrier(carrier) };
}
}
Ok(())
@@ -514,11 +514,11 @@ fn abi_mask(abi: AbiType) -> u8 {
fn invalidate_dynamic(values: &mut [Fact], origin: u64, budget: &mut LoadBudget) -> Result<(), E> {
budget.work(values.len() * 2)?;
for value in values {
if let Fact::Dynamic { part, origin: other } = *value {
if origin == other {
budget.work(1)?;
*value = if part == 0 { Fact::Carrier(I64 | NULL) } else { Fact::Unknown };
}
if let Fact::Dynamic { part, origin: other } = *value
&& origin == other
{
budget.work(1)?;
*value = if part == 0 { Fact::Carrier(I64 | NULL) } else { Fact::Unknown };
}
}
Ok(())
@@ -586,10 +586,10 @@ fn check_group(
let color = matches!(kind, TypeKind::Builtin(B::COLOR | B::PIXEL));
if color {
budget.work(1)?;
if let Fact::Int64(value) = values[width - 1] {
if u32::try_from(value).is_err() {
return Err(mismatch(width - 1).reference(IdDomain::Type, ty.0));
}
if let Fact::Int64(value) = values[width - 1]
&& u32::try_from(value).is_err()
{
return Err(mismatch(width - 1).reference(IdDomain::Type, ty.0));
}
}
Ok(())
@@ -295,8 +295,7 @@ fn type_analysis_is_metered_and_releases_scratch_on_success_and_failure() {
let mut full = LoadBudget::new(Default::default());
validate_registry_types(&code, &r, &[], &mut full).unwrap();
assert_eq!(full.used(Q::TemporaryBytes), 0);
let mut limits = LoadLimits::default();
limits.work = full.used(Q::Work) - 1;
let limits = LoadLimits { work: full.used(Q::Work) - 1, ..Default::default() };
let mut limited = LoadBudget::new(limits);
limited.charge(Q::TemporaryBytes, 7).unwrap();
let e = validate_registry_types(&code, &r, &[], &mut limited).unwrap_err();
@@ -1,21 +1,9 @@
//! 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::fmt;
use std::sync::{Arc, Mutex, MutexGuard};
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(usize)]
pub enum RuntimeResource {
GuestBytes,
HandleSlots,
AuxiliaryBytes,
TemporaryBytes,
StringBytes,
StringAllocations,
IndividualStringBytes,
CallDepth,
}
pub use prometeu_bytecode::{ResourceFailure, ResourceReason, RuntimeResource};
const COUNT: usize = 8;
const MIB: u64 = 1_048_576;
const CEILINGS: [u64; COUNT] =
@@ -51,30 +39,6 @@ impl RuntimeLimits {
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ResourceReason {
Limit,
SizeOverflow,
AllocationFailed,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct ResourceFailure {
pub resource: RuntimeResource,
pub reason: ResourceReason,
pub requested: u64,
pub limit: u64,
}
impl fmt::Display for ResourceFailure {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(
f,
"{:?}: {:?}, requested {}, limit {}",
self.resource, self.reason, self.requested, self.limit
)
}
}
impl std::error::Error for ResourceFailure {}
#[derive(Debug)]
struct State {
limits: RuntimeLimits,
@@ -339,3 +339,6 @@ fn drop_native(data: &mut Allocation, offset: usize, ownership: Ownership) {
#[cfg(test)]
pub(crate) mod tests;
#[cfg(test)]
mod ownership_tests;
@@ -0,0 +1,36 @@
use super::*;
use crate::heap::Heap;
use crate::string_ledger::StringLedger;
#[test]
fn session_string_charge_survives_alias_removal_until_last_storage_owner_is_collected() {
let registry = tests::fixture_registry();
let budget = RuntimeBudget::default();
let strings = StringLedger::new(budget.clone()).unwrap();
let mut heap = Heap::with_budget(&budget);
let text = strings.import("é猫").unwrap();
let weak = Arc::downgrade(&text);
let holder = heap.allocate_typed_struct(registry.clone(), TypeId(11)).unwrap();
heap.store_typed(&registry, holder, 3, &[Value::String(text.clone())]).unwrap();
heap.store_typed(&registry, holder, 4, &[Value::Int64(7), Value::String(text)]).unwrap();
assert_eq!(budget.used(Q::StringBytes), 5);
assert_eq!(budget.used(Q::StringAllocations), 1);
heap.mark_from_roots([holder]).unwrap();
heap.sweep();
assert_eq!(strings.reconcile(), 0);
assert!(weak.upgrade().is_some());
heap.store_typed(&registry, holder, 3, &[Value::Null]).unwrap();
assert_eq!(strings.reconcile(), 0);
let dynamic = heap.load_typed(&registry, holder, 4).unwrap();
let [Value::Int64(7), Value::String(alias)] = dynamic.as_slice() else {
panic!("retained string")
};
assert!(Arc::ptr_eq(alias, &weak.upgrade().unwrap()));
drop(dynamic);
heap.sweep();
assert_eq!(strings.reconcile(), 1);
assert!(weak.upgrade().is_none());
assert_eq!(budget.used(Q::StringBytes), 0);
assert_eq!(budget.used(Q::StringAllocations), 0);
assert_eq!(budget.used(Q::GuestBytes), 0);
}
@@ -526,3 +526,156 @@ fn typed_dynamic_self_cycle_uses_one_mark_worklist_entry() {
heap.sweep();
assert_eq!(budget.used(Q::GuestBytes), 0);
}
#[test]
#[ignore = "explicit release measurement; not a timing assertion"]
fn storage_and_gc_probe() {
use crate::value_contract::{pack_dynamic, unpack_dynamic};
use std::hint::black_box;
use std::time::Instant;
println!(
"native arch={} Value={}/{} HeapRef={}/{} StringSlot={}/{} DynamicSlot={}/{} TraitSlot={}/{} StoredObject={}/{}",
std::env::consts::ARCH,
size_of::<Value>(),
align_of::<Value>(),
size_of::<HeapRef>(),
align_of::<HeapRef>(),
size_of::<StringSlot>(),
align_of::<StringSlot>(),
size_of::<DynamicSlot>(),
align_of::<DynamicSlot>(),
size_of::<TraitSlot>(),
align_of::<TraitSlot>(),
size_of::<StoredObject>(),
align_of::<StoredObject>()
);
let registry = fixture_registry();
for array in [INTS, BOOLS, VECS, PIXELS, REFS, STRINGS, TRAITS, DYNAMICS] {
let budget = RuntimeBudget::default();
let mut heap = Heap::with_budget(&budget);
let layout = registry.type_layout(array).unwrap().array.unwrap();
let count = 4096;
let start = Instant::now();
let reference = heap.allocate_typed_array(registry.clone(), array, count).unwrap();
let allocation_ns = start.elapsed().as_nanos();
let default =
registry.type_layout(layout.element_type_id).unwrap().storage.default_values();
assert_eq!(heap.load_typed(&registry, reference, 4095).unwrap().as_slice(), default);
let start = Instant::now();
for index in 0..100_000 {
black_box(
heap.load_typed(black_box(&registry), reference, index % count as usize).unwrap(),
);
}
let access_ns = start.elapsed().as_nanos();
println!(
"array type={} count={} stride={} align={} guest={} aux={} handles={} allocation_ns={} reads=100000 access_ns={}",
array.0,
count,
layout.stride,
layout.element_alignment,
budget.used(Q::GuestBytes),
budget.used(Q::AuxiliaryBytes),
budget.used(Q::HandleSlots),
allocation_ns,
access_ns
);
heap.mark_from_roots([reference]).unwrap();
heap.sweep();
assert_eq!(heap.len(), 1);
heap.sweep();
assert_eq!(budget.used(Q::GuestBytes), 0);
drop(heap);
assert_eq!(budget.used(Q::AuxiliaryBytes), 0);
}
for period in [1, 16, 256] {
let mut declarations = registry.declarations().clone();
let ty = TypeId(declarations.types.len() as u32);
declarations.types.push(TypeDecl {
name: None,
kind: TypeKind::Struct(
(0..4096)
.map(|index| NamedType {
name: None,
type_id: if index % period == 0 { ENEMY } else { I64 },
})
.collect(),
),
});
let mut load = LoadBudget::new(Default::default());
let registry = Arc::new(Registry::resolve(declarations, 0, &mut load).unwrap());
let budget = RuntimeBudget::default();
let mut heap = Heap::with_budget(&budget);
let holder = heap.allocate_typed_struct(registry.clone(), ty).unwrap();
let child = heap.allocate_typed_struct(registry.clone(), ENEMY).unwrap();
let dead = heap.allocate_typed_struct(registry.clone(), ENEMY).unwrap();
for index in (0..4096).step_by(period) {
heap.store_typed(&registry, holder, index, &[Value::HeapRef(child)]).unwrap();
}
let start = Instant::now();
for _ in 0..1000 {
heap.mark_from_roots([holder]).unwrap();
heap.sweep();
}
let gc_ns = start.elapsed().as_nanos();
assert_eq!(heap.len(), 2);
assert!(heap.is_valid(child));
assert!(!heap.is_valid(dead));
assert_eq!(budget.used(Q::TemporaryBytes), 0);
println!(
"gc period={} fields=4096 roots={} live={} guest={} aux={} work={} load_peak_scratch={} rounds=1000 gc_ns={}",
period,
4096 / period,
heap.len(),
budget.used(Q::GuestBytes),
budget.used(Q::AuxiliaryBytes),
load.used(prometeu_bytecode::load_limits::LoadResource::Work),
load.peak_usage(prometeu_bytecode::load_limits::LoadResource::TemporaryBytes),
gc_ns
);
}
let budget = RuntimeBudget::default();
let mut heap = Heap::with_budget(&budget);
let start = Instant::now();
let dynamic =
pack_dynamic(&registry, &mut heap, VEC, &[Value::Float(3.0), Value::Float(4.0)]).unwrap();
let pack_ns = start.elapsed().as_nanos();
let start = Instant::now();
for _ in 0..100_000 {
black_box(unpack_dynamic(&registry, &heap, VEC, black_box(dynamic.as_slice())).unwrap());
}
println!(
"dynamic vec2_boxes={} guest={} pack_ns={} unpacks=100000 unpack_ns={}",
heap.len(),
budget.used(Q::GuestBytes),
pack_ns,
start.elapsed().as_nanos()
);
let holder = heap.allocate_typed_array(registry.clone(), DYNAMICS, 1).unwrap();
heap.store_typed(&registry, holder, 0, dynamic.as_slice()).unwrap();
heap.mark_from_roots([holder]).unwrap();
heap.sweep();
assert_eq!(heap.len(), 2);
heap.sweep();
assert_eq!(budget.used(Q::GuestBytes), 0);
let strings = crate::string_ledger::StringLedger::new(budget.clone()).unwrap();
let text = strings.import("shared-native").unwrap();
let weak = Arc::downgrade(&text);
let root = heap.allocate_typed_struct(registry.clone(), MIXED).unwrap();
heap.store_typed(&registry, root, 3, &[Value::String(text.clone())]).unwrap();
heap.store_typed(&registry, root, 4, &[Value::Int64(STRING.0.into()), Value::String(text)])
.unwrap();
assert_eq!(budget.used(Q::StringBytes), 13);
heap.mark_from_roots([root]).unwrap();
heap.sweep();
strings.reconcile();
assert!(weak.upgrade().is_some());
assert_eq!(budget.used(Q::StringBytes), 13);
heap.sweep();
strings.reconcile();
assert!(weak.upgrade().is_none());
assert_eq!(budget.used(Q::StringBytes), 0);
println!(
"native_string content=13 storage_owners=2 allocations=1 rooted_gc=retained unrooted_gc=released"
);
}
@@ -153,15 +153,17 @@ impl VirtualMachine {
let mut owners = [None, None];
for value in &values {
if let Value::String(content) = value {
if let Some(image) = &self.validated_image {
if owners[0].is_none() && image.retains_string(content) {
owners[0] = Some(image.string_retention());
}
if let Some(image) = &self.validated_image
&& owners[0].is_none()
&& image.retains_string(content)
{
owners[0] = Some(image.string_retention());
}
if let Some(strings) = &self.strings {
if owners[1].is_none() && strings.retains(content) {
owners[1] = Some(strings.retention());
}
if let Some(strings) = &self.strings
&& owners[1].is_none()
&& strings.retains(content)
{
owners[1] = Some(strings.retention());
}
}
}
@@ -1264,6 +1266,9 @@ impl VirtualMachine {
self.operand_stack.truncate(stack_height_before);
}
native_result.map_err(|fault| match fault {
VmFault::ResourceLimit(resource) => {
self.resource_trap(resource, opcode, pc_at_syscall)
}
VmFault::Trap(code, msg) => {
self.trap(code, OpCode::Syscall as u16, msg, pc_at_syscall)
}
@@ -18,7 +18,10 @@ impl VirtualMachine {
opcode: OpCode,
pc: u32,
) -> LogicalFrameEndingReason {
self.trap(TRAP_RESOURCE_LIMIT, opcode as u16, error.to_string(), pc)
let mut trap =
self.program.create_trap(TRAP_RESOURCE_LIMIT, opcode as u16, error.to_string(), pc);
trap.resource = Some(error);
LogicalFrameEndingReason::Trap(trap)
}
pub fn trap(
@@ -7,6 +7,9 @@ pub(super) struct SessionStringAllocator<'a> {
pub budget: RuntimeBudget,
}
impl prometeu_hal::host_return::GuestStringAllocator for SessionStringAllocator<'_> {
fn byte_limit(&self) -> u64 {
self.budget.limit(RuntimeResource::StringBytes)
}
fn build(
&mut self,
length: usize,
@@ -24,7 +27,7 @@ impl prometeu_hal::host_return::GuestStringAllocator for SessionStringAllocator<
}
}
fn resource_fault(resource: ResourceFailure) -> VmFault {
VmFault::Trap(TRAP_RESOURCE_LIMIT, resource.to_string())
VmFault::ResourceLimit(resource)
}
impl VirtualMachine {
@@ -151,7 +151,7 @@ fn decoded_dynamic_scalar_string_reference_and_null_paths_have_exact_attempt_cos
(13, Value::Null),
] {
let mut pack = dynamic_vm(OpCode::DynPack, ty, 1, 2, RuntimeLimits::default());
load_globals_and_step(&mut pack, &[value.clone()]).unwrap();
load_globals_and_step(&mut pack, std::slice::from_ref(&value)).unwrap();
assert_eq!(pack.operand_stack.as_slice(), &[Value::Int64(ty.into()), value.clone()]);
let pair = pack.operand_stack.as_slice();
let mut unpack = dynamic_vm(OpCode::DynUnpack, ty, 2, 1, RuntimeLimits::default());
@@ -203,6 +203,50 @@ fn decoded_dynamic_box_roundtrip_and_identity_never_nest_boxes() {
}
}
#[test]
fn decoded_trait_box_is_the_only_receiver_root_across_frame_sync_gc() {
let mut code = vec![];
arg(&mut code, OpCode::GetGlobal, 0);
arg(&mut code, OpCode::GetGlobal, 1);
arg(&mut code, OpCode::DynPack, 11);
op(&mut code, OpCode::FrameSync);
arg(&mut code, OpCode::DynUnpack, 11);
op(&mut code, OpCode::Pop);
op(&mut code, OpCode::Pop);
op(&mut code, OpCode::FrameSync);
op(&mut code, OpCode::Halt);
let image = image(&code, vec![function(0, code.len(), &[], &[], 0, 2)]);
let registry = image.registry().clone();
let mut vm = VirtualMachine::from_image(image, RuntimeLimits::default());
vm.prepare_boot_call().unwrap();
let receiver = vm.heap.allocate_typed_struct(registry, TypeId(9)).unwrap();
load_globals_and_step(&mut vm, &[Value::HeapRef(receiver), Value::Int64(0)]).unwrap();
let Value::HeapRef(box_handle) = vm.operand_stack[1] else { panic!("box handle") };
vm.globals.clear();
vm.gc_alloc_threshold = 1;
vm.last_gc_live_count = 0;
assert!(matches!(
vm.step(&mut Native, &mut HostContext::new(None)),
Err(LogicalFrameEndingReason::FrameSync)
));
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.
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();
vm.step(&mut Native, &mut HostContext::new(None)).unwrap();
// Force the next permitted GC even though no allocation occurred between safepoints.
vm.last_gc_live_count = 0;
assert!(matches!(
vm.step(&mut Native, &mut HostContext::new(None)),
Err(LogicalFrameEndingReason::FrameSync)
));
assert!(!vm.heap.is_valid(receiver));
assert!(!vm.heap.is_valid(box_handle));
assert_eq!(vm.heap.len(), 1);
}
#[test]
fn decoded_dynamic_malformed_pairs_trap_once_without_consuming_source() {
for operation in [OpCode::DynUnpack, OpCode::DynCanUnpack] {
@@ -527,7 +571,7 @@ fn native_string_failures_cannot_publish_partial_results_even_if_handler_ignores
// This synthetic native implementation tests the bounded writer, not the
// has-cart handler's ordinary Boolean semantic contract.
assert!(
matches!(report.reason,LogicalFrameEndingReason::Trap(info) if info.code==TRAP_RESOURCE_LIMIT && info.pc==0)
matches!(report.reason,LogicalFrameEndingReason::Trap(info) if info.code==TRAP_RESOURCE_LIMIT && info.pc==0 && info.resource.is_some_and(|resource|resource.resource==RuntimeResource::StringBytes && resource.requested==3 && resource.limit==2))
);
assert!(vm.operand_stack.is_empty());
assert_eq!(vm.budget.used(RuntimeResource::StringBytes), 0);
@@ -0,0 +1,92 @@
use prometeu_bytecode::load_limits::LoadBudget;
use prometeu_bytecode::registry::{
BuiltinId, FunctionDecl, NamedType, Registry, RegistryDeclarations, Signature, TypeDecl,
TypeId, TypeKind,
};
use prometeu_bytecode::registry_codec::PbxModule;
use prometeu_bytecode::{Value, assemble};
use prometeu_hal::{HostContext, HostReturn, NativeInterface, syscalls::caps, vm_fault::VmFault};
use prometeu_vm::{
LogicalFrameEndingReason, ValidatedProgramImage, VirtualMachine, resource_budget::RuntimeLimits,
};
struct NoNative;
impl NativeInterface for NoNative {
fn syscall(
&mut self,
_id: u32,
_args: &[Value],
_ret: &mut HostReturn,
_ctx: &mut HostContext,
) -> Result<(), VmFault> {
panic!("oracle has no native calls")
}
}
#[test]
fn named_arguments_preserve_source_effect_order_and_call_in_signature_order_without_debug() {
// Frontend oracle: combine(y: effectY(20), x: effectX(10)).
// Trace appends Y=2 before X=1; combine(x,y) computes x*100+y.
let bodies=[
assemble("PUSH_I32 0\nSET_GLOBAL 0\nCALL 2\nSET_LOCAL 0\nCALL 1\nSET_LOCAL 1\nGET_LOCAL 1\nGET_LOCAL 0\nCALL 3\nSET_GLOBAL 1\nGET_GLOBAL 0\nGET_GLOBAL 1\nHALT").unwrap(),
assemble("GET_GLOBAL 0\nPUSH_I32 10\nMUL\nPUSH_I32 1\nADD\nSET_GLOBAL 0\nPUSH_I32 10\nRET").unwrap(),
assemble("GET_GLOBAL 0\nPUSH_I32 10\nMUL\nPUSH_I32 2\nADD\nSET_GLOBAL 0\nPUSH_I32 20\nRET").unwrap(),
assemble("GET_LOCAL 0\nPUSH_I32 100\nMUL\nGET_LOCAL 1\nADD\nRET").unwrap(),
];
let mut code = vec![];
let mut functions = vec![];
for (index, body) in bodies.iter().enumerate() {
let parameters = if index == 3 {
vec![
NamedType { type_id: TypeId(0), name: Some("x".into()) },
NamedType { type_id: TypeId(0), name: Some("y".into()) },
]
} else {
vec![]
};
functions.push(FunctionDecl {
name: Some(["main", "effectX", "effectY", "combine"][index].into()),
signature: Signature {
parameters,
results: if index == 0 { vec![] } else { vec![TypeId(0)] },
},
code_offset: code.len() as u32,
code_len: body.len() as u32,
local_slots: if index == 0 { 2 } else { 0 },
max_stack_slots: 2,
});
code.extend_from_slice(body);
}
let registry = Registry::resolve(
RegistryDeclarations {
types: vec![TypeDecl { name: None, kind: TypeKind::Builtin(BuiltinId::INT32) }],
functions,
..Default::default()
},
code.len(),
&mut LoadBudget::new(Default::default()),
)
.unwrap();
let bytes = PbxModule {
registry: &registry,
code: &code,
constants: &[],
debug: None,
exports: &[],
syscalls: &[],
}
.serialize(&mut LoadBudget::new(Default::default()))
.unwrap();
let image =
ValidatedProgramImage::load(&bytes, &mut LoadBudget::new(Default::default()), caps::NONE)
.unwrap();
assert!(image.debug().is_none());
let parameters = &image.registry().declarations().functions[3].signature.parameters;
assert_eq!(parameters[0].name.as_deref(), Some("x"));
assert_eq!(parameters[1].name.as_deref(), Some("y"));
let mut vm = VirtualMachine::from_image(image, RuntimeLimits::default());
vm.prepare_boot_call().unwrap();
let report = vm.run_budget(10_000, &mut NoNative, &mut HostContext::new(None)).unwrap();
assert_eq!(report.reason, LogicalFrameEndingReason::Halted);
assert_eq!(vm.operand_stack_top(2), vec![Value::Int32(1020), Value::Int32(21)]);
}
@@ -0,0 +1,112 @@
use prometeu_bytecode::Value;
use prometeu_bytecode::load_limits::{LoadBudget, LoadCode, LoadLimits, LoadReason, LoadResource};
use prometeu_hal::{HostContext, HostReturn, NativeInterface, syscalls::caps, vm_fault::VmFault};
use prometeu_vm::{
LogicalFrameEndingReason, ValidatedProgramImage, VirtualMachine, VmInitError,
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.
fn minimal() -> Vec<u8> {
"50 42 58 00 01 00 00 00 07 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
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
01 00
00 00 00 00
00 00 00 00
01 00 00 00 00 00 13 00 00 00
00 00 00 00"
.split_whitespace()
.map(|byte| u8::from_str_radix(byte, 16).unwrap())
.collect()
}
struct Native;
impl NativeInterface for Native {
fn syscall(
&mut self,
_id: u32,
_args: &[Value],
_ret: &mut HostReturn,
_ctx: &mut HostContext,
) -> Result<(), VmFault> {
panic!("HALT oracle has no native call")
}
}
#[test]
fn independent_v1_bytes_load_publish_and_execute_through_the_public_sealed_boundary() {
let bytes = minimal();
assert_eq!(bytes.len(), 173);
let mut load = LoadBudget::new(Default::default());
let image = ValidatedProgramImage::load(&bytes, &mut load, caps::NONE).unwrap();
assert_eq!(load.used(LoadResource::TemporaryBytes), 0);
assert_eq!(image.registry().declarations().functions[0].max_stack_slots, 0);
let mut vm = VirtualMachine::from_image(image, RuntimeLimits::default());
vm.prepare_boot_call().unwrap();
let report = vm.run_budget(100, &mut Native, &mut HostContext::new(None)).unwrap();
assert_eq!(report.reason, LogicalFrameEndingReason::Halted);
assert_eq!(report.steps_executed, 1);
assert!(vm.operand_stack_top(1).is_empty());
}
#[test]
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)),
] {
let mut bytes = minimal();
bytes[offset] = replacement;
let mut load = LoadBudget::new(Default::default());
load.charge(LoadResource::TemporaryBytes, 7).unwrap();
load.charge(LoadResource::RegistryBytes, 3).unwrap();
let VmInitError::RegistryLoadFailed(error) =
ValidatedProgramImage::load(&bytes, &mut load, caps::NONE).unwrap_err()
else {
panic!()
};
assert_eq!((error.code, error.reason, error.pc), (code, reason, pc));
if pc.is_some() {
assert_eq!(error.function, Some(0));
assert_eq!(error.section, Some(2));
}
assert_eq!(load.used(LoadResource::TemporaryBytes), 7);
assert_eq!(load.used(LoadResource::RegistryBytes), 3);
assert_eq!(load.used(LoadResource::Functions), 0);
assert_eq!(load.used(LoadResource::PbxBytes), 0);
}
}
#[test]
fn load_scratch_and_session_depth_are_separate_admission_failures() {
let mut load = LoadBudget::new(LoadLimits { temporary_bytes: 0, ..Default::default() });
assert!(
matches!(ValidatedProgramImage::load(&minimal(),&mut load,caps::NONE),Err(VmInitError::RegistryLoadFailed(error)) if error.resource==Some(LoadResource::TemporaryBytes))
);
assert_eq!(load.used(LoadResource::RegistryBytes), 0);
let image = ValidatedProgramImage::load(
&minimal(),
&mut LoadBudget::new(Default::default()),
caps::NONE,
)
.unwrap();
let limits = RuntimeLimits::default().lowered(RuntimeResource::CallDepth, 0).unwrap();
let mut vm = VirtualMachine::from_image(image, limits);
assert!(
matches!(vm.prepare_boot_call(),Err(VmInitError::RuntimeResourceLimit(error)) if error.resource==RuntimeResource::CallDepth && error.requested==1 && error.limit==0)
);
assert!(vm.call_stack_is_empty());
assert_eq!(vm.heap().len(), 0);
}
@@ -379,6 +379,10 @@ impl HostDebugger {
CrashReport::VmTrap { trap } => (Some(trap.code), Some(trap.opcode)),
CrashReport::VmPanic { .. } | CrashReport::VmInit { .. } => (None, None),
};
let span = match report {
CrashReport::VmTrap { trap } => trap.span.clone(),
_ => None,
};
self.send_event(DebugEvent::Fault {
kind: report.kind().to_string(),
@@ -386,6 +390,9 @@ impl HostDebugger {
pc: report.pc(),
trap_code,
opcode,
span,
resource: report.resource_failure(),
init: report.init_diagnostic(),
});
self.last_fault_summary = Some(summary);
}
@@ -2,10 +2,11 @@ use base64::{Engine as _, engine::general_purpose::STANDARD};
use prometeu_bytecode::Value as VmValue;
use prometeu_hal::InputSignals;
use prometeu_system::CrashReport;
use prometeu_vm::VmInitError;
use serde::{Deserialize, Serialize};
use serde_json::{Value, json};
use std::io;
#[cfg(test)]
mod fault_tests;
use crate::{CapturedFrame, HostError, HostExecutionStatus, HostState};
@@ -232,7 +233,7 @@ pub(super) fn host_error(error: HostError) -> WireError {
let (code, details) = match &error {
HostError::AlreadyBooted => ("already_booted", json!({})),
HostError::BootFailed { reason, report } => {
("boot_failed", json!({"reason":reason,"fault":report.as_ref().map(fault)}))
("boot_failed", json!({"reason":reason,"fault":report.as_deref().map(fault)}))
}
HostError::InvalidState { operation, status } => {
("invalid_state", json!({"operation":operation,"status":status_name(*status)}))
@@ -282,24 +283,13 @@ pub(super) fn fault(report: &CrashReport) -> Value {
match report {
CrashReport::VmTrap { trap } => {
result["trap"] = json!({"code":trap.code,"opcode":trap.opcode,
"message":trap.message,"pc":trap.pc,"span":trap.span});
"message":trap.message,"pc":trap.pc,"span":trap.span,"resource":trap.resource});
}
CrashReport::VmPanic { message, .. } => {
result["message"] = json!(message);
}
CrashReport::VmInit { error } => {
let code = match error {
VmInitError::RegistryLoadFailed(_) => "registry_load_failed",
VmInitError::RuntimeResourceLimit(_) => "runtime_resource_limit",
VmInitError::InvalidFormat => "invalid_format",
VmInitError::UnsupportedFormat => "unsupported_format",
VmInitError::ImageLoadFailed(_) => "image_load_failed",
VmInitError::LoaderPatchFailed(_) => "loader_patch_failed",
VmInitError::EntrypointNotFound => "entrypoint_not_found",
VmInitError::EntrypointArgumentsInvalid { .. } => "entrypoint_arguments_invalid",
VmInitError::VerificationFailed(_) => "verification_failed",
};
result["initError"] = json!({"code":code,"message":format!("{error:?}")});
CrashReport::VmInit { .. } => {
result["initError"] = report.init_diagnostic().expect("initialization report");
}
}
result
@@ -0,0 +1,47 @@
use super::*;
use prometeu_bytecode::{
ResourceFailure, ResourceReason, RuntimeResource, SourceSpan, TRAP_RESOURCE_LIMIT, TrapInfo,
};
#[test]
fn resource_trap_wire_preserves_native_fields_and_source_span() {
let report = CrashReport::VmTrap {
trap: TrapInfo {
code: TRAP_RESOURCE_LIMIT,
opcode: 0x90,
pc: 18,
message: "localized human wording".into(),
span: Some(SourceSpan { file_id: 7, start: 4, end: 9 }),
resource: Some(ResourceFailure {
resource: RuntimeResource::HandleSlots,
reason: ResourceReason::Limit,
requested: 3,
limit: 2,
}),
},
};
let wire = fault(&report);
assert_eq!(wire["trap"]["code"], 0x10);
assert_eq!(wire["trap"]["opcode"], 0x90);
assert_eq!(wire["trap"]["pc"], 18);
assert_eq!(wire["trap"]["span"]["file_id"], 7);
assert_eq!(wire["trap"]["resource"]["resource"], "HandleSlots");
assert_eq!(wire["trap"]["resource"]["requested"], 3);
assert_eq!(wire["trap"]["resource"]["limit"], 2);
}
#[test]
fn load_failure_wire_uses_shared_structured_serializer_and_no_runtime_pc() {
use prometeu_bytecode::load_limits::{LoadCode, LoadFailure, LoadReason, LoadResource};
let mut error = LoadFailure::resource(LoadResource::Work, 23, 22).in_function(1, Some(6));
error.code = LoadCode::ResourceLimit;
error.reason = LoadReason::Limit;
let report = CrashReport::VmInit { error: prometeu_vm::VmInitError::RegistryLoadFailed(error) };
let wire = fault(&report);
assert_eq!(wire["pc"], Value::Null);
assert_eq!(wire["initError"], report.init_diagnostic().unwrap());
assert_eq!(wire["initError"]["load"]["code"], "LOAD_RESOURCE_LIMIT");
assert_eq!(wire["initError"]["load"]["resource"], "Work");
assert_eq!(wire["initError"]["load"]["requested"], 23);
assert_eq!(wire["initError"]["load"]["limit"], 22);
}
@@ -65,7 +65,7 @@ pub struct AdvanceFramesOutcome {
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum HostError {
AlreadyBooted,
BootFailed { reason: String, report: Option<CrashReport> },
BootFailed { reason: String, report: Option<Box<CrashReport>> },
InvalidState { operation: &'static str, status: HostExecutionStatus },
FrameAdvanceWatchdogExpired { host_tick_limit: usize },
FrameNotPublished { previous: Option<FrameId> },
@@ -152,7 +152,7 @@ impl HeadlessHost {
.as_ref()
.map(CrashReport::summary)
.unwrap_or_else(|| "cartridge crashed during boot".to_string());
return Err(HostError::BootFailed { reason, report });
return Err(HostError::BootFailed { reason, report: report.map(Box::new) });
}
if matches!(self.firmware.state, FirmwareState::HubHome(_)) {
return Err(HostError::BootFailed {
@@ -168,7 +168,7 @@ impl HeadlessHost {
} else {
Err(HostError::BootFailed {
reason: "boot did not reach the game".to_string(),
report: self.get_fault(),
report: self.get_fault().map(Box::new),
})
}
}
@@ -330,12 +330,12 @@ fn vm_init_failure_is_returned_as_structured_boot_failure() {
let mut host = HeadlessHost::new();
let error = host.boot(&dir).expect_err("invalid PBX must fail boot");
assert!(matches!(
error,
HostError::BootFailed { report: Some(CrashReport::VmInit { .. }), .. }
));
let HostError::BootFailed { report: Some(report), .. } = error else {
panic!("expected structured boot failure: {error:?}");
};
assert!(matches!(report.as_ref(), CrashReport::VmInit { .. }));
assert_eq!(host.get_state().status, HostExecutionStatus::Faulted);
assert!(matches!(host.get_fault(), Some(CrashReport::VmInit { .. })));
assert_eq!(host.get_fault().as_ref(), Some(report.as_ref()));
}
#[test]
@@ -0,0 +1,46 @@
use serde_json::{Value, json};
fn schema() -> jsonschema::Validator {
let full: Value = serde_json::from_str(include_str!(
"../../../../devtools/headless-protocol/response.schema.json"
))
.unwrap();
jsonschema::validator_for(&json!({"$defs":full["$defs"],"$ref":"#/$defs/fault"})).unwrap()
}
#[test]
fn published_schema_accepts_structured_resource_fields_and_rejects_unknown_or_negative_values() {
let schema = schema();
let valid = json!({"kind":"vm_trap","pc":18,"summary":"human wording","trap":{
"code":16,"opcode":144,"pc":18,"message":"unrelated localized text","span":{"file_id":7,"start":4,"end":9},
"resource":{"resource":"HandleSlots","reason":"Limit","requested":3,"limit":2}}});
schema.validate(&valid).unwrap();
for (field, value) in [
("resource", json!("Bogus")),
("requested", json!(-1)),
("reason", json!("arbitrary text")),
] {
let mut invalid = valid.clone();
invalid["trap"]["resource"][field] = value;
assert!(schema.validate(&invalid).is_err());
}
}
#[test]
fn published_load_schema_requires_tag_context_and_the_matching_init_payload() {
let schema = schema();
let valid = json!({"kind":"vm_init","pc":null,"summary":"human wording","initError":{
"code":"registry_load_failed","message":"unrelated human text","load":{
"code":"LOAD_INVALID_REFERENCE","reason":"TypeId","section":6,"offset":159,"record":4,"member":2,
"id_domain":"Type","referenced_id":77,"function":3,"pc":18,"resource":null,"requested":null,"limit":null}}});
schema.validate(&valid).unwrap();
let mut invalid = valid.clone();
invalid["initError"]["load"]["referenced_id"] = json!(4294967296u64);
assert!(schema.validate(&invalid).is_err());
let mut invalid = valid.clone();
invalid["initError"]["load"]["code"] = json!("InvalidReference");
assert!(schema.validate(&invalid).is_err());
let mut invalid = valid.clone();
invalid["initError"]["code"] = json!("invalid_format");
assert!(schema.validate(&invalid).is_err());
}
+717 -16
View File
@@ -396,9 +396,23 @@
"minimum": 0
},
"span": {
"type": [
"object",
"null"
"anyOf": [
{
"$ref": "#/$defs/sourceSpan"
},
{
"type": "null"
}
]
},
"resource": {
"anyOf": [
{
"$ref": "#/$defs/resourceFailure"
},
{
"type": "null"
}
]
}
},
@@ -407,7 +421,8 @@
"opcode",
"message",
"pc",
"span"
"span",
"resource"
],
"additionalProperties": false
}
@@ -465,20 +480,191 @@
"const": "vm_init"
},
"initError": {
"type": "object",
"properties": {
"code": {
"type": "string"
"oneOf": [
{
"type": "object",
"properties": {
"code": {
"const": "registry_load_failed"
},
"message": {
"type": "string"
},
"load": {
"$ref": "#/$defs/loadFailure"
}
},
"required": [
"code",
"message",
"load"
],
"additionalProperties": false
},
"message": {
"type": "string"
{
"type": "object",
"properties": {
"code": {
"const": "runtime_resource_limit"
},
"message": {
"type": "string"
},
"resource": {
"$ref": "#/$defs/resourceFailure"
}
},
"required": [
"code",
"message",
"resource"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"code": {
"const": "entrypoint_arguments_invalid"
},
"message": {
"type": "string"
},
"entry": {
"type": "object",
"properties": {
"function": {
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"slot": {
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"trapCode": {
"type": "integer",
"minimum": 0,
"maximum": 4294967295
}
},
"required": [
"function",
"slot",
"trapCode"
],
"additionalProperties": false
}
},
"required": [
"code",
"message",
"entry"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"code": {
"const": "loader_patch_failed"
},
"message": {
"type": "string"
},
"binding": {
"$ref": "#/$defs/bindingFailure"
}
},
"required": [
"code",
"message",
"binding"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"code": {
"const": "invalid_format"
},
"message": {
"type": "string"
}
},
"required": [
"code",
"message"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"code": {
"const": "unsupported_format"
},
"message": {
"type": "string"
}
},
"required": [
"code",
"message"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"code": {
"const": "image_load_failed"
},
"message": {
"type": "string"
}
},
"required": [
"code",
"message"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"code": {
"const": "entrypoint_not_found"
},
"message": {
"type": "string"
}
},
"required": [
"code",
"message"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"code": {
"const": "verification_failed"
},
"message": {
"type": "string"
}
},
"required": [
"code",
"message"
],
"additionalProperties": false
}
},
"required": [
"code",
"message"
],
"additionalProperties": false
]
}
},
"required": [
@@ -661,6 +847,521 @@
"shutdownTimeoutMs"
],
"additionalProperties": false
},
"resourceFailure": {
"type": "object",
"properties": {
"resource": {
"enum": [
"GuestBytes",
"HandleSlots",
"AuxiliaryBytes",
"TemporaryBytes",
"StringBytes",
"StringAllocations",
"IndividualStringBytes",
"CallDepth"
]
},
"reason": {
"enum": [
"Limit",
"SizeOverflow",
"AllocationFailed"
]
},
"requested": {
"type": "integer",
"minimum": 0
},
"limit": {
"type": "integer",
"minimum": 0
}
},
"required": [
"resource",
"reason",
"requested",
"limit"
],
"additionalProperties": false
},
"sourceSpan": {
"type": "object",
"properties": {
"file_id": {
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"start": {
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"end": {
"type": "integer",
"minimum": 0,
"maximum": 4294967295
}
},
"required": [
"file_id",
"start",
"end"
],
"additionalProperties": false
},
"loadFailure": {
"type": "object",
"properties": {
"code": {
"enum": [
"LOAD_INVALID_FORMAT",
"LOAD_UNSUPPORTED_FORMAT",
"LOAD_INVALID_REFERENCE",
"LOAD_INVALID_REGISTRY",
"LOAD_INVALID_CODE",
"LOAD_RESOURCE_LIMIT",
"LOAD_INVALID_ENTRYPOINT"
]
},
"reason": {
"enum": [
"Magic",
"Version",
"Endianness",
"Reserved",
"SectionKind",
"MissingSection",
"DuplicateSection",
"Overlap",
"Truncated",
"TrailingBytes",
"InvalidFlag",
"Utf8",
"Category",
"Builtin",
"TypeId",
"FunctionId",
"OwnerCategory",
"TraitCategory",
"DuplicateBuiltin",
"DuplicateArray",
"ArrayCycle",
"DuplicateImplementation",
"MethodCount",
"Signature",
"CodeRange",
"FrameSlots",
"ReturnSlots",
"Overflow",
"Limit",
"Allocation",
"ConstantTag",
"DebugRange",
"DuplicateSyscall",
"UnknownOpcode",
"LocalSlot",
"JumpTarget",
"InstructionBoundary",
"BooleanImmediate",
"ConstantIndex",
"NativeId",
"UnpatchedHostcall",
"StackUnderflow",
"StackOverflow",
"StackJoin",
"ReturnHeight",
"UnterminatedPath",
"UnknownClosureCallee",
"NotClosure",
"InvalidYield",
"TypeMismatch"
]
},
"section": {
"anyOf": [
{
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
{
"type": "null"
}
]
},
"record": {
"anyOf": [
{
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
{
"type": "null"
}
]
},
"member": {
"anyOf": [
{
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
{
"type": "null"
}
]
},
"referenced_id": {
"anyOf": [
{
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
{
"type": "null"
}
]
},
"function": {
"anyOf": [
{
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
{
"type": "null"
}
]
},
"pc": {
"anyOf": [
{
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
{
"type": "null"
}
]
},
"offset": {
"anyOf": [
{
"type": "integer",
"minimum": 0
},
{
"type": "null"
}
]
},
"id_domain": {
"enum": [
"Type",
"Function",
"Implementation",
null
]
},
"resource": {
"enum": [
"PbxBytes",
"CodeBytes",
"Types",
"Functions",
"Implementations",
"NestedRecords",
"NameBytes",
"RegistryBytes",
"TemporaryBytes",
"Work",
"ConstantEntries",
"ConstantStringBytes",
null
]
},
"requested": {
"anyOf": [
{
"type": "integer",
"minimum": 0
},
{
"type": "null"
}
]
},
"limit": {
"anyOf": [
{
"type": "integer",
"minimum": 0
},
{
"type": "null"
}
]
}
},
"required": [
"code",
"reason",
"section",
"record",
"member",
"referenced_id",
"function",
"pc",
"offset",
"id_domain",
"resource",
"requested",
"limit"
],
"additionalProperties": false
},
"bindingFailure": {
"oneOf": [
{
"type": "object",
"properties": {
"reason": {
"const": "unknown_syscall"
},
"module": {
"type": "string"
},
"name": {
"type": "string"
},
"version": {
"type": "integer",
"minimum": 0,
"maximum": 65535
}
},
"required": [
"reason",
"module",
"name",
"version"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"reason": {
"const": "missing_capability"
},
"module": {
"type": "string"
},
"name": {
"type": "string"
},
"version": {
"type": "integer",
"minimum": 0,
"maximum": 65535
},
"required": {
"type": "integer",
"minimum": 0
},
"provided": {
"type": "integer",
"minimum": 0
}
},
"required": [
"reason",
"module",
"name",
"version",
"required",
"provided"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"reason": {
"const": "abi_mismatch"
},
"module": {
"type": "string"
},
"name": {
"type": "string"
},
"version": {
"type": "integer",
"minimum": 0,
"maximum": 65535
},
"declared_arg_slots": {
"type": "integer",
"minimum": 0,
"maximum": 65535
},
"declared_ret_slots": {
"type": "integer",
"minimum": 0,
"maximum": 65535
},
"expected_arg_slots": {
"type": "integer",
"minimum": 0,
"maximum": 65535
},
"expected_ret_slots": {
"type": "integer",
"minimum": 0,
"maximum": 65535
}
},
"required": [
"reason",
"module",
"name",
"version",
"declared_arg_slots",
"declared_ret_slots",
"expected_arg_slots",
"expected_ret_slots"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"reason": {
"const": "hostcall_index_out_of_bounds"
},
"pc": {
"type": "integer",
"minimum": 0
},
"syscallIndex": {
"type": "integer",
"minimum": 0,
"maximum": 4294967295
},
"syscallsLength": {
"type": "integer",
"minimum": 0
}
},
"required": [
"reason",
"pc",
"syscallIndex",
"syscallsLength"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"reason": {
"const": "raw_syscall"
},
"pc": {
"type": "integer",
"minimum": 0
},
"syscallId": {
"type": "integer",
"minimum": 0,
"maximum": 4294967295
}
},
"required": [
"reason",
"pc",
"syscallId"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"reason": {
"const": "unused_syscall"
},
"module": {
"type": "string"
},
"name": {
"type": "string"
},
"version": {
"type": "integer",
"minimum": 0,
"maximum": 65535
},
"syscallIndex": {
"type": "integer",
"minimum": 0,
"maximum": 4294967295
}
},
"required": [
"reason",
"module",
"name",
"version",
"syscallIndex"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"reason": {
"const": "hostcall_remaining"
},
"pc": {
"type": "integer",
"minimum": 0
},
"syscallIndex": {
"type": "integer",
"minimum": 0,
"maximum": 4294967295
}
},
"required": [
"reason",
"pc",
"syscallIndex"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"reason": {
"const": "decode_failed"
}
},
"required": [
"reason"
],
"additionalProperties": false
}
]
}
}
}
@@ -0,0 +1,119 @@
---
id: LSN-0059
ticket: program-registry-type-and-function-metadata
title: Registry Boundaries and Owned Values
created: 2026-10-08
tags: [vm, bytecode, registry, ownership, planning]
---
## Context
DEC-0045, accepted from AGD-0061, established an image-owned Type/Function Registry,
typed signatures, PBX v1, compact stored values and bounded resource ownership.
PLN-0176 delivered the independent foundation and its sealed execution path. On
2026-10-08 the user corrected the plan's scope to its originating agenda and
closed that delivery. Coordinated production activation was explicitly received
as future-plan suggestions in AGD-0055. Closing this delivery does not mean the
old production loader or version-0 example generators were migrated.
The normative reference is [Program Registry and PBX v1](../../../docs/specs/runtime/02c-program-registry-and-pbx-v1.md).
The [permanent handoff](../../../docs/vm-arch/registry-producer-handoff.md) records
delivered APIs, producer oracles and pending integration ownership. This lesson
explains published mechanisms; it does not define callable/capture policy.
## Key Decisions and Published Patterns
### Identity, Execution Width and Stored Layout Have Different Jobs
A Registry TypeId identifies a semantic type within an image. Execution still
uses tagged Value slots; storage uses resolved size, alignment, defaults and
ownership maps. A vec2 occupies two Float execution slots and sixteen inline
array bytes. An array of Struct values holds generational references to objects.
Equal native carriers or names do not make semantic types equivalent.
This separation avoids scalar boxing per array element while preserving simple
stack roots. A stored Dynamic slot is larger because it preserves the semantic
tag and payload ownership.
### Publication Is an Ownership Boundary
ValidatedProgramImage::load decodes under bounded work/capacity budgets, resolves
metadata, binds native calls and performs structural/height/type-flow verification
before publishing a shared image. Sessions retain the same immutable Registry,
code, constants and debug owners. Rejected loads restore provisional ownership
counters while attempted work remains charged.
Conformance through that factory proves its behavior, but cannot prove that a
different production entry point already uses it. Keep activation distinct from
the provider API in handoff and validation evidence.
### Complete Groups Prevent Partial Type Checks
Typed CALL/RET/native entry validates ordered parameter/result groups, including
multi-slot values. A trait's receiver and ImplementationId are one group; a
Dynamic tag and payload are another. Validating only one carrier permits malformed
combinations to cross boundaries. Conservative verifier joins may produce Unknown;
runtime checks still validate complete groups before consuming operands or
publishing frames/results.
### String Sharing Requires Domain Ownership
Arc identity shares content, but an Arc alone does not explain which quota owns
it. Image constants and session-created strings have separate Weak ledgers.
Cloning within a domain preserves one allocation charge; equal independently
created content has independent ownership. Cross-session import copies and
accounts content in the destination domain.
Native ValueSnapshot owners retain provenance after the VM closes, while
serialization exports ordinary values. A String field and direct Dynamic field
can share one allocation; removing one storage owner keeps its charge alive until
the last owner disappears and reconciliation releases it. Content reservations
and temporary/result coexistence precede materialization.
### Dynamic Boxes Preserve Existing Receiver Identity
Single-slot Dynamic payloads remain direct. Present multi-slot values use an
immutable, exact-width Value box with Registry identity and TypeId. Copies and
repacking share its handle. Typed-null traits allocate no box. A box is an internal
category rather than a user object or collection receiver.
The real FRAME_SYNC test removes original receiver roots and retains the receiver
only through the operand-stack Dynamic pair and its trait box. Once unpack/POP
removes those roots, permitted GC invalidates both handles. Actual safepoint
execution proves more than constructing a box and checking its contents.
## Evidence and Its Limits
Independent literal PBX fixtures complement writer/reader roundtrips. The named
argument oracle evaluates y before x, records effect order 21, marshals x/y in
signature order and returns 1020. It checks runtime behavior without claiming an
external frontend implementation.
Baseline dd35942 passed 899 workspace tests with zero failures and nine ignored
tests; the two new ignored probes were explicitly run in release. Ownership,
quota rollback, stale handles, exact diagnostics and decoded conversion costs
have focused evidence. [Technical measurements](../../../docs/vm-arch/registry-layout-evidence.md)
record native representation, load high-water capacity and dense/sparse GC behavior.
These observations do not establish process RSS, game headroom or long-run stability.
## Pitfalls
Plan ownership was initially mixed: production migration depended on a callable
contract assigned to another agenda, yet remained a completion gate of the
Registry plan. Moving only the callable opcode step left that dependency in loader
activation, producer regeneration and final audits.
The correction preserves both facts: the foundation is delivered and integration
is pending with a named owner. It transfers exact targets and acceptance to
AGD-0055's future plan. It does not approve that agenda's proposal, weaken the
final PBX contract or label transferred code as executed. Other agendas retain
their own collection/string/stress/game obligations.
## Takeaways
- Keep each plan atomic to its originating agenda and identify integration ownership before execution.
- Distinguish validated publication APIs from activation of every production consumer.
- Treat semantic identity, execution carriers and compact storage as separate contracts.
- Preserve quota provenance for shared native owners and test release at the final owner.
- Use independent bytes and actual safepoints to substantiate boundary behavior.
- Close a user-corrected delivery with explicit handoff; future work belongs to its owner's plan.
@@ -3,7 +3,9 @@
Domain: VM program metadata, binary format, typed storage and resource boundaries
Function: normative
This chapter publishes DEC-0045 through PLN-0176. It 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.
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.
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).
The requirements below use MUST/MUST NOT semantics. The Registry owns type/function identity, storage shapes and signatures; other chapters retain authority over scheduling, collection operations, cartridge boot and host ABI behavior outside these requirements.
+5 -4
View File
@@ -9,8 +9,7 @@ Didactic companion: [`../learn/mental-model-gfx.md`](../runtime/learn/mental-mod
The **GFX** peripheral is responsible for generating images in PROMETEU.
`DEC-0030` defines the current logical render boundary. PROMETEU render
production is split from render implementation:
PROMETEU logical render production is separate from render implementation:
```text
domain buffers during logical frame
@@ -121,8 +120,10 @@ This guarantees:
## 4. Asynchronous Render Boundary
`DEC-0031` defines the asynchronous render boundary. The contract applies even
when the current implementation consumes submissions synchronously.
The asynchronous render boundary applies even when the current implementation
consumes submissions synchronously. [Render Workers Need a Closed Packet Contract](../../../discussion/lessons/DSC-0040-vm-render-parallel-execution-boundary/LSN-0048-render-workers-need-a-closed-packet-contract.md)
explains the packet and ownership model; [Render Workers Publish Frames, Hosts Present Them](../../../discussion/lessons/DSC-0042-real-render-worker-establishment/LSN-0049-render-worker-publication-boundary.md)
explains its worker/publication implementation.
### 4.1 Complete packet contract
@@ -7,9 +7,9 @@ Didactic companion: [`../learn/mental-model-observability-and-debugging.md`](../
## 1 Scope
This chapter defines the machine-visible diagnostics and profiling surface of PROMETEU after `DEC-0009`.
This chapter defines the machine-visible diagnostics and profiling surface of PROMETEU.
`DEC-0009` locks debug tooling and certification output as host-owned concerns. The runtime machine contract therefore exposes only bounded operational diagnostics and deterministic telemetry production, not a general-purpose guest-visible debug surface.
Debug tooling and certification output are host-owned concerns. The runtime machine contract therefore exposes only bounded operational diagnostics and deterministic telemetry production, not a general-purpose guest-visible debug surface. The rationale is explained in [Host-Owned Debug Boundaries and Cheap Machine Diagnostics](../../../discussion/lessons/DSC-0012-perf-runtime-introspection-syscalls/LSN-0034-host-owned-debug-boundaries.md).
It covers:
@@ -2,9 +2,11 @@
**Domain:** runtime host tooling. **Function:** normative.
This chapter implements Studio DSC-0068 / DEC-0060 baseline v1, runtime phase
of PLN-0139. The host owns this wire contract. It does not change guest ABI,
firmware, VM, frame/input semantics or the desktop DevTools protocol.
This chapter defines the v1 automation wire contract owned by the headless host.
It does not change guest ABI, firmware, VM, frame/input semantics or the desktop
DevTools protocol.
The observation model is explained in [Deterministic Observation Must Follow the Active Producer](../../../discussion/lessons/DSC-0050-headless-automation-host-hardening/LSN-0058-deterministic-observation-must-follow-the-active-producer.md).
## Process and transport
@@ -94,6 +96,19 @@ exact round-trippable string (including non-finite values). Faults expose kind,
pc, summary and structural trap code/opcode/message/source span or init-error code.
No client must parse a summary to distinguish trap, panic or initialization failure.
Resource traps include a nullable `trap.resource` object with `resource`, `reason`,
`requested` and `limit`; resource and reason are enumerated machine values.
`initError` is discriminated by `code`: `registry_load_failed` includes `load`,
`runtime_resource_limit` includes `resource`, `entrypoint_arguments_invalid`
includes `entry`, and `loader_patch_failed` includes `binding`. Other initialization
codes carry only their code and human message. `load.code` uses the stable
`LOAD_*` tag and retains typed reason, section/offset, record/member, ID domain,
referenced ID, function/PC and quota context, with null for unavailable fields.
Binding context preserves canonical native identity, version, capabilities or
declared/expected ABI counts as applicable. A load-relative PC remains nested
inside its diagnostic; initialization failure does not invent a runtime PC.
The published response schema rejects unknown fields and invalid contexts.
## Ordering, cancellation and lifecycle
Only one host operation is admitted at a time. Conflicting work, including state
+4 -2
View File
@@ -129,7 +129,7 @@ Even with `codec = NONE`, `GLYPH` still requires bank-specific decode from its s
#### 4.1.1 Metadata Normalization
Following `DEC-0004`, the `AssetEntry.metadata` field must be structured in segmented form to avoid ambiguity.
The `AssetEntry.metadata` field must be structured in segmented form to avoid ambiguity. [Typed Helpers for Asset Metadata](../../../discussion/lessons/DSC-0017-asset-metadata-normalization/LSN-0023-typed-asset-metadata-helpers.md) explains the typed parsing pattern for this structure.
Required effective metadata fields for `GLYPH` at the root level:
@@ -281,9 +281,11 @@ Rules:
- the visible contract MUST NOT expose byte-oriented bank occupancy as the canonical summary;
- canonical bank names are `GLYPH` and `SOUNDS`;
- detailed occupancy inspection remains host-owned and slot-based through slot references, not bank byte totals;
- public runtime specs MUST NOT treat `bank.slot_info` or JSON bank inspection payloads as the long-term guest ABI after `DEC-0009`;
- public runtime specs MUST NOT treat `bank.slot_info` or JSON bank inspection payloads as the long-term guest ABI;
- any residual byte accounting MAY exist internally, but it is not part of the visible bank telemetry contract.
The rationale for this boundary is explained in [Host-Owned Debug Boundaries and Cheap Machine Diagnostics](../../../discussion/lessons/DSC-0012-perf-runtime-introspection-syscalls/LSN-0034-host-owned-debug-boundaries.md).
## 6 Load Lifecycle
The runtime asset manager exposes a staged lifecycle:
@@ -15,7 +15,7 @@ It focuses on:
Operational policies such as capabilities, fault classes, determinism, GC interaction, budgeting, and blocking are split into a companion chapter.
Per `DEC-0009`, debug tooling and certification are host-owned concerns. This chapter therefore excludes general-purpose guest-visible debug syscalls from the canonical public ABI.
Debug tooling and certification are host-owned concerns. This chapter therefore excludes general-purpose guest-visible debug syscalls from the canonical public ABI. The rationale is explained in [Host-Owned Debug Boundaries and Cheap Machine Diagnostics](../../../discussion/lessons/DSC-0012-perf-runtime-introspection-syscalls/LSN-0034-host-owned-debug-boundaries.md).
## 1 Design Principles
@@ -246,7 +246,7 @@ ordering model.
### Bank diagnostics surface (`bank`, v1)
`DEC-0009` narrows the public bank contract:
The public bank contract is bounded:
- `bank.info(bank_type) -> (used_slots, total_slots)` is the only surviving public bank diagnostic shape in v1;
- `bank.info` exists only as a cheap deterministic operational summary aligned with the slot-first bank telemetry contract from [`15-asset-management.md`](15-asset-management.md);
@@ -256,10 +256,13 @@ ordering model.
### Render surfaces (`composer`, `gfx2d`, `gfxui`, v1)
`DEC-0030` splits logical render production from render implementation. Public
Logical render production is separate from render implementation. Public
render syscalls mutate app-mode-specific domain buffers. They do not directly
publish a framebuffer and do not call host presentation APIs.
[Render Workers Publish Frames, Hosts Present Them](../../../discussion/lessons/DSC-0042-real-render-worker-establishment/LSN-0049-render-worker-publication-boundary.md)
explains the ownership and publication model.
The canonical flow is:
```text
+1 -1
View File
@@ -9,7 +9,7 @@ It complements [`16-host-abi-and-syscalls.md`](16-host-abi-and-syscalls.md), whi
Unless a domain chapter explicitly narrows behavior further, this chapter is the transversal policy for all syscalls in v1.
Per `DEC-0009`, guest-visible syscalls must not exist merely for debug convenience or certification plumbing. Those concerns belong to host-owned tooling.
Guest-visible syscalls must not exist merely for debug convenience or certification plumbing. Those concerns belong to host-owned tooling, as explained in [Host-Owned Debug Boundaries and Cheap Machine Diagnostics](../../../discussion/lessons/DSC-0012-perf-runtime-introspection-syscalls/LSN-0034-host-owned-debug-boundaries.md).
## 1 Error Model: Faults vs Status Returns
+2 -3
View File
@@ -23,9 +23,8 @@ 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);
- agendas, proposals, and plans:
`discussion/workflow/agendas/`, `discussion/workflow/decisions/` and `discussion/workflow/plans/`.
[`../learn/README.md`](../runtime/learn/README.md) and
[published lessons](../../../discussion/lessons/).
## Organization Rules
+4 -2
View File
@@ -15,7 +15,7 @@ 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.
- Roadmaps, agendas, and PR proposals may discuss future changes, but they are not authoritative until this document is updated.
- 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.
Maintenance rule:
@@ -125,7 +125,7 @@ The verifier statically checks bytecode for structural safety and stack‑shape
4.2 Runtime vs Verifier Guarantees
- The verifier guarantees structural correctness and stack‑shape invariants. It does not perform full type checking of value contents; dynamic checks (e.g., numeric domain checks, polymorphic comparisons, concrete syscall argument validation) occur at runtime and may trap.
- 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.
- Capability gating for syscalls is enforced at load from cartridge capability flags and checked again at runtime by the VM/native interface.
@@ -187,3 +187,5 @@ The verifier statically checks bytecode for structural safety and stack‑shape
## 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.
`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.
+97
View File
@@ -0,0 +1,97 @@
# Registry layout, load and GC evidence
This report records bounded technical fixtures for Registry layout, loading and GC. The normative contract is [Program Registry and PBX v1](../specs/runtime/02c-program-registry-and-pbx-v1.md); producer obligations and publication status are in the [producer handoff](registry-producer-handoff.md). [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.
Measured on 2026-10-07: Darwin arm64, Rust 1.98.1 (`48a229cea`), host `aarch64-apple-darwin`, LLVM 22.1.8, optimized Cargo release profile. The code baseline is `c6fff08`; this report's commit also contains the load high-water instrumentation and measurement fixtures. Wall-clock values are single observations, not thresholds or statistically established throughput. No timing assertion is used.
## Reproduction
```sh
cargo test -p prometeu-bytecode --release --test registry_v1 reference_map_probe -- --ignored --nocapture
cargo test -p prometeu-vm --release --lib probe -- --ignored --nocapture --test-threads=1
cargo test -p prometeu-vm --release --lib decoded_trait_box_is_the_only_receiver_root_across_frame_sync_gc --quiet
cargo test -p prometeu-vm --lib ownership_tests --quiet
```
The first probe compares ownership-map traversal with a synthetic bitmap. The second executes complete sealed-image loading, typed-array allocation/access, object tracing and native-owner cleanup. Its tests run sequentially. Fixtures construct internal typed containers; guest collection allocation/read/write operations are outside the measured instruction surface. No new collection instruction or cost is inferred from native helper timings.
## Native representation and typed-array access
Native sizes/alignment in bytes on this target:
| Carrier or owner | Size | Alignment |
| --- | ---: | ---: |
| `Value` | 24 | 8 |
| `HeapRef` | 8 | 8 |
| `StringSlot` | 16 | 8 |
| `DynamicSlot` | 32 | 8 |
| Compact trait slot | 16 | 8 |
| `StoredObject` | 416 | 8 |
`Value` remains the execution carrier. Arrays use resolved storage directly. The fixture allocates 4,096 default-initialized elements per array in a fresh heap, checks the last element, then performs 100,000 checked `load_typed` reads with `black_box`. It does not allocate a result Vec per read. Reference/native arrays below contain their null defaults, so these access times do not measure live-handle validation or String cloning throughput.
| Element | Stride / alignment | Guest bytes | Auxiliary bytes | Allocation ns | 100,000 reads ns |
| --- | ---: | ---: | ---: | ---: | ---: |
| int32 | 4 / 4 | 16,800 | 60 | 45,709 | 2,439,084 |
| bool | 1 / 1 | 4,512 | 60 | 14,792 | 2,348,666 |
| vec2 | 16 / 8 | 65,952 | 60 | 18,167 | 2,220,125 |
| pixel | 24 / 8 | 98,720 | 60 | 17,208 | 2,469,125 |
| Struct reference | 8 / 8 | 33,184 | 60 | 21,833 | 1,990,667 |
| String | 16 / 8 | 65,952 | 60 | 15,042 | 2,069,584 |
| Trait | 16 / 8 | 65,952 | 60 | 13,500 | 2,019,667 |
| Dynamic | 32 / 8 | 131,488 | 60 | 17,875 | 2,330,000 |
Each case owns one handle. Guest bytes equal one actual `StoredObject` plus `count * stride`. Auxiliary bytes are the initial generational-table capacities, separate from element storage and Registry metadata. After marking the array it survives; after an unrooted sweep guest bytes return to zero, and dropping the heap releases retained auxiliary tables. Native header sizes are implementation details, not PBX fields or portable guest ABI promises.
## Complete load and scratch ownership
The sealed-image fixture contains one named bool type, one named zero-argument HALT function and 512 distinct 64-byte String constants; no debug records or native calls.
| Measurement | Value |
| --- | ---: |
| PBX bytes | 35,520 |
| Retained Registry bytes | 587 |
| Retained image payload accounting | 65,880 |
| Deterministic load work units | 204,641 |
| Peak admitted temporary bytes | 77,906 |
| Temporary bytes after publication | 0 |
| String content bytes / allocations | 32,768 / 512 |
| Complete load ns | 184,416 |
`LoadBudget::peak_usage` measures the highest successfully admitted reservation total in a budget's lifetime. Refunds and failed transactions retain that high-water mark; rejected charges do not increase it. The associated test proves rollback restores current ownership while preserving attempted work and peak history. These are accounted capacities and coexistence reservations, including conservative native owner sizing; they are not allocator telemetry or process RSS. Image payload, constant content and PBX admission are different counters, so this table must not be summed into a physical-memory total. A single fixture does not establish worst-case load work or peak scratch at the 64 MiB PBX ceiling.
## Ownership maps and actual object GC
The map-only fixture has 4,096 eight-byte fields, with a reference every `period` fields. It traverses the resolved ownership list and a synthetic bitmap 10,000 times and checks equal offsets/checksums. Its Registry has only the three types needed for that comparison.
| Period | Mapped entries | Registry bytes | List / bitmap bytes | Resolve ns | List traversal ns | Bitmap traversal ns |
| --- | ---: | ---: | ---: | ---: | ---: | ---: |
| 1 | 4,096 | 262,816 | 65,536 / 512 | 271,709 | 8,048,708 | 62,797,875 |
| 16 | 256 | 201,376 | 4,096 / 512 | 121,083 | 819,584 | 4,254,000 |
| 256 | 16 | 197,536 | 256 / 512 | 30,959 | 89,458 | 442,791 |
The actual GC fixture extends the storage test Registry with a 4,096-field Struct. Every mapped reference aliases the same live child; an unrelated child is unrooted. The one holder root retains exactly two objects after mark/sweep. It repeats 1,000 collections, verifies that the unrelated handle is invalid and releases the temporary mark worklist on every collection.
| Period | Mapped entries | Live guest bytes | Retained auxiliary bytes | Resolve work | Resolve peak scratch | 1,000 GC rounds ns |
| --- | ---: | ---: | ---: | ---: | ---: | ---: |
| 1 | 4,096 | 33,600 | 180 | 16,765 | 312 | 15,308,125 |
| 16 | 256 | 33,600 | 180 | 16,765 | 312 | 1,039,625 |
| 256 | 16 | 33,600 | 180 | 16,765 | 312 | 138,916 |
Mapped entries are edges, not distinct worklist roots. Repeated aliases enqueue the child once. Retained auxiliary capacity includes the swept object's reusable handle slot. Resolve scratch here measures direct Registry resolution, not complete PBX decoding. The timing shows the expected dependence on mapped edges for these fixtures; it does not establish pause times for a broad object graph or justify changing the accepted map representation.
## Dynamic conversion and native ownership
A vec2 pack creates one immutable box with 464 guest bytes: the 416-byte structural owner plus two 24-byte Values. The observed pack took 1,000 ns; 100,000 exact vec2 unpacks took 2,816,583 ns. Storing the Dynamic pair in a typed array, marking that array and sweeping retains the box; removing the root releases its guest charge. Separate conformance tests prove repeated Dynamic copies/repacking preserve the box handle, typed-null traits allocate no box and malformed category/type/width/handle combinations fail.
Decoded guest operations have independently asserted attempt costs: Dynamic pack/unpack/query = 8/4/3, reference exact/implements/cast = 4, reference-to-trait = 5. Each charges once on success or trap. Native timings above do not redefine those costs.
The decoded trait-box test removes the original global receiver owners, then reaches `FRAME_SYNC` through the sealed image. GC retains the box and receiver solely through the operand-stack Dynamic pair. After unpack and two POPs, the next permitted GC invalidates both handles and retains the entry coroutine. This proves the real interpreter/safepoint path as well as the internal container path.
The native fixture stores one session-imported 13-byte String in both a String field and a direct Dynamic field: two storage owners, one content allocation and one charge. Rooted collection retains it; unrooted collection drops both owners and ledger reconciliation releases content/allocation charges. The focused ownership test additionally removes the String field while the Dynamic alias remains, checks Arc identity and proves only the final owner permits release. Image constants, cross-session imports and retained native snapshots have separate integration tests.
## Publication boundary
The sealed v1 image, bounded verifier, typed direct calls, Dynamic/reference execution, metered native strings and structured host diagnostics have executable evidence. Production `VirtualMachine::initialize` still uses the old loader, and existing generators still emit version 0. Their coordinated migration must preserve existing closures and requires a typed callable contract; the producer handoff records pending implementation targets and validation requirements.
These measurements cover bounded layout/load/access/ownership/GC behavior. Representative-game capacity/headroom and coordinated long-run stress require separate workloads and evidence. No external compiler implementation, cross-host stress acceptance, regenerated production PBX smoke or final production activation is claimed by this report.
+145
View File
@@ -0,0 +1,145 @@
# Registry v1 producer and consumer handoff
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).
## Publication state
The bounded writer/owned decoder, sealed `ValidatedProgramImage::load`, shared
session factory, typed direct-call/return boundaries, Dynamic/reference execution,
fixed input catalogue and string accounting have executable tests. The production
`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.
### 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. Guest collection
operations, new strings/bytes/save APIs, coordinated stress and representative-game
headroom each require their own technical contract or validation workload.
The external Studio handoff targets are the build-pipeline
`backend/bytecode/BytecodeModule.java` and `backend/irvm/IRVMIntrinsicRegistry.java`,
compiler-core `source/tables/IntrinsicTableReader.java`, PBS
`lowering/PbsExecutableBodyLowerer.java`, `lowering/PbsExecutableCallsiteEmitter.java`
and `semantics/PbsBuiltinLayoutResolver.java`, with their producer tests. This
repository publishes requirements and oracles; those modules have not been edited.
## Exact producer obligations
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 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.
TypeId, FunctionId and ImplementationId are independent image-local table indices;
zero is valid. BuiltinIds are imports, not local TypeIds. Function records contain
optional name, ordered named parameters, ordered result TypeIds, code offset/length,
extra local slots and maximum temporary slots. Names are independent of debug.
Widths are derived from TypeIds; serialize no parameter/result width caches.
`max_stack_slots = 0` is a literal zero limit. Boot authority remains FunctionId 0.
The nine BuiltinIds are color `0x0001`, vec2 `0x0002`, pixel `0x0003`, Int32 `0x0010`,
Int64 `0x0011`, Float `0x0012`, Bool `0x0013`, String `0x0014`, Dynamic `0x0015`.
Removed input BuiltinIds `0x0100`–`0x0102` have no aliases. Struct/Trait identity is
nominal; Array identity is its exact element TypeId. Do not deduplicate declarations
by name or shape, or introduce array covariance. Preserve complete multi-slot groups
and exact parameter/result order; use explicit accepted conversions at boundaries.
HOSTCALL `0x0071` carries a syscall-declaration index. Declare canonical native
module/name/version and exact ABI counts; every declaration must be used. Loading
binds it to SYSCALL after capability/ABI validation. Raw SYSCALL in producer PBX,
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:
| 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 |
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
bytes are `42 00 00 00 00 00 42 00 01 00 00 00 51 00`: GET_LOCAL 0,
GET_LOCAL 1, RET. Both signature widths resolve to 2. Complement these oracles with
roundtrips; do not derive every expected byte from the producer under test.
## Named arguments and observable evaluation order
For a frontend whose expressions evaluate left to right, use this source-level
pseudocode oracle; it is not a claim that PBS syntax has already been implemented:
```text
combine(x: Int32, y: Int32) -> Int32 = x * 100 + y
combine(y: effect("Y", 20), x: effect("X", 10))
```
Expected effect order is **Y, X**. Evaluate `y` first into a temporary, then `x` into
another temporary. Load the temporaries in signature order **x=10, y=20** before
CALL. The result is **1020**. Reordering evaluation into parameter order would
produce the wrong effect trace; pushing source order would produce **2010**.
Parameter names resolve positions in the frontend; runtime CALL remains positional.
An absent name prevents name-only resolution from that metadata, while positional
execution remains valid. Names do not adapt trait method compatibility.
## Endpoint-free input lowering
The [complete 54-entry table](../specs/runtime/02c-program-registry-and-pbx-v1.md#input)
defines every accepted name/ID/result. Queries take zero guest arguments, read the
logical-frame snapshot and cost one intrinsic cycle. States return Bool;
hold/x/y return Int64. For example, `input.pad.a.down` lowers directly to
`72 00 12 21 00 00`; `input.touch.x` uses ID `0x2134`. Do not produce an endpoint
value, load it into a local or pass a selector. Removed intrinsic IDs are
`0x2000`/`0x2001`, `0x2010`–`0x201B`, `0x2020`–`0x2022`, `0x2030`–`0x2033`.
A removed/unknown ID differs from a known query whose platform is unavailable;
the latter raises TRAP_UNAVAILABLE, not a fabricated false/zero.
## Diagnostics, ownership and consumer status
Load failures preserve stable LOAD_* tags, typed reasons and available
section/offset/record/member/ID/function/PC/resource fields. Native binding preserves
its specific identity/capability/ABI context. Runtime resource faults preserve
resource/reason/requested/limit plus opcode/PC/source span. Headless and desktop
share initialization serialization; the strict
`devtools/headless-protocol/response.schema.json` is the machine shape. Never parse
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 |
| 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 |
Image constant allocations are shared between sessions without a session-content
charge. New/imported runtime allocations belong to their session; equal text does
not merge independent allocations. Native owners retain provenance alongside their
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.
@@ -2,7 +2,7 @@
"version": 1,
"domains": {
"system/os": {
"baseline_percent": 75,
"baseline_percent": 77.24,
"paths": [
"crates/console/prometeu-system/src/os/",
"crates/console/prometeu-system/src/services/process",
@@ -10,26 +10,26 @@
]
},
"system/runtime": {
"baseline_percent": 70,
"baseline_percent": 76.5,
"paths": [
"crates/console/prometeu-system/src/services/vm_runtime"
]
},
"system/fs": {
"baseline_percent": 77,
"baseline_percent": 76.08,
"paths": [
"crates/console/prometeu-system/src/services/fs/",
"crates/console/prometeu-system/src/services/memcard.rs"
]
},
"system/programs": {
"baseline_percent": 55,
"baseline_percent": 93.05,
"paths": [
"crates/console/prometeu-system/src/programs/"
]
},
"asset/bank": {
"baseline_percent": 86,
"baseline_percent": 86.76,
"paths": [
"crates/console/prometeu-hal/src/asset",
"crates/console/prometeu-hal/src/asset.rs",
@@ -40,19 +40,19 @@
]
},
"firmware": {
"baseline_percent": 80,
"baseline_percent": 83.2,
"paths": [
"crates/console/prometeu-firmware/src/"
]
},
"host-dependent": {
"baseline_percent": 35,
"baseline_percent": 40.05,
"paths": [
"crates/host/prometeu-host-desktop-winit/src/"
]
},
"host/headless": {
"baseline_percent": 80,
"baseline_percent": 83.39,
"paths": [
"crates/host/prometeu-host-headless/src/"
]