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
bquarkz e01b463e1f implements PLN-0153
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
2026-07-04 19:42:59 +01:00
bquarkz b8fc5a0534 implements PLN-0152 2026-07-04 19:41:35 +01:00
bquarkz f26731413f implements PLN-0151 2026-07-04 19:40:05 +01:00
bquarkz fa2e329d4b implements PLN-0150 2026-07-04 19:36:24 +01:00
bquarkz c3d6b70b0c implements PLN-0149 2026-07-04 19:34:04 +01:00
bquarkz 49a676ff86 implements PLN-0148 2026-07-04 19:30:00 +01:00
bquarkz 23a181de46 VM Context Ownership for Resident Game and VM-Backed Shell 2026-07-04 19:25:55 +01:00
bquarkz bd27f5eb63 implements PLN-0147 2026-07-04 18:55:24 +01:00
bquarkz 6646ccfbb5 implements PLN-0146 2026-07-04 18:52:49 +01:00
bquarkz 0ecab2910b implements PLN-0145 2026-07-04 18:52:04 +01:00
bquarkz 3eeda25e97 Foreground Stack, Game Pause, and VM-Backed Shell Coexistence 2026-07-04 18:48:11 +01:00
bquarkz a22215392d fix native shell ticking resident game 2026-07-04 18:32:44 +01:00
bquarkz e19409a2ef fix resident game relaunch from hub 2026-07-04 18:26:25 +01:00
bquarkz a517a24978 implements PLN-0144 2026-07-04 13:26:05 +01:00
bquarkz a771f6320e implements PLN-0143 2026-07-04 13:24:08 +01:00
bquarkz d645bbb7bd implements PLN-0142 2026-07-04 13:20:52 +01:00
bquarkz 5ff273f167 Foreground Stack, Game Pause, and VM-Backed Shell Coexistence 2026-07-04 13:17:30 +01:00
bquarkz 33f70d1c6e implements PLN-0139 2026-07-04 13:10:55 +01:00
bquarkz 999136fef3 implements PLN-0141 2026-07-03 23:15:11 +01:00
bquarkz 1b29b2f985 implements PLN-0140 2026-07-03 23:10:03 +01:00
bquarkz 29e002c5f3 implements PLN-0138 2026-07-03 23:06:35 +01:00
bquarkz 57c9af939b implements PLN-0137 2026-07-03 23:04:23 +01:00
bquarkz d54dadf2a5 implements PLN-0136 2026-07-03 23:00:49 +01:00
bquarkz 126bffa37d Foreground Stack, Game Pause, and VM-Backed Shell Coexistence 2026-07-03 22:52:08 +01:00
bquarkz 4bc9ce2b73 Merge pull request 'dev/system-run-cart' (#34) from dev/system-run-cart into master
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
Reviewed-on: #34
2026-07-03 20:43:02 +00:00
bquarkz 95465869b1 fix fragile test
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
2026-07-03 21:35:07 +01:00
bquarkz 377cb41a3f implements PLN-0135
Intrepid/Prometeu/Runtime/pipeline/pr-master There was a failure building this commit
2026-07-03 17:30:10 +01:00
bquarkz 6593581954 implements PLN-0134 2026-07-03 17:28:54 +01:00
bquarkz badc9b8874 implements PLN-0133 2026-07-03 17:26:00 +01:00
bquarkz f49accc796 implements PLN-0132 2026-07-03 17:23:49 +01:00
bquarkz 46b2fae514 SystemOS Library Root and Home Game Launch 2026-07-03 17:22:35 +01:00
bquarkz 7307870414 fix format and clippy
Intrepid/Prometeu/Runtime/pipeline/pr-master There was a failure building this commit
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
2026-07-03 10:05:56 +01:00
bquarkz 5137592cdd implements PLN-0131 2026-07-03 09:59:55 +01:00
bquarkz 68fd3bcd65 implements PLN-0130 2026-07-03 09:58:30 +01:00
bquarkz d39e03c7d9 implements PLN-0129 2026-07-03 09:57:11 +01:00
bquarkz 2ab5c43334 System Run Cart 2026-07-03 09:56:02 +01:00
bquarkz 23d3ed641e Merge pull request '[PERF] Async Background Work Lanes for Assets and FS' (#33) from dev/perf-async-background-work-lanes-for-assets-and-fs into master
Intrepid/Prometeu/Runtime/pipeline/head There was a failure building this commit
Reviewed-on: #33
2026-07-01 09:17:23 +00:00
bquarkz 5d3db4c22a [PERF] Async Background Work Lanes for Assets and FS
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
2026-07-01 10:09:33 +01:00
bquarkz b84946a3a0 [PERF] Async Background Work Lanes for Assets and FS 2026-07-01 10:01:51 +01:00
bquarkz 0adec90f23 implements PLN-0128 asset pipeline telemetry tests
Intrepid/Prometeu/Runtime/pipeline/pr-master There was a failure building this commit
2026-06-28 14:20:53 +01:00
bquarkz 8747c4f4cf implements PLN-0127 async io lane boundaries 2026-06-28 14:14:10 +01:00
bquarkz 961557583b implements PLN-0126 asset backlog public api 2026-06-28 14:08:30 +01:00
bquarkz 30c24a4ea7 implements PLN-0125 asset backlog stable handles 2026-06-28 14:02:53 +01:00
bquarkz 7598a15782 implements PLN-0124 async work lane infrastructure 2026-06-28 13:57:41 +01:00
bquarkz 54dad3b398 implements PLN-0123 async work lane specs 2026-06-28 13:53:53 +01:00
103 changed files with 8908 additions and 2405 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
File diff suppressed because it is too large Load Diff
@@ -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
}
File diff suppressed because it is too large Load Diff
@@ -14,6 +14,7 @@ pub enum FirmwareState {
LaunchHub(LaunchHubStep),
HubHome(HubHomeStep),
LoadCartridge(LoadCartridgeStep),
ResumeResidentGame,
GameRunning(GameRunningStep),
ShellRunning(ShellRunningStep),
AppCrashes(AppCrashesStep),
@@ -1,8 +1,9 @@
use crate::firmware::firmware_state::{AppCrashesStep, FirmwareState};
use crate::firmware::firmware_state::{AppCrashesStep, FirmwareState, HubHomeStep};
use crate::firmware::prometeu_context::PrometeuContext;
use prometeu_hal::app_mode::AppMode;
use prometeu_hal::log::{LogLevel, LogSource};
use prometeu_system::CrashReport;
use prometeu_system::task::{TaskId, TaskState};
use prometeu_system::{CrashReport, ResidentGameState};
#[derive(Debug, Clone)]
pub struct GameRunningStep {
@@ -36,13 +37,35 @@ impl GameRunningStep {
return Some(FirmwareState::AppCrashes(AppCrashesStep { report }));
}
let result = ctx.os.vm().tick(ctx.vm, ctx.signals, ctx.platform);
let pause_requested = matches!(
ctx.os.lifecycle().resident_game().map(|game| game.state),
Some(ResidentGameState::PauseRequested { .. })
);
let result = ctx.os.vm().tick_session(self.task_id, ctx.signals, ctx.platform);
if let Some(report) = result {
let _ = ctx.os.lifecycle().crash_task(self.task_id, Some(&report));
return Some(FirmwareState::AppCrashes(AppCrashesStep { report }));
}
if pause_requested {
match ctx.os.lifecycle().advance_game_pause_budget(self.task_id) {
Ok(true) => {
ctx.os.vm().transition_render_owner(AppMode::Shell, 0);
return Some(FirmwareState::HubHome(HubHomeStep));
}
Ok(false) => {}
Err(_) => {
let report = CrashReport::VmPanic {
message: "failed to advance game pause budget".to_string(),
pc: None,
};
let _ = ctx.os.lifecycle().crash_task(self.task_id, Some(&report));
return Some(FirmwareState::AppCrashes(AppCrashesStep { report }));
}
}
}
None
}
@@ -1,5 +1,10 @@
use crate::firmware::firmware_state::{AppCrashesStep, FirmwareState, ShellRunningStep};
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};
use prometeu_hal::primitives::Rect;
use prometeu_system::SystemProfileAction;
@@ -16,21 +21,104 @@ 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 }));
}
if let Some(SystemProfileAction::LaunchNativeShell(app)) = outcome.action {
let task_id = ctx.os.sessions().create_native_shell_task(app.app_id(), app.title());
let id = ctx.os.windows().add_window(
app.title().to_string(),
WindowOwner::Task(task_id),
Rect { x: 40, y: 20, w: 400, h: 220 },
app.color(),
);
ctx.os.windows().set_focus(id);
return Some(FirmwareState::ShellRunning(ShellRunningStep::new(task_id)));
match outcome.action {
Some(SystemProfileAction::LaunchNativeShell(app)) => {
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),
Rect { x: 40, y: 20, w: 400, h: 220 },
app.color(),
);
ctx.os.windows().set_focus(id);
return Some(FirmwareState::ShellRunning(ShellRunningStep::new(task_id)));
}
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 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::Error,
LogSource::Hub,
0,
format!(
"Failed to launch Home game {}: {:?}",
target.path.display(),
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 kill resident game from Hub: {error:?}"),
);
}
}
Some(SystemProfileAction::CloseShell) | None => {}
}
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;
@@ -14,11 +15,30 @@ use prometeu_system::windows::WindowOwner;
pub struct LoadCartridgeStep {
pub cartridge: Cartridge,
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 }
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) {
@@ -29,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(),
@@ -36,19 +58,66 @@ impl LoadCartridgeStep {
self.cartridge.assets.clone(),
);
self.init_error = ctx.os.vm().initialize(ctx.vm, &self.cartridge).err();
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.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 }));
}
if self.cartridge.app_mode == AppMode::Shell {
let task_id = ctx
.os
.sessions()
.create_vm_shell_task(self.cartridge.app_id, self.cartridge.title.clone());
let Some(task_id) = self.loaded_task_id.take() else {
let report = CrashReport::VmPanic {
message: format!(
"cartridge {} was not loaded into a VM session",
self.cartridge.title
),
pc: None,
};
return Some(FirmwareState::AppCrashes(AppCrashesStep { report }));
};
if self.loaded_app_mode == Some(AppMode::Shell) {
let id = ctx.os.windows().add_window(
self.cartridge.title.clone(),
WindowOwner::Task(task_id),
@@ -59,10 +128,6 @@ impl LoadCartridgeStep {
return Some(FirmwareState::ShellRunning(ShellRunningStep::new(task_id)));
}
let task_id = ctx
.os
.sessions()
.create_vm_game_task(self.cartridge.app_id, self.cartridge.title.clone());
Some(FirmwareState::GameRunning(GameRunningStep::new(task_id)))
}
@@ -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> {
@@ -1,6 +1,7 @@
use crate::firmware::firmware_state::{AppCrashesStep, FirmwareState, HubHomeStep};
use crate::firmware::prometeu_context::PrometeuContext;
use prometeu_hal::log::LogSource;
use prometeu_system::process::ProcessKind;
use prometeu_system::task::{TaskId, TaskState};
use prometeu_system::{CrashReport, SystemProfileAction};
@@ -59,7 +60,36 @@ impl ShellRunningStep {
}
}
let outcome = ctx.hub.update_shell_profile(ctx.os, ctx.vm, ctx.signals, ctx.platform);
let process_kind = match ctx.os.lifecycle().process_kind_for_task(self.task_id) {
Ok(process_kind) => process_kind,
Err(error) => {
let report = CrashReport::VmPanic {
message: format!(
"ShellRunningStep cannot resolve process for {:?}: {:?}",
self.task_id, error,
),
pc: None,
};
return Some(FirmwareState::AppCrashes(AppCrashesStep { report }));
}
};
let outcome = match process_kind {
ProcessKind::VmShell => {
ctx.hub.update_vm_shell_profile(ctx.os, self.task_id, ctx.signals, ctx.platform)
}
ProcessKind::NativeShell => ctx.hub.update_native_shell_profile(ctx.os, ctx.platform),
ProcessKind::VmGame => {
let report = CrashReport::VmPanic {
message: format!(
"ShellRunningStep expected shell process for {:?}, got VmGame",
self.task_id,
),
pc: None,
};
return Some(FirmwareState::AppCrashes(AppCrashesStep { report }));
}
};
if let Some(report) = outcome.crash {
let _ = ctx.os.lifecycle().crash_task(self.task_id, Some(&report));
@@ -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 })
}
+36
View File
@@ -112,6 +112,12 @@ pub enum LoadStatus {
CANCELED = 4,
ERROR = 5,
UnknownHandle = 6,
QUEUED = 7,
ACTIVE = 8,
SUPERSEDED = 9,
EMPTY = 10,
INVALID = 11,
BackendUnavailable = 12,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
@@ -129,6 +135,36 @@ pub enum AssetOpStatus {
Ok = 0,
UnknownHandle = 1,
InvalidState = 2,
Superseded = 3,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct AssetBacklogInfo {
pub status: AssetOpStatus,
pub pending_count: u32,
pub active_handle: HandleId,
pub active_asset_id: Option<AssetId>,
pub active_bank_type: Option<BankType>,
pub active_slot: Option<usize>,
pub active_progress: u16,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct AssetBacklogPosition {
pub status: AssetOpStatus,
pub state: LoadStatus,
pub position: u32,
pub progress: u16,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct AssetTargetStatus {
pub status: AssetOpStatus,
pub asset_id: Option<AssetId>,
pub handle: HandleId,
pub state: LoadStatus,
pub position: u32,
pub progress: u16,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
@@ -1,6 +1,7 @@
use crate::asset::{
AssetEntry, AssetId, AssetLoadError, AssetOpStatus, BankTelemetry, HandleId, LoadStatus,
PreloadEntry, SlotRef, SlotStats,
AssetBacklogInfo, AssetBacklogPosition, AssetEntry, AssetId, AssetLoadError, AssetOpStatus,
AssetTargetStatus, BankTelemetry, BankType, HandleId, LoadStatus, PreloadEntry, SlotRef,
SlotStats,
};
use crate::cartridge::AssetsPayloadSource;
@@ -15,6 +16,12 @@ pub trait AssetBridge {
fn status(&self, handle: HandleId) -> LoadStatus;
fn commit(&self, handle: HandleId) -> AssetOpStatus;
fn cancel(&self, handle: HandleId) -> AssetOpStatus;
fn backlog_info(&self) -> AssetBacklogInfo;
fn backlog_position(&self, handle: HandleId) -> AssetBacklogPosition;
fn backlog_move(&self, handle: HandleId, new_position: usize) -> AssetOpStatus;
fn backlog_promote(&self, handle: HandleId) -> AssetOpStatus;
fn backlog_demote(&self, handle: HandleId) -> AssetOpStatus;
fn target_status(&self, bank_type: BankType, slot: usize) -> AssetTargetStatus;
fn apply_commits(&self);
fn bank_telemetry(&self) -> Vec<BankTelemetry>;
fn slot_info(&self, slot: SlotRef) -> SlotStats;
+1 -1
View File
@@ -297,7 +297,7 @@ pub enum Capability {
All,
}
#[derive(Deserialize)]
#[derive(Debug, Clone, Deserialize)]
pub struct CartridgeManifest {
pub magic: String,
pub cartridge_version: u32,
@@ -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 -1
View File
@@ -29,7 +29,6 @@ pub use resolver::{
#[repr(u32)]
pub enum Syscall {
SystemHasCart = 0x0001,
SystemRunCart = 0x0002,
GfxClear = 0x1001,
GfxFillRect = 0x1002,
GfxDrawLine = 0x1003,
@@ -69,6 +68,12 @@ pub enum Syscall {
AssetStatus = 0x6002,
AssetCommit = 0x6003,
AssetCancel = 0x6004,
AssetBacklogInfo = 0x6005,
AssetBacklogPosition = 0x6006,
AssetBacklogMove = 0x6007,
AssetBacklogPromote = 0x6008,
AssetBacklogDemote = 0x6009,
AssetTargetStatus = 0x600A,
BankInfo = 0x6101,
}
@@ -24,4 +24,40 @@ pub(crate) const ENTRIES: &[SyscallRegistryEntry] = &[
.caps(caps::ASSET)
.non_deterministic()
.cost(20),
SyscallRegistryEntry::builder(Syscall::AssetBacklogInfo, "asset", "backlog_info")
.args(0)
.rets(7)
.caps(caps::ASSET)
.non_deterministic()
.cost(5),
SyscallRegistryEntry::builder(Syscall::AssetBacklogPosition, "asset", "backlog_position")
.args(1)
.rets(4)
.caps(caps::ASSET)
.non_deterministic()
.cost(5),
SyscallRegistryEntry::builder(Syscall::AssetBacklogMove, "asset", "backlog_move")
.args(2)
.rets(1)
.caps(caps::ASSET)
.non_deterministic()
.cost(10),
SyscallRegistryEntry::builder(Syscall::AssetBacklogPromote, "asset", "backlog_promote")
.args(1)
.rets(1)
.caps(caps::ASSET)
.non_deterministic()
.cost(10),
SyscallRegistryEntry::builder(Syscall::AssetBacklogDemote, "asset", "backlog_demote")
.args(1)
.rets(1)
.caps(caps::ASSET)
.non_deterministic()
.cost(10),
SyscallRegistryEntry::builder(Syscall::AssetTargetStatus, "asset", "target_status")
.args(2)
.rets(6)
.caps(caps::ASSET)
.non_deterministic()
.cost(5),
];
@@ -1,11 +1,6 @@
use crate::syscalls::{Syscall, SyscallRegistryEntry, caps};
pub(crate) const ENTRIES: &[SyscallRegistryEntry] = &[
SyscallRegistryEntry::builder(Syscall::SystemHasCart, "system", "has_cart")
pub(crate) const ENTRIES: &[SyscallRegistryEntry] =
&[SyscallRegistryEntry::builder(Syscall::SystemHasCart, "system", "has_cart")
.rets(1)
.caps(caps::SYSTEM),
SyscallRegistryEntry::builder(Syscall::SystemRunCart, "system", "run_cart")
.caps(caps::SYSTEM)
.non_deterministic()
.cost(50),
];
.caps(caps::SYSTEM)];
@@ -13,7 +13,6 @@ impl Syscall {
pub fn from_u32(id: u32) -> Option<Self> {
match id {
0x0001 => Some(Self::SystemHasCart),
0x0002 => Some(Self::SystemRunCart),
0x1001 => Some(Self::GfxClear),
0x1002 => Some(Self::GfxFillRect),
0x1003 => Some(Self::GfxDrawLine),
@@ -53,6 +52,12 @@ impl Syscall {
0x6002 => Some(Self::AssetStatus),
0x6003 => Some(Self::AssetCommit),
0x6004 => Some(Self::AssetCancel),
0x6005 => Some(Self::AssetBacklogInfo),
0x6006 => Some(Self::AssetBacklogPosition),
0x6007 => Some(Self::AssetBacklogMove),
0x6008 => Some(Self::AssetBacklogPromote),
0x6009 => Some(Self::AssetBacklogDemote),
0x600A => Some(Self::AssetTargetStatus),
0x6101 => Some(Self::BankInfo),
_ => None,
}
@@ -69,7 +74,6 @@ impl Syscall {
pub fn name(&self) -> &'static str {
match self {
Self::SystemHasCart => "SystemHasCart",
Self::SystemRunCart => "SystemRunCart",
Self::GfxClear => "GfxClear",
Self::GfxFillRect => "GfxFillRect",
Self::GfxDrawLine => "GfxDrawLine",
@@ -109,6 +113,12 @@ impl Syscall {
Self::AssetStatus => "AssetStatus",
Self::AssetCommit => "AssetCommit",
Self::AssetCancel => "AssetCancel",
Self::AssetBacklogInfo => "AssetBacklogInfo",
Self::AssetBacklogPosition => "AssetBacklogPosition",
Self::AssetBacklogMove => "AssetBacklogMove",
Self::AssetBacklogPromote => "AssetBacklogPromote",
Self::AssetBacklogDemote => "AssetBacklogDemote",
Self::AssetTargetStatus => "AssetTargetStatus",
Self::BankInfo => "BankInfo",
}
}
@@ -72,6 +72,33 @@ fn resolver_rejects_removed_legacy_gfx_set_sprite_identity() {
assert_eq!(err, LoadError::UnknownSyscall { module: "gfx2d", name: "set_sprite", version: 1 });
}
#[test]
fn resolver_rejects_userland_system_run_cart_identity() {
assert!(Syscall::from_u32(0x0002).is_none());
assert!(resolve_syscall("system", "run_cart", 1).is_none());
let requested = [SyscallIdentity { module: "system", name: "run_cart", version: 1 }];
let err = resolve_program_syscalls(&requested, caps::ALL).unwrap_err();
assert_eq!(err, LoadError::UnknownSyscall { module: "system", name: "run_cart", version: 1 });
let declared = [prometeu_bytecode::SyscallDecl {
module: "system".into(),
name: "run_cart".into(),
version: 1,
arg_slots: 0,
ret_slots: 0,
}];
let err = resolve_declared_program_syscalls(&declared, caps::ALL).unwrap_err();
assert_eq!(
err,
DeclaredLoadError::UnknownSyscall {
module: "system".into(),
name: "run_cart".into(),
version: 1,
}
);
}
#[test]
fn resolver_enforces_capabilities() {
let requested = [SyscallIdentity { module: "gfx2d", name: "clear", version: 1 }];
@@ -258,6 +285,30 @@ fn status_first_syscall_signatures_are_pinned() {
assert_eq!(asset_cancel.arg_slots, 1);
assert_eq!(asset_cancel.ret_slots, 1);
let asset_backlog_info = meta_for(Syscall::AssetBacklogInfo);
assert_eq!(asset_backlog_info.arg_slots, 0);
assert_eq!(asset_backlog_info.ret_slots, 7);
let asset_backlog_position = meta_for(Syscall::AssetBacklogPosition);
assert_eq!(asset_backlog_position.arg_slots, 1);
assert_eq!(asset_backlog_position.ret_slots, 4);
let asset_backlog_move = meta_for(Syscall::AssetBacklogMove);
assert_eq!(asset_backlog_move.arg_slots, 2);
assert_eq!(asset_backlog_move.ret_slots, 1);
let asset_backlog_promote = meta_for(Syscall::AssetBacklogPromote);
assert_eq!(asset_backlog_promote.arg_slots, 1);
assert_eq!(asset_backlog_promote.ret_slots, 1);
let asset_backlog_demote = meta_for(Syscall::AssetBacklogDemote);
assert_eq!(asset_backlog_demote.arg_slots, 1);
assert_eq!(asset_backlog_demote.ret_slots, 1);
let asset_target_status = meta_for(Syscall::AssetTargetStatus);
assert_eq!(asset_target_status.arg_slots, 2);
assert_eq!(asset_target_status.ret_slots, 6);
let bank_info = meta_for(Syscall::BankInfo);
assert_eq!(bank_info.arg_slots, 1);
assert_eq!(bank_info.ret_slots, 2);
+21 -2
View File
@@ -4,14 +4,33 @@ mod programs;
mod services;
pub use crash_report::CrashReport;
pub use os::{LifecycleError, LifecycleOperation, SystemOS};
pub use programs::{NativeShellApp, PrometeuHub, SystemProfileAction, SystemProfileUpdate};
pub use os::{
DEFAULT_GAME_PAUSE_BUDGET_TICKS, GameLifecycleEvent, GameLifecycleEventKind, LifecycleError,
LifecycleOperation, SessionError, SystemOS,
};
pub use programs::{
HUB_SUSPENDED_GAME_KILL_CONTROL, NativeShellApp, PrometeuHub, SystemProfileAction,
SystemProfileUpdate,
};
pub use prometeu_hal::{RenderWorkerBackend, RenderWorkerFrameSink};
pub use services::async_work::{
AsyncWorkActiveJob, AsyncWorkCancelToken, AsyncWorkJobContext, AsyncWorkJobId,
AsyncWorkJobKind, AsyncWorkJobOutcome, AsyncWorkLane, AsyncWorkLaneConfig,
AsyncWorkLaneController, AsyncWorkLaneError, AsyncWorkLaneTelemetry, AsyncWorkPriority,
};
pub use services::foreground::{
ForegroundOwner, ForegroundStack, ForegroundStackError, ResidentGame, ResidentGameState,
};
pub use services::fs;
pub use services::game_library::{
GameLibrary, GameLibraryDiagnostic, GameLibraryEntry, GameSwitchTarget, discover_games_root,
};
pub use services::memcard::MemcardAsyncLaneOperation;
pub use services::process;
pub use services::task;
pub use services::vm_runtime::{
LatestRenderFrameStore, RenderWorkerConfig, RenderWorkerController, RenderWorkerHandoff,
RenderWorkerHandoffWait, RenderWorkerOwnership, VirtualMachineRuntime,
};
pub use services::vm_session;
pub use services::windows;
@@ -1,8 +1,14 @@
use crate::CrashReport;
use crate::os::SystemOS;
use crate::os::{LifecycleError, LifecycleOperation};
use crate::process::{ProcessId, ProcessState};
use crate::task::{TaskId, TaskState};
use crate::os::{
DEFAULT_GAME_PAUSE_BUDGET_TICKS, GameLifecycleEvent, GameLifecycleEventKind, LifecycleError,
LifecycleOperation,
};
use crate::process::{Process, ProcessId, ProcessKind, ProcessState};
use crate::services::foreground::{
ForegroundOwner, ForegroundStackError, ResidentGame, ResidentGameState,
};
use crate::task::{TaskId, TaskKind, TaskState};
pub struct LifecycleFacade<'a> {
pub(in crate::os) os: &'a mut SystemOS,
@@ -14,28 +20,145 @@ impl<'a> LifecycleFacade<'a> {
}
pub fn process_state_for_task(&self, task_id: TaskId) -> Result<ProcessState, LifecycleError> {
let process_id = process_id_for_task(self.os, task_id)?;
self.os
.process_manager
.get(process_id)
.map(|process| process.state)
.ok_or(LifecycleError::ProcessNotFound(process_id))
process_for_task(self.os, task_id).map(|process| process.state)
}
pub fn process_kind_for_task(&self, task_id: TaskId) -> Result<ProcessKind, LifecycleError> {
process_for_task(self.os, task_id).map(|process| process.kind)
}
pub fn set_foreground_task(&mut self, task_id: TaskId) -> Result<(), LifecycleError> {
match task_kind_for_task(self.os, task_id)? {
TaskKind::Game => self.set_game_foreground_task(task_id),
TaskKind::Shell => self.set_shell_foreground_task(task_id),
}
}
pub fn set_game_foreground_task(&mut self, task_id: TaskId) -> Result<(), LifecycleError> {
let process_id = process_id_for_task(self.os, task_id)?;
if task_kind_for_task(self.os, task_id)? != TaskKind::Game {
return Err(LifecycleError::InvalidTransition {
task_id,
from: self.task_state(task_id).unwrap_or(TaskState::Closed),
operation: LifecycleOperation::SetForeground,
});
}
self.os.foreground_stack.set_game_foreground(task_id).map_err(map_foreground_error)?;
self.os.task_manager.set_foreground(task_id);
self.os.process_manager.mark_running(process_id);
Ok(())
}
pub fn set_shell_foreground_task(&mut self, task_id: TaskId) -> Result<(), LifecycleError> {
let process_id = process_id_for_task(self.os, task_id)?;
if task_kind_for_task(self.os, task_id)? != TaskKind::Shell {
return Err(LifecycleError::InvalidTransition {
task_id,
from: self.task_state(task_id).unwrap_or(TaskState::Closed),
operation: LifecycleOperation::SetForeground,
});
}
if let Some(game_task_id) = self.os.foreground_stack.resident_game_task()
&& game_task_id != task_id
&& self.task_state(game_task_id) != Some(TaskState::Suspended)
{
let game_process_id = process_id_for_task(self.os, game_task_id)?;
self.os.task_manager.mark_suspended(game_task_id);
self.os.process_manager.mark_suspended(game_process_id);
}
self.os.foreground_stack.set_shell_foreground(task_id).map_err(map_foreground_error)?;
self.os.task_manager.set_foreground(task_id);
self.os.process_manager.mark_running(process_id);
Ok(())
}
pub fn foreground_owner(&self) -> ForegroundOwner {
self.os.foreground_stack.owner()
}
pub fn resident_game(&self) -> Option<ResidentGame> {
self.os.foreground_stack.resident_game()
}
pub fn resident_game_task(&self) -> Option<TaskId> {
self.os.foreground_stack.resident_game_task()
}
pub fn request_home_from_game(&mut self, task_id: TaskId) -> Result<(), LifecycleError> {
let _process_id = process_id_for_task(self.os, task_id)?;
let previous = self.os.foreground_stack.resident_game();
self.os
.foreground_stack
.request_home_from_game(task_id, DEFAULT_GAME_PAUSE_BUDGET_TICKS)
.map_err(map_foreground_error)?;
if !matches!(
previous.map(|game| game.state),
Some(ResidentGameState::PauseRequested { .. } | ResidentGameState::PausedSuspended)
) {
self.os
.game_lifecycle_events
.push(GameLifecycleEvent { task_id, kind: GameLifecycleEventKind::Pause });
}
Ok(())
}
pub fn advance_game_pause_budget(&mut self, task_id: TaskId) -> Result<bool, LifecycleError> {
let expired =
self.os.foreground_stack.advance_pause_budget(task_id).map_err(map_foreground_error)?;
if expired {
let process_id = process_id_for_task(self.os, task_id)?;
self.os.task_manager.mark_suspended(task_id);
self.os.process_manager.mark_suspended(process_id);
}
Ok(expired)
}
pub fn pending_game_lifecycle_events(&self) -> &[GameLifecycleEvent] {
&self.os.game_lifecycle_events
}
pub fn take_game_lifecycle_events(&mut self) -> Vec<GameLifecycleEvent> {
std::mem::take(&mut self.os.game_lifecycle_events)
}
pub fn return_to_hub(&mut self) {
self.os.foreground_stack.return_to_hub();
self.os.task_manager.clear_foreground();
}
pub fn suspend_task(&mut self, task_id: TaskId) -> Result<(), LifecycleError> {
let process_id = process_id_for_task(self.os, task_id)?;
self.os.task_manager.mark_suspended(task_id);
self.os.process_manager.mark_suspended(process_id);
match self.os.foreground_stack.owner() {
ForegroundOwner::Game(owner) if owner == task_id => {
self.os
.foreground_stack
.request_home_from_game(task_id, DEFAULT_GAME_PAUSE_BUDGET_TICKS)
.map_err(map_foreground_error)?;
self.os
.foreground_stack
.advance_pause_budget(task_id)
.map_err(map_foreground_error)?;
}
ForegroundOwner::Shell(owner) if owner == task_id => {
self.os.foreground_stack.return_to_hub();
}
_ => {}
}
Ok(())
}
@@ -54,8 +177,32 @@ impl<'a> LifecycleFacade<'a> {
let process_id = process_id_for_task(self.os, task_id)?;
self.os.task_manager.set_foreground(task_id);
self.os.process_manager.mark_running(process_id);
match task_kind_for_task(self.os, task_id)? {
TaskKind::Game => {
self.os
.foreground_stack
.request_resume_game(task_id)
.map_err(map_foreground_error)?;
self.os.task_manager.set_foreground(task_id);
self.os.process_manager.mark_running(process_id);
self.os.game_lifecycle_events.push(GameLifecycleEvent {
task_id,
kind: GameLifecycleEventKind::ResumeForeground,
});
self.os
.foreground_stack
.complete_resume_game(task_id)
.map_err(map_foreground_error)?;
}
TaskKind::Shell => {
self.os
.foreground_stack
.set_shell_foreground(task_id)
.map_err(map_foreground_error)?;
self.os.task_manager.set_foreground(task_id);
self.os.process_manager.mark_running(process_id);
}
}
Ok(())
}
@@ -65,10 +212,38 @@ impl<'a> LifecycleFacade<'a> {
self.os.task_manager.close_task(task_id);
self.os.process_manager.mark_stopped(process_id);
if self.os.foreground_stack.resident_game_task() == Some(task_id) {
self.os.foreground_stack.clear_resident_game(task_id);
} else if matches!(self.os.foreground_stack.owner(), ForegroundOwner::Shell(owner) if owner == task_id)
{
self.os.foreground_stack.return_to_hub();
}
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,
@@ -78,11 +253,22 @@ impl<'a> LifecycleFacade<'a> {
self.os.task_manager.mark_crashed(task_id);
self.os.process_manager.mark_crashed(process_id);
if self.os.foreground_stack.resident_game_task() == Some(task_id) {
self.os.foreground_stack.clear_resident_game(task_id);
} else if matches!(self.os.foreground_stack.owner(), ForegroundOwner::Shell(owner) if owner == task_id)
{
self.os.foreground_stack.return_to_hub();
}
Ok(())
}
}
fn task_kind_for_task(os: &SystemOS, task_id: TaskId) -> Result<TaskKind, LifecycleError> {
let task = os.task_manager.get(task_id).ok_or(LifecycleError::TaskNotFound(task_id))?;
Ok(task.kind)
}
fn process_id_for_task(os: &SystemOS, task_id: TaskId) -> Result<ProcessId, LifecycleError> {
let task = os.task_manager.get(task_id).ok_or(LifecycleError::TaskNotFound(task_id))?;
@@ -92,3 +278,22 @@ fn process_id_for_task(os: &SystemOS, task_id: TaskId) -> Result<ProcessId, Life
Ok(task.process_id)
}
fn process_for_task(os: &SystemOS, task_id: TaskId) -> Result<&Process, LifecycleError> {
let process_id = process_id_for_task(os, task_id)?;
os.process_manager.get(process_id).ok_or(LifecycleError::ProcessNotFound(process_id))
}
fn map_foreground_error(error: ForegroundStackError) -> LifecycleError {
match error {
ForegroundStackError::ResidentGameAlreadyExists { existing, requested } => {
LifecycleError::ResidentGameAlreadyExists { existing, requested }
}
ForegroundStackError::ForegroundShellAlreadyExists { existing, requested } => {
LifecycleError::ForegroundShellAlreadyExists { existing, requested }
}
ForegroundStackError::TaskIsNotResidentGame(task_id) => {
LifecycleError::TaskIsNotResidentGame(task_id)
}
}
}
@@ -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,44 +1,209 @@
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 std::sync::Arc;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct LoadedVmCartridge {
pub task_id: TaskId,
pub app_mode: AppMode,
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("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, SessionError> {
if let Some(session) = self.os.vm_sessions.resident_game_for_app(app_id) {
return Ok(session.task_id);
}
let title = title.into();
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_foreground_task(task_id)
.expect("newly created game task should have an associated process");
self.os.lifecycle().set_game_foreground_task(task_id)?;
self.try_create_vm_session_for_task(task_id)?;
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_foreground_task(task_id)
.expect("newly created shell task should have an associated process");
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_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,
cartridge: &Cartridge,
) -> Result<LoadedVmCartridge, SessionError> {
let existing_game_task = if cartridge.app_mode == AppMode::Game {
self.os
.vm_sessions
.resident_game_for_app(cartridge.app_id)
.map(|session| session.task_id)
} else {
None
};
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.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())?;
(task_id, false)
};
if !reused_existing_session {
self.try_initialize_session_cartridge(task_id, cartridge)?;
}
Ok(LoadedVmCartridge { task_id, app_mode: cartridge.app_mode, reused_existing_session })
}
pub fn vm_session_for_task(&self, task_id: TaskId) -> Option<&VmSession> {
self.os.vm_sessions.for_task(task_id)
}
pub fn vm_session_for_task_mut(&mut self, task_id: TaskId) -> Option<&mut VmSession> {
self.os.vm_sessions.for_task_mut(task_id)
}
pub fn resident_game_session_for_app(&self, app_id: u32) -> Option<&VmSession> {
self.os.vm_sessions.resident_game_for_app(app_id)
}
pub fn vm_session_count(&self) -> usize {
self.os.vm_sessions.len()
}
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)
.ok_or(SessionError::ProcessNotFound(task.process_id))?
.clone();
let cap_config = self.os.vm_runtime.certifier.config;
let logs_count = Arc::clone(&self.os.log_service.logs_count);
self.os
.vm_sessions
.create_for_task(&task, &process, "", Some(cap_config), logs_count)
.map(|_| ())
.map_err(SessionError::from)
}
pub fn try_initialize_session_cartridge(
&mut self,
task_id: TaskId,
cartridge: &Cartridge,
) -> Result<(), SessionError> {
let session = self
.os
.vm_sessions
.for_task_mut(task_id)
.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)
.map_err(SessionError::Initialization)
}
}
@@ -1,14 +1,15 @@
use crate::CrashReport;
use crate::os::SystemOS;
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, RenderWorkerBackend, RenderWorkerError, RenderWorkerFrameSink,
RuntimePlatform,
FrameId, InputSignals, RenderOwnership, RenderWorkerBackend, RenderWorkerError,
RenderWorkerFrameSink, RuntimePlatform,
};
use prometeu_vm::VirtualMachine;
use std::sync::atomic::Ordering;
pub struct VmFacade<'a> {
@@ -16,88 +17,216 @@ pub struct VmFacade<'a> {
}
impl<'a> VmFacade<'a> {
pub fn initialize(
pub fn tick_session(
&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,
task_id: TaskId,
signals: &InputSignals,
platform: &mut dyn RuntimePlatform,
) -> Option<CrashReport> {
self.os.vm_runtime.tick(
self.deliver_pending_game_lifecycle_events_to_session(task_id);
let Some(session) = self.os.vm_sessions.for_task_mut(task_id) else {
return Some(CrashReport::VmPanic {
message: format!("task {:?} has no VM session", task_id),
pc: None,
});
};
session.runtime.tick(
&mut self.os.log_service,
&mut self.os.fs,
&mut self.os.fs_state,
&mut session.fs_state,
&mut self.os.memcard,
&mut self.os.open_files,
&mut self.os.next_handle,
vm,
&mut session.open_files,
&mut session.next_handle,
&mut session.vm,
signals,
platform,
)
}
pub fn reset(&mut self, vm: &mut VirtualMachine) {
self.os.vm_runtime.reset(vm);
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;
};
if session.runtime.current_cartridge_app_mode != AppMode::Game {
return;
}
let mut retained = Vec::new();
let mut delivered = Vec::new();
for event in self.os.game_lifecycle_events.drain(..) {
if event.task_id == task_id {
delivered.push(event);
} else {
retained.push(event);
}
}
self.os.game_lifecycle_events = retained;
if let Some(session) = self.os.vm_sessions.for_task_mut(task_id) {
session.runtime.deliver_game_lifecycle_events(delivered);
}
}
pub fn debug_step_instruction(
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_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 {
self.os.vm_runtime.paused
self.active_session()
.map(|session| session.runtime.paused)
.unwrap_or(self.os.vm_runtime.paused)
}
pub fn set_paused(&mut self, paused: bool) {
if let Some(session) = self.active_session_mut() {
session.runtime.paused = paused;
return;
}
self.os.vm_runtime.paused = paused;
}
pub fn set_inspection_active(&mut self, active: bool) {
if let Some(session) = self.active_session_mut() {
session.runtime.inspection_active = active;
return;
}
self.os.vm_runtime.inspection_active = active;
}
pub fn request_debug_step(&mut self) {
if let Some(session) = self.active_session_mut() {
session.runtime.debug_step_request = true;
return;
}
self.os.vm_runtime.debug_step_request = true;
}
pub fn debug_step_requested(&self) -> bool {
self.os.vm_runtime.debug_step_request
self.active_session()
.map(|session| session.runtime.debug_step_request)
.unwrap_or(self.os.vm_runtime.debug_step_request)
}
pub fn logical_frame_active(&self) -> bool {
self.os.vm_runtime.logical_frame_active
self.active_session()
.map(|session| session.runtime.logical_frame_active)
.unwrap_or(self.os.vm_runtime.logical_frame_active)
}
pub fn delivered_game_lifecycle_events(&self) -> &[GameLifecycleEvent] {
self.active_session()
.map(|session| session.runtime.delivered_game_lifecycle_events())
.unwrap_or_else(|| self.os.vm_runtime.delivered_game_lifecycle_events())
}
pub fn take_delivered_game_lifecycle_events(&mut self) -> Vec<GameLifecycleEvent> {
if let Some(session) = self.active_session_mut() {
return session.runtime.take_delivered_game_lifecycle_events();
}
self.os.vm_runtime.take_delivered_game_lifecycle_events()
}
pub fn tick_index(&self) -> u64 {
self.os.vm_runtime.tick_index
self.active_session()
.map(|session| session.runtime.tick_index)
.unwrap_or(self.os.vm_runtime.tick_index)
}
pub fn logical_frame_index(&self) -> u64 {
self.os.vm_runtime.logical_frame_index
self.active_session()
.map(|session| session.runtime.logical_frame_index)
.unwrap_or(self.os.vm_runtime.logical_frame_index)
}
pub fn last_frame_cpu_time_us(&self) -> u64 {
self.os.vm_runtime.last_frame_cpu_time_us
self.active_session()
.map(|session| session.runtime.last_frame_cpu_time_us)
.unwrap_or(self.os.vm_runtime.last_frame_cpu_time_us)
}
pub fn completed_logical_frames(&self) -> u64 {
self.os.vm_runtime.atomic_telemetry.completed_logical_frames.load(Ordering::Relaxed).into()
self.active_session()
.map(|session| {
session
.runtime
.atomic_telemetry
.completed_logical_frames
.load(Ordering::Relaxed)
.into()
})
.unwrap_or_else(|| {
self.os
.vm_runtime
.atomic_telemetry
.completed_logical_frames
.load(Ordering::Relaxed)
.into()
})
}
pub fn telemetry_snapshot(&self) -> TelemetryFrame {
self.os.vm_runtime.atomic_telemetry.snapshot()
self.active_session()
.map(|session| session.runtime.atomic_telemetry.snapshot())
.unwrap_or_else(|| self.os.vm_runtime.atomic_telemetry.snapshot())
}
pub fn start_render_worker<B, S>(&mut self, config: RenderWorkerConfig, backend: B, sink: S)
@@ -120,27 +249,82 @@ impl<'a> VmFacade<'a> {
self.os.vm_runtime.record_repeated_render_worker_frame(frame_id);
}
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()
}
pub fn transition_render_owner(&mut self, app_mode: AppMode, app_id: u32) {
self.os.vm_runtime.render_manager.transition_render_owner(app_mode, app_id);
self.os.vm_runtime.sync_render_worker_ownership();
self.os.vm_runtime.render_manager.sync_telemetry(&self.os.vm_runtime.atomic_telemetry);
}
pub fn cert_config(&self) -> &CertificationConfig {
&self.os.vm_runtime.certifier.config
}
pub fn last_crash_report(&self) -> Option<&CrashReport> {
self.os.vm_runtime.last_crash_report.as_ref()
self.active_session()
.and_then(|session| session.runtime.last_crash_report.as_ref())
.or(self.os.vm_runtime.last_crash_report.as_ref())
}
pub fn current_app_id(&self) -> u32 {
self.os.vm_runtime.current_app_id
self.active_session()
.map(|session| session.runtime.current_app_id)
.unwrap_or(self.os.vm_runtime.current_app_id)
}
pub fn current_cartridge_title(&self) -> String {
self.os.vm_runtime.current_cartridge_title.clone()
self.active_session()
.map(|session| session.runtime.current_cartridge_title.clone())
.unwrap_or_else(|| self.os.vm_runtime.current_cartridge_title.clone())
}
pub fn current_cartridge_app_version(&self) -> String {
self.os.vm_runtime.current_cartridge_app_version.clone()
self.active_session()
.map(|session| session.runtime.current_cartridge_app_version.clone())
.unwrap_or_else(|| self.os.vm_runtime.current_cartridge_app_version.clone())
}
pub fn current_cartridge_app_mode(&self) -> AppMode {
self.os.vm_runtime.current_cartridge_app_mode
self.active_session()
.map(|session| session.runtime.current_cartridge_app_mode)
.unwrap_or(self.os.vm_runtime.current_cartridge_app_mode)
}
fn active_session(&self) -> Option<&VmSession> {
self.os
.task_manager
.foreground_task()
.and_then(|task_id| self.os.vm_sessions.for_task(task_id))
.or_else(|| {
self.os
.foreground_stack
.resident_game_task()
.and_then(|task_id| self.os.vm_sessions.for_task(task_id))
})
}
fn active_session_mut(&mut self) -> Option<&mut VmSession> {
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()
}
}
@@ -1,6 +1,20 @@
use crate::process::ProcessId;
use crate::task::{TaskId, TaskState};
pub const DEFAULT_GAME_PAUSE_BUDGET_TICKS: u8 = 1;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum GameLifecycleEventKind {
Pause,
ResumeForeground,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct GameLifecycleEvent {
pub task_id: TaskId,
pub kind: GameLifecycleEventKind,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum LifecycleOperation {
SetForeground,
@@ -15,4 +29,7 @@ pub enum LifecycleError {
TaskNotFound(TaskId),
ProcessNotFound(ProcessId),
InvalidTransition { task_id: TaskId, from: TaskState, operation: LifecycleOperation },
ResidentGameAlreadyExists { existing: TaskId, requested: TaskId },
ForegroundShellAlreadyExists { existing: TaskId, requested: TaskId },
TaskIsNotResidentGame(TaskId),
}
+7 -2
View File
@@ -2,6 +2,11 @@ mod facades;
mod lifecycle;
mod system_os;
pub use facades::{FsFacade, LifecycleFacade, SessionsFacade, VmFacade, WindowFacade};
pub use lifecycle::{LifecycleError, LifecycleOperation};
pub use facades::{
FsFacade, LifecycleFacade, SessionError, SessionsFacade, VmFacade, WindowFacade,
};
pub use lifecycle::{
DEFAULT_GAME_PAUSE_BUDGET_TICKS, GameLifecycleEvent, GameLifecycleEventKind, LifecycleError,
LifecycleOperation,
};
pub use system_os::SystemOS;
@@ -1,8 +1,12 @@
use crate::VirtualMachineRuntime;
use crate::fs::{FsState, VirtualFS};
use crate::os::{FsFacade, LifecycleFacade, SessionsFacade, VmFacade, WindowFacade};
use crate::os::{
FsFacade, GameLifecycleEvent, LifecycleFacade, SessionsFacade, VmFacade, WindowFacade,
};
use crate::process::ProcessManager;
use crate::services::foreground::ForegroundStack;
use crate::services::memcard::MemcardService;
use crate::services::vm_session::VmSessionRegistry;
use crate::services::windows::WindowManager;
use crate::task::TaskManager;
use prometeu_hal::log::{LogEvent, LogLevel, LogService, LogSource};
@@ -14,6 +18,9 @@ pub struct SystemOS {
pub(super) vm_runtime: VirtualMachineRuntime,
pub(super) process_manager: ProcessManager,
pub(super) task_manager: TaskManager,
pub(super) foreground_stack: ForegroundStack,
pub(super) vm_sessions: VmSessionRegistry,
pub(super) game_lifecycle_events: Vec<GameLifecycleEvent>,
pub(super) window_manager: WindowManager,
pub(super) log_service: LogService,
pub(super) fs: VirtualFS,
@@ -33,6 +40,9 @@ impl SystemOS {
),
process_manager: ProcessManager::new(),
task_manager: TaskManager::new(),
foreground_stack: ForegroundStack::new(),
vm_sessions: VmSessionRegistry::new(),
game_lifecycle_events: Vec::new(),
window_manager: WindowManager::new(),
log_service,
fs: VirtualFS::new(),
@@ -133,15 +143,33 @@ impl SystemOS {
#[cfg(test)]
mod tests {
use super::*;
use crate::os::{LifecycleError, LifecycleOperation};
use crate::process::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);
@@ -157,6 +185,394 @@ mod tests {
assert_eq!(process_state_for_task(&os, task_id), ProcessState::Running);
}
#[test]
fn foreground_stack_starts_at_hub() {
let os = SystemOS::new(None);
assert_eq!(os.foreground_stack.owner(), ForegroundOwner::Hub);
assert_eq!(os.foreground_stack.resident_game(), None);
}
#[test]
fn game_session_registers_single_resident_game() {
let mut os = SystemOS::new(None);
let task_id = os.sessions().create_vm_game_task(42, "Sector Crawl");
assert_eq!(os.lifecycle().foreground_owner(), ForegroundOwner::Game(task_id));
assert_eq!(
os.lifecycle().resident_game(),
Some(ResidentGame { task_id, state: ResidentGameState::Foreground })
);
}
#[test]
fn second_resident_game_is_rejected() {
let mut os = SystemOS::new(None);
let first = os.sessions().create_vm_game_task(42, "Sector Crawl");
let process_id = os.process_manager.spawn_vm_game(43, "Second");
let second = os.task_manager.create_game_task(process_id, 43, "Second");
assert_eq!(
os.lifecycle().set_game_foreground_task(second),
Err(LifecycleError::ResidentGameAlreadyExists { existing: first, requested: second })
);
}
#[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);
let task_id = os.sessions().create_vm_game_task(42, "Sector Crawl");
let sessions = os.sessions();
let session = sessions.vm_session_for_task(task_id).expect("VM session should exist");
assert_eq!(session.task_id, task_id);
assert_eq!(session.app_id, 42);
assert_eq!(session.title, "Sector Crawl");
assert_eq!(session.app_mode, AppMode::Game);
assert_eq!(sessions.vm_session_count(), 1);
}
#[test]
fn vm_shell_task_creates_vm_session() {
let mut os = SystemOS::new(None);
let task_id = os.sessions().create_vm_shell_task(7, "Settings");
let sessions = os.sessions();
let session = sessions.vm_session_for_task(task_id).expect("VM session should exist");
assert_eq!(session.task_id, task_id);
assert_eq!(session.app_id, 7);
assert_eq!(session.title, "Settings");
assert_eq!(session.app_mode, AppMode::Shell);
assert_eq!(sessions.vm_session_count(), 1);
}
#[test]
fn native_shell_task_does_not_create_vm_session() {
let mut os = SystemOS::new(None);
let task_id = os.sessions().create_native_shell_task(7, "Settings");
let sessions = os.sessions();
assert!(sessions.vm_session_for_task(task_id).is_none());
assert_eq!(sessions.vm_session_count(), 0);
}
#[test]
fn same_resident_game_app_reuses_existing_vm_session() {
let mut os = SystemOS::new(None);
let first = os.sessions().create_vm_game_task(42, "Sector Crawl");
let second = os.sessions().create_vm_game_task(42, "Sector Crawl");
let sessions = os.sessions();
assert_eq!(second, first);
assert_eq!(
sessions.resident_game_session_for_app(42).map(|session| session.task_id),
Some(first)
);
assert_eq!(sessions.vm_session_count(), 1);
}
#[test]
fn vm_sessions_hold_independent_runtime_state() {
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.runtime.tick_index = 100;
game_session.open_files.insert(1, "/game.dat".to_string());
}
{
let mut sessions = os.sessions();
let shell_session =
sessions.vm_session_for_task_mut(shell).expect("shell VM session should exist");
shell_session.runtime.tick_index = 5;
shell_session.open_files.insert(1, "/shell.dat".to_string());
}
let sessions = os.sessions();
let game_session =
sessions.vm_session_for_task(game).expect("game VM session should exist");
let shell_session =
sessions.vm_session_for_task(shell).expect("shell VM session should exist");
assert_eq!(game_session.runtime.tick_index, 100);
assert_eq!(shell_session.runtime.tick_index, 5);
assert_eq!(game_session.open_files.get(&1).map(String::as_str), Some("/game.dat"));
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);
let task_id = os.sessions().create_vm_game_task(42, "Sector Crawl");
os.lifecycle().request_home_from_game(task_id).expect("home request should succeed");
assert_eq!(os.lifecycle().foreground_owner(), ForegroundOwner::Game(task_id));
assert_eq!(
os.lifecycle().resident_game(),
Some(ResidentGame {
task_id,
state: ResidentGameState::PauseRequested { remaining_ticks: 1 },
})
);
assert_eq!(
os.lifecycle().pending_game_lifecycle_events()[0].kind,
GameLifecycleEventKind::Pause
);
assert_eq!(
os.task_manager.get(task_id).expect("task should exist").state,
TaskState::Foreground
);
assert!(os.lifecycle().advance_game_pause_budget(task_id).expect("budget should advance"));
assert_eq!(os.lifecycle().foreground_owner(), ForegroundOwner::Hub);
assert_eq!(
os.lifecycle().resident_game(),
Some(ResidentGame { task_id, state: ResidentGameState::PausedSuspended })
);
assert_eq!(
os.task_manager.get(task_id).expect("task should exist").state,
TaskState::Suspended
);
assert_eq!(process_state_for_task(&os, task_id), ProcessState::Suspended);
}
#[test]
fn shell_foreground_keeps_game_resident_and_marks_it_suspended() {
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().foreground_owner(), ForegroundOwner::Shell(shell));
assert_eq!(
os.lifecycle().resident_game(),
Some(ResidentGame { task_id: game, state: ResidentGameState::PausedSuspended })
);
}
#[test]
fn vm_shell_foreground_suspends_foreground_resident_game() {
let mut os = SystemOS::new(None);
let game = os.sessions().create_vm_game_task(42, "Sector Crawl");
let shell = os.sessions().create_vm_shell_task(7, "Settings");
assert_eq!(os.lifecycle().foreground_owner(), ForegroundOwner::Shell(shell));
assert_eq!(
os.lifecycle().resident_game(),
Some(ResidentGame { task_id: game, state: ResidentGameState::PausedSuspended })
);
assert_eq!(
os.task_manager.get(game).expect("game should exist").state,
TaskState::Suspended
);
assert_eq!(process_state_for_task(&os, game), ProcessState::Suspended);
}
#[test]
fn native_shell_foreground_suspends_foreground_resident_game() {
let mut os = SystemOS::new(None);
let game = os.sessions().create_vm_game_task(42, "Sector Crawl");
let shell = os.sessions().create_native_shell_task(7, "Settings");
assert_eq!(os.lifecycle().foreground_owner(), ForegroundOwner::Shell(shell));
assert_eq!(
os.lifecycle().resident_game(),
Some(ResidentGame { task_id: game, state: ResidentGameState::PausedSuspended })
);
assert_eq!(
os.task_manager.get(game).expect("game should exist").state,
TaskState::Suspended
);
assert_eq!(process_state_for_task(&os, game), ProcessState::Suspended);
}
#[test]
fn lifecycle_exposes_process_kind_for_shell_tasks() {
let mut os = SystemOS::new(None);
let vm_shell = os.sessions().create_vm_shell_task(7, "Settings");
os.lifecycle().close_task(vm_shell).expect("vm shell should close");
let native_shell = os.sessions().create_native_shell_task(8, "Files");
assert_eq!(os.lifecycle().process_kind_for_task(vm_shell), Ok(ProcessKind::VmShell));
assert_eq!(
os.lifecycle().process_kind_for_task(native_shell),
Ok(ProcessKind::NativeShell)
);
}
#[test]
fn second_foreground_shell_is_rejected() {
let mut os = SystemOS::new(None);
let first = os.sessions().create_vm_shell_task(7, "Settings");
let process_id = os.process_manager.spawn_vm_shell(8, "Files");
let second = os.task_manager.create_shell_task(process_id, 8, "Files");
assert_eq!(
os.lifecycle().set_shell_foreground_task(second),
Err(LifecycleError::ForegroundShellAlreadyExists {
existing: first,
requested: second,
})
);
}
#[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);
let shell = os.sessions().create_vm_shell_task(7, "Settings");
os.lifecycle().close_task(shell).expect("close should succeed");
assert_eq!(os.lifecycle().foreground_owner(), ForegroundOwner::Hub);
assert_eq!(
os.task_manager.get(shell).expect("shell should remain").state,
TaskState::Closed
);
}
#[test]
fn suspend_task_marks_task_and_process_suspended() {
let mut os = SystemOS::new(None);
@@ -184,6 +600,10 @@ mod tests {
TaskState::Foreground
);
assert_eq!(process_state_for_task(&os, task_id), ProcessState::Running);
assert_eq!(
os.lifecycle().pending_game_lifecycle_events().last().map(|event| event.kind),
Some(GameLifecycleEventKind::ResumeForeground)
);
}
#[test]
@@ -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,18 +1,26 @@
use crate::{CrashReport, SystemOS};
use crate::task::TaskId;
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;
const SHELL_A_BUTTON: Rect = Rect { x: 112, y: 108, w: 112, h: 48 };
const SHELL_B_BUTTON: Rect = Rect { x: 256, y: 108, w: 112, h: 48 };
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 };
const CLOSE_BUTTON: Rect = Rect { x: 420, y: 24, w: 16, h: 16 };
const VIEWPORT: Rect = Rect { x: 0, y: 0, w: 480, h: 270 };
const HOME_PANEL: Rect = Rect { x: 48, y: 58, w: 384, h: 154 };
const TITLE_PANEL: Rect = Rect { x: 72, y: 34, w: 336, h: 28 };
const GAME_ROW_X: i32 = 72;
const GAME_ROW_Y: i32 = 90;
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 };
@@ -25,10 +33,13 @@ 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 {
home_input_armed: bool,
game_library: GameLibrary,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
@@ -72,9 +83,11 @@ impl NativeShellApp {
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum SystemProfileAction {
LaunchNativeShell(NativeShellApp),
LaunchGame { target: GameSwitchTarget },
KillResidentGame,
CloseShell,
}
@@ -91,13 +104,21 @@ impl Default for PrometeuHub {
impl PrometeuHub {
pub fn new() -> Self {
Self { home_input_armed: false }
Self { home_input_armed: false, game_library: GameLibrary::empty() }
}
pub fn init(&mut self) {
self.home_input_armed = false;
}
pub fn set_game_library(&mut self, game_library: GameLibrary) {
self.game_library = game_library;
}
pub fn game_library(&self) -> &GameLibrary {
&self.game_library
}
pub fn gui_update(
&mut self,
os: &mut SystemOS,
@@ -115,11 +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);
}
@@ -132,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)
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() {
@@ -156,7 +186,23 @@ impl PrometeuHub {
pub fn update_shell_profile(
&mut self,
os: &mut SystemOS,
vm: &mut VirtualMachine,
platform: &mut dyn RuntimePlatform,
) -> SystemProfileUpdate {
let mut action = self.gui_update(os, platform);
if os.windows().focused_window().is_some() && platform.input().pad().start().down {
action = Some(SystemProfileAction::CloseShell);
}
self.render(os, platform);
SystemProfileUpdate { crash: None, action }
}
pub fn update_vm_shell_profile(
&mut self,
os: &mut SystemOS,
task_id: TaskId,
signals: &InputSignals,
platform: &mut dyn RuntimePlatform,
) -> SystemProfileUpdate {
@@ -167,7 +213,7 @@ impl PrometeuHub {
if platform.input().pad().start().down {
action = Some(SystemProfileAction::CloseShell);
} else if action != Some(SystemProfileAction::CloseShell) {
crash = os.vm().tick(vm, signals, platform);
crash = os.vm().tick_session(task_id, signals, platform);
}
}
@@ -175,9 +221,32 @@ impl PrometeuHub {
SystemProfileUpdate { crash, action }
}
pub fn update_native_shell_profile(
&mut self,
os: &mut SystemOS,
platform: &mut dyn RuntimePlatform,
) -> SystemProfileUpdate {
let mut action = self.gui_update(os, platform);
if os.windows().focused_window().is_some() && platform.input().pad().start().down {
action = Some(SystemProfileAction::CloseShell);
}
self.render(os, platform);
SystemProfileUpdate { crash: None, action }
}
}
fn action_for_click(in_shell: bool, x: i32, y: i32, pressed: bool) -> Option<SystemProfileAction> {
fn action_for_click(
in_shell: bool,
x: i32,
y: i32,
pressed: bool,
game_entries: &[crate::GameLibraryEntry],
suspended_game: Option<&SuspendedGameIndicator>,
) -> Option<SystemProfileAction> {
if !pressed {
return None;
}
@@ -186,12 +255,52 @@ fn action_for_click(in_shell: bool, x: i32, y: i32, pressed: bool) -> Option<Sys
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)
.enumerate()
.find(|(index, _entry)| rect_contains(game_row_rect(*index), x, y))
.map(|(_index, entry)| entry)
{
return Some(SystemProfileAction::LaunchGame { target: entry.switch_target() });
}
HOME_BUTTONS
.iter()
.find(|button| rect_contains(button.rect, x, y))
.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,
y: GAME_ROW_Y + (GAME_ROW_H + GAME_ROW_GAP) * index as i32,
w: GAME_ROW_W,
h: GAME_ROW_H,
}
}
fn rect_contains(rect: Rect, x: i32, y: i32) -> bool {
x >= rect.x && x < rect.x + rect.w && y >= rect.y && y < rect.y + rect.h
}
@@ -203,7 +312,12 @@ fn activation_input_down(input: &dyn InputPlatform) -> bool {
|| input.pad().start().down
}
fn render_home_packet(pointer_x: i32, pointer_y: i32) -> ShellUiFramePacket {
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 });
fill_rect(&mut commands, VIEWPORT, COLOR_BG);
@@ -217,26 +331,36 @@ fn render_home_packet(pointer_x: i32, pointer_y: i32) -> ShellUiFramePacket {
);
draw_panel(&mut commands, HOME_PANEL, COLOR_PANEL, COLOR_BORDER);
draw_buffer_text(
&mut commands,
HOME_PANEL.x + 26,
HOME_PANEL.y + 22,
"Native Shell Apps",
COLOR_TEXT,
);
draw_buffer_text(&mut commands, HOME_PANEL.x + 26, HOME_PANEL.y + 22, "Games", COLOR_TEXT);
draw_buffer_text(
&mut commands,
HOME_PANEL.x + 26,
HOME_PANEL.y + 40,
"first retro ui slice",
"local library",
COLOR_MUTED,
);
if game_entries.is_empty() {
draw_buffer_text(&mut commands, GAME_ROW_X, GAME_ROW_Y + 6, "No games found", COLOR_MUTED);
} else {
for (index, entry) in game_entries.iter().take(MAX_HOME_GAME_ROWS).enumerate() {
let rect = game_row_rect(index);
let hovered = rect_contains(rect, pointer_x, pointer_y);
let text = format!("{} #{} {}", entry.title, entry.app_id, entry.app_version);
draw_game_row(&mut commands, rect, &text, hovered);
}
}
for button in HOME_BUTTONS {
let hovered = rect_contains(button.rect, pointer_x, pointer_y);
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)
}
@@ -326,9 +450,50 @@ fn draw_button(commands: &mut Vec<GfxUiCommand>, rect: Rect, label: &str, hovere
Rect { x: rect.x + 3, y: rect.y + 3, w: rect.w - 6, h: rect.h - 6 },
COLOR_MUTED,
);
fill_rect(commands, Rect { x: rect.x + 12, y: rect.y + 12, w: 16, h: 24 }, border);
draw_rect(commands, Rect { x: rect.x + 34, y: rect.y + 12, w: 62, h: 24 }, COLOR_PANEL_DARK);
draw_buffer_text(commands, rect.x + 40, rect.y + 21, label, COLOR_TEXT);
fill_rect(commands, Rect { x: rect.x + 12, y: rect.y + 8, w: 14, h: 16 }, border);
draw_rect(commands, Rect { x: rect.x + 34, y: rect.y + 8, w: 62, h: 16 }, COLOR_PANEL_DARK);
draw_buffer_text(commands, rect.x + 40, rect.y + 13, label, COLOR_TEXT);
}
fn draw_game_row(commands: &mut Vec<GfxUiCommand>, rect: Rect, label: &str, hovered: bool) {
let fill = if hovered { COLOR_BUTTON_ACTIVE } else { COLOR_PANEL_DARK };
let border = if hovered { COLOR_HILITE } else { COLOR_MUTED };
fill_rect(commands, rect, fill);
draw_rect(commands, rect, border);
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) {
@@ -338,11 +503,47 @@ fn draw_buffer_text(commands: &mut Vec<GfxUiCommand>, x: i32, y: i32, text: &str
#[cfg(test)]
mod tests {
use super::*;
use crate::task::TaskId;
use crate::windows::WindowOwner;
use prometeu_drivers::TestPlatform;
use prometeu_hal::{InputSignals, RuntimePlatform};
use std::path::PathBuf;
fn focused_native_shell_fixture(
signals: &InputSignals,
) -> (PrometeuHub, SystemOS, TestPlatform) {
let hub = PrometeuHub::new();
let mut os = SystemOS::new(None);
let mut platform = TestPlatform::new();
{
let mut windows = os.windows();
let id = windows.add_window(
"ShellA".to_string(),
WindowOwner::Task(TaskId(7)),
SHELL_FRAME,
Color::GREEN,
);
windows.set_focus(id);
}
platform.input_mut().pad_mut().begin_frame(signals);
platform.input_mut().touch_mut().begin_frame(signals);
(hub, os, platform)
}
#[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))
);
}
@@ -354,7 +555,9 @@ mod tests {
false,
SHELL_B_BUTTON.x + SHELL_B_BUTTON.w - 1,
SHELL_B_BUTTON.y,
true
true,
&[],
None
),
Some(SystemProfileAction::LaunchNativeShell(NativeShellApp::ShellB))
);
@@ -363,18 +566,35 @@ mod tests {
#[test]
fn button_hit_test_excludes_right_and_bottom_edges() {
assert_eq!(
action_for_click(false, SHELL_A_BUTTON.x + SHELL_A_BUTTON.w, SHELL_A_BUTTON.y, true),
action_for_click(
false,
SHELL_A_BUTTON.x + SHELL_A_BUTTON.w,
SHELL_A_BUTTON.y,
true,
&[],
None
),
None
);
assert_eq!(
action_for_click(false, SHELL_A_BUTTON.x, SHELL_A_BUTTON.y + SHELL_A_BUTTON.h, true),
action_for_click(
false,
SHELL_A_BUTTON.x,
SHELL_A_BUTTON.y + SHELL_A_BUTTON.h,
true,
&[],
None
),
None
);
}
#[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]
@@ -383,13 +603,54 @@ mod tests {
assert!(!hub.home_input_armed);
}
#[test]
fn game_row_click_emits_launch_game_action() {
let entry = crate::GameLibraryEntry {
manifest: prometeu_hal::cartridge::CartridgeManifest {
magic: "PMTU".to_string(),
cartridge_version: 1,
app_id: 42,
title: "Stress".to_string(),
app_version: "1.0.0".to_string(),
app_mode: prometeu_hal::app_mode::AppMode::Game,
capabilities: vec![],
},
title: "Stress".to_string(),
app_id: 42,
app_version: "1.0.0".to_string(),
path: PathBuf::from("test-cartridges/stress-console"),
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,
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]
@@ -403,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| {
@@ -411,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));
@@ -420,4 +798,35 @@ mod tests {
CLOSE_BUTTON.y + CLOSE_BUTTON.h - 1
));
}
#[test]
fn native_shell_profile_start_close_does_not_tick_vm() {
let signals = InputSignals { start_signal: true, ..Default::default() };
let (mut hub, mut os, mut platform) = focused_native_shell_fixture(&signals);
let tick_index_before_update = os.vm().tick_index();
let outcome = hub.update_native_shell_profile(&mut os, &mut platform);
assert_eq!(outcome.action, Some(SystemProfileAction::CloseShell));
assert!(outcome.crash.is_none());
assert_eq!(os.vm().tick_index(), tick_index_before_update);
}
#[test]
fn native_shell_profile_close_button_does_not_tick_vm() {
let signals = InputSignals {
f_signal: true,
x_pos: CLOSE_BUTTON.x,
y_pos: CLOSE_BUTTON.y,
..Default::default()
};
let (mut hub, mut os, mut platform) = focused_native_shell_fixture(&signals);
let tick_index_before_update = os.vm().tick_index();
let outcome = hub.update_native_shell_profile(&mut os, &mut platform);
assert_eq!(outcome.action, Some(SystemProfileAction::CloseShell));
assert!(outcome.crash.is_none());
assert_eq!(os.vm().tick_index(), tick_index_before_update);
}
}
@@ -0,0 +1,601 @@
use std::collections::VecDeque;
use std::panic::{AssertUnwindSafe, catch_unwind};
use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::mpsc::{self, Receiver, RecvTimeoutError};
use std::sync::{Arc, Condvar, Mutex};
use std::thread::{self, JoinHandle};
use std::time::Duration;
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct AsyncWorkJobId(u64);
impl AsyncWorkJobId {
pub const ZERO: Self = Self(0);
pub fn new(value: u64) -> Self {
Self(value)
}
pub fn get(self) -> u64 {
self.0
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum AsyncWorkJobKind {
Asset,
Memcard,
Fs,
Test,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum AsyncWorkPriority {
MemcardCommitWrite,
FsWriteConfig,
AssetLoad,
NonCriticalReadList,
}
impl AsyncWorkPriority {
const fn rank(self) -> u8 {
match self {
Self::MemcardCommitWrite => 0,
Self::FsWriteConfig => 1,
Self::AssetLoad => 2,
Self::NonCriticalReadList => 3,
}
}
}
impl AsyncWorkJobKind {
pub const fn default_priority(self) -> AsyncWorkPriority {
match self {
Self::Memcard => AsyncWorkPriority::MemcardCommitWrite,
Self::Fs => AsyncWorkPriority::FsWriteConfig,
Self::Asset => AsyncWorkPriority::AssetLoad,
Self::Test => AsyncWorkPriority::NonCriticalReadList,
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum AsyncWorkJobOutcome {
Completed,
Canceled,
Failed,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum AsyncWorkLaneError {
Shutdown,
WorkerPanic,
ShutdownTimeout,
InternalFailure,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct AsyncWorkLaneConfig {
pub shutdown_timeout: Duration,
}
impl Default for AsyncWorkLaneConfig {
fn default() -> Self {
Self { shutdown_timeout: Duration::from_millis(250) }
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct AsyncWorkActiveJob {
pub id: AsyncWorkJobId,
pub kind: AsyncWorkJobKind,
pub priority: AsyncWorkPriority,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub struct AsyncWorkLaneTelemetry {
pub submitted_jobs: u64,
pub started_jobs: u64,
pub completed_jobs: u64,
pub canceled_jobs: u64,
pub failed_jobs: u64,
pub shutdown_discards: u64,
pub pending_depth: usize,
pub max_pending_depth: usize,
pub active_job_id: Option<AsyncWorkJobId>,
pub last_submitted_job_id: Option<AsyncWorkJobId>,
pub last_started_job_id: Option<AsyncWorkJobId>,
pub last_closed_job_id: Option<AsyncWorkJobId>,
}
impl AsyncWorkLaneTelemetry {
fn record_submitted(&mut self, job_id: AsyncWorkJobId, pending_depth: usize) {
self.submitted_jobs += 1;
self.pending_depth = pending_depth;
self.max_pending_depth = self.max_pending_depth.max(pending_depth);
self.last_submitted_job_id = Some(job_id);
}
fn record_started(&mut self, job_id: AsyncWorkJobId, pending_depth: usize) {
self.started_jobs += 1;
self.pending_depth = pending_depth;
self.active_job_id = Some(job_id);
self.last_started_job_id = Some(job_id);
}
fn record_closed(&mut self, job_id: AsyncWorkJobId, outcome: AsyncWorkJobOutcome) {
match outcome {
AsyncWorkJobOutcome::Completed => self.completed_jobs += 1,
AsyncWorkJobOutcome::Canceled => self.canceled_jobs += 1,
AsyncWorkJobOutcome::Failed => self.failed_jobs += 1,
}
self.active_job_id = None;
self.last_closed_job_id = Some(job_id);
}
fn record_shutdown_discards(&mut self, count: usize) {
self.shutdown_discards += count as u64;
self.pending_depth = 0;
}
}
#[derive(Clone, Debug)]
pub struct AsyncWorkCancelToken {
canceled: Arc<AtomicBool>,
}
impl AsyncWorkCancelToken {
fn new() -> Self {
Self { canceled: Arc::new(AtomicBool::new(false)) }
}
pub fn cancel(&self) {
self.canceled.store(true, Ordering::Relaxed);
}
pub fn is_canceled(&self) -> bool {
self.canceled.load(Ordering::Relaxed)
}
}
#[derive(Clone, Debug)]
pub struct AsyncWorkJobContext {
pub job_id: AsyncWorkJobId,
pub kind: AsyncWorkJobKind,
pub priority: AsyncWorkPriority,
cancel_token: AsyncWorkCancelToken,
}
impl AsyncWorkJobContext {
pub fn is_canceled(&self) -> bool {
self.cancel_token.is_canceled()
}
}
type AsyncWorkFn = Box<dyn FnOnce(AsyncWorkJobContext) -> AsyncWorkJobOutcome + Send + 'static>;
struct PendingAsyncWorkJob {
id: AsyncWorkJobId,
kind: AsyncWorkJobKind,
priority: AsyncWorkPriority,
cancel_token: AsyncWorkCancelToken,
work: AsyncWorkFn,
}
struct RunningAsyncWorkJob {
id: AsyncWorkJobId,
kind: AsyncWorkJobKind,
priority: AsyncWorkPriority,
cancel_token: AsyncWorkCancelToken,
work: AsyncWorkFn,
}
#[derive(Default)]
struct AsyncWorkLaneState {
next_job_id: u64,
pending: VecDeque<PendingAsyncWorkJob>,
active: Option<AsyncWorkActiveJob>,
active_cancel_token: Option<AsyncWorkCancelToken>,
shutdown_requested: bool,
telemetry: AsyncWorkLaneTelemetry,
}
#[derive(Default)]
pub struct AsyncWorkLane {
state: Mutex<AsyncWorkLaneState>,
ready: Condvar,
}
impl AsyncWorkLane {
pub fn submit(
&self,
kind: AsyncWorkJobKind,
work: impl FnOnce(AsyncWorkJobContext) -> AsyncWorkJobOutcome + Send + 'static,
) -> Result<AsyncWorkJobId, AsyncWorkLaneError> {
self.submit_with_priority(kind, kind.default_priority(), work)
}
pub fn submit_with_priority(
&self,
kind: AsyncWorkJobKind,
priority: AsyncWorkPriority,
work: impl FnOnce(AsyncWorkJobContext) -> AsyncWorkJobOutcome + Send + 'static,
) -> Result<AsyncWorkJobId, AsyncWorkLaneError> {
let mut state = self.state.lock().map_err(|_| AsyncWorkLaneError::InternalFailure)?;
if state.shutdown_requested {
return Err(AsyncWorkLaneError::Shutdown);
}
state.next_job_id += 1;
let id = AsyncWorkJobId::new(state.next_job_id);
let cancel_token = AsyncWorkCancelToken::new();
let job = PendingAsyncWorkJob { id, kind, priority, cancel_token, work: Box::new(work) };
let insert_at = state
.pending
.iter()
.position(|pending| priority.rank() < pending.priority.rank())
.unwrap_or(state.pending.len());
state.pending.insert(insert_at, job);
let pending_depth = state.pending.len();
state.telemetry.record_submitted(id, pending_depth);
self.ready.notify_one();
Ok(id)
}
pub fn submit_memcard_commit_write(
&self,
work: impl FnOnce(AsyncWorkJobContext) -> AsyncWorkJobOutcome + Send + 'static,
) -> Result<AsyncWorkJobId, AsyncWorkLaneError> {
self.submit_with_priority(
AsyncWorkJobKind::Memcard,
AsyncWorkPriority::MemcardCommitWrite,
work,
)
}
pub fn submit_fs_write_config(
&self,
work: impl FnOnce(AsyncWorkJobContext) -> AsyncWorkJobOutcome + Send + 'static,
) -> Result<AsyncWorkJobId, AsyncWorkLaneError> {
self.submit_with_priority(AsyncWorkJobKind::Fs, AsyncWorkPriority::FsWriteConfig, work)
}
pub fn submit_asset_load(
&self,
work: impl FnOnce(AsyncWorkJobContext) -> AsyncWorkJobOutcome + Send + 'static,
) -> Result<AsyncWorkJobId, AsyncWorkLaneError> {
self.submit_with_priority(AsyncWorkJobKind::Asset, AsyncWorkPriority::AssetLoad, work)
}
pub fn submit_non_critical_read_list(
&self,
kind: AsyncWorkJobKind,
work: impl FnOnce(AsyncWorkJobContext) -> AsyncWorkJobOutcome + Send + 'static,
) -> Result<AsyncWorkJobId, AsyncWorkLaneError> {
self.submit_with_priority(kind, AsyncWorkPriority::NonCriticalReadList, work)
}
pub fn request_cancel(&self, job_id: AsyncWorkJobId) -> bool {
let state = self.state.lock().unwrap();
if let Some(token) = state
.active
.filter(|active| active.id == job_id)
.and(state.active_cancel_token.as_ref())
{
token.cancel();
return true;
}
for pending in &state.pending {
if pending.id == job_id {
pending.cancel_token.cancel();
return true;
}
}
false
}
pub fn active_job(&self) -> Option<AsyncWorkActiveJob> {
self.state.lock().unwrap().active
}
pub fn pending_depth(&self) -> usize {
self.state.lock().unwrap().pending.len()
}
pub fn telemetry(&self) -> AsyncWorkLaneTelemetry {
self.state.lock().unwrap().telemetry
}
pub fn request_shutdown(&self) {
let mut state = self.state.lock().unwrap();
state.shutdown_requested = true;
if let Some(token) = &state.active_cancel_token {
token.cancel();
}
self.ready.notify_all();
}
fn wait_take(&self) -> Option<RunningAsyncWorkJob> {
self.wait_take_with_hook(|| {})
}
fn wait_take_with_hook(&self, mut before_wait: impl FnMut()) -> Option<RunningAsyncWorkJob> {
let mut state = self.state.lock().unwrap();
loop {
if state.shutdown_requested {
let discarded = state.pending.len();
state.pending.clear();
state.telemetry.record_shutdown_discards(discarded);
return None;
}
if let Some(pending) = state.pending.pop_front() {
let active = AsyncWorkActiveJob {
id: pending.id,
kind: pending.kind,
priority: pending.priority,
};
state.active = Some(active);
state.active_cancel_token = Some(pending.cancel_token.clone());
let pending_depth = state.pending.len();
state.telemetry.record_started(pending.id, pending_depth);
return Some(RunningAsyncWorkJob {
id: pending.id,
kind: pending.kind,
priority: pending.priority,
cancel_token: pending.cancel_token,
work: pending.work,
});
}
before_wait();
state = self.ready.wait(state).unwrap();
}
}
fn record_finished(&self, job_id: AsyncWorkJobId, outcome: AsyncWorkJobOutcome) {
let mut state = self.state.lock().unwrap();
if state.active.is_some_and(|active| active.id == job_id) {
state.active = None;
state.active_cancel_token = None;
}
state.telemetry.record_closed(job_id, outcome);
}
}
pub struct AsyncWorkLaneController {
config: AsyncWorkLaneConfig,
lane: Arc<AsyncWorkLane>,
handle: Option<JoinHandle<()>>,
done_rx: Receiver<Result<(), AsyncWorkLaneError>>,
}
impl AsyncWorkLaneController {
pub fn start(config: AsyncWorkLaneConfig, lane: Arc<AsyncWorkLane>) -> Self {
let worker_lane = Arc::clone(&lane);
let (done_tx, done_rx) = mpsc::channel();
let handle = thread::spawn(move || {
let result = catch_unwind(AssertUnwindSafe(|| run_async_work_loop(worker_lane)))
.map_err(|_| AsyncWorkLaneError::WorkerPanic);
let _ = done_tx.send(result);
});
Self { config, lane, handle: Some(handle), done_rx }
}
pub fn lane(&self) -> Arc<AsyncWorkLane> {
Arc::clone(&self.lane)
}
pub fn stop(&mut self) -> Result<(), AsyncWorkLaneError> {
self.lane.request_shutdown();
match self.done_rx.recv_timeout(self.config.shutdown_timeout) {
Ok(result) => {
if let Some(handle) = self.handle.take()
&& handle.join().is_err()
{
return Err(AsyncWorkLaneError::WorkerPanic);
}
result
}
Err(RecvTimeoutError::Timeout) => Err(AsyncWorkLaneError::ShutdownTimeout),
Err(RecvTimeoutError::Disconnected) => Err(AsyncWorkLaneError::InternalFailure),
}
}
}
impl Drop for AsyncWorkLaneController {
fn drop(&mut self) {
if self.handle.is_some() {
let _ = self.stop();
}
}
}
fn run_async_work_loop(lane: Arc<AsyncWorkLane>) {
while let Some(job) = lane.wait_take() {
let context = AsyncWorkJobContext {
job_id: job.id,
kind: job.kind,
priority: job.priority,
cancel_token: job.cancel_token,
};
let result = catch_unwind(AssertUnwindSafe(|| (job.work)(context)))
.unwrap_or(AsyncWorkJobOutcome::Failed);
lane.record_finished(job.id, result);
}
}
#[cfg(test)]
mod tests {
use super::*;
use std::sync::mpsc;
#[test]
fn async_work_lane_runs_jobs_in_submission_order() {
let lane = Arc::new(AsyncWorkLane::default());
let mut controller =
AsyncWorkLaneController::start(AsyncWorkLaneConfig::default(), Arc::clone(&lane));
let (tx, rx) = mpsc::channel();
lane.submit(AsyncWorkJobKind::Test, {
let tx = tx.clone();
move |_| {
tx.send(1).unwrap();
AsyncWorkJobOutcome::Completed
}
})
.unwrap();
lane.submit(AsyncWorkJobKind::Test, {
let tx = tx.clone();
move |_| {
tx.send(2).unwrap();
AsyncWorkJobOutcome::Completed
}
})
.unwrap();
assert_eq!(rx.recv().unwrap(), 1);
assert_eq!(rx.recv().unwrap(), 2);
controller.stop().unwrap();
let telemetry = lane.telemetry();
assert_eq!(telemetry.submitted_jobs, 2);
assert_eq!(telemetry.started_jobs, 2);
assert_eq!(telemetry.completed_jobs, 2);
}
#[test]
fn async_work_lane_runs_higher_priority_io_before_assets() {
let lane = Arc::new(AsyncWorkLane::default());
let (tx, rx) = mpsc::channel();
lane.submit_asset_load({
let tx = tx.clone();
move |ctx| {
tx.send((ctx.kind, ctx.priority)).unwrap();
AsyncWorkJobOutcome::Completed
}
})
.unwrap();
lane.submit_non_critical_read_list(AsyncWorkJobKind::Fs, {
let tx = tx.clone();
move |ctx| {
tx.send((ctx.kind, ctx.priority)).unwrap();
AsyncWorkJobOutcome::Completed
}
})
.unwrap();
lane.submit_memcard_commit_write({
let tx = tx.clone();
move |ctx| {
tx.send((ctx.kind, ctx.priority)).unwrap();
AsyncWorkJobOutcome::Completed
}
})
.unwrap();
lane.submit_fs_write_config({
let tx = tx.clone();
move |ctx| {
tx.send((ctx.kind, ctx.priority)).unwrap();
AsyncWorkJobOutcome::Completed
}
})
.unwrap();
let mut controller =
AsyncWorkLaneController::start(AsyncWorkLaneConfig::default(), Arc::clone(&lane));
assert_eq!(
rx.recv().unwrap(),
(AsyncWorkJobKind::Memcard, AsyncWorkPriority::MemcardCommitWrite)
);
assert_eq!(rx.recv().unwrap(), (AsyncWorkJobKind::Fs, AsyncWorkPriority::FsWriteConfig));
assert_eq!(rx.recv().unwrap(), (AsyncWorkJobKind::Asset, AsyncWorkPriority::AssetLoad));
assert_eq!(
rx.recv().unwrap(),
(AsyncWorkJobKind::Fs, AsyncWorkPriority::NonCriticalReadList)
);
controller.stop().unwrap();
}
#[test]
fn async_work_lane_has_one_active_job() {
let lane = Arc::new(AsyncWorkLane::default());
let mut controller =
AsyncWorkLaneController::start(AsyncWorkLaneConfig::default(), Arc::clone(&lane));
let (first_started_tx, first_started_rx) = mpsc::channel();
let (release_first_tx, release_first_rx) = mpsc::channel();
let (second_started_tx, second_started_rx) = mpsc::channel();
let first = lane
.submit(AsyncWorkJobKind::Test, move |_| {
first_started_tx.send(()).unwrap();
release_first_rx.recv().unwrap();
AsyncWorkJobOutcome::Completed
})
.unwrap();
let second = lane
.submit(AsyncWorkJobKind::Test, move |_| {
second_started_tx.send(()).unwrap();
AsyncWorkJobOutcome::Completed
})
.unwrap();
first_started_rx.recv().unwrap();
assert_eq!(lane.active_job().unwrap().id, first);
assert_eq!(lane.pending_depth(), 1);
assert!(second_started_rx.try_recv().is_err());
release_first_tx.send(()).unwrap();
second_started_rx.recv().unwrap();
assert_eq!(lane.telemetry().last_started_job_id, Some(second));
controller.stop().unwrap();
}
#[test]
fn async_work_lane_supports_cooperative_cancellation() {
let lane = Arc::new(AsyncWorkLane::default());
let mut controller =
AsyncWorkLaneController::start(AsyncWorkLaneConfig::default(), Arc::clone(&lane));
let (started_tx, started_rx) = mpsc::channel();
let job_id = lane
.submit(AsyncWorkJobKind::Test, move |ctx| {
started_tx.send(()).unwrap();
while !ctx.is_canceled() {
std::thread::yield_now();
}
AsyncWorkJobOutcome::Canceled
})
.unwrap();
started_rx.recv().unwrap();
assert!(lane.request_cancel(job_id));
controller.stop().unwrap();
assert_eq!(lane.telemetry().canceled_jobs, 1);
}
#[test]
fn async_work_lane_rejects_submit_after_shutdown() {
let lane = Arc::new(AsyncWorkLane::default());
lane.request_shutdown();
let result = lane.submit(AsyncWorkJobKind::Test, |_| AsyncWorkJobOutcome::Completed);
assert_eq!(result, Err(AsyncWorkLaneError::Shutdown));
}
#[test]
fn async_work_lane_shutdown_discards_pending_jobs() {
let lane = Arc::new(AsyncWorkLane::default());
lane.submit(AsyncWorkJobKind::Test, |_| AsyncWorkJobOutcome::Completed).unwrap();
assert_eq!(lane.pending_depth(), 1);
lane.request_shutdown();
assert!(lane.wait_take().is_none());
assert_eq!(lane.pending_depth(), 0);
assert_eq!(lane.telemetry().shutdown_discards, 1);
}
}
@@ -0,0 +1,330 @@
use crate::task::TaskId;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ForegroundOwner {
Hub,
Game(TaskId),
Shell(TaskId),
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ResidentGameState {
Foreground,
PauseRequested { remaining_ticks: u8 },
ResumeRequested,
PausedSuspended,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct ResidentGame {
pub task_id: TaskId,
pub state: ResidentGameState,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ForegroundStackError {
ResidentGameAlreadyExists { existing: TaskId, requested: TaskId },
ForegroundShellAlreadyExists { existing: TaskId, requested: TaskId },
TaskIsNotResidentGame(TaskId),
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ForegroundStack {
owner: ForegroundOwner,
resident_game: Option<ResidentGame>,
}
impl Default for ForegroundStack {
fn default() -> Self {
Self { owner: ForegroundOwner::Hub, resident_game: None }
}
}
impl ForegroundStack {
pub fn new() -> Self {
Self::default()
}
pub fn owner(&self) -> ForegroundOwner {
self.owner
}
pub fn resident_game(&self) -> Option<ResidentGame> {
self.resident_game
}
pub fn resident_game_task(&self) -> Option<TaskId> {
self.resident_game.map(|game| game.task_id)
}
pub fn set_game_foreground(&mut self, task_id: TaskId) -> Result<(), ForegroundStackError> {
if let Some(game) = self.resident_game
&& game.task_id != task_id
{
return Err(ForegroundStackError::ResidentGameAlreadyExists {
existing: game.task_id,
requested: task_id,
});
}
self.resident_game = Some(ResidentGame { task_id, state: ResidentGameState::Foreground });
self.owner = ForegroundOwner::Game(task_id);
Ok(())
}
pub fn request_home_from_game(
&mut self,
task_id: TaskId,
pause_budget_ticks: u8,
) -> Result<(), ForegroundStackError> {
match self.resident_game {
Some(game) if game.task_id == task_id => {
if !matches!(
game.state,
ResidentGameState::PauseRequested { .. } | ResidentGameState::PausedSuspended
) {
self.resident_game = Some(ResidentGame {
task_id,
state: ResidentGameState::PauseRequested {
remaining_ticks: pause_budget_ticks.max(1),
},
});
}
Ok(())
}
_ => Err(ForegroundStackError::TaskIsNotResidentGame(task_id)),
}
}
pub fn advance_pause_budget(&mut self, task_id: TaskId) -> Result<bool, ForegroundStackError> {
match self.resident_game {
Some(game)
if game.task_id == task_id
&& matches!(
game.state,
ResidentGameState::PauseRequested { remaining_ticks: 1 }
) =>
{
self.resident_game =
Some(ResidentGame { task_id, state: ResidentGameState::PausedSuspended });
self.owner = ForegroundOwner::Hub;
Ok(true)
}
Some(game)
if game.task_id == task_id
&& matches!(game.state, ResidentGameState::PauseRequested { .. }) =>
{
let ResidentGameState::PauseRequested { remaining_ticks } = game.state else {
unreachable!();
};
self.resident_game = Some(ResidentGame {
task_id,
state: ResidentGameState::PauseRequested {
remaining_ticks: remaining_ticks.saturating_sub(1).max(1),
},
});
Ok(false)
}
Some(game) if game.task_id == task_id => Ok(false),
_ => Err(ForegroundStackError::TaskIsNotResidentGame(task_id)),
}
}
pub fn request_resume_game(&mut self, task_id: TaskId) -> Result<(), ForegroundStackError> {
match self.resident_game {
Some(game) if game.task_id == task_id => {
self.resident_game =
Some(ResidentGame { task_id, state: ResidentGameState::ResumeRequested });
Ok(())
}
_ => Err(ForegroundStackError::TaskIsNotResidentGame(task_id)),
}
}
pub fn complete_resume_game(&mut self, task_id: TaskId) -> Result<(), ForegroundStackError> {
match self.resident_game {
Some(game) if game.task_id == task_id => {
self.resident_game =
Some(ResidentGame { task_id, state: ResidentGameState::Foreground });
self.owner = ForegroundOwner::Game(task_id);
Ok(())
}
_ => Err(ForegroundStackError::TaskIsNotResidentGame(task_id)),
}
}
pub fn set_shell_foreground(&mut self, task_id: TaskId) -> Result<(), ForegroundStackError> {
if let ForegroundOwner::Shell(existing) = self.owner
&& existing != task_id
{
return Err(ForegroundStackError::ForegroundShellAlreadyExists {
existing,
requested: task_id,
});
}
if let Some(game) = self.resident_game {
self.resident_game = Some(ResidentGame {
task_id: game.task_id,
state: ResidentGameState::PausedSuspended,
});
}
self.owner = ForegroundOwner::Shell(task_id);
Ok(())
}
pub fn return_to_hub(&mut self) {
self.owner = ForegroundOwner::Hub;
}
pub fn clear_resident_game(&mut self, task_id: TaskId) {
if self.resident_game_task() == Some(task_id) {
self.resident_game = None;
}
if self.owner == ForegroundOwner::Game(task_id) {
self.owner = ForegroundOwner::Hub;
}
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn foreground_stack_starts_at_hub() {
let stack = ForegroundStack::new();
assert_eq!(stack.owner(), ForegroundOwner::Hub);
assert_eq!(stack.resident_game(), None);
}
#[test]
fn setting_game_foreground_registers_resident_game() {
let mut stack = ForegroundStack::new();
let game = TaskId(7);
stack.set_game_foreground(game).expect("game should become foreground");
assert_eq!(stack.owner(), ForegroundOwner::Game(game));
assert_eq!(
stack.resident_game(),
Some(ResidentGame { task_id: game, state: ResidentGameState::Foreground })
);
}
#[test]
fn second_resident_game_is_rejected() {
let mut stack = ForegroundStack::new();
stack.set_game_foreground(TaskId(1)).expect("first game should be accepted");
assert_eq!(
stack.set_game_foreground(TaskId(2)),
Err(ForegroundStackError::ResidentGameAlreadyExists {
existing: TaskId(1),
requested: TaskId(2),
})
);
}
#[test]
fn home_request_moves_resident_game_to_pause_requested() {
let mut stack = ForegroundStack::new();
let game = TaskId(3);
stack.set_game_foreground(game).expect("game should be foreground");
stack.request_home_from_game(game, 2).expect("home request should pause game");
assert_eq!(stack.owner(), ForegroundOwner::Game(game));
assert_eq!(
stack.resident_game(),
Some(ResidentGame {
task_id: game,
state: ResidentGameState::PauseRequested { remaining_ticks: 2 },
})
);
}
#[test]
fn pause_budget_expiry_suspends_game_and_returns_to_hub() {
let mut stack = ForegroundStack::new();
let game = TaskId(3);
stack.set_game_foreground(game).expect("game should be foreground");
stack.request_home_from_game(game, 1).expect("home request should pause game");
assert!(stack.advance_pause_budget(game).expect("budget should advance"));
assert_eq!(stack.owner(), ForegroundOwner::Hub);
assert_eq!(
stack.resident_game(),
Some(ResidentGame { task_id: game, state: ResidentGameState::PausedSuspended })
);
}
#[test]
fn pause_budget_decrements_before_expiry() {
let mut stack = ForegroundStack::new();
let game = TaskId(3);
stack.set_game_foreground(game).expect("game should be foreground");
stack.request_home_from_game(game, 2).expect("home request should pause game");
assert!(!stack.advance_pause_budget(game).expect("budget should advance"));
assert_eq!(stack.owner(), ForegroundOwner::Game(game));
assert_eq!(
stack.resident_game(),
Some(ResidentGame {
task_id: game,
state: ResidentGameState::PauseRequested { remaining_ticks: 1 },
})
);
assert!(stack.advance_pause_budget(game).expect("budget should expire"));
assert_eq!(stack.owner(), ForegroundOwner::Hub);
assert_eq!(
stack.resident_game(),
Some(ResidentGame { task_id: game, state: ResidentGameState::PausedSuspended })
);
}
#[test]
fn resume_request_precedes_game_foreground_restore() {
let mut stack = ForegroundStack::new();
let game = TaskId(3);
stack.set_game_foreground(game).expect("game should be foreground");
stack.request_home_from_game(game, 1).expect("home request should pause game");
stack.advance_pause_budget(game).expect("budget should expire");
stack.request_resume_game(game).expect("resume should be requested");
assert_eq!(stack.owner(), ForegroundOwner::Hub);
assert_eq!(
stack.resident_game(),
Some(ResidentGame { task_id: game, state: ResidentGameState::ResumeRequested })
);
stack.complete_resume_game(game).expect("resume should complete");
assert_eq!(stack.owner(), ForegroundOwner::Game(game));
assert_eq!(
stack.resident_game(),
Some(ResidentGame { task_id: game, state: ResidentGameState::Foreground })
);
}
#[test]
fn shell_foreground_keeps_resident_game() {
let mut stack = ForegroundStack::new();
let game = TaskId(3);
let shell = TaskId(4);
stack.set_game_foreground(game).expect("game should be foreground");
stack.request_home_from_game(game, 1).expect("home request should suspend game");
stack.advance_pause_budget(game).expect("budget should expire");
stack.set_shell_foreground(shell).expect("shell should become foreground");
assert_eq!(stack.owner(), ForegroundOwner::Shell(shell));
assert_eq!(stack.resident_game_task(), Some(game));
}
}
@@ -8,4 +8,4 @@ pub use fs_backend::FsBackend;
pub use fs_entry::FsEntry;
pub use fs_error::FsError;
pub use fs_state::FsState;
pub use virtual_fs::VirtualFS;
pub use virtual_fs::{FsAsyncLaneOperation, VirtualFS};
@@ -1,4 +1,5 @@
use crate::fs::{FsBackend, FsEntry, FsError};
use crate::services::async_work::{AsyncWorkJobKind, AsyncWorkPriority};
/// Virtual Filesystem (VFS) interface for Prometeu.
///
@@ -13,6 +14,29 @@ pub struct VirtualFS {
backend: Option<Box<dyn FsBackend>>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum FsAsyncLaneOperation {
Write,
Delete,
Config,
Read,
ListDir,
Exists,
}
impl FsAsyncLaneOperation {
pub const fn job_kind(self) -> AsyncWorkJobKind {
AsyncWorkJobKind::Fs
}
pub const fn priority(self) -> AsyncWorkPriority {
match self {
Self::Write | Self::Delete | Self::Config => AsyncWorkPriority::FsWriteConfig,
Self::Read | Self::ListDir | Self::Exists => AsyncWorkPriority::NonCriticalReadList,
}
}
}
impl Default for VirtualFS {
fn default() -> Self {
Self::new()
@@ -242,4 +266,18 @@ mod tests {
assert!(matches!(vfs.delete("/"), Err(FsError::PermissionDenied)));
assert_eq!(calls.delete.load(Ordering::Relaxed), 0);
}
#[test]
fn fs_async_lane_operations_classify_priority_without_public_api_changes() {
assert_eq!(FsAsyncLaneOperation::Write.job_kind(), AsyncWorkJobKind::Fs);
assert_eq!(FsAsyncLaneOperation::Write.priority(), AsyncWorkPriority::FsWriteConfig);
assert_eq!(FsAsyncLaneOperation::Delete.priority(), AsyncWorkPriority::FsWriteConfig);
assert_eq!(FsAsyncLaneOperation::Config.priority(), AsyncWorkPriority::FsWriteConfig);
assert_eq!(FsAsyncLaneOperation::Read.priority(), AsyncWorkPriority::NonCriticalReadList);
assert_eq!(
FsAsyncLaneOperation::ListDir.priority(),
AsyncWorkPriority::NonCriticalReadList
);
assert_eq!(FsAsyncLaneOperation::Exists.priority(), AsyncWorkPriority::NonCriticalReadList);
}
}
@@ -0,0 +1,336 @@
use prometeu_hal::app_mode::AppMode;
use prometeu_hal::cartridge::CartridgeManifest;
use std::fs;
use std::path::{Path, PathBuf};
use std::time::SystemTime;
#[derive(Debug, Clone)]
pub struct GameLibraryEntry {
pub manifest: CartridgeManifest,
pub title: String,
pub app_id: u32,
pub app_version: String,
pub path: PathBuf,
pub discovered_at: SystemTime,
}
impl GameLibraryEntry {
fn new(path: PathBuf, manifest: CartridgeManifest, discovered_at: SystemTime) -> Self {
Self {
title: manifest.title.clone(),
app_id: manifest.app_id,
app_version: manifest.app_version.clone(),
manifest,
path,
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)]
pub struct GameLibraryDiagnostic {
pub path: PathBuf,
pub reason: GameLibraryDiagnosticReason,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum GameLibraryDiagnosticReason {
RootNotDirectory,
CandidateReadFailed,
MissingManifest,
InvalidManifest,
UnsupportedVersion,
MissingProgram,
NonGameAppMode,
}
#[derive(Debug, Clone, Default)]
pub struct GameLibrary {
entries: Vec<GameLibraryEntry>,
diagnostics: Vec<GameLibraryDiagnostic>,
}
impl GameLibrary {
pub fn empty() -> Self {
Self::default()
}
pub fn entries(&self) -> &[GameLibraryEntry] {
&self.entries
}
pub fn diagnostics(&self) -> &[GameLibraryDiagnostic] {
&self.diagnostics
}
pub fn is_empty(&self) -> bool {
self.entries.is_empty()
}
}
pub fn discover_games_root(root: impl AsRef<Path>) -> GameLibrary {
let root = root.as_ref();
let discovered_at = SystemTime::now();
if !root.is_dir() {
return GameLibrary {
entries: Vec::new(),
diagnostics: vec![GameLibraryDiagnostic {
path: root.to_path_buf(),
reason: GameLibraryDiagnosticReason::RootNotDirectory,
}],
};
}
let read_dir = match fs::read_dir(root) {
Ok(read_dir) => read_dir,
Err(_) => {
return GameLibrary {
entries: Vec::new(),
diagnostics: vec![GameLibraryDiagnostic {
path: root.to_path_buf(),
reason: GameLibraryDiagnosticReason::CandidateReadFailed,
}],
};
}
};
let mut entries = Vec::new();
let mut diagnostics = Vec::new();
for item in read_dir {
let Ok(item) = item else {
diagnostics.push(GameLibraryDiagnostic {
path: root.to_path_buf(),
reason: GameLibraryDiagnosticReason::CandidateReadFailed,
});
continue;
};
let path = item.path();
if !path.is_dir() {
continue;
}
match discover_candidate(&path, discovered_at) {
Ok(entry) => entries.push(entry),
Err(reason) => diagnostics.push(GameLibraryDiagnostic { path, reason }),
}
}
entries.sort_by(|left, right| {
left.title
.cmp(&right.title)
.then_with(|| left.app_id.cmp(&right.app_id))
.then_with(|| left.path.cmp(&right.path))
});
GameLibrary { entries, diagnostics }
}
fn discover_candidate(
path: &Path,
discovered_at: SystemTime,
) -> Result<GameLibraryEntry, GameLibraryDiagnosticReason> {
let manifest_path = path.join("manifest.json");
if !manifest_path.exists() {
return Err(GameLibraryDiagnosticReason::MissingManifest);
}
let manifest_content = fs::read_to_string(manifest_path)
.map_err(|_| GameLibraryDiagnosticReason::InvalidManifest)?;
let manifest: CartridgeManifest = serde_json::from_str(&manifest_content)
.map_err(|_| GameLibraryDiagnosticReason::InvalidManifest)?;
if manifest.magic != "PMTU" {
return Err(GameLibraryDiagnosticReason::InvalidManifest);
}
if manifest.cartridge_version != 1 {
return Err(GameLibraryDiagnosticReason::UnsupportedVersion);
}
if manifest.app_mode != AppMode::Game {
return Err(GameLibraryDiagnosticReason::NonGameAppMode);
}
if !path.join("program.pbx").exists() {
return Err(GameLibraryDiagnosticReason::MissingProgram);
}
Ok(GameLibraryEntry::new(path.to_path_buf(), manifest, discovered_at))
}
#[cfg(test)]
mod tests {
use super::*;
use serde_json::json;
use std::sync::atomic::{AtomicU64, Ordering};
use std::time::UNIX_EPOCH;
static TEST_DIR_COUNTER: AtomicU64 = AtomicU64::new(0);
struct TestRoot {
path: PathBuf,
}
impl TestRoot {
fn new() -> Self {
let unique = TEST_DIR_COUNTER.fetch_add(1, Ordering::Relaxed);
let path = std::env::temp_dir().join(format!(
"prometeu-game-library-test-{}-{}",
std::process::id(),
unique
));
fs::create_dir_all(&path).expect("test root should be created");
Self { path }
}
fn add_candidate(&self, name: &str, manifest: serde_json::Value, with_program: bool) {
let candidate = self.path.join(name);
fs::create_dir_all(&candidate).expect("candidate should be created");
fs::write(candidate.join("manifest.json"), manifest.to_string())
.expect("manifest should be written");
if with_program {
fs::write(candidate.join("program.pbx"), [0_u8])
.expect("program should be written");
}
}
}
impl Drop for TestRoot {
fn drop(&mut self) {
let _ = fs::remove_dir_all(&self.path);
}
}
fn manifest(title: &str, app_id: u32, app_mode: &str) -> serde_json::Value {
json!({
"magic": "PMTU",
"cartridge_version": 1,
"app_id": app_id,
"title": title,
"app_version": "1.0.0",
"app_mode": app_mode
})
}
#[test]
fn discovery_returns_only_immediate_valid_game_directories() {
let root = TestRoot::new();
root.add_candidate("zeta", manifest("Zeta", 2, "Game"), true);
root.add_candidate("alpha", manifest("Alpha", 1, "Game"), true);
root.add_candidate("shell", manifest("Shell", 3, "Shell"), true);
root.add_candidate("missing-program", manifest("Missing Program", 4, "Game"), false);
fs::write(root.path.join("loose-file.txt"), "ignored").expect("file should be written");
let nested_parent = root.path.join("nested-parent");
fs::create_dir_all(nested_parent.join("nested-game")).expect("nested dir should exist");
fs::write(
nested_parent.join("nested-game").join("manifest.json"),
manifest("Nested", 5, "Game").to_string(),
)
.expect("nested manifest should be written");
fs::write(nested_parent.join("nested-game").join("program.pbx"), [0_u8])
.expect("nested program should be written");
let library = discover_games_root(&root.path);
assert_eq!(library.entries().len(), 2);
assert_eq!(library.entries()[0].title, "Alpha");
assert_eq!(library.entries()[0].app_id, 1);
assert_eq!(library.entries()[0].app_version, "1.0.0");
assert_eq!(library.entries()[0].manifest.app_mode, AppMode::Game);
assert!(library.entries()[0].path.ends_with("alpha"));
assert!(library.entries()[0].discovered_at >= UNIX_EPOCH);
assert_eq!(library.entries()[1].title, "Zeta");
assert!(library.diagnostics().iter().any(|diagnostic| {
diagnostic.path.ends_with("shell")
&& diagnostic.reason == GameLibraryDiagnosticReason::NonGameAppMode
}));
assert!(library.diagnostics().iter().any(|diagnostic| {
diagnostic.path.ends_with("missing-program")
&& diagnostic.reason == GameLibraryDiagnosticReason::MissingProgram
}));
assert!(library.diagnostics().iter().any(|diagnostic| {
diagnostic.path.ends_with("nested-parent")
&& diagnostic.reason == GameLibraryDiagnosticReason::MissingManifest
}));
}
#[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();
let missing = root.path.join("missing");
let library = discover_games_root(&missing);
assert!(library.is_empty());
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")
}));
}
}
@@ -1,4 +1,5 @@
use crate::fs::{FsError, VirtualFS};
use crate::services::async_work::{AsyncWorkJobKind, AsyncWorkPriority};
use std::collections::HashMap;
pub const MEMCARD_SLOT_COUNT: usize = 32;
@@ -50,6 +51,30 @@ pub struct MemcardWriteResult {
pub bytes_written: u32,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum MemcardAsyncLaneOperation {
SlotWrite,
SlotCommit,
SlotClear,
SlotRead,
SlotStat,
}
impl MemcardAsyncLaneOperation {
pub const fn job_kind(self) -> AsyncWorkJobKind {
AsyncWorkJobKind::Memcard
}
pub const fn priority(self) -> AsyncWorkPriority {
match self {
Self::SlotWrite | Self::SlotCommit | Self::SlotClear => {
AsyncWorkPriority::MemcardCommitWrite
}
Self::SlotRead | Self::SlotStat => AsyncWorkPriority::NonCriticalReadList,
}
}
}
#[derive(Debug, Clone)]
struct SlotImage {
payload: Vec<u8>,
@@ -428,4 +453,29 @@ mod tests {
let stat = mem.slot_stat(&fs, 7, 2);
assert_eq!(stat.state, MemcardSlotState::Corrupt);
}
#[test]
fn memcard_async_lane_operations_classify_priority_without_changing_public_api() {
assert_eq!(MemcardAsyncLaneOperation::SlotWrite.job_kind(), AsyncWorkJobKind::Memcard);
assert_eq!(
MemcardAsyncLaneOperation::SlotWrite.priority(),
AsyncWorkPriority::MemcardCommitWrite
);
assert_eq!(
MemcardAsyncLaneOperation::SlotCommit.priority(),
AsyncWorkPriority::MemcardCommitWrite
);
assert_eq!(
MemcardAsyncLaneOperation::SlotClear.priority(),
AsyncWorkPriority::MemcardCommitWrite
);
assert_eq!(
MemcardAsyncLaneOperation::SlotRead.priority(),
AsyncWorkPriority::NonCriticalReadList
);
assert_eq!(
MemcardAsyncLaneOperation::SlotStat.priority(),
AsyncWorkPriority::NonCriticalReadList
);
}
}
@@ -1,6 +1,10 @@
pub mod async_work;
pub mod foreground;
pub mod fs;
pub mod game_library;
pub mod memcard;
pub mod process;
pub mod task;
pub mod vm_runtime;
pub mod vm_session;
pub mod windows;
@@ -168,13 +168,9 @@ impl NativeInterface for VmRuntimeHost<'_> {
VmFault::Trap(TRAP_INVALID_SYSCALL, format!("Unknown syscall: 0x{:08X}", id))
})?;
match syscall {
Syscall::SystemHasCart => {
ret.push_bool(true);
return Ok(());
}
Syscall::SystemRunCart => return Ok(()),
_ => {}
if syscall == Syscall::SystemHasCart {
ret.push_bool(true);
return Ok(());
}
self.ensure_game_profile_syscall(syscall)?;
@@ -183,7 +179,6 @@ impl NativeInterface for VmRuntimeHost<'_> {
match syscall {
Syscall::SystemHasCart => unreachable!(),
Syscall::SystemRunCart => unreachable!(),
Syscall::GfxClear => {
let color = self.get_color(expect_int(args, 0)?)?;
self.gfx2d_commands.push(Gfx2dCommand::Clear { color });
@@ -757,6 +752,64 @@ impl NativeInterface for VmRuntimeHost<'_> {
ret.push_int(status as i64);
Ok(())
}
Syscall::AssetBacklogInfo => {
let info = platform.assets().backlog_info();
ret.push_int(info.status as i64);
ret.push_int(info.pending_count as i64);
ret.push_int(info.active_handle as i64);
ret.push_int(info.active_asset_id.unwrap_or(0) as i64);
ret.push_int(info.active_bank_type.map(|bank| bank as i64).unwrap_or(0));
ret.push_int(info.active_slot.map(|slot| slot as i64).unwrap_or(0));
ret.push_int(info.active_progress as i64);
Ok(())
}
Syscall::AssetBacklogPosition => {
let position = platform.assets().backlog_position(expect_int(args, 0)? as u32);
ret.push_int(position.status as i64);
ret.push_int(position.state as i64);
ret.push_int(position.position as i64);
ret.push_int(position.progress as i64);
Ok(())
}
Syscall::AssetBacklogMove => {
let new_position = expect_non_negative_usize(args, 1, "new_position")?;
let status =
platform.assets().backlog_move(expect_int(args, 0)? as u32, new_position);
ret.push_int(status as i64);
Ok(())
}
Syscall::AssetBacklogPromote => {
let status = platform.assets().backlog_promote(expect_int(args, 0)? as u32);
ret.push_int(status as i64);
Ok(())
}
Syscall::AssetBacklogDemote => {
let status = platform.assets().backlog_demote(expect_int(args, 0)? as u32);
ret.push_int(status as i64);
Ok(())
}
Syscall::AssetTargetStatus => {
let bank_type = match expect_int(args, 0)? {
0 => BankType::GLYPH,
1 => BankType::SOUNDS,
2 => BankType::SCENE,
other => {
return Err(VmFault::Trap(
TRAP_TYPE,
format!("Invalid asset bank type: {}", other),
));
}
};
let slot = expect_non_negative_usize(args, 1, "slot")?;
let target = platform.assets().target_status(bank_type, slot);
ret.push_int(target.status as i64);
ret.push_int(target.asset_id.unwrap_or(0) as i64);
ret.push_int(target.handle as i64);
ret.push_int(target.state as i64);
ret.push_int(target.position as i64);
ret.push_int(target.progress as i64);
Ok(())
}
Syscall::BankInfo => {
let asset_type = match expect_int(args, 0)? as u32 {
0 => BankType::GLYPH,
@@ -32,6 +32,7 @@ impl VirtualMachineRuntime {
gfx2d_commands: Vec::new(),
gfxui_commands: Vec::new(),
logs_written_this_frame: HashMap::new(),
game_lifecycle_events_delivered: Vec::new(),
atomic_telemetry,
last_crash_report: None,
certifier: Certifier::new(cap_config.unwrap_or_default()),
@@ -135,6 +136,7 @@ impl VirtualMachineRuntime {
self.gfx2d_commands.clear();
self.gfxui_commands.clear();
self.logs_written_this_frame.clear();
self.game_lifecycle_events_delivered.clear();
self.last_crash_report = None;
@@ -191,6 +193,21 @@ impl VirtualMachineRuntime {
}
}
pub fn deliver_game_lifecycle_events<I>(&mut self, events: I)
where
I: IntoIterator<Item = GameLifecycleEvent>,
{
self.game_lifecycle_events_delivered.extend(events);
}
pub fn delivered_game_lifecycle_events(&self) -> &[GameLifecycleEvent] {
&self.game_lifecycle_events_delivered
}
pub fn take_delivered_game_lifecycle_events(&mut self) -> Vec<GameLifecycleEvent> {
std::mem::take(&mut self.game_lifecycle_events_delivered)
}
pub fn initialize_vm(
&mut self,
log_service: &mut LogService,
@@ -224,3 +241,26 @@ impl VirtualMachineRuntime {
}
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::os::{GameLifecycleEvent, GameLifecycleEventKind};
use crate::task::TaskId;
#[test]
fn vm_runtime_records_and_drains_delivered_game_lifecycle_events() {
let mut runtime = VirtualMachineRuntime::new(None);
let pause = GameLifecycleEvent { task_id: TaskId(7), kind: GameLifecycleEventKind::Pause };
let resume = GameLifecycleEvent {
task_id: TaskId(7),
kind: GameLifecycleEventKind::ResumeForeground,
};
runtime.deliver_game_lifecycle_events([pause, resume]);
assert_eq!(runtime.delivered_game_lifecycle_events(), &[pause, resume]);
assert_eq!(runtime.take_delivered_game_lifecycle_events(), vec![pause, resume]);
assert!(runtime.delivered_game_lifecycle_events().is_empty());
}
}
@@ -13,6 +13,7 @@ mod tests;
mod tick;
use crate::CrashReport;
use crate::os::GameLifecycleEvent;
pub use frame_scheduler::FrameScheduler;
use prometeu_bytecode::string_materialization_count;
use prometeu_hal::app_mode::AppMode;
@@ -49,6 +50,7 @@ pub struct VirtualMachineRuntime {
pub gfx2d_commands: Vec<Gfx2dCommand>,
pub gfxui_commands: Vec<GfxUiCommand>,
pub logs_written_this_frame: HashMap<u32, u32>,
pub game_lifecycle_events_delivered: Vec<GameLifecycleEvent>,
pub atomic_telemetry: Arc<AtomicTelemetry>,
pub last_crash_report: Option<CrashReport>,
pub certifier: Certifier,
@@ -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);
@@ -180,6 +180,102 @@ fn tick_asset_status_unknown_handle_returns_status_not_crash() {
assert_eq!(vm.operand_stack_top(1), vec![Value::Int64(LoadStatus::UnknownHandle as i64)]);
}
#[test]
fn tick_asset_target_status_empty_slot_returns_status_first_payload() {
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 mut platform = TestPlatform::new();
let signals = InputSignals::default();
let code = assemble("PUSH_I32 0\nPUSH_I32 0\nHOSTCALL 0\nHALT").expect("assemble");
let program = serialized_single_function_module(
code,
vec![SyscallDecl {
module: "asset".into(),
name: "target_status".into(),
version: 1,
arg_slots: 2,
ret_slots: 6,
}],
);
let cartridge = cartridge_with_program(program, caps::ASSET);
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(), "target_status must not crash for empty slots");
assert!(vm.is_halted());
assert_eq!(
vm.operand_stack_top(6),
vec![
Value::Int64(0),
Value::Int64(0),
Value::Int64(LoadStatus::EMPTY as i64),
Value::Int64(1),
Value::Int64(0),
Value::Int64(AssetOpStatus::Ok as i64),
]
);
}
#[test]
fn tick_asset_backlog_promote_unknown_handle_returns_status_not_crash() {
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 mut platform = TestPlatform::new();
let signals = InputSignals::default();
let code = assemble("PUSH_I32 999\nHOSTCALL 0\nHALT").expect("assemble");
let program = serialized_single_function_module(
code,
vec![SyscallDecl {
module: "asset".into(),
name: "backlog_promote".into(),
version: 1,
arg_slots: 1,
ret_slots: 1,
}],
);
let cartridge = cartridge_with_program(program, caps::ASSET);
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(), "unknown backlog handle must not crash");
assert!(vm.is_halted());
assert_eq!(vm.operand_stack_top(1), vec![Value::Int64(AssetOpStatus::UnknownHandle as i64)]);
}
#[test]
fn tick_bank_info_returns_slot_summary_not_json() {
let mut runtime = VirtualMachineRuntime::new(None);
@@ -391,20 +487,15 @@ fn tick_asset_cancel_invalid_transition_returns_status_not_crash() {
runtime.initialize_vm(&mut log_service, &mut vm, &cartridge).expect("runtime must initialize");
let mut asset_ready = false;
for _ in 0..1_000 {
match platform.local_hardware().assets.status(handle) {
LoadStatus::READY => {
asset_ready = true;
break;
}
LoadStatus::PENDING | LoadStatus::LOADING => {
std::thread::yield_now();
}
other => panic!("unexpected asset status before commit: {:?}", other),
}
let start = Instant::now();
let mut status = platform.local_hardware().assets.status(handle);
while matches!(status, LoadStatus::PENDING | LoadStatus::LOADING)
&& start.elapsed() < std::time::Duration::from_secs(5)
{
std::thread::sleep(std::time::Duration::from_millis(10));
status = platform.local_hardware().assets.status(handle);
}
assert!(asset_ready, "asset did not become ready before commit");
assert_eq!(status, LoadStatus::READY, "asset did not become ready before commit");
assert_eq!(platform.local_hardware().assets.commit(handle), AssetOpStatus::Ok);
platform.local_hardware().assets.apply_commits();
@@ -0,0 +1,310 @@
use crate::VirtualMachineRuntime;
use crate::fs::FsState;
use crate::process::{Process, ProcessId, ProcessKind};
use crate::task::{Task, TaskId, TaskKind};
use prometeu_hal::app_mode::AppMode;
use prometeu_hal::telemetry::CertificationConfig;
use prometeu_vm::VirtualMachine;
use std::collections::HashMap;
use std::sync::Arc;
use std::sync::atomic::AtomicU32;
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct VmSessionId(pub TaskId);
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum VmSessionError {
SessionAlreadyExists(TaskId),
TaskProcessMismatch { task_id: TaskId, task_process: ProcessId, process_id: ProcessId },
TaskKindMismatch { task_id: TaskId, task_kind: TaskKind, process_kind: ProcessKind },
ProcessIsNotVmBacked(ProcessId),
}
pub struct VmSession {
pub id: VmSessionId,
pub task_id: TaskId,
pub process_id: ProcessId,
pub app_id: u32,
pub title: String,
pub app_version: String,
pub app_mode: AppMode,
pub vm: VirtualMachine,
pub runtime: VirtualMachineRuntime,
pub fs_state: FsState,
pub open_files: HashMap<u32, String>,
pub next_handle: u32,
}
impl VmSession {
fn new(
task: &Task,
process: &Process,
app_mode: AppMode,
app_version: impl Into<String>,
cap_config: Option<CertificationConfig>,
logs_count: Arc<AtomicU32>,
) -> Self {
Self {
id: VmSessionId(task.id),
task_id: task.id,
process_id: process.id,
app_id: task.app_id,
title: task.title.clone(),
app_version: app_version.into(),
app_mode,
vm: VirtualMachine::default(),
runtime: VirtualMachineRuntime::new_with_log_counter(cap_config, logs_count),
fs_state: FsState::Unmounted,
open_files: HashMap::new(),
next_handle: 1,
}
}
pub fn clear_cartridge_service_state(&mut self) {
self.open_files.clear();
self.next_handle = 1;
}
}
#[derive(Default)]
pub struct VmSessionRegistry {
sessions: HashMap<VmSessionId, VmSession>,
}
impl VmSessionRegistry {
pub fn new() -> Self {
Self { sessions: HashMap::new() }
}
pub fn create_for_task(
&mut self,
task: &Task,
process: &Process,
app_version: impl Into<String>,
cap_config: Option<CertificationConfig>,
logs_count: Arc<AtomicU32>,
) -> Result<VmSessionId, VmSessionError> {
if task.process_id != process.id {
return Err(VmSessionError::TaskProcessMismatch {
task_id: task.id,
task_process: task.process_id,
process_id: process.id,
});
}
let app_mode = app_mode_for_task_and_process(task, process)?;
let id = VmSessionId(task.id);
if self.sessions.contains_key(&id) {
return Err(VmSessionError::SessionAlreadyExists(task.id));
}
self.sessions.insert(
id,
VmSession::new(task, process, app_mode, app_version, cap_config, logs_count),
);
Ok(id)
}
pub fn get(&self, id: VmSessionId) -> Option<&VmSession> {
self.sessions.get(&id)
}
pub fn get_mut(&mut self, id: VmSessionId) -> Option<&mut VmSession> {
self.sessions.get_mut(&id)
}
pub fn for_task(&self, task_id: TaskId) -> Option<&VmSession> {
self.get(VmSessionId(task_id))
}
pub fn for_task_mut(&mut self, task_id: TaskId) -> Option<&mut VmSession> {
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)
}
pub fn resident_game_for_app(&self, app_id: u32) -> Option<&VmSession> {
self.sessions
.values()
.find(|session| session.app_mode == AppMode::Game && session.app_id == app_id)
}
pub fn len(&self) -> usize {
self.sessions.len()
}
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(
task: &Task,
process: &Process,
) -> Result<AppMode, VmSessionError> {
match (task.kind, process.kind) {
(TaskKind::Game, ProcessKind::VmGame) => Ok(AppMode::Game),
(TaskKind::Shell, ProcessKind::VmShell) => Ok(AppMode::Shell),
(_, ProcessKind::NativeShell) => Err(VmSessionError::ProcessIsNotVmBacked(process.id)),
_ => Err(VmSessionError::TaskKindMismatch {
task_id: task.id,
task_kind: task.kind,
process_kind: process.kind,
}),
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::process::Process;
use crate::task::Task;
#[test]
fn creates_vm_game_session_for_vm_game_task() {
let process = Process::new(ProcessId(1), 42, "Stress", ProcessKind::VmGame);
let task = Task::new(TaskId(7), process.id, 42, "Stress", TaskKind::Game);
let mut registry = VmSessionRegistry::new();
let id = registry
.create_for_task(&task, &process, "", None, Arc::new(AtomicU32::new(0)))
.expect("session should create");
let session = registry.get(id).expect("session should exist");
assert_eq!(session.id, VmSessionId(task.id));
assert_eq!(session.task_id, task.id);
assert_eq!(session.process_id, process.id);
assert_eq!(session.app_id, 42);
assert_eq!(session.title, "Stress");
assert_eq!(session.app_mode, AppMode::Game);
assert_eq!(session.runtime.current_app_id, 0);
assert_eq!(session.fs_state, FsState::Unmounted);
assert_eq!(session.next_handle, 1);
}
#[test]
fn creates_vm_shell_session_for_vm_shell_task() {
let process = Process::new(ProcessId(1), 7, "Shell", ProcessKind::VmShell);
let task = Task::new(TaskId(3), process.id, 7, "Shell", TaskKind::Shell);
let mut registry = VmSessionRegistry::new();
let id = registry
.create_for_task(&task, &process, "1.0", None, Arc::new(AtomicU32::new(0)))
.expect("session should create");
let session = registry.get(id).expect("session should exist");
assert_eq!(session.app_mode, AppMode::Shell);
assert_eq!(session.app_version, "1.0");
}
#[test]
fn rejects_native_shell_process() {
let process = Process::new(ProcessId(1), 7, "Shell", ProcessKind::NativeShell);
let task = Task::new(TaskId(3), process.id, 7, "Shell", TaskKind::Shell);
let mut registry = VmSessionRegistry::new();
assert_eq!(
registry.create_for_task(&task, &process, "", None, Arc::new(AtomicU32::new(0))),
Err(VmSessionError::ProcessIsNotVmBacked(process.id))
);
}
#[test]
fn finds_resident_game_by_app_id() {
let process = Process::new(ProcessId(1), 42, "Stress", ProcessKind::VmGame);
let task = Task::new(TaskId(7), process.id, 42, "Stress", TaskKind::Game);
let mut registry = VmSessionRegistry::new();
registry
.create_for_task(&task, &process, "", None, Arc::new(AtomicU32::new(0)))
.expect("session should create");
assert_eq!(
registry.resident_game_for_app(42).map(|session| session.task_id),
Some(task.id)
);
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);
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");
registry
.for_task_mut(game_task.id)
.expect("game session should exist")
.runtime
.tick_index = 11;
registry
.for_task_mut(shell_task.id)
.expect("shell session should exist")
.runtime
.tick_index = 3;
registry
.for_task_mut(game_task.id)
.expect("game session should exist")
.open_files
.insert(1, "/game.save".to_string());
assert_eq!(
registry.for_task(game_task.id).map(|session| session.runtime.tick_index),
Some(11)
);
assert_eq!(
registry.for_task(shell_task.id).map(|session| session.runtime.tick_index),
Some(3)
);
assert!(
registry
.for_task(shell_task.id)
.expect("shell session should exist")
.open_files
.is_empty()
);
}
}
@@ -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();
@@ -43,9 +43,27 @@ impl FbViewport {
pub struct HostInputHandler {
pub signals: InputSignals,
system_controls: HostSystemControls,
display_size: (usize, usize),
}
#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
pub struct HostSystemControls {
home_requested: bool,
}
impl HostSystemControls {
pub fn request_home(&mut self) {
self.home_requested = true;
}
pub fn take_home_requested(&mut self) -> bool {
let requested = self.home_requested;
self.home_requested = false;
requested
}
}
impl Default for HostInputHandler {
fn default() -> Self {
Self::new((480, 270))
@@ -54,35 +72,51 @@ impl Default for HostInputHandler {
impl HostInputHandler {
pub fn new(display_size: (usize, usize)) -> Self {
Self { signals: InputSignals::default(), display_size }
Self {
signals: InputSignals::default(),
system_controls: HostSystemControls::default(),
display_size,
}
}
pub fn take_home_requested(&mut self) -> bool {
self.system_controls.take_home_requested()
}
pub fn clear_guest_signals(&mut self) {
self.signals = InputSignals::default();
}
pub fn handle_key_code(&mut self, code: KeyCode, state: ElementState) {
let is_down = state == ElementState::Pressed;
match code {
KeyCode::Escape | KeyCode::Home if is_down => self.system_controls.request_home(),
KeyCode::ArrowUp => self.signals.up_signal = is_down,
KeyCode::ArrowDown => self.signals.down_signal = is_down,
KeyCode::ArrowLeft => self.signals.left_signal = is_down,
KeyCode::ArrowRight => self.signals.right_signal = is_down,
KeyCode::KeyA => self.signals.a_signal = is_down,
KeyCode::KeyD => self.signals.b_signal = is_down,
KeyCode::KeyW => self.signals.x_signal = is_down,
KeyCode::KeyS => self.signals.y_signal = is_down,
KeyCode::KeyQ => self.signals.l_signal = is_down,
KeyCode::KeyE => self.signals.r_signal = is_down,
KeyCode::KeyZ => self.signals.start_signal = is_down,
KeyCode::ShiftLeft | KeyCode::ShiftRight => self.signals.select_signal = is_down,
_ => {}
}
}
pub fn handle_event(&mut self, event: &WindowEvent, window: &Window) {
match event {
WindowEvent::KeyboardInput { event, .. } => {
if let PhysicalKey::Code(code) = event.physical_key {
let is_down = event.state == ElementState::Pressed;
match code {
KeyCode::ArrowUp => self.signals.up_signal = is_down,
KeyCode::ArrowDown => self.signals.down_signal = is_down,
KeyCode::ArrowLeft => self.signals.left_signal = is_down,
KeyCode::ArrowRight => self.signals.right_signal = is_down,
KeyCode::KeyA => self.signals.a_signal = is_down,
KeyCode::KeyD => self.signals.b_signal = is_down,
KeyCode::KeyW => self.signals.x_signal = is_down,
KeyCode::KeyS => self.signals.y_signal = is_down,
KeyCode::KeyQ => self.signals.l_signal = is_down,
KeyCode::KeyE => self.signals.r_signal = is_down,
KeyCode::KeyZ => self.signals.start_signal = is_down,
KeyCode::ShiftLeft | KeyCode::ShiftRight => {
self.signals.select_signal = is_down
}
_ => {}
}
self.handle_key_code(code, event.state);
}
}
@@ -134,3 +168,81 @@ impl HostInputHandler {
}
}
}
#[cfg(test)]
mod tests {
use super::*;
fn assert_no_pad_signal(signals: InputSignals) {
assert!(!signals.up_signal);
assert!(!signals.down_signal);
assert!(!signals.left_signal);
assert!(!signals.right_signal);
assert!(!signals.a_signal);
assert!(!signals.b_signal);
assert!(!signals.x_signal);
assert!(!signals.y_signal);
assert!(!signals.l_signal);
assert!(!signals.r_signal);
assert!(!signals.start_signal);
assert!(!signals.select_signal);
assert!(!signals.f_signal);
}
#[test]
fn escape_requests_home_without_mutating_guest_pad() {
let mut input = HostInputHandler::default();
input.handle_key_code(KeyCode::Escape, ElementState::Pressed);
assert!(input.take_home_requested());
assert!(!input.take_home_requested());
assert_no_pad_signal(input.signals);
}
#[test]
fn physical_home_requests_home_without_mutating_guest_pad() {
let mut input = HostInputHandler::default();
input.handle_key_code(KeyCode::Home, ElementState::Pressed);
assert!(input.take_home_requested());
assert_no_pad_signal(input.signals);
}
#[test]
fn home_release_does_not_emit_a_new_home_request() {
let mut input = HostInputHandler::default();
input.handle_key_code(KeyCode::Home, ElementState::Released);
assert!(!input.take_home_requested());
assert_no_pad_signal(input.signals);
}
#[test]
fn existing_keyboard_pad_mapping_is_preserved() {
let mut input = HostInputHandler::default();
input.handle_key_code(KeyCode::KeyZ, ElementState::Pressed);
input.handle_key_code(KeyCode::ShiftLeft, ElementState::Pressed);
input.handle_key_code(KeyCode::ArrowUp, ElementState::Pressed);
assert!(input.signals.start_signal);
assert!(input.signals.select_signal);
assert!(input.signals.up_signal);
assert!(!input.take_home_requested());
}
#[test]
fn clearing_guest_signals_preserves_system_home_control() {
let mut input = HostInputHandler::default();
input.handle_key_code(KeyCode::ArrowUp, ElementState::Pressed);
input.handle_key_code(KeyCode::Escape, ElementState::Pressed);
input.clear_guest_signals();
assert_no_pad_signal(input.signals);
assert!(input.take_home_requested());
}
}
@@ -33,6 +33,10 @@ struct Cli {
#[arg(long, value_name = "PATH")]
fs_root: Option<String>,
/// Root directory for local game cartridge discovery
#[arg(long, value_name = "PATH")]
games_root: Option<String>,
/// Path to the capability configuration file
#[arg(long, value_name = "PATH")]
cap: Option<String>,
@@ -55,6 +59,9 @@ pub fn run() -> Result<(), Box<dyn std::error::Error>> {
let event_loop = EventLoop::new()?;
let mut runner = HostRunner::new(fs_root, cap_config);
if let Some(games_root) = cli.games_root {
runner.set_games_root(games_root);
}
runner.set_boot_target(boot_target);
event_loop.run_app(&mut runner)?;
@@ -10,9 +10,9 @@ use pixels::{Pixels, PixelsBuilder, SurfaceTexture};
use prometeu_drivers::hardware::Hardware;
use prometeu_drivers::{AudioCommand, LocalFramebufferRenderBackend, MemoryBanks};
use prometeu_firmware::{BootTarget, Firmware, FirmwareState};
use prometeu_hal::RuntimePlatform;
use prometeu_hal::telemetry::CertificationConfig;
use prometeu_system::{LatestRenderFrameStore, RenderWorkerConfig};
use prometeu_hal::{OwnedRgba8888Frame, RenderOwnership, RuntimePlatform};
use prometeu_system::{LatestRenderFrameStore, RenderWorkerConfig, discover_games_root};
use std::sync::Arc;
use std::time::{Duration, Instant};
use winit::application::ApplicationHandler;
@@ -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;
}
}
@@ -88,8 +95,12 @@ fn desired_control_flow(
}
}
fn should_present_worker_frame(state: &FirmwareState) -> bool {
matches!(state, FirmwareState::GameRunning(_))
fn should_present_worker_frame(
state: &FirmwareState,
frame: &OwnedRgba8888Frame,
active_ownership: RenderOwnership,
) -> bool {
matches!(state, FirmwareState::GameRunning(_)) && frame.ownership == active_ownership
}
/// The Desktop implementation of the PROMETEU Runtime.
@@ -151,6 +162,18 @@ impl HostRunner {
self.debugger.setup_boot_target(&boot_target, &mut self.firmware);
}
pub(crate) fn set_games_root(&mut self, games_root: String) {
let library = discover_games_root(&games_root);
for diagnostic in library.diagnostics() {
eprintln!(
"games-root: omitted candidate {}: {:?}",
diagnostic.path.display(),
diagnostic.reason
);
}
self.firmware.hub.set_game_library(library);
}
/// Creates a new desktop runner instance.
pub(crate) fn new(fs_root: Option<String>, cap_config: Option<CertificationConfig>) -> Self {
let target_fps = 60;
@@ -300,8 +323,13 @@ impl ApplicationHandler for HostRunner {
{
let frame = pixels.frame_mut();
if should_present_worker_frame(&self.firmware.state)
&& let Some(worker_frame) = self.render_frame_store.latest_frame()
let active_ownership = self.firmware.os.vm().active_render_ownership();
if let Some(worker_frame) = self.render_frame_store.latest_frame()
&& should_present_worker_frame(
&self.firmware.state,
&worker_frame,
active_ownership,
)
{
self.firmware
.os
@@ -360,6 +388,13 @@ impl ApplicationHandler for HostRunner {
self.firmware.os.fs().mount(Box::new(backend));
}
if self.input.take_home_requested() {
self.input.clear_guest_signals();
self.firmware.request_home_from_host();
self.invalidate_host_surface();
self.request_redraw_if_needed();
}
// 3. Timing Management (The heart of determinism).
// We measure the elapsed time since the last iteration and add it to an
// accumulator. We then execute exactly as many 60Hz slices as the
@@ -387,7 +422,10 @@ impl ApplicationHandler for HostRunner {
// Sync pause state with audio.
// We do this AFTER firmware.tick to avoid MasterPause/Resume commands
// being cleared by the OS if a new logical frame starts in this tick.
let is_paused = self.firmware.os.vm().paused() || self.debugger.waiting_for_start;
let lifecycle_audio_paused = self.firmware.game_lifecycle_audio_paused();
let is_paused = lifecycle_audio_paused
|| self.firmware.os.vm().paused()
|| self.debugger.waiting_for_start;
if is_paused != self.last_paused_state {
self.last_paused_state = is_paused;
let cmd =
@@ -402,12 +440,15 @@ impl ApplicationHandler for HostRunner {
self.stats.record_frame();
}
if should_present_worker_frame(&self.firmware.state)
&& let Some(worker_frame) = self.render_frame_store.latest_frame()
let active_ownership = self.firmware.os.vm().active_render_ownership();
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()
@@ -473,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]
@@ -524,14 +588,39 @@ mod tests {
}
#[test]
fn worker_frame_presentation_is_game_only() {
assert!(should_present_worker_frame(&FirmwareState::GameRunning(GameRunningStep::new(
TaskId(1),
))));
assert!(!should_present_worker_frame(&FirmwareState::ShellRunning(ShellRunningStep::new(
TaskId(2)
),)));
assert!(!should_present_worker_frame(&FirmwareState::HubHome(HubHomeStep)));
fn worker_frame_presentation_requires_game_state_and_current_ownership() {
let active = RenderOwnership::new(3, AppMode::Game, 1);
let current = OwnedRgba8888Frame::packed(FrameId::new(9), active, 1, 1, vec![0xFF00FFFF])
.expect("test frame");
let stale = OwnedRgba8888Frame::packed(
FrameId::new(8),
RenderOwnership::new(2, AppMode::Game, 1),
1,
1,
vec![0xFF00FFFF],
)
.expect("test frame");
assert!(should_present_worker_frame(
&FirmwareState::GameRunning(GameRunningStep::new(TaskId(1))),
&current,
active,
));
assert!(!should_present_worker_frame(
&FirmwareState::GameRunning(GameRunningStep::new(TaskId(1),)),
&stale,
active,
));
assert!(!should_present_worker_frame(
&FirmwareState::ShellRunning(ShellRunningStep::new(TaskId(2))),
&current,
active,
));
assert!(!should_present_worker_frame(
&FirmwareState::HubHome(HubHomeStep),
&current,
active,
));
}
#[test]
@@ -551,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
+10 -4
View File
@@ -1,7 +1,9 @@
{"type":"meta","next_id":{"DSC":43,"AGD":44,"DEC":35,"PLN":129,"LSN":50,"CLSN":1}}
{"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":"open","ticket":"foreground-stack-game-pause-shell-vm-backed","title":"Foreground Stack, Game Pause, and VM-Backed Shell Coexistence","created_at":"2026-06-05","updated_at":"2026-06-05","tags":["runtime","os","lifecycle","shell","game","vm","foreground","architecture"],"agendas":[{"id":"AGD-0041","file":"AGD-0041-foreground-stack-game-pause-shell-vm-backed.md","status":"open","created_at":"2026-06-05","updated_at":"2026-06-05"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-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"}]}
@@ -13,12 +15,13 @@
{"type":"discussion","id":"DSC-0001","status":"done","ticket":"legacy-runtime-learn-import","title":"Import legacy runtime learn into discussion lessons","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["migration","tech-debt"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0001","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0001-prometeu-learn-index.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0002","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0002-historical-asset-status-first-fault-and-return-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0003","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0003-historical-audio-status-first-fault-and-return-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0004","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0004-historical-cartridge-boot-protocol-and-manifest-authority.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0005","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0005-historical-game-memcard-slots-surface-and-semantics.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0006","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0006-historical-gfx-status-first-fault-and-return-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0007","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0007-historical-retired-fault-and-input-decisions.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0008","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0008-historical-vm-core-and-assets.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0009","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0009-mental-model-asset-management.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0010","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0010-mental-model-audio.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0011","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0011-mental-model-gfx.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0012","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0012-mental-model-input.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0013","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0013-mental-model-observability-and-debugging.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0014","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0014-mental-model-portability-and-cross-platform.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0015","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0015-mental-model-save-memory-and-memcard.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0016","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0016-mental-model-status-first-and-fault-thinking.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0017","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0017-mental-model-time-and-cycles.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0018","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0018-mental-model-touch.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
{"type":"discussion","id":"DSC-0002","status":"done","ticket":"runtime-edge-test-plan","title":"Agenda - Runtime Edge Test Plan","created_at":"2026-03-27","updated_at":"2026-04-21","tags":[],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0037","file":"discussion/lessons/DSC-0002-runtime-edge-test-plan/LSN-0037-domain-gates-must-be-owned-by-the-repository.md","status":"done","created_at":"2026-04-21","updated_at":"2026-04-21"}]}
{"type":"discussion","id":"DSC-0003","status":"open","ticket":"packed-cartridge-loader-pmc","title":"Agenda - Packed Cartridge Loader PMC","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0002","file":"AGD-0002-packed-cartridge-loader-pmc.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0004","status":"open","ticket":"system-run-cart","title":"Agenda - System Run Cart","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0003","file":"AGD-0003-system-run-cart.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0004","status":"done","ticket":"system-run-cart","title":"Agenda - System Run Cart","created_at":"2026-03-27","updated_at":"2026-07-03","tags":[],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0051","file":"discussion/lessons/DSC-0004-system-run-cart/LSN-0051-launch-authority-belongs-to-systemos.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03"}]}
{"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":"in_progress","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-06-28","tags":["perf","asset","fs","async","scheduler","runtime"],"agendas":[{"id":"AGD-0008","file":"AGD-0008-perf-async-background-work-lanes-for-assets-and-fs.md","status":"accepted","created_at":"2026-03-27","updated_at":"2026-06-28"}],"decisions":[{"id":"DEC-0034","file":"DEC-0034-async-work-lane-and-asset-backlog-contract.md","status":"accepted","created_at":"2026-06-28","updated_at":"2026-06-28","ref_agenda":"AGD-0008"}],"plans":[{"id":"PLN-0123","file":"PLN-0123-async-work-lane-specification-propagation.md","status":"open","created_at":"2026-06-28","updated_at":"2026-06-28","ref_decisions":["DEC-0034"]},{"id":"PLN-0124","file":"PLN-0124-async-work-lane-runtime-infrastructure.md","status":"open","created_at":"2026-06-28","updated_at":"2026-06-28","ref_decisions":["DEC-0034"]},{"id":"PLN-0125","file":"PLN-0125-asset-backlog-and-stable-slot-handles.md","status":"open","created_at":"2026-06-28","updated_at":"2026-06-28","ref_decisions":["DEC-0034"]},{"id":"PLN-0126","file":"PLN-0126-asset-backlog-public-api-and-status-surface.md","status":"open","created_at":"2026-06-28","updated_at":"2026-06-28","ref_decisions":["DEC-0034"]},{"id":"PLN-0127","file":"PLN-0127-async-lane-memcard-and-fs-integration-boundaries.md","status":"open","created_at":"2026-06-28","updated_at":"2026-06-28","ref_decisions":["DEC-0034"]},{"id":"PLN-0128","file":"PLN-0128-async-asset-pipeline-contract-tests-and-telemetry.md","status":"open","created_at":"2026-06-28","updated_at":"2026-06-28","ref_decisions":["DEC-0034"]}],"lessons":[]}
{"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"}]}
{"type":"discussion","id":"DSC-0011","status":"abandoned","ticket":"perf-gfx-render-pipeline-and-dirty-regions","title":"Agenda - [PERF] GFX Render Pipeline and Dirty Regions","created_at":"2026-03-27","updated_at":"2026-06-28","tags":[],"agendas":[{"id":"AGD-0010","file":"AGD-0010-perf-gfx-render-pipeline-and-dirty-regions.md","status":"abandoned","created_at":"2026-03-27","updated_at":"2026-06-28","_override_reason":"User explicitly chose to remove this agenda because it no longer applies to the current render scenario; future optimizations can be discussed when needed."}],"decisions":[],"plans":[],"lessons":[],"_override_reason":"User explicitly chose to abandon this discussion because it no longer applies to the current render scenario; future optimizations can be discussed when needed."}
{"type":"discussion","id":"DSC-0012","status":"done","ticket":"perf-runtime-introspection-syscalls","title":"Agenda - [PERF] Runtime Introspection Syscalls","created_at":"2026-03-27","updated_at":"2026-04-19","tags":["perf","runtime","syscall","telemetry","debug","asset"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0034","file":"discussion/lessons/DSC-0012-perf-runtime-introspection-syscalls/LSN-0034-host-owned-debug-boundaries.md","status":"done","created_at":"2026-04-19","updated_at":"2026-04-19"}]}
@@ -41,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,118 @@
---
id: LSN-0051
ticket: system-run-cart
title: Launch Authority Belongs to SystemOS
created: 2026-07-03
tags: [runtime, systemos, cartridge, launch, abi, home]
---
## Context
The `system.run_cart` workflow resolved two related questions: whether a guest
should have an app-callable cartridge launch syscall, and how Home should start
games from a local library.
The final model removes `system.run_cart` from the userland ABI while preserving
direct host-controlled cartridge boot. Home launch is restored as a
system-owned path: the host may provide `--games-root <dir>`, SystemOS/Home
discovers valid Game directory cartridges, and selecting an entry routes through
firmware into `LoadCartridge`.
The important distinction is authority. A launch can be a valid product action
without being a guest capability.
## Key Decisions
### Remove Guest Cartridge Launch
**What:** Prometeu removed `system.run_cart` from the public userland syscall
surface, generated guest metadata, and runtime dispatch.
**Why:** A guest syscall made cartridge launch look like app-owned navigation.
That gave userland implied authority over target resolution, lifecycle cleanup,
failure policy, and system navigation.
**Trade-offs:** Obsolete guest code cannot keep a compatibility stub. The
runtime instead keeps direct boot as a host/system entrypoint and lets stale
guest attempts fail through the invalid syscall path.
### Preserve Direct Boot Outside The Guest ABI
**What:** Host, CLI, debugger, tests, and single-game flows continue to boot a
selected cartridge directly.
**Why:** Direct boot is still essential for development, automation, and future
single-game distribution. Those flows start with a host-selected target before
VM execution, so they do not need a guest syscall.
**Trade-offs:** The loader remains reusable, but it is not lifecycle
orchestration authority. Higher-level transitions must be owned by firmware or
SystemOS.
### Model Home Launch As A System Action
**What:** `--games-root <dir>` configures a local games library for Home. V1
discovery scans immediate child directories, keeps only valid Game cartridges,
and exposes enough internal metadata to launch a selected entry.
**Why:** Home needs a product path for "choose a game and start it", but that
action belongs to the system profile. SystemOS can present the library and ask
firmware to enter `LoadCartridge` without reintroducing guest-controlled launch.
**Trade-offs:** V1 intentionally excludes recursive discovery, `.pmc`, non-game
apps, rich catalog metadata, return-to-Home, and game-to-game switching. Those
need separate lifecycle and orchestration decisions.
## Patterns and Algorithms
### Authority-Based API Classification
Before exposing an operation to guest/userland code, classify what authority it
implies. If the operation selects another executable target, changes process
lifecycle, or controls navigation between system-owned modes, it is probably a
SystemOS or firmware action rather than an app syscall.
### Separate Selection From Loading
Home owns user selection and presentation. SystemOS owns the launch request.
Firmware owns the transition into `LoadCartridge`. The cartridge loader remains
the mechanism that validates and materializes a cartridge, not the authority
that decides when navigation is allowed.
### Expandable Internal Catalog Records
Home can render a small v1 list while the internal entry retains manifest data,
title, app id, app version, cartridge path, and discovery metadata. This keeps
the UI simple without reducing the model to a display-only DTO.
## Pitfalls
### Compatibility Stubs Preserve False Contracts
A syscall that returns success without doing real lifecycle work is worse than
an absent syscall. It teaches callers that the platform supports app-driven
launch while hiding that no complete transition happened.
### A Product Flow Is Not Automatically A Guest API
"Home can launch a game" and "a guest can launch a cartridge" are different
claims. Product behavior should be mapped to the component with the correct
authority instead of mirrored into the nearest callable ABI.
### Generic Library Roots Prematurely Expand Scope
The first launcher path is a games library, not a marketplace or full app
catalog. Shell apps, System apps, packages, icons, search, and recursive layouts
carry separate contracts and should not be smuggled into the v1 games-root path.
## Takeaways
- Cartridge launch is system navigation, not a userland syscall.
- Direct boot can remain host-controlled without appearing in guest metadata.
- Home launch should emit a system action and let firmware enter
`LoadCartridge`.
- Loader reuse does not imply loader ownership of lifecycle policy.
- Keep v1 discovery narrow: immediate child directory cartridges with
`app_mode: Game`.
- Preserve internal catalog metadata even when the Home UI renders only a small
subset.
@@ -0,0 +1,100 @@
---
id: LSN-0050
ticket: perf-async-background-work-lanes-for-assets-and-fs
title: Serial Async Lanes Bound Backlog Complexity
created: 2026-07-01
tags: [runtime, asset, async, scheduler, telemetry]
---
## Context
The async asset work moved from request-owned worker creation toward a
runtime-owned serial lane. The important shift is not just "use a worker
thread"; it is the introduction of a third logical execution lane with explicit
ownership, priority, cancellation, progress, and telemetry.
This work followed `DEC-0034` and plans `PLN-0123` through `PLN-0128`. The
published model separates:
- main runtime execution, where guest-visible state is committed;
- render worker execution, where closed render packets are consumed;
- async IO/decode/persistence work, where one background job is active at a
time.
## Key Decisions
### Async Work Lane and Asset Backlog Contract
**What:** Asset IO/decode and compatible persistence work use a runtime-owned
serial async lane. Asset requests are queued by target bank slot, not by
unbounded transient request identity.
**Why:** A serial lane keeps the runtime observable and portable. It preserves
the intended hardware mental model while avoiding a desktop-biased thread pool
or one OS thread per asset request.
**Trade-offs:** The lane intentionally sacrifices parallel decode throughput in
exchange for bounded state, deterministic ownership, simpler telemetry, and
clear priority rules. If future implementations add more physical parallelism,
they still need to preserve the logical serial contract where the spec requires
it.
## Patterns and Algorithms
The asset backlog is bounded by target identity. A request targets a concrete
bank type and slot. A newer request for the same target supersedes the older
pending request, and an older active result is discarded when its generation is
no longer current.
Stable handles observe slots. A handle should not be treated as a worker job or
thread token. The durable identity is the bank slot plus request generation:
slot state says what is resident; request state says what is queued, active,
ready, canceled, superseded, or failed.
Commit remains a main-lane operation. The background lane may read and decode,
but publication into resident runtime state happens at predictable ownership
points. This keeps VM execution, render handoff, and frame observation from
racing with background mutation.
Progress and telemetry are closure-oriented. Use integer progress and update
expensive aggregate telemetry when jobs close, not inside decode loops. Tests
should synchronize on explicit state transitions rather than sleeps.
Priority is part of the lane contract. Memcard commit/write work can outrank
ordinary asset loads, FS write/config work can be represented internally, and
non-critical read/list work belongs below asset loads. Public FS semantics
remain owned by the filesystem discussion; sharing the lane is not permission
to decide the FS API here.
## Pitfalls
Do not hide concurrency behind per-request `thread::spawn`. That appears simple
locally but loses boundedness, priority, cancellation, and telemetry.
Do not let a handle mean "the current background job." Handles must survive
empty slots, completed work, cancellation, superseding, errors, and already
resident fast paths.
Do not install background results directly from the worker. Decode completion is
not the same as publication. Use request generation checks before committing a
result.
Do not turn operational states into traps. Queued, active, canceled,
superseded, error, and backend-unavailable outcomes belong in status-first
surfaces unless the caller violated the structural ABI.
Do not reopen FS public API scope while wiring internal async-lane consumers.
The lane can support FS-style work without deciding request/poll semantics.
## Takeaways
- A runtime async lane is an ownership boundary, not just an implementation
thread.
- Backlog keying by target slot bounds complexity better than queue length
limits exposed to the guest.
- Stable slot handles plus request generations prevent stale async results from
mutating newer state.
- Main-lane commit keeps background IO/decode compatible with deterministic
runtime publication.
- Telemetry belongs at state transitions and job closure, not inside hot decode
loops.
@@ -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,94 +0,0 @@
---
id: AGD-0003
ticket: system-run-cart
title: Agenda - System Run Cart
status: open
created: 2026-03-27
resolved:
decision:
tags: []
---
# Agenda - System Run Cart
## Problema
A syscall `system.run_cart` existe na ABI pública, mas hoje não produz efeito real no runtime.
Isso cria uma falsa promessa de plataforma:
- o programa consegue declarar e chamar a syscall;
- o loader aceita sua existência;
- o runtime retorna sucesso vazio;
- nenhuma troca de cartucho, transição de firmware, validação de alvo ou política de segurança ocorre.
## Dor
- A ABI expõe uma capability de sistema que, na prática, nao existe.
- O guest pode acreditar que solicitou uma troca de app quando nada aconteceu.
- Isso corrói a confiabilidade da plataforma: a interface pública deixa de ser contrato e vira placebo.
- Qualquer ferramenta, SDK ou documentação construída sobre essa syscall passa a modelar um comportamento inexistente.
## Alvo da Discussao
Definir o contrato real de `system.run_cart` do ponto de vista:
- do guest;
- do runtime;
- do firmware;
- do host/cartridge loader.
Ao final da discussão, deve ficar claro se a syscall:
- permanece na ABI e ganha implementação completa; ou
- sai temporariamente da ABI até existir fluxo fechado.
## O Que Precisa Ser Definido
1. Semântica da operação.
O que significa "run cart": trocar imediatamente, agendar para o próximo frame, retornar ao firmware, reiniciar VM atual, ou apenas emitir uma intenção?
2. Origem do alvo.
Como o guest identifica o cartucho alvo: id numérico, nome canônico, path virtual, handle, manifesto, ou nenhum argumento nesta primeira versão?
3. Modelo de segurança.
Quem pode chamar isso, sob qual capability, e com quais restrições para evitar que um app force navegação arbitrária do sistema?
4. Ponto de integração.
Onde a transição vive: `VirtualMachineRuntime`, firmware, host, ou combinação dos três?
5. Efeitos observáveis.
O que acontece com:
- estado do app atual;
- FS aberto;
- assets carregados;
- telemetria;
- crash reports;
- logs.
6. Contrato de erro.
Quais falhas retornam trap ao guest e quais viram evento de sistema.
## O Que Necessita Para Resolver
- fluxo fechado entre syscall -> runtime -> firmware -> loader -> novo app;
- modelo explícito para seleção do alvo;
- definição de lifecycle da troca de cartucho;
- testes de integração cobrindo transição bem-sucedida, alvo inválido, capability insuficiente e cleanup de estado.
## Fora de Escopo
- catálogo completo de apps instalados;
- UX final do launcher/hub;
- resolução remota ou download de cartuchos;
- política de marketplace/distribuição.
## Critério de Saida Desta Agenda
Esta agenda só pode virar PR de implementação quando existir decisão escrita para:
- assinatura final da syscall;
- local canônico da troca de estado;
- política de erro;
- limpeza de recursos;
- cobertura mínima de testes de integração.
@@ -22,6 +22,19 @@ Sem um contrato claro de `home` por app, a API tende a crescer com semantica inc
1. Todo `app` acessa somente sua `home` logica.
2. Nunca ha acesso direto ao filesystem global do host pela userland.
3. O runtime `fs` interno continua cobrindo tanto `game` quanto `app`.
4. Existe uma async IO lane compartilhavel por assets, memcard e FS. Esta
agenda deve decidir a API publica de FS considerando essa lane, mas a
existencia da lane ja esta fechada por `DEC-0034`.
## Fronteira com a Async IO Lane
`DEC-0034` fecha a existencia de uma lane serial para trabalho async de IO. FS
pode consumir essa lane internamente para escrita, configuracao, leitura ou
listagem, conforme prioridade operacional definida pelo runtime.
Esta agenda continua dona da decisao sobre API publica de FS para `app home`.
Portanto, a existencia da lane nao implica criar agora request handles, polling
publico ou novas syscalls de FS. Esses shapes permanecem em aberto aqui.
## Alvo da Discussao
@@ -116,6 +129,8 @@ No perfil `app` (`home` sandbox), esta agenda passa a ser a fonte normativa para
2. `rename` entra no MVP ou pode ficar para fase seguinte?
3. Qual conjunto minimo de metadados garante portabilidade real entre hosts?
4. Qual grau de atomicidade e obrigatorio para escrita de arquivo no v1?
5. Quais operacoes de FS devem consumir a async IO lane e quais permanecem
sincrono-aparentes para a userland?
## Dependencias
@@ -1,557 +0,0 @@
---
id: AGD-0008
ticket: perf-async-background-work-lanes-for-assets-and-fs
title: Agenda - [PERF] Async Background Work Lanes for Assets and FS
status: accepted
created: 2026-03-27
resolved: 2026-06-28
decision: DEC-0034
tags: [perf, asset, fs, async, scheduler, runtime]
---
# Agenda - [PERF] Async Background Work Lanes for Assets and FS
## Contexto
Depois das decisoes de render worker, a concorrencia de render saiu do escopo
desta agenda. O problema restante e a lane de trabalho assincrono para IO,
decode e persistencia.
O modelo de execucao que queremos discutir agora assume uma terceira core/lane
dedicada a trabalhos assincronos de runtime:
```text
Core/lane 1: VM, firmware, SystemOS e frame logico
Core/lane 2: render worker / rasterizacao assincrona
Core/lane 3: async work lane para asset IO/decode e possivelmente FS
```
Essa terceira lane nao deve virar um pool grande e solto. A intencao e ter uma
fila previsivel, com capacidade limitada, telemetria e regras de saturacao.
Para assets, a necessidade e concreta: `asset.load()` ainda cria uma thread do
SO por requisicao. Para FS, a motivacao provavel era evitar que operacoes de
leitura/escrita/listagem/delete, hoje chamadas de forma sincrona pelo dispatch,
roubem tempo do frame quando o backend real envolver IO. Precisamos verificar
se FS deve usar a mesma lane agora ou apenas reservar compatibilidade.
## Problema
`asset.load()` hoje dispara `thread::spawn` por requisicao de asset nao
residente. Isso escala mal, cria jitter e deixa o runtime sem uma politica
unica de backpressure.
O dominio `fs` tambem tem operacoes potencialmente bloqueantes (`read`,
`write`, `list_dir`, `delete`, memcard commit/read/write) e a tabela de
syscalls ja as marca como nao deterministicas/custosas. Ainda assim, a
implementacao atual executa essas chamadas diretamente no caminho de dispatch.
Sem um contrato explicito, cada dominio pode inventar sua propria concorrencia:
asset criando threads, FS bloqueando o frame, e memcard herdando comportamento
acidental do backend.
## Pontos Criticos
- `thread::spawn` por request escala mal e cria jitter.
- A terceira core/lane deve ser um recurso de plataforma controlado, nao uma
permissao geral para criar threads.
- Asset loading precisa de um pool/fila limitada para multiplos loads
pendentes.
- FS pode justificar a mesma lane quando envolver IO real, mas nao devemos
assinar uma API assincrona ampla sem entender a semantica de retorno.
- Commit/install em bancos residentes pode ter restricoes de determinismo e
ownership; decode pode ser assincrono, mas publicacao/instalacao talvez tenha
que cruzar de volta para a lane principal.
- A estrategia precisa funcionar em hardware alvo com poucos cores e tambem no
host desktop sem transformar desktop em referencia de custo errada.
- Render worker ja tem seu proprio contrato e nao deve compartilhar essa lane.
## Hotspots Atuais
- [asset.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/asset.rs#L438) - `AssetManager::load`.
- [asset.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/asset.rs#L507) - `thread::spawn` por load.
- [fs.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-hal/src/syscalls/domains/fs.rs#L4) - `fs` e `mem` marcados como superficies custosas/nao deterministicas.
- [dispatch.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-system/src/services/vm_runtime/dispatch.rs#L549) - chamadas `fs.*` executam no dispatch.
- [virtual_fs.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-system/src/services/fs/virtual_fs.rs#L69) - VFS normaliza path e chama backend diretamente.
## Alvo da Discussao
Fechar um modelo de terceira core/lane para trabalho assincrono de runtime,
comecando por asset loading e avaliando se FS deve entrar na mesma lane no v1.
O alvo nao e criar multitarefa geral, callbacks para guest, ou um scheduler
paralelo da VM. A lane deve executar trabalho de IO/decode/sync e publicar
resultados observaveis por status/polling em pontos previsiveis.
## O Que Precisa Ser Definido
1. Topologia da terceira lane.
Definir:
- uma async work lane dedicada, separada da VM e do render worker;
- se a lane e uma thread fixa no host e uma core dedicada no hardware alvo;
- fallback quando nao houver core fisico dedicado;
- proibicao explicita de `thread::spawn` por request no caminho normal.
2. Pool/fila de asset loading.
Definir:
- backlog de pedidos sem limite operacional fixo;
- exatamente um job ativo por vez na lane;
- o "pool" significa backlog e estados de job, nao multiplos workers reais;
- politica de substituicao/cancelamento para pedidos que miram o mesmo
bank/slot;
- status para pending/backlog, ativo, progresso, cancelamento, erro de
decode e sucesso.
3. Fases do asset load.
Separar:
- request e alocacao de handle;
- leitura de bytes;
- decode/materializacao;
- staging de resultado;
- install/commit em banco residente.
Ponto a fechar: quais fases rodam na terceira lane e quais voltam para a
lane principal por determinismo/ownership.
4. Inclusao de FS na mesma lane.
Verificar se `fs` deve usar a terceira lane no v1 para:
- leituras grandes;
- escritas;
- listagem;
- delete;
- memcard commit/read/write.
Ponto a fechar: FS sync publico continua bloqueante/status-first, vira
request/poll, ou ganha apenas uma implementacao interna que drena trabalho em
pontos de frame.
5. Separacao por dominio.
Decidir se `asset` e `fs` compartilham uma fila com classes de prioridade ou
se a terceira lane contem subfilas dedicadas.
6. Politica de prioridade.
Definir:
- prioridade de loads visuais vs audio;
- prioridade de save/config;
- prioridade de memcard commit;
- starvation prevention;
- limite de trabalho de instalacao/publicacao por frame.
7. Modelo de retorno e telemetria.
Fechar como guest/runtime observa:
- `pending`;
- `loading`;
- `ready`;
- `canceled`;
- `backend_unavailable`;
- backlog;
- posicao de um asset no backlog;
- progresso percentual do asset ativo;
- drops/retries quando aplicavel.
8. Orcamento para hardware barato.
Definir o baseline:
- VM principal;
- render worker;
- terceira async work lane;
- limites de memoria para jobs pendentes e buffers temporarios.
## Opcoes
### Opcao A - Terceira lane unica com subfilas e pool limitado de assets
- **Abordagem:** criar uma async work lane dedicada. Assets usam um pool/fila
de jobs nessa lane; FS tambem pode submeter jobs na mesma lane, com
prioridade menor ou classe separada.
- **Pro:** modelo simples de budget; evita explosao de threads; encaixa no alvo
de terceira core; permite compartilhar backpressure e telemetria.
- **Contra:** assets e FS podem competir por IO; precisa politica clara para
evitar que save/config fique atras de loads longos.
- **Manutenibilidade:** boa se a lane tiver tipos de job e estados explicitos.
### Opcao B - Lane de assets agora, FS apenas reservado
- **Abordagem:** fechar v1 somente para asset loading, removendo `spawn` por
request. FS continua sincrono por enquanto, mas o contrato da lane reserva
compatibilidade para FS no futuro.
- **Pro:** menor escopo; resolve a dor concreta de assets rapidamente; evita
alterar semantica de FS antes da agenda de app home filesystem.
- **Contra:** nao resolve stalls reais de FS/memcard; pode exigir refatorar a
lane depois para aceitar FS.
- **Manutenibilidade:** boa no curto prazo, com risco de segunda migracao.
### Opcao C - Lanes separadas para asset e FS
- **Abordagem:** criar uma lane/pool para assets e outra para FS.
- **Pro:** isolamento forte; FS/save nao compete diretamente com loads de
textura/audio/cena.
- **Contra:** consome mais threads/cores; contraria a premissa de terceira core
unica; pior para hardware simples.
- **Manutenibilidade:** media; isolamento ajuda, mas a topologia fica pesada.
### Opcao D - Pool global pequeno sem nocao de terceira lane
- **Abordagem:** trocar `spawn` por request por um pool global fixo.
- **Pro:** simples de implementar em host desktop.
- **Contra:** perde a arquitetura de lanes por core; pode mascarar custo em
desktop; fica menos claro como mapear para hardware alvo.
- **Manutenibilidade:** baixa para o modelo de console se virar dependencia
acidental de scheduler do SO.
## Sugestao / Recomendacao
Recomendo seguir com a Opcao A como direcao de arquitetura, mas fechar a
decisao em duas camadas:
1. Contrato obrigatorio agora:
- terceira async work lane como recurso runtime;
- assets deixam de usar `thread::spawn` por requisicao;
- asset loading passa por backlog consultavel/reordenavel;
- status, progresso e telemetria de backlog ficam explicitos.
2. Contrato condicionado para FS:
- FS deve ser analisado como consumidor legitimo da mesma lane porque suas
operacoes podem envolver IO real e ja sao custosas/nao deterministicas;
- a decisao precisa escolher entre incluir FS no v1 ou reservar a lane para
FS sem mudar ainda a superficie publica;
- memcard precisa ser considerado junto com FS, porque usa a mesma
capacidade e backend de persistencia.
O ponto importante: a terceira core/lane deve ser a unidade de concorrencia.
O pool de assets deve existir dentro desse modelo, nao como criacao livre de
threads por load.
## Respostas Consolidadas Ate Aqui
1. O pool de assets deve ser uma lane serial.
- Ha exatamente um job ativo na async work lane.
- O pool representa backlog, estados e controle de ordem, nao multiplos
workers executando em paralelo.
2. O backlog de pedidos deve ser semanticamente ilimitado.
- Nao existe `queue_full` como status normal do dominio.
- Como cada pedido mira um `bank_type/slot` e pedidos novos para o mesmo
alvo substituem os anteriores, o backlog efetivo fica limitado pela soma
dos slots dos bancos.
- O contrato nao precisa expor limite de fila, mas a implementacao deve
garantir que metadados de handles cancelados/superseded nao crescam sem
coleta.
3. Asset loading precisa expor consulta e reordenacao do backlog.
- Deve existir API publica/runtime para consultar onde um asset esta no
backlog.
- Deve existir capacidade de adiantar ou atrasar um pedido de asset na fila.
- O asset ativo deve expor progresso percentual.
- Requests novos para o mesmo `bank_type/slot` devem cancelar pedidos
anteriores pendentes para aquele alvo, evitando carregar asset que ja foi
substituido antes de executar.
- Se o alvo ja estiver carregado com o mesmo `asset_id`, o novo request nao
entra no backlog; ele retorna imediatamente pronto com handle disponivel.
- Se um novo request substituir o alvo atualmente ativo, a lane deve cancelar
em ponto cooperativo quando possivel; se o trabalho nao puder ser
interrompido, o resultado antigo deve ser descartado ao final por geracao
superseded.
- `superseded` significa que um request foi substituido por outro request
mais novo para o mesmo `bank_type/slot`. Nao e erro e nao e cancelamento
manual; e obsolescencia operacional do pedido antigo.
- Handles representam o slot do bank como alvo estavel. Dentro do estado do
handle deve existir uma secao de request/backlog para aquele slot,
informando se ha pedido pendente/ativo, qual asset foi solicitado,
progresso, posicao e geracao.
- Handles devem ser capazes de consultar o estado do alvo `bank_type/slot`
a qualquer momento. Se nao houver asset valido carregado e tambem nao
houver request pendente para aquele alvo, a consulta deve retornar estado
explicito de vazio/invalido, nao falhar por ausencia de request ativo.
4. Decode/materializacao fria rodam na terceira lane.
- Leitura e decode de asset podem acontecer fora da lane principal.
- O resultado deve voltar como material pronto/staged.
5. Install/commit em bancos residentes continua na lane principal.
- A async lane prepara trabalho.
- A lane principal publica/instala em pontos previsiveis por ownership,
determinismo e integracao com bancos/render/audio.
6. FS e memcard entram como consumidores possiveis da mesma lane, mas precisam
ser melhor amarrados com a agenda de app home filesystem.
- A `DSC-0007` / `AGD-0006` deve ser ajustada para estabelecer melhor a
superficie publica e o modelo async/sync de FS.
- Esta agenda deve afirmar a existencia da lane para trabalhos async de IO
desse tipo e permitir que FS a consuma.
- Questoes de API publica de FS, request/poll e semantica de app home devem
ficar a cargo da agenda 6.
- FS, memcard e assets nao devem operar sobrepostos quando isso gerar
concorrencia real de backend; se houver competicao, a fila unica resolve a
ordem.
7. Prioridade quando houver competicao:
- memcard commit/write;
- FS write/config;
- asset visual/audio load;
- list/read nao critico.
8. Status-first continua valendo.
- `backend_unavailable`, `canceled`, erro de decode e estados de job sao
status operacionais.
- Cancelamento por superseding de pedido no mesmo bank/slot e resultado
operacional normal, nao fault.
- Nao ha `queue_full` no contrato esperado.
- Trap permanece para violacao estrutural, como argumento invalido,
capability ausente ou handle estruturalmente invalido.
9. Telemetria minima:
- backlog atual;
- posicao por asset;
- progresso percentual do asset ativo;
- jobs submetidos, concluidos, falhos e cancelados;
- tempo por job;
- percentis por asset enquanto estiver carregando na lane.
10. Escopo da agenda.
- O foco desta agenda e a lane, assets e memcard/game persistence.
- FS entra como consumidor permitido da lane de IO, mas as decisoes de API
publica de FS pertencem a `AGD-0006`.
11. API de backlog.
- A API inicial sugerida cobre os casos esperados.
- `asset.backlog_promote(handle)` deve ser mantido como atalho oficial para
`asset.backlog_move(handle, 1)`.
- `asset.backlog_demote(handle)` deve ser mantido como atalho oficial para
mover o pedido para o fim dos pendentes.
- Os atalhos nao criam semantica nova; apenas evitam que o caller calcule
posicoes comuns.
- O handle deve permitir consulta estavel do slot do bank mesmo quando nao ha
asset valido carregado.
- O estado do handle deve separar:
- estado do slot/residencia atual;
- estado do request/backlog atual para aquele slot.
- Operacoes que mudam estado, como commit/cancel/reorder, atuam sobre a
secao de request/backlog do handle e precisam validar geracao/request atual
para nao agir sobre um pedido substituido.
12. Cancelamento por substituicao.
- Quando um request novo chega para o mesmo `bank_type/slot`, o request
anterior e marcado imediatamente como `superseded`.
- Se o request anterior ainda estiver no backlog, ele sai da fila.
- Se o request anterior estiver ativo, a lane tenta cancelar
cooperativamente quando a fase atual permitir.
- Se a fase ativa nao puder ser interrompida com baixo custo, ela termina e
o resultado e descartado ao final porque a geracao do alvo ja mudou.
- Como o handle pertence ao slot do bank, ele continua consultavel; sua
secao de request deve indicar que a geracao anterior foi `superseded` ou
que nao ha request ativo para aquele alvo.
13. Fases de progresso.
- `read/decode/stage` e suficiente como modelo minimo para `GLYPH`, `SOUND`
e `SCENE`.
- Subfases futuras podem detalhar progresso dentro de `decode` sem mudar o
contrato geral.
14. Percentis.
- Percentis devem existir por `bank_type` como telemetria principal.
- Percentis por `asset_id` tambem sao uteis, mas podem usar janela pequena
ou agregador leve.
- Percentis sao atualizados no fechamento do job, nao durante o hot path.
15. Ajuste esperado na agenda de FS.
- `AGD-0006` deve registrar que existe uma async IO lane compartilhavel por
FS/memcard/assets.
- Esta agenda so decide que FS pode consumir a lane.
- A API publica de FS, incluindo request/poll ou sync aparente, pertence a
`AGD-0006`.
## API Inicial Sugerida Para Assets
Esta agenda ainda nao fecha nomes finais de ABI, mas a direcao inicial sugerida
e manter `asset.load/status/commit/cancel` e adicionar uma superficie pequena
para backlog:
1. `asset.backlog_info() -> (status, pending_count, active_handle, active_asset_id, active_bank_type, active_slot, active_progress)`
- Consulta o estado geral da lane de assets.
- `active_progress` usa escala inteira, preferencialmente `0..10000` para
permitir duas casas decimais sem float.
2. `asset.backlog_position(handle) -> (status, state, position, progress)`
- Consulta um pedido especifico.
- `position = 0` significa job ativo.
- `position > 0` significa posicao no backlog.
- `position = -1` pode representar nao enfileirado/pronto/cancelado,
dependendo do `state`.
3. `asset.backlog_move(handle, new_position) -> status`
- Move um pedido pendente para uma posicao absoluta.
- `new_position = 1` significa primeiro pendente depois do ativo.
- Nao interrompe diretamente o job ativo; substituicao do mesmo
`bank_type/slot` usa a regra de superseding.
4. `asset.backlog_promote(handle) -> status`
- Atalho para mover o pedido para a frente do backlog pendente.
5. `asset.backlog_demote(handle) -> status`
- Atalho para mover o pedido para o fim do backlog pendente.
6. `asset.target_status(bank_type, slot) -> (status, asset_id, handle, state, position, progress)`
- Consulta por alvo operacional, que e o que realmente controla superseding.
- Ajuda quando o caller quer saber "o que esta programado para este slot".
Estados sugeridos para `state`:
- `empty`;
- `invalid`;
- `queued`;
- `active`;
- `ready`;
- `committed`;
- `canceled`;
- `superseded`;
- `error`;
- `backend_unavailable`.
Regra de design: APIs de backlog sao operacionais e status-first. Reordenar um
handle inexistente, ja concluido ou ja superseded retorna status operacional
apropriado quando o handle e conhecido; violações estruturais continuam Trap.
Handles sao observaveis e representam slots de banks. Um handle conhecido pode
ser consultado mesmo quando o slot alvo nao contem asset valido carregado; nesse
caso a consulta deve retornar estado como `empty` ou `invalid`.
O estado do handle deve conter pelo menos duas partes:
```text
slot_state:
loaded_asset_id
resident_state
request_state:
requested_asset_id
generation
queued/active/ready/canceled/superseded/error
backlog_position
progress
```
Mutacoes seguem regras mais estritas e devem falhar operacionalmente quando a
secao de request/backlog do handle nao representa a geracao atual.
## Progresso e Percentis
### Progresso percentual
Sugestao:
- usar progresso em base inteira `0..10000`;
- quando o tamanho total de bytes for conhecido, calcular progresso por fases
ponderadas;
- quando o decode nao for linear ou nao houver tamanho confiavel, expor
progresso por fase com marcos conservadores.
Modelo inicial de fases:
```text
queued -> 0
read -> 0..4000
decode -> 4000..9000
stage -> 9000..10000
ready -> 10000
```
Se uma fase nao consegue reportar progresso interno, ela deve manter o ultimo
marco e saltar para o proximo marco ao concluir. Isso evita progresso falso
sem perder visibilidade de fase.
### Percentis por asset
Sugestao:
- registrar duracoes por asset no fim de cada job, nao por tick/frame;
- manter agregadores pequenos por `asset_id` e por `bank_type`;
- calcular percentis a partir de janela/ring buffer pequeno ou histograma
barato por bucket de duracao;
- nunca atualizar percentis no loop quente de decode por item/pixel;
- o job ativo pode expor tempo decorrido e fase atual; percentis sao atualizados
apenas no fechamento do job.
## Perguntas em Aberto
- [x] A agenda esta madura para virar decisao normativa ou ainda falta algum
caso de asset/memcard/lane?
- [x] A estrutura minima de `slot_state` e `request_state` no handle esta
completa ou falta algum campo para commit/cancel/reorder seguro?
## Resolucao
A agenda esta madura para decisao normativa.
A decisao deve formalizar:
- a terceira async work lane serial;
- um job ativo por vez;
- backlog efetivamente limitado pela unicidade de `bank_type/slot`;
- handles como observadores estaveis de slots de bank;
- `slot_state` e `request_state` dentro do handle;
- cancelamento/superseding por novo request para o mesmo alvo;
- load pronto imediato quando o asset ja esta residente no alvo;
- decode/materializacao na lane async;
- commit/install na lane principal;
- memcard como consumidor prioritario da mesma lane;
- FS como consumidor permitido, deixando API publica de FS para `AGD-0006`;
- progresso por fases e percentis atualizados no fechamento do job.
## Dependencias
- `docs/specs/runtime/09-events-and-concurrency.md`
- `docs/specs/runtime/15-asset-management.md`
- `docs/specs/runtime/16a-syscall-policies.md`
- `discussion/workflow/agendas/AGD-0006-app-home-filesystem-surface-and-semantics.md`
## Criterio para Encerrar
Pode virar PR quando houver decisao escrita sobre:
- existencia e papel da terceira async work lane;
- relacao dessa lane com a terceira core no hardware alvo e fallback no host;
- desenho do backlog serial de asset loading;
- regra de cancelamento/substituicao para requests no mesmo bank/slot;
- proibicao de `thread::spawn` por load no caminho normal;
- fases de asset load que rodam na lane vs lane principal;
- inclusao condicionada de FS/memcard nessa mesma lane;
- API de consulta e reordenacao do backlog de assets;
- comportamento de request imediato quando o asset ja esta residente no alvo;
- regra de bounded backlog por unicidade de `bank_type/slot`;
- politica de prioridade entre asset, FS e memcard;
- status e telemetria para backlog, progresso, percentis, cancelamento e falha.
## Discussao
- 2026-06-28: Agenda atualizada para remover render worker do escopo, assumir
uma terceira core/lane para trabalhos assincronos, exigir pool/fila limitada
para asset loading e reavaliar o papel de FS/memcard como consumidores da
mesma lane.
- 2026-06-28: Discussao consolidou que a async work lane deve ser serial, com
um job ativo, backlog semanticamente ilimitado, consulta/reordenacao publica
de backlog de assets, progresso percentual do asset ativo, decode na lane
async, install/commit na lane principal, e FS/memcard como consumidores a
alinhar com a agenda de app home filesystem.
- 2026-06-28: Acrescentada regra de asset pipe: requests para o mesmo bank/slot
devem cancelar pedidos anteriores pendentes para aquele alvo, tratando o
pedido mais novo como substituto operacional.
- 2026-06-28: Discussao refinou que o alvo canonico e `bank_type/slot`; um
asset ja residente deve retornar handle pronto sem entrar no backlog; o
backlog efetivo e limitado pela soma dos slots dos bancos; FS fica como
consumidor permitido da lane, enquanto API publica de FS permanece na agenda
6; progresso deve usar fases conservadoras e percentis devem ser atualizados
no fechamento do job, nao no hot path.
- 2026-06-28: Open questions restantes foram consolidadas: API de backlog
aceita com `promote/demote` como atalhos; superseding marca requests
substituidos por outro request para o mesmo `bank_type/slot`; cancelamento do
ativo e cooperativo quando barato e descarte por geracao quando nao for;
`read/decode/stage` cobre GLYPH/SOUND/SCENE; percentis ficam por `bank_type`
e por `asset_id`; API publica de FS permanece em `AGD-0006`.
- 2026-06-28: Adicionada a expectativa de que handles possam consultar o alvo
`bank_type/slot` a qualquer momento, inclusive quando nao houver asset valido
carregado; mutacoes devem continuar protegidas por request/geracao para evitar
commit/cancel acidental de pedidos substituidos.
- 2026-06-28: Refinado o modelo de handle: o handle pertence ao slot do bank e
contem uma secao de estado de request/backlog para aquele slot. Consulta e
residencia ficam estaveis por alvo; mutacoes atuam sobre a geracao atual do
request dentro do handle.
@@ -1,126 +0,0 @@
---
id: AGD-0041
ticket: foreground-stack-game-pause-shell-vm-backed
title: Foreground Stack, Game Pause, and VM-Backed Shell Coexistence
status: open
created: 2026-06-05
resolved:
decision:
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
- [ ] Qual e o nome canonico dos estados de Game fora do foreground: `Paused`, `Suspended`, ambos, ou outro?
- [ ] Ao apertar Home, o Game deve receber um evento/interrupt/trap de pausa antes de parar de executar?
- [ ] O Hub e um Shell especial sempre presente ou uma task Shell comum?
- [ ] Um app Shell VM-backed pode substituir o Hub no foreground ou o Hub permanece como owner raiz?
- [ ] Quando o Shell VM-backed fecha, o retorno vai sempre para Hub ou pode voltar diretamente ao Game?
- [ ] O input do Game e drenado/limpo ao pausar e ao retomar?
- [ ] Audio do Game pausa junto com a VM ou tem politica propria?
- [ ] Existe limite de memoria/residencia para manter Game pausado enquanto Shell app roda?
- [ ] O retorno ao Game exige novo frame antes de trocar a superficie, ou a tela pode manter Hub/Shell ate a primeira submission valida?
- [ ] Quais eventos de lifecycle precisam ser visiveis para firmware, OS, VM e host?
## 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.
@@ -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,336 +0,0 @@
---
id: DEC-0034
ticket: perf-async-background-work-lanes-for-assets-and-fs
title: Async Work Lane and Asset Backlog Contract
status: accepted
created: 2026-06-28
accepted: 2026-06-28
ref_agenda: AGD-0008
plans: [PLN-0123, PLN-0124, PLN-0125, PLN-0126, PLN-0127, PLN-0128]
tags: [perf, asset, fs, async, scheduler, runtime]
---
# DEC-0034 - Async Work Lane and Asset Backlog Contract
## Status
Accepted.
## Contexto
`asset.load()` currently creates an OS thread per non-resident asset request.
That behavior does not match the target runtime model: the machine should have
explicit execution lanes, bounded ownership, observable backpressure, and no
uncontrolled thread creation from guest-visible operations.
Render worker concurrency is already handled by separate render decisions. This
decision covers the third runtime lane for asynchronous IO/decode/persistence
work:
```text
Lane 1: VM, firmware, SystemOS, logical frame
Lane 2: render worker / asynchronous rasterization
Lane 3: async work lane for asset IO/decode and game persistence work
```
The concrete first consumer is asset loading. Game persistence through memcard
may also consume this lane. FS is allowed to consume this lane, but public FS API
shape belongs to the app-home filesystem agenda.
## Decisao
Prometeu MUST introduce a third async work lane as the runtime-owned execution
place for asset IO/decode work and compatible persistence IO work.
The async work lane MUST be serial: it has exactly one active job at a time.
The runtime MUST NOT create one OS thread per `asset.load` request in the normal
path.
Asset loading MUST use a backlog keyed by target `bank_type/slot`. A target can
have at most one current request. A newer request for the same `bank_type/slot`
MUST supersede the previous request for that target.
Asset handles MUST represent stable bank slots, not transient worker threads.
A handle MUST remain queryable even when the slot has no valid loaded asset and
even when there is no active request for that slot. The handle state MUST
separate resident slot state from request/backlog state.
Asset IO/read and decode/materialization MUST run on the async work lane.
Asset install/commit into resident banks MUST happen on the main runtime lane at
predictable ownership points.
Memcard work MAY consume the same async work lane and has higher priority than
ordinary asset loads when contention exists. FS MAY consume the same lane for
IO-style work, but this decision does not define the public FS API.
## Rationale
A serial lane maps cleanly to the intended third-core mental model and avoids a
desktop-biased generic thread pool. It gives the runtime one place to observe
IO/decode backlog, progress, priority, cancellation, and telemetry.
Keying requests by `bank_type/slot` makes the backlog naturally bounded by the
sum of bank slots. There is no need for a guest-visible `queue_full` state:
there cannot be unbounded distinct pending targets if each target has at most
one current request.
Keeping commit/install on the main lane preserves deterministic publication
semantics and avoids letting the async lane mutate resident graphics/audio/scene
state while the VM, render handoff, or frame boundary is observing it.
Separating `slot_state` and `request_state` inside the handle avoids ambiguity:
callers can inspect the slot at any time, while mutating operations still remain
protected by request generation.
## Invariantes / Contrato
### Async Work Lane
- The async work lane MUST be runtime-owned.
- The async work lane MUST be separate from the render worker.
- The async work lane MUST execute at most one active job at a time.
- The runtime MUST NOT use `thread::spawn` per asset request in the normal
asset loading path.
- The host may implement the lane as a fixed worker thread. Hardware targets may
map it to a dedicated core when available.
- If a physical third core is unavailable, the implementation MUST preserve the
same logical lane contract.
### Asset Backlog
- Asset requests MUST target a concrete `bank_type/slot`.
- The backlog is ordered and serial.
- Each `bank_type/slot` MUST have at most one current request.
- A newer request for the same `bank_type/slot` MUST supersede any earlier
pending request for that target.
- If the target already contains the requested `asset_id` as a valid resident
asset, `asset.load` MUST return a handle in ready state without adding a job
to the backlog.
- The effective backlog size is bounded by the sum of targetable bank slots,
even though the contract does not expose a fixed queue limit.
- Implementations MUST collect stale metadata for canceled or superseded
requests so the handle/request history does not grow without bound.
### Handles
An asset handle MUST represent a stable bank slot target. The handle state MUST
include at least:
```text
handle:
bank_type
slot
slot_state:
loaded_asset_id
resident_state
slot_generation
request_state:
requested_asset_id
request_generation
state
backlog_position
progress
```
The handle MUST be queryable when:
- the slot is empty;
- the slot contains a valid resident asset;
- a request is queued;
- a request is active;
- a request is ready for commit;
- a request has been canceled;
- a request has been superseded;
- a request ended in error.
Mutating operations such as commit, cancel, promote, demote, or move MUST act on
the current request generation. They MUST NOT accidentally mutate a newer
request through an older handle view.
### Superseding
`superseded` means a request was replaced by a newer request for the same
`bank_type/slot`.
- Superseding is an operational state, not a fault.
- If the old request is queued, it MUST be removed from the backlog.
- If the old request is active, the lane SHOULD cancel cooperatively when the
current phase supports cheap cancellation.
- If active work cannot be interrupted cheaply, it MAY finish, but its result
MUST be discarded when its generation no longer matches the target's current
request generation.
### Asset Backlog API Direction
The existing asset operations remain the base surface:
```text
asset.load(asset_id, slot) -> (status, handle)
asset.status(handle) -> status
asset.commit(handle) -> status
asset.cancel(handle) -> status
```
The asset backlog surface SHOULD add a small status-first API:
```text
asset.backlog_info()
-> (status, pending_count, active_handle, active_asset_id,
active_bank_type, active_slot, active_progress)
asset.backlog_position(handle)
-> (status, state, position, progress)
asset.backlog_move(handle, new_position)
-> status
asset.backlog_promote(handle)
-> status
asset.backlog_demote(handle)
-> status
asset.target_status(bank_type, slot)
-> (status, asset_id, handle, state, position, progress)
```
`asset.backlog_promote(handle)` is an official shortcut for moving a queued
request to position `1`, the first pending position after the active job.
`asset.backlog_demote(handle)` is an official shortcut for moving a queued
request to the end of the pending backlog.
The final ABI names and exact return shapes may be refined during planning, but
the implementation MUST preserve the capabilities above.
### Progress
Progress MUST be represented without floating point. The recommended scale is
`0..10000`.
The initial phase model is:
```text
queued -> 0
read -> 0..4000
decode -> 4000..9000
stage -> 9000..10000
ready -> 10000
```
If a phase cannot report internal progress, it MUST keep the previous progress
mark and advance at phase completion. Implementations MUST NOT invent false
precision for non-linear decode phases.
### Telemetry
Telemetry MUST be cheap and must not add hot-path per-item decode cost.
Minimum telemetry:
- current backlog depth;
- target/request position;
- active job progress;
- jobs submitted;
- jobs completed;
- jobs failed;
- jobs canceled;
- jobs superseded;
- job duration;
- percentiles by `bank_type`;
- lightweight percentiles or small-window samples by `asset_id`.
Percentiles MUST be updated when a job closes, not inside the inner decode loop.
### Priority
When async lane consumers contend, the initial priority order is:
1. memcard commit/write;
2. FS write/config work;
3. asset visual/audio/scene load;
4. non-critical list/read work.
This priority order is a lane arbitration rule. It does not define public FS
syscall semantics.
### FS Boundary
FS MAY consume the async work lane for IO-style work.
This decision MUST NOT define the public FS API, app-home FS semantics, or
whether FS is exposed as request/poll or sync-appearing operations. Those
questions belong to `AGD-0006`.
`AGD-0006` MUST be updated or interpreted with the existence of this async IO
lane in mind.
## Impactos
### Spec
- `docs/specs/runtime/15-asset-management.md` must absorb the async lane,
backlog, handle, superseding, progress, and telemetry contract.
- `docs/specs/runtime/16-host-abi-and-syscalls.md` must absorb any final public
asset backlog syscall names and return shapes.
- `docs/specs/runtime/16a-syscall-policies.md` may need status catalog updates
for superseded/canceled/backend unavailable states if not already covered by
asset domain status.
- `docs/specs/runtime/09-events-and-concurrency.md` should mention the async
work lane as an implementation-side lane that does not introduce guest
callbacks.
- `AGD-0006` / future FS spec work must account for FS as a possible consumer of
the async IO lane.
### Runtime
- Asset loading must stop spawning a thread per request.
- AssetManager needs a serial backlog keyed by `bank_type/slot`.
- Asset handles need stable slot identity plus separated `slot_state` and
`request_state`.
- Commit/install remains a main-lane operation.
- Superseding and generation checks become required correctness mechanisms.
### Host
- Desktop host may implement the async work lane with one fixed worker thread.
- Host presentation/render worker remains separate and unaffected.
### Firmware
- No direct firmware behavior is required for asset backlog mechanics.
- Firmware flows that rely on preload or memcard may later use lane telemetry or
priority policy if needed.
### Tooling
- Test tools may need support for inspecting backlog state and forcing request
ordering.
- Asset fixtures should cover queued, active, ready, canceled, superseded, and
already-resident paths.
## Referencias
- `AGD-0008` - Async Background Work Lanes for Assets and FS.
- `docs/specs/runtime/15-asset-management.md`
- `docs/specs/runtime/16-host-abi-and-syscalls.md`
- `docs/specs/runtime/16a-syscall-policies.md`
- `docs/specs/runtime/09-events-and-concurrency.md`
- `docs/specs/runtime/08-save-memory-and-memcard.md`
- `AGD-0006` - App Home Filesystem Surface and Semantics.
## Propagacao Necessaria
1. Update asset management specs with the lane/backlog/handle contract.
2. Update syscall specs if backlog APIs become public ABI.
3. Update FS agenda/spec work to acknowledge the async IO lane without deciding
FS public API in this decision.
4. Plan implementation of a serial async work lane and asset backlog.
5. Plan tests for superseding, stable slot handles, immediate-ready resident
assets, progress, telemetry, and main-lane commit.
## Revision Log
- 2026-06-28: Initial draft from `AGD-0008`.
@@ -1,118 +0,0 @@
---
id: PLN-0123
ticket: perf-async-background-work-lanes-for-assets-and-fs
title: Async Work Lane Specification Propagation
status: open
created: 2026-06-28
completed:
ref_decisions: [DEC-0034]
tags: [perf, asset, fs, async, scheduler, runtime, spec]
---
# PLN-0123 - Async Work Lane Specification Propagation
## Briefing
`DEC-0034` establishes a third serial async work lane, asset backlog semantics,
stable bank-slot handles, superseding, progress, telemetry, and FS/memcard lane
boundaries. The canonical specs must be updated before code work relies on the
new contract.
## Decisions de Origem
- `DEC-0034` - Async Work Lane and Asset Backlog Contract.
## Alvo
Publish the accepted async work lane and asset backlog contract in the canonical
runtime specs.
## Escopo
Included:
- Update asset management spec.
- Update syscall ABI spec if public backlog APIs are named there.
- Update syscall policy/status language for operational asset states.
- Update events/concurrency spec with the async work lane as an implementation
lane that does not introduce guest callbacks.
- Add a cross-reference from FS/app-home agenda or notes to the async IO lane.
Fora de Escopo:
- Implementing runtime code.
- Finalizing public FS API semantics.
- Changing render worker contracts.
## Plano de Execucao
### Step 1 - Update Asset Management
**What:** Add the third async lane, backlog, handle, superseding, progress, and
telemetry contract.
**How:** Extend `docs/specs/runtime/15-asset-management.md` around the existing
`asset.load/status/commit/cancel` section. Preserve the existing
`asset.load(asset_id, slot)` identity contract.
**Files:** `docs/specs/runtime/15-asset-management.md`.
### Step 2 - Update Host ABI
**What:** Add the backlog API direction if the ABI spec is the canonical place
for syscall shapes.
**How:** Extend the asset surface section with the planned backlog operations,
marking exact numeric ids as implementation-plan work if ids are not assigned
yet.
**Files:** `docs/specs/runtime/16-host-abi-and-syscalls.md`.
### Step 3 - Update Syscall Policies
**What:** Clarify that `superseded`, `canceled`, `backend_unavailable`, and
decode failures are operational statuses, not faults.
**How:** Add asset-domain examples under status-first policy.
**Files:** `docs/specs/runtime/16a-syscall-policies.md`.
### Step 4 - Update Events and Concurrency
**What:** Document that the async work lane is an implementation lane.
**How:** Add a section next to render worker concurrency stating that asset/IO
lane work does not introduce guest callbacks or hidden guest execution.
**Files:** `docs/specs/runtime/09-events-and-concurrency.md`.
### Step 5 - Cross-Reference FS Work
**What:** Record that FS may consume the async IO lane, while public FS API
semantics remain owned by the app-home filesystem discussion.
**How:** Add a note in `AGD-0006` or its future decision input, without deciding
FS request/poll shape in this plan.
**Files:** `discussion/workflow/agendas/AGD-0006-app-home-filesystem-surface-and-semantics.md`.
## Criterios de Aceite
- [ ] Specs state that the async work lane is serial and separate from render.
- [ ] Asset spec states backlog keying by `bank_type/slot`.
- [ ] Asset spec states stable slot handles with `slot_state` and `request_state`.
- [ ] Asset spec states superseding behavior.
- [ ] Asset spec states main-lane commit/install.
- [ ] FS is cross-referenced as a permitted lane consumer without public API decisions.
## Tests / Validacao
- Run `discussion validate`.
- Review spec links for broken relative paths.
- No cargo tests are required for this documentation-only plan.
## Riscos
- Public ABI names may be refined later; the spec must avoid assigning ids too
early if implementation work has not reserved them.
- FS scope can leak into this work; keep FS public API decisions in `AGD-0006`.
@@ -1,119 +0,0 @@
---
id: PLN-0124
ticket: perf-async-background-work-lanes-for-assets-and-fs
title: Async Work Lane Runtime Infrastructure
status: open
created: 2026-06-28
completed:
ref_decisions: [DEC-0034]
tags: [perf, asset, fs, async, scheduler, runtime]
---
# PLN-0124 - Async Work Lane Runtime Infrastructure
## Briefing
`DEC-0034` requires one runtime-owned async work lane, separate from VM/main
execution and separate from render worker execution. This plan introduces the
lane infrastructure before migrating asset loading.
## Decisions de Origem
- `DEC-0034` - Async Work Lane and Asset Backlog Contract.
## Alvo
Create a serial async work lane primitive that can execute one active job at a
time, expose observable state, and support deterministic shutdown.
## Escopo
Included:
- Runtime-owned async work lane type.
- Single active job execution.
- Ordered pending job storage.
- Cooperative cancellation hook.
- Shutdown and join behavior.
- Basic lane telemetry.
Fora de Escopo:
- Public asset backlog syscalls.
- Asset handle model migration.
- FS public API.
- Render worker changes.
## Plano de Execucao
### Step 1 - Locate Runtime Service Boundary
**What:** Choose the crate/module boundary for the async lane.
**How:** Place generic lane infrastructure near VM runtime services, not inside
desktop host code and not inside render worker modules.
**Files:** likely `crates/console/prometeu-system/src/services/` or
`crates/console/prometeu-system/src/services/vm_runtime/`.
### Step 2 - Define Job and Lane Types
**What:** Add a lane type with pending queue, active job metadata, generation,
state, progress, and cancellation flag.
**How:** Use typed job enums or traits that do not require guest callbacks.
Start with internal asset job support but keep the lane generic enough for
memcard/FS later.
**Files:** new module under `prometeu-system` service layer.
### Step 3 - Implement Serial Worker
**What:** Implement one worker loop that takes one pending job and runs it to
completion or cooperative cancellation.
**How:** Use a fixed worker thread on host builds. Preserve a logical-lane API
so future hardware can map it to a dedicated core.
**Files:** async lane module; lifecycle wiring in VM runtime service setup.
### Step 4 - Implement Shutdown
**What:** Add explicit stop/shutdown behavior.
**How:** Wake the lane, stop accepting new jobs, report pending jobs as canceled
or shutdown-discarded, and join the worker with bounded behavior.
**Files:** async lane module and VM runtime lifecycle modules.
### Step 5 - Expose Internal Telemetry
**What:** Add counters for pending depth, active job, submitted, completed,
failed, canceled, and superseded.
**How:** Use cheap atomics or lane-owned state snapshots. Do not update
expensive percentile data inside inner decode loops.
**Files:** async lane module; telemetry structs where runtime telemetry lives.
## Criterios de Aceite
- [ ] Lane has one active job maximum.
- [ ] Lane is separate from render worker code.
- [ ] Lane can be started and stopped deterministically.
- [ ] Pending jobs are observable.
- [ ] Cooperative cancellation can be signaled.
- [ ] No guest callback path is introduced.
## Tests / Validacao
- Unit tests for enqueue, single active execution, ordering, cancellation signal,
and shutdown.
- Concurrency tests must synchronize on real state transitions, not sleeps.
- Run targeted `cargo test` for the owning crate.
## Riscos
- Accidentally creating a generic pool instead of a serial lane.
- Coupling the lane to desktop host thread details.
- Reusing render worker handoff semantics where ordered backlog is required.
@@ -1,127 +0,0 @@
---
id: PLN-0125
ticket: perf-async-background-work-lanes-for-assets-and-fs
title: Asset Backlog and Stable Slot Handles
status: open
created: 2026-06-28
completed:
ref_decisions: [DEC-0034]
tags: [perf, asset, async, runtime]
---
# PLN-0125 - Asset Backlog and Stable Slot Handles
## Briefing
`DEC-0034` changes asset loading from request-owned thread spawning to a serial
backlog keyed by `bank_type/slot`. Handles become stable bank-slot observers
with separate resident slot state and request state.
## Decisions de Origem
- `DEC-0034` - Async Work Lane and Asset Backlog Contract.
## Alvo
Refactor `AssetManager` so asset requests are tracked by target bank slot,
deduplicated/superseded by target, and observable through stable handles.
## Escopo
Included:
- Stable handle structure with `bank_type`, `slot`, `slot_state`, and
`request_state`.
- Backlog keyed by `bank_type/slot`.
- Already-resident fast path.
- Superseding for queued and active requests.
- Main-lane commit/install boundary.
Fora de Escopo:
- Public backlog syscall wiring.
- Percentile telemetry.
- FS public API.
## Plano de Execucao
### Step 1 - Model Slot Handles
**What:** Replace transient load-operation assumptions with stable bank-slot
handle state.
**How:** Introduce structures equivalent to:
```text
handle: bank_type, slot
slot_state: loaded_asset_id, resident_state, slot_generation
request_state: requested_asset_id, request_generation, state, position, progress
```
**Files:** `crates/console/prometeu-drivers/src/asset.rs` and HAL asset types if
public type definitions belong there.
### Step 2 - Key Backlog by Target
**What:** Ensure at most one current request per `bank_type/slot`.
**How:** Add a target index from `(bank_type, slot)` to current request
generation/handle state. Enqueue only when the target does not already have the
same resident asset and no newer request supersedes it.
**Files:** `crates/console/prometeu-drivers/src/asset.rs`.
### Step 3 - Implement Already-Resident Fast Path
**What:** Return a ready handle immediately when the requested asset already
resides in the target slot.
**How:** Compare requested `asset_id` with the target `slot_state.loaded_asset_id`
and resident validity before creating a queued job.
**Files:** `crates/console/prometeu-drivers/src/asset.rs`.
### Step 4 - Implement Superseding
**What:** New request for the same target supersedes previous queued or active
request.
**How:** Remove queued older request immediately. For active work, update target
generation so the old result is discarded if it cannot stop cooperatively.
**Files:** `crates/console/prometeu-drivers/src/asset.rs`; async lane module
from `PLN-0124`.
### Step 5 - Preserve Main-Lane Commit
**What:** Keep install/commit into resident banks on the main runtime lane.
**How:** Async lane produces staged materialized result. `asset.commit(handle)`
installs only when the request generation is current and ready.
**Files:** `crates/console/prometeu-drivers/src/asset.rs`; VM runtime dispatch if
commit behavior changes.
## Criterios de Aceite
- [ ] No asset load spawns an OS thread per request.
- [ ] At most one request exists per `bank_type/slot`.
- [ ] Same-target newer request supersedes older queued request.
- [ ] Same-target newer request prevents active stale result from installing.
- [ ] Already-resident target returns ready handle without backlog entry.
- [ ] Handles remain queryable for empty, queued, active, ready, committed,
canceled, superseded, and error states.
## Tests / Validacao
- Unit tests for handle state transitions.
- Unit tests for target-keyed superseding.
- Unit tests for already-resident fast path.
- Integration test for stale active result discard.
- Existing asset load/commit tests must continue passing.
## Riscos
- Confusing handle identity with request generation.
- Installing a stale async result after superseding.
- Losing compatibility with existing `asset.status/commit/cancel` behavior.
@@ -1,124 +0,0 @@
---
id: PLN-0126
ticket: perf-async-background-work-lanes-for-assets-and-fs
title: Asset Backlog Public API and Status Surface
status: open
created: 2026-06-28
completed:
ref_decisions: [DEC-0034]
tags: [perf, asset, async, syscall, runtime]
---
# PLN-0126 - Asset Backlog Public API and Status Surface
## Briefing
`DEC-0034` keeps `asset.load/status/commit/cancel` and adds a small status-first
backlog inspection and ordering surface. This plan wires that surface through
HAL syscall metadata and runtime dispatch.
## Decisions de Origem
- `DEC-0034` - Async Work Lane and Asset Backlog Contract.
## Alvo
Expose asset backlog inspection and reordering while preserving status-first
semantics and existing asset load identity.
## Escopo
Included:
- Syscall registry additions for backlog APIs.
- Runtime dispatch handlers.
- Status enum additions or normalization.
- ABI/spec alignment with `PLN-0123`.
Fora de Escopo:
- Async lane internals.
- Asset decode refactor.
- FS API.
## Plano de Execucao
### Step 1 - Finalize Syscall Shapes
**What:** Choose final names, arity, and return slots for backlog operations.
**How:** Start from `DEC-0034`:
```text
asset.backlog_info()
asset.backlog_position(handle)
asset.backlog_move(handle, new_position)
asset.backlog_promote(handle)
asset.backlog_demote(handle)
asset.target_status(bank_type, slot)
```
**Files:** `crates/console/prometeu-hal/src/syscalls/domains/asset.rs`,
`docs/specs/runtime/16-host-abi-and-syscalls.md`.
### Step 2 - Add Status Values
**What:** Represent `empty`, `invalid`, `queued`, `active`, `ready`,
`committed`, `canceled`, `superseded`, `error`, and `backend_unavailable`.
**How:** Extend or map existing `LoadStatus` and `AssetOpStatus` without
turning operational states into traps.
**Files:** HAL asset status types and `crates/console/prometeu-drivers/src/asset.rs`.
### Step 3 - Add Dispatch
**What:** Wire new syscalls through VM runtime dispatch.
**How:** Add match arms near existing `AssetLoad`, `AssetStatus`,
`AssetCommit`, and `AssetCancel` arms. Return status-first values.
**Files:** `crates/console/prometeu-system/src/services/vm_runtime/dispatch.rs`.
### Step 4 - Implement API Methods
**What:** Add AssetManager methods backing each public operation.
**How:** Methods must read stable handle/target state and reorder only queued
requests. `promote` and `demote` are shortcuts over move semantics.
**Files:** `crates/console/prometeu-drivers/src/asset.rs`.
### Step 5 - Validate ABI Metadata
**What:** Ensure registry ids, args, returns, capability, cost, and
non-deterministic flags are correct.
**How:** Update syscall metadata tests and any declared PBS/runtime syscall
tables.
**Files:** `crates/console/prometeu-hal/src/syscalls/tests.rs` and related
registry files.
## Criterios de Aceite
- [ ] Public backlog operations are registered with stable metadata.
- [ ] All backlog operations are status-first.
- [ ] `promote` is equivalent to moving to first pending position.
- [ ] `demote` moves to the end of pending backlog.
- [ ] Reordering a non-queued request returns operational status.
- [ ] Structural ABI misuse remains Trap.
## Tests / Validacao
- HAL syscall metadata tests.
- VM runtime dispatch tests for each new syscall.
- AssetManager unit tests for move/promote/demote.
- Tests for `target_status` on empty, queued, active, ready, and superseded
targets.
## Riscos
- Adding too many public ABI details before spec propagation is accepted.
- Returning payload values that are ambiguous when status is not success.
- Treating known but non-mutable states as traps instead of statuses.
@@ -1,120 +0,0 @@
---
id: PLN-0127
ticket: perf-async-background-work-lanes-for-assets-and-fs
title: Async Lane Memcard and FS Integration Boundaries
status: open
created: 2026-06-28
completed:
ref_decisions: [DEC-0034]
tags: [perf, fs, memcard, async, runtime]
---
# PLN-0127 - Async Lane Memcard and FS Integration Boundaries
## Briefing
`DEC-0034` allows memcard and FS work to consume the async IO lane but keeps
public FS API semantics out of scope. This plan establishes integration
boundaries without deciding app-home FS API shape.
## Decisions de Origem
- `DEC-0034` - Async Work Lane and Asset Backlog Contract.
## Alvo
Define and implement safe internal boundaries for memcard and FS use of the
async work lane, preserving lane priority and keeping FS public API decisions in
`AGD-0006`.
## Escopo
Included:
- Memcard as a priority lane consumer candidate.
- FS as a permitted internal lane consumer.
- Priority ordering in the lane.
- Updates to `AGD-0006` to acknowledge the lane.
Fora de Escopo:
- Public FS request/poll design.
- App-home path/status contract.
- Full memcard async conversion if it requires public ABI changes.
## Plano de Execucao
### Step 1 - Update FS Agenda
**What:** Record that an async IO lane exists and may be used by FS.
**How:** Add a concise section to `AGD-0006` stating that FS public API remains
owned by that agenda, but implementation may use the async lane from `DEC-0034`.
**Files:** `discussion/workflow/agendas/AGD-0006-app-home-filesystem-surface-and-semantics.md`.
### Step 2 - Identify Memcard Operations
**What:** List memcard operations that can benefit from async IO.
**How:** Inspect `crates/console/prometeu-system/src/services/memcard.rs` and
VM runtime dispatch for `mem.*` operations. Classify read, write, commit, and
clear behavior.
**Files:** memcard service and VM runtime dispatch modules.
### Step 3 - Define Lane Priority
**What:** Encode the initial priority order from `DEC-0034`.
**How:** Add priority classes:
```text
memcard commit/write
FS write/config
asset load
non-critical list/read
```
**Files:** async lane module from `PLN-0124`.
### Step 4 - Add Internal Consumer Hooks
**What:** Provide internal APIs for memcard/FS to submit lane jobs later.
**How:** Add types/interfaces without changing public FS syscall behavior.
No public FS request/poll operations are introduced here.
**Files:** async lane module; FS/memcard service modules as needed.
### Step 5 - Preserve Current Public Behavior
**What:** Ensure existing memcard and FS syscalls keep their current observable
surface unless a later plan explicitly changes it.
**How:** Do not alter return shapes in this plan. Add tests proving existing
status-first behavior remains intact.
**Files:** VM runtime FS/memcard tests.
## Criterios de Aceite
- [ ] `AGD-0006` acknowledges the async IO lane and keeps FS public API in its
own scope.
- [ ] Async lane supports priority classes required by `DEC-0034`.
- [ ] Memcard and FS can be represented as internal lane consumers.
- [ ] Existing public memcard/FS syscall shapes are unchanged.
- [ ] No FS public request/poll API is introduced by this plan.
## Tests / Validacao
- Existing FS/memcard tests continue passing.
- Unit tests for lane priority ordering.
- Tests proving asset jobs do not overlap with higher-priority memcard jobs
once both are submitted through the lane.
## Riscos
- Accidentally deciding FS public API in the wrong discussion.
- Making memcard async in a way that changes status-first behavior.
- Starving asset loads if priority rules do not include fairness.
@@ -1,126 +0,0 @@
---
id: PLN-0128
ticket: perf-async-background-work-lanes-for-assets-and-fs
title: Async Asset Pipeline Contract Tests and Telemetry
status: open
created: 2026-06-28
completed:
ref_decisions: [DEC-0034]
tags: [perf, asset, async, telemetry, tests, runtime]
---
# PLN-0128 - Async Asset Pipeline Contract Tests and Telemetry
## Briefing
`DEC-0034` requires observable progress, backlog state, superseding, and cheap
telemetry. This plan adds the validation and telemetry evidence needed to prove
the new async asset pipeline is correct.
## Decisions de Origem
- `DEC-0034` - Async Work Lane and Asset Backlog Contract.
## Alvo
Provide contract tests and telemetry for the async asset lane so future
implementations can be changed without regressing lane semantics.
## Escopo
Included:
- Contract tests for lane and asset backlog behavior.
- Progress reporting tests.
- Superseding and stale result discard tests.
- Telemetry counters and percentile updates.
- No-sleep deterministic test helpers where needed.
Fora de Escopo:
- Implementing public API wiring if `PLN-0126` has not run.
- Full benchmarking infrastructure.
- Host UI display of telemetry.
## Plano de Execucao
### Step 1 - Build Deterministic Test Hooks
**What:** Add test hooks for blocking a lane job at read/decode/stage.
**How:** Use channels/barriers or explicit fake job steps. Do not rely on
`thread::sleep` for correctness.
**Files:** async lane tests; asset test support modules.
### Step 2 - Test Backlog Ordering
**What:** Prove queued jobs run serially and in backlog order.
**How:** Submit multiple target slots and assert active job, pending positions,
promote, demote, and move behavior.
**Files:** asset manager tests and lane tests.
### Step 3 - Test Superseding
**What:** Prove newer request for the same `bank_type/slot` supersedes older
requests.
**How:** Cover queued superseding and active superseding. For active work, prove
stale completion cannot install.
**Files:** asset manager tests.
### Step 4 - Test Stable Handle Observability
**What:** Prove handles are queryable for empty, queued, active, ready,
committed, canceled, superseded, and error states.
**How:** Use `target_status` and handle status APIs to inspect both `slot_state`
and `request_state`.
**Files:** asset manager tests; VM dispatch tests if public API is available.
### Step 5 - Test Progress
**What:** Prove progress uses `0..10000` and phase boundaries.
**How:** Fake read/decode/stage phases with known completion points. Validate
non-linear phases do not report false internal progress.
**Files:** asset manager tests; telemetry tests.
### Step 6 - Add Telemetry
**What:** Add counters and percentile aggregation.
**How:** Update submitted/completed/failed/canceled/superseded counters when job
state closes. Update percentiles by `bank_type` and lightweight `asset_id`
window only at job completion.
**Files:** asset manager telemetry, async lane telemetry, existing runtime
telemetry types if shared.
## Criterios de Aceite
- [ ] Tests prove one active job at a time.
- [ ] Tests prove backlog order and reordering.
- [ ] Tests prove queued and active superseding.
- [ ] Tests prove stale active results are discarded.
- [ ] Tests prove handles remain queryable across all required states.
- [ ] Tests prove progress phase behavior.
- [ ] Telemetry is updated at job closure, not inside inner decode loops.
## Tests / Validacao
- Run targeted cargo tests for asset manager, async lane, and VM runtime
dispatch.
- Run existing asset-bank tests to prove current behavior remains compatible.
- Run `discussion validate` after plan state changes.
## Riscos
- Tests that depend on sleeps will be flaky.
- Telemetry may become too expensive if updated inside decode loops.
- Public API tests must wait for `PLN-0126` if syscall wiring is not present.
+17 -6
View File
@@ -239,8 +239,10 @@ The same physical surface may be reused by multiple visual owners, but logical
ownership MUST remain explicit.
Game pause/resume, foreground stack behavior, and coexistence of a paused Game
with VM-backed Shell apps are outside this contract and are tracked by the
foreground/lifecycle discussion.
with VM-backed Shell apps are defined by the foreground/lifecycle contract. The
render boundary's responsibility is narrower: foreground owner changes MUST
advance ownership, stale submissions MUST be discarded, and visual return to a
resumed Game MUST wait for a valid submission from the current ownership epoch.
### 4.7 Render telemetry
@@ -623,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
@@ -638,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
---
@@ -647,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
@@ -665,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
@@ -764,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`
@@ -772,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
@@ -795,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.
+18
View File
@@ -107,3 +107,21 @@ Input access is VM-owned and should not be reported as host syscall consumption.
All platforms must provide the mandatory input elements (`pad`, `touch`, `button`) to the runtime.
Platform differences in physical device mapping are resolved outside VM semantics.
## 9 Host/System Controls
Host/System controls are not part of the guest-visible input surface.
The Home/SystemOS request changes machine foreground authority. It must be
handled by the host, firmware, or SystemOS before input is exposed to the Game.
It must not be represented as `pad.start`, `pad.select`, a new pad field, a VM
intrinsic, or a userland syscall.
For the desktop host, `Esc` is the primary keyboard mapping for the
Home/SystemOS request. The physical `Home` key may be supported as an alias.
Both mappings are host controls and must not mutate `InputSignals`.
When a Game leaves or re-enters foreground, pending Game input must be cleared
or barriered so held or pressed input cannot leak across pause/resume
boundaries. This barrier applies to the Game-facing snapshot; it does not
change the meaning of host/system Home controls.
+109 -3
View File
@@ -100,7 +100,89 @@ Important properties:
- no execution occurs outside the frame loop;
- frame structure remains observable for host tooling and host-owned certification.
## 7 Render Worker Concurrency
## 7 Foreground Lifecycle Events
Foreground lifecycle events are system events with bounded delivery points.
They do not execute arbitrary guest callbacks at arrival time.
The Game pause path is:
```text
Home/SystemOS request
-> pause event becomes visible to the Game
-> bounded pause reaction budget
-> SystemOS suspension, even if the Game did not cooperate
```
The Game resume path is:
```text
SystemOS resume request
-> VM reactivation
-> resume or foreground-restore event becomes visible to the Game
-> Game may synchronize while still internally paused
-> visual foreground returns after a valid current-epoch render submission
```
`Paused` is the Game-visible event/state. `Suspended` is the OS-owned
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
contract.
## 8 VM Sessions and Execution Eligibility
Every VM-backed process MUST own a distinct VM session. A VM session owns the
mutable execution context for that process, including the VM instance,
per-session runtime counters, lifecycle delivery bookkeeping, debug/pause state,
and transient handles opened through VM-facing services.
Foreground ownership and execution eligibility are related but separate
concepts:
- foreground ownership selects the visual/navigation owner;
- execution eligibility selects which sessions may receive VM ticks;
- v1 grants normal VM execution only to the foreground VM-backed task, plus the
bounded Game pause handoff tick defined above;
- a suspended resident Game preserves its VM session but MUST NOT receive
normal gameplay ticks, normal Game input, or frame pacing;
- a VM-backed Shell owns its own VM session and MUST NOT overwrite or advance
the resident Game session while the Shell is foreground;
- a native Shell does not own a VM session.
The model is intentionally compatible with future background execution. Future
service or media processes may become execution-eligible without changing the
rule that mutable VM context belongs to the owning session. This chapter does
not grant any v1 background progress guarantee.
Durable app data remains keyed by `app_id` where the relevant storage contract
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
guest callbacks. It is an implementation-side consumer of closed render
@@ -127,7 +209,31 @@ Shutdown is explicit and bounded. A shutdown request wakes a waiting worker,
causes pending work that will not be consumed to be discarded, and reports a
typed failure if the worker cannot join within the configured timeout.
## 8 Determinism and Best Practices
## 10 Async Asset and IO Work Lane
The asset/IO async work lane is not a machine-visible event source and does not
introduce guest callbacks. It is an implementation-side lane for asset
IO/decode/materialization and compatible persistence IO work.
The lane is serial:
- it has at most one active job;
- it keeps an ordered backlog;
- it is separate from the render worker;
- it must not create one OS thread per guest-visible asset request.
Asset jobs are keyed by target `bank_type/slot`. A newer request for the same
target supersedes the older request. Superseding is an operational status and
does not execute guest code.
Asset install/commit into resident banks happens on the main runtime lane at
predictable ownership points. The async lane prepares materialized results; it
does not publish resident graphics/audio/scene state directly.
FS and game persistence services may consume this lane for IO-style work, but
public FS API shape is defined by the FS/app-home contract, not by this chapter.
## 11 Determinism and Best Practices
PROMETEU encourages:
@@ -142,7 +248,7 @@ PROMETEU discourages:
- hidden timing channels;
- ambiguous out-of-band execution.
## 9 Relationship to Other Specs
## 12 Relationship to Other Specs
- [`09a-coroutines-and-cooperative-scheduling.md`](09a-coroutines-and-cooperative-scheduling.md) defines coroutine lifecycle and scheduling behavior.
- [`10-debug-inspection-and-profiling.md`](10-debug-inspection-and-profiling.md) defines observability and diagnostics surfaces.
@@ -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
@@ -39,13 +39,32 @@ The VM does not own the machine lifecycle. Firmware does.
`Hub`, `Task(TaskId)`, and `Overlay`.
- **Shell task window**: a `WindowManager` window whose owner is
`WindowOwner::Task(TaskId)`.
- **Games root**: a host-provided local directory used by Hub/Home to discover
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
prepare for foreground loss.
- **Suspended**: an OS-owned scheduler/runtime state. A suspended Game remains
resident but does not receive normal gameplay ticks, normal Game input, or
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
POS is responsible for:
- deterministic reset into known machine state;
- VM initialization and teardown for cartridge execution;
- VM session creation, initialization, activation, and teardown for cartridge
execution;
- input latching and logical-frame budgeting;
- peripheral reset/orchestration;
- fault capture and crash-flow transition;
@@ -57,6 +76,10 @@ At the VM boundary, POS must preserve:
- `FRAME_SYNC` as the canonical frame boundary;
- deterministic transition from host tick to VM slice execution.
Firmware must not treat a single global VM object as the canonical execution
owner for all cartridges. The firmware state machine orchestrates macro-state;
POS/session services own VM-backed process context.
## 4 PrometeuHub Responsibilities
PrometeuHub is responsible for:
@@ -65,9 +88,22 @@ PrometeuHub is responsible for:
- reading cartridge metadata needed for launch decisions;
- deciding launch behavior based on `AppMode`;
- managing the system window surface for system-mode apps.
- 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.
For v1, the local games library is Game-only. Hub/Home must not expose Shell or
System cartridges from the games root. The internal library entry must retain
the loaded manifest data, `title`, `app_id`, `app_version`, the cartridge path,
and discovery metadata such as a timestamp or equivalent discovery marker.
The Home UI may display only `title`, `app_id`, and `app_version`. Path and
operational metadata may remain internal.
## 5 App Modes
### Game
@@ -139,22 +175,148 @@ Shell task loses its eligible focused window
-> FirmwareState::HubHome
```
## 7 Cartridge Load Flow
## 7 Foreground Stack and Game Pause
The v1 foreground contract is single-owner:
- exactly one foreground visual owner exists at a time;
- at most one Game may be resident;
- at most one Shell app may be foreground;
- Hub/Home is the root Shell owner and back-stack controller.
The minimal supported navigation cycle is:
```text
Game foreground
-> Home request
-> Game pause notification
-> Game suspended by SystemOS after a bounded budget
-> Hub/Home foreground
-> optional Shell foreground
-> Shell close returns to Hub/Home
-> same Game resume/foreground-restore notification
-> Game foreground after a valid current-epoch render submission
```
`Paused` is cooperative and visible to the Game. `Suspended` is imposed by
SystemOS. The Game may react to pause/resume, but it must not control whether
the OS suspends or resumes its VM.
When Home is requested during Game execution, SystemOS must notify the Game and
grant a short bounded pause budget. After the budget, SystemOS may suspend the
VM even if the Game did not cooperate. While suspended, the Game must not
receive normal gameplay ticks, normal Game input, or frame pacing.
When returning to the same Game, SystemOS must reactivate the VM and send a
resume or foreground-restore notification before visual foreground is restored.
The Game may remain internally paused while it synchronizes. Hub/Shell remains
visible until the resumed Game publishes a valid render submission for the
current ownership epoch.
Input pending for the Game must be cleared or barriered across pause/resume
boundaries. Game audio pauses with the Game VM in v1. Independent background
audio, real background execution, multiple resident Games, multiple foreground
Shells, and direct Game-to-Game switching are outside this contract.
The resident Game VM session remains allocated while Hub or Shell is foreground.
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:
1. POS receives a cartridge to load;
2. asset manager is initialized from the cartridge asset table, preload list, and packed asset bytes;
3. POS initializes the VM/runtime for the cartridge;
4. launch behavior branches by `AppMode`:
3. POS creates or selects the VM session for the cartridge;
4. POS initializes the session-owned VM/runtime for the cartridge;
5. launch behavior branches by `AppMode`:
- `Game` -> transition to the game-running firmware state;
- `System` -> create/focus a Hub window and return to the Hub state.
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 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`.
## 8 Firmware States
When Home launches a discovered Game entry, the request is a system-owned action
from PrometeuHub to POS/firmware. Firmware must load the selected cartridge
through the normal cartridge loader and transition to `LoadCartridge` on
success. This path must not use a guest syscall and must not reintroduce
userland `run_cart`.
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:
@@ -164,11 +326,12 @@ The current firmware state model includes:
- `HubHome`
- `LoadCartridge`
- `GameRunning`
- `ShellRunning`
- `AppCrashes`
These states express machine orchestration above the VM. They are not guest-visible bytecode states.
## 9 Execution Contract
## 10 Execution Contract
For game-mode execution, firmware/runtime coordination preserves:
@@ -179,7 +342,7 @@ For game-mode execution, firmware/runtime coordination preserves:
This keeps the machine model deterministic and observable.
## 10 Crash Handling
## 11 Crash Handling
Firmware owns terminal fault presentation.
@@ -191,7 +354,35 @@ When a terminal app fault occurs:
Crash handling is outside the guest VM execution model.
## 11 Relationship to Other Specs
## 12 Desktop Smoke Validation
The foreground contract can be smoke-tested on the desktop host with:
```text
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
```
Expected behavior:
- direct `--run` still boots the selected Game without using a guest cartridge
switching API;
- `--games-root` starts in Home and launches Games through the Home library;
- while a Game is running, `Esc` opens Home/SystemOS without entering the guest
pad input surface;
- the Game is paused, then suspended after the bounded SystemOS budget;
- Home remains foreground while the Game is resident;
- launching and closing a Shell app returns to Home without losing the resident
Game;
- a VM-backed Shell advances its own VM session and does not tick the suspended
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
- [`02-vm-instruction-set.md`](02-vm-instruction-set.md) defines the VM subsystem run by firmware.
- [`09-events-and-concurrency.md`](09-events-and-concurrency.md) defines the frame-boundary model used by firmware.
+28
View File
@@ -175,10 +175,38 @@ Runtime loading policy:
This is the working runtime/dev form used by the current loader.
Directory cartridges are also the only form discovered by the v1 local Home
games library. When a host provides `--games-root <dir>`, discovery scans only
immediate child directories under that root. Each child directory is a candidate
cartridge.
For the v1 Home games library:
- a candidate must have a valid `manifest.json`;
- 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.
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.
Packaged `.pmc` cartridges are not discovered by the v1 Home games library.
The cartridge spec therefore distinguishes:
- supported current load form;
+73 -1
View File
@@ -18,6 +18,9 @@ enum BootTarget {
This is a firmware/host orchestration contract, not a guest-visible ABI.
The local Home games library is not a separate firmware boot target. It is host
configuration consumed by the Hub profile after boot.
## 2 Boot Modes
### Hub
@@ -27,6 +30,10 @@ When the boot target is `Hub`:
- firmware boots into the Hub flow;
- no cartridge is auto-launched.
If the host also provides `--games-root <dir>`, the Hub may discover and render
valid Game cartridges from that root. Selecting one is a system-owned Home
action that requests cartridge loading after the Hub is already running.
### Cartridge
When the boot target is `Cartridge`:
@@ -43,6 +50,8 @@ For a cartridge boot target:
- `Game` cartridges transition into the game-running pipeline;
- `System` cartridges transition into a Runtime/Hub pipeline dedicated to
system UI and app hosting.
- VM-backed cartridges are initialized in a POS-owned VM session associated with
the created task/process.
This preserves the distinction between machine firmware state and app execution mode.
@@ -59,9 +68,53 @@ Typical host-facing boot intents are:
- default start -> enter Hub;
- run cartridge -> boot with cartridge target;
- debug cartridge -> boot with cartridge target plus debug mode parameters.
- games-root start -> enter Hub with a local Game library for Home.
The CLI is an entry surface for boot target selection; the firmware contract remains the same underneath.
Host CLI, debugger, and equivalent single-game launch flows are the supported
direct cartridge boot surfaces. Direct boot is not requested by guest bytecode
through a `system.run_cart` syscall or any other app-callable cartridge boot
ABI.
`--run <cart>` and `--debug <cart>` are direct cartridge boot profiles. They
select one cartridge before normal Hub/Home interaction and remain independent
from the local library.
`--games-root <dir>` is a Hub/Home library configuration. It does not
auto-launch a cartridge and does not create a guest-visible launch API.
The v1 games root contract is:
- the root contains directory cartridges as immediate child directories;
- recursive discovery is not performed;
- only valid cartridges whose manifest declares `app_mode: "Game"` are listed;
- Shell/System apps, packaged `.pmc` cartridges, remote catalogs, marketplace
metadata, search, icons, and rich presentation are outside this profile;
- invalid candidates are logged and omitted from the Home list;
- Home entries may display only `title`, `app_id`, and `app_version`;
- selecting a Home entry requests firmware/SystemOS loading for that cartridge
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 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
boot, or `--games-root` Home library startup semantics. Home/SystemOS requests
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
Boot target selection feeds into firmware states such as:
@@ -90,7 +143,26 @@ When booting a cartridge in debug mode:
Debug mode changes orchestration, not the cartridge contract.
## 7 Relationship to Other Specs
## 7 Smoke Validation
The local Home library path should be smoke tested in release mode for realistic
interactive speed:
```sh
cargo run --release -p prometeu-host-desktop-winit -- --games-root test-cartridges
```
Direct single-cartridge boot remains a separate validation path:
```sh
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.
- [`13-cartridge.md`](13-cartridge.md) defines cartridge structure.
+142 -6
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:
@@ -393,14 +407,129 @@ Fault boundary:
Rules:
- `handle` is valid only when `load` status is `OK`;
- `handle` is returned when `load` status is `OK`;
- `handle` represents a stable bank slot target, not a worker thread;
- a known handle remains queryable even when the slot is empty, has no active
request, or has a superseded request;
- failed `load` returns `handle = 0`;
- `commit` and `cancel` must not be silent no-op for unknown/invalid handle state.
- `asset.load` resolves the target bank type from `asset_table` using `asset_id`;
- public callers must not supply `asset_name` or `bank_type` to `asset.load`;
- slot validation and residency/lifecycle rejection remain in `asset` status space and are not delegated to `bank`.
### 11.2 Minimum status tables
### 11.2 Async work lane and backlog
Asset loading uses the runtime async work lane. This lane is separate from the
VM/main lane and separate from the render worker lane.
The asset async lane is serial:
- it executes at most one active asset job at a time;
- it keeps an ordered backlog of pending requests;
- it must not create one OS thread per `asset.load` request.
Asset requests are keyed by the target `bank_type/slot`.
Rules:
- each `bank_type/slot` has at most one current request;
- a newer request for the same `bank_type/slot` supersedes the previous request;
- if the previous request is queued, it is removed from the backlog;
- if the previous request is active, the lane should cancel cooperatively when
the current phase supports cheap cancellation;
- if active work cannot stop cheaply, it may finish, but the result must be
discarded when its generation no longer matches the target request generation;
- if the target already contains the requested `asset_id` as a valid resident
asset, `asset.load` returns a ready handle without adding a backlog entry.
The effective backlog size is bounded by the sum of targetable bank slots,
because only one current request can exist per `bank_type/slot`. The runtime
does not expose a guest-visible `queue_full` status for the normal asset
backlog path.
### 11.3 Handle state
An asset handle observes one stable bank slot target. Its observable state has
two parts:
```text
handle:
bank_type
slot
slot_state:
loaded_asset_id
resident_state
slot_generation
request_state:
requested_asset_id
request_generation
state
backlog_position
progress
```
`slot_state` describes what is currently resident in the target slot.
`request_state` describes the current or most recent request for that target.
Mutating operations such as commit, cancel, promote, demote, and move must act
on the current request generation. They must not accidentally mutate a newer
request through an older handle view.
### 11.4 Backlog inspection and ordering
The asset backlog surface may expose these status-first operations:
- `asset.backlog_info() -> (status, pending_count, active_handle, active_asset_id, active_bank_type, active_slot, active_progress)`
- `asset.backlog_position(handle) -> (status, state, position, progress)`
- `asset.backlog_move(handle, new_position) -> status`
- `asset.backlog_promote(handle) -> status`
- `asset.backlog_demote(handle) -> status`
- `asset.target_status(bank_type, slot) -> (status, asset_id, handle, state, position, progress)`
`asset.backlog_promote(handle)` is a shortcut for moving a queued request to
position `1`, the first pending position after the active job.
`asset.backlog_demote(handle)` is a shortcut for moving a queued request to the
end of the pending backlog.
### 11.5 Progress and telemetry
Asset progress uses integer progress, not floating point. The preferred scale is
`0..10000`.
The initial phase model is:
```text
queued -> 0
read -> 0..4000
decode -> 4000..9000
stage -> 9000..10000
ready -> 10000
```
If a phase cannot report internal progress, it keeps the previous progress mark
and advances at phase completion. The runtime must not invent false precision
for non-linear decode phases.
Minimum telemetry:
- current backlog depth;
- target/request position;
- active job progress;
- jobs submitted;
- jobs completed;
- jobs failed;
- jobs canceled;
- jobs superseded;
- job duration;
- percentiles by `bank_type`;
- lightweight percentiles or small-window samples by `asset_id`.
Percentiles are updated when a job closes, not inside the inner decode loop.
### 11.6 Minimum status tables
`asset.load` request statuses:
@@ -418,9 +547,16 @@ Rules:
- `4` = `CANCELED`
- `5` = `ERROR`
- `6` = `UNKNOWN_HANDLE`
- `7` = `QUEUED`
- `8` = `ACTIVE`
- `9` = `SUPERSEDED`
- `10` = `EMPTY`
- `11` = `INVALID`
- `12` = `BACKEND_UNAVAILABLE`
`asset.commit` and `asset.cancel` operation statuses:
- `0` = `OK`
- `1` = `UNKNOWN_HANDLE`
- `2` = `INVALID_STATE`
- `3` = `SUPERSEDED`
@@ -52,6 +52,11 @@ This identity is:
Input queries are VM-owned intrinsic calls in v1 and are outside the syscall identity space.
Cartridge boot is also outside the guest syscall identity space. A cartridge,
Shell app, or other userland guest must not declare or call `system.run_cart`.
Direct cartridge boot is a host/system boot-profile entrypoint, not an
app-callable syscall.
Syscall identity is transport, not the conceptual boundary for runtime
profiles. `Game` and `System` may both use syscall transport internally or at
their ABI edge, but that does not make their public authoring surfaces the same
@@ -60,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:
```
@@ -182,6 +193,11 @@ The game memcard profile uses module `mem` with status-first return shapes.
The `mem` module is a game profile surface. It is not the public storage model
for `System` profile apps.
Durable memcard data is keyed by `app_id` according to the save-memory
contract. Runtime handles, open file tables, pending lifecycle delivery, and
other mutable VM-facing syscall context are scoped to the owning VM session and
MUST NOT be used as durable app identity.
Canonical operations in v1 are:
- `mem.slot_count() -> (status, count)`
@@ -203,6 +219,12 @@ Canonical operations in v1 are:
- `asset.status(handle) -> status`
- `asset.commit(handle) -> status`
- `asset.cancel(handle) -> status`
- `asset.backlog_info() -> (status, pending_count, active_handle, active_asset_id, active_bank_type, active_slot, active_progress)`
- `asset.backlog_position(handle) -> (status, state, position, progress)`
- `asset.backlog_move(handle, new_position) -> status`
- `asset.backlog_promote(handle) -> status`
- `asset.backlog_demote(handle) -> status`
- `asset.target_status(bank_type, slot) -> (status, asset_id, handle, state, position, progress)`
For `asset.load`:
@@ -210,6 +232,18 @@ For `asset.load`:
- `slot` is the target slot index;
- bank kind is resolved from `asset_table` by `asset_id`, not supplied by the caller.
Asset handles represent stable bank slot targets. A handle can be queried even
when its slot has no resident asset or active request. Internally the handle
state separates resident `slot_state` from current `request_state`.
The asset backlog is keyed by `bank_type/slot`. New requests for the same target
supersede older requests for that target. `superseded` is an operational status,
not a structural trap.
`asset.backlog_promote(handle)` and `asset.backlog_demote(handle)` are
convenience operations over backlog movement. They do not introduce a second
ordering model.
### Bank diagnostics surface (`bank`, v1)
`DEC-0009` narrows the public bank contract:
@@ -44,6 +44,9 @@ Normal operational success and operational failure conditions should be represen
Examples:
- asset not yet loaded;
- asset request queued or active;
- asset request superseded by a newer request for the same bank slot;
- asset backend unavailable;
- audio voice unavailable;
- persistent storage full.
@@ -107,6 +110,11 @@ Game memcard operations (`mem.*`) are status-first and use `fs` capability in v1
`mem` remains layered on runtime `fs`; no parallel persistence channel is introduced.
Domain surface, status catalog and slot semantics are defined in [`08-save-memory-and-memcard.md`](08-save-memory-and-memcard.md).
Asset backlog operations are status-first. `queued`, `active`, `ready`,
`canceled`, `superseded`, `empty`, `invalid`, decode failure, and backend
unavailability are operational results. They must not be reclassified as `Trap`
unless the caller violates the structural ABI contract.
## 3 Interaction with the Garbage Collector
The VM heap and host-managed memory are separate.
+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.

Some files were not shown because too many files have changed in this diff Show More