Real Render Worker Establishment
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good

This commit is contained in:
2026-06-20 17:05:25 +01:00
parent aa917cf44e
commit 21b5d59a7d
44 changed files with 350 additions and 3092 deletions
@@ -1,81 +0,0 @@
---
id: PLN-0098
ticket: real-render-worker-establishment
title: Define Platform Facade Contracts
status: done
created: 2026-06-06
completed:
ref_decisions: [DEC-0032]
tags: [runtime, platform, hal, facades]
---
## Objective
Define the first `prometeu-hal` platform facade contracts that will replace the monolithic `HardwareBridge` model.
## Background
`DEC-0032` requires Prometeu to move from one runtime-facing `HardwareBridge` to explicit platform services/facades. This first plan creates the stable contract surface without migrating callers yet.
## Scope
### Included
- Add facade modules/types in `crates/console/prometeu-hal`.
- Define names and module ownership for `RuntimePlatform`, `RenderSubmissionSink`, `RenderBackend`, `Game2DFrameComposer`, and `TestPlatform` integration points.
- Add minimal documentation explaining that `HardwareBridge` is legacy migration scaffold.
### Excluded
- Do not remove `HardwareBridge`.
- Do not migrate syscalls, firmware, Hub, host, or tests yet.
- Do not implement the real render worker.
## Execution Steps
### Step 1 - Add platform facade module
**What:** Create a `platform` module in `prometeu-hal`.
**How:** Add facade trait declarations and re-exports without changing existing call sites.
**File(s):** `crates/console/prometeu-hal/src/platform.rs`, `crates/console/prometeu-hal/src/lib.rs`.
### Step 2 - Declare domain facade boundaries
**What:** Define initial placeholder traits for render submission, render backend, Game2D composer, audio, input/touch, assets/storage, clock/pacing, and telemetry.
**How:** Keep non-render traits minimal or marker-like when detailed APIs are not yet migrated.
**File(s):** `crates/console/prometeu-hal/src/platform.rs`.
### Step 3 - Document migration status
**What:** Mark `HardwareBridge` as legacy scaffold.
**How:** Add module-level comments stating it must be removed by later plans.
**File(s):** `crates/console/prometeu-hal/src/hardware_bridge.rs`.
## Test Requirements
### Unit Tests
- Compile-only tests or trait object assertions where useful.
### Integration Tests
- Existing HAL/system/driver tests must continue to pass.
### Manual Verification
- Confirm `HardwareBridge` has no new dependencies on the platform facades.
## Acceptance Criteria
- [ ] Platform facade module exists in `prometeu-hal`.
- [ ] `HardwareBridge` is explicitly documented as migration scaffold.
- [ ] No runtime behavior changes.
- [ ] Existing tests pass.
## Dependencies
- `DEC-0032`.
## Risks
- Introducing too much API too early can freeze poor names. Keep this plan narrow.
@@ -1,82 +0,0 @@
---
id: PLN-0099
ticket: real-render-worker-establishment
title: Introduce Owned RenderSubmissionSink
status: done
created: 2026-06-06
completed:
ref_decisions: [DEC-0032]
tags: [runtime, renderer, hal, errors]
---
## Objective
Introduce an owned `RenderSubmissionSink` facade with minimal typed submission errors.
## Background
`DEC-0032` requires render publication to move away from `HardwareBridge` and to accept owned `RenderSubmission` values so the contract is compatible with async handoff.
## Scope
### Included
- Define `RenderSubmissionSink`.
- Define minimal `RenderSubmitError`.
- Implement the facade for the current local driver path.
### Excluded
- Do not migrate all publication call sites yet.
- Do not spawn a render worker.
- Do not remove `HardwareBridge::publish_render_submission`.
## Execution Steps
### Step 1 - Define sink and error
**What:** Add `RenderSubmissionSink` and `RenderSubmitError`.
**How:** `submit_render_submission(&mut self, submission: RenderSubmission) -> Result<(), RenderSubmitError>`.
**File(s):** `crates/console/prometeu-hal/src/platform.rs` or a render-specific HAL module.
### Step 2 - Implement local sink
**What:** Implement the sink for the current local driver implementation.
**How:** Adapt owned submission to the existing local `Hardware` publication path.
**File(s):** `crates/console/prometeu-drivers/src/hardware.rs`.
### Step 3 - Add tests
**What:** Prove owned submission is consumed by the local sink.
**How:** Add driver test using `RenderSubmission::game2d` and `RenderSubmission::shell_ui`.
**File(s):** `crates/console/prometeu-drivers/src/hardware.rs` or platform test module.
## Test Requirements
### Unit Tests
- Local sink accepts owned Game2D and ShellUi submissions.
- Error type is constructible and debuggable.
### Integration Tests
- `cargo test -p prometeu-hal -p prometeu-drivers`.
### Manual Verification
- Confirm the sink does not take `&RenderSubmission`.
## Acceptance Criteria
- [ ] `RenderSubmissionSink` takes owned `RenderSubmission`.
- [ ] Minimal typed error exists.
- [ ] Local driver implements the sink.
- [ ] Existing publication behavior remains intact.
## Dependencies
- `PLN-0098`.
## Risks
- Local paths may still need temporary borrow adaptation. Keep it internal to the implementation.
@@ -1,80 +0,0 @@
---
id: PLN-0100
ticket: real-render-worker-establishment
title: Migrate Local Render Publication to RenderSubmissionSink
status: done
created: 2026-06-06
completed:
ref_decisions: [DEC-0032]
tags: [runtime, renderer, platform]
---
## Objective
Move local render publication call sites from `HardwareBridge::publish_render_submission` to `RenderSubmissionSink`.
## Background
The sink must become the publication boundary before a real worker can replace the local path. Runtime, firmware, and Hub currently publish through the monolithic bridge.
## Scope
### Included
- Runtime local render surface uses `RenderSubmissionSink`.
- Firmware splash/crash publication uses the sink.
- Hub Shell UI publication uses the sink or a temporary adapter.
### Excluded
- Do not remove `HardwareBridge`.
- Do not migrate non-render domains.
- Do not change command buffering semantics yet.
## Execution Steps
### Step 1 - Adapt runtime tick publication
**What:** Replace `HardwareRenderSurface` dependency on `HardwareBridge::publish_render_submission`.
**How:** Route submission through `RenderSubmissionSink`.
**File(s):** `crates/console/prometeu-system/src/services/vm_runtime/tick.rs`.
### Step 2 - Adapt firmware and Hub publication
**What:** Stop direct calls to `hw.publish_render_submission`.
**How:** Use the sink through explicit platform/render facade access or temporary adapter.
**File(s):** `crates/console/prometeu-firmware/src/firmware_step_splash_screen.rs`, `crates/console/prometeu-firmware/src/firmware_step_crash_screen.rs`, `crates/console/prometeu-system/src/programs/prometeu_hub/prometeu_hub.rs`.
### Step 3 - Update tests
**What:** Adjust tests that call `HardwareBridge::publish_render_submission`.
**How:** Use `RenderSubmissionSink` where render publication is the target.
**File(s):** `crates/console/prometeu-system/src/services/vm_runtime/tests.rs`, driver tests.
## Test Requirements
### Unit Tests
- Existing render manager tests pass.
### Integration Tests
- `cargo test -p prometeu-system -p prometeu-firmware -p prometeu-drivers`.
### Manual Verification
- `rg "publish_render_submission" crates/console` shows only legacy implementation or intentionally unmigrated scaffold.
## Acceptance Criteria
- [ ] Runtime publication uses `RenderSubmissionSink`.
- [ ] Firmware/Hub publication no longer depend directly on the monolithic bridge.
- [ ] Tests pass.
## Dependencies
- `PLN-0099`.
## Risks
- Firmware code may need a small context shape change. Keep compatibility adapters temporary and explicit.
@@ -1,82 +0,0 @@
---
id: PLN-0101
ticket: real-render-worker-establishment
title: Remove Immediate Gfx2D and GfxUI Syscall Rendering
status: done
created: 2026-06-06
completed:
ref_decisions: [DEC-0032]
tags: [runtime, gfx, syscalls, renderer]
---
## Objective
Make `gfx2d.*` and `gfxui.*` syscalls buffer commands only, without mutating the framebuffer immediately.
## Background
`DEC-0032` requires framebuffer mutation to occur through render submission consumption/publication, not inside VM syscall dispatch. This is required before render can run independently.
## Scope
### Included
- Remove `hw.gfx_mut().*` immediate draw calls from VM dispatch for `gfx2d` and `gfxui`.
- Add regression tests for `gfx2d.clear` and `gfx2d.draw_text`.
- Update tests that assumed immediate pixel mutation.
### Excluded
- Do not remove `GfxBridge`.
- Do not migrate composer in this plan.
- Do not implement worker.
## Execution Steps
### Step 1 - Remove immediate Game gfx writes
**What:** Delete direct `hw.gfx_mut()` rendering in `Gfx*` syscall handlers.
**How:** Keep command buffering into `gfx2d_commands`.
**File(s):** `crates/console/prometeu-system/src/services/vm_runtime/dispatch.rs`.
### Step 2 - Remove immediate Shell UI writes
**What:** Delete direct `hw.gfx_mut()` rendering in `GfxUi*` syscall handlers.
**How:** Keep command buffering into `gfxui_commands`.
**File(s):** `crates/console/prometeu-system/src/services/vm_runtime/dispatch.rs`.
### Step 3 - Add regression tests
**What:** Prove syscalls do not affect pixels until publication.
**How:** Tests for `gfx2d.clear` and `gfx2d.draw_text` should inspect command buffers and frame publication.
**File(s):** `crates/console/prometeu-system/src/services/vm_runtime/tests.rs`.
## Test Requirements
### Unit Tests
- `gfx2d.clear` buffers only.
- `gfx2d.draw_text` buffers only.
- Shell UI commands buffer only.
### Integration Tests
- Stress cartridge still renders after frame publication.
### Manual Verification
- `rg "gfx_mut\\(\\).*draw|gfx_mut\\(\\).*clear|gfx_mut\\(\\).*fill" dispatch.rs` returns no immediate render calls.
## Acceptance Criteria
- [ ] Gfx syscalls no longer mutate framebuffer immediately.
- [ ] Pixels change only after render submission publication.
- [ ] Tests updated to the new contract.
## Dependencies
- `PLN-0100`.
## Risks
- Debug workflows may have relied on immediate drawing. Tests must make the new frame boundary explicit.
@@ -1,82 +0,0 @@
---
id: PLN-0102
ticket: real-render-worker-establishment
title: Introduce Game2DFrameComposer Logical Service
status: done
created: 2026-06-06
completed:
ref_decisions: [DEC-0032]
tags: [runtime, composer, game2d, platform]
---
## Objective
Introduce `Game2DFrameComposer` as the logical-side service/facade for Game2D frame preparation.
## Background
`DEC-0032` states that `bind_scene`, `set_camera`, `emit_sprite`, and `close_game2d_packet` are logical frame preparation, not physical backend behavior.
## Scope
### Included
- Define a `Game2DFrameComposer` facade.
- Move or wrap existing `FrameComposer` behavior under logical-side naming.
- Migrate composer syscalls to use the facade rather than generic hardware.
### Excluded
- Do not rewrite scene cache internals.
- Do not move viewport cache across threads.
- Do not implement worker.
## Execution Steps
### Step 1 - Define composer facade
**What:** Add `Game2DFrameComposer` trait or service contract.
**How:** Include `begin_frame`, `bind_scene`, `unbind_scene`, `set_camera`, `emit_sprite`, `close_game2d_packet`, and required read checks.
**File(s):** `crates/console/prometeu-hal/src/platform.rs` or composer-specific HAL module.
### Step 2 - Implement using current composer
**What:** Make current local driver composer satisfy the new logical service.
**How:** Reuse `FrameComposer` implementation under adapter/implementation.
**File(s):** `crates/console/prometeu-drivers/src/frame_composer.rs`, `crates/console/prometeu-drivers/src/hardware.rs`.
### Step 3 - Migrate composer syscalls
**What:** Dispatch composer syscalls through `Game2DFrameComposer`.
**How:** Remove dependency on `HardwareBridge` methods for composer.
**File(s):** `crates/console/prometeu-system/src/services/vm_runtime/dispatch.rs`.
## Test Requirements
### Unit Tests
- Composer facade closes packets equivalent to previous `FrameComposer`.
- Invalid scene/bank behavior remains unchanged.
### Integration Tests
- Existing scene/composer runtime tests pass.
### Manual Verification
- Composer syscalls no longer require `&mut dyn HardwareBridge`.
## Acceptance Criteria
- [ ] `Game2DFrameComposer` exists as logical service/facade.
- [ ] Composer syscalls route through it.
- [ ] Existing Game2D scene rendering remains correct.
## Dependencies
- `PLN-0098`.
- `PLN-0101`.
## Risks
- Scene cache ownership can be accidentally moved too early. Keep cache behavior local while changing the boundary.
@@ -1,82 +0,0 @@
---
id: PLN-0103
ticket: real-render-worker-establishment
title: Introduce RuntimePlatform and TestPlatform
status: done
created: 2026-06-06
completed:
ref_decisions: [DEC-0032]
tags: [runtime, platform, tests]
---
## Objective
Introduce `RuntimePlatform`/`Platform` as the aggregate of explicit platform services, and `TestPlatform` as the default test fixture.
## Background
`DEC-0032` requires tests and runtime integration to depend on explicit facades rather than `Hardware::new()` and `HardwareBridge`.
## Scope
### Included
- Define aggregate platform access shape.
- Add `TestPlatform` in `prometeu-drivers`.
- Start migrating representative VM runtime tests.
### Excluded
- Do not migrate all tests in this plan.
- Do not remove `HardwareBridge`.
- Do not migrate all host code.
## Execution Steps
### Step 1 - Define platform aggregate
**What:** Add `RuntimePlatform` or `Platform` aggregate facade.
**How:** Expose accessors for render sink, Game2D composer, audio, input/touch, assets/storage, clock/pacing, and telemetry placeholders.
**File(s):** `crates/console/prometeu-hal/src/platform.rs`.
### Step 2 - Add TestPlatform
**What:** Provide ergonomic test fixture implementing the initial platform facades.
**How:** Reuse current local driver components internally without exposing `HardwareBridge`.
**File(s):** `crates/console/prometeu-drivers/src/test_platform.rs`, `crates/console/prometeu-drivers/src/lib.rs`.
### Step 3 - Migrate representative tests
**What:** Move a small set of runtime tests from `Hardware::new()` to `TestPlatform`.
**How:** Choose tests covering render, composer, and asset surfaces.
**File(s):** `crates/console/prometeu-system/src/services/vm_runtime/tests.rs`, asset/memcard test modules as appropriate.
## Test Requirements
### Unit Tests
- `TestPlatform` initializes all required facades.
### Integration Tests
- Migrated runtime tests pass with `TestPlatform`.
### Manual Verification
- New tests do not import `prometeu_drivers::Hardware` directly.
## Acceptance Criteria
- [ ] `RuntimePlatform`/`Platform` aggregate exists.
- [ ] `TestPlatform` exists and is used by representative tests.
- [ ] Test ergonomics remain acceptable.
## Dependencies
- `PLN-0098`.
- `PLN-0099`.
- `PLN-0102`.
## Risks
- Overly broad aggregate can recreate `HardwareBridge`. Keep domain access explicit and named.
@@ -1,79 +0,0 @@
---
id: PLN-0104
ticket: real-render-worker-establishment
title: Migrate VM Runtime HostContext to Platform Services
status: done
created: 2026-06-06
completed:
ref_decisions: [DEC-0032]
tags: [runtime, vm, platform, hostcontext]
---
## Objective
Change VM runtime execution from receiving `&mut dyn HardwareBridge` to receiving explicit platform services.
## Background
`HostContext` currently carries `Option<&mut dyn HardwareBridge>`. That shape lets every syscall see the entire bridge. `DEC-0032` requires explicit services instead.
## Scope
### Included
- Introduce a platform-aware `HostContext` shape.
- Migrate VM runtime tick/dispatch to use platform services.
- Preserve VM tests and fault behavior.
### Excluded
- Do not migrate firmware/Hub in this plan.
- Do not remove `HardwareBridge` yet.
## Execution Steps
### Step 1 - Add platform host context
**What:** Extend or replace `HostContext` with platform-service access.
**How:** Add methods for required VM syscall domains instead of `require_hw()`.
**File(s):** `crates/console/prometeu-hal/src/host_context.rs`.
### Step 2 - Migrate runtime tick
**What:** Tick uses platform services for begin-frame, composer frame closure, render sink, audio clear, and telemetry reads.
**How:** Replace direct bridge access with explicit facade calls.
**File(s):** `crates/console/prometeu-system/src/services/vm_runtime/tick.rs`.
### Step 3 - Migrate dispatch
**What:** VM syscall dispatch uses explicit facade methods.
**How:** Remove `ctx.require_hw()` as the central dispatch dependency.
**File(s):** `crates/console/prometeu-system/src/services/vm_runtime/dispatch.rs`.
## Test Requirements
### Unit Tests
- VM dispatch tests pass with platform context.
### Integration Tests
- `cargo test -p prometeu-system`.
### Manual Verification
- `rg "require_hw|HardwareBridge" vm_runtime` shows no production VM runtime dependency except temporary compatibility adapters explicitly marked.
## Acceptance Criteria
- [ ] VM runtime dispatch no longer depends on the monolithic bridge.
- [ ] Tick uses explicit platform services.
- [ ] Existing VM fault behavior remains unchanged.
## Dependencies
- `PLN-0103`.
## Risks
- `HostContext` is used in VM unit tests. Migration must keep no-hardware test contexts ergonomic.
@@ -1,81 +0,0 @@
---
id: PLN-0105
ticket: real-render-worker-establishment
title: Migrate Firmware and Hub to Platform Services
status: done
created: 2026-06-06
completed:
ref_decisions: [DEC-0032]
tags: [firmware, hub, platform, render]
---
## Objective
Move firmware screens and Hub UI away from `HardwareBridge` and onto explicit platform services.
## Background
Firmware splash/crash and Hub currently receive `&mut dyn HardwareBridge` and publish Shell UI directly through it. `DEC-0032` requires migration to platform facades.
## Scope
### Included
- Firmware context uses platform services.
- Splash/crash screens publish via render sink.
- Hub input/render uses input/render facades.
### Excluded
- Do not implement worker.
- Do not change Hub UX or firmware state machine semantics.
## Execution Steps
### Step 1 - Update firmware context
**What:** Replace `PrometeuContext` hardware bridge field with platform services.
**How:** Expose only the services firmware needs: input, assets, render sink.
**File(s):** `crates/console/prometeu-firmware/src/firmware/prometeu_context.rs`, `firmware.rs`.
### Step 2 - Migrate firmware screens
**What:** Splash and crash screens publish through `RenderSubmissionSink`.
**How:** Build Shell UI packet and submit owned submission.
**File(s):** `crates/console/prometeu-firmware/src/firmware_step_splash_screen.rs`, `firmware_step_crash_screen.rs`.
### Step 3 - Migrate Hub
**What:** Hub uses platform input/render services instead of `HardwareBridge`.
**How:** Replace activation input and render publication dependencies.
**File(s):** `crates/console/prometeu-system/src/programs/prometeu_hub/prometeu_hub.rs`.
## Test Requirements
### Unit Tests
- Firmware state tests pass.
- Hub UI tests pass.
### Integration Tests
- `cargo test -p prometeu-firmware -p prometeu-system`.
### Manual Verification
- Firmware/Hub no longer call `publish_render_submission` on `HardwareBridge`.
## Acceptance Criteria
- [ ] Firmware context no longer exposes the monolithic bridge.
- [ ] Splash/crash/Hub render via render sink.
- [ ] Hub input uses platform/input facade.
## Dependencies
- `PLN-0103`.
- `PLN-0104`.
## Risks
- Firmware code is lifecycle-sensitive. Keep behavior changes out of scope.
@@ -1,79 +0,0 @@
---
id: PLN-0106
ticket: real-render-worker-establishment
title: Migrate Desktop Host to Platform Services
status: done
created: 2026-06-06
completed:
ref_decisions: [DEC-0032]
tags: [host, desktop, platform]
---
## Objective
Move the desktop host from directly exposing `prometeu_drivers::Hardware` as the runtime bridge to owning a platform implementation.
## Background
The host currently creates `Hardware::new()` and passes it into firmware/runtime paths. `DEC-0032` requires hosts to implement platform services, not to expose a monolithic bridge.
## Scope
### Included
- Introduce desktop/local platform ownership in the host.
- Replace host usage of `Hardware::W/H` with platform display constants or framebuffer descriptor.
- Keep the same visual/audio/input behavior.
### Excluded
- Do not implement render worker thread.
- Do not change windowing library or presentation policy.
## Execution Steps
### Step 1 - Add host platform field
**What:** Host runner owns a platform implementation rather than raw `Hardware`.
**How:** Wrap current local driver implementation behind platform facades.
**File(s):** `crates/host/prometeu-host-desktop-winit/src/runner.rs`.
### Step 2 - Replace direct hardware constants
**What:** Stop reading `Hardware::W/H` directly in host rendering/input.
**How:** Use a framebuffer/display descriptor exposed by platform/render service.
**File(s):** `crates/host/prometeu-host-desktop-winit/src/runner.rs`, `input.rs`.
### Step 3 - Update debugger host setup
**What:** Debugger paths instantiate platform fixture/implementation.
**How:** Replace `Hardware::new()` in debugger setup.
**File(s):** `crates/host/prometeu-host-desktop-winit/src/debugger.rs`.
## Test Requirements
### Unit Tests
- Host crate tests compile.
### Integration Tests
- `cargo test -p prometeu-host-desktop-winit`.
### Manual Verification
- Desktop host still runs stress cartridge.
## Acceptance Criteria
- [ ] Desktop host owns platform services.
- [ ] Host no longer treats `Hardware` as runtime bridge.
- [ ] Display dimensions come from platform/render descriptor.
## Dependencies
- `PLN-0105`.
## Risks
- Desktop host mixes runtime and window concerns. Keep worker threading out of this plan.
@@ -1,89 +0,0 @@
---
id: PLN-0107
ticket: real-render-worker-establishment
title: Migrate Remaining Platform Domains
status: done
created: 2026-06-06
completed:
ref_decisions: [DEC-0032]
tags: [platform, audio, input, assets, clock, telemetry]
---
## Objective
Migrate non-render domains out of `HardwareBridge` into explicit platform services.
## Background
`DEC-0032` permits render to migrate first but requires the full migration to cover audio, input/touch, assets/storage, clock/pacing, and telemetry where applicable.
## Scope
### Included
- Audio service/facade migration.
- Input/touch service/facade migration.
- Assets/storage service/facade migration.
- Clock/pacing and telemetry surface migration where currently coupled.
### Excluded
- Do not change domain semantics.
- Do not implement async IO unless already supported by existing services.
## Execution Steps
### Step 1 - Migrate audio
**What:** Replace `hw.audio()`/`hw.audio_mut()` production dependencies.
**How:** Route through explicit audio platform service.
**File(s):** `crates/console/prometeu-system/src/services/vm_runtime/dispatch.rs`, firmware/host integration files.
### Step 2 - Migrate input and touch
**What:** Replace `hw.pad()`/`hw.touch()` dependencies.
**How:** Expose input snapshots through platform input service.
**File(s):** `crates/console/prometeu-system`, `crates/console/prometeu-firmware`, host input modules.
### Step 3 - Migrate assets/storage
**What:** Replace `hw.assets()`/`hw.assets_mut()` dependencies.
**How:** Route through asset/storage services while preserving commit and bank visibility semantics.
**File(s):** `crates/console/prometeu-system/src/services/vm_runtime`, `crates/console/prometeu-firmware`.
### Step 4 - Migrate clock/pacing/telemetry coupling
**What:** Move any platform-facing clock or telemetry coupling out of `HardwareBridge`.
**How:** Use explicit runtime/platform services.
**File(s):** `crates/console/prometeu-system/src/services/vm_runtime`, HAL telemetry modules.
## Test Requirements
### Unit Tests
- Audio/input/asset syscall tests pass.
### Integration Tests
- `cargo test -p prometeu-system -p prometeu-firmware -p prometeu-drivers`.
### Manual Verification
- `rg "audio_mut|pad_mut|touch_mut|assets_mut" crates/console` does not show production bridge dependencies.
## Acceptance Criteria
- [ ] Audio migrated to platform service.
- [ ] Input/touch migrated to platform service.
- [ ] Assets/storage migrated to platform service.
- [ ] Clock/pacing/telemetry bridge coupling removed where applicable.
## Dependencies
- `PLN-0104`.
- `PLN-0105`.
- `PLN-0106`.
## Risks
- Asset visibility semantics are high risk. Keep behavior-preserving tests broad.
@@ -1,81 +0,0 @@
---
id: PLN-0108
ticket: real-render-worker-establishment
title: Migrate Tests to TestPlatform
status: done
created: 2026-06-06
completed:
ref_decisions: [DEC-0032]
tags: [tests, platform, fixtures]
---
## Objective
Replace remaining test dependence on `Hardware::new()` and `HardwareBridge` with `TestPlatform` or narrower facade fixtures.
## Background
`DEC-0032` requires tests that need a full local platform fixture to use `TestPlatform`, not hidden `HardwareBridge` compatibility.
## Scope
### Included
- VM runtime tests.
- Firmware tests.
- Driver integration tests that still use monolithic hardware only as fixture.
- Host debugger tests where applicable.
### Excluded
- Do not remove production bridge until tests are migrated.
- Do not change behavior under test.
## Execution Steps
### Step 1 - Inventory test dependencies
**What:** Find all direct `Hardware::new()` and `HardwareBridge` test uses.
**How:** Use `rg` and classify by domain.
**File(s):** test modules across `crates/console` and `crates/host`.
### Step 2 - Migrate full-platform tests
**What:** Replace `Hardware::new()` with `TestPlatform`.
**How:** Use explicit facade accessors in assertions.
**File(s):** `crates/console/prometeu-system/src/services/vm_runtime/tests*.rs`, firmware tests.
### Step 3 - Migrate narrow tests
**What:** Replace full platform with narrower fixtures where only one domain is under test.
**How:** Use render/composer/audio/input/asset fixtures directly.
**File(s):** driver and runtime test modules.
## Test Requirements
### Unit Tests
- All migrated tests pass.
### Integration Tests
- `cargo test --workspace` or relevant workspace subset if full workspace is too broad.
### Manual Verification
- `rg "Hardware::new\\(|HardwareBridge" crates --glob '*test*'` shows no test dependency except tests explicitly covering legacy removal.
## Acceptance Criteria
- [ ] `TestPlatform` is the default full platform fixture.
- [ ] Tests no longer preserve `HardwareBridge` by habit.
- [ ] Narrow tests use narrower fixtures.
## Dependencies
- `PLN-0103`.
- `PLN-0107`.
## Risks
- Large mechanical changes can hide behavior regressions. Keep commits grouped by test domain.
@@ -1,91 +0,0 @@
---
id: PLN-0109
ticket: real-render-worker-establishment
title: Remove HardwareBridge and Update Specs
status: done
created: 2026-06-06
completed:
ref_decisions: [DEC-0032]
tags: [platform, cleanup, specs, hal]
---
## Objective
Remove `HardwareBridge` from the codebase and publish the new platform layer contract in specs.
## Background
`DEC-0032` explicitly forbids preserving `HardwareBridge` as final compatibility. After all domains and tests migrate, the bridge must be deleted.
## Scope
### Included
- Delete `HardwareBridge`.
- Remove exports/imports and adapters that only preserve bridge compatibility.
- Update canonical specs in English.
- Run validation and broad tests.
### Excluded
- Do not implement the real render worker.
- Do not change platform service semantics beyond cleanup.
## Execution Steps
### Step 1 - Delete bridge
**What:** Remove `HardwareBridge` trait and module.
**How:** Delete source file and remove exports/imports.
**File(s):** `crates/console/prometeu-hal/src/hardware_bridge.rs`, `crates/console/prometeu-hal/src/lib.rs`, all remaining imports.
### Step 2 - Remove compatibility adapters
**What:** Delete migration-only adapters.
**How:** Replace final references with direct platform services or remove dead code.
**File(s):** HAL, drivers, system, firmware, host modules touched by previous plans.
### Step 3 - Update specs
**What:** Document platform layer and removal of monolithic hardware bridge.
**How:** Update runtime/host/render specs in English.
**File(s):** `docs/specs/runtime/*.md` and related canonical specs.
### Step 4 - Validate and test
**What:** Run discussion validation and broad test suite.
**How:** Use `discussion validate` and cargo tests for affected crates.
**File(s):** repository root.
## Test Requirements
### Unit Tests
- HAL, drivers, firmware, system tests pass.
### Integration Tests
- Host desktop crate compiles/tests.
- Stress cartridge still runs through local platform path.
### Manual Verification
- `rg "HardwareBridge"` returns no production references.
- `rg "Hardware::new\\("` returns no runtime-facing dependency; any remaining use is local implementation detail or removed.
## Acceptance Criteria
- [ ] `HardwareBridge` is deleted.
- [ ] No production/runtime dependencies remain.
- [ ] Specs describe platform services/facades.
- [ ] Tests pass.
- [ ] `AGD-0043` can proceed without needing `&mut Hardware`, `&mut Gfx`, live `FrameComposer`, or mutable VM state in the worker.
## Dependencies
- `PLN-0107`.
- `PLN-0108`.
## Risks
- Removing the bridge too early will cause broad breakage. Only execute after dependency searches show all call sites have migrated.
@@ -1,79 +0,0 @@
---
id: PLN-0110
ticket: real-render-worker-establishment
title: Define Owned RGBA8888 Frame Contract
status: done
created: 2026-06-15
completed:
ref_decisions: [DEC-0033]
tags: [runtime, renderer, worker, hal, frame-contract]
---
## Briefing
`DEC-0033` requires the worker to publish an owned RGBA8888 frame that is independent of native window APIs. This plan defines that shared HAL contract before any worker implementation depends on it.
## Decisions de Origem
- `DEC-0033`: Real Render Worker Contract.
## Alvo
Introduce `OwnedRgba8888Frame` in `prometeu-hal` as the canonical worker-to-host published frame type.
## Escopo
- Add the shared frame type to HAL.
- Include frame id, ownership/epoch metadata, dimensions, stride, and owned `Vec<u32>` RGBA8888 pixels.
- Add constructors and validation helpers that keep dimensions, stride, and pixel length coherent.
- Add unit tests for layout and validation.
## Fora de Escopo
- No worker thread.
- No host upload/present integration.
- No resource bank access.
- No spec updates beyond code-facing rustdoc if useful.
## Plano de Execucao
### Step 1 - Add HAL frame module
**What:** Add `OwnedRgba8888Frame`.
**How:** Create a HAL module, likely `crates/console/prometeu-hal/src/owned_frame.rs` or equivalent, and export it from `lib.rs`.
**File(s):** `crates/console/prometeu-hal/src/lib.rs`, new HAL frame module.
### Step 2 - Define required fields
**What:** Encode the DEC-0033 frame contract.
**How:** Include `FrameId`, render ownership/epoch metadata compatible with `RenderSubmission`, `width`, `height`, `stride_pixels`, and `pixels: Vec<u32>`.
**File(s):** HAL frame module, existing render ownership types if reuse is needed.
### Step 3 - Add constructors and validation
**What:** Prevent malformed frame buffers from entering the worker-host boundary.
**How:** Add checked constructor(s) that reject zero dimensions, too-small stride, and pixel buffers shorter than `stride_pixels * height`.
**File(s):** HAL frame module.
### Step 4 - Add tests
**What:** Pin layout semantics.
**How:** Test valid construction, invalid stride, invalid pixel length, and that raw pixel values are preserved as RGBA8888 `u32`.
**File(s):** HAL frame module tests.
## Criterios de Aceite
- [ ] `OwnedRgba8888Frame` is exported by `prometeu-hal`.
- [ ] The type contains `FrameId`, ownership/epoch, width, height, `stride_pixels`, and `Vec<u32>` pixels.
- [ ] Invalid dimensions/stride/pixel length cannot be silently accepted by checked constructors.
- [ ] No native host/window/pixels/winit/SDL type appears in the HAL frame contract.
## Tests / Validacao
- `cargo test -p prometeu-hal`
- `rg "OwnedRgba8888Frame" crates/console/prometeu-hal -n`
## Riscos
- Reusing native pixel terminology could blur the logical RGBA8888 contract.
- Overfitting the frame type to current desktop upload code would leak host details into HAL.
@@ -1,79 +0,0 @@
---
id: PLN-0111
ticket: real-render-worker-establishment
title: Define Read-Only Render Resource Access
status: done
created: 2026-06-15
completed:
ref_decisions: [DEC-0033]
tags: [runtime, renderer, worker, hal, resources]
---
## Briefing
`DEC-0033` requires the worker backend to resolve render resources by stable ids through compact read-only access, without copying banks, snapshotting banks, requiring `Arc` in the public contract, or accessing mutable `Hardware`/`Gfx`/`FrameComposer`.
## Decisions de Origem
- `DEC-0033`: Real Render Worker Contract.
## Alvo
Define shared read-only render resource traits in HAL and implement them over existing local bank storage without changing bank ownership semantics.
## Escopo
- Define compact HAL traits for read-only glyph and scene bank access by id.
- Keep the public contract id-based and read-only.
- Implement the traits in the local driver/resource owner currently used by rendering.
- Add tests proving banks are read through the new interface.
## Fora de Escopo
- No worker thread.
- No bank copying or snapshotting.
- No public `Arc` requirement.
- No asset residency policy changes.
## Plano de Execucao
### Step 1 - Define HAL read-only traits
**What:** Add worker-facing resource access contracts.
**How:** Define traits for resolving glyph and scene banks by stable ids. Return borrowed read-only references or compact read-only views, not mutable handles.
**File(s):** `crates/console/prometeu-hal/src/*`, likely a new render resource module.
### Step 2 - Implement local resource access
**What:** Expose current local bank storage through the new traits.
**How:** Implement the read-only traits for the existing memory bank/resource owner used by `prometeu-drivers`.
**File(s):** `crates/console/prometeu-drivers/src/memory_banks.rs`, `frame_composer.rs`, or adjacent resource modules.
### Step 3 - Thread access through backend-facing APIs
**What:** Make future backends able to receive resource access without `Hardware`.
**How:** Add narrow parameters/types where needed so a backend can be given read-only resources independently from the full platform.
**File(s):** HAL contracts and driver modules touched above.
### Step 4 - Add resource access tests
**What:** Prove id lookup and read-only behavior.
**How:** Add tests for resident/missing glyph and scene banks through the new traits and verify no mutable API is exposed.
**File(s):** HAL/driver tests.
## Criterios de Aceite
- [ ] Worker-facing render resource access is defined in `prometeu-hal`.
- [ ] Resource access is by stable id and read-only.
- [ ] The public contract does not require `Arc`, bank copies, bank snapshots, `Hardware`, `Gfx`, or `FrameComposer`.
- [ ] Local driver storage implements the traits.
## Tests / Validacao
- `cargo test -p prometeu-hal -p prometeu-drivers`
- `rg "Arc<.*RenderResource|snapshot.*bank|&mut Hardware|&mut Gfx|FrameComposer" crates/console/prometeu-hal crates/console/prometeu-drivers -n`
## Riscos
- Returning concrete bank internals may overexpose driver implementation.
- Accidentally requiring `Arc` in the trait would make a storage strategy part of the public contract.
@@ -1,78 +0,0 @@
---
id: PLN-0112
ticket: real-render-worker-establishment
title: Define Render Worker Errors and Telemetry
status: done
created: 2026-06-15
completed:
ref_decisions: [DEC-0033]
tags: [runtime, renderer, worker, hal, telemetry]
---
## Briefing
`DEC-0033` requires typed worker/backend errors and telemetry that observes worker behavior without changing VM semantics.
## Decisions de Origem
- `DEC-0033`: Real Render Worker Contract.
## Alvo
Introduce the shared error and telemetry vocabulary required by the real worker.
## Escopo
- Define `RenderWorkerError` or equivalent shared error type.
- Define worker telemetry counters/snapshot shape.
- Integrate the new telemetry shape with existing render telemetry types where appropriate.
- Add tests for error/debug/copy/equality behavior and telemetry defaults.
## Fora de Escopo
- No worker lifecycle implementation.
- No thread-safe handoff.
- No host integration.
## Plano de Execucao
### Step 1 - Add worker error type
**What:** Define typed worker errors.
**How:** Add variants for backend unavailable, render failed, publish/present handoff failed, shutdown timeout, stale submission discarded, and worker panic/internal failure.
**File(s):** `crates/console/prometeu-hal/src/*` or `prometeu-system` if the type is not shared; prefer HAL if host/tests need it.
### Step 2 - Add telemetry snapshot
**What:** Define counters required by DEC-0033.
**How:** Include produced, replaced/dropped, consumed, published/presented, stale discarded, render failures, repeated frames, and shutdown timeouts.
**File(s):** existing telemetry/render manager modules or new worker telemetry module.
### Step 3 - Preserve existing telemetry compatibility
**What:** Avoid breaking existing render telemetry tests.
**How:** Map or extend current render telemetry without changing VM semantics or current counters unexpectedly.
**File(s):** `crates/console/prometeu-system/src/services/vm_runtime/render_manager.rs`, HAL telemetry modules as needed.
### Step 4 - Add tests
**What:** Pin type behavior.
**How:** Test default zero telemetry, counter increments through helper methods if added, and error formatting/debug behavior.
**File(s):** HAL/system tests.
## Criterios de Aceite
- [ ] Worker/backend failure has a typed error surface.
- [ ] Telemetry includes all DEC-0033 minimum counters.
- [ ] Existing render telemetry tests still pass.
- [ ] No worker/backend failure path relies on panic as the normal reporting model.
## Tests / Validacao
- `cargo test -p prometeu-hal -p prometeu-system`
- `rg "RenderWorkerError|shutdown_timeout|stale.*discard|repeat" crates/console -n`
## Riscos
- Splitting telemetry between too many structs may make final worker accounting inconsistent.
- Adding errors before call sites exist may create unused-code warnings if not scoped carefully.
@@ -1,80 +0,0 @@
---
id: PLN-0113
ticket: real-render-worker-establishment
title: Implement Thread-Safe Latest-Wins Handoff
status: done
created: 2026-06-15
completed:
ref_decisions: [DEC-0033]
tags: [runtime, renderer, worker, concurrency, handoff]
---
## Briefing
`DEC-0033` requires a thread-safe single-slot latest-wins handoff. The producer must replace pending work without waiting for rasterization or present, and the consumer must take ownership of the latest pending submission.
## Decisions de Origem
- `DEC-0033`: Real Render Worker Contract.
## Alvo
Add the real worker handoff primitive in `prometeu-system`, using explicit synchronization and deterministic tests.
## Escopo
- Implement a single-slot pending submission structure.
- Use `Mutex<Option<RenderSubmission>> + Condvar` or an equivalent explicit structure.
- Add producer publish/replace behavior and consumer wait/take behavior.
- Track replacement/drop telemetry.
## Fora de Escopo
- No worker thread controller lifecycle.
- No backend rendering.
- No host integration.
- No stale epoch publish behavior beyond storing ownership data already present in submissions.
## Plano de Execucao
### Step 1 - Add handoff module
**What:** Create the worker handoff primitive.
**How:** Add a module under `crates/console/prometeu-system/src/services/vm_runtime/`, for example `render_worker_handoff.rs`.
**File(s):** new system module, `mod.rs` exports.
### Step 2 - Implement publish replacement
**What:** Producer publishes owned `RenderSubmission`.
**How:** Lock the slot, replace any pending submission, increment replacement/drop counters when applicable, notify the condvar, and return immediately.
**File(s):** handoff module.
### Step 3 - Implement consumer wait/take
**What:** Consumer waits for work or shutdown signal.
**How:** Add wait/take APIs that block only the consumer side and return owned submissions.
**File(s):** handoff module.
### Step 4 - Add deterministic tests
**What:** Prove latest-wins and blocking boundaries.
**How:** Use threads, barriers, and condvars to prove producer replacement and consumer wake behavior without sleeps.
**File(s):** handoff module tests or `async_render_contract_tests.rs`.
## Criterios de Aceite
- [ ] Producer publish does not wait for consumer rasterization.
- [ ] Multiple pending publishes leave only the newest submission available.
- [ ] Replacements increment telemetry.
- [ ] Consumer can wait for work and is woken by publish.
- [ ] Tests do not use sleep as their primary synchronization proof.
## Tests / Validacao
- `cargo test -p prometeu-system render_worker_handoff`
- `cargo test -p prometeu-system`
## Riscos
- Holding the mutex while doing heavy work would violate non-blocking producer behavior.
- Condvar wait loops must handle spurious wakeups.
@@ -1,78 +0,0 @@
---
id: PLN-0114
ticket: real-render-worker-establishment
title: Add Deterministic Render Worker Test Harness
status: done
created: 2026-06-15
completed:
ref_decisions: [DEC-0033]
tags: [runtime, renderer, worker, tests, concurrency]
---
## Briefing
`DEC-0033` requires worker behavior to be proven without a native window and without fragile sleeps. This plan creates reusable deterministic test fixtures for the remaining worker plans.
## Decisions de Origem
- `DEC-0033`: Real Render Worker Contract.
## Alvo
Add a fake backend and synchronization harness capable of blocking render at controlled points, observing publication, and proving non-blocking VM/producer behavior.
## Escopo
- Create test-only synchronization helpers using barriers/condvars.
- Create a fake render backend shape that can block/fail/publish deterministically.
- Add helper functions for constructing owned render submissions and frames.
- Reuse the harness in later worker tests.
## Fora de Escopo
- No production worker lifecycle.
- No desktop host integration.
- No real GFX rasterization.
## Plano de Execucao
### Step 1 - Add test support module
**What:** Introduce deterministic worker test fixtures.
**How:** Add test-only helpers under `prometeu-system` worker tests or a local test module.
**File(s):** `crates/console/prometeu-system/src/services/vm_runtime/*`.
### Step 2 - Add controllable fake backend
**What:** Provide backend behavior for tests.
**How:** Fake backend can block at render start, unblock by test signal, return errors, and record published frames.
**File(s):** worker test module.
### Step 3 - Add submission/frame builders
**What:** Make tests concise and consistent.
**How:** Build Game/Shell submissions with explicit frame ids and ownership metadata; build `OwnedRgba8888Frame` fixtures.
**File(s):** worker test module.
### Step 4 - Add initial harness self-tests
**What:** Prove harness itself is deterministic.
**How:** Verify a test can block and release backend render without timing sleeps.
**File(s):** worker test module.
## Criterios de Aceite
- [ ] Tests can block worker backend render using deterministic synchronization.
- [ ] Tests can observe published `OwnedRgba8888Frame` values.
- [ ] Harness can inject backend errors.
- [ ] Harness helpers are scoped to tests or clearly internal.
## Tests / Validacao
- `cargo test -p prometeu-system render_worker`
- `rg "sleep\\(|thread::sleep" crates/console/prometeu-system/src/services/vm_runtime -n`
## Riscos
- Test harness code can become too coupled to implementation internals.
- Overly broad helpers can hide important assertions in later plans.
@@ -1,87 +0,0 @@
---
id: PLN-0115
ticket: real-render-worker-establishment
title: Implement Render Worker Controller Lifecycle
status: done
created: 2026-06-15
completed:
ref_decisions: [DEC-0033]
tags: [runtime, renderer, worker, lifecycle, concurrency]
---
## Briefing
`DEC-0033` requires a runtime-owned worker controller in `prometeu-system`, with stop signaling, bounded shutdown, pending/in-flight separation, typed errors, and telemetry.
## Decisions de Origem
- `DEC-0033`: Real Render Worker Contract.
## Alvo
Implement the production worker controller lifecycle around the handoff primitive and backend trait shape.
## Escopo
- Add worker controller type in `prometeu-system`.
- Spawn and join a worker thread.
- Add configurable shutdown timeout with initial default `250ms`.
- Add stop token/wakeup behavior.
- Preserve pending/in-flight separation.
- Capture panic as typed internal failure.
## Fora de Escopo
- No desktop host presentation.
- No full runtime tick integration.
- No stale epoch/repeat behavior beyond lifecycle foundations.
## Plano de Execucao
### Step 1 - Define controller and config
**What:** Add worker controller and configuration.
**How:** Include shutdown timeout, default `250ms`, and hooks for backend and handoff dependencies.
**File(s):** new `render_worker.rs` or similar in `prometeu-system`.
### Step 2 - Implement start and run loop
**What:** Start worker execution.
**How:** Spawn a thread that waits on the handoff, takes submissions, marks in-flight locally, calls backend, and publishes results through a frame sink abstraction.
**File(s):** worker controller module.
### Step 3 - Implement stop and bounded join
**What:** Make shutdown observable and bounded.
**How:** Signal stop, wake the condvar, join with timeout strategy available in Rust implementation, and return/report `ShutdownTimeout` when exceeded.
**File(s):** worker controller module.
### Step 4 - Add panic containment
**What:** Convert worker panic into typed failure.
**How:** Use panic containment around backend calls or worker thread join result and update telemetry/errors.
**File(s):** worker controller module.
### Step 5 - Add lifecycle tests
**What:** Prove start/stop/join behavior.
**How:** Use deterministic harness from `PLN-0114`.
**File(s):** worker tests.
## Criterios de Aceite
- [ ] Worker controller lives in `prometeu-system`.
- [ ] Controller can start and stop a real worker thread.
- [ ] Shutdown wakes waiting worker and completes within configured bound in tests.
- [ ] Shutdown timeout is typed and observable.
- [ ] Worker panic is captured as typed internal failure.
## Tests / Validacao
- `cargo test -p prometeu-system render_worker`
- `cargo test -p prometeu-system`
## Riscos
- Rust thread join timeout requires careful design because standard `JoinHandle::join` has no timeout.
- Backend ownership must be `'static + Send` without leaking host-specific types into system contracts.
@@ -1,78 +0,0 @@
---
id: PLN-0116
ticket: real-render-worker-establishment
title: Implement Fake Local Render Backend
status: done
created: 2026-06-15
completed:
ref_decisions: [DEC-0033]
tags: [runtime, renderer, worker, backend, drivers]
---
## Briefing
`DEC-0033` requires fake/local backend behavior before desktop integration so worker semantics can be proven without a window.
## Decisions de Origem
- `DEC-0033`: Real Render Worker Contract.
## Alvo
Implement backend contracts that consume `RenderSubmission` plus read-only resources and produce `OwnedRgba8888Frame`.
## Escopo
- Define or finalize a backend trait for worker rendering.
- Add a fake backend for deterministic tests.
- Add a local framebuffer backend that can rasterize through existing driver/GFX logic without exposing mutable `Hardware` as the worker contract.
- Verify output frame ownership and pixels.
## Fora de Escopo
- No desktop upload/present.
- No runtime tick integration.
- No resource mutation policy changes.
## Plano de Execucao
### Step 1 - Define backend trait
**What:** Encode backend consumption contract.
**How:** Trait consumes `RenderSubmission` and read-only resource access and returns `OwnedRgba8888Frame` or `RenderWorkerError`.
**File(s):** HAL if shared, or system if internal; prefer HAL if host/drivers implement it.
### Step 2 - Implement fake backend
**What:** Provide test backend.
**How:** Fake backend returns deterministic frames, can block through harness, and can return typed errors.
**File(s):** system test module or driver test utility.
### Step 3 - Implement local framebuffer backend
**What:** Provide non-window raster backend.
**How:** Use existing GFX rendering internally to turn submissions into `OwnedRgba8888Frame`, but expose only the backend trait and read-only resources.
**File(s):** `prometeu-drivers` rendering modules, possibly a new backend module.
### Step 4 - Add output tests
**What:** Prove frame content and metadata.
**How:** Render simple Game2D and ShellUi submissions and compare `OwnedRgba8888Frame` pixels/metadata.
**File(s):** driver/system tests.
## Criterios de Aceite
- [ ] Backend trait does not expose mutable `Hardware`, `Gfx`, `FrameComposer`, or VM state.
- [ ] Fake backend supports deterministic blocking/error behavior.
- [ ] Local backend produces `OwnedRgba8888Frame`.
- [ ] Game2D and ShellUi submissions can produce frame output without a native window.
## Tests / Validacao
- `cargo test -p prometeu-drivers -p prometeu-system`
- `rg "&mut Hardware|&mut Gfx|FrameComposer" crates/console/prometeu-hal crates/console/prometeu-system/src/services/vm_runtime -n`
## Riscos
- Local backend may be tempted to reuse `Hardware` directly as the public worker contract.
- Resource access gaps may surface when moving from fake to local rasterization.
@@ -1,80 +0,0 @@
---
id: PLN-0117
ticket: real-render-worker-establishment
title: Integrate Runtime Submission With Worker
status: done
created: 2026-06-15
completed:
ref_decisions: [DEC-0033]
tags: [runtime, renderer, worker, integration]
---
## Briefing
`DEC-0033` requires VM/render production to submit work without blocking on worker consumption. This plan connects runtime frame closure to the worker handoff while preserving local synchronous fallback.
## Decisions de Origem
- `DEC-0033`: Real Render Worker Contract.
## Alvo
Route eligible Game render submissions from `RenderManager` into the real worker handoff and keep Shell/local paths correct.
## Escopo
- Add worker-capable runtime path.
- Submit owned `RenderSubmission` to the handoff.
- Preserve AppMode policy: Game may use worker; Shell remains local unless a future decision changes it.
- Keep local synchronous fallback.
- Prove VM tick returns without waiting for worker backend completion.
## Fora de Escopo
- No desktop host presentation.
- No final stale/repeat behavior beyond integration needed for basic worker use.
- No spec edits.
## Plano de Execucao
### Step 1 - Add worker ownership to runtime state
**What:** Store worker controller/handoff in runtime-owned state.
**How:** Extend `VirtualMachineRuntime` or `RenderManager` integration points without moving policy to host.
**File(s):** `crates/console/prometeu-system/src/services/vm_runtime/tick.rs`, `render_manager.rs`, worker modules.
### Step 2 - Submit Game frames to worker handoff
**What:** Replace local worker prototype path with real worker submission.
**How:** On eligible Game frame closure, publish owned `RenderSubmission` into the handoff and return to VM tick without waiting for consumption.
**File(s):** runtime tick/render manager integration.
### Step 3 - Preserve local fallback
**What:** Keep current local synchronous behavior available.
**How:** Use existing `RenderConsumerPath`/policy or update it to select local fallback when worker is disabled/unavailable.
**File(s):** `render_manager.rs`, `tick.rs`.
### Step 4 - Add non-blocking tests
**What:** Prove VM producer does not block.
**How:** Use harness to hold backend render, run tick/publish additional frames, assert return and replacement telemetry.
**File(s):** runtime worker tests.
## Criterios de Aceite
- [ ] Game render submissions can be sent to the real worker handoff.
- [ ] VM tick does not wait for worker rasterization.
- [ ] Shell/local policy remains unchanged.
- [ ] Local synchronous fallback still passes existing tests.
- [ ] Replacement telemetry increments when producer outruns worker.
## Tests / Validacao
- `cargo test -p prometeu-system`
- `cargo test -p prometeu-firmware`
## Riscos
- Accidentally making frame closure wait for worker consumption would violate DEC-0033.
- Mixing Shell lifecycle rendering into the worker path too early would broaden scope.
@@ -1,85 +0,0 @@
---
id: PLN-0118
ticket: real-render-worker-establishment
title: Add Stale Epoch and Repeat Frame Behavior
status: done
created: 2026-06-15
completed:
ref_decisions: [DEC-0033]
tags: [runtime, renderer, worker, ownership, telemetry]
---
## Briefing
`DEC-0033` requires the worker to discard stale in-flight frames before publication and repeat the last published `OwnedRgba8888Frame` rather than recomposing.
## Decisions de Origem
- `DEC-0033`: Real Render Worker Contract.
## Alvo
Complete ownership/epoch checks and repeat-last-published-frame behavior for the worker path.
## Escopo
- Add shared active ownership/epoch observation for worker publication checks.
- Discard stale in-flight frames before publication.
- Store and expose the latest published `OwnedRgba8888Frame`.
- Implement repeat-last-frame behavior and telemetry.
## Fora de Escopo
- No desktop upload/present.
- No new AppMode policy.
- No native window invalidation changes.
## Plano de Execucao
### Step 1 - Expose ownership/epoch to worker
**What:** Let worker validate in-flight submissions before publishing.
**How:** Add a thread-safe snapshot or handle that the worker can read without mutating runtime state.
**File(s):** `render_manager.rs`, worker modules.
### Step 2 - Implement stale discard
**What:** Prevent stale pixels from publication.
**How:** Before publishing frame output, compare submission ownership/epoch with active ownership/epoch; discard on mismatch and increment telemetry.
**File(s):** worker controller module.
### Step 3 - Store latest published frame
**What:** Make the latest valid frame available to host/fallback tests.
**How:** Add a published-frame slot distinct from pending submission and in-flight work.
**File(s):** worker controller or published frame module.
### Step 4 - Implement repeat behavior
**What:** Repeat last valid frame without recomposition.
**How:** Add API to fetch/reuse the latest published `OwnedRgba8888Frame`; increment repeat telemetry when cadence requests reuse.
**File(s):** worker modules, tests.
### Step 5 - Add tests
**What:** Prove stale discard and repeat.
**How:** Use harness to hold in-flight work, change owner/epoch, release backend, and assert no publication; separately assert repeat returns last frame.
**File(s):** worker tests.
## Criterios de Aceite
- [ ] Worker checks active owner/epoch before publishing.
- [ ] Stale in-flight frames are discarded and counted.
- [ ] Latest published frame is an `OwnedRgba8888Frame`.
- [ ] Repeat uses the last published frame and does not recompose.
- [ ] Tests cover stale discard and repeat deterministically.
## Tests / Validacao
- `cargo test -p prometeu-system render_worker`
- `cargo test -p prometeu-system`
## Riscos
- Reading active ownership from the wrong layer may reintroduce mutable runtime coupling.
- Repeat behavior must not hide render failures unless telemetry records them.
@@ -1,81 +0,0 @@
---
id: PLN-0119
ticket: real-render-worker-establishment
title: Integrate Desktop Host Worker Presentation
status: done
created: 2026-06-15
completed:
ref_decisions: [DEC-0033]
tags: [runtime, renderer, worker, host, desktop]
---
## Briefing
`DEC-0033` is not complete until the real host path uses the worker. This plan integrates desktop presentation with the latest published `OwnedRgba8888Frame` while keeping native upload/present in the host event loop.
## Decisions de Origem
- `DEC-0033`: Real Render Worker Contract.
## Alvo
Make `prometeu-host-desktop-winit` present frames produced by the worker path.
## Escopo
- Wire the host to enable/use the worker path.
- Read the latest published `OwnedRgba8888Frame`.
- Upload/copy RGBA8888 pixels to the existing pixels/winit presentation surface in the event loop.
- Preserve host invalidation and redraw behavior.
- Keep worker free of native window dependencies.
## Fora de Escopo
- No SDL migration.
- No change to logical pixel format.
- No change to input/audio/filesystem host behavior.
## Plano de Execucao
### Step 1 - Add host access to published frame
**What:** Expose latest worker-published frame to desktop host.
**How:** Add an API through runtime/platform integration that returns or copies the latest `OwnedRgba8888Frame` for host upload.
**File(s):** system worker modules, host runner integration.
### Step 2 - Upload RGBA8888 in event loop
**What:** Present worker output through existing host surface.
**How:** Convert/copy `Vec<u32>` RGBA8888 into the existing pixels frame buffer using existing RGBA8888 utility conventions.
**File(s):** `crates/host/prometeu-host-desktop-winit/src/runner.rs`, `utilities.rs` if needed.
### Step 3 - Preserve invalidation model
**What:** Keep host redraw policy coherent.
**How:** Trigger redraw when a new frame is published or host invalidation occurs; repeat uses the last published frame.
**File(s):** host runner/presentation state.
### Step 4 - Add host tests
**What:** Prove host consumes worker-published frame.
**How:** Add unit tests for RGBA8888 copy/upload helper and presentation state transitions without opening a native window.
**File(s):** host tests.
## Criterios de Aceite
- [ ] Desktop host presents the latest worker-published `OwnedRgba8888Frame`.
- [ ] Worker code does not import winit, pixels, SDL, swapchain, native texture, or window APIs.
- [ ] Host event loop remains responsible for native present.
- [ ] Existing host invalidation tests still pass.
- [ ] Real host path can run with worker enabled.
## Tests / Validacao
- `cargo test -p prometeu-host-desktop-winit`
- `cargo test -p prometeu-system -p prometeu-firmware`
- Manual run of a simple cartridge through desktop host with worker path enabled.
## Riscos
- Upload/copy can accidentally reinterpret RGBA8888 as native endian bytes.
- Host redraw policy can regress into perpetual polling if publication/invalidation are not kept separate.
@@ -1,79 +0,0 @@
---
id: PLN-0120
ticket: real-render-worker-establishment
title: Update Real Render Worker Specs
status: done
created: 2026-06-15
completed:
ref_decisions: [DEC-0033]
tags: [runtime, renderer, worker, specs]
---
## Briefing
`DEC-0033` requires canonical runtime specs to document the real worker contract after implementation publishes the behavior.
## Decisions de Origem
- `DEC-0033`: Real Render Worker Contract.
## Alvo
Update English canonical specs to describe `OwnedRgba8888Frame`, worker handoff, host presentation split, read-only bank access, shutdown, errors, and telemetry.
## Escopo
- Update GFX/render specs.
- Update portability/host presentation specs.
- Update host ABI/syscall specs if worker behavior affects published runtime surfaces.
- Ensure no spec says the worker owns native window present.
## Fora de Escopo
- No new architecture beyond `DEC-0033`.
- No lesson writing.
- No implementation changes except documentation.
## Plano de Execucao
### Step 1 - Update GFX spec
**What:** Document worker frame publication.
**How:** Add `OwnedRgba8888Frame`, RGBA8888 `Vec<u32>` semantics, latest published frame, and repeat behavior.
**File(s):** `docs/specs/runtime/04-gfx-peripheral.md`.
### Step 2 - Update portability spec
**What:** Document worker/host split.
**How:** State that worker produces owned RGBA8888 frames and host event loop performs native upload/present.
**File(s):** `docs/specs/runtime/11-portability-and-cross-platform-execution.md`.
### Step 3 - Update concurrency/events spec if needed
**What:** Document handoff and shutdown behavior.
**How:** Add single-slot latest-wins, bounded shutdown, and non-blocking producer semantics where concurrency is specified.
**File(s):** `docs/specs/runtime/09-events-and-concurrency.md` or adjacent runtime spec.
### Step 4 - Update README/index references
**What:** Keep spec map discoverable.
**How:** Add any needed cross-reference to worker/render sections.
**File(s):** `docs/specs/runtime/README.md`.
## Criterios de Aceite
- [ ] Specs define `OwnedRgba8888Frame`.
- [ ] Specs state worker does not own native window present.
- [ ] Specs state producer does not block on worker rasterization/present.
- [ ] Specs document read-only bank access by id.
- [ ] Specs document bounded shutdown and typed error expectations.
## Tests / Validacao
- `rg "OwnedRgba8888Frame|latest-wins|shutdown|read-only" docs/specs/runtime -n`
- `discussion validate`
## Riscos
- Updating specs before implementation may accidentally publish intent as completed behavior; execute after code plans that establish the behavior.
- Spec wording must remain English and normative.
@@ -1,102 +0,0 @@
---
id: PLN-0121
ticket: real-render-worker-establishment
title: Final Worker Path Validation and Hardening
status: done
created: 2026-06-15
completed:
ref_decisions: [DEC-0033]
tags: [runtime, renderer, worker, validation, hardening]
---
## Briefing
`DEC-0033` is complete only when the worker functions on the real host path and the contract is proven end to end. This plan performs final validation, residue scans, and hardening before housekeeping.
## Decisions de Origem
- `DEC-0033`: Real Render Worker Contract.
## Alvo
Prove the real render worker path satisfies DEC-0033 across HAL, system, drivers, firmware, host, specs, and tests.
## Escopo
- Run broad test suites.
- Add missing edge tests found during validation.
- Scan for forbidden coupling.
- Verify host real path uses worker.
- Verify local fallback still works.
- Prepare evidence for discussion housekeeping.
## Fora de Escopo
- No new worker architecture.
- No SDL migration.
- No unrelated performance tuning.
## Plano de Execucao
### Step 1 - Run full affected test suite
**What:** Validate all touched crates.
**How:** Run workspace tests and focused worker/host tests.
**File(s):** repository root.
### Step 2 - Run coupling residue scans
**What:** Enforce DEC-0033 boundaries.
**How:** Search worker/system/HAL code for native window dependencies, mutable hardware/GFX/composer leaks, bank copying/snapshot terminology, and sleeps in concurrency tests.
**File(s):** repository root.
### Step 3 - Add missing hardening tests
**What:** Close any discovered gaps.
**How:** Add focused tests for missing telemetry/error/shutdown/host-path cases.
**File(s):** affected test modules.
### Step 4 - Verify host path
**What:** Prove desktop host uses worker output.
**How:** Run host tests and a manual/simple cartridge path with worker enabled; record evidence in final summary.
**File(s):** host runner and runtime integration.
### Step 5 - Prepare housekeeping evidence
**What:** Make `DSC-0042` ready for final lesson/housekeeping.
**How:** Record completed plan state and validation evidence for later `discussion-housekeep`.
**File(s):** discussion artifacts if needed.
## Criterios de Aceite
- [ ] `cargo test --workspace` passes.
- [ ] Focused worker, system, drivers, firmware, and host tests pass.
- [ ] Residue scans show worker code does not depend on native window APIs.
- [ ] Residue scans show worker boundary does not expose `&mut Hardware`, `&mut Gfx`, live `FrameComposer`, or mutable VM state.
- [ ] Desktop host path uses the real worker output.
- [ ] Local fallback still works.
- [ ] `discussion validate` passes.
## Tests / Validacao
- `cargo test --workspace`
- `cargo test -p prometeu-system -p prometeu-drivers -p prometeu-hal -p prometeu-firmware -p prometeu-host-desktop-winit`
- `discussion validate`
- `rg "winit|pixels|SDL|swapchain|native texture" crates/console/prometeu-system crates/console/prometeu-hal -n`
- `rg "&mut Hardware|&mut Gfx|FrameComposer" crates/console/prometeu-system/src/services/vm_runtime crates/console/prometeu-hal -n`
- `rg "thread::sleep|sleep\\(" crates/console/prometeu-system/src/services/vm_runtime -n`
## Riscos
- Final validation may expose earlier plan gaps; fix them in the narrowest affected plan/module.
- Manual host evidence can be flaky if tied to native window availability; keep automated host-unit evidence as the primary gate.
## Validation Evidence
- `cargo test --workspace`: passed.
- `cargo test -p prometeu-system -p prometeu-drivers -p prometeu-hal -p prometeu-firmware -p prometeu-host-desktop-winit`: passed.
- Native API coupling scan for worker/runtime console code: no `winit`, `pixels`, SDL, swapchain, or native texture API references found.
- Mutable boundary scan for worker/runtime console code: no `&mut Hardware`, `&mut Gfx`, or concrete live `FrameComposer` references found.
- Timing scan for render worker runtime tests: no `thread::sleep` / `sleep(` usage found.
- Added host-unit evidence that worker frame presentation is restricted to `GameRunning`; Shell/Hub paths keep local presentation behavior.