frame composer - abi adjustments
This commit is contained in:
@@ -0,0 +1,122 @@
|
||||
---
|
||||
id: PLN-0022
|
||||
ticket: frame-composer-public-syscall-surface
|
||||
title: Plan - Composer Syscall Domain and Spec Propagation
|
||||
status: accepted
|
||||
created: 2026-04-17
|
||||
completed:
|
||||
tags: [gfx, runtime, syscall, abi, spec, isa-core, frame-composer]
|
||||
---
|
||||
|
||||
## Objective
|
||||
|
||||
Introduce the canonical `composer.*` syscall domain, define `ComposerOpStatus`, and propagate the new public contract through the canonical spec, ABI documentation, and `ISA_CORE` artifacts where affected.
|
||||
|
||||
## Background
|
||||
|
||||
`DEC-0015` locks the public orchestration surface on `composer.*`, requires `ComposerOpStatus` for mutating composer-domain calls, and requires propagation beyond code into canonical spec, ABI-facing documentation, and `ISA_CORE` where the public syscall surface is described normatively.
|
||||
|
||||
## Scope
|
||||
|
||||
### Included
|
||||
- add the `composer` syscall domain and ids
|
||||
- define `ComposerOpStatus`
|
||||
- remove `gfx.set_sprite(...)` from the public ABI contract
|
||||
- update canonical spec documentation for the new public surface
|
||||
- update ABI-facing documentation and `ISA_CORE` wherever the public syscall contract is described
|
||||
|
||||
### Excluded
|
||||
- runtime dispatch implementation
|
||||
- cartridge and stress program migration
|
||||
- final repository-wide CI execution
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1 - Define the public `composer` syscall contract
|
||||
|
||||
**What:**
|
||||
Add the new canonical public syscall surface to the HAL syscall contract.
|
||||
|
||||
**How:**
|
||||
- Extend the syscall enum, registry, metadata, and resolver with a new `composer` domain.
|
||||
- Allocate explicit syscall ids for:
|
||||
- `composer.bind_scene`
|
||||
- `composer.unbind_scene`
|
||||
- `composer.set_camera`
|
||||
- `composer.emit_sprite`
|
||||
- Remove `gfx.set_sprite` from the public syscall contract and registry.
|
||||
- Keep syscall metadata explicit for arg/ret slots and capability requirements.
|
||||
|
||||
**File(s):**
|
||||
- `crates/console/prometeu-hal/src/syscalls.rs`
|
||||
- `crates/console/prometeu-hal/src/syscalls/domains/*`
|
||||
- `crates/console/prometeu-hal/src/syscalls/registry.rs`
|
||||
- `crates/console/prometeu-hal/src/syscalls/resolver.rs`
|
||||
|
||||
### Step 2 - Introduce `ComposerOpStatus`
|
||||
|
||||
**What:**
|
||||
Create the status family for composer-domain mutating operations.
|
||||
|
||||
**How:**
|
||||
- Define a `ComposerOpStatus` type in HAL with explicit operational states needed by:
|
||||
- scene binding
|
||||
- scene unbinding
|
||||
- sprite emission
|
||||
- Ensure the enum is semantically composer-domain specific rather than a rename wrapper around `GfxOpStatus`.
|
||||
- Update public API references so composer syscalls return `ComposerOpStatus` where required by `DEC-0015`.
|
||||
|
||||
**File(s):**
|
||||
- `crates/console/prometeu-hal/src/*`
|
||||
- any shared status exports used by runtime/VM code
|
||||
|
||||
### Step 3 - Propagate the contract into spec, ABI docs, and `ISA_CORE`
|
||||
|
||||
**What:**
|
||||
Update normative documentation so the public contract no longer describes legacy `gfx.set_sprite`.
|
||||
|
||||
**How:**
|
||||
- Identify canonical spec files that describe VM graphics/composition syscalls.
|
||||
- Replace public references to legacy sprite orchestration with `composer.*`.
|
||||
- Update ABI-facing docs to pin:
|
||||
- namespace
|
||||
- names
|
||||
- arg order
|
||||
- return semantics
|
||||
- Update `ISA_CORE` if and where it references the affected syscall surface.
|
||||
- Keep published spec content in English per repository policy.
|
||||
|
||||
**File(s):**
|
||||
- canonical spec location(s)
|
||||
- ABI contract documentation
|
||||
- `ISA_CORE` artifact(s) if affected
|
||||
|
||||
## Test Requirements
|
||||
|
||||
### Unit Tests
|
||||
- syscall registry tests pin the new `composer.*` entries and reject removed legacy identities
|
||||
- `ComposerOpStatus` values are pinned where public return semantics are asserted
|
||||
|
||||
### Integration Tests
|
||||
- declared syscall resolution accepts `composer.*` declarations and rejects removed `gfx.set_sprite`
|
||||
|
||||
### Manual Verification
|
||||
- inspect canonical spec, ABI docs, and `ISA_CORE` references to confirm the public contract matches `DEC-0015`
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] The public syscall registry exposes `composer.bind_scene`, `composer.unbind_scene`, `composer.set_camera`, and `composer.emit_sprite`.
|
||||
- [ ] `ComposerOpStatus` exists as the canonical status family for composer-domain mutating syscalls.
|
||||
- [ ] `gfx.set_sprite` is removed from the public ABI contract.
|
||||
- [ ] Canonical spec documentation is updated to describe `composer.*`.
|
||||
- [ ] ABI-facing docs and `ISA_CORE` are updated wherever the affected public surface is documented.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Source decision: `DEC-0015`
|
||||
|
||||
## Risks
|
||||
|
||||
- Missing a normative doc location would leave the code and published contract divergent.
|
||||
- Reusing `GfxOpStatus` semantics by accident would weaken the service-boundary separation required by `DEC-0015`.
|
||||
- Removing the legacy syscall contract incompletely could leave resolver or ABI ambiguity behind.
|
||||
@@ -0,0 +1,112 @@
|
||||
---
|
||||
id: PLN-0023
|
||||
ticket: frame-composer-public-syscall-surface
|
||||
title: Plan - Composer Runtime Dispatch and Legacy Removal
|
||||
status: accepted
|
||||
created: 2026-04-17
|
||||
completed:
|
||||
tags: [runtime, syscall, frame-composer, dispatch, migration]
|
||||
---
|
||||
|
||||
## Objective
|
||||
|
||||
Route the new public `composer.*` syscalls through `FrameComposer`, remove legacy `gfx.set_sprite` handling, and align runtime-side operational behavior with `DEC-0015`.
|
||||
|
||||
## Background
|
||||
|
||||
`DEC-0015` closes the public contract around `composer.*` and requires that `gfx.set_sprite` be removed completely rather than kept as a compatibility shim. The internal `FrameComposer` ownership model already exists from `DEC-0014` and plans `PLN-0017` through `PLN-0021`.
|
||||
|
||||
## Scope
|
||||
|
||||
### Included
|
||||
- runtime syscall dispatch for `composer.*`
|
||||
- operational mapping from syscall args to `FrameComposer`
|
||||
- removal of legacy `gfx.set_sprite` runtime handling
|
||||
- runtime-facing tests for composer-domain behavior
|
||||
|
||||
### Excluded
|
||||
- spec and ABI doc propagation
|
||||
- cartridge/tooling migration
|
||||
- final `make ci` closure
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1 - Add runtime dispatch for `composer.*`
|
||||
|
||||
**What:**
|
||||
Teach VM runtime dispatch to call `FrameComposer` through the new public contract.
|
||||
|
||||
**How:**
|
||||
- Add dispatch arms for:
|
||||
- `composer.bind_scene`
|
||||
- `composer.unbind_scene`
|
||||
- `composer.set_camera`
|
||||
- `composer.emit_sprite`
|
||||
- Parse arguments exactly as pinned by the HAL metadata.
|
||||
- Return `ComposerOpStatus` for mutating composer-domain syscalls.
|
||||
|
||||
**File(s):**
|
||||
- `crates/console/prometeu-system/src/virtual_machine_runtime/dispatch.rs`
|
||||
- any adjacent runtime helpers
|
||||
|
||||
### Step 2 - Map operational outcomes cleanly onto `ComposerOpStatus`
|
||||
|
||||
**What:**
|
||||
Make runtime failures and normal outcomes reflect the new composer-domain status model.
|
||||
|
||||
**How:**
|
||||
- Bind runtime-side operational checks to status outcomes such as:
|
||||
- scene bank unavailable
|
||||
- bank invalid
|
||||
- argument range invalid
|
||||
- layer invalid
|
||||
- sprite overflow if surfaced operationally
|
||||
- Keep non-fatal overflow behavior aligned with `DEC-0015`.
|
||||
|
||||
**File(s):**
|
||||
- `crates/console/prometeu-system/src/virtual_machine_runtime/dispatch.rs`
|
||||
- `crates/console/prometeu-hal/src/*` as needed for shared status meaning
|
||||
|
||||
### Step 3 - Remove legacy `gfx.set_sprite` runtime support
|
||||
|
||||
**What:**
|
||||
Delete the old public runtime path for slot-style sprite submission.
|
||||
|
||||
**How:**
|
||||
- Remove dispatch support for `gfx.set_sprite`.
|
||||
- Remove runtime assumptions about `active`, caller-provided indices, and legacy sprite ABI shape.
|
||||
- Keep no private compatibility hook behind the public API.
|
||||
|
||||
**File(s):**
|
||||
- `crates/console/prometeu-system/src/virtual_machine_runtime/dispatch.rs`
|
||||
- adjacent tests and public syscall references
|
||||
|
||||
## Test Requirements
|
||||
|
||||
### Unit Tests
|
||||
- runtime dispatch returns `ComposerOpStatus` for bind, unbind, and emit operations
|
||||
- `composer.set_camera` stores the minimal V1 camera coordinates correctly
|
||||
|
||||
### Integration Tests
|
||||
- a VM/runtime test can bind a scene, set camera, emit a sprite, reach `FRAME_SYNC`, and render through the canonical frame path
|
||||
- public runtime behavior rejects removed `gfx.set_sprite` declarations/calls
|
||||
|
||||
### Manual Verification
|
||||
- inspect dispatch code to confirm all public orchestration now routes through `FrameComposer` rather than a legacy `gfx` sprite syscall path
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Runtime dispatch supports all canonical `composer.*` syscalls.
|
||||
- [ ] Mutating composer-domain calls return `ComposerOpStatus`.
|
||||
- [ ] `gfx.set_sprite` is removed from runtime public handling.
|
||||
- [ ] Runtime tests cover scene bind, camera set, sprite emit, and frame rendering through the public path.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Depends on `PLN-0022`
|
||||
- Source decision: `DEC-0015`
|
||||
|
||||
## Risks
|
||||
|
||||
- Removing legacy handling before all runtime references are migrated can strand tests or bytecode fixtures.
|
||||
- Poor `ComposerOpStatus` mapping could collapse useful operational distinctions into generic failures.
|
||||
+107
@@ -0,0 +1,107 @@
|
||||
---
|
||||
id: PLN-0024
|
||||
ticket: frame-composer-public-syscall-surface
|
||||
title: Plan - Composer Cartridge, Tooling, and Regression Migration
|
||||
status: accepted
|
||||
created: 2026-04-17
|
||||
completed:
|
||||
tags: [runtime, bytecode, tooling, stress, regression, frame-composer]
|
||||
---
|
||||
|
||||
## Objective
|
||||
|
||||
Migrate bytecode declarations, cartridges, stress tooling, and regression coverage from legacy public sprite orchestration to the canonical `composer.*` surface.
|
||||
|
||||
## Background
|
||||
|
||||
`DEC-0015` requires the new public composer-domain ABI to land without leaving `gfx.set_sprite` as a fallback. That means the migration must cover the generated bytecode, test cartridges, and stress tooling that still assume the old public contract.
|
||||
|
||||
## Scope
|
||||
|
||||
### Included
|
||||
- bytecode declaration updates for `composer.*`
|
||||
- cartridge and stress generator migration
|
||||
- regression coverage for the public composer-domain path
|
||||
- removal of legacy syscall usage from test and tooling surfaces
|
||||
|
||||
### Excluded
|
||||
- canonical spec propagation
|
||||
- runtime dispatch implementation
|
||||
- final repository-wide CI closure
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1 - Migrate declared syscall users and fixtures
|
||||
|
||||
**What:**
|
||||
Update code and fixtures that declare public syscalls so they target `composer.*`.
|
||||
|
||||
**How:**
|
||||
- Replace legacy public sprite syscall declarations with composer-domain declarations.
|
||||
- Update ABI expectations in bytecode-related tests and fixtures.
|
||||
- Ensure removal of `gfx.set_sprite` is reflected in any declaration validation snapshots.
|
||||
|
||||
**File(s):**
|
||||
- bytecode tests and fixtures
|
||||
- syscall declaration users across runtime and tools
|
||||
|
||||
### Step 2 - Migrate stress and cartridge tooling
|
||||
|
||||
**What:**
|
||||
Make the stress cartridge and related generators exercise the canonical public frame path.
|
||||
|
||||
**How:**
|
||||
- Update `pbxgen-stress` and any cartridge generators to declare and call `composer.*`.
|
||||
- Replace legacy sprite-path usage with `composer.emit_sprite`.
|
||||
- Add scene bind and camera usage where needed so the stress path reaches the real canonical pipeline.
|
||||
|
||||
**File(s):**
|
||||
- `crates/tools/pbxgen-stress/src/*`
|
||||
- `test-cartridges/stress-console/*`
|
||||
- related scripts such as `scripts/run-stress.sh`
|
||||
|
||||
### Step 3 - Expand regression coverage around the public path
|
||||
|
||||
**What:**
|
||||
Lock the new public orchestration contract with regression tests.
|
||||
|
||||
**How:**
|
||||
- Add tests that cover:
|
||||
- composer-domain declaration resolution
|
||||
- public bind/unbind/camera/emit behavior
|
||||
- scene rendering through the public path
|
||||
- stress/tooling integration using `composer.*`
|
||||
- Ensure no regression fixture still relies on removed `gfx.set_sprite`.
|
||||
|
||||
**File(s):**
|
||||
- runtime tests
|
||||
- HAL syscall tests
|
||||
- tooling tests where available
|
||||
|
||||
## Test Requirements
|
||||
|
||||
### Unit Tests
|
||||
- bytecode and syscall declaration tests pin `composer.*` names and slot counts
|
||||
|
||||
### Integration Tests
|
||||
- stress or cartridge-facing tests exercise scene bind, camera set, and sprite emit through `composer.*`
|
||||
- regression fixtures fail if `gfx.set_sprite` is reintroduced
|
||||
|
||||
### Manual Verification
|
||||
- inspect generated stress cartridge declarations and program behavior to confirm the public path is truly composer-domain based
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Bytecode declarations and fixtures use `composer.*` instead of legacy public sprite orchestration.
|
||||
- [ ] Stress tooling and test cartridges exercise the canonical public `FrameComposer` path.
|
||||
- [ ] Regression coverage protects against fallback to `gfx.set_sprite`.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Depends on `PLN-0022` and `PLN-0023`
|
||||
- Source decision: `DEC-0015`
|
||||
|
||||
## Risks
|
||||
|
||||
- Partial cartridge/tooling migration could leave the repository with hidden legacy public ABI usage.
|
||||
- Stress tooling may appear to pass while still missing scene/camera coverage if it only migrates sprite calls.
|
||||
@@ -0,0 +1,96 @@
|
||||
---
|
||||
id: PLN-0025
|
||||
ticket: frame-composer-public-syscall-surface
|
||||
title: Plan - Final CI Validation and Polish
|
||||
status: accepted
|
||||
created: 2026-04-17
|
||||
completed:
|
||||
tags: [ci, validation, regression, polish]
|
||||
---
|
||||
|
||||
## Objective
|
||||
|
||||
Run the final repository validation path, including `make ci`, and perform the last compatibility, formatting, lint, and regression fixes required to close the composer-domain migration cleanly.
|
||||
|
||||
## Background
|
||||
|
||||
`DEC-0015` requires a coordinated migration across ABI, runtime, tooling, cartridges, spec, and documentation. After the implementation plans land, the repository still needs a final closure pass so no residual breakage survives in formatting, linting, tests, generated artifacts, or CI expectations.
|
||||
|
||||
## Scope
|
||||
|
||||
### Included
|
||||
- final repository validation with `make ci`
|
||||
- fixups required by formatting, lint, tests, snapshots, or generated artifacts
|
||||
- final consistency pass across migrated files
|
||||
|
||||
### Excluded
|
||||
- introducing new contract changes beyond `DEC-0015`
|
||||
- reopening ABI or service-boundary decisions
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1 - Run the final validation entrypoint
|
||||
|
||||
**What:**
|
||||
Execute the repository’s final CI validation path.
|
||||
|
||||
**How:**
|
||||
- Run `make ci` after `PLN-0022`, `PLN-0023`, and `PLN-0024` are complete.
|
||||
- Capture failures from formatting, lint, tests, coverage setup, generation steps, or artifact drift.
|
||||
|
||||
**File(s):**
|
||||
- repository-wide validation entrypoints
|
||||
|
||||
### Step 2 - Apply closure fixes without reopening scope
|
||||
|
||||
**What:**
|
||||
Resolve residual breakage surfaced by final validation.
|
||||
|
||||
**How:**
|
||||
- Fix formatting and lint issues.
|
||||
- Update snapshots or generated artifacts only where the migrated public contract requires it.
|
||||
- Repair any remaining tests or documentation references that fail under `make ci`.
|
||||
- Do not widen scope beyond the accepted composer-domain migration.
|
||||
|
||||
**File(s):**
|
||||
- any files directly implicated by final validation failures
|
||||
|
||||
### Step 3 - Confirm final repository consistency
|
||||
|
||||
**What:**
|
||||
Leave the migration in a stable publishable state.
|
||||
|
||||
**How:**
|
||||
- Re-run `make ci` until it passes cleanly.
|
||||
- Verify no legacy public `gfx.set_sprite` usage remains in code, tests, tooling, or docs.
|
||||
- Confirm the worktree reflects only intended migration changes.
|
||||
|
||||
**File(s):**
|
||||
- repository-wide
|
||||
|
||||
## Test Requirements
|
||||
|
||||
### Unit Tests
|
||||
- whatever unit coverage is exercised by `make ci` must remain green
|
||||
|
||||
### Integration Tests
|
||||
- repository integration coverage under `make ci` must pass after the migration
|
||||
|
||||
### Manual Verification
|
||||
- inspect the tree for residual `gfx.set_sprite` references and incomplete composer-domain propagation
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] `make ci` passes after the composer-domain migration family lands.
|
||||
- [ ] Final fixups do not reopen contract scope beyond `DEC-0015`.
|
||||
- [ ] No residual public `gfx.set_sprite` usage remains in the repository.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Depends on `PLN-0022`, `PLN-0023`, and `PLN-0024`
|
||||
- Source decision: `DEC-0015`
|
||||
|
||||
## Risks
|
||||
|
||||
- If this final closure pass is skipped, small residual regressions can survive across formatting, lint, or generated artifacts even when the core implementation is correct.
|
||||
- Late fixes can accidentally widen scope unless kept strictly bounded to validation fallout.
|
||||
Reference in New Issue
Block a user