prometeu-runtime/discussion/workflow/plans/PLN-0146-consolidate-lifecycle-process-lookup-helpers.md

id	ticket	title	status	created	ref_decisions	tags
PLN-0146	foreground-stack-game-pause-shell-vm-backed	Consolidate Lifecycle Process Lookup Helpers	done	2026-07-04	DEC-0037	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.