Studio Alignment with Runtime FrameComposer Syscalls and Sprite Composition
This commit is contained in:
@@ -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.
|
||||
Reference in New Issue
Block a user