4.8 KiB
| id | ticket | title | created | tags | ||||||
|---|---|---|---|---|---|---|---|---|---|---|
| LSN-0051 | system-run-cart | Launch Authority Belongs to SystemOS | 2026-07-03 |
|
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.