prometeu-runtime/discussion/workflow/plans/PLN-0048-minimal-system-hub-pipeline.md

id	ticket	title	status	created	completed	ref_decisions	tags
PLN-0048	runtime-mode-separation-game-system	Minimal System Hub Pipeline	done	2026-05-14		DEC-0023	runtime firmware hub system-apps window-manager

Briefing

This plan moves focused System execution out of the game-oriented frame path and into a minimal Runtime/Hub pipeline. The pipeline may initially be thin, but it must be named, testable, and owned by the Hub/WindowManager domain.

Decisions de Origem

• DEC-0023 - System Pipeline Separation.

Alvo

Create a minimal System profile execution path that handles system execution, events, and presentation through Runtime/Hub concepts instead of the game pipeline.

Escopo

• Add a small system pipeline entry point owned by prometeu_system or the firmware Hub domain.
• Move focused system VM ticking from generic HubHomeStep inline logic into that entry point.
• Keep rendering oriented around PrometeuHub and WindowManager.
• Preserve the current minimal behavior where a focused system window may tick the VM and render hub windows.

Fora de Escopo

• No final component tree, invalidation model, transition model, lifecycle contract, or multitasking scheduler.
• No public PBS ABI.
• No game pipeline changes.

Plano de Execucao

Step 1 - Define the minimal system pipeline API

What: Introduce a function/type that represents one system-profile update. How: Create a small API that accepts the runtime, VM, input signals, hardware, and hub/window state needed today, and returns an optional CrashReport. File(s): crates/console/prometeu-system/src/programs/prometeu_hub/prometeu_hub.rs, possible new module under crates/console/prometeu-system/src/programs/prometeu_hub/.

Step 2 - Move focused system ticking behind the pipeline API

What: Remove direct focused-system ctx.os.tick(...) calls from hub-home or system-running firmware code. How: Replace inline ticking with the new Runtime/Hub pipeline call. Keep behavior equivalent: hub GUI updates, focused window handling, system app tick, hub render, present. File(s): crates/console/prometeu-firmware/src/firmware/firmware_step_hub_home.rs, new system-running step from PLN-0047.

Step 3 - Keep game surfaces private to the game profile

What: Ensure the system pipeline does not expose game composition APIs as its public contract. How: The system pipeline may temporarily use existing internal hardware presentation to preserve behavior, but its public entry point must be named around hub/system concepts and must not accept or return FrameComposer, game banks, sprites, or game input abstractions. File(s): crates/console/prometeu-system/src/programs/prometeu_hub/, crates/console/prometeu-firmware/src/firmware/.

Step 4 - Add focused-system pipeline tests

What: Prove the system pipeline is invoked for focused system windows. How: Add tests using existing test support or fakes to assert that a focused system app uses the system pipeline call and returns crashes through the system state, not through GameRunningStep. File(s): crates/console/prometeu-firmware/src/firmware/firmware.rs, crates/console/prometeu-system/src/programs/prometeu_hub/.

Criterios de Aceite

• Focused System execution is behind a Runtime/Hub-named pipeline entry point.
• Firmware no longer embeds the focused system VM tick as anonymous hub-home logic.
• Game-running code is not modified except for compile integration.
• The system pipeline remains minimal and does not define deferred WindowManager contracts.

Tests / Validacao

• cargo test -p prometeu-firmware
• cargo test -p prometeu-system
• Manual smoke run of a System cartridge should show the hub/window path still presents.

Riscos

• The current system window rendering is simple and hardware-backed; the plan allows internal reuse while preventing it from becoming the public system ABI.
• Test support may need small fakes to observe routing without introducing broad runtime refactors.