Spec gap: bridge operator error handling is undefined (missing graph, execution failure) #18

New issue

Open

opened 2026-05-27 05:26:41 +00:00 by hurui200320 · 0 comments

hurui200320 commented

2026-05-27 05:26:41 +00:00

Member

Problem

§5.3.2 defines four bridge operators (graph_execute, state_update, state_checkpoint, graph_node) that each reference a named graph route. However, no error semantics are defined for failure cases:

Named graph does not exist: What happens if params.graph names a route that does not exist in the routes section? Is this caught at validation time (§11) or only at runtime?
Graph execution fails: If graph_execute invokes a graph that throws an ExecutionError, how is this surfaced to the stream? Is the message forwarded to __error__? Is a timeout message emitted?
State update on non-existent graph: If state_update or state_checkpoint references a graph that hasn't been executed yet, is there state to update?

In contrast, the agent mapper in §5.3.4 has detailed error handling rules: timeout messages with metadata.timeout: true, error messages with metadata.error: true, and specific content strings. Bridge operators have no equivalent specification.

Fix Needed

Add an error handling subsection to §5.3.2 (or a dedicated §5.3.x) for bridge operators, covering:

Whether missing graph names are a validation error or runtime error
The message emitted on graph execution failure (content, metadata fields)
The behavior of state_update / state_checkpoint when no prior graph execution exists

References

§5.3.2 — Bridge Operators (graph_execute, state_update, state_checkpoint, graph_node)
§5.3.4 — Agent Mappers (provides the error handling model to follow)
§11.3 — Route Validation (should mention bridge operator graph references)

## Problem §5.3.2 defines four bridge operators (`graph_execute`, `state_update`, `state_checkpoint`, `graph_node`) that each reference a named graph route. However, no error semantics are defined for failure cases: 1. **Named graph does not exist**: What happens if `params.graph` names a route that does not exist in the `routes` section? Is this caught at validation time (§11) or only at runtime? 2. **Graph execution fails**: If `graph_execute` invokes a graph that throws an `ExecutionError`, how is this surfaced to the stream? Is the message forwarded to `__error__`? Is a timeout message emitted? 3. **State update on non-existent graph**: If `state_update` or `state_checkpoint` references a graph that hasn't been executed yet, is there state to update? In contrast, the agent mapper in §5.3.4 has detailed error handling rules: timeout messages with `metadata.timeout: true`, error messages with `metadata.error: true`, and specific content strings. Bridge operators have no equivalent specification. ## Fix Needed Add an error handling subsection to §5.3.2 (or a dedicated §5.3.x) for bridge operators, covering: 1. Whether missing graph names are a validation error or runtime error 2. The message emitted on graph execution failure (content, metadata fields) 3. The behavior of `state_update` / `state_checkpoint` when no prior graph execution exists ## References - §5.3.2 — Bridge Operators (`graph_execute`, `state_update`, `state_checkpoint`, `graph_node`) - §5.3.4 — Agent Mappers (provides the error handling model to follow) - §11.3 — Route Validation (should mention bridge operator graph references)

Rows
Columns