# Pipeline OA Event Flow

Pipeline 的最终控制模型必须是 100% OA 事件流驱动。开发过程可以分阶段迁移，但交付态不能保留中间态、双写语义、点对点控制通道或依赖旧事件的永久兜底；任何阶段性兼容只能作为局部迁移手段，必须在同一重构闭环内被删除并由 E2E 证明已退出。

## Core Principles

- OA backend 是 Pipeline runtime 的唯一控制总线；node、monitor、runner、UniDesk frontend 和 CLI 都只能通过 OA 事件表达事实、订阅事实或发出控制意图。
- Node 之间不得直接启动、暂停、重试或通知彼此；monitor 不得绕过 OA 直接控制 runner；frontend 不得直接写 Pipeline `.state`、prompt 文件、命令队列或 worker 状态文件。
- 事实事件只描述已经发生的事实，策略判断由 OA 加载 Pipeline config/topology 后完成；`node-finished` 不得携带 `legacy audit policy flag`、`nextNodeIds`、`shouldStartDownstream` 这类控制决策字段。
- 控制行为必须由 OA 控制/管理事件表达，例如 start downstream、pause、resume、single-step、append prompt、guide、modify、approve、redo/restart、skip、cancel 和 retry。
- UI、CLI、E2E 和调试工具都应消费 OA 归一化读接口或通过 OA 控制 API 写入事件，不得解析 monitor 文本、worker log、runner 私有文件或旧 JSONL 文件来反推控制语义。
- 旧的本地文件传输通道必须完全退出控制路径：不得创建、轮询或依赖 `control-prompts.jsonl`、`monitor-prompts.jsonl`、`monitor-control`、`control-events.jsonl`、monitor stop 文件、`.state/pipeline-runs/{runId}/control/commands/` 或给 monitor 容器挂载可读 `/pipeline-state` 来完成 prompt、stop、guide、approve、redo/restart、append 或 UI/Gantt 事件取证。

## Event Identity And Tags

- 每条事件必须有稳定 `eventId`、`type`、`createdAt`、`sourceKind`、`sourceId`、`correlationId` 和可选 `causationId`，用于排序、幂等、回放和追踪控制来源。
- Pipeline 后端必须自动附加 scope tag：`pipeline:{pipelineId}`、`epoch:{runId}`，node 相关事件还必须带 `node:{nodeId}`；attempt/procedure 相关事件应带 `attempt:{attemptId}` 或 `procedure:{procedureRunId}`。
- Monitor 在 config 中只声明要订阅的业务 tag 或事件类型，OA backend 在订阅时自动追加当前 `pipeline:{pipelineId}` 与 `epoch:{runId}` 限制，避免不同 pipeline 或 epoch 串流。
- 一次 epoch 应绑定 config snapshot 或 config version；OA 的审核、拓扑推进、并发和单步策略都以该快照为准，避免运行中配置漂移导致控制解释不一致。
- 控制事件必须有幂等键，重复投递同一个 start、approve、redo/restart 或 append prompt 时，OA 应识别为同一意图而不是重复启动或重复写入。

## Fact Events

- `node-started`、`node-finished`、`node-failed`、`node-cancelled`、`node-long-running-observation` 等事实事件用于记录运行状态，不承担流程推进决策。
- `node-finished` 是中性完成事实，包含 node id、procedure run id、status、timestamps、outputs summary 和诊断摘要；它不描述是否需要审核，也不直接声明下游节点。
- 长任务观察事件只在 node 未进入终态时触发，默认节奏为 2、5、10、20 分钟，之后每 20 分钟循环；固定 30 秒 monitor 周期不得作为正式机制保留。
- `legacy batch completion gate` 只能作为派生统计或兼容只读事件，不能作为流程推进门禁；下游推进由每个 `node-finished` 加 OA config/topology 判断完成。
- 如果 node 完成后需要 monitor 审核，UI 中仍只应保留这一条 `node-finished` 作为完成/等待审核的事实点，不再创建独立的 `legacy node audit request event` 或 `legacy monitor audit request event` 事实点。

## No-Audit Flow

1. Runner 观察到 node 进入终态，并把中性 `node-finished` 事实推入 OA backend。
2. OA backend 记录事件，加载该 epoch 的 config snapshot 和 topology。
3. OA 判定该 node 不需要 monitor 审核，且下游依赖已满足。
4. OA 产生下游 `start-node` 控制事件。
5. Runner 只消费 OA 控制事件来启动下游 node，并把启动结果再写回 OA 事件流。

## Audit Flow

1. Runner 把中性 `node-finished` 事实推入 OA backend。
2. OA backend 记录事件，并按 config snapshot 判定该 node completion 需要 monitor 审核。
3. Monitor 通过 OA 订阅收到同一 scope 下的 `node-finished` 事实和 prompt；是否需要审核来自 OA policy，不来自 `node-finished.detail`。
4. Monitor 通过 OA skill 或等价 OA 控制 API 发出 `approve`、`modify`、`redo/restart`、`reject` 等管理事件。
5. OA backend 记录 monitor 决策，按 config/topology 产生 start downstream、reset downstream、restart target 或 stop/pause 等后续控制事件。
6. Runner 只消费 OA 控制事件执行后续动作，执行结果继续回写 OA 事件流。

## Single-Step And Debug Flow

- 单步运行、人工放行、暂停、恢复、重试、跳过和取消都必须建模为 OA 控制事件；不得通过调试 HTTP 端点直接修改 runner 内存状态。
- CLI 和 UniDesk frontend 的 node 精细控制面板只能调用 Pipeline 后端的 OA 控制 API；后端可保留 `node-control` 路由名，但路由内部必须写入 OA 事件并由 OA dispatcher 执行。
- Debug 工具可以读取事件流、config snapshot 和归一化状态机结果，但不得维护另一套流程推进逻辑。

## Rendering Contract

- UniDesk Pipeline UI 只消费 Pipeline 后端根据 OA 事件流生成的 snapshot、Gantt DTO、node detail 和 control history，不直接消费旧 monitor append 文件语义。
- 甘特图中的执行条、prompt 点、monitor 决策点、长任务观察箭头和人工控制箭头都必须来自 OA 事件或 OA 派生 DTO。
- 有 monitor 的 pipeline 中，monitor node 固定在甘特图第 1 列，其余 node 再按拓扑上游到下游向右排列。
- `node-long-running-observation` 必须画从被观察 node 到 monitor node 的观察连线；被观察 node 上不得额外绘制“观察来源”点，因为点只代表真实行为。
- Running node 必须显示从实际开始时间延伸到当前时间的实时闪动执行条；相邻 OpenCode step 之间的真实空闲区间必须留白，不能被连续装饰线误渲染为执行。
- 审核开启时不得同时渲染 `node-finished` 和独立 audit-request 点；node completion 是唯一完成/等待审核点，monitor 的 approve/modify/redo/restart 是后续独立控制点。

## Migration And Completion Gates

- 分阶段重构只允许按“schema 文档与测试门禁 -> OA 事件写入 -> OA dispatcher 接管控制 -> UI/CLI 改为 OA 读写 -> 删除旧事件和旧控制路径”的方向前进，不得把双写/双读作为最终设计。
- 完成态必须删除或禁用以下残留：`legacy detail audit policy flag` 作为权威策略字段、`legacy node audit request event` / `legacy monitor audit request event` 独立审核请求事件、`legacy batch completion gate` 控制推进、monitor 直接调用 runner、node 直接启动下游、frontend/CLI 直接写 `.state` 文件。
- 完成态还必须删除文件传输残留：`PIPELINE_MONITOR_APPEND_FILE`、`PIPELINE_MONITOR_STOP_FILE`、`PIPELINE_MONITOR_CONTROL_DIR`、`PIPELINE_NODE_PROMPT_APPEND_FILE`、`control-events.jsonl`、`runControlEventFile`、`appendJsonLine`、`readJsonLineRecords`、`readPromptAppendFile`、`parseCommandFile`、`parseMonitorCommandFile`、`readMonitorCommands`、`fallbackMonitorInterventions`、`syntheticMonitorStopPrompt` 以及 monitor 的 `/pipeline-state` 挂载都不得出现在运行代码中。
- E2E 必须覆盖有审核与无审核两条链路：无审核时由 OA 从 `node-finished` 推进下游；有审核时由 monitor 经 OA 控制事件推进下游；事件都必须带 `pipeline:{pipelineId}` 与 `epoch:{runId}` tag。
- Pipeline 甘特图 E2E 必须证明没有重复审核点、长任务观察有连线且无来源伪点、running node 有实时条、OpenCode step 空闲区间留白、控制箭头来自 OA 控制事件。
- 代码检查应加入防回归搜索或等价单元测试，防止重新引入 `legacy audit policy flag` 权威字段、旧 audit-request 事件、`legacy batch completion gate` 推进逻辑或非 OA 控制写路径。