Studio Alignment with Runtime FrameComposer Syscalls and Sprite Composition

This commit is contained in:
2026-04-18 16:58:54 +01:00
parent 9dbc88ce35
commit ef582b6687
6 changed files with 708 additions and 1 deletions
@@ -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.
@@ -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.
@@ -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.