prometeu-runtime/discussion/workflow/decisions/DEC-0032-platform-layer-and-hardwarebridge-elimination.md

id	ticket	title	status	created	accepted	agenda	plans	tags
DEC-0032	real-render-worker-establishment	Platform Layer and HardwareBridge Elimination	accepted	2026-06-06		AGD-0042	PLN-0098 PLN-0099 PLN-0100 PLN-0101 PLN-0102 PLN-0103 PLN-0104 PLN-0105 PLN-0106 PLN-0107 PLN-0108 PLN-0109	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.