This commit is contained in:
+95
@@ -0,0 +1,95 @@
|
||||
---
|
||||
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.
|
||||
+89
@@ -0,0 +1,89 @@
|
||||
---
|
||||
id: LSN-0042
|
||||
ticket: system-os-service-ownership-and-module-layout
|
||||
title: SystemOS Service Ownership Boundary
|
||||
created: 2026-05-15
|
||||
tags: [runtime, os, services, module-layout, vm, window-manager, logging]
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
Prometeu's runtime started with VM execution as the center of gravity. As the
|
||||
system evolved toward a console OS, services such as logging, filesystem,
|
||||
memcard and window management needed a clearer owner.
|
||||
|
||||
The important shift was to stop treating `VirtualMachineRuntime` and
|
||||
`PrometeuHub` as implicit owners of OS services.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
### SystemOS owns shared OS services
|
||||
|
||||
**What:** `SystemOS` became the owner or mediator for shared OS services:
|
||||
logging, filesystem, memcard, VM runtime and window management.
|
||||
|
||||
**Why:** VM execution is a service of the OS, not the OS itself. If filesystem,
|
||||
memcard, logging and windows remain owned by the VM runtime or Hub, the
|
||||
architecture keeps pulling policy back into the wrong layer.
|
||||
|
||||
**Trade-offs:** Moving ownership into `SystemOS` increases the breadth of the OS
|
||||
object, but it makes service boundaries explicit and prepares the system for
|
||||
facades, permissions and lifecycle coordination.
|
||||
|
||||
### PrometeuHub is Shell/Home, not the OS
|
||||
|
||||
**What:** `PrometeuHub` should consume OS services through `SystemOS` rather
|
||||
than owning services such as window management.
|
||||
|
||||
**Why:** The Hub is a visual Shell/Home program. Treating it as the service
|
||||
owner makes UI structure and OS infrastructure hard to separate.
|
||||
|
||||
**Trade-offs:** Hub callsites may become slightly more explicit, but service
|
||||
ownership becomes visible and testable.
|
||||
|
||||
### VM runtime is execution, not a service container
|
||||
|
||||
**What:** `VirtualMachineRuntime` moved into the service layout and stopped
|
||||
owning shared services such as logging, filesystem and memcard.
|
||||
|
||||
**Why:** The VM runtime should execute VM code and use OS services through
|
||||
explicit boundaries. It should not silently become the container for every
|
||||
runtime facility.
|
||||
|
||||
**Trade-offs:** VM execution now receives more explicit service references, but
|
||||
the ownership model is cleaner.
|
||||
|
||||
## Patterns and Algorithms
|
||||
|
||||
When a capability is shared by game, shell, firmware or diagnostics, default to
|
||||
OS ownership or OS mediation. The VM may use the capability, but use is not
|
||||
ownership.
|
||||
|
||||
Keep module layout aligned with meaning:
|
||||
|
||||
```text
|
||||
services/vm_runtime
|
||||
services/window_manager
|
||||
services/fs
|
||||
services/memcard
|
||||
```
|
||||
|
||||
Avoid compatibility reexports for old internal paths when the boundary is still
|
||||
private to the workspace. Updating callsites directly keeps architectural
|
||||
direction visible.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- Do not move files into `services/` while leaving semantic ownership unchanged.
|
||||
- Do not let UI programs such as Hub own OS infrastructure just because they are
|
||||
the first consumer.
|
||||
- Do not let `VirtualMachineRuntime` become a general-purpose service bag.
|
||||
- Do not confuse "VM needs access" with "VM owns the service".
|
||||
|
||||
## Takeaways
|
||||
|
||||
- OS service ownership should follow policy authority, not first caller.
|
||||
- VM runtime is a service under the OS boundary.
|
||||
- Shell/Home programs consume OS services; they are not the OS.
|
||||
- A cleaner ownership boundary can make the root object wider temporarily, so a
|
||||
later domain-facade pass is expected rather than optional.
|
||||
Reference in New Issue
Block a user