fix(headless): wait for memcard bootstrap IO progress
Intrepid/Prometeu/Runtime/pipeline/head There was a failure building this commit

Coordinate bounded native publication progress during frame advance while preserving watchdogs, guest budgets and resource ownership. Add controlled and packaged reopen regressions, clarify the runtime specs, and retain qualification evidence.
This commit is contained in:
2026-11-10 23:26:40 +00:00
parent 49d7fca0b7
commit c3589be1ad
34 changed files with 5904 additions and 5 deletions
@@ -11,6 +11,7 @@ use std::collections::BTreeMap;
pub enum MemcardFixture {
Write,
Read,
ReadWithPresentation,
Dirty,
}
#[derive(Default)]
@@ -47,12 +48,14 @@ impl Code {
/// 104 MEMORY_ONLY, 201 exact existing readback, 301 dirty/uncommitted RAM.
/// Read never writes or submits a commit; a missing/wrong payload traps.
pub fn memcard_program(kind: MemcardFixture) -> Vec<u8> {
let reads = matches!(kind, MemcardFixture::Read | MemcardFixture::ReadWithPresentation);
let mut main = Code::default();
main.emit("HOSTCALL 0");
main.check(0, true);
main.emit("PUSH_I64 4\nARRAY_NEW 9\nSET_GLOBAL 1");
if matches!(kind, MemcardFixture::Read) {
main.emit("GET_GLOBAL 0\nPUSH_I32 0\nPUSH_I32 0\nGET_GLOBAL 1\nPUSH_I32 0\nPUSH_I32 4\nHOSTCALL 1");
if reads {
let read_import = if matches!(kind, MemcardFixture::Read) { 1 } else { 2 };
main.emit(&format!("GET_GLOBAL 0\nPUSH_I32 0\nPUSH_I32 0\nGET_GLOBAL 1\nPUSH_I32 0\nPUSH_I32 4\nHOSTCALL {read_import}"));
main.check(4, false);
main.check(0, false);
for (i, value) in [0, 127, 128, 255].into_iter().enumerate() {
@@ -101,7 +104,9 @@ pub fn memcard_program(kind: MemcardFixture) -> Vec<u8> {
imports.push(("presentation", 8, 1));
}
match kind {
MemcardFixture::Read => imports.push(("slot_read", 6, 2)),
MemcardFixture::Read | MemcardFixture::ReadWithPresentation => {
imports.push(("slot_read", 6, 2));
}
MemcardFixture::Dirty => imports.push(("slot_write", 6, 2)),
MemcardFixture::Write => {
imports.extend([("slot_write", 6, 2), ("slot_commit", 2, 2), ("query", 2, 3)])
@@ -1,5 +1,6 @@
use std::fmt;
use std::sync::Arc;
use std::time::{Duration, Instant};
use prometeu_drivers::hardware::Hardware;
use prometeu_drivers::{ControlledWallClock, MemoryBanks};
@@ -20,6 +21,21 @@ pub use memcard::{
const BOOT_TICK_LIMIT: usize = 5000;
const HOST_FRAME_ADVANCE_TICK_LIMIT: usize = 100_000;
const BOOTSTRAP_IO_WAIT_QUANTUM: Duration = Duration::from_millis(5);
const BOOTSTRAP_IO_WAIT_LIMIT: Duration = Duration::from_secs(2);
/// One deadline for the entire advance, including repeated admission to the gate.
#[derive(Default)]
struct BootstrapIoWait {
deadline: Option<Instant>,
}
impl BootstrapIoWait {
fn next_wait(&mut self, now: Instant) -> Option<Duration> {
let deadline = *self.deadline.get_or_insert(now + BOOTSTRAP_IO_WAIT_LIMIT);
let remaining = deadline.saturating_duration_since(now);
(!remaining.is_zero()).then_some(remaining.min(BOOTSTRAP_IO_WAIT_QUANTUM))
}
}
/// One published logical frame plus the automation counter.
#[derive(Debug, Clone, PartialEq, Eq)]
@@ -360,6 +376,7 @@ impl HeadlessHost {
self.firmware.os.vm().set_paused(false);
self.firmware.os.vm().request_debug_step();
let mut io_wait = BootstrapIoWait::default();
for _ in 0..HOST_FRAME_ADVANCE_TICK_LIMIT {
// A controlled lifecycle slice can consume the runtime step marker
// without closing a logical frame. This operation still owns the
@@ -398,6 +415,24 @@ impl HeadlessHost {
frame_id: frame.frame_id,
});
}
loop {
// Refresh before every observation/poll: another lane job may
// have progressed without completing this publication.
let progress = self.firmware.os.memcard().lane.progress_stamp();
if !self.bootstrap_io_pending() {
break;
}
// Native polling and waiting do not execute machine ticks.
self.poll_memcard();
if self.host_action_required() {
self.finish_frame_advance();
return Ok(AdvanceFrameOutcome::ActionRequired);
}
if self.bootstrap_io_pending() {
self.wait_for_bootstrap_io(&mut io_wait, progress)?;
}
}
}
self.finish_frame_advance();
@@ -406,6 +441,32 @@ impl HeadlessHost {
})
}
fn bootstrap_io_pending(&mut self) -> bool {
let FirmwareState::GameRunning(step) = &self.firmware.state else { return false };
let task = step.task_id;
let hook_complete = self
.firmware
.os
.sessions()
.vm_session_for_task(task)
.is_some_and(|session| session.vm.memcard_boot_result() == Some(0));
let service = self.firmware.os.memcard();
hook_complete && service.session.boot_pending() && service.session.io_active()
}
fn wait_for_bootstrap_io(
&mut self,
wait: &mut BootstrapIoWait,
progress: u64,
) -> Result<(), HostError> {
let Some(timeout) = wait.next_wait(Instant::now()) else {
self.finish_frame_advance();
return Err(self.memcard_error("advance", "restart_required"));
};
self.firmware.os.memcard().lane.wait_for_progress(progress, timeout);
Ok(())
}
pub fn advance_frames(&mut self, count: u64) -> Result<AdvanceFramesOutcome, HostError> {
let mut completed = 0;
for _ in 0..count {
@@ -3,6 +3,282 @@ use crate::{AdvanceFrameOutcome, HostExecutionStatus};
use prometeu_test_support::memcard_fixture::{MemcardFixture, memcard_program};
use std::{fs, sync::mpsc};
/// Holds the first native write after admission; the controller decides its outcome.
struct BootstrapStore {
file: FileMemcard,
entered: mpsc::Sender<()>,
continue_io: mpsc::Receiver<Result<(), MemcardIoError>>,
held: bool,
}
impl MemcardStorage for BootstrapStore {
fn len(&self) -> Result<u64, MemcardIoError> {
self.file.len()
}
fn read_only(&self) -> bool {
false
}
fn read_at(&mut self, offset: u64, bytes: &mut [u8]) -> Result<(), MemcardIoError> {
self.file.read_at(offset, bytes)
}
fn write_at(&mut self, offset: u64, bytes: &[u8]) -> Result<(), MemcardIoError> {
if !self.held {
self.held = true;
let _ = self.entered.send(());
self.continue_io
.recv_timeout(Duration::from_secs(5))
.unwrap_or(Err(MemcardIoError::IoError))?;
}
self.file.write_at(offset, bytes)
}
fn sync(&mut self) -> Result<(), MemcardIoError> {
self.file.sync()
}
}
fn reopen_with_controlled_io(
kind: MemcardFixture,
) -> (Fixture, HeadlessHost, mpsc::Receiver<()>, mpsc::Sender<Result<(), MemcardIoError>>) {
use prometeu_system::memcard::{
image::{Game, Icon, crc32c},
transaction::{DurableResult, PublicationControl},
};
let f = Fixture::new(kind);
let file = FileMemcard::create(&f.image, IMAGE_BYTES, |io, id| {
Card::format(io, id).map_err(|_| MemcardIoError::IoError)
})
.unwrap();
let mut card = Card::mount(Box::new(file)).unwrap();
let icon = [0; 560];
card.register(
Game {
app_id: 42,
title: "Existing record".into(),
data_format_version: 1,
created_at: 0,
slots: vec![0],
icon: Icon { offset: 0, frames: 1, duration: 1, crc32c: crc32c(&icon) },
},
&icon,
&PublicationControl::default(),
)
.unwrap();
assert_eq!(
card.commit(0, &[0, 127, 128, 255], 0, &PublicationControl::default()).durable,
DurableResult::Success
);
drop(card);
let (entered_tx, entered) = mpsc::channel();
let (continue_io, release_rx) = mpsc::channel();
let mut host = HeadlessHost::new();
host.media.path = Some(f.image.clone());
host.media.access = Some(MediaAccess::ReadWrite);
host.install_memcard(Box::new(BootstrapStore {
file: FileMemcard::open(&f.image, false).unwrap(),
entered: entered_tx,
continue_io: release_rx,
held: false,
}))
.unwrap();
host.boot_with_memcard_choice(f.cart.to_string_lossy(), Choice::Persistent).unwrap();
assert_eq!(host.get_state().tick_index, 0);
(f, host, entered, continue_io)
}
#[test]
fn first_reopen_frame_waits_for_controlled_presentation_without_replaying() {
let (_f, mut host, entered, continue_io) =
reopen_with_controlled_io(MemcardFixture::ReadWithPresentation);
let (finished_tx, finished) = mpsc::channel();
let controller = std::thread::spawn(move || {
entered.recv_timeout(Duration::from_secs(3)).unwrap();
// Observe the owner while publication is provably held. This is a
// channel deadline, not a sleep used to infer that IO has started.
let premature = finished.recv_timeout(Duration::from_millis(300)).is_ok();
let _ = continue_io.send(Ok(()));
premature
});
let result = host.advance_frame();
let _ = finished_tx.send(());
let premature = controller.join().unwrap();
assert!(!premature, "advance returned while native publication was held: {result:?}");
assert!(matches!(
result,
Ok(AdvanceFrameOutcome::FrameCompleted { logical_frame_index: 1, .. })
));
let state = host.get_state();
assert_eq!(state.frame_index, 1);
assert_eq!(state.tick_index, 2);
assert_eq!(state.status, HostExecutionStatus::Paused);
assert_eq!(state.stack_top.last(), Some(&prometeu_bytecode::Value::Int64(201)));
assert!(!host.firmware.os.vm().debug_step_requested());
assert!(host.get_fault().is_none());
assert!(!host.get_memcard_state().io.active);
assert_eq!(host.capture_frame().unwrap().logical_frame_index, 1);
host.shutdown(TeardownPolicy::default()).unwrap();
}
#[test]
fn blocked_bootstrap_reaches_native_deadline_and_keeps_worker_lock() {
let (f, mut host, entered, continue_io) =
reopen_with_controlled_io(MemcardFixture::ReadWithPresentation);
let started = Instant::now();
let result = host.advance_frame();
entered.recv_timeout(Duration::from_secs(1)).unwrap();
let state = host.get_memcard_state();
let busy = matches!(FileMemcard::open(&f.image, false), Err(MemcardIoError::Busy));
// Always let the worker return before asserting, including on the old host.
continue_io.send(Ok(())).unwrap();
settle(&mut host);
assert_eq!(result.unwrap(), AdvanceFrameOutcome::ActionRequired);
assert!(started.elapsed() < Duration::from_secs(3));
assert!(state.recovery.restart_required);
assert!(state.io.active && busy);
assert_eq!(host.get_state().frame_index, 0);
assert_eq!(host.get_state().tick_index, 1);
assert_eq!(host.get_state().status, HostExecutionStatus::Paused);
assert!(!host.firmware.os.vm().debug_step_requested());
assert!(host.get_fault().is_none());
}
#[test]
fn ordinary_gameplay_commit_does_not_wait_for_native_io() {
let (_f, mut host, entered, continue_io) = reopen_with_controlled_io(MemcardFixture::Read);
host.advance_frame().unwrap();
let service = host.firmware.os.memcard();
let context = service.session.context();
service.session.write(context, 0, 0, &[0, 127, 128, 255]).unwrap();
service.session.commit(context, 0, 0, Instant::now(), &service.lane).unwrap();
entered.recv_timeout(Duration::from_secs(2)).unwrap();
let result = host.advance_frame();
let pending = host.get_memcard_state();
continue_io.send(Ok(())).unwrap();
settle(&mut host);
assert!(matches!(
result,
Ok(AdvanceFrameOutcome::FrameCompleted { logical_frame_index: 2, .. })
));
assert!(pending.io.active);
assert_eq!(pending.request.unwrap().operation, "commit");
assert!(!host.firmware.os.vm().debug_step_requested());
assert!(host.get_fault().is_none());
host.shutdown(TeardownPolicy::default()).unwrap();
}
#[test]
fn bootstrap_wait_deadline_is_shared_across_wakes_and_reentry() {
use super::super::{BOOTSTRAP_IO_WAIT_QUANTUM, BootstrapIoWait};
let start = Instant::now();
let mut wait = BootstrapIoWait::default();
assert_eq!(wait.next_wait(start), Some(BOOTSTRAP_IO_WAIT_QUANTUM));
assert_eq!(
wait.next_wait(start + Duration::from_millis(1000)),
Some(BOOTSTRAP_IO_WAIT_QUANTUM)
);
assert_eq!(wait.next_wait(start + Duration::from_millis(1999)), Some(Duration::from_millis(1)));
assert_eq!(wait.next_wait(start + Duration::from_secs(2)), None);
assert_eq!(wait.next_wait(start + Duration::from_secs(3)), None);
}
#[test]
fn bootstrap_outer_timeout_preserves_native_snapshot_and_machine_state() {
use super::super::BootstrapIoWait;
let (_f, mut host, _entered, _release) = reopen_with_controlled_io(MemcardFixture::Read);
let before = host.get_state();
host.firmware.os.vm().set_paused(false);
host.firmware.os.vm().request_debug_step();
let mut wait = BootstrapIoWait { deadline: Some(Instant::now()) };
let error = host.wait_for_bootstrap_io(&mut wait, 0).unwrap_err();
let snapshot = host.get_memcard_state();
let HostError::Memcard(error) = error else { panic!("expected a native memcard error") };
assert_eq!(error.operation, "advance");
assert_eq!(error.reason, "restart_required");
assert_eq!(error.state, snapshot);
let after = host.get_state();
assert_eq!((after.pc, after.frame_index, after.tick_index), (before.pc, 0, 0));
assert_eq!(after.stack_top.to_vec(), before.stack_top.to_vec());
assert_eq!(after.status, HostExecutionStatus::Paused);
assert!(!host.firmware.os.vm().debug_step_requested());
assert!(host.get_fault().is_none());
host.shutdown(TeardownPolicy::default()).unwrap();
}
#[test]
fn failed_bootstrap_io_returns_native_media_action_without_guest_fault() {
let (_f, mut host, entered, continue_io) =
reopen_with_controlled_io(MemcardFixture::ReadWithPresentation);
let controller = std::thread::spawn(move || {
entered.recv_timeout(Duration::from_secs(2)).unwrap();
continue_io.send(Err(MemcardIoError::Unavailable)).unwrap();
});
let result = host.advance_frame();
controller.join().unwrap();
assert_eq!(result.unwrap(), AdvanceFrameOutcome::ActionRequired);
let state = host.get_memcard_state();
assert!(state.recovery.removal_pending);
assert!(!state.io.active);
assert_eq!(host.get_state().frame_index, 0);
assert_eq!(host.get_state().status, HostExecutionStatus::Paused);
assert!(!host.firmware.os.vm().debug_step_requested());
assert!(host.get_fault().is_none());
}
#[test]
fn queued_bootstrap_publication_can_progress_without_moving_guest_during_poll() {
use prometeu_system::AsyncWorkJobOutcome;
let (_f, mut host, entered, continue_io) =
reopen_with_controlled_io(MemcardFixture::ReadWithPresentation);
let (busy_tx, busy) = mpsc::channel();
let (unblock, unblock_rx) = mpsc::channel();
host.firmware
.os
.memcard()
.lane
.submit_memcard_commit_write(move |_| {
busy_tx.send(()).unwrap();
let _ = unblock_rx.recv_timeout(Duration::from_secs(3));
AsyncWorkJobOutcome::Completed
})
.unwrap();
busy.recv_timeout(Duration::from_secs(2)).unwrap();
for _ in 0..10 {
host.firmware.os.vm().set_paused(false);
host.firmware.os.vm().request_debug_step();
host.tick_once();
if host.bootstrap_io_pending() {
break;
}
}
let pending = host.bootstrap_io_pending();
let queued = host.get_memcard_state();
let before = host.get_state();
host.poll_memcard();
let after = host.get_state();
let (finished_tx, finished) = mpsc::channel();
let controller = std::thread::spawn(move || {
let premature = finished.recv_timeout(Duration::from_millis(300)).is_ok();
let _ = unblock.send(());
entered.recv_timeout(Duration::from_secs(2)).unwrap();
let _ = continue_io.send(Ok(()));
premature
});
let result = host.advance_frame();
let _ = finished_tx.send(());
let premature = controller.join().unwrap();
assert!(pending);
assert!(!premature, "advance returned while its publication was queued: {result:?}");
assert_eq!(queued.io.phase, "queued");
assert_eq!(
(before.pc, before.frame_index, before.tick_index),
(after.pc, after.frame_index, after.tick_index)
);
assert_eq!(before.stack_top.to_vec(), after.stack_top.to_vec());
assert!(matches!(
result,
Ok(AdvanceFrameOutcome::FrameCompleted { logical_frame_index: 1, .. })
));
host.shutdown(TeardownPolicy::default()).unwrap();
}
struct Fixture {
root: PathBuf,
image: PathBuf,
@@ -10,10 +286,12 @@ struct Fixture {
}
impl Fixture {
fn new(kind: MemcardFixture) -> Self {
static COUNTER: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
let root = std::env::temp_dir().join(format!(
"native-memcard-{}-{}",
"native-memcard-{}-{}-{}",
std::process::id(),
std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).unwrap().as_nanos()
std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).unwrap().as_nanos(),
COUNTER.fetch_add(1, std::sync::atomic::Ordering::Relaxed)
));
let cart = root.join("cart");
fs::create_dir_all(&cart).unwrap();
@@ -844,6 +844,15 @@ fn packaged_installation_smoke() {
c.wait_exit();
}
#[test]
#[ignore = "requires PROMETEU_PROTOCOL_TEST_INSTALL pointing to an isolated installation"]
fn packaged_memcard_reopen_first_frame() {
let installation = PathBuf::from(
std::env::var_os("PROMETEU_PROTOCOL_TEST_INSTALL").expect("set isolated installation path"),
);
memcard_process::presentation_reopen(&installation.join("prometeu"));
}
#[test]
#[ignore = "requires PROMETEU_PROTOCOL_TEST_INSTALL pointing to an isolated installation"]
fn packaged_native_log_observation() {
@@ -102,6 +102,63 @@ fn persistence(binary: &Path) {
assert!(fs::read(&image).unwrap() == bytes);
}
pub(super) fn presentation_reopen(binary: &Path) {
let root = TempDir::new();
let image = root.0.join("presentation-reopen.pmc");
let write = card(MemcardFixture::Write, "1");
let mut writer = start_at(binary);
mount(&mut writer, &image, "create", "read_write");
launch(&mut writer, &write, "persistent");
oracle(&mut writer, 101);
assert_eq!(writer.ok("get_memcard_state", json!({}))["dirty"], false);
writer.close();
for version in ["1", "2"] {
let read = card(MemcardFixture::ReadWithPresentation, version);
let mut reader = start_at(binary);
mount(&mut reader, &image, "open", "read_write");
launch(&mut reader, &read, "persistent");
let booted = reader.ok("get_state", json!({}));
assert_eq!(booted["pc"], 0);
assert_eq!(booted["tickIndex"], 0);
assert_eq!(booted["logicalFrameIndex"], 0);
// Exactly one command owns the first frame; there is no oracle retry.
let advanced = reader.ok("advance", json!({"frames":1}));
assert_eq!(advanced, json!({"requested":1,"completed":1,"stop":"completed"}));
let state = reader.ok("get_state", json!({}));
assert_eq!(state["logicalFrameIndex"], 1);
assert_eq!(state["tickIndex"], 2);
assert_eq!(state["status"], "paused");
assert_eq!(state["appId"], 4294967295u32);
assert_eq!(state["stackTop"].as_array().unwrap().last().unwrap()["value"], "201");
assert_eq!(reader.ok("get_fault", json!({})), Value::Null);
let media = reader.ok("get_memcard_state", json!({}));
assert_eq!(
media["request"],
Value::Null,
"presentation must finish without a payload save"
);
assert_eq!(media["io"]["active"], false);
assert_eq!(media["dirty"], false);
assert_eq!(reader.ok("capture", json!({}))["logicalFrameIndex"], 1);
reader.close();
}
// Preserve the original reader's independent read-without-writing oracle.
let bytes = fs::read(&image).unwrap();
let read = card(MemcardFixture::Read, "2");
let mut reader = start_at(binary);
mount(&mut reader, &image, "open", "read_write");
launch(&mut reader, &read, "persistent");
oracle(&mut reader, 201);
reader.close();
assert_eq!(fs::read(&image).unwrap(), bytes);
}
#[test]
fn memcard_reopen_presentation_completes_exactly_one_first_frame() {
presentation_reopen(Path::new(env!("CARGO_BIN_EXE_prometeu")));
}
#[test]
fn memcard_public_distinct_process_save_readback_and_version_identity() {
persistence(Path::new(env!("CARGO_BIN_EXE_prometeu")));
@@ -0,0 +1,123 @@
---
id: LSN-0076
ticket: headless-memcard-reopen-io-progress
title: Native IO progress is not machine progress
created: 2026-11-10
tags: [headless, memcard, testing, ownership]
---
## Context and published result
The headless owner now waits for native progress when a successful memcard
bootstrap hook is still blocked on its queued or running publication. The wait
stays outside machine ticks and inside the original frame advance. Ordinary
asynchronous gameplay commits continue independently of this coordination.
Historical source: accepted DEC-0071, implemented through PLN-0202 from AGD-0075.
The canonical contracts are [Save Memory and MEMCARD](../../../docs/specs/runtime/08-save-memory-and-memcard.md),
[Headless Control](../../../docs/specs/runtime/11-portability-and-cross-platform-execution.md#131-control-contract)
and [Memcard Controls](../../../docs/specs/runtime/11a-headless-automation-protocol.md#memcard-controls).
This lesson explains the published result rather than defining a new policy.
## A tick watchdog can measure attempts without measuring useful work
An owner can repeatedly call firmware while an execution gate returns before
the VM advances. In the original incident, 100,000 firmware attempts left the
guest at logical frame zero and VM tick two, with native presentation IO pending.
The host watchdog correctly reported exhausted attempts; that observation did
not establish excessive guest instructions or a guest fault.
Increasing a guest budget would have changed the wrong quantity. The useful
question is which dependency prevents progress, which owner can observe it,
and which deadline governs it. Here the synchronous host owns the frame request,
while an asynchronous storage worker owns the publication and its resources.
## Wait on the execution dependency, not every active worker
The query follows the active GameRunning task's session: its bootstrap hook
completed successfully, the memcard session still blocks execution, and native IO
remains owned. That excludes an ordinary gameplay save whose caller can continue
executing while storage works in parallel.
This distinction is operationally observable. A channel-controlled gameplay
commit remains active while the guest completes its next frame. A bootstrap
publication under the same kind of hold prevents the first frame until the
worker returns or native supervision requests external action.
## Notification ordering and clocks solve different problems
The owner reads a fresh lane progress stamp before every dependency observation
and native poll. It then waits for actual progress, in requested intervals of at
most 5 ms. Reusing a stamp indefinitely after another job finishes would turn
later waits into immediate returns even while the relevant publication remains
pending. A wake only permits another observation; it is not proof of success.
The request keeps its native deadlines from admission: cancellation at 500 ms
and stop/escalation at 1 s. A separate owner guard expires 2 s after the first wait
admission within that advance and never resets on wakes or reentry. Native
action-required boundaries take precedence over that guard. Explicit-instant
tests qualify the guard; actual blocked storage reaches native supervision first.
Machine execution keeps its 100,000 firmware-tick watchdog. Polling and waiting
do not add simulated ticks, frames, input or instruction work. The frame request
is neither replayed nor moved into boot.
## Native supervision should return before another guest tick
While the bootstrap dependency remains held, the owner polls native work without
executing another firmware tick. This lets it observe an unavailable card or
restart requirement before allowing guest execution to proceed. The controlled
failure case asserts zero completed frames, a paused guest and no fabricated
VM fault.
Timeout and cessation remain separate. A blocked native operation can require
external action while its worker still owns the file lock. Returning from an
advance does not free that lock or its buffers. The integration test verifies
ownership while the operation is held, then explicitly permits safe worker
return before cleanup.
## A reader can publish metadata without saving its own answer
The previous neutral reader intentionally imported no presentation or commit
operation. That is a strong readback oracle: correct payload plus an unchanged
whole image. It also leaves presentation during reopened bootstrap untested.
An additional neutral reader supplies presentation in its hook and verifies the
existing bytes 0, 127, 128 and 255 without a slot write or payload commit. Its
metadata publication is intentional. A distinct-process test sends exactly one
first advance, checks its frame/tick state and captures the canonical game frame.
The original no-presentation reader separately retains the whole-image oracle.
## Optimized and debug execution expose different scheduling windows
The original installed probe failed intermittently in two of nineteen fresh
processes. The controlled storage test establishes entry into the relevant write
using a channel, holds it while observing the owner, and then permits completion.
The old optimized host expired its tick watchdog while that write was held.
The slower debug host could already let it finish before exhausting attempts.
The [pre-fix release failure](evidence/qualification/red-controlled-release.log)
and corrected [release qualification](evidence/qualification/release.log) preserve
that distinction. A green debug test alone would not have established the fix.
Control of the IO phase and optimized execution complement each other.
## Evidence and ownership boundary
The [qualification summary](evidence/summary.json) records 1,125 passing workspace
tests, 89 passing release tests, formatter and strict workspace clippy success,
and all four packaged automation cases passing against the exact extracted
macOS arm64 distribution. The generic workspace run has 16 ignored tests; the
four packaged cases were separately executed successfully. Other manual/device
and resource qualification cases remain ignored.
The [baseline](evidence/baseline/review-summary.json) preserves the nineteen
installed native probes and two original failure transcripts. Source deltas,
source/binary/archive/schema hashes, native logs and the selected stable install's
unchanged fingerprints remain in the qualification evidence. The archive is also
retained alongside its isolated installation.
The [runtime handoff](runtime-handoff.md) identifies the qualified executable for
the Studio owner. This delivery executes only provider tests with runtime-owned
PBX/ABI fixtures. Studio/game builds and the consumer's Zelda/UI/MCP acceptance
remain with that owner. Qualification is macOS arm64, not a cross-platform,
physical power-cut or device-latency certification.
@@ -0,0 +1,485 @@
{
"hello": {
"capabilities": [
"boot",
"reset",
"set_input",
"clear_input",
"advance",
"capture",
"get_state",
"get_fault",
"log_read",
"cancel",
"shutdown",
"memcard",
"memcard_mount",
"memcard_unmount",
"get_memcard_state",
"memcard_reconcile",
"memcard_continue_in_memory"
],
"limits": {
"callTimeoutMs": 60000,
"handshakeTimeoutMs": 5000,
"maxCommandBytes": 65536,
"maxFrames": 600,
"maxResponseBytes": 33554432,
"shutdownTimeoutMs": 5000
},
"protocolVersion": {
"major": 1,
"minor": 2
},
"runtimeVersion": "0.1.0",
"sessionId": "51e29382483fa5aea3c9318bb6f4a33b",
"type": "hello"
},
"observations": [
{
"request": {
"requestId": "1",
"command": "initialize",
"params": {
"protocolVersion": {
"major": 1,
"minor": 2
},
"requiredCapabilities": [
"memcard",
"log_read"
]
}
},
"response": {
"requestId": "1",
"result": {
"capabilities": [
"boot",
"reset",
"set_input",
"clear_input",
"advance",
"capture",
"get_state",
"get_fault",
"log_read",
"cancel",
"shutdown",
"memcard",
"memcard_mount",
"memcard_unmount",
"get_memcard_state",
"memcard_reconcile",
"memcard_continue_in_memory"
],
"protocolVersion": {
"major": 1,
"minor": 2
}
},
"sessionId": "51e29382483fa5aea3c9318bb6f4a33b",
"type": "response"
}
},
{
"request": {
"requestId": "2",
"command": "memcard_mount",
"params": {
"path": "/var/folders/0t/tfsqc14j5wbgh9h4s4dytwb00000gq/T/pln172-native-reopen-8ipr560i/owned-copy.pmc",
"action": "open",
"access": "read_write"
}
},
"response": {
"requestId": "2",
"result": {
"dirty": false,
"dirtySlots": [],
"io": {
"active": false,
"deferred": false,
"phase": "idle"
},
"media": {
"access": "read_write",
"cardId": "c0e20cf55f4661f7298054098c710b2d",
"degraded": false,
"error": null,
"mountEpoch": "0",
"path": "/var/folders/0t/tfsqc14j5wbgh9h4s4dytwb00000gq/T/pln172-native-reopen-8ipr560i/owned-copy.pmc",
"preparation": "ready",
"recovered": false,
"writeBlocked": false
},
"recovery": {
"reconciliationRequired": false,
"removalPending": false,
"restartRequired": false
},
"request": null,
"session": {
"actionRequired": false,
"appId": null,
"bootAttempted": false,
"bootPhase": "idle",
"choice": null,
"mode": null,
"resident": false
}
},
"sessionId": "51e29382483fa5aea3c9318bb6f4a33b",
"type": "response"
}
},
{
"request": {
"requestId": "3",
"command": "boot",
"params": {
"path": "/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/studio/discussion/workflow/plans/evidence/PLN-0172/native-reopen-watchdog/reader-cartridge",
"memcardChoice": "persistent"
}
},
"response": {
"requestId": "3",
"result": {
"appId": 2137977836,
"logicalFrameIndex": 0,
"pc": 0,
"stackTop": [],
"status": "running",
"tickIndex": 0
},
"sessionId": "51e29382483fa5aea3c9318bb6f4a33b",
"type": "response"
}
},
{
"request": {
"requestId": "4",
"command": "get_logs",
"params": {
"afterSequence": null,
"limit": 128
}
},
"response": {
"requestId": "4",
"result": {
"events": [
{
"appId": null,
"frame": 0,
"level": "info",
"message": "PrometeuOS starting...",
"sequence": 0,
"source": "pos",
"tag": 0,
"timestampMs": 0
},
{
"appId": null,
"frame": 0,
"level": "info",
"message": "Firmware Reset",
"sequence": 1,
"source": "pos",
"tag": 0,
"timestampMs": 2
},
{
"appId": null,
"frame": 0,
"level": "info",
"message": "Launching Hub",
"sequence": 2,
"source": "pos",
"tag": 0,
"timestampMs": 2
},
{
"appId": null,
"frame": 0,
"level": "info",
"message": "Loading cartridge: zelda1",
"sequence": 3,
"source": "pos",
"tag": 0,
"timestampMs": 6
},
{
"appId": null,
"frame": 0,
"level": "info",
"message": "Entering GameRunning",
"sequence": 4,
"source": "pos",
"tag": 0,
"timestampMs": 30
}
],
"gap": false,
"logEpoch": 0,
"newestSequence": 4,
"nextAfterSequence": 4,
"oldestSequence": 0,
"overflow": false,
"sessionId": "51e29382483fa5aea3c9318bb6f4a33b"
},
"sessionId": "51e29382483fa5aea3c9318bb6f4a33b",
"type": "response"
}
},
{
"request": {
"requestId": "5",
"command": "advance",
"params": {
"frames": 1
}
},
"response": {
"requestId": "5",
"result": {
"completed": 0,
"error": {
"code": "watchdog_expired",
"details": {
"hostTickLimit": 100000
},
"message": "headless host frame-advance watchdog expired after 100000 firmware ticks"
},
"requested": 1,
"stop": "host_error"
},
"sessionId": "51e29382483fa5aea3c9318bb6f4a33b",
"type": "response"
}
},
{
"request": {
"requestId": "6",
"command": "get_state",
"params": {}
},
"response": {
"requestId": "6",
"result": {
"appId": 2137977836,
"logicalFrameIndex": 0,
"pc": 233,
"stackTop": [
{
"kind": "int32",
"value": 0
}
],
"status": "paused",
"tickIndex": 2
},
"sessionId": "51e29382483fa5aea3c9318bb6f4a33b",
"type": "response"
}
},
{
"request": {
"requestId": "7",
"command": "get_fault",
"params": {}
},
"response": {
"requestId": "7",
"result": null,
"sessionId": "51e29382483fa5aea3c9318bb6f4a33b",
"type": "response"
}
},
{
"request": {
"requestId": "8",
"command": "get_memcard_state",
"params": {}
},
"response": {
"requestId": "8",
"result": {
"dirty": false,
"dirtySlots": [],
"io": {
"active": true,
"deferred": false,
"phase": "running"
},
"media": {
"access": "read_write",
"cardId": "c0e20cf55f4661f7298054098c710b2d",
"degraded": false,
"error": null,
"mountEpoch": "1",
"path": "/var/folders/0t/tfsqc14j5wbgh9h4s4dytwb00000gq/T/pln172-native-reopen-8ipr560i/owned-copy.pmc",
"preparation": "ready",
"recovered": false,
"writeBlocked": false
},
"recovery": {
"reconciliationRequired": false,
"removalPending": false,
"restartRequired": false
},
"request": {
"id": "1",
"operation": "presentation",
"reason": "none",
"retained": false,
"slot": null,
"state": "pending",
"storageError": null
},
"session": {
"actionRequired": false,
"appId": 2137977836,
"bootAttempted": true,
"bootPhase": "running",
"choice": "persistent",
"mode": "persistent",
"resident": true
}
},
"sessionId": "51e29382483fa5aea3c9318bb6f4a33b",
"type": "response"
}
},
{
"request": {
"requestId": "9",
"command": "get_logs",
"params": {
"afterSequence": null,
"limit": 128
}
},
"response": {
"requestId": "9",
"result": {
"events": [
{
"appId": null,
"frame": 0,
"level": "info",
"message": "PrometeuOS starting...",
"sequence": 0,
"source": "pos",
"tag": 0,
"timestampMs": 0
},
{
"appId": null,
"frame": 0,
"level": "info",
"message": "Firmware Reset",
"sequence": 1,
"source": "pos",
"tag": 0,
"timestampMs": 2
},
{
"appId": null,
"frame": 0,
"level": "info",
"message": "Launching Hub",
"sequence": 2,
"source": "pos",
"tag": 0,
"timestampMs": 2
},
{
"appId": null,
"frame": 0,
"level": "info",
"message": "Loading cartridge: zelda1",
"sequence": 3,
"source": "pos",
"tag": 0,
"timestampMs": 6
},
{
"appId": null,
"frame": 0,
"level": "info",
"message": "Entering GameRunning",
"sequence": 4,
"source": "pos",
"tag": 0,
"timestampMs": 30
}
],
"gap": false,
"logEpoch": 0,
"newestSequence": 4,
"nextAfterSequence": 4,
"oldestSequence": 0,
"overflow": false,
"sessionId": "51e29382483fa5aea3c9318bb6f4a33b"
},
"sessionId": "51e29382483fa5aea3c9318bb6f4a33b",
"type": "response"
}
},
{
"request": {
"requestId": "10",
"command": "shutdown",
"params": {}
},
"response": {
"requestId": "10",
"result": {
"closed": true,
"memcard": {
"dirty": false,
"dirtySlots": [],
"io": {
"active": false,
"deferred": false,
"phase": "idle"
},
"media": {
"access": "read_write",
"cardId": "c0e20cf55f4661f7298054098c710b2d",
"degraded": false,
"error": null,
"mountEpoch": "1",
"path": "/var/folders/0t/tfsqc14j5wbgh9h4s4dytwb00000gq/T/pln172-native-reopen-8ipr560i/owned-copy.pmc",
"preparation": "ready",
"recovered": false,
"writeBlocked": false
},
"recovery": {
"reconciliationRequired": false,
"removalPending": false,
"restartRequired": false
},
"request": null,
"session": {
"actionRequired": false,
"appId": 2137977836,
"bootAttempted": true,
"bootPhase": "running",
"choice": "persistent",
"mode": "persistent",
"resident": true
}
}
},
"sessionId": "51e29382483fa5aea3c9318bb6f4a33b",
"type": "response"
}
}
],
"exitCode": 0,
"headlessSha256": "e5e9571e7ab42724af37294c79b19478a1e1b5a71df177eee7141d42e042f6f4",
"advanceCommands": 1,
"scope": "Native-only probe; temporary copy of fixture card; no Studio consumer and no advance retry."
}
@@ -0,0 +1,485 @@
{
"hello": {
"capabilities": [
"boot",
"reset",
"set_input",
"clear_input",
"advance",
"capture",
"get_state",
"get_fault",
"log_read",
"cancel",
"shutdown",
"memcard",
"memcard_mount",
"memcard_unmount",
"get_memcard_state",
"memcard_reconcile",
"memcard_continue_in_memory"
],
"limits": {
"callTimeoutMs": 60000,
"handshakeTimeoutMs": 5000,
"maxCommandBytes": 65536,
"maxFrames": 600,
"maxResponseBytes": 33554432,
"shutdownTimeoutMs": 5000
},
"protocolVersion": {
"major": 1,
"minor": 2
},
"runtimeVersion": "0.1.0",
"sessionId": "9b96872c8a5c0a2d66543d4f7ff90acf",
"type": "hello"
},
"observations": [
{
"request": {
"requestId": "1",
"command": "initialize",
"params": {
"protocolVersion": {
"major": 1,
"minor": 2
},
"requiredCapabilities": [
"memcard",
"log_read"
]
}
},
"response": {
"requestId": "1",
"result": {
"capabilities": [
"boot",
"reset",
"set_input",
"clear_input",
"advance",
"capture",
"get_state",
"get_fault",
"log_read",
"cancel",
"shutdown",
"memcard",
"memcard_mount",
"memcard_unmount",
"get_memcard_state",
"memcard_reconcile",
"memcard_continue_in_memory"
],
"protocolVersion": {
"major": 1,
"minor": 2
}
},
"sessionId": "9b96872c8a5c0a2d66543d4f7ff90acf",
"type": "response"
}
},
{
"request": {
"requestId": "2",
"command": "memcard_mount",
"params": {
"path": "/var/folders/0t/tfsqc14j5wbgh9h4s4dytwb00000gq/T/pln172-native-reopen-hyqvb7jv/owned-copy.pmc",
"action": "open",
"access": "read_write"
}
},
"response": {
"requestId": "2",
"result": {
"dirty": false,
"dirtySlots": [],
"io": {
"active": false,
"deferred": false,
"phase": "idle"
},
"media": {
"access": "read_write",
"cardId": "c0e20cf55f4661f7298054098c710b2d",
"degraded": false,
"error": null,
"mountEpoch": "0",
"path": "/var/folders/0t/tfsqc14j5wbgh9h4s4dytwb00000gq/T/pln172-native-reopen-hyqvb7jv/owned-copy.pmc",
"preparation": "ready",
"recovered": false,
"writeBlocked": false
},
"recovery": {
"reconciliationRequired": false,
"removalPending": false,
"restartRequired": false
},
"request": null,
"session": {
"actionRequired": false,
"appId": null,
"bootAttempted": false,
"bootPhase": "idle",
"choice": null,
"mode": null,
"resident": false
}
},
"sessionId": "9b96872c8a5c0a2d66543d4f7ff90acf",
"type": "response"
}
},
{
"request": {
"requestId": "3",
"command": "boot",
"params": {
"path": "/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/studio/discussion/workflow/plans/evidence/PLN-0172/native-reopen-watchdog/reader-cartridge",
"memcardChoice": "persistent"
}
},
"response": {
"requestId": "3",
"result": {
"appId": 2137977836,
"logicalFrameIndex": 0,
"pc": 0,
"stackTop": [],
"status": "running",
"tickIndex": 0
},
"sessionId": "9b96872c8a5c0a2d66543d4f7ff90acf",
"type": "response"
}
},
{
"request": {
"requestId": "4",
"command": "get_logs",
"params": {
"afterSequence": null,
"limit": 128
}
},
"response": {
"requestId": "4",
"result": {
"events": [
{
"appId": null,
"frame": 0,
"level": "info",
"message": "PrometeuOS starting...",
"sequence": 0,
"source": "pos",
"tag": 0,
"timestampMs": 0
},
{
"appId": null,
"frame": 0,
"level": "info",
"message": "Firmware Reset",
"sequence": 1,
"source": "pos",
"tag": 0,
"timestampMs": 1
},
{
"appId": null,
"frame": 0,
"level": "info",
"message": "Launching Hub",
"sequence": 2,
"source": "pos",
"tag": 0,
"timestampMs": 1
},
{
"appId": null,
"frame": 0,
"level": "info",
"message": "Loading cartridge: zelda1",
"sequence": 3,
"source": "pos",
"tag": 0,
"timestampMs": 4
},
{
"appId": null,
"frame": 0,
"level": "info",
"message": "Entering GameRunning",
"sequence": 4,
"source": "pos",
"tag": 0,
"timestampMs": 29
}
],
"gap": false,
"logEpoch": 0,
"newestSequence": 4,
"nextAfterSequence": 4,
"oldestSequence": 0,
"overflow": false,
"sessionId": "9b96872c8a5c0a2d66543d4f7ff90acf"
},
"sessionId": "9b96872c8a5c0a2d66543d4f7ff90acf",
"type": "response"
}
},
{
"request": {
"requestId": "5",
"command": "advance",
"params": {
"frames": 1
}
},
"response": {
"requestId": "5",
"result": {
"completed": 0,
"error": {
"code": "watchdog_expired",
"details": {
"hostTickLimit": 100000
},
"message": "headless host frame-advance watchdog expired after 100000 firmware ticks"
},
"requested": 1,
"stop": "host_error"
},
"sessionId": "9b96872c8a5c0a2d66543d4f7ff90acf",
"type": "response"
}
},
{
"request": {
"requestId": "6",
"command": "get_state",
"params": {}
},
"response": {
"requestId": "6",
"result": {
"appId": 2137977836,
"logicalFrameIndex": 0,
"pc": 233,
"stackTop": [
{
"kind": "int32",
"value": 0
}
],
"status": "paused",
"tickIndex": 2
},
"sessionId": "9b96872c8a5c0a2d66543d4f7ff90acf",
"type": "response"
}
},
{
"request": {
"requestId": "7",
"command": "get_fault",
"params": {}
},
"response": {
"requestId": "7",
"result": null,
"sessionId": "9b96872c8a5c0a2d66543d4f7ff90acf",
"type": "response"
}
},
{
"request": {
"requestId": "8",
"command": "get_memcard_state",
"params": {}
},
"response": {
"requestId": "8",
"result": {
"dirty": false,
"dirtySlots": [],
"io": {
"active": true,
"deferred": false,
"phase": "running"
},
"media": {
"access": "read_write",
"cardId": "c0e20cf55f4661f7298054098c710b2d",
"degraded": false,
"error": null,
"mountEpoch": "1",
"path": "/var/folders/0t/tfsqc14j5wbgh9h4s4dytwb00000gq/T/pln172-native-reopen-hyqvb7jv/owned-copy.pmc",
"preparation": "ready",
"recovered": false,
"writeBlocked": false
},
"recovery": {
"reconciliationRequired": false,
"removalPending": false,
"restartRequired": false
},
"request": {
"id": "1",
"operation": "presentation",
"reason": "none",
"retained": false,
"slot": null,
"state": "pending",
"storageError": null
},
"session": {
"actionRequired": false,
"appId": 2137977836,
"bootAttempted": true,
"bootPhase": "running",
"choice": "persistent",
"mode": "persistent",
"resident": true
}
},
"sessionId": "9b96872c8a5c0a2d66543d4f7ff90acf",
"type": "response"
}
},
{
"request": {
"requestId": "9",
"command": "get_logs",
"params": {
"afterSequence": null,
"limit": 128
}
},
"response": {
"requestId": "9",
"result": {
"events": [
{
"appId": null,
"frame": 0,
"level": "info",
"message": "PrometeuOS starting...",
"sequence": 0,
"source": "pos",
"tag": 0,
"timestampMs": 0
},
{
"appId": null,
"frame": 0,
"level": "info",
"message": "Firmware Reset",
"sequence": 1,
"source": "pos",
"tag": 0,
"timestampMs": 1
},
{
"appId": null,
"frame": 0,
"level": "info",
"message": "Launching Hub",
"sequence": 2,
"source": "pos",
"tag": 0,
"timestampMs": 1
},
{
"appId": null,
"frame": 0,
"level": "info",
"message": "Loading cartridge: zelda1",
"sequence": 3,
"source": "pos",
"tag": 0,
"timestampMs": 4
},
{
"appId": null,
"frame": 0,
"level": "info",
"message": "Entering GameRunning",
"sequence": 4,
"source": "pos",
"tag": 0,
"timestampMs": 29
}
],
"gap": false,
"logEpoch": 0,
"newestSequence": 4,
"nextAfterSequence": 4,
"oldestSequence": 0,
"overflow": false,
"sessionId": "9b96872c8a5c0a2d66543d4f7ff90acf"
},
"sessionId": "9b96872c8a5c0a2d66543d4f7ff90acf",
"type": "response"
}
},
{
"request": {
"requestId": "10",
"command": "shutdown",
"params": {}
},
"response": {
"requestId": "10",
"result": {
"closed": true,
"memcard": {
"dirty": false,
"dirtySlots": [],
"io": {
"active": false,
"deferred": false,
"phase": "idle"
},
"media": {
"access": "read_write",
"cardId": "c0e20cf55f4661f7298054098c710b2d",
"degraded": false,
"error": null,
"mountEpoch": "1",
"path": "/var/folders/0t/tfsqc14j5wbgh9h4s4dytwb00000gq/T/pln172-native-reopen-hyqvb7jv/owned-copy.pmc",
"preparation": "ready",
"recovered": false,
"writeBlocked": false
},
"recovery": {
"reconciliationRequired": false,
"removalPending": false,
"restartRequired": false
},
"request": null,
"session": {
"actionRequired": false,
"appId": 2137977836,
"bootAttempted": true,
"bootPhase": "running",
"choice": "persistent",
"mode": "persistent",
"resident": true
}
}
},
"sessionId": "9b96872c8a5c0a2d66543d4f7ff90acf",
"type": "response"
}
}
],
"exitCode": 0,
"headlessSha256": "e5e9571e7ab42724af37294c79b19478a1e1b5a71df177eee7141d42e042f6f4",
"advanceCommands": 1,
"scope": "Native-only probe; temporary copy of fixture card; no Studio consumer and no advance retry."
}
@@ -0,0 +1,8 @@
Compiling prometeu-host-headless v0.1.0 (/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/host/prometeu-host-headless)
Finished `test` profile [unoptimized + debuginfo] target(s) in 2.30s
Running unittests src/lib.rs (target/debug/deps/prometeu_host_headless-34e7d78b76b56071)
running 1 test
test host::memcard::tests::first_reopen_frame_waits_for_controlled_presentation_without_replaying ... ok
test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 18 filtered out; finished in 0.38s
@@ -0,0 +1,3 @@
Checking prometeu-host-headless v0.1.0 (/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/host/prometeu-host-headless)
Checking prometeu-cli v0.1.0 (/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/tools/prometeu-cli)
Finished `dev` profile [unoptimized + debuginfo] target(s) in 3.58s
@@ -0,0 +1,38 @@
building artifacts:
prometeu-cli-aarch64-apple-darwin.zip
prometeu-cli-aarch64-apple-darwin.zip.sha256
prometeu-host-desktop-winit-aarch64-apple-darwin.zip
prometeu-host-desktop-winit-aarch64-apple-darwin.zip.sha256
pbxgen-dummy-boy-aarch64-apple-darwin.zip
pbxgen-dummy-boy-aarch64-apple-darwin.zip.sha256
pbxgen-stress-aarch64-apple-darwin.zip
pbxgen-stress-aarch64-apple-darwin.zip.sha256
building aarch64-apple-darwin target, using cargo profile dist --workspace)
Compiling prometeu-host-headless v0.1.0 (/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/host/prometeu-host-headless)
Compiling prometeu-test-support v0.1.0 (/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/dev/prometeu-test-support)
Compiling prometeu-cli v0.1.0 (/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/tools/prometeu-cli)
Finished `dist` profile [optimized] target(s) in 42.70s
announcing v0.1.0
prometeu-cli 0.1.0
/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/target/distrib/prometeu-cli-aarch64-apple-darwin.zip
[bin] prometeu
[bin] prometeu-headless
[bin] prometeu-runtime
[misc] 11a-headless-automation-protocol.md, LICENSE, README.md, headless-protocol
[checksum] /Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/target/distrib/prometeu-cli-aarch64-apple-darwin.zip.sha256
prometeu-host-desktop-winit 0.1.0
/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/target/distrib/prometeu-host-desktop-winit-aarch64-apple-darwin.zip
[bin] prometeu-host-desktop-winit
[misc] LICENSE, README.md, VERSION.txt
[checksum] /Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/target/distrib/prometeu-host-desktop-winit-aarch64-apple-darwin.zip.sha256
pbxgen-dummy-boy 0.1.0
/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/target/distrib/pbxgen-dummy-boy-aarch64-apple-darwin.zip
[bin] pbxgen-dummy-boy
[misc] LICENSE, README.md
[checksum] /Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/target/distrib/pbxgen-dummy-boy-aarch64-apple-darwin.zip.sha256
pbxgen-stress 0.1.0
/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/target/distrib/pbxgen-stress-aarch64-apple-darwin.zip
[bin] pbxgen-stress
[misc] LICENSE, README.md
[checksum] /Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/target/distrib/pbxgen-stress-aarch64-apple-darwin.zip.sha256
@@ -0,0 +1,17 @@
{
"builder": "cargo-dist 0.30.3",
"target": "aarch64-apple-darwin",
"profile": "dist",
"archive": "/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/target/distrib/prometeu-cli-aarch64-apple-darwin.zip",
"archiveSha256": "05b0e38f797bc6d24cd69aeb7f6cad9ae224cb2308390a084634dfebe5e8f2f7",
"installation": "/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/dist-staging/qualification/PLN-0202",
"installedSha256": {
"prometeu": "bb245dd057bbc910053b63c55b75a573ab4e9c9a02b7c79ba89e659bea8e85c3",
"prometeu-runtime": "ee00a587eb48030d1455d3c9bedd784ab620309a09877b50fe3641ae502635df",
"prometeu-headless": "18423f798ab28bbd38c12a7ee46459f3ef3d08876cc64327952f57be041fc5df",
"headless-protocol/request.schema.json": "554960a1c6c1304da32753937b899b51ac658cae4b9d96927f5a384325ce2ae2",
"headless-protocol/response.schema.json": "7a8a0fe70a6864203b771e0564dc4227b768213d2368c5b162c892c55c5e186b",
"11a-headless-automation-protocol.md": "2c5391fdbeb35964717f2af1f994b5c81b1b4278641fece17ccdc3fb6b766a6e"
},
"retainedArchive": "/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/dist-staging/qualification/PLN-0202/prometeu-cli-aarch64-apple-darwin.zip"
}
@@ -0,0 +1,4 @@
{
"workflowMentions": [],
"brokenLessonLinks": []
}
@@ -0,0 +1,673 @@
use std::fmt;
use std::sync::Arc;
use prometeu_drivers::hardware::Hardware;
use prometeu_drivers::{ControlledWallClock, MemoryBanks};
use prometeu_firmware::firmware_state::{AppCrashesStep, ResetStep};
use prometeu_firmware::{BootTarget, Firmware, FirmwareState};
use prometeu_hal::{
AssetBridge, AudioBridge, FrameId, Game2DFrameComposer, InputPlatform, InputSignals,
OwnedRgba8888Frame, RenderBackend, RenderSubmission, RenderSubmissionSink, RenderSubmitError,
RuntimePlatform, TelemetryPlatform, WallClock,
};
use prometeu_system::{CrashReport, LatestRenderFrameStore};
#[path = "memcard.rs"]
mod memcard;
pub use memcard::{
MediaAccess, MediaAction, MemcardChoice, MemcardFailure, MemcardMount, MemcardState,
PendingWrites, TeardownPolicy,
};
const BOOT_TICK_LIMIT: usize = 5000;
const HOST_FRAME_ADVANCE_TICK_LIMIT: usize = 100_000;
/// One published logical frame plus the automation counter.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CapturedFrame {
pub logical_frame_index: u64,
pub frame: OwnedRgba8888Frame,
}
/// Debugger-shaped execution snapshot.
#[derive(Debug, Clone)]
pub struct HostState {
pub pc: usize,
pub stack_top: prometeu_hal::ValueSnapshot,
pub frame_index: u64,
pub tick_index: u64,
pub app_id: u32,
pub status: HostExecutionStatus,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum HostExecutionStatus {
Running,
Paused,
Terminated,
Faulted,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum AdvanceFrameOutcome {
FrameCompleted { logical_frame_index: u64, frame_id: FrameId },
Faulted(CrashReport),
Terminated,
ActionRequired,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum AdvanceFramesStop {
Completed,
Faulted(CrashReport),
Terminated,
ActionRequired,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct AdvanceFramesOutcome {
pub requested: u64,
pub completed: u64,
pub stop: AdvanceFramesStop,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum HostError {
Memcard(Box<MemcardFailure>),
AlreadyBooted,
BootFailed { reason: String, report: Option<Box<CrashReport>> },
InvalidState { operation: &'static str, status: HostExecutionStatus },
FrameAdvanceWatchdogExpired { host_tick_limit: usize },
FrameNotPublished { previous: Option<FrameId> },
NoFrameAvailable,
}
impl fmt::Display for HostError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::Memcard(error) => write!(f, "{}: {}", error.operation, error.reason),
Self::AlreadyBooted => write!(f, "boot requires reset before another attempt"),
Self::BootFailed { reason, .. } => write!(f, "boot failed: {reason}"),
Self::InvalidState { operation, status } => {
write!(f, "{operation} is invalid while execution is {status:?}")
}
Self::FrameAdvanceWatchdogExpired { host_tick_limit } => {
write!(
f,
"headless host frame-advance watchdog expired after {host_tick_limit} firmware ticks"
)
}
Self::FrameNotPublished { .. } => {
write!(f, "logical frame closed without its canonical published frame")
}
Self::NoFrameAvailable => write!(f, "no completed frame is available for capture"),
}
}
}
impl std::error::Error for HostError {}
/// In-process host. The desktop winit runner is a separate crate and is not linked here.
pub struct HeadlessHost {
firmware: Firmware,
platform: HeadlessPlatform,
signals: InputSignals,
boot_attempted: bool,
last_completed_frame: Option<CompletedFrame>,
controlled_wall_clock: Option<Arc<ControlledWallClock>>,
media: memcard::MediaSelection,
}
#[derive(Debug, Clone, Copy)]
struct CompletedFrame {
logical_frame_index: u64,
frame_id: FrameId,
}
struct HeadlessPlatform {
hardware: Hardware,
store: LatestRenderFrameStore,
}
impl HeadlessHost {
/// Install storage through the shared worker. Progress is driven by ordinary host ticks.
pub fn install_memcard(
&mut self,
storage: Box<dyn prometeu_hal::memcard::MemcardStorage>,
) -> prometeu_system::memcard::image::Result<()> {
self.firmware.os.memcard().mount_card(storage)
}
pub fn memcard_preparation(&mut self) -> prometeu_system::memcard::admission::PreparationState {
self.firmware.os.memcard().admission.state
}
pub fn new() -> Self {
let clock = Arc::new(ControlledWallClock::default());
Self::with_clock(clock.clone(), Some(clock))
}
/// Supply a host-owned civil clock. The caller retains control of this provider.
pub fn new_with_wall_clock(clock: Arc<dyn WallClock>) -> Self {
Self::with_clock(clock, None)
}
fn with_clock(
clock: Arc<dyn WallClock>,
controlled_wall_clock: Option<Arc<ControlledWallClock>>,
) -> Self {
let memory_banks = Arc::new(MemoryBanks::new());
let hardware = Hardware::new_with_memory_banks(Arc::clone(&memory_banks), clock);
let store = LatestRenderFrameStore::default();
Self {
firmware: Firmware::new(None),
platform: HeadlessPlatform { hardware, store },
signals: InputSignals::default(),
boot_attempted: false,
last_completed_frame: None,
controlled_wall_clock,
media: Default::default(),
}
}
/// Read the same clock supplied to the runtime platform.
pub fn wall_clock(&self) -> &dyn WallClock {
self.platform.wall_clock()
}
/// Native controls for the default clock; custom providers are controlled by their owner.
pub fn controlled_wall_clock(&self) -> Option<&ControlledWallClock> {
self.controlled_wall_clock.as_deref()
}
/// Observe native log history without advancing, draining or changing lifecycle.
pub fn log_snapshot(
&self,
after: Option<u64>,
limit: usize,
) -> (Vec<prometeu_hal::log::LogEvent>, Option<u64>, Option<u64>) {
self.firmware.os.log_snapshot(after, limit)
}
/// Load `path` and tick until the firmware is in `GameRunning`.
///
/// The transition into `GameRunning` is the last tick. The first game
/// logical frame stays available for [`Self::advance_frame`].
pub fn boot(&mut self, path: impl Into<String>) -> Result<(), HostError> {
self.boot_with_choice(path, None)
}
pub fn boot_with_memcard_choice(
&mut self,
path: impl Into<String>,
choice: prometeu_system::memcard::admission::Choice,
) -> Result<(), HostError> {
self.boot_with_choice(path, Some(choice))
}
fn boot_with_choice(
&mut self,
path: impl Into<String>,
choice: Option<prometeu_system::memcard::admission::Choice>,
) -> Result<(), HostError> {
if self.boot_attempted {
return Err(HostError::AlreadyBooted);
}
self.boot_attempted = true;
self.media.choice = choice;
self.media.boot_phase = "loading";
let path = path.into();
self.firmware.boot_target = BootTarget::Cartridge { path, debug: false, debug_port: 7777 };
let boot_deadline = std::time::Instant::now() + std::time::Duration::from_secs(5);
let mut choice_submitted = false;
for _ in 0..BOOT_TICK_LIMIT {
if matches!(self.firmware.state, FirmwareState::GameRunning(_)) {
self.media.boot_phase = "running";
return Ok(());
}
if matches!(self.firmware.state, FirmwareState::AppCrashes(_)) {
self.media.boot_phase = "failed";
let report = self.get_fault();
let reason = report
.as_ref()
.map(CrashReport::summary)
.unwrap_or_else(|| "cartridge crashed during boot".to_string());
return Err(HostError::BootFailed { reason, report: report.map(Box::new) });
}
if matches!(self.firmware.state, FirmwareState::HubHome(_)) {
self.media.boot_phase = "failed";
return Err(HostError::BootFailed {
reason: "cartridge did not load".to_string(),
report: None,
});
}
let progress = self.firmware.os.memcard().lane.progress_stamp();
if let FirmwareState::LoadCartridge(step) = &self.firmware.state
&& step.cartridge.memcard_slots.is_none()
&& choice.is_some()
{
self.media.boot_phase = "failed";
return Err(self.memcard_error("boot", "invalid_state"));
}
if choice_submitted
&& let prometeu_system::memcard::admission::PreparationState::Failed(error) =
self.firmware.os.memcard().admission.state
{
self.media.boot_phase = "failed";
return Err(self.memcard_error("boot", memcard::error_name(error)));
}
let waiting = matches!(&self.firmware.state,FirmwareState::LoadCartridge(step) if step.needs_memcard_choice());
if waiting {
let Some(choice) = choice else {
self.media.boot_phase = "choice_required";
return Err(self.memcard_error("boot", "choice_required"));
};
if self.firmware.os.memcard().preparation_active() {
self.poll_memcard();
self.firmware
.os
.memcard()
.lane
.wait_for_progress(progress, std::time::Duration::from_millis(5));
continue;
}
let created_at = self.platform.wall_clock().utc_unix_seconds();
let result = match &mut self.firmware.state {
FirmwareState::LoadCartridge(step) => {
step.choose_memcard(&mut self.firmware.os, choice, created_at)
}
_ => unreachable!(),
};
if let Err(error) = result {
self.media.boot_phase = "failed";
return Err(self.memcard_error("boot", memcard::error_name(error)));
}
choice_submitted = true;
self.media.boot_phase = "preparing";
}
self.tick_once();
self.signals = InputSignals::default();
if matches!(self.firmware.state, FirmwareState::LoadCartridge(_)) {
if std::time::Instant::now() >= boot_deadline {
break;
}
self.firmware
.os
.memcard()
.lane
.wait_for_progress(progress, std::time::Duration::from_millis(16));
}
}
if matches!(self.firmware.state, FirmwareState::GameRunning(_)) {
Ok(())
} else {
self.media.boot_phase = "failed";
Err(HostError::BootFailed {
reason: "boot did not reach the game".to_string(),
report: self.get_fault().map(Box::new),
})
}
}
pub fn reset(&mut self) -> Result<(), HostError> {
self.reset_with_policy(TeardownPolicy::default()).map(|_| ())
}
fn reset_inner(&mut self) {
self.signals = InputSignals::default();
self.firmware.change_state(
FirmwareState::Reset(ResetStep),
&self.signals,
&mut self.platform,
);
self.platform.store = LatestRenderFrameStore::default();
self.boot_attempted = false;
self.last_completed_frame = None;
}
pub fn pause(&mut self) -> Result<(), HostError> {
self.require_active("pause")?;
self.firmware.os.vm().set_paused(true);
Ok(())
}
pub fn resume(&mut self) -> Result<(), HostError> {
self.require_active("resume")?;
self.firmware.os.vm().set_paused(false);
Ok(())
}
/// Execute one VM instruction. This does not close a logical frame.
pub fn step(&mut self) -> Result<Option<CrashReport>, HostError> {
self.require_active("step")?;
self.firmware.os.vm().set_paused(true);
let report = self.firmware.os.vm().debug_step_active_session(&mut self.platform);
self.platform.hardware.audio.transport().consume_silently();
Ok(report)
}
pub fn advance_frame(&mut self) -> Result<AdvanceFrameOutcome, HostError> {
if let Some(report) = self.get_fault() {
return Ok(AdvanceFrameOutcome::Faulted(report));
}
if !matches!(self.firmware.state, FirmwareState::GameRunning(_)) {
return Ok(if self.host_action_required() {
AdvanceFrameOutcome::ActionRequired
} else {
AdvanceFrameOutcome::Terminated
});
}
let start = self.firmware.os.vm().logical_frame_index();
let previous_frame_id = self.platform.store.latest_frame().map(|frame| frame.frame_id);
self.firmware.os.vm().set_paused(false);
self.firmware.os.vm().request_debug_step();
for _ in 0..HOST_FRAME_ADVANCE_TICK_LIMIT {
// A controlled lifecycle slice can consume the runtime step marker
// without closing a logical frame. This operation still owns the
// request until its first frame or an explicit stop boundary.
self.firmware.os.vm().set_paused(false);
self.firmware.os.vm().request_debug_step();
self.tick_once();
if let Some(report) = self.get_fault() {
self.finish_frame_advance();
return Ok(AdvanceFrameOutcome::Faulted(report));
}
if !matches!(self.firmware.state, FirmwareState::GameRunning(_)) {
self.finish_frame_advance();
return Ok(if self.host_action_required() {
AdvanceFrameOutcome::ActionRequired
} else {
AdvanceFrameOutcome::Terminated
});
}
let logical_frame_index = self.firmware.os.vm().logical_frame_index();
if logical_frame_index > start {
self.finish_frame_advance();
let frame = self
.platform
.store
.latest_frame()
.ok_or(HostError::FrameNotPublished { previous: previous_frame_id })?;
if Some(frame.frame_id) == previous_frame_id {
return Err(HostError::FrameNotPublished { previous: previous_frame_id });
}
self.last_completed_frame =
Some(CompletedFrame { logical_frame_index, frame_id: frame.frame_id });
return Ok(AdvanceFrameOutcome::FrameCompleted {
logical_frame_index,
frame_id: frame.frame_id,
});
}
}
self.finish_frame_advance();
Err(HostError::FrameAdvanceWatchdogExpired {
host_tick_limit: HOST_FRAME_ADVANCE_TICK_LIMIT,
})
}
pub fn advance_frames(&mut self, count: u64) -> Result<AdvanceFramesOutcome, HostError> {
let mut completed = 0;
for _ in 0..count {
match self.advance_frame()? {
AdvanceFrameOutcome::FrameCompleted { .. } => completed += 1,
AdvanceFrameOutcome::Faulted(report) => {
return Ok(AdvanceFramesOutcome {
requested: count,
completed,
stop: AdvanceFramesStop::Faulted(report),
});
}
AdvanceFrameOutcome::Terminated => {
return Ok(AdvanceFramesOutcome {
requested: count,
completed,
stop: AdvanceFramesStop::Terminated,
});
}
AdvanceFrameOutcome::ActionRequired => {
return Ok(AdvanceFramesOutcome {
requested: count,
completed,
stop: AdvanceFramesStop::ActionRequired,
});
}
}
}
Ok(AdvanceFramesOutcome { requested: count, completed, stop: AdvanceFramesStop::Completed })
}
pub fn set_input(&mut self, signals: InputSignals) {
self.signals = signals;
}
pub fn clear_input(&mut self) {
self.signals = InputSignals::default();
}
pub fn set_right(&mut self, down: bool) {
self.signals.right_signal = down;
}
pub fn capture_frame(&self) -> Result<CapturedFrame, HostError> {
let completed = self.last_completed_frame.ok_or(HostError::NoFrameAvailable)?;
let frame = self.platform.store.latest_frame().ok_or(HostError::NoFrameAvailable)?;
if frame.frame_id != completed.frame_id {
return Err(HostError::FrameNotPublished { previous: Some(completed.frame_id) });
}
Ok(CapturedFrame { logical_frame_index: completed.logical_frame_index, frame })
}
pub fn get_state(&mut self) -> HostState {
let status = self.execution_status();
HostState {
pc: self.firmware.os.vm().active_pc().unwrap_or(0),
stack_top: self.firmware.os.vm().active_operand_stack_top(10),
frame_index: self.firmware.os.vm().logical_frame_index(),
tick_index: self.firmware.os.vm().tick_index(),
app_id: self.firmware.os.vm().current_app_id(),
status,
}
}
pub fn get_fault(&mut self) -> Option<CrashReport> {
if let Some(report) = self.firmware.os.vm().last_crash_report() {
return Some(report.clone());
}
match &self.firmware.state {
FirmwareState::AppCrashes(AppCrashesStep { report }) => Some(report.clone()),
_ => None,
}
}
fn tick_once(&mut self) {
self.firmware.tick(&self.signals, &mut self.platform);
self.platform.hardware.audio.transport().consume_silently();
}
fn execution_status(&mut self) -> HostExecutionStatus {
if self.fault_is_visible() {
HostExecutionStatus::Faulted
} else if self.host_action_required() {
HostExecutionStatus::Paused
} else if !matches!(self.firmware.state, FirmwareState::GameRunning(_)) {
HostExecutionStatus::Terminated
} else if self.firmware.os.vm().paused() {
HostExecutionStatus::Paused
} else {
HostExecutionStatus::Running
}
}
fn fault_is_visible(&mut self) -> bool {
self.firmware.os.vm().last_crash_report().is_some()
|| matches!(self.firmware.state, FirmwareState::AppCrashes(_))
}
fn require_active(&mut self, operation: &'static str) -> Result<(), HostError> {
let status = self.execution_status();
if matches!(status, HostExecutionStatus::Running | HostExecutionStatus::Paused)
&& !self.host_action_required()
{
Ok(())
} else {
Err(HostError::InvalidState { operation, status })
}
}
fn finish_frame_advance(&mut self) {
self.firmware.os.vm().set_paused(true);
self.firmware.os.vm().clear_debug_step_request();
}
}
impl Default for HeadlessHost {
fn default() -> Self {
Self::new()
}
}
#[cfg(all(test, feature = "resource-diagnostics"))]
#[path = "resource_qualification_tests.rs"]
mod resource_qualification_tests;
impl RenderSubmissionSink for HeadlessPlatform {
fn submit_render_submission(
&mut self,
submission: RenderSubmission,
) -> Result<(), RenderSubmitError> {
let frame_id = submission.frame_id;
let ownership = submission.ownership;
self.hardware.submit_render_submission(submission)?;
// Host dialogs use their own producer and may reuse FrameId::ZERO.
// Capture/advance observe only canonical game publications.
if ownership.app_mode != prometeu_hal::app_mode::AppMode::Game {
return Ok(());
}
let (width, height) = self.hardware.gfx.size();
let pixels = self.hardware.gfx.front_buffer().to_vec();
let frame = OwnedRgba8888Frame::packed(frame_id, ownership, width, height, pixels)
.map_err(|_| RenderSubmitError::SubmissionRejected)?;
self.store.publish_frame(frame);
Ok(())
}
}
impl RuntimePlatform for HeadlessPlatform {
fn wall_clock(&self) -> &dyn WallClock {
self.hardware.wall_clock()
}
fn display_size(&self) -> (usize, usize) {
(Hardware::W, Hardware::H)
}
fn render_submission_sink(&mut self) -> &mut dyn RenderSubmissionSink {
self
}
fn render_backend(&mut self) -> &mut dyn RenderBackend {
&mut self.hardware
}
fn game2d_frame_composer(&mut self) -> &mut dyn Game2DFrameComposer {
&mut self.hardware
}
fn audio(&self) -> &dyn AudioBridge {
self.hardware.audio()
}
fn audio_mut(&mut self) -> &mut dyn AudioBridge {
self.hardware.audio_mut()
}
fn input(&self) -> &dyn InputPlatform {
self.hardware.input()
}
fn input_mut(&mut self) -> &mut dyn InputPlatform {
self.hardware.input_mut()
}
fn assets(&self) -> &dyn AssetBridge {
self.hardware.assets()
}
fn assets_mut(&mut self) -> &mut dyn AssetBridge {
self.hardware.assets_mut()
}
fn telemetry(&self) -> &dyn TelemetryPlatform {
self.hardware.telemetry()
}
}
#[cfg(test)]
mod tests {
use prometeu_bytecode::registry::FunctionDecl;
use prometeu_test_support::program::{TestProgram, int64_signature};
use std::fs;
use prometeu_bytecode::assembler::assemble;
use prometeu_bytecode::model::Export;
use super::{AdvanceFrameOutcome, HeadlessHost};
#[test]
fn termination_during_frame_advance_clears_host_step_control() {
let cartridge = non_closing_cartridge();
let mut host = HeadlessHost::new();
host.boot(cartridge.to_string_lossy()).expect("boot non-closing cartridge");
host.firmware.request_home_from_host();
assert_eq!(
host.advance_frame().expect("lifecycle termination"),
AdvanceFrameOutcome::Terminated
);
assert!(host.firmware.os.vm().paused());
assert!(!host.firmware.os.vm().debug_step_requested());
fs::remove_dir_all(cartridge).expect("remove test cartridge");
}
fn non_closing_cartridge() -> std::path::PathBuf {
let directory = std::env::temp_dir().join(format!(
"prometeu-headless-termination-cleanup-{}-{}",
std::process::id(),
std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.expect("system clock")
.as_nanos()
));
fs::create_dir_all(&directory).expect("create test cartridge");
let code = assemble("JMP 0\n").expect("assemble non-closing program");
let module = TestProgram {
const_pool: vec![],
functions: vec![FunctionDecl {
lifecycle_role: Default::default(),
code_offset: 0,
code_len: code.len() as u32,
local_slots: 0,
max_stack_slots: 1,
signature: int64_signature(0, 0),
captures: vec![],
name: None,
}],
code,
debug_info: None,
exports: vec![Export { symbol: "main".into(), func_idx: 0 }],
syscalls: vec![],
}
.serialize();
fs::write(directory.join("program.pbx"), module).expect("write test program");
fs::write(
directory.join("manifest.json"),
"{\n \"magic\": \"PMTU\",\n \"cartridge_version\": 1,\n \"app_id\": 91,\n \"title\": \"Termination Cleanup\",\n \"app_version\": \"0.1.0\",\n \"app_mode\": \"Game\",\n \"capabilities\": []\n}\n",
)
.expect("write test manifest");
directory
}
}
@@ -0,0 +1,17 @@
Compiling prometeu-host-headless v0.1.0 (/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/host/prometeu-host-headless)
Finished `test` profile [unoptimized + debuginfo] target(s) in 2.49s
Running unittests src/lib.rs (target/debug/deps/prometeu_host_headless-34e7d78b76b56071)
running 10 tests
test host::memcard::tests::bootstrap_wait_deadline_is_shared_across_wakes_and_reentry ... ok
test host::memcard::tests::failed_bootstrap_io_returns_native_media_action_without_guest_fault ... ok
test host::memcard::tests::ordinary_gameplay_commit_does_not_wait_for_native_io ... ok
test host::memcard::tests::bootstrap_outer_timeout_preserves_native_snapshot_and_machine_state ... ok
test host::memcard::tests::explicit_continue_in_ram_preserves_dirty_snapshot_and_uses_no_new_boot ... ok
test host::memcard::tests::same_media_recovery_rejects_replacement_and_preserves_ram_continuation ... ok
test host::memcard::tests::unceased_io_retains_lock_and_terminal_result_survives_late_return_and_reconcile ... ok
test host::memcard::tests::first_reopen_frame_waits_for_controlled_presentation_without_replaying ... ok
test host::memcard::tests::queued_bootstrap_publication_can_progress_without_moving_guest_during_poll ... ok
test host::memcard::tests::blocked_bootstrap_reaches_native_deadline_and_keeps_worker_lock ... ok
test result: ok. 10 passed; 0 failed; 0 ignored; 0 measured; 13 filtered out; finished in 1.19s
@@ -0,0 +1,512 @@
diff --git a/crates/dev/prometeu-test-support/src/memcard_fixture.rs b/crates/dev/prometeu-test-support/src/memcard_fixture.rs
index af88c27..fba14c2 100644
--- a/crates/dev/prometeu-test-support/src/memcard_fixture.rs
+++ b/crates/dev/prometeu-test-support/src/memcard_fixture.rs
@@ -13,0 +14 @@ pub enum MemcardFixture {
+ ReadWithPresentation,
@@ -49,0 +51 @@ pub fn memcard_program(kind: MemcardFixture) -> Vec<u8> {
+ let reads = matches!(kind, MemcardFixture::Read | MemcardFixture::ReadWithPresentation);
@@ -54,2 +56,3 @@ pub fn memcard_program(kind: MemcardFixture) -> Vec<u8> {
- if matches!(kind, MemcardFixture::Read) {
- main.emit("GET_GLOBAL 0\nPUSH_I32 0\nPUSH_I32 0\nGET_GLOBAL 1\nPUSH_I32 0\nPUSH_I32 4\nHOSTCALL 1");
+ if reads {
+ let read_import = if matches!(kind, MemcardFixture::Read) { 1 } else { 2 };
+ main.emit(&format!("GET_GLOBAL 0\nPUSH_I32 0\nPUSH_I32 0\nGET_GLOBAL 1\nPUSH_I32 0\nPUSH_I32 4\nHOSTCALL {read_import}"));
@@ -104 +107,3 @@ pub fn memcard_program(kind: MemcardFixture) -> Vec<u8> {
- MemcardFixture::Read => imports.push(("slot_read", 6, 2)),
+ MemcardFixture::Read | MemcardFixture::ReadWithPresentation => {
+ imports.push(("slot_read", 6, 2));
+ }
diff --git a/crates/host/prometeu-host-headless/src/host.rs b/crates/host/prometeu-host-headless/src/host.rs
index f01ed2d..8da66d7 100644
--- a/crates/host/prometeu-host-headless/src/host.rs
+++ b/crates/host/prometeu-host-headless/src/host.rs
@@ -2,0 +3 @@ use std::sync::Arc;
+use std::time::{Duration, Instant};
@@ -22,0 +24,15 @@ const HOST_FRAME_ADVANCE_TICK_LIMIT: usize = 100_000;
+const BOOTSTRAP_IO_WAIT_QUANTUM: Duration = Duration::from_millis(5);
+const BOOTSTRAP_IO_WAIT_LIMIT: Duration = Duration::from_secs(2);
+
+/// One deadline for the entire advance, including repeated admission to the gate.
+#[derive(Default)]
+struct BootstrapIoWait {
+ deadline: Option<Instant>,
+}
+impl BootstrapIoWait {
+ fn next_wait(&mut self, now: Instant) -> Option<Duration> {
+ let deadline = *self.deadline.get_or_insert(now + BOOTSTRAP_IO_WAIT_LIMIT);
+ let remaining = deadline.saturating_duration_since(now);
+ (!remaining.is_zero()).then_some(remaining.min(BOOTSTRAP_IO_WAIT_QUANTUM))
+ }
+}
@@ -362,0 +379 @@ impl HeadlessHost {
+ let mut io_wait = BootstrapIoWait::default();
@@ -400,0 +418,18 @@ impl HeadlessHost {
+
+ loop {
+ // Refresh before every observation/poll: another lane job may
+ // have progressed without completing this publication.
+ let progress = self.firmware.os.memcard().lane.progress_stamp();
+ if !self.bootstrap_io_pending() {
+ break;
+ }
+ // Native polling and waiting do not execute machine ticks.
+ self.poll_memcard();
+ if self.host_action_required() {
+ self.finish_frame_advance();
+ return Ok(AdvanceFrameOutcome::ActionRequired);
+ }
+ if self.bootstrap_io_pending() {
+ self.wait_for_bootstrap_io(&mut io_wait, progress)?;
+ }
+ }
@@ -408,0 +444,26 @@ impl HeadlessHost {
+ fn bootstrap_io_pending(&mut self) -> bool {
+ let FirmwareState::GameRunning(step) = &self.firmware.state else { return false };
+ let task = step.task_id;
+ let hook_complete = self
+ .firmware
+ .os
+ .sessions()
+ .vm_session_for_task(task)
+ .is_some_and(|session| session.vm.memcard_boot_result() == Some(0));
+ let service = self.firmware.os.memcard();
+ hook_complete && service.session.boot_pending() && service.session.io_active()
+ }
+
+ fn wait_for_bootstrap_io(
+ &mut self,
+ wait: &mut BootstrapIoWait,
+ progress: u64,
+ ) -> Result<(), HostError> {
+ let Some(timeout) = wait.next_wait(Instant::now()) else {
+ self.finish_frame_advance();
+ return Err(self.memcard_error("advance", "restart_required"));
+ };
+ self.firmware.os.memcard().lane.wait_for_progress(progress, timeout);
+ Ok(())
+ }
+
diff --git a/crates/host/prometeu-host-headless/src/memcard_tests.rs b/crates/host/prometeu-host-headless/src/memcard_tests.rs
index 4056e40..1899610 100644
--- a/crates/host/prometeu-host-headless/src/memcard_tests.rs
+++ b/crates/host/prometeu-host-headless/src/memcard_tests.rs
@@ -5,0 +6,276 @@ use std::{fs, sync::mpsc};
+/// Holds the first native write after admission; the controller decides its outcome.
+struct BootstrapStore {
+ file: FileMemcard,
+ entered: mpsc::Sender<()>,
+ continue_io: mpsc::Receiver<Result<(), MemcardIoError>>,
+ held: bool,
+}
+impl MemcardStorage for BootstrapStore {
+ fn len(&self) -> Result<u64, MemcardIoError> {
+ self.file.len()
+ }
+ fn read_only(&self) -> bool {
+ false
+ }
+ fn read_at(&mut self, offset: u64, bytes: &mut [u8]) -> Result<(), MemcardIoError> {
+ self.file.read_at(offset, bytes)
+ }
+ fn write_at(&mut self, offset: u64, bytes: &[u8]) -> Result<(), MemcardIoError> {
+ if !self.held {
+ self.held = true;
+ let _ = self.entered.send(());
+ self.continue_io
+ .recv_timeout(Duration::from_secs(5))
+ .unwrap_or(Err(MemcardIoError::IoError))?;
+ }
+ self.file.write_at(offset, bytes)
+ }
+ fn sync(&mut self) -> Result<(), MemcardIoError> {
+ self.file.sync()
+ }
+}
+
+fn reopen_with_controlled_io(
+ kind: MemcardFixture,
+) -> (Fixture, HeadlessHost, mpsc::Receiver<()>, mpsc::Sender<Result<(), MemcardIoError>>) {
+ use prometeu_system::memcard::{
+ image::{Game, Icon, crc32c},
+ transaction::{DurableResult, PublicationControl},
+ };
+ let f = Fixture::new(kind);
+ let file = FileMemcard::create(&f.image, IMAGE_BYTES, |io, id| {
+ Card::format(io, id).map_err(|_| MemcardIoError::IoError)
+ })
+ .unwrap();
+ let mut card = Card::mount(Box::new(file)).unwrap();
+ let icon = [0; 560];
+ card.register(
+ Game {
+ app_id: 42,
+ title: "Existing record".into(),
+ data_format_version: 1,
+ created_at: 0,
+ slots: vec![0],
+ icon: Icon { offset: 0, frames: 1, duration: 1, crc32c: crc32c(&icon) },
+ },
+ &icon,
+ &PublicationControl::default(),
+ )
+ .unwrap();
+ assert_eq!(
+ card.commit(0, &[0, 127, 128, 255], 0, &PublicationControl::default()).durable,
+ DurableResult::Success
+ );
+ drop(card);
+ let (entered_tx, entered) = mpsc::channel();
+ let (continue_io, release_rx) = mpsc::channel();
+ let mut host = HeadlessHost::new();
+ host.media.path = Some(f.image.clone());
+ host.media.access = Some(MediaAccess::ReadWrite);
+ host.install_memcard(Box::new(BootstrapStore {
+ file: FileMemcard::open(&f.image, false).unwrap(),
+ entered: entered_tx,
+ continue_io: release_rx,
+ held: false,
+ }))
+ .unwrap();
+ host.boot_with_memcard_choice(f.cart.to_string_lossy(), Choice::Persistent).unwrap();
+ assert_eq!(host.get_state().tick_index, 0);
+ (f, host, entered, continue_io)
+}
+
+#[test]
+fn first_reopen_frame_waits_for_controlled_presentation_without_replaying() {
+ let (_f, mut host, entered, continue_io) =
+ reopen_with_controlled_io(MemcardFixture::ReadWithPresentation);
+ let (finished_tx, finished) = mpsc::channel();
+ let controller = std::thread::spawn(move || {
+ entered.recv_timeout(Duration::from_secs(3)).unwrap();
+ // Observe the owner while publication is provably held. This is a
+ // channel deadline, not a sleep used to infer that IO has started.
+ let premature = finished.recv_timeout(Duration::from_millis(300)).is_ok();
+ let _ = continue_io.send(Ok(()));
+ premature
+ });
+ let result = host.advance_frame();
+ let _ = finished_tx.send(());
+ let premature = controller.join().unwrap();
+ assert!(!premature, "advance returned while native publication was held: {result:?}");
+ assert!(matches!(
+ result,
+ Ok(AdvanceFrameOutcome::FrameCompleted { logical_frame_index: 1, .. })
+ ));
+ let state = host.get_state();
+ assert_eq!(state.frame_index, 1);
+ assert_eq!(state.tick_index, 2);
+ assert_eq!(state.status, HostExecutionStatus::Paused);
+ assert_eq!(state.stack_top.last(), Some(&prometeu_bytecode::Value::Int64(201)));
+ assert!(!host.firmware.os.vm().debug_step_requested());
+ assert!(host.get_fault().is_none());
+ assert!(!host.get_memcard_state().io.active);
+ assert_eq!(host.capture_frame().unwrap().logical_frame_index, 1);
+ host.shutdown(TeardownPolicy::default()).unwrap();
+}
+
+#[test]
+fn blocked_bootstrap_reaches_native_deadline_and_keeps_worker_lock() {
+ let (f, mut host, entered, continue_io) =
+ reopen_with_controlled_io(MemcardFixture::ReadWithPresentation);
+ let started = Instant::now();
+ let result = host.advance_frame();
+ entered.recv_timeout(Duration::from_secs(1)).unwrap();
+ let state = host.get_memcard_state();
+ let busy = matches!(FileMemcard::open(&f.image, false), Err(MemcardIoError::Busy));
+ // Always let the worker return before asserting, including on the old host.
+ continue_io.send(Ok(())).unwrap();
+ settle(&mut host);
+ assert_eq!(result.unwrap(), AdvanceFrameOutcome::ActionRequired);
+ assert!(started.elapsed() < Duration::from_secs(3));
+ assert!(state.recovery.restart_required);
+ assert!(state.io.active && busy);
+ assert_eq!(host.get_state().frame_index, 0);
+ assert_eq!(host.get_state().tick_index, 1);
+ assert_eq!(host.get_state().status, HostExecutionStatus::Paused);
+ assert!(!host.firmware.os.vm().debug_step_requested());
+ assert!(host.get_fault().is_none());
+}
+
+#[test]
+fn ordinary_gameplay_commit_does_not_wait_for_native_io() {
+ let (_f, mut host, entered, continue_io) = reopen_with_controlled_io(MemcardFixture::Read);
+ host.advance_frame().unwrap();
+ let service = host.firmware.os.memcard();
+ let context = service.session.context();
+ service.session.write(context, 0, 0, &[0, 127, 128, 255]).unwrap();
+ service.session.commit(context, 0, 0, Instant::now(), &service.lane).unwrap();
+ entered.recv_timeout(Duration::from_secs(2)).unwrap();
+ let result = host.advance_frame();
+ let pending = host.get_memcard_state();
+ continue_io.send(Ok(())).unwrap();
+ settle(&mut host);
+ assert!(matches!(
+ result,
+ Ok(AdvanceFrameOutcome::FrameCompleted { logical_frame_index: 2, .. })
+ ));
+ assert!(pending.io.active);
+ assert_eq!(pending.request.unwrap().operation, "commit");
+ assert!(!host.firmware.os.vm().debug_step_requested());
+ assert!(host.get_fault().is_none());
+ host.shutdown(TeardownPolicy::default()).unwrap();
+}
+
+#[test]
+fn bootstrap_wait_deadline_is_shared_across_wakes_and_reentry() {
+ use super::super::{BOOTSTRAP_IO_WAIT_QUANTUM, BootstrapIoWait};
+ let start = Instant::now();
+ let mut wait = BootstrapIoWait::default();
+ assert_eq!(wait.next_wait(start), Some(BOOTSTRAP_IO_WAIT_QUANTUM));
+ assert_eq!(
+ wait.next_wait(start + Duration::from_millis(1000)),
+ Some(BOOTSTRAP_IO_WAIT_QUANTUM)
+ );
+ assert_eq!(wait.next_wait(start + Duration::from_millis(1999)), Some(Duration::from_millis(1)));
+ assert_eq!(wait.next_wait(start + Duration::from_secs(2)), None);
+ assert_eq!(wait.next_wait(start + Duration::from_secs(3)), None);
+}
+
+#[test]
+fn bootstrap_outer_timeout_preserves_native_snapshot_and_machine_state() {
+ use super::super::BootstrapIoWait;
+ let (_f, mut host, _entered, _release) = reopen_with_controlled_io(MemcardFixture::Read);
+ let before = host.get_state();
+ host.firmware.os.vm().set_paused(false);
+ host.firmware.os.vm().request_debug_step();
+ let mut wait = BootstrapIoWait { deadline: Some(Instant::now()) };
+ let error = host.wait_for_bootstrap_io(&mut wait, 0).unwrap_err();
+ let snapshot = host.get_memcard_state();
+ let HostError::Memcard(error) = error else { panic!("expected a native memcard error") };
+ assert_eq!(error.operation, "advance");
+ assert_eq!(error.reason, "restart_required");
+ assert_eq!(error.state, snapshot);
+ let after = host.get_state();
+ assert_eq!((after.pc, after.frame_index, after.tick_index), (before.pc, 0, 0));
+ assert_eq!(after.stack_top.to_vec(), before.stack_top.to_vec());
+ assert_eq!(after.status, HostExecutionStatus::Paused);
+ assert!(!host.firmware.os.vm().debug_step_requested());
+ assert!(host.get_fault().is_none());
+ host.shutdown(TeardownPolicy::default()).unwrap();
+}
+
+#[test]
+fn failed_bootstrap_io_returns_native_media_action_without_guest_fault() {
+ let (_f, mut host, entered, continue_io) =
+ reopen_with_controlled_io(MemcardFixture::ReadWithPresentation);
+ let controller = std::thread::spawn(move || {
+ entered.recv_timeout(Duration::from_secs(2)).unwrap();
+ continue_io.send(Err(MemcardIoError::Unavailable)).unwrap();
+ });
+ let result = host.advance_frame();
+ controller.join().unwrap();
+ assert_eq!(result.unwrap(), AdvanceFrameOutcome::ActionRequired);
+ let state = host.get_memcard_state();
+ assert!(state.recovery.removal_pending);
+ assert!(!state.io.active);
+ assert_eq!(host.get_state().frame_index, 0);
+ assert_eq!(host.get_state().status, HostExecutionStatus::Paused);
+ assert!(!host.firmware.os.vm().debug_step_requested());
+ assert!(host.get_fault().is_none());
+}
+
+#[test]
+fn queued_bootstrap_publication_can_progress_without_moving_guest_during_poll() {
+ use prometeu_system::AsyncWorkJobOutcome;
+ let (_f, mut host, entered, continue_io) =
+ reopen_with_controlled_io(MemcardFixture::ReadWithPresentation);
+ let (busy_tx, busy) = mpsc::channel();
+ let (unblock, unblock_rx) = mpsc::channel();
+ host.firmware
+ .os
+ .memcard()
+ .lane
+ .submit_memcard_commit_write(move |_| {
+ busy_tx.send(()).unwrap();
+ let _ = unblock_rx.recv_timeout(Duration::from_secs(3));
+ AsyncWorkJobOutcome::Completed
+ })
+ .unwrap();
+ busy.recv_timeout(Duration::from_secs(2)).unwrap();
+ for _ in 0..10 {
+ host.firmware.os.vm().set_paused(false);
+ host.firmware.os.vm().request_debug_step();
+ host.tick_once();
+ if host.bootstrap_io_pending() {
+ break;
+ }
+ }
+ let pending = host.bootstrap_io_pending();
+ let queued = host.get_memcard_state();
+ let before = host.get_state();
+ host.poll_memcard();
+ let after = host.get_state();
+ let (finished_tx, finished) = mpsc::channel();
+ let controller = std::thread::spawn(move || {
+ let premature = finished.recv_timeout(Duration::from_millis(300)).is_ok();
+ let _ = unblock.send(());
+ entered.recv_timeout(Duration::from_secs(2)).unwrap();
+ let _ = continue_io.send(Ok(()));
+ premature
+ });
+ let result = host.advance_frame();
+ let _ = finished_tx.send(());
+ let premature = controller.join().unwrap();
+ assert!(pending);
+ assert!(!premature, "advance returned while its publication was queued: {result:?}");
+ assert_eq!(queued.io.phase, "queued");
+ assert_eq!(
+ (before.pc, before.frame_index, before.tick_index),
+ (after.pc, after.frame_index, after.tick_index)
+ );
+ assert_eq!(before.stack_top.to_vec(), after.stack_top.to_vec());
+ assert!(matches!(
+ result,
+ Ok(AdvanceFrameOutcome::FrameCompleted { logical_frame_index: 1, .. })
+ ));
+ host.shutdown(TeardownPolicy::default()).unwrap();
+}
+
@@ -12,0 +289 @@ impl Fixture {
+ static COUNTER: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
@@ -14 +291 @@ impl Fixture {
- "native-memcard-{}-{}",
+ "native-memcard-{}-{}-{}",
@@ -16 +293,2 @@ impl Fixture {
- std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).unwrap().as_nanos()
+ std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).unwrap().as_nanos(),
+ COUNTER.fetch_add(1, std::sync::atomic::Ordering::Relaxed)
diff --git a/crates/tools/prometeu-cli/tests/automation_process.rs b/crates/tools/prometeu-cli/tests/automation_process.rs
index 9c87fa9..0f372ac 100644
--- a/crates/tools/prometeu-cli/tests/automation_process.rs
+++ b/crates/tools/prometeu-cli/tests/automation_process.rs
@@ -846,0 +847,9 @@ fn packaged_installation_smoke() {
+#[test]
+#[ignore = "requires PROMETEU_PROTOCOL_TEST_INSTALL pointing to an isolated installation"]
+fn packaged_memcard_reopen_first_frame() {
+ let installation = PathBuf::from(
+ std::env::var_os("PROMETEU_PROTOCOL_TEST_INSTALL").expect("set isolated installation path"),
+ );
+ memcard_process::presentation_reopen(&installation.join("prometeu"));
+}
+
diff --git a/crates/tools/prometeu-cli/tests/support/memcard_process.rs b/crates/tools/prometeu-cli/tests/support/memcard_process.rs
index a0b70d9..0bfb90b 100644
--- a/crates/tools/prometeu-cli/tests/support/memcard_process.rs
+++ b/crates/tools/prometeu-cli/tests/support/memcard_process.rs
@@ -104,0 +105,57 @@ fn persistence(binary: &Path) {
+pub(super) fn presentation_reopen(binary: &Path) {
+ let root = TempDir::new();
+ let image = root.0.join("presentation-reopen.pmc");
+ let write = card(MemcardFixture::Write, "1");
+ let mut writer = start_at(binary);
+ mount(&mut writer, &image, "create", "read_write");
+ launch(&mut writer, &write, "persistent");
+ oracle(&mut writer, 101);
+ assert_eq!(writer.ok("get_memcard_state", json!({}))["dirty"], false);
+ writer.close();
+
+ for version in ["1", "2"] {
+ let read = card(MemcardFixture::ReadWithPresentation, version);
+ let mut reader = start_at(binary);
+ mount(&mut reader, &image, "open", "read_write");
+ launch(&mut reader, &read, "persistent");
+ let booted = reader.ok("get_state", json!({}));
+ assert_eq!(booted["pc"], 0);
+ assert_eq!(booted["tickIndex"], 0);
+ assert_eq!(booted["logicalFrameIndex"], 0);
+ // Exactly one command owns the first frame; there is no oracle retry.
+ let advanced = reader.ok("advance", json!({"frames":1}));
+ assert_eq!(advanced, json!({"requested":1,"completed":1,"stop":"completed"}));
+ let state = reader.ok("get_state", json!({}));
+ assert_eq!(state["logicalFrameIndex"], 1);
+ assert_eq!(state["tickIndex"], 2);
+ assert_eq!(state["status"], "paused");
+ assert_eq!(state["appId"], 4294967295u32);
+ assert_eq!(state["stackTop"].as_array().unwrap().last().unwrap()["value"], "201");
+ assert_eq!(reader.ok("get_fault", json!({})), Value::Null);
+ let media = reader.ok("get_memcard_state", json!({}));
+ assert_eq!(
+ media["request"],
+ Value::Null,
+ "presentation must finish without a payload save"
+ );
+ assert_eq!(media["io"]["active"], false);
+ assert_eq!(media["dirty"], false);
+ assert_eq!(reader.ok("capture", json!({}))["logicalFrameIndex"], 1);
+ reader.close();
+ }
+ // Preserve the original reader's independent read-without-writing oracle.
+ let bytes = fs::read(&image).unwrap();
+ let read = card(MemcardFixture::Read, "2");
+ let mut reader = start_at(binary);
+ mount(&mut reader, &image, "open", "read_write");
+ launch(&mut reader, &read, "persistent");
+ oracle(&mut reader, 201);
+ reader.close();
+ assert_eq!(fs::read(&image).unwrap(), bytes);
+}
+
+#[test]
+fn memcard_reopen_presentation_completes_exactly_one_first_frame() {
+ presentation_reopen(Path::new(env!("CARGO_BIN_EXE_prometeu")));
+}
+
diff --git a/docs/specs/runtime/08-save-memory-and-memcard.md b/docs/specs/runtime/08-save-memory-and-memcard.md
index ddbdfcf..8379a4d 100644
--- a/docs/specs/runtime/08-save-memory-and-memcard.md
+++ b/docs/specs/runtime/08-save-memory-and-memcard.md
@@ -373,0 +374,15 @@ remains independent of real-time pacing.
+During a headless frame advance, a successful bootstrap hook may still depend on
+its native presentation publication. Only while that dependency blocks the active
+VM and the corresponding IO remains queued or running, the host owner waits on
+the shared lane's progress signal, outside firmware/VM ticks. Each requested wait
+is at most 5 ms. Polling preserves the request's original 500 ms cancellation and
+1 s stop/escalation deadlines. A single additional 2 s owner deadline starts on
+first entry to this wait within an advance and never resets on wake or reentry.
+It does not extend the native deadlines. Native media action stops the advance
+with exact progress; if the dependency outlives the owner deadline without a
+terminal boundary, it returns a native `memcard_error` for `advance` with reason
+`restart_required` and the current media state. Neither outcome confirms IO
+cessation or releases worker-owned buffers, media or locks. An ordinary gameplay
+commit that does not block the VM does not activate this wait. Pure IO polling
+and waiting do not advance guest counters or input and do not pace game frames.
+
diff --git a/docs/specs/runtime/11-portability-and-cross-platform-execution.md b/docs/specs/runtime/11-portability-and-cross-platform-execution.md
index e7bbc7b..e254734 100644
--- a/docs/specs/runtime/11-portability-and-cross-platform-execution.md
+++ b/docs/specs/runtime/11-portability-and-cross-platform-execution.md
@@ -328,0 +329,11 @@ wall-clock timeout.
+- If a successful memcard bootstrap still blocks the active VM on its queued or
+ running native publication, the headless owner coordinates lane progress outside
+ machine ticks, in requested waits of at most 5 ms. The same advance retains its
+ request and a single 2 s outer deadline from first wait admission; wakes/reentry
+ do not reset it. Native 500 ms cancellation and 1 s escalation remain authoritative.
+ A native action-required boundary takes precedence; unresolved IO at the outer
+ deadline returns a memcard `restart_required` host error with a native snapshot.
+ Every return pauses execution and clears the host's step request. IO-only polls
+ and waits do not add guest ticks/frames, enlarge the 100,000 firmware-tick
+ watchdog, rerun bootstrap, or synchronize unrelated gameplay commits. Waiting
+ does not establish IO cessation or permit release of worker-owned resources.
diff --git a/docs/specs/runtime/11a-headless-automation-protocol.md b/docs/specs/runtime/11a-headless-automation-protocol.md
index d201d3a..df0ce40 100644
--- a/docs/specs/runtime/11a-headless-automation-protocol.md
+++ b/docs/specs/runtime/11a-headless-automation-protocol.md
@@ -322,0 +323,16 @@ RAM/continuation/original retained results and does not rerun initialization.
+When successful bootstrap remains blocked by its pending native publication, the
+owner coordinates lane progress within the same advance, outside machine ticks,
+with requested waits of at most 5 ms. This does not apply to an unrelated gameplay
+commit. Native deadlines remain 500 ms for cancellation and 1 s for stop/escalation,
+measured from the original request admission. One additional 2 s deadline from
+first wait entry in an `advance_frame` does not reset on wake/reentry or extend
+those deadlines. Existing native action-required/fault boundaries take precedence.
+If the dependency remains pending at the outer deadline without such a boundary,
+the advance returns `stop:host_error`, exact known `completed` progress, and
+`error.code:memcard_error` with `details.operation:advance`,
+`details.reason:restart_required` and `details.state` holding the native snapshot.
+The guest finishes paused with the host step request cleared. This preserves
+worker ownership until actual cessation, the 100,000-tick frame watchdog, transport
+responsiveness and cancellation between frames; it introduces no intraframe
+cancellation, guest fault, simulated progress, command replay or new protocol shape.
+
@@ -0,0 +1,22 @@
{
"workspace": {
"passed": 1125,
"failed": 0,
"ignored": 16,
"suites": 60
},
"release": {
"passed": 89,
"failed": 0,
"ignored": 4,
"suites": 10
},
"clippy": {
"result": "passed",
"logSha256": "47bf8a993b7cac246fb86835dd5a114a585cd6d1dd676b0ac507f10be3e78084"
},
"format": {
"result": "passed",
"logSha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}
}
@@ -0,0 +1,12 @@
Compiling prometeu-host-headless v0.1.0 (/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/host/prometeu-host-headless)
Compiling prometeu-cli v0.1.0 (/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/tools/prometeu-cli)
Finished `test` profile [unoptimized + debuginfo] target(s) in 4.84s
Running tests/automation_process.rs (target/debug/deps/automation_process-018fadef87e61183)
running 4 tests
test memcard_process::packaged_memcard_process_persistence ... ok
test packaged_installation_smoke ... ok
test packaged_memcard_reopen_first_frame ... ok
test packaged_native_log_observation ... ok
test result: ok. 4 passed; 0 failed; 0 ignored; 0 measured; 26 filtered out; finished in 1.38s
@@ -0,0 +1,39 @@
Compiling prometeu-host-headless v0.1.0 (/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/host/prometeu-host-headless)
Compiling prometeu-test-support v0.1.0 (/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/dev/prometeu-test-support)
Compiling prometeu-cli v0.1.0 (/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/tools/prometeu-cli)
Finished `test` profile [unoptimized + debuginfo] target(s) in 6.12s
Running tests/automation_process.rs (target/debug/deps/automation_process-018fadef87e61183)
running 30 tests
test handshake_versions_capabilities_and_limits_are_explicit ... ok
test faults_and_boot_failures_are_structured_not_log_parsing ... ok
test log_observation_preserves_existing_guest_length_and_rate_limits ... ok
test conflicting_work_is_rejected_and_cancellation_reports_partial_progress ... ok
test bounded_log_responses_can_be_retried_without_draining ... ok
test dispatcher_works_from_a_relocated_installation_and_other_cwd ... ok
test idle_eof_and_truncated_eof_close_the_process ... ok
test malformed_fragmented_and_oversized_commands_do_not_desynchronize ... ok
test log_read_requires_explicit_capability_and_minor_two ... ok
test lifecycle_and_capture_match_the_in_process_canonical_oracle ... ok
test memcard_process::memcard_media_errors_and_negotiation_never_select_a_fallback ... ok
test memcard_process::packaged_memcard_process_persistence ... ignored, requires PROMETEU_PROTOCOL_TEST_INSTALL pointing to an extracted dist archive
test memcard_process::memcard_creation_race_and_process_death_release_real_ownership ... ok
test native_log_pages_are_read_only_replayable_and_survive_reset ... ok
test packaged_installation_smoke ... ignored, requires PROMETEU_PROTOCOL_TEST_INSTALL pointing to an extracted dist archive
test packaged_memcard_reopen_first_frame ... ignored, requires PROMETEU_PROTOCOL_TEST_INSTALL pointing to an isolated installation
test packaged_native_log_observation ... ignored, requires PROMETEU_PROTOCOL_TEST_INSTALL pointing to an isolated installation
test independent_processes_match_pixels_ids_state_and_fault ... ok
test schemas_and_distributed_request_fixtures_are_consistent ... ok
test memcard_process::memcard_dirty_refusal_retains_channel_and_explicit_ram_has_no_save ... ok
test memcard_process::memcard_idle_observation_never_advances_guest_counters ... ok
test shutdown_and_eof_interrupt_active_work_without_resuming_it ... ok
test memcard_process::memcard_access_denial_is_typed_and_does_not_create_or_modify_media ... ok
test missing_binary_and_invalid_cli_limits_fail_explicitly ... ok
test memcard_process::memcard_process_ownership_covers_aliases_readers_and_release ... ok
test memcard_process::memcard_public_distinct_process_save_readback_and_version_identity ... ok
test memcard_process::memcard_reopen_presentation_completes_exactly_one_first_frame ... ok
test memcard_process::desktop_dispatch_forwards_explicit_media_without_interpreting_player_policy ... ok
test timely_readers_outlive_ring_capacity_while_stale_cursors_report_gaps ... ok
test partial_guest_fault_and_host_watchdog_are_distinct_outcomes ... ok
test result: ok. 26 passed; 0 failed; 4 ignored; 0 measured; 0 filtered out; finished in 1.82s
@@ -0,0 +1,13 @@
{
"sourceHead": "49d7fca0b725a0a261cda09bf5e924102c84fe31",
"decision": "DEC-0071",
"plan": "PLN-0202",
"owner": "runtime/headless",
"baselineProbe": "../baseline/review-summary.json",
"originalRuntimeOnlyBoundary": "Studio consumer source/build/tests and Zelda pilot are owned by the Studio AI. No consumer checkout is a provider fixture.",
"redEvidence": "red-controlled-release.log",
"redOutcome": "Old optimized host returns FrameAdvanceWatchdogExpired while channel-controlled presentation is held. Debug timing can allow IO completion before its tick watchdog.",
"controlledTest": "Channel entry milestone proves pending publication; controller observes owner response for 300 ms then permits IO, below the native 500 ms cancellation threshold.",
"hostTimerTest": "Explicit instants prove a shared 2 s outer timer across wakes/reentry; native 1 s escalation takes precedence in an actually blocked storage integration.",
"machineCounters": "Neutral presentation reader completes first frame at logicalFrameIndex=1/tickIndex=2; ticks depend on the fixture, not the Zelda reproduction."
}
@@ -0,0 +1,26 @@
Compiling getrandom v0.3.4
Compiling prometeu-hal v0.1.0 (/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-hal)
Compiling prometeu-test-support v0.1.0 (/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/dev/prometeu-test-support)
Compiling prometeu-vm v0.1.0 (/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-vm)
Compiling prometeu-drivers v0.1.0 (/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers)
Compiling prometeu-system v0.1.0 (/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-system)
Compiling prometeu-firmware v0.1.0 (/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-firmware)
Compiling prometeu-host-headless v0.1.0 (/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/host/prometeu-host-headless)
Finished `release` profile [optimized] target(s) in 9.57s
Running unittests src/lib.rs (target/release/deps/prometeu_host_headless-c1bddddaf26a1995)
running 1 test
thread 'host::memcard::tests::first_reopen_frame_waits_for_controlled_presentation_without_replaying' (3546672) panicked at crates/host/prometeu-host-headless/src/memcard_tests.rs:103:5:
advance returned while native publication was held: Err(FrameAdvanceWatchdogExpired { host_tick_limit: 100000 })
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
test host::memcard::tests::first_reopen_frame_waits_for_controlled_presentation_without_replaying ... FAILED
failures:
failures:
host::memcard::tests::first_reopen_frame_waits_for_controlled_presentation_without_replaying
test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 18 filtered out; finished in 0.09s
error: test failed, to rerun pass `-p prometeu-host-headless --lib`
@@ -0,0 +1,155 @@
Compiling prometeu-host-headless v0.1.0 (/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/host/prometeu-host-headless)
Compiling prometeu-cli v0.1.0 (/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/tools/prometeu-cli)
Finished `release` profile [optimized] target(s) in 8.54s
Running unittests src/lib.rs (target/release/deps/prometeu_cli-a2a569acb4d2123a)
running 0 tests
test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
Running unittests src/main.rs (target/release/deps/prometeu-233bd0c6f7dfd1c0)
running 4 tests
test tests::child_exit_code_preserves_non_zero_one ... ok
test tests::child_exit_code_preserves_zero ... ok
test tests::child_exit_code_preserves_non_zero_other ... ok
test tests::child_exit_code_rejects_status_without_numeric_code ... ok
test result: ok. 4 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
Running unittests src/bin/prometeu-headless.rs (target/release/deps/prometeu_headless-891734b93133c22e)
running 0 tests
test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
Running unittests src/bin/prometeu-runtime.rs (target/release/deps/prometeu_runtime-2d42636990523667)
running 0 tests
test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
Running tests/automation_process.rs (target/release/deps/automation_process-48ae7cde6854c255)
running 30 tests
test handshake_versions_capabilities_and_limits_are_explicit ... ok
test log_observation_preserves_existing_guest_length_and_rate_limits ... ok
test faults_and_boot_failures_are_structured_not_log_parsing ... ok
test conflicting_work_is_rejected_and_cancellation_reports_partial_progress ... ok
test bounded_log_responses_can_be_retried_without_draining ... ok
test lifecycle_and_capture_match_the_in_process_canonical_oracle ... ok
test dispatcher_works_from_a_relocated_installation_and_other_cwd ... ok
test idle_eof_and_truncated_eof_close_the_process ... ok
test malformed_fragmented_and_oversized_commands_do_not_desynchronize ... ok
test independent_processes_match_pixels_ids_state_and_fault ... ok
test log_read_requires_explicit_capability_and_minor_two ... ok
test memcard_process::packaged_memcard_process_persistence ... ignored, requires PROMETEU_PROTOCOL_TEST_INSTALL pointing to an extracted dist archive
test memcard_process::memcard_media_errors_and_negotiation_never_select_a_fallback ... ok
test memcard_process::memcard_creation_race_and_process_death_release_real_ownership ... ok
test packaged_installation_smoke ... ignored, requires PROMETEU_PROTOCOL_TEST_INSTALL pointing to an extracted dist archive
test packaged_memcard_reopen_first_frame ... ignored, requires PROMETEU_PROTOCOL_TEST_INSTALL pointing to an isolated installation
test packaged_native_log_observation ... ignored, requires PROMETEU_PROTOCOL_TEST_INSTALL pointing to an isolated installation
test native_log_pages_are_read_only_replayable_and_survive_reset ... ok
test schemas_and_distributed_request_fixtures_are_consistent ... ok
test shutdown_and_eof_interrupt_active_work_without_resuming_it ... ok
test partial_guest_fault_and_host_watchdog_are_distinct_outcomes ... ok
test memcard_process::memcard_dirty_refusal_retains_channel_and_explicit_ram_has_no_save ... ok
test timely_readers_outlive_ring_capacity_while_stale_cursors_report_gaps ... ok
test memcard_process::memcard_idle_observation_never_advances_guest_counters ... ok
test missing_binary_and_invalid_cli_limits_fail_explicitly ... ok
test memcard_process::memcard_access_denial_is_typed_and_does_not_create_or_modify_media ... ok
test memcard_process::desktop_dispatch_forwards_explicit_media_without_interpreting_player_policy ... ok
test memcard_process::memcard_process_ownership_covers_aliases_readers_and_release ... ok
test memcard_process::memcard_public_distinct_process_save_readback_and_version_identity ... ok
test memcard_process::memcard_reopen_presentation_completes_exactly_one_first_frame ... ok
test result: ok. 26 passed; 0 failed; 4 ignored; 0 measured; 0 filtered out; finished in 0.85s
Running tests/registry_fault_schema.rs (target/release/deps/registry_fault_schema-2274560704287ef1)
running 2 tests
test published_load_schema_requires_tag_context_and_the_matching_init_payload ... ok
test published_schema_accepts_structured_resource_fields_and_rejects_unknown_or_negative_values ... ok
test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.05s
Running unittests src/lib.rs (target/release/deps/prometeu_host_headless-751195d1585cd278)
running 23 tests
test automation::tests::bounded_lines_accept_fragmentation_and_recover_after_oversize ... ok
test automation::tests::response_limit_counts_the_complete_envelope_and_keeps_correlation ... ok
test automation::wire::fault_tests::resource_trap_wire_preserves_native_fields_and_source_span ... ok
test automation::wire::log_tests::native_records_preserve_unsigned_maxima_and_typed_sources ... ok
test automation::tests::input_snapshot_is_replacement_and_rejects_unknown_fields ... ok
test automation::wire::fault_tests::load_failure_wire_uses_shared_structured_serializer_and_no_runtime_pc ... ok
test automation::tests::distributed_request_fixtures_are_accepted_by_the_actual_parser ... ok
test automation::tests::capture_preserves_independent_ids_and_excludes_padding_without_channel_loss ... ok
test automation::wire::log_tests::oversized_native_event_is_an_error_without_partial_result ... ok
test automation::wire::log_tests::required_nullable_cursor_and_limit_reject_malformed_values ... ok
test host::memcard::tests::bootstrap_wait_deadline_is_shared_across_wakes_and_reentry ... ok
test automation::wire::fault_tests::executed_closure_quota_refusal_reaches_wire_with_machine_fields ... ok
test automation::wire::fault_tests::active_host_native_type_fault_preserves_wire_machine_fields ... ok
test host::tests::termination_during_frame_advance_clears_host_step_control ... ok
test host::memcard::tests::failed_bootstrap_io_returns_native_media_action_without_guest_fault ... ok
test host::memcard::tests::bootstrap_outer_timeout_preserves_native_snapshot_and_machine_state ... ok
test host::memcard::tests::ordinary_gameplay_commit_does_not_wait_for_native_io ... ok
test host::memcard::tests::explicit_continue_in_ram_preserves_dirty_snapshot_and_uses_no_new_boot ... ok
test host::memcard::tests::unceased_io_retains_lock_and_terminal_result_survives_late_return_and_reconcile ... ok
test host::memcard::tests::same_media_recovery_rejects_replacement_and_preserves_ram_continuation ... ok
test host::memcard::tests::first_reopen_frame_waits_for_controlled_presentation_without_replaying ... ok
test host::memcard::tests::queued_bootstrap_publication_can_progress_without_moving_guest_during_poll ... ok
test host::memcard::tests::blocked_bootstrap_reaches_native_deadline_and_keeps_worker_lock ... ok
test result: ok. 23 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 1.17s
Running tests/deterministic_control.rs (target/release/deps/deterministic_control-98e9b0ea3dcb6c52)
running 25 tests
test headless_source_has_no_timing_wait_or_interactive_backend_dependency ... ok
test advance_after_reset_reports_termination_without_ticking ... ok
test instruction_step_fault_remains_structured ... ok
test end_of_rom_completes_a_logical_frame ... ok
test batch_stops_early_on_fault_and_reports_partial_progress ... ok
test injected_civil_clock_remains_the_runtime_source_across_lifecycle ... ok
test clear_input_drops_right ... ok
test lifecycle_state_and_preconditions_are_structural ... ok
test audio_play_does_not_need_a_device ... ok
test normalized_touch_edges_and_coordinates_use_the_same_input_surface ... ok
test normalized_button_press_hold_release_and_clear_are_observable ... ok
test step_does_not_complete_a_logical_frame ... ok
test one_frame_returns_and_captures_the_exact_published_frame ... ok
test controlled_civil_time_is_independent_of_frames_pause_and_reset ... ok
test right_hold_then_release_changes_pixels ... ok
test one_logical_frame_may_span_multiple_internal_ticks ... ok
test stepping_frame_sync_is_not_a_fault_or_completed_runtime_frame ... ok
test vm_init_failure_is_returned_as_structured_boot_failure ... ok
test trap_is_structured ... ok
test zero_frames_is_an_explicit_noop ... ok
test two_runs_match_oracle ... ok
test reset_matches_fresh_host ... ok
test three_hundred_frames_complete_without_realtime_pacing ... ok
test outer_frame_limit_is_a_host_error_and_finishes_paused ... ok
test audio_controls_quota_and_multiple_frames_are_device_independent ... ok
test result: ok. 25 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.09s
Running tests/input_queries.rs (target/release/deps/input_queries-2ee1672fd0295c9d)
running 4 tests
test catalogue_has_exact_names_ids_signatures_and_no_endpoint_aliases ... ok
test vm_queries_charge_one_cycle_each_and_allocate_no_guest_objects ... ok
test every_button_uses_its_own_snapshot_and_queries_do_not_advance_frames ... ok
test every_known_query_faults_when_unavailable_and_rejects_arguments ... ok
test result: ok. 4 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
Running tests/typed_runtime.rs (target/release/deps/typed_runtime-e31573f60bd59e2a)
running 5 tests
test typed_native_argument_fault_inside_callback_reaches_active_host ... ok
test active_host_preserves_removed_opcode_load_context_and_null_fn_trap ... ok
test sync_in_callee_or_closure_resumes_next_pc_with_locals_and_init_once ... ok
test budget_exhaustion_inside_fn_keeps_the_same_open_logical_frame ... ok
test regenerated_cartridges_run_six_complete_frames_on_production_host ... ok
test result: ok. 5 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.06s
@@ -0,0 +1,17 @@
{
"Cargo.toml": "ac6f69d0bd2ae0c50f0e6123239825eef12d92288625d1ce3eebf71a1d5e8e63",
"Cargo.lock": "cffad9ed62f38a591538abd81dd39270d6022397342c8189f4ac6c7baaa8e795",
"rust-toolchain.toml": "a7a23801522d469e93021507fc88e9f5651056fce0e6aa22b3d3157c5f3dc6fe",
"dist-workspace.toml": "ece5a7b40083ac1565e8659f8e9874c7510b9cd80571e17540fd70c1b3be8d64",
"crates/tools/prometeu-cli/Cargo.toml": "6aa6001b65498f118f46d995fc00f1c7c3b690637a6259870eb74043f206c1e6",
"crates/host/prometeu-host-headless/src/host.rs": "e4e5b5809773e00b11d2823b854528970ba7914925b9a2089f9e0e9336de117a",
"crates/host/prometeu-host-headless/src/memcard_tests.rs": "d94fc73ec614d00c78bdc1d38e4f5fc5dba38c33ee2fd04d7d529abf7588da8e",
"crates/dev/prometeu-test-support/src/memcard_fixture.rs": "3ca22dd5bc193f07034991ac1d3b232cb02edac433052430604aaa3be6443ec8",
"crates/tools/prometeu-cli/tests/automation_process.rs": "5b79b0d2ebefbce595095487fa9c392c204923ef34ab5c2b0036656c4f0c07ee",
"crates/tools/prometeu-cli/tests/support/memcard_process.rs": "b7e5b24474b4bfa13a386e2ab5f8fad4464f665fbd40f1b1e34763d62284b6e7",
"docs/specs/runtime/08-save-memory-and-memcard.md": "edd46ced0f0f4fb32d95db6c6b89120d1a61561111d2575d3737b7d8175547c1",
"docs/specs/runtime/11-portability-and-cross-platform-execution.md": "1a0db0500ae72f709b05a0be9d3474ce23b4c3a5ab21f36f4611090e1f1f70b0",
"docs/specs/runtime/11a-headless-automation-protocol.md": "2c5391fdbeb35964717f2af1f994b5c81b1b4278641fece17ccdc3fb6b766a6e",
"devtools/headless-protocol/request.schema.json": "554960a1c6c1304da32753937b899b51ac658cae4b9d96927f5a384325ce2ae2",
"devtools/headless-protocol/response.schema.json": "7a8a0fe70a6864203b771e0564dc4227b768213d2368c5b162c892c55c5e186b"
}
@@ -0,0 +1,5 @@
{
"prometeu": "73101a42ed5f2a22ad74fd639498d424c070a712a3bce32a9cec6fab3d5bdd80",
"prometeu-runtime": "ee00a587eb48030d1455d3c9bedd784ab620309a09877b50fe3641ae502635df",
"prometeu-headless": "e5e9571e7ab42724af37294c79b19478a1e1b5a71df177eee7141d42e042f6f4"
}
@@ -0,0 +1,13 @@
{
"unchanged": true,
"before": {
"prometeu": "73101a42ed5f2a22ad74fd639498d424c070a712a3bce32a9cec6fab3d5bdd80",
"prometeu-runtime": "ee00a587eb48030d1455d3c9bedd784ab620309a09877b50fe3641ae502635df",
"prometeu-headless": "e5e9571e7ab42724af37294c79b19478a1e1b5a71df177eee7141d42e042f6f4"
},
"after": {
"prometeu": "73101a42ed5f2a22ad74fd639498d424c070a712a3bce32a9cec6fab3d5bdd80",
"prometeu-runtime": "ee00a587eb48030d1455d3c9bedd784ab620309a09877b50fe3641ae502635df",
"prometeu-headless": "e5e9571e7ab42724af37294c79b19478a1e1b5a71df177eee7141d42e042f6f4"
}
}
@@ -0,0 +1,3 @@
rustc 1.98.1 (48a229cea 2026-09-01)
cargo 1.98.1 (797e8a9bc 2026-08-05)
cargo-dist 0.30.3
@@ -0,0 +1,79 @@
{
"sourceHead": "49d7fca0b725a0a261cda09bf5e924102c84fe31",
"implementation": "qualified as an uncommitted checkout; delta in qualification/implementation.patch",
"decision": "DEC-0071",
"plan": "PLN-0202",
"scope": "Runtime/headless only. No Studio source/build/gates executed.",
"checks": {
"workspace": {
"passed": 1125,
"failed": 0,
"ignored": 16,
"suites": 60
},
"release": {
"passed": 89,
"failed": 0,
"ignored": 4,
"suites": 10
},
"clippy": {
"result": "passed",
"logSha256": "47bf8a993b7cac246fb86835dd5a114a585cd6d1dd676b0ac507f10be3e78084"
},
"format": {
"result": "passed",
"logSha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
},
"packaged": {
"passed": 4,
"failed": 0,
"ignored": 0,
"installation": "/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/dist-staging/qualification/PLN-0202"
}
},
"preFixControlledRegression": {
"profile": "release",
"result": "failed as expected",
"error": "FrameAdvanceWatchdogExpired",
"hostTickLimit": 100000,
"evidence": "qualification/red-controlled-release.log"
},
"nativeBlockedIO": "Native escalation/action_required precedes the 2 s owner guard; worker lock retained until explicit test-controlled cessation.",
"outerGuardQualification": "Explicit-instant tests establish non-resetting timer, bounded quantum and existing native error snapshot/paused cleanup.",
"distribution": {
"builder": "cargo-dist 0.30.3",
"target": "aarch64-apple-darwin",
"profile": "dist",
"archive": "/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/target/distrib/prometeu-cli-aarch64-apple-darwin.zip",
"archiveSha256": "05b0e38f797bc6d24cd69aeb7f6cad9ae224cb2308390a084634dfebe5e8f2f7",
"installation": "/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/dist-staging/qualification/PLN-0202",
"installedSha256": {
"prometeu": "bb245dd057bbc910053b63c55b75a573ab4e9c9a02b7c79ba89e659bea8e85c3",
"prometeu-runtime": "ee00a587eb48030d1455d3c9bedd784ab620309a09877b50fe3641ae502635df",
"prometeu-headless": "18423f798ab28bbd38c12a7ee46459f3ef3d08876cc64327952f57be041fc5df",
"headless-protocol/request.schema.json": "554960a1c6c1304da32753937b899b51ac658cae4b9d96927f5a384325ce2ae2",
"headless-protocol/response.schema.json": "7a8a0fe70a6864203b771e0564dc4227b768213d2368c5b162c892c55c5e186b",
"11a-headless-automation-protocol.md": "2c5391fdbeb35964717f2af1f994b5c81b1b4278641fece17ccdc3fb6b766a6e"
},
"retainedArchive": "/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/dist-staging/qualification/PLN-0202/prometeu-cli-aarch64-apple-darwin.zip"
},
"stableInstallation": {
"unchanged": true,
"before": {
"prometeu": "73101a42ed5f2a22ad74fd639498d424c070a712a3bce32a9cec6fab3d5bdd80",
"prometeu-runtime": "ee00a587eb48030d1455d3c9bedd784ab620309a09877b50fe3641ae502635df",
"prometeu-headless": "e5e9571e7ab42724af37294c79b19478a1e1b5a71df177eee7141d42e042f6f4"
},
"after": {
"prometeu": "73101a42ed5f2a22ad74fd639498d424c070a712a3bce32a9cec6fab3d5bdd80",
"prometeu-runtime": "ee00a587eb48030d1455d3c9bedd784ab620309a09877b50fe3641ae502635df",
"prometeu-headless": "e5e9571e7ab42724af37294c79b19478a1e1b5a71df177eee7141d42e042f6f4"
}
},
"platformLimit": "macOS arm64 only; no physical power-cut or other-target qualification",
"ignoredWorkspaceTests": "16 ignored by the generic run; the four packaged cases were separately executed successfully. Other manual/resource/device cases remain ignored.",
"baseline": "baseline/review-summary.json",
"sourceFingerprints": "qualification/source-sha256.json",
"docsValidation": "qualification/docs-check.json"
}
@@ -0,0 +1,73 @@
# Runtime qualification: reopened memcard first-frame progress
Owner: runtime/headless. Provider correction and native qualification complete.
## Qualified installation
Use the extracted installation at:
```text
/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/dist-staging/qualification/PLN-0202
```
Invoke its dispatcher as `prometeu headless --stdio`. It advertises the existing
protocol 1.2 with explicit `memcard` and `log_read` negotiation. No protocol schema,
guest ABI, guest budget or replay policy was changed.
SHA-256 of `prometeu-headless`:
```text
18423f798ab28bbd38c12a7ee46459f3ef3d08876cc64327952f57be041fc5df
```
Retained archive: `prometeu-cli-aarch64-apple-darwin.zip` in the installation above.
Archive SHA-256:
```text
05b0e38f797bc6d24cd69aeb7f6cad9ae224cb2308390a084634dfebe5e8f2f7
```
[Complete fingerprints](evidence/qualification/distribution.json) identify the
dispatcher, runtime binary, schemas and packaged spec. The selected stable
installation has the same binary fingerprints as before this work.
## Corrected behavior
When successful bootstrap is blocked on its native publication, the headless
owner waits for lane progress outside firmware/VM ticks, within the original
advance. Requested waits are at most 5 ms, with an immutable outer guard of 2 s.
Native cancellation at 500 ms and escalation at 1 s keep their original request
admission time and take precedence. Native media action and original errors retain
their existing classification and resource ownership.
The 100,000 firmware-tick watchdog remains. Ordinary asynchronous gameplay saves
do not invoke this bootstrap wait. Boot still stops before guest execution;
frame advancement and cancellation retain their published boundaries.
## Native evidence
- Controlled old optimized host: watchdog expires while presentation write is held.
- Corrected host: controlled completion, native error, queued publication,
blocked IO with retained lock, immutable outer deadline and unrelated gameplay
commit cases pass.
- Neutral writer creates/commits data; a new-process reader publishes presentation
and completes exactly one first `advance(1)` with correct prior payload, paused
state, no guest fault and canonical capture. Same/changed app versions pass.
- Original no-presentation reader still verifies readback without image mutation.
- Workspace: 1,125 passed, 16 ignored; scoped release: 89 passed, 4 ignored;
separately executed packaged cases: 4 passed, zero ignored/failures.
- Formatter and strict workspace clippy pass.
See [summary](evidence/summary.json), [packaged results](evidence/qualification/packaged.log)
and [source delta](evidence/qualification/implementation.patch). Qualification used
an uncommitted checkout based on `49d7fca0b725a0a261cda09bf5e924102c84fe31`;
fingerprints identify the qualified delivery independently of a commit.
## Consumer ownership
The Studio AI owns selecting this qualification installation in its own context
and rerunning its unchanged consumer pilot and runner/UI/MCP gates. Those gates
were not executed or declared passed by the runtime delivery. No Studio/game
sources, consumer configuration or selected stable install were changed here.
Provider closure is independent of consumer acceptance. This handoff is a local
artifact; no external message was sent automatically.
@@ -371,6 +371,21 @@ and an explicit player policy through `boot_with_memcard_choice`. Its boot loop
waits for actual worker progress with a bounded watchdog timeout; frame execution
remains independent of real-time pacing.
During a headless frame advance, a successful bootstrap hook may still depend on
its native presentation publication. Only while that dependency blocks the active
VM and the corresponding IO remains queued or running, the host owner waits on
the shared lane's progress signal, outside firmware/VM ticks. Each requested wait
is at most 5 ms. Polling preserves the request's original 500 ms cancellation and
1 s stop/escalation deadlines. A single additional 2 s owner deadline starts on
first entry to this wait within an advance and never resets on wake or reentry.
It does not extend the native deadlines. Native media action stops the advance
with exact progress; if the dependency outlives the owner deadline without a
terminal boundary, it returns a native `memcard_error` for `advance` with reason
`restart_required` and the current media state. Neither outcome confirms IO
cessation or releases worker-owned buffers, media or locks. An ordinary gameplay
commit that does not block the VM does not activate this wait. Pure IO polling
and waiting do not advance guest counters or input and do not pace game frames.
Before guest boot, firmware presents persistent, fresh-memory-only and (when
available) existing-save-memory-only choices. Choosing no card does not bypass
snapshot reservation. Leaving a resident game with dirty RAM requires an explicit
@@ -326,6 +326,17 @@ wall-clock timeout.
the number of firmware ticks spent advancing one logical frame. Its limit is
tooling policy, not a guest cycle budget, runtime fault, or wall-clock
performance requirement.
- If a successful memcard bootstrap still blocks the active VM on its queued or
running native publication, the headless owner coordinates lane progress outside
machine ticks, in requested waits of at most 5 ms. The same advance retains its
request and a single 2 s outer deadline from first wait admission; wakes/reentry
do not reset it. Native 500 ms cancellation and 1 s escalation remain authoritative.
A native action-required boundary takes precedence; unresolved IO at the outer
deadline returns a memcard `restart_required` host error with a native snapshot.
Every return pauses execution and clears the host's step request. IO-only polls
and waits do not add guest ticks/frames, enlarge the 100,000 firmware-tick
watchdog, rerun bootstrap, or synchronize unrelated gameplay commits. Waiting
does not establish IO cessation or permit release of worker-owned resources.
- `capture_frame()` returns an owned clone of the canonical frame paired with
the latest successful advance. The explicit `{logical_frame_index, FrameId}`
pair is authoritative; no numeric equality or fixed offset is implied.
@@ -320,6 +320,22 @@ as a game frame. Idle IO polling leaves guest counters/input unchanged. Reconcil
accepts no replacement path, validates expected identity before changes, preserves
RAM/continuation/original retained results and does not rerun initialization.
When successful bootstrap remains blocked by its pending native publication, the
owner coordinates lane progress within the same advance, outside machine ticks,
with requested waits of at most 5 ms. This does not apply to an unrelated gameplay
commit. Native deadlines remain 500 ms for cancellation and 1 s for stop/escalation,
measured from the original request admission. One additional 2 s deadline from
first wait entry in an `advance_frame` does not reset on wake/reentry or extend
those deadlines. Existing native action-required/fault boundaries take precedence.
If the dependency remains pending at the outer deadline without such a boundary,
the advance returns `stop:host_error`, exact known `completed` progress, and
`error.code:memcard_error` with `details.operation:advance`,
`details.reason:restart_required` and `details.state` holding the native snapshot.
The guest finishes paused with the host step request cleared. This preserves
worker ownership until actual cessation, the 100,000-tick frame watchdog, transport
responsiveness and cancellation between frames; it introduces no intraframe
cancellation, guest fault, simulated progress, command replay or new protocol shape.
Runtime qualification uses neutral PBX/ABI fixtures, real distinct processes and
an isolated extracted distribution. It proves SUCCESS, termination, exact readback
without resave and stable appId across cartridge versions. Consumer source-language