Foreground Stack, Game Pause, and VM-Backed Shell Coexistence
This commit is contained in:
parent
4bc9ce2b73
commit
126bffa37d
SSH Key Fingerprint:
SHA256:Z7dgqoglWwoK6j6u4QC87OveEq74WOhFN+gitsxtkf8
@ -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-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-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-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-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-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"}]}
|
{"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-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-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-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-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-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":[]}
|
{"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":[]}
|
||||||
|
|||||||
@ -0,0 +1,118 @@
|
|||||||
|
---
|
||||||
|
id: LSN-0051
|
||||||
|
ticket: system-run-cart
|
||||||
|
title: Launch Authority Belongs to SystemOS
|
||||||
|
created: 2026-07-03
|
||||||
|
tags: [runtime, systemos, cartridge, launch, abi, home]
|
||||||
|
---
|
||||||
|
|
||||||
|
## Context
|
||||||
|
|
||||||
|
The `system.run_cart` workflow resolved two related questions: whether a guest
|
||||||
|
should have an app-callable cartridge launch syscall, and how Home should start
|
||||||
|
games from a local library.
|
||||||
|
|
||||||
|
The final model removes `system.run_cart` from the userland ABI while preserving
|
||||||
|
direct host-controlled cartridge boot. Home launch is restored as a
|
||||||
|
system-owned path: the host may provide `--games-root <dir>`, SystemOS/Home
|
||||||
|
discovers valid Game directory cartridges, and selecting an entry routes through
|
||||||
|
firmware into `LoadCartridge`.
|
||||||
|
|
||||||
|
The important distinction is authority. A launch can be a valid product action
|
||||||
|
without being a guest capability.
|
||||||
|
|
||||||
|
## Key Decisions
|
||||||
|
|
||||||
|
### Remove Guest Cartridge Launch
|
||||||
|
|
||||||
|
**What:** Prometeu removed `system.run_cart` from the public userland syscall
|
||||||
|
surface, generated guest metadata, and runtime dispatch.
|
||||||
|
|
||||||
|
**Why:** A guest syscall made cartridge launch look like app-owned navigation.
|
||||||
|
That gave userland implied authority over target resolution, lifecycle cleanup,
|
||||||
|
failure policy, and system navigation.
|
||||||
|
|
||||||
|
**Trade-offs:** Obsolete guest code cannot keep a compatibility stub. The
|
||||||
|
runtime instead keeps direct boot as a host/system entrypoint and lets stale
|
||||||
|
guest attempts fail through the invalid syscall path.
|
||||||
|
|
||||||
|
### Preserve Direct Boot Outside The Guest ABI
|
||||||
|
|
||||||
|
**What:** Host, CLI, debugger, tests, and single-game flows continue to boot a
|
||||||
|
selected cartridge directly.
|
||||||
|
|
||||||
|
**Why:** Direct boot is still essential for development, automation, and future
|
||||||
|
single-game distribution. Those flows start with a host-selected target before
|
||||||
|
VM execution, so they do not need a guest syscall.
|
||||||
|
|
||||||
|
**Trade-offs:** The loader remains reusable, but it is not lifecycle
|
||||||
|
orchestration authority. Higher-level transitions must be owned by firmware or
|
||||||
|
SystemOS.
|
||||||
|
|
||||||
|
### Model Home Launch As A System Action
|
||||||
|
|
||||||
|
**What:** `--games-root <dir>` configures a local games library for Home. V1
|
||||||
|
discovery scans immediate child directories, keeps only valid Game cartridges,
|
||||||
|
and exposes enough internal metadata to launch a selected entry.
|
||||||
|
|
||||||
|
**Why:** Home needs a product path for "choose a game and start it", but that
|
||||||
|
action belongs to the system profile. SystemOS can present the library and ask
|
||||||
|
firmware to enter `LoadCartridge` without reintroducing guest-controlled launch.
|
||||||
|
|
||||||
|
**Trade-offs:** V1 intentionally excludes recursive discovery, `.pmc`, non-game
|
||||||
|
apps, rich catalog metadata, return-to-Home, and game-to-game switching. Those
|
||||||
|
need separate lifecycle and orchestration decisions.
|
||||||
|
|
||||||
|
## Patterns and Algorithms
|
||||||
|
|
||||||
|
### Authority-Based API Classification
|
||||||
|
|
||||||
|
Before exposing an operation to guest/userland code, classify what authority it
|
||||||
|
implies. If the operation selects another executable target, changes process
|
||||||
|
lifecycle, or controls navigation between system-owned modes, it is probably a
|
||||||
|
SystemOS or firmware action rather than an app syscall.
|
||||||
|
|
||||||
|
### Separate Selection From Loading
|
||||||
|
|
||||||
|
Home owns user selection and presentation. SystemOS owns the launch request.
|
||||||
|
Firmware owns the transition into `LoadCartridge`. The cartridge loader remains
|
||||||
|
the mechanism that validates and materializes a cartridge, not the authority
|
||||||
|
that decides when navigation is allowed.
|
||||||
|
|
||||||
|
### Expandable Internal Catalog Records
|
||||||
|
|
||||||
|
Home can render a small v1 list while the internal entry retains manifest data,
|
||||||
|
title, app id, app version, cartridge path, and discovery metadata. This keeps
|
||||||
|
the UI simple without reducing the model to a display-only DTO.
|
||||||
|
|
||||||
|
## Pitfalls
|
||||||
|
|
||||||
|
### Compatibility Stubs Preserve False Contracts
|
||||||
|
|
||||||
|
A syscall that returns success without doing real lifecycle work is worse than
|
||||||
|
an absent syscall. It teaches callers that the platform supports app-driven
|
||||||
|
launch while hiding that no complete transition happened.
|
||||||
|
|
||||||
|
### A Product Flow Is Not Automatically A Guest API
|
||||||
|
|
||||||
|
"Home can launch a game" and "a guest can launch a cartridge" are different
|
||||||
|
claims. Product behavior should be mapped to the component with the correct
|
||||||
|
authority instead of mirrored into the nearest callable ABI.
|
||||||
|
|
||||||
|
### Generic Library Roots Prematurely Expand Scope
|
||||||
|
|
||||||
|
The first launcher path is a games library, not a marketplace or full app
|
||||||
|
catalog. Shell apps, System apps, packages, icons, search, and recursive layouts
|
||||||
|
carry separate contracts and should not be smuggled into the v1 games-root path.
|
||||||
|
|
||||||
|
## Takeaways
|
||||||
|
|
||||||
|
- Cartridge launch is system navigation, not a userland syscall.
|
||||||
|
- Direct boot can remain host-controlled without appearing in guest metadata.
|
||||||
|
- Home launch should emit a system action and let firmware enter
|
||||||
|
`LoadCartridge`.
|
||||||
|
- Loader reuse does not imply loader ownership of lifecycle policy.
|
||||||
|
- Keep v1 discovery narrow: immediate child directory cartridges with
|
||||||
|
`app_mode: Game`.
|
||||||
|
- Preserve internal catalog metadata even when the Home UI renders only a small
|
||||||
|
subset.
|
||||||
@ -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.
|
|
||||||
@ -2,10 +2,10 @@
|
|||||||
id: AGD-0041
|
id: AGD-0041
|
||||||
ticket: foreground-stack-game-pause-shell-vm-backed
|
ticket: foreground-stack-game-pause-shell-vm-backed
|
||||||
title: Foreground Stack, Game Pause, and VM-Backed Shell Coexistence
|
title: Foreground Stack, Game Pause, and VM-Backed Shell Coexistence
|
||||||
status: open
|
status: accepted
|
||||||
created: 2026-06-05
|
created: 2026-06-05
|
||||||
resolved:
|
resolved: 2026-07-03
|
||||||
decision:
|
decision: DEC-0037
|
||||||
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
|
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
|
## Perguntas em Aberto
|
||||||
|
|
||||||
- [ ] Qual e o nome canonico dos estados de Game fora do foreground: `Paused`, `Suspended`, ambos, ou outro?
|
- [x] 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?
|
- [x] 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?
|
- [x] 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?
|
- [x] 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?
|
- [x] 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?
|
- [x] O input do Game e drenado/limpo ao pausar e ao retomar?
|
||||||
- [ ] Audio do Game pausa junto com a VM ou tem politica propria?
|
- [x] 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?
|
- [x] 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?
|
- [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?
|
||||||
- [ ] Quais eventos de lifecycle precisam ser visiveis para firmware, OS, VM e host?
|
- [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
|
## Criterio para Encerrar
|
||||||
|
|
||||||
@ -124,3 +157,22 @@ A agenda pode ser encerrada quando tivermos uma decisao clara sobre:
|
|||||||
## Discussao
|
## 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-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.
|
||||||
|
|||||||
@ -1,161 +0,0 @@
|
|||||||
---
|
|
||||||
id: AGD-0045
|
|
||||||
ticket: system-run-cart
|
|
||||||
title: SystemOS Library Root and Home Game Launch
|
|
||||||
status: accepted
|
|
||||||
created: 2026-07-03
|
|
||||||
resolved:
|
|
||||||
decision:
|
|
||||||
tags: [runtime, os, hub, cartridge, launcher, library, game, architecture]
|
|
||||||
---
|
|
||||||
|
|
||||||
## Contexto
|
|
||||||
|
|
||||||
A `DEC-0035` fechou que `system.run_cart` nao deve existir como syscall
|
|
||||||
userland e que boot direto por host/CLI/debug deve permanecer.
|
|
||||||
|
|
||||||
Isso resolveu a autoridade negativa, mas ainda nao resolveu a experiencia
|
|
||||||
desejada para o SO: apontar o runtime para um diretorio raiz de biblioteca,
|
|
||||||
fazer a Home listar os cartuchos encontrados ali e permitir que o usuario clique
|
|
||||||
em um jogo para carrega-lo.
|
|
||||||
|
|
||||||
O objetivo pratico e um "Switch feio": uma lista simples na Home, sem UX final,
|
|
||||||
sem marketplace e sem catalogo rico, mas capaz de provar que o SO, e nao o
|
|
||||||
guest, escolhe e carrega um cartucho a partir de uma biblioteca local.
|
|
||||||
|
|
||||||
## Problema
|
|
||||||
|
|
||||||
Hoje temos dois caminhos separados:
|
|
||||||
|
|
||||||
- boot direto por `--run <cart>` funciona e carrega um cartucho unico;
|
|
||||||
- Hub/Home existe, mas mostra acoes fixas de Shell nativo e nao lista jogos de
|
|
||||||
uma biblioteca real.
|
|
||||||
|
|
||||||
Sem uma biblioteca de cartuchos visivel para o SO, o usuario nao consegue
|
|
||||||
iniciar jogos a partir da Home. Isso deixa a agenda `system-run-cart` incompleta
|
|
||||||
do ponto de vista de produto: removemos o `run_cart` userland, mas ainda falta a
|
|
||||||
alternativa correta, que e o SO iniciar cartuchos por acao de usuario.
|
|
||||||
|
|
||||||
## Pontos Criticos
|
|
||||||
|
|
||||||
- O root da biblioteca deve ser fornecido pelo host como `--games-root <dir>`.
|
|
||||||
- O scan inicial deve cobrir subdiretorios imediatos com `manifest.json`.
|
|
||||||
- O loader de diretorio existente deve continuar sendo a autoridade para validar
|
|
||||||
cartucho completo; a biblioteca pode ler metadados minimos para listagem.
|
|
||||||
- A Home pode mostrar uma lista feia/clicavel; polimento visual fica fora.
|
|
||||||
- O clique em um Game deve iniciar `LoadCartridge` pelo firmware/SystemOS, nao
|
|
||||||
por syscall guest.
|
|
||||||
- V1 nao precisa tratar retorno de um Game para Home, porque isso pertence a
|
|
||||||
`AGD-0041`.
|
|
||||||
- `.pmc`, outros tipos de app, catalogo remoto, marketplace, icones, busca e
|
|
||||||
metadados ricos ficam fora.
|
|
||||||
|
|
||||||
## Opcoes
|
|
||||||
|
|
||||||
### Opcao A - Biblioteca apenas para listagem
|
|
||||||
|
|
||||||
- **Abordagem:** adicionar `--games-root`, escanear manifestos e mostrar jogos
|
|
||||||
na Home, mas sem permitir launch ainda.
|
|
||||||
- **Pro:** baixa complexidade; prova descoberta/catalogo local.
|
|
||||||
- **Contra:** nao entrega o objetivo principal de carregar jogo pela Home.
|
|
||||||
- **Manutenibilidade:** boa, mas valor funcional limitado.
|
|
||||||
|
|
||||||
### Opcao B - Home lista biblioteca e carrega Game quando nao ha Game ativo
|
|
||||||
|
|
||||||
- **Abordagem:** adicionar `--games-root`, escanear cartuchos locais, renderizar
|
|
||||||
lista simples na Home e permitir clique para carregar um Game via
|
|
||||||
`LoadCartridge`. A primeira versao cobre Home inicial/sem Game residente.
|
|
||||||
- **Pro:** entrega o fluxo desejado sem abrir troca completa entre jogos.
|
|
||||||
- **Contra:** exige passar biblioteca/acao selecionada entre host, Hub,
|
|
||||||
firmware e loader.
|
|
||||||
- **Manutenibilidade:** boa se a fronteira ficar clara: biblioteca descobre,
|
|
||||||
Hub escolhe, firmware carrega.
|
|
||||||
|
|
||||||
### Opcao C - Biblioteca mais troca completa entre jogos
|
|
||||||
|
|
||||||
- **Abordagem:** Home lista biblioteca e tambem permite `Game A -> Home ->
|
|
||||||
Game B` ja no primeiro passo.
|
|
||||||
- **Pro:** cobre a experiencia final.
|
|
||||||
- **Contra:** mistura biblioteca com pausa, fechamento, cleanup e falha de load;
|
|
||||||
depende de `AGD-0041` e `AGD-0044`.
|
|
||||||
- **Manutenibilidade:** baixa para v1.
|
|
||||||
|
|
||||||
## Sugestao / Recomendacao
|
|
||||||
|
|
||||||
Recomendo a Opcao B.
|
|
||||||
|
|
||||||
O v1 deve permitir:
|
|
||||||
|
|
||||||
- host recebe `--games-root <dir>`;
|
|
||||||
- o SO/Hub recebe uma lista de cartuchos descobertos;
|
|
||||||
- a Home mostra uma lista simples/clicavel de jogos;
|
|
||||||
- clicar em um Game carrega o cartucho via firmware `LoadCartridge`;
|
|
||||||
- boot direto por `--run <cart>` continua separado e intacto;
|
|
||||||
- nenhum guest/app chama `run_cart`;
|
|
||||||
- o escopo v1 acontece na Home inicial; retorno de Game para Home fica para
|
|
||||||
`AGD-0041`, e troca `Game A -> Home -> Game B` fica para `AGD-0044`.
|
|
||||||
|
|
||||||
Detalhes aceitos para v1:
|
|
||||||
|
|
||||||
- scan apenas de subdiretorios imediatos;
|
|
||||||
- somente cartuchos `app_mode: Game`;
|
|
||||||
- `.pmc` fica para futuro;
|
|
||||||
- cartuchos invalidos sao logados e omitidos da lista;
|
|
||||||
- o modelo interno deve ser uma entry de biblioteca expansivel, nao apenas um
|
|
||||||
summary de UI. A entry pode manter o manifest carregado em memoria, path
|
|
||||||
interno necessario para launch e metadados operacionais como instante de
|
|
||||||
descoberta/instalacao. A UI v1 mostra apenas `title`, `app_id` e
|
|
||||||
`app_version`, mas futuros metadados ingeridos pela biblioteca poderao ser
|
|
||||||
usados pelo catalogo e pela propria UI;
|
|
||||||
- clique carrega imediatamente, sem confirmacao;
|
|
||||||
- falha de load volta para Home e registra log/erro.
|
|
||||||
|
|
||||||
Essa agenda deve produzir a alternativa correta ao `run_cart` userland: uma
|
|
||||||
acao de sistema, iniciada pela Home, que carrega cartucho escolhido pelo usuario
|
|
||||||
a partir de uma biblioteca local.
|
|
||||||
|
|
||||||
## Perguntas em Aberto
|
|
||||||
|
|
||||||
- [x] O argumento deve se chamar `--games-root`.
|
|
||||||
- [x] A biblioteca deve escanear apenas subdiretorios imediatos.
|
|
||||||
- [x] A listagem v1 deve incluir apenas `app_mode: Game`.
|
|
||||||
- [x] O scan deve logar cartuchos invalidos e omiti-los da lista.
|
|
||||||
- [x] O Hub/SystemOS deve receber uma entry de biblioteca expansivel, capaz de
|
|
||||||
manter o manifest carregado, path interno para launch e metadados
|
|
||||||
operacionais como timestamp de descoberta/instalacao. A UI v1 so precisa
|
|
||||||
mostrar `title`, `app_id` e `app_version`.
|
|
||||||
- [x] O clique deve carregar imediatamente, sem confirmacao.
|
|
||||||
- [x] Se um cartucho falha ao carregar, o sistema volta para Home e registra
|
|
||||||
erro/log.
|
|
||||||
- [x] Retorno de Game para Home nao pertence a esta agenda; fica para
|
|
||||||
`AGD-0041`.
|
|
||||||
- [x] O teste minimo deve provar o fluxo `games-root -> Home list -> click ->
|
|
||||||
LoadCartridge -> GameRunning`?
|
|
||||||
|
|
||||||
## Criterio para Encerrar
|
|
||||||
|
|
||||||
A agenda pode virar decisao quando estiver claro:
|
|
||||||
|
|
||||||
- nome e semantica do argumento de host para root da biblioteca;
|
|
||||||
- escopo do scan e metadados minimos;
|
|
||||||
- fronteira entre biblioteca, Hub, firmware e loader;
|
|
||||||
- politica v1 para cartuchos invalidos;
|
|
||||||
- regra v1 para launch quando nao ha Game ativo;
|
|
||||||
- fronteira explicita com `AGD-0041` e `AGD-0044`;
|
|
||||||
- testes minimos para discovery e launch pela Home.
|
|
||||||
|
|
||||||
## Discussao
|
|
||||||
|
|
||||||
- 2026-07-03: Agenda criada como continuacao da `DSC-0004` apos a `DEC-0035`.
|
|
||||||
A decisao anterior removeu `run_cart` userland; esta agenda define o caminho
|
|
||||||
correto para o SO/Home carregar jogos a partir de uma biblioteca local.
|
|
||||||
- 2026-07-03: Respostas aceitas: usar `--games-root`, escanear apenas
|
|
||||||
subdiretorios imediatos, listar somente Games, deixar `.pmc` e outros apps
|
|
||||||
para depois, logar/omitir invalidos, usar summary com `title`, `app_id` e
|
|
||||||
`app_version`, carregar imediatamente no clique, e deixar retorno para Home
|
|
||||||
sob responsabilidade da `AGD-0041`.
|
|
||||||
- 2026-07-03: Modelo de dados refinado: a biblioteca deve produzir entries
|
|
||||||
expansíveis, nao somente summaries de UI. Cada entry pode manter manifest em
|
|
||||||
memoria, path interno de launch e metadados operacionais como timestamp de
|
|
||||||
descoberta/instalacao; a UI v1 escolhe quais campos mostrar, mas o modelo
|
|
||||||
deve permitir que metadados futuros sejam ingeridos e usados pelo catalogo/UI.
|
|
||||||
@ -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`.
|
|
||||||
@ -1,156 +0,0 @@
|
|||||||
---
|
|
||||||
id: DEC-0036
|
|
||||||
ticket: system-run-cart
|
|
||||||
title: SystemOS Games Root and Home Game Launch
|
|
||||||
status: accepted
|
|
||||||
created: 2026-07-03
|
|
||||||
ref_agenda: AGD-0045
|
|
||||||
tags: []
|
|
||||||
---
|
|
||||||
|
|
||||||
## Status
|
|
||||||
|
|
||||||
Accepted.
|
|
||||||
|
|
||||||
## Contexto
|
|
||||||
|
|
||||||
`DEC-0035` removed `system.run_cart` from the userland guest ABI and preserved
|
|
||||||
direct host/CLI/debug cartridge boot. That decision intentionally did not
|
|
||||||
deliver the Home/SO product flow: pointing PROMETEU at a local games directory,
|
|
||||||
listing available games in Home, and launching a selected game by user action.
|
|
||||||
|
|
||||||
This decision defines the first system-owned replacement for userland
|
|
||||||
`run_cart`: a local games-root library discovered by the host/SystemOS and
|
|
||||||
exposed through a simple Home UI.
|
|
||||||
|
|
||||||
## Decisao
|
|
||||||
|
|
||||||
PROMETEU MUST support a host-provided games library root through
|
|
||||||
`--games-root <dir>`.
|
|
||||||
|
|
||||||
The games root is a directory containing game cartridge directories as immediate
|
|
||||||
children. V1 MUST scan only immediate child directories. Recursive discovery is
|
|
||||||
out of scope.
|
|
||||||
|
|
||||||
The v1 games library MUST include only cartridges whose manifest declares
|
|
||||||
`app_mode: Game`. Shell/System apps, `.pmc` packages, remote catalogs,
|
|
||||||
marketplace/distribution metadata, rich icons, search, and non-game apps are out
|
|
||||||
of scope.
|
|
||||||
|
|
||||||
The library MUST produce expandable internal entries, not UI-only summaries.
|
|
||||||
Each entry MUST retain enough internal data to launch the cartridge and to grow
|
|
||||||
as a catalog model. At minimum, each entry MUST include:
|
|
||||||
|
|
||||||
- loaded manifest data;
|
|
||||||
- `title`;
|
|
||||||
- `app_id`;
|
|
||||||
- `app_version`;
|
|
||||||
- internal cartridge path;
|
|
||||||
- operational discovery metadata, including a timestamp or equivalent discovery
|
|
||||||
marker.
|
|
||||||
|
|
||||||
The Home UI v1 SHOULD display only `title`, `app_id`, and `app_version`. It MAY
|
|
||||||
hide path and operational metadata.
|
|
||||||
|
|
||||||
Invalid cartridge candidates MUST be logged and omitted from the Home game list.
|
|
||||||
|
|
||||||
Selecting a listed Game in Home MUST immediately request a system-owned launch
|
|
||||||
through firmware/SystemOS, resulting in `LoadCartridge` for that cartridge. This
|
|
||||||
MUST NOT use a guest syscall and MUST NOT reintroduce userland `run_cart`.
|
|
||||||
|
|
||||||
If launch fails, the machine MUST return to or remain in Home and record an
|
|
||||||
error/log. A polished error UI is out of scope.
|
|
||||||
|
|
||||||
Booting directly with `--run <cart>` MUST remain separate and unchanged.
|
|
||||||
|
|
||||||
Returning from a running Game to Home is outside this decision and belongs to
|
|
||||||
`AGD-0041`. Switching from `Game A -> Home -> Game B` after a game is already
|
|
||||||
active belongs to `DSC-0043 / AGD-0044`.
|
|
||||||
|
|
||||||
## Rationale
|
|
||||||
|
|
||||||
The previous `run_cart` surface was wrong because it made cartridge launch look
|
|
||||||
like an app/userland capability. The desired behavior is still valid, but the
|
|
||||||
authority must live in the system: Home presents available games and the
|
|
||||||
firmware/SystemOS loads the selected cartridge.
|
|
||||||
|
|
||||||
Using `--games-root` keeps the v1 product model honest: this is a local game
|
|
||||||
library, not a general app root. Other app types can be introduced later without
|
|
||||||
forcing the first launcher model to pretend it is a full marketplace.
|
|
||||||
|
|
||||||
Immediate child scanning keeps discovery deterministic and testable. `.pmc` and
|
|
||||||
recursive layouts can be added after the directory-cartridge path is proven.
|
|
||||||
|
|
||||||
An expandable entry model avoids prematurely freezing the UI shape as the data
|
|
||||||
model. The UI is intentionally simple, but the catalog model needs room for
|
|
||||||
future metadata such as package origin, installation/discovery timestamps, rich
|
|
||||||
presentation fields, and packaged cartridge details.
|
|
||||||
|
|
||||||
## Invariantes / Contrato
|
|
||||||
|
|
||||||
- `--games-root <dir>` is the v1 host argument for a local games library.
|
|
||||||
- The games root is Game-only in v1.
|
|
||||||
- Discovery scans immediate child directories only.
|
|
||||||
- Directory candidates without valid Game cartridge metadata are logged and
|
|
||||||
omitted.
|
|
||||||
- Library entries are internal catalog records, not direct UI DTOs.
|
|
||||||
- The UI v1 displays a simple clickable list and may show only `title`,
|
|
||||||
`app_id`, and `app_version`.
|
|
||||||
- The internal entry retains cartridge path and loaded manifest data for launch.
|
|
||||||
- Home selection is a system action that enters firmware/SystemOS loading. It is
|
|
||||||
not a guest syscall.
|
|
||||||
- `--run <cart>` direct boot remains independent from `--games-root`.
|
|
||||||
- Return-to-Home and game-to-game switching are not implemented by this
|
|
||||||
decision.
|
|
||||||
|
|
||||||
## Impactos
|
|
||||||
|
|
||||||
- **Host:** add a `--games-root <dir>` argument and pass the resolved root into
|
|
||||||
runtime/firmware/SystemOS initialization.
|
|
||||||
- **SystemOS / Hub:** add a local game library model and expose entries to Home.
|
|
||||||
Home must render a minimal clickable list and emit a system-owned launch
|
|
||||||
action for a selected entry.
|
|
||||||
- **Firmware:** consume the Home launch action and transition to
|
|
||||||
`LoadCartridge` with the selected cartridge path.
|
|
||||||
- **Loader:** continue to validate complete directory cartridges. Discovery may
|
|
||||||
read manifest metadata, but full launch still uses the existing loader.
|
|
||||||
- **Runtime / VM:** no userland ABI is added. No guest syscall participates in
|
|
||||||
launch.
|
|
||||||
- **Specs / Docs:** document `--games-root`, Game-only v1 discovery, and the
|
|
||||||
distinction between direct boot, games library launch, and future game
|
|
||||||
switching.
|
|
||||||
- **Tests:** cover discovery, invalid omission/logging, Home action emission,
|
|
||||||
and the end-to-end path from games root selection to `GameRunning`.
|
|
||||||
|
|
||||||
## Alternativas Descartadas
|
|
||||||
|
|
||||||
- **List only, no launch:** rejected because it does not satisfy the product
|
|
||||||
goal of starting games from Home.
|
|
||||||
- **General app root:** rejected for v1 because Shell/System apps need separate
|
|
||||||
lifecycle and UI contracts.
|
|
||||||
- **Recursive discovery:** rejected for v1 to keep semantics deterministic.
|
|
||||||
- **`.pmc` discovery:** rejected for v1 because packed cartridge loading is a
|
|
||||||
separate open agenda.
|
|
||||||
- **Game-to-game switch now:** rejected because it depends on foreground and
|
|
||||||
cartridge-switch orchestration work in `AGD-0041` and `AGD-0044`.
|
|
||||||
|
|
||||||
## Referencias
|
|
||||||
|
|
||||||
- Source agenda: `AGD-0045`
|
|
||||||
- Userland run-cart removal: `DEC-0035`
|
|
||||||
- Foreground/Home return scope: `AGD-0041`
|
|
||||||
- Future cartridge switch orchestration: `DSC-0043 / AGD-0044`
|
|
||||||
|
|
||||||
## Propagacao Necessaria
|
|
||||||
|
|
||||||
- Add or update runtime specs for games-root discovery and Home launch.
|
|
||||||
- Add host CLI argument plumbing for `--games-root`.
|
|
||||||
- Add a catalog/library entry model.
|
|
||||||
- Add Hub/Home list rendering and click handling.
|
|
||||||
- Add firmware/SystemOS action routing to `LoadCartridge`.
|
|
||||||
- Add tests for discovery, invalid candidates, action emission, and
|
|
||||||
`games-root -> Home click -> GameRunning`.
|
|
||||||
|
|
||||||
## Revision Log
|
|
||||||
|
|
||||||
- 2026-07-03: Initial draft from `AGD-0045`.
|
|
||||||
@ -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`.
|
||||||
@ -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`
|
|
||||||
@ -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`
|
|
||||||
@ -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/`
|
|
||||||
@ -1,103 +0,0 @@
|
|||||||
---
|
|
||||||
id: PLN-0132
|
|
||||||
ticket: system-run-cart
|
|
||||||
title: Specify Games Root Home Launch Contract
|
|
||||||
status: done
|
|
||||||
created: 2026-07-03
|
|
||||||
ref_decisions: [DEC-0036]
|
|
||||||
tags: []
|
|
||||||
---
|
|
||||||
|
|
||||||
## Briefing
|
|
||||||
|
|
||||||
`DEC-0036` establishes a new system-owned game library launch path:
|
|
||||||
the host receives `--games-root <dir>`, SystemOS/Home lists valid Game
|
|
||||||
directory cartridges from that root, and selecting one starts the cartridge
|
|
||||||
through firmware loading rather than a guest syscall.
|
|
||||||
|
|
||||||
This plan updates the normative specs before code is changed.
|
|
||||||
|
|
||||||
## Objective
|
|
||||||
|
|
||||||
Document the v1 games-root and Home launch contract in the canonical runtime
|
|
||||||
specs so implementation plans cannot drift back into userland `run_cart` or
|
|
||||||
general app-library semantics.
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
- Source decision: `DEC-0036`.
|
|
||||||
- Prior decision: `DEC-0035`, which removed userland `system.run_cart` and
|
|
||||||
preserved direct `--run` boot.
|
|
||||||
- This plan must be completed before `PLN-0133`, `PLN-0134`, and `PLN-0135`.
|
|
||||||
|
|
||||||
## Scope
|
|
||||||
|
|
||||||
- Update the runtime specs to define `--games-root <dir>` as the v1 local games
|
|
||||||
library root.
|
|
||||||
- Specify that discovery scans only immediate child directories.
|
|
||||||
- Specify that v1 library discovery includes only valid directory cartridges
|
|
||||||
with `app_mode: Game`.
|
|
||||||
- Specify that `.pmc`, recursive discovery, Shell/System apps, marketplace
|
|
||||||
metadata, rich presentation, search, and non-game apps are out of scope.
|
|
||||||
- Specify the internal library entry contract: loaded manifest data, `title`,
|
|
||||||
`app_id`, `app_version`, internal cartridge path, and discovery metadata.
|
|
||||||
- Specify that Home v1 may display only `title`, `app_id`, and `app_version`.
|
|
||||||
- Specify that selecting a Home game emits a system-owned launch request that
|
|
||||||
transitions through firmware/SystemOS into `LoadCartridge`.
|
|
||||||
- Specify that invalid candidates are logged and omitted.
|
|
||||||
- Specify that launch failure remains or returns to Home and logs the failure.
|
|
||||||
- Reaffirm that direct `--run <cart>` boot remains independent and unchanged.
|
|
||||||
|
|
||||||
## Non-Goals
|
|
||||||
|
|
||||||
- No Rust implementation.
|
|
||||||
- No Home UI changes.
|
|
||||||
- No `.pmc` discovery or packaged-cartridge spec changes.
|
|
||||||
- No recursive library layout.
|
|
||||||
- No return-to-Home behavior for a running Game.
|
|
||||||
- No Game A -> Home -> Game B orchestration.
|
|
||||||
- No guest syscall or userland ABI addition.
|
|
||||||
|
|
||||||
## Execution Method
|
|
||||||
|
|
||||||
1. Update [docs/specs/runtime/14-boot-profiles.md](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/docs/specs/runtime/14-boot-profiles.md) with:
|
|
||||||
- direct `--run` boot remaining a single-cartridge boot profile;
|
|
||||||
- `--games-root <dir>` as a SystemOS/Home library profile;
|
|
||||||
- the distinction between direct boot, Home launch, and future game-switch
|
|
||||||
orchestration.
|
|
||||||
2. Update [docs/specs/runtime/12-firmware-pos-and-prometeuhub.md](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/docs/specs/runtime/12-firmware-pos-and-prometeuhub.md) with:
|
|
||||||
- Home's responsibility to display the local games library;
|
|
||||||
- the system-owned launch action boundary;
|
|
||||||
- failure handling that leaves the machine in Home and records an error.
|
|
||||||
3. Update [docs/specs/runtime/13-cartridge.md](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/docs/specs/runtime/13-cartridge.md) with:
|
|
||||||
- directory-cartridge discovery requirements for library candidates;
|
|
||||||
- Game-only filtering by manifest `app_mode`;
|
|
||||||
- invalid candidate omission and diagnostics.
|
|
||||||
4. Update [docs/specs/runtime/16-host-abi-and-syscalls.md](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/docs/specs/runtime/16-host-abi-and-syscalls.md) only if needed to reinforce that no guest syscall owns cartridge launch.
|
|
||||||
5. Keep all spec text in English.
|
|
||||||
|
|
||||||
## Acceptance Criteria
|
|
||||||
|
|
||||||
- The specs define `--games-root <dir>` and do not describe it as a generic app
|
|
||||||
root.
|
|
||||||
- The specs state that v1 scans immediate child directories only.
|
|
||||||
- The specs state that only valid Game directory cartridges enter the Home list.
|
|
||||||
- The specs state that Home launch is system-owned and enters `LoadCartridge`.
|
|
||||||
- The specs preserve `--run <cart>` as a separate direct boot path.
|
|
||||||
- The specs explicitly exclude `.pmc`, recursive discovery, return-to-Home, and
|
|
||||||
game-switch orchestration from this implementation slice.
|
|
||||||
- No spec reintroduces userland `run_cart`.
|
|
||||||
|
|
||||||
## Tests
|
|
||||||
|
|
||||||
- Run `discussion validate`.
|
|
||||||
- Run targeted text checks for `--games-root`, `LoadCartridge`, and absence of
|
|
||||||
`system.run_cart` as an active public launch mechanism in edited specs.
|
|
||||||
|
|
||||||
## Affected Artifacts
|
|
||||||
|
|
||||||
- `docs/specs/runtime/12-firmware-pos-and-prometeuhub.md`
|
|
||||||
- `docs/specs/runtime/13-cartridge.md`
|
|
||||||
- `docs/specs/runtime/14-boot-profiles.md`
|
|
||||||
- `docs/specs/runtime/16-host-abi-and-syscalls.md`
|
|
||||||
- `discussion/workflow/plans/PLN-0132-specify-games-root-home-launch-contract.md`
|
|
||||||
@ -1,118 +0,0 @@
|
|||||||
---
|
|
||||||
id: PLN-0133
|
|
||||||
ticket: system-run-cart
|
|
||||||
title: Implement Games Root Library Discovery
|
|
||||||
status: done
|
|
||||||
created: 2026-07-03
|
|
||||||
ref_decisions: [DEC-0036]
|
|
||||||
tags: []
|
|
||||||
---
|
|
||||||
|
|
||||||
## Briefing
|
|
||||||
|
|
||||||
`DEC-0036` requires a host-provided games root and an expandable internal
|
|
||||||
library model before Home can render or launch games. This plan implements the
|
|
||||||
library discovery and host plumbing only; UI launch wiring is handled by
|
|
||||||
`PLN-0134`.
|
|
||||||
|
|
||||||
## Objective
|
|
||||||
|
|
||||||
Add a tested games-root discovery model that scans immediate child directory
|
|
||||||
cartridges, filters to valid Game manifests, records diagnostics for invalid
|
|
||||||
candidates, and carries enough metadata for Home rendering and later launch.
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
- Source decision: `DEC-0036`.
|
|
||||||
- `PLN-0132` should be completed first so code follows the documented contract.
|
|
||||||
- Existing cartridge manifest and directory loader behavior in the console
|
|
||||||
crates.
|
|
||||||
- Existing host CLI and `HostRunner` boot setup.
|
|
||||||
|
|
||||||
## Scope
|
|
||||||
|
|
||||||
- Add `--games-root <PATH>` to the desktop host CLI.
|
|
||||||
- Pass the optional games root into the host runner / firmware initialization
|
|
||||||
path without changing direct `--run` or `--debug` boot behavior.
|
|
||||||
- Add a SystemOS-owned games library model for directory cartridge discovery.
|
|
||||||
- Scan only immediate child directories of the root.
|
|
||||||
- Read and retain manifest data for each valid candidate.
|
|
||||||
- Include only candidates whose manifest declares `app_mode: Game`.
|
|
||||||
- Retain internal cartridge path and operational discovery metadata on each
|
|
||||||
entry.
|
|
||||||
- Emit diagnostics for invalid, unreadable, or non-Game candidates and omit
|
|
||||||
them from the returned entries.
|
|
||||||
- Keep discovery independent from full cartridge launch: discovery reads
|
|
||||||
metadata; launch still uses the existing loader in `PLN-0134`.
|
|
||||||
|
|
||||||
## Non-Goals
|
|
||||||
|
|
||||||
- No Home list rendering.
|
|
||||||
- No click handling or `LoadCartridge` transition.
|
|
||||||
- No `.pmc` discovery.
|
|
||||||
- No recursive scan.
|
|
||||||
- No Shell/System app catalog.
|
|
||||||
- No marketplace metadata, icons, search, sorting UI, or polished errors.
|
|
||||||
- No new guest syscall.
|
|
||||||
|
|
||||||
## Execution Method
|
|
||||||
|
|
||||||
1. Introduce a library/discovery module in the SystemOS side, preferably under
|
|
||||||
`crates/console/prometeu-system/src/services/` unless the existing module
|
|
||||||
layout has a more local owner.
|
|
||||||
2. Define an internal entry type with at least:
|
|
||||||
- loaded cartridge manifest data;
|
|
||||||
- `title`;
|
|
||||||
- `app_id`;
|
|
||||||
- `app_version`;
|
|
||||||
- internal cartridge path;
|
|
||||||
- discovery metadata, using `SystemTime` or another explicit discovery
|
|
||||||
marker.
|
|
||||||
3. Define discovery diagnostics that can be logged by the caller and asserted in
|
|
||||||
tests.
|
|
||||||
4. Implement a scanner that:
|
|
||||||
- accepts an optional root path;
|
|
||||||
- returns an empty library when no root is configured;
|
|
||||||
- iterates only immediate child directories;
|
|
||||||
- parses `manifest.json` using structured manifest types, not ad hoc string
|
|
||||||
matching;
|
|
||||||
- filters to `app_mode: Game`;
|
|
||||||
- sorts entries deterministically for stable Home presentation and tests.
|
|
||||||
5. Add `--games-root <PATH>` to
|
|
||||||
[crates/host/prometeu-host-desktop-winit/src/lib.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/host/prometeu-host-desktop-winit/src/lib.rs)
|
|
||||||
and pass the path into
|
|
||||||
[crates/host/prometeu-host-desktop-winit/src/runner.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/host/prometeu-host-desktop-winit/src/runner.rs).
|
|
||||||
6. Store or expose the discovered library to firmware/SystemOS in a way that
|
|
||||||
`PLN-0134` can consume without re-scanning inside the Home click path.
|
|
||||||
7. Add focused unit tests using temporary cartridge roots with:
|
|
||||||
- one valid Game directory cartridge;
|
|
||||||
- one valid non-Game cartridge;
|
|
||||||
- one invalid directory;
|
|
||||||
- one nested directory that must not be discovered.
|
|
||||||
|
|
||||||
## Acceptance Criteria
|
|
||||||
|
|
||||||
- `--games-root <PATH>` is accepted by the desktop host CLI.
|
|
||||||
- Absence of `--games-root` leaves existing Hub boot behavior unchanged.
|
|
||||||
- Direct `--run <cart>` and `--debug <cart>` behavior remains unchanged.
|
|
||||||
- Discovery returns only immediate valid Game directory cartridges.
|
|
||||||
- Each library entry retains manifest data, path, title, app id, app version,
|
|
||||||
and discovery metadata.
|
|
||||||
- Invalid candidates are represented in diagnostics and excluded from entries.
|
|
||||||
- Discovery does not fully load or boot cartridge programs.
|
|
||||||
|
|
||||||
## Tests
|
|
||||||
|
|
||||||
- Add and run focused games-library discovery tests in the owning console crate.
|
|
||||||
- Run `cargo test -p prometeu-system` if the library lives in
|
|
||||||
`prometeu-system`.
|
|
||||||
- Run `cargo test -p prometeu-host-desktop-winit` for CLI/runner plumbing.
|
|
||||||
- Run `discussion validate`.
|
|
||||||
|
|
||||||
## Affected Artifacts
|
|
||||||
|
|
||||||
- `crates/console/prometeu-system/src/services/`
|
|
||||||
- `crates/console/prometeu-system/src/lib.rs` or module exports as needed
|
|
||||||
- `crates/host/prometeu-host-desktop-winit/src/lib.rs`
|
|
||||||
- `crates/host/prometeu-host-desktop-winit/src/runner.rs`
|
|
||||||
- `discussion/workflow/plans/PLN-0133-implement-games-root-library-discovery.md`
|
|
||||||
@ -1,104 +0,0 @@
|
|||||||
---
|
|
||||||
id: PLN-0134
|
|
||||||
ticket: system-run-cart
|
|
||||||
title: Wire Home Game List Launch Flow
|
|
||||||
status: done
|
|
||||||
created: 2026-07-03
|
|
||||||
ref_decisions: [DEC-0036]
|
|
||||||
tags: []
|
|
||||||
---
|
|
||||||
|
|
||||||
## Briefing
|
|
||||||
|
|
||||||
After `PLN-0133`, SystemOS can discover a local Game library but Home still
|
|
||||||
does not present or launch those entries. This plan wires the discovered
|
|
||||||
library into Prometeu Hub/Home and routes a selected game to firmware
|
|
||||||
`LoadCartridge`.
|
|
||||||
|
|
||||||
## Objective
|
|
||||||
|
|
||||||
Make Home display a minimal clickable games list and launch the selected Game
|
|
||||||
through a system-owned firmware/SystemOS path, without reintroducing userland
|
|
||||||
`run_cart`.
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
|
|
||||||
- Source decision: `DEC-0036`.
|
|
||||||
- `PLN-0132` for documented contract.
|
|
||||||
- `PLN-0133` for `--games-root` plumbing and the internal library entry model.
|
|
||||||
- Existing Prometeu Hub Home profile and firmware state transitions.
|
|
||||||
|
|
||||||
## Scope
|
|
||||||
|
|
||||||
- Provide the discovered games library to Prometeu Hub/Home.
|
|
||||||
- Render a minimal Home list showing `title`, `app_id`, and `app_version`.
|
|
||||||
- Add Home hit-testing/click handling for game entries.
|
|
||||||
- Extend the system profile action model with a system-owned game launch action.
|
|
||||||
- Handle that action in firmware/SystemOS by loading the selected cartridge via
|
|
||||||
the existing cartridge loader and entering `LoadCartridge`.
|
|
||||||
- On load failure, log/record the error and keep or return the machine to Home.
|
|
||||||
- Preserve existing native shell launch behavior.
|
|
||||||
|
|
||||||
## Non-Goals
|
|
||||||
|
|
||||||
- No polished launcher UI.
|
|
||||||
- No icons, screenshots, search, filtering, or marketplace metadata.
|
|
||||||
- No return-to-Home while a Game is running.
|
|
||||||
- No Game A -> Home -> Game B foreground orchestration.
|
|
||||||
- No `.pmc` launch support.
|
|
||||||
- No guest syscall.
|
|
||||||
- No direct-boot behavior changes.
|
|
||||||
|
|
||||||
## Execution Method
|
|
||||||
|
|
||||||
1. Extend the SystemOS/Hub action type currently represented by
|
|
||||||
`SystemProfileAction::LaunchNativeShell` with a game-launch action that
|
|
||||||
carries a stable reference to the selected library entry or cartridge path.
|
|
||||||
2. Update the Prometeu Hub state in
|
|
||||||
[crates/console/prometeu-system/src/programs/prometeu_hub.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-system/src/programs/prometeu_hub.rs)
|
|
||||||
or its local modules to accept the discovered game entries.
|
|
||||||
3. Render the Home games list with stable dimensions and simple clickable rows.
|
|
||||||
Rows must display only `title`, `app_id`, and `app_version` for v1.
|
|
||||||
4. Add hit-testing so selecting a row emits the game-launch action immediately.
|
|
||||||
5. Update
|
|
||||||
[crates/console/prometeu-firmware/src/firmware/steps/firmware_step_hub_home.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-firmware/src/firmware/steps/firmware_step_hub_home.rs)
|
|
||||||
to consume the new action.
|
|
||||||
6. In the firmware action handler:
|
|
||||||
- call the existing cartridge loader for the selected path;
|
|
||||||
- on success, return `FirmwareState::LoadCartridge(...)`;
|
|
||||||
- on failure, log/record the error and remain in the Home path.
|
|
||||||
7. Ensure shell launch still works exactly as before.
|
|
||||||
8. Add unit or integration tests for:
|
|
||||||
- Home list presentation data;
|
|
||||||
- click-to-action emission;
|
|
||||||
- firmware action handling success;
|
|
||||||
- firmware action handling failure.
|
|
||||||
|
|
||||||
## Acceptance Criteria
|
|
||||||
|
|
||||||
- Starting the host with `--games-root <dir>` exposes valid Game entries in
|
|
||||||
Home.
|
|
||||||
- The Home list displays `title`, `app_id`, and `app_version`.
|
|
||||||
- Clicking a listed Game routes through a system action and enters
|
|
||||||
`LoadCartridge`.
|
|
||||||
- The launch path does not use a guest syscall and does not mention
|
|
||||||
`system.run_cart`.
|
|
||||||
- Invalid or failing launch paths remain in Home and record an error.
|
|
||||||
- Existing native shell Home actions continue to work.
|
|
||||||
- Direct `--run` remains separate and unchanged.
|
|
||||||
|
|
||||||
## Tests
|
|
||||||
|
|
||||||
- Run `cargo test -p prometeu-system` for Hub action and presentation behavior.
|
|
||||||
- Run `cargo test -p prometeu-firmware` for firmware transition behavior.
|
|
||||||
- Run `cargo test -p prometeu-host-desktop-winit` if runner integration changes.
|
|
||||||
- Run `discussion validate`.
|
|
||||||
|
|
||||||
## Affected Artifacts
|
|
||||||
|
|
||||||
- `crates/console/prometeu-system/src/programs/prometeu_hub.rs`
|
|
||||||
- `crates/console/prometeu-system/src/services/`
|
|
||||||
- `crates/console/prometeu-firmware/src/firmware/steps/firmware_step_hub_home.rs`
|
|
||||||
- `crates/console/prometeu-firmware/src/firmware/firmware.rs`
|
|
||||||
- `crates/host/prometeu-host-desktop-winit/src/runner.rs`
|
|
||||||
- `discussion/workflow/plans/PLN-0134-wire-home-game-list-launch-flow.md`
|
|
||||||
@ -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`
|
|
||||||
@ -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.
|
||||||
@ -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.
|
||||||
@ -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.
|
||||||
@ -0,0 +1,106 @@
|
|||||||
|
---
|
||||||
|
id: PLN-0139
|
||||||
|
ticket: foreground-stack-game-pause-shell-vm-backed
|
||||||
|
title: Validate Game Home Shell Game End To End
|
||||||
|
status: open
|
||||||
|
created: 2026-07-03
|
||||||
|
ref_decisions: [DEC-0037]
|
||||||
|
tags: [runtime, validation, firmware, host, lifecycle]
|
||||||
|
---
|
||||||
|
|
||||||
|
## Briefing
|
||||||
|
|
||||||
|
`DEC-0037` is not complete until the product flow is proven end to end:
|
||||||
|
a Game runs, the user requests Home, the Game is paused/suspended, Hub or a
|
||||||
|
VM-backed Shell takes foreground, closing Shell returns to Hub, and the same
|
||||||
|
Game can resume only after a valid current-epoch frame exists.
|
||||||
|
|
||||||
|
This plan adds final validation after the spec, SystemOS, VM, host input, and
|
||||||
|
render/audio/input boundary plans are implemented.
|
||||||
|
|
||||||
|
## Decisions of Origin
|
||||||
|
|
||||||
|
- `DEC-0037` - Foreground Stack and Game Pause Contract.
|
||||||
|
|
||||||
|
## Target
|
||||||
|
|
||||||
|
Prove the complete `Game -> Home/Shell -> same Game` lifecycle and prevent
|
||||||
|
regressions around guest input, foreground authority, and stale rendering.
|
||||||
|
|
||||||
|
## Scope
|
||||||
|
|
||||||
|
- Add integration-style tests for:
|
||||||
|
- Game running to Home request;
|
||||||
|
- pause notification and forced suspension;
|
||||||
|
- Hub foreground while Game is resident;
|
||||||
|
- VM-backed Shell foreground while Game is suspended;
|
||||||
|
- Shell close returning to Hub;
|
||||||
|
- resume request returning to same Game;
|
||||||
|
- first-valid-frame visual restore;
|
||||||
|
- host `Esc`/`Home` not entering guest input.
|
||||||
|
- Add manual smoke instructions for desktop host.
|
||||||
|
- Confirm direct `--run` and games-root Home launch remain separate.
|
||||||
|
|
||||||
|
## Out of Scope
|
||||||
|
|
||||||
|
- No new implementation beyond tests and developer-facing validation notes.
|
||||||
|
- No Game A -> Home -> Game B switching.
|
||||||
|
- No performance tuning.
|
||||||
|
- No polished UI.
|
||||||
|
|
||||||
|
## Execution Plan
|
||||||
|
|
||||||
|
1. Add firmware/SystemOS integration tests.
|
||||||
|
Use the most stable existing seams in `crates/console/prometeu-firmware/src/firmware/firmware.rs`
|
||||||
|
and `crates/console/prometeu-system` tests to drive Game foreground, Home
|
||||||
|
request, Shell foreground, Shell close, and Game resume.
|
||||||
|
|
||||||
|
2. Add host input integration tests.
|
||||||
|
Ensure `Esc` and physical `Home` create a host Home event and do not mutate
|
||||||
|
guest `InputSignals`.
|
||||||
|
|
||||||
|
3. Add render publication validation.
|
||||||
|
Assert stale submissions from the pre-pause Game epoch are rejected after
|
||||||
|
Home takes foreground and that the Game is not visually restored until a new
|
||||||
|
current-epoch submission exists.
|
||||||
|
|
||||||
|
4. Add audio/input boundary validation.
|
||||||
|
Assert Game input is cleared or barriered across pause/resume. Assert Game
|
||||||
|
audio pause follows Game suspension.
|
||||||
|
|
||||||
|
5. Add direct boot and games-root regression checks.
|
||||||
|
Ensure direct `--run <cart>` remains independent from Home request handling
|
||||||
|
and that games-root Home launch still enters the Game path.
|
||||||
|
|
||||||
|
6. Document manual smoke commands.
|
||||||
|
Add or update developer-facing spec text with release-mode commands:
|
||||||
|
- `cargo run --release -p prometeu-host-desktop-winit -- --run test-cartridges/stress-console`
|
||||||
|
- `cargo run --release -p prometeu-host-desktop-winit -- --games-root test-cartridges`
|
||||||
|
Include the expected `Esc -> Home -> Shell -> Hub -> resume Game` behavior
|
||||||
|
once implemented.
|
||||||
|
|
||||||
|
## Acceptance Criteria
|
||||||
|
|
||||||
|
- Automated tests cover `Game -> Home -> same Game`.
|
||||||
|
- Automated tests cover `Game -> Home -> Shell -> Hub -> same Game`.
|
||||||
|
- Tests prove Home request is host/SystemOS control, not guest pad input.
|
||||||
|
- Tests prove suspended Game does not tick.
|
||||||
|
- Tests prove stale render submissions are not presented.
|
||||||
|
- Tests prove visual return waits for a current-epoch Game frame.
|
||||||
|
- Direct `--run` and games-root Home launch regressions pass.
|
||||||
|
|
||||||
|
## Tests / Validation
|
||||||
|
|
||||||
|
- Run `cargo test -p prometeu-system`.
|
||||||
|
- Run `cargo test -p prometeu-firmware`.
|
||||||
|
- Run `cargo test -p prometeu-host-desktop-winit`.
|
||||||
|
- Run any targeted render worker tests affected by ownership epoch changes.
|
||||||
|
- Run `discussion validate`.
|
||||||
|
|
||||||
|
## Risks
|
||||||
|
|
||||||
|
- The current test seams may not expose enough host-driven lifecycle behavior.
|
||||||
|
If needed, add narrow test-only helpers rather than testing through sleeps or
|
||||||
|
real-time window loops.
|
||||||
|
- End-to-end validation can become flaky if it depends on wall-clock timing.
|
||||||
|
Use deterministic ticks and explicit state transitions.
|
||||||
@ -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`.
|
||||||
@ -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.
|
||||||
Loading…
x
Reference in New Issue
Block a user