import Foundation /// 一次计划执行的结果:动作是否全部按序成功,以及本次执行占用的并发流 /// 代际。占用代际供收敛票据推进 flow 分量,取代调用方对 execute 内部 /// 「恰好自增一次」时序的依赖(原 `flowGeneration + 1` 手算)。 struct RuntimeExecutionOutcome { /// 本次执行占用的 `flowGeneration`。 let flow: Int /// 全部计划动作是否按序成功。 let succeeded: Bool } /// 收敛票据:运行时收敛操作的代际快照。入口捕获三个并发代际,之后每步 /// 推进用它判定「从入口到现在,并发流 / 模式切换 / 运行时派生是否前进了, /// 会话内 agent 意图是否仍开启」;被更新提交或新意图取代的旧收敛不得再 /// 变更运行时状态或写契约。 /// /// 四项失效事实由票据恒全查,不随调用路径增减——「什么会使一次收敛失效」 /// 是票据的固有语义(逐路径手选子集曾让 agent 关闭在 mode 切换的健康门 /// await 窗口内被误分类为失败并触发复活性的 restore)。各路径只负责捕获 /// 与推进时机:flow 分量在 execute 后以实际占用值推进,mode 切换路径在 /// 派生后推进 preparation 分量(派生自身会推进它),rules 部署在推进 mode /// 代际之后捕获。 private struct ConvergenceTicket: Equatable { /// 并发流代际;每次 execute 之后由调用方以实际占用值推进。 var flow: Int /// 模式切换代际;捕获后不再变化。 let mode: Int /// 运行时文档派生代际;每次派生之后由调用方以当前值推进。 var preparation: Int } extension ProxyRuntimeController { /// 以当前代际捕获收敛票据。 private func convergenceTicket() -> ConvergenceTicket { ConvergenceTicket( flow: flowGeneration, mode: modeChangeGeneration, preparation: runtimePreparationGeneration) } /// 票据是否仍代表当前收敛:并发流 / 模式切换 / 派生三个代际均未前进, /// 且会话内 agent 意图仍开启。 private func convergenceIsCurrent(_ ticket: ConvergenceTicket) -> Bool { ticket.flow == flowGeneration && ticket.mode == modeChangeGeneration && ticket.preparation == runtimePreparationGeneration && settings.agentEnabled } /// 派生文档对当前运行时是否无事可做(GLOSSARY.md「有效值未变的提交不做 /// 运行时收敛」):磁盘契约与派生字节逐位相同、agent 已注册且 wrapper /// 存活、控制器处于健康运行态——计划层动作序列为空即幂等跳过。判定在 /// 置 `starting` 之前进行,跳过路径不闪状态、不重走健康门;磁盘漂移或 /// wrapper 失踪时动作序列自然非空,走完整 deploy 自愈。 private func convergencePlanIsEmpty( _ document: SslocalRuntimeDocument, preparedContract: PreparedRuntimeContract? ) -> Bool { switch state { case .running, .firewallBlocked: break case .off, .starting, .launchFailed, .requiresApproval, .serviceFailed: return false } let actions = ProxyRuntimePlan.actions( intent: .run(document), agentStatus: agent.status, wrapper: wrapperState(), contractOnDisk: runtimeFileStore.readData(), preparedContract: preparedContract) return actions.isEmpty } /// 统一的设置持久化 epilogue:保存失败不静默偏离持久化事实——记录日志、 /// 呈现 `serviceFailed(.persistence)`,调用方放弃本次收敛。 func persistSettings(_ proposed: ProxySettings) -> Bool { do { try settingsStore.save(proposed) return true } catch { RuntimeLog.emit(.runtimePersistFailed(detail: String(describing: error))) state = .serviceFailed(.persistence) return false } } /// reexpand 三-case 开关的收敛主体(显式收敛、设置保存、启动重同步共用): /// deployed → 部署派生文档;目标失效 → 清除并按意图收敛;无目标 → 空监听。 /// 幂等跳过由 apply 层的 plan 空判定承担;目录重校验(跳过名单、目标失效 /// 清除)已在 `reexpand` 完成,不受其影响。 func convergeToReexpanded(_ catalog: ConfigurationCatalog) async { guard catalogSnapshotReader.isCatalogAvailable else { return } switch reexpand(in: catalog) { case .deployed(let configuration): await deploy(configuration.document) case .clearedAndStopped(let failure): await handleCleared(failure) case nil: await deployListeningWithoutTarget() } } /// 一个意图入口隐藏派生、执行政策和失败呈现;调用者不组合执行选项。 enum RuntimeConvergenceIntent { case deployment(SslocalRuntimeDocument) case modeTransition case savedRules } enum ConvergenceResult { case applied case unchanged /// 派生或部署失败;失败呈现已经处理。 case failed /// 被新意图取代,不得发布旧结果。 case superseded } @discardableResult func convergeRuntime(_ intent: RuntimeConvergenceIntent) async -> ConvergenceResult { guard catalogSnapshotReader.isCatalogAvailable else { return .failed } switch intent { case .deployment(let source): return await convergeDeployment(source) case .modeTransition: return await convergeModeTransition() case .savedRules: return await convergeSavedRules() } } private func convergeDeployment(_ source: SslocalRuntimeDocument) async -> ConvergenceResult { if settingsUnreadable { RuntimeLog.emit(.activationFailed(reason: "settings unreadable")) _ = await execute(.stop, document: nil) lastDocument = nil skippedServers = [] state = .launchFailed(.unreadableSettings) await systemProxyObserver.holdSystemProxyIntent() return .failed } let contract: PreparedRuntimeContract do { contract = try PreparedRuntimeContract(await runtimeDocument(source, for: proxyMode)) } catch RulePreparationError.superseded { return .superseded } catch { RuntimeLog.emit(.runtimePersistFailed(detail: String(describing: error))) state = .serviceFailed(.runtimeFile) return .failed } var ticket = convergenceTicket() return await apply(contract.document, ticket: &ticket, policy: .deployment) } private func convergeModeTransition() async -> ConvergenceResult { var ticket = convergenceTicket() guard settings.agentEnabled, state != .off, let current = lastDocument ?? runtimeFileStore.loadDocument() else { systemProxyObserver.modeTransitionAwaitingRuntime() return .unchanged } let next: SslocalRuntimeDocument do { next = try await runtimeDocument(current, for: proxyMode) } catch RulePreparationError.superseded { return .superseded } catch { RuntimeLog.emit(.runtimePersistFailed(detail: String(describing: error))) ticket.preparation = runtimePreparationGeneration state = .serviceFailed(.runtimeFile) return .failed } // 派生会推进 preparation;仅该意图在派生前捕获了收敛票据。 ticket.preparation = runtimePreparationGeneration let alreadyRunning: Bool switch state { case .running, .firewallBlocked: alreadyRunning = true default: alreadyRunning = false } if next.aclRuntime == current.aclRuntime, runtimeFileStore.readFailure() == nil, alreadyRunning { // 保留原有特殊路径:无系统代理意图即结束;否则只检查健康,不部署或恢复。 guard settings.systemProxyEnabled else { return .unchanged } state = .starting return await presentLaunchHealth(next) ? .applied : .failed } let result = await apply(next, ticket: &ticket, policy: .modeTransition) return result } private func convergeSavedRules() async -> ConvergenceResult { guard proxyMode == .rule, settings.agentEnabled, state != .off, let current = lastDocument ?? runtimeFileStore.loadDocument() else { return .unchanged } let revision = ruleDocuments.revision let next: SslocalRuntimeDocument do { next = try await runtimeDocument(current, for: proxyMode) } catch RulePreparationError.superseded { return .superseded } catch { RuntimeLog.emit(.runtimePersistFailed(detail: String(describing: error))) ruleApplicationFailure = .service(.runtimeFile) return .failed } guard next.aclRuntime != current.aclRuntime || ruleApplicationFailure != nil else { ruleApplicationFailure = nil return .unchanged } modeChangeGeneration += 1 var ticket = convergenceTicket() let result = await apply(next, ticket: &ticket, policy: .savedRules) switch result { case .applied, .unchanged: if revision == ruleDocuments.revision { ruleApplicationFailure = nil } case .superseded: break case .failed: let failure = ProxyRuntimeFacts(state: state).failure ?? .service(.runtimeFile) if convergenceIsCurrent(ticket), revision == ruleDocuments.revision { ruleApplicationFailure = failure } } return result } /// 三种意图的执行差异只在 module 内选择,不能由调用者拼成任意组合。 private enum DeploymentPolicy { case deployment case modeTransition case savedRules } /// 共用执行脊柱;票据不越过意图 seam。 private func apply( _ document: SslocalRuntimeDocument, ticket: inout ConvergenceTicket, policy: DeploymentPolicy ) async -> ConvergenceResult { let contract = try? PreparedRuntimeContract(document) if runtimeFileStore.blocksDeployment(document) { state = .serviceFailed(.agent) await systemProxyObserver.holdSystemProxyIntent() return .failed } if convergencePlanIsEmpty(document, preparedContract: contract) { RuntimeLog.emit(.contractUnchanged) ruleApplicationFailure = nil return .unchanged } guard convergenceIsCurrent(ticket) else { return .superseded } lastDocument = document state = .starting let execution = await execute(.run(document), document: document, preparedContract: contract) ticket.flow = execution.flow guard convergenceIsCurrent(ticket) else { return .superseded } guard execution.succeeded else { if state != .requiresApproval, runtimeFileStore.receiptIdentity(for: document) != nil { await failDeployment(ticket: &ticket) } return .failed } let healthy = await presentLaunchHealth( document, requiresReceipt: policy != .deployment || document.aclRuntime != nil, convergeProxyOnSuccess: policy == .deployment, preserveProxyOnFailure: false, preparedContract: contract) guard convergenceIsCurrent(ticket) else { return .superseded } guard healthy else { await failDeployment(ticket: &ticket) return .failed } do { try runtimeFileStore.settleSuccessfulDeployment() } catch { state = .serviceFailed(.runtimeFile) await failDeployment(ticket: &ticket) return .failed } lastDocument = document ruleApplicationFailure = nil switch policy { case .modeTransition: await systemProxyObserver.convergeSystemProxy(forceApply: true) case .savedRules: await systemProxyObserver.convergeSystemProxy() case .deployment: break } return .applied } /// 发布后失败保留配置及失败身份,停止服务但不改写两个开关意图。 private func failDeployment(ticket: inout ConvergenceTicket) async { guard convergenceIsCurrent(ticket) else { return } var failureState = state do { try runtimeFileStore.recordFailure(reason: "GUI deployment verification failed") } catch { failureState = .serviceFailed(.runtimeFile) } let stopped = await unregisterFailedDeployment() guard convergenceIsCurrent(ticket) else { return } if stopped { state = failureState } else { state = .serviceFailed(.agent) } await systemProxyObserver.holdSystemProxyIntent() } private func unregisterFailedDeployment() async -> Bool { do { try agent.unregister() } catch { return false } await waitForWrapperExit() return wrapperState() == .notRunning && !runtimeFileStore.hasUnconfirmedChild } }