108 lines
3.6 KiB
Markdown
108 lines
3.6 KiB
Markdown
---
|
|
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.
|