/**
 * Upgrade Reconcile — state IO。
 *
 * 读写 .soloforge/upgrade/** 下的升级状态与计划文件。
 * 只写派生状态目录，不触碰用户业务文件。
 *
 * 职责边界：
 * - 负责：升级状态/计划的读写与 acknowledge 确认（同步读 JSON + 原子写）+ HMAC provenance 签发/验签（经 SignatureProvider）
 * - 不负责：计划编排/清理逻辑、不触碰用户业务文件
 *
 * 被谁调用：upgrade_reconcile/bypass.ts（readUpgradeStateTolerant）、plan.ts（readUpgradeStateTolerant/writeUpgradeState/writeUpgradePlan）、cleanup.ts（readUpgradePlan/writeUpgradeState/acknowledgeUpgrade/readUpgradeStateTolerant）、handle_deliver（readUpgradeState）、doctor_service（readUpgradeState）
 * 调用谁：internals（UPGRADE_STATE_FILE/UPGRADE_PLANS_DIR/writeJsonAtomic）、revision（currentUpgradeRevisions）、shared/helpers（readStateJsonSync）、signature_provider（SignatureProvider）
 *
 * 数据流：projectRoot → 拼路径 + JSON 原子写/同步读 → UpgradeState / UpgradePlan；acknowledge → revisions → status=acknowledged；HMAC:写时签/读时验(失败 throw,经 SignatureProvider)
 * 持久化：读写 .soloforge/upgrade/state.json 与 .soloforge/upgrade/plans/{plan_id}.json（经 internals.writeJsonAtomic 原子写）
 *
 * HMAC 与读取侧 throw 语义(升级状态强制确认防伪造):
 *  upgrade state 的 mandatory_impacts 是 handle_deliver 的**唯一**强制确认阻断来源,无 HMAC 则 AI 可经解释器 fs
 *  (`node -e fs.writeFileSync('.soloforge/upgrade/state.json',{mandatory_impacts:[]})`)伪造空强制项绕交付门禁。
 *  故与 gate/review/waiver 对齐:写时签、读时验。验签失败(伪造/损坏)**throw** 而非返 null——因 `?? []` 默认空会放行,
 *  必须 fail-closed 让 handle_deliver 捕获后阻断。文件缺失仍返 null(合法"无升级")。无 secret(init 前)不签不验靠 schema。
 *
 * Layer2 签名边界:state_io 经 SignatureProvider 签名/验签,不直接读 secret。所有读写函数因此为 async(provider IPC)。
 * provider 按 projectRoot 缓存(module-level),避免 middleware 热路径每次工具调用反复 spawn 签名服务子进程(ipc 模式)。
 */
import type { UpgradeState, UpgradePlan } from "./types.js";
export declare function readUpgradeState(projectRoot: string): Promise<UpgradeState | null>;
/** 宽松读(信息类调用点用):HMAC 校验失败/损坏返 null 而非 throw,避免诊断/展示/bypass 判定路径因损坏状态炸断。
 *  安全关键读取(handle_deliver 的 mandatory_impacts 判定)用 strict 版 readUpgradeState——损坏必须 throw 让 deliver 阻断。 */
export declare function readUpgradeStateTolerant(projectRoot: string): Promise<UpgradeState | null>;
export declare function writeUpgradeState(projectRoot: string, state: UpgradeState): Promise<void>;
export declare function writeUpgradePlan(projectRoot: string, plan: UpgradePlan): Promise<void>;
export declare function readUpgradePlan(projectRoot: string, planId: string): Promise<UpgradePlan | null>;
/** 宽松读(信息类调用点用,如 cleanup 的 status 回填):HMAC 失败/损坏返 null。ack 路径用 strict readUpgradePlan(伪造 plan 须 throw 阻断 ack)。 */
export declare function readUpgradePlanTolerant(projectRoot: string, planId: string): Promise<UpgradePlan | null>;
export declare function acknowledgeUpgrade(projectRoot: string, planId: string): Promise<UpgradeState>;