From 3521eec319481f56b735ac5f42ae12607c2d005d Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Fri, 5 Jun 2026 09:44:29 +0100 Subject: [PATCH] implements PLN-0092 --- crates/console/prometeu-hal/src/lib.rs | 4 +- .../prometeu-hal/src/render_submission.rs | 42 ++++++++- .../src/services/vm_runtime/lifecycle.rs | 2 +- .../src/services/vm_runtime/render_manager.rs | 94 +++++++++++++++++-- .../src/services/vm_runtime/tick.rs | 5 +- discussion/index.ndjson | 2 +- ...-add-render-epoch-ownership-transitions.md | 2 +- 7 files changed, 135 insertions(+), 16 deletions(-) diff --git a/crates/console/prometeu-hal/src/lib.rs b/crates/console/prometeu-hal/src/lib.rs index a9e65eef..fdd14e47 100644 --- a/crates/console/prometeu-hal/src/lib.rs +++ b/crates/console/prometeu-hal/src/lib.rs @@ -48,7 +48,7 @@ pub use native_interface::{NativeInterface, SyscallId}; pub use pad_bridge::PadBridge; pub use render_submission::{ BoundScenePacket, Camera2D, ComposerFramePacket, FrameId, Game2DFramePacket, GameSpritePacket, - Gfx2dCommand, GfxUiCommand, HudCommand, HudPacket, RenderSubmission, RenderSubmissionPacket, - ShellUiFramePacket, + Gfx2dCommand, GfxUiCommand, HudCommand, HudPacket, RenderOwnership, RenderSubmission, + RenderSubmissionPacket, ShellUiFramePacket, }; pub use touch_bridge::TouchBridge; diff --git a/crates/console/prometeu-hal/src/render_submission.rs b/crates/console/prometeu-hal/src/render_submission.rs index 3427f581..6f04e7ef 100644 --- a/crates/console/prometeu-hal/src/render_submission.rs +++ b/crates/console/prometeu-hal/src/render_submission.rs @@ -25,16 +25,32 @@ impl FrameId { pub struct RenderSubmission { pub frame_id: FrameId, pub app_mode: AppMode, + pub ownership: RenderOwnership, pub packet: RenderSubmissionPacket, } impl RenderSubmission { pub const fn game2d(frame_id: FrameId, packet: Game2DFramePacket) -> Self { - Self { frame_id, app_mode: AppMode::Game, packet: RenderSubmissionPacket::Game2D(packet) } + Self { + frame_id, + app_mode: AppMode::Game, + ownership: RenderOwnership::new(0, AppMode::Game, 0), + packet: RenderSubmissionPacket::Game2D(packet), + } } pub const fn shell_ui(frame_id: FrameId, packet: ShellUiFramePacket) -> Self { - Self { frame_id, app_mode: AppMode::Shell, packet: RenderSubmissionPacket::ShellUi(packet) } + Self { + frame_id, + app_mode: AppMode::Shell, + ownership: RenderOwnership::new(0, AppMode::Shell, 0), + packet: RenderSubmissionPacket::ShellUi(packet), + } + } + + pub const fn with_ownership(mut self, ownership: RenderOwnership) -> Self { + self.ownership = ownership; + self } pub const fn is_coherent(&self) -> bool { @@ -46,6 +62,19 @@ impl RenderSubmission { } } +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct RenderOwnership { + pub epoch: u64, + pub app_mode: AppMode, + pub app_id: u32, +} + +impl RenderOwnership { + pub const fn new(epoch: u64, app_mode: AppMode, app_id: u32) -> Self { + Self { epoch, app_mode, app_id } + } +} + #[derive(Debug, Clone, PartialEq, Eq)] pub enum RenderSubmissionPacket { Game2D(Game2DFramePacket), @@ -164,12 +193,21 @@ mod tests { let submission = RenderSubmission { frame_id: FrameId::new(1), app_mode: AppMode::Game, + ownership: RenderOwnership::new(0, AppMode::Game, 0), packet: RenderSubmissionPacket::ShellUi(ShellUiFramePacket::new(Vec::new())), }; assert!(!submission.is_coherent()); } + #[test] + fn ownership_can_be_stamped_by_runtime() { + let submission = RenderSubmission::game2d(FrameId::new(3), Game2DFramePacket::default()) + .with_ownership(RenderOwnership::new(9, AppMode::Game, 42)); + + assert_eq!(submission.ownership, RenderOwnership::new(9, AppMode::Game, 42)); + } + #[test] fn closed_submission_owns_command_payload() { let mut commands = vec![Gfx2dCommand::DrawText { diff --git a/crates/console/prometeu-system/src/services/vm_runtime/lifecycle.rs b/crates/console/prometeu-system/src/services/vm_runtime/lifecycle.rs index 10b570b9..7d64c02f 100644 --- a/crates/console/prometeu-system/src/services/vm_runtime/lifecycle.rs +++ b/crates/console/prometeu-system/src/services/vm_runtime/lifecycle.rs @@ -156,7 +156,7 @@ impl VirtualMachineRuntime { self.current_cartridge_title = cartridge.title.clone(); self.current_cartridge_app_version = cartridge.app_version.clone(); self.current_cartridge_app_mode = cartridge.app_mode; - self.render_manager.set_active_app_mode(cartridge.app_mode); + self.render_manager.transition_render_owner(cartridge.app_mode, cartridge.app_id); Ok(()) } Err(e) => { diff --git a/crates/console/prometeu-system/src/services/vm_runtime/render_manager.rs b/crates/console/prometeu-system/src/services/vm_runtime/render_manager.rs index 715953db..6085b99a 100644 --- a/crates/console/prometeu-system/src/services/vm_runtime/render_manager.rs +++ b/crates/console/prometeu-system/src/services/vm_runtime/render_manager.rs @@ -1,12 +1,13 @@ use prometeu_hal::app_mode::AppMode; use prometeu_hal::{ - FrameId, Game2DFramePacket, RenderSubmission, RenderSubmissionPacket, ShellUiFramePacket, + FrameId, Game2DFramePacket, RenderOwnership, RenderSubmission, RenderSubmissionPacket, + ShellUiFramePacket, }; #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub enum RenderTransitionState { Idle, - Pending { from: AppMode, to: AppMode }, + Pending { from: RenderOwnership, to: RenderOwnership }, } #[derive(Debug, Clone, Copy, PartialEq, Eq)] @@ -64,6 +65,7 @@ pub struct RenderHandoff { last_consumed: Option, replaced_before_consume: u64, discarded_pending: u64, + stale_epoch_discards: u64, } impl RenderHandoff { @@ -89,6 +91,11 @@ impl RenderHandoff { self.last_consumed = Some(submission); } + pub fn record_stale_epoch_discard(&mut self, submission: RenderSubmission) { + self.stale_epoch_discards = self.stale_epoch_discards.wrapping_add(1); + self.last_consumed = Some(submission); + } + pub fn discard_pending(&mut self) -> Option { let discarded = self.pending.take(); if discarded.is_some() { @@ -104,11 +111,17 @@ impl RenderHandoff { pub fn discarded_pending(&self) -> u64 { self.discarded_pending } + + pub fn stale_epoch_discards(&self) -> u64 { + self.stale_epoch_discards + } } #[derive(Debug, Clone)] pub struct RenderManager { active_app_mode: AppMode, + active_app_id: u32, + active_ownership: RenderOwnership, active_policy: RenderPolicy, next_frame_id: FrameId, handoff: RenderHandoff, @@ -119,6 +132,8 @@ impl RenderManager { pub fn new(active_app_mode: AppMode) -> Self { Self { active_app_mode, + active_app_id: 0, + active_ownership: RenderOwnership::new(0, active_app_mode, 0), active_policy: RenderPolicy::for_app_mode(active_app_mode), next_frame_id: FrameId::ZERO, handoff: RenderHandoff::default(), @@ -130,6 +145,10 @@ impl RenderManager { self.active_app_mode } + pub fn active_ownership(&self) -> RenderOwnership { + self.active_ownership + } + pub fn active_render_policy(&self) -> RenderPolicy { self.active_policy } @@ -158,19 +177,31 @@ impl RenderManager { self.handoff.discarded_pending() } + pub fn stale_epoch_discards(&self) -> u64 { + self.handoff.stale_epoch_discards() + } + pub fn discard_pending_submission(&mut self) -> Option { self.handoff.discard_pending() } pub fn set_active_app_mode(&mut self, app_mode: AppMode) { - if self.active_app_mode == app_mode { + self.transition_render_owner(app_mode, self.active_app_id); + } + + pub fn transition_render_owner(&mut self, app_mode: AppMode, app_id: u32) { + if self.active_app_mode == app_mode && self.active_app_id == app_id { return; } - let previous = self.active_app_mode; + let previous = self.active_ownership; self.active_app_mode = app_mode; + self.active_app_id = app_id; + self.active_ownership = + RenderOwnership::new(self.active_ownership.epoch.wrapping_add(1), app_mode, app_id); self.active_policy = RenderPolicy::for_app_mode(app_mode); - self.transition_state = RenderTransitionState::Pending { from: previous, to: app_mode }; + self.transition_state = + RenderTransitionState::Pending { from: previous, to: self.active_ownership }; } pub fn acknowledge_transition(&mut self) { @@ -184,10 +215,10 @@ impl RenderManager { let frame_id = self.next_frame_id; let submission = match (self.active_app_mode, packet) { (AppMode::Game, RenderSubmissionPacket::Game2D(packet)) => { - RenderSubmission::game2d(frame_id, packet) + RenderSubmission::game2d(frame_id, packet).with_ownership(self.active_ownership) } (AppMode::Shell, RenderSubmissionPacket::ShellUi(packet)) => { - RenderSubmission::shell_ui(frame_id, packet) + RenderSubmission::shell_ui(frame_id, packet).with_ownership(self.active_ownership) } (active, _) => { return Err(RenderSubmissionError::PacketAppModeMismatch { active }); @@ -212,6 +243,10 @@ impl RenderManager { let Some(submission) = self.handoff.take_latest() else { return false; }; + if submission.ownership != self.active_ownership { + self.handoff.record_stale_epoch_discard(submission); + return false; + } surface.consume_submission(&submission); self.handoff.record_consumed(submission); true @@ -277,19 +312,45 @@ mod tests { #[test] fn app_mode_switch_records_noop_transition_placeholder() { let mut manager = RenderManager::new(AppMode::Game); + let previous = manager.active_ownership(); manager.set_active_app_mode(AppMode::Shell); assert_eq!(manager.active_app_mode(), AppMode::Shell); assert_eq!( manager.transition_state(), - RenderTransitionState::Pending { from: AppMode::Game, to: AppMode::Shell } + RenderTransitionState::Pending { + from: previous, + to: RenderOwnership::new(1, AppMode::Shell, 0) + } ); manager.acknowledge_transition(); assert_eq!(manager.transition_state(), RenderTransitionState::Idle); } + #[test] + fn transition_render_owner_increments_epoch_for_same_mode_app_swap() { + let mut manager = RenderManager::new(AppMode::Game); + + manager.transition_render_owner(AppMode::Game, 7); + let first_owner = manager.active_ownership(); + manager.transition_render_owner(AppMode::Game, 8); + + assert_eq!(first_owner, RenderOwnership::new(1, AppMode::Game, 7)); + assert_eq!(manager.active_ownership(), RenderOwnership::new(2, AppMode::Game, 8)); + } + + #[test] + fn close_frame_stamps_submission_with_active_ownership() { + let mut manager = RenderManager::new(AppMode::Game); + manager.transition_render_owner(AppMode::Game, 42); + + let submission = manager.close_compat_frame(); + + assert_eq!(submission.ownership, RenderOwnership::new(1, AppMode::Game, 42)); + } + #[test] fn render_policy_maps_game_to_frame_scheduled_worker_capable() { let policy = RenderPolicy::for_app_mode(AppMode::Game); @@ -382,4 +443,21 @@ mod tests { FrameId::ZERO ); } + + #[test] + fn publish_latest_discards_stale_epoch_before_present() { + let mut manager = RenderManager::new(AppMode::Game); + let mut surface = RecordingSurface::default(); + + manager.close_compat_frame(); + manager.transition_render_owner(AppMode::Shell, 1); + + assert!(!manager.publish_latest(&mut surface)); + assert!(surface.seen.is_empty()); + assert_eq!(manager.stale_epoch_discards(), 1); + assert_eq!( + manager.latest_complete_submission().expect("stale consumed for diagnostics").ownership, + RenderOwnership::new(0, AppMode::Game, 0) + ); + } } 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 7046fa4b..40d3782c 100644 --- a/crates/console/prometeu-system/src/services/vm_runtime/tick.rs +++ b/crates/console/prometeu-system/src/services/vm_runtime/tick.rs @@ -241,7 +241,10 @@ impl VirtualMachineRuntime { if run.reason == LogicalFrameEndingReason::FrameSync || run.reason == LogicalFrameEndingReason::EndOfRom { - self.render_manager.set_active_app_mode(self.current_cartridge_app_mode); + self.render_manager.transition_render_owner( + self.current_cartridge_app_mode, + self.current_app_id, + ); if self.current_cartridge_app_mode == AppMode::Game { let mut packet = hw.close_game2d_packet(); packet.gfx2d = std::mem::take(&mut self.gfx2d_commands); diff --git a/discussion/index.ndjson b/discussion/index.ndjson index 0d6a4ff7..474f6f9e 100644 --- a/discussion/index.ndjson +++ b/discussion/index.ndjson @@ -1,6 +1,6 @@ {"type":"meta","next_id":{"DSC":42,"AGD":42,"DEC":32,"PLN":98,"LSN":48,"CLSN":1}} {"type":"discussion","id":"DSC-0039","status":"abandoned","ticket":"render-pipeline-family-and-future-3d","title":"Render Pipeline Family and Future 3D","created_at":"2026-06-04","updated_at":"2026-06-04","tags":["gfx","renderer","runtime","architecture","pipeline"],"agendas":[{"id":"AGD-0039","file":"AGD-0039-render-pipeline-family-and-future-3d.md","status":"abandoned","created_at":"2026-06-04","updated_at":"2026-06-04","_override_reason":"User explicitly chose to close this agenda without a new decision because DSC-0038 already established enough architecture for future extension, and 3D is intentionally deferred."}],"decisions":[],"plans":[],"lessons":[],"_override_reason":"User explicitly chose to close this agenda without a new decision because DSC-0038 already established enough architecture for future extension, and 3D is intentionally deferred."} -{"type":"discussion","id":"DSC-0040","status":"in_progress","ticket":"vm-render-parallel-execution-boundary","title":"VM and Render Parallel Execution Boundary","created_at":"2026-06-04","updated_at":"2026-06-05","tags":["runtime","renderer","vm","concurrency","architecture","perf"],"agendas":[{"id":"AGD-0040","file":"AGD-0040-vm-and-render-parallel-execution-boundary.md","status":"accepted","created_at":"2026-06-04","updated_at":"2026-06-05"}],"decisions":[{"id":"DEC-0031","file":"DEC-0031-vm-and-render-parallel-execution-boundary.md","status":"accepted","created_at":"2026-06-05","updated_at":"2026-06-05","ref_agenda":"AGD-0040"}],"plans":[{"id":"PLN-0087","file":"PLN-0087-fix-game2d-packet-overlay-composition.md","status":"done","created_at":"2026-06-05","updated_at":"2026-06-05","ref_decisions":["DEC-0031"]},{"id":"PLN-0088","file":"PLN-0088-define-read-only-render-resource-boundary.md","status":"done","created_at":"2026-06-05","updated_at":"2026-06-05","ref_decisions":["DEC-0031"]},{"id":"PLN-0089","file":"PLN-0089-introduce-render-handoff-abstraction.md","status":"done","created_at":"2026-06-05","updated_at":"2026-06-05","ref_decisions":["DEC-0031"]},{"id":"PLN-0090","file":"PLN-0090-add-render-frame-pacing-contract.md","status":"done","created_at":"2026-06-05","updated_at":"2026-06-05","ref_decisions":["DEC-0031"]},{"id":"PLN-0091","file":"PLN-0091-implement-appmode-render-policy-matrix.md","status":"done","created_at":"2026-06-05","updated_at":"2026-06-05","ref_decisions":["DEC-0031"]},{"id":"PLN-0092","file":"PLN-0092-add-render-epoch-ownership-transitions.md","status":"open","created_at":"2026-06-05","updated_at":"2026-06-05","ref_decisions":["DEC-0031"]},{"id":"PLN-0093","file":"PLN-0093-add-render-telemetry-counters-and-events.md","status":"open","created_at":"2026-06-05","updated_at":"2026-06-05","ref_decisions":["DEC-0031"]},{"id":"PLN-0094","file":"PLN-0094-specify-async-render-boundary.md","status":"open","created_at":"2026-06-05","updated_at":"2026-06-05","ref_decisions":["DEC-0031"]},{"id":"PLN-0095","file":"PLN-0095-prototype-local-render-worker-capability.md","status":"open","created_at":"2026-06-05","updated_at":"2026-06-05","ref_decisions":["DEC-0031"]},{"id":"PLN-0096","file":"PLN-0096-define-render-shutdown-and-failure-handling.md","status":"open","created_at":"2026-06-05","updated_at":"2026-06-05","ref_decisions":["DEC-0031"]},{"id":"PLN-0097","file":"PLN-0097-add-async-render-integration-test-matrix.md","status":"open","created_at":"2026-06-05","updated_at":"2026-06-05","ref_decisions":["DEC-0031"]}],"lessons":[]} +{"type":"discussion","id":"DSC-0040","status":"in_progress","ticket":"vm-render-parallel-execution-boundary","title":"VM and Render Parallel Execution Boundary","created_at":"2026-06-04","updated_at":"2026-06-05","tags":["runtime","renderer","vm","concurrency","architecture","perf"],"agendas":[{"id":"AGD-0040","file":"AGD-0040-vm-and-render-parallel-execution-boundary.md","status":"accepted","created_at":"2026-06-04","updated_at":"2026-06-05"}],"decisions":[{"id":"DEC-0031","file":"DEC-0031-vm-and-render-parallel-execution-boundary.md","status":"accepted","created_at":"2026-06-05","updated_at":"2026-06-05","ref_agenda":"AGD-0040"}],"plans":[{"id":"PLN-0087","file":"PLN-0087-fix-game2d-packet-overlay-composition.md","status":"done","created_at":"2026-06-05","updated_at":"2026-06-05","ref_decisions":["DEC-0031"]},{"id":"PLN-0088","file":"PLN-0088-define-read-only-render-resource-boundary.md","status":"done","created_at":"2026-06-05","updated_at":"2026-06-05","ref_decisions":["DEC-0031"]},{"id":"PLN-0089","file":"PLN-0089-introduce-render-handoff-abstraction.md","status":"done","created_at":"2026-06-05","updated_at":"2026-06-05","ref_decisions":["DEC-0031"]},{"id":"PLN-0090","file":"PLN-0090-add-render-frame-pacing-contract.md","status":"done","created_at":"2026-06-05","updated_at":"2026-06-05","ref_decisions":["DEC-0031"]},{"id":"PLN-0091","file":"PLN-0091-implement-appmode-render-policy-matrix.md","status":"done","created_at":"2026-06-05","updated_at":"2026-06-05","ref_decisions":["DEC-0031"]},{"id":"PLN-0092","file":"PLN-0092-add-render-epoch-ownership-transitions.md","status":"done","created_at":"2026-06-05","updated_at":"2026-06-05","ref_decisions":["DEC-0031"]},{"id":"PLN-0093","file":"PLN-0093-add-render-telemetry-counters-and-events.md","status":"open","created_at":"2026-06-05","updated_at":"2026-06-05","ref_decisions":["DEC-0031"]},{"id":"PLN-0094","file":"PLN-0094-specify-async-render-boundary.md","status":"open","created_at":"2026-06-05","updated_at":"2026-06-05","ref_decisions":["DEC-0031"]},{"id":"PLN-0095","file":"PLN-0095-prototype-local-render-worker-capability.md","status":"open","created_at":"2026-06-05","updated_at":"2026-06-05","ref_decisions":["DEC-0031"]},{"id":"PLN-0096","file":"PLN-0096-define-render-shutdown-and-failure-handling.md","status":"open","created_at":"2026-06-05","updated_at":"2026-06-05","ref_decisions":["DEC-0031"]},{"id":"PLN-0097","file":"PLN-0097-add-async-render-integration-test-matrix.md","status":"open","created_at":"2026-06-05","updated_at":"2026-06-05","ref_decisions":["DEC-0031"]}],"lessons":[]} {"type":"discussion","id":"DSC-0041","status":"open","ticket":"foreground-stack-game-pause-shell-vm-backed","title":"Foreground Stack, Game Pause, and VM-Backed Shell Coexistence","created_at":"2026-06-05","updated_at":"2026-06-05","tags":["runtime","os","lifecycle","shell","game","vm","foreground","architecture"],"agendas":[{"id":"AGD-0041","file":"AGD-0041-foreground-stack-game-pause-shell-vm-backed.md","status":"open","created_at":"2026-06-05","updated_at":"2026-06-05"}],"decisions":[],"plans":[],"lessons":[]} {"type":"discussion","id":"DSC-0038","status":"done","ticket":"render-frame-packet-boundary","title":"Logical Render Pipelines and Command Packets","created_at":"2026-05-25","updated_at":"2026-06-04","tags":["gfx","renderer","runtime","frame-composer","architecture","ui","pipeline"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0047","file":"discussion/lessons/DSC-0038-render-frame-packet-boundary/LSN-0047-typed-render-submissions-preserve-domain-boundaries.md","status":"done","created_at":"2026-06-04","updated_at":"2026-06-04"}]} {"type":"discussion","id":"DSC-0035","status":"done","ticket":"task-owned-shell-windows","title":"Agenda - Task-Owned Shell Windows","created_at":"2026-05-15","updated_at":"2026-05-15","tags":["runtime","os","task","window-manager","shell","lifecycle"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0044","file":"discussion/lessons/DSC-0035-task-owned-shell-windows/LSN-0044-task-window-liveness-belongs-to-the-task.md","status":"done","created_at":"2026-05-15","updated_at":"2026-05-15"}]} diff --git a/discussion/workflow/plans/PLN-0092-add-render-epoch-ownership-transitions.md b/discussion/workflow/plans/PLN-0092-add-render-epoch-ownership-transitions.md index 4746f5fc..57f05e98 100644 --- a/discussion/workflow/plans/PLN-0092-add-render-epoch-ownership-transitions.md +++ b/discussion/workflow/plans/PLN-0092-add-render-epoch-ownership-transitions.md @@ -2,7 +2,7 @@ id: PLN-0092 ticket: vm-render-parallel-execution-boundary title: Add Render Epoch Ownership Transitions -status: open +status: done created: 2026-06-05 ref_decisions: [DEC-0031] tags: [runtime, lifecycle, render-epoch, ownership]