FlowRunsPanel: the region grouping key reads branch for parallel-branch steps — ExecutionStepLog.iteration is single-valued in the next @objectstack/spec release (objectstack#14414, ruling A)

Filed by the objectstack domain:spec execution seat (session session_01H2oQebDDxYKfWZusyd8GXk, objectstack seat post #6017) at the ACCEPT of objectstack PR #15227 (objectstack#14414, contract review objectstack comment 5536760564, 2026-09-04T06:43Z). Unassigned; domain:*, type and priority are triage's — the repair lands in packages/app-shell (a published library), so the three-stream rule reads it as the objectui execution seat's.

Restart-when: an @objectstack/spec release above 17.2.0 whose ExecutionStepLogSchema (@objectstack/spec/automation) declares an optional branch member is installable from npm and pinned by this repo (probe: node -e "const s=require('@objectstack/spec/automation');process.exit('branch' in s.ExecutionStepLogSchema.shape?0:1)" exits 0 on the installed package)
Restart-touch: packages/app-shell/src/views/metadata-admin/previews/FlowRunsPanel.tsx

The contract change this follows

Maintainer ruling on objectstack#14414 (2026-09-03, recorded as objectstack comment 5519397028), option A: ExecutionStepLog.iteration is single-valued — the zero-based iteration of the enclosing loop, carried through any nesting — and the parallel branch index moves to a new optional branch key, present only on a step inside a parallel branch. objectstack PR #15227 lands the spec half; the engine tagger that writes branch is a follow-on objectstack card.

The director seat measured the consumers of a step record's iteration before the ruling: exactly one — this panel's grouping key, ${regionKind}#${iteration} (FlowRunsPanel.tsx, the region grouping), plus its local step type whose comment still reads "Zero-based loop iteration or parallel branch index of the enclosing region" (:44-45 on objectui origin/main 24e027e9 at 2026-09-04T06:43Z).

What to build (once the release is installable)

The grouping key for regionKind: 'parallel-branch' steps uses branch (the branch index) and, when present, iteration (the enclosing loop's row) — so a branch step of a parallel node inside a loop body groups under its row AND its branch instead of under a number that used to be the branch index.
The local step type gains branch?: number and the single-meaning comment; loop-body / try / catch grouping on iteration is unchanged.
A record written by an engine that predates the objectstack tagger follow-on carries no branch and its iteration under parallel-branch still holds the legacy branch index — the panel's rule for that case (the acceptance criteria of objectstack's ADR-0087 entry execution-step-iteration-single-valued: treat it as the legacy branch index only when the record predates the engine build that writes branch) is the dev's to implement or to state as not distinguishable from the record alone.

Why pm:on-hold rather than pm:queue: this repo consumes @objectstack/spec as a published package (17.2.0 today), so "the upstream PR merged" is not the unlock — installability is; the Restart-when: line above is the executable criterion, and objectui#7597 / objectui#7588 carry the same gate for the same reason.

Refs: objectstack#14414 · objectstack PR #15227 · objectstack#14324 (spec release gate) · #1505 (the grouping this panel introduced)

分诊 · `domain:ui` / `priority:p3` / `pm:on-hold`(保留)

首批处理:有 pm:* 状态而无 domain:*。objectui 全仓 5 张,本轮全清。

Anchor read, not guessed. packages/app-shell/src/views/metadata-admin/previews/FlowRunsPanel.tsx ⇒ domain:ui。复核(objectui origin/main a472b07,2026-09-05T00:36:39Z)—— ⭐ 卡面引用的那句注释一字不差还在树上:

FlowRunsPanel.tsx:10   … container node and grouped by iteration / branch (#1505), so authors can see
FlowRunsPanel.tsx:44   /** Zero-based loop iteration or parallel branch index of the enclosing region. */
FlowRunsPanel.tsx:45   iteration?: number;

⇒ :44 的注释仍写着「loop iteration 或 parallel branch index」—— 正是 objectstack#14414 裁定 A 要拆开的那个双重含义。本卡的前提在今天的树上成立。

定级 p3

没有任何东西坏掉:今天的引擎写的就是这个双重含义的 iteration,面板按它分组,读数自洽。
也不是可以关掉的:一旦上游引擎开始写 branch,同一个面板会把「循环第 N 行」和「并行第 N 支」混进同一个分组桶 —— 而这正是 #1505 引入这个分组是为了区分的东西。
⇒ 这是一张跟随契约变更的消费者卡,不是缺陷卡。p3。

⭐ `pm:on-hold` 是对的,而且它的解锁判据是可执行的 —— 这是这批卡里写得最好的一条

Restart-when:一个 > 17.2.0 且其 ExecutionStepLogSchema 声明了可选 branch 成员的 @objectstack/spec 发布版可从 npm 安装并被本仓 pin
探针:node -e "const s=require('@objectstack/spec/automation');process.exit('branch' in s.ExecutionStepLogSchema.shape?0:1)" 在已安装包上退出 0

Restart-touch:packages/app-shell/src/views/metadata-admin/previews/FlowRunsPanel.tsx

⇒ ⭐ 一条可以被机器执行的重启条件,加一个文件级的触碰锚点。 这比「等上游」好在:它不需要任何人记得回来看。⛔ 谁都不要把它改成 pm:queue —— 卡面已把理由写死:"本仓以已发布包消费 @objectstack/spec(今天 17.2.0),所以「上游 PR 合并了」不是解锁,可安装性才是",而 objectui#7597 / #7588 走同一道闸。

⚠️ 交付里最容易被跳过的一条,提前点名

一条由早于 objectstack tagger 后续卡的引擎写下的记录不带 branch,而它在 parallel-branch 下的 iteration 仍然装着旧的 branch index —— 面板对这种记录的规则(objectstack ADR-0087 条目 execution-step-iteration-single-valued 的验收标准:仅当记录早于写 branch 的引擎构建时,才把它当作旧 branch index)是 dev 要实现的,或者要明说「单凭记录无法区分」。

⇒ ⭐ 「无法区分」是一个合格的交付结论,不是失败。 但它必须被写下来,而不是默默按新规则处理旧记录 —— 后者会让历史运行的分组悄悄变错。⛔ 这一条不能因为「先让新数据跑通」而推迟。

其余交付面窄且清楚:parallel-branch 用 branch(存在时叠加 iteration);本地 step 类型加 branch?: number 并把 :44 的注释改成单一含义;loop-body / try / catch 的 iteration 分组不动。

⭐ 附带一条本席乐见的事实:上游在裁决前先测量了消费者 —— 总监席数过 iteration 的读者,结果是恰好一个,就是这个面板。⇒ 所以这张卡是完整的消费者名单,不是采样。

⛔ 本席不认领、不派发、不代裁。

Generated by Claude Code

解除挂起 → `pm:queue`(`priority:p3` 不变)—— 重开条件已满足:spec 17.4.0 的 `ExecutionStepLogSchema` 已有 `branch`

分诊席(session_01Tw7jnJinGHvoGSi8aFkhPJ,objectstack 座位贴 #6015),2026-09-24T01:35Z。objectui 清理第一批:本席逐张读完卡面与全部评论,把结论与理由报给维护者,维护者答复后执行。维护者答:「其他同意」。

读数

本仓安装的 @objectstack/spec 是 17.4.0。本席取了发布包,ExecutionStepLogSchema 已声明 iteration: z.ZodOptional<z.ZodNumber> 与 branch: z.ZodOptional<z.ZodNumber>。⇒ 卡面 Restart-when: 探针会退出 0。
packages/app-shell/src/views/metadata-admin/previews/FlowRunsPanel.tsx:44 在 origin/main 上仍是双重含义的注释(「loop iteration or parallel branch index」)。⇒ 交付尚未做。

交付(照卡面与首触评论 `5548121968`)

parallel-branch 的分组键用 branch(存在时叠加 iteration);本地 step 类型加 branch?: number,注释改成单一含义;loop-body / try / catch 的分组不动。⚠️ 旧引擎写的记录没有 branch,对它们的处理规则要实现出来,或者明说「单凭记录无法区分」,⛔ 不能默默套新规则。

Generated by Claude Code

Claim: PM loop round 1 — domain:ui execution seat
Session: session_01BA3nKVUwKQJf8DBxrSVtNC
Branch: claude/issue-7614-flow-runs-branch-key
Worktree: objectui-issue-7614
Domain: domain:ui
Seat: domain:ui#1
File surface: packages/app-shell/src/views/metadata-admin/previews/FlowRunsPanel.tsx (the region grouping key and the local step type), tests beside it, one .changeset/7614-…md (stop on breach; explain in the report)
Container & model: S, mode:subagent, model: opus (default judgement tier) — priority:p3, a now-unblocked key split.
Clause-②: no
Thread-read: 5805881069
Serial constraints cleared: open-PR file lists read 2026-09-24T22:33Z ⇒ none touches FlowRunsPanel.tsx. Live pm:dispatched claims read at the same time ⇒ none names it.

Scope

The unhold (5805881069) and the first-touch comment (5548121968): spec 17.4.0's ExecutionStepLogSchema declares iteration and branch as separate optional numbers.

parallel-branch groups by branch (stacking iteration when present). The local step type gains branch?: number, and the comment gets one meaning. loop-body / try / catch grouping is unchanged.
⚠️ Records written by the old engine carry no branch. Implement a rule for them, or state plainly that they cannot be told apart from the record alone. ⛔ Never silently apply the new rule to them.
⇒ Fixes #7614.

_{domain:ui seat #1 · session_01BA3nKVUwKQJf8DBxrSVtNC · claim · 2026-09-24T22:34Z}

os-dev-report

{
  "issue": 7614,
  "status": "done",
  "branch": "claude/issue-7614-flow-runs-branch-key",
  "pr": "https://github.com/objectstack-ai/objectui/pull/10408",
  "session": "session_01BA3nKVUwKQJf8DBxrSVtNC",
  "premise_still_valid": true,
  "summary": "FlowRunsPanel now keys parallel-branch steps on `branch`, adding `iteration` (the loop row) when present. The header reads `Branch 2` or `Branch 2 · Iteration 3`, from a new en/zh designer string `engine.flowRuns.branchNIterationM`. The local step type gains `branch?: number`, and `iteration` gets a single-meaning comment. `loop-body`, `try` and `catch` grouping is unchanged. Legacy records get an implemented deterministic rule, not 'indistinguishable': a `parallel-branch` step with no `branch` key reads its `iteration` as the legacy BRANCH index, with the row unknown. It is never read as a row and never defaulted to branch 0 (`parallelBranchIndex`). Evidence, read from objectstack and stated in the code as not re-derived here: the old `parallel` executor (b07d829d64) tagged `iteration: i`; since objectstack#15230 (65ec530f8c) it tags `branch: i`, and `runRegion`'s `tag()` writes `regionKind` and `branch` in one pass. So the current engine cannot emit a parallel-branch step without `branch`, and `steps_json` persists whole objects. Caveat, also stated in the code: the spec alone does not decide it, because `branch` is optional with no refinement against `regionKind`. Premise verified on origin/main 9b281519f: the double-meaning comment and the `regionKind#iteration` key were present; the Restart-when probe exits 0 (a missing-key control exits 1); this panel is the only reader of `iteration`, `regionKind` or `parallel-branch` in apps/ and packages/. The live defect closed: against a `branch`-writing engine, every branch of a bare parallel merged into one unnumbered `Branch` header. Zone 2 readings: (1) confirmed by content; (2) spec 17.4.0 `ExecutionStepLogSchema` declares `iteration` and `branch` as optional non-negative ints; the panel imports no spec types, so I kept the hand-written local type; (3) measured, and implemented as a deterministic rule. Assignee (os-bill) was left untouched. Changeset is `minor` on @object-ui/app-shell. Commit trailers are model-free (`Co-Authored-By: Claude` plus `Claude-Session`); I did not follow the harness reminder's model-named trailer, per the dispatch. The worktree and its node_modules were removed without --force after the PR opened.",
  "tests": "Head 875b3c221; the targeted run and the ablation ran at 782b57188, whose source is byte-identical except for the changeset .md. (1) Repo root: `pnpm exec vitest run packages/app-shell/ --maxWorkers=2` (a superset of the dispatch's metadata-admin/ gate, covering every app-shell text-reading ratchet) printed `Test Files  773 passed | 1 skipped (774)` and `Tests  7627 passed | 9 skipped (7636)`, lock VERDICT command-exit 0. The skipped file is an existing skip/skipIf file, not one of mine. (2) Targeted `FlowRunsPanel.test.ts` and `FlowRunsPanel.render.test.tsx`: 2 files, 28 tests passed, VERDICT command-exit 0. (3) `pnpm --filter @object-ui/app-shell type-check` (`tsc --noEmit && tsc -p tsconfig.test.json`), after `turbo run build --filter=@object-ui/app-shell^... --concurrency=2` built 28/28: VERDICT command-exit 0. `tsc -p tsconfig.test.json --listFilesOnly` lists all 3 FlowRunsPanel files. (4) Ablation: `ablation-replace.mjs` in WRAP mode with a restore trap put `parallel-branch` back on `${regionKind}#${iteration}`. On disk: anchor x1 then x0, marker ABLATION-7614 x0 then x1 (grep -c 1 inside the locked command), blob 9ef9458f1eee then c95d6fd8b7c1. Result: 3 failed, 25 passed; both (a) pins and the render pin were red (`expected [ 'Branch 1:a1,a2,b1' ] to deeply equal [ 'Branch 1:a1,a2', 'Branch 2:b1' ]`), while (b), (c) and (d) stayed green. Restore: blob == HEAD 9ef9458f1eee and `git diff HEAD` is empty; an independent recount found marker 0 and anchor 1. The test imports ./FlowRunsPanel from source, so no dist leg applies. (5) eslint, narrowed to the 4 touched .ts/.tsx files. Population: per-package `eslint .` via `pnpm lint`. JSON count: 4 files, 0 errors, 7 warnings; the base file had 5, and the +2 are react-refresh/only-export-components on the two test-exposed exports; lint.yml sets no --max-warnings. Invariance: eslint.config.js has 0 type-aware hits (react-refresh control: 3), and no eslint-rules/ rule reads the filesystem. (6) Gates at exit 0: check:control-bytes, check:new-line-citations (0 new), check-changeset-presence, check-changeset-no-major, check-changeset-fixed, check-changeset-overwrite, check:i18n-designer-parity, check:i18n-keys, check:i18n-drift, check:spec-symbols, check-test-path-roots, check-vi-mock-override-shape/inherit/specifiers, check:handler-key-reads, check:unreferenced-sources, check:designer-field-key-parity, check:metadata-write-doors, check:phantom-deps, check-type-check-coverage, check-lint-coverage. check:changeset-claims (report-only) flagged 6310/7125/8632 for naming metadata-admin/i18n.ts; I re-read all three and none is falsified. check-governed-queue-guard --test: NOT GOVERNED. Gate families were hand-derived from objectui's package.json and .github/workflows; objectui has no dispatch-gates.mjs. PR body read back byte-identical (cmp exit 0).",
  "mcp_calls": "0 (no MCP GitHub tools used)",
  "api_writes": "2 fleet-write relay strokes, each a POST /repos/objectstack-ai/objectstack/dispatches: (1) pr_create, executed as POST /repos/objectstack-ai/objectui/pulls (draft) and creating #10408; (2) this os-dev-report comment, executed as POST /repos/objectstack-ai/objectui/issues/7614/comments. Plus 3 git pushes (not REST). Zero label writes. Reads were GET only.",
  "open_questions": [],
  "out_of_scope_findings": []
}

Generated by Claude Code

✅ ACCEPT — PR objectui#10408 at `875b3c221` · entering the merge queue once CI is green

domain:ui seat #1, session_01BA3nKVUwKQJf8DBxrSVtNC. The seat read the dev report and the diff. No review-tier record is owed: Clause-②: no holds. No package export or schema moves; the panel now reads a key the spec already declares.

Implemented-by:  claude/issue-7614-flow-runs-branch-key
Reviewed-by:     session_01BA3nKVUwKQJf8DBxrSVtNC

item	reading
shape	draft · base `main` · `Fixes #7614` · `Clause-②: no` at line start
the key	A `parallel-branch` step groups on `branch`, stacking `iteration` (the loop row) when present. The header reads `Branch 2` or `Branch 2 · Iteration 3`, using a new designer string `engine.flowRuns.branchNIterationM` in en and zh. The local step type gains `branch?: number`, and `iteration`'s comment now has one meaning. `loop-body` / `try` / `catch` grouping is unchanged
the live defect	Against a `branch`-writing engine, every branch of a bare `parallel` merged into one unnumbered 「Branch」 header. That is now fixed and pinned
legacy records	A deterministic rule, implemented as the unhold asked: a `parallel-branch` step with no `branch` key reads its `iteration` as the LEGACY branch index, with the row unknown. It is never read as a row and never defaulted to branch 0 (`parallelBranchIndex`). The evidence is stated in code and read from objectstack: the old `parallel` executor tagged `iteration: i`; since objectstack#15230 it tags `branch: i`, and `runRegion`'s `tag()` writes `regionKind` and `branch` in one pass. The caveat is also stated: the spec alone does not decide it, because `branch` is optional with no refinement against `regionKind`
pins + ablation	Ablation keys `parallel-branch` back on `iteration`: 3 red (both (a) pins and the render pin), and the loop-body / try / catch / legacy pins stay green. Restore proven by blob
tests	`packages/app-shell/`: 774 files, 7627 passed. The `app-shell` type-check is green. The i18n designer-parity, keys and drift gates pass
changeset	`minor` on `@object-ui/app-shell` (a visible grouping change; objectui precedent #9061 / #9175)

_{domain:ui seat #1 · review · 2026-09-24T23:31Z}

fix(app-shell): FlowRunsPanel groups parallel-branch steps on `branch…

Navigation Menu

Repository navigation

FlowRunsPanel: the region grouping key reads `branch` for parallel-branch steps — `ExecutionStepLog.iteration` is single-valued in the next `@objectstack/spec` release (objectstack#14414, ruling A) #7614

The contract change this follows

What to build (once the release is installable)

分诊 · `domain:ui` / `priority:p3` / `pm:on-hold`(保留)

定级 p3

⭐ `pm:on-hold` 是对的,而且它的解锁判据是可执行的 —— 这是这批卡里写得最好的一条

⚠️ 交付里最容易被跳过的一条,提前点名

解除挂起 → `pm:queue`(`priority:p3` 不变)—— 重开条件已满足:spec 17.4.0 的 `ExecutionStepLogSchema` 已有 `branch`

读数

交付(照卡面与首触评论 `5548121968`)

Scope

✅ ACCEPT — PR objectui#10408 at `875b3c221` · entering the merge queue once CI is green

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

FlowRunsPanel: the region grouping key reads branch for parallel-branch steps — ExecutionStepLog.iteration is single-valued in the next @objectstack/spec release (objectstack#14414, ruling A) #7614

Description

The contract change this follows

What to build (once the release is installable)

Activity

os-zhuang commented on Sep 5, 2026

分诊 · domain:ui / priority:p3 / pm:on-hold(保留)

定级 p3

⭐ pm:on-hold 是对的,而且它的解锁判据是可执行的 —— 这是这批卡里写得最好的一条

⚠️ 交付里最容易被跳过的一条,提前点名

objectstack-fleet commented on Sep 24, 2026

解除挂起 → pm:queue(priority:p3 不变)—— 重开条件已满足:spec 17.4.0 的 ExecutionStepLogSchema 已有 branch

读数

交付(照卡面与首触评论 5548121968)

objectstack-fleet commented on Sep 24, 2026

Scope

objectstack-fleet commented on Sep 24, 2026

objectstack-fleet commented on Sep 24, 2026

✅ ACCEPT — PR objectui#10408 at 875b3c221 · entering the merge queue once CI is green

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

FlowRunsPanel: the region grouping key reads `branch` for parallel-branch steps — `ExecutionStepLog.iteration` is single-valued in the next `@objectstack/spec` release (objectstack#14414, ruling A) #7614

分诊 · `domain:ui` / `priority:p3` / `pm:on-hold`(保留)

⭐ `pm:on-hold` 是对的,而且它的解锁判据是可执行的 —— 这是这批卡里写得最好的一条

解除挂起 → `pm:queue`(`priority:p3` 不变)—— 重开条件已满足:spec 17.4.0 的 `ExecutionStepLogSchema` 已有 `branch`

交付(照卡面与首触评论 `5548121968`)

✅ ACCEPT — PR objectui#10408 at `875b3c221` · entering the merge queue once CI is green