--- id: AGD-0032 ticket: system-os-lifecycle-process-task-contract title: Agenda - SystemOS Lifecycle, Process and Task Contract status: accepted created: 2026-05-14 resolved: 2026-05-15 decision: DEC-0025 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::Shell -> 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. `AppMode::System` já foi renomeado para `AppMode::Shell`. A nomenclatura pública fica alinhada com o modelo atual: `AppMode::Game` executa cartuchos como jogo/session fullscreen, enquanto `AppMode::Shell` executa cartuchos como apps gerenciados pela Shell do Prometeu OS. ## Perguntas em Aberto - [x] `SystemOS` deve expor `suspend_task`, `resume_task`, `close_task` e `crash_task` já no próximo corte? Sim. Eles são a próxima API semântica de lifecycle e evitam que firmware ou outros chamadores manipulem `TaskManager` e `ProcessManager` separadamente. - [x] `foreground_task` e `background_task` devem ser operações explícitas do `SystemOS`, ou apenas detalhe do `TaskManager`? `set_foreground_task(task_id)` deve ser operação explícita do `SystemOS`. `background_task` fica fora da primeira wave. - [x] Qual é a semântica exata de `Background`: processo ainda `Running`, processo `Suspended`, ou estado de presença sem garantia de execução? Fora de escopo nesta wave. `Background` permanece estado reservado sem semântica normativa no primeiro contrato. - [x] `resume_task` deve sempre mover a task para `Foreground`, ou pode retomar para `Background`? Nesta wave, `resume_task` sempre move para `Foreground` e move o processo associado para `Running`. - [x] O que acontece quando a task existe mas o processo associado não existe? Isso é erro de lifecycle e deve retornar erro tipado, não `bool`. - [x] `close_task` remove imediatamente entidades fechadas ou apenas marca `Closed`/`Stopped` para coleta posterior? Apenas marca `TaskState::Closed` e `ProcessState::Stopped`; coleta é operação futura separada. - [x] `crash_task` deve receber/armazenar `CrashReport`, ou isso fica em outro serviço de diagnóstico? A operação deve aceitar ou preparar o contrato para `CrashReport`, mas a primeira wave pode apenas coordenar estados e deixar o armazenamento para diagnóstico/logging futuro. - [x] `GameRunningStep` deve transicionar para Hub/Home quando sua task deixa de estar `Foreground`, ou apenas não executar frame? Nesta wave, mantém a invariant forte: `GameRunningStep` só suporta game task em `Foreground`; outro estado é inválido e deve gerar diagnóstico/crash claro. - [x] O perfil de manifesto continua `AppMode::System`, ou abrimos uma migração formal para `AppMode::Shell`? Resolvido: `AppMode::System` já virou `AppMode::Shell`. - [x] 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? Pode executar em paralelo e não bloqueia esta wave. O plan de lifecycle deve evitar mover `WindowManager`, `VirtualMachineRuntime`, Hub ou background services. ## Resolucao A agenda fecha pela **Opcao B**: centralizar lifecycle no `SystemOS`. `SystemOS` deixa de ser apenas um agregador de serviços e passa a ser a autoridade normativa para coordenar `TaskState` e `ProcessState`. `TaskManager` e `ProcessManager` continuam existindo, mas como mecanismos internos de armazenamento e transição simples. O firmware não deve decidir diretamente como task e processo mudam juntos. A primeira wave deve cobrir apenas: - `set_foreground_task(task_id)` - `suspend_task(task_id)` - `resume_task(task_id)` - `close_task(task_id)` - `crash_task(task_id, report?)` O mapeamento inicial é: ```text TaskState::Foreground -> ProcessState::Running TaskState::Suspended -> ProcessState::Suspended TaskState::Closed -> ProcessState::Stopped TaskState::Crashed -> ProcessState::Crashed ``` `Background` permanece reservado e explicitamente fora da primeira wave. O primeiro plan recomendado é `PLAN-0032-A: SystemOS Lifecycle API`, com escopo limitado a erro tipado, métodos de lifecycle em `SystemOS`, coordenação de `TaskState`/`ProcessState`, testes unitários no nível `SystemOS` e nenhuma mudança em `WindowManager`, `PrometeuHub`, background services ou UX completa de suspensão/retomada. ## 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.