Author orch Markdown test plan

2026-03-19 16:27:28 +08:00
parent b448d98e71
commit a20bec1cac
68 changed files with 2225 additions and 160 deletions
@@ -1,7 +1,8 @@
 # Orch `wait` Test Plan Index

-## Status
+## Case Files

-No command case files are authored yet.
-
-Use [../ROADMAP.md](../ROADMAP.md) for planned case slugs and document progress.
+| Case Slug | File | Coverage Note |
+| --- | --- | --- |
+| `wait-wakes-on-matching-run-event` | [wait-wakes-on-matching-run-event.md](./wait-wakes-on-matching-run-event.md) | wakes on a later matching task event and returns that event payload |
+| `wait-times-out-without-matching-event` | [wait-times-out-without-matching-event.md](./wait-times-out-without-matching-event.md) | returns a stable timeout payload when no later matching event appears |
@@ -0,0 +1,33 @@
+# Case: `wait-times-out-without-matching-event`
+
+## 用例意义
+
+验证 `wait` 在没有后续匹配事件时返回稳定的超时结果，而不是把超时视为命令失败。
+
+## 前置条件
+
+- 空数据库已初始化
+- 已创建运行 `run_blog_wait_002`
+- 当前没有会产生 `task_done` 的后续事件
+
+## 输入
+
+```bash
+orch --db TMPDIR/coord.db --json wait --run run_blog_wait_002 --for task_done --after-event 0 --timeout-seconds 1
+```
+
+## 预期输出
+
+- 退出码为 `0`
+- `wait.data.woke == false`
+- `wait.data.next_event_id == 0`
+- `wait.data.events` 为空或缺省
+
+## 断言结论
+
+- `wait` 的超时是可消费的正常结果，不是错误态
+- leader 可以基于 `woke=false` 决定继续轮询、切换过滤条件，或退出当前控制循环
+
+## 补充约束
+
+- 该用例强调超时契约，不要求系统中存在任何任务
@@ -0,0 +1,40 @@
+# Case: `wait-wakes-on-matching-run-event`
+
+## 用例意义
+
+验证 `wait` 能在后续匹配事件出现时被唤醒，并返回稳定的事件载荷。
+
+## 前置条件
+
+- 空数据库已初始化
+- 已创建运行 `run_blog_wait_001`
+- 已添加任务 `T1` 并完成一次 `dispatch`
+- 已知当前尝试线程为 `THREAD_ID`
+- `wait` 在工作线程写入阻塞状态前启动
+
+## 输入
+
+```bash
+orch --db TMPDIR/coord.db --json wait --run run_blog_wait_001 --for task_blocked --after-event 0 --timeout-seconds 2
+inbox --db TMPDIR/coord.db --json claim --agent worker-a --thread THREAD_ID
+inbox --db TMPDIR/coord.db --json update --agent worker-a --thread THREAD_ID --status blocked --summary "Need logging decision" --payload-json '{"question":"stdout or stderr?"}'
+```
+
+## 预期输出
+
+- `wait` 退出码为 `0`
+- `wait.data.woke == true`
+- `wait.data.events` 长度为 `1`
+- 唯一事件的 `type == "task_blocked"`
+- 事件 `summary == "Need logging decision"`
+- 事件 `payload.question == "stdout or stderr?"`
+
+## 断言结论
+
+- `wait` 不是简单睡眠，而是面向 run 事件流的阻塞读取接口
+- `task_blocked` 事件会把 worker 提问摘要和结构化 payload 暴露给 leader
+
+## 补充约束
+
+- `--for` 支持逗号分隔的事件类型列表；该用例验证的是单事件过滤
+- `wait` 返回成功时也会给出 `next_event_id`，便于后续增量等待