feat(runtime): add optional pause and resume lifecycle hooks
Intrepid/Prometeu/Runtime/pipeline/pr-master Build started...

This commit is contained in:
2026-10-13 12:18:18 +01:00
parent 23dc6fc66d
commit 0af8b2b1fe
39 changed files with 1381 additions and 70 deletions
@@ -37,6 +37,9 @@ impl LoadCode {
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum LoadReason {
LifecycleRole,
LifecycleSignature,
DuplicateLifecycleRole,
Magic,
Version,
Endianness,
@@ -57,8 +57,30 @@ pub struct TypeDecl {
pub name: Option<String>,
pub kind: TypeKind,
}
/// Runtime-owned roles; frontend names and FunctionIds are independent.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
#[repr(u8)]
pub enum LifecycleRole {
#[default]
None = 0,
BeforePause = 1,
BeforeResume = 2,
}
impl TryFrom<u8> for LifecycleRole {
type Error = E;
fn try_from(value: u8) -> Result<Self, E> {
match value {
0 => Ok(Self::None),
1 => Ok(Self::BeforePause),
2 => Ok(Self::BeforeResume),
_ => Err(E::new(C::InvalidRegistry, R::LifecycleRole)),
}
}
}
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct FunctionDecl {
pub lifecycle_role: LifecycleRole,
pub name: Option<String>,
pub signature: Signature,
pub code_offset: u32,
@@ -232,6 +254,7 @@ pub struct FunctionLayout {
#[derive(Debug)]
pub struct Registry {
lifecycle_hooks: [Option<FunctionId>; 2],
declarations: RegistryDeclarations,
layouts: Vec<TypeLayout>,
functions: Vec<FunctionLayout>,
@@ -239,6 +262,13 @@ pub struct Registry {
implementations: Vec<(TypeId, TypeId, ImplementationId)>,
}
impl Registry {
pub fn lifecycle_hook(&self, role: LifecycleRole) -> Option<FunctionId> {
match role {
LifecycleRole::None => None,
LifecycleRole::BeforePause => self.lifecycle_hooks[0],
LifecycleRole::BeforeResume => self.lifecycle_hooks[1],
}
}
pub fn declarations(&self) -> &RegistryDeclarations {
&self.declarations
}
@@ -346,10 +376,31 @@ impl Registry {
});
}
}
let mut lifecycle_hooks = [None; 2];
let mut functions = b.vector(d.functions.len(), Q::RegistryBytes)?;
let mut ranges = b.vector(d.functions.len(), Q::TemporaryBytes)?;
for (i, f) in d.functions.iter().enumerate() {
b.work(1)?;
if f.lifecycle_role != LifecycleRole::None {
let invalid = i == 0
|| !f.signature.parameters.is_empty()
|| !f.signature.results.is_empty()
|| !f.captures.is_empty();
if invalid {
return Err(E::new(C::InvalidEntrypoint, R::LifecycleSignature)
.in_section(1)
.record(i as u32)
.in_function(i as u32, None));
}
let slot = &mut lifecycle_hooks[f.lifecycle_role as usize - 1];
if slot.replace(FunctionId(i as u32)).is_some() {
return Err(E::new(C::InvalidRegistry, R::DuplicateLifecycleRole)
.in_section(1)
.record(i as u32)
.in_function(i as u32, None));
}
}
let params = width(f.signature.parameters.iter().map(|p| p.type_id), &layouts, b)?;
let results = width(f.signature.results.iter().copied(), &layouts, b)?;
let frame = u64::from(params) + u64::from(f.local_slots) + u64::from(f.max_stack_slots);
@@ -459,7 +510,7 @@ impl Registry {
.record(pair[1].2 .0));
}
}
Ok(Self { declarations: d, layouts, functions, implementations })
Ok(Self { lifecycle_hooks, declarations: d, layouts, functions, implementations })
}
}
fn overflow() -> E {
@@ -249,11 +249,14 @@ impl<'a, 'b> Reader<'a, 'b> {
Ok(out)
}
fn functions(mut self) -> Result<Vec<FunctionDecl>, E> {
let (mut out, n) = self.list(Q::Functions, 25)?;
let (mut out, n) = self.list(Q::Functions, 26)?;
for i in 0..n {
self.budget.work(1)?;
let f = (|| {
Ok(FunctionDecl {
lifecycle_role: LifecycleRole::try_from(self.byte()?).map_err(|e| {
e.at(1, self.section.offset + self.pos - 1).in_function(i as u32, None)
})?,
name: self.name()?,
signature: self.signature()?,
code_offset: self.u32()?,
@@ -407,6 +410,7 @@ pub fn encode_registry(registry: &Registry, b: &mut LoadBudget) -> Result<Regist
let functions = write_section(b, |w| {
w.count(d.functions.len())?;
for f in &d.functions {
w.byte(f.lifecycle_role as u8)?;
w.name(&f.name)?;
w.signature(&f.signature)?;
w.u32(f.code_offset)?;
@@ -129,6 +129,7 @@ fn captures_section_has_independent_bytes_and_strict_shape() {
let r = resolve(RegistryDeclarations {
types: vec![builtin(BuiltinId::INT32), builtin(BuiltinId::VEC2)],
functions: vec![FunctionDecl {
lifecycle_role: Default::default(),
code_len: 2,
captures: vec![TypeId(1), TypeId(0)],
..Default::default()
@@ -167,22 +168,22 @@ fn hex(s: &str) -> Vec<u8> {
// Independently specified PBX, not generated by any production serializer.
// Header 32 bytes, eight directory entries (96 bytes), payload starts at 128.
// constants=128/4, functions=132/29, code=161/2, exports=163/4,
// syscalls=167/4, types=171/10, implementations=181/4. Total=193.
// constants=128/4, functions=132/30, code=162/2, exports=164/4,
// syscalls=168/4, types=172/10, implementations=182/4, captures=186/8. Total=194.
fn minimal_bytes() -> Vec<u8> {
hex("
50 42 58 00 01 00 00 00 08 00 00 00
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
00 00 00 00 80 00 00 00 04 00 00 00
01 00 00 00 84 00 00 00 1d 00 00 00
02 00 00 00 a1 00 00 00 02 00 00 00
04 00 00 00 a3 00 00 00 04 00 00 00
05 00 00 00 a7 00 00 00 04 00 00 00
06 00 00 00 ab 00 00 00 0a 00 00 00
07 00 00 00 b5 00 00 00 04 00 00 00
08 00 00 00 b9 00 00 00 08 00 00 00
01 00 00 00 84 00 00 00 1e 00 00 00
02 00 00 00 a2 00 00 00 02 00 00 00
04 00 00 00 a4 00 00 00 04 00 00 00
05 00 00 00 a8 00 00 00 04 00 00 00
06 00 00 00 ac 00 00 00 0a 00 00 00
07 00 00 00 b6 00 00 00 04 00 00 00
08 00 00 00 ba 00 00 00 08 00 00 00
00 00 00 00
01 00 00 00 00 00 00 00 00 00 00 00 00
01 00 00 00 00 00 00 00 00 00 00 00 00 00
00 00 00 00 02 00 00 00 00 00 00 00 00 00 00 00
01 00
00 00 00 00
@@ -194,7 +195,11 @@ fn minimal_bytes() -> Vec<u8> {
fn minimal_registry() -> Registry {
resolve(RegistryDeclarations {
types: vec![builtin(BuiltinId::BOOL)],
functions: vec![FunctionDecl { code_len: 2, ..Default::default() }],
functions: vec![FunctionDecl {
lifecycle_role: Default::default(),
code_len: 2,
..Default::default()
}],
..Default::default()
})
.unwrap()
@@ -225,10 +230,10 @@ fn writer_matches_independent_minimal_envelope() {
let sections = encode_registry(&minimal_registry(), &mut budget()).unwrap();
let bytes = envelope(&sections.types, &sections.functions, &sections.implementations);
assert_eq!(bytes, minimal_bytes());
assert_eq!(bytes.len(), 193);
assert_eq!(bytes.len(), 194);
let mut b = budget();
let env = PbxEnvelope::parse(&bytes, &mut b).unwrap();
assert_eq!(env.section(2).unwrap().offset, 161);
assert_eq!(env.section(2).unwrap().offset, 162);
let registry = env.resolve_registry(&mut b).unwrap();
assert_eq!(registry.declarations(), minimal_registry().declarations());
assert_eq!(b.used(LoadResource::TemporaryBytes), 0);
@@ -499,7 +504,7 @@ fn representative_records_match_fixed_bytes_and_preserve_names_without_debug() {
01 00 00 00 00 00 00 00 01 01 00 00 00 70
01 00 00 00 00 00 00 00");
let functions = hex("
01 00 00 00 01 01 00 00 00 66
01 00 00 00 00 01 01 00 00 00 66
02 00 00 00 01 00 00 00 00 00 00 00 00 01 01 00 00 00 70
01 00 00 00 00 00 00 00
00 00 00 00 02 00 00 00 00 00 00 00 01 00 00 00");
@@ -721,6 +726,7 @@ fn implemented() -> RegistryDeclarations {
},
],
functions: vec![FunctionDecl {
lifecycle_role: Default::default(),
signature: Signature { parameters: vec![named(1), named(0)], results: vec![TypeId(0)] },
code_len: 2,
max_stack_slots: 2,
@@ -1024,7 +1030,7 @@ fn reference_map_probe() {
fn independent_multi_slot_signature_fixture_has_no_serialized_widths() {
// vec2 import; fn(vec2)->vec2; GET_LOCAL 0; GET_LOCAL 1; RET.
let types = hex("01 00 00 00 00 00 02 00 00 00");
let functions=hex("01 00 00 00 00 01 00 00 00 00 00 00 00 00 01 00 00 00 00 00 00 00 00 00 00 00 0e 00 00 00 00 00 00 00 02 00 00 00");
let functions=hex("01 00 00 00 00 00 01 00 00 00 00 00 00 00 00 01 00 00 00 00 00 00 00 00 00 00 00 0e 00 00 00 00 00 00 00 02 00 00 00");
let code = hex("42 00 00 00 00 00 42 00 01 00 00 00 51 00");
let empty = [0; 4];
let bytes = encode_envelope(
@@ -1055,3 +1061,70 @@ fn independent_multi_slot_signature_fixture_has_no_serialized_widths() {
assert_eq!(sections.functions, functions);
assert_eq!(sections.types, types);
}
#[test]
fn lifecycle_roles_resolve_and_roundtrip_with_strict_validation() {
let functions = vec![
FunctionDecl { code_len: 2, ..Default::default() },
FunctionDecl {
lifecycle_role: LifecycleRole::BeforePause,
code_offset: 2,
code_len: 2,
..Default::default()
},
FunctionDecl {
lifecycle_role: LifecycleRole::BeforeResume,
code_offset: 4,
code_len: 2,
..Default::default()
},
];
let declarations = RegistryDeclarations {
types: vec![builtin(BuiltinId::BOOL)],
functions,
..Default::default()
};
let registry = resolve(declarations.clone()).unwrap();
assert_eq!(registry.lifecycle_hook(LifecycleRole::None), None);
assert_eq!(registry.lifecycle_hook(LifecycleRole::BeforePause), Some(FunctionId(1)));
assert_eq!(registry.lifecycle_hook(LifecycleRole::BeforeResume), Some(FunctionId(2)));
let bytes = PbxModule {
registry: &registry,
code: &[1, 0, 1, 0, 1, 0],
constants: &[],
debug: None,
exports: &[],
syscalls: &[],
}
.serialize(&mut budget())
.unwrap();
let parsed = OwnedPbx::parse(&bytes, &mut budget()).unwrap();
assert_eq!(parsed.registry.declarations(), &declarations);
let env = PbxEnvelope::parse(&bytes, &mut budget()).unwrap();
let role_offset = env.section(1).unwrap().offset + 4;
let mut invalid = bytes.clone();
invalid[role_offset] = 255;
let error = OwnedPbx::parse(&invalid, &mut budget()).unwrap_err();
assert_eq!(error.reason, LoadReason::LifecycleRole);
assert_eq!(error.function, Some(0));
assert_eq!(error.offset, Some(role_offset));
for case in 0..5 {
let mut d = declarations.clone();
match case {
0 => d.functions[0].lifecycle_role = LifecycleRole::BeforePause,
1 => d.functions[2].lifecycle_role = LifecycleRole::BeforePause,
2 => d.functions[1].signature.parameters.push(named(0)),
3 => d.functions[1].signature.results.push(TypeId(0)),
_ => d.functions[1].captures.push(TypeId(0)),
}
let error = resolve(d).unwrap_err();
assert_eq!(
error.reason,
if case == 1 {
LoadReason::DuplicateLifecycleRole
} else {
LoadReason::LifecycleSignature
}
);
}
}