prometeu-runtime/discussion/workflow/decisions/DEC-0024-systemos-service-ownership-and-module-layout.md

id	ticket	title	status	created	ref_agenda	tags
DEC-0024	system-os-service-ownership-and-module-layout	SystemOS Service Ownership and Module Layout	accepted	2026-05-14	AGD-0033	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:

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.