120 lines
4.6 KiB
Markdown
120 lines
4.6 KiB
Markdown
---
|
|
id: PLN-0146
|
|
ticket: foreground-stack-game-pause-shell-vm-backed
|
|
title: Consolidate Lifecycle Process Lookup Helpers
|
|
status: done
|
|
created: 2026-07-04
|
|
ref_decisions: [DEC-0037]
|
|
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
|
|
---
|
|
|
|
## Briefing
|
|
|
|
`DEC-0037` depends on SystemOS lifecycle authority being internally
|
|
consistent. The lifecycle facade now exposes both process state and process kind
|
|
for a task so firmware can distinguish VM-backed Shell tasks from native Shell
|
|
tasks. Both accessors repeat the same task-to-process lookup pattern.
|
|
|
|
The duplication is small, but this facade is now part of the foreground
|
|
contract surface. Keeping lookup and error mapping in one place reduces the
|
|
chance that future lifecycle accessors drift in behavior.
|
|
|
|
## Objective
|
|
|
|
Consolidate task-to-process lookup in `LifecycleFacade` behind one private
|
|
helper, while preserving the public lifecycle facade behavior and errors.
|
|
|
|
## Dependencies
|
|
|
|
- Source decision: `DEC-0037`.
|
|
- Depends on the process/task authority from SystemOS lifecycle work.
|
|
- Can be implemented independently of `PLN-0145` and `PLN-0147`.
|
|
|
|
## Scope
|
|
|
|
Included:
|
|
|
|
- Add one private helper that resolves a `TaskId` to its backing process.
|
|
- Route `process_state_for_task` and `process_kind_for_task` through that
|
|
helper.
|
|
- Preserve `LifecycleError::TaskNotFound` and
|
|
`LifecycleError::ProcessNotFound` behavior exactly.
|
|
- Keep the current process/task manager ownership boundaries intact.
|
|
- Keep the current non-architectural cleanup in `set_foreground_task` if it is
|
|
still present in the working tree.
|
|
|
|
Excluded:
|
|
|
|
- No new public process manager API.
|
|
- No changes to task or process IDs.
|
|
- No changes to Shell/Game lifecycle semantics.
|
|
- No broader facade refactor outside lifecycle lookup.
|
|
|
|
## Non-Goals
|
|
|
|
- Do not expose raw process manager access through SystemOS.
|
|
- Do not change `ProcessKind` or `TaskKind` definitions.
|
|
- Do not alter foreground stack behavior.
|
|
|
|
## Execution Method
|
|
|
|
1. Add a private lifecycle lookup helper.
|
|
- What changes: add a private function near `process_id_for_task` that
|
|
returns a process reference for a `TaskId`.
|
|
- How it changes: the helper should call `process_id_for_task`, then
|
|
retrieve the process from `process_manager`, returning
|
|
`LifecycleError::ProcessNotFound(process_id)` if the process is missing.
|
|
- File(s): `crates/console/prometeu-system/src/os/facades/lifecycle.rs`.
|
|
|
|
2. Route state and kind accessors through the helper.
|
|
- What changes: `LifecycleFacade::process_state_for_task` and
|
|
`LifecycleFacade::process_kind_for_task` stop duplicating the process
|
|
manager lookup.
|
|
- How it changes: both methods call the helper and map the process reference
|
|
to `ProcessState` or `ProcessKind`.
|
|
- File(s): `crates/console/prometeu-system/src/os/facades/lifecycle.rs`.
|
|
|
|
3. Preserve existing foreground code cleanup.
|
|
- What changes: keep `set_foreground_task` as an expression-returning match
|
|
rather than using redundant `return` statements.
|
|
- How it changes: ensure formatting and clippy stay clean.
|
|
- File(s): `crates/console/prometeu-system/src/os/facades/lifecycle.rs`.
|
|
|
|
4. Tighten tests around lookup behavior.
|
|
- What changes: extend or keep tests proving VM Shell and native Shell
|
|
process kinds are observable through lifecycle.
|
|
- How it changes: add missing-task and missing-process coverage only if the
|
|
helper changes the observable path enough to justify it.
|
|
- File(s): `crates/console/prometeu-system/src/os/system_os.rs`.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] `process_state_for_task` and `process_kind_for_task` share one private
|
|
task-to-process lookup implementation.
|
|
- [ ] Missing task and missing process errors remain unchanged.
|
|
- [ ] Existing lifecycle tests continue to pass.
|
|
- [ ] Firmware can still distinguish `ProcessKind::VmShell` from
|
|
`ProcessKind::NativeShell`.
|
|
- [ ] Clippy reports no warnings for the touched crates.
|
|
|
|
## Tests
|
|
|
|
- Unit tests in `prometeu-system` for shell process kind lookup.
|
|
- Existing lifecycle missing task/process tests must continue to pass.
|
|
- Run `cargo test -p prometeu-system lifecycle process_kind`.
|
|
- Run `cargo test -p prometeu-firmware shell`.
|
|
- Run `cargo clippy -p prometeu-system -p prometeu-firmware --all-targets -- -D warnings`.
|
|
- Run `discussion validate`.
|
|
|
|
## Affected Artifacts
|
|
|
|
- `crates/console/prometeu-system/src/os/facades/lifecycle.rs`
|
|
- `crates/console/prometeu-system/src/os/system_os.rs`
|
|
|
|
## Risks
|
|
|
|
- Over-generalizing the helper could leak process manager concepts outside the
|
|
lifecycle facade. Keep it private and narrowly typed.
|
|
- This is intentionally small cleanup. It must not become a broad SystemOS
|
|
facade redesign.
|