prometeu-studio/discussion/workflow/plans/PLN-0054-composer-compiler-and-conformance-migration.md

id	ticket	title	status	created	completed	tags
PLN-0054	studio-frame-composer-syscall-and-sprite-alignment	Compiler, Frontend, and Conformance Migration to `composer.emit_sprite`	review	2026-04-18		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.