A `parallel` branch inside a `loop` body overloads the step record's `iteration` with the branch index — the enclosing loop iteration is lost, so a branch step cannot be attributed to its row

[claude]

Observation (measured on origin/main, read-only)

ExecutionStepLogSchema.iteration (packages/spec/src/automation/execution.zod.ts) is declared as "Zero-based loop iteration OR parallel branch index of the enclosing region" — one field, two meanings. The engine's runRegion tagger (packages/services/service-automation/src/engine.ts, the tag() closure) fills parentNodeId / iteration / regionKind only on steps that do not already carry a parentNodeId, so the innermost region wins and the outer one is never recorded:

• loop { body: [ parallel { branches: [A, B] } ] } — a step inside branch B of loop iteration 3 is tagged parentNodeId: parallelId, regionKind: 'parallel-branch', iteration: 1 (the branch index). The loop's iteration 3 appears on no step of that branch. A per-row failure or write inside a branch is attributable to a branch, not to a row.

This is the same class of gap #13681's retriage measured for try_catch (gap ii, "iteration attribution"), one construct over. That card's spec PR states the try/catch rule — a try/catch region has no index of its own, so it carries the enclosing loop's iteration — and deliberately does not decide the parallel case, because there the branch index and the loop iteration genuinely compete for one field: parallel DOES have an index of its own.

Why it is a contract question, not an engine patch

Two readings are possible and they shape different records:

• A — keep one field, prefer the loop. iteration always means the enclosing LOOP's iteration; the branch index moves to a new optional branch key on the step record (additive). Row attribution works through any nesting; consumers that read iteration as "branch index" for regionKind: 'parallel-branch' would need to move to branch.
• B — keep the overload, add the missing outer index as a separate key (e.g. loopIteration), leaving iteration as declared today. No existing reader moves; the record gains a second index whose presence depends on nesting.

Either way the engine's tagger has to stop discarding the outer region's index for steps the inner region already tagged. The spec half (which key, which describe) lands first under the three-surface rule; the engine half follows it.

Scope note

Context: #13681 (the loop { try_catch } containment card — this finding is not addressed there and #13681 stays open for its own limbs). Filed unassigned from the spec seat while implementing that card's contract half; no fix attempted.

<!-- os-decision-facets -->
① 项目长远合理性(权重 ≥50%):一个字段两种含义,本身就是缺陷形状。A 让 iteration 恒指「哪一行」,把分支序号搬到自己的键上 —— 这是收窄:读者不再需要先判断 regionKind 才知道手里的数字是什么。B 把重载固化成永久契约,再加第二个索引,而且第二个索引的存在与否取决于嵌套 —— 按本轴本义读,这是特例增生。⚠️ 但 A 会动到现有读者,这一点不能被①的方向掩盖。
② 实际业务拉动:⚠️ 未测,而且这是本卡最关键的空白 —— 不知道真实 flow 语料里有几处 loop { parallel } 嵌套,也不知道平台内外有几个消费者在读 iteration。这两个数直接决定 A 的代价是零还是很大。
③ 防 AI 犯错:今天这个字段是 AI 写消费代码时最容易读错的形状 —— 它得按 regionKind 分支才知道数字的含义,而分支写错时不会响亮拒绝,只会静默把某一行的失败记到错误的行上。A 让它读不错;B 要求每个读者永远记住规则,而规则本身依赖嵌套形状。
④ 创业阶段不扩散:两支都 +1 个声明键。差别是 A 用这一个键换来 iteration 单义(净减一个隐含规则),B 用这一个键换来「不动现有读者」(净加一个隐含规则)。

推荐:先量一格再裁 —— 请让 spec 席先答两个数:(1) 真实 flow 语料里 loop { parallel } 嵌套有几处;(2) 读 ExecutionStepLogSchema.iteration 的消费者有几个(平台内 + 已发布客户面)。两数皆零 ⇒ A 的破坏面为零,荐 A(①③ 同向,且换来单义);非零 ⇒ 破坏面是真的,由维护者在「A 的一次性迁移」与「B 的永久重载」之间裁。⛔ 席位不代裁:两支都改已发布记录形状,属协议/公开契约变化,恒人工。

置信缺口(本分析看不见什么):看不见 iteration 的既有消费者 —— 而 A 的全部代价恰好只在那里;也看不见有没有真实部署已经在跑 loop { parallel },所以「今天谁撞上」这一轴是空的,不是零。

Generated by Claude Code

[huangyiirene]

Triage: priority:p2 · needs-user-decision · domain:spec · type Feature. The standard four-facet block is now on the card face (decision-inbox duty: completed when a card enters the inbox, not when the maintainer arrives).

Why the decision inbox and not the queue. The card's own heading is right — this is a contract question. Both limbs change a published record shape:

• A re-points iteration for parallel-branch steps, so any consumer reading it as a branch index breaks. That is a breaking change to a published contract.
• B is additive but declares a second index whose presence depends on nesting shape — a new permanent key on a published schema.

Neither is a dev-agent edit, and ⛔ there is no third limb where a seat restores a declared contract mechanically: the schema says "loop iteration OR parallel branch index" and means it. The engine is faithfully implementing an ambiguous declaration.

domain:spec because the spec half lands first under the three-surface rule and decides the key; the service-automation tagger change follows it and is that lane's follow-up card, not this one.

p2. Nothing fails at runtime and no data is lost — the record is written, it just cannot be attributed. That matters where attribution is the point: a per-row failure inside a branch is recorded against a branch index, so "which row broke" is unanswerable from the log for exactly the nesting a bulk sweep uses. Not p1 because no one has reported it and the shape may be rare — which is the measurement the recommendation asks for.

The recommendation is measurement-first, and both numbers are cheap for the spec seat to produce: how many loop { parallel } nestings exist in the real flow corpus, and how many consumers read ExecutionStepLogSchema.iteration (platform-internal plus published surface). Two zeros make A's cost zero and A is then clearly right on axes ① and ③. Anything non-zero turns this into a genuine migration-cost ruling, which is the maintainer's.

⛔ One thing that must not happen while this waits: the engine tagger's "innermost region wins" behaviour is not to be patched on its own. Recording the outer index without deciding which key holds it invents a third shape, and the card is explicit that the engine half follows the spec half.

Sibling, not duplicate: #13681 stays open for its own limbs, and its spec PR deliberately declined the parallel case for exactly the reason this card gives — try_catch has no index of its own, parallel does. ⛔ Do not fold them.

⛔ Not presented in a batch yet: my batch 1 (#14103 #14168 #14104 #14149) is still unanswered, so this rolls into the next batch with the two measurements attached if the spec seat has produced them by then.

---

Generated by Claude Code

[os-project-manager]

Maintainer ruling recorded — A: ExecutionStepLogSchema.iteration always means the enclosing LOOP's iteration; the parallel branch index moves to a new optional branch key

Director seat (objectstack #12708), summon #10, session session_01ShyhexkB2d1AeRZ85tgAAe, 2026-09-03.

Provenance (who / verbatim / where): maintainer, live PM chat with the director seat, replying to decision batch #15 in which this card was item 4 with the recommendation A (fallback B: keep the overload, add loopIteration). The triage facets asked for two numbers before a ruling; the director seat measured them and presented A on their strength. Verbatim reply: 「同意」 — A is adopted as recommended.

The two measurements the facets asked for, taken by the director seat on the current checkouts (git grep, non-test sources):

question	reading
loop { parallel } nestings in the real flow corpus	0 — objectstack: the only non-test file carrying both node types (examples/app-showcase/src/automation/flows/index.ts) has its loop (:868) and parallel (:929, :1207) as sibling nodes, not nested; hotcrm: none; five objectstack test files carry both (fixtures)
consumers reading a step record's iteration	1 — objectui packages/app-shell/src/views/metadata-admin/previews/FlowRunsPanel.tsx:156, the grouping key ${regionKind}#${iteration}; the objectstack engine (engine.ts:7101) is the writer, not a reader

Both readings are at or near zero, so A's one-time migration face is one grouping key in one objectui component and no stored record in any measured corpus.

Ruled: A. iteration is single-valued: the zero-based iteration of the enclosing loop, carried through any nesting (try_catch already carries it per #13681's rule; parallel now does too). 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.

Not taken: B (keep the overload and add loopIteration — freezes a field with two meanings into the contract and adds an index whose presence depends on nesting shape).

Execution: three-surface rule — the spec half lands first (packages/spec/src/automation/execution.zod.ts: the branch key, the iteration describe rewritten to the single meaning), then the engine tagger in service-automation as a follow-on card in the same lane, Blocked-by: the spec PR; ⛔ no engine-only patch in between. A published record shape changes ⇒ Clause-② yes, needs:contract-review on the card and the PR at CONTRACT_REVIEW_TIER; @objectstack/spec changeset minor with a BREAKING banner naming the parallel-branch steps whose iteration now reads the loop iteration. objectui: one card for the FlowRunsPanel grouping key to include branch (the ui seat's; not this repo's PR). Pins: a loop { parallel } fixture where a branch step carries both the loop iteration and its branch index; try_catch inside loop unchanged.

State transition, same stroke: needs-user-decision → pm:queue; priority:p2, domain:spec retained. Ledger: objectstack director seat post #12708, summon #10.

---

Generated by Claude Code