feat(spec)!: ExecutionStepLog.iteration is single-valued (the enclosing loop iteration); the parallel branch index moves to a new optional branch key (#14414) (#15227)

* feat(spec)!: ExecutionStepLog.iteration is single-valued; parallel branch index moves to a new optional branch key

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01H2oQebDDxYKfWZusyd8GXk

* chore(spec): regenerate migrations registry for execution-step-iteration-single-valued

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01H2oQebDDxYKfWZusyd8GXk

* chore(spec): regenerate execution reference and authorable-surface shard for ExecutionStepLog.branch

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01H2oQebDDxYKfWZusyd8GXk

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-justin

.changeset/execution-step-branch-key.md

@@ -0,0 +1,63 @@
+---
+"@objectstack/spec": minor
+---
+
+feat(spec)!: `ExecutionStepLog.iteration` is single-valued — the enclosing loop iteration — and the parallel branch index moves to a new optional `branch` key (#14414)
+
+<!-- adr-0087: registered execution-step-iteration-single-valued -->
+
+**BREAKING** for any consumer that read `iteration` as the parallel branch index
+on a `regionKind: 'parallel-branch'` step record: that number now means the
+enclosing `loop`'s iteration, and the branch index lives on `branch`. Shipped as
+`minor` under the repo's launch-window convention for breaking changes; the
+hand-migration prescription is registered under protocol major 18. Maintainer
+ruling 2026-09-03 on #14414 (director decision batch #15, verbatim 「同意」):
+option A.
+
+`ExecutionStepLogSchema.iteration` was declared as "zero-based loop iteration
+OR parallel branch index of the enclosing region" — one field, two meanings,
+told apart only by reading `regionKind` first. For `loop { body: [ parallel {
+branches } ] }` the engine tagged each branch step with the branch index and no
+step of that branch with the loop iteration, so a per-row failure inside a
+branch was attributable to a branch, never to the row. The sibling `try_catch`
+rule (a try/catch region has no index of its own, so it carries the loop
+iteration) had deliberately left `parallel` open, because a parallel region
+DOES have an index of its own.
+
+**What changes on the record shape** (`packages/spec/src/automation/execution.zod.ts`):
+
+- `iteration` — single-valued: the zero-based iteration of the enclosing
+  `loop`, carried through any nesting (`try` / `catch` already carried it;
+  `parallel-branch` now does too). The try/catch sentence is unchanged.
+- `branch` — **new**, optional, `integer >= 0`: the zero-based index of the
+  enclosing `parallel` branch, present only on a step inside a parallel
+  branch. A branch step of a parallel node inside a loop body carries both.
+- `regionKind` — unchanged vocabulary; its describe now points the
+  `parallel-branch` index at `branch`.
+
+**What does NOT change in this PR:** the engine tagger in
+`@objectstack/service-automation` still writes the innermost region only —
+today it writes the branch index into `iteration` on `parallel-branch` steps
+and never writes `branch`. The tagger change is a follow-on card in the same
+lane, blocked by this one (three-surface rule: spec first, no engine-only patch
+in between). A step record written by an engine that predates that follow-on
+therefore carries no `branch` key, and its `iteration` under `parallel-branch`
+still holds the legacy branch index.
+
+## FROM → TO
+
+```ts
+// before — one key, two meanings; the loop iteration of a branch step is lost
+const step = { regionKind: 'parallel-branch', iteration: 1 }; // 1 = branch index
+const branchIndex = step.regionKind === 'parallel-branch' ? step.iteration : undefined;
+
+// after — one meaning per key; a branch step inside a loop body carries both
+const step = { regionKind: 'parallel-branch', iteration: 3, branch: 1 };
+const branchIndex = step.branch;   // 1 — the branch
+const rowIteration = step.iteration; // 3 — the enclosing loop's row
+```
+
+Fix: where a consumer groups or labels `parallel-branch` steps by `iteration`
+(the objectui `FlowRunsPanel` grouping key is the one measured reader), read
+`branch` for the branch index and keep `iteration` for the row. Reads of
+`iteration` on `loop-body`, `try` and `catch` steps need no change.

content/docs/references/automation/execution.mdx

@@ -140,8 +140,9 @@ const result = CheckpointSchema.parse(data);
 | **error** | `{ code: string; message: string; stack?: string }` | optional | Error details if step failed |
 | **retryAttempt** | `integer` | optional | Retry attempt number (0 = first try) |
 | **parentNodeId** | `string` | optional | Enclosing structured-region container node ID (loop/parallel/try_catch) |
-| **iteration** | `integer` | optional | Zero-based loop iteration or parallel branch index of the enclosing region. A step inside a `try` / `catch` region that is itself inside a loop body carries the enclosing loop's iteration — a try/catch region has no index of its own — while `regionKind` stays `try` / `catch`. |
-| **regionKind** | `string` | optional | Region kind the step ran in: loop-body \| parallel-branch \| try \| catch. Stays `try` / `catch` for a step inside a try/catch region nested in a loop body; the loop is reported through `iteration`. |
+| **iteration** | `integer` | optional | Zero-based iteration of the enclosing `loop`, carried through any nesting — a step inside a `parallel` branch that is itself inside a loop body carries the loop's iteration here and its branch index on `branch`. A step inside a `try` / `catch` region that is itself inside a loop body carries the enclosing loop's iteration — a try/catch region has no index of its own — while `regionKind` stays `try` / `catch`. |
+| **branch** | `integer` | optional | Zero-based index of the enclosing `parallel` branch. Present only on a step inside a parallel branch; absent everywhere else. When the parallel node is itself inside a loop body, the loop iteration is reported through `iteration`, never here. |
+| **regionKind** | `string` | optional | Region kind the step ran in: loop-body \| parallel-branch \| try \| catch. Stays `try` / `catch` for a step inside a try/catch region nested in a loop body; the loop is reported through `iteration`. For `parallel-branch` the branch index is reported through `branch`, and the enclosing loop iteration — when the parallel node sits inside a loop body — through `iteration`. |
 | **metrics** | `{ selected?: integer; acted?: integer; unmeasuredEffect?: boolean }` | optional | Records this step selected / acted on, as reported by the node executor |
 | **skippedBy** | `{ nodeId: string; edgeId?: string; label?: string }` | optional | The gate that closed, when `status` is `skipped` |
 
@@ -195,8 +196,9 @@ const result = CheckpointSchema.parse(data);
 | **error** | `{ code: string; message: string; stack?: string }` | optional | Error details if step failed |
 | **retryAttempt** | `integer` | optional | Retry attempt number (0 = first try) |
 | **parentNodeId** | `string` | optional | Enclosing structured-region container node ID (loop/parallel/try_catch) |
-| **iteration** | `integer` | optional | Zero-based loop iteration or parallel branch index of the enclosing region. A step inside a `try` / `catch` region that is itself inside a loop body carries the enclosing loop's iteration — a try/catch region has no index of its own — while `regionKind` stays `try` / `catch`. |
-| **regionKind** | `string` | optional | Region kind the step ran in: loop-body \| parallel-branch \| try \| catch. Stays `try` / `catch` for a step inside a try/catch region nested in a loop body; the loop is reported through `iteration`. |
+| **iteration** | `integer` | optional | Zero-based iteration of the enclosing `loop`, carried through any nesting — a step inside a `parallel` branch that is itself inside a loop body carries the loop's iteration here and its branch index on `branch`. A step inside a `try` / `catch` region that is itself inside a loop body carries the enclosing loop's iteration — a try/catch region has no index of its own — while `regionKind` stays `try` / `catch`. |
+| **branch** | `integer` | optional | Zero-based index of the enclosing `parallel` branch. Present only on a step inside a parallel branch; absent everywhere else. When the parallel node is itself inside a loop body, the loop iteration is reported through `iteration`, never here. |
+| **regionKind** | `string` | optional | Region kind the step ran in: loop-body \| parallel-branch \| try \| catch. Stays `try` / `catch` for a step inside a try/catch region nested in a loop body; the loop is reported through `iteration`. For `parallel-branch` the branch index is reported through `branch`, and the enclosing loop iteration — when the parallel node sits inside a loop body — through `iteration`. |
 | **metrics** | `{ selected?: integer; acted?: integer; unmeasuredEffect?: boolean }` | optional | Records this step selected / acted on, as reported by the node executor |
 | **skippedBy** | `{ nodeId: string; edgeId?: string; label?: string }` | optional | The gate that closed, when `status` is `skipped` |
 

packages/spec/authorable-surface/automation.json

@@ -120,6 +120,7 @@
     "automation/ExecutionLog:tenantId",
     "automation/ExecutionLog:trigger",
     "automation/ExecutionLog:variables",
+    "automation/ExecutionStepLog:branch",
     "automation/ExecutionStepLog:completedAt",
     "automation/ExecutionStepLog:durationMs",
     "automation/ExecutionStepLog:error",

packages/spec/src/automation/execution.test.ts

@@ -114,6 +114,73 @@ describe('ExecutionStepLogSchema', () => {
     expect(step.parentNodeId).toBe('guard');
     expect(step.regionKind).toBe('try');
     expect(step.iteration).toBe(3);
+    // Only a `parallel` branch has an index of its own; a try/catch region
+    // never carries `branch`, so the key is absent — not `0`, not `null`.
+    expect(step.branch).toBeUndefined();
+    expect('branch' in step).toBe(false);
+  });
+
+  it('a step inside a parallel branch nested in a loop body carries the loop iteration on `iteration` and the branch index on `branch`', () => {
+    // `loop { body: [ parallel { branches: [A, B] } ] }` — `iteration` is
+    // single-valued (the enclosing LOOP's, carried through any nesting) and a
+    // parallel region, which DOES have an index of its own, reports it on
+    // `branch`. Both at once is what makes a per-row failure inside a branch
+    // attributable to its row; under the old one-field-two-meanings declaration
+    // the branch index displaced the loop iteration and the row was lost.
+    const step = ExecutionStepLogSchema.parse({
+      nodeId: 'notify',
+      nodeType: 'email',
+      status: 'failure',
+      startedAt: '2026-01-01T00:00:00Z',
+      parentNodeId: 'fan_out',
+      regionKind: 'parallel-branch',
+      iteration: 3,
+      branch: 1,
+      error: { code: 'NODE_FAILURE', message: 'mailbox unavailable' },
+    });
+    expect(step.parentNodeId).toBe('fan_out');
+    expect(step.regionKind).toBe('parallel-branch');
+    expect(step.iteration).toBe(3);
+    expect(step.branch).toBe(1);
+  });
+
+  it('`branch: 0` — the first branch — survives the parse as 0', () => {
+    // Zero is a real index; a falsy-check anywhere on the way would drop it.
+    const step = ExecutionStepLogSchema.parse({
+      nodeId: 'notify',
+      nodeType: 'email',
+      status: 'success',
+      startedAt: '2026-01-01T00:00:00Z',
+      parentNodeId: 'fan_out',
+      regionKind: 'parallel-branch',
+      branch: 0,
+    });
+    expect(step.branch).toBe(0);
+    expect(step.iteration).toBeUndefined();
+  });
+
+  it.each([
+    [-1, 'too_small'],
+    [1.5, 'invalid_type'],
+  ])('refuses `branch: %j` with one zod issue at path ["branch"] (code %s)', (value, code) => {
+    // A branch index is a zero-based integer, like `iteration`. The assertion
+    // is on the issue's PATH and CODE, not on "it threw": a refusal from some
+    // other key would otherwise pass for this one.
+    const result = ExecutionStepLogSchema.safeParse({
+      nodeId: 'notify',
+      nodeType: 'email',
+      status: 'success',
+      startedAt: '2026-01-01T00:00:00Z',
+      parentNodeId: 'fan_out',
+      regionKind: 'parallel-branch',
+      iteration: 0,
+      branch: value,
+    });
+    expect(result.success).toBe(false);
+    const issues = result.success ? [] : result.error.issues;
+    expect(issues).toHaveLength(1);
+    expect(issues[0].path).toEqual(['branch']);
+    expect(issues[0].code).toBe(code);
   });
 });
 

packages/spec/src/automation/execution.zod.ts

@@ -128,14 +128,28 @@ export const ExecutionStepLogSchema = lazySchema(() => z.object({
   // so run observability can nest per-iteration / per-branch body steps under
   // the container instead of showing it as a single opaque step.
   parentNodeId: z.string().optional().describe('Enclosing structured-region container node ID (loop/parallel/try_catch)'),
+  // `iteration` is SINGLE-VALUED: the zero-based iteration of the enclosing
+  // `loop`, carried through any nesting. It used to double as the parallel
+  // branch index — one field, two meanings, told apart only by reading
+  // `regionKind` first — so for `loop { body: [ parallel { branches } ] }`
+  // every branch step recorded the branch index and no step of that branch
+  // recorded the loop iteration: a per-row failure inside a branch was
+  // attributable to a branch, never to the row. The branch index now has its
+  // own key, `branch`, below (maintainer ruling 2026-09-03, option A: one
+  // meaning per key; the overload-plus-second-index alternative was not taken).
+  //
   // A `try` / `catch` region has no index of its own, so a step it ran for a
   // loop body — `loop { body: [ try_catch { try, catch } ] }`, the containment
   // spelling for a per-iteration failure that must not end the sweep — carries
   // the ENCLOSING LOOP's iteration while `regionKind` keeps naming the
   // try/catch region: the step says which region ran it AND which row it ran
   // for. Without that, a caught per-row failure is attributable to no row.
-  iteration: z.number().int().min(0).optional().describe('Zero-based loop iteration or parallel branch index of the enclosing region. A step inside a `try` / `catch` region that is itself inside a loop body carries the enclosing loop\'s iteration — a try/catch region has no index of its own — while `regionKind` stays `try` / `catch`.'),
-  regionKind: z.string().optional().describe('Region kind the step ran in: loop-body | parallel-branch | try | catch. Stays `try` / `catch` for a step inside a try/catch region nested in a loop body; the loop is reported through `iteration`.'),
+  iteration: z.number().int().min(0).optional().describe('Zero-based iteration of the enclosing `loop`, carried through any nesting — a step inside a `parallel` branch that is itself inside a loop body carries the loop\'s iteration here and its branch index on `branch`. A step inside a `try` / `catch` region that is itself inside a loop body carries the enclosing loop\'s iteration — a try/catch region has no index of its own — while `regionKind` stays `try` / `catch`.'),
+  // A `parallel` region DOES have an index of its own, which is exactly why it
+  // cannot share `iteration`: a branch step of a parallel node inside a loop
+  // body carries BOTH — `iteration` for the row, `branch` for the branch.
+  branch: z.number().int().min(0).optional().describe('Zero-based index of the enclosing `parallel` branch. Present only on a step inside a parallel branch; absent everywhere else. When the parallel node is itself inside a loop body, the loop iteration is reported through `iteration`, never here.'),
+  regionKind: z.string().optional().describe('Region kind the step ran in: loop-body | parallel-branch | try | catch. Stays `try` / `catch` for a step inside a try/catch region nested in a loop body; the loop is reported through `iteration`. For `parallel-branch` the branch index is reported through `branch`, and the enclosing loop iteration — when the parallel node sits inside a loop body — through `iteration`.'),
   // #4354: what the step did to the data, and — for a `skipped` step — which
   // gate stopped it. Both feed the run summary aggregated on ExecutionLog.
   metrics: ExecutionStepMetricsSchema.optional()

packages/spec/src/migrations/entries/semantic/18.execution-step-iteration-single-valued.ts

@@ -0,0 +1,60 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { SemanticMigration } from '../../types.js';
+
+export const entry: SemanticMigration = {
+  id: 'execution-step-iteration-single-valued',
+  surface:
+    '`ExecutionStepLog.iteration` on a step whose `regionKind` is '
+    + '`parallel-branch` — the per-step records under `ExecutionLog.steps`, as '
+    + 'the automation run endpoints return them — and the new optional '
+    + '`ExecutionStepLog.branch` key',
+  replacement:
+    'Read the parallel branch index from `branch`. `iteration` is now '
+    + 'single-valued: the zero-based iteration of the enclosing `loop`, carried '
+    + 'through any nesting, so a branch step of a `parallel` node that sits '
+    + 'inside a loop body carries BOTH keys — `iteration` for the row and '
+    + '`branch` for the branch. A consumer that grouped or labelled steps by '
+    + '`iteration` under `regionKind: parallel-branch` moves that read to '
+    + '`branch`; a consumer reading `iteration` on `loop-body`, `try` or '
+    + '`catch` steps changes nothing.',
+  reason:
+    'The key was declared as the zero-based loop iteration OR the parallel '
+    + 'branch index of the enclosing region — one field, two meanings, told '
+    + 'apart only by reading `regionKind` first. The engine tagged each step '
+    + 'with its innermost region only, so for a `parallel` node inside a `loop` '
+    + 'body every branch step recorded the branch index and no step of that '
+    + 'branch recorded the loop iteration: a per-row failure inside a branch '
+    + 'was attributable to a branch, never to the row the sweep was processing. '
+    + 'The sibling try/catch rule had already settled the containment case — a '
+    + 'try/catch region has no index of its own, so it carries the loop '
+    + 'iteration — and deliberately left `parallel` open, because there the '
+    + 'two indexes genuinely compete for one field. The maintainer ruling of '
+    + '2026-09-03 took option A: `iteration` always means the enclosing loop '
+    + 'iteration and the branch index moves to its own optional key, so a '
+    + 'reader no longer has to branch on `regionKind` to know which number it '
+    + 'holds, and getting that wrong no longer silently books a failure against '
+    + 'the wrong row. Option B — keep the overload and add a second index whose '
+    + 'presence depends on nesting shape — was not taken. This is not a '
+    + 'mechanical conversion: a step record written before this change carries '
+    + '`iteration` under `parallel-branch` with the branch-index meaning, and '
+    + 'only its producer knows whether the parallel node sat inside a loop. The '
+    + 'measured corpus held zero `loop { parallel }` nestings and one consumer '
+    + 'reading the key — a grouping key in the objectui flow-runs panel — so '
+    + 'the migration is a consumer-side read move, not a data rewrite. The '
+    + 'engine tagger that writes both keys follows this contract change as its '
+    + 'own card; until it lands, `branch` is declared and unwritten, and '
+    + '`iteration` on a `parallel-branch` step written by an older engine still '
+    + 'holds the branch index.',
+  acceptanceCriteria:
+    'No consumer reads `iteration` as a branch index: every read of a '
+    + '`parallel-branch` step\'s index goes through `branch`, and every read of '
+    + 'the enclosing loop iteration goes through `iteration` regardless of '
+    + '`regionKind`. A step record carrying `regionKind: parallel-branch`, '
+    + '`iteration: 3`, `branch: 1` parses under `ExecutionStepLogSchema` with '
+    + 'both numbers intact, and a negative or fractional `branch` is refused at '
+    + 'the `branch` path. A record written before the engine follow-on carries '
+    + 'no `branch` key; treat its `iteration` under `parallel-branch` as the '
+    + 'legacy branch index only when the record predates the engine build that '
+    + 'writes `branch`.',
+};