chore: harden sqlite-first lightweight persistence

[liujuanjuan1984]

背景

本 PR 收敛 #383 里围绕轻量持久化路径的实现与文档边界，目标保持不变：

• 本地默认 SQLite
• 单实例为主
• 轻量 durable state
• 不引入 Alembic 或复杂 DBA 运维负担

变更

migration / state-store

• 抽出并收敛 schema version helper，保持 migration wiring 轻量化
• 为 schema version 首次并发写入补 IntegrityError -> update 兜底
• 将 pending session claim 持久化语义从相对 TTL 收敛为绝对 expires_at
• 保留 legacy updated_at 记录的兼容读取与清理路径
• 为 pending claim 过期清理、interrupt recovery 列表查询、interrupt tombstone 清理补最小必要索引
• 将 session / owner / pending-claim / interrupt-request 写入统一到共享 upsert / IntegrityError fallback helper

task-store / runtime

• 为默认 SQLite 持久化路径补父目录创建、WAL、busy_timeout、synchronous=NORMAL
• 为 database task-store 收紧 terminal write guard，保持 first-terminal-state-wins 语义
• 启动期输出轻量持久化摘要日志，显式记录 backend、共享 scope、脱敏后的 database URL 与 SQLite 本地 durability profile

docs / tests

• 文档明确 A2A_TASK_STORE_BACKEND / A2A_TASK_STORE_DATABASE_URL 配置的是统一轻量持久化后端
• 文档进一步收紧为 SQLite-first 单实例定位，不把其它 dialect 路径表述为正式部署承诺
• 补充 migration、并发写入兜底、绝对过期时间、索引补齐、启动摘要日志等回归测试

相关提交

• f45cb62 chore: harden lightweight persistence paths
• cd2effc chore: refine sqlite-first persistence boundaries

验证

• ./scripts/doctor.sh
• 504 passed
• total coverage 91.25%

关联

• Closes [Chore] 收敛 state-store migration helper 与 schema version 幂等边界 #383
• Related [Architecture] 基于 A2A 与 Python 最佳实践审查 opencode-a2a 的长期优化方向 #367

[liujuanjuan1984]

独立审查结论

本次基于 main...HEAD 独立复核 #384 的代码与文档改动后，未发现阻塞性问题。

整体判断：

• 改动范围与 #383 想解决的轻量持久化问题基本对齐，没有明显偏题
• 实现方式整体是增量式收敛，没有把当前 SQLite-first / 单实例目标带向重型 DB 方案
• 文档、测试、migration 与运行时行为保持了一致，没有明显脱节

代码变动审查

migration / state-store

• schema version helper 抽取、并发首写 IntegrityError 兜底、pending claim 绝对 expires_at、最小索引补齐，这几项组合起来是合理且稳健的。
• legacy updated_at 记录仍保留兼容读取与清理路径，这个取舍符合当前 issue 的平滑演进目标。
• 将 session / owner / pending-claim / interrupt-request 写入统一到共享 helper，也减少了之前分散的 read-before-write 竞争窗口。

task-store / runtime

• SQLite 父目录创建、WAL / busy_timeout / synchronous=NORMAL 与 atomic terminal guard 都贴合本仓库当前目标。
• 启动期持久化摘要日志是低侵入可观测性，没有扩张协议面，方向合理。

docs / tests

• 文档已补足统一轻量持久化后端的语义边界。
• 本次又进一步把表述收紧为 SQLite-first，没有再把 incidental 的其它 dialect 路径写成部署承诺，这一点是正确的。
• 回归测试覆盖了 migration、兼容读取、绝对过期时间、索引补齐、启动摘要等关键边界，完整度足够。

残余注意点

• legacy updated_at 行在被新写入覆盖前，仍会沿用运行时 TTL 做兼容推导；这是兼容旧数据所必需的折中，目前看属于可接受的非阻塞残余。
• 启动摘要日志会暴露脱敏后的 database URL；对当前运维侧可观测性目标是合理的，但仍应保持“不记录密码、不输出 token”的约束。

PR 标题与描述

已审查并更新为：

• 标题：chore: harden sqlite-first lightweight persistence
• 描述：已按 migration / state-store、task-store / runtime、docs / tests 分块说明，并补充相关 commits、验证结果与 issue 关联

issue 关联审查

当前关系判断是准确的：

• Closes #383：准确，本 PR 已覆盖该 issue 当前收敛范围
• Related #367：准确，适合作为相关背景 issue 保留 related，不建议改成 closes