From 908cb2b1fe2bf95124b4ab2d3b316f0a6f4d46a2 Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Sat, 18 Apr 2026 17:27:22 +0100 Subject: [PATCH] housekeep --- discussion/index.ndjson | 4 +- ...oser-must-own-public-sprite-composition.md | 70 ++++++++ ...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 ------------- 7 files changed, 72 insertions(+), 708 deletions(-) create mode 100644 discussion/lessons/DSC-0029-studio-frame-composer-syscall-and-sprite-alignment/LSN-0041-composer-must-own-public-sprite-composition.md delete mode 100644 discussion/workflow/agendas/AGD-0031-studio-frame-composer-syscall-and-sprite-alignment.md delete mode 100644 discussion/workflow/decisions/DEC-0027-studio-composer-sprite-syscall-alignment.md delete mode 100644 discussion/workflow/plans/PLN-0053-composer-spec-and-stdlib-surface.md delete mode 100644 discussion/workflow/plans/PLN-0054-composer-compiler-and-conformance-migration.md delete 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 be362693..31c3065c 100644 --- a/discussion/index.ndjson +++ b/discussion/index.ndjson @@ -1,5 +1,5 @@ -{"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":"meta","next_id":{"DSC":30,"AGD":32,"DEC":28,"PLN":56,"LSN":42,"CLSN":1}} +{"type":"discussion","id":"DSC-0029","status":"done","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":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0041","file":"discussion/lessons/DSC-0029-studio-frame-composer-syscall-and-sprite-alignment/LSN-0041-composer-must-own-public-sprite-composition.md","status":"done","created_at":"2026-04-18","updated_at":"2026-04-18"}]} {"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/lessons/DSC-0029-studio-frame-composer-syscall-and-sprite-alignment/LSN-0041-composer-must-own-public-sprite-composition.md b/discussion/lessons/DSC-0029-studio-frame-composer-syscall-and-sprite-alignment/LSN-0041-composer-must-own-public-sprite-composition.md new file mode 100644 index 00000000..f7dcc6a0 --- /dev/null +++ b/discussion/lessons/DSC-0029-studio-frame-composer-syscall-and-sprite-alignment/LSN-0041-composer-must-own-public-sprite-composition.md @@ -0,0 +1,70 @@ +--- +id: LSN-0041 +ticket: studio-frame-composer-syscall-and-sprite-alignment +title: Composer Must Own the Public Sprite-Composition Surface +created: 2026-04-18 +tags: [studio, compiler, pbs, stdlib, runtime-alignment, abi, syscall, frame-composer, sprites] +--- + +## Context + +The runtime had already moved canonical frame orchestration to `FrameComposer` and published the corresponding public ABI under `composer.*`, but Studio still exposed sprite composition through `@sdk:gfx` and `Gfx.set_sprite`. + +That left the repository teaching the wrong owner even though runtime dispatch, architectural lessons, and the public syscall domain had already changed. The migration closed that drift for the sprite path without pulling scene binding, camera control, or scene-bank work into the same ticket. + +## Key Decisions + +### Public Source Ownership Must Match the Runtime ABI + +**What:** +Studio now exposes sprite composition through `@sdk:composer`, with `LowComposer` as the low-level host owner and `Composer` as the public service facade. The old `Gfx.set_sprite` path was removed instead of being kept as compatibility sugar. + +**Why:** +Once runtime ownership moved to `FrameComposer`, keeping sprite submission under `gfx.*` would preserve a false mental model and create a dual contract between what the runtime actually owns and what PBS/stdlib teaches. + +**Trade-offs:** +The migration required coordinated changes across stdlib resources, specs, frontend conformance, examples, and LSP fixtures. That was more work up front, but it avoided a longer-lived compatibility layer that would have encoded the wrong architecture. + +### A Partial Domain Rollout Is Valid If the Boundary Is Explicit + +**What:** +This wave shipped only `composer.emit_sprite(...)` in Studio. `bind_scene`, `unbind_scene`, and `set_camera` were explicitly deferred. + +**Why:** +The current pipeline only needed sprite composition. Pulling scene/camera rollout into the same thread would have mixed ABI convergence with unfinished scene-work concerns and made the migration harder to execute cleanly. + +**Trade-offs:** +The docs had to state clearly that `@sdk:composer` exists now for sprite emission while other composer members remain future work. That is slightly less symmetrical in the short term, but it keeps the implemented contract honest. + +### Raw Status Returns Can Be Preserved During Ownership Migration + +**What:** +`Composer.emit_sprite(...)` kept the raw `int` status return for this wave instead of introducing a new editorial status shell. + +**Why:** +The architectural problem in this discussion was ownership and ABI drift, not status typing. Keeping the return shape stable allowed the migration to focus on the service boundary and public surface without coupling it to a second API redesign. + +**Trade-offs:** +The API remains less expressive than a nominal status shell, but the migration stayed narrow and easier to validate end to end. + +## Patterns and Algorithms + +- Treat runtime service ownership changes as public-source changes, not merely internal lowering rewrites. +- When the runtime removes a legacy public syscall path, prefer removing the matching source-level facade instead of silently retargeting it. +- Split migrations by boundary: first stdlib/spec surface, then compiler/conformance, then examples and fixture cleanup. +- Keep primitive-oriented `@sdk:gfx` coverage intact while moving only frame-composition behavior to `@sdk:composer`. +- Use a negative regression test for the removed API so compatibility leakage is caught explicitly. + +## Pitfalls + +- Retargeting `Gfx.set_sprite` internally to `composer.emit_sprite` would have looked convenient, but it would have preserved the wrong owner in the public teaching surface. +- A repository sweep that ignores examples and fixtures leaves stale guidance behind even when compiler tests are green. +- Replacing every `@sdk:gfx` example wholesale would be overcorrection; primitive and overlay operations still belong there. +- Updating docs to mention deferred composer members as if they already shipped would create a second kind of contract drift. + +## Takeaways + +- Public SDK ownership should mirror canonical runtime ownership, not historical implementation leftovers. +- Removing the old API is safer than keeping a compatibility facade that encodes the wrong subsystem boundary. +- A sprite-only `@sdk:composer` wave is acceptable when the deferred scene/camera scope is stated explicitly. +- Ownership migration and status-typing redesign do not need to happen in the same change. 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 deleted file mode 100644 index 602761b4..00000000 --- a/discussion/workflow/agendas/AGD-0031-studio-frame-composer-syscall-and-sprite-alignment.md +++ /dev/null @@ -1,170 +0,0 @@ ---- -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 deleted file mode 100644 index fc216dac..00000000 --- a/discussion/workflow/decisions/DEC-0027-studio-composer-sprite-syscall-alignment.md +++ /dev/null @@ -1,158 +0,0 @@ ---- -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 deleted file mode 100644 index 59991cfa..00000000 --- a/discussion/workflow/plans/PLN-0053-composer-spec-and-stdlib-surface.md +++ /dev/null @@ -1,136 +0,0 @@ ---- -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 deleted file mode 100644 index f8a17ad4..00000000 --- a/discussion/workflow/plans/PLN-0054-composer-compiler-and-conformance-migration.md +++ /dev/null @@ -1,122 +0,0 @@ ---- -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 deleted file mode 100644 index 969d303f..00000000 --- a/discussion/workflow/plans/PLN-0055-composer-fixtures-examples-and-repo-cleanup.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -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.