This commit is contained in:
-133
@@ -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.
|
||||
-203
@@ -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`.
|
||||
Reference in New Issue
Block a user