---
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`