PR001: sync core syscall specs (16/16a) with status-first policy

This commit is contained in:
2026-03-24 13:40:50 +00:00
parent 14acd47421
commit b241db7011
2 changed files with 21 additions and 0 deletions
@@ -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. 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) ## 7 Syscalls as Callable Entities (Not First-Class)
Syscalls behave like call sites, not like first-class guest values. Syscalls behave like call sites, not like first-class guest values.
@@ -43,6 +43,20 @@ Examples:
- audio voice unavailable; - audio voice unavailable;
- persistent storage full. - 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 ## 2 Capability System
Each syscall requires a declared capability. 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. - [`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. - [`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. - [`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.