Foreground Stack, Game Pause, and VM-Backed Shell Coexistence
This commit is contained in:
+118
@@ -0,0 +1,118 @@
|
||||
---
|
||||
id: LSN-0051
|
||||
ticket: system-run-cart
|
||||
title: Launch Authority Belongs to SystemOS
|
||||
created: 2026-07-03
|
||||
tags: [runtime, systemos, cartridge, launch, abi, home]
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
The `system.run_cart` workflow resolved two related questions: whether a guest
|
||||
should have an app-callable cartridge launch syscall, and how Home should start
|
||||
games from a local library.
|
||||
|
||||
The final model removes `system.run_cart` from the userland ABI while preserving
|
||||
direct host-controlled cartridge boot. Home launch is restored as a
|
||||
system-owned path: the host may provide `--games-root <dir>`, SystemOS/Home
|
||||
discovers valid Game directory cartridges, and selecting an entry routes through
|
||||
firmware into `LoadCartridge`.
|
||||
|
||||
The important distinction is authority. A launch can be a valid product action
|
||||
without being a guest capability.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
### Remove Guest Cartridge Launch
|
||||
|
||||
**What:** Prometeu removed `system.run_cart` from the public userland syscall
|
||||
surface, generated guest metadata, and runtime dispatch.
|
||||
|
||||
**Why:** A guest syscall made cartridge launch look like app-owned navigation.
|
||||
That gave userland implied authority over target resolution, lifecycle cleanup,
|
||||
failure policy, and system navigation.
|
||||
|
||||
**Trade-offs:** Obsolete guest code cannot keep a compatibility stub. The
|
||||
runtime instead keeps direct boot as a host/system entrypoint and lets stale
|
||||
guest attempts fail through the invalid syscall path.
|
||||
|
||||
### Preserve Direct Boot Outside The Guest ABI
|
||||
|
||||
**What:** Host, CLI, debugger, tests, and single-game flows continue to boot a
|
||||
selected cartridge directly.
|
||||
|
||||
**Why:** Direct boot is still essential for development, automation, and future
|
||||
single-game distribution. Those flows start with a host-selected target before
|
||||
VM execution, so they do not need a guest syscall.
|
||||
|
||||
**Trade-offs:** The loader remains reusable, but it is not lifecycle
|
||||
orchestration authority. Higher-level transitions must be owned by firmware or
|
||||
SystemOS.
|
||||
|
||||
### Model Home Launch As A System Action
|
||||
|
||||
**What:** `--games-root <dir>` configures a local games library for Home. V1
|
||||
discovery scans immediate child directories, keeps only valid Game cartridges,
|
||||
and exposes enough internal metadata to launch a selected entry.
|
||||
|
||||
**Why:** Home needs a product path for "choose a game and start it", but that
|
||||
action belongs to the system profile. SystemOS can present the library and ask
|
||||
firmware to enter `LoadCartridge` without reintroducing guest-controlled launch.
|
||||
|
||||
**Trade-offs:** V1 intentionally excludes recursive discovery, `.pmc`, non-game
|
||||
apps, rich catalog metadata, return-to-Home, and game-to-game switching. Those
|
||||
need separate lifecycle and orchestration decisions.
|
||||
|
||||
## Patterns and Algorithms
|
||||
|
||||
### Authority-Based API Classification
|
||||
|
||||
Before exposing an operation to guest/userland code, classify what authority it
|
||||
implies. If the operation selects another executable target, changes process
|
||||
lifecycle, or controls navigation between system-owned modes, it is probably a
|
||||
SystemOS or firmware action rather than an app syscall.
|
||||
|
||||
### Separate Selection From Loading
|
||||
|
||||
Home owns user selection and presentation. SystemOS owns the launch request.
|
||||
Firmware owns the transition into `LoadCartridge`. The cartridge loader remains
|
||||
the mechanism that validates and materializes a cartridge, not the authority
|
||||
that decides when navigation is allowed.
|
||||
|
||||
### Expandable Internal Catalog Records
|
||||
|
||||
Home can render a small v1 list while the internal entry retains manifest data,
|
||||
title, app id, app version, cartridge path, and discovery metadata. This keeps
|
||||
the UI simple without reducing the model to a display-only DTO.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
### Compatibility Stubs Preserve False Contracts
|
||||
|
||||
A syscall that returns success without doing real lifecycle work is worse than
|
||||
an absent syscall. It teaches callers that the platform supports app-driven
|
||||
launch while hiding that no complete transition happened.
|
||||
|
||||
### A Product Flow Is Not Automatically A Guest API
|
||||
|
||||
"Home can launch a game" and "a guest can launch a cartridge" are different
|
||||
claims. Product behavior should be mapped to the component with the correct
|
||||
authority instead of mirrored into the nearest callable ABI.
|
||||
|
||||
### Generic Library Roots Prematurely Expand Scope
|
||||
|
||||
The first launcher path is a games library, not a marketplace or full app
|
||||
catalog. Shell apps, System apps, packages, icons, search, and recursive layouts
|
||||
carry separate contracts and should not be smuggled into the v1 games-root path.
|
||||
|
||||
## Takeaways
|
||||
|
||||
- Cartridge launch is system navigation, not a userland syscall.
|
||||
- Direct boot can remain host-controlled without appearing in guest metadata.
|
||||
- Home launch should emit a system action and let firmware enter
|
||||
`LoadCartridge`.
|
||||
- Loader reuse does not imply loader ownership of lifecycle policy.
|
||||
- Keep v1 discovery narrow: immediate child directory cartridges with
|
||||
`app_mode: Game`.
|
||||
- Preserve internal catalog metadata even when the Home UI renders only a small
|
||||
subset.
|
||||
Reference in New Issue
Block a user