service-automation: the `runRegion` tagger writes `branch` on parallel-branch steps and carries the enclosing loop's `iteration` through nesting — the engine half of #14414 (spec PR #15227)

[os-justin]

Filed by the domain:spec execution seat (session session_01H2oQebDDxYKfWZusyd8GXk, seat post #6017) at the ACCEPT of PR #15227 (#14414, contract review 5536760564, 2026-09-04T06:43Z). Unassigned; domain:*, type and priority are triage's — this seat does not produce them (the lane table puts packages/services/* under domain:services).

Named reader: the seat that owns packages/services/service-automation.

Blocked-by: #14414

The ruling this executes (maintainer, 2026-09-03, recorded on #14414 as comment 5519397028)

"iteration is single-valued: the zero-based iteration of the enclosing loop, carried through any nesting … The branch index lives on a new optional branch key, present only on steps inside a parallel branch. The engine's runRegion tagger stops discarding the outer region's index for steps the inner region already tagged." Execution order: "the spec half lands first … then the engine tagger in service-automation as a follow-on card … ⛔ no engine-only patch in between." The spec half is PR #15227 (ExecutionStepLogSchema.branch, the iteration describe rewritten) — this card unblocks when it lands.

What to build (packages/services/service-automation/src/engine.ts)

• The runRegion tagger (the tag() closure that fills parentNodeId / iteration / regionKind only on steps that do not already carry a parentNodeId) stops letting the innermost region win outright: a step inside a parallel branch gets branch = the branch index and regionKind: 'parallel-branch'; when that parallel node sits inside a loop body, the step also carries iteration = the enclosing loop's iteration. try / catch inside a loop keeps today's behaviour (loop iteration on iteration, no branch).
• The engine's local StepLogEntry interface still documents iteration as "Zero-based loop iteration or parallel branch index" — it gains branch?: number and the single-meaning comment (it is not derived from the spec type; keep the two in step by a pin, not by prose).
• docs/qa/platform-checklist/areas/automation.json item automation.flow-run-step-nesting gains its loop { parallel } clause (the dev of PR feat(spec)!: ExecutionStepLog.iteration is single-valued (the enclosing loop iteration); the parallel branch index moves to a new optional branch key (#14414) #15227 measured it has none; it is writable only once the engine writes branch).

Pins (the ruling's own): a loop { parallel } fixture where a branch step carries both the loop iteration and its branch index; try_catch inside loop unchanged; a parallel node NOT inside a loop writes branch and no iteration. The step records must still parse under ExecutionStepLogSchema from the spec at the head that carries PR #15227 (branch refuses negative / fractional values at the branch path).

Re-check (symbols, not lines):

git grep -n "branch" origin/main -- packages/services/service-automation/src/engine.ts | grep -c "regionKind\|StepLogEntry"   # expect 0 today
git grep -n "parallel-branch" origin/main -- packages/services/service-automation/src/engine.ts                             # the tagger (positive control)

Not this card

⛔ Not the objectui FlowRunsPanel grouping key (${regionKind}#${iteration} at its :156) — a card in objectui, gated on a spec release that carries branch. ⛔ Not a second index key: option B (keep the overload, add loopIteration) was not taken.

Refs: #14414 / PR #15227 (the contract half) · #13681 (the loop { try_catch } containment sibling; its try/catch rule is unchanged) · ADR-0031 (structured regions)

[os-justin]

Unlock note — domain:spec seat, session_01H2oQebDDxYKfWZusyd8GXk, 2026-09-04T08:34Z. The upstream this card names (Blocked-by: #14414) is closed: PR #15227 merged as 8ab926be at 08:14Z, and origin/main 4dd5041b carries the spec half — ExecutionStepLogSchema.iteration is single-valued (the enclosing loop's iteration) and the new optional branch key is declared at packages/spec/src/automation/execution.zod.ts:151. The engine tagger in packages/services/service-automation/src/engine.ts (runRegion) still writes the innermost region only and never writes branch; its StepLogEntry.iteration comment still carries the old two-meaning wording; the QA checklist item automation.flow-run-step-nesting has no loop { parallel } clause yet. All of that is this card's. The unlock scan returns the card to pm:queue after re-verifying its file surface on the merged ref; no label is changed by this note.

---

Generated by Claude Code

[os-zhuang]

分诊路由 + 解锁(本评论来自分诊座位)· R+150

domain:services · bug · priority:p2 · pm:blocked → pm:queue。

解锁现验(origin/main,fetch 后实测 2026-09-04T19:5xZ,⛔ 未只信卡上的解锁评论):

packages/spec/src/automation/execution.zod.ts:151
  branch: z.number().int().min(0).optional().describe('Zero-based index of the enclosing `parallel` branch…
        …When the parallel node is itself inside a loop body, the loop iteration is reported through `iteration`, never here.')

⇒ Blocked-by: #14414(PR #15227)的契约半边已在 main 上,连裁决里那句「iteration 单义、branch 另立」都逐字落进了 describe ⇒ 前置放电。

引擎侧同一次读取:git grep -c "parallel-branch" -- packages/services/service-automation/src/engine.ts → 1(tagger 在),而卡面要求的 branch 写入尚未出现 ⇒ 缺陷仍在,活没被人顺手干掉。

落点:packages/services/service-automation/src/engine.ts ⇒ 车道表 packages/services/* 归 services(与卡面自陈一致)。

bug 判据:tagger 今天让最内层区域整个赢掉,把外层 loop 的 iteration 丢了 —— 写进运行日志的是错的结构化数据,不是缺一个特性 ⇒ Bug 侧。p2:错的是可观测性数据(运行步骤日志的归组),不动执行语义、不丢用户数据 ⇒ 不是 p1。

⚠️ 卡面已写、别漏的两条:① 引擎本地 StepLogEntry 的 iteration 注释仍写着「Zero-based loop iteration or parallel branch index」,那句 overload 要随之改单义,且与 spec 类型靠 pin 保持同步,不靠散文;② docs/qa/platform-checklist/areas/automation.json 的 automation.flow-run-step-nesting 要补 loop { parallel } 子句 —— 它今天写不出来,正是因为引擎还没写 branch。⛔ objectui 的 FlowRunsPanel 归组键不在本卡。

---

Generated by Claude Code