---
id: PLN-0057
ticket: system-os-lifecycle-process-task-contract
title: Lifecycle Tests and Invariants
status: done
created: 2026-05-15
ref_decisions: [DEC-0025]
tags: [runtime, os, lifecycle, process, task, shell, firmware]
---

## Briefing

Add focused test coverage and invariant checks for the lifecycle contract
introduced by `PLN-0055` and consumed by `PLN-0056`.

## Source Decisions

- `DEC-0025`: first-wave lifecycle maps task states to process states through
  `SystemOS` and keeps `Background` outside the public lifecycle contract.

## Target

Make the lifecycle contract executable through unit tests and regression tests,
without expanding scope into background execution, UI behavior, or service
ownership.

## Scope

- Add `SystemOS` unit tests for all first-wave lifecycle operations.
- Add negative tests for missing task, missing process, and invalid transition.
- Add firmware-level regression coverage for lifecycle delegation where the
  existing test harness can observe it.
- Keep manager tests focused on local storage and simple transitions.

## Out of Scope

- End-to-end UX tests for suspend/resume.
- Hub/Home navigation after lifecycle changes.
- Background services.
- Docking.
- App switching.
- Diagnostics persistence.
- WindowManager behavior changes.

## Execution Plan

1. Add core lifecycle mapping tests.
   - Target file: `crates/console/prometeu-system/src/os/system_os.rs` or a
     dedicated `os` test module following existing crate style.
   - Verify:
     - `set_foreground_task`: task becomes `Foreground`, process becomes
       `Running`.
     - `suspend_task`: task becomes `Suspended`, process becomes `Suspended`.
     - `resume_task`: suspended task becomes `Foreground`, process becomes
       `Running`.
     - `close_task`: task becomes `Closed`, process becomes `Stopped`.
     - `crash_task`: task becomes `Crashed`, process becomes `Crashed`.

2. Add error tests.
   - Verify missing task returns `LifecycleError::TaskNotFound`.
   - Verify a task whose process no longer exists returns
     `LifecycleError::ProcessNotFound`.
   - Verify invalid resume from non-suspended task returns
     `LifecycleError::InvalidTransition` with operation `Resume`.

3. Add non-removal tests.
   - Verify `close_task` leaves the closed task available through
     `TaskManager::get`.
   - Verify `close_task` leaves the stopped process available through
     `ProcessManager::get`.
   - Do not call `remove_closed` or `remove_stopped` as part of lifecycle API
     tests.

4. Add background exclusion tests.
   - Assert there is no `SystemOS::background_task` API added by this wave.
   - Keep any existing `TaskState::Background` behavior in manager-level tests
     documented as manager behavior, not first-wave lifecycle semantics.

5. Add firmware regression tests after `PLN-0056`.
   - Target file: `crates/console/prometeu-firmware/src/firmware/firmware.rs`
     or the relevant step test module.
   - Verify game launch still enters `GameRunningStep`.
   - Verify shell launch still enters `SystemRunningStep`.
   - Verify a game crash path marks the active task as crashed when the test
     harness can observe `ctx.os.task_manager`.

## Acceptance Criteria

- Every lifecycle method from `DEC-0025` has a positive `SystemOS` test.
- Missing task and missing process return typed lifecycle errors.
- Invalid resume transition is covered by a test.
- `close_task` is tested as mark-only, not removal.
- No test encodes `Background` as a normative first-wave lifecycle operation.
- Firmware regression tests still pass for game and shell launch.

## Tests / Validation

- Run `cargo test -p prometeu-system`.
- Run `cargo test -p prometeu-firmware`.
- If workspace-level tests are practical after these changes, run the relevant
  workspace command used by this repository.

## Risks

- Some negative tests may require test-only helpers to create an inconsistent
  task/process relationship. Prefer narrow test fixtures over making corruption
  APIs public.
- Compile-time absence of `background_task` may not be directly testable
  without compile-fail infrastructure. In that case, validate it by code review
  and keep runtime tests focused on the exposed first-wave methods.