diff --git a/crates/console/prometeu-hal/src/log/log_service.rs b/crates/console/prometeu-hal/src/log/log_service.rs index 6002228..18fcd04 100644 --- a/crates/console/prometeu-hal/src/log/log_service.rs +++ b/crates/console/prometeu-hal/src/log/log_service.rs @@ -57,6 +57,21 @@ impl LogService { self.events.iter().filter(|e| e.seq > seq).cloned().collect() } + /// Non-destructive page in native sequence order. A null cursor includes zero. + pub fn get_page(&self, after: Option, limit: usize) -> Vec { + self.events + .iter() + .filter(|event| after.is_none_or(|seq| event.seq > seq)) + .take(limit) + .cloned() + .collect() + } + + /// Retained bounds, independent of any reader's progress. + pub fn sequence_bounds(&self) -> (Option, Option) { + (self.events.front().map(|event| event.seq), self.last_seq()) + } + pub fn last_seq(&self) -> Option { self.events.back().map(|e| e.seq) } @@ -107,4 +122,35 @@ mod tests { assert_eq!(after[0].msg, "Log 3"); assert_eq!(after[1].msg, "Log 4"); } + + #[test] + fn pages_preserve_zero_requery_and_retained_bounds() { + let mut service = LogService::new(3); + assert_eq!(service.sequence_bounds(), (None, None)); + assert!(service.get_page(None, 2).is_empty()); + for i in 0..3 { + service.log(i, i, LogLevel::Info, LogSource::Pos, 7, format!("{i}")); + } + assert_eq!(service.sequence_bounds(), (Some(0), Some(2))); + for _ in 0..2 { + let page = service.get_page(None, 2); + assert_eq!(page.iter().map(|event| event.seq).collect::>(), vec![0, 1]); + } + assert_eq!(service.get_page(Some(1), 2)[0].seq, 2); + assert!(service.get_page(Some(2), 2).is_empty()); + service.log(3, 3, LogLevel::Info, LogSource::Pos, 7, "next".into()); + assert_eq!(service.sequence_bounds(), (Some(1), Some(3))); + assert_eq!(service.get_page(Some(2), 2)[0].seq, 3); + assert_eq!(service.get_page(None, 10).len(), 3); + } + + #[test] + fn page_cursors_preserve_large_unsigned_sequences() { + let mut service = LogService::new(3); + service.next_seq = u64::MAX - 2; + service.log(0, 0, LogLevel::Info, LogSource::Pos, 0, "first".into()); + service.log(0, 0, LogLevel::Info, LogSource::Pos, 0, "second".into()); + assert_eq!(service.get_page(Some(u64::MAX - 2), 1)[0].seq, u64::MAX - 1); + assert!(service.get_page(Some(u64::MAX), 1).is_empty()); + } } diff --git a/crates/console/prometeu-system/src/os/system_os.rs b/crates/console/prometeu-system/src/os/system_os.rs index d1ac08a..3d2f85c 100644 --- a/crates/console/prometeu-system/src/os/system_os.rs +++ b/crates/console/prometeu-system/src/os/system_os.rs @@ -170,6 +170,16 @@ impl SystemOS { self.log_service.get_after(seq) } + /// Coherent non-destructive page and retained bounds; does not execute the VM. + pub fn log_snapshot( + &self, + after: Option, + limit: usize, + ) -> (Vec, Option, Option) { + let (oldest, newest) = self.log_service.sequence_bounds(); + (self.log_service.get_page(after, limit), oldest, newest) + } + pub fn frame_index(&mut self) -> u64 { self.vm().logical_frame_index() } diff --git a/crates/host/prometeu-host-headless/src/automation/mod.rs b/crates/host/prometeu-host-headless/src/automation/mod.rs index 4b74d2b..1689a7a 100644 --- a/crates/host/prometeu-host-headless/src/automation/mod.rs +++ b/crates/host/prometeu-host-headless/src/automation/mod.rs @@ -106,6 +106,7 @@ fn read_commands( ) -> io::Result<()> { let mut initialized = false; let mut memcard = false; + let mut log_read = false; loop { let bytes = match read_line(&mut input, limits.max_command_bytes)? { Line::Eof => break, @@ -144,6 +145,16 @@ fn read_commands( continue; } }; + if matches!(command, Command::GetLogs(_)) && !log_read { + output.reply( + Some(&id), + Err(WireError::new( + "unsupported_capability", + "negotiate minor 1.2 and require log_read first", + )), + )?; + continue; + } if command.needs_memcard() && !memcard { output.reply( Some(&id), @@ -180,12 +191,18 @@ fn read_commands( && params.required_capabilities.iter().any(|c| c == "memcard") { Err(WireError::new("incompatible_version", "memcard requires protocol minor >= 1")) + } else if params.protocol_version.minor < 2 + && params.required_capabilities.iter().any(|c| c == "log_read") + { + Err(WireError::new("incompatible_version", "log_read requires protocol minor >= 2")) } else { initialized = true; memcard = params.protocol_version.minor >= 1 && params.required_capabilities.iter().any(|c| c == "memcard"); + log_read = params.protocol_version.minor >= 2 + && params.required_capabilities.iter().any(|c| c == "log_read"); Ok( - json!({"protocolVersion":{"major":1,"minor":params.protocol_version.minor.min(1)},"capabilities":CAPABILITIES}), + json!({"protocolVersion":{"major":1,"minor":params.protocol_version.minor.min(2)},"capabilities":CAPABILITIES}), ) }; output.reply(Some(&id), result)?; @@ -281,6 +298,7 @@ fn execute( } Command::GetState => Ok(wire::state(host.get_state())), Command::GetFault => Ok(host.get_fault().as_ref().map(wire::fault).unwrap_or(Value::Null)), + Command::GetLogs(params) => wire::logs(host, params, &output.session), Command::Capture => host.capture_frame().map_err(wire::host_error).and_then(wire::capture), Command::Advance(p) => { let mut result = json!({"requested":p.frames,"completed":0,"stop":"completed"}); @@ -339,7 +357,7 @@ pub fn serve( let output = Arc::new(Output { writer: Mutex::new(writer), session, limit: limits.max_response_bytes }); output.send( - json!({"type":"hello","sessionId":output.session,"protocolVersion":{"major":1,"minor":1}, + json!({"type":"hello","sessionId":output.session,"protocolVersion":{"major":1,"minor":2}, "runtimeVersion":runtime_version,"capabilities":CAPABILITIES,"limits":limits}), )?; let control = Arc::new(Mutex::new(Control::default())); @@ -476,7 +494,7 @@ mod tests { "../../../../../devtools/headless-protocol/requests.json" )) .unwrap(); - assert_eq!(requests.len(), 21); + assert!(!requests.is_empty()); for request in requests { wire::parse(serde_json::from_value(request).unwrap()).unwrap(); } diff --git a/crates/host/prometeu-host-headless/src/automation/wire.rs b/crates/host/prometeu-host-headless/src/automation/wire.rs index 1a0a4eb..5521a71 100644 --- a/crates/host/prometeu-host-headless/src/automation/wire.rs +++ b/crates/host/prometeu-host-headless/src/automation/wire.rs @@ -22,6 +22,7 @@ pub const CAPABILITIES: &[&str] = &[ "capture", "get_state", "get_fault", + "log_read", "cancel", "shutdown", "memcard", @@ -139,6 +140,19 @@ pub(super) struct Advance { pub frames: u64, } +#[derive(Debug, Deserialize)] +#[serde(deny_unknown_fields, rename_all = "camelCase")] +pub(super) struct GetLogs { + // Explicit deserializer makes the nullable field required, including on first read. + #[serde(deserialize_with = "nullable_cursor")] + pub after_sequence: Option, + pub limit: u16, +} + +fn nullable_cursor<'de, D: serde::Deserializer<'de>>(d: D) -> Result, D::Error> { + Option::::deserialize(d) +} + #[derive(Debug, Deserialize)] #[serde(deny_unknown_fields, rename_all = "camelCase")] pub(super) struct Cancel { @@ -203,6 +217,7 @@ pub(super) enum Command { Capture, GetState, GetFault, + GetLogs(GetLogs), Cancel(Cancel), Shutdown(Teardown), } @@ -247,6 +262,13 @@ pub(super) fn parse(req: Request) -> Result<(String, Command), WireError> { Command::Boot(p) } "advance" => Command::Advance(params(req.params)?), + "get_logs" => { + let p: GetLogs = params(req.params)?; + if !(1..=1024).contains(&p.limit) { + return Err(WireError::new("invalid_params", "limit must be 1..1024")); + } + Command::GetLogs(p) + } "reset" => Command::Reset(params(req.params)?), "shutdown" => Command::Shutdown(params(req.params)?), "memcard_mount" => { @@ -357,6 +379,48 @@ pub(super) fn state(s: HostState) -> Value { "status":status_name(s.status)}) } +pub(super) fn logs( + host: &crate::HeadlessHost, + params: GetLogs, + session: &str, +) -> Result { + let (events, oldest, newest) = + host.log_snapshot(params.after_sequence, usize::from(params.limit)); + if params.after_sequence.is_some_and(|after| newest.is_none_or(|newest| after > newest)) { + return Err(WireError::new("invalid_cursor", "afterSequence exceeds the log stream")); + } + let gap = oldest.is_some_and(|oldest| match params.after_sequence { + None => oldest > 0, + Some(after) => after.checked_add(1).is_some_and(|next| next < oldest), + }); + let next = events.last().map(|event| event.seq).or(params.after_sequence); + Ok( + json!({"sessionId":session,"logEpoch":0,"events":events.iter().map(log_event).collect::>(), + "oldestSequence":oldest,"newestSequence":newest,"nextAfterSequence":next, + "gap":gap,"overflow":oldest.is_some_and(|oldest| oldest > 0)}), + ) +} + +fn log_event(event: &prometeu_hal::log::LogEvent) -> Value { + use prometeu_hal::log::{LogLevel, LogSource}; + let level = match event.level { + LogLevel::Trace => "trace", + LogLevel::Debug => "debug", + LogLevel::Info => "info", + LogLevel::Warn => "warn", + LogLevel::Error => "error", + }; + let (source, app_id) = match event.source { + LogSource::Pos => ("pos", None), + LogSource::Hub => ("hub", None), + LogSource::Vm => ("vm", None), + LogSource::Fs => ("fs", None), + LogSource::App { app_id } => ("app", Some(app_id)), + }; + json!({"sequence":event.seq,"frame":event.frame,"timestampMs":event.ts_ms, + "level":level,"source":source,"appId":app_id,"tag":event.tag,"message":event.msg}) +} + pub(super) fn fault(report: &CrashReport) -> Value { let mut result = json!({"kind":report.kind(),"pc":report.pc(),"summary":report.summary()}); match report { @@ -402,3 +466,105 @@ pub(super) fn capture(c: CapturedFrame) -> Result { "width":width,"height":height,"stridePixels":frame.stride_pixels,"pixelFormat":"RGBA8888", "logicalFrameIndex":c.logical_frame_index,"frameId":frame.frame_id.get()})) } + +#[cfg(test)] +mod log_tests { + use super::*; + use prometeu_hal::log::{LogEvent, LogLevel, LogSource}; + + #[test] + fn oversized_native_event_is_an_error_without_partial_result() { + let event = LogEvent { + seq: 0, + frame: 0, + ts_ms: 0, + level: LogLevel::Error, + source: LogSource::Vm, + tag: 0, + msg: "x".repeat(8192), + }; + let output = super::super::Output { + writer: std::sync::Mutex::new(Vec::new()), + session: "session".into(), + limit: 4096, + }; + output.reply(Some("logs"), Ok(json!({"events":[log_event(&event)]}))).unwrap(); + let bytes = output.writer.into_inner().unwrap(); + assert!(bytes.len() <= 4097); + let response: Value = serde_json::from_slice(&bytes).unwrap(); + assert_eq!(response["error"]["code"], "response_too_large"); + assert_eq!(response["requestId"], "logs"); + assert!(response.get("result").is_none()); + } + + #[test] + fn native_records_preserve_unsigned_maxima_and_typed_sources() { + for (source, name, app_id) in [ + (LogSource::Pos, "pos", None), + (LogSource::Hub, "hub", None), + (LogSource::Vm, "vm", None), + (LogSource::Fs, "fs", None), + (LogSource::App { app_id: u32::MAX }, "app", Some(u32::MAX)), + ] { + for (level, level_name) in [ + (LogLevel::Trace, "trace"), + (LogLevel::Debug, "debug"), + (LogLevel::Info, "info"), + (LogLevel::Warn, "warn"), + (LogLevel::Error, "error"), + ] { + let event = LogEvent { + seq: u64::MAX, + frame: u64::MAX, + ts_ms: u64::MAX, + level, + source, + tag: u16::MAX, + msg: "complete native message".into(), + }; + let encoded = log_event(&event); + let decoded: Value = + serde_json::from_slice(&serde_json::to_vec(&encoded).unwrap()).unwrap(); + for key in ["sequence", "frame", "timestampMs"] { + assert_eq!(decoded[key].as_u64(), Some(u64::MAX)); + } + assert_eq!(decoded["level"], level_name); + assert_eq!(decoded["source"], name); + assert_eq!(decoded["appId"], json!(app_id)); + assert_eq!(decoded["tag"], u16::MAX); + assert_eq!(decoded["message"], event.msg); + } + } + } + + #[test] + fn required_nullable_cursor_and_limit_reject_malformed_values() { + for value in [ + json!({"limit":1}), + json!({"afterSequence":null}), + json!({"afterSequence":-1,"limit":1}), + json!({"afterSequence":1.5,"limit":1}), + json!({"afterSequence":"0","limit":1}), + json!({"afterSequence":null,"limit":0}), + json!({"afterSequence":null,"limit":1025}), + json!({"afterSequence":null,"limit":1,"filter":"app"}), + ] { + assert!( + parse(Request { + request_id: "logs".into(), + command: "get_logs".into(), + params: value + }) + .is_err() + ); + } + assert!( + parse(Request { + request_id: "logs".into(), + command: "get_logs".into(), + params: json!({"afterSequence":u64::MAX,"limit":1024}) + }) + .is_ok() + ); + } +} diff --git a/crates/host/prometeu-host-headless/src/host.rs b/crates/host/prometeu-host-headless/src/host.rs index f2674b1..f01ed2d 100644 --- a/crates/host/prometeu-host-headless/src/host.rs +++ b/crates/host/prometeu-host-headless/src/host.rs @@ -178,6 +178,15 @@ impl HeadlessHost { self.controlled_wall_clock.as_deref() } + /// Observe native log history without advancing, draining or changing lifecycle. + pub fn log_snapshot( + &self, + after: Option, + limit: usize, + ) -> (Vec, Option, Option) { + 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 diff --git a/crates/tools/prometeu-cli/tests/automation_process.rs b/crates/tools/prometeu-cli/tests/automation_process.rs index 0bff9b1..9c87fa9 100644 --- a/crates/tools/prometeu-cli/tests/automation_process.rs +++ b/crates/tools/prometeu-cli/tests/automation_process.rs @@ -1,7 +1,7 @@ use base64::{Engine as _, engine::general_purpose::STANDARD}; use prometeu_bytecode::SourceSpan; use prometeu_bytecode::assembler::assemble; -use prometeu_bytecode::model::{DebugInfo, Export, SyscallDecl}; +use prometeu_bytecode::model::{ConstantPoolEntry, DebugInfo, Export, SyscallDecl}; use prometeu_bytecode::registry::FunctionDecl; use prometeu_host_headless::{AdvanceFramesStop, HeadlessHost}; use prometeu_test_support::program::{TestProgram, int64_signature}; @@ -223,6 +223,48 @@ fn cartridge_bytes(code: Vec, gfx: bool) -> TempDir { fn colored_cart() -> TempDir { cartridge("PUSH_I64 4278190335\nHOSTCALL 0\nRET\n", true) } + +fn logging_cart(messages_per_frame: usize, message: &str) -> TempDir { + let dir = TempDir::new(); + let code = assemble(&format!( + "{}RET\n", + "PUSH_I64 2\nPUSH_I64 41000\nPUSH_CONST 0\nHOSTCALL 0\n".repeat(messages_per_frame) + )) + .unwrap(); + let mut module = TestProgram::single(code, int64_signature(0, 0), 0, 3); + module.const_pool = vec![ConstantPoolEntry::String(message.into())]; + module.exports = vec![Export { symbol: "main".into(), func_idx: 0 }]; + module.syscalls = vec![SyscallDecl { + module: "log".into(), + name: "write_tag".into(), + version: 1, + arg_slots: 3, + ret_slots: 0, + }]; + fs::write(dir.0.join("program.pbx"), module.serialize()).unwrap(); + fs::write( + dir.0.join("manifest.json"), + serde_json::to_vec(&json!({ + "magic":"PMTU","cartridge_version":1,"app_id":41,"title":"Native log test", + "app_version":"0.1.0","app_mode":"Game","capabilities":["log"]})) + .unwrap(), + ) + .unwrap(); + dir +} + +fn initialize_logs(client: &mut Client) { + let result = client.ok( + "initialize", + json!({"protocolVersion":{"major":1,"minor":2}, + "requiredCapabilities":["log_read"]}), + ); + assert_eq!(result["protocolVersion"]["minor"], 2); +} + +fn read_log_page(client: &mut Client, after: Value, limit: u16) -> Value { + client.ok("get_logs", json!({"afterSequence":after,"limit":limit})) +} fn boot(client: &mut Client, dir: &TempDir) { client.ok("boot", json!({"path":dir.0})); } @@ -243,7 +285,7 @@ fn png_bytes(capture: &Value) -> Vec { fn handshake_versions_capabilities_and_limits_are_explicit() { let mut c = Client::new(&["--stdio"]); assert_eq!(c.hello["runtimeVersion"], env!("CARGO_PKG_VERSION")); - assert_eq!(c.hello["protocolVersion"], json!({"major":1,"minor":1})); + assert_eq!(c.hello["protocolVersion"], json!({"major":1,"minor":2})); assert_eq!( c.hello["limits"], json!({"maxFrames":600,"maxCommandBytes":65536,"maxResponseBytes":33554432, @@ -269,7 +311,7 @@ fn handshake_versions_capabilities_and_limits_are_explicit() { "initialize", json!({"protocolVersion":{"major":1,"minor":42},"requiredCapabilities":[]}) )["protocolVersion"]["minor"], - 1 + 2 ); assert_eq!( c.call( @@ -432,11 +474,15 @@ fn faults_and_boot_failures_are_structured_not_log_parsing() { fn conflicting_work_is_rejected_and_cancellation_reports_partial_progress() { let dir = colored_cart(); let mut c = Client::new(&["--stdio", "--max-frames", "100000"]); - c.initialize(); + initialize_logs(&mut c); boot(&mut c, &dir); let advance = c.send("advance", json!({"frames":100000})); assert_eq!(c.event()["type"], "progress"); assert_eq!(c.call("reset", json!({}))["error"]["code"], "busy"); + assert_eq!( + c.call("get_logs", json!({"afterSequence":null,"limit":1}))["error"]["code"], + "busy" + ); c.ok("cancel", json!({"targetRequestId":advance})); let response = c.response(&advance); let result = &response["result"]; @@ -551,6 +597,187 @@ fn missing_binary_and_invalid_cli_limits_fail_explicitly() { } } +#[test] +fn log_read_requires_explicit_capability_and_minor_two() { + for minor in [0, 1, 2] { + let mut c = Client::new(&["--stdio"]); + assert!(c.hello["capabilities"].as_array().unwrap().contains(&json!("log_read"))); + if minor < 2 { + assert_eq!( + c.call( + "initialize", + json!({"protocolVersion":{"major":1,"minor":minor}, + "requiredCapabilities":["log_read"]}) + )["error"]["code"], + "incompatible_version" + ); + } + let initialized = c.ok( + "initialize", + json!({"protocolVersion":{"major":1,"minor":minor}, + "requiredCapabilities":[]}), + ); + assert_eq!(initialized["protocolVersion"]["minor"], minor); + assert_eq!( + c.call("get_logs", json!({"afterSequence":null,"limit":1}))["error"]["code"], + "unsupported_capability" + ); + assert_eq!(c.ok("get_state", json!({}))["logicalFrameIndex"], 0); + c.close(); + } +} + +#[test] +fn native_log_pages_are_read_only_replayable_and_survive_reset() { + let dir = logging_cart(2, "{\"native\":\"é\"}"); + let mut c = Client::new(&["--stdio"]); + initialize_logs(&mut c); + let initial = read_log_page(&mut c, Value::Null, 1); + assert_eq!(initial["events"][0]["sequence"], 0); + assert_eq!(initial["events"][0]["source"], "pos"); + assert_eq!(initial["events"][0]["appId"], Value::Null); + assert_eq!(initial["sessionId"], c.hello["sessionId"]); + assert_eq!(initial["logEpoch"], 0); + assert_eq!(initial["gap"], false); + assert_eq!(initial["overflow"], false); + boot(&mut c, &dir); + c.ok("advance", json!({"frames":2})); + let state = c.ok("get_state", json!({})); + let fault = c.ok("get_fault", json!({})); + let all = read_log_page(&mut c, Value::Null, 1024); + let native = all["events"].as_array().unwrap(); + let app: Vec<_> = native.iter().filter(|event| event["source"] == "app").collect(); + assert_eq!(app.len(), 4); + assert!(app.iter().all(|event| event["tag"] == 41000 + && event["appId"] == 41 + && event["level"] == "info" + && event["message"] == "{\"native\":\"é\"}")); + let mut cursor = Value::Null; + let mut paged = Vec::new(); + loop { + let page = read_log_page(&mut c, cursor.clone(), 2); + assert_eq!(page, read_log_page(&mut c, cursor.clone(), 2)); + paged.extend(page["events"].as_array().unwrap().iter().cloned()); + cursor = page["nextAfterSequence"].clone(); + if cursor == page["newestSequence"] { + break; + } + } + assert_eq!(&paged, native); + let empty = read_log_page(&mut c, cursor.clone(), 1); + assert!(empty["events"].as_array().unwrap().is_empty()); + assert_eq!(empty["nextAfterSequence"], cursor); + assert_eq!(state, c.ok("get_state", json!({}))); + assert_eq!(fault, c.ok("get_fault", json!({}))); + assert_eq!( + c.call("get_logs", json!({"afterSequence":u64::MAX,"limit":1}))["error"]["code"], + "invalid_cursor" + ); + c.ok("reset", json!({})); + let reset = read_log_page(&mut c, Value::Null, 1024); + assert_eq!(&reset["events"].as_array().unwrap()[..native.len()], native); + let after_reset = read_log_page(&mut c, cursor, 1024); + assert!(!after_reset["events"].as_array().unwrap().is_empty()); + assert_eq!(after_reset["gap"], false); + assert_eq!(after_reset["logEpoch"], 0); + assert_eq!(after_reset["sessionId"], all["sessionId"]); + c.close(); + let mut other = Client::new(&["--stdio"]); + initialize_logs(&mut other); + let fresh = read_log_page(&mut other, Value::Null, 1); + assert_ne!(fresh["sessionId"], all["sessionId"]); + assert_eq!(fresh["events"][0]["sequence"], 0); + assert_eq!( + other.call("get_logs", json!({"afterSequence":all["newestSequence"],"limit":1}))["error"]["code"], + "invalid_cursor" + ); + other.close(); +} + +#[test] +fn timely_readers_outlive_ring_capacity_while_stale_cursors_report_gaps() { + let dir = logging_cart(10, "retention"); + let mut c = Client::new(&["--stdio"]); + initialize_logs(&mut c); + boot(&mut c, &dir); + let mut cursor = Value::Null; + let mut count = 0; + let mut saw_eviction = false; + for _ in 0..5 { + assert_eq!(c.ok("advance", json!({"frames":100}))["completed"], 100); + loop { + let page = read_log_page(&mut c, cursor.clone(), 128); + assert_eq!(page["gap"], false); + saw_eviction |= page["overflow"] == true; + for event in page["events"].as_array().unwrap() { + assert_eq!(event["sequence"].as_u64().unwrap(), count); + count += 1; + } + cursor = page["nextAfterSequence"].clone(); + if cursor == page["newestSequence"] { + break; + } + } + } + assert!(count > 4096 && saw_eviction); + for stale in [Value::Null, json!(0)] { + let page = read_log_page(&mut c, stale, 1); + assert_eq!(page["gap"], true); + assert_eq!(page["overflow"], true); + assert!(page["oldestSequence"].as_u64().unwrap() > 0); + assert_eq!(page["events"][0]["sequence"], page["oldestSequence"]); + } + let empty = read_log_page(&mut c, cursor.clone(), 1); + assert_eq!(empty["gap"], false); + assert_eq!(empty["overflow"], true); + assert_eq!(empty["nextAfterSequence"], cursor); + c.close(); +} + +#[test] +fn bounded_log_responses_can_be_retried_without_draining() { + let dir = logging_cart(10, &"x".repeat(200)); + let mut c = Client::new(&["--stdio", "--max-response-bytes", "4096"]); + initialize_logs(&mut c); + boot(&mut c, &dir); + c.ok("advance", json!({"frames":5})); + let state = c.ok("get_state", json!({})); + let response = c.call("get_logs", json!({"afterSequence":null,"limit":1024})); + assert_eq!(response["error"]["code"], "response_too_large"); + assert!(response.get("result").is_none()); + let first = read_log_page(&mut c, Value::Null, 1); + assert_eq!(first["events"][0]["sequence"], 0); + assert_eq!(first, read_log_page(&mut c, Value::Null, 1)); + assert_eq!(state, c.ok("get_state", json!({}))); + c.close(); +} + +#[test] +fn log_observation_preserves_existing_guest_length_and_rate_limits() { + let dir = logging_cart(12, &"x".repeat(300)); + let mut c = Client::new(&["--stdio"]); + initialize_logs(&mut c); + boot(&mut c, &dir); + c.ok("advance", json!({"frames":1})); + let page = read_log_page(&mut c, Value::Null, 1024); + let app: Vec<_> = page["events"] + .as_array() + .unwrap() + .iter() + .filter(|event| event["source"] == "app") + .collect(); + let messages: Vec<_> = app.iter().filter(|event| event["tag"] == 41000).collect(); + assert_eq!(messages.len(), 10); + assert!(messages.iter().all(|event| event["message"].as_str().unwrap().len() == 256)); + assert_eq!(app.len(), 11); + assert!(app.iter().any(|event| event["tag"] == 0 + && event["level"] == "warn" + && event["message"] == "App exceeded log limit per frame")); + assert_eq!(page["gap"], false); + assert_eq!(page["overflow"], false); + c.close(); +} + #[test] fn schemas_and_distributed_request_fixtures_are_consistent() { let request: Value = serde_json::from_str(include_str!( @@ -616,3 +843,38 @@ fn packaged_installation_smoke() { c.input.take(); c.wait_exit(); } + +#[test] +#[ignore = "requires PROMETEU_PROTOCOL_TEST_INSTALL pointing to an isolated installation"] +fn packaged_native_log_observation() { + let installation = PathBuf::from( + std::env::var_os("PROMETEU_PROTOCOL_TEST_INSTALL").expect("set isolated installation path"), + ); + let cwd = TempDir::new(); + let dir = logging_cart(1, "installed native log"); + let mut c = + Client::spawn(&installation.join("prometeu"), &["headless", "--stdio"], Some(&cwd.0)); + initialize_logs(&mut c); + boot(&mut c, &dir); + c.ok("advance", json!({"frames":1})); + let page = read_log_page(&mut c, Value::Null, 1024); + assert_eq!(page["gap"], false); + assert!( + page["events"] + .as_array() + .unwrap() + .iter() + .any(|event| event["source"] == "app" && event["message"] == "installed native log") + ); + let installed_schema: Value = serde_json::from_slice( + &fs::read(installation.join("headless-protocol/response.schema.json")).unwrap(), + ) + .unwrap(); + jsonschema::validator_for(&installed_schema) + .unwrap() + .validate(&json!({ + "type":"response","sessionId":c.hello["sessionId"],"requestId":"logs","result":page, + })) + .unwrap(); + c.close(); +} diff --git a/devtools/headless-protocol/invalid-requests.json b/devtools/headless-protocol/invalid-requests.json index b3dfe93..705dce9 100644 --- a/devtools/headless-protocol/invalid-requests.json +++ b/devtools/headless-protocol/invalid-requests.json @@ -99,5 +99,84 @@ "params": { "anything": true } + }, + { + "requestId": "bad-logs-0", + "command": "get_logs", + "params": { + "limit": 1 + } + }, + { + "requestId": "bad-logs-1", + "command": "get_logs", + "params": { + "afterSequence": null + } + }, + { + "requestId": "bad-logs-2", + "command": "get_logs", + "params": { + "afterSequence": null, + "limit": 0 + } + }, + { + "requestId": "bad-logs-3", + "command": "get_logs", + "params": { + "afterSequence": null, + "limit": 1025 + } + }, + { + "requestId": "bad-logs-4", + "command": "get_logs", + "params": { + "afterSequence": null, + "limit": 1.5 + } + }, + { + "requestId": "bad-logs-5", + "command": "get_logs", + "params": { + "afterSequence": -1, + "limit": 1 + } + }, + { + "requestId": "bad-logs-6", + "command": "get_logs", + "params": { + "afterSequence": 18446744073709551616, + "limit": 1 + } + }, + { + "requestId": "bad-logs-7", + "command": "get_logs", + "params": { + "afterSequence": "0", + "limit": 1 + } + }, + { + "requestId": "bad-logs-8", + "command": "get_logs", + "params": { + "afterSequence": 0.5, + "limit": 1 + } + }, + { + "requestId": "bad-logs-9", + "command": "get_logs", + "params": { + "afterSequence": null, + "limit": 1, + "filter": "app" + } } ] diff --git a/devtools/headless-protocol/request.schema.json b/devtools/headless-protocol/request.schema.json index 890be0f..5b1f800 100644 --- a/devtools/headless-protocol/request.schema.json +++ b/devtools/headless-protocol/request.schema.json @@ -1,7 +1,7 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://prometeu.dev/headless/v1/request.schema.json", - "title": "Prometeu Headless v1.1 Request", + "title": "Prometeu Headless v1.2 Request", "type": "object", "additionalProperties": false, "required": [ @@ -319,6 +319,36 @@ "additionalProperties": false } } + }, + { + "properties": { + "command": { + "const": "get_logs" + }, + "params": { + "type": "object", + "additionalProperties": false, + "required": [ + "afterSequence", + "limit" + ], + "properties": { + "afterSequence": { + "type": [ + "integer", + "null" + ], + "minimum": 0, + "maximum": 18446744073709551615 + }, + "limit": { + "type": "integer", + "minimum": 1, + "maximum": 1024 + } + } + } + } } ], "$defs": { diff --git a/devtools/headless-protocol/requests.json b/devtools/headless-protocol/requests.json index 228678e..b8c6c63 100644 --- a/devtools/headless-protocol/requests.json +++ b/devtools/headless-protocol/requests.json @@ -148,5 +148,42 @@ "params": { "pendingWrites": "wait" } + }, + { + "requestId": "logs-init", + "command": "initialize", + "params": { + "protocolVersion": { + "major": 1, + "minor": 2 + }, + "requiredCapabilities": [ + "log_read" + ] + } + }, + { + "requestId": "logs-first", + "command": "get_logs", + "params": { + "afterSequence": null, + "limit": 1 + } + }, + { + "requestId": "logs-next", + "command": "get_logs", + "params": { + "afterSequence": 0, + "limit": 1024 + } + }, + { + "requestId": "logs-u64", + "command": "get_logs", + "params": { + "afterSequence": 18446744073709551615, + "limit": 128 + } } ] diff --git a/devtools/headless-protocol/response.schema.json b/devtools/headless-protocol/response.schema.json index 544bedb..7a09b62 100644 --- a/devtools/headless-protocol/response.schema.json +++ b/devtools/headless-protocol/response.schema.json @@ -1,7 +1,7 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", - "title": "Prometeu headless server messages v1.1", - "$comment": "Producer schema for supported 1.0/1.1 shapes. Consumers permit compatible minor additions; 64-bit identities require lossless decoding.", + "title": "Prometeu Headless v1.2 Response", + "$comment": "Producer schema for supported 1.0/1.1/1.2 shapes. Consumers permit compatible minor additions; 64-bit identities require lossless decoding.", "oneOf": [ { "type": "object", @@ -179,6 +179,9 @@ }, { "$ref": "#/$defs/memcard" + }, + { + "$ref": "#/$defs/logPage" } ] } @@ -1761,6 +1764,158 @@ "recovery" ], "additionalProperties": false + }, + "logEvent": { + "type": "object", + "properties": { + "sequence": { + "type": "integer", + "minimum": 0, + "maximum": 18446744073709551615 + }, + "frame": { + "type": "integer", + "minimum": 0, + "maximum": 18446744073709551615 + }, + "timestampMs": { + "type": "integer", + "minimum": 0, + "maximum": 18446744073709551615 + }, + "level": { + "enum": [ + "trace", + "debug", + "info", + "warn", + "error" + ] + }, + "source": { + "enum": [ + "pos", + "hub", + "vm", + "fs", + "app" + ] + }, + "appId": { + "type": [ + "integer", + "null" + ], + "minimum": 0, + "maximum": 4294967295 + }, + "tag": { + "type": "integer", + "minimum": 0, + "maximum": 65535 + }, + "message": { + "type": "string" + } + }, + "required": [ + "sequence", + "frame", + "timestampMs", + "level", + "source", + "appId", + "tag", + "message" + ], + "additionalProperties": false, + "allOf": [ + { + "if": { + "properties": { + "source": { + "const": "app" + } + } + }, + "then": { + "properties": { + "appId": { + "type": "integer" + } + } + }, + "else": { + "properties": { + "appId": { + "type": "null" + } + } + } + } + ] + }, + "logPage": { + "type": "object", + "properties": { + "sessionId": { + "type": "string", + "minLength": 1 + }, + "logEpoch": { + "type": "integer", + "minimum": 0, + "maximum": 18446744073709551615 + }, + "events": { + "type": "array", + "maxItems": 1024, + "items": { + "$ref": "#/$defs/logEvent" + } + }, + "oldestSequence": { + "type": [ + "integer", + "null" + ], + "minimum": 0, + "maximum": 18446744073709551615 + }, + "newestSequence": { + "type": [ + "integer", + "null" + ], + "minimum": 0, + "maximum": 18446744073709551615 + }, + "nextAfterSequence": { + "type": [ + "integer", + "null" + ], + "minimum": 0, + "maximum": 18446744073709551615 + }, + "gap": { + "type": "boolean" + }, + "overflow": { + "type": "boolean" + } + }, + "required": [ + "sessionId", + "logEpoch", + "events", + "oldestSequence", + "newestSequence", + "nextAfterSequence", + "gap", + "overflow" + ], + "additionalProperties": false } } } diff --git a/discussion/lessons/DSC-0070-headless-bounded-log-observation/LSN-0074-native-log-retention-and-reader-progress.md b/discussion/lessons/DSC-0070-headless-bounded-log-observation/LSN-0074-native-log-retention-and-reader-progress.md new file mode 100644 index 0000000..9fd770e --- /dev/null +++ b/discussion/lessons/DSC-0070-headless-bounded-log-observation/LSN-0074-native-log-retention-and-reader-progress.md @@ -0,0 +1,122 @@ +--- +id: LSN-0074 +ticket: headless-bounded-log-observation +title: Native log retention and reader progress +created: 2026-11-10 +tags: [runtime, headless, tooling, logging, retention] +--- + +## Context and published result + +The runtime exposes native logs through negotiated headless protocol 1.2 +`log_read` and `get_logs`. This is generic observation over the existing ring and +JSONL execution owner. Assertions, test catalogs and verdicts remain consumer +semantics. No new guest syscall, execution budget, listener or media policy was +introduced, and no Studio files or selected installations were changed. + +Historical source: accepted DEC-0069, executed through PLN-0200 from AGD-0073, +after the user's runtime-only authorization. Those workflow files are disposable. +The normative contract is [Native log observation](../../../docs/specs/runtime/11a-headless-automation-protocol.md#native-log-observation). +This lesson explains the published behavior and its limits. + +## Retention and delivery answer different questions + +A ring must eventually evict old records. That fact alone does not establish +that a reader missed any. The protocol therefore exposes two different facts: + +| Observation | Meaning | +| --- | --- | +| overflow | The process-owned ring has evicted historical records. | +| gap | The requested cursor requires history older than the retained oldest record. | + +For retained oldest sequence 100, afterSequence=150 has no gap, and +afterSequence=99 can read record 100 without loss. A cursor of 98 or null reports +a gap. A reader that consumed records promptly can run beyond the ring's +4096-record capacity with overflow=true and gap=false. Rejecting that combination +would impose an accidental limit on total run length rather than unread backlog. + +The provider returns every native source in order, without filtering by guest tag. +Filtering before cursor validation would hide missing history. Interpretation can +select relevant application/tag records after preserving native continuity. + +## An explicit first cursor preserves sequence zero + +An unsigned exclusive cursor cannot express the position before zero. Null is the +initial position; zero means zero has already been observed. Both cursor and limit +are required parameters. A nonempty page advances to its last returned sequence; +an empty page preserves the input cursor. A cursor beyond the stream is rejected +instead of silently being treated as caught up. + +Requerying is non-destructive and does not execute the guest. Native uint64 +identities and elapsed timestamps remain lossless on the wire; elapsed wall time +is not a deterministic oracle. The adapter must not route these values through a +floating-point number representation. + +## Process identity outlives a VM reset + +Reset preserves SystemOS and its log ring, even though guest frame counters reset. +Clearing logs or incrementing an invented reset epoch would contradict the native +producer. The stream epoch remains zero and native sequence continues. A new +process has a different sessionId and its own sequence zero. Readers bind cursors +and deduplication to session/epoch, not frame number or a portable numeric cursor. + +## A complete ring transcript is not a complete producer transcript + +The existing guest logging path stores at most 10 messages per application/frame +and at most 256 UTF-8 bytes per message. Excess calls are dropped before obtaining +a native sequence; truncation also creates no native gap. Real process qualification +demonstrates 12 attempted calls becoming 10 stored messages plus one native warning, +while gap and overflow both remain false. + +A structured-event consumer must therefore bound its encoded events and validate +its own producer continuity and explicit completion, such as ordinals and final +counts. Missing assertions cannot be detected from the native ring sequence alone. +Those consumer changes are outside this provider delivery. Increasing guest budgets +or adding assertion parsing to the runtime would move the wrong responsibility. + +## Bounded observation requires a page loop + +Negotiate the capability before guest execution. Read after boot, after bounded +frame blocks and after completion/failure when available. Consume all pending +pages to the observed newest sequence before starting another block, preserving +the cursor and original records. Validate session/epoch and gap on every page; +deduplicate already observed native sequences. Historical overflow alone is not +loss. Never replay advancement automatically after a missing response. + +The advertised frame maximum is an admission ceiling, not a safe polling interval: +600 frames at 10 application messages/frame already exceed the ring capacity. +System messages also occupy that ring. Polling cannot promise lossless delivery +for arbitrary rates or an unbounded block. + +The serialized response limit includes the complete envelope. If a page or one +event cannot fit, the provider returns response_too_large without partial records. +A smaller page can be retried without draining or executing anything. Shortening +an event silently would destroy the consumer's ability to validate its payload. + +## Qualification and boundaries + +The HAL, SystemOS and headless suites passed 380 tests; the CLI process suite +passed 25 tests. Three separately selected installation tests passed for native +logs, existing production capture and memcard persistence: 408 passing tests in +these gates. One existing manual memcard latency qualification remained ignored. +The initial process run's three installation skips were subsequently executed. + +Real PBX guest fixtures prove native application records, sequence zero, requery, +empty/future cursors, reset continuity, separate processes, byte bounds, unchanged +producer limits and more than 4096 cumulative records with timely reads. Process +output is checked against the published response schema; typed uint64 maxima and +all native source/level variants also have unit coverage. + +The installation checks used an isolated staging directory of debug binaries, +invoked through the dispatcher from another working directory. They do not claim +a release archive was built or the Studio-selected installation was updated. +Consumer helpers, runner, UI, assertions and their end-to-end qualification remain +consumer work. See [qualification evidence](evidence/qualification.json), the +recorded logs and [wire observations](evidence/wire-observations.json). + +## Implementation references + +- [Native ring](../../../crates/console/prometeu-hal/src/log/log_service.rs). +- [Wire serialization and validation](../../../crates/host/prometeu-host-headless/src/automation/wire.rs). +- [Negotiation and owner dispatch](../../../crates/host/prometeu-host-headless/src/automation/mod.rs). +- [Real process conformance](../../../crates/tools/prometeu-cli/tests/automation_process.rs). diff --git a/discussion/lessons/DSC-0070-headless-bounded-log-observation/evidence/packaged-tests.log b/discussion/lessons/DSC-0070-headless-bounded-log-observation/evidence/packaged-tests.log new file mode 100644 index 0000000..1382b96 --- /dev/null +++ b/discussion/lessons/DSC-0070-headless-bounded-log-observation/evidence/packaged-tests.log @@ -0,0 +1,9 @@ + Finished `test` profile [unoptimized + debuginfo] target(s) in 0.91s + Running tests/automation_process.rs (target/debug/deps/automation_process-018fadef87e61183) + +running 3 tests +test packaged_native_log_observation ... ok +test packaged_installation_smoke ... ok +test memcard_process::packaged_memcard_process_persistence ... ok + +test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured; 25 filtered out; finished in 1.40s diff --git a/discussion/lessons/DSC-0070-headless-bounded-log-observation/evidence/process-tests.log b/discussion/lessons/DSC-0070-headless-bounded-log-observation/evidence/process-tests.log new file mode 100644 index 0000000..04177ad --- /dev/null +++ b/discussion/lessons/DSC-0070-headless-bounded-log-observation/evidence/process-tests.log @@ -0,0 +1,36 @@ + 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 5.59s + Running tests/automation_process.rs (target/debug/deps/automation_process-018fadef87e61183) + +running 28 tests +test handshake_versions_capabilities_and_limits_are_explicit ... ok +test conflicting_work_is_rejected_and_cancellation_reports_partial_progress ... ok +test log_observation_preserves_existing_guest_length_and_rate_limits ... ok +test faults_and_boot_failures_are_structured_not_log_parsing ... ok +test bounded_log_responses_can_be_retried_without_draining ... ok +test idle_eof_and_truncated_eof_close_the_process ... ok +test malformed_fragmented_and_oversized_commands_do_not_desynchronize ... ok +test dispatcher_works_from_a_relocated_installation_and_other_cwd ... 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::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_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 independent_processes_match_pixels_ids_state_and_fault ... ok +test shutdown_and_eof_interrupt_active_work_without_resuming_it ... 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_access_denial_is_typed_and_does_not_create_or_modify_media ... 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_process_ownership_covers_aliases_readers_and_release ... ok +test timely_readers_outlive_ring_capacity_while_stale_cursors_report_gaps ... ok +test memcard_process::memcard_public_distinct_process_save_readback_and_version_identity ... ok +test memcard_process::desktop_dispatch_forwards_explicit_media_without_interpreting_player_policy ... ok +test partial_guest_fault_and_host_watchdog_are_distinct_outcomes ... ok + +test result: ok. 25 passed; 0 failed; 3 ignored; 0 measured; 0 filtered out; finished in 1.62s diff --git a/discussion/lessons/DSC-0070-headless-bounded-log-observation/evidence/qualification.json b/discussion/lessons/DSC-0070-headless-bounded-log-observation/evidence/qualification.json new file mode 100644 index 0000000..c0519ef --- /dev/null +++ b/discussion/lessons/DSC-0070-headless-bounded-log-observation/evidence/qualification.json @@ -0,0 +1,74 @@ +{ + "status": "complete", + "scope": "runtime provider only; Studio untouched", + "sourceRevision": "09d8778f046a2819c50ac786bfb50e958ef5af61", + "gates": [ + { + "command": "cargo test -p prometeu-hal -p prometeu-system -p prometeu-host-headless", + "exitCode": 0, + "passed": 380, + "failed": 0, + "ignored": 1, + "logSha256": "c959ce94316ca9c953e3f337da1bdb0d02c5308c75dfeec2b2a803b1ee38c282", + "rawLogSha256": "e80d2df6721b75a196c90cb0b3d56bf6d8dced951f55d7cf7f41758cc85bb987" + }, + { + "command": "cargo test -p prometeu-cli --test automation_process", + "exitCode": 0, + "passed": 25, + "failed": 0, + "ignored": 3, + "logSha256": "dd69cb68e40660a5a349bc32397fd0c632517a4654a2d20948cad48cbb4d2532", + "rawLogSha256": "7cad6b59819348150867f6d8013958ecc189b3d79c6bbdea3970d1ffdb171ad0" + }, + { + "command": "PROMETEU_PROTOCOL_TEST_INSTALL= cargo test -p prometeu-cli --test automation_process packaged_ -- --ignored", + "exitCode": 0, + "passed": 3, + "failed": 0, + "ignored": 0, + "logSha256": "4900e90b07e68268084b674c05b5959a1c8adef86710582c5dd35f86fa3f8175", + "rawLogSha256": "9511b19fe51b1776e83990737858e2e5df3971023c514cc89bd5b7056a36b78e" + } + ], + "passingTests": 408, + "remainingIgnored": "One pre-existing manual memcard file-host latency qualification. The three installation cases skipped in process-tests were run in packaged-tests.", + "installation": { + "installation": "/var/folders/0t/tfsqc14j5wbgh9h4s4dytwb00000gq/T/prometeu-log-read-58e3d38i", + "profile": "debug", + "kind": "isolated local staging; no release archive or selected installation update", + "sha256": { + "prometeu": "f35eeea1a13b48c382b108a7f516bc4205d635f6a1698e98d2b0acb12df49e58", + "prometeu-runtime": "75e2a2c56d6a00d94bf265d4d0ed507d869e954ebcb26f9711c332a3a6cb5874", + "prometeu-headless": "dce18f2d753c227e291fba41b761df0b6d04155d9fba44f4faed81d308b38212" + } + }, + "checks": { + "cargoFmt": "passed", + "gitDiffCheck": "passed", + "discussionValidate": "validation passed after housekeeping", + "headlessSpecLinks": "passed", + "publishedWorkflowReferences": "none in docs/", + "lessonLinks": "passed" + }, + "sourceSha256": { + "crates/console/prometeu-hal/src/log/log_service.rs": "80b689cc133da4dd52a34834012f12c9ce15892eb109ea7ddc71392faa6cc8dd", + "crates/console/prometeu-system/src/os/system_os.rs": "50d5f71f55b4c40b3ec959aacd91df587f2ffa4cc4f183b1c3343589fabb983a", + "crates/host/prometeu-host-headless/src/automation/mod.rs": "e1107aefc12a5fbebd6d59fdae4e642f2844eada4205c9317589a9cbd45fcba6", + "crates/host/prometeu-host-headless/src/automation/wire.rs": "b779f4d71a472d6bca6008bb217a568c9a7ac5ee9b2b388ed3c30479c85cdafa", + "crates/host/prometeu-host-headless/src/host.rs": "5459b51906cf43342c64ee2ac429d1ccd6274da9418916f5be77a9062c1b0862", + "crates/tools/prometeu-cli/tests/automation_process.rs": "454d791c6afa24d117715bdf69f9c8f5c7da89349fd598518721db40fbd65966", + "devtools/headless-protocol/invalid-requests.json": "57b409c7db95acd8ee66373806497cc35a68c9141265b6d9781692d0a17aea4b", + "devtools/headless-protocol/request.schema.json": "554960a1c6c1304da32753937b899b51ac658cae4b9d96927f5a384325ce2ae2", + "devtools/headless-protocol/requests.json": "23307436be7a943e1b3565533d79ac5af8d985f7983690cfcfb5466188d0cb48", + "devtools/headless-protocol/response.schema.json": "7a8a0fe70a6864203b771e0564dc4227b768213d2368c5b162c892c55c5e186b", + "docs/specs/runtime/11a-headless-automation-protocol.md": "5c9520ba8db26f9c4529a8ad236fb94778b05edd495666ebba8b00fec468110c" + }, + "limits": [ + "No release archive built or selected installation replaced.", + "No Studio helpers, runner, UI or consumer end-to-end qualification performed.", + "Guest pre-insertion logging limits remain unchanged; native continuity cannot prove producer completeness." + ], + "commitsCreated": 0, + "logNormalization": "Stored logs omit trailing blank lines; rawLogSha256 identifies the original captured output." +} diff --git a/discussion/lessons/DSC-0070-headless-bounded-log-observation/evidence/runtime-tests.log b/discussion/lessons/DSC-0070-headless-bounded-log-observation/evidence/runtime-tests.log new file mode 100644 index 0000000..f7517f8 --- /dev/null +++ b/discussion/lessons/DSC-0070-headless-bounded-log-observation/evidence/runtime-tests.log @@ -0,0 +1,438 @@ + Compiling prometeu-hal v0.1.0 (/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-hal) + Compiling prometeu-system v0.1.0 (/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-system) + 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 4.80s + Running unittests src/lib.rs (target/debug/deps/prometeu_hal-372ad163668682c6) + +running 99 tests +test cartridge_loader::tests::load_with_asset_capability_requires_assets_pa ... ok +test cartridge_loader::tests::directory_loader_rejects_oversized_pbx_with_default_limit ... ok +test cartridge_loader::tests::load_rejects_legacy_raw_codec_string_in_assets_pa_header ... ok +test cartridge_loader::tests::load_rejects_invalid_assets_pa_prelude ... ok +test cartridge_loader::tests::load_rejects_preload_with_missing_asset_id ... ok +test cartridge_loader::tests::load_rejects_invalid_assets_pa_header_json ... ok +test cartridge_loader::tests::load_rejects_unknown_codec_string_in_assets_pa_header ... ok +test cartridge_loader::tests::load_rejects_preload_slot_clash_per_bank_type ... ok +test cartridge_loader::tests::load_with_all_capability_normalizes_to_all_flags ... ok +test cartridge_loader::tests::program_admission_accepts_exact_limit_and_rejects_growth_after_metadata ... ok +test cartridge_loader::tests::load_reads_asset_table_and_preload_from_assets_pa_header ... ok +test cartridge_loader::tests::program_admission_handles_empty_short_and_interrupted_reads ... ok +test cartridge_loader::tests::program_admission_rejects_oversized_metadata_before_reading ... ok +test debugger_protocol::tests::test_fault_event_serialization ... ok +test debugger_protocol::tests::test_get_state_serialization ... ok +test debugger_protocol::tests::test_telemetry_event_serialization ... ok +test glyph_bank::tests::glyph_bank_can_materialize_v1_max_palette_count ... ok +test glyph_bank::tests::invalid_palette_lookup_is_distinct_from_transparent_color ... ok +test cartridge_loader::tests::load_with_duplicate_capabilities_fails ... ok +test glyph_bank::tests::glyph_bank_rejects_zero_resident_palettes - should panic ... ok +test glyph_bank::tests::new_glyph_bank_uses_single_resident_palette ... ok +test host_return::tests::full_native_result_buffer_does_not_invoke_string_allocator ... ok +test host_return::tests::native_results_cannot_grow_the_reserved_buffer_or_exceed_the_signature ... ok +test log::log_service::tests::page_cursors_preserve_large_unsigned_sequences ... ok +test cartridge_loader::tests::load_with_unknown_capability_fails ... ok +test host_return::tests::measured_native_encoding_matches_utf8_lossy_hex_and_join_semantics ... ok +test log::log_service::tests::pages_preserve_zero_requery_and_retained_bounds ... ok +test log::log_service::tests::test_get_after ... ok +test cartridge_loader::tests::load_with_multiple_capabilities_combines_flags ... ok +test log::log_service::tests::test_get_recent ... ok +test log::log_service::tests::test_ring_buffer_capacity ... ok +test cartridge_loader::tests::load_with_none_capability_keeps_zero_flags ... ok +test cartridge_loader::tests::load_with_legacy_input_capability_fails ... ok +test owned_frame::tests::checked_constructor_rejects_empty_dimensions ... ok +test owned_frame::tests::checked_constructor_rejects_short_pixel_buffer ... ok +test cartridge_loader::tests::load_without_capabilities_defaults_to_none ... ok +test owned_frame::tests::checked_constructor_rejects_stride_smaller_than_width ... ok +test owned_frame::tests::owned_rgba8888_frame_preserves_metadata_and_pixels ... ok +test cartridge_loader::tests::load_with_single_capability_normalizes_to_flag ... ok +test owned_frame::tests::row_returns_visible_width_without_stride_padding ... ok +test platform::tests::core_platform_facades_are_object_safe ... ok +test platform::tests::render_submit_error_is_typed_and_debuggable ... ok +test render_resources::tests::missing_resources_return_none ... ok +test render_resources::tests::reads_resident_resources_by_id ... ok +test render_submission::tests::closed_submission_owns_command_payload ... ok +test cartridge_loader::tests::load_without_asset_capability_accepts_missing_assets_pa ... ok +test render_submission::tests::coherence_check_rejects_mismatched_envelope ... ok +test render_submission::tests::constructors_pin_app_mode_to_packet_kind ... ok +test render_submission::tests::frame_id_advances_monotonically_with_wrapping_arithmetic ... ok +test render_submission::tests::ownership_can_be_stamped_by_runtime ... ok +test render_worker::tests::render_worker_error_is_copy_equatable_and_debuggable ... ok +test render_worker::tests::render_worker_telemetry_defaults_to_zero ... ok +test render_worker::tests::render_worker_telemetry_records_counters_and_frame_ids ... ok +test scene_bank::tests::scene_bank_owns_exactly_four_layers ... ok +test scene_layer::tests::scene_layer_preserves_parallax_factor_and_tilemap_ownership ... ok +test scene_viewport_cache::tests::cache_entry_fields_are_derived_from_scene_tiles ... ok +test scene_viewport_cache::tests::column_refresh_only_updates_the_requested_column ... ok +test scene_viewport_cache::tests::corner_style_region_update_does_not_touch_outside_tiles ... ok +test scene_viewport_cache::tests::layer_cache_wraps_ring_origin_for_negative_and_large_movements ... ok +test scene_viewport_cache::tests::layer_cache_wraps_ring_origin_under_window_movement ... ok +test scene_viewport_cache::tests::line_refresh_only_updates_the_requested_line ... ok +test scene_viewport_cache::tests::materialization_populates_all_four_layers ... ok +test scene_viewport_cache::tests::move_window_to_matches_incremental_ring_movement ... ok +test scene_viewport_cache::tests::out_of_bounds_logical_origins_materialize_default_entries_after_wrap ... ok +test scene_viewport_cache::tests::partial_refresh_uses_wrapped_physical_slots_after_window_move ... ok +test scene_viewport_cache::tests::refresh_after_wrapped_window_move_materializes_new_logical_tiles ... ok +test scene_viewport_cache::tests::region_refresh_only_updates_the_requested_area ... ok +test scene_viewport_cache::tests::ringbuffer_preserves_logical_tile_mapping_across_long_mixed_movements ... ok +test scene_viewport_cache::tests::scene_swap_invalidation_clears_all_layers ... ok +test scene_viewport_resolver::tests::anchors_clamp_near_scene_edges ... ok +test scene_viewport_resolver::tests::corner_trigger_converts_to_non_overlapping_region_requests ... ok +test scene_viewport_resolver::tests::first_update_initializes_master_and_layer_anchors ... ok +test scene_viewport_resolver::tests::reset_scene_requests_full_invalidation_for_all_layers ... ok +test scene_viewport_resolver::tests::hysteresis_prevents_small_back_and_forth_refresh_churn ... ok +test scene_viewport_resolver::tests::per_layer_copy_requests_follow_parallax_factor ... ok +test syscalls::tests::declared_resolver_accepts_mixed_status_first_surface_as_a_single_module ... ok +test syscalls::tests::audio_control_abi_and_capability_are_stable ... ok +test syscalls::tests::declared_resolver_rejects_abi_mismatch ... ok +test syscalls::tests::declared_resolver_rejects_missing_capability ... ok +test syscalls::tests::declared_resolver_rejects_unknown_identity ... ok +test syscalls::tests::declared_resolver_rejects_legacy_status_first_signatures ... ok +test syscalls::tests::declared_resolver_returns_expected_id_for_known_identity ... ok +test scene_viewport_resolver::tests::repeated_high_speed_movement_advances_in_tile_steps ... ok +test syscalls::tests::resolver_enforces_capabilities ... ok +test syscalls::tests::resolver_exposes_split_render_capabilities ... ok +test syscalls::tests::resolver_rejects_removed_bank_slot_info_identity ... ok +test syscalls::tests::resolver_rejects_removed_legacy_gfx_set_sprite_identity ... ok +test syscalls::tests::resolver_rejects_unknown_identity ... ok +test syscalls::tests::resolver_rejects_userland_system_run_cart_identity ... ok +test syscalls::tests::resolver_returns_expected_id_for_known_identity ... ok +test syscalls::tests::memcard_syscall_signatures_are_pinned ... ok +test telemetry::tests::snapshot_includes_internal_allocation_evidence ... ok +test telemetry::tests::snapshot_maps_render_worker_telemetry ... ok +test telemetry::tests::snapshot_uses_persisted_last_frame_logs ... ok +test syscalls::tests::status_first_syscall_signatures_are_pinned ... ok +test telemetry::tests::test_certifier_violations ... ok +test tilemap::tests::tilemap_tile_write_and_read_remain_canonical ... ok +test value_snapshot::tests::serialization_contains_values_and_never_exports_native_domain_metadata ... ok +test syscalls::tests::every_syscall_has_metadata ... ok + +test result: ok. 99 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.02s + + Running unittests src/lib.rs (target/debug/deps/prometeu_host_headless-34e7d78b76b56071) + +running 16 tests +test automation::tests::bounded_lines_accept_fragmentation_and_recover_after_oversize ... ok +test automation::wire::fault_tests::resource_trap_wire_preserves_native_fields_and_source_span ... 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::wire::log_tests::required_nullable_cursor_and_limit_reject_malformed_values ... ok +test automation::wire::log_tests::oversized_native_event_is_an_error_without_partial_result ... ok +test automation::tests::response_limit_counts_the_complete_envelope_and_keeps_correlation ... ok +test automation::wire::log_tests::native_records_preserve_unsigned_maxima_and_typed_sources ... ok +test automation::tests::capture_preserves_independent_ids_and_excludes_padding_without_channel_loss ... 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::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 result: ok. 16 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.20s + + Running tests/deterministic_control.rs (target/debug/deps/deterministic_control-bf4ec7093c206e5c) + +running 25 tests +test headless_source_has_no_timing_wait_or_interactive_backend_dependency ... ok +test instruction_step_fault_remains_structured ... ok +test lifecycle_state_and_preconditions_are_structural ... ok +test audio_play_does_not_need_a_device ... ok +test batch_stops_early_on_fault_and_reports_partial_progress ... ok +test injected_civil_clock_remains_the_runtime_source_across_lifecycle ... ok +test end_of_rom_completes_a_logical_frame ... ok +test advance_after_reset_reports_termination_without_ticking ... ok +test clear_input_drops_right ... ok +test one_frame_returns_and_captures_the_exact_published_frame ... ok +test step_does_not_complete_a_logical_frame ... ok +test normalized_button_press_hold_release_and_clear_are_observable ... ok +test normalized_touch_edges_and_coordinates_use_the_same_input_surface ... ok +test stepping_frame_sync_is_not_a_fault_or_completed_runtime_frame ... ok +test controlled_civil_time_is_independent_of_frames_pause_and_reset ... ok +test trap_is_structured ... ok +test zero_frames_is_an_explicit_noop ... ok +test vm_init_failure_is_returned_as_structured_boot_failure ... ok +test right_hold_then_release_changes_pixels ... ok +test two_runs_match_oracle ... ok +test one_logical_frame_may_span_multiple_internal_ticks ... 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 1.30s + + Running tests/input_queries.rs (target/debug/deps/input_queries-95d1e124c4662847) + +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.02s + + Running tests/typed_runtime.rs (target/debug/deps/typed_runtime-e8b3a2e2b04729f7) + +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 regenerated_cartridges_run_six_complete_frames_on_production_host ... ok +test budget_exhaustion_inside_fn_keeps_the_same_open_logical_frame ... ok + +test result: ok. 5 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.65s + + Running unittests src/lib.rs (target/debug/deps/prometeu_system-5bd0bf863c9e944e) + +running 232 tests +test crash_report::init_diagnostic::tests::all_load_codes_serialize_to_the_normative_tags ... ok +test os::system_os::tests::foreground_stack_starts_at_hub ... ok +test crash_report::init_diagnostic::tests::native_abi_and_resource_context_are_machine_fields ... ok +test os::system_os::tests::close_task_marks_task_closed_and_process_stopped_without_removing_entities ... ok +test os::system_os::tests::game_session_registers_single_resident_game ... ok +test crash_report::init_diagnostic::tests::load_tag_and_reference_context_survive_without_fabricating_runtime_pc ... ok +test os::system_os::tests::closing_foreground_shell_returns_to_hub ... ok +test os::system_os::tests::lifecycle_exposes_process_kind_for_shell_tasks ... ok +test os::system_os::tests::crash_task_marks_task_and_process_crashed ... ok +test os::system_os::tests::lifecycle_operation_missing_process_returns_typed_error ... ok +test os::system_os::tests::lifecycle_operation_missing_task_returns_typed_error ... ok +test os::system_os::tests::home_request_notifies_game_before_budget_suspends_it ... ok +test os::system_os::tests::native_shell_task_does_not_create_vm_session ... ok +test os::system_os::tests::native_shell_foreground_suspends_foreground_resident_game ... ok +test os::system_os::tests::resume_task_from_non_suspended_state_returns_invalid_transition ... ok +test os::system_os::tests::resume_task_marks_suspended_task_foreground_and_process_running ... ok +test os::system_os::tests::same_resident_game_app_reuses_existing_vm_session ... ok +test os::system_os::tests::second_foreground_shell_is_rejected ... ok +test os::system_os::tests::second_resident_game_is_rejected ... ok +test os::system_os::tests::session_cartridge_initialization_returns_typed_error_for_missing_session ... ok +test os::system_os::tests::set_foreground_task_marks_task_and_process_running ... ok +test os::system_os::tests::shell_foreground_keeps_game_resident_and_marks_it_suspended ... ok +test os::system_os::tests::suspend_task_marks_task_and_process_suspended ... ok +test os::system_os::tests::terminate_resident_game_closes_task_and_removes_vm_session ... ok +test os::system_os::tests::terminate_resident_game_preserves_foreground_shell ... ok +test os::system_os::tests::vm_debug_operations_target_foreground_shell_before_resident_game ... ok +test os::system_os::tests::vm_game_task_creates_vm_session ... ok +test os::system_os::tests::vm_session_creation_returns_typed_error_for_missing_process ... ok +test os::system_os::tests::vm_session_creation_returns_typed_error_for_missing_task ... ok +test os::system_os::tests::vm_sessions_hold_independent_runtime_state ... ok +test os::system_os::tests::vm_shell_foreground_suspends_foreground_resident_game ... ok +test os::system_os::tests::vm_shell_load_returns_typed_error_when_foreground_shell_exists ... ok +test os::system_os::tests::vm_shell_task_creates_vm_session ... ok +test programs::prometeu_hub::prometeu_hub::tests::button_hit_test_excludes_right_and_bottom_edges ... ok +test programs::prometeu_hub::prometeu_hub::tests::close_button_click_emits_close_only_in_shell ... ok +test programs::prometeu_hub::prometeu_hub::tests::game_row_click_emits_launch_game_action ... ok +test programs::prometeu_hub::prometeu_hub::tests::held_pointer_does_not_emit_click_action ... ok +test programs::prometeu_hub::prometeu_hub::tests::home_layout_exposes_exactly_two_manual_shell_buttons ... ok +test programs::prometeu_hub::prometeu_hub::tests::home_render_omits_suspended_game_kill_control_without_resident_game ... ok +test programs::prometeu_hub::prometeu_hub::tests::home_render_produces_shell_ui_packet_commands ... ok +test programs::prometeu_hub::prometeu_hub::tests::home_render_shows_suspended_game_kill_control_when_game_is_resident ... ok +test programs::prometeu_hub::prometeu_hub::tests::hub_starts_with_home_input_disarmed ... ok +test programs::prometeu_hub::prometeu_hub::tests::shell_a_button_click_emits_launch_action ... ok +test programs::prometeu_hub::prometeu_hub::tests::resident_game_indicator_uses_only_resident_game_sessions ... ok +test programs::prometeu_hub::prometeu_hub::tests::shell_close_button_sits_inside_shell_frame ... ok +test programs::prometeu_hub::prometeu_hub::tests::shell_b_button_click_emits_launch_action ... ok +test programs::prometeu_hub::prometeu_hub::tests::suspended_game_kill_control_click_emits_kill_action ... ok +test programs::prometeu_hub::prometeu_hub::tests::suspended_game_kill_control_truncates_long_titles ... ok +test services::async_work::tests::async_work_lane_rejects_submit_after_shutdown ... ok +test services::async_work::tests::async_work_lane_shutdown_discards_pending_jobs ... ok +test services::foreground::tests::foreground_stack_starts_at_hub ... ok +test services::foreground::tests::home_request_moves_resident_game_to_pause_requested ... ok +test services::foreground::tests::pause_budget_decrements_before_expiry ... ok +test services::async_work::tests::async_work_lane_runs_higher_priority_io_before_assets ... ok +test services::async_work::tests::async_work_lane_runs_jobs_in_submission_order ... ok +test services::foreground::tests::pause_budget_expiry_suspends_game_and_returns_to_hub ... ok +test services::async_work::tests::async_work_lane_has_one_active_job ... ok +test services::foreground::tests::resume_request_precedes_game_foreground_restore ... ok +test services::foreground::tests::second_resident_game_is_rejected ... ok +test services::foreground::tests::setting_game_foreground_registers_resident_game ... ok +test services::foreground::tests::shell_foreground_keeps_resident_game ... ok +test services::fs::virtual_fs::tests::fs_async_lane_operations_classify_priority_without_public_api_changes ... ok +test services::fs::virtual_fs::tests::test_delete_root_is_rejected_before_backend ... ok +test services::fs::virtual_fs::tests::test_invalid_paths_never_reach_backend ... ok +test services::fs::virtual_fs::tests::test_normalize_path_rejects_parent_traversal ... ok +test services::fs::virtual_fs::tests::test_virtual_fs_health ... ok +test services::fs::virtual_fs::tests::test_virtual_fs_operations ... ok +test services::game_library::tests::switch_target_preserves_resolved_identity ... ok +test services::game_library::tests::missing_root_returns_diagnostic_and_no_entries ... ok +test services::memcard::image::tests::closed_catalog_rejects_duplicates_and_deep_input ... ok +test services::game_library::tests::repository_test_cartridges_include_stress_and_dummy_boy ... ok +test services::memcard::image::tests::crc_vectors_and_identity_golden ... ok +test services::async_work::tests::async_work_lane_supports_cooperative_cancellation ... ok +test services::memcard::image::tests::descriptor_roundtrip_rejects_reserved_and_alias ... ok +test programs::prometeu_hub::prometeu_hub::tests::native_shell_profile_close_button_does_not_tick_vm ... ok +test services::async_work::step_tests::yielded_asset_resumes_same_job_after_priority_save ... ok +test programs::prometeu_hub::prometeu_hub::tests::native_shell_profile_start_close_does_not_tick_vm ... ok +test services::memcard::session::tests::clear_and_sparse_writes_do_not_expose_previous_bytes ... ok +test services::memcard::session::tests::memory_snapshot_limits_isolation_and_no_fake_durability ... ok +test services::memcard::image::tests::maximum_catalog_and_icons_fit_and_preserve_uint64 ... ok +test services::memcard::transaction::tests::cancellation_prevents_publication_and_generations_do_not_wrap ... ok +test services::memcard::transaction::tests::corrupted_new_payload_recovers_old_map_with_diagnostic ... ok +test services::memcard::transaction::tests::async_commit_protects_only_source_and_retains_result_without_occupying_lane ... ok +test services::memcard::transaction::tests::deferred_boot_memcard_deadline_stays_timeout ... ok +test services::memcard::transaction::tests::boot_commit_waits_for_ready_and_publishes_registration_before_payload ... ok +test services::game_library::tests::discovery_samples_once_per_scan_and_preserves_adjustments_and_full_range ... ok +test services::memcard::transaction::tests::ending_a_session_releases_a_completed_unconsumed_request ... ok +test services::memcard::transaction::tests::full_card_admission_preserves_card_and_memory_only_can_extend_existing_data ... ok +test services::memcard::transaction::tests::grow_shrink_removal_and_clean_reassignment ... ok +test services::memcard::admission::tests::idle_uncertain_media_remains_blocked_before_another_persistent_admission ... ok +test services::memcard::transaction::tests::qualify_file_commits_with_production_asset_decoder ... ignored, manual file-host latency qualification; prints measurements for this host +test services::memcard::transaction::tests::quarantine_survives_remount_and_is_never_selected ... ok +test services::memcard::transaction::tests::lifecycle_cancellation_is_not_a_watchdog_timeout ... ok +test services::memcard::transaction::tests::catalog_cuts_never_publish_partial_registration ... ok +test services::game_library::tests::discovery_returns_only_immediate_valid_game_directories ... ok +test services::memcard::transaction::tests::reinsertion_retains_ram_and_different_card_requires_explicit_load ... ok +test services::process::process_manager::tests::mark_stopped_updates_process_state ... ok +test services::process::process_manager::tests::mark_suspended_updates_process_state ... ok +test services::process::process_manager::tests::remove_stopped_keeps_running_processes ... ok +test services::process::process_manager::tests::spawn_native_shell_creates_running_process ... ok +test services::process::process_manager::tests::spawn_vm_game_creates_running_process ... ok +test services::process::process_manager::tests::spawn_vm_shell_creates_running_process ... ok +test services::process::process_manager::tests::unknown_process_transition_returns_false ... ok +test services::task::task_manager::tests::close_foreground_task_clears_foreground ... ok +test services::task::task_manager::tests::crashed_foreground_task_clears_foreground ... ok +test services::task::task_manager::tests::create_game_task_registers_task ... ok +test services::task::task_manager::tests::set_foreground_marks_task_as_foreground ... ok +test services::task::task_manager::tests::set_foreground_moves_previous_task_to_background ... ok +test services::task::task_manager::tests::set_foreground_unknown_task_returns_false ... ok +test services::task::task_manager::tests::suspend_foreground_task_clears_foreground ... ok +test services::vm_runtime::async_render_contract_tests::async_render_contract_matrix_rows_have_validation ... ok +test services::memcard::transaction::tests::queued_memcard_watchdog_preserves_timeout_and_guest_reason ... ok +test services::vm_runtime::async_render_contract_tests::matrix_epoch_stale_discard_and_telemetry_sync_remain_consistent ... ok +test services::vm_runtime::async_render_contract_tests::matrix_packet_policy_and_pacing_are_mode_specific ... ok +test services::vm_runtime::async_render_contract_tests::matrix_shutdown_failure_and_repeat_are_observable ... ok +test services::vm_runtime::async_render_contract_tests::matrix_sync_and_worker_paths_share_latest_wins_handoff_contract ... ok +test services::vm_runtime::frame_scheduler::tests::authorizes_one_game_frame_until_completion ... ok +test services::vm_runtime::frame_scheduler::tests::completion_is_sequential_without_catch_up_frames ... ok +test services::vm_runtime::frame_scheduler::tests::records_logical_frame_overrun_without_advancing_frame_id ... ok +test services::vm_runtime::lifecycle::tests::vm_runtime_records_and_drains_delivered_game_lifecycle_events ... ok +test services::vm_runtime::render_manager::tests::app_mode_switch_records_noop_transition_placeholder ... ok +test services::vm_runtime::render_manager::tests::active_render_policy_follows_app_mode_transition ... ok +test services::vm_runtime::render_manager::tests::close_frame_stamps_submission_with_active_ownership ... ok +test services::vm_runtime::render_manager::tests::frame_closure_assigns_monotonic_frame_ids ... ok +test services::memcard::transaction::tests::blocked_host_memcard_watchdog_preserves_outcome_and_escalation ... ok +test services::vm_runtime::render_manager::tests::latest_complete_submission_wins_without_queue_growth ... ok +test services::vm_runtime::render_manager::tests::local_render_worker_consumes_latest_game_submission ... ok +test services::vm_runtime::render_manager::tests::publish_latest_consumes_pending_but_keeps_observable_last_submission ... ok +test services::vm_runtime::render_manager::tests::present_panic_is_reported_without_unwinding_to_vm ... ok +test services::vm_runtime::render_manager::tests::publish_latest_discards_stale_epoch_before_present ... ok +test services::vm_runtime::render_manager::tests::publish_latest_hands_submission_to_surface ... ok +test services::vm_runtime::render_manager::tests::rejects_packet_that_does_not_match_active_app_mode ... ok +test services::vm_runtime::render_manager::tests::render_handoff_counts_replacement_before_consume ... ok +test services::vm_runtime::render_manager::tests::render_handoff_discards_pending_submission ... ok +test services::vm_runtime::render_manager::tests::render_handoff_takes_owned_latest_submission ... ok +test services::vm_runtime::render_manager::tests::render_policy_keeps_shell_local_even_when_worker_capability_is_enabled ... ok +test services::vm_runtime::render_manager::tests::render_policy_maps_game_to_frame_scheduled_worker_capable ... ok +test services::vm_runtime::render_manager::tests::render_policy_maps_shell_to_lifecycle_driven_local_sync ... ok +test services::vm_runtime::render_manager::tests::render_policy_resolves_game_worker_only_when_capability_is_enabled ... ok +test services::vm_runtime::render_manager::tests::render_telemetry_counts_produced_replaced_consumed_and_presented ... ok +test services::vm_runtime::render_manager::tests::render_telemetry_counts_stale_repeat_and_error_hooks ... ok +test services::vm_runtime::render_manager::tests::render_telemetry_syncs_to_atomic_telemetry ... ok +test services::vm_runtime::render_manager::tests::request_shutdown_discards_pending_submission_without_presenting ... ok +test services::vm_runtime::render_manager::tests::stopped_consumer_discards_new_pending_submission_before_present ... ok +test services::vm_runtime::render_manager::tests::resume_consumer_allows_presentation_after_shutdown ... ok +test services::vm_runtime::render_worker::tests::latest_render_frame_store_is_sink_and_observable_publication_source ... ok +test services::vm_runtime::render_manager::tests::transition_render_owner_increments_epoch_for_same_mode_app_swap ... ok +test services::vm_runtime::render_worker::tests::render_worker_controller_renders_and_publishes_submission ... ok +test services::vm_runtime::render_worker::tests::render_worker_controller_repeats_latest_published_frame_without_rendering ... ok +test services::vm_runtime::render_worker::tests::render_worker_controller_discards_stale_frame_before_publish ... ok +test services::vm_runtime::render_worker::tests::render_worker_controller_captures_backend_panic_as_typed_failure ... ok +test services::vm_runtime::render_worker::tests::render_worker_controller_starts_and_stops_waiting_worker ... ok +test services::vm_runtime::render_worker_handoff::tests::render_worker_handoff_is_latest_wins_and_counts_replacements ... ok +test services::vm_runtime::render_worker_handoff::tests::render_worker_handoff_takes_owned_submission ... ok +test services::vm_runtime::render_worker::tests::runtime_publishes_game_submissions_to_worker_without_waiting_for_render ... ok +test services::vm_runtime::render_worker_handoff::tests::render_worker_handoff_wait_take_returns_pending_without_blocking ... ok +test services::vm_runtime::render_worker_handoff::tests::render_worker_handoff_wait_returns_shutdown_signal ... ok +test services::vm_runtime::render_worker_test_harness::tests::render_worker_harness_builds_game_and_shell_submissions ... ok +test services::vm_runtime::render_worker_handoff::tests::render_worker_handoff_waits_for_publish_without_timing_delay ... ok +test services::vm_runtime::render_worker_test_harness::tests::render_worker_harness_blocks_and_releases_render_without_timing_delay ... ok +test services::vm_runtime::render_worker_test_harness::tests::render_worker_harness_injects_backend_errors ... ok +test services::vm_runtime::render_worker_test_harness::tests::render_worker_harness_records_published_owned_frames ... ok +test services::vm_runtime::tests::asset_bank::initialize_vm_rejects_removed_bank_slot_info_syscall_identity ... ok +test services::vm_runtime::tests::asset_bank::tick_asset_backlog_promote_unknown_handle_returns_status_not_crash ... ok +test services::vm_runtime::tests::asset_bank::tick_asset_cancel_unknown_handle_returns_status_not_crash ... ok +test services::vm_runtime::render_worker::tests::render_worker_controller_reports_shutdown_timeout ... ok +test services::vm_runtime::tests::asset_bank::tick_asset_commit_operational_error_returns_status_not_crash ... ok +test services::vm_runtime::tests::asset_bank::tick_asset_commit_invalid_transition_returns_status_not_crash ... ok +test services::vm_runtime::tests::asset_bank::tick_asset_load_invalid_slot_returns_status_and_zero_handle ... ok +test services::vm_runtime::tests::asset_bank::tick_asset_load_missing_asset_returns_status_and_zero_handle ... ok +test services::vm_runtime::tests::asset_bank::tick_asset_status_unknown_handle_returns_status_not_crash ... ok +test services::vm_runtime::tests::asset_bank::tick_asset_target_status_empty_slot_returns_status_first_payload ... ok +test services::vm_runtime::tests::asset_bank::tick_status_first_surface_smoke_across_composer_audio_and_asset ... ok +test services::vm_runtime::tests::asset_bank::tick_bank_info_returns_slot_summary_not_json ... ok +test services::memcard::transaction::tests::explicit_revalidation_preserves_exclusions_until_separate_reintegration ... ok +test services::vm_runtime::tests::audio_controls::frame_publication_backpressure_abort_and_debug_steps ... ok +test services::memcard::transaction::tests::persistent_save_preempts_real_multichunk_asset_decoders ... ok +test services::vm_runtime::tests::audio_controls::normal_entry_return_is_a_successful_implicit_audio_frame ... ok +test services::vm_runtime::tests::initialize_vm_applies_cartridge_capabilities_before_loader_resolution ... ok +test services::vm_runtime::tests::fs_memcard::tick_memcard_boot_is_denied_for_non_game_profile ... ok +test services::vm_runtime::tests::initialize_vm_failure_clears_previous_identity_and_handles ... ok +test services::vm_runtime::tests::initialize_vm_succeeds_when_cartridge_capabilities_cover_hostcalls ... ok +test services::vm_runtime::tests::fs_memcard::tick_memcard_boot_receives_admitted_context_and_precedes_first_frame ... ok +test services::vm_runtime::tests::initialize_vm_success_clears_previous_crash_report ... ok +test services::vm_runtime::tests::reset_clears_cartridge_scoped_runtime_state ... ok +test services::vm_runtime::tests::audio_controls::guest_audio_status_matrix_and_type_traps ... ok +test services::vm_runtime::tests::tick_audio_play_missing_asset_returns_status_not_crash ... ok +test services::vm_runtime::tests::tick_already_materialized_string_path_records_zero_internal_allocations ... ok +test services::vm_runtime::tests::tick_audio_play_sample_operational_error_returns_status_not_crash ... ok +test services::vm_runtime::tests::tick_audio_play_type_mismatch_surfaces_trap_not_panic ... ok +test services::vm_runtime::tests::tick_audio_play_voice_invalid_returns_status_not_crash ... ok +test services::vm_runtime::tests::tick_composer_bind_scene_operational_error_returns_status_not_crash ... ok +test services::vm_runtime::tests::tick_composer_emit_sprite_invalid_layer_returns_status_not_crash ... ok +test services::vm_runtime::tests::tick_composer_emit_sprite_invalid_palette_returns_bank_invalid ... ok +test services::vm_runtime::tests::tick_composer_emit_sprite_invalid_range_returns_status_not_crash ... ok +test services::vm_runtime::tests::tick_composer_emit_sprite_type_mismatch_surfaces_trap_not_panic ... ok +test services::vm_runtime::tests::tick_composer_emit_sprite_operational_error_returns_status_not_crash ... ok +test services::vm_runtime::tests::tick_draw_text_survives_no_scene_frame_path ... ok +test services::vm_runtime::tests::audio_controls::guest_play_validates_raw_bank_loop_and_preserves_both_play_forms ... ok +test services::vm_runtime::tests::tick_game_profile_rejects_gfxui_shell_surface ... ok +test services::vm_runtime::tests::tick_game_submissions_are_immutable_and_latest_complete_wins ... ok +test services::vm_runtime::tests::tick_numeric_happy_path_records_zero_internal_allocations ... ok +test services::vm_runtime::tests::tick_returns_error_when_vm_ends_slice_with_trap ... ok +test services::vm_runtime::tests::tick_shell_profile_closes_gfxui_commands_into_shell_packet ... ok +test services::vm_runtime::tests::tick_system_profile_can_use_shared_log_transport ... ok +test services::vm_runtime::tests::tick_renders_scene_through_public_composer_syscalls ... ok +test services::vm_runtime::tests::tick_renders_bound_eight_pixel_scene_through_frame_composer_path ... ok +test services::vm_runtime::tests::tick_system_profile_rejects_bank_game_surface ... ok +test services::vm_runtime::tests::tick_system_profile_rejects_composer_game_surface ... ok +test services::vm_runtime::tests::asset_bank::tick_asset_cancel_invalid_transition_returns_status_not_crash ... ok +test services::vm_runtime::tests::tick_system_profile_rejects_gfx_game_surface ... ok +test services::vm_session::tests::creates_vm_shell_session_for_vm_shell_task ... ok +test services::vm_runtime::tests::unpatched_hostcall_is_rejected_before_tick ... ok +test services::vm_session::tests::creates_vm_game_session_for_vm_game_task ... ok +test services::vm_session::tests::finds_resident_game_by_app_id ... ok +test services::vm_session::tests::rejects_native_shell_process ... ok +test services::vm_session::tests::remove_for_task_removes_only_matching_session ... ok +test services::vm_session::tests::session_runtime_state_is_independent_per_session ... ok +test services::windows::window_manager::tests::focused_window_belongs_to_task_matches_focused_task_owner ... ok +test services::windows::window_manager::tests::focused_window_belongs_to_task_rejects_hub_owner ... ok +test services::windows::window_manager::tests::focused_window_belongs_to_task_rejects_other_task_owner ... ok +test services::windows::window_manager::tests::focused_window_belongs_to_task_rejects_stale_focus ... ok +test services::windows::window_manager::tests::focused_window_belongs_to_task_rejects_overlay_owner ... ok +test services::windows::window_manager::tests::focused_window_belongs_to_task_returns_false_without_focus ... ok +test services::windows::window_manager::tests::test_window_manager_focus ... ok +test services::windows::window_manager::tests::test_window_manager_remove_window ... ok +test services::memcard::transaction::tests::cut_every_commit_step_including_sync_that_persists_then_errors ... ok +test services::memcard::transaction::tests::file_backend_allocates_full_image_and_reopens_verified_save_without_replacing_files ... ok +test services::memcard::transaction::tests::full_pool_rotates_and_empty_keeps_ownership ... ok +test services::vm_runtime::tests::audio_controls::guest_quota_is_deterministic_and_resets_on_next_frame ... ok +test services::vm_runtime::tests::tick_gfx2d_draw_text_buffers_without_immediate_pixel_mutation_before_frame_close ... ok +test services::vm_runtime::tests::tick_gfx2d_clear_buffers_without_immediate_pixel_mutation_before_frame_close ... ok + +test result: ok. 231 passed; 0 failed; 1 ignored; 0 measured; 0 filtered out; finished in 0.28s + + Doc-tests prometeu_hal + +running 0 tests + +test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s + + Doc-tests prometeu_host_headless + +running 0 tests + +test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s + + Doc-tests prometeu_system + +running 0 tests + +test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s diff --git a/discussion/lessons/DSC-0070-headless-bounded-log-observation/evidence/wire-observations.json b/discussion/lessons/DSC-0070-headless-bounded-log-observation/evidence/wire-observations.json new file mode 100644 index 0000000..b6a5605 --- /dev/null +++ b/discussion/lessons/DSC-0070-headless-bounded-log-observation/evidence/wire-observations.json @@ -0,0 +1,243 @@ +{ + "installation": { + "installation": "/var/folders/0t/tfsqc14j5wbgh9h4s4dytwb00000gq/T/prometeu-log-read-58e3d38i", + "profile": "debug", + "kind": "isolated local staging; no release archive or selected installation update", + "sha256": { + "prometeu": "f35eeea1a13b48c382b108a7f516bc4205d635f6a1698e98d2b0acb12df49e58", + "prometeu-runtime": "75e2a2c56d6a00d94bf265d4d0ed507d869e954ebcb26f9711c332a3a6cb5874", + "prometeu-headless": "dce18f2d753c227e291fba41b761df0b6d04155d9fba44f4faed81d308b38212" + } + }, + "records": [ + { + "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": "fc44b1adef1a5044fccf5d801fa5f2c8", + "type": "hello" + }, + { + "request": { + "requestId": "init", + "command": "initialize", + "params": { + "protocolVersion": { + "major": 1, + "minor": 2 + }, + "requiredCapabilities": [ + "log_read" + ] + } + }, + "response": { + "requestId": "init", + "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": "fc44b1adef1a5044fccf5d801fa5f2c8", + "type": "response" + } + }, + { + "request": { + "requestId": "before", + "command": "get_state", + "params": {} + }, + "response": { + "requestId": "before", + "result": { + "appId": 0, + "logicalFrameIndex": 0, + "pc": 0, + "stackTop": [], + "status": "terminated", + "tickIndex": 0 + }, + "sessionId": "fc44b1adef1a5044fccf5d801fa5f2c8", + "type": "response" + } + }, + { + "request": { + "requestId": "logs", + "command": "get_logs", + "params": { + "afterSequence": null, + "limit": 1 + } + }, + "response": { + "requestId": "logs", + "result": { + "events": [ + { + "appId": null, + "frame": 0, + "level": "info", + "message": "PrometeuOS starting...", + "sequence": 0, + "source": "pos", + "tag": 0, + "timestampMs": 0 + } + ], + "gap": false, + "logEpoch": 0, + "newestSequence": 0, + "nextAfterSequence": 0, + "oldestSequence": 0, + "overflow": false, + "sessionId": "fc44b1adef1a5044fccf5d801fa5f2c8" + }, + "sessionId": "fc44b1adef1a5044fccf5d801fa5f2c8", + "type": "response" + } + }, + { + "request": { + "requestId": "after", + "command": "get_state", + "params": {} + }, + "response": { + "requestId": "after", + "result": { + "appId": 0, + "logicalFrameIndex": 0, + "pc": 0, + "stackTop": [], + "status": "terminated", + "tickIndex": 0 + }, + "sessionId": "fc44b1adef1a5044fccf5d801fa5f2c8", + "type": "response" + } + }, + { + "request": { + "requestId": "reset", + "command": "reset", + "params": {} + }, + "response": { + "requestId": "reset", + "result": { + "appId": 0, + "logicalFrameIndex": 0, + "pc": 0, + "stackTop": [], + "status": "terminated", + "tickIndex": 0 + }, + "sessionId": "fc44b1adef1a5044fccf5d801fa5f2c8", + "type": "response" + } + }, + { + "request": { + "requestId": "continued", + "command": "get_logs", + "params": { + "afterSequence": 0, + "limit": 128 + } + }, + "response": { + "requestId": "continued", + "result": { + "events": [ + { + "appId": null, + "frame": 0, + "level": "info", + "message": "Firmware Reset", + "sequence": 1, + "source": "pos", + "tag": 0, + "timestampMs": 1 + } + ], + "gap": false, + "logEpoch": 0, + "newestSequence": 1, + "nextAfterSequence": 1, + "oldestSequence": 0, + "overflow": false, + "sessionId": "fc44b1adef1a5044fccf5d801fa5f2c8" + }, + "sessionId": "fc44b1adef1a5044fccf5d801fa5f2c8", + "type": "response" + } + }, + { + "request": { + "requestId": "shutdown", + "command": "shutdown", + "params": {} + }, + "response": { + "requestId": "shutdown", + "result": { + "closed": true + }, + "sessionId": "fc44b1adef1a5044fccf5d801fa5f2c8", + "type": "response" + } + } + ], + "readPreservedState": true +} diff --git a/docs/specs/runtime/11a-headless-automation-protocol.md b/docs/specs/runtime/11a-headless-automation-protocol.md index eabc5cf..d201d3a 100644 --- a/docs/specs/runtime/11a-headless-automation-protocol.md +++ b/docs/specs/runtime/11a-headless-automation-protocol.md @@ -30,7 +30,7 @@ and may terminate the process tree. There is no transport replay or durable queu ## Handshake and compatibility The server first emits a `hello` object with `sessionId`, `protocolVersion` -(`major: 1, minor: 1`), real `runtimeVersion`, `capabilities` and `limits`. +(`major: 1, minor: 2`), real `runtimeVersion`, `capabilities` and `limits`. Session identity is opaque and process-local, excluded from deterministic oracles. Before work, the client sends `initialize` with `protocolVersion` and an array @@ -81,6 +81,7 @@ operationId are a separate boundary, not part of this wire protocol. | capture | empty object | PNG/base64 plus canonical frame metadata | | get_state | empty object | pc, stackTop, logicalFrameIndex, tickIndex, appId, status | | get_fault | empty object | fault object or null | +| get_logs | required afterSequence: null/uint64, limit: 1..1024 | native log page; requires negotiated 1.2 log_read | | cancel | targetRequestId | acknowledgement that cancellation was requested for that active advance | | shutdown | empty object | acknowledgement after the active operation stops and host is dropped | @@ -177,6 +178,90 @@ structured faults, progress on partial failure and retained desktop run/debug. Neither Studio UI nor an AI model is required. See `tests/automation_process.rs` in prometeu-cli and the in-process deterministic-control tests in the headless crate. +## Native log observation + +Protocol minor 1.2 adds capability `log_read`. Clients MUST negotiate minor >= 2 +and include `log_read` in `requiredCapabilities` before using `get_logs`. +Requiring it with an older minor returns `incompatible_version`; using it without +negotiation returns `unsupported_capability`. Production clients negotiating 1.0 +or 1.1 retain their existing command/result shapes and media behavior. + +```json +{"requestId":"init","command":"initialize","params":{"protocolVersion":{"major":1,"minor":2},"requiredCapabilities":["log_read"]}} +{"requestId":"logs","command":"get_logs","params":{"afterSequence":null,"limit":128}} +``` + +Send each request after the preceding response. `afterSequence` is a required +nullable exclusive uint64 cursor. Null includes the first retained event, including +sequence zero. `limit` is required and MUST be an integer in 1..1024. Unknown fields, +missing parameters, strings/fractional/negative cursors and invalid limits return +`invalid_params`. A cursor greater than newest, or any non-null cursor on an empty +stream, returns `invalid_cursor`. + +The result contains `sessionId`, `logEpoch`, `events`, `oldestSequence`, +`newestSequence`, `nextAfterSequence`, `gap` and `overflow`. Events include complete +`sequence`, `frame`, `timestampMs`, `level`, `source`, `appId`, `tag` and `message`. +Levels are `trace`, `debug`, `info`, `warn`, `error`; sources are `pos`, `hub`, +`vm`, `fs`, `app`. `appId` is uint32 for `app` and null for all other sources. +`tag` is uint16. Sequences, frames, timestamps and epochs are unsigned JSON uint64 +integers; clients MUST decode them losslessly. Native elapsed-time timestamps +MUST NOT determine deterministic verdicts. Messages are native stored strings, +without assertion parsing, filtering, formatting or additional truncation. + +Events are returned in increasing native sequence order across all sources. +Retained oldest/newest bounds are both null for an empty ring. The next cursor is +the final returned sequence, or the input cursor for an empty page. Requerying an +unchanged ring returns the same events; it never drains records. Reads MUST NOT +tick the firmware, execute guest code or change lifecycle, input, media or faults. +Existing single-operation admission applies: reading during an advance returns +`busy`. Complete envelope byte bounds apply: an oversized page or single event +returns `response_too_large`, without a partial result. Retry a smaller page if +appropriate; a single event that cannot fit remains an explicit error. + +### Retention, cursors and reset + +The ring retains at most 4096 native records. `overflow` reports whether retention +has ever evicted records in this log stream. It is historical information, not +proof of loss for this reader. `gap` reports missing history relative to the +requested cursor: null with retained oldest > 0, or a non-null cursor whose next +sequence is less than retained oldest. `overflow: true, gap: false` is a valid +page for a reader that consumed the evicted records already. Readers MUST use +cursor continuity and `gap` to detect unread retention loss, rather than reject +historical overflow alone. For example, oldest=100 and afterSequence=150 has no +gap; afterSequence=98 or null has a gap. No gap is hidden by source/tag filtering. + +`logEpoch` is zero for the existing process-owned log stream. VM reset retains +the ring, native sequences and epoch; frame counters may reset independently. +It MUST NOT clear or renumber logs to simulate a new stream. A different process +has a different sessionId and its own sequence zero. Clients MUST bind cursors +and deduplication to sessionId/logEpoch; a numeric cursor alone is not a portable +identity between processes. A native sequence already applied MUST NOT be +applied again when inspecting overlapping pages. + +### Producer limits and consumer responsibility + +The unchanged guest logging path accepts at most 10 messages per application per +logical frame, with at most 256 UTF-8 bytes per message. Longer guest messages +are truncated before insertion; excess calls are dropped and produce one native +warning for that application/frame. Dropped calls receive no native sequence, and +truncation does not create a native gap. Consequently `gap: false` does not establish +that every attempted guest event was stored. Reading cannot recover those losses. + +Structured-event consumers MUST bound their encoded messages and per-frame +emission, accounting for other logs from the same application. They MUST validate +their own producer event continuity and explicit completion (for example, ordinals +and final event counts), rejecting missing, malformed or incomplete reports. +The provider supplies generic native observations and does not interpret suites, +assertions or success. Do not enlarge guest budgets to transport test reports. + +Consumers advancing the guest MUST read all pending pages before the next frame +block, including after boot and completion/failure when available. Choose +conservative blocks within actual retention headroom; `maxFrames` is an admission +ceiling, not a safe polling interval. At 10 app messages/frame, 600 frames can +already exceed the 4096-record ring, independently of system messages. Bounded +polling does not guarantee lossless delivery for arbitrary production rates or +unbounded work. Response loss MUST NOT trigger automatic advance replay. + ## Memcard controls Protocol minor 1.1 adds capability `memcard`. Initialize negotiates the lesser