prometeu-runtime/discussion/workflow/decisions/DEC-0035-remove-userland-system-run-cart-and-preserve-direct-boot.md

id	ticket	title	status	created	ref_agenda	tags
DEC-0035	system-run-cart	Remove Userland system.run_cart and Preserve Direct Boot	accepted	2026-07-03	AGD-0003

Status

Accepted.

Contexto

system.run_cart existe na ABI publica, mas nao possui comportamento real de troca de cartucho. Isso cria uma falsa promessa: um guest pode declarar/chamar uma operacao que aparenta iniciar outro cartucho, enquanto o runtime retorna sucesso vazio ou nao executa uma transicao completa.

A discussao fechou tres separacoes:

• boot direto por host/CLI/debug e necessario e deve permanecer;
• apps/userland nao devem iniciar cartuchos diretamente;
• troca Game A -> Home -> Game B exige um orquestrador de SystemOS proprio, separado em DSC-0043 / AGD-0044.

AGD-0041 permanece responsavel por Game -> Home -> mesmo Game, foreground, pausa/suspensao e retorno ao mesmo Game.

Decisao

system.run_cart MUST be removed from the userland guest ABI.

No app, cartridge, Shell app, or other userland guest code MAY directly request cartridge boot through system.run_cart.

The platform MUST NOT preserve compatibility for the current userland system.run_cart surface. It MUST NOT remain as a callable stub, reserved guest syscall that returns success, or capability-gated userland escape hatch.

Direct boot MUST remain supported through host/CLI/debug or equivalent single-game launch paths. This direct boot path is a host/system entrypoint, not a guest syscall.

Internal cartridge loading MAY continue to use the existing loader path, including directory cartridges and test fixtures. .pmc support is not required by this decision.

If apps ever need to request navigation in the future, that MUST be designed as a separate SystemOS-mediated surface with different naming and semantics. It MUST NOT reintroduce userland run_cart as direct cartridge boot.

Rationale

Direct cartridge boot is essential for development, debugging, automated tests, and future distribution modes where the runtime launches as a single game. That use case does not require a guest-visible syscall.

Userland cartridge boot would give app code authority over system navigation, lifecycle, cleanup, target resolution, and failure policy. Those concerns belong to SystemOS/firmware and later to the cartridge switch orchestrator, not to a VM guest syscall.

Keeping a stub or compatibility surface would preserve the current ambiguity. The public ABI should not advertise an operation that either does nothing or looks like direct app-controlled navigation.

Invariantes / Contrato

• Guest/userland MUST NOT expose or call system.run_cart.
• The public syscall registry, declarations, generated bindings, and docs MUST stop presenting system.run_cart as an app-callable operation.
• Booting a cartridge directly MUST remain available from host/CLI/debug flows.
• Direct boot MUST enter the runtime with a selected cartridge target; it MUST NOT depend on a guest syscall issued after VM startup.
• Loader code MAY remain reusable by host/firmware/SystemOS internals.
• Loader code MUST NOT become lifecycle orchestration authority.
• Game -> Home -> same Game remains owned by AGD-0041.
• Game A -> Home -> Game B remains owned by DSC-0043 / AGD-0044.
• .pmc, app catalog, launcher UX, marketplace/distribution, and full cartridge replacement under Home are outside this decision.

Impactos

• Spec / ABI: remove or retire system.run_cart from the userland syscall surface. Any syscall table, PBS declarations, generated metadata, or docs must stop advertising it to apps.
• Runtime / VM: guest dispatch must no longer treat system.run_cart as a valid userland operation. If obsolete bytecode or declarations still reach the runtime during migration, they must fail explicitly rather than report success.
• Firmware / Host: direct boot remains supported for command-line, debugger, test harness, and future single-game launch flows.
• SystemOS: no new cart-switch orchestrator is required by this decision. That work is deferred to DSC-0043 / AGD-0044.
• Tooling: tools must continue to support direct cartridge launch for development and test workflows, without relying on a guest syscall.
• Tests: coverage must prove both sides: userland cannot declare/call system.run_cart, and direct boot of a cartridge still works.

Alternativas Descartadas

• Implement system.run_cart as a normal syscall: rejected because it gives userland direct navigation authority and mixes guest execution with system lifecycle.
• Keep a compatibility stub: rejected because no compatibility is required and a stub preserves the false contract.
• Make system.run_cart privileged but still guest-visible: rejected for v1 because it keeps the ambiguous idea that some guest profile may directly boot cartuchos.
• Implement full Home -> another Game now: rejected for this decision; it requires SystemOS orchestration after the AGD-0041 foreground contract.

Referencias

• Agenda: AGD-0003
• Foreground/pause scope: AGD-0041
• Future cartridge switch orchestrator: DSC-0043 / AGD-0044
• Related lessons: LSN-0041 SystemOS lifecycle authority, LSN-0042 SystemOS service ownership boundary, LSN-0043 SystemOS domain facades.

Propagacao Necessaria

• Remove SystemRunCart from userland ABI declarations and generated syscall metadata.
• Remove or rewrite runtime dispatch paths that return success for system.run_cart.
• Preserve host/CLI/debug direct boot paths and add regression tests for them.
• Add negative tests for guest/userland declaration or call attempts.
• Update any documentation/spec text that describes system.run_cart as app-callable.

Revision Log

• 2026-07-03: Initial draft from AGD-0003.