diff --git a/discussion/index.ndjson b/discussion/index.ndjson index 48b236ba..1779eddc 100644 --- a/discussion/index.ndjson +++ b/discussion/index.ndjson @@ -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":[]} diff --git a/discussion/lessons/DSC-0004-system-run-cart/LSN-0051-launch-authority-belongs-to-systemos.md b/discussion/lessons/DSC-0004-system-run-cart/LSN-0051-launch-authority-belongs-to-systemos.md new file mode 100644 index 00000000..d88d2d7f --- /dev/null +++ b/discussion/lessons/DSC-0004-system-run-cart/LSN-0051-launch-authority-belongs-to-systemos.md @@ -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 `, 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 ` 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. diff --git a/discussion/workflow/agendas/AGD-0003-system-run-cart.md b/discussion/workflow/agendas/AGD-0003-system-run-cart.md deleted file mode 100644 index b0e1b2ad..00000000 --- a/discussion/workflow/agendas/AGD-0003-system-run-cart.md +++ /dev/null @@ -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. diff --git a/discussion/workflow/agendas/AGD-0041-foreground-stack-game-pause-shell-vm-backed.md b/discussion/workflow/agendas/AGD-0041-foreground-stack-game-pause-shell-vm-backed.md index 973f74e2..65520de4 100644 --- a/discussion/workflow/agendas/AGD-0041-foreground-stack-game-pause-shell-vm-backed.md +++ b/discussion/workflow/agendas/AGD-0041-foreground-stack-game-pause-shell-vm-backed.md @@ -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. diff --git a/discussion/workflow/agendas/AGD-0045-systemos-library-root-home-game-launch.md b/discussion/workflow/agendas/AGD-0045-systemos-library-root-home-game-launch.md deleted file mode 100644 index 3f1980f7..00000000 --- a/discussion/workflow/agendas/AGD-0045-systemos-library-root-home-game-launch.md +++ /dev/null @@ -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 ` 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 `. -- 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 `; -- 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 ` 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. diff --git a/discussion/workflow/decisions/DEC-0035-remove-userland-system-run-cart-and-preserve-direct-boot.md b/discussion/workflow/decisions/DEC-0035-remove-userland-system-run-cart-and-preserve-direct-boot.md deleted file mode 100644 index 5e212b26..00000000 --- a/discussion/workflow/decisions/DEC-0035-remove-userland-system-run-cart-and-preserve-direct-boot.md +++ /dev/null @@ -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`. diff --git a/discussion/workflow/decisions/DEC-0036-systemos-games-root-and-home-game-launch.md b/discussion/workflow/decisions/DEC-0036-systemos-games-root-and-home-game-launch.md deleted file mode 100644 index ed7eda2c..00000000 --- a/discussion/workflow/decisions/DEC-0036-systemos-games-root-and-home-game-launch.md +++ /dev/null @@ -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 `. - -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 ` 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 ` 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 ` 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 ` 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`. diff --git a/discussion/workflow/decisions/DEC-0037-foreground-stack-and-game-pause-contract.md b/discussion/workflow/decisions/DEC-0037-foreground-stack-and-game-pause-contract.md new file mode 100644 index 00000000..5e2d8765 --- /dev/null +++ b/discussion/workflow/decisions/DEC-0037-foreground-stack-and-game-pause-contract.md @@ -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`. diff --git a/discussion/workflow/plans/PLN-0129-remove-userland-run-cart-abi-surface.md b/discussion/workflow/plans/PLN-0129-remove-userland-run-cart-abi-surface.md deleted file mode 100644 index 52c071ae..00000000 --- a/discussion/workflow/plans/PLN-0129-remove-userland-run-cart-abi-surface.md +++ /dev/null @@ -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` diff --git a/discussion/workflow/plans/PLN-0130-remove-runtime-run-cart-stub-dispatch.md b/discussion/workflow/plans/PLN-0130-remove-runtime-run-cart-stub-dispatch.md deleted file mode 100644 index 71be6a70..00000000 --- a/discussion/workflow/plans/PLN-0130-remove-runtime-run-cart-stub-dispatch.md +++ /dev/null @@ -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` diff --git a/discussion/workflow/plans/PLN-0131-preserve-direct-cartridge-boot-coverage.md b/discussion/workflow/plans/PLN-0131-preserve-direct-cartridge-boot-coverage.md deleted file mode 100644 index 75660a8c..00000000 --- a/discussion/workflow/plans/PLN-0131-preserve-direct-cartridge-boot-coverage.md +++ /dev/null @@ -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/` diff --git a/discussion/workflow/plans/PLN-0132-specify-games-root-home-launch-contract.md b/discussion/workflow/plans/PLN-0132-specify-games-root-home-launch-contract.md deleted file mode 100644 index 7bd714c1..00000000 --- a/discussion/workflow/plans/PLN-0132-specify-games-root-home-launch-contract.md +++ /dev/null @@ -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 `, 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 ` 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 ` 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 ` 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 ` 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 ` 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` diff --git a/discussion/workflow/plans/PLN-0133-implement-games-root-library-discovery.md b/discussion/workflow/plans/PLN-0133-implement-games-root-library-discovery.md deleted file mode 100644 index 65bc21f2..00000000 --- a/discussion/workflow/plans/PLN-0133-implement-games-root-library-discovery.md +++ /dev/null @@ -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 ` 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 ` 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 ` is accepted by the desktop host CLI. -- Absence of `--games-root` leaves existing Hub boot behavior unchanged. -- Direct `--run ` and `--debug ` 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` diff --git a/discussion/workflow/plans/PLN-0134-wire-home-game-list-launch-flow.md b/discussion/workflow/plans/PLN-0134-wire-home-game-list-launch-flow.md deleted file mode 100644 index 001a2bf0..00000000 --- a/discussion/workflow/plans/PLN-0134-wire-home-game-list-launch-flow.md +++ /dev/null @@ -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 ` 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` diff --git a/discussion/workflow/plans/PLN-0135-validate-games-root-launch-end-to-end.md b/discussion/workflow/plans/PLN-0135-validate-games-root-launch-end-to-end.md deleted file mode 100644 index 95721ff1..00000000 --- a/discussion/workflow/plans/PLN-0135-validate-games-root-launch-end-to-end.md +++ /dev/null @@ -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` diff --git a/discussion/workflow/plans/PLN-0136-route-desktop-home-key-outside-guest-input.md b/discussion/workflow/plans/PLN-0136-route-desktop-home-key-outside-guest-input.md new file mode 100644 index 00000000..7117ec6e --- /dev/null +++ b/discussion/workflow/plans/PLN-0136-route-desktop-home-key-outside-guest-input.md @@ -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. diff --git a/discussion/workflow/plans/PLN-0137-implement-systemos-foreground-stack-state.md b/discussion/workflow/plans/PLN-0137-implement-systemos-foreground-stack-state.md new file mode 100644 index 00000000..e3d29add --- /dev/null +++ b/discussion/workflow/plans/PLN-0137-implement-systemos-foreground-stack-state.md @@ -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. diff --git a/discussion/workflow/plans/PLN-0138-specify-foreground-pause-and-home-contract.md b/discussion/workflow/plans/PLN-0138-specify-foreground-pause-and-home-contract.md new file mode 100644 index 00000000..78ad1dea --- /dev/null +++ b/discussion/workflow/plans/PLN-0138-specify-foreground-pause-and-home-contract.md @@ -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. diff --git a/discussion/workflow/plans/PLN-0139-validate-game-home-shell-game-end-to-end.md b/discussion/workflow/plans/PLN-0139-validate-game-home-shell-game-end-to-end.md new file mode 100644 index 00000000..b8f7086e --- /dev/null +++ b/discussion/workflow/plans/PLN-0139-validate-game-home-shell-game-end-to-end.md @@ -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 ` 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. diff --git a/discussion/workflow/plans/PLN-0140-deliver-game-pause-resume-and-suspension.md b/discussion/workflow/plans/PLN-0140-deliver-game-pause-resume-and-suspension.md new file mode 100644 index 00000000..32cf8eba --- /dev/null +++ b/discussion/workflow/plans/PLN-0140-deliver-game-pause-resume-and-suspension.md @@ -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`. diff --git a/discussion/workflow/plans/PLN-0141-integrate-render-audio-and-input-pause-boundaries.md b/discussion/workflow/plans/PLN-0141-integrate-render-audio-and-input-pause-boundaries.md new file mode 100644 index 00000000..710caeb2 --- /dev/null +++ b/discussion/workflow/plans/PLN-0141-integrate-render-audio-and-input-pause-boundaries.md @@ -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.