feat(registry): checkpoint PLN-0176 foundations and validated partial integrations

This commit is contained in:
2026-10-07 17:49:46 +01:00
parent 01fab56cc6
commit 126a9e50e7
63 changed files with 8499 additions and 1462 deletions
@@ -0,0 +1,503 @@
//! 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,
}
const COUNT: usize = 8;
const MIB: u64 = 1_048_576;
const CEILINGS: [u64; COUNT] =
[256 * MIB, 1_048_576, 64 * MIB, 64 * MIB, 64 * MIB, 262_144, 4 * MIB, 1_024];
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RuntimeLimits([u64; COUNT]);
impl Default for RuntimeLimits {
fn default() -> Self {
Self(CEILINGS)
}
}
impl RuntimeLimits {
pub fn get(&self, resource: RuntimeResource) -> u64 {
self.0[resource as usize]
}
/// Test/host configurations may lower ceilings; guest code cannot raise them.
pub fn lowered(
mut self,
resource: RuntimeResource,
limit: u64,
) -> Result<Self, ResourceFailure> {
if limit > self.get(resource) {
return Err(ResourceFailure {
resource,
reason: ResourceReason::Limit,
requested: limit,
limit: self.get(resource),
});
}
self.0[resource as usize] = limit;
Ok(self)
}
}
#[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,
used: [u64; COUNT],
}
#[derive(Debug, Clone)]
pub struct RuntimeBudget(Arc<Mutex<State>>);
impl Default for RuntimeBudget {
fn default() -> Self {
Self::new(RuntimeLimits::default())
}
}
impl RuntimeBudget {
pub fn new(limits: RuntimeLimits) -> Self {
Self(Arc::new(Mutex::new(State { limits, used: [0; COUNT] })))
}
fn state(&self) -> MutexGuard<'_, State> {
self.0.lock().unwrap_or_else(std::sync::PoisonError::into_inner)
}
pub fn used(&self, resource: RuntimeResource) -> u64 {
self.state().used[resource as usize]
}
pub fn limit(&self, resource: RuntimeResource) -> u64 {
self.state().limits.get(resource)
}
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 })
} else {
Ok(())
}
}
pub fn failure(
&self,
resource: RuntimeResource,
reason: ResourceReason,
requested: u64,
) -> ResourceFailure {
ResourceFailure { resource, reason, requested, limit: self.limit(resource) }
}
pub fn bytes<T>(
&self,
count: usize,
resource: RuntimeResource,
) -> Result<u64, ResourceFailure> {
count
.checked_mul(size_of::<T>())
.and_then(|bytes| u64::try_from(bytes).ok())
.ok_or_else(|| self.failure(resource, ResourceReason::SizeOverflow, u64::MAX))
}
pub fn reserve(
&self,
resource: RuntimeResource,
amount: u64,
) -> Result<Reservation, ResourceFailure> {
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,
})?;
if requested > limit {
return Err(ResourceFailure {
resource,
reason: ResourceReason::Limit,
requested,
limit,
});
}
state.used[resource as usize] = requested;
Ok(Reservation { budget: self.clone(), resource, amount })
}
pub(crate) fn empty_charge(&self, resource: RuntimeResource) -> Reservation {
Reservation { budget: self.clone(), resource, amount: 0 }
}
}
/// Unique accounting ownership; moving this token never charges a second time.
#[derive(Debug)]
pub struct Reservation {
budget: RuntimeBudget,
resource: RuntimeResource,
amount: u64,
}
impl Reservation {
pub fn amount(&self) -> u64 {
self.amount
}
pub(crate) fn absorb(&mut self, mut other: Self) {
assert!(Arc::ptr_eq(&self.budget.0, &other.budget.0));
assert_eq!(self.resource, other.resource);
self.amount += other.amount;
other.amount = 0;
}
fn resize(&mut self, amount: u64) -> Result<(), ResourceFailure> {
if amount > self.amount {
self.absorb(self.budget.reserve(self.resource, amount - self.amount)?);
} else {
self.budget.state().used[self.resource as usize] -= self.amount - amount;
self.amount = amount;
}
Ok(())
}
}
impl Drop for Reservation {
fn drop(&mut self) {
self.budget.state().used[self.resource as usize] -= self.amount;
}
}
/// Scheduler storage owns its capacity charge, including unused capacity.
/// During growth, the old allocation is also covered by a temporary reservation.
#[derive(Debug)]
pub(crate) struct BudgetQueue<T> {
data: VecDeque<T>,
charge: Reservation,
}
impl<T> BudgetQueue<T> {
#[cfg(test)]
pub(crate) fn capacity_bytes(&self) -> u64 {
self.charge.amount
}
pub fn new(budget: &RuntimeBudget) -> Self {
Self { data: VecDeque::new(), charge: budget.empty_charge(RuntimeResource::AuxiliaryBytes) }
}
#[cfg(test)]
pub fn len(&self) -> usize {
self.data.len()
}
pub fn is_empty(&self) -> bool {
self.data.is_empty()
}
pub fn pop_front(&mut self) -> Option<T> {
self.data.pop_front()
}
pub fn reserve(&mut self, additional: usize) -> Result<(), ResourceFailure> {
let b = &self.charge.budget;
let q = RuntimeResource::AuxiliaryBytes;
let required = self
.data
.len()
.checked_add(additional)
.ok_or_else(|| b.failure(q, ResourceReason::SizeOverflow, u64::MAX))?;
if required <= self.data.capacity() {
return Ok(());
}
// Exact growth prevents a geometric allocation from exceeding the available quota.
let bytes = b.bytes::<T>(required, q)?;
let mut extra = b.reserve(q, bytes - self.charge.amount)?;
let _temporary = b.reserve(RuntimeResource::TemporaryBytes, self.charge.amount)?;
let mut candidate = VecDeque::new();
candidate
.try_reserve_exact(required)
.map_err(|_| b.failure(q, ResourceReason::AllocationFailed, bytes))?;
let actual = b.bytes::<T>(candidate.capacity(), q)?;
// If the allocator reports excess capacity, reject before publishing the new buffer.
extra.resize(actual - self.charge.amount)?;
candidate.append(&mut self.data);
self.data = candidate;
self.charge.absorb(extra);
Ok(())
}
pub fn push_back(&mut self, value: T) -> Result<(), ResourceFailure> {
self.reserve(1)?;
self.data.push_back(value);
Ok(())
}
pub fn insert(&mut self, index: usize, value: T) -> Result<(), ResourceFailure> {
self.reserve(1)?;
self.data.insert(index, value);
Ok(())
}
pub fn partition_point(&self, predicate: impl FnMut(&T) -> bool) -> usize {
self.data.partition_point(predicate)
}
}
#[cfg(test)]
mod tests {
use super::*;
use RuntimeResource::*;
#[test]
fn accepted_limits_are_fixed_and_can_only_be_lowered() {
let limits = RuntimeLimits::default();
for (resource, expected) in [
(GuestBytes, 268_435_456),
(HandleSlots, 1_048_576),
(AuxiliaryBytes, 67_108_864),
(TemporaryBytes, 67_108_864),
(StringBytes, 67_108_864),
(StringAllocations, 262_144),
(IndividualStringBytes, 4_194_304),
(CallDepth, 1_024),
] {
assert_eq!(limits.get(resource), expected);
assert!(limits.clone().lowered(resource, expected + 1).is_err());
assert_eq!(limits.clone().lowered(resource, 0).unwrap().get(resource), 0);
}
}
#[test]
fn shared_reservations_refund_on_failure_and_follow_their_owner() {
let budget = RuntimeBudget::new(RuntimeLimits::default().lowered(GuestBytes, 10).unwrap());
let charge = budget.reserve(GuestBytes, 7).unwrap();
let shared = budget.clone();
let failure = shared.reserve(GuestBytes, 4).unwrap_err();
assert_eq!((failure.resource, failure.requested, failure.limit), (GuestBytes, 11, 10));
assert_eq!(budget.used(GuestBytes), 7);
let transferred = charge;
assert_eq!(shared.used(GuestBytes), 7);
let tail = shared.reserve(GuestBytes, 3).unwrap();
assert_eq!(shared.used(GuestBytes), 10);
drop(transferred);
assert_eq!(shared.used(GuestBytes), 3);
drop(tail);
assert_eq!(shared.used(GuestBytes), 0);
}
#[test]
fn queue_capacity_is_retained_until_drop_and_transfer_does_not_charge_twice() {
let budget =
RuntimeBudget::new(RuntimeLimits::default().lowered(AuxiliaryBytes, 16).unwrap());
let mut queue = BudgetQueue::<u64>::new(&budget);
queue.push_back(11).unwrap();
queue.push_back(22).unwrap();
assert_eq!(budget.used(AuxiliaryBytes), 16);
assert!(queue.push_back(33).is_err());
assert_eq!(queue.pop_front(), Some(11));
assert_eq!(budget.used(AuxiliaryBytes), 16);
queue.push_back(44).unwrap(); // reuse retained capacity
let mut moved = queue;
assert_eq!(budget.used(AuxiliaryBytes), 16);
assert_eq!(moved.pop_front(), Some(22));
assert_eq!(moved.pop_front(), Some(44));
drop(moved);
assert_eq!(budget.used(AuxiliaryBytes), 0);
assert_eq!(budget.used(TemporaryBytes), 0);
}
#[test]
fn temporary_growth_refusal_keeps_old_buffer_and_refunds_provisional_charge() {
let limits = RuntimeLimits::default()
.lowered(AuxiliaryBytes, 16)
.unwrap()
.lowered(TemporaryBytes, 0)
.unwrap();
let budget = RuntimeBudget::new(limits);
let mut queue = BudgetQueue::<u64>::new(&budget);
queue.push_back(11).unwrap();
let error = queue.push_back(22).unwrap_err();
assert_eq!((error.resource, error.requested), (TemporaryBytes, 8));
assert_eq!(budget.used(AuxiliaryBytes), 8);
assert_eq!(queue.pop_front(), Some(11));
assert_eq!(queue.pop_front(), None);
assert_eq!(budget.used(TemporaryBytes), 0);
}
#[test]
fn size_and_length_overflow_fail_before_growth() {
let budget = RuntimeBudget::default();
assert_eq!(
budget.bytes::<u64>(usize::MAX, AuxiliaryBytes).unwrap_err().reason,
ResourceReason::SizeOverflow
);
let mut queue = BudgetQueue::<u64>::new(&budget);
queue.push_back(11).unwrap();
assert_eq!(queue.reserve(usize::MAX).unwrap_err().reason, ResourceReason::SizeOverflow);
assert_eq!(budget.used(AuxiliaryBytes), 8);
assert_eq!(queue.pop_front(), Some(11));
}
}
/// Contiguous execution storage. The capacity reservation travels with the buffer
/// when a coroutine suspends/resumes, and is refunded only when storage is dropped.
#[derive(Debug)]
pub struct BudgetVec<T> {
data: Vec<T>,
charge: Reservation,
}
impl<T> BudgetVec<T> {
pub fn new(budget: &RuntimeBudget, resource: RuntimeResource) -> Self {
Self { data: Vec::new(), charge: budget.empty_charge(resource) }
}
pub(crate) fn prepare_growth(
&self,
additional: usize,
) -> Result<Option<VecGrowth<T>>, ResourceFailure> {
let b = &self.charge.budget;
let q = self.charge.resource;
let required = self
.data
.len()
.checked_add(additional)
.ok_or_else(|| b.failure(q, ResourceReason::SizeOverflow, u64::MAX))?;
if required <= self.data.capacity() {
return Ok(None);
}
let bytes = b.bytes::<T>(required, q)?;
let mut extra = b.reserve(q, bytes - self.charge.amount)?;
let temporary = b.reserve(RuntimeResource::TemporaryBytes, self.charge.amount)?;
let mut candidate = Vec::new();
candidate
.try_reserve_exact(required)
.map_err(|_| b.failure(q, ResourceReason::AllocationFailed, bytes))?;
extra.resize(b.bytes::<T>(candidate.capacity(), q)? - self.charge.amount)?;
Ok(Some(VecGrowth {
candidate,
extra,
_temporary: temporary,
old_capacity: self.data.capacity(),
}))
}
pub(crate) fn commit_growth(&mut self, growth: Option<VecGrowth<T>>) {
if let Some(mut growth) = growth {
assert_eq!(self.data.capacity(), growth.old_capacity);
growth.candidate.append(&mut self.data);
self.data = growth.candidate;
self.charge.absorb(growth.extra);
}
}
pub fn reserve(&mut self, additional: usize) -> Result<(), ResourceFailure> {
let growth = self.prepare_growth(additional)?;
self.commit_growth(growth);
Ok(())
}
pub(crate) fn accounted_bytes(&self) -> u64 {
self.charge.amount
}
pub(crate) fn from_slice(
budget: &RuntimeBudget,
resource: RuntimeResource,
values: &[T],
) -> Result<Self, ResourceFailure>
where
T: Clone,
{
let mut result = Self::new(budget, resource);
result.reserve(values.len())?;
result.data.extend_from_slice(values);
Ok(result)
}
pub fn push(&mut self, value: T) -> Result<(), ResourceFailure> {
self.reserve(1)?;
self.data.push(value);
Ok(())
}
pub fn resize(&mut self, len: usize, value: T) -> Result<(), ResourceFailure>
where
T: Clone,
{
self.reserve(len.saturating_sub(self.data.len()))?;
self.data.resize(len, value);
Ok(())
}
pub fn pop(&mut self) -> Option<T> {
self.data.pop()
}
pub fn clear(&mut self) {
self.data.clear();
}
pub fn truncate(&mut self, len: usize) {
self.data.truncate(len);
}
pub fn capacity(&self) -> usize {
self.data.capacity()
}
pub fn as_slice(&self) -> &[T] {
&self.data
}
pub fn drain(&mut self, range: impl std::ops::RangeBounds<usize>) -> std::vec::Drain<'_, T> {
self.data.drain(range)
}
pub fn take(&mut self) -> Self {
let empty = Self::new(&self.charge.budget, self.charge.resource);
std::mem::replace(self, empty)
}
/// Only used with the bounded native result writer after reserving its result slots.
pub(crate) fn native_result_buffer(&mut self) -> &mut Vec<T> {
&mut self.data
}
#[cfg(test)]
pub(crate) fn fixture(data: Vec<T>) -> Self {
let budget = RuntimeBudget::default();
let bytes = budget.bytes::<T>(data.capacity(), RuntimeResource::AuxiliaryBytes).unwrap();
let charge = budget.reserve(RuntimeResource::AuxiliaryBytes, bytes).unwrap();
Self { data, charge }
}
}
impl<T> std::ops::Deref for BudgetVec<T> {
type Target = [T];
fn deref(&self) -> &[T] {
&self.data
}
}
impl<T> std::ops::DerefMut for BudgetVec<T> {
fn deref_mut(&mut self) -> &mut [T] {
&mut self.data
}
}
impl<'a, T> IntoIterator for &'a BudgetVec<T> {
type Item = &'a T;
type IntoIter = std::slice::Iter<'a, T>;
fn into_iter(self) -> Self::IntoIter {
self.data.iter()
}
}
#[cfg(test)]
impl<T: PartialEq> PartialEq<Vec<T>> for BudgetVec<T> {
fn eq(&self, other: &Vec<T>) -> bool {
&self.data == other
}
}
/// Unpublished growth can be dropped to refund every provisional reservation.
pub(crate) struct VecGrowth<T> {
candidate: Vec<T>,
extra: Reservation,
_temporary: Reservation,
old_capacity: usize,
}