# 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.0`

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

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

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

## 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 leftover counts.
- The worker persists a local JSON-backed workspace state containing the latest snapshot, current Smart Clean plan, and settings, including the persisted app-language preference.
- 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.
- 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.
