use std::fs; use std::path::Path; use prometeu_bytecode::SourceSpan; use prometeu_bytecode::assembler::assemble; use prometeu_bytecode::model::{BytecodeModule, DebugInfo, Export, FunctionMeta, SyscallDecl}; use prometeu_hal::InputSignals; use prometeu_hal::app_mode::AppMode; use prometeu_hal::color::Color; use prometeu_host_headless::{ AdvanceFrameOutcome, AdvanceFramesStop, CapturedFrame, HeadlessHost, HostError, HostExecutionStatus, HostState, }; use prometeu_system::CrashReport; const RED: u32 = Color::RED.raw(); const BLUE: u32 = Color::BLUE.raw(); const GREEN: u32 = Color::GREEN.raw(); const BLACK: u32 = Color::BLACK.raw(); #[test] fn headless_source_has_no_timing_wait_or_interactive_backend_dependency() { let source = include_str!("../src/host.rs"); let manifest = include_str!("../Cargo.toml"); for forbidden in ["FRAME_PUBLISH_SPINS", "spin_loop", "thread::sleep", "ensure_worker", "RenderWorkerConfig"] { assert!(!source.contains(forbidden), "headless source contains {forbidden}"); } for forbidden in ["winit", "pixels", "cpal"] { assert!(!manifest.contains(forbidden), "headless manifest contains {forbidden}"); } } #[test] fn lifecycle_state_and_preconditions_are_structural() { let mut host = HeadlessHost::new(); assert_eq!(host.get_state().status, HostExecutionStatus::Terminated); assert_eq!(host.capture_frame(), Err(HostError::NoFrameAvailable)); assert_eq!( host.pause(), Err(HostError::InvalidState { operation: "pause", status: HostExecutionStatus::Terminated, }) ); let cartridge = color_cartridge(); host.boot(&cartridge).expect("boot"); let booted = host.get_state(); assert_eq!(booted.status, HostExecutionStatus::Running); assert_eq!(booted.pc, 0, "boot must not execute the first game instruction"); assert_eq!(host.boot(&cartridge), Err(HostError::AlreadyBooted)); host.pause().expect("pause"); assert_eq!(host.get_state().status, HostExecutionStatus::Paused); host.resume().expect("resume"); assert_eq!(host.get_state().status, HostExecutionStatus::Running); } #[test] fn step_does_not_complete_a_logical_frame() { let mut host = boot_color(); let before = host.get_state(); assert_eq!(host.step().expect("step"), None); let after = host.get_state(); assert_eq!(after.frame_index, before.frame_index); assert_ne!(after.pc, before.pc); assert_eq!(after.status, HostExecutionStatus::Paused); } #[test] fn stepping_frame_sync_is_not_a_fault_or_completed_runtime_frame() { let dir = temp_cart("step-frame-sync"); write_cartridge(&dir, 51, "Step Frame Sync", &module(asm("FRAME_SYNC\nRET\n"), vec![]), &[]); let mut host = HeadlessHost::new(); host.boot(&dir).expect("boot frame-sync cartridge"); let before = host.get_state().frame_index; assert_eq!(host.step().expect("step frame sync"), None); assert_eq!(host.get_state().frame_index, before); assert!(host.get_fault().is_none()); assert_eq!(host.get_state().status, HostExecutionStatus::Paused); } #[test] fn one_logical_frame_may_span_multiple_internal_ticks() { let dir = temp_cart("multi-tick"); write_cartridge(&dir, 47, "Multi Tick", &multi_tick_program(), &[]); let mut host = HeadlessHost::new(); host.boot(&dir).expect("boot multi-tick cartridge"); let before = host.get_state(); completed(host.advance_frame().expect("multi-tick frame")); let after = host.get_state(); assert_eq!(after.frame_index, before.frame_index + 1); assert!(after.tick_index >= before.tick_index + 2); } #[test] fn outer_frame_limit_is_a_host_error_and_finishes_paused() { let dir = temp_cart("frame-limit"); write_cartridge(&dir, 50, "Frame Limit", &module(asm("JMP 0\n"), vec![]), &[]); let mut host = HeadlessHost::new(); host.boot(&dir).expect("boot non-closing cartridge"); assert_eq!( host.advance_frame(), Err(HostError::FrameAdvanceWatchdogExpired { host_tick_limit: 100_000 }) ); assert_eq!(host.get_state().status, HostExecutionStatus::Paused); assert!(host.get_fault().is_none()); } #[test] fn one_frame_returns_and_captures_the_exact_published_frame() { let mut host = boot_color(); let before = host.get_state().frame_index; let (logical_frame_index, frame_id) = completed(host.advance_frame().expect("frame")); let captured = host.capture_frame().expect("capture"); assert_eq!(logical_frame_index, before + 1); assert_eq!(captured.logical_frame_index, logical_frame_index); assert_eq!(captured.frame.frame_id, frame_id); assert_eq!(captured.frame.ownership.app_mode, AppMode::Game); assert_eq!(captured.frame.ownership.app_id, 41); assert_eq!(captured.frame.stride_pixels, captured.frame.width); assert_eq!(captured.frame.pixels.len(), 480 * 270); assert_eq!(host.capture_frame().expect("repeat capture"), captured); let mut mutated_clone = captured.clone(); mutated_clone.frame.pixels[0] = GREEN; assert_ne!(host.capture_frame().expect("owned capture").frame.pixels[0], GREEN); assert_eq!(host.get_state().status, HostExecutionStatus::Paused); } #[test] fn zero_frames_is_an_explicit_noop() { let mut host = boot_color(); let before = host.get_state(); let outcome = host.advance_frames(0).expect("zero frames"); assert_eq!(outcome.requested, 0); assert_eq!(outcome.completed, 0); assert_eq!(outcome.stop, AdvanceFramesStop::Completed); let after = host.get_state(); assert_eq!(after.frame_index, before.frame_index); assert_eq!(after.tick_index, before.tick_index); assert_eq!(after.status, before.status); } #[test] fn clear_input_drops_right() { let mut host = boot_color(); host.set_right(true); host.clear_input(); completed(host.advance_frame().expect("frame")); assert_color(&host.capture_frame().expect("frame"), BLUE); } #[test] fn right_hold_then_release_changes_pixels() { let mut host = boot_color(); let before = host.get_state().frame_index; host.set_right(true); assert_completed(host.advance_frames(60).expect("hold"), 60); let held = host.capture_frame().expect("held frame"); assert_eq!(host.get_state().frame_index, before + 60); assert_color(&held, RED); assert!(host.get_fault().is_none()); host.set_right(false); assert_completed(host.advance_frames(1).expect("release"), 1); let released = host.capture_frame().expect("released frame"); assert_eq!(released.logical_frame_index, before + 61); assert_color(&released, BLUE); assert!(host.get_fault().is_none()); } #[test] fn normalized_button_press_hold_release_and_clear_are_observable() { let mut host = boot_input_edges(); let mut signals = InputSignals { right_signal: true, ..InputSignals::default() }; host.set_input(signals); completed(host.advance_frame().expect("press")); assert_color(&host.capture_frame().expect("pressed"), RED); completed(host.advance_frame().expect("hold")); assert_color(&host.capture_frame().expect("held"), BLUE); signals.right_signal = false; host.set_input(signals); completed(host.advance_frame().expect("release")); assert_color(&host.capture_frame().expect("released"), GREEN); host.set_input(InputSignals { right_signal: true, f_signal: true, x_pos: 123, y_pos: 45, ..InputSignals::default() }); host.clear_input(); completed(host.advance_frame().expect("clear")); assert_color(&host.capture_frame().expect("cleared"), BLACK); } #[test] fn normalized_touch_edges_and_coordinates_use_the_same_input_surface() { let mut host = boot_touch_edges(); let mut signals = InputSignals { f_signal: true, x_pos: 123, y_pos: 45, ..InputSignals::default() }; host.set_input(signals); completed(host.advance_frame().expect("touch press")); assert_color(&host.capture_frame().expect("touch pressed"), RED); completed(host.advance_frame().expect("touch hold")); assert_color(&host.capture_frame().expect("touch held"), BLUE); signals.f_signal = false; host.set_input(signals); completed(host.advance_frame().expect("touch release")); assert_color(&host.capture_frame().expect("touch released"), GREEN); } #[test] fn two_runs_match_oracle() { let first = run_color_sequence(); let second = run_color_sequence(); assert_eq!(first.held.logical_frame_index, second.held.logical_frame_index); assert_eq!(first.held.frame.pixels, second.held.frame.pixels); assert_eq!(first.held.frame.frame_id, second.held.frame.frame_id); assert_eq!(first.released.frame.pixels, second.released.frame.pixels); assert_eq!(first.released.frame.frame_id, second.released.frame.frame_id); assert_eq!(first.released.logical_frame_index, second.released.logical_frame_index); assert_same_state(&first.state, &second.state); assert_eq!(first.fault, second.fault); } #[test] fn reset_matches_fresh_host() { let mut host = boot_color(); let _ = run_on(&mut host); host.reset(); assert_eq!(host.get_state().status, HostExecutionStatus::Terminated); assert_eq!(host.capture_frame(), Err(HostError::NoFrameAvailable)); host.boot(color_cartridge()).expect("reboot"); let after_reset = run_on(&mut host); let fresh = run_color_sequence(); assert_eq!(after_reset.held.frame.pixels, fresh.held.frame.pixels); assert_eq!(after_reset.released.frame.pixels, fresh.released.frame.pixels); assert_eq!(after_reset.held.frame.frame_id, fresh.held.frame.frame_id); assert_eq!(after_reset.released.frame.frame_id, fresh.released.frame.frame_id); assert_eq!(after_reset.released.logical_frame_index, fresh.released.logical_frame_index); assert_same_state(&after_reset.state, &fresh.state); assert_eq!(after_reset.fault, fresh.fault); } #[test] fn trap_is_structured() { let dir = temp_cart("fault"); write_cartridge(&dir, 42, "Fault", &fault_program(), &[]); let mut host = HeadlessHost::new(); host.boot(&dir).expect("boot fault cartridge"); let outcome = host.advance_frame().expect("faulting frame"); match outcome { AdvanceFrameOutcome::Faulted(CrashReport::VmTrap { trap }) => { assert_eq!(trap.code, prometeu_bytecode::TRAP_EXPLICIT); assert_eq!(trap.opcode, prometeu_bytecode::isa::core::CoreOpCode::Trap as u16); assert_eq!(trap.pc, 0); assert_eq!(trap.span, Some(SourceSpan { file_id: 7, start: 11, end: 15 })); assert!(trap.message.contains("main")); } other => panic!("expected VmTrap outcome, got {other:?}"), } assert!(matches!(host.get_fault(), Some(CrashReport::VmTrap { .. }))); assert_eq!(host.get_state().status, HostExecutionStatus::Faulted); } #[test] fn instruction_step_fault_remains_structured() { let dir = temp_cart("step-fault"); write_cartridge(&dir, 48, "Step Fault", &fault_program(), &[]); let mut host = HeadlessHost::new(); host.boot(&dir).expect("boot fault cartridge"); let report = host.step().expect("step result").expect("structured step fault"); assert!(matches!(report, CrashReport::VmTrap { .. })); assert_eq!(host.get_fault(), Some(report)); assert_eq!(host.get_state().status, HostExecutionStatus::Faulted); } #[test] fn batch_stops_early_on_fault_and_reports_partial_progress() { let dir = temp_cart("fault-batch"); write_cartridge(&dir, 43, "Fault Batch", &delayed_fault_program(), &gfx_syscalls()); let mut host = HeadlessHost::new(); host.boot(&dir).expect("boot fault cartridge"); let outcome = host.advance_frames(5).expect("batch outcome"); assert_eq!(outcome.requested, 5); assert_eq!(outcome.completed, 2); assert!(matches!(outcome.stop, AdvanceFramesStop::Faulted(CrashReport::VmTrap { .. }))); } #[test] fn advance_after_reset_reports_termination_without_ticking() { let mut host = boot_color(); host.reset(); let before = host.get_state().tick_index; assert_eq!(host.advance_frame().expect("termination outcome"), AdvanceFrameOutcome::Terminated); assert_eq!(host.get_state().tick_index, before); let batch = host.advance_frames(3).expect("terminated batch"); assert_eq!(batch.completed, 0); assert_eq!(batch.stop, AdvanceFramesStop::Terminated); } #[test] fn vm_init_failure_is_returned_as_structured_boot_failure() { let dir = temp_cart("bad-pbx"); write_cartridge(&dir, 44, "Bad PBX", b"not a pbx", &[]); let mut host = HeadlessHost::new(); let error = host.boot(&dir).expect_err("invalid PBX must fail boot"); assert!(matches!( error, HostError::BootFailed { report: Some(CrashReport::VmInit { .. }), .. } )); assert_eq!(host.get_state().status, HostExecutionStatus::Faulted); assert!(matches!(host.get_fault(), Some(CrashReport::VmInit { .. }))); } #[test] fn end_of_rom_completes_a_logical_frame() { let dir = temp_cart("end-of-rom"); write_cartridge(&dir, 45, "End Of Rom", &module(asm("RET\n"), vec![]), &[]); let mut host = HeadlessHost::new(); host.boot(&dir).expect("boot end-of-rom cartridge"); let first = completed(host.advance_frame().expect("first frame")); let second = completed(host.advance_frame().expect("second frame")); assert_eq!(second.0, first.0 + 1); assert_ne!(second.1, first.1); } #[test] fn three_hundred_frames_complete_without_realtime_pacing() { let mut host = boot_color(); assert_completed(host.advance_frames(300).expect("fast frames"), 300); } #[test] fn audio_play_does_not_need_a_device() { let mut host = boot_color(); completed(host.advance_frame().expect("frame with audio.play")); assert!(host.get_fault().is_none()); assert_color(&host.capture_frame().expect("frame"), BLUE); } struct ColorOracle { held: CapturedFrame, released: CapturedFrame, state: HostState, fault: Option, } fn boot_color() -> HeadlessHost { let mut host = HeadlessHost::new(); host.boot(color_cartridge()).expect("boot color cartridge"); host } fn boot_input_edges() -> HeadlessHost { let dir = temp_cart("input-edges"); write_cartridge(&dir, 46, "Input Edges", &input_edge_program(), &gfx_syscalls()); let mut host = HeadlessHost::new(); host.boot(&dir).expect("boot input cartridge"); host } fn boot_touch_edges() -> HeadlessHost { let dir = temp_cart("touch-edges"); write_cartridge(&dir, 49, "Touch Edges", &touch_edge_program(), &gfx_syscalls()); let mut host = HeadlessHost::new(); host.boot(&dir).expect("boot touch cartridge"); host } fn color_cartridge() -> String { let dir = temp_cart("color"); write_cartridge(&dir, 41, "Right Pixel", &color_program(), &color_syscalls()); dir } fn run_color_sequence() -> ColorOracle { let mut host = boot_color(); run_on(&mut host) } fn run_on(host: &mut HeadlessHost) -> ColorOracle { host.set_right(true); assert_completed(host.advance_frames(60).expect("hold"), 60); let held = host.capture_frame().expect("held"); host.set_right(false); assert_completed(host.advance_frames(1).expect("release"), 1); let released = host.capture_frame().expect("released"); let state = host.get_state(); let fault = host.get_fault(); ColorOracle { held, released, state, fault } } fn completed(outcome: AdvanceFrameOutcome) -> (u64, prometeu_hal::FrameId) { match outcome { AdvanceFrameOutcome::FrameCompleted { logical_frame_index, frame_id } => { (logical_frame_index, frame_id) } other => panic!("expected completed frame, got {other:?}"), } } fn assert_completed(outcome: prometeu_host_headless::AdvanceFramesOutcome, expected: u64) { assert_eq!(outcome.requested, expected); assert_eq!(outcome.completed, expected); assert_eq!(outcome.stop, AdvanceFramesStop::Completed); } fn assert_color(captured: &CapturedFrame, color: u32) { assert_eq!(captured.frame.width, 480); assert_eq!(captured.frame.height, 270); assert!(captured.frame.pixels.iter().all(|pixel| *pixel == color)); } fn assert_same_state(left: &HostState, right: &HostState) { assert_eq!(left.pc, right.pc); assert_eq!(left.frame_index, right.frame_index); assert_eq!(left.tick_index, right.tick_index); assert_eq!(left.app_id, right.app_id); assert_eq!(left.status, right.status); assert_eq!(format!("{:?}", left.stack_top), format!("{:?}", right.stack_top)); } fn temp_cart(name: &str) -> String { let dir = std::env::temp_dir().join(format!( "prometeu-headless-{name}-{}-{}", std::process::id(), std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).unwrap().as_nanos() )); fs::create_dir_all(&dir).expect("temp cartridge dir"); dir.to_string_lossy().into_owned() } fn write_cartridge(dir: &str, app_id: u32, title: &str, program: &[u8], syscalls: &[SyscallDecl]) { let path = Path::new(dir); fs::write(path.join("program.pbx"), program).expect("program"); fs::write( path.join("manifest.json"), format!( "{{\n \"magic\": \"PMTU\",\n \"cartridge_version\": 1,\n \"app_id\": {app_id},\n \"title\": \"{title}\",\n \"app_version\": \"0.1.0\",\n \"app_mode\": \"Game\",\n \"capabilities\": [\"gfx2d\", \"audio\"]\n}}\n" ), ) .expect("manifest"); let _ = syscalls; } fn color_program() -> Vec { let mut rom = Vec::new(); rom.extend(asm("PUSH_I32 0\n\ PUSH_I32 0\n\ PUSH_I32 0\n\ PUSH_I32 255\n\ PUSH_I32 128\n\ PUSH_I32 1\n\ PUSH_I32 0\n\ HOSTCALL 1\n\ POP_N 1\n\ INTRINSIC 0x210E\n")); let jump_to_blue = rom.len() + 2; rom.extend(asm("JMP_IF_FALSE 0")); rom.extend(asm(&format!("PUSH_I64 {RED}\nHOSTCALL 0\nFRAME_SYNC\nRET\n"))); let blue_at = rom.len() as u32; rom.extend(asm(&format!("PUSH_I64 {BLUE}\nHOSTCALL 0\nFRAME_SYNC\nRET\n"))); rom[jump_to_blue..jump_to_blue + 4].copy_from_slice(&blue_at.to_le_bytes()); module(rom, color_syscalls()) } fn input_edge_program() -> Vec { let mut rom = Vec::new(); let pressed_jump = emit_right_predicate(&mut rom, 0x210C); rom.extend(asm(&format!("PUSH_I64 {RED}\nHOSTCALL 0\nFRAME_SYNC\nRET\n"))); let released_at = rom.len() as u32; rom[pressed_jump..pressed_jump + 4].copy_from_slice(&released_at.to_le_bytes()); let released_jump = emit_right_predicate(&mut rom, 0x210D); rom.extend(asm(&format!("PUSH_I64 {GREEN}\nHOSTCALL 0\nFRAME_SYNC\nRET\n"))); let down_at = rom.len() as u32; rom[released_jump..released_jump + 4].copy_from_slice(&down_at.to_le_bytes()); let down_jump = emit_right_predicate(&mut rom, 0x210E); rom.extend(asm(&format!("PUSH_I64 {BLUE}\nHOSTCALL 0\nFRAME_SYNC\nRET\n"))); let idle_at = rom.len() as u32; rom[down_jump..down_jump + 4].copy_from_slice(&idle_at.to_le_bytes()); rom.extend(asm(&format!("PUSH_I64 {BLACK}\nHOSTCALL 0\nFRAME_SYNC\nRET\n"))); module(rom, gfx_syscalls()) } fn emit_right_predicate(rom: &mut Vec, predicate: u32) -> usize { rom.extend(asm(&format!("INTRINSIC {predicate:#x}\n"))); let target = rom.len() + 2; rom.extend(asm("JMP_IF_FALSE 0\n")); target } fn touch_edge_program() -> Vec { let mut rom = Vec::new(); let pressed_jump = emit_touch_predicate(&mut rom, 0x2130); rom.extend(asm(&format!("PUSH_I64 {RED}\nHOSTCALL 0\nFRAME_SYNC\nRET\n"))); let released_at = rom.len() as u32; rom[pressed_jump..pressed_jump + 4].copy_from_slice(&released_at.to_le_bytes()); let released_jump = emit_touch_predicate(&mut rom, 0x2131); rom.extend(asm(&format!("PUSH_I64 {GREEN}\nHOSTCALL 0\nFRAME_SYNC\nRET\n"))); let down_at = rom.len() as u32; rom[released_jump..released_jump + 4].copy_from_slice(&down_at.to_le_bytes()); let down_jump = emit_touch_predicate(&mut rom, 0x2132); rom.extend(asm(&format!("PUSH_I64 {BLUE}\nHOSTCALL 0\nFRAME_SYNC\nRET\n"))); let idle_at = rom.len() as u32; rom[down_jump..down_jump + 4].copy_from_slice(&idle_at.to_le_bytes()); rom.extend(asm(&format!("PUSH_I64 {BLACK}\nHOSTCALL 0\nFRAME_SYNC\nRET\n"))); module(rom, gfx_syscalls()) } fn emit_touch_predicate(rom: &mut Vec, predicate: u32) -> usize { rom.extend(asm(&format!( "INTRINSIC {predicate:#x}\n\ INTRINSIC 0x2134\nPUSH_I64 123\nEQ\nAND\n\ INTRINSIC 0x2135\nPUSH_I64 45\nEQ\nAND\n" ))); let target = rom.len() + 2; rom.extend(asm("JMP_IF_FALSE 0\n")); target } fn fault_program() -> Vec { // `INTRINSIC 0xDEADBEEF` is rejected by the loader as `VerificationFailed`. // `TRAP` is a legal instruction that becomes `CrashReport::VmTrap` at runtime. module(asm("TRAP\nFRAME_SYNC\nRET\n"), vec![]) } fn delayed_fault_program() -> Vec { let mut rom = asm("GET_GLOBAL 0\nPUSH_I32 1\nADD\nSET_GLOBAL 0\nGET_GLOBAL 0\nPUSH_I32 3\nEQ\n"); let continue_jump = rom.len() + 2; rom.extend(asm("JMP_IF_FALSE 0\nTRAP\n")); let continue_at = rom.len() as u32; rom[continue_jump..continue_jump + 4].copy_from_slice(&continue_at.to_le_bytes()); rom.extend(asm(&format!("PUSH_I64 {BLACK}\nHOSTCALL 0\nFRAME_SYNC\nRET\n"))); module(rom, gfx_syscalls()) } fn multi_tick_program() -> Vec { let mut rom = asm("PUSH_I32 30000\nSET_LOCAL 0\n"); let loop_at = rom.len() as u32; rom.extend(asm("GET_LOCAL 0\nPUSH_I32 1\nSUB\nSET_LOCAL 0\nGET_LOCAL 0\nPUSH_I32 0\nGT\n")); rom.extend(asm(&format!("JMP_IF_TRUE {loop_at}\nFRAME_SYNC\nRET\n"))); module_with_locals(rom, vec![], 1) } fn color_syscalls() -> Vec { vec![ SyscallDecl { module: "gfx2d".into(), name: "clear".into(), version: 1, arg_slots: 1, ret_slots: 0, }, SyscallDecl { module: "audio".into(), name: "play".into(), version: 1, arg_slots: 7, ret_slots: 1, }, ] } fn gfx_syscalls() -> Vec { vec![SyscallDecl { module: "gfx2d".into(), name: "clear".into(), version: 1, arg_slots: 1, ret_slots: 0, }] } fn module(code: Vec, syscalls: Vec) -> Vec { module_with_locals(code, syscalls, 0) } fn module_with_locals(code: Vec, syscalls: Vec, local_slots: u16) -> Vec { BytecodeModule { version: 0, const_pool: vec![], functions: vec![FunctionMeta { code_offset: 0, code_len: code.len() as u32, param_slots: 0, local_slots, return_slots: 0, max_stack_slots: 8, }], code, debug_info: Some(DebugInfo { pc_to_span: vec![(0, SourceSpan { file_id: 7, start: 11, end: 15 })], function_names: vec![(0, "main".into())], }), exports: vec![Export { symbol: "main".into(), func_idx: 0 }], syscalls, } .serialize() } fn asm(source: &str) -> Vec { assemble(source).expect("assemble") }