Intrepid/prometeu-runtime
Intrepid/prometeu-runtime
4
0
Fork 0
Code Pull Requests Activity
prometeu-runtime/discussion/workflow/agendas/AGD-0033-system-os-service-ownership-and-module-layout.md

8.5 KiB
Raw Blame History

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

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

  • O path deve ser services/vm_runtime ou services/virtual_machine_runtime? vm_runtime
  • 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
  • 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
  • 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
  • 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
  • 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
  • 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.