implements PLN-0022

This commit is contained in:
2026-04-17 17:49:18 +01:00
parent 240fe65da7
commit dd90ff812c
13 changed files with 179 additions and 111 deletions
+39 -34
View File
@@ -536,7 +536,12 @@ The system can measure:
## 19. Syscall Return and Fault Policy
`gfx` follows status-first policy for operations with operational failure modes.
Graphics-related public ABI in v1 is split between:
- `gfx.*` for direct drawing/backend-oriented operations;
- `composer.*` for frame orchestration operations.
Only operations with real operational rejection paths return explicit status values.
Fault boundary:
@@ -544,50 +549,50 @@ Fault boundary:
- `status`: operational failure;
- `Panic`: internal runtime invariant break only.
### 19.1 `gfx.set_sprite`
### 19.1 Return-shape matrix in v1
Return-shape matrix in v1:
| Syscall | Return | Policy basis |
| ----------------------- | ------------- | --------------------------------------------------- |
| `gfx.clear` | `void` | no real operational failure path in v1 |
| `gfx.fill_rect` | `void` | no real operational failure path in v1 |
| `gfx.draw_line` | `void` | no real operational failure path in v1 |
| `gfx.draw_circle` | `void` | no real operational failure path in v1 |
| `gfx.draw_disc` | `void` | no real operational failure path in v1 |
| `gfx.draw_square` | `void` | no real operational failure path in v1 |
| `gfx.draw_text` | `void` | no real operational failure path in v1 |
| `gfx.clear_565` | `void` | no real operational failure path in v1 |
| `composer.bind_scene` | `status:int` | explicit orchestration-domain operational result |
| `composer.unbind_scene` | `status:int` | explicit orchestration-domain operational result |
| `composer.set_camera` | `void` | no real operational failure path in v1 |
| `composer.emit_sprite` | `status:int` | explicit orchestration-domain operational rejection |
| Syscall | Return | Policy basis |
| ------------------ | ------------- | ---------------------------------------------------- |
| `gfx.clear` | `void` | no real operational failure path in v1 |
| `gfx.fill_rect` | `void` | no real operational failure path in v1 |
| `gfx.draw_line` | `void` | no real operational failure path in v1 |
| `gfx.draw_circle` | `void` | no real operational failure path in v1 |
| `gfx.draw_disc` | `void` | no real operational failure path in v1 |
| `gfx.draw_square` | `void` | no real operational failure path in v1 |
| `gfx.set_sprite` | `status:int` | operational rejection must be explicit |
| `gfx.draw_text` | `void` | no real operational failure path in v1 |
| `gfx.clear_565` | `void` | no real operational failure path in v1 |
### 19.2 `composer.emit_sprite`
Only `gfx.set_sprite` is status-returning in v1.
All other `gfx` syscalls remain `void` unless a future domain revision introduces a real operational failure path.
### 19.2 `gfx.set_sprite`
`gfx.set_sprite` returns `status:int`.
`composer.emit_sprite` returns `status:int`.
ABI:
1. `bank_id: int` — index of the tile bank
2. `index: int` — sprite index (0..511)
1. `glyph_id: int` — glyph index within the bank
2. `palette_id: int` — palette index
3. `x: int` — x coordinate
4. `y: int` — y coordinate
5. `tile_id: int` — tile index within the bank
6. `palette_id: int` — palette index (0..63)
7. `active: bool` — visibility toggle
8. `flip_x: bool` — horizontal flip
9. `flip_y: bool` — vertical flip
10. `priority: int` — layer priority (0..4)
5. `layer: int` — composition layer reference
6. `bank_id: int` — glyph bank index
7. `flip_x: bool` — horizontal flip
8. `flip_y: bool` — vertical flip
9. `priority: int` — within-layer ordering priority
Minimum status table:
- `0` = `OK`
- `2` = `INVALID_SPRITE_INDEX`
- `3` = `INVALID_ARG_RANGE`
- `4` = `BANK_INVALID`
- `1` = `SCENE_UNAVAILABLE`
- `2` = `INVALID_ARG_RANGE`
- `3` = `BANK_INVALID`
- `4` = `LAYER_INVALID`
- `5` = `SPRITE_OVERFLOW`
Operational notes:
- no fallback to default bank when the sprite bank id cannot be resolved;
- no silent no-op for invalid index/range;
- `palette_id` and `priority` must be validated against runtime-supported ranges.
- the canonical public sprite contract is frame-emission based;
- no caller-provided sprite index exists in the v1 canonical ABI;
- no `active` flag exists in the v1 canonical ABI;
- overflow remains non-fatal and must not escalate to trap in v1.
@@ -39,6 +39,7 @@ Example:
```
("gfx", "present", 1)
("audio", "play", 2)
("composer", "emit_sprite", 1)
```
This identity is:
@@ -198,6 +199,24 @@ For `asset.load`:
- `slot` is the target slot index;
- bank kind is resolved from `asset_table` by `asset_id`, not supplied by the caller.
### Composition surface (`composer`, v1)
The canonical frame-orchestration public ABI uses module `composer`.
Canonical operations in v1 are:
- `composer.bind_scene(bank_id) -> (status)`
- `composer.unbind_scene() -> (status)`
- `composer.set_camera(x, y) -> void`
- `composer.emit_sprite(glyph_id, palette_id, x, y, layer, bank_id, flip_x, flip_y, priority) -> (status)`
For mutating composer operations:
- `status` is a `ComposerOpStatus` value;
- `bind_scene`, `unbind_scene`, and `emit_sprite` are status-returning;
- `set_camera` remains `void` in v1;
- no caller-provided sprite index or `active` flag is part of the canonical contract.
## 7 Syscalls as Callable Entities (Not First-Class)
Syscalls behave like call sites, not like first-class guest values.
+3
View File
@@ -85,6 +85,9 @@ Example:
- `asset.load` currently resolves with `arg_slots = 2` and `ret_slots = 2`.
- The canonical stack contract is `asset_id, slot -> status, handle`.
- Callers do not provide an explicit asset kind; the runtime derives it from `asset_table`.
- `composer.bind_scene` resolves with `arg_slots = 1` and `ret_slots = 1`.
- The canonical stack contract is `bank_id -> status`.
- `composer.emit_sprite` resolves with `arg_slots = 9` and `ret_slots = 1`.
#### Canonical Intrinsic Registry Artifact