prometeu-runtime/discussion/workflow/decisions/DEC-0025-systemos-lifecycle-authority-for-tasks-and-processes.md

---
id: DEC-0025
ticket: system-os-lifecycle-process-task-contract
title: SystemOS Lifecycle Authority for Tasks and Processes
status: accepted
created: 2026-05-15
ref_agenda: AGD-0032
tags: [runtime, os, lifecycle, process, task, shell, firmware]
---

## Status

Accepted. Esta decisão foi aceita em 2026-05-15 e passa a ser referência
normativa para a primeira wave de lifecycle de `Task` e `Process` no
`SystemOS`.

## Contexto

`SystemOS` já agrega serviços centrais do Prometeu OS, incluindo runtime VM,
processos e tasks. A arquitetura anterior ainda permitia que firmware,
`TaskManager` e `ProcessManager` decidissem transições de lifecycle de forma
distribuída.

Esse arranjo é insuficiente para um console OS: `Task` representa presença
navegável e experiência do usuário, enquanto `Process` representa execução
técnica. Essas duas dimensões precisam mudar juntas por uma autoridade
semântica única.

`DEC-0024` já separou ownership/layout de serviços do `SystemOS`. Esta decisão
é focada apenas em lifecycle de `Task`/`Process` e não reabre a migração de
serviços, `WindowManager`, Hub ou ownership da VM.

`AppMode::System` já foi renomeado para `AppMode::Shell`. O contrato público
fica:

- `AppMode::Game`: cartucho executado como jogo/session fullscreen.
- `AppMode::Shell`: cartucho executado como app gerenciado pela Shell do
  Prometeu OS.

## Decisao

`SystemOS` SHALL ser a autoridade normativa de lifecycle para `Task` e
`Process`.

`TaskManager` e `ProcessManager` SHALL continuar existindo como mecanismos
internos de armazenamento e transição local, mas MUST NOT ser a API semântica
principal para lifecycle coordenado. Firmware e outros chamadores MUST delegate
transições semânticas de lifecycle para `SystemOS`.

A primeira wave de lifecycle SHALL expor o contrato mínimo:

```text
set_foreground_task(task_id)
suspend_task(task_id)
resume_task(task_id)
close_task(task_id)
crash_task(task_id, report?)
```

Essas operações SHALL coordenar `TaskState` e `ProcessState` juntos.

O mapeamento normativo inicial SHALL ser:

```text
TaskState::Foreground -> ProcessState::Running
TaskState::Suspended  -> ProcessState::Suspended
TaskState::Closed     -> ProcessState::Stopped
TaskState::Crashed    -> ProcessState::Crashed
```

`Background` SHALL remain reserved and MUST NOT guide any public lifecycle API
in the first wave.

`resume_task` SHALL mean resuming active user-perceived execution. In this first
wave, it MUST move a suspended task to `TaskState::Foreground` and its associated
process to `ProcessState::Running`.

`close_task` SHALL mark task/process state only. It MUST NOT remove task or
process entities immediately. Collection of closed/stopped entities is a future
separate operation.

`crash_task` SHALL be the semantic crash operation for a task. The first wave MAY
only coordinate `TaskState::Crashed` and `ProcessState::Crashed`, but the
signature SHOULD either accept or remain compatible with a future `CrashReport`
handoff to diagnostics/logging.

`GameRunningStep` SHALL keep the strong invariant that an active game execution
step only supports a game task in `TaskState::Foreground`. In this wave, any
non-foreground game task observed by `GameRunningStep` is invalid and should
produce clear diagnostic/crash behavior rather than silently running frames.

## Rationale

Centralizing lifecycle in `SystemOS` prevents firmware from becoming the de
facto OS policy layer. Firmware should remain a boot/execution state machine; it
should not know how to update `TaskState` and `ProcessState` in lockstep.

Keeping `TaskManager` and `ProcessManager` as internal mechanisms preserves
simple storage and local transition responsibilities while giving the OS a
single semantic boundary for suspend, resume, close, crash and foreground
selection.

Leaving `Background` out of the first wave avoids freezing an incomplete model
for docked apps, background services, non-focused shell apps or capability-gated
execution. The reserved enum state can remain, but no normative public lifecycle
API should depend on it yet.

Making `resume_task` return to `Foreground` keeps the first contract simple and
matches the user-perceived meaning of resume. Future background wake/service
semantics should be introduced as separate concepts rather than overloading
`resume_task`.

Marking closed/stopped entities instead of removing them immediately preserves
room for diagnostics, crash handling, system UI history and later collection
policy.

## Invariantes / Contrato

- `SystemOS` MUST coordinate lifecycle operations that affect both task and
  process state.
- Firmware MUST NOT call separate task/process manager transitions to implement
  semantic lifecycle operations such as suspend, resume, close or crash.
- `set_foreground_task(task_id)` MUST set the task to `TaskState::Foreground`
  and its associated process to `ProcessState::Running`.
- `suspend_task(task_id)` MUST set the task to `TaskState::Suspended` and its
  associated process to `ProcessState::Suspended`.
- `resume_task(task_id)` MUST move from suspended user-visible execution back to
  foreground execution: `TaskState::Foreground` and `ProcessState::Running`.
- `close_task(task_id)` MUST set `TaskState::Closed` and
  `ProcessState::Stopped`.
- `crash_task(task_id, report?)` MUST set `TaskState::Crashed` and
  `ProcessState::Crashed`.
- A missing task MUST return a typed lifecycle error such as
  `LifecycleError::TaskNotFound(TaskId)`.
- A task whose associated process is missing MUST return a typed lifecycle error
  such as `LifecycleError::ProcessNotFound(ProcessId)`.
- Invalid lifecycle transitions SHOULD return a typed error carrying the task,
  source state and requested operation.
- `Background` MUST NOT have normative first-wave semantics.
- This decision MUST NOT move `WindowManager`, redesign `PrometeuHub`, introduce
  background services, implement docking, implement app switching, or make
  `ProcessManager` own the VM.

The expected first-wave error shape is:

```rust
pub enum LifecycleError {
    TaskNotFound(TaskId),
    ProcessNotFound(ProcessId),
    InvalidTransition {
        task_id: TaskId,
        from: TaskState,
        operation: LifecycleOperation,
    },
}
```

`LifecycleOperation` SHOULD identify at least:

```text
SetForeground
Suspend
Resume
Close
Crash
```

## Impactos

- `prometeu-system` must expose lifecycle methods on `SystemOS`.
- `TaskManager` and `ProcessManager` may need smaller internal transition
  helpers, but not public semantic ownership of lifecycle.
- Firmware code should call `system_os.suspend_task(...)`,
  `system_os.resume_task(...)`, `system_os.close_task(...)`,
  `system_os.crash_task(...)` and `system_os.set_foreground_task(...)` instead
  of coordinating task/process managers directly.
- Tests should move lifecycle assertions to the `SystemOS` level.
- Specs do not need to change before the first code plan unless the lifecycle
  API is promoted to a public external contract.
- `DEC-0024` remains valid and complementary; ownership/layout work can execute
  in parallel and does not block this first lifecycle wave.

## Referencias

- Agenda: `AGD-0032`
- Related decision: `DEC-0024`

## Propagacao Necessaria

- Plan: create `PLAN-0032-A: SystemOS Lifecycle API`.
- Code: update `prometeu-system` `SystemOS`, task/process lifecycle helpers,
  firmware callsites if they currently coordinate managers directly, and unit
  tests.
- Tests: add unit coverage for successful lifecycle mappings, missing task,
  missing process and invalid transition handling.
- Discussion: keep `Background` reserved for a future agenda covering dock,
  services, non-focused shell apps and capability-gated execution.
- Learn: after implementation is complete, write or update lessons only from the
  published state.

## Revisao

- 2026-05-15: Initial accepted decision from `AGD-0032`.