aios/docs/aios-v2/adr/ADR-006-candidate-persistence-strategy.md

ADR-006：候选持久化采用可替换 SQLite Snapshot

• 状态：已采纳
• 日期：2026-07-20
• 影响范围：Control Plane、Persistence、Deployment、Backup、Recovery、HA 演进

1. 背景

AIOS V2 候选版本需要在服务重启后恢复 Tenant、Agent、Task、Audit 和 Idempotency 状态，同时又必须尽快进入预发布部署与 Bug 修复阶段。

候选阶段如果立即引入完整分布式数据库、消息系统和 HA，会显著扩大开发范围，推迟控制面、Runtime Boundary 和多租户模型的验证。

2. 决策

候选版本使用可替换的 SQLite WAL 原子 Snapshot：

• SQLiteSnapshotRepository 保存版本化 Control Plane Snapshot；
• DurableControlPlaneService 在成功变更后持久化；
• 使用 WAL、synchronous=FULL 和 BEGIN IMMEDIATE；
• 状态目录独立于代码版本；
• 上层 Domain、API、Orchestrator 和 Runtime Contract 不依赖 SQLite 实现。

执行证据使用租户分区 JSON 文件，由 ExecutionTracker 原子写入。

3. 持久化范围

候选 Snapshot 包含：

• Tenant；
• Agent；
• Task；
• Audit；
• Idempotency。

独立 Evidence 目录包含：

• claim；
• heartbeat；
• progress；
• blocker；
• commit；
• test_status；
• result。

4. 选择理由

• 无额外外部依赖；
• 易于快速部署和回滚；
• 支持事务、WAL 和完整性检查；
• 可以验证上层控制面和 Runtime Contract；
• 便于在预发布阶段复现和修复 Bug；
• 可通过 Repository 边界替换为生产数据库。

5. 备选方案

方案 A：候选阶段直接使用 PostgreSQL 集群

暂不采用原因：会增加部署、迁移、HA、Secret、网络和容量范围，延迟核心架构验证。

方案 B：继续使用纯内存状态

拒绝原因：服务重启会丢失权威状态，无法进入预发布。

方案 C：每个模块各自使用 SQLite

拒绝原因：会形成多个事实源和跨模块事务问题。

方案 D：将完整状态写入 Git

拒绝原因：运行状态不应成为 Git 内容，可能暴露敏感业务数据并造成提交风暴。

6. 正面影响

• 候选版具备重启恢复能力；
• 状态与代码版本解耦；
• 回滚默认只切换代码，不覆盖新状态；
• 可快速进入预发布测试；
• 生产后端替换不改变上层 Contract。

7. 负面影响与风险

• SQLite 主要适用于单进程候选部署；
• 尚未提供多实例写入和分布式锁；
• 租户隔离是逻辑隔离，不是 RLS 或物理隔离；
• 大规模任务、审计和并发容量尚未验证；
• Evidence 文件数量增长需要归档策略；
• Snapshot 粒度可能导致状态增长后的写放大。

8. 生产迁移要求

生产数据层替换必须满足：

1. 保持 Control Plane Domain/API Contract 不变；
2. 提供 schema migration；
3. 提供租户 RLS 或物理隔离；
4. 提供备份、恢复、PITR 和灾难恢复；
5. 提供 HA、多实例并发和故障转移；
6. 提供容量、延迟和锁等待测试；
7. 保持 Audit 与 Evidence 可追踪；
8. 提供从 SQLite Candidate 到生产后端的数据迁移工具；
9. 通过新的 ADR 说明生产持久化决策。

9. 回滚策略

• 回滚前备份 /var/lib/aios-v2；
• 默认只回滚代码；
• 状态恢复必须由 Owner 显式授权；
• 恢复前必须验证 Snapshot schema 兼容性；
• 回滚后执行 SQLite PRAGMA quick_check 和 AIOS Healthcheck。

10. 验收要求

候选版至少通过：

• 创建 Tenant、Agent、Task；
• 服务重启；
• 读取恢复后的 Task；
• Idempotency 仍有效；
• Audit 仍存在；
• SQLite quick_check=ok；
• 状态目录权限正确；
• 回滚演练不丢失新增状态。

11. 实现与测试映射

• Repository：active-runtime/app/aios_v2/persistence.py
• 应用入口：active-runtime/app/aios_v2/app.py
• Evidence：active-runtime/app/aios_v2/execution_tracking.py
• 测试：tests/aios_v2_candidate/test_candidate_flow.py
• 健康检查：deploy/aios-v2/healthcheck/check.sh
• 回滚：deploy/aios-v2/rollback/rollback.sh

12. 更新触发条件

以下变化必须更新或替代本 ADR：

• 引入生产数据库；
• 支持多实例写入；
• 修改 Snapshot 格式；
• 改变 Evidence 存储；
• 增加 RLS、HA、分片或事件溯源；
• 修改状态回滚策略。