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

id	ticket	title	status	created	resolved	decision	tags
AGD-0032	system-os-lifecycle-process-task-contract	Agenda - SystemOS Lifecycle, Process and Task Contract	accepted	2026-05-14	2026-05-15	DEC-0025	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:

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:

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:

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:

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:

suspend_task
resume_task
close_task
crash_task
foreground_task
background_task

Essas operações coordenam TaskManager e ProcessManager juntas.

Exemplos de contrato:

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

• 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.
• 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.
• 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.
• 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.
• 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.
• 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.
• 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.
• 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.
• O perfil de manifesto continua AppMode::System, ou abrimos uma migração formal para AppMode::Shell? Resolvido: AppMode::System já virou 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? 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 é:

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.