--- id: DEC-0023 ticket: runtime-mode-separation-game-system title: Decision - System Pipeline Separation status: accepted created: 2026-05-14 accepted: 2026-05-14 agenda: AGD-0031 plans: [PLN-0046, PLN-0047, PLN-0048, PLN-0049, PLN-0050] tags: [runtime, firmware, hub, system-apps, game-mode, scheduler, abi] --- ## Status Accepted. This decision is derived from `AGD-0031` and is locked as the normative basis for follow-up implementation plans. It does not authorize implementation outside those plans. ## Contexto Prometeu currently distinguishes `AppMode::Game` and `AppMode::System` in the manifest/runtime model, but the execution path for focused `System` apps still falls through the same VM tick/pipeline used by games. That makes a system app behave like a game running inside a window. The desired model is different: `System` apps belong to the Prometeu Runtime/Hub domain. They should be hosted by a system UI/window environment, inspired by Android-style app hosting, rather than by the game frame pipeline. The existing `manifest.json app_mode` / `AppMode` field is the profile discriminator: - `Game` identifies the game/cartridge profile. - `System` identifies the system app/runtime Hub profile. No new `target` field is required for this decision. ## Decisao Prometeu MUST treat `Game` and `System` as distinct runtime profiles with distinct pipelines. The existing game pipeline MUST remain conceptually intact for this decision. Work derived from this decision MUST NOT redesign `GameRunningStep`, canonical game composition, `FrameComposer`, `Gfx`, game input, banks, sprites, or memory-card semantics except where a minimal guard is required to prevent `System` from entering the game path. `System` MUST get a dedicated Runtime/Hub pipeline. The first implementation slice MUST separate the current `AppMode::System` path from the game tick/pipeline and route system execution, events, and rendering toward the Runtime/Hub `WindowManager` domain. This decision MUST NOT require building the complete `WindowManager`, a full component tree, final lifecycle semantics, rich invalidation, transitions, or the public PBS `System` ABI. Those are later stages built on top of the separated pipeline. Future PBS calls for creating windows, components, receiving events, or interacting with system UI MAY use syscalls as the transport mechanism. That syscall mechanism MUST NOT be treated as the conceptual contract. The public contract, when introduced, SHALL be a `System` profile ABI distinct from the game ABI. ## Rationale The current behavior collapses `System` into the game runtime model. That creates the wrong boundary: system UI becomes a game inside a window, and game APIs become tempting shortcuts for system apps. Keeping the game pipeline untouched reduces risk. The game pipeline already has established ownership around game frame composition, game input, banks, sprites, and memory-card style persistence. The first useful architectural correction is to stop routing `System` apps through that path. Creating a separate `System` pipeline first gives the Runtime/Hub a stable territory where `WindowManager`, app focus, events, component models, lifecycle, invalidation, transitions, and eventual PBS exposure can evolve without freezing public API too early. Treating future syscalls as transport avoids letting the call mechanism define the architecture. The important contract is the profile-specific ABI: game apps use game surfaces, while system apps use system surfaces. ## Invariantes / Contrato - `manifest.json app_mode` / `AppMode` SHALL remain the discriminator for `Game` versus `System`. - `Game` SHALL continue to use the game pipeline. - `System` SHALL use a Runtime/Hub pipeline dedicated to system UI/app hosting. - The first implementation slice SHALL segment pipeline routing only; it SHALL NOT attempt to complete the WindowManager. - The `System` pipeline SHALL be oriented toward the `WindowManager` domain. - The `Game` profile SHALL retain ownership of `FrameComposer`, `Gfx`, game `Input`, banks, sprites, and memory-card style persistence. - The `System` profile MUST NOT inherit the game stdlib or game ABI. - `System` MUST NOT use `FrameComposer`, `Gfx`, game `Input`, banks, sprites, or game memory cards as public profile surfaces. - `System` APIs exposed later to PBS SHALL be part of a dedicated `System` ABI and stdlib/framework. - Future `System` syscalls SHALL be transport for the `System` ABI, not the ABI's conceptual boundary. - `Logs` MAY share runtime implementation internally, but author-facing APIs SHALL be resolved through the profile-specific stdlib. - Detailed `System` filesystem semantics are out of scope for this decision and SHALL remain owned by the dedicated filesystem agenda. ## Technical Specification The implementation plan derived from this decision should target the current point where `AppMode::System` enters the same tick/pipeline as `Game`. The first slice should: - identify the focused `System` app path currently sharing the game tick; - introduce a distinct Runtime/Hub step or dispatch branch for `System`; - keep the game-running path behaviorally unchanged; - route `System` execution/events/rendering to a Runtime/Hub-owned path oriented around the existing `WindowManager`; - enforce or preserve profile gates so `System` cannot use game-only surfaces; - leave full component modeling, final lifecycle, public PBS ABI, and rich animation/transition semantics for later decisions/plans. The output of the first slice should be an architectural split that future plans can extend. It is acceptable if the `System` path is initially minimal, provided it no longer behaves as a game pipeline in a window. ## Constraints - This decision is not a public PBS API decision. - This decision is not a complete WindowManager design. - This decision is not the `System` filesystem contract. - This decision is not a scheduler/multitasking contract for multiple concurrent apps. - This decision does not change the canonical game rendering model. - This decision must be implemented through a plan before spec or code changes. ## Impactos ### Runtime / Firmware Runtime and firmware must stop treating focused `System` apps as regular game ticks. The Runtime/Hub must gain a separated path that can host system app execution under the system UI domain. ### Host Host behavior should remain unchanged except where it observes the runtime state transition or presentation output of the separated `System` pipeline. ### VM / Language The VM and PBS-like languages may remain shared across profiles. Sharing VM/language does not imply sharing stdlib, ABI, lifecycle, input, rendering, or storage semantics. ### Studio / Tooling Studio and compiler tooling should use the existing `manifest.json app_mode` value to select profile-specific stdlib/capability behavior. No new `target` field is introduced by this decision. ### Specs Any future canonical specification update must describe profile separation and state that `System` uses a Runtime/Hub pipeline distinct from the game pipeline. Public `System` ABI details must wait until the internal pipeline and WindowManager model are mature enough to expose. ### Filesystem The only filesystem statement locked here is negative: `System` must not use game memory cards as its public storage model. The positive `System` filesystem contract remains delegated to the existing filesystem agenda. ## Referencias - `AGD-0031` - Runtime Mode Separation: Game and System. - `manifest.json app_mode` / `AppMode::{Game,System}`. - Existing game-frame ownership lessons around `FrameComposer`, `Gfx`, overlays, and memory-card-style persistence. - Existing filesystem agenda for app/system filesystem semantics. ## Propagacao Necessaria - A plan must be created for the first pipeline-separation implementation slice. - The plan must explicitly protect the game pipeline from unrelated redesign. - The plan must define tests/evidence that `System` no longer enters the game tick path. - Compiler/Studio follow-up work must align stdlib/capability resolution with `app_mode`. - A later decision or plan must define public `System` ABI exposure only after the internal Runtime/Hub pipeline is proven. - The filesystem agenda must remain the owner of detailed `System` filesystem semantics. ## Revision Log - 2026-05-14: Initial draft from `AGD-0031`.