123 lines
4.5 KiB
Markdown
123 lines
4.5 KiB
Markdown
---
|
|
id: PLN-0022
|
|
ticket: frame-composer-public-syscall-surface
|
|
title: Plan - Composer Syscall Domain and Spec Propagation
|
|
status: accepted
|
|
created: 2026-04-17
|
|
completed:
|
|
tags: [gfx, runtime, syscall, abi, spec, isa-core, frame-composer]
|
|
---
|
|
|
|
## Objective
|
|
|
|
Introduce the canonical `composer.*` syscall domain, define `ComposerOpStatus`, and propagate the new public contract through the canonical spec, ABI documentation, and `ISA_CORE` artifacts where affected.
|
|
|
|
## Background
|
|
|
|
`DEC-0015` locks the public orchestration surface on `composer.*`, requires `ComposerOpStatus` for mutating composer-domain calls, and requires propagation beyond code into canonical spec, ABI-facing documentation, and `ISA_CORE` where the public syscall surface is described normatively.
|
|
|
|
## Scope
|
|
|
|
### Included
|
|
- add the `composer` syscall domain and ids
|
|
- define `ComposerOpStatus`
|
|
- remove `gfx.set_sprite(...)` from the public ABI contract
|
|
- update canonical spec documentation for the new public surface
|
|
- update ABI-facing documentation and `ISA_CORE` wherever the public syscall contract is described
|
|
|
|
### Excluded
|
|
- runtime dispatch implementation
|
|
- cartridge and stress program migration
|
|
- final repository-wide CI execution
|
|
|
|
## Execution Steps
|
|
|
|
### Step 1 - Define the public `composer` syscall contract
|
|
|
|
**What:**
|
|
Add the new canonical public syscall surface to the HAL syscall contract.
|
|
|
|
**How:**
|
|
- Extend the syscall enum, registry, metadata, and resolver with a new `composer` domain.
|
|
- Allocate explicit syscall ids for:
|
|
- `composer.bind_scene`
|
|
- `composer.unbind_scene`
|
|
- `composer.set_camera`
|
|
- `composer.emit_sprite`
|
|
- Remove `gfx.set_sprite` from the public syscall contract and registry.
|
|
- Keep syscall metadata explicit for arg/ret slots and capability requirements.
|
|
|
|
**File(s):**
|
|
- `crates/console/prometeu-hal/src/syscalls.rs`
|
|
- `crates/console/prometeu-hal/src/syscalls/domains/*`
|
|
- `crates/console/prometeu-hal/src/syscalls/registry.rs`
|
|
- `crates/console/prometeu-hal/src/syscalls/resolver.rs`
|
|
|
|
### Step 2 - Introduce `ComposerOpStatus`
|
|
|
|
**What:**
|
|
Create the status family for composer-domain mutating operations.
|
|
|
|
**How:**
|
|
- Define a `ComposerOpStatus` type in HAL with explicit operational states needed by:
|
|
- scene binding
|
|
- scene unbinding
|
|
- sprite emission
|
|
- Ensure the enum is semantically composer-domain specific rather than a rename wrapper around `GfxOpStatus`.
|
|
- Update public API references so composer syscalls return `ComposerOpStatus` where required by `DEC-0015`.
|
|
|
|
**File(s):**
|
|
- `crates/console/prometeu-hal/src/*`
|
|
- any shared status exports used by runtime/VM code
|
|
|
|
### Step 3 - Propagate the contract into spec, ABI docs, and `ISA_CORE`
|
|
|
|
**What:**
|
|
Update normative documentation so the public contract no longer describes legacy `gfx.set_sprite`.
|
|
|
|
**How:**
|
|
- Identify canonical spec files that describe VM graphics/composition syscalls.
|
|
- Replace public references to legacy sprite orchestration with `composer.*`.
|
|
- Update ABI-facing docs to pin:
|
|
- namespace
|
|
- names
|
|
- arg order
|
|
- return semantics
|
|
- Update `ISA_CORE` if and where it references the affected syscall surface.
|
|
- Keep published spec content in English per repository policy.
|
|
|
|
**File(s):**
|
|
- canonical spec location(s)
|
|
- ABI contract documentation
|
|
- `ISA_CORE` artifact(s) if affected
|
|
|
|
## Test Requirements
|
|
|
|
### Unit Tests
|
|
- syscall registry tests pin the new `composer.*` entries and reject removed legacy identities
|
|
- `ComposerOpStatus` values are pinned where public return semantics are asserted
|
|
|
|
### Integration Tests
|
|
- declared syscall resolution accepts `composer.*` declarations and rejects removed `gfx.set_sprite`
|
|
|
|
### Manual Verification
|
|
- inspect canonical spec, ABI docs, and `ISA_CORE` references to confirm the public contract matches `DEC-0015`
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] The public syscall registry exposes `composer.bind_scene`, `composer.unbind_scene`, `composer.set_camera`, and `composer.emit_sprite`.
|
|
- [ ] `ComposerOpStatus` exists as the canonical status family for composer-domain mutating syscalls.
|
|
- [ ] `gfx.set_sprite` is removed from the public ABI contract.
|
|
- [ ] Canonical spec documentation is updated to describe `composer.*`.
|
|
- [ ] ABI-facing docs and `ISA_CORE` are updated wherever the affected public surface is documented.
|
|
|
|
## Dependencies
|
|
|
|
- Source decision: `DEC-0015`
|
|
|
|
## Risks
|
|
|
|
- Missing a normative doc location would leave the code and published contract divergent.
|
|
- Reusing `GfxOpStatus` semantics by accident would weaken the service-boundary separation required by `DEC-0015`.
|
|
- Removing the legacy syscall contract incompletely could leave resolver or ABI ambiguity behind.
|