prometeu-runtime/discussion/workflow/decisions/DEC-0026-systemos-domain-facades.md

---
id: DEC-0026
ticket: system-os-domain-facades
title: SystemOS Domain Facades
status: accepted
created: 2026-05-15
ref_agenda: AGD-0034
tags: [runtime, os, services, api-surface, lifecycle, fs]
---

## Status

Accepted. Esta decisão foi aceita em 2026-05-15 e passa a ser referência
normativa para compartimentalizar a superfície pública do `SystemOS`.

## Contexto

`DEC-0024` consolidou `SystemOS` como owner de serviços do Prometeu OS.
`DEC-0025` colocou o lifecycle de `Task` e `Process` sob autoridade do
`SystemOS`.

Essas decisões estão corretas em termos de ownership, mas fizeram a raiz do
`SystemOS` crescer como superfície pública. Hoje a raiz mistura runtime VM,
filesystem, memcard, window management, lifecycle, managers internos, handles
operacionais e helpers de criação de tasks/processos.

Esta decisão não muda o ownership: `SystemOS` continua sendo o boundary do OS.
O que muda é a forma normativa de acesso aos domínios.

## Decisao

`SystemOS` SHALL expose OS behavior through domain facades.

The canonical first-wave access shape SHALL be method-based, borrow-friendly
views:

```rust
os.lifecycle().suspend_task(task_id)
os.sessions().create_vm_game_task(app_id, title)
os.vm().initialize(vm, cartridge)
os.fs().mount(backend)
os.window().set_focus(window_id)
os.log(level, source, tag, msg)
```

Direct field syntax such as `os.lifecycle.suspend_task(...)` is NOT required in
this wave. Domain clarity is normative; direct field ownership is not.

The first-wave `SystemOS` root SHALL keep only minimal root operations:

```text
SystemOS
    new(...)
    log(...)
    lifecycle()
    sessions()
    vm()
    fs()
    window()
```

`log(...)` MAY remain on the root because logging is a cross-cutting operation
used by multiple firmware and OS domains.

The first-wave domain surface SHALL be:

```text
lifecycle()
    set_foreground_task
    suspend_task
    resume_task
    close_task
    crash_task

sessions()
    create_vm_game_task
    create_vm_shell_task
    create_native_shell_task

vm()
    initialize
    tick

fs()
    mount
    open
    read
    write
    close

window()
    add_window
    set_focus
    focused_window
    close_window
```

Internal service state SHALL NOT remain public on `SystemOS` once the
corresponding facade exists. This includes:

- `task_manager`
- `process_manager`
- `window_manager`
- `vm_runtime`
- `fs`
- `fs_state`
- `memcard`
- `open_files`
- `next_handle`

Plans MAY use temporary transitional access only when needed to keep migrations
small, but the completed first-wave facade migration MUST remove direct public
access for migrated domains.

## Rationale

`SystemOS` should remain the owner of OS services, but callers should not see it
as a bag of unrelated fields and root methods. Domain facades make the API read
like an OS surface:

- lifecycle operations live under lifecycle;
- session construction lives under sessions;
- VM execution lives under vm;
- filesystem operations live under fs;
- window operations live under window;
- logging remains root-level because it cuts across domains.

Method-based facades are preferred over direct fields in this wave because they
preserve Rust borrowing flexibility. A facade can be a temporary view over
multiple internal fields without forcing premature service ownership splits.

This also protects `DEC-0025`: lifecycle remains the semantic coordinator for
`TaskState` and `ProcessState`, but callers reach it through
`os.lifecycle()`, not through root methods or direct manager access.

## Invariantes / Contrato

- `SystemOS` MUST remain the OS ownership and coordination boundary.
- Facades MUST be views or handles over `SystemOS` internals unless a later
  decision explicitly promotes a domain to an independently owned service.
- Facades MUST NOT duplicate state.
- Root-level `SystemOS` API MUST stay minimal.
- Lifecycle operations MUST move from root-level `SystemOS` methods to
  `os.lifecycle()`.
- Session creation helpers MUST move to `os.sessions()`.
- VM initialization and ticking MUST move to `os.vm()`.
- Filesystem operations MUST move to `os.fs()`.
- Window operations MUST move to `os.window()`.
- Logging MAY remain as `os.log(...)`.
- Firmware, Hub and tests SHOULD use facades instead of direct internal fields.
- Tests for domain behavior SHOULD live at the facade/domain level.
- `SystemOS` tests SHOULD focus on composition and cross-domain coordination.

## Impactos

- `crates/console/prometeu-system/src/os/` should gain facade/view types for
  lifecycle, sessions, VM, filesystem and window domains.
- Existing root methods such as `suspend_task`, `resume_task`, `close_task`,
  `crash_task`, `initialize_vm`, `tick_vm`, `mount_fs`, `create_vm_game_task`,
  `create_vm_shell_task` and `create_native_shell_task` should migrate behind
  domain facades.
- Direct access to managers and service fields from firmware, Hub and tests
  should be removed or narrowed.
- Filesystem state may require a dedicated facade because it spans `VirtualFS`,
  `FsState`, file handles, memcard-adjacent state and logging.
- Window access should move away from `os.window_manager` to `os.window()`.
- Specs do not need immediate updates unless these facades become part of a
  published external API.

## Referencias

- Agenda: `AGD-0034`
- Related decision: `DEC-0024`
- Related decision: `DEC-0025`

## Propagacao Necessaria

- Plans: create small plans for lifecycle facade, sessions/vm facade, fs facade,
  window facade and internal field encapsulation.
- Code: update `prometeu-system`, firmware, Hub and tests to use domain
  facades.
- Tests: move lifecycle/session/fs/window assertions to domain-level tests where
  possible.
- Discussion: keep this decision separate from future decisions about true
  service ownership splits.

## Revisao

- 2026-05-15: Initial accepted decision from `AGD-0034`.