# 33-needs-gate-role-filter-bug. `requiredInputsMissing` 未按 role 过滤 —— produces 声明被误判成 needs > **日期**: 2026-08-21 > **状态**: 🔴 **待修**(发现于 31 号文档修复的真实 E2E 回归验证过程中,是一个独立的新 bug, > 与 31 号文档的兜底边问题无关) > **触发**: `e2e-demo` 公司真实回归任务 `T-mt2r6fz0-125b`(goal `G-mt2r62ia-73af`, > root run `run_0e9074815130`)——为验证 [31 号文档](./31-work-graph-fail-fallback-coverage.md) > 的兜底边修复而起的新任务,链路走到 `org-coder-validator` 时意外反复 blocked --- ## 一、先说 31 号文档的验证结果:修复生效,有真实证据 这条任务本身是为了拿到 31 号文档 §六「尚未做」的那一步真实验收证据(当时因为原任务 `T-mt1qx0c4-95bf` 状态不干净,改用确定性回归测试代替,见 31 号文档 §7.3)。这次补上了: - 新起的 `org-planner` 子图(`run_38b3df8fd228`)里,`org-planner-sdd` 真实自判失败 (下游信息不足),沿新补的兜底边(`org-planner-sdd --fail--> org-planner-prd`, edge `wge_ce0f7f05f6dc`)**自动回退了 3 次**(`graph_run_loop_records`: `verdict=registered`,`loop_count` 1→2→3),全程**零次 `retryNode` 调用**,最终 brd→prd→sdd→benchmark→validator 整条链路收敛到 `run_status=completed`。 - 31 号文档的决策 A(除入口节点外强制兜底边)在真实 LLM 驱动下按设计工作,**结论确认**。 --- ## 二、新发现:`org-coder-validator` 被 `missing_required_input` 反复误判 ### 2.1 现象 同一条任务往下走到 `org-coder`(`run_21fd814c2f56`,用的是 `executor.json` 骨架)时, `org-coder-validator` 连续两轮都以 `fail_reason=missing_required_input` 收场: - 第一轮(attempt 1,10:01-10:11):沿兜底边 `validator --fail--> impl` 回退两次 (`wge_1bdb181b14ef` 一次、`wge_aa5bad61fe9a` 一次),第三次撞上 run 树级回退硬顶 (`backward_count` 全树累计 >5,`LOOP_HARD_CAP_RUN=5`),`force_terminated`, 节点 `blocked`。**这一段是硬顶熔断本身在正常工作**,不是这次要报的 bug。 - 人工 `POST /nodes/:id/retry` 把 `org-coder-validator` 打回 `ready` 后, **第二轮**(attempt 2,10:42:48-10:44:01)**又**判了一次 `missing_required_input`, 这次连新的 `loop_record` 都没写(回退硬顶已越顶,直接静默 blocked)。 - 节点自己的 `remediationNote` 写的是「无需整改。……本轮重新独立跑了一遍测试脚本与 goal-contract,结果与 attempt-1 完全一致,判定 attempt-1 的 passed 结论有效」—— **agent 自己认为通过了**,是引擎的产出/输入契约闸门(T-mt25ecbd 那次加的机制, commit `aecf5c9`)把 success 强行改判成 fail。 ### 2.2 复现证据:`graph_files` 里明明有 `artifact` 却仍报缺 查 `T-mt2r6fz0-125b` 的产物索引(`data/graph.sqlite` 的 `graph_files` 表), `org-coder-impl`(`rn_e71be3641174`,10:06:51 完成)与 `org-coder-test` (`rn_cd3e3a1c51e2`,10:08:52 完成)都成功登记了当前(`superseded_by IS NULL`) `kind='artifact'` 的产物行(`_plan.md` / `_research.md` / `coder.log`)。 `org-coder-validator` 的 attempt 2 在 10:42:48 才跑,**比这些产物晚了半小时以上**, 不是时序竞争,是稳定复现。 ### 2.3 根因:`inboundContracts` 不按 `role` 过滤,把 `produces` 声明也当成 `needs` `executor.json` 里 `test → validator` 这条边同时声明了两条契约(`work-graph-db.js` `declareEdgeContract`): ```json { "from": "{{orgNode}}-test", "to": "{{orgNode}}-validator", "condition": "success", "produces": ["log"], "needs": ["artifact"] } ``` 即:`kind=log, role=produces`(test 自己产出的是 log)+ `kind=artifact, role=needs` (validator 要吃的是 artifact)。这两条都落进同一张 `graph_edge_contracts` 表, `required=1`。 问题出在 `work-graph-db.js:2542` 的 `inboundContracts()`: ```js function inboundContracts(edgeLayer, edges, defNodeId) { const inbound = (edges || []).filter( (e) => String(e.to) === String(defNodeId) && (e.edgeKind || 'forward') !== 'backward' ); const out = []; for (const e of inbound) { for (const c of edgeContracts(edgeLayer, e.id)) out.push({ ...c, fromNodeId: e.from }); } return out; } ``` 它把入边上**所有**契约行原样吐出来,不管 `role` 是 `produces` 还是 `needs`。 下游 `graph-engine.js:3945` 的 `requiredInputsMissing()` 接着只按 `required` 过滤: ```js const requiredKinds = [...new Set(contracts.filter((c) => c.required).map((c) => c.kind))]; ``` 于是 `validator` 的「必须在索引里找到实例」的 kind 集合变成了 `{log, artifact}`, 而不是本该只有的 `{artifact}`——`log` 是 test 声明**自己产出**的 kind(描述 test 的 输出形态),不是 validator 要读的输入。这个 task 的 `graph_files` 里从来没有任何 `kind='log'` 的行(`org-coder-test` 实际写的是 `coder.log` 但被索引成 `kind='artifact'`,不是 `kind='log'`),于是 `requiredKinds - haveKinds = ['log']`, `missing.length > 0`,success 被强改成 fail。 **对照**:同一份代码里至少三处其他函数在读同一张 `graph_edge_contracts` 表时都记得 按 `role` 过滤(`(c.role || 'produces') !== 'needs'` 或 `=== 'produces'`, 见 `graph-engine.js:968` / `:3811` / `:3866`),唯独 `inboundContracts` / `requiredInputsMissing` 这一条链路漏了。判据不一致,不是设计如此。 ### 2.4 影响面推测(未逐一核实,留给修的时候一并查) - 任何在同一条边上**同时声明了 `produces` 和 `needs`** 的节点,只要 `produces` 的那个 kind 从未被单独索引过(大多数「描述性」kind,比如这里的 `log`,本来就不 一定会被单独记录成同名 kind 的产物行),下游节点的 success 就会被这条误判的 `missing_required_input` 拦下来,且**每次重试都会复现**(不是一次性的)。 - `executor.json` / `executor-fanout.json` / `validator.json` 里凡是 `test→validator` 这种「同边混写 produces+needs」的写法都要复查一遍(§一 T3/T4 审计脚本可以扩展 一个「edge 同时有 produces 与 needs 时,produces 的 kind 是否真的会被索引」的检查项)。 ### 2.5 建议修法(留给实施时定案,这里只记方向) `inboundContracts()` 应该只返回 `role='needs'`(含历史 NULL 按 `produces` 处理的 存量行需要保留原有兼容语义,但 NULL 不该被当成 `needs`)的契约行,或者 `requiredInputsMissing()` 在 `contracts.filter(...)` 那一步同时按 `(c.role || 'produces') === 'needs'` 过滤——两者选一,不建议两处都改(避免出现 「谁的语义才是权威」的第二份判据)。改完要跑一遍 §一 提到的真实回归任务,确认 `org-coder-validator` 不再假阳性 blocked。 --- ## 三、下一步 - [ ] 定案 §2.5 的修法,改 `inboundContracts` 或 `requiredInputsMissing` 之一 - [ ] 新增单测:`test→validator` 同边声明 `produces:log` + `needs:artifact`, 只有 `artifact` 有索引实例、`log` 没有,validator 的 success 判定不应被拦 - [ ] 跑一遍 `graph-real-chain-smoke.test.js` 同款「真实引擎代码 + 真实 DB + 换掉最外层 CLI 子进程」的确定性回归,复现本次撞见的具体场景 - [ ] 复查 `system/work-graph-templates/*.json` 里其他「同边混写 produces+needs」的边