92 lines
3.5 KiB
Markdown
92 lines
3.5 KiB
Markdown
---
|
|
id: LSN-0040
|
|
discussion: DSC-0031
|
|
decision: DEC-0023
|
|
title: System Pipeline Separation
|
|
status: done
|
|
created: 2026-05-14
|
|
tags: [runtime, firmware, hub, system-apps, game-mode, abi]
|
|
---
|
|
|
|
# System Pipeline Separation
|
|
|
|
`AppMode` is the profile discriminator. `Game` and `System` can share the VM
|
|
and syscall transport machinery internally, but they must not share the same
|
|
author-facing runtime profile.
|
|
|
|
The important boundary is not the instruction used to cross into host services.
|
|
The boundary is the profile contract selected by `manifest.json app_mode`:
|
|
|
|
- `Game` uses the game pipeline and owns game-facing surfaces such as GFX,
|
|
frame composition, asset/bank access, sprites, game input, and memcard-style
|
|
persistence.
|
|
- `System` uses a Runtime/Hub pipeline oriented around system UI and app
|
|
hosting.
|
|
- Future system APIs may use syscalls as transport, but the public contract is a
|
|
dedicated `System` ABI and stdlib/framework.
|
|
|
|
## What Changed
|
|
|
|
The cartridge and boot specs now state that `app_mode` is the discriminator and
|
|
that no separate manifest `target` field is involved.
|
|
|
|
Firmware now routes loaded `System` cartridges into `SystemRunning` instead of
|
|
`GameRunning` or an implicit HubHome fallback. That state delegates focused
|
|
system app updates to `PrometeuHub::update_system_profile`, which gives the Hub
|
|
domain a named system-profile pipeline entry point.
|
|
|
|
The game-running path remains isolated. `GameRunningStep` still owns the game
|
|
tick and presentation behavior.
|
|
|
|
Runtime syscall dispatch now rejects representative game-only surfaces when the
|
|
current cartridge profile is `System`. GFX, composer, asset/bank surfaces are
|
|
guarded as game-profile syscalls. Memcard calls keep their existing
|
|
status-first `AccessDenied` contract for non-game profiles. Log transport
|
|
remains internally shared, while future author-facing APIs are still expected to
|
|
resolve through profile-specific stdlibs.
|
|
|
|
## Evidence
|
|
|
|
The implementation evidence for this separation was:
|
|
|
|
- `cargo test -p prometeu-firmware`: 8 passed.
|
|
- `cargo test -p prometeu-system`: 48 passed.
|
|
- `cargo test -p prometeu-host-desktop-winit`: 25 passed, 5 ignored.
|
|
|
|
The firmware tests prove that:
|
|
|
|
- `AppMode::Game` still reaches `GameRunning`;
|
|
- `AppMode::System` reaches `SystemRunning`;
|
|
- a focused system app ticks through the Hub system-profile pipeline.
|
|
|
|
The runtime tests prove that:
|
|
|
|
- `System` profile cartridges cannot call representative game GFX, composer, or
|
|
bank surfaces;
|
|
- non-game memcard access remains status-first instead of crashing;
|
|
- log transport can remain shared internally.
|
|
|
|
## How To Think About It
|
|
|
|
Do not model system apps as games inside windows. Model them as apps hosted by
|
|
the Runtime/Hub environment.
|
|
|
|
The first split is deliberately small: it creates a stable place for system UI
|
|
execution without freezing the final WindowManager, lifecycle, component tree,
|
|
filesystem, or public PBS `System` ABI. Those are follow-up contracts.
|
|
|
|
When extending this area, ask which profile owns the author-facing capability
|
|
before deciding which syscall or internal runtime service carries it. Syscalls
|
|
are a transport mechanism. Profile ABI is the contract.
|
|
|
|
## References
|
|
|
|
- `DEC-0023` - System Pipeline Separation.
|
|
- `PLN-0046` - Profile Separation Specification.
|
|
- `PLN-0047` - Firmware Runtime Profile Dispatch.
|
|
- `PLN-0048` - Minimal System Hub Pipeline.
|
|
- `PLN-0049` - System Profile ABI Gates.
|
|
- `docs/specs/runtime/13-cartridge.md`
|
|
- `docs/specs/runtime/14-boot-profiles.md`
|
|
- `docs/specs/runtime/16-host-abi-and-syscalls.md`
|