Intrepid/prometeu-runtime
Intrepid/prometeu-runtime
4
0
Fork 0
Code Pull Requests Activity
prometeu-runtime/discussion/workflow/plans/PLN-0056-firmware-lifecycle-delegation.md

4.5 KiB
Raw Blame History

id ticket title status created ref_decisions tags
PLN-0056 system-os-lifecycle-process-task-contract Firmware Lifecycle Delegation done 2026-05-15
DEC-0025
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.