fix(manifests): validate surface binding contracts

Signed-off-by: Pouyanpi <13303554+Pouyanpi@users.noreply.github.com>

Author: Pouyanpi

nemoguardrails/manifests/manifest.py

@@ -26,7 +26,7 @@
 from enum import Enum
 from typing import Any, Literal, Optional, Tuple, Union
 
-from pydantic import BaseModel, ConfigDict, Field, field_validator
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
 
 from nemoguardrails.actions.rail_outcome import TransformTarget
 
@@ -174,6 +174,14 @@ class Binding(BaseModel):
 
     model_config = ConfigDict(extra="forbid", frozen=True)
 
+    @model_validator(mode="after")
+    def _source_must_match_kind(self) -> "Binding":
+        if self.kind == "literal" and self.key is not None:
+            raise ValueError("Literal bindings cannot declare a source key.")
+        if self.kind != "literal" and self.key is None:
+            raise ValueError(f"{self.kind} bindings must declare a source key.")
+        return self
+
     @classmethod
     def surface_param(cls, action_param: str, name: str, *, required: bool = True) -> "Binding":
         """Bind `action_param` to a caller-supplied surface parameter.
@@ -227,6 +235,18 @@ class RailSurface(BaseModel):
 
     model_config = ConfigDict(extra="forbid", frozen=True)
 
+    @model_validator(mode="after")
+    def _validate_execution_contract(self) -> "RailSurface":
+        seen = set()
+        duplicates = set()
+        for binding in self.bindings:
+            if binding.action_param in seen:
+                duplicates.add(binding.action_param)
+            seen.add(binding.action_param)
+        if duplicates:
+            raise ValueError(f"Rail surfaces cannot bind action parameters more than once: {sorted(duplicates)}.")
+        return self
+
 
 class EnvVar(BaseModel):
     """Environment variable declared by a rail requirement."""

tests/manifests/test_manifest.py

@@ -18,6 +18,7 @@
 
 from nemoguardrails.manifests import (
     ActionRef,
+    Binding,
     ConfigSpecRef,
     RailActions,
     RailConfigSchema,
@@ -121,3 +122,26 @@ def test_flat_manifest_is_rejected():
 
     with pytest.raises(ValidationError):
         RailManifest.model_validate(flat_manifest)
+
+
+@pytest.mark.parametrize(
+    "factory",
+    (
+        lambda: Binding(kind="context", action_param="text"),
+        lambda: Binding(kind="surface_param", action_param="model"),
+        lambda: Binding(kind="literal", action_param="mode", key="source", value="strict"),
+    ),
+)
+def test_binding_source_matches_binding_kind(factory):
+    with pytest.raises(ValidationError, match="source key"):
+        factory()
+
+
+def test_surface_rejects_duplicate_action_parameter_bindings():
+    with pytest.raises(ValidationError, match="more than once"):
+        RailSurface(
+            name="duplicate bindings",
+            direction="input",
+            action=_action(),
+            bindings=(Binding.context("text", "user_message"), Binding.literal("text", "value")),
+        )