---
id: PLN-0046
ticket: runtime-mode-separation-game-system
title: Profile Separation Specification
status: open
created: 2026-05-14
completed:
ref_decisions: [DEC-0023]
tags: [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.