discussion framework migration
This commit is contained in:
@@ -0,0 +1,162 @@
|
||||
# Syscall Policies
|
||||
|
||||
Domain: host ABI operational policy
|
||||
Function: normative
|
||||
|
||||
This chapter defines the operational policies that sit on top of the host ABI.
|
||||
|
||||
It complements [`16-host-abi-and-syscalls.md`](16-host-abi-and-syscalls.md), which defines the structural ABI itself.
|
||||
|
||||
Unless a domain chapter explicitly narrows behavior further, this chapter is the transversal policy for all syscalls in v1.
|
||||
|
||||
## 1 Error Model: Faults vs Status Returns
|
||||
|
||||
Syscalls use a status-first hybrid model.
|
||||
|
||||
### Fault conditions
|
||||
|
||||
The VM faults when contract rules are violated, for example:
|
||||
|
||||
- invalid syscall id;
|
||||
- unresolved canonical identity;
|
||||
- missing required capability;
|
||||
- insufficient argument slots;
|
||||
- invalid or dead heap handle.
|
||||
|
||||
These are not ordinary domain statuses.
|
||||
|
||||
Faults are split into two runtime classes:
|
||||
|
||||
- `Trap`: guest-visible structural violation (ABI misuse / invalid call shape).
|
||||
- `Panic`: runtime invariant break (internal inconsistency).
|
||||
|
||||
`Unavailable` is not a canonical fault class in this policy model.
|
||||
|
||||
- operational unavailability should be represented as `status`;
|
||||
- structural host/runtime collapse should be treated as `Panic`.
|
||||
|
||||
### Status returns
|
||||
|
||||
Normal operational success and operational failure conditions should be represented as values in return slots.
|
||||
|
||||
Examples:
|
||||
|
||||
- asset not yet loaded;
|
||||
- audio voice unavailable;
|
||||
- persistent storage full.
|
||||
|
||||
When a syscall returns `status`, that `status:int` occupies the first return slot.
|
||||
Any additional payload is domain-defined and follows that leading status slot.
|
||||
|
||||
### Return shape policy (`void` vs `status`)
|
||||
|
||||
This policy is normative:
|
||||
|
||||
- if an operation has observable operational failure modes, it must return `status:int` explicitly;
|
||||
- if an operation can be operationally rejected, ignored, deferred with failure, or conclude with guest-observable `no_effect`, it is not eligible to remain `void`;
|
||||
- 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.
|
||||
|
||||
Practical rule:
|
||||
|
||||
- `void` is allowed only for operations whose non-fault path is effectively unconditional success;
|
||||
- any operation with a meaningful operational non-success outcome must surface that outcome through `status`, not through absence of return values.
|
||||
|
||||
### 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.
|
||||
|
||||
Implicit fallback is also forbidden when it hides an operational error or state rejection that the guest could observe or reason about.
|
||||
|
||||
This means operational problems must not be reclassified as:
|
||||
|
||||
- silent success;
|
||||
- silent ignore;
|
||||
- `Trap`, when the failure is not structural;
|
||||
- `Panic`, when the failure is not an internal invariant break.
|
||||
|
||||
## 2 Capability System
|
||||
|
||||
Each syscall requires a declared capability.
|
||||
|
||||
Example groups:
|
||||
|
||||
- `gfx`
|
||||
- `audio`
|
||||
- `asset`
|
||||
- `fs` (includes game memcard module `mem` in v1)
|
||||
|
||||
Capability checks exist to constrain which host-managed surfaces a cartridge may use.
|
||||
|
||||
Input in v1 is VM-owned intrinsic surface and is not capability-gated through syscall policy.
|
||||
|
||||
Game memcard operations (`mem.*`) are status-first and use `fs` capability in v1.
|
||||
`mem` remains layered on runtime `fs`; no parallel persistence channel is introduced.
|
||||
Domain surface, status catalog and slot semantics are defined in [`08-save-memory-and-memcard.md`](08-save-memory-and-memcard.md).
|
||||
|
||||
## 3 Interaction with the Garbage Collector
|
||||
|
||||
The VM heap and host-managed memory are separate.
|
||||
|
||||
### Heap vs host memory
|
||||
|
||||
| Memory | Managed by | GC scanned |
|
||||
| --------------- | ---------- | ---------- |
|
||||
| VM heap objects | VM GC | Yes |
|
||||
| Asset banks | Host | No |
|
||||
| Audio buffers | Host | No |
|
||||
| Framebuffers | Host | No |
|
||||
|
||||
### Host root rule
|
||||
|
||||
If the host stores a VM heap handle beyond the duration of the syscall, that handle must be treated as a host root according to the runtime contract.
|
||||
|
||||
This rule applies to VM heap objects, not to host-owned asset identifiers or primitive values.
|
||||
|
||||
## 4 Determinism Rules
|
||||
|
||||
Syscalls must obey machine-level determinism.
|
||||
|
||||
Forbidden patterns:
|
||||
|
||||
- reading wall-clock time as gameplay state;
|
||||
- non-deterministic OS access in the gameplay contract;
|
||||
- blocking I/O in the execution slice.
|
||||
|
||||
Allowed patterns:
|
||||
|
||||
- frame-based timing;
|
||||
- request + poll status models;
|
||||
- deterministic event publication at frame boundaries.
|
||||
|
||||
## 5 Cost Model and Budgeting
|
||||
|
||||
Each syscall contributes to frame cost.
|
||||
|
||||
The system may account for:
|
||||
|
||||
- syscall count;
|
||||
- cycles spent in syscalls;
|
||||
- allocations triggered by syscalls.
|
||||
|
||||
This keeps host interaction visible in certification, telemetry, and profiling.
|
||||
|
||||
## 6 Blocking and Long Operations
|
||||
|
||||
Syscalls must not block the execution model.
|
||||
|
||||
Long operations should follow explicit staged patterns such as:
|
||||
|
||||
1. request;
|
||||
2. status polling or completion observation.
|
||||
|
||||
This keeps the host ABI compatible with a deterministic frame machine.
|
||||
|
||||
## 7 Relationship to Other Specs
|
||||
|
||||
- [`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.
|
||||
Reference in New Issue
Block a user