prometeu-runtime/discussion/workflow/decisions/DEC-0023-system-pipeline-separation.md

id	ticket	title	status	created	accepted	agenda	plans	tags
DEC-0023	runtime-mode-separation-game-system	Decision - System Pipeline Separation	accepted	2026-05-14	2026-05-14	AGD-0031	PLN-0046 PLN-0047 PLN-0048 PLN-0049 PLN-0050	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.