From bb6f212779916e329d7789de3156850b6de9aa1b Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Wed, 14 Oct 2026 13:08:34 +0100 Subject: [PATCH] Share asset decoding validation and reject truncated payloads --- crates/console/prometeu-drivers/src/asset.rs | 252 ++-------- .../prometeu-drivers/src/asset/decode.rs | 187 ++++++++ .../src/asset/decode/tests.rs | 432 ++++++++++++++++++ .../prometeu-drivers/src/asset/resumable.rs | 177 +++---- .../src/services/memcard/transaction/tests.rs | 229 ++++++++++ ...al-async-lanes-bound-backlog-complexity.md | 29 ++ docs/specs/runtime/15-asset-management.md | 26 ++ 7 files changed, 1024 insertions(+), 308 deletions(-) create mode 100644 crates/console/prometeu-drivers/src/asset/decode.rs create mode 100644 crates/console/prometeu-drivers/src/asset/decode/tests.rs diff --git a/crates/console/prometeu-drivers/src/asset.rs b/crates/console/prometeu-drivers/src/asset.rs index c131731..0e8bc21 100644 --- a/crates/console/prometeu-drivers/src/asset.rs +++ b/crates/console/prometeu-drivers/src/asset.rs @@ -1,4 +1,5 @@ #![allow(clippy::collapsible_if)] +mod decode; mod resumable; use crate::memory_banks::{GlyphBankPoolInstaller, SceneBankPoolInstaller, SoundBankPoolInstaller}; use prometeu_hal::AssetBridge; @@ -634,62 +635,13 @@ impl AssetManager { fn decode_glyph_bank_layout( entry: &AssetEntry, ) -> Result<(TileSize, usize, usize, usize, usize, usize), String> { - let meta = entry.metadata_as_glyph_bank()?; - - let tile_size = match meta.tile_size { - 8 => TileSize::Size8, - 16 => TileSize::Size16, - 32 => TileSize::Size32, - _ => return Err(format!("Invalid tile_size: {}", meta.tile_size)), - }; - - let palette_count = meta.palette_count as usize; - if !(1..=GLYPH_BANK_MAX_PALETTE_COUNT_V1).contains(&palette_count) { - return Err(format!("Invalid palette_count: {}", meta.palette_count)); - } - - let width = meta.width as usize; - let height = meta.height as usize; - - let logical_pixels = width.checked_mul(height).ok_or("GlyphBank dimensions overflow")?; - let serialized_pixel_bytes = logical_pixels.div_ceil(2); - let palette_bytes = palette_count - .checked_mul(GLYPH_BANK_PALETTE_BYTES_PER_PALETTE) - .ok_or("GlyphBank palette size overflow")?; - let serialized_size = serialized_pixel_bytes - .checked_add(palette_bytes) - .ok_or("GlyphBank serialized size overflow")?; - let decoded_size = - logical_pixels.checked_add(palette_bytes).ok_or("GlyphBank decoded size overflow")?; - - if entry.size != serialized_size as u64 { - return Err(format!( - "Invalid GLYPHBANK serialized size: expected {}, got {}", - serialized_size, entry.size - )); - } - - if entry.decoded_size != decoded_size as u64 { - return Err(format!( - "Invalid GLYPHBANK decoded_size: expected {}, got {}", - decoded_size, entry.decoded_size - )); - } - - Ok((tile_size, width, height, serialized_pixel_bytes, palette_count, palette_bytes)) + decode::glyph_layout(entry) } fn unpack_glyph_bank_pixels(packed_pixels: &[u8], logical_pixels: usize) -> Vec { - let mut pixel_indices = Vec::with_capacity(logical_pixels); - for &packed in packed_pixels { - if pixel_indices.len() < logical_pixels { - pixel_indices.push(packed >> 4); - } - if pixel_indices.len() < logical_pixels { - pixel_indices.push(packed & 0x0f); - } - } - pixel_indices + let mut pixels = Vec::with_capacity(logical_pixels); + decode::append_pixels(&mut pixels, packed_pixels, logical_pixels); + pixels } fn op_mode_for(entry: &AssetEntry) -> Result { @@ -1260,17 +1212,7 @@ impl AssetManager { let palette_data = &buffer[packed_pixel_bytes..packed_pixel_bytes + palette_bytes]; let mut palettes = vec![[Color::BLACK; GLYPH_BANK_COLORS_PER_PALETTE]; palette_count]; - for (p, pal) in palettes.iter_mut().enumerate() { - for (c, slot) in pal.iter_mut().enumerate() { - let offset = (p * 16 + c) * 4; - *slot = Color::rgba( - palette_data[offset], - palette_data[offset + 1], - palette_data[offset + 2], - palette_data[offset + 3], - ); - } - } + decode::write_palettes(&mut palettes, 0, palette_data); Ok(GlyphBank { tile_size, width, height, pixel_indices, palettes }) } @@ -1295,17 +1237,7 @@ impl AssetManager { .map_err(|_| "Buffer too small for GLYPHBANK".to_string())?; let mut palettes = vec![[Color::BLACK; GLYPH_BANK_COLORS_PER_PALETTE]; palette_count]; - for (p, pal) in palettes.iter_mut().enumerate() { - for (c, slot) in pal.iter_mut().enumerate() { - let offset = (p * 16 + c) * 4; - *slot = Color::rgba( - palette_data[offset], - palette_data[offset + 1], - palette_data[offset + 2], - palette_data[offset + 3], - ); - } - } + decode::write_palettes(&mut palettes, 0, &palette_data); Ok(GlyphBank { tile_size, width, height, pixel_indices, palettes }) } @@ -1340,7 +1272,7 @@ impl AssetManager { entry: &AssetEntry, assets_data: Arc>, ) -> Result { - let _ = entry.metadata_as_scene_bank()?; + decode::scene_metadata(entry)?; let op_mode = Self::op_mode_for(entry)?; let slice = { let assets_data = assets_data.read().unwrap(); @@ -1367,152 +1299,25 @@ impl AssetManager { entry: &AssetEntry, buffer: &[u8], ) -> Result { - let _ = entry.metadata_as_scene_bank()?; - - if buffer.len() < SCENE_HEADER_BYTES_V1 { - return Err("Buffer too small for SCENE".to_string()); - } - - if buffer[0..4] != SCENE_PAYLOAD_MAGIC_V1 { - return Err("Invalid SCENE magic".to_string()); - } - - let version = u16::from_le_bytes([buffer[4], buffer[5]]); - if version != SCENE_PAYLOAD_VERSION_V1 { - return Err(format!("Unsupported SCENE version: {}", version)); - } - - let layer_count = u16::from_le_bytes([buffer[6], buffer[7]]) as usize; - if layer_count != SCENE_LAYER_COUNT_V1 { - return Err(format!("Invalid SCENE layer count: {}", layer_count)); - } - + decode::scene_metadata(entry)?; + decode::payload_size(entry, buffer.len())?; + decode::scene_header(buffer)?; let mut offset = SCENE_HEADER_BYTES_V1; - let mut decoded_size = 0_usize; - let layers = std::array::from_fn(|_| SceneLayer { - active: false, - glyph_asset_id: 0, - tile_size: TileSize::Size8, - parallax_factor: ParallaxFactor { x: 1.0, y: 1.0 }, - tilemap: TileMap { width: 0, height: 0, tiles: Vec::new() }, - }); - let mut layers = layers; - + let mut decoded = 0; + let mut layers = decode::empty_layers(); for layer in &mut layers { - let header_end = offset + let end = offset .checked_add(SCENE_LAYER_HEADER_BYTES_V1) - .ok_or("SCENE layer header offset overflow")?; - if header_end > buffer.len() { - return Err("Buffer too small for SCENE layer header".to_string()); - } - - let flags = buffer[offset]; - let glyph_asset_id = i32::from_le_bytes([ - buffer[offset + 1], - buffer[offset + 2], - buffer[offset + 3], - buffer[offset + 4], - ]); - let tile_size_raw = buffer[offset + 5]; - let tile_size = match tile_size_raw { - 8 => TileSize::Size8, - 16 => TileSize::Size16, - 32 => TileSize::Size32, - other => return Err(format!("Invalid SCENE tile size: {}", other)), - }; - let parallax_factor_x = f32::from_le_bytes([ - buffer[offset + 8], - buffer[offset + 9], - buffer[offset + 10], - buffer[offset + 11], - ]); - let parallax_factor_y = f32::from_le_bytes([ - buffer[offset + 12], - buffer[offset + 13], - buffer[offset + 14], - buffer[offset + 15], - ]); - if !parallax_factor_x.is_finite() || !parallax_factor_y.is_finite() { - return Err("Invalid SCENE parallax_factor".to_string()); - } - - let width = u32::from_le_bytes([ - buffer[offset + 16], - buffer[offset + 17], - buffer[offset + 18], - buffer[offset + 19], - ]) as usize; - let height = u32::from_le_bytes([ - buffer[offset + 20], - buffer[offset + 21], - buffer[offset + 22], - buffer[offset + 23], - ]) as usize; - let tile_count = u32::from_le_bytes([ - buffer[offset + 24], - buffer[offset + 25], - buffer[offset + 26], - buffer[offset + 27], - ]) as usize; - - let expected_tile_count = - width.checked_mul(height).ok_or("SCENE tile count overflow")?; - if tile_count != expected_tile_count { - return Err(format!( - "Invalid SCENE tile count for layer: expected {}, got {}", - expected_tile_count, tile_count - )); - } - - offset = header_end; - - let tile_bytes = tile_count - .checked_mul(SCENE_TILE_RECORD_BYTES_V1) - .ok_or("SCENE tile payload overflow")?; - let tiles_end = offset.checked_add(tile_bytes).ok_or("SCENE payload overflow")?; - if tiles_end > buffer.len() { - return Err("Buffer too small for SCENE tile data".to_string()); - } - - let mut tiles = Vec::with_capacity(tile_count); - for _ in 0..tile_count { - let tile_flags = buffer[offset]; - let palette_id = buffer[offset + 1]; - let glyph_id = u16::from_le_bytes([buffer[offset + 2], buffer[offset + 3]]); - tiles.push(Tile { - active: (tile_flags & 0b0000_0001) != 0, - glyph: Glyph { glyph_id, palette_id }, - flip_x: (tile_flags & 0b0000_0010) != 0, - flip_y: (tile_flags & 0b0000_0100) != 0, - }); - offset += SCENE_TILE_RECORD_BYTES_V1; - } - - decoded_size = decoded_size - .checked_add(SCENE_DECODED_LAYER_OVERHEAD_BYTES_V1) - .and_then(|size| size.checked_add(tile_count * size_of::())) - .ok_or("SCENE decoded_size overflow")?; - - *layer = SceneLayer { - active: (flags & 0b0000_0001) != 0, - glyph_asset_id, - tile_size, - parallax_factor: ParallaxFactor { x: parallax_factor_x, y: parallax_factor_y }, - tilemap: TileMap { width, height, tiles }, - }; + .ok_or("SCENE header offset overflow")?; + let header = + buffer.get(offset..end).ok_or("Buffer too small for SCENE layer header")?; + *layer = decode::scene_layer(header, end, entry.size, &mut decoded)?; + let tile_bytes = + layer.tilemap.width * layer.tilemap.height * SCENE_TILE_RECORD_BYTES_V1; + offset = end + tile_bytes; // checked by scene_layer before allocation + decode::append_tiles(&mut layer.tilemap.tiles, &buffer[end..offset]); } - - if offset != buffer.len() { - return Err("Trailing bytes in SCENE payload".to_string()); - } - - if entry.decoded_size != decoded_size as u64 { - return Err(format!( - "Invalid SCENE decoded_size: expected {}, got {}", - decoded_size, entry.decoded_size - )); - } - + decode::scene_finish(entry, offset, decoded)?; Ok(SceneBank { layers }) } @@ -1529,15 +1334,10 @@ impl AssetManager { entry: &AssetEntry, buffer: &[u8], ) -> Result { - let meta = entry.metadata_as_sound_bank()?; - let sample_rate = meta.sample_rate; - + let sample_rate = decode::sound_rate(entry)?; + decode::payload_size(entry, buffer.len())?; let mut data = Vec::with_capacity(buffer.len() / 2); - for i in (0..buffer.len()).step_by(2) { - if i + 1 < buffer.len() { - data.push(i16::from_le_bytes([buffer[i], buffer[i + 1]])); - } - } + decode::append_pcm(&mut data, buffer); let sample = Arc::new(Sample::new(sample_rate, data)); Ok(SoundBank::new(vec![sample])) diff --git a/crates/console/prometeu-drivers/src/asset/decode.rs b/crates/console/prometeu-drivers/src/asset/decode.rs new file mode 100644 index 0000000..dcc4397 --- /dev/null +++ b/crates/console/prometeu-drivers/src/asset/decode.rs @@ -0,0 +1,187 @@ +//! Format authority shared by complete-buffer and bounded resumable decoding. +use super::*; + +pub(super) fn glyph_layout( + entry: &AssetEntry, +) -> Result<(TileSize, usize, usize, usize, usize, usize), String> { + let meta = entry.metadata_as_glyph_bank()?; + + let tile_size = match meta.tile_size { + 8 => TileSize::Size8, + 16 => TileSize::Size16, + 32 => TileSize::Size32, + _ => return Err(format!("Invalid tile_size: {}", meta.tile_size)), + }; + + let palette_count = meta.palette_count as usize; + if !(1..=GLYPH_BANK_MAX_PALETTE_COUNT_V1).contains(&palette_count) { + return Err(format!("Invalid palette_count: {}", meta.palette_count)); + } + + let width = meta.width as usize; + let height = meta.height as usize; + + let logical_pixels = width.checked_mul(height).ok_or("GlyphBank dimensions overflow")?; + let serialized_pixel_bytes = logical_pixels.div_ceil(2); + let palette_bytes = palette_count + .checked_mul(GLYPH_BANK_PALETTE_BYTES_PER_PALETTE) + .ok_or("GlyphBank palette size overflow")?; + let serialized_size = serialized_pixel_bytes + .checked_add(palette_bytes) + .ok_or("GlyphBank serialized size overflow")?; + let decoded_size = + logical_pixels.checked_add(palette_bytes).ok_or("GlyphBank decoded size overflow")?; + + if entry.size != serialized_size as u64 { + return Err(format!( + "Invalid GLYPHBANK serialized size: expected {}, got {}", + serialized_size, entry.size + )); + } + + if entry.decoded_size != decoded_size as u64 { + return Err(format!( + "Invalid GLYPHBANK decoded_size: expected {}, got {}", + decoded_size, entry.decoded_size + )); + } + + Ok((tile_size, width, height, serialized_pixel_bytes, palette_count, palette_bytes)) +} + +pub(super) fn append_pixels(pixels: &mut Vec, bytes: &[u8], logical: usize) { + for &packed in bytes { + if pixels.len() < logical { + pixels.push(packed >> 4); + } + if pixels.len() < logical { + pixels.push(packed & 15); + } + } +} +pub(super) fn write_palettes( + palettes: &mut [[Color; GLYPH_BANK_COLORS_PER_PALETTE]], + position: usize, + bytes: &[u8], +) { + for (i, rgba) in bytes.as_chunks::<4>().0.iter().enumerate() { + let at = position / 4 + i; + palettes[at / 16][at % 16] = Color::rgba(rgba[0], rgba[1], rgba[2], rgba[3]); + } +} +pub(super) fn sound_rate(entry: &AssetEntry) -> Result { + Ok(entry.metadata_as_sound_bank()?.sample_rate) +} +// Callers split on even chunk boundaries. Only the final odd byte is ignored. +pub(super) fn append_pcm(data: &mut Vec, bytes: &[u8]) { + data.extend(bytes.as_chunks::<2>().0.iter().map(|p| i16::from_le_bytes(*p))); +} +pub(super) fn payload_size(entry: &AssetEntry, actual: usize) -> Result<(), String> { + if actual as u64 != entry.size { + return Err("Invalid asset payload size".into()); + } + Ok(()) +} +pub(super) fn scene_metadata(entry: &AssetEntry) -> Result<(), String> { + entry.metadata_as_scene_bank().map(|_| ()) +} +pub(super) fn empty_layers() -> [SceneLayer; SCENE_LAYER_COUNT_V1] { + std::array::from_fn(|_| SceneLayer { + active: false, + glyph_asset_id: 0, + tile_size: TileSize::Size8, + parallax_factor: ParallaxFactor { x: 1.0, y: 1.0 }, + tilemap: TileMap { width: 0, height: 0, tiles: Vec::new() }, + }) +} +pub(super) fn scene_header(bytes: &[u8]) -> Result<(), String> { + if bytes.len() < SCENE_HEADER_BYTES_V1 { + return Err("Buffer too small for SCENE".into()); + } + if bytes[..4] != SCENE_PAYLOAD_MAGIC_V1 { + return Err("Invalid SCENE magic".into()); + } + let version = u16::from_le_bytes([bytes[4], bytes[5]]); + if version != SCENE_PAYLOAD_VERSION_V1 { + return Err(format!("Unsupported SCENE version: {version}")); + } + let count = u16::from_le_bytes([bytes[6], bytes[7]]) as usize; + if count != SCENE_LAYER_COUNT_V1 { + return Err(format!("Invalid SCENE layer count: {count}")); + } + Ok(()) +} +pub(super) fn scene_layer( + bytes: &[u8], + position: usize, + payload_len: u64, + decoded: &mut usize, +) -> Result { + if bytes.len() < SCENE_LAYER_HEADER_BYTES_V1 { + return Err("Buffer too small for SCENE layer header".into()); + } + let u32at = |at| u32::from_le_bytes(bytes[at..at + 4].try_into().unwrap()); + let tile_size = match bytes[5] { + 8 => TileSize::Size8, + 16 => TileSize::Size16, + 32 => TileSize::Size32, + other => return Err(format!("Invalid SCENE tile size: {other}")), + }; + let x = f32::from_le_bytes(bytes[8..12].try_into().unwrap()); + let y = f32::from_le_bytes(bytes[12..16].try_into().unwrap()); + if !x.is_finite() || !y.is_finite() { + return Err("Invalid SCENE parallax_factor".into()); + } + let width = u32at(16) as usize; + let height = u32at(20) as usize; + let count = u32at(24) as usize; + let expected = width.checked_mul(height).ok_or("SCENE tile count overflow")?; + if count != expected { + return Err(format!( + "Invalid SCENE tile count for layer: expected {expected}, got {count}" + )); + } + let end = count + .checked_mul(SCENE_TILE_RECORD_BYTES_V1) + .and_then(|n| position.checked_add(n)) + .ok_or("SCENE payload overflow")?; + if end as u64 > payload_len { + return Err("Buffer too small for SCENE tile data".into()); + } + *decoded = decoded + .checked_add(SCENE_DECODED_LAYER_OVERHEAD_BYTES_V1) + .and_then(|n| count.checked_mul(size_of::()).and_then(|b| n.checked_add(b))) + .ok_or("SCENE decoded_size overflow")?; + Ok(SceneLayer { + active: bytes[0] & 1 != 0, + glyph_asset_id: i32::from_le_bytes(bytes[1..5].try_into().unwrap()), + tile_size, + parallax_factor: ParallaxFactor { x, y }, + tilemap: TileMap { width, height, tiles: Vec::with_capacity(count) }, + }) +} +pub(super) fn append_tiles(tiles: &mut Vec, bytes: &[u8]) { + tiles.extend(bytes.as_chunks::().0.iter().map(|b| Tile { + active: b[0] & 1 != 0, + glyph: Glyph { glyph_id: u16::from_le_bytes([b[2], b[3]]), palette_id: b[1] }, + flip_x: b[0] & 2 != 0, + flip_y: b[0] & 4 != 0, + })); +} +pub(super) fn scene_finish( + entry: &AssetEntry, + position: usize, + decoded: usize, +) -> Result<(), String> { + payload_size(entry, position)?; + if decoded as u64 != entry.decoded_size { + return Err(format!( + "Invalid SCENE decoded_size: expected {decoded}, got {}", + entry.decoded_size + )); + } + Ok(()) +} + +#[cfg(test)] +pub(super) mod tests; diff --git a/crates/console/prometeu-drivers/src/asset/decode/tests.rs b/crates/console/prometeu-drivers/src/asset/decode/tests.rs new file mode 100644 index 0000000..8c21f7f --- /dev/null +++ b/crates/console/prometeu-drivers/src/asset/decode/tests.rs @@ -0,0 +1,432 @@ +use super::*; +use serde_json::{Value, json}; + +struct FileFixture(std::path::PathBuf); +impl FileFixture { + fn new(name: &str, bytes: &[u8]) -> Self { + let path = std::env::temp_dir() + .join(format!("prometeu-conformance-{}-{name}", std::process::id())); + std::fs::write(&path, bytes).unwrap(); + Self(path) + } + fn source(&self, declared_len: u64) -> Arc> { + Arc::new(RwLock::new(AssetsPayloadSource::from_file(self.0.clone(), 0, declared_len))) + } +} +impl Drop for FileFixture { + fn drop(&mut self) { + std::fs::remove_file(&self.0).unwrap(); + } +} +fn pcm_entry(size: u64) -> AssetEntry { + AssetEntry { + asset_id: 1, + asset_name: "pcm".into(), + bank_type: BankType::SOUNDS, + offset: 0, + size, + decoded_size: size, + codec: AssetCodec::None, + metadata: json!({"sample_rate": 44100, "channels": 1}), + } +} + +#[test] +fn pcm_chunk_edges_and_odd_tails_have_explicit_baseline_outputs() { + for len in [0, 1, 2, 3, 4095, 4096, 4097, 8191, 8192, 8193] { + let bytes: Vec = (0..len).map(|i| if i % 2 == 0 { 0x34 } else { 0x12 }).collect(); + let entry = pcm_entry(len as u64); + let expected = json!([[vec![0x1234_i16; len / 2], 44100, null, null]]); + let buffer = AssetManager::decode_sound_bank_from_buffer(&entry, &bytes).unwrap(); + let reader = AssetManager::decode_sound_bank_from_reader(&entry, &mut &bytes[..]).unwrap(); + let source = Arc::new(RwLock::new(AssetsPayloadSource::from_bytes(bytes))); + let production = AssetManager::perform_load_sound_bank(&entry, source.clone()).unwrap(); + assert_eq!(sound_snapshot(&buffer), expected, "buffer len={len}"); + assert_eq!(sound_snapshot(&reader), expected, "reader len={len}"); + assert_eq!(sound_snapshot(&production), expected, "legacy load len={len}"); + assert_eq!( + resumable::conformance_result(&entry, &source).unwrap(), + expected, + "resumable len={len}" + ); + } +} + +#[test] +fn physically_truncated_pcm_file_is_rejected_by_both_modes() { + // Two actual bytes, three declared bytes: the missing byte is an odd tail. + // The approved rule rejects missing declared bytes, including an odd tail. + let fixture = FileFixture::new("truncated-pcm", &[0x34, 0x12]); + let entry = pcm_entry(3); + let source = fixture.source(3); + assert!(AssetManager::perform_load_sound_bank(&entry, source.clone()).is_err()); + assert!(resumable::conformance_result(&entry, &source).is_err()); + // With the declared byte physically present, both accept and ignore it. + std::fs::write(&fixture.0, [0x34, 0x12, 0xff]).unwrap(); + let expected = json!([[[0x1234], 44100, null, null]]); + assert_eq!(resumable::conformance_result(&entry, &source).unwrap(), expected); + assert_eq!( + sound_snapshot(&AssetManager::perform_load_sound_bank(&entry, source.clone()).unwrap()), + expected + ); + // Memory carriers reject the range before either decoder can accept it. + let memory = Arc::new(RwLock::new(AssetsPayloadSource::from_bytes(vec![0x34, 0x12]))); + assert!(AssetManager::perform_load_sound_bank(&entry, memory.clone()).is_err()); + assert!(resumable::conformance_result(&entry, &memory).is_err()); +} + +#[test] +fn physically_short_scene_file_is_rejected_by_both_modes() { + // Minimal scene: four empty layers, 12-byte header + 4 * 32-byte headers. + let mut bytes = vec![0_u8; 140]; + bytes[..8].copy_from_slice(&[b'S', b'C', b'N', b'E', 1, 0, 4, 0]); + for start in [12, 44, 76, 108] { + bytes[start + 5] = 8; + } + let fixture = FileFixture::new("short-scene", &bytes); + let mut entry = AssetEntry { + asset_id: 2, + asset_name: "scene".into(), + bank_type: BankType::SCENE, + offset: 0, + size: 141, + decoded_size: 64, + codec: AssetCodec::None, + metadata: json!({}), + }; + let expected = json!(vec![json!([false, 0, 8, 0.0, 0.0, 0, 0, []]); 4]); + let source = fixture.source(141); + assert!(AssetManager::perform_load_scene_bank(&entry, source.clone()).is_err()); + assert!(resumable::conformance_result(&entry, &source).is_err()); + // Exact physical/declared size is accepted by both. + entry.size = 140; + assert_eq!(resumable::conformance_result(&entry, &source).unwrap(), expected); + assert_eq!( + scene_snapshot(&AssetManager::perform_load_scene_bank(&entry, source.clone()).unwrap()), + expected + ); + // An actual trailing byte is rejected by both. + entry.size = 141; + bytes.push(0); + std::fs::write(&fixture.0, bytes).unwrap(); + assert!(AssetManager::perform_load_scene_bank(&entry, source.clone()).is_err()); + assert!(resumable::conformance_result(&entry, &source).is_err()); +} + +// Every mode sees the same declared slice, just as it does in production. +fn check_case(name: &str, entry: &AssetEntry, bytes: Vec, expected: Option) { + let source = Arc::new(RwLock::new(AssetsPayloadSource::from_bytes(bytes))); + for mode in 0..4 { + let result = (|| -> Result { + if mode == 3 { + return resumable::conformance_result(entry, &source); + } + if mode == 2 { + return match entry.bank_type { + BankType::GLYPH => AssetManager::perform_load_glyph_bank(entry, source.clone()) + .map(|b| glyph_snapshot(&b)), + BankType::SOUNDS => { + AssetManager::perform_load_sound_bank(entry, source.clone()) + .map(|b| sound_snapshot(&b)) + } + BankType::SCENE => AssetManager::perform_load_scene_bank(entry, source.clone()) + .map(|b| scene_snapshot(&b)), + }; + } + let slice = source + .read() + .unwrap() + .open_slice(entry.offset, entry.size) + .map_err(|e| e.to_string())?; + let bytes = slice.read_all().map_err(|e| e.to_string())?; + let mut reader = &bytes[..]; + match (entry.bank_type, mode) { + (BankType::GLYPH, 0) => AssetManager::decode_glyph_bank_from_buffer(entry, &bytes) + .map(|b| glyph_snapshot(&b)), + (BankType::GLYPH, _) => { + AssetManager::decode_glyph_bank_from_reader(entry, &mut reader) + .map(|b| glyph_snapshot(&b)) + } + (BankType::SOUNDS, 0) => AssetManager::decode_sound_bank_from_buffer(entry, &bytes) + .map(|b| sound_snapshot(&b)), + (BankType::SOUNDS, _) => { + AssetManager::decode_sound_bank_from_reader(entry, &mut reader) + .map(|b| sound_snapshot(&b)) + } + (BankType::SCENE, 0) => AssetManager::decode_scene_bank_from_buffer(entry, &bytes) + .map(|b| scene_snapshot(&b)), + (BankType::SCENE, _) => { + AssetManager::decode_scene_bank_from_reader(entry, &mut reader) + .map(|b| scene_snapshot(&b)) + } + } + })(); + assert_eq!(result.ok(), expected, "{name}, mode={mode}"); + } +} + +#[test] +fn glyph_layout_palette_nibbles_and_chunk_boundaries() { + for pixels in [0_usize, 1, 2, 8191, 8192, 8193, 16385] { + for palettes in [1, 3, 64] { + let mut bytes = vec![0x12; pixels.div_ceil(2)]; + bytes.extend(std::iter::repeat_n([0x12, 0x34, 0x56, 0x78], palettes * 16).flatten()); + let entry = AssetEntry { + asset_id: 1, + asset_name: "glyph".into(), + bank_type: BankType::GLYPH, + offset: 0, + size: bytes.len() as u64, + decoded_size: (pixels + palettes * 64) as u64, + codec: AssetCodec::None, + metadata: json!({"tile_size":16,"width":pixels,"height":1,"palette_count":palettes,"palette_authored":palettes}), + }; + let expected = json!([ + 16, + pixels, + 1, + (0..pixels).map(|i| 1 + i % 2).collect::>(), + vec![vec![0x12345678_u32; 16]; palettes] + ]); + check_case("glyph-valid", &entry, bytes.clone(), Some(expected)); + for (key, value) in [ + ("tile_size", json!(7)), + ("palette_count", json!(0)), + ("palette_count", json!(65)), + ("width", json!(-1)), + ("height", json!("bad")), + ] { + let mut invalid = entry.clone(); + invalid.metadata[key] = value; + check_case(key, &invalid, bytes.clone(), None); + } + let mut invalid = entry.clone(); + invalid.decoded_size += 1; + check_case("glyph-decoded-size", &invalid, bytes.clone(), None); + let mut invalid = entry.clone(); + invalid.size += 1; + let mut extra = bytes.clone(); + extra.push(0); + check_case("glyph-trailing", &invalid, extra, None); + bytes.pop(); + check_case("glyph-truncated", &entry, bytes, None); + } + } +} + +fn empty_scene() -> (AssetEntry, Vec, Value) { + let mut bytes = vec![0_u8; 140]; + bytes[..8].copy_from_slice(&[b'S', b'C', b'N', b'E', 1, 0, 4, 0]); + for start in [12, 44, 76, 108] { + bytes[start + 5] = 8; + } + let entry = AssetEntry { + asset_id: 2, + asset_name: "scene".into(), + bank_type: BankType::SCENE, + offset: 0, + size: 140, + decoded_size: 64, + codec: AssetCodec::None, + metadata: json!({}), + }; + (entry, bytes, json!(vec![json!([false, 0, 8, 0.0, 0.0, 0, 0, []]); 4])) +} + +#[test] +fn scene_header_ranges_nonfinite_and_truncation_corpus() { + let (entry, bytes, expected) = empty_scene(); + check_case("empty-scene", &entry, bytes.clone(), Some(expected)); + for end in 0..bytes.len() { + let mut e = entry.clone(); + e.size = end as u64; + check_case("scene-every-truncation", &e, bytes[..end].to_vec(), None); + } + for (offset, value) in [(0, 0xff), (4, 2), (6, 3), (17, 7), (36, 1)] { + let mut invalid = bytes.clone(); + invalid[offset] = value; + check_case("scene-invalid-header-field", &entry, invalid, None); + } + for offset in [20, 24] { + for value in [f32::NAN, f32::INFINITY, f32::NEG_INFINITY] { + let mut invalid = bytes.clone(); + invalid[offset..offset + 4].copy_from_slice(&value.to_le_bytes()); + check_case("scene-nonfinite", &entry, invalid, None); + } + } + let mut invalid = bytes.clone(); + for offset in [28, 32, 36] { + invalid[offset..offset + 4].copy_from_slice(&u32::MAX.to_le_bytes()); + } + check_case("scene-dimensions-overflow-or-count-mismatch", &entry, invalid, None); + let mut invalid = bytes.clone(); + for offset in [28, 32, 36] { + invalid[offset..offset + 4].copy_from_slice(&1_u32.to_le_bytes()); + } + // Four layer headers no longer fit after the declared tile consumes bytes. + check_case("scene-tile-range", &entry, invalid, None); + let mut sequence_metadata = entry.clone(); + sequence_metadata.metadata = json!([]); + check_case( + "scene-empty-sequence-metadata", + &sequence_metadata, + bytes.clone(), + Some(empty_scene().2), + ); + let mut e = entry.clone(); + e.decoded_size += 1; + check_case("scene-decoded-size", &e, bytes.clone(), None); + e = entry.clone(); + e.size += 1; + let mut trailing = bytes.clone(); + trailing.push(0); + check_case("scene-trailing", &e, trailing, None); + for metadata in [json!(null), json!("bad")] { + e = entry.clone(); + e.metadata = metadata; + check_case("scene-metadata", &e, bytes.clone(), None); + } +} + +#[test] +fn scene_tile_chunk_edges_flags_and_reserved_bytes() { + for count in [1_usize, 1023, 1024, 1025, 2049] { + let (mut entry, mut bytes, mut expected) = empty_scene(); + bytes[12] = 0xff; // Only the active flag is meaningful. + bytes[13..17].copy_from_slice(&(-7_i32).to_le_bytes()); + bytes[17] = 32; + bytes[18..20].copy_from_slice(&[0xff; 2]); // Reserved fields are ignored. + bytes[20..24].copy_from_slice(&(-0.5_f32).to_le_bytes()); + bytes[24..28].copy_from_slice(&2.0_f32.to_le_bytes()); + bytes[28..32].copy_from_slice(&(count as u32).to_le_bytes()); + bytes[32..36].copy_from_slice(&1_u32.to_le_bytes()); + bytes[36..40].copy_from_slice(&(count as u32).to_le_bytes()); + bytes.splice(44..44, std::iter::repeat_n([0xff, 255, 0x34, 0x12], count).flatten()); + entry.size = bytes.len() as u64; + entry.decoded_size += (count * size_of::()) as u64; + expected[0] = json!([ + true, + -7, + 32, + -0.5, + 2.0, + count, + 1, + vec![(true, 0x1234, 255, true, true); count] + ]); + check_case("scene-chunks", &entry, bytes, Some(expected)); + } +} + +#[test] +fn pcm_metadata_and_source_range_corpus() { + for metadata in [ + json!(null), + json!({}), + json!({"sample_rate":-1,"channels":1}), + json!({"sample_rate":44100,"channels":"bad"}), + ] { + let mut e = pcm_entry(2); + e.metadata = metadata; + check_case("pcm-metadata", &e, vec![0x34, 0x12], None); + } + // These fields are currently descriptive, not extra PCM layout constraints. + let mut e = pcm_entry(2); + e.metadata = json!({"sample_rate":0,"channels":0}); + e.decoded_size = 999; + check_case( + "pcm-permissive-metadata", + &e, + vec![0x34, 0x12], + Some(json!([[[0x1234], 0, null, null]])), + ); + for offset in [1, u64::MAX] { + let mut e = pcm_entry(2); + e.offset = offset; + check_case("source-range", &e, vec![0x34, 0x12], None); + } + let mut e = pcm_entry(2); + e.size = u64::MAX; + check_case("source-size-overflow", &e, vec![0x34, 0x12], None); +} + +pub(in crate::asset) fn glyph_snapshot(bank: &GlyphBank) -> Value { + json!([ + bank.tile_size as u8, + bank.width, + bank.height, + bank.pixel_indices, + bank.palettes + .iter() + .map(|p| p.iter().map(|c| c.raw()).collect::>()) + .collect::>() + ]) +} +pub(in crate::asset) fn sound_snapshot(bank: &SoundBank) -> Value { + json!( + bank.samples + .iter() + .map(|s| (&s.data, s.sample_rate, s.loop_start, s.loop_end)) + .collect::>() + ) +} +pub(in crate::asset) fn scene_snapshot(bank: &SceneBank) -> Value { + json!( + bank.layers + .iter() + .map(|l| json!([ + l.active, + l.glyph_asset_id, + l.tile_size as u8, + l.parallax_factor.x, + l.parallax_factor.y, + l.tilemap.width, + l.tilemap.height, + l.tilemap + .tiles + .iter() + .map(|t| (t.active, t.glyph.glyph_id, t.glyph.palette_id, t.flip_x, t.flip_y)) + .collect::>() + ])) + .collect::>() + ) +} + +#[test] +fn shared_scene_arithmetic_rejects_overflow_before_allocating() { + let (_, bytes, _) = empty_scene(); + let mut header = bytes[12..44].to_vec(); + header[16..20].copy_from_slice(&1_u32.to_le_bytes()); + header[20..24].copy_from_slice(&1_u32.to_le_bytes()); + header[24..28].copy_from_slice(&1_u32.to_le_bytes()); + assert!(scene_layer(&header, usize::MAX, u64::MAX, &mut 0).is_err()); + let mut decoded = usize::MAX; + assert!(scene_layer(&header, 44, 48, &mut decoded).is_err()); + assert!(scene_layer(&header, 44, 47, &mut 0).is_err()); + assert!(scene_layer(&header[..31], 44, 48, &mut 0).is_err()); +} + +#[test] +fn physically_truncated_glyph_palette_is_rejected_by_both_modes() { + let fixture = FileFixture::new("truncated-glyph", &[0; 63]); + let entry = AssetEntry { + asset_id: 3, + asset_name: "empty-glyph".into(), + bank_type: BankType::GLYPH, + offset: 0, + size: 64, + decoded_size: 64, + codec: AssetCodec::None, + metadata: json!({"tile_size":8,"width":0,"height":0,"palette_count":1,"palette_authored":1}), + }; + let source = fixture.source(64); + assert!(AssetManager::perform_load_glyph_bank(&entry, source.clone()).is_err()); + assert!(resumable::conformance_result(&entry, &source).is_err()); + std::fs::write(&fixture.0, [0; 64]).unwrap(); + let expected = json!([8, 0, 0, [], vec![vec![0; 16]]]); + assert_eq!( + glyph_snapshot(&AssetManager::perform_load_glyph_bank(&entry, source.clone()).unwrap()), + expected + ); + assert_eq!(resumable::conformance_result(&entry, &source).unwrap(), expected); +} diff --git a/crates/console/prometeu-drivers/src/asset/resumable.rs b/crates/console/prometeu-drivers/src/asset/resumable.rs index e063d60..11be923 100644 --- a/crates/console/prometeu-drivers/src/asset/resumable.rs +++ b/crates/console/prometeu-drivers/src/asset/resumable.rs @@ -246,7 +246,7 @@ impl Decoder { } } BankType::SOUNDS => { - let sample_rate = entry.metadata_as_sound_bank()?.sample_rate; + let sample_rate = decode::sound_rate(entry)?; State::Sound { sample_rate, data: Vec::with_capacity(entry.size as usize / 2), @@ -254,15 +254,9 @@ impl Decoder { } } BankType::SCENE => { - entry.metadata_as_scene_bank()?; + decode::scene_metadata(entry)?; State::Scene { - layers: std::array::from_fn(|_| SceneLayer { - active: false, - glyph_asset_id: 0, - tile_size: TileSize::Size8, - parallax_factor: ParallaxFactor { x: 1.0, y: 1.0 }, - tilemap: TileMap { width: 0, height: 0, tiles: Vec::new() }, - }), + layers: decode::empty_layers(), layer: 0, tiles_left: 0, header: false, @@ -279,25 +273,18 @@ impl Decoder { if *position < *packed { let n = (*packed - *position).min(bytes.len()); self.reader.read_exact(&mut bytes[..n]).map_err(|e| e.to_string())?; - for &v in &bytes[..n] { - if bank.pixel_indices.len() < bank.width * bank.height { - bank.pixel_indices.push(v >> 4) - } - if bank.pixel_indices.len() < bank.width * bank.height { - bank.pixel_indices.push(v & 15) - } - } + decode::append_pixels( + &mut bank.pixel_indices, + &bytes[..n], + bank.width * bank.height, + ); *position += n; return Ok(None); } if *palette_position < *palette_bytes { let n = (*palette_bytes - *palette_position).min(bytes.len()); self.reader.read_exact(&mut bytes[..n]).map_err(|e| e.to_string())?; - for (i, rgba) in bytes[..n].as_chunks::<4>().0.iter().enumerate() { - let at = *palette_position / 4 + i; - bank.palettes[at / 16][at % 16] = - Color::rgba(rgba[0], rgba[1], rgba[2], rgba[3]); - } + decode::write_palettes(&mut bank.palettes, *palette_position, &bytes[..n]); *palette_position += n; return Ok(None); } @@ -311,9 +298,7 @@ impl Decoder { if *remaining > 0 { let n = (*remaining).min(bytes.len()); self.reader.read_exact(&mut bytes[..n]).map_err(|e| e.to_string())?; - for pair in bytes[..n].as_chunks::<2>().0 { - data.push(i16::from_le_bytes([pair[0], pair[1]])); - } + decode::append_pcm(data, &bytes[..n]); *remaining -= n; return Ok(None); } @@ -327,12 +312,7 @@ impl Decoder { self.reader .read_exact(&mut bytes[..SCENE_HEADER_BYTES_V1]) .map_err(|e| e.to_string())?; - if bytes[..4] != SCENE_PAYLOAD_MAGIC_V1 - || u16::from_le_bytes([bytes[4], bytes[5]]) != SCENE_PAYLOAD_VERSION_V1 - || u16::from_le_bytes([bytes[6], bytes[7]]) as usize != SCENE_LAYER_COUNT_V1 - { - return Err("Invalid scene header".into()); - } + decode::scene_header(&bytes[..SCENE_HEADER_BYTES_V1])?; self.position += SCENE_HEADER_BYTES_V1; *header = true; return Ok(None); @@ -341,17 +321,7 @@ impl Decoder { let n = (*tiles_left).min(bytes.len() / SCENE_TILE_RECORD_BYTES_V1); let count = n * SCENE_TILE_RECORD_BYTES_V1; self.reader.read_exact(&mut bytes[..count]).map_err(|e| e.to_string())?; - for b in bytes[..count].as_chunks::().0 { - layers[*layer - 1].tilemap.tiles.push(Tile { - active: b[0] & 1 != 0, - glyph: Glyph { - glyph_id: u16::from_le_bytes([b[2], b[3]]), - palette_id: b[1], - }, - flip_x: b[0] & 2 != 0, - flip_y: b[0] & 4 != 0, - }); - } + decode::append_tiles(&mut layers[*layer - 1].tilemap.tiles, &bytes[..count]); *tiles_left -= n; self.position += count; return Ok(None); @@ -361,50 +331,18 @@ impl Decoder { .read_exact(&mut bytes[..SCENE_LAYER_HEADER_BYTES_V1]) .map_err(|e| e.to_string())?; self.position += SCENE_LAYER_HEADER_BYTES_V1; - let u32at = |at| u32::from_le_bytes(bytes[at..at + 4].try_into().unwrap()); - let width = u32at(16) as usize; - let height = u32at(20) as usize; - let count = u32at(24) as usize; - let tile_size = match bytes[5] { - 8 => TileSize::Size8, - 16 => TileSize::Size16, - 32 => TileSize::Size32, - _ => return Err("Invalid scene tile size".into()), - }; - let x = f32::from_le_bytes(bytes[8..12].try_into().unwrap()); - let y = f32::from_le_bytes(bytes[12..16].try_into().unwrap()); - if !x.is_finite() - || !y.is_finite() - || width.checked_mul(height) != Some(count) - || count - .checked_mul(SCENE_TILE_RECORD_BYTES_V1) - .and_then(|n| n.checked_add(self.position)) - .is_none_or(|n| n as u64 > self.entry.size) - { - return Err("Invalid scene layer range".into()); - } - *decoded = decoded - .checked_add(SCENE_DECODED_LAYER_OVERHEAD_BYTES_V1) - .and_then(|n| { - count.checked_mul(size_of::()).and_then(|b| n.checked_add(b)) - }) - .ok_or("Scene size overflow")?; - layers[*layer] = SceneLayer { - active: bytes[0] & 1 != 0, - glyph_asset_id: i32::from_le_bytes(bytes[1..5].try_into().unwrap()), - tile_size, - parallax_factor: ParallaxFactor { x, y }, - tilemap: TileMap { width, height, tiles: Vec::with_capacity(count) }, - }; + layers[*layer] = decode::scene_layer( + &bytes[..SCENE_LAYER_HEADER_BYTES_V1], + self.position, + self.entry.size, + decoded, + )?; + let count = layers[*layer].tilemap.width * layers[*layer].tilemap.height; *layer += 1; *tiles_left = count; return Ok(None); } - if self.position as u64 != self.entry.size - || *decoded as u64 != self.entry.decoded_size - { - return Err("Invalid scene payload size".into()); - } + decode::scene_finish(&self.entry, self.position, *decoded)?; let State::Scene { layers, .. } = std::mem::replace(&mut self.state, State::Done) else { unreachable!() @@ -416,6 +354,30 @@ impl Decoder { } } +// Test-only access to the production state machine; no alternate decode rules. +#[cfg(test)] +pub(super) fn conformance_result( + entry: &AssetEntry, + source: &Arc>, +) -> Result { + use std::io::Seek; + let mut decoder = Decoder::new(entry, source)?; + for _ in 0..100 { + let before = decoder.reader.stream_position().unwrap(); + let result = decoder.step(); + let after = decoder.reader.stream_position().unwrap(); + assert!(after >= before && after - before <= 4096, "unbounded or rewound decode step"); + if let Some(bank) = result? { + return Ok(match bank { + Decoded::Glyph(bank) => super::decode::tests::glyph_snapshot(&bank), + Decoded::Sound(bank) => super::decode::tests::sound_snapshot(&bank), + Decoded::Scene(bank) => super::decode::tests::scene_snapshot(&bank), + }); + } + } + panic!("conformance fixture exceeded its step budget") +} + #[cfg(test)] mod tests { use super::*; @@ -556,4 +518,55 @@ mod tests { assert_eq!(manager.preloads_ready(), Ok(true)); assert_eq!(manager.slot_info(SlotRef::audio(0)).asset_id, Some(1)); } + #[test] + fn canceled_and_superseded_partial_decoders_never_publish() { + use crate::memory_banks::SoundBankPoolAccess; + let bytes = vec![0x12; 16384]; + let entry = AssetEntry { + asset_id: 1, + asset_name: "pcm".into(), + bank_type: BankType::SOUNDS, + offset: 0, + size: bytes.len() as u64, + decoded_size: bytes.len() as u64, + codec: AssetCodec::None, + metadata: serde_json::json!({"sample_rate":44100,"channels":1}), + }; + let mut newer = entry.clone(); + newer.asset_id = 2; + let banks = Arc::new(crate::memory_banks::MemoryBanks::new()); + let mut manager = AssetManager::new( + vec![entry, newer], + AssetsPayloadSource::from_bytes(bytes), + banks.clone(), + banks.clone(), + banks.clone(), + ); + let lane = Arc::new(ManualLane::default()); + assert!(manager.bind_background_work(lane.clone())); + let handle = manager.load(1, 0).unwrap(); + assert!(lane.step()); + assert!(lane.step()); + assert_eq!(manager.status(handle), LoadStatus::LOADING); + assert_eq!(manager.cancel(handle), AssetOpStatus::Ok); + while lane.step() {} + assert_eq!(manager.status(handle), LoadStatus::CANCELED); + assert!(manager.sound_policy.staging.read().unwrap().is_empty()); + manager.apply_commits(); + assert!(banks.sound_bank_slot(0).is_none()); + let old = manager.load(1, 0).unwrap(); + assert!(lane.step()); + assert!(lane.step()); + let new = manager.load(2, 0).unwrap(); + assert_eq!(old, new); // Stable slot handle, different request generation. + assert!(lane.step()); // Discard the in-flight old decoder. + assert!(manager.sound_policy.staging.read().unwrap().is_empty()); + while lane.step() {} + assert_eq!(manager.status(new), LoadStatus::READY); + assert!(banks.sound_bank_slot(0).is_none()); + assert_eq!(manager.commit(new), AssetOpStatus::Ok); + manager.apply_commits(); + assert_eq!(manager.slot_info(SlotRef::audio(0)).asset_id, Some(2)); + assert_eq!(banks.sound_bank_slot(0).unwrap().samples[0].data, vec![0x1212; 8192]); + } } diff --git a/crates/console/prometeu-system/src/services/memcard/transaction/tests.rs b/crates/console/prometeu-system/src/services/memcard/transaction/tests.rs index 02106ee..5d139dc 100644 --- a/crates/console/prometeu-system/src/services/memcard/transaction/tests.rs +++ b/crates/console/prometeu-system/src/services/memcard/transaction/tests.rs @@ -885,3 +885,232 @@ fn ending_a_session_releases_a_completed_unconsumed_request() { assert!(s.take_idle_card().unwrap().is_some()); controller.stop().unwrap(); } + +#[test] +fn persistent_save_preempts_real_multichunk_asset_decoders() { + use crate::memcard::session::{RequestState, Session}; + use crate::{AsyncWorkLane, AsyncWorkLaneConfig, AsyncWorkLaneController}; + use prometeu_drivers::{ + AssetManager, GlyphBankPoolAccess, MemoryBanks, SceneBankPoolAccess, SoundBankPoolAccess, + }; + use prometeu_hal::{ + AssetBridge, + asset::{AssetCodec, AssetEntry, AssetOpStatus, BankType, LoadStatus}, + background_work::{AssetWork, BackgroundWork, WorkUnavailable}, + cartridge::AssetsPayloadSource, + }; + use std::{ + sync::mpsc, + thread, + time::{Duration, Instant}, + }; + type Events = Arc>>; + struct ObservedLane { + lane: Arc, + events: Events, + paused: mpsc::Sender<()>, + resume: Mutex>>, + } + impl BackgroundWork for ObservedLane { + fn submit_asset(&self, mut work: AssetWork) -> std::result::Result<(), WorkUnavailable> { + let events = self.events.clone(); + let paused = self.paused.clone(); + let resume = self.resume.lock().unwrap().take().unwrap(); + let mut step = 0; + self.lane.submit_asset(Box::new(move |canceled| { + let result = work(canceled); + step += 1; + events.lock().unwrap().push(("asset", thread::current().id())); + if step == 4 { + paused.send(()).unwrap(); + resume.recv_timeout(Duration::from_secs(10)).unwrap(); + } + result + })) + } + } + struct ObservedStore { + inner: Store, + events: Events, + } + impl MemcardStorage for ObservedStore { + fn len(&self) -> std::result::Result { + self.inner.len() + } + fn read_only(&self) -> bool { + false + } + fn read_at( + &mut self, + offset: u64, + out: &mut [u8], + ) -> std::result::Result<(), MemcardIoError> { + self.inner.read_at(offset, out) + } + fn write_at( + &mut self, + offset: u64, + bytes: &[u8], + ) -> std::result::Result<(), MemcardIoError> { + self.events.lock().unwrap().push(("save write", thread::current().id())); + self.inner.write_at(offset, bytes) + } + fn sync(&mut self) -> std::result::Result<(), MemcardIoError> { + self.events.lock().unwrap().push(("save sync", thread::current().id())); + self.inner.sync() + } + } + for kind in [BankType::GLYPH, BankType::SOUNDS, BankType::SCENE] { + let (card, disk) = formatted(); + drop(card); + let events: Events = Arc::default(); + let mut card = Card::mount(Box::new(ObservedStore { + inner: Store(disk.clone()), + events: events.clone(), + })) + .unwrap(); + add(&mut card, 1, 1); + let mut session = Session::default(); + let context = session.load_card(card, 1, 1, 1024 * 1024).unwrap(); + session.write(context, 0, 0, b"persistent under asset pressure").unwrap(); + events.lock().unwrap().clear(); + let (bytes, decoded_size, metadata) = match kind { + BankType::GLYPH => { + let mut bytes = vec![0x12; 16384]; + bytes.extend([255; 64]); + ( + bytes, + 32768 + 64, + serde_json::json!({"tile_size":8,"width":256,"height":128,"palette_count":1,"palette_authored":1}), + ) + } + BankType::SOUNDS => { + (vec![0x12; 16385], 16385, serde_json::json!({"sample_rate":44100,"channels":1})) + } + BankType::SCENE => { + let mut bytes = vec![0; 140]; + bytes[..8].copy_from_slice(&[b'S', b'C', b'N', b'E', 1, 0, 4, 0]); + for start in [12, 44, 76, 108] { + bytes[start + 5] = 8; + } + bytes[12] = 1; + bytes[28..32].copy_from_slice(&4097_u32.to_le_bytes()); + bytes[32..36].copy_from_slice(&1_u32.to_le_bytes()); + bytes[36..40].copy_from_slice(&4097_u32.to_le_bytes()); + bytes.splice(44..44, std::iter::repeat_n([7, 3, 0x34, 0x12], 4097).flatten()); + ( + bytes, + 64 + 4097 * size_of::() as u64, + serde_json::json!({}), + ) + } + }; + let entry = AssetEntry { + asset_id: 1, + asset_name: "pressure".into(), + bank_type: kind, + offset: 0, + size: bytes.len() as u64, + decoded_size, + codec: AssetCodec::None, + metadata, + }; + let banks = Arc::new(MemoryBanks::new()); + let mut manager = AssetManager::new( + vec![entry], + AssetsPayloadSource::from_bytes(bytes), + banks.clone(), + banks.clone(), + banks.clone(), + ); + let lane = Arc::new(AsyncWorkLane::default()); + let (paused_tx, paused_rx) = mpsc::channel(); + let (resume_tx, resume_rx) = mpsc::channel(); + let observed = Arc::new(ObservedLane { + lane: lane.clone(), + events: events.clone(), + paused: paused_tx, + resume: Mutex::new(Some(resume_rx)), + }); + assert!(manager.bind_background_work(observed)); + let mut controller = + AsyncWorkLaneController::start(AsyncWorkLaneConfig::default(), lane.clone()); + let handle = manager.load(1, 0).unwrap(); + paused_rx.recv_timeout(Duration::from_secs(10)).unwrap(); + assert_eq!(manager.status(handle), LoadStatus::LOADING); + assert!( + banks.glyph_bank_slot(0).is_none() + && banks.sound_bank_slot(0).is_none() + && banks.scene_bank_slot(0).is_none() + ); + let request = session.commit(context, 0, 7, Instant::now(), &lane).unwrap(); + resume_tx.send(()).unwrap(); + let deadline = Instant::now() + Duration::from_secs(10); + loop { + session.poll(Instant::now()); + if session.query(context, request).unwrap().state != RequestState::Pending + && manager.status(handle) == LoadStatus::READY + { + break; + } + assert!(Instant::now() < deadline, "save/asset did not complete for {kind:?}"); + thread::yield_now(); + } + assert_eq!(session.query(context, request).unwrap().state, RequestState::Success); + assert!( + banks.glyph_bank_slot(0).is_none() + && banks.sound_bank_slot(0).is_none() + && banks.scene_bank_slot(0).is_none() + ); + assert_eq!(manager.commit(handle), AssetOpStatus::Ok); + manager.apply_commits(); + match kind { + BankType::GLYPH => { + let bank = banks.glyph_bank_slot(0).unwrap(); + assert_eq!((bank.width, bank.height), (256, 128)); + assert_eq!( + bank.pixel_indices, + (0..32768).map(|i| 1 + (i % 2) as u8).collect::>() + ); + assert!(bank.palettes[0].iter().all(|c| c.raw() == 0xffffffff)); + } + BankType::SOUNDS => { + let bank = banks.sound_bank_slot(0).unwrap(); + assert_eq!(bank.samples[0].sample_rate, 44100); + assert_eq!(bank.samples[0].data, vec![0x1212; 8192]); + } + BankType::SCENE => { + let bank = banks.scene_bank_slot(0).unwrap(); + assert_eq!( + (bank.layers[0].tilemap.width, bank.layers[0].tilemap.height), + (4097, 1) + ); + assert!(bank.layers[0].active); + assert_eq!(bank.layers[0].tilemap.tiles.len(), 4097); + assert!(bank.layers[0].tilemap.tiles.iter().all(|t| t.active + && t.flip_x + && t.flip_y + && t.glyph.glyph_id == 0x1234 + && t.glyph.palette_id == 3)); + assert!(bank.layers[1..].iter().all(|l| l.tilemap.tiles.is_empty())); + } + } + controller.stop().unwrap(); + let observed = events.lock().unwrap(); + assert_eq!(observed[..4].iter().map(|e| e.0).collect::>(), vec!["asset"; 4]); + assert_eq!(observed[4].0, "save write"); + let resumed = observed[4..].iter().position(|e| e.0 == "asset").unwrap() + 4; + assert_eq!(observed[resumed - 1].0, "save sync"); + assert!(observed[resumed..].iter().all(|e| e.0 == "asset")); + let worker = observed[0].1; + assert_ne!(worker, thread::current().id()); + assert!(observed.iter().all(|e| e.1 == worker)); + drop(observed); + drop(session); + let mut recovered = Session::default(); + let c = recovered.load_card(reboot(&disk), 1, 1, 1024 * 1024).unwrap(); + let mut saved = [0; 64]; + let n = recovered.read(c, 0, 0, &mut saved).unwrap(); + assert_eq!(&saved[..n], b"persistent under asset pressure"); + } +} diff --git a/discussion/lessons/DSC-0009-perf-async-background-work-lanes-for-assets-and-fs/LSN-0050-serial-async-lanes-bound-backlog-complexity.md b/discussion/lessons/DSC-0009-perf-async-background-work-lanes-for-assets-and-fs/LSN-0050-serial-async-lanes-bound-backlog-complexity.md index 71df825..2e60f2c 100644 --- a/discussion/lessons/DSC-0009-perf-async-background-work-lanes-for-assets-and-fs/LSN-0050-serial-async-lanes-bound-backlog-complexity.md +++ b/discussion/lessons/DSC-0009-perf-async-background-work-lanes-for-assets-and-fs/LSN-0050-serial-async-lanes-bound-backlog-complexity.md @@ -86,6 +86,35 @@ 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. +## Share format rules without sharing execution strategy + +The glyph, sound and scene decoders now consume one private driver validation +module. Complete-buffer decoding can materialize a whole payload, while the +shared worker retains state and reads at most 4096 bytes per decode step. Sharing +validation does not require replacing cooperative IO with a full-buffer read. + +A differential test alone is insufficient: both paths can agree on a mistake. +Use independent expected banks and rejection fixtures, then compare each entry +point against those expectations. Include physical file carriers: an in-memory +slice rejects an out-of-range request before a decoder runs, which can conceal +a short-file discrepancy in a reader that accepts EOF. The initial corpus found +that legacy PCM and scene loads accepted missing declared bytes. After an +explicit compatibility decision, both modes reject those files while still +ignoring a physically present odd PCM tail. + +The production pressure regression pauses the real decoder after a safe step, +queues a persistent memcard save, and observes save writes and synchronization +before the next asset step. It checks all three multi-chunk asset kinds, the +single worker identity, complete output, deferred frame publication and saved +data after remount. This establishes priority and retained progress through +observable ordering, rather than a host-specific latency threshold. Separate +regressions cover cancellation, superseding and preload publication. + +This refinement follows [DEC-0064](../../workflow/decisions/DEC-0064-q7-share-asset-decoding-validation-and-conformance.md). +The published contract is [Asset Management](../../../docs/specs/runtime/15-asset-management.md#43-decoding-validation-and-physical-payload-completeness). +The ordering fixture uses the persistent transaction protocol with a deterministic +storage backend; file-host latency measurements remain separate evidence. + ## Takeaways - A runtime async lane is an ownership boundary, not just an implementation diff --git a/docs/specs/runtime/15-asset-management.md b/docs/specs/runtime/15-asset-management.md index 6c73891..6d3f5ec 100644 --- a/docs/specs/runtime/15-asset-management.md +++ b/docs/specs/runtime/15-asset-management.md @@ -242,6 +242,32 @@ If a scene glyph dependency cannot be resolved: - draw/composition MUST fail as a fatal machine error with clear logging; - runtime MUST NOT continue scene composition after the missing dependency is detected. +### 4.3 Decoding validation and physical payload completeness + +Complete-buffer/reader decoding and resumable decoding MUST use the same driver +format authority for glyph layout, sound metadata and PCM conversion, and scene +headers, layers, tile ranges and decoded-size validation. Execution mode MUST NOT +change acceptance or semantic bank output for the same declared asset slice. + +Every byte of the declared slice MUST be physically available. A short file read +MUST fail; it must not publish a partial sound or accept a physically complete +scene whose byte length is shorter than the declared asset size. This applies +even when the missing sound byte would have been an ignored odd PCM tail. +A physically present final unpaired PCM byte remains accepted and ignored. + +The shared worker retains resumable state and reads at most 4096 payload bytes +per decode step. Scene header and layer steps read their fixed headers; tile +steps use complete tile records. PCM steps end on sample boundaries except for +the final odd tail. Save work takes priority at the next safe step. Cancellation +and target generation are checked before continuing and before staging a +complete bank; frame-boundary publication remains separate from decoding. + +The conformance corpus checks explicit outputs and refusal outcomes across +buffer, reader, legacy load and resumable entry points. It covers empty supported +forms, chunk edges, palettes, truncated and trailing data, metadata, declared +sizes, scene ranges and nonfinite parallax. Ignored reserved fields remain +ignored; this validation sharing does not introduce new codecs or payload versions. + ## 5 Banks and Slots The current runtime exposes bank types: