implements PLN-0097

This commit is contained in:
2026-06-05 09:58:41 +01:00
parent e4c1390614
commit 8cd218dc04
4 changed files with 240 additions and 2 deletions
@@ -0,0 +1,236 @@
use super::FrameScheduler;
use super::frame_scheduler::FrameAuthorizationError;
use super::render_manager::{
LocalRenderWorker, RenderConsumeOutcome, RenderConsumerPath, RenderExecutionPolicy,
RenderPacingPolicy, RenderPolicy, RenderRuntimeCapabilities, RenderSurface,
};
use prometeu_hal::app_mode::AppMode;
use prometeu_hal::telemetry::AtomicTelemetry;
use prometeu_hal::{
FrameId, Game2DFramePacket, RenderOwnership, RenderSubmission, RenderSubmissionPacket,
ShellUiFramePacket,
};
use std::sync::Arc;
use std::sync::atomic::AtomicU32;
use super::render_manager::RenderManager;
struct ContractMatrixRow {
invariant: &'static str,
validations: &'static [&'static str],
}
const ASYNC_RENDER_CONTRACT_MATRIX: &[ContractMatrixRow] = &[
ContractMatrixRow {
invariant: "complete packet and AppMode policy are explicit",
validations: &["matrix_packet_policy_and_pacing_are_mode_specific"],
},
ContractMatrixRow {
invariant: "handoff is single-slot latest-wins in sync and worker-capable paths",
validations: &["matrix_sync_and_worker_paths_share_latest_wins_handoff_contract"],
},
ContractMatrixRow {
invariant: "render consumers see resource banks through read-only access",
validations: &[
"prometeu-drivers::render_resource_access_traits_are_thread_safe",
"prometeu-drivers::render_resource_access_exposes_read_only_glyph_and_scene_banks",
],
},
ContractMatrixRow {
invariant: "Game pacing is frame scheduled and does not catch up skipped frames",
validations: &["matrix_packet_policy_and_pacing_are_mode_specific"],
},
ContractMatrixRow {
invariant: "ownership epoch prevents obsolete work from presenting",
validations: &["matrix_epoch_stale_discard_and_telemetry_sync_remain_consistent"],
},
ContractMatrixRow {
invariant: "telemetry exposes production, drops, consumes, presents, repeats, and errors",
validations: &[
"matrix_epoch_stale_discard_and_telemetry_sync_remain_consistent",
"matrix_shutdown_failure_and_repeat_are_observable",
],
},
ContractMatrixRow {
invariant: "shutdown discards pending work and bounded local worker failure is contained",
validations: &["matrix_shutdown_failure_and_repeat_are_observable"],
},
ContractMatrixRow {
invariant: "active-scene Game2D overlay is composed after layer blit",
validations: &[
"prometeu-drivers::publish_game2d_submission_applies_gfx2d_overlay_after_active_scene",
],
},
];
#[derive(Default)]
struct RecordingSurface {
seen: Vec<FrameId>,
}
impl RenderSurface for RecordingSurface {
fn consume_submission(&mut self, submission: &RenderSubmission) {
self.seen.push(submission.frame_id);
}
}
struct PanickingSurface;
impl RenderSurface for PanickingSurface {
fn consume_submission(&mut self, _submission: &RenderSubmission) {
panic!("matrix present failure");
}
}
fn close_game(manager: &mut RenderManager) {
manager
.close_frame_with_packet(RenderSubmissionPacket::Game2D(Game2DFramePacket::default()))
.expect("game packet must match Game mode");
}
fn close_shell(manager: &mut RenderManager) {
manager
.close_frame_with_packet(RenderSubmissionPacket::ShellUi(ShellUiFramePacket::new(
Vec::new(),
)))
.expect("shell packet must match Shell mode");
}
#[test]
fn async_render_contract_matrix_rows_have_validation() {
assert!(ASYNC_RENDER_CONTRACT_MATRIX.len() >= 7);
for row in ASYNC_RENDER_CONTRACT_MATRIX {
assert!(!row.invariant.is_empty());
assert!(!row.validations.is_empty(), "missing validation for {}", row.invariant);
}
}
#[test]
fn matrix_packet_policy_and_pacing_are_mode_specific() {
let game_policy = RenderPolicy::for_app_mode(AppMode::Game);
assert_eq!(game_policy.pacing, RenderPacingPolicy::FrameScheduled);
assert_eq!(game_policy.execution, RenderExecutionPolicy::WorkerCapableWithLocalFallback);
assert_eq!(
game_policy.resolve_consumer_path(RenderRuntimeCapabilities { game_render_worker: true }),
RenderConsumerPath::LocalWorkerPrototype
);
let shell_policy = RenderPolicy::for_app_mode(AppMode::Shell);
assert_eq!(shell_policy.pacing, RenderPacingPolicy::LifecycleDriven);
assert_eq!(shell_policy.execution, RenderExecutionPolicy::LocalSynchronous);
assert_eq!(
shell_policy.resolve_consumer_path(RenderRuntimeCapabilities { game_render_worker: true }),
RenderConsumerPath::LocalSynchronous
);
let mut game_manager = RenderManager::new(AppMode::Game);
close_game(&mut game_manager);
assert!(
game_manager
.close_frame_with_packet(RenderSubmissionPacket::ShellUi(ShellUiFramePacket::new(
Vec::new()
)))
.is_err()
);
let mut shell_manager = RenderManager::new(AppMode::Shell);
close_shell(&mut shell_manager);
assert!(
shell_manager
.close_frame_with_packet(RenderSubmissionPacket::Game2D(Game2DFramePacket::default()))
.is_err()
);
let mut scheduler = FrameScheduler::default();
assert_eq!(scheduler.authorize_game_frame(), Ok(FrameId::ZERO));
scheduler.record_logical_frame_overrun();
assert_eq!(
scheduler.authorize_game_frame(),
Err(FrameAuthorizationError::GameFrameAlreadyActive { active_frame_id: FrameId::ZERO })
);
assert_eq!(scheduler.complete_game_frame(), Some(FrameId::ZERO));
assert_eq!(scheduler.authorize_game_frame(), Ok(FrameId::new(1)));
}
#[test]
fn matrix_sync_and_worker_paths_share_latest_wins_handoff_contract() {
fn consume_with(path: RenderConsumerPath) -> (RenderConsumeOutcome, Vec<FrameId>, u64) {
let mut manager = RenderManager::new(AppMode::Game);
let mut surface = RecordingSurface::default();
close_game(&mut manager);
close_game(&mut manager);
let outcome = match path {
RenderConsumerPath::LocalSynchronous => manager.consume_latest(&mut surface),
RenderConsumerPath::LocalWorkerPrototype => {
let mut worker = LocalRenderWorker;
worker.consume_latest(&mut manager, &mut surface)
}
};
(outcome, surface.seen, manager.render_telemetry().replaced_before_consume)
}
for path in [RenderConsumerPath::LocalSynchronous, RenderConsumerPath::LocalWorkerPrototype] {
let (outcome, seen, replaced) = consume_with(path);
assert_eq!(outcome, RenderConsumeOutcome::Presented { frame_id: FrameId::new(1) });
assert_eq!(seen, vec![FrameId::new(1)]);
assert_eq!(replaced, 1);
}
}
#[test]
fn matrix_epoch_stale_discard_and_telemetry_sync_remain_consistent() {
let mut manager = RenderManager::new(AppMode::Game);
let mut surface = RecordingSurface::default();
let atomic = AtomicTelemetry::new(Arc::new(AtomicU32::new(0)));
manager.transition_render_owner(AppMode::Game, 7);
close_game(&mut manager);
manager.transition_render_owner(AppMode::Game, 8);
assert_eq!(
manager.consume_latest(&mut surface),
RenderConsumeOutcome::DiscardedStaleEpoch { frame_id: FrameId::ZERO }
);
assert!(surface.seen.is_empty());
manager.sync_telemetry(&atomic);
let snapshot = atomic.snapshot();
assert_eq!(snapshot.produced_submissions, 1);
assert_eq!(snapshot.stale_epoch_discards, 1);
assert_eq!(snapshot.presented_frames, 0);
assert_eq!(snapshot.last_dropped_frame_id, 0);
assert_eq!(snapshot.active_render_epoch, 2);
assert_eq!(manager.active_ownership(), RenderOwnership::new(2, AppMode::Game, 8));
}
#[test]
fn matrix_shutdown_failure_and_repeat_are_observable() {
let mut manager = RenderManager::new(AppMode::Game);
close_game(&mut manager);
let discarded = manager.request_shutdown().expect("pending frame discarded");
assert_eq!(discarded.frame_id, FrameId::ZERO);
manager.resume_consumer();
close_game(&mut manager);
let mut surface = PanickingSurface;
assert_eq!(
manager.consume_latest(&mut surface),
RenderConsumeOutcome::PresentFailed {
frame_id: FrameId::new(1),
message: "matrix present failure".to_string()
}
);
manager.record_repeated_present(FrameId::new(1));
let telemetry = manager.render_telemetry();
assert_eq!(telemetry.shutdown_discards, 1);
assert_eq!(telemetry.present_errors, 1);
assert_eq!(telemetry.presented_frames, 0);
assert_eq!(telemetry.repeated_presents, 1);
assert_eq!(telemetry.last_error_frame_id, 1);
assert_eq!(telemetry.last_presented_frame_id, 1);
}
@@ -1,3 +1,5 @@
#[cfg(test)]
mod async_render_contract_tests;
mod dispatch;
mod frame_scheduler;
mod lifecycle;