fix(automation): close the default-routable footgun on refuse-to-execute guards (#3863)

[os-zhuang]

Why

#3881 stopped a fault edge from swallowing a guard refusal, keyed on NodeExecutionResult.errorClass. That field defaults to 'runtime' — the right call for compatibility, since every executor written before the split keeps its routing — but it leaves the footgun pointing the other way:

A new refuse-to-execute guard is routable unless its author remembers to classify it, and forgetting is silent.

Nothing in the type system catches that. The property #3881 secured can be un-secured by omission, which is the weakest possible way to hold a safety guarantee.

Auditing for it also turned up five guards that were already unmarked.

What changed

1. refuseNode(reason) — one act, not two

Writing a guard and marking it un-routable become the same call:

if (!url) return refuseNode('http: url is required');

Its doc states the test for using it — re-running unchanged can never succeed AND the fix is to edit metadata — and states the inverse just as plainly, because over-marking is not the safe direction: classifying a handleable condition as guard turns a recoverable integration into a dead run.

2. Five guards that were never marked

All are a missing required config key or a defective graph; none can succeed on a retry:

Guard	Why it is metadata, not the world
http with no url	required config key
subflow with no config.flowName	required config key
subflow past max nesting depth	a recursive graph nests exactly as deep next run
map with no config.flowName	required config key (the per-item subflow)
connector_action with no connectorId/actionId	required config keys

The seven crud-nodes guards from #3881 move to the helper — same behaviour, one spelling.

3. A behavioural inventory test

Every known guard is driven through the engine with a fault edge attached and asserted still fatal — matching on the refusal text, so a guard that starts failing for a different reason cannot pass vacuously.

Verified to have teeth: temporarily un-marking the http guard fails its row immediately (1 failed | 13 passed), then passes again once restored. A test that pins a safety property is worth little unless you have watched it fail.

The negative half is pinned in the same file — a plain node failure and a thrown error must still route, since that is what fault edges exist for.

Deliberately not marked

Judgment calls, recorded so they are not silently revisited:

• a degraded connector — feat(connector-mcp): declarative provider — non-fatal / lazy boot for unreachable MCP servers (ADR-0096 follow-up) #3017 states recovery is automatic, so it is transient by construction
• a collection that did not resolve to an array — data-dependent; the value can come from a prior node's output
• a collection over the iteration cap — a data-volume condition, not a defect
• a subflow that failed on its own — the child's failure is the child's business

Each is a condition the world caused, and an author must be able to handle it.

Considered and rejected

Making errorClass required on NodeExecutionResult would enforce classification at compile time — the genuinely airtight fix. Measured the blast radius: 281 non-test success: false sites across the repo (58 in automation) plus 82 in tests, and it would break third-party executors at compile time. That is a large, noisy change for a type-only gain over the helper, so it is out of scope here; if the executor surface is ever revised for other reasons, it is worth folding in then.

Verification

• packages/services/service-automation: 421 passed, no regressions (was 407 before this branch's 14 new tests).
• ESLint clean on all changed files; check-role-word gate OK.
• tsc --noEmit on the package: 2 errors, both pre-existing in engine.test.ts about resumeAuthority — unchanged from the base.

---

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:33pm

[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.