test: add mysql outage recovery rehearsal

docs/api/README.md

@@ -24,6 +24,7 @@
 | `orbit-admin retention inventory` 保留清单 | 已实现带 UTC 截止时间的只读盘点；不执行归档、删除或权限变更 | [保留清单](retention.md) |
 | `sdk/go/cmd/orbit-load` 有界受理负载工具 | 已实现固定并发、无自动重试、延迟百分位和错误分类；只用于隔离环境 | [负载工具](load.md) |
 | `scripts/test-backup-restore.sh` 隔离备份恢复演练 | 已实现一次性 MySQL 逻辑备份、独立恢复、核心计数及零外键核验 | [备份恢复演练](backup-restore.md) |
+| `scripts/test-db-recovery.sh` MySQL 短暂不可用恢复演练 | 已实现 readiness 503、同卷恢复 200 及恢复后任务受理核验 | [数据库恢复演练](db-recovery.md) |
 | `/v1/worker/connect` | P2 已实现并通过阶段验收 | [Worker 契约](worker.md)、[Schema](worker-schema.md) |
 | 任务相对延迟 `delay_ms` | 已实现数据库计时、原键恢复与实际执行例子 | [任务接口](tasks.md)、[延迟示例](../examples/delayed-task.md) |
 | 任务冻结策略与 Worker `retryable` | P3 安全重试已实现 | [安全重试](retries.md) |

docs/api/db-recovery.md

@@ -0,0 +1,26 @@
+# MySQL 短暂不可用恢复演练
+
+Orbit 不在运行时自动执行迁移，也不把数据库错误伪装成业务成功。`GET /health/ready` 每次都在有限上下文内执行数据库 Ping、迁移账本和零外键检查；数据库不可用时返回 `503`，恢复后由 `database/sql` 连接池重新建立连接。
+
+## 可复现命令
+
+``@@BT@sh
+DOCKER=/usr/local/bin/docker \
+ORBIT_TEST_MYSQL_IMAGE=mysql:8.4 \
+sh scripts/test-db-recovery.sh
+``@@BT@
+
+脚本会创建一次性 MySQL 容器和本地卷，迁移当前结构，初始化通用应用/命名空间/队列，启动 Orbit；然后停止并移除数据库容器，在相同主机端口和卷上创建恢复容器。恢复后会再次请求 readiness，并提交一条原权限范围内的任务。临时凭据、容器和卷均由脚本清理。
+
+成功输出：
+
+``@@BT@json
+{"initial_readiness":200,"during_database_outage":503,"after_database_recovery":200,"task_accepted_after_recovery":true}
+``@@BT@
+
+## 运行边界
+
+- 503 只表示当前节点不能确认数据库和结构，不代表任务已回滚或外部效果已撤销；写请求超时仍必须保留原幂等键核对。
+- 数据库恢复后只证明新连接可以读取迁移账本并继续受理，不证明正在执行的任务、租约、复制确认或外部副作用已经自动完成。
+- 该演练使用本地 MySQL 卷模拟单节点短暂中断，不等同于主从切换、复制延迟、跨故障域、磁盘故障、RPO/RTO 或生产容量验收。
+- 数据库保持无外键；`orbit-admin verify` 和 readiness 都会拒绝实际外键漂移。