123 lines
5.7 KiB
Markdown
123 lines
5.7 KiB
Markdown
---
|
|
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.
|