prometeu-runtime/discussion/workflow/agendas/AGD-0032-system-os-lifecycle-process-task-contract.md

---
id: AGD-0032
ticket: system-os-lifecycle-process-task-contract
title: Agenda - SystemOS Lifecycle, Process and Task Contract
status: open
created: 2026-05-14
resolved:
decision:
tags: [runtime, os, lifecycle, process, task, shell, firmware]
---

# Agenda - SystemOS Lifecycle, Process and Task Contract

## Contexto

Prometeu deu o primeiro passo concreto para deixar de ser apenas um firmware que
roda cartuchos e passar a ter um modelo de sistema operacional de console.

Antes, o cartucho era representado quase exclusivamente pelo fluxo do firmware:

```text
LoadCartridgeStep
    -> initialize_vm
    -> GameRunningStep / SystemRunningStep
```

Esse modelo permitia executar jogos e apps de sistema, mas não dava ao OS uma
entidade própria para representar processo, task, foreground, background,
suspensão, fechamento ou crash. O firmware sabia que algo estava rodando; o
Prometeu OS ainda não possuía um contrato próprio de execução e presença de
usuário.

Agora existe um `SystemOS` em `prometeu-system`, agregando:

```text
SystemOS
    VirtualMachineRuntime
    ProcessManager
    TaskManager
```

Isso estabelece uma fronteira importante: a VM continua sendo a VM, e não a dona
do sistema. O `SystemOS` passa a ser o lugar natural para concentrar serviços de
OS, lifecycle, permissões e coordenação entre execução técnica e experiência de
usuário.

Os conceitos iniciais são:

```text
Process
    execução técnica:
    VmGame, VmShell, NativeShell

Task
    presença navegável do usuário:
    Game ou Shell em Foreground, Background, Suspended, Closed ou Crashed
```

O carregamento de cartucho começou a registrar entidades de sistema:

```text
AppMode::Game
    -> cria processo VmGame
    -> cria task Game
    -> marca task como Foreground
    -> entra em GameRunningStep com TaskId

AppMode::System
    -> cria processo VmShell
    -> cria task Shell
    -> marca task como Foreground
    -> entra em SystemRunningStep com TaskId
```

`GameRunningStep` agora executa uma task específica e valida se ela ainda está em
`Foreground` antes de avançar o frame. Essa é a primeira ponte real entre o
firmware atual e um OS com lifecycle.

## Problema

O código já tem os primeiros tipos e fluxos, mas o contrato arquitetural ainda
não está fechado:

- quem é a autoridade para mover uma task entre `Foreground`, `Background`,
  `Suspended`, `Closed` e `Crashed`;
- como `TaskState` e `ProcessState` devem evoluir juntos;
- quais transições pertencem ao `SystemOS` e quais continuam nos managers
  internos;
- como o firmware deve reagir quando uma task deixa de estar executável;
- quando o `WindowManager` deixa de ser parte do `PrometeuHub` e vira serviço
  real do OS;
- se o nome público do perfil de sistema deve continuar `System` ou convergir
  para `Shell` no contrato de cartucho/runtime.

Sem esse contrato, o risco é o sistema crescer em duas direções ruins:

1. o firmware continuar acumulando decisões de lifecycle que pertencem ao OS;
2. `TaskManager`, `ProcessManager`, `PrometeuHub` e `VirtualMachineRuntime`
   criarem regras paralelas e inconsistentes.

## Pontos Criticos

- `SystemOS` deve ser a API de coordenação de lifecycle, não apenas um struct
  agregador de managers.
- `ProcessManager` e `TaskManager` devem continuar guardando estado local, mas
  não devem, sozinhos, definir o contrato semântico completo entre task e
  processo.
- `Task` representa presença navegável e foco do usuário; `Process` representa
  execução técnica.
- `Foreground` não é apenas uma flag visual: no modelo atual, ele autoriza o
  `GameRunningStep` a executar frame.
- `Suspended`, `Closed` e `Crashed` precisam mover `TaskState` e `ProcessState`
  de forma coordenada.
- `Background` precisa ser distinguido de `Suspended`: background pode existir
  como presença navegável não focada, mas ainda não implica que o processo possa
  executar.
- `PrometeuHub` deve evoluir para Shell/Home visual, não permanecer como
  sinônimo de OS.
- `WindowManager` provavelmente deve virar serviço de `SystemOS`, mas talvez
  isso precise esperar a primeira API de lifecycle estabilizar.
- A inspiração de UX é console/Switch; a inspiração interna é mais Android-like:
  processos, tasks, lifecycle, surfaces/janelas, serviços e permissões.

## Dependencia / Agenda Paralela

`AGD-0033` trata a limpeza de ownership e layout de serviços do `SystemOS` antes
ou em paralelo a esta agenda.

Essa separação é intencional: `AGD-0032` deve decidir lifecycle de
`Task`/`Process`, enquanto `AGD-0033` deve decidir se `VirtualMachineRuntime`,
`LogService`, `WindowManager` e outros serviços pertencem ao root, ao Hub ou à
camada `services` do `SystemOS`.

Se `AGD-0033` concluir que `LogService` e outros serviços precisam sair da VM
antes do lifecycle, a decisão de `AGD-0032` deve tratar essa mudança como
pré-requisito de implementação, não como parte do contrato de lifecycle em si.

## Opcoes

### Opcao A - Manter lifecycle distribuido nos managers e no firmware

**Abordagem:**
`TaskManager` muda tasks, `ProcessManager` muda processos, e o firmware chama
ambos diretamente quando precisar.

**Vantagens:**
- menor mudança imediata;
- preserva managers simples;
- fácil de encaixar incrementalmente no código atual.

**Custos / Riscos:**
- espalha regra de lifecycle por vários chamadores;
- torna mais provável esquecer de mover `ProcessState` junto com `TaskState`;
- mantém firmware como conhecedor de detalhes internos do OS;
- dificulta introduzir Shell/Home, suspensão e retomada sem duplicação.

**Manutenibilidade:**
Aceitável no curto prazo, fraca como modelo de OS.

### Opcao B - Centralizar lifecycle no SystemOS

**Abordagem:**
`SystemOS` vira a API semântica para operações como:

```text
suspend_task
resume_task
close_task
crash_task
foreground_task
background_task
```

Essas operações coordenam `TaskManager` e `ProcessManager` juntas.

Exemplos de contrato:

```text
jogo rodando:
    TaskState::Foreground
    ProcessState::Running

jogo suspenso:
    TaskState::Suspended
    ProcessState::Suspended

jogo fechado:
    TaskState::Closed
    ProcessState::Stopped

jogo crashado:
    TaskState::Crashed
    ProcessState::Crashed
```

**Vantagens:**
- estabelece `SystemOS` como autoridade de lifecycle;
- mantém firmware mais fino;
- reduz inconsistência entre task e processo;
- cria base natural para Home/Shell, suspend/resume, close/crash e permissões.

**Custos / Riscos:**
- exige definir transições inválidas e retorno/erro de cada operação;
- pode expor API cedo demais se tentarmos modelar todas as regras finais agora;
- precisa decidir se `Background` implica processo running, suspended ou apenas
  presença não focada.

**Manutenibilidade:**
Forte. É o caminho mais alinhado com transformar Prometeu em console OS.

### Opcao C - Promover WindowManager a servico do OS antes do lifecycle

**Abordagem:**
Mover primeiro o `WindowManager` para dentro de `SystemOS` e depois organizar
tasks/processos em torno de janelas/surfaces.

**Vantagens:**
- aproxima rapidamente o modelo de Shell/Home e apps gerenciados;
- evita `PrometeuHub` continuar parecendo o sistema inteiro;
- abre caminho para surfaces e composição de apps de sistema.

**Custos / Riscos:**
- pode misturar lifecycle de execução com lifecycle visual;
- força decisões de janela/surface antes de fechar Process/Task;
- pode congelar um WindowManager ainda experimental.

**Manutenibilidade:**
Boa como passo futuro, mas arriscada como próximo passo se o lifecycle base
ainda não estiver normativo.

## Sugestao / Recomendacao

A recomendação inicial é seguir a **Opção B**.

O próximo contrato deve declarar `SystemOS` como autoridade para lifecycle de
tasks e processos. `TaskManager` e `ProcessManager` continuam existindo, mas
devem ser mecanismos internos de armazenamento/transição, não a API semântica
principal do sistema.

O primeiro corte deve ser pequeno:

- adicionar métodos de lifecycle em `SystemOS`;
- coordenar `TaskState` e `ProcessState` nesses métodos;
- definir comportamento para task inexistente e process inexistente;
- preservar `GameRunningStep` como consumidor de `TaskId`, validando
  foreground;
- evitar mover `WindowManager` neste mesmo corte.

O `WindowManager` deve ser a agenda/decisão seguinte: promovê-lo a serviço real
do sistema quando a base `Task/Process/Lifecycle` estiver fechada.

Também precisamos resolver a nomenclatura `System` versus `Shell`. O código e o
contrato anterior usam `AppMode::System`; a narrativa nova fala em
`AppMode::Shell`. A agenda deve decidir se:

- mantemos `AppMode::System` como perfil formal e usamos `Shell` como tipo de
  task/processo/UI; ou
- renomeamos o perfil público para `Shell`, com migração explícita.

Minha inclinação inicial é manter `AppMode::System` por compatibilidade de
contrato e usar `Shell` para a camada de UI/app gerenciado dentro do OS.

## Perguntas em Aberto

- [ ] `SystemOS` deve expor `suspend_task`, `resume_task`, `close_task` e
  `crash_task` já no próximo corte?
- [ ] `foreground_task` e `background_task` devem ser operações explícitas do
  `SystemOS`, ou apenas detalhe do `TaskManager`?
- [ ] Qual é a semântica exata de `Background`: processo ainda `Running`,
  processo `Suspended`, ou estado de presença sem garantia de execução?
- [ ] `resume_task` deve sempre mover a task para `Foreground`, ou pode retomar
  para `Background`?
- [ ] O que acontece quando a task existe mas o processo associado não existe?
- [ ] `close_task` remove imediatamente entidades fechadas ou apenas marca
  `Closed`/`Stopped` para coleta posterior?
- [ ] `crash_task` deve receber/armazenar `CrashReport`, ou isso fica em outro
  serviço de diagnóstico?
- [ ] `GameRunningStep` deve transicionar para Hub/Home quando sua task deixa de
  estar `Foreground`, ou apenas não executar frame?
- [ ] O perfil de manifesto continua `AppMode::System`, ou abrimos uma migração
  formal para `AppMode::Shell`?
- [ ] A decisão de ownership/layout em `AGD-0033` deve ser pré-requisito para o
  primeiro plan de lifecycle, ou pode ser executada em paralelo?

## Criterio para Encerrar

Esta agenda pode virar decisão quando houver resposta para:

- qual entidade é autoridade normativa de lifecycle;
- quais métodos mínimos entram no primeiro contrato de `SystemOS`;
- como cada método move `TaskState` e `ProcessState`;
- qual semântica inicial de `Background` e `Suspended`;
- como o firmware deve reagir a task não-foreground/não-executável;
- qual nomenclatura será usada para `System` versus `Shell`;
- como a dependência com `AGD-0033` será tratada nos plans.

## Proximo Passo

Revisar esta agenda e fechar as perguntas principais. Se a direção for aceita,
o próximo estágio deve ser uma decisão normativa para `SystemOS` como autoridade
de lifecycle de `Task`/`Process`, seguida de uma família curta de plans para
implementação.