feat(studio): integrate memcard persistence and headless controls
Test / Tests and coverage
Intrepid/Prometeu/Studio/pipeline/pr-master This commit looks good

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.
This commit is contained in:
2026-10-30 11:01:02 +00:00
parent 3a3417eb44
commit 1d8b8c2101
110 changed files with 6502 additions and 85 deletions
+533
View File
@@ -0,0 +1,533 @@
//! 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();
}