Intrepid/prometeu-runtime
Intrepid/prometeu-runtime
4
0
Fork 0
Code Pull Requests Activity
prometeu-runtime/discussion/workflow/plans/PLN-0055-systemos-lifecycle-core-api.md

4.6 KiB
Raw Blame History

id ticket title status created ref_decisions tags
PLN-0055 system-os-lifecycle-process-task-contract SystemOS Lifecycle Core API done 2026-05-15
DEC-0025
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.