From e03b498886609b168bf8506b2a45e3804c2ddac0 Mon Sep 17 00:00:00 2001 From: fffonion Date: Sat, 14 Nov 2026 17:43:29 +0800 Subject: [PATCH 01/16] feat(stdlib): return Option from public index_of lookups --- .../examples/rss-collections-iter-example.rss | 11 +++++- stdlib/rss/bytes.rss | 14 ++++---- stdlib/rss/collections.rss | 15 ++++---- stdlib/tests/bytes.rss | 36 +++++++++++++++++-- stdlib/tests/collections.rss | 32 +++++++++++++++-- 5 files changed, 88 insertions(+), 20 deletions(-) diff --git a/pd-vm-wasm/examples/rss-collections-iter-example.rss b/pd-vm-wasm/examples/rss-collections-iter-example.rss index af095f42..d2927eb9 100644 --- a/pd-vm-wasm/examples/rss-collections-iter-example.rss +++ b/pd-vm-wasm/examples/rss-collections-iter-example.rss @@ -77,7 +77,16 @@ assert(config_value_count == 3); let reversed_preview: [string] = collections::reverse::(["world", "finance"]); let combined_names: [string] = reversed_preview + ["archive"]; -assert(collections::index_of::(&combined_names, "archive") == 2); +let archive_index: int = match collections::index_of::(&combined_names, "archive") { + Option::Some(value) => value, + Option::None => -1, +}; +assert(archive_index == 2); +let missing_index: bool = match collections::index_of::(&combined_names, "sports") { + Option::Some(_) => false, + Option::None => true, +}; +assert(missing_index); assert(collections::contains::(&combined_names, "world")); assert(collections::contains::(combined_names, "sports") == false); diff --git a/stdlib/rss/bytes.rss b/stdlib/rss/bytes.rss index f39eb6c6..46e01133 100644 --- a/stdlib/rss/bytes.rss +++ b/stdlib/rss/bytes.rss @@ -41,20 +41,20 @@ pub fn ends_with(buf: bytes, suffix: bytes) -> bool { suffix_len <= buf.length && buf[(buf.length - suffix_len):buf.length] == suffix } -// Returns the first index of needle in buf, or -1 when it is absent. -pub fn index_of(buf: bytes, needle: bytes) -> int { +// Returns the first index of needle in buf, or None when it is absent. +pub fn index_of(buf: bytes, needle: bytes) -> Option { let buf_len = buf.length; let needle_len = needle.length; - let out = if needle_len == 0 => { - 0 + let out: Option = if needle_len == 0 => { + Option::Some(0) } else if needle_len > buf_len => { - -1 + Option::None } else => { - let mut found = -1; + let mut found: Option = Option::None; let limit = buf_len - needle_len + 1; for index in 0..limit { if buf[index:(index + needle_len)] == needle { - found = index; + found = Option::Some(index); break; } } diff --git a/stdlib/rss/collections.rss b/stdlib/rss/collections.rss index 0a0c648a..b3d49693 100644 --- a/stdlib/rss/collections.rss +++ b/stdlib/rss/collections.rss @@ -1,20 +1,23 @@ // Collection helpers implemented in pure RustScript. -// Returns the first index of a value in an array, or -1 when it is absent. -pub fn index_of(values: [T], needle: T) -> int { - let mut found =-1; +// Returns the first index of a value in an array, or None when it is absent. +pub fn index_of(values: [T], needle: T) -> Option { + let mut out: Option = Option::None; for find_index in 0..values.length { if values[find_index] == needle { - found = find_index; + out = Option::Some(find_index); break; } } - found + out } // Returns whether an array contains a value. pub fn contains(values: [T], needle: T) -> bool { - index_of::(values, needle) >-1 + match index_of::(values, needle) { + Option::Some(_) => true, + Option::None => false, + } } // Returns a reversed copy of an array. diff --git a/stdlib/tests/bytes.rss b/stdlib/tests/bytes.rss index 3dfd9d1b..9d3207d6 100644 --- a/stdlib/tests/bytes.rss +++ b/stdlib/tests/bytes.rss @@ -36,9 +36,39 @@ assert(bytes_std::starts_with(hello, builtin_bytes::from_utf8("ll")) == false); assert(bytes_std::ends_with(hello, builtin_bytes::from_utf8("lo"))); assert(bytes_std::ends_with(hello, builtin_bytes::from_utf8("he")) == false); -assert(bytes_std::index_of(hello, builtin_bytes::from_utf8("")) == 0); -assert(bytes_std::index_of(hello, builtin_bytes::from_utf8("ll")) == 2); -assert(bytes_std::index_of(hello, builtin_bytes::from_utf8("zz")) == -1); +// W02: `index_of` reports absence with `Option`; an empty needle is still +// a real match at offset 0. +let empty_needle_index = match bytes_std::index_of(hello, builtin_bytes::from_utf8("")) { + Option::Some(value) => value, + Option::None => -1, +}; +assert(empty_needle_index == 0); + +let middle_index = match bytes_std::index_of(hello, builtin_bytes::from_utf8("ll")) { + Option::Some(value) => value, + Option::None => -1, +}; +assert(middle_index == 2); + +let last_index = match bytes_std::index_of(hello, builtin_bytes::from_utf8("o")) { + Option::Some(value) => value, + Option::None => -1, +}; +assert(last_index == 4); + +let absent = bytes_std::index_of(hello, builtin_bytes::from_utf8("zz")); +let absent_is_none = match absent { + Option::Some(_) => false, + Option::None => true, +}; +assert(absent_is_none); + +let long_needle = bytes_std::index_of(hello, builtin_bytes::from_utf8("hello!")); +let long_needle_is_none = match long_needle { + Option::Some(_) => false, + Option::None => true, +}; +assert(long_needle_is_none); let with_tail = bytes_std::push_u8(builtin_bytes::from_hex("0102"), 255); assert(builtin_bytes::to_hex(with_tail) == "0102ff"); diff --git a/stdlib/tests/collections.rss b/stdlib/tests/collections.rss index 4f11a938..10b1d37d 100644 --- a/stdlib/tests/collections.rss +++ b/stdlib/tests/collections.rss @@ -1,13 +1,39 @@ use super::rss::collections::{contains, dedup, entries, get_or, has, index_of, merge, reverse, values}; +// W02: `index_of` reports absence with `Option`, so every assertion below +// distinguishes a found position from a miss instead of comparing against a -1 +// sentinel. +fn index_of_int(values: [int], needle: int) -> Option { + index_of::(values, needle) +} + +fn index_position(values: [int], needle: int, fallback: int) -> int { + match index_of_int(values, needle) { + Option::Some(value) => value, + Option::None => fallback, + } +} + +fn index_is_some(values: [int], needle: int) -> bool { + match index_of_int(values, needle) { + Option::Some(_) => true, + Option::None => false, + } +} + let mut appended = [1, 2] + [3, 4]; assert(appended.length == 4); assert(appended.copy()[0] == 1); assert(appended.copy()[3] == 4); -assert(index_of::(appended, 3) == 2); -assert(index_of::(appended, 9) ==-1); -assert(contains::(appended, 2)); +assert(index_is_some(appended, 1)); +assert(index_position(appended, 1, -1) == 0); +assert(index_position(appended, 3, -1) == 2); +assert(index_position(appended, 4, -1) == 3); +assert(index_is_some(appended, 9) == false); +assert(index_position(appended, 9, 99) == 99); +assert(contains::(appended, 1)); +assert(contains::(appended, 4)); assert(contains::(appended, 9) == false); let mut reversed = reverse::(appended); From 6eca4e11ad1d8612e15ba556512f6eb7d453112f Mon Sep 17 00:00:00 2001 From: fffonion Date: Sat, 14 Nov 2026 18:04:12 +0800 Subject: [PATCH 02/16] refactor(stdlib): drop the duplicate found flag from LRU results --- stdlib/rss/lrucache.rss | 40 ++++------ stdlib/tests/lrucache.rss | 160 ++++++++++++++++++++++++++++++-------- 2 files changed, 141 insertions(+), 59 deletions(-) diff --git a/stdlib/rss/lrucache.rss b/stdlib/rss/lrucache.rss index 711f9883..04441f21 100644 --- a/stdlib/rss/lrucache.rss +++ b/stdlib/rss/lrucache.rss @@ -29,20 +29,8 @@ struct LruCacheState { nodes: map> } -struct LruPeekResult { - found: bool, - value: Option -} - struct LruGetResult { cache: LruCacheState, - found: bool, - value: Option -} - -struct LruEntryReport { - found: bool, - key: Option, value: Option } @@ -216,12 +204,13 @@ fn evict_oldest( out } -fn entry_report(cache: LruCacheState, id: int) -> LruEntryReport { - let out: LruEntryReport = if id != 0 => { +fn entry_report(cache: LruCacheState, id: int) -> Option> { + let out: Option> = if id != 0 => { let node: LruNode =&((&cache).nodes[id]); - {found: true, key: Option::Some(node.key.copy()), value: Option::Some(node.value.copy())} + let row: LruEntryRow = {key: node.key.copy(), value: node.value.copy()}; + Option::Some(row) } else => { - {found: false, key: Option::None, value: Option::None} + Option::None }; out } @@ -257,15 +246,15 @@ pub fn has(cache: LruCacheState, key: K) -> bool { } // Returns the cached value without updating recency. -pub fn peek(cache: LruCacheState, key: K) -> LruPeekResult { +pub fn peek(cache: LruCacheState, key: K) -> Option { let state: LruCacheState = cache; let lookup = state.lookup; - let out: LruPeekResult = if lookup.has(key) => { + let out: Option = if lookup.has(key) => { let id =(&lookup)[key]; let node: LruNode =&((&state.nodes)[id]); - {found: true, value: Option::Some(node.value.copy())} + Option::Some(node.value.copy()) } else => { - {found: false, value: Option::None} + Option::None }; out } @@ -308,11 +297,10 @@ pub fn get(cache: LruCacheState, key: K) -> LruGetResult { relinked.nodes ) }; - {cache: next_cache, found: true, value: Option::Some(value)} + {cache: next_cache, value: Option::Some(value)} } else => { { cache: make_cache::(limit, size, next_id, head, tail, lookup, nodes), - found: false, value: Option::None } }; @@ -522,14 +510,14 @@ pub fn entries(cache: LruCacheState) -> [LruEntryRow] { out } -// Returns the oldest cache entry report. -pub fn oldest(cache: LruCacheState) -> LruEntryReport { +// Returns the oldest cache entry, or None when the cache is empty. +pub fn oldest(cache: LruCacheState) -> Option> { let state: LruCacheState = cache; entry_report::(state, state.head) } -// Returns the newest cache entry report. -pub fn newest(cache: LruCacheState) -> LruEntryReport { +// Returns the newest cache entry, or None when the cache is empty. +pub fn newest(cache: LruCacheState) -> Option> { let state: LruCacheState = cache; entry_report::(state, state.tail) } diff --git a/stdlib/tests/lrucache.rss b/stdlib/tests/lrucache.rss index dec49e7b..bc5547cd 100644 --- a/stdlib/tests/lrucache.rss +++ b/stdlib/tests/lrucache.rss @@ -18,32 +18,57 @@ assert(initial_keys.length == 2); assert(initial_keys[0] == "a"); assert(initial_keys[1] == "b"); -let mut peeked = peek::(cache, "a"); -assert(peeked.found); -let peeked_value: int = peeked.value.unwrap_or(0); +// W01: `peek` reports presence with `Option` and never promotes recency. +let peeked_value = match peek::(cache, "a") { + Option::Some(value) => value, + Option::None => -1, +}; assert(peeked_value == 1); +let peeked_absent = match peek::(cache, "missing") { + Option::Some(_) => false, + Option::None => true, +}; +assert(peeked_absent); let mut still_initial = keys::(cache); assert(still_initial[0] == "a"); assert(still_initial[1] == "b"); +// `get` keeps the updated cache and the payload; the redundant `found` flag is +// gone, so absence is read from the `Option` alone. let mut accessed = get::(cache, "a"); -assert(accessed.found); -let accessed_value: int = accessed.value.unwrap_or(0); +let accessed_value = match accessed.value { + Option::Some(value) => value, + Option::None => -1, +}; assert(accessed_value == 1); cache = accessed.cache; let mut after_get = keys::(cache); assert(after_get[0] == "b"); assert(after_get[1] == "a"); -let mut lru_entry = oldest::(cache); -assert(lru_entry.found); -assert(lru_entry.key.unwrap_or("") == "b"); -assert(lru_entry.value.unwrap_or(0) == 2); - -let mut mru_entry = newest::(cache); -assert(mru_entry.found); -assert(mru_entry.key.unwrap_or("") == "a"); -assert(mru_entry.value.unwrap_or(0) == 1); +// `oldest` / `newest` report one key/value row, so the pair can never +// disagree about presence. +let oldest_key = match oldest::(cache) { + Option::Some(row) => row.key, + Option::None => "missing", +}; +assert(oldest_key == "b"); +let oldest_value = match oldest::(cache) { + Option::Some(row) => row.value, + Option::None => -1, +}; +assert(oldest_value == 2); + +let newest_key = match newest::(cache) { + Option::Some(row) => row.key, + Option::None => "missing", +}; +assert(newest_key == "a"); +let newest_value = match newest::(cache) { + Option::Some(row) => row.value, + Option::None => -1, +}; +assert(newest_value == 1); cache = put::(cache, "c", 3); let mut after_evict = keys::(cache); @@ -62,12 +87,18 @@ cache = put::(cache, "a", 10); let mut after_update = keys::(cache); assert(after_update[0] == "c"); assert(after_update[1] == "a"); -let mut updated = peek::(cache, "a"); -assert(updated.found); -assert(updated.value.unwrap_or(0) == 10); +let updated_value = match peek::(cache, "a") { + Option::Some(value) => value, + Option::None => -1, +}; +assert(updated_value == 10); let mut missed = get::(cache, "missing"); -assert(missed.found == false); +let missed_is_none = match missed.value { + Option::Some(_) => false, + Option::None => true, +}; +assert(missed_is_none); cache = missed.cache; let mut after_miss = keys::(cache); assert(after_miss[0] == "c"); @@ -100,8 +131,16 @@ cache = clear::(cache); assert(capacity::(cache) == 2); assert(len::(cache) == 0); assert(is_empty::(cache)); -assert(oldest::(cache).found == false); -assert(newest::(cache).found == false); +let cleared_oldest = match oldest::(cache) { + Option::Some(_) => false, + Option::None => true, +}; +assert(cleared_oldest); +let cleared_newest = match newest::(cache) { + Option::Some(_) => false, + Option::None => true, +}; +assert(cleared_newest); let mut disabled = new::(0); disabled = put::(disabled, "x", 1); @@ -113,15 +152,18 @@ let mut feed_cache = new::(2); feed_cache = put::(feed_cache, 7, {slug: "alpha", score: 10}); feed_cache = put::(feed_cache, 8, {slug: "beta", score: 20}); -let mut cached_feed = peek::(feed_cache, 7); -assert(cached_feed.found); -let cached_feed_value = cached_feed.value.unwrap_or({slug: "", score: 0}).copy(); +let cached_feed_value = match peek::(feed_cache, 7) { + Option::Some(value) => value.copy(), + Option::None => {slug: "", score: 0}, +}; assert(cached_feed_value.slug == "alpha"); assert(cached_feed_value.score == 10); let mut accessed_feed = get::(feed_cache, 7); -assert(accessed_feed.found); -let accessed_feed_value = accessed_feed.value.unwrap_or({slug: "", score: 0}).copy(); +let accessed_feed_value = match accessed_feed.value { + Option::Some(value) => value.copy(), + Option::None => {slug: "", score: 0}, +}; assert(accessed_feed_value.slug == "alpha"); feed_cache = accessed_feed.cache; @@ -137,14 +179,66 @@ assert(first_feed_row.value.slug == "beta"); assert(second_feed_row.key == 7); assert(second_feed_row.value.score == 10); -let mut feed_oldest = oldest::(feed_cache); -assert(feed_oldest.found); -assert(feed_oldest.key.unwrap_or(0) == 8); -let feed_oldest_value = feed_oldest.value.unwrap_or({slug: "", score: 0}).copy(); +let feed_oldest_key = match oldest::(feed_cache) { + Option::Some(row) => row.key, + Option::None => -1, +}; +assert(feed_oldest_key == 8); +let feed_oldest_value = match oldest::(feed_cache) { + Option::Some(row) => row.value.copy(), + Option::None => {slug: "", score: 0}, +}; assert(feed_oldest_value.slug == "beta"); -let mut feed_newest = newest::(feed_cache); -assert(feed_newest.found); -assert(feed_newest.key.unwrap_or(0) == 7); -let feed_newest_value = feed_newest.value.unwrap_or({slug: "", score: 0}).copy(); +let feed_newest_key = match newest::(feed_cache) { + Option::Some(row) => row.key, + Option::None => -1, +}; +assert(feed_newest_key == 7); +let feed_newest_value = match newest::(feed_cache) { + Option::Some(row) => row.value.copy(), + Option::None => {slug: "", score: 0}, +}; assert(feed_newest_value.score == 10); + +// A false key with an empty-string payload is a real hit: `Option::Some(false)` +// and `Option::Some("")` are distinct from `Option::None`. +let mut flag_cache = new::(2); +flag_cache = put::(flag_cache, false, ""); +let empty_payload_value = match peek::(flag_cache, false) { + Option::Some(value) => value, + Option::None => "missing", +}; +assert(empty_payload_value == ""); +let false_key_absent = match peek::(flag_cache, true) { + Option::Some(_) => false, + Option::None => true, +}; +assert(false_key_absent); +let empty_payload_row = match oldest::(flag_cache) { + Option::Some(row) => row.value, + Option::None => "missing", +}; +assert(empty_payload_row == ""); + +// A cached zero payload is a hit as well: presence comes from the `Option` +// variant, never from the payload's truthiness. +let mut zero_cache = new::(1); +zero_cache = put::(zero_cache, "zero", 0); +let zero_value = match peek::(zero_cache, "zero") { + Option::Some(value) => value, + Option::None => 99, +}; +assert(zero_value == 0); +let zero_absent = match peek::(zero_cache, "missing") { + Option::Some(_) => false, + Option::None => true, +}; +assert(zero_absent); +let zero_get = get::(zero_cache, "zero"); +let zero_get_value = match zero_get.value { + Option::Some(value) => value, + Option::None => 99, +}; +assert(zero_get_value == 0); +zero_cache = zero_get.cache; From 0f2d16117539f27b0b5e885db4d171839bcffeaf Mon Sep 17 00:00:00 2001 From: fffonion Date: Sat, 14 Nov 2026 18:04:34 +0800 Subject: [PATCH 03/16] refactor(runtime): report Unit from command-style host calls runtime::sleep, aot::compile, aot::clear and timer::at/every no longer return a fixed success boolean. A successful runtime::sleep and AOT command is the logical Unit result (VmResult<()>), and the owned timer registration returns the Unit carrier instead of `true`. The timer catalog declares HostTypeSchema::Unit for both registration commands, so the timer and composed standard catalog identities are re-pinned; aot::is_compiled, aot::exec_count, timer counts and the callback `premature` flag keep their real boolean/integer results. Guest call sites drop the unused confirmation value: the complex example sleeps as a statement, the type-inference case compares the propagated Unit result, and the JIT binding tests bind the wait to a typed Unit local. The timer architecture guard still rejects nullable routes and now checks the registration Unit result explicitly. --- docs/standard-timer-host.md | 6 ++++ examples/example_complex.rss | 6 ++-- src/builtins/runtime/aot.rs | 20 ++++++-------- src/builtins/runtime/host.rs | 9 ++++-- src/builtins/runtime/timer.rs | 13 +++++++-- tests/common/mod.rs | 4 ++- tests/compiler/compiler_rustscript_tests.rs | 17 +++++++----- tests/compiler/type_inference_tests.rs | 6 ++-- tests/host_binding_generation_tests.rs | 4 +-- tests/standard_host_descriptor_arch_tests.rs | 14 ++++++---- tests/timer_host_arch_tests.rs | 29 ++++++++++++++------ tests/timer_host_tests.rs | 6 ++-- tests/vm/vm_runtime_tests.rs | 10 ++++--- 13 files changed, 92 insertions(+), 52 deletions(-) diff --git a/docs/standard-timer-host.md b/docs/standard-timer-host.md index 0acd3089..931dfa73 100644 --- a/docs/standard-timer-host.md +++ b/docs/standard-timer-host.md @@ -15,6 +15,12 @@ are `DEFAULT_MAX_PENDING_TIMERS` (1024) pending registrations and re-exported at the crate root, and an embedding can install different `TimerConfig` limits. +`timer::at` / `timer::every` report the logical Unit result. A successful +registration therefore has no payload to inspect: the callback transfer is the +whole effect, and a rejected registration is the ordinary `VmResult` error +(the callback operand returns to the guest exactly once). The synchronous count +queries stay real `int` results. + The callback parameter is typed `fn(bool) -> unknown`: the callback observes the `premature` flag and its **return value is discarded**, so the declared result is `unknown` — an `int`/`string`/`map`/`bool`/`()` body compiles and runs, diff --git a/examples/example_complex.rss b/examples/example_complex.rss index ef609358..91cec068 100644 --- a/examples/example_complex.rss +++ b/examples/example_complex.rss @@ -62,14 +62,16 @@ struct PayloadPartial { let payload_json = json::encode(payload); let payload_decoded = json::decode::(payload_json); let json_score = payload_decoded.score; -let sleep_ok = runtime::sleep(100); +// `runtime::sleep` reports the logical Unit result, so there is no success value +// to compare; the completed wait is the whole effect. +runtime::sleep(100); let io_ok = if true => { io::exists(".") } else => { false }; -if regex_ok && io_ok && sleep_ok && json_score == matched { +if regex_ok && io_ok && json_score == matched { print(closure_value); } else { print(0); diff --git a/src/builtins/runtime/aot.rs b/src/builtins/runtime/aot.rs index ef6e7450..b6239420 100644 --- a/src/builtins/runtime/aot.rs +++ b/src/builtins/runtime/aot.rs @@ -4,16 +4,16 @@ use crate::vm::{Value, Vm, VmError, VmResult}; /// Compile and install a whole-program AOT artifact for the current VM program. #[pd_host_function(name = "aot::compile")] -pub(super) fn builtin_aot_compile(vm: &mut Vm) -> VmResult { +pub(super) fn builtin_aot_compile(vm: &mut Vm) -> VmResult<()> { vm.compile_aot()?; - Ok(true) + Ok(()) } /// Clear the currently installed whole-program AOT artifact. #[pd_host_function(name = "aot::clear")] -pub(super) fn builtin_aot_clear(vm: &mut Vm) -> VmResult { +pub(super) fn builtin_aot_clear(vm: &mut Vm) -> VmResult<()> { vm.clear_aot(); - Ok(false) + Ok(()) } /// Return whether a whole-program AOT artifact is currently installed. @@ -91,20 +91,16 @@ mod tests { "fresh vm should not have aot installed" ); - assert!( - builtin_aot_compile(&mut vm, args).expect("compile should succeed"), - "compile should report success" - ); + // Both commands now report the logical Unit result: `compile` no longer + // claims `true` and `clear` no longer reports a fake `false`. + builtin_aot_compile(&mut vm, args).expect("compile should succeed"); assert!(vm.has_aot_program(), "aot program should be installed"); assert_eq!( builtin_aot_resume_ips(&mut vm, args).expect("resume query should succeed"), vec![Value::Int(0)] ); - assert!( - !builtin_aot_clear(&mut vm, args).expect("clear should succeed"), - "clear should report the disabled state" - ); + builtin_aot_clear(&mut vm, args).expect("clear should succeed"); assert!(!vm.has_aot_program(), "aot program should be cleared"); } diff --git a/src/builtins/runtime/host.rs b/src/builtins/runtime/host.rs index 31a64b66..df4b59ba 100644 --- a/src/builtins/runtime/host.rs +++ b/src/builtins/runtime/host.rs @@ -47,13 +47,13 @@ fn sleep_duration(millis: i64) -> VmResult { /// Sleeps for the requested milliseconds. #[pd_host_function(name = "runtime::sleep")] -fn runtime_sleep_impl(ms: i64) -> VmResult { +fn runtime_sleep_impl(ms: i64) -> VmResult<()> { let duration = sleep_duration(ms)?; #[cfg(not(target_family = "wasm"))] std::thread::sleep(duration); #[cfg(target_family = "wasm")] let _ = duration; - Ok(true) + Ok(()) } /// Halts the current VM invocation immediately. @@ -116,6 +116,11 @@ mod tests { ); } + #[test] + fn runtime_sleep_returns_unit_on_success() { + runtime_sleep_impl(0).expect("zero millisecond sleep should succeed"); + } + #[test] fn runtime_sleep_name_is_stable() { assert_eq!(RUNTIME_SLEEP_NAME, "runtime::sleep"); diff --git a/src/builtins/runtime/timer.rs b/src/builtins/runtime/timer.rs index 5f24df41..10b2f331 100644 --- a/src/builtins/runtime/timer.rs +++ b/src/builtins/runtime/timer.rs @@ -456,6 +456,10 @@ fn timer_callback_schema() -> HostTypeSchema { /// adapter, so the module declares explicit descriptors. The descriptor still /// carries the schema, binding class, adapter factory, and effects, so there is /// no parallel catalog or registry glue. +/// +/// The declared result is the logical Unit: a registration has nothing to +/// confirm once the backend accepted the transferred callback, and a rejection +/// is already the `VmResult` error channel. fn timer_register_contract(name: &'static str, delay_name: &'static str) -> HostFunctionSchema { HostFunctionSchema::with_return( name, @@ -467,7 +471,7 @@ fn timer_register_contract(name: &'static str, delay_name: &'static str) -> Host HostParamPassing::TakeOwned, ), ], - HostTypeSchema::Bool, + HostTypeSchema::Unit, ) .with_description("Registers an owned timer callback") } @@ -669,6 +673,9 @@ pub fn installed_timer_counts(vm: &mut Vm) -> VmResult { /// and must be positive (a zero repeating interval is rejected). /// * Registration uses the installed [`TimerConfig`] limits, which travel with /// every [`TimerRegistration`] as MUST-enforce backend obligations. +/// * Success returns the logical Unit as its internal Null payload: a +/// registration has no confirmation value, and absence/failure is already +/// the outer `VmResult` error channel. /// /// The helper is name-independent and unit-independent: it never inspects the /// call's host name and never converts units. A milliseconds adapter @@ -734,7 +741,7 @@ pub fn register_owned_timer( backend.register(registration) })); match result { - Ok(Ok(())) => Ok(CallOutcome::Return(CallReturn::one(Value::Bool(true)))), + Ok(Ok(())) => Ok(CallOutcome::Return(CallReturn::one(Value::Null))), Ok(Err(error)) => { call.restore_arg(callback_arg, rollback_callback)?; Err(error) @@ -1041,7 +1048,7 @@ mod tests { passing: HostParamPassing::TakeOwned, }, ], - return_type: HostTypeSchema::Bool, + return_type: HostTypeSchema::Unit, fingerprint: timer_host_catalog().fingerprint(), }; let duplicate = registry diff --git a/tests/common/mod.rs b/tests/common/mod.rs index 51da5ada..85a4b94d 100644 --- a/tests/common/mod.rs +++ b/tests/common/mod.rs @@ -364,7 +364,9 @@ impl HostFunction for AlwaysAllow { impl HostFunction for RuntimeSleep { fn call(&mut self, _vm: &mut Vm, _args: &[Value]) -> Result { - Ok(CallOutcome::Return(vec![Value::Bool(true)].into())) + // `runtime::sleep` declares the logical Unit result, so a stand-in host + // supplies the internal Null payload instead of a confirmation value. + Ok(CallOutcome::Return(vec![Value::Null].into())) } } diff --git a/tests/compiler/compiler_rustscript_tests.rs b/tests/compiler/compiler_rustscript_tests.rs index 4d2a40d1..7c4fd8a5 100644 --- a/tests/compiler/compiler_rustscript_tests.rs +++ b/tests/compiler/compiler_rustscript_tests.rs @@ -100,11 +100,11 @@ fn rustscript_host_import_runtime_cases_work() { use runtime; runtime::sleep(41); "#, - vec![Value::Bool(true)], + vec![Value::Null], ), bindings: vec![HostBindingCase { name: "runtime::sleep", - factory: make_always_allow, + factory: make_runtime_sleep, }], }, BoundRuntimeCase { @@ -128,11 +128,11 @@ fn rustscript_host_import_runtime_cases_work() { use runtime; runtime::sleep(41); "#, - vec![Value::Bool(true)], + vec![Value::Null], ), bindings: vec![HostBindingCase { name: "runtime::sleep", - factory: make_always_allow, + factory: make_runtime_sleep, }], }, BoundRuntimeCase { @@ -156,11 +156,11 @@ fn rustscript_host_import_runtime_cases_work() { use runtime as rt; rt::sleep(41); "#, - vec![Value::Bool(true)], + vec![Value::Null], ), bindings: vec![HostBindingCase { name: "runtime::sleep", - factory: make_always_allow, + factory: make_runtime_sleep, }], }, ]; @@ -573,7 +573,10 @@ fn compile_source_file_with_rustscript_complex_fixture() { .expect("vm should complete host operation"), } } - assert_eq!(vm.stack(), &[Value::Int(12)]); + // The top of the stack is still the fixture's result value. The `runtime::sleep` + // statement below it contributes its logical Unit carrier (the internal Null), + // because a statement-position host call keeps its result on the operand stack. + assert_eq!(vm.stack(), &[Value::Null, Value::Int(12)]); } #[test] diff --git a/tests/compiler/type_inference_tests.rs b/tests/compiler/type_inference_tests.rs index 810b29a4..8c9ee7f9 100644 --- a/tests/compiler/type_inference_tests.rs +++ b/tests/compiler/type_inference_tests.rs @@ -734,8 +734,8 @@ fn compiler_type_inference_runtime_cases_cover_host_signature_flows() { "edge host namespace signatures propagate to comparisons", r#" use runtime; - let slept = runtime::sleep(1); - slept == true; + let slept: () = runtime::sleep(1); + slept == (); "#, vec![Value::Bool(true)], vec![HostBindingCase { @@ -744,7 +744,7 @@ fn compiler_type_inference_runtime_cases_cover_host_signature_flows() { }], &[TypeMetadataExpectation::LastExact { opcode: OpCode::Ceq, - expected: (ValueType::Bool, ValueType::Bool), + expected: (ValueType::Null, ValueType::Null), }], ), ]; diff --git a/tests/host_binding_generation_tests.rs b/tests/host_binding_generation_tests.rs index 1bc29566..45c5021a 100644 --- a/tests/host_binding_generation_tests.rs +++ b/tests/host_binding_generation_tests.rs @@ -256,7 +256,7 @@ fn assert_runtime_sleep_loop_uses_native_host_call(bind_cached_registry: bool) { use runtime; let mut i = 0; while i < 100 { - let _ = runtime::sleep(0); + let slept: () = runtime::sleep(0); i = i + 1; } i; @@ -342,7 +342,7 @@ fn restricted_capabilities_disable_trace_jit_for_host_imports_and_builtins() { use runtime; let mut i = 0; while i < 4 { - let _ = runtime::sleep(0); + let slept: () = runtime::sleep(0); i = i + 1; } i; diff --git a/tests/standard_host_descriptor_arch_tests.rs b/tests/standard_host_descriptor_arch_tests.rs index 395c58dd..52e140ec 100644 --- a/tests/standard_host_descriptor_arch_tests.rs +++ b/tests/standard_host_descriptor_arch_tests.rs @@ -23,16 +23,20 @@ use std::path::{Path, PathBuf}; const HTTP_SURFACE_ENABLED: bool = cfg!(all(feature = "http-client", not(target_family = "wasm"))); // Current descriptor identities, selected for the actual native feature set. +// +// These were re-pinned when `timer::at` / `timer::every` moved from a fixed +// `true` result to the logical Unit result: the timer module schema is part of +// both the timer and the composed standard catalog identity. const SQLITE_SURFACE_ENABLED: bool = cfg!(all(feature = "sqlite", not(target_family = "wasm"))); -const STANDARD_CATALOG_FINGERPRINT_HTTP_SQLITE: &str = "b704c1210e3ab4a4"; -const STANDARD_CATALOG_FINGERPRINT_SQLITE: &str = "6cad8e423debdebd"; -const STANDARD_CATALOG_FINGERPRINT_HTTP: &str = "c9e705595cfd2cc7"; -const STANDARD_CATALOG_FINGERPRINT_BASE: &str = "8254b00d727494b4"; +const STANDARD_CATALOG_FINGERPRINT_HTTP_SQLITE: &str = "84cb7f8e3872bec4"; +const STANDARD_CATALOG_FINGERPRINT_SQLITE: &str = "b0d7ea2d8fb1c73d"; +const STANDARD_CATALOG_FINGERPRINT_HTTP: &str = "e49304b3042a55cf"; +const STANDARD_CATALOG_FINGERPRINT_BASE: &str = "9683c55f6e57531c"; const IO_CATALOG_FINGERPRINT: &str = "a16730bd11bf5e10"; #[cfg(all(feature = "sqlite", not(target_family = "wasm")))] const SQLITE_CATALOG_FINGERPRINT: &str = "740ab59ccb8fd09a"; const JIT_CATALOG_FINGERPRINT: &str = "ae81318e8a018681"; -const TIMER_CATALOG_FINGERPRINT: &str = "7ecc0517cea3570b"; +const TIMER_CATALOG_FINGERPRINT: &str = "cf14ffffd6b39273"; #[cfg(all(feature = "http-client", not(target_family = "wasm")))] const HTTP_CATALOG_FINGERPRINT: &str = "41e6557a7dd03118"; fn standard_catalog_fingerprint() -> &'static str { diff --git a/tests/timer_host_arch_tests.rs b/tests/timer_host_arch_tests.rs index 1b27ea83..17095189 100644 --- a/tests/timer_host_arch_tests.rs +++ b/tests/timer_host_arch_tests.rs @@ -541,8 +541,15 @@ fn assert_timer_no_nullable_or_void(path: &str, schema: &HostTypeSchema) { HostTypeSchema::Optional(_) | HostTypeSchema::Option(_) => { panic!("timer public schema {path} exposes a nullable route: {schema:?}") } - HostTypeSchema::Null | HostTypeSchema::Unit => { - panic!("timer public schema {path} exposes a void/null route: {schema:?}") + HostTypeSchema::Null => { + panic!("timer public schema {path} exposes a null route: {schema:?}") + } + HostTypeSchema::Unit => { + // `timer::{at,every}` legitimately report logical Unit on success; + // the caller checks that top-level result explicitly. A Unit nested + // in an array, map, struct field, or callback would still be a + // shape regression, so the recursive helper keeps rejecting it. + panic!("timer public schema {path} exposes a nested void route: {schema:?}") } HostTypeSchema::Array(inner) => { assert_timer_no_nullable_or_void(&format!("{path}[]"), inner) @@ -581,7 +588,7 @@ fn assert_timer_no_nullable_or_void(path: &str, schema: &HostTypeSchema) { } #[test] -fn timer_public_contract_keeps_boolean_and_count_results_without_nullable_routes() { +fn timer_public_contract_keeps_concrete_results_without_nullable_routes() { let catalog = vm::timer_host_catalog(); for function in catalog.functions() { for param in &function.params { @@ -590,14 +597,18 @@ fn timer_public_contract_keeps_boolean_and_count_results_without_nullable_routes ¶m.ty, ); } - assert_timer_no_nullable_or_void( - &format!("{} return", function.name), - &function.return_type, - ); + // The registration commands report the logical Unit result; a + // registration has no confirmation value left to report. + if !matches!(function.name.as_str(), "timer::at" | "timer::every") { + assert_timer_no_nullable_or_void( + &format!("{} return", function.name), + &function.return_type, + ); + } } let at = catalog.function("timer::at").expect("timer::at"); - assert_eq!(at.return_type, HostTypeSchema::Bool); + assert_eq!(at.return_type, HostTypeSchema::Unit); assert_eq!( at.params[1].ty, HostTypeSchema::Callable { @@ -618,6 +629,6 @@ fn timer_public_contract_keeps_boolean_and_count_results_without_nullable_routes .function("timer::every") .expect("timer::every") .return_type, - HostTypeSchema::Bool + HostTypeSchema::Unit ); } diff --git a/tests/timer_host_tests.rs b/tests/timer_host_tests.rs index 5e000532..a9b2c404 100644 --- a/tests/timer_host_tests.rs +++ b/tests/timer_host_tests.rs @@ -1820,7 +1820,9 @@ fn vendor_catalog() -> Arc { HostParamPassing::TakeOwned, ), ], - HostTypeSchema::Bool, + // The shared `register_owned_timer` seam reports logical Unit on + // success, so the downstream adapter must not keep a `true` schema. + HostTypeSchema::Unit, )); } builder.function(HostFunctionSchema::with_return( @@ -1831,7 +1833,7 @@ fn vendor_catalog() -> Arc { // so the runtime type check (not the compiler) decides. HostParamSchema::value("callback", HostTypeSchema::Unknown), ], - HostTypeSchema::Bool, + HostTypeSchema::Unit, )); for name in ["vendor::pending", "vendor::running"] { builder.function(HostFunctionSchema::with_return( diff --git a/tests/vm/vm_runtime_tests.rs b/tests/vm/vm_runtime_tests.rs index af432fef..eb311870 100644 --- a/tests/vm/vm_runtime_tests.rs +++ b/tests/vm/vm_runtime_tests.rs @@ -1104,7 +1104,8 @@ fn runtime_sleep_host_import_is_available_by_default() { let status = vm.run().expect("vm should run"); assert_eq!(status, VmStatus::Halted); - assert_eq!(vm.stack(), &[Value::Bool(true)]); + // `runtime::sleep` reports the logical Unit carrier, not a success `true`. + assert_eq!(vm.stack(), &[Value::Null]); } #[test] @@ -1134,7 +1135,7 @@ fn runtime_sleep_host_import_can_be_overridden_by_host_binding() { impl HostFunction for RuntimeSleepOverride { fn call(&mut self, _vm: &mut Vm, args: &[Value]) -> Result { assert_eq!(args, &[Value::Int(3)]); - Ok(CallOutcome::Return(vec![Value::Bool(true)].into())) + Ok(CallOutcome::Return(vec![Value::Null].into())) } } @@ -1150,7 +1151,7 @@ fn runtime_sleep_host_import_can_be_overridden_by_host_binding() { let status = vm.run().expect("vm should run"); assert_eq!(status, VmStatus::Halted); - assert_eq!(vm.stack(), &[Value::Bool(true)]); + assert_eq!(vm.stack(), &[Value::Null]); } #[test] @@ -1170,7 +1171,8 @@ fn host_function_registry_includes_default_runtime_sleep() { let status = vm.run().expect("vm should run"); assert_eq!(status, VmStatus::Halted); - assert_eq!(vm.stack(), &[Value::Bool(true)]); + // The default binding reports the logical Unit carrier, not `true`. + assert_eq!(vm.stack(), &[Value::Null]); } #[test] From 1989e0a625780867eb17baf34b06919d222dbdfa Mon Sep 17 00:00:00 2001 From: fffonion Date: Sat, 14 Nov 2026 18:35:41 +0800 Subject: [PATCH 04/16] fix(wasm): return Unit from the sleep completion The browser async bridge completed `runtime::sleep` with `Value::Bool(true)`, so the playground left a success `true` in the guest value slot while Core declares the logical Unit result. Wasm binds hosts by name and installs no import schema, so the Core return check never ran there and the divergence stayed silent. - Complete the deadline poll with the Unit carrier (`Value::Null`), matching `timer::at` / `timer::every` and the other command hosts. No other wasm command host still returns an old success confirmation. - Cover the bridge return and the guest-visible value slot, and pin the Unit slot in the embedded-stdlib + named-runtime-import case. Before this fix the new assertions report `left: One(Bool(true))` / `left: ["true"]`. - Assert the `Option::Some` payload directly in the collections-iter example, the bytes spec and the lrucache spec instead of threading a `-1` sentinel that a missing payload would satisfy. - Note `runtime::sleep` and `aot::compile` / `aot::clear` in the standard catalog fingerprint comment, and assert the Unit carrier on timer registration success. --- .../examples/rss-collections-iter-example.rss | 9 ++-- pd-vm-wasm/src/lib.rs | 30 ++++++++++++++ pd-vm-wasm/src/runtime.rs | 41 ++++++++++++++++++- stdlib/tests/bytes.rss | 24 +++++------ stdlib/tests/lrucache.rss | 16 ++++---- tests/standard_host_descriptor_arch_tests.rs | 5 ++- tests/timer_host_tests.rs | 13 +++++- 7 files changed, 111 insertions(+), 27 deletions(-) diff --git a/pd-vm-wasm/examples/rss-collections-iter-example.rss b/pd-vm-wasm/examples/rss-collections-iter-example.rss index d2927eb9..2f2078d3 100644 --- a/pd-vm-wasm/examples/rss-collections-iter-example.rss +++ b/pd-vm-wasm/examples/rss-collections-iter-example.rss @@ -77,11 +77,12 @@ assert(config_value_count == 3); let reversed_preview: [string] = collections::reverse::(["world", "finance"]); let combined_names: [string] = reversed_preview + ["archive"]; -let archive_index: int = match collections::index_of::(&combined_names, "archive") { - Option::Some(value) => value, - Option::None => -1, +let archive_index: Option = collections::index_of::(&combined_names, "archive"); +let archive_index_matches: bool = match archive_index { + Option::Some(value) => value == 2, + Option::None => false, }; -assert(archive_index == 2); +assert(archive_index_matches); let missing_index: bool = match collections::index_of::(&combined_names, "sports") { Option::Some(_) => false, Option::None => true, diff --git a/pd-vm-wasm/src/lib.rs b/pd-vm-wasm/src/lib.rs index 122ca301..6955a850 100644 --- a/pd-vm-wasm/src/lib.rs +++ b/pd-vm-wasm/src/lib.rs @@ -2205,6 +2205,13 @@ mod runtime_tests { "expected stack to include trimmed string, got {:?}", report.stack ); + assert_eq!( + report.stack.first().map(String::as_str), + Some("null"), + "the named runtime host must leave the Unit carrier in the sleep value slot, \ + not a success bool; stack = {:?}", + report.stack + ); } #[test] @@ -2347,6 +2354,29 @@ mod runtime_tests { ); } + /// `runtime::sleep` declares the logical Unit result, so a completed sleep + /// must leave the Unit carrier (`null`) in the value slot. The wasm binding + /// is name-based and installs no import schema, so the Core return check + /// cannot catch a stray success `true` here — only this assertion can. + #[test] + fn sleep_completion_leaves_the_unit_carrier_on_the_stack() { + let source = r#" + use runtime; + runtime::sleep(0); + "#; + let report = run_source_with_flavor(source, SourceFlavor::RustScript); + assert!( + report.error.is_none(), + "expected runtime::sleep to succeed, got {:?}", + report.error + ); + assert_eq!( + report.stack, + vec!["null".to_string()], + "a completed runtime::sleep must report Unit (null), not a success bool" + ); + } + #[test] fn debug_session_supports_breakpoints_and_hover_print() { let source = r#" diff --git a/pd-vm-wasm/src/runtime.rs b/pd-vm-wasm/src/runtime.rs index 3043f070..72039625 100644 --- a/pd-vm-wasm/src/runtime.rs +++ b/pd-vm-wasm/src/runtime.rs @@ -290,7 +290,12 @@ impl HostAsyncBridge for BrowserAsyncBridge { }; if current_time_ms() >= deadline_ms { state.deadlines_ms.remove(&op_id); - Poll::Ready(Ok(CallReturn::one(Value::Bool(true)))) + // `runtime::sleep` declares the logical Unit result, so completion + // reports the Unit carrier (`Null`). Returning a success `true` + // would leak a Bool into the guest value slot: the Core return + // check rejects it for schema-bound binds, and the name-based wasm + // binding installs no import schema, so nothing would catch it. + Poll::Ready(Ok(CallReturn::one(Value::Null))) } else { Poll::Pending } @@ -1392,3 +1397,37 @@ fn push_output_line(lines: &Arc>>, rendered: String) { guard.push(normalized); } } + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn sleep_completion_is_the_unit_carrier() { + let state = Arc::new(Mutex::new(BrowserAsyncState::default())); + let op_id = 7; + state + .lock() + .expect("async state") + .deadlines_ms + .insert(op_id, 0.0); + let mut bridge = BrowserAsyncBridge::new(Arc::clone(&state)); + let waker = Waker::noop().clone(); + let mut cx = Context::from_waker(&waker); + + let completed = bridge.poll_op(op_id, &mut cx); + match completed { + Poll::Ready(Ok(returned)) => assert_eq!( + returned, + CallReturn::one(Value::Null), + "a reached deadline must complete with the Unit carrier, not a success bool" + ), + Poll::Ready(Err(error)) => panic!("sleep completion must not fail: {error:?}"), + Poll::Pending => panic!("a reached deadline must complete, not stay pending"), + } + assert!( + state.lock().expect("async state").deadlines_ms.is_empty(), + "completion must drop the deadline entry" + ); + } +} diff --git a/stdlib/tests/bytes.rss b/stdlib/tests/bytes.rss index 9d3207d6..a0239672 100644 --- a/stdlib/tests/bytes.rss +++ b/stdlib/tests/bytes.rss @@ -38,23 +38,23 @@ assert(bytes_std::ends_with(hello, builtin_bytes::from_utf8("he")) == false); // W02: `index_of` reports absence with `Option`; an empty needle is still // a real match at offset 0. -let empty_needle_index = match bytes_std::index_of(hello, builtin_bytes::from_utf8("")) { - Option::Some(value) => value, - Option::None => -1, +let empty_needle_matches: bool = match bytes_std::index_of(hello, builtin_bytes::from_utf8("")) { + Option::Some(value) => value == 0, + Option::None => false, }; -assert(empty_needle_index == 0); +assert(empty_needle_matches); -let middle_index = match bytes_std::index_of(hello, builtin_bytes::from_utf8("ll")) { - Option::Some(value) => value, - Option::None => -1, +let middle_index_matches: bool = match bytes_std::index_of(hello, builtin_bytes::from_utf8("ll")) { + Option::Some(value) => value == 2, + Option::None => false, }; -assert(middle_index == 2); +assert(middle_index_matches); -let last_index = match bytes_std::index_of(hello, builtin_bytes::from_utf8("o")) { - Option::Some(value) => value, - Option::None => -1, +let last_index_matches: bool = match bytes_std::index_of(hello, builtin_bytes::from_utf8("o")) { + Option::Some(value) => value == 4, + Option::None => false, }; -assert(last_index == 4); +assert(last_index_matches); let absent = bytes_std::index_of(hello, builtin_bytes::from_utf8("zz")); let absent_is_none = match absent { diff --git a/stdlib/tests/lrucache.rss b/stdlib/tests/lrucache.rss index bc5547cd..3193fb50 100644 --- a/stdlib/tests/lrucache.rss +++ b/stdlib/tests/lrucache.rss @@ -19,11 +19,11 @@ assert(initial_keys[0] == "a"); assert(initial_keys[1] == "b"); // W01: `peek` reports presence with `Option` and never promotes recency. -let peeked_value = match peek::(cache, "a") { - Option::Some(value) => value, - Option::None => -1, +let peeked_matches: bool = match peek::(cache, "a") { + Option::Some(value) => value == 1, + Option::None => false, }; -assert(peeked_value == 1); +assert(peeked_matches); let peeked_absent = match peek::(cache, "missing") { Option::Some(_) => false, Option::None => true, @@ -36,11 +36,11 @@ assert(still_initial[1] == "b"); // `get` keeps the updated cache and the payload; the redundant `found` flag is // gone, so absence is read from the `Option` alone. let mut accessed = get::(cache, "a"); -let accessed_value = match accessed.value { - Option::Some(value) => value, - Option::None => -1, +let accessed_matches: bool = match accessed.value { + Option::Some(value) => value == 1, + Option::None => false, }; -assert(accessed_value == 1); +assert(accessed_matches); cache = accessed.cache; let mut after_get = keys::(cache); assert(after_get[0] == "b"); diff --git a/tests/standard_host_descriptor_arch_tests.rs b/tests/standard_host_descriptor_arch_tests.rs index 52e140ec..4d96b405 100644 --- a/tests/standard_host_descriptor_arch_tests.rs +++ b/tests/standard_host_descriptor_arch_tests.rs @@ -26,7 +26,10 @@ const HTTP_SURFACE_ENABLED: bool = cfg!(all(feature = "http-client", not(target_ // // These were re-pinned when `timer::at` / `timer::every` moved from a fixed // `true` result to the logical Unit result: the timer module schema is part of -// both the timer and the composed standard catalog identity. +// both the timer and the composed standard catalog identity. The composed +// standard catalog also carries `runtime::sleep` (same Unit result) and the +// `aot::compile` / `aot::clear` command hosts, so any result-type change to +// those two surface families re-pins these values as well. const SQLITE_SURFACE_ENABLED: bool = cfg!(all(feature = "sqlite", not(target_family = "wasm"))); const STANDARD_CATALOG_FINGERPRINT_HTTP_SQLITE: &str = "84cb7f8e3872bec4"; const STANDARD_CATALOG_FINGERPRINT_SQLITE: &str = "b0d7ea2d8fb1c73d"; diff --git a/tests/timer_host_tests.rs b/tests/timer_host_tests.rs index a9b2c404..2bb54671 100644 --- a/tests/timer_host_tests.rs +++ b/tests/timer_host_tests.rs @@ -751,6 +751,12 @@ fn at_registers_and_returns_then_callback_runs() { ) .expect("registration succeeds"); assert_eq!(vm.take_callable_result(), None); + assert_eq!( + vm.stack(), + &[Value::Null], + "a successful registration reports the Unit carrier in the value slot, \ + not a success bool and not a missing value" + ); assert_eq!(backend.pending_count(), 1); let mut registration = backend.pop(); @@ -812,12 +818,17 @@ fn default_limits_match_the_documented_contract() { #[test] fn every_marks_interval_and_preserves_callable_between_rounds() { let backend = Arc::new(ManualBackend::default()); - run_with_backend( + let vm = run_with_backend( "use timer; timer::every(7, |premature| ());", Arc::clone(&backend), TimerConfig::default(), ) .expect("registration succeeds"); + assert_eq!( + vm.stack(), + &[Value::Null], + "a successful interval registration reports the Unit carrier in the value slot" + ); let mut registration = backend.pop(); assert_eq!(registration.delay, Duration::from_millis(7)); assert_eq!(registration.interval, Some(Duration::from_millis(7))); From ace8b0627c4a9cb94de5528171a02dd4beb16009 Mon Sep 17 00:00:00 2001 From: fffonion Date: Sat, 14 Nov 2026 19:10:56 +0800 Subject: [PATCH 05/16] feat(typing): type builtin guest unions from their host contracts MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A namespaced builtin's guest return type was inferred from the coarse `ValueType` of its Rust signature, so a `Result` contract stayed invisible to `?` and `match`: `io::open(...)` typed as `int` even though its catalog contract returns `resource`. The runtime dispatch now exposes `guest_return_schema`, the `HostTypeSchema` the builtin's published descriptor declares — a declared contract when the function has one, otherwise the signature-derived schema. It is emitted into the dispatch unit because that unit owns the private backend modules the descriptors are declared in. Only `Result` carriers are surfaced, so every other builtin keeps the existing `ValueType` inference and no guest type moves until a builtin actually returns a `GuestResult`. --- build.rs | 76 ++++++++++++++++++++++++++++++++++ src/compiler/typing/context.rs | 25 ++++++++++- 2 files changed, 99 insertions(+), 2 deletions(-) diff --git a/build.rs b/build.rs index 444d4a94..b59e3c02 100644 --- a/build.rs +++ b/build.rs @@ -1284,6 +1284,9 @@ fn render_builtin_runtime_dispatch( .unwrap(); writeln!(&mut out, " }}").unwrap(); writeln!(&mut out, "}}").unwrap(); + writeln!(&mut out).unwrap(); + + render_builtin_guest_return_schema_method(&mut out, builtin_callables); out } @@ -1647,6 +1650,79 @@ fn render_builtin_static_return_type_method( writeln!(out).unwrap(); } +/// Emits `guest_return_schema` into the runtime dispatch unit: the guest +/// return schema a namespaced builtin's published descriptor declares. +/// +/// A carrier's coarse `ValueType` cannot express its payloads (and the nominal +/// resource keys inside them), so the schema comes from the same descriptor the +/// module catalog publishes — a declared contract when the function has one, +/// otherwise the signature-derived schema. Only `Result` carriers are surfaced +/// to the compiler; every other return keeps the `ValueType` inference. +/// +/// The method lives in the dispatch unit because that unit owns the private +/// backend modules (`io`, `math`, `host`, …) the descriptors are declared in. +fn render_builtin_guest_return_schema_method(out: &mut String, builtin_callables: &[CallableDecl]) { + writeln!(out, "impl BuiltinFunction {{").unwrap(); + writeln!( + out, + " /// The guest return schema this builtin's published descriptor declares." + ) + .unwrap(); + writeln!(out, " ///").unwrap(); + writeln!( + out, + " /// Only `Result` carriers are reported: a scalar return is already fully" + ) + .unwrap(); + writeln!( + out, + " /// described by `static_return_type`, while a carrier's payloads and the" + ) + .unwrap(); + writeln!( + out, + " /// nominal resource keys inside them only exist in the descriptor." + ) + .unwrap(); + writeln!( + out, + " pub(crate) fn guest_return_schema(self) -> Option {{" + ) + .unwrap(); + writeln!(out, " let schema = match self {{").unwrap(); + for callable in builtin_callables + .iter() + .filter(|callable| callable.wrapper.is_some()) + { + let variant = builtin_variant_name(&callable.name); + let module = &callable.module; + let wrapper_name = callable + .rust_ident + .strip_suffix("_impl") + .unwrap_or(&callable.rust_ident); + writeln!( + out, + " BuiltinFunction::{variant} => \ + {module}::{wrapper_name}_descriptor().schema.return_type," + ) + .unwrap(); + } + writeln!( + out, + " _ => crate::host_api::HostTypeSchema::Unknown," + ) + .unwrap(); + writeln!(out, " }};").unwrap(); + writeln!( + out, + " matches!(schema, crate::host_api::HostTypeSchema::Result {{ .. }}).then_some(schema)" + ) + .unwrap(); + writeln!(out, " }}").unwrap(); + writeln!(out, "}}").unwrap(); + writeln!(out).unwrap(); +} + fn render_builtin_signature_method(out: &mut String, builtin_variant_order: &[String]) { writeln!( out, diff --git a/src/compiler/typing/context.rs b/src/compiler/typing/context.rs index 80b9ea27..22804c36 100644 --- a/src/compiler/typing/context.rs +++ b/src/compiler/typing/context.rs @@ -2015,7 +2015,10 @@ impl<'a> TypeContext<'a> { BuiltinFunction::MathClamp if args.len() == 3 => { self.infer_numeric_triplet_return_type(&args[0], &args[1], &args[2], state) } - _ => BoundType::from(builtin.static_return_type()), + _ => match builtin_guest_return_schema(builtin) { + Some(schema) => self.bound_type_for_schema(&schema), + None => BoundType::from(builtin.static_return_type()), + }, } } @@ -2077,7 +2080,7 @@ impl<'a> TypeContext<'a> { _ => None, } } - _ => None, + _ => builtin_guest_return_schema(builtin), } } @@ -3756,6 +3759,24 @@ fn schema_instance_key( } } +/// The guest return schema of a builtin whose result is a logical carrier +/// (`Result<...>` or `Option<...>`), read from its published host descriptor. +/// +/// Only carriers need this: a scalar return is already fully described by +/// [`BuiltinFunction::static_return_type`], while a carrier's payloads (and the +/// nominal resource keys inside them) are only available through the contract +/// the module catalog publishes. +#[cfg(feature = "runtime")] +fn builtin_guest_return_schema(builtin: BuiltinFunction) -> Option { + let schema = builtin.guest_return_schema()?.to_compiler_schema(); + (!matches!(schema, TypeSchema::Unknown)).then_some(schema) +} + +#[cfg(not(feature = "runtime"))] +fn builtin_guest_return_schema(_builtin: BuiltinFunction) -> Option { + None +} + fn builtin_generic_return_schema( builtin: BuiltinFunction, type_args: &[TypeSchema], From 4ac0391ba58b626315c6e145d0ffc6b5ff10304a Mon Sep 17 00:00:00 2001 From: fffonion Date: Sat, 14 Nov 2026 19:37:50 +0800 Subject: [PATCH 06/16] feat(io): report IO outcomes as Result instead of sentinels The IO guest surface could not distinguish "empty" from "failed": an EOF read_line returned "", every flush/close returned a fixed `true`, and an open on a missing file aborted the VM. Every fallible IO call now declares `Result`: `io.open`/`io.popen` -> `Result, string>`, `io.read_all` -> `Result`, `io.read_line` -> `Result, string>`, `io.write` -> `Result` (bytes written), `io.flush`/`io.close` -> `Result<(), string>`, and `io.exists` keeps its Boolean. `read_line` drops the single trailing newline, so EOF is `Ok(None)`, a real empty line is `Ok(Some(""))`, and an empty file reads as `Ok("")`. Only ordinary file-system outcomes take the `Err` branch. Invalid or closed handles, resource borrow/ownership/scope failures, policy and capability denials, read/write limits, unsupported modes and wasm rejections stay fatal `VmError`s. A failed close still retires its scope resource: the blocking backend falls back to the drop path (which signals the process tree), and the async backend detaches the shared handle before retirement. The three backends share the contracts declared in `io/mod.rs`, including new contracts for popen/read_line/write/flush, so the descriptor schema cannot drift per target. The async adapter returns its carriers through `HostFutureOutput` plus `publish_owned`, because an owned resource inside a `GuestResult` cannot cross a future publication. `stdlib/rss/io.rss` propagates with `?` and no longer swallows close or flush failures; the stdlib, blocking, async and descriptor-install suites migrate to the new contract and pin the recoverable outcomes by name. EOF and empty-file assertions, the write byte count, and the Unit close/flush results replace the former sentinel checks. --- docs/host-sdk-descriptors.md | 31 +-- src/builtins/runtime/io/async_io.rs | 191 ++++++++++++---- src/builtins/runtime/io/blocking.rs | 221 ++++++++++++------- src/builtins/runtime/io/mod.rs | 92 +++++++- src/builtins/runtime/io_wasm.rs | 26 ++- stdlib/rss/io.rss | 45 ++-- stdlib/tests/io.rss | 24 ++- stdlib/tests/io_primitives.rss | 19 +- tests/builtins/io_async_tests.rs | 175 +++++++++++++-- tests/builtins/io_builtin_edge_tests.rs | 239 +++++++++++++++++++-- tests/builtins/io_scope_lifecycle_tests.rs | 88 ++++++-- tests/io_descriptor_install_tests.rs | 157 +++++++------- 12 files changed, 995 insertions(+), 313 deletions(-) diff --git a/docs/host-sdk-descriptors.md b/docs/host-sdk-descriptors.md index c3266a92..65271b60 100644 --- a/docs/host-sdk-descriptors.md +++ b/docs/host-sdk-descriptors.md @@ -212,26 +212,33 @@ pub(crate) async fn builtin_io_open( #[pd_host_context] context: IoPolicyContext, path: String, mode: String, -) -> VmResult> { +) -> VmResult> { // Mode validation and `OpenOptions` setup are omitted here. let path = authorize_io_path(context.policy.as_ref(), &path, writes).await?; - let file = options - .open(path) - .await - .map_err(|error| VmError::HostError(format!("io_open failed: {error}")))?; + let file = match options.open(path).await { + Ok(file) => file, + // A recoverable failure is the contract's `Err` branch, never a VM fault. + Err(error) => return Ok(io_error_output("io_open", error)), + }; let handle = IoHandle::File(BufReader::new(file)); Ok(vm::HostFutureOutput::complete(move |vm| { - let token = vm - .execution_scope() - .push_resource(IoResource::new(handle)) - .map_err(|error| VmError::HostError(format!( - "io resource insert failed: {error}" - )))?; - Ok(token.into_handle().raw() as i64) + publish_open_handle(vm, handle, super::io_open_contract().return_type) })) } ``` +A contract may also declare a fallible return. `io::open`, `io::popen`, +`io::read_all`, `io::read_line`, `io::write`, `io::flush` and `io::close` +declare `Result`, where only ordinary file-system outcomes take the +`Err` branch: invalid or closed handles, ownership/scope errors, policy denials, +byte limits, unsupported modes and capability rejections stay fatal `VmError`s. + +An owned resource cannot cross the future boundary inside a `GuestResult` (the +macro rejects it), so the async adapter returns the assembled guest carrier +through `vm::HostFutureOutput` and publishes it with +`crate::result::publish_owned`, which inserts the resource, validates the +carrier against the declared contract and rolls the insertion back on failure. + When context depends on a resource-token argument, implement `capture_with_args(vm, args)` to validate the token and clone the owned resource state before submission. `IoHandleContext`, `SqliteConnectionContext`, and diff --git a/src/builtins/runtime/io/async_io.rs b/src/builtins/runtime/io/async_io.rs index b407ec37..f1b16491 100644 --- a/src/builtins/runtime/io/async_io.rs +++ b/src/builtins/runtime/io/async_io.rs @@ -30,6 +30,7 @@ use crate::vm::resource::close::{CloseProgress, HostResource}; use crate::vm::resource::error::{ResourceError, ResourceErrorCode, ResourceResult}; use crate::vm::resource::{ResourceCloseReason, ResourceHandle}; use crate::vm::{CaptureAsyncHostContext, HostFutureOutput, Value, Vm, VmError, VmResult}; +use crate::{GuestOption, GuestResult, ResourceOwned}; /// A file / child-process backed IO handle. #[derive(Debug)] @@ -582,12 +583,22 @@ impl CaptureAsyncHostContext for IoHandleContext { } /// Opens a file handle for runtime I/O. +/// +/// Only the `OpenOptions` failure is a guest error; an unsupported mode and a +/// policy denial stay fatal. +/// +/// The async adapter returns the guest `Value` carrier instead of +/// `HostFutureOutput, String>>` because +/// the host SDK rejects owned resources crossing a future publication. The +/// declared contract is unchanged, and [`publish_open_handle`] reuses +/// `publish_owned`, so ownership, schema validation and rollback stay +/// identical to the blocking backend. #[pd_host_function(name = "io::open", contract = super::io_open_contract)] pub(crate) async fn builtin_io_open( #[pd_host_context] context: IoPolicyContext, path: String, mode: String, -) -> VmResult> { +) -> VmResult> { let writes = match mode.as_str() { "r" => false, "w" | "a" | "r+" | "w+" | "a+" => true, @@ -620,27 +631,26 @@ pub(crate) async fn builtin_io_open( } _ => unreachable!("mode validated above"), } - let file = options - .open(path) - .await - .map_err(|error| VmError::HostError(format!("io_open failed: {error}")))?; + let file = match options.open(path).await { + Ok(file) => file, + Err(error) => return Ok(io_error_output("io_open", error)), + }; let handle = IoHandle::File(BufReader::new(file)); Ok(HostFutureOutput::complete(move |vm| { - let token = vm - .execution_scope() - .push_resource(IoResource::new(handle)) - .map_err(|error| VmError::HostError(format!("io resource insert failed: {error}")))?; - Ok(token.into_handle().raw() as i64) + publish_open_handle(vm, handle, super::io_open_contract().return_type) })) } /// Starts a child process and returns a process-backed handle. -#[pd_host_function(name = "io::popen")] +/// +/// An unsupported mode and a disabled process capability stay fatal; a process +/// that cannot be started or wired up is a guest error. +#[pd_host_function(name = "io::popen", contract = super::io_popen_contract)] pub(crate) async fn builtin_io_popen( #[pd_host_context] context: IoPolicyContext, command: String, mode: String, -) -> VmResult> { +) -> VmResult> { if mode != "r" && mode != "w" { return Err(VmError::HostError(format!( "unsupported io_popen mode '{mode}', expected r or w" @@ -655,28 +665,62 @@ pub(crate) async fn builtin_io_popen( "io_popen requires the process capability".to_string(), )); } - let handle = spawn_shell_command(&command, &mode)?; + let handle = match spawn_shell_command(&command, &mode) { + Ok(handle) => handle, + Err(message) => { + return Ok(HostFutureOutput::returning(crate::result::carrier( + false, + Value::string(&message), + ))); + } + }; Ok(HostFutureOutput::complete(move |vm| { - let token = vm - .execution_scope() - .push_resource(IoResource::new(handle)) - .map_err(|error| VmError::HostError(format!("io resource insert failed: {error}")))?; - Ok(token.into_handle().raw() as i64) + publish_open_handle(vm, handle, super::io_popen_contract().return_type) })) } +/// Publishes an opened handle as the `Ok` branch of `io.open` / `io.popen`. +/// +/// `publish_owned` validates the assembled carrier against `schema`, inserts +/// the resource into the execution scope and rolls the insertion back when +/// assembly fails, so the async adapter keeps the blocking backend's ownership +/// guarantees despite crossing the future boundary with a plain `Value`. +fn publish_open_handle( + vm: &mut Vm, + handle: IoHandle, + schema: crate::HostTypeSchema, +) -> VmResult { + crate::result::publish_owned::( + vm, + ResourceOwned::new(IoResource::new(handle)), + &schema, + |token| Ok(crate::result::carrier(true, token)), + ) +} + +/// The guest `Err` carrier of a recoverable IO failure. +fn io_error_output(operation: &str, error: io::Error) -> HostFutureOutput { + HostFutureOutput::returning(crate::result::carrier( + false, + Value::string(super::io_failure(operation, error)), + )) +} + /// Reads all remaining text from an I/O handle. +/// +/// A read failure is a guest error; an unusable handle kind and the read limit +/// stay fatal. #[pd_host_function(name = "io::read_all", contract = super::io_read_all_contract)] pub(crate) async fn builtin_io_read_all( #[pd_host_context] context: IoHandleContext, _handle_id: i64, -) -> VmResult> { +) -> VmResult>> { let mut slot = context.handle.lock().await; let handle = slot .as_mut() .ok_or_else(|| VmError::HostError("io handle is closed".to_string()))?; let mut out = String::new(); - match handle { + let read = match handle { IoHandle::File(file) => file.read_to_string(&mut out).await, IoHandle::PopenRead { stdout, .. } => stdout.read_to_string(&mut out).await, IoHandle::PopenWrite { .. } => { @@ -684,8 +728,12 @@ pub(crate) async fn builtin_io_read_all( "io_read_all requires a readable handle".to_string(), )); } + }; + if let Err(error) = read { + return Ok(HostFutureOutput::returning(GuestResult::Err( + super::io_failure("io_read_all", error), + ))); } - .map_err(|error| VmError::HostError(format!("io_read_all failed: {error}")))?; if context .max_read_bytes .is_some_and(|limit| out.len() > limit) @@ -694,21 +742,25 @@ pub(crate) async fn builtin_io_read_all( "io_read_all exceeded read limit".to_string(), )); } - Ok(HostFutureOutput::returning(out)) + Ok(HostFutureOutput::returning(GuestResult::Ok(out))) } /// Reads a single line of text from an I/O handle. -#[pd_host_function(name = "io::read_line")] +/// +/// End of file is `Ok(None)` and an empty line is `Ok(Some(""))`: the returned +/// line has its single trailing `\n` removed. A read failure is a guest error; +/// an unusable handle kind and the read limit stay fatal. +#[pd_host_function(name = "io::read_line", contract = super::io_read_line_contract)] pub(crate) async fn builtin_io_read_line( #[pd_host_context] context: IoHandleContext, _handle_id: i64, -) -> VmResult> { +) -> VmResult, String>>> { let mut slot = context.handle.lock().await; let handle = slot .as_mut() .ok_or_else(|| VmError::HostError("io handle is closed".to_string()))?; let mut line = String::new(); - match handle { + let read = match handle { IoHandle::File(file) => file.read_line(&mut line).await, IoHandle::PopenRead { stdout, .. } => stdout.read_line(&mut line).await, IoHandle::PopenWrite { .. } => { @@ -716,8 +768,23 @@ pub(crate) async fn builtin_io_read_line( "io_read_line requires a readable handle".to_string(), )); } + }; + let read = match read { + Ok(read) => read, + Err(error) => { + return Ok(HostFutureOutput::returning(GuestResult::Err( + super::io_failure("io_read_line", error), + ))); + } + }; + if read == 0 { + return Ok(HostFutureOutput::returning(GuestResult::Ok( + GuestOption::None, + ))); + } + if line.ends_with('\n') { + line.pop(); } - .map_err(|error| VmError::HostError(format!("io_read_line failed: {error}")))?; if context .max_read_bytes .is_some_and(|limit| line.len() > limit) @@ -726,16 +793,21 @@ pub(crate) async fn builtin_io_read_line( "io_read_line exceeded read limit".to_string(), )); } - Ok(HostFutureOutput::returning(line)) + Ok(HostFutureOutput::returning(GuestResult::Ok( + GuestOption::Some(line), + ))) } /// Writes text to an I/O handle. -#[pd_host_function(name = "io::write")] +/// +/// A write failure is a guest error; an unusable handle kind and the write +/// limit stay fatal. +#[pd_host_function(name = "io::write", contract = super::io_write_contract)] pub(crate) async fn builtin_io_write( #[pd_host_context] context: IoHandleContext, _handle_id: i64, text: String, -) -> VmResult> { +) -> VmResult>> { if context .max_write_bytes .is_some_and(|limit| text.len() > limit) @@ -756,37 +828,60 @@ pub(crate) async fn builtin_io_write( "io_write requires a writable handle".to_string(), )); } + }; + match written { + Ok(written) => Ok(HostFutureOutput::returning(GuestResult::Ok(written as i64))), + Err(error) => Ok(HostFutureOutput::returning(GuestResult::Err( + super::io_failure("io_write", error), + ))), } - .map_err(|error| VmError::HostError(format!("io_write failed: {error}")))?; - Ok(HostFutureOutput::returning(written as i64)) } /// Flushes buffered output for an I/O handle. -#[pd_host_function(name = "io::flush")] +/// +/// A flush failure is a guest error; an unusable handle kind stays fatal. +#[pd_host_function(name = "io::flush", contract = super::io_flush_contract)] pub(crate) async fn builtin_io_flush( #[pd_host_context] context: IoHandleContext, _handle_id: i64, -) -> VmResult> { +) -> VmResult>> { let mut slot = context.handle.lock().await; let handle = slot .as_mut() .ok_or_else(|| VmError::HostError("io handle is closed".to_string()))?; - match handle { + let flushed = match handle { IoHandle::File(file) => file.get_mut().flush().await, IoHandle::PopenWrite { stdin, .. } => stdin.flush().await, IoHandle::PopenRead { .. } => Ok(()), + }; + match flushed { + Ok(()) => Ok(HostFutureOutput::returning(GuestResult::Ok(()))), + Err(error) => Ok(HostFutureOutput::returning(GuestResult::Err( + super::io_failure("io_flush", error), + ))), } - .map_err(|error| VmError::HostError(format!("io_flush failed: {error}")))?; - Ok(HostFutureOutput::returning(true)) } /// Closes an I/O handle. +/// +/// A cleanup (flush or process termination) failure is a guest error and still +/// retires the scope resource; an already-closed handle and a pending scope +/// retirement stay fatal. #[pd_host_function(name = "io::close", contract = super::io_close_contract)] pub(crate) async fn builtin_io_close( #[pd_host_context] context: IoHandleContext, _handle_id: i64, -) -> VmResult> { - close_shared_io_handle_with(Arc::clone(&context.handle), close_io_handle_future).await?; +) -> VmResult>> { + let closed = + close_shared_io_handle_with(Arc::clone(&context.handle), close_io_handle_future).await; + let mut close_failure = None; + if let Err(error) = closed { + // Take the failed handle out of the shared slot so the drop path + // signals the process tree and the scope can still retire it; the + // guest reports the cleanup failure instead of aborting the VM. + context.handle.lock().await.take(); + close_failure = Some(error.to_string()); + } let resource = context.resource; Ok(HostFutureOutput::complete(move |vm| { let progress = vm @@ -800,7 +895,10 @@ pub(crate) async fn builtin_io_close( "io_close scope retirement is still pending".to_string(), )); } - Ok(true) + Ok(match close_failure { + Some(message) => GuestResult::Err(message), + None => GuestResult::Ok(()), + }) })) } @@ -913,7 +1011,10 @@ fn io_parse_handle(handle_id: i64) -> VmResult { .map_err(|error| VmError::HostError(format!("invalid io handle id {handle_id}: {error}"))) } -fn spawn_shell_command(shell_command: &str, mode: &str) -> VmResult { +/// Starts the shell for a `popen` handle. +/// +/// Failures are formatted for the guest error channel of [`builtin_io_popen`]. +fn spawn_shell_command(shell_command: &str, mode: &str) -> Result { let mut process = if cfg!(windows) { let mut command = Command::new("cmd"); command.arg("/C").arg(shell_command); @@ -936,16 +1037,16 @@ fn spawn_shell_command(shell_command: &str, mode: &str) -> VmResult { } let mut child = process .spawn() - .map_err(|error| VmError::HostError(format!("io_popen failed: {error}")))?; + .map_err(|error| super::io_failure("io_popen", error))?; if mode == "r" { let Some(stdout) = child.stdout.take() else { let cleanup = start_terminate_child_tree_for_drop(&mut child); - return Err(VmError::HostError(match cleanup { + return Err(match cleanup { Ok(()) => "io_popen('r') did not provide stdout pipe".to_string(), Err(error) => format!( "io_popen('r') did not provide stdout pipe; process cleanup failed: {error}" ), - })); + }); }; Ok(IoHandle::PopenRead { child, @@ -954,12 +1055,12 @@ fn spawn_shell_command(shell_command: &str, mode: &str) -> VmResult { } else { let Some(stdin) = child.stdin.take() else { let cleanup = start_terminate_child_tree_for_drop(&mut child); - return Err(VmError::HostError(match cleanup { + return Err(match cleanup { Ok(()) => "io_popen('w') did not provide stdin pipe".to_string(), Err(error) => format!( "io_popen('w') did not provide stdin pipe; process cleanup failed: {error}" ), - })); + }); }; Ok(IoHandle::PopenWrite { child, stdin }) } diff --git a/src/builtins/runtime/io/blocking.rs b/src/builtins/runtime/io/blocking.rs index 52ceed40..377eef8d 100644 --- a/src/builtins/runtime/io/blocking.rs +++ b/src/builtins/runtime/io/blocking.rs @@ -9,6 +9,7 @@ use crate::vm::resource::close::{CloseProgress, HostResource}; use crate::vm::resource::error::{ResourceError, ResourceErrorCode, ResourceResult}; use crate::vm::resource::{Resource, ResourceCloseReason, ResourceHandle}; use crate::vm::{Vm, VmError, VmResult}; +use crate::{GuestResult, ResourceOwned}; /// A file / child-process backed IO handle. pub(super) enum IoHandle { @@ -18,7 +19,7 @@ pub(super) enum IoHandle { } /// The typed resource stored in the execution scope for one IO handle. -struct IoResource { +pub(super) struct IoResource { handle: Option, explicit_cleanup: fn(&mut IoHandle) -> VmResult<()>, drop_cleanup: fn(&mut IoHandle) -> VmResult<()>, @@ -124,8 +125,15 @@ impl HostResource for IoResource { } /// Opens a file handle for runtime I/O inline on non-async builds. +/// +/// Only the `OpenOptions` failure is a guest error; an unsupported mode, a +/// policy denial and a scope-insertion failure stay fatal. #[pd_host_function(name = "io::open", contract = super::io_open_contract)] -pub(super) fn builtin_io_open(vm: &mut Vm, path: &str, mode: &str) -> VmResult { +pub(super) fn builtin_io_open( + vm: &mut Vm, + path: &str, + mode: &str, +) -> VmResult, String>> { let writes = match mode { "r" => false, "w" | "a" | "r+" | "w+" | "a+" => true, @@ -158,19 +166,24 @@ pub(super) fn builtin_io_open(vm: &mut Vm, path: &str, mode: &str) -> VmResult unreachable!("mode validated above"), } - let file = options - .open(path) - .map_err(|error| VmError::HostError(format!("io_open failed: {error}")))?; - let token = vm - .execution_scope() - .push_resource(IoResource::new(IoHandle::File(file))) - .map_err(|error| VmError::HostError(format!("io resource insert failed: {error}")))?; - Ok(token.into_handle().raw() as i64) + match options.open(path) { + Ok(file) => Ok(GuestResult::Ok(ResourceOwned::new(IoResource::new( + IoHandle::File(file), + )))), + Err(error) => Ok(GuestResult::Err(super::io_failure("io_open", error))), + } } /// Starts a child process and returns a process-backed handle. -#[pd_host_function(name = "io::popen")] -pub(super) fn builtin_io_popen(vm: &mut Vm, command: &str, mode: &str) -> VmResult { +/// +/// An unsupported mode and a disabled process capability stay fatal; a process +/// that cannot be started or wired up is a guest error. +#[pd_host_function(name = "io::popen", contract = super::io_popen_contract)] +pub(super) fn builtin_io_popen( + vm: &mut Vm, + command: &str, + mode: &str, +) -> VmResult, String>> { if mode != "r" && mode != "w" { return Err(VmError::HostError(format!( "unsupported io_popen mode '{mode}', expected r or w" @@ -184,17 +197,21 @@ pub(super) fn builtin_io_popen(vm: &mut Vm, command: &str, mode: &str) -> VmResu "io_popen requires the process capability".to_string(), )); } - let handle = spawn_shell_command(command, mode)?; - let token = vm - .execution_scope() - .push_resource(IoResource::new(handle)) - .map_err(|error| VmError::HostError(format!("io resource insert failed: {error}")))?; - Ok(token.into_handle().raw() as i64) + match spawn_shell_command(command, mode) { + Ok(handle) => Ok(GuestResult::Ok(ResourceOwned::new(IoResource::new(handle)))), + Err(message) => Ok(GuestResult::Err(message)), + } } /// Reads all remaining text from an I/O handle. +/// +/// A read failure is a guest error; an unusable handle kind and the read limit +/// stay fatal. #[pd_host_function(name = "io::read_all", contract = super::io_read_all_contract)] -pub(super) fn builtin_io_read_all(vm: &mut Vm, handle_id: i64) -> VmResult { +pub(super) fn builtin_io_read_all( + vm: &mut Vm, + handle_id: i64, +) -> VmResult> { let limit = super::io_policy(vm).map(|policy| policy.max_read_bytes); let token = io_resource_for_handle(vm, handle_id)?; let mut resource = vm @@ -207,7 +224,7 @@ pub(super) fn builtin_io_read_all(vm: &mut Vm, handle_id: i64) -> VmResult file.read_to_string(&mut out), IoHandle::PopenRead { child } => child .stdout @@ -221,19 +238,28 @@ pub(super) fn builtin_io_read_all(vm: &mut Vm, handle_id: i64) -> VmResult limit) { return Err(VmError::HostError( "io_read_all exceeded read limit".to_string(), )); } - Ok(out) + Ok(GuestResult::Ok(out)) } /// Reads a single line of text from an I/O handle. -#[pd_host_function(name = "io::read_line")] -pub(super) fn builtin_io_read_line(vm: &mut Vm, handle_id: i64) -> VmResult { +/// +/// End of file is `Ok(None)` and an empty line is `Ok(Some(""))`: the returned +/// line has its single trailing `\n` removed. A read failure is a guest error; +/// an unusable handle kind and the read limit stay fatal. +#[pd_host_function(name = "io::read_line", contract = super::io_read_line_contract)] +pub(super) fn builtin_io_read_line( + vm: &mut Vm, + handle_id: i64, +) -> VmResult, String>> { let limit = super::io_policy(vm).map(|policy| policy.max_read_bytes); let token = io_resource_for_handle(vm, handle_id)?; let mut resource = vm @@ -246,11 +272,11 @@ pub(super) fn builtin_io_read_line(vm: &mut Vm, handle_id: i64) -> VmResult read_line_from_reader(file)?, + IoHandle::File(file) => read_line_from_reader(file), IoHandle::PopenRead { child } => { read_line_from_reader(child.stdout.as_mut().ok_or_else(|| { VmError::HostError("io_read_line popen handle missing stdout".to_string()) - })?)? + })?) } IoHandle::PopenWrite { .. } => { return Err(VmError::HostError( @@ -258,17 +284,31 @@ pub(super) fn builtin_io_read_line(vm: &mut Vm, handle_id: i64) -> VmResult line, + Err(error) => return Ok(GuestResult::Err(super::io_failure("io_read_line", error))), + }; + let Some(line) = line else { + return Ok(GuestResult::Ok(crate::GuestOption::None)); + }; if limit.is_some_and(|limit| line.len() > limit) { return Err(VmError::HostError( "io_read_line exceeded read limit".to_string(), )); } - Ok(line) + Ok(GuestResult::Ok(crate::GuestOption::Some(line))) } /// Writes text to an I/O handle. -#[pd_host_function(name = "io::write")] -pub(super) fn builtin_io_write(vm: &mut Vm, handle_id: i64, text: &str) -> VmResult { +/// +/// A write failure is a guest error; an unusable handle kind and the write +/// limit stay fatal. +#[pd_host_function(name = "io::write", contract = super::io_write_contract)] +pub(super) fn builtin_io_write( + vm: &mut Vm, + handle_id: i64, + text: &str, +) -> VmResult> { if super::io_policy(vm) .as_ref() .is_some_and(|policy| text.len() > policy.max_write_bytes) @@ -299,14 +339,18 @@ pub(super) fn builtin_io_write(vm: &mut Vm, handle_id: i64, text: &str) -> VmRes "io_write requires a writable handle".to_string(), )); } + }; + match written { + Ok(written) => Ok(GuestResult::Ok(written as i64)), + Err(error) => Ok(GuestResult::Err(super::io_failure("io_write", error))), } - .map_err(|error| VmError::HostError(format!("io_write failed: {error}")))?; - Ok(written as i64) } /// Flushes buffered output for an I/O handle. -#[pd_host_function(name = "io::flush")] -pub(super) fn builtin_io_flush(vm: &mut Vm, handle_id: i64) -> VmResult { +/// +/// A flush failure is a guest error; an unusable handle kind stays fatal. +#[pd_host_function(name = "io::flush", contract = super::io_flush_contract)] +pub(super) fn builtin_io_flush(vm: &mut Vm, handle_id: i64) -> VmResult> { let token = io_resource_for_handle(vm, handle_id)?; let mut resource = vm .execution_scope() @@ -317,7 +361,7 @@ pub(super) fn builtin_io_flush(vm: &mut Vm, handle_id: i64) -> VmResult { .handle .as_mut() .ok_or_else(|| VmError::HostError("io handle is closed".to_string()))?; - match handle { + let flushed = match handle { IoHandle::File(file) => file.flush(), IoHandle::PopenWrite { child } => child .stdin @@ -325,16 +369,23 @@ pub(super) fn builtin_io_flush(vm: &mut Vm, handle_id: i64) -> VmResult { .ok_or_else(|| VmError::HostError("io_flush popen handle missing stdin".to_string()))? .flush(), IoHandle::PopenRead { .. } => Ok(()), + }; + match flushed { + Ok(()) => Ok(GuestResult::Ok(())), + Err(error) => Ok(GuestResult::Err(super::io_failure("io_flush", error))), } - .map_err(|error| VmError::HostError(format!("io_flush failed: {error}")))?; - Ok(true) } /// Closes an I/O handle. +/// +/// A cleanup (flush or process termination) failure is a guest error and still +/// retires the scope resource; an already-closed handle and a pending scope +/// retirement stay fatal. #[pd_host_function(name = "io::close", contract = super::io_close_contract)] -pub(super) fn builtin_io_close(vm: &mut Vm, handle_id: i64) -> VmResult { +pub(super) fn builtin_io_close(vm: &mut Vm, handle_id: i64) -> VmResult> { let token = io_resource_for_handle(vm, handle_id)?; let handle = token.handle(); + let mut close_failure = None; { let mut resource = vm .execution_scope() @@ -344,7 +395,16 @@ pub(super) fn builtin_io_close(vm: &mut Vm, handle_id: i64) -> VmResult { if resource.handle.is_none() { return Err(VmError::HostError("io handle is closed".to_string())); } - resource.close_explicit()?; + if let Err(error) = resource.close_explicit() { + // The handle survives a failed explicit close (a failing flush, a + // process that will not terminate). Fall back to the drop path so + // the process tree is still signalled, detach the handle so the + // scope retirement can complete, and report the failure to the + // guest instead of aborting the VM. + let _ = resource.begin_close_for_drop_nonblocking(); + resource.handle.take(); + close_failure = Some(error.to_string()); + } } let progress = vm .execution_scope() @@ -357,7 +417,10 @@ pub(super) fn builtin_io_close(vm: &mut Vm, handle_id: i64) -> VmResult { "io_close scope retirement is still pending".to_string(), )); } - Ok(true) + match close_failure { + Some(message) => Ok(GuestResult::Err(message)), + None => Ok(GuestResult::Ok(())), + } } /// Returns whether a file system path exists. @@ -440,7 +503,12 @@ fn canonicalize_blocking_target(path: &Path) -> VmResult { Ok(canonical_parent.join(name)) } -fn spawn_shell_command(command: &str, mode: &str) -> VmResult { +/// Starts the shell for a `popen` handle. +/// +/// Failures are formatted for the guest error channel of [`builtin_io_popen`]: +/// a process that cannot start, or that cannot be wired to the requested pipe, +/// is an environment outcome the script can report, not a VM fault. +fn spawn_shell_command(command: &str, mode: &str) -> Result { let mut process = if cfg!(windows) { let mut shell = Command::new("cmd"); shell.arg("/C").arg(command); @@ -466,27 +534,27 @@ fn spawn_shell_command(command: &str, mode: &str) -> VmResult { } let mut child = process .spawn() - .map_err(|error| VmError::HostError(format!("io_popen failed: {error}")))?; + .map_err(|error| super::io_failure("io_popen", error))?; match mode { "r" if child.stdout.is_some() => Ok(IoHandle::PopenRead { child }), "w" if child.stdin.is_some() => Ok(IoHandle::PopenWrite { child }), "r" => { let cleanup = terminate_child_tree(&mut child); - Err(VmError::HostError(match cleanup { + Err(match cleanup { Ok(()) => "io_popen('r') did not provide stdout pipe".to_string(), Err(error) => format!( "io_popen('r') did not provide stdout pipe; process cleanup failed: {error}" ), - })) + }) } "w" => { let cleanup = terminate_child_tree(&mut child); - Err(VmError::HostError(match cleanup { + Err(match cleanup { Ok(()) => "io_popen('w') did not provide stdin pipe".to_string(), Err(error) => format!( "io_popen('w') did not provide stdin pipe; process cleanup failed: {error}" ), - })) + }) } _ => unreachable!("mode validated above"), } @@ -665,13 +733,16 @@ where } } -fn read_line_from_reader(reader: &mut impl Read) -> VmResult { +/// Reads one line, without its single trailing `\n`. +/// +/// `Ok(None)` is end of file; `Ok(Some(""))` is a real empty line. A read +/// failure is returned as the raw [`std::io::Error`] so the caller decides +/// whether it is a guest error or a VM fault. +fn read_line_from_reader(reader: &mut impl Read) -> io::Result> { let mut bytes = Vec::new(); let mut one = [0u8; 1]; loop { - let read = reader - .read(&mut one) - .map_err(|error| VmError::HostError(format!("io_read_line failed: {error}")))?; + let read = reader.read(&mut one)?; if read == 0 { break; } @@ -680,7 +751,13 @@ fn read_line_from_reader(reader: &mut impl Read) -> VmResult { break; } } - Ok(String::from_utf8_lossy(&bytes).into_owned()) + if bytes.is_empty() { + return Ok(None); + } + if bytes.last() == Some(&b'\n') { + bytes.pop(); + } + Ok(Some(String::from_utf8_lossy(&bytes).into_owned())) } #[cfg(test)] @@ -797,7 +874,7 @@ mod tests { } #[test] - fn failed_builtin_close_preserves_process_resource_for_retry() { + fn failed_builtin_close_reports_a_guest_error_and_still_retires() { let _guard = PROCESS_CLEANUP_TEST_LOCK.lock().expect("test lock"); DROP_CLEANUP_CALLS.store(0, Ordering::SeqCst); EXPLICIT_CLEANUP_CALLS.store(0, Ordering::SeqCst); @@ -817,41 +894,29 @@ mod tests { let raw = handle.raw() as i64; let args = [crate::vm::Value::Int(raw)]; - let error = builtin_io_close(&mut vm, &args).expect_err("cleanup failure must propagate"); + let outcome = builtin_io_close(&mut vm, &args) + .expect("a cleanup failure is a guest outcome, not a VM fault"); + let (ok, payload) = + crate::result::payload(&outcome).expect("close must return a Result carrier"); + assert!(!ok, "a cleanup failure must not report success"); + let crate::vm::Value::String(message) = payload else { + panic!("close must report a string error, got {payload:?}"); + }; assert!( - error - .to_string() - .contains("injected explicit cleanup failure") + message.contains("injected explicit cleanup failure"), + "unexpected guest error: {message}" ); - let recovered = vm - .execution_scope() - .resources() - .typed::(handle) - .expect("failed close must leave the resource live"); - assert!( - vm.execution_scope() - .resources() - .get(&recovered) - .expect("resource borrow") - .handle - .is_some() - ); - vm.execution_scope() - .resources_mut() - .get_mut(&recovered) - .expect("resource borrow") - .explicit_cleanup = record_explicit_cleanup; - - assert!(builtin_io_close(&mut vm, &args).expect("retry should close the resource")); assert!( vm.execution_scope() .resources() .typed::(handle) .is_err(), - "successful retry must retire the resource" + "a reported cleanup failure must still retire the scope resource" ); - assert_eq!(EXPLICIT_CLEANUP_CALLS.load(Ordering::SeqCst), 1); - assert_eq!(DROP_CLEANUP_CALLS.load(Ordering::SeqCst), 0); + // The failed explicit close falls back to the drop path, which is the + // only cleanup that can still run for the abandoned handle. + assert_eq!(DROP_CLEANUP_CALLS.load(Ordering::SeqCst), 1); + assert_eq!(EXPLICIT_CLEANUP_CALLS.load(Ordering::SeqCst), 0); } #[cfg(windows)] diff --git a/src/builtins/runtime/io/mod.rs b/src/builtins/runtime/io/mod.rs index 66ca2bf4..db92c70e 100644 --- a/src/builtins/runtime/io/mod.rs +++ b/src/builtins/runtime/io/mod.rs @@ -134,10 +134,34 @@ fn io_file_key() -> ResourceTypeKey { io_file_resource().schema.key } +/// The guest contract of a fallible IO operation: the success payload, or the +/// formatted OS error message. +/// +/// Only ordinary file-system read/write/open failures travel through this +/// channel. Invalid or closed handles, resource borrow/ownership/scope +/// failures, policy denials, read/write limits, unsupported modes and +/// wasm capability rejections stay fatal [`VmError`](crate::vm::VmError)s: they +/// are programming or configuration errors, not recoverable IO outcomes. +fn io_result(ok: HostTypeSchema) -> HostTypeSchema { + HostTypeSchema::Result { + ok: Box::new(ok), + err: Box::new(HostTypeSchema::String), + } +} + +/// Formats a recoverable IO failure, keeping the operating-system text. +/// +/// Every backend reports through this single formatter, so the guest sees one +/// shape of message regardless of the target. +#[cfg(not(target_family = "wasm"))] +fn io_failure(operation: &str, error: impl std::fmt::Display) -> String { + format!("{operation} failed: {error}") +} + /// Guest contract for `io::open`. /// -/// The runtime signature carries the raw scope-token `i64` for the opened -/// handle; the guest contract is the typed `io.file` resource it denotes. +/// The runtime signature carries the opened handle as an owned `io.file` +/// resource; a failure is the formatted OS error. fn io_open_contract() -> HostFunctionSchema { HostFunctionSchema::with_return( "io::open", @@ -145,7 +169,19 @@ fn io_open_contract() -> HostFunctionSchema { HostParamSchema::value("path", HostTypeSchema::String), HostParamSchema::value("mode", HostTypeSchema::String), ], - HostTypeSchema::Resource(io_file_key()), + io_result(HostTypeSchema::Resource(io_file_key())), + ) +} + +/// Guest contract for `io::popen`. +fn io_popen_contract() -> HostFunctionSchema { + HostFunctionSchema::with_return( + "io::popen", + vec![ + HostParamSchema::value("command", HostTypeSchema::String), + HostParamSchema::value("mode", HostTypeSchema::String), + ], + io_result(HostTypeSchema::Resource(io_file_key())), ) } @@ -158,7 +194,53 @@ fn io_read_all_contract() -> HostFunctionSchema { HostTypeSchema::Resource(io_file_key()), HostParamPassing::Borrow, )], - HostTypeSchema::String, + io_result(HostTypeSchema::String), + ) +} + +/// Guest contract for `io::read_line`. +/// +/// End of file is `Ok(None)`; a present but empty line is `Ok(Some(""))`. +fn io_read_line_contract() -> HostFunctionSchema { + HostFunctionSchema::with_return( + "io::read_line", + vec![HostParamSchema::with_passing( + "handle", + HostTypeSchema::Resource(io_file_key()), + HostParamPassing::Borrow, + )], + io_result(HostTypeSchema::Option(Box::new(HostTypeSchema::String))), + ) +} + +/// Guest contract for `io::write`. +/// +/// The success payload is the number of bytes actually written. +fn io_write_contract() -> HostFunctionSchema { + HostFunctionSchema::with_return( + "io::write", + vec![ + HostParamSchema::with_passing( + "handle", + HostTypeSchema::Resource(io_file_key()), + HostParamPassing::Borrow, + ), + HostParamSchema::value("text", HostTypeSchema::String), + ], + io_result(HostTypeSchema::Int), + ) +} + +/// Guest contract for `io::flush`. +fn io_flush_contract() -> HostFunctionSchema { + HostFunctionSchema::with_return( + "io::flush", + vec![HostParamSchema::with_passing( + "handle", + HostTypeSchema::Resource(io_file_key()), + HostParamPassing::Borrow, + )], + io_result(HostTypeSchema::Unit), ) } @@ -171,7 +253,7 @@ fn io_close_contract() -> HostFunctionSchema { HostTypeSchema::Resource(io_file_key()), HostParamPassing::TakeOwned, )], - HostTypeSchema::Bool, + io_result(HostTypeSchema::Unit), ) } diff --git a/src/builtins/runtime/io_wasm.rs b/src/builtins/runtime/io_wasm.rs index 9194fd83..83a95b87 100644 --- a/src/builtins/runtime/io_wasm.rs +++ b/src/builtins/runtime/io_wasm.rs @@ -5,10 +5,20 @@ //! only supplies the adapter implementations for a target without a file //! system. Every entry point fails closed with a host error, so the guest //! surface and the compiled contracts stay identical to the native backends. +//! +//! Every call declares its guest contract explicitly, so the guest-visible +//! `Result` is the same on this target. The compiled signature keeps the raw +//! physical carrier (a scope token, text, a Boolean) because no value is ever +//! produced here — a capability rejection is a fatal host error, never a guest +//! `Err` branch. use pd_host_function::pd_host_function; -use super::{HostCallResult, IO_FILE_DESCRIPTION, IO_FILE_KEY}; +use super::{ + HostCallResult, IO_FILE_DESCRIPTION, IO_FILE_KEY, io_close_contract, io_flush_contract, + io_open_contract, io_popen_contract, io_read_all_contract, io_read_line_contract, + io_write_contract, +}; use crate::vm::{Vm, VmError, VmResult}; /// The wasm32 IO backend keeps no scope resource, but the guest-visible @@ -29,7 +39,7 @@ pub(crate) fn io_file_resource() -> crate::host_extension::HostResourceTypeMeta } /// Opens a file handle for runtime I/O. -#[pd_host_function(name = "io::open", contract = super::io_open_contract)] +#[pd_host_function(name = "io::open", contract = io_open_contract)] pub(super) fn builtin_io_open( _vm: &mut Vm, _path: &str, @@ -41,7 +51,7 @@ pub(super) fn builtin_io_open( } /// Starts a child process and returns a process-backed handle. -#[pd_host_function(name = "io::popen")] +#[pd_host_function(name = "io::popen", contract = io_popen_contract)] pub(super) fn builtin_io_popen( _vm: &mut Vm, _command: &str, @@ -53,7 +63,7 @@ pub(super) fn builtin_io_popen( } /// Reads all remaining text from an I/O handle. -#[pd_host_function(name = "io::read_all", contract = super::io_read_all_contract)] +#[pd_host_function(name = "io::read_all", contract = io_read_all_contract)] pub(super) fn builtin_io_read_all( _vm: &mut Vm, _handle_id: i64, @@ -64,7 +74,7 @@ pub(super) fn builtin_io_read_all( } /// Reads a single line of text from an I/O handle. -#[pd_host_function(name = "io::read_line")] +#[pd_host_function(name = "io::read_line", contract = io_read_line_contract)] pub(super) fn builtin_io_read_line( _vm: &mut Vm, _handle_id: i64, @@ -75,7 +85,7 @@ pub(super) fn builtin_io_read_line( } /// Writes text to an I/O handle. -#[pd_host_function(name = "io::write")] +#[pd_host_function(name = "io::write", contract = io_write_contract)] pub(super) fn builtin_io_write( _vm: &mut Vm, _handle_id: i64, @@ -87,7 +97,7 @@ pub(super) fn builtin_io_write( } /// Flushes buffered output for an I/O handle. -#[pd_host_function(name = "io::flush")] +#[pd_host_function(name = "io::flush", contract = io_flush_contract)] pub(super) fn builtin_io_flush(_vm: &mut Vm, _handle_id: i64) -> VmResult> { Err(VmError::HostError( "io::flush is unsupported on wasm32 runtime".to_string(), @@ -95,7 +105,7 @@ pub(super) fn builtin_io_flush(_vm: &mut Vm, _handle_id: i64) -> VmResult VmResult> { Err(VmError::HostError( "io::close is unsupported on wasm32 runtime".to_string(), diff --git a/stdlib/rss/io.rss b/stdlib/rss/io.rss index 3f6ceda7..98ec3fcc 100644 --- a/stdlib/rss/io.rss +++ b/stdlib/rss/io.rss @@ -1,35 +1,40 @@ // I/O wrappers implemented in pure RustScript. +// +// Every wrapper reports the recoverable IO failure of the host `io` module to +// its caller. A close or flush failure is part of that contract: it is +// propagated instead of being swallowed, because a silently dropped buffer is +// data loss the caller cannot observe. use io; // Reads an entire file into a string. -pub fn read_text(path: string) -> string { - let handle = io::open(path, "r"); - let out = io::read_all(handle); - let read_text_closed = io::close(handle); - out +pub fn read_text(path: string) -> Result { + let handle = io::open(path, "r")?; + let text = io::read_all(handle)?; + io::close(handle)?; + Result::Ok(text) } // Writes text to a file, replacing any existing contents. -pub fn write_text(path: string, text: string) -> int { - let handle = io::open(path, "w"); - let written = io::write(handle, text); - let write_text_flushed = io::flush(handle); - let write_text_closed = io::close(handle); - written +pub fn write_text(path: string, text: string) -> Result { + let handle = io::open(path, "w")?; + let written = io::write(handle, text)?; + io::flush(handle)?; + io::close(handle)?; + Result::Ok(written) } // Appends text to the end of a file. -pub fn append_text(path: string, text: string) -> int { - let handle = io::open(path, "a"); - let written = io::write(handle, text); - let append_text_flushed = io::flush(handle); - let append_text_closed = io::close(handle); - written +pub fn append_text(path: string, text: string) -> Result { + let handle = io::open(path, "a")?; + let written = io::write(handle, text)?; + io::flush(handle)?; + io::close(handle)?; + Result::Ok(written) } // Reads a file and splits it into newline-delimited lines. -pub fn read_lines(path: string) -> [string] { - let text = read_text(path); +pub fn read_lines(path: string) -> Result<[string], string> { + let text = read_text(path)?; let mut lines: [string] = []; let text_len =(&text).length; let mut start = 0; @@ -42,5 +47,5 @@ pub fn read_lines(path: string) -> [string] { if start < text_len { lines[lines.length] =(&text)[start:text_len]; } - lines + Result::Ok(lines) } diff --git a/stdlib/tests/io.rss b/stdlib/tests/io.rss index 8d9bab5c..20865d68 100644 --- a/stdlib/tests/io.rss +++ b/stdlib/tests/io.rss @@ -5,10 +5,22 @@ use io; let mut fixture_path = "stdlib/rss/strings.rss"; assert(io::exists(fixture_path)); -let mut text = file_io::read_text(fixture_path); -assert(string::contains(text, "pub fn contains")); -assert(string::contains(text, "pub fn trim")); +// The wrappers surface IO failure instead of returning an empty string: a +// missing file is `Err`, and a real read is `Ok` with the file contents. +let mut text_ok = match file_io::read_text(fixture_path) { + Result::Ok(text) => string::contains(text, "pub fn contains") && string::contains(text, "pub fn trim"), + Result::Err(message) => false, +}; +assert(text_ok); -let mut lines = file_io::read_lines(fixture_path); -assert(lines.length > 10); -assert(string::contains(lines[0], "String helpers")); +let mut missing_is_err = match file_io::read_text("stdlib/rss/__missing_fixture__.rss") { + Result::Ok(text) => false, + Result::Err(message) => message.length > 0, +}; +assert(missing_is_err); + +let mut lines_ok = match file_io::read_lines(fixture_path) { + Result::Ok(lines) => lines.length > 10 && string::contains(lines[0], "String helpers"), + Result::Err(message) => false, +}; +assert(lines_ok); diff --git a/stdlib/tests/io_primitives.rss b/stdlib/tests/io_primitives.rss index ee6bd99f..ed7bc026 100644 --- a/stdlib/tests/io_primitives.rss +++ b/stdlib/tests/io_primitives.rss @@ -3,8 +3,17 @@ use io; assert(io::exists("stdlib/rss/strings.rss")); -let mut handle = io::popen("echo rustscript_io_builtin", "r"); -let mut output = io::read_all(handle); -let mut closed = io::close(handle); -assert(closed); -assert(string::contains(output, "rustscript_io_builtin")); +// Runs a command, reads every byte it prints, and closes the handle, so a +// failure at any step reaches the caller instead of an empty string. +fn read_command_output(command: string) -> Result { + let handle = io::popen(command, "r")?; + let output = io::read_all(handle)?; + io::close(handle)?; + Result::Ok(output) +} + +let mut popen_ok = match read_command_output("echo rustscript_io_builtin") { + Result::Ok(output) => string::contains(output, "rustscript_io_builtin"), + Result::Err(message) => false, +}; +assert(popen_ok); diff --git a/tests/builtins/io_async_tests.rs b/tests/builtins/io_async_tests.rs index baff78c2..2b03b75b 100644 --- a/tests/builtins/io_async_tests.rs +++ b/tests/builtins/io_async_tests.rs @@ -106,14 +106,19 @@ fn async_io_round_trips_file_operations_through_host_driver() { let stack = run_source(&format!( r#" - let handle = io::open("{}", "w"); - io::write(handle, "host-driven"); - io::flush(handle); - io::close(handle); - io::exists("{}"); + fn round_trip() -> Result {{ + let handle = io::open("{path}", "w")?; + io::write(handle, "host-driven")?; + io::flush(handle)?; + io::close(handle)?; + Result::Ok(io::exists("{path}")) + }} + match round_trip() {{ + Result::Ok(value) => value, + Result::Err(message) => false, + }}; "#, - path.display(), - path.display(), + path = path.display(), )) .expect("async io program should complete"); @@ -139,17 +144,35 @@ fn async_io_read_line_preserves_buffered_data_between_calls() { let stack = run_source(&format!( r#" - let handle = io::open("{}", "r"); - io::read_line(handle); - let second = io::read_line(handle); - io::close(handle); - second; + fn read_two_lines() -> Result {{ + let handle = io::open("{path}", "r")?; + let first = io::read_line(handle)?; + let second = io::read_line(handle)?; + io::close(handle)?; + let line = match second {{ + Option::Some(text) => text, + Option::None => "", + }}; + let first_line = match first {{ + Option::Some(text) => text, + Option::None => "missing", + }}; + Result::Ok(line + first_line) + }} + match read_two_lines() {{ + Result::Ok(line) => line, + Result::Err(message) => message, + }}; "#, - path.display(), + path = path.display(), )) .expect("async read_line program should complete"); - assert_eq!(stack.last(), Some(&Value::string("second\n"))); + assert_eq!( + stack.last(), + Some(&Value::string("secondfirst")), + "read_line must strip the terminator and preserve buffered data" + ); let _ = std::fs::remove_file(path); } @@ -158,10 +181,16 @@ fn async_io_read_line_preserves_buffered_data_between_calls() { fn async_io_popen_reads_through_tokio_process_pipe() { let stack = run_source( r#" - let handle = io::popen("printf async-process", "r"); - let output = io::read_all(handle); - io::close(handle); - output; + fn read_output() -> Result { + let handle = io::popen("printf async-process", "r")?; + let output = io::read_all(handle)?; + io::close(handle)?; + Result::Ok(output) + } + match read_output() { + Result::Ok(output) => output, + Result::Err(message) => message, + }; "#, ) .expect("async popen program should complete"); @@ -253,9 +282,32 @@ fn process_tree_command( ) } +/// A guest program that opens a `popen` handle and then either reads it +/// (`read`) or just keeps the process resource alive (`hold`). #[cfg(unix)] -fn guest_popen_program(command: &str, expression: &str) -> String { - format!(r#"let h = io::popen("{command}", "r"); {expression}"#) +fn guest_popen_program(command: &str, read: bool) -> String { + if read { + format!( + r#" + fn drive() -> Result {{ + let handle = io::popen("{command}", "r")?; + let output = io::read_all(handle)?; + Result::Ok(output) + }} + drive(); + "# + ) + } else { + format!( + r#" + fn drive() -> Result {{ + let handle = io::popen("{command}", "r")?; + Result::Ok(true) + }} + drive(); + "# + ) + } } #[cfg(target_os = "linux")] @@ -273,7 +325,7 @@ fn async_io_reset_kills_and_reaps_the_entire_popen_process_group() { let descendant_path = base.with_extension("descendant"); let marker_path = base.with_extension("marker"); let command = process_tree_command(&parent_path, &descendant_path, &marker_path); - let source = guest_popen_program(&command, "io::read_all(h);"); + let source = guest_popen_program(&command, true); let compiled = compile_source(&format!("use io;\n{source}")).expect("source should compile"); let mut vm = Vm::new(compiled.program); @@ -373,7 +425,7 @@ fn async_io_vm_drop_terminates_live_popen_process_tree() { let descendant_path = base.with_extension("descendant"); let marker_path = base.with_extension("marker"); let command = process_tree_command(&parent_path, &descendant_path, &marker_path); - let source = guest_popen_program(&command, "h;"); + let source = guest_popen_program(&command, false); let compiled = compile_source(&format!("use io;\n{source}")).expect("source should compile"); let mut vm = Vm::new(compiled.program); @@ -438,7 +490,7 @@ fn async_io_failed_resource_handoff_cleans_up_the_popen_process_group() { let descendant_path = base.with_extension("descendant"); let marker_path = base.with_extension("marker"); let command = process_tree_command(&parent_path, &descendant_path, &marker_path); - let source = guest_popen_program(&command, "h;"); + let source = guest_popen_program(&command, false); let compiled = compile_source(&format!("use io;\n{source}")).expect("source should compile"); let mut vm = Vm::new(compiled.program); @@ -470,3 +522,80 @@ fn async_io_failed_resource_handoff_cleans_up_the_popen_process_group() { let _ = std::fs::remove_file(descendant_path); let _ = std::fs::remove_file(marker_path); } + +#[test] +fn async_io_read_line_at_eof_is_ok_none() { + let nonce = SystemTime::now() + .duration_since(UNIX_EPOCH) + .expect("clock should follow Unix epoch") + .as_nanos(); + let path = std::env::temp_dir().join(format!( + "pd-vm-async-read-line-eof-{}-{nonce}", + std::process::id() + )); + std::fs::write(&path, "").expect("fixture should be written"); + + let stack = run_source(&format!( + r#" + fn probe() -> Result {{ + let handle = io::open("{path}", "r")?; + let line = io::read_line(handle)?; + io::close(handle)?; + Result::Ok(match line {{ + Option::Some(_) => false, + Option::None => true, + }}) + }} + match probe() {{ + Result::Ok(value) => value, + Result::Err(message) => false, + }}; + "#, + path = path.display() + )) + .expect("async EOF must be a guest outcome"); + + assert_eq!( + stack.last(), + Some(&Value::Bool(true)), + "async end of file must be Ok(None)" + ); + let _ = std::fs::remove_file(path); +} + +#[test] +fn async_io_write_reports_bytes_and_close_reports_unit() { + let nonce = SystemTime::now() + .duration_since(UNIX_EPOCH) + .expect("clock should follow Unix epoch") + .as_nanos(); + let path = std::env::temp_dir().join(format!( + "pd-vm-async-write-count-{}-{nonce}", + std::process::id() + )); + + let stack = run_source(&format!( + r#" + fn probe() -> Result {{ + let handle = io::open("{path}", "w")?; + let written = io::write(handle, "abcde")?; + io::flush(handle)?; + io::close(handle)?; + Result::Ok(written == 5) + }} + match probe() {{ + Result::Ok(value) => value, + Result::Err(message) => false, + }}; + "#, + path = path.display() + )) + .expect("async write must report its byte count"); + + assert_eq!(stack.last(), Some(&Value::Bool(true))); + assert_eq!( + std::fs::read_to_string(&path).expect("the written file must exist"), + "abcde" + ); + let _ = std::fs::remove_file(path); +} diff --git a/tests/builtins/io_builtin_edge_tests.rs b/tests/builtins/io_builtin_edge_tests.rs index 90309cc3..0d013740 100644 --- a/tests/builtins/io_builtin_edge_tests.rs +++ b/tests/builtins/io_builtin_edge_tests.rs @@ -67,15 +67,22 @@ fn io_open_rejects_unsupported_mode() { } #[test] -fn io_open_read_mode_reports_missing_file() { - let err = run_source_host_error( +fn io_open_missing_file_is_a_guest_error() { + let stack = run_source( r#" - io::open("__pd_vm_missing_file_for_test__.txt", "r"); + match io::open("__pd_vm_missing_file_for_test__.txt", "r") { + Result::Ok(handle) => "", + Result::Err(message) => message, + }; "#, - ); + ) + .expect("a missing file must not abort the VM"); + let Some(Value::String(message)) = stack.last() else { + panic!("a missing file must report a guest Err string, got {stack:?}"); + }; assert!( - err.contains("io_open failed"), - "unexpected error message: {err}" + message.contains("io_open failed"), + "the guest error must keep the operating-system text: {message}" ); } @@ -96,8 +103,12 @@ fn io_popen_rejects_invalid_mode() { fn io_read_all_rejects_write_only_popen_handle() { let err = run_source_host_error( r#" - let handle = io::popen("echo hello", "w"); - io::read_all(handle); + fn probe() -> Result { + let handle = io::popen("echo hello", "w")?; + let text = io::read_all(handle)?; + Result::Ok(text.length) + } + probe(); "#, ); assert!( @@ -110,8 +121,12 @@ fn io_read_all_rejects_write_only_popen_handle() { fn io_write_rejects_read_only_popen_handle() { let err = run_source_host_error( r#" - let handle = io::popen("echo hello", "r"); - io::write(handle, "payload"); + fn probe() -> Result { + let handle = io::popen("echo hello", "r")?; + let written = io::write(handle, "payload")?; + Result::Ok(written) + } + probe(); "#, ); assert!( @@ -134,15 +149,27 @@ fn io_close_rejects_non_positive_handle_id() { } #[test] -fn io_flush_on_read_handle_is_a_noop_true() { +fn io_flush_on_read_handle_is_a_noop_unit_result() { let stack = run_source( r#" - let handle = io::popen("echo hello", "r"); - io::flush(handle); + fn flush_read_handle() -> Result { + let handle = io::popen("echo hello", "r")?; + let flushed = io::flush(handle)?; + io::close(handle)?; + Result::Ok(true) + } + match flush_read_handle() { + Result::Ok(value) => value, + Result::Err(message) => false, + }; "#, ) .expect("program should execute"); - assert_eq!(stack.last(), Some(&Value::Bool(true))); + assert_eq!( + stack.last(), + Some(&Value::Bool(true)), + "flushing a read-only handle stays a successful command" + ); } #[cfg(unix)] @@ -235,8 +262,12 @@ fn io_policy_limits_write_size() { let compiled = compile_source(&format!( r#" use io; - let handle = io::open("{}", "w"); - io::write(handle, "four"); + fn probe() -> Result {{ + let handle = io::open("{}", "w")?; + let written = io::write(handle, "four")?; + Result::Ok(written) + }} + probe(); "#, path.display() )) @@ -264,3 +295,179 @@ fn io_policy_limits_write_size() { assert!(matches!(error, VmError::HostError(message) if message.contains("write limit"))); let _ = std::fs::remove_file(path); } + +/// A unique scratch file for one test run, written with `contents`. +fn scratch_fixture(label: &str, contents: &str) -> std::path::PathBuf { + let path = std::env::temp_dir().join(format!( + "pd-vm-io-{label}-{}-{:?}", + std::process::id(), + std::time::SystemTime::now() + .duration_since(std::time::UNIX_EPOCH) + .expect("clock should follow Unix epoch") + .as_nanos() + )); + std::fs::write(&path, contents).expect("fixture should be writable"); + path +} + +#[test] +fn io_read_line_at_eof_is_ok_none() { + let path = scratch_fixture("eof", ""); + let stack = run_source(&format!( + r#" + fn probe() -> Result {{ + let handle = io::open("{path}", "r")?; + let line = io::read_line(handle)?; + io::close(handle)?; + Result::Ok(match line {{ + Option::Some(_) => false, + Option::None => true, + }}) + }} + match probe() {{ + Result::Ok(value) => value, + Result::Err(message) => false, + }}; + "#, + path = path.display() + )) + .expect("EOF must be a guest outcome, not a host error"); + assert_eq!( + stack.last(), + Some(&Value::Bool(true)), + "end of file must be Ok(None)" + ); + let _ = std::fs::remove_file(path); +} + +#[test] +fn io_read_line_reports_an_empty_line_as_ok_some_empty() { + let path = scratch_fixture("empty-line", "\nsecond\n"); + let stack = run_source(&format!( + r#" + fn probe() -> Result {{ + let handle = io::open("{path}", "r")?; + let first = io::read_line(handle)?; + let second = io::read_line(handle)?; + let third = io::read_line(handle)?; + io::close(handle)?; + let empty_line = match first {{ + Option::Some(line) => line.length == 0, + Option::None => false, + }}; + let content = match second {{ + Option::Some(line) => line == "second", + Option::None => false, + }}; + let eof = match third {{ + Option::Some(_) => false, + Option::None => true, + }}; + Result::Ok(empty_line && content && eof) + }} + match probe() {{ + Result::Ok(value) => value, + Result::Err(message) => false, + }}; + "#, + path = path.display() + )) + .expect("empty lines must be a guest outcome"); + assert_eq!( + stack.last(), + Some(&Value::Bool(true)), + "a real empty line must be Ok(Some(\"\")) and the terminator must not leak" + ); + let _ = std::fs::remove_file(path); +} + +#[test] +fn io_read_all_on_an_empty_file_is_ok_empty_string() { + let path = scratch_fixture("empty-read", ""); + let stack = run_source(&format!( + r#" + fn probe() -> Result {{ + let handle = io::open("{path}", "r")?; + let text = io::read_all(handle)?; + io::close(handle)?; + Result::Ok(text == "") + }} + match probe() {{ + Result::Ok(value) => value, + Result::Err(message) => false, + }}; + "#, + path = path.display() + )) + .expect("an empty file must read as an empty string"); + assert_eq!(stack.last(), Some(&Value::Bool(true))); + let _ = std::fs::remove_file(path); +} + +#[test] +fn io_write_reports_the_bytes_it_wrote() { + let path = scratch_fixture("write-count", ""); + let stack = run_source(&format!( + r#" + fn probe() -> Result {{ + let handle = io::open("{path}", "w")?; + let written = io::write(handle, "abcde")?; + io::flush(handle)?; + io::close(handle)?; + Result::Ok(written == 5) + }} + match probe() {{ + Result::Ok(value) => value, + Result::Err(message) => false, + }}; + "#, + path = path.display() + )) + .expect("a write must report its byte count"); + assert_eq!(stack.last(), Some(&Value::Bool(true))); + assert_eq!( + std::fs::read_to_string(&path).expect("the written file must exist"), + "abcde" + ); + let _ = std::fs::remove_file(path); +} + +#[test] +fn io_close_reports_unit_and_retires_the_scope_resource() { + let compiled = compile_source( + r#" + use io; + fn probe() -> Result { + let handle = io::open("Cargo.toml", "r")?; + io::close(handle)?; + Result::Ok(true) + } + match probe() { + Result::Ok(value) => value, + Result::Err(message) => false, + }; + "#, + ) + .expect("source should compile"); + let mut vm = Vm::new(compiled.program); + let mut status = vm.run().expect("close must not abort the VM"); + loop { + match status { + VmStatus::Halted => break, + VmStatus::Yielded => status = vm.resume().expect("resume"), + VmStatus::Waiting(_) => { + vm.wait_for_host_op_blocking().expect("complete op"); + status = vm.resume().expect("resume"); + } + } + } + assert_eq!( + vm.stack().last(), + Some(&Value::Bool(true)), + "close must report the logical Unit success" + ); + assert!( + vm.execution_scope().resources().is_empty(), + "a successful close must retire its handle" + ); +} diff --git a/tests/builtins/io_scope_lifecycle_tests.rs b/tests/builtins/io_scope_lifecycle_tests.rs index 74571206..a34fc231 100644 --- a/tests/builtins/io_scope_lifecycle_tests.rs +++ b/tests/builtins/io_scope_lifecycle_tests.rs @@ -52,18 +52,31 @@ fn vm_for(source: &str) -> Vm { #[test] fn inline_io_calls_complete_without_pending_operations() { - let mut vm = vm_for("let h = io::open(\"Cargo.toml\", \"r\"); io::close(h);"); + let mut vm = vm_for( + r#" + fn probe() -> Result { + let handle = io::open("Cargo.toml", "r")?; + io::close(handle)?; + Result::Ok(true) + } + probe(); + "#, + ); assert!(vm.execution_scope().operations().is_empty()); assert!(vm.execution_scope().resources().is_empty()); } #[test] -fn io_close_returns_true_and_closed_handle_is_stale() { +fn io_close_reports_unit_and_a_closed_handle_is_stale() { let error = run_source_host_error( r#" - let handle = io::open("Cargo.toml", "r"); - io::close(handle); - io::close(handle); + fn probe() -> Result { + let handle = io::open("Cargo.toml", "r")?; + io::close(handle)?; + io::close(handle)?; + Result::Ok(true) + } + probe(); "#, ); assert!( @@ -79,9 +92,13 @@ fn io_close_returns_true_and_closed_handle_is_stale() { fn io_close_then_read_rejects_stale_handle() { let error = run_source_host_error( r#" - let handle = io::open("Cargo.toml", "r"); - io::close(handle); - io::read_all(handle); + fn probe() -> Result { + let handle = io::open("Cargo.toml", "r")?; + io::close(handle)?; + let text = io::read_all(handle)?; + Result::Ok(text.length > 0) + } + probe(); "#, ); assert!( @@ -100,9 +117,23 @@ fn io_close_on_non_positive_handle_is_rejected() { } #[test] -fn io_open_read_mode_reports_missing_file() { - let error = run_source_host_error("io::open(\"__pd_vm_missing_file_for_test__.txt\", \"r\");"); - assert!(error.contains("io_open failed"), "{error}"); +fn io_open_missing_file_is_a_guest_error() { + let stack = run_source( + r#" + match io::open("__pd_vm_missing_file_for_test__.txt", "r") { + Result::Ok(handle) => "", + Result::Err(message) => message, + }; + "#, + ) + .expect("a missing file must not abort the VM"); + let Some(Value::String(message)) = stack.last() else { + panic!("a missing file must report a guest Err string, got {stack:?}"); + }; + assert!( + message.contains("io_open failed"), + "the guest error must keep the operating-system text: {message}" + ); } #[test] @@ -114,11 +145,14 @@ fn io_open_rejects_unsupported_mode() { #[test] fn io_rejects_foreign_scope_handles() { let foreign_handle = { - let vm = vm_for("let h = io::open(\"Cargo.toml\", \"r\"); h;"); - let Value::Int(raw) = vm.stack().last().cloned().expect("handle on stack") else { - panic!("io::open must return an integer handle"); - }; - raw + let vm = vm_for("io::open(\"Cargo.toml\", \"r\");"); + let value = vm.stack().last().cloned().expect("open result on stack"); + let (ok, payload) = + vm::result::payload(&value).expect("io::open must return a Result carrier"); + assert!(ok, "io::open on a readable file must succeed"); + let handle = vm::result::resource_handle(&payload) + .expect("the Ok branch of io::open must carry the opened handle"); + handle.raw() as i64 }; let error = run_source_host_error(&format!("io::close({foreign_handle});")); assert!( @@ -149,7 +183,7 @@ fn generic_resource_types_remain_distinct() { #[test] fn reset_for_reuse_retires_io_resources_through_scope() { - let mut vm = vm_for("let h = io::open(\"Cargo.toml\", \"r\"); h;"); + let mut vm = vm_for("io::open(\"Cargo.toml\", \"r\");"); assert!(!vm.execution_scope().resources().is_empty()); reset_for_reuse_to_ready(&mut vm).expect("reset should reach quiescence"); assert!(vm.execution_scope().resources().is_empty()); @@ -239,7 +273,15 @@ fn reset_for_reuse_terminates_live_popen_process_tree() { "parent=$$; sleep 30 & child=$!; printf '%s %s' $parent $child > {}; wait $child", marker.display() ); - let mut vm = vm_for(&format!("let h = io::popen(\"{command}\", \"r\"); h;")); + let mut vm = vm_for(&format!( + r#" + fn hold_process() -> Result {{ + let handle = io::popen("{command}", "r")?; + Result::Ok(true) + }} + hold_process(); + "# + )); let (leader, descendant) = read_process_marker(&marker); let _cleanup = ProcessTreeCleanup { leader, @@ -265,7 +307,15 @@ fn vm_drop_signals_live_popen_process_tree_without_driving_close() { "parent=$$; sleep 30 & child=$!; printf '%s %s' $parent $child > {}; wait $child", marker.display() ); - let vm = vm_for(&format!("let h = io::popen(\"{command}\", \"r\"); h;")); + let vm = vm_for(&format!( + r#" + fn hold_process() -> Result {{ + let handle = io::popen("{command}", "r")?; + Result::Ok(true) + }} + hold_process(); + "# + )); let (leader, descendant) = read_process_marker(&marker); let _cleanup = ProcessTreeCleanup { leader, diff --git a/tests/io_descriptor_install_tests.rs b/tests/io_descriptor_install_tests.rs index 371551ed..962a9305 100644 --- a/tests/io_descriptor_install_tests.rs +++ b/tests/io_descriptor_install_tests.rs @@ -98,47 +98,12 @@ fn host_error(error: VmError) -> String { } } -/// The IO guest contract has no nullable or void route: absence is a domain -/// value (`false`, an empty string, or a host error), never an implicit -/// `Option`/`Optional`/`Null` carrier, and every void-free call keeps its -/// concrete return type. -fn assert_no_nullable_or_void_route(path: &str, schema: &HostTypeSchema) { - match schema { - HostTypeSchema::Null | HostTypeSchema::Unit => { - panic!("io public schema {path} exposes a void/null route: {schema:?}") - } - HostTypeSchema::Optional(_) | HostTypeSchema::Option(_) => { - panic!("io public schema {path} exposes a nullable route: {schema:?}") - } - HostTypeSchema::Array(inner) => { - assert_no_nullable_or_void_route(&format!("{path}[]"), inner) - } - HostTypeSchema::Map(inner) => { - assert_no_nullable_or_void_route(&format!("{path}{{}}"), inner) - } - HostTypeSchema::Callable { params, result } => { - for (index, param) in params.iter().enumerate() { - assert_no_nullable_or_void_route(&format!("{path}.callback_param[{index}]"), param); - } - assert_no_nullable_or_void_route(&format!("{path}.callback_result"), result); - } - HostTypeSchema::Result { ok, err } => { - assert_no_nullable_or_void_route(&format!("{path}.ok"), ok); - assert_no_nullable_or_void_route(&format!("{path}.err"), err); - } - HostTypeSchema::Named { fields, .. } => { - for field in fields { - assert_no_nullable_or_void_route(&format!("{path}.{}", field.name), &field.ty); - } - } - HostTypeSchema::Unknown - | HostTypeSchema::Int - | HostTypeSchema::Float - | HostTypeSchema::Number - | HostTypeSchema::Bool - | HostTypeSchema::String - | HostTypeSchema::Bytes - | HostTypeSchema::Resource(_) => {} +/// The recoverable IO contract: the success payload, or the formatted +/// operating-system error message. +fn io_result(ok: HostTypeSchema) -> HostTypeSchema { + HostTypeSchema::Result { + ok: Box::new(ok), + err: Box::new(HostTypeSchema::String), } } @@ -179,11 +144,11 @@ fn io_module_descriptors_carry_coherent_schema_binding_and_effects() { ); let key = io_file_key(); + let open_result = io_result(HostTypeSchema::Resource(key.clone())); let open = &owned["io::open"]; assert_eq!( - open.schema.return_type, - HostTypeSchema::Resource(key.clone()), - "io::open must return the typed io.file resource" + open.schema.return_type, open_result, + "io::open must return the typed io.file resource or a string error" ); assert!( open.effects @@ -272,30 +237,54 @@ fn io_module_descriptors_carry_coherent_schema_binding_and_effects() { // -------------------------------------------------------------------- install #[test] -fn io_owned_public_schemas_have_no_nullable_or_void_route() { +fn io_owned_public_schemas_declare_their_recoverable_routes() { + // Every fallible call reports a plain string error, and no handle parameter + // is ever a nullable route: ownership stays typed. for descriptor in owned_descriptors().values() { - assert_no_nullable_or_void_route( - &format!("{}(return)", descriptor.schema.name), - &descriptor.schema.return_type, - ); - for param in &descriptor.schema.params { - assert_no_nullable_or_void_route( - &format!("{}({})", descriptor.schema.name, param.name), - ¶m.ty, - ); + if descriptor.schema.name == "io::exists" { + continue; + } + match &descriptor.schema.return_type { + HostTypeSchema::Result { err, .. } => assert_eq!( + **err, + HostTypeSchema::String, + "`{}` must report a string error", + descriptor.schema.name + ), + other => panic!( + "`{}` must declare a Result contract, found {other:?}", + descriptor.schema.name + ), } } - // The domain keeps its actual present/absent policy: a missing path is - // `false`, an empty file is an empty string, and close reports its Boolean - // result. None of these is a logical nullable route. + // Recoverable outcomes are explicit in the contract: a missing path and a + // missing command stay Booleans/`Err`, an empty file is `Ok("")`, end of + // file is `Ok(None)`, and the command-style flush/close report `Ok(())`. let owned = owned_descriptors(); assert_eq!(owned["io::exists"].schema.return_type, HostTypeSchema::Bool); assert_eq!( owned["io::read_all"].schema.return_type, - HostTypeSchema::String + io_result(HostTypeSchema::String) + ); + assert_eq!( + owned["io::read_line"].schema.return_type, + io_result(HostTypeSchema::Option(Box::new(HostTypeSchema::String))), + "io::read_line must distinguish end of file from an empty line" + ); + assert_eq!( + owned["io::write"].schema.return_type, + io_result(HostTypeSchema::Int), + "io::write must report the bytes it wrote" + ); + assert_eq!( + owned["io::flush"].schema.return_type, + io_result(HostTypeSchema::Unit) + ); + assert_eq!( + owned["io::close"].schema.return_type, + io_result(HostTypeSchema::Unit) ); - assert_eq!(owned["io::close"].schema.return_type, HostTypeSchema::Bool); } #[test] @@ -602,14 +591,20 @@ fn installed_io_descriptors_execute_open_write_read_close() { let inside = dir.join("payload.txt"); let (mut vm, submitted) = vm_with_installed_io(&format!( r#" - let written = io::open("{inside}", "w"); - io::write(written, "descriptor-installed"); - io::flush(written); - let closed = io::close(written); - let read_back = io::open("{inside}", "r"); - let contents = io::read_all(read_back); - let closed_again = io::close(read_back); - contents; + fn round_trip() -> Result {{ + let written = io::open("{inside}", "w")?; + io::write(written, "descriptor-installed")?; + io::flush(written)?; + io::close(written)?; + let read_back = io::open("{inside}", "r")?; + let contents = io::read_all(read_back)?; + io::close(read_back)?; + Result::Ok(contents) + }} + match round_trip() {{ + Result::Ok(contents) => contents, + Result::Err(message) => message, + }}; "#, inside = inside.display() )); @@ -652,12 +647,18 @@ fn installed_io_descriptors_preserve_absent_false_and_empty_file_string() { fs::write(&empty, "").expect("the empty fixture should be writable"); let (mut vm, submitted) = vm_with_installed_io(&format!( r#" - let present = io::exists("{empty}"); - let absent = io::exists("{missing}"); - let handle = io::open("{empty}", "r"); - let contents = io::read_all(handle); - let closed = io::close(handle); - present && !absent && contents == "" && closed; + fn probe() -> Result {{ + let present = io::exists("{empty}"); + let absent = io::exists("{missing}"); + let handle = io::open("{empty}", "r")?; + let contents = io::read_all(handle)?; + io::close(handle)?; + Result::Ok(present && !absent && contents == "") + }} + match probe() {{ + Result::Ok(value) => value, + Result::Err(message) => false, + }}; "#, empty = empty.display(), missing = missing.display() @@ -697,9 +698,13 @@ fn installed_io_descriptors_reject_a_stale_handle_after_close() { fs::write(&inside, "ownership").expect("fixture file should be writable"); let (mut vm, submitted) = vm_with_installed_io(&format!( r#" - let handle = io::open("{inside}", "r"); - let closed = io::close(handle); - io::read_all(handle); + fn reuse_closed() -> Result {{ + let handle = io::open("{inside}", "r")?; + io::close(handle)?; + let contents = io::read_all(handle)?; + Result::Ok(contents.length) + }} + reuse_closed(); "#, inside = inside.display() )); From 9b7bc441ebd23ff6a8e2d95bf2063fd50d1a00ae Mon Sep 17 00:00:00 2001 From: fffonion Date: Sat, 14 Nov 2026 19:38:02 +0800 Subject: [PATCH 07/16] test(stdlib): assert LRU row values instead of a -1 sentinel The five `oldest`/`newest`/`peek` checks compared against an artificial `-1` fallback, so a wrong `Option` branch would have been indistinguishable from a real value of -1. Each lookup now asserts the expected payload in its `Some` arm and fails in `None`, with no intermediate sentinel. --- stdlib/tests/lrucache.rss | 35 +++++++++++++++-------------------- 1 file changed, 15 insertions(+), 20 deletions(-) diff --git a/stdlib/tests/lrucache.rss b/stdlib/tests/lrucache.rss index 3193fb50..af02cb9a 100644 --- a/stdlib/tests/lrucache.rss +++ b/stdlib/tests/lrucache.rss @@ -53,22 +53,20 @@ let oldest_key = match oldest::(cache) { Option::None => "missing", }; assert(oldest_key == "b"); -let oldest_value = match oldest::(cache) { - Option::Some(row) => row.value, - Option::None => -1, +match oldest::(cache) { + Option::Some(row) => assert(row.value == 2), + Option::None => assert(false), }; -assert(oldest_value == 2); let newest_key = match newest::(cache) { Option::Some(row) => row.key, Option::None => "missing", }; assert(newest_key == "a"); -let newest_value = match newest::(cache) { - Option::Some(row) => row.value, - Option::None => -1, +match newest::(cache) { + Option::Some(row) => assert(row.value == 1), + Option::None => assert(false), }; -assert(newest_value == 1); cache = put::(cache, "c", 3); let mut after_evict = keys::(cache); @@ -87,11 +85,10 @@ cache = put::(cache, "a", 10); let mut after_update = keys::(cache); assert(after_update[0] == "c"); assert(after_update[1] == "a"); -let updated_value = match peek::(cache, "a") { - Option::Some(value) => value, - Option::None => -1, +match peek::(cache, "a") { + Option::Some(value) => assert(value == 10), + Option::None => assert(false), }; -assert(updated_value == 10); let mut missed = get::(cache, "missing"); let missed_is_none = match missed.value { @@ -179,22 +176,20 @@ assert(first_feed_row.value.slug == "beta"); assert(second_feed_row.key == 7); assert(second_feed_row.value.score == 10); -let feed_oldest_key = match oldest::(feed_cache) { - Option::Some(row) => row.key, - Option::None => -1, +match oldest::(feed_cache) { + Option::Some(row) => assert(row.key == 8), + Option::None => assert(false), }; -assert(feed_oldest_key == 8); let feed_oldest_value = match oldest::(feed_cache) { Option::Some(row) => row.value.copy(), Option::None => {slug: "", score: 0}, }; assert(feed_oldest_value.slug == "beta"); -let feed_newest_key = match newest::(feed_cache) { - Option::Some(row) => row.key, - Option::None => -1, +match newest::(feed_cache) { + Option::Some(row) => assert(row.key == 7), + Option::None => assert(false), }; -assert(feed_newest_key == 7); let feed_newest_value = match newest::(feed_cache) { Option::Some(row) => row.value.copy(), Option::None => {slug: "", score: 0}, From bb719cf737675c9a0a0fe21c2886679b2d7cefcb Mon Sep 17 00:00:00 2001 From: fffonion Date: Sat, 14 Nov 2026 20:12:52 +0800 Subject: [PATCH 08/16] fix(io): keep a closed async handle fatal and migrate the IO call sites `io::close` on the async backend routed every `close_shared_io_handle_with` error through the guest `Err` branch after detaching the handle and retiring the scope. That made an already-closed slot (no handle left to flush, signal or retire) look like a recoverable flush failure and pushed the scope through a second retirement. Classify the failure where it is produced instead: `CloseFailure::RuntimeRequired` and an empty slot stay fatal `VmError`s before any mutation, and only `CloseFailure::Cleanup` detaches the handle so `Drop` still signals the process tree, the scope still retires, and the guest sees the message. This matches the blocking backend's order of "fatal empty slot first, then cleanup outcome". Also migrate the remaining call sites to the Result contract this branch introduced: `tests/pr24_resource_tests.rs` (open/close ownership flows and the `io::open` / `io::close` schema assertions) and both guest scripts in `tests/vm/io_http_coexistence_tests.rs`. Document that `io::read_line` strips only the trailing `\n` (so `\r\n` leaves the `\r`) and that the async `publish_owned` validation covers the `Ok` path only, and reword the stale "close stays Boolean" assertion message. New coverage: a closed slot stays fatal and never reaches the cleanup closure, a cleanup failure detaches the handle and cannot be retried, a missing file is a guest error on the async backend, and a retried guest close is rejected. --- docs/host-sdk-descriptors.md | 11 ++ src/builtins/runtime/io/async_io.rs | 174 +++++++++++++++++++++----- tests/builtins/io_async_tests.rs | 78 ++++++++++++ tests/io_descriptor_install_tests.rs | 2 +- tests/pr24_resource_tests.rs | 53 ++++++-- tests/vm/io_http_coexistence_tests.rs | 24 +++- 6 files changed, 295 insertions(+), 47 deletions(-) diff --git a/docs/host-sdk-descriptors.md b/docs/host-sdk-descriptors.md index 65271b60..224ee17d 100644 --- a/docs/host-sdk-descriptors.md +++ b/docs/host-sdk-descriptors.md @@ -238,6 +238,17 @@ macro rejects it), so the async adapter returns the assembled guest carrier through `vm::HostFutureOutput` and publishes it with `crate::result::publish_owned`, which inserts the resource, validates the carrier against the declared contract and rolls the insertion back on failure. +That validation covers the success path only: it is the one that must agree +with `io::open` / `io::popen`'s `Ok(resource)` branch. The `Err` +branches (an unopenable path, a process that cannot be started) are plain +`Value` strings built by the adapter itself, so they carry no resource and are +never routed through `publish_owned` — nothing validates them beyond the +guest's own contract typing. + +`io::read_line`'s success payload is the line **without** its terminator: the +adapter strips one trailing `\n`, so a file ending in `\r\n` leaves the `\r` +in the payload. End of file is `Ok(None)`, and a present but empty line is +`Ok(Some(""))`; the two are never conflated. When context depends on a resource-token argument, implement `capture_with_args(vm, args)` to validate the token and clone the owned resource diff --git a/src/builtins/runtime/io/async_io.rs b/src/builtins/runtime/io/async_io.rs index f1b16491..64c2aa40 100644 --- a/src/builtins/runtime/io/async_io.rs +++ b/src/builtins/runtime/io/async_io.rs @@ -336,42 +336,88 @@ fn start_close_io_handle_for_drop_with( } } -type CloseIoFuture<'a> = Pin> + Send + 'a>>; +/// Why one `io::close` did not reach completion. +/// +/// The variants are classified where they are produced so the caller can keep +/// the two guest-visible channels apart: a cleanup failure is a guest `Err`, +/// while a broken runtime lease is a fatal `VmError`. +#[derive(Debug)] +enum CloseFailure { + /// The handle could not be flushed, or its process tree could not be + /// terminated: a recoverable guest error. + Cleanup(String), + /// Process cleanup was polled without a live Tokio runtime, so the + /// embedding's runtime lease is broken: fatal. + RuntimeRequired, +} + +/// The outcome of a close whose handle was still present in the shared slot. +#[derive(Debug)] +enum SharedCloseOutcome { + /// The handle was flushed/terminated and detached from the slot. + Closed, + /// Flush or process termination failed. The handle was detached so `Drop` + /// still signals the process tree and the scope can retire, and the guest + /// receives the message. + CleanupFailed(String), +} + +type CloseIoFuture<'a> = Pin> + Send + 'a>>; fn close_io_handle_future(handle: &mut IoHandle) -> CloseIoFuture<'_> { Box::pin(close_io_handle(handle)) } +/// Closes the handle owned by `shared`, if it still owns one. +/// +/// An already-closed slot is fatal and mutates nothing: the resource has +/// already retired its handle, so there is nothing left to flush, signal, or +/// retire again. Only a flush or process-termination failure detaches the +/// handle and becomes the guest `Err` branch, mirroring the blocking backend's +/// order of "fatal empty slot first, then cleanup outcome". async fn close_shared_io_handle_with( shared: Arc>>, close: impl for<'a> FnOnce(&'a mut IoHandle) -> CloseIoFuture<'a>, -) -> VmResult<()> { +) -> VmResult { let mut slot = shared.lock().await; let handle = slot .as_mut() .ok_or_else(|| VmError::HostError("io handle is closed".to_string()))?; - close(handle).await?; - slot.take(); - Ok(()) + match close(handle).await { + Ok(()) => { + slot.take(); + Ok(SharedCloseOutcome::Closed) + } + // The handle stays owned: the caller must not retire the scope. + Err(CloseFailure::RuntimeRequired) => Err(VmError::HostError( + "RuntimeRequired: io::close process cleanup must be polled from a live Tokio runtime" + .to_string(), + )), + // The handle survives a failed flush or a process that will not + // terminate. Detach it so the scope retirement can complete while + // `Drop` still signals the process tree, and report the failure to the + // guest instead of aborting the VM. The handle is gone afterwards, so a + // retried close reports a closed slot instead of repeating the cleanup. + Err(CloseFailure::Cleanup(message)) => { + slot.take(); + Ok(SharedCloseOutcome::CleanupFailed(message)) + } + } } -async fn close_io_handle(handle: &mut IoHandle) -> VmResult<()> { +async fn close_io_handle(handle: &mut IoHandle) -> Result<(), CloseFailure> { if matches!( handle, IoHandle::PopenRead { .. } | IoHandle::PopenWrite { .. } ) && tokio::runtime::Handle::try_current().is_err() { - return Err(VmError::HostError( - "RuntimeRequired: io::close process cleanup must be polled from a live Tokio runtime" - .to_string(), - )); + return Err(CloseFailure::RuntimeRequired); } match handle { IoHandle::File(file) => { - file.get_mut() - .flush() - .await - .map_err(|error| VmError::HostError(format!("io_close flush failed: {error}")))?; + file.get_mut().flush().await.map_err(|error| { + CloseFailure::Cleanup(format!("io_close flush failed: {error}")) + })?; } IoHandle::PopenRead { child, .. } => { terminate_child_tree(child).await?; @@ -384,11 +430,11 @@ async fn close_io_handle(handle: &mut IoHandle) -> VmResult<()> { Ok(()) } -async fn terminate_child_tree(child: &mut Child) -> VmResult<()> { +async fn terminate_child_tree(child: &mut Child) -> Result<(), CloseFailure> { let pid = child.id().unwrap_or(0); terminate_process_tree_and_leader(|| terminate_process_id(pid), || kill_and_reap_child(child)) .await - .map_err(|error| VmError::HostError(format!("io_close popen terminate failed: {error}"))) + .map_err(|error| CloseFailure::Cleanup(format!("io_close popen terminate failed: {error}"))) } async fn kill_and_reap_child(child: &mut Child) -> io::Result<()> { @@ -872,16 +918,16 @@ pub(crate) async fn builtin_io_close( #[pd_host_context] context: IoHandleContext, _handle_id: i64, ) -> VmResult>> { - let closed = - close_shared_io_handle_with(Arc::clone(&context.handle), close_io_handle_future).await; - let mut close_failure = None; - if let Err(error) = closed { - // Take the failed handle out of the shared slot so the drop path - // signals the process tree and the scope can still retire it; the - // guest reports the cleanup failure instead of aborting the VM. - context.handle.lock().await.take(); - close_failure = Some(error.to_string()); - } + // A closed slot returns before any retirement: that handle is already gone, + // so retiring the scope again would corrupt the accounting the fatal error + // is reporting. + let close_failure = + match close_shared_io_handle_with(Arc::clone(&context.handle), close_io_handle_future) + .await? + { + SharedCloseOutcome::Closed => None, + SharedCloseOutcome::CleanupFailed(message) => Some(message), + }; let resource = context.resource; Ok(HostFutureOutput::complete(move |vm| { let progress = vm @@ -1094,23 +1140,31 @@ mod tests { fn pending_close<'a>( _handle: &'a mut IoHandle, started: Arc>, - ) -> Pin> + Send + 'a>> { + ) -> Pin> + Send + 'a>> { Box::pin(async move { *started.lock().expect("started lock") = true; pending().await }) } + /// Fails the close the way a real flush or process termination would. + fn failing_close<'a>( + _handle: &'a mut IoHandle, + message: &'static str, + ) -> Pin> + Send + 'a>> { + Box::pin(async move { Err(CloseFailure::Cleanup(message.to_string())) }) + } + #[cfg(unix)] fn start_process_kill_then_pending<'a>( handle: &'a mut IoHandle, started: Arc>, - ) -> Pin> + Send + 'a>> { + ) -> Pin> + Send + 'a>> { Box::pin(async move { match handle { IoHandle::PopenRead { child, .. } | IoHandle::PopenWrite { child, .. } => { child.start_kill().map_err(|error| { - VmError::HostError(format!("test process kill failed: {error}")) + CloseFailure::Cleanup(format!("test process kill failed: {error}")) })?; } IoHandle::File(_) => panic!("expected process handle"), @@ -1120,6 +1174,68 @@ mod tests { }) } + #[tokio::test] + async fn closed_slot_close_is_fatal_and_touches_nothing() { + let resource = file_resource(); + let shared = Arc::clone(&resource.handle); + // The resource already retired its handle; the slot is empty. + shared.lock().await.take(); + let ran = Arc::new(StdMutex::new(false)); + let close_ran = Arc::clone(&ran); + + let error = close_shared_io_handle_with(Arc::clone(&shared), move |handle| { + *close_ran.lock().expect("ran lock") = true; + failing_close(handle, "must not run") + }) + .await + .expect_err("a closed slot must stay fatal instead of becoming a guest error"); + + assert!( + matches!(&error, VmError::HostError(message) if message == "io handle is closed"), + "unexpected error: {error:?}" + ); + assert!( + !*ran.lock().expect("ran lock"), + "a closed slot must not reach the cleanup closure" + ); + assert!( + shared.lock().await.is_none(), + "a closed slot must not take or restore a handle" + ); + } + + #[tokio::test] + async fn cleanup_failure_detaches_the_handle_and_cannot_be_retried() { + let resource = file_resource(); + let shared = Arc::clone(&resource.handle); + + let outcome = close_shared_io_handle_with(Arc::clone(&shared), |handle| { + failing_close(handle, "io_close flush failed: fixture") + }) + .await + .expect("a flush failure is a guest error, not a VM fault"); + assert!( + matches!( + &outcome, + SharedCloseOutcome::CleanupFailed(message) + if message == "io_close flush failed: fixture" + ), + "unexpected close outcome" + ); + assert!( + shared.lock().await.is_none(), + "the failed handle must be detached so Drop signals and the scope can retire" + ); + + let error = close_shared_io_handle_with(Arc::clone(&shared), close_io_handle_future) + .await + .expect_err("a detached handle must not be closable twice"); + assert!( + matches!(&error, VmError::HostError(message) if message == "io handle is closed"), + "the retry must report the closed slot, not repeat the cleanup: {error:?}" + ); + } + #[tokio::test] async fn cancelling_explicit_close_retains_the_handle_in_the_resource() { let resource = file_resource(); diff --git a/tests/builtins/io_async_tests.rs b/tests/builtins/io_async_tests.rs index 2b03b75b..874c9e72 100644 --- a/tests/builtins/io_async_tests.rs +++ b/tests/builtins/io_async_tests.rs @@ -599,3 +599,81 @@ fn async_io_write_reports_bytes_and_close_reports_unit() { ); let _ = std::fs::remove_file(path); } + +/// A missing file is an ordinary guest outcome on the async backend: the call +/// reports `Err(message)` and the VM keeps running. +#[test] +fn async_io_open_missing_file_is_a_guest_error() { + let nonce = SystemTime::now() + .duration_since(UNIX_EPOCH) + .expect("clock should follow Unix epoch") + .as_nanos(); + let path = std::env::temp_dir().join(format!( + "pd-vm-async-missing-{}-{nonce}", + std::process::id() + )); + let _ = std::fs::remove_file(&path); + + let stack = run_source(&format!( + r#" + match io::open("{path}", "r") {{ + Result::Ok(handle) => "unexpected success", + Result::Err(message) => message, + }}; + "#, + path = path.display() + )) + .expect("a missing file must not abort the async VM"); + + let Some(Value::String(message)) = stack.last() else { + panic!("a missing file must report a guest Err string, got {stack:?}"); + }; + assert!( + message.contains("io_open failed"), + "the guest error must keep the operating-system text: {message}" + ); + assert!( + !path.exists(), + "a failed open must not create the missing path" + ); +} + +/// `io::close` takes the handle, so neither a successful close nor a close that +/// reported a cleanup failure can be retried through the same guest handle: the +/// second call is a fatal stale-handle error. +#[test] +fn async_io_close_cannot_be_retried_through_the_same_handle() { + let nonce = SystemTime::now() + .duration_since(UNIX_EPOCH) + .expect("clock should follow Unix epoch") + .as_nanos(); + let path = std::env::temp_dir().join(format!( + "pd-vm-async-close-retry-{}-{nonce}", + std::process::id() + )); + std::fs::write(&path, "retry").expect("fixture should be written"); + + let error = run_source(&format!( + r#" + fn probe() -> Result {{ + let handle = io::open("{path}", "r")?; + io::close(handle)?; + io::close(handle)?; + Result::Ok(true) + }} + probe(); + "#, + path = path.display() + )) + .expect_err("a retried close must fail instead of repeating the cleanup"); + + let message = error.to_string(); + assert!( + message.contains("stale") + || message.contains("not found") + || message.contains("closed") + || message.contains("invalid"), + "a retried close must be rejected: {message}" + ); + let _ = std::fs::remove_file(path); +} diff --git a/tests/io_descriptor_install_tests.rs b/tests/io_descriptor_install_tests.rs index 962a9305..8588d3a3 100644 --- a/tests/io_descriptor_install_tests.rs +++ b/tests/io_descriptor_install_tests.rs @@ -672,7 +672,7 @@ fn installed_io_descriptors_preserve_absent_false_and_empty_file_string() { assert_eq!( run.stack.last(), Some(&Value::Bool(true)), - "a present empty file stays an empty string, a missing path stays false, and close stays Boolean" + "a present empty file stays an empty string, a missing path stays false, and close reports the Unit branch of Result<(), string>" ); assert_pending_ops_resolved_by_backend(&submitted, run.driven_ops, 5); assert_eq!( diff --git a/tests/pr24_resource_tests.rs b/tests/pr24_resource_tests.rs index f6aa74bd..349acfdb 100644 --- a/tests/pr24_resource_tests.rs +++ b/tests/pr24_resource_tests.rs @@ -15,6 +15,14 @@ fn key(name: &str) -> ResourceTypeKey { ResourceTypeKey::new(name).expect("test resource key") } +/// The recoverable IO contract: the success payload, or a string error. +fn io_result(ok: TypeSchema) -> TypeSchema { + TypeSchema::Result { + ok: Box::new(ok), + err: Box::new(TypeSchema::String), + } +} + #[test] fn resource_schema_is_nominal_and_preserves_its_key() { let schema = TypeSchema::Resource(key("sqlite.connection")); @@ -95,7 +103,14 @@ fn standard_catalog_contains_exact_resource_close_schemas() { HostParamPassing::TakeOwned, )] ); - assert_eq!(io_close.return_type, HostTypeSchema::Bool); + assert_eq!( + io_close.return_type, + HostTypeSchema::Result { + ok: Box::new(HostTypeSchema::Unit), + err: Box::new(HostTypeSchema::String), + }, + "io::close reports the flush/terminate outcome as Result<(), string>" + ); #[cfg(all(feature = "sqlite", not(target_family = "wasm")))] { @@ -126,14 +141,18 @@ fn standard_catalog_resolves_open_then_close_with_nominal_ownership() { .expect("standard io::open resolves"); assert_eq!( file.return_type, - TypeSchema::Resource(key("io.file")), - "io::open must produce the IO resource key" + io_result(TypeSchema::Resource(key("io.file"))), + "io::open must produce the IO resource key inside its Result contract" ); let io_close = resolver .resolve("io::close", &[TypeSchema::Resource(key("io.file"))]) .expect("standard io::close resolves"); assert_eq!(io_close.passing, vec![HostParamPassing::TakeOwned]); - assert_eq!(io_close.return_type, TypeSchema::Bool); + assert_eq!( + io_close.return_type, + io_result(TypeSchema::Unit), + "io::close resolves to Result<(), string>" + ); #[cfg(all(feature = "sqlite", not(target_family = "wasm")))] { @@ -170,16 +189,24 @@ fn default_source_compilation_accepts_open_use_close_ownership_flow() { let source = r#" use io; use sqlite; - let file = io::open("Cargo.toml", "r"); - io::close(file); + fn open_and_close() -> Result { + let file = io::open("Cargo.toml", "r")?; + io::close(file)?; + Result::Ok(true) + } + open_and_close(); let connection = sqlite::open({}); sqlite::close(connection); "#; #[cfg(not(all(feature = "sqlite", not(target_family = "wasm"))))] let source = r#" use io; - let file = io::open("Cargo.toml", "r"); - io::close(file); + fn open_and_close() -> Result { + let file = io::open("Cargo.toml", "r")?; + io::close(file)?; + Result::Ok(true) + } + open_and_close(); "#; compile_source_with_flavor_and_options(source, vm::SourceFlavor::RustScript, options) .expect("standard catalog must compile normal open/use/close ownership flow"); @@ -264,9 +291,13 @@ fn closure_capture_can_transfer_resource_to_take_owned_host_call() { CompileSourceFileOptions::new().with_host_api_catalog(vm::standard_host_catalog()); let source = r#" use io; - let file = io::open("Cargo.toml", "r"); - let close_file = || io::close(file); - close_file(); + fn close_in_closure() -> Result { + let file = io::open("Cargo.toml", "r")?; + let close_file = || io::close(file); + close_file()?; + Result::Ok(true) + } + close_in_closure(); "#; compile_source_with_flavor_and_options(source, vm::SourceFlavor::RustScript, options) .expect("a closure may move its captured resource into a TakeOwned host call"); diff --git a/tests/vm/io_http_coexistence_tests.rs b/tests/vm/io_http_coexistence_tests.rs index 2ba0f183..0def2bad 100644 --- a/tests/vm/io_http_coexistence_tests.rs +++ b/tests/vm/io_http_coexistence_tests.rs @@ -652,9 +652,16 @@ async fn triple_domain_single_vm_typed_dataflow_uses_shared_catalog() { use sqlite; use bytes; - let source = io::open("{fixture_path}", "r"); - let payload = io::read_all(&source); - let closed = io::close(source); + fn read_and_close(path: string) -> Result {{ + let source = io::open(path, "r")?; + let payload = io::read_all(source)?; + io::close(source)?; + Result::Ok(payload) + }} + let payload = match read_and_close("{fixture_path}") {{ + Result::Ok(text) => text, + Result::Err(message) => message, + }}; let mut request = http::request::new("POST", "http://127.0.0.1:{port}/echo"); let unit: () = http::request::set_body_text(&mut request, payload); @@ -718,7 +725,6 @@ async fn triple_domain_single_vm_typed_dataflow_uses_shared_catalog() { assert(absent_values.length == 0); assert(inserted.rows_affected == 1); assert(null_inserted.rows_affected == 1); - assert(closed == true); let close_unit: () = sqlite::close(db); stored; "#, @@ -814,8 +820,14 @@ async fn triple_domain_error_cleanup_reset_and_reuse_keep_all_policies() { use http; use sqlite; - let source = io::open("{fixture_path}", "r"); - let payload = io::read_all(&source); + fn read_payload(path: string) -> Result {{ + let source = io::open(path, "r")?; + io::read_all(source) + }} + let payload = match read_payload("{fixture_path}") {{ + Result::Ok(text) => text, + Result::Err(message) => message, + }}; let mut request = http::request::new("POST", "http://127.0.0.1:{port}/echo"); let unit: () = http::request::set_body_text(&mut request, payload); From 16ae08be4ac192ce316d10f2f76113d0fa3ee3dc Mon Sep 17 00:00:00 2001 From: fffonion Date: Sat, 14 Nov 2026 20:35:17 +0800 Subject: [PATCH 09/16] test(io): pin the fatal close at the call site, not just in the helper MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The previous commit fixed `builtin_io_close` and covered the helper it calls, so a revert of the call site kept the suite green. Add the missing caller-level coverage and correct two claims the review found overstated. `builtin_close_keeps_an_empty_slot_resource_registered_and_fatal` installs a registered `io.file` resource whose internal handle is already gone and drives `builtin_io_close`'s own body. It asserts the fatal `io handle is closed` `VmError` and that nothing was retired: the resource count is unchanged, the token still resolves to the same live resource (so its `Drop` never ran), and the scope is not closing. Neither new test passes against the pre-fix caller. `runtime_required_close_retains_the_process_handle` covers the branch the review found untested: a popen close polled outside any Tokio runtime fails with `RuntimeRequired` and still leaves the handle owned, so a retry under a live runtime can close and reap the retained child. The empty-slot state is not reachable from guest code once the fix is in place (only the old double-retirement produced it), which is why the test installs it directly rather than driving a script. Accuracy fixes: the retried-close test only covers the stale-capture path in `io_handle_for_resource` (`resource_stale`), not the cleanup-failure path; the descriptor test's assertion message no longer claims the stack-top `Bool(true)` is close's `Unit` branch; and the docs no longer say the guest `Err` branches skip validation entirely — they skip `publish_owned` only and still pass `validate_host_call_return`. --- docs/host-sdk-descriptors.md | 12 ++- src/builtins/runtime/io/async_io.rs | 146 +++++++++++++++++++++++++++ tests/builtins/io_async_tests.rs | 12 ++- tests/io_descriptor_install_tests.rs | 2 +- 4 files changed, 164 insertions(+), 8 deletions(-) diff --git a/docs/host-sdk-descriptors.md b/docs/host-sdk-descriptors.md index 224ee17d..fc3a87dd 100644 --- a/docs/host-sdk-descriptors.md +++ b/docs/host-sdk-descriptors.md @@ -238,12 +238,16 @@ macro rejects it), so the async adapter returns the assembled guest carrier through `vm::HostFutureOutput` and publishes it with `crate::result::publish_owned`, which inserts the resource, validates the carrier against the declared contract and rolls the insertion back on failure. -That validation covers the success path only: it is the one that must agree -with `io::open` / `io::popen`'s `Ok(resource)` branch. The `Err` +That path is specific to the successful branch: it is the one that must agree +with `io::open` / `io::popen`'s `Ok(resource)` outcome. The `Err` branches (an unopenable path, a process that cannot be started) are plain `Value` strings built by the adapter itself, so they carry no resource and are -never routed through `publish_owned` — nothing validates them beyond the -guest's own contract typing. +never routed through `publish_owned` — there is nothing to insert or roll back. +They are not unchecked, though: every return, including these, still passes the +generic `validate_host_call_return` check +(`src/vm/host.rs:2141` → `validate_host_value`) when the operation completes, +which validates the value against the declared `Result` schema. What they +deliberately skip is resource ownership bookkeeping, not schema validation. `io::read_line`'s success payload is the line **without** its terminator: the adapter strips one trailing `\n`, so a file ending in `\r\n` leaves the `\r` diff --git a/src/builtins/runtime/io/async_io.rs b/src/builtins/runtime/io/async_io.rs index 64c2aa40..c84ba2bd 100644 --- a/src/builtins/runtime/io/async_io.rs +++ b/src/builtins/runtime/io/async_io.rs @@ -1204,6 +1204,152 @@ mod tests { ); } + /// Regression for the call site, not just the helper: a resource entry that + /// is still registered while the handle it owns is already gone must stay a + /// fatal `VmError` out of `builtin_io_close`'s body, before any retirement. + /// + /// `_impl` is the name `#[pd_host_function]` gives the authored body; the + /// generated wrapper only captures the context and submits the future, so + /// this drives the code that owns the `?`-before-retirement ordering. + /// + /// The state itself is not reachable from guest code in a correct build + /// (only the pre-fix double-retirement left an entry behind with an empty + /// slot), so the test installs it directly and asserts on the scope: no + /// `close_resource`, no entry dropped, no scope teardown. + #[tokio::test] + async fn builtin_close_keeps_an_empty_slot_resource_registered_and_fatal() { + let mut vm = Vm::new(crate::vm::Program::new( + Vec::new(), + vec![crate::vm::OpCode::Ret as u8], + )); + let resource = file_resource(); + let shared = Arc::clone(&resource.handle); + let token = vm + .execution_scope() + .push_resource(resource) + .expect("resource insert"); + let handle = token.handle(); + // The handle is gone; the entry and its accounting are not. + shared.lock().await.take(); + + let close = builtin_io_close_impl( + IoHandleContext { + resource: handle, + handle: Arc::clone(&shared), + max_read_bytes: None, + max_write_bytes: None, + }, + handle.raw() as i64, + ) + .await; + + let error = match close { + Err(error) => error, + Ok(_) => { + panic!("a closed slot must stay fatal at the call site, not become a guest error") + } + }; + + assert!( + matches!(&error, VmError::HostError(message) if message == "io handle is closed"), + "unexpected error: {error:?}" + ); + assert_eq!( + vm.execution_scope().resources().len(), + 1, + "the fatal close must not call close_resource on the scope" + ); + assert!( + vm.execution_scope() + .resources() + .get::(&token) + .is_ok(), + "the resource must still be registered, so its Drop never ran" + ); + assert!( + !vm.execution_scope().is_closing(), + "the fatal close must not start scope teardown" + ); + assert!( + shared.lock().await.is_none(), + "the fatal close must not take or restore a handle" + ); + } + + /// `CloseFailure::RuntimeRequired` is the one failure that keeps the handle: + /// the runtime lease broke before the close started, so nothing was flushed + /// or signalled and the caller must not retire its scope either. + #[cfg(target_os = "linux")] + #[test] + fn runtime_required_close_retains_the_process_handle() { + // Popens need a reactor, so spawn under one and then drop out of it: + // `Handle::try_current` is what decides the branch under test. + let runtime = tokio::runtime::Builder::new_current_thread() + .enable_all() + .build() + .expect("spawn runtime should build"); + let resource = runtime.block_on(async { + IoResource::new(spawn_shell_command("sleep 30", "r").expect("process should spawn")) + }); + let shared = Arc::clone(&resource.handle); + assert!( + tokio::runtime::Handle::try_current().is_err(), + "the close must be polled outside a runtime to reach RuntimeRequired" + ); + + let mut vm = Vm::new(crate::vm::Program::new( + Vec::new(), + vec![crate::vm::OpCode::Ret as u8], + )); + let token = vm + .execution_scope() + .push_resource(resource) + .expect("resource insert"); + let handle = token.handle(); + let mut close = Box::pin(builtin_io_close_impl( + IoHandleContext { + resource: handle, + handle: Arc::clone(&shared), + max_read_bytes: None, + max_write_bytes: None, + }, + handle.raw() as i64, + )); + let mut cx = Context::from_waker(Waker::noop()); + + let error = match close.as_mut().poll(&mut cx) { + Poll::Ready(Err(error)) => error, + Poll::Ready(Ok(_)) => panic!("an off-runtime close must not report a guest outcome"), + Poll::Pending => panic!("an off-runtime close must fail instead of waiting"), + }; + assert!( + matches!(&error, VmError::HostError(message) if message.contains("RuntimeRequired")), + "unexpected error: {error:?}" + ); + assert!( + shared.blocking_lock().is_some(), + "a broken runtime lease must leave the handle owned for a retry" + ); + assert_eq!( + vm.execution_scope().resources().len(), + 1, + "the fatal close must not call close_resource on the scope" + ); + + // The retained handle is still closable once a runtime is driven again. + drop(close); + runtime + .block_on(close_shared_io_handle_with( + Arc::clone(&shared), + close_io_handle_future, + )) + .expect("retry under a live runtime should close the retained process"); + assert!( + shared.blocking_lock().is_none(), + "the retried close must detach the handle" + ); + } + #[tokio::test] async fn cleanup_failure_detaches_the_handle_and_cannot_be_retried() { let resource = file_resource(); diff --git a/tests/builtins/io_async_tests.rs b/tests/builtins/io_async_tests.rs index 874c9e72..6ebdc294 100644 --- a/tests/builtins/io_async_tests.rs +++ b/tests/builtins/io_async_tests.rs @@ -638,9 +638,15 @@ fn async_io_open_missing_file_is_a_guest_error() { ); } -/// `io::close` takes the handle, so neither a successful close nor a close that -/// reported a cleanup failure can be retried through the same guest handle: the -/// second call is a fatal stale-handle error. +/// A retried `io::close` on the same guest handle never reaches a close: the +/// first call retired the `io.file` resource, so the second call fails while +/// resolving the token against the scope (`io_handle_for_resource` in +/// `async_io.rs` reports `resource_stale`) and the VM aborts with a fatal handle +/// error. +/// +/// This test covers that stale-capture path only. The empty-slot fatal branch and +/// the cleanup-failure ("cannot be retried through the same handle") path are +/// asserted by the `async_io.rs` unit tests. #[test] fn async_io_close_cannot_be_retried_through_the_same_handle() { let nonce = SystemTime::now() diff --git a/tests/io_descriptor_install_tests.rs b/tests/io_descriptor_install_tests.rs index 8588d3a3..4ee9e10f 100644 --- a/tests/io_descriptor_install_tests.rs +++ b/tests/io_descriptor_install_tests.rs @@ -672,7 +672,7 @@ fn installed_io_descriptors_preserve_absent_false_and_empty_file_string() { assert_eq!( run.stack.last(), Some(&Value::Bool(true)), - "a present empty file stays an empty string, a missing path stays false, and close reports the Unit branch of Result<(), string>" + "a present empty file stays an empty string, a missing path stays false, and io::close's Unit payload only flows through `?` here (its declared Result<(), string> is pinned by the descriptor test in this file)" ); assert_pending_ops_resolved_by_backend(&submitted, run.driven_ops, 5); assert_eq!( From aa2a001fa2f55fba56f8ffbc05c850f94b77822f Mon Sep 17 00:00:00 2001 From: fffonion Date: Sat, 14 Nov 2026 20:53:54 +0800 Subject: [PATCH 10/16] feat(host): port the runtime-owned stack descriptor adapter Descriptors could not express a stack adapter whose pending operation belongs to the generic VM operation/stream registries, so a downstream composed against this revision had to drop either the guest unions or the descriptor adapters. The classes were already present for the other dispatch families; only the runtime-owned pair was missing: * `HostBindingKind::StaticStackRuntimeOwned`, documented as the stack class whose pending operation is resolved from the generic registries rather than from a registered per-function operation driver. * `HostAdapterDescriptor::StaticStackRuntimeOwned(StaticHostStackFunction)`, so the adapter descriptor stays `Copy` and `'static` like its siblings. * `HostFunctionRegistry::mark_exact_runtime_owned_pending`, the registration hook the install path calls after the import registers. `install_descriptor_adapter` registers the adapter exactly like `StaticStack` and marks the import runtime-owned afterwards; the hook fails closed with `cannot mark unregistered host import '' as runtime-owned` and records no per-import state, because submitted operations are already keyed by their reserved host-operation id. No parallel op-driver table is revived, and the binding/adapter mismatch diagnostic is unchanged. Tests cover the install through a module, an explicit descriptor list and a caller catalog snapshot, the unregistered-name rejection, the plain `StaticStack` regression, and both mismatch directions. --- docs/host-sdk-descriptors.md | 37 ++++- src/vm/host.rs | 19 +++ src/vm/host_extension.rs | 200 ++++++++++++++++++++++++++ tests/host_descriptor_effect_tests.rs | 59 ++++++++ 4 files changed, 314 insertions(+), 1 deletion(-) diff --git a/docs/host-sdk-descriptors.md b/docs/host-sdk-descriptors.md index fc3a87dd..c5655642 100644 --- a/docs/host-sdk-descriptors.md +++ b/docs/host-sdk-descriptors.md @@ -13,7 +13,7 @@ One host function declaration produces, in a single macro expansion: | Part | Meaning | |---|---| | `schema` | The guest ABI: parameter names, types, passing modes, return type. This is the only fingerprint input. | -| `binding` | The dispatch class (`Static`, `StaticStack`, `StaticArgs`, `StaticNonYieldingArgs`, `Owned`). | +| `binding` | The dispatch class (`Static`, `StaticStack`, `StaticStackRuntimeOwned`, `StaticArgs`, `StaticNonYieldingArgs`, `Owned`). | | `adapter` | The concrete adapter or owned-dispatch factory installed into a registry. | | `effects` | Guest resource effects (borrow/borrow-mut/take-owned/create) and hidden host-state read/write effects. Runtime-only metadata; excluded from the fingerprint. | | `resource_types` | The concrete resource-type declarations this function contributes. | @@ -379,6 +379,41 @@ operand draining, callback provenance, isolated callback VM, and transactional owned-resource transfer. Do not route an owned function through borrowed or static dispatch. +### Runtime-owned pending dispatch + +A stack adapter whose call suspends — the HTTP request and SQLite statement +families are the standard examples — resolves its pending operation from the +generic VM operation/stream registries (submitted host operations and stream +drivers) instead of from a per-function operation driver. Descriptors express +that with `HostBindingKind::StaticStackRuntimeOwned` and the stack adapter: + +```rust +HostFunctionDescriptor { + schema: http_request_contract(), + binding: HostBindingDescriptor { kind: HostBindingKind::StaticStackRuntimeOwned }, + effects: vec![], + adapter: HostAdapterDescriptor::StaticStackRuntimeOwned(builtin_http_client_request), + resource_types: vec![], +} +``` + +The adapter is a `StaticHostStackFunction`, exactly like `StaticStack`: the two +classes register identically. The difference is the install step — after the +import registers, the module install path calls +`HostFunctionRegistry::mark_exact_runtime_owned_pending(&name)`, which fails +closed for a name that is not registered: + +``` +cannot mark unregistered host import '' as runtime-owned +``` + +The marker records no per-import state: submitted operations are keyed by their +reserved host-operation id, so there is no parallel op-driver table to maintain. +Choose `StaticStackRuntimeOwned` only when the call's pending operation is owned +by those generic registries. A module that schedules its own concrete operation +driver (the `io::*` family) keeps plain `StaticStack`, and an owned-dispatch +function that transfers its operands keeps `Owned`. + ## 6. Aggregation and feature gates A build composes modules through one deterministic list. The standard library's diff --git a/src/vm/host.rs b/src/vm/host.rs index 0c695460..d4966b61 100644 --- a/src/vm/host.rs +++ b/src/vm/host.rs @@ -1627,6 +1627,25 @@ impl HostFunctionRegistry { self.invalidate_plan_cache(); } + /// Marks an exact import as owning its pending operation. + /// + /// A runtime-owned stack adapter suspends into the generic VM + /// submitted-operation/stream registries instead of a registered + /// per-function operation driver; those registries are keyed by the + /// reserved host-operation id, so no per-import state is recorded here. + /// This method is deliberately a registration validation hook: it accepts + /// only an already-registered import and otherwise fails closed, which + /// keeps the descriptor install path honest without resurrecting the + /// retired parallel op-driver table. + pub fn mark_exact_runtime_owned_pending(&mut self, name: &str) -> VmResult<()> { + if !self.contains_name(name) { + return Err(VmError::HostError(format!( + "cannot mark unregistered host import '{name}' as runtime-owned" + ))); + } + Ok(()) + } + pub fn register_catalog_stack( &mut self, schema: HostImportSchema, diff --git a/src/vm/host_extension.rs b/src/vm/host_extension.rs index 6ad985a3..de868598 100644 --- a/src/vm/host_extension.rs +++ b/src/vm/host_extension.rs @@ -111,6 +111,17 @@ pub enum HostBindingKind { Static, /// Stack-mutating adapter with `&mut Vm`. StaticStack, + /// Stack-mutating adapter whose pending operation is owned by the generic + /// runtime operation/stream registries rather than by a registered + /// operation driver. + /// + /// Installs exactly like [`Self::StaticStack`]; the install path + /// additionally marks the registered import runtime-owned through + /// [`super::host::HostFunctionRegistry::mark_exact_runtime_owned_pending`] + /// so a stack adapter that suspends resolves its pending operation from the + /// generic VM registries (submitted host ops / stream drivers) instead of a + /// per-function driver. + StaticStackRuntimeOwned, /// Args-slice adapter without `&mut Vm`. StaticArgs, /// Non-yielding args-slice adapter. @@ -150,6 +161,10 @@ pub enum HostAdapterDescriptor { Static(super::host::StaticHostFunction), /// [`super::host::StaticHostStackFunction`]. StaticStack(super::host::StaticHostStackFunction), + /// Pending-operation-owning [`super::host::StaticHostStackFunction`]: + /// installed as a stack adapter, then marked runtime-owned so its pending + /// operation resolves from the generic VM operation/stream registries. + StaticStackRuntimeOwned(super::host::StaticHostStackFunction), /// [`super::host::StaticHostArgsFunction`]. StaticArgs(super::host::StaticHostArgsFunction), /// Non-yielding [`super::host::StaticHostArgsFunction`]. @@ -528,6 +543,7 @@ fn install_descriptor_adapter( descriptor: &HostFunctionDescriptor, schema: HostImportSchema, ) -> VmResult<()> { + let mut runtime_owned_pending: Option = None; let result = match (&descriptor.binding.kind, &descriptor.adapter) { (HostBindingKind::Static, HostAdapterDescriptor::Static(function)) => { registry.register_catalog_static(schema, *function) @@ -535,6 +551,15 @@ fn install_descriptor_adapter( (HostBindingKind::StaticStack, HostAdapterDescriptor::StaticStack(function)) => { registry.register_catalog_static_stack(schema, *function) } + ( + HostBindingKind::StaticStackRuntimeOwned, + HostAdapterDescriptor::StaticStackRuntimeOwned(function), + ) => { + // The adapter registers exactly like a stack adapter; the + // runtime-owned marker is applied only after the import exists. + runtime_owned_pending = Some(schema.name.clone()); + registry.register_catalog_static_stack(schema, *function) + } (HostBindingKind::StaticArgs, HostAdapterDescriptor::StaticArgs(function)) => { registry.register_catalog_static_args(schema, *function) @@ -559,6 +584,14 @@ fn install_descriptor_adapter( descriptor.schema.name )) })?; + if let Some(name) = runtime_owned_pending { + // Pending dispatch for this import is resolved from the generic VM + // submitted-operation/stream registries, so the registered import is + // marked runtime-owned. The marker is a registration validation hook: + // the submitted-future model already routes those operations, and no + // per-function op driver is installed here. + registry.mark_exact_runtime_owned_pending(&name)?; + } let _ = registered; Ok(()) } @@ -1665,4 +1698,171 @@ mod tests { Err(CatalogRegistrationError::AmbiguousOverload { .. }) )); } + + fn runtime_owned_noop(_vm: &mut Vm, _args: &[Value]) -> VmResult { + Ok(CallOutcome::Return(crate::vm::CallReturn::None)) + } + + fn runtime_owned_schema(name: &str) -> HostFunctionSchema { + HostFunctionSchema::with_return( + name, + vec![HostParamSchema::value("value", HostTypeSchema::Int)], + HostTypeSchema::String, + ) + } + + fn runtime_owned_descriptor(name: &str) -> HostFunctionDescriptor { + HostFunctionDescriptor { + schema: runtime_owned_schema(name), + binding: HostBindingDescriptor { + kind: HostBindingKind::StaticStackRuntimeOwned, + }, + effects: vec![], + adapter: HostAdapterDescriptor::StaticStackRuntimeOwned(runtime_owned_noop), + resource_types: vec![], + } + } + + fn static_stack_descriptor(name: &str) -> HostFunctionDescriptor { + HostFunctionDescriptor { + schema: runtime_owned_schema(name), + binding: HostBindingDescriptor { + kind: HostBindingKind::StaticStack, + }, + effects: vec![], + adapter: HostAdapterDescriptor::StaticStack(runtime_owned_noop), + resource_types: vec![], + } + } + + #[test] + fn runtime_owned_descriptor_installs_and_marks_pending() { + fn descriptor() -> HostFunctionDescriptor { + runtime_owned_descriptor("demo::runtime_owned") + } + const FUNCTIONS: &[fn() -> HostFunctionDescriptor] = &[descriptor]; + let module = HostModuleDescriptor { + name: "demo", + functions: FUNCTIONS, + resources: &[], + }; + let catalog = module.catalog().expect("module catalog"); + + let mut via_module = HostFunctionRegistry::empty(); + module.install(&mut via_module).expect("module install"); + assert!(via_module.contains_name("demo::runtime_owned")); + + let mut via_descriptors = HostFunctionRegistry::empty(); + HostModuleDescriptor::install_descriptors(&mut via_descriptors, &[descriptor()]) + .expect("explicit descriptor install"); + assert!(via_descriptors.contains_name("demo::runtime_owned")); + + let mut via_catalog = HostFunctionRegistry::empty(); + let installed = module + .install_from_catalog(&mut via_catalog, &catalog) + .expect("catalog snapshot install"); + assert_eq!(installed.fingerprint(), catalog.fingerprint()); + assert!(via_catalog.contains_name("demo::runtime_owned")); + // The marker is a registration check, not one-shot state: an import + // installed through the descriptor path is runtime-ownable afterwards. + via_catalog + .mark_exact_runtime_owned_pending("demo::runtime_owned") + .expect("registered import stays runtime-ownable"); + } + + #[test] + fn runtime_owned_marker_rejects_unregistered_imports() { + let mut registry = HostFunctionRegistry::empty(); + let error = registry + .mark_exact_runtime_owned_pending("demo::unregistered") + .expect_err("an unregistered import cannot be marked runtime-owned"); + assert!( + matches!( + &error, + crate::vm::VmError::HostError(message) + if message + == "cannot mark unregistered host import 'demo::unregistered' as runtime-owned" + ), + "unexpected error: {error}" + ); + assert!(!registry.contains_name("demo::unregistered")); + } + + #[test] + fn static_stack_descriptor_still_installs_without_the_runtime_owned_marker() { + fn descriptor() -> HostFunctionDescriptor { + static_stack_descriptor("demo::static_stack") + } + const FUNCTIONS: &[fn() -> HostFunctionDescriptor] = &[descriptor]; + let module = HostModuleDescriptor { + name: "demo", + functions: FUNCTIONS, + resources: &[], + }; + let catalog = module.catalog().expect("module catalog"); + + let mut registry = HostFunctionRegistry::empty(); + HostModuleDescriptor::install_descriptors(&mut registry, &[descriptor()]) + .expect("plain stack descriptor install"); + assert!(registry.contains_name("demo::static_stack")); + + let mut from_catalog = HostFunctionRegistry::empty(); + module + .install_from_catalog(&mut from_catalog, &catalog) + .expect("plain stack catalog install"); + assert!(from_catalog.contains_name("demo::static_stack")); + } + + #[test] + fn runtime_owned_binding_requires_the_runtime_owned_adapter() { + fn descriptor() -> HostFunctionDescriptor { + HostFunctionDescriptor { + schema: runtime_owned_schema("demo::variant_mismatch"), + binding: HostBindingDescriptor { + kind: HostBindingKind::StaticStackRuntimeOwned, + }, + effects: vec![], + adapter: HostAdapterDescriptor::StaticStack(runtime_owned_noop), + resource_types: vec![], + } + } + fn mirrored() -> HostFunctionDescriptor { + HostFunctionDescriptor { + schema: runtime_owned_schema("demo::mirrored_mismatch"), + binding: HostBindingDescriptor { + kind: HostBindingKind::StaticStack, + }, + effects: vec![], + adapter: HostAdapterDescriptor::StaticStackRuntimeOwned(runtime_owned_noop), + resource_types: vec![], + } + } + + for (factory, name) in [ + ( + descriptor as fn() -> HostFunctionDescriptor, + "demo::variant_mismatch", + ), + ( + mirrored as fn() -> HostFunctionDescriptor, + "demo::mirrored_mismatch", + ), + ] { + let mut registry = HostFunctionRegistry::empty(); + let error = HostModuleDescriptor::install_descriptors(&mut registry, &[factory()]) + .expect_err("binding/adapter disagreement must fail"); + assert!( + error.to_string().contains("binding/adapter mismatch"), + "unexpected error: {error}" + ); + assert!( + error.to_string().contains(name), + "unexpected error: {error}" + ); + assert!( + !registry.contains_name(name), + "a rejected install must leave `{name}` unbound" + ); + } + } } diff --git a/tests/host_descriptor_effect_tests.rs b/tests/host_descriptor_effect_tests.rs index 632d2508..4377bedd 100644 --- a/tests/host_descriptor_effect_tests.rs +++ b/tests/host_descriptor_effect_tests.rs @@ -1672,3 +1672,62 @@ fn module_install_from_catalog_keeps_caller_identity_and_restricted_policy() { "a rejected module must leave the registry unchanged: {error}" ); } + +fn runtime_owned_descriptor() -> vm::host_extension::HostFunctionDescriptor { + use vm::host_extension::{ + HostAdapterDescriptor, HostBindingDescriptor, HostBindingKind, HostFunctionDescriptor, + }; + HostFunctionDescriptor { + schema: HostFunctionSchema::with_return( + "demo::await_signal", + vec![HostParamSchema::value("value", HostTypeSchema::Int)], + HostTypeSchema::String, + ), + binding: HostBindingDescriptor { + kind: HostBindingKind::StaticStackRuntimeOwned, + }, + effects: vec![], + adapter: HostAdapterDescriptor::StaticStackRuntimeOwned(noop_host), + resource_types: vec![], + } +} + +#[test] +fn runtime_owned_descriptor_installs_through_the_caller_catalog() { + use vm::host_extension::{HostAdapterDescriptor, HostBindingKind, HostModuleDescriptor}; + + let module = HostModuleDescriptor { + name: "demo.runtime_owned", + functions: &[runtime_owned_descriptor], + resources: &[], + }; + let catalog = module.catalog().expect("module catalog"); + + // The descriptor keeps the runtime-owned binding class and the plain stack + // adapter: pending dispatch is resolved by the generic VM registries, so + // the adapter is a `StaticHostStackFunction` like `StaticStack`. + let descriptor = (module.functions[0])(); + assert_eq!( + descriptor.binding.kind, + HostBindingKind::StaticStackRuntimeOwned + ); + assert!(matches!( + descriptor.adapter, + HostAdapterDescriptor::StaticStackRuntimeOwned(_) + )); + + let mut registry = vm::HostFunctionRegistry::restricted(); + module + .install_from_catalog(&mut registry, &catalog) + .expect("a runtime-owned module installs against the caller catalog"); + assert!(registry.contains_name("demo::await_signal")); + registry + .mark_exact_runtime_owned_pending("demo::await_signal") + .expect("the installed import is runtime-ownable"); + + // The same descriptor list installs through the aggregate path. + let mut aggregate = vm::HostFunctionRegistry::empty(); + HostModuleDescriptor::install_descriptors(&mut aggregate, &[runtime_owned_descriptor()]) + .expect("runtime-owned descriptors install without a module wrapper"); + assert!(aggregate.contains_name("demo::await_signal")); +} From cc156f3898efb33b5a1be2002e18faac8e228f16 Mon Sep 17 00:00:00 2001 From: fffonion Date: Sat, 14 Nov 2026 20:54:53 +0800 Subject: [PATCH 11/16] test(standard): re-pin the catalog fingerprints after the IO Result contracts The `io` module now reports its outcomes as `Result` instead of sentinel values, which changes its guest schema and therefore its catalog identity. The arch guard still carried the pre-`Result` pins, so `io` and every composed standard catalog failed byte-for-byte comparison on a clean tree. `io` is composed into every build, so all four composed identities move with it. Re-pinned from the values the guard itself reports for each feature set: `io` `c8877c93e38dd831`; standard base `8bf67281072b7f1d`, sqlite `34b88854300802c8`, http `48b693a20f1b92d0`, http+sqlite `2cd4d66a50e0cc47`. No schema, adapter, or IO behavior is touched. --- tests/standard_host_descriptor_arch_tests.rs | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/tests/standard_host_descriptor_arch_tests.rs b/tests/standard_host_descriptor_arch_tests.rs index 4d96b405..c38661ae 100644 --- a/tests/standard_host_descriptor_arch_tests.rs +++ b/tests/standard_host_descriptor_arch_tests.rs @@ -30,12 +30,17 @@ const HTTP_SURFACE_ENABLED: bool = cfg!(all(feature = "http-client", not(target_ // standard catalog also carries `runtime::sleep` (same Unit result) and the // `aot::compile` / `aot::clear` command hosts, so any result-type change to // those two surface families re-pins these values as well. +// +// They were re-pinned again when the `io` module reported its outcomes as +// `Result` instead of sentinel values: `io` is composed into every build, so +// its schema change moves both the `io` catalog identity and all four composed +// standard identities. const SQLITE_SURFACE_ENABLED: bool = cfg!(all(feature = "sqlite", not(target_family = "wasm"))); -const STANDARD_CATALOG_FINGERPRINT_HTTP_SQLITE: &str = "84cb7f8e3872bec4"; -const STANDARD_CATALOG_FINGERPRINT_SQLITE: &str = "b0d7ea2d8fb1c73d"; -const STANDARD_CATALOG_FINGERPRINT_HTTP: &str = "e49304b3042a55cf"; -const STANDARD_CATALOG_FINGERPRINT_BASE: &str = "9683c55f6e57531c"; -const IO_CATALOG_FINGERPRINT: &str = "a16730bd11bf5e10"; +const STANDARD_CATALOG_FINGERPRINT_HTTP_SQLITE: &str = "2cd4d66a50e0cc47"; +const STANDARD_CATALOG_FINGERPRINT_SQLITE: &str = "34b88854300802c8"; +const STANDARD_CATALOG_FINGERPRINT_HTTP: &str = "48b693a20f1b92d0"; +const STANDARD_CATALOG_FINGERPRINT_BASE: &str = "8bf67281072b7f1d"; +const IO_CATALOG_FINGERPRINT: &str = "c8877c93e38dd831"; #[cfg(all(feature = "sqlite", not(target_family = "wasm")))] const SQLITE_CATALOG_FINGERPRINT: &str = "740ab59ccb8fd09a"; const JIT_CATALOG_FINGERPRINT: &str = "ae81318e8a018681"; From f53bb626073547e5c3d93072a35f5c2f780d0e5a Mon Sep 17 00:00:00 2001 From: fffonion Date: Sat, 14 Nov 2026 21:36:26 +0800 Subject: [PATCH 12/16] feat(host): port the runtime_owned_pending macro attribute The runtime side already understood `StaticStackRuntimeOwned`, but the attribute macro could not emit it: `#[pd_host_function]` accepted `name` and `contract` only, so a function whose pending operation belongs to the generic VM operation/stream registries had no declarative spelling. No downstream in this tree uses it yet, but the gap made the macro line strictly weaker than the descriptor line it is supposed to mirror, and the next composed module would have hit a parse error instead of a descriptor. The attribute now accepts a `runtime_owned_pending` path flag end to end: * `parse_function_args` returns it alongside `name`/`contract`, and the unsupported-argument diagnostic names it. * The flag is threaded through `generate_host_function_descriptor` into `generated_adapter_tokens`, which both the inferred and the contract-declared paths now share instead of duplicating the binding match. * It is only accepted on a stack-dispatch signature. Any other binding class fails closed with the descriptor-line wording, character for character: `runtime_owned_pending requires a stack-dispatch signature (`&mut Vm` or a resource parameter)`. * On a stack signature it swaps the binding class to `HostBindingKind::StaticStackRuntimeOwned` and the adapter to `HostAdapterDescriptor::StaticStackRuntimeOwned()`. The adapter function itself stays the plain stack adapter, so install and dispatch are unchanged; only the marker records that pending resolution is generic. The one deliberate difference from the descriptor line: the flag also applies to the inferred (no `contract`) path, where it was silently ignored. Implementing it once in the shared helper makes both paths behave the same and turns a silent no-op into either a working binding or the exact arity error. Tests: `runtime_owned_pending_flag_selects_the_pending_owning_stack_adapter`, `runtime_owned_pending_flag_requires_a_stack_dispatch_signature` (exact message), and `stack_signature_without_the_flag_still_generates_a_plain_stack_adapter` as the regression that a non-opted-in function keeps `StaticStack`. The runtime-owned integration case also grows the missing restricted-registry assertion: a catalogue that does not declare the import still rejects the module with `missing catalog member 'demo::await_signal'` and leaves the registry generation untouched. --- pd-host-function/src/lib.rs | 199 +++++++++++++++++++------- tests/host_descriptor_effect_tests.rs | 25 ++++ 2 files changed, 169 insertions(+), 55 deletions(-) diff --git a/pd-host-function/src/lib.rs b/pd-host-function/src/lib.rs index a3b94b6d..fffc6c11 100644 --- a/pd-host-function/src/lib.rs +++ b/pd-host-function/src/lib.rs @@ -25,7 +25,7 @@ fn expand_pd_host_function( attr: Punctuated, mut item: ItemFn, ) -> Result { - let (guest_name, contract) = parse_function_args(&attr)?; + let (guest_name, contract, runtime_owned_pending) = parse_function_args(&attr)?; let is_async = item.sig.asyncness.is_some(); let docs = doc_string(&item.attrs); let mut resource_params = Vec::<(String, ResourceSpec)>::new(); @@ -136,6 +136,7 @@ fn expand_pd_host_function( &resource_params, &state_params, contract.as_ref(), + runtime_owned_pending, )?; for input in &mut item.sig.inputs { if let FnArg::Typed(pat_type) = input { @@ -266,21 +267,30 @@ fn is_async_owned_type(ty: &Type) -> bool { } /// Parses `#[pd_host_function(name = "...")]` plus the optional -/// `contract = ` guest-schema override. +/// `contract = ` guest-schema override and the optional +/// `runtime_owned_pending` dispatch flag. /// /// `contract` names a zero-argument callable returning a /// [`HostFunctionSchema`](pd_host_schema) for functions whose guest contract -/// cannot be inferred from the Rust signature alone (raw handle parameters, +/// cannot be inferred from the Rust signature (raw-handle parameters, or /// fixed-shape map returns). The contract is declared next to the function it /// describes, so the adapter, binding class, and effects still come from one /// macro expansion and there is no parallel catalog entry. +/// +/// `runtime_owned_pending` selects the stack dispatch class whose pending +/// operation is owned by the generic runtime operation/stream registries +/// instead of a registered operation driver. fn parse_function_args( args: &Punctuated, -) -> Result<(LitStr, Option), Error> { +) -> Result<(LitStr, Option, bool), Error> { let mut name: Option = None; let mut contract: Option = None; + let mut runtime_owned_pending = false; for meta in args { match meta { + Meta::Path(path) if path.is_ident("runtime_owned_pending") => { + runtime_owned_pending = true; + } Meta::NameValue(name_value) if name_value.path.is_ident("name") => { let syn::Expr::Lit(expr_lit) = &name_value.value else { return Err(Error::new_spanned( @@ -321,7 +331,7 @@ fn parse_function_args( return Err(Error::new_spanned( other, "#[pd_host_function] only supports name = \"...\", an optional \ - contract = ", + contract = , and the runtime_owned_pending dispatch flag", )); } } @@ -332,7 +342,7 @@ fn parse_function_args( "expected #[pd_host_function(name = \"...\")]", )); }; - Ok((name, contract)) + Ok((name, contract, runtime_owned_pending)) } fn doc_string(attrs: &[syn::Attribute]) -> String { @@ -1045,6 +1055,7 @@ fn generate_host_function_descriptor( resource_params: &[(String, ResourceSpec)], state_params: &[(String, StateSpec)], contract: Option<&syn::Path>, + runtime_owned_pending: bool, ) -> Result { let descriptor_name = syn::Ident::new(&format!("{wrapper_name}_descriptor"), wrapper_name.span()); @@ -1064,6 +1075,7 @@ fn generate_host_function_descriptor( state_params, binding, item, + runtime_owned_pending, ); } @@ -1162,47 +1174,14 @@ fn generate_host_function_descriptor( resource_meta_tokens.push(meta); } - let (binding_kind, adapter, adapter_fn) = match binding { - GeneratedBinding::Stack => ( - quote!(#sdk::host_extension::HostBindingKind::StaticStack), - quote!(#sdk::host_extension::HostAdapterDescriptor::StaticStack(#adapter_name)), - quote! { - #[allow(dead_code)] - fn #adapter_name( - vm: &mut #sdk::Vm, - args: &[#sdk::Value], - ) -> #sdk::VmResult<#sdk::CallOutcome> { - #sdk::host_extension::host_descriptor_call_outcome( - #wrapper_name(vm, args), - ) - } - }, - ), - GeneratedBinding::Args => ( - quote!(#sdk::host_extension::HostBindingKind::StaticArgs), - quote!(#sdk::host_extension::HostAdapterDescriptor::StaticArgs(#adapter_name)), - quote! { - #[allow(dead_code)] - fn #adapter_name( - args: &[#sdk::Value], - ) -> #sdk::VmResult<#sdk::CallOutcome> { - #sdk::host_extension::host_descriptor_call_outcome(#wrapper_name(args)) - } - }, - ), - GeneratedBinding::NonYieldingArgs => ( - quote!(#sdk::host_extension::HostBindingKind::StaticNonYieldingArgs), - quote!(#sdk::host_extension::HostAdapterDescriptor::StaticNonYieldingArgs(#adapter_name)), - quote! { - #[allow(dead_code)] - fn #adapter_name( - args: &[#sdk::Value], - ) -> #sdk::VmResult<#sdk::CallOutcome> { - #sdk::host_extension::host_descriptor_call_outcome(#wrapper_name(args)) - } - }, - ), - }; + let (binding_kind, adapter, adapter_fn) = generated_adapter_tokens( + &sdk, + &adapter_name, + wrapper_name, + binding, + runtime_owned_pending, + item, + )?; Ok(quote! { #adapter_fn @@ -1237,17 +1216,35 @@ enum GeneratedBinding { /// /// Returns `(binding kind, adapter value, adapter function)` so the inferred /// and contract-declared descriptor paths cannot diverge. +/// +/// `runtime_owned_pending` upgrades a stack adapter to +/// `HostBindingKind::StaticStackRuntimeOwned` so its pending operation resolves +/// from the generic runtime operation/stream registries. The flag is only +/// meaningful for a signature that already dispatches through the stack, so any +/// other binding class is rejected here rather than silently ignored. fn generated_adapter_tokens( sdk: &proc_macro2::TokenStream, adapter_name: &syn::Ident, wrapper_name: &syn::Ident, binding: GeneratedBinding, -) -> ( - proc_macro2::TokenStream, - proc_macro2::TokenStream, - proc_macro2::TokenStream, -) { - match binding { + runtime_owned_pending: bool, + item: &ItemFn, +) -> Result< + ( + proc_macro2::TokenStream, + proc_macro2::TokenStream, + proc_macro2::TokenStream, + ), + Error, +> { + if runtime_owned_pending && !matches!(binding, GeneratedBinding::Stack) { + return Err(Error::new_spanned( + &item.sig.ident, + "runtime_owned_pending requires a stack-dispatch signature (`&mut Vm` or a resource \ + parameter)", + )); + } + let (mut binding_kind, mut adapter, adapter_fn) = match binding { GeneratedBinding::Stack => ( quote!(#sdk::host_extension::HostBindingKind::StaticStack), quote!(#sdk::host_extension::HostAdapterDescriptor::StaticStack(#adapter_name)), @@ -1287,7 +1284,17 @@ fn generated_adapter_tokens( } }, ), + }; + if runtime_owned_pending { + // The adapter function itself stays a stack adapter; only the binding + // class and adapter marker record that the pending operation belongs to + // the generic runtime registries. + binding_kind = quote!(#sdk::host_extension::HostBindingKind::StaticStackRuntimeOwned); + adapter = quote!(#sdk::host_extension::HostAdapterDescriptor::StaticStackRuntimeOwned( + #adapter_name + )); } + Ok((binding_kind, adapter, adapter_fn)) } /// Descriptor tokens for a function that declares its guest schema explicitly. @@ -1311,6 +1318,7 @@ fn generate_contract_host_function_descriptor( state_params: &[(String, StateSpec)], binding: GeneratedBinding, item: &ItemFn, + runtime_owned_pending: bool, ) -> Result { let mut state_effect_tokens = Vec::new(); for input in &item.sig.inputs { @@ -1337,8 +1345,14 @@ fn generate_contract_host_function_descriptor( }); } - let (binding_kind, adapter, adapter_fn) = - generated_adapter_tokens(sdk, adapter_name, wrapper_name, binding); + let (binding_kind, adapter, adapter_fn) = generated_adapter_tokens( + sdk, + adapter_name, + wrapper_name, + binding, + runtime_owned_pending, + item, + )?; Ok(quote! { #adapter_fn @@ -1915,6 +1929,81 @@ mod tests { ); } + #[test] + fn runtime_owned_pending_flag_selects_the_pending_owning_stack_adapter() { + let attr: Punctuated = parse_quote!( + name = "http::client::request", + contract = http_request_contract, + runtime_owned_pending + ); + let item: ItemFn = parse_quote! { + /// Suspends until the generic runtime operation registry completes it. + fn request(vm: &mut Vm, request: VmMapHandle) -> VmResult> { + todo!() + } + }; + let expanded = expand_pd_host_function(attr, item).unwrap().to_string(); + assert!( + expanded.contains("HostBindingKind :: StaticStackRuntimeOwned"), + "the dispatch flag must select the pending-owning binding class: {expanded}" + ); + assert!( + expanded.contains("HostAdapterDescriptor :: StaticStackRuntimeOwned"), + "the dispatch flag must select the pending-owning adapter: {expanded}" + ); + assert!( + expanded.contains("declared_host_contract"), + "the guest contract is still declared on the same function: {expanded}" + ); + } + + #[test] + fn runtime_owned_pending_flag_requires_a_stack_dispatch_signature() { + let attr: Punctuated = parse_quote!( + name = "demo::count", + contract = demo_count_contract, + runtime_owned_pending + ); + let item: ItemFn = parse_quote! { + /// A non-yielding signature cannot own a pending operation. + fn count() -> i64 { + todo!() + } + }; + let error = expand_pd_host_function(attr, item) + .expect_err("the pending flag requires a stack-dispatch signature"); + assert_eq!( + error.to_string(), + "runtime_owned_pending requires a stack-dispatch signature (`&mut Vm` or a resource \ + parameter)" + ); + } + + #[test] + fn stack_signature_without_the_flag_still_generates_a_plain_stack_adapter() { + let attr: Punctuated = + parse_quote!(name = "io::open", contract = io_open_contract); + let item: ItemFn = parse_quote! { + /// Opens a raw handle whose guest contract is declared explicitly. + fn open(vm: &mut Vm, path: &str) -> VmResult { + todo!() + } + }; + let expanded = expand_pd_host_function(attr, item).unwrap().to_string(); + assert!( + expanded.contains("HostBindingKind :: StaticStack"), + "the default stack binding class must be unchanged: {expanded}" + ); + assert!( + expanded.contains("HostAdapterDescriptor :: StaticStack ("), + "the default stack adapter must be unchanged: {expanded}" + ); + assert!( + !expanded.contains("StaticStackRuntimeOwned"), + "a function that does not opt in must not become runtime-owned: {expanded}" + ); + } + #[test] fn contract_argument_keeps_hidden_state_effects() { let attr: Punctuated = diff --git a/tests/host_descriptor_effect_tests.rs b/tests/host_descriptor_effect_tests.rs index 4377bedd..5e59104a 100644 --- a/tests/host_descriptor_effect_tests.rs +++ b/tests/host_descriptor_effect_tests.rs @@ -1725,6 +1725,31 @@ fn runtime_owned_descriptor_installs_through_the_caller_catalog() { .mark_exact_runtime_owned_pending("demo::await_signal") .expect("the installed import is runtime-ownable"); + // A restricted registry is still bounded by the caller catalogue: the + // runtime-owned binding class does not widen what may be installed, so a + // catalogue that does not declare the import must reject it and leave the + // registry untouched. + let other_module = HostModuleDescriptor { + name: "demo.other", + functions: &[add_descriptor], + resources: &[], + }; + let foreign_catalog = other_module.catalog().expect("foreign module catalog"); + let mut narrowed = vm::HostFunctionRegistry::restricted(); + let plan_before = narrowed + .prepare_shared_plan(&[]) + .expect("baseline plan should build"); + let error = module + .install_from_catalog(&mut narrowed, &foreign_catalog) + .expect_err("an undeclared import must be rejected by a restricted registry"); + assert!( + error + .to_string() + .contains("missing catalog member 'demo::await_signal'"), + "the rejection should report the undeclared import as missing, got {error}" + ); + assert_registry_unmodified(&narrowed, &plan_before, &["demo::await_signal"]); + // The same descriptor list installs through the aggregate path. let mut aggregate = vm::HostFunctionRegistry::empty(); HostModuleDescriptor::install_descriptors(&mut aggregate, &[runtime_owned_descriptor()]) From e01ee773de7bec024d14270c687c1e339eda5a9e Mon Sep 17 00:00:00 2001 From: fffonion Date: Sat, 14 Nov 2026 22:23:26 +0800 Subject: [PATCH 13/16] chore(vscode): sync the canonical TextMate grammar with spec master Copy syntaxes/rustscript.tmLanguage.json byte-for-byte from the spec repository (master c2161b31) so the Core extension highlights the same lexical surface: unit literal, Option/Result constructors, propagation operator and optional access operator, with the removed null literal. --- .../syntaxes/rustscript.tmLanguage.json | 46 ++++++++++++++++--- 1 file changed, 39 insertions(+), 7 deletions(-) diff --git a/vscode-rustscript/syntaxes/rustscript.tmLanguage.json b/vscode-rustscript/syntaxes/rustscript.tmLanguage.json index 006f3785..a15ca5ae 100644 --- a/vscode-rustscript/syntaxes/rustscript.tmLanguage.json +++ b/vscode-rustscript/syntaxes/rustscript.tmLanguage.json @@ -28,7 +28,7 @@ "include": "#booleans" }, { - "include": "#null-literal" + "include": "#unit-literal" }, { "include": "#numbers" @@ -39,6 +39,9 @@ { "include": "#wildcard-pattern" }, + { + "include": "#option-result-constructor" + }, { "include": "#namespace-call" }, @@ -51,6 +54,12 @@ { "include": "#closure-pipes" }, + { + "include": "#optional-access-operator" + }, + { + "include": "#propagation-operator" + }, { "include": "#operators" }, @@ -411,9 +420,24 @@ "name": "constant.language.boolean.rss", "match": "\\b(?:true|false)\\b" }, - "null-literal": { - "name": "constant.language.null.rss", - "match": "\\bnull\\b" + "unit-literal": { + "name": "constant.language.unit.rss", + "match": "(?\\n]*(?:<[^<>\\n]*>[^<>\\n]*)*>)(?=\\s*\\()", + "match": "\\b(?!pub\\b|struct\\b|fn\\b|let\\b|mut\\b|for\\b|if\\b|else\\b|match\\b|while\\b|break\\b|continue\\b|use\\b|as\\b|true\\b|false\\b)([A-Za-z_][A-Za-z0-9_]*)(\\s*)(::)(\\s*)(<[^<>\\n]*(?:<[^<>\\n]*>[^<>\\n]*)*>)(?=\\s*\\()", "captures": { "1": { "name": "entity.name.function.rss" @@ -589,7 +613,7 @@ }, { "name": "entity.name.function.rss", - "match": "\\b(?!pub\\b|struct\\b|fn\\b|let\\b|mut\\b|for\\b|if\\b|else\\b|match\\b|while\\b|break\\b|continue\\b|use\\b|as\\b|true\\b|false\\b|null\\b)([A-Za-z_][A-Za-z0-9_]*)\\s*(?=\\()" + "match": "\\b(?!pub\\b|struct\\b|fn\\b|let\\b|mut\\b|for\\b|if\\b|else\\b|match\\b|while\\b|break\\b|continue\\b|use\\b|as\\b|true\\b|false\\b)([A-Za-z_][A-Za-z0-9_]*)\\s*(?=\\()" } ] }, @@ -659,7 +683,15 @@ }, "operators": { "name": "keyword.operator.rss", - "match": "=>|==|!=|&&|\\|\\||&|=|\\+|-|\\*|/|%|<|>|!|\\?" + "match": "=>|==|!=|&&|\\|\\||&|=|\\+|-|\\*|/|%|<|>|!" + }, + "propagation-operator": { + "name": "keyword.operator.propagation.rss", + "match": "\\?(?!\\.)" + }, + "optional-access-operator": { + "name": "keyword.operator.optional-access.rss", + "match": "\\?\\." }, "punctuation": { "name": "punctuation.separator.rss", From 9b86a2709d97682aa3edec9aa46c2f4bd2fd46bd Mon Sep 17 00:00:00 2001 From: fffonion Date: Sat, 14 Nov 2026 22:23:26 +0800 Subject: [PATCH 14/16] test(examples): move the canonical examples onto the Unit/Option/Result contracts The LRU example now returns Option from peek, drops the found flag from get, and returns Option> from oldest/newest instead of the removed LruPeekResult/LruEntryReport wrappers. The complex example documents runtime::sleep as a Unit statement. A new self-contained Option/Result example prints one named line per contract check, and tests/option_result_downstream_examples.rs compiles and runs it, the LRU and the complex examples through the hidden stdlib modules, asserting the named output rather than only the exit status. --- pd-vm-wasm/examples/rss-complex-example.rss | 2 + pd-vm-wasm/examples/rss-lrucache-example.rss | 66 ++--- .../examples/rss-option-result-example.rss | 243 +++++++++++++++ pd-vm-wasm/src/lib.rs | 6 +- tests/option_result_downstream_examples.rs | 279 ++++++++++++++++++ 5 files changed, 562 insertions(+), 34 deletions(-) create mode 100644 pd-vm-wasm/examples/rss-option-result-example.rss create mode 100644 tests/option_result_downstream_examples.rs diff --git a/pd-vm-wasm/examples/rss-complex-example.rss b/pd-vm-wasm/examples/rss-complex-example.rss index 2dfbadd3..83699c45 100644 --- a/pd-vm-wasm/examples/rss-complex-example.rss +++ b/pd-vm-wasm/examples/rss-complex-example.rss @@ -19,6 +19,8 @@ for i in 0..4 { total = total + i; } +// `runtime::sleep` declares the logical Unit result, so it stays a statement: +// the call is never bound and its value is never inspected. runtime::sleep(100); let total = if !string::non_empty("rustscript") => { diff --git a/pd-vm-wasm/examples/rss-lrucache-example.rss b/pd-vm-wasm/examples/rss-lrucache-example.rss index 0aad0306..f3d5df55 100644 --- a/pd-vm-wasm/examples/rss-lrucache-example.rss +++ b/pd-vm-wasm/examples/rss-lrucache-example.rss @@ -32,20 +32,8 @@ struct LruCacheState { nodes: map> } -struct LruPeekResult { - found: bool, - value: Option -} - struct LruGetResult { cache: LruCacheState, - found: bool, - value: Option -} - -struct LruEntryReport { - found: bool, - key: Option, value: Option } @@ -219,12 +207,13 @@ fn evict_oldest( out } -fn entry_report(cache: LruCacheState, id: int) -> LruEntryReport { - let out: LruEntryReport = if id != 0 => { +fn entry_report(cache: LruCacheState, id: int) -> Option> { + let out: Option> = if id != 0 => { let node: LruNode = &((&cache).nodes[id]); - {found: true, key: Option::Some(node.key.copy()), value: Option::Some(node.value.copy())} + let row: LruEntryRow = {key: node.key.copy(), value: node.value.copy()}; + Option::Some(row) } else => { - {found: false, key: Option::None, value: Option::None} + Option::None }; out } @@ -260,15 +249,15 @@ pub fn has(cache: LruCacheState, key: K) -> bool { } // Returns the cached value without updating recency. -pub fn peek(cache: LruCacheState, key: K) -> LruPeekResult { +pub fn peek(cache: LruCacheState, key: K) -> Option { let state: LruCacheState = cache; let lookup = state.lookup; - let out: LruPeekResult = if lookup.has(key) => { + let out: Option = if lookup.has(key) => { let id = (&lookup)[key]; let node: LruNode = &((&state.nodes)[id]); - {found: true, value: Option::Some(node.value.copy())} + Option::Some(node.value.copy()) } else => { - {found: false, value: Option::None} + Option::None }; out } @@ -311,11 +300,10 @@ pub fn get(cache: LruCacheState, key: K) -> LruGetResult { relinked.nodes ) }; - {cache: next_cache, found: true, value: Option::Some(value)} + {cache: next_cache, value: Option::Some(value)} } else => { { cache: make_cache::(limit, size, next_id, head, tail, lookup, nodes), - found: false, value: Option::None } }; @@ -531,14 +519,14 @@ pub fn entries(cache: LruCacheState) -> [LruEntryRow] { out } -// Returns the oldest cache entry report. -pub fn oldest(cache: LruCacheState) -> LruEntryReport { +// Returns the oldest cache entry, or None when the cache is empty. +pub fn oldest(cache: LruCacheState) -> Option> { let state: LruCacheState = cache; entry_report::(state, state.head) } -// Returns the newest cache entry report. -pub fn newest(cache: LruCacheState) -> LruEntryReport { +// Returns the newest cache entry, or None when the cache is empty. +pub fn newest(cache: LruCacheState) -> Option> { let state: LruCacheState = cache; entry_report::(state, state.tail) } @@ -577,7 +565,6 @@ assert(initial_order[1] == "markets"); assert(initial_order[2] == "build-ops"); let mut world_hit = get::(cache, "world-news"); -assert(world_hit.found); let world_item: FeedCacheItem = world_hit.value.unwrap_or({ day: "", topic: "", @@ -600,20 +587,33 @@ cache = put::( ); assert(has::(cache, "markets") == false); -let world_peek = peek::(cache, "world-news"); -assert(world_peek.value.unwrap_or({ +let world_peek: Option = peek::(cache, "world-news"); +assert(world_peek.unwrap_or({ day: "", topic: "", article_count: 0, slug: "" }).article_count == 5); +let absent_peek: Option = peek::(cache, "markets"); +let absent_peek_is_none = match absent_peek { + Option::Some(item) => false, + Option::None => true, +}; +assert(absent_peek_is_none); + cache = touch::(cache, "build-ops"); -let oldest_entry = oldest::(cache); -let newest_entry = newest::(cache); -let oldest_key: string = oldest_entry.key.unwrap_or("").copy(); -let newest_key: string = newest_entry.key.unwrap_or("").copy(); +let oldest_entry: Option> = oldest::(cache); +let newest_entry: Option> = newest::(cache); +let oldest_key: string = match oldest_entry { + Option::Some(entry) => entry.key.copy(), + Option::None => "", +}; +let newest_key: string = match newest_entry { + Option::Some(entry) => entry.key.copy(), + Option::None => "", +}; assert(oldest_key == "world-news"); assert(newest_key == "build-ops"); diff --git a/pd-vm-wasm/examples/rss-option-result-example.rss b/pd-vm-wasm/examples/rss-option-result-example.rss new file mode 100644 index 00000000..32e593a4 --- /dev/null +++ b/pd-vm-wasm/examples/rss-option-result-example.rss @@ -0,0 +1,243 @@ +// Canonical Unit / Option / Result example. +// +// Every check prints one named line, so downstream tests assert the +// observable result instead of only the process exit status. +fn nothing() {} + +fn explicit_unit() ->() {} + +fn unit_identity(value:()) ->() { + value +} + +fn int_or(value: Option, fallback: int) -> int { + match value { + Option::Some(inner) => inner, + Option::None => fallback, + } +} + +fn option_relay(flag: bool) -> Option { + let value: Option = if flag => { + Option::Some(1) + } else => { + Option::None + }; + let item = value?; + Option::Some(item + 1) +} + +fn checked(flag: bool) -> Result { + let out: Result = if flag => { + Result::Ok(7) + } else => { + Result::Err(9) + }; + out +} + +fn forward(flag: bool) -> Result { + let number = checked(flag)?; + Result::Ok("continued") +} + +fn convert(error: string) -> int { + 7 +} + +fn load() -> Result { + Result::Err("bad") +} + +fn relay_mapped() -> Result { + let value: int = load().map_err(convert)?; + Result::Ok(value) +} + +struct Record { + name: string, + tag: string +} + +// ---- Unit ---- +let unit:() = (); +let unit_from_fn:() = nothing(); +let unit_from_explicit:() = explicit_unit(); +let unit_roundtrip:() = unit_identity(unit); +print("unit_literal={}\n", unit); +print("unit_fn_returns_unit={}\n", unit_from_fn); +print("unit_explicit_annotation={}\n", unit_from_explicit); +print("unit_roundtrip={}\n", unit_roundtrip); + +// ---- Option construction and matching ---- +let some_zero: Option = Option::Some(0); +let none: Option = Option::None; +print("option_some_zero={}\n", int_or(some_zero, -1)); +print("option_none={}\n", int_or(none, -1)); + +let some_false: Option = Option::Some(false); +print("option_some_false={}\n", some_false.unwrap_or(true)); + +let some_empty: Option = Option::Some(""); +let empty_payload: string = some_empty.unwrap_or("missing"); +print("option_some_empty_is_empty={}\n", empty_payload == ""); + +let matched_none: int = match none { + Option::Some(inner) => inner, + Option::None => -2, +}; +print("option_match_none={}\n", matched_none); + +// ---- Option combinators ---- +let mapped: Option = some_zero.map(|value| value + 1); +let flattened: Option = some_zero.and_then(|value| Option::Some(value + 2)); +let recovered_source: Option = Option::None; +let recovered: Option = recovered_source.or_else(|| Option::Some(5)); +let lazy_source: Option = Option::None; +let lazy: int = lazy_source.unwrap_or_else(|| 4); +print("option_map={}\n", mapped.unwrap_or(-1)); +print("option_and_then={}\n", flattened.unwrap_or(-1)); +print("option_or_else={}\n", recovered.unwrap_or(-1)); +print("option_unwrap_or_else={}\n", lazy); + +// ---- Option propagation ---- +print("option_relay_some={}\n", option_relay(true).unwrap_or(-1)); +print("option_relay_none={}\n", option_relay(false).unwrap_or(-1)); + +// ---- Result construction and matching ---- +let ok_value: Result = Result::Ok(21); +let err_value: Result = Result::Err("bad input"); +print("result_is_ok={}\n", ok_value.is_ok()); +print("result_is_err={}\n", err_value.is_err()); + +let matched_ok: int = match ok_value { + Result::Ok(inner) => inner, + Result::Err(error) => -1, +}; +print("result_match_ok={}\n", matched_ok); + +let matched_err: string = match err_value { + Result::Ok(inner) => "ok", + Result::Err(error) => error, +}; +print("result_match_err={}\n", matched_err); + +// ---- Result combinators ---- +let build_ok: Result = Result::Ok(2); +let ok_mapped: Result = build_ok.map(|item| item + 1); +let ok_map_err: Result = ok_mapped.map_err(|error| 8); +let ok_and_then: Result = ok_map_err.and_then(|item| Result::Ok(item * 3)); +let combined_ok: Result = ok_and_then.or_else(|error| Result::Ok(error - 1)); +let ok_path: int = match combined_ok { + Result::Ok(inner) => inner, + Result::Err(error) => -1, +}; +print("result_chain_ok={}\n", ok_path); + +let build_err: Result = Result::Err("bad"); +let err_mapped: Result = build_err.map(|item| item + 1); +let err_map_err: Result = err_mapped.map_err(|error| 8); +let err_and_then: Result = err_map_err.and_then(|item| Result::Ok(item * 3)); +let combined_err: Result = err_and_then.or_else(|error| Result::Ok(error - 1)); +let err_path: int = match combined_err { + Result::Ok(inner) => inner, + Result::Err(error) => -1, +}; +print("result_chain_err={}\n", err_path); + +let eager_ok_source: Result = Result::Ok(11); +let eager_err_source: Result = Result::Err(2); +let lazy_err_source: Result = Result::Err(2); +let eager_ok: int = eager_ok_source.unwrap_or(20); +let eager_err: int = eager_err_source.unwrap_or(30); +let lazy_err: int = lazy_err_source.unwrap_or_else(|error| error + 40); +print("result_unwrap_or_ok={}\n", eager_ok); +print("result_unwrap_or_err={}\n", eager_err); +print("result_unwrap_or_else_err={}\n", lazy_err); + +// ---- Result propagation and error conversion ---- +let forwarded_ok: int = match forward(true) { + Result::Ok(text) => 0, + Result::Err(code) => code, +}; +let forwarded_err: int = match forward(false) { + Result::Ok(text) => 0, + Result::Err(code) => code, +}; +let mapped_error: int = match relay_mapped() { + Result::Ok(value) => value, + Result::Err(code) => code, +}; +print("result_forward_ok={}\n", forwarded_ok); +print("result_forward_err={}\n", forwarded_err); +print("result_map_err_then_try={}\n", mapped_error); + +// ---- Result to Option ---- +let ok_source: Result = Result::Ok(21); +let ok_as_option: Option = ok_source.ok(); +let ok_payload: int = match ok_as_option { + Option::Some(inner) => inner, + Option::None => -1, +}; +print("result_ok_to_option={}\n", ok_payload); + +let err_source: Result = Result::Err("bad input"); +let err_as_option: Option = err_source.err(); +let err_payload: string = match err_as_option { + Option::Some(inner) => inner, + Option::None => "missing", +}; +print("result_err_to_option={}\n", err_payload); + +let ok_err_source: Result = Result::Ok(21); +let absent_err: Option = ok_err_source.err(); +let absent_err_is_none: bool = match absent_err { + Option::Some(inner) => false, + Option::None => true, +}; +print("result_ok_err_is_none={}\n", absent_err_is_none); + +// ---- Fallible projection (`?.`) ---- +let record: Record = {name: "crab", tag: "shell"}; +let projected: string = match record?.name { + Option::Some(value) => value, + Option::None => "missing", +}; +print("project_field={}\n", projected); + +let table: map = {"a": "one"}; +let absent_key: string = match table?.["b"] { + Option::Some(value) => value, + Option::None => "missing", +}; +let present_key: string = match table?.["a"] { + Option::Some(value) => value, + Option::None => "missing", +}; +print("project_absent_key={}\n", absent_key); +print("project_present_key={}\n", present_key); + +struct Grid { + cells: [int] +} + +let grid: Grid = {cells: [10, 20]}; +let grid_cell: int = match grid?.cells?.[1] { + Option::Some(value) => value, + Option::None => -1, +}; +print("project_array_index={}\n", grid_cell); + +let label: string = "abc"; +let label_letter: string = match label?.[1] { + Option::Some(value) => value, + Option::None => "missing", +}; +print("project_string_index={}\n", label_letter); + +let missing_label: string = ""; +let missing_letter: string = match missing_label?.[1] { + Option::Some(value) => value, + Option::None => "missing", +}; +print("project_missing_string_index={}\n", missing_letter); diff --git a/pd-vm-wasm/src/lib.rs b/pd-vm-wasm/src/lib.rs index 6955a850..acb626ec 100644 --- a/pd-vm-wasm/src/lib.rs +++ b/pd-vm-wasm/src/lib.rs @@ -1435,7 +1435,7 @@ mod runtime_tests { compile_source_with_flavor_and_options, }; - fn rss_playground_examples() -> [(&'static str, &'static str); 6] { + fn rss_playground_examples() -> [(&'static str, &'static str); 7] { [ ("Demo", include_str!("../examples/rss-complex-example.rss")), ( @@ -1458,6 +1458,10 @@ mod runtime_tests { "Strings and Regex Example", include_str!("../examples/rss-strings-regex-example.rss"), ), + ( + "Option and Result Example", + include_str!("../examples/rss-option-result-example.rss"), + ), ] } diff --git a/tests/option_result_downstream_examples.rs b/tests/option_result_downstream_examples.rs new file mode 100644 index 00000000..49578927 --- /dev/null +++ b/tests/option_result_downstream_examples.rs @@ -0,0 +1,279 @@ +#![cfg(feature = "runtime")] + +use std::collections::BTreeMap; +use std::path::PathBuf; +use std::sync::{Arc, Mutex}; + +use vm::{CompileSourceFileOptions, Value, Vm, VmStatus, compile_source_file_with_options}; + +mod common; + +const STDLIB_MODULES: &[&str] = &[ + "bytes", + "collections", + "io", + "iter", + "lrucache", + "math", + "parse", + "path", + "strings", +]; + +fn workspace_root() -> PathBuf { + PathBuf::from(env!("CARGO_MANIFEST_DIR")) +} + +fn example_path(name: &str) -> PathBuf { + workspace_root() + .join("pd-vm-wasm") + .join("examples") + .join(name) +} + +fn stdlib_options() -> CompileSourceFileOptions { + let mut options = CompileSourceFileOptions::new(); + for module in STDLIB_MODULES { + let spec = format!("stdlib/rss/{module}.rss"); + let source = std::fs::read_to_string(workspace_root().join(&spec)).unwrap_or_else(|err| { + panic!( + "bundled stdlib module '{spec}' should be readable from the Core checkout: {err}" + ) + }); + options.set_module_override_source(spec, source); + } + options +} + +struct ExampleRun { + lines: Vec, + stack: Vec, +} + +/// Compiles one canonical playground example and executes it with the print +/// sink captured, so the assertions read the example's named output lines. +fn run_example(name: &str) -> ExampleRun { + let path = example_path(name); + let compiled = compile_source_file_with_options(&path, stdlib_options()) + .unwrap_or_else(|err| panic!("example '{name}' should compile: {err}")); + + let output = Arc::new(Mutex::new(Vec::::new())); + let sink_output = Arc::clone(&output); + let mut vm = Vm::new(compiled.program.with_local_count(compiled.locals)); + vm.set_runtime_print_sink(move |rendered| { + sink_output + .lock() + .expect("print sink should lock") + .push(rendered); + }); + for decl in &compiled.functions { + if decl.name == "runtime::sleep" { + vm.bind_function("runtime::sleep", common::make_runtime_sleep()); + } + } + + loop { + match vm.run().expect("example should run") { + VmStatus::Halted => break, + VmStatus::Yielded => continue, + VmStatus::Waiting(_op_id) => vm + .wait_for_host_op_blocking() + .expect("example host operation should complete"), + } + } + + let rendered = output.lock().expect("print sink should lock").clone(); + let lines = rendered + .iter() + .flat_map(|entry| entry.split('\n')) + .filter(|line| !line.is_empty()) + .map(|line| line.to_string()) + .collect(); + + ExampleRun { + lines, + stack: vm.stack().to_vec(), + } +} + +fn named_output(lines: &[String]) -> BTreeMap<&str, &str> { + lines + .iter() + .map(|line| { + line.split_once('=') + .unwrap_or_else(|| panic!("example output line '{line}' should be named")) + }) + .collect() +} + +/// Every named line the canonical Unit/Option/Result example must print. +const OPTION_RESULT_EXPECTED: &[(&str, &str)] = &[ + ("unit_literal", "()"), + ("unit_fn_returns_unit", "()"), + ("unit_explicit_annotation", "()"), + ("unit_roundtrip", "()"), + ("option_some_zero", "0"), + ("option_none", "-1"), + ("option_some_false", "false"), + ("option_some_empty_is_empty", "true"), + ("option_match_none", "-2"), + ("option_map", "1"), + ("option_and_then", "2"), + ("option_or_else", "5"), + ("option_unwrap_or_else", "4"), + ("option_relay_some", "2"), + ("option_relay_none", "-1"), + ("result_is_ok", "true"), + ("result_is_err", "true"), + ("result_match_ok", "21"), + ("result_match_err", "bad input"), + ("result_chain_ok", "9"), + ("result_chain_err", "7"), + ("result_unwrap_or_ok", "11"), + ("result_unwrap_or_err", "30"), + ("result_unwrap_or_else_err", "42"), + ("result_forward_ok", "0"), + ("result_forward_err", "9"), + ("result_map_err_then_try", "7"), + ("result_ok_to_option", "21"), + ("result_err_to_option", "bad input"), + ("result_ok_err_is_none", "true"), + ("project_field", "crab"), + ("project_absent_key", "missing"), + ("project_present_key", "one"), + ("project_array_index", "20"), + ("project_string_index", "b"), + ("project_missing_string_index", "missing"), +]; + +#[test] +fn option_result_example_prints_every_named_contract_line() { + let run = run_example("rss-option-result-example.rss"); + assert_eq!( + run.lines.len(), + OPTION_RESULT_EXPECTED.len(), + "the canonical example must print exactly the named contract lines, got {:?}", + run.lines + ); + + let actual = named_output(&run.lines); + for (name, expected) in OPTION_RESULT_EXPECTED { + let observed = actual + .get(name) + .unwrap_or_else(|| panic!("missing named output line '{name}' in {:?}", run.lines)); + assert_eq!( + observed, expected, + "named output line '{name}' should report '{expected}'" + ); + } + + assert_eq!( + run.stack, + vec![ + Value::string("unit_literal=()\n"), + Value::string("unit_fn_returns_unit=()\n"), + Value::string("unit_explicit_annotation=()\n"), + Value::string("unit_roundtrip=()\n"), + Value::string("option_some_zero=0\n"), + Value::string("option_none=-1\n"), + Value::string("option_some_false=false\n"), + Value::string("option_some_empty_is_empty=true\n"), + Value::string("option_match_none=-2\n"), + Value::string("option_map=1\n"), + Value::string("option_and_then=2\n"), + Value::string("option_or_else=5\n"), + Value::string("option_unwrap_or_else=4\n"), + Value::string("option_relay_some=2\n"), + Value::string("option_relay_none=-1\n"), + Value::string("result_is_ok=true\n"), + Value::string("result_is_err=true\n"), + Value::string("result_match_ok=21\n"), + Value::string("result_match_err=bad input\n"), + Value::string("result_chain_ok=9\n"), + Value::string("result_chain_err=7\n"), + Value::string("result_unwrap_or_ok=11\n"), + Value::string("result_unwrap_or_err=30\n"), + Value::string("result_unwrap_or_else_err=42\n"), + Value::string("result_forward_ok=0\n"), + Value::string("result_forward_err=9\n"), + Value::string("result_map_err_then_try=7\n"), + Value::string("result_ok_to_option=21\n"), + Value::string("result_err_to_option=bad input\n"), + Value::string("result_ok_err_is_none=true\n"), + Value::string("project_field=crab\n"), + Value::string("project_absent_key=missing\n"), + Value::string("project_present_key=one\n"), + Value::string("project_array_index=20\n"), + Value::string("project_string_index=b\n"), + Value::string("project_missing_string_index=missing\n"), + ], + "the canonical example must keep its print order" + ); +} + +#[test] +fn lru_example_reports_option_shaped_entry_output() { + let run = run_example("rss-lrucache-example.rss"); + assert_eq!( + run.lines, + vec![ + "{\"newest_key\":\"build-ops\",\"oldest_key\":\"world-news\",\"order\":[\"world-news\",\"breaking-alerts\",\"build-ops\"],\"total_visible_articles\":18,\"visible_topics\":[\"world news\",\"breaking alerts\",\"build ops\"]}".to_string() + ], + "the LRU example must keep its report shape and values" + ); + assert_eq!( + run.stack, + vec![Value::string( + "{\"newest_key\":\"build-ops\",\"oldest_key\":\"world-news\",\"order\":[\"world-news\",\"breaking-alerts\",\"build-ops\"],\"total_visible_articles\":18,\"visible_topics\":[\"world news\",\"breaking alerts\",\"build ops\"]}" + )], + "the LRU example must return the encoded report" + ); +} + +#[test] +fn lru_example_has_no_legacy_found_wrapper() { + let source = std::fs::read_to_string(example_path("rss-lrucache-example.rss")) + .expect("LRU example should be readable"); + for legacy in ["LruPeekResult", "LruEntryReport", "found:"] { + assert!( + !source.contains(legacy), + "the LRU example must not keep the legacy '{legacy}' shape" + ); + } + for required in [ + "pub fn peek(cache: LruCacheState, key: K) -> Option", + "pub fn oldest(cache: LruCacheState) -> Option>", + "pub fn newest(cache: LruCacheState) -> Option>", + ] { + assert!( + source.contains(required), + "the LRU example must expose '{required}'" + ); + } +} + +#[test] +fn complex_example_treats_runtime_sleep_as_a_unit_statement() { + let source = std::fs::read_to_string(example_path("rss-complex-example.rss")) + .expect("complex example should be readable"); + assert!( + source.contains("\nruntime::sleep(100);\n"), + "runtime::sleep must stay an unbound Unit statement" + ); + assert!( + !source.contains("= runtime::sleep"), + "no local may depend on the runtime::sleep return value" + ); + + let run = run_example("rss-complex-example.rss"); + assert_eq!( + run.lines, + vec!["closure_value is 12".to_string()], + "the complex example must keep its printed output" + ); + assert!( + run.stack.contains(&Value::Null), + "the Unit sleep result must reach the stack as the Null carrier, got {:?}", + run.stack + ); +} From fc8b0c8179640a8ffe460a64b3690e35c2f7eb73 Mon Sep 17 00:00:00 2001 From: fffonion Date: Sat, 14 Nov 2026 22:23:26 +0800 Subject: [PATCH 15/16] test(host): cover runtime_owned_pending on the inferred contract path The dispatch flag is now exercised without a declared contract: a &mut Vm signature still selects StaticStackRuntimeOwned while keeping the inferred schema, an argument-only signature is rejected, and a trybuild case pins the stack-dispatch diagnostic. --- pd-host-function/src/lib.rs | 48 +++++++++++++++++++ ..._owned_pending_requires_stack_signature.rs | 9 ++++ ...ed_pending_requires_stack_signature.stderr | 5 ++ 3 files changed, 62 insertions(+) create mode 100644 pd-host-function/tests/ui/fail/runtime_owned_pending_requires_stack_signature.rs create mode 100644 pd-host-function/tests/ui/fail/runtime_owned_pending_requires_stack_signature.stderr diff --git a/pd-host-function/src/lib.rs b/pd-host-function/src/lib.rs index fffc6c11..eeecc080 100644 --- a/pd-host-function/src/lib.rs +++ b/pd-host-function/src/lib.rs @@ -1979,6 +1979,54 @@ mod tests { ); } + #[test] + fn runtime_owned_pending_flag_applies_to_the_inferred_contract_path() { + let attr: Punctuated = + parse_quote!(name = "runtime::sleep", runtime_owned_pending); + let item: ItemFn = parse_quote! { + /// Suspends until the generic runtime operation registry completes it. + fn sleep(vm: &mut Vm, ms: i64) -> VmResult<()> { + todo!() + } + }; + let expanded = expand_pd_host_function(attr, item).unwrap().to_string(); + assert!( + expanded.contains("HostBindingKind :: StaticStackRuntimeOwned"), + "the dispatch flag must select the pending-owning binding class without a contract: {expanded}" + ); + assert!( + expanded.contains("HostAdapterDescriptor :: StaticStackRuntimeOwned"), + "the dispatch flag must select the pending-owning adapter without a contract: {expanded}" + ); + assert!( + !expanded.contains("declared_host_contract"), + "opting into the pending class must not switch the inferred path to a declared contract: {expanded}" + ); + assert!( + expanded.contains("\"runtime::sleep\""), + "the inferred path must keep the attribute's guest name: {expanded}" + ); + } + + #[test] + fn runtime_owned_pending_flag_rejects_a_non_stack_inferred_signature() { + let attr: Punctuated = + parse_quote!(name = "demo::count", runtime_owned_pending); + let item: ItemFn = parse_quote! { + /// An argument-only adapter cannot own a pending operation. + fn count(ms: i64) -> VmResult { + todo!() + } + }; + let error = expand_pd_host_function(attr, item) + .expect_err("the pending flag must be rejected on an inferred argument-only signature"); + assert_eq!( + error.to_string(), + "runtime_owned_pending requires a stack-dispatch signature (`&mut Vm` or a resource \ + parameter)" + ); + } + #[test] fn stack_signature_without_the_flag_still_generates_a_plain_stack_adapter() { let attr: Punctuated = diff --git a/pd-host-function/tests/ui/fail/runtime_owned_pending_requires_stack_signature.rs b/pd-host-function/tests/ui/fail/runtime_owned_pending_requires_stack_signature.rs new file mode 100644 index 00000000..37b632d6 --- /dev/null +++ b/pd-host-function/tests/ui/fail/runtime_owned_pending_requires_stack_signature.rs @@ -0,0 +1,9 @@ +#![allow(dead_code, unused_imports)] +use pd_host_function::pd_host_function; +use vm::VmResult; +/// The pending dispatch flag needs a stack-dispatch signature. +#[pd_host_function(name = "test::pending", runtime_owned_pending)] +fn pending() -> VmResult { + todo!() +} +fn main() {} diff --git a/pd-host-function/tests/ui/fail/runtime_owned_pending_requires_stack_signature.stderr b/pd-host-function/tests/ui/fail/runtime_owned_pending_requires_stack_signature.stderr new file mode 100644 index 00000000..c6f7df1d --- /dev/null +++ b/pd-host-function/tests/ui/fail/runtime_owned_pending_requires_stack_signature.stderr @@ -0,0 +1,5 @@ +error: runtime_owned_pending requires a stack-dispatch signature (`&mut Vm` or a resource parameter) + --> tests/ui/fail/runtime_owned_pending_requires_stack_signature.rs:6:4 + | +6 | fn pending() -> VmResult { + | ^^^^^^^ From 8db4583298cce9806d617322606537e6344c8b6e Mon Sep 17 00:00:00 2001 From: fffonion Date: Sun, 15 Nov 2026 20:33:12 +0800 Subject: [PATCH 16/16] refactor(wire): expose the VMBC codec without the runtime feature encode_program only needs bytecode and schema types, but both vmbc and its re-exports were gated behind `runtime`, forcing compiler-only consumers such as IronRust to enable the whole VM. Publish vmbc unconditionally and import the program types from `bytecode`; the optional-schema validator it uses moves out from behind the same gate. --- src/host_api.rs | 1 - src/lib.rs | 2 -- src/vmbc.rs | 2 +- 3 files changed, 1 insertion(+), 4 deletions(-) diff --git a/src/host_api.rs b/src/host_api.rs index 5b84bcb2..73dc47bc 100644 --- a/src/host_api.rs +++ b/src/host_api.rs @@ -3974,7 +3974,6 @@ pub fn validate_host_import_schemas( validate_host_import_schema_iter(schemas.iter()) } -#[cfg(feature = "runtime")] pub(crate) fn validate_optional_host_import_schemas( schemas: &[Option], ) -> Result<(), HostSchemaValidationError> { diff --git a/src/lib.rs b/src/lib.rs index 75c32f4a..5bbef6fb 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -24,7 +24,6 @@ pub mod jit { pub mod cli; #[cfg(feature = "runtime")] pub mod vm; -#[cfg(feature = "runtime")] pub mod vmbc; pub use assembler::{AsmParseError, Assembler, AssemblerError, BytecodeBuilder, assemble}; @@ -198,7 +197,6 @@ pub use vm::{ CaptureCertificationStats, CaptureQueryError, CaptureRootState, CheckedResourceCapture, ResourceCaptureRoot, }; -#[cfg(feature = "runtime")] pub use vmbc::{ DisassembleOptions, ValidationError, WireError, decode_program, disassemble_program, disassemble_program_with_options, disassemble_vmbc, disassemble_vmbc_with_options, diff --git a/src/vmbc.rs b/src/vmbc.rs index e651f978..8d9c8bc8 100644 --- a/src/vmbc.rs +++ b/src/vmbc.rs @@ -8,6 +8,7 @@ use crate::bytecode::{ FunctionRegion, MAX_FRAME_LOCAL_COUNT, RetCleanupLocal, RetCleanupPlan, RootCallableBinding, ScriptFunction, TypeMap, ValueType, }; +use crate::bytecode::{HostImport, OpCode, Program, Value}; use crate::compiler::ir::{StructDecl, StructDeclOrigin, TypeSchema}; use crate::debug_info::{ArgInfo, DebugFunction, DebugInfo, LineInfo, LocalInfo}; use crate::host_api::{ @@ -16,7 +17,6 @@ use crate::host_api::{ MAX_HOST_PARAMETER_NAME_LEN, MAX_HOST_RESOURCE_KEY_LEN, MAX_HOST_SCHEMA_DEPTH, MAX_HOST_SCHEMA_NODES, MAX_HOST_SCHEMA_PROPERTIES, ResourceTypeKey, }; -use crate::vm::{HostImport, OpCode, Program, Value}; const MAGIC: [u8; 4] = *b"VMBC"; const VERSION_V14: u16 = 14;