RFC: first-class on_error routing (brainstorm)

[PolyphonyRequiem]

RFC adding an engineering brief that proposes teaching conductor's routes: table about errors.

Read order: the TL;DR + thesis + top decisions + critical open questions at the top of the doc are the only parts that need eyes. Everything below the # Deep dives fold is the design at full depth — skim or skip.

What it proposes

A node raises a typed error envelope; outgoing routes match on either success or error; four route actions (to / retry / halt / propagate) cover the full control-flow surface; sub-workflow errors propagate by default; provider transport exhaustion surfaces as a routable kind.

``yaml
routes:

• to: next_node # success path (unchanged)
• on_error: external.git.drift
  retry: { max: 5, backoff: exponential, initial_seconds: 2 }
• on_error: external.git.drift
  to: drift_recovery_gate # post-exhaustion fallback
• on_error: provider.exhausted
  halt: { message: "model down: {{ error.message }}" }
• on_error: "*"
  propagate: true # uncaught -> parent workflow
  ``

Why

Polyphony has ~40 human_gate nodes across its 15 workflows whose sole purpose is to absorb script-level failures ({success: false} lands here, human picks retry / skip / abort). They exist because conductor has no other primitive that can catch a node-level failure. With this brief shipped, most of those collapse to one or two route lines on the failing node.

What's in this PR

Just the brainstorm doc — docs/projects/error-routing/on-error-routing.brainstorm.md. No schema changes, no code.

What I'd like back

Not a yes/no on the whole thing. Specifically:

1. A read on the three critical open questions flagged at the top of the brief (post-retry-exhaustion semantics, route-actions vs. smaller alternative, reserved-kind namespace).
2. A read on the thesis: is "routes table as universal control flow" the right north star for conductor, or am I projecting?
3. If yes-in-principle, your preference on phasing.

Submitted from polyphony's architecture/rationalization track (AB#3257, parent epic AB#3253).

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (main@efa520f). Learn more about missing BASE report.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #227   +/-   ##
=======================================
  Coverage        ?   88.26%           
=======================================
  Files           ?       60           
  Lines           ?     9667           
  Branches        ?        0           
=======================================
  Hits            ?     8533           
  Misses          ?     1134           
  Partials        ?        0           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[PolyphonyRequiem]

Pushed a substantive update to D1 (the script-side error contract). Top-level shape is unchanged; the change is about engine reach.

What changed and why

A reviewer (Daniel) pushed back: conductor's script executor is engine-agnostic (asyncio.create_subprocess_exec, no language assumptions), and the original draft leaned on a pwsh Write-ConductorError cmdlet as the headline ergonomic surface. That was an accident of the polyphony codebase being pwsh-heavy, not a design choice — and it pushed the cost of adoption onto every other engine.

The fix is to make the contract language-neutral, with prior art:

• Contract: conductor sets \ to a temp-file path; the script writes the envelope JSON to that path and exits 0. Three lines in pwsh, bash, python, node, or dotnet (side-by-side examples in D1.2).
• Prior art: GitHub Actions explicitly migrated from stdout sentinels (::set-output::) to env-var-files (\, \, \) for these exact reasons (stdout pollution, parser fragility, security). We're walking the same path. Cross-platform behavior is proven at scale.
• Helpers ship as sugar, not as the contract. helpers/error/ directory with one file per common engine, all optional. The contract is what you can implement in 60 seconds from the spec.

Also in this push

• D1.6 'Where do kinds come from?' — an authorship table making it explicit that conductor never infers kinds from exit codes or stderr patterns. Without intentional authorship at the failure site, all you can know is internal.script_error.
• D1.7 optional raises: [kind] declaration on nodes — opt-in self-doc that powers a lint pass (validator can flag on_error: x.z against a node that declares raises: [x.y]) and a runtime undeclared-kind check (kinds raised but not declared become internal.undeclared_kind). Strictly optional; existing nodes need no change.
• D1.8 wrapping third-party CLIs — concrete bash and pwsh examples of translating git fetch / npm install exit codes into typed envelopes at the workflow author's boundary.
• New non-goal: no inference of kinds from runtime signals.
• Touch points updated: tempfile.mkstemp(delete=False) for the path so Windows file-locking doesn't bite; conductor reads only after subprocess exit so no read/write overlap.
• Phase 1 acceptance criteria expanded: cross-engine tests (pwsh-on-Windows, bash-on-Linux, python on both); raises: lint and runtime checks.

Net effect: the contract is now provably the simplest thing that could work for any script engine, the prior art is named, and the ergonomic helpers are positioned correctly (optional, not load-bearing).

Commit: 02eace8