Real Render Worker Establishment
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
This commit is contained in:
@@ -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.
|
||||
Reference in New Issue
Block a user