Skip to content

Commit 28c1107

Browse files
committed
docs(flows): drop self-reference, name the repair verb an operator can call
PM review on PR #20377: remove the two sentences that talk about the page's own prose ("that sentence is scoped to..." / "the claim above does not hold for it") and state the scoping as behaviour instead. Name the third case's repair verb the same way the other two cases do -- the `restore-suspension` REST verb (routed to `restoreConsumedSuspension` at packages/runtime/src/domains/automation.ts:2752), issued on the parent's run id, the one `resumeFailure` names -- rather than only the engine method name.
1 parent d008938 commit 28c1107

1 file changed

Lines changed: 20 additions & 20 deletions

File tree

‎content/docs/automation/flows.mdx‎

Lines changed: 20 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1102,30 +1102,30 @@ the chain resolves from either end:
11021102
parked on an `approval`, resuming the parent is refused too.
11031103

11041104
A child that fails terminally after the pause fails every waiting ancestor, so
1105-
no run is stranded as resumable-forever — that sentence is scoped to exactly
1106-
this case, not the two below it. **When the child's failure is a strand** —
1107-
its resume consumed the pause and a downstream node threw — each ancestor's
1108-
consumed pause is recorded too, and the repair verb puts the whole chain back
1109-
in one call: `POST …/runs/{runId}/restore-suspension` on **any** member
1110-
re-arms every member, deepest first, so the continuation re-issued on the run
1111-
you named flows back up through the ancestors instead of completing a leaf
1112-
into a parent that never continues. Re-arming an ancestor is all the verb does
1113-
in this case — no ancestor is stranded here, because resuming it is not what
1114-
moves it. A cascade from a child that is **not** repairable records no
1115-
ancestor snapshot, deliberately, so the verb never promises a chain repair it
1116-
could not finish.
1105+
none of them is left stranded as resumable-forever. **When the child's failure
1106+
is a strand** — its resume consumed the pause and a downstream node threw —
1107+
each ancestor's consumed pause is recorded too, and the repair verb puts the
1108+
whole chain back in one call: `POST …/runs/{runId}/restore-suspension` on
1109+
**any** member re-arms every member, deepest first, so the continuation
1110+
re-issued on the run you named flows back up through the ancestors instead of
1111+
completing a leaf into a parent that never continues. Re-arming an ancestor is
1112+
all the verb does in this case — no ancestor is stranded here, because
1113+
resuming it is not what moves it. A cascade from a child that is **not**
1114+
repairable records no ancestor snapshot, deliberately, so the verb never
1115+
promises a chain repair it could not finish.
11171116

11181117
**A third case is the opposite: the bubble itself is what strands an
11191118
ancestor.** The child completes cleanly, `bubbleToParent` resumes the parent
11201119
on the child's behalf, and the parent's own downstream node throws. There the
1121-
bubble — not a resume the caller issued — is exactly what moves the parent, so
1122-
the claim above does not hold for it: the parent lands on the engine's
1123-
`'stranded'` exit, terminal, and repairable only by an operator's
1124-
`restoreConsumedSuspension`. The child's own resume genuinely succeeded, so its
1125-
resumer (an approvals decision door, a wait timer) is told the resume
1126-
succeeded; as of #15556 an approval `decide()` also reports the stranded
1127-
parent on `resumeFailure` (`{ code: 'RESUME_FAILED', runId: '<parent>',
1128-
status: 'stranded', repairable: true }`).
1120+
bubble — not a resume the caller issued — is exactly what moves the parent,
1121+
and it is the parent, not the child, that lands on the engine's `'stranded'`
1122+
exit, terminal. The child's own resume genuinely succeeded, so its resumer
1123+
(an approvals decision door, a wait timer) is told the resume succeeded; as
1124+
of #15556 an approval `decide()` also reports the stranded parent on
1125+
`resumeFailure` (`{ code: 'RESUME_FAILED', runId: '<parent>', status:
1126+
'stranded', repairable: true }`). Repair it the same way: the same
1127+
`restore-suspension` verb (`restoreConsumedSuspension` underneath), issued on
1128+
the parent's run id — the `runId` `resumeFailure` names, not the child's.
11291129

11301130
See the worked example pair in the showcase app:
11311131
`showcase_project_closure` invokes the reusable `showcase_closure_signoff`

0 commit comments

Comments
 (0)