prometeu-runtime/discussion/workflow/plans/PLN-0046-profile-separation-specification.md

id	ticket	title	status	created	completed	ref_decisions	tags
PLN-0046	runtime-mode-separation-game-system	Profile Separation Specification	done	2026-05-14		DEC-0023	runtime firmware hub system-apps game-mode scheduler spec

Briefing

This plan publishes the canonical profile-separation contract from DEC-0023 before code changes rely on it. It documents that manifest.json app_mode / AppMode is the discriminator, Game remains on the game pipeline, and System uses a Runtime/Hub pipeline oriented around system app hosting.

Decisions de Origem

• DEC-0023 - System Pipeline Separation.

Alvo

Create or update the canonical English runtime specification so implementers have a stable contract for Game versus System profile routing.

Escopo

• Document AppMode::Game and AppMode::System as distinct runtime profiles.
• State that System must not inherit the game stdlib, game ABI, FrameComposer, Gfx, game input, banks, sprites, or game memory-card surfaces as public profile APIs.
• State that future System syscalls are transport for a dedicated System ABI, not the ABI boundary itself.
• Link filesystem details to the dedicated filesystem discussion instead of defining them here.

Fora de Escopo

• No code changes.
• No public PBS System ABI design.
• No complete WindowManager lifecycle, component tree, invalidation, transition, or multitasking model.
• No changes to the canonical game rendering model.

Plano de Execucao

Step 1 - Locate the canonical runtime specification target

What: Identify the existing English spec location for manifest/runtime profile behavior. How: Search the repository for app_mode, AppMode, profile, manifest, and runtime pipeline documentation. If no canonical spec exists, create the smallest runtime-profile spec file in the repository's canonical spec location. File(s): Canonical spec location for runtime/manifest/profile contracts.

Step 2 - Publish the profile discriminator contract

What: Document that manifest.json app_mode / AppMode is the only discriminator introduced by this decision. How: Add normative language for Game and System profiles, including that no new target manifest field is introduced. File(s): Same spec file from Step 1.

Step 3 - Publish public surface boundaries

What: Document which public surfaces remain game-owned and which profile owns future system UI APIs. How: Add a section that reserves FrameComposer, Gfx, game input, banks, sprites, and game memory cards for the Game profile, while reserving future system UI APIs for a dedicated System stdlib/ABI. File(s): Same spec file from Step 1.

Step 4 - Record deferred contracts explicitly

What: Prevent this spec update from accidentally defining later-stage architecture. How: Add non-goals for WindowManager completion, component tree, lifecycle, rich invalidation, transitions, public PBS ABI, multitasking, and filesystem semantics. File(s): Same spec file from Step 1.

Criterios de Aceite

• The spec states that AppMode is the Game versus System discriminator.
• The spec states that Game and System use distinct pipelines.
• The spec states that System does not inherit game public surfaces.
• The spec leaves public System ABI and filesystem semantics to later work.
• The spec is written in English.

Tests / Validacao

• Run the repository documentation/spec checks if they exist.
• Run rg -n "target.*System|System.*target" <spec target> to confirm no new target discriminator was introduced.
• Review the spec against every invariant in DEC-0023.

Riscos

• The canonical spec location may be absent or stale; this plan allows creating the smallest profile spec rather than scattering normative text.
• Over-specifying future System APIs would freeze design too early; the acceptance criteria require deferral.