fix(automation): a fault edge must not switch off a guardrail (#3863)

[os-zhuang]

What this turned out to be

#3863 was filed to build node-level error branches. On opening the engine, they already exist and work: type: 'fault' is in the edge schema, executeNode routes both the thrown and the returned failure paths to the handler, $error is populated, and there are tests. So the feature was not the gap.

The gap was that it routed everything — including guard refusals. That is the fail-open hole flagged as the hard design constraint when the issue was promoted, and it is live in main today.

The bug, reproduced before fixing

Attach a fault edge to a delete_record whose filter has a typo:

{ id: 'op', type: 'delete_record',
  config: { objectName: 'deal', filter: { owner: '{record.ownr}' } } },   // typo
{ id: 'e_fault', source: 'op', target: 'handler', type: 'fault' },

{record.ownr} does not resolve, so the only condition is erased and the filter would collapse to {} — every row. #3810's guard correctly refuses the node. The fault edge then swallowed the refusal, ran the handler, and the run reported success: true.

One declared edge silently disabled the platform's protection against emptying an object. That is precisely the fail-open direction #3810 was opened to close, and it is the first thing an AI authoring loop reaches for when trying to make a diagnostic go away — the same suppression dynamic that got the $optional proposal (#3862) closed as not planned.

The test asserting this lands in the tree failing, then passes with the fix.

The fix: failures carry a class

NodeExecutionResult.errorClass — 'runtime' (default) or 'guard'.

Class	Examples	Routable by a fault edge
runtime	http 404, connector rate-limit, data engine rejected a write	yes
guard	filter lost a condition (#3810), data node names no object, run would execute unscoped (ADR-0049/#1888)	no — stays fatal

Defaulting to runtime means every existing executor keeps its current routing; this is not a behaviour change for anything except the guards.

Thrown guards are covered too. resolveNodeFilter returns its refusal; UnscopedRunDataAccessError throws one. Both paths are contained, via a shared guard-refusal module (its own file because engine.ts already imports runtime-identity.ts, so the guard cannot import the engine back). Otherwise the catch path would simply become the bypass the return path no longer is.

Marked guard-class: the three resolveNodeFilter refusals, the four objectName required refusals, and UnscopedRunDataAccessError. Genuine engine failures (get_record(x) failed: …) stay runtime-class and keep routing.

Also in scope (the rest of the issue's v1)

• {<nodeId>.error} now carries a failed node's message alongside run-wide {$error}. $error names only the most recent failure, so a handler shared by two fault edges could not tell which node it was handling; {charge_card.error} is addressable from any downstream template. Purely additive — $error is unchanged.
• Run history: already correct. A run taking a fault branch reports success, and the failed step keeps status: 'failure' with its message — verified with a test, since 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 is that recovery must not erase the record.
• Documentation: fault edges were undocumented. Added to content/docs/automation/flows.mdx and the automation skill, including the routable/not-routable table. The skill says plainly not to add a fault edge to silence a guard error — that is the misuse the class split now makes impossible, and the skill is what an AI author reads.

Verification

• New fault-edge-guard-containment.test.ts — 6 tests: guard refusal contained with a fault edge present; runtime failure on the same shape still routes; thrown ADR-0049 guard also contained; guard fatal without a fault edge; {<nodeId>.error} published; failed step still traced after recovery.
• packages/services/service-automation full suite: 407 passed, no regressions — the pre-existing fault-edge tests still pass, which is the point of defaulting to runtime.
• ESLint clean on all changed files; check-role-word gate OK.
• tsc --noEmit on the package reports 2 errors, both in engine.test.ts about resumeAuthority — confirmed pre-existing by stashing this branch's changes and re-running on the base.

Deferred (still tracked on #3863)

Interaction with flow-level errorHandling.retry; error edges that loop back (needs the ADR-0044 type: 'back' cycle treatment); whether label: 'error' should be an accepted alias.

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Jul 28, 2026 2:06pm

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): packages/services.

6 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/automation/webhooks.mdx (via packages/services)
• content/docs/kernel/runtime-services/audit-service.mdx (via packages/services)
• content/docs/kernel/runtime-services/index.mdx (via packages/services)
• content/docs/kernel/runtime-services/settings-service.mdx (via packages/services)
• content/docs/plugins/packages.mdx (via packages/services)
• content/docs/protocol/kernel/i18n-standard.mdx (via packages/services)

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.