SystemOS Service Ownership and Module Layout

This commit is contained in:
2026-05-14 18:24:29 +01:00
parent c1f5691cd8
commit cccbd48e57
8 changed files with 1008 additions and 1 deletions
@@ -0,0 +1,103 @@
---
id: PLN-0051
ticket: system-os-service-ownership-and-module-layout
title: Move VM Runtime Into Services
status: open
created: 2026-05-14
ref_decisions: [DEC-0024]
tags: [runtime, os, services, module-layout, vm, window-manager, logging]
---
## Briefing
Implement the mechanical module relocation required by `DEC-0024`: move
`VirtualMachineRuntime` from the `prometeu-system` crate root into the services
tree at `services/vm_runtime`.
This plan is intentionally behavior-preserving. It prepares the service layout
for later ownership plans without moving logging, filesystem, or memcard state.
## Source Decisions
- `DEC-0024`: `VirtualMachineRuntime` SHALL move to
`services/vm_runtime`; old root paths MUST NOT remain available through
compatibility reexports.
## Target
Make `VirtualMachineRuntime` a service module while keeping the public type name
unchanged and preserving current VM behavior.
The canonical implementation path after this plan is:
```text
crates/console/prometeu-system/src/services/vm_runtime/
```
## Dependencies
- Source decision: `DEC-0024`.
- No prior plan is required.
- This plan should run before `PLN-0052`, `PLN-0053`, and `PLN-0054`.
## Scope
- Move `crates/console/prometeu-system/src/virtual_machine_runtime.rs` to
`crates/console/prometeu-system/src/services/vm_runtime.rs` or equivalent
module root under `services/vm_runtime`.
- Move the existing `virtual_machine_runtime/` child modules under
`services/vm_runtime/`.
- Update `crates/console/prometeu-system/src/services/mod.rs` to expose
`vm_runtime`.
- Update `crates/console/prometeu-system/src/lib.rs` to export
`VirtualMachineRuntime` from `services::vm_runtime`.
- Update internal module paths and tests directly.
## Out of Scope
- Do not move `LogService` ownership.
- Do not move `VirtualFS` or `MemcardService` ownership.
- Do not move `WindowManager`.
- Do not introduce reexports or aliases for the old root module path.
- Do not change VM runtime behavior, syscalls, telemetry, logging semantics, or
cartridge execution behavior.
## Execution Plan
1. Move the VM runtime module files into `src/services/vm_runtime/`.
2. Register `pub mod vm_runtime;` from `src/services/mod.rs`.
3. Remove the root `mod virtual_machine_runtime;` declaration from `src/lib.rs`.
4. Export `VirtualMachineRuntime` through the services path.
5. Update `SystemOS`, tests, and any internal imports to use the new module
location.
6. Run formatting and the affected Rust tests.
## Acceptance Criteria
- `VirtualMachineRuntime` implementation lives under `services/vm_runtime`.
- No root `virtual_machine_runtime` module remains in `prometeu-system`.
- No compatibility reexport preserves the old root module path.
- Public type name `VirtualMachineRuntime` remains available where the crate API
intentionally exposes it.
- Runtime behavior remains unchanged.
## Tests / Validation
- Run `cargo test -p prometeu-system`.
- If workspace constraints make that too broad, run the narrowest available
`prometeu-system` test target and record the exact command in implementation
evidence.
## Risks
- Module move churn can hide accidental import compatibility. Review must check
that no old root module remains.
- Test modules may need path updates because they currently live under the VM
runtime module tree.
## Affected Artifacts
- `crates/console/prometeu-system/src/lib.rs`
- `crates/console/prometeu-system/src/services/mod.rs`
- `crates/console/prometeu-system/src/services/vm_runtime/**`
- Existing VM runtime tests moved with the module
@@ -0,0 +1,85 @@
---
id: PLN-0052
ticket: system-os-service-ownership-and-module-layout
title: Promote Window Manager To SystemOS Service
status: open
created: 2026-05-14
ref_decisions: [DEC-0024]
tags: [runtime, os, services, module-layout, vm, window-manager, logging]
---
## Briefing
Promote `WindowManager` from a `PrometeuHub` private module into an OS service
owned or mediated by `SystemOS`, as required by `DEC-0024`.
## Source Decisions
- `DEC-0024`: `WindowManager` SHALL move to the services tree and SHALL be
owned or mediated by `SystemOS`; `PrometeuHub` MUST NOT own it as an OS
service.
## Target
Make `WindowManager` part of the `services` tree and stop treating
`PrometeuHub` as the owner of window management.
## Dependencies
- Source decision: `DEC-0024`.
- Depends on `PLN-0051` only for the general service layout convention.
## Scope
- Move `crates/console/prometeu-system/src/programs/prometeu_hub/window_manager.rs`
into the `services` tree.
- Expose the service from `crates/console/prometeu-system/src/services/mod.rs`.
- Add a `WindowManager` field or OS-mediated access path on `SystemOS`.
- Remove `window_manager` ownership from `PrometeuHub`.
- Update `PrometeuHub` to access window management through `SystemOS`.
- Update tests and imports directly.
## Out of Scope
- Do not implement new windowing behavior.
- Do not define surface/window lifecycle beyond the existing minimal behavior.
- Do not introduce old-path compatibility reexports.
- Do not change task/process lifecycle semantics.
## Execution Plan
1. Move the `WindowManager` module into `src/services/`.
2. Register the new service module in `services/mod.rs`.
3. Add `WindowManager` initialization to `SystemOS::new`.
4. Remove `WindowManager` storage from `PrometeuHub`.
5. Update Hub methods so their window manager access is mediated by `SystemOS`.
6. Update tests for the new module path and ownership location.
7. Run formatting and the affected tests.
## Acceptance Criteria
- `WindowManager` no longer lives under `programs/prometeu_hub`.
- `PrometeuHub` does not own a `WindowManager` field.
- `SystemOS` owns or mediates access to `WindowManager`.
- No old `programs::prometeu_hub::window_manager` path remains available.
- Existing Hub behavior remains unchanged.
## Tests / Validation
- Run `cargo test -p prometeu-system`.
- Include any focused tests for `WindowManager` after the move.
## Risks
- `PrometeuHub` currently owns its `WindowManager`; moving ownership may require
method signatures to pass through `SystemOS` cleanly.
- The implementation must not accidentally introduce new window/surface
semantics while moving ownership.
## Affected Artifacts
- `crates/console/prometeu-system/src/programs/prometeu_hub/mod.rs`
- `crates/console/prometeu-system/src/programs/prometeu_hub/prometeu_hub.rs`
- `crates/console/prometeu-system/src/services/mod.rs`
- `crates/console/prometeu-system/src/services/window_manager.rs` or equivalent
- `crates/console/prometeu-system/src/os/system_os.rs`
@@ -0,0 +1,88 @@
---
id: PLN-0053
ticket: system-os-service-ownership-and-module-layout
title: Move Logging Ownership To SystemOS
status: open
created: 2026-05-14
ref_decisions: [DEC-0024]
tags: [runtime, os, services, module-layout, vm, window-manager, logging]
---
## Briefing
Move `LogService` ownership from `VirtualMachineRuntime` to `SystemOS`, while
allowing VM execution code to use OS logging through an explicit reference or
handle.
## Source Decisions
- `DEC-0024`: `LogService` SHALL move from `VirtualMachineRuntime` to
`SystemOS`; VM execution MAY use an explicit OS logging reference or handle
but MUST NOT own logging.
## Target
Make logging an OS-owned service and reduce `VirtualMachineRuntime` to a user of
logging rather than its owner.
## Dependencies
- Source decision: `DEC-0024`.
- Depends on `PLN-0051`.
- May run after or alongside `PLN-0052`, but code integration is simpler after
`SystemOS` service ownership is established.
## Scope
- Add `LogService` ownership to `SystemOS`.
- Remove `log_service: LogService` from `VirtualMachineRuntime`.
- Update VM runtime methods that read/write logs to receive logging access from
`SystemOS` or a narrow explicit handle.
- Update construction paths so `LogService::new(4096)` is owned by `SystemOS`.
- Update tests that currently inspect runtime-owned logs.
## Out of Scope
- Do not change log capacity or log record semantics.
- Do not change VM syscall behavior except for the ownership path.
- Do not introduce compatibility accessors that imply VM ownership.
- Do not move filesystem or memcard ownership in this plan.
## Execution Plan
1. Add a `LogService` field to `SystemOS` and initialize it in `SystemOS::new`.
2. Remove `LogService` initialization and storage from
`VirtualMachineRuntime::new`.
3. Update VM logging call paths in `dispatch`, `tick`, lifecycle, and tests to
use OS-owned logging.
4. If borrow constraints require it, introduce a narrow logging handle/reference
parameter at the call boundary instead of giving the VM ownership.
5. Update all tests that assert logging behavior.
6. Run formatting and tests.
## Acceptance Criteria
- `VirtualMachineRuntime` no longer stores `LogService`.
- `SystemOS` owns `LogService`.
- VM execution can still emit and expose logs through the existing behavior.
- No compatibility API suggests that logging remains VM-owned.
- Existing logging tests pass or are updated to assert OS ownership.
## Tests / Validation
- Run `cargo test -p prometeu-system`.
- Include focused tests covering VM log writes and reads after ownership moves
to `SystemOS`.
## Risks
- Borrowing constraints around `NativeInterface` may require a narrow access
pattern rather than simply borrowing all of `SystemOS`.
- Tests that currently construct only `VirtualMachineRuntime` may need to move
to `SystemOS` construction to reflect the new owner.
## Affected Artifacts
- `crates/console/prometeu-system/src/os/system_os.rs`
- `crates/console/prometeu-system/src/services/vm_runtime/**`
- Tests under the VM runtime module
@@ -0,0 +1,95 @@
---
id: PLN-0054
ticket: system-os-service-ownership-and-module-layout
title: Move FS And Memcard Ownership To SystemOS
status: open
created: 2026-05-14
ref_decisions: [DEC-0024]
tags: [runtime, os, services, module-layout, vm, window-manager, logging]
---
## Briefing
Move `VirtualFS` and `MemcardService` ownership from `VirtualMachineRuntime` to
`SystemOS`, preserving current VM filesystem and memcard behavior.
## Source Decisions
- `DEC-0024`: `VirtualFS` and `MemcardService` SHALL move from
`VirtualMachineRuntime` to `SystemOS`; VM execution may use them, but OS owns
the service state.
## Target
Make filesystem and memcard OS-owned services while keeping VM syscalls and
tests behaviorally equivalent.
## Dependencies
- Source decision: `DEC-0024`.
- Depends on `PLN-0051`.
- Should run after `PLN-0053` so the pattern for VM access to OS-owned services
is already established.
## Scope
- Add `VirtualFS`, `FsState`, `MemcardService`, open file handle state, and
related handle allocation state to `SystemOS` if they are currently VM-owned
service state.
- Remove direct ownership of `VirtualFS` and `MemcardService` from
`VirtualMachineRuntime`.
- Update FS and memcard syscall paths so VM execution uses OS-owned services.
- Update tests that currently create a bare `VirtualMachineRuntime` when they
need filesystem or memcard services.
- Keep service modules under `services/fs` and `services/memcard`.
## Out of Scope
- Do not redesign filesystem semantics, path normalization, memcard slot
semantics, or persistence policy.
- Do not introduce process permissions or mount namespaces.
- Do not change cartridge ABI.
- Do not move unrelated telemetry, certification, asset, or debug state unless
required by compilation and explicitly documented in implementation evidence.
## Execution Plan
1. Identify the complete set of FS/memcard-owned fields currently stored in
`VirtualMachineRuntime`.
2. Add the OS-owned fields to `SystemOS` and initialize them in `SystemOS::new`.
3. Remove those service fields from `VirtualMachineRuntime`.
4. Update VM dispatch/syscall code to operate on OS-owned FS and memcard state
through explicit references or narrow access methods.
5. Update tests to construct `SystemOS` when testing FS/memcard behavior through
VM execution.
6. Run formatting and the affected Rust tests.
## Acceptance Criteria
- `VirtualMachineRuntime` no longer owns `VirtualFS` or `MemcardService`.
- `SystemOS` owns filesystem and memcard service state needed by VM execution.
- Existing FS and memcard behavior is preserved.
- No compatibility path implies VM ownership of FS or memcard services.
- Any remaining VM-owned fields are execution-specific and justified by the
implementation evidence.
## Tests / Validation
- Run `cargo test -p prometeu-system`.
- Include focused FS and memcard tests after updating constructors/access paths.
## Risks
- FS and memcard syscalls are stateful and may be coupled to open handle fields
in `VirtualMachineRuntime`; the implementation must move the whole service
state coherently.
- Bare VM tests may need broader OS fixtures, which can reveal unrelated setup
assumptions.
## Affected Artifacts
- `crates/console/prometeu-system/src/os/system_os.rs`
- `crates/console/prometeu-system/src/services/fs/**`
- `crates/console/prometeu-system/src/services/memcard.rs`
- `crates/console/prometeu-system/src/services/vm_runtime/**`
- FS/memcard runtime tests