Intrepid/prometeu-runtime
Intrepid/prometeu-runtime
4
0
Fork 0
Code Pull Requests Activity

Foreground Stack, Game Pause, and VM-Backed Shell Coexistence

Browse Source
This commit is contained in:
bQUARKz 2026-07-03 22:52:08 +01:00
parent 4bc9ce2b73
commit 126bffa37d
Signed by: bquarkz
SSH Key Fingerprint: SHA256:Z7dgqoglWwoK6j6u4QC87OveEq74WOhFN+gitsxtkf8
21 changed files with 1023 additions and 1347 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
discussion/index.ndjson
View File

@ -1,8 +1,8 @@
{"type":"meta","next_id":{"DSC":44,"AGD":46,"DEC":37,"PLN":136,"LSN":51,"CLSN":1}}
{"type":"meta","next_id":{"DSC":44,"AGD":46,"DEC":38,"PLN":142,"LSN":52,"CLSN":1}}
{"type":"discussion","id":"DSC-0043","status":"open","ticket":"system-os-cartridge-switch-orchestrator","title":"SystemOS Cartridge Switch Orchestrator","created_at":"2026-07-03","updated_at":"2026-07-03","tags":["runtime","os","lifecycle","game","cartridge","architecture"],"agendas":[{"id":"AGD-0044","file":"AGD-0044-systemos-cartridge-switch-orchestrator.md","status":"open","created_at":"2026-07-03","updated_at":"2026-07-03"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0039","status":"abandoned","ticket":"render-pipeline-family-and-future-3d","title":"Render Pipeline Family and Future 3D","created_at":"2026-06-04","updated_at":"2026-06-04","tags":["gfx","renderer","runtime","architecture","pipeline"],"agendas":[{"id":"AGD-0039","file":"AGD-0039-render-pipeline-family-and-future-3d.md","status":"abandoned","created_at":"2026-06-04","updated_at":"2026-06-04","_override_reason":"User explicitly chose to close this agenda without a new decision because DSC-0038 already established enough architecture for future extension, and 3D is intentionally deferred."}],"decisions":[],"plans":[],"lessons":[],"_override_reason":"User explicitly chose to close this agenda without a new decision because DSC-0038 already established enough architecture for future extension, and 3D is intentionally deferred."}
{"type":"discussion","id":"DSC-0040","status":"done","ticket":"vm-render-parallel-execution-boundary","title":"VM and Render Parallel Execution Boundary","created_at":"2026-06-04","updated_at":"2026-06-06","tags":["runtime","renderer","vm","concurrency","architecture","perf"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0048","file":"discussion/lessons/DSC-0040-vm-render-parallel-execution-boundary/LSN-0048-render-workers-need-a-closed-packet-contract.md","status":"done","created_at":"2026-06-06","updated_at":"2026-06-06"}]}
{"type":"discussion","id":"DSC-0041","status":"open","ticket":"foreground-stack-game-pause-shell-vm-backed","title":"Foreground Stack, Game Pause, and VM-Backed Shell Coexistence","created_at":"2026-06-05","updated_at":"2026-06-05","tags":["runtime","os","lifecycle","shell","game","vm","foreground","architecture"],"agendas":[{"id":"AGD-0041","file":"AGD-0041-foreground-stack-game-pause-shell-vm-backed.md","status":"open","created_at":"2026-06-05","updated_at":"2026-06-05"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0041","status":"in_progress","ticket":"foreground-stack-game-pause-shell-vm-backed","title":"Foreground Stack, Game Pause, and VM-Backed Shell Coexistence","created_at":"2026-06-05","updated_at":"2026-07-03","tags":["runtime","os","lifecycle","shell","game","vm","foreground","architecture"],"agendas":[{"id":"AGD-0041","file":"AGD-0041-foreground-stack-game-pause-shell-vm-backed.md","status":"accepted","created_at":"2026-06-05","updated_at":"2026-07-03"}],"decisions":[{"id":"DEC-0037","file":"DEC-0037-foreground-stack-and-game-pause-contract.md","status":"accepted","created_at":"2026-07-03","updated_at":"2026-07-03","ref_agenda":"AGD-0041"}],"plans":[{"id":"PLN-0136","file":"PLN-0136-route-desktop-home-key-outside-guest-input.md","status":"open","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0037"]},{"id":"PLN-0137","file":"PLN-0137-implement-systemos-foreground-stack-state.md","status":"open","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0037"]},{"id":"PLN-0138","file":"PLN-0138-specify-foreground-pause-and-home-contract.md","status":"open","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0037"]},{"id":"PLN-0139","file":"PLN-0139-validate-game-home-shell-game-end-to-end.md","status":"open","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0037"]},{"id":"PLN-0140","file":"PLN-0140-deliver-game-pause-resume-and-suspension.md","status":"open","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0037"]},{"id":"PLN-0141","file":"PLN-0141-integrate-render-audio-and-input-pause-boundaries.md","status":"open","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0037"]}],"lessons":[]}
{"type":"discussion","id":"DSC-0042","status":"done","ticket":"real-render-worker-establishment","title":"Real Render Worker Establishment","created_at":"2026-06-06","updated_at":"2026-06-20","tags":["runtime","renderer","worker","concurrency","host","hal","architecture"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0049","file":"discussion/lessons/DSC-0042-real-render-worker-establishment/LSN-0049-render-worker-publication-boundary.md","status":"done","created_at":"2026-06-20","updated_at":"2026-06-20"}]}
{"type":"discussion","id":"DSC-0038","status":"done","ticket":"render-frame-packet-boundary","title":"Logical Render Pipelines and Command Packets","created_at":"2026-05-25","updated_at":"2026-06-04","tags":["gfx","renderer","runtime","frame-composer","architecture","ui","pipeline"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0047","file":"discussion/lessons/DSC-0038-render-frame-packet-boundary/LSN-0047-typed-render-submissions-preserve-domain-boundaries.md","status":"done","created_at":"2026-06-04","updated_at":"2026-06-04"}]}
{"type":"discussion","id":"DSC-0035","status":"done","ticket":"task-owned-shell-windows","title":"Agenda - Task-Owned Shell Windows","created_at":"2026-05-15","updated_at":"2026-05-15","tags":["runtime","os","task","window-manager","shell","lifecycle"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0044","file":"discussion/lessons/DSC-0035-task-owned-shell-windows/LSN-0044-task-window-liveness-belongs-to-the-task.md","status":"done","created_at":"2026-05-15","updated_at":"2026-05-15"}]}
@ -14,7 +14,7 @@
{"type":"discussion","id":"DSC-0001","status":"done","ticket":"legacy-runtime-learn-import","title":"Import legacy runtime learn into discussion lessons","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["migration","tech-debt"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0001","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0001-prometeu-learn-index.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0002","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0002-historical-asset-status-first-fault-and-return-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0003","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0003-historical-audio-status-first-fault-and-return-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0004","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0004-historical-cartridge-boot-protocol-and-manifest-authority.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0005","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0005-historical-game-memcard-slots-surface-and-semantics.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0006","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0006-historical-gfx-status-first-fault-and-return-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0007","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0007-historical-retired-fault-and-input-decisions.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0008","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0008-historical-vm-core-and-assets.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0009","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0009-mental-model-asset-management.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0010","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0010-mental-model-audio.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0011","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0011-mental-model-gfx.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0012","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0012-mental-model-input.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0013","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0013-mental-model-observability-and-debugging.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0014","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0014-mental-model-portability-and-cross-platform.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0015","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0015-mental-model-save-memory-and-memcard.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0016","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0016-mental-model-status-first-and-fault-thinking.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0017","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0017-mental-model-time-and-cycles.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0018","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0018-mental-model-touch.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
{"type":"discussion","id":"DSC-0002","status":"done","ticket":"runtime-edge-test-plan","title":"Agenda - Runtime Edge Test Plan","created_at":"2026-03-27","updated_at":"2026-04-21","tags":[],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0037","file":"discussion/lessons/DSC-0002-runtime-edge-test-plan/LSN-0037-domain-gates-must-be-owned-by-the-repository.md","status":"done","created_at":"2026-04-21","updated_at":"2026-04-21"}]}
{"type":"discussion","id":"DSC-0003","status":"open","ticket":"packed-cartridge-loader-pmc","title":"Agenda - Packed Cartridge Loader PMC","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0002","file":"AGD-0002-packed-cartridge-loader-pmc.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0004","status":"in_progress","ticket":"system-run-cart","title":"Agenda - System Run Cart","created_at":"2026-03-27","updated_at":"2026-07-03","tags":[],"agendas":[{"id":"AGD-0003","file":"AGD-0003-system-run-cart.md","status":"accepted","created_at":"2026-03-27","updated_at":"2026-07-03"},{"id":"AGD-0045","file":"AGD-0045-systemos-library-root-home-game-launch.md","status":"accepted","created_at":"2026-07-03","updated_at":"2026-07-03"}],"decisions":[{"id":"DEC-0035","file":"DEC-0035-remove-userland-system-run-cart-and-preserve-direct-boot.md","status":"accepted","created_at":"2026-07-03","updated_at":"2026-07-03","ref_agenda":"AGD-0003"},{"id":"DEC-0036","file":"DEC-0036-systemos-games-root-and-home-game-launch.md","status":"accepted","created_at":"2026-07-03","updated_at":"2026-07-03","ref_agenda":"AGD-0045"}],"plans":[{"id":"PLN-0129","file":"PLN-0129-remove-userland-run-cart-abi-surface.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0035"]},{"id":"PLN-0130","file":"PLN-0130-remove-runtime-run-cart-stub-dispatch.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0035"]},{"id":"PLN-0131","file":"PLN-0131-preserve-direct-cartridge-boot-coverage.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0035"]},{"id":"PLN-0132","file":"PLN-0132-specify-games-root-home-launch-contract.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0036"]},{"id":"PLN-0133","file":"PLN-0133-implement-games-root-library-discovery.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0036"]},{"id":"PLN-0134","file":"PLN-0134-wire-home-game-list-launch-flow.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0036"]},{"id":"PLN-0135","file":"PLN-0135-validate-games-root-launch-end-to-end.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0036"]}],"lessons":[]}
{"type":"discussion","id":"DSC-0004","status":"done","ticket":"system-run-cart","title":"Agenda - System Run Cart","created_at":"2026-03-27","updated_at":"2026-07-03","tags":[],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0051","file":"discussion/lessons/DSC-0004-system-run-cart/LSN-0051-launch-authority-belongs-to-systemos.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03"}]}
{"type":"discussion","id":"DSC-0005","status":"open","ticket":"system-fault-semantics-and-control-surface","title":"Agenda - System Fault Semantics and Control Surface","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0004","file":"AGD-0004-system-fault-semantics-and-control-surface.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0006","status":"open","ticket":"vm-owned-random-service","title":"Agenda - VM-Owned Random Service","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0005","file":"AGD-0005-vm-owned-random-service.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0007","status":"open","ticket":"app-home-filesystem-surface-and-semantics","title":"Agenda - App Home Filesystem Surface and Semantics","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0006","file":"AGD-0006-app-home-filesystem-surface-and-semantics.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}

118
discussion/lessons/DSC-0004-system-run-cart/LSN-0051-launch-authority-belongs-to-systemos.md Normal file
View File

@ -0,0 +1,118 @@
---
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.

202
discussion/workflow/agendas/AGD-0003-system-run-cart.md
View File

@ -1,202 +0,0 @@
---
id: AGD-0003
ticket: system-run-cart
title: Agenda - System Run Cart
status: accepted
created: 2026-03-27
resolved:
decision:
tags: []
---
# Agenda - System Run Cart
## Problema
`system.run_cart` existe na ABI pública, mas hoje não produz efeito real no runtime.
Isso expõe duas questões: a superfície atual é um placebo e, mesmo quando houver
fluxo real, rodar cartuchos não deve ser uma operação userland. A autoridade
para iniciar cartuchos deve pertencer ao sistema/firmware.
Isso cria uma falsa promessa de plataforma:
- o programa consegue declarar e chamar uma operação que aparenta iniciar cartuchos;
- o loader aceita sua existência;
- o runtime retorna sucesso vazio;
- nenhuma troca de cartucho, transição de firmware, validação de alvo ou política de segurança ocorre.
## Dor
- A ABI expõe uma capability de sistema que, na prática, nao existe.
- Mesmo se implementada, a operação não deve ser uma syscall userland comum:
apps não devem iniciar cartuchos diretamente.
- O guest pode acreditar que solicitou uma troca de app quando nada aconteceu.
- Isso corrói a confiabilidade da plataforma: a interface pública deixa de ser contrato e vira placebo.
- Qualquer ferramenta, SDK ou documentação construída sobre essa syscall passa a modelar um comportamento inexistente.
## Alvo da Discussao
Definir o contrato real da troca de cartucho iniciada pelo sistema do ponto de vista:
- do guest;
- do runtime;
- do firmware;
- do host/cartridge loader.
Ao final da discussão, deve ficar claro se a superfície atual:
- permanece apenas como mecanismo interno do sistema e sai da ABI userland; ou
- permanece na ABI somente como superfície privilegiada impossível de chamar por apps comuns; ou
- sai temporariamente da ABI até existir fluxo fechado.
Esta discussao nao deve depender do fechamento previo do formato `.pmc`.
Para o primeiro fluxo fechado, `system.run_cart` pode resolver um alvo por
um loader ja disponivel, incluindo cartucho em diretorio ou fixture de teste.
O suporte ao artefato empacotado `.pmc` permanece responsabilidade da
`DSC-0003 / packed-cartridge-loader-pmc` e nao deve bloquear a prova inicial
de troca `Shell/Hub -> Game`.
Tambem precisa ficar claro que `run_cart`, se existir, nao e o orquestrador da
troca. No boot direto por linha de comando, carregar um cartucho e simples
porque o runtime nasce ja apontado para aquele jogo. Com o SO em execucao, o
caso real e diferente: pode haver um Game residente/rodando, o usuario volta
para Home, e o sistema decide iniciar outro Game. Nesse caso o SO precisa
orquestrar fechamento/suspensao descartada do app atual, limpeza de estado,
resolucao do novo alvo, carregamento e transicao para o proximo estado de
firmware. O carregador de cartucho e apenas uma etapa desse fluxo.
A direcao preferida e que a orquestracao de troca de cartucho viva no
SystemOS. Porem, essa agenda nao deve capturar o caso `Game -> Home -> mesmo
Game`: esse e o escopo da `AGD-0041`, que precisa fechar foreground,
pausa/suspensao e retorno ao mesmo Game. A troca `Home -> outro Game`, com
fechamento do jogo atual e carregamento de outro cartucho, pode merecer uma
agenda propria depois da `AGD-0041`, derivada do contrato de foreground que ela
fechar.
## O Que Precisa Ser Definido
1. Semântica da operação.
O que significa "run cart" quando existe SO: trocar imediatamente,
agendar para o próximo frame, iniciar uma transicao orquestrada pelo
sistema, ou apenas carregar bytes de cartucho como etapa interna?
2. Origem do alvo.
Como o guest identifica o cartucho alvo: id numérico, nome canônico, path virtual, handle, manifesto, ou nenhum argumento nesta primeira versão?
Para v1, uma opcao aceitavel e limitar a resolucao a alvos conhecidos pelo host/test harness e carregaveis pelo loader de diretorio, deixando `.pmc` fora do caminho critico.
3. Modelo de segurança.
Nenhum app/userland deve chamar `run_cart`. O sistema/firmware e o caminho
host/CLI/debug devem ser as unicas autoridades para iniciar cartuchos.
Se apps precisarem solicitar navegacao no futuro, isso deve ser uma
superficie nova e mediada pelo sistema.
4. Ponto de integração.
Onde a transição vive: `VirtualMachineRuntime`, firmware, host, SystemOS,
ou combinação dos três? Para esta agenda, a decisao minima e separar o boot
direto host/CLI/debug da ABI guest. A orquestracao `Home -> outro Game`
pertence a `DSC-0043 / AGD-0044`.
5. Efeitos observáveis.
O que acontece quando um guest tenta chamar a superficie removida, e como
ferramentas/boot direto continuam carregando cartuchos sem depender de uma
syscall userland?
6. Contrato de erro.
Remocao da ABI significa erro de build/declaracao, syscall desconhecida,
ou bloqueio em registro/capability ate a limpeza completa das declaracoes?
## O Que Necessita Para Resolver
- remocao de `system.run_cart` da ABI userland;
- definicao de que boot direto continua por caminho host/CLI/debug, nao por
syscall guest;
- separacao explicita entre boot direto, loader interno e orquestracao
`Home -> outro Game` da `DSC-0043 / AGD-0044`;
- testes garantindo que guest/userland nao pode declarar/chamar `run_cart`;
- testes garantindo que boot direto de cartucho continua funcional.
## Fora de Escopo
- catálogo completo de apps instalados;
- UX final do launcher/hub;
- resolução remota ou download de cartuchos;
- política de marketplace/distribuição.
- obrigatoriedade de boot a partir de `.pmc` no primeiro fluxo funcional.
## Sugestao / Recomendacao
Recomendo remover `system.run_cart` da ABI userland para v1. Nao ha necessidade
de compatibilidade com a superficie atual: ela nao deve permanecer como stub,
syscall reservada chamavel por guest, nem sucesso vazio.
Rodar cartuchos deve ser uma operacao interna do SystemOS/firmware ou do
caminho host/CLI/debug, nunca uma syscall de app. O boot direto deve continuar
existindo porque e o fluxo essencial para testar cartuchos em desenvolvimento e
tambem representa o modo futuro de executar um jogo unico, como em uma
integracao tipo Steam.
Recomendo tambem separar dois conceitos:
- **boot direto:** usado por linha de comando/debug, inicia o runtime ja com um
cartucho alvo e pode continuar simples;
- **troca via SO:** fluxo orquestrado pelo SystemOS, que fecha o app
atual quando necessario, limpa estado cartridge-scoped, resolve o proximo
alvo e so entao chama o carregador.
Essa agenda nao deve implementar o fluxo `Game -> Home -> mesmo Game`; esse
trabalho pertence a `AGD-0041`. Depois dela, a troca `Home -> outro Game` deve
ser aberta ou refinada como discussao propria, porque adiciona fechamento do
jogo atual, limpeza cartridge-scoped, resolucao de novo alvo e falhas de load.
Se a plataforma precisar de uma ação solicitável por apps no futuro, ela deve
ser modelada separadamente como pedido de navegação mediado pelo sistema, com
nome e erros que não prometam boot direto.
## Respostas Atuais
- `system.run_cart` deve ser removido da ABI userland.
- Nao precisamos manter compatibilidade com a superficie atual.
- Nao deve existir syscall publica para app iniciar cartucho.
- Boot direto por linha de comando, host, debug ou fluxo equivalente de jogo
unico deve permanecer.
- O carregamento interno pode continuar usando loader ja disponivel, incluindo
cartucho em diretorio/fixture.
- `.pmc`, catalogo, UX final de launcher e troca `Game A -> Home -> Game B`
ficam fora desta agenda.
- Se no futuro apps precisarem pedir navegacao, isso deve ser uma nova
superficie mediada pelo sistema, nao a volta de `run_cart` userland.
## Critério de Saida Desta Agenda
Esta agenda só pode virar PR de implementação quando existir decisão escrita para:
- retirada da superfície userland atual;
- preservacao explicita do boot direto host/CLI/debug;
- comportamento esperado para declaracao/chamada guest obsoleta;
- fronteira com `AGD-0041` e `AGD-0044`;
- cobertura minima de testes para remocao userland e boot direto.
## Discussao
- 2026-07-03: A agenda deve ser aberta antes da `AGD-0041` como habilitadora
de validacao do ciclo `Shell/Hub -> Game`. Ficou definido como premissa de
agenda que o primeiro `system.run_cart` testavel nao depende de `.pmc`; ele
pode usar cartucho em diretorio ou fixture resolvida pelo host/test harness.
- 2026-07-03: Direcao ajustada: `run_cart` nao deve ser uma operacao userland.
A autoridade de iniciar cartuchos deve pertencer ao sistema/firmware; apps
podem, no maximo, solicitar navegacao por uma superficie separada e mediada.
- 2026-07-03: Direcao refinada: `run_cart` simples nao resolve o caso com SO.
Boot direto por linha de comando continua sendo um caminho simples, mas
iniciar outro jogo a partir do Home exige um orquestrador do SO/firmware que
fecha o app atual, limpa estado e so entao carrega o novo cartucho.
- 2026-07-03: Escopo refinado: `Game -> Home -> mesmo Game` pertence a
`AGD-0041`. A agenda atual nao deve absorver esse trabalho. Depois da
`AGD-0041`, a troca `Home -> outro Game` pode ser aberta ou refinada como
agenda propria para o orquestrador de troca de cartucho no SystemOS.
- 2026-07-03: A troca `Game A -> Home -> Game B` foi separada para
`DSC-0043 / AGD-0044`, mantendo esta agenda focada na superficie
`run_cart`/loader e sua remocao ou restricao como operacao userland.
- 2026-07-03: Direcao aceita para esta agenda: remover `system.run_cart` da ABI
userland sem necessidade de compatibilidade, manter boot direto para
CLI/debug/teste de cartuchos e futuro modo de jogo unico, e deixar navegacao
mediada por apps para uma superficie futura separada se ela vier a existir.

78
discussion/workflow/agendas/AGD-0041-foreground-stack-game-pause-shell-vm-backed.md
View File

@ -2,10 +2,10 @@
id: AGD-0041
ticket: foreground-stack-game-pause-shell-vm-backed
title: Foreground Stack, Game Pause, and VM-Backed Shell Coexistence
status: open
status: accepted
created: 2026-06-05
resolved:
decision:
resolved: 2026-07-03
decision: DEC-0037
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
---
@ -99,16 +99,49 @@ Isso preserva o ciclo `Game -> Home/Shell -> Game` sem transformar o runtime em
## Perguntas em Aberto
- [ ] Qual e o nome canonico dos estados de Game fora do foreground: `Paused`, `Suspended`, ambos, ou outro?
- [ ] Ao apertar Home, o Game deve receber um evento/interrupt/trap de pausa antes de parar de executar?
- [ ] O Hub e um Shell especial sempre presente ou uma task Shell comum?
- [ ] Um app Shell VM-backed pode substituir o Hub no foreground ou o Hub permanece como owner raiz?
- [ ] Quando o Shell VM-backed fecha, o retorno vai sempre para Hub ou pode voltar diretamente ao Game?
- [ ] O input do Game e drenado/limpo ao pausar e ao retomar?
- [ ] Audio do Game pausa junto com a VM ou tem politica propria?
- [ ] Existe limite de memoria/residencia para manter Game pausado enquanto Shell app roda?
- [ ] O retorno ao Game exige novo frame antes de trocar a superficie, ou a tela pode manter Hub/Shell ate a primeira submission valida?
- [ ] Quais eventos de lifecycle precisam ser visiveis para firmware, OS, VM e host?
- [x] Qual e o nome canonico dos estados de Game fora do foreground: `Paused`, `Suspended`, ambos, ou outro?
- [x] Ao apertar Home, o Game deve receber um evento/interrupt/trap de pausa antes de parar de executar?
- [x] O Hub e um Shell especial sempre presente ou uma task Shell comum?
- [x] Um app Shell VM-backed pode substituir o Hub no foreground ou o Hub permanece como owner raiz?
- [x] Quando o Shell VM-backed fecha, o retorno vai sempre para Hub ou pode voltar diretamente ao Game?
- [x] O input do Game e drenado/limpo ao pausar e ao retomar?
- [x] Audio do Game pausa junto com a VM ou tem politica propria?
- [x] Existe limite de memoria/residencia para manter Game pausado enquanto Shell app roda?
- [x] O retorno ao Game exige novo frame antes de trocar a superficie, ou a tela pode manter Hub/Shell ate a primeira submission valida?
- [x] Quais eventos de lifecycle precisam ser visiveis para firmware, OS, VM e host?
## Resolucao
Fica aceito o modelo `Game -> Home/Shell -> mesmo Game` com foreground unico e
residencia limitada:
- somente um Game pode estar residente por vez;
- somente um Shell pode ser foreground por vez;
- Hub e o Shell root/especial e permanece owner raiz/back-stack;
- um Shell VM-backed pode assumir o foreground visual, mas segue lifecycle de
Shell e nao herda politica de game loop;
- fechar um Shell VM-backed retorna ao Hub em v1;
- background execution real fica fora de escopo;
- no host desktop, `Esc` e a tecla principal para solicitar Home/SystemOS e a
tecla fisica `Home` pode existir como alias;
- a acao Home/SystemOS e interceptada pelo host/SystemOS e nao entra no pad
logico visivel ao Game;
- `Paused` e o estado/evento cooperativo visivel ao Game;
- `Suspended` e o estado operacional imposto pelo OS/scheduler;
- ao sair do foreground, o OS notifica o Game para pausar e concede um budget
curto de reacao;
- se o Game nao reagir ao pause dentro do budget, o OS suspende a VM mesmo
assim;
- ao retornar, o OS reativa a VM, notifica o Game para resume/foreground
restore e permite que o Game sincronize antes de voltar ao gameplay;
- input pendente do Game e drenado/limpo nas fronteiras de pause/resume;
- audio do Game pausa junto com a VM em v1;
- retorno ao Game deve manter Hub/Shell visivel ate a primeira render submission
valida do Game retomado;
- render ownership muda junto com o foreground owner e invalida submissions
antigas via epoch/generation;
- firmware observa transicoes macro; OS observa lifecycle completo; VM observa
pause/resume; host observa owner/render epoch e estado de apresentacao.
## Criterio para Encerrar
@ -124,3 +157,22 @@ A agenda pode ser encerrada quando tivermos uma decisao clara sobre:
## Discussao
- 2026-06-05: Agenda criada a partir da `DSC-0040`, quando o caso de Shell VM-backed aberto sobre um Game pausado mostrou que a discussao pertence ao lifecycle/SystemOS, nao apenas ao render worker.
- 2026-07-03: Direcao provisoria aceita para as perguntas 2-10:
Game deve receber evento de pausa com budget curto antes da suspensao; Hub e
Shell root/especial; Shell VM-backed pode assumir foreground visual, mas Hub
permanece como owner raiz/back-stack; fechar Shell VM-backed retorna ao Hub em
v1; input do Game deve ser drenado/limpo em pause/resume; audio do Game pausa
junto com VM em v1; apenas um Game pausado residente e permitido; retorno ao
Game deve manter Hub/Shell visivel ate a primeira submission valida; firmware
ve transicoes macro, OS ve lifecycle completo, VM ve pause/resume, host ve
owner/render epoch e estado de apresentacao.
- 2026-07-03: Pergunta 1 permanece aberta para esclarecer se `Paused` e
`Suspended` sao estados distintos, nomes para camadas diferentes, ou se v1
deve expor somente um deles.
- 2026-07-03: Direcao proposta para pergunta 1: `Paused` e o estado/evento
cooperativo visivel ao Game; `Suspended` e o estado operacional imposto pelo
OS. Ao sair do foreground, o OS notifica o Game para pausar e concede um
budget curto de reacao; se o Game nao reagir, o OS suspende a VM mesmo assim.
Ao retornar, o OS notifica o Game antes de recoloca-lo no foreground visual,
permitindo sincronizacao/revalidacao. O Game nao controla a suspensao, mas
pode observar `pause`/`resume` para ajustar seu estado interno.

161
discussion/workflow/agendas/AGD-0045-systemos-library-root-home-game-launch.md
View File

@ -1,161 +0,0 @@
---
id: AGD-0045
ticket: system-run-cart
title: SystemOS Library Root and Home Game Launch
status: accepted
created: 2026-07-03
resolved:
decision:
tags: [runtime, os, hub, cartridge, launcher, library, game, architecture]
---
## Contexto
A `DEC-0035` fechou que `system.run_cart` nao deve existir como syscall
userland e que boot direto por host/CLI/debug deve permanecer.
Isso resolveu a autoridade negativa, mas ainda nao resolveu a experiencia
desejada para o SO: apontar o runtime para um diretorio raiz de biblioteca,
fazer a Home listar os cartuchos encontrados ali e permitir que o usuario clique
em um jogo para carrega-lo.
O objetivo pratico e um "Switch feio": uma lista simples na Home, sem UX final,
sem marketplace e sem catalogo rico, mas capaz de provar que o SO, e nao o
guest, escolhe e carrega um cartucho a partir de uma biblioteca local.
## Problema
Hoje temos dois caminhos separados:
- boot direto por `--run <cart>` funciona e carrega um cartucho unico;
- Hub/Home existe, mas mostra acoes fixas de Shell nativo e nao lista jogos de
uma biblioteca real.
Sem uma biblioteca de cartuchos visivel para o SO, o usuario nao consegue
iniciar jogos a partir da Home. Isso deixa a agenda `system-run-cart` incompleta
do ponto de vista de produto: removemos o `run_cart` userland, mas ainda falta a
alternativa correta, que e o SO iniciar cartuchos por acao de usuario.
## Pontos Criticos
- O root da biblioteca deve ser fornecido pelo host como `--games-root <dir>`.
- O scan inicial deve cobrir subdiretorios imediatos com `manifest.json`.
- O loader de diretorio existente deve continuar sendo a autoridade para validar
cartucho completo; a biblioteca pode ler metadados minimos para listagem.
- A Home pode mostrar uma lista feia/clicavel; polimento visual fica fora.
- O clique em um Game deve iniciar `LoadCartridge` pelo firmware/SystemOS, nao
por syscall guest.
- V1 nao precisa tratar retorno de um Game para Home, porque isso pertence a
`AGD-0041`.
- `.pmc`, outros tipos de app, catalogo remoto, marketplace, icones, busca e
metadados ricos ficam fora.
## Opcoes
### Opcao A - Biblioteca apenas para listagem
- **Abordagem:** adicionar `--games-root`, escanear manifestos e mostrar jogos
na Home, mas sem permitir launch ainda.
- **Pro:** baixa complexidade; prova descoberta/catalogo local.
- **Contra:** nao entrega o objetivo principal de carregar jogo pela Home.
- **Manutenibilidade:** boa, mas valor funcional limitado.
### Opcao B - Home lista biblioteca e carrega Game quando nao ha Game ativo
- **Abordagem:** adicionar `--games-root`, escanear cartuchos locais, renderizar
lista simples na Home e permitir clique para carregar um Game via
`LoadCartridge`. A primeira versao cobre Home inicial/sem Game residente.
- **Pro:** entrega o fluxo desejado sem abrir troca completa entre jogos.
- **Contra:** exige passar biblioteca/acao selecionada entre host, Hub,
firmware e loader.
- **Manutenibilidade:** boa se a fronteira ficar clara: biblioteca descobre,
Hub escolhe, firmware carrega.
### Opcao C - Biblioteca mais troca completa entre jogos
- **Abordagem:** Home lista biblioteca e tambem permite `Game A -> Home ->
Game B` ja no primeiro passo.
- **Pro:** cobre a experiencia final.
- **Contra:** mistura biblioteca com pausa, fechamento, cleanup e falha de load;
depende de `AGD-0041` e `AGD-0044`.
- **Manutenibilidade:** baixa para v1.
## Sugestao / Recomendacao
Recomendo a Opcao B.
O v1 deve permitir:
- host recebe `--games-root <dir>`;
- o SO/Hub recebe uma lista de cartuchos descobertos;
- a Home mostra uma lista simples/clicavel de jogos;
- clicar em um Game carrega o cartucho via firmware `LoadCartridge`;
- boot direto por `--run <cart>` continua separado e intacto;
- nenhum guest/app chama `run_cart`;
- o escopo v1 acontece na Home inicial; retorno de Game para Home fica para
`AGD-0041`, e troca `Game A -> Home -> Game B` fica para `AGD-0044`.
Detalhes aceitos para v1:
- scan apenas de subdiretorios imediatos;
- somente cartuchos `app_mode: Game`;
- `.pmc` fica para futuro;
- cartuchos invalidos sao logados e omitidos da lista;
- o modelo interno deve ser uma entry de biblioteca expansivel, nao apenas um
summary de UI. A entry pode manter o manifest carregado em memoria, path
interno necessario para launch e metadados operacionais como instante de
descoberta/instalacao. A UI v1 mostra apenas `title`, `app_id` e
`app_version`, mas futuros metadados ingeridos pela biblioteca poderao ser
usados pelo catalogo e pela propria UI;
- clique carrega imediatamente, sem confirmacao;
- falha de load volta para Home e registra log/erro.
Essa agenda deve produzir a alternativa correta ao `run_cart` userland: uma
acao de sistema, iniciada pela Home, que carrega cartucho escolhido pelo usuario
a partir de uma biblioteca local.
## Perguntas em Aberto
- [x] O argumento deve se chamar `--games-root`.
- [x] A biblioteca deve escanear apenas subdiretorios imediatos.
- [x] A listagem v1 deve incluir apenas `app_mode: Game`.
- [x] O scan deve logar cartuchos invalidos e omiti-los da lista.
- [x] O Hub/SystemOS deve receber uma entry de biblioteca expansivel, capaz de
manter o manifest carregado, path interno para launch e metadados
operacionais como timestamp de descoberta/instalacao. A UI v1 so precisa
mostrar `title`, `app_id` e `app_version`.
- [x] O clique deve carregar imediatamente, sem confirmacao.
- [x] Se um cartucho falha ao carregar, o sistema volta para Home e registra
erro/log.
- [x] Retorno de Game para Home nao pertence a esta agenda; fica para
`AGD-0041`.
- [x] O teste minimo deve provar o fluxo `games-root -> Home list -> click ->
LoadCartridge -> GameRunning`?
## Criterio para Encerrar
A agenda pode virar decisao quando estiver claro:
- nome e semantica do argumento de host para root da biblioteca;
- escopo do scan e metadados minimos;
- fronteira entre biblioteca, Hub, firmware e loader;
- politica v1 para cartuchos invalidos;
- regra v1 para launch quando nao ha Game ativo;
- fronteira explicita com `AGD-0041` e `AGD-0044`;
- testes minimos para discovery e launch pela Home.
## Discussao
- 2026-07-03: Agenda criada como continuacao da `DSC-0004` apos a `DEC-0035`.
A decisao anterior removeu `run_cart` userland; esta agenda define o caminho
correto para o SO/Home carregar jogos a partir de uma biblioteca local.
- 2026-07-03: Respostas aceitas: usar `--games-root`, escanear apenas
subdiretorios imediatos, listar somente Games, deixar `.pmc` e outros apps
para depois, logar/omitir invalidos, usar summary com `title`, `app_id` e
`app_version`, carregar imediatamente no clique, e deixar retorno para Home
sob responsabilidade da `AGD-0041`.
- 2026-07-03: Modelo de dados refinado: a biblioteca deve produzir entries
expansíveis, nao somente summaries de UI. Cada entry pode manter manifest em
memoria, path interno de launch e metadados operacionais como timestamp de
descoberta/instalacao; a UI v1 escolhe quais campos mostrar, mas o modelo
deve permitir que metadados futuros sejam ingeridos e usados pelo catalogo/UI.

136
discussion/workflow/decisions/DEC-0035-remove-userland-system-run-cart-and-preserve-direct-boot.md
View File

@ -1,136 +0,0 @@
---
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`.

156
discussion/workflow/decisions/DEC-0036-systemos-games-root-and-home-game-launch.md
View File

@ -1,156 +0,0 @@
---
id: DEC-0036
ticket: system-run-cart
title: SystemOS Games Root and Home Game Launch
status: accepted
created: 2026-07-03
ref_agenda: AGD-0045
tags: []
---
## Status
Accepted.
## Contexto
`DEC-0035` removed `system.run_cart` from the userland guest ABI and preserved
direct host/CLI/debug cartridge boot. That decision intentionally did not
deliver the Home/SO product flow: pointing PROMETEU at a local games directory,
listing available games in Home, and launching a selected game by user action.
This decision defines the first system-owned replacement for userland
`run_cart`: a local games-root library discovered by the host/SystemOS and
exposed through a simple Home UI.
## Decisao
PROMETEU MUST support a host-provided games library root through
`--games-root <dir>`.
The games root is a directory containing game cartridge directories as immediate
children. V1 MUST scan only immediate child directories. Recursive discovery is
out of scope.
The v1 games library MUST include only cartridges whose manifest declares
`app_mode: Game`. Shell/System apps, `.pmc` packages, remote catalogs,
marketplace/distribution metadata, rich icons, search, and non-game apps are out
of scope.
The library MUST produce expandable internal entries, not UI-only summaries.
Each entry MUST retain enough internal data to launch the cartridge and to grow
as a catalog model. At minimum, each entry MUST include:
- loaded manifest data;
- `title`;
- `app_id`;
- `app_version`;
- internal cartridge path;
- operational discovery metadata, including a timestamp or equivalent discovery
marker.
The Home UI v1 SHOULD display only `title`, `app_id`, and `app_version`. It MAY
hide path and operational metadata.
Invalid cartridge candidates MUST be logged and omitted from the Home game list.
Selecting a listed Game in Home MUST immediately request a system-owned launch
through firmware/SystemOS, resulting in `LoadCartridge` for that cartridge. This
MUST NOT use a guest syscall and MUST NOT reintroduce userland `run_cart`.
If launch fails, the machine MUST return to or remain in Home and record an
error/log. A polished error UI is out of scope.
Booting directly with `--run <cart>` MUST remain separate and unchanged.
Returning from a running Game to Home is outside this decision and belongs to
`AGD-0041`. Switching from `Game A -> Home -> Game B` after a game is already
active belongs to `DSC-0043 / AGD-0044`.
## Rationale
The previous `run_cart` surface was wrong because it made cartridge launch look
like an app/userland capability. The desired behavior is still valid, but the
authority must live in the system: Home presents available games and the
firmware/SystemOS loads the selected cartridge.
Using `--games-root` keeps the v1 product model honest: this is a local game
library, not a general app root. Other app types can be introduced later without
forcing the first launcher model to pretend it is a full marketplace.
Immediate child scanning keeps discovery deterministic and testable. `.pmc` and
recursive layouts can be added after the directory-cartridge path is proven.
An expandable entry model avoids prematurely freezing the UI shape as the data
model. The UI is intentionally simple, but the catalog model needs room for
future metadata such as package origin, installation/discovery timestamps, rich
presentation fields, and packaged cartridge details.
## Invariantes / Contrato
- `--games-root <dir>` is the v1 host argument for a local games library.
- The games root is Game-only in v1.
- Discovery scans immediate child directories only.
- Directory candidates without valid Game cartridge metadata are logged and
omitted.
- Library entries are internal catalog records, not direct UI DTOs.
- The UI v1 displays a simple clickable list and may show only `title`,
`app_id`, and `app_version`.
- The internal entry retains cartridge path and loaded manifest data for launch.
- Home selection is a system action that enters firmware/SystemOS loading. It is
not a guest syscall.
- `--run <cart>` direct boot remains independent from `--games-root`.
- Return-to-Home and game-to-game switching are not implemented by this
decision.
## Impactos
- **Host:** add a `--games-root <dir>` argument and pass the resolved root into
runtime/firmware/SystemOS initialization.
- **SystemOS / Hub:** add a local game library model and expose entries to Home.
Home must render a minimal clickable list and emit a system-owned launch
action for a selected entry.
- **Firmware:** consume the Home launch action and transition to
`LoadCartridge` with the selected cartridge path.
- **Loader:** continue to validate complete directory cartridges. Discovery may
read manifest metadata, but full launch still uses the existing loader.
- **Runtime / VM:** no userland ABI is added. No guest syscall participates in
launch.
- **Specs / Docs:** document `--games-root`, Game-only v1 discovery, and the
distinction between direct boot, games library launch, and future game
switching.
- **Tests:** cover discovery, invalid omission/logging, Home action emission,
and the end-to-end path from games root selection to `GameRunning`.
## Alternativas Descartadas
- **List only, no launch:** rejected because it does not satisfy the product
goal of starting games from Home.
- **General app root:** rejected for v1 because Shell/System apps need separate
lifecycle and UI contracts.
- **Recursive discovery:** rejected for v1 to keep semantics deterministic.
- **`.pmc` discovery:** rejected for v1 because packed cartridge loading is a
separate open agenda.
- **Game-to-game switch now:** rejected because it depends on foreground and
cartridge-switch orchestration work in `AGD-0041` and `AGD-0044`.
## Referencias
- Source agenda: `AGD-0045`
- Userland run-cart removal: `DEC-0035`
- Foreground/Home return scope: `AGD-0041`
- Future cartridge switch orchestration: `DSC-0043 / AGD-0044`
## Propagacao Necessaria
- Add or update runtime specs for games-root discovery and Home launch.
- Add host CLI argument plumbing for `--games-root`.
- Add a catalog/library entry model.
- Add Hub/Home list rendering and click handling.
- Add firmware/SystemOS action routing to `LoadCartridge`.
- Add tests for discovery, invalid candidates, action emission, and
`games-root -> Home click -> GameRunning`.
## Revision Log
- 2026-07-03: Initial draft from `AGD-0045`.

191
discussion/workflow/decisions/DEC-0037-foreground-stack-and-game-pause-contract.md Normal file
View File

@ -0,0 +1,191 @@
---
id: DEC-0037
ticket: foreground-stack-game-pause-shell-vm-backed
title: Foreground Stack and Game Pause Contract
status: accepted
created: 2026-07-03
ref_agenda: AGD-0041
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
---
## Status
Accepted.
## Contexto
`AGD-0041` defines the minimum lifecycle contract for `Game -> Home/Shell ->
same Game`.
The issue is not only rendering. The render worker needs a single valid visual
owner, but SystemOS must decide which VMs may exist, which owner receives input,
which owner may tick, what happens to a Game when Home takes foreground, and how
a VM-backed Shell app coexists with a paused Game.
This decision builds on:
- `DSC-0031`: runtime mode separation between Game and System/Shell;
- `DSC-0032`: SystemOS lifecycle/process/task authority;
- `DSC-0035`: task-owned Shell windows and Shell liveness;
- `DSC-0036`: Hub/Shell as a lifecycle proving surface;
- `DSC-0040`: render ownership/epoch and stale submission invalidation.
## Decisao
PROMETEU MUST use a single-foreground-owner model for v1.
At most one Game MAY be resident at a time. At most one Shell app MAY be the
foreground visual owner at a time.
The Hub MUST be treated as the root/special Shell owner for Home. A VM-backed
Shell app MAY replace the Hub as the foreground visual owner, but the Hub
remains the root/back-stack controller. In v1, closing a VM-backed Shell app
MUST return to Hub/Home, not directly to the Game.
When the user requests Home while a Game is running, SystemOS MUST start a
cooperative pause transition:
- the Game receives a pause lifecycle notification;
- the Game is given a short bounded budget to react;
- after that budget, SystemOS MAY suspend the Game VM even if the Game did not
cooperate;
- the Game remains resident but MUST NOT receive normal gameplay ticks, normal
game input, or frame pacing while suspended;
- the Shell/Hub foreground owner MAY execute according to Shell lifecycle rules.
`Paused` is the Game-visible lifecycle state/event. `Suspended` is the
OS/scheduler operational state. A Game may observe pause/resume, but it MUST NOT
control whether the OS suspends or resumes its VM.
When returning to the same Game, SystemOS MUST reactivate the Game VM and send a
resume or foreground-restore lifecycle notification before restoring visual
foreground. The Game MAY remain internally paused while it synchronizes. The
system MUST keep Hub/Shell visible until the resumed Game produces a valid new
render submission for the current ownership epoch.
Input pending for the Game MUST be drained or cleared across pause/resume
boundaries. Game audio MUST pause with the Game VM in v1. Independent background
audio policy is out of scope.
Render ownership MUST move with the foreground owner. Foreground transitions
MUST invalidate stale render submissions through ownership epoch/generation so
old Game frames cannot be presented after Shell takes foreground, and old Shell
frames cannot be presented after the Game resumes.
On the desktop host, `Esc` MUST be the primary keyboard request for Home/SystemOS.
The physical `Home` key MAY be supported as an alias. This Home request is a
host/SystemOS control action and MUST NOT be exposed as a normal guest pad
button or userland input capability.
Real background execution, multiple resident Games, multiple foreground Shells,
Game-to-Game switching, Shell app persistence policy, memory eviction policy,
and rich multitasking are out of scope for this decision.
## Rationale
The chosen model preserves the expected console-like flow: a Game can be
paused, Home can run, Shell apps can open, and the same Game can resume without
turning the runtime into a general multitasking scheduler.
Separating `Paused` from `Suspended` keeps authority clear. `Paused` is the
contract the Game can observe and react to. `Suspended` is the OS mechanism that
prevents the paused Game from continuing to consume ticks, input, audio, and
render ownership while another owner is foreground.
Keeping Hub as root/back-stack prevents VM-backed Shell apps from becoming
independent lifecycle roots. Returning to Hub before resuming Game keeps v1
navigation deterministic and leaves more complex direct-return behavior for a
future decision.
Keeping Hub/Shell visible until the Game submits a new valid frame avoids
presenting stale pixels from the previous Game epoch. This aligns lifecycle
state with the render ownership model from `DSC-0040`.
Using `Esc` as desktop Home makes the control available on compact keyboards.
Supporting the physical `Home` key as an alias is acceptable, but the portable
contract cannot depend on it.
## Invariantes / Contrato
- There is exactly one foreground visual owner at a time.
- V1 supports at most one resident Game.
- V1 supports at most one foreground Shell app.
- Hub/Home is the root Shell owner and back-stack controller.
- VM-backed Shell apps follow Shell lifecycle, not Game loop lifecycle.
- A paused Game may remain resident, but a suspended Game does not receive
normal gameplay ticks, normal game input, or frame pacing.
- Pause/resume are cooperative Game-visible lifecycle events.
- Suspend/resume scheduling authority belongs to SystemOS.
- SystemOS may suspend a Game after the pause budget even if the Game does not
cooperate.
- Input is cleared or barriered across Game pause/resume boundaries.
- Game audio pauses with the Game VM in v1.
- Foreground transitions advance render ownership epoch/generation.
- Visual foreground returns to Game only after a valid current-epoch Game render
submission exists.
- Desktop `Esc` is a host/SystemOS Home request; physical `Home` may alias it.
- Home/SystemOS is not a guest pad button and is not userland input.
- Background execution and general multitasking are explicitly excluded.
## Impactos
- **Spec:** runtime lifecycle, firmware/Hub, input, and render ownership specs
must document foreground ownership, pause/suspend semantics, Home key mapping,
and stale frame invalidation.
- **Runtime / SystemOS:** SystemOS needs explicit foreground owner, Hub root,
Shell foreground, Game paused, and Game suspended state.
- **VM:** VM execution must support pause/resume lifecycle delivery and OS-owned
suspension of ticks.
- **Firmware:** firmware should observe macro transitions such as GameRunning,
Hub/Home, Shell foreground, pause request, and resume request without owning
every internal OS detail.
- **Host:** host must route desktop `Esc` and optional physical `Home` to a
SystemOS Home request instead of guest pad input.
- **Input:** Game input must be drained or barriered during pause/resume and
Home/SystemOS must stay outside the guest-visible pad ABI.
- **Audio:** v1 audio follows Game pause/suspend and does not continue as
independent background audio.
- **Renderer:** render publication must reject stale submissions after ownership
epoch changes and keep previous foreground visible until the resumed Game
publishes a valid current-epoch frame.
- **Tests:** coverage must prove pause budget behavior, non-foreground VM
non-execution, input clearing, host Home routing, Shell return-to-Hub, and
stale render rejection.
## Alternativas Descartadas
- **Terminate Game when entering Shell:** rejected because it makes
`Game -> Shell -> Game` a reload rather than a pause/resume flow.
- **Real background execution now:** rejected because it pulls in scheduler,
budget, energy, audio, input, IO, memory, and persistence policy beyond v1.
- **Multiple resident Games:** rejected for v1 because Game-to-Game switching is
owned by `DSC-0043 / AGD-0044`.
- **Expose Home as guest input:** rejected because Home changes system
foreground authority and must not be handled as ordinary game input.
- **Return directly from Shell app to Game in v1:** rejected to keep Hub as the
deterministic root/back-stack owner.
## Referencias
- Source agenda: `AGD-0041`
- Runtime mode separation: `DSC-0031`
- SystemOS lifecycle authority: `DSC-0032`
- Shell task/window lifecycle: `DSC-0035`
- Hub UI direction: `DSC-0036`
- Render ownership and stale submission handling: `DSC-0040`
- Future Game A -> Home -> Game B switching: `DSC-0043 / AGD-0044`
## Propagacao Necessaria
- Update canonical runtime specs for foreground ownership and pause/suspend.
- Specify desktop Home request mapping in host/input documentation.
- Add plan(s) for SystemOS foreground stack state and Game pause/suspend.
- Add plan(s) for VM lifecycle event delivery and forced suspension budget.
- Add plan(s) for host `Esc`/`Home` routing outside guest pad input.
- Add plan(s) for render epoch integration during Game/Shell transitions.
- Add tests covering lifecycle, input, host routing, and render publication
invariants.
## Revision Log
- 2026-07-03: Initial decision from `AGD-0041`.

90
discussion/workflow/plans/PLN-0129-remove-userland-run-cart-abi-surface.md
View File

@ -1,90 +0,0 @@
---
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`

79
discussion/workflow/plans/PLN-0130-remove-runtime-run-cart-stub-dispatch.md
View File

@ -1,79 +0,0 @@
---
id: PLN-0130
ticket: system-run-cart
title: Remove Runtime Run Cart Stub Dispatch
status: done
created: 2026-07-03
ref_decisions: [DEC-0035]
tags: []
---
## Briefing
`DEC-0035` forbids a callable userland `system.run_cart` stub. This plan covers
runtime and VM dispatch cleanup so obsolete calls cannot silently succeed.
Public ABI removal is handled by `PLN-0129`; direct boot preservation is handled
by `PLN-0131`.
## Objective
Remove the runtime no-op dispatch path for `SystemRunCart` and ensure stale or
obsolete userland attempts fail explicitly rather than returning success.
## Dependencies
- Source decision: `DEC-0035`.
- Depends on the ABI direction in `PLN-0129`, but can be implemented in the same
PR if the public enum/registry removal and dispatch cleanup move together.
## Scope
- Remove the `Syscall::SystemRunCart => return Ok(())` path from
`crates/console/prometeu-system/src/services/vm_runtime/dispatch.rs`.
- Update any match arms made unreachable or obsolete by removing
`SystemRunCart`.
- Ensure stale numeric syscall ids or stale bytecode declarations fail with the
repository's existing unknown/invalid syscall behavior.
- Add negative coverage for userland attempts to invoke the removed operation,
using the closest existing VM runtime syscall tests.
## Non-Goals
- Do not implement a replacement navigation operation.
- Do not implement the `Home -> another Game` orchestrator.
- Do not alter direct host/CLI/debug cartridge boot paths.
- Do not change `system.has_cart` behavior unless required by compile fallout.
## Execution Method
1. Inspect `dispatch.rs` for all `SystemRunCart` match arms.
2. Remove the no-op success path and any unreachable arms tied only to
`SystemRunCart`.
3. If the public enum variant is removed by `PLN-0129`, update exhaustiveness
and registry mapping accordingly.
4. Add or update VM runtime tests that demonstrate `system.run_cart` is not
callable from guest/userland.
5. Run targeted runtime tests and compile checks.
## Acceptance Criteria
- There is no runtime path where a guest `system.run_cart` call returns `Ok(())`.
- Stale/obsolete attempts fail explicitly through existing invalid syscall or
declaration validation behavior.
- `system.has_cart` and unrelated system syscalls keep their current behavior.
- Runtime dispatch remains exhaustive and clear after removing `SystemRunCart`.
## Tests
- Add a negative test in `crates/console/prometeu-system/src/services/vm_runtime`
for stale userland `run_cart` attempts, if the test harness can express it.
- Run `cargo test` for `prometeu-system` and any impacted syscall crates.
- Run a workspace compile/test command if targeted tests reveal cross-crate enum
fallout.
## Affected Artifacts
- `crates/console/prometeu-system/src/services/vm_runtime/dispatch.rs`
- `crates/console/prometeu-system/src/services/vm_runtime/tests.rs`
- `crates/console/prometeu-hal/src/syscalls.rs`
- `crates/console/prometeu-hal/src/syscalls/registry.rs`

83
discussion/workflow/plans/PLN-0131-preserve-direct-cartridge-boot-coverage.md
View File

@ -1,83 +0,0 @@
---
id: PLN-0131
ticket: system-run-cart
title: Preserve Direct Cartridge Boot Coverage
status: done
created: 2026-07-03
ref_decisions: [DEC-0035]
tags: []
---
## Briefing
`DEC-0035` removes userland `system.run_cart`, but direct cartridge boot remains
mandatory for development, debugging, automated tests, and future single-game
launch scenarios. This plan protects that path while the guest syscall is
removed.
## Objective
Preserve and test host/CLI/debug direct cartridge boot without relying on a
guest syscall.
## Dependencies
- Source decision: `DEC-0035`.
- Can be implemented after or alongside `PLN-0129` and `PLN-0130`.
- Must not depend on `.pmc`, app catalog, launcher UX, `AGD-0041`, or
`AGD-0044`.
## Scope
- Identify direct boot entrypoints in `crates/tools/prometeu-cli/src/main.rs`,
`crates/host/prometeu-host-desktop-winit/src/lib.rs`,
`crates/host/prometeu-host-desktop-winit/src/debugger.rs`, and firmware
cartridge loading code.
- Add or preserve tests showing a cartridge can be loaded directly into
firmware/runtime from host or CLI paths.
- Ensure these paths do not call or require `system.run_cart`.
- Document the distinction between direct boot and guest navigation where
runtime specs describe boot behavior.
## Non-Goals
- Do not implement `Home -> another Game`.
- Do not add app-callable navigation.
- Do not require `.pmc`.
- Do not redesign cartridge loader internals beyond what is required to keep
direct boot working.
## Execution Method
1. Trace the CLI/debug direct boot path from cartridge path argument through
loader, firmware `load_cartridge`, and runtime initialization.
2. Add regression tests at the lowest practical layer proving direct boot still
reaches `GameRunning` for a valid game cartridge.
3. Add a guard or assertion that direct boot does not depend on `system.run_cart`
metadata.
4. Update docs/specs to describe direct boot as host/system-controlled.
5. Run targeted CLI/firmware/host tests.
## Acceptance Criteria
- A valid game cartridge can still boot directly from host/CLI/debug paths.
- Direct boot does not depend on `system.run_cart` being in the guest syscall
registry.
- Existing debugger/handshake metadata that reports cartridge info still works.
- The direct boot behavior is documented as host/system entry, not guest ABI.
## Tests
- Add or preserve firmware tests around `load_cartridge` and `GameRunning`.
- Add or preserve host/CLI tests for cartridge path boot when practical.
- Run `cargo test` for `prometeu-firmware`, `prometeu-host-desktop-winit`, and
`prometeu-cli` where available.
## Affected Artifacts
- `crates/tools/prometeu-cli/src/main.rs`
- `crates/host/prometeu-host-desktop-winit/src/lib.rs`
- `crates/host/prometeu-host-desktop-winit/src/debugger.rs`
- `crates/console/prometeu-firmware/src/firmware/firmware.rs`
- `crates/console/prometeu-firmware/src/firmware/firmware_step_load_cartridge.rs`
- `docs/specs/runtime/`

103
discussion/workflow/plans/PLN-0132-specify-games-root-home-launch-contract.md
View File

@ -1,103 +0,0 @@
---
id: PLN-0132
ticket: system-run-cart
title: Specify Games Root Home Launch Contract
status: done
created: 2026-07-03
ref_decisions: [DEC-0036]
tags: []
---
## Briefing
`DEC-0036` establishes a new system-owned game library launch path:
the host receives `--games-root <dir>`, SystemOS/Home lists valid Game
directory cartridges from that root, and selecting one starts the cartridge
through firmware loading rather than a guest syscall.
This plan updates the normative specs before code is changed.
## Objective
Document the v1 games-root and Home launch contract in the canonical runtime
specs so implementation plans cannot drift back into userland `run_cart` or
general app-library semantics.
## Dependencies
- Source decision: `DEC-0036`.
- Prior decision: `DEC-0035`, which removed userland `system.run_cart` and
preserved direct `--run` boot.
- This plan must be completed before `PLN-0133`, `PLN-0134`, and `PLN-0135`.
## Scope
- Update the runtime specs to define `--games-root <dir>` as the v1 local games
library root.
- Specify that discovery scans only immediate child directories.
- Specify that v1 library discovery includes only valid directory cartridges
with `app_mode: Game`.
- Specify that `.pmc`, recursive discovery, Shell/System apps, marketplace
metadata, rich presentation, search, and non-game apps are out of scope.
- Specify the internal library entry contract: loaded manifest data, `title`,
`app_id`, `app_version`, internal cartridge path, and discovery metadata.
- Specify that Home v1 may display only `title`, `app_id`, and `app_version`.
- Specify that selecting a Home game emits a system-owned launch request that
transitions through firmware/SystemOS into `LoadCartridge`.
- Specify that invalid candidates are logged and omitted.
- Specify that launch failure remains or returns to Home and logs the failure.
- Reaffirm that direct `--run <cart>` boot remains independent and unchanged.
## Non-Goals
- No Rust implementation.
- No Home UI changes.
- No `.pmc` discovery or packaged-cartridge spec changes.
- No recursive library layout.
- No return-to-Home behavior for a running Game.
- No Game A -> Home -> Game B orchestration.
- No guest syscall or userland ABI addition.
## Execution Method
1. Update [docs/specs/runtime/14-boot-profiles.md](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/docs/specs/runtime/14-boot-profiles.md) with:
- direct `--run` boot remaining a single-cartridge boot profile;
- `--games-root <dir>` as a SystemOS/Home library profile;
- the distinction between direct boot, Home launch, and future game-switch
orchestration.
2. Update [docs/specs/runtime/12-firmware-pos-and-prometeuhub.md](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/docs/specs/runtime/12-firmware-pos-and-prometeuhub.md) with:
- Home's responsibility to display the local games library;
- the system-owned launch action boundary;
- failure handling that leaves the machine in Home and records an error.
3. Update [docs/specs/runtime/13-cartridge.md](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/docs/specs/runtime/13-cartridge.md) with:
- directory-cartridge discovery requirements for library candidates;
- Game-only filtering by manifest `app_mode`;
- invalid candidate omission and diagnostics.
4. Update [docs/specs/runtime/16-host-abi-and-syscalls.md](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/docs/specs/runtime/16-host-abi-and-syscalls.md) only if needed to reinforce that no guest syscall owns cartridge launch.
5. Keep all spec text in English.
## Acceptance Criteria
- The specs define `--games-root <dir>` and do not describe it as a generic app
root.
- The specs state that v1 scans immediate child directories only.
- The specs state that only valid Game directory cartridges enter the Home list.
- The specs state that Home launch is system-owned and enters `LoadCartridge`.
- The specs preserve `--run <cart>` as a separate direct boot path.
- The specs explicitly exclude `.pmc`, recursive discovery, return-to-Home, and
game-switch orchestration from this implementation slice.
- No spec reintroduces userland `run_cart`.
## Tests
- Run `discussion validate`.
- Run targeted text checks for `--games-root`, `LoadCartridge`, and absence of
`system.run_cart` as an active public launch mechanism in edited specs.
## Affected Artifacts
- `docs/specs/runtime/12-firmware-pos-and-prometeuhub.md`
- `docs/specs/runtime/13-cartridge.md`
- `docs/specs/runtime/14-boot-profiles.md`
- `docs/specs/runtime/16-host-abi-and-syscalls.md`
- `discussion/workflow/plans/PLN-0132-specify-games-root-home-launch-contract.md`

118
discussion/workflow/plans/PLN-0133-implement-games-root-library-discovery.md
View File

@ -1,118 +0,0 @@
---
id: PLN-0133
ticket: system-run-cart
title: Implement Games Root Library Discovery
status: done
created: 2026-07-03
ref_decisions: [DEC-0036]
tags: []
---
## Briefing
`DEC-0036` requires a host-provided games root and an expandable internal
library model before Home can render or launch games. This plan implements the
library discovery and host plumbing only; UI launch wiring is handled by
`PLN-0134`.
## Objective
Add a tested games-root discovery model that scans immediate child directory
cartridges, filters to valid Game manifests, records diagnostics for invalid
candidates, and carries enough metadata for Home rendering and later launch.
## Dependencies
- Source decision: `DEC-0036`.
- `PLN-0132` should be completed first so code follows the documented contract.
- Existing cartridge manifest and directory loader behavior in the console
crates.
- Existing host CLI and `HostRunner` boot setup.
## Scope
- Add `--games-root <PATH>` to the desktop host CLI.
- Pass the optional games root into the host runner / firmware initialization
path without changing direct `--run` or `--debug` boot behavior.
- Add a SystemOS-owned games library model for directory cartridge discovery.
- Scan only immediate child directories of the root.
- Read and retain manifest data for each valid candidate.
- Include only candidates whose manifest declares `app_mode: Game`.
- Retain internal cartridge path and operational discovery metadata on each
entry.
- Emit diagnostics for invalid, unreadable, or non-Game candidates and omit
them from the returned entries.
- Keep discovery independent from full cartridge launch: discovery reads
metadata; launch still uses the existing loader in `PLN-0134`.
## Non-Goals
- No Home list rendering.
- No click handling or `LoadCartridge` transition.
- No `.pmc` discovery.
- No recursive scan.
- No Shell/System app catalog.
- No marketplace metadata, icons, search, sorting UI, or polished errors.
- No new guest syscall.
## Execution Method
1. Introduce a library/discovery module in the SystemOS side, preferably under
`crates/console/prometeu-system/src/services/` unless the existing module
layout has a more local owner.
2. Define an internal entry type with at least:
- loaded cartridge manifest data;
- `title`;
- `app_id`;
- `app_version`;
- internal cartridge path;
- discovery metadata, using `SystemTime` or another explicit discovery
marker.
3. Define discovery diagnostics that can be logged by the caller and asserted in
tests.
4. Implement a scanner that:
- accepts an optional root path;
- returns an empty library when no root is configured;
- iterates only immediate child directories;
- parses `manifest.json` using structured manifest types, not ad hoc string
matching;
- filters to `app_mode: Game`;
- sorts entries deterministically for stable Home presentation and tests.
5. Add `--games-root <PATH>` to
[crates/host/prometeu-host-desktop-winit/src/lib.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/host/prometeu-host-desktop-winit/src/lib.rs)
and pass the path into
[crates/host/prometeu-host-desktop-winit/src/runner.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/host/prometeu-host-desktop-winit/src/runner.rs).
6. Store or expose the discovered library to firmware/SystemOS in a way that
`PLN-0134` can consume without re-scanning inside the Home click path.
7. Add focused unit tests using temporary cartridge roots with:
- one valid Game directory cartridge;
- one valid non-Game cartridge;
- one invalid directory;
- one nested directory that must not be discovered.
## Acceptance Criteria
- `--games-root <PATH>` is accepted by the desktop host CLI.
- Absence of `--games-root` leaves existing Hub boot behavior unchanged.
- Direct `--run <cart>` and `--debug <cart>` behavior remains unchanged.
- Discovery returns only immediate valid Game directory cartridges.
- Each library entry retains manifest data, path, title, app id, app version,
and discovery metadata.
- Invalid candidates are represented in diagnostics and excluded from entries.
- Discovery does not fully load or boot cartridge programs.
## Tests
- Add and run focused games-library discovery tests in the owning console crate.
- Run `cargo test -p prometeu-system` if the library lives in
`prometeu-system`.
- Run `cargo test -p prometeu-host-desktop-winit` for CLI/runner plumbing.
- Run `discussion validate`.
## Affected Artifacts
- `crates/console/prometeu-system/src/services/`
- `crates/console/prometeu-system/src/lib.rs` or module exports as needed
- `crates/host/prometeu-host-desktop-winit/src/lib.rs`
- `crates/host/prometeu-host-desktop-winit/src/runner.rs`
- `discussion/workflow/plans/PLN-0133-implement-games-root-library-discovery.md`

104
discussion/workflow/plans/PLN-0134-wire-home-game-list-launch-flow.md
View File

@ -1,104 +0,0 @@
---
id: PLN-0134
ticket: system-run-cart
title: Wire Home Game List Launch Flow
status: done
created: 2026-07-03
ref_decisions: [DEC-0036]
tags: []
---
## Briefing
After `PLN-0133`, SystemOS can discover a local Game library but Home still
does not present or launch those entries. This plan wires the discovered
library into Prometeu Hub/Home and routes a selected game to firmware
`LoadCartridge`.
## Objective
Make Home display a minimal clickable games list and launch the selected Game
through a system-owned firmware/SystemOS path, without reintroducing userland
`run_cart`.
## Dependencies
- Source decision: `DEC-0036`.
- `PLN-0132` for documented contract.
- `PLN-0133` for `--games-root` plumbing and the internal library entry model.
- Existing Prometeu Hub Home profile and firmware state transitions.
## Scope
- Provide the discovered games library to Prometeu Hub/Home.
- Render a minimal Home list showing `title`, `app_id`, and `app_version`.
- Add Home hit-testing/click handling for game entries.
- Extend the system profile action model with a system-owned game launch action.
- Handle that action in firmware/SystemOS by loading the selected cartridge via
the existing cartridge loader and entering `LoadCartridge`.
- On load failure, log/record the error and keep or return the machine to Home.
- Preserve existing native shell launch behavior.
## Non-Goals
- No polished launcher UI.
- No icons, screenshots, search, filtering, or marketplace metadata.
- No return-to-Home while a Game is running.
- No Game A -> Home -> Game B foreground orchestration.
- No `.pmc` launch support.
- No guest syscall.
- No direct-boot behavior changes.
## Execution Method
1. Extend the SystemOS/Hub action type currently represented by
`SystemProfileAction::LaunchNativeShell` with a game-launch action that
carries a stable reference to the selected library entry or cartridge path.
2. Update the Prometeu Hub state in
[crates/console/prometeu-system/src/programs/prometeu_hub.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-system/src/programs/prometeu_hub.rs)
or its local modules to accept the discovered game entries.
3. Render the Home games list with stable dimensions and simple clickable rows.
Rows must display only `title`, `app_id`, and `app_version` for v1.
4. Add hit-testing so selecting a row emits the game-launch action immediately.
5. Update
[crates/console/prometeu-firmware/src/firmware/steps/firmware_step_hub_home.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-firmware/src/firmware/steps/firmware_step_hub_home.rs)
to consume the new action.
6. In the firmware action handler:
- call the existing cartridge loader for the selected path;
- on success, return `FirmwareState::LoadCartridge(...)`;
- on failure, log/record the error and remain in the Home path.
7. Ensure shell launch still works exactly as before.
8. Add unit or integration tests for:
- Home list presentation data;
- click-to-action emission;
- firmware action handling success;
- firmware action handling failure.
## Acceptance Criteria
- Starting the host with `--games-root <dir>` exposes valid Game entries in
Home.
- The Home list displays `title`, `app_id`, and `app_version`.
- Clicking a listed Game routes through a system action and enters
`LoadCartridge`.
- The launch path does not use a guest syscall and does not mention
`system.run_cart`.
- Invalid or failing launch paths remain in Home and record an error.
- Existing native shell Home actions continue to work.
- Direct `--run` remains separate and unchanged.
## Tests
- Run `cargo test -p prometeu-system` for Hub action and presentation behavior.
- Run `cargo test -p prometeu-firmware` for firmware transition behavior.
- Run `cargo test -p prometeu-host-desktop-winit` if runner integration changes.
- Run `discussion validate`.
## Affected Artifacts
- `crates/console/prometeu-system/src/programs/prometeu_hub.rs`
- `crates/console/prometeu-system/src/services/`
- `crates/console/prometeu-firmware/src/firmware/steps/firmware_step_hub_home.rs`
- `crates/console/prometeu-firmware/src/firmware/firmware.rs`
- `crates/host/prometeu-host-desktop-winit/src/runner.rs`
- `discussion/workflow/plans/PLN-0134-wire-home-game-list-launch-flow.md`

99
discussion/workflow/plans/PLN-0135-validate-games-root-launch-end-to-end.md
View File

@ -1,99 +0,0 @@
---
id: PLN-0135
ticket: system-run-cart
title: Validate Games Root Launch End To End
status: done
created: 2026-07-03
ref_decisions: [DEC-0036]
tags: []
---
## Briefing
`PLN-0132` through `PLN-0134` specify, discover, display, and launch games
from a local games root. This plan closes the slice by adding end-to-end
validation evidence and manual smoke instructions for the product behavior the
user wants: point the SO at a directory, click a listed game, and boot it.
## Objective
Prove the complete `--games-root -> Home list -> click -> LoadCartridge ->
GameRunning` path while preserving direct `--run` boot and the absence of
userland `run_cart`.
## Dependencies
- Source decision: `DEC-0036`.
- `PLN-0132`, `PLN-0133`, and `PLN-0134` must be complete.
- Existing test cartridge fixtures, especially `test-cartridges/stress-console`.
## Scope
- Add automated integration coverage for the full games-root Home launch path
where the existing host/firmware test seams allow it.
- Add or document a minimal local games-root fixture using existing directory
cartridges.
- Validate invalid-candidate omission at the end-to-end boundary.
- Validate direct `--run` still works after games-root wiring.
- Capture manual smoke-test commands for release-mode functional verification.
## Non-Goals
- No new product UI polish.
- No screenshot automation unless the existing test harness already supports it
cleanly.
- No return-to-Home after a running Game.
- No Game A -> Home -> Game B orchestration.
- No `.pmc` validation.
- No broad performance tuning beyond confirming release-mode smoke behavior.
## Execution Method
1. Add an integration-style firmware or host test that constructs a games root
with a valid Game directory cartridge and boots to Hub/Home with that root.
2. Drive the Home selection path through the same action path used by user
input, not by calling the cartridge loader directly.
3. Assert that the machine reaches `LoadCartridge` or `GameRunning`, depending
on the most stable observable state available in the test harness.
4. Add a negative case with an invalid candidate and assert it is omitted or
reported as a diagnostic without appearing in Home.
5. Add a regression assertion that no public guest syscall named
`system.run_cart` is required by this path.
6. Re-run direct boot tests or add a small regression test proving
`--run test-cartridges/stress-console` remains independent from
`--games-root`.
7. Record manual smoke commands in the relevant spec or developer-facing doc:
- `cargo run --release -p prometeu-host-desktop-winit -- --games-root test-cartridges`
- `cargo run --release -p prometeu-host-desktop-winit -- --run test-cartridges/stress-console`
## Acceptance Criteria
- Automated tests cover a valid games-root Home launch path.
- Automated tests cover invalid candidate omission or diagnostics at the
end-to-end boundary.
- Automated or documented validation proves direct `--run` still works.
- Manual smoke instructions use release mode for realistic interactive speed.
- Validation evidence shows no guest syscall participates in launch.
- `discussion validate` passes.
## Tests
- Run `cargo test -p prometeu-system`.
- Run `cargo test -p prometeu-firmware`.
- Run `cargo test -p prometeu-host-desktop-winit`.
- Run `cargo test -p prometeu-hal syscalls` to keep the removed syscall surface
guarded.
- Manually smoke test:
`cargo run --release -p prometeu-host-desktop-winit -- --games-root test-cartridges`.
- Manually smoke test:
`cargo run --release -p prometeu-host-desktop-winit -- --run test-cartridges/stress-console`.
- Run `discussion validate`.
## Affected Artifacts
- `crates/console/prometeu-system/`
- `crates/console/prometeu-firmware/`
- `crates/host/prometeu-host-desktop-winit/`
- `crates/console/prometeu-hal/src/syscalls/tests.rs`
- Runtime specs or developer docs containing smoke commands
- `discussion/workflow/plans/PLN-0135-validate-games-root-launch-end-to-end.md`

96
discussion/workflow/plans/PLN-0136-route-desktop-home-key-outside-guest-input.md Normal file
View File

@ -0,0 +1,96 @@
---
id: PLN-0136
ticket: foreground-stack-game-pause-shell-vm-backed
title: Route Desktop Home Key Outside Guest Input
status: open
created: 2026-07-03
ref_decisions: [DEC-0037]
tags: [host, input, systemos, keyboard, lifecycle]
---
## Briefing
`DEC-0037` makes desktop `Esc` the primary Home/SystemOS request and allows the
physical `Home` key as an alias. This request must be intercepted by the
host/SystemOS and must not appear as a guest pad button or input intrinsic.
This plan adds the host input route for the Home request without changing the
guest-visible pad surface.
## Decisions of Origin
- `DEC-0037` - Foreground Stack and Game Pause Contract.
## Target
Route desktop `Esc` and optional physical `Home` key to a SystemOS Home request
outside `InputSignals`.
## Scope
- Extend `crates/host/prometeu-host-desktop-winit/src/input.rs` or a nearby
host input module with a host/system control signal separate from
`prometeu_hal::InputSignals`.
- Map `KeyCode::Escape` to Home/SystemOS request.
- Map `KeyCode::Home` as an alias.
- Ensure neither key mutates `start_signal`, `select_signal`, or any pad field.
- Route the request through `crates/host/prometeu-host-desktop-winit/src/runner.rs`
into firmware/SystemOS.
- Add tests proving `Esc` and `Home` do not affect guest pad state.
## Out of Scope
- No pause/resume lifecycle implementation.
- No render ownership gating.
- No guest-visible Home button.
- No gamepad hardware Home mapping unless a future plan defines controller
system controls separately.
## Execution Plan
1. Define host control state.
Add a small host-only type such as `HostSystemControls` with a
`home_requested` edge or event. Store it in `HostInputHandler` or in the
runner next to the existing input handler.
2. Update keyboard handling.
In `HostInputHandler::handle_event`, recognize `KeyCode::Escape` and
`KeyCode::Home` on press. Set the host control event and return without
modifying `InputSignals`.
3. Preserve pad mapping.
Keep existing pad mappings unchanged:
arrows, `A/D/W/S`, `Q/E`, `Z`, and Shift. Do not reuse `Start` or `Select`
for Home.
4. Route to firmware/SystemOS.
In `crates/host/prometeu-host-desktop-winit/src/runner.rs`, consume the
host Home event before or during `about_to_wait` and call the firmware or
SystemOS method introduced by `PLN-0137` / `PLN-0140`.
5. Add tests.
Add host input tests for `Esc`, physical `Home`, and existing pad mappings.
Tests must prove Home produces a system event and no guest pad mutation.
## Acceptance Criteria
- Pressing desktop `Esc` emits a Home/SystemOS host control event.
- Pressing physical `Home` emits the same event.
- Neither key affects `InputSignals`.
- Existing guest pad keyboard mappings still work.
- The runner consumes the Home request as a system action.
- The implementation does not add a guest syscall, intrinsic, or pad button.
## Tests / Validation
- Add unit tests in `prometeu-host-desktop-winit` for host input mapping.
- Run `cargo test -p prometeu-host-desktop-winit input`.
- Run `cargo test -p prometeu-hal input` if pad signal behavior changes.
- Run `discussion validate`.
## Risks
- `Esc` may conflict with debugger or window-close expectations. Keep debugger
start handling on `D` unchanged and do not map `Esc` to process exit.
- Physical `Home` is not available on every keyboard, so it must remain an
alias rather than the primary portable mapping.

116
discussion/workflow/plans/PLN-0137-implement-systemos-foreground-stack-state.md Normal file
View File

@ -0,0 +1,116 @@
---
id: PLN-0137
ticket: foreground-stack-game-pause-shell-vm-backed
title: Implement SystemOS Foreground Stack State
status: open
created: 2026-07-03
ref_decisions: [DEC-0037]
tags: [runtime, os, lifecycle, foreground, shell, game]
---
## Briefing
`DEC-0037` requires SystemOS to own foreground authority. The system must know
which owner is foreground, keep Hub/Home as root, allow only one resident Game,
allow only one foreground Shell, and return from VM-backed Shell apps to Hub in
v1.
This plan implements the SystemOS state model only. It does not yet deliver
Game pause/resume events, host keyboard routing, or render/audio/input boundary
changes.
## Decisions of Origin
- `DEC-0037` - Foreground Stack and Game Pause Contract.
## Target
Add an explicit SystemOS foreground stack model that can represent Hub, a
foreground Shell task, and a paused/suspended resident Game.
## Scope
- Add or extend SystemOS-owned foreground state under
`crates/console/prometeu-system/src/os/` or
`crates/console/prometeu-system/src/services/`.
- Represent v1 foreground owners:
- Hub/Home root;
- Shell task foreground;
- Game foreground;
- Game paused/suspended resident.
- Enforce at most one resident Game and at most one foreground Shell.
- Keep Hub as root/back-stack controller.
- Ensure Shell close returns to Hub/Home in v1.
- Expose focused queries through existing or new facades, likely
`crates/console/prometeu-system/src/os/facades/lifecycle.rs` and
`crates/console/prometeu-system/src/os/facades/sessions.rs`.
## Out of Scope
- No VM pause/resume event delivery.
- No host `Esc`/`Home` keyboard mapping.
- No render epoch implementation.
- No Game-to-Game switching.
- No background execution.
- No memory eviction for the resident Game.
## Execution Plan
1. Define foreground model types.
Add enums/structs for foreground owner and resident Game state in the most
local SystemOS module. The model must distinguish Game foreground, Game
paused/suspended, Hub foreground, and Shell task foreground.
2. Add SystemOS storage.
Store the foreground model in `SystemOS` from
`crates/console/prometeu-system/src/os/system_os.rs` with initialization to
Hub/Home root.
3. Wire lifecycle facade operations.
Extend lifecycle/session facades so firmware can request:
- set Game foreground;
- request Home from Game;
- set Shell foreground from Hub;
- close Shell and return to Hub;
- query current foreground owner;
- query resident Game task.
4. Enforce cardinality.
Add checks that reject a second resident Game and a second foreground Shell
with typed lifecycle errors. Use existing `LifecycleError` style or add
precise variants.
5. Integrate existing Shell close behavior.
Update `crates/console/prometeu-firmware/src/firmware/firmware_step_shell_running.rs`
only where needed so closing a Shell task routes through the foreground model
and ends in `FirmwareState::HubHome`.
6. Add tests.
Cover initial Hub foreground, Game foreground registration, Home request
moving Game to resident paused/suspended state, Shell foreground activation,
Shell close returning to Hub, and cardinality rejection.
## Acceptance Criteria
- SystemOS has an explicit foreground owner model.
- Hub/Home is the initialized root foreground owner.
- Only one resident Game can exist in v1.
- Only one Shell task can be foreground in v1.
- VM-backed Shell close returns to Hub/Home.
- Foreground queries are available to firmware and later plans.
- No implementation path enables background execution.
## Tests / Validation
- Add focused unit tests in `prometeu-system` around the new model and facade.
- Run `cargo test -p prometeu-system lifecycle foreground`.
- Run `cargo test -p prometeu-firmware shell`.
- Run `discussion validate`.
## Risks
- Existing `TaskState::Foreground` and `TaskState::Suspended` may look like the
complete model. Do not overload them until foreground ownership and Hub root
authority are explicit.
- Shell windows already have focus semantics. Keep window focus as visual/task
evidence, not the sole source of SystemOS foreground truth.

114
discussion/workflow/plans/PLN-0138-specify-foreground-pause-and-home-contract.md Normal file
View File

@ -0,0 +1,114 @@
---
id: PLN-0138
ticket: foreground-stack-game-pause-shell-vm-backed
title: Specify Foreground Pause and Home Contract
status: open
created: 2026-07-03
ref_decisions: [DEC-0037]
tags: [runtime, specs, lifecycle, input, renderer, foreground]
---
## Briefing
`DEC-0037` establishes the v1 foreground stack contract: one foreground visual
owner, one resident Game, one foreground Shell, Hub as root, Game-visible
pause/resume, OS-owned suspension, desktop `Esc` as Home/SystemOS request, and
render epoch invalidation across foreground transitions.
This plan updates the canonical runtime specs before implementation so code
plans cannot drift into guest-owned Home input, background execution, or stale
frame presentation.
## Decisions of Origin
- `DEC-0037` - Foreground Stack and Game Pause Contract.
## Target
Document the foreground, pause/suspend, Home request, input, audio, and render
ownership contract in the canonical runtime specs.
## Scope
- Update `docs/specs/runtime/12-firmware-pos-and-prometeuhub.md` with:
- Hub as root/special Shell owner;
- one foreground visual owner;
- one resident Game;
- one foreground Shell;
- `Game -> Home/Shell -> same Game` lifecycle;
- VM-backed Shell app return-to-Hub behavior.
- Update `docs/specs/runtime/06-input-peripheral.md` with:
- Home/SystemOS as host/system control, not pad input;
- desktop `Esc` as primary Home request;
- physical `Home` key as optional alias;
- input clear/barrier requirements across Game pause/resume.
- Update `docs/specs/runtime/09-events-and-concurrency.md` with:
- pause notification budget;
- OS-owned suspension after the budget;
- resume/foreground-restore notification before visual return.
- Update `docs/specs/runtime/14-boot-profiles.md` only to clarify that this
foreground contract is not Game-to-Game switching and does not change direct
`--run` or `--games-root` boot semantics.
- Update renderer-related spec text in the most local existing runtime spec if
present, otherwise add a short subsection to `12-firmware-pos-and-prometeuhub.md`
describing ownership epoch invalidation and first-valid-frame gating.
## Out of Scope
- No Rust implementation.
- No new guest ABI or pad button.
- No background execution policy.
- No Game A -> Home -> Game B switching.
- No memory eviction policy for resident Games.
## Execution Plan
1. Edit `12-firmware-pos-and-prometeuhub.md`.
Define foreground owner cardinality, Hub root ownership, Shell foreground
behavior, Game resident/suspended behavior, return-to-Hub from Shell, and the
requirement to keep Hub/Shell visible until a resumed Game submits a valid
current-epoch frame.
2. Edit `06-input-peripheral.md`.
State that Home/SystemOS is outside the guest-visible pad and input
intrinsic surface. Document desktop `Esc` as the primary host mapping and
physical `Home` as an optional alias.
3. Edit `09-events-and-concurrency.md`.
Add the pause/resume event ordering: Home request, pause notification,
bounded reaction budget, OS suspension, resume/foreground-restore
notification, first-valid-frame visual return.
4. Edit `14-boot-profiles.md`.
Cross-reference the foreground contract and explicitly keep direct boot,
games-root Home launch, and future Game-to-Game switching separate.
5. Run text checks.
Search for wording that implies Home is a guest input button, a guest ABI, or
background execution. Replace misleading text with the `DEC-0037` contract.
## Acceptance Criteria
- Specs define `Paused` as Game-visible and `Suspended` as OS-owned.
- Specs state that desktop `Esc` is the primary Home request and is not guest
pad input.
- Specs state that the Game receives pause/resume notifications but does not
control OS suspension.
- Specs state that Hub is the root Shell owner and Shell app close returns to
Hub in v1.
- Specs state that visual return to Game waits for a valid current-epoch render
submission.
- Specs explicitly exclude background execution and Game-to-Game switching.
## Tests / Validation
- Run `discussion validate`.
- Run `rg -n "Home|Esc|Suspended|Paused|foreground|background execution" docs/specs/runtime`.
- Verify no edited spec describes Home/SystemOS as a guest-visible pad button.
## Risks
- The spec could accidentally reopen Game-to-Game switching; keep that scoped to
`DSC-0043 / AGD-0044`.
- The input spec could confuse physical keyboard mapping with VM input; keep
host/system controls outside the guest input surface.

106
discussion/workflow/plans/PLN-0139-validate-game-home-shell-game-end-to-end.md Normal file
View File

@ -0,0 +1,106 @@
---
id: PLN-0139
ticket: foreground-stack-game-pause-shell-vm-backed
title: Validate Game Home Shell Game End To End
status: open
created: 2026-07-03
ref_decisions: [DEC-0037]
tags: [runtime, validation, firmware, host, lifecycle]
---
## Briefing
`DEC-0037` is not complete until the product flow is proven end to end:
a Game runs, the user requests Home, the Game is paused/suspended, Hub or a
VM-backed Shell takes foreground, closing Shell returns to Hub, and the same
Game can resume only after a valid current-epoch frame exists.
This plan adds final validation after the spec, SystemOS, VM, host input, and
render/audio/input boundary plans are implemented.
## Decisions of Origin
- `DEC-0037` - Foreground Stack and Game Pause Contract.
## Target
Prove the complete `Game -> Home/Shell -> same Game` lifecycle and prevent
regressions around guest input, foreground authority, and stale rendering.
## Scope
- Add integration-style tests for:
- Game running to Home request;
- pause notification and forced suspension;
- Hub foreground while Game is resident;
- VM-backed Shell foreground while Game is suspended;
- Shell close returning to Hub;
- resume request returning to same Game;
- first-valid-frame visual restore;
- host `Esc`/`Home` not entering guest input.
- Add manual smoke instructions for desktop host.
- Confirm direct `--run` and games-root Home launch remain separate.
## Out of Scope
- No new implementation beyond tests and developer-facing validation notes.
- No Game A -> Home -> Game B switching.
- No performance tuning.
- No polished UI.
## Execution Plan
1. Add firmware/SystemOS integration tests.
Use the most stable existing seams in `crates/console/prometeu-firmware/src/firmware/firmware.rs`
and `crates/console/prometeu-system` tests to drive Game foreground, Home
request, Shell foreground, Shell close, and Game resume.
2. Add host input integration tests.
Ensure `Esc` and physical `Home` create a host Home event and do not mutate
guest `InputSignals`.
3. Add render publication validation.
Assert stale submissions from the pre-pause Game epoch are rejected after
Home takes foreground and that the Game is not visually restored until a new
current-epoch submission exists.
4. Add audio/input boundary validation.
Assert Game input is cleared or barriered across pause/resume. Assert Game
audio pause follows Game suspension.
5. Add direct boot and games-root regression checks.
Ensure direct `--run <cart>` remains independent from Home request handling
and that games-root Home launch still enters the Game path.
6. Document manual smoke commands.
Add or update developer-facing spec text with release-mode commands:
- `cargo run --release -p prometeu-host-desktop-winit -- --run test-cartridges/stress-console`
- `cargo run --release -p prometeu-host-desktop-winit -- --games-root test-cartridges`
Include the expected `Esc -> Home -> Shell -> Hub -> resume Game` behavior
once implemented.
## Acceptance Criteria
- Automated tests cover `Game -> Home -> same Game`.
- Automated tests cover `Game -> Home -> Shell -> Hub -> same Game`.
- Tests prove Home request is host/SystemOS control, not guest pad input.
- Tests prove suspended Game does not tick.
- Tests prove stale render submissions are not presented.
- Tests prove visual return waits for a current-epoch Game frame.
- Direct `--run` and games-root Home launch regressions pass.
## Tests / Validation
- Run `cargo test -p prometeu-system`.
- Run `cargo test -p prometeu-firmware`.
- Run `cargo test -p prometeu-host-desktop-winit`.
- Run any targeted render worker tests affected by ownership epoch changes.
- Run `discussion validate`.
## Risks
- The current test seams may not expose enough host-driven lifecycle behavior.
If needed, add narrow test-only helpers rather than testing through sleeps or
real-time window loops.
- End-to-end validation can become flaky if it depends on wall-clock timing.
Use deterministic ticks and explicit state transitions.

110
discussion/workflow/plans/PLN-0140-deliver-game-pause-resume-and-suspension.md Normal file
View File

@ -0,0 +1,110 @@
---
id: PLN-0140
ticket: foreground-stack-game-pause-shell-vm-backed
title: Deliver Game Pause Resume and Suspension
status: open
created: 2026-07-03
ref_decisions: [DEC-0037]
tags: [runtime, os, vm, lifecycle, pause, suspension]
---
## Briefing
`DEC-0037` separates Game-visible `Paused` from OS-owned `Suspended`. When Home
is requested during Game execution, SystemOS must notify the Game, give it a
short bounded budget, then suspend the VM even if the Game does not cooperate.
When returning, SystemOS must reactivate the VM and send a resume or
foreground-restore notification before the visual owner returns to Game.
This plan implements the pause/resume and suspension mechanics after the
foreground state model exists.
## Decisions of Origin
- `DEC-0037` - Foreground Stack and Game Pause Contract.
## Target
Add Game pause/resume lifecycle delivery and OS-enforced VM suspension for the
same resident Game.
## Scope
- Add a Game lifecycle event model for pause and resume/foreground-restore.
- Add a bounded pause reaction budget owned by SystemOS.
- Suspend the Game VM after the budget even if the Game does not cooperate.
- Ensure a suspended Game receives no normal gameplay ticks.
- Reactivate the VM and deliver resume/foreground-restore before Game visual
foreground restoration.
- Integrate with `GameRunningStep` and VM runtime tick control.
## Out of Scope
- No render first-valid-frame gating; that is in `PLN-0141`.
- No host keyboard routing; that is in `PLN-0136`.
- No new guest syscall.
- No background execution.
- No Game-to-Game switching.
## Execution Plan
1. Add lifecycle event representation.
Define pause/resume events in the most local runtime lifecycle module,
likely under `crates/console/prometeu-system/src/os/lifecycle.rs` or a new
SystemOS lifecycle submodule. Events must be observable by the VM/runtime
path without giving the Game authority over suspension.
2. Add pause transition state.
Extend the foreground state from `PLN-0137` with a `PauseRequested` or
equivalent transition state that records the target Game task and the
remaining pause budget.
3. Gate VM ticks.
Update `crates/console/prometeu-firmware/src/firmware/firmware_step_game_running.rs`
and `crates/console/prometeu-system/src/services/vm_runtime/tick.rs` so a
suspended Game does not receive normal ticks, normal input, or frame pacing.
4. Deliver pause notification.
Add the mechanism that makes the pause event visible to the running Game
before suspension. Use an existing VM event channel if present; otherwise add
a narrow lifecycle-event queue owned by SystemOS/VM runtime.
5. Enforce the budget.
Advance the pause budget on firmware ticks. When it expires, transition the
Game task/process to suspended through SystemOS lifecycle regardless of Game
cooperation.
6. Deliver resume notification.
On return to the resident Game, transition from suspended to resume-requested,
reactivate VM execution, deliver resume/foreground-restore, and leave visual
restoration to the render boundary plan.
7. Add tests.
Cover cooperative pause, non-cooperative forced suspension, no tick while
suspended, resume notification delivery, and no Game-owned ability to cancel
OS suspension.
## Acceptance Criteria
- Game receives pause before suspension.
- SystemOS suspends after a bounded budget even if the Game does not cooperate.
- Suspended Game does not receive normal gameplay ticks.
- Resume/foreground-restore is delivered before visual return to Game.
- Game cannot prevent OS suspension through guest-visible behavior.
- Existing debugger pause behavior remains distinct from lifecycle suspension.
## Tests / Validation
- Add unit tests in `prometeu-system` for lifecycle transition state.
- Add firmware tests around `GameRunningStep` pause request and suspension.
- Add VM runtime tests proving suspended state suppresses normal ticks.
- Run `cargo test -p prometeu-system`.
- Run `cargo test -p prometeu-firmware`.
- Run `discussion validate`.
## Risks
- Debugger pause already exists in VM runtime. Keep debug pause separate from
lifecycle pause/suspend.
- A lifecycle event queue could become a general app event system. Keep this
plan limited to pause/resume required by `DEC-0037`.

104
discussion/workflow/plans/PLN-0141-integrate-render-audio-and-input-pause-boundaries.md Normal file
View File

@ -0,0 +1,104 @@
---
id: PLN-0141
ticket: foreground-stack-game-pause-shell-vm-backed
title: Integrate Render Audio and Input Pause Boundaries
status: open
created: 2026-07-03
ref_decisions: [DEC-0037]
tags: [runtime, renderer, audio, input, foreground, lifecycle]
---
## Briefing
`DEC-0037` requires foreground transitions to invalidate stale render
submissions, keep Hub/Shell visible until the resumed Game publishes a valid
current-epoch frame, clear or barrier Game input across pause/resume, and pause
Game audio with the Game VM in v1.
This plan integrates those boundary effects after SystemOS foreground state and
Game pause/resume mechanics exist.
## Decisions of Origin
- `DEC-0037` - Foreground Stack and Game Pause Contract.
## Target
Make foreground transitions safe at the render, input, and audio boundaries.
## Scope
- Advance render ownership epoch/generation whenever foreground owner changes.
- Discard stale Game frames after Shell/Hub takes foreground.
- Discard stale Shell frames after Game resumes.
- Keep Hub/Shell visible until a resumed Game publishes a valid current-epoch
submission.
- Clear or barrier Game input across pause/resume boundaries.
- Pause Game audio with the Game VM in v1.
- Add telemetry/tests for stale discards and first-valid-frame gating.
## Out of Scope
- No independent background audio policy.
- No overlay rendering policy.
- No Game-to-Game switch rendering.
- No full memory eviction behavior.
## Execution Plan
1. Extend render ownership transition calls.
Update `crates/console/prometeu-system/src/services/vm_runtime/render_manager.rs`
and call sites in `tick.rs` so foreground owner changes explicitly advance
ownership epoch/generation, not only app mode/app id changes.
2. Add foreground restore gating.
Add state in SystemOS or firmware that records when visual return to Game is
pending. The state must remain in Hub/Shell presentation until a
current-epoch Game submission is observed.
3. Update host presentation selection.
Update `crates/host/prometeu-host-desktop-winit/src/runner.rs` if necessary
so `should_present_worker_frame` and fallback framebuffer presentation obey
the foreground restore gate.
4. Add stale discard coverage.
Extend render manager and render worker tests to prove stale submissions
from the previous owner are discarded after epoch change.
5. Add input boundary clearing.
Add a SystemOS or firmware input barrier when Game pause starts and when
Game resume starts. The barrier must prevent held or pressed Game input from
leaking across the lifecycle boundary.
6. Add audio pause integration.
Ensure Game pause/suspend produces the existing host audio pause command path
or a new explicit lifecycle audio pause signal. Keep this separate from
debugger pause if the observable cause matters in tests.
7. Add tests.
Cover stale frame discard, first-valid-frame visual return, input clearing,
and Game audio pause/resume behavior.
## Acceptance Criteria
- Foreground owner changes advance render ownership epoch/generation.
- Old Game frames cannot present after Hub/Shell takes foreground.
- Old Hub/Shell frames cannot present after Game resumes.
- Visual return to Game waits for a valid current-epoch Game submission.
- Game input does not leak across pause/resume boundaries.
- Game audio pauses with Game suspension in v1.
## Tests / Validation
- Run `cargo test -p prometeu-system render foreground`.
- Run `cargo test -p prometeu-firmware pause`.
- Run `cargo test -p prometeu-host-desktop-winit presentation`.
- Run `discussion validate`.
## Risks
- Existing render epoch logic may already key off app mode/app id. Foreground
owner changes must be explicit so Shell/Hub and resumed Game cannot share a
stale epoch by accident.
- Audio pause currently follows VM paused/debugger state in the host. Keep Game
lifecycle pause distinct enough that tests can prove the decision contract.