Runtime Mode Separation: Game and System

This commit is contained in:
2026-05-14 13:22:34 +01:00
parent 4d34e08c6c
commit e3ac3dfd06
7 changed files with 437 additions and 37 deletions
@@ -0,0 +1,81 @@
---
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.
@@ -0,0 +1,79 @@
---
id: PLN-0047
ticket: runtime-mode-separation-game-system
title: Firmware Runtime Profile Dispatch
status: open
created: 2026-05-14
completed:
ref_decisions: [DEC-0023]
tags: [runtime, firmware, hub, system-apps, game-mode, scheduler]
---
## Briefing
This plan implements the first routing split required by `DEC-0023`: focused `System` cartridges must not enter `GameRunningStep` or the game frame pipeline. The existing game path must remain behaviorally unchanged.
## Decisions de Origem
- `DEC-0023` - System Pipeline Separation.
## Alvo
Make firmware dispatch choose an explicit runtime profile path after cartridge load: `Game` routes to `GameRunningStep`, while `System` routes to a Runtime/Hub-owned system step.
## Escopo
- Introduce explicit profile dispatch around cartridge load and firmware state transitions.
- Add a dedicated system-running firmware step or equivalent dispatch branch.
- Keep `GameRunningStep` semantics unchanged for `AppMode::Game`.
- Preserve current minimal WindowManager window creation/focus behavior for `AppMode::System`.
## Fora de Escopo
- No redesign of `GameRunningStep`, `FrameComposer`, canonical game composition, game input, banks, sprites, or memory-card semantics.
- No complete WindowManager or public PBS `System` ABI.
- No multitasking/scheduler contract beyond one focused system app path.
## Plano de Execucao
### Step 1 - Add a profile-named system firmware step
**What:** Create a dedicated step for focused `System` cartridge execution.
**How:** Add a `SystemRunningStep` or similarly explicit type under the firmware module and register it in `firmware_state`.
**File(s):** `crates/console/prometeu-firmware/src/firmware/firmware_step_system_running.rs`, `crates/console/prometeu-firmware/src/firmware/mod.rs`, `crates/console/prometeu-firmware/src/firmware/firmware_state.rs`.
### Step 2 - Route cartridge load by `AppMode`
**What:** Replace implicit HubHome fallback with explicit profile dispatch.
**How:** In `LoadCartridgeStep::on_update`, route `AppMode::Game` to `FirmwareState::GameRunning(GameRunningStep)` and `AppMode::System` to the new system-running state after creating/focusing the hub window.
**File(s):** `crates/console/prometeu-firmware/src/firmware/firmware_step_load_cartridge.rs`.
### Step 3 - Preserve game behavior
**What:** Ensure the game path still calls `ctx.os.tick(ctx.vm, ctx.signals, ctx.hw)` and presents exactly as before.
**How:** Do not change `GameRunningStep` except for imports required by compile fallout.
**File(s):** `crates/console/prometeu-firmware/src/firmware/firmware_step_game_running.rs`.
### Step 4 - Add route tests
**What:** Prove `System` does not transition to `GameRunning`.
**How:** Add or update firmware tests that load a `System` cartridge and assert the resulting firmware state is the dedicated system state, while a `Game` cartridge still reaches `GameRunning`.
**File(s):** `crates/console/prometeu-firmware/src/firmware/firmware.rs` or nearby firmware tests.
## Criterios de Aceite
- [ ] Loading an `AppMode::Game` cartridge transitions to `GameRunning`.
- [ ] Loading an `AppMode::System` cartridge transitions to a dedicated system profile state.
- [ ] No `AppMode::System` path enters `GameRunningStep`.
- [ ] Existing game-running behavior remains unchanged except for profile guards.
## Tests / Validacao
- `cargo test -p prometeu-firmware`
- `cargo test -p prometeu-system`
- Add assertions that the system route creates/focuses a hub window without selecting `GameRunning`.
## Riscos
- Existing `HubHomeStep` currently mixes hub GUI work and focused system VM ticking; splitting state names may reveal hidden assumptions in host/debugger state reporting.
- The implementation must not use this step to redesign game presentation or hub UI.
@@ -0,0 +1,79 @@
---
id: PLN-0048
ticket: runtime-mode-separation-game-system
title: Minimal System Hub Pipeline
status: open
created: 2026-05-14
completed:
ref_decisions: [DEC-0023]
tags: [runtime, firmware, hub, system-apps, window-manager]
---
## Briefing
This plan moves focused `System` execution out of the game-oriented frame path and into a minimal Runtime/Hub pipeline. The pipeline may initially be thin, but it must be named, testable, and owned by the Hub/WindowManager domain.
## Decisions de Origem
- `DEC-0023` - System Pipeline Separation.
## Alvo
Create a minimal `System` profile execution path that handles system execution, events, and presentation through Runtime/Hub concepts instead of the game pipeline.
## Escopo
- Add a small system pipeline entry point owned by `prometeu_system` or the firmware Hub domain.
- Move focused system VM ticking from generic `HubHomeStep` inline logic into that entry point.
- Keep rendering oriented around `PrometeuHub` and `WindowManager`.
- Preserve the current minimal behavior where a focused system window may tick the VM and render hub windows.
## Fora de Escopo
- No final component tree, invalidation model, transition model, lifecycle contract, or multitasking scheduler.
- No public PBS ABI.
- No game pipeline changes.
## Plano de Execucao
### Step 1 - Define the minimal system pipeline API
**What:** Introduce a function/type that represents one system-profile update.
**How:** Create a small API that accepts the runtime, VM, input signals, hardware, and hub/window state needed today, and returns an optional `CrashReport`.
**File(s):** `crates/console/prometeu-system/src/programs/prometeu_hub/prometeu_hub.rs`, possible new module under `crates/console/prometeu-system/src/programs/prometeu_hub/`.
### Step 2 - Move focused system ticking behind the pipeline API
**What:** Remove direct focused-system `ctx.os.tick(...)` calls from hub-home or system-running firmware code.
**How:** Replace inline ticking with the new Runtime/Hub pipeline call. Keep behavior equivalent: hub GUI updates, focused window handling, system app tick, hub render, present.
**File(s):** `crates/console/prometeu-firmware/src/firmware/firmware_step_hub_home.rs`, new system-running step from `PLN-0047`.
### Step 3 - Keep game surfaces private to the game profile
**What:** Ensure the system pipeline does not expose game composition APIs as its public contract.
**How:** The system pipeline may temporarily use existing internal hardware presentation to preserve behavior, but its public entry point must be named around hub/system concepts and must not accept or return `FrameComposer`, game banks, sprites, or game input abstractions.
**File(s):** `crates/console/prometeu-system/src/programs/prometeu_hub/`, `crates/console/prometeu-firmware/src/firmware/`.
### Step 4 - Add focused-system pipeline tests
**What:** Prove the system pipeline is invoked for focused system windows.
**How:** Add tests using existing test support or fakes to assert that a focused system app uses the system pipeline call and returns crashes through the system state, not through `GameRunningStep`.
**File(s):** `crates/console/prometeu-firmware/src/firmware/firmware.rs`, `crates/console/prometeu-system/src/programs/prometeu_hub/`.
## Criterios de Aceite
- [ ] Focused `System` execution is behind a Runtime/Hub-named pipeline entry point.
- [ ] Firmware no longer embeds the focused system VM tick as anonymous hub-home logic.
- [ ] Game-running code is not modified except for compile integration.
- [ ] The system pipeline remains minimal and does not define deferred WindowManager contracts.
## Tests / Validacao
- `cargo test -p prometeu-firmware`
- `cargo test -p prometeu-system`
- Manual smoke run of a `System` cartridge should show the hub/window path still presents.
## Riscos
- The current system window rendering is simple and hardware-backed; the plan allows internal reuse while preventing it from becoming the public system ABI.
- Test support may need small fakes to observe routing without introducing broad runtime refactors.
@@ -0,0 +1,79 @@
---
id: PLN-0049
ticket: runtime-mode-separation-game-system
title: System Profile ABI Gates
status: open
created: 2026-05-14
completed:
ref_decisions: [DEC-0023]
tags: [runtime, firmware, hub, system-apps, abi, stdlib]
---
## Briefing
This plan enforces the negative side of `DEC-0023`: `System` must not inherit the game ABI or game stdlib surfaces. It does not design the final public `System` ABI.
## Decisions de Origem
- `DEC-0023` - System Pipeline Separation.
## Alvo
Make profile gates explicit enough that `System` apps cannot call game-only public surfaces by accident while the dedicated system ABI remains deferred.
## Escopo
- Audit current runtime syscall/profile gates for game-only domains.
- Preserve or add guards that reject `System` access to game-only surfaces.
- Ensure logs may share runtime implementation internally but remain resolved through profile-specific author-facing APIs later.
- Add tests for representative game-only surfaces under `AppMode::System`.
## Fora de Escopo
- No final `System` stdlib/framework.
- No public PBS `System` ABI.
- No filesystem contract beyond preserving the negative rule that `System` does not use game memory cards as its public storage model.
## Plano de Execucao
### Step 1 - Audit existing domain gates
**What:** Map syscall domains and runtime dispatch branches that are game-only or shared.
**How:** Inspect `dispatch.rs`, `syscalls/domains/*`, caps, and tests for checks against `current_cartridge_app_mode`.
**File(s):** `crates/console/prometeu-system/src/virtual_machine_runtime/dispatch.rs`, `crates/console/prometeu-hal/src/syscalls/domains/`, `crates/console/prometeu-hal/src/syscalls/caps.rs`.
### Step 2 - Define a local profile-gate helper if duplication appears
**What:** Centralize repeated `AppMode::Game` checks only if it reduces real duplication.
**How:** Add a small helper in runtime dispatch or profile policy code that returns the existing fault/error style for game-only domains.
**File(s):** `crates/console/prometeu-system/src/virtual_machine_runtime/dispatch.rs` or a nearby runtime module.
### Step 3 - Preserve shared internal services without exposing shared author APIs
**What:** Keep internal log implementation sharing valid while avoiding a shared stdlib conclusion.
**How:** Do not rename or split internal log services in this plan. Add comments/tests only where needed to clarify that profile-specific stdlib resolution is future tooling/API work.
**File(s):** `crates/console/prometeu-hal/src/log/`, `crates/console/prometeu-system/src/virtual_machine_runtime/dispatch.rs`.
### Step 4 - Add system-denial tests for game surfaces
**What:** Prove `System` cannot use representative game-only surfaces.
**How:** Add tests that set `current_cartridge_app_mode = AppMode::System` and verify game-only calls fail for representative GFX/composer/bank/input/memcard-style surfaces according to the existing error contract.
**File(s):** `crates/console/prometeu-system/src/virtual_machine_runtime/tests.rs`, `crates/console/prometeu-system/src/virtual_machine_runtime/tests_fs_memcard.rs`, related dispatch tests.
## Criterios de Aceite
- [ ] Game-only public surfaces reject `AppMode::System`.
- [ ] Representative tests cover system denial for game rendering/composition/bank or persistence surfaces.
- [ ] Shared internal log implementation is not mistaken for shared public stdlib.
- [ ] No final `System` ABI is introduced.
## Tests / Validacao
- `cargo test -p prometeu-system`
- `cargo test -p prometeu-hal`
- `rg -n "current_cartridge_app_mode != AppMode::Game|AppMode::System" crates/console/prometeu-system/src/virtual_machine_runtime` to review gate coverage.
## Riscos
- Over-centralizing gates may cause churn in dispatch code; use a helper only when it makes tests and policy clearer.
- Some game-only surfaces may currently fail through capabilities rather than explicit profile checks; tests should assert the behavioral contract, not force one implementation style.
@@ -0,0 +1,82 @@
---
id: PLN-0050
ticket: runtime-mode-separation-game-system
title: System Pipeline Evidence and Learning
status: open
created: 2026-05-14
completed:
ref_decisions: [DEC-0023]
tags: [runtime, firmware, hub, system-apps, validation, lessons]
---
## Briefing
This plan closes the implementation family by collecting evidence that `DEC-0023` was executed and preparing the required learning artifact after spec/code publication.
## Decisions de Origem
- `DEC-0023` - System Pipeline Separation.
## Alvo
Produce test evidence and a didactic lesson showing how to reason about profile-specific pipelines after the implementation plans are complete.
## Escopo
- Run the relevant firmware/system/host checks after `PLN-0046` through `PLN-0049`.
- Verify that no `System` path enters `GameRunningStep`.
- Verify that the game pipeline remains unchanged in behavior.
- Create an English lesson under `discussion/lessons/DSC-0031-runtime-mode-separation-game-system/`.
- Move the discussion lifecycle forward only after implementation evidence exists.
## Fora de Escopo
- No new architecture decisions.
- No code or spec changes except small documentation links required by housekeeping.
- No lesson before the execution result is published.
## Plano de Execucao
### Step 1 - Collect automated evidence
**What:** Run package-level checks covering firmware dispatch, system runtime gates, and host integration fallout.
**How:** Execute the test commands from the preceding plans and record the passing command set in the PR or execution notes.
**File(s):** Test output only.
### Step 2 - Collect routing evidence
**What:** Demonstrate that `AppMode::System` does not enter `GameRunningStep`.
**How:** Use tests, targeted logs, or debugger-visible state assertions to show `System` reaches the Runtime/Hub system path while `Game` reaches `GameRunning`.
**File(s):** Tests from `PLN-0047` and `PLN-0048`.
### Step 3 - Write the lesson
**What:** Explain the resulting mental model.
**How:** Create a lesson that distinguishes profile discriminator, pipeline routing, public ABI, syscall transport, and deferred WindowManager/filesystem contracts.
**File(s):** `discussion/lessons/DSC-0031-runtime-mode-separation-game-system/LSN-0040-system-pipeline-separation.md`.
### Step 4 - Housekeep the discussion state
**What:** Close the workflow once implementation and lesson are complete.
**How:** Use the discussion housekeeping flow to mark completed plans and discussion state after the lesson exists.
**File(s):** `discussion/index.ndjson`, lesson artifact.
## Criterios de Aceite
- [ ] Firmware and system runtime tests pass after the implementation family.
- [ ] Evidence shows `System` does not enter `GameRunningStep`.
- [ ] Evidence shows `Game` still enters and behaves through `GameRunningStep`.
- [ ] The lesson is in English and links back to `DEC-0023`.
- [ ] Housekeeping is run only after code/spec execution is complete.
## Tests / Validacao
- `cargo test -p prometeu-firmware`
- `cargo test -p prometeu-system`
- `cargo test -p prometeu-host-desktop-winit` if host-observable state changed.
- `discussion validate` after housekeeping, or document existing unrelated index validation debt if it still blocks.
## Riscos
- Existing discussion index path debt may block deterministic CLI housekeeping; if so, record it separately and avoid broad historical rewrites inside this implementation family.
- A lesson written before execution would become intent rather than learning; this plan explicitly sequences it after evidence.