housekeeping
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good

This commit is contained in:
2026-05-15 10:29:24 +01:00
parent a0601fe816
commit 15615f3b54
14 changed files with 187 additions and 1606 deletions
@@ -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.
@@ -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.