feat(libsy): add routing outcome metadata

crates/libsy/src/core.rs

@@ -10,5 +10,6 @@ pub(crate) mod testing;
 
 pub mod algorithm;
 pub mod classifier;
+pub mod decision;
 pub mod processor;
 pub mod state;

crates/libsy/src/core/algorithm.rs

@@ -68,6 +68,8 @@ pub struct RoutingOutcome {
     pub request: Request,
     /// A response produced while routing, or `None` when the client must make the answer call.
     pub response: Option<Response>,
+    /// Optional algorithm-owned explanation of the routing decision.
+    pub decision: Option<crate::DecisionMetadata>,
 }
 
 impl RoutingOutcome {
@@ -93,6 +95,7 @@ impl RoutingOutcome {
             selected_model_ids,
             request,
             response: None,
+            decision: None,
         }
     }
 
@@ -104,6 +107,7 @@ impl RoutingOutcome {
             selected_model_ids: vec![selected_model_id],
             request,
             response: Some(response),
+            decision: None,
         }
     }
 }
@@ -483,6 +487,7 @@ mod tests {
         );
         assert_eq!(outcome.request.model_id().as_deref(), Some("selected"));
         assert!(outcome.response.is_none());
+        assert!(outcome.decision.is_none());
 
         let outcome = RoutingOutcome::route_to("only".into(), Vec::new(), request());
         assert_eq!(outcome.selected_model_ids, target_set(&["only"]));

crates/libsy/src/core/decision.rs

@@ -0,0 +1,13 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+//! Optional metadata explaining a routing decision.
+
+/// Algorithm-owned metadata attached to a successful routing outcome.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct DecisionMetadata {
+    /// Stable name of the algorithm that made the decision.
+    pub algorithm: String,
+    /// Optional bounded, machine-readable evidence produced by the algorithm.
+    pub evidence: Option<String>,
+}

crates/libsy/src/lib.rs

@@ -7,6 +7,7 @@
 mod core;
 pub use core::algorithm::{Algorithm, CallModel, Driver, RoutingOutcome, Step, StepStream, drive};
 pub use core::classifier::{Classification, Classifier, Score};
+pub use core::decision::DecisionMetadata;
 pub use core::processor::{Event, Processor};
 pub use core::state::{State, StateValue};
 

crates/switchyard-py/src/libsy_bindings.rs

@@ -675,6 +675,7 @@ fn step_to_python(step: RustStep) -> PyResult<PyStep> {
                 selected_model_ids,
                 request,
                 response,
+                decision: _,
             } = *outcome;
             Python::attach(|py| {
                 Ok(PyStep::Done {