119 lines
4.8 KiB
Markdown
119 lines
4.8 KiB
Markdown
---
|
|
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.
|