docs(automation): un-stale the run summary line and narrow what failed=0 claims (#14456)

Contract review, three docs-only changes; no engine change.

- `flows.mdx` printed the summary line as literal log output and was left
  stale by this PR's own token: the run it shows now prints
  `skipped=30 failed=0 gate=…`, and the line sits directly above the table
  row documenting `failed`.
- Narrowed the reading of `failed=0` in three places — the doc's `failed`
  row, `formatRunSummaryLine`'s comment and the changeset — from "nothing
  failed" to what was measured: no node execution OF THIS RUN failed. A
  `subflow` child's contained failures stay on the child's summary rather
  than rolling up the way `acted` does. Cites #15617, where the
  declaration's two paragraphs are being reconciled.

`content/docs/releases/v17.mdx` carries the same line and is deliberately
NOT touched: release notes are a record of what that release printed, and
are never edited from a code PR.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XpTx2tbq3pZRYAdoGt6E6Y

Author: claude

.changeset/contained-failure-visibility.md

@@ -9,7 +9,7 @@ A contained per-iteration failure is now visible at run level, attributed to its
 Four changes populate the contract `@objectstack/spec` already declares:
 
 - **`FlowRunSummary.failed`** — `summarizeRun` now folds `failed = Σ nodes[].failures` over the per-node array it publishes, so the run-level count can never disagree with the breakdown it summarizes. It counts every node execution that failed, contained or fatal; on a run that completed, all of them were contained.
-- **`failed=N` on the run summary line** — `formatRunSummaryLine` prints the token whenever the count is present, `failed=0` included. That is the opposite of the `unmeasured` rule beside it and deliberate: `unmeasured` qualifies `acted`, while `failed` answers a question a completed run's line otherwise cannot be asked at all.
+- **`failed=N` on the run summary line** — `formatRunSummaryLine` prints the token whenever the count is present, `failed=0` included. That is the opposite of the `unmeasured` rule beside it and deliberate: `unmeasured` qualifies `acted`, while `failed` answers a question a completed run's line otherwise cannot be asked at all. Read `failed=0` precisely: **no node execution of this run failed**. It is the node fold and only that, so a `subflow` child's own contained failures stay on the child's summary rather than rolling up the way `acted` does — see #15617, where the declaration's two paragraphs are being reconciled.
 - **Iteration through `try_catch`** — a step that ran in a `try` or `catch` region inside a loop body now carries the enclosing loop's `iteration`, with `regionKind` still `try` / `catch`. The step says which region ran it *and* which row it ran for. `parallel` branch tagging is unchanged.
 - **`$error` binds the row** — the value bound to `errorVariable` (default `$error`) is the declared `TryCatchErrorValue`: `nodeId` and `message` as before, plus `iteration` and the loop's current `item` when the failure happened inside a loop body. A `subflow` / `map` child run has its own variable scope and therefore binds neither, so a parent's row identity never leaks into a child's `$error`.
 

content/docs/automation/flows.mdx

@@ -872,7 +872,7 @@ terminal run therefore carries a **summary** — on the `AutomationResult`, on t
 run in `listRuns` / `getRun`, and in the log:
 
 ```
-[automation] run flow=stalled_deal_sweep run=run_a1b2 status=completed durationMs=142 selected=30 acted=0 skipped=30 gate=check_stalled->send_nudge:30
+[automation] run flow=stalled_deal_sweep run=run_a1b2 status=completed durationMs=142 selected=30 acted=0 skipped=30 failed=0 gate=check_stalled->send_nudge:30
 ```
 
 | Field | Meaning |
@@ -881,7 +881,7 @@ run in `listRuns` / `getRun`, and in the log:
 | `acted` | Records **created / updated / deleted**, plus effects dispatched (notifications delivered) |
 | `skipped` | Node executions a **closed gate** prevented — one per loop iteration whose conditional edge evaluated false |
 | `unmeasured` | Executions that reached something the platform **cannot count** — see below |
-| `failed` | Node executions that **failed and were contained** — caught by a `try_catch` or routed down a `fault` edge — so the run went on; the sum of `nodes[].failures`. Absent on a run that did not track it, which is not zero |
+| `failed` | Node executions **of this run** that failed — on a completed run every one of them was contained, caught by a `try_catch` or routed down a `fault` edge, so the run went on; the sum of `nodes[].failures`. `failed=0` therefore reads "no node execution of this run failed", which is narrower than "nothing failed anywhere": a `subflow` child's own contained failures are counted on the CHILD's summary, not folded up here the way `acted` is (that inconsistency in the declaration is [#15617](https://github.com/objectstack-ai/objectstack/issues/15617)). Absent on a run that did not track it, which is not zero |
 | `nodes[]` | Per-node terminal status with `runs` / `failures` / `skipped` and its own selected/acted |
 | `gates[]` | Which gates closed and how often, most-skipped first |
 

packages/services/service-automation/src/run-summary.ts

@@ -199,10 +199,23 @@ export function formatRunSummaryLine(
     // `unmeasured` is a qualifier on `acted`: absent, the zero beside it is
     // trustworthy. `failed` answers a question the line otherwise cannot be
     // asked at all — a completed run says nothing about the rows it lost — so
-    // the token has to be there to be read, and `failed=0` is the reading
-    // "nothing failed" as against a line with no token at all, which is the
-    // older "not tracked". A run summarized by `summarizeRun` always carries
-    // it; only a summary persisted before this existed prints nothing here.
+    // the token has to be there to be read.
+    //
+    // What `failed=0` says, exactly: NO NODE EXECUTION OF THIS RUN FAILED.
+    // That is narrower than "nothing failed", and the difference is a
+    // `subflow`: the fold this prints is `Sigma nodes[].failures` over THIS
+    // run's own nodes, so a child run that CONTAINED failures of its own
+    // reports them on the child's summary and the parent still prints
+    // `failed=0` — measured, alongside the control where a child that FAILS
+    // rather than contains does reach the parent's count through the
+    // `subflow` node's own failure step. `acted` rolls a child's totals up
+    // and this does not; the declaration says both things in two paragraphs
+    // and is being reconciled in #15617. Until it is, this line is the node
+    // fold, and only that.
+    //
+    // A line with no token at all is a different reading again — the older
+    // "not tracked". A run summarized by `summarizeRun` always carries the
+    // count; only a summary persisted before this existed prints nothing here.
     if (summary.failed !== undefined) parts.push(`failed=${summary.failed}`);
     if (summary.unmeasured) parts.push(`unmeasured=${summary.unmeasured}`);
     const topGate = summary.gates[0];