Node-level error branches: let a flow handle a failed node instead of aborting the run

[os-zhuang]

Status: design placeholder / engine-level feature. Filed to capture the motivation, not scheduled.

Today

A node that returns { success: false } fails the entire run. AutomationEngine.execute catches it, writes the run-history row, and returns { success: false, error }. The only recovery available is flow-level errorHandling.strategy: 'retry', which re-runs the whole flow from the start — useless when the failure is deterministic (a bad filter, a validation rejection, a 4xx from an http node).

There is no way to say "if this node fails, take this other path."

Why it matters now

Guardrails that refuse to execute are the platform's main defense against silently-wrong data operations, and we keep (correctly) adding them:

• Flow node filters silently blank date macros: the template engine consumes {…} before the query engine sees it #3810 — a CRUD node refuses when interpolation erased a filter condition
• spec: formalize readonly write semantics — keep user-context strip, add design-time lint for flow writes to readonly fields (#2948 follow-up) #3425 — a readonly flow write is a certain no-op
• ADR-0049 / [P0][security] Flow runAs never switches execution identity #1888 — unscoped scheduled runs

Every one of them makes a node fail hard, and every one therefore aborts the run. That is the right default — a widened delete_record must not proceed — but it means the only available response to a guard is "the whole automation stops." The strictness debate on #3810 was really a debate about this: the objection was never "the guard is wrong," it was "aborting is expensive." An error branch decouples the two.

It also generalizes well past guards. A get_record that finds nothing, an http node that 404s, a connector_action that rate-limits — all are ordinary business conditions an author would like to route around, and today each one kills the run.

Sketch

An out-edge with an error semantic, resolved when the source node fails:

edges: [
  { source: 'fetch_account', target: 'use_account', label: 'ok' },
  { source: 'fetch_account', target: 'notify_admin', type: 'error' },
]

Open questions:

• Edge shape — a reserved label: 'error' or a first-class type: 'error'? type: 'back' (ADR-0044) is the existing precedent for an edge whose type changes traversal semantics, which argues for type.
• What the branch can read — the failing node's error message needs to land in a variable ({<nodeId>.error}) or the branch cannot act on it.
• Unhandled failures stay fatal. A node with no error edge must keep aborting the run. This is a strict opt-in, or it silently converts every existing guard into a swallowed error — the exact fail-open direction Flow node filters silently blank date macros: the template engine consumes {…} before the query engine sees it #3810 closed.
• Interaction with errorHandling.retry — does a handled node still count toward flow-level retry? Presumably not: the failure was handled.
• Cycle validation — an error edge looping back needs the same type: 'back' treatment approvals use, or registerFlow will reject legitimate retry-ish shapes.
• Run-history semantics — a run that took an error branch and completed: success with a warning on the step, or a distinct status? The Runs surface should not report a clean success with no trace of the failure (service-automation: runAs:'user' runs data ops with a credential-less user — trigger context never carries the actor's permission sets/positions (follow-up to #1888) #3356 / service-automation: update_record reports success when written fields are silently stripped — no observability for dropped writes (split from #3356) #3407 lesson).

Related

• Flow node filters silently blank date macros: the template engine consumes {…} before the query engine sees it #3810 — the guard whose cost motivated this
• Explicit syntax for a legitimately optional filter condition (design only — no implementation until a real request) #3862 — explicit optional filter conditions (the narrow fix for one case; this is the general one)
• ADR-0044 — type: 'back', the existing precedent for edge-type-driven traversal

[os-zhuang]

Decision: build this. Promoting from design placeholder to planned work.

Decided on platform direction rather than held for a user request. Sibling issue #3862 was closed as not planned in the same review — the two are not symmetric, and the contrast is the argument for this one.

Why this is a capability gap, not a nice-to-have

A node returning { success: false } kills the entire run. The only recovery is flow-level errorHandling.strategy: 'retry', which re-runs from the start — useless for a deterministic failure, and wrong for a transient one that only affects a single step.

That means ObjectStack cannot express the most ordinary sentence in business automation:

If the external API call fails, notify the owner and continue.

Every workflow engine we are compared against can. A record that a get_record does not find, an http node that 404s, a connector_action that rate-limits — these are normal business conditions, not faults, and today each one destroys the whole run. This is table stakes, and it is missing.

Why it matters more the more guards we add

The platform's main defense against silently-wrong data operations is the family of nodes that refuse to execute: #3810 (filter lost a condition), #3425 (readonly write is a certain no-op), ADR-0049/#1888 (unscoped scheduled run). We are going to keep adding them, because they work.

But each one makes "the guard fired" and "the automation stopped" the same event. That coupling is what the strictness debate on #3810 was actually about — the objection was never that the guard judged wrong, it was that aborting is expensive. This issue decouples them, which means we can keep tightening guards without the cost compounding.

Hard design constraint (new — this is the part that makes it safe)

A guard refusal must NOT be routable. Only genuine runtime errors are catchable.

Class	Example	Routable?
The world did not cooperate	http 404, no rows matched, connector rate-limited, timeout	yes
The metadata is wrong	filter lost a condition (#3810), readonly write (#3425), unscoped run (#1888)	no — stays fatal

Without this split, error branches become a strictly worse version of the $optional idea just rejected in #3862: an AI author attaches an error edge to every CRUD node and every guard on the platform is silently swallowed. With the split, the guards keep their absoluteness and error branches serve only what they should.

This is also why this issue survives the AI-authoring objection that killed #3862. An error branch forces the author to write the target node — it must state what happens instead, and the result is visible in the flow graph. That is an order of magnitude more work than adding a suppressing keyword, and it is reviewable. $optional was a silent one-token bypass; this is a drawn edge.

Scoped v1 (ship this, defer the rest)

• type: 'error' on an edge — follows the type: 'back' precedent (ADR-0044), where edge type already drives traversal semantics.
• The failing node's message lands in {<nodeId>.error} so the branch can act on it.
• Only runtime errors route. Guard refusals bypass error edges and stay fatal, per the table above. This needs a distinguishable failure class on the node result, not just a string.
• Unhandled failures stay fatal, unchanged. Strict opt-in.
• Run history must not report a clean success. A run that took an error branch and completed needs the failure visible on the step — the service-automation: runAs:'user' runs data ops with a credential-less user — trigger context never carries the actor's permission sets/positions (follow-up to #1888) #3356/service-automation: update_record reports success when written fields are silently stripped — no observability for dropped writes (split from #3356) #3407 lesson, where a silent 3ms success hid a write that never landed.

Deferred out of v1, tracked here:

• Interaction with errorHandling.retry (does a handled node still count toward flow-level retry? presumably not).
• Error edges that loop back — needs the same type: 'back' cycle treatment or registerFlow rejects legitimate retry shapes.
• Whether label: 'error' should be accepted as an alias (leaning no — one spelling).

Sequencing note

Landing this lowers the cost of every guard already shipped and every one we add next, so it should come before the next batch of refuse-to-execute guardrails rather than after.

---

Generated by Claude Code

[os-zhuang]

v1 landed in #3881 — with a correction to this issue's premise

This issue was filed to build node-level error branches. On opening the engine, they were already there and working: type: 'fault' is in the edge schema, executeNode routes both the thrown and returned failure paths to a handler, $error is populated, and there were tests. The feature was never the gap.

The gap was the hard constraint added when this was promoted — and it was live in main:

A guard refusal must NOT be routable. Only genuine runtime errors are catchable.

fault edges routed everything, guards included. Reproduced before fixing: a fault edge on a delete_record whose filter carries a typo ({record.ownr}) made #3810's protection against emptying the object disappear — the guard fired, the handler swallowed it, and the run reported success: true. One declared edge, and the platform's data-safety guarantee was off.

So the work was a containment fix, not a feature build. Shipped:

• NodeExecutionResult.errorClass — 'runtime' (default, so every existing executor keeps its routing) or 'guard'. Guard-class failures are never routed; they stay fatal with or without a fault edge and fail with the guard's own message.
• Thrown guards contained too. resolveNodeFilter returns its refusal, UnscopedRunDataAccessError throws one; both are covered via a shared guard-refusal module. Otherwise the catch path would have become the bypass the return path no longer was.
• {<nodeId>.error} alongside run-wide {$error}, so a handler shared by two fault edges can tell which node it is handling.
• Run history was already correct and is now pinned by a test: a run that recovers reports success, and the failed step keeps status: 'failure' with its message.
• Documentation — fault edges were entirely undocumented. Added to content/docs/automation/flows.mdx and the automation skill, including the routable/not-routable table and an explicit instruction not to add a fault edge to silence a guard error.

407 tests pass in service-automation with no regressions; the pre-existing fault-edge tests still pass, which is what defaulting to runtime is for.

Still open here

• Interaction with flow-level errorHandling.retry — does a handled node still count toward flow-level retry? (Presumably not.)
• Error edges that loop back — needs the ADR-0044 type: 'back' cycle treatment, or registerFlow rejects legitimate retry shapes.
• Whether label: 'error' should be an accepted alias (leaning no — one spelling).

Leaving this open for those three. The safety property and the v1 ergonomics are done.

---

Generated by Claude Code