prometeu-runtime/docs/runtime/specs/16a-syscall-policies.md

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, which defines the structural ABI itself.

1 Error Model: Faults vs Status Returns

Syscalls use a 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 conditions should be represented as values in return slots.

Examples:

• asset not yet loaded;
• 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.

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.

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 defines the structural ABI.
• 03-memory-stack-heap-and-allocation.md defines VM heap ownership and handles.
• 10-debug-inspection-and-profiling.md defines visibility of cost and diagnostics.
• domain chapters (e.g. 04, 05, 15) define per-operation status tables.