fix(approvals): the ADR-0044 revise window is a service-owned node type (#3823) - #5560
Merged
Conversation
…pe (#3823) Send-back parked the run on an ordinary `wait` node the flow author placed. `wait` is `resumeAuthority: 'any'` — correctly, for a signal wait — so the #3801 type-keyed resume gate could not see that the pause was service-owned: a raw `POST /automation/:name/runs/:runId/resume` with an empty body walked the resubmit back-edge into the approval node with no submitter check and no `resubmit` audit row, and when a request was already pending on the record it consumed the suspension before the re-entry failed — destroying the run. The revise pause becomes its own node type instead: - `APPROVAL_REVISE_NODE_TYPE` (`approval_revise`), registered by plugin-approvals alongside the `approval` node, declaring `resumeAuthority: 'service'`. No engine change: the existing gate covers any node type that declares service ownership. No config — the window ends on the submitter's resubmit, never on a signal or timer. - `ApprovalService.sendBack` refuses a `revise` edge whose target is not that node type, before any mutation. - `flow-approval-revise-target-not-service-owned` (severity `error`, via the already-wired `lintFlowPatterns` entry) rejects the old shape at authoring time — CLI commands and the runtime metadata publish gate. ADR-0044's amendment gains an implementation section: what shipped, why the approval node does not re-suspend itself, why no ADR-0087 conversion was added for the legacy shape, and what upgrading a legacy flow costs (one token). Showcase, skill guidance, skill eval and docs migrated with it. Fixes #3823 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BWS4heBoAitLmzCLhcYdbK
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
github-actions
Bot
added
size/l
documentation
Contributor
📓 Docs Drift CheckThis PR changes 3 package(s): 109 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:
|
This was referenced Aug 5, 2026
Closed
os-zhuang
marked this pull request as ready for review
August 5, 2026 18:54
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #3823
维护者已批准方案 A(2026-08-05 裁决评论):把 revise 暂停改为 typed / service-owned,使 #3822 既有的
resumeAuthority类型门直接覆盖它,零新机制。本 PR 按「专用节点类型」落地。前提复核(先于实现)
在当前
origin/main(229d29e)上按 2026-07-28 实证评论重写了 repro(真引擎 + 真ApprovalService),三段实录完全复现,前提成立:repro 是临时文件,已删除;它的两个断言以正式用例的形式留在
approval-revise.test.ts。形状与理由
APPROVAL_REVISE_NODE_TYPE(approval_revise),在spec/automation/approval.zod.ts声明,由 plugin-approvals 与approval节点同一处注册(registerApprovalNode内调用),descriptor 声明resumeAuthority: 'service'/supportsPause/isAsync/category: 'human'。引擎一行未改 —— 门本来就按「暂停节点的注册类型」判定,这正是裁决的验收标准。wait/subflow/decision同为 schemaless),不凭空造一个没有读者的可编写面。executor 入场不武装任何东西,因此故意没有配onSuspensionReleased(与 wait 的 timer 一次性钩子相反,wait 定时唤醒 job 在 resume 没能消费掉暂停时也会自我取消 —— store 短暂不可达即丢掉这一次唤醒,run 挂到下次重启才被捞回 #5529 的先例在此不适用),代码里写明了这一点。revise边 —— 该分支上的节点(notify、状态更新)不再执行,窗口也从画布与 run log 上消失,而这正是 ADR-0044 当初选择通用wait要的性质。错的只是复用。ApprovalService.sendBack在任何写入之前拒绝 revise 边指向非approval_revise的图(与既有「无 revise 边」检查同一处);flow-approval-revise-target-not-service-owned(@objectstack/lint,severityerror)在编写期拒绝 —— 走的是lintFlowPatterns这条已经接好的注册项(gating、三个 CLI 命令 + runtime publish gate),所以连 lint 的接线都没有新增。该 rule 升到error符合该模块自陈的门槛(「运行时会拒绝」),理由写在 rule 旁。约束 1:approve →
screen的 UI 推进不受影响resumeAuthority只挂在 revise 窗口这一个类型上,screen/wait一律不动。新增用例 leaves an approve-branch screen resumable through the generic route 用真 screen executor 钉住:approval → approve → screen,decide 后 run 停在collect,随后automation.resume(runId, { variables: … })(无 service marker)成功推进到终点。同一用例里也断言wait的 descriptor 仍不是'service'。约束 2:向后兼容(明确写出)
按现行 D3 写好的存量 flow(
revise边 → 作者放置的普通wait):type: 'wait'→type: 'approval_revise',并删掉waitEventConfig);重新发布该 flow 会报 lint error。用例 refuses send-back into a bare wait node before anything mutates 钉住「拒绝发生在任何写入之前」:请求仍是pending,只有submit一行审计,run 仍停在 approval 节点。SuspendedRun.nodeType是暂停时刻记录、读取时 recorded-first(fix(automation,approvals): gate the generic run-resume route on the suspended node (#3801) #3822 有意如此,避免 republish 把活 run 的节点改型),所以这些 run 保持原样,由resubmit或recall正常排空 —— 不做追溯改型。为什么不加 ADR-0087 D2 conversion(考虑过并否决,ADR 里记了):它不会是无损改名,而是依赖拓扑的语义重写 —— timer 风味的 wait 会静默丢掉 timer,被另一条入边共用的 wait 会连那条路径一起变成 service-only,这两种破坏 conversion 看不见。可测量的存量也指向同一结论:Studio designer 还不能画 revise 边(ADR-0044 自己的 follow-up),
cloud仓库没有任何 revise flow,本仓库唯一一个是 showcase(本 PR 一并迁移)。一处响亮的拒绝 + 一个 token 的修复,胜过日后还要退休的容忍层 —— 对读诊断信息的 AI 作者尤其如此。一处有意的收窄:
revise边的直接目标必须是窗口。想写revise → notify → 窗口的图会被拒绝,而不是去做「该分支上所有可达暂停都是 service-owned」的不定边界分析;send-back 本身已经通知提交人,这个写法背后没有丢失的能力。测试
反向验证(方向先定后跑):把 descriptor 的
resumeAuthority从'service'改回'any'(只改这一处,保持 flow 仍用新类型,以隔离「类型门」这一条论断),预期新增的门用例转红 —— 结果如预期:第一条是 descriptor 断言(与 flow 无关),另两条正是实证评论里的行为回归 —— raw resume 重新成功。其余用例(legacy-wait 拒绝、screen 推进)自带各自的 flow,不受该反转影响,保持绿色,这点如实记录而非硬凑成「全红」。
另外把迁移后的 showcase flow 直接喂给 lint 验证:
lintFlowPatterns零 finding(另有两条既有的approval-approvers-may-resolve-emptyinfo,与本改动无关)。面
packages/spec/src/automation/approval.zod.ts(常量 +APPROVAL_BRANCH_LABELS.revise文档)、packages/plugins/plugin-approvals/(新approval-revise-node.ts、approval-node.ts注册、approval-service.ts的assertReviseEdge、index 导出)、packages/lint/(rule + 导出 + 测试)、examples/app-showcase(迁移)、skills/objectstack-automation/(SKILL.md 与 revise-loop eval)、content/docs/automation/approvals.mdx、docs/adr/0044-*.md(amendment 增补 Implementation 段:落地形状、否决 conversion 的理由、向后兼容),changeset 覆盖 spec / plugin-approvals / lint(均 minor)。同包排队中的 #5048 / #4792 的面未触碰;
service-automation一个字节未改(引擎侧零改动本身就是裁决的验收标准)。packages/spec/authorable-surface.base.json在本地gen:schema运行时会把 baseRev 前推并补 3 个与本单无关的EmailServiceConfigkey —— 已还原,不夹带进本 PR(其 gate 通过,只提示 "trails the merge base by 3 key(s)")。🤖 Generated with Claude Code
https://claude.ai/code/session_01BWS4heBoAitLmzCLhcYdbK
Generated by Claude Code