Runtime Mode Separation: Game and System
This commit is contained in:
@@ -2,19 +2,19 @@
|
||||
id: DEC-0023
|
||||
ticket: runtime-mode-separation-game-system
|
||||
title: Decision - System Pipeline Separation
|
||||
status: open
|
||||
status: accepted
|
||||
created: 2026-05-14
|
||||
accepted:
|
||||
accepted: 2026-05-14
|
||||
agenda: AGD-0031
|
||||
plans: []
|
||||
plans: [PLN-0046, PLN-0047, PLN-0048, PLN-0049, PLN-0050]
|
||||
tags: [runtime, firmware, hub, system-apps, game-mode, scheduler, abi]
|
||||
---
|
||||
|
||||
## Status
|
||||
|
||||
Open for review.
|
||||
Accepted.
|
||||
|
||||
This decision is derived from `AGD-0031` and is ready to be locked once the wording below is accepted. It does not authorize implementation until a follow-up plan exists.
|
||||
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
|
||||
|
||||
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user