prometeu-runtime/discussion/lessons/DSC-0032-system-os-lifecycle-process-task-contract/LSN-0041-systemos-lifecycle-authority.md

id	ticket	title	created	tags
LSN-0041	system-os-lifecycle-process-task-contract	SystemOS Lifecycle Authority	2026-05-15	runtime os lifecycle process task firmware

Context

Prometeu moved from firmware-driven cartridge execution toward a console OS model with explicit tasks and processes. That created two related but distinct state dimensions:

• TaskState: user-visible presence and navigation.
• ProcessState: technical execution.

Letting firmware, TaskManager, and ProcessManager each mutate those states independently would make suspend, resume, close and crash behavior drift over time.

Key Decisions

SystemOS owns lifecycle semantics

What: SystemOS became the semantic lifecycle authority for task/process coordination. TaskManager and ProcessManager remain storage and simple transition mechanisms, not the public lifecycle policy boundary.

Why: Lifecycle operations must update user-visible and technical execution state together. A firmware call sequence like "mark task suspended, then mark process suspended" is too easy to duplicate, forget or partially apply.

Trade-offs: This adds an OS-level API layer, but it keeps lifecycle policy in one place and makes future suspend/resume behavior easier to reason about.

The first lifecycle wave is intentionally small

What: The first wave covers only foreground, suspend, resume, close and crash:

Foreground -> Running
Suspended  -> Suspended
Closed     -> Stopped
Crashed    -> Crashed

Background remains reserved and non-normative.

Why: Background execution has unresolved implications around docked apps, services, app switching and capabilities. Keeping it out of the first contract prevents premature semantics from leaking into firmware and tests.

Trade-offs: The model cannot yet express every desired app lifecycle state, but it gives the runtime a stable base without freezing background behavior too early.

Patterns and Algorithms

Use SystemOS operations for semantic lifecycle changes:

set_foreground_task
suspend_task
resume_task
close_task
crash_task

Each operation should resolve the task, validate its associated process, and return a typed lifecycle error for missing or invalid state instead of a bare boolean.

resume_task in this wave means "return to active foreground execution", not "wake in any possible state". If a future service needs to wake without foregrounding, it should be modeled separately.

Pitfalls

• Do not let firmware coordinate task and process state manually.
• Do not treat Background as semantically defined just because the enum value exists.
• Do not remove closed/stopped entities as part of close_task; marking and collection are different responsibilities.
• Do not hide lifecycle policy inside manager-level tests. Domain behavior belongs at the OS lifecycle boundary.

Takeaways

• TaskState and ProcessState are separate concepts, but lifecycle operations must coordinate them atomically at the OS boundary.
• A small lifecycle contract is better than a broad but ambiguous one.
• Reserved states are useful only if callers are prevented from treating them as normative before their semantics are decided.