Add durable update coordination and next-launch reconciliation

Co-authored-by: JusterZhu <11714536+JusterZhu@users.noreply.github.com>

Author: Copilot

README-EN.md

@@ -22,6 +22,7 @@ The project uses composable abstractions so you can replace version comparison,
 - **Extensible architecture**: `IVersionComparer`, `IUpdateDownloader`, `IHashValidator`, `IApkInstaller`, and more are replaceable.  
 - **Resumable downloading**: sidecar metadata + streaming writes for better reliability on unstable networks.  
 - **Unified event model**: built-in validation, progress, completion, and failure events for UI/log integration.  
+- **Durable coordinator**: complete-attempt serialization, pending-install tracking, next-launch version confirmation and explicit recovery.
 
 ## Quick Start
 
@@ -53,7 +54,7 @@ dotnet add package GeneralUpdate.Avalonia.Android
 dotnet test tests/GeneralUpdate.Avalonia.Android.Tests/GeneralUpdate.Avalonia.Android.Tests.csproj
 ```
 
-### Basic Usage
+### Low-level Usage
 
 ```csharp
 using GeneralUpdate.Avalonia.Android;
@@ -91,6 +92,63 @@ if (check.Success && check.UpdateFound && check.PackageInfo is { } packageInfo)
 }
 ```
 
+### Coordinated Updates and Next-launch Confirmation
+
+For new integrations, use `GeneralUpdateBootstrap.CreateCoordinator(options)` instead of manually chaining the three
+low-level operations. It owns the bootstrap it creates, serializes the complete workflow, and records a durable intent
+**before** launching Android's installer. Keep the coordinator for the host's update-service lifetime.
+
+```csharp
+using GeneralUpdate.Avalonia.Android.Enums;
+
+await using var coordinator = GeneralUpdateBootstrap.CreateCoordinator(options);
+coordinator.StateChanged += (_, args) =>
+    Console.WriteLine($"{args.Result.Stage}: {args.Result.Outcome}");
+
+// Read the actual installed app version from the host, not the server's target version.
+var startup = await coordinator.ReconcileAsync(installedVersion, cancellationToken);
+if (startup.Outcome == UpdateCoordinatorOutcome.NoPendingUpdate)
+{
+    // Invoke from the host's update command/policy, not from a notification callback.
+    var result = await coordinator.RunAsync(installedVersion, cancellationToken);
+    // InstallerLaunched is a handoff; Updated is reported only by reconciliation.
+}
+```
+
+| Operation | Contract |
+|---|---|
+| `RunAsync(currentVersion, ct)` | Check → download/verify → persist intent → launch installer. Existing pending state returns `PendingUpdateExists` without another install. |
+| `ReconcileAsync(currentVersion, ct)` | Offline startup check. Installed version equal to or newer than the pending target returns `Updated`; the old version remains `AwaitingInstallation` or `RecoveryRequired`. No intent returns `NoPendingUpdate`. |
+| `RetryAsync(currentVersion, ct)` | Explicit recovery of a pending attempt: reconcile first, then rediscover and verify the same target. A changed server target returns `RecoveryRequired` without overwriting the earlier handoff. Never installs a persisted path or reuses stored credentials. Use `RunAsync` again after failures that left no pending intent. |
+| `AbandonAsync(ct)` | Explicitly forget pending tracking, including corrupt state. Does **not** cancel Android installation, delete APKs, or roll back the app/data. |
+
+`StateChanged` reports named stages and a terminal outcome, rather than treating a generic “completed” notification as
+installation success. Pass an `IUpdateEventDispatcher` to `CreateCoordinator` for Avalonia UI dispatch, as shown below.
+Check `Outcome` and `FailureReason`: `InstallerLaunched`, `NoUpdate` and `Updated` have different meanings.
+Subscribe to `AddListenerDownloadProgressChanged` for byte/speed progress and register `AddListenerUpdatePrecheck` before
+starting operations for optional-update policy (`true` still means skip; forced updates bypass it). These are forwarded
+through the coordinator, so factory users do not need access to its underlying bootstrap.
+The legacy `CreateDefault` / `IAndroidBootstrap` API remains available and unchanged.
+
+The factory stores only a versioned attempt ID, original/target versions, timestamp and handoff phase in
+`<NoBackupFilesDir>/generalupdate/pending-update.json`. No APK path, URL, package credentials or exception is serialized.
+The file is atomically replaced from a flushed temporary file in the same directory. Corrupt, oversized or unknown-schema state
+fails closed instead of silently starting another update. A write failure before handoff prevents installer launch; uncertainty
+after handoff remains pending for reconciliation. This protects process-restart recovery, not arbitrary storage hardware failure.
+For a custom location/store, pass `pendingStore: new JsonPendingUpdateStore(privatePersistentPath)` (services namespace);
+do not place the record in a cache, shared downloads folder or backup-restored location.
+The default JSON store holds an exclusive `.lock` file lease for the entire workflow, preventing cooperating coordinator
+instances/processes using the same state path from overwriting each other's intent. Do not delete that lock file while in use.
+Custom stores can implement `IPendingUpdateStoreLeaseProvider`; otherwise the host must enforce a single coordinator.
+Separate state paths do not protect a shared APK staging directory, so use one coordinator per staging directory.
+
+**Recovery policy:** reconcile on each app launch and when returning from the installer, using the actual installed version.
+An unchanged version is not proof the user rejected installation—it may still be in progress. Offer explicit retry or abandonment;
+do not automatically loop on either. If the server now offers a different target, reconcile the earlier handoff or explicitly abandon
+its tracking before starting a new attempt. A successful reconciliation confirms the observed version, not application health or successful
+data migration. Silent installation, automatic relaunch, OS downgrade/rollback, signed manifests and APK identity preflight are not
+provided. The host still supplies installation permissions/FileProvider configuration and must validate device behavior.
+
 ### Server-Driven Version Validation
 
 `ValidateAsync(currentVersion, cancellationToken)` only needs the version installed on the device: the component queries
@@ -234,12 +292,13 @@ Cancellation while waiting for the gate still throws `OperationCanceledException
 cancellation during verification returns a canceled result. Notification exceptions are logged and isolated, whereas a pre-check
 exception produces a failed validation result. Installed-version confirmation is still not part of disposal or a completed event.
 
-Use a single host coordinator and a private staging directory for the full check → download/verify → install sequence.
+Use a single coordinator and a private staging directory for the full check → download/verify → install sequence.
 Only hand the returned verified path to the installer; do not modify or remove the APK while installation may be reading it.
 The public installer method also supports independent calls, so it does not establish verification provenance for arbitrary paths.
-Persist the target version before handoff, reconcile the actual installed version on next launch, and clear obsolete staging files
-only when no update/installer is using them. Keep resumable partial files for a bounded retention period.
-Permission prompting, actual installation outcome, app relaunch and recovery from a bad release or data migration remain host/platform
+`CreateCoordinator` handles target-version persistence and next-launch reconciliation; call `ReconcileAsync` at startup with the
+actual installed version. With the low-level API, implement that tracking in the host. Clear obsolete staging files only when no
+update/installer is using them. Keep resumable partial files for a bounded retention period.
+Permission prompting, app relaunch and recovery from a bad release or data migration remain host/platform
 responsibilities; they are not made reliable merely by a successful installer intent.
 
 ## Source Review and Production Readiness
@@ -260,13 +319,20 @@ retained with revision-pinned evidence; **its defect descriptions refer to the p
 | Callback errors | Synchronous notification subscriber, dispatcher and logger exceptions cannot replace operation outcomes. A throwing pre-check fails validation instead of bypassing host policy. | `BootstrapLifecycleTests`: throwing subscribers/loggers/dispatchers and fail-closed pre-check. |
 | Package license | NuGet metadata now declares Apache-2.0, matching the existing LICENSE. | MSBuild property evaluation against LICENSE. |
 
-Validation after remediation: **160/160 core tests passed** (no failures or skips), including HEAD-rejection fallback and
+Validation of the earlier remediation: **160/160 core tests passed** (no failures or skips), including HEAD-rejection fallback and
 authentication-policy failures returning terminal validation results before provider/network invocation.
-The local Android build could not run because the `android` workload is missing (`NETSDK1147`); current PR CI requires approval.
+At that stage the local Android build was blocked by the missing `android` workload (`NETSDK1147`).
 Tests for these fixes use the existing .NET core test project; they are not Android device installation tests.
-The fixes do **not** add desktop support, installer completion callbacks, automatic restart/rollback, independent manifest signing,
-APK identity preflight, persisted workflow state, directory-wide coordination, or a runnable Avalonia sample.
-UI dispatch, verified-path handoff, cache retention and next-launch reconciliation remain explicit host responsibilities described above.
+The coordinator addition now provides persistent intent tracking, complete-attempt orchestration, offline installed-version
+reconciliation, explicit retry/abandon recovery and stage-specific outcomes (see the new integration section).
+Coordinator validation: **57 focused tests and all 217 core tests passed**. With the Android workload installed,
+the Android library **Release build succeeded**, including the default factory. Coverage includes real HTTP downloader/storage/hash
+integration with fake transport/installer, persistent state across recreated coordinators, uncertain handoff, concurrency and recovery.
+The build retains the existing dependency advisory noted below and three XML-documentation warnings. PR CI still requires approval;
+no device/emulator installation, restart or application-health validation was performed.
+The fixes do **not** add desktop support, native installer completion callbacks, automatic restart/rollback, independent manifest signing,
+APK identity preflight, or a runnable Avalonia sample.
+UI dispatch, providing the actual installed version, invoking reconciliation at startup and cache retention remain host responsibilities.
 Metadata-provider/storage extensibility and production dependency/device validation remain follow-up work, not silently resolved findings.
 
 ### Historical scope and evidence (before remediation)
@@ -373,7 +439,9 @@ Snapshots are in-memory and do not establish verified-package provenance or cras
 shutdown and post-install reconciliation. The default logger is no-op; production hosts need stage/failure telemetry without credentials.
 
 **Dependency risks:** [AndroidX Core is the runtime package dependency; SourceLink is private build tooling][review-project].
-No dependency advisory audit or transitive inventory was performed for this assessment, so version age alone is not a vulnerability finding.
+The original assessment did not include a dependency advisory audit or transitive inventory.
+The subsequent coordinator build reports a pre-existing `Microsoft.Build.Tasks.Git` 8.0.0 advisory
+([GHSA-23fw-v26w-5fgq](https://github.com/advisories/GHSA-23fw-v26w-5fgq)); this change does not update dependencies.
 Validate the resolved dependency graph, Android workload/toolchain compatibility and packaged artifact on supported devices before release.
 
 ### Original validation evidence and remaining production release gates

README.md

@@ -22,6 +22,7 @@
 - **可扩展架构**：`IVersionComparer`、`IUpdateDownloader`、`IHashValidator`、`IApkInstaller` 等均可替换。  
 - **断点续传下载**：支持 sidecar 元数据与流式写入，提升弱网场景稳定性。  
 - **统一事件通知**：提供验证、进度、完成、失败等事件用于 UI/日志集成。  
+- **持久化协调器**：完整流程串行化、待安装状态跟踪、下次启动版本确认以及显式恢复。
 
 ## 快速开始
 
@@ -91,6 +92,51 @@ if (check.Success && check.UpdateFound && check.PackageInfo is { } packageInfo)
 }
 ```
 
+### 完整流程协调与下次启动确认
+
+新接入可使用 `GeneralUpdateBootstrap.CreateCoordinator(options)`，无需自行串联三个低层调用。
+协调器按“查询 → 下载并验证 → 持久化意图 → 拉起安装器”执行；`CreateDefault` 低层 API 保持兼容。
+
+```csharp
+using GeneralUpdate.Avalonia.Android.Enums;
+
+await using var coordinator = GeneralUpdateBootstrap.CreateCoordinator(options);
+coordinator.StateChanged += (_, args) =>
+    Console.WriteLine($"{args.Result.Stage}: {args.Result.Outcome}");
+
+// installedVersion 必须来自当前实际安装的应用，不能传服务端目标版本。
+var startup = await coordinator.ReconcileAsync(installedVersion, cancellationToken);
+if (startup.Outcome == UpdateCoordinatorOutcome.NoPendingUpdate)
+{
+    // 由宿主更新命令/策略触发，不要在通知回调里同步等待此调用。
+    var result = await coordinator.RunAsync(installedVersion, cancellationToken);
+}
+```
+
+- `RunAsync`：串行执行整个流程；存在待确认记录时返回 `PendingUpdateExists`，不会覆盖并再次安装。
+- `ReconcileAsync`：离线核对待确认目标版本。实际版本达到或超过目标才返回 `Updated`；
+  仍为旧版本则返回 `AwaitingInstallation` 或 `RecoveryRequired`，没有记录为 `NoPendingUpdate`。
+- `RetryAsync`：显式恢复，先核对安装版本，再重新查询服务器并下载验证同一目标；若服务端目标改变，
+  返回 `RecoveryRequired` 并保留原交接记录，需先核对或明确放弃后再开始新尝试。
+  不会安装从磁盘恢复的任意路径，也不会重复安装已经达到的目标版本。
+- `AbandonAsync`：显式放弃跟踪，也可清除损坏状态；不取消系统安装、不删除 APK、不回滚应用或数据。
+
+默认状态保存在 `<NoBackupFilesDir>/generalupdate/pending-update.json`，不是可被清理的 APK 缓存。
+只记录 schema、尝试 ID、原始/目标版本、时间和交接阶段，不保存 URL、APK 路径、凭据或异常。
+状态通过同目录临时文件刷新后原子替换；安装前保存失败就停止，安装交接后的不确定状态留待下次启动核对。
+损坏、过大或未知 schema 不会被当成“无更新”，而是明确失败。可注入 `IPendingUpdateStore`；
+自定义文件位置必须是应用私有持久化目录，不应参与备份恢复。
+默认 JSON 存储对整个流程持有 `.lock` 文件独占租约，协调使用同一路径的实例/进程；使用中不要删除锁文件。
+自定义存储可实现 `IPendingUpdateStoreLeaseProvider`，否则宿主必须保证单协调器。不同状态路径不能保护共用的 APK 目录。
+
+保持协调器与宿主更新服务相同生命周期，释放时可 `await DisposeAsync()`。
+`StateChanged` 区分阶段与最终 `Outcome`，`InstallerLaunched` 仅表示交接，不能展示为安装成功。
+UI 线程仍需传入 `IUpdateEventDispatcher`；应用每次启动及从安装器返回时调用 `ReconcileAsync`。
+协调器还转发 `AddListenerDownloadProgressChanged` 和 `AddListenerUpdatePrecheck`，无需获取内部 bootstrap；
+pre-check 应在开始操作前注册，仍保持 `true` 表示跳过、强制更新不调用的兼容语义。
+旧版本仍在运行不等于用户拒绝安装，可能尚未完成；应由用户明确选择重试或放弃，不要自动循环。
+此核心闭环确认的是实际安装版本，不是应用健康或数据迁移成功；静默安装、自动重启、系统回滚仍不提供。
+
 ### 服务端版本校验
 
 `ValidateAsync(currentVersion, cancellationToken)` 只需要当前应用的版本号：组件按
@@ -174,7 +220,12 @@ ZIP、差分包、驱动包不会交给 Android 安装器；`body` 为空数组
 [英文评审正文](https://github.com/GeneralLibrary/GeneralUpdate.Avalonia/blob/main/README-EN.md#source-review-and-production-readiness)。
 下表保留原始评审背景；当前已按项修复 B1–B5、S1、回调异常隔离及许可证元数据，详见正文的修复状态表。
 新增回归测试覆盖重试/续传、超时与取消、状态及清理失败、资源释放竞争、认证源限制和重定向拒绝。
-修复后的核心测试 **160/160 通过**；本地 Android 构建因缺少工作负载（`NETSDK1147`）受阻，当前 PR CI 尚需批准。
+此前缺陷修复后的核心测试 **160/160 通过**；当时本地 Android 构建因缺少工作负载（`NETSDK1147`）受阻。
+本次协调器新增验证：**57 个专项测试、全部 217 个核心测试通过**；安装 Android 工作负载后，
+包含默认工厂的 Android 库 **Release 构建成功**。覆盖真实下载器、文件及哈希处理与模拟网络/安装器、
+协调器重建后的持久化确认、不确定交接、并发及恢复。构建仍报告已有的
+`Microsoft.Build.Tasks.Git` 8.0.0 安全公告（[GHSA-23fw-v26w-5fgq](https://github.com/advisories/GHSA-23fw-v26w-5fgq)）
+和 3 个 XML 文档警告；未修改依赖版本，PR CI 仍需批准，尚未进行真机/模拟器安装、重启或应用健康验证。
 这些测试不等价于真机安装或自动回滚验证。
 
 | 维度 | 结论与风险 | 建议 |
@@ -193,8 +244,9 @@ ZIP、差分包、驱动包不会交给 Android 安装器；`body` 为空数组
 没有证据支持把旧的“写流未关闭即重命名”问题、Zip Slip 或 Android 签名绕过列为当前缺陷。
 
 **生产结论：不能直接作为开箱即用的跨平台、全闭环生产更新器。**
-上述修复并未新增桌面支持、安装完成确认、自动重启/回滚、独立清单签名、APK 身份预检或可运行的 Avalonia 示例。
-仍需限定可信更新源、补齐宿主协调及恢复逻辑，并通过 Android 真机故障场景验收后，
+新增协调器已提供持久化意图、下次启动的安装版本确认、完整流程串行化及重试/放弃恢复。
+仍未新增桌面支持、原生安装器完成回调、自动重启/回滚、独立清单签名、APK 身份预检或可运行的 Avalonia 示例。
+仍需限定可信更新源、在宿主启动时调用核对并处理平台权限和健康恢复，并通过 Android 真机故障场景验收后，
 作为 Android 更新基础组件使用；详细上线门槛见完整评审。
 
 ## 目录结构