feat(vm): add resource diagnostics and macOS stability qualification
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good

This commit is contained in:
2026-10-14 08:26:07 +01:00
parent 6c2a07e579
commit 3899b7f12c
21 changed files with 1502 additions and 33 deletions
+7
View File
@@ -4,6 +4,13 @@ version = "0.1.0"
edition = "2024"
license.workspace = true
[features]
resource-diagnostics = []
[[example]]
name = "resource_qualification"
required-features = ["resource-diagnostics"]
[dependencies]
prometeu-bytecode = { path = "../prometeu-bytecode" }
prometeu-hal = { path = "../prometeu-hal" }
@@ -0,0 +1,113 @@
//! Bounded, opt-in macOS qualification workload. See --help.
#[path = "../tests/support/qualification.rs"]
mod qualification;
use prometeu_vm::resource_diagnostics::ResourceSnapshot;
use qualification::Workload;
use std::time::{Duration, Instant};
fn report(name: &str, frames: u64, hash: u64, s: &ResourceSnapshot) {
println!(
"checkpoint name={name} frames={frames} digest={hash:016x} cycles={} live={} free={} retired={} strings={} depth={} peak_depth={} used={:?} peaks={:?} limits={:?} reservation_refusals={:?} gc={} reclaimed={} gc_p50_upper_ns={} gc_p95_upper_ns={} gc_p99_upper_ns={} gc_max_ns={} mark_max_ns={} sweep_max_ns={} reconcile_max_ns={}",
s.cycles,
s.live_objects,
s.free_handles,
s.retired_handles,
s.tracked_strings,
s.call_depth,
s.peak_call_depth,
s.budget.used,
s.budget.peaks,
s.budget.limits,
s.budget.refusals,
s.gc.collections,
s.gc.reclaimed,
s.gc.total.percentile_upper_ns(50),
s.gc.total.percentile_upper_ns(95),
s.gc.total.percentile_upper_ns(99),
s.gc.total.max_ns,
s.gc.mark.max_ns,
s.gc.sweep.max_ns,
s.gc.string_reconciliation.max_ns
);
}
fn main() {
let args: Vec<_> = std::env::args().collect();
if args.len() != 3 || !matches!(args[1].as_str(), "--frames" | "--seconds") {
eprintln!(
"usage: resource_qualification --frames N | --seconds N\nRuns all three stationary families with lockstep replay; --seconds counts active batches only. Seed=73. Checkpoints every 10000 frames, fixed-size memory. Does not certify desktop or other hosts."
);
std::process::exit(2);
}
let amount: u64 = args[2].parse().expect("positive integer duration/frame count");
assert!(amount > 0);
let timed = args[1] == "--seconds";
println!(
"start os={} arch={} debug={} seed=73 mode={} amount={} pid={}",
std::env::consts::OS,
std::env::consts::ARCH,
cfg!(debug_assertions),
args[1],
amount,
std::process::id()
);
let mut workloads: Vec<_> =
qualification::NAMES.iter().map(|&name| Workload::new(name)).collect();
let mut replays: Vec<_> =
qualification::NAMES.iter().map(|&name| Workload::new(name)).collect();
let started = Instant::now();
let mut active = Duration::ZERO;
let mut excluded = Duration::ZERO;
while if timed { active.as_secs() < amount } else { workloads[0].frames < amount } {
let batch_started = Instant::now();
for (w, replay) in workloads.iter_mut().zip(&mut replays) {
let batch = if timed { 64 } else { 64.min(amount - w.frames) };
for _ in 0..batch {
w.frame();
replay.frame();
assert_eq!(w.digest, replay.digest, "{} replay at {}", w.name, w.frames);
if w.frames % 10_000 == 0 {
w.check_stationary();
replay.check_stationary();
assert_eq!(
w.vm.resource_snapshot().budget,
replay.vm.resource_snapshot().budget
);
report(w.name, w.frames, w.digest, &w.vm.resource_snapshot());
}
}
}
let elapsed = batch_started.elapsed();
// Conservatively exclude any long interval, including sleep/descheduling.
// This can extend the run; it never credits suspended time as active work.
if elapsed <= Duration::from_secs(2) {
active += elapsed;
} else {
excluded += elapsed;
}
}
println!(
"load_complete active_seconds={:.3} wall_seconds={:.3} excluded_seconds={:.3}",
active.as_secs_f64(),
started.elapsed().as_secs_f64(),
excluded.as_secs_f64()
);
for (w, replay) in workloads.into_iter().zip(replays) {
let name = w.name;
let frames = w.frames;
let expected = (w.digest, w.vm.resource_snapshot().cycles);
report(name, frames, w.digest, &w.vm.resource_snapshot());
w.finish();
assert_eq!(
(replay.digest, replay.vm.resource_snapshot().cycles),
expected,
"{name} replay"
);
replay.finish();
println!(
"replay_pass name={name} frames={frames} digest={:016x} cycles={} disposed_usage=zero",
expected.0, expected.1
);
}
println!("qualification_pass scope=vm_workloads_only");
}
+5
View File
@@ -427,6 +427,11 @@ impl Heap {
pub fn allocation_count(&self) -> u64 {
self.allocation_count.load(Ordering::Relaxed)
}
#[cfg(feature = "resource-diagnostics")]
pub(crate) fn diagnostic_handles(&self) -> (usize, usize) {
(self.free_list.len(), self.objects.len() - self.free_list.len() - self.len())
}
}
// Internal consumer seam for PLN-0176 step 18 / AGD-0054. Executable image
+2
View File
@@ -16,6 +16,8 @@ mod local_addressing;
mod heap;
mod object;
pub mod resource_budget;
#[cfg(feature = "resource-diagnostics")]
pub mod resource_diagnostics;
mod roots;
// Bounded Registry preflight is consumed by the upcoming v1 image loader.
mod program_image;
@@ -260,6 +260,28 @@ fn constant_strings_share_image_domain_across_sessions_and_native_snapshots() {
assert_eq!(text.as_ref(), "shared");
}
#[test]
fn final_session_and_snapshot_drop_release_image_and_constant_domain() {
let bytes = fixture(&[1, 0], 0, &[K::String("shared".into())], None, &[]);
let image = ValidatedProgramImage::load(&bytes, &mut budget(), caps::NONE).unwrap();
let image_weak = Arc::downgrade(&image);
let registry_weak = Arc::downgrade(&image.registry);
let strings_weak = Arc::downgrade(&image.strings);
let lease = image.lease_constant(0).unwrap();
let first = crate::VirtualMachine::from_image(image.clone(), Default::default());
let second = crate::VirtualMachine::from_image(image.clone(), Default::default());
drop(image);
drop(first);
assert!(image_weak.upgrade().is_some());
drop(second);
assert!(image_weak.upgrade().is_none());
assert!(registry_weak.upgrade().is_none());
assert_eq!(lease.retained_content(), (6, 1));
assert!(strings_weak.upgrade().is_some());
drop(lease);
assert!(strings_weak.upgrade().is_none());
}
#[test]
#[ignore = "explicit release measurement; not a timing assertion"]
fn sealed_image_load_probe() {
@@ -42,6 +42,10 @@ impl RuntimeLimits {
struct State {
limits: RuntimeLimits,
used: [u64; COUNT],
#[cfg(feature = "resource-diagnostics")]
peaks: [u64; COUNT],
#[cfg(feature = "resource-diagnostics")]
refusals: [u64; COUNT],
}
#[derive(Debug, Clone)]
pub struct RuntimeBudget(Arc<Mutex<State>>);
@@ -52,7 +56,14 @@ impl Default for RuntimeBudget {
}
impl RuntimeBudget {
pub fn new(limits: RuntimeLimits) -> Self {
Self(Arc::new(Mutex::new(State { limits, used: [0; COUNT] })))
Self(Arc::new(Mutex::new(State {
limits,
used: [0; COUNT],
#[cfg(feature = "resource-diagnostics")]
peaks: [0; COUNT],
#[cfg(feature = "resource-diagnostics")]
refusals: [0; COUNT],
})))
}
fn state(&self) -> MutexGuard<'_, State> {
self.0.lock().unwrap_or_else(std::sync::PoisonError::into_inner)
@@ -73,8 +84,13 @@ impl RuntimeBudget {
pub fn check(&self, resource: RuntimeResource, requested: u64) -> Result<(), ResourceFailure> {
let limit = self.limit(resource);
if requested > limit {
Err(ResourceFailure { resource, reason: ResourceReason::Limit, requested, limit })
Err(self.failure(resource, ResourceReason::Limit, requested))
} else {
#[cfg(feature = "resource-diagnostics")]
{
let mut state = self.state();
state.peaks[resource as usize] = state.peaks[resource as usize].max(requested);
}
Ok(())
}
}
@@ -84,6 +100,11 @@ impl RuntimeBudget {
reason: ResourceReason,
requested: u64,
) -> ResourceFailure {
#[cfg(feature = "resource-diagnostics")]
{
let mut state = self.state();
state.refusals[resource as usize] += 1;
}
ResourceFailure { resource, reason, requested, limit: self.limit(resource) }
}
pub fn bytes<T>(
@@ -104,13 +125,23 @@ impl RuntimeBudget {
let mut state = self.state();
let current = state.used[resource as usize];
let limit = state.limits.get(resource);
let requested = current.checked_add(amount).ok_or(ResourceFailure {
resource,
reason: ResourceReason::SizeOverflow,
requested: u64::MAX,
limit,
})?;
let Some(requested) = current.checked_add(amount) else {
#[cfg(feature = "resource-diagnostics")]
{
state.refusals[resource as usize] += 1;
}
return Err(ResourceFailure {
resource,
reason: ResourceReason::SizeOverflow,
requested: u64::MAX,
limit,
});
};
if requested > limit {
#[cfg(feature = "resource-diagnostics")]
{
state.refusals[resource as usize] += 1;
}
return Err(ResourceFailure {
resource,
reason: ResourceReason::Limit,
@@ -119,11 +150,27 @@ impl RuntimeBudget {
});
}
state.used[resource as usize] = requested;
#[cfg(feature = "resource-diagnostics")]
{
state.peaks[resource as usize] = state.peaks[resource as usize].max(requested);
}
Ok(Reservation { budget: self.clone(), resource, amount })
}
pub(crate) fn empty_charge(&self, resource: RuntimeResource) -> Reservation {
Reservation { budget: self.clone(), resource, amount: 0 }
}
/// Engineering-only counters. Holding the budget does not retain guest owners.
#[cfg(feature = "resource-diagnostics")]
pub fn diagnostic_snapshot(&self) -> crate::resource_diagnostics::BudgetSnapshot {
let state = self.state();
crate::resource_diagnostics::BudgetSnapshot {
used: state.used,
peaks: state.peaks,
refusals: state.refusals,
limits: state.limits.0,
}
}
}
/// Unique accounting ownership; moving this token never charges a second time.
@@ -0,0 +1,89 @@
//! Opt-in engineering observations, never a guest ABI or a source of GC roots.
//! Timing distributions are bounded logarithmic histograms in nanoseconds.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct BudgetSnapshot {
/// RuntimeResource discriminant order; depth/individual string size are checked,
/// not reserved, so their current usage remains zero and their peak records checks.
pub used: [u64; 8],
pub peaks: [u64; 8],
/// Includes refused speculative capacity growth that may fall back to exact growth.
pub refusals: [u64; 8],
pub limits: [u64; 8],
}
#[derive(Debug, Clone)]
pub struct DurationHistogram {
buckets: [u64; 64],
pub count: u64,
pub max_ns: u64,
}
impl Default for DurationHistogram {
fn default() -> Self {
Self { buckets: [0; 64], count: 0, max_ns: 0 }
}
}
impl DurationHistogram {
pub(crate) fn record(&mut self, elapsed: std::time::Duration) {
let ns = elapsed.as_nanos().min(u64::MAX as u128) as u64;
let bucket = (63 - ns.max(1).leading_zeros()) as usize;
self.buckets[bucket] += 1;
self.count += 1;
self.max_ns = self.max_ns.max(ns);
}
/// Inclusive upper bound for the percentile's bucket, capped by observed max.
pub fn percentile_upper_ns(&self, percentile: u64) -> u64 {
assert!((1..=100).contains(&percentile));
if self.count == 0 {
return 0;
}
let rank = (self.count as u128 * percentile as u128).div_ceil(100);
let mut seen = 0u128;
for (i, &count) in self.buckets.iter().enumerate() {
seen += count as u128;
if seen >= rank {
return (u64::MAX >> (63 - i)).min(self.max_ns);
}
}
self.max_ns
}
}
#[derive(Debug, Default, Clone)]
pub struct GcDiagnostics {
pub collections: u64,
pub reclaimed: u64,
pub mark: DurationHistogram,
pub sweep: DurationHistogram,
pub total: DurationHistogram,
pub string_reconciliation: DurationHistogram,
}
#[derive(Debug, Clone)]
pub struct ResourceSnapshot {
pub budget: BudgetSnapshot,
pub live_objects: usize,
pub free_handles: usize,
pub retired_handles: usize,
pub tracked_strings: usize,
pub call_depth: usize,
pub peak_call_depth: usize,
pub cycles: u64,
pub gc: GcDiagnostics,
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn bounded_histogram_reports_upper_bounds_and_exact_max() {
let mut h = DurationHistogram::default();
assert_eq!(h.percentile_upper_ns(99), 0);
for ns in 0..100 {
h.record(std::time::Duration::from_nanos(ns));
}
assert_eq!(h.count, 100);
assert_eq!(h.percentile_upper_ns(50), 63);
assert_eq!(h.percentile_upper_ns(95), 99);
assert_eq!(h.max_ns, 99);
}
}
@@ -129,6 +129,10 @@ pub struct VirtualMachine {
/// Syscalls are capability-gated using `prometeu_hal::syscalls::SyscallMeta::caps`.
capabilities: prometeu_hal::syscalls::CapFlags,
budget: RuntimeBudget,
#[cfg(feature = "resource-diagnostics")]
gc_diagnostics: crate::resource_diagnostics::GcDiagnostics,
#[cfg(feature = "resource-diagnostics")]
peak_call_depth: usize,
}
impl Default for VirtualMachine {
@@ -138,6 +142,26 @@ impl Default for VirtualMachine {
}
impl VirtualMachine {
#[cfg(feature = "resource-diagnostics")]
pub fn resource_observer(&self) -> RuntimeBudget {
self.budget.clone()
}
#[cfg(feature = "resource-diagnostics")]
pub fn resource_snapshot(&self) -> crate::resource_diagnostics::ResourceSnapshot {
let (free_handles, retired_handles) = self.heap.diagnostic_handles();
crate::resource_diagnostics::ResourceSnapshot {
budget: self.budget.diagnostic_snapshot(),
live_objects: self.heap.len(),
free_handles,
retired_handles,
tracked_strings: self.strings.as_ref().map_or(0, |s| s.tracked_allocations()),
call_depth: self.call_stack.len(),
peak_call_depth: self.peak_call_depth.max(self.call_stack.len()),
cycles: self.cycles,
gc: self.gc_diagnostics.clone(),
}
}
/// Returns the current program counter.
pub fn pc(&self) -> usize {
self.pc
@@ -248,6 +272,10 @@ impl VirtualMachine {
last_gc_live_count: 0,
capabilities: NONE,
budget,
#[cfg(feature = "resource-diagnostics")]
gc_diagnostics: Default::default(),
#[cfg(feature = "resource-diagnostics")]
peak_call_depth: 0,
}
}
@@ -5,6 +5,8 @@ impl VirtualMachine {
if self.gc_alloc_threshold > 0
&& self.heap.len().saturating_sub(self.last_gc_live_count) >= self.gc_alloc_threshold
{
#[cfg(feature = "resource-diagnostics")]
let (started, before) = (std::time::Instant::now(), self.heap.len());
let roots = self
.operand_stack
.iter()
@@ -12,11 +14,27 @@ impl VirtualMachine {
.filter_map(crate::roots::value_heap_ref)
.chain(self.call_stack.iter().filter_map(|frame| frame.closure));
self.heap.mark_session_roots(roots)?;
#[cfg(feature = "resource-diagnostics")]
let sweep_started = {
self.gc_diagnostics.mark.record(started.elapsed());
std::time::Instant::now()
};
self.heap.sweep();
self.last_gc_live_count = self.heap.len();
#[cfg(feature = "resource-diagnostics")]
{
self.gc_diagnostics.collections += 1;
self.gc_diagnostics.reclaimed += (before - self.last_gc_live_count) as u64;
self.gc_diagnostics.sweep.record(sweep_started.elapsed());
self.gc_diagnostics.total.record(started.elapsed());
}
}
if let Some(strings) = &self.strings {
#[cfg(feature = "resource-diagnostics")]
let started = std::time::Instant::now();
strings.reconcile();
#[cfg(feature = "resource-diagnostics")]
self.gc_diagnostics.string_reconciliation.record(started.elapsed());
}
Ok(())
}
@@ -121,7 +121,16 @@ impl VirtualMachine {
}
let had_call = self.lifecycle.is_some();
let before = self.cycles;
#[cfg(feature = "resource-diagnostics")]
{
// Include an entry/hook whose first instruction immediately returns.
self.peak_call_depth = self.peak_call_depth.max(self.call_stack.len());
}
let result = self.step_inner(native, ctx);
#[cfg(feature = "resource-diagnostics")]
{
self.peak_call_depth = self.peak_call_depth.max(self.call_stack.len());
}
if !had_call && self.lifecycle.is_some() && result.is_ok() {
return Err(LogicalFrameEndingReason::BudgetExhausted);
}
@@ -0,0 +1,116 @@
#![cfg(feature = "resource-diagnostics")]
#[allow(dead_code)]
#[path = "support/callables.rs"]
mod callables;
#[path = "support/qualification.rs"]
mod qualification;
use prometeu_bytecode::{Value, model::ConstantPoolEntry};
use prometeu_vm::{
LogicalFrameEndingReason, VirtualMachine,
resource_budget::{RuntimeLimits, RuntimeResource as Q},
};
#[test]
fn depth_diagnostics_include_an_entry_that_returns_immediately() {
let mut vm = callables::vm(&[("RET", callables::sig(&[], &[]), vec![])]);
assert_eq!(callables::run(&mut vm, 100).reason, LogicalFrameEndingReason::EndOfRom);
let snapshot = vm.resource_snapshot();
assert_eq!(snapshot.call_depth, 0);
assert_eq!(snapshot.peak_call_depth, 1);
}
#[test]
fn stationary_workloads_repeat_cycles_and_release_all_session_reservations() {
for name in qualification::NAMES {
let mut first = qualification::Workload::new(name);
let mut second = qualification::Workload::new(name);
for _ in 0..32 {
first.frame();
second.frame();
}
first.check_stationary();
second.check_stationary();
assert_eq!(first.digest, second.digest);
assert_eq!(first.vm.resource_snapshot().budget, second.vm.resource_snapshot().budget);
assert_eq!(first.vm.resource_snapshot().cycles, second.vm.resource_snapshot().cycles);
first.finish();
second.finish();
}
}
#[test]
fn no_sync_loop_returns_each_slice_without_gc_frames_or_allocation() {
let mut vm = callables::vm(&[("JMP 0", callables::sig(&[], &[]), vec![])]);
let before = vm.resource_snapshot();
for _ in 0..1_000 {
let r = callables::run(&mut vm, 100);
assert_eq!(r.reason, LogicalFrameEndingReason::BudgetExhausted);
assert!(r.steps_executed > 0);
assert_eq!(vm.pc(), 0);
}
let after = vm.resource_snapshot();
assert_eq!(after.budget.used, before.budget.used);
assert_eq!(after.gc.collections, 0);
assert_eq!(after.call_depth, 1);
vm.insert_breakpoint(0);
assert_eq!(callables::run(&mut vm, 100).reason, LogicalFrameEndingReason::Breakpoint);
let observer = vm.resource_observer();
drop(vm);
assert_eq!(observer.diagnostic_snapshot().used, [0; 8]);
}
#[test]
fn host_string_snapshot_keeps_its_domain_alive_then_final_drop_refunds_it() {
let image = callables::image_constants(
&[("PUSH_CONST 0\nPUSH_CONST 1\nADD\nRET", callables::sig(&[], &[3]), vec![])],
vec![],
&[ConstantPoolEntry::String("abc".into()), ConstantPoolEntry::String("def".into())],
)
.unwrap();
let mut vm = VirtualMachine::from_image(image, Default::default());
vm.prepare_boot_call().unwrap();
assert_eq!(callables::run(&mut vm, 1000).reason, LogicalFrameEndingReason::EndOfRom);
let snapshot = vm.operand_stack_top(1);
assert_eq!(&*snapshot, &[Value::String("abcdef".into())]);
let observer = vm.resource_observer();
drop(vm);
assert_eq!(observer.used(Q::StringBytes), 6);
assert_eq!(observer.used(Q::StringAllocations), 1);
drop(snapshot);
assert_eq!(observer.diagnostic_snapshot().used, [0; 8]);
}
#[test]
fn refused_allocation_keeps_operands_and_charges_attempt_without_rescue_gc() {
let image = callables::image(
&[
("PUSH_I32 73\nMAKE_CLOSURE fn=1,type=4\nPOP\nRET", callables::sig(&[], &[]), vec![]),
(
"GET_CAPTURE 0\nRET",
callables::sig(&[], &[0]),
vec![prometeu_bytecode::registry::TypeId(0)],
),
],
vec![],
)
.unwrap();
let mut vm = VirtualMachine::from_image(
image,
RuntimeLimits::default().lowered(Q::GuestBytes, 0).unwrap(),
);
vm.prepare_boot_call().unwrap();
let before = vm.resource_snapshot();
let result = callables::run(&mut vm, 1000);
let LogicalFrameEndingReason::Trap(trap) = result.reason else { panic!("quota must trap") };
assert_eq!(trap.code, prometeu_bytecode::TRAP_RESOURCE_LIMIT);
assert_eq!(&*vm.operand_stack_top(1), &[Value::Int32(73)]);
let after = vm.resource_snapshot();
assert!(after.cycles > before.cycles);
assert_eq!(after.gc.collections, 0);
assert_eq!(after.live_objects, 0);
assert_eq!(after.budget.used[0], 0);
assert!(after.budget.refusals[0] > 0);
let observer = vm.resource_observer();
drop(vm);
assert_eq!(observer.diagnostic_snapshot().used, [0; 8]);
}
@@ -0,0 +1,204 @@
use prometeu_bytecode::{
Value, assemble, load_limits::LoadBudget, registry::*, registry_codec::PbxModule,
};
use prometeu_hal::{HostContext, HostReturn, NativeInterface};
use prometeu_vm::{LogicalFrameEndingReason, ValidatedProgramImage, VirtualMachine};
use std::sync::Arc;
pub const NAMES: [&str; 3] = ["collections", "closures", "strings_dynamic"];
pub struct Native;
impl NativeInterface for Native {
fn syscall(
&mut self,
_: u32,
_: &[Value],
_: &mut HostReturn,
_: &mut HostContext,
) -> Result<(), prometeu_hal::vm_fault::VmFault> {
panic!("workload has no syscalls")
}
}
fn field(id: u32) -> NamedType {
NamedType { type_id: TypeId(id), name: None }
}
fn sig(results: &[u32]) -> Signature {
Signature { parameters: vec![], results: results.iter().copied().map(TypeId).collect() }
}
pub fn image(name: &str) -> Arc<ValidatedProgramImage> {
let mut kinds = vec![
TypeKind::Builtin(BuiltinId::INT64),
TypeKind::Builtin(BuiltinId::INT32),
TypeKind::Builtin(BuiltinId::FLOAT),
TypeKind::Builtin(BuiltinId::BOOL),
TypeKind::Builtin(BuiltinId::STRING),
TypeKind::Builtin(BuiltinId::DYNAMIC),
TypeKind::Builtin(BuiltinId::VEC2),
];
kinds.extend([
TypeKind::Struct(vec![field(0), field(7), field(4), field(5)]),
TypeKind::Array(TypeId(7)),
TypeKind::Fn(sig(&[0])),
TypeKind::Array(TypeId(4)),
]);
let (root, body, captures) = match name {
"collections" => {
// Each iteration publishes one self-cycle plus a rooted containing array.
let chunk = "STRUCT_NEW 7\nSET_LOCAL 0\nGET_LOCAL 0\nGET_LOCAL 0\nSTRUCT_SET type=7,field=1\nGET_LOCAL 0\nPUSH_I64 73\nSTRUCT_SET type=7,field=0\nPUSH_I64 2\nARRAY_NEW 8\nSET_LOCAL 1\nGET_LOCAL 1\nPUSH_I64 0\nGET_LOCAL 0\nARRAY_SET 8\nGET_LOCAL 1\nPUSH_I64 0\nARRAY_GET 8\nSTRUCT_GET type=7,field=0\nPOP\n";
(
format!("{}GET_LOCAL 0\nSTRUCT_GET type=7,field=0\nRET", chunk.repeat(64)),
"RET".to_owned(),
vec![],
)
}
"closures" => (
format!(
"{}PUSH_I64 73\nMAKE_CLOSURE fn=1,type=9\nCALL_CLOSURE 9\nRET",
"PUSH_I64 73\nMAKE_CLOSURE fn=1,type=9\nPOP\n".repeat(127)
),
"FRAME_SYNC\nGET_CAPTURE 0\nRET".to_owned(),
vec![TypeId(0)],
),
"strings_dynamic" => {
let chunk = "PUSH_CONST 0\nPUSH_CONST 1\nADD\nSET_LOCAL 0\nPUSH_I64 1\nARRAY_NEW 10\nSET_LOCAL 1\nGET_LOCAL 1\nPUSH_I64 0\nGET_LOCAL 0\nARRAY_SET 10\nGET_LOCAL 1\nPUSH_I64 0\nARRAY_GET 10\nDYN_PACK 4\nDYN_UNPACK 4\nPOP\n";
(
format!("{}GET_LOCAL 0\nPUSH_CONST 2\nEQ\nRET", chunk.repeat(64)),
"RET".to_owned(),
vec![],
)
}
_ => panic!("unknown workload"),
};
let mut code = assemble(&root).unwrap();
let body = assemble(&body).unwrap();
let functions = vec![
FunctionDecl {
signature: sig(&[if name == "strings_dynamic" { 3 } else { 0 }]),
local_slots: 2,
max_stack_slots: 32,
code_len: code.len() as u32,
..Default::default()
},
FunctionDecl {
signature: if name == "closures" { sig(&[0]) } else { sig(&[]) },
captures,
code_offset: code.len() as u32,
code_len: body.len() as u32,
max_stack_slots: 4,
..Default::default()
},
];
code.extend(body);
let mut budget = LoadBudget::new(Default::default());
let registry = Registry::resolve(
RegistryDeclarations {
types: kinds.into_iter().map(|kind| TypeDecl { name: None, kind }).collect(),
functions,
implementations: vec![],
},
code.len(),
&mut budget,
)
.unwrap();
let constants = vec![
prometeu_bytecode::model::ConstantPoolEntry::String("resource".into()),
prometeu_bytecode::model::ConstantPoolEntry::String("-73".into()),
prometeu_bytecode::model::ConstantPoolEntry::String("resource-73".into()),
];
let bytes = PbxModule {
registry: &registry,
code: &code,
constants: &constants,
debug: None,
exports: &[],
syscalls: &[],
}
.serialize(&mut budget)
.unwrap();
ValidatedProgramImage::load(
&bytes,
&mut LoadBudget::new(Default::default()),
prometeu_hal::syscalls::caps::NONE,
)
.unwrap()
}
pub struct Workload {
pub name: &'static str,
pub vm: VirtualMachine,
pub frames: u64,
pub digest: u64,
prepare: bool,
envelope: Option<([u64; 8], usize, usize, usize)>,
}
impl Workload {
pub fn new(name: &'static str) -> Self {
Self {
name,
vm: VirtualMachine::from_image(image(name), Default::default()),
frames: 0,
digest: 0xcbf29ce484222325,
prepare: true,
envelope: None,
}
}
pub fn frame(&mut self) {
if self.prepare {
self.vm.prepare_boot_call().unwrap();
}
let mut finished = false;
for _ in 0..1_000 {
let r = self.vm.run_budget(10_000, &mut Native, &mut HostContext::new(None)).unwrap();
self.digest = (self.digest ^ r.cycles_used).wrapping_mul(0x100000001b3);
match r.reason {
LogicalFrameEndingReason::BudgetExhausted => {}
LogicalFrameEndingReason::FrameSync => {
self.prepare = false;
finished = true;
break;
}
LogicalFrameEndingReason::EndOfRom => {
let expected = if self.name == "strings_dynamic" {
Value::Boolean(true)
} else {
Value::Int64(73)
};
assert_eq!(&*self.vm.operand_stack_top(1), &[expected]);
self.prepare = true;
finished = true;
break;
}
reason => panic!("{} unexpected {reason:?}", self.name),
}
}
assert!(finished, "bounded workload did not complete");
self.frames += 1;
self.digest = (self.digest ^ self.vm.pc() as u64 ^ self.frames).wrapping_mul(0x100000001b3);
}
pub fn check_stationary(&mut self) {
let s = self.vm.resource_snapshot();
assert_eq!(s.budget.used[3], 0, "temporary reservations must be refunded");
assert_eq!(s.retired_handles, 0);
assert_eq!(s.call_depth, 0, "checkpoint at root completion");
// Default threshold 1024; fixtures allocate a divisor of 1024 per entry.
// The closure is rooted at FRAME_SYNC collection, then dies at RET.
// RET has insufficient new allocations to trigger another collection;
// one unrooted object legitimately waits for the next threshold sweep.
assert_eq!(s.live_objects, usize::from(self.name == "closures"));
assert_eq!(s.tracked_strings, 0);
let now = (s.budget.used, s.live_objects, s.free_handles, s.tracked_strings);
if let Some(expected) = &self.envelope {
assert_eq!(&now, expected, "{} stationary envelope", self.name);
} else {
self.envelope = Some(now);
}
}
pub fn finish(self) {
let observer = self.vm.resource_observer();
drop(self);
assert_eq!(
observer.diagnostic_snapshot().used,
[0; 8],
"last session owner must release every reservation"
);
}
}
@@ -1,28 +1,25 @@
use prometeu_hal::vm_fault::VmFault;
use prometeu_vm::VirtualMachine;
use prometeu_vm::{HostContext, HostReturn, NativeInterface, SyscallId};
#[allow(dead_code)]
#[path = "../../../console/prometeu-vm/tests/support/callables.rs"]
mod callables;
use prometeu_bytecode::{registry::TypeId, Value};
use prometeu_vm::LogicalFrameEndingReason;
#[test]
fn gc_collects_unreachable_closure_but_keeps_marked() {
// Black-box check: a fresh VM with no program initializes and can run a zero-budget slice.
// The GC behavior is covered by unit tests inside the VM crate; this layer test remains
// as a smoke-test for public API stability.
struct NoopNative;
impl NativeInterface for NoopNative {
fn syscall(
&mut self,
_id: SyscallId,
_args: &[prometeu_bytecode::Value],
_ret: &mut HostReturn,
_ctx: &mut HostContext,
) -> Result<(), VmFault> {
Ok(())
}
}
let mut vm = VirtualMachine::default();
let mut native = NoopNative;
let mut ctx = HostContext::new(None);
let res = vm.run_budget(0, &mut native, &mut ctx);
assert!(res.is_ok());
fn gc_collects_unreachable_closures_and_retains_active_environment_through_sync() {
let body =
format!("{}FRAME_SYNC\nGET_CAPTURE 0\nRET", "MAKE_CLOSURE fn=2,type=4\nPOP\n".repeat(1030));
let mut vm = callables::vm(&[
(
"PUSH_I32 73\nMAKE_CLOSURE fn=1,type=4\nCALL_CLOSURE 4\nRET",
callables::sig(&[], &[0]),
vec![],
),
(&body, callables::sig(&[], &[0]), vec![TypeId(0)]),
("PUSH_I32 1\nRET", callables::sig(&[], &[0]), vec![]),
]);
assert_eq!(callables::run(&mut vm, 100_000).reason, LogicalFrameEndingReason::FrameSync);
assert_eq!(vm.heap().allocation_count(), 1031);
assert_eq!(vm.heap().len(), 1, "only the active closure remains reachable");
assert_eq!(callables::run(&mut vm, 100).reason, LogicalFrameEndingReason::EndOfRom);
assert_eq!(&*vm.operand_stack_top(1), &[Value::Int32(73)]);
}
@@ -523,6 +523,64 @@ mod tests {
use std::io::{Read, Write};
use std::net::TcpStream;
#[test]
fn desktop_worker_survives_repeated_home_resume_and_cold_reset() {
use prometeu_firmware::firmware::firmware_state::ResetStep;
use prometeu_hal::InputSignals;
let path = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
.join("../../../test-cartridges/dummy-boy");
let mut runner = HostRunner::new(None, None);
runner.set_boot_target(BootTarget::Cartridge {
path: path.to_string_lossy().into_owned(),
debug: false,
debug_port: 0,
});
let signals = InputSignals::default();
for cycle in 0..32 {
runner.firmware.change_state(
FirmwareState::Reset(ResetStep),
&signals,
&mut runner.hardware,
);
assert_eq!(runner.firmware.os.sessions().vm_session_count(), 0);
for _ in 0..6000 {
runner.firmware.tick(&signals, &mut runner.hardware);
if matches!(runner.firmware.state, FirmwareState::GameRunning(_)) {
break;
}
assert!(!matches!(runner.firmware.state, FirmwareState::AppCrashes(_)));
std::thread::sleep(Duration::from_millis(1));
}
assert!(matches!(runner.firmware.state, FirmwareState::GameRunning(_)), "boot {cycle}");
for _ in 0..8 {
runner.firmware.tick(&signals, &mut runner.hardware);
}
runner.firmware.request_home_from_host();
for _ in 0..32 {
runner.firmware.tick(&signals, &mut runner.hardware);
if matches!(runner.firmware.state, FirmwareState::HubHome(_)) {
break;
}
}
assert!(matches!(runner.firmware.state, FirmwareState::HubHome(_)), "home {cycle}");
assert!(runner.firmware.resume_resident_game_from_home());
for _ in 0..8 {
runner.firmware.tick(&signals, &mut runner.hardware);
}
assert!(
matches!(runner.firmware.state, FirmwareState::GameRunning(_)),
"resume {cycle}"
);
assert_eq!(runner.firmware.os.sessions().vm_session_count(), 1);
}
runner.firmware.change_state(
FirmwareState::Reset(ResetStep),
&signals,
&mut runner.hardware,
);
assert_eq!(runner.firmware.os.sessions().vm_session_count(), 0);
}
#[test]
fn presentation_state_requires_initial_redraw_only_once() {
let mut state = PresentationState::default();
@@ -0,0 +1,68 @@
"""Exercise the real Dummy Boy desktop window on localhost:17959.
Start the host with --debug test-cartridges/dummy-boy --port 17959 first.
This finite smoke observes progress; its timeout is not a realtime guarantee.
"""
import json
import socket
import time
def run():
with socket.create_connection(("127.0.0.1", 17959), timeout=10) as connection:
connection.settimeout(10)
with connection.makefile("rb") as incoming:
def send(kind):
connection.sendall((json.dumps({"type": kind}) + "\n").encode())
def state():
send("getState")
deadline = time.monotonic() + 10
while time.monotonic() < deadline:
line = incoming.readline()
assert line, "Desktop disconnected"
message = json.loads(line)
assert message.get("event") != "fault", message
if message.get("type") == "getState":
return message
raise TimeoutError("Desktop did not answer getState")
def await_progress(previous):
deadline = time.monotonic() + 5
current = state()
while current["frame_index"] == previous and time.monotonic() < deadline:
time.sleep(0.02)
current = state()
return current
handshake = json.loads(incoming.readline())
assert handshake["type"] == "handshake", handshake
assert handshake["cartridge"]["app_id"] == 2, handshake
print(json.dumps(handshake), flush=True)
send("start")
time.sleep(0.5)
first = state()
assert first["app_id"] == 2, first
for _ in range(32):
send("pause")
time.sleep(0.025)
paused = state()
time.sleep(0.025)
still = state()
assert (paused["pc"], paused["frame_index"]) == (still["pc"], still["frame_index"])
send("stepFrame")
stepped = await_progress(paused["frame_index"])
assert stepped["frame_index"] == paused["frame_index"] + 1, (paused, stepped)
send("resume")
resumed = await_progress(stepped["frame_index"])
assert resumed["frame_index"] > stepped["frame_index"], (stepped, resumed)
print(json.dumps({
"result": "pass", "cycles": 32,
"first_frame": first["frame_index"], "last_frame": resumed["frame_index"],
"last_pc": resumed["pc"],
}), flush=True)
send("resume")
if __name__ == "__main__":
run()
@@ -6,6 +6,9 @@ license.workspace = true
repository.workspace = true
description = "In-process Prometeu host that boots and steps cartridges without a window, display, or audio device."
[features]
resource-diagnostics = ["prometeu-vm/resource-diagnostics"]
[dependencies]
prometeu-bytecode = { path = "../../console/prometeu-bytecode" }
prometeu-drivers = { path = "../../console/prometeu-drivers" }
@@ -451,6 +451,10 @@ impl Default for HeadlessHost {
}
}
#[cfg(all(test, feature = "resource-diagnostics"))]
#[path = "resource_qualification_tests.rs"]
mod resource_qualification_tests;
impl RenderSubmissionSink for HeadlessPlatform {
fn submit_render_submission(
&mut self,
@@ -0,0 +1,73 @@
#[allow(dead_code)]
#[path = "../../../console/prometeu-vm/tests/support/callables.rs"]
mod callables;
use super::{AdvanceFrameOutcome, HeadlessHost};
use prometeu_bytecode::{Value, registry::TypeId};
#[test]
fn thousand_reset_reload_cycles_release_session_owners_and_preserve_controls() {
let body =
format!("{}FRAME_SYNC\nGET_CAPTURE 0\nRET", "MAKE_CLOSURE fn=2,type=4\nPOP\n".repeat(1030));
let bytes = callables::bytes(
&[
(
"PUSH_I32 73\nMAKE_CLOSURE fn=1,type=4\nCALL_CLOSURE 4\nRET",
callables::sig(&[], &[0]),
vec![],
),
(&body, callables::sig(&[], &[0]), vec![TypeId(0)]),
("PUSH_I32 1\nRET", callables::sig(&[], &[0]), vec![]),
],
vec![],
&[],
)
.unwrap();
let path = std::env::temp_dir().join(format!("prometeu-resource-reset-{}", std::process::id()));
std::fs::create_dir_all(&path).unwrap();
std::fs::write(path.join("program.pbx"), bytes).unwrap();
std::fs::write(path.join("manifest.json"),r#"{"magic":"PMTU","cartridge_version":1,"app_id":77,"title":"Resource reset qualification","app_version":"1.0.0","app_mode":"Game","capabilities":[]}"#).unwrap();
let mut host = HeadlessHost::new();
for cycle in 0..1000 {
host.boot(path.to_string_lossy()).unwrap();
let observer = host
.firmware
.os
.sessions()
.resident_game_session_for_app(77)
.unwrap()
.vm
.resource_observer();
assert!(
matches!(
host.advance_frame().unwrap(),
AdvanceFrameOutcome::FrameCompleted { logical_frame_index: 1, .. }
),
"cycle {cycle}"
);
{
let sessions = host.firmware.os.sessions();
let vm = &sessions.resident_game_session_for_app(77).unwrap().vm;
assert_eq!(vm.heap().len(), 1);
assert_eq!(vm.resource_snapshot().gc.collections, 1);
}
let pc = host.get_state().pc;
host.pause().unwrap();
host.tick_once();
assert_eq!(host.get_state().pc, pc);
host.resume().unwrap();
assert!(matches!(
host.advance_frame().unwrap(),
AdvanceFrameOutcome::FrameCompleted { logical_frame_index: 2, .. }
));
assert_eq!(&*host.get_state().stack_top, &[Value::Int32(73)]);
assert!(host.get_fault().is_none());
host.reset();
assert_eq!(host.firmware.os.sessions().vm_session_count(), 0);
assert_eq!(
observer.diagnostic_snapshot().used,
[0; 8],
"reset {cycle} retained session allocation"
);
}
std::fs::remove_dir_all(path).unwrap();
}
@@ -0,0 +1,102 @@
---
id: LSN-0068
ticket: vm-resource-limits-handle-safety-and-long-run-stability
title: Resource Stability Needs Phase-Aware Evidence
created: 2026-10-14
tags: [vm, memory, gc, testing, ownership]
---
## Context
DEC-0056 and PLN-0187 delivered an audit of the existing VM resource contracts,
opt-in engineering diagnostics and reproducible macOS/arm64 workloads. The user
explicitly revised the closure criterion on 2026-10-14: accept the executed
functional, stationary and host evidence plus the observed extended run, waive
eight-hour completion for this delivery, and leave further testing to future
qualification. The discussion is closed; the interrupted timed run did not pass
an eight-hour endurance test. This lesson preserves the decision and its revision
after workflow cleanup; the [discussion index](../../index.ndjson) tracks closure.
Normative references remain [memory and GC](../../../docs/specs/runtime/03-memory-stack-heap-and-allocation.md),
[Registry/PBX](../../../docs/specs/runtime/02c-program-registry-and-pbx-v1.md),
[typed callables](../../../docs/specs/runtime/02b-vm-function-values-and-closures.md)
and [single-context lifecycle](../../../docs/specs/runtime/09a-coroutines-and-cooperative-scheduling.md).
The [published evidence report](../../../docs/vm-arch/resource-stability-qualification.md)
and its compact data record contain the enforcement matrix, commands, counters,
source-log hashes, environmental details and limitations. This lesson introduces
no new quotas, GC policy, instruction costs or runtime guarantees.
## Key Decisions
### Observe the existing collector before redesigning it
The implementation kept threshold-based collection at the published safepoints.
Fixed-size budget counters and logarithmic GC histograms expose behavior through
an opt-in Rust feature without expanding the guest ABI or retaining guest roots.
The audit did not reproduce a pre-existing VM contract violation requiring a
collector redesign. One newly added diagnostic needed before-step sampling to
count an entry whose first instruction immediately returns; its regression
distinguishes an observation defect from a change to execution semantics.
### Acceptance and run outcome are separate facts
Three stationary families each completed 216,000 frames and identical-input
replay with final session reservations zero. Functional suites, 1,000 headless
reset/reload cycles, desktop lifecycle tests and real-window controls also
passed. The longer release run reached a common checkpoint of 36,420,000 frames
per family/replay, with stable resource envelopes and no recorded replay failure.
External RSS ranged from 3,296 to 3,408 KiB over 369 samples.
That process exited with code 101 after approximately 3h22 elapsed when writing
stdout failed because the host disk was full. It never emitted completed active
duration, final replay/disposal or qualification-pass markers. The log occupied
about 5.7 MiB; its size alone did not explain exhaustion of the host volume.
The explicit scope revision accepted the available evidence, not an invented
successful run. Final disposal evidence comes from the normally completed
stationary and ownership/reset tests. Additional endurance, representative-game
headroom and unavailable-platform qualification remain unexecuted.
## Patterns and Algorithms
Compare memory at equivalent workload phases. A closure reachable during sync
collection can become unreachable at RET without enough subsequent allocation
to trigger another sweep. The observed stable 332-byte closure is expected
under the current policy; forcing collection to make every checkpoint zero
would test a different policy. Final owner disposal supplies a separate oracle.
Distinguish live guest objects, reserved capacities, retired/free handle slots,
native string owners and process RSS. Capacity can remain charged after objects
die, and a native string snapshot can legitimately retain its accounting domain
after VM disposal. A cloned budget observer retains accounting but no guest
owners, allowing the tests to assert zero only after the actual final owner dies.
Use independent sessions with identical input for lockstep replay. Compare logical
output, cycles and resource envelopes, while recording host timing separately.
Every frame has a finite slice guard; no-sync loops have a finite slice count
instead of an unreachable completed-frame target. Time-bounded runs must record
their actual logical progress rather than assuming identical frame counts across
equal wall durations or platforms.
## Pitfalls
- A no-op VM smoke cannot establish GC reachability. The replacement layer test
allocates 1,031 closures and checks that only the active environment survives.
- A fixed short sleep is not evidence of desktop responsiveness. Bounded polling
of logical progress removed the initial harness timing assumption.
- Reserved-capacity refusal counters can include speculative growth followed by
successful exact-capacity fallback; they are not guest trap counts.
- Histogram quantiles are bucket upper bounds, capped by the observed maximum.
Host timing includes scheduling effects and does not establish real-time safety.
- A stationary synthetic workload repeatedly exercises a bounded state space.
More elapsed time does not automatically supply more scenario coverage.
- An interrupted process supplies useful checkpoints but cannot prove execution
of its final assertions. An explicit acceptance revision must preserve that gap.
## Takeaways
Resource safety combines admission enforcement, ownership tests and integrated
observations; elapsed time alone cannot replace any of them. Preserve failures
and attribution, make acceptance changes explicit, and keep future qualification
separate from delivered evidence. The long-run example is manually invoked;
the repository pipelines run bounded automated tests and do not request the
eight-hour workload. Audio remains open and no audio behavior was qualified here.
@@ -0,0 +1,250 @@
{
"recorded_on": "2026-10-14",
"delivery_status": "accepted_complete_with_observed_evidence",
"timed_run_status": "interrupted_host_disk_full",
"eight_hour_requirement": "waived_for_this_delivery_by_user_2026-10-14",
"requested_active_seconds": 28800,
"completed_active_seconds": null,
"observed_elapsed_approx_seconds": 12120,
"exit_code": 101,
"failure": "failed printing to stdout: No space left on device (os error 28)",
"last_log_write_utc": "2026-10-13T18:32:24Z",
"run_completion_markers_present": false,
"final_disposal_checked_in_timed_run": false,
"last_checkpoints": {
"collections": {
"name": "collections",
"frames": 36430000,
"digest": "080a33b50f388f15",
"cycles": 165902220000,
"live": 0,
"free": 1024,
"retired": 0,
"strings": 0,
"depth": 0,
"peak_depth": 1,
"used": [
0,
1024,
61672,
0,
0,
0,
0,
0
],
"peaks": [
344064,
1024,
61672,
30720,
0,
0,
0,
1
],
"limits": [
268435456,
1048576,
67108864,
67108864,
67108864,
262144,
4194304,
1024
],
"reservation_refusals": [
0,
0,
0,
0,
0,
0,
0,
0
],
"gc": 4553750,
"reclaimed": 4663040000,
"gc_p50_upper_ns": 65535,
"gc_p95_upper_ns": 65535,
"gc_p99_upper_ns": 131071,
"gc_max_ns": 128828583,
"mark_max_ns": 13416458,
"sweep_max_ns": 128826291,
"reconcile_max_ns": 0
},
"closures": {
"name": "closures",
"frames": 36420000,
"digest": "232bd29e13e355a5",
"cycles": 28280130000,
"live": 1,
"free": 1024,
"retired": 0,
"strings": 0,
"depth": 0,
"peak_depth": 2,
"used": [
332,
1025,
123056,
0,
0,
0,
0,
0
],
"peaks": [
340300,
1025,
123056,
61440,
0,
0,
0,
2
],
"limits": [
268435456,
1048576,
67108864,
67108864,
67108864,
262144,
4194304,
1024
],
"reservation_refusals": [
0,
0,
0,
0,
0,
0,
0,
0
],
"gc": 2276250,
"reclaimed": 2330879999,
"gc_p50_upper_ns": 65535,
"gc_p95_upper_ns": 131071,
"gc_p99_upper_ns": 131071,
"gc_max_ns": 46940041,
"mark_max_ns": 2268708,
"sweep_max_ns": 46938417,
"reconcile_max_ns": 0
},
"strings_dynamic": {
"name": "strings_dynamic",
"frames": 36420000,
"digest": "4bc7ac7e0ba21cc5",
"cycles": 123900840000,
"live": 0,
"free": 1024,
"retired": 0,
"strings": 0,
"depth": 0,
"peak_depth": 1,
"used": [
0,
1024,
127320,
0,
0,
0,
0,
0
],
"peaks": [
319488,
1024,
127320,
32768,
11264,
1024,
11,
1
],
"limits": [
268435456,
1048576,
67108864,
67108864,
67108864,
262144,
4194304,
1024
],
"reservation_refusals": [
0,
0,
0,
0,
0,
0,
0,
0
],
"gc": 2276250,
"reclaimed": 2330880000,
"gc_p50_upper_ns": 65535,
"gc_p95_upper_ns": 131071,
"gc_p99_upper_ns": 131071,
"gc_max_ns": 51491375,
"mark_max_ns": 5365833,
"sweep_max_ns": 51488000,
"reconcile_max_ns": 34300250
}
},
"rss": {
"sample_count": 369,
"first_sample": {
"utc": "2026-10-13T15:28:13.763663+00:00",
"pid": "86850",
"rss_kib": "3360",
"elapsed": "17:49"
},
"last_sample": {
"utc": "2026-10-13T18:32:21.624887+00:00",
"pid": "86850",
"rss_kib": "3328",
"elapsed": "03:21:57"
},
"min_kib": 3296,
"max_kib": 3408,
"startup_not_sampled": true
},
"stationary_completed_run": {
"frames_per_family_and_replay": 216000,
"final_records": [
"load_complete active_seconds=70.652 wall_seconds=70.652 excluded_seconds=0.000",
"replay_pass name=collections frames=216000 digest=f81812a99fda45e5 cycles=983664000 disposed_usage=zero",
"replay_pass name=closures frames=216000 digest=ca8215da0bc457a5 cycles=167724000 disposed_usage=zero",
"replay_pass name=strings_dynamic frames=216000 digest=9711182bb9169a65 cycles=734832000 disposed_usage=zero",
"qualification_pass scope=vm_workloads_only"
]
},
"frozen_binary_sha256": "d9265cd90c085965220a581623023a84bb6d4d2efe9cb91ad12ebf501e15e388",
"source_artifacts": [
{
"name": "resource-qualification-8h.log",
"bytes": 5934947,
"sha256": "e558cb0c3b1bcc6cdba0f601b22ac999a40cfbb05e8e8331f9e22f65819c63f6"
},
{
"name": "resource-qualification-rss.csv",
"bytes": 19696,
"sha256": "884fb642d61f5ff1adbb3832772c45d94d1dd1b00a87d50ba993ed17b6f1a253"
},
{
"name": "resource-qualification-216000.log",
"bytes": 35550,
"sha256": "dc8b0ffb61b2e083686c51c545ac33fd265835ee8cd5b2e582bfafa6cfed4f12"
},
{
"name": "resource-qualification-environment.txt",
"bytes": 267,
"sha256": "b3691f703de9523d6b5c2038cc45303fe81253c307e7a7486a879b31f27b830c"
}
]
}
@@ -0,0 +1,254 @@
# VM Resource Safety and Stability Qualification
The local functional and stationary workload checks described below passed on
macOS/arm64. This delivery was **accepted as complete on 2026-10-14** using those
checks and the observed extended-run evidence. The planned eight-hour active
release soak was interrupted by host disk exhaustion after approximately 3h22
elapsed; the user explicitly waived the eight-hour completion requirement for
this delivery. Eight-hour endurance was not demonstrated. Linux and other
architectures have not been tested by this qualification.
The normative contracts remain [Registry/PBX v1](../specs/runtime/02c-program-registry-and-pbx-v1.md),
[memory/GC](../specs/runtime/03-memory-stack-heap-and-allocation.md),
[typed callables](../specs/runtime/02b-vm-function-values-and-closures.md), and
[single-context lifecycle](../specs/runtime/09a-coroutines-and-cooperative-scheduling.md).
This report does not change quotas, safepoints, instruction costs or scheduler
policy. Audio and representative-game headroom are outside this qualification.
## Environment and Reproduction
Recorded 2026-10-13: Apple M2 Pro, macOS 27.0.1 (26A434), arm64, Rust
1.98.1 (48a229cea 2026-09-01). Base repository revision:
`6c2a07e579fce6eda15bff89dc0e9c9cf02e7dbf`, with the resource diagnostics and
qualification changes in the working tree. No result below implies x86-64 or
Linux execution.
```sh
cargo test --workspace
cargo test --workspace --features prometeu-host-headless/resource-diagnostics
cargo test --release --workspace --features prometeu-host-headless/resource-diagnostics
cargo run --release -p prometeu-vm --features resource-diagnostics --example resource_qualification -- --frames 216000
cargo run --release -p prometeu-vm --features resource-diagnostics --example resource_qualification -- --seconds 28800
cargo test --release -p prometeu-vm --features resource-diagnostics --lib -- --ignored --nocapture
cargo test --release -p prometeu-bytecode reference_map_probe -- --ignored --nocapture
cargo test -p prometeu-host-desktop-winit --lib -- --ignored
```
The `resource-diagnostics` feature adds engineering observations through Rust
only. It adds no guest syscall. The eight-hour example is a manual command;
the repository CI, release workflow and Jenkins pipeline do not invoke it. Normal builds omit timing histograms, additional
budget counters and depth sampling. Identical-input replay compares logical
outputs/cycles, never wall-clock durations.
## Resource and Enforcement Matrix
All sizes below are binary MiB. `LOAD_RESOURCE_LIMIT` is a load-time refusal;
`TRAP_RESOURCE_LIMIT` is runtime code `0x10`. `TRAP_INVALID_HANDLE` is `0x0F`.
Each failure must preserve its domain, requested amount and limit. Instruction
and function context are checked where applicable. VM quotas are not RSS caps.
| Resource / invariant | Accepted limit / rule | Enforcement and evidence |
| --- | --- | --- |
| Input PBX | 64 MiB | HAL `cartridge_loader::read_program` checks metadata before read and detects extra data without unchecked growth. `program_admission_accepts_exact_limit_and_rejects_growth_after_metadata`, metadata-before-read, short/interrupted-read and real sparse-file rejection tests. |
| Code | 32 MiB | Bytecode envelope/owned decoder uses `LoadBudget` before materialization; `registry_v1` covers oversized declarations, truncation, code ranges and transactional payload refusal. |
| Type/function records | 65,536 each | Registry decoder/resolver bounded count admission; `oversized_counts_fail_before_dependent_allocation` and invalid reference tests. |
| Implementation/nested records | 262,144 / 1,048,576 | Registry resolution/codec count checks; multi-slot/trait records, aggregate checks and owned-payload rollback coverage in `registry_v1`. |
| Names | 4,096 bytes each; 4 MiB aggregate | `name_limits_include_aggregate_and_empty_is_not_absent`; invalid UTF-8/flags/tails rejected before publication. |
| Retained Registry | 64 MiB/image | Charged native layouts/capacities during resolution; `work_retained_and_temporary_limits_refuse_before_publication`; explicit reference-map probe records native representation. |
| Load scratch | 128 MiB | Parser/writer/verifier temporary buffers charged and refunded; `scratch_is_refunded_per_function_and_preserves_prior_load_ownership`, `stack_analysis_refunds_all_state_buffers_and_preserves_prior_ownership`, sealed-image load probe. |
| Load/verifier work | 268,435,456 units | `LoadBudget::work`, CFG/type reprocessing and native lookup charging; `late_work_refusal_releases_all_new_owners`, `native_lookup_work_refusal_retains_the_actual_instruction_pc`, work-exhaustion tests. |
| Declared frame/results | 16,384 slots / 1,024 slots | Registry layout/verification before narrowed execution widths; `literal_zero_max_stack_is_preserved_and_frame_limits_are_not_truncated`, call/result-group verification tests. |
| Constants | 1,048,576 entries; 64 MiB string content/image; 4 MiB individual string | Owned decoder/writer checks before materialization; `complete_module_writer_checks_constant_quotas_before_payload_allocation`, `constant_string_limits_are_checked_before_materialization`, shared image ownership and final-owner tests. |
| Guest objects | 256 MiB/session | Heap `StoredAllocation`, typed payloads and captures reserve before publication. Header/payload boundary, partial construction and provisional allocation tests; stationary graph/closure workloads. |
| Handle slots | 1,048,576 including free/retired | Heap admission and persistent slot charge; `handle_limit_counts_free_and_retired_slots_and_reuse_does_not_charge_twice`. |
| Generations | No wrap; stale handles trap | `maximum_generation_is_retired_without_wraparound`, stale typed reference/collection/callable tests. Controlled generation injection tests retirement without billions of allocations. |
| Persistent auxiliary storage | 64 MiB/session | `BudgetVec` capacities for stacks, frames, globals, tables, free lists and string ledger. Atomic table growth, entry/call quota refusal, capacity transfer and rollback tests. |
| Operation temporaries | 64 MiB/session | Provisional coexistence, native results and GC worklist reservation. `temporary_growth_refusal_keeps_old_buffer_and_refunds_provisional_charge`, `mark_worklist_refusal_changes_no_marks_or_objects`, collection/callable rollback tests. |
| Runtime string content/count | 64 MiB / 262,144 allocations | Weak `StringLedger` admission; UTF-8 byte/count boundaries, empty strings, pressure reconciliation and failed ledger growth tests. |
| Individual runtime string | 4 MiB | `content_and_individual_limits_are_checked_before_materialization`, bounded native writer tests; refusal precedes content creation/callback. |
| Call depth | 1,024 including entry | `call_depth_includes_entry_and_traps_before_frame_growth` covers 1/3/1,024; zero-entry setup and closure call refusal preserve owners and attempt costs. |
| GC roots/safepoints | FRAME_SYNC and successful last-root RET, threshold only | Active frame environments, transitively rooted Trait/Dynamic/native groups, cycles and rooted results. Actual layer test allocates 1,031 closures and verifies only the active closure survives sync collection. |
| Native provenance/retention | Session ownership retained explicitly | Native string import/snapshot and cross-session isolation tests; an external string snapshot keeps its accounting domain alive after VM disposal and its final drop refunds it. Raw handle bits/snapshots do not establish guest roots. |
| Lifecycle | Same stacks/quotas; existing hook budgets | Nested pause/resume hook, breakpoint/budget, forbidden FRAME_SYNC, entry refusal and result ownership tests; repeated host reset and desktop Home/resume validation. |
| No-sync loop | Existing slice/fuel semantics | 1,000 finite slices of a sealed `JMP 0` program return BudgetExhausted, preserve PC/depth/capacities, perform no GC, and remain breakpoint-controllable. No frame completion is fabricated. |
Relevant test sources:
[Registry v1](../../crates/console/prometeu-bytecode/tests/registry_v1.rs),
[HAL cartridge admission](../../crates/console/prometeu-hal/src/cartridge_loader.rs),
[heap](../../crates/console/prometeu-vm/src/heap.rs),
[string ledger](../../crates/console/prometeu-vm/src/string_ledger/tests.rs),
[typed execution](../../crates/console/prometeu-vm/src/virtual_machine/typed_tests.rs),
[callables](../../crates/console/prometeu-vm/src/virtual_machine/callable_tests.rs),
[collections](../../crates/console/prometeu-vm/src/virtual_machine/collections_tests.rs),
[integrated resource probes](../../crates/console/prometeu-vm/tests/resource_stability.rs).
The matrix identifies enforcement and discriminating evidence; it does not claim
exhaustive coverage of all bytecode states or recovery from physical allocator
abort. A blocked native call cannot be preempted by VM fuel. LoadBudget records
one admission attempt; its retained counters are not RAII session reservations.
Image/Registry/constant owners are checked separately through owner lifetimes.
## Bounded Observations
The budget snapshot uses the discriminant order
`GuestBytes, HandleSlots, AuxiliaryBytes, TemporaryBytes, StringBytes,
StringAllocations, IndividualStringBytes, CallDepth`. Current usage is reserved
storage; individual size/depth are admission checks and therefore have a peak
but no current reservation. Refusal counters include speculative geometric
capacity attempts that may succeed through an exact-capacity fallback. They
must not be interpreted as guest trap counts.
GC mark, sweep, total and string reconciliation use fixed 64-bucket logarithmic
nanosecond histograms. Percentiles are **bucket upper bounds**, capped by observed
maximum, not exact percentiles. Count and maximum are exact observations.
Snapshots and observers retain no guest root. A budget observer keeps accounting
available after VM destruction without retaining its guest allocations.
## Stationary Workloads
The [versioned fixtures](../../crates/console/prometeu-vm/tests/support/qualification.rs)
are serialized through the official bounded PBX writer and loaded through the
sealed production image boundary. Fixed input seed/value is 73. Each family has
an independent session and a second identical session used for lockstep replay:
- **Collections:** self-referencing typed nodes and containing arrays, alias
reads and numeric output verification; 128 objects per completed entry.
- **Closures:** 127 discarded closures and one executing captured closure,
FRAME_SYNC inside that closure, then result 73 returned through its caller;
128 objects per two completed frames.
- **Strings/Dynamic:** UTF-8 concatenation, typed string arrays, Dynamic
pack/unpack and equality against an independent expected constant.
The default GC allocation threshold remains 1,024. Each frame has a finite
1,000-slice harness guard. No history of individual instructions/frames is kept.
Equivalent checkpoints occur every 10,000 frames, starting at the end of the
10,000-frame warm-up. Logical output and cycle digest are compared every frame;
resource snapshots are compared at checkpoints. Timed mode runs the replay
alongside the primary sessions, not as a second eight-hour job.
Observed stationary result (216,000 frames **per family and per replay**, release):
| Family | Logical cycles | Digest | Guest bytes at checkpoint | Auxiliary bytes | Handle slots | GC collections |
| --- | ---: | --- | ---: | ---: | ---: | ---: |
| Collections | 983,664,000 | `f81812a99fda45e5` | 0 | 61,672 | 1,024 | 27,000 |
| Closures | 167,724,000 | `ca8215da0bc457a5` | 332 | 123,056 | 1,025 | 13,500 |
| Strings/Dynamic | 734,832,000 | `9711182bb9169a65` | 0 | 127,320 | 1,024 | 13,500 |
All replays matched and every disposed session reported zero reserved usage.
The run took approximately 70.652 seconds of active wall time; this is not a
real-time frame-rate promise. Temporary/string reservations were zero at the
stationary checkpoints. Peak guest storage was 344,064 / 340,300 / 319,488 bytes,
respectively. Peak tracked runtime string content was 11,264 bytes in 1,024
allocations. These are synthetic small workloads, not near-limit game headroom.
One closure remains allocated after its root return: it was reachable at the
preceding FRAME_SYNC collection, then became unreachable, with insufficient new
allocation to trigger another collection at RET. It is reclaimed by the next
threshold sweep. The stable 332 bytes are expected safepoint policy, not a leak;
final session disposal releases them. The free-list capacity and 1,025 published
slots are also legitimately retained. Retirement has a separate injected-state
oracle because retired slots must accumulate by contract.
## Host and Functional Evidence
- Baseline workspace: 984 passed, zero failed, 10 ignored.
- Instrumented workspace debug and release before the final diagnostic-depth and
image-owner regression additions: 990 passed each, zero failed, 10 ignored.
- Final default workspace: 986 passed, zero failed, 10 ignored. Final instrumented
workspace debug: 993 passed, zero failed, 10 ignored. Final instrumented VM
release unit/resource subset: 291 passed, zero failed, 2 ignored. The final
desktop lifecycle regression also passed separately in release.
- Formatting, whitespace and documentation reference checks passed.
- Headless: 1,000 production boot/GC/frame/pause/resume/reset cycles passed;
session count and all session reservations returned to zero after every reset.
- Desktop runner: 32 cold-reset/Home/resume cycles with the actual desktop
hardware and render worker passed in debug and release.
- Real desktop window: 32 pause/stepFrame/resume cycles via port 17959 passed,
progressing from logical frame 2,668 to 2,937; no fault event was observed.
The initial harness incorrectly assumed completion within a fixed 60 ms.
Replacing that assumption with bounded polling of logical progress passed;
no runtime timing contract was changed.
- All five explicit localhost debugger transport tests passed.
- Three explicit release engineering probes passed: sealed image load,
storage/GC and Registry reference-map measurements. The sealed-image example
used 77,906 peak scratch bytes and retained zero scratch after publication.
- Remaining ignored default-suite cases are the independent file-host memcard
latency measurement and packaged-installation smoke; neither is claimed as
executed here or required for VM resource qualification.
Desktop smoke reproduction (two terminals, from repository root):
```sh
cargo run -p prometeu-host-desktop-winit -- --debug test-cartridges/dummy-boy --port 17959
python3 crates/host/prometeu-host-desktop-winit/tests/resource_control_smoke.py
```
## Interrupted Extended Run and Accepted Scope
The interrupted run used a frozen release executable with SHA-256
`d9265cd90c085965220a581623023a84bb6d4d2efe9cb91ad12ebf501e15e388`.
It counts batches lasting at most two seconds as active wall time; longer gaps
are conservatively excluded, so suspension/descheduling can extend the run.
It requires at least 28,800 credited seconds and prints final replay and
disposal results only after that duration. Do not infer completion from an
intermediate checkpoint or process survival.
Checked on 2026-10-14: the process exited with code 101 after stdout failed with
`No space left on device (os error 28)`. The last log modification was
2026-10-13 18:32:24 UTC, approximately 3 hours 22 minutes after launch. This is
observed elapsed time, not a completed measurement of credited active time.
There are no `load_complete`, `replay_pass`, or `qualification_pass` records;
final disposal checks were not reached.
The last common checkpoint completed 36,420,000 frames per family and replay;
collections additionally recorded 36,430,000. All recorded equivalent-phase
envelopes remained stable and no replay assertion failed before the stdout
failure. The 369 external RSS samples span 15:28:13–18:32:21 UTC and range from
3,296 to 3,408 KiB, with a final sample of 3,328 KiB. Sampling started about
18 minutes after launch, so it does not measure startup peak RSS.
The log is 5,934,947 bytes; its size alone does not explain the host volume
exhaustion. On inspection the volume reported only 1.3 GiB available. This
failure is in host log output, not a recorded guest resource-limit violation.
The user accepted the observed evidence on 2026-10-14 and removed the requirement
to repeat eight hours before closing this delivery. The interrupted attempt is
not a successful eight-hour run. Final disposal and successful runner completion
are evidenced by the separate 216,000-frame run and ownership/reset tests above,
not inferred from the interrupted process. Further duration, workload diversity
and platform testing remain future work with their own acceptance criteria.
The [compact evidence record](evidence/resource-stability-2026-10-13.json)
preserves the last counters, digests, GC distributions, RSS summary, completed
stationary-run records and source-log hashes independently of temporary files.
| Family | Last recorded frames | GC collections | GC p50 upper bound (ms) | GC p95 / p99 upper bounds (ms) | GC maximum (ms) |
| --- | ---: | ---: | ---: | ---: | ---: |
| Collections | 36,430,000 | 4,553,750 | 0.065535 | 0.065535 / 0.131071 | 128.828583 |
| Closures | 36,420,000 | 2,276,250 | 0.065535 | 0.131071 / 0.131071 | 46.940041 |
| Strings/Dynamic | 36,420,000 | 2,276,250 | 0.065535 | 0.131071 / 0.131071 | 51.491375 |
These are instrumented host wall-time observations and may include scheduling
delays; the maxima are not a universal latency guarantee. They do not qualify
representative-game headroom or a near-limit workload.
Session artifacts currently reside in `/tmp/resource-qualification-8h.log`,
`/tmp/resource-qualification-rss.csv`, and
`/tmp/resource-qualification-environment.txt`. The external RSS monitor also
exited successfully after the workload stopped. RSS is not a guest allocation
counter. These artifacts preserve the interrupted attempt for diagnosis.
The frozen executable predates a diagnostic-only correction that counts an
entry returning on its first instruction in peak call depth. These workloads
already execute multiple instructions before return and their depth evidence
is unaffected; the immediate-return case is checked by a separate regression.
## Future Platform Qualification
Run the same corpus, seed, commands and logical oracles on Linux/x86-64 and other
supported targets when available. Record native layouts and quota boundaries
locally; native-capacity counts can differ by ABI. Cross-platform numerical,
resource-fault and timing comparisons must not be inferred from this macOS run.
The [resource stability lesson](../../discussion/lessons/DSC-0056-vm-resource-limits-handle-safety-and-long-run-stability/LSN-0068-resource-stability-needs-phase-aware-evidence.md)
explains phase-aware memory observations, ownership checks and the distinction
between an accepted delivery and an interrupted test run.