82 lines
3.9 KiB
Markdown
82 lines
3.9 KiB
Markdown
---
|
|
id: PLN-0046
|
|
ticket: runtime-mode-separation-game-system
|
|
title: Profile Separation Specification
|
|
status: done
|
|
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.
|