---
id: LSN-0041
ticket: system-os-lifecycle-process-task-contract
title: SystemOS Lifecycle Authority
created: 2026-05-15
tags: [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:

```text
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:

```text
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.