accept DEC-0025 lifecycle plans

This commit is contained in:
2026-05-15 05:31:37 +01:00
parent 5282089c7d
commit fbebd8887a
6 changed files with 632 additions and 34 deletions
@@ -0,0 +1,121 @@
---
id: PLN-0055
ticket: system-os-lifecycle-process-task-contract
title: SystemOS Lifecycle Core API
status: open
created: 2026-05-15
ref_decisions: [DEC-0025]
tags: [runtime, os, lifecycle, process, task, shell, firmware]
---
## Briefing
Implement the first-wave `SystemOS` lifecycle API required by `DEC-0025`.
`SystemOS` becomes the semantic coordinator for `TaskState` and `ProcessState`;
`TaskManager` and `ProcessManager` remain storage and simple transition
mechanisms.
## Source Decisions
- `DEC-0025`: `SystemOS` is the lifecycle authority for tasks and processes.
## Target
Add typed lifecycle operations to `prometeu-system` without changing firmware
behavior, WindowManager ownership, Hub UI, background services, docking, app
switching, or VM ownership.
## Scope
- Add `LifecycleError` and `LifecycleOperation` in `prometeu-system`.
- Add lifecycle methods on `SystemOS`:
- `set_foreground_task(task_id)`
- `suspend_task(task_id)`
- `resume_task(task_id)`
- `close_task(task_id)`
- `crash_task(task_id, report?)`
- Coordinate task and process state changes inside `SystemOS`.
- Preserve `TaskManager` and `ProcessManager` as internal state managers.
- Keep `Background` reserved and out of public lifecycle semantics.
## Out of Scope
- Background semantics.
- Docking.
- Background services.
- App switcher.
- WindowManager migration.
- PrometeuHub redesign.
- Game suspend/resume UX.
- ProcessManager owning VM execution.
- Collection/removal of closed or stopped entities.
## Execution Plan
1. Add lifecycle types.
- Create a lifecycle module or colocate the types under
`crates/console/prometeu-system/src/os/`.
- Define `LifecycleOperation` with `SetForeground`, `Suspend`, `Resume`,
`Close`, and `Crash`.
- Define `LifecycleError` with `TaskNotFound(TaskId)`,
`ProcessNotFound(ProcessId)`, and `InvalidTransition { task_id, from,
operation }`.
- Re-export the types through `prometeu-system` only if the existing public
module style requires it.
2. Add the `SystemOS` coordination helpers.
- Target file: `crates/console/prometeu-system/src/os/system_os.rs`.
- Resolve the task first through `task_manager`.
- Extract the task's associated `ProcessId`.
- Validate that the process exists before mutating state.
- Return typed errors instead of `bool`.
3. Implement first-wave operations.
- `set_foreground_task`: call `task_manager.set_foreground(task_id)` and
`process_manager.mark_running(process_id)`.
- `suspend_task`: set `TaskState::Suspended` and
`ProcessState::Suspended`.
- `resume_task`: require a suspended task, then set
`TaskState::Foreground` and `ProcessState::Running`.
- `close_task`: set `TaskState::Closed` and `ProcessState::Stopped`.
- `crash_task`: set `TaskState::Crashed` and `ProcessState::Crashed`.
4. Keep manager APIs mechanical.
- Target files:
`crates/console/prometeu-system/src/services/task/task_manager.rs` and
`crates/console/prometeu-system/src/services/process/process_manager.rs`.
- Do not remove existing manager methods in this plan.
- Add only narrow helpers if needed to support the `SystemOS` API cleanly.
5. Update task creation to use the lifecycle API internally.
- In `SystemOS::create_vm_game_task`, `create_vm_shell_task`, and
`create_native_shell_task`, replace direct foreground manager calls with
`set_foreground_task`.
- Keep the constructors returning `TaskId`; handle impossible internal
errors with explicit debug/assert behavior or an internal helper that
cannot fail after creation.
## Acceptance Criteria
- `SystemOS` exposes all five first-wave lifecycle methods from `DEC-0025`.
- All five methods coordinate both task and process state.
- Missing task returns `LifecycleError::TaskNotFound`.
- Missing associated process returns `LifecycleError::ProcessNotFound`.
- Invalid resume from a non-suspended task returns `InvalidTransition`.
- `Background` is not exposed through a new lifecycle API.
- Closed and stopped entities are not removed by `close_task`.
## Tests / Validation
- Add or update unit tests in `prometeu-system` for each lifecycle mapping.
- Add tests for missing task, missing process, and invalid resume transition.
- Run the affected Rust test suite for `prometeu-system`.
## Risks
- Existing direct manager access is public enough that callsites may keep using
it. This plan does not remove those methods; enforcement continues in
`PLN-0056`.
- `TaskManager::set_foreground` currently moves the previous foreground task to
`Background`. Since `Background` is out of first-wave semantics, tests must
avoid treating that transition as normative lifecycle policy.
@@ -0,0 +1,119 @@
---
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.
@@ -0,0 +1,110 @@
---
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.