PR002: implement gfx status-first contract for set_sprite

This commit is contained in:
2026-03-24 13:40:50 +00:00
parent b241db7011
commit fe6931d420
3 changed files with 58 additions and 15 deletions
+29
View File
@@ -511,3 +511,32 @@ The system can measure:
- `palettes_referenced_this_frame`
- `tiles_drawn_by_palette_id`
- `sprites_drawn_by_palette_id`
---
## 19. Syscall Return and Fault Policy
`gfx` 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 runtime invariant break only.
### 19.1 `gfx.set_sprite`
`gfx.set_sprite` returns `status:int`.
Minimum status table:
- `0` = `OK`
- `1` = `ASSET_NOT_FOUND`
- `2` = `INVALID_SPRITE_INDEX`
- `3` = `INVALID_ARG_RANGE`
Operational notes:
- no fallback to default bank when the sprite asset name cannot be resolved;
- no silent no-op for invalid index/range;
- `palette_id` and `priority` must be validated against runtime-supported ranges.