107 lines
5.7 KiB
Markdown
107 lines
5.7 KiB
Markdown
---
|
|
phase: 02-lifecycle-command-safety
|
|
plan: 01
|
|
subsystem: runtime
|
|
tags: [tauri, rust, lifecycle, runtime, desktop]
|
|
requires:
|
|
- phase: 01-draft-state-ownership
|
|
provides: runtime draft/live separation that lifecycle metadata now extends without clobbering edits
|
|
provides:
|
|
- explicit runtime snapshot lifecycle command metadata
|
|
- backend guards for conflicting local runtime start and stop requests
|
|
- restart-required save guidance aligned to backend-owned runtime fields
|
|
affects: [phase-02-02, phase-02-03, runtime-workspace]
|
|
tech-stack:
|
|
added: []
|
|
patterns: [snapshot lifecycle transport, centralized runtime command guards]
|
|
key-files:
|
|
created: []
|
|
modified:
|
|
- tauri-app/src-tauri/src/runtime/types.rs
|
|
- tauri-app/src-tauri/src/runtime/state.rs
|
|
- tauri-app/src-tauri/src/runtime/mod.rs
|
|
key-decisions:
|
|
- "Expose active and last lifecycle command data on RuntimeSnapshot so frontend polling can render trustworthy lifecycle feedback without inferring from status alone."
|
|
- "Centralize duplicate start/stop blocking in runtime state helpers so save, start, and stop flows share the same command-result contract."
|
|
- "Keep restart-required save enforcement limited to connection_mode, model_path, addr, gpu_layers, and ctx_size to stay aligned with the existing backend runtime boundary."
|
|
patterns-established:
|
|
- "RuntimeSnapshot includes active_command plus last_command_result for stable in-flight and terminal lifecycle messaging."
|
|
- "Lifecycle commands update terminal outcomes through helper functions instead of ad-hoc last_error-only handling."
|
|
requirements-completed: [CTRL-01, CTRL-03]
|
|
duration: 6min
|
|
completed: 2026-03-29
|
|
---
|
|
|
|
# Phase 2 Plan 01: Lifecycle Command Safety Summary
|
|
|
|
**Runtime snapshot lifecycle metadata and guarded local start/stop/save outcomes at the Tauri runtime boundary**
|
|
|
|
## Performance
|
|
|
|
- **Duration:** 6 min
|
|
- **Started:** 2026-03-29T03:45:48Z
|
|
- **Completed:** 2026-03-29T03:51:43Z
|
|
- **Tasks:** 2
|
|
- **Files modified:** 3
|
|
|
|
## Accomplishments
|
|
- Added serialized lifecycle command metadata to `RuntimeSnapshot` so backend snapshots now report both the active command and the last completed command result.
|
|
- Centralized lifecycle result helpers and guard rules in runtime state so duplicate start/stop requests return stable blocked messages instead of silent no-ops.
|
|
- Routed restart-required saves and lifecycle success/failure paths through one command-result contract while preserving the existing backend restart-impact field list.
|
|
|
|
## Task Commits
|
|
|
|
Each task was committed atomically:
|
|
|
|
1. **Task 1: Add explicit lifecycle command metadata to the runtime snapshot** - `217e265` (test)
|
|
2. **Task 1: Add explicit lifecycle command metadata to the runtime snapshot** - `cf73eb2` (feat)
|
|
3. **Task 2: Guard conflicting lifecycle commands and preserve restart-impacting save rules** - `581b81b` (test)
|
|
4. **Task 2: Guard conflicting lifecycle commands and preserve restart-impacting save rules** - `67651bf` (feat)
|
|
|
|
## Files Created/Modified
|
|
- `tauri-app/src-tauri/src/runtime/types.rs` - defines lifecycle command and result payloads on runtime snapshots.
|
|
- `tauri-app/src-tauri/src/runtime/state.rs` - stores lifecycle metadata, shared guard helpers, and regression tests for blocked command behavior.
|
|
- `tauri-app/src-tauri/src/runtime/mod.rs` - applies guard helpers to save/start/stop commands and records consistent lifecycle outcomes.
|
|
|
|
## Decisions Made
|
|
- Used snapshot-level lifecycle transport instead of separate command-specific responses so existing polling consumers can adopt the new contract incrementally.
|
|
- Kept blocked lifecycle feedback in `last_command_result` while reserving `last_error` for actual runtime failures such as restart-required, spawn, health, and stop failures.
|
|
- Preserved the restart-required field list exactly as planned and covered non-restart fields with regression tests.
|
|
|
|
## Deviations from Plan
|
|
|
|
### Auto-fixed Issues
|
|
|
|
**1. [Rule 1 - Bug] Cleared latched active commands when config persistence fails**
|
|
- **Found during:** Task 2 (Guard conflicting lifecycle commands and preserve restart-impacting save rules)
|
|
- **Issue:** Beginning a save or save-and-start command before persisting config could leave `active_command` stuck if `save_runtime_config` returned an error.
|
|
- **Fix:** Added failure handling that records a failed lifecycle result, stores `save_failed`, and exits without leaving the runtime in an in-flight command state.
|
|
- **Files modified:** `tauri-app/src-tauri/src/runtime/mod.rs`
|
|
- **Verification:** `cargo test --manifest-path "tauri-app/src-tauri/Cargo.toml" runtime::` and `cargo check --manifest-path "tauri-app/src-tauri/Cargo.toml"`
|
|
- **Committed in:** `67651bf` (part of task commit)
|
|
|
|
---
|
|
|
|
**Total deviations:** 1 auto-fixed (1 bug)
|
|
**Impact on plan:** The auto-fix kept the new lifecycle contract trustworthy under save failures without expanding scope beyond the planned backend boundary.
|
|
|
|
## Issues Encountered
|
|
- The plan's verification command used `cargo test -p tauri-app runtime::`, but the Tauri crate is named `forgelm-chat`; verification succeeded via `cargo test --manifest-path "tauri-app/src-tauri/Cargo.toml" runtime::`.
|
|
|
|
## User Setup Required
|
|
|
|
None - no external service configuration required.
|
|
|
|
## Next Phase Readiness
|
|
- Frontend lifecycle manager work can now read `active_command` and `last_command_result` directly from runtime snapshots.
|
|
- Restart/apply UI work can rely on the backend restart-required contract staying limited to `connection_mode`, `model_path`, `addr`, `gpu_layers`, and `ctx_size`.
|
|
|
|
## Self-Check: PASSED
|
|
|
|
- Summary file exists at `.planning/phases/02-lifecycle-command-safety/02-01-SUMMARY.md`.
|
|
- Verified commit hashes `217e265`, `cf73eb2`, `581b81b`, and `67651bf` are present in git history.
|
|
|
|
---
|
|
*Phase: 02-lifecycle-command-safety*
|
|
*Completed: 2026-03-29*
|