Studio Alignment with Runtime FrameComposer Syscalls and Sprite Composition

2026-04-18 16:58:54 +01:00 · 2026-04-18 16:58:54 +01:00 · ef582b6687
commit ef582b6687
parent 9dbc88ce35
6 changed files with 708 additions and 1 deletions
--- a/discussion/index.ndjson
+++ b/discussion/index.ndjson
@ -1,4 +1,5 @@
-{"type":"meta","next_id":{"DSC":29,"AGD":31,"DEC":27,"PLN":53,"LSN":40,"CLSN":1}}
+{"type":"meta","next_id":{"DSC":30,"AGD":32,"DEC":28,"PLN":56,"LSN":40,"CLSN":1}}
 {"type":"discussion","id":"DSC-0029","status":"open","ticket":"studio-frame-composer-syscall-and-sprite-alignment","title":"Studio Alignment with Runtime FrameComposer Syscalls and Sprite Composition","created_at":"2026-04-18","updated_at":"2026-04-18","tags":["studio","compiler","pbs","stdlib","runtime-alignment","abi","syscall","frame-composer","sprites"],"agendas":[{"id":"AGD-0031","file":"AGD-0031-studio-frame-composer-syscall-and-sprite-alignment.md","status":"in_progress","created_at":"2026-04-18","updated_at":"2026-04-18"}],"decisions":[{"id":"DEC-0027","file":"DEC-0027-studio-composer-sprite-syscall-alignment.md","status":"in_progress","created_at":"2026-04-18","updated_at":"2026-04-18","ref_agenda":"AGD-0031"}],"plans":[{"id":"PLN-0053","file":"PLN-0053-composer-spec-and-stdlib-surface.md","status":"review","created_at":"2026-04-18","updated_at":"2026-04-18","ref_decisions":["DEC-0027"]},{"id":"PLN-0054","file":"PLN-0054-composer-compiler-and-conformance-migration.md","status":"review","created_at":"2026-04-18","updated_at":"2026-04-18","ref_decisions":["DEC-0027"]},{"id":"PLN-0055","file":"PLN-0055-composer-fixtures-examples-and-repo-cleanup.md","status":"review","created_at":"2026-04-18","updated_at":"2026-04-18","ref_decisions":["DEC-0027"]}],"lessons":[]}
 {"type":"discussion","id":"DSC-0028","status":"open","ticket":"studio-tiled-parser-assets-scene-asset-type","title":"Tiled Parser and Scene Asset-Type Ownership in Assets Workspace","created_at":"2026-04-15","updated_at":"2026-04-15","tags":["studio","assets","scene","tiled","parser","asset-type"],"agendas":[{"id":"AGD-0030","file":"AGD-0030-tiled-parser-and-scene-asset-type.md","status":"open","created_at":"2026-04-15","updated_at":"2026-04-15"}],"decisions":[],"plans":[],"lessons":[]}
 {"type":"discussion","id":"DSC-0027","status":"abandoned","ticket":"studio-scene-workspace","title":"Scene Workspace for SCENE Authoring","created_at":"2026-04-14","updated_at":"2026-04-15","tags":["studio","workspace","scene","tilemap","asset","runtime-alignment"],"agendas":[{"id":"AGD-0029","file":"AGD-0029-studio-scene-workspace.md","status":"abandoned","created_at":"2026-04-14","updated_at":"2026-04-15","_override_reason":"Explicit user request on 2026-04-15 to abandon the accepted agenda and its downstream work."}],"decisions":[{"id":"DEC-0026","file":"DEC-0026-studio-scene-workspace.md","status":"abandoned","created_at":"2026-04-14","updated_at":"2026-04-15","ref_agenda":"AGD-0029","_override_reason":"Explicit user request on 2026-04-15 to abandon the accepted decision and stop using it as normative guidance."}],"plans":[{"id":"PLN-0049","file":"PLN-0049-scene-workspace-spec-and-boundary-propagation.md","status":"abandoned","created_at":"2026-04-14","updated_at":"2026-04-15","ref_decisions":["DEC-0026"],"_override_reason":"Explicit user request on 2026-04-15 to abandon all plans derived from DEC-0026."},{"id":"PLN-0050","file":"PLN-0050-scene-workspace-shell-and-project-state-foundations.md","status":"abandoned","created_at":"2026-04-14","updated_at":"2026-04-15","ref_decisions":["DEC-0026"],"_override_reason":"Explicit user request on 2026-04-15 to abandon all plans derived from DEC-0026."},{"id":"PLN-0051","file":"PLN-0051-scene-artifact-and-assets-handoff-contract.md","status":"abandoned","created_at":"2026-04-14","updated_at":"2026-04-15","ref_decisions":["DEC-0026"],"_override_reason":"Explicit user request on 2026-04-15 to abandon all plans derived from DEC-0026."},{"id":"PLN-0052","file":"PLN-0052-scene-workspace-wave-1-tilemap-editor.md","status":"abandoned","created_at":"2026-04-14","updated_at":"2026-04-15","ref_decisions":["DEC-0026"],"_override_reason":"Explicit user request on 2026-04-15 to abandon all plans derived from DEC-0026."}],"lessons":[]}
 {"type":"discussion","id":"DSC-0026","status":"done","ticket":"glyph-bank-naming-alignment-with-runtime","title":"Glyph Bank Naming Alignment with Runtime DEC-0006","created_at":"2026-04-10","updated_at":"2026-04-10","tags":["packer","studio","naming","asset-contract","runtime-alignment","glyph-bank"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0040","file":"discussion/lessons/DSC-0026-glyph-bank-naming-alignment-with-runtime/LSN-0040-glyph-bank-artifact-naming-alignment.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
--- a/discussion/workflow/agendas/AGD-0031-studio-frame-composer-syscall-and-sprite-alignment.md
+++ b/discussion/workflow/agendas/AGD-0031-studio-frame-composer-syscall-and-sprite-alignment.md
@ -0,0 +1,170 @@
 ---
 id: AGD-0031
 ticket: studio-frame-composer-syscall-and-sprite-alignment
 title: Studio Alignment with Runtime FrameComposer Syscalls and Sprite Composition
 status: in_progress
 created: 2026-04-18
 resolved: 2026-04-18
 decision: DEC-0027
 tags:
  - studio
  - compiler
  - pbs
  - stdlib
  - runtime-alignment
  - abi
  - syscall
  - frame-composer
  - sprites
 ---
 ## Pain
 The sibling runtime has already moved the public frame-orchestration ABI to `composer.*`.
 This repository still exposes the old model through `@sdk:gfx` and `Gfx.set_sprite`, which means:
 - the Studio-side compiler and stdlib still teach a legacy public contract;
 - PBS examples and tests still lower sprite composition through the wrong owner;
 - specs still describe a source surface that no longer matches the runtime's canonical syscall boundary;
 - any new Studio work risks reinforcing a dual contract between `gfx.*` primitives and `composer.*` frame orchestration.
 The user explicitly scoped this discussion to:
 - ABI/syscall alignment with the current `../runtime`;
 - `FrameComposer` convergence for sprite composition;
 - Studio-side propagation across `compiler`, `pbs`, and `stdlib`;
 - `@sdk:composer` for the sprite-composition path;
 - removal of the legacy `Gfx.set_sprite` entrypoint;
 - no scene-bank implementation work in this ticket.
 ## Context
 Domain owner: `studio`
 Primary affected subdomains:
 - `compiler/pbs`
 - `studio`
 Expected propagation targets if this discussion closes:
 - `docs/specs/compiler-languages/pbs`
 - `docs/specs/compiler`
 - PBS stdlib resources under `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/stdlib`
 - compiler/frontend/backend conformance tests
 - Studio-adjacent examples and fixtures that still import `@sdk:gfx` for sprite composition
 Observed current state on 2026-04-18:
 - `../runtime` lesson `DSC-0026` locks `FrameComposer` as the canonical frame owner above the render backend.
 - `../runtime` lesson `DSC-0027` locks the public VM-facing syscall ABI to `composer.bind_scene`, `composer.unbind_scene`, `composer.set_camera`, and `composer.emit_sprite`, and removes the legacy public `gfx.set_sprite` path.
 - `../runtime` lesson `DSC-0028` keeps immediate/debug primitives such as `gfx.draw_text` outside canonical game composition as a deferred overlay path.
 - this repository still ships `@sdk:gfx` with `LowGfx.set_sprite(...)` and `Gfx.set_sprite(...)`;
 - this repository does not yet expose a reserved `@sdk:composer` module;
 - docs and tests still use `@sdk:gfx` as the visible source surface for sprite composition.
 This creates architectural drift:
 - runtime public ownership says `composer.*` for frame composition;
 - Studio-side language and stdlib surfaces still say `gfx.*` for part of that same behavior.
 The drift is specifically about syscall and sprite-composer alignment.
 Out of scope for this agenda:
 - `composer.bind_scene`, `composer.unbind_scene`, and `composer.set_camera` rollout in Studio;
 - scene-bank authoring workflows;
 - scene asset import/editor design;
 - scene bank build/materialization contracts beyond what is minimally needed to name ABI boundaries;
 - broader scene workspace/product decisions already separated into other discussions.
 ## Open Questions
 - [x] Studio should expose a new reserved module `@sdk:composer` as the canonical public source surface for sprite composition.
 - [x] `@sdk:gfx` should remain limited to primitive/overlay/back-end-adjacent operations once sprite composition moves out.
 - [x] PBS should export `@sdk:composer` using the same source-level shape already used by `@sdk:gfx`: low-level host owner plus public service facade.
 - [x] Mutating composer operations should remain raw `int` status returns in v1 for now.
 - [x] Tests, fixtures, examples, and callsites should all migrate in this wave if possible; no compatibility path should be preserved.
 - [x] No temporary compatibility alias is acceptable; `Gfx.set_sprite` should be removed completely.
 ## Options
 ### Option A - Introduce `@sdk:composer` now for sprite emission only in this wave
 - **Approach:** Add a dedicated reserved stdlib module that exposes the sprite-composition path through `composer.emit_sprite`; migrate sprite composition calls, host metadata, docs, and tests to that module; keep `@sdk:gfx` for primitives/overlay-style operations only; defer Studio-side `bind_scene`, `unbind_scene`, and `set_camera`.
 - **Pro:** Matches the runtime's canonical service boundary, preserves the split between frame composition and render primitives, and avoids teaching the retired `gfx.set_sprite` contract.
 - **Con:** Introduces a partial first wave of the `composer` domain, so docs must be explicit that other composer operations are intentionally deferred rather than absent by accident.
 - **Maintainability:** Strong, because the public source surface mirrors the actual runtime ABI and ownership model.
 ### Option B - Keep `@sdk:gfx` as the user-facing module and only retarget its internals to `composer.*`
 - **Approach:** Preserve the visible `Gfx.set_sprite` API in Studio while changing lowering metadata underneath to hit `composer.emit_sprite`.
 - **Pro:** Smaller immediate source churn in examples and tests.
 - **Con:** Encodes the wrong owner in the public teaching surface, preserves the exact dual-contract problem the runtime discussion just removed, and makes later cleanup harder.
 - **Maintainability:** Weak, because it keeps historical naming instead of canonical service ownership.
 ### Option C - Add `@sdk:composer` but retain temporary `Gfx.set_sprite` compatibility in parallel
 - **Approach:** Introduce the new canonical module while leaving `Gfx.set_sprite` as an alias or transitional wrapper for one or more waves.
 - **Pro:** Softens migration pressure for existing examples and downstream users.
 - **Con:** Creates two public ways to express the same operation, invites drift in specs/tests/docs, and conflicts with the runtime lesson that legacy public fallbacks should be removed when they preserve the wrong model.
 - **Maintainability:** Medium at best in the short term, poor in the long term if the alias survives longer than intended.
 ## Discussion
 The runtime side has already made two architectural facts explicit:
 1. frame orchestration belongs to `FrameComposer`, not to `Gfx`;
 2. the public syscall namespace must reflect that ownership.
 That means this repository is no longer choosing between equivalent naming styles.
 It is choosing whether Studio will:
 - align its source-facing contracts with the canonical runtime boundary; or
 - preserve a legacy public façade that the runtime has already declared misleading.
 The user's scope also matters.
 This ticket is not asking for scene-bank product work, and it also is not asking for Studio-side scene binding or camera rollout.
 So the migration target should stay narrow:
 - syscall/domain alignment;
 - `@sdk:composer` surface alignment for sprite emission;
 - compiler/PBS/stdlib propagation;
 - tests and examples updated to stop asserting the retired path.
 - removal of the old `Gfx.set_sprite` path.
 The remaining design work is therefore smaller and more concrete:
 - define the Studio-side shape of `@sdk:composer` for sprite emission;
 - propagate `composer.emit_sprite` through stdlib, specs, compiler, and tests;
 - keep the deferred composer calls explicitly out of this ticket so the repository does not accidentally mix sprite convergence with unfinished scene-facing rollout.
 The agenda questions are now resolved with explicit user direction:
 1. `@sdk:composer` should follow the same editorial pattern already used by `@sdk:gfx`, meaning a low-level host owner plus a public service facade.
 2. `composer.emit_sprite` should continue returning a raw `int` status in this wave.
 3. Migration should be broad and immediate across tests, fixtures, and examples where feasible.
 4. `Gfx.set_sprite` should be removed entirely, with no compatibility alias or dual-path surface.
 5. Specs should document only what this wave actually implements, while leaving room for `bind_scene`, `unbind_scene`, and `set_camera` to be added later using the same pattern.
 ## Resolution
 Recommended direction:
 - adopt Option A as the working direction for this discussion;
 - open a Studio-side canonical `@sdk:composer` surface aligned to the runtime ABI for sprite emission in this wave;
 - retire `Gfx.set_sprite` from normative Studio-facing contracts instead of preserving a compatibility façade;
 - defer `composer.bind_scene`, `composer.unbind_scene`, and `composer.set_camera` to a later ticket;
 - keep scene-bank authoring/editor work explicitly out of this ticket;
 - keep `@sdk:gfx` focused on primitive and overlay-style operations.
 Recommended next step:
 - treat the sprite-only `@sdk:composer` wave as the accepted scope of this agenda;
 - write a decision that locks:
  - `@sdk:composer` as the canonical Studio-side sprite-composition module;
  - the `LowComposer` + `Composer` shape matching the established `@sdk:gfx` pattern;
  - raw `int` status returns for this wave;
  - complete removal of `Gfx.set_sprite` with no compatibility path;
  - broad propagation across specs, stdlib, compiler, tests, fixtures, and examples;
  - deferred addition of `bind_scene`, `unbind_scene`, and `set_camera` in later work.
--- a/discussion/workflow/decisions/DEC-0027-studio-composer-sprite-syscall-alignment.md
+++ b/discussion/workflow/decisions/DEC-0027-studio-composer-sprite-syscall-alignment.md
@ -0,0 +1,158 @@
 ---
 id: DEC-0027
 ticket: studio-frame-composer-syscall-and-sprite-alignment
 title: Studio MUST Adopt `@sdk:composer` for Sprite Composition and Remove `Gfx.set_sprite`
 status: in_progress
 created: 2026-04-18
 accepted: 2026-04-18
 agenda: AGD-0031
 plans:
  - PLN-0053
  - PLN-0054
  - PLN-0055
 tags:
  - studio
  - compiler
  - pbs
  - stdlib
  - runtime-alignment
  - abi
  - syscall
  - frame-composer
  - sprites
 ---
 ## Context
 O `../runtime` já convergiu a ownership pública de frame orchestration para `FrameComposer` e já publicou a ABI pública correspondente no domínio `composer.*`.
 Para o recorte desta discussão, o ponto normativo relevante é simples:
 - sprite composition não pertence mais ao domínio público `gfx.*`;
 - o caminho público legado `gfx.set_sprite` já não representa o owner canônico no runtime;
 - o Studio ainda expõe esse caminho legado em stdlib, specs, testes, fixtures e exemplos.
 Isso cria drift entre:
 - a ABI pública real do runtime;
 - o contrato que o Studio ensina e emite;
 - a superfície que PBS usa como owner visível para composição de sprites.
 O usuário fechou explicitamente o escopo desta decisão:
 - entra apenas a wave de `@sdk:composer` para sprite composition;
 - entra `composer.emit_sprite`;
 - entra remoção total de `Gfx.set_sprite`;
 - `composer.bind_scene`, `composer.unbind_scene` e `composer.set_camera` ficam para trabalho posterior;
 - scene bank e concerns de authoring/editor ficam fora deste ticket.
 ## Decision
 O Studio MUST adotar `@sdk:composer` como a superfície canônica de stdlib/PBS para sprite composition nesta wave.
 Mais especificamente:
 1. A operação pública de composição de sprites MUST ser exposta por `composer.emit_sprite`.
 2. O módulo reservado `@sdk:composer` MUST seguir o mesmo shape editorial hoje usado por `@sdk:gfx`:
   - um owner host de baixo nível `LowComposer`;
   - uma façade pública `Composer`.
 3. Nesta wave, o contrato de retorno de `composer.emit_sprite` MUST permanecer um `int` cru.
 4. `Gfx.set_sprite` MUST ser removido integralmente da superfície normativa e executável do Studio.
 5. O repositório MUST NOT manter alias, wrapper de compatibilidade, dual path, ou retargeting silencioso que preserve `Gfx.set_sprite` como API pública.
 6. `@sdk:gfx` MUST permanecer restrito às operações primitivas/overlay/backend-adjacent que continuarem pertencendo a esse domínio.
 7. `composer.bind_scene`, `composer.unbind_scene` e `composer.set_camera` MUST permanecer fora do escopo de implementação desta decisão e SHALL ser adicionados depois por propagação separada, usando o mesmo padrão editorial.
 ## Rationale
 Esta decisão existe para eliminar um dual contract arquitetural que já deixou de ser válido no runtime.
 Manter `Gfx.set_sprite` como superfície pública teria três efeitos ruins:
 - preservaria o owner errado no contrato ensinado por PBS/stdlib;
 - manteria dois modelos mentais concorrentes para a mesma operação;
 - empurraria a remoção real do legado para um momento futuro mais caro e mais difícil.
 O recorte sprite-only é deliberado.
 Ele permite alinhar imediatamente a parte já necessária para o pipeline atual sem misturar:
 - rollout de scene binding;
 - rollout de camera control;
 - ou trabalho de scene bank/editoria de assets.
 Também ficou decidido que esta wave não tentará resolver modelagem de status com tipos editoriais novos.
 O retorno cru `int` é suficiente para convergir o boundary agora, sem introduzir uma segunda mudança de API no mesmo passo.
 ## Technical Specification
 ### 1. Stdlib Surface
 O repositório MUST introduzir um módulo reservado `@sdk:composer`.
 Esse módulo MUST:
 - declarar `LowComposer` com metadata canônica `Host(module = "composer", name = "emit_sprite", version = 1)`;
 - declarar a capability canônica correspondente;
 - expor `Composer.emit_sprite(...)` como façade pública;
 - usar o mesmo padrão estrutural já adotado por `@sdk:gfx`.
 O repositório MUST remover de `@sdk:gfx`:
 - a declaração host `LowGfx.set_sprite(...)`;
 - a façade pública `Gfx.set_sprite(...)`;
 - qualquer export relacionado à operação pública antiga.
 ### 2. Compiler and PBS Propagation
 As specs e implementações de PBS/compiler MUST passar a tratar `@sdk:composer` como a superfície canônica para sprite composition.
 Isso inclui:
 - examples normativos;
 - exemplos de import;
 - resolução de stdlib;
 - fixtures e testes que verificam host metadata;
 - testes que hoje afirmam `LowGfx`/`Gfx.set_sprite`.
 O lowering MUST emitir identidade canônica de host do domínio `composer`, não do domínio `gfx`, para sprite emission nesta wave.
 ### 3. Removal Rule
 `Gfx.set_sprite` MUST ser tratado como removido, não como deprecated.
 Consequências obrigatórias:
 - código de teste antigo que use `Gfx.set_sprite` MUST ser migrado;
 - fixtures e sample projects SHOULD ser migrados integralmente nesta wave sempre que estiverem dentro do repositório;
 - docs MUST deixar de ensinar `Gfx.set_sprite` como caminho válido;
 - a implementação MUST NOT deixar fallback oculto para o caminho antigo.
 ### 4. Documentation Scope
 As specs MUST documentar exatamente o que esta wave implementa:
 - `@sdk:composer` para sprite emission;
 - remoção de `Gfx.set_sprite`;
 - permanência de `@sdk:gfx` para primitivas/overlay relevantes.
 As specs MUST NOT fingir que scene binding ou camera control já fazem parte desta wave no Studio.
 Elas MAY mencionar que:
 - `bind_scene`,
 - `unbind_scene`,
 - `set_camera`
 serão adicionados depois seguindo o mesmo padrão, mas sem tratá-los como parte implementada agora.
 ## Constraints
 - Esta decisão MUST ser tratada como normativa e locked até revisão explícita do usuário.
 - Qualquer `plan` derivado dela MUST cobrir integralmente a criação de `@sdk:composer`, a propagação para specs/compiler/tests e a remoção total de `Gfx.set_sprite`.
 - Nenhum `plan` ou `implement` pode reinterpretar esta decisão como “migrar só internamente” mantendo a API pública antiga.
 - Nenhum `plan` ou `implement` pode puxar scene bank, bind/unbind de scene ou camera para dentro deste ticket por conveniência.
 - Se surgir ambiguidade sobre assinatura exata de `emit_sprite`, capability metadata, ou pontos concretos de propagação, o próximo estágio MUST esclarecer isso sem reabrir a remoção total do caminho antigo.
 ## Revision Log
 - 2026-04-18: Initial accepted decision from AGD-0031.
--- a/discussion/workflow/plans/PLN-0053-composer-spec-and-stdlib-surface.md
+++ b/discussion/workflow/plans/PLN-0053-composer-spec-and-stdlib-surface.md
@ -0,0 +1,136 @@
 ---
 id: PLN-0053
 ticket: studio-frame-composer-syscall-and-sprite-alignment
 title: Composer Spec and Stdlib Surface for Sprite Emission
 status: review
 created: 2026-04-18
 completed:
 tags:
  - studio
  - compiler
  - pbs
  - stdlib
  - specs
  - composer
  - sprites
 ---
 ## Objective
 Introduce the canonical `@sdk:composer` sprite-emission surface and remove `Gfx.set_sprite` from the normative stdlib/spec contract, exactly as required by `DEC-0027`.
 ## Background
 The runtime already moved public frame composition ownership to `composer.*` and removed the legacy public `gfx.set_sprite` path. This repository still teaches and packages sprite composition through `@sdk:gfx`, which creates ABI drift between runtime ownership and Studio-facing source surfaces.
 `DEC-0027` locks the following requirements for this wave:
 - `@sdk:composer` is the canonical Studio-side module for sprite composition.
 - The source shape must mirror the existing `@sdk:gfx` pattern: `LowComposer` plus public `Composer`.
 - `composer.emit_sprite` keeps a raw `int` return for now.
 - `Gfx.set_sprite` must be removed completely.
 - `bind_scene`, `unbind_scene`, and `set_camera` remain out of scope.
 ## Scope
 ### Included
 - Add `stdlib/1/sdk/composer/main.pbs`.
 - Add `stdlib/1/sdk/composer/mod.barrel`.
 - Remove `set_sprite` from `stdlib/1/sdk/gfx/main.pbs`.
 - Update stdlib/spec documentation to name `@sdk:composer` as the canonical sprite-composition surface.
 - Document that scene/camera composer calls are deferred and not part of this wave.
 ### Excluded
 - Compiler implementation changes beyond what is necessary to consume the new stdlib files.
 - Test fixture migration outside of spec/stdlib-focused assertions.
 - Runtime changes in `../runtime`.
 - Scene binding, scene unbinding, camera APIs, and scene-bank work.
 ## Execution Steps
 ### Step 1 - Add the reserved `@sdk:composer` module
 **What:**
 Create the reserved stdlib module for sprite emission.
 **How:**
 Add a new `sdk/composer` directory that follows the established reserved-module layout. Define `LowComposer.emit_sprite(...)` with canonical host metadata `Host(module = "composer", name = "emit_sprite", version = 1)` and the canonical capability metadata. Define a public `Composer.emit_sprite(...)` service method that forwards to `LowComposer`.
 **File(s):**
 - `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/stdlib/1/sdk/composer/main.pbs`
 - `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/stdlib/1/sdk/composer/mod.barrel`
 ### Step 2 - Remove the old public sprite path from `@sdk:gfx`
 **What:**
 Delete the legacy `set_sprite` public path from the GFX stdlib module.
 **How:**
 Remove the `LowGfx.set_sprite(...)` host declaration, remove the `Gfx.set_sprite(...)` service method, and leave the remaining primitive/overlay-oriented GFX surface intact.
 **File(s):**
 - `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/stdlib/1/sdk/gfx/main.pbs`
 - `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/stdlib/1/sdk/gfx/mod.barrel` if export adjustments become necessary
 ### Step 3 - Update PBS stdlib and host-binding specs
 **What:**
 Rewrite the normative docs so they stop teaching sprite composition through `@sdk:gfx`.
 **How:**
 Update the PBS specs that describe reserved stdlib modules, interface-module examples, host-binding examples, and logical stdlib mapping. Add `@sdk:composer` to the reserved-module inventory and update examples that currently import `Gfx` for host-backed illustration when those examples are used to explain sprite composition or SDK host ownership. Document that this wave covers only sprite emission, while scene/camera composer members are deferred.
 **File(s):**
 - `docs/specs/compiler-languages/pbs/5. Manifest, Stdlib, and SDK Resolution Specification.md`
 - `docs/specs/compiler-languages/pbs/6.2. Host ABI Binding and Loader Resolution Specification.md`
 - `docs/specs/compiler-languages/pbs/8. Stdlib Environment Packaging and Loading Specification.md`
 - `docs/specs/compiler/18. Standard Library Surface Specification.md`
 - Any additional compiler/PBS spec file whose examples currently name `Gfx.set_sprite` as canonical
 ### Step 4 - Align syntax/interface examples with the new owner
 **What:**
 Remove spec examples that preserve the old mental model for sprite composition.
 **How:**
 Review interface-module and host-declaration examples in the PBS syntax/spec set. Keep `gfx` examples where they demonstrate primitives generically, but change any sprite-composition-oriented illustration to `composer` so the docs no longer imply that `gfx` owns frame-composition policy.
 **File(s):**
 - `docs/specs/compiler-languages/pbs/3. Core Syntax Specification.md`
 - `docs/specs/compiler-languages/pbs/5. Manifest, Stdlib, and SDK Resolution Specification.md`
 - `docs/specs/compiler-languages/pbs/6.2. Host ABI Binding and Loader Resolution Specification.md`
 ## Test Requirements
 ### Unit Tests
 - Add or update stdlib-loading tests so `@sdk:composer` resolves successfully.
 - Add or update PBS SDK-interface tests so `LowComposer` and `Composer.emit_sprite(...)` are part of the reserved stdlib contract.
 ### Integration Tests
 - Existing compiler/frontend integration tests that load the stdlib must pass with the new module present and the old sprite path removed.
 ### Manual Verification
 - Inspect the generated stdlib resource tree and confirm `sdk/composer` is present and `sdk/gfx` no longer exposes `set_sprite`.
 - Read the updated spec sections and confirm they document only sprite emission for this wave and explicitly defer scene/camera composer calls.
 ## Acceptance Criteria
 - [ ] `@sdk:composer` exists under stdlib line `1` with `LowComposer` and `Composer`.
 - [ ] `Composer.emit_sprite(...)` uses canonical host metadata for `("composer", "emit_sprite", 1)`.
 - [ ] `@sdk:gfx` no longer exposes `set_sprite`.
 - [ ] PBS/compiler specs name `@sdk:composer` as the canonical sprite-composition surface.
 - [ ] Specs do not claim that `bind_scene`, `unbind_scene`, or `set_camera` are part of this wave.
 ## Dependencies
 - Depends directly on `DEC-0027`.
 - Should complete before broad compiler/test/example migration so downstream work can reference the final stdlib surface.
 ## Risks
 - Spec examples may accidentally over-generalize `composer` and imply that deferred scene/camera members are already available.
 - Removing `set_sprite` from `@sdk:gfx` may break more frontend tests than expected if hidden fixtures still import the old API.
 - If capability metadata or parameter shape drifts from runtime expectations, later compiler/test work will encode the wrong ABI under a new module name.
--- a/discussion/workflow/plans/PLN-0054-composer-compiler-and-conformance-migration.md
+++ b/discussion/workflow/plans/PLN-0054-composer-compiler-and-conformance-migration.md
@ -0,0 +1,122 @@
 ---
 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.
--- a/discussion/workflow/plans/PLN-0055-composer-fixtures-examples-and-repo-cleanup.md
+++ b/discussion/workflow/plans/PLN-0055-composer-fixtures-examples-and-repo-cleanup.md
@ -0,0 +1,120 @@
 ---
 id: PLN-0055
 ticket: studio-frame-composer-syscall-and-sprite-alignment
 title: Repository Fixtures, Examples, and Cleanup for Composer Sprite Migration
 status: review
 created: 2026-04-18
 completed:
 tags:
  - studio
  - examples
  - fixtures
  - lsp
  - composer
  - sprites
 ---
 ## Objective
 Remove repository-visible usage of `Gfx.set_sprite` and migrate examples, fixtures, and supporting tests to the new `@sdk:composer` sprite path.
 ## Background
 `DEC-0027` requires broad propagation across tests, fixtures, and examples, with no compatibility path. Even after stdlib/spec/compiler work lands, stale sample code or support fixtures would continue teaching the retired API and could hide incomplete migration.
 ## Scope
 ### Included
 - Migrate repository sample projects that still call `Gfx.set_sprite`.
 - Update LSP or support fixtures that rely on reserved SDK import examples where the new module is more appropriate.
 - Sweep repository-owned callsites for stale references to the old sprite path.
 - Add or update verification to ensure no repository-visible `Gfx.set_sprite` usage remains.
 ### Excluded
 - Third-party or external downstream projects outside this repository.
 - Runtime test suites in `../runtime`.
 - New scene/camera composer scenarios.
 ## Execution Steps
 ### Step 1 - Migrate sample projects to `@sdk:composer`
 **What:**
 Rewrite repository examples that still use the old sprite path.
 **How:**
 Update `test-projects/main` to import `Composer` from `@sdk:composer` and replace all `Gfx.set_sprite(...)` calls with `Composer.emit_sprite(...)`. Keep `Gfx` imports only for the remaining primitive calls such as `clear(...)`. Review `test-projects/fragments` and migrate only if it contains sprite-composition examples or should demonstrate the new reserved module inventory.
 **File(s):**
 - `test-projects/main/src/main.pbs`
 - `test-projects/fragments/src/main.pbs`
 ### Step 2 - Update LSP/import fixtures where the reserved SDK inventory is exercised
 **What:**
 Keep non-compiler support tests aligned with the new reserved-module set.
 **How:**
 Review LSP fixtures that use `@sdk:gfx` imports as representative SDK examples. Leave primitive-oriented examples intact when they are still valid, but add or switch coverage where the test should reflect the new reserved `@sdk:composer` module being part of the environment.
 **File(s):**
 - `prometeu-lsp/prometeu-lsp-v1/src/test/java/p/studio/lsp/LspServiceImplTest.java`
 ### Step 3 - Run a repository sweep for stale public sprite references
 **What:**
 Ensure the old API is not still visible in repository-owned artifacts.
 **How:**
 Search for `Gfx.set_sprite`, `LowGfx.set_sprite`, and sprite-specific `@sdk:gfx` examples. Remove or migrate every repository-owned occurrence that is part of the normative surface, examples, fixtures, or tests. Keep pure `@sdk:gfx` primitive usage where it remains valid.
 **File(s):**
 - `docs/**`
 - `prometeu-compiler/**`
 - `prometeu-lsp/**`
 - `test-projects/**`
 ### Step 4 - Add final regression verification for no-compat policy
 **What:**
 Create a final gate that makes legacy leakage easy to detect.
 **How:**
 Add or document a repository grep-based verification step in the execution notes or test workflow so implementation can confirm there are no remaining repository-owned `Gfx.set_sprite` references once the migration is complete.
 **File(s):**
 - Verification notes in the implementation PR or relevant test documentation
 ## Test Requirements
 ### Unit Tests
 - Any support or fixture tests touched by the migration must continue to pass with the new imports.
 ### Integration Tests
 - Repository sample projects used by compiler or integration flows must build/analyze successfully after migration.
 ### Manual Verification
 - Run a repository-wide search for `Gfx.set_sprite` and verify zero remaining repository-owned hits.
 - Run a repository-wide search for sprite-specific `@sdk:gfx` examples and verify they were either migrated or intentionally retained only for primitive usage.
 ## Acceptance Criteria
 - [ ] Repository sample code no longer uses `Gfx.set_sprite`.
 - [ ] No repository-owned fixture or example teaches the retired public sprite API.
 - [ ] Any retained `@sdk:gfx` usage is primitive/overlay-oriented rather than sprite-composition-oriented.
 - [ ] A repeatable verification step exists to confirm no-compat cleanup.
 ## Dependencies
 - Depends on `PLN-0053` for the final stdlib surface.
 - Depends on `PLN-0054` for compiler/frontend acceptance of the new imports and calls.
 - Depends directly on `DEC-0027`.
 ## Risks
 - Repository examples may mix primitive and sprite usage, making partial migration easy to miss.
 - LSP fixtures may not strictly require composer coverage, so the cleanup can be under-scoped unless reviewed deliberately.
 - Without a final sweep, legacy references can survive in docs or examples even after tests pass.