111 lines
4.1 KiB
Markdown
111 lines
4.1 KiB
Markdown
---
|
|
id: PLN-0057
|
|
ticket: system-os-lifecycle-process-task-contract
|
|
title: Lifecycle Tests and Invariants
|
|
status: open
|
|
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.
|