prometeu-runtime/discussion/workflow/plans/PLN-0057-lifecycle-tests-and-invariants.md

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