feat(vm): add VM-owned PCG64 random and coverage headroom
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good

Implement GC-managed random generators, next/nextf intrinsics, bounded ranges and deterministic conformance coverage. Publish the runtime contract and producer guidance.

Give coverage domains at least five percentage points of measured headroom while preserving sufficient floors. Record local qualification: make ci-domains passes with 939 tests and all domain gates green.
This commit is contained in:
2026-10-09 12:51:05 +01:00
parent 9318cf7cd3
commit 3e39a90083
50 changed files with 2545 additions and 189 deletions
+187 -34
View File
@@ -83,6 +83,7 @@ pub enum BuiltinTypeShape {
Scalar,
Aggregate,
Dynamic,
Reference,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
@@ -137,13 +138,23 @@ impl BuiltinTypeMeta {
// This context-free catalogue must never claim to validate it.
return Err(BuiltinValueError::RegistryRequired);
}
if self.shape == BuiltinTypeShape::Reference {
if values.len() != 1 {
return Err(BuiltinValueError::ArityMismatch { expected: 1, got: values.len() });
}
return if matches!(values, [Value::Null]) {
Ok(())
} else {
Err(BuiltinValueError::RegistryRequired)
};
}
let layout = self.flatten_layout();
validate_values_against_layout(values, &layout)
}
fn flatten_into(&self, out: &mut Vec<AbiType>) {
match self.shape {
BuiltinTypeShape::Scalar | BuiltinTypeShape::Dynamic => {
BuiltinTypeShape::Scalar | BuiltinTypeShape::Dynamic | BuiltinTypeShape::Reference => {
out.extend_from_slice(self.flat_slot_layout)
}
BuiltinTypeShape::Aggregate => {
@@ -216,9 +227,38 @@ pub enum BuiltinValueError {
TypeMismatch { index: usize, expected: AbiType },
}
pub type IntrinsicImplementation =
pub type IntrinsicHostImplementation =
fn(&[Value], &mut HostContext<'_>) -> Result<Vec<Value>, IntrinsicExecutionError>;
/// VM-owned operations cannot be invoked through a HostContext callback.
#[derive(Debug, Clone, Copy)]
pub enum IntrinsicImplementation {
Host(IntrinsicHostImplementation),
VmOwned,
}
impl IntrinsicImplementation {
pub fn host_callback(self) -> Option<IntrinsicHostImplementation> {
match self {
Self::Host(f) => Some(f),
Self::VmOwned => None,
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum IntrinsicCostModel {
Fixed,
RandomRejectionV1,
}
impl IntrinsicCostModel {
pub const fn name(self) -> &'static str {
match self {
Self::Fixed => "fixed",
Self::RandomRejectionV1 => "random_rejection_v1",
}
}
}
#[derive(Debug, Clone, Copy)]
pub struct IntrinsicMeta {
pub id: u32,
@@ -228,8 +268,12 @@ pub struct IntrinsicMeta {
pub arg_layout: &'static [AbiType],
pub ret_layout: &'static [AbiType],
pub parameter_names: &'static [&'static str],
/// Total virtual call cost; math attempts are charged before checks.
/// Full fixed cost, or base cost for a variable model.
pub cost_cycles: u64,
pub cost_model: IntrinsicCostModel,
pub attempt_cost_cycles: u64,
pub max_attempts: u32,
pub mutates_guest_state: bool,
pub deterministic: bool,
pub may_allocate: bool,
pub implementation: IntrinsicImplementation,
@@ -343,7 +387,7 @@ const PIXEL_FIELDS: [BuiltinFieldMeta; 3] = [
},
];
const BUILTIN_TYPES: [BuiltinTypeMeta; 9] = [
const BUILTIN_TYPES: [BuiltinTypeMeta; 10] = [
BuiltinTypeMeta {
id: 0x0001,
name: COLOR.name,
@@ -371,6 +415,15 @@ const BUILTIN_TYPES: [BuiltinTypeMeta; 9] = [
flat_slot_layout: &PIXEL_LAYOUT,
flat_slot_width: 3,
},
BuiltinTypeMeta {
id: 0x16,
name: "Random",
version: 1,
shape: BuiltinTypeShape::Reference,
fields: &[],
flat_slot_layout: &[AbiType::Builtin(BuiltinTypeKey::new("Random", 1))],
flat_slot_width: 1,
},
scalar_meta(0x10, "Int32", &[AbiType::Scalar(BuiltinScalarType::Int32)]),
scalar_meta(0x11, "Int64", &[AbiType::Scalar(BuiltinScalarType::Int64)]),
scalar_meta(0x12, "Float", &[AbiType::Scalar(BuiltinScalarType::Float)]),
@@ -513,9 +566,13 @@ const INTRINSICS: [IntrinsicMeta; 21] = [
ret_layout: &SINGLE_FLOAT_RET,
parameter_names: &["ax", "ay", "bx", "by"],
cost_cycles: 10,
cost_model: crate::IntrinsicCostModel::Fixed,
attempt_cost_cycles: 0,
max_attempts: 0,
mutates_guest_state: false,
deterministic: true,
may_allocate: false,
implementation: vec2_dot,
implementation: crate::IntrinsicImplementation::Host(vec2_dot),
},
IntrinsicMeta {
id: 0x1001,
@@ -526,9 +583,13 @@ const INTRINSICS: [IntrinsicMeta; 21] = [
ret_layout: &SINGLE_FLOAT_RET,
parameter_names: &["x", "y"],
cost_cycles: 40,
cost_model: crate::IntrinsicCostModel::Fixed,
attempt_cost_cycles: 0,
max_attempts: 0,
mutates_guest_state: false,
deterministic: true,
may_allocate: false,
implementation: vec2_length,
implementation: crate::IntrinsicImplementation::Host(vec2_length),
},
IntrinsicMeta {
id: 0x1100,
@@ -539,9 +600,13 @@ const INTRINSICS: [IntrinsicMeta; 21] = [
ret_layout: &COLOR_RET,
parameter_names: &["raw"],
cost_cycles: 1,
cost_model: crate::IntrinsicCostModel::Fixed,
attempt_cost_cycles: 0,
max_attempts: 0,
mutates_guest_state: false,
deterministic: true,
may_allocate: false,
implementation: color_from_raw,
implementation: crate::IntrinsicImplementation::Host(color_from_raw),
},
IntrinsicMeta {
id: 0x1101,
@@ -552,9 +617,13 @@ const INTRINSICS: [IntrinsicMeta; 21] = [
ret_layout: &COLOR_RET,
parameter_names: &["r", "g", "b"],
cost_cycles: 1,
cost_model: crate::IntrinsicCostModel::Fixed,
attempt_cost_cycles: 0,
max_attempts: 0,
mutates_guest_state: false,
deterministic: true,
may_allocate: false,
implementation: color_rgb,
implementation: crate::IntrinsicImplementation::Host(color_rgb),
},
IntrinsicMeta {
id: 0x1102,
@@ -565,9 +634,13 @@ const INTRINSICS: [IntrinsicMeta; 21] = [
ret_layout: &COLOR_RET,
parameter_names: &["r", "g", "b", "a"],
cost_cycles: 1,
cost_model: crate::IntrinsicCostModel::Fixed,
attempt_cost_cycles: 0,
max_attempts: 0,
mutates_guest_state: false,
deterministic: true,
may_allocate: false,
implementation: color_rgba,
implementation: crate::IntrinsicImplementation::Host(color_rgba),
},
IntrinsicMeta {
id: 0x1103,
@@ -578,9 +651,13 @@ const INTRINSICS: [IntrinsicMeta; 21] = [
ret_layout: &COLOR_RET,
parameter_names: &["value"],
cost_cycles: 1,
cost_model: crate::IntrinsicCostModel::Fixed,
attempt_cost_cycles: 0,
max_attempts: 0,
mutates_guest_state: false,
deterministic: true,
may_allocate: false,
implementation: color_html_rgba,
implementation: crate::IntrinsicImplementation::Host(color_html_rgba),
},
IntrinsicMeta {
id: 0x1104,
@@ -591,9 +668,13 @@ const INTRINSICS: [IntrinsicMeta; 21] = [
ret_layout: &COLOR_RET,
parameter_names: &["value"],
cost_cycles: 1,
cost_model: crate::IntrinsicCostModel::Fixed,
attempt_cost_cycles: 0,
max_attempts: 0,
mutates_guest_state: false,
deterministic: true,
may_allocate: false,
implementation: color_gray_scale,
implementation: crate::IntrinsicImplementation::Host(color_gray_scale),
},
IntrinsicMeta {
id: 0x1105,
@@ -604,9 +685,13 @@ const INTRINSICS: [IntrinsicMeta; 21] = [
ret_layout: &INT_RET,
parameter_names: &["color"],
cost_cycles: 1,
cost_model: crate::IntrinsicCostModel::Fixed,
attempt_cost_cycles: 0,
max_attempts: 0,
mutates_guest_state: false,
deterministic: true,
may_allocate: false,
implementation: color_hex,
implementation: crate::IntrinsicImplementation::Host(color_hex),
},
IntrinsicMeta {
id: 0x1106,
@@ -617,9 +702,13 @@ const INTRINSICS: [IntrinsicMeta; 21] = [
ret_layout: &INT_RET,
parameter_names: &["color"],
cost_cycles: 1,
cost_model: crate::IntrinsicCostModel::Fixed,
attempt_cost_cycles: 0,
max_attempts: 0,
mutates_guest_state: false,
deterministic: true,
may_allocate: false,
implementation: color_alpha,
implementation: crate::IntrinsicImplementation::Host(color_alpha),
},
IntrinsicMeta {
id: 0x1120,
@@ -630,9 +719,13 @@ const INTRINSICS: [IntrinsicMeta; 21] = [
ret_layout: &COLOR_RET,
parameter_names: &[],
cost_cycles: 1,
cost_model: crate::IntrinsicCostModel::Fixed,
attempt_cost_cycles: 0,
max_attempts: 0,
mutates_guest_state: false,
deterministic: true,
may_allocate: false,
implementation: color_black,
implementation: crate::IntrinsicImplementation::Host(color_black),
},
IntrinsicMeta {
id: 0x1121,
@@ -643,9 +736,13 @@ const INTRINSICS: [IntrinsicMeta; 21] = [
ret_layout: &COLOR_RET,
parameter_names: &[],
cost_cycles: 1,
cost_model: crate::IntrinsicCostModel::Fixed,
attempt_cost_cycles: 0,
max_attempts: 0,
mutates_guest_state: false,
deterministic: true,
may_allocate: false,
implementation: color_white,
implementation: crate::IntrinsicImplementation::Host(color_white),
},
IntrinsicMeta {
id: 0x1122,
@@ -656,9 +753,13 @@ const INTRINSICS: [IntrinsicMeta; 21] = [
ret_layout: &COLOR_RET,
parameter_names: &[],
cost_cycles: 1,
cost_model: crate::IntrinsicCostModel::Fixed,
attempt_cost_cycles: 0,
max_attempts: 0,
mutates_guest_state: false,
deterministic: true,
may_allocate: false,
implementation: color_red,
implementation: crate::IntrinsicImplementation::Host(color_red),
},
IntrinsicMeta {
id: 0x1123,
@@ -669,9 +770,13 @@ const INTRINSICS: [IntrinsicMeta; 21] = [
ret_layout: &COLOR_RET,
parameter_names: &[],
cost_cycles: 1,
cost_model: crate::IntrinsicCostModel::Fixed,
attempt_cost_cycles: 0,
max_attempts: 0,
mutates_guest_state: false,
deterministic: true,
may_allocate: false,
implementation: color_green,
implementation: crate::IntrinsicImplementation::Host(color_green),
},
IntrinsicMeta {
id: 0x1124,
@@ -682,9 +787,13 @@ const INTRINSICS: [IntrinsicMeta; 21] = [
ret_layout: &COLOR_RET,
parameter_names: &[],
cost_cycles: 1,
cost_model: crate::IntrinsicCostModel::Fixed,
attempt_cost_cycles: 0,
max_attempts: 0,
mutates_guest_state: false,
deterministic: true,
may_allocate: false,
implementation: color_blue,
implementation: crate::IntrinsicImplementation::Host(color_blue),
},
IntrinsicMeta {
id: 0x1125,
@@ -695,9 +804,13 @@ const INTRINSICS: [IntrinsicMeta; 21] = [
ret_layout: &COLOR_RET,
parameter_names: &[],
cost_cycles: 1,
cost_model: crate::IntrinsicCostModel::Fixed,
attempt_cost_cycles: 0,
max_attempts: 0,
mutates_guest_state: false,
deterministic: true,
may_allocate: false,
implementation: color_yellow,
implementation: crate::IntrinsicImplementation::Host(color_yellow),
},
IntrinsicMeta {
id: 0x1126,
@@ -708,9 +821,13 @@ const INTRINSICS: [IntrinsicMeta; 21] = [
ret_layout: &COLOR_RET,
parameter_names: &[],
cost_cycles: 1,
cost_model: crate::IntrinsicCostModel::Fixed,
attempt_cost_cycles: 0,
max_attempts: 0,
mutates_guest_state: false,
deterministic: true,
may_allocate: false,
implementation: color_orange,
implementation: crate::IntrinsicImplementation::Host(color_orange),
},
IntrinsicMeta {
id: 0x1127,
@@ -721,9 +838,13 @@ const INTRINSICS: [IntrinsicMeta; 21] = [
ret_layout: &COLOR_RET,
parameter_names: &[],
cost_cycles: 1,
cost_model: crate::IntrinsicCostModel::Fixed,
attempt_cost_cycles: 0,
max_attempts: 0,
mutates_guest_state: false,
deterministic: true,
may_allocate: false,
implementation: color_indigo,
implementation: crate::IntrinsicImplementation::Host(color_indigo),
},
IntrinsicMeta {
id: 0x1128,
@@ -734,9 +855,13 @@ const INTRINSICS: [IntrinsicMeta; 21] = [
ret_layout: &COLOR_RET,
parameter_names: &[],
cost_cycles: 1,
cost_model: crate::IntrinsicCostModel::Fixed,
attempt_cost_cycles: 0,
max_attempts: 0,
mutates_guest_state: false,
deterministic: true,
may_allocate: false,
implementation: color_gray,
implementation: crate::IntrinsicImplementation::Host(color_gray),
},
IntrinsicMeta {
id: 0x1129,
@@ -747,9 +872,13 @@ const INTRINSICS: [IntrinsicMeta; 21] = [
ret_layout: &COLOR_RET,
parameter_names: &[],
cost_cycles: 1,
cost_model: crate::IntrinsicCostModel::Fixed,
attempt_cost_cycles: 0,
max_attempts: 0,
mutates_guest_state: false,
deterministic: true,
may_allocate: false,
implementation: color_cyan,
implementation: crate::IntrinsicImplementation::Host(color_cyan),
},
IntrinsicMeta {
id: 0x112A,
@@ -760,9 +889,13 @@ const INTRINSICS: [IntrinsicMeta; 21] = [
ret_layout: &COLOR_RET,
parameter_names: &[],
cost_cycles: 1,
cost_model: crate::IntrinsicCostModel::Fixed,
attempt_cost_cycles: 0,
max_attempts: 0,
mutates_guest_state: false,
deterministic: true,
may_allocate: false,
implementation: color_magenta,
implementation: crate::IntrinsicImplementation::Host(color_magenta),
},
IntrinsicMeta {
id: 0x112B,
@@ -773,9 +906,13 @@ const INTRINSICS: [IntrinsicMeta; 21] = [
ret_layout: &COLOR_RET,
parameter_names: &[],
cost_cycles: 1,
cost_model: crate::IntrinsicCostModel::Fixed,
attempt_cost_cycles: 0,
max_attempts: 0,
mutates_guest_state: false,
deterministic: true,
may_allocate: false,
implementation: color_transparent,
implementation: crate::IntrinsicImplementation::Host(color_transparent),
},
];
@@ -806,6 +943,7 @@ pub fn lookup_intrinsic(owner: &str, name: &str, version: u16) -> Option<&'stati
.iter()
.chain(crate::input_intrinsics::INPUT_INTRINSICS.iter())
.chain(crate::math_intrinsics::MATH_INTRINSICS.iter())
.chain(crate::random_intrinsics::RANDOM_INTRINSICS.iter())
.find(|meta| meta.owner == owner && meta.name == name && meta.version == version)
}
@@ -814,6 +952,7 @@ pub fn lookup_intrinsic_by_id(id: u32) -> Option<&'static IntrinsicMeta> {
.iter()
.chain(crate::input_intrinsics::INPUT_INTRINSICS.iter())
.chain(crate::math_intrinsics::MATH_INTRINSICS.iter())
.chain(crate::random_intrinsics::RANDOM_INTRINSICS.iter())
.find(|meta| meta.id == id)
}
@@ -877,6 +1016,9 @@ fn value_matches_abi_type(value: &Value, expected: AbiType) -> bool {
AbiType::Scalar(BuiltinScalarType::String) => {
matches!(value, Value::String(_) | Value::Null)
}
AbiType::Builtin(key) if key.name == "Random" && key.version == 1 => {
matches!(value, Value::HeapRef(_) | Value::Null)
}
AbiType::Builtin(key) if key == COLOR => {
matches!(value, Value::Int64(raw) if u32::try_from(*raw).is_ok())
}
@@ -1111,6 +1253,7 @@ pub(crate) fn metered_lookup_intrinsic(
.iter()
.chain(crate::input_intrinsics::INPUT_INTRINSICS.iter())
.chain(crate::math_intrinsics::MATH_INTRINSICS.iter())
.chain(crate::random_intrinsics::RANDOM_INTRINSICS.iter())
{
budget.work(1)?;
if meta.id == id {
@@ -1226,7 +1369,7 @@ mod tests {
fn intrinsic_implementations_are_registered_without_syscalls() {
let dot = lookup_intrinsic("vec2", "dot", 1).expect("vec2.dot must exist");
let mut ctx = HostContext::new(None);
let result = (dot.implementation)(
let result = (dot.implementation.host_callback().expect("host intrinsic"))(
&[Value::Float(1.0), Value::Float(2.0), Value::Float(3.0), Value::Float(4.0)],
&mut ctx,
)
@@ -1234,8 +1377,11 @@ mod tests {
assert_eq!(result, vec![Value::Float(11.0)]);
let length = lookup_intrinsic("vec2", "length", 1).expect("vec2.length must exist");
let result = (length.implementation)(&[Value::Float(3.0), Value::Float(4.0)], &mut ctx)
.expect("length implementation must execute");
let result = (length.implementation.host_callback().expect("host intrinsic"))(
&[Value::Float(3.0), Value::Float(4.0)],
&mut ctx,
)
.expect("length implementation must execute");
assert_eq!(result, vec![Value::Float(5.0)]);
}
@@ -1244,7 +1390,7 @@ mod tests {
let mut ctx = HostContext::new(None);
let rgba = lookup_intrinsic("color", "rgba", 1).expect("color.rgba must exist");
let result = (rgba.implementation)(
let result = (rgba.implementation.host_callback().expect("host intrinsic"))(
&[Value::Int64(0x11), Value::Int64(0x22), Value::Int64(0x33), Value::Int64(0x44)],
&mut ctx,
)
@@ -1252,13 +1398,19 @@ mod tests {
assert_eq!(result, vec![Value::Int64(0x11223344)]);
let html = lookup_intrinsic("color", "html_rgba", 1).expect("color.html_rgba must exist");
let result = (html.implementation)(&[Value::String("#AABBCCDD".into())], &mut ctx)
.expect("html_rgba implementation must execute");
let result = (html.implementation.host_callback().expect("host intrinsic"))(
&[Value::String("#AABBCCDD".into())],
&mut ctx,
)
.expect("html_rgba implementation must execute");
assert_eq!(result, vec![Value::Int64(0xAABBCCDD)]);
let alpha = lookup_intrinsic("color", "alpha", 1).expect("color.alpha must exist");
let result = (alpha.implementation)(&[Value::Int64(0xAABBCCDD)], &mut ctx)
.expect("alpha implementation must execute");
let result = (alpha.implementation.host_callback().expect("host intrinsic"))(
&[Value::Int64(0xAABBCCDD)],
&mut ctx,
)
.expect("alpha implementation must execute");
assert_eq!(result, vec![Value::Int64(0xDD)]);
}
@@ -1266,7 +1418,7 @@ mod tests {
fn input_intrinsic_requires_hardware_context() {
let mut ctx = HostContext::new(None);
let touch_x = lookup_intrinsic("input.touch", "x", 1).expect("input.touch.x must exist");
let err = (touch_x.implementation)(&[], &mut ctx)
let err = (touch_x.implementation.host_callback().expect("host intrinsic"))(&[], &mut ctx)
.expect_err("touch.x must fail without hardware context");
assert_eq!(err, IntrinsicExecutionError::HardwareUnavailable);
}
@@ -1287,6 +1439,7 @@ pub fn intrinsic_catalog() -> impl Iterator<Item = &'static IntrinsicMeta> {
.iter()
.chain(crate::input_intrinsics::INPUT_INTRINSICS.iter())
.chain(crate::math_intrinsics::MATH_INTRINSICS.iter())
.chain(crate::random_intrinsics::RANDOM_INTRINSICS.iter())
}
pub fn builtin_constant_catalog() -> impl Iterator<Item = &'static BuiltinConstMeta> {
BUILTIN_CONSTS.iter()