120 lines
4.5 KiB
Markdown
120 lines
4.5 KiB
Markdown
---
|
|
id: PLN-0056
|
|
ticket: system-os-lifecycle-process-task-contract
|
|
title: Firmware Lifecycle Delegation
|
|
status: open
|
|
created: 2026-05-15
|
|
ref_decisions: [DEC-0025]
|
|
tags: [runtime, os, lifecycle, process, task, shell, firmware]
|
|
---
|
|
|
|
## Briefing
|
|
|
|
Move firmware lifecycle callsites to the `SystemOS` semantic API introduced by
|
|
`PLN-0055`. Firmware remains a boot and execution state machine; it must not
|
|
coordinate task/process lifecycle by calling `TaskManager` and `ProcessManager`
|
|
separately.
|
|
|
|
## Source Decisions
|
|
|
|
- `DEC-0025`: firmware must delegate semantic lifecycle transitions to
|
|
`SystemOS`.
|
|
|
|
## Target
|
|
|
|
Replace direct lifecycle manipulation in firmware with `SystemOS` lifecycle
|
|
methods while preserving current observable behavior.
|
|
|
|
## Scope
|
|
|
|
- Update cartridge launch paths to use `SystemOS` lifecycle authority when
|
|
placing newly created tasks in foreground.
|
|
- Update crash paths where a task crash is detected so task/process state moves
|
|
through `SystemOS::crash_task`.
|
|
- Preserve the strong `GameRunningStep` invariant: a running game step only
|
|
supports a game task in `TaskState::Foreground`.
|
|
- Keep `SystemRunningStep`, Hub, and WindowManager behavior unchanged except for
|
|
lifecycle delegation required by `DEC-0025`.
|
|
|
|
## Out of Scope
|
|
|
|
- Full game suspend/resume UX.
|
|
- Returning to Hub/Home on suspend or close.
|
|
- Shell UI redesign.
|
|
- App switcher.
|
|
- Background task API.
|
|
- WindowManager migration.
|
|
- Diagnostics service or crash report persistence.
|
|
|
|
## Execution Plan
|
|
|
|
1. Audit direct lifecycle manager usage.
|
|
- Target files:
|
|
`crates/console/prometeu-firmware/src/firmware/*.rs`,
|
|
`crates/console/prometeu-system/src/os/system_os.rs`.
|
|
- Search for direct calls to `task_manager.set_foreground`,
|
|
`task_manager.mark_suspended`, `task_manager.close_task`,
|
|
`task_manager.mark_crashed`, `process_manager.mark_suspended`,
|
|
`process_manager.mark_stopped`, and `process_manager.mark_crashed`.
|
|
|
|
2. Keep launch construction inside `SystemOS`.
|
|
- Target file:
|
|
`crates/console/prometeu-system/src/os/system_os.rs`.
|
|
- Ensure `create_vm_game_task`, `create_vm_shell_task`, and
|
|
`create_native_shell_task` coordinate foreground/running state through the
|
|
lifecycle core API from `PLN-0055`.
|
|
|
|
3. Update game crash handling.
|
|
- Target file:
|
|
`crates/console/prometeu-firmware/src/firmware/firmware_step_game_running.rs`.
|
|
- When the task is missing, preserve current crash-screen behavior. If the
|
|
task does not exist, `SystemOS::crash_task` cannot attach state and the
|
|
firmware should continue producing a clear crash report.
|
|
- When a foreground invariant fails for an existing task, call
|
|
`ctx.os.crash_task(task_id, report?)` before transitioning to
|
|
`AppCrashesStep`.
|
|
- When `tick_vm` returns a crash report for the active task, call
|
|
`ctx.os.crash_task(task_id, report?)` before transitioning to
|
|
`AppCrashesStep`.
|
|
|
|
4. Keep shell launch behavior unchanged.
|
|
- Target file:
|
|
`crates/console/prometeu-firmware/src/firmware/firmware_step_load_cartridge.rs`.
|
|
- Do not move `WindowManager` logic.
|
|
- Do not change shell window creation or focus behavior.
|
|
- Rely on `SystemOS::create_vm_shell_task` to coordinate task/process
|
|
foreground state.
|
|
|
|
5. Avoid introducing background lifecycle.
|
|
- Do not add `background_task`.
|
|
- Do not treat `TaskState::Background` as a public lifecycle result in
|
|
firmware.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- Firmware does not coordinate task/process lifecycle by manually changing both
|
|
managers.
|
|
- Game VM crash results in `SystemOS::crash_task` for the active task when the
|
|
task still exists.
|
|
- Foreground invariant violation in `GameRunningStep` crashes the task through
|
|
`SystemOS`.
|
|
- Launch behavior for `AppMode::Game` and `AppMode::Shell` remains unchanged.
|
|
- WindowManager and Hub behavior are not redesigned or moved.
|
|
|
|
## Tests / Validation
|
|
|
|
- Run firmware tests that cover cartridge launch for `AppMode::Game` and
|
|
`AppMode::Shell`.
|
|
- Add or update tests for `GameRunningStep` crash delegation if the existing
|
|
test harness supports firmware step testing.
|
|
- Run the affected Rust test suite for `prometeu-firmware`.
|
|
|
|
## Risks
|
|
|
|
- Crash report ownership is not final. This plan should pass the report through
|
|
the lifecycle API only to the extent supported by `PLN-0055`; persistence
|
|
remains out of scope.
|
|
- `GameRunningStep` currently reads task state directly. This is acceptable for
|
|
enforcing the foreground invariant, but it must not become a place that
|
|
coordinates lifecycle state across managers.
|