This commit is contained in:
@@ -1,189 +0,0 @@
|
||||
---
|
||||
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`.
|
||||
Reference in New Issue
Block a user