return value cleanup + raise on empty

src/wf_authoring/builder/refs.py

@@ -10,19 +10,43 @@ from ..nodes import NodeSpec
 StepRef: TypeAlias = (
     str | NodeUse | ConditionNode | ForeachNode | InterruptNode | JoinNode
 )
+"""A reference to a step, which can be either a string id or a node object
+ that should be auto-used."""
 BranchRef: TypeAlias = StepRef | NodeSpec[Any, Any]
+"""A reference to a branch source or target, which can be either a step ref
+ or a NodeSpec that should be auto-used."""
 
 
 @dataclass(frozen=True, slots=True)
-class RouteRef:
-    """Reference bundle returned by control-flow helpers with generated conditions."""
+class BranchResult:
+    """Resolved branch source plus outcome-indexed targets."""
+
+    source: StepRef
+    targets: dict[str, StepRef]
+
+    def __getitem__(self, outcome: str) -> StepRef:
+        """Keep branch outcome lookup ergonomic while exposing the source."""
+        return self.targets[outcome]
+
+
+@dataclass(frozen=True, slots=True)
+class HandleResult:
+    """Resolved shared target plus source/outcome pairs that feed it."""
+
+    target: StepRef
+    branches: tuple[tuple[StepRef, str], ...]
+
+
+@dataclass(frozen=True, slots=True)
+class DecisionResult:
+    """Generated condition entry plus resolved targets for one decision helper."""
 
     entry: ConditionNode
     conditions: tuple[ConditionNode, ...]
     targets: dict[object, StepRef]
 
     def __getitem__(self, key: object) -> StepRef:
-        """Keep helper result lookup ergonomic while exposing generated conditions."""
+        """Keep decision result lookup ergonomic while exposing conditions."""
         return self.targets[key]