Intrepid/prometeu-runtime
Intrepid/prometeu-runtime
4
0
Fork 0
Code Pull Requests Activity
prometeu-runtime/discussion/workflow/decisions/DEC-0025-systemos-lifecycle-authority-for-tasks-and-processes.md

7.7 KiB
Raw Blame History

id ticket title status created ref_agenda tags
DEC-0025 system-os-lifecycle-process-task-contract SystemOS Lifecycle Authority for Tasks and Processes accepted 2026-05-15 AGD-0032
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:

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:

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:

pub enum LifecycleError {
    TaskNotFound(TaskId),
    ProcessNotFound(ProcessId),
    InvalidTransition {
        task_id: TaskId,
        from: TaskState,
        operation: LifecycleOperation,
    },
}

LifecycleOperation SHOULD identify at least:

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.