---
id: PLN-0024
ticket: frame-composer-public-syscall-surface
title: Plan - Composer Cartridge, Tooling, and Regression Migration
status: accepted
created: 2026-04-17
completed:
tags: [runtime, bytecode, tooling, stress, regression, frame-composer]
---

## Objective

Migrate bytecode declarations, cartridges, stress tooling, and regression coverage from legacy public sprite orchestration to the canonical `composer.*` surface.

## Background

`DEC-0015` requires the new public composer-domain ABI to land without leaving `gfx.set_sprite` as a fallback. That means the migration must cover the generated bytecode, test cartridges, and stress tooling that still assume the old public contract.

## Scope

### Included
- bytecode declaration updates for `composer.*`
- cartridge and stress generator migration
- regression coverage for the public composer-domain path
- removal of legacy syscall usage from test and tooling surfaces

### Excluded
- canonical spec propagation
- runtime dispatch implementation
- final repository-wide CI closure

## Execution Steps

### Step 1 - Migrate declared syscall users and fixtures

**What:**
Update code and fixtures that declare public syscalls so they target `composer.*`.

**How:**
- Replace legacy public sprite syscall declarations with composer-domain declarations.
- Update ABI expectations in bytecode-related tests and fixtures.
- Ensure removal of `gfx.set_sprite` is reflected in any declaration validation snapshots.

**File(s):**
- bytecode tests and fixtures
- syscall declaration users across runtime and tools

### Step 2 - Migrate stress and cartridge tooling

**What:**
Make the stress cartridge and related generators exercise the canonical public frame path.

**How:**
- Update `pbxgen-stress` and any cartridge generators to declare and call `composer.*`.
- Replace legacy sprite-path usage with `composer.emit_sprite`.
- Add scene bind and camera usage where needed so the stress path reaches the real canonical pipeline.

**File(s):**
- `crates/tools/pbxgen-stress/src/*`
- `test-cartridges/stress-console/*`
- related scripts such as `scripts/run-stress.sh`

### Step 3 - Expand regression coverage around the public path

**What:**
Lock the new public orchestration contract with regression tests.

**How:**
- Add tests that cover:
  - composer-domain declaration resolution
  - public bind/unbind/camera/emit behavior
  - scene rendering through the public path
  - stress/tooling integration using `composer.*`
- Ensure no regression fixture still relies on removed `gfx.set_sprite`.

**File(s):**
- runtime tests
- HAL syscall tests
- tooling tests where available

## Test Requirements

### Unit Tests
- bytecode and syscall declaration tests pin `composer.*` names and slot counts

### Integration Tests
- stress or cartridge-facing tests exercise scene bind, camera set, and sprite emit through `composer.*`
- regression fixtures fail if `gfx.set_sprite` is reintroduced

### Manual Verification
- inspect generated stress cartridge declarations and program behavior to confirm the public path is truly composer-domain based

## Acceptance Criteria

- [ ] Bytecode declarations and fixtures use `composer.*` instead of legacy public sprite orchestration.
- [ ] Stress tooling and test cartridges exercise the canonical public `FrameComposer` path.
- [ ] Regression coverage protects against fallback to `gfx.set_sprite`.

## Dependencies

- Depends on `PLN-0022` and `PLN-0023`
- Source decision: `DEC-0015`

## Risks

- Partial cartridge/tooling migration could leave the repository with hidden legacy public ABI usage.
- Stress tooling may appear to pass while still missing scene/camera coverage if it only migrates sprite calls.