housekeeping
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good

This commit is contained in:
2026-05-15 10:29:24 +01:00
parent a0601fe816
commit 15615f3b54
14 changed files with 187 additions and 1606 deletions
@@ -1,133 +0,0 @@
---
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.
@@ -1,203 +0,0 @@
---
id: DEC-0025
ticket: system-os-lifecycle-process-task-contract
title: SystemOS Lifecycle Authority for Tasks and Processes
status: accepted
created: 2026-05-15
ref_agenda: AGD-0032
tags: [runtime, os, lifecycle, process, task, shell, firmware]
---
## Status
Accepted. Esta decisão foi aceita em 2026-05-15 e passa a ser referência
normativa para a primeira wave de lifecycle de `Task` e `Process` no
`SystemOS`.
## Contexto
`SystemOS` já agrega serviços centrais do Prometeu OS, incluindo runtime VM,
processos e tasks. A arquitetura anterior ainda permitia que firmware,
`TaskManager` e `ProcessManager` decidissem transições de lifecycle de forma
distribuída.
Esse arranjo é insuficiente para um console OS: `Task` representa presença
navegável e experiência do usuário, enquanto `Process` representa execução
técnica. Essas duas dimensões precisam mudar juntas por uma autoridade
semântica única.
`DEC-0024` já separou ownership/layout de serviços do `SystemOS`. Esta decisão
é focada apenas em lifecycle de `Task`/`Process` e não reabre a migração de
serviços, `WindowManager`, Hub ou ownership da VM.
`AppMode::System` já foi renomeado para `AppMode::Shell`. O contrato público
fica:
- `AppMode::Game`: cartucho executado como jogo/session fullscreen.
- `AppMode::Shell`: cartucho executado como app gerenciado pela Shell do
Prometeu OS.
## Decisao
`SystemOS` SHALL ser a autoridade normativa de lifecycle para `Task` e
`Process`.
`TaskManager` e `ProcessManager` SHALL continuar existindo como mecanismos
internos de armazenamento e transição local, mas MUST NOT ser a API semântica
principal para lifecycle coordenado. Firmware e outros chamadores MUST delegate
transições semânticas de lifecycle para `SystemOS`.
A primeira wave de lifecycle SHALL expor o contrato mínimo:
```text
set_foreground_task(task_id)
suspend_task(task_id)
resume_task(task_id)
close_task(task_id)
crash_task(task_id, report?)
```
Essas operações SHALL coordenar `TaskState` e `ProcessState` juntos.
O mapeamento normativo inicial SHALL ser:
```text
TaskState::Foreground -> ProcessState::Running
TaskState::Suspended -> ProcessState::Suspended
TaskState::Closed -> ProcessState::Stopped
TaskState::Crashed -> ProcessState::Crashed
```
`Background` SHALL remain reserved and MUST NOT guide any public lifecycle API
in the first wave.
`resume_task` SHALL mean resuming active user-perceived execution. In this first
wave, it MUST move a suspended task to `TaskState::Foreground` and its associated
process to `ProcessState::Running`.
`close_task` SHALL mark task/process state only. It MUST NOT remove task or
process entities immediately. Collection of closed/stopped entities is a future
separate operation.
`crash_task` SHALL be the semantic crash operation for a task. The first wave MAY
only coordinate `TaskState::Crashed` and `ProcessState::Crashed`, but the
signature SHOULD either accept or remain compatible with a future `CrashReport`
handoff to diagnostics/logging.
`GameRunningStep` SHALL keep the strong invariant that an active game execution
step only supports a game task in `TaskState::Foreground`. In this wave, any
non-foreground game task observed by `GameRunningStep` is invalid and should
produce clear diagnostic/crash behavior rather than silently running frames.
## Rationale
Centralizing lifecycle in `SystemOS` prevents firmware from becoming the de
facto OS policy layer. Firmware should remain a boot/execution state machine; it
should not know how to update `TaskState` and `ProcessState` in lockstep.
Keeping `TaskManager` and `ProcessManager` as internal mechanisms preserves
simple storage and local transition responsibilities while giving the OS a
single semantic boundary for suspend, resume, close, crash and foreground
selection.
Leaving `Background` out of the first wave avoids freezing an incomplete model
for docked apps, background services, non-focused shell apps or capability-gated
execution. The reserved enum state can remain, but no normative public lifecycle
API should depend on it yet.
Making `resume_task` return to `Foreground` keeps the first contract simple and
matches the user-perceived meaning of resume. Future background wake/service
semantics should be introduced as separate concepts rather than overloading
`resume_task`.
Marking closed/stopped entities instead of removing them immediately preserves
room for diagnostics, crash handling, system UI history and later collection
policy.
## Invariantes / Contrato
- `SystemOS` MUST coordinate lifecycle operations that affect both task and
process state.
- Firmware MUST NOT call separate task/process manager transitions to implement
semantic lifecycle operations such as suspend, resume, close or crash.
- `set_foreground_task(task_id)` MUST set the task to `TaskState::Foreground`
and its associated process to `ProcessState::Running`.
- `suspend_task(task_id)` MUST set the task to `TaskState::Suspended` and its
associated process to `ProcessState::Suspended`.
- `resume_task(task_id)` MUST move from suspended user-visible execution back to
foreground execution: `TaskState::Foreground` and `ProcessState::Running`.
- `close_task(task_id)` MUST set `TaskState::Closed` and
`ProcessState::Stopped`.
- `crash_task(task_id, report?)` MUST set `TaskState::Crashed` and
`ProcessState::Crashed`.
- A missing task MUST return a typed lifecycle error such as
`LifecycleError::TaskNotFound(TaskId)`.
- A task whose associated process is missing MUST return a typed lifecycle error
such as `LifecycleError::ProcessNotFound(ProcessId)`.
- Invalid lifecycle transitions SHOULD return a typed error carrying the task,
source state and requested operation.
- `Background` MUST NOT have normative first-wave semantics.
- This decision MUST NOT move `WindowManager`, redesign `PrometeuHub`, introduce
background services, implement docking, implement app switching, or make
`ProcessManager` own the VM.
The expected first-wave error shape is:
```rust
pub enum LifecycleError {
TaskNotFound(TaskId),
ProcessNotFound(ProcessId),
InvalidTransition {
task_id: TaskId,
from: TaskState,
operation: LifecycleOperation,
},
}
```
`LifecycleOperation` SHOULD identify at least:
```text
SetForeground
Suspend
Resume
Close
Crash
```
## Impactos
- `prometeu-system` must expose lifecycle methods on `SystemOS`.
- `TaskManager` and `ProcessManager` may need smaller internal transition
helpers, but not public semantic ownership of lifecycle.
- Firmware code should call `system_os.suspend_task(...)`,
`system_os.resume_task(...)`, `system_os.close_task(...)`,
`system_os.crash_task(...)` and `system_os.set_foreground_task(...)` instead
of coordinating task/process managers directly.
- Tests should move lifecycle assertions to the `SystemOS` level.
- Specs do not need to change before the first code plan unless the lifecycle
API is promoted to a public external contract.
- `DEC-0024` remains valid and complementary; ownership/layout work can execute
in parallel and does not block this first lifecycle wave.
## Referencias
- Agenda: `AGD-0032`
- Related decision: `DEC-0024`
## Propagacao Necessaria
- Plan: create `PLAN-0032-A: SystemOS Lifecycle API`.
- Code: update `prometeu-system` `SystemOS`, task/process lifecycle helpers,
firmware callsites if they currently coordinate managers directly, and unit
tests.
- Tests: add unit coverage for successful lifecycle mappings, missing task,
missing process and invalid transition handling.
- Discussion: keep `Background` reserved for a future agenda covering dock,
services, non-focused shell apps and capability-gated execution.
- Learn: after implementation is complete, write or update lessons only from the
published state.
## Revisao
- 2026-05-15: Initial accepted decision from `AGD-0032`.