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/docs/host-sdk-descriptors.md b/docs/host-sdk-descriptors.md index c3266a92..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. | @@ -212,26 +212,48 @@ 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. +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` — 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` +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 state before submission. `IoHandleContext`, `SqliteConnectionContext`, and @@ -357,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/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/pd-host-function/src/lib.rs b/pd-host-function/src/lib.rs index a3b94b6d..eeecc080 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,129 @@ 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 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 = + 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/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 { + | ^^^^^^^ diff --git a/pd-vm-wasm/examples/rss-collections-iter-example.rss b/pd-vm-wasm/examples/rss-collections-iter-example.rss index af095f42..2f2078d3 100644 --- a/pd-vm-wasm/examples/rss-collections-iter-example.rss +++ b/pd-vm-wasm/examples/rss-collections-iter-example.rss @@ -77,7 +77,17 @@ 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: 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_matches); +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/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 122ca301..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"), + ), ] } @@ -2205,6 +2209,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 +2358,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/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/io/async_io.rs b/src/builtins/runtime/io/async_io.rs index b407ec37..c84ba2bd 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)] @@ -335,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?; @@ -383,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<()> { @@ -582,12 +629,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 +677,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 +711,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 +774,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 +788,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 +814,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 +839,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 +874,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>> { + // 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 @@ -800,7 +941,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 +1057,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 +1083,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 +1101,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 }) } @@ -993,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"), @@ -1019,6 +1174,214 @@ 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" + ); + } + + /// 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(); + 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/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/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/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], 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/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/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; 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/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/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/bytes.rss b/stdlib/tests/bytes.rss index 3dfd9d1b..a0239672 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_matches: bool = match bytes_std::index_of(hello, builtin_bytes::from_utf8("")) { + Option::Some(value) => value == 0, + Option::None => false, +}; +assert(empty_needle_matches); + +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_matches); + +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_matches); + +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); 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/stdlib/tests/lrucache.rss b/stdlib/tests/lrucache.rss index dec49e7b..af02cb9a 100644 --- a/stdlib/tests/lrucache.rss +++ b/stdlib/tests/lrucache.rss @@ -18,32 +18,55 @@ 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); -assert(peeked_value == 1); +// W01: `peek` reports presence with `Option` and never promotes recency. +let peeked_matches: bool = match peek::(cache, "a") { + Option::Some(value) => value == 1, + Option::None => false, +}; +assert(peeked_matches); +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); -assert(accessed_value == 1); +let accessed_matches: bool = match accessed.value { + Option::Some(value) => value == 1, + Option::None => false, +}; +assert(accessed_matches); 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"); +match oldest::(cache) { + Option::Some(row) => assert(row.value == 2), + Option::None => assert(false), +}; + +let newest_key = match newest::(cache) { + Option::Some(row) => row.key, + Option::None => "missing", +}; +assert(newest_key == "a"); +match newest::(cache) { + Option::Some(row) => assert(row.value == 1), + Option::None => assert(false), +}; cache = put::(cache, "c", 3); let mut after_evict = keys::(cache); @@ -62,12 +85,17 @@ 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); +match peek::(cache, "a") { + Option::Some(value) => assert(value == 10), + Option::None => assert(false), +}; 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 +128,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 +149,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 +176,64 @@ 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(); +match oldest::(feed_cache) { + Option::Some(row) => assert(row.key == 8), + Option::None => assert(false), +}; +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(); +match newest::(feed_cache) { + Option::Some(row) => assert(row.key == 7), + Option::None => assert(false), +}; +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; diff --git a/tests/builtins/io_async_tests.rs b/tests/builtins/io_async_tests.rs index baff78c2..6ebdc294 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,164 @@ 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); +} + +/// 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" + ); +} + +/// 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() + .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/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/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/host_descriptor_effect_tests.rs b/tests/host_descriptor_effect_tests.rs index 632d2508..5e59104a 100644 --- a/tests/host_descriptor_effect_tests.rs +++ b/tests/host_descriptor_effect_tests.rs @@ -1672,3 +1672,87 @@ 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"); + + // 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()]) + .expect("runtime-owned descriptors install without a module wrapper"); + assert!(aggregate.contains_name("demo::await_signal")); +} diff --git a/tests/io_descriptor_install_tests.rs b/tests/io_descriptor_install_tests.rs index 371551ed..4ee9e10f 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() @@ -671,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 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!( @@ -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() )); 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 + ); +} 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/standard_host_descriptor_arch_tests.rs b/tests/standard_host_descriptor_arch_tests.rs index 395c58dd..c38661ae 100644 --- a/tests/standard_host_descriptor_arch_tests.rs +++ b/tests/standard_host_descriptor_arch_tests.rs @@ -23,16 +23,28 @@ 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. 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. +// +// 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 = "b704c1210e3ab4a4"; -const STANDARD_CATALOG_FINGERPRINT_SQLITE: &str = "6cad8e423debdebd"; -const STANDARD_CATALOG_FINGERPRINT_HTTP: &str = "c9e705595cfd2cc7"; -const STANDARD_CATALOG_FINGERPRINT_BASE: &str = "8254b00d727494b4"; -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"; -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..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))); @@ -1820,7 +1831,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 +1844,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/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); 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] 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",