134 lines
5.6 KiB
Markdown
134 lines
5.6 KiB
Markdown
---
|
|
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.
|