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