zapstore/spec/features/FEAT-001-package-manager.md

# FEAT-001 — Package Manager

## Goal

Allow users to install, update, and uninstall apps with clear progress feedback and reliable error handling.

## Core Invariant: No Hanging States

**Every operation MUST resolve to a terminal state.** The UI must never get stuck in an in-progress state indefinitely.

- On success, present a launch action
- On failure, show an error with an actionable message
- On cancel, restore the pre-operation UI

If the system stops responding, the operation must either:
1. **Advance** to completion when the system eventually responds, OR
2. **Fall back** to an error state with clear feedback

There is no third option. Timeouts, crashes, backgrounding, network loss—all paths lead to a resolved state.

### Timeouts

- Operations must enforce timeouts to avoid hanging states.
- Timeout durations are defined in implementation (not in this spec).

## State Model

### Download States (per app)

| State | Description | User Action |
|-------|-------------|-------------|
| `DownloadQueued` | Waiting for download slot (max 3 active) | Cancel available |
| `Downloading` | Actively downloading, shows progress % | Pause/Cancel available |
| `DownloadPaused` | Download paused by user | Resume/Cancel available |
| `Verifying` | Computing hash, shows progress % | Cannot cancel |

**Transitions:**
- `Idle` → tap download → `DownloadQueued` or `Downloading`
- `DownloadQueued` → slot available → `Downloading`
- `DownloadQueued` → cancel → `Idle`
- `Downloading` ↔ `DownloadPaused` (pause/resume)
- `Downloading` → cancel → `Idle` (clears partial file)
- `Downloading` → success → `Verifying`
- `Downloading` → failure/timeout → `Error`
- `Verifying` → success → `AwaitingPermission` or `ReadyToInstall`
- `Verifying` → failure/timeout → `Error`
- App restart while downloading → `Idle` (partial file cleared)

### Permission State (per app)

| State | Description | User Action |
|-------|-------------|-------------|
| `AwaitingPermission` | User must grant "Install unknown apps" | Tap opens Android settings |

**Transitions:**
- `Verifying` success + missing permission → `AwaitingPermission`
- `Verifying` success + has permission → `ReadyToInstall`
- `AwaitingPermission` → permission granted → `ReadyToInstall`
- `AwaitingPermission` → permission denied → `Error`

### Install States (per app)

| State | Description | User Action |
|-------|-------------|-------------|
| `ReadyToInstall` | File verified, queued for install slot | Automatic (no user action) |
| `Installing` | System install dialog shown or processing | Confirm/Cancel dialog |
| `InstallCancelled` | User cancelled dialog, file still ready | "Install (retry)" button |
| `SystemProcessing` | Committed to Android, cannot cancel | Wait for completion |
| `Installed` | Successfully installed | "Open" button |

**Transitions:**
- `ReadyToInstall` → install slot available → `Installing`
- `Installing` → user confirms → continues `Installing`
- `Installing` → user cancels dialog → `InstallCancelled`
- `InstallCancelled` → user taps "Install (retry)" → `Installing`
- `Installing` (silent) → system completes → `Installed`
- `Installing` → failure/timeout → `Error`
- `Installing` → committed + slow → `SystemProcessing`
- `SystemProcessing` → completes → `Installed`
- `SystemProcessing` → failure/timeout → `Error`

### Update State (per app)

- `UpdateAvailable` → start update → `Downloading`
- `Installing` (silent not allowed) → manual dialog flow
  - If the app was originally installed by Zapstore and platform allows, update may be silent

### Uninstall State (per app)

- `Installed` → uninstall → `Uninstalling`
- `Uninstalling` → user confirms → `Idle`
- `Uninstalling` → user cancels → `Installed`
- `Uninstalling` → failure/timeout → `Error`

### Queue State (global)

- Download queue: insertion order (best-effort), max 3 active
- Install queue: insertion order (best-effort), max 1 active
  - Only one install dialog is shown at a time; others wait

## Non-Goals

- iOS/macOS/desktop support (Android only)
- Split APK support
- Background installs without any user awareness

## User-Visible Behavior

### Download

- Progress bar shows percentage (0-100%)
- Pause/resume buttons available during download
- Cancel clears the download
- Multiple apps can download simultaneously (up to 3)
- Pause does not persist across app restarts
- Partial downloads are deleted on app restart

### Verification

- Progress bar shows percentage (0-100%) during hash verification
- Verification cannot be paused or cancelled
- Large APKs (100MB+) may show noticeable verification time

### Install

- System confirmation dialog appears for first-time installs
- If user cancels dialog, shows "Install (retry)" button (no re-download needed)
- Silent install skips dialog when Zapstore is the original installer

### Update

- Same flow as install
- Silent update possible if Zapstore originally installed the app
- If silent update is not allowed, proceed with manual update flow

### Uninstall

- System uninstall dialog appears
- If uninstall succeeds, the app is removed from the installed list
- If uninstall is canceled, there is no change

### Force Update (Certificate Mismatch)

- When app signature changed (different developer/build):
  - Show a certificate mismatch error
  - Force update action offered
  - Tapping shows uninstall dialog first
  - After uninstall, install proceeds automatically
  - Warning: user data in the app will be lost

## Edge Cases

### Network/Download Issues

- On download failure, provide a retry option
- On 404, retry from `cdn.zapstore.dev`, otherwise fail
- If network is lost mid-download, support resume when reconnected

### Verification Failures

- Hash mismatch suggests re-download
- Invalid file (not an APK) shows a clear error

### Install Failures

- Insufficient storage shows a clear error message
- Incompatible device shows a clear "Device incompatible" error message
- Blocked by device policy shows a clear error message
- If the user cancels the dialog, show "Install (retry)" (`InstallCancelled` state)

### Permission Issues

- If install unknown apps permission is missing, show `AwaitingPermission` state
- Tapping opens Android settings to grant permission
- If the user denies permission, show a clear error with instructions

### App Lifecycle

- If the app is backgrounded during install dialog, the dialog reappears on return
- If the app is killed during install, reset UI and clean up temp files on next launch
- If install takes too long, it cannot be canceled once committed

### Concurrent Operations

- Multiple downloads: limited based on device capability (1-4 simultaneous), others queued
- Multiple installs: 1 at a time, others wait in queue
- Queue order: best-effort insertion order (not guaranteed)
- Queue advances automatically after each completion

### Batch Progress

- When operations are in progress, show a summary banner on the updates screen
- Works for both "Update All" and individual update taps
- Banner displays current phase: downloading, verifying, or installing
- Shows completion progress: "3 of 10 updated"
- Shows count of failures if any
- "Update All" button is disabled while operations are in progress
- All progress state is fully derived from operations map:
  - Successful operations transition to `Completed` state (stay in map)
  - Total = operations.length (includes completed)
  - Completed = count of `Completed` operations
  - In-progress = Total - Completed - Failed - Cancelled
  - Phase = derived from operation types currently active
- Terminal states for batch progress: `Completed`, `OperationFailed`, `InstallCancelled`
  - `InstallCancelled` counts as cancelled (user can retry individually, but batch doesn't wait)
- When all operations reach terminal state, banner shows "X of X updated ✓"
- After 3 seconds with no in-progress operations, completed operations auto-clear

### Device Adaptation

- Download concurrency adapts to device RAM to prevent crashes on low-capability devices
- Behavior degrades gracefully on constrained devices, never hangs

## Acceptance Criteria

- [ ] **No operation hangs indefinitely** — every state resolves to success, failure, or cancelled
- [ ] User sees download progress percentage
- [ ] User sees verification progress percentage
- [ ] User can pause and resume downloads
- [ ] User can cancel downloads
- [ ] Verification errors show clear message
- [ ] Install dialog appears for new apps
- [ ] Silent update works for Zapstore-owned apps
- [ ] Certificate mismatch offers force update option
- [ ] Force update uninstalls then installs
- [ ] Backgrounding app preserves install dialog
- [ ] Long installs transition to SystemProcessing (cannot cancel)
- [ ] All errors show actionable messages
- [ ] Multiple downloads queue correctly
- [ ] Multiple installs proceed one at a time
- [ ] Batch progress banner shows during "Update All"
- [ ] "Update All" button disabled while operations in progress

## Notes

- Silent install requires Android 12+ and Zapstore as original installer
- Certificate mismatch requires uninstall (app data lost) - ensure user understands
- Some device policies may block all installs from unknown sources