From 0af8b2b1fe2e78082919ffdbfe3a8b6bde7e3878 Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Tue, 13 Oct 2026 12:18:18 +0100 Subject: [PATCH] feat(runtime): add optional pause and resume lifecycle hooks --- .../prometeu-bytecode/src/load_limits.rs | 3 + .../console/prometeu-bytecode/src/registry.rs | 53 +++- .../prometeu-bytecode/src/registry_codec.rs | 6 +- .../prometeu-bytecode/tests/registry_v1.rs | 103 ++++++- .../src/firmware/firmware.rs | 258 ++++++++++++++++++ .../firmware/firmware_step_game_running.rs | 9 + .../src/os/facades/lifecycle.rs | 88 ++++++ .../prometeu-system/src/os/facades/vm.rs | 113 +++++++- .../src/services/vm_runtime/tests.rs | 1 + .../src/services/vm_runtime/tick.rs | 52 +++- .../src/services/vm_session.rs | 23 ++ .../prometeu-vm/src/program_image/tests.rs | 1 + .../src/registry_verifier/tests.rs | 102 ++++++- .../src/registry_verifier/types/tests.rs | 1 + .../prometeu-vm/src/virtual_machine.rs | 55 +++- .../src/virtual_machine/lifecycle.rs | 109 ++++++++ .../prometeu-vm/src/virtual_machine/loader.rs | 3 + .../src/virtual_machine/runtime.rs | 19 +- .../src/virtual_machine/typed_tests.rs | 169 ++++++++++++ .../prometeu-vm/tests/producer_handoff.rs | 1 + .../prometeu-vm/tests/registry_conformance.rs | 26 +- .../prometeu-vm/tests/support/callables.rs | 1 + .../prometeu-vm/tests/support/collections.rs | 1 + .../prometeu-vm/tests/support/random.rs | 1 + .../dev/prometeu-test-support/src/program.rs | 1 + .../benches/temporal.rs | 1 + .../src/automation/wire/fault_tests.rs | 14 +- .../host/prometeu-host-headless/src/host.rs | 1 + .../tests/deterministic_control.rs | 1 + crates/tools/pbxgen-dummy-boy/src/lib.rs | 1 + crates/tools/pbxgen-stress/src/lib.rs | 1 + .../prometeu-cli/tests/automation_process.rs | 1 + ...ycle-calls-retain-the-game-continuation.md | 111 ++++++++ .../02b-vm-function-values-and-closures.md | 24 +- .../02c-program-registry-and-pbx-v1.md | 25 +- .../runtime/09-events-and-concurrency.md | 19 +- ...a-coroutines-and-cooperative-scheduling.md | 53 +++- test-cartridges/dummy-boy/program.pbx | Bin 475 -> 476 bytes test-cartridges/stress-console/program.pbx | Bin 1232 -> 1233 bytes 39 files changed, 1381 insertions(+), 70 deletions(-) create mode 100644 crates/console/prometeu-vm/src/virtual_machine/lifecycle.rs create mode 100644 discussion/lessons/DSC-0062-guest-lifecycle-pause-and-resume-api/LSN-0066-lifecycle-calls-retain-the-game-continuation.md diff --git a/crates/console/prometeu-bytecode/src/load_limits.rs b/crates/console/prometeu-bytecode/src/load_limits.rs index 3f4a923..d446921 100644 --- a/crates/console/prometeu-bytecode/src/load_limits.rs +++ b/crates/console/prometeu-bytecode/src/load_limits.rs @@ -37,6 +37,9 @@ impl LoadCode { } #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] pub enum LoadReason { + LifecycleRole, + LifecycleSignature, + DuplicateLifecycleRole, Magic, Version, Endianness, diff --git a/crates/console/prometeu-bytecode/src/registry.rs b/crates/console/prometeu-bytecode/src/registry.rs index 4aa7ba2..a91577e 100644 --- a/crates/console/prometeu-bytecode/src/registry.rs +++ b/crates/console/prometeu-bytecode/src/registry.rs @@ -57,8 +57,30 @@ pub struct TypeDecl { pub name: Option, 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 for LifecycleRole { + type Error = E; + fn try_from(value: u8) -> Result { + 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, pub signature: Signature, pub code_offset: u32, @@ -232,6 +254,7 @@ pub struct FunctionLayout { #[derive(Debug)] pub struct Registry { + lifecycle_hooks: [Option; 2], declarations: RegistryDeclarations, layouts: Vec, functions: Vec, @@ -239,6 +262,13 @@ pub struct Registry { implementations: Vec<(TypeId, TypeId, ImplementationId)>, } impl Registry { + pub fn lifecycle_hook(&self, role: LifecycleRole) -> Option { + 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 { diff --git a/crates/console/prometeu-bytecode/src/registry_codec.rs b/crates/console/prometeu-bytecode/src/registry_codec.rs index de82859..a6a41a5 100644 --- a/crates/console/prometeu-bytecode/src/registry_codec.rs +++ b/crates/console/prometeu-bytecode/src/registry_codec.rs @@ -249,11 +249,14 @@ impl<'a, 'b> Reader<'a, 'b> { Ok(out) } fn functions(mut self) -> Result, 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 Vec { // 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 { 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 { 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(§ions.types, §ions.functions, §ions.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: ®istry, + 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 + } + ); + } +} diff --git a/crates/console/prometeu-firmware/src/firmware/firmware.rs b/crates/console/prometeu-firmware/src/firmware/firmware.rs index 1336afa..4587c4d 100644 --- a/crates/console/prometeu-firmware/src/firmware/firmware.rs +++ b/crates/console/prometeu-firmware/src/firmware/firmware.rs @@ -83,6 +83,40 @@ impl Firmware { self.state_initialized = true; } + // Hooks run after leaving gameplay and before completing OS suspension/resume. + if let Some((task_id, result)) = self.os.vm().poll_pending_lifecycle(platform) { + if let Err(report) = result { + let _ = self.os.lifecycle().crash_task(task_id, Some(&report)); + self.change_state( + FirmwareState::AppCrashes(crate::firmware::firmware_state::AppCrashesStep { + report, + }), + effective_signals, + platform, + ); + } else if matches!(self.state, FirmwareState::GameRunning(_)) + && matches!( + self.os.lifecycle().task_state(task_id), + Some( + prometeu_system::task::TaskState::Suspended + | prometeu_system::task::TaskState::Closed + ) + ) + { + self.os.vm().transition_render_owner(AppMode::Shell, 0); + let state = match self.os.lifecycle().foreground_owner() { + prometeu_system::ForegroundOwner::Shell(task_id) => { + FirmwareState::ShellRunning( + crate::firmware::firmware_state::ShellRunningStep::new(task_id), + ) + } + _ => FirmwareState::HubHome(crate::firmware::firmware_state::HubHomeStep), + }; + self.change_state(state, effective_signals, platform); + } + return; + } + // 3. Update the current state and check for transitions. if let Some(next_state) = self.on_update(effective_signals, platform) { self.change_state(next_state, effective_signals, platform); @@ -352,6 +386,7 @@ mod tests { TestProgram { const_pool: vec![], functions: vec![FunctionDecl { + lifecycle_role: Default::default(), code_offset: 0, code_len: code.len() as u32, @@ -392,6 +427,7 @@ mod tests { let program = TestProgram { const_pool: vec![], functions: vec![FunctionDecl { + lifecycle_role: Default::default(), code_offset: 0, code_len: code.len() as u32, @@ -1714,4 +1750,226 @@ mod tests { assert!(matches!(firmware.state, FirmwareState::GameRunning(_))); assert_eq!(firmware.os.vm().current_cartridge_title(), "Valid Cart"); } + fn lifecycle_cartridge(pause: &str, resume: &str) -> Cartridge { + use prometeu_bytecode::registry::LifecycleRole; + let mut program = TestProgram::single( + assemble("FRAME_SYNC\nJMP 0").unwrap(), + int64_signature(0, 0), + 0, + 8, + ); + for (role, source) in + [(LifecycleRole::BeforePause, pause), (LifecycleRole::BeforeResume, resume)] + { + if source.is_empty() { + continue; + } + let code = assemble(source).unwrap(); + program.functions.push(FunctionDecl { + lifecycle_role: role, + code_offset: program.code.len() as u32, + code_len: code.len() as u32, + max_stack_slots: 8, + ..Default::default() + }); + program.code.extend(code); + } + let mut cartridge = valid_cartridge(AppMode::Game); + cartridge.program = program.serialize(); + cartridge + } + + fn load_lifecycle(pause: &str, resume: &str) -> (Firmware, TestPlatform, TaskId) { + let mut firmware = Firmware::new(None); + let mut platform = TestPlatform::new(); + firmware.load_cartridge(lifecycle_cartridge(pause, resume)); + firmware.tick(&InputSignals::default(), &mut platform); + let task = firmware.os.lifecycle().resident_game_task().unwrap(); + (firmware, platform, task) + } + + #[test] + fn lifecycle_home_resume_callbacks_are_outside_frames_and_preserve_pc() { + let (mut fw, mut platform, task) = load_lifecycle("RET", "RET"); + let signals = InputSignals::default(); + assert!(!fw.os.lifecycle().advance_game_pause_budget(task).unwrap()); + assert!(fw.os.vm().poll_pending_lifecycle(&mut platform).is_none()); + fw.request_home_from_host(); + fw.tick(&signals, &mut platform); // existing handoff tick + let pc = fw.os.vm().active_pc(); + let ticks = vm_session_tick_index(&mut fw, task); + let frames = fw.os.vm().completed_logical_frames(); + assert_eq!(fw.os.lifecycle().task_state(task), Some(TaskState::Foreground)); + fw.tick(&signals, &mut platform); // BeforePause only + assert_eq!(fw.os.lifecycle().task_state(task), Some(TaskState::Suspended)); + assert_eq!(fw.os.vm().active_pc(), pc); + assert_eq!(vm_session_tick_index(&mut fw, task), ticks); + assert!(fw.resume_resident_game_from_home()); + fw.tick(&signals, &mut platform); // BeforeResume only + assert_eq!(fw.os.vm().active_pc(), pc); + assert_eq!(vm_session_tick_index(&mut fw, task), ticks); + assert_eq!(fw.os.vm().completed_logical_frames(), frames); + assert_eq!(fw.os.lifecycle().resident_game().unwrap().state, ResidentGameState::Foreground); + fw.tick(&signals, &mut platform); + assert_eq!(vm_session_tick_index(&mut fw, task), ticks + 1); + } + + #[test] + fn lifecycle_direct_suspend_and_shell_handoff_wait_for_callback() { + let (mut fw, mut platform, task) = load_lifecycle("RET", "RET"); + fw.os.lifecycle().suspend_task(task).unwrap(); + assert_eq!(fw.os.lifecycle().task_state(task), Some(TaskState::Foreground)); + fw.tick(&InputSignals::default(), &mut platform); + assert_eq!(fw.os.lifecycle().task_state(task), Some(TaskState::Suspended)); + assert!(fw.resume_resident_game_from_home()); + fw.tick(&InputSignals::default(), &mut platform); + let shell = fw.os.sessions().try_create_native_shell_task(99, "Tools").unwrap(); + assert_eq!(fw.os.lifecycle().foreground_owner(), ForegroundOwner::Game(task)); + fw.tick(&InputSignals::default(), &mut platform); + assert_eq!(fw.os.lifecycle().foreground_owner(), ForegroundOwner::Shell(shell)); + assert_eq!(fw.os.lifecycle().task_state(task), Some(TaskState::Suspended)); + } + + #[test] + fn lifecycle_debugger_retains_budget_and_steps_without_game_frames() { + let (mut fw, mut platform, task) = load_lifecycle("PUSH_I32 7\nSET_GLOBAL 0\nRET", "RET"); + fw.os.lifecycle().suspend_task(task).unwrap(); + let offset = assemble("FRAME_SYNC\nJMP 0").unwrap().len(); + fw.os.vm().insert_active_breakpoint(offset); + fw.tick(&InputSignals::default(), &mut platform); + assert!(fw.os.vm().paused()); + assert_eq!(fw.os.lifecycle().task_state(task), Some(TaskState::Foreground)); + let remaining = + fw.os.sessions().vm_session_for_task(task).unwrap().vm.lifecycle_remaining_cycles(); + fw.tick(&InputSignals::default(), &mut platform); + assert_eq!( + fw.os.sessions().vm_session_for_task(task).unwrap().vm.lifecycle_remaining_cycles(), + remaining + ); + for _ in 0..3 { + assert!(fw.os.vm().debug_step_active_session(&mut platform).is_none()); + } + assert_eq!(fw.os.lifecycle().task_state(task), Some(TaskState::Suspended)); + assert_eq!(vm_session_tick_index(&mut fw, task), 0); + } + + #[test] + fn lifecycle_faults_exhaustion_and_halt_never_resume_gameplay() { + for body in ["FRAME_SYNC\nRET", "JMP 0", "HALT"] { + let (mut fw, mut platform, task) = load_lifecycle(body, "RET"); + fw.os.lifecycle().suspend_task(task).unwrap(); + for _ in 0..8 { + fw.tick(&InputSignals::default(), &mut platform); + if fw.os.lifecycle().task_state(task) != Some(TaskState::Foreground) { + break; + } + } + if body == "HALT" { + assert_eq!(fw.os.lifecycle().task_state(task), Some(TaskState::Closed)); + assert!(matches!(fw.state, FirmwareState::HubHome(_))); + } else { + assert_eq!(fw.os.lifecycle().task_state(task), Some(TaskState::Crashed)); + let FirmwareState::AppCrashes(step) = &fw.state else { panic!("expected crash") }; + assert!(step.report.to_string().contains("BeforePause")); + } + assert_eq!(vm_session_tick_index(&mut fw, task), 0); + } + } + #[test] + fn lifecycle_debugger_hostcalls_use_real_session_handles() { + use prometeu_bytecode::registry::LifecycleRole; + let main = assemble("FRAME_SYNC\nJMP 0").unwrap(); + let mut program = TestProgram::single(main, int64_signature(0, 0), 0, 8); + let hook = + assemble("PUSH_CONST 0\nHOSTCALL 0\nPOP_N 1\nPUSH_I32 42\nHOSTCALL 1\nRET").unwrap(); + program + .const_pool + .push(prometeu_bytecode::model::ConstantPoolEntry::String("/missing".into())); + program.syscalls.push(SyscallDecl { + module: "fs".into(), + name: "open".into(), + version: 1, + arg_slots: 1, + ret_slots: 1, + }); + program.functions.push(FunctionDecl { + lifecycle_role: LifecycleRole::BeforePause, + code_offset: program.code.len() as u32, + code_len: hook.len() as u32, + max_stack_slots: 8, + ..Default::default() + }); + program.code.extend(hook); + program.syscalls.push(SyscallDecl { + module: "fs".into(), + name: "close".into(), + version: 1, + arg_slots: 1, + ret_slots: 0, + }); + let mut cartridge = valid_cartridge(AppMode::Game); + cartridge.capabilities = caps::FS; + cartridge.program = program.serialize(); + let mut fw = Firmware::new(None); + let mut platform = TestPlatform::new(); + fw.load_cartridge(cartridge); + fw.tick(&InputSignals::default(), &mut platform); + let task = fw.os.lifecycle().resident_game_task().unwrap(); + fw.os + .sessions() + .vm_session_for_task_mut(task) + .unwrap() + .open_files + .insert(42, "/save".into()); + fw.os.lifecycle().suspend_task(task).unwrap(); + fw.os.vm().set_paused(true); + assert_eq!( + fw.os.sessions().vm_session_for_task(task).unwrap().fs_state, + prometeu_system::fs::FsState::Unmounted + ); + // fs.open returns an ordinary error value on this unmounted session. + for _ in 0..6 { + assert!(fw.os.vm().debug_step_active_session(&mut platform).is_none()); + } + assert!(fw.os.sessions().vm_session_for_task(task).unwrap().open_files.is_empty()); + let pc = fw.os.vm().active_pc(); + assert!(fw.os.vm().debug_step_active_session(&mut platform).is_none()); + assert_eq!(fw.os.vm().active_pc(), pc); + assert!(fw.os.vm().tick_session(task, &InputSignals::default(), &mut platform).is_none()); + assert_eq!(fw.os.vm().active_pc(), pc); + fw.tick(&InputSignals::default(), &mut platform); + assert!(matches!(fw.state, FirmwareState::HubHome(_))); + assert_eq!(vm_session_tick_index(&mut fw, task), 0); + } + + #[test] + fn lifecycle_resume_failure_blocks_gameplay_and_conflicting_pause_request() { + let (mut fw, mut platform, task) = load_lifecycle("RET", "FRAME_SYNC\nRET"); + fw.os.lifecycle().suspend_task(task).unwrap(); + fw.tick(&InputSignals::default(), &mut platform); + assert!(fw.resume_resident_game_from_home()); + assert!(fw.os.lifecycle().request_home_from_game(task).is_err()); + assert!(fw.os.lifecycle().suspend_task(task).is_err()); + fw.tick(&InputSignals::default(), &mut platform); + let FirmwareState::AppCrashes(step) = &fw.state else { panic!("expected failure") }; + assert!(step.report.to_string().contains("BeforeResume")); + assert_eq!(vm_session_tick_index(&mut fw, task), 0); + } + #[test] + fn lifecycle_roles_are_independently_optional() { + for (pause, resume) in [("", "RET"), ("RET", "")] { + let (mut fw, mut platform, task) = load_lifecycle(pause, resume); + fw.request_home_from_host(); + for _ in 0..2 { + fw.tick(&InputSignals::default(), &mut platform); + } + assert_eq!(fw.os.lifecycle().task_state(task), Some(TaskState::Suspended)); + assert!(fw.resume_resident_game_from_home()); + fw.tick(&InputSignals::default(), &mut platform); + assert_eq!( + fw.os.lifecycle().resident_game().unwrap().state, + ResidentGameState::Foreground + ); + } + } } diff --git a/crates/console/prometeu-firmware/src/firmware/firmware_step_game_running.rs b/crates/console/prometeu-firmware/src/firmware/firmware_step_game_running.rs index 677ea2e..d04d9c1 100644 --- a/crates/console/prometeu-firmware/src/firmware/firmware_step_game_running.rs +++ b/crates/console/prometeu-firmware/src/firmware/firmware_step_game_running.rs @@ -27,6 +27,15 @@ impl GameRunningStep { return Some(FirmwareState::AppCrashes(AppCrashesStep { report })); }; + if matches!(task_state, TaskState::Suspended | TaskState::Closed) { + ctx.os.vm().transition_render_owner(AppMode::Shell, 0); + return Some(match ctx.os.lifecycle().foreground_owner() { + prometeu_system::ForegroundOwner::Shell(task_id) => FirmwareState::ShellRunning( + crate::firmware::firmware_state::ShellRunningStep::new(task_id), + ), + _ => FirmwareState::HubHome(HubHomeStep), + }); + } if task_state != TaskState::Foreground { // TODO: is it panic? let report = CrashReport::VmPanic { diff --git a/crates/console/prometeu-system/src/os/facades/lifecycle.rs b/crates/console/prometeu-system/src/os/facades/lifecycle.rs index b7f6d06..0f647f8 100644 --- a/crates/console/prometeu-system/src/os/facades/lifecycle.rs +++ b/crates/console/prometeu-system/src/os/facades/lifecycle.rs @@ -9,6 +9,7 @@ use crate::services::foreground::{ ForegroundOwner, ForegroundStackError, ResidentGame, ResidentGameState, }; use crate::task::{TaskId, TaskKind, TaskState}; +use crate::vm_session::LifecycleTransition; pub struct LifecycleFacade<'a> { pub(in crate::os) os: &'a mut SystemOS, @@ -45,6 +46,27 @@ impl<'a> LifecycleFacade<'a> { }); } + if self + .os + .vm_sessions + .for_task(task_id) + .is_some_and(|session| session.lifecycle_transition.is_some()) + { + return Err(LifecycleError::InvalidTransition { + task_id, + from: self.task_state(task_id).unwrap_or(TaskState::Closed), + operation: LifecycleOperation::SetForeground, + }); + } + if self.task_state(task_id) == Some(TaskState::Suspended) + && self.os.vm_sessions.for_task(task_id).is_some_and(|session| { + session + .vm + .has_lifecycle_hook(prometeu_bytecode::registry::LifecycleRole::BeforeResume) + }) + { + return self.resume_task(task_id); + } self.os.foreground_stack.set_game_foreground(task_id).map_err(map_foreground_error)?; self.os.task_manager.set_foreground(task_id); self.os.process_manager.mark_running(process_id); @@ -67,6 +89,9 @@ impl<'a> LifecycleFacade<'a> { && game_task_id != task_id && self.task_state(game_task_id) != Some(TaskState::Suspended) { + if self.defer_pause(game_task_id, LifecycleTransition::PauseToShell(task_id))? { + return Ok(()); + } let game_process_id = process_id_for_task(self.os, game_task_id)?; self.os.task_manager.mark_suspended(game_task_id); self.os.process_manager.mark_suspended(game_process_id); @@ -93,6 +118,19 @@ impl<'a> LifecycleFacade<'a> { pub fn request_home_from_game(&mut self, task_id: TaskId) -> Result<(), LifecycleError> { let _process_id = process_id_for_task(self.os, task_id)?; + if let Some(pending) = + self.os.vm_sessions.for_task(task_id).and_then(|s| s.lifecycle_transition) + { + return if pending == LifecycleTransition::PauseToHub { + Ok(()) + } else { + Err(LifecycleError::InvalidTransition { + task_id, + from: self.task_state(task_id).unwrap_or(TaskState::Closed), + operation: LifecycleOperation::Suspend, + }) + }; + } let previous = self.os.foreground_stack.resident_game(); self.os @@ -113,6 +151,13 @@ impl<'a> LifecycleFacade<'a> { } pub fn advance_game_pause_budget(&mut self, task_id: TaskId) -> Result { + if self.os.foreground_stack.resident_game().is_some_and(|game| { + game.task_id == task_id + && game.state == ResidentGameState::PauseRequested { remaining_ticks: 1 } + }) && self.defer_pause(task_id, LifecycleTransition::PauseToHub)? + { + return Ok(false); + } let expired = self.os.foreground_stack.advance_pause_budget(task_id).map_err(map_foreground_error)?; @@ -125,6 +170,34 @@ impl<'a> LifecycleFacade<'a> { Ok(expired) } + fn defer_pause( + &mut self, + task_id: TaskId, + transition: LifecycleTransition, + ) -> Result { + let state = self.task_state(task_id).unwrap_or(TaskState::Closed); + let Some(session) = self.os.vm_sessions.for_task_mut(task_id) else { + return Ok(false); + }; + if let Some(pending) = session.lifecycle_transition { + return if pending == transition { + Ok(true) + } else { + Err(LifecycleError::InvalidTransition { + task_id, + from: state, + operation: LifecycleOperation::Suspend, + }) + }; + } + if session.pause_hook_complete || !session.vm.has_lifecycle_hook(transition.role()) { + return Ok(false); + } + session.lifecycle_transition = Some(transition); + session.lifecycle_started = false; + Ok(true) + } + pub fn pending_game_lifecycle_events(&self) -> &[GameLifecycleEvent] { &self.os.game_lifecycle_events } @@ -141,6 +214,11 @@ impl<'a> LifecycleFacade<'a> { pub fn suspend_task(&mut self, task_id: TaskId) -> Result<(), LifecycleError> { let process_id = process_id_for_task(self.os, task_id)?; + if task_kind_for_task(self.os, task_id)? == TaskKind::Game + && self.defer_pause(task_id, LifecycleTransition::PauseToHub)? + { + return Ok(()); + } self.os.task_manager.mark_suspended(task_id); self.os.process_manager.mark_suspended(process_id); match self.os.foreground_stack.owner() { @@ -189,6 +267,16 @@ impl<'a> LifecycleFacade<'a> { task_id, kind: GameLifecycleEventKind::ResumeForeground, }); + if let Some(session) = self.os.vm_sessions.for_task_mut(task_id) { + session.pause_hook_complete = false; + if session.vm.has_lifecycle_hook( + prometeu_bytecode::registry::LifecycleRole::BeforeResume, + ) { + session.lifecycle_transition = Some(LifecycleTransition::Resume); + session.lifecycle_started = false; + return Ok(()); + } + } self.os .foreground_stack .complete_resume_game(task_id) diff --git a/crates/console/prometeu-system/src/os/facades/vm.rs b/crates/console/prometeu-system/src/os/facades/vm.rs index 31d6c53..1750daa 100644 --- a/crates/console/prometeu-system/src/os/facades/vm.rs +++ b/crates/console/prometeu-system/src/os/facades/vm.rs @@ -1,7 +1,7 @@ use crate::CrashReport; use crate::os::{GameLifecycleEvent, SystemOS}; use crate::task::TaskId; -use crate::vm_session::VmSession; +use crate::vm_session::{LifecycleTransition, VmSession}; use crate::{RenderWorkerConfig, RenderWorkerController}; use prometeu_hal::app_mode::AppMode; use prometeu_hal::telemetry::{CertificationConfig, TelemetryFrame}; @@ -9,6 +9,7 @@ use prometeu_hal::{ FrameId, InputSignals, RenderOwnership, RenderWorkerBackend, RenderWorkerError, RenderWorkerFrameSink, RuntimePlatform, }; +use prometeu_vm::LogicalFrameEndingReason; use std::sync::atomic::Ordering; pub struct VmFacade<'a> { @@ -22,6 +23,12 @@ impl<'a> VmFacade<'a> { signals: &InputSignals, platform: &mut dyn RuntimePlatform, ) -> Option { + if self.os.lifecycle().task_state(task_id) != Some(crate::task::TaskState::Foreground) { + return None; + } + if self.os.vm_sessions.for_task(task_id).is_some_and(|s| s.lifecycle_transition.is_some()) { + return self.drive_lifecycle(task_id, platform, false).err(); + } self.deliver_pending_game_lifecycle_events_to_session(task_id); let Some(session) = self.os.vm_sessions.for_task_mut(task_id) else { @@ -44,6 +51,104 @@ impl<'a> VmFacade<'a> { ) } + /// Firmware polls this before dispatching ordinary Game/Shell updates. + pub fn poll_pending_lifecycle( + &mut self, + platform: &mut dyn RuntimePlatform, + ) -> Option<(TaskId, Result<(), CrashReport>)> { + let task_id = self.os.foreground_stack.resident_game_task()?; + self.os.vm_sessions.for_task(task_id)?.lifecycle_transition?; + Some((task_id, self.drive_lifecycle(task_id, platform, false))) + } + + fn drive_lifecycle( + &mut self, + task_id: TaskId, + platform: &mut dyn RuntimePlatform, + single_step: bool, + ) -> Result<(), CrashReport> { + self.deliver_pending_game_lifecycle_events_to_session(task_id); + let session = self.os.vm_sessions.for_task_mut(task_id).expect("pending lifecycle session"); + let transition = session.lifecycle_transition.expect("pending lifecycle transition"); + let role = transition.role(); + // A fatal hook remains failed even if a caller tries to tick the same session again. + if let Some(report) = &session.runtime.last_crash_report { + return Err(report.clone()); + } + let reason = if !session.lifecycle_started { + session.lifecycle_started = true; + match session.vm.begin_lifecycle(role) { + Ok(true) => None, + Ok(false) => Some(LogicalFrameEndingReason::LifecycleComplete), + Err(error) => Some(LogicalFrameEndingReason::Panic(format!("{error:?}"))), + } + } else { + None + }; + let reason = reason.unwrap_or_else(|| { + session.runtime.tick_lifecycle( + &mut self.os.log_service, + &mut self.os.fs, + &mut session.fs_state, + &mut self.os.memcard, + &mut session.open_files, + &mut session.next_handle, + &mut session.vm, + platform, + single_step, + ) + }); + match reason { + LogicalFrameEndingReason::BudgetExhausted | LogicalFrameEndingReason::Breakpoint => { + Ok(()) + } + LogicalFrameEndingReason::LifecycleComplete => { + session.lifecycle_transition = None; + session.lifecycle_started = false; + match transition { + LifecycleTransition::PauseToHub => { + session.pause_hook_complete = true; + self.os.lifecycle().suspend_task(task_id).expect("validated suspension"); + } + LifecycleTransition::PauseToShell(shell) => { + session.pause_hook_complete = true; + self.os + .lifecycle() + .set_shell_foreground_task(shell) + .expect("validated Shell transition"); + } + LifecycleTransition::Resume => { + self.os + .foreground_stack + .complete_resume_game(task_id) + .expect("validated resume"); + } + } + Ok(()) + } + LogicalFrameEndingReason::Halted => { + // HALT ends the session; it must never restore or resume gameplay. + session.lifecycle_transition = None; + self.os.lifecycle().close_task(task_id).expect("validated task"); + Ok(()) + } + failure => { + let report = match failure { + LogicalFrameEndingReason::Trap(mut trap) => { + trap.message = format!("{role:?}: {}", trap.message); + CrashReport::VmTrap { trap } + } + other => CrashReport::VmPanic { + message: format!("{role:?} lifecycle failed: {other:?}"), + pc: Some(session.vm.pc() as u32), + }, + }; + session.runtime.last_crash_report = Some(report.clone()); + Err(report) + } + } + } + fn deliver_pending_game_lifecycle_events_to_session(&mut self, task_id: TaskId) { let Some(session) = self.os.vm_sessions.for_task(task_id) else { return; @@ -85,6 +190,12 @@ impl<'a> VmFacade<'a> { pc: None, }); }; + if self.os.lifecycle().task_state(task_id) != Some(crate::task::TaskState::Foreground) { + return None; + } + if self.os.vm_sessions.for_task(task_id).is_some_and(|s| s.lifecycle_transition.is_some()) { + return self.drive_lifecycle(task_id, platform, true).err(); + } let Some(session) = self.os.vm_sessions.for_task_mut(task_id) else { return Some(CrashReport::VmPanic { message: format!("active debug task {:?} has no VM session", task_id), diff --git a/crates/console/prometeu-system/src/services/vm_runtime/tests.rs b/crates/console/prometeu-system/src/services/vm_runtime/tests.rs index 83f4338..222999e 100644 --- a/crates/console/prometeu-system/src/services/vm_runtime/tests.rs +++ b/crates/console/prometeu-system/src/services/vm_runtime/tests.rs @@ -101,6 +101,7 @@ fn serialized_single_function_module_with_consts( TestProgram { const_pool, functions: vec![FunctionDecl { + lifecycle_role: Default::default(), code_offset: 0, code_len: code.len() as u32, diff --git a/crates/console/prometeu-system/src/services/vm_runtime/tick.rs b/crates/console/prometeu-system/src/services/vm_runtime/tick.rs index 64736a8..1bf34e6 100644 --- a/crates/console/prometeu-system/src/services/vm_runtime/tick.rs +++ b/crates/console/prometeu-system/src/services/vm_runtime/tick.rs @@ -105,7 +105,8 @@ impl VirtualMachineRuntime { match step_result { Ok(()) | Err( - LogicalFrameEndingReason::FrameSync + LogicalFrameEndingReason::LifecycleComplete + | LogicalFrameEndingReason::FrameSync | LogicalFrameEndingReason::BudgetExhausted | LogicalFrameEndingReason::Halted | LogicalFrameEndingReason::EndOfRom @@ -138,6 +139,55 @@ impl VirtualMachineRuntime { } } + /// Uses the session's real services, outside logical-frame accounting. + #[allow(clippy::too_many_arguments)] + pub(crate) fn tick_lifecycle( + &mut self, + log_service: &mut LogService, + fs: &mut VirtualFS, + fs_state: &mut FsState, + memcard: &mut MemcardService, + open_files: &mut HashMap, + next_handle: &mut u32, + vm: &mut VirtualMachine, + platform: &mut dyn RuntimePlatform, + single_step: bool, + ) -> LogicalFrameEndingReason { + if self.paused && !single_step && !self.debug_step_request { + return LogicalFrameEndingReason::Breakpoint; + } + let result = catch_unwind(AssertUnwindSafe(|| { + let mut ctx = HostContext::new_platform(Some(platform)); + let mut host = VmRuntimeHost { + runtime: self, + log_service, + fs, + fs_state, + memcard, + open_files, + next_handle, + }; + if single_step { + vm.step(&mut host, &mut ctx) + .err() + .unwrap_or(LogicalFrameEndingReason::BudgetExhausted) + } else { + vm.run_budget(VirtualMachine::LIFECYCLE_SLICE, &mut host, &mut ctx) + .map(|report| report.reason) + .unwrap_or_else(LogicalFrameEndingReason::Panic) + } + })); + let reason = result.unwrap_or_else(|payload| { + LogicalFrameEndingReason::Panic(Self::host_panic_payload_to_string(payload)) + }); + if reason == LogicalFrameEndingReason::Breakpoint || single_step || self.debug_step_request + { + self.paused = true; + self.debug_step_request = false; + } + reason + } + #[allow(clippy::too_many_arguments)] pub fn tick( &mut self, diff --git a/crates/console/prometeu-system/src/services/vm_session.rs b/crates/console/prometeu-system/src/services/vm_session.rs index ffd1dbb..de8076a 100644 --- a/crates/console/prometeu-system/src/services/vm_session.rs +++ b/crates/console/prometeu-system/src/services/vm_session.rs @@ -20,7 +20,27 @@ pub enum VmSessionError { ProcessIsNotVmBacked(ProcessId), } +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub(crate) enum LifecycleTransition { + PauseToHub, + PauseToShell(TaskId), + Resume, +} + +impl LifecycleTransition { + pub(crate) fn role(self) -> prometeu_bytecode::registry::LifecycleRole { + use prometeu_bytecode::registry::LifecycleRole; + match self { + Self::Resume => LifecycleRole::BeforeResume, + _ => LifecycleRole::BeforePause, + } + } +} + pub struct VmSession { + pub(crate) lifecycle_transition: Option, + pub(crate) lifecycle_started: bool, + pub(crate) pause_hook_complete: bool, pub id: VmSessionId, pub task_id: TaskId, pub process_id: ProcessId, @@ -45,6 +65,9 @@ impl VmSession { logs_count: Arc, ) -> Self { Self { + lifecycle_transition: None, + lifecycle_started: false, + pause_hook_complete: false, id: VmSessionId(task.id), task_id: task.id, process_id: process.id, diff --git a/crates/console/prometeu-vm/src/program_image/tests.rs b/crates/console/prometeu-vm/src/program_image/tests.rs index 2b03daf..edb3ae3 100644 --- a/crates/console/prometeu-vm/src/program_image/tests.rs +++ b/crates/console/prometeu-vm/src/program_image/tests.rs @@ -25,6 +25,7 @@ fn fixture( kind: TypeKind::Builtin(BuiltinId::BOOL), }], functions: vec![FunctionDecl { + lifecycle_role: Default::default(), name: Some("boot".into()), code_len: code.len() as u32, max_stack_slots: max, diff --git a/crates/console/prometeu-vm/src/registry_verifier/tests.rs b/crates/console/prometeu-vm/src/registry_verifier/tests.rs index 45ddd5b..3bbf1b4 100644 --- a/crates/console/prometeu-vm/src/registry_verifier/tests.rs +++ b/crates/console/prometeu-vm/src/registry_verifier/tests.rs @@ -38,7 +38,12 @@ fn registry(code: &[u8], functions: Vec) -> Registry { .unwrap() } fn function(code: &[u8]) -> FunctionDecl { - FunctionDecl { code_len: code.len() as u32, max_stack_slots: 4, ..Default::default() } + FunctionDecl { + lifecycle_role: Default::default(), + code_len: code.len() as u32, + max_stack_slots: 4, + ..Default::default() + } } fn check(code: &[u8], registry: &Registry) -> Result<(), E> { validate_registry_instructions(code, registry, 1, &mut LoadBudget::new(Default::default())) @@ -53,7 +58,14 @@ fn stack_analysis_honors_literal_zero_and_wide_pop_operands() { let mut code = vec![]; arg(&mut code, Op::PushI32, 0); op(&mut code, Op::Halt); - let r = registry(&code, vec![FunctionDecl { max_stack_slots: 0, ..function(&code) }]); + let r = registry( + &code, + vec![FunctionDecl { + lifecycle_role: Default::default(), + max_stack_slots: 0, + ..function(&code) + }], + ); let e = stacks(&code, &r).unwrap_err(); assert_eq!( (e.reason, e.requested, e.limit, e.pc), @@ -78,6 +90,7 @@ fn stack_analysis_cannot_consume_parameters_or_extra_locals_as_temporaries() { let r = registry( &code, vec![FunctionDecl { + lifecycle_role: Default::default(), local_slots: 100, signature: Signature { parameters: vec![NamedType { type_id: TypeId(1), name: None }], @@ -112,8 +125,14 @@ fn stack_analysis_resolves_multislot_calls_and_registry_operations() { let r = registry( &code, vec![ - FunctionDecl { code_len: callee as u32, max_stack_slots: 2, ..function(&code) }, FunctionDecl { + lifecycle_role: Default::default(), + code_len: callee as u32, + max_stack_slots: 2, + ..function(&code) + }, + FunctionDecl { + lifecycle_role: Default::default(), code_offset: callee as u32, code_len: (code.len() - callee) as u32, signature, @@ -136,6 +155,7 @@ fn stack_analysis_checks_returns_empty_bodies_and_implicit_end_branches() { op(&mut code, operation); } let f = FunctionDecl { + lifecycle_role: Default::default(), signature: Signature { parameters: vec![], results: vec![TypeId(0)] }, ..function(&code) }; @@ -172,7 +192,14 @@ fn stack_analysis_rejects_different_join_heights_and_accepts_a_bounded_loop() { assert_eq!(stacks(&code, &r).unwrap_err().reason, R::StackJoin); let mut code = vec![]; arg(&mut code, Op::Jmp, 0); - let r = registry(&code, vec![FunctionDecl { max_stack_slots: 0, ..function(&code) }]); + let r = registry( + &code, + vec![FunctionDecl { + lifecycle_role: Default::default(), + max_stack_slots: 0, + ..function(&code) + }], + ); assert!(stacks(&code, &r).is_ok()); } @@ -181,7 +208,14 @@ fn stack_analysis_accounts_only_reachable_transfers_but_preflights_dead_operands let mut code = vec![]; op(&mut code, Op::Halt); arg(&mut code, Op::PopN, u32::MAX); - let r = registry(&code, vec![FunctionDecl { max_stack_slots: 0, ..function(&code) }]); + let r = registry( + &code, + vec![FunctionDecl { + lifecycle_role: Default::default(), + max_stack_slots: 0, + ..function(&code) + }], + ); assert!(stacks(&code, &r).is_ok()); let mut code = vec![]; op(&mut code, Op::Halt); @@ -220,7 +254,12 @@ fn stack_analysis_straight_line_storage_is_bounded_by_blocks_not_instruction_fra op(&mut code, Op::Halt); let r = registry( &code, - vec![FunctionDecl { local_slots: 300, max_stack_slots: 0, ..function(&code) }], + vec![FunctionDecl { + lifecycle_role: Default::default(), + local_slots: 300, + max_stack_slots: 0, + ..function(&code) + }], ); let limits = LoadLimits { temporary_bytes: 41_000, ..Default::default() }; let mut b = LoadBudget::new(limits); @@ -232,6 +271,7 @@ fn stack_analysis_straight_line_storage_is_bounded_by_blocks_not_instruction_fra fn stack_analysis_accepts_unknown_fn_targets_and_rejects_removed_opcodes() { let code = prometeu_bytecode::assemble("GET_LOCAL 0\nCALL_CLOSURE 4\nHALT").unwrap(); let f = FunctionDecl { + lifecycle_role: Default::default(), signature: Signature { parameters: vec![NamedType { type_id: TypeId(4), name: None }], results: vec![], @@ -263,12 +303,19 @@ fn expected_fn_signature_checks_argument_height_after_permutations() { &code, vec![ FunctionDecl { + lifecycle_role: Default::default(), code_len: end as u32, local_slots: 1, max_stack_slots: 2, ..function(&code) }, - FunctionDecl { signature, code_offset: end as u32, code_len: 2, ..Default::default() }, + FunctionDecl { + lifecycle_role: Default::default(), + signature, + code_offset: end as u32, + code_len: 2, + ..Default::default() + }, ], ); assert_eq!(stacks(&code, &r).unwrap_err().reason, R::StackUnderflow); @@ -309,12 +356,14 @@ fn stack_analysis_charges_work_for_loop_reprocessing_and_refunds_on_exhaustion() &code, vec![ FunctionDecl { + lifecycle_role: Default::default(), code_len: end as u32, local_slots: 1, max_stack_slots: 1, ..function(&code) }, FunctionDecl { + lifecycle_role: Default::default(), code_offset: end as u32, code_len: (code.len() - end) as u32, max_stack_slots: 1, @@ -353,8 +402,13 @@ fn typed_opcodes_and_relative_jumps_are_resolved_in_declared_ranges() { let r = registry( &code, vec![ - FunctionDecl { code_len: start as u32, ..function(&code) }, FunctionDecl { + lifecycle_role: Default::default(), + code_len: start as u32, + ..function(&code) + }, + FunctionDecl { + lifecycle_role: Default::default(), code_offset: start as u32, code_len: 6, max_stack_slots: 0, @@ -394,8 +448,13 @@ fn jumps_reject_cross_range_and_mid_instruction_even_when_unreachable() { let r = registry( &code, vec![ - FunctionDecl { code_len: 6, ..function(&code) }, - FunctionDecl { code_offset: 6, code_len: 2, ..function(&code) }, + FunctionDecl { lifecycle_role: Default::default(), code_len: 6, ..function(&code) }, + FunctionDecl { + lifecycle_role: Default::default(), + code_offset: 6, + code_len: 2, + ..function(&code) + }, ], ); let e = check(&code, &r).unwrap_err(); @@ -479,7 +538,10 @@ fn spawn_arity_does_not_truncate_and_closure_function_ids_are_checked() { #[test] fn declared_range_is_not_extended_into_gaps_or_neighbor_functions() { let code = vec![Op::Halt as u8, 0, 0xff, 0xff]; - let r = registry(&code, vec![FunctionDecl { code_len: 2, ..function(&code) }]); + let r = registry( + &code, + vec![FunctionDecl { lifecycle_role: Default::default(), code_len: 2, ..function(&code) }], + ); assert!(check(&code, &r).is_ok()); // Unowned gap is outside this phase's ranges. let r = registry(&code, vec![function(&code)]); assert_eq!(check(&code, &r).unwrap_err().reason, R::UnknownOpcode); @@ -493,8 +555,13 @@ fn scratch_is_refunded_per_function_and_preserves_prior_load_ownership() { let r = registry( &code, vec![ - FunctionDecl { code_len: 2, ..function(&code) }, - FunctionDecl { code_offset: 2, code_len: 2, ..function(&code) }, + FunctionDecl { lifecycle_role: Default::default(), code_len: 2, ..function(&code) }, + FunctionDecl { + lifecycle_role: Default::default(), + code_offset: 2, + code_len: 2, + ..function(&code) + }, ], ); let limits = LoadLimits { temporary_bytes: 8, ..Default::default() }; @@ -531,8 +598,13 @@ fn truncated_immediates_cannot_borrow_bytes_from_the_next_function() { let r = registry( &code, vec![ - FunctionDecl { code_len: 2, ..function(&code) }, - FunctionDecl { code_offset: 2, code_len: 2, ..function(&code) }, + FunctionDecl { lifecycle_role: Default::default(), code_len: 2, ..function(&code) }, + FunctionDecl { + lifecycle_role: Default::default(), + code_offset: 2, + code_len: 2, + ..function(&code) + }, ], ); let e = check(&code, &r).unwrap_err(); diff --git a/crates/console/prometeu-vm/src/registry_verifier/types/tests.rs b/crates/console/prometeu-vm/src/registry_verifier/types/tests.rs index 6fe7b95..db59f01 100644 --- a/crates/console/prometeu-vm/src/registry_verifier/types/tests.rs +++ b/crates/console/prometeu-vm/src/registry_verifier/types/tests.rs @@ -32,6 +32,7 @@ fn function( max: u32, ) -> FunctionDecl { FunctionDecl { + lifecycle_role: Default::default(), captures: vec![], code_offset: offset as u32, code_len: len as u32, diff --git a/crates/console/prometeu-vm/src/virtual_machine.rs b/crates/console/prometeu-vm/src/virtual_machine.rs index cc44c81..1957b50 100644 --- a/crates/console/prometeu-vm/src/virtual_machine.rs +++ b/crates/console/prometeu-vm/src/virtual_machine.rs @@ -7,6 +7,7 @@ mod collections_tests; mod control; mod dynamic; mod gc; +mod lifecycle; mod loader; mod random; mod reference; @@ -49,6 +50,8 @@ use prometeu_test_support::program::{TestProgram, int64_signature}; pub enum LogicalFrameEndingReason { /// Execution reached a `FRAME_SYNC` instruction, marking the end of the logical frame. FrameSync, + /// The outer lifecycle callback returned; gameplay has not resumed. + LifecycleComplete, /// The cycle budget for the current host tick was exhausted before reaching `FRAME_SYNC`. BudgetExhausted, /// A `HALT` instruction was executed, terminating the program. @@ -109,6 +112,8 @@ pub struct VirtualMachine { cycles: u64, /// Stop flag: true if a `HALT` opcode was encountered. halted: bool, + lifecycle: Option, + lifecycle_failure: Option, /// Set of ROM addresses used for software breakpoints in the debugger. breakpoints: std::collections::HashSet, /// GC: number of newly allocated live objects threshold to trigger a collection at safepoint. @@ -229,6 +234,8 @@ impl VirtualMachine { heap: Heap::with_budget(&budget), cycles: 0, halted: true, + lifecycle: None, + lifecycle_failure: None, breakpoints: std::collections::HashSet::new(), gc_alloc_threshold: 1024, // conservative default; tests may override last_gc_live_count: 0, @@ -257,7 +264,7 @@ impl VirtualMachine { /// 1. Fetch: Read the opcode from memory. /// 2. Decode: Identify what operation to perform. /// 3. Execute: Perform the operation, updating stacks, memory, or calling peripherals. - pub fn step( + fn step_inner( &mut self, native: &mut dyn NativeInterface, ctx: &mut HostContext, @@ -1039,6 +1046,14 @@ impl VirtualMachine { return self.execute_collection(opcode, ty, field, start_pc as u32); } OpCode::FrameSync => { + if self.lifecycle.is_some() { + return Err(self.trap( + TRAP_TYPE, + opcode as u16, + "FRAME_SYNC is forbidden in lifecycle hooks".into(), + start_pc as u32, + )); + } // Marks the logical end of a frame: consume cycles and signal to the driver self.cycles += OpCode::FrameSync.cycles(); self.handle_safepoint() @@ -1152,7 +1167,11 @@ mod tests { typed_test_vm( code, constant_pool, - vec![FunctionDecl { max_stack_slots: 256, ..Default::default() }], + vec![FunctionDecl { + lifecycle_role: Default::default(), + max_stack_slots: 256, + ..Default::default() + }], ) } fn limited_session(code: Vec, limits: RuntimeLimits) -> VirtualMachine { @@ -1196,6 +1215,7 @@ mod tests { TestProgram { const_pool: vec![], functions: vec![FunctionDecl { + lifecycle_role: Default::default(), code_offset: 0, code_len: code.len() as u32, @@ -1511,8 +1531,13 @@ mod tests { rom, vec![], vec![ - FunctionDecl { max_stack_slots: 256, ..Default::default() }, FunctionDecl { + lifecycle_role: Default::default(), + max_stack_slots: 256, + ..Default::default() + }, + FunctionDecl { + lifecycle_role: Default::default(), code_offset: func_addr as u32, signature: int64_signature(1, 1), max_stack_slots: 256, @@ -1593,8 +1618,13 @@ mod tests { rom2, vec![], vec![ - FunctionDecl { max_stack_slots: 256, ..Default::default() }, FunctionDecl { + lifecycle_role: Default::default(), + max_stack_slots: 256, + ..Default::default() + }, + FunctionDecl { + lifecycle_role: Default::default(), code_offset: func_addr2 as u32, signature: int64_signature(0, 1), max_stack_slots: 256, @@ -1834,6 +1864,7 @@ mod tests { rom.clone(), vec![], vec![FunctionDecl { + lifecycle_role: Default::default(), code_offset: 0, signature: scalar_signature(0, 0, 1), @@ -2449,6 +2480,7 @@ mod tests { let header = TestProgram { const_pool: vec![], functions: vec![FunctionDecl { + lifecycle_role: Default::default(), code_offset: 0, code_len: code.len() as u32, @@ -2964,6 +2996,7 @@ mod tests { vec![], vec![ FunctionDecl { + lifecycle_role: Default::default(), code_offset: f0_start as u32, signature: scalar_signature(0, 0, 1), @@ -2974,6 +3007,7 @@ mod tests { local_slots: 0, }, FunctionDecl { + lifecycle_role: Default::default(), code_offset: f1_start, signature: scalar_signature(2, 1, 1), @@ -3025,6 +3059,7 @@ mod tests { vec![], vec![ FunctionDecl { + lifecycle_role: Default::default(), code_offset: f0_start as u32, signature: scalar_signature(0, 0, 1), @@ -3035,6 +3070,7 @@ mod tests { local_slots: 0, }, FunctionDecl { + lifecycle_role: Default::default(), code_offset: f1_start, signature: scalar_signature(0, 2, 1), @@ -3085,6 +3121,7 @@ mod tests { vec![], vec![ FunctionDecl { + lifecycle_role: Default::default(), code_offset: f0_start as u32, signature: scalar_signature(0, 0, 1), @@ -3095,6 +3132,7 @@ mod tests { local_slots: 0, }, FunctionDecl { + lifecycle_role: Default::default(), code_offset: f1_start, signature: scalar_signature(1, 0, 1), @@ -3210,6 +3248,7 @@ mod tests { rom.clone(), vec![], vec![FunctionDecl { + lifecycle_role: Default::default(), code_offset: 0, local_slots: 1, @@ -3269,6 +3308,7 @@ mod tests { vec![], vec![ FunctionDecl { + lifecycle_role: Default::default(), code_offset: f0_start as u32, signature: scalar_signature(0, 0, 4), @@ -3279,6 +3319,7 @@ mod tests { local_slots: 0, }, FunctionDecl { + lifecycle_role: Default::default(), code_offset: f1_start, local_slots: 1, @@ -3391,6 +3432,7 @@ mod tests { rom.clone(), vec![], vec![FunctionDecl { + lifecycle_role: Default::default(), code_offset: 0, signature: scalar_signature(0, 0, 1), @@ -3439,6 +3481,7 @@ mod tests { rom.clone(), vec![], vec![FunctionDecl { + lifecycle_role: Default::default(), code_offset: 0, signature: scalar_signature(0, 0, 1), @@ -3506,6 +3549,7 @@ mod tests { rom.clone(), vec![], vec![FunctionDecl { + lifecycle_role: Default::default(), code_offset: 0, signature: scalar_signature(0, 0, 1), @@ -3556,6 +3600,7 @@ mod tests { rom.clone(), vec![], vec![FunctionDecl { + lifecycle_role: Default::default(), code_offset: 0, signature: scalar_signature(0, 0, 1), @@ -3606,6 +3651,7 @@ mod tests { rom.clone(), vec![], vec![FunctionDecl { + lifecycle_role: Default::default(), code_offset: 0, signature: scalar_signature(0, 0, 1), @@ -3661,6 +3707,7 @@ mod tests { rom.clone(), vec![], vec![FunctionDecl { + lifecycle_role: Default::default(), code_offset: 0, signature: scalar_signature(0, 0, 1), diff --git a/crates/console/prometeu-vm/src/virtual_machine/lifecycle.rs b/crates/console/prometeu-vm/src/virtual_machine/lifecycle.rs new file mode 100644 index 0000000..61e37c9 --- /dev/null +++ b/crates/console/prometeu-vm/src/virtual_machine/lifecycle.rs @@ -0,0 +1,109 @@ +//! Bounded calls that retain the suspended guest continuation and its GC roots. +use super::*; +use prometeu_bytecode::registry::LifecycleRole; + +pub(super) struct LifecycleCall { + depth: usize, + pc: usize, + halted: bool, + pub(super) remaining: u64, + pub(super) breakpoint: Option, +} + +impl VirtualMachine { + pub const LIFECYCLE_CYCLES: u64 = 1_500_000; + pub const LIFECYCLE_SLICE: u64 = 250_000; + + pub fn has_lifecycle_hook(&self, role: LifecycleRole) -> bool { + self.validated_image.as_ref().is_some_and(|i| i.registry().lifecycle_hook(role).is_some()) + } + + pub fn lifecycle_active(&self) -> bool { + self.lifecycle.is_some() + } + + pub fn lifecycle_remaining_cycles(&self) -> Option { + self.lifecycle.as_ref().map(|call| call.remaining) + } + + /// Returns false for an absent role. Entry is transactional with respect to quotas. + pub fn begin_lifecycle(&mut self, role: LifecycleRole) -> Result { + if self.lifecycle.is_some() || self.lifecycle_failure.is_some() { + return Err(VmInitError::EntrypointNotFound); + } + let Some(id) = + self.validated_image.as_ref().and_then(|i| i.registry().lifecycle_hook(role)) + else { + return Ok(false); + }; + let func_idx = id.0 as usize; + let callee = &self.program.functions[func_idx]; + let locals = callee.local_slots as usize; + let offset = callee.code_offset as usize; + self.budget.check(RuntimeResource::CallDepth, (self.call_stack.len() + 1) as u64)?; + let operands = self.operand_stack.prepare_growth(locals)?; + let frames = self.call_stack.prepare_growth(1)?; + self.operand_stack.commit_growth(operands); + self.call_stack.commit_growth(frames); + let base = self.operand_stack.len(); + let call = LifecycleCall { + depth: self.call_stack.len(), + pc: self.pc, + halted: self.halted, + remaining: Self::LIFECYCLE_CYCLES, + breakpoint: None, + }; + for _ in 0..locals { + self.operand_stack.push(Value::Null)?; + } + self.call_stack.push(CallFrame { + return_pc: self.pc as u32, + stack_base: base, + func_idx, + closure: None, + })?; + self.lifecycle = Some(call); + self.pc = offset; + self.halted = false; + Ok(true) + } + + /// Both the debugger and normal slices pass through the same accounting boundary. + pub fn step( + &mut self, + native: &mut dyn NativeInterface, + ctx: &mut HostContext, + ) -> Result<(), LogicalFrameEndingReason> { + if let Some(reason) = &self.lifecycle_failure { + return Err(reason.clone()); + } + if let Some(call) = &mut self.lifecycle { + call.breakpoint = None; + } + let before = self.cycles; + let result = self.step_inner(native, ctx); + let Some(call) = self.lifecycle.as_mut() else { + return result; + }; + call.remaining = call.remaining.saturating_sub(self.cycles - before); + if result.is_ok() && !self.halted && self.call_stack.len() == call.depth { + let call = self.lifecycle.take().unwrap(); + self.pc = call.pc; + self.halted = call.halted; + return Err(LogicalFrameEndingReason::LifecycleComplete); + } + let failure = match result { + Err(reason) => Some(reason), + Ok(()) if self.halted => Some(LogicalFrameEndingReason::Halted), + Ok(()) if call.remaining == 0 => Some(LogicalFrameEndingReason::Panic( + "lifecycle total cycle budget exhausted".into(), + )), + Ok(()) => None, + }; + if let Some(reason) = failure { + self.lifecycle_failure = Some(reason.clone()); + return Err(reason); + } + Ok(()) + } +} diff --git a/crates/console/prometeu-vm/src/virtual_machine/loader.rs b/crates/console/prometeu-vm/src/virtual_machine/loader.rs index f4001f1..d63d97c 100644 --- a/crates/console/prometeu-vm/src/virtual_machine/loader.rs +++ b/crates/console/prometeu-vm/src/virtual_machine/loader.rs @@ -55,6 +55,9 @@ impl VirtualMachine { func_idx: usize, arguments: &[Value], ) -> Result<(), VmInitError> { + if self.lifecycle.is_some() || self.lifecycle_failure.is_some() { + return Err(VmInitError::EntrypointNotFound); + } #[cfg(not(test))] if self.validated_image.is_none() { return Err(VmInitError::EntrypointNotFound); diff --git a/crates/console/prometeu-vm/src/virtual_machine/runtime.rs b/crates/console/prometeu-vm/src/virtual_machine/runtime.rs index 7edef35..4fb9aa6 100644 --- a/crates/console/prometeu-vm/src/virtual_machine/runtime.rs +++ b/crates/console/prometeu-vm/src/virtual_machine/runtime.rs @@ -7,6 +7,11 @@ impl VirtualMachine { native: &mut dyn NativeInterface, ctx: &mut HostContext, ) -> Result { + if let Some(reason) = &self.lifecycle_failure { + return Ok(BudgetReport { cycles_used: 0, steps_executed: 0, reason: reason.clone() }); + } + let budget = + if self.lifecycle.is_some() { budget.min(Self::LIFECYCLE_SLICE) } else { budget }; let start_cycles = self.cycles; let mut steps_executed = 0; let mut ending_reason: Option = None; @@ -15,7 +20,13 @@ impl VirtualMachine { && !self.halted && self.pc < self.program.rom.len() { - if steps_executed > 0 && self.breakpoints.contains(&self.pc) { + if self.breakpoints.contains(&self.pc) + && (steps_executed > 0 + || self.lifecycle.as_ref().is_some_and(|c| c.breakpoint != Some(self.pc))) + { + if let Some(call) = &mut self.lifecycle { + call.breakpoint = Some(self.pc); + } ending_reason = Some(LogicalFrameEndingReason::Breakpoint); break; } @@ -70,7 +81,8 @@ impl VirtualMachine { let rep = self.run_budget(budget_per_slice, native, ctx)?; let terminal = matches!( rep.reason, - LogicalFrameEndingReason::Halted + LogicalFrameEndingReason::LifecycleComplete + | LogicalFrameEndingReason::Halted | LogicalFrameEndingReason::EndOfRom | LogicalFrameEndingReason::Panic(_) | LogicalFrameEndingReason::Trap(_) @@ -113,7 +125,8 @@ impl VirtualMachine { let rep = self.run_budget(budget_per_slice, native, ctx)?; let terminal = matches!( rep.reason, - LogicalFrameEndingReason::Halted + LogicalFrameEndingReason::LifecycleComplete + | LogicalFrameEndingReason::Halted | LogicalFrameEndingReason::EndOfRom | LogicalFrameEndingReason::Panic(_) | LogicalFrameEndingReason::Trap(_) diff --git a/crates/console/prometeu-vm/src/virtual_machine/typed_tests.rs b/crates/console/prometeu-vm/src/virtual_machine/typed_tests.rs index d5df471..80d54bc 100644 --- a/crates/console/prometeu-vm/src/virtual_machine/typed_tests.rs +++ b/crates/console/prometeu-vm/src/virtual_machine/typed_tests.rs @@ -36,6 +36,7 @@ fn function( max: u32, ) -> FunctionDecl { FunctionDecl { + lifecycle_role: Default::default(), captures: vec![], name: Some(format!("f{offset}")), code_offset: offset as u32, @@ -777,3 +778,171 @@ fn call_growth_refusal_does_not_publish_frame_or_keep_provisional_capacity() { assert_eq!(vm.budget.used(RuntimeResource::AuxiliaryBytes), before); assert_eq!(vm.budget.used(RuntimeResource::TemporaryBytes), 0); } + +mod lifecycle_tests { + use super::*; + use prometeu_bytecode::registry::LifecycleRole; + + fn machine(hook: Vec) -> VirtualMachine { + let mut code = vec![]; + arg(&mut code, OpCode::PushI32, 17); + op(&mut code, OpCode::FrameSync); + arg(&mut code, OpCode::SetGlobal, 0); + op(&mut code, OpCode::Ret); + let len = code.len(); + code.extend(&hook); + let mut callback = function(len, hook.len(), &[], &[], 0, 8); + callback.lifecycle_role = LifecycleRole::BeforePause; + let image = image(&code, vec![function(0, len, &[], &[], 0, 8), callback]); + let mut vm = VirtualMachine::from_image(image, RuntimeLimits::default()); + vm.prepare_boot_call().unwrap(); + assert_eq!(run(&mut vm), LogicalFrameEndingReason::FrameSync); + vm + } + + #[test] + fn lifecycle_preserves_continuation_and_does_not_run_gameplay_after_return() { + let mut hook = vec![]; + arg(&mut hook, OpCode::PushI32, 42); + arg(&mut hook, OpCode::SetGlobal, 1); + op(&mut hook, OpCode::Ret); + let mut vm = machine(hook); + let pc = vm.pc; + let depth = vm.call_stack.len(); + let stack = vm.operand_stack.to_vec(); + assert!(vm.begin_lifecycle(LifecycleRole::BeforePause).unwrap()); + assert!(vm.begin_lifecycle(LifecycleRole::BeforePause).is_err()); + assert_eq!(run(&mut vm), LogicalFrameEndingReason::LifecycleComplete); + assert_eq!(vm.pc, pc); + assert_eq!(vm.call_stack.len(), depth); + assert_eq!(&vm.operand_stack[..], stack.as_slice()); + assert_eq!(vm.globals[1], Value::Int32(42)); + assert_eq!(run(&mut vm), LogicalFrameEndingReason::EndOfRom); + assert_eq!(vm.globals[0], Value::Int32(17)); + assert!(!vm.begin_lifecycle(LifecycleRole::BeforeResume).unwrap()); + } + + #[test] + fn lifecycle_budget_survives_slices_breakpoints_and_single_steps() { + let mut hook = vec![]; + arg(&mut hook, OpCode::Jmp, 0); + let mut vm = machine(hook); + vm.begin_lifecycle(LifecycleRole::BeforePause).unwrap(); + vm.insert_breakpoint(vm.pc); + let rep = vm.run_budget(u64::MAX, &mut Native, &mut HostContext::new(None)).unwrap(); + assert_eq!(rep.reason, LogicalFrameEndingReason::Breakpoint); + assert_eq!(rep.cycles_used, 0); + let before = vm.lifecycle_remaining_cycles().unwrap(); + vm.step(&mut Native, &mut HostContext::new(None)).unwrap(); + assert!(vm.lifecycle_remaining_cycles().unwrap() < before); + vm.breakpoints.clear(); + let mut total = VirtualMachine::LIFECYCLE_CYCLES - vm.lifecycle_remaining_cycles().unwrap(); + loop { + let rep = vm.run_budget(u64::MAX, &mut Native, &mut HostContext::new(None)).unwrap(); + assert!(rep.cycles_used <= VirtualMachine::LIFECYCLE_SLICE + OpCode::Jmp.cycles()); + total += rep.cycles_used; + if let LogicalFrameEndingReason::Panic(message) = rep.reason { + assert!(message.contains("total cycle budget")); + break; + } + assert_eq!(rep.reason, LogicalFrameEndingReason::BudgetExhausted); + } + assert!(total >= VirtualMachine::LIFECYCLE_CYCLES); + let pc = vm.pc; + assert!(vm.step(&mut Native, &mut HostContext::new(None)).is_err()); + assert_eq!(vm.pc, pc); + } + + #[test] + fn lifecycle_normal_return_wins_at_budget_boundary_and_halt_does_not_complete() { + for remaining in [1, OpCode::Ret.cycles()] { + let mut hook = vec![]; + op(&mut hook, OpCode::Ret); + let mut vm = machine(hook); + vm.begin_lifecycle(LifecycleRole::BeforePause).unwrap(); + vm.lifecycle.as_mut().unwrap().remaining = remaining; + assert_eq!(run(&mut vm), LogicalFrameEndingReason::LifecycleComplete); + } + let mut hook = vec![]; + op(&mut hook, OpCode::Halt); + let mut vm = machine(hook); + vm.begin_lifecycle(LifecycleRole::BeforePause).unwrap(); + assert_eq!(run(&mut vm), LogicalFrameEndingReason::Halted); + assert!(vm.lifecycle_active()); + } + + #[test] + fn lifecycle_forbids_frame_sync_and_preserves_failure() { + let mut hook = vec![]; + op(&mut hook, OpCode::FrameSync); + op(&mut hook, OpCode::Ret); + let mut vm = machine(hook); + vm.begin_lifecycle(LifecycleRole::BeforePause).unwrap(); + let reason = run(&mut vm); + assert!( + matches!(&reason, LogicalFrameEndingReason::Trap(t) if t.message.contains("FRAME_SYNC")) + ); + assert_eq!(run(&mut vm), reason); + } + #[test] + fn lifecycle_nested_calls_keep_saved_roots_and_branch_returns_stop_at_boundary() { + let main = prometeu_bytecode::assembler::assemble("FRAME_SYNC\nRET").unwrap(); + let hook = prometeu_bytecode::assembler::assemble("CALL 2\nJMP 12").unwrap(); + for callee_source in ["PUSH_I32 9\nSET_GLOBAL 0\nRET", "FRAME_SYNC\nRET"] { + let callee = prometeu_bytecode::assembler::assemble(callee_source).unwrap(); + let mut callback = function(main.len(), hook.len(), &[], &[], 0, 8); + callback.lifecycle_role = LifecycleRole::BeforePause; + let code = [main.as_slice(), hook.as_slice(), callee.as_slice()].concat(); + let image = image( + &code, + vec![ + function(0, main.len(), &[], &[], 0, 8), + callback, + function(main.len() + hook.len(), callee.len(), &[], &[], 0, 8), + ], + ); + let mut vm = VirtualMachine::from_image(image, RuntimeLimits::default()); + vm.prepare_boot_call().unwrap(); + assert_eq!(run(&mut vm), LogicalFrameEndingReason::FrameSync); + let retained = vm.heap.alloc_closure(0, &[]).unwrap(); + vm.operand_stack.push(Value::HeapRef(retained)).unwrap(); + vm.begin_lifecycle(LifecycleRole::BeforePause).unwrap(); + vm.gc_alloc_threshold = 1; + vm.handle_safepoint().unwrap(); + assert!(vm.heap.is_valid(retained)); + let result = run(&mut vm); + if callee_source.starts_with("FRAME_SYNC") { + assert!(matches!(result, LogicalFrameEndingReason::Trap(_))); + } else { + assert_eq!(result, LogicalFrameEndingReason::LifecycleComplete); + assert_eq!(vm.call_stack.len(), 1); + assert_eq!(vm.operand_stack.last(), Some(&Value::HeapRef(retained))); + assert_eq!(vm.globals[0], Value::Int32(9)); + } + } + } + + #[test] + fn lifecycle_entry_quota_refusal_is_transactional_and_empty_context_is_supported() { + let mut vm = machine(prometeu_bytecode::assembler::assemble("RET").unwrap()); + let image = vm.validated_image.clone().unwrap(); + let limits = RuntimeLimits::default().lowered(RuntimeResource::CallDepth, 1).unwrap(); + vm = VirtualMachine::from_image(image.clone(), limits); + vm.prepare_boot_call().unwrap(); + let pc = vm.pc; + let stack = vm.operand_stack.to_vec(); + assert!(vm.begin_lifecycle(LifecycleRole::BeforePause).is_err()); + assert_eq!(vm.pc, pc); + assert_eq!(&vm.operand_stack[..], stack.as_slice()); + assert_eq!(vm.call_stack.len(), 1); + assert!(!vm.lifecycle_active()); + let mut vm = VirtualMachine::from_image(image, RuntimeLimits::default()); + let halted = vm.halted; + let pc = vm.pc; + vm.begin_lifecycle(LifecycleRole::BeforePause).unwrap(); + assert_eq!(run(&mut vm), LogicalFrameEndingReason::LifecycleComplete); + assert_eq!(vm.pc, pc); + assert_eq!(vm.halted, halted); + assert!(vm.call_stack.is_empty()); + } +} diff --git a/crates/console/prometeu-vm/tests/producer_handoff.rs b/crates/console/prometeu-vm/tests/producer_handoff.rs index ff43889..e020b51 100644 --- a/crates/console/prometeu-vm/tests/producer_handoff.rs +++ b/crates/console/prometeu-vm/tests/producer_handoff.rs @@ -45,6 +45,7 @@ fn named_arguments_preserve_source_effect_order_and_call_in_signature_order_with vec![] }; functions.push(FunctionDecl { + lifecycle_role: Default::default(), captures: vec![], name: Some(["main", "effectX", "effectY", "combine"][index].into()), signature: Signature { diff --git a/crates/console/prometeu-vm/tests/registry_conformance.rs b/crates/console/prometeu-vm/tests/registry_conformance.rs index d865e98..7837d90 100644 --- a/crates/console/prometeu-vm/tests/registry_conformance.rs +++ b/crates/console/prometeu-vm/tests/registry_conformance.rs @@ -7,20 +7,20 @@ use prometeu_vm::{ }; // Independent executable oracle: 32-byte header, eight directory entries, -// payload at 128, one Bool import, one zero-slot HALT function; total 193. +// payload at 128, one Bool import, one zero-slot HALT function; total 194. fn minimal() -> Vec { "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 @@ -48,7 +48,7 @@ impl NativeInterface for Native { #[test] fn independent_v1_bytes_load_publish_and_execute_through_the_public_sealed_boundary() { let bytes = minimal(); - assert_eq!(bytes.len(), 193); + assert_eq!(bytes.len(), 194); let mut load = LoadBudget::new(Default::default()); let image = ValidatedProgramImage::load(&bytes, &mut load, caps::NONE).unwrap(); assert_eq!(load.used(LoadResource::TemporaryBytes), 0); @@ -65,9 +65,9 @@ fn independent_v1_bytes_load_publish_and_execute_through_the_public_sealed_bound fn single_violation_oracles_reject_before_image_publication_with_typed_context() { for (offset, replacement, code, reason, pc) in [ (4, 0, LoadCode::UnsupportedFormat, LoadReason::Version, None), - (177, 0, LoadCode::UnsupportedFormat, LoadReason::Builtin, None), - (161, 0xff, LoadCode::InvalidCode, LoadReason::UnknownOpcode, Some(0)), - (161, 0x11, LoadCode::InvalidCode, LoadReason::StackUnderflow, Some(0)), + (178, 0, LoadCode::UnsupportedFormat, LoadReason::Builtin, None), + (162, 0xff, LoadCode::InvalidCode, LoadReason::UnknownOpcode, Some(0)), + (162, 0x11, LoadCode::InvalidCode, LoadReason::StackUnderflow, Some(0)), ] { let mut bytes = minimal(); bytes[offset] = replacement; diff --git a/crates/console/prometeu-vm/tests/support/callables.rs b/crates/console/prometeu-vm/tests/support/callables.rs index 8f95da6..9e64c5c 100644 --- a/crates/console/prometeu-vm/tests/support/callables.rs +++ b/crates/console/prometeu-vm/tests/support/callables.rs @@ -89,6 +89,7 @@ pub fn bytes_with_syscalls( for (source, signature, captures) in bodies { let body = assemble(source).unwrap(); functions.push(FunctionDecl { + lifecycle_role: Default::default(), signature: signature.clone(), captures: captures.clone(), code_offset: code.len() as u32, diff --git a/crates/console/prometeu-vm/tests/support/collections.rs b/crates/console/prometeu-vm/tests/support/collections.rs index 7e67ca5..160c9ce 100644 --- a/crates/console/prometeu-vm/tests/support/collections.rs +++ b/crates/console/prometeu-vm/tests/support/collections.rs @@ -60,6 +60,7 @@ pub fn declarations(code_len: usize) -> RegistryDeclarations { RegistryDeclarations { types, functions: vec![FunctionDecl { + lifecycle_role: Default::default(), code_len: code_len as u32, local_slots: 0, max_stack_slots: 32, diff --git a/crates/console/prometeu-vm/tests/support/random.rs b/crates/console/prometeu-vm/tests/support/random.rs index 7f941be..16b9b28 100644 --- a/crates/console/prometeu-vm/tests/support/random.rs +++ b/crates/console/prometeu-vm/tests/support/random.rs @@ -50,6 +50,7 @@ pub fn bytes(bodies: &[Body<'_>]) -> Vec { for (text, signature, captures, locals) in bodies { let body = assemble(text).unwrap(); functions.push(FunctionDecl { + lifecycle_role: Default::default(), signature: signature.clone(), captures: captures.clone(), local_slots: *locals, diff --git a/crates/dev/prometeu-test-support/src/program.rs b/crates/dev/prometeu-test-support/src/program.rs index 92c0061..7861acd 100644 --- a/crates/dev/prometeu-test-support/src/program.rs +++ b/crates/dev/prometeu-test-support/src/program.rs @@ -49,6 +49,7 @@ impl TestProgram { ) -> Self { Self { functions: vec![FunctionDecl { + lifecycle_role: Default::default(), name: None, signature, captures: vec![], diff --git a/crates/host/prometeu-host-headless/benches/temporal.rs b/crates/host/prometeu-host-headless/benches/temporal.rs index 93a8367..deba747 100644 --- a/crates/host/prometeu-host-headless/benches/temporal.rs +++ b/crates/host/prometeu-host-headless/benches/temporal.rs @@ -53,6 +53,7 @@ fn benchmark_cartridge() -> PathBuf { let module = TestProgram { const_pool: vec![], functions: vec![FunctionDecl { + lifecycle_role: Default::default(), code_offset: 0, code_len: code.len() as u32, local_slots: 0, diff --git a/crates/host/prometeu-host-headless/src/automation/wire/fault_tests.rs b/crates/host/prometeu-host-headless/src/automation/wire/fault_tests.rs index 53d47bb..9867284 100644 --- a/crates/host/prometeu-host-headless/src/automation/wire/fault_tests.rs +++ b/crates/host/prometeu-host-headless/src/automation/wire/fault_tests.rs @@ -64,8 +64,18 @@ fn executed_closure_quota_refusal_reaches_wire_with_machine_fields() { RegistryDeclarations { types: vec![TypeDecl { name: None, kind: TypeKind::Fn(Default::default()) }], functions: vec![ - FunctionDecl { code_len: end, max_stack_slots: 1, ..Default::default() }, - FunctionDecl { code_offset: end, code_len: 2, ..Default::default() }, + FunctionDecl { + lifecycle_role: Default::default(), + code_len: end, + max_stack_slots: 1, + ..Default::default() + }, + FunctionDecl { + lifecycle_role: Default::default(), + code_offset: end, + code_len: 2, + ..Default::default() + }, ], implementations: vec![], }, diff --git a/crates/host/prometeu-host-headless/src/host.rs b/crates/host/prometeu-host-headless/src/host.rs index f116459..2e5d7ea 100644 --- a/crates/host/prometeu-host-headless/src/host.rs +++ b/crates/host/prometeu-host-headless/src/host.rs @@ -501,6 +501,7 @@ mod tests { let module = TestProgram { const_pool: vec![], functions: vec![FunctionDecl { + lifecycle_role: Default::default(), code_offset: 0, code_len: code.len() as u32, local_slots: 0, diff --git a/crates/host/prometeu-host-headless/tests/deterministic_control.rs b/crates/host/prometeu-host-headless/tests/deterministic_control.rs index 0e44470..e6518c3 100644 --- a/crates/host/prometeu-host-headless/tests/deterministic_control.rs +++ b/crates/host/prometeu-host-headless/tests/deterministic_control.rs @@ -660,6 +660,7 @@ fn module_with_locals(code: Vec, syscalls: Vec, local_slots: u1 TestProgram { const_pool: vec![], functions: vec![FunctionDecl { + lifecycle_role: Default::default(), code_offset: 0, code_len: code.len() as u32, local_slots: u32::from(local_slots), diff --git a/crates/tools/pbxgen-dummy-boy/src/lib.rs b/crates/tools/pbxgen-dummy-boy/src/lib.rs index 73c4778..4b512f6 100644 --- a/crates/tools/pbxgen-dummy-boy/src/lib.rs +++ b/crates/tools/pbxgen-dummy-boy/src/lib.rs @@ -72,6 +72,7 @@ pub fn build_program() -> Vec { let registry = Registry::resolve( RegistryDeclarations { functions: vec![FunctionDecl { + lifecycle_role: Default::default(), code_len: code.len() as u32, local_slots: 1, max_stack_slots: 8, diff --git a/crates/tools/pbxgen-stress/src/lib.rs b/crates/tools/pbxgen-stress/src/lib.rs index 78e3cf5..4c907af 100644 --- a/crates/tools/pbxgen-stress/src/lib.rs +++ b/crates/tools/pbxgen-stress/src/lib.rs @@ -85,6 +85,7 @@ pub fn generate() -> Result<()> { let registry = Registry::resolve( RegistryDeclarations { functions: vec![FunctionDecl { + lifecycle_role: Default::default(), code_len: rom.len() as u32, local_slots: 2, max_stack_slots: 32, diff --git a/crates/tools/prometeu-cli/tests/automation_process.rs b/crates/tools/prometeu-cli/tests/automation_process.rs index b4270b7..6791c87 100644 --- a/crates/tools/prometeu-cli/tests/automation_process.rs +++ b/crates/tools/prometeu-cli/tests/automation_process.rs @@ -180,6 +180,7 @@ fn cartridge_bytes(code: Vec, gfx: bool) -> TempDir { let module = TestProgram { const_pool: vec![], functions: vec![FunctionDecl { + lifecycle_role: Default::default(), code_offset: 0, code_len: code.len() as u32, local_slots: 0, diff --git a/discussion/lessons/DSC-0062-guest-lifecycle-pause-and-resume-api/LSN-0066-lifecycle-calls-retain-the-game-continuation.md b/discussion/lessons/DSC-0062-guest-lifecycle-pause-and-resume-api/LSN-0066-lifecycle-calls-retain-the-game-continuation.md new file mode 100644 index 0000000..02adcd6 --- /dev/null +++ b/discussion/lessons/DSC-0062-guest-lifecycle-pause-and-resume-api/LSN-0066-lifecycle-calls-retain-the-game-continuation.md @@ -0,0 +1,111 @@ +--- +id: LSN-0066 +ticket: guest-lifecycle-pause-and-resume-api +title: Lifecycle Calls Retain the Game Continuation +created: 2026-10-13 +tags: [lifecycle, vm, registry, debugger] +--- + +## Context + +Optional BeforePause and BeforeResume functions now run around the existing OS +suspension and reactivation transitions. The implementation derives from accepted +DEC-0054 and PLN-0185, originating in AGD-0065 / DSC-0062. These workflow records +are disposable; the durable contracts are +[Registry roles](../../../docs/specs/runtime/02c-program-registry-and-pbx-v1.md#optional-lifecycle-roles) +and [controlled lifecycle calls](../../../docs/specs/runtime/09a-coroutines-and-cooperative-scheduling.md#controlled-lifecycle-calls). + +## Binding Describes a Runtime Event, Not a Frontend Construct + +A Registry function has one explicit role byte. Zero means no lifecycle role; +nonzero bindings are unique and optional. The function index is chosen by the +producer. A source name, manifest entry or arbitrary fixed FunctionId would mix +language policy with runtime scheduling. Signature validation at image loading +makes the OS call boundary independent of source syntax. + +Init and Frame remain frontend assembly choices behind ordinary entry zero. +The external compiler must emit the new role byte for every Function record, +validate source declarations, and regenerate its PBX v1 artifacts. That compiler +integration was not performed in this runtime delivery. Internal producers and +tracked dummy-boy/stress-console images use the revised layout. Independent +binary oracles were updated field by field, including directory offsets and +malformed-input locations; merely regenerating fixtures would lose that check. + +## Retaining the Continuation Avoids a Second Execution Context + +The VM appends a hook frame to its own operand and call stacks. The previous PC, +halted flag and boundaries define where to restore execution. Existing values +and closure environments stay in the normal root traversal, so a suspended +caller cannot disappear during collection. Globals and heap mutations made by +the hook persist. Retained frames still count toward call-depth and memory limits. + +Boot-entry preparation clears stacks and is therefore the wrong operation for +this boundary. A second VM would separate globals, capabilities, handles and +heap identity. Appending a controlled frame keeps those identities intact. The +critical completion rule is to stop at the outer return immediately: unused +slice fuel must not execute the saved gameplay continuation. A branch to function +end follows the same boundary, including nested ordinary calls. + +## A Debugger Is Another Execution Driver + +Normal slices and instruction stepping share the VM's total-fuel accounting. +Breakpoints retain that balance, including a breakpoint on the first hook +instruction. Waiting in the debugger costs no cycles. The OS step path uses the +session's actual filesystem state, open handles and memcard service. A dummy +service context would make stepping change the program's meaning. + +One total budget survives all slices. Whole instructions retain their ordinary +overshoot semantics; a completed return wins at the boundary, while unfinished +work fails at exhaustion. FRAME_SYNC is forbidden transitively because a hook +must not close or publish a gameplay frame. Normal service errors remain data; +fatal faults and host panics fail the session with the phase in diagnostics. +HALT closes the task rather than completing a hook or returning to gameplay. + +## Deferring Completion Preserves Existing OS Policy + +The Home path still grants its existing handoff tick. After it leaves gameplay, +the pending transition drives only the callback until suspension completes. +Direct suspension and Shell activation use the same callback boundary without +inventing an extra gameplay tick. Reactivation precedes BeforeResume, and normal +frames remain gated until return. Requests are serialized; repeated requests +cannot replenish fuel or start another invocation. + +The firmware also recognizes completion caused by debugger stepping, so its +next update cannot treat a properly suspended task as a crash. Transitions with +no applicable hook retain their immediate behavior. + +## Bytecode Fuel Does Not Bound a Blocked Native Call + +The executor adds no disk wait or automatic flush and does not cancel owned IO +on hook failure. Existing asset/async-work protocols retain their ownership. +The native audit found that FS read/write and the current memcard commit still +call synchronous backend interfaces. A deterministic cycle cap cannot preempt +one of those host calls. Prompt native return is a host/service obligation; +there is no wall-time guarantee in this delivery. + +The new memcard backend must supply bounded asynchronous submission/polling and +own in-flight data until completion or safe release. Its consumer acceptance +belongs to the memcard workflow: explicit commit from a hook, return without +waiting for disk, late completion after lifecycle failure, and availability +checks on resume without automatic reload/save/reinitialization. The runtime +hook mechanism is independently complete and does not implement that backend. + +## Evidence + +Loaded-bytecode tests exercise optional roles, strict metadata rejection, +retained PC/stacks/roots, nested calls, branch returns, quota refusal, an empty +continuation, exact/overshooting return budgets, multiple slices, breakpoints, +and sticky fatal failures. Firmware tests cover Home, direct suspend, Shell, +resume, independently absent hooks, debugger steps using real handles, phase +failures and HALT. Validation completed with 960 passed / 9 existing ignored across 53 workspace +suites (`cargo test --workspace --all-targets --all-features --no-fail-fast`). +After the final tick/step and boot-entry guards, all 528 affected VM/system/firmware +library tests passed (2 existing ignored). The final pause-request guard was +also revalidated by the 245 system/firmware library tests. Formatting, Clippy, +diff whitespace, published-doc workflow-reference checks and discussion validation +passed. Published lesson links resolve. Internal producer regeneration completed. + +The tests also verify ordinary unmounted-FS error data inside a hook, real +session-handle mutation under debugger stepping, and that a suspended session +cannot execute gameplay through direct tick/step requests. Preparing a new boot +entry while a hook is active is refused rather than clearing the retained stacks. diff --git a/docs/specs/runtime/02b-vm-function-values-and-closures.md b/docs/specs/runtime/02b-vm-function-values-and-closures.md index 1f2d84a..bab3356 100644 --- a/docs/specs/runtime/02b-vm-function-values-and-closures.md +++ b/docs/specs/runtime/02b-vm-function-values-and-closures.md @@ -76,13 +76,15 @@ call and capture access validate whole groups and reserve capacity before consum or publication. Refusal preserves operands/owners and publishes no partial object or frame; provisional reservations refund and attempted cycles remain. No quota rescue GC. Use existing distinct NullReference/InvalidHandle/Type/Resource traps. -Fn can invoke syscalls, mutate and fault: no purity flag, fault isolation, separate -budget, guest unwind or rollback of earlier body effects. +Ordinary Fn calls can invoke syscalls, mutate and fault: no purity flag, fault +isolation, separate budget, guest unwind or rollback of earlier body effects. +SystemOS lifecycle invocations use the separate budget described below. ## 5 Context, GC and Host VM owns one PC, operand/call stacks and globals directly. FRAME_SYNC retains -frames/locals/environments and resumes next PC in any body. Budget exhaustion +frames/locals/environments and resumes next PC in normal gameplay bodies. It is +forbidden during lifecycle hooks and their callees. Budget exhaustion retains the same logical frame. Last-root RET completes entry, rooting results before threshold GC. Recurring host entry remains FunctionId 0 with init once. @@ -92,8 +94,9 @@ and legally retained native/host roots. Trace whole capture groups and shared cells; unreachable cycles collect. Results remain roots until consumed/replaced, reset/unload. No GC at ordinary callee RET or allocation/quota rescue. HeapRef copies/inspection snapshots establish no guest roots or cross-session -imports. No native registration/delivery/reentry API is created here. Guest -callbacks are ordinary Fn calls in the main execution context. +imports. Ordinary guest callbacks are Fn calls in the main execution context. +Optional SystemOS lifecycle entry uses Registry roles and the controlled boundary +described below; it does not introduce arbitrary native reentry. See [memory](03-memory-stack-heap-and-allocation.md), [Registry/PBX](02c-program-registry-and-pbx-v1.md) and @@ -102,3 +105,14 @@ See [memory](03-memory-stack-heap-and-allocation.md), ## Random core integration [Random references](02e-vm-owned-random-core.md) are valid capture, parameter and result groups. Existing roots retain the generator; copying captures aliases its state. + +## System-owned lifecycle entry + +Optional zero-argument, zero-result, capture-free lifecycle targets are bound by +[Registry roles](02c-program-registry-and-pbx-v1.md#optional-lifecycle-roles). +They are ordinary functions called through a controlled SystemOS boundary, not +closure values or replacement boot entries. The boundary retains the existing +stacks and roots, appends its frame, and returns to SystemOS immediately on outer +completion. See [lifecycle execution](09a-coroutines-and-cooperative-scheduling.md#controlled-lifecycle-calls) +for independent fuel, debugger behavior and failure semantics. Frontend Init and +Frame assembly is unchanged. diff --git a/docs/specs/runtime/02c-program-registry-and-pbx-v1.md b/docs/specs/runtime/02c-program-registry-and-pbx-v1.md index 5c72fdb..53f525c 100644 --- a/docs/specs/runtime/02c-program-registry-and-pbx-v1.md +++ b/docs/specs/runtime/02c-program-registry-and-pbx-v1.md @@ -81,11 +81,34 @@ Encoding primitives: list=`count:u32` followed by records; optional name=`presen | Trait payload | ordered method list; each method has optional name, explicit-parameter list, result list; concrete receiver is not repeated here | | Fn payload | ordered parameter list, result list; names do not define identity | | Captures section | function_count:u32, then each FunctionId in order: capture_count:u32 and TypeIds:u32; counts match functions, empty lists explicit | -| Function | optional name, parameter list, result list, code_offset:u32, code_len:u32, local_slots:u32, max_stack_slots:u32 | +| Function | lifecycle_role:u8, optional name, parameter list, result list, code_offset:u32, code_len:u32, local_slots:u32, max_stack_slots:u32 | | Implementation | owner_type_id:u32, trait_type_id:u32, method_count:u32, FunctionIds:u32 in trait-method order; count must match | Code offsets are relative to Code. Local and temporary counts widen from current u16 without truncation. `max_stack_slots` counts temporaries only; zero means zero, never infer. No guest-controlled builtin layouts or raw Rust structures/pointers are serialized. Remove old/external compatibility; regeneration is mandatory. +## Optional lifecycle roles + +The executable Function record carries one role byte before its optional name: +`0=None`, `1=BeforePause`, `2=BeforeResume`. Zero means an ordinary function, +not a callable hook. Unknown values reject with InvalidRegistry/LifecycleRole. +Each nonzero role has at most one target; duplicates reject with +InvalidRegistry/DuplicateLifecycleRole. Targets MUST NOT be FunctionId 0 and +MUST have zero parameters, results and captures; violations reject with +InvalidEntrypoint/LifecycleSignature. Preserve function/section context and the +wire offset when decoding an invalid role. Resolve optional FunctionIds once +in the immutable Registry. Names, exports, manifests and trait Method records +are not the binding mechanism. + +Either hook may be absent. Additional roles require a future contract; there is +no termination role. PBX remains version 1, with no old-layout fallback or +external-artifact compatibility. Producers MUST regenerate their images and +emit this byte for every function, including zero for ordinary functions. +Frontend compilers choose their own source syntax and lower it to these roles. +Their existing Init/Frame boot assembly remains frontend-owned; runtime keeps +FunctionId 0 as its ordinary entry and does not introduce Init/Frame roles. + +Execution ordering and limits are defined in [lifecycle](09a-coroutines-and-cooperative-scheduling.md). + ## Values, storage and initialization Value remains the generic stack/local representation. Structs/arrays are references; primitive and builtin-value array elements are stored directly. Layout descriptors distinguish value-slot width from heap-instance layout and distinguish GC references from native ownership. Derive offsets/defaults/maps once; access by indices/offsets rather than repeatedly traversing semantic metadata. Measure bitmap versus offset/block lists; changing the map encoding must not change the contract. diff --git a/docs/specs/runtime/09-events-and-concurrency.md b/docs/specs/runtime/09-events-and-concurrency.md index a0b2ae4..a3e866a 100644 --- a/docs/specs/runtime/09-events-and-concurrency.md +++ b/docs/specs/runtime/09-events-and-concurrency.md @@ -97,7 +97,8 @@ Sync Phase Important properties: - events are processed at known points; -- no execution occurs outside the frame loop; +- normal gameplay executes inside the frame loop; optional SystemOS lifecycle + hooks execute outside it with an independent budget; - frame structure remains observable for host tooling and host-owned certification. ## 7 Foreground Lifecycle Events @@ -111,7 +112,9 @@ The Game pause path is: Home/SystemOS request -> pause event becomes visible to the Game -> bounded pause reaction budget - -> SystemOS suspension, even if the Game did not cooperate + -> leave gameplay execution + -> optional BeforePause hook + -> SystemOS suspension on normal completion, or session failure ``` The Game resume path is: @@ -120,7 +123,8 @@ The Game resume path is: SystemOS resume request -> VM reactivation -> resume or foreground-restore event becomes visible to the Game - -> Game may synchronize while still internally paused + -> optional BeforeResume hook + -> normal gameplay becomes eligible after successful return -> visual foreground returns after a valid current-epoch render submission ``` @@ -128,10 +132,11 @@ SystemOS resume request scheduler/runtime state. A Game may observe pause/resume, but it must not control whether SystemOS suspends or resumes the VM. -When SystemOS replaces one Game with another from Home, the old Game MAY receive -a cooperative terminate/save lifecycle event if the runtime supports such an -event. That event is non-blocking in v1. SystemOS remains authoritative and may -close the old Game task/session without guest acknowledgement. +Registry hooks are optional and independent. Their binding, single-context call +boundary, fuel and debugger semantics follow [the lifecycle contract](09a-coroutines-and-cooperative-scheduling.md#controlled-lifecycle-calls). +Existing pending native lifecycle delivery bookkeeping remains separate; it is +not a new guest event API. There is no termination hook. SystemOS may close an +old Game task/session without guest acknowledgement when replacing it. Pause budgets are measured in deterministic machine units, not host wall-clock time. A suspended Game receives no normal gameplay ticks, no normal Game input, diff --git a/docs/specs/runtime/09a-coroutines-and-cooperative-scheduling.md b/docs/specs/runtime/09a-coroutines-and-cooperative-scheduling.md index 32dc692..501b6f1 100644 --- a/docs/specs/runtime/09a-coroutines-and-cooperative-scheduling.md +++ b/docs/specs/runtime/09a-coroutines-and-cooperative-scheduling.md @@ -13,7 +13,8 @@ diagnostic decoding can identify retired numbers. No compatibility mode exists. Other instruction numbers are unchanged. FRAME_SYNC closes a logical frame and preserves context. It has zero stack effect, -is not a terminator, can occur in any body and resumes next PC. Host MUST NOT +is not a terminator and resumes next PC. It is forbidden while a lifecycle hook +is active, including in its callees. Host MUST NOT prepare fresh entry solely because sync occurred. Budget exhaustion/breakpoints preserve the same open frame without draw publication or extra callback budget. @@ -34,3 +35,53 @@ and invoke typed Fn callbacks. UI/SDK APIs and future coroutine protocols requir separate contracts. See [Fn](02b-vm-function-values-and-closures.md), [events](09-events-and-concurrency.md) and [memory](03-memory-stack-heap-and-allocation.md). + +## Controlled lifecycle calls + +SystemOS optionally invokes the Registry's BeforePause and BeforeResume roles. +BeforePause runs after leaving the existing gameplay loop/handoff and before OS +suspension completes. BeforeResume runs after reactivation and before any normal +gameplay instruction. Neither hook is required, takes arguments, returns a +value, or vetoes the transition. Absence preserves the existing transition. +Direct suspension and Shell foreground handoff obey the same ordering; they do +not add a gameplay reaction tick. Home retains its existing one-tick handoff. + +A controlled call appends a frame and locals to the same VM stacks. It retains +the previous PC, halted state and stack boundaries; all suspended stack values, +frame environments, globals and heap references remain roots. Existing stack, +call-depth and allocation quotas include retained frames. Reserve before entry +mutation. Ordinary calls inside the hook work normally. On successful outer +return (including a branch to function end), restore the continuation and return +immediately to SystemOS, even if the execution slice has unused cycles. Never +clear the stacks with boot-entry preparation or execute gameplay in that slice. +Global/heap mutations persist. There is at most one lifecycle invocation per +session; duplicate requests do not reenter or renew it, and conflicting pending +transitions reject. + +Each invocation receives 1,500,000 virtual cycles total, sliced at no more than +250,000 admitted cycles per host update. This budget is independent of normal +logical frames and never renews between slices or debugger stops. Positive +remaining budget admits a whole instruction and allows its existing overshoot. +A normal completed return succeeds even if that final instruction consumes the +remaining budget; an unfinished invocation at exhaustion fails. There is no +wall-clock deadline. Breakpoints preserve the invocation and remaining budget; +while stopped, no cycles or gameplay frames advance. Instruction stepping uses +the same budget and the session's real service context. + +FRAME_SYNC traps before frame/GC/publication effects, including from ordinary +callees. Fatal traps, host errors/panics and total exhaustion fail the session, +block gameplay and report the failing phase through the existing crash path. +There is no retry, rollback of earlier mutations or compensating other hook. +Normal service-result errors remain guest data. HALT closes the task through +the OS termination path; it is not successful hook return. + +Hooks use the existing services and capability checks. No automatic save, +flush, disk-completion wait, guest event queue or reason argument is added. +Host-owned in-flight work keeps its ownership until the service/host safely +releases it; lifecycle failure does not simulate cancellation or free borrowed +buffers. Native calls must return promptly: VM fuel only bounds bytecode and +cannot preempt a blocked native/host call. Existing FS read/write and the current +memcard commit backend are synchronous interfaces, so this implementation does +not promise a wall-time bound for them. The new asynchronous memcard backend +must expose bounded submission/polling independently; hooks can then submit an +explicit commit without waiting for disk completion. diff --git a/test-cartridges/dummy-boy/program.pbx b/test-cartridges/dummy-boy/program.pbx index e4b6ecdd20df0fe61c7d529f97f0c177a3c29a5c..c4e883cee00729a0cba1d1c6fe7ebbeccfda9d9b 100644 GIT binary patch delta 105 zcmcc3e2000Nt_%50|OHfuLI%}K+FupWsD3AB0!o2h`WGn0U*r^#It~GBOuKN#AkqP akUTpOUx2bXfb1(kHi!lRMuv?Oy%+(71PYq~ delta 104 zcmcb^e4BZKNvtdb0|OHfuLa^0K+FuprHl*=B0!o2h&zF70U*r^#4~|xBOuKN#HWF5 ZkUTpOpNFzJfb7daHi!lR#*LG_7y)_33X=c; diff --git a/test-cartridges/stress-console/program.pbx b/test-cartridges/stress-console/program.pbx index 3b64b507db81d6681447e8061759c1689be4ab04..07ca8f2dde61d4d578e7098862881e6bbe177178 100644 GIT binary patch delta 95 zcmcb>d69F1NuV490|OHf-vMGfW(EczVvu5CU=RV)K#D;RNC*IFRv@+mvYUZ48xS7^ YvO)6fKztO+<^Zx!PHgqsc#eq$0O33eqyPW_ delta 95 zcmcb}d4Y3+NuVqP0|OHf-v(kkW(EczVvuBEU=RV)K#D;ZNC*IFRv@+ovYUZ48xS7= YvO)6fKzszs<^Zx!Olod5s;