# 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.

## 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.

## 2 Capability System

Each syscall requires a declared capability.

Example groups:

- `gfx`
- `audio`
- `asset`
- `memcard`

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.

## 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.