---
id: PLN-0048
ticket: runtime-mode-separation-game-system
title: Minimal System Hub Pipeline
status: open
created: 2026-05-14
completed:
ref_decisions: [DEC-0023]
tags: [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.