199 lines
9.6 KiB
Markdown
199 lines
9.6 KiB
Markdown
---
|
|
id: DEC-0032
|
|
ticket: real-render-worker-establishment
|
|
title: Platform Layer and HardwareBridge Elimination
|
|
status: accepted
|
|
created: 2026-06-06
|
|
accepted:
|
|
agenda: AGD-0042
|
|
plans: [PLN-0098, PLN-0099, PLN-0100, PLN-0101, PLN-0102, PLN-0103, PLN-0104, PLN-0105, PLN-0106, PLN-0107, PLN-0108, PLN-0109]
|
|
tags: [runtime, platform, hardware, host, hal, renderer, architecture]
|
|
---
|
|
|
|
## Status
|
|
|
|
Decision draft emitted from accepted agenda `AGD-0042`.
|
|
|
|
This decision is ready for review. Once accepted, it becomes the normative contract for plans that prepare Prometeu's platform layer before the real render worker work in `AGD-0043`.
|
|
|
|
## Contexto
|
|
|
|
`DEC-0031` established the VM/render boundary: closed render submissions, single-slot handoff, frame pacing, AppMode policy, ownership epoch, and render telemetry.
|
|
|
|
The current implementation still depends on `HardwareBridge`, a monolithic trait that exposes render, composer, `Gfx`, audio, input, touch, assets, frame begin, and presentation through one runtime-facing object. That bridge was useful as an early abstraction, but it is no longer sufficient for a high-quality handheld-style runtime.
|
|
|
|
The goal is no longer to make `HardwareBridge` the permanent host-implemented interface. The goal is to replace it with an explicit platform layer made of domain services/facades. Runtime code should depend on stable platform contracts; host/board code should provide concrete implementations.
|
|
|
|
This decision prepares the platform boundary. It does not implement the real render worker. Worker establishment remains scoped to `AGD-0043`.
|
|
|
|
## Decisao
|
|
|
|
Prometeu SHALL replace the monolithic `HardwareBridge` model with a platform layer composed of explicit domain services/facades.
|
|
|
|
`HardwareBridge` SHALL NOT survive as a final compatibility contract. It MAY exist only as temporary migration scaffold. The end state MUST remove `HardwareBridge` and all production/runtime dependencies on it.
|
|
|
|
The migration MAY begin with render, because render blocks the real worker path, but it MUST NOT stop there. The migration MUST cover every domain currently coupled through `HardwareBridge`: render, Game2D frame composition, audio, input/touch, assets/storage, clock/pacing, and telemetry where applicable.
|
|
|
|
The first implementation wave SHALL prepare render-worker-safe boundaries without introducing the real worker yet:
|
|
|
|
- introduce an owned `RenderSubmissionSink`;
|
|
- introduce minimal typed render submission errors;
|
|
- remove immediate framebuffer writes from `gfx2d` and `gfxui` syscalls;
|
|
- move Game2D frame composition into a logical-side `Game2DFrameComposer` service/facade;
|
|
- replace test fixtures centered on `Hardware::new()` with `TestPlatform`.
|
|
|
|
## Rationale
|
|
|
|
A handheld-quality runtime needs clear separation between platform policy and board/host implementation.
|
|
|
|
The runtime/OS owns:
|
|
|
|
- lifecycle and AppMode policy;
|
|
- VM execution;
|
|
- frame pacing;
|
|
- render ownership and handoff;
|
|
- logical frame composition;
|
|
- command buffers;
|
|
- resource visibility policy;
|
|
- telemetry semantics.
|
|
|
|
The host/board implementation owns:
|
|
|
|
- window/surface or physical framebuffer;
|
|
- concrete present implementation;
|
|
- physical input events;
|
|
- audio backend;
|
|
- IO/storage backend;
|
|
- host threads, cores, DMA, or coprocessor mapping.
|
|
|
|
A single `HardwareBridge` encourages accidental coupling. It lets VM syscalls, firmware, Hub, renderer, audio, input, assets, and present share the same mutable object. That model makes it too easy for future worker work to pass `&mut Hardware`, `&mut Gfx`, or live `FrameComposer` state across the render boundary.
|
|
|
|
Explicit facades make dependencies visible and testable. They also let each domain evolve with the lifecycle, threading, and error semantics it actually needs.
|
|
|
|
## Invariantes / Contrato
|
|
|
|
### 1. No final `HardwareBridge`
|
|
|
|
`HardwareBridge` MUST be removed from the final architecture of this migration.
|
|
|
|
During migration, code MAY use adapters or temporary accessors to bridge old and new APIs. Those adapters MUST be treated as implementation scaffolding, not as new public/runtime architecture.
|
|
|
|
`HardwareBridge` MUST NOT inherit the new facades as a way to preserve itself as a permanent aggregate contract.
|
|
|
|
### 2. Facades live at the right layer
|
|
|
|
Contracts/facades SHALL live in `prometeu-hal`.
|
|
|
|
Local/default and test implementations SHALL live in `prometeu-drivers` unless a domain has a stronger existing home.
|
|
|
|
Operational integration and ownership orchestration SHALL live in `prometeu-system` and host crates.
|
|
|
|
### 3. Render submission is owned
|
|
|
|
`RenderSubmissionSink` SHALL accept owned `RenderSubmission` values.
|
|
|
|
The owned contract is required because asynchronous handoff transfers ownership to a consumer. Local/synchronous paths MAY adapt internally, but the facade MUST be compatible with future worker handoff.
|
|
|
|
### 4. Render submission errors are typed
|
|
|
|
The preparation work SHALL introduce a minimal typed error surface for submission/render publication.
|
|
|
|
The API MUST NOT be born infallible if the next worker stage will immediately need typed failure. Panic containment may remain as a safety net, but normal backend failure should have an explicit result type.
|
|
|
|
### 5. `gfx2d` and `gfxui` syscalls buffer commands only
|
|
|
|
`gfx2d.*` and `gfxui.*` syscalls MUST NOT mutate the framebuffer immediately.
|
|
|
|
Those syscalls SHALL record commands into the appropriate logical command buffer. Pixels change only when a closed render submission is consumed/published by the render path.
|
|
|
|
The first regression tests MUST include `gfx2d.clear` and `gfx2d.draw_text` proving that syscalls buffer commands and presentation happens only after frame closure/publication.
|
|
|
|
### 6. Game2D composition is logical-side state
|
|
|
|
`bind_scene`, `set_camera`, `emit_sprite`, and `close_game2d_packet` are logical frame preparation, not physical backend behavior.
|
|
|
|
The migration SHALL introduce `Game2DFrameComposer` as the logical-side service/facade for Game2D frame composition. Its implementation may move in phases, but it MUST NOT remain conceptually part of a physical render backend.
|
|
|
|
### 7. Tests use `TestPlatform`
|
|
|
|
Tests that need a full local platform fixture SHALL migrate toward `TestPlatform`.
|
|
|
|
`TestPlatform` SHOULD keep tests ergonomic while making dependencies explicit through the new facades. It MUST NOT preserve `HardwareBridge` as hidden compatibility.
|
|
|
|
### 8. Render may migrate first, but the migration is complete only when every domain is moved
|
|
|
|
The render path MAY be migrated first.
|
|
|
|
The architecture is not complete until audio, input/touch, assets/storage, clock/pacing, telemetry where applicable, firmware, Hub, runtime, host desktop, and tests no longer depend on `HardwareBridge`.
|
|
|
|
## Impactos
|
|
|
|
### Spec
|
|
|
|
Specs need to describe the platform layer as explicit services/facades rather than a monolithic hardware bridge.
|
|
|
|
Render specifications must state that `gfx2d`/`gfxui` syscalls buffer commands and that framebuffer mutation occurs through render submission consumption/publication.
|
|
|
|
### Runtime
|
|
|
|
Runtime code must stop depending on `&mut dyn HardwareBridge`.
|
|
|
|
VM dispatch must stop using `hw.gfx_mut()` for immediate drawing. Runtime frame closure must depend on logical services such as `Game2DFrameComposer` and publication facades such as `RenderSubmissionSink`.
|
|
|
|
### HAL
|
|
|
|
`prometeu-hal` must define the stable contracts for the platform layer.
|
|
|
|
At minimum, the first wave needs `RenderSubmissionSink` and its typed error. Later waves should define or refine composer, audio, input/touch, assets/storage, clock/pacing, and telemetry facades.
|
|
|
|
### Drivers
|
|
|
|
`prometeu-drivers` should provide local/default implementations and `TestPlatform`.
|
|
|
|
The existing `prometeu_drivers::Hardware` may be used as a migration source, but it must not remain the final runtime-facing architecture.
|
|
|
|
### Host
|
|
|
|
Host crates must move from directly owning and exposing `Hardware` as the runtime's universal bridge toward implementing platform services.
|
|
|
|
The desktop host may remain the first concrete integration, but the contracts must remain portable to handheld board support, emulator, web, or coprocessor/DMA implementations.
|
|
|
|
### Firmware / Hub
|
|
|
|
Firmware and Hub must migrate away from `publish_render_submission` on `HardwareBridge` and toward explicit render submission publication/platform services.
|
|
|
|
### Tests
|
|
|
|
Tests must migrate from direct `Hardware::new()` dependence to `TestPlatform` or narrower facade-specific fixtures.
|
|
|
|
Tests must be updated where they assume immediate framebuffer mutation from `gfx2d`/`gfxui` syscalls.
|
|
|
|
## Referencias
|
|
|
|
- `AGD-0042`: Host Hardware and Render Boundary Preparation.
|
|
- `AGD-0043`: Real Render Worker Establishment.
|
|
- `DEC-0031`: VM and Render Parallel Execution Boundary.
|
|
- `LSN-0048`: Render Workers Need a Closed Packet Contract.
|
|
|
|
## Propagacao Necessaria
|
|
|
|
Create implementation plans before editing specs or code.
|
|
|
|
Recommended plan sequence:
|
|
|
|
1. introduce `RenderSubmissionSink` and minimal typed submit error;
|
|
2. migrate local render publication away from `HardwareBridge`;
|
|
3. remove immediate framebuffer writes from `gfx2d`/`gfxui` syscalls and update tests;
|
|
4. introduce `Game2DFrameComposer` as logical-side service/facade;
|
|
5. introduce `RuntimePlatform`/`Platform` and `TestPlatform`;
|
|
6. migrate firmware, Hub, runtime, host desktop, and tests to explicit facades;
|
|
7. migrate remaining domains: audio, input/touch, assets/storage, clock/pacing, telemetry as needed;
|
|
8. remove `HardwareBridge`;
|
|
9. update specs and lessons after implementation publishes the new structure.
|
|
|
|
`AGD-0043` SHOULD NOT move to implementation until this decision has produced enough platform boundary work that a render worker can be built without `&mut Hardware`, `&mut Gfx`, live `FrameComposer`, or mutable VM state crossing into the worker.
|
|
|
|
## Revision Log
|
|
|
|
- 2026-06-06: Initial decision draft generated from accepted `AGD-0042`.
|