System Run Cart
This commit is contained in:
+136
@@ -0,0 +1,136 @@
|
||||
---
|
||||
id: DEC-0035
|
||||
ticket: system-run-cart
|
||||
title: Remove Userland system.run_cart and Preserve Direct Boot
|
||||
status: accepted
|
||||
created: 2026-07-03
|
||||
ref_agenda: AGD-0003
|
||||
tags: []
|
||||
---
|
||||
|
||||
## 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`.
|
||||
Reference in New Issue
Block a user