bQUARKz
15615f3b54
All checks were successful
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
96 lines
3.2 KiB
Markdown
96 lines
3.2 KiB
Markdown
---
|
|
id: LSN-0041
|
|
ticket: system-os-lifecycle-process-task-contract
|
|
title: SystemOS Lifecycle Authority
|
|
created: 2026-05-15
|
|
tags: [runtime, os, lifecycle, process, task, firmware]
|
|
---
|
|
|
|
## Context
|
|
|
|
Prometeu moved from firmware-driven cartridge execution toward a console OS
|
|
model with explicit tasks and processes. That created two related but distinct
|
|
state dimensions:
|
|
|
|
- `TaskState`: user-visible presence and navigation.
|
|
- `ProcessState`: technical execution.
|
|
|
|
Letting firmware, `TaskManager`, and `ProcessManager` each mutate those states
|
|
independently would make suspend, resume, close and crash behavior drift over
|
|
time.
|
|
|
|
## Key Decisions
|
|
|
|
### SystemOS owns lifecycle semantics
|
|
|
|
**What:** `SystemOS` became the semantic lifecycle authority for task/process
|
|
coordination. `TaskManager` and `ProcessManager` remain storage and simple
|
|
transition mechanisms, not the public lifecycle policy boundary.
|
|
|
|
**Why:** Lifecycle operations must update user-visible and technical execution
|
|
state together. A firmware call sequence like "mark task suspended, then mark
|
|
process suspended" is too easy to duplicate, forget or partially apply.
|
|
|
|
**Trade-offs:** This adds an OS-level API layer, but it keeps lifecycle policy
|
|
in one place and makes future suspend/resume behavior easier to reason about.
|
|
|
|
### The first lifecycle wave is intentionally small
|
|
|
|
**What:** The first wave covers only foreground, suspend, resume, close and
|
|
crash:
|
|
|
|
```text
|
|
Foreground -> Running
|
|
Suspended -> Suspended
|
|
Closed -> Stopped
|
|
Crashed -> Crashed
|
|
```
|
|
|
|
`Background` remains reserved and non-normative.
|
|
|
|
**Why:** Background execution has unresolved implications around docked apps,
|
|
services, app switching and capabilities. Keeping it out of the first contract
|
|
prevents premature semantics from leaking into firmware and tests.
|
|
|
|
**Trade-offs:** The model cannot yet express every desired app lifecycle state,
|
|
but it gives the runtime a stable base without freezing background behavior too
|
|
early.
|
|
|
|
## Patterns and Algorithms
|
|
|
|
Use `SystemOS` operations for semantic lifecycle changes:
|
|
|
|
```text
|
|
set_foreground_task
|
|
suspend_task
|
|
resume_task
|
|
close_task
|
|
crash_task
|
|
```
|
|
|
|
Each operation should resolve the task, validate its associated process, and
|
|
return a typed lifecycle error for missing or invalid state instead of a bare
|
|
boolean.
|
|
|
|
`resume_task` in this wave means "return to active foreground execution", not
|
|
"wake in any possible state". If a future service needs to wake without
|
|
foregrounding, it should be modeled separately.
|
|
|
|
## Pitfalls
|
|
|
|
- Do not let firmware coordinate task and process state manually.
|
|
- Do not treat `Background` as semantically defined just because the enum value
|
|
exists.
|
|
- Do not remove closed/stopped entities as part of `close_task`; marking and
|
|
collection are different responsibilities.
|
|
- Do not hide lifecycle policy inside manager-level tests. Domain behavior
|
|
belongs at the OS lifecycle boundary.
|
|
|
|
## Takeaways
|
|
|
|
- `TaskState` and `ProcessState` are separate concepts, but lifecycle operations
|
|
must coordinate them atomically at the OS boundary.
|
|
- A small lifecycle contract is better than a broad but ambiguous one.
|
|
- Reserved states are useful only if callers are prevented from treating them as
|
|
normative before their semantics are decided.
|