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
+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);
}