ADR 0026 - Wire Failure Taxonomy

Classifies Wire parse, admission, elaboration, runtime, executor, validation, provider, and Pulse infrastructure failures by owning layer and replay semantics.

On this page
  1. Status
  2. Context
  3. Decision
  4. Compile-Time Failures
  5. Runtime Deterministic Failures
  6. Retryable Executor Failures
  7. Pulse Operational Failures
  8. Alternatives considered
  9. Consequences
  10. Positive
  11. Negative
  12. Obligations
  13. Related

ADR 0026 - Wire Failure Taxonomy

Status

Proposed - defines the failure vocabulary needed by the next Wire elaborator, CLI diagnostics, and Pulse durable execution path.

Context

ADRs 0023 through 0027 introduce several distinct failure sites:

  • malformed Wire syntax;
  • missing, duplicate, or undeclared output equations;
  • unknown contracts or executor ids;
  • invalid configured executor values;
  • elaboration-time CorePure typed errors;
  • runtime CorePure typed errors;
  • executor input decode failures;
  • executor output validation failures;
  • provider and tool failures;
  • Pulse infrastructure crashes and resumes.

These failures should not collapse into one generic “execution failed” bucket. They belong to different layers, have different retry behavior, and mean different things for durable replay.

Decision

Wire should use a closed failure taxonomy. Each failure has an owning layer and replay class.

Failure kindOwning layerWhen raisedReplay class
ParseFailureParserLexing or grammar failureCompile-time
NameFailureStatic analysisUnbound name, duplicate binding, invalid scopeCompile-time
ProjectionFailureWire admissionUnknown contract, executor, port, or projection mismatchCompile-time
ConfigFailureWire admission / Capability projectionExecutor config cannot be statically elaborated or decodedCompile-time
TopologyFailureWire admissionMissing output equation, duplicate equation, invalid composition, invalid boundaryCompile-time
ElaborationPureFailureElaboratorStatically reducible CorePure expression failsCompile-time deterministic
RuntimePureFailurePure executorInput-dependent CorePure evaluation failsRuntime deterministic
ExecutorInputDecodeFailureHost bindingWire value cannot decode into executor input typeRuntime deterministic
ExecutorProviderFailureExecutor bindingProvider, tool, network, quota, or external service failureRuntime retryable by policy
ExecutorOutputValidationFailureExecutor binding / Wire runtimeExecutor output fails contract, schema, or payload-kind validationRuntime deterministic after retry policy
PulseInfrastructureFailurePulseProcess crash, storage interruption, worker lossOperational, resumable

Compile-time failures prevent a circuit from being admitted. Runtime deterministic failures are materialized as failed stage results and replay the same way given the same admitted circuit and materialized inputs. Retryable external failures may be retried according to executor policy before they become a durable executor failure. Pulse infrastructure failures are not Wire semantic failures; Pulse should resume or retry the interrupted attempt according to its durable protocol.

Compile-Time Failures

Parser, name, projection, config, topology, and elaboration-pure failures occur before runtime admission completes. They should be reported by the compiler or CLI with source spans whenever possible.

Elaboration-time CorePure failures are compile-time failures because ADR 0021 requires maximal static reduction. A statically known divide-by-zero, bad index, missing field, type mismatch, or budget exhaustion must not be deferred to runtime.

Runtime Deterministic Failures

Runtime CorePure failures, host input decode failures, and output validation failures are deterministic relative to the admitted circuit, materialized inputs, registered binding, and validation schema.

They may be surfaced as typed executor failures. Whether a graph routes those failures through an explicit error contract is a topology decision, not a change to the failure taxonomy.

Retryable Executor Failures

External model, tool, HTTP, artifact, and provider failures may be retryable. The executor binding owns retry policy and decides which provider failures are retryable.

For model-mediated outputs, a malformed structured response may be retried inside the executor policy only before a result is materialized. After retries are exhausted, the durable failure is an ExecutorOutputValidationFailure, not an untyped downstream payload.

Pulse Operational Failures

Pulse crashes, process exits, worker loss, and transient storage interruptions are operational failures. They should be recorded and resumed by Pulse, but they do not change the Wire program’s semantic result.

Alternatives considered

  • Use one generic executor failure. Rejected because compile diagnostics, retry policy, and replay semantics need finer distinctions.
  • Treat all runtime failures as retryable. Rejected because deterministic CorePure, decode, and schema failures will not become valid by retrying the same inputs.
  • Expose provider failures as Wire topology errors. Rejected because provider behavior belongs to executor binding and Pulse attempts, not source graph admission.

Consequences

Positive

  • CLI and editor diagnostics can name the layer that owns a failure.
  • Pulse can distinguish deterministic failed results from retryable attempts and operational interruption.
  • Executor authors get a stable vocabulary for decode, provider, and validation failures.
  • Tests can assert the exact phase in which a bad program fails.

Negative

  • The implementation needs structured error ADTs rather than free-form text.
  • Some existing tests that only check failure text need to assert failure kind.
  • Binding authors must classify provider failures instead of returning opaque exceptions.

Obligations

  • Define failure ADTs in Wire, Capability, and Pulse without circular dependencies.
  • Add parser, elaborator, pure evaluator, config, and binding tests for each failure kind.
  • Attach source spans to compile-time failures where possible.
  • Record runtime failure kind, retry class, and relevant schema/config hashes in Pulse events.
  • Keep operational Pulse failures separate from Wire semantic failures.