---
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.