Author SHA1 Message Date
bquarkz 6ef376763c multi-frontend-pvm-neutrality
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
2026-09-18 23:16:26 +01:00
bquarkz f50a3f127f regenerate PBX test cartridges
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
2026-07-15 08:04:29 +01:00
bquarkz f0f3f972ce fix PBX executable format identity 2026-07-15 08:01:47 +01:00
bquarkz b2d2533acb Fix PBX problems 2026-07-15 07:55:52 +01:00
bquarkz 4b499288e2 Portable Host Backend Strategy
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
2026-07-14 16:39:46 +01:00
bquarkz aa3b31deb5 Merge pull request 'dev/runtime-owned-variable-glyph-bank-palette-protocol' (#37) from dev/runtime-owned-variable-glyph-bank-palette-protocol into master
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
Reviewed-on: #37
2026-07-14 15:25:05 +00:00
bquarkz f784ccd774 Runtime-Owned Variable Glyph Bank Palette Protocol
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
2026-07-14 16:16:05 +01:00
bquarkz 7cced0709b housekeep DSC-0046 variable glyph palette protocol
Intrepid/Prometeu/Runtime/pipeline/head There was a failure building this commit
Intrepid/Prometeu/Runtime/pipeline/pr-master There was a failure building this commit
2026-07-14 16:08:17 +01:00
bquarkz e2a5a67621 implements PLN-0172 runtime glyph palette handoff 2026-07-14 15:54:28 +01:00
bquarkz fbe4d0cac0 implements PLN-0171 variable glyph palette test coverage 2026-07-14 15:53:31 +01:00
bquarkz 4c0f1cb9ad implements PLN-0170 palette reference failures 2026-07-14 15:51:44 +01:00
bquarkz 94ffd241bd implements PLN-0169 variable glyph palette decode 2026-07-14 15:48:57 +01:00
bquarkz a415c172c7 implements PLN-0168 variable glyph bank residency 2026-07-14 15:46:50 +01:00
bquarkz c89116b6f8 implements PLN-0167 variable glyph palette specs 2026-07-14 15:46:20 +01:00
bquarkz dc279fe72b Runtime-Owned Variable Glyph Bank Palette Protocol 2026-07-14 15:40:49 +01:00
bquarkz 01221769cd added agendo about background service (music player as example)
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
2026-07-05 19:10:19 +01:00
bquarkz 3cce8a2b25 Merge pull request 'dev/system-os-cartridge-switch-orchestrator' (#36) from dev/system-os-cartridge-switch-orchestrator into master
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
Reviewed-on: #36
2026-07-05 17:47:26 +00:00
bquarkz de53eb5ad7 Hub Suspended Game Kill Affordance
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
2026-07-05 16:27:05 +01:00
bquarkz 49cb16b6cb implements PLN-0166 2026-07-05 09:42:57 +01:00
bquarkz 3aec829c70 implements PLN-0165 2026-07-05 09:41:01 +01:00
bquarkz 73c8246c8d implements PLN-0163 2026-07-05 09:36:59 +01:00
bquarkz fa0a768b84 implements PLN-0164 2026-07-05 09:31:27 +01:00
bquarkz 62573e9574 Hub Suspended Game Kill Affordance 2026-07-05 09:25:01 +01:00
bquarkz c814e057dc implements PLN-0162 2026-07-05 01:26:42 +01:00
bquarkz 8d719843c7 implements PLN-0161 2026-07-05 01:24:45 +01:00
bquarkz d6afa6ae6b implements PLN-0160 2026-07-05 01:18:33 +01:00
bquarkz 3df8227ebf implements PLN-0159 2026-07-05 01:14:45 +01:00
bquarkz b30ff73e3d implements PLN-0158 2026-07-05 01:12:09 +01:00
bquarkz dcd3479b1d implements PLN-0157 2026-07-05 01:07:54 +01:00
bquarkz 0ffb3467b1 SystemOS Cartridge Switch Orchestrator 2026-07-05 01:03:02 +01:00
bquarkz 313b896e7b Merge pull request 'dev/foreground-stack-game-pause-shell-vm-backed' (#35) from dev/foreground-stack-game-pause-shell-vm-backed into master
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
Reviewed-on: #35
2026-07-04 23:46:58 +00:00
bquarkz 6dc8cb5372 VM Context Ownership for Resident Game and VM-Backed Shell
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
2026-07-05 00:36:15 +01:00
bquarkz c34bbaf936 implements PLN-0156 2026-07-05 00:30:56 +01:00
bquarkz e613ab43c9 implements PLN-0155 2026-07-05 00:26:16 +01:00
bquarkz 4e05daf280 implements PLN-0154 2026-07-05 00:21:10 +01:00
bquarkz 8098dbd7f4 VM Context Ownership for Resident Game and VM-Backed Shell 2026-07-05 00:16:50 +01:00
87 changed files with 3290 additions and 3229 deletions
Generated
+10
View File
@@ -1469,6 +1469,16 @@ version = "1.0.15"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "57c0d7b74b563b49d38dae00a0c37d4d6de9b432382b2892f0574ddcae73fd0a"
[[package]]
name = "pbxgen-dummy-boy"
version = "0.1.0"
dependencies = [
"anyhow",
"prometeu-bytecode",
"prometeu-hal",
"serde_json",
]
[[package]]
name = "pbxgen-stress"
version = "0.1.0"
+1
View File
@@ -8,6 +8,7 @@ members = [
"crates/console/prometeu-vm",
"crates/host/prometeu-host-desktop-winit",
"crates/tools/prometeu-cli",
"crates/tools/pbxgen-dummy-boy",
"crates/tools/pbxgen-stress",
"crates/dev/prometeu-test-support",
"crates/dev/prometeu-layer-tests",
+1 -1
View File
@@ -19,6 +19,6 @@ pub use assembler::{assemble, AsmError};
pub use decoder::{decode_next, DecodeError};
pub use disassembler::disassemble;
pub use layout::{compute_function_layouts, FunctionLayout};
pub use model::{BytecodeLoader, FunctionMeta, LoadError, SyscallDecl};
pub use model::{BytecodeLoader, FunctionMeta, LoadError, SyscallDecl, PBX_MAGIC};
pub use program_image::ProgramImage;
pub use value::{string_materialization_count, HeapRef, Value};
+13 -11
View File
@@ -80,9 +80,11 @@ const SECTION_KIND_DEBUG: u32 = 3;
const SECTION_KIND_EXPORTS: u32 = 4;
const SECTION_KIND_SYSCALLS: u32 = 5;
/// Represents the final serialized format of a PBS v0 module.
pub const PBX_MAGIC: [u8; 4] = *b"PBX\0";
/// Represents the final serialized format of a PBX v0 module.
///
/// This structure is a pure data container for the PBS format. It does NOT
/// This structure is a pure data container for the PBX format. It does NOT
/// contain any linker-like logic (symbol resolution, patching, etc.).
/// All multi-module programs must be flattened and linked by the compiler
/// before being serialized into this format.
@@ -126,8 +128,8 @@ impl BytecodeModule {
final_sections.push((SECTION_KIND_SYSCALLS, syscall_data));
let mut out = Vec::new();
// Magic "PBS\0"
out.extend_from_slice(b"PBS\0");
// Magic "PBX\0"
out.extend_from_slice(&PBX_MAGIC);
// Version 0
out.extend_from_slice(&0u16.to_le_bytes());
// Endianness 0 (Little Endian), Reserved
@@ -272,8 +274,8 @@ impl BytecodeLoader {
return Err(LoadError::UnexpectedEof);
}
// Magic "PBS\0"
if &bytes[0..4] != b"PBS\0" {
// Magic "PBX\0"
if bytes[0..4] != PBX_MAGIC[..] {
return Err(LoadError::InvalidMagic);
}
@@ -708,7 +710,7 @@ mod tests {
fn create_header(section_count: u32) -> Vec<u8> {
let mut h = vec![0u8; 32];
h[0..4].copy_from_slice(b"PBS\0");
h[0..4].copy_from_slice(&PBX_MAGIC);
h[4..6].copy_from_slice(&0u16.to_le_bytes()); // version
h[6] = 0; // endianness
h[8..12].copy_from_slice(&section_count.to_le_bytes());
@@ -727,7 +729,7 @@ mod tests {
}
}
fn build_pbs_with_sections(sections: Vec<(u32, Vec<u8>)>) -> Vec<u8> {
fn build_pbx_with_sections(sections: Vec<(u32, Vec<u8>)>) -> Vec<u8> {
let mut data = create_header(sections.len() as u32);
let mut offset = 32 + (sections.len() as u32 * 12);
@@ -748,7 +750,7 @@ mod tests {
#[test]
fn test_invalid_magic() {
let mut data = create_header(0);
data[0] = b'X';
data[0..4].copy_from_slice(b"PBS\0");
assert_eq!(BytecodeLoader::load(&data), Err(LoadError::InvalidMagic));
}
@@ -897,7 +899,7 @@ mod tests {
#[test]
fn test_malformed_sysc_section_is_rejected() {
let data = build_pbs_with_sections(vec![(SECTION_KIND_SYSCALLS, vec![1, 0, 0])]);
let data = build_pbx_with_sections(vec![(SECTION_KIND_SYSCALLS, vec![1, 0, 0])]);
assert_eq!(BytecodeLoader::load(&data), Err(LoadError::MalformedSection));
}
@@ -914,7 +916,7 @@ mod tests {
sysc.extend_from_slice(&0u16.to_le_bytes());
sysc.extend_from_slice(&0u16.to_le_bytes());
let data = build_pbs_with_sections(vec![(SECTION_KIND_SYSCALLS, sysc)]);
let data = build_pbx_with_sections(vec![(SECTION_KIND_SYSCALLS, sysc)]);
assert_eq!(BytecodeLoader::load(&data), Err(LoadError::InvalidUtf8));
}
@@ -4,7 +4,7 @@ use crate::value::Value;
use std::collections::HashMap;
use std::sync::Arc;
/// Represents a fully linked, executable PBS program image.
/// Represents a fully linked, executable PBX program image.
///
/// Under the Prometeu architecture, the ProgramImage is a "closed-world" artifact
/// produced by the compiler. All linking, relocation, and symbol resolution
+208 -35
View File
@@ -191,10 +191,10 @@ impl GlyphAssetSlotIndex {
}
}
const GLYPH_BANK_PALETTE_COUNT_V1: usize = 64;
const GLYPH_BANK_MAX_PALETTE_COUNT_V1: usize = 64;
const GLYPH_BANK_COLORS_PER_PALETTE: usize = 16;
const GLYPH_BANK_PALETTE_BYTES_V1: usize =
GLYPH_BANK_PALETTE_COUNT_V1 * GLYPH_BANK_COLORS_PER_PALETTE * size_of::<u32>();
const GLYPH_BANK_PALETTE_BYTES_PER_PALETTE: usize =
GLYPH_BANK_COLORS_PER_PALETTE * size_of::<u32>();
/// Resident metadata for a decoded/materialized asset inside a BankPolicy.
#[derive(Debug)]
@@ -599,7 +599,7 @@ impl AssetBridge for AssetManager {
impl AssetManager {
fn decode_glyph_bank_layout(
entry: &AssetEntry,
) -> Result<(TileSize, usize, usize, usize), String> {
) -> Result<(TileSize, usize, usize, usize, usize, usize), String> {
let meta = entry.metadata_as_glyph_bank()?;
let tile_size = match meta.tile_size {
@@ -609,7 +609,8 @@ impl AssetManager {
_ => return Err(format!("Invalid tile_size: {}", meta.tile_size)),
};
if meta.palette_count as usize != GLYPH_BANK_PALETTE_COUNT_V1 {
let palette_count = meta.palette_count as usize;
if !(1..=GLYPH_BANK_MAX_PALETTE_COUNT_V1).contains(&palette_count) {
return Err(format!("Invalid palette_count: {}", meta.palette_count));
}
@@ -618,12 +619,14 @@ impl AssetManager {
let logical_pixels = width.checked_mul(height).ok_or("GlyphBank dimensions overflow")?;
let serialized_pixel_bytes = logical_pixels.div_ceil(2);
let palette_bytes = palette_count
.checked_mul(GLYPH_BANK_PALETTE_BYTES_PER_PALETTE)
.ok_or("GlyphBank palette size overflow")?;
let serialized_size = serialized_pixel_bytes
.checked_add(GLYPH_BANK_PALETTE_BYTES_V1)
.checked_add(palette_bytes)
.ok_or("GlyphBank serialized size overflow")?;
let decoded_size = logical_pixels
.checked_add(GLYPH_BANK_PALETTE_BYTES_V1)
.ok_or("GlyphBank decoded size overflow")?;
let decoded_size =
logical_pixels.checked_add(palette_bytes).ok_or("GlyphBank decoded size overflow")?;
if entry.size != serialized_size as u64 {
return Err(format!(
@@ -639,7 +642,7 @@ impl AssetManager {
));
}
Ok((tile_size, width, height, serialized_pixel_bytes))
Ok((tile_size, width, height, serialized_pixel_bytes, palette_count, palette_bytes))
}
fn unpack_glyph_bank_pixels(packed_pixels: &[u8], logical_pixels: usize) -> Vec<u8> {
@@ -1200,19 +1203,18 @@ impl AssetManager {
entry: &AssetEntry,
buffer: &[u8],
) -> Result<GlyphBank, String> {
let (tile_size, width, height, packed_pixel_bytes) = Self::decode_glyph_bank_layout(entry)?;
if buffer.len() < packed_pixel_bytes + GLYPH_BANK_PALETTE_BYTES_V1 {
let (tile_size, width, height, packed_pixel_bytes, palette_count, palette_bytes) =
Self::decode_glyph_bank_layout(entry)?;
if buffer.len() < packed_pixel_bytes + palette_bytes {
return Err("Buffer too small for GLYPHBANK".to_string());
}
let logical_pixels = width * height;
let packed_pixels = &buffer[0..packed_pixel_bytes];
let pixel_indices = Self::unpack_glyph_bank_pixels(packed_pixels, logical_pixels);
let palette_data =
&buffer[packed_pixel_bytes..packed_pixel_bytes + GLYPH_BANK_PALETTE_BYTES_V1];
let palette_data = &buffer[packed_pixel_bytes..packed_pixel_bytes + palette_bytes];
let mut palettes =
[[Color::BLACK; GLYPH_BANK_COLORS_PER_PALETTE]; GLYPH_BANK_PALETTE_COUNT_V1];
let mut palettes = vec![[Color::BLACK; GLYPH_BANK_COLORS_PER_PALETTE]; palette_count];
for (p, pal) in palettes.iter_mut().enumerate() {
for (c, slot) in pal.iter_mut().enumerate() {
let offset = (p * 16 + c) * 4;
@@ -1232,7 +1234,8 @@ impl AssetManager {
entry: &AssetEntry,
reader: &mut impl Read,
) -> Result<GlyphBank, String> {
let (tile_size, width, height, packed_pixel_bytes) = Self::decode_glyph_bank_layout(entry)?;
let (tile_size, width, height, packed_pixel_bytes, palette_count, palette_bytes) =
Self::decode_glyph_bank_layout(entry)?;
let logical_pixels = width * height;
let mut packed_pixels = vec![0_u8; packed_pixel_bytes];
reader
@@ -1241,13 +1244,12 @@ impl AssetManager {
let pixel_indices = Self::unpack_glyph_bank_pixels(&packed_pixels, logical_pixels);
let mut palette_data = [0_u8; GLYPH_BANK_PALETTE_BYTES_V1];
let mut palette_data = vec![0_u8; palette_bytes];
reader
.read_exact(&mut palette_data)
.map_err(|_| "Buffer too small for GLYPHBANK".to_string())?;
let mut palettes =
[[Color::BLACK; GLYPH_BANK_COLORS_PER_PALETTE]; GLYPH_BANK_PALETTE_COUNT_V1];
let mut palettes = vec![[Color::BLACK; GLYPH_BANK_COLORS_PER_PALETTE]; palette_count];
for (p, pal) in palettes.iter_mut().enumerate() {
for (c, slot) in pal.iter_mut().enumerate() {
let offset = (p * 16 + c) * 4;
@@ -1858,6 +1860,9 @@ impl AssetManager {
self.glyph_slot_index.clear();
self.sound_slots.write().unwrap().fill(None);
self.scene_slots.write().unwrap().fill(None);
self.gfx_installer.clear_glyph_banks();
self.sound_installer.clear_sound_banks();
self.scene_installer.clear_scene_banks();
}
pub fn glyph_asset_slot_index(&self) -> GlyphAssetSlotIndex {
@@ -1880,35 +1885,53 @@ mod tests {
use prometeu_hal::tile::Tile;
use prometeu_hal::tilemap::TileMap;
fn expected_glyph_payload_size(width: usize, height: usize) -> usize {
(width * height).div_ceil(2) + GLYPH_BANK_PALETTE_BYTES_V1
fn expected_glyph_payload_size(width: usize, height: usize, palette_count: usize) -> usize {
(width * height).div_ceil(2) + (palette_count * GLYPH_BANK_PALETTE_BYTES_PER_PALETTE)
}
fn expected_glyph_decoded_size(width: usize, height: usize) -> usize {
width * height + GLYPH_BANK_PALETTE_BYTES_V1
fn expected_glyph_decoded_size(width: usize, height: usize, palette_count: usize) -> usize {
width * height + (palette_count * GLYPH_BANK_PALETTE_BYTES_PER_PALETTE)
}
fn test_glyph_asset_data() -> Vec<u8> {
test_glyph_asset_data_with_palette_count(GLYPH_BANK_MAX_PALETTE_COUNT_V1)
}
fn test_glyph_asset_data_with_palette_count(palette_count: usize) -> Vec<u8> {
let mut data = vec![0x11u8; 128];
data.extend_from_slice(&[0u8; GLYPH_BANK_PALETTE_BYTES_V1]);
data.extend_from_slice(&vec![0u8; palette_count * GLYPH_BANK_PALETTE_BYTES_PER_PALETTE]);
data
}
fn test_glyph_asset_entry(asset_name: &str, width: usize, height: usize) -> AssetEntry {
test_glyph_asset_entry_with_palette_count(
asset_name,
width,
height,
GLYPH_BANK_MAX_PALETTE_COUNT_V1,
)
}
fn test_glyph_asset_entry_with_palette_count(
asset_name: &str,
width: usize,
height: usize,
palette_count: usize,
) -> AssetEntry {
AssetEntry {
asset_id: 0,
asset_name: asset_name.to_string(),
bank_type: BankType::GLYPH,
offset: 0,
size: expected_glyph_payload_size(width, height) as u64,
decoded_size: expected_glyph_decoded_size(width, height) as u64,
size: expected_glyph_payload_size(width, height, palette_count) as u64,
decoded_size: expected_glyph_decoded_size(width, height, palette_count) as u64,
codec: AssetCodec::None,
metadata: serde_json::json!({
"tile_size": 16,
"width": width,
"height": height,
"palette_count": GLYPH_BANK_PALETTE_COUNT_V1,
"palette_authored": GLYPH_BANK_PALETTE_COUNT_V1
"palette_count": palette_count,
"palette_authored": palette_count
}),
}
}
@@ -2031,22 +2054,67 @@ mod tests {
#[test]
fn test_decode_glyph_bank_unpacks_packed_pixels_and_reads_palette_colors() {
let entry = test_glyph_asset_entry("glyphs", 2, 2);
let entry = test_glyph_asset_entry_with_palette_count("glyphs", 2, 2, 1);
let mut data = vec![0x10, 0x23];
data.extend_from_slice(&[0u8; GLYPH_BANK_PALETTE_BYTES_V1]);
data.extend_from_slice(&[0u8; GLYPH_BANK_PALETTE_BYTES_PER_PALETTE]);
data[2..6].copy_from_slice(&[0x12, 0x34, 0x56, 0x78]);
let bank =
AssetManager::decode_glyph_bank_from_buffer(&entry, &data).expect("glyph decode");
assert_eq!(bank.pixel_indices, vec![1, 0, 2, 3]);
assert_eq!(bank.palette_count(), 1);
assert_eq!(bank.palettes[0][0], Color::from_raw(0x12345678));
}
#[test]
fn test_decode_glyph_bank_accepts_intermediate_palette_count() {
let entry = test_glyph_asset_entry_with_palette_count("glyphs", 16, 16, 7);
let data = test_glyph_asset_data_with_palette_count(7);
let bank =
AssetManager::decode_glyph_bank_from_buffer(&entry, &data).expect("glyph decode");
assert_eq!(bank.palette_count(), 7);
}
#[test]
fn test_decode_glyph_bank_accepts_max_palette_count() {
let entry = test_glyph_asset_entry_with_palette_count(
"glyphs",
16,
16,
GLYPH_BANK_MAX_PALETTE_COUNT_V1,
);
let data = test_glyph_asset_data_with_palette_count(GLYPH_BANK_MAX_PALETTE_COUNT_V1);
let bank =
AssetManager::decode_glyph_bank_from_buffer(&entry, &data).expect("glyph decode");
assert_eq!(bank.palette_count(), GLYPH_BANK_MAX_PALETTE_COUNT_V1);
}
#[test]
fn test_decode_glyph_bank_reader_matches_buffer_for_variable_palette_count() {
let entry = test_glyph_asset_entry_with_palette_count("glyphs", 16, 16, 3);
let data = test_glyph_asset_data_with_palette_count(3);
let from_buffer =
AssetManager::decode_glyph_bank_from_buffer(&entry, &data).expect("buffer decode");
let mut reader = std::io::Cursor::new(data);
let from_reader = AssetManager::decode_glyph_bank_from_reader(&entry, &mut reader)
.expect("reader decode");
assert_eq!(from_buffer.palette_count(), from_reader.palette_count());
assert_eq!(from_buffer.pixel_indices, from_reader.pixel_indices);
assert_eq!(from_buffer.palettes, from_reader.palettes);
}
#[test]
fn test_decode_glyph_bank_rejects_short_packed_buffer() {
let entry = test_glyph_asset_entry("glyphs", 16, 16);
let data = vec![0u8; expected_glyph_payload_size(16, 16) - 1];
let data =
vec![0u8; expected_glyph_payload_size(16, 16, GLYPH_BANK_MAX_PALETTE_COUNT_V1) - 1];
let err = match AssetManager::decode_glyph_bank_from_buffer(&entry, &data) {
Ok(_) => panic!("glyph decode should reject short buffer"),
@@ -2057,9 +2125,9 @@ mod tests {
}
#[test]
fn test_decode_glyph_bank_requires_palette_count_64() {
fn test_decode_glyph_bank_rejects_palette_count_zero() {
let mut entry = test_glyph_asset_entry("glyphs", 16, 16);
entry.metadata["palette_count"] = serde_json::json!(32);
entry.metadata["palette_count"] = serde_json::json!(0);
let err =
match AssetManager::decode_glyph_bank_from_buffer(&entry, &test_glyph_asset_data()) {
@@ -2067,7 +2135,67 @@ mod tests {
Err(err) => err,
};
assert_eq!(err, "Invalid palette_count: 32");
assert_eq!(err, "Invalid palette_count: 0");
}
#[test]
fn test_decode_glyph_bank_rejects_palette_count_above_v1_max() {
let mut entry = test_glyph_asset_entry("glyphs", 16, 16);
entry.metadata["palette_count"] = serde_json::json!(65);
let err =
match AssetManager::decode_glyph_bank_from_buffer(&entry, &test_glyph_asset_data()) {
Ok(_) => panic!("glyph decode should reject invalid palette_count"),
Err(err) => err,
};
assert_eq!(err, "Invalid palette_count: 65");
}
#[test]
fn test_decode_glyph_bank_rejects_mismatched_variable_decoded_size() {
let mut entry = test_glyph_asset_entry_with_palette_count("glyphs", 16, 16, 3);
entry.decoded_size += 1;
let err = match AssetManager::decode_glyph_bank_from_buffer(
&entry,
&test_glyph_asset_data_with_palette_count(3),
) {
Ok(_) => panic!("glyph decode should reject invalid decoded_size"),
Err(err) => err,
};
assert_eq!(
err,
format!(
"Invalid GLYPHBANK decoded_size: expected {}, got {}",
expected_glyph_decoded_size(16, 16, 3),
expected_glyph_decoded_size(16, 16, 3) + 1
)
);
}
#[test]
fn test_decode_glyph_bank_rejects_mismatched_variable_serialized_size() {
let mut entry = test_glyph_asset_entry_with_palette_count("glyphs", 16, 16, 3);
entry.size += 1;
let err = match AssetManager::decode_glyph_bank_from_buffer(
&entry,
&test_glyph_asset_data_with_palette_count(3),
) {
Ok(_) => panic!("glyph decode should reject invalid serialized size"),
Err(err) => err,
};
assert_eq!(
err,
format!(
"Invalid GLYPHBANK serialized size: expected {}, got {}",
expected_glyph_payload_size(16, 16, 3),
expected_glyph_payload_size(16, 16, 3) + 1
)
);
}
#[test]
@@ -2668,6 +2796,51 @@ mod tests {
assert_eq!(am.slot_info(SlotRef::scene(4)).asset_id, Some(2));
}
#[test]
fn shutdown_clears_physical_memory_bank_slots() {
let banks = Arc::new(MemoryBanks::new());
let gfx_installer = Arc::clone(&banks) as Arc<dyn GlyphBankPoolInstaller>;
let sound_installer = Arc::clone(&banks) as Arc<dyn SoundBankPoolInstaller>;
let scene_installer = Arc::clone(&banks) as Arc<dyn SceneBankPoolInstaller>;
let glyph_data = test_glyph_asset_data();
let scene = test_scene();
let scene_data = encode_scene_payload(&scene);
let glyph_entry = test_glyph_asset_entry("preload_glyphs", 16, 16);
let scene_entry = test_scene_asset_entry("preload_scene", &scene_data, &scene);
let mut payload = Vec::new();
payload.extend_from_slice(&glyph_data);
payload.extend_from_slice(&scene_data);
let mut shifted_scene_entry = scene_entry;
shifted_scene_entry.offset = glyph_data.len() as u64;
let am = AssetManager::new(
vec![],
AssetsPayloadSource::empty(),
gfx_installer,
sound_installer,
scene_installer,
);
am.initialize_for_cartridge(
vec![glyph_entry, shifted_scene_entry],
vec![PreloadEntry { asset_id: 0, slot: 0 }, PreloadEntry { asset_id: 2, slot: 0 }],
AssetsPayloadSource::from_bytes(payload),
);
assert!(banks.glyph_bank_slot(0).is_some());
assert!(banks.scene_bank_slot(0).is_some());
assert_eq!(am.slot_info(SlotRef::gfx(0)).asset_id, Some(0));
assert_eq!(am.slot_info(SlotRef::scene(0)).asset_id, Some(2));
am.shutdown();
assert!(banks.glyph_bank_slot(0).is_none());
assert!(banks.scene_bank_slot(0).is_none());
assert_eq!(am.slot_info(SlotRef::gfx(0)).asset_id, None);
assert_eq!(am.slot_info(SlotRef::scene(0)).asset_id, None);
}
#[test]
fn test_load_returns_asset_not_found() {
let banks = Arc::new(MemoryBanks::new());
@@ -557,8 +557,9 @@ mod tests {
fn make_glyph_bank(tile_size: TileSize, palette_id: u8, color: Color) -> GlyphBank {
let size = tile_size as usize;
let mut bank = GlyphBank::new(tile_size, size, size);
bank.palettes[palette_id as usize][1] = color;
let mut bank =
GlyphBank::with_palette_count(tile_size, size, size, palette_id as usize + 1);
bank.palette_mut(palette_id).unwrap()[1] = color;
for pixel in &mut bank.pixel_indices {
*pixel = 1;
}
+63 -4
View File
@@ -812,7 +812,14 @@ impl Gfx {
let fetch_x = if tile.entry.flip_x() { size - 1 - local_x } else { local_x };
let fetch_y = if tile.entry.flip_y() { size - 1 - local_y } else { local_y };
let px_index = tile.bank.get_pixel_index(tile.entry.glyph_id, fetch_x, fetch_y);
let color = tile.bank.resolve_color(tile.entry.palette_id, px_index);
let color = tile.bank.resolve_color(tile.entry.palette_id, px_index).unwrap_or_else(
|| {
panic!(
"SCENE composition fatal: palette_id {} is not resident for glyph asset {}",
tile.entry.palette_id, tile.entry.glyph_asset_id
)
},
);
if color.alpha() == 0 {
continue;
}
@@ -862,7 +869,14 @@ impl Gfx {
let fetch_y = if sprite.flip_y { size - 1 - local_y } else { local_y };
let px_index = bank.get_pixel_index(sprite.glyph.glyph_id, fetch_x, fetch_y);
let color = bank.resolve_color(sprite.glyph.palette_id, px_index);
let color = bank.resolve_color(sprite.glyph.palette_id, px_index).unwrap_or_else(
|| {
panic!(
"SPRITE composition fatal: palette_id {} is not resident for glyph bank {}",
sprite.glyph.palette_id, sprite.bank_id
)
},
);
if color.alpha() == 0 {
continue;
}
@@ -1010,9 +1024,14 @@ mod tests {
fn make_glyph_bank(tile_size: TileSize, palette_colors: &[(u8, u8, Color)]) -> GlyphBank {
let size = tile_size as usize;
let mut bank = GlyphBank::new(tile_size, size, size);
let palette_count = palette_colors
.iter()
.map(|(palette_id, _, _)| *palette_id as usize + 1)
.max()
.unwrap_or(1);
let mut bank = GlyphBank::with_palette_count(tile_size, size, size, palette_count);
for (palette_id, color_index, color) in palette_colors {
bank.palettes[*palette_id as usize][*color_index as usize] = *color;
bank.palette_mut(*palette_id).unwrap()[*color_index as usize] = *color;
}
bank
}
@@ -1152,6 +1171,26 @@ mod tests {
assert_eq!(back[0], Color::RED.raw());
}
#[test]
#[should_panic(expected = "SPRITE composition fatal: palette_id 1 is not resident")]
fn sprite_draw_panics_for_invalid_palette_reference() {
let bank = make_filled_glyph_bank(TileSize::Size8, 0, &[(0, 0, Color::GREEN)]);
let mut back = vec![Color::BLACK.raw(); 8 * 8];
let sprite = Sprite {
glyph: Glyph { glyph_id: 0, palette_id: 1 },
x: 0,
y: 0,
layer: 0,
flip_x: false,
flip_y: false,
bank_id: 0,
active: true,
priority: 0,
};
Gfx::draw_sprite_pixel_by_pixel(&mut back, 8, 8, &sprite, &bank);
}
#[test]
fn test_cached_tile_draws_opaque_color_index_zero() {
let bank = make_filled_glyph_bank(TileSize::Size8, 0, &[(0, 0, Color::GREEN)]);
@@ -1194,6 +1233,26 @@ mod tests {
assert_eq!(target.back[0], Color::RED.raw());
}
#[test]
#[should_panic(expected = "SCENE composition fatal: palette_id 1 is not resident")]
fn cached_tile_draw_panics_for_invalid_palette_reference() {
let bank = make_filled_glyph_bank(TileSize::Size8, 0, &[(0, 0, Color::GREEN)]);
let mut back = vec![Color::BLACK.raw(); 8 * 8];
let mut target = RenderTarget { back: &mut back, screen_w: 8, screen_h: 8 };
let entry = CachedTileEntry {
active: true,
glyph_id: 0,
palette_id: 1,
flags: 0,
glyph_asset_id: 0,
};
Gfx::draw_cached_tile_pixels(
&mut target,
CachedTileDraw { x: 0, y: 0, entry, bank: &bank, tile_size: TileSize::Size8 },
);
}
#[test]
fn test_draw_rect() {
let banks = Arc::new(MemoryBanks::new());
@@ -118,7 +118,11 @@ impl Game2DFrameComposer for Hardware {
}
fn emit_sprite(&mut self, sprite: Sprite) -> prometeu_hal::ComposerOpStatus {
if self.gfx.glyph_banks.glyph_bank_slot(sprite.bank_id as usize).is_none() {
let Some(bank) = self.gfx.glyph_banks.glyph_bank_slot(sprite.bank_id as usize) else {
return prometeu_hal::ComposerOpStatus::BankInvalid;
};
if !bank.contains_palette(sprite.glyph.palette_id) {
return prometeu_hal::ComposerOpStatus::BankInvalid;
}
@@ -261,7 +265,7 @@ mod tests {
fn make_glyph_bank() -> GlyphBank {
let mut bank = GlyphBank::new(TileSize::Size8, 8, 8);
bank.palettes[0][1] = Color::RED;
bank.palette_mut(0).unwrap()[1] = Color::RED;
for pixel in &mut bank.pixel_indices {
*pixel = 1;
}
@@ -433,4 +437,28 @@ mod tests {
assert_eq!(hardware.gfx.front_buffer()[0], Color::RED.raw());
}
#[test]
fn emit_sprite_rejects_palette_id_outside_loaded_glyph_bank() {
let banks = Arc::new(MemoryBanks::new());
banks.install_glyph_bank(0, Arc::new(make_glyph_bank()));
let mut hardware = Hardware::new_with_memory_banks(banks);
let status = Game2DFrameComposer::emit_sprite(
&mut hardware,
Sprite {
glyph: Glyph { glyph_id: 0, palette_id: 1 },
x: 0,
y: 0,
layer: 0,
bank_id: 0,
active: false,
flip_x: false,
flip_y: false,
priority: 0,
},
);
assert_eq!(status, prometeu_hal::ComposerOpStatus::BankInvalid);
}
}
@@ -24,6 +24,8 @@ pub trait GlyphBankPoolAccess: Send + Sync {
pub trait GlyphBankPoolInstaller: Send + Sync {
/// Atomically swaps the resident GlyphBank in the specified slot.
fn install_glyph_bank(&self, slot: usize, bank: Arc<GlyphBank>);
/// Clears all resident GlyphBank slots.
fn clear_glyph_banks(&self);
}
/// Non-generic interface for peripherals to access sound banks.
@@ -38,6 +40,8 @@ pub trait SoundBankPoolAccess: Send + Sync {
pub trait SoundBankPoolInstaller: Send + Sync {
/// Atomically swaps the resident SoundBank in the specified slot.
fn install_sound_bank(&self, slot: usize, bank: Arc<SoundBank>);
/// Clears all resident SoundBank slots.
fn clear_sound_banks(&self);
}
/// Non-generic interface for peripherals to access scene banks.
@@ -52,6 +56,8 @@ pub trait SceneBankPoolAccess: Send + Sync {
pub trait SceneBankPoolInstaller: Send + Sync {
/// Atomically swaps the resident SceneBank in the specified slot.
fn install_scene_bank(&self, slot: usize, bank: Arc<SceneBank>);
/// Clears all resident SceneBank slots.
fn clear_scene_banks(&self);
}
/// Centralized container for all hardware memory banks.
@@ -100,6 +106,10 @@ impl GlyphBankPoolInstaller for MemoryBanks {
pool[slot] = Some(bank);
}
}
fn clear_glyph_banks(&self) {
self.glyph_bank_pool.write().unwrap().fill(None);
}
}
impl SoundBankPoolAccess for MemoryBanks {
@@ -120,6 +130,10 @@ impl SoundBankPoolInstaller for MemoryBanks {
pool[slot] = Some(bank);
}
}
fn clear_sound_banks(&self) {
self.sound_bank_pool.write().unwrap().fill(None);
}
}
impl SceneBankPoolAccess for MemoryBanks {
@@ -140,6 +154,10 @@ impl SceneBankPoolInstaller for MemoryBanks {
pool[slot] = Some(bank);
}
}
fn clear_scene_banks(&self) {
self.scene_bank_pool.write().unwrap().fill(None);
}
}
impl HalRenderResourceAccess for MemoryBanks {
@@ -178,7 +196,7 @@ mod tests {
fn make_glyph_bank() -> GlyphBank {
let mut bank = GlyphBank::new(TileSize::Size8, 8, 8);
bank.palettes[0][1] = Color::WHITE;
bank.palette_mut(0).unwrap()[1] = Color::WHITE;
bank
}
@@ -9,7 +9,6 @@ use prometeu_hal::log::LogSource;
use prometeu_hal::telemetry::CertificationConfig;
use prometeu_hal::{InputSignals, RuntimePlatform};
use prometeu_system::{PrometeuHub, ResidentGameState, SystemOS};
use prometeu_vm::VirtualMachine;
/// PROMETEU Firmware.
///
@@ -27,8 +26,6 @@ use prometeu_vm::VirtualMachine;
/// 2. Delegates the logic update to the current active state.
/// 3. Handles state transitions (e.g., from Loading to Playing).
pub struct Firmware {
/// The execution engine (PVM) for user applications.
pub vm: VirtualMachine,
/// The underlying OS services (Syscalls, Filesystem, Telemetry).
pub os: SystemOS,
/// The internal state of the system launcher (Hub).
@@ -46,7 +43,6 @@ impl Firmware {
/// Initializes the firmware in the `Reset` state.
pub fn new(cap_config: Option<CertificationConfig>) -> Self {
Self {
vm: VirtualMachine::default(),
os: SystemOS::new(cap_config),
hub: PrometeuHub::new(),
state: FirmwareState::Reset(ResetStep),
@@ -122,7 +118,6 @@ impl Firmware {
/// Dispatches the `on_enter` event to the current state implementation.
fn on_enter(&mut self, signals: &InputSignals, platform: &mut dyn RuntimePlatform) {
let mut req = PrometeuContext {
vm: &mut self.vm,
os: &mut self.os,
hub: &mut self.hub,
boot_target: &self.boot_target,
@@ -150,7 +145,6 @@ impl Firmware {
platform: &mut dyn RuntimePlatform,
) -> Option<FirmwareState> {
let mut req = PrometeuContext {
vm: &mut self.vm,
os: &mut self.os,
hub: &mut self.hub,
boot_target: &self.boot_target,
@@ -173,7 +167,6 @@ impl Firmware {
/// Dispatches the `on_exit` event to the current state implementation.
fn on_exit(&mut self, signals: &InputSignals, platform: &mut dyn RuntimePlatform) {
let mut req = PrometeuContext {
vm: &mut self.vm,
os: &mut self.os,
hub: &mut self.hub,
boot_target: &self.boot_target,
@@ -257,21 +250,24 @@ impl Firmware {
mod tests {
use super::*;
use crate::firmware::firmware_state::HubHomeStep;
use crate::firmware::resident_game_termination::{self, ResidentGameTerminationOutcome};
use prometeu_bytecode::assembler::assemble;
use prometeu_bytecode::model::{BytecodeModule, FunctionMeta, SyscallDecl};
use prometeu_drivers::TestPlatform;
use prometeu_drivers::{GlyphBankPoolAccess, SceneBankPoolAccess, TestPlatform};
use prometeu_hal::RuntimePlatform;
use prometeu_hal::app_mode::AppMode;
use prometeu_hal::asset::{BankType, SlotRef};
use prometeu_hal::cartridge::AssetsPayloadSource;
use prometeu_hal::color::Color;
use prometeu_hal::log::{LogLevel, LogSource};
use prometeu_hal::primitives::Rect;
use prometeu_hal::syscalls::{Syscall, caps};
use prometeu_system::process::ProcessState;
use prometeu_system::task::{TaskId, TaskState};
use prometeu_system::windows::WindowOwner;
use prometeu_system::{
CrashReport, ForegroundOwner, GameLifecycleEventKind, ResidentGameState,
discover_games_root,
CrashReport, ForegroundOwner, GameLifecycleEventKind, HUB_SUSPENDED_GAME_KILL_CONTROL,
ResidentGameState, discover_games_root,
};
use std::fs;
use std::path::PathBuf;
@@ -296,20 +292,45 @@ mod tests {
}
fn add_game(&self, name: &str, with_program: bool) -> PathBuf {
self.add_game_with_identity(name, 42, "Stress", "1.0.0", with_program)
}
fn add_game_with_identity(
&self,
name: &str,
app_id: u32,
title: &str,
app_version: &str,
with_program: bool,
) -> PathBuf {
let program = with_program.then(halting_program);
self.add_game_with_program(name, app_id, title, app_version, program)
}
fn add_game_with_program(
&self,
name: &str,
app_id: u32,
title: &str,
app_version: &str,
program: Option<Vec<u8>>,
) -> PathBuf {
let cart = self.path.join(name);
fs::create_dir_all(&cart).expect("test cartridge should be created");
let manifest = r#"{
"magic": "PMTU",
"cartridge_version": 1,
"app_id": 42,
"title": "Stress",
"app_version": "1.0.0",
"app_mode": "Game"
}"#;
let manifest = format!(
r#"{{
"magic": "PMTU",
"cartridge_version": 1,
"app_id": {app_id},
"title": "{title}",
"app_version": "{app_version}",
"app_mode": "Game"
}}"#
);
fs::write(cart.join("manifest.json"), manifest)
.expect("test manifest should be written");
if with_program {
fs::write(cart.join("program.pbx"), halting_program())
if let Some(program) = program {
fs::write(cart.join("program.pbx"), program)
.expect("test program should be written");
}
cart
@@ -340,6 +361,10 @@ mod tests {
.serialize()
}
fn repository_test_cartridges_root() -> PathBuf {
PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../../..").join("test-cartridges")
}
fn invalid_game_cartridge() -> Cartridge {
Cartridge {
app_id: 7,
@@ -454,6 +479,12 @@ mod tests {
windows.set_focus(id);
}
fn front_buffer_pixel(platform: &TestPlatform, x: i32, y: i32) -> u32 {
const FRAMEBUFFER_WIDTH: usize = 480;
let index = x as usize + y as usize * FRAMEBUFFER_WIDTH;
platform.local_hardware().gfx.front_buffer()[index]
}
#[test]
fn load_cartridge_transitions_to_app_crashes_when_vm_init_fails() {
let mut firmware = Firmware::new(None);
@@ -532,6 +563,24 @@ mod tests {
assert!(matches!(firmware.state, FirmwareState::LaunchHub(_)));
}
#[test]
fn reset_clears_vm_sessions_and_runtime_identity() {
let mut firmware = Firmware::new(None);
let mut platform = TestPlatform::new();
let signals = InputSignals::default();
firmware.load_cartridge(valid_cartridge(AppMode::Game));
firmware.tick(&signals, &mut platform);
assert_eq!(firmware.os.sessions().vm_session_count(), 1);
assert_eq!(firmware.os.vm().current_cartridge_title(), "Valid Cart");
firmware.change_state(FirmwareState::Reset(ResetStep), &signals, &mut platform);
assert_eq!(firmware.os.sessions().vm_session_count(), 0);
assert_eq!(firmware.os.vm().current_cartridge_title(), "");
}
#[test]
fn load_cartridge_routes_system_apps_to_system_running() {
let mut firmware = Firmware::new(None);
@@ -717,6 +766,499 @@ mod tests {
);
}
#[test]
fn hub_home_clicking_different_game_terminates_previous_resident_session() {
let root = TestGameRoot::new();
root.add_game("stress", true);
root.add_game_with_identity("zzz-dummy", 43, "Zzz Dummy", "1.0.0", true);
let (mut firmware, mut platform) = hub_home_firmware();
firmware.hub.set_game_library(discover_games_root(&root.path));
firmware.tick(&InputSignals::default(), &mut platform);
let stress_click =
InputSignals { f_signal: true, x_pos: 72, y_pos: 90, ..Default::default() };
firmware.tick(&stress_click, &mut platform);
firmware.tick(&InputSignals::default(), &mut platform);
let first_game_task = match &firmware.state {
FirmwareState::GameRunning(step) => step.task_id,
other => panic!("expected first GameRunning state, got {:?}", other),
};
firmware.request_home_from_host();
firmware.tick(&InputSignals::default(), &mut platform);
assert_eq!(firmware.os.lifecycle().resident_game_task(), Some(first_game_task));
firmware.tick(&InputSignals::default(), &mut platform);
let dummy_click =
InputSignals { f_signal: true, x_pos: 72, y_pos: 118, ..Default::default() };
firmware.tick(&dummy_click, &mut platform);
assert_eq!(firmware.os.lifecycle().task_state(first_game_task), Some(TaskState::Closed));
assert_eq!(
firmware.os.lifecycle().process_state_for_task(first_game_task),
Ok(ProcessState::Stopped)
);
assert_eq!(
firmware
.os
.sessions()
.vm_session_for_task(first_game_task)
.map(|session| session.task_id),
None
);
let second_game_task = firmware
.os
.lifecycle()
.resident_game_task()
.expect("replacement game should be resident");
assert_ne!(second_game_task, first_game_task);
assert_eq!(
firmware
.os
.sessions()
.vm_session_for_task(second_game_task)
.map(|session| session.app_id),
Some(43)
);
firmware.tick(&InputSignals::default(), &mut platform);
match &firmware.state {
FirmwareState::GameRunning(step) => assert_eq!(step.task_id, second_game_task),
other => panic!("expected replacement GameRunning state, got {:?}", other),
}
}
#[test]
fn repository_stress_to_dummy_boy_switch_is_end_to_end() {
let library = discover_games_root(repository_test_cartridges_root());
assert!(
library
.entries()
.iter()
.any(|entry| entry.app_id == 1 && entry.title == "Stress Console")
);
assert!(
library.entries().iter().any(|entry| entry.app_id == 2 && entry.title == "Dummy Boy")
);
let (mut firmware, mut platform) = hub_home_firmware();
firmware.hub.set_game_library(library);
firmware.tick(&InputSignals::default(), &mut platform);
let stress_click =
InputSignals { f_signal: true, x_pos: 72, y_pos: 118, ..Default::default() };
firmware.tick(&stress_click, &mut platform);
firmware.tick(&InputSignals::default(), &mut platform);
let stress_task = match &firmware.state {
FirmwareState::GameRunning(step) => step.task_id,
other => panic!("expected Stress GameRunning state, got {:?}", other),
};
assert_eq!(firmware.os.vm().current_app_id(), 1);
assert_eq!(firmware.os.vm().current_cartridge_title(), "Stress Console");
assert_eq!(
platform.assets().slot_info(SlotRef { asset_type: BankType::GLYPH, index: 0 }).asset_id,
Some(100)
);
assert_eq!(
platform.assets().slot_info(SlotRef { asset_type: BankType::SCENE, index: 0 }).asset_id,
Some(1)
);
firmware.request_home_from_host();
firmware.tick(&InputSignals::default(), &mut platform);
let hub_ownership = firmware.os.vm().active_render_ownership();
assert_eq!(hub_ownership.app_mode, AppMode::Shell);
assert_eq!(hub_ownership.app_id, 0);
assert_eq!(
platform.assets().slot_info(SlotRef { asset_type: BankType::GLYPH, index: 0 }).asset_id,
Some(100)
);
assert_eq!(
platform.assets().slot_info(SlotRef { asset_type: BankType::SCENE, index: 0 }).asset_id,
Some(1)
);
firmware.tick(&InputSignals::default(), &mut platform);
let dummy_click =
InputSignals { f_signal: true, x_pos: 72, y_pos: 90, ..Default::default() };
firmware.tick(&dummy_click, &mut platform);
assert_eq!(
platform.assets().slot_info(SlotRef { asset_type: BankType::GLYPH, index: 0 }).asset_id,
None
);
assert_eq!(
platform.assets().slot_info(SlotRef { asset_type: BankType::SCENE, index: 0 }).asset_id,
None
);
assert!(platform.local_hardware().memory_banks.glyph_bank_slot(0).is_none());
assert!(platform.local_hardware().memory_banks.scene_bank_slot(0).is_none());
assert_eq!(firmware.os.lifecycle().task_state(stress_task), Some(TaskState::Closed));
assert_eq!(
firmware.os.lifecycle().process_state_for_task(stress_task),
Ok(ProcessState::Stopped)
);
assert_eq!(
firmware.os.sessions().vm_session_for_task(stress_task).map(|session| session.task_id),
None
);
let dummy_task = firmware
.os
.lifecycle()
.resident_game_task()
.expect("Dummy Boy should be resident after switch load");
assert_ne!(dummy_task, stress_task);
assert_eq!(
firmware.os.sessions().vm_session_for_task(dummy_task).map(|session| {
(session.app_id, session.title.clone(), session.app_version.clone())
}),
Some((2, "Dummy Boy".to_string(), "0.1.0".to_string()))
);
firmware.tick(&InputSignals::default(), &mut platform);
match &firmware.state {
FirmwareState::GameRunning(step) => assert_eq!(step.task_id, dummy_task),
other => panic!("expected Dummy Boy GameRunning state, got {:?}", other),
}
assert_eq!(firmware.os.lifecycle().foreground_owner(), ForegroundOwner::Game(dummy_task));
assert_eq!(firmware.os.vm().current_app_id(), 2);
assert_eq!(firmware.os.vm().current_cartridge_title(), "Dummy Boy");
firmware.tick(&InputSignals::default(), &mut platform);
let dummy_ownership = firmware.os.vm().active_render_ownership();
assert_eq!(dummy_ownership.app_mode, AppMode::Game);
assert_eq!(dummy_ownership.app_id, 2);
let front = platform.local_hardware().gfx.front_buffer();
let center = 240 + 135 * 480;
assert_eq!(front[center], Color::GREEN.raw());
firmware.request_home_from_host();
firmware.tick(&InputSignals::default(), &mut platform);
let hub_ownership = firmware.os.vm().active_render_ownership();
assert_eq!(hub_ownership.app_mode, AppMode::Shell);
assert_eq!(hub_ownership.app_id, 0);
firmware.tick(&InputSignals::default(), &mut platform);
let stress_click =
InputSignals { f_signal: true, x_pos: 72, y_pos: 118, ..Default::default() };
firmware.tick(&stress_click, &mut platform);
assert_eq!(firmware.os.lifecycle().task_state(dummy_task), Some(TaskState::Closed));
assert_eq!(
firmware.os.lifecycle().process_state_for_task(dummy_task),
Ok(ProcessState::Stopped)
);
assert_eq!(
firmware.os.sessions().vm_session_for_task(dummy_task).map(|session| session.task_id),
None
);
assert_eq!(
platform.assets().slot_info(SlotRef { asset_type: BankType::GLYPH, index: 0 }).asset_id,
Some(100)
);
assert_eq!(
platform.assets().slot_info(SlotRef { asset_type: BankType::SCENE, index: 0 }).asset_id,
Some(1)
);
assert!(platform.local_hardware().memory_banks.glyph_bank_slot(0).is_some());
assert!(platform.local_hardware().memory_banks.scene_bank_slot(0).is_some());
let second_stress_task = firmware
.os
.lifecycle()
.resident_game_task()
.expect("Stress should be resident after switching back");
assert_ne!(second_stress_task, stress_task);
assert_ne!(second_stress_task, dummy_task);
firmware.tick(&InputSignals::default(), &mut platform);
match &firmware.state {
FirmwareState::GameRunning(step) => assert_eq!(step.task_id, second_stress_task),
other => panic!("expected second Stress GameRunning state, got {:?}", other),
}
assert_eq!(firmware.os.vm().current_app_id(), 1);
assert_eq!(firmware.os.vm().current_cartridge_title(), "Stress Console");
firmware.tick(&InputSignals::default(), &mut platform);
let stress_ownership = firmware.os.vm().active_render_ownership();
assert_eq!(stress_ownership.app_mode, AppMode::Game);
assert_eq!(stress_ownership.app_id, 1);
}
#[test]
fn resident_game_termination_noops_when_no_game_is_resident() {
let (mut firmware, mut platform) = hub_home_firmware();
let ownership_before = firmware.os.vm().active_render_ownership();
let outcome = resident_game_termination::terminate_resident_game(
&mut firmware.os,
&mut platform,
true,
)
.expect("no resident game termination should not fail");
assert_eq!(outcome, ResidentGameTerminationOutcome::NoResidentGame);
assert_eq!(firmware.os.vm().active_render_ownership(), ownership_before);
assert_eq!(firmware.os.lifecycle().resident_game_task(), None);
assert!(
!firmware
.os
.recent_logs(16)
.iter()
.any(|event| event.msg.contains("Resident game killed from Hub"))
);
}
#[test]
fn resident_game_termination_closes_session_and_cleans_runtime_state() {
let library = discover_games_root(repository_test_cartridges_root());
let (mut firmware, mut platform) = hub_home_firmware();
firmware.hub.set_game_library(library);
firmware.tick(&InputSignals::default(), &mut platform);
let stress_click =
InputSignals { f_signal: true, x_pos: 72, y_pos: 118, ..Default::default() };
firmware.tick(&stress_click, &mut platform);
firmware.tick(&InputSignals::default(), &mut platform);
let stress_task = match &firmware.state {
FirmwareState::GameRunning(step) => step.task_id,
other => panic!("expected Stress GameRunning state, got {:?}", other),
};
firmware.request_home_from_host();
firmware.tick(&InputSignals::default(), &mut platform);
assert!(matches!(firmware.state, FirmwareState::HubHome(_)));
assert_eq!(firmware.os.lifecycle().resident_game_task(), Some(stress_task));
assert!(firmware.game_lifecycle_audio_paused());
assert_eq!(
platform.assets().slot_info(SlotRef { asset_type: BankType::GLYPH, index: 0 }).asset_id,
Some(100)
);
assert_eq!(
platform.assets().slot_info(SlotRef { asset_type: BankType::SCENE, index: 0 }).asset_id,
Some(1)
);
assert!(platform.local_hardware().memory_banks.glyph_bank_slot(0).is_some());
assert!(platform.local_hardware().memory_banks.scene_bank_slot(0).is_some());
let outcome = resident_game_termination::terminate_resident_game(
&mut firmware.os,
&mut platform,
true,
)
.expect("resident game termination should succeed");
assert_eq!(
outcome,
ResidentGameTerminationOutcome::Terminated {
task_id: stress_task,
title: "Stress Console".to_string()
}
);
assert_eq!(firmware.os.lifecycle().resident_game_task(), None);
assert_eq!(firmware.os.lifecycle().task_state(stress_task), Some(TaskState::Closed));
assert_eq!(
firmware.os.lifecycle().process_state_for_task(stress_task),
Ok(ProcessState::Stopped)
);
assert_eq!(
firmware.os.sessions().vm_session_for_task(stress_task).map(|session| session.task_id),
None
);
assert!(!firmware.game_lifecycle_audio_paused());
let ownership = firmware.os.vm().active_render_ownership();
assert_eq!(ownership.app_mode, AppMode::Shell);
assert_eq!(ownership.app_id, 0);
assert_eq!(platform.local_hardware().frame_composer.active_scene_id(), None);
assert_eq!(
platform.assets().slot_info(SlotRef { asset_type: BankType::GLYPH, index: 0 }).asset_id,
None
);
assert_eq!(
platform.assets().slot_info(SlotRef { asset_type: BankType::SCENE, index: 0 }).asset_id,
None
);
assert!(platform.local_hardware().memory_banks.glyph_bank_slot(0).is_none());
assert!(platform.local_hardware().memory_banks.scene_bank_slot(0).is_none());
assert!(
firmware.os.recent_logs(32).iter().any(|event| {
event.level == LogLevel::Info
&& event.source == LogSource::Hub
&& event.msg == "Resident game killed from Hub: Stress Console"
}),
"manual Hub kill should emit an INFO log"
);
}
#[test]
fn hub_kill_control_click_terminates_resident_game_and_stays_home() {
let library = discover_games_root(repository_test_cartridges_root());
let (mut firmware, mut platform) = hub_home_firmware();
firmware.hub.set_game_library(library);
firmware.tick(&InputSignals::default(), &mut platform);
let stress_click =
InputSignals { f_signal: true, x_pos: 72, y_pos: 118, ..Default::default() };
firmware.tick(&stress_click, &mut platform);
firmware.tick(&InputSignals::default(), &mut platform);
let stress_task = match &firmware.state {
FirmwareState::GameRunning(step) => step.task_id,
other => panic!("expected Stress GameRunning state, got {:?}", other),
};
firmware.request_home_from_host();
firmware.tick(&InputSignals::default(), &mut platform);
firmware.tick(&InputSignals::default(), &mut platform);
assert!(matches!(firmware.state, FirmwareState::HubHome(_)));
assert_eq!(firmware.os.lifecycle().resident_game_task(), Some(stress_task));
let kill_sample_x = HUB_SUSPENDED_GAME_KILL_CONTROL.x + 2;
let kill_sample_y = HUB_SUSPENDED_GAME_KILL_CONTROL.y + 2;
assert_eq!(
front_buffer_pixel(&platform, kill_sample_x, kill_sample_y),
Color::rgb(164, 32, 40).raw(),
"Hub should render the suspended-game kill control before click"
);
let kill_click = InputSignals {
f_signal: true,
x_pos: HUB_SUSPENDED_GAME_KILL_CONTROL.x,
y_pos: HUB_SUSPENDED_GAME_KILL_CONTROL.y,
..Default::default()
};
firmware.tick(&kill_click, &mut platform);
assert!(matches!(firmware.state, FirmwareState::HubHome(_)));
assert_eq!(firmware.os.lifecycle().foreground_owner(), ForegroundOwner::Hub);
assert_eq!(firmware.os.lifecycle().resident_game_task(), None);
assert_eq!(firmware.os.lifecycle().resident_game(), None);
assert_eq!(firmware.os.lifecycle().task_state(stress_task), Some(TaskState::Closed));
assert_eq!(
firmware.os.lifecycle().process_state_for_task(stress_task),
Ok(ProcessState::Stopped)
);
assert_eq!(
firmware.os.sessions().vm_session_for_task(stress_task).map(|session| session.task_id),
None
);
assert!(!firmware.game_lifecycle_audio_paused());
assert!(!firmware.resume_resident_game_from_home());
let ownership = firmware.os.vm().active_render_ownership();
assert_eq!(ownership.app_mode, AppMode::Shell);
assert_eq!(ownership.app_id, 0);
assert_eq!(platform.local_hardware().frame_composer.active_scene_id(), None);
assert_eq!(
platform.assets().slot_info(SlotRef { asset_type: BankType::GLYPH, index: 0 }).asset_id,
None
);
assert_eq!(
platform.assets().slot_info(SlotRef { asset_type: BankType::SCENE, index: 0 }).asset_id,
None
);
assert!(platform.local_hardware().memory_banks.glyph_bank_slot(0).is_none());
assert!(platform.local_hardware().memory_banks.scene_bank_slot(0).is_none());
assert!(
firmware.os.recent_logs(32).iter().any(|event| {
event.level == LogLevel::Info
&& event.source == LogSource::Hub
&& event.msg == "Resident game killed from Hub: Stress Console"
}),
"Hub kill control should use the canonical manual kill log"
);
firmware.tick(&InputSignals::default(), &mut platform);
assert_eq!(
front_buffer_pixel(&platform, kill_sample_x, kill_sample_y),
Color::rgb(12, 14, 22).raw(),
"Hub should stop rendering the kill control after the game is gone"
);
}
#[test]
fn failed_game_switch_returns_home_without_restoring_previous_game() {
let root = TestGameRoot::new();
root.add_game("stress", true);
root.add_game_with_program("zzz-broken", 43, "Zzz Broken", "1.0.0", Some(vec![0, 0, 0, 0]));
let (mut firmware, mut platform) = hub_home_firmware();
firmware.hub.set_game_library(discover_games_root(&root.path));
firmware.tick(&InputSignals::default(), &mut platform);
let stress_click =
InputSignals { f_signal: true, x_pos: 72, y_pos: 90, ..Default::default() };
firmware.tick(&stress_click, &mut platform);
firmware.tick(&InputSignals::default(), &mut platform);
let first_game_task = match &firmware.state {
FirmwareState::GameRunning(step) => step.task_id,
other => panic!("expected first GameRunning state, got {:?}", other),
};
firmware.request_home_from_host();
firmware.tick(&InputSignals::default(), &mut platform);
firmware.tick(&InputSignals::default(), &mut platform);
let broken_click =
InputSignals { f_signal: true, x_pos: 72, y_pos: 118, ..Default::default() };
firmware.tick(&broken_click, &mut platform);
assert_eq!(firmware.os.lifecycle().task_state(first_game_task), Some(TaskState::Closed));
assert_eq!(
firmware
.os
.sessions()
.vm_session_for_task(first_game_task)
.map(|session| session.task_id),
None
);
let partial_task = firmware
.os
.lifecycle()
.resident_game_task()
.expect("failed target should be resident until recovery tick");
assert_ne!(partial_task, first_game_task);
firmware.tick(&InputSignals::default(), &mut platform);
assert!(matches!(firmware.state, FirmwareState::HubHome(_)));
assert_eq!(firmware.os.lifecycle().resident_game_task(), None);
assert_eq!(firmware.os.lifecycle().task_state(first_game_task), Some(TaskState::Closed));
assert_eq!(firmware.os.lifecycle().task_state(partial_task), Some(TaskState::Closed));
assert_eq!(
firmware.os.lifecycle().process_state_for_task(partial_task),
Ok(ProcessState::Stopped)
);
assert_eq!(
firmware.os.sessions().vm_session_for_task(partial_task).map(|session| session.task_id),
None
);
assert!(
firmware
.os
.recent_logs(16)
.iter()
.any(|event| event.msg.contains("Failed to switch to game Zzz Broken app_id 43"))
);
}
#[test]
fn invalid_games_root_candidate_is_omitted_from_home_launch_boundary() {
let root = TestGameRoot::new();
@@ -899,6 +1441,8 @@ mod tests {
};
let tick_index_before_home = firmware.os.vm().tick_index();
let render_ownership_before_home = firmware.os.vm().active_render_ownership();
assert_eq!(render_ownership_before_home.app_mode, AppMode::Game);
assert_eq!(render_ownership_before_home.app_id, 9);
firmware.request_home_from_host();
@@ -930,7 +1474,6 @@ mod tests {
let render_ownership_after_home = firmware.os.vm().active_render_ownership();
assert_eq!(render_ownership_after_home.app_mode, AppMode::Shell);
assert_eq!(render_ownership_after_home.app_id, 0);
assert!(render_ownership_after_home.epoch > render_ownership_before_home.epoch);
assert!(firmware.os.lifecycle().pending_game_lifecycle_events().is_empty());
assert_eq!(
firmware.os.vm().delivered_game_lifecycle_events().last().map(|event| event.kind),
@@ -959,6 +1502,8 @@ mod tests {
firmware.request_home_from_host();
firmware.tick(&signals, &mut platform);
let hub_ownership = firmware.os.vm().active_render_ownership();
assert_eq!(hub_ownership.app_mode, AppMode::Shell);
assert_eq!(hub_ownership.app_id, 0);
assert!(firmware.resume_resident_game_from_home());
assert!(matches!(firmware.state, FirmwareState::GameRunning(_)));
@@ -971,7 +1516,6 @@ mod tests {
let game_ownership = firmware.os.vm().active_render_ownership();
assert_eq!(game_ownership.app_mode, AppMode::Game);
assert_eq!(game_ownership.app_id, 9);
assert!(game_ownership.epoch > hub_ownership.epoch);
let held_signals =
InputSignals { up_signal: true, f_signal: true, x_pos: 72, y_pos: 90, ..signals };
@@ -2,6 +2,7 @@ use crate::firmware::firmware_state::{
AppCrashesStep, FirmwareState, LoadCartridgeStep, ShellRunningStep,
};
use crate::firmware::prometeu_context::PrometeuContext;
use crate::firmware::resident_game_termination;
use prometeu_hal::app_mode::AppMode;
use prometeu_hal::cartridge_loader::CartridgeLoader;
use prometeu_hal::log::{LogLevel, LogSource};
@@ -20,14 +21,29 @@ impl HubHomeStep {
}
pub fn on_update(&mut self, ctx: &mut PrometeuContext) -> Option<FirmwareState> {
let outcome = ctx.hub.update_shell_profile(ctx.os, ctx.vm, ctx.signals, ctx.platform);
let outcome = ctx.hub.update_shell_profile(ctx.os, ctx.platform);
if let Some(report) = outcome.crash {
return Some(FirmwareState::AppCrashes(AppCrashesStep { report }));
}
match outcome.action {
Some(SystemProfileAction::LaunchNativeShell(app)) => {
let task_id = ctx.os.sessions().create_native_shell_task(app.app_id(), app.title());
let task_id = match ctx
.os
.sessions()
.try_create_native_shell_task(app.app_id(), app.title())
{
Ok(task_id) => task_id,
Err(error) => {
ctx.os.log(
LogLevel::Warn,
LogSource::Hub,
0,
format!("Failed to launch native shell {}: {:?}", app.title(), error),
);
return None;
}
};
let id = ctx.os.windows().add_window(
app.title().to_string(),
WindowOwner::Task(task_id),
@@ -37,45 +53,71 @@ impl HubHomeStep {
ctx.os.windows().set_focus(id);
return Some(FirmwareState::ShellRunning(ShellRunningStep::new(task_id)));
}
Some(SystemProfileAction::LaunchGame { path }) => match CartridgeLoader::load(&path) {
Ok(cartridge) => {
if cartridge.app_mode == AppMode::Game
&& let Some(resident_task_id) = ctx.os.lifecycle().resident_game_task()
{
let resident_app_id = ctx
.os
.sessions()
.vm_session_for_task(resident_task_id)
.map(|session| session.app_id)
.unwrap_or(0);
Some(SystemProfileAction::LaunchGame { target }) => {
match CartridgeLoader::load(&target.path) {
Ok(cartridge) => {
if cartridge.app_mode == AppMode::Game
&& let Some(resident_task_id) = ctx.os.lifecycle().resident_game_task()
{
let resident_app_id = ctx
.os
.sessions()
.vm_session_for_task(resident_task_id)
.map(|session| session.app_id)
.unwrap_or(0);
if resident_app_id == cartridge.app_id {
return Some(FirmwareState::ResumeResidentGame);
if resident_app_id == cartridge.app_id {
return Some(FirmwareState::ResumeResidentGame);
}
if let Err(error) = resident_game_termination::terminate_resident_game(
ctx.os,
ctx.platform,
false,
) {
ctx.os.log(
LogLevel::Error,
LogSource::Hub,
0,
format!(
"Failed to terminate resident game app_id {} before launching {}: {:?}",
resident_app_id, cartridge.title, error
),
);
return None;
}
}
return Some(FirmwareState::LoadCartridge(
LoadCartridgeStep::new_game_switch(cartridge),
));
}
Err(error) => {
ctx.os.log(
LogLevel::Warn,
LogLevel::Error,
LogSource::Hub,
0,
format!(
"Cannot launch Home game {} while resident game app_id {} is active",
cartridge.title, resident_app_id
"Failed to launch Home game {}: {:?}",
target.path.display(),
error
),
);
return None;
}
return Some(FirmwareState::LoadCartridge(LoadCartridgeStep::new(cartridge)));
}
Err(error) => {
}
Some(SystemProfileAction::KillResidentGame) => {
if let Err(error) =
resident_game_termination::terminate_resident_game(ctx.os, ctx.platform, true)
{
ctx.os.log(
LogLevel::Error,
LogSource::Hub,
0,
format!("Failed to launch Home game {}: {:?}", path.display(), error),
format!("Failed to kill resident game from Hub: {error:?}"),
);
}
},
}
Some(SystemProfileAction::CloseShell) | None => {}
}
@@ -1,7 +1,8 @@
use crate::firmware::firmware_state::{
AppCrashesStep, FirmwareState, GameRunningStep, ShellRunningStep,
AppCrashesStep, FirmwareState, GameRunningStep, HubHomeStep, ShellRunningStep,
};
use crate::firmware::prometeu_context::PrometeuContext;
use crate::firmware::resident_game_termination;
use prometeu_hal::app_mode::AppMode;
use prometeu_hal::cartridge::Cartridge;
use prometeu_hal::color::Color;
@@ -16,11 +17,28 @@ pub struct LoadCartridgeStep {
init_error: Option<CrashReport>,
loaded_task_id: Option<prometeu_system::task::TaskId>,
loaded_app_mode: Option<AppMode>,
failure_recovery: LoadCartridgeFailureRecovery,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum LoadCartridgeFailureRecovery {
AppCrash,
ReturnToHub,
}
impl LoadCartridgeStep {
pub fn new(cartridge: Cartridge) -> Self {
Self { cartridge, init_error: None, loaded_task_id: None, loaded_app_mode: None }
Self {
cartridge,
init_error: None,
loaded_task_id: None,
loaded_app_mode: None,
failure_recovery: LoadCartridgeFailureRecovery::AppCrash,
}
}
pub fn new_game_switch(cartridge: Cartridge) -> Self {
Self { failure_recovery: LoadCartridgeFailureRecovery::ReturnToHub, ..Self::new(cartridge) }
}
pub fn on_enter(&mut self, ctx: &mut PrometeuContext) {
@@ -31,6 +49,8 @@ impl LoadCartridgeStep {
format!("Loading cartridge: {}", self.cartridge.title),
);
ctx.platform.game2d_frame_composer().unbind_scene();
// Initialize Asset Manager
ctx.platform.assets_mut().initialize_for_cartridge(
self.cartridge.asset_table.clone(),
@@ -38,19 +58,51 @@ impl LoadCartridgeStep {
self.cartridge.assets.clone(),
);
match ctx.os.sessions().load_vm_cartridge(ctx.vm, &self.cartridge) {
match ctx.os.sessions().load_vm_cartridge(&self.cartridge) {
Ok(loaded) => {
self.loaded_task_id = Some(loaded.task_id);
self.loaded_app_mode = Some(loaded.app_mode);
}
Err(report) => {
self.init_error = Some(report);
self.init_error = Some(report.into_crash_report("load VM cartridge into session"));
}
}
}
pub fn on_update(&mut self, ctx: &mut PrometeuContext) -> Option<FirmwareState> {
if let Some(report) = self.init_error.take() {
if self.failure_recovery == LoadCartridgeFailureRecovery::ReturnToHub {
if self.cartridge.app_mode == AppMode::Game
&& let Some(task_id) = ctx.os.lifecycle().resident_game_task()
{
let is_partial_target = ctx
.os
.sessions()
.vm_session_for_task(task_id)
.map(|session| session.app_id == self.cartridge.app_id)
.unwrap_or(false);
if is_partial_target {
let _ = resident_game_termination::terminate_resident_game(
ctx.os,
ctx.platform,
false,
);
}
}
ctx.os.log(
LogLevel::Error,
LogSource::Hub,
0,
format!(
"Failed to switch to game {} app_id {}; returning to Home: {:?}",
self.cartridge.title, self.cartridge.app_id, report
),
);
return Some(FirmwareState::HubHome(HubHomeStep));
}
return Some(FirmwareState::AppCrashes(AppCrashesStep { report }));
}
@@ -9,7 +9,8 @@ pub struct ResetStep;
impl ResetStep {
pub fn on_enter(&mut self, ctx: &mut PrometeuContext) {
ctx.os.log(LogLevel::Info, LogSource::Pos, 0, "Firmware Reset".to_string());
ctx.os.vm().reset(ctx.vm);
ctx.os.sessions().clear_vm_sessions();
ctx.os.vm().reset_global_runtime_state();
}
pub fn on_update(&mut self, ctx: &mut PrometeuContext) -> Option<FirmwareState> {
@@ -12,6 +12,7 @@ pub(crate) mod firmware_step_reset;
pub(crate) mod firmware_step_shell_running;
pub(crate) mod firmware_step_splash_screen;
mod prometeu_context;
pub(crate) mod resident_game_termination;
pub use boot_target::BootTarget;
pub use firmware::Firmware;
@@ -1,10 +1,8 @@
use crate::firmware::boot_target::BootTarget;
use prometeu_hal::{InputSignals, RuntimePlatform};
use prometeu_system::{PrometeuHub, SystemOS};
use prometeu_vm::VirtualMachine;
pub struct PrometeuContext<'a> {
pub vm: &'a mut VirtualMachine,
pub os: &'a mut SystemOS,
pub hub: &'a mut PrometeuHub,
pub boot_target: &'a BootTarget,
@@ -0,0 +1,42 @@
use prometeu_hal::RuntimePlatform;
use prometeu_hal::app_mode::AppMode;
use prometeu_hal::log::LogSource;
use prometeu_system::task::TaskId;
use prometeu_system::{LifecycleError, SystemOS};
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) enum ResidentGameTerminationOutcome {
NoResidentGame,
Terminated { task_id: TaskId, title: String },
}
pub(crate) fn terminate_resident_game(
os: &mut SystemOS,
platform: &mut dyn RuntimePlatform,
log_manual_hub_kill: bool,
) -> Result<ResidentGameTerminationOutcome, LifecycleError> {
let Some(task_id) = os.lifecycle().resident_game_task() else {
return Ok(ResidentGameTerminationOutcome::NoResidentGame);
};
let title = os
.sessions()
.vm_session_for_task(task_id)
.map(|session| session.title.clone())
.unwrap_or_else(|| "<unknown>".to_string());
let terminated = os.lifecycle().terminate_resident_game()?;
let Some(task_id) = terminated else {
return Ok(ResidentGameTerminationOutcome::NoResidentGame);
};
os.vm().transition_render_owner(AppMode::Shell, 0);
platform.game2d_frame_composer().unbind_scene();
platform.assets_mut().shutdown();
if log_manual_hub_kill {
os.info(LogSource::Hub, format!("Resident game killed from Hub: {title}"));
}
Ok(ResidentGameTerminationOutcome::Terminated { task_id, title })
}
@@ -203,7 +203,7 @@ mod tests {
use super::*;
use crate::asset::{AssetCodec, AssetEntry, BankType, PreloadEntry};
use crate::cartridge::{ASSETS_PA_MAGIC, ASSETS_PA_SCHEMA_VERSION, AssetsPackPrelude};
use crate::glyph_bank::GLYPH_BANK_PALETTE_COUNT_V1;
use crate::glyph_bank::GLYPH_BANK_MAX_PALETTE_COUNT_V1;
use serde_json::json;
use std::path::{Path, PathBuf};
use std::sync::atomic::{AtomicU64, Ordering};
@@ -369,14 +369,14 @@ mod tests {
bank_type: BankType::GLYPH,
offset,
size,
decoded_size: 16 * 16 + (GLYPH_BANK_PALETTE_COUNT_V1 as u64 * 16 * 4),
decoded_size: 16 * 16 + (GLYPH_BANK_MAX_PALETTE_COUNT_V1 as u64 * 16 * 4),
codec: AssetCodec::None,
metadata: json!({
"tile_size": 16,
"width": 16,
"height": 16,
"palette_count": GLYPH_BANK_PALETTE_COUNT_V1,
"palette_authored": GLYPH_BANK_PALETTE_COUNT_V1
"palette_count": GLYPH_BANK_MAX_PALETTE_COUNT_V1,
"palette_authored": GLYPH_BANK_MAX_PALETTE_COUNT_V1
}),
}
}
@@ -452,14 +452,14 @@ mod tests {
bank_type: BankType::GLYPH,
offset: 4,
size: 4,
decoded_size: 16 * 16 + (GLYPH_BANK_PALETTE_COUNT_V1 as u64 * 16 * 4),
decoded_size: 16 * 16 + (GLYPH_BANK_MAX_PALETTE_COUNT_V1 as u64 * 16 * 4),
codec: AssetCodec::None,
metadata: json!({
"tile_size": 16,
"width": 16,
"height": 16,
"palette_count": GLYPH_BANK_PALETTE_COUNT_V1,
"palette_authored": GLYPH_BANK_PALETTE_COUNT_V1
"palette_count": GLYPH_BANK_MAX_PALETTE_COUNT_V1,
"palette_authored": GLYPH_BANK_MAX_PALETTE_COUNT_V1
}),
},
];
@@ -519,8 +519,8 @@ mod tests {
"tile_size": 16,
"width": 16,
"height": 16,
"palette_count": GLYPH_BANK_PALETTE_COUNT_V1,
"palette_authored": GLYPH_BANK_PALETTE_COUNT_V1
"palette_count": GLYPH_BANK_MAX_PALETTE_COUNT_V1,
"palette_authored": GLYPH_BANK_MAX_PALETTE_COUNT_V1
}
}],
"preload": []
@@ -561,8 +561,8 @@ mod tests {
"tile_size": 16,
"width": 16,
"height": 16,
"palette_count": GLYPH_BANK_PALETTE_COUNT_V1,
"palette_authored": GLYPH_BANK_PALETTE_COUNT_V1
"palette_count": GLYPH_BANK_MAX_PALETTE_COUNT_V1,
"palette_authored": GLYPH_BANK_MAX_PALETTE_COUNT_V1
}
}],
"preload": []
@@ -40,7 +40,7 @@ pub enum DebugResponse {
Breakpoints { pcs: Vec<usize> },
}
#[derive(Debug, Serialize, Deserialize)]
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct HandshakeCartridge {
pub app_id: u32,
pub title: String,
+81 -7
View File
@@ -1,7 +1,7 @@
use crate::color::Color;
use serde::{Deserialize, Serialize};
pub const GLYPH_BANK_PALETTE_COUNT_V1: usize = 64;
pub const GLYPH_BANK_MAX_PALETTE_COUNT_V1: usize = 64;
pub const GLYPH_BANK_COLORS_PER_PALETTE: usize = 16;
/// Standard sizes for square tiles.
@@ -35,22 +35,59 @@ pub struct GlyphBank {
/// Palette indices are ordinary indices; transparency is resolved through
/// the RGBA alpha channel of the palette entry.
pub pixel_indices: Vec<u8>,
/// Runtime-facing v1 palette table: 64 palettes of 16 RGBA8888 colors each.
pub palettes: [[Color; GLYPH_BANK_COLORS_PER_PALETTE]; GLYPH_BANK_PALETTE_COUNT_V1],
/// Runtime-facing v1 palette table.
///
/// Palette identity is the direct index in this vector. A resident glyph
/// bank carries exactly the palettes materialized from its payload.
pub palettes: Vec<[Color; GLYPH_BANK_COLORS_PER_PALETTE]>,
}
impl GlyphBank {
/// Creates an empty glyph bank with the specified dimensions.
/// Creates an empty glyph bank with one palette.
pub fn new(tile_size: TileSize, width: usize, height: usize) -> Self {
Self::with_palette_count(tile_size, width, height, 1)
}
/// Creates an empty glyph bank with the specified resident palette count.
pub fn with_palette_count(
tile_size: TileSize,
width: usize,
height: usize,
palette_count: usize,
) -> Self {
assert!(
(1..=GLYPH_BANK_MAX_PALETTE_COUNT_V1).contains(&palette_count),
"glyph bank palette_count must be in 1..={}",
GLYPH_BANK_MAX_PALETTE_COUNT_V1
);
Self {
tile_size,
width,
height,
pixel_indices: vec![0; width * height],
palettes: [[Color::BLACK; GLYPH_BANK_COLORS_PER_PALETTE]; GLYPH_BANK_PALETTE_COUNT_V1],
palettes: vec![[Color::BLACK; GLYPH_BANK_COLORS_PER_PALETTE]; palette_count],
}
}
/// Returns the number of resident palettes.
pub fn palette_count(&self) -> usize {
self.palettes.len()
}
/// Returns true when the palette id is valid for this resident bank.
pub fn contains_palette(&self, palette_id: u8) -> bool {
(palette_id as usize) < self.palette_count()
}
/// Returns a mutable palette slot when the palette exists.
pub fn palette_mut(
&mut self,
palette_id: u8,
) -> Option<&mut [Color; GLYPH_BANK_COLORS_PER_PALETTE]> {
self.palettes.get_mut(palette_id as usize)
}
/// Resolves a global tile ID and local pixel coordinates to a palette index.
/// tile_id: the tile index in the bank
/// local_x, local_y: the pixel position inside the tile (0 to tile_size-1)
@@ -71,11 +108,48 @@ impl GlyphBank {
}
/// Maps a 4-bit index to a real RGBA8888 Color using the specified palette.
pub fn resolve_color(&self, palette_id: u8, pixel_index: u8) -> Color {
pub fn resolve_color(&self, palette_id: u8, pixel_index: u8) -> Option<Color> {
self.palettes
.get(palette_id as usize)
.and_then(|palette| palette.get(pixel_index as usize))
.copied()
.unwrap_or(Color::TRANSPARENT)
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn new_glyph_bank_uses_single_resident_palette() {
let bank = GlyphBank::new(TileSize::Size8, 8, 8);
assert_eq!(bank.palette_count(), 1);
assert!(bank.contains_palette(0));
assert!(!bank.contains_palette(1));
}
#[test]
fn glyph_bank_can_materialize_v1_max_palette_count() {
let bank =
GlyphBank::with_palette_count(TileSize::Size8, 8, 8, GLYPH_BANK_MAX_PALETTE_COUNT_V1);
assert_eq!(bank.palette_count(), GLYPH_BANK_MAX_PALETTE_COUNT_V1);
assert!(bank.contains_palette((GLYPH_BANK_MAX_PALETTE_COUNT_V1 - 1) as u8));
}
#[test]
fn invalid_palette_lookup_is_distinct_from_transparent_color() {
let mut bank = GlyphBank::new(TileSize::Size8, 8, 8);
bank.palette_mut(0).unwrap()[1] = Color::TRANSPARENT;
assert_eq!(bank.resolve_color(0, 1), Some(Color::TRANSPARENT));
assert_eq!(bank.resolve_color(1, 1), None);
}
#[test]
#[should_panic(expected = "glyph bank palette_count must be in 1..=64")]
fn glyph_bank_rejects_zero_resident_palettes() {
let _ = GlyphBank::with_palette_count(TileSize::Size8, 8, 8, 0);
}
}
+6 -3
View File
@@ -6,9 +6,12 @@ mod services;
pub use crash_report::CrashReport;
pub use os::{
DEFAULT_GAME_PAUSE_BUDGET_TICKS, GameLifecycleEvent, GameLifecycleEventKind, LifecycleError,
LifecycleOperation, SystemOS,
LifecycleOperation, SessionError, SystemOS,
};
pub use programs::{
HUB_SUSPENDED_GAME_KILL_CONTROL, NativeShellApp, PrometeuHub, SystemProfileAction,
SystemProfileUpdate,
};
pub use programs::{NativeShellApp, PrometeuHub, SystemProfileAction, SystemProfileUpdate};
pub use prometeu_hal::{RenderWorkerBackend, RenderWorkerFrameSink};
pub use services::async_work::{
AsyncWorkActiveJob, AsyncWorkCancelToken, AsyncWorkJobContext, AsyncWorkJobId,
@@ -20,7 +23,7 @@ pub use services::foreground::{
};
pub use services::fs;
pub use services::game_library::{
GameLibrary, GameLibraryDiagnostic, GameLibraryEntry, discover_games_root,
GameLibrary, GameLibraryDiagnostic, GameLibraryEntry, GameSwitchTarget, discover_games_root,
};
pub use services::memcard::MemcardAsyncLaneOperation;
pub use services::process;
@@ -222,6 +222,28 @@ impl<'a> LifecycleFacade<'a> {
Ok(())
}
pub fn terminate_resident_game(&mut self) -> Result<Option<TaskId>, LifecycleError> {
let Some(task_id) = self.os.foreground_stack.resident_game_task() else {
return Ok(None);
};
let process_id = process_id_for_task(self.os, task_id)?;
self.os.task_manager.close_task(task_id);
self.os.process_manager.mark_stopped(process_id);
self.os.foreground_stack.clear_resident_game(task_id);
self.os.vm_sessions.remove_for_task(task_id);
self.os.game_lifecycle_events.retain(|event| event.task_id != task_id);
if matches!(self.os.foreground_stack.owner(), ForegroundOwner::Game(owner) if owner == task_id)
{
self.os.foreground_stack.return_to_hub();
self.os.task_manager.clear_foreground();
}
Ok(Some(task_id))
}
pub fn crash_task(
&mut self,
task_id: TaskId,
@@ -6,6 +6,6 @@ mod window;
pub use fs::FsFacade;
pub use lifecycle::LifecycleFacade;
pub use sessions::SessionsFacade;
pub use sessions::{SessionError, SessionsFacade};
pub use vm::VmFacade;
pub use window::WindowFacade;
@@ -1,11 +1,11 @@
use crate::CrashReport;
use crate::os::LifecycleError;
use crate::os::SystemOS;
use crate::process::ProcessId;
use crate::task::TaskId;
use crate::vm_session::{VmSession, VmSessionError};
use prometeu_hal::app_mode::AppMode;
use prometeu_hal::cartridge::Cartridge;
use prometeu_vm::VirtualMachine;
use std::sync::Arc;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
@@ -15,21 +15,55 @@ pub struct LoadedVmCartridge {
pub reused_existing_session: bool,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum SessionError {
Lifecycle(LifecycleError),
VmSession(VmSessionError),
TaskNotFound(TaskId),
ProcessNotFound(ProcessId),
MissingVmSession(TaskId),
Initialization(CrashReport),
}
impl SessionError {
pub fn into_crash_report(self, operation: &str) -> CrashReport {
match self {
Self::Initialization(report) => report,
error => {
CrashReport::VmPanic { message: format!("{operation} failed: {error:?}"), pc: None }
}
}
}
}
impl From<LifecycleError> for SessionError {
fn from(error: LifecycleError) -> Self {
Self::Lifecycle(error)
}
}
impl From<VmSessionError> for SessionError {
fn from(error: VmSessionError) -> Self {
Self::VmSession(error)
}
}
pub struct SessionsFacade<'a> {
pub(in crate::os) os: &'a mut SystemOS,
}
impl<'a> SessionsFacade<'a> {
#[cfg(test)]
pub fn create_vm_game_task(&mut self, app_id: u32, title: impl Into<String>) -> TaskId {
self.try_create_vm_game_task(app_id, title)
.expect("newly created game task should have an associated process")
.expect("test/setup VM game creation should succeed")
}
pub fn try_create_vm_game_task(
&mut self,
app_id: u32,
title: impl Into<String>,
) -> Result<TaskId, LifecycleError> {
) -> Result<TaskId, SessionError> {
if let Some(session) = self.os.vm_sessions.resident_game_for_app(app_id) {
return Ok(session.task_id);
}
@@ -38,43 +72,54 @@ impl<'a> SessionsFacade<'a> {
let process_id = self.os.process_manager.spawn_vm_game(app_id, title.clone());
let task_id = self.os.task_manager.create_game_task(process_id, app_id, title);
self.os.lifecycle().set_game_foreground_task(task_id)?;
self.create_vm_session_for_task(task_id)
.expect("newly created game task should create a VM session");
self.try_create_vm_session_for_task(task_id)?;
Ok(task_id)
}
#[cfg(test)]
pub fn create_vm_shell_task(&mut self, app_id: u32, title: impl Into<String>) -> TaskId {
self.try_create_vm_shell_task(app_id, title)
.expect("test/setup VM shell creation should succeed")
}
pub fn try_create_vm_shell_task(
&mut self,
app_id: u32,
title: impl Into<String>,
) -> Result<TaskId, SessionError> {
let title = title.into();
let process_id = self.os.process_manager.spawn_vm_shell(app_id, title.clone());
let task_id = self.os.task_manager.create_shell_task(process_id, app_id, title);
self.os
.lifecycle()
.set_shell_foreground_task(task_id)
.expect("newly created shell task should have an associated process");
self.create_vm_session_for_task(task_id)
.expect("newly created shell task should create a VM session");
self.os.lifecycle().set_shell_foreground_task(task_id)?;
self.try_create_vm_session_for_task(task_id)?;
task_id
Ok(task_id)
}
#[cfg(test)]
pub fn create_native_shell_task(&mut self, app_id: u32, title: impl Into<String>) -> TaskId {
self.try_create_native_shell_task(app_id, title)
.expect("test/setup native shell creation should succeed")
}
pub fn try_create_native_shell_task(
&mut self,
app_id: u32,
title: impl Into<String>,
) -> Result<TaskId, SessionError> {
let title = title.into();
let process_id = self.os.process_manager.spawn_native_shell(app_id, title.clone());
let task_id = self.os.task_manager.create_shell_task(process_id, app_id, title);
self.os
.lifecycle()
.set_shell_foreground_task(task_id)
.expect("newly created native shell task should have an associated process");
self.os.lifecycle().set_shell_foreground_task(task_id)?;
task_id
Ok(task_id)
}
pub fn load_vm_cartridge(
&mut self,
legacy_vm: &mut VirtualMachine,
cartridge: &Cartridge,
) -> Result<LoadedVmCartridge, CrashReport> {
) -> Result<LoadedVmCartridge, SessionError> {
let existing_game_task = if cartridge.app_mode == AppMode::Game {
self.os
.vm_sessions
@@ -87,20 +132,15 @@ impl<'a> SessionsFacade<'a> {
let (task_id, reused_existing_session) = if let Some(task_id) = existing_game_task {
(task_id, true)
} else if cartridge.app_mode == AppMode::Shell {
(self.create_vm_shell_task(cartridge.app_id, cartridge.title.clone()), false)
(self.try_create_vm_shell_task(cartridge.app_id, cartridge.title.clone())?, false)
} else {
let task_id = self
.try_create_vm_game_task(cartridge.app_id, cartridge.title.clone())
.map_err(|error| CrashReport::VmPanic {
message: format!("failed to create VM game task: {error:?}"),
pc: None,
})?;
let task_id =
self.try_create_vm_game_task(cartridge.app_id, cartridge.title.clone())?;
(task_id, false)
};
if !reused_existing_session {
self.initialize_session_cartridge(task_id, cartridge)?;
self.initialize_legacy_active_vm(legacy_vm, cartridge)?;
self.try_initialize_session_cartridge(task_id, cartridge)?;
}
Ok(LoadedVmCartridge { task_id, app_mode: cartridge.app_mode, reused_existing_session })
@@ -122,13 +162,18 @@ impl<'a> SessionsFacade<'a> {
self.os.vm_sessions.len()
}
fn create_vm_session_for_task(&mut self, task_id: TaskId) -> Result<(), VmSessionError> {
let task = self.os.task_manager.get(task_id).expect("session task should exist").clone();
pub fn clear_vm_sessions(&mut self) {
self.os.vm_sessions.clear();
}
pub fn try_create_vm_session_for_task(&mut self, task_id: TaskId) -> Result<(), SessionError> {
let task =
self.os.task_manager.get(task_id).ok_or(SessionError::TaskNotFound(task_id))?.clone();
let process = self
.os
.process_manager
.get(task.process_id)
.expect("session process should exist")
.ok_or(SessionError::ProcessNotFound(task.process_id))?
.clone();
let cap_config = self.os.vm_runtime.certifier.config;
@@ -137,33 +182,28 @@ impl<'a> SessionsFacade<'a> {
.vm_sessions
.create_for_task(&task, &process, "", Some(cap_config), logs_count)
.map(|_| ())
.map_err(SessionError::from)
}
fn initialize_session_cartridge(
pub fn try_initialize_session_cartridge(
&mut self,
task_id: TaskId,
cartridge: &Cartridge,
) -> Result<(), CrashReport> {
) -> Result<(), SessionError> {
let session = self
.os
.vm_sessions
.for_task_mut(task_id)
.expect("loaded VM task should have a VM session");
.ok_or(SessionError::MissingVmSession(task_id))?;
session.app_id = cartridge.app_id;
session.title = cartridge.title.clone();
session.app_version = cartridge.app_version.clone();
session.app_mode = cartridge.app_mode;
session.clear_cartridge_service_state();
session.runtime.initialize_vm(&mut self.os.log_service, &mut session.vm, cartridge)
}
fn initialize_legacy_active_vm(
&mut self,
legacy_vm: &mut VirtualMachine,
cartridge: &Cartridge,
) -> Result<(), CrashReport> {
self.os.clear_cartridge_service_state();
self.os.vm_runtime.initialize_vm(&mut self.os.log_service, legacy_vm, cartridge)
session
.runtime
.initialize_vm(&mut self.os.log_service, &mut session.vm, cartridge)
.map_err(SessionError::Initialization)
}
}
@@ -3,14 +3,13 @@ use crate::os::{GameLifecycleEvent, SystemOS};
use crate::task::TaskId;
use crate::vm_session::VmSession;
use crate::{RenderWorkerConfig, RenderWorkerController};
use prometeu_bytecode::Value;
use prometeu_hal::app_mode::AppMode;
use prometeu_hal::cartridge::Cartridge;
use prometeu_hal::telemetry::{CertificationConfig, TelemetryFrame};
use prometeu_hal::{
FrameId, InputSignals, RenderOwnership, RenderWorkerBackend, RenderWorkerError,
RenderWorkerFrameSink, RuntimePlatform,
};
use prometeu_vm::VirtualMachine;
use std::sync::atomic::Ordering;
pub struct VmFacade<'a> {
@@ -18,36 +17,6 @@ pub struct VmFacade<'a> {
}
impl<'a> VmFacade<'a> {
pub fn initialize(
&mut self,
vm: &mut VirtualMachine,
cartridge: &Cartridge,
) -> Result<(), CrashReport> {
self.os.clear_cartridge_service_state();
self.os.vm_runtime.initialize_vm(&mut self.os.log_service, vm, cartridge)
}
pub fn tick(
&mut self,
vm: &mut VirtualMachine,
signals: &InputSignals,
platform: &mut dyn RuntimePlatform,
) -> Option<CrashReport> {
self.deliver_pending_game_lifecycle_events();
self.os.vm_runtime.tick(
&mut self.os.log_service,
&mut self.os.fs,
&mut self.os.fs_state,
&mut self.os.memcard,
&mut self.os.open_files,
&mut self.os.next_handle,
vm,
signals,
platform,
)
}
pub fn tick_session(
&mut self,
task_id: TaskId,
@@ -76,25 +45,6 @@ impl<'a> VmFacade<'a> {
)
}
pub fn deliver_pending_game_lifecycle_events(&mut self) {
if self.os.vm_runtime.current_cartridge_app_mode == AppMode::Game {
let resident_game_task = self.os.foreground_stack.resident_game_task();
let mut retained = Vec::new();
let mut delivered = Vec::new();
for event in self.os.game_lifecycle_events.drain(..) {
if Some(event.task_id) == resident_game_task {
delivered.push(event);
} else {
retained.push(event);
}
}
self.os.game_lifecycle_events = retained;
self.os.vm_runtime.deliver_game_lifecycle_events(delivered);
}
}
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;
@@ -121,16 +71,59 @@ impl<'a> VmFacade<'a> {
}
}
pub fn reset(&mut self, vm: &mut VirtualMachine) {
self.os.vm_runtime.reset(vm);
pub fn reset_global_runtime_state(&mut self) {
self.os.clear_cartridge_service_state();
self.os.vm_runtime.clear_cartridge_state();
}
pub fn debug_step_instruction(
pub fn debug_step_active_session(
&mut self,
vm: &mut VirtualMachine,
platform: &mut dyn RuntimePlatform,
) -> Option<CrashReport> {
self.os.vm_runtime.debug_step_instruction(&mut self.os.log_service, vm, platform)
let Some(task_id) = self.active_session_task_id() else {
return Some(CrashReport::VmPanic {
message: "debug step requested without an active VM session".to_string(),
pc: None,
});
};
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),
pc: None,
});
};
session.runtime.debug_step_instruction(&mut self.os.log_service, &mut session.vm, platform)
}
pub fn active_pc(&self) -> Option<usize> {
self.active_session().map(|session| session.vm.pc())
}
pub fn active_operand_stack_top(&self, n: usize) -> Vec<Value> {
self.active_session().map(|session| session.vm.operand_stack_top(n)).unwrap_or_default()
}
pub fn insert_active_breakpoint(&mut self, pc: usize) -> bool {
if let Some(session) = self.active_session_mut() {
session.vm.insert_breakpoint(pc);
return true;
}
false
}
pub fn remove_active_breakpoint(&mut self, pc: usize) -> bool {
if let Some(session) = self.active_session_mut() {
session.vm.remove_breakpoint(pc);
return true;
}
false
}
pub fn active_breakpoints_list(&self) -> Vec<usize> {
self.active_session().map(|session| session.vm.breakpoints_list()).unwrap_or_default()
}
pub fn paused(&self) -> bool {
@@ -257,6 +250,12 @@ impl<'a> VmFacade<'a> {
}
pub fn active_render_ownership(&self) -> RenderOwnership {
if let Some(task_id) = self.foreground_session_task_id()
&& let Some(session) = self.os.vm_sessions.for_task(task_id)
{
return session.runtime.render_manager.active_ownership();
}
self.os.vm_runtime.render_manager.active_ownership()
}
@@ -314,11 +313,18 @@ impl<'a> VmFacade<'a> {
}
fn active_session_mut(&mut self) -> Option<&mut VmSession> {
let task_id = self
.os
.task_manager
.foreground_task()
.or_else(|| self.os.foreground_stack.resident_game_task())?;
let task_id = self.active_session_task_id()?;
self.os.vm_sessions.for_task_mut(task_id)
}
fn active_session_task_id(&self) -> Option<TaskId> {
self.os
.task_manager
.foreground_task()
.or_else(|| self.os.foreground_stack.resident_game_task())
}
fn foreground_session_task_id(&self) -> Option<TaskId> {
self.os.task_manager.foreground_task()
}
}
+3 -1
View File
@@ -2,7 +2,9 @@ mod facades;
mod lifecycle;
mod system_os;
pub use facades::{FsFacade, LifecycleFacade, SessionsFacade, VmFacade, WindowFacade};
pub use facades::{
FsFacade, LifecycleFacade, SessionError, SessionsFacade, VmFacade, WindowFacade,
};
pub use lifecycle::{
DEFAULT_GAME_PAUSE_BUDGET_TICKS, GameLifecycleEvent, GameLifecycleEventKind, LifecycleError,
LifecycleOperation,
@@ -143,17 +143,33 @@ impl SystemOS {
#[cfg(test)]
mod tests {
use super::*;
use crate::os::{GameLifecycleEventKind, LifecycleError, LifecycleOperation};
use crate::process::{ProcessKind, ProcessState};
use crate::os::{GameLifecycleEventKind, LifecycleError, LifecycleOperation, SessionError};
use crate::process::{ProcessId, ProcessKind, ProcessState};
use crate::services::foreground::{ForegroundOwner, ResidentGame, ResidentGameState};
use crate::task::{TaskId, TaskState};
use prometeu_hal::app_mode::AppMode;
use prometeu_hal::cartridge::{AssetsPayloadSource, Cartridge};
use prometeu_hal::syscalls::caps;
fn process_state_for_task(os: &SystemOS, task_id: TaskId) -> ProcessState {
let task = os.task_manager.get(task_id).expect("task should exist");
os.process_manager.get(task.process_id).expect("process should exist").state
}
fn session_test_cartridge(app_mode: AppMode, app_id: u32, title: &str) -> Cartridge {
Cartridge {
app_id,
title: title.to_string(),
app_version: "1.0.0".to_string(),
app_mode,
capabilities: caps::NONE,
program: vec![],
assets: AssetsPayloadSource::empty(),
asset_table: vec![],
preload: vec![],
}
}
#[test]
fn set_foreground_task_marks_task_and_process_running() {
let mut os = SystemOS::new(None);
@@ -202,6 +218,42 @@ mod tests {
);
}
#[test]
fn terminate_resident_game_closes_task_and_removes_vm_session() {
let mut os = SystemOS::new(None);
let game = os.sessions().create_vm_game_task(42, "Sector Crawl");
os.lifecycle().request_home_from_game(game).expect("home request should succeed");
assert_eq!(os.lifecycle().pending_game_lifecycle_events().len(), 1);
assert_eq!(os.lifecycle().terminate_resident_game(), Ok(Some(game)));
assert_eq!(os.lifecycle().resident_game(), None);
assert_eq!(os.lifecycle().foreground_owner(), ForegroundOwner::Hub);
assert_eq!(os.lifecycle().task_state(game), Some(TaskState::Closed));
assert_eq!(process_state_for_task(&os, game), ProcessState::Stopped);
assert_eq!(os.sessions().vm_session_for_task(game).map(|session| session.task_id), None);
assert!(os.lifecycle().pending_game_lifecycle_events().is_empty());
}
#[test]
fn terminate_resident_game_preserves_foreground_shell() {
let mut os = SystemOS::new(None);
let game = os.sessions().create_vm_game_task(42, "Sector Crawl");
os.lifecycle().request_home_from_game(game).expect("home request should succeed");
os.lifecycle().advance_game_pause_budget(game).expect("budget should expire");
let shell = os.sessions().create_vm_shell_task(7, "Settings");
assert_eq!(os.lifecycle().terminate_resident_game(), Ok(Some(game)));
assert_eq!(os.lifecycle().foreground_owner(), ForegroundOwner::Shell(shell));
assert_eq!(os.lifecycle().resident_game(), None);
assert_eq!(os.lifecycle().task_state(game), Some(TaskState::Closed));
assert_eq!(process_state_for_task(&os, game), ProcessState::Stopped);
assert_eq!(os.sessions().vm_session_for_task(game).map(|session| session.task_id), None);
assert_eq!(os.lifecycle().task_state(shell), Some(TaskState::Foreground));
}
#[test]
fn vm_game_task_creates_vm_session() {
let mut os = SystemOS::new(None);
@@ -295,6 +347,43 @@ mod tests {
assert_eq!(shell_session.open_files.get(&1).map(String::as_str), Some("/shell.dat"));
}
#[test]
fn vm_debug_operations_target_foreground_shell_before_resident_game() {
let mut os = SystemOS::new(None);
let game = os.sessions().create_vm_game_task(42, "Sector Crawl");
os.lifecycle().request_home_from_game(game).expect("home request should succeed");
os.lifecycle().advance_game_pause_budget(game).expect("budget should expire");
let shell = os.sessions().create_vm_shell_task(7, "Settings");
{
let mut sessions = os.sessions();
let game_session =
sessions.vm_session_for_task_mut(game).expect("game VM session should exist");
game_session.vm.insert_breakpoint(10);
}
assert!(os.vm().insert_active_breakpoint(20));
assert_eq!(os.vm().active_breakpoints_list(), vec![20]);
let sessions = os.sessions();
assert_eq!(
sessions
.vm_session_for_task(game)
.expect("game VM session should exist")
.vm
.breakpoints_list(),
vec![10]
);
assert_eq!(
sessions
.vm_session_for_task(shell)
.expect("shell VM session should exist")
.vm
.breakpoints_list(),
vec![20]
);
}
#[test]
fn home_request_notifies_game_before_budget_suspends_it() {
let mut os = SystemOS::new(None);
@@ -416,6 +505,60 @@ mod tests {
);
}
#[test]
fn vm_shell_load_returns_typed_error_when_foreground_shell_exists() {
let mut os = SystemOS::new(None);
let first = os.sessions().create_vm_shell_task(7, "Settings");
let cartridge = session_test_cartridge(AppMode::Shell, 8, "Files");
let error = os.sessions().load_vm_cartridge(&cartridge).expect_err("load should fail");
match error {
SessionError::Lifecycle(LifecycleError::ForegroundShellAlreadyExists {
existing,
requested,
}) => {
assert_eq!(existing, first);
assert_ne!(requested, first);
}
other => panic!("expected foreground shell lifecycle error, got {:?}", other),
}
}
#[test]
fn vm_session_creation_returns_typed_error_for_missing_task() {
let mut os = SystemOS::new(None);
assert_eq!(
os.sessions().try_create_vm_session_for_task(TaskId(999)),
Err(SessionError::TaskNotFound(TaskId(999)))
);
}
#[test]
fn vm_session_creation_returns_typed_error_for_missing_process() {
let mut os = SystemOS::new(None);
let task_id = os.task_manager.create_game_task(ProcessId(999), 42, "Broken");
assert_eq!(
os.sessions().try_create_vm_session_for_task(task_id),
Err(SessionError::ProcessNotFound(ProcessId(999)))
);
}
#[test]
fn session_cartridge_initialization_returns_typed_error_for_missing_session() {
let mut os = SystemOS::new(None);
let process_id = os.process_manager.spawn_vm_game(42, "Sector Crawl");
let task_id = os.task_manager.create_game_task(process_id, 42, "Sector Crawl");
let cartridge = session_test_cartridge(AppMode::Game, 42, "Sector Crawl");
assert_eq!(
os.sessions().try_initialize_session_cartridge(task_id, &cartridge),
Err(SessionError::MissingVmSession(task_id))
);
}
#[test]
fn closing_foreground_shell_returns_to_hub() {
let mut os = SystemOS::new(None);
@@ -1,3 +1,6 @@
mod prometeu_hub;
pub use prometeu_hub::{NativeShellApp, PrometeuHub, SystemProfileAction, SystemProfileUpdate};
pub use prometeu_hub::{
HUB_SUSPENDED_GAME_KILL_CONTROL, NativeShellApp, PrometeuHub, SystemProfileAction,
SystemProfileUpdate,
};
@@ -1,4 +1,7 @@
#[allow(clippy::module_inception)]
mod prometeu_hub;
pub use prometeu_hub::{NativeShellApp, PrometeuHub, SystemProfileAction, SystemProfileUpdate};
pub use prometeu_hub::{
HUB_SUSPENDED_GAME_KILL_CONTROL, NativeShellApp, PrometeuHub, SystemProfileAction,
SystemProfileUpdate,
};
@@ -1,13 +1,12 @@
use crate::task::TaskId;
use crate::{CrashReport, GameLibrary, SystemOS};
use crate::{CrashReport, GameLibrary, GameSwitchTarget, SystemOS};
use prometeu_hal::app_mode::AppMode;
use prometeu_hal::color::Color;
use prometeu_hal::primitives::Rect;
use prometeu_hal::{
FrameId, GfxUiCommand, InputPlatform, InputSignals, RenderSubmission, RuntimePlatform,
ShellUiFramePacket,
};
use prometeu_vm::VirtualMachine;
use std::path::PathBuf;
const SHELL_A_BUTTON: Rect = Rect { x: 112, y: 172, w: 112, h: 32 };
const SHELL_B_BUTTON: Rect = Rect { x: 256, y: 172, w: 112, h: 32 };
@@ -21,6 +20,7 @@ const GAME_ROW_W: i32 = 336;
const GAME_ROW_H: i32 = 22;
const GAME_ROW_GAP: i32 = 6;
const MAX_HOME_GAME_ROWS: usize = 3;
pub const HUB_SUSPENDED_GAME_KILL_CONTROL: Rect = Rect { x: 288, y: 230, w: 168, h: 24 };
#[cfg(test)]
const SHELL_FRAME: Rect = Rect { x: 40, y: 20, w: 400, h: 220 };
@@ -33,6 +33,8 @@ const COLOR_TEXT: Color = Color::rgb(230, 236, 224);
const COLOR_MUTED: Color = Color::rgb(91, 112, 128);
const COLOR_BUTTON: Color = Color::rgb(45, 59, 82);
const COLOR_BUTTON_ACTIVE: Color = Color::rgb(72, 91, 122);
const COLOR_KILL: Color = Color::rgb(164, 32, 40);
const COLOR_KILL_ACTIVE: Color = Color::rgb(206, 46, 54);
/// PrometeuHub: Launcher and system UI environment.
pub struct PrometeuHub {
@@ -84,7 +86,8 @@ impl NativeShellApp {
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum SystemProfileAction {
LaunchNativeShell(NativeShellApp),
LaunchGame { path: PathBuf },
LaunchGame { target: GameSwitchTarget },
KillResidentGame,
CloseShell,
}
@@ -133,12 +136,14 @@ impl PrometeuHub {
}
let input = platform.input();
let suspended_game = if in_shell { None } else { resident_game_indicator(os) };
if let Some(action) = action_for_click(
in_shell,
input.touch().x(),
input.touch().y(),
input.touch().f().pressed,
self.game_library.entries(),
suspended_game.as_ref(),
) {
return Some(action);
}
@@ -151,7 +156,13 @@ impl PrometeuHub {
let pointer_y = platform.input().touch().y();
let packet = if os.windows().window_count() == 0 {
render_home_packet(pointer_x, pointer_y, self.game_library.entries())
let suspended_game = resident_game_indicator(os);
render_home_packet(
pointer_x,
pointer_y,
self.game_library.entries(),
suspended_game.as_ref(),
)
} else {
let mut commands = Vec::new();
for window in os.windows().windows() {
@@ -175,24 +186,17 @@ impl PrometeuHub {
pub fn update_shell_profile(
&mut self,
os: &mut SystemOS,
vm: &mut VirtualMachine,
signals: &InputSignals,
platform: &mut dyn RuntimePlatform,
) -> SystemProfileUpdate {
let mut crash = None;
let mut action = self.gui_update(os, platform);
if os.windows().focused_window().is_some() {
if platform.input().pad().start().down {
action = Some(SystemProfileAction::CloseShell);
} else if action != Some(SystemProfileAction::CloseShell) {
crash = os.vm().tick(vm, signals, platform);
}
if os.windows().focused_window().is_some() && platform.input().pad().start().down {
action = Some(SystemProfileAction::CloseShell);
}
self.render(os, platform);
SystemProfileUpdate { crash, action }
SystemProfileUpdate { crash: None, action }
}
pub fn update_vm_shell_profile(
@@ -241,6 +245,7 @@ fn action_for_click(
y: i32,
pressed: bool,
game_entries: &[crate::GameLibraryEntry],
suspended_game: Option<&SuspendedGameIndicator>,
) -> Option<SystemProfileAction> {
if !pressed {
return None;
@@ -250,6 +255,10 @@ fn action_for_click(
return rect_contains(CLOSE_BUTTON, x, y).then_some(SystemProfileAction::CloseShell);
}
if suspended_game.is_some() && rect_contains(HUB_SUSPENDED_GAME_KILL_CONTROL, x, y) {
return Some(SystemProfileAction::KillResidentGame);
}
if let Some(entry) = game_entries
.iter()
.take(MAX_HOME_GAME_ROWS)
@@ -257,7 +266,7 @@ fn action_for_click(
.find(|(index, _entry)| rect_contains(game_row_rect(*index), x, y))
.map(|(_index, entry)| entry)
{
return Some(SystemProfileAction::LaunchGame { path: entry.path.clone() });
return Some(SystemProfileAction::LaunchGame { target: entry.switch_target() });
}
HOME_BUTTONS
@@ -266,6 +275,23 @@ fn action_for_click(
.map(|button| SystemProfileAction::LaunchNativeShell(button.app))
}
#[derive(Debug, Clone, PartialEq, Eq)]
struct SuspendedGameIndicator {
title: String,
}
fn resident_game_indicator(os: &mut SystemOS) -> Option<SuspendedGameIndicator> {
let task_id = os.lifecycle().resident_game_task()?;
let sessions = os.sessions();
let session = sessions.vm_session_for_task(task_id)?;
if session.app_mode != AppMode::Game {
return None;
}
Some(SuspendedGameIndicator { title: session.title.clone() })
}
fn game_row_rect(index: usize) -> Rect {
Rect {
x: GAME_ROW_X,
@@ -290,6 +316,7 @@ fn render_home_packet(
pointer_x: i32,
pointer_y: i32,
game_entries: &[crate::GameLibraryEntry],
suspended_game: Option<&SuspendedGameIndicator>,
) -> ShellUiFramePacket {
let mut commands = Vec::new();
commands.push(GfxUiCommand::Clear { color: COLOR_BG });
@@ -329,6 +356,11 @@ fn render_home_packet(
draw_button(&mut commands, button.rect, button.label, hovered);
}
if let Some(suspended_game) = suspended_game {
let hovered = rect_contains(HUB_SUSPENDED_GAME_KILL_CONTROL, pointer_x, pointer_y);
draw_suspended_game_kill_control(&mut commands, suspended_game, hovered);
}
ShellUiFramePacket::new(commands)
}
@@ -431,6 +463,39 @@ fn draw_game_row(commands: &mut Vec<GfxUiCommand>, rect: Rect, label: &str, hove
draw_buffer_text(commands, rect.x + 8, rect.y + 7, label, COLOR_TEXT);
}
fn draw_suspended_game_kill_control(
commands: &mut Vec<GfxUiCommand>,
suspended_game: &SuspendedGameIndicator,
hovered: bool,
) {
let fill = if hovered { COLOR_KILL_ACTIVE } else { COLOR_KILL };
let border = if hovered { COLOR_HILITE } else { COLOR_BORDER };
fill_rect(commands, HUB_SUSPENDED_GAME_KILL_CONTROL, fill);
draw_rect(commands, HUB_SUSPENDED_GAME_KILL_CONTROL, border);
draw_buffer_text(
commands,
HUB_SUSPENDED_GAME_KILL_CONTROL.x + 8,
HUB_SUSPENDED_GAME_KILL_CONTROL.y + 8,
&fit_text_to_control(&suspended_game.title, HUB_SUSPENDED_GAME_KILL_CONTROL.w - 16),
COLOR_TEXT,
);
}
fn fit_text_to_control(text: &str, max_width: i32) -> String {
let max_chars = (max_width / 8).max(0) as usize;
if text.chars().count() <= max_chars {
return text.to_string();
}
if max_chars <= 2 {
return text.chars().take(max_chars).collect();
}
let mut fitted: String = text.chars().take(max_chars - 2).collect();
fitted.push_str("..");
fitted
}
fn draw_buffer_text(commands: &mut Vec<GfxUiCommand>, x: i32, y: i32, text: &str, color: Color) {
commands.push(GfxUiCommand::DrawText { x, y, text: text.to_string(), color });
}
@@ -442,6 +507,7 @@ mod tests {
use crate::windows::WindowOwner;
use prometeu_drivers::TestPlatform;
use prometeu_hal::{InputSignals, RuntimePlatform};
use std::path::PathBuf;
fn focused_native_shell_fixture(
signals: &InputSignals,
@@ -470,7 +536,14 @@ mod tests {
#[test]
fn shell_a_button_click_emits_launch_action() {
assert_eq!(
action_for_click(false, HOME_BUTTONS[0].rect.x, HOME_BUTTONS[0].rect.y, true, &[]),
action_for_click(
false,
HOME_BUTTONS[0].rect.x,
HOME_BUTTONS[0].rect.y,
true,
&[],
None
),
Some(SystemProfileAction::LaunchNativeShell(NativeShellApp::ShellA))
);
}
@@ -483,7 +556,8 @@ mod tests {
SHELL_B_BUTTON.x + SHELL_B_BUTTON.w - 1,
SHELL_B_BUTTON.y,
true,
&[]
&[],
None
),
Some(SystemProfileAction::LaunchNativeShell(NativeShellApp::ShellB))
);
@@ -497,7 +571,8 @@ mod tests {
SHELL_A_BUTTON.x + SHELL_A_BUTTON.w,
SHELL_A_BUTTON.y,
true,
&[]
&[],
None
),
None
);
@@ -507,7 +582,8 @@ mod tests {
SHELL_A_BUTTON.x,
SHELL_A_BUTTON.y + SHELL_A_BUTTON.h,
true,
&[]
&[],
None
),
None
);
@@ -515,7 +591,10 @@ mod tests {
#[test]
fn held_pointer_does_not_emit_click_action() {
assert_eq!(action_for_click(false, SHELL_A_BUTTON.x, SHELL_A_BUTTON.y, false, &[]), None);
assert_eq!(
action_for_click(false, SHELL_A_BUTTON.x, SHELL_A_BUTTON.y, false, &[], None),
None
);
}
#[test]
@@ -543,19 +622,35 @@ mod tests {
discovered_at: std::time::SystemTime::UNIX_EPOCH,
};
let action = action_for_click(
false,
GAME_ROW_X,
GAME_ROW_Y,
true,
std::slice::from_ref(&entry),
None,
);
assert_eq!(
action_for_click(false, GAME_ROW_X, GAME_ROW_Y, true, std::slice::from_ref(&entry)),
Some(SystemProfileAction::LaunchGame { path: entry.path.clone() })
action,
Some(SystemProfileAction::LaunchGame {
target: GameSwitchTarget {
path: entry.path.clone(),
app_id: 42,
title: "Stress".to_string(),
app_version: "1.0.0".to_string(),
}
})
);
}
#[test]
fn close_button_click_emits_close_only_in_shell() {
assert_eq!(
action_for_click(true, CLOSE_BUTTON.x, CLOSE_BUTTON.y, true, &[]),
action_for_click(true, CLOSE_BUTTON.x, CLOSE_BUTTON.y, true, &[], None),
Some(SystemProfileAction::CloseShell)
);
assert_eq!(action_for_click(false, CLOSE_BUTTON.x, CLOSE_BUTTON.y, true, &[]), None);
assert_eq!(action_for_click(false, CLOSE_BUTTON.x, CLOSE_BUTTON.y, true, &[], None), None);
}
#[test]
@@ -569,7 +664,7 @@ mod tests {
#[test]
fn home_render_produces_shell_ui_packet_commands() {
let packet = render_home_packet(SHELL_A_BUTTON.x, SHELL_A_BUTTON.y, &[]);
let packet = render_home_packet(SHELL_A_BUTTON.x, SHELL_A_BUTTON.y, &[], None);
assert!(matches!(packet.commands.first(), Some(GfxUiCommand::Clear { .. })));
assert!(packet.commands.iter().any(|command| {
@@ -577,6 +672,123 @@ mod tests {
}));
}
#[test]
fn resident_game_indicator_uses_only_resident_game_sessions() {
let mut os = SystemOS::new(None);
assert_eq!(resident_game_indicator(&mut os), None);
let shell = os.sessions().create_vm_shell_task(7, "VM Shell");
assert_eq!(resident_game_indicator(&mut os), None);
os.lifecycle().suspend_task(shell).expect("shell suspend should succeed");
assert_eq!(resident_game_indicator(&mut os), None);
let game = os.sessions().create_vm_game_task(42, "Stress Console");
os.lifecycle().suspend_task(game).expect("game suspend should succeed");
assert_eq!(
resident_game_indicator(&mut os),
Some(SuspendedGameIndicator { title: "Stress Console".to_string() })
);
}
#[test]
fn home_render_shows_suspended_game_kill_control_when_game_is_resident() {
let suspended_game = SuspendedGameIndicator { title: "Stress Console".to_string() };
let packet = render_home_packet(
HUB_SUSPENDED_GAME_KILL_CONTROL.x,
HUB_SUSPENDED_GAME_KILL_CONTROL.y,
&[],
Some(&suspended_game),
);
assert!(packet.commands.iter().any(|command| {
matches!(
command,
GfxUiCommand::FillRect { rect, color }
if *rect == HUB_SUSPENDED_GAME_KILL_CONTROL && *color == COLOR_KILL_ACTIVE
)
}));
assert!(packet.commands.iter().any(|command| {
matches!(
command,
GfxUiCommand::DrawText { x, y, text, .. }
if *x == HUB_SUSPENDED_GAME_KILL_CONTROL.x + 8
&& *y == HUB_SUSPENDED_GAME_KILL_CONTROL.y + 8
&& text == "Stress Console"
)
}));
}
#[test]
fn home_render_omits_suspended_game_kill_control_without_resident_game() {
let packet = render_home_packet(
HUB_SUSPENDED_GAME_KILL_CONTROL.x,
HUB_SUSPENDED_GAME_KILL_CONTROL.y,
&[],
None,
);
assert!(!packet.commands.iter().any(|command| {
matches!(
command,
GfxUiCommand::FillRect { rect, color }
if *rect == HUB_SUSPENDED_GAME_KILL_CONTROL
&& (*color == COLOR_KILL || *color == COLOR_KILL_ACTIVE)
)
}));
}
#[test]
fn suspended_game_kill_control_click_emits_kill_action() {
let suspended_game = SuspendedGameIndicator { title: "Stress Console".to_string() };
assert_eq!(
action_for_click(
false,
HUB_SUSPENDED_GAME_KILL_CONTROL.x,
HUB_SUSPENDED_GAME_KILL_CONTROL.y,
true,
&[],
Some(&suspended_game),
),
Some(SystemProfileAction::KillResidentGame)
);
assert_eq!(
action_for_click(
false,
HUB_SUSPENDED_GAME_KILL_CONTROL.x,
HUB_SUSPENDED_GAME_KILL_CONTROL.y,
true,
&[],
None,
),
None
);
}
#[test]
fn suspended_game_kill_control_truncates_long_titles() {
let long_title =
SuspendedGameIndicator { title: "Extremely Long Resident Game Title".to_string() };
let packet = render_home_packet(0, 0, &[], Some(&long_title));
let label = packet
.commands
.iter()
.find_map(|command| match command {
GfxUiCommand::DrawText { x, y, text, .. }
if *x == HUB_SUSPENDED_GAME_KILL_CONTROL.x + 8
&& *y == HUB_SUSPENDED_GAME_KILL_CONTROL.y + 8 =>
{
Some(text)
}
_ => None,
})
.expect("kill control text should render");
assert!(label.ends_with(".."));
assert!(label.chars().count() <= ((HUB_SUSPENDED_GAME_KILL_CONTROL.w - 16) / 8) as usize);
}
#[test]
fn shell_close_button_sits_inside_shell_frame() {
assert!(rect_contains(SHELL_FRAME, CLOSE_BUTTON.x, CLOSE_BUTTON.y));
@@ -25,6 +25,29 @@ impl GameLibraryEntry {
discovered_at,
}
}
pub fn switch_target(&self) -> GameSwitchTarget {
GameSwitchTarget::from_entry(self)
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct GameSwitchTarget {
pub path: PathBuf,
pub app_id: u32,
pub title: String,
pub app_version: String,
}
impl GameSwitchTarget {
pub fn from_entry(entry: &GameLibraryEntry) -> Self {
Self {
path: entry.path.clone(),
app_id: entry.app_id,
title: entry.title.clone(),
app_version: entry.app_version.clone(),
}
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
@@ -256,6 +279,31 @@ mod tests {
}));
}
#[test]
fn switch_target_preserves_resolved_identity() {
let path = PathBuf::from("test-cartridges/stress-console");
let entry = GameLibraryEntry::new(
path.clone(),
CartridgeManifest {
magic: "PMTU".to_string(),
cartridge_version: 1,
app_id: 42,
title: "Stress".to_string(),
app_version: "1.0.0".to_string(),
app_mode: AppMode::Game,
capabilities: vec![],
},
UNIX_EPOCH,
);
let target = entry.switch_target();
assert_eq!(target.path, path);
assert_eq!(target.app_id, 42);
assert_eq!(target.title, "Stress");
assert_eq!(target.app_version, "1.0.0");
}
#[test]
fn missing_root_returns_diagnostic_and_no_entries() {
let root = TestRoot::new();
@@ -267,4 +315,22 @@ mod tests {
assert_eq!(library.diagnostics().len(), 1);
assert_eq!(library.diagnostics()[0].reason, GameLibraryDiagnosticReason::RootNotDirectory);
}
#[test]
fn repository_test_cartridges_include_stress_and_dummy_boy() {
let games_root =
PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../../..").join("test-cartridges");
let library = discover_games_root(games_root);
let entries = library.entries();
assert!(entries.iter().any(|entry| {
entry.app_id == 1
&& entry.title == "Stress Console"
&& entry.path.ends_with("stress-console")
}));
assert!(entries.iter().any(|entry| {
entry.app_id == 2 && entry.title == "Dummy Boy" && entry.path.ends_with("dummy-boy")
}));
}
}
@@ -15,7 +15,7 @@ use prometeu_hal::asset::{
use prometeu_hal::cartridge::{AssetsPayloadSource, Cartridge};
use prometeu_hal::color::Color;
use prometeu_hal::glyph::Glyph;
use prometeu_hal::glyph_bank::{GLYPH_BANK_PALETTE_COUNT_V1, GlyphBank, TileSize};
use prometeu_hal::glyph_bank::{GLYPH_BANK_MAX_PALETTE_COUNT_V1, GlyphBank, TileSize};
use prometeu_hal::scene_bank::SceneBank;
use prometeu_hal::scene_layer::{ParallaxFactor, SceneLayer};
use prometeu_hal::syscalls::caps;
@@ -113,11 +113,12 @@ fn serialized_single_function_module_with_consts(
}
fn test_glyph_payload_size(width: usize, height: usize) -> usize {
(width * height).div_ceil(2) + (GLYPH_BANK_PALETTE_COUNT_V1 * 16 * std::mem::size_of::<u32>())
(width * height).div_ceil(2)
+ (GLYPH_BANK_MAX_PALETTE_COUNT_V1 * 16 * std::mem::size_of::<u32>())
}
fn test_glyph_decoded_size(width: usize, height: usize) -> usize {
width * height + (GLYPH_BANK_PALETTE_COUNT_V1 * 16 * std::mem::size_of::<u32>())
width * height + (GLYPH_BANK_MAX_PALETTE_COUNT_V1 * 16 * std::mem::size_of::<u32>())
}
fn test_glyph_asset_entry(asset_name: &str, data_len: usize) -> AssetEntry {
@@ -133,23 +134,23 @@ fn test_glyph_asset_entry(asset_name: &str, data_len: usize) -> AssetEntry {
"tile_size": 16,
"width": 16,
"height": 16,
"palette_count": GLYPH_BANK_PALETTE_COUNT_V1,
"palette_authored": GLYPH_BANK_PALETTE_COUNT_V1
"palette_count": GLYPH_BANK_MAX_PALETTE_COUNT_V1,
"palette_authored": GLYPH_BANK_MAX_PALETTE_COUNT_V1
}),
}
}
fn test_glyph_asset_data() -> Vec<u8> {
let mut data =
vec![0x11u8; test_glyph_payload_size(16, 16) - (GLYPH_BANK_PALETTE_COUNT_V1 * 16 * 4)];
data.extend_from_slice(&[0u8; GLYPH_BANK_PALETTE_COUNT_V1 * 16 * 4]);
vec![0x11u8; test_glyph_payload_size(16, 16) - (GLYPH_BANK_MAX_PALETTE_COUNT_V1 * 16 * 4)];
data.extend_from_slice(&[0u8; GLYPH_BANK_MAX_PALETTE_COUNT_V1 * 16 * 4]);
data
}
fn runtime_test_glyph_bank(tile_size: TileSize, palette_id: u8, color: Color) -> GlyphBank {
let size = tile_size as usize;
let mut bank = GlyphBank::new(tile_size, size, size);
bank.palettes[palette_id as usize][1] = color;
let mut bank = GlyphBank::with_palette_count(tile_size, size, size, palette_id as usize + 1);
bank.palette_mut(palette_id).unwrap()[1] = color;
for pixel in &mut bank.pixel_indices {
*pixel = 1;
}
@@ -1275,6 +1276,53 @@ fn tick_composer_emit_sprite_operational_error_returns_status_not_crash() {
assert_eq!(vm.operand_stack_top(1), vec![Value::Int64(ComposerOpStatus::BankInvalid as i64)]);
}
#[test]
fn tick_composer_emit_sprite_invalid_palette_returns_bank_invalid() {
let mut runtime = VirtualMachineRuntime::new(None);
let mut log_service = LogService::new(4096);
let mut fs = VirtualFS::new();
let mut fs_state = FsState::Unmounted;
let mut memcard = MemcardService::new();
let mut open_files: HashMap<u32, String> = HashMap::new();
let mut next_handle = 1;
let mut vm = VirtualMachine::default();
let banks = Arc::new(MemoryBanks::new());
banks.install_glyph_bank(0, Arc::new(runtime_test_glyph_bank(TileSize::Size8, 0, Color::BLUE)));
let mut platform = TestPlatform::new_with_memory_banks(banks);
let signals = InputSignals::default();
let code = assemble(
"PUSH_I32 0\nPUSH_I32 1\nPUSH_I32 0\nPUSH_I32 0\nPUSH_I32 0\nPUSH_I32 0\nPUSH_BOOL 0\nPUSH_BOOL 0\nPUSH_I32 0\nHOSTCALL 0\nHALT",
)
.expect("assemble");
let program = serialized_single_function_module(
code,
vec![SyscallDecl {
module: "composer".into(),
name: "emit_sprite".into(),
version: 1,
arg_slots: 9,
ret_slots: 1,
}],
);
let cartridge = cartridge_with_program(program, caps::GFX);
runtime.initialize_vm(&mut log_service, &mut vm, &cartridge).expect("runtime must initialize");
let report = runtime.tick(
&mut log_service,
&mut fs,
&mut fs_state,
&mut memcard,
&mut open_files,
&mut next_handle,
&mut vm,
&signals,
&mut platform,
);
assert!(report.is_none(), "invalid palette must not crash VM execution");
assert!(vm.is_halted());
assert_eq!(vm.operand_stack_top(1), vec![Value::Int64(ComposerOpStatus::BankInvalid as i64)]);
}
#[test]
fn tick_composer_emit_sprite_invalid_layer_returns_status_not_crash() {
let mut runtime = VirtualMachineRuntime::new(None);
@@ -121,6 +121,10 @@ impl VmSessionRegistry {
self.get_mut(VmSessionId(task_id))
}
pub fn remove_for_task(&mut self, task_id: TaskId) -> Option<VmSession> {
self.sessions.remove(&VmSessionId(task_id))
}
pub fn resident_game(&self) -> Option<&VmSession> {
self.sessions.values().find(|session| session.app_mode == AppMode::Game)
}
@@ -138,6 +142,10 @@ impl VmSessionRegistry {
pub fn is_empty(&self) -> bool {
self.sessions.is_empty()
}
pub fn clear(&mut self) {
self.sessions.clear();
}
}
fn app_mode_for_task_and_process(
@@ -227,6 +235,31 @@ mod tests {
assert_eq!(registry.resident_game_for_app(43).map(|session| session.task_id), None);
}
#[test]
fn remove_for_task_removes_only_matching_session() {
let game_process = Process::new(ProcessId(1), 42, "Stress", ProcessKind::VmGame);
let game_task = Task::new(TaskId(7), game_process.id, 42, "Stress", TaskKind::Game);
let shell_process = Process::new(ProcessId(2), 9, "Shell", ProcessKind::VmShell);
let shell_task = Task::new(TaskId(8), shell_process.id, 9, "Shell", TaskKind::Shell);
let mut registry = VmSessionRegistry::new();
registry
.create_for_task(&game_task, &game_process, "", None, Arc::new(AtomicU32::new(0)))
.expect("game session should create");
registry
.create_for_task(&shell_task, &shell_process, "", None, Arc::new(AtomicU32::new(0)))
.expect("shell session should create");
let removed = registry.remove_for_task(game_task.id).expect("game session should remove");
assert_eq!(removed.task_id, game_task.id);
assert_eq!(registry.for_task(game_task.id).map(|session| session.task_id), None);
assert_eq!(
registry.for_task(shell_task.id).map(|session| session.task_id),
Some(shell_task.id)
);
}
#[test]
fn session_runtime_state_is_independent_per_session() {
let game_process = Process::new(ProcessId(1), 42, "Stress", ProcessKind::VmGame);
@@ -2627,7 +2627,7 @@ mod tests {
fn test_loader_hardening_unsupported_version() {
let mut vm = VirtualMachine::default();
let mut header = vec![0u8; 32];
header[0..4].copy_from_slice(b"PBS\0");
header[0..4].copy_from_slice(&prometeu_bytecode::PBX_MAGIC);
header[4..6].copy_from_slice(&1u16.to_le_bytes()); // version 1 (unsupported)
let res = vm.initialize(header);
@@ -2635,16 +2635,16 @@ mod tests {
}
#[test]
fn test_loader_hardening_malformed_pbs_v0() {
fn test_loader_hardening_malformed_pbx_v0() {
let mut vm = VirtualMachine::default();
let mut header = vec![0u8; 32];
header[0..4].copy_from_slice(b"PBS\0");
header[0..4].copy_from_slice(&prometeu_bytecode::PBX_MAGIC);
header[8..12].copy_from_slice(&1u32.to_le_bytes()); // 1 section claimed but none provided
let res = vm.initialize(header);
match res {
Err(VmInitError::ImageLoadFailed(prometeu_bytecode::LoadError::UnexpectedEof)) => {}
_ => panic!("Expected PbsV0LoadFailed(UnexpectedEof), got {:?}", res),
_ => panic!("Expected PBX v0 load failure UnexpectedEof, got {:?}", res),
}
}
@@ -2695,6 +2695,13 @@ mod tests {
assert_eq!(vm.pc, 0);
assert_eq!(vm.program.rom.len(), 2);
assert_eq!(vm.cycles, 0);
vm.prepare_boot_call();
let mut native = MockNative;
let mut ctx = HostContext::new(None);
let report = vm.run_budget(100, &mut native, &mut ctx).expect("run loaded PBX");
assert_eq!(report.reason, LogicalFrameEndingReason::Halted);
assert!(vm.is_halted());
}
#[test]
@@ -3084,7 +3091,7 @@ mod tests {
fn test_loader_hardening_missing_sysc_section() {
let mut vm = VirtualMachine::default();
let mut header = vec![0u8; 32];
header[0..4].copy_from_slice(b"PBS\0");
header[0..4].copy_from_slice(&prometeu_bytecode::PBX_MAGIC);
let res = vm.initialize(header);
@@ -83,30 +83,32 @@ impl VirtualMachine {
self.scheduler = Scheduler::new();
self.current_coro = None;
let program = if program_bytes.starts_with(b"PBS\0") {
match prometeu_bytecode::BytecodeLoader::load(&program_bytes) {
Ok(mut module) => {
patch_module_hostcalls(&mut module, self.capabilities)
.map_err(VmInitError::LoaderPatchFailed)?;
let program = match prometeu_bytecode::BytecodeLoader::load(&program_bytes) {
Ok(mut module) => {
patch_module_hostcalls(&mut module, self.capabilities)
.map_err(VmInitError::LoaderPatchFailed)?;
let max_stacks = Verifier::verify(&module.code, &module.functions)
.map_err(|e| VmInitError::VerificationFailed(format!("{:?}", e)))?;
let max_stacks = Verifier::verify(&module.code, &module.functions)
.map_err(|e| VmInitError::VerificationFailed(format!("{:?}", e)))?;
let mut program = ProgramImage::from(module);
let mut functions = program.functions.as_ref().to_vec();
for (func, max_stack) in functions.iter_mut().zip(max_stacks) {
func.max_stack_slots = max_stack;
}
program.functions = std::sync::Arc::from(functions);
program
let mut program = ProgramImage::from(module);
let mut functions = program.functions.as_ref().to_vec();
for (func, max_stack) in functions.iter_mut().zip(max_stacks) {
func.max_stack_slots = max_stack;
}
Err(prometeu_bytecode::LoadError::InvalidVersion) => {
return Err(VmInitError::UnsupportedFormat);
}
Err(e) => return Err(VmInitError::ImageLoadFailed(e)),
program.functions = std::sync::Arc::from(functions);
program
}
} else {
return Err(VmInitError::InvalidFormat);
Err(prometeu_bytecode::LoadError::InvalidVersion) => {
return Err(VmInitError::UnsupportedFormat);
}
Err(prometeu_bytecode::LoadError::InvalidMagic) => {
return Err(VmInitError::InvalidFormat);
}
Err(prometeu_bytecode::LoadError::UnexpectedEof) if program_bytes.len() < 32 => {
return Err(VmInitError::InvalidFormat);
}
Err(e) => return Err(VmInitError::ImageLoadFailed(e)),
};
let pc = program
@@ -2,8 +2,8 @@ use prometeu_vm::{VirtualMachine, VmInitError};
#[test]
fn invalid_image_format_is_rejected_before_execution() {
// Provide bytes that are not a valid PBS image. The VM must reject it with InvalidFormat.
let program_bytes = b"NOT_PBS_IMAGE".to_vec();
// Provide bytes that are not a valid PBX image. The VM must reject it with InvalidFormat.
let program_bytes = b"NOT_PBX_IMAGE".to_vec();
let mut vm = VirtualMachine::default();
let result = vm.initialize(program_bytes);
assert!(matches!(result, Err(VmInitError::InvalidFormat)));
@@ -0,0 +1,74 @@
use std::fs;
use std::path::{Path, PathBuf};
const TARGET_MANIFESTS: &[&str] =
&["crates/console/prometeu-bytecode/Cargo.toml", "crates/console/prometeu-vm/Cargo.toml"];
const FORBIDDEN_DEPENDENCY_FRAGMENTS: &[&str] = &["compiler", "frontend"];
#[test]
fn pbx_and_pvm_crates_must_not_depend_on_compiler_or_frontend_crates() {
let workspace_root = find_workspace_root().expect("runtime workspace root");
let mut violations = Vec::new();
for relative_path in TARGET_MANIFESTS {
let manifest_path = workspace_root.join(relative_path);
let manifest = fs::read_to_string(&manifest_path)
.unwrap_or_else(|error| panic!("failed to read {}: {error}", manifest_path.display()));
for dependency in dependency_names(&manifest) {
let normalized = dependency.to_ascii_lowercase();
if FORBIDDEN_DEPENDENCY_FRAGMENTS.iter().any(|fragment| normalized.contains(fragment)) {
violations.push(format!("{relative_path}: forbidden dependency `{dependency}`"));
}
}
}
assert!(
violations.is_empty(),
"PBX/PVM crates must remain independent of compiler and frontend crates:\n{}",
violations.join("\n")
);
}
fn dependency_names(manifest: &str) -> Vec<&str> {
let mut names = Vec::new();
let mut in_dependency_section = false;
for raw_line in manifest.lines() {
let line = raw_line.trim();
if line.starts_with('[') && line.ends_with(']') {
let section = &line[1..line.len() - 1];
in_dependency_section = section == "dependencies"
|| section == "dev-dependencies"
|| section == "build-dependencies"
|| section.ends_with(".dependencies")
|| section.ends_with(".dev-dependencies")
|| section.ends_with(".build-dependencies");
continue;
}
if !in_dependency_section || line.is_empty() || line.starts_with('#') {
continue;
}
if let Some((name, _)) = line.split_once('=') {
names.push(name.trim().trim_matches('"'));
}
}
names
}
fn find_workspace_root() -> Option<PathBuf> {
let mut cursor = Path::new(env!("CARGO_MANIFEST_DIR")).to_path_buf();
loop {
let manifest = cursor.join("Cargo.toml");
if fs::read_to_string(&manifest).is_ok_and(|contents| contents.contains("[workspace]")) {
return Some(cursor);
}
if !cursor.pop() {
return None;
}
}
}
@@ -28,6 +28,8 @@ pub struct HostDebugger {
last_telemetry_frame: u64,
/// Last fault summary sent to the debugger client.
last_fault_summary: Option<String>,
/// Debug cartridge metadata captured before the VM session exists.
debug_cartridge: Option<HandshakeCartridge>,
}
impl Default for HostDebugger {
@@ -46,19 +48,25 @@ impl HostDebugger {
last_log_seq: 0,
last_telemetry_frame: 0,
last_fault_summary: None,
debug_cartridge: None,
}
}
/// Configures the debugger based on the boot target.
/// If debug mode is enabled, it binds to the specified TCP port.
pub fn setup_boot_target(&mut self, boot_target: &BootTarget, firmware: &mut Firmware) {
pub fn setup_boot_target(&mut self, boot_target: &BootTarget, _firmware: &mut Firmware) {
if let BootTarget::Cartridge { path, debug: true, debug_port } = boot_target {
self.waiting_for_start = true;
// Pre-load cartridge metadata so the Handshake message can contain
// valid information about the App being debugged.
// valid information before the VM session is created.
if let Ok(cartridge) = CartridgeLoader::load(path) {
let _ = firmware.os.vm().initialize(&mut firmware.vm, &cartridge);
self.debug_cartridge = Some(HandshakeCartridge {
app_id: cartridge.app_id,
title: cartridge.title,
app_version: cartridge.app_version,
app_mode: cartridge.app_mode,
});
}
match TcpListener::bind(format!("127.0.0.1:{}", debug_port)) {
@@ -116,12 +124,7 @@ impl HostDebugger {
let handshake = DebugResponse::Handshake {
protocol_version: DEVTOOLS_PROTOCOL_VERSION,
runtime_version: "0.1".to_string(),
cartridge: HandshakeCartridge {
app_id: firmware.os.vm().current_app_id(),
title: firmware.os.vm().current_cartridge_title(),
app_version: firmware.os.vm().current_cartridge_app_version(),
app_mode: firmware.os.vm().current_cartridge_app_mode(),
},
cartridge: self.handshake_cartridge(firmware),
};
self.send_response(handshake);
} else {
@@ -201,7 +204,7 @@ impl HostDebugger {
DebugCommand::Step => {
// Execute exactly one instruction and keep paused.
firmware.os.vm().set_paused(true);
let _ = firmware.os.vm().debug_step_instruction(&mut firmware.vm, platform);
let _ = firmware.os.vm().debug_step_active_session(platform);
}
DebugCommand::StepFrame => {
// Execute until the end of the current logical frame.
@@ -210,10 +213,10 @@ impl HostDebugger {
}
DebugCommand::GetState => {
// Return detailed VM register and stack state.
let stack_top = firmware.vm.operand_stack_top(10);
let stack_top = firmware.os.vm().active_operand_stack_top(10);
let resp = DebugResponse::GetState {
pc: firmware.vm.pc(),
pc: firmware.os.vm().active_pc().unwrap_or(0),
stack_top,
frame_index: firmware.os.vm().logical_frame_index(),
app_id: firmware.os.vm().current_app_id(),
@@ -221,18 +224,37 @@ impl HostDebugger {
self.send_response(resp);
}
DebugCommand::SetBreakpoint { pc } => {
firmware.vm.insert_breakpoint(pc);
let _ = firmware.os.vm().insert_active_breakpoint(pc);
}
DebugCommand::ListBreakpoints => {
let pcs = firmware.vm.breakpoints_list();
let pcs = firmware.os.vm().active_breakpoints_list();
self.send_response(DebugResponse::Breakpoints { pcs });
}
DebugCommand::ClearBreakpoint { pc } => {
firmware.vm.remove_breakpoint(pc);
let _ = firmware.os.vm().remove_active_breakpoint(pc);
}
}
}
fn handshake_cartridge(&self, firmware: &mut Firmware) -> HandshakeCartridge {
let app_id = firmware.os.vm().current_app_id();
if app_id != 0 {
return HandshakeCartridge {
app_id,
title: firmware.os.vm().current_cartridge_title(),
app_version: firmware.os.vm().current_cartridge_app_version(),
app_mode: firmware.os.vm().current_cartridge_app_mode(),
};
}
self.debug_cartridge.clone().unwrap_or_else(|| HandshakeCartridge {
app_id,
title: firmware.os.vm().current_cartridge_title(),
app_version: firmware.os.vm().current_cartridge_app_version(),
app_mode: firmware.os.vm().current_cartridge_app_mode(),
})
}
pub(crate) fn cert_event_from_snapshot(
tag: u16,
telemetry: TelemetryFrame,
@@ -315,7 +337,7 @@ impl HostDebugger {
// Map specific internal log tags to protocol events.
if event.tag == 0xDEB1 {
self.send_event(DebugEvent::BreakpointHit {
pc: firmware.vm.pc(),
pc: firmware.os.vm().active_pc().unwrap_or(0),
frame_index: firmware.os.vm().logical_frame_index(),
});
}
@@ -409,6 +431,52 @@ mod tests {
assert!(firmware.os.vm().debug_step_requested());
}
#[test]
fn breakpoint_commands_mutate_active_vm_session() {
let mut debugger = HostDebugger::new();
let mut firmware = Firmware::new(None);
let mut platform = TestPlatform::new();
let task_id = firmware
.os
.sessions()
.try_create_vm_game_task(42, "Sector Crawl")
.expect("debugger test should create a game session");
debugger.handle_command(
DebugCommand::SetBreakpoint { pc: 123 },
&mut firmware,
&mut platform,
);
assert_eq!(
firmware
.os
.sessions()
.vm_session_for_task(task_id)
.expect("game VM session should exist")
.vm
.breakpoints_list(),
vec![123]
);
debugger.handle_command(
DebugCommand::ClearBreakpoint { pc: 123 },
&mut firmware,
&mut platform,
);
assert!(
firmware
.os
.sessions()
.vm_session_for_task(task_id)
.expect("game VM session should exist")
.vm
.breakpoints_list()
.is_empty()
);
}
#[test]
fn handle_command_start_leaves_waiting_for_start_mode() {
let mut debugger = HostDebugger::new();
@@ -26,16 +26,22 @@ const IDLE_HOST_POLL_DT: Duration = Duration::from_millis(100);
#[derive(Debug, Clone)]
struct PresentationState {
latest_published_frame: u64,
last_presented_frame: Option<u64>,
latest_published_frame: Option<PresentationFrameMarker>,
last_presented_frame: Option<PresentationFrameMarker>,
host_invalidated: bool,
redraw_requested: bool,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
struct PresentationFrameMarker {
ownership: RenderOwnership,
frame_id: u64,
}
impl Default for PresentationState {
fn default() -> Self {
Self {
latest_published_frame: 0,
latest_published_frame: None,
last_presented_frame: None,
host_invalidated: true,
redraw_requested: false,
@@ -44,9 +50,10 @@ impl Default for PresentationState {
}
impl PresentationState {
fn note_published_frame(&mut self, frame_index: u64) {
if frame_index > self.latest_published_frame {
self.latest_published_frame = frame_index;
fn note_published_frame(&mut self, ownership: RenderOwnership, frame_id: u64) {
let marker = PresentationFrameMarker { ownership, frame_id };
if self.latest_published_frame != Some(marker) {
self.latest_published_frame = Some(marker);
}
}
@@ -55,7 +62,7 @@ impl PresentationState {
}
fn needs_redraw(&self) -> bool {
self.host_invalidated || self.last_presented_frame != Some(self.latest_published_frame)
self.host_invalidated || self.last_presented_frame != self.latest_published_frame
}
fn should_request_redraw(&mut self) -> bool {
@@ -70,7 +77,7 @@ impl PresentationState {
fn mark_presented(&mut self) {
self.redraw_requested = false;
self.host_invalidated = false;
self.last_presented_frame = Some(self.latest_published_frame);
self.last_presented_frame = self.latest_published_frame;
}
}
@@ -437,9 +444,11 @@ impl ApplicationHandler for HostRunner {
if let Some(worker_frame) = self.render_frame_store.latest_frame()
&& should_present_worker_frame(&self.firmware.state, &worker_frame, active_ownership)
{
self.presentation.note_published_frame(worker_frame.frame_id.get());
self.presentation
.note_published_frame(worker_frame.ownership, worker_frame.frame_id.get());
} else {
self.presentation.note_published_frame(self.firmware.os.frame_index());
self.presentation
.note_published_frame(active_ownership, self.firmware.os.frame_index());
}
if was_debugger_connected != self.debugger.stream.is_some()
@@ -505,14 +514,37 @@ mod tests {
#[test]
fn presentation_state_requests_redraw_for_new_frame_publication() {
let ownership = RenderOwnership::new(1, AppMode::Game, 1);
let mut state = PresentationState::default();
state.mark_presented();
state.note_published_frame(1);
state.note_published_frame(ownership, 1);
assert!(state.should_request_redraw());
state.mark_presented();
assert_eq!(state.last_presented_frame, Some(1));
assert_eq!(
state.last_presented_frame,
Some(PresentationFrameMarker { ownership, frame_id: 1 })
);
}
#[test]
fn presentation_state_requests_redraw_when_ownership_changes_with_lower_frame_id() {
let first = RenderOwnership::new(3, AppMode::Game, 1);
let next = RenderOwnership::new(4, AppMode::Game, 2);
let mut state = PresentationState::default();
state.note_published_frame(first, 120);
state.mark_presented();
state.note_published_frame(next, 0);
assert!(state.should_request_redraw());
state.mark_presented();
assert_eq!(
state.last_presented_frame,
Some(PresentationFrameMarker { ownership: next, frame_id: 0 })
);
}
#[test]
@@ -608,11 +640,14 @@ mod tests {
let mut presentation = PresentationState::default();
presentation.mark_presented();
let published = store.latest_frame().expect("published frame");
presentation.note_published_frame(published.frame_id.get());
presentation.note_published_frame(published.ownership, published.frame_id.get());
assert!(presentation.should_request_redraw());
presentation.mark_presented();
assert_eq!(presentation.last_presented_frame, Some(9));
assert_eq!(
presentation.last_presented_frame,
Some(PresentationFrameMarker { ownership: published.ownership, frame_id: 9 })
);
}
#[test]
+12
View File
@@ -0,0 +1,12 @@
[package]
name = "pbxgen-dummy-boy"
version = "0.1.0"
edition = "2021"
[dependencies]
anyhow = "1"
prometeu-bytecode = { path = "../../console/prometeu-bytecode" }
prometeu-hal = { path = "../../console/prometeu-hal" }
[dev-dependencies]
serde_json = "1"
+147
View File
@@ -0,0 +1,147 @@
use anyhow::Result;
use prometeu_bytecode::assembler::assemble;
use prometeu_bytecode::model::{BytecodeModule, DebugInfo, Export, FunctionMeta, SyscallDecl};
use prometeu_hal::color::Color;
use std::fs;
use std::path::PathBuf;
const APP_ID: u32 = 2;
const TITLE: &str = "Dummy Boy";
const APP_VERSION: &str = "0.1.0";
fn asm(s: &str) -> Vec<u8> {
assemble(s).expect("assemble")
}
pub fn generate() -> Result<()> {
let out_dir = cartridge_dir();
fs::create_dir_all(&out_dir)?;
fs::write(out_dir.join("program.pbx"), build_program())?;
fs::write(out_dir.join("manifest.json"), manifest_json())?;
Ok(())
}
pub fn build_program() -> Vec<u8> {
let mut rom = Vec::new();
rom.extend(asm("GET_GLOBAL 0\nPUSH_I32 1\nADD\nSET_GLOBAL 0"));
rom.extend(asm(&format!("PUSH_I64 {}\nHOSTCALL 0", Color::BLACK.raw())));
rom.extend(asm("GET_GLOBAL 0\nPUSH_I32 3\nMOD\nPUSH_I32 0\nEQ"));
let jump_to_green_case_offset = rom.len() + 2;
rom.extend(asm("JMP_IF_FALSE 0"));
rom.extend(asm(&format!("PUSH_I64 {}\nSET_LOCAL 0", Color::RED.raw())));
let jump_to_draw_after_red_offset = rom.len() + 2;
rom.extend(asm("JMP 0"));
let green_case = rom.len() as u32;
rom.extend(asm("GET_GLOBAL 0\nPUSH_I32 3\nMOD\nPUSH_I32 1\nEQ"));
let jump_to_blue_case_offset = rom.len() + 2;
rom.extend(asm("JMP_IF_FALSE 0"));
rom.extend(asm(&format!("PUSH_I64 {}\nSET_LOCAL 0", Color::GREEN.raw())));
let jump_to_draw_after_green_offset = rom.len() + 2;
rom.extend(asm("JMP 0"));
let blue_case = rom.len() as u32;
rom.extend(asm(&format!("PUSH_I64 {}\nSET_LOCAL 0", Color::BLUE.raw())));
let draw = rom.len() as u32;
rom.extend(asm(&format!(
"PUSH_I32 180\n\
PUSH_I32 75\n\
PUSH_I32 120\n\
PUSH_I32 120\n\
PUSH_I64 {}\n\
GET_LOCAL 0\n\
HOSTCALL 1\n\
FRAME_SYNC\n\
RET",
Color::WHITE.raw()
)));
patch_jump(&mut rom, jump_to_green_case_offset, green_case);
patch_jump(&mut rom, jump_to_draw_after_red_offset, draw);
patch_jump(&mut rom, jump_to_blue_case_offset, blue_case);
patch_jump(&mut rom, jump_to_draw_after_green_offset, draw);
BytecodeModule {
version: 0,
const_pool: vec![],
functions: vec![FunctionMeta {
code_offset: 0,
code_len: rom.len() as u32,
param_slots: 0,
local_slots: 1,
return_slots: 0,
max_stack_slots: 8,
}],
code: rom,
debug_info: Some(DebugInfo {
pc_to_span: vec![],
function_names: vec![(0, "main".into())],
}),
exports: vec![Export { symbol: "main".into(), func_idx: 0 }],
syscalls: vec![
SyscallDecl {
module: "gfx2d".into(),
name: "clear".into(),
version: 1,
arg_slots: 1,
ret_slots: 0,
},
SyscallDecl {
module: "gfx2d".into(),
name: "draw_square".into(),
version: 1,
arg_slots: 6,
ret_slots: 0,
},
],
}
.serialize()
}
pub fn manifest_json() -> Vec<u8> {
format!(
"{{\n \"magic\": \"PMTU\",\n \"cartridge_version\": 1,\n \"app_id\": {APP_ID},\n \"title\": \"{TITLE}\",\n \"app_version\": \"{APP_VERSION}\",\n \"app_mode\": \"Game\",\n \"capabilities\": [\"gfx2d\"]\n}}\n"
)
.into_bytes()
}
fn cartridge_dir() -> PathBuf {
let mut out_dir = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
out_dir.pop();
out_dir.pop();
out_dir.pop();
out_dir.push("test-cartridges");
out_dir.push("dummy-boy");
out_dir
}
fn patch_jump(buf: &mut [u8], imm_offset: usize, target: u32) {
buf[imm_offset..imm_offset + 4].copy_from_slice(&target.to_le_bytes());
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn generated_program_is_pbx_module_with_expected_syscalls() {
let bytes = build_program();
assert!(bytes.starts_with(&prometeu_bytecode::PBX_MAGIC));
assert!(bytes.len() > 64);
}
#[test]
fn manifest_declares_distinct_game_identity() {
let manifest: serde_json::Value =
serde_json::from_slice(&manifest_json()).expect("manifest should parse");
assert_eq!(manifest["app_id"], APP_ID);
assert_eq!(manifest["title"], TITLE);
assert_eq!(manifest["app_mode"], "Game");
assert_eq!(manifest["capabilities"], serde_json::json!(["gfx2d"]));
}
}
@@ -0,0 +1,5 @@
use anyhow::Result;
fn main() -> Result<()> {
pbxgen_dummy_boy::generate()
}
+6 -6
View File
@@ -14,7 +14,7 @@ use prometeu_hal::cartridge::{
use prometeu_hal::color::Color;
use prometeu_hal::glyph::Glyph;
use prometeu_hal::glyph_bank::{
TileSize, GLYPH_BANK_COLORS_PER_PALETTE, GLYPH_BANK_PALETTE_COUNT_V1,
TileSize, GLYPH_BANK_COLORS_PER_PALETTE, GLYPH_BANK_MAX_PALETTE_COUNT_V1,
};
use prometeu_hal::scene_bank::SceneBank;
use prometeu_hal::scene_layer::{ParallaxFactor, SceneLayer};
@@ -275,15 +275,15 @@ fn build_glyph_asset() -> (AssetEntry, Vec<u8>) {
bank_type: BankType::GLYPH,
offset: 0,
size: payload.len() as u64,
decoded_size: (8 * 8 + GLYPH_BANK_PALETTE_COUNT_V1 * GLYPH_BANK_COLORS_PER_PALETTE * 4)
decoded_size: (8 * 8 + GLYPH_BANK_MAX_PALETTE_COUNT_V1 * GLYPH_BANK_COLORS_PER_PALETTE * 4)
as u64,
codec: AssetCodec::None,
metadata: serde_json::json!({
"tile_size": 8,
"width": 8,
"height": 8,
"palette_count": GLYPH_BANK_PALETTE_COUNT_V1,
"palette_authored": GLYPH_BANK_PALETTE_COUNT_V1
"palette_count": GLYPH_BANK_MAX_PALETTE_COUNT_V1,
"palette_authored": GLYPH_BANK_MAX_PALETTE_COUNT_V1
}),
};
@@ -292,8 +292,8 @@ fn build_glyph_asset() -> (AssetEntry, Vec<u8>) {
fn build_palette_bytes() -> Vec<u8> {
let mut bytes =
Vec::with_capacity(GLYPH_BANK_PALETTE_COUNT_V1 * GLYPH_BANK_COLORS_PER_PALETTE * 4);
for palette_id in 0..GLYPH_BANK_PALETTE_COUNT_V1 {
Vec::with_capacity(GLYPH_BANK_MAX_PALETTE_COUNT_V1 * GLYPH_BANK_COLORS_PER_PALETTE * 4);
for palette_id in 0..GLYPH_BANK_MAX_PALETTE_COUNT_V1 {
for color_index in 0..GLYPH_BANK_COLORS_PER_PALETTE {
let color = if color_index == 1 { stress_color(palette_id) } else { Color::BLACK };
bytes.extend_from_slice(&color.raw().to_be_bytes());
View File
+8 -3
View File
@@ -1,8 +1,9 @@
{"type":"meta","next_id":{"DSC":44,"AGD":47,"DEC":39,"PLN":154,"LSN":52,"CLSN":1}}
{"type":"discussion","id":"DSC-0043","status":"open","ticket":"system-os-cartridge-switch-orchestrator","title":"SystemOS Cartridge Switch Orchestrator","created_at":"2026-07-03","updated_at":"2026-07-03","tags":["runtime","os","lifecycle","game","cartridge","architecture"],"agendas":[{"id":"AGD-0044","file":"AGD-0044-systemos-cartridge-switch-orchestrator.md","status":"open","created_at":"2026-07-03","updated_at":"2026-07-03"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"meta","next_id":{"DSC":49,"AGD":52,"DEC":43,"PLN":174,"LSN":57,"CLSN":1}}
{"type":"discussion","id":"DSC-0044","status":"done","ticket":"hub-suspended-game-kill-affordance","title":"Hub Suspended Game Kill Affordance","created_at":"2026-07-05","updated_at":"2026-07-05","tags":["hub","lifecycle","game","ui"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0054","file":"discussion/lessons/DSC-0044-hub-suspended-game-kill-affordance/LSN-0054-manual-hub-kill-must-share-game-termination-cleanup.md","status":"done","created_at":"2026-07-05","updated_at":"2026-07-05"}]}
{"type":"discussion","id":"DSC-0043","status":"done","ticket":"system-os-cartridge-switch-orchestrator","title":"SystemOS Cartridge Switch Orchestrator","created_at":"2026-07-03","updated_at":"2026-07-05","tags":["runtime","os","lifecycle","game","cartridge","architecture"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0053","file":"discussion/lessons/DSC-0043-system-os-cartridge-switch-orchestrator/LSN-0053-game-switching-is-lifecycle-replacement-not-loader-work.md","status":"done","created_at":"2026-07-05","updated_at":"2026-07-05"}]}
{"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":"done","ticket":"vm-render-parallel-execution-boundary","title":"VM and Render Parallel Execution Boundary","created_at":"2026-06-04","updated_at":"2026-06-06","tags":["runtime","renderer","vm","concurrency","architecture","perf"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0048","file":"discussion/lessons/DSC-0040-vm-render-parallel-execution-boundary/LSN-0048-render-workers-need-a-closed-packet-contract.md","status":"done","created_at":"2026-06-06","updated_at":"2026-06-06"}]}
{"type":"discussion","id":"DSC-0041","status":"in_progress","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-07-04","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":"accepted","created_at":"2026-06-05","updated_at":"2026-07-03"},{"id":"AGD-0046","file":"AGD-0046-vm-context-ownership-for-resident-game-and-vm-backed-shell.md","status":"accepted","created_at":"2026-07-04","updated_at":"2026-07-04"}],"decisions":[{"id":"DEC-0037","file":"DEC-0037-foreground-stack-and-game-pause-contract.md","status":"accepted","created_at":"2026-07-03","updated_at":"2026-07-03","ref_agenda":"AGD-0041"},{"id":"DEC-0038","file":"DEC-0038-vm-session-ownership-for-vm-backed-processes.md","status":"accepted","created_at":"2026-07-04","updated_at":"2026-07-04","ref_agenda":"AGD-0046"}],"plans":[{"id":"PLN-0136","file":"PLN-0136-route-desktop-home-key-outside-guest-input.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0037"]},{"id":"PLN-0137","file":"PLN-0137-implement-systemos-foreground-stack-state.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0037"]},{"id":"PLN-0138","file":"PLN-0138-specify-foreground-pause-and-home-contract.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0037"]},{"id":"PLN-0139","file":"PLN-0139-validate-game-home-shell-game-end-to-end.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0037"]},{"id":"PLN-0140","file":"PLN-0140-deliver-game-pause-resume-and-suspension.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0037"]},{"id":"PLN-0141","file":"PLN-0141-integrate-render-audio-and-input-pause-boundaries.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0037"]},{"id":"PLN-0142","file":"PLN-0142-deliver-game-lifecycle-events-to-vm-runtime.md","status":"done","created_at":"2026-07-04","updated_at":"2026-07-04","ref_decisions":["DEC-0037"]},{"id":"PLN-0143","file":"PLN-0143-guarantee-cooperative-pause-budget-tick-before-suspension.md","status":"done","created_at":"2026-07-04","updated_at":"2026-07-04","ref_decisions":["DEC-0037"]},{"id":"PLN-0144","file":"PLN-0144-suspend-resident-game-when-shell-takes-foreground.md","status":"done","created_at":"2026-07-04","updated_at":"2026-07-04","ref_decisions":["DEC-0037"]},{"id":"PLN-0145","file":"PLN-0145-centralize-resident-game-resume-transition.md","status":"done","created_at":"2026-07-04","updated_at":"2026-07-04","ref_decisions":["DEC-0037"]},{"id":"PLN-0146","file":"PLN-0146-consolidate-lifecycle-process-lookup-helpers.md","status":"done","created_at":"2026-07-04","updated_at":"2026-07-04","ref_decisions":["DEC-0037"]},{"id":"PLN-0147","file":"PLN-0147-move-native-shell-profile-update-into-hub.md","status":"done","created_at":"2026-07-04","updated_at":"2026-07-04","ref_decisions":["DEC-0037"]},{"id":"PLN-0148","file":"PLN-0148-introduce-vm-session-registry-and-identity.md","status":"done","created_at":"2026-07-04","updated_at":"2026-07-04","ref_decisions":["DEC-0038"]},{"id":"PLN-0149","file":"PLN-0149-move-vm-runtime-state-into-vm-sessions.md","status":"done","created_at":"2026-07-04","updated_at":"2026-07-04","ref_decisions":["DEC-0038"]},{"id":"PLN-0150","file":"PLN-0150-route-cartridge-loading-through-vm-sessions.md","status":"done","created_at":"2026-07-04","updated_at":"2026-07-04","ref_decisions":["DEC-0038"]},{"id":"PLN-0151","file":"PLN-0151-schedule-foreground-vm-session-ticks.md","status":"done","created_at":"2026-07-04","updated_at":"2026-07-04","ref_decisions":["DEC-0038"]},{"id":"PLN-0152","file":"PLN-0152-validate-game-and-vm-shell-session-coexistence.md","status":"done","created_at":"2026-07-04","updated_at":"2026-07-04","ref_decisions":["DEC-0038"]},{"id":"PLN-0153","file":"PLN-0153-specify-vm-session-ownership-and-background-ready-scheduling.md","status":"done","created_at":"2026-07-04","updated_at":"2026-07-04","ref_decisions":["DEC-0038"]}],"lessons":[]}
{"type":"discussion","id":"DSC-0041","status":"done","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-07-05","tags":["runtime","os","lifecycle","shell","game","vm","foreground","architecture"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0052","file":"discussion/lessons/DSC-0041-foreground-stack-game-pause-shell-vm-backed/LSN-0052-foreground-ownership-and-vm-session-ownership-are-separate.md","status":"done","created_at":"2026-07-05","updated_at":"2026-07-05"}]}
{"type":"discussion","id":"DSC-0042","status":"done","ticket":"real-render-worker-establishment","title":"Real Render Worker Establishment","created_at":"2026-06-06","updated_at":"2026-06-20","tags":["runtime","renderer","worker","concurrency","host","hal","architecture"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0049","file":"discussion/lessons/DSC-0042-real-render-worker-establishment/LSN-0049-render-worker-publication-boundary.md","status":"done","created_at":"2026-06-20","updated_at":"2026-06-20"}]}
{"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"}]}
@@ -18,6 +19,7 @@
{"type":"discussion","id":"DSC-0005","status":"open","ticket":"system-fault-semantics-and-control-surface","title":"Agenda - System Fault Semantics and Control Surface","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0004","file":"AGD-0004-system-fault-semantics-and-control-surface.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0006","status":"open","ticket":"vm-owned-random-service","title":"Agenda - VM-Owned Random Service","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0005","file":"AGD-0005-vm-owned-random-service.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0007","status":"open","ticket":"app-home-filesystem-surface-and-semantics","title":"Agenda - App Home Filesystem Surface and Semantics","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0006","file":"AGD-0006-app-home-filesystem-surface-and-semantics.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0045","status":"open","ticket":"background-service-audio-execution","title":"Background Service and Audio Execution","created_at":"2026-07-05","updated_at":"2026-07-05","tags":["runtime","os","lifecycle","service","audio","background","architecture"],"agendas":[{"id":"AGD-0048","file":"AGD-0048-background-service-audio-execution.md","status":"open","created_at":"2026-07-05","updated_at":"2026-07-05"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0008","status":"done","ticket":"perf-runtime-telemetry-hot-path","title":"Agenda - [PERF] Runtime Telemetry Hot Path","created_at":"2026-03-27","updated_at":"2026-06-04","tags":[],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0026","file":"discussion/lessons/DSC-0008-perf-runtime-telemetry-hot-path/LSN-0026-push-based-telemetry-model.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
{"type":"discussion","id":"DSC-0009","status":"done","ticket":"perf-async-background-work-lanes-for-assets-and-fs","title":"Agenda - [PERF] Async Background Work Lanes for Assets and FS","created_at":"2026-03-27","updated_at":"2026-07-01","tags":["perf","asset","fs","async","scheduler","runtime"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0050","file":"discussion/lessons/DSC-0009-perf-async-background-work-lanes-for-assets-and-fs/LSN-0050-serial-async-lanes-bound-backlog-complexity.md","status":"done","created_at":"2026-07-01","updated_at":"2026-07-01"}]}
{"type":"discussion","id":"DSC-0010","status":"done","ticket":"perf-host-desktop-frame-pacing-and-presentation","title":"Agenda - [PERF] Host Desktop Frame Pacing and Presentation","created_at":"2026-03-27","updated_at":"2026-04-20","tags":[],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0036","file":"discussion/lessons/DSC-0010-perf-host-desktop-frame-pacing-and-presentation/LSN-0036-frame-publication-and-host-invalidation-must-be-separate.md","status":"done","created_at":"2026-04-20","updated_at":"2026-04-20"}]}
@@ -42,3 +44,6 @@
{"type":"discussion","id":"DSC-0033","status":"done","ticket":"system-os-service-ownership-and-module-layout","title":"Agenda - SystemOS Service Ownership and Module Layout","created_at":"2026-05-14","updated_at":"2026-05-15","tags":["runtime","os","services","module-layout","vm","window-manager","logging"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0042","file":"discussion/lessons/DSC-0033-system-os-service-ownership-and-module-layout/LSN-0042-systemos-service-ownership-boundary.md","status":"done","created_at":"2026-05-15","updated_at":"2026-05-15"}]}
{"type":"discussion","id":"DSC-0036","status":"done","ticket":"prometeu-hub-ui-direction","title":"Agenda - Prometeu Hub UI Direction","created_at":"2026-05-15","updated_at":"2026-05-22","tags":["hub","ui","shell","system-apps","lifecycle","design-system"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0045","file":"discussion/lessons/DSC-0036-prometeu-hub-ui-direction/LSN-0045-hub-ui-slices-should-prove-os-boundaries.md","status":"done","created_at":"2026-05-22","updated_at":"2026-05-22"}]}
{"type":"discussion","id":"DSC-0037","status":"done","ticket":"rgba8888-framebuffer-and-pixel-format-direction","title":"Agenda - RGBA8888 Framebuffer and Pixel Format Direction","created_at":"2026-05-22","updated_at":"2026-05-23","tags":["gfx","framebuffer","rgb565","rgba8888","renderer","assets","host","backend"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0046","file":"discussion/lessons/DSC-0037-rgba8888-framebuffer-and-pixel-format-direction/LSN-0046-pixel-format-contracts-must-move-as-one-surface.md","status":"done","created_at":"2026-05-23","updated_at":"2026-05-23"}]}
{"type":"discussion","id":"DSC-0046","status":"done","ticket":"runtime-owned-variable-glyph-bank-palette-protocol","title":"Runtime-Owned Variable Glyph Bank Palette Protocol","created_at":"2026-07-14","updated_at":"2026-07-14","tags":["runtime","gfx","assets","glyph-bank","palette-serialization","protocol"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0055","file":"discussion/lessons/DSC-0046-runtime-owned-variable-glyph-bank-palette-protocol/LSN-0055-runtime-owned-asset-protocols-must-align-payload-residency-and-lookup.md","status":"done","created_at":"2026-07-14","updated_at":"2026-07-14"}]}
{"type":"discussion","id":"DSC-0047","status":"open","ticket":"portable-host-backend-strategy","title":"Portable Host Backend Strategy","created_at":"2026-07-14","updated_at":"2026-07-14","tags":["host","desktop","portable","sdl","backend","rendering","input","audio","linux","android","handheld"],"agendas":[{"id":"AGD-0050","file":"AGD-0050-portable-host-backend-strategy.md","status":"open","created_at":"2026-07-14","updated_at":"2026-07-14"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0048","status":"done","ticket":"corrigir-identificacao-formato-pbx","title":"Corrigir Identificacao do Formato PBX","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["runtime","bytecode","pbx","loader","format","architecture"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0056","file":"discussion/lessons/DSC-0048-corrigir-identificacao-formato-pbx/LSN-0056-runtime-artifact-identity-must-not-borrow-frontend-names.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15"}]}
@@ -0,0 +1,145 @@
---
id: LSN-0052
ticket: foreground-stack-game-pause-shell-vm-backed
title: Foreground Ownership and VM Session Ownership Are Separate
created: 2026-07-05
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
---
# LSN-0052: Foreground Ownership and VM Session Ownership Are Separate
## Context
DSC-0041 closed the `Game -> Home/Shell -> same Game` lifecycle for the first
runtime implementation that supports both native Shell apps and VM-backed Shell
apps. The important architectural shift was not only pausing the Game. The
runtime also had to stop treating one firmware-owned VM as the place where all
guest execution state lives.
The final model separates two questions:
- Who owns the foreground visual/input authority right now?
- Which VM-backed process owns a mutable VM execution context?
Foreground ownership is global SystemOS policy. VM execution state belongs to a
session associated with a task/process. A suspended resident Game is not a saved
snapshot and not a special global VM. It is a live VM session that is temporarily
ineligible for normal foreground ticks, input, frame pacing, and render
publication.
## Key Decisions
### Foreground Stack and Game Pause Contract
**What:** PROMETEU uses a single foreground owner in v1. Hub/Home is the root
Shell owner, a Game may remain resident, and one foreground Shell app may run in
front of the resident Game. Pressing desktop `Esc` is a host/SystemOS Home
request, not guest input.
**Why:** This preserves console-like navigation without turning the runtime into
a general multitasking scheduler. It lets the system pause and suspend a Game,
run Hub or Shell, then resume the same Game deterministically.
**Trade-offs:** The model intentionally rejects multiple resident Games, direct
Shell-to-Game return, background execution, and Game-to-Game switching in v1.
Those features remain future work, but the lifecycle structure now has a place
to add them.
### VM Session Ownership for VM-Backed Processes
**What:** VM-backed mutable execution state is owned by VM sessions. A
VM-backed Game and a VM-backed Shell never share the same VM, stack, heap, PC,
open handles, cartridge identity, or VM-scoped runtime state.
**Why:** A single firmware-owned VM cannot represent a suspended resident Game
and a foreground VM Shell at the same time. Loading the Shell into that global
VM would overwrite the Game context that the lifecycle model says is resident.
**Trade-offs:** Session ownership is more explicit than one global VM, but it
keeps the model simpler than snapshot/restore. It also prepares the runtime for
future background-capable sessions without committing to background scheduling
yet.
## Patterns and Algorithms
### Pause Is Cooperative, Suspension Is OS Authority
The Game receives lifecycle events such as pause and resume, but the OS owns the
actual scheduling state. If the Game does not cooperate within the bounded pause
budget, SystemOS can suspend it anyway. On resume, the Game receives a foreground
restore event and may still keep its internal pause screen while it
synchronizes.
This distinction prevents userland from owning system navigation. The Game may
observe and react. It cannot veto Home.
### Foreground Owner Is Not the Same as Tick Eligibility
Foreground ownership controls input, visual authority, render ownership, and
normal frame pacing. Tick eligibility controls whether a VM session may execute.
In v1, only the foreground VM session receives normal ticks, and the resident
Game does not tick while Shell or Hub is foreground.
The important design detail is that the data model does not assume this must be
true forever. Sessions can later become background-eligible without changing who
owns render/input foreground.
### VM Sessions Are the Unit of Mutable Guest State
Each VM-backed task/process maps to a `VmSession`. The session owns the VM,
runtime state, session-scoped filesystem state, open file handles, next handle
allocation, cartridge identity, lifecycle delivery state, and debug state.
Cartridge loading creates or reuses a VM session through SystemOS session
services. Firmware orchestrates macro states such as `LoadCartridge`,
`GameRunning`, `HubHome`, and `ShellRunning`, but it no longer owns a canonical
guest VM.
### Debugger and Host Inspection Must Follow the Active Session
Host debugging must inspect and mutate the active session VM, not a transitional
global VM. PC, operand stack, breakpoints, debug-step execution, cartridge
identity, and breakpoint-hit events all need to resolve through active session
state.
This keeps debugger behavior aligned with actual execution. A debugger that
observes a different VM than the scheduler ticks is worse than no debugger: it
creates false confidence and hides lifecycle bugs.
### Operational Failures Should Cross Facades as Typed Errors
Session creation and loading are operational boundaries. Missing task, missing
process, duplicate VM session, missing VM session during initialization, and
foreground Shell rejection should be typed errors. Firmware can then choose a
controlled crash report, a launch rejection, or a logged no-transition outcome.
Panics are reserved for test/setup wrappers or impossible internal invariants
that have already been proven by prior checks.
## Pitfalls
- Do not use a global VM as a compatibility bridge after session ownership is
introduced. It will eventually become stale or contradictory.
- Do not let Home/SystemOS be guest input. It changes OS authority, so it must
bypass guest pad state.
- Do not present old frames after foreground ownership changes. Render ownership
and epoch validation are part of lifecycle correctness, not renderer polish.
- Do not model pause and suspension as the same state. Pause is visible to the
Game; suspension is the scheduler mechanism.
- Do not encode v1 limits such as one resident Game or one foreground Shell by
collapsing storage into one VM. Express those limits as lifecycle/session
policy.
- Do not let debugger state drift from scheduler state. The debugger must use
the same active session as normal execution.
## Takeaways
- Foreground ownership is global policy; VM execution state is session-owned.
- A suspended Game is a preserved session, not a serialized VM and not a global
VM waiting to be reused.
- Shell apps can be native or VM-backed, but only VM-backed processes need VM
sessions.
- Session ownership is the foundation for future background-capable processes,
even before background execution exists.
- Typed session/lifecycle errors make launch and recovery behavior explicit at
firmware boundaries.
@@ -0,0 +1,67 @@
---
id: LSN-0053
ticket: system-os-cartridge-switch-orchestrator
title: Game Switching Is Lifecycle Replacement, Not Loader Work
created: 2026-07-05
tags: [runtime, os, lifecycle, game, cartridge]
---
## Context
PROMETEU supports two superficially similar flows:
- `Game -> Home -> same Game`, which is pause/suspend/resume.
- `Game A -> Home -> Game B`, which is destructive replacement.
The second flow is not a loader feature. It is a SystemOS lifecycle operation
that happens to use the cartridge loader after the old resident Game has been
removed from resumable state.
## Key Decisions
### SystemOS Game Cartridge Switch Orchestrator
**What:** A different-Game launch from Home terminates the previous resident
Game before loading the new cartridge. The new Game receives a fresh VM session.
**Why:** Reusing or preserving the old Game while the new Game loads creates a
rollback problem across VM state, handles, assets, input, audio, render
ownership, debug state, and lifecycle delivery. V1 does not need that
transactional model.
**Trade-offs:** Failed replacement returns to Home and does not restore the old
Game. This is intentionally simpler than snapshot/rollback and makes state
ownership visible in tests.
## Patterns and Algorithms
Use a resolved SystemOS switch target, not a guest syscall, for Home launches.
The target carries cartridge path and identity, while SystemOS owns the policy:
1. detect whether the selected Game matches the resident `app_id`;
2. resume if it is the same Game;
3. terminate the old resident Game if it is different;
4. load the new cartridge through the normal loader;
5. create and initialize a fresh VM session;
6. return to Home on replacement failure without restoring the previous Game.
The loader stays a materializer. It does not close tasks, remove sessions,
repair foreground state, or own failure recovery.
## Pitfalls
- Treating a different Game as a resume path leaks VM execution state.
- Letting the loader own lifecycle cleanup hides policy in the wrong layer.
- Keeping the old Game as rollback state requires correctness across assets,
render ownership, input barriers, audio, open handles, and debugger state.
- A switch test with only one cartridge cannot prove identity replacement.
## Takeaways
- Same-Game Home selection is resume; different-Game Home selection is
destructive replacement.
- SystemOS owns cartridge switching policy; the cartridge loader only loads.
- Replacement failure should be a clean Home state, not a rollback to the old
Game.
- End-to-end switch tests need visually distinct cartridges to catch stale
session or stale frame reuse.
@@ -0,0 +1,72 @@
---
id: LSN-0054
ticket: hub-suspended-game-kill-affordance
title: Manual Hub Kill Must Share Game Termination Cleanup
created: 2026-07-05
tags: [hub, lifecycle, game, ui, assets]
---
## Context
After a Game returns to Home, the Game can remain resident and suspended so it
can be resumed later. That state needs a visible, direct way to terminate the
resident Game without launching another cartridge just to force replacement.
The Hub kill affordance solved the UX gap, but the durable engineering lesson is
the cleanup boundary: manual kill must not become a second, partial termination
path.
## Key Decisions
### Hub Suspended Game Kill Affordance
**What:** Hub renders a red bottom-right control when a Game is resident and
suspended. The control shows only the Game title. Clicking it immediately
terminates the resident Game and keeps the user in Hub.
**Why:** The user can distinguish "resume this Game" from "discard this resident
Game" without starting a different cartridge. Reusing the canonical termination
path prevents a repeat of stale scene/glyph/asset state bugs.
**Trade-offs:** V1 has no confirmation step. The destructive nature is carried
by placement, color, and the fact that the target Game is already out of
foreground.
## Patterns and Algorithms
Manual Hub kill and destructive Game replacement should call the same resident
Game termination helper. That helper is responsible for the whole runtime
surface:
- close the Game task;
- stop the process;
- remove the VM session;
- clear resident Game state and task-scoped lifecycle delivery;
- restore Shell/Hub render ownership;
- clear lifecycle audio pause state;
- unbind the Game2D composer scene;
- shut down cartridge-scoped asset manager state and physical banks;
- emit explicit Hub/POS observability for manual kill.
The Hub itself should emit a high-level action such as `KillResidentGame`; it
should not know how to clean runtime subsystems.
## Pitfalls
- A UI-only kill that removes a task but leaves assets or composer binding alive
can still fail later when another Game renders.
- A cleanup-only helper without an end-to-end Hub click test can miss the
interaction between hitbox, foreground ownership, render owner, and no-resume.
- Hard-coded click coordinates in tests make the UI contract harder to maintain;
expose the layout hitbox when tests need to exercise it.
## Takeaways
- Visible system controls should produce system actions, not direct subsystem
mutation from UI code.
- Manual kill and Game replacement are variants of the same resident Game
termination contract.
- Cleanup tests should prove both logical state removal and visible-frame
behavior: the control appears before kill and disappears after kill.
- "No resume after kill" is as important as "task closed" because resumability
is the user-facing state.
@@ -0,0 +1,97 @@
---
id: LSN-0055
ticket: runtime-owned-variable-glyph-bank-palette-protocol
title: Runtime-Owned Asset Protocols Must Align Payload, Residency, and Lookup
created: 2026-07-14
tags: [runtime, assets, glyph-bank, palette-serialization, protocol]
decision: DEC-0041
---
## Context
The runtime changed the `GLYPH/indexed_v1` glyph-bank palette contract from a
fixed 64-palette payload and resident table to variable palette serialization
and variable resident palette storage.
The initiating pressure came from packer/studio: fixed RGBA8888 palette padding
made small glyph banks pay for `64 * 16 * 4` palette bytes even when they used
far fewer palettes. The important architectural point was that the runtime, not
the packer, had to decide the protocol. The packer can only emit payloads that
conform to the runtime contract once the runtime spec is published.
## Key Decisions
### Variable Glyph Bank Palette Protocol
**What:**
`palette_count` became the number of serialized palettes and the number of
resident palettes in the loaded `GlyphBank`. The valid range is `1..=64`.
`palette_id` remains a direct palette identity and is valid only when
`palette_id < palette_count` for the referenced resident bank.
**Why:**
Keeping serialized count variable while retaining a fixed 64-slot resident
table would preserve two meanings for palette capacity. The runtime would save
payload bytes but still carry a split contract between payload shape, resident
shape, and lookup validity. Making all three agree gives the runtime one
source of truth.
**Trade-offs:**
Palette validity is now bank-dependent. Scene and sprite composition must check
the referenced loaded bank instead of relying on a global `0..63` rule. This
adds validation work, but it prevents invalid references from silently becoming
transparent or default colors.
## Patterns and Algorithms
Let the runtime own runtime-facing asset protocols. Tooling can discover pain,
but the runtime spec must define effective metadata, payload shape, resident
shape, and failure semantics.
Make count fields material. A count such as `palette_count` should not describe
only what the producer authored or only what the payload happens to include. If
runtime lookup depends on it, the count must also define resident state and
validation boundaries.
Keep identity direct unless a real remapping problem exists. Sparse-to-dense
palette remapping was rejected because it would add a second identity layer
across scenes, sprites, packer output, and runtime lookup. V1 keeps palette id
`N` as palette slot `N` in the resident bank.
Separate transparent color from invalid lookup. RGBA alpha is valid color data.
An invalid palette reference must be observable as invalid; it must not be
collapsed into `Color::TRANSPARENT`.
Use residue scans after protocol migrations. Search for fixed byte formulas,
old constants, fixture helpers, and spec phrases. Legitimate hits should be
renamed as maximum-bound concepts, not left as accidental active contracts.
## Pitfalls
Partially variable specs are worse than fixed specs. The asset spec already had
variable size formulas in some places but still required `palette_count = 64`
elsewhere. That contradiction made it unclear which rule was canonical.
Resident data structures can preserve obsolete protocol assumptions after the
payload changes. A fixed array in `GlyphBank` would have kept the old model
alive even if decode accepted variable payloads.
Fallback rendering hides contract errors. Returning transparent for an invalid
palette id makes bad assets and bad scene references look like intentional
alpha, which is exactly the wrong failure mode for a runtime protocol.
Fixture generators are part of the contract surface. Stress cartridges and
test payload builders must express whether they are using a variable count or
the v1 maximum; otherwise they reintroduce fixed-padding assumptions.
## Takeaways
- Runtime-facing asset protocols should align payload size, resident memory,
and lookup validity.
- `palette_count` is effective runtime metadata, not producer commentary.
- Direct identity is simpler than remapping until a concrete remapping need
exists.
- Invalid palette references should fail explicitly; transparent remains a
valid RGBA color, not an error substitute.
- Protocol migrations need spec edits, code changes, fixture updates, and
residue scans in the same workflow.
@@ -0,0 +1,61 @@
---
id: LSN-0056
ticket: corrigir-identificacao-formato-pbx
title: Runtime Artifact Identity Must Not Borrow Frontend Names
created: 2026-07-15
tags: [runtime, bytecode, pbx, frontend, format-boundary]
---
## Context
Prometeu accepts bytecode produced by multiple frontends. PBS is the base
frontend language, while PBX is the executable bytecode artifact consumed by the
runtime.
The runtime had inherited PBS terminology in the executable bytecode path,
including the serialized magic number, comments, tests, and VM loader checks.
That made one frontend appear to own the runtime executable format.
## Key Decisions
### PBX Executable Format Identity
**What:** PBX is the runtime executable bytecode format, and `PBX\0` is its only
valid magic number.
**Why:** Runtime artifact identity must be independent from any frontend that can
produce the artifact. Naming the executable format after PBS would make the
runtime boundary look language-specific.
**Trade-offs:** The correction intentionally rejects old PBS-prefixed executable
artifacts instead of carrying a compatibility alias. This keeps the format
contract singular, but requires stale generated fixtures to be regenerated or
updated.
## Patterns and Algorithms
Put file-format identity in the module that serializes and deserializes the
format. Loaders and higher-level runtime code should call that boundary instead
of duplicating magic-number checks.
When renaming an artifact identity, update all fixture construction and generator
assertions in the same pass as production serialization. Mixed fixture identity
usually means tests are asserting historical spelling rather than current
contract.
## Pitfalls
Do not globally erase frontend names. PBS remains correct when the subject is
the PBS language, stdlib, or frontend-facing API. It is wrong only when it names
the executable bytecode artifact.
Do not preserve old magic values just to make a rename feel less disruptive. If
there is no compatibility requirement for old artifacts, aliases keep the
incorrect model alive.
## Takeaways
- Runtime artifact names should describe the runtime contract, not the compiler
or frontend that produced the artifact.
- Magic numbers are normative format identity, not cosmetic labels.
- Loader code should delegate file-format validation to the format owner.
@@ -1,178 +0,0 @@
---
id: AGD-0041
ticket: foreground-stack-game-pause-shell-vm-backed
title: Foreground Stack, Game Pause, and VM-Backed Shell Coexistence
status: accepted
created: 2026-06-05
resolved: 2026-07-03
decision: DEC-0037
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
---
## Contexto
Durante a discussao da `DSC-0040` sobre separar VM e render worker, surgiu um caso que nao pertence somente ao render: `Game -> Shell -> Game`.
O caso minimo e:
- um Game esta rodando;
- o usuario aperta Home;
- o Game deve sair do foreground sem ser encerrado;
- o Hub/Shell assume a tela;
- o usuario pode abrir um app Shell, inclusive VM-backed;
- depois o usuario retorna ao mesmo Game.
O render worker precisa saber qual visual owner pode apresentar frames, mas a decisao principal e de lifecycle: quais VMs existem, quais podem executar, o que significa pausar um Game, e como Shell apps coexistem com um Game pausado.
Material relacionado:
- `DSC-0031`: separacao entre perfis Game e System/Shell.
- `DSC-0032`: SystemOS como autoridade de lifecycle/process/task.
- `DSC-0035`: janelas Shell pertencem a tasks e definem liveness do app.
- `DSC-0036`: Hub/Shell prova fatias de lifecycle.
- `DSC-0040`: render ownership/epoch durante transicoes e paralelismo VM/render.
## Problema
Precisamos definir o contrato de foreground para impedir ambiguidades como:
- Game pausado continuando a executar frames logicos enquanto Shell esta no foreground;
- Shell VM-backed competindo com Game por pacing, input, superficie ou render ownership;
- multiplos Shells foreground ou multiplos Games ativos sem uma politica explicita;
- retorno ao Game sem clareza sobre estado pausado, input, render invalidation e retomada da VM.
Sem esse contrato, a separacao VM/render da `DSC-0040` pode ficar tecnicamente correta, mas o SystemOS ainda pode permitir estados incoerentes.
## Pontos Criticos
- Existe apenas um foreground visual owner por vez.
- Background execution e outro assunto e deve ficar fora da primeira decisao, salvo se for necessario definir uma proibicao explicita.
- Shell VM-backed nao deve herdar politica de game loop so por usar VM.
- Game pausado provavelmente deve reter estado, mas nao deve consumir frames logicos.
- O Hub/Shell precisa ser capaz de rodar enquanto o Game esta suspenso.
- A transicao deve invalidar render submissions antigas para impedir present de frames obsoletos.
- O modelo precisa caber no SystemOS/lifecycle existente, nao diretamente no render worker.
## Opcoes
### Opcao A - Foreground unico, Game suspenso, Shell unico
- **Abordagem:** permitir no maximo um Game carregado e no maximo um Shell foreground; ao apertar Home, o Game entra em estado pausado/suspenso e Shell/Hub assume o foreground. Shell VM-backed pode executar apenas enquanto for o foreground Shell.
- **Pro:** modelo simples, previsivel e alinhado com console; reduz concorrencia real entre VMs; combina com a regra de render ownership unico.
- **Contra:** nao cobre multitarefa/background; futuras features de overlay ou apps persistentes precisarao expandir o contrato.
- **Manutenibilidade:** alta; SystemOS pode modelar uma pilha pequena de foreground/suspended sem virar scheduler generico.
### Opcao B - Multiplas VMs residentes, somente foreground executa
- **Abordagem:** permitir que Game e Shell VM-backed coexistam como VMs residentes, mas somente a entidade foreground executa. O Game pausado fica residente, sem tick; Shell VM-backed roda sob lifecycle Shell.
- **Pro:** preserva estado e permite retorno rapido; nao exige background execution.
- **Contra:** precisa contrato claro de memoria, ownership de input, foco, cancelamento e fechamento.
- **Manutenibilidade:** boa se os estados forem explicitos; ruim se a residencia for confundida com execucao em background.
### Opcao C - Encerrar Game ao entrar no Shell VM-backed
- **Abordagem:** Home fecha/salva o Game antes de abrir Shell VM-backed, evitando coexistencia.
- **Pro:** simplifica o runtime.
- **Contra:** quebra a expectativa de console moderno; torna `Game -> Shell -> Game` um reload, nao uma pausa.
- **Manutenibilidade:** simples no curto prazo, mas provavelmente gera mais excecoes e UX ruim depois.
### Opcao D - Background real desde ja
- **Abordagem:** permitir Game pausado ou Shell apps rodando em background com politicas de prioridade.
- **Pro:** cobre casos futuros ricos.
- **Contra:** amplia demais escopo: scheduler, budget, energia, audio, input, IO e memoria.
- **Manutenibilidade:** baixa para v1; mistura a decisao de foreground com multitarefa real.
## Sugestao / Recomendacao
Recomendo seguir com a combinacao das opcoes A e B:
- somente um Game residente por vez;
- somente um Shell foreground por vez;
- Game pode ficar pausado/suspenso enquanto Shell esta foreground;
- Shell VM-backed pode existir junto com Game pausado, mas segue lifecycle Shell;
- somente o owner foreground executa VM/tick/event loop conforme sua politica;
- background execution fica explicitamente fora de escopo;
- render ownership muda junto com foreground owner e deve invalidar submissions antigas via epoch/generation, conforme `DSC-0040`.
Isso preserva o ciclo `Game -> Home/Shell -> Game` sem transformar o runtime em multitarefa geral agora.
## Perguntas em Aberto
- [x] Qual e o nome canonico dos estados de Game fora do foreground: `Paused`, `Suspended`, ambos, ou outro?
- [x] Ao apertar Home, o Game deve receber um evento/interrupt/trap de pausa antes de parar de executar?
- [x] O Hub e um Shell especial sempre presente ou uma task Shell comum?
- [x] Um app Shell VM-backed pode substituir o Hub no foreground ou o Hub permanece como owner raiz?
- [x] Quando o Shell VM-backed fecha, o retorno vai sempre para Hub ou pode voltar diretamente ao Game?
- [x] O input do Game e drenado/limpo ao pausar e ao retomar?
- [x] Audio do Game pausa junto com a VM ou tem politica propria?
- [x] Existe limite de memoria/residencia para manter Game pausado enquanto Shell app roda?
- [x] O retorno ao Game exige novo frame antes de trocar a superficie, ou a tela pode manter Hub/Shell ate a primeira submission valida?
- [x] Quais eventos de lifecycle precisam ser visiveis para firmware, OS, VM e host?
## Resolucao
Fica aceito o modelo `Game -> Home/Shell -> mesmo Game` com foreground unico e
residencia limitada:
- somente um Game pode estar residente por vez;
- somente um Shell pode ser foreground por vez;
- Hub e o Shell root/especial e permanece owner raiz/back-stack;
- um Shell VM-backed pode assumir o foreground visual, mas segue lifecycle de
Shell e nao herda politica de game loop;
- fechar um Shell VM-backed retorna ao Hub em v1;
- background execution real fica fora de escopo;
- no host desktop, `Esc` e a tecla principal para solicitar Home/SystemOS e a
tecla fisica `Home` pode existir como alias;
- a acao Home/SystemOS e interceptada pelo host/SystemOS e nao entra no pad
logico visivel ao Game;
- `Paused` e o estado/evento cooperativo visivel ao Game;
- `Suspended` e o estado operacional imposto pelo OS/scheduler;
- ao sair do foreground, o OS notifica o Game para pausar e concede um budget
curto de reacao;
- se o Game nao reagir ao pause dentro do budget, o OS suspende a VM mesmo
assim;
- ao retornar, o OS reativa a VM, notifica o Game para resume/foreground
restore e permite que o Game sincronize antes de voltar ao gameplay;
- input pendente do Game e drenado/limpo nas fronteiras de pause/resume;
- audio do Game pausa junto com a VM em v1;
- retorno ao Game deve manter Hub/Shell visivel ate a primeira render submission
valida do Game retomado;
- render ownership muda junto com o foreground owner e invalida submissions
antigas via epoch/generation;
- firmware observa transicoes macro; OS observa lifecycle completo; VM observa
pause/resume; host observa owner/render epoch e estado de apresentacao.
## Criterio para Encerrar
A agenda pode ser encerrada quando tivermos uma decisao clara sobre:
- cardinalidade de Games e Shells residentes/foreground;
- semantica de Game pausado/suspenso;
- politica de execucao para Shell VM-backed durante Game pausado;
- regra de foreground visual owner e render invalidation;
- comportamento minimo do ciclo `Game -> Shell -> Game`;
- itens explicitamente fora de escopo, especialmente background execution real.
## Discussao
- 2026-06-05: Agenda criada a partir da `DSC-0040`, quando o caso de Shell VM-backed aberto sobre um Game pausado mostrou que a discussao pertence ao lifecycle/SystemOS, nao apenas ao render worker.
- 2026-07-03: Direcao provisoria aceita para as perguntas 2-10:
Game deve receber evento de pausa com budget curto antes da suspensao; Hub e
Shell root/especial; Shell VM-backed pode assumir foreground visual, mas Hub
permanece como owner raiz/back-stack; fechar Shell VM-backed retorna ao Hub em
v1; input do Game deve ser drenado/limpo em pause/resume; audio do Game pausa
junto com VM em v1; apenas um Game pausado residente e permitido; retorno ao
Game deve manter Hub/Shell visivel ate a primeira submission valida; firmware
ve transicoes macro, OS ve lifecycle completo, VM ve pause/resume, host ve
owner/render epoch e estado de apresentacao.
- 2026-07-03: Pergunta 1 permanece aberta para esclarecer se `Paused` e
`Suspended` sao estados distintos, nomes para camadas diferentes, ou se v1
deve expor somente um deles.
- 2026-07-03: Direcao proposta para pergunta 1: `Paused` e o estado/evento
cooperativo visivel ao Game; `Suspended` e o estado operacional imposto pelo
OS. Ao sair do foreground, o OS notifica o Game para pausar e concede um
budget curto de reacao; se o Game nao reagir, o OS suspende a VM mesmo assim.
Ao retornar, o OS notifica o Game antes de recoloca-lo no foreground visual,
permitindo sincronizacao/revalidacao. O Game nao controla a suspensao, mas
pode observar `pause`/`resume` para ajustar seu estado interno.
@@ -1,145 +0,0 @@
---
id: AGD-0044
ticket: system-os-cartridge-switch-orchestrator
title: SystemOS Cartridge Switch Orchestrator
status: open
created: 2026-07-03
resolved:
decision:
tags: [runtime, os, lifecycle, game, cartridge, architecture]
---
## Contexto
A `AGD-0041` cobre o caso `Game -> Home/Shell -> mesmo Game`: o usuario sai do
foreground do jogo, o SO assume a tela, Shell/Hub pode rodar, e depois o mesmo
Game e retomado.
Existe um segundo caso, diferente, que nao deve ser escondido dentro da
`AGD-0041`: `Game A -> Home -> Game B`.
Nesse fluxo, o usuario esta com um Game rodando, aperta Home, volta para o SO e
pede para iniciar outro jogo. O SystemOS nao deve simplesmente chamar um loader
por cima do estado atual. Ele precisa orquestrar a substituicao do app corrente:
fechar ou descartar o Game residente, limpar estado cartridge-scoped, resolver o
novo alvo, carregar o proximo cartucho e entrar no novo estado de firmware.
Essa agenda tambem se relaciona com a `AGD-0003 / system-run-cart`: `run_cart`,
se existir, nao e userland e nao e o orquestrador. O carregador de cartucho e
apenas uma etapa dentro de uma transicao comandada pelo SystemOS.
## Problema
Sem um orquestrador explicito de troca de cartucho no SystemOS, a plataforma
pode cair em estados incoerentes:
- carregar um novo Game sem fechar corretamente o Game anterior;
- reaproveitar estado VM, assets, input, audio, render ou telemetria do cartucho
anterior;
- misturar boot direto por linha de comando com troca de app sob o SO;
- deixar o loader decidir lifecycle, quando ele deveria apenas materializar o
cartucho alvo;
- tentar implementar `Home -> outro Game` antes de existir o contrato de
foreground/pausa definido pela `AGD-0041`.
## Pontos Criticos
- Esta agenda deve ser executada depois da `AGD-0041`.
- `Game -> Home -> mesmo Game` fica fora desta agenda.
- O SystemOS deve ser a autoridade da troca entre cartuchos sob o SO.
- O loader nao deve possuir politica de fechamento, pausa, foreground ou
cleanup.
- Boot direto por CLI/debug continua sendo caminho separado e mais simples.
- A troca para outro Game deve tratar falha de load sem deixar o sistema em
estado parcialmente substituido.
- `.pmc`, catalogo completo e UX final de launcher continuam fora de escopo,
salvo se forem necessarios para definir o contrato minimo.
## Opcoes
### Opcao A - Adiar tudo para depois da AGD-0041
- **Abordagem:** manter esta agenda como registro de escopo futuro; primeiro
fechar e implementar o contrato `Game -> Home -> mesmo Game`.
- **Pro:** evita misturar pausa/resume com substituicao de cartucho; reduz risco
de reabrir arquitetura durante a `AGD-0041`.
- **Contra:** a plataforma continua sem troca `Home -> outro Game` ate uma etapa
posterior.
- **Manutenibilidade:** alta, porque cada agenda fecha um eixo de lifecycle.
### Opcao B - Definir agora o contrato conceitual, implementar depois
- **Abordagem:** fechar uma decisao curta ja dizendo que o orquestrador pertence
ao SystemOS, que `run_cart` nao e userland, e que a execucao depende da
`AGD-0041`; o plano de codigo fica para depois.
- **Pro:** reduz ambiguidade enquanto trabalhamos na `AGD-0041`.
- **Contra:** pode produzir uma decisao com pouca evidencia operacional antes
do contrato de foreground estar fechado.
- **Manutenibilidade:** boa se a decisao for claramente marcada como dependente
da `AGD-0041`.
### Opcao C - Implementar o orquestrador completo agora
- **Abordagem:** tentar resolver `Game A -> Home -> Game B` antes ou junto da
`AGD-0041`.
- **Pro:** ataca o fluxo final diretamente.
- **Contra:** mistura pausa/resume, fechamento, cleanup, resolucao de alvo e
falha de load em uma unica frente; alto risco de contrato instavel.
- **Manutenibilidade:** baixa para v1, porque a troca completa depende do
contrato de foreground ainda aberto.
## Sugestao / Recomendacao
Recomendo a Opcao A agora, com esta agenda aberta como marcador explicito de
escopo futuro.
A ordem preferida passa a ser:
1. fechar a `AGD-0041` para definir foreground, pausa/suspensao, Shell no
foreground e retorno ao mesmo Game;
2. voltar para esta agenda e decidir o contrato do orquestrador de troca de
cartucho no SystemOS;
3. so entao planejar a execucao de `Game A -> Home -> Game B`.
Se durante a `AGD-0041` aparecer uma decisao que exige antecipar parte do
orquestrador, esta agenda deve ser reaberta/atualizada com a dependencia
concreta em vez de esconder a troca de cartucho dentro da agenda de foreground.
## Perguntas em Aberto
- [ ] Depois da `AGD-0041`, qual estado representa um Game que sera descartado
em vez de retomado?
- [ ] O fechamento do Game atual e observavel para o firmware/game, ou e uma
destruicao interna do SystemOS?
- [ ] Quais estados cartridge-scoped devem ser limpos antes do novo load: VM,
assets, FS handles, input, audio, render ownership, telemetry, logs?
- [ ] Se o novo cartucho falha ao carregar, o sistema volta ao Home, mostra uma
tela de erro, ou tenta preservar o Game anterior?
- [ ] Como a resolucao do novo alvo e representada sem depender de catalogo
completo ou `.pmc`?
- [ ] Qual evidencia minima prova `Game A -> Home -> Game B` sem depender de UX
final de launcher?
## Criterio para Encerrar
A agenda pode virar decisao quando:
- a `AGD-0041` tiver fechado o contrato de foreground/pausa/resume;
- estiver claro que o orquestrador pertence ao SystemOS;
- `run_cart`/loader estiver limitado a etapa interna, nao userland;
- existir regra para fechar/descartar o Game atual;
- existir contrato de limpeza de estado cartridge-scoped;
- existir politica para falha de carregamento do novo Game;
- houver criterio de teste minimo para `Game A -> Home -> Game B`.
## Discussao
- 2026-07-03: Agenda criada a partir da separacao entre `AGD-0041`
(`Game -> Home -> mesmo Game`) e `AGD-0003` (`run_cart`/loader nao userland).
O novo escopo cobre a troca posterior `Game A -> Home -> Game B`, com
orquestracao pelo SystemOS depois que o contrato de foreground estiver
fechado.
## Resolution
Ainda em aberto.
@@ -1,186 +0,0 @@
---
id: AGD-0046
ticket: foreground-stack-game-pause-shell-vm-backed
title: VM Context Ownership for Resident Game and VM-Backed Shell
status: accepted
created: 2026-07-04
resolved:
decision: DEC-0038
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
---
## Contexto
`DEC-0037` define que o v1 deve suportar o fluxo `Game -> Home/Shell -> same
Game`, com o Game residente pausado/suspenso enquanto Hub ou Shell possuem o
foreground. A implementacao atual ja impede que Shell nativo ticke o Game
suspenso, porque Shell nativo nao usa a VM.
A lacuna aparece quando o Shell tambem eh VM-backed. Hoje `Firmware` possui um
unico `VirtualMachine` global (`Firmware.vm`). O Game residente e um Shell
VM-backed competem por esse mesmo contexto. Se o Shell VM-backed inicializa uma
nova cartridge nesse objeto, ele sobrescreve o contexto do Game que deveria
permanecer residente/suspenso.
Isso significa que o modelo de foreground/task/process ja avancou, mas o modelo
de contexto VM ainda esta acoplado ao firmware global.
## Problema
Precisamos decidir onde vive o contexto de execucao VM quando existem, ao mesmo
tempo, um Game residente suspenso e um Shell VM-backed foreground.
O problema nao eh apenas pausar ticks. Para coexistencia real, cada VM-backed
process precisa preservar seu proprio estado: PC, stack, heap, globals,
cartridge identity, runtime services escopados, render ownership metadata e
eventos lifecycle pendentes.
Enquanto `Firmware.vm` for unico, "suspender" um Game VM nao preserva o
contexto se outra cartridge VM-backed for carregada.
## Pontos Criticos
- `DEC-0037` diz que um Game suspenso nao recebe ticks/input/frame pacing, mas
continua residente para voltar ao mesmo Game.
- Shell nativo nao precisa de VM context proprio, mas Shell VM-backed precisa.
- `SystemOS` ja eh autoridade de lifecycle/process/task, entao eh candidato
natural para possuir ou localizar contextos VM por sessao.
- `Firmware` deve orquestrar macro estados, mas nao deveria ser dono unico do
contexto de todos os processos VM-backed.
- `VirtualMachineRuntime` contem estado atualmente misto: identidade da
cartridge atual, render manager, lifecycle delivery, fs/memcard/open handles
e telemetria. Precisamos separar o que eh global do OS do que eh por sessao
VM-backed.
- A solucao deve preservar a restricao v1: no maximo um Game residente e no
maximo um Shell foreground. Ela nao deve abrir multitasking geral.
- Game-to-Game switching continua fora desta agenda e pertence a `DSC-0043`.
## Opcoes
### Opcao A - Manter VM global no Firmware e bloquear Shell VM-backed com Game residente
- **Abordagem:** documentar que Shell VM-backed nao pode abrir enquanto um Game
VM esta residente; apenas Shell nativo coexiste com Game suspenso.
- **Pro:** menor implementacao imediata.
- **Contra:** contradiz a intencao de coexistencia de VM-backed Shell em
`DEC-0037` e deixa a arquitetura incompleta.
- **Manutenibilidade:** baixa, porque o sistema teria regras diferentes para
Shell nativo e Shell VM-backed sem uma fronteira clara de sessao.
### Opcao B - Serializar o Game VM ao suspender e restaurar ao resumir
- **Abordagem:** ao suspender Game, extrair snapshot do `VirtualMachine` e do
runtime associado; ao resumir, restaurar snapshot depois do Shell VM-backed.
- **Pro:** preserva a ideia de um unico VM executor ativo.
- **Contra:** exige serializacao profunda e correta de todo o estado VM/runtime,
incluindo handles, assets, render state e side effects. Isso eh muito mais
complexo que a necessidade v1.
- **Manutenibilidade:** baixa a media; snapshots viram contrato dificil e
fragil antes de termos necessidade de hibernacao real.
### Opcao C - Tornar o contexto VM propriedade da sessao/processo VM-backed
- **Abordagem:** cada processo VM-backed possui seu proprio `VirtualMachine` e
seu contexto runtime VM-scoped. O scheduler/firmware seleciona qual sessao
recebe tick conforme foreground/lifecycle. Game suspenso simplesmente deixa
de ser tickado, mas seu contexto permanece armazenado na sessao Game.
- **Pro:** alinha com task/process/lifecycle, suporta Game residente + Shell
VM-backed sem sobrescrever contexto, e prepara o terreno para futuras sessoes
sem implementar multitasking geral agora.
- **Contra:** exige separar estado hoje concentrado em `Firmware.vm` e
`SystemOS.vm_runtime`, decidindo o que eh global do OS e o que eh por sessao.
- **Manutenibilidade:** alta, porque a posse do contexto acompanha o processo
que executa a VM.
### Opcao D - Criar apenas dois slots VM fixos: Game VM e Shell VM
- **Abordagem:** manter um slot `game_vm` e um slot `shell_vm`, em vez de uma VM
por processo/sessao.
- **Pro:** mais simples que uma tabela geral de sessoes.
- **Contra:** codifica uma limitacao acidental. Ainda precisariamos decidir
ownership, runtime scoped state e lifecycle por slot. Pode virar refactor
duplo quando mais de um Shell ou Game switching aparecer.
- **Manutenibilidade:** media; aceitavel como stepping stone somente se modelado
internamente como sessao, nao como campos especiais permanentes.
## Sugestao / Recomendacao
Seguir a Opcao C: contexto VM deve pertencer a uma sessao/processo VM-backed,
nao ao `Firmware` global.
Para v1, a implementacao pode continuar limitada a uma sessao Game residente e
uma sessao Shell foreground, mas o modelo deve ser "session-owned VM context".
Isso permite que Shell VM-backed rode enquanto o Game fica suspenso sem perder
PC/stack/heap/estado runtime.
O firmware deve deixar de possuir a VM como estado global de todos os apps e
passar a pedir ao SystemOS/runtime scheduler o contexto VM ativo para o owner
foreground. `SystemOS` deve continuar sendo a autoridade de lifecycle; o
runtime deve separar estado VM-scoped de estado global de OS/render/telemetria
conforme necessario.
## Perguntas em Aberto
- [ ] Qual objeto deve representar a sessao VM-backed: `Process`, novo
`VmSession`, ou uma tabela separada ligada a `ProcessId`/`TaskId`?
- [ ] Quais campos de `VirtualMachineRuntime` sao por sessao VM-backed e quais
devem permanecer globais em `SystemOS`?
- [ ] O render manager fica global por foreground owner ou dentro de cada
contexto VM com handoff global?
- [ ] Handles de FS, memcard, assets e open files devem ser por sessao,
por app_id, ou globais com namespace por processo?
- [ ] Como `LoadCartridgeStep` deve mudar: criar sessao VM nova, ativar sessao
existente, ou delegar tudo para uma facade de sessions?
- [ ] Como preservar os testes e invariantes de `DEC-0037` durante a migracao
incremental sem abrir multitasking geral?
- [ ] Como processos background-capable, como um player de musica, entram no
modelo sem confundir foreground visual ownership com elegibilidade de
execucao?
- [ ] Cada Shell VM-backed deve ter uma VM propria, mesmo quando existe mais de
um Shell em memoria no futuro?
## Criterio para Encerrar
Esta agenda pode virar decision quando definirmos:
- o proprietario canonico do contexto VM;
- a fronteira entre estado VM-scoped e estado global do OS;
- como firmware seleciona/ticka a sessao VM ativa;
- como Game residente suspenso e Shell VM-backed foreground coexistem;
- quais restricoes v1 permanecem explicitamente fora de escopo.
## Discussion
- 2026-07-04: Aberta a partir da observacao de que Shell nativo coexiste com
Game suspenso, mas Shell VM-backed ainda conflita com o `Firmware.vm` unico.
- 2026-07-04: Discussao adicional separou foreground ownership de background
execution. A recomendacao atual eh que todo processo VM-backed tenha sua
propria `VmSession`; processos background-capable devem ser modelados como
sessoes com classe/politica de scheduling propria, nao como foreground owners.
## Resolution
Resolvido em 2026-07-04:
- O modelo deve seguir a Opcao C: todo processo VM-backed deve possuir uma
`VmSession` propria, ligada ao lifecycle/task/process, em vez de depender de
um `Firmware.vm` global.
- Cada Shell VM-backed deve ter sua propria sessao VM. Ele pode compartilhar a
engine/runtime e caches imutaveis, mas nao stack, heap, PC, globals, handles
ou identidade mutavel de execucao.
- O Game residente suspenso preserva seu contexto porque sua `VmSession`
continua viva; ele apenas deixa de ser elegivel para ticks normais enquanto
Hub/Shell possui foreground.
- Foreground ownership e background execution sao conceitos separados.
Foreground ownership decide input visual, render ownership e frame pacing
normal. Execution eligibility decide quais sessoes podem receber ticks sem
serem foreground.
- Background execution, como player de musica ou background services, nao entra
na primeira implementacao desta agenda. Mesmo assim, o modelo de `VmSession`
deve ser obrigatoriamente compativel com essa evolucao em um futuro proximo.
- Render ownership permanece autoridade global do SystemOS. Sessoes VM-backed
produzem frames, mas nao decidem se podem apresentar.
- `LoadCartridgeStep` nao deve inicializar uma VM global diretamente. Ele deve
delegar criacao/ativacao de sessao para uma facade de sessions/scheduler.
Esta agenda esta pronta para virar decision normativa.
@@ -0,0 +1,208 @@
---
id: AGD-0048
ticket: background-service-audio-execution
title: Agenda - Background Service and Audio Execution
status: open
created: 2026-07-05
resolved:
decision:
tags: [runtime, os, lifecycle, service, audio, background, architecture]
---
# Agenda - Background Service and Audio Execution
## Contexto
O runtime ja tem sinais claros de preparacao para multitarefa controlada:
- `TaskState::Background` existe como estado de tarefa;
- `VmSession` separa estado mutavel de VM por tarefa/processo;
- `SystemOS` e dono de lifecycle, task/process, VM sessions, filesystem,
memcard, windows e logging;
- a spec de eventos separa foreground ownership de execution eligibility;
- o contrato atual declara que execucao real em background fica fora do v1, mas
o modelo foi desenhado para permitir servicos ou processos de midia no futuro.
O caso motivador e:
```text
Game foreground -> Home -> music player -> escolher musica -> voltar ao Game
```
Depois disso, o Game deve voltar ao foreground enquanto o player continua
executando e produzindo audio junto com audio do Game.
## Problema
Hoje o runtime preserva sessoes, mas nao tem contrato para uma sessao continuar
executando quando nao e foreground.
Os pontos atuais que bloqueiam o caso:
- `TaskKind` so distingue `Game` e `Shell`;
- `ProcessKind` so distingue `VmGame`, `VmShell` e `NativeShell`;
- `ProcessState` nao possui estado normativo de background-running;
- `GameRunningStep` ticka apenas o Game foreground;
- `ShellRunningStep` ticka apenas o Shell foreground;
- `HubHomeStep` nao ticka sessoes VM em background;
- `Audio` e `AudioMixer` usam vozes globais sem namespace por tarefa/sessao;
- cada logical frame chama `platform.audio_mut().clear_commands()`, o que torna
perigoso tickar dois produtores de audio no mesmo frame;
- pausa de lifecycle hoje emite `MasterPause`, afetando o mixer inteiro.
Sem uma decisao, background service pode virar apenas "tickar mais uma VM", mas
isso quebraria isolamento, audio, debugger, lifecycle e previsibilidade.
## Pontos Criticos
1. **Execution eligibility nao e foreground.**
O contrato atual ja separa os conceitos, mas a implementacao ainda so ticka o
owner foreground. Precisamos introduzir uma politica explicita de quem pode
executar em background.
2. **Servico nao e Shell escondido.**
Um music player pode ter UI de Shell para escolher musica, mas a reproducao
continua como servico quando a UI deixa o foreground. Fechar isso como
`Shell` em background confundiria janela, tarefa, sessao e servico.
3. **Audio precisa de origem.**
Hoje `voice_id` e global no mixer. Se Game e player usam `voice_id = 0`, um
sobrescreve o outro. Precisamos decidir se o mixer tera namespaces por
`AudioOwner`, se servicos terao pool dedicado, ou se o player nao usara a
mesma superficie `audio.*`.
4. **Pausa de Game nao pode pausar servico de midia.**
`MasterPause` global serve para o contrato atual de pausa/debug, mas nao
expressa "pausar Game audio e manter music player". Pausa precisa virar
escopo por origem ou politica de mixer.
5. **Servico precisa de lifecycle proprio.**
Deve existir contrato para start, foreground UI, background-running, stop,
crash, terminate, recurso negado, e talvez wake/resume de UI.
6. **Budget e determinismo precisam ser fechados.**
Se servicos rodam junto com Game, precisamos decidir cota por frame, ordem de
ticks, starvation, crash isolation, e se background service participa do
mesmo tempo deterministico da maquina.
7. **Sistema de apps precisa descobrir e lancar o player.**
Hoje Home lista Game cartridges e tem Shells nativos fixos. O caso de music
player exige decidir se ele e cartridge `System`, app instalado, Shell nativo,
ou novo perfil `Service`.
## Opcoes
### Opcao A - Background Service como novo tipo de processo/sessao
Criar contrato explicito para `Service`:
- `TaskKind::Service` ou entidade equivalente;
- `ProcessKind::VmService` / `NativeService`;
- execution eligibility independente de foreground;
- UI de controle opcional via Shell task associada ao servico;
- audio com origem por service/session;
- lifecycle proprio: start, background, foreground-control, stop, crash.
**Pros:**
- modela diretamente music player e futuros servicos;
- preserva a separacao entre UI foreground e execucao;
- evita transformar Shell em "processo que tambem e daemon";
- facilita quotas, permissao e observabilidade.
**Contras:**
- maior mudanca arquitetural;
- exige novo contrato em specs, SystemOS, firmware, audio e testes;
- precisa fechar politica de recursos antes de implementar.
**Manutencao:**
- melhor base para crescer com qualidade, desde que o MVP seja pequeno.
### Opcao B - Shell em background com audio permitido
Permitir que uma VM Shell continue tickando quando sai do foreground e use audio
normalmente.
**Pros:**
- reaproveita Shell, WindowManager e VM session existentes;
- menor numero de novos tipos no curto prazo.
**Contras:**
- mistura UI e servico;
- torna `TaskState::Background` semantico antes de definir `ProcessState`;
- abre precedente para qualquer Shell continuar executando;
- nao resolve sozinho namespace de audio, pause por origem, quotas e debugging.
**Manutencao:**
- atraente como atalho, mas tende a espalhar excecoes pela firmware state
machine.
### Opcao C - Audio player como servico nativo OS-owned, sem VM background
Implementar music player como servico nativo de SystemOS, controlado por uma
Shell UI. A reproducao continua no host/OS sem tickar VM em background.
**Pros:**
- entrega o caso de musica com menor risco para scheduler VM;
- evita abrir execucao arbitraria de background agora;
- audio service pode ser projetado como recurso OS-owned e depois exposto.
**Contras:**
- nao resolve background VM services em geral;
- player deixa de ser app userland completo no primeiro ciclo;
- precisa ainda fechar origem/mixagem de audio e relacao com UI.
**Manutencao:**
- bom MVP se o objetivo imediato for media playback, mas deve ser declarado como
`media service` nativo, nao como contrato geral de background VM.
## Sugestao / Recomendacao
Recomendo fechar em duas camadas:
1. **Decisao de arquitetura:** introduzir o conceito de service/background
execution como contrato de SystemOS, separado de foreground Shell e Game.
Essa decisao deve definir execution eligibility, lifecycle, quotas, crash
policy, controle de UI e relacao com VM sessions.
2. **MVP de media:** implementar primeiro um `media/audio service` com escopo
reduzido, preferencialmente OS-owned ou `Service` bem delimitado, antes de
permitir background VM arbitrario.
Para excelente qualidade, o primeiro plano nao deve tentar "qualquer app em
background". O alvo deve ser: um unico servico de audio/midia, com origem de
audio propria, controle por Hub/Shell, execucao enquanto Game esta foreground,
e testes end-to-end de mistura e lifecycle.
## Perguntas em Aberto
- O music player deve ser um cartridge `System`, um novo `Service`, ou um
servico nativo do OS controlado por Shell?
- A UI do player e a reproducao pertencem a mesma tarefa ou a tarefas
separadas?
- Um servico pode ter janela foreground temporaria e continuar sem janela?
- Quantos servicos background podem existir no MVP: um media service ou N
servicos?
- O background service recebe ticks todo frame, tick rate reduzido, ou apenas
eventos?
- O audio mixer deve isolar vozes por `TaskId`, `ProcessId`, `VmSessionId`,
`AppId`, ou novo `AudioOwner`?
- Como pausar apenas o audio do Game durante Home/debug sem pausar musica?
- O debugger inspeciona foreground session apenas ou tambem sessoes background?
- Como crash de servico e exibido: toast/log, janela de crash, ou parada
silenciosa com diagnostico?
- Que capacidades sao necessarias para media service: `audio`, `fs`, `asset`,
talvez `background_audio`?
## Criterio para Encerrar
Esta agenda pode virar decisao quando houver resposta escrita para:
- modelo de entidade (`Service` novo vs Shell background vs native OS service);
- execution eligibility e ordem de ticks;
- lifecycle e estados de task/process;
- ownership/namespace de audio e politica de pausa por origem;
- relacao entre UI foreground do player e reproducao background;
- escopo do MVP e explicitamente o que fica fora;
- testes obrigatorios de lifecycle, audio mixing, crash isolation e regressao do
contrato Game/Home/Shell existente.
@@ -0,0 +1,138 @@
---
id: AGD-0050
ticket: portable-host-backend-strategy
title: Portable Host Backend Strategy
status: open
created: 2026-07-14
resolved:
decision:
tags: [host, desktop, portable, sdl, backend, rendering, input, audio, linux, android, handheld]
---
## Contexto
O runtime ja tem uma fronteira de host relativamente clara: o host desktop atual vive em `crates/host/prometeu-host-desktop-winit`, usando `winit`, `pixels` e `cpal` para janela, apresentacao de framebuffer, input e audio.
A direcao desejada nao e substituir esse host de forma disruptiva no primeiro corte. A proposta e estudar e construir um segundo host portatil para servir como runtime host em handhelds e consoles portateis, especialmente hardwares chineses que rodam Linux internamente e, em alguns casos, Android customizado. O mesmo host tambem deve servir como base para uma futura versao DIY do hardware, desde que ela rode sobre um Linux base compatível. SDL e a hipotese principal, mas a agenda tambem deve avaliar outras familias de host/backend antes de virar decisao normativa.
Esse novo host deve conviver com o host atual durante estabilizacao, mas nao e descartavel: ele e candidato a se tornar o host principal quando provar paridade e estabilidade.
A troca deve ficar isolada no dominio de host: contratos de runtime, firmware, frame, input semantico e audio semantico nao devem mudar por causa da escolha de backend. Essa separacao e justamente o objetivo arquitetural que permite que um host portatil evolua para principal sem arrastar o runtime.
## Problema
Hoje a existencia de um unico host desktop torna dificil separar problemas do runtime de problemas do adaptador de plataforma. Um novo host portatil pode ajudar em testes, portabilidade, comparacao operacional e reducao de dependencia de uma pilha unica de janela/render/audio. O alvo "mobile" desta agenda nao significa telefone/tablet como produto primario; significa hardware portatil dedicado, geralmente com controles fisicos, framebuffer/display integrado, Linux customizado e distribuicao fora do modelo desktop tradicional. O alvo tambem inclui um possivel handheld DIY futuro, em que o valor esperado e ja existir um host pronto se o dispositivo expuser um Linux base suficiente.
O risco e tratar uma tecnologia especifica como resposta antes de comparar os requisitos reais de Linux handheld e Android. A agenda precisa cravar o modelo de host paralelo em estabilizacao, com destino de host principal, e entao escolher a familia de backend que melhor atende esse objetivo.
## Pontos Criticos
- A troca de host deve ser simples e local ao host, sem exigir mudancas em runtime, firmware, asset protocol, render packet, VM ou syscalls.
- O novo host precisa consumir as mesmas saidas canonicas do runtime: frames RGBA8888, comandos semanticos de audio e eventos de input normalizados.
- A estrategia deve preservar o host `winit` enquanto o novo host ainda nao provar equivalencia operacional, mas o novo host e candidato a virar o host principal depois dessa prova.
- O alvo primario e portabilidade operacional para handhelds Linux e consoles portateis com controles fisicos; Android customizado e um alvo possivel que deve influenciar a escolha de API, packaging e input/audio.
- O host portatil deve ser viavel em um futuro hardware DIY rodando Linux base, sem exigir um runtime especial ou fork de contratos.
- Testes devem distinguir contrato comum de host de detalhes especificos de backend.
- SDL2 pode ter ecossistema Rust mais estabelecido; SDL3 pode estar mais alinhado com a direcao upstream. A escolha da versao e uma pergunta separada da decisao de criar um segundo host.
- A arquitetura deve evitar duplicar logica de runtime loop, pacing, debugger, stats e presentation policy quando essa logica for comum a qualquer host.
- Outras familias de host tambem devem ser avaliadas: evoluir `winit`, SDL2/SDL3, backend Android nativo, ou uma camada multiplataforma alternativa.
## Opcoes
### Opcao A - Manter apenas o host winit atual
- **Abordagem:** continuar evoluindo `prometeu-host-desktop-winit` como unico host desktop.
- **Pro:** menor custo imediato; evita nova dependencia nativa.
- **Con:** mantem a pilha de plataforma unica como ponto de acoplamento pratico.
- **Tradeoff:** bom para estabilidade curta, fraco para provar independencia real do host.
### Opcao B - Migrar diretamente do host winit para outro backend
- **Abordagem:** substituir o host desktop atual por um novo backend portatil assim que a escolha tecnologica for feita.
- **Pro:** reduz a manutencao para um unico host depois da migracao.
- **Con:** aumenta risco de regressao e mistura decisao de backend com mudanca operacional.
- **Tradeoff:** so faz sentido depois de prova local de superioridade e paridade, o que ainda nao existe.
### Opcao C - Criar um host SDL paralelo com destino de principal
- **Abordagem:** adicionar um novo crate/binario de host SDL que implemente os mesmos contratos externos do host atual, mantendo `winit` como referencia e rollback ate haver evidencia de equivalencia.
- **Pro:** permite teste A/B, reduz risco, valida se a fronteira de host esta realmente limpa, atende a meta de handheld Linux/Android customizado/DIY e preserva caminho para tornar SDL o host principal.
- **Con:** aumenta temporariamente manutencao e exige fatorar partes comuns se houver duplicacao.
- **Tradeoff:** melhor caminho para chegar a um host principal portatil sem reabrir runtime.
### Opcao D - Evoluir winit/pixels/cpal como host portatil
- **Abordagem:** manter a familia atual e investir em configuracao, input, fullscreen, packaging e compatibilidade de Linux handheld/Android/DIY dentro dela.
- **Pro:** reaproveita o host existente e reduz dependencias nativas novas.
- **Con:** pode nao resolver os problemas praticos de distribuicao, gamepad/device handling, fullscreen/scaling, Android customizado e ambientes handheld.
- **Tradeoff:** forte se a pilha atual suportar bem os alvos; fraco se o problema real for portabilidade operacional.
### Opcao E - Host Android nativo separado
- **Abordagem:** tratar Linux handheld e Android como hosts diferentes: SDL ou winit para Linux; Android com camada nativa/propria quando o alvo amadurecer.
- **Pro:** permite respeitar o ciclo de vida, packaging, input e audio do Android sem contaminar o host Linux.
- **Con:** duplica mais superficie e adia a promessa de um host portatil unico.
- **Tradeoff:** bom se Android tiver requisitos proprios demais; ruim se SDL conseguir cobrir Android bem o bastante.
### Opcao F - Camada multiplataforma alternativa
- **Abordagem:** avaliar alternativas como uma camada Rust-first ou game-framework-level para janela, input, audio e render.
- **Pro:** pode reduzir FFI nativa e integrar melhor com Cargo.
- **Con:** pode ser menos madura para Linux handheld/Android real, packaging e controles.
- **Tradeoff:** deve ser considerada, mas precisa provar vantagem concreta sobre SDL para justificar risco.
## Sugestao / Recomendacao
Recomendacao inicial: manter a **Opcao C** como favorita, mas ampliar a fase de agenda para comparar SDL com as demais familias de host antes da decisao. O resultado desejado continua sendo um segundo host portatil, inicialmente paralelo, com destino explicito de se tornar o host principal quando atingir paridade e estabilidade.
O caminho recomendado e:
1. Definir o contrato minimo de equivalencia entre hosts: janela, framebuffer RGBA8888, input, audio, pacing, debugger/logs e encerramento.
2. Identificar o que e comum ao host e o que e backend especifico.
3. Comparar as familias candidatas contra esse contrato: SDL2, SDL3, winit atual evoluido, Android nativo separado e alternativas Rust-first.
4. Implementar o candidato escolhido como novo crate/binario sem remover `prometeu-host-desktop-winit`.
5. Permitir troca simples por binario/comando/feature, mantendo o runtime cego para a escolha.
6. Tratar handheld Linux como alvo primario de produto para esse host; tratar Android customizado e DIY Linux como restricoes de desenho quando afetarem backend, packaging, input, audio ou boot/runtime integration.
7. Promover o novo host a principal apenas depois de evidencia de estabilidade e paridade.
## Perguntas em Aberto
- [ ] A primeira implementacao SDL deve usar SDL2 ou SDL3?
- [ ] SDL deve ser a familia escolhida, ou winit evoluido, Android nativo separado ou outra camada oferece melhor caminho?
- [ ] A selecao do host deve ser por binario separado, feature Cargo, parametro CLI, ou combinacao desses mecanismos?
- [ ] Qual e o menor conjunto de comportamento que define paridade aceitavel com o host winit?
- [ ] Quais partes do host atual devem virar modulo comum antes do SDL, e quais devem ser duplicadas primeiro para evitar abstracao prematura?
- [ ] O host SDL deve reutilizar `cpal` para audio inicialmente ou usar audio SDL desde o primeiro corte?
- [ ] Quais familias de hardware handheld Linux devem ser usadas como referencia inicial?
- [ ] Handheld Linux exige controles/gamepad, fullscreen, scaling, latency, sleep/resume, framebuffer/display mode ou packaging especificos desde o primeiro corte?
- [ ] Qual e o "Linux base" minimo que um futuro hardware DIY precisaria expor para rodar o host portatil sem fork?
- [ ] Android customizado deve ser criterio de escolha entre SDL2 e SDL3 agora, ou deve ficar como compatibilidade futura?
- [ ] Como validar input e pacing de forma automatizada sem depender de janela real em CI?
- [ ] O nome do crate deve ser `prometeu-host-desktop-sdl`, `prometeu-host-desktop-sdl2`, ou algo neutro a versao?
## Criterio para Encerrar
A agenda pode virar decision quando estiver claro:
- se o novo host sera paralelo em estabilizacao, com destino de host principal;
- qual familia de backend sera alvo inicial;
- se SDL for escolhido, qual versao SDL sera alvo inicial;
- como a selecao/troca de host deve funcionar;
- quais contratos sao comuns e proibidos de mudar;
- quais requisitos minimos de handheld Linux e possivel Android customizado entram no primeiro plano;
- qual contrato minimo de Linux base mantem aberta a opcao de hardware DIY;
- qual evidencia minima prova paridade suficiente para iniciar planos de implementacao.
## Discussion
Ponto inicial aceito pelo usuario: a intencao e ter um segundo host para testes, com troca simples e facil, aproveitando o trabalho ja feito para isolar essa troca no host sem envolver runtime ou outros dominios.
Atualizacao de escopo: o novo host nao e descartavel. O objetivo e servir como runtime host para sistemas Linux rodando em consoles portateis e hardwares handheld chineses, e possivelmente Android customizado. Assim que estiver estavel, ele deve poder virar o host principal.
Atualizacao de escopo: outras familias de host/backend tambem devem viver nesta agenda. SDL segue como hipotese forte, mas a decisao deve comparar opcoes antes de cravar a tecnologia.
Clarificacao: "mobile" nesta agenda nao se refere primariamente a telefone/tablet. O foco sao dispositivos portateis dedicados com Linux interno ou Android customizado, geralmente com controles fisicos e ambiente de distribuicao proprio.
Clarificacao: a agenda tambem deve preservar a opcao de um futuro hardware DIY. A premissa desejada e que, se esse hardware expuser um Linux base suficiente, o runtime ja tenha um host portatil pronto para rodar nele.
## Resolution
@@ -1,191 +0,0 @@
---
id: DEC-0037
ticket: foreground-stack-game-pause-shell-vm-backed
title: Foreground Stack and Game Pause Contract
status: accepted
created: 2026-07-03
ref_agenda: AGD-0041
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
---
## Status
Accepted.
## Contexto
`AGD-0041` defines the minimum lifecycle contract for `Game -> Home/Shell ->
same Game`.
The issue is not only rendering. The render worker needs a single valid visual
owner, but SystemOS must decide which VMs may exist, which owner receives input,
which owner may tick, what happens to a Game when Home takes foreground, and how
a VM-backed Shell app coexists with a paused Game.
This decision builds on:
- `DSC-0031`: runtime mode separation between Game and System/Shell;
- `DSC-0032`: SystemOS lifecycle/process/task authority;
- `DSC-0035`: task-owned Shell windows and Shell liveness;
- `DSC-0036`: Hub/Shell as a lifecycle proving surface;
- `DSC-0040`: render ownership/epoch and stale submission invalidation.
## Decisao
PROMETEU MUST use a single-foreground-owner model for v1.
At most one Game MAY be resident at a time. At most one Shell app MAY be the
foreground visual owner at a time.
The Hub MUST be treated as the root/special Shell owner for Home. A VM-backed
Shell app MAY replace the Hub as the foreground visual owner, but the Hub
remains the root/back-stack controller. In v1, closing a VM-backed Shell app
MUST return to Hub/Home, not directly to the Game.
When the user requests Home while a Game is running, SystemOS MUST start a
cooperative pause transition:
- the Game receives a pause lifecycle notification;
- the Game is given a short bounded budget to react;
- after that budget, SystemOS MAY suspend the Game VM even if the Game did not
cooperate;
- the Game remains resident but MUST NOT receive normal gameplay ticks, normal
game input, or frame pacing while suspended;
- the Shell/Hub foreground owner MAY execute according to Shell lifecycle rules.
`Paused` is the Game-visible lifecycle state/event. `Suspended` is the
OS/scheduler operational state. A Game may observe pause/resume, but it MUST NOT
control whether the OS suspends or resumes its VM.
When returning to the same Game, SystemOS MUST reactivate the Game VM and send a
resume or foreground-restore lifecycle notification before restoring visual
foreground. The Game MAY remain internally paused while it synchronizes. The
system MUST keep Hub/Shell visible until the resumed Game produces a valid new
render submission for the current ownership epoch.
Input pending for the Game MUST be drained or cleared across pause/resume
boundaries. Game audio MUST pause with the Game VM in v1. Independent background
audio policy is out of scope.
Render ownership MUST move with the foreground owner. Foreground transitions
MUST invalidate stale render submissions through ownership epoch/generation so
old Game frames cannot be presented after Shell takes foreground, and old Shell
frames cannot be presented after the Game resumes.
On the desktop host, `Esc` MUST be the primary keyboard request for Home/SystemOS.
The physical `Home` key MAY be supported as an alias. This Home request is a
host/SystemOS control action and MUST NOT be exposed as a normal guest pad
button or userland input capability.
Real background execution, multiple resident Games, multiple foreground Shells,
Game-to-Game switching, Shell app persistence policy, memory eviction policy,
and rich multitasking are out of scope for this decision.
## Rationale
The chosen model preserves the expected console-like flow: a Game can be
paused, Home can run, Shell apps can open, and the same Game can resume without
turning the runtime into a general multitasking scheduler.
Separating `Paused` from `Suspended` keeps authority clear. `Paused` is the
contract the Game can observe and react to. `Suspended` is the OS mechanism that
prevents the paused Game from continuing to consume ticks, input, audio, and
render ownership while another owner is foreground.
Keeping Hub as root/back-stack prevents VM-backed Shell apps from becoming
independent lifecycle roots. Returning to Hub before resuming Game keeps v1
navigation deterministic and leaves more complex direct-return behavior for a
future decision.
Keeping Hub/Shell visible until the Game submits a new valid frame avoids
presenting stale pixels from the previous Game epoch. This aligns lifecycle
state with the render ownership model from `DSC-0040`.
Using `Esc` as desktop Home makes the control available on compact keyboards.
Supporting the physical `Home` key as an alias is acceptable, but the portable
contract cannot depend on it.
## Invariantes / Contrato
- There is exactly one foreground visual owner at a time.
- V1 supports at most one resident Game.
- V1 supports at most one foreground Shell app.
- Hub/Home is the root Shell owner and back-stack controller.
- VM-backed Shell apps follow Shell lifecycle, not Game loop lifecycle.
- A paused Game may remain resident, but a suspended Game does not receive
normal gameplay ticks, normal game input, or frame pacing.
- Pause/resume are cooperative Game-visible lifecycle events.
- Suspend/resume scheduling authority belongs to SystemOS.
- SystemOS may suspend a Game after the pause budget even if the Game does not
cooperate.
- Input is cleared or barriered across Game pause/resume boundaries.
- Game audio pauses with the Game VM in v1.
- Foreground transitions advance render ownership epoch/generation.
- Visual foreground returns to Game only after a valid current-epoch Game render
submission exists.
- Desktop `Esc` is a host/SystemOS Home request; physical `Home` may alias it.
- Home/SystemOS is not a guest pad button and is not userland input.
- Background execution and general multitasking are explicitly excluded.
## Impactos
- **Spec:** runtime lifecycle, firmware/Hub, input, and render ownership specs
must document foreground ownership, pause/suspend semantics, Home key mapping,
and stale frame invalidation.
- **Runtime / SystemOS:** SystemOS needs explicit foreground owner, Hub root,
Shell foreground, Game paused, and Game suspended state.
- **VM:** VM execution must support pause/resume lifecycle delivery and OS-owned
suspension of ticks.
- **Firmware:** firmware should observe macro transitions such as GameRunning,
Hub/Home, Shell foreground, pause request, and resume request without owning
every internal OS detail.
- **Host:** host must route desktop `Esc` and optional physical `Home` to a
SystemOS Home request instead of guest pad input.
- **Input:** Game input must be drained or barriered during pause/resume and
Home/SystemOS must stay outside the guest-visible pad ABI.
- **Audio:** v1 audio follows Game pause/suspend and does not continue as
independent background audio.
- **Renderer:** render publication must reject stale submissions after ownership
epoch changes and keep previous foreground visible until the resumed Game
publishes a valid current-epoch frame.
- **Tests:** coverage must prove pause budget behavior, non-foreground VM
non-execution, input clearing, host Home routing, Shell return-to-Hub, and
stale render rejection.
## Alternativas Descartadas
- **Terminate Game when entering Shell:** rejected because it makes
`Game -> Shell -> Game` a reload rather than a pause/resume flow.
- **Real background execution now:** rejected because it pulls in scheduler,
budget, energy, audio, input, IO, memory, and persistence policy beyond v1.
- **Multiple resident Games:** rejected for v1 because Game-to-Game switching is
owned by `DSC-0043 / AGD-0044`.
- **Expose Home as guest input:** rejected because Home changes system
foreground authority and must not be handled as ordinary game input.
- **Return directly from Shell app to Game in v1:** rejected to keep Hub as the
deterministic root/back-stack owner.
## Referencias
- Source agenda: `AGD-0041`
- Runtime mode separation: `DSC-0031`
- SystemOS lifecycle authority: `DSC-0032`
- Shell task/window lifecycle: `DSC-0035`
- Hub UI direction: `DSC-0036`
- Render ownership and stale submission handling: `DSC-0040`
- Future Game A -> Home -> Game B switching: `DSC-0043 / AGD-0044`
## Propagacao Necessaria
- Update canonical runtime specs for foreground ownership and pause/suspend.
- Specify desktop Home request mapping in host/input documentation.
- Add plan(s) for SystemOS foreground stack state and Game pause/suspend.
- Add plan(s) for VM lifecycle event delivery and forced suspension budget.
- Add plan(s) for host `Esc`/`Home` routing outside guest pad input.
- Add plan(s) for render epoch integration during Game/Shell transitions.
- Add tests covering lifecycle, input, host routing, and render publication
invariants.
## Revision Log
- 2026-07-03: Initial decision from `AGD-0041`.
@@ -1,199 +0,0 @@
---
id: DEC-0038
ticket: foreground-stack-game-pause-shell-vm-backed
title: VM Session Ownership for VM-Backed Processes
status: accepted
created: 2026-07-04
ref_agenda: AGD-0046
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
---
## Status
Open for review.
## Contexto
`DEC-0037` established the foreground stack and Game pause contract for
`Game -> Home/Shell -> same Game`. It requires a suspended resident Game to stop
receiving normal gameplay ticks, input, and frame pacing while remaining
resident for later resume.
The current implementation works for native Shell apps because native Shell
apps do not use the VM. It does not fully support VM-backed Shell coexistence:
`Firmware` owns a single global `VirtualMachine` (`Firmware.vm`), so loading a
VM-backed Shell can overwrite the suspended Game context that should remain
resident.
`AGD-0046` closes this gap by separating VM execution context ownership from
foreground ownership. A foreground owner decides who receives visual/input
authority. A VM execution context decides where PC, stack, heap, globals,
handles, cartridge identity, lifecycle delivery state, and VM-scoped runtime
state live.
## Decisao
PROMETEU MUST make VM execution context session-owned for VM-backed processes.
Every VM-backed process MUST have its own `VmSession` or equivalent
session-owned context. A VM-backed Game and a VM-backed Shell MUST NOT share the
same mutable `VirtualMachine` instance, stack, heap, PC, globals, open handles,
cartridge identity, or VM-scoped lifecycle state.
`Firmware.vm` MUST NOT remain the canonical owner of all VM-backed app context.
Firmware MAY continue to orchestrate macro states such as loading, Home, Shell,
and GameRunning, but it MUST delegate VM session creation, activation, lookup,
and ticking to SystemOS/session services.
For v1, the system MAY still enforce:
- at most one resident Game;
- at most one foreground Shell;
- no Game-to-Game switching;
- no general background execution.
Those restrictions MUST NOT be implemented by relying on a single global VM
context. They must be expressed as lifecycle/session policy.
Each VM-backed Shell MUST receive its own VM session. If future Shell
persistence allows more than one Shell app to remain in memory, each retained
VM-backed Shell MUST still have distinct mutable VM context.
A suspended resident Game MUST preserve its VM session. Suspension means the
session is not eligible for normal foreground ticks, normal Game input, or
normal frame pacing. It does not mean serializing, deleting, or overwriting the
VM context.
Foreground ownership and execution eligibility MUST be separate concepts:
- foreground ownership controls visual owner, primary input, render ownership,
and normal foreground frame pacing;
- execution eligibility controls which sessions may receive ticks or restricted
callbacks while not foreground.
Background execution, including music players or background services, is out of
scope for the first implementation of this decision. However, the session model
MUST be compatible with adding background-capable scheduling soon. The initial
model MUST NOT bake in assumptions that only the foreground session can ever be
eligible to execute.
Render ownership MUST remain a global SystemOS authority. VM sessions may
produce render submissions, but they MUST NOT decide whether those submissions
can be presented. SystemOS/render ownership policy remains responsible for
active owner, epoch/generation validity, stale submission rejection, and final
publication authority.
`LoadCartridgeStep` MUST stop initializing a global firmware VM directly as the
long-term model. Cartridge load/activation MUST be delegated to a sessions or
VM-session facade that can create a new VM session, activate an existing VM
session, or reject an unsupported transition according to lifecycle policy.
## Rationale
The foreground stack is already task/process-oriented. VM execution context must
follow the same ownership model. Otherwise the system can mark a Game as
resident and suspended while the only real VM context has already been reused
for a Shell.
Session ownership solves the actual coexistence problem without requiring VM
snapshot/restore. A suspended Game is simply a live session that is not scheduled
for normal ticks. A VM-backed Shell is another session with its own mutable
state.
Keeping background execution out of the first implementation avoids expanding
this work into a general scheduler. At the same time, making execution
eligibility separate from foreground ownership prevents an immediate future
background audio/player feature from requiring another foundational refactor.
Keeping render ownership global preserves the contract from `DEC-0037` and the
render ownership model from `DSC-0040`: sessions can generate frames, but only
the current foreground/render owner can publish valid current-epoch output.
## Invariantes / Contrato
- VM-backed mutable execution state is owned by a VM session, not by a global
firmware VM.
- A VM-backed Game and VM-backed Shell never share mutable VM context.
- A suspended resident Game retains its VM session.
- Suspension prevents normal foreground Game ticks/input/frame pacing; it does
not destroy or overwrite VM state.
- Native Shell apps do not require VM sessions.
- VM-backed Shell apps always require VM sessions.
- Each VM-backed Shell gets its own mutable VM session.
- Foreground ownership and execution eligibility are distinct.
- General background execution is out of scope for the initial implementation,
but the model must support adding it without replacing session ownership.
- SystemOS remains lifecycle and render ownership authority.
- Render ownership and stale frame rejection remain global policy, not per-VM
session policy.
- Cartridge load/activation must go through session services rather than
initializing one global firmware VM.
- V1 restrictions on one resident Game and one foreground Shell remain policy,
not a consequence of single-VM storage.
## Impactos
- **Runtime / SystemOS:** add a VM session model or equivalent service that
stores VM-backed process execution context and maps it to task/process
lifecycle.
- **Firmware:** remove `Firmware.vm` as the canonical VM context owner for all
apps. Firmware should request session creation/activation/tick from SystemOS.
- **VM:** support multiple distinct `VirtualMachine` instances or equivalent
isolated VM contexts in one OS lifetime.
- **Lifecycle:** task/process states must control session scheduling
eligibility without conflating foreground ownership with future background
execution.
- **Hub / Shell:** VM-backed Shell load must create or activate a Shell VM
session without overwriting a resident Game session.
- **Game:** Game pause/suspend/resume must preserve the Game VM session and
deliver lifecycle events to that session.
- **Renderer:** render manager stays global and validates ownership/epoch for
submissions produced by sessions.
- **FS / Memcard / Assets:** mutable handles and per-app runtime handles must
be evaluated for session scoping. Durable memcard/app data can remain keyed by
`app_id`; open handles and staging state should not accidentally leak across
sessions.
- **Tests:** add coverage proving VM-backed Shell creation does not overwrite a
suspended Game session, and that only eligible sessions tick.
## Alternativas Descartadas
- **Keep one global firmware VM and block VM-backed Shell when a Game is
resident:** rejected because it leaves `DEC-0037` incomplete and creates
divergent Shell behavior.
- **Serialize/snapshot the Game VM on suspension:** rejected because snapshot
correctness is harder than needed for v1 and would include VM, handles,
render state, assets, and side effects.
- **Hard-code two VM slots (`game_vm`, `shell_vm`):** rejected as a permanent
model because it encodes a short-term limit as architecture. It may only be
acceptable as an internal stepping stone if represented through the same
session abstraction.
- **Treat background-capable apps as hidden foreground owners:** rejected
because it would violate foreground ownership semantics and make render/input
authority ambiguous.
## Referencias
- Source agenda: `AGD-0046`
- Foreground stack and Game pause contract: `DEC-0037`
- Runtime mode separation: `DSC-0031`
- SystemOS lifecycle/process/task authority: `DSC-0032`
- VM render parallel execution boundary: `DSC-0040`
- Future Game-to-Game switching: `DSC-0043`
## Propagacao Necessaria
- Add implementation plans for introducing VM sessions and moving VM context
out of `Firmware`.
- Add implementation plans for separating VM-scoped runtime state from global
SystemOS/render state.
- Update runtime/firmware specs to describe session-owned VM context and the
distinction between foreground ownership and execution eligibility.
- Update tests for Game resident suspension, VM-backed Shell creation, and
session isolation.
- Keep future background execution as out of scope for first implementation,
but document that the model must support background-capable scheduling.
## Revision Log
- 2026-07-04: Initial decision draft from `AGD-0046`.
@@ -1,96 +0,0 @@
---
id: PLN-0136
ticket: foreground-stack-game-pause-shell-vm-backed
title: Route Desktop Home Key Outside Guest Input
status: done
created: 2026-07-03
ref_decisions: [DEC-0037]
tags: [host, input, systemos, keyboard, lifecycle]
---
## Briefing
`DEC-0037` makes desktop `Esc` the primary Home/SystemOS request and allows the
physical `Home` key as an alias. This request must be intercepted by the
host/SystemOS and must not appear as a guest pad button or input intrinsic.
This plan adds the host input route for the Home request without changing the
guest-visible pad surface.
## Decisions of Origin
- `DEC-0037` - Foreground Stack and Game Pause Contract.
## Target
Route desktop `Esc` and optional physical `Home` key to a SystemOS Home request
outside `InputSignals`.
## Scope
- Extend `crates/host/prometeu-host-desktop-winit/src/input.rs` or a nearby
host input module with a host/system control signal separate from
`prometeu_hal::InputSignals`.
- Map `KeyCode::Escape` to Home/SystemOS request.
- Map `KeyCode::Home` as an alias.
- Ensure neither key mutates `start_signal`, `select_signal`, or any pad field.
- Route the request through `crates/host/prometeu-host-desktop-winit/src/runner.rs`
into firmware/SystemOS.
- Add tests proving `Esc` and `Home` do not affect guest pad state.
## Out of Scope
- No pause/resume lifecycle implementation.
- No render ownership gating.
- No guest-visible Home button.
- No gamepad hardware Home mapping unless a future plan defines controller
system controls separately.
## Execution Plan
1. Define host control state.
Add a small host-only type such as `HostSystemControls` with a
`home_requested` edge or event. Store it in `HostInputHandler` or in the
runner next to the existing input handler.
2. Update keyboard handling.
In `HostInputHandler::handle_event`, recognize `KeyCode::Escape` and
`KeyCode::Home` on press. Set the host control event and return without
modifying `InputSignals`.
3. Preserve pad mapping.
Keep existing pad mappings unchanged:
arrows, `A/D/W/S`, `Q/E`, `Z`, and Shift. Do not reuse `Start` or `Select`
for Home.
4. Route to firmware/SystemOS.
In `crates/host/prometeu-host-desktop-winit/src/runner.rs`, consume the
host Home event before or during `about_to_wait` and call the firmware or
SystemOS method introduced by `PLN-0137` / `PLN-0140`.
5. Add tests.
Add host input tests for `Esc`, physical `Home`, and existing pad mappings.
Tests must prove Home produces a system event and no guest pad mutation.
## Acceptance Criteria
- Pressing desktop `Esc` emits a Home/SystemOS host control event.
- Pressing physical `Home` emits the same event.
- Neither key affects `InputSignals`.
- Existing guest pad keyboard mappings still work.
- The runner consumes the Home request as a system action.
- The implementation does not add a guest syscall, intrinsic, or pad button.
## Tests / Validation
- Add unit tests in `prometeu-host-desktop-winit` for host input mapping.
- Run `cargo test -p prometeu-host-desktop-winit input`.
- Run `cargo test -p prometeu-hal input` if pad signal behavior changes.
- Run `discussion validate`.
## Risks
- `Esc` may conflict with debugger or window-close expectations. Keep debugger
start handling on `D` unchanged and do not map `Esc` to process exit.
- Physical `Home` is not available on every keyboard, so it must remain an
alias rather than the primary portable mapping.
@@ -1,116 +0,0 @@
---
id: PLN-0137
ticket: foreground-stack-game-pause-shell-vm-backed
title: Implement SystemOS Foreground Stack State
status: done
created: 2026-07-03
ref_decisions: [DEC-0037]
tags: [runtime, os, lifecycle, foreground, shell, game]
---
## Briefing
`DEC-0037` requires SystemOS to own foreground authority. The system must know
which owner is foreground, keep Hub/Home as root, allow only one resident Game,
allow only one foreground Shell, and return from VM-backed Shell apps to Hub in
v1.
This plan implements the SystemOS state model only. It does not yet deliver
Game pause/resume events, host keyboard routing, or render/audio/input boundary
changes.
## Decisions of Origin
- `DEC-0037` - Foreground Stack and Game Pause Contract.
## Target
Add an explicit SystemOS foreground stack model that can represent Hub, a
foreground Shell task, and a paused/suspended resident Game.
## Scope
- Add or extend SystemOS-owned foreground state under
`crates/console/prometeu-system/src/os/` or
`crates/console/prometeu-system/src/services/`.
- Represent v1 foreground owners:
- Hub/Home root;
- Shell task foreground;
- Game foreground;
- Game paused/suspended resident.
- Enforce at most one resident Game and at most one foreground Shell.
- Keep Hub as root/back-stack controller.
- Ensure Shell close returns to Hub/Home in v1.
- Expose focused queries through existing or new facades, likely
`crates/console/prometeu-system/src/os/facades/lifecycle.rs` and
`crates/console/prometeu-system/src/os/facades/sessions.rs`.
## Out of Scope
- No VM pause/resume event delivery.
- No host `Esc`/`Home` keyboard mapping.
- No render epoch implementation.
- No Game-to-Game switching.
- No background execution.
- No memory eviction for the resident Game.
## Execution Plan
1. Define foreground model types.
Add enums/structs for foreground owner and resident Game state in the most
local SystemOS module. The model must distinguish Game foreground, Game
paused/suspended, Hub foreground, and Shell task foreground.
2. Add SystemOS storage.
Store the foreground model in `SystemOS` from
`crates/console/prometeu-system/src/os/system_os.rs` with initialization to
Hub/Home root.
3. Wire lifecycle facade operations.
Extend lifecycle/session facades so firmware can request:
- set Game foreground;
- request Home from Game;
- set Shell foreground from Hub;
- close Shell and return to Hub;
- query current foreground owner;
- query resident Game task.
4. Enforce cardinality.
Add checks that reject a second resident Game and a second foreground Shell
with typed lifecycle errors. Use existing `LifecycleError` style or add
precise variants.
5. Integrate existing Shell close behavior.
Update `crates/console/prometeu-firmware/src/firmware/firmware_step_shell_running.rs`
only where needed so closing a Shell task routes through the foreground model
and ends in `FirmwareState::HubHome`.
6. Add tests.
Cover initial Hub foreground, Game foreground registration, Home request
moving Game to resident paused/suspended state, Shell foreground activation,
Shell close returning to Hub, and cardinality rejection.
## Acceptance Criteria
- SystemOS has an explicit foreground owner model.
- Hub/Home is the initialized root foreground owner.
- Only one resident Game can exist in v1.
- Only one Shell task can be foreground in v1.
- VM-backed Shell close returns to Hub/Home.
- Foreground queries are available to firmware and later plans.
- No implementation path enables background execution.
## Tests / Validation
- Add focused unit tests in `prometeu-system` around the new model and facade.
- Run `cargo test -p prometeu-system lifecycle foreground`.
- Run `cargo test -p prometeu-firmware shell`.
- Run `discussion validate`.
## Risks
- Existing `TaskState::Foreground` and `TaskState::Suspended` may look like the
complete model. Do not overload them until foreground ownership and Hub root
authority are explicit.
- Shell windows already have focus semantics. Keep window focus as visual/task
evidence, not the sole source of SystemOS foreground truth.
@@ -1,114 +0,0 @@
---
id: PLN-0138
ticket: foreground-stack-game-pause-shell-vm-backed
title: Specify Foreground Pause and Home Contract
status: done
created: 2026-07-03
ref_decisions: [DEC-0037]
tags: [runtime, specs, lifecycle, input, renderer, foreground]
---
## Briefing
`DEC-0037` establishes the v1 foreground stack contract: one foreground visual
owner, one resident Game, one foreground Shell, Hub as root, Game-visible
pause/resume, OS-owned suspension, desktop `Esc` as Home/SystemOS request, and
render epoch invalidation across foreground transitions.
This plan updates the canonical runtime specs before implementation so code
plans cannot drift into guest-owned Home input, background execution, or stale
frame presentation.
## Decisions of Origin
- `DEC-0037` - Foreground Stack and Game Pause Contract.
## Target
Document the foreground, pause/suspend, Home request, input, audio, and render
ownership contract in the canonical runtime specs.
## Scope
- Update `docs/specs/runtime/12-firmware-pos-and-prometeuhub.md` with:
- Hub as root/special Shell owner;
- one foreground visual owner;
- one resident Game;
- one foreground Shell;
- `Game -> Home/Shell -> same Game` lifecycle;
- VM-backed Shell app return-to-Hub behavior.
- Update `docs/specs/runtime/06-input-peripheral.md` with:
- Home/SystemOS as host/system control, not pad input;
- desktop `Esc` as primary Home request;
- physical `Home` key as optional alias;
- input clear/barrier requirements across Game pause/resume.
- Update `docs/specs/runtime/09-events-and-concurrency.md` with:
- pause notification budget;
- OS-owned suspension after the budget;
- resume/foreground-restore notification before visual return.
- Update `docs/specs/runtime/14-boot-profiles.md` only to clarify that this
foreground contract is not Game-to-Game switching and does not change direct
`--run` or `--games-root` boot semantics.
- Update renderer-related spec text in the most local existing runtime spec if
present, otherwise add a short subsection to `12-firmware-pos-and-prometeuhub.md`
describing ownership epoch invalidation and first-valid-frame gating.
## Out of Scope
- No Rust implementation.
- No new guest ABI or pad button.
- No background execution policy.
- No Game A -> Home -> Game B switching.
- No memory eviction policy for resident Games.
## Execution Plan
1. Edit `12-firmware-pos-and-prometeuhub.md`.
Define foreground owner cardinality, Hub root ownership, Shell foreground
behavior, Game resident/suspended behavior, return-to-Hub from Shell, and the
requirement to keep Hub/Shell visible until a resumed Game submits a valid
current-epoch frame.
2. Edit `06-input-peripheral.md`.
State that Home/SystemOS is outside the guest-visible pad and input
intrinsic surface. Document desktop `Esc` as the primary host mapping and
physical `Home` as an optional alias.
3. Edit `09-events-and-concurrency.md`.
Add the pause/resume event ordering: Home request, pause notification,
bounded reaction budget, OS suspension, resume/foreground-restore
notification, first-valid-frame visual return.
4. Edit `14-boot-profiles.md`.
Cross-reference the foreground contract and explicitly keep direct boot,
games-root Home launch, and future Game-to-Game switching separate.
5. Run text checks.
Search for wording that implies Home is a guest input button, a guest ABI, or
background execution. Replace misleading text with the `DEC-0037` contract.
## Acceptance Criteria
- Specs define `Paused` as Game-visible and `Suspended` as OS-owned.
- Specs state that desktop `Esc` is the primary Home request and is not guest
pad input.
- Specs state that the Game receives pause/resume notifications but does not
control OS suspension.
- Specs state that Hub is the root Shell owner and Shell app close returns to
Hub in v1.
- Specs state that visual return to Game waits for a valid current-epoch render
submission.
- Specs explicitly exclude background execution and Game-to-Game switching.
## Tests / Validation
- Run `discussion validate`.
- Run `rg -n "Home|Esc|Suspended|Paused|foreground|background execution" docs/specs/runtime`.
- Verify no edited spec describes Home/SystemOS as a guest-visible pad button.
## Risks
- The spec could accidentally reopen Game-to-Game switching; keep that scoped to
`DSC-0043 / AGD-0044`.
- The input spec could confuse physical keyboard mapping with VM input; keep
host/system controls outside the guest input surface.
@@ -1,106 +0,0 @@
---
id: PLN-0139
ticket: foreground-stack-game-pause-shell-vm-backed
title: Validate Game Home Shell Game End To End
status: done
created: 2026-07-03
ref_decisions: [DEC-0037]
tags: [runtime, validation, firmware, host, lifecycle]
---
## Briefing
`DEC-0037` is not complete until the product flow is proven end to end:
a Game runs, the user requests Home, the Game is paused/suspended, Hub or a
VM-backed Shell takes foreground, closing Shell returns to Hub, and the same
Game can resume only after a valid current-epoch frame exists.
This plan adds final validation after the spec, SystemOS, VM, host input, and
render/audio/input boundary plans are implemented.
## Decisions of Origin
- `DEC-0037` - Foreground Stack and Game Pause Contract.
## Target
Prove the complete `Game -> Home/Shell -> same Game` lifecycle and prevent
regressions around guest input, foreground authority, and stale rendering.
## Scope
- Add integration-style tests for:
- Game running to Home request;
- pause notification and forced suspension;
- Hub foreground while Game is resident;
- VM-backed Shell foreground while Game is suspended;
- Shell close returning to Hub;
- resume request returning to same Game;
- first-valid-frame visual restore;
- host `Esc`/`Home` not entering guest input.
- Add manual smoke instructions for desktop host.
- Confirm direct `--run` and games-root Home launch remain separate.
## Out of Scope
- No new implementation beyond tests and developer-facing validation notes.
- No Game A -> Home -> Game B switching.
- No performance tuning.
- No polished UI.
## Execution Plan
1. Add firmware/SystemOS integration tests.
Use the most stable existing seams in `crates/console/prometeu-firmware/src/firmware/firmware.rs`
and `crates/console/prometeu-system` tests to drive Game foreground, Home
request, Shell foreground, Shell close, and Game resume.
2. Add host input integration tests.
Ensure `Esc` and physical `Home` create a host Home event and do not mutate
guest `InputSignals`.
3. Add render publication validation.
Assert stale submissions from the pre-pause Game epoch are rejected after
Home takes foreground and that the Game is not visually restored until a new
current-epoch submission exists.
4. Add audio/input boundary validation.
Assert Game input is cleared or barriered across pause/resume. Assert Game
audio pause follows Game suspension.
5. Add direct boot and games-root regression checks.
Ensure direct `--run <cart>` remains independent from Home request handling
and that games-root Home launch still enters the Game path.
6. Document manual smoke commands.
Add or update developer-facing spec text with release-mode commands:
- `cargo run --release -p prometeu-host-desktop-winit -- --run test-cartridges/stress-console`
- `cargo run --release -p prometeu-host-desktop-winit -- --games-root test-cartridges`
Include the expected `Esc -> Home -> Shell -> Hub -> resume Game` behavior
once implemented.
## Acceptance Criteria
- Automated tests cover `Game -> Home -> same Game`.
- Automated tests cover `Game -> Home -> Shell -> Hub -> same Game`.
- Tests prove Home request is host/SystemOS control, not guest pad input.
- Tests prove suspended Game does not tick.
- Tests prove stale render submissions are not presented.
- Tests prove visual return waits for a current-epoch Game frame.
- Direct `--run` and games-root Home launch regressions pass.
## Tests / Validation
- Run `cargo test -p prometeu-system`.
- Run `cargo test -p prometeu-firmware`.
- Run `cargo test -p prometeu-host-desktop-winit`.
- Run any targeted render worker tests affected by ownership epoch changes.
- Run `discussion validate`.
## Risks
- The current test seams may not expose enough host-driven lifecycle behavior.
If needed, add narrow test-only helpers rather than testing through sleeps or
real-time window loops.
- End-to-end validation can become flaky if it depends on wall-clock timing.
Use deterministic ticks and explicit state transitions.
@@ -1,110 +0,0 @@
---
id: PLN-0140
ticket: foreground-stack-game-pause-shell-vm-backed
title: Deliver Game Pause Resume and Suspension
status: done
created: 2026-07-03
ref_decisions: [DEC-0037]
tags: [runtime, os, vm, lifecycle, pause, suspension]
---
## Briefing
`DEC-0037` separates Game-visible `Paused` from OS-owned `Suspended`. When Home
is requested during Game execution, SystemOS must notify the Game, give it a
short bounded budget, then suspend the VM even if the Game does not cooperate.
When returning, SystemOS must reactivate the VM and send a resume or
foreground-restore notification before the visual owner returns to Game.
This plan implements the pause/resume and suspension mechanics after the
foreground state model exists.
## Decisions of Origin
- `DEC-0037` - Foreground Stack and Game Pause Contract.
## Target
Add Game pause/resume lifecycle delivery and OS-enforced VM suspension for the
same resident Game.
## Scope
- Add a Game lifecycle event model for pause and resume/foreground-restore.
- Add a bounded pause reaction budget owned by SystemOS.
- Suspend the Game VM after the budget even if the Game does not cooperate.
- Ensure a suspended Game receives no normal gameplay ticks.
- Reactivate the VM and deliver resume/foreground-restore before Game visual
foreground restoration.
- Integrate with `GameRunningStep` and VM runtime tick control.
## Out of Scope
- No render first-valid-frame gating; that is in `PLN-0141`.
- No host keyboard routing; that is in `PLN-0136`.
- No new guest syscall.
- No background execution.
- No Game-to-Game switching.
## Execution Plan
1. Add lifecycle event representation.
Define pause/resume events in the most local runtime lifecycle module,
likely under `crates/console/prometeu-system/src/os/lifecycle.rs` or a new
SystemOS lifecycle submodule. Events must be observable by the VM/runtime
path without giving the Game authority over suspension.
2. Add pause transition state.
Extend the foreground state from `PLN-0137` with a `PauseRequested` or
equivalent transition state that records the target Game task and the
remaining pause budget.
3. Gate VM ticks.
Update `crates/console/prometeu-firmware/src/firmware/firmware_step_game_running.rs`
and `crates/console/prometeu-system/src/services/vm_runtime/tick.rs` so a
suspended Game does not receive normal ticks, normal input, or frame pacing.
4. Deliver pause notification.
Add the mechanism that makes the pause event visible to the running Game
before suspension. Use an existing VM event channel if present; otherwise add
a narrow lifecycle-event queue owned by SystemOS/VM runtime.
5. Enforce the budget.
Advance the pause budget on firmware ticks. When it expires, transition the
Game task/process to suspended through SystemOS lifecycle regardless of Game
cooperation.
6. Deliver resume notification.
On return to the resident Game, transition from suspended to resume-requested,
reactivate VM execution, deliver resume/foreground-restore, and leave visual
restoration to the render boundary plan.
7. Add tests.
Cover cooperative pause, non-cooperative forced suspension, no tick while
suspended, resume notification delivery, and no Game-owned ability to cancel
OS suspension.
## Acceptance Criteria
- Game receives pause before suspension.
- SystemOS suspends after a bounded budget even if the Game does not cooperate.
- Suspended Game does not receive normal gameplay ticks.
- Resume/foreground-restore is delivered before visual return to Game.
- Game cannot prevent OS suspension through guest-visible behavior.
- Existing debugger pause behavior remains distinct from lifecycle suspension.
## Tests / Validation
- Add unit tests in `prometeu-system` for lifecycle transition state.
- Add firmware tests around `GameRunningStep` pause request and suspension.
- Add VM runtime tests proving suspended state suppresses normal ticks.
- Run `cargo test -p prometeu-system`.
- Run `cargo test -p prometeu-firmware`.
- Run `discussion validate`.
## Risks
- Debugger pause already exists in VM runtime. Keep debug pause separate from
lifecycle pause/suspend.
- A lifecycle event queue could become a general app event system. Keep this
plan limited to pause/resume required by `DEC-0037`.
@@ -1,104 +0,0 @@
---
id: PLN-0141
ticket: foreground-stack-game-pause-shell-vm-backed
title: Integrate Render Audio and Input Pause Boundaries
status: done
created: 2026-07-03
ref_decisions: [DEC-0037]
tags: [runtime, renderer, audio, input, foreground, lifecycle]
---
## Briefing
`DEC-0037` requires foreground transitions to invalidate stale render
submissions, keep Hub/Shell visible until the resumed Game publishes a valid
current-epoch frame, clear or barrier Game input across pause/resume, and pause
Game audio with the Game VM in v1.
This plan integrates those boundary effects after SystemOS foreground state and
Game pause/resume mechanics exist.
## Decisions of Origin
- `DEC-0037` - Foreground Stack and Game Pause Contract.
## Target
Make foreground transitions safe at the render, input, and audio boundaries.
## Scope
- Advance render ownership epoch/generation whenever foreground owner changes.
- Discard stale Game frames after Shell/Hub takes foreground.
- Discard stale Shell frames after Game resumes.
- Keep Hub/Shell visible until a resumed Game publishes a valid current-epoch
submission.
- Clear or barrier Game input across pause/resume boundaries.
- Pause Game audio with the Game VM in v1.
- Add telemetry/tests for stale discards and first-valid-frame gating.
## Out of Scope
- No independent background audio policy.
- No overlay rendering policy.
- No Game-to-Game switch rendering.
- No full memory eviction behavior.
## Execution Plan
1. Extend render ownership transition calls.
Update `crates/console/prometeu-system/src/services/vm_runtime/render_manager.rs`
and call sites in `tick.rs` so foreground owner changes explicitly advance
ownership epoch/generation, not only app mode/app id changes.
2. Add foreground restore gating.
Add state in SystemOS or firmware that records when visual return to Game is
pending. The state must remain in Hub/Shell presentation until a
current-epoch Game submission is observed.
3. Update host presentation selection.
Update `crates/host/prometeu-host-desktop-winit/src/runner.rs` if necessary
so `should_present_worker_frame` and fallback framebuffer presentation obey
the foreground restore gate.
4. Add stale discard coverage.
Extend render manager and render worker tests to prove stale submissions
from the previous owner are discarded after epoch change.
5. Add input boundary clearing.
Add a SystemOS or firmware input barrier when Game pause starts and when
Game resume starts. The barrier must prevent held or pressed Game input from
leaking across the lifecycle boundary.
6. Add audio pause integration.
Ensure Game pause/suspend produces the existing host audio pause command path
or a new explicit lifecycle audio pause signal. Keep this separate from
debugger pause if the observable cause matters in tests.
7. Add tests.
Cover stale frame discard, first-valid-frame visual return, input clearing,
and Game audio pause/resume behavior.
## Acceptance Criteria
- Foreground owner changes advance render ownership epoch/generation.
- Old Game frames cannot present after Hub/Shell takes foreground.
- Old Hub/Shell frames cannot present after Game resumes.
- Visual return to Game waits for a valid current-epoch Game submission.
- Game input does not leak across pause/resume boundaries.
- Game audio pauses with Game suspension in v1.
## Tests / Validation
- Run `cargo test -p prometeu-system render foreground`.
- Run `cargo test -p prometeu-firmware pause`.
- Run `cargo test -p prometeu-host-desktop-winit presentation`.
- Run `discussion validate`.
## Risks
- Existing render epoch logic may already key off app mode/app id. Foreground
owner changes must be explicit so Shell/Hub and resumed Game cannot share a
stale epoch by accident.
- Audio pause currently follows VM paused/debugger state in the host. Keep Game
lifecycle pause distinct enough that tests can prove the decision contract.
@@ -1,127 +0,0 @@
---
id: PLN-0142
ticket: foreground-stack-game-pause-shell-vm-backed
title: Deliver Game Lifecycle Events To VM Runtime
status: done
created: 2026-07-04
ref_decisions: [DEC-0037]
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
---
## Briefing
`DEC-0037` requires pause/resume to be Game-visible lifecycle events. The
current implementation records `GameLifecycleEvent` values in SystemOS, but no
runtime or VM execution path consumes them. Tests currently prove that the OS
queue contains events, not that the Game/runtime can observe them before
suspension or after resume.
## Objective
Deliver Game lifecycle pause/resume events from SystemOS into the VM runtime
boundary in a deterministic, testable way, without exposing Home as guest pad
input or a userland syscall.
## Dependencies
- Source decision: `DEC-0037`.
- Fixes the lifecycle event delivery gap found after `PLN-0140` and
`PLN-0141`.
- `PLN-0143` depends on this plan if it needs to prove that the pause event is
consumed before the pause budget expires.
## Scope
Included:
- Define the runtime-facing lifecycle event delivery API for `Pause` and
`ResumeForeground`.
- Move events from the SystemOS queue into the VM/runtime tick boundary.
- Make delivered events observable in tests without creating a broad app event
system.
- Preserve the distinction between lifecycle pause and debugger pause.
- Ensure events are delivered only to the resident Game task they target.
Excluded:
- No guest Home input, pad field, intrinsic, or syscall.
- No general userland event bus.
- No background execution while suspended.
- No new Shell lifecycle event model.
## Non-Goals
- Do not implement Game-to-Game switching.
- Do not change renderer ownership policy except where tests need to assert
lifecycle event ordering.
- Do not add wall-clock timers or asynchronous callbacks.
## Execution Method
1. Add a narrow VM runtime lifecycle inbox.
- What changes: introduce a small data structure for pending/delivered Game
lifecycle events in `VirtualMachineRuntime`.
- How it changes: add methods such as `queue_game_lifecycle_events`,
`take_delivered_game_lifecycle_events`, or a more idiomatic local name
that preserves deterministic frame-boundary delivery.
- File(s): `crates/console/prometeu-system/src/services/vm_runtime/mod.rs`,
`crates/console/prometeu-system/src/services/vm_runtime/tick.rs`, and
focused tests under `crates/console/prometeu-system/src/services/vm_runtime/`.
2. Route SystemOS events into the VM facade before ticking.
- What changes: `VmFacade::tick` must drain lifecycle events from SystemOS
and pass only events targeted at the currently running resident Game into
the VM runtime lifecycle inbox.
- How it changes: use the existing `LifecycleFacade::take_game_lifecycle_events`
or replace it with an equivalent internal method if borrowing requires a
cleaner API. Do not leave events only observable through
`pending_game_lifecycle_events`.
- File(s): `crates/console/prometeu-system/src/os/facades/vm.rs`,
`crates/console/prometeu-system/src/os/facades/lifecycle.rs`.
3. Expose deterministic test visibility.
- What changes: tests must be able to assert that `Pause` and
`ResumeForeground` reached the VM runtime boundary.
- How it changes: add test-only or public diagnostic accessors on
`VmFacade`/`VirtualMachineRuntime` for delivered lifecycle events, scoped
to lifecycle validation rather than a guest ABI.
- File(s): `crates/console/prometeu-system/src/os/facades/vm.rs`,
`crates/console/prometeu-system/src/services/vm_runtime/tests.rs`.
4. Update firmware tests to assert delivery, not only queue presence.
- What changes: existing firmware tests that inspect
`pending_game_lifecycle_events` should assert VM-runtime delivery at the
tick boundary.
- How it changes: after a Game pause/resume flow, verify that the VM/runtime
observed the lifecycle event in order.
- File(s): `crates/console/prometeu-firmware/src/firmware/firmware.rs`.
## Acceptance Criteria
- [ ] `Pause` is moved from SystemOS into the VM runtime boundary before
suspension is allowed to complete.
- [ ] `ResumeForeground` is moved into the VM runtime boundary before the Game
is considered visually restored.
- [ ] Tests fail if events remain only in `SystemOS.game_lifecycle_events`.
- [ ] Lifecycle event delivery does not mutate `InputSignals`.
- [ ] Debugger pause remains separate from lifecycle pause.
## Tests
- Unit tests in `prometeu-system` proving VM runtime lifecycle event delivery
and drain semantics.
- Firmware tests proving Home request delivers `Pause` to the VM/runtime before
suspension.
- Firmware tests proving resident Game resume delivers `ResumeForeground`
before Game foreground restoration.
- Run `cargo test -p prometeu-system`.
- Run `cargo test -p prometeu-firmware`.
- Run `discussion validate`.
## Affected Artifacts
- `crates/console/prometeu-system/src/os/facades/vm.rs`
- `crates/console/prometeu-system/src/os/facades/lifecycle.rs`
- `crates/console/prometeu-system/src/services/vm_runtime/mod.rs`
- `crates/console/prometeu-system/src/services/vm_runtime/tick.rs`
- `crates/console/prometeu-firmware/src/firmware/firmware.rs`
@@ -1,122 +0,0 @@
---
id: PLN-0143
ticket: foreground-stack-game-pause-shell-vm-backed
title: Guarantee Cooperative Pause Budget Tick Before Suspension
status: done
created: 2026-07-04
ref_decisions: [DEC-0037]
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
---
## Briefing
`DEC-0037` requires a Game-visible `Paused` event followed by a bounded
cooperative reaction budget before SystemOS imposes `Suspended`. The current
implementation uses a one-tick budget and advances it before `vm.tick` in
`GameRunningStep`, so the Game can be suspended without any runtime tick in
which it could observe or react to pause.
## Objective
Guarantee at least one deterministic VM/runtime delivery point for the Game to
observe pause before forced suspension, while preserving SystemOS authority to
suspend the Game after the budget.
## Dependencies
- Source decision: `DEC-0037`.
- Should be executed after or together with `PLN-0142`, because budget tests
must prove delivered lifecycle events, not only queued OS events.
## Scope
Included:
- Fix pause budget ordering so the pause budget cannot expire before the VM
runtime has a delivery point for `Pause`.
- Define the budget in deterministic machine ticks/frames, not wall-clock time.
- Ensure a Game receives no normal gameplay ticks after it reaches
`PausedSuspended`.
- Preserve the existing forced-suspension authority when the budget expires.
- Update tests that currently assert no VM tick occurs immediately after Home.
Excluded:
- No guest-controlled cancellation of suspension.
- No background execution after suspension.
- No extension of the pause budget based on host timing.
- No direct visual-return behavior; render restore gating remains covered by
the existing render boundary work.
## Non-Goals
- Do not add a general scheduler.
- Do not make pause cooperation mandatory for suspension.
- Do not conflate lifecycle pause with debugger pause.
## Execution Method
1. Redefine pause budget state transitions.
- What changes: `ResidentGameState::PauseRequested` must represent a state
in which one or more delivery ticks remain before `PausedSuspended`.
- How it changes: adjust `ForegroundStack::advance_pause_budget` or split it
into explicit methods such as `mark_pause_delivered` and
`advance_pause_budget_after_delivery`.
- File(s): `crates/console/prometeu-system/src/services/foreground.rs`.
2. Move budget advancement after lifecycle delivery.
- What changes: `GameRunningStep::on_update` must not suspend before the VM
runtime has a chance to receive and process the pause lifecycle event.
- How it changes: reorder the GameRunning update so the event delivery path
runs first, then the budget is advanced, and only a subsequent eligible
boundary can force suspension.
- File(s): `crates/console/prometeu-firmware/src/firmware/firmware_step_game_running.rs`,
`crates/console/prometeu-system/src/os/facades/vm.rs`.
3. Preserve no-tick-after-suspended behavior.
- What changes: once `ResidentGameState::PausedSuspended` and
`TaskState::Suspended` are reached, the Game must not receive normal ticks,
normal input, or frame pacing.
- How it changes: keep the existing early transition to Hub after suspension
expires, but ensure it occurs after the cooperative pause window rather
than before it.
- File(s): `crates/console/prometeu-firmware/src/firmware/firmware_step_game_running.rs`.
4. Update tests to match the corrected semantics.
- What changes: tests must stop asserting that the first tick after Home does
zero VM work purely because Home was requested.
- How it changes: assert that the pause event was delivered during the
cooperative window, then assert that a later deterministic tick forces
suspension and no further Game ticks occur.
- File(s): `crates/console/prometeu-firmware/src/firmware/firmware.rs`,
`crates/console/prometeu-system/src/os/system_os.rs`.
## Acceptance Criteria
- [ ] A Game receives a deterministic pause delivery point before SystemOS
suspends it.
- [ ] SystemOS still suspends the Game after the bounded budget even if the
Game does not cooperate.
- [ ] A suspended Game receives no normal gameplay ticks, normal Game input, or
frame pacing.
- [ ] Tests prove the order: Home request -> pause delivery -> budget expiry ->
suspension.
- [ ] Debugger pause behavior is unchanged.
## Tests
- Unit tests in `prometeu-system` for pause budget transitions.
- Firmware tests for non-cooperative forced suspension after at least one
delivered pause boundary.
- Regression tests proving suspended Game tick count does not advance.
- Run `cargo test -p prometeu-system foreground lifecycle`.
- Run `cargo test -p prometeu-firmware pause`.
- Run `discussion validate`.
## Affected Artifacts
- `crates/console/prometeu-system/src/services/foreground.rs`
- `crates/console/prometeu-system/src/os/facades/lifecycle.rs`
- `crates/console/prometeu-system/src/os/facades/vm.rs`
- `crates/console/prometeu-firmware/src/firmware/firmware_step_game_running.rs`
- `crates/console/prometeu-firmware/src/firmware/firmware.rs`
@@ -1,124 +0,0 @@
---
id: PLN-0144
ticket: foreground-stack-game-pause-shell-vm-backed
title: Suspend Resident Game When Shell Takes Foreground
status: done
created: 2026-07-04
ref_decisions: [DEC-0037]
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
---
## Briefing
`DEC-0037` says a suspended resident Game must not receive normal gameplay
ticks, normal Game input, or frame pacing while Hub/Shell owns foreground. The
current `set_shell_foreground` path can mark the resident Game as
`PausedSuspended` in the foreground stack while `TaskManager::set_foreground`
only demotes the previous foreground Game task to `Background`. This creates a
state mismatch if a Shell is opened while the Game has not already gone through
the Home suspension path.
## Objective
Make Shell foreground acquisition either require an already suspended resident
Game or perform the necessary OS-owned suspension consistently across
foreground stack, task manager, and process manager.
## Dependencies
- Source decision: `DEC-0037`.
- Can be implemented independently of `PLN-0142` and `PLN-0143`, but tests
should be rerun with those fixes if they are executed first.
## Scope
Included:
- Close the mismatch between `ResidentGameState::PausedSuspended` and
`TaskState::Background`.
- Ensure Shell foreground cannot leave a resident Game running or backgrounded.
- Cover both `create_vm_shell_task` and `create_native_shell_task` paths.
- Preserve the rule that only one foreground Shell may exist.
- Keep the normal Home -> Shell flow working.
Excluded:
- No direct Shell -> Game return behavior; v1 still returns Shell close to Hub.
- No background Game execution.
- No multiple resident Games.
- No Shell persistence policy changes.
## Non-Goals
- Do not broaden Shell lifecycle semantics.
- Do not implement Game-to-Game switching.
- Do not add UI controls for resume.
## Execution Method
1. Define the legal Shell foreground precondition.
- What changes: decide in code whether Shell foreground requires the
resident Game to already be `PausedSuspended`, or whether
`set_shell_foreground_task` is responsible for suspending it.
- How it changes: prefer centralizing the invariant in
`LifecycleFacade::set_shell_foreground_task`, because it owns task/process
transitions.
- File(s): `crates/console/prometeu-system/src/os/facades/lifecycle.rs`,
`crates/console/prometeu-system/src/services/foreground.rs`.
2. Synchronize task/process state when Shell takes foreground.
- What changes: if a resident Game exists and is not already suspended,
mark the Game task and process `Suspended` before or during Shell
foreground transition.
- How it changes: use `process_id_for_task` for the resident Game and call
`task_manager.mark_suspended` and `process_manager.mark_suspended` in the
same lifecycle operation that sets Shell foreground.
- File(s): `crates/console/prometeu-system/src/os/facades/lifecycle.rs`.
3. Tighten foreground stack behavior.
- What changes: `ForegroundStack::set_shell_foreground` must not silently
hide invalid state transitions.
- How it changes: either reject Shell foreground when the resident Game is
still `Foreground`/`PauseRequested`, or return enough information for the
lifecycle facade to suspend the resident Game explicitly.
- File(s): `crates/console/prometeu-system/src/services/foreground.rs`.
4. Add regression tests for reachable session paths.
- What changes: create tests that call `create_vm_shell_task` and
`create_native_shell_task` while a Game task is foreground.
- How it changes: assert foreground owner is Shell, resident Game remains
recorded, Game task state is `Suspended`, and Game process state is
`Suspended`.
- File(s): `crates/console/prometeu-system/src/os/system_os.rs`,
`crates/console/prometeu-firmware/src/firmware/firmware.rs` if the
firmware Home/Shell path needs coverage.
## Acceptance Criteria
- [ ] A Shell foreground transition cannot leave the resident Game in
`TaskState::Background`.
- [ ] Foreground stack state, task state, and process state agree that the
resident Game is suspended while Shell is foreground.
- [ ] `create_vm_shell_task` and `create_native_shell_task` both preserve the
invariant.
- [ ] Opening a second foreground Shell remains rejected.
- [ ] Closing Shell still returns to Hub/Home, not directly to Game.
## Tests
- Unit tests in `prometeu-system` for `set_shell_foreground_task` with a
resident foreground Game.
- Session facade tests for VM Shell and native Shell creation while a Game is
resident.
- Existing firmware Shell close tests must continue to pass.
- Run `cargo test -p prometeu-system foreground lifecycle shell`.
- Run `cargo test -p prometeu-firmware shell`.
- Run `discussion validate`.
## Affected Artifacts
- `crates/console/prometeu-system/src/services/foreground.rs`
- `crates/console/prometeu-system/src/os/facades/lifecycle.rs`
- `crates/console/prometeu-system/src/os/facades/sessions.rs`
- `crates/console/prometeu-system/src/os/system_os.rs`
- `crates/console/prometeu-firmware/src/firmware/firmware.rs`
@@ -1,149 +0,0 @@
---
id: PLN-0145
ticket: foreground-stack-game-pause-shell-vm-backed
title: Centralize Resident Game Resume Transition
status: done
created: 2026-07-04
ref_decisions: [DEC-0037]
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
---
## Briefing
`DEC-0037` requires returning to the same resident Game to reactivate the Game
VM, restore render ownership, send a resume/foreground lifecycle notification,
and clear or barrier pending Game input. That transition currently exists in
more than one firmware path: `Firmware::resume_resident_game_from_home` and the
Hub library click path that resumes the selected resident Game by `app_id`.
The behavior is correct, but the duplication is fragile. Any future change to
resume ordering, input barriers, render ownership, or lifecycle event delivery
could fix one path while leaving the other path stale.
## Objective
Create one firmware-owned resident Game resume helper and route every
Home/Hub-to-Game resume path through it.
## Dependencies
- Source decision: `DEC-0037`.
- Depends on the accepted v1 identity rule that `app_id` is unique for all
games and may be used to decide whether a Hub game selection refers to the
current resident Game.
- Should preserve the behavior introduced by `PLN-0142`, `PLN-0143`, and
`PLN-0144`.
## Scope
Included:
- Centralize resident Game resume orchestration in `Firmware`.
- Preserve resume lifecycle event queuing through `LifecycleFacade::resume_task`.
- Preserve render ownership transition back to `AppMode::Game`.
- Preserve input barrier behavior across all Home/Hub-to-Game resume paths.
- Preserve the Hub rule that selecting the same resident Game resumes it, while
selecting a different Game remains blocked by v1 scope.
- Keep tests proving same-task resume, lifecycle event delivery, and input
barriering.
Excluded:
- No Game-to-Game switching.
- No multiple resident Games.
- No change to `app_id` uniqueness policy.
- No direct Shell-to-Game close behavior.
## Non-Goals
- Do not move foreground authority from SystemOS into firmware.
- Do not change pause budget or suspend behavior.
- Do not add UI affordances beyond the existing Hub game row selection.
## Execution Method
1. Introduce a single resident Game resume helper.
- What changes: create a private firmware method that performs the complete
resident Game resume operation and returns the target `TaskId` or a typed
failure.
- How it changes: move the shared sequence currently duplicated across
`resume_resident_game_from_home` and `HubHomeStep`: read resident task,
call `LifecycleFacade::resume_task`, transition VM render ownership to
`AppMode::Game`, install `GameRunningStep`, clear state initialization,
and arm the input barrier.
- File(s): `crates/console/prometeu-firmware/src/firmware/firmware.rs`.
2. Route explicit resume through the helper.
- What changes: `Firmware::resume_resident_game_from_home` becomes a thin
wrapper around the centralized helper.
- How it changes: preserve its public `bool` return contract for existing
tests and call sites.
- File(s): `crates/console/prometeu-firmware/src/firmware/firmware.rs`.
3. Route Hub same-game selection through the helper.
- What changes: `HubHomeStep` must no longer hand-roll resume task, render
ownership, and input clearing.
- How it changes: expose a state transition request that lets the firmware
perform the centralized helper, or restructure the Hub action handling so
the parent `Firmware` owns this transition. Keep `HubHomeStep` responsible
only for recognizing that the selected cartridge matches the resident
`app_id`.
- File(s): `crates/console/prometeu-firmware/src/firmware/firmware.rs`,
`crates/console/prometeu-firmware/src/firmware/firmware_step_hub_home.rs`,
`crates/console/prometeu-firmware/src/firmware/firmware_state.rs` if a new
transition variant is needed.
4. Keep different-game launch blocked under v1.
- What changes: selecting a different `app_id` while a resident Game exists
continues to log and remain in Hub.
- How it changes: keep the existing warning behavior, but ensure it does not
duplicate resume side effects.
- File(s): `crates/console/prometeu-firmware/src/firmware/firmware_step_hub_home.rs`.
5. Update regression tests.
- What changes: tests should prove both explicit resume and Hub same-game
selection use the same observable transition.
- How it changes: assert same `TaskId`, foreground owner restored to Game,
pending resume lifecycle event exists before the next Game tick, delivered
resume event after the Game tick, and input barrier suppresses held input.
- File(s): `crates/console/prometeu-firmware/src/firmware/firmware.rs`.
## Acceptance Criteria
- [ ] There is exactly one implementation of the resident Game resume sequence.
- [ ] `Firmware::resume_resident_game_from_home` preserves its external
behavior.
- [ ] Hub selection of the same resident Game resumes the existing `TaskId`
without creating or loading a new Game task.
- [ ] The resume path always queues and delivers the Game lifecycle
`ResumeForeground` event.
- [ ] The resume path always barriers held Game input.
- [ ] Selecting a different Game while one Game is resident remains blocked in
v1.
## Tests
- Unit/integration tests in `prometeu-firmware` for explicit resume from Home.
- Unit/integration tests in `prometeu-firmware` for Hub same-game selection
after Home suspension.
- Regression assertion that held input does not leak into the Game immediately
after resume.
- Run `cargo test -p prometeu-firmware resident_game_resume`.
- Run `cargo test -p prometeu-firmware hub_home_clicking_resident_game`.
- Run `cargo test -p prometeu-system`.
- Run `discussion validate`.
## Affected Artifacts
- `crates/console/prometeu-firmware/src/firmware/firmware.rs`
- `crates/console/prometeu-firmware/src/firmware/firmware_step_hub_home.rs`
- `crates/console/prometeu-firmware/src/firmware/firmware_state.rs`
## Risks
- The current step/state architecture gives `HubHomeStep` a `PrometeuContext`
but not direct access to private `Firmware` fields. If a new transition
variant is introduced, it must stay narrow and must not turn state steps into
owners of lifecycle authority.
- Duplicating less logic must not accidentally weaken the input barrier that was
added for Hub-to-Game transitions.
@@ -1,119 +0,0 @@
---
id: PLN-0146
ticket: foreground-stack-game-pause-shell-vm-backed
title: Consolidate Lifecycle Process Lookup Helpers
status: done
created: 2026-07-04
ref_decisions: [DEC-0037]
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
---
## Briefing
`DEC-0037` depends on SystemOS lifecycle authority being internally
consistent. The lifecycle facade now exposes both process state and process kind
for a task so firmware can distinguish VM-backed Shell tasks from native Shell
tasks. Both accessors repeat the same task-to-process lookup pattern.
The duplication is small, but this facade is now part of the foreground
contract surface. Keeping lookup and error mapping in one place reduces the
chance that future lifecycle accessors drift in behavior.
## Objective
Consolidate task-to-process lookup in `LifecycleFacade` behind one private
helper, while preserving the public lifecycle facade behavior and errors.
## Dependencies
- Source decision: `DEC-0037`.
- Depends on the process/task authority from SystemOS lifecycle work.
- Can be implemented independently of `PLN-0145` and `PLN-0147`.
## Scope
Included:
- Add one private helper that resolves a `TaskId` to its backing process.
- Route `process_state_for_task` and `process_kind_for_task` through that
helper.
- Preserve `LifecycleError::TaskNotFound` and
`LifecycleError::ProcessNotFound` behavior exactly.
- Keep the current process/task manager ownership boundaries intact.
- Keep the current non-architectural cleanup in `set_foreground_task` if it is
still present in the working tree.
Excluded:
- No new public process manager API.
- No changes to task or process IDs.
- No changes to Shell/Game lifecycle semantics.
- No broader facade refactor outside lifecycle lookup.
## Non-Goals
- Do not expose raw process manager access through SystemOS.
- Do not change `ProcessKind` or `TaskKind` definitions.
- Do not alter foreground stack behavior.
## Execution Method
1. Add a private lifecycle lookup helper.
- What changes: add a private function near `process_id_for_task` that
returns a process reference for a `TaskId`.
- How it changes: the helper should call `process_id_for_task`, then
retrieve the process from `process_manager`, returning
`LifecycleError::ProcessNotFound(process_id)` if the process is missing.
- File(s): `crates/console/prometeu-system/src/os/facades/lifecycle.rs`.
2. Route state and kind accessors through the helper.
- What changes: `LifecycleFacade::process_state_for_task` and
`LifecycleFacade::process_kind_for_task` stop duplicating the process
manager lookup.
- How it changes: both methods call the helper and map the process reference
to `ProcessState` or `ProcessKind`.
- File(s): `crates/console/prometeu-system/src/os/facades/lifecycle.rs`.
3. Preserve existing foreground code cleanup.
- What changes: keep `set_foreground_task` as an expression-returning match
rather than using redundant `return` statements.
- How it changes: ensure formatting and clippy stay clean.
- File(s): `crates/console/prometeu-system/src/os/facades/lifecycle.rs`.
4. Tighten tests around lookup behavior.
- What changes: extend or keep tests proving VM Shell and native Shell
process kinds are observable through lifecycle.
- How it changes: add missing-task and missing-process coverage only if the
helper changes the observable path enough to justify it.
- File(s): `crates/console/prometeu-system/src/os/system_os.rs`.
## Acceptance Criteria
- [ ] `process_state_for_task` and `process_kind_for_task` share one private
task-to-process lookup implementation.
- [ ] Missing task and missing process errors remain unchanged.
- [ ] Existing lifecycle tests continue to pass.
- [ ] Firmware can still distinguish `ProcessKind::VmShell` from
`ProcessKind::NativeShell`.
- [ ] Clippy reports no warnings for the touched crates.
## Tests
- Unit tests in `prometeu-system` for shell process kind lookup.
- Existing lifecycle missing task/process tests must continue to pass.
- Run `cargo test -p prometeu-system lifecycle process_kind`.
- Run `cargo test -p prometeu-firmware shell`.
- Run `cargo clippy -p prometeu-system -p prometeu-firmware --all-targets -- -D warnings`.
- Run `discussion validate`.
## Affected Artifacts
- `crates/console/prometeu-system/src/os/facades/lifecycle.rs`
- `crates/console/prometeu-system/src/os/system_os.rs`
## Risks
- Over-generalizing the helper could leak process manager concepts outside the
lifecycle facade. Keep it private and narrowly typed.
- This is intentionally small cleanup. It must not become a broad SystemOS
facade redesign.
@@ -1,144 +0,0 @@
---
id: PLN-0147
ticket: foreground-stack-game-pause-shell-vm-backed
title: Move Native Shell Profile Update Into Hub
status: done
created: 2026-07-04
ref_decisions: [DEC-0037]
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
---
## Briefing
`DEC-0037` says a suspended Game must not receive normal gameplay ticks while
Hub or Shell owns foreground. A recent fix made `ShellRunningStep` branch on
`ProcessKind`: VM-backed Shell tasks use the VM-backed shell profile path, while
native Shell tasks call `PrometeuHub::gui_update` and `PrometeuHub::render`
without ticking the VM.
That behavior is correct, but the native Shell update sequence now lives in
firmware rather than in the Hub profile API. This duplicates part of
`PrometeuHub::update_shell_profile` and creates a drift risk if Shell close,
render, or input rules change later.
## Objective
Move native Shell profile updating into `PrometeuHub` so `ShellRunningStep`
chooses the correct profile API without reimplementing Hub behavior.
## Dependencies
- Source decision: `DEC-0037`.
- Depends on the `ProcessKind::VmShell` vs `ProcessKind::NativeShell`
distinction available through `LifecycleFacade::process_kind_for_task`.
- May be implemented before or after `PLN-0146`, but should use the consolidated
lookup helper if `PLN-0146` has already landed.
## Scope
Included:
- Add a Hub-owned native Shell update API that does not tick the VM.
- Keep VM-backed Shell update behavior in the existing VM-backed profile path.
- Keep Shell close handling consistent between native and VM-backed Shells.
- Keep native Shell rendering in the Hub/Shell UI path.
- Keep firmware responsible for choosing which profile applies to the current
Shell task.
- Preserve regression coverage that a suspended resident Game does not advance
while native Shell is foreground.
Excluded:
- No change to VM-backed Shell execution semantics.
- No change to native Shell UI content.
- No direct Shell close to Game.
- No multiple foreground Shells.
- No background Game ticking.
## Non-Goals
- Do not move foreground lifecycle authority into `PrometeuHub`.
- Do not make native Shells VM tasks.
- Do not introduce a general scheduler abstraction.
## Execution Method
1. Add a native Shell profile update method on `PrometeuHub`.
- What changes: create `update_native_shell_profile` or an equivalent
clearly named method that returns `SystemProfileUpdate`.
- How it changes: the method calls `gui_update`, maps Start input to
`SystemProfileAction::CloseShell` when a shell window is focused, calls
`render`, and always returns `crash: None`.
- File(s):
`crates/console/prometeu-system/src/programs/prometeu_hub/prometeu_hub.rs`.
2. Keep the VM-backed Shell profile method explicitly VM-backed.
- What changes: either keep `update_shell_profile` and document/name its VM
tick behavior, or rename/split it if the codebase convention supports that
without churn.
- How it changes: ensure the VM-backed path is the only Hub profile update
method that calls `os.vm().tick(...)`.
- File(s):
`crates/console/prometeu-system/src/programs/prometeu_hub/prometeu_hub.rs`.
3. Simplify `ShellRunningStep`.
- What changes: remove manual native Shell `gui_update`, Start handling, and
render calls from firmware.
- How it changes: branch on `ProcessKind` and call the appropriate Hub
profile method; keep crash handling only for the VM-backed method.
- File(s):
`crates/console/prometeu-firmware/src/firmware/firmware_step_shell_running.rs`.
4. Add Hub-level native profile tests.
- What changes: prove native Shell profile update emits close on the close
button and on Start, renders Shell UI, and does not tick the VM.
- How it changes: use existing Hub/system test helpers where possible; assert
VM tick index remains unchanged for native profile update.
- File(s):
`crates/console/prometeu-system/src/programs/prometeu_hub/prometeu_hub.rs`
and/or `crates/console/prometeu-firmware/src/firmware/firmware.rs`.
5. Preserve end-to-end regression coverage.
- What changes: keep the Game -> Home -> native Shell test asserting that
repeated Shell frames do not advance the resident Game VM tick index.
- How it changes: rerun the firmware regression added for native Shell
foreground.
- File(s): `crates/console/prometeu-firmware/src/firmware/firmware.rs`.
## Acceptance Criteria
- [ ] Native Shell update behavior is owned by `PrometeuHub`, not hand-coded in
`ShellRunningStep`.
- [ ] The native Shell profile update never calls `os.vm().tick(...)`.
- [ ] VM-backed Shell update remains the only Shell profile path that ticks the
VM runtime.
- [ ] Start and close-button Shell close behavior remains unchanged for native
Shells.
- [ ] A suspended resident Game receives no normal gameplay ticks while native
Shell is foreground.
## Tests
- Hub-level tests for native Shell profile close behavior.
- Hub-level or firmware-level tests proving native Shell profile update does not
tick the VM.
- Existing firmware regression for Game -> Home -> native Shell repeated frames.
- Run `cargo test -p prometeu-system native_shell shell_profile`.
- Run `cargo test -p prometeu-firmware game_home_shell_hub_same_game_flow`.
- Run `cargo test -p prometeu-firmware`.
- Run `cargo test -p prometeu-system`.
- Run `discussion validate`.
## Affected Artifacts
- `crates/console/prometeu-system/src/programs/prometeu_hub/prometeu_hub.rs`
- `crates/console/prometeu-firmware/src/firmware/firmware_step_shell_running.rs`
- `crates/console/prometeu-firmware/src/firmware/firmware.rs`
## Risks
- Renaming the existing VM-backed shell profile method may create unnecessary
churn. Prefer adding the native method and keeping call sites explicit unless
the rename is small and clearly improves readability.
- Hub APIs must remain UI/profile orchestration only; lifecycle close and task
state changes still belong to firmware/SystemOS lifecycle.
@@ -1,92 +0,0 @@
---
id: PLN-0148
ticket: foreground-stack-game-pause-shell-vm-backed
title: Introduce VM Session Registry and Identity
status: done
created: 2026-07-04
ref_decisions: [DEC-0038]
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
---
## Briefing
DEC-0038 requires every VM-backed process to own its own mutable VM context instead of sharing `Firmware.vm`. This plan introduces the identity and registry layer required before moving runtime state or changing cartridge loading.
The implementation must make VM session ownership explicit inside `SystemOS`. A VM-backed Game task and a VM-backed Shell task must be able to coexist as distinct sessions, even before all execution paths are migrated to session-owned VMs.
## Objective
Add a `VmSession` model and registry owned by `SystemOS`, keyed by a stable session identity tied to the owning task/process. The registry must support creating, retrieving, and validating VM sessions for VM-backed Game and Shell tasks.
## Dependencies
- Source decision: DEC-0038.
- Existing foreground/task/process lifecycle from DEC-0037 remains authoritative.
- Must be implemented before PLN-0149, PLN-0150, PLN-0151, and PLN-0152.
## Scope
- Add a session identity type, preferably `VmSessionId`, with a deliberate mapping from the owning `TaskId`.
- Add a `VmSession` data structure containing at least:
- owning `TaskId`;
- owning process id or process lookup path;
- `app_id`, title, version, and `AppMode`;
- initial placeholder for the session-owned `VirtualMachine`;
- initial placeholder for session-owned runtime state to be populated by PLN-0149.
- Add a registry under `crates/console/prometeu-system/src/services/` or an equivalent existing services module.
- Expose creation and lookup through `crates/console/prometeu-system/src/os/facades/sessions.rs`.
- Update `SystemOS` construction in `crates/console/prometeu-system/src/os/system_os.rs` to own the registry.
- Enforce V1 uniqueness:
- at most one resident Game session;
- one foreground Shell task at a time;
- same `app_id` resident Game relaunch maps to the existing resident session rather than creating a second Game session.
## Non-Goals
- Do not move all VM runtime fields yet; that is PLN-0149.
- Do not route cartridge loading through sessions yet; that is PLN-0150.
- Do not remove `Firmware.vm` yet.
- Do not implement general background execution.
- Do not allow Game-to-Game switching.
## Execution Method
1. Inspect `TaskId`, process ids, and `ProcessKind` definitions in `crates/console/prometeu-system/src/services/task/` and `crates/console/prometeu-system/src/services/process/`.
2. Add the VM session module with a small API:
- create session for an existing VM-backed task/process;
- get immutable/mutable session by task id;
- get resident Game session by `app_id`;
- reject incompatible duplicate Game sessions.
3. Wire the registry into `SystemOS`.
4. Extend `SessionsFacade::create_vm_game_task` and `create_vm_shell_task` so task creation also creates a VM session record.
5. Keep native Shell task creation out of the VM session registry.
6. Add focused unit tests under `prometeu-system` for registry identity and duplicate handling.
## Acceptance Criteria
- `SystemOS` owns a VM session registry.
- Creating a VM Game task creates exactly one VM session associated with that task.
- Creating a VM Shell task creates exactly one VM session associated with that task.
- Creating a native Shell task creates no VM session.
- Attempting to create a second resident Game session for a different `app_id` is rejected or routed through the existing lifecycle rejection path.
- Relaunching the same resident Game can resolve the existing VM session by `app_id`.
- No firmware state transition depends on the new registry yet except through task/session creation.
## Tests
- `cargo test -p prometeu-system`
- Add unit tests for:
- VM Game task creates a VM session;
- VM Shell task creates a VM session;
- native Shell task does not create a VM session;
- lookup by `TaskId`;
- same resident Game `app_id` resolves to the existing session;
- different resident Game `app_id` remains blocked under V1.
## Affected Artifacts
- `crates/console/prometeu-system/src/os/system_os.rs`
- `crates/console/prometeu-system/src/os/facades/sessions.rs`
- `crates/console/prometeu-system/src/services/mod.rs`
- New or extended module under `crates/console/prometeu-system/src/services/`
- `crates/console/prometeu-system/src/lib.rs` if exports are required
@@ -1,99 +0,0 @@
---
id: PLN-0149
ticket: foreground-stack-game-pause-shell-vm-backed
title: Move VM Runtime State Into VM Sessions
status: done
created: 2026-07-04
ref_decisions: [DEC-0038]
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
---
## Briefing
DEC-0038 states that mutable VM context must belong to the VM-backed process session, not to firmware or a single global runtime slot. The current split has `Firmware.vm: VirtualMachine` and `SystemOS.vm_runtime: VirtualMachineRuntime`, which makes a suspended Game vulnerable to VM-backed Shell execution.
This plan migrates mutable per-application VM runtime state into the session model introduced by PLN-0148 while keeping global OS services global.
## Objective
Make each VM session own the state needed to suspend and later resume that VM-backed process without being overwritten by another VM-backed process.
## Dependencies
- Source decision: DEC-0038.
- Requires PLN-0148.
- Must precede full cartridge-loading and scheduler migration in PLN-0150 and PLN-0151.
## Scope
- Classify `VirtualMachineRuntime` fields into session-owned versus global OS-owned state.
- Move session-owned fields into the `VmSession` context.
- Keep global services in `SystemOS`, including:
- `LogService`;
- process/task/window managers;
- foreground stack;
- durable `MemcardService`;
- global render publication authority or worker coordination that must remain host-facing.
- Treat these as session-owned unless proven otherwise during implementation:
- `VirtualMachine`;
- current cartridge identity;
- frame and tick counters;
- lifecycle delivery bookkeeping;
- crash report for that session;
- pause/debug flags that apply to that session;
- per-session open files, handles, and staging state used by VM syscalls.
- Keep durable memcard contents keyed by `app_id`; do not turn save data into session-private durable storage.
- Update `VmFacade` and VM runtime helpers so callers can operate on a selected session.
## Non-Goals
- Do not redesign render workers beyond separating session-local render command state from global presentation authority.
- Do not implement background execution.
- Do not change syscall semantics except where required to route state through the active session.
- Do not remove host debugger features; preserve or adapt their access path.
## Execution Method
1. Add an internal field-by-field classification comment or test-only assertion near `VirtualMachineRuntime` before moving fields.
2. Introduce a session runtime/context type in the VM session module or by splitting `VirtualMachineRuntime` into:
- session-local runtime;
- global render/log/runtime services.
3. Move `VirtualMachine` ownership from firmware placeholder/session stub into the session context.
4. Move per-cartridge and per-frame state from `SystemOS.vm_runtime` into the session context.
5. Move `open_files`, `next_handle`, and VM syscall staging state out of global `SystemOS` if they are VM-session specific.
6. Update `VmRuntimeHost` in `crates/console/prometeu-system/src/services/vm_runtime/dispatch.rs` to receive session-local state plus references to required global services.
7. Update `VmFacade` in `crates/console/prometeu-system/src/os/facades/vm.rs` with explicit session-targeted methods.
8. Preserve temporary compatibility methods only where needed for existing host/debugger code, and mark them as active-session views rather than canonical global ownership.
9. Add tests proving two VM sessions can hold different app identity and counters at the same time.
## Acceptance Criteria
- No canonical VM state lives in `Firmware`.
- `SystemOS` can hold at least two VM sessions with independent `VirtualMachine` and per-session runtime state.
- VM session A and VM session B can have different `app_id`, title, frame counters, lifecycle delivery history, crash report, open file handles, and debug pause state.
- Durable memcard contents remain shared by `app_id` according to the existing memcard contract.
- Global render ownership remains controlled by SystemOS/host-facing runtime services, not by individual sessions.
- Existing `prometeu-system` VM runtime tests still pass after adapting their setup.
## Tests
- `cargo test -p prometeu-system`
- `cargo test -p prometeu-firmware`
- Add tests for:
- independent session app identity;
- independent tick/logical-frame counters;
- independent lifecycle delivery bookkeeping;
- VM Shell session initialization does not mutate resident Game session identity;
- session-scoped file handles do not collide across sessions.
## Affected Artifacts
- `crates/console/prometeu-system/src/services/vm_runtime/`
- VM session module introduced by PLN-0148
- `crates/console/prometeu-system/src/os/facades/vm.rs`
- `crates/console/prometeu-system/src/os/system_os.rs`
- `crates/console/prometeu-system/src/os/facades/fs.rs`
- `crates/console/prometeu-firmware/src/firmware/firmware.rs`
- `crates/host/prometeu-host-desktop-winit/src/debugger.rs`
- `crates/host/prometeu-host-desktop-winit/src/runner.rs`
- `crates/host/prometeu-host-desktop-winit/src/stats.rs`
@@ -1,90 +0,0 @@
---
id: PLN-0150
ticket: foreground-stack-game-pause-shell-vm-backed
title: Route Cartridge Loading Through VM Sessions
status: done
created: 2026-07-04
ref_decisions: [DEC-0038]
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
---
## Briefing
DEC-0038 requires cartridge loading to create or activate a VM-backed process session instead of initializing a single global VM. The current `LoadCartridgeStep` initializes `ctx.os.vm().initialize(ctx.vm, &cartridge)` before task/session ownership is selected.
This plan moves cartridge initialization behind session services so Game and VM-backed Shell loading cannot overwrite each other.
## Objective
Route Game and VM Shell cartridge loading through the VM session registry and initialize the cartridge inside the target session-owned VM context.
## Dependencies
- Source decision: DEC-0038.
- Requires PLN-0148.
- Requires enough of PLN-0149 to expose session-owned VM/runtime initialization.
- Must precede the end-to-end coexistence validation in PLN-0152.
## Scope
- Replace direct global VM initialization in `LoadCartridgeStep`.
- Add a session/facade operation that:
- selects an existing resident Game session when the same `app_id` is relaunched;
- rejects or reports different resident Game launches under V1;
- creates a new VM Shell session for a Shell cartridge;
- initializes the cartridge inside the selected session VM.
- Keep asset manager initialization aligned with the foreground cartridge being launched.
- Ensure `AppCrashesStep` receives initialization failures from the target session.
- Update Hub cartridge selection logic so resume versus load is based on lifecycle/session identity, not global VM identity.
## Non-Goals
- Do not implement multiple resident Games.
- Do not implement background execution.
- Do not redesign cartridge format or asset packaging.
- Do not broaden Shell windowing behavior beyond the existing one-foreground-Shell model.
## Execution Method
1. Add a `load_vm_cartridge` or equivalent method to `SessionsFacade` or `VmFacade`.
2. Make the method return an execution target:
- existing Game task for same resident `app_id`;
- new Game task for first Game launch;
- new VM Shell task for Shell launch;
- structured error/crash report for invalid VM initialization;
- explicit lifecycle error for blocked second Game.
3. Update `crates/console/prometeu-firmware/src/firmware/firmware_step_load_cartridge.rs` to call the facade method instead of initializing `ctx.vm`.
4. Update `crates/console/prometeu-firmware/src/firmware/firmware_step_hub_home.rs` so same-Game relaunch checks session/lifecycle state rather than `ctx.os.vm().current_app_id()`.
5. Preserve AppMode-based transition:
- Game target transitions to `GameRunning`;
- Shell target creates/focuses a window and transitions to `ShellRunning`.
6. Adapt crash tests and resident-game relaunch tests in firmware.
## Acceptance Criteria
- `LoadCartridgeStep` no longer initializes a global firmware VM.
- Loading a Shell cartridge creates/initializes a Shell VM session.
- Loading the first Game cartridge creates/initializes the resident Game VM session.
- Clicking the same resident Game from Hub resumes the existing Game session without reinitializing it.
- Attempting to load a different Game while one resident Game exists remains blocked under V1 with a controlled outcome.
- VM initialization failure still transitions to `AppCrashesStep`.
## Tests
- `cargo test -p prometeu-firmware`
- `cargo test -p prometeu-system`
- Add or update firmware tests for:
- first Game load creates one session and enters `GameRunning`;
- same Game relaunch resumes existing task/session;
- VM Shell load creates a distinct session;
- Shell load does not change resident Game session app identity;
- invalid cartridge reports `CrashReport::VmInit`.
## Affected Artifacts
- `crates/console/prometeu-firmware/src/firmware/firmware_step_load_cartridge.rs`
- `crates/console/prometeu-firmware/src/firmware/firmware_step_hub_home.rs`
- `crates/console/prometeu-firmware/src/firmware/firmware.rs`
- `crates/console/prometeu-system/src/os/facades/sessions.rs`
- `crates/console/prometeu-system/src/os/facades/vm.rs`
- VM session module introduced by PLN-0148
@@ -1,92 +0,0 @@
---
id: PLN-0151
ticket: foreground-stack-game-pause-shell-vm-backed
title: Schedule Foreground VM Session Ticks
status: done
created: 2026-07-04
ref_decisions: [DEC-0038]
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
---
## Briefing
DEC-0038 separates session ownership from foreground ownership and states that V1 does not provide general background execution. The runtime therefore needs an explicit scheduler path that ticks the VM session eligible for foreground execution, while leaving suspended resident Game sessions intact.
## Objective
Make firmware and SystemOS tick the VM session associated with the current foreground VM-backed task, instead of ticking a global VM/runtime pair.
## Dependencies
- Source decision: DEC-0038.
- Requires PLN-0148.
- Requires PLN-0149.
- Requires PLN-0150 for loaded cartridges to map to sessions.
## Scope
- Add scheduler/facade operations that tick a specific VM session by `TaskId`.
- Update `GameRunningStep` to tick the Game session identified by its `task_id`.
- Update `ShellRunningStep` to tick only VM-backed Shell sessions.
- Ensure native Shell foreground state performs native profile updates without ticking any VM session.
- Keep suspended Game sessions non-executing while Hub or Shell is foreground.
- Preserve lifecycle event delivery:
- pause/resume events go to the resident Game session;
- Shell lifecycle events, if any, remain scoped to the Shell session.
- Preserve host debugger pause/step behavior against the active VM session view.
## Non-Goals
- Do not add background execution classes yet.
- Do not allow multiple simultaneous VM ticks in one host frame.
- Do not implement general service/player processes.
- Do not change the 60 Hz firmware tick contract.
## Execution Method
1. Add `SystemOS` facade methods for:
- ticking a VM session by task id;
- querying whether a task is VM-backed;
- exposing the active VM session to host/debugger tooling.
2. Update `crates/console/prometeu-firmware/src/firmware/firmware_step_game_running.rs` to tick through the task/session facade.
3. Update `crates/console/prometeu-firmware/src/firmware/firmware_step_shell_running.rs` to branch on process kind:
- VM Shell ticks its VM session;
- native Shell runs native profile logic only.
4. Remove direct `ctx.vm` use from Game/Shell execution steps.
5. Ensure resident Game pause budget can deliver one final pause tick and then stop ticking once suspended.
6. Update host/debugger active VM access paths to resolve through the foreground session.
7. Add regression tests for tick counters across Game, Hub, native Shell, and VM Shell transitions.
## Acceptance Criteria
- A suspended Game session does not advance while Hub is foreground.
- A suspended Game session does not advance while a Shell is foreground.
- A VM Shell session advances while that VM Shell is foreground.
- A native Shell does not tick any VM session.
- Returning from Hub to resident Game resumes ticking the same Game session.
- Host debugger and stats read the active VM session, not a stale global VM.
## Tests
- `cargo test -p prometeu-firmware`
- `cargo test -p prometeu-system`
- `cargo test -p prometeu-host-desktop-winit`
- Add tests for:
- Game tick count freezes after Home suspension;
- VM Shell tick count advances independently;
- native Shell does not advance Game tick count;
- resume returns to same Game session tick counter;
- active-session debugger snapshot uses foreground VM session.
## Affected Artifacts
- `crates/console/prometeu-firmware/src/firmware/firmware_step_game_running.rs`
- `crates/console/prometeu-firmware/src/firmware/firmware_step_shell_running.rs`
- `crates/console/prometeu-firmware/src/firmware/prometeu_context.rs`
- `crates/console/prometeu-firmware/src/firmware/firmware.rs`
- `crates/console/prometeu-system/src/os/facades/vm.rs`
- `crates/console/prometeu-system/src/os/facades/lifecycle.rs`
- VM session module introduced by PLN-0148
- `crates/host/prometeu-host-desktop-winit/src/debugger.rs`
- `crates/host/prometeu-host-desktop-winit/src/runner.rs`
- `crates/host/prometeu-host-desktop-winit/src/stats.rs`
@@ -1,86 +0,0 @@
---
id: PLN-0152
ticket: foreground-stack-game-pause-shell-vm-backed
title: Validate Game and VM Shell Session Coexistence
status: done
created: 2026-07-04
ref_decisions: [DEC-0038]
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
---
## Briefing
DEC-0038 was motivated by the concrete failure mode where a resident Game is suspended, a Shell is opened, and Game logs or state unexpectedly continue under the wrong foreground owner. After VM sessions and scheduling are implemented, the system needs explicit regression coverage for this workflow.
## Objective
Add end-to-end and integration validation proving a resident Game VM session and a VM-backed Shell session can coexist without overwriting or ticking each other incorrectly.
## Dependencies
- Source decision: DEC-0038.
- Requires PLN-0148, PLN-0149, PLN-0150, and PLN-0151.
- Should be executed before closing the broader DEC-0038 implementation thread.
## Scope
- Add firmware-level regression tests for:
- Game launch;
- Home/SystemOS request;
- Game pause/suspend;
- VM Shell launch;
- Shell foreground ticking;
- Shell exit;
- Hub return;
- resident Game resume.
- Add system-level tests for independent session state.
- Add host-level tests only where active VM/debugger/stat routing cannot be covered at firmware/system level.
- Verify logs from the stress cartridge or equivalent test cartridge do not appear while Game is suspended and Shell is foreground.
- Verify Shell logs, frames, or tick counters belong to the Shell session.
## Non-Goals
- Do not introduce new architecture in this plan.
- Do not broaden background execution.
- Do not rewrite Hub UI behavior except where required to exercise the flow.
- Do not depend on manual desktop testing as the only evidence.
## Execution Method
1. Identify or add deterministic test cartridges/helpers that can emit per-session tick/log evidence.
2. Add a firmware integration test for `Game -> Home -> VM Shell -> Hub -> same Game`.
3. Capture Game session counters before Shell launch and after Shell foreground ticks.
4. Assert the Game session counters and lifecycle delivery state remain stable while Shell is foreground.
5. Assert the Shell session counters advance while Shell is foreground.
6. Assert returning to the same Game resumes the same task/session and then advances the Game counter.
7. Add a regression specifically covering the prior symptom: Game `stress` logs must not appear during Shell foreground execution.
8. Run the relevant crate tests and record evidence in the plan completion notes when implemented.
## Acceptance Criteria
- The failing manual scenario is covered by automated tests.
- The Game session is suspended and non-ticking while VM Shell is foreground.
- The VM Shell session ticks independently.
- Returning to Hub and selecting the same Game resumes the resident Game session instead of creating a duplicate process/session.
- No test relies on a single global `current_app_id` to infer correctness.
## Tests
- `cargo test -p prometeu-system`
- `cargo test -p prometeu-firmware`
- `cargo test -p prometeu-host-desktop-winit` if host active-session plumbing changed.
- Optional manual smoke:
- run `cargo run --bin prometeu-host-desktop-winit --profile release --manifest-path crates/host/prometeu-host-desktop-winit/Cargo.toml -- --games-root test-cartridges`;
- open Stress Console;
- press ESC/Home;
- open VM-backed Shell;
- verify no Stress logs appear while Shell is foreground;
- return and resume Stress Console.
## Affected Artifacts
- `crates/console/prometeu-firmware/src/firmware/firmware.rs` tests
- `crates/console/prometeu-system/src/os/system_os.rs` tests
- `crates/console/prometeu-system/src/services/vm_runtime/tests.rs`
- `crates/host/prometeu-host-desktop-winit/src/runner.rs` tests if needed
- `test-cartridges/` only if a deterministic VM Shell fixture is missing
@@ -1,82 +0,0 @@
---
id: PLN-0153
ticket: foreground-stack-game-pause-shell-vm-backed
title: Specify VM Session Ownership and Background-Ready Scheduling
status: done
created: 2026-07-04
ref_decisions: [DEC-0038]
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
---
## Briefing
DEC-0038 locks the runtime direction: VM context is session-owned, firmware orchestrates macro-state, and background execution is out of V1 but must remain a near-term compatible extension. The canonical specs must describe that contract in English so future implementation and debugging do not drift back to a single global VM model.
## Objective
Update canonical runtime specifications to document VM session ownership, foreground execution eligibility, render publication authority, and the background-ready shape of the scheduler without committing to background execution in this implementation batch.
## Dependencies
- Source decision: DEC-0038.
- Should be informed by PLN-0148 through PLN-0151 once implementation names settle.
- May be done before PLN-0152 if the implementation contract is already stable, but final wording must match implemented APIs.
## Scope
- Update the canonical specs under `docs/specs/runtime/` in English.
- Document:
- each VM-backed process owns one VM session;
- VM sessions own mutable VM context;
- foreground ownership and execution eligibility are separate concepts;
- V1 executes only the foreground VM-backed task, except the existing pause handoff budget;
- suspended resident Game sessions preserve VM context but do not tick;
- VM-backed Shell sessions have their own VM context;
- native Shell does not own a VM session;
- durable app data remains keyed by `app_id`;
- session-scoped handles and staging state are not durable app data;
- global render publication remains SystemOS/host authority.
- Add background-ready wording:
- scheduler model can later mark sessions or service processes as eligible without changing ownership;
- no current guarantee of background progress is introduced.
## Non-Goals
- Do not write implementation plans into specs.
- Do not document background execution as available.
- Do not move normative text into `discussion/lessons/`.
- Do not create new legacy docs paths.
## Execution Method
1. Locate the most relevant runtime specs, likely:
- `docs/specs/runtime/09-events-and-concurrency.md`;
- `docs/specs/runtime/12-firmware-pos-and-prometeuhub.md`;
- `docs/specs/runtime/14-boot-profiles.md`;
- `docs/specs/runtime/16-host-abi-and-syscalls.md` if host/debugger active VM views are affected.
2. Add concise normative sections using `MUST`, `MUST NOT`, and `SHALL` where appropriate.
3. Keep discussion history out of the spec; cite behavior, not agenda chronology.
4. Align terminology with implemented type names from PLN-0148 through PLN-0151.
5. Run discussion validation after edits and any repository tests required by touched docs tooling.
## Acceptance Criteria
- Specs explicitly state that VM context is session-owned for VM-backed processes.
- Specs explicitly state that native Shell does not own a VM session.
- Specs distinguish foreground ownership from future execution eligibility.
- Specs state that V1 does not support general background execution.
- Specs preserve a future path for background-capable sessions/services without changing VM ownership.
- No new framework artifacts are written outside `discussion/`.
## Tests
- `discussion validate`
- Manual review of touched specs for English-only normative text.
- Run repository doc checks if such a command exists; otherwise no code test is required for this plan.
## Affected Artifacts
- `docs/specs/runtime/09-events-and-concurrency.md`
- `docs/specs/runtime/12-firmware-pos-and-prometeuhub.md`
- `docs/specs/runtime/14-boot-profiles.md`
- `docs/specs/runtime/16-host-abi-and-syscalls.md` if active VM host/debugger wording is needed
+13 -4
View File
@@ -625,7 +625,8 @@ Each tilemap cell contains:
Runtime-facing validity rule for v1:
- `palette_id` values are valid only in the range `0..63`
- `palette_id` values are valid only when `palette_id < palette_count` for the
resolved resident glyph bank
#### Sprite
@@ -640,7 +641,8 @@ Each sprite draw contains:
Runtime-facing validity rule for v1:
- `palette_id` values are valid only in the range `0..63`
- `palette_id` values are valid only when `palette_id < palette_count` for the
referenced resident glyph bank
---
@@ -649,7 +651,7 @@ Runtime-facing validity rule for v1:
The pipeline works like this:
1. Read indexed pixel from tile (value 0..15)
2. Resolve:
2. Validate and resolve:
- real_color = palette[palette_id][index]
3. Apply:
- flip
@@ -667,6 +669,9 @@ else:
draw_or_blend(color)
```
The `palette_id` lookup above is valid only after the runtime has established
that the referenced resident glyph bank contains that palette.
---
### 19.7. Organization of Tile Banks
@@ -766,6 +771,8 @@ Rules:
- missing glyph dependencies referenced by a resident scene are not a passive `status:int` case;
- if scene activation discovers that a layer dependency cannot be resolved to a committed glyph asset, the machine MUST fail fatally and emit a clear log;
- if scene composition later discovers that a layer dependency can no longer be resolved, the machine MUST fail fatally and emit a clear log;
- if scene activation or composition discovers that a tile references `palette_id >= palette_count` for its resolved glyph bank, the machine MUST fail fatally and emit a clear log;
- invalid scene palette references are scene dependency failures and MUST NOT be rendered through transparent, black, or default color substitution;
- runtime MUST NOT continue canonical scene composition after such a dependency failure.
### 20.2 `composer.emit_sprite`
@@ -774,7 +781,7 @@ Rules:
ABI:
1. `glyph_id: int` — glyph index within the bank
2. `palette_id: int` — palette index
2. `palette_id: int` — palette index within the referenced bank; valid only when `palette_id < palette_count` for that resident glyph bank
3. `x: int` — x coordinate
4. `y: int` — y coordinate
5. `layer: int` — composition layer reference
@@ -797,4 +804,6 @@ Operational notes:
- the canonical public sprite contract is frame-emission based;
- no caller-provided sprite index exists in the v1 canonical ABI;
- no `active` flag exists in the v1 canonical ABI;
- `palette_id >= palette_count` for the referenced glyph bank MUST return `BANK_INVALID`;
- invalid sprite palette references MUST NOT be rendered through transparent, black, or default color substitution;
- overflow remains non-fatal and must not escalate to trap in v1.
@@ -128,6 +128,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.
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,
and no frame pacing. Real background execution is outside the v1 foreground
@@ -163,6 +168,20 @@ requires it. Transient VM handles, open files, lifecycle delivery queues, and
staging state are session-scoped unless another spec explicitly makes them
durable app data.
During destructive Game replacement, the old Game VM session MUST be removed
from execution eligibility and resumable state before the new Game becomes the
foreground Game. The new Game MUST receive a fresh VM session. Failure while
loading or initializing the replacement Game MUST return the machine to
Hub/Home and MUST NOT restore the previous Game in v1.
Manual Hub termination of a suspended resident Game has the same session
removal authority as destructive Game replacement, except that no replacement
Game is started. SystemOS MUST remove the Game from execution eligibility and
resumable state, close its task, stop its process, remove its VM session, clear
task-scoped pending lifecycle delivery, and keep Hub/Home as the foreground
owner. After manual Hub termination, resume queries MUST report no resident
Game. A later launch of the same cartridge is a fresh Game session.
## 9 Render Worker Concurrency
The render worker is not a machine-visible event source and does not introduce
@@ -44,6 +44,11 @@ PROMETEU operates in three main modes:
No mode alters the logical result of the program.
Debug boot is a host-selected direct cartridge boot profile. It follows the same
cartridge/app-mode resolution path as direct boot and is separate from
Home-driven Game switching. Debug boot MUST NOT be modeled as a guest-visible
Game switch request and MUST NOT reuse a Home switch failure-recovery contract.
## 3 Execution Control
### 3.1 Pause and Resume
@@ -43,6 +43,9 @@ The VM does not own the machine lifecycle. Firmware does.
Game directory cartridges.
- **Library entry**: an internal catalog record retained by Hub/SystemOS for a
discovered cartridge.
- **Game switch target**: a SystemOS-owned launch target derived from a library
entry. It carries the cartridge path plus resolved identity such as `app_id`,
`title`, and `app_version`.
- **Foreground visual owner**: the single machine owner whose visual output may
be presented at a given time.
- **Paused**: a Game-visible lifecycle event/state. The Game may observe it and
@@ -52,6 +55,8 @@ The VM does not own the machine lifecycle. Firmware does.
frame pacing.
- **VM session**: the POS-owned mutable execution context for one VM-backed
process. It contains the VM instance and per-session runtime state.
- **Hub resident Game kill control**: a Hub/Home affordance that terminates the
current resident Game instead of resuming it.
## 3 POS Responsibilities
@@ -86,6 +91,8 @@ PrometeuHub is responsible for:
- presenting the host-provided local games library when `--games-root <dir>` is
configured;
- emitting system-owned launch actions for selected Home entries.
- presenting a resident Game kill control while Hub/Home owns foreground and a
Game is resident/suspended.
The Hub does not execute bytecode directly. It always delegates execution setup to POS.
@@ -216,6 +223,17 @@ It preserves Game VM state but is not execution-eligible except for the bounded
pause handoff and later foreground resume. A VM-backed Shell has a separate VM
session. A native Shell has no VM session.
When Hub/Home is foreground and a Game cartridge remains resident/suspended,
PrometeuHub MUST render a red control in the bottom-right of the Hub viewport.
The control MUST display only the resident Game title. It MUST NOT be rendered
for no resident Game, Shell tasks, System tasks, or native Shell tasks.
Clicking the Hub resident Game kill control is a system-owned immediate
termination request. Firmware MUST keep the user in Hub/Home, MUST NOT ask for
confirmation in v1, and MUST NOT resume the killed Game on subsequent Home
actions. The control MUST disappear on the next Hub frame after the resident
Game is no longer present.
## 8 Cartridge Load Flow
Current high-level flow:
@@ -231,11 +249,51 @@ Current high-level flow:
If VM initialization fails, firmware transitions to the crash path.
For v1, POS must enforce at most one resident Game session. Selecting the same
resident Game from Home resumes that session. Selecting a different Game while a
resident Game exists is outside the v1 foreground contract and must not create a
second resident Game session. VM-backed Shell loading creates a distinct Shell
resident Game from Home resumes that session. Selecting a different Game from
Home is a SystemOS-owned Game switch and MUST be destructive replacement:
```text
Game A resident
-> Hub/Home selected Game B with different app_id
-> SystemOS terminates Game A resident task/session
-> SystemOS removes Game A from resumable state
-> firmware loads Game B through LoadCartridge
-> Game B receives a fresh VM session
```
SystemOS MUST NOT create a second resident Game session. SystemOS MUST NOT
reuse the old Game VM session, transient VM handles, pending lifecycle delivery
state, render ownership, debug pause state, or crash/debug runtime state for the
new Game. Durable app data remains governed by the relevant storage specs and
may still be keyed by `app_id`.
SystemOS MAY emit a cooperative non-blocking terminate/save lifecycle event
before closing the old Game when such an event exists. Replacement MUST NOT
block on that event in v1. VM-backed Shell loading creates a distinct Shell
session and must not overwrite resident Game VM state.
Manual Hub resident Game kill and destructive different-Game replacement MUST
share the canonical resident-Game termination path. That path MUST:
- close the resident Game task;
- mark its process stopped;
- remove its VM session;
- clear resident Game state and pending Game lifecycle delivery for that task;
- keep or return foreground ownership to Hub/Home;
- transition render ownership to Shell/Hub (`AppMode::Shell`, `app_id = 0`);
- clear the Game lifecycle audio pause state;
- unbind the Game2D frame composer scene;
- shut down cartridge-scoped asset manager state, including slot identity and
physical glyph/scene/sound banks.
After this operation, the killed Game MUST NOT be resumable. Launching that
same Game again from Home is a fresh cartridge load and a fresh VM session.
Manual Hub kill MUST emit an INFO Hub log with the message shape:
```text
Resident game killed from Hub: <title>
```
POS selects the cartridge and its execution context, but the cartridge's initial callable is not chosen by firmware metadata. Execution starts from the cartridge boot protocol defined in [`13-cartridge.md`](13-cartridge.md), currently `func_id = 0`.
When Home launches a discovered Game entry, the request is a system-owned action
@@ -248,6 +306,16 @@ If the selected cartridge cannot be loaded, firmware must leave or return the
machine in the Hub/Home flow and record the failure through diagnostics or
logging. A polished Home error surface is not required by v1.
If a destructive Game switch has already begun and the new Game fails to load or
initialize, firmware MUST return to Hub/Home, MUST discard any partial new Game
task/session/window/render/input/audio state, and MUST NOT restore the previous
Game. Direct boot and debug boot failures remain governed by the boot profile
that requested them and may still transition to the crash path.
Switch validation MUST include two distinct Game cartridges. The current
repository evidence uses `Stress Console` and `Dummy Boy`; those cartridges are
test evidence, not required runtime features.
## 9 Firmware States
The current firmware state model includes:
@@ -310,6 +378,9 @@ Expected behavior:
resident Game session;
- returning to the same Game resumes it through the foreground lifecycle and
waits for current-epoch Game rendering before visual Game presentation.
- clicking the red bottom-right resident Game kill control terminates the
resident Game, keeps Home foreground, clears runtime/cartridge residue, and
removes the resume path.
## 13 Relationship to Other Specs
+8
View File
@@ -186,6 +186,9 @@ For the v1 Home games library:
- the manifest must declare `app_mode: "Game"`;
- the library retains the loaded manifest data, `title`, `app_id`,
`app_version`, the internal cartridge path, and discovery metadata;
- the library entry identity is the input to the SystemOS Game switch target;
- `app_id` is the v1 identity used to distinguish same-Game resume from
different-Game destructive replacement;
- invalid candidates are logged or reported as diagnostics and omitted from the
Home list;
- valid non-Game cartridges are omitted from the Game library.
@@ -193,6 +196,11 @@ For the v1 Home games library:
Discovery reads metadata for cataloging. It does not replace the normal
cartridge loader used when firmware starts the selected cartridge.
Selecting a discovered Game from Home is not cartridge self-execution and is not
guest-controlled. The cartridge path is consumed by firmware/SystemOS, which
owns same-Game resume, different-Game replacement, failure recovery, and VM
session creation policy.
### Packaged `.pmc` form
This form is recognized conceptually by the loader boundary, but its actual load path is not implemented yet.
+13 -3
View File
@@ -97,9 +97,11 @@ The v1 games root contract is:
and transitions through `LoadCartridge`;
- launch failure leaves or returns the machine to Home and records an error.
Game-to-game switching after a game is already active is not part of this boot
profile. That orchestration belongs to the foreground/home and cartridge switch
contracts.
Game-to-game switching after a game is already active is not a boot profile.
That orchestration belongs to the foreground/home and cartridge switch
contracts. In that path, SystemOS owns the switch policy: selecting the same
resident Game resumes it, while selecting a different Game performs destructive
replacement and creates a fresh VM session for the new Game.
The foreground/home contract defines `Game -> Home/Shell -> same Game` after a
Game is already running. It does not change direct `--run`, debugger direct
@@ -108,6 +110,10 @@ are host/system controls, not guest cartridge boot APIs.
Direct boot creates the initial VM session for the selected cartridge. It does
not create a reusable global VM shared by later Game or Shell cartridges.
Direct boot and debug boot MUST NOT be treated as failed-switch recovery paths:
load or initialization failures for direct boot may transition to the crash
flow, while Home-driven switch failures return to Home and do not restore the
previous Game.
## 5 Firmware State Relationship
@@ -152,6 +158,10 @@ Direct single-cartridge boot remains a separate validation path:
cargo run --release -p prometeu-host-desktop-winit -- --run test-cartridges/stress-console
```
Game switch validation should cover the Home-driven two-cartridge path, for
example `Stress Console -> Home -> Dummy Boy`, and assert that the first Game is
not resumable after replacement.
## 8 Relationship to Other Specs
- [`12-firmware-pos-and-prometeuhub.md`](12-firmware-pos-and-prometeuhub.md) defines the firmware state machine that consumes boot targets.
+18 -4
View File
@@ -115,7 +115,7 @@ For `BankType::GLYPH`, the v1 runtime-facing contract is:
- `codec = NONE`
- serialized pixels use packed `u4` palette indices
- serialized palettes use `RGBA8888` with canonical RGBA channel order
- `palette_count = 64`
- `palette_count` is the number of serialized and resident palettes and must be in `1..=64`
- runtime materialization may expand pixel indices to one `u8` per pixel
For `GLYPH`, `NONE` means there is no additional generic codec layer beyond the bank contract itself.
@@ -136,7 +136,7 @@ Required effective metadata fields for `GLYPH` at the root level:
- `tile_size`: tile edge in pixels; valid values are `8`, `16`, or `32`
- `width`: total sheet width in pixels
- `height`: total sheet height in pixels
- `palette_count`: number of serialized palettes for the bank
- `palette_count`: number of serialized palettes and resident runtime palettes for the bank
Optional informative subtrees:
@@ -145,7 +145,7 @@ Optional informative subtrees:
Validation rules for `GLYPH` v1:
- `palette_count` must be `64`
- `palette_count` must be in the inclusive range `1..=64`
- `width * height` defines the number of logical indexed pixels in the decoded sheet
- extra metadata may exist, but the runtime contract must not depend on it to reconstruct the in-memory bank unless that data is defined at the root as an effective field.
@@ -158,7 +158,16 @@ The tile-bank payload therefore separates serialized storage form from runtime m
- serialized pixel plane: packed `4bpp`
- decoded pixel plane: expanded `u8` indices, one entry per pixel
- palette table: `64 * 16` colors in RGBA8888 channel order
- palette table: `palette_count * 16` colors in RGBA8888 channel order
For `GLYPH` v1:
```text
serialized_pixel_bytes = ceil(width * height / 2)
palette_bytes = palette_count * 16 * 4
size = serialized_pixel_bytes + palette_bytes
decoded_size = (width * height) + palette_bytes
```
For `GLYPH` v1:
@@ -172,6 +181,11 @@ before they are loaded by the runtime.
Palette indices are ordinary indices. Transparency is represented by the alpha
channel of the resolved RGBA8888 palette entry, not by reserving index `0`.
`palette_id` is valid only when it is lower than the referenced resident glyph
bank's `palette_count`. Canonical runtime composition MUST NOT substitute
transparent, black, or any other default color for `palette_id >=
palette_count`.
### 4.2 `SCENE` asset contract in v1
For `BankType::SCENE`, the v1 runtime-facing contract is:
@@ -65,6 +65,12 @@ dedicated `System` profile ABI and stdlib/framework.
## 3 Syscall Resolution
PBX, Prometeu Bytecode Executable, is the runtime executable bytecode format.
Its canonical file magic is `PBX\0`. The former PBS-prefixed magic is not valid
for PBX artifacts: PBS names a frontend language, while PBX names the executable
artifact accepted by the runtime. This distinction is required because Prometeu
bytecode can be produced by multiple frontends.
The host maintains a registry:
```
+11
View File
@@ -0,0 +1,11 @@
# Dummy Boy
Regenerate this cartridge with:
```sh
cargo run -p pbxgen-dummy-boy
```
Dummy Boy is a minimal visual Game cartridge used by runtime switch tests. It
clears the frame and draws a centered square whose fill color cycles
deterministically across frames.
+9
View File
@@ -0,0 +1,9 @@
{
"magic": "PMTU",
"cartridge_version": 1,
"app_id": 2,
"title": "Dummy Boy",
"app_version": "0.1.0",
"app_mode": "Game",
"capabilities": ["gfx2d"]
}
Binary file not shown.
Binary file not shown.