From ef582b6687f18d920deb7be4fd897d7cc9db418d Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Sat, 18 Apr 2026 16:58:54 +0100 Subject: [PATCH] Studio Alignment with Runtime FrameComposer Syscalls and Sprite Composition --- discussion/index.ndjson | 3 +- ...e-composer-syscall-and-sprite-alignment.md | 170 ++++++++++++++++++ ...tudio-composer-sprite-syscall-alignment.md | 158 ++++++++++++++++ ...N-0053-composer-spec-and-stdlib-surface.md | 136 ++++++++++++++ ...oser-compiler-and-conformance-migration.md | 122 +++++++++++++ ...oser-fixtures-examples-and-repo-cleanup.md | 120 +++++++++++++ 6 files changed, 708 insertions(+), 1 deletion(-) create mode 100644 discussion/workflow/agendas/AGD-0031-studio-frame-composer-syscall-and-sprite-alignment.md create mode 100644 discussion/workflow/decisions/DEC-0027-studio-composer-sprite-syscall-alignment.md create mode 100644 discussion/workflow/plans/PLN-0053-composer-spec-and-stdlib-surface.md create mode 100644 discussion/workflow/plans/PLN-0054-composer-compiler-and-conformance-migration.md create mode 100644 discussion/workflow/plans/PLN-0055-composer-fixtures-examples-and-repo-cleanup.md diff --git a/discussion/index.ndjson b/discussion/index.ndjson index cac0aaff..be362693 100644 --- 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"}]} diff --git 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 new file mode 100644 index 00000000..602761b4 --- /dev/null +++ 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. diff --git a/discussion/workflow/decisions/DEC-0027-studio-composer-sprite-syscall-alignment.md b/discussion/workflow/decisions/DEC-0027-studio-composer-sprite-syscall-alignment.md new file mode 100644 index 00000000..fc216dac --- /dev/null +++ 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. diff --git a/discussion/workflow/plans/PLN-0053-composer-spec-and-stdlib-surface.md b/discussion/workflow/plans/PLN-0053-composer-spec-and-stdlib-surface.md new file mode 100644 index 00000000..59991cfa --- /dev/null +++ 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. diff --git a/discussion/workflow/plans/PLN-0054-composer-compiler-and-conformance-migration.md b/discussion/workflow/plans/PLN-0054-composer-compiler-and-conformance-migration.md new file mode 100644 index 00000000..f8a17ad4 --- /dev/null +++ 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. diff --git 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 new file mode 100644 index 00000000..969d303f --- /dev/null +++ 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.