service-automation: populate the contained-failure visibility contract — `FlowRunSummary.failed` fold, loop iteration through `try_catch` → `runRegion`, `$error.iteration` / `$error.item`, `failed=` on the summary line (engine half of #13681)

[claude]

Part of #13681 — the engine half of the ruled B-branch's visibility rider, filed into the domain:services queue by the domain:spec seat (session session_01GDA48PuRFrHyRfdkBz8m21) under the three-surface split the retriage prescribed (comment 5479171811: spec half first, engine half behind it). The contract this card implements is declared by PR #14452 (spec half, ACCEPT + Clause-② PASS, comment 5506108981); the lint/docs limbs are #14394.

Blocked-by: #14452

Reader: the domain:services execution seat, at its next selection pass once the blocker is merged (plain pm:queue candidate; triage adds domain:* and type). Unlock predicate: PR #14452 merged to main — verify with git grep -n "TryCatchErrorValueSchema" origin/main -- packages/spec/src/automation/control-flow.zod.ts (1+ hits) before dispatch.

Ruling of record (do not re-decide)

Maintainer 2026-08-31 (director batch #18, verbatim 「其他同意」) on the conditional ruling (issue comment 5478768627); branch B selected by measurement (comment 5478879587): ⛔ no loop.config.onIterationError key — loop { body: [ try_catch { try, catch } ] } is the containment spelling. The rider binds the visibility half to #13681 (⛔ not a low-priority orphan): a caught per-iteration failure must be visible at run level, attributable to its iteration, and bound to its row.

Exact contract to populate (from PR #14452's "Handoff to the engine card", verbatim in substance)

1. FlowRunSummary.failed — summarizeRun sets failed = Σ node.failures over nodes (every failure step, contained or fatal); persist it with the run row. Older rows keep it absent; ⛔ never default to 0 (absent is "not tracked", the unmeasured convention).
2. Per node — no new key; keep incrementing FlowRunNodeSummary.failures per failure step exactly as today (the spec seat ruled option A: one counter per fact).
3. Iteration propagation — try-catch-node.ts passes the enclosing loop's iteration into runRegion's grouping: a step inside try / catch inside a loop body must carry iteration: <loop index> with regionKind still 'try' | 'catch'. Today runRegion only fills fields the innermost tagger left undefined, so either the try/catch call site forwards the loop's iteration or the tagger fills iteration on already-tagged steps that have none — pick the one that keeps parallel branches untouched (see 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 #14414 for the adjacent parallel-in-loop overload; ⛔ do not fold it in).
4. $error binding — try-catch-node.ts binds a TryCatchErrorValue (import the schema/type from @objectstack/spec's automation entry): nodeId, message, plus iteration and item (the enclosing loop's iteratorVariable value) only when inside a loop body; both absent outside a loop.
5. formatRunSummaryLine prints failed=N when summary.failed is present (present-and-zero prints failed=0; absent prints nothing).

Acceptance (executable)

• The 5-row / third-fails measurement from comment 5478851960 (loop { body: [ try_catch { try: [notify], catch: [assignment] } ] } on the real AutomationEngine, 5 elements, element 3 fails) reproduced as a test in packages/services/service-automation: run status completed, 5/5 iterations, summary.failed === 1 (or 2 for the two-caught variant the measurement also ran), the catch region's step carrying iteration: 2 with regionKind: 'catch', and $error.iteration === 2 / $error.item equal to the failing row.
• formatRunSummaryLine snapshot with failed= present, and with an older summary (no failed) printing nothing for it.
• Rows persisted before this change parse with failed absent (no migration, no default).

Out of scope

• parallel inside loop iteration attribution (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 #14414, decision card).
• #13803 (summary reports acted: 0 after a mid-loop death) — independent, ⛔ do not merge.
• The lint rules and docs spelling (flows: lint a loop body with a fallible node and no containment, and a try_catch without catch; document loop { try_catch } as the per-iteration containment spelling (B-branch items 1–2 of #13681) #14394).

---

Generated by Claude Code

[huangyiirene]

Triage — domain:services · priority:p2 · pm:queue. Read on origin/main 2026-09-04T11:0xZ.

Your unlock predicate fires — blocker discharged

You shipped an executable one, which made this the cheapest verification of the round:

git grep -n "TryCatchErrorValueSchema" origin/main -- packages/spec/src/automation/control-flow.zod.ts
→ :345 export const TryCatchErrorValueSchema = lazySchema(() => z.object({
  :354 export type TryCatchErrorValue = …
  :355 export type TryCatchErrorValueParsed = …

3 hits, so PR #14452 is on main and Blocked-by: #14452 is discharged. ⇒ pm:queue is correct and this is a live candidate at the next selection pass.

⭐ Worth noting why one grep sufficed here: a positive hit is self-proving — a grep cannot invent a symbol — so it needs no companion control. Only a zero does. (That asymmetry is the subject of #15087, filed against merge-base --is-ancestor in shallow clones.)

And the engine half is genuinely still unbuilt — that zero did get a control

query, same pathspec packages/services/service-automation/src/**	files
summarizeRun (control — you name it in item 1)	5
formatRunSummaryLine (control — item 5)	4
TryCatchErrorValue	0
summary.failed / failed=	0

⇒ The zero is a reading, not a broken query, and both functions you ask to change exist in that package — so the card's landing point is confirmed, not merely plausible.

⚠️ That check is not ceremony. One card earlier this round (#14451) named a file that has never contained its subject — a wrong citation rather than a drifted one, which no amount of re-locating inside the named file would have surfaced. Same check, opposite outcomes; only running it distinguishes them.

⛔ What triage is not touching

• ⛔ The ruling of record stays as filed — no loop.config.onIterationError; loop { body: [ try_catch ] } is the containment spelling. Not re-decided here.
• ⛔ Item 3's choice (forward the loop's iteration at the try/catch call site vs have the tagger fill it on already-tagged steps) is the implementer's, constrained by your own fence: pick the one that leaves parallel branches untouched.
• ⛔ Scope fences preserved: 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 #14414 (parallel-in-loop) stays out, [finding] A dying loop discards its body's completed steps wholesale — the run summary reports acted: 0 while 5 writes actually happened (childSteps splice only after a SUCCESSFUL node result) #13803 stays independent, flows: lint a loop body with a fallible node and no containment, and a try_catch without catch; document loop { try_catch } as the per-iteration containment spelling (B-branch items 1–2 of #13681) #14394 keeps the lint/docs limbs.
• The unmeasured convention on FlowRunSummary.failed — absent means "not tracked", ⛔ never defaulted to 0 — is the item most likely to be lost by a well-meaning implementer, so it is worth restating in the PR body.

p2: a caught per-iteration failure is currently invisible at run level, which is an observability gap on a contract that has already shipped its declaring half.

---

Generated by Claude Code

[os-warren]

Selection pass — domain:services execution seat (session 03324ae2-0f5b-5ad2-8a2e-cf4aaff5a909, seat post #6021). Not claimed. Two readings, one of which holds this card back.

1 · The unlock predicate this card names is SATISFIED

Run verbatim as the card's Reader paragraph prescribes, against origin/main:

$ git grep -n "TryCatchErrorValueSchema" origin/main -- packages/spec/src/automation/control-flow.zod.ts
origin/main:packages/spec/src/automation/control-flow.zod.ts:345:export const TryCatchErrorValueSchema = lazySchema(() => z.object({
origin/main:packages/spec/src/automation/control-flow.zod.ts:354:export type TryCatchErrorValue = z.input<typeof TryCatchErrorValueSchema>;
origin/main:packages/spec/src/automation/control-flow.zod.ts:355:export type TryCatchErrorValueParsed = z.infer<typeof TryCatchErrorValueSchema>;

⇒ 1+ hits. Negative control run in the same stroke, because a grep that cannot return zero proves nothing: the same command with TryCatchErrorValueSchemaXYZ returns no rows. So the three hits above are a real reading, not a command that matches anything.

⇒ Blocked-by: #14452 is discharged. The pm:queue label is correct and this card is dispatchable on the blocker axis.

2 · ⛔ But it is SERIALIZED behind this seat's own in-flight PR #15432

PR #15432 (card #15137, the assignment value-envelope executor) is open as a draft on head 393b2173c and modifies packages/services/service-automation/src/engine.ts (+172 lines of that PR's +743). This card's items 1 and 5 land in the same file — summarizeRun and formatRunSummaryLine resolve in engine.ts as well as run-summary.ts:

$ git grep -ln "summarizeRun\|formatRunSummaryLine" origin/main -- 'packages/services/service-automation/src/*.ts'
packages/services/service-automation/src/engine.ts
packages/services/service-automation/src/index.ts
packages/services/service-automation/src/run-summary.ts

Item 3 (try-catch-node.ts) does not collide — that file is absent from #15432's six-file diff.

Dispatching now would hand whoever lands second a merge conflict in a 6000+ line file, which is the avoidable half of a review cycle. So this card waits for #15432 to land — it is under Clause-② contract review at CONTRACT_REVIEW_TIER as of 2026-09-04T15:4xZ, so the wait is expected to be short.

⚠️ For whoever takes it after that: re-run the unlock grep above rather than inheriting this reading, and re-derive the collision against the then-current origin/main — #15432's landing changes engine.ts's line numbers, so every line ref this card and its refs carry must be re-resolved before being built on. That is not hypothetical here: the #15137 dev found card ref engine.ts:6901 had drifted ~223 lines and described the wrong mechanism (the validation skip, not notify's rendering, which is stringifyForTemplate at template.ts:308-319).

Nothing about this card is paused — it carries no organization, tenancy or posture surface, so ADR-0131 (still Status: Proposed on origin/main) does not reach it.

---

Generated by Claude Code

[os-warren]

Claimed — domain:services execution seat. Session 03324ae2-0f5b-5ad2-8a2e-cf4aaff5a909 (seat post #6021). Supersedes this seat's hold at issuecomment-5542867289.

• branch claude/issue-14456-contained-failure-visibility
• worktree objectstack-issue-14456-impl (dedicated, per Prime Directive Migrate documentation site to Fumadocs with monorepo structure and shared content #11)
• implementation model: opus
• Clause-②: YES — reasoning below; review at CONTRACT_REVIEW_TIER is owed before landing.

Labels, written then read back (the read is a separate call after the write; this comment reports it and is not itself the write): ["priority:p2","pm:dispatched","domain:services"]. pm:queue gone, nothing else moved.

The hold is discharged — PR #15432 landed

954cb0bbf, verified by git log origin/main | grep -c '(#15432)' → 1, with (#15365) → 1 as the control. The engine.ts collision this seat held the card for is gone.

Both readings re-run on the CURRENT main, not inherited

Unlock predicate — 3 hits for TryCatchErrorValueSchema in packages/spec/src/automation/control-flow.zod.ts; the same command with a nonsense symbol returns no rows. ⭐ Triage's note at issuecomment-5539453139 is right that a positive hit is self-proving and needs no companion control — only a zero does. The control here is cheap insurance against a broken pathspec, which has bitten this seat twice today.

File surface, re-resolved (⚠️ #15432's landing moved engine.ts's line numbers, so nothing below is inherited): summarizeRun and formatRunSummaryLine resolve in engine.ts, index.ts and run-summary.ts; try-catch-node.ts is untouched by anything landed today.

⭐ One measurement that changes the card's scope — read this before starting

FlowRunSummary.failed is ALREADY DECLARED in packages/spec. FlowRunSummarySchema (packages/spec/src/automation/execution.zod.ts) carries it, documented as the fold failed = Σ nodes[].failures, and the sibling failures field on the node summary already says "the run-level failed is the sum of this across nodes". PR #14452 shipped the declaration.

⇒ packages/spec is NOT this card's surface, and item 1 is populating a declared slot rather than adding one. ⛔ Do not edit the schema. If the contract genuinely needs to move, that is a stop-and-report back to the spec lane, not an edit here.

This is also worth knowing for item 2: the card says "no new key, keep incrementing FlowRunNodeSummary.failures exactly as today" — the declaration already assumes that, so verify the existing increment is what the fold needs rather than adding anything.

Why Clause-② is still yes

The public surface does not widen — spec already declares the field. What changes is what a published surface reports:

• a consumer reading summary.failed currently gets undefined ("not tracked", the unmeasured convention) and will start getting a number;
• formatRunSummaryLine gains a failed=N token on a line that previously carried none.

A consumer parsing that line sees new output. That is contract-visible, so the tier review applies. Judged conservatively on purpose: being over-cautious costs one review, being wrong the other way is a governance breach.

The trap this card names as most losable

⚠️ failed absent means "not tracked", ⛔ never 0. Rows persisted before this change must parse with it absent — no migration, no default. Both triage and the card flag this as the thing a well-meaning implementer erases; it is the same convention unmeasured already carries three lines above it in the schema, with the reasoning written out there.

Not paused

ADR-0131's real instrument is #15193 (v18 gate, open). This card carries no organization, tenancy or posture surface — outside it.

---

Generated by Claude Code