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

id	ticket	title	status	created	ref_agenda	tags
DEC-0026	system-os-domain-facades	SystemOS Domain Facades	accepted	2026-05-15	AGD-0034	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:

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:

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:

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.