This commit is contained in:
@@ -1,103 +0,0 @@
|
||||
---
|
||||
id: PLN-0051
|
||||
ticket: system-os-service-ownership-and-module-layout
|
||||
title: Move VM Runtime Into Services
|
||||
status: done
|
||||
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
|
||||
@@ -1,85 +0,0 @@
|
||||
---
|
||||
id: PLN-0052
|
||||
ticket: system-os-service-ownership-and-module-layout
|
||||
title: Promote Window Manager To SystemOS Service
|
||||
status: done
|
||||
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`
|
||||
@@ -1,88 +0,0 @@
|
||||
---
|
||||
id: PLN-0053
|
||||
ticket: system-os-service-ownership-and-module-layout
|
||||
title: Move Logging Ownership To SystemOS
|
||||
status: done
|
||||
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
|
||||
@@ -1,95 +0,0 @@
|
||||
---
|
||||
id: PLN-0054
|
||||
ticket: system-os-service-ownership-and-module-layout
|
||||
title: Move FS And Memcard Ownership To SystemOS
|
||||
status: done
|
||||
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
|
||||
@@ -1,121 +0,0 @@
|
||||
---
|
||||
id: PLN-0055
|
||||
ticket: system-os-lifecycle-process-task-contract
|
||||
title: SystemOS Lifecycle Core API
|
||||
status: done
|
||||
created: 2026-05-15
|
||||
ref_decisions: [DEC-0025]
|
||||
tags: [runtime, os, lifecycle, process, task, shell, firmware]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
Implement the first-wave `SystemOS` lifecycle API required by `DEC-0025`.
|
||||
`SystemOS` becomes the semantic coordinator for `TaskState` and `ProcessState`;
|
||||
`TaskManager` and `ProcessManager` remain storage and simple transition
|
||||
mechanisms.
|
||||
|
||||
## Source Decisions
|
||||
|
||||
- `DEC-0025`: `SystemOS` is the lifecycle authority for tasks and processes.
|
||||
|
||||
## Target
|
||||
|
||||
Add typed lifecycle operations to `prometeu-system` without changing firmware
|
||||
behavior, WindowManager ownership, Hub UI, background services, docking, app
|
||||
switching, or VM ownership.
|
||||
|
||||
## Scope
|
||||
|
||||
- Add `LifecycleError` and `LifecycleOperation` in `prometeu-system`.
|
||||
- Add lifecycle methods on `SystemOS`:
|
||||
- `set_foreground_task(task_id)`
|
||||
- `suspend_task(task_id)`
|
||||
- `resume_task(task_id)`
|
||||
- `close_task(task_id)`
|
||||
- `crash_task(task_id, report?)`
|
||||
- Coordinate task and process state changes inside `SystemOS`.
|
||||
- Preserve `TaskManager` and `ProcessManager` as internal state managers.
|
||||
- Keep `Background` reserved and out of public lifecycle semantics.
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- Background semantics.
|
||||
- Docking.
|
||||
- Background services.
|
||||
- App switcher.
|
||||
- WindowManager migration.
|
||||
- PrometeuHub redesign.
|
||||
- Game suspend/resume UX.
|
||||
- ProcessManager owning VM execution.
|
||||
- Collection/removal of closed or stopped entities.
|
||||
|
||||
## Execution Plan
|
||||
|
||||
1. Add lifecycle types.
|
||||
- Create a lifecycle module or colocate the types under
|
||||
`crates/console/prometeu-system/src/os/`.
|
||||
- Define `LifecycleOperation` with `SetForeground`, `Suspend`, `Resume`,
|
||||
`Close`, and `Crash`.
|
||||
- Define `LifecycleError` with `TaskNotFound(TaskId)`,
|
||||
`ProcessNotFound(ProcessId)`, and `InvalidTransition { task_id, from,
|
||||
operation }`.
|
||||
- Re-export the types through `prometeu-system` only if the existing public
|
||||
module style requires it.
|
||||
|
||||
2. Add the `SystemOS` coordination helpers.
|
||||
- Target file: `crates/console/prometeu-system/src/os/system_os.rs`.
|
||||
- Resolve the task first through `task_manager`.
|
||||
- Extract the task's associated `ProcessId`.
|
||||
- Validate that the process exists before mutating state.
|
||||
- Return typed errors instead of `bool`.
|
||||
|
||||
3. Implement first-wave operations.
|
||||
- `set_foreground_task`: call `task_manager.set_foreground(task_id)` and
|
||||
`process_manager.mark_running(process_id)`.
|
||||
- `suspend_task`: set `TaskState::Suspended` and
|
||||
`ProcessState::Suspended`.
|
||||
- `resume_task`: require a suspended task, then set
|
||||
`TaskState::Foreground` and `ProcessState::Running`.
|
||||
- `close_task`: set `TaskState::Closed` and `ProcessState::Stopped`.
|
||||
- `crash_task`: set `TaskState::Crashed` and `ProcessState::Crashed`.
|
||||
|
||||
4. Keep manager APIs mechanical.
|
||||
- Target files:
|
||||
`crates/console/prometeu-system/src/services/task/task_manager.rs` and
|
||||
`crates/console/prometeu-system/src/services/process/process_manager.rs`.
|
||||
- Do not remove existing manager methods in this plan.
|
||||
- Add only narrow helpers if needed to support the `SystemOS` API cleanly.
|
||||
|
||||
5. Update task creation to use the lifecycle API internally.
|
||||
- In `SystemOS::create_vm_game_task`, `create_vm_shell_task`, and
|
||||
`create_native_shell_task`, replace direct foreground manager calls with
|
||||
`set_foreground_task`.
|
||||
- Keep the constructors returning `TaskId`; handle impossible internal
|
||||
errors with explicit debug/assert behavior or an internal helper that
|
||||
cannot fail after creation.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- `SystemOS` exposes all five first-wave lifecycle methods from `DEC-0025`.
|
||||
- All five methods coordinate both task and process state.
|
||||
- Missing task returns `LifecycleError::TaskNotFound`.
|
||||
- Missing associated process returns `LifecycleError::ProcessNotFound`.
|
||||
- Invalid resume from a non-suspended task returns `InvalidTransition`.
|
||||
- `Background` is not exposed through a new lifecycle API.
|
||||
- Closed and stopped entities are not removed by `close_task`.
|
||||
|
||||
## Tests / Validation
|
||||
|
||||
- Add or update unit tests in `prometeu-system` for each lifecycle mapping.
|
||||
- Add tests for missing task, missing process, and invalid resume transition.
|
||||
- Run the affected Rust test suite for `prometeu-system`.
|
||||
|
||||
## Risks
|
||||
|
||||
- Existing direct manager access is public enough that callsites may keep using
|
||||
it. This plan does not remove those methods; enforcement continues in
|
||||
`PLN-0056`.
|
||||
- `TaskManager::set_foreground` currently moves the previous foreground task to
|
||||
`Background`. Since `Background` is out of first-wave semantics, tests must
|
||||
avoid treating that transition as normative lifecycle policy.
|
||||
@@ -1,119 +0,0 @@
|
||||
---
|
||||
id: PLN-0056
|
||||
ticket: system-os-lifecycle-process-task-contract
|
||||
title: Firmware Lifecycle Delegation
|
||||
status: done
|
||||
created: 2026-05-15
|
||||
ref_decisions: [DEC-0025]
|
||||
tags: [runtime, os, lifecycle, process, task, shell, firmware]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
Move firmware lifecycle callsites to the `SystemOS` semantic API introduced by
|
||||
`PLN-0055`. Firmware remains a boot and execution state machine; it must not
|
||||
coordinate task/process lifecycle by calling `TaskManager` and `ProcessManager`
|
||||
separately.
|
||||
|
||||
## Source Decisions
|
||||
|
||||
- `DEC-0025`: firmware must delegate semantic lifecycle transitions to
|
||||
`SystemOS`.
|
||||
|
||||
## Target
|
||||
|
||||
Replace direct lifecycle manipulation in firmware with `SystemOS` lifecycle
|
||||
methods while preserving current observable behavior.
|
||||
|
||||
## Scope
|
||||
|
||||
- Update cartridge launch paths to use `SystemOS` lifecycle authority when
|
||||
placing newly created tasks in foreground.
|
||||
- Update crash paths where a task crash is detected so task/process state moves
|
||||
through `SystemOS::crash_task`.
|
||||
- Preserve the strong `GameRunningStep` invariant: a running game step only
|
||||
supports a game task in `TaskState::Foreground`.
|
||||
- Keep `SystemRunningStep`, Hub, and WindowManager behavior unchanged except for
|
||||
lifecycle delegation required by `DEC-0025`.
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- Full game suspend/resume UX.
|
||||
- Returning to Hub/Home on suspend or close.
|
||||
- Shell UI redesign.
|
||||
- App switcher.
|
||||
- Background task API.
|
||||
- WindowManager migration.
|
||||
- Diagnostics service or crash report persistence.
|
||||
|
||||
## Execution Plan
|
||||
|
||||
1. Audit direct lifecycle manager usage.
|
||||
- Target files:
|
||||
`crates/console/prometeu-firmware/src/firmware/*.rs`,
|
||||
`crates/console/prometeu-system/src/os/system_os.rs`.
|
||||
- Search for direct calls to `task_manager.set_foreground`,
|
||||
`task_manager.mark_suspended`, `task_manager.close_task`,
|
||||
`task_manager.mark_crashed`, `process_manager.mark_suspended`,
|
||||
`process_manager.mark_stopped`, and `process_manager.mark_crashed`.
|
||||
|
||||
2. Keep launch construction inside `SystemOS`.
|
||||
- Target file:
|
||||
`crates/console/prometeu-system/src/os/system_os.rs`.
|
||||
- Ensure `create_vm_game_task`, `create_vm_shell_task`, and
|
||||
`create_native_shell_task` coordinate foreground/running state through the
|
||||
lifecycle core API from `PLN-0055`.
|
||||
|
||||
3. Update game crash handling.
|
||||
- Target file:
|
||||
`crates/console/prometeu-firmware/src/firmware/firmware_step_game_running.rs`.
|
||||
- When the task is missing, preserve current crash-screen behavior. If the
|
||||
task does not exist, `SystemOS::crash_task` cannot attach state and the
|
||||
firmware should continue producing a clear crash report.
|
||||
- When a foreground invariant fails for an existing task, call
|
||||
`ctx.os.crash_task(task_id, report?)` before transitioning to
|
||||
`AppCrashesStep`.
|
||||
- When `tick_vm` returns a crash report for the active task, call
|
||||
`ctx.os.crash_task(task_id, report?)` before transitioning to
|
||||
`AppCrashesStep`.
|
||||
|
||||
4. Keep shell launch behavior unchanged.
|
||||
- Target file:
|
||||
`crates/console/prometeu-firmware/src/firmware/firmware_step_load_cartridge.rs`.
|
||||
- Do not move `WindowManager` logic.
|
||||
- Do not change shell window creation or focus behavior.
|
||||
- Rely on `SystemOS::create_vm_shell_task` to coordinate task/process
|
||||
foreground state.
|
||||
|
||||
5. Avoid introducing background lifecycle.
|
||||
- Do not add `background_task`.
|
||||
- Do not treat `TaskState::Background` as a public lifecycle result in
|
||||
firmware.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- Firmware does not coordinate task/process lifecycle by manually changing both
|
||||
managers.
|
||||
- Game VM crash results in `SystemOS::crash_task` for the active task when the
|
||||
task still exists.
|
||||
- Foreground invariant violation in `GameRunningStep` crashes the task through
|
||||
`SystemOS`.
|
||||
- Launch behavior for `AppMode::Game` and `AppMode::Shell` remains unchanged.
|
||||
- WindowManager and Hub behavior are not redesigned or moved.
|
||||
|
||||
## Tests / Validation
|
||||
|
||||
- Run firmware tests that cover cartridge launch for `AppMode::Game` and
|
||||
`AppMode::Shell`.
|
||||
- Add or update tests for `GameRunningStep` crash delegation if the existing
|
||||
test harness supports firmware step testing.
|
||||
- Run the affected Rust test suite for `prometeu-firmware`.
|
||||
|
||||
## Risks
|
||||
|
||||
- Crash report ownership is not final. This plan should pass the report through
|
||||
the lifecycle API only to the extent supported by `PLN-0055`; persistence
|
||||
remains out of scope.
|
||||
- `GameRunningStep` currently reads task state directly. This is acceptable for
|
||||
enforcing the foreground invariant, but it must not become a place that
|
||||
coordinates lifecycle state across managers.
|
||||
@@ -1,110 +0,0 @@
|
||||
---
|
||||
id: PLN-0057
|
||||
ticket: system-os-lifecycle-process-task-contract
|
||||
title: Lifecycle Tests and Invariants
|
||||
status: done
|
||||
created: 2026-05-15
|
||||
ref_decisions: [DEC-0025]
|
||||
tags: [runtime, os, lifecycle, process, task, shell, firmware]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
Add focused test coverage and invariant checks for the lifecycle contract
|
||||
introduced by `PLN-0055` and consumed by `PLN-0056`.
|
||||
|
||||
## Source Decisions
|
||||
|
||||
- `DEC-0025`: first-wave lifecycle maps task states to process states through
|
||||
`SystemOS` and keeps `Background` outside the public lifecycle contract.
|
||||
|
||||
## Target
|
||||
|
||||
Make the lifecycle contract executable through unit tests and regression tests,
|
||||
without expanding scope into background execution, UI behavior, or service
|
||||
ownership.
|
||||
|
||||
## Scope
|
||||
|
||||
- Add `SystemOS` unit tests for all first-wave lifecycle operations.
|
||||
- Add negative tests for missing task, missing process, and invalid transition.
|
||||
- Add firmware-level regression coverage for lifecycle delegation where the
|
||||
existing test harness can observe it.
|
||||
- Keep manager tests focused on local storage and simple transitions.
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- End-to-end UX tests for suspend/resume.
|
||||
- Hub/Home navigation after lifecycle changes.
|
||||
- Background services.
|
||||
- Docking.
|
||||
- App switching.
|
||||
- Diagnostics persistence.
|
||||
- WindowManager behavior changes.
|
||||
|
||||
## Execution Plan
|
||||
|
||||
1. Add core lifecycle mapping tests.
|
||||
- Target file: `crates/console/prometeu-system/src/os/system_os.rs` or a
|
||||
dedicated `os` test module following existing crate style.
|
||||
- Verify:
|
||||
- `set_foreground_task`: task becomes `Foreground`, process becomes
|
||||
`Running`.
|
||||
- `suspend_task`: task becomes `Suspended`, process becomes `Suspended`.
|
||||
- `resume_task`: suspended task becomes `Foreground`, process becomes
|
||||
`Running`.
|
||||
- `close_task`: task becomes `Closed`, process becomes `Stopped`.
|
||||
- `crash_task`: task becomes `Crashed`, process becomes `Crashed`.
|
||||
|
||||
2. Add error tests.
|
||||
- Verify missing task returns `LifecycleError::TaskNotFound`.
|
||||
- Verify a task whose process no longer exists returns
|
||||
`LifecycleError::ProcessNotFound`.
|
||||
- Verify invalid resume from non-suspended task returns
|
||||
`LifecycleError::InvalidTransition` with operation `Resume`.
|
||||
|
||||
3. Add non-removal tests.
|
||||
- Verify `close_task` leaves the closed task available through
|
||||
`TaskManager::get`.
|
||||
- Verify `close_task` leaves the stopped process available through
|
||||
`ProcessManager::get`.
|
||||
- Do not call `remove_closed` or `remove_stopped` as part of lifecycle API
|
||||
tests.
|
||||
|
||||
4. Add background exclusion tests.
|
||||
- Assert there is no `SystemOS::background_task` API added by this wave.
|
||||
- Keep any existing `TaskState::Background` behavior in manager-level tests
|
||||
documented as manager behavior, not first-wave lifecycle semantics.
|
||||
|
||||
5. Add firmware regression tests after `PLN-0056`.
|
||||
- Target file: `crates/console/prometeu-firmware/src/firmware/firmware.rs`
|
||||
or the relevant step test module.
|
||||
- Verify game launch still enters `GameRunningStep`.
|
||||
- Verify shell launch still enters `SystemRunningStep`.
|
||||
- Verify a game crash path marks the active task as crashed when the test
|
||||
harness can observe `ctx.os.task_manager`.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- Every lifecycle method from `DEC-0025` has a positive `SystemOS` test.
|
||||
- Missing task and missing process return typed lifecycle errors.
|
||||
- Invalid resume transition is covered by a test.
|
||||
- `close_task` is tested as mark-only, not removal.
|
||||
- No test encodes `Background` as a normative first-wave lifecycle operation.
|
||||
- Firmware regression tests still pass for game and shell launch.
|
||||
|
||||
## Tests / Validation
|
||||
|
||||
- Run `cargo test -p prometeu-system`.
|
||||
- Run `cargo test -p prometeu-firmware`.
|
||||
- If workspace-level tests are practical after these changes, run the relevant
|
||||
workspace command used by this repository.
|
||||
|
||||
## Risks
|
||||
|
||||
- Some negative tests may require test-only helpers to create an inconsistent
|
||||
task/process relationship. Prefer narrow test fixtures over making corruption
|
||||
APIs public.
|
||||
- Compile-time absence of `background_task` may not be directly testable
|
||||
without compile-fail infrastructure. In that case, validate it by code review
|
||||
and keep runtime tests focused on the exposed first-wave methods.
|
||||
Reference in New Issue
Block a user