prometeu-runtime/discussion/workflow/plans/PLN-0024-composer-cartridge-tooling-and-regression-migration.md

id	ticket	title	status	created	completed	tags
PLN-0024	frame-composer-public-syscall-surface	Plan - Composer Cartridge, Tooling, and Regression Migration	accepted	2026-04-17		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.