implements PLN-0089

crates/console/prometeu-system/src/services/vm_runtime/render_manager.rs

@@ -18,11 +18,59 @@ pub trait RenderSurface {
     fn consume_submission(&mut self, submission: &RenderSubmission);
 }
 
+#[derive(Debug, Clone, Default)]
+pub struct RenderHandoff {
+    pending: Option<RenderSubmission>,
+    last_consumed: Option<RenderSubmission>,
+    replaced_before_consume: u64,
+    discarded_pending: u64,
+}
+
+impl RenderHandoff {
+    pub fn publish(&mut self, submission: RenderSubmission) {
+        if self.pending.replace(submission).is_some() {
+            self.replaced_before_consume = self.replaced_before_consume.wrapping_add(1);
+        }
+    }
+
+    pub fn pending_submission(&self) -> Option<&RenderSubmission> {
+        self.pending.as_ref()
+    }
+
+    pub fn latest_submission(&self) -> Option<&RenderSubmission> {
+        self.pending.as_ref().or(self.last_consumed.as_ref())
+    }
+
+    pub fn take_latest(&mut self) -> Option<RenderSubmission> {
+        self.pending.take()
+    }
+
+    pub fn record_consumed(&mut self, submission: RenderSubmission) {
+        self.last_consumed = Some(submission);
+    }
+
+    pub fn discard_pending(&mut self) -> Option<RenderSubmission> {
+        let discarded = self.pending.take();
+        if discarded.is_some() {
+            self.discarded_pending = self.discarded_pending.wrapping_add(1);
+        }
+        discarded
+    }
+
+    pub fn replaced_before_consume(&self) -> u64 {
+        self.replaced_before_consume
+    }
+
+    pub fn discarded_pending(&self) -> u64 {
+        self.discarded_pending
+    }
+}
+
 #[derive(Debug, Clone)]
 pub struct RenderManager {
     active_app_mode: AppMode,
     next_frame_id: FrameId,
-    latest_complete_submission: Option<RenderSubmission>,
+    handoff: RenderHandoff,
     transition_state: RenderTransitionState,
 }
 
@@ -31,7 +79,7 @@ impl RenderManager {
         Self {
             active_app_mode,
             next_frame_id: FrameId::ZERO,
-            latest_complete_submission: None,
+            handoff: RenderHandoff::default(),
             transition_state: RenderTransitionState::Idle,
         }
     }
@@ -45,7 +93,23 @@ impl RenderManager {
     }
 
     pub fn latest_complete_submission(&self) -> Option<&RenderSubmission> {
-        self.latest_complete_submission.as_ref()
+        self.handoff.latest_submission()
+    }
+
+    pub fn pending_submission(&self) -> Option<&RenderSubmission> {
+        self.handoff.pending_submission()
+    }
+
+    pub fn replaced_before_consume(&self) -> u64 {
+        self.handoff.replaced_before_consume()
+    }
+
+    pub fn discarded_pending(&self) -> u64 {
+        self.handoff.discarded_pending()
+    }
+
+    pub fn discard_pending_submission(&mut self) -> Option<RenderSubmission> {
+        self.handoff.discard_pending()
     }
 
     pub fn set_active_app_mode(&mut self, app_mode: AppMode) {
@@ -80,8 +144,8 @@ impl RenderManager {
         };
 
         self.next_frame_id = self.next_frame_id.next();
-        self.latest_complete_submission = Some(submission);
-        Ok(self.latest_complete_submission.as_ref().expect("submission was just stored"))
+        self.handoff.publish(submission);
+        Ok(self.handoff.pending_submission().expect("submission was just stored"))
     }
 
     pub fn close_compat_frame(&mut self) -> &RenderSubmission {
@@ -93,11 +157,12 @@ impl RenderManager {
         self.close_frame_with_packet(packet).expect("compat packet matches active app mode")
     }
 
-    pub fn publish_latest<S: RenderSurface>(&self, surface: &mut S) -> bool {
-        let Some(submission) = self.latest_complete_submission.as_ref() else {
+    pub fn publish_latest<S: RenderSurface>(&mut self, surface: &mut S) -> bool {
+        let Some(submission) = self.handoff.take_latest() else {
             return false;
         };
-        surface.consume_submission(submission);
+        surface.consume_submission(&submission);
+        self.handoff.record_consumed(submission);
         true
     }
 }
@@ -185,4 +250,56 @@ mod tests {
 
         assert_eq!(surface.seen, vec![FrameId::new(0)]);
     }
+
+    #[test]
+    fn render_handoff_takes_owned_latest_submission() {
+        let mut handoff = RenderHandoff::default();
+
+        assert!(handoff.take_latest().is_none());
+        handoff.publish(RenderSubmission::game2d(FrameId::new(7), Game2DFramePacket::default()));
+
+        let submission = handoff.take_latest().expect("pending submission");
+        assert_eq!(submission.frame_id, FrameId::new(7));
+        assert!(handoff.take_latest().is_none());
+    }
+
+    #[test]
+    fn render_handoff_counts_replacement_before_consume() {
+        let mut handoff = RenderHandoff::default();
+
+        handoff.publish(RenderSubmission::game2d(FrameId::new(1), Game2DFramePacket::default()));
+        handoff.publish(RenderSubmission::game2d(FrameId::new(2), Game2DFramePacket::default()));
+
+        assert_eq!(handoff.replaced_before_consume(), 1);
+        assert_eq!(handoff.take_latest().expect("latest").frame_id, FrameId::new(2));
+    }
+
+    #[test]
+    fn render_handoff_discards_pending_submission() {
+        let mut handoff = RenderHandoff::default();
+
+        assert!(handoff.discard_pending().is_none());
+        handoff.publish(RenderSubmission::game2d(FrameId::new(3), Game2DFramePacket::default()));
+
+        let discarded = handoff.discard_pending().expect("discarded pending");
+        assert_eq!(discarded.frame_id, FrameId::new(3));
+        assert_eq!(handoff.discarded_pending(), 1);
+        assert!(handoff.take_latest().is_none());
+    }
+
+    #[test]
+    fn publish_latest_consumes_pending_but_keeps_observable_last_submission() {
+        let mut manager = RenderManager::new(AppMode::Game);
+        let mut surface = RecordingSurface::default();
+
+        manager.close_compat_frame();
+        assert!(manager.pending_submission().is_some());
+        assert!(manager.publish_latest(&mut surface));
+
+        assert!(manager.pending_submission().is_none());
+        assert_eq!(
+            manager.latest_complete_submission().expect("last consumed").frame_id,
+            FrameId::ZERO
+        );
+    }
 }

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":"open","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":"open","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":"open","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":"open","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":"open","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-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"}]}

discussion/workflow/plans/PLN-0089-introduce-render-handoff-abstraction.md

@@ -2,7 +2,7 @@
 id: PLN-0089
 ticket: vm-render-parallel-execution-boundary
 title: Introduce Render Handoff Abstraction
-status: open
+status: done
 created: 2026-06-05
 ref_decisions: [DEC-0031]
 tags: [runtime, renderer, handoff, latest-wins]