feat(spec,plugin-approvals,app-shell): the approvals get serves a request's own route, and both approval step lines draw it - #26976

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/plugin-approvals, @objectstack/spec, touching 19 documentable anchor(s).

5 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/automation/approvals.mdx (via flow_route (symbol, a field of interface ApprovalRequestRow), flow_route (literal, a string literal in FlowRoute), sys_approval_request (literal, a string literal in attachFlowRoute))
• content/docs/automation/flows.mdx (via ApprovalService (symbol, a top-level class), sys_approval_request (literal, a string literal in attachFlowRoute))
• content/docs/automation/workflows.mdx (via sys_approval_request (literal, a string literal in attachFlowRoute))
• content/docs/plugins/packages.mdx (via sys_approval_request (literal, a string literal in attachFlowRoute))
• content/docs/ui/translations.mdx (via sys_approval_request (literal, a string literal in attachFlowRoute))

⛔ 3 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v16.mdx (via sys_approval_request (literal, a string literal in attachFlowRoute))
• content/docs/releases/v17/17-6.mdx (via ApprovalService (symbol, a top-level class), sys_approval_request (literal, a string literal in attachFlowRoute))
• content/docs/releases/v18/18-1.mdx (via ApprovalService (symbol, a top-level class))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin c5a88d1e4d0ed32fb211671f1fbbd3b3199c7e38 && git checkout c5a88d1e4d0ed32fb211671f1fbbd3b3199c7e38
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 49b505915a37270ddf12d0ed4a6fd67f9907fb74 b97005bf14417759f5fdf57e4cb90c41622774bd && git checkout -B drift-repro 49b505915a37270ddf12d0ed4a6fd67f9907fb74 && git merge --no-ff b97005bf14417759f5fdf57e4cb90c41622774bd

node scripts/docs-audit/affected-docs.mjs --json 49b505915a37270ddf12d0ed4a6fd67f9907fb74

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 49b505915a37270ddf12d0ed4a6fd67f9907fb74 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 4efa377e203fb1b515195033c56e57c104b90739
Local-runs: none
Scope: packages/spec/src/contracts/approval-service.ts + packages/plugins/plugin-approvals/src/approval-route.ts, packages/plugins/plugin-approvals/src/approval-route.test.ts, packages/plugins/plugin-approvals/src/approval-service.ts, packages/plugins/plugin-approvals/src/flow-route.integration.test.ts, ui/apps/console/src/services/approvalsApi.ts, ui/apps/console/src/services/approvalRequestsDataSource.servedPageStepLine-12491.test.tsx, ui/packages/app-shell/README.md, ui/packages/app-shell/src/hooks/useRecordApprovals.ts, ui/packages/app-shell/src/views/RecordApprovalsPanel.tsx, ui/packages/app-shell/src/views/RecordApprovalsPanel.servedRoute-26668.test.tsx, ui/packages/app-shell/src/views/RecordApprovalsPanel.stepProgressVertical.test.tsx, ui/packages/app-shell/src/views/RecordApprovalsPanel.visitedRoute-26563.test.tsx (deleted), ui/packages/app-shell/src/views/approval-decision/ApprovalDecisionPanel.tsx, ui/packages/app-shell/src/views/approval-decision/ApprovalDecisionPanel.stepLine-12491.test.tsx, ui/packages/app-shell/src/views/approval-progress/ApprovalStepLine.tsx; cited code read on origin/main 7bb80845: packages/services/service-automation/src/dag-traversal.ts (traverseNext), packages/spec/src/automation/flow.zod.ts (FlowNodeAction, the edge schema), packages/plugins/plugin-approvals/src/approval-node.ts (resume labels, auto-approve), packages/plugins/plugin-approvals/src/sys-approval-request.object.ts, packages/drivers/driver-sql/src/sql-driver.ts (formatOutput datetime canon), the pre-change attachFlowSteps. Prose faces (.changeset/26668-approval-served-route.md, content/docs/automation/approvals.mdx) are the dispatching seat's ACCEPT, not this record.

Inputs: card #26668 (body; comments 6442524346, 6445757080, 6446765160, 6455118705, 6456589397), card #26563 and PR #26666 (body, files), PR #26976 (body, 18 files, the one comment 6456593091, the net diff against main at the head), the head's check-runs. Read-only throughout; no worktree, build, test or gate run.

① Derived judgments

1. Accept set / public face. ApprovalRequestRow (@objectstack/spec/contracts) gains one optional served member flow_route?: { steps, ahead: 'end' | 'undecided' | 'decided' }; flow_steps is byte-identical in shape and producer, its doc rewritten to say it is the trunk and that a step line draws flow_route, never it. Widening of a published read contract; nothing an author writes moves. Correct as declared.

2. ⛔ No guessed path — judged on the producer (approval-route.ts, attachFlowRoute).

   • Passed steps come ONLY from the run's own sys_approval_request rows: the service reads where: { flow_run_id: row.flow_run_id } as the system, and passedSteps keeps a row only if it is another node, approved, opened before the request (created_at compare) and, per node, its latest round. The current step is row.flow_node_id. The graph is never consulted for either. Correct.
   • Steps ahead (stepsAhead): from an approval node the approve-labelled out-edges, else every non-fault out-edge — exactly the engine's rule in traverseNext (claim by branchLabel, else every out-edge, fault excluded). It follows ONE edge with no condition and returns undecided at a decision node (even with one edge), a conditioned edge, more than one out-edge, a node already seen, a node not in the graph, or a subflow / map / loop / any node with regions. A single isDefault edge is followed, which is what the engine does when no conditional sibling exists. The trunk is never substituted: nothing in the module reads the true edge or out[0]. Correct.
   • Shapes probed, with what ahead says: a re-entered step (loop back) stops at the seen node, undecided, after listing the steps up to it; a rejected-then-resubmitted run (ADR-0044) lists no returned / rejected row, lists a re-approved node once at its latest round, and never walks the revise / reject edges because the node's approve edges exist; a parallel or fan-out (parallel_gateway, or any node with two unconditioned out-edges) stops undecided — two pending requests of one run each see the other's approved rows as done, which are facts of the run; a run with no history rows yields passed [] and the walk alone; a request with no flow_run_id or no flow_node_id gets no flow_route (documented); a flow edited after the request started is read at its current version — the request's own node missing from the graph gives { steps: [passed, own], ahead: 'undecided' }, a passed node missing is labelled from the stored current_step_label, a deleted flow gives no flow_route at all (no guess, a gap); a non-pending request (approved, rejected, returned, cancelled, recalled) is passed + own (done once approved, else current) with ahead: 'decided' and no walk.
   • decided is served only when row.status !== 'pending', and then never with a walked tail. Never served without a decided path.
   • Not a guess but an omission, noted for the record: an auto-approved rung (审批流无法在「运行中」动态确定审批人——审批人在提交时即被 $trigger 快照锁定（动态路由 / 动态会签受阻） #3447, empty slate, no request row) is absent from the passed steps.

3. Two fields. Readers of the rail now read ONLY flow_route.steps: RecordApprovalsPanel (pendingRequest?.flow_route?.steps, the pending request being the one row the hook enriches by getRequest, so the single-read member reaches it), ApprovalDecisionPanel (request.flow_route?.steps, at any status), and ApprovalStepLine's step type is now flow_route's. The two type declarations (ApprovalRequestLite in app-shell, the console's approvalsApi.ts row) carry both members, each doc saying the line draws flow_route and nothing draws flow_steps; the app-shell README and the approvals guide say the same; the spec doc on flow_steps says it. git grep on origin/main finds no other reader: no packages/client type, no OpenAPI or content/docs/references output names flow_steps (the only other hit is a liveness-evidence string naming attachFlowSteps, whose producer is unchanged). Nowhere do the two fields disagree without the doc saying which the UI reads. The spec doc's stop list omits the two extra conservative stops the code has (missing node, regions); the guide's matches the spec. Not a disagreement.

4. Declarations. Clause-②: yes (widening) — right (one added optional member of a published contract). Metadata-protocol: none — right: the rule (AGENTS.md Post-Task Checklist step 3) grades the change to what a metadata author can write; flow_route is a served read member, no key, value or type an author writes moves. The claim's added was marked provisional and assumed an authorable key; the dev's re-judgment from the diff stands. Precedent feat(plugin-approvals,rest,client): a record-anchored approval lock read, { locked } for every caller who can read the record #26361 holds: it added the optional getRecordLock? member to IApprovalService in the same contract file under yes (widening) / none. Skills-docs: none — the third line is not owed at all (kind none, arm widening); git grep over skills/ for flow_steps, flow_route, the step line or progress strip: 0 hits, so the guide's new paragraph makes no skill text false. ADR-0087: no marker owed — no breaking changeset (no !, no (narrowing), patch everywhere), and the gate reads the breaking declaration alone. Changesets: one entry per touched published package (@objectstack/spec, @objectstack/plugin-approvals, @object-ui/app-shell, @object-ui/console), all patch, each body carrying both declaration lines.

5. Stopgap deletion (fix(app-shell): the approval step line draws the route the request's run took, not the flow graph's first branch #26666). visitedApprovalSteps and the request page's no-line rule are deleted; ApprovalStepLine's markup is untouched. Tests, one by one: RecordApprovalsPanel.visitedRoute-26563.test.tsx removed with its subject — its four panel pins are re-pinned in RecordApprovalsPanel.servedRoute-26668.test.tsx (the reported route with no trunk rung; a one-step route draws none; the viewer served only the pending row now sees the whole route, inverted on purpose because the route no longer comes from the list read; the rejoin-trunk case moved to the server where the rule now lives, integration case 3), its seven unit pins on the deleted function are re-pinned as passedSteps cases in approval-route.test.ts (order, outcomes that are not a pass, later rows, the current node's earlier rounds, round dedup, missing node or time); RecordApprovalsPanel.stepProgressVertical.test.tsx re-pinned to served-route fixtures, its connector-tint case now pinning both tints (green into done/current, bg-border into upcoming) where it pinned all-green under the no-ahead regime; ApprovalDecisionPanel.stepLine-12491.test.tsx re-pinned from "no line" to the drawn route, adding no-route-draws-nothing and line-above-tally-above-decisions, the old tally control kept inside the ordering case; the console servedPageStepLine-12491 (the real served page) re-pinned likewise, its queryByRole('list') null-check dropped because a list now legitimately exists. No retained assertion is weakened. A trunk request renders the same for every reader: integration case 5 pins flow_route.steps deep-equal to flow_steps at every step of a linear flow with ahead: 'end', and both panels draw one ApprovalStepLine from that one member.

6. Tests pin the real service path. flow-route.integration.test.ts boots a real ObjectQL over SqlDriver, the real AutomationEngine with its logic nodes (the gateway is a real decision), the real approval node and ApprovalService; every request is opened by the engine and every decision resumes the run; the route is read through svc.getRequest. The dev's repro on origin/main's producer reports 5 of 6 red: the green one is case 6, "the list read serves no route, as it serves no flow_steps" — green on both sides by construction (the list read never served either member), which is what the dev reports; case 1's flow_steps assertion is likewise green on both sides on purpose. The unit file covers the branch kinds a live run reaches slowly.

7. Gates. The dev's 110 locally derived gates are the dev's reading and do not carry to the head; the head's check-runs are the verdict. Readings of /commits/4efa377e…/check-runs: at 2026-10-27T23:57Z 40 runs, 29 in progress, 0 failures; at 2026-10-28T00:05Z 60 runs, 28 in progress (the 16 Test UI shards, 8 Test Core shards, Lint UI, Type Check UI, two Type Check lanes), 26 success, 6 skipped, 0 failures. Final reading before this record was written, at 2026-10-28T00:09Z: 61 runs, 41 success, 6 skipped, 0 failure, 14 still in progress (Test UI shards 2, 7, 8, 9, 12 and 14 of 16; Test Core shards 2, 3, 4, 5, 6 and 7 of 8; Lint UI; Type Check UI). An in-progress gate is an honest reading, not a pass: no check on the head has failed, and the landing pre-check (every check green) is the owning seat's to re-read before the queue; this record does not stand in for it.

② Semver level

patch on all four touched published packages. Right by the rule: Metadata-protocol: none takes patch, and a non-protocol widening ships patch whatever its Clause-② arm. No minor is owed because no authorable surface moved; no BREAKING banner, no ADR-0087 disposition, no tombstone. Changeset bodies and the PR body carry the same two declaration lines.

③ Boundary flags

• Dev flag, "the line does not mark an undecided tail": accepted. The served row says ahead: 'undecided'; the line ending at the last listed step draws no guess. A marker is a ui follow-up if wanted, not a defect.
• Dev flag, "who sees which steps changed on the record panel" (the run's rows are read as the system): accepted. What crosses is step ids, labels and states, which flow_steps already served to the same reader; no approver, payload or comment data rides it.
• Dev flag, ordering by created_at with a same-millisecond tie: accepted; a run opens its next request only after the previous decision. created_at is written as an ISO string and formatOutput canonicalises Field.datetime to ISO on read on every SQL dialect, so the rule's typeof === 'string' guard holds off sqlite too.
• Dev flag, the full packages/app-shell suite not run locally: the 16 Test UI shards on the head are the reading (see ① 7).
• Deviation, Metadata-protocol re-judged from the claim's provisional added to none: the re-judgment is right (① 4).
• Deviation, branch claude/project-thread-04q6o5 rather than claude/issue-26668-*: platform-assigned, written as measured in the claim; Implemented-by names it.
• Observation, non-blocking: stepsAhead seeds seen with the current node only, so a walk that re-enters a step already in passedSteps would list that id twice and ApprovalStepLine keys rows by s.id. Reachable only on an unconditioned approve-edge cycle, which the engine would itself loop on; no guess is drawn. A follow-up may seed seen with the passed ids.
• Observation, non-blocking: the passedSteps docblock says rows of other runs are ignored; the function does not filter by run — the caller's where: { flow_run_id } does. Doc nit.
• Observation: attachFlowRoute adds one system read per single get (limit: 1000), display-only and caught, as attachFlowSteps is.
• Author: PR user.login is objectstack-fleet[bot]; no relay login to name.
• Governed surfaces: none of the 18 paths; 1,544 changed lines, under the 3,000 threshold; not Tier H. The schema face alone makes this review owed. Landing stays the owning seat's, through the queue, once every check on the head is green.

Implemented-by: claude/project-thread-04q6o5
Reviewed-by: session_01WGufzgbJhFoXYsLSe5WSPP

VERDICT: PASS

Generated by Claude Code

维护者速读 (席位终稿)

• 改了什么：审批单读取新增 flow_route，包含三部分。① 本单所在流程运行已走过的审批步骤，取自同一次运行自己的审批单行，不取流程图。② 本单当前步骤。③ 后续步骤：只对待审单列出，且只在流程图本身就能确定时列出，遇到未决定的分支即停，并标明 ahead: 'undecided'。flow_steps（流程图主干）原样保留。业务记录审批面板和审批单页面都改画 flow_route，fix(app-shell): the approval step line draws the route the request's run took, not the flow graph's first branch #26666 的客户端临时方案和「不画步骤线」规则一并删除。
• 为什么改：审批走「直属上级 → 仅财务」这类分支时，服务端只给主干，而且全部标「待办」，本单所在的步骤根本不在其中，步骤线只能不画或画错。
• 风险与回滚：只新增字段，flow_steps 字节不变，老客户端不受影响。每次单条读取多一次按 flow_run_id 的系统查询（最多 1000 行）。回滚 = revert 本 PR。
• 先看：packages/plugins/plugin-approvals/src/approval-route.ts 的 stepsAhead（哪些节点会让后续步骤停为 undecided），以及 packages/spec/src/contracts/approval-service.ts 的 flow_route 文档。
• 两分钟验证：pnpm --filter @objectstack/plugin-approvals exec vitest run src/flow-route.integration.test.ts，预期 6 项全绿；报告中那条路线只有「Manager（done）· Finance（current）」两步，ahead 为 undecided。
• 需要你做的：无，席位落地。

席位意见：接受。契约复核 PASS（6456957540），确认「不猜路线」成立：已走步骤只来自本次运行的审批单行，后续步骤遇到判断、条件、分叉、回环或子流程即停。复核指出的一句不实注释已在 b97005bf 改正，这一提交只改注释。

席位核对 · ACCEPT · domain:spec seat 3 · os-support-ai · session session_01WGufzgbJhFoXYsLSe5WSPP · 2026-10-28T00:44Z

Head: b97005bf14417759f5fdf57e4cb90c41622774bd · card #26668 · claim 6455118705

1. 形态: a draft PR to main whose only closing keyword is Fixes #26668. It has 18 paths, +1127 / −418. Everything sits inside the claim surface: the spec contract, plugin-approvals approval-route.ts and its service wiring, the two app-shell rail readers and the step-line component, their tests, approvals.mdx, the plugin README and changesets. check-governed-merges --pr 26976 reports NOT governed, 1545 lines, under 3000, so the ordinary queue landing applies. The assignee is os-support-ai.
2. 前提实测: the premise holds, measured by the dev on origin/main 7a2818c5. A contract_approval-shaped request routed manager → finance only serves every trunk entry upcoming and leaves finance_only absent. A route that rejoins the trunk is served the joint rung as done, a rung the run never visited. Five of the six route pins are red on main. The sixth, the list-read control, is green on purpose, and the review confirmed it.
3. 门禁 check-runs (on this head): 63 runs: 57 success, 6 skipped (opt-in or path selector), none red or pending, read at 2026-10-28T00:43Z. Mergeable state is clean. The contract-tier review PASSED on 4efa377e (6456957540). This head adds one comment-only commit on top of it: the seat read the compare diff, which changes one docblock line in approval-route.ts and no code. The review therefore carries to this head. The dev's local runs: spec, plugin-approvals and app-shell suites green, and dispatch gates 110 derived, 110 run, 0 NOT-MEASURED.
4. 接受的偏差: (a) The claim provisionally gave Metadata-protocol: added; the dev re-judged it to none. The review agrees: flow_route is a served read member and nothing authorable, the same pair as feat(plugin-approvals,rest,client): a record-anchored approval lock read, { locked } for every caller who can read the record #26361 in the same file. Clause-②: yes (widening), and all four published packages take a patch. (b) The branch is the platform-assigned claude/project-thread-04q6o5, as written in the claim. (c) Observations accepted without change. A step re-entered on an unconditioned approve cycle could be listed twice; that path is reachable only on a cycle the engine itself would loop on, and no guess is drawn. Auto-approved rungs that have no request row are absent from the route; no row exists, so this is no guess either. The record panel now shows passed step labels to viewers who did not take part, but those labels are the same data flow_steps already served to the same reader.
5. 范围外去向: nothing is filed. ahead: 'undecided' has no visual marker on the line, which the review judged a possible ui follow-up rather than a defect. The seat does not file it unless the ui lane asks. The PR body says nothing of plugin-approvals: the approval request page's step rail lists one fixed path, so a request routed to the finance-only rung shows step 2 as the joint legal + finance rung #26563 is left, because fix(app-shell): the approval step line draws the route the request's run took, not the flow graph's first branch #26666 completed it and this PR draws the line again.
6. 落地条款: the seat checked the prose faces against the diff on this head: the PR body, the changesets, the flow_route contract doc, which says the line never draws flow_steps, approvals.mdx and the README. The passedSteps docblock is now true. The seat readies the PR and arms auto-merge in this act, then follows it to MERGED.

Generated by Claude Code