refactor: split oversized files and cut complexity to clear SonarCloud gate

changelog.d/+sonar-modularity-refactor.changed.md

@@ -0,0 +1 @@
+Internal refactor to clear the SonarCloud `new_violations` quality gate on the `dev → main` integration PR: split four oversized source files into focused modules — `aces_contracts/participant_behavior.py` (enums/tables → `_participant_behavior_types.py`), `aces_sdl/validator/_runtime_platform.py` (orchestration-authority checks → `_runtime_orchestration.py`), `aces_sdl/validator/_relationships.py` (proxy-upstream checks → `_relationships_proxy.py`), and `aces_sdl/runtime_datastore_partitions.py` (node child models → `runtime_datastore_nodes.py`, shared helpers → `_runtime_datastore_support.py`) — and reduced the cognitive complexity of `ParticipantHistoryViewModel._validate_nested_record_scope` plus a returns-count refactor in `runtime_values.name_indicates_secret`. No behavior change; all public APIs are preserved by re-export.

implementations/python/packages/aces_contracts/_participant_behavior_types.py

@@ -0,0 +1,166 @@
+"""Participant behavior runtime enums and derived constant tables.
+
+Split out of ``participant_behavior.py`` (file-size governance). The public
+enums are re-exported from ``participant_behavior``; importers should continue
+to use ``aces_contracts.participant_behavior``.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class ParticipantBehaviorHistoryEventType(str, Enum):
+    """Portable history event kinds for participant behavior semantics."""
+
+    ACTION_ATTEMPTED = "action_attempted"
+    STATE_TRANSITION_RECORDED = "state_transition_recorded"
+    OBSERVATION_EMITTED = "observation_emitted"
+
+
+class ParticipantObservationStatus(str, Enum):
+    """Terminal interpretation of a participant observation event."""
+
+    TERMINAL = "terminal"
+    ORPHANED_ACTION = "orphaned_action"
+
+
+class ParticipantActionPreconditionStatus(str, Enum):
+    """Runtime resolution state for one SEM-211 action precondition."""
+
+    SATISFIED = "satisfied"
+    UNSATISFIED = "unsatisfied"
+    UNRESOLVED = "unresolved"
+
+
+class ParticipantActionResultStatus(str, Enum):
+    """Portable local status for a SEM-211 participant action attempt."""
+
+    ACCEPTED = "accepted"
+    REJECTED = "rejected"
+    WITHHELD = "withheld"
+    SUCCEEDED = "succeeded"
+    FAILED = "failed"
+    PARTIAL_SUCCESS = "partial_success"
+    UNKNOWN = "unknown"
+
+
+class ParticipantRuntimeLifecyclePhase(str, Enum):
+    """RUN-306 observable participant runtime lifecycle phases."""
+
+    INTENT_OR_PROPOSAL = "intent_or_proposal"
+    SELECTION_OR_ADMISSION = "selection_or_admission"
+    EXECUTION_ATTEMPT = "execution_attempt"
+    OBSERVATION_EMISSION = "observation_emission"
+    STATE_UPDATE_COMMIT = "state_update_commit"
+
+
+class ParticipantPhaseRealization(str, Enum):
+    """RUN-306 realization modes for an observable lifecycle phase."""
+
+    OBSERVED = "observed"
+    RUNTIME_MEDIATED = "runtime_mediated"
+    EXTERNALLY_SUPPLIED = "externally_supplied"
+    OPAQUE = "opaque"
+    UNKNOWN = "unknown"
+    NOT_APPLICABLE = "not_applicable"
+    UNSUPPORTED = "unsupported"
+
+
+class ParticipantAdmissionDisposition(str, Enum):
+    """RUN-306 selection/admission disposition values."""
+
+    ADMITTED = "admitted"
+    REJECTED = "rejected"
+    WITHHELD = "withheld"
+    UNKNOWN = "unknown"
+    NOT_APPLICABLE = "not_applicable"
+
+
+class ParticipantLifecycleOperationState(str, Enum):
+    """RUN-306 operation states for execution-attempt records."""
+
+    SUBMITTED = "submitted"
+    ACKNOWLEDGED = "acknowledged"
+    RUNNING = "running"
+    BLOCKED = "blocked"
+    COMPLETED = "completed"
+    PARTIAL = "partial"
+    FAILED = "failed"
+    TIMED_OUT = "timed_out"
+    CANCELLED = "cancelled"
+    UNKNOWN = "unknown"
+    UNSUPPORTED = "unsupported"
+
+
+_PARTICIPANT_BEHAVIOR_HISTORY_KEY = "runtime.snapshot.participant-behavior-history"
+_PARTICIPANT_RUNTIME_METADATA_KEY = "runtime.snapshot.metadata"
+_RESERVED_RUNTIME_STATE_KEYS = frozenset(
+    {
+        "participant_episode_results",
+        "participant_episode_history",
+        "participant_behavior_history",
+    }
+)
+_REQUIRED_BEHAVIOR_EVENT_FIELDS = (
+    "event_type",
+    "timestamp",
+    "participant_address",
+    "episode_id",
+    "action_instance_id",
+)
+_OPTIONAL_NON_EMPTY_STRING_FIELDS = (
+    "action_contract_address",
+    "observation_boundary_address",
+    "actor_provenance",
+    "state_transition_kind",
+    "post_state_digest",
+    "joint_action_set_id",
+    "interaction_ref",
+    "operation_ref",
+)
+
+
+def _enum_values(enum_type: type[Enum]) -> frozenset[str]:
+    return frozenset(str(item.value) for item in enum_type.__members__.values())
+
+
+_PARTICIPANT_BEHAVIOR_EVENT_TYPE_VALUES = _enum_values(ParticipantBehaviorHistoryEventType)
+_PARTICIPANT_OBSERVATION_STATUS_VALUES = _enum_values(ParticipantObservationStatus)
+_PARTICIPANT_RUNTIME_LIFECYCLE_PHASE_VALUES = _enum_values(ParticipantRuntimeLifecyclePhase)
+_PARTICIPANT_PHASE_REALIZATION_VALUES = _enum_values(ParticipantPhaseRealization)
+_PARTICIPANT_ADMISSION_DISPOSITION_VALUES = _enum_values(ParticipantAdmissionDisposition)
+_PARTICIPANT_LIFECYCLE_OPERATION_STATE_VALUES = _enum_values(ParticipantLifecycleOperationState)
+_ACTION_ATTEMPTED_LIFECYCLE_PHASE_VALUES = frozenset(
+    {
+        ParticipantRuntimeLifecyclePhase.INTENT_OR_PROPOSAL.value,
+        ParticipantRuntimeLifecyclePhase.SELECTION_OR_ADMISSION.value,
+        ParticipantRuntimeLifecyclePhase.EXECUTION_ATTEMPT.value,
+    }
+)
+_LIFECYCLE_ENUM_FIELDS = (
+    ("lifecycle_phase", _PARTICIPANT_RUNTIME_LIFECYCLE_PHASE_VALUES),
+    ("phase_realization", _PARTICIPANT_PHASE_REALIZATION_VALUES),
+    ("admission_disposition", _PARTICIPANT_ADMISSION_DISPOSITION_VALUES),
+    ("operation_state", _PARTICIPANT_LIFECYCLE_OPERATION_STATE_VALUES),
+)
+_LIFECYCLE_PHASE_BY_EVENT_TYPE = {
+    ParticipantBehaviorHistoryEventType.ACTION_ATTEMPTED.value: _ACTION_ATTEMPTED_LIFECYCLE_PHASE_VALUES,
+    ParticipantBehaviorHistoryEventType.STATE_TRANSITION_RECORDED.value: frozenset(
+        {ParticipantRuntimeLifecyclePhase.STATE_UPDATE_COMMIT.value}
+    ),
+    ParticipantBehaviorHistoryEventType.OBSERVATION_EMITTED.value: frozenset(
+        {ParticipantRuntimeLifecyclePhase.OBSERVATION_EMISSION.value}
+    ),
+}
+_LIFECYCLE_PHASE_BY_EVENT_TYPE_MESSAGES = {
+    ParticipantBehaviorHistoryEventType.ACTION_ATTEMPTED.value: (
+        "action_attempted lifecycle_phase must be one of intent_or_proposal, selection_or_admission, execution_attempt"
+    ),
+    ParticipantBehaviorHistoryEventType.STATE_TRANSITION_RECORDED.value: (
+        "state_transition_recorded lifecycle_phase must be state_update_commit"
+    ),
+    ParticipantBehaviorHistoryEventType.OBSERVATION_EMITTED.value: (
+        "observation_emitted lifecycle_phase must be observation_emission"
+    ),
+}

implementations/python/packages/aces_contracts/contracts.py

@@ -1236,6 +1236,46 @@ def _validate_episode_scope(self) -> ParticipantStatusViewModel:
         return self
 
 
+def _check_history_record_scope_binding(
+    key: str,
+    value: object,
+    path: str,
+    *,
+    participant_address: str,
+    episode_id: str,
+) -> None:
+    """Raise if a nested record scope key conflicts with the history view scope."""
+    if not isinstance(value, str):
+        return
+    if key == "participant_address" and value != participant_address:
+        raise ValueError(f"{path}.{key} '{value}' does not match the view participant_address '{participant_address}'")
+    if key == "episode_id" and value != episode_id:
+        raise ValueError(f"{path}.{key} '{value}' does not match the view episode_id '{episode_id}'")
+
+
+def _walk_history_record_scope(
+    node: object,
+    path: str,
+    *,
+    participant_address: str,
+    episode_id: str,
+) -> None:
+    """Recursively bind nested recorded-contract scope to the history view scope."""
+    if isinstance(node, dict):
+        for key, value in node.items():
+            _check_history_record_scope_binding(
+                key, value, path, participant_address=participant_address, episode_id=episode_id
+            )
+            _walk_history_record_scope(
+                value, f"{path}.{key}", participant_address=participant_address, episode_id=episode_id
+            )
+    elif isinstance(node, list):
+        for index, item in enumerate(node):
+            _walk_history_record_scope(
+                item, f"{path}[{index}]", participant_address=participant_address, episode_id=episode_id
+            )
+
+
 class ParticipantHistoryViewModel(ContractModel):
     """API-408 retrieval projection of participant episode/behavior history."""
 
@@ -1270,29 +1310,17 @@ def _validate_nested_record_scope(self) -> ParticipantHistoryViewModel:
         through those subrecords.
         """
 
-        def _walk(node: object, path: str) -> None:
-            if isinstance(node, dict):
-                for key, value in node.items():
-                    if key == "participant_address" and isinstance(value, str) and value != self.participant_address:
-                        raise ValueError(
-                            f"{path}.{key} '{value}' does not match the view "
-                            f"participant_address '{self.participant_address}'"
-                        )
-                    if key == "episode_id" and isinstance(value, str) and value != self.episode_id:
-                        raise ValueError(
-                            f"{path}.{key} '{value}' does not match the view episode_id '{self.episode_id}'"
-                        )
-                    _walk(value, f"{path}.{key}")
-            elif isinstance(node, list):
-                for index, item in enumerate(node):
-                    _walk(item, f"{path}[{index}]")
-
         for field_name, events in (
             ("episode_history", self.episode_history),
             ("behavior_history", self.behavior_history),
         ):
             for index, event in enumerate(events):
-                _walk(event.model_dump(mode="python"), f"{field_name}[{index}]")
+                _walk_history_record_scope(
+                    event.model_dump(mode="python"),
+                    f"{field_name}[{index}]",
+                    participant_address=self.participant_address,
+                    episode_id=self.episode_id,
+                )
         return self
 
     @classmethod