收敛 SDK-owned task schema migration 与扩展边界到 upstream 最佳实践

[liujuanjuan1984]

背景

当前仓库为了兼容旧实例里的 tasks 表 schema，在运行时启动路径中对 SDK-owned task table 做了 in-place compatibility migration，然后再委托 a2a-sdk 的 DatabaseTaskStore.initialize() 完成稳态初始化。

这是一种可工作的应急兼容方案，但它把 SDK-owned schema 的版本升级责任放进了应用进程启动路径，长期看并不优雅，也不符合 upstream 已经提供 a2a-db migration CLI 的最佳实践方向。

与此同时，这个问题与 upstream 的扩展能力边界高度相关：

• a2a-sdk 当前支持 a2a-db 管理其自带 tasks / push_notification_configs schema。
• 当前也支持自定义表名（table_name）和 compatibility conversions。
• 但并未一等支持“下游在 SDK task 表上扩自定义列并由 SDK 共同管理”的 contract。
• 当前仓库若继续直接贴着 SDK-owned task table 做 runtime migration，会把 schema ownership、升级职责、扩展边界混在一起。

因此，这里需要把“SDK 表 migration 最佳实践”和“是否支持扩表/如何扩展版本升级 contract”合并审视。

现状

• 运行时兼容迁移位于 src/opencode_a2a/server/migrations.py 与 src/opencode_a2a/server/task_store.py。
• 当前分支已将 /v1/tasks 列表与 owner scope 收敛回 a2a-sdk 原生能力，但 task table compatibility migration 仍在本仓库启动路径中执行。
• 本仓库还有 adapter-owned state tables（session binding / pending claim / interrupt state），它们与 SDK-owned task tables 的 schema ownership 不同。

需要回答的问题

1. 对 SDK-owned tasks 表，当前 runtime auto-migrate 做法是否应废弃，改为显式依赖 a2a-db 或 fail-fast 版本检查？
2. 对本仓库自己的 adapter-owned state tables，是否继续由本仓库 migration runner 管理？
3. 是否应将 schema management 策略明确分层：SDK-owned tables 由 upstream migration tool 管理，adapter-owned tables 由本仓库管理？
4. upstream 当前是否支持扩表；如果不支持，我们长期是否应该避免在 SDK-owned task table 上加自定义扩展，转而使用独立 side tables？
5. 是否值得向 a2a-python upstream 提 issue / PR，推动公开的 migration hook、schema version check hook，或更明确的 custom task model / extension contract？

目标

• 给出本仓库针对 SDK-owned schema 与 adapter-owned schema 的明确 ownership 边界。
• 提出替换当前 runtime auto-migrate 的最佳实践方案。
• 评估并整理 upstream 可贡献的最小改进方向。

[liujuanjuan1984]

开始收敛当前分支里 SDK-owned task table 的 runtime auto-migrate 临时方案。目标是改为更接近 upstream 最佳实践的显式 schema 校验/失败提示，并梳理 SDK-owned 与 adapter-owned schema 边界。

[liujuanjuan1984]

当前分支已去掉 SDK-owned tasks 表的 runtime auto-migrate 临时方案，改为启动期显式 schema 兼容性校验：若检测到 legacy SDK task schema，则 fail-fast 并提示先执行 upstream a2a-db。adapter-owned state tables 仍继续由本仓库 migration runner 管理。相关实现、文档与回归测试已提交到 fix/442-align-db-usage-with-sdk。

[liujuanjuan1984]

审查结论：该 issue 的核心问题已在当前主干上得到明确落地。当前 不再对 SDK-owned 表执行 runtime auto-migrate，而是在发现 legacy schema 时 fail-fast，并明确要求在启动前运行 ；对应边界也已写入 。剩余仍需继续跟踪的内容，主要是如何隔离对 私有/半私有形状的依赖，这一点由 #446 更准确覆盖。为避免与现状重复，关闭本 issue。

[liujuanjuan1984]

补充更正：上一条关闭说明中的代码引用缺失，完整结论如下。

当前 src/opencode_a2a/server/task_store.py 已不再对 SDK-owned tasks 表执行 runtime auto-migrate，而是在发现 legacy schema 时 fail-fast，并明确要求在启动前运行 a2a-db；对应边界也已写入 docs/guide.md。剩余仍需继续跟踪的内容，主要是如何隔离对 DatabaseTaskStore 私有/半私有形状的依赖，这一点由 #446 更准确覆盖。