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

### 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`](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.