---
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.