omnibase_infra 0.2.1__py3-none-any.whl → 0.2.2__py3-none-any.whl

omnibase_infra/services/service_capability_query.py

@@ -131,10 +131,10 @@ class ServiceCapabilityQuery(MixinAsyncCircuitBreaker):
         Dependency Injection Pattern: This service is a leaf infrastructure
         service that receives its dependencies directly via constructor
         parameters rather than resolving them from a container. Unlike
-        orchestrators that use ``container.resolve()`` to obtain services
-        dynamically, leaf services like this one are instantiated with
-        concrete dependencies (projection_reader, node_selector) and are
-        themselves resolved by higher-level components.
+        orchestrators that use ``container.service_registry.resolve_service()``
+        to obtain services dynamically, leaf services like this one are
+        instantiated with concrete dependencies (projection_reader, node_selector)
+        and are themselves resolved by higher-level components.
     """
 
     def __init__(

omnibase_infra/services/service_health.py

@@ -57,10 +57,11 @@ See Also:
 from __future__ import annotations
 
 import logging
-from typing import TYPE_CHECKING, Literal
+from typing import TYPE_CHECKING, Literal, cast
 
 from aiohttp import web
 
+from omnibase_core.types import JsonType
 from omnibase_infra.enums import EnumInfraTransportType
 from omnibase_infra.errors import (
     ModelInfraErrorContext,
@@ -859,7 +860,7 @@ class ServiceHealth:
             response = ModelHealthCheckResponse.success(
                 status=status,
                 version=self._version,
-                details=health_details,
+                details=cast("dict[str, JsonType]", health_details),
             )
 
             return web.Response(

omnibase_infra/services/service_timeout_emitter.py

@@ -36,6 +36,7 @@ from uuid import UUID
 
 from pydantic import BaseModel, ConfigDict, Field, field_validator
 
+from omnibase_core.models.events.model_event_envelope import ModelEventEnvelope
 from omnibase_infra.enums import EnumInfraTransportType
 from omnibase_infra.errors import ModelInfraErrorContext, ProtocolConfigurationError
 from omnibase_infra.models.projection import ModelRegistrationProjection
@@ -568,8 +569,13 @@ class ServiceTimeoutEmitter:
             },
         )
 
+        # Wrap event in ModelEventEnvelope for protocol compliance
+        envelope: ModelEventEnvelope[object] = ModelEventEnvelope(
+            payload=event,
+            correlation_id=correlation_id,
+        )
         await self._event_bus.publish_envelope(
-            envelope=event,
+            envelope=envelope,  # type: ignore[arg-type]
             topic=topic,
         )
 
@@ -657,8 +663,13 @@ class ServiceTimeoutEmitter:
             },
         )
 
+        # Wrap event in ModelEventEnvelope for protocol compliance
+        envelope: ModelEventEnvelope[object] = ModelEventEnvelope(
+            payload=event,
+            correlation_id=correlation_id,
+        )
         await self._event_bus.publish_envelope(
-            envelope=event,
+            envelope=envelope,  # type: ignore[arg-type]
             topic=topic,
         )
 

omnibase_infra/utils/util_dsn_validation.py

@@ -73,7 +73,7 @@ def _assert_postgres_scheme(scheme: str) -> Literal["postgresql", "postgres"]:
             parameter="scheme",
             value=scheme,
         )
-    return cast(Literal["postgresql", "postgres"], scheme)
+    return cast("Literal['postgresql', 'postgres']", scheme)
 
 
 def parse_and_validate_dsn(dsn: object) -> ModelParsedDSN:

omnibase_infra/validation/__init__.py

@@ -200,17 +200,8 @@ from omnibase_infra.validation.validator_runtime_shape import (
     enforce_execution_shape,
 )
 
-# Security validation for handler introspection and security constraints
-from omnibase_infra.validation.validator_security import (
-    SENSITIVE_METHOD_PATTERNS,
-    SENSITIVE_PARAMETER_NAMES,
-    SecurityRuleId,
-    convert_to_validation_error,
-    has_sensitive_parameters,
-    is_sensitive_method_name,
-    validate_handler_security,
-    validate_method_exposure,
-)
+# Security validation (OMN-1277) - contract-driven validator
+from omnibase_infra.validation.validator_security import ValidatorSecurity
 
 # Topic category validation for execution shape enforcement
 from omnibase_infra.validation.validator_topic_category import (
@@ -229,8 +220,6 @@ __all__: list[str] = [
     "EXECUTION_SHAPE_RULES",  # Runtime shape validation rules
     "INFRA_MAX_UNIONS",  # Infrastructure max union threshold
     "NODE_ARCHETYPE_EXPECTED_CATEGORIES",  # Node archetype categories
-    "SENSITIVE_METHOD_PATTERNS",  # Security validation patterns
-    "SENSITIVE_PARAMETER_NAMES",  # Security validation names
     "TOPIC_CATEGORY_PATTERNS",  # Topic category patterns
     "TOPIC_SUFFIXES",  # Topic suffix constants
     # Errors
@@ -239,7 +228,6 @@ __all__: list[str] = [
     "RoutingCoverageError",  # Routing coverage error (OMN-958)
     # Enums
     "EnumContractViolationSeverity",  # Contract violation severity
-    "SecurityRuleId",  # Security rule identifiers
     # Models
     "ModelAnyTypeValidationResult",  # Any type validation result (OMN-1276)
     "ModelContractLintResult",  # Contract lint result
@@ -261,9 +249,9 @@ __all__: list[str] = [
     "TopicCategoryASTVisitor",  # Topic category AST visitor
     "TopicCategoryValidator",  # Topic category validator
     "ValidationAggregator",  # Validation error aggregation (OMN-1091)
+    "ValidatorSecurity",  # Contract-driven security validator (OMN-1277)
     # Functions
     "check_routing_coverage_ci",  # CI routing coverage check
-    "convert_to_validation_error",  # Error conversion utility
     "detect_message_category",  # Message category detection
     "discover_message_types",  # Message type discovery
     "discover_registered_routes",  # Route discovery
@@ -271,9 +259,7 @@ __all__: list[str] = [
     "enforce_execution_shape",  # Execution shape enforcement
     "get_execution_shape_rules",  # Get shape rules
     "get_validation_summary",  # Get validation summary
-    "has_sensitive_parameters",  # Sensitive parameter check
     "is_isinstance_union",  # Check if union is in isinstance() call
-    "is_sensitive_method_name",  # Sensitive method check
     "lint_contract_file",  # Lint single contract file
     "lint_contracts_ci",  # CI contract linting
     "lint_contracts_in_directory",  # Directory contract linting
@@ -286,7 +272,6 @@ __all__: list[str] = [
     "validate_execution_shapes",  # Execution shape validation
     "validate_execution_shapes_ci",  # CI shape validation
     "validate_handler_registration",  # Handler registration validation (OMN-1098)
-    "validate_handler_security",  # Handler security validation
     "validate_infra_all",  # Infrastructure validation
     "validate_infra_architecture",  # Infrastructure architecture
     "validate_infra_circular_imports",  # Circular import check
@@ -298,7 +283,6 @@ __all__: list[str] = [
     "validate_localhandler_in_file",  # LocalHandler file validation (OMN-743)
     "validate_message_chain",  # Message chain validation
     "validate_message_on_topic",  # Topic message validation
-    "validate_method_exposure",  # Method exposure validation
     "validate_patterns",  # Re-export from omnibase_core
     "validate_routing_coverage_on_startup",  # Startup routing check
     "validate_topic_categories_in_directory",  # Directory topic validation

omnibase_infra/validation/contracts/security.validation.yaml

@@ -0,0 +1,114 @@
+contract_kind: validation_subcontract
+validation:
+  version:
+    major: 1
+    minor: 0
+    patch: 0
+  validator_id: security
+  validator_name: ONEX Security Validator
+  validator_description: |
+    Validates Python source files for security concerns in handler implementations.
+    Detects sensitive method names that should be private, credential exposure in
+    method signatures, and admin/internal operations exposed publicly.
+
+    This validator performs static AST analysis to identify:
+    - Public methods with sensitive names (get_password, get_secret, etc.)
+    - Method signatures containing sensitive parameter names
+    - Admin/internal methods exposed without underscore prefix
+    - Decrypt operations exposed publicly
+
+    Part of OMN-1277: Refactor validators to be Handler and contract-driven.
+  target_patterns:
+    - "**/*.py"
+  exclude_patterns:
+    - "**/node_modules/**"
+    - "**/.git/**"
+    - "**/venv/**"
+    - "**/.venv/**"
+    - "**/__pycache__/**"
+    - "**/archived/**"
+    - "**/tests/**"
+    - "**/*_test.py"
+    - "**/test_*.py"
+    - "**/conftest.py"
+  rules:
+    - rule_id: sensitive_method_exposed
+      description: |
+        Detects public methods with sensitive names that should be private.
+        Matches patterns: get_password, get_secret, get_token, get_api_key,
+        get_credential*, fetch_password, fetch_secret, fetch_token,
+        validate_password, check_password, verify_password.
+      severity: error
+      enabled: true
+      parameters:
+        patterns:
+          - "^get_password$"
+          - "^get_secret$"
+          - "^get_token$"
+          - "^get_api_key$"
+          - "^get_credential"
+          - "^fetch_password$"
+          - "^fetch_secret$"
+          - "^fetch_token$"
+          - "^validate_password$"
+          - "^check_password$"
+          - "^verify_password$"
+    - rule_id: credential_in_signature
+      description: |
+        Detects method signatures containing sensitive parameter names.
+        Matches parameters: password, secret, token, api_key, apikey,
+        access_key, private_key, credential, auth_token, bearer_token,
+        decrypt_key, encryption_key.
+      severity: error
+      enabled: true
+      parameters:
+        sensitive_params:
+          - "password"
+          - "secret"
+          - "token"
+          - "api_key"
+          - "apikey"
+          - "access_key"
+          - "private_key"
+          - "credential"
+          - "auth_token"
+          - "bearer_token"
+          - "decrypt_key"
+          - "encryption_key"
+    - rule_id: admin_method_public
+      description: |
+        Detects admin or internal methods exposed without underscore prefix.
+        Matches patterns: admin_*, internal_*.
+      severity: warning
+      enabled: true
+      parameters:
+        patterns:
+          - "^admin_"
+          - "^internal_"
+    - rule_id: decrypt_method_public
+      description: |
+        Detects decrypt operations exposed publicly.
+        Matches patterns: decrypt_*.
+      severity: warning
+      enabled: true
+      parameters:
+        patterns:
+          - "^decrypt_"
+  # ============================================================================
+  # LINE-BASED SUPPRESSION
+  # ============================================================================
+  # If ANY pattern below appears on a source line, ALL security violations
+  # on that line are suppressed.
+  #
+  # Usage example:
+  #   def get_password(self) -> str:  # ONEX_EXCLUDE: security - required for legacy API
+  #   def admin_reset(self) -> None:  # security-ok: admin endpoint with auth guard
+  # ============================================================================
+  suppression_comments:
+    - "# ONEX_EXCLUDE: security"
+    - "# security-ok:"
+  severity_default: error
+  fail_on_error: true
+  fail_on_warning: false
+  max_violations: 0
+  parallel_execution: true

omnibase_infra/validation/infra_validators.py

@@ -37,10 +37,12 @@ from typing import TypedDict
 import yaml
 
 from omnibase_core.models.common import ModelValidationMetadata
+from omnibase_core.models.primitives import ModelSemVer
 from omnibase_core.models.validation.model_union_pattern import ModelUnionPattern
 from omnibase_core.validation import (
     CircularImportValidator,
     ModelContractValidationResult,
+    ModelImportValidationResult,
     ModelModuleImportResult,
     ModelValidationResult,
     validate_architecture,
@@ -423,7 +425,11 @@ INFRA_NODES_PATH = "src/omnibase_infra/nodes/"
 #                    (+2 unions for EnumPolicyType | str in validate_policy_type_value)
 #                    (-1 union: fix PolicyTypeInput validator coercion, changed return
 #                    type from str | EnumPolicyType to EnumPolicyType)
-INFRA_MAX_UNIONS = 96
+# - 98 (2026-01-20): OMN-1277 security validator contract refactoring (+2 unions)
+#                    ast.FunctionDef | ast.AsyncFunctionDef for AST method type checking
+# - 105 (2026-01-21): Contract-driven handler config loading (+4 unions)
+#                     ModelHandlerContract transport config fields and lifecycle types
+INFRA_MAX_UNIONS = 105
 
 # Maximum allowed architecture violations in infrastructure code.
 # Set to 0 (strict enforcement) to ensure one-model-per-file principle is always followed.
@@ -747,13 +753,14 @@ def validate_infra_contract_deep(
         return result
 
     # If result is a different type, wrap it in ModelContractValidationResult
-    # Default to passed=False for unknown result types to avoid silently masking failures
-    # Check 'passed' first, then 'is_valid' as fallback (some validators use is_valid)
+    # Default to is_valid=False for unknown result types to avoid silently masking failures
+    # Check 'is_valid' first, then 'passed' as fallback (some validators use passed)
     return ModelContractValidationResult(
-        passed=getattr(result, "passed", getattr(result, "is_valid", False)),
+        is_valid=getattr(result, "is_valid", getattr(result, "passed", False)),
         score=getattr(result, "score", 0.0),
-        errors=getattr(result, "errors", []),
+        violations=getattr(result, "violations", getattr(result, "errors", [])),
         warnings=getattr(result, "warnings", []),
+        interface_version=ModelSemVer(major=1, minor=0, patch=0),
     )
 
 
@@ -1318,29 +1325,33 @@ def validate_infra_union_usage(
     # Note: ModelValidationMetadata uses extra="allow", so extension fields
     # are accepted as int values.
     # See docstring "Metadata Extension Fields" section for field documentation.
+    #
+    # Extension fields are passed via model_construct() to satisfy type checker
+    # while preserving runtime behavior with extra="allow".
+    metadata_fields: dict[str, object] = {
+        # Standard ModelValidationMetadata fields (formally defined)
+        "validation_type": "union_usage",
+        "files_processed": files_processed,
+        "violations_found": len(filtered_issues),
+        "total_unions": total_count,  # Base field: all unions found
+        "max_unions": max_unions,  # Base field: configured threshold
+        "strict_mode": strict,  # Base field: whether strict mode enabled
+        # Extension fields (via extra="allow", typed as int)
+        # These provide transparency into the exclusion logic:
+        "non_optional_unions": threshold_count,  # What threshold actually checks
+        "optional_unions_excluded": optional_count,  # X | None patterns
+        "isinstance_unions_excluded": isinstance_count,  # isinstance(x, A | B) patterns
+    }
     return ModelValidationResult(
         is_valid=is_valid,
         errors=filtered_issues,
-        metadata=ModelValidationMetadata(
-            # Standard ModelValidationMetadata fields (formally defined)
-            validation_type="union_usage",
-            files_processed=files_processed,
-            violations_found=len(filtered_issues),
-            total_unions=total_count,  # Base field: all unions found
-            max_unions=max_unions,  # Base field: configured threshold
-            strict_mode=strict,  # Base field: whether strict mode enabled
-            # Extension fields (via extra="allow", typed as int)
-            # These provide transparency into the exclusion logic:
-            non_optional_unions=threshold_count,  # What threshold actually checks
-            optional_unions_excluded=optional_count,  # X | None patterns
-            isinstance_unions_excluded=isinstance_count,  # isinstance(x, A | B) patterns
-        ),
+        metadata=ModelValidationMetadata.model_construct(**metadata_fields),  # type: ignore[arg-type]
     )
 
 
 def validate_infra_circular_imports(
     directory: PathInput = INFRA_SRC_PATH,
-) -> ModelModuleImportResult:
+) -> ModelImportValidationResult:
     """
     Check for circular imports in infrastructure code.
 
@@ -1351,7 +1362,7 @@ def validate_infra_circular_imports(
         directory: Directory to check. Defaults to infrastructure source.
 
     Returns:
-        ModelModuleImportResult with detailed import validation results.
+        ModelImportValidationResult with detailed import validation results.
         Use result.has_circular_imports to check for issues.
     """
     validator = CircularImportValidator(source_path=Path(directory))
@@ -1361,7 +1372,7 @@ def validate_infra_circular_imports(
 def validate_infra_all(
     directory: PathInput = INFRA_SRC_PATH,
     nodes_directory: PathInput = INFRA_NODES_PATH,
-) -> dict[str, ValidationResult | ModelModuleImportResult]:
+) -> dict[str, ValidationResult | ModelImportValidationResult]:
     """
     Run all validations on infrastructure code.
 
@@ -1379,7 +1390,7 @@ def validate_infra_all(
     Returns:
         Dictionary mapping validator name to result.
     """
-    results: dict[str, ValidationResult | ModelModuleImportResult] = {}
+    results: dict[str, ValidationResult | ModelImportValidationResult] = {}
 
     # HIGH priority validators
     results["architecture"] = validate_infra_architecture(directory)
@@ -1394,7 +1405,7 @@ def validate_infra_all(
 
 
 def get_validation_summary(
-    results: dict[str, ValidationResult | ModelModuleImportResult],
+    results: dict[str, ValidationResult | ModelImportValidationResult],
 ) -> dict[str, int | list[str]]:
     """
     Generate a summary of validation results.

omnibase_infra/validation/validation_exemptions.yaml

@@ -486,6 +486,47 @@ pattern_exemptions:
       - CLAUDE.md (Registry Naming Conventions)
     ticket: OMN-953
   # ==========================================================================
+  # TransitionNotificationPublisher publisher_id Exemption (OMN-1139)
+  # ==========================================================================
+  # publisher_id is a human-readable semantic identifier similar to scheduler_id.
+  # It identifies the publisher instance and may be auto-generated or user-specified.
+  - file_pattern: 'model_transition_notification_publisher_metrics\.py'
+    violation_pattern: "Field 'publisher_id' should use UUID"
+    reason: >
+      publisher_id is a human-readable semantic identifier (e.g., "transition-publisher-<uuid>") that identifies the publisher instance. Follows the same pattern as scheduler_id.
+
+    documentation:
+      - CLAUDE.md (Registry Naming Conventions)
+    ticket: OMN-1139
+  # ==========================================================================
+  # ModelTransitionNotificationOutboxMetrics table_name Exemption (OMN-1139)
+  # ==========================================================================
+  # table_name is the database table name string, not an entity reference.
+  - file_pattern: 'model_transition_notification_outbox_metrics\.py'
+    violation_pattern: "Field 'table_name' might reference an entity"
+    reason: >
+      table_name is the database table name string (e.g., "transition_notification_outbox"), not an entity reference. It identifies the outbox table for metrics reporting and does not require ID + display_name pattern.
+
+    documentation:
+      - CLAUDE.md (Registry Naming Conventions)
+    ticket: OMN-1139
+  # ==========================================================================
+  # TransitionNotificationOutbox Method Count Exemption (OMN-1139)
+  # ==========================================================================
+  # Outbox pattern requires lifecycle (start/stop), storage (store/cleanup),
+  # processing (process_pending), and multiple config properties for observability.
+  # NOTE: Pattern anchored with src/omnibase_infra/runtime/ prefix to match only
+  # the production file, not test files.
+  - file_pattern: 'src/omnibase_infra/runtime/transition_notification_outbox\.py'
+    class_pattern: "Class 'TransitionNotificationOutbox'"
+    violation_pattern: 'has \d+ methods'
+    reason: >
+      Transactional outbox pattern inherently requires: lifecycle methods (start/stop), storage operations (store/cleanup_processed), processing (process_pending), background loop (_processor_loop), metrics (get_metrics), and configuration properties (table_name, batch_size, poll_interval, is_running, shutdown_timeout, notifications_stored/processed/failed, strict_transaction_mode). Method count is driven by pattern requirements, not poor design.
+
+    documentation:
+      - src/omnibase_infra/schemas/schema_transition_notification_outbox.sql
+    ticket: OMN-1139
+  # ==========================================================================
   # ServiceTimeoutEmitter/Scanner Naming Exemptions (OMN-1055)
   # ==========================================================================
   # These service classes follow the CLAUDE.md Service<Name> naming convention.
@@ -1032,6 +1073,27 @@ pattern_exemptions:
       - CLAUDE.md (ONEX Architecture - Handler Types)
     ticket: OMN-1097
   # ==========================================================================
+  # Handler Bootstrap Source Exemptions (OMN-1087)
+  # ==========================================================================
+  # HandlerBootstrapSource provides hardcoded handler descriptors for core
+  # infrastructure handlers. The "Handler" in the name refers to ONEX handler
+  # concepts, consistent with HandlerContractSource and HandlerPluginLoader.
+  #
+  # Pattern specificity note: Uses separate class_pattern + violation_pattern
+  # (not combined "Class name .* contains...") for precise targeting. All three
+  # patterns must match: exact filename, exact class name, and violation type.
+  # This is consistent with HandlerContractSource/HandlerPluginLoader exemptions.
+  - file_pattern: 'handler_bootstrap_source\.py'
+    class_pattern: "Class name 'HandlerBootstrapSource'"
+    violation_pattern: "contains anti-pattern 'Handler'"
+    reason: >
+      HandlerBootstrapSource centralizes hardcoded handler registration for core infrastructure handlers (Consul, DB, HTTP, Vault). The "Handler" refers to ONEX handler concepts, consistent with HandlerContractSource. This is legitimate handler infrastructure code per OMN-1087.
+
+    documentation:
+      - docs/architecture/HANDLER_PROTOCOL_DRIVEN_ARCHITECTURE.md
+      - CLAUDE.md (ONEX Architecture - Handler Types)
+    ticket: OMN-1087
+  # ==========================================================================
   # Handler Plugin Loader Exemptions (OMN-1132)
   # ==========================================================================
   # HandlerPluginLoader discovers and loads ONEX handlers from contract YAML files.
@@ -1456,16 +1518,17 @@ pattern_exemptions:
   # ProjectorShell Exemptions (OMN-1169)
   # ==========================================================================
   # ProjectorShell implements ProtocolEventProjector protocol which requires:
-  # - Protocol properties (projector_id, aggregate_type, consumed_events, is_placeholder)
-  # - Core methods (project, get_state)
-  # - SQL execution modes (_upsert, _insert, _append, _execute_projection)
-  # - Value extraction (_extract_values, _resolve_path, _get_event_type)
-  # - Utility (_parse_row_count)
-  # Total: 11 methods, all cohesive to the projector contract pattern.
-  # NOTE: Pattern anchored with omnibase_infra/runtime/ prefix and $ suffix to
-  # match only the production file at src/omnibase_infra/runtime/projector_shell.py.
+  # - Protocol properties (projector_id, aggregate_type, consumed_events, contract, is_placeholder)
+  # - Core methods (project, get_state, get_states, partial_update, upsert_partial)
+  # - SQL execution modes handled by MixinProjectorSqlOperations
+  # - Value extraction (_extract_values, _resolve_path, _get_event_type, _execute_projection)
+  # - Notification integration (via MixinProjectorNotificationPublishing)
+  # Total: 11 methods, all cohesive to the contract-driven projector pattern.
+  # OMN-1139: Added notification publishing support via mixin composition.
+  # NOTE: Pattern anchored with src/omnibase_infra/runtime/ prefix to match only
+  # the production file at src/omnibase_infra/runtime/projector_shell.py.
   # This prevents matching test files in tests/unit/runtime/ or tests/integration/runtime/.
-  - file_pattern: 'omnibase_infra/runtime/projector_shell\.py$'
+  - file_pattern: 'src/omnibase_infra/runtime/projector_shell\.py'
     class_pattern: "Class 'ProjectorShell'"
     violation_pattern: 'has \d+ methods'
     reason: >
@@ -1631,6 +1694,47 @@ pattern_exemptions:
     documentation:
       - docs/patterns/binding_config_resolver.md
     ticket: OMN-765
+  # ==========================================================================
+  # HandlerMCP Method Count Exemption (OMN-1282)
+  # ==========================================================================
+  # MCP handler is a complex infrastructure component requiring many methods:
+  # - 4 ProtocolHandler methods (initialize, shutdown, execute, health_check)
+  # - 2 factory methods for route handlers (_create_health_endpoint, _create_tools_list_endpoint)
+  # - 2 server lifecycle methods (_start_http_server, _stop_http_server)
+  # - 3 execution/operation methods (_run_server, _execute_tool_operation, _execute_describe)
+  # Complexity is inherent to MCP protocol requirements and uvicorn server management.
+  - file_pattern: 'handler_mcp\.py'
+    class_pattern: "Class 'HandlerMCP'"
+    violation_pattern: 'has \d+ methods'
+    reason: >
+      HandlerMCP is a complex infrastructure handler implementing MCP protocol with internal uvicorn server lifecycle. The 11 methods are cohesive: 4 ProtocolHandler interface methods, 2 factory methods for Starlette route handlers (explicit closure capture), 2 server lifecycle methods (start/stop), and 3 operation methods. Splitting would fragment the unified MCP server abstraction.
+
+    documentation:
+      - CLAUDE.md (Handler Plugin Loader Patterns)
+    ticket: OMN-1282
+  # ==========================================================================
+  # Registry API Models - service_name Exemptions (OMN-1278)
+  # ==========================================================================
+  # service_name in registry API models is the Consul service name for discovery,
+  # NOT an entity reference. It's an external Consul identifier.
+  - file_pattern: 'services/registry_api/models/model_registry_node_view\.py'
+    violation_pattern: "Field 'service_name' might reference an entity"
+    reason: >
+      service_name is the Consul service name for service discovery (e.g., "onex-effect-abc123"). This is an external Consul identifier, NOT an ONEX entity reference. The node_id field provides the UUID identifier; service_name is how the node appears in Consul's catalog.
+
+    documentation:
+      - CLAUDE.md (Type Annotation Conventions)
+      - Consul service discovery documentation
+    ticket: OMN-1278
+  - file_pattern: 'services/registry_api/models/model_registry_instance_view\.py'
+    violation_pattern: "Field 'service_name' might reference an entity"
+    reason: >
+      service_name is the Consul service name for live instance discovery (e.g., "my-service"). This is an external Consul identifier, NOT an ONEX entity reference. The node_id and service_id fields provide UUID identifiers; service_name is the Consul catalog name.
+
+    documentation:
+      - CLAUDE.md (Type Annotation Conventions)
+      - Consul service discovery documentation
+    ticket: OMN-1278
 # Architecture validator exemptions
 # These handle one-model-per-file violations for domain-grouped protocols
 architecture_exemptions:

omnibase_infra/validation/validator_chain_propagation.py

@@ -183,7 +183,7 @@ def get_message_id(envelope: ModelEventEnvelope[object]) -> UUID:
     """
     # envelope_id is typed as UUID in ModelEventEnvelope, but mypy sees it as Any
     # due to the generic type parameter. Cast is required for type safety.
-    return cast(UUID, envelope.envelope_id)
+    return cast("UUID", envelope.envelope_id)
 
 
 def get_correlation_id(envelope: ModelEventEnvelope[object]) -> UUID | None:
@@ -200,7 +200,7 @@ def get_correlation_id(envelope: ModelEventEnvelope[object]) -> UUID | None:
     correlation_id = envelope.correlation_id
     if correlation_id is None:
         return None
-    return cast(UUID, correlation_id)
+    return cast("UUID", correlation_id)
 
 
 def get_causation_id(envelope: ModelEventEnvelope[object]) -> UUID | None:

omnibase_infra/validation/validator_runtime_shape.py

@@ -893,7 +893,7 @@ def enforce_execution_shape(node_archetype: EnumNodeArchetype) -> Callable[[F],
 
         # Cast wrapper to F - functools.wraps preserves the signature at runtime,
         # and mypy cannot prove the equivalence, so we use an explicit cast.
-        return cast(F, wrapper)
+        return cast("F", wrapper)
 
     return decorator