---
id: DEC-0024
ticket: system-os-service-ownership-and-module-layout
title: SystemOS Service Ownership and Module Layout
status: accepted
created: 2026-05-14
ref_agenda: AGD-0033
tags: [runtime, os, services, module-layout, vm, window-manager, logging]
---

## Status

Accepted. Esta decisão foi aceita em 2026-05-14 e passa a ser referência
normativa para os plans de ownership e layout de serviços do `SystemOS`.

## Contexto

`SystemOS` está se tornando o dono dos serviços de console em
`prometeu-system`. O formato atual ainda deixa responsabilidades de OS dentro ou
perto de `VirtualMachineRuntime` e `PrometeuHub`:

- `VirtualMachineRuntime` vive no root do crate, embora agora seja um serviço de
  execução VM do OS;
- `LogService` é owned por `VirtualMachineRuntime`, embora logging seja serviço
  de observabilidade do OS;
- `VirtualFS` e `MemcardService` também ficam dentro de
  `VirtualMachineRuntime`, embora representem serviços do sistema;
- `WindowManager` vive em `programs/prometeu_hub`, embora `PrometeuHub` deva ser
  Shell/Home visual, não dono de serviços do OS.

Esta decisão é separada da `AGD-0032`, que trata lifecycle de `Task`/`Process`.
Aqui o contrato é ownership de serviços e layout de módulos.

## Decisao

`SystemOS` SHALL ser o owner dos serviços do Prometeu OS.

`VirtualMachineRuntime` SHALL representar somente execução VM. Ele MUST NOT ser
usado como container geral de serviços do sistema.

O layout canônico da VM runtime SHALL ser:

```text
crates/console/prometeu-system/src/services/vm_runtime/
```

O nome público do tipo SHALL continuar `VirtualMachineRuntime`.

`WindowManager` SHALL sair de `programs/prometeu_hub` e ir para a árvore
`services`. Ele SHALL ser owned ou mediado por `SystemOS` desde este estágio,
mesmo que a implementação continue mínima.

`PrometeuHub` SHALL ser tratado como uma Shell/Home especial. Ele MUST NOT ser
owner do window manager como serviço de OS. O acesso do Hub a window management
MUST passar por `SystemOS` ou por uma superfície mediada pelo OS.

`LogService` SHALL sair de `VirtualMachineRuntime` e virar serviço owned por
`SystemOS`. `VirtualMachineRuntime` MAY receber referência ou handle explícito
para o logging do OS quando precisar registrar eventos de execução VM, mas esse
acesso MUST NOT transformar a VM em owner de logging.

`VirtualFS` e `MemcardService` SHALL mover para `SystemOS` neste cleanup de
ownership. A VM pode continuar usando capacidades de filesystem e memcard, mas
o ownership pertence ao boundary do OS.

Esta decisão MUST NOT introduzir reexports ou aliases de compatibilidade para
os paths antigos. Os plans de implementação MUST atualizar callsites
diretamente. Novos imports MUST usar os paths canônicos de `services` e o
boundary de ownership do `SystemOS`.

## Rationale

O runtime está saindo de um runner de firmware para um console OS. Nesse modelo,
execução VM é um serviço do sistema, não o centro proprietário do sistema. Se
logging, filesystem, memcard, window management e futuramente lifecycle
continuarem dentro ou ao redor de `VirtualMachineRuntime`, a VM permanece como
owner de fato do OS.

Mover `VirtualMachineRuntime` para `services/vm_runtime` alinha layout com
arquitetura: execução VM é serviço, não root.

Mover `WindowManager` para `services` evita que `PrometeuHub` continue parecendo
o sistema inteiro. O Hub é Shell/Home e deve consumir serviços do OS.

Mover `LogService`, `VirtualFS` e `MemcardService` para `SystemOS` cria uma base
mais limpa para permissões, processo/task ownership, mount policy, diagnóstico e
mediação da Shell.

Não manter compatibilidade por reexport é aceitável agora porque esses paths são
internos e não há necessidade de janela longa de migração. Atualizar callsites
diretamente mantém o boundary claro.

## Invariantes / Contrato

- `SystemOS` MUST ser o ponto de ownership para serviços compartilhados do OS.
- `VirtualMachineRuntime` MUST NOT own `LogService`, `VirtualFS`,
  `MemcardService` ou `WindowManager` depois dos plans correspondentes.
- `VirtualMachineRuntime` MAY usar serviços do OS por referência, handle ou API
  estreita, mas MUST permanecer semanticamente executor VM.
- `PrometeuHub` MUST ser consumidor de OS services, não owner desses serviços.
- Paths antigos MUST NOT permanecer disponíveis por reexport ou alias.
- Mudanças de path MUST preservar comportamento observável.
- Esta decisão MUST NOT definir lifecycle de `Task`/`Process`; isso pertence à
  `AGD-0032` e à decisão futura correspondente.

## Impactos

- `prometeu-system` deve ganhar layout de serviço mais coerente em `services`.
- `SystemOS` deve concentrar ownership de `LogService`, `VirtualFS`,
  `MemcardService` e `WindowManager`.
- `VirtualMachineRuntime` deve reduzir escopo para execução VM.
- `PrometeuHub` deve começar a depender de mediação do OS para window
  management.
- Firmware e testes podem precisar atualizar imports e construtores.
- Não há mudança exigida de ABI pública de cartucho.

## Referencias

- Agenda: `AGD-0033`
- Agenda relacionada: `AGD-0032`

## Propagacao Necessaria

- Plans: criar plans pequenos para relocação da VM runtime, promoção do
  WindowManager e extração de ownership de serviços.
- Code: atualizar `prometeu-system`, `SystemOS`, `VirtualMachineRuntime`,
  `PrometeuHub`, callsites de firmware e testes afetados.
- Tests: rodar a suíte Rust afetada e adicionar cobertura se ownership mudar
  construtores ou caminhos de acesso.
- Specs: sem update obrigatório neste momento, salvo se plans futuros expuserem
  o boundary em contrato público.
- Discussion: manter `AGD-0032` dependente desta decisão antes de planejar
  lifecycle.