Reject feedforward outputs at earlier layers

Add validation for feedforward graphs so all inferred terminal output nodes
must be located at the final layer depth. This prevents artifacts from listing
earlier sink nodes that EdgeModel.forward() would not return, keeping inferred
outputs consistent with the model output tensor.

Add regression coverage for feedforward DAGs with terminal nodes at multiple
depths.

Author: Thomas-Rauter

README.md

@@ -129,7 +129,7 @@ feature_attributions = e2t.interpret_model(
     artifact=artifact,
     data=data,
     target="features",
-    method="integrated_gradients",
+    method="IntegratedGradients",
 )
 ```
 

src/edge2torch/compile/execution_plan.py

@@ -141,6 +141,27 @@ def build_feedforward_execution_plan(
         node for node in graph.nodes if len(children[node]) == 0
     )
 
+    output_node_depths = {
+        node: node_to_depth[node] for node in output_node_names
+    }
+
+    if output_node_depths:
+        final_output_depth = max(output_node_depths.values())
+        early_output_nodes = sorted(
+            node
+            for node, node_depth in output_node_depths.items()
+            if node_depth != final_output_depth
+        )
+
+        if early_output_nodes:
+            early_output_str = ", ".join(early_output_nodes)
+            raise Edge2TorchError(
+                "Feedforward compilation requires all terminal output nodes "
+                "to be at the same layer depth. Output node(s) at earlier "
+                "depth than the final output layer are not supported: "
+                f"{early_output_str}."
+            )
+
     has_initial_weight = "initial_weight" in original_edges.columns
     has_constraint = "constraint" in original_edges.columns
 

src/edge2torch/graph/validate.py

@@ -248,26 +248,54 @@ def _validate_feedforward_graph(
         return
 
     visited_nodes: set[str] = set()
+    node_to_depth: dict[str, int] = {}
+    depth = 0
 
     while current_layer_nodes:
         next_layer_candidates: set[str] = set()
 
         for node in current_layer_nodes:
             visited_nodes.add(node)
+            node_to_depth[node] = depth
 
             for child in children[node]:
                 in_degree[child] -= 1
 
                 if in_degree[child] == 0:
                     next_layer_candidates.add(child)
 
+        depth += 1
         current_layer_nodes = sorted(next_layer_candidates)
 
     if len(visited_nodes) != len(node_names):
         report.errors.append(
             "Feedforward compilation requires an acyclic, layerable graph. "
             "The graph contains at least one cycle or unresolved dependency."
         )
+        return
+
+    output_node_depths = {
+        node: node_to_depth[node]
+        for node in node_names
+        if len(children[node]) == 0
+    }
+
+    if output_node_depths:
+        final_output_depth = max(output_node_depths.values())
+        early_output_nodes = sorted(
+            node
+            for node, node_depth in output_node_depths.items()
+            if node_depth != final_output_depth
+        )
+
+        if early_output_nodes:
+            early_output_str = ", ".join(early_output_nodes)
+            report.errors.append(
+                "Feedforward compilation requires all terminal output nodes "
+                "to be at the same layer depth. Output node(s) at earlier "
+                "depth than the final output layer are not supported: "
+                f"{early_output_str}."
+            )
 
 
 def _validate_recurrent_graph(

tests/api/compile_graph/test_api_compile_graph.py

@@ -9,6 +9,25 @@
 from edge2torch.utils.errors import Edge2TorchError
 
 
+def test_compile_graph_rejects_feedforward_terminal_outputs_at_multi_depths():
+    edgelist = pd.DataFrame(
+        {
+            "source": ["input", "input", "hidden"],
+            "target": ["early_output", "hidden", "late_output"],
+        }
+    )
+
+    with pytest.raises(
+        Edge2TorchError,
+        match="terminal output nodes.*same layer depth",
+    ):
+        compile_graph(
+            edgelist=edgelist,
+            backend="feedforward",
+            quiet=True,
+        )
+
+
 def test_compile_graph_returns_model_and_artifact_for_valid_feedforward_graph():
     edgelist = pd.DataFrame(
         {

tests/module/compile/test_execution_plan_internal.py

@@ -23,6 +23,22 @@ def __init__(self, edges, nodes=None):
 # build_feedforward_execution_plan --------------------------------------------
 
 
+def test_build_feedforward_execution_plan_rejects_terminal_out_multi_depths():
+    graph = _Graph(
+        [
+            ("input", "early_output"),
+            ("input", "hidden"),
+            ("hidden", "late_output"),
+        ]
+    )
+
+    with pytest.raises(
+        Edge2TorchError,
+        match="terminal output nodes.*same layer depth",
+    ):
+        build_feedforward_execution_plan(graph)
+
+
 def test_build_feedforward_execution_plan_rejects_no_input_nodes():
     graph = _Graph(
         [

tests/module/graph/test_validate_internal.py

@@ -122,6 +122,25 @@ def test_validate_common_graph_structure_errors_for_duplicate_edges():
     assert report.notes == ["Graph contains 2 node(s) and 2 edge(s)."]
 
 
+def test_validate_feedforward_graph_rejects_terminal_outputs_at_multi_depths():
+    graph = _Graph(
+        [
+            ("input", "early_output"),
+            ("input", "hidden"),
+            ("hidden", "late_output"),
+        ]
+    )
+    report = ValidationReport()
+
+    _validate_feedforward_graph(graph=graph, report=report)
+
+    assert any(
+        "all terminal output nodes to be at the same layer depth" in error
+        and "early_output" in error
+        for error in report.errors
+    )
+
+
 def test_validate_feedforward_graph_accepts_layerable_graph():
     graph = _Graph(
         [