From b241db701151022b7bae917123f0121f48ce80c1 Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Mon, 9 Mar 2026 06:53:11 +0000 Subject: [PATCH] PR001: sync core syscall specs (16/16a) with status-first policy --- docs/runtime/specs/16-host-abi-and-syscalls.md | 6 ++++++ docs/runtime/specs/16a-syscall-policies.md | 15 +++++++++++++++ 2 files changed, 21 insertions(+) diff --git a/docs/runtime/specs/16-host-abi-and-syscalls.md b/docs/runtime/specs/16-host-abi-and-syscalls.md index f4b8bb20..81923b01 100644 --- a/docs/runtime/specs/16-host-abi-and-syscalls.md +++ b/docs/runtime/specs/16-host-abi-and-syscalls.md @@ -150,6 +150,12 @@ After execution, the syscall leaves exactly `ret_slots` values on the stack. Composite results use multiple stack slots rather than implicit hidden structures. +Return shape must also follow the operational policy in [`16a-syscall-policies.md`](16a-syscall-policies.md): + +- operations with observable operational failure paths should expose an explicit `status:int` return; +- operations with no real operational error path may remain `void` (`ret_slots = 0`); +- stack shape remains strict in both cases and must match syscall metadata exactly. + ## 7 Syscalls as Callable Entities (Not First-Class) Syscalls behave like call sites, not like first-class guest values. diff --git a/docs/runtime/specs/16a-syscall-policies.md b/docs/runtime/specs/16a-syscall-policies.md index 62e4782c..709be357 100644 --- a/docs/runtime/specs/16a-syscall-policies.md +++ b/docs/runtime/specs/16a-syscall-policies.md @@ -43,6 +43,20 @@ Examples: - audio voice unavailable; - persistent storage full. +### Return shape policy (`void` vs `status`) + +This policy is normative: + +- if an operation has observable operational failure modes, it should return `status:int` explicitly; +- if an operation has no real operational error path, it may remain `void` (`ret_slots = 0`); +- `status` coding is domain-owned and may differ by operation, but must be deterministic and documented. + +### No-op policy + +Silent no-op is not allowed when an operation can fail operationally in a guest-observable way. + +In those cases, the runtime must return explicit `status` instead of masking failure as implicit success. + ## 2 Capability System Each syscall requires a declared capability. @@ -121,3 +135,4 @@ This keeps the host ABI compatible with a deterministic frame machine. - [`16-host-abi-and-syscalls.md`](16-host-abi-and-syscalls.md) defines the structural ABI. - [`03-memory-stack-heap-and-allocation.md`](03-memory-stack-heap-and-allocation.md) defines VM heap ownership and handles. - [`10-debug-inspection-and-profiling.md`](10-debug-inspection-and-profiling.md) defines visibility of cost and diagnostics. +- domain chapters (e.g. `04`, `05`, `15`) define per-operation status tables.