SystemOS Service Ownership and Module Layout

This commit is contained in:
2026-05-14 18:24:29 +01:00
parent c1f5691cd8
commit cccbd48e57
8 changed files with 1008 additions and 1 deletions
@@ -0,0 +1,302 @@
---
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.
@@ -0,0 +1,199 @@
---
id: AGD-0033
ticket: system-os-service-ownership-and-module-layout
title: Agenda - SystemOS Service Ownership and Module Layout
status: accepted
created: 2026-05-14
resolved:
decision:
tags: [runtime, os, services, module-layout, vm, window-manager, logging]
---
# Agenda - SystemOS Service Ownership and Module Layout
## Contexto
Antes de avançar o contrato de lifecycle do `SystemOS`, há uma limpeza de
fronteira que precisa ser discutida separadamente.
O `SystemOS` começou como agregador de:
```text
SystemOS
VirtualMachineRuntime
ProcessManager
TaskManager
```
Mas o código ainda carrega sinais do modelo anterior, em que a VM concentrava
coisas que hoje parecem serviços de sistema. O exemplo mais claro é
`LogService` dentro de `VirtualMachineRuntime`. A mesma dúvida aparece em torno
de outros serviços e estados associados a filesystem, memcard, diagnóstico,
telemetria e identidade do cartucho.
Há também uma questão de layout:
- `VirtualMachineRuntime` está no root de `prometeu-system`, embora conceitualmente
agora seja um serviço do OS;
- `WindowManager` está dentro de `programs/prometeu_hub`, embora a direção de
arquitetura seja transformar o Hub em Shell/Home visual, não no sistema;
- `ProcessManager` e `TaskManager` já vivem em `services`, o que torna a posição
da VM e do WindowManager inconsistente com o desenho novo.
## Problema
Misturar ownership de serviços com execução da VM dificulta a evolução do OS.
Se `VirtualMachineRuntime` continuar parecendo dona de logging, filesystem,
memcard, diagnóstico e janela, o `SystemOS` vira apenas um wrapper, e não a
autoridade natural para coordenar serviços do console.
Ao mesmo tempo, nem tudo aqui é puramente mecânico:
- mover arquivos para `services` pode ser uma alteração sem mudança funcional;
- mover `LogService` para `SystemOS` altera ownership e pode exigir uma API de
serviço ou passagem explícita de dependência para a VM;
- promover `WindowManager` a serviço do OS antecipa uma fronteira arquitetural,
mesmo que a implementação continue mínima.
Por isso, este assunto não deve ser escondido dentro da agenda de lifecycle
(`AGD-0032`). Ele é uma agenda de pré-requisito ou paralela: primeiro precisamos
limpar a fronteira entre "VM como executor" e "OS como dono de serviços".
## Pontos Criticos
- `VirtualMachineRuntime` deve representar execução VM, não ser o container
geral de serviços do sistema.
- `SystemOS` deve ser o lugar natural para serviços compartilhados por jogos,
Shell/Home, firmware e processos nativos futuros.
- `LogService` provavelmente pertence ao `SystemOS`, mas a forma de acesso pela
VM precisa respeitar as restrições de borrow e o desenho de `NativeInterface`.
- `VirtualFS` e `MemcardService` também parecem serviços de OS, mas movê-los no
mesmo corte pode aumentar demais o risco.
- `WindowManager` deve sair de `PrometeuHub` porque o Hub deve virar consumidor
visual do OS, não proprietário de serviço de janela.
- A mudança de layout de módulo deve preservar comportamento, mas não precisa
preservar caminhos antigos de import; callsites devem ser atualizados
diretamente.
- A decisão precisa separar explicitamente "relocação de módulo" de "mudança de
ownership".
## Opcoes
### Opcao A - Agregar tudo na agenda de lifecycle
**Abordagem:**
Usar `AGD-0032` para decidir lifecycle, ownership de serviços, layout de módulos
e promoção do `WindowManager`.
**Vantagens:**
- uma única discussão cobre toda a direção do `SystemOS`;
- menos artefatos de workflow.
**Custos / Riscos:**
- mistura semântica de lifecycle com limpeza estrutural;
- aumenta a chance de uma decisão grande demais;
- dificulta transformar a discussão em plans pequenos e verificáveis;
- pode bloquear lifecycle por causa de detalhes de módulo e borrow.
### Opcao B - Separar uma agenda de service ownership e layout
**Abordagem:**
Manter `AGD-0032` focada em lifecycle de `Task`/`Process` e usar esta agenda
para decidir onde vivem os serviços do OS, quais módulos devem ir para
`services`, e quais extrações são mecânicas ou semânticas.
**Vantagens:**
- mantém a agenda principal limpa;
- permite um primeiro plan mecânico de relocação sem reabrir lifecycle;
- torna explícito que `LogService` sair da VM é mudança de ownership;
- cria base melhor para promover `WindowManager` sem confundir Hub e OS.
**Custos / Riscos:**
- cria uma dependência a mais antes da implementação do lifecycle;
- pode revelar que alguns serviços exigem desenho de API antes do refactor;
- exige cuidado para atualizar callsites diretamente sem deixar caminhos antigos
exportados.
### Opcao C - Fazer apenas os moves mecanicos direto no codigo
**Abordagem:**
Mover `VirtualMachineRuntime` e `WindowManager` para `services` sem decisão
formal, deixando `LogService` para depois.
**Vantagens:**
- rápido;
- baixo risco se for realmente só path/reexport;
- reduz ruído visual do layout atual.
**Custos / Riscos:**
- não resolve a dúvida central de ownership;
- pode mascarar uma decisão arquitetural como refactor mecânico;
- viola a política do repositório se a mudança alterar fronteiras sem agenda e
decisão.
## Sugestao / Recomendacao
A recomendação é seguir a **Opção B**.
Esta agenda deve ser separada da `AGD-0032`, mas tratada como pré-requisito ou
agenda paralela para ela. O primeiro contrato deve dividir o trabalho em dois
tipos:
1. **Relocação mecânica sem mudança funcional**
- mover `VirtualMachineRuntime` para `services`;
- mover `WindowManager` para `services`;
- não manter reexports ou aliases de compatibilidade para os caminhos antigos;
- atualizar callsites diretamente para os caminhos novos;
- provar que o comportamento não mudou.
2. **Correção de ownership de serviços**
- mover `LogService` para `SystemOS` se aceitarmos que logging é serviço do
OS;
- decidir se `VirtualFS`, `MemcardService`, diagnóstico, telemetria e
certificação ficam na VM, no OS, ou em serviços próprios;
- definir como a VM acessa serviços de OS sem voltar a ser dona deles.
Para o primeiro corte, a inclinação é:
- `VirtualMachineRuntime` deve ficar em `services`, como serviço de execução VM;
- `WindowManager` deve ficar em `services`, mesmo que ainda seja mínimo;
- `LogService` deve ser tratado como serviço de `SystemOS`, não detalhe interno
da VM;
- `VirtualFS` e `MemcardService` devem ser avaliados em seguida, sem mover tudo
junto automaticamente.
## Perguntas em Aberto
- [x] O path deve ser `services/vm_runtime` ou
`services/virtual_machine_runtime`? vm_runtime
- [x] `VirtualMachineRuntime` continua sendo o nome correto depois de virar
serviço, ou devemos introduzir um nome menor apenas no módulo? Podemos manter o mesmo nome
- [x] `LogService` deve sair da VM no mesmo plan do move mecânico, ou em um
plan separado de ownership? pode ser em um plan separado
- [x] A VM deve receber referência explícita ao logging do `SystemOS`, ou deve
chamar uma API de serviço mais estreita? A VM pode ter uma referência explícita ao logging do `SystemOS` para seu uso
- [x] `VirtualFS` e `MemcardService` pertencem ao `SystemOS` já, ou continuam na
VM até existir uma camada de permissões e mount por processo? podemos move-los para systemos jah
- [x] `WindowManager` deve virar campo do `SystemOS` imediatamente, ou primeiro
apenas sair de `PrometeuHub` em termos de módulo? eu diria que ele jah deve nascer em system os a partir de jah, mesmo que sem implementar nada
- [x] O `PrometeuHub` deve continuar expondo `window_manager` enquanto a Shell
visual ainda depende dele, ou isso deve ser mediado pelo `SystemOS` desde já? o prometeu hub eh um shell especial, ou seja, o window manager deve mediado pelo system os desde jah
## Criterio para Encerrar
Esta agenda pode virar decisão quando houver resposta para:
- quais serviços pertencem ao `SystemOS` no primeiro corte;
- qual layout canônico de módulo será usado em `services`;
- quais mudanças são relocação mecânica e quais são ownership semântico;
- como `VirtualMachineRuntime` acessa `LogService` depois da extração;
- se `WindowManager` será apenas movido de módulo ou também promovido a campo do
`SystemOS`;
- como os callsites serão atualizados sem reexports temporários.
## Proximo Passo
Revisar esta agenda antes de fechar `AGD-0032`. Se a direção for aceita, o
próximo estágio deve ser uma decisão curta para fronteira de serviços do
`SystemOS`, seguida de plans pequenos: primeiro relocação mecânica, depois
extração de ownership onde houver contrato suficiente.