---
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.