Merge pull request #570 from Brad-Edwards/201-participant-feature-support

added: expose participant feature support declarations

Author: Brad-Edwards

changelog.d/201.added.md

@@ -0,0 +1 @@
+Expose API-407 participant feature-support declarations through backend manifest capability helpers and preserve them in rendered backend-manifest v2 payloads.

implementations/python/packages/aces_backend_protocols/capabilities.py

@@ -11,7 +11,7 @@
 )
 from aces_contracts.controlled_vocabularies import validate_controlled_vocabulary_scope_values
 from aces_contracts.manifest_authority import validate_backend_supported_contract_versions
-from aces_contracts.vocabulary import WorkflowFeature, WorkflowStatePredicateFeature
+from aces_contracts.vocabulary import ParticipantFeatureSupportLevel, WorkflowFeature, WorkflowStatePredicateFeature
 
 PARTICIPANT_RUNTIME_ROLE_SCOPE = "capabilities.participant_runtime.supported_participant_roles"
 PARTICIPANT_RUNTIME_BEHAVIOR_FEATURE_SCOPE = "capabilities.participant_runtime.supported_behavior_features"
@@ -195,6 +195,66 @@ def __post_init__(self) -> None:
             raise ValueError("EvaluatorCapabilities must support scoring, objectives, or both")
 
 
+def _validate_unique_non_empty_strings(field_name: str, values: tuple[str, ...]) -> None:
+    if any(not value.strip() for value in values):
+        raise ValueError(f"{field_name} must not contain empty strings")
+    if len(set(values)) != len(values):
+        raise ValueError(f"{field_name} must not contain duplicate values")
+
+
+def _validate_participant_feature_support_term(feature: str) -> None:
+    errors: list[str] = []
+    for scope in (PARTICIPANT_RUNTIME_BEHAVIOR_FEATURE_SCOPE, PARTICIPANT_RUNTIME_INTERACTION_FEATURE_SCOPE):
+        try:
+            validate_controlled_vocabulary_scope_values(scope, (feature,))
+        except ValueError as exc:
+            errors.append(str(exc))
+            continue
+        return
+    raise ValueError(
+        "ParticipantFeatureSupport.feature must be a governed participant behavior or interaction feature "
+        f"term, or match the governed extension pattern; got {feature!r}; "
+        f"validation details: {'; '.join(errors)}"
+    )
+
+
+@dataclass(frozen=True)
+class ParticipantFeatureSupport:
+    """API-407 per-feature participant runtime support declaration."""
+
+    feature: str
+    support_level: ParticipantFeatureSupportLevel | str
+    constraint_refs: tuple[str, ...] = ()
+    disclosure_refs: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        if not self.feature.strip():
+            raise ValueError("ParticipantFeatureSupport.feature must be non-empty")
+        _validate_participant_feature_support_term(self.feature)
+
+        try:
+            support_level = (
+                self.support_level
+                if isinstance(self.support_level, ParticipantFeatureSupportLevel)
+                else ParticipantFeatureSupportLevel(str(self.support_level))
+            )
+        except ValueError as exc:
+            raise ValueError("ParticipantFeatureSupport.support_level must be a valid support level") from exc
+
+        constraint_refs = tuple(self.constraint_refs)
+        disclosure_refs = tuple(self.disclosure_refs)
+        _validate_unique_non_empty_strings("ParticipantFeatureSupport.constraint_refs", constraint_refs)
+        _validate_unique_non_empty_strings("ParticipantFeatureSupport.disclosure_refs", disclosure_refs)
+        if support_level != ParticipantFeatureSupportLevel.EXACT and not disclosure_refs:
+            raise ValueError(
+                "ParticipantFeatureSupport disclosure_refs must be non-empty when support_level is below exact"
+            )
+
+        object.__setattr__(self, "support_level", support_level)
+        object.__setattr__(self, "constraint_refs", constraint_refs)
+        object.__setattr__(self, "disclosure_refs", disclosure_refs)
+
+
 @dataclass(frozen=True)
 class ParticipantRuntimeCapabilities:
     """Participant-episode lifecycle support declaration.
@@ -217,6 +277,7 @@ class ParticipantRuntimeCapabilities:
     supported_participant_roles: frozenset[str] = frozenset()
     supported_behavior_features: frozenset[str] = frozenset()
     supported_interaction_features: frozenset[str] = frozenset()
+    feature_support: tuple[ParticipantFeatureSupport, ...] = ()
     constraints: dict[str, str] = field(default_factory=dict)
 
     def __post_init__(self) -> None:
@@ -252,6 +313,22 @@ def __post_init__(self) -> None:
             PARTICIPANT_RUNTIME_INTERACTION_FEATURE_SCOPE,
             self.supported_interaction_features,
         )
+        feature_support = tuple(
+            entry if isinstance(entry, ParticipantFeatureSupport) else ParticipantFeatureSupport(**entry)
+            for entry in self.feature_support
+        )
+        feature_names = tuple(entry.feature for entry in feature_support)
+        _validate_unique_non_empty_strings("ParticipantRuntimeCapabilities.feature_support", feature_names)
+        supported_features = self.supported_behavior_features | self.supported_interaction_features
+        for entry in feature_support:
+            if (
+                entry.support_level == ParticipantFeatureSupportLevel.UNSUPPORTED
+                and entry.feature in supported_features
+            ):
+                raise ValueError(
+                    "ParticipantRuntimeCapabilities.feature_support cannot declare a supported feature unsupported"
+                )
+        object.__setattr__(self, "feature_support", feature_support)
 
 
 @dataclass(frozen=True)

implementations/python/packages/aces_backend_protocols/manifest.py

@@ -9,6 +9,7 @@
     BackendCompatibilityModel,
     BackendManifestV2Model,
     ConceptBindingEntryModel,
+    ParticipantFeatureSupportModel,
     RealizationSupportDeclarationModel,
 )
 from aces_contracts.manifest_authority import BACKEND_SUPPORTED_CONTRACT_IDS
@@ -97,6 +98,15 @@ def backend_manifest_v2_model(manifest: BackendManifest) -> BackendManifestV2Mod
                     "supported_interaction_features": sorted(
                         manifest.participant_runtime.supported_interaction_features
                     ),
+                    "feature_support": [
+                        ParticipantFeatureSupportModel(
+                            feature=entry.feature,
+                            support_level=entry.support_level,
+                            constraint_refs=list(entry.constraint_refs),
+                            disclosure_refs=list(entry.disclosure_refs),
+                        )
+                        for entry in manifest.participant_runtime.feature_support
+                    ],
                     "constraints": dict(manifest.participant_runtime.constraints),
                 }
                 if manifest.participant_runtime is not None

implementations/python/tests/test_backend_manifest.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import json
+from dataclasses import replace
 from pathlib import Path
 
 import pytest
@@ -13,6 +14,7 @@
     PARTICIPANT_RUNTIME_ROLE_SCOPE,
     BackendManifest,
     OrchestratorCapabilities,
+    ParticipantFeatureSupport,
     ParticipantRuntimeCapabilities,
     ProvisionerCapabilities,
     participant_runtime_capability_contract_gaps,
@@ -125,6 +127,7 @@ def test_backend_manifest_v2_declares_participant_capability_dimensions():
         "interference",
         "shared_state_change",
     ]
+    assert participant_runtime["feature_support"] == []
 
     model = BackendManifestV2Model.model_validate(payload)
     assert model.capabilities.participant_runtime is not None
@@ -189,6 +192,89 @@ def test_participant_runtime_capabilities_validate_api_405_vocabularies():
         )
 
 
+def test_participant_feature_support_validates_api_407_declarations():
+    declaration = ParticipantFeatureSupport(
+        feature="coordination",
+        support_level=ParticipantFeatureSupportLevel.EXACT,
+    )
+
+    assert declaration.support_level == ParticipantFeatureSupportLevel.EXACT
+
+    with pytest.raises(ValueError, match="governed participant behavior or interaction feature"):
+        ParticipantFeatureSupport(
+            feature="custom_feature",
+            support_level=ParticipantFeatureSupportLevel.EXACT,
+        )
+
+    with pytest.raises(ValueError, match="disclosure_refs"):
+        ParticipantFeatureSupport(
+            feature="coordination",
+            support_level=ParticipantFeatureSupportLevel.BOUNDED,
+        )
+
+    unsupported_declaration = ParticipantFeatureSupport(
+        feature="coordination",
+        support_level=ParticipantFeatureSupportLevel.UNSUPPORTED,
+        disclosure_refs=("disclosures.coordination.unsupported.v1",),
+    )
+    with pytest.raises(ValueError, match="supported feature unsupported"):
+        ParticipantRuntimeCapabilities(
+            name="participant-runtime",
+            supported_participant_roles=frozenset({"blue"}),
+            supported_behavior_features=frozenset({"action_contracts"}),
+            supported_interaction_features=frozenset({"coordination"}),
+            feature_support=(unsupported_declaration,),
+        )
+
+
+def test_backend_manifest_payload_renders_api_407_feature_support_entries():
+    manifest = create_stub_manifest()
+    assert manifest.participant_runtime is not None
+    participant_runtime = replace(
+        manifest.participant_runtime,
+        feature_support=(
+            ParticipantFeatureSupport(
+                feature="behavior_history",
+                support_level=ParticipantFeatureSupportLevel.BOUNDED,
+                constraint_refs=("constraints.behavior-history.retention-window",),
+                disclosure_refs=("disclosures.behavior-history.bounded.v1",),
+            ),
+            ParticipantFeatureSupport(
+                feature="coordination",
+                support_level=ParticipantFeatureSupportLevel.EXACT,
+            ),
+        ),
+    )
+    capabilities = replace(manifest.capabilities, participant_runtime=participant_runtime)
+    manifest = BackendManifest(
+        identity=manifest.identity,
+        supported_contract_versions=manifest.supported_contract_versions,
+        compatibility=manifest.compatibility,
+        realization_support=manifest.realization_support,
+        concept_bindings=manifest.concept_bindings,
+        constraints=manifest.constraints,
+        capabilities=capabilities,
+    )
+
+    payload = backend_manifest_payload(manifest)
+
+    assert payload["capabilities"]["participant_runtime"]["feature_support"] == [
+        {
+            "feature": "behavior_history",
+            "support_level": "bounded",
+            "constraint_refs": ["constraints.behavior-history.retention-window"],
+            "disclosure_refs": ["disclosures.behavior-history.bounded.v1"],
+        },
+        {
+            "feature": "coordination",
+            "support_level": "exact",
+            "constraint_refs": [],
+            "disclosure_refs": [],
+        },
+    ]
+    BackendManifestV2Model.model_validate(payload)
+
+
 def test_participant_runtime_capability_evidence_covers_standard_vocabularies():
     catalog_path = FIXTURES_ROOT / "concept-authority" / "controlled-vocabularies-v1" / "valid" / "reference.json"
     catalog = json.loads(catalog_path.read_text(encoding="utf-8"))