accept DEC-0025 lifecycle plans

This commit is contained in:
2026-05-15 05:31:37 +01:00
parent 5282089c7d
commit fbebd8887a
6 changed files with 632 additions and 34 deletions
@@ -2,10 +2,10 @@
id: AGD-0032
ticket: system-os-lifecycle-process-task-contract
title: Agenda - SystemOS Lifecycle, Process and Task Contract
status: open
status: accepted
created: 2026-05-14
resolved:
decision:
resolved: 2026-05-15
decision: DEC-0025
tags: [runtime, os, lifecycle, process, task, shell, firmware]
---
@@ -65,7 +65,7 @@ AppMode::Game
-> marca task como Foreground
-> entra em GameRunningStep com TaskId
AppMode::System
AppMode::Shell
-> cria processo VmShell
-> cria task Shell
-> marca task como Foreground
@@ -249,38 +249,83 @@ O primeiro corte deve ser pequeno:
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.
`AppMode::System` já foi renomeado para `AppMode::Shell`. A nomenclatura pública
fica alinhada com o modelo atual: `AppMode::Game` executa cartuchos como
jogo/session fullscreen, enquanto `AppMode::Shell` executa cartuchos como apps
gerenciados pela Shell do Prometeu 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`,
- [x] `SystemOS` deve expor `suspend_task`, `resume_task`, `close_task` e
`crash_task` já no próximo corte? Sim. Eles são a próxima API semântica de
lifecycle e evitam que firmware ou outros chamadores manipulem
`TaskManager` e `ProcessManager` separadamente.
- [x] `foreground_task` e `background_task` devem ser operações explícitas do
`SystemOS`, ou apenas detalhe do `TaskManager`? `set_foreground_task(task_id)`
deve ser operação explícita do `SystemOS`. `background_task` fica fora da
primeira wave.
- [x] 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?
Fora de escopo nesta wave. `Background` permanece estado reservado sem
semântica normativa no primeiro contrato.
- [x] `resume_task` deve sempre mover a task para `Foreground`, ou pode retomar
para `Background`? Nesta wave, `resume_task` sempre move para
`Foreground` e move o processo associado para `Running`.
- [x] O que acontece quando a task existe mas o processo associado não existe?
Isso é erro de lifecycle e deve retornar erro tipado, não `bool`.
- [x] `close_task` remove imediatamente entidades fechadas ou apenas marca
`Closed`/`Stopped` para coleta posterior? Apenas marca `TaskState::Closed` e
`ProcessState::Stopped`; coleta é operação futura separada.
- [x] `crash_task` deve receber/armazenar `CrashReport`, ou isso fica em outro
serviço de diagnóstico? A operação deve aceitar ou preparar o contrato para
`CrashReport`, mas a primeira wave pode apenas coordenar estados e deixar o
armazenamento para diagnóstico/logging futuro.
- [x] `GameRunningStep` deve transicionar para Hub/Home quando sua task deixa de
estar `Foreground`, ou apenas não executar frame? Nesta wave, mantém a
invariant forte: `GameRunningStep` só suporta game task em `Foreground`; outro
estado é inválido e deve gerar diagnóstico/crash claro.
- [x] O perfil de manifesto continua `AppMode::System`, ou abrimos uma migração
formal para `AppMode::Shell`? Resolvido: `AppMode::System` já virou
`AppMode::Shell`.
- [x] 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? Pode executar
em paralelo e não bloqueia esta wave. O plan de lifecycle deve evitar mover
`WindowManager`, `VirtualMachineRuntime`, Hub ou background services.
## Resolucao
A agenda fecha pela **Opcao B**: centralizar lifecycle no `SystemOS`.
`SystemOS` deixa de ser apenas um agregador de serviços e passa a ser a
autoridade normativa para coordenar `TaskState` e `ProcessState`. `TaskManager`
e `ProcessManager` continuam existindo, mas como mecanismos internos de
armazenamento e transição simples. O firmware não deve decidir diretamente como
task e processo mudam juntos.
A primeira wave deve cobrir apenas:
- `set_foreground_task(task_id)`
- `suspend_task(task_id)`
- `resume_task(task_id)`
- `close_task(task_id)`
- `crash_task(task_id, report?)`
O mapeamento inicial é:
```text
TaskState::Foreground -> ProcessState::Running
TaskState::Suspended -> ProcessState::Suspended
TaskState::Closed -> ProcessState::Stopped
TaskState::Crashed -> ProcessState::Crashed
```
`Background` permanece reservado e explicitamente fora da primeira wave.
O primeiro plan recomendado é `PLAN-0032-A: SystemOS Lifecycle API`, com escopo
limitado a erro tipado, métodos de lifecycle em `SystemOS`, coordenação de
`TaskState`/`ProcessState`, testes unitários no nível `SystemOS` e nenhuma
mudança em `WindowManager`, `PrometeuHub`, background services ou UX completa de
suspensão/retomada.
## Criterio para Encerrar