CleanMM/Docs/TaskStateMachine.md

Task State Machine

Task Types

• scan
• execute_clean
• execute_uninstall
• restore
• inspect_permissions
• health_snapshot

Main States

• draft
• submitted
• validating
• awaiting_permission
• queued
• running
• cancelling
• completed
• partial_failed
• failed
• cancelled
• expired

Terminal States

• completed
• partial_failed
• failed
• cancelled
• expired

Core Transition Rules

• draft -> submitted
• submitted -> validating
• validating -> awaiting_permission | queued | failed
• awaiting_permission -> queued | cancelled | failed
• queued -> running | cancelled
• running -> cancelling | completed | partial_failed | failed
• cancelling -> cancelled

Action Item States

• pending
• running
• succeeded
• skipped
• failed
• cancelled

Guarantees

• Terminal states are immutable.
• Progress must not move backwards.
• Destructive tasks must be audited.
• Recoverable tasks must leave structured recovery entries until restored or expired.
• Expired recovery entries must no longer remain actionable in active recovery state.
• Repeated write requests must honor idempotency rules when those flows become externally reentrant.

Current MVP Notes

• scan emits monotonic progress and finishes with a preview-ready plan when the upstream scan adapter succeeds; otherwise the request should fail rather than silently fabricate findings.
• execute_clean must not report completion in release-facing flows unless real cleanup side effects have been applied. Fresh preview plans now carry structured execution targets, and unsupported or unstructured targets should fail closed.
• execute_uninstall removes an app from the current workspace view and creates a recovery entry.
• restore can physically restore items when structured recovery mappings are present, and can still rehydrate a Finding or an app payload into Atlas state from the recovery payload.
• restore must reject expired recovery items before side effects and must fail closed when the original destination already exists.
• When restore rehydrates an app payload, the Apps surface should refresh inventory before presenting footprint counts or a new uninstall preview.
• User-visible task summaries and settings-driven text should reflect the persisted app-language preference when generated.