prometeu-runtime/discussion/workflow/plans/PLN-0022-composer-syscall-domain-and-spec-propagation.md

id	ticket	title	status	created	completed	tags
PLN-0022	frame-composer-public-syscall-surface	Plan - Composer Syscall Domain and Spec Propagation	accepted	2026-04-17		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.