---
id: PLN-0129
ticket: system-run-cart
title: Remove Userland Run Cart ABI Surface
status: done
created: 2026-07-03
ref_decisions: [DEC-0035]
tags: []
---

## Briefing

`DEC-0035` removes `system.run_cart` from the userland guest ABI. This plan
covers the public ABI, syscall registry/declaration surface, generated metadata,
and documentation/spec propagation. It does not change runtime dispatch behavior
or direct boot tests; those are covered by `PLN-0130` and `PLN-0131`.

## Objective

Remove `system.run_cart` from every app-callable/userland ABI surface while
preserving non-guest direct boot entrypoints.

## Dependencies

- Source decision: `DEC-0035`.
- Must stay scoped away from `AGD-0041` and `AGD-0044`.
- Coordinate with `PLN-0130` so runtime dispatch does not retain a callable
  success path after the declaration is removed.

## Scope

- Remove or retire `Syscall::SystemRunCart` from userland-visible syscall
  declarations in `crates/console/prometeu-hal/src/syscalls.rs`.
- Remove the `system.run_cart` registry entry from
  `crates/console/prometeu-hal/src/syscalls/domains/system.rs` and
  `crates/console/prometeu-hal/src/syscalls/registry.rs`, unless implementation
  discovers an internal-only registry distinct from guest ABI.
- Remove generated/static bytecode or VM-facing declarations that expose
  `system.run_cart`, including known references in
  `crates/console/prometeu-bytecode/src/model.rs` and
  `crates/console/prometeu-vm/src/virtual_machine.rs` if they include it.
- Update docs/specs that mention `system.run_cart` as app-callable.
- Update `AGD-0004` references only if they become factually misleading after
  removal; do not close or reinterpret that agenda.

## Non-Goals

- Do not implement `Home -> another Game`.
- Do not add a replacement app navigation syscall.
- Do not implement `.pmc`.
- Do not change direct host/CLI/debug boot behavior.
- Do not add compatibility stubs for obsolete guest code.

## Execution Method

1. Search for `SystemRunCart`, `run_cart`, and `"system", "run_cart"` across
   `crates/`, `docs/`, and `discussion/`.
2. Remove `system.run_cart` from userland syscall domain declarations and
   lookup/name registries.
3. Remove generated/static guest-facing metadata entries that advertise
   `system.run_cart`.
4. Update docs/specs to state that cartridges are booted by host/system paths,
   not by guest syscall.
5. Compile the workspace or targeted crates to find stale references.

## Acceptance Criteria

- No userland ABI declaration advertises `system.run_cart`.
- No generated guest metadata exposes `run_cart` as callable.
- Documentation/spec text no longer describes app-callable cartridge boot.
- Any retained code path is clearly internal-only and is not reachable through
  guest syscall lookup.

## Tests

- Add or update syscall registry tests to assert `system.run_cart` is absent
  from the public/userland registry.
- Run targeted tests for `prometeu-hal`, `prometeu-bytecode`, and
  `prometeu-vm` if available.
- Run repository validation commands used for syscall declaration consistency.

## Affected Artifacts

- `crates/console/prometeu-hal/src/syscalls.rs`
- `crates/console/prometeu-hal/src/syscalls/domains/system.rs`
- `crates/console/prometeu-hal/src/syscalls/registry.rs`
- `crates/console/prometeu-bytecode/src/model.rs`
- `crates/console/prometeu-vm/src/virtual_machine.rs`
- `docs/specs/runtime/`
- `discussion/workflow/agendas/AGD-0004-system-fault-semantics-and-control-surface.md`