From cccbd48e57e701bc3395582c9dd236a3391cf89d Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Thu, 14 May 2026 18:24:29 +0100 Subject: [PATCH] SystemOS Service Ownership and Module Layout --- discussion/index.ndjson | 4 +- ...stem-os-lifecycle-process-task-contract.md | 302 ++++++++++++++++++ ...-os-service-ownership-and-module-layout.md | 199 ++++++++++++ ...mos-service-ownership-and-module-layout.md | 133 ++++++++ .../PLN-0051-move-vm-runtime-into-services.md | 103 ++++++ ...mote-window-manager-to-systemos-service.md | 85 +++++ ...0053-move-logging-ownership-to-systemos.md | 88 +++++ ...ve-fs-and-memcard-ownership-to-systemos.md | 95 ++++++ 8 files changed, 1008 insertions(+), 1 deletion(-) create mode 100644 discussion/workflow/agendas/AGD-0032-system-os-lifecycle-process-task-contract.md create mode 100644 discussion/workflow/agendas/AGD-0033-system-os-service-ownership-and-module-layout.md create mode 100644 discussion/workflow/decisions/DEC-0024-systemos-service-ownership-and-module-layout.md create mode 100644 discussion/workflow/plans/PLN-0051-move-vm-runtime-into-services.md create mode 100644 discussion/workflow/plans/PLN-0052-promote-window-manager-to-systemos-service.md create mode 100644 discussion/workflow/plans/PLN-0053-move-logging-ownership-to-systemos.md create mode 100644 discussion/workflow/plans/PLN-0054-move-fs-and-memcard-ownership-to-systemos.md diff --git a/discussion/index.ndjson b/discussion/index.ndjson index bd845d39..bc4d0752 100644 --- a/discussion/index.ndjson +++ b/discussion/index.ndjson @@ -1,4 +1,4 @@ -{"type":"meta","next_id":{"DSC":32,"AGD":32,"DEC":24,"PLN":51,"LSN":41,"CLSN":1}} +{"type":"meta","next_id":{"DSC":34,"AGD":34,"DEC":25,"PLN":55,"LSN":41,"CLSN":1}} {"type":"discussion","id":"DSC-0023","status":"done","ticket":"perf-full-migration-to-atomic-telemetry","title":"Agenda - [PERF] Full Migration to Atomic Telemetry","created_at":"2026-04-10","updated_at":"2026-04-10","tags":["perf","runtime","telemetry"],"agendas":[{"id":"AGD-0021","file":"AGD-0021-full-migration-to-atomic-telemetry.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}],"decisions":[{"id":"DEC-0008","file":"DEC-0008-full-migration-to-atomic-telemetry.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10"}],"plans":[{"id":"PLN-0007","file":"PLN-0007-full-migration-to-atomic-telemetry.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}],"lessons":[{"id":"LSN-0028","file":"discussion/lessons/DSC-0023-perf-full-migration-to-atomic-telemetry/LSN-0028-converging-to-single-atomic-telemetry-source.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]} {"type":"discussion","id":"DSC-0020","status":"done","ticket":"jenkins-gitea-integration","title":"Jenkins Gitea Integration and Relocation","created_at":"2026-04-07","updated_at":"2026-04-07","tags":["ci","jenkins","gitea"],"agendas":[{"id":"AGD-0018","file":"AGD-0018-jenkins-gitea-integration-and-relocation.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}],"decisions":[{"id":"DEC-0003","file":"DEC-0003-jenkins-gitea-strategy.md","status":"accepted","created_at":"2026-04-07","updated_at":"2026-04-07"}],"plans":[{"id":"PLN-0003","file":"PLN-0003-jenkins-gitea-execution.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}],"lessons":[{"id":"LSN-0021","file":"discussion/lessons/DSC-0020-jenkins-gitea-integration/LSN-0021-jenkins-gitea-integration.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}]} {"type":"discussion","id":"DSC-0021","status":"done","ticket":"asset-entry-codec-enum-with-metadata","title":"Asset Entry Codec Enum Contract","created_at":"2026-04-09","updated_at":"2026-04-09","tags":["asset","runtime","codec","metadata"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0024","file":"discussion/lessons/DSC-0021-asset-entry-codec-enum-contract/LSN-0024-string-on-the-wire-enum-in-runtime.md","status":"done","created_at":"2026-04-09","updated_at":"2026-04-09"}]} @@ -30,3 +30,5 @@ {"type":"discussion","id":"DSC-0019","status":"done","ticket":"jenkinsfile-correction","title":"Jenkinsfile Correction and Relocation","created_at":"2026-04-07","updated_at":"2026-04-07","tags":["ci","jenkins"],"agendas":[{"id":"AGD-0017","file":"AGD-0017-jenkinsfile-correction.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}],"decisions":[{"id":"DEC-0002","file":"DEC-0002-jenkinsfile-strategy.md","status":"accepted","created_at":"2026-04-07","updated_at":"2026-04-07"}],"plans":[{"id":"PLN-0002","file":"PLN-0002-jenkinsfile-execution.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}],"lessons":[{"id":"LSN-0020","file":"discussion/lessons/DSC-0019-jenkins-ci-standardization/LSN-0020-jenkins-standard-relocation.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}]} {"type":"discussion","id":"DSC-0030","status":"done","ticket":"internal-viewport-270p","title":"Agenda - Internal Viewport 270p (480x270)","created_at":"2026-04-27","updated_at":"2026-04-28","tags":["gfx","runtime","viewport","resolution","frame-composer","host"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0039","file":"discussion/lessons/DSC-0030-internal-viewport-270p/LSN-0039-resolution-baseline-changes-are-runtime-wide-contracts.md","status":"done","created_at":"2026-04-28","updated_at":"2026-04-28"}]} {"type":"discussion","id":"DSC-0031","status":"done","ticket":"runtime-mode-separation-game-system","title":"Agenda - Runtime Mode Separation: Game and System","created_at":"2026-05-11","updated_at":"2026-05-14","tags":["runtime","firmware","hub","system-apps","game-mode","scheduler"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0040","file":"discussion/lessons/DSC-0031-runtime-mode-separation-game-system/LSN-0040-system-pipeline-separation.md","status":"done","created_at":"2026-05-14","updated_at":"2026-05-14"}]} +{"type":"discussion","id":"DSC-0032","status":"open","ticket":"system-os-lifecycle-process-task-contract","title":"Agenda - SystemOS Lifecycle, Process and Task Contract","created_at":"2026-05-14","updated_at":"2026-05-14","tags":["runtime","os","lifecycle","process","task","shell","firmware"],"agendas":[{"id":"AGD-0032","file":"AGD-0032-system-os-lifecycle-process-task-contract.md","status":"open","created_at":"2026-05-14","updated_at":"2026-05-14"}],"decisions":[],"plans":[],"lessons":[]} +{"type":"discussion","id":"DSC-0033","status":"in_progress","ticket":"system-os-service-ownership-and-module-layout","title":"Agenda - SystemOS Service Ownership and Module Layout","created_at":"2026-05-14","updated_at":"2026-05-14","tags":["runtime","os","services","module-layout","vm","window-manager","logging"],"agendas":[{"id":"AGD-0033","file":"AGD-0033-system-os-service-ownership-and-module-layout.md","status":"accepted","created_at":"2026-05-14","updated_at":"2026-05-14"}],"decisions":[{"id":"DEC-0024","file":"DEC-0024-systemos-service-ownership-and-module-layout.md","status":"accepted","created_at":"2026-05-14","updated_at":"2026-05-14","ref_agenda":"AGD-0033"}],"plans":[{"id":"PLN-0051","file":"PLN-0051-move-vm-runtime-into-services.md","status":"open","created_at":"2026-05-14","updated_at":"2026-05-14","ref_decisions":["DEC-0024"]},{"id":"PLN-0052","file":"PLN-0052-promote-window-manager-to-systemos-service.md","status":"open","created_at":"2026-05-14","updated_at":"2026-05-14","ref_decisions":["DEC-0024"]},{"id":"PLN-0053","file":"PLN-0053-move-logging-ownership-to-systemos.md","status":"open","created_at":"2026-05-14","updated_at":"2026-05-14","ref_decisions":["DEC-0024"]},{"id":"PLN-0054","file":"PLN-0054-move-fs-and-memcard-ownership-to-systemos.md","status":"open","created_at":"2026-05-14","updated_at":"2026-05-14","ref_decisions":["DEC-0024"]}],"lessons":[]} diff --git a/discussion/workflow/agendas/AGD-0032-system-os-lifecycle-process-task-contract.md b/discussion/workflow/agendas/AGD-0032-system-os-lifecycle-process-task-contract.md new file mode 100644 index 00000000..425b59cb --- /dev/null +++ b/discussion/workflow/agendas/AGD-0032-system-os-lifecycle-process-task-contract.md @@ -0,0 +1,302 @@ +--- +id: AGD-0032 +ticket: system-os-lifecycle-process-task-contract +title: Agenda - SystemOS Lifecycle, Process and Task Contract +status: open +created: 2026-05-14 +resolved: +decision: +tags: [runtime, os, lifecycle, process, task, shell, firmware] +--- + +# Agenda - SystemOS Lifecycle, Process and Task Contract + +## Contexto + +Prometeu deu o primeiro passo concreto para deixar de ser apenas um firmware que +roda cartuchos e passar a ter um modelo de sistema operacional de console. + +Antes, o cartucho era representado quase exclusivamente pelo fluxo do firmware: + +```text +LoadCartridgeStep + -> initialize_vm + -> GameRunningStep / SystemRunningStep +``` + +Esse modelo permitia executar jogos e apps de sistema, mas não dava ao OS uma +entidade própria para representar processo, task, foreground, background, +suspensão, fechamento ou crash. O firmware sabia que algo estava rodando; o +Prometeu OS ainda não possuía um contrato próprio de execução e presença de +usuário. + +Agora existe um `SystemOS` em `prometeu-system`, agregando: + +```text +SystemOS + VirtualMachineRuntime + ProcessManager + TaskManager +``` + +Isso estabelece uma fronteira importante: a VM continua sendo a VM, e não a dona +do sistema. O `SystemOS` passa a ser o lugar natural para concentrar serviços de +OS, lifecycle, permissões e coordenação entre execução técnica e experiência de +usuário. + +Os conceitos iniciais são: + +```text +Process + execução técnica: + VmGame, VmShell, NativeShell + +Task + presença navegável do usuário: + Game ou Shell em Foreground, Background, Suspended, Closed ou Crashed +``` + +O carregamento de cartucho começou a registrar entidades de sistema: + +```text +AppMode::Game + -> cria processo VmGame + -> cria task Game + -> marca task como Foreground + -> entra em GameRunningStep com TaskId + +AppMode::System + -> cria processo VmShell + -> cria task Shell + -> marca task como Foreground + -> entra em SystemRunningStep com TaskId +``` + +`GameRunningStep` agora executa uma task específica e valida se ela ainda está em +`Foreground` antes de avançar o frame. Essa é a primeira ponte real entre o +firmware atual e um OS com lifecycle. + +## Problema + +O código já tem os primeiros tipos e fluxos, mas o contrato arquitetural ainda +não está fechado: + +- quem é a autoridade para mover uma task entre `Foreground`, `Background`, + `Suspended`, `Closed` e `Crashed`; +- como `TaskState` e `ProcessState` devem evoluir juntos; +- quais transições pertencem ao `SystemOS` e quais continuam nos managers + internos; +- como o firmware deve reagir quando uma task deixa de estar executável; +- quando o `WindowManager` deixa de ser parte do `PrometeuHub` e vira serviço + real do OS; +- se o nome público do perfil de sistema deve continuar `System` ou convergir + para `Shell` no contrato de cartucho/runtime. + +Sem esse contrato, o risco é o sistema crescer em duas direções ruins: + +1. o firmware continuar acumulando decisões de lifecycle que pertencem ao OS; +2. `TaskManager`, `ProcessManager`, `PrometeuHub` e `VirtualMachineRuntime` + criarem regras paralelas e inconsistentes. + +## Pontos Criticos + +- `SystemOS` deve ser a API de coordenação de lifecycle, não apenas um struct + agregador de managers. +- `ProcessManager` e `TaskManager` devem continuar guardando estado local, mas + não devem, sozinhos, definir o contrato semântico completo entre task e + processo. +- `Task` representa presença navegável e foco do usuário; `Process` representa + execução técnica. +- `Foreground` não é apenas uma flag visual: no modelo atual, ele autoriza o + `GameRunningStep` a executar frame. +- `Suspended`, `Closed` e `Crashed` precisam mover `TaskState` e `ProcessState` + de forma coordenada. +- `Background` precisa ser distinguido de `Suspended`: background pode existir + como presença navegável não focada, mas ainda não implica que o processo possa + executar. +- `PrometeuHub` deve evoluir para Shell/Home visual, não permanecer como + sinônimo de OS. +- `WindowManager` provavelmente deve virar serviço de `SystemOS`, mas talvez + isso precise esperar a primeira API de lifecycle estabilizar. +- A inspiração de UX é console/Switch; a inspiração interna é mais Android-like: + processos, tasks, lifecycle, surfaces/janelas, serviços e permissões. + +## Dependencia / Agenda Paralela + +`AGD-0033` trata a limpeza de ownership e layout de serviços do `SystemOS` antes +ou em paralelo a esta agenda. + +Essa separação é intencional: `AGD-0032` deve decidir lifecycle de +`Task`/`Process`, enquanto `AGD-0033` deve decidir se `VirtualMachineRuntime`, +`LogService`, `WindowManager` e outros serviços pertencem ao root, ao Hub ou à +camada `services` do `SystemOS`. + +Se `AGD-0033` concluir que `LogService` e outros serviços precisam sair da VM +antes do lifecycle, a decisão de `AGD-0032` deve tratar essa mudança como +pré-requisito de implementação, não como parte do contrato de lifecycle em si. + +## Opcoes + +### Opcao A - Manter lifecycle distribuido nos managers e no firmware + +**Abordagem:** +`TaskManager` muda tasks, `ProcessManager` muda processos, e o firmware chama +ambos diretamente quando precisar. + +**Vantagens:** +- menor mudança imediata; +- preserva managers simples; +- fácil de encaixar incrementalmente no código atual. + +**Custos / Riscos:** +- espalha regra de lifecycle por vários chamadores; +- torna mais provável esquecer de mover `ProcessState` junto com `TaskState`; +- mantém firmware como conhecedor de detalhes internos do OS; +- dificulta introduzir Shell/Home, suspensão e retomada sem duplicação. + +**Manutenibilidade:** +Aceitável no curto prazo, fraca como modelo de OS. + +### Opcao B - Centralizar lifecycle no SystemOS + +**Abordagem:** +`SystemOS` vira a API semântica para operações como: + +```text +suspend_task +resume_task +close_task +crash_task +foreground_task +background_task +``` + +Essas operações coordenam `TaskManager` e `ProcessManager` juntas. + +Exemplos de contrato: + +```text +jogo rodando: + TaskState::Foreground + ProcessState::Running + +jogo suspenso: + TaskState::Suspended + ProcessState::Suspended + +jogo fechado: + TaskState::Closed + ProcessState::Stopped + +jogo crashado: + TaskState::Crashed + ProcessState::Crashed +``` + +**Vantagens:** +- estabelece `SystemOS` como autoridade de lifecycle; +- mantém firmware mais fino; +- reduz inconsistência entre task e processo; +- cria base natural para Home/Shell, suspend/resume, close/crash e permissões. + +**Custos / Riscos:** +- exige definir transições inválidas e retorno/erro de cada operação; +- pode expor API cedo demais se tentarmos modelar todas as regras finais agora; +- precisa decidir se `Background` implica processo running, suspended ou apenas + presença não focada. + +**Manutenibilidade:** +Forte. É o caminho mais alinhado com transformar Prometeu em console OS. + +### Opcao C - Promover WindowManager a servico do OS antes do lifecycle + +**Abordagem:** +Mover primeiro o `WindowManager` para dentro de `SystemOS` e depois organizar +tasks/processos em torno de janelas/surfaces. + +**Vantagens:** +- aproxima rapidamente o modelo de Shell/Home e apps gerenciados; +- evita `PrometeuHub` continuar parecendo o sistema inteiro; +- abre caminho para surfaces e composição de apps de sistema. + +**Custos / Riscos:** +- pode misturar lifecycle de execução com lifecycle visual; +- força decisões de janela/surface antes de fechar Process/Task; +- pode congelar um WindowManager ainda experimental. + +**Manutenibilidade:** +Boa como passo futuro, mas arriscada como próximo passo se o lifecycle base +ainda não estiver normativo. + +## Sugestao / Recomendacao + +A recomendação inicial é seguir a **Opção B**. + +O próximo contrato deve declarar `SystemOS` como autoridade para lifecycle de +tasks e processos. `TaskManager` e `ProcessManager` continuam existindo, mas +devem ser mecanismos internos de armazenamento/transição, não a API semântica +principal do sistema. + +O primeiro corte deve ser pequeno: + +- adicionar métodos de lifecycle em `SystemOS`; +- coordenar `TaskState` e `ProcessState` nesses métodos; +- definir comportamento para task inexistente e process inexistente; +- preservar `GameRunningStep` como consumidor de `TaskId`, validando + foreground; +- evitar mover `WindowManager` neste mesmo corte. + +O `WindowManager` deve ser a agenda/decisão seguinte: promovê-lo a serviço real +do sistema quando a base `Task/Process/Lifecycle` estiver fechada. + +Também precisamos resolver a nomenclatura `System` versus `Shell`. O código e o +contrato anterior usam `AppMode::System`; a narrativa nova fala em +`AppMode::Shell`. A agenda deve decidir se: + +- mantemos `AppMode::System` como perfil formal e usamos `Shell` como tipo de + task/processo/UI; ou +- renomeamos o perfil público para `Shell`, com migração explícita. + +Minha inclinação inicial é manter `AppMode::System` por compatibilidade de +contrato e usar `Shell` para a camada de UI/app gerenciado dentro do OS. + +## Perguntas em Aberto + +- [ ] `SystemOS` deve expor `suspend_task`, `resume_task`, `close_task` e + `crash_task` já no próximo corte? +- [ ] `foreground_task` e `background_task` devem ser operações explícitas do + `SystemOS`, ou apenas detalhe do `TaskManager`? +- [ ] Qual é a semântica exata de `Background`: processo ainda `Running`, + processo `Suspended`, ou estado de presença sem garantia de execução? +- [ ] `resume_task` deve sempre mover a task para `Foreground`, ou pode retomar + para `Background`? +- [ ] O que acontece quando a task existe mas o processo associado não existe? +- [ ] `close_task` remove imediatamente entidades fechadas ou apenas marca + `Closed`/`Stopped` para coleta posterior? +- [ ] `crash_task` deve receber/armazenar `CrashReport`, ou isso fica em outro + serviço de diagnóstico? +- [ ] `GameRunningStep` deve transicionar para Hub/Home quando sua task deixa de + estar `Foreground`, ou apenas não executar frame? +- [ ] O perfil de manifesto continua `AppMode::System`, ou abrimos uma migração + formal para `AppMode::Shell`? +- [ ] A decisão de ownership/layout em `AGD-0033` deve ser pré-requisito para o + primeiro plan de lifecycle, ou pode ser executada em paralelo? + +## Criterio para Encerrar + +Esta agenda pode virar decisão quando houver resposta para: + +- qual entidade é autoridade normativa de lifecycle; +- quais métodos mínimos entram no primeiro contrato de `SystemOS`; +- como cada método move `TaskState` e `ProcessState`; +- qual semântica inicial de `Background` e `Suspended`; +- como o firmware deve reagir a task não-foreground/não-executável; +- qual nomenclatura será usada para `System` versus `Shell`; +- como a dependência com `AGD-0033` será tratada nos plans. + +## Proximo Passo + +Revisar esta agenda e fechar as perguntas principais. Se a direção for aceita, +o próximo estágio deve ser uma decisão normativa para `SystemOS` como autoridade +de lifecycle de `Task`/`Process`, seguida de uma família curta de plans para +implementação. diff --git a/discussion/workflow/agendas/AGD-0033-system-os-service-ownership-and-module-layout.md b/discussion/workflow/agendas/AGD-0033-system-os-service-ownership-and-module-layout.md new file mode 100644 index 00000000..5dad3dc5 --- /dev/null +++ b/discussion/workflow/agendas/AGD-0033-system-os-service-ownership-and-module-layout.md @@ -0,0 +1,199 @@ +--- +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. diff --git a/discussion/workflow/decisions/DEC-0024-systemos-service-ownership-and-module-layout.md b/discussion/workflow/decisions/DEC-0024-systemos-service-ownership-and-module-layout.md new file mode 100644 index 00000000..50679e50 --- /dev/null +++ b/discussion/workflow/decisions/DEC-0024-systemos-service-ownership-and-module-layout.md @@ -0,0 +1,133 @@ +--- +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. diff --git a/discussion/workflow/plans/PLN-0051-move-vm-runtime-into-services.md b/discussion/workflow/plans/PLN-0051-move-vm-runtime-into-services.md new file mode 100644 index 00000000..b92729c3 --- /dev/null +++ b/discussion/workflow/plans/PLN-0051-move-vm-runtime-into-services.md @@ -0,0 +1,103 @@ +--- +id: PLN-0051 +ticket: system-os-service-ownership-and-module-layout +title: Move VM Runtime Into Services +status: open +created: 2026-05-14 +ref_decisions: [DEC-0024] +tags: [runtime, os, services, module-layout, vm, window-manager, logging] +--- + +## Briefing + +Implement the mechanical module relocation required by `DEC-0024`: move +`VirtualMachineRuntime` from the `prometeu-system` crate root into the services +tree at `services/vm_runtime`. + +This plan is intentionally behavior-preserving. It prepares the service layout +for later ownership plans without moving logging, filesystem, or memcard state. + +## Source Decisions + +- `DEC-0024`: `VirtualMachineRuntime` SHALL move to + `services/vm_runtime`; old root paths MUST NOT remain available through + compatibility reexports. + +## Target + +Make `VirtualMachineRuntime` a service module while keeping the public type name +unchanged and preserving current VM behavior. + +The canonical implementation path after this plan is: + +```text +crates/console/prometeu-system/src/services/vm_runtime/ +``` + +## Dependencies + +- Source decision: `DEC-0024`. +- No prior plan is required. +- This plan should run before `PLN-0052`, `PLN-0053`, and `PLN-0054`. + +## Scope + +- Move `crates/console/prometeu-system/src/virtual_machine_runtime.rs` to + `crates/console/prometeu-system/src/services/vm_runtime.rs` or equivalent + module root under `services/vm_runtime`. +- Move the existing `virtual_machine_runtime/` child modules under + `services/vm_runtime/`. +- Update `crates/console/prometeu-system/src/services/mod.rs` to expose + `vm_runtime`. +- Update `crates/console/prometeu-system/src/lib.rs` to export + `VirtualMachineRuntime` from `services::vm_runtime`. +- Update internal module paths and tests directly. + +## Out of Scope + +- Do not move `LogService` ownership. +- Do not move `VirtualFS` or `MemcardService` ownership. +- Do not move `WindowManager`. +- Do not introduce reexports or aliases for the old root module path. +- Do not change VM runtime behavior, syscalls, telemetry, logging semantics, or + cartridge execution behavior. + +## Execution Plan + +1. Move the VM runtime module files into `src/services/vm_runtime/`. +2. Register `pub mod vm_runtime;` from `src/services/mod.rs`. +3. Remove the root `mod virtual_machine_runtime;` declaration from `src/lib.rs`. +4. Export `VirtualMachineRuntime` through the services path. +5. Update `SystemOS`, tests, and any internal imports to use the new module + location. +6. Run formatting and the affected Rust tests. + +## Acceptance Criteria + +- `VirtualMachineRuntime` implementation lives under `services/vm_runtime`. +- No root `virtual_machine_runtime` module remains in `prometeu-system`. +- No compatibility reexport preserves the old root module path. +- Public type name `VirtualMachineRuntime` remains available where the crate API + intentionally exposes it. +- Runtime behavior remains unchanged. + +## Tests / Validation + +- Run `cargo test -p prometeu-system`. +- If workspace constraints make that too broad, run the narrowest available + `prometeu-system` test target and record the exact command in implementation + evidence. + +## Risks + +- Module move churn can hide accidental import compatibility. Review must check + that no old root module remains. +- Test modules may need path updates because they currently live under the VM + runtime module tree. + +## Affected Artifacts + +- `crates/console/prometeu-system/src/lib.rs` +- `crates/console/prometeu-system/src/services/mod.rs` +- `crates/console/prometeu-system/src/services/vm_runtime/**` +- Existing VM runtime tests moved with the module diff --git a/discussion/workflow/plans/PLN-0052-promote-window-manager-to-systemos-service.md b/discussion/workflow/plans/PLN-0052-promote-window-manager-to-systemos-service.md new file mode 100644 index 00000000..8ab24ab8 --- /dev/null +++ b/discussion/workflow/plans/PLN-0052-promote-window-manager-to-systemos-service.md @@ -0,0 +1,85 @@ +--- +id: PLN-0052 +ticket: system-os-service-ownership-and-module-layout +title: Promote Window Manager To SystemOS Service +status: open +created: 2026-05-14 +ref_decisions: [DEC-0024] +tags: [runtime, os, services, module-layout, vm, window-manager, logging] +--- + +## Briefing + +Promote `WindowManager` from a `PrometeuHub` private module into an OS service +owned or mediated by `SystemOS`, as required by `DEC-0024`. + +## Source Decisions + +- `DEC-0024`: `WindowManager` SHALL move to the services tree and SHALL be + owned or mediated by `SystemOS`; `PrometeuHub` MUST NOT own it as an OS + service. + +## Target + +Make `WindowManager` part of the `services` tree and stop treating +`PrometeuHub` as the owner of window management. + +## Dependencies + +- Source decision: `DEC-0024`. +- Depends on `PLN-0051` only for the general service layout convention. + +## Scope + +- Move `crates/console/prometeu-system/src/programs/prometeu_hub/window_manager.rs` + into the `services` tree. +- Expose the service from `crates/console/prometeu-system/src/services/mod.rs`. +- Add a `WindowManager` field or OS-mediated access path on `SystemOS`. +- Remove `window_manager` ownership from `PrometeuHub`. +- Update `PrometeuHub` to access window management through `SystemOS`. +- Update tests and imports directly. + +## Out of Scope + +- Do not implement new windowing behavior. +- Do not define surface/window lifecycle beyond the existing minimal behavior. +- Do not introduce old-path compatibility reexports. +- Do not change task/process lifecycle semantics. + +## Execution Plan + +1. Move the `WindowManager` module into `src/services/`. +2. Register the new service module in `services/mod.rs`. +3. Add `WindowManager` initialization to `SystemOS::new`. +4. Remove `WindowManager` storage from `PrometeuHub`. +5. Update Hub methods so their window manager access is mediated by `SystemOS`. +6. Update tests for the new module path and ownership location. +7. Run formatting and the affected tests. + +## Acceptance Criteria + +- `WindowManager` no longer lives under `programs/prometeu_hub`. +- `PrometeuHub` does not own a `WindowManager` field. +- `SystemOS` owns or mediates access to `WindowManager`. +- No old `programs::prometeu_hub::window_manager` path remains available. +- Existing Hub behavior remains unchanged. + +## Tests / Validation + +- Run `cargo test -p prometeu-system`. +- Include any focused tests for `WindowManager` after the move. + +## Risks + +- `PrometeuHub` currently owns its `WindowManager`; moving ownership may require + method signatures to pass through `SystemOS` cleanly. +- The implementation must not accidentally introduce new window/surface + semantics while moving ownership. + +## Affected Artifacts + +- `crates/console/prometeu-system/src/programs/prometeu_hub/mod.rs` +- `crates/console/prometeu-system/src/programs/prometeu_hub/prometeu_hub.rs` +- `crates/console/prometeu-system/src/services/mod.rs` +- `crates/console/prometeu-system/src/services/window_manager.rs` or equivalent +- `crates/console/prometeu-system/src/os/system_os.rs` diff --git a/discussion/workflow/plans/PLN-0053-move-logging-ownership-to-systemos.md b/discussion/workflow/plans/PLN-0053-move-logging-ownership-to-systemos.md new file mode 100644 index 00000000..31617743 --- /dev/null +++ b/discussion/workflow/plans/PLN-0053-move-logging-ownership-to-systemos.md @@ -0,0 +1,88 @@ +--- +id: PLN-0053 +ticket: system-os-service-ownership-and-module-layout +title: Move Logging Ownership To SystemOS +status: open +created: 2026-05-14 +ref_decisions: [DEC-0024] +tags: [runtime, os, services, module-layout, vm, window-manager, logging] +--- + +## Briefing + +Move `LogService` ownership from `VirtualMachineRuntime` to `SystemOS`, while +allowing VM execution code to use OS logging through an explicit reference or +handle. + +## Source Decisions + +- `DEC-0024`: `LogService` SHALL move from `VirtualMachineRuntime` to + `SystemOS`; VM execution MAY use an explicit OS logging reference or handle + but MUST NOT own logging. + +## Target + +Make logging an OS-owned service and reduce `VirtualMachineRuntime` to a user of +logging rather than its owner. + +## Dependencies + +- Source decision: `DEC-0024`. +- Depends on `PLN-0051`. +- May run after or alongside `PLN-0052`, but code integration is simpler after + `SystemOS` service ownership is established. + +## Scope + +- Add `LogService` ownership to `SystemOS`. +- Remove `log_service: LogService` from `VirtualMachineRuntime`. +- Update VM runtime methods that read/write logs to receive logging access from + `SystemOS` or a narrow explicit handle. +- Update construction paths so `LogService::new(4096)` is owned by `SystemOS`. +- Update tests that currently inspect runtime-owned logs. + +## Out of Scope + +- Do not change log capacity or log record semantics. +- Do not change VM syscall behavior except for the ownership path. +- Do not introduce compatibility accessors that imply VM ownership. +- Do not move filesystem or memcard ownership in this plan. + +## Execution Plan + +1. Add a `LogService` field to `SystemOS` and initialize it in `SystemOS::new`. +2. Remove `LogService` initialization and storage from + `VirtualMachineRuntime::new`. +3. Update VM logging call paths in `dispatch`, `tick`, lifecycle, and tests to + use OS-owned logging. +4. If borrow constraints require it, introduce a narrow logging handle/reference + parameter at the call boundary instead of giving the VM ownership. +5. Update all tests that assert logging behavior. +6. Run formatting and tests. + +## Acceptance Criteria + +- `VirtualMachineRuntime` no longer stores `LogService`. +- `SystemOS` owns `LogService`. +- VM execution can still emit and expose logs through the existing behavior. +- No compatibility API suggests that logging remains VM-owned. +- Existing logging tests pass or are updated to assert OS ownership. + +## Tests / Validation + +- Run `cargo test -p prometeu-system`. +- Include focused tests covering VM log writes and reads after ownership moves + to `SystemOS`. + +## Risks + +- Borrowing constraints around `NativeInterface` may require a narrow access + pattern rather than simply borrowing all of `SystemOS`. +- Tests that currently construct only `VirtualMachineRuntime` may need to move + to `SystemOS` construction to reflect the new owner. + +## Affected Artifacts + +- `crates/console/prometeu-system/src/os/system_os.rs` +- `crates/console/prometeu-system/src/services/vm_runtime/**` +- Tests under the VM runtime module diff --git a/discussion/workflow/plans/PLN-0054-move-fs-and-memcard-ownership-to-systemos.md b/discussion/workflow/plans/PLN-0054-move-fs-and-memcard-ownership-to-systemos.md new file mode 100644 index 00000000..03f2b1c0 --- /dev/null +++ b/discussion/workflow/plans/PLN-0054-move-fs-and-memcard-ownership-to-systemos.md @@ -0,0 +1,95 @@ +--- +id: PLN-0054 +ticket: system-os-service-ownership-and-module-layout +title: Move FS And Memcard Ownership To SystemOS +status: open +created: 2026-05-14 +ref_decisions: [DEC-0024] +tags: [runtime, os, services, module-layout, vm, window-manager, logging] +--- + +## Briefing + +Move `VirtualFS` and `MemcardService` ownership from `VirtualMachineRuntime` to +`SystemOS`, preserving current VM filesystem and memcard behavior. + +## Source Decisions + +- `DEC-0024`: `VirtualFS` and `MemcardService` SHALL move from + `VirtualMachineRuntime` to `SystemOS`; VM execution may use them, but OS owns + the service state. + +## Target + +Make filesystem and memcard OS-owned services while keeping VM syscalls and +tests behaviorally equivalent. + +## Dependencies + +- Source decision: `DEC-0024`. +- Depends on `PLN-0051`. +- Should run after `PLN-0053` so the pattern for VM access to OS-owned services + is already established. + +## Scope + +- Add `VirtualFS`, `FsState`, `MemcardService`, open file handle state, and + related handle allocation state to `SystemOS` if they are currently VM-owned + service state. +- Remove direct ownership of `VirtualFS` and `MemcardService` from + `VirtualMachineRuntime`. +- Update FS and memcard syscall paths so VM execution uses OS-owned services. +- Update tests that currently create a bare `VirtualMachineRuntime` when they + need filesystem or memcard services. +- Keep service modules under `services/fs` and `services/memcard`. + +## Out of Scope + +- Do not redesign filesystem semantics, path normalization, memcard slot + semantics, or persistence policy. +- Do not introduce process permissions or mount namespaces. +- Do not change cartridge ABI. +- Do not move unrelated telemetry, certification, asset, or debug state unless + required by compilation and explicitly documented in implementation evidence. + +## Execution Plan + +1. Identify the complete set of FS/memcard-owned fields currently stored in + `VirtualMachineRuntime`. +2. Add the OS-owned fields to `SystemOS` and initialize them in `SystemOS::new`. +3. Remove those service fields from `VirtualMachineRuntime`. +4. Update VM dispatch/syscall code to operate on OS-owned FS and memcard state + through explicit references or narrow access methods. +5. Update tests to construct `SystemOS` when testing FS/memcard behavior through + VM execution. +6. Run formatting and the affected Rust tests. + +## Acceptance Criteria + +- `VirtualMachineRuntime` no longer owns `VirtualFS` or `MemcardService`. +- `SystemOS` owns filesystem and memcard service state needed by VM execution. +- Existing FS and memcard behavior is preserved. +- No compatibility path implies VM ownership of FS or memcard services. +- Any remaining VM-owned fields are execution-specific and justified by the + implementation evidence. + +## Tests / Validation + +- Run `cargo test -p prometeu-system`. +- Include focused FS and memcard tests after updating constructors/access paths. + +## Risks + +- FS and memcard syscalls are stateful and may be coupled to open handle fields + in `VirtualMachineRuntime`; the implementation must move the whole service + state coherently. +- Bare VM tests may need broader OS fixtures, which can reveal unrelated setup + assumptions. + +## Affected Artifacts + +- `crates/console/prometeu-system/src/os/system_os.rs` +- `crates/console/prometeu-system/src/services/fs/**` +- `crates/console/prometeu-system/src/services/memcard.rs` +- `crates/console/prometeu-system/src/services/vm_runtime/**` +- FS/memcard runtime tests