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