113 lines
3.8 KiB
Markdown
113 lines
3.8 KiB
Markdown
---
|
|
id: PLN-0023
|
|
ticket: frame-composer-public-syscall-surface
|
|
title: Plan - Composer Runtime Dispatch and Legacy Removal
|
|
status: accepted
|
|
created: 2026-04-17
|
|
completed:
|
|
tags: [runtime, syscall, frame-composer, dispatch, migration]
|
|
---
|
|
|
|
## Objective
|
|
|
|
Route the new public `composer.*` syscalls through `FrameComposer`, remove legacy `gfx.set_sprite` handling, and align runtime-side operational behavior with `DEC-0015`.
|
|
|
|
## Background
|
|
|
|
`DEC-0015` closes the public contract around `composer.*` and requires that `gfx.set_sprite` be removed completely rather than kept as a compatibility shim. The internal `FrameComposer` ownership model already exists from `DEC-0014` and plans `PLN-0017` through `PLN-0021`.
|
|
|
|
## Scope
|
|
|
|
### Included
|
|
- runtime syscall dispatch for `composer.*`
|
|
- operational mapping from syscall args to `FrameComposer`
|
|
- removal of legacy `gfx.set_sprite` runtime handling
|
|
- runtime-facing tests for composer-domain behavior
|
|
|
|
### Excluded
|
|
- spec and ABI doc propagation
|
|
- cartridge/tooling migration
|
|
- final `make ci` closure
|
|
|
|
## Execution Steps
|
|
|
|
### Step 1 - Add runtime dispatch for `composer.*`
|
|
|
|
**What:**
|
|
Teach VM runtime dispatch to call `FrameComposer` through the new public contract.
|
|
|
|
**How:**
|
|
- Add dispatch arms for:
|
|
- `composer.bind_scene`
|
|
- `composer.unbind_scene`
|
|
- `composer.set_camera`
|
|
- `composer.emit_sprite`
|
|
- Parse arguments exactly as pinned by the HAL metadata.
|
|
- Return `ComposerOpStatus` for mutating composer-domain syscalls.
|
|
|
|
**File(s):**
|
|
- `crates/console/prometeu-system/src/virtual_machine_runtime/dispatch.rs`
|
|
- any adjacent runtime helpers
|
|
|
|
### Step 2 - Map operational outcomes cleanly onto `ComposerOpStatus`
|
|
|
|
**What:**
|
|
Make runtime failures and normal outcomes reflect the new composer-domain status model.
|
|
|
|
**How:**
|
|
- Bind runtime-side operational checks to status outcomes such as:
|
|
- scene bank unavailable
|
|
- bank invalid
|
|
- argument range invalid
|
|
- layer invalid
|
|
- sprite overflow if surfaced operationally
|
|
- Keep non-fatal overflow behavior aligned with `DEC-0015`.
|
|
|
|
**File(s):**
|
|
- `crates/console/prometeu-system/src/virtual_machine_runtime/dispatch.rs`
|
|
- `crates/console/prometeu-hal/src/*` as needed for shared status meaning
|
|
|
|
### Step 3 - Remove legacy `gfx.set_sprite` runtime support
|
|
|
|
**What:**
|
|
Delete the old public runtime path for slot-style sprite submission.
|
|
|
|
**How:**
|
|
- Remove dispatch support for `gfx.set_sprite`.
|
|
- Remove runtime assumptions about `active`, caller-provided indices, and legacy sprite ABI shape.
|
|
- Keep no private compatibility hook behind the public API.
|
|
|
|
**File(s):**
|
|
- `crates/console/prometeu-system/src/virtual_machine_runtime/dispatch.rs`
|
|
- adjacent tests and public syscall references
|
|
|
|
## Test Requirements
|
|
|
|
### Unit Tests
|
|
- runtime dispatch returns `ComposerOpStatus` for bind, unbind, and emit operations
|
|
- `composer.set_camera` stores the minimal V1 camera coordinates correctly
|
|
|
|
### Integration Tests
|
|
- a VM/runtime test can bind a scene, set camera, emit a sprite, reach `FRAME_SYNC`, and render through the canonical frame path
|
|
- public runtime behavior rejects removed `gfx.set_sprite` declarations/calls
|
|
|
|
### Manual Verification
|
|
- inspect dispatch code to confirm all public orchestration now routes through `FrameComposer` rather than a legacy `gfx` sprite syscall path
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] Runtime dispatch supports all canonical `composer.*` syscalls.
|
|
- [ ] Mutating composer-domain calls return `ComposerOpStatus`.
|
|
- [ ] `gfx.set_sprite` is removed from runtime public handling.
|
|
- [ ] Runtime tests cover scene bind, camera set, sprite emit, and frame rendering through the public path.
|
|
|
|
## Dependencies
|
|
|
|
- Depends on `PLN-0022`
|
|
- Source decision: `DEC-0015`
|
|
|
|
## Risks
|
|
|
|
- Removing legacy handling before all runtime references are migrated can strand tests or bytecode fixtures.
|
|
- Poor `ComposerOpStatus` mapping could collapse useful operational distinctions into generic failures.
|