langgraph: make is_control_flow_signal public#12
Merged
Conversation
A host instrumenting its own LangGraph nodes has to separate a node that parked on a control-flow signal from one that crashed. Get it wrong and you sign a false failure — a record claiming a node failed when it merely stopped at a human gate and will re-execute and succeed. This library treats that as exactly as dishonest as a false success, so the predicate is load-bearing for record honesty, not a convenience. It shipped underscored and out of __all__, which left a host two options: import a private name, or restate the boundary itself. bosun imports the private name (core/audit.py) and was right to — a hand-rolled isinstance(exc, (GraphInterrupt, ParentCommand)) misses GraphDrained today, and would drift silently the next time the runtime widens the boundary. The predicate delegates to GraphBubbleUp instead, so it cannot drift. The only thing wrong with it was the underscore. The underscore name stays as an alias. Hosts importing it pin >=0.2,<0.3, and removing it inside that range would break their resolve. Drop it in 0.3. The guard enumerates GraphBubbleUp's subclasses from the runtime's class tree rather than listing them, since a list in the test would be the same brittle restatement the predicate exists to avoid.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
A host instrumenting its own LangGraph nodes has to separate a node that parked on a control-flow signal from one that crashed. Get it wrong and you sign a false failure — a record claiming a node failed when it merely stopped at a human gate and will re-execute and succeed. This library treats that as exactly as dishonest as a false success, so the predicate is load-bearing for record honesty, not a convenience.
It shipped underscore-prefixed and out of
__all__, which left a host two options: import a private name, or restate the boundary itself.The private import was the right call
bosun imports
_is_control_flow_signal(src/bosun/core/audit.py) rather than hand-rolling. Verified against the installed runtime,GraphBubbleUphas four subclasses:A hand-rolled
isinstance(exc, (GraphInterrupt, ParentCommand))missesGraphDrainedtoday — and would drift silently the next time the runtime widens the boundary, quietly resuming false-failure signing with nothing to notice. A moved private symbol at least fails loudly at import. The predicate delegates toGraphBubbleUpinstead of restating it, so it cannot drift. The only thing wrong with it was the underscore.What changes
is_control_flow_signalis public and in__all__._is_control_flow_signalstays as an alias. Hosts importing it pin>=0.2,<0.3; removing it inside that range would break their resolve. Drop it in 0.3.GraphBubbleUp's subclasses from the runtime's class tree rather than listing them — a list in the test would be the same brittle restatement the predicate exists to avoid.No behaviour change: same function, same callers, new name.
Reported from the bosun migration, 2026-07-17.