CleanMM/Docs/Protocol.md

Local Protocol

Goals

• Provide a stable local contract between UI, worker, and helper components.
• Avoid parsing terminal-oriented text output.
• Support progress, execution, history, recovery, settings, and helper handoff.

Protocol Version

• Current implementation version: 0.3.2

UI ↔ Worker Commands

• health.snapshot
• permissions.inspect
• scan.start
• plan.preview
• plan.execute
• recovery.restore
• apps.list
• apps.uninstall.preview
• apps.uninstall.execute
• settings.get
• settings.set

Worker ↔ Helper Models

AtlasHelperAction

• id
• kind
• targetPath
• destinationPath (required for restore-style actions)

AtlasHelperActionResult

• action
• success
• message
• resolvedPath

Response Payloads

• accepted(task)
• health(snapshot)
• permissions(permissionStates)
• apps(appFootprints)
• preview(actionPlan)
• settings(settings)
• rejected(code, reason)

Error Codes in Current Use

• unsupportedCommand
• permissionRequired
• helperUnavailable
• executionUnavailable
• restoreExpired
• restoreConflict
• invalidSelection

Event Payloads

• taskProgress(taskID, completed, total)
• taskFinished(taskRun)
• permissionUpdated(permissionState)

Core Schemas

Finding

• id
• category
• title
• detail
• bytes
• risk
• targetPaths (optional structured execution targets derived from the scan adapter)

ActionPlan

• id
• title
• items
• estimatedBytes

ActionItem

• id
• title
• detail
• kind
• recoverable
• targetPaths (optional structured execution targets carried by the current plan)
• evidencePaths (optional structured review-only evidence paths carried by the current plan; not executable intent)

TaskRun

• id
• kind
• status
• summary
• startedAt
• finishedAt

AppFootprint

• id
• name
• bundleIdentifier
• bundlePath
• bytes
• leftoverItems

RecoveryItem

• id
• title
• detail
• originalPath
• bytes
• deletedAt
• expiresAt
• payload
• restoreMappings (optional original-path ↔ trashed-path records for physical restoration)

AppRecoveryPayload

• schemaVersion
• app
• uninstallEvidence

Workspace State Persistence

Atlas persists local workspace state in a versioned JSON envelope:

• schemaVersion
• savedAt
• snapshot
• currentPlan
• settings

Compatibility rules:

• legacy top-level AtlasWorkspaceState files must still decode on load
• after a successful legacy decode, Atlas may rewrite the file into the current versioned envelope
• legacy app recovery payloads that stored a raw AppFootprint must still decode into the current AppRecoveryPayload shape

AtlasSettings

• recoveryRetentionDays
• notificationsEnabled
• excludedPaths
• language
• acknowledgementText
• thirdPartyNoticesText

Protocol Rules

• Progress must be monotonic.
• Rejected requests return a stable code plus a user-facing reason.
• Destructive flows must end in a history record.
• Recoverable flows must produce structured recovery items.
• Helper actions must remain allowlisted structured actions, never arbitrary command strings.
• Fresh Smart Clean preview plans should carry ActionItem.targetPaths for executable items so execution does not have to reconstruct destructive intent from UI state.
• Review-only uninstall evidence may carry ActionItem.evidencePaths, which are informational only and must not be treated as execution targets.

Current Implementation Note

• health.snapshot is backed by lib/check/health_json.sh through MoleHealthAdapter.

• scan.start is backed by bin/clean.sh --dry-run through MoleSmartCleanAdapter when the upstream workflow succeeds. If it cannot complete, the worker now rejects the request instead of silently fabricating scan results.

• apps.list is backed by MacAppsInventoryAdapter, which scans local app bundles and derives lightweight leftover counts suitable for interactive refresh.

• The worker persists a versioned local JSON workspace state containing the latest snapshot, current Smart Clean plan, and settings, including the persisted app-language preference.

• Legacy top-level workspace-state files are migrated on load into the current versioned envelope when possible.

• The repository and worker normalize recovery state by pruning expired RecoveryItems and rejecting restore requests that arrive after the retention window has closed.

• Atlas localizes user-facing shell copy through a package-scoped resource bundle and uses the persisted language to keep summaries and settings text aligned.

• App uninstall can invoke the packaged or development helper executable through structured JSON actions.

• Structured Smart Clean findings can now carry executable target paths, and a safe subset of those targets can be moved to Trash and physically restored later.

• Structured Smart Clean action items now also carry targetPaths, and plan.execute prefers those plan-carried targets. Older cached plans can still fall back to finding-carried targets for backward compatibility.

• App uninstall preview items may also carry evidencePaths for review-only leftover evidence. These are visible in UI detail but must never be executed as destructive targets.

• The app shell communicates with the worker over structured XPC Data payloads that encode Atlas request and result envelopes.

• executePlan is fail-closed for unsupported targets, but now supports a real Trash-based execution path for a safe structured subset of Smart Clean items.

• recovery.restore can physically restore items when restoreMappings are present; otherwise it falls back to model rehydration only.

• recovery.restore rejects expired recovery items with restoreExpired and rejects destination collisions with restoreConflict.

• App payload restores should be followed by app-inventory refresh so the Apps surface does not reuse stale uninstall preview or stale footprint counts after recovery.