Files
prometeu-studio/tools/pbx-conformance/memcard.rs
bquarkz 1d8b8c2101
Test / Tests and coverage
Intrepid/Prometeu/Studio/pipeline/pr-master This commit looks good
feat(studio): integrate memcard persistence and headless controls
Persist cartridge identity and slot configuration, add MemcardBoot and the MemcardBuffer SDK, and consume the runtime's negotiated memcard host controls with protected teardown.

Qualify save/reopen and version upgrades through distinct configured runtime processes. Include specs, examples, regression evidence and the consolidated discussion lesson.
2026-10-30 11:01:02 +00:00

534 lines
18 KiB
Rust

//! Native production Firmware/SystemOS evidence; never a claim about the installed process protocol.
use prometeu_drivers::{TestPlatform, memcard::FileMemcard};
use prometeu_firmware::firmware::{Firmware, FirmwareState};
use prometeu_hal::{
InputSignals,
app_mode::AppMode,
cartridge::{AssetsPayloadSource, Cartridge},
memcard::{MemcardIoError, MemcardStorage},
};
use prometeu_system::memcard::{
admission::PreparationState,
image::IMAGE_BYTES,
session::{Mode, RequestState},
transaction::Card,
};
use std::{
path::Path,
time::{Duration, Instant},
};
const APP: u32 = 1296387395;
const PAYLOAD: [u8; 4] = [0, 127, 128, 255];
fn fresh(path: &Path) -> FileMemcard {
FileMemcard::create(path, IMAGE_BYTES, |io, id| {
Card::format(io, id).map_err(|_| MemcardIoError::IoError)
})
.unwrap()
}
fn start(
root: &Path,
name: &str,
storage: Option<Box<dyn MemcardStorage>>,
choice: InputSignals,
) -> (Firmware, TestPlatform) {
start_slots(root, name, storage, choice, 1)
}
fn start_slots(
root: &Path,
name: &str,
storage: Option<Box<dyn MemcardStorage>>,
choice: InputSignals,
slots: u8,
) -> (Firmware, TestPlatform) {
let mut fw = Firmware::new(None);
let mut platform = TestPlatform::new();
fw.os.poll_background_io(&mut platform);
if let Some(storage) = storage {
fw.os.memcard().mount_card(storage).unwrap();
let deadline = Instant::now() + Duration::from_secs(5);
while !fw.os.memcard().card_installed() {
fw.os.poll_background_io(&mut platform);
assert!(
!matches!(fw.os.memcard().admission.state, PreparationState::Failed(_)),
"mount failed: {:?}",
fw.os.memcard().admission.state
);
assert!(Instant::now() < deadline);
std::thread::sleep(Duration::from_millis(1));
}
}
fw.load_cartridge(Cartridge {
app_id: APP,
title: "Studio memcard".into(),
app_version: "1".into(),
app_mode: AppMode::Game,
capabilities: super::caps::MEMCARD,
memcard_slots: Some(slots),
program: std::fs::read(root.join(format!("{name}.pbx"))).unwrap(),
assets: AssetsPayloadSource::empty(),
asset_table: vec![],
preload: vec![],
});
fw.tick(&InputSignals::default(), &mut platform);
fw.tick(&choice, &mut platform);
(fw, platform)
}
fn run(fw: &mut Firmware, platform: &mut TestPlatform, frames: usize) {
for _ in 0..frames {
fw.tick(&InputSignals::default(), platform);
assert!(
!matches!(fw.state, FirmwareState::AppCrashes(_)),
"guest crashed: {:?}",
fw.state
);
std::thread::sleep(Duration::from_millis(1));
}
let deadline = Instant::now() + Duration::from_secs(2);
while worker_pending(fw) {
assert!(Instant::now() < deadline, "native worker did not settle");
fw.tick(&InputSignals::default(), platform);
assert!(
!matches!(fw.state, FirmwareState::AppCrashes(_)),
"guest crashed: {:?}",
fw.state
);
std::thread::sleep(Duration::from_millis(1));
}
}
fn worker_pending(fw: &mut Firmware) -> bool {
let mem = fw.os.memcard();
let telemetry = mem.lane.telemetry();
let context = mem.session.context();
mem.admission.state == PreparationState::Pending
|| telemetry.active_job_id.is_some()
|| telemetry.pending_depth != 0
|| (1..=8).any(|id| {
mem.session
.query(context, id)
.is_ok_and(|r| r.state == RequestState::Pending)
})
}
fn assert_ram(fw: &mut Firmware, dirty: bool) {
let session = &mut fw.os.memcard().session;
let context = session.context();
let mut bytes = [0; 4];
assert_eq!(session.read(context, 0, 0, &mut bytes).unwrap(), 4);
assert_eq!(bytes, PAYLOAD);
assert_eq!(session.descriptor(context, 0).unwrap().2, dirty);
}
struct Fault {
inner: FileMemcard,
kind: u8,
payload: bool,
}
impl MemcardStorage for Fault {
fn len(&self) -> Result<u64, MemcardIoError> {
self.inner.len()
}
fn read_only(&self) -> bool {
self.inner.read_only()
}
fn read_at(&mut self, o: u64, b: &mut [u8]) -> Result<(), MemcardIoError> {
self.inner.read_at(o, b)
}
fn write_at(&mut self, o: u64, b: &[u8]) -> Result<(), MemcardIoError> {
if o >= 802816 {
self.payload = true;
if self.kind == 1 {
return Err(MemcardIoError::IoError);
}
}
self.inner.write_at(o, b)?;
if self.kind == 2 && self.payload && (o == 8192 || o == 12288) {
self.inner.sync()?;
return Err(MemcardIoError::IoError);
}
Ok(())
}
fn sync(&mut self) -> Result<(), MemcardIoError> {
self.inner.sync()
}
}
pub fn verify(root: &Path) {
let work = std::env::temp_dir().join(format!("studio-memcard-native-{}", std::process::id()));
std::fs::create_dir_all(&work).unwrap();
let abi = std::fs::read(root.join("pbs-memcard-abi.pbx")).unwrap();
super::ValidatedProgramImage::load(
&abi,
&mut super::LoadBudget::new(Default::default()),
super::caps::MEMCARD,
)
.unwrap();
println!("NATIVE LOAD PASS all 14 mem imports against the production loader");
for suffix in ["", "-optimized"] {
let name = format!("pbs-memcard-example{suffix}");
let path = work.join(format!("save{suffix}.pmc"));
let (mut fw, mut p) = start(
root,
&name,
Some(Box::new(fresh(&path))),
InputSignals {
a_signal: true,
..Default::default()
},
);
run(&mut fw, &mut p, 100);
assert_ram(&mut fw, false);
assert_eq!(fw.os.memcard().session.mode(), Some(Mode::Persistent));
drop(fw);
let mut card = Card::mount(Box::new(FileMemcard::open(&path, false).unwrap())).unwrap();
let slot = card
.catalog
.games
.iter()
.find(|g| g.app_id == APP)
.unwrap()
.slots[0] as usize;
let generation = card.current().slots[slot].generation;
let mut bytes = [0; 4];
assert_eq!(card.read_slot(slot, &mut bytes).unwrap(), 4);
assert_eq!(bytes, PAYLOAD);
drop(card);
let (mut reopened, mut p) = start(
root,
&name,
Some(Box::new(FileMemcard::open(&path, false).unwrap())),
InputSignals {
a_signal: true,
..Default::default()
},
);
run(&mut reopened, &mut p, 100);
assert_ram(&mut reopened, false);
drop(reopened);
let card = Card::mount(Box::new(FileMemcard::open(&path, false).unwrap())).unwrap();
assert_eq!(
card.current().slots[slot].generation,
generation,
"reopen must read, not resave"
);
drop(card);
let (mut memory, mut p) = start(
root,
&name,
None,
InputSignals {
x_signal: true,
..Default::default()
},
);
run(&mut memory, &mut p, 100);
assert_ram(&mut memory, true);
assert_eq!(memory.os.memcard().session.mode(), Some(Mode::MemoryOnly));
memory.request_home_from_host();
run(&mut memory, &mut p, 4);
assert!(memory.resume_resident_game_from_home());
run(&mut memory, &mut p, 4);
assert_ram(&mut memory, true);
println!(
"NATIVE PASS {name}: exact save/reopen, no resave, memory-only; not installed-process evidence"
);
let name = format!("pbs-memcard-contract{suffix}");
let path = work.join(format!("contract{suffix}.pmc"));
let (mut contract, mut p) = start(
root,
&name,
Some(Box::new(fresh(&path))),
InputSignals {
a_signal: true,
..Default::default()
},
);
run(&mut contract, &mut p, 100);
assert_ram(&mut contract, false);
println!(
"NATIVE PASS {name}: zero initialization, aliases, ordinary-array vacancy, domain errors/status-first Null payloads"
);
let name = format!("pbs-memcard-alias{suffix}");
let (mut alias, mut p) = start(
root,
&name,
None,
InputSignals {
x_signal: true,
..Default::default()
},
);
run(&mut alias, &mut p, 100);
assert_ram(&mut alias, true);
println!(
"NATIVE PASS {name}: imported type/service aliases retain native carrier and forwarding"
);
let name = format!("pbs-memcard-imports{suffix}");
let (mut imports, mut p) = start(
root,
&name,
None,
InputSignals {
x_signal: true,
..Default::default()
},
);
run(&mut imports, &mut p, 100);
let context = imports.os.memcard().session.context();
assert_eq!(
imports
.os
.memcard()
.session
.presentation(context)
.unwrap()
.unwrap()
.title,
"Imported hook"
);
println!(
"NATIVE PASS {name}: one canonical imported role, initialized dependencies, retained target"
);
let name = format!("pbs-memcard-busy{suffix}");
let path = work.join(format!("busy{suffix}.pmc"));
let (mut busy, mut p) = start(
root,
&name,
Some(Box::new(fresh(&path))),
InputSignals {
a_signal: true,
..Default::default()
},
);
run(&mut busy, &mut p, 100);
assert_ram(&mut busy, false);
println!("NATIVE PASS {name}: committing source rejects write/clear/second commit");
let name = format!("pbs-memcard-clear{suffix}");
let path = work.join(format!("clear{suffix}.pmc"));
let (mut clear, mut p) = start(
root,
&name,
Some(Box::new(fresh(&path))),
InputSignals {
a_signal: true,
..Default::default()
},
);
run(&mut clear, &mut p, 100);
let context = clear.os.memcard().session.context();
let (descriptor, used, dirty) = clear.os.memcard().session.descriptor(context, 0).unwrap();
assert_eq!(used, 0);
assert_eq!(descriptor.generation, 2);
assert!(!dirty);
drop(clear);
let mut card = Card::mount(Box::new(FileMemcard::open(&path, false).unwrap())).unwrap();
let slot = card
.catalog
.games
.iter()
.find(|g| g.app_id == APP)
.unwrap()
.slots[0] as usize;
assert_eq!(card.read_slot(slot, &mut [0; 4]).unwrap(), 0);
println!("NATIVE PASS {name}: explicit clear commit survives remount");
let name = format!("pbs-memcard-publish{suffix}");
let path = work.join(format!("publish{suffix}.pmc"));
let (mut public, mut p) = start(
root,
&name,
Some(Box::new(fresh(&path))),
InputSignals {
a_signal: true,
..Default::default()
},
);
run(&mut public, &mut p, 100);
assert_ram(&mut public, false);
let context = public.os.memcard().session.context();
let result = (1..=8)
.find_map(|id| public.os.memcard().session.query(context, id).ok())
.unwrap();
assert_eq!(result.state, RequestState::Success);
drop(public);
let mut card = Card::mount(Box::new(FileMemcard::open(&path, false).unwrap())).unwrap();
let game = card.catalog.games.iter().find(|g| g.app_id == APP).unwrap();
assert_eq!(game.title, "Updated presentation");
assert_eq!(game.data_format_version, 2);
assert_eq!(card.read_icon(APP).unwrap(), vec![0; 560]);
println!("NATIVE PASS {name}: public title/format/icon publication and retained request");
let name = format!("pbs-memcard-transfer-limit{suffix}");
let (mut transfer, mut p) = start(
root,
&name,
None,
InputSignals {
x_signal: true,
..Default::default()
},
);
run(&mut transfer, &mut p, 100);
let session = &mut transfer.os.memcard().session;
let context = session.context();
assert_eq!(session.descriptor(context, 0).unwrap().1, 4096);
let mut last = [0];
assert_eq!(session.read(context, 0, 4095, &mut last).unwrap(), 1);
assert_eq!(last, [255]);
println!("NATIVE PASS {name}: exact 4096-byte transfer and byte 255");
let name = format!("pbs-memcard-example{suffix}");
let (mut full, mut p) = start_slots(
root,
&name,
None,
InputSignals {
x_signal: true,
..Default::default()
},
64,
);
run(&mut full, &mut p, 100);
assert_eq!(full.os.memcard().session.count(), 64);
assert_ram(&mut full, true);
println!("NATIVE PASS {name}: 64-slot admission");
}
for (kind, expected) in [(1, RequestState::Failure), (2, RequestState::Indeterminate)] {
for suffix in ["", "-optimized"] {
let path = work.join(format!("fault-{kind}{suffix}.pmc"));
let fault = Fault {
inner: fresh(&path),
kind,
payload: false,
};
let (mut fw, mut p) = start(
root,
&format!("pbs-memcard-retained{suffix}"),
Some(Box::new(fault)),
InputSignals {
a_signal: true,
..Default::default()
},
);
run(&mut fw, &mut p, 100);
let session = &mut fw.os.memcard().session;
let context = session.context();
let result = (1..=8)
.find_map(|id| session.query(context, id).ok())
.expect("one retained guest request");
assert_eq!(result.state, expected);
assert!(session.descriptor(context, 0).unwrap().2);
println!(
"NATIVE PASS PBS facade query{suffix}: {expected:?}, request {}, dirty RAM preserved",
result.id
);
}
}
for name in [
"pbs-memcard-inconsistent",
"pbs-memcard-trap",
"pbs-memcard-fuel",
"pbs-memcard-capacity-negative",
"pbs-memcard-capacity-overflow",
"pbs-memcard-read-bounds",
"pbs-memcard-write-bounds",
"pbs-memcard-byte-negative",
"pbs-memcard-byte-overflow",
"pbs-memcard-transfer-overflow",
] {
for suffix in ["", "-optimized"] {
let name = format!("{name}{suffix}");
let (mut fw, mut p) = start(
root,
&name,
None,
InputSignals {
x_signal: true,
..Default::default()
},
);
for _ in 0..150 {
fw.tick(&InputSignals::default(), &mut p);
if matches!(fw.state, FirmwareState::AppCrashes(_)) {
break;
}
std::thread::sleep(Duration::from_millis(1));
}
assert!(
matches!(fw.state, FirmwareState::AppCrashes(_)),
"{name} must block admission"
);
if let Some(task) = fw.os.lifecycle().resident_game_task() {
let sessions = fw.os.sessions();
let session = sessions.vm_session_for_task(task).unwrap();
assert_eq!(
session
.runtime
.atomic_telemetry
.completed_logical_frames
.load(std::sync::atomic::Ordering::Relaxed),
0
);
}
println!("NATIVE PASS {name}: trap/failure, no completed gameplay frame");
}
}
let path = work.join("readonly.pmc");
drop(fresh(&path));
for storage in [
None,
Some(Box::new(FileMemcard::open(&path, true).unwrap()) as Box<dyn MemcardStorage>),
] {
let (mut fw, mut p) = start(
root,
"pbs-memcard-example",
storage,
InputSignals {
a_signal: true,
..Default::default()
},
);
run(&mut fw, &mut p, 20);
assert!(matches!(fw.state, FirmwareState::LoadCartridge(_)));
assert_eq!(
fw.os.memcard().session.mode(),
None,
"must not silently fall back to RAM"
);
}
println!("NATIVE PASS absent/read-only: explicit choice retained; no memory fallback");
let corrupt = work.join("corrupt.pmc");
drop(fresh(&corrupt));
let mut bytes = std::fs::read(&corrupt).unwrap();
bytes[8192..16384].fill(0);
std::fs::write(&corrupt, &bytes).unwrap();
let mut fw = Firmware::new(None);
let mut p = TestPlatform::new();
fw.os.poll_background_io(&mut p);
fw.os
.memcard()
.mount_card(Box::new(FileMemcard::open(&corrupt, false).unwrap()))
.unwrap();
let deadline = Instant::now() + Duration::from_secs(2);
while fw.os.memcard().admission.state == PreparationState::Pending {
fw.os.poll_background_io(&mut p);
assert!(Instant::now() < deadline);
std::thread::sleep(Duration::from_millis(1));
}
assert_eq!(
fw.os.memcard().admission.state,
PreparationState::Failed(prometeu_system::memcard::image::Error::Corrupt)
);
assert_eq!(std::fs::read(&corrupt).unwrap(), bytes);
println!("NATIVE PASS corrupt media: rejected without replacing with empty data");
let (mut installed, mut p) = start(
root,
"pbs-memcard-installed",
None,
InputSignals {
x_signal: true,
..Default::default()
},
);
run(&mut installed, &mut p, 100);
assert_ram(&mut installed, true);
println!(
"NATIVE PASS installed-JAR PBS example: native Firmware/SystemOS execution, not installed runtime process"
);
std::fs::remove_dir_all(work).unwrap();
}