PR003: implement audio status-first returns for play operations

This commit is contained in:
2026-03-24 13:40:50 +00:00
parent fe6931d420
commit 998252aa25
6 changed files with 117 additions and 36 deletions
+32
View File
@@ -174,3 +174,35 @@ voices_active: 9
mix_cycles: 410
audio_commands: 6
```
## 11 Syscall Return and Fault Policy
`audio` follows status-first policy for operations with operational failure modes.
Fault boundary:
- `Trap`: structural ABI misuse (type/arity/capability/shape mismatch);
- `status`: operational failure;
- `Panic`: internal invariant break only.
### 11.1 MVP return shape
In the current MVP:
- `audio.play` returns `status:int`;
- `audio.play_sample` returns `status:int`.
### 11.2 Minimum status table for `play`/`play_sample`
- `0` = `OK`
- `1` = `VOICE_INVALID`
- `2` = `SAMPLE_NOT_FOUND`
- `3` = `ARG_RANGE_INVALID`
- `4` = `ASSET_NOT_FOUND`
- `5` = `NO_EFFECT`
Operational rules:
- no fallback to default bank when an asset cannot be resolved;
- no silent no-op for invalid `voice_id`;
- invalid numeric ranges (e.g. `volume`, `pan`, `pitch`) must return explicit status.