---
id: PLN-0054
ticket: studio-frame-composer-syscall-and-sprite-alignment
title: Compiler, Frontend, and Conformance Migration to `composer.emit_sprite`
status: review
created: 2026-04-18
completed:
tags:
  - studio
  - compiler
  - pbs
  - conformance
  - composer
  - sprites
---

## Objective

Migrate compiler/frontend/conformance behavior from the retired `Gfx.set_sprite` path to the canonical `Composer.emit_sprite` path, with no compatibility fallback.

## Background

Once the stdlib and spec surface move to `@sdk:composer`, the compiler and frontend test suite must stop asserting `LowGfx.set_sprite` metadata and `Gfx.set_sprite` callsites. `DEC-0027` forbids internal retargeting that preserves the old public API, so the implementation and conformance layers must change the visible source contract as well as the lowered host identity.

## Scope

### Included
- Update PBS frontend tests that import `@sdk:gfx` for sprite composition.
- Update SDK-interface and host-metadata assertions from `LowGfx`/`set_sprite` to `LowComposer`/`emit_sprite`.
- Update any compiler-side conformance or bytecode expectations that observe host declaration metadata for sprite emission.
- Add regression coverage that proves sprite emission lowers to the `composer` host identity and that `Gfx.set_sprite` is no longer available.

### Excluded
- Repository sample project migration outside compiler-facing fixtures.
- Runtime behavior changes in `../runtime`.
- Scene/camera composer APIs.

## Execution Steps

### Step 1 - Update frontend phase tests to the new imports and calls

**What:**
Rewrite PBS frontend phase coverage that still imports `Gfx` for sprite composition.

**How:**
Replace sprite-oriented `import { Gfx } from @sdk:gfx;` snippets with `import { Composer } from @sdk:composer;` where the test is validating sprite composition. Rewrite callsites from `Gfx.set_sprite(...)` to `Composer.emit_sprite(...)`. Keep pure primitive tests on `@sdk:gfx` unchanged.

**File(s):**
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/services/PBSFrontendPhaseServiceTest.java`

### Step 2 - Update SDK-interface and reserved-stdlib conformance assertions

**What:**
Make reserved-stdlib conformance assert the new module and owner names.

**How:**
Change assertions that currently look for `LowGfx` or `set_sprite` so they instead require `LowComposer` and `emit_sprite`. Add direct reserved-import coverage for `@sdk:composer`.

**File(s):**
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/PbsGateUSdkInterfaceConformanceTest.java`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/stdlib/InterfaceModuleLoaderTest.java` if loader coverage is needed for the new module

### Step 3 - Update parser/semantic/linking fixtures only where the visible SDK surface changes

**What:**
Remove stale assumptions that the sprite path belongs to `Gfx`.

**How:**
Inspect PBS parser, semantic, linking, and diagnostics tests that rely on concrete stdlib imports or host owners. Migrate only the cases that directly encode sprite composition or reserved-SDK examples for this operation. Do not churn unrelated `gfx` primitive tests.

**File(s):**
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/linking/...`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/semantics/...`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/...`

### Step 4 - Add conformance coverage for removal of the old API

**What:**
Prove that the old public path is gone.

**How:**
Add negative coverage that user code importing `@sdk:gfx` can no longer call `set_sprite`, and positive coverage that sprite emission lowers through the `composer` host identity with the expected raw `int` return shape.

**File(s):**
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/services/PBSFrontendPhaseServiceTest.java`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/PbsGateUSdkInterfaceConformanceTest.java`

## Test Requirements

### Unit Tests

- PBS frontend tests must assert `LowComposer` host ownership for sprite emission.
- SDK-interface tests must assert that `@sdk:composer` resolves and exports the expected surface.
- Negative tests must confirm `Gfx.set_sprite` is no longer admitted.

### Integration Tests

- Compiler integration/conformance tests that inspect host declarations or emitted syscalls must pass with `composer.emit_sprite`.
- Any existing lower-to-host assertion must prove the canonical identity is `("composer", "emit_sprite", 1)`.

### Manual Verification

- Run focused test subsets around PBS frontend/stdlib loading and inspect failures for any remaining `LowGfx`/`set_sprite` assumptions.
- Review changed tests and confirm `@sdk:gfx` is still used only for primitive-oriented cases.

## Acceptance Criteria

- [ ] No compiler/frontend conformance test still asserts `LowGfx.set_sprite` or `Gfx.set_sprite`.
- [ ] Positive coverage exists for `Composer.emit_sprite(...)` lowering.
- [ ] Negative coverage exists for removal of `Gfx.set_sprite`.
- [ ] Primitive-oriented `@sdk:gfx` tests remain intact and are not accidentally migrated to `composer`.

## Dependencies

- Depends on `PLN-0053` establishing the canonical stdlib surface.
- Depends directly on `DEC-0027`.

## Risks

- Broad test churn can accidentally rewrite legitimate primitive-oriented `gfx` tests that should stay unchanged.
- If negative coverage is omitted, hidden compatibility behavior could survive behind updated positive tests.
- If host metadata assertions are updated inconsistently, compiler conformance may appear green while still teaching mixed ownership in fixtures.